@bongos/core 1.17.0

package/scripts/gds/migration-namespace.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+'use strict';
+// migration-namespace.js — cross-repo migration numbering discipline (ADR 0108 §5,
+// configurable-root W5 / task 1885). Pure helpers, no fs/git — trivially testable.
+//
+// PROBLEM. Once the Cloud Bongos core is a pinned npm dependency (ADR 0108), the core
+// repo and the instance repo version INDEPENDENTLY. Each allocates its next migration
+// number by scanning its OWN migrations/ dir (next-number.js: max+1). With a single
+// shared bare `NNN_` namespace they would both pick the SAME "next" (e.g. both 188).
+// migrate.sh keys schema_migrations by the filename STEM (basename minus .sql), so two
+// same-stemmed migrations from different repos are seen as ONE — the second is silently
+// skipped and NEVER applied. That silent-skip is the collision this module prevents.
+//
+// DISCIPLINE. Every migration SOURCE owns a distinct filename namespace, so stems can
+// never collide across sources and each source's allocator counts only its own numbers:
+//   • CORE      (the @cloudbongos/core package's  migrations/*.sql)        → core_NNN_slug.sql
+//   • MODULE    (modules/<key>/migrations/*.sql)                           → <key>_NNN_slug.sql   (key: dev-box → dev_box_)
+//   • INSTANCE  (the host repo's                   migrations/instance/*.sql) → NNN_slug.sql        (BARE — the instance owns the bare namespace)
+//
+// The core prefix ALONE is enough to break stem-equality with a bare instance file
+// (`core_188_x` ≠ `188_x`), so the instance keeps the zero-ceremony bare form its seeds
+// already use. Modules were already `<key>_`-prefixed by convention (economy_001_,
+// lifecycle_001_); this makes it a rule for NEW module migrations.
+//
+// GRANDFATHER. Every migration that existed when this discipline landed (task 1885) is
+// bare and already recorded in schema_migrations by its bare stem — renaming one would
+// make migrate.sh re-run it (a from-scratch replay must still match history). So existing
+// bare files are grandfathered and the rule applies only to NEW migrations: a bare CORE
+// file numbered above LEGACY_BARE_CORE_MAX, or a bare migration in a non-legacy MODULE.
+// New prefixed files sort AFTER the legacy block (a letter sorts after a digit in the
+// basename merge-sort), which is the correct "newer applies later" order.
+//
+// ORDER OF APPLICATION (migrate.sh). Core + instance are merge-sorted by basename, so all
+// `core_*` files apply before all bare instance files (and before instance's own new
+// files). That matches the only real dependency direction — instance seeds read core
+// schema, never the reverse. Modules apply in their own later pass, keyed by stem.
+
+// ---- namespaces ------------------------------------------------------------
+
+const CORE_NS = 'core';
+const INSTANCE_NS = 'instance';
+// Reserved namespace words a module key may not be (they name the core/instance sources).
+const RESERVED_NS = new Set([CORE_NS, INSTANCE_NS]);
+
+// SQL/filename-safe namespace prefix for a module key: dev-box → dev_box (matches
+// fitness.js moduleNamespace + the existing economy_/lifecycle_ files).
+function sqlNamespace(moduleKey) {
+  return String(moduleKey == null ? '' : moduleKey).replace(/-/g, '_');
+}
+
+// Highest bare-numbered CORE migration when the discipline landed (W5 / task 1885). New
+// core migrations are `core_`-prefixed, so no bare core file can ever exceed this — the
+// cutoff never advances. Bare core files ≤ this are legacy (already applied) and allowed.
+const LEGACY_BARE_CORE_MAX = 187;
+
+// Modules whose migrations predate the `<key>_` filename convention (bare NNN_). New
+// module migrations must be `<key>_`-prefixed; these stay bare (already applied on prod).
+const LEGACY_BARE_MODULES = new Set(['game', 'demo']);
+
+// ---- parsing ---------------------------------------------------------------
+
+const BARE_RE = /^(\d{3,})_(.+)\.sql$/;
+// A prefix is a lowercase word (letters/digits/underscores) starting with a letter,
+// then `_NNN_`. Lazy so `dev_box_003_x` splits as prefix=dev_box, num=003 (not dev/box).
+const PREFIXED_RE = /^([a-z][a-z0-9_]*?)_(\d{3,})_(.+)\.sql$/;
+
+// Parse a migration basename into { prefix, number, slug, bare, ok }. A non-migration
+// name (README, .keep, a .txt) returns { ok: false }. Bare files (leading digit) parse
+// with prefix=null; prefixed files carry their namespace prefix.
+function parseMigrationName(basename) {
+  const s = String(basename == null ? '' : basename);
+  let m = BARE_RE.exec(s);
+  if (m) return { prefix: null, number: parseInt(m[1], 10), slug: m[2], bare: true, ok: true };
+  m = PREFIXED_RE.exec(s);
+  if (m) return { prefix: m[1], number: parseInt(m[2], 10), slug: m[3], bare: false, ok: true };
+  return { prefix: null, number: null, slug: null, bare: false, ok: false };
+}
+
+// The migration number in a basename (bare or prefixed), or null if not a migration.
+function migrationNumberOf(basename) {
+  const p = parseMigrationName(basename);
+  return p.ok ? p.number : null;
+}
+
+// ---- filename discipline ---------------------------------------------------
+
+const pad3 = (n) => String(n).padStart(3, '0');
+
+// For ONE migration file, return a violation string or null. `source` is one of
+// 'core' | 'instance' | 'module'; for 'module' pass { moduleKey }.
+function filenameViolation(source, basename, { moduleKey } = {}) {
+  const p = parseMigrationName(basename);
+  if (!p.ok) return null; // not a migration file — ignore (a .keep, a README)
+
+  if (source === CORE_NS) {
+    if (p.bare) {
+      return p.number > LEGACY_BARE_CORE_MAX
+        ? `core migration "${basename}" is bare — a NEW core migration must be ${CORE_NS}_-prefixed so its stem can't collide with an instance/module migration across repos (ADR 0108 §5): use ${CORE_NS}_${pad3(p.number)}_${p.slug}.sql`
+        : null; // legacy bare core ≤ cutoff — grandfathered (already applied)
+    }
+    return p.prefix === CORE_NS
+      ? null
+      : `core migration "${basename}" carries the "${p.prefix}_" prefix — core migrations must be ${CORE_NS}_-prefixed (ADR 0108 §5).`;
+  }
+
+  if (source === INSTANCE_NS) {
+    // The instance owns the BARE namespace; an explicit instance_ prefix is also fine.
+    if (p.bare || p.prefix === INSTANCE_NS) return null;
+    return `instance migration "${basename}" carries the "${p.prefix}_" prefix — instance migrations stay bare (NNN_) or use the ${INSTANCE_NS}_ prefix; "${p.prefix}_" is another source's namespace (ADR 0108 §5).`;
+  }
+
+  // module
+  const ns = sqlNamespace(moduleKey);
+  if (p.bare) {
+    return LEGACY_BARE_MODULES.has(moduleKey)
+      ? null // legacy bare module — grandfathered
+      : `module "${moduleKey}" migration "${basename}" is bare — a NEW module migration must be ${ns}_-prefixed (ADR 0083 §Decision #5 / ADR 0108 §5): use ${ns}_${pad3(p.number)}_${p.slug}.sql`;
+  }
+  return p.prefix === ns
+    ? null
+    : `module "${moduleKey}" migration "${basename}" carries the "${p.prefix}_" prefix — it must be ${ns}_-prefixed to its own module (ADR 0083 §Decision #5).`;
+}
+
+// ---- cross-root stem-collision detector ------------------------------------
+
+// A stem shared by migrations from ≥2 sources is the silent-skip hazard: migrate.sh
+// applies the first and skips the rest (schema_migrations is stem-keyed). Given a flat
+// list of { source, moduleKey?, basename }, return [{ stem, files:[label/basename,…] }]
+// for every stem produced by more than one distinct source-file.
+function stemCollisions(files) {
+  const byStem = new Map();
+  for (const f of files || []) {
+    if (!parseMigrationName(f.basename).ok) continue;
+    const stem = f.basename.replace(/\.sql$/, '');
+    const label = f.source === 'module' ? `module:${f.moduleKey}` : f.source;
+    if (!byStem.has(stem)) byStem.set(stem, new Set());
+    byStem.get(stem).add(`${label}/${f.basename}`);
+  }
+  const out = [];
+  for (const [stem, set] of byStem) {
+    if (set.size > 1) out.push({ stem, files: [...set].sort() });
+  }
+  return out.sort((a, b) => a.stem.localeCompare(b.stem));
+}
+
+// ---- numbering / lineage (mirrors the public-mirror pattern) ---------------
+
+// next free = max + 1; empty starts at `start` (same shape as next-number.js nextFree,
+// re-implemented here so this module stays dependency-free — it is imported by fitness.js
+// on every CI run and by next-number.js, so a require cycle must not form).
+function _nextFree(numbers, start = 1) {
+  let max = -Infinity;
+  for (const n of numbers) if (n > max) max = n;
+  return max === -Infinity ? start : max + 1;
+}
+
+// The next free migration number WITHIN a namespace, from that namespace's basenames.
+function nextInNamespace(basenames) {
+  return _nextFree((basenames || []).map(migrationNumberOf).filter((n) => n != null));
+}
+
+// A lineage report over the three sources: the next free number each source would
+// allocate, plus any cross-root stem collision. Reuses the public-mirror numbering
+// approach (mirror-lineage-check.js) — independent allocators are safe iff the sources
+// are namespaced (so stems can't collide) even when their NUMBERS overlap.
+function lineageReport({ core = [], instance = [], modulesByKey = {} } = {}) {
+  const files = [
+    ...core.map((basename) => ({ source: CORE_NS, basename })),
+    ...instance.map((basename) => ({ source: INSTANCE_NS, basename })),
+    ...Object.entries(modulesByKey).flatMap(([moduleKey, names]) =>
+      (names || []).map((basename) => ({ source: 'module', moduleKey, basename }))),
+  ];
+  const violations = files
+    .map((f) => filenameViolation(f.source, f.basename, { moduleKey: f.moduleKey }))
+    .filter(Boolean);
+  return {
+    nextCore: nextInNamespace(core),
+    nextInstance: nextInNamespace(instance),
+    nextByModule: Object.fromEntries(
+      Object.entries(modulesByKey).map(([k, names]) => [k, nextInNamespace(names)])),
+    collisions: stemCollisions(files),
+    violations,
+    consistent: violations.length === 0 && stemCollisions(files).length === 0,
+  };
+}
+
+module.exports = {
+  CORE_NS,
+  INSTANCE_NS,
+  RESERVED_NS,
+  LEGACY_BARE_CORE_MAX,
+  LEGACY_BARE_MODULES,
+  sqlNamespace,
+  parseMigrationName,
+  migrationNumberOf,
+  filenameViolation,
+  stemCollisions,
+  nextInNamespace,
+  lineageReport,
+};

