@bongos/core 1.21.175 → 1.21.177

package/scripts/gds/gen-api-docs.js

@@ -1,1102 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/gen-api-docs.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/gen-api-docs.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-// gen-api-docs.js — generate a standards-compliant OpenAPI 3.1 spec + a human/AI
-// Markdown reference DIRECTLY FROM the live route files (task 1918, BONGOS-V1).
-//
-// WHY: the GDS API had no machine-readable contract — the only endpoint doc was a
-// hand-maintained mirror (docs/routes-permissions.md) that drifted from the code.
-// An AI agent hitting the API had nothing standard to read. This generator emits
-// OpenAPI 3.1 — the format every tool (Postman, Swagger, Redoc, LLM tool-callers)
-// already understands — from the SAME route-introspection engine the ship-time
-// rank gate uses (src/bongos/route-rank-check.js). So the docs enumerate EXACTLY the
-// routes the server mounts and cannot silently drift.
-//
-// DESIGN (mirrors gen-repo-map.js / ADR 0063):
-//   - Deterministic: no timestamps, stable sort — so `--check` is a clean CI gate.
-//   - Zero runtime deps: a line+regex extractor over the route source, plus a
-//     built-in structural OpenAPI validator (no @redocly/cli in the critical path;
-//     run `npm run docs:api:lint` for the full standard lint on demand).
-//   - Two-root aware (ADR 0108): route discovery + doc writes route through
-//     resolveCoreRoot(); never hardcode path.resolve(__dirname,'..','..').
-//
-// Writes (all deterministic):
-//   docs/api/openapi.json      — OpenAPI 3.1, the machine-readable contract
-//   docs/api-reference.md       — grouped Markdown reference (for humans + AI)
-//   docs/routes-permissions.md  — generated pointer stub (the retired hand-mirror)
-//
-// Usage:
-//   node scripts/gds/gen-api-docs.js            # regenerate the three files
-//   node scripts/gds/gen-api-docs.js --check     # write nothing; exit 2 on drift (+ structural-validate)
-//   node scripts/gds/gen-api-docs.js --json      # print the extracted model as JSON (debug)
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const { resolveCoreRoot, resolveDocsRoot } = require('../../src/instance-config');
-const rrc = require('../../src/bongos/route-rank-check');
-// Destructured, not reached through `rrc.` — knip tracks a destructured CJS require but
-// not namespace member access, so `rrc.canonicalRoutePath(...)` read as an unused export
-// and tripped the dead-code ratchet (knip_issue_count 224 > baseline 223) even though the
-// call site below is real. The named import is how a new helper on this module gets
-// counted as used (task 1003747).
-const { canonicalRoutePath } = require('../../src/bongos/route-rank-check');
-const { API_PREFIX, API_VERSION, VERSIONED_API_PREFIX } = require('../../src/bongos/api-prefix');
-// Task 2050 (ADR 0118): the enriched extractor resolves named constants used in
-// validate() rules. Both requires are pure (no side effects / no DB / no express):
-// _helpers exports the LIMITS caps; api-errors is the kernel error registry whose
-// category taxonomy the spec advertises (ADR 0116). Keep them pure — the generator
-// must never execute a route file or open a connection.
-const { LIMITS } = require('../../src/bongos/routes/_helpers');
-const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
-const apiErrors = require('../../src/bongos/api-errors');
-
-const CORE_ROOT = resolveCoreRoot();
-// Routes are READ from the core (CORE_ROOT, via route-rank-check); the generated
-// spec + reference are WRITTEN to the DOCS root — the instance repo when a consumer
-// points at it (`bongos upgrade`), the same coreRoot in a single checkout (ADR 0108,
-// task 2051). So `bongos upgrade` refreshes the CONSUMER's docs, not node_modules.
-const DOCS_ROOT = resolveDocsRoot();
-const OPENAPI_PATH = path.join(DOCS_ROOT, 'docs', 'api', 'openapi.json');
-const REFERENCE_PATH = path.join(DOCS_ROOT, 'docs', 'api-reference.md');
-const PERMISSIONS_PATH = path.join(DOCS_ROOT, 'docs', 'routes-permissions.md');
-
-// Spec version tracks the core package version — deterministic (no build clock).
-function specVersion() {
-  try {
-    return require(path.join(CORE_ROOT, 'package.json')).version || '0.0.0';
-  } catch {
-    return '0.0.0';
-  }
-}
-
-// Human-facing product name for the spec title, from the branding pack. Best-effort:
-// a branding hiccup must not break doc generation (falls back to a neutral name).
-function productName() {
-  try {
-    const { branding } = require('../../src/branding');
-    const b = branding();
-    return (b.identity && (b.identity.productName || b.identity.worldName)) || 'Cloud Bongos';
-  } catch {
-    return 'Cloud Bongos';
-  }
-}
-
-const METHOD_ORDER = ['get', 'post', 'put', 'patch', 'delete'];
-
-const RANK_BLURB = {
-  public: 'No authentication — any caller.',
-  'any-builder': 'Any authenticated builder (row-level ownership enforced in-handler).',
-  'metic+archon': 'Metic or Archon rank (review/triage powers).',
-  archon: 'Archon only (rank and identity management + the escalation keys — the trust boundary).',
-  'bfg-principal': 'The BFG cross-builder memory service principal (not a human rank).',
-  unknown: 'Gate could not be classified from source — treat as privileged.',
-};
-
-// ---------------------------------------------------------------------------
-// Extraction (per route file)
-// ---------------------------------------------------------------------------
-
-// The contiguous `//` comment block immediately above line i, `//` stripped and
-// joined. A leading "rank: <val> — " token is dropped so the prose that remains is
-// the human rationale (the rank itself is captured structurally). Blank lines and
-// code end the block.
-// Route-comment descriptions carry bare "#NNN" GDS task refs (e.g. "V3.R91 / #401").
-// Emitted verbatim they mis-render as GitHub *issue* links in the committed
-// docs/api-reference.md AND trip the doc-ref-linkify CI gate — while gen-api-docs
-// --check demands the committed file match this generator's output, so the two
-// checks would fight over the generated file forever. Neutralize the refs at their
-// single origin to plain "task NNN" (brand-neutral, deterministic, and what
-// linkify-refs treats as clean — it never rewrites a hostname). Only a #-prefixed
-// run of digits is touched; "V3.R91", anchors like "#/task", and "# heading" are left
-// alone. (task 1918 follow-up; surfaced landing task 1915.)
-function neutralizeTaskRefs(text) {
-  return String(text || '').replace(/#(\d{1,6})\b/g, 'task $1');
-}
-
-function commentBlockAbove(lines, i) {
-  const buf = [];
-  for (let j = i - 1; j >= 0; j--) {
-    const line = lines[j];
-    if (/^\s*\/\//.test(line)) {
-      buf.unshift(line.replace(/^\s*\/\/\s?/, ''));
-      continue;
-    }
-    break; // blank or code — stop
-  }
-  let text = buf.join(' ').replace(/\s+/g, ' ').trim();
-  text = text.replace(/^rank:\s*[a-z+-]+\s*(?:—|-|:)?\s*/i, '').trim();
-  return neutralizeTaskRefs(text);
-}
-
-// An Express inline param constraint — `:id(\d+)` (task 1003747). It is a ROUTING
-// detail, never part of the URL a caller types, so it is stripped everywhere a
-// route string reaches a reader or the spec. Without this, `/inbox/:id(\d+)`
-// generated the path template `/inbox/{id}(\\d+)` (malformed — it would break the
-// generated client), renamed the operationId `get_inbox_id` → `get_inbox_id_d`
-// (a silent breaking change for every client consumer), and printed the regex in
-// the public API reference.
-// The canonicaliser itself lives in route-rank-check, next to scanDeclarations — the
-// scanner this generator already shares with the auditor — so there is ONE definition
-// rather than a copy per consumer. Declarations therefore arrive canonical already;
-// this wrapper stays because pathParams/routeForDisplay are pure exported helpers that
-// callers (and tests/api_docs.mjs) hand raw strings to directly.
-function routeForDisplay(route) {
-  return canonicalRoutePath(String(route || ''));
-}
-
-// :param → {param}; also return the ordered param name list. Inline constraints
-// are dropped first so the template stays a valid OpenAPI path.
-function pathParams(route) {
-  const names = [];
-  const openapiPath = routeForDisplay(route).replace(/:([A-Za-z0-9_]+)/g, (_, n) => {
-    names.push(n);
-    return `{${n}}`;
-  });
-  return { openapiPath, names };
-}
-
-// Strip // line comments and /* */ block comments, honoring string literals — so
-// a schema literal's inline comments (`parallel_safe: {}, // note`) don't derail
-// the brace/key scan below.
-function stripComments(str) {
-  let out = '';
-  let quote = null;
-  for (let k = 0; k < str.length; k++) {
-    const c = str[k];
-    const n = str[k + 1];
-    if (quote) {
-      out += c;
-      if (c === '\\') { out += n == null ? '' : n; k++; continue; }
-      if (c === quote) quote = null;
-      continue;
-    }
-    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; continue; }
-    if (c === '/' && n === '/') { while (k < str.length && str[k] !== '\n') k++; out += '\n'; continue; }
-    if (c === '/' && n === '*') { k += 2; while (k < str.length && !(str[k] === '*' && str[k + 1] === '/')) k++; k++; continue; }
-    out += c;
-  }
-  return out;
-}
-
-// Capture the balanced {...} literal starting at the first '{' at or after `from`.
-// Returns the substring (incl. braces) or null. String/char literals are skipped
-// so a brace inside a quoted default doesn't unbalance the scan.
-function captureBalanced(str, from) {
-  const open = str.indexOf('{', from);
-  if (open === -1) return null;
-  let depth = 0;
-  let quote = null;
-  for (let k = open; k < str.length; k++) {
-    const c = str[k];
-    if (quote) {
-      if (c === '\\') { k++; continue; }
-      if (c === quote) quote = null;
-      continue;
-    }
-    if (c === '"' || c === "'" || c === '`') { quote = c; continue; }
-    if (c === '{') depth++;
-    else if (c === '}') { depth--; if (depth === 0) return str.slice(open, k + 1); }
-  }
-  return null;
-}
-
-// Top-level `identifier:` keys of an object-literal string (depth-1 only).
-// Strips comments first so it is robust regardless of caller (idempotent on
-// already-stripped input).
-function topLevelKeys(objLiteral) {
-  const inner = stripComments(objLiteral).slice(1, -1);
-  const keys = [];
-  let depth = 0;
-  let quote = null;
-  let atFieldStart = true;
-  let ident = '';
-  for (let k = 0; k < inner.length; k++) {
-    const c = inner[k];
-    if (quote) {
-      if (c === '\\') { k++; continue; }
-      if (c === quote) quote = null;
-      continue;
-    }
-    if (c === '"' || c === "'" || c === '`') { quote = c; ident = ''; atFieldStart = false; continue; }
-    if (c === '{' || c === '[' || c === '(') { depth++; atFieldStart = false; ident = ''; continue; }
-    if (c === '}' || c === ']' || c === ')') { depth--; continue; }
-    if (depth === 0) {
-      if (c === ',') { atFieldStart = true; ident = ''; continue; }
-      if (c === ':' && ident) { keys.push(ident); ident = ''; atFieldStart = false; continue; }
-      if (atFieldStart && /[A-Za-z0-9_$]/.test(c)) { ident += c; continue; }
-      if (!/\s/.test(c)) { ident = ''; atFieldStart = false; }
-    }
-  }
-  return keys;
-}
-
-// ---------------------------------------------------------------------------
-// Rule-set extraction (task 2050 / ADR 0118 §1 "enrich the generator")
-// ---------------------------------------------------------------------------
-//
-// The per-route validate() schema object is already structured data (_helpers.js):
-// each field's rule carries type/required/enum/min/max/minLength/maxLength/
-// itemsType/maxItems. We parse that rule set (not just field names) so the spec can
-// emit typed request schemas + named components.schemas. Values are resolved
-// STATICALLY — the generator NEVER executes a route file (the stripComments/
-// captureBalanced philosophy). Literals resolve directly; a named constant
-// (LIMITS.TITLE, a file-local `const CAP = 64`) resolves via a per-file constants
-// map; an unresolvable expression (e.g. a computed bound) is simply omitted from
-// that ONE annotation — the field's type still emits, so a schema degrades
-// gracefully and never emits a wrong constraint.
-
-const KNOWN_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'array', 'object']);
-const RULE_NUM_KEYS = ['maxLength', 'minLength', 'min', 'max', 'maxItems'];
-// Only digits, numeric separators, and arithmetic operators — no identifiers. A
-// string matching this is safe to evaluate (it cannot reference anything).
-const NUMERIC_ARITH_RE = /^[-+*/()\s\d._]+$/;
-
-// Split an object/array INNER (braces/brackets already stripped) on depth-0 commas,
-// honoring string literals and nesting. Returns the raw segments (untrimmed).
-function splitTopLevel(inner) {
-  const parts = [];
-  let depth = 0;
-  let quote = null;
-  let start = 0;
-  for (let k = 0; k < inner.length; k++) {
-    const c = inner[k];
-    if (quote) {
-      if (c === '\\') { k++; continue; }
-      if (c === quote) quote = null;
-      continue;
-    }
-    if (c === '"' || c === "'" || c === '`') { quote = c; continue; }
-    if (c === '{' || c === '[' || c === '(') depth++;
-    else if (c === '}' || c === ']' || c === ')') depth--;
-    else if (c === ',' && depth === 0) { parts.push(inner.slice(start, k)); start = k + 1; }
-  }
-  if (inner.slice(start).trim() !== '') parts.push(inner.slice(start));
-  return parts;
-}
-
-// Split "key: value" on the FIRST depth-0 colon. Returns { key, value } (both
-// trimmed; key unquoted) or null for a shorthand / non-key-value segment.
-function splitKeyValue(segment) {
-  let depth = 0;
-  let quote = null;
-  for (let k = 0; k < segment.length; k++) {
-    const c = segment[k];
-    if (quote) {
-      if (c === '\\') { k++; continue; }
-      if (c === quote) quote = null;
-      continue;
-    }
-    if (c === '"' || c === "'" || c === '`') { quote = c; continue; }
-    if (c === '{' || c === '[' || c === '(') depth++;
-    else if (c === '}' || c === ']' || c === ')') depth--;
-    else if (c === ':' && depth === 0) {
-      const key = segment.slice(0, k).trim().replace(/^['"`]|['"`]$/g, '');
-      return { key, value: segment.slice(k + 1).trim() };
-    }
-  }
-  return null;
-}
-
-// Top-level `key: value` entries of an object literal (depth-1), value kept as its
-// raw source substring. Comments are stripped first (idempotent).
-function topLevelEntries(objLiteral) {
-  const inner = stripComments(String(objLiteral)).trim().replace(/^\{/, '').replace(/\}$/, '');
-  const entries = [];
-  for (const seg of splitTopLevel(inner)) {
-    const kv = splitKeyValue(seg);
-    if (kv && /^[A-Za-z_$][\w$]*$/.test(kv.key)) entries.push(kv);
-  }
-  return entries;
-}
-
-// Walk a dotted path (LIMITS.TITLE, TASK_FIELD_BOUNDS.priority.min) against the
-// constants map. Returns the primitive/array value or undefined.
-function resolveConst(pathExpr, constants) {
-  let cur = constants;
-  for (const p of pathExpr.split('.')) {
-    if (cur == null || typeof cur !== 'object' || !(p in cur)) return undefined;
-    cur = cur[p];
-  }
-  return (cur !== null && (typeof cur !== 'object' || Array.isArray(cur))) ? cur : undefined;
-}
-
-// Resolve a scalar rule value: boolean/number/string literal, pure numeric
-// arithmetic (30 * 1024 * 1024, 2_000_000), or a named constant. Undefined if
-// unresolvable (a computed/dynamic expression).
-function resolveScalar(expr, constants = {}) {
-  const s = String(expr).trim();
-  if (s === 'true') return true;
-  if (s === 'false') return false;
-  const str = /^(['"`])([\s\S]*)\1$/.exec(s);
-  if (str) return str[2];
-  if (NUMERIC_ARITH_RE.test(s) && /\d/.test(s)) {
-    try {
-      // Safe: charset-restricted to digits/separators/operators/parens — no identifiers.
-      const v = Function('"use strict"; return (' + s.replace(/_/g, '') + ');')();
-      if (typeof v === 'number' && Number.isFinite(v)) return v;
-    } catch { /* not a number after all */ }
-    return undefined;
-  }
-  if (/^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/.test(s)) return resolveConst(s, constants);
-  return undefined;
-}
-
-// Resolve an array rule value (enum): a literal array of literals, or a named
-// constant that resolves to such an array. All-or-nothing — if any element is
-// unresolvable the enum is dropped (never emit a partial/wrong enum).
-function resolveArray(expr, constants = {}) {
-  const s = String(expr).trim();
-  if (s.startsWith('[') && s.endsWith(']')) {
-    const out = [];
-    for (const seg of splitTopLevel(s.slice(1, -1))) {
-      if (seg.trim() === '') continue;
-      const v = resolveScalar(seg, constants);
-      if (v === undefined) return undefined;
-      out.push(v);
-    }
-    return out;
-  }
-  const c = resolveConst(s, constants);
-  return Array.isArray(c) ? c : undefined;
-}
-
-// Parse one field's rule object → the recognized, resolved constraint keys.
-function parseRule(ruleLiteral, constants = {}) {
-  const rule = {};
-  if (!/^\s*\{/.test(String(ruleLiteral))) return rule; // `field: SOMETHING` non-object → unconstrained
-  for (const { key, value } of topLevelEntries(ruleLiteral)) {
-    if (key === 'required') {
-      if (resolveScalar(value, constants) === true) rule.required = true;
-    } else if (key === 'type' || key === 'itemsType') {
-      const v = resolveScalar(value, constants);
-      if (typeof v === 'string' && KNOWN_TYPES.has(v)) rule[key] = v;
-    } else if (key === 'enum') {
-      const v = resolveArray(value, constants);
-      if (Array.isArray(v) && v.length) rule.enum = v;
-    } else if (RULE_NUM_KEYS.includes(key)) {
-      const v = resolveScalar(value, constants);
-      if (typeof v === 'number' && Number.isFinite(v)) rule[key] = v;
-    }
-  }
-  return rule;
-}
-
-// Per-file constants map: top-level single-line `const NAME = <literal>` decls
-// (numbers, arithmetic, strings, arrays of literals). Catches the file-local caps
-// + enum arrays (CLAIM_OUTCOMES, INBOX_STATUS_VALUES, SECURITY_DOC_CONTENT_MAX,
-// PUBLISH_BUNDLE_B64_MAX). Merged over the global constants (LIMITS).
-function scanFileConstants(source) {
-  const out = {};
-  const re = /^\s*const\s+([A-Za-z_$][\w$]*)\s*=\s*([^;\n]+);?\s*$/gm;
-  let m;
-  while ((m = re.exec(source))) {
-    const name = m[1];
-    const rhs = m[2].trim();
-    const v = rhs.startsWith('[') ? resolveArray(rhs, out) : resolveScalar(rhs, out);
-    if (v !== undefined) out[name] = v;
-  }
-  return out;
-}
-
-// Global constants available to every route file: the LIMITS caps (the dominant
-// referenced constant). TASK_FIELD_BOUNDS is imported (not file-local) so its
-// bounds are omitted — the affected fields still emit their integer type.
-function globalConstants() {
-  return { LIMITS: LIMITS || {} };
-}
-
-// The source line where THIS route's handler ends — the next router.<verb>(
-// declaration, or +200 lines, whichever comes first. Bounds the window both the
-// request- and response-shape extractors scan so they never bleed into the next
-// handler.
-function routeEndLine(lines, i) {
-  for (let j = i + 1; j < lines.length && j < i + 200; j++) {
-    if (/^\s*router\.(get|post|patch|put|delete)\s*\(/.test(lines[j])) return j;
-    if (j === i + 199) return j;
-  }
-  return lines.length;
-}
-
-// Request-body shape for a write route: does it read req.body, is it validated, and
-// (best-effort) the top-level field names from its validateOrRespond/validate schema.
-function extractBody(lines, i, method, constants = {}) {
-  if (!['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) return null;
-  // Window: from this route to the next route declaration (or +200 lines).
-  const end = routeEndLine(lines, i);
-  const window = stripComments(lines.slice(i, end).join('\n'));
-  const readsBody = /\breq\.body\b/.test(window);
-  const orRespond = /validateOrRespond\s*\(\s*req\s*,\s*res\s*,/.exec(window);
-  const lowLevel = /\bvalidate\s*\(\s*req\.body/.exec(window);
-  const validateCall = orRespond || lowLevel;
-  const fields = [];
-  const rules = {};
-  // validateOrRespond REJECTS unknown fields by default (R11/#1998); the low-level
-  // validate() defaults lenient. `strict` drives additionalProperties in the spec.
-  let strict = false;
-  if (validateCall) {
-    const after = validateCall.index + validateCall[0].length;
-    let lit = captureBalanced(window, after);
-    // captureBalanced seeks the NEXT '{' anywhere — when the third argument is
-    // an identifier, that grabs some unrelated later block. Only trust the
-    // capture when the brace directly follows the call.
-    if (lit && !/^\s*\{/.test(window.slice(after))) lit = null;
-    if (!lit) {
-      // Schema hoisted to a module-scope const (the boot-loud enum-spread
-      // pattern, task 1003057): resolve `validateOrRespond(req, res, IDENT)`
-      // against `const IDENT = [Object.freeze(] { … }` anywhere in the file,
-      // so hoisting a schema never silently drops a route from the API docs.
-      const ident = /^\s*([A-Za-z_$][\w$]*)\s*[,)]/.exec(window.slice(after));
-      if (ident) {
-        const whole = stripComments(lines.join('\n'));
-        const decl = new RegExp(`const\\s+${ident[1]}\\s*=\\s*(?:Object\\.freeze\\s*\\(\\s*)?`).exec(whole);
-        if (decl) lit = captureBalanced(whole, decl.index + decl[0].length);
-      }
-    }
-    if (lit) {
-      for (const { key, value } of topLevelEntries(lit)) {
-        if (/^\d/.test(key)) continue; // defensive: no numeric-leading field names
-        fields.push(key);
-        rules[key] = parseRule(value, constants);
-      }
-      if (orRespond) {
-        // The opts arg follows the schema literal; strict unless it passes
-        // strict:false. When the schema was resolved from a module-scope const,
-        // the literal is not in the window — read the call tail instead.
-        const litAt = window.indexOf(lit, after);
-        const optsWindow = litAt >= 0 ? window.slice(litAt + lit.length) : window.slice(after);
-        strict = !/\bstrict\s*:\s*false\b/.test(optsWindow);
-      }
-    }
-  }
-  if (!readsBody && !validateCall) return null;
-  return { readsBody, validated: Boolean(validateCall), fields, rules, strict };
-}
-
-// ---------------------------------------------------------------------------
-// Response-shape extraction (task 2061 / ADR 0124 — type the success RESPONSE)
-// ---------------------------------------------------------------------------
-//
-// Task 2050 typed the REQUEST body from validate(); the SUCCESS response stayed
-// `any`. Routes declare no response schema, but they DO build the body inline —
-// `res.json({ … })` — and that object literal IS the shape. We read it statically
-// (the same captureBalanced/splitTopLevel machinery the request extractor uses),
-// never executing a route. Only the KEYS are provable (a value is usually a
-// variable, so it types as `unknown`); two values type safely — a boolean literal,
-// and the ADR-0119 `pageMeta()` `page` block (→ the shared PageInfo component).
-//
-// DEGRADE-GRACEFULLY CONTRACT — never emit a shape we cannot prove:
-//   - a bare-value response (`res.json(row)`), a top-level spread (`{ …rest }`),
-//     a computed/quoted key, or an empty `{}` → the route keeps the `ApiResponse`
-//     alias (extractResponse returns null). We only ever NARROW `any`, never lie.
-
-// The value expression of one response property → a JSON Schema fragment. Only two
-// shapes are typed with confidence; everything else is `{}` (renders as `unknown`).
-function responseValueSchema(expr) {
-  const v = String(expr).trim();
-  if (v === 'true' || v === 'false') return { type: 'boolean' };
-  // `!!x` and `Boolean(x)` are boolean whatever x is — the two idioms routes use
-  // to coerce a truthy value before returning it (task 1002430). Without this a
-  // handler returning `{ ok: true }` in one branch and `{ ok: !!v }` in another
-  // documents `ok` as untyped, which is strictly worse than the truth.
-  if (/^!!/.test(v) || /^Boolean\s*\(/.test(v)) return { type: 'boolean' };
-  if (/^pageMeta\s*\(/.test(v)) return { $ref: '#/components/schemas/PageInfo' };
-  return {}; // a variable / call / ternary — the KEY is the win; leave the value open
-}
-
-// Parse one `res.json({ … })` object literal → { key: valueSchema } (depth-1), or
-// null if the shape can't be fully trusted (spread / non-identifier key / empty).
-function parseResponseObject(objLiteral) {
-  const inner = stripComments(String(objLiteral)).trim().replace(/^\{/, '').replace(/\}$/, '');
-  const props = {};
-  let count = 0;
-  for (const seg of splitTopLevel(inner)) {
-    const s = seg.trim();
-    if (s === '') continue;
-    if (s.startsWith('...')) return null;            // spread → unknown extra keys
-    const kv = splitKeyValue(s);
-    let key; let value;
-    if (kv) { key = kv.key; value = kv.value; }
-    else if (/^[A-Za-z_$][\w$]*$/.test(s)) { key = s; value = s; } // { foo } shorthand
-    else return null;                                 // method / unparseable segment
-    if (!/^[A-Za-z_$][\w$]*$/.test(key)) return null; // computed/quoted key → give up
-    props[key] = responseValueSchema(value);
-    count++;
-  }
-  return count ? props : null;
-}
-
-// Merge the shapes of every success `res.json({ … })` in one handler (branches):
-// union the keys; a key present in EVERY branch is required, others optional; a
-// value schema is kept only where all branches agree (else it opens to `unknown`).
-function mergeResponseShapes(shapes) {
-  const order = [];
-  const byKey = {};
-  for (const shape of shapes) {
-    for (const [key, schema] of Object.entries(shape)) {
-      if (!byKey[key]) { byKey[key] = []; order.push(key); }
-      byKey[key].push(schema);
-    }
-  }
-  const properties = {};
-  const required = [];
-  for (const key of order) {
-    const variants = byKey[key];
-    const first = JSON.stringify(variants[0]);
-    properties[key] = variants.every((s) => JSON.stringify(s) === first) ? variants[0] : {};
-    if (variants.length === shapes.length) required.push(key);
-  }
-  return { properties, required };
-}
-
-// The success-response shape for a route: scan its handler window for success
-// `res.json(…)` / `res.status(2xx).json(…)` calls. Returns { properties, required }
-// when EVERY success body is a provable object literal, else null (degrade).
-function extractResponse(lines, i) {
-  const window = stripComments(lines.slice(i, routeEndLine(lines, i)).join('\n'));
-  const re = /\bres\s*\.\s*(?:status\s*\(\s*(\d+)\s*\)\s*\.\s*)?json\s*\(/g;
-  const shapes = [];
-  let m;
-  let sawSuccessJson = false;
-  while ((m = re.exec(window))) {
-    const status = m[1] ? Number(m[1]) : 200;
-    if (status < 200 || status > 299) continue;       // error body — the envelope covers it
-    sawSuccessJson = true;
-    let k = m.index + m[0].length;                    // first char after '('
-    while (k < window.length && /\s/.test(window[k])) k++;
-    if (window[k] !== '{') return null;               // bare value → shape unknowable
-    const lit = captureBalanced(window, k);
-    const shape = lit && parseResponseObject(lit);
-    if (!shape) return null;                           // couldn't prove the shape
-    shapes.push(shape);
-  }
-  if (!sawSuccessJson || !shapes.length) return null;
-  return mergeResponseShapes(shapes);
-}
-
-// First path segment → resource tag (tasks, me, public, …). '' → 'root'.
-function tagFor(route) {
-  const seg = route.split('/').filter(Boolean)[0] || 'root';
-  return seg.replace(/[^A-Za-z0-9_-]/g, '');
-}
-
-// The full extracted model: [{ method, route, openapiPath, params, rank, tag,
-// description, body, file }], stable-sorted.
-// `routeFiles` is injectable so a test can drive the model over a fixture route file
-// (the default is the live core + module route set).
-function extractModel({ routeFiles = rrc.discoverRouteFiles() } = {}) {
-  const routes = [];
-  const globals = globalConstants();
-  for (const { abs, rel } of routeFiles) {
-    const text = fs.readFileSync(abs, 'utf8');
-    const lines = text.split('\n');
-    // Constants a validate() rule in THIS file may reference (LIMITS + file-local consts).
-    const constants = Object.assign({}, globals, scanFileConstants(text));
-    // rrc.scanDeclarations, not a second regex: the spec must enumerate EXACTLY the
-    // routes the ship-time gate enforces. Its own regex missed multi-line declarations,
-    // so 10 real endpoints (6 writes) were absent from the published contract entirely
-    // (BV1.R109b). An unresolvable path is skipped here and reported by checkRouteRanks.
-    for (const decl of rrc.scanDeclarations(text)) {
-      if (decl.route === null) continue;
-      const i = decl.line;
-      const method = decl.method;
-      const route = decl.route;
-      const { openapiPath, names } = pathParams(route);
-      // classifyGate, not classifyRank: a route migrated to requirePermission(...)
-      // (BV1.R104-R107) resolves through the governance catalog to its real rank
-      // floor, and names the authority atoms it gates on. Before BV1.R109 those
-      // routes documented as 'any-builder' — enforcement was correct, the LABEL lied.
-      const { rank, perms } = rrc.classifyGate(lines, i);
-      routes.push({
-        method,
-        route,
-        openapiPath,
-        params: names,
-        rank,
-        perms,
-        tag: tagFor(route),
-        description: commentBlockAbove(lines, i),
-        body: extractBody(lines, i, method, constants),
-        response: extractResponse(lines, i),
-        file: rel,
-      });
-    }
-  }
-  routes.sort((a, b) =>
-    a.openapiPath.localeCompare(b.openapiPath)
-    || METHOD_ORDER.indexOf(a.method.toLowerCase()) - METHOD_ORDER.indexOf(b.method.toLowerCase())
-    || a.file.localeCompare(b.file));
-  return routes;
-}
-
-// ---------------------------------------------------------------------------
-// OpenAPI 3.1 assembly
-// ---------------------------------------------------------------------------
-
-function operationId(method, openapiPath) {
-  const slug = openapiPath.replace(/[{}]/g, '').replace(/[^A-Za-z0-9]+/g, '_').replace(/^_|_$/g, '');
-  return `${method.toLowerCase()}_${slug || 'root'}`;
-}
-
-function pascalCase(s) {
-  return String(s).split(/[^A-Za-z0-9]+/).filter(Boolean)
-    .map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
-}
-
-// A body field whose validate() rule declared NO type but whose name is a resource
-// id: task_id/builder_id/parent_task_id/… These are Postgres bigint PKs left untyped
-// on purpose (R11/#1998 — they arrive as a JSON number OR a stringified integer).
-// Give them the shared StringifiableId schema instead of degrading to `{}`.
-// version_id is excluded (it is a text slug and always declares type:'string', so it
-// never reaches the untyped branch — the guard is belt-and-braces).
-function isIdField(field) {
-  return field !== 'version_id' && (field === 'id' || /_id$/.test(field));
-}
-
-// ruleToSchema(field, rule) — one field's parsed rule → a JSON Schema fragment.
-function ruleToSchema(field, rule) {
-  if (!rule.type) {
-    if (isIdField(field)) return { $ref: '#/components/schemas/StringifiableId' };
-    return rule.enum ? { enum: rule.enum } : {}; // untyped, non-id → unconstrained
-  }
-  const s = {};
-  if (rule.type === 'integer' || rule.type === 'number') {
-    s.type = rule.type;
-    if (rule.min != null) s.minimum = rule.min;
-    if (rule.max != null) s.maximum = rule.max;
-  } else if (rule.type === 'string') {
-    s.type = 'string';
-    if (rule.minLength != null) s.minLength = rule.minLength;
-    if (rule.maxLength != null) s.maxLength = rule.maxLength;
-  } else if (rule.type === 'array') {
-    s.type = 'array';
-    if (rule.itemsType) s.items = { type: rule.itemsType };
-    if (rule.maxItems != null) s.maxItems = rule.maxItems;
-  } else {
-    s.type = rule.type; // boolean | object
-  }
-  if (rule.enum) s.enum = rule.enum;
-  return s;
-}
-
-// requestSchemaFor(r) — the JSON Schema for a write route's body, plus a component
-// name when it carries declared fields (so it lands in components.schemas and the
-// operation references it by $ref). A body with no declared fields (an undocumented
-// or schema-less body) stays an inline open object with no named component.
-function requestSchemaFor(r) {
-  const rules = r.body.rules || {};
-  const fields = r.body.fields || [];
-  if (!fields.length) return { schema: { type: 'object', additionalProperties: true } };
-  const properties = {};
-  const required = [];
-  for (const f of fields) {
-    const rule = rules[f] || {};
-    properties[f] = ruleToSchema(f, rule);
-    if (rule.required) required.push(f);
-  }
-  const schema = { type: 'object', properties };
-  if (required.length) schema.required = required;
-  // A validated strict route rejects unknown fields; a lenient/undeclared one allows them.
-  schema.additionalProperties = r.body.validated ? !r.body.strict : true;
-  return { schema, componentName: pascalCase(operationId(r.method, r.openapiPath)) + 'Request', required };
-}
-
-// The reusable component schemas every spec carries (task 2050): the ADR-0116 error
-// envelope + its inner object, and the pg-bigint id convention.
-function baseComponentSchemas() {
-  return {
-    ApiErrorObject: {
-      type: 'object',
-      required: ['code', 'message'],
-      properties: {
-        code: { type: 'string', description: 'Stable machine-readable slug the caller may switch on (e.g. `task_not_found`). Classified into a category (`x-error-categories`); the specific slug is preserved (ADR 0116).' },
-        message: { type: 'string', description: 'Human-readable, safe to surface. Never leaks internals unless a handler opts in.' },
-        details: { description: 'Optional structured payload — e.g. the validator\'s `[{ field, reason }]` list.' },
-      },
-      description: 'The inner error object carried by every non-2xx response.',
-    },
-    ErrorEnvelope: {
-      type: 'object',
-      required: ['error'],
-      properties: { error: { $ref: '#/components/schemas/ApiErrorObject' } },
-      description: 'The single error shape returned by EVERY non-2xx response (ADR 0116). A caller reads `error.code`.',
-    },
-    StringifiableId: {
-      type: ['integer', 'string'],
-      description: 'A resource id — an integer, or its stringified form (a Postgres bigint serializes as a JSON string, so ids may arrive either way). Accept both.',
-    },
-    PageInfo: {
-      type: 'object',
-      required: ['limit', 'offset'],
-      properties: {
-        limit: { type: 'integer', description: 'Page size actually applied (clamped to the endpoint cap, ADR 0119).' },
-        offset: { type: 'integer', description: 'Zero-based row offset of this page.' },
-        total: { type: 'integer', description: 'Total matching rows, when cheaply countable; derive "more pages" via `offset + items.length < total`.' },
-      },
-      description: 'The `page` block of a paginated list response (ADR 0119), built by `pageMeta()`.',
-    },
-  };
-}
-
-// The reusable error responses (ADR 0116) — the envelope, referenced by every
-// non-2xx. Defined ONCE in components.responses; each operation $refs the right one
-// (keeps the committed spec lean instead of inlining the body on 200+ routes).
-function baseComponentResponses() {
-  const body = { content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } } };
-  return {
-    BadRequest: { description: 'Malformed or invalid request (the ADR-0116 error envelope).', ...body },
-    ValidationFailed: { description: 'Request body failed schema validation; `error.details` lists the field errors.', ...body },
-    Unauthorized: { description: 'No or invalid session.', ...body },
-    Forbidden: { description: 'Authenticated but rank/ownership too low for this route.', ...body },
-    NotFound: { description: 'The referenced resource does not exist.', ...body },
-  };
-}
-
-function buildOperation(r, stats, schemas) {
-  const op = {
-    operationId: operationId(r.method, r.openapiPath),
-    tags: [r.tag],
-    summary: `${r.method} ${routeForDisplay(r.route)}`,
-    description: (r.description ? r.description + '\n\n' : '')
-      + `**Rank:** \`${r.rank}\` — ${RANK_BLURB[r.rank] || RANK_BLURB.unknown}`
-      + (r.perms && r.perms.length ? `\n\n**Permissions:** \`${r.perms.join('`, `')}\` (all required).` : ''),
-    'x-rank': r.rank,
-    'x-source': r.file,
-  };
-  // The authority ATOMS a migrated route gates on (ADR 0151). Absent on a route still
-  // gated by rank, so today's spec is byte-identical until BV1.R104-R107 land.
-  if (r.perms && r.perms.length) op['x-permissions'] = r.perms;
-  if (r.params.length) {
-    op.parameters = r.params.map((name) => ({
-      name, in: 'path', required: true, schema: { type: 'string' },
-      description: `Path parameter \`${name}\`.`,
-    }));
-  }
-  if (r.body) {
-    const { schema, componentName, required } = requestSchemaFor(r);
-    let bodySchema = schema;
-    if (componentName) {
-      schemas[componentName] = schema; // land it in components.schemas
-      bodySchema = { $ref: '#/components/schemas/' + componentName };
-    }
-    op.requestBody = {
-      // A body is REQUIRED when the schema declares at least one required field.
-      required: Boolean(required && required.length),
-      content: { 'application/json': { schema: bodySchema } },
-      'x-validated': r.body.validated,
-    };
-    if (!r.body.validated) {
-      op.requestBody['x-body-undocumented'] = true;
-      stats.undocumentedBodies++;
-    }
-  }
-  const responses = { 200: { description: 'Success.' } };
-  // task 2061: attach the statically-proven success shape (from res.json({…})) to
-  // 200 as a named component, so the generated client types the return concretely.
-  if (r.response && Object.keys(r.response.properties).length) {
-    const componentName = pascalCase(operationId(r.method, r.openapiPath)) + 'Response';
-    const schema = { type: 'object', properties: r.response.properties };
-    if (r.response.required.length) schema.required = r.response.required;
-    schemas[componentName] = schema;
-    responses[200] = { description: 'Success.', content: { 'application/json': { schema: { $ref: '#/components/schemas/' + componentName } } } };
-    stats.responseSchemas++;
-  }
-  responses[400] = { $ref: (r.body && r.body.validated) ? '#/components/responses/ValidationFailed' : '#/components/responses/BadRequest' };
-  if (r.rank !== 'public') {
-    responses[401] = { $ref: '#/components/responses/Unauthorized' };
-    responses[403] = { $ref: '#/components/responses/Forbidden' };
-  }
-  if (r.params.length) responses[404] = { $ref: '#/components/responses/NotFound' };
-  op.responses = responses;
-  op.security = r.rank === 'public' ? [] : [{ builderSession: [] }];
-  return op;
-}
-
-function buildOpenapi(model) {
-  const stats = { undocumentedBodies: 0, responseSchemas: 0 };
-  const schemas = baseComponentSchemas();
-  const paths = {};
-  for (const r of model) {
-    if (!paths[r.openapiPath]) paths[r.openapiPath] = {};
-    paths[r.openapiPath][r.method.toLowerCase()] = buildOperation(r, stats, schemas);
-  }
-  // Deterministic key order for components.schemas (base + per-operation request schemas).
-  const sortedSchemas = {};
-  for (const k of Object.keys(schemas).sort()) sortedSchemas[k] = schemas[k];
-  // Stable key order for paths (already sorted in model, but rebuild explicitly).
-  const sortedPaths = {};
-  for (const p of Object.keys(paths).sort()) sortedPaths[p] = paths[p];
-
-  const tags = [...new Set(model.map((r) => r.tag))].sort()
-    .map((name) => ({ name, description: `Endpoints under \`${API_PREFIX}/${name}\`.` }));
-
-  const spec = {
-    openapi: '3.1.0',
-    info: {
-      title: `${productName()} — Bongos API`,
-      version: specVersion(),
-      license: { name: 'AGPL-3.0-or-later', url: 'https://www.gnu.org/licenses/agpl-3.0.html' },
-      description: [
-        `The Bongos API — the build-methodology backend`,
-        `(builders, tasks, claims, credits, grading, memory).`,
-        ``,
-        `**API version:** \`${API_VERSION}\` — served at \`${VERSIONED_API_PREFIX}\`. The`,
-        `unversioned \`${API_PREFIX}\` and legacy \`/api/gds\` are permanent aliases`,
-        `pinned to this version; pin to \`${VERSIONED_API_PREFIX}\` for a stable`,
-        `contract (breaking changes ship a new \`/vN\`, ADR 0117). This is the`,
-        `CONTRACT version, distinct from the package build in \`info.version\`.`,
-        ``,
-        `**Base path:** \`${API_PREFIX}\` (every path below is relative to it).`,
-        ``,
-        `**Auth:** a builder session — the \`gds_session\` cookie (web) or`,
-        `\`Authorization: Bearer <token>\` (CLI). **Ranks** gate writes and are`,
-        `enforced server-side per request, never cached (ADR 0016):`,
-        `\`public\` < \`any-builder\` < \`metic+archon\` < \`archon\`.`,
-        `Each operation carries its required rank in \`x-rank\`.`,
-        ``,
-        `Generated from the live route files by \`scripts/gds/gen-api-docs.js\` —`,
-        `do not hand-edit; it regenerates on every ship.`,
-      ].join('\n'),
-    },
-    'x-api-version': API_VERSION, // the explicit contract version (ADR 0117)
-    servers: [
-      { url: VERSIONED_API_PREFIX, description: 'Versioned API base (same-origin) — pin here for a stable contract.' },
-      { url: API_PREFIX, description: 'Unversioned alias (permanent) — resolves to the current version.' },
-    ],
-    tags,
-    paths: sortedPaths,
-    components: {
-      securitySchemes: {
-        builderSession: {
-          type: 'apiKey',
-          in: 'cookie',
-          name: 'gds_session',
-          description: 'Builder session. Web clients send the `gds_session` cookie; '
-            + 'CLI clients send `Authorization: Bearer <token>`. Rank is resolved from '
-            + 'the live builder record on every request (ADR 0016).',
-        },
-      },
-      schemas: sortedSchemas,
-      responses: baseComponentResponses(),
-    },
-    // The error-code taxonomy (ADR 0116): every non-2xx `error.code` classifies onto
-    // one of these categories, each with a default status + retriable flag. Sourced
-    // from the kernel registry (src/bongos/api-errors.js) so docs can't drift from it.
-    'x-error-categories': apiErrors.CATEGORIES,
-    'x-endpoint-count': model.length,
-    'x-schema-count': Object.keys(sortedSchemas).length,
-    'x-undocumented-bodies': stats.undocumentedBodies,
-    'x-response-schemas': stats.responseSchemas,
-    'x-generated-by': 'scripts/gds/gen-api-docs.js',
-  };
-  return spec;
-}
-
-// ---------------------------------------------------------------------------
-// Markdown reference
-// ---------------------------------------------------------------------------
-
-const MD_BANNER = '<!-- GENERATED by scripts/gds/gen-api-docs.js — do not hand-edit. Run `node scripts/gds/gen-api-docs.js`. -->';
-
-function shortDesc(d) {
-  if (!d) return '';
-  const first = d.split(/(?<=\.)\s/)[0];
-  return (first.length > 140 ? first.slice(0, 137) + '…' : first).replace(/\|/g, '\\|');
-}
-
-function buildReferenceMd(model, spec) {
-  const L = [];
-  L.push(MD_BANNER);
-  L.push('');
-  L.push('# Bongos API reference');
-  L.push('');
-  L.push(`> **Generated from the live route files** — the route file is authoritative. ${model.length} endpoints across ${new Set(model.map((r) => r.file)).size} route files.`);
-  L.push('> Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).');
-  L.push('');
-  L.push(`Base path: \`${API_PREFIX}\`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): \`public\` < \`any-builder\` < \`metic+archon\` < \`archon\`.`);
-  L.push('');
-  const byTag = new Map();
-  for (const r of model) {
-    if (!byTag.has(r.tag)) byTag.set(r.tag, []);
-    byTag.get(r.tag).push(r);
-  }
-  for (const tag of [...byTag.keys()].sort()) {
-    const rows = byTag.get(tag);
-    L.push(`## \`${tag}\` (${rows.length})`);
-    L.push('');
-    L.push('| Method | Path | Rank | Body | Description |');
-    L.push('|---|---|---|---|---|');
-    for (const r of rows) {
-      const body = r.body
-        ? (r.body.validated
-          ? (r.body.fields.length ? '`' + r.body.fields.join('`, `') + '`' : 'validated')
-          : '_undocumented_')
-        : '—';
-      L.push(`| ${r.method} | \`${API_PREFIX}${routeForDisplay(r.route)}\` | \`${r.rank}\` | ${body} | ${shortDesc(r.description)} |`);
-    }
-    L.push('');
-  }
-  if (spec['x-undocumented-bodies'] > 0) {
-    L.push('---');
-    L.push('');
-    L.push(`> ${spec['x-undocumented-bodies']} write endpoint(s) take a JSON body with no declared validator schema — their fields are not yet machine-documented. Adding a \`validateOrRespond\` schema (\`src/bongos/routes/_helpers.js\`) surfaces them here automatically.`);
-    L.push('');
-  }
-  return L.join('\n') + '\n';
-}
-
-function buildPermissionsStub() {
-  return [
-    MD_BANNER,
-    '',
-    '# Routes & permissions — moved',
-    '',
-    '> This hand-maintained mirror has been **retired**. Every endpoint and its rank gate',
-    '> is now generated from the live route files.',
-    '',
-    '- **Full endpoint + permission reference:** [`docs/api-reference.md`](api-reference.md)',
-    '- **Machine-readable spec (OpenAPI 3.1):** [`docs/api/openapi.json`](api/openapi.json)',
-    '- **Rendered docs site:** **`/docs`** (e.g. `cloudbongos.com/docs`)',
-    '- **Rank-ladder model:** [`docs/canonical-permissions.md`](canonical-permissions.md) · [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)',
-    '',
-    'Regenerate with `node scripts/gds/gen-api-docs.js`.',
-    '',
-  ].join('\n');
-}
-
-// ---------------------------------------------------------------------------
-// Built-in structural OpenAPI 3.1 validator (no external dep)
-// ---------------------------------------------------------------------------
-
-function validateOpenapi(spec) {
-  const problems = [];
-  if (spec.openapi !== '3.1.0') problems.push(`openapi must be '3.1.0' (got ${JSON.stringify(spec.openapi)})`);
-  if (!spec.info || typeof spec.info.title !== 'string' || !spec.info.title) problems.push('info.title missing');
-  if (!spec.info || typeof spec.info.version !== 'string' || !spec.info.version) problems.push('info.version missing');
-  if (!spec.paths || typeof spec.paths !== 'object') problems.push('paths missing');
-  const schemes = (spec.components && spec.components.securitySchemes) || {};
-  for (const [p, item] of Object.entries(spec.paths || {})) {
-    if (!p.startsWith('/')) problems.push(`path ${p} must start with '/'`);
-    for (const [method, op] of Object.entries(item)) {
-      if (!METHOD_ORDER.includes(method)) problems.push(`${p}: unexpected method ${method}`);
-      if (!op.responses || Object.keys(op.responses).length === 0) problems.push(`${method.toUpperCase()} ${p}: no responses`);
-      for (const param of op.parameters || []) {
-        if (!param.name || !param.in) problems.push(`${method.toUpperCase()} ${p}: malformed parameter`);
-      }
-      for (const req of op.security || []) {
-        for (const name of Object.keys(req)) {
-          if (!schemes[name]) problems.push(`${method.toUpperCase()} ${p}: security scheme '${name}' not defined in components`);
-        }
-      }
-    }
-  }
-  // Every local $ref under paths/components must resolve to a defined component
-  // (schema or response) — a dangling $ref is a broken contract (task 2050).
-  const definedSchemas = new Set(Object.keys((spec.components && spec.components.schemas) || {}));
-  const definedResponses = new Set(Object.keys((spec.components && spec.components.responses) || {}));
-  const seen = [];
-  (function collectRefs(node) {
-    if (!node || typeof node !== 'object') return;
-    if (typeof node.$ref === 'string') seen.push(node.$ref);
-    for (const v of Object.values(node)) collectRefs(v);
-  })({ paths: spec.paths, components: spec.components });
-  for (const ref of seen) {
-    const sm = /^#\/components\/schemas\/(.+)$/.exec(ref);
-    const rm = /^#\/components\/responses\/(.+)$/.exec(ref);
-    if (sm) { if (!definedSchemas.has(sm[1])) problems.push(`$ref '${ref}' does not resolve to a defined component schema`); }
-    else if (rm) { if (!definedResponses.has(rm[1])) problems.push(`$ref '${ref}' does not resolve to a defined component response`); }
-    else problems.push(`unsupported $ref (only #/components/{schemas,responses}/* is emitted): ${ref}`);
-  }
-  return problems;
-}
-
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
-
-function build() {
-  const model = extractModel();
-  const spec = buildOpenapi(model);
-  return {
-    model,
-    spec,
-    files: [
-      { full: OPENAPI_PATH, rel: 'docs/api/openapi.json', content: JSON.stringify(spec, null, 2) + '\n' },
-      { full: REFERENCE_PATH, rel: 'docs/api-reference.md', content: buildReferenceMd(model, spec) },
-      { full: PERMISSIONS_PATH, rel: 'docs/routes-permissions.md', content: buildPermissionsStub() },
-    ],
-  };
-}
-
-function main() {
-  const args = process.argv.slice(2);
-  const checkOnly = args.includes('--check');
-  const jsonOnly = args.includes('--json');
-
-  const { model, spec, files } = build();
-
-  if (jsonOnly) {
-    console.log(JSON.stringify({ endpoints: model.length, undocumentedBodies: spec['x-undocumented-bodies'], model }, null, 2));
-    return;
-  }
-
-  // Always structurally validate — a malformed spec is a hard failure in both modes.
-  const problems = validateOpenapi(spec);
-  if (problems.length) {
-    console.error('gen-api-docs: generated spec is NOT valid OpenAPI 3.1:');
-    for (const p of problems) console.error('  - ' + p);
-    process.exit(1);
-  }
-
-  if (checkOnly) {
-    const stale = files.filter((f) => {
-      let cur = null;
-      try { cur = fs.readFileSync(f.full, 'utf8'); } catch { return true; /* missing → stale */ }
-      return !sameContent(cur, f.content);
-    });
-    if (stale.length) {
-      console.error(`gen-api-docs --check: STALE — would update ${stale.map((f) => f.rel).join(', ')}. Run \`node scripts/gds/gen-api-docs.js\` and commit.`);
-      process.exit(2);
-    }
-    console.log(`gen-api-docs --check: up to date (${model.length} endpoints, ${spec['x-undocumented-bodies']} undocumented bodies).`);
-    return;
-  }
-
-  fs.mkdirSync(path.dirname(OPENAPI_PATH), { recursive: true });
-  for (const f of files) fs.writeFileSync(f.full, f.content);
-  console.log(`gen-api-docs: wrote ${files.length} files — ${model.length} endpoints, ${spec['x-undocumented-bodies']} undocumented bodies.`);
-}
-
-if (require.main === module) main();
-
-module.exports = {
-  extractModel,
-  buildOpenapi,
-  buildReferenceMd,
-  buildPermissionsStub,
-  validateOpenapi,
-  commentBlockAbove,
-  pathParams,
-  routeForDisplay,
-  captureBalanced,
-  topLevelKeys,
-  topLevelEntries,
-  splitTopLevel,
-  splitKeyValue,
-  resolveScalar,
-  resolveArray,
-  resolveConst,
-  parseRule,
-  scanFileConstants,
-  ruleToSchema,
-  requestSchemaFor,
-  isIdField,
-  pascalCase,
-  extractBody,
-  routeEndLine,
-  responseValueSchema,
-  parseResponseObject,
-  mergeResponseShapes,
-  extractResponse,
-  build,
-  API_PREFIX,
-};
+require('../bongos/forwarder.js').forward(module, 'gen-api-docs.js');