@yemi33/minions 0.1.2424 → 0.1.2426

package/engine/api-contracts/core.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const { CC_API_LIMITS, PRESENCE_VISIBILITIES } = require('../cc-api-validation');
+
+module.exports = {
+  owner: 'core',
+  routes: [
+    'GET /api/version',
+    'GET /api/routes',
+    'GET /api/status',
+    'GET /api/engine-log',
+    'GET /api/constellation/v1/snapshot',
+    'GET /state/<path>',
+    'GET /api/metrics',
+    'GET /api/tools',
+    'GET /api/browser-presence',
+    'POST /api/browser-presence',
+    'GET /api/status-stream',
+    'GET /api/health',
+    'POST /api/dashboard/restart',
+  ],
+  bodyless: [
+    'POST /api/dashboard/restart',
+  ],
+  overrides: {
+    'POST /api/dashboard/restart': {
+      audit: 'audited',
+      body: {
+        policy: 'optional',
+        fields: [],
+        rationale: 'The fixed operator action accepts either no body or an empty JSON object.',
+      },
+      constraints: [
+        { kind: 'absent-or-empty-object', location: 'body' },
+      ],
+      negativeTests: [
+        { strategy: 'send-meaningful-object-body', expectedStatus: 400 },
+        { strategy: 'send-non-object-json-body', expectedStatus: 400 },
+      ],
+    },
+    'GET /api/version': {
+      audit: 'audited',
+      noInputReason: 'Returns process and package version state; accepts no caller input.',
+    },
+    'GET /api/routes': {
+      audit: 'audited',
+      noInputReason: 'Returns the static executable route catalog; dynamic constraints are source references.',
+    },
+    'GET /api/status': {
+      audit: 'audited',
+      noInputReason: 'Returns the current dashboard snapshot; accepts no caller input.',
+    },
+    'GET /api/engine-log': {
+      audit: 'audited',
+      noInputReason: 'Returns the latest SQL-backed engine log entries; accepts no caller input.',
+    },
+    'GET /api/tools': {
+      audit: 'audited',
+      noInputReason: 'Returns the cached skills/commands/MCP inventory; accepts no caller input.',
+    },
+    'GET /api/constellation/v1/snapshot': {
+      audit: 'audited',
+      noInputReason: 'Returns the versioned bridge snapshot; accepts no caller input.',
+    },
+    'GET /state/<path>': {
+      audit: 'audited',
+      path: {
+        policy: 'required',
+        fields: [
+          {
+            name: 'path',
+            type: 'path',
+            required: true,
+            maxLength: 4096,
+            allowedValuesSource: 'dashboard.STATE_READ_ALLOWED_DIRS/STATE_READ_ALLOWED_FILES',
+          },
+        ],
+      },
+      constraints: [
+        {
+          kind: 'sandbox-membership',
+          base: 'queries.MINIONS_DIR',
+          traversalStatus: 403,
+          missingStatus: 404,
+        },
+        {
+          kind: 'decoded-before-filesystem-access',
+          field: 'path',
+          location: 'path',
+        },
+      ],
+      negativeTests: [
+        { strategy: 'malformed-url-encoding', expectedStatus: 400 },
+        { strategy: 'path-traversal', expectedStatus: 403 },
+        { strategy: 'missing-path', expectedStatus: 404 },
+      ],
+    },
+    'GET /api/metrics': {
+      audit: 'audited',
+      noInputReason: 'Returns the current metrics projection; accepts no caller input.',
+    },
+    'GET /api/browser-presence': {
+      audit: 'audited',
+      noInputReason: 'Returns the current browser-presence snapshot; accepts no caller input.',
+    },
+    'GET /api/status-stream': {
+      audit: 'audited',
+      noInputReason: 'Opens the fixed status SSE stream; accepts no caller input.',
+    },
+    'GET /api/health': {
+      audit: 'audited',
+      noInputReason: 'Returns the lightweight process health snapshot; accepts no caller input.',
+    },
+    'POST /api/browser-presence': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'tabId', type: 'string', required: true, maxLength: CC_API_LIMITS.tabIdMaxChars },
+          { name: 'closed', type: 'boolean', required: false },
+          { name: 'url', type: 'string', required: false, maxLength: CC_API_LIMITS.presenceUrlMaxChars },
+          {
+            name: 'visibility',
+            type: 'string',
+            required: false,
+            allowedValues: PRESENCE_VISIBILITIES,
+            maxLength: CC_API_LIMITS.visibilityMaxChars,
+          },
+        ],
+      },
+      negativeTests: [
+        { strategy: 'omit-or-malform-tab-id', expectedStatus: 400 },
+        { strategy: 'use-wrong-field-types', expectedStatus: 400 },
+        { strategy: 'exceed-string-limits', expectedStatus: 400 },
+      ],
+    },
+  },
+};

