koala73/worldmonitor · error · Error

llms.txt must contain exactly one OpenAPI YAML byte-size ann

Error message

llms.txt must contain exactly one OpenAPI YAML byte-size annotation

What it means

withOpenApiByteSize rewrites the single byte-size annotation for the OpenAPI YAML link in llms.txt. It requires exactly one match of the '[OpenAPI specification](https://www.worldmonitor.app/openapi.yaml), which is N bytes' pattern; zero or multiple matches throw, because updating the size would otherwise be ambiguous or impossible.

Solutions

1. Open public/llms.txt and restore exactly one sentence matching '[OpenAPI specification](https://www.worldmonitor.app/openapi.yaml), which is <digits> bytes'.
2. Remove any duplicate copies of the annotation.
3. Prefer regenerating the file (npm run build:llms-full) rather than editing by hand, then rerun build-openapi-json.

Example fix

// before (llms.txt)
[OpenAPI specification](https://www.worldmonitor.app/openapi.yaml) - see the file.
// after
[OpenAPI specification](https://www.worldmonitor.app/openapi.yaml), which is 12,345 bytes.

const re = /\[OpenAPI specification\]\(https:\/\/www\.worldmonitor\.app\/openapi\.yaml\), which is [\d,]+ bytes/g;
if ([...llmsTxt.matchAll(re)].length !== 1) throw new Error('exactly one OpenAPI byte-size annotation required');

try { txt = withOpenApiByteSize(txt, yamlBytes); } catch (e) { console.error('Fix llms.txt annotation:', e.message); process.exit(1); }

When it happens

Trigger: Running build-openapi-json when public/llms.txt is missing the byte-size annotation entirely, has a malformed size (not digits/commas, e.g. 'about N bytes'), or contains the annotation twice.

Common situations: Manual editing of llms.txt removed or reworded the annotation sentence; a merge duplicated the paragraph; annotation format drifted from the regex after copy changes.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• needs a summary for the llms.txt Comparisons section
• ${LLMS_TXT_PATH} carries ${headings.length} "${COMPARISONS_H
• ${LLMS_TXT_PATH} must carry a "${COMPARISONS_ANCHOR_HEADING}
• is missing methodology prose
• is missing following prose

AI-assisted analysis of koala73/worldmonitor@7d06c8633d (2026-09-15). Data as JSON: /api/errors/f60e2b19c4b3b202. Report an issue: GitHub.

Appendix: source

Thrown at scripts/build-openapi-json.mjs:74

  dedupeSharedChinaProvenanceSchemas,
  dedupeSharedResponseHeaders,
  dedupeSharedSchemaSubtrees,
} from './openapi-dedup-schemas.mjs';
import { dropUnreachableSchemas } from './openapi-drop-unreachable-schemas.mjs';

const scriptDir = dirname(fileURLToPath(import.meta.url));
// OPENAPI_YAML_PATH exists so the capacity report's "could not measure" exit can
// be exercised as a real process against a real missing/invalid source, instead
// of being asserted from a hand-built report object that never runs the CLI.
export const yamlPath = process.env.OPENAPI_YAML_PATH
  ?? resolve(scriptDir, '../docs/api/worldmonitor.openapi.yaml');
export const jsonPath = resolve(scriptDir, '../public/openapi.json');
const llmsPath = resolve(scriptDir, '../public/llms.txt');

export function withOpenApiByteSize(text, yamlBytes) {
  const annotation = /(\[OpenAPI specification\]\(https:\/\/www\.worldmonitor\.app\/openapi\.yaml\), which is )[\d,]+ bytes/g;
  if ([...text.matchAll(annotation)].length !== 1) {
    throw new Error('llms.txt must contain exactly one OpenAPI YAML byte-size annotation');
  }
  return text.replace(annotation, (_, prefix) => `${prefix}${yamlBytes.toLocaleString('en-US')} bytes`);
}

export const DEPRECATION_POLICY_URL = 'https://www.worldmonitor.app/api-versioning.md';
const DEPRECATION_POLICY_HTML_URL = 'https://www.worldmonitor.app/docs/api-versioning';

function injectDeprecationPolicyMetadata(spec) {
  spec.components ??= {};
  spec.components.headers ??= {};
  spec.components.headers.Deprecation ??= {
    description:
      'RFC 9745. Present only when this operation or version is deprecated; omitted while the surface is current. Value is the deprecation instant as an HTTP Structured Field date (for example `@1782864000`).',
    schema: { type: 'string', examples: ['@1782864000'] },
  };
  spec.components.headers.Sunset ??= {
    description:
      'RFC 8594. Present only when this operation or version is deprecated. Final availability date in HTTP-date format (for example `Thu, 31 Dec 2026 23:59:59 GMT`).',

View on GitHub (pinned to 7d06c8633d)