package/scripts/gds/mirror-lineage-check.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/mirror-lineage-check.js — the C9 PROOF: private⇄public lineage
+// consistency + a no-leak check (GDS-V4 · V4.R73 · task 1212, implementing the
+// ADR 0099 "Consequences" recipe).
+//
+// C9 (Cloud Bongos ⇄ Amazonprimea decoupling) publishes a redacted, 6-month-
+// delayed public mirror of the private build repo (task 1211, scripts/public-
+// mirror-export.js). This check asserts the two lineages can't silently diverge:
+//
+//   1. NO-LEAK / NO-TOPOLOGY — redact the whole publishable tree exactly as the
+//      export does (mirror-redact + secret-scrub, via the SHARED redactBlob) and
+//      assert ZERO residual instance literals, public IPs, or secrets survive.
+//      Same detector the export gates on — "one detector, two consumers."
+//   2. MIGRATION NUMBERING — the set of core migrations/NNN_*.sql numbers that
+//      reach the mirror is IDENTICAL to the private set (redaction never renames
+//      a file), so the claim-time next-number allocator computes the SAME next
+//      migration on both sides. A dropped/renumbered migration = divergence = fail.
+//   3. ENUM VALUES — for every publishable migration, the CHECK (... IN (...))
+//      value-lists are byte-identical before and after redaction. Redaction may
+//      touch a domain in a comment; it must NEVER alter a schema enum value.
+//
+// TWO MODES:
+//   • default (simulation) — proves the invariant against the CURRENT tree. This
+//     is the live C9 acceptance while the repo is younger than the 180-day publish
+//     lag (the export is a deliberate no-op until then, so there is no mirror yet).
+//   • --mirror <dir> — the live check once the pipeline is publishing: reads the
+//     mirror's .mirror-provenance.json, asserts source_commit is an ancestor of
+//     private main, then diffs the mirror's migrations/enums against that commit
+//     and no-leak-scans the mirror's actual files.
+//
+// Exit 0 = consistent + clean; 1 = divergence or a residual leak; 2 = bad usage.
+// Pure helpers (parseEnumChecks / migrationNumbersFromPaths / numberingDivergence
+// / enumDrift) are exported for tests/mirror_lineage_proof.mjs.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const { isPublishable } = require(path.join(REPO_ROOT, 'scripts/gds/publish-manifest.js'));
+const {
+  buildRedactionRules, collectSensitiveLiterals, redactText, findLeaks,
+} = require(path.join(REPO_ROOT, 'scripts/gds/mirror-redact.js'));
+const { isBinary } = require(path.join(REPO_ROOT, 'scripts/public-mirror-export.js'));
+const { scrubSecrets, collectEnvSecrets, SECRET_PATTERNS } = require(path.join(REPO_ROOT, 'modules/security/secret-scrub.js'));
+const { nextFree } = require(path.join(REPO_ROOT, 'scripts/gds/next-number.js'));
+
+// Known secret SHAPES as NON-GLOBAL clones. We scan each file with .test(), and a
+// `/g` regex carries lastIndex state across .test() calls — reused in a loop over
+// files that makes the result order-dependent (the exact footgun that leaves the
+// export's own findSecretLeak evaluation-order-sensitive; task 1212 flagged it,
+// see docs/reviews/gds-v4-c9-lineage-proof.md). Stateless clones keep this proof
+// deterministic regardless of file order.
+const KNOWN_SECRET_SHAPES = SECRET_PATTERNS.map((re) => new RegExp(re.source, re.flags.replace('g', '')));
+
+// Core migrations are migrations/NNN_slug.sql (3+ digit prefix). Module migrations
+// live under modules/<key>/migrations/ and are numbered independently — the
+// claim-time allocator only reads the core dir, so only core numbering can diverge.
+const MIGRATION_BASENAME_RE = /^(\d{3,})_.*\.sql$/;
+
+// ---- pure helpers (exported for tests) ------------------------------------
+
+// The set of CORE migration numbers among a list of repo-relative paths.
+function migrationNumbersFromPaths(paths) {
+  const out = new Set();
+  for (const p of paths || []) {
+    const s = String(p);
+    if (!s.startsWith('migrations/')) continue; // core dir only
+    const m = MIGRATION_BASENAME_RE.exec(s.split('/').pop());
+    if (m) out.add(parseInt(m[1], 10));
+  }
+  return out;
+}
+
+// Extract the enum value-lists from a migration's SQL: every `IN ( '...' , ... )`
+// clause's quoted literals. Returns a deterministic (sorted) structure so it can
+// be deep-compared before/after redaction. Non-enum `IN (...)` (a subquery with
+// no string literals) contributes nothing. Robust to multi-line lists.
+function parseEnumChecks(sql) {
+  const lists = [];
+  if (typeof sql !== 'string') return lists;
+  const inRe = /\bIN\s*\(([^)]*)\)/gi;
+  let m;
+  while ((m = inRe.exec(sql)) !== null) {
+    const vals = m[1].match(/'((?:[^']|'')*)'/g) || [];
+    if (vals.length) lists.push([...vals].sort());
+  }
+  lists.sort((a, b) => (a.join('\u0000') < b.join('\u0000') ? -1 : a.join('\u0000') > b.join('\u0000') ? 1 : 0));
+  return lists;
+}
+
+// Compare two migration-number sets. { missing, extra, consistent }.
+function numberingDivergence(privateSet, mirrorSet) {
+  const priv = privateSet instanceof Set ? privateSet : new Set(privateSet);
+  const mir = mirrorSet instanceof Set ? mirrorSet : new Set(mirrorSet);
+  const missing = [...priv].filter((n) => !mir.has(n)).sort((a, b) => a - b);
+  const extra = [...mir].filter((n) => !priv.has(n)).sort((a, b) => a - b);
+  return { missing, extra, consistent: missing.length === 0 && extra.length === 0 };
+}
+
+// Which migrations had their enum value-lists changed by redaction. files:
+// [{ path, original, redacted }] → [{ path, before, after }].
+function enumDrift(files) {
+  const drift = [];
+  for (const f of files || []) {
+    const before = parseEnumChecks(f.original);
+    const after = parseEnumChecks(f.redacted);
+    if (JSON.stringify(before) !== JSON.stringify(after)) drift.push({ path: f.path, before, after });
+  }
+  return drift;
+}
+
+// ---- git plumbing (private repo = REPO_ROOT) ------------------------------
+function git(args) {
+  return execFileSync('git', ['-C', REPO_ROOT, ...args], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+}
+
+function buildRedactionContext() {
+  let branding = {};
+  try {
+    branding = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'config/branding.json'), 'utf8'));
+  } catch { /* vanilla instance — only the public-IP floor + secret scrub apply */ }
+  const extra = {
+    owners: String(process.env.OWNER_ALIASES || '').split(',').map((s) => s.trim()).filter(Boolean),
+    literals: process.env.DROPLET_IP ? [process.env.DROPLET_IP] : [],
+  };
+  return {
+    rules: buildRedactionRules(branding, extra),
+    sensitiveLiterals: collectSensitiveLiterals(branding, extra),
+    envSecrets: collectEnvSecrets(),
+  };
+}
+
+// Redact + scan ONE file the way the export publishes it, then check it for
+// residual leaks — DETERMINISTICALLY (no dependency on the export's evaluation-
+// order-sensitive findSecretLeak). Text files are redacted (instance literals +
+// IPs) then secret-scrubbed — those exact bytes are what the mirror would carry;
+// binary files ride verbatim but are still latin1-scanned. Returns
+// { redactedText|null, leaks:[{label,sample?}] }.
+function scanFile(buf, ctx) {
+  const { rules, sensitiveLiterals, envSecrets } = ctx;
+  let scanText;
+  let redactedText = null;
+  if (isBinary(buf)) {
+    scanText = buf.toString('latin1');
+  } else {
+    redactedText = scrubSecrets(redactText(buf.toString('utf8'), rules), envSecrets);
+    scanText = redactedText;
+  }
+  // Instance literals + public IPs (the topology/no-instance guarantee — findLeaks
+  // resets its own IP-regex lastIndex, so it is order-safe).
+  const leaks = findLeaks(scanText, sensitiveLiterals).map((l) => ({ label: l.label, sample: l.sample }));
+  // Any KNOWN secret shape surviving the scrub (stateless clones — see above).
+  for (const re of KNOWN_SECRET_SHAPES) {
+    if (re.test(scanText)) { leaks.push({ label: 'secret-shape' }); break; }
+  }
+  return { redactedText, leaks };
+}
+
+// The shared assertion core: given the publishable file set (as {path, buf}),
+// run the three checks. Returns a report.
+function proveLineage({ publishableFiles, privateMigrationNumbers, ctx }) {
+  const leaks = [];
+  const migFiles = [];
+  const mirrorNums = new Set();
+
+  for (const f of publishableFiles) {
+    const { redactedText, leaks: fileLeaks } = scanFile(f.buf, ctx);
+    for (const l of fileLeaks) leaks.push({ path: f.path, label: l.label, sample: l.sample });
+    if (f.path.startsWith('migrations/') && MIGRATION_BASENAME_RE.test(f.path.split('/').pop())) {
+      migFiles.push({ path: f.path, original: f.buf.toString('utf8'), redacted: redactedText != null ? redactedText : f.buf.toString('utf8') });
+      const mm = MIGRATION_BASENAME_RE.exec(f.path.split('/').pop());
+      mirrorNums.add(parseInt(mm[1], 10));
+    }
+  }
+
+  const numbering = numberingDivergence(privateMigrationNumbers, mirrorNums);
+  const drift = enumDrift(migFiles);
+  return {
+    leaks,
+    numbering,
+    nextPrivate: nextFree(privateMigrationNumbers),
+    nextMirror: nextFree(mirrorNums),
+    drift,
+    counts: { publishable: publishableFiles.length, migrations: migFiles.length },
+  };
+}
+
+// ---- mode: simulation (default) -------------------------------------------
+function runSimulation() {
+  const ctx = buildRedactionContext();
+  const tracked = git(['ls-files']).split('\n').map((s) => s.trim()).filter(Boolean);
+  const publishablePaths = tracked.filter(isPublishable);
+  const privateMigrationNumbers = migrationNumbersFromPaths(tracked);
+
+  const publishableFiles = [];
+  for (const p of publishablePaths) {
+    try {
+      publishableFiles.push({ path: p, buf: fs.readFileSync(path.join(REPO_ROOT, p)) });
+    } catch (err) {
+      // A tracked-but-unreadable file is itself a failure to surface.
+      publishableFiles.push({ path: p, buf: Buffer.from('') });
+      console.error(`[c9] could not read ${p}: ${err.message}`);
+    }
+  }
+  return proveLineage({ publishableFiles, privateMigrationNumbers, ctx });
+}
+
+// ---- mode: live (--mirror <dir>) ------------------------------------------
+function runAgainstMirror(mirrorDir) {
+  const ctx = buildRedactionContext();
+  const provPath = path.join(mirrorDir, '.mirror-provenance.json');
+  const prov = JSON.parse(fs.readFileSync(provPath, 'utf8'));
+  const sourceCommit = prov.source_commit;
+  if (!sourceCommit) throw new Error('.mirror-provenance.json has no source_commit');
+
+  // Lineage anchor: source_commit MUST be an ancestor of private main (HEAD here).
+  let ancestor = false;
+  try {
+    execFileSync('git', ['-C', REPO_ROOT, 'merge-base', '--is-ancestor', sourceCommit, 'HEAD'], { stdio: 'ignore' });
+    ancestor = true;
+  } catch { ancestor = false; }
+
+  // Private publishable migration numbers AT the source commit (the mirror is a
+  // redacted copy of exactly that commit's publishable tree).
+  const srcPaths = git(['ls-tree', '-r', '--name-only', sourceCommit]).split('\n').map((s) => s.trim()).filter(Boolean);
+  const privateMigrationNumbers = migrationNumbersFromPaths(srcPaths.filter(isPublishable));
+
+  // The mirror's ACTUAL files (already redacted) — scan them as-is for leaks +
+  // read migration enums straight off disk. We compare mirror migration numbers +
+  // enums to the source commit.
+  const walk = (dir, base = '') => {
+    const out = [];
+    for (const name of fs.readdirSync(dir)) {
+      if (name === '.git') continue;
+      const abs = path.join(dir, name);
+      const rel = base ? `${base}/${name}` : name;
+      if (fs.statSync(abs).isDirectory()) out.push(...walk(abs, rel));
+      else out.push({ path: rel, buf: fs.readFileSync(abs) });
+    }
+    return out;
+  };
+  const mirrorFiles = walk(mirrorDir).filter((f) => f.path !== '.mirror-provenance.json');
+
+  // The mirror is already redacted, so "redact again" is a no-op; redactBlob still
+  // gives us the leak scan. proveLineage compares mirror migration numbers to the
+  // source commit's publishable set and checks enum stability (idempotent here).
+  const report = proveLineage({ publishableFiles: mirrorFiles, privateMigrationNumbers, ctx });
+  report.ancestor = ancestor;
+  report.sourceCommit = sourceCommit;
+  return report;
+}
+
+// ---- report + exit --------------------------------------------------------
+function printReport(report, { mode }) {
+  const log = console.log;
+  log(`\nC9 lineage proof — ${mode}`);
+  log(`  publishable files: ${report.counts.publishable}   core migrations: ${report.counts.migrations}`);
+  if (report.sourceCommit) {
+    log(`  source_commit: ${String(report.sourceCommit).slice(0, 12)}  ancestor-of-main: ${report.ancestor ? 'YES' : 'NO'}`);
+  }
+
+  const ok = { leak: report.leaks.length === 0, numbering: report.numbering.consistent, enum: report.drift.length === 0, ancestor: report.ancestor !== false };
+
+  log('');
+  log(`  [${ok.leak ? '✓' : '✗'}] no-leak / no-topology   (${report.leaks.length} residual leak(s))`);
+  log(`  [${ok.numbering ? '✓' : '✗'}] migration numbering     (next: private=${report.nextPrivate} mirror=${report.nextMirror}; missing=[${report.numbering.missing.join(',')}] extra=[${report.numbering.extra.join(',')}])`);
+  log(`  [${ok.enum ? '✓' : '✗'}] enum values preserved   (${report.drift.length} migration(s) drifted)`);
+  if (report.sourceCommit) log(`  [${ok.ancestor ? '✓' : '✗'}] lineage anchor          (source_commit ancestor of private main)`);
+
+  if (!ok.leak) {
+    log('\n  Residual leaks (fix mirror-redact.js rules or publish-manifest.js exclusions):');
+    for (const l of report.leaks.slice(0, 30)) {
+      const shown = l.label === 'secret-shape' ? '' : (l.sample ? ` (“${String(l.sample).slice(0, 40)}”)` : '');
+      log(`    ${l.path}: ${l.label}${shown}`);
+    }
+    if (report.leaks.length > 30) log(`    … +${report.leaks.length - 30} more`);
+  }
+  if (!ok.numbering) log(`\n  Migration numbering DIVERGED — a migration was dropped/renamed on the way to the mirror.`);
+  if (!ok.enum) {
+    log('\n  Enum values were altered by redaction (they must be identical private⇄public):');
+    for (const d of report.drift.slice(0, 10)) log(`    ${d.path}`);
+  }
+
+  const pass = ok.leak && ok.numbering && ok.enum && ok.ancestor;
+  log(`\n${pass ? '✓ C9 lineage proof PASSED' : '✗ C9 lineage proof FAILED'} — private⇄public numbering + enums consistent, mirror clean.`);
+  return pass;
+}
+
+function main() {
+  const mIdx = process.argv.indexOf('--mirror');
+  const mirrorDir = mIdx >= 0 ? process.argv[mIdx + 1] : null;
+  try {
+    if (mirrorDir) {
+      const report = runAgainstMirror(path.resolve(mirrorDir));
+      process.exit(printReport(report, { mode: `live (mirror: ${mirrorDir})` }) ? 0 : 1);
+    }
+    const report = runSimulation();
+    process.exit(printReport(report, { mode: 'simulation (current tree — the dormant-repo acceptance)' }) ? 0 : 1);
+  } catch (err) {
+    console.error(`✖ C9 lineage proof error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  MIGRATION_BASENAME_RE,
+  migrationNumbersFromPaths,
+  parseEnumChecks,
+  numberingDivergence,
+  enumDrift,
+  proveLineage,
+  buildRedactionContext,
+  runSimulation,
+};