@bongos/core 1.17.0

package/scripts/migrate.sh

@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# Apply any unapplied SQL files to the local Postgres, from THREE roots (ADR 0108 §5,
+# configurable-root W5): the CORE package's migrations/, the INSTANCE's migrations/instance/,
+# and each enabled MODULE's migrations/. Each migration is named NNN_name.sql — or a namespaced
+# core_NNN_/<key>_NNN_ (ADR 0108 §5) — and tracked in schema_migrations by its filename STEM.
+# Idempotent.
+
+set -euo pipefail
+
+# --- Resolve the core + instance roots (ADR 0108 configurable-root) -------
+# TWO roots, resolved via src/instance-config.js. Today the core lives at the repo root
+# alongside the instance, so both resolve to the SAME dir and this is byte-identical to the
+# old `cd "$(dirname "$0")/.."`. Once the core installs from node_modules, resolveCoreRoot()
+# points into the package (core migrations + src/) while resolveInstanceRoot() stays the host
+# repo (env → bongos.config → cwd). We resolve from the SCRIPT-relative dir so the result does
+# not depend on the caller's cwd (preserving the old script-relative behavior), and fail open to
+# that dir if node is unavailable so a deploy never breaks.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DEFAULT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CORE_ROOT="$(cd "$DEFAULT_ROOT" && node -e "process.stdout.write(require('./src/instance-config').resolveCoreRoot())" 2>/dev/null || echo "$DEFAULT_ROOT")"
+INSTANCE_ROOT="$(cd "$DEFAULT_ROOT" && node -e "process.stdout.write(require('./src/instance-config').resolveInstanceRoot())" 2>/dev/null || echo "$DEFAULT_ROOT")"
+# Run from the instance root so instance-relative paths resolve (the post-deploy art check below)
+# AND so the enabledModules() read finds the instance's config/modules.json (resolveInstanceRoot
+# falls back to cwd).
+cd "$INSTANCE_ROOT"
+
+DB="${PGDATABASE:-amazonprimea}"
+
+# --- Instance-seed policy (task 1704 / ADR 0105) --------------------------
+# OTB/product scope-truth (versions, goals, done_when_criteria) lives in seed
+# migrations under migrations/instance/ (plus a few guarded blocks embedded in the
+# mixed schema+seed files 003/006). These must NOT run on a fresh non-owning DB:
+# on a vanilla self-host they FK-crash the boot (the 2026-07-02 regression,
+# tactically patched in 172/173); on a branded third-party instance they'd pollute
+# it with OTB's versions/goals. So instance seeds are OPT-IN and DEFAULT OFF.
+#
+# The owning instance turns them on explicitly (GDS_APPLY_INSTANCE_SEEDS=1) only
+# when rebuilding its DB from scratch (the DR runbook). A normal OTB deploy never
+# needs it — those rows are already recorded in schema_migrations, so they're
+# skipped as-applied regardless. MEDUSA_GDS_ONLY=1 (the self-host marker set in
+# docker-compose.yml) HARD force-skips even if the opt-in is present.
+#
+# SEED_INSTANCE does two things below: (1) gates whether migrations/instance/*.sql
+# are applied at all, and (2) is exposed to SQL as the app.seed_instance_data GUC
+# (via PGOPTIONS, inherited by every psql), so the unavoidable instance-seed blocks
+# embedded in the mixed migrations 003/006 guard on it.
+if [ -n "${MEDUSA_GDS_ONLY:-}" ]; then
+  SEED_INSTANCE=off
+elif [ "${GDS_APPLY_INSTANCE_SEEDS:-0}" = "1" ]; then
+  SEED_INSTANCE=on
+else
+  SEED_INSTANCE=off
+fi
+export PGOPTIONS="${PGOPTIONS:+$PGOPTIONS }-c app.seed_instance_data=$SEED_INSTANCE"
+echo "instance-seed policy: app.seed_instance_data=$SEED_INSTANCE (migrations/instance/ $([ "$SEED_INSTANCE" = "on" ] && echo applied || echo skipped))"
+
+# Make sure schema_migrations exists before we query it. (001 creates
+# it; other migrations rely on it.)
+psql -d "$DB" -v ON_ERROR_STOP=1 -tAc "
+  CREATE TABLE IF NOT EXISTS schema_migrations (
+    version text PRIMARY KEY,
+    applied_at timestamptz NOT NULL DEFAULT now()
+  );
+" >/dev/null
+
+APPLIED=$(psql -d "$DB" -tA -c "SELECT version FROM schema_migrations ORDER BY version")
+
+# Apply one migration file unless its filename stem is already recorded. Stem (not path) is the
+# key, so moving a file between migrations/ and migrations/game/ does NOT re-run it on prod.
+apply_migration() {
+  local f="$1" version
+  version="$(basename "$f" .sql)"
+  if echo "$APPLIED" | grep -q "^${version}$"; then
+    echo "skip   $version (already applied)"
+    return
+  fi
+  echo "apply  $version"
+  psql -d "$DB" -v ON_ERROR_STOP=1 -f "$f"
+  # Self-register the apply. Most migrations contain their own INSERT INTO
+  # schema_migrations, but ~14 of the historical files do not — for those,
+  # this is what keeps them from re-running on the next deploy. ON CONFLICT
+  # DO NOTHING means it's safe for files that DO self-register too.
+  psql -d "$DB" -v ON_ERROR_STOP=1 -tAc \
+    "INSERT INTO schema_migrations (version) VALUES ('${version}') ON CONFLICT DO NOTHING" \
+    >/dev/null
+}
+
+# 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).
+#   $INSTANCE_ROOT/migrations/instance/*.sql — OTB/product scope-truth (owning instance only; policy above).
+# MERGING both dirs and sorting by BASENAME preserves the original global order — e.g.
+# instance seed 018 still applies before core rename 019 — so a from-scratch replay
+# matches history. New namespaced files (core_NNN_, ADR 0108 §5) sort AFTER the legacy bare
+# block (a letter sorts after a digit), the correct "newer applies later" order. Instance files
+# are included only when SEED_INSTANCE=on; stem-keyed tracking means a file's directory never
+# affects whether it re-runs on OTB prod. Today CORE_ROOT == INSTANCE_ROOT (single checkout);
+# once the core installs from node_modules the two roots diverge and this still merges correctly.
+MIGRATIONS=$( {
+  ls "$CORE_ROOT"/migrations/*.sql 2>/dev/null
+  if [ "$SEED_INSTANCE" = "on" ]; then ls "$INSTANCE_ROOT"/migrations/instance/*.sql 2>/dev/null; fi
+} | awk -F/ '{ print $NF "\t" $0 }' | sort | cut -f2- )
+for f in $MIGRATIONS; do
+  [ -e "$f" ] || continue
+  apply_migration "$f"
+done
+[ "$SEED_INSTANCE" = "on" ] || echo "instance seeds skipped (migrations/instance/) — non-owning / vanilla instance"
+
+# Module-owned migrations (modules/<key>/migrations/*.sql) — applied only when the module is
+# enabled. The enablement is read from the instance's config/modules.json (or the neutral
+# starter). The module CODE lives in the core package (require $CORE_ROOT/src/modules), but the
+# config is instance content (resolveInstanceRoot() falls back to cwd == INSTANCE_ROOT, set
+# above). The stem-key guarantee means moving a migration from migrations/game/ to
+# modules/game/migrations/ does NOT re-run it on prod — schema_migrations is keyed by filename
+# stem alone (ADR 0083 / BV1.R49, task 1418). A vanilla instance leaves game disabled via
+# config/modules.neutral.json.
+NODE_ENABLED_MODULES=$(node -e "
+try {
+  const { enabledModules } = require('$CORE_ROOT/src/modules');
+  process.stdout.write(enabledModules().join(' '));
+} catch(e) {
+  process.stderr.write('migrate.sh: could not read module config: ' + e.message + '\n');
+  process.stdout.write('');
+}
+" 2>/dev/null || true)
+
+# Modules can be shipped by the CORE package or by the INSTANCE repo, so scan modules/ under
+# BOTH roots. Apply each module key ONCE — today the two roots coincide (so instance-root modules
+# are all already seen), and after the split a core module and an instance module never share a
+# key (the loader errors on a cross-root key collision — ADR 0108).
+SEEN_MODULE_KEYS=" "
+for root in "$CORE_ROOT" "$INSTANCE_ROOT"; do
+  for mod_dir in "$root"/modules/*/; do
+    [ -d "$mod_dir" ] || continue
+    mod_key=$(basename "$mod_dir")
+    case "$SEEN_MODULE_KEYS" in *" $mod_key "*) continue ;; esac
+    SEEN_MODULE_KEYS="$SEEN_MODULE_KEYS$mod_key "
+    mig_dir="${mod_dir}migrations"
+    [ -d "$mig_dir" ] || continue
+    # Check if this module is enabled
+    if ! echo " $NODE_ENABLED_MODULES " | grep -q " $mod_key "; then
+      echo "module $mod_key disabled — skipping ${mig_dir}/*.sql"
+      continue
+    fi
+    for f in "$mig_dir"/*.sql; do
+      [ -e "$f" ] || continue
+      apply_migration "$f"
+    done
+  done
+done
+
+echo "done."
+
+# ---------- post-deploy whole-world regression check (GDS #151 / E.1) ----------
+#
+# Renders the live world to a PNG, scores it via Gemini vision, and compares
+# the score to the previous deploy. Fails the script (exit 1) if the score
+# drops more than 1.0 point — catches asset-swap regressions that per-tile
+# review misses (e.g. grass becomes tan, container becomes invisible).
+#
+# Gated on OTB_POST_DEPLOY_CHECK=1 so the droplet's ~/deploy.sh path (which
+# calls this script) stays unaffected — the droplet has no Google API key
+# and no Python pillow installed by default. The check runs from a deploy
+# wrapper on the dev machine that sets the flag.
+if [ "${OTB_POST_DEPLOY_CHECK:-0}" = "1" ]; then
+  echo
+  echo "post-deploy: running whole-world regression check"
+  if command -v python3 >/dev/null 2>&1; then
+    # Baseline-only on first invocation: if the ledger doesn't yet exist,
+    # save the score without failing (we have no prior to compare against).
+    BASELINE_FLAG=""
+    if [ ! -s art/iterations/world_scores.jsonl ]; then
+      BASELINE_FLAG="--baseline-only"
+      echo "post-deploy: no prior score ledger — running in baseline-only mode"
+    fi
+    if ! python3 modules/art-pipeline/pipeline/post_deploy_check.py $BASELINE_FLAG; then
+      echo "post-deploy: whole-world check FAILED — see output above" >&2
+      exit 1
+    fi
+  else
+    echo "post-deploy: python3 not found — skipping whole-world check" >&2
+  fi
+fi

package/scripts/migrate_cost_ledger.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# scripts/migrate_cost_ledger.sh
+#
+# One-shot (idempotent) migration: fold any per-worktree
+# art/iterations/cost_ledger.jsonl files into the shared location at
+# ~/.config/otb/iterations/cost_ledger.jsonl, then rebuild cost_summary.json
+# from the merged ledger.
+#
+# Per GDS #140 (2026-05-10 Lars decision): the ledger lives next to
+# pms-session.json + GOOGLE_AI_STUDIO_KEY in $HOME so it survives worktree churn
+# the way the API key does.
+#
+# Safe to re-run: appends only ledger rows not already present in the shared
+# file (matched by (ts, model, kind, tile, attempt, cost_usd, notes) tuple).
+# Per-worktree files are renamed to *.migrated-<timestamp> instead of deleted,
+# so nothing is destroyed.
+#
+# Usage:
+#   scripts/migrate_cost_ledger.sh                  # search standard locations
+#   scripts/migrate_cost_ledger.sh <ledger> [...]   # explicit files to fold in
+#   OTB_LEDGER_DIR=/tmp/foo scripts/migrate_cost_ledger.sh   # override target
+
+set -euo pipefail
+
+SHARED_DIR="${OTB_LEDGER_DIR:-$HOME/.config/otb/iterations}"
+SHARED_LEDGER="$SHARED_DIR/cost_ledger.jsonl"
+SHARED_SUMMARY="$SHARED_DIR/cost_summary.json"
+
+mkdir -p "$SHARED_DIR"
+touch "$SHARED_LEDGER"
+
+# Build candidate list: explicit args win, otherwise sweep common locations.
+declare -a CANDIDATES=()
+if [ "$#" -gt 0 ]; then
+    CANDIDATES=("$@")
+else
+    # Repo root (this script lives in <root>/scripts/).
+    SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+    REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+    # 1. The current repo's per-worktree ledger.
+    [ -f "$REPO_ROOT/art/iterations/cost_ledger.jsonl" ] && \
+        CANDIDATES+=("$REPO_ROOT/art/iterations/cost_ledger.jsonl")
+
+    # 2. Any sibling worktrees of this repo.
+    if [ -d "$REPO_ROOT/.claude/worktrees" ]; then
+        while IFS= read -r p; do
+            CANDIDATES+=("$p")
+        done < <(find "$REPO_ROOT/.claude/worktrees" -mindepth 2 -maxdepth 4 \
+                      -type f -name cost_ledger.jsonl 2>/dev/null)
+    fi
+fi
+
+# De-dup the candidate list AND drop the shared-ledger path itself if it snuck in.
+# (Stays portable to macOS default bash 3.2 — no associative arrays.)
+SHARED_REAL="$(cd "$SHARED_DIR" && pwd)/cost_ledger.jsonl"
+SEEN_LIST=""
+FILTERED=()
+for c in "${CANDIDATES[@]+"${CANDIDATES[@]}"}"; do
+    [ -f "$c" ] || continue
+    REAL="$(cd "$(dirname "$c")" && pwd)/$(basename "$c")"
+    [ "$REAL" = "$SHARED_REAL" ] && continue
+    case "$SEEN_LIST" in
+        *"|$REAL|"*) continue ;;
+    esac
+    SEEN_LIST="$SEEN_LIST|$REAL|"
+    FILTERED+=("$REAL")
+done
+
+if [ "${#FILTERED[@]}" -eq 0 ]; then
+    echo "No per-worktree cost_ledger.jsonl files to migrate."
+    echo "Shared ledger: $SHARED_LEDGER"
+    # Still rebuild the summary so a fresh shared dir gets a summary file.
+    python3 "$(dirname "$0")/../modules/art-pipeline/pipeline/cost_ledger.py" status >/dev/null || true
+    exit 0
+fi
+
+echo "Migrating to: $SHARED_LEDGER"
+for f in "${FILTERED[@]}"; do echo "  source: $f"; done
+
+# Python does the dedup + merge + summary rebuild. Keeps the bash side simple
+# and gives us proper JSON-aware comparison.
+python3 - "$SHARED_LEDGER" "$SHARED_SUMMARY" "${FILTERED[@]}" <<'PYEOF'
+import json, os, sys, time
+from pathlib import Path
+
+shared_ledger = Path(sys.argv[1])
+shared_summary = Path(sys.argv[2])
+sources = [Path(p) for p in sys.argv[3:]]
+
+def row_key(r: dict) -> tuple:
+    # Identity: (ts, model, kind, tile, attempt, cost_usd, notes).
+    # No `id` column exists today, so dedup by content tuple.
+    return (
+        r.get("ts", ""),
+        r.get("model", ""),
+        r.get("kind", ""),
+        r.get("tile", ""),
+        r.get("attempt", 0),
+        round(float(r.get("cost_usd", 0.0)), 6),
+        r.get("notes", ""),
+    )
+
+existing_keys: set = set()
+if shared_ledger.exists():
+    with shared_ledger.open() as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                existing_keys.add(row_key(json.loads(line)))
+            except Exception:
+                pass
+
+added = 0
+skipped_dup = 0
+skipped_bad = 0
+ts_suffix = time.strftime("%Y%m%dT%H%M%S")
+
+with shared_ledger.open("a") as out:
+    for src in sources:
+        if not src.exists():
+            continue
+        with src.open() as f:
+            for line in f:
+                line_stripped = line.strip()
+                if not line_stripped:
+                    continue
+                try:
+                    row = json.loads(line_stripped)
+                except Exception:
+                    skipped_bad += 1
+                    continue
+                k = row_key(row)
+                if k in existing_keys:
+                    skipped_dup += 1
+                    continue
+                existing_keys.add(k)
+                out.write(line if line.endswith("\n") else line_stripped + "\n")
+                added += 1
+        # Rename source so a re-run doesn't re-process it AND nothing is destroyed.
+        try:
+            src.rename(src.with_suffix(src.suffix + f".migrated-{ts_suffix}"))
+            print(f"  archived: {src} → {src.name}.migrated-{ts_suffix}")
+        except OSError as e:
+            print(f"  warn: could not rename {src}: {e}", file=sys.stderr)
+
+# Rebuild summary from the merged ledger.
+total = 0.0
+n = 0
+with shared_ledger.open() as f:
+    for line in f:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            total += float(json.loads(line).get("cost_usd", 0.0))
+            n += 1
+        except Exception:
+            pass
+
+HARD_STOP = 80.00
+shared_summary.parent.mkdir(parents=True, exist_ok=True)
+shared_summary.write_text(json.dumps({
+    "total_usd": round(total, 4),
+    "calls": n,
+    "hard_stop_usd": HARD_STOP,
+    "remaining_usd": round(HARD_STOP - total, 4),
+    "updated_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
+}, indent=2))
+
+print(f"\nMerged: {added} new rows, {skipped_dup} duplicates skipped, {skipped_bad} malformed lines skipped.")
+print(f"Shared ledger now: {n} rows, ${total:.4f} spent of ${HARD_STOP:.2f} cap.")
+PYEOF
+
+echo
+echo "Done. Verify with: python3 modules/art-pipeline/pipeline/cost_ledger.py status"

package/scripts/public-mirror-export.js

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/public-mirror-export.js — the TIME-DELAYED, REDACTED export to the Cloud
+// Bongos public mirror. GDS-V4 R72 (task 1211), implementing ADR 0098 + ADR 0065 §4.
+//
+// WHAT IT DOES, in one fail-closed pass:
+//   1. Pick the SNAPSHOT commit: the newest commit on the source ref whose committer
+//      date is >= LAG_DAYS old (default 180 ≈ 6 months). The mirror is always ~6 months
+//      behind, by construction.
+//   2. Enumerate that commit's tree and PARTITION it through publish-manifest.isPublishable
+//      — the SINGLE source of truth for what publishes (task 1210). No second allow-list.
+//   3. REDACT every publishable file IN MEMORY: instance literals + public IPs
+//      (mirror-redact) then the secret backstop (secret-scrub). Binary files are kept
+//      verbatim but still leak-scanned.
+//   4. NO-LEAK GATE (fail-closed): scan the redacted bytes of every file. If ANY instance
+//      literal, public IP, or secret survives, PUBLISH NOTHING — the mirror filesystem is
+//      never touched. This is why redaction happens in memory first: an abort is atomic.
+//   5. Only when the whole set is clean: clear the mirror tree, write the redacted files
+//      (modes preserved), write .mirror-provenance.json (the lineage anchor R73 reads),
+//      commit, and (with --push) push.
+//
+// The 6-month delay alone does NOT scrub secrets/topology — redaction is mandatory and
+// the gate is the backstop. Reuses the status-mirror-sync transport shape (--repo-dir /
+// --push + a scoped deploy key, see .github/workflows/sync-public-mirror.yml).
+//
+// USAGE:
+//   node scripts/public-mirror-export.js --repo-dir <mirror-checkout> [--push]
+//        [--lag-days 180] [--source-ref origin/main] [--droplet-ip <ip>]
+//   Without --push: redacts + gates + writes the tree, prints `git status`, does NOT
+//   commit/push (a dry run you can inspect). With --push: commits + pushes HEAD:main.
+//   --droplet-ip (or env DROPLET_IP) adds the prod IP as an exact extra literal so the
+//   gate asserts that specific value is gone — belt-and-suspenders over the public-IP
+//   floor, and kept OUT of every committed file (sourced at publish time).
+
+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, findSecretLeak,
+} = require(path.join(REPO_ROOT, 'scripts/gds/mirror-redact.js'));
+const { collectEnvSecrets, scrubSecrets } = require(path.join(REPO_ROOT, 'modules/security/secret-scrub.js'));
+
+const PROVENANCE_FILE = '.mirror-provenance.json';
+const DEFAULT_LAG_DAYS = 180;
+
+// ---- arg parsing ----------------------------------------------------------
+function arg(name, fallback = null) {
+  const i = process.argv.indexOf(name);
+  return i >= 0 && i + 1 < process.argv.length ? process.argv[i + 1] : fallback;
+}
+function hasFlag(name) { return process.argv.includes(name); }
+
+// ---- pure helpers (exported for tests) ------------------------------------
+
+// Pick the newest commit at least LAG_DAYS old. `commits` is newest-first
+// [{ sha, epoch }] (epoch = committer date, UNIX seconds). Returns the commit or null
+// if the whole history is younger than the lag (a young repo: nothing to publish yet).
+function pickSnapshotCommit(commits, nowMs, lagDays) {
+  const cutoffMs = nowMs - lagDays * 86400 * 1000;
+  for (const c of commits || []) {
+    if (typeof c.epoch === 'number' && c.epoch * 1000 <= cutoffMs) return c;
+  }
+  return null;
+}
+
+// Parse `git ls-tree -r <sha>` output → [{ mode, type, sha, path }] (blobs + the rest).
+function parseLsTree(output) {
+  const out = [];
+  for (const line of String(output || '').split('\n')) {
+    if (!line.trim()) continue;
+    // "<mode> <type> <objsha>\t<path>"
+    const tab = line.indexOf('\t');
+    if (tab < 0) continue;
+    const meta = line.slice(0, tab).split(/\s+/);
+    if (meta.length < 3) continue;
+    out.push({ mode: meta[0], type: meta[1], sha: meta[2], path: line.slice(tab + 1) });
+  }
+  return out;
+}
+
+// Heuristic binary sniff: a NUL byte in the first 8 KiB. Mirrors how git decides.
+function isBinary(buf) {
+  if (!Buffer.isBuffer(buf)) return false;
+  const n = Math.min(buf.length, 8192);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+// Redact one blob and report any residual leak. Text files are redacted (instance
+// literals + IP, then secret scrub); binary files are kept verbatim but leak-scanned
+// over their latin1 view (so an embedded literal still trips the gate). The gate uses
+// `sensitiveLiterals` (raw substrings), NOT `rules` — stricter than redaction on
+// purpose (see mirror-redact.js). Returns { buf:Buffer, leaks:[{label,sample}], secret:boolean }.
+function redactBlob({ buf, rules, sensitiveLiterals, envSecrets }) {
+  if (isBinary(buf)) {
+    const view = buf.toString('latin1');
+    return { buf, leaks: findLeaks(view, sensitiveLiterals), secret: findSecretLeak(view, envSecrets) };
+  }
+  const redacted = redactText(buf.toString('utf8'), rules);
+  const scrubbed = scrubSecrets(redacted, envSecrets);
+  return {
+    buf: Buffer.from(scrubbed, 'utf8'),
+    leaks: findLeaks(scrubbed, sensitiveLiterals),
+    secret: findSecretLeak(scrubbed, envSecrets),
+  };
+}
+
+function buildProvenance({ sourceCommit, committedAtIso, lagDays, fileCount, nowIso }) {
+  return {
+    _note: 'Lineage anchor for the Cloud Bongos public mirror (ADR 0098 / GDS-V4 R72). '
+      + 'This mirror is a redacted, time-delayed snapshot of the private build repo. The '
+      + 'R73 proof (#1212) asserts source_commit is an ancestor of the private main and that '
+      + 'no secret/topology literal reached these files.',
+    generator: 'scripts/public-mirror-export.js',
+    source_commit: sourceCommit,
+    source_committed_at: committedAtIso,
+    lag_days: lagDays,
+    exported_files: fileCount,
+    exported_at: nowIso,
+  };
+}
+
+// ---- git plumbing (private repo = REPO_ROOT) ------------------------------
+function gitRoot(args) {
+  return execFileSync('git', ['-C', REPO_ROOT, ...args], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+}
+function gitRootBuf(args) {
+  return execFileSync('git', ['-C', REPO_ROOT, ...args], { maxBuffer: 256 * 1024 * 1024 });
+}
+
+// Newest-first [{sha, epoch}] for a ref.
+function listCommits(ref) {
+  const out = gitRoot(['log', ref, '--format=%H %ct', '--no-merges']);
+  return out.split('\n').filter(Boolean).map((l) => {
+    const sp = l.indexOf(' ');
+    return { sha: l.slice(0, sp), epoch: Number(l.slice(sp + 1)) };
+  });
+}
+
+function main() {
+  const repoDir = arg('--repo-dir');
+  const doPush = hasFlag('--push');
+  const lagDays = Number(arg('--lag-days', String(DEFAULT_LAG_DAYS)));
+  const sourceRef = arg('--source-ref', 'origin/main');
+  const dropletIp = arg('--droplet-ip', process.env.DROPLET_IP || null);
+
+  if (!repoDir) {
+    console.error('usage: node scripts/public-mirror-export.js --repo-dir <mirror-checkout> [--push] [--lag-days 180] [--source-ref origin/main]');
+    process.exit(2);
+  }
+  const mirrorDir = path.resolve(repoDir);
+  if (!fs.existsSync(path.join(mirrorDir, '.git'))) {
+    console.error(`refusing: ${mirrorDir} is not a git checkout (no .git). Clone the public mirror first.`);
+    process.exit(2);
+  }
+  if (mirrorDir === REPO_ROOT) {
+    console.error('refusing: --repo-dir is the private source repo itself. It must be the SEPARATE public mirror checkout.');
+    process.exit(2);
+  }
+  if (!Number.isFinite(lagDays) || lagDays < 1) {
+    console.error(`refusing: --lag-days must be a positive number (got ${lagDays}).`);
+    process.exit(2);
+  }
+
+  // 1. Pick the lagged snapshot commit.
+  const nowMs = Date.now();
+  const commits = listCommits(sourceRef);
+  const snapshot = pickSnapshotCommit(commits, nowMs, lagDays);
+  if (!snapshot) {
+    console.error(`[public-mirror-export] no commit on ${sourceRef} is >= ${lagDays} days old yet — nothing to publish. (Repo younger than the publish lag.)`);
+    process.exit(0);
+  }
+  const committedAtIso = new Date(snapshot.epoch * 1000).toISOString();
+  console.error(`[public-mirror-export] snapshot = ${snapshot.sha.slice(0, 12)} (committed ${committedAtIso}, ${lagDays}d lag) from ${sourceRef}`);
+
+  // 2. Enumerate + partition the tree through the manifest (single source of truth).
+  const entries = parseLsTree(gitRoot(['ls-tree', '-r', snapshot.sha])).filter((e) => e.type === 'blob');
+  const publishable = entries.filter((e) => isPublishable(e.path));
+  console.error(`[public-mirror-export] tree has ${entries.length} files; ${publishable.length} publishable per the manifest, ${entries.length - publishable.length} excluded.`);
+  if (publishable.length === 0) {
+    console.error('refusing: the publishable set is EMPTY — that is almost certainly a bug (manifest/ref mismatch), not an intentional wipe. Aborting without touching the mirror.');
+    process.exit(1);
+  }
+
+  // 3. Build the redaction rules from THIS instance's branding (current HEAD), plus the
+  //    droplet IP as an exact extra literal (sourced here, never written to a file).
+  let branding = {};
+  try {
+    branding = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'config/branding.json'), 'utf8'));
+  } catch { /* vanilla instance: derive only from the public-IP floor */ }
+  // Owner-identity aliases beyond the GitHub login (real name, home-dir username) come
+  // from OWNER_ALIASES (comma-separated) — set in the WORKFLOW yaml, which is excluded
+  // from the mirror, so the alias literal never appears in a published file. Redacting
+  // the login/alias substring also covers "/Users/<login>" home paths.
+  const ownerAliases = String(process.env.OWNER_ALIASES || '')
+    .split(',').map((s) => s.trim()).filter(Boolean);
+  const extra = { owners: ownerAliases, literals: dropletIp ? [dropletIp] : [] };
+  const rules = buildRedactionRules(branding, extra);
+  const sensitiveLiterals = collectSensitiveLiterals(branding, extra);
+  const envSecrets = collectEnvSecrets();
+  console.error(`[public-mirror-export] ${rules.length} redaction rule(s), ${sensitiveLiterals.length} gate literal(s) + public-IP floor + ${envSecrets.length} env-secret literal(s).`);
+
+  // 4. Redact every file IN MEMORY and run the fail-closed no-leak gate. Nothing touches
+  //    the mirror filesystem until the ENTIRE set is proven clean (atomic abort).
+  const staged = []; // { path, buf, mode }
+  const leaks = [];  // { path, label, sample? }
+  for (const e of publishable) {
+    let raw;
+    try {
+      raw = gitRootBuf(['cat-file', 'blob', e.sha]);
+    } catch (err) {
+      leaks.push({ path: e.path, label: `read-failed:${err.message}` });
+      continue;
+    }
+    const { buf, leaks: fileLeaks, secret } = redactBlob({ buf: raw, rules, sensitiveLiterals, envSecrets });
+    for (const l of fileLeaks) leaks.push({ path: e.path, label: l.label, sample: l.sample });
+    if (secret) leaks.push({ path: e.path, label: 'secret-shape' }); // never print the secret sample
+    staged.push({ path: e.path, buf, mode: e.mode });
+  }
+
+  if (leaks.length > 0) {
+    console.error(`\n[public-mirror-export] NO-LEAK GATE FAILED — ${leaks.length} residual leak(s). PUBLISHING NOTHING (fail-closed):`);
+    for (const l of leaks.slice(0, 50)) {
+      // Print the label + file but NEVER a secret value; instance literals are safe to show.
+      const shown = l.label === 'secret-shape' ? '' : (l.sample ? ` (“${String(l.sample).slice(0, 40)}”)` : '');
+      console.error(`   ${l.path}: ${l.label}${shown}`);
+    }
+    if (leaks.length > 50) console.error(`   … +${leaks.length - 50} more`);
+    console.error('\nFix: extend the redaction rules (scripts/gds/mirror-redact.js) or the manifest exclusions (scripts/gds/publish-manifest.js), then re-run. The mirror was NOT modified.');
+    process.exit(1);
+  }
+  console.error(`[public-mirror-export] no-leak gate PASSED — ${staged.length} files clean.`);
+
+  // 5. Clean → write → provenance. Only reached when the whole set is clean.
+  clearMirrorTree(mirrorDir);
+  for (const f of staged) {
+    const dest = path.join(mirrorDir, f.path);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, f.buf);
+    if (f.mode === '100755') fs.chmodSync(dest, 0o755); // preserve the executable bit
+  }
+  const provenance = buildProvenance({
+    sourceCommit: snapshot.sha,
+    committedAtIso,
+    lagDays,
+    fileCount: staged.length,
+    nowIso: new Date(nowMs).toISOString(),
+  });
+  fs.writeFileSync(path.join(mirrorDir, PROVENANCE_FILE), JSON.stringify(provenance, null, 2) + '\n');
+
+  // 6. Commit + (optionally) push.
+  const mgit = (args) => execFileSync('git', ['-C', mirrorDir, ...args], { encoding: 'utf8' });
+  mgit(['add', '-A']);
+  const status = mgit(['status', '--porcelain']);
+  if (!status.trim()) {
+    console.error('[public-mirror-export] mirror already up to date for this snapshot — nothing to commit.');
+    process.exit(0);
+  }
+  console.error(`[public-mirror-export] ${status.split('\n').filter(Boolean).length} path(s) changed in the mirror.`);
+  if (!doPush) {
+    console.error('[public-mirror-export] DRY RUN (no --push). Redacted tree written + gated clean; review the checkout, then re-run with --push.');
+    process.exit(0);
+  }
+  // Commit message carries only the SHA + date (no instance literals/secrets).
+  mgit(['commit', '-m', `chore(mirror): redacted snapshot of ${snapshot.sha.slice(0, 12)} (committed ${committedAtIso}; ${lagDays}d lag)`]);
+  mgit(['push', 'origin', 'HEAD:main']);
+  console.error('[public-mirror-export] published to the public mirror.');
+  process.exit(0);
+}
+
+// Remove every tracked + untracked entry from the mirror working tree EXCEPT .git, so a
+// file that drops out of the publishable set (or out of the lagged tree) disappears from
+// the mirror too. Only reached after the no-leak gate passes, so this never wipes the
+// mirror on a failed run.
+function clearMirrorTree(mirrorDir) {
+  for (const name of fs.readdirSync(mirrorDir)) {
+    if (name === '.git') continue;
+    fs.rmSync(path.join(mirrorDir, name), { recursive: true, force: true });
+  }
+}
+
+module.exports = {
+  pickSnapshotCommit, parseLsTree, isBinary, redactBlob, buildProvenance,
+  PROVENANCE_FILE, DEFAULT_LAG_DAYS,
+};
+
+if (require.main === module) main();