package/engine/api-contracts/index.js

@@ -0,0 +1,506 @@
+'use strict';
+
+const OWNER_MODULES = [
+  require('./core'),
+  require('./work-plan-prd'),
+  require('./pull-requests'),
+  require('./config-runtime'),
+  require('./orchestration'),
+  require('./qa-process'),
+  require('./agent-content'),
+  require('./cc-ops'),
+];
+
+const OWNER_NAMES = OWNER_MODULES.map(moduleContract => String(moduleContract.owner || '').trim());
+if (new Set(OWNER_NAMES).size !== OWNER_NAMES.length) {
+  throw new Error('API contract ownership modules must use unique owner names');
+}
+const OWNERS = Object.freeze(OWNER_NAMES);
+const LOCATION_POLICIES = new Set(['none', 'optional', 'required', 'pending-audit']);
+const AUDIT_STATUSES = new Set(['audited', 'pending-audit']);
+
+function canonicalPathTemplate(value) {
+  const pathTemplate = String(value || '').trim();
+  if (!pathTemplate.startsWith('/')) {
+    throw new Error(`Route path template must start with "/": ${pathTemplate || '(empty)'}`);
+  }
+  return pathTemplate.replace(/:([A-Za-z][A-Za-z0-9_]*)/g, '<$1>');
+}
+
+function canonicalRouteKey(route) {
+  if (typeof route === 'string') {
+    const match = route.trim().match(/^([A-Za-z]+)\s+(.+)$/);
+    if (!match) throw new Error(`Invalid route key: ${route}`);
+    return `${match[1].toUpperCase()} ${canonicalPathTemplate(match[2])}`;
+  }
+  if (!route || typeof route !== 'object') throw new Error('Route must be an object or canonical key');
+  const method = String(route.method || '').trim().toUpperCase();
+  if (!method) throw new Error('Route method is required');
+  let pathTemplate;
+  if (typeof route.path === 'string') {
+    pathTemplate = route.path;
+  } else if (route.path instanceof RegExp) {
+    pathTemplate = route.template || route.pathTemplate;
+    if (!pathTemplate) {
+      throw new Error(`${method} regex route requires an explicit path template`);
+    }
+  } else {
+    throw new Error(`${method} route path must be a string or RegExp`);
+  }
+  return `${method} ${canonicalPathTemplate(pathTemplate)}`;
+}
+
+function splitCanonicalKey(key) {
+  const canonical = canonicalRouteKey(key);
+  const separator = canonical.indexOf(' ');
+  return {
+    key: canonical,
+    method: canonical.slice(0, separator),
+    path: canonical.slice(separator + 1),
+  };
+}
+
+function pathFields(pathTemplate) {
+  return [...pathTemplate.matchAll(/<([A-Za-z][A-Za-z0-9_]*)>/g)].map(match => ({
+    name: match[1],
+    type: match[1].toLowerCase() === 'path' ? 'path' : 'string',
+    required: true,
+  }));
+}
+
+function cloneSerializable(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function normalizeFields(fields, key, location) {
+  if (fields === undefined) return [];
+  if (!Array.isArray(fields)) throw new Error(`${key} ${location}.fields must be an array`);
+  return fields.map(field => {
+    if (!field || typeof field !== 'object' || Array.isArray(field)) {
+      throw new Error(`${key} ${location} field must be an object`);
+    }
+    const name = String(field.name || '').trim();
+    const type = String(field.type || '').trim();
+    if (!name || !type) throw new Error(`${key} ${location} fields require name and type`);
+    if (field.allowedValuesSource !== undefined
+        && (typeof field.allowedValuesSource !== 'string' || !field.allowedValuesSource.trim())) {
+      throw new Error(`${key} ${location}.${name} allowedValuesSource must be a non-empty string`);
+    }
+    return cloneSerializable({ ...field, name, type });
+  });
+}
+
+function normalizeLocation(value, fallback, key, location) {
+  const source = value === undefined ? fallback : value;
+  if (!source || typeof source !== 'object' || Array.isArray(source)) {
+    throw new Error(`${key} ${location} contract must be an object`);
+  }
+  const policy = String(source.policy || '').trim();
+  if (!LOCATION_POLICIES.has(policy)) {
+    throw new Error(`${key} ${location} has invalid policy "${policy}"`);
+  }
+  const normalized = {
+    policy,
+    fields: normalizeFields(source.fields, key, location),
+  };
+  if (source.rationale) normalized.rationale = String(source.rationale);
+  return normalized;
+}
+
+function defaultPendingNegativeTest() {
+  return {
+    strategy: 'reject-malformed-or-invalid-input',
+    expectedStatus: '4xx',
+    audit: 'pending-audit',
+  };
+}
+
+function buildRouteContract(owner, key, bodyless, override = {}) {
+  const parsed = splitCanonicalKey(key);
+  const stateChanging = !['GET', 'HEAD', 'OPTIONS'].includes(parsed.method);
+  const routePathFields = pathFields(parsed.path);
+  const bodylessRoute = bodyless.has(parsed.key);
+  // A route is "declared" when its owning module explicitly authored an I/O
+  // contract for it — via an `overrides` entry or a `bodyless` opt-in. Routes
+  // that were never declared must not be silently certified as `audited`
+  // (see the read-side default below).
+  const declared = bodylessRoute || Object.keys(override).length > 0;
+  const bodyRationale = parsed.method === 'DELETE'
+    ? 'The resource identifier is supplied by the path; this route does not accept a request body.'
+    : 'This state-changing route does not accept a request body.';
+  let defaultBody = { policy: 'none', fields: [] };
+  if (stateChanging && !bodylessRoute) {
+    defaultBody = { policy: 'pending-audit', fields: [] };
+  } else if (stateChanging) {
+    defaultBody.rationale = bodyRationale;
+  }
+  // An undeclared read-side surface (query/headers) is *unknown*, not empty. A
+  // route whose owning module never authored any contract for it (no override,
+  // not bodyless) must not be silently certified as `audited` while asserting it
+  // consumes no query/header input — that would publish a false contract hiding
+  // live params (e.g. GET /api/work-items/<id>?source or the SSE ?tail cutoff).
+  // Declaring the route — via ANY override or a bodyless opt-in — is the explicit
+  // assertion that opts its unspecified read-side locations back into `none`.
+  const unspecifiedReadInput = location => (declared
+    ? { policy: 'none', fields: [] }
+    : {
+      policy: 'pending-audit',
+      fields: [],
+      rationale: `The ${location} input surface for this route has not been audited.`,
+    });
+  const defaults = {
+    body: defaultBody,
+    path: routePathFields.length
+      ? { policy: 'required', fields: routePathFields }
+      : { policy: 'none', fields: [] },
+    query: unspecifiedReadInput('query'),
+    headers: unspecifiedReadInput('headers'),
+  };
+  const request = {
+    body: normalizeLocation(override.body, defaults.body, parsed.key, 'body'),
+    path: normalizeLocation(override.path, defaults.path, parsed.key, 'path'),
+    query: normalizeLocation(override.query, defaults.query, parsed.key, 'query'),
+    headers: normalizeLocation(override.headers, defaults.headers, parsed.key, 'headers'),
+    aliases: cloneSerializable(override.aliases || []),
+    constraints: cloneSerializable(override.constraints || []),
+  };
+  if (!Array.isArray(request.aliases) || !Array.isArray(request.constraints)) {
+    throw new Error(`${parsed.key} aliases and constraints must be arrays`);
+  }
+  const noInput = ['body', 'path', 'query', 'headers']
+    .every(location => request[location].policy === 'none');
+  const hasPendingAudit = ['body', 'path', 'query', 'headers']
+    .some(location => request[location].policy === 'pending-audit');
+  // A route earns the `audited` badge only when its caller-supplied input surface
+  // has been EXPLICITLY described or affirmed — never merely by omission. Leaving
+  // body/query/headers unspecified defaults them to `none`, which previously
+  // auto-certified the whole route as `audited` and published a false "no input"
+  // contract for routes that actually read a query/body (e.g. GET
+  // /api/work-items/<id>?source, POST /api/projects/browse). Path fields are
+  // auto-derived from the template and do NOT count as an owner declaration.
+  // Explicit affirmation is any of: an owner override that declares a body/query/
+  // headers location, an explicit `noInput: true`, an explicit `audit` value, or
+  // (for state-changing routes) an explicit bodyless declaration whose rationale
+  // documents the empty contract. Otherwise the route stays `pending-audit`
+  // (review PR #966).
+  const describesInput = override.body !== undefined
+    || override.query !== undefined
+    || override.headers !== undefined
+    || override.noInput === true;
+  const explicitlyAffirmed = describesInput
+    || override.audit !== undefined
+    || (stateChanging && bodylessRoute);
+  let audit;
+  if (override.audit) {
+    audit = override.audit;
+  } else if (hasPendingAudit || !explicitlyAffirmed) {
+    audit = 'pending-audit';
+  } else {
+    audit = 'audited';
+  }
+  if (!AUDIT_STATUSES.has(audit)) throw new Error(`${parsed.key} has invalid audit status "${audit}"`);
+  const negativeTests = override.negativeTests === undefined
+    ? (stateChanging && request.body.policy !== 'none' ? [defaultPendingNegativeTest()] : [])
+    : cloneSerializable(override.negativeTests);
+  if (!Array.isArray(negativeTests)) throw new Error(`${parsed.key} negativeTests must be an array`);
+  const contract = {
+    ...parsed,
+    owner,
+    audit,
+    stateChanging,
+    noInput,
+    request,
+    negativeTests,
+  };
+  if (noInput) {
+    contract.noInputReason = override.noInputReason
+      || (stateChanging
+        ? 'The action is selected by its fixed route and accepts no caller-supplied input.'
+        : 'This route consumes no caller-supplied body, path, query, or header input.');
+  }
+  if (stateChanging && request.body.policy === 'none' && !request.body.rationale) {
+    throw new Error(`${parsed.key} must explain why it accepts no request body`);
+  }
+  if (stateChanging && request.body.policy !== 'none' && negativeTests.length === 0) {
+    throw new Error(`${parsed.key} must declare a negative-test strategy`);
+  }
+  return contract;
+}
+
+function collectUniqueRouteKeys(owner, routes) {
+  const routeKeys = new Set();
+  for (const route of routes) {
+    const routeKey = canonicalRouteKey(route);
+    if (routeKeys.has(routeKey)) {
+      throw new Error(`${owner} lists duplicate route: ${routeKey}`);
+    }
+    routeKeys.add(routeKey);
+  }
+  return routeKeys;
+}
+
+function buildCatalog(ownerModules = OWNER_MODULES) {
+  const catalog = new Map();
+  for (const moduleContract of ownerModules) {
+    const owner = String(moduleContract.owner || '').trim();
+    if (!owner || !OWNERS.includes(owner)) throw new Error(`Invalid API contract owner "${owner}"`);
+    const routes = Array.isArray(moduleContract.routes) ? moduleContract.routes : [];
+    const bodyless = new Set((moduleContract.bodyless || []).map(canonicalRouteKey));
+    const overrides = moduleContract.overrides || {};
+    const normalizedOverrides = new Map(
+      Object.entries(overrides).map(([routeKey, override]) => [canonicalRouteKey(routeKey), override]),
+    );
+    // Detect same-owner duplicates in the normalized sequence BEFORE deduping.
+    // Collapsing the module's route list into a Set first would silently swallow
+    // a route listed twice by the same owner, so the cross-owner `catalog.has`
+    // guard below would never see it and the advertised one-to-one contract gate
+    // would only catch cross-owner collisions.
+    const routeKeys = new Set();
+    for (const routeKey of routes.map(canonicalRouteKey)) {
+      if (routeKeys.has(routeKey)) {
+        throw new Error(`${owner} lists duplicate API contract key: ${routeKey}`);
+      }
+      routeKeys.add(routeKey);
+    }
+    for (const bodylessKey of bodyless) {
+      if (!routeKeys.has(bodylessKey)) throw new Error(`${owner} bodyless route is not catalogued: ${bodylessKey}`);
+    }
+    for (const overrideKey of normalizedOverrides.keys()) {
+      if (!routeKeys.has(overrideKey)) {
+        throw new Error(`${owner} override route is not catalogued: ${overrideKey}`);
+      }
+    }
+    for (const routeKey of routeKeys) {
+      if (catalog.has(routeKey)) throw new Error(`Duplicate API contract key: ${routeKey}`);
+      const override = normalizedOverrides.get(routeKey) || {};
+      catalog.set(routeKey, buildRouteContract(owner, routeKey, bodyless, override));
+    }
+  }
+  return catalog;
+}
+
+const ROUTE_CONTRACTS = buildCatalog();
+
+function getRouteContract(route) {
+  const key = canonicalRouteKey(route);
+  return ROUTE_CONTRACTS.get(key) || null;
+}
+
+function listRouteContracts() {
+  return [...ROUTE_CONTRACTS.values()].map(cloneSerializable);
+}
+
+function routeContractMetadata(route) {
+  const contract = getRouteContract(route);
+  if (!contract) throw new Error(`Missing route contract: ${canonicalRouteKey(route)}`);
+  return cloneSerializable({
+    key: contract.key,
+    owner: contract.owner,
+    audit: contract.audit,
+    noInput: contract.noInput,
+    ...(contract.noInputReason ? { noInputReason: contract.noInputReason } : {}),
+    request: contract.request,
+    negativeTests: contract.negativeTests,
+  });
+}
+
+function assertRouteContractCoverage(routes, options = {}) {
+  if (!Array.isArray(routes)) throw new Error('Route registry must be an array');
+  const exact = options.exact !== false;
+  const requireAudited = options.requireAudited === true;
+  const seen = new Set();
+  for (const route of routes) {
+    const key = canonicalRouteKey(route);
+    if (seen.has(key)) throw new Error(`Duplicate route key in live registry: ${key}`);
+    seen.add(key);
+    if (!ROUTE_CONTRACTS.has(key)) throw new Error(`Missing route contract for live route: ${key}`);
+  }
+  if (exact) {
+    const extras = [...ROUTE_CONTRACTS.keys()].filter(key => !seen.has(key));
+    if (extras.length) throw new Error(`Contract catalog contains routes missing from live registry: ${extras.join(', ')}`);
+  }
+  if (requireAudited) {
+    for (const key of seen) assertRouteAuditClosure(ROUTE_CONTRACTS.get(key));
+  }
+  return true;
+}
+
+// Enforce audited-route closure for a single contract. A route is only allowed
+// through the tightened gate when its caller-supplied input surface has been
+// fully described:
+//   - no location may remain `pending-audit`;
+//   - every declared alias must document its canonical target;
+//   - a state-changing route must publish an explicit body policy plus a
+//     side-effect assertion (a negative-test strategy when it consumes input, or
+//     a bodyless rationale when it does not).
+function assertRouteAuditClosure(contract) {
+  if (!contract) throw new Error('Cannot certify a missing route contract');
+  const key = contract.key;
+  if (contract.audit !== 'audited') {
+    throw new Error(`Route ${key} is still ${contract.audit}; every route must be audited before release`);
+  }
+  for (const location of ['body', 'path', 'query', 'headers']) {
+    const policy = contract.request[location].policy;
+    if (policy === 'pending-audit') {
+      throw new Error(`Route ${key} leaves its ${location} input surface pending-audit`);
+    }
+  }
+  for (const alias of contract.request.aliases) {
+    if (!alias || typeof alias !== 'object'
+        || !String(alias.name || '').trim()
+        || !String(alias.canonical || '').trim()) {
+      throw new Error(`Route ${key} declares an undocumented alias (name and canonical are required)`);
+    }
+  }
+  if (contract.stateChanging) {
+    if (contract.request.body.policy === 'none') {
+      if (!contract.request.body.rationale) {
+        throw new Error(`Route ${key} is state-changing and must document its bodyless side-effect policy`);
+      }
+    } else if (contract.negativeTests.length === 0) {
+      throw new Error(`Route ${key} is state-changing and must declare a negative-test strategy`);
+    }
+  }
+  return true;
+}
+
+// Assert full audited-route closure across a live registry: coverage
+// (one-to-one, no duplicates, no gaps) plus per-route audit certification.
+function assertAuditedRouteClosure(routes, options = {}) {
+  return assertRouteContractCoverage(routes, { ...options, requireAudited: true });
+}
+
+// Runtime-derived contract counts. Never cache — the gate and verification guide
+// must reflect the live catalog so a regressed route is visible immediately.
+function summarizeRouteContracts() {
+  const contracts = [...ROUTE_CONTRACTS.values()];
+  const byOwner = {};
+  for (const owner of OWNERS) byOwner[owner] = 0;
+  let audited = 0;
+  let pendingAudit = 0;
+  let stateChanging = 0;
+  let readOnly = 0;
+  let noInput = 0;
+  for (const contract of contracts) {
+    byOwner[contract.owner] = (byOwner[contract.owner] || 0) + 1;
+    if (contract.audit === 'audited') audited += 1; else pendingAudit += 1;
+    if (contract.stateChanging) stateChanging += 1; else readOnly += 1;
+    if (contract.noInput) noInput += 1;
+  }
+  return {
+    total: contracts.length,
+    audited,
+    pendingAudit,
+    stateChanging,
+    readOnly,
+    noInput,
+    byOwner,
+  };
+}
+
+// Derive the human-readable side-effect assertion for a contract. Read-only
+// routes assert no mutation; state-changing routes assert their guard posture
+// (bodyless rationale or the ordered validate-before-side-effect constraints).
+function sideEffectAssertion(contract) {
+  if (!contract.stateChanging) {
+    return { mutates: false, assertion: 'Read-only; no persistent side effects.' };
+  }
+  if (contract.request.body.policy === 'none') {
+    return {
+      mutates: true,
+      assertion: contract.request.body.rationale
+        || 'State-changing; accepts no request body.',
+    };
+  }
+  const guards = contract.request.constraints
+    .map(constraint => constraint.kind || constraint.rule)
+    .filter(Boolean);
+  const guardText = guards.length
+    ? `Guarded by ${guards.length} constraint(s): ${guards.join(', ')}.`
+    : '';
+  return {
+    mutates: true,
+    assertion: `State-changing; rejects invalid input before side effects. ${guardText}`.trim(),
+  };
+}
+
+// Collect the "contract source" references a route derives its validation from:
+// allowed-value sources, shape sources, and named constraint kinds. Static
+// allowedValues arrays are surfaced separately so the matrix distinguishes a
+// live source reference from a frozen enum.
+function contractSources(contract) {
+  const sources = new Set();
+  for (const location of ['body', 'path', 'query', 'headers']) {
+    for (const field of contract.request[location].fields) {
+      if (field.allowedValuesSource) sources.add(field.allowedValuesSource);
+      if (field.shapeSource) sources.add(field.shapeSource);
+      if (field.defaultSource) sources.add(field.defaultSource);
+    }
+  }
+  for (const constraint of contract.request.constraints) {
+    if (constraint.kind) sources.add(constraint.kind);
+    else if (constraint.rule) sources.add(constraint.rule);
+  }
+  return [...sources];
+}
+
+// Build the route-to-validation matrix from the live catalog. Every row records
+// method/path, owner, accepted inputs, contract source, negative cases, status
+// mapping, and the side-effect assertion — the shape consumed by the plan
+// verification guide. Counts and rows derive at call time, never from a cache.
+function buildRouteValidationMatrix(routes) {
+  if (routes !== undefined) assertAuditedRouteClosure(routes);
+  const rows = [...ROUTE_CONTRACTS.values()].map(contract => {
+    const acceptedInputs = {};
+    for (const location of ['body', 'path', 'query', 'headers']) {
+      const input = contract.request[location];
+      acceptedInputs[location] = {
+        policy: input.policy,
+        fields: input.fields.map(field => field.name),
+      };
+    }
+    const negativeStatuses = [...new Set(
+      contract.negativeTests.map(test => test.expectedStatus).filter(Boolean),
+    )];
+    return {
+      key: contract.key,
+      method: contract.method,
+      path: contract.path,
+      owner: contract.owner,
+      audit: contract.audit,
+      acceptedInputs,
+      contractSource: contractSources(contract),
+      negativeCases: cloneSerializable(contract.negativeTests),
+      statusMapping: {
+        success: contract.stateChanging ? '2xx' : '200',
+        rejections: negativeStatuses,
+      },
+      sideEffect: sideEffectAssertion(contract),
+    };
+  });
+  rows.sort((a, b) => a.key.localeCompare(b.key));
+  return {
+    generatedFrom: 'engine/api-contracts live catalog',
+    summary: summarizeRouteContracts(),
+    rows,
+  };
+}
+
+module.exports = {
+  OWNERS,
+  canonicalRouteKey,
+  collectUniqueRouteKeys,
+  getRouteContract,
+  listRouteContracts,
+  routeContractMetadata,
+  assertRouteContractCoverage,
+  assertRouteAuditClosure,
+  assertAuditedRouteClosure,
+  summarizeRouteContracts,
+  buildRouteValidationMatrix,
+  // exported for testing — lets same-owner duplicate detection and default
+  // certification be exercised against synthetic ownership modules. Both names
+  // resolve to the same builder (`_buildCatalog` retained for existing callers).
+  buildCatalog,
+  _buildCatalog: buildCatalog,
+};