@bongos/core 1.18.0 → 1.18.3

package/tests/upgrade.mjs

@@ -16,10 +16,11 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 
 const require = createRequire(import.meta.url);
 const u = require('../scripts/gds/upgrade.js');
+const pc = require('../scripts/gds/package-core.js'); // the packager — reuse its EXACT hash fns to build reference pins
 
 let passed = 0, failed = 0;
 const pending = [];
@@ -159,7 +160,9 @@ t('full: pre-flight → pin → install → migrate → materialize → restart
   let materialized = null;
   let regenArgs = null;
   const res = await u.runUpgrade(
-    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'emersonian.service' },
+    // healthCheck:false — this test exercises the full pipeline, not the health poll (which would need
+    // a fetch mock); a managed-restart bump now requires a --health-url unless health is opted out (H9).
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'emersonian.service', healthCheck: false },
     {
       log: () => {}, err: () => {},
       run: fakeRun(calls, { dirty: '', installTo: '1.15.0', dir }),
@@ -398,7 +401,7 @@ t('runUpgrade --registry (full): pins the exact version + writes the env-fed .np
   const dir = scratchConsumer({ pinned: '1.16.0', installed: '1.16.0' });
   const calls = [];
   const res = await u.runUpgrade(
-    { to: '1.17.0', registry: true, instance: dir, service: 'demo.service' },
+    { to: '1.17.0', registry: true, instance: dir, service: 'demo.service', healthCheck: false }, // H9: opt out (no health poll under test)
     {
       log: () => {}, err: () => {},
       run: fakeRun(calls, { dirty: '', installTo: '1.17.0', dir }),
@@ -479,7 +482,7 @@ t('rollback on migrate failure: reverts pin + reinstalls previous core + rolled_
   const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
   const calls = [], queries = [];
   const res = await u.runUpgrade(
-    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service' },
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service', healthCheck: false }, // H9: opt out — this test is about migrate-failure rollback, not health
     {
       log: () => {}, err: () => {},
       run: pinAwareRun(calls, { dir, failMigrate: true }),
@@ -502,7 +505,7 @@ t('rollback on npm-install failure: reverts pin + reinstalls previous core', asy
   const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
   const calls = [], queries = [];
   const res = await u.runUpgrade(
-    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service' },
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service', healthCheck: false }, // H9: opt out — this test is about install-failure rollback, not health
     {
       log: () => {}, err: () => {},
       run: pinAwareRun(calls, { dir, failInstallForVersion: '1.15.0' }),
@@ -547,6 +550,252 @@ t('restorePin: writes a previous dep string back verbatim (file: or registry)',
   assert.equal(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies['@bongos/core'], '^1.16.0');
 });
 
+// ---- 7. integrity-pin verification (task 1002216 / audit H8, finding F1) ----
+// Build a reference pin exactly as the packager does — canonicalTreeHash over the pinned
+// files' sha256, so a matching installed tree recomputes byte-identically.
+function pinManifestFor(files, { tarballSha = null, tarballBytes = 0 } = {}) {
+  const meta = files
+    .map((f) => ({ path: f.path, mode: f.mode || '0000644', sha256: pc.sha256hex(Buffer.from(f.content)) }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const m = { artifact: 'bongos-core', tree_sha256: pc.canonicalTreeHash(meta), files: meta };
+  if (tarballSha) m.tarball = { name: 'bongos-core.tgz', sha256: tarballSha, bytes: tarballBytes };
+  return m;
+}
+function writeCoreTree(coreDir, files) {
+  for (const f of files) {
+    const abs = join(coreDir, ...f.path.split('/'));
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, f.content);
+  }
+}
+const PIN_FILES = [{ path: 'a.js', content: 'console.log(1)\n' }, { path: 'sub/b.json', content: '{"x":1}\n' }];
+
+t('verifyInstalledPin: matching installed tree + tarball bytes → ok (both checks)', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-pin-'));
+  const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+  writeCoreTree(coreDir, PIN_FILES);
+  const tgzBytes = Buffer.from('deterministic-fake-tgz');
+  const tgz = join(dir, 'vendor', 'bongos-core-1.15.0.tgz');
+  mkdirSync(dirname(tgz), { recursive: true });
+  writeFileSync(tgz, tgzBytes);
+  const m = pinManifestFor(PIN_FILES, { tarballSha: pc.sha256hex(tgzBytes), tarballBytes: tgzBytes.length });
+  const res = u.verifyInstalledPin({ coreDir, referenceManifest: m, tgzPath: tgz });
+  assert.equal(res.ran, true);
+  assert.equal(res.ok, true, res.problems.join('; '));
+  assert.deepEqual(res.checks.map((c) => c.name).sort(), ['tarball.sha256', 'tree_sha256']);
+});
+
+t('verifyInstalledPin: a corrupted installed file → mismatch (ran, not ok)', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-pin-'));
+  const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+  writeCoreTree(coreDir, PIN_FILES);
+  const m = pinManifestFor(PIN_FILES);
+  writeFileSync(join(coreDir, 'a.js'), 'console.log(999) // tampered\n'); // corrupt AFTER pinning
+  const res = u.verifyInstalledPin({ coreDir, referenceManifest: m, tgzPath: null });
+  assert.equal(res.ran, true);
+  assert.equal(res.ok, false);
+  assert.ok(res.problems.some((p) => /content mismatch: a\.js/.test(p)), res.problems.join('; '));
+});
+
+t('verifyInstalledPin: a missing installed file → mismatch', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-pin-'));
+  const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+  writeCoreTree(coreDir, [PIN_FILES[0]]); // omit sub/b.json
+  const res = u.verifyInstalledPin({ coreDir, referenceManifest: pinManifestFor(PIN_FILES), tgzPath: null });
+  assert.equal(res.ok, false);
+  assert.ok(res.problems.some((p) => /missing installed file: sub\/b\.json/.test(p)), res.problems.join('; '));
+});
+
+t('verifyInstalledPin: tarball bytes differ from the pin → mismatch', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-pin-'));
+  const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+  writeCoreTree(coreDir, PIN_FILES);
+  const tgz = join(dir, 'vendor', 'bongos-core-1.15.0.tgz');
+  mkdirSync(dirname(tgz), { recursive: true });
+  writeFileSync(tgz, Buffer.from('the-actual-bytes'));
+  const m = pinManifestFor(PIN_FILES, { tarballSha: pc.sha256hex(Buffer.from('DIFFERENT-bytes')), tarballBytes: 9 });
+  const res = u.verifyInstalledPin({ coreDir, referenceManifest: m, tgzPath: tgz });
+  assert.equal(res.ok, false);
+  assert.ok(res.problems.some((p) => /tarball bytes/.test(p)), res.problems.join('; '));
+});
+
+t('verifyInstalledPin: no pin in the reference manifest → ran:false (nothing to check)', () => {
+  const res = u.verifyInstalledPin({ coreDir: '/nonexistent', referenceManifest: {}, tgzPath: null });
+  assert.equal(res.ran, false);
+  assert.equal(res.ok, false);
+});
+
+t('resolveReferenceManifest: prefers the committed vendored side-car (strong)', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-pin-'));
+  const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+  mkdirSync(join(dir, 'vendor'), { recursive: true });
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.manifest.json'), JSON.stringify(pinManifestFor(PIN_FILES)));
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.tgz'), 'x');
+  const ref = u.resolveReferenceManifest({ instanceDir: dir, coreDir, targetVersion: '1.15.0' });
+  assert.equal(ref.source, 'vendored side-car manifest');
+  assert.equal(ref.strong, true);
+  assert.ok(ref.tgzPath && existsSync(ref.tgzPath));
+});
+
+t('resolveReferenceManifest: falls back to the installed inner manifest (not strong)', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-pin-'));
+  const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+  mkdirSync(coreDir, { recursive: true });
+  writeFileSync(join(coreDir, '.bongos-core.json'), JSON.stringify(pinManifestFor(PIN_FILES)));
+  const ref = u.resolveReferenceManifest({ instanceDir: dir, coreDir, targetVersion: '1.15.0' });
+  assert.equal(ref.source, 'installed inner manifest');
+  assert.equal(ref.strong, false);
+  assert.equal(ref.tgzPath, null);
+});
+
+// A spawn shim whose `npm install` writes an installed core tree (+ version) so the
+// real pin-verify step can run against it. `files` is what actually lands on disk.
+function installWritingTree(calls, { dir, version, files }) {
+  return (cmd, args) => {
+    calls.push(`${cmd} ${(args || []).join(' ')}`.trim());
+    if (cmd === 'git' && args[0] === 'status') return { status: 0, stdout: '' };
+    if (cmd === 'npm' && args[0] === 'install') {
+      const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+      writeCoreTree(coreDir, files);
+      writeFileSync(join(coreDir, 'package.json'), JSON.stringify({ name: '@bongos/core', version }) + '\n');
+    }
+    return { status: 0 };
+  };
+}
+
+t('runUpgrade: a matching pin passes verification (upgrade proceeds)', async () => {
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  mkdirSync(join(dir, 'vendor'), { recursive: true });
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.tgz'), 'fake-tgz');
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.manifest.json'),
+    JSON.stringify(pinManifestFor(PIN_FILES, { tarballSha: pc.sha256hex(Buffer.from('fake-tgz')), tarballBytes: 8 })));
+  const logs = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', instance: dir },
+    {
+      log: (m) => logs.push(m), err: () => {},
+      run: installWritingTree([], { dir, version: '1.15.0', files: PIN_FILES }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+    }
+  );
+  assert.equal(res.ok, true, res.error);
+  assert.ok(logs.some((m) => /integrity pin verified.*tarball\.sha256.*tree_sha256/.test(m)), logs.join('\n'));
+});
+
+t('runUpgrade: a pin MISMATCH after install fails and auto-rolls-back', async () => {
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  mkdirSync(join(dir, 'vendor'), { recursive: true });
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.tgz'), 'fake-tgz');
+  // The reference pin is for PIN_FILES, but install writes DIFFERENT content → tree mismatch.
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.manifest.json'), JSON.stringify(pinManifestFor(PIN_FILES)));
+  const corrupted = [{ path: 'a.js', content: 'console.log(666)\n' }, { path: 'sub/b.json', content: '{"x":1}\n' }];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', instance: dir },
+    {
+      log: () => {}, err: () => {},
+      run: installWritingTree([], { dir, version: '1.15.0', files: corrupted }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+    }
+  );
+  assert.equal(res.ok, false);
+  assert.ok(/integrity pin MISMATCH/.test(res.error || ''), res.error);
+  assert.equal(res.rolledBack, true);
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'pin reverted to the previous version on rollback');
+});
+
+t('runUpgrade: --require-pin makes a MISSING reference manifest fatal', async () => {
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  mkdirSync(join(dir, 'vendor'), { recursive: true });
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.tgz'), 'fake-tgz'); // tgz present, but NO manifest
+  const res = await u.runUpgrade(
+    { to: '1.15.0', instance: dir, requirePin: true },
+    {
+      log: () => {}, err: () => {},
+      run: installWritingTree([], { dir, version: '1.15.0', files: PIN_FILES }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+    }
+  );
+  assert.equal(res.ok, false);
+  assert.ok(/no reference manifest/.test(res.error || ''), res.error);
+  assert.equal(res.rolledBack, true, 'unverifiable pin rolls back under --require-pin');
+});
+
+t('runUpgrade: --skip-pin-verify bypasses the check (no manifest, still succeeds)', async () => {
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  mkdirSync(join(dir, 'vendor'), { recursive: true });
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.tgz'), 'fake-tgz');
+  const res = await u.runUpgrade(
+    { to: '1.15.0', instance: dir, skipPinVerify: true },
+    {
+      log: () => {}, err: () => {},
+      run: installWritingTree([], { dir, version: '1.15.0', files: PIN_FILES }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+    }
+  );
+  assert.equal(res.ok, true, res.error);
+});
+
+// ---- 8. mandatory post-restart health check (task 1002222 / audit H9, finding F5) ----
+t('runUpgrade: a managed-restart bump WITHOUT --health-url is refused up front (H9 mandatory)', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const calls = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service' }, // restarts, no --health-url, not opted out
+    { log: () => {}, err: () => {}, run: fakeRun(calls, { dirty: '', installTo: '1.15.0', dir }), materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }) }
+  );
+  assert.equal(res.ok, false);
+  assert.match(res.error, /health check is mandatory/);
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'refused in pre-flight → pin untouched');
+  assert.ok(!calls.some((c) => /npm install/.test(c)), 'refused before any install');
+});
+
+t('runUpgrade: --no-health-check lets a managed-restart bump proceed without a URL', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const logs = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service', healthCheck: false },
+    { log: (m) => logs.push(m), err: () => {}, run: fakeRun([], { dirty: '', installTo: '1.15.0', dir }), materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }) }
+  );
+  assert.equal(res.ok, true, res.error);
+  assert.ok(logs.some((m) => /health check skipped \(--no-health-check\)/.test(m)), logs.join('\n'));
+});
+
+t('runUpgrade: a managed-restart bump WITH a healthy --health-url confirms + succeeds', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const logs = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service', healthUrl: 'http://x/healthz' },
+    {
+      log: (m) => logs.push(m), err: () => {}, run: fakeRun([], { dirty: '', installTo: '1.15.0', dir }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      fetch: async () => ({ ok: true, status: 200 }), sleep: async () => {}, now: () => 0,
+    }
+  );
+  assert.equal(res.ok, true, res.error);
+  assert.equal(res.healthOk, true);
+  assert.ok(logs.some((m) => /health http:\/\/x\/healthz → 200/.test(m)), logs.join('\n'));
+});
+
+t('runUpgrade: no managed restart + no --health-url proceeds but flags the bump as unconfirmed', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const logs = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir }, // no service/restart-cmd, no --health-url
+    { log: (m) => logs.push(m), err: () => {}, run: fakeRun([], { dirty: '', installTo: '1.15.0', dir }), materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }) }
+  );
+  assert.equal(res.ok, true, res.error);
+  assert.equal(res.healthOk, null);
+  assert.ok(logs.some((m) => /not confirmed serving/.test(m)), logs.join('\n'));
+});
+
 await Promise.all(pending);
 console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/.gitignore

