@bongos/core 1.18.0 → 1.18.18

package/scripts/gds/upgrade.js

@@ -194,6 +194,115 @@ function regenerateApiArtifacts({ instanceDir, coreRoot }, run = spawnSync, fsIm
   return { ok: true, ran };
 }
 
+// The instance's GITIGNORED WHOLE-FILE navigation docs (ADR 0110). On the monorepo these
+// regenerate at deploy (deploy-prod.sh) + box-fetch and are gitignored so no branch ever diffs
+// them. STANDALONE instances (ADR 0108) never got that step: their bespoke deploy regenerated
+// nothing and init/upgrade only did the API docs, so a fresh instance shipped with an empty docs/
+// and nothing kept the index live (task 1002314, the owner's "docs didn't transfer from primea").
+// This is the standalone sibling of deploy-prod.sh's regen: run the generator(s) against the
+// INSTANCE root, best-effort + LOUD — a broken generator must surface (::ERROR::) but must NEVER
+// fail the deploy/bump (a stale nav doc is tolerable; a failed deploy is not — ADR 0110 §2
+// "accepted staleness").
+//
+// SCOPE — deliberately just session-index (the one gitignored whole-file doc that is INSTANCE
+// content). Excluded on purpose:
+//   • repo-map.md — CORE-scoped: gen-repo-map writes to resolveCoreRoot() (the platform code map),
+//     not the instance. A pure standalone instance runs core from node_modules and has ~no code of
+//     its own to map, so an instance-level repo-map is empty/meaningless; the core ships its own.
+//     (An instance-scoped map for BROWNFIELD/adopted repos is a separate enhancement — task 1001655.)
+//   • file-map.md + API docs — TRACKED/committed (seeded at init, refreshed at ship/upgrade);
+//     regenerating them on the box would perpetually dirty the tree that deploy.sh `git reset
+//     --hard`es. file-map is also HYBRID (hand-written prose + generated sections, ADR 0110) so it
+//     cannot leave git; seeding it at standup is a follow-up (needs a scaffolded file-map.md).
+//   • diagrams + atlas.json — NOT instance content: they are CORE-scoped generated assets that
+//     live under resolveCoreRoot(). They are handled separately by healDocAssets() below, because
+//     an upgrade is precisely what destroys them (task 1002441).
+const NAV_WHOLE_FILE_GENERATORS = ['gen-session-index.js'];
+function regenerateNavDocs({ instanceDir, coreRoot, generators = NAV_WHOLE_FILE_GENERATORS }, run = spawnSync, fsImpl = fs) {
+  const env = { ...process.env, CLOUDBONGOS_INSTANCE_ROOT: instanceDir };
+  const ran = [];
+  const failed = [];
+  for (const gen of generators) {
+    const script = path.join(coreRoot, 'scripts', 'gds', gen);
+    if (!fsImpl.existsSync(script)) { failed.push({ gen, reason: `not found in core (${coreRoot})` }); continue; }
+    const r = run(process.execPath, [script], { cwd: instanceDir, env, stdio: 'inherit' });
+    if (!r || r.error || r.status !== 0) {
+      // LOUD per ADR 0110 §2 — journald greps ::ERROR:: so a broken generator alarms.
+      failed.push({ gen, reason: r && r.error ? r.error.message : `exited ${r && r.status}` });
+      continue;
+    }
+    ran.push(gen);
+  }
+  return { ok: failed.length === 0, ran, failed };
+}
+
+// The CORE-scoped generated doc assets that back two builders'-hall surfaces:
+//
+//   modules/hall-ui/public/atlas.json      → the Repo Atlas   (/builders/atlas)
+//   docs/onboarding/diagrams/<n>.svg+.png  → the system maps  (/builders/diagrams)
+//
+// Both are GITIGNORED (.gitignore: `modules/hall-ui/public/atlas.json`,
+// `docs/onboarding/diagrams/*.svg|*.png` — ADR 0122 / task 1002027) and both are generated INTO
+// the vendored core root. So an upgrade DESTROYS them: npmInstall replaces node_modules wholesale
+// and the new tarball carries only the .mmd sources. Nothing else puts them back —
+//   • packaging does not render (package-core.js has no render step, and the renders are
+//     gitignored so a git checkout has none to copy), and
+//   • a standalone instance's pull-deploy typically short-circuits on an unchanged git SHA, which
+//     an upgrade does not move — so its regen hooks never fire.
+// Result before this healer: /builders/atlas 404'd and the diagrams page showed broken images
+// after every `bongos upgrade`, until some unrelated commit happened to land (task 1002441).
+//
+// Both generators resolve their own output dir from __dirname, so running the CORE's copy always
+// writes into coreRoot regardless of cwd. Idempotent by design — each asset is regenerated only
+// when actually absent, so this is also safe to call from a deploy loop.
+//
+// Best-effort + LOUD, per ADR 0110 §2 "accepted staleness": a stale diagram is tolerable, a failed
+// upgrade is not. render-diagrams.sh additionally needs a system Chromium (ADR 0122); where none is
+// installed it fails and we say so via ::ERROR:: rather than aborting the bump.
+const DOC_ASSET_GENERATORS = {
+  atlas: { rel: path.join('scripts', 'gds', 'gen-atlas.js'), kind: 'node' },
+  diagrams: { rel: path.join('scripts', 'render-diagrams.sh'), kind: 'bash' },
+};
+
+// Which of the two asset groups are missing under coreRoot. Exported for testing.
+function missingDocAssets(coreRoot, fsImpl = fs) {
+  const missing = [];
+  if (!fsImpl.existsSync(path.join(coreRoot, 'modules', 'hall-ui', 'public', 'atlas.json'))) {
+    missing.push('atlas');
+  }
+  const diagramDir = path.join(coreRoot, 'docs', 'onboarding', 'diagrams');
+  let sources = [];
+  try {
+    sources = fsImpl.readdirSync(diagramDir).filter((f) => f.endsWith('.mmd'));
+  } catch { sources = []; }  // no diagram dir in this core → nothing to render
+  const unrendered = sources.some((src) => {
+    const base = path.join(diagramDir, src.replace(/\.mmd$/, ''));
+    return !fsImpl.existsSync(`${base}.svg`) || !fsImpl.existsSync(`${base}.png`);
+  });
+  if (unrendered) missing.push('diagrams');
+  return missing;
+}
+
+function healDocAssets({ coreRoot }, run = spawnSync, fsImpl = fs) {
+  const missing = missingDocAssets(coreRoot, fsImpl);
+  if (missing.length === 0) return { ok: true, ran: [], failed: [], missing: [] };
+  const ran = [];
+  const failed = [];
+  for (const group of missing) {
+    const gen = DOC_ASSET_GENERATORS[group];
+    const script = path.join(coreRoot, gen.rel);
+    if (!fsImpl.existsSync(script)) { failed.push({ group, reason: `not found in core (${gen.rel})` }); continue; }
+    const argv = gen.kind === 'bash' ? ['bash', [script]] : [process.execPath, [script]];
+    const r = run(argv[0], argv[1], { cwd: coreRoot, stdio: 'inherit' });
+    if (!r || r.error || r.status !== 0) {
+      failed.push({ group, reason: r && r.error ? r.error.message : `exited ${r && r.status}` });
+      continue;
+    }
+    ran.push(group);
+  }
+  return { ok: failed.length === 0, ran, failed, missing };
+}
+
 function restartService({ service, restartCmd }, run = spawnSync) {
   if (restartCmd) {
     const parts = restartCmd.split(/\s+/);
@@ -295,6 +404,91 @@ async function pollHealth(healthUrl, deps = {}) {
   }
 }
 
+// ---- integrity-pin verification (task 1002216 / audit H8, finding F1) --------
+// The packager (package-core.js) computes tree_sha256 = canonicalTreeHash over the
+// redacted core files (+ the two synthesized files) and records it, the per-file
+// hashes, AND the exact tarball bytes' sha256 in a side-car manifest — stating a
+// consumer "verifies an install by recomputing it from the unpacked tree." Until now
+// nothing on the CONSUME side did: `bongos upgrade` compared only the version STRING,
+// so a corrupted / truncated / swapped tarball whose package.json still read the target
+// version installed silently — the R88-class failure this goal exists to prevent.
+// The three functions below close that gap: recompute the pin over the INSTALLED tree
+// and assert it equals the TRUSTED reference manifest.
+
+// Read + parse a manifest JSON; null on any failure (missing / unparseable).
+function readManifest(file, fsImpl = fs) {
+  try { return JSON.parse(fsImpl.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+// Resolve the trusted reference pin for this bump:
+//   • VENDORED — the committed side-car `vendor/<artifact>-<v>.manifest.json` (carries
+//     tree_sha256 + files[] + the exact tarball.sha256). It lives OUTSIDE the tarball
+//     (version-controlled in the consumer repo), so it detects a swapped/corrupted
+//     tarball. This is the strong reference.
+//   • REGISTRY / no side-car — the inner manifest `<core>/.bongos-core.json` that ships
+//     INSIDE the package (tree_sha256 + files[], no tarball.*). Self-referential (a full
+//     swap regenerates it too), so it is a self-consistency check backing npm's own
+//     registry integrity rather than an independent one — flagged `strong:false`.
+function resolveReferenceManifest({ instanceDir, coreDir, targetVersion }, fsImpl = fs) {
+  const sidecarPath = path.join(instanceDir, 'vendor', `${ARTIFACT}-${targetVersion}.manifest.json`);
+  const sidecar = readManifest(sidecarPath, fsImpl);
+  if (sidecar && sidecar.tree_sha256) {
+    const tgz = path.join(instanceDir, 'vendor', `${ARTIFACT}-${targetVersion}.tgz`);
+    return { manifest: sidecar, tgzPath: fsImpl.existsSync(tgz) ? tgz : null, source: 'vendored side-car manifest', strong: true };
+  }
+  const inner = readManifest(path.join(coreDir, '.bongos-core.json'), fsImpl);
+  if (inner && inner.tree_sha256) return { manifest: inner, tgzPath: null, source: 'installed inner manifest', strong: false };
+  return { manifest: null, tgzPath: null, source: null, strong: false };
+}
+
+// Recompute the integrity pin over the installed core tree and compare to `referenceManifest`.
+// Reuses the PACKAGER's exact hash functions (canonicalTreeHash / sha256hex) so the consume-side
+// recompute can never drift from the produce-side pin. Returns { ran, ok, checks, problems };
+// ran=false ⇒ the manifest carried no pin to check against.
+function verifyInstalledPin({ coreDir, referenceManifest, tgzPath }, deps = {}) {
+  const fsImpl = deps.fs || fs;
+  const pc = deps.packageCore || require('./package-core');
+  const checks = [];
+  const problems = [];
+  if (!referenceManifest || !referenceManifest.tree_sha256) return { ran: false, ok: false, checks, problems };
+
+  // (a) exact tarball bytes (vendored path only) — the strongest single check: the bytes
+  //     npm actually installs, hashed and compared to the externally-held pin.
+  const tb = referenceManifest.tarball;
+  if (tgzPath && tb && tb.sha256 && fsImpl.existsSync(tgzPath)) {
+    const got = pc.sha256hex(fsImpl.readFileSync(tgzPath));
+    const ok = got === tb.sha256;
+    checks.push({ name: 'tarball.sha256', ok });
+    if (!ok) problems.push(`vendored tarball bytes sha256 ${got.slice(0, 12)}… ≠ pinned ${String(tb.sha256).slice(0, 12)}…`);
+  }
+
+  // (b) installed tree — recompute each pinned file's sha256 from the unpacked tree, rebuild
+  //     the canonical tree hash (using the manifest's already-canonical modes), assert equality.
+  //     Catches partial extraction, post-install corruption, or a registry package that diverged.
+  const files = Array.isArray(referenceManifest.files) ? referenceManifest.files : [];
+  if (files.length) {
+    const recomputed = [];
+    let missing = 0, changed = 0;
+    for (const f of files) {
+      const abs = path.join(coreDir, ...String(f.path).split('/')); // POSIX manifest path → native
+      let buf;
+      try { buf = fsImpl.readFileSync(abs); } catch { missing++; problems.push(`missing installed file: ${f.path}`); continue; }
+      const sha = pc.sha256hex(buf);
+      if (sha !== f.sha256) { changed++; problems.push(`content mismatch: ${f.path}`); }
+      recomputed.push({ path: f.path, mode: f.mode, sha256: sha });
+    }
+    const treeHash = pc.canonicalTreeHash(recomputed);
+    const ok = missing === 0 && changed === 0 && treeHash === referenceManifest.tree_sha256;
+    checks.push({ name: 'tree_sha256', ok, missing, changed, file_count: files.length });
+    if (!ok && missing === 0 && changed === 0) {
+      problems.push(`recomputed tree_sha256 ${treeHash.slice(0, 12)}… ≠ pinned ${String(referenceManifest.tree_sha256).slice(0, 12)}…`);
+    }
+  }
+
+  const ran = checks.length > 0;
+  return { ran, ok: ran && problems.length === 0, checks, problems };
+}
+
 // Auto-rollback (task 2149): a bump failed AFTER the pin was moved — an install or migrate
 // error, or a failed post-restart health check. Revert the code pin to the pre-upgrade
 // snapshot, reinstall the previous core, restart, re-verify health, and record the reversal
@@ -390,6 +584,18 @@ async function runUpgrade(opts, deps = {}) {
   log(`  ✓ pre-flight: ${mods.note}`);
   if (!mods.ok) return { ok: false, error: `module pre-check failed: ${mods.blocking.map((b) => b.key).join(', ')} incompatible with core ${targetVersion}` };
 
+  // 1b. mandatory post-restart health check (audit H9 / task 1002222, finding F5). A bump that
+  //     brings the new core live via a managed restart (--service / --restart-cmd) MUST confirm it
+  //     actually serves — an upgrade that can't be health-checked can't be reported as a success.
+  //     Enforced here in PRE-FLIGHT, before anything is mutated, so there is nothing to roll back:
+  //     if this bump will restart the service and the check isn't explicitly opted out, a
+  //     --health-url is required. (No managed restart ⇒ nothing is brought live here ⇒ the check
+  //     does not apply; the operator restarts + verifies separately.)
+  const willRestart = !!(opts.service || opts.restartCmd);
+  if (!dryRun && opts.healthCheck !== false && willRestart && !opts.healthUrl) {
+    return { ok: false, error: 'post-restart health check is mandatory for a bump that restarts the service, but no --health-url was given.\n  Pass --health-url <url> to confirm the new core serves after restart, or --no-health-check to explicitly skip the confirmation.' };
+  }
+
   // 2. bump the pin. Two mutually exclusive core sources (ADR 0134, task 2090):
   //    REGISTRY (--registry): pin @bongos/core@<version> + ensure the env-fed .npmrc, so
   //      the `npm install` below pulls the PRIVATE package from the registry (needs NPM_TOKEN).
@@ -429,6 +635,38 @@ async function runUpgrade(opts, deps = {}) {
   }
   log('  ✓ npm install');
 
+  // 3b. verify the integrity pin (audit H8 / task 1002216, finding F1). Recompute tree_sha256 over
+  //     the freshly-installed core (+ the exact vendored tarball bytes) and assert it matches the
+  //     TRUSTED reference manifest — the pin the packager produced but the consume side never
+  //     re-checked. Runs BEFORE migrate so a corrupted core can never touch the DB. A MISMATCH is
+  //     fatal → rollback (like an install/migrate failure). A MISSING reference (no side-car AND no
+  //     inner manifest) can't be verified: a warning by default, fatal only with --require-pin.
+  if (!opts.skipPinVerify) {
+    const coreDir = path.join(instanceDir, 'node_modules', CORE_PKG);
+    const ref = (deps.resolveReferenceManifest || resolveReferenceManifest)({ instanceDir, coreDir, targetVersion }, fsImpl);
+    if (!ref.manifest) {
+      const msg = `integrity pin: no reference manifest (looked for vendor/${ARTIFACT}-${targetVersion}.manifest.json and ${CORE_PKG}/.bongos-core.json) — cannot verify this install`;
+      if (opts.requirePin) {
+        const error = `${msg} (--require-pin)`;
+        if (rollbackOnFailure && snapshot) { const rb = await doRollback('integrity pin unverifiable (--require-pin)'); return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb }; }
+        return { ok: false, error, fromVersion };
+      }
+      err(`  ! ${msg} — pass --require-pin to treat this as fatal.`);
+    } else {
+      const pin = (deps.verifyInstalledPin || verifyInstalledPin)({ coreDir, referenceManifest: ref.manifest, tgzPath: ref.tgzPath }, deps);
+      if (!pin.ok) {
+        const detail = pin.problems.slice(0, 6).join('; ') + (pin.problems.length > 6 ? `; +${pin.problems.length - 6} more` : '');
+        const error = `integrity pin MISMATCH (${ref.source}) — installed core does not match its pin: ${detail}`;
+        if (rollbackOnFailure && snapshot) {
+          const rb = await doRollback('integrity pin mismatch');
+          return { ok: false, error, fromVersion, toVersion: targetVersion, rolledBack: true, rollback: rb };
+        }
+        return { ok: false, error, fromVersion };
+      }
+      log(`  ✓ integrity pin verified (${pin.checks.map((c) => c.name).join(' + ')}) against the ${ref.source}${ref.strong ? '' : ' — self-consistency check; npm registry integrity is the primary guard'}`);
+    }
+  } else log('  • integrity-pin verify skipped (--skip-pin-verify)');
+
   // 4. migrate (additive core_* migrations).
   if (!opts.skipMigrate) {
     const mig = runMigrate(instanceDir, run);
@@ -458,7 +696,20 @@ async function runUpgrade(opts, deps = {}) {
     const regen = (deps.regenerateApiArtifacts || regenerateApiArtifacts)({ instanceDir, coreRoot }, run);
     if (regen.ok) log(`  ✓ regenerated API docs + typed client from core ${targetVersion}`);
     else err(`  ! API-artifact regen incomplete (${regen.reason}) — ran ${regen.ran.join(', ') || 'nothing'}; the next ship's fitness gate refreshes them.`);
-  } else log('  • API-artifact regen skipped (--skip-regen-docs)');
+    // 5c. regenerate the whole-file navigation docs (repo-map + session-index) from the new
+    // core against the instance root (ADR 0110 / task 1002314). Best-effort + LOUD: a broken
+    // generator alarms via ::ERROR:: but never fails the bump.
+    const nav = (deps.regenerateNavDocs || regenerateNavDocs)({ instanceDir, coreRoot }, run);
+    if (nav.ok) log(`  ✓ regenerated navigation docs (${nav.ran.join(', ')}) from core ${targetVersion}`);
+    else err(`  ! ::ERROR:: navigation-doc regen incomplete — ran ${nav.ran.join(', ') || 'nothing'}; failed ${nav.failed.map((f) => `${f.gen} (${f.reason})`).join(', ')}. The next deploy retries.`);
+    // 5d. re-generate the CORE-scoped doc assets this very upgrade just wiped — the Repo Atlas
+    // data file + the onboarding diagram renders (task 1002441). See healDocAssets() for why
+    // nothing else puts them back. Best-effort + LOUD, same contract as 5c.
+    const heal = (deps.healDocAssets || healDocAssets)({ coreRoot }, run);
+    if (heal.missing.length === 0) log('  • doc assets intact (atlas + diagram renders present)');
+    else if (heal.ok) log(`  ✓ regenerated doc assets wiped by the core swap (${heal.ran.join(', ')})`);
+    else err(`  ! ::ERROR:: doc-asset regen incomplete — ran ${heal.ran.join(', ') || 'nothing'}; failed ${heal.failed.map((f) => `${f.group} (${f.reason})`).join(', ')}. /builders/atlas or /builders/diagrams may be broken until the next deploy retries (diagram renders need a system Chromium — ADR 0122).`);
+  } else log('  • doc regen skipped (--skip-regen-docs)');
 
   // 6. restart.
   const rs = restartService({ service: opts.service, restartCmd: opts.restartCmd }, run);
@@ -472,11 +723,17 @@ async function runUpgrade(opts, deps = {}) {
   log(`  ${versionOk ? '✓' : '!'} installed core version: ${installed || '(unknown)'}${versionOk ? '' : ` (expected ${targetVersion})`}`);
 
   let healthOk = null;
-  if (opts.healthUrl) {
+  if (opts.healthCheck === false) {
+    log('  • post-restart health check skipped (--no-health-check) — success is NOT confirmed against a live endpoint.');
+  } else if (opts.healthUrl) {
     const h = await pollHealth(opts.healthUrl, deps);
     healthOk = h.ok;
     if (h.ok) log(`  ✓ health ${opts.healthUrl} → ${h.status}${h.attempts > 1 ? ` (ready after ${h.attempts} tries)` : ''}`);
     else err(`  ! health ${opts.healthUrl} not ready after ${h.attempts} tr${h.attempts === 1 ? 'y' : 'ies'}: ${h.error || 'status ' + h.status}`);
+  } else {
+    // Reachable only when NO managed restart happened (pre-flight requires a URL when one will):
+    // the new core is installed on disk, but nothing was brought live here to health-check.
+    log('  • no managed restart + no --health-url — new core installed but not confirmed serving; restart the instance + health-check it to complete the bump.');
   }
 
   // A failed post-restart health check means the new core is serving broken — auto-revert (task
@@ -514,6 +771,9 @@ function parseArgs(argv) {
     skipMigrate: hasFlag('--skip-migrate', argv),
     skipMaterialize: hasFlag('--skip-materialize', argv),
     skipRegenDocs: hasFlag('--skip-regen-docs', argv),
+    skipPinVerify: hasFlag('--skip-pin-verify', argv), // task 1002216: opt out of the post-install integrity-pin check
+    requirePin: hasFlag('--require-pin', argv), // task 1002216: a MISSING reference manifest becomes fatal (not just a warning)
+    healthCheck: !hasFlag('--no-health-check', argv), // task 1002222: post-restart health check is ON by default (finding F5/H9)
     rollbackOnFailure: !hasFlag('--no-rollback-on-failure', argv), // ADR 0100: auto-revert ON by default (task 2149)
   };
 }
@@ -533,16 +793,19 @@ async function main(argv = process.argv.slice(2)) {
       '  --instance <dir>     consumer instance root (default: cwd)',
       '  --service <unit>     systemd unit to restart after applying',
       '  --restart-cmd <cmd>  explicit restart command (overrides --service)',
-      '  --health-url <url>   poll after restart (~30s) until 2xx; still-failing is a warning',
+      '  --health-url <url>   poll after restart (~30s) until 2xx; a still-failing check fails the bump (auto-rollback). REQUIRED for a bump that restarts the service, unless --no-health-check.',
+      '  --no-health-check    explicitly skip the post-restart health confirmation (default: the check is ON — a bump that restarts the service must confirm it serves)',
       '  --skip-migrate       do not run `npm run migrate`',
       '  --skip-materialize   do not refresh .claude/',
       '  --skip-regen-docs    do not regenerate the OpenAPI spec + typed client from the new core',
-      '  --no-rollback-on-failure  do NOT auto-revert on a failed install/migrate/health check (default: auto-rollback ON)',
+      '  --skip-pin-verify    do not verify the integrity pin (tree_sha256 + tarball.sha256) after install',
+      '  --require-pin        treat a MISSING reference manifest as fatal (default: warn — a MISMATCH is always fatal)',
+      '  --no-rollback-on-failure  do NOT auto-revert on a failed install/pin-verify/migrate/health check (default: auto-rollback ON)',
       '  --dry-run            show the plan; change nothing',
       '  --force              skip the clean-tree + same-version guards',
       '',
-      'Full bump: pre-flight → bump pin → npm install → migrate → materialize .claude → regen API docs+client → restart → verify.',
-      'On a failure after the pin moves (install/migrate/health), auto-rollback reverts the pin, reinstalls the previous core, restarts, and records a rolled_back ledger row (the DB is not rolled back — core migrations are additive).',
+      'Full bump: pre-flight → bump pin → npm install → verify integrity pin → migrate → materialize .claude → regen API docs+client → restart → verify.',
+      'On a failure after the pin moves (install/pin-verify/migrate/health), auto-rollback reverts the pin, reinstalls the previous core, restarts, and records a rolled_back ledger row (the DB is not rolled back — core migrations are additive).',
     ].join('\n') + '\n');
     return 0;
   }
@@ -559,7 +822,8 @@ async function main(argv = process.argv.slice(2)) {
 module.exports = {
   runUpgrade, parseArgs, main, rollback,
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
-  vendorTarball, gitTreeClean, preflightModules, npmInstall, runMigrate, regenerateApiArtifacts, restartService, recordLedger, pollHealth,
+  vendorTarball, gitTreeClean, preflightModules, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth,
+  readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
   CORE_PKG, ARTIFACT,
 };
 

package/scripts/migrate.sh

@@ -110,6 +110,16 @@ apply_migration() {
     >/dev/null
 }
 
+# --- Forward-safety notice (task 1002223 / audit H10) ---------------------
+# `bongos upgrade` auto-rollback reverts the code pin but NOT the DB — safe only if core migrations
+# are forward-safe (the PREVIOUS code still runs on the new schema). Surface — never block — any
+# UNACKNOWLEDGED forward-unsafe core migration so an operator knows a rollback past it would strand
+# old code on new schema. Fail-closed enforcement is the unit gate (tests/migrations_forward_safe.mjs);
+# here it is advisory (`|| true`) so a lint hiccup can NEVER break a deploy.
+if [ -f "$CORE_ROOT/scripts/gds/lint-migrations.js" ]; then
+  node "$CORE_ROOT/scripts/gds/lint-migrations.js" --warn --dir "$CORE_ROOT/migrations" || true
+fi
+
 # Build the ordered migration list and apply it as ONE numeric sequence by
 # filename stem, regardless of directory:
 #   $CORE_ROOT/migrations/*.sql              — core: schema + platform-universal seeds (EVERY instance).

package/scripts/status-mirror-sync.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // scripts/status-mirror-sync.js — publish the status surface to the off-box status
-// mirror (lars589/amazonprimea-status → GitHub Pages → status.amazonprimea.com).
+// mirror (a separate repo → a static Pages host → the instance's status domain).
 //
 // SOURCE PATH (BV1.R84 / task 1635): the status dashboard moved from public-status/
 // to modules/status-ui/public/ when the status surface became a module (a web
@@ -14,19 +14,28 @@
 // (that's how #726's reorg + #731's theming never showed up). This makes the
 // publish deterministic and CI-driven.
 //
+// CONFIG (task 1002510 — no host identity is baked in here; ADR 0062 §3):
+//   domains.publicOrigin  — the origin the mirror calls cross-origin
+//                           (window.STATUS_API_BASE), and the site label the
+//                           availability banner names as up/down.
+//   domains.statusDataUrl — the off-box prober's status.json URL the availability
+//                           banner reads. EMPTY ⇒ this instance runs no off-box
+//                           mirror, and the publish REFUSES rather than shipping a
+//                           page whose banner points nowhere.
+//
 // DESIGN: status.js + style.css + cursors/ are byte-identical between the
 // droplet copy and the mirror (#737 parameterized the one differing constant via
 // window.STATUS_API_BASE), so they are PURE COPIES. Only index.html carries the
 // three off-box additions, injected here at stable anchors:
-//   1. <script>window.STATUS_API_BASE='https://amazonprimea.com'</script>  (head)
-//   2. <div id="offbox-status">…</div>                                     (after <body>)
-//   3. the availability-banner driver <script> (reads the status-data branch)  (before status.js)
+//   1. <script>window.STATUS_API_BASE = <domains.publicOrigin></script>   (head)
+//   2. <div id="offbox-status">…</div>                                    (after <body>)
+//   3. the availability-banner driver <script> (reads domains.statusDataUrl) (before status.js)
 // If any anchor is missing the script THROWS — a silent mis-sync is worse than
 // a failed run.
 //
 // USAGE:
 //   node scripts/status-mirror-sync.js --repo-dir <path-to-mirror-checkout> [--push]
-//     --repo-dir : a checkout of lars589/amazonprimea-status (its `main` branch).
+//     --repo-dir : a checkout of the status-mirror repo (its `main` branch).
 //     --push     : commit + push the result. Without it the files are written
 //                  and `git status` is printed for inspection (dry-ish run).
 //
@@ -42,52 +51,36 @@ const SRC = path.join(REPO_ROOT, 'modules', 'status-ui', 'public');
 const { branding, clientBranding } = require('../src/branding');
 
 // Stamp instance-identity tokens into the mirror HTML. The off-box mirror is
-// served by GitHub Pages, NOT the branding-injecting Node server — so this script
-// must reproduce serve-internal.applyBrandTokens (task 1705, ADR 0062 §3), else the
-// mirror would render literal {{worldName}}/{{currency}} placeholders. KEEP IN SYNC
-// with src/bongos/serve-internal.js applyBrandTokens.
-function brandTokens(html) {
-  const b = clientBranding();
-  const world = (b.identity && b.identity.worldName) || '';
-  const product = (b.identity && b.identity.productName) || '';
-  const cur = (b.currency && b.currency.label) || 'credits';
+// served by a static Pages host, NOT the branding-injecting Node server — so this
+// script must reproduce serve-internal.applyBrandTokens (task 1705, ADR 0062 §3), else
+// the mirror would render literal {{worldName}}/{{currency}} placeholders. KEEP IN SYNC
+// with src/bongos/serve-internal.js applyBrandTokens. `brand` is the client-safe pack
+// and `publicOrigin` the resolved origin — both injected, never read ambiently, so the
+// transform stays pure and testable.
+function brandTokens(html, brand = {}, publicOrigin = '') {
+  const world = (brand.identity && brand.identity.worldName) || '';
+  const product = (brand.identity && brand.identity.productName) || '';
+  const cur = (brand.currency && brand.currency.label) || 'credits';
   const Cur = cur ? cur.charAt(0).toUpperCase() + cur.slice(1) : cur;
-  let origin = '';
-  try { origin = branding().domains.publicOrigin || ''; } catch (_) { /* neutral */ }
   return html
     .split('{{worldName}}').join(world)
     .split('{{productName}}').join(product)
     .split('{{Currency}}').join(Cur)
     .split('{{currency}}').join(cur)
-    .split('{{publicOrigin}}').join(origin);
-}
-
-function arg(name) {
-  const i = process.argv.indexOf(name);
-  return i >= 0 ? process.argv[i + 1] : null;
-}
-const repoDir = arg('--repo-dir');
-const doPush = process.argv.includes('--push');
-if (!repoDir) {
-  console.error('usage: node scripts/status-mirror-sync.js --repo-dir <mirror-checkout> [--push]');
-  process.exit(2);
-}
-if (!fs.existsSync(path.join(repoDir, 'CNAME'))) {
-  console.error(`refusing: ${repoDir} does not look like the status mirror (no CNAME). Clone lars589/amazonprimea-status first.`);
-  process.exit(2);
+    .split('{{publicOrigin}}').join(publicOrigin || '');
 }
 
 // ---- the three off-box index.html injections -------------------------------
 
-const HEAD_INJECT =
+const headInject = (apiBase) =>
   `  <!-- #737: off-box mirror runs cross-origin against the droplet. -->\n` +
-  `  <script>window.STATUS_API_BASE = 'https://amazonprimea.com';</script>\n`;
+  `  <script>window.STATUS_API_BASE = ${JSON.stringify(apiBase)};</script>\n`;
 
 // The client-safe branding pack, so status.js reads the instance currency label
 // on the mirror exactly as it does on the droplet (serve-internal injects the same
 // global there). Without this, status.js would fall back to the neutral 'credits'.
-const BRANDING_INJECT =
-  `  <script>window.__BRANDING__ = ${JSON.stringify(clientBranding())};</script>\n`;
+const brandingInject = (brand) =>
+  `  <script>window.__BRANDING__ = ${JSON.stringify(brand)};</script>\n`;
 
 const BANNER_DIV =
   `\n<!-- Off-box availability banner (ADR 0029) — injected by scripts/status-mirror-sync.js.\n` +
@@ -95,11 +88,17 @@ const BANNER_DIV =
   `     prober's status.json from this repo's status-data branch, no droplet dependency. -->\n` +
   `<div id="offbox-status" role="status" aria-live="polite"></div>\n`;
 
-const BANNER_DRIVER = `<!-- Off-box availability banner driver (ADR 0029) — loaded before status.js so
+// The banner names the site it is reporting on. Derived from the configured origin
+// so no hostname is baked in; a non-URL origin falls back to the raw string.
+function siteLabel(origin) {
+  try { return new URL(origin).host; } catch { return String(origin || ''); }
+}
+
+const bannerDriver = (statusDataUrl, label) => `<!-- Off-box availability banner driver (ADR 0029) — loaded before status.js so
      it lights up even if the dashboard script or its cross-origin fetches fail. -->
 <script>
 (function () {
-  var OFFBOX_URL = 'https://raw.githubusercontent.com/lars589/amazonprimea-status/status-data/status.json';
+  var OFFBOX_URL = ${JSON.stringify(statusDataUrl)};
   var el = document.getElementById('offbox-status');
   if (!el) return;
   function fmtUtc(iso) {
@@ -113,8 +112,8 @@ const BANNER_DRIVER = `<!-- Off-box availability banner driver (ADR 0029) — lo
       .then(function (res) { if (!res.ok) throw new Error('HTTP ' + res.status); return res.json(); })
       .then(function (data) {
         var cur = data && data.current, status = cur && cur.status, when = fmtUtc(cur && cur.t);
-        if (status === 'up') setState('up', '\\uD83D\\uDFE2 amazonprimea.com is operational \\u2014 checked ' + when);
-        else if (status === 'down') setState('down', '\\uD83D\\uDD34 amazonprimea.com is DOWN \\u2014 checked ' + when);
+        if (status === 'up') setState('up', '\\uD83D\\uDFE2 ${label} is operational \\u2014 checked ' + when);
+        else if (status === 'down') setState('down', '\\uD83D\\uDD34 ${label} is DOWN \\u2014 checked ' + when);
         else setState('unknown', 'status data is momentarily unavailable');
       })
       .catch(function () { setState('unknown', 'status data is momentarily unavailable'); });
@@ -134,59 +133,90 @@ function injectOnce(haystack, anchor, insertion, where) {
   return haystack.slice(0, idx + anchor.length) + insertion + haystack.slice(idx + anchor.length);
 }
 
-function buildIndexHtml() {
-  let html = fs.readFileSync(path.join(SRC, 'index.html'), 'utf8');
+// Pure: droplet index.html + resolved config → the mirror's index.html. No disk, no
+// network, no ambient branding read — everything the output depends on is a parameter.
+function buildMirrorIndex({ srcHtml, apiBase, statusDataUrl, brand }) {
+  if (!statusDataUrl) {
+    throw new Error('domains.statusDataUrl is empty — the off-box availability banner would point nowhere. Set domains.statusDataUrl (the prober\'s status.json URL) in the branding config, or do not publish a mirror for this instance.');
+  }
+  let html = String(srcHtml == null ? '' : srcHtml);
   if (html.includes('offbox-status')) {
     throw new Error('modules/status-ui/public/index.html already contains offbox markup — the source should be the droplet (no-banner) copy. Aborting.');
   }
-  html = injectOnce(html, '</head>', HEAD_INJECT + BRANDING_INJECT, 'before');
+  html = injectOnce(html, '</head>', headInject(apiBase) + brandingInject(brand), 'before');
   html = injectOnce(html, '<body>', BANNER_DIV, 'after');
   // Insert the driver right before the main status.js script tag.
   const scriptAnchor = '<script src="/status.js';
-  html = injectOnce(html, scriptAnchor, BANNER_DRIVER + '', 'before');
-  // Stamp the instance branding tokens LAST — GitHub Pages won't run the server's
+  html = injectOnce(html, scriptAnchor, bannerDriver(statusDataUrl, siteLabel(apiBase)), 'before');
+  // Stamp the instance branding tokens LAST — the Pages host won't run the server's
   // injection, so the mirror must resolve {{worldName}}/{{currency}}/… itself.
-  html = brandTokens(html);
-  return html;
+  return brandTokens(html, brand, apiBase);
 }
 
-// ---- copy the verbatim assets + the transformed index ----------------------
+// ---- CLI -------------------------------------------------------------------
+
+if (require.main === module) {
+  const arg = (name) => {
+    const i = process.argv.indexOf(name);
+    return i >= 0 ? process.argv[i + 1] : null;
+  };
+  const repoDir = arg('--repo-dir');
+  const doPush = process.argv.includes('--push');
+  if (!repoDir) {
+    console.error('usage: node scripts/status-mirror-sync.js --repo-dir <mirror-checkout> [--push]');
+    process.exit(2);
+  }
+  if (!fs.existsSync(path.join(repoDir, 'CNAME'))) {
+    console.error(`refusing: ${repoDir} does not look like the status mirror (no CNAME). Clone the status-mirror repo first.`);
+    process.exit(2);
+  }
 
-function copyFile(rel) {
-  fs.copyFileSync(path.join(SRC, rel), path.join(repoDir, rel));
-  console.error(`  copied ${rel}`);
-}
-function copyDir(rel) {
-  const from = path.join(SRC, rel), to = path.join(repoDir, rel);
-  if (!fs.existsSync(from)) return;
-  fs.rmSync(to, { recursive: true, force: true });
-  fs.cpSync(from, to, { recursive: true });
-  console.error(`  copied ${rel}/`);
+  const b = branding();
+
+  // ---- copy the verbatim assets + the transformed index ----------------------
+
+  const copyFile = (rel) => {
+    fs.copyFileSync(path.join(SRC, rel), path.join(repoDir, rel));
+    console.error(`  copied ${rel}`);
+  };
+  const copyDir = (rel) => {
+    const from = path.join(SRC, rel), to = path.join(repoDir, rel);
+    if (!fs.existsSync(from)) return;
+    fs.rmSync(to, { recursive: true, force: true });
+    fs.cpSync(from, to, { recursive: true });
+    console.error(`  copied ${rel}/`);
+  };
+
+  console.error('[status-mirror-sync] building mirror from modules/status-ui/public/ …');
+  const indexHtml = buildMirrorIndex({
+    srcHtml: fs.readFileSync(path.join(SRC, 'index.html'), 'utf8'),
+    apiBase: b.domains.publicOrigin,
+    statusDataUrl: b.domains.statusDataUrl,
+    brand: clientBranding(),
+  });
+  fs.writeFileSync(path.join(repoDir, 'index.html'), indexHtml);
+  console.error('  wrote index.html (with off-box injections)');
+  copyFile('status.js');
+  copyFile('style.css');
+  copyDir('cursors');
+
+  // ---- commit + (optionally) push -------------------------------------------
+
+  const git = (args) => execFileSync('git', ['-C', repoDir, ...args], { encoding: 'utf8' });
+  git(['add', 'index.html', 'status.js', 'style.css', 'cursors']);
+  const status = git(['status', '--porcelain']);
+  if (!status.trim()) {
+    console.error('[status-mirror-sync] mirror already up to date — nothing to publish.');
+    process.exit(0);
+  }
+  console.error('[status-mirror-sync] changes staged:\n' + status);
+  if (!doPush) {
+    console.error('[status-mirror-sync] dry run (no --push). Review the checkout, then re-run with --push.');
+    process.exit(0);
+  }
+  git(['commit', '-m', 'chore(status): sync off-box mirror from modules/status-ui/public/ (#737)']);
+  git(['push', 'origin', 'HEAD:main']);
+  console.error(`[status-mirror-sync] published. The Pages host rebuilds ${b.domains.statusOrigin || 'the mirror'} in ~1 min.`);
 }
 
-console.error('[status-mirror-sync] building mirror from modules/status-ui/public/ …');
-fs.writeFileSync(path.join(repoDir, 'index.html'), buildIndexHtml());
-console.error('  wrote index.html (with off-box injections)');
-copyFile('status.js');
-copyFile('style.css');
-copyDir('cursors');
-
-// ---- commit + (optionally) push -------------------------------------------
-
-function git(args) {
-  return execFileSync('git', ['-C', repoDir, ...args], { encoding: 'utf8' });
-}
-git(['add', 'index.html', 'status.js', 'style.css', 'cursors']);
-const status = git(['status', '--porcelain']);
-if (!status.trim()) {
-  console.error('[status-mirror-sync] mirror already up to date — nothing to publish.');
-  process.exit(0);
-}
-console.error('[status-mirror-sync] changes staged:\n' + status);
-if (!doPush) {
-  console.error('[status-mirror-sync] dry run (no --push). Review the checkout, then re-run with --push.');
-  process.exit(0);
-}
-git(['commit', '-m', 'chore(status): sync off-box mirror from modules/status-ui/public/ (#737)']);
-git(['push', 'origin', 'HEAD:main']);
-console.error('[status-mirror-sync] published. GitHub Pages rebuilds status.amazonprimea.com in ~1 min.');
+module.exports = { buildMirrorIndex, injectOnce, brandTokens };