@@ -1,91 +0,0 @@
-# Dependencies
-node_modules/
-
-# Per-session git worktrees live under here; each is itself a git checkout
-# and must NEVER be committed (would create embedded-repo references).
-.claude/worktrees/
-
-# Environment / secrets
-.env
-.env.local
-.env.*.local
-
-# Google Chat OAuth credentials — must NEVER be committed.
-# Live on the droplet at /etc/amazonprimea/ instead.
-google-chat-credentials.json
-google-chat-refresh-token.json
-*.credentials.json
-
-# Build output
-dist/
-build/
-
-# Logs
-*.log
-npm-debug.log*
-
-# OS files
-.DS_Store
-
-# Pixel art generation artifacts (iterations are huge; keep references + finals only)
-modules/art-pipeline/iterations/*
-# ...but keep the anti-grid FFT baselines tracked (idea 27): they're tiny + the smoke suite
-# (tests/anti_grid.mjs) compares against them. `modules/art-pipeline/iterations/*` (not the bare
-# dir) lets this negation re-include the file — git can't re-include under a fully-excluded dir.
-!modules/art-pipeline/iterations/anti_grid_baselines.json
-modules/art-pipeline/generated/raw/
-modules/art-pipeline/generated/*/raw/
-# Derived from references/ via slice_references.py — easy to regenerate, no need in git
-modules/art-pipeline/template/ref_tiles/
-modules/art-pipeline/template/ref_clusters/
-# Autotile cross-verify snapshot — regenerated on every smoke_test run.
-modules/art-pipeline/pipeline/_autotile_tables.json
-__pycache__/
-*.pyc
-
-
-# World snapshots — generated on the droplet by scripts/snapshots/render-world.mjs.
-# Untracked so git reset --hard on deploy doesn't wipe them.
-public-status/snapshots/*.png
-public-status/snapshots/manifest.json
-
-# Repo Atlas data — generated on the droplet by scripts/gds/gen-atlas.js on every
-# deploy (ADR 0094). Untracked so git reset --hard doesn't wipe it; the deploy
-# step rewrites it fresh each time, so a committed copy would only go stale.
-# (The hall surface carved to modules/hall-ui/public/ in BV1.R85.)
-modules/hall-ui/public/atlas.json
-
-# Whole-file generated navigation docs — untracked since ADR 0110 (task 1926), the
-# same reasoning as the atlas above. docs/repo-map.md (symbol skeleton, ADR 0063) and
-# docs/session-log-index.md (session index, ADR 0062 §8) are 100%-generated and were
-# regenerated + committed on EVERY ship, so two parallel builder branches collided on
-# them constantly. Untracked + regenerated at deploy (scripts/deploy/deploy-prod.sh) and
-# at box-source-fetch, they can never appear in a branch diff → the conflict class is
-# gone at the source. Their generators are dual-duty: the nested CLAUDE.md symbol blocks
-# and the CLAUDE.md §13 snippet stay TRACKED and CI-gated (gen-*.js --check-block).
-docs/repo-map.md
-docs/session-log-index.md
-
-# Onboarding diagram RENDERS — untracked since ADR 0110 pt.3 / ADR 0122 (task 2027),
-# the deferred diagram half of ADR 0110. The .svg/.png are regenerated + committed on
-# every render-capable ship, so parallel builder branches collided on them (same class
-# as the nav docs above). Untracked + re-rendered at deploy (scripts/deploy/deploy-prod.sh
-# runs scripts/render-diagrams.sh against the tracked .mmd, using the host's installed
-# Chrome — never puppeteer's own droplet-stalling download) and best-effort at
-# box-source-fetch. The .mmd SOURCES + assertions.json stay TRACKED (git reset --hard
-# restores them; the render regenerates the images from them), so the nightly
-# diagram-drift cron (reads assertions.json) is unaffected.
-docs/onboarding/diagrams/*.svg
-docs/onboarding/diagrams/*.png
-
-# Re-hosted #bugs screenshots (task #936). Downloaded from Discord and served
-# by routes/bug-attachments.js. Outside git so a deploy never wipes them.
-var/bug-attachments/
-
-# Custom merge-driver scratch files. The regen merge driver
-# (scripts/gds/git-merge-regen.js, installed by scripts/gds/install-git-hooks.js)
-# writes `.merge_file_*` temp files while resolving conflicts. They are pure
-# scratch — never source — but a `git add -A` once staged one onto main
-# (.merge_file_IKo9KW, merge 3e9f1f81). Ignore the pattern so it can't recur.
-.merge_file_*
-scratchpad/

package/docs/adr/0139-platform-history-migration-to-cloudbongos.md

@@ -1,94 +0,0 @@
-# ADR 0139 — Migrate the platform work-history from the Off the Boats instance DB to the cloudbongos DB
-
-- **Status:** Accepted — **MIGRATION COMPLETE 2026-07-11** (owner greenlit the production run + the cut). Load into cloudbongos + verification done; TIER-2 valuable-history sweep done; and the WS-6 clean cut **fired + verified on live amazonprimea** (now game-only). The CB↔OTB split is complete (code + data). See the **Execution record** at the end.
-- **Date:** 2026-07-10
-- **Track:** internal (platform)
-- **Decides:** whether — and how — the Cloud Bongos *platform* work-history (tasks, goals, done-when criteria, the credit ledger, builder identities + balances) is physically relocated from the `amazonprimea` (Off the Boats "customer zero") Postgres database to the `cloudbongos` database, so a builder signing into the cloudbongos hall with the same GitHub sees their earned balance.
-- **Builds on:** ADR 0103 (core-first extraction; cloud-bongos is the trunk), ADR 0108 (configurable-root; the code half), ADR 0100 §3 (per-repo GDS), ADR 0016 (server-enforced permissions / trust boundary).
-- **Supersedes framing of:** ADR 0107 §3, which *deferred* cross-instance identity/payout as an open question, and the goal-41 "identity federated, authority per-project" design string. This ADR is the deliberate, bounded decision those left open — see Context.
-- **Companion:** the **code half** of the CB↔OTB split (amazonprimea task 1728 / R89 cutover; cloud-bongos re-seeded to the authoritative source by amazonprimea task 2190). This ADR is the **data half**.
-
-## Context
-
-Off the Boats (`amazonprimea` DB) is where Cloud Bongos itself was built — "customer zero." The R89 cutover already moved the platform **code** out: amazonprimea now consumes `@bongos/core` as a vendored dependency, and cloud-bongos is the authoritative editable core source. What remains inside the `amazonprimea` database is the platform's entire **work-history**: ~2,000+ platform tasks/goals/criteria, the credit ledger, and the builder identities that earned those credits — interleaved with the game's own ~57 tasks and game-earned credits.
-
-The requirement: a builder who signs into the cloudbongos hall with the same GitHub account should see the platform balance they earned. The platform's *own* design deliberately drew a line against this — goal-41's design says "identity is federated, authority (ranks/credits) is **not**," and ADR 0107 §3 explicitly defers cross-instance payout. So **relocating balances runs counter to that line and therefore needs its own decision record** — this ADR. It is *not* the future federation hub (goal 41), and it is not "finishing" an existing plan; it is a one-time, supervised data move.
-
-No cross-instance data-mover exists today. The only tooling is per-instance `pg_dump` backup; provisioning creates an *empty* DB; the public-mirror export moves *source code*, not data. The mover (WS-2) is therefore bespoke and is the bulk of the effort.
-
-## Decision
-
-### Locked decisions (owner)
-
-1. **Clean move, not copy.** The platform history *leaves* Off the Boats. No frozen dual copy — two diverging ledgers would double-count balances and rot.
-2. **Game credits stay at Off the Boats.** Everything else — platform credits, including orphan/no-task session & bonus awards — moves.
-3. **Identity is keyed by `builders.github_id`** (a stable global value present in both DBs). The migrated balance surfaces automatically on the builder's *existing* per-instance GitHub sign-in — **no federation hub is required**.
-4. **Currency: the number moves, the label adapts.** The reward unit is the integer `credits`; the label ("drachmae" at OTB, "credits" at the neutral starter) is pure instance config (`branding.currency.label`, ADR-referenced `<redacted>`). A 1,000 balance arrives as 1,000 in cloudbongos's unit automatically. *(Open: whether cloudbongos relabels to "drachmae" — see Open Questions.)*
-5. **The cloudbongos DB is near-empty → clean load, not a merge.** Only `lars589` (auto-seated founding Archon) and one CB-V1 test task exist; preserve them.
-6. **The ETL runs one-time, supervised, from the owner's Mac over SSH**, reaching both droplets' databases. It is not a builder-facing tool.
-
-### Classification is decided at the version level
-
-Every task/goal/criterion/credit inherits its **version's** label. `versions.id` is a text PK, so version rows copy without renumbering.
-
-| MOVE → cloudbongos (platform) | STAY at Off the Boats (game) |
-|---|---|
-| PMS-V1, PMS-V2, GDS-V3, GDS-V4 → BONGOS-V1 and all their tasks/goals/criteria/credits | Off the Boats V1/V2/V3 and their tasks/goals/pixel-art |
-| The dependency graph among those records | Credits earned on game work |
-| A copy of each builder identity (keyed by github_id) carrying the platform balance | The live game world + Colyseus server (untouched) |
-
-Edge cases: work that *built* the art pipeline = platform (moves); *running* it to draw tiles = game (stays) — WS-1 includes a human review pass. Orphan credits (`task_id = NULL`) move with the platform (reversible if the owner disagrees).
-
-## Workstreams (filed under switchover goal 26; execution owner-gated)
-
-- **WS-0 — Re-provision cloudbongos.com onto core 1.17.3 on a fresh DB, FIRST.** The box still runs a lift-and-shift clone whose deploy script references R89-removed paths; a re-provision *after* a load would wipe it. Must precede any data load. Preserve/re-seat the `lars589` Archon.
-- **WS-1 — Label every version game vs platform** (the single line that decides the move-set) + human pass over art-pipeline-style edge cases.
-- **WS-2 — Build the one-time mover (most effort).** Renumber bigint PKs; match builders by `github_id`; remap every FK; handle the polymorphic `dependencies` table per-kind; load with sync/promotion triggers OFF; preserve the `credit_log` idempotency key. **Prove on a throwaway copy first — never run blind on live.**
-- **WS-3 — This ADR.**
-- **WS-4 — Move day (OWNER GREENLIGHT REQUIRED).** Brief platform-write freeze at amazonprimea; full DB snapshots of both sides; run the mover into cloudbongos; rebuild balances from the ledger. Still reversible — amazonprimea untouched until WS-6.
-- **WS-5 — Prove it.** Reconcile record counts both sides; sample balances to the drachma; and the real test — a live GitHub sign-in at cloudbongos shows the right person with the right balance.
-- **WS-6 — Clean cut at Off the Boats.** Only after WS-5: delete the moved records from amazonprimea (reverse FK/dependency order), rebuild amazonprimea balances to game-only, repoint platform doc-links to cloudbongos.
-- **WS-7 — Close the switchover.** Tie off the goal; tell builders where their history now lives.
-
-## DB mechanics (the production hazards the mover must respect)
-
-- **Schema lives in `@bongos/core`** under `package/migrations/*.sql` (not in the amazonprimea repo anymore). `003_pms.sql` is foundational.
-- **Bigserial PK collision.** Both DBs allocate 1,2,3…; a naive copy collides on PK and *silently mis-links* FKs. Collide: `builders/tasks/claims/goals/credit_log/cost_log/karma_log/done_when_criteria/builder_sessions/idea_inbox/learnings/goal_membership_requests/core_upgrades`. Only text/natural PKs copy cleanly (`versions`, `achievements`). People are re-keyed off the natural `builders.github_id` (UNIQUE); everything else gets a fresh offset, and **every FK is rewritten** to the remapped ids.
-- **Polymorphic `dependencies` table — highest risk.** `(from_kind, from_id, to_kind, to_id)` over {task, goal, criterion} has **NO foreign keys** — ids are bare bigints disambiguated only by `*_kind`. The mover must remap `from_id`/`to_id` **per-kind**, or edges silently repoint. (The older `020_task_dependencies` task→task list also needs remapping.)
-- **`credit_log` double-count trap.** `credit_log` is an append-only ledger; `builders.total_credits` is a trigger-maintained cache (`trg_credit_log_apply` → `+= delta` on INSERT). Authoritative balance = `SUM(credit_log.delta)` per builder. **Load with triggers OFF, then rebuild `total_credits` from `SUM(delta)`** — else balances double. Same shape for `karma_log` → `builders.karma`.
-- **Idempotency key must be preserved.** A partial unique index on `credit_log(session_id) WHERE reason='session.token_reward'` enforces one token-reward payout per session. If the index or `session_id` values are lost, the token-reward path **double-pays on replay**.
-- **Promotion triggers also fire on status writes** (auto-promote backlog→ready on ship/satisfy/achieve). Load with all triggers disabled, then re-enable.
-
-## Consequences
-
-- **Positive:** the platform's work-history + rewards live at their true home; builders keep their earned balance across the sign-in they already use; the CB↔OTB separation is completed (data + code); no standing federation infrastructure is incurred.
-- **Reversibility:** everything through WS-5 is reversible — amazonprimea is untouched until WS-6, and both sides are snapshotted on move day. The point of no return is WS-6 (the clean cut).
-- **Risk:** a mistimed trigger or a missed FK/idempotency remap corrupts balances. Mitigation: prove the mover on a throwaway clone (WS-2), triggers-off load + ledger rebuild (WS-4), and full reconciliation before the cut (WS-5).
-
-## Open questions (owner)
-
-1. Confirm the exact game/platform version line (the single decision that fixes the move-set).
-2. Currency label at cloudbongos — keep "credits" or relabel to "drachmae" (one-line config; balances identical either way).
-3. Confirm tracking home for WS-0…WS-7 (proposed: switchover goal 26).
-4. Greenlight to *execute* (WS-4 onward) — nothing runs against production until then.
-5. WS-0 reality check — confirm cloudbongos.com was fully re-provisioned onto core 1.17.3 on a fresh DB, not merely code-updated.
-6. Orphan credits (`task_id = NULL`) — confirm the "move with platform" rule.
-
-### Open questions — RESOLVED (owner, 2026-07-11)
-
-1. Version line: **game V1/V2/V3 stay; PMS-V1, PMS-V2, GDS-V3, GDS-V4, BONGOS-V1 move** (as tabled). 2. Currency: **keep label "credits" at cloudbongos, 1:1 with drachmae** (no relabel). 3. Tracking home: **cloudbongos**. 4. **Greenlight given** — execute through production. 5. WS-0 reality check delegated to the executor → **verified: cloudbongos.com already runs @bongos/core 1.17.4 on the dependency model; no re-provision performed** (would have wiped legit native data). 6. Orphan credits: **move with platform** (confirmed).
-
-## Execution record (2026-07-11)
-
-Executed from the cloudbongos droplet (the ETL host): reads amazonprimea via the live `cohost-db-tunnel` (`127.0.0.1:5433`), writes the local cloudbongos DB. Scripts + full snapshots persist at `/home/lars/mig/` (`mover.js`, `verify.js`, `cut.js`, both pg_dumps, a pre-load cloudbongos snapshot). Tracked as amazonprimea switchover tasks 2192–2198.
-
-- **WS-0 (2192):** verified already-provisioned (core 1.17.4); no re-provision.
-- **WS-1 (2193):** per-table move-set classified (14 platform-history tables; ~50 OTB-instance-infra tables correctly stay).
-- **WS-2 (2194):** mover built (Node ETL: +1,000,000 PK offset; builders merged by `github_id`; versions upsert; deletes the target's core-seeded placeholder platform goals/criteria first; triggers-off load then rebuild `total_credits`/`karma` from `SUM(delta)`; `credit_log` `ON CONFLICT` on the token-reward partial index `DO NOTHING`). **Rehearsed on a throwaway copy: 25/25 checks pass.**
-- **WS-4 (2195):** **live load into cloudbongos COMMITTED** — 1,865 tasks, 27 goals, 69 criteria, 1,678 claims, 1,373 credit rows (1 token-reward idempotency skip), + full history; FK-check clean. Pre-load snapshot taken; amazonprimea untouched (fully reversible).
-- **WS-5 (2196):** **verified on live cloudbongos — 25/25.** All table counts + all six builder balances reconcile (lars589 **37,072**; jaxri 5,341; scootermack 2,389; IAMMASTERQUA 195; LarsCode 44; kingaonline 36). Game/native preserved; 0 FK orphans. `cloudbongos.com` leaderboard serves the migrated builders.
-- **WS-5b (2199) — TIER-2 valuable sweep (post-audit):** a full 59-table completeness audit confirmed the core move was 100% complete (2 flagged gaps were false positives), and surfaced ~13k deferred TIER-2 rows. Owner chose the valuable sweep → `sweep2.js` carried builder_memory, grading history, session_records/BFG, vulnerability_reports, builder_sessions (tokens redacted; restored 1,442 nulled claim links), + governance rows to cloudbongos; **verified 18/18**. Only the rebuildable `search_chunks` retrieval index was intentionally skipped.
-- **WS-6 (2197) — clean cut: FIRED + verified on live amazonprimea.** Pre-fire review found the first-draft cut too aggressive (it would delete live-game learnings/ideas/blockers), so it was rewritten **surgical** (`cut2.js`): deletes only platform-version-scoped work + the platform/orphan credit ledger, and preserves game + unlinked methodology, karma, builder-level tables, and all auth/game data. Run as the non-superuser app user (no trigger-disable) with children-before-parents + FK enforcement (safer). Rehearsed clean on a fresh copy, then fired after a final backup. Result: amazonprimea is game-only (versions V1/V2/V3, 157 game tasks, 123 game claims + auth intact, lars589 38,919→**1,824**, ledger reconciles, 0 platform residue, 0 FK orphans, app healthy).
-- **WS-7 (2198):** data + cut complete. Sole remaining owner step: announce to builders (Discord) where their history now lives.
-
-**Notes:** the migration's own bookkeeping tasks (2192–2199, all BONGOS-V1) moved to cloudbongos and were then removed from amazonprimea by the cut — self-referential, expected; their record lives here + in session memory. The 56-credit token-reward for the shared session `1b57dcb4` is dropped by the idempotency skip. Minor residue intentionally kept on amazonprimea (harmless, also on cloudbongos): platform karma, unlinked ideas/learnings, and vuln/achievement rows with nulled platform refs. Doc-links to platform tasks in the OTB repo now resolve on the cloudbongos hall. Scripts + backups: `/home/lars/mig/` on the cloudbongos droplet.

package/docs/adr/0140-cloudbongos-standalone-reprovision.md

@@ -1,43 +0,0 @@
-# ADR 0140 — cloudbongos.com re-provisioned to the standalone model, DB-preserving (closes ADR 0139 WS-0)
-
-- **Status:** Accepted — executed 2026-07-12
-- **Date:** 2026-07-12
-- **Deciders:** Lars (owner)
-- **Track:** internal (platform / infra)
-- **Builds on:** ADR 0108 (configurable-root / standalone consumer model), ADR 0126 (dedicated cloudbongos.com droplet), ADR 0129 (pull-timer deploy), ADR 0139 (CB↔OTB data migration — this closes its WS-0)
-
-## Context
-
-cloudbongos.com ran as a **lift-and-shift clone of the `amazonprimea` game repo** (ADR 0126): the `cloudbongos` systemd service executed `src/platform-server.js` out of `/home/lars/cloudbongos` (a checkout whose `origin` was `lars589/amazonprimea`), branded via `GDS_BRANDING_FILE`, against the separate `cloudbongos` DB.
-
-ADR 0139's **WS-0** called for re-provisioning cloudbongos.com onto the ADR 0108 standalone `@bongos/core` model *first, on a fresh DB*. WS-0 was recorded as "verified already-provisioned; no re-provision performed" — but that verification was wrong: the box kept running the amazonprimea clone. The data-half workstreams (WS-4/5/6) then loaded the platform history into the `cloudbongos` DB and cut OTB.
-
-The gap surfaced on 2026-07-12: `builders.cloudbongos.com` served a bare, unstyled shell — every `/builders/*` asset 404'd. Root cause: the running process was frozen on stale amazonprimea code (its pull-deploy silently no-op'd because `origin` tracked the unchanged amazonprimea repo, not a cloudbongos instance). The site had **never run the restored code**.
-
-The key constraint that inverts WS-0's original plan: the `cloudbongos` DB is now **full** — the migrated work-history and credit balances (e.g. `lars589` = 37,072). WS-0's "fresh DB" re-provision would wipe it. So the re-provision had to be **DB-preserving**.
-
-## Decision
-
-We will convert cloudbongos.com to a proper ADR 0108 **standalone instance**, preserving the existing `cloudbongos` DB, via a **build-alongside-then-flip** procedure:
-
-1. **Its own instance repo** — `cloudbongos/cloudbongos-instance` (private): lean `config/` (`branding.json` = the real cloudbongos.com domains over the neutral "Cloud Bongos" brand; `modules.json` = game-less + `provisioning`), a `bongos.config.json` instance-root pointer, and a **pinned `@bongos/core@1.17.3`** dependency. The engine, hall, and all platform code come from the package.
-2. **Materialize beside the old checkout** — clone + `npm ci` into a new dir (`/home/lars/cloudbongos-instance`); the old `/home/lars/cloudbongos` stays untouched as rollback.
-3. **Prove before flipping** — boot on a spare port against the live DB; confirm the hall serves and the leaderboard reads migrated balances; confirm `migrate` is a **no-op** (the DB already carries all 112 of 1.17.3's migrations).
-4. **Flip the service** — `cloudbongos.service` `WorkingDirectory` → the instance, `ExecStart` → `node_modules/@bongos/core/src/platform-server.js`; drop `GDS_BRANDING_FILE`; add `CLOUDBONGOS_INSTANCE_ROOT`; keep `PGDATABASE` + OAuth via `/etc/cloudbongos/web.env`. Back up the old unit first.
-5. **Repoint the ADR 0129 pull-deploy** — rewrite `/home/lars/deploy.sh` to fetch/reset the instance repo → `npm ci` (lockfile-gated) → core-package `migrate` → restart → healthz.
-
-The engine **source stays authoritative at `lars589/cloud-bongos`** (not relocated); the instance consumes `@bongos/core` from npm. A **verified DB backup precedes all changes**, and the old checkout + old unit + old deploy script are retained for instant rollback.
-
-## Alternatives considered
-
-- **Run cloudbongos.com directly from the `cloud-bongos` engine repo.** Rejected: it forces one host's identity into the shared/authoritative engine (the very anti-pattern that entangled cloudbongos with the amazonprimea repo), and it would ride the engine's development `main` with no stable pin — any work-in-progress commit could take the live site down.
-- **Keep the amazonprimea lift-and-shift; just restart / repoint that checkout.** Rejected: leaves the intended standalone model unfinished and keeps cloudbongos coupled to the OTB repo.
-- **Vanilla WS-0 (fresh-DB re-provision).** Rejected now: it would wipe the freshly-migrated history and balances — the whole point of ADR 0139. Hence the DB-preserving variant.
-- **Reuse an existing repo for the site** — `cloud-bongos` (the engine) or `cloudbongos/bongos` (the public AGPL source mirror). Rejected: both hold load-bearing roles; a dedicated `cloudbongos/cloudbongos-instance` keeps host identity out of both.
-
-## Consequences
-
-- cloudbongos.com runs the clean standalone model: hall renders, all three hosts (apex/builders/status) healthy, DB + balances intact. Future platform updates are a one-line `@bongos/core` pin bump, auto-deployed within ~2 min by the repointed pull-timer.
-- **Closes ADR 0139 WS-0** (belatedly, in DB-preserving form).
-- Deploy keys had to be **enabled org-wide on the `cloudbongos` org** so the box's read-only deploy key could attach to an org repo (they were disabled by default).
-- Follow-ups (non-blocking): retire `/home/lars/cloudbongos` + the backups after a soak; version `/home/lars/deploy.sh` into the instance repo and restore the ADR 0129 self-heal step; the packaged engine's `CORE_VERSION` constant lags its `package.json` (reports 1.17.2 while running 1.17.3) — cosmetic, flag upstream.

package/scripts/hall-preview/fixtures/access-requests.json

@@ -1,20 +0,0 @@
-{
-  "requests": [
-    {
-      "id": "901",
-      "display_name": "Preview Applicant",
-      "github_login": "preview-applicant",
-      "note": "Synthetic access request for the preview harness.",
-      "created_at": "2026-07-08T14:02:00.000Z",
-      "status": "pending"
-    },
-    {
-      "id": "902",
-      "display_name": null,
-      "github_login": "sample-builder",
-      "note": null,
-      "created_at": "2026-07-09T09:41:00.000Z",
-      "status": "pending"
-    }
-  ]
-}

package/scripts/hall-preview/fixtures/achievements.json

@@ -1,76 +0,0 @@
-{
-  "achievements": [
-    {
-      "id": "first-ship",
-      "name": "First Ship",
-      "description": "Ship your first task.",
-      "icon": "📦",
-      "credit_bonus": 1,
-      "sort_order": 10
-    },
-    {
-      "id": "first-claim",
-      "name": "First Claim",
-      "description": "Claim your first task.",
-      "icon": "🪙",
-      "credit_bonus": 1,
-      "sort_order": 20
-    },
-    {
-      "id": "first-parallel-claim",
-      "name": "First Parallel Claim",
-      "description": "Hold two simultaneous claims; ship both successfully.",
-      "icon": "⚓",
-      "credit_bonus": 2,
-      "sort_order": 30
-    },
-    {
-      "id": "streak-3",
-      "name": "Streak: 3 Nights",
-      "description": "Ship a task in 3 consecutive local-time nights (>=15min; cleanup/refactor now counts).",
-      "icon": "🔥",
-      "credit_bonus": 2,
-      "sort_order": 40
-    },
-    {
-      "id": "streak-7",
-      "name": "Streak: 7 Nights",
-      "description": "Ship a task in 7 consecutive local-time nights (>=15min; cleanup/refactor now counts).",
-      "icon": "🌋",
-      "credit_bonus": 5,
-      "sort_order": 50
-    },
-    {
-      "id": "art-pipeline-shipper",
-      "name": "Art Pipeline Shipper",
-      "description": "Ship a task whose touches[] include the art/ pipeline.",
-      "icon": "🎨",
-      "credit_bonus": 2,
-      "sort_order": 60
-    },
-    {
-      "id": "subtractor",
-      "name": "Subtractor",
-      "description": "Earn the net-negative ship bonus on 3 ships — across your work you have deleted more than you have added.",
-      "icon": "🪓",
-      "credit_bonus": 2,
-      "sort_order": 65
-    },
-    {
-      "id": "gds-shipper",
-      "name": "GDS Shipper",
-      "description": "Ship a task whose touches[] include src/gds/ or scripts/gds/.",
-      "icon": "⚙️",
-      "credit_bonus": 2,
-      "sort_order": 70
-    },
-    {
-      "id": "breaking-the-100c-bar",
-      "name": "Breaking the 100c Bar",
-      "description": "Cross 100 total credits.",
-      "icon": "💯",
-      "credit_bonus": 5,
-      "sort_order": 80
-    }
-  ]
-}