@bongos/core 1.19.971 → 1.19.973

package/scripts/hall-preview/server.js

@@ -123,6 +123,11 @@ const FIXTURE_FALLBACKS = [
   // the profile's connections section (task 1002296) — one degree fixture serves
   // any handle, since the handle is the address and the label is the payload.
   [/^connections\/degree\/[^/]+$/, 'connections__degree'],
+  // the deploy door's per-project preview (task 1004171). One fixture serves any id
+  // because the page renders ONE project and the id is the address, not the payload —
+  // without it /deploy?project=… only ever rendered its "could not read" state, which
+  // is the trap this directory's README calls out by name.
+  [/^provisioning\/instances\/\d+\/core-upgrade$/, 'provisioning__instances__core-upgrade'],
 ];
 
 // A DATE THAT ROTS CANNOT DEMO AN AGE SIGNAL (task 1004041). The help-request

package/src/bongos/module-scope-map.js

@@ -451,6 +451,7 @@ const MODULE_GLOBS = {
     'scripts/gds/fitness-checks-packaging.js', 'scripts/gds/fitness-checks-route-pins.js',
     'scripts/gds/fitness-checks-vocabulary.js', 'scripts/gds/fitness-checks-write-validation.js',
     'scripts/gds/fitness-migration-contraction.js', 'scripts/gds/role-pack-guard.js',
+    'scripts/gds/scope-roster-guard.js',
     'scripts/gds/route-shadow-guard.js', 'scripts/gds/routine-schedule.js',
     'scripts/gds/seam-wiring-guard.js', 'scripts/gds/skill-preflight.js',
     'scripts/gds/test-path-guard.js', 'scripts/gds/version-literal-guard.js',

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.971'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.973'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/api_alias_caller_ratchet.mjs

@@ -39,7 +39,7 @@ test('a collapsed enumeration is visible as scanned=0, not as a flattering total
 
   const allExcluded = scan.scanAliasCallers(fake({
     'tests/x.mjs': '/api/gds\n',
-    'docs/x.md': '/api/gds\n',
+    'docs/adr/0001-x.md': '/api/gds\n', // frozen record — NOT `docs/x.md`, which counts since task 1004113
   }));
   assert.equal(allExcluded.total, 0);
   assert.equal(allExcluded.scanned, 0, 'an every-path-excluded run is also scanned=0 — the same signal');
@@ -67,7 +67,11 @@ test('the exclusions are real and each one is reachable', () => {
     'scripts/gds/api-alias-caller-scan.js',
     'tests/api_alias_exceptions.mjs',      // 5 tests
     'modules/dev-box/app/test/thing.mjs',
-    'docs/architecture.md',                // 6 docs
+    'docs/adr/0016-permissions.md',        // 6 the FROZEN RECORD under docs/ (narrowed, task 1004113)
+    'docs/session-logs/2026-09-16-x.md',
+    'docs/audits/2026-08-01-x.md',
+    'docs/governance/authority-sweep-2026-07-24.md',
+    'docs/recipes/failed-ship-recovery-proof.md',
     'migrations/033_audit_log.sql',        // 7 migrations
     'scripts/hall-preview/fixtures/tasks.json', // 9 captured fixtures
     'node_modules/pkg/index.js',           // vendored
@@ -81,11 +85,58 @@ test('the exclusions are real and each one is reachable', () => {
     'clients/bongos-client/index.mjs', // a .mjs that is NOT a test — a blanket \.mjs$ would blind the ratchet
     'bin/bongos.js',
     'CLAUDE.md',
+    // task 1004113: live instruction under docs/ is counted. If this list ever goes back to being
+    // excluded, the ~95 occurrences the sweep moved can silently grow back unpoliced.
+    'docs/architecture.md',
+    'docs/canonical-permissions.md',
+    'docs/recipes/parallel-goal-waves.md',
+    'docs/packs/engineer.md',
+    'docs/onboarding/drachmae-and-karma.md',
   ]) {
     assert.equal(scan.isExcludedPath(p), false, `${p} must NOT be excluded`);
   }
 });
 
+// ---------------------------------------------------------------------------
+// task 1004113 — the docs/ split. This is the case the parent task (1004064)
+// deferred, and it is proved in BOTH directions on purpose: a narrowing that
+// only asserts "the frozen record is excluded" would pass identically if the
+// blanket `docs/` exclusion were still in place, which is exactly the vacuous
+// shape this file's header warns about.
+// ---------------------------------------------------------------------------
+
+test('docs/ is SPLIT: the frozen record stays out, live instruction is now counted', () => {
+  const r = scan.scanAliasCallers(fake({
+    'docs/adr/0010-pms-architecture.md': 'GET /api/gds/tasks\n',
+    'docs/session-logs/2026-09-16-x.md': 'GET /api/gds/tasks\n',
+    'docs/audits/2026-08-01-x.md': 'GET /api/gds/tasks\n',
+    'docs/governance/rank-map-2026-08-06.md': 'GET /api/gds/tasks\n',
+    'docs/recipes/failed-ship-recovery-proof.md': 'POST /api/gds/claims/1/resolve\n',
+    'docs/recipes/how-to-do-a-thing.md': 'node scripts/gds/api.js GET /api/gds/tasks/1\n',
+    'docs/packs/engineer.md': 'create a task via POST /api/gds/tasks\n',
+  }));
+  assert.deepEqual(
+    Object.keys(r.byFile).sort(),
+    ['docs/packs/engineer.md', 'docs/recipes/how-to-do-a-thing.md'],
+    'only the instructional docs count — and they MUST count, or the narrowing did nothing',
+  );
+  assert.equal(r.total, 2);
+  assert.equal(r.scanned, 2, 'the frozen-record files are excluded before they are read, not counted as zero');
+});
+
+test('the rename-history floors all sit INSIDE the excluded subtrees — the line is measured, not asserted', () => {
+  // The narrowing's load-bearing evidence: rename-history-check.js fails the build when the old
+  // name is ERASED from a file with a floor, so a docs sweep could have failed a DIFFERENT gate.
+  // It did not, because every floor is in a subtree this scanner still excludes. If a floor is ever
+  // added outside them, this reds and whoever added it has to decide which gate wins.
+  const floors = Object.keys(
+    JSON.parse(readFileSync(path.join(ROOT, 'config', 'rename-history-baseline.json'), 'utf8')).frozenLiteralFloors || {},
+  );
+  assert.ok(floors.length > 100, `the baseline must actually carry floors (got ${floors.length})`);
+  const outside = floors.filter((f) => !scan.isExcludedPath(f));
+  assert.deepEqual(outside, [], 'a file with a rename-history floor must never be inside the caller ratchet');
+});
+
 test('a line ABOUT the alias is not a caller of it — and the rule is not so loose it excuses everything', () => {
   // Excluded: names the canonical prefix too, or says what it is.
   assert.equal(scan.isCountedLine('mount /api/bongos and /api/gds'), false);
@@ -100,6 +151,21 @@ test('a line ABOUT the alias is not a caller of it — and the rule is not so lo
   assert.equal(scan.isCountedLine('a line about a legacy alias, forever'), false);
 });
 
+test('a PINNED auth URL is not a caller anyone may move (rule 10, task 1004113)', () => {
+  // These are registered in GitHub's OAuth app settings. A recipe that teaches a builder to
+  // register /api/bongos/auth/web/callback breaks sign-in on the instance they are standing up,
+  // so the ratchet must never create pressure to rewrite them.
+  assert.equal(scan.isCountedLine('  https://example.com/api/gds/auth/web/callback'), false);
+  assert.equal(scan.isCountedLine('the server sends `${publicOrigin}/api/gds/auth/web/callback`'), false);
+  assert.equal(scan.isCountedLine('`/api/gds/auth/web/start` = no session'), false);
+  // …and prose ABOUT that URL, which names the prefix without the /auth/ segment. Sweeping this
+  // heading left it contradicting its own body two lines down; caught in review on 1004113.
+  assert.equal(scan.isCountedLine('### Authorized callback URL must include the full /api/gds path'), false);
+  // The rule is NOT so wide that an ordinary caller in an auth-adjacent file escapes it.
+  assert.equal(scan.isCountedLine('node scripts/gds/api.js GET /api/gds/me'), true);
+  assert.equal(scan.isCountedLine('POST /api/gds/auth-free/thing'), true, 'only the /auth/ segment, not any word starting auth');
+});
+
 test('occurrences are counted, not lines — moving ONE of two callers on a line lowers the number', () => {
   assert.equal(scan.countInText('f("/api/gds/a"); f("/api/gds/b");\n'), 2);
   assert.equal(scan.countInText('f("/api/bongos/a"); f("/api/gds/b");\n'), 0, 'the canonical name on the line is the alias-commentary rule, by design');

package/tests/core_upgrade_door.mjs

@@ -756,5 +756,86 @@ await t('lastCoreMove reads MOVES only — a preview refusal is not a failed dep
   assert.deepEqual(seen[0].params, [41]);
 });
 
+
+console.log('\nthe change list is withheld when the box has moved since (task 1004173):');
+
+const PF = (over = {}) => ({ target: '1.19.949', ok: true, lines: [], error: null,
+  changes: { from: '1.19.900', to: '1.19.949', entries: [{ text: 'a thing landed' }], more: 0 }, ...over });
+
+await t('a verdict taken from where the box IS keeps its change list', () => {
+  const p = CU.previewFromSnapshot(ACTIVE, { ...SNAP, preflight: PF() }, null, null);
+  assert.equal(p.preflight.changes.entries.length, 1);
+});
+
+await t('THE LIST GOES WHEN THE BOX HAS MOVED — the verdict beside it does NOT', () => {
+  // Two independent staleness questions. The verdict is about a TARGET; the list is
+  // about a RANGE, so it also depends on where the box starts. Dropping both would throw
+  // away a good verdict; dropping neither would show a range starting somewhere the box
+  // no longer is.
+  const p = CU.previewFromSnapshot(ACTIVE, { ...SNAP, served_version: '1.19.930', preflight: PF() }, null, null);
+  assert.equal(p.preflight.changes, null, 'the range no longer starts where the box is');
+  assert.equal(p.preflight.ok, true, 'but the check is still a true answer about this target');
+  assert.equal(p.preflight.target, '1.19.949');
+});
+
+await t('a verdict about a SUPERSEDED target is withheld whole, list and all', () => {
+  const p = CU.previewFromSnapshot(ACTIVE, { ...SNAP, preflight: PF({ target: '1.19.920' }) }, null, null);
+  assert.equal(p.preflight, null, 'a stale pass reads as a guarantee — worse than no answer');
+});
+
+await t('withholding does not MUTATE the cached verdict', () => {
+  // previewFromSnapshot runs per request over a row the caller may reuse; blanking the
+  // list in place would make the second reader see a range the first one invalidated.
+  const snap = { ...SNAP, served_version: '1.19.930', preflight: PF() };
+  CU.previewFromSnapshot(ACTIVE, snap, null, null);
+  assert.ok(snap.preflight.changes, 'the snapshot is untouched');
+});
+
+console.log('\nis the last move still NEWS, or history the box moved past? (task 1004172):');
+
+await t('a failure the box has already moved past is marked superseded', () => {
+  // The live defect, 2026-09-22: the control plane's row led with "The move to core
+  // 1.19.921 did not land", undated, while the box served 1.19.969 and a move to
+  // 1.19.972 was on offer. Two days old, a different target, and a cause fixed and
+  // released in between — all of it rendered as the present.
+  const old = { action: 'core-upgrade', state: 'error', target_version: '1.19.921', resolved_at: new Date().toISOString(), last_error: 'Postgres has no role "root"' };
+  const p = CU.previewFromSnapshot(ACTIVE, SNAP, null, old);
+  assert.equal(p.last_move.superseded, true, 'a different move is on offer now');
+});
+
+await t('a failure against the move STILL on offer is NOT superseded', () => {
+  const now = { action: 'core-upgrade', state: 'error', target_version: '1.19.949', resolved_at: new Date().toISOString(), last_error: 'working tree not clean' };
+  const p = CU.previewFromSnapshot(ACTIVE, SNAP, null, now);
+  assert.equal(p.last_move.superseded, false, 'this is the button in front of the owner');
+});
+
+await t('a box that reached the target by another road supersedes the failure', () => {
+  // The exact shape of the live case: the move failed, and the version arrived anyway.
+  const old = { action: 'core-upgrade', state: 'error', target_version: '1.19.949', resolved_at: new Date().toISOString(), last_error: 'x' };
+  const p = CU.previewFromSnapshot(ACTIVE, { ...SNAP, served_version: '1.19.949', recommended: '1.19.949' }, null, old);
+  assert.equal(p.last_move.superseded, true);
+});
+
+await t('AN UNREADABLE REGISTRY LEAVES A FAILURE STANDING — not knowing is not evidence of recovery', () => {
+  const now = { action: 'core-upgrade', state: 'error', target_version: '1.19.949', resolved_at: new Date().toISOString(), last_error: 'x' };
+  const p = CU.previewFromSnapshot(ACTIVE, { ...SNAP, recommended: null }, null, now);
+  assert.equal(p.last_move.superseded, false, 'the direction to fail in is showing an old failure, never hiding a live one');
+});
+
+await t('lastMoveSuperseded computes no version ORDERING — only identity', () => {
+  // The page's standing rule is that no version comparison happens outside the runner's
+  // channel resolution. This helper answers "is this news" without ever asking which of
+  // two versions is newer, and the source is held to that.
+  const src = read('modules', 'provisioning', 'core-upgrade.js');
+  const body = /function lastMoveSuperseded\([^)]*\) \{([\s\S]*?)\n\}/.exec(src);
+  assert.ok(body, 'the helper is there to read');
+  assert.doesNotMatch(body[1], /parseVersion|semver|split\(/, 'no version parsing');
+  assert.doesNotMatch(body[1], /[<>]=?/, 'and no ordering comparison');
+  // And it is genuinely reachable both ways from the same inputs.
+  assert.equal(CU.lastMoveSuperseded(null, '1.19.900', '1.19.949'), false, 'no target is not superseded');
+  assert.equal(CU.lastMoveSuperseded('1.19.949', '1.19.900', '1.19.949'), false);
+  assert.equal(CU.lastMoveSuperseded('1.19.921', '1.19.900', '1.19.949'), true);
+});
+
 console.log(`\ncore_upgrade_door: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);

package/tests/core_upgrade_runner.mjs

@@ -836,5 +836,137 @@ await t('and a silent failure STILL refuses rather than inventing a pass', async
   assert.match(v.error, /said nothing/);
 });
 
+
+console.log('\nwhat the move would CARRY, not just whether it is allowed (task 1004173):');
+
+// The two merge shapes a real core history holds, as `git log --merges
+// --format=%s%x1f%b%x1e` emits them. The second shape is the COMMON one: measured over
+// 1.19.881→1.19.972, 98 of 114 usable summaries came from the CI auto-merge's body.
+const REC = (subject, body = '') => `${subject}\x1f${body}\x1e`;
+const LOG = [
+  REC('Merge scoperoster-1002900: The build now catches a missing registration at the moment it happens.'),
+  REC('Merge pull request #1108 from an-owner/task-1004167', 'task 1004167: Groundwork for letting an owner make their code repository private.\n'),
+  REC('Merge origin/main into scoperoster-1002900 (pre-stage freshness, task 1068)'),
+  REC('Merge remote-tracking branch \'origin/main\' into errshape-1003658'),
+  REC('Merge pull request #1107 from an-owner/task-1001621'),
+  REC('chore: regen repo-map after merge'),
+].join('');
+
+await t('BOTH merge shapes are read — the CI auto-merge carries its summary in the BODY', () => {
+  const out = R.parseChangeRecords(LOG);
+  assert.equal(out.length, 2, `two usable summaries — got ${JSON.stringify(out)}`);
+  assert.match(out[0].text, /catches a missing registration/, 'the hand-landed shape, from the subject');
+  assert.equal(out[1].id, '1004167', 'and the CI shape, from the body, with its task id');
+  assert.match(out[1].text, /make their code repository private/);
+});
+
+await t('the mechanics of landing are DROPPED — they are not the work', () => {
+  // Over a real range these outnumber the summaries roughly ten to one, so listing them
+  // buries every sentence the owner wants.
+  const out = R.parseChangeRecords(LOG).map((e) => e.text).join(' | ');
+  assert.doesNotMatch(out, /pre-stage freshness/);
+  assert.doesNotMatch(out, /remote-tracking/);
+  assert.doesNotMatch(out, /regen repo-map/);
+  assert.doesNotMatch(out, /pull request/, 'a merge with no body summary contributes nothing');
+});
+
+await t('a branch merged twice says its sentence once', () => {
+  const dup = LOG + REC('Merge scoperoster-1002900: The build now catches a missing registration at the moment it happens.');
+  assert.equal(R.parseChangeRecords(dup).length, 2);
+});
+
+await t('a paragraph-long summary is bounded — it reaches a DOM', () => {
+  const out = R.parseChangeRecords(REC(`Merge x-1: ${'y'.repeat(5000)}`));
+  assert.ok(out[0].text.length <= 400, `bounded — got ${out[0].text.length}`);
+  assert.match(out[0].text, /…$/, 'and says it was cut');
+});
+
+// --- the range, and every way it can fail to resolve ------------------------------
+
+const changeDeps = ({ shas = { '1.19.900': 'a'.repeat(40), '1.19.949': 'b'.repeat(40) }, log = LOG, logOk = true } = {}) => {
+  const ran = [];
+  return {
+    ran,
+    selfInstanceRoot: () => '/srv/core',
+    exec: (cmd) => {
+      ran.push(cmd);
+      const m = /--grep='release: core ([0-9.]+) '/.exec(cmd);
+      if (m) return { ok: true, stdout: `${shas[m[1]] || ''}\n` };
+      if (!logOk) return { ok: false, softFailed: true, stdout: '' };
+      return { ok: true, stdout: log };
+    },
+  };
+};
+
+await t('the range resolves through the release commits and lists what landed between', () => {
+  const d = changeDeps();
+  const r = R.changesBetween('1.19.900', '1.19.949', d);
+  assert.equal(r.error, undefined);
+  assert.equal(r.from, '1.19.900');
+  assert.equal(r.to, '1.19.949');
+  assert.equal(r.entries.length, 2);
+  assert.ok(d.ran.some((c) => /--merges/.test(c) && /a{40}\.\.b{40}/.test(c)), 'the log is asked for the resolved range');
+});
+
+await t('IT READS THE CONTROL PLANE’S OWN CHECKOUT, whichever instance is previewed', () => {
+  // A tenant's directory is a checkout of the TENANT's repo with the core vendored in
+  // from npm — no core history in it, and the wrong history if you squint. Under
+  // PROVISION_REMOTE_HOST `exec` is the remote box, so the executor matters too.
+  const d = changeDeps();
+  d.controlExec = d.exec;
+  d.exec = () => { throw new Error('the instance executor must not be used for core history'); };
+  const r = R.changesBetween('1.19.900', '1.19.949', d);
+  assert.equal(r.entries.length, 2);
+  for (const c of d.ran) assert.match(c, /git -C \/srv\/core /, 'always the control plane’s own core checkout');
+});
+
+await t('A RANGE THAT CANNOT BE RESOLVED IS AN ERROR, NEVER AN EMPTY LIST', () => {
+  // An empty list reads as "nothing changed", which over ninety-one releases is the one
+  // wrong impression this section could give — and it is the shape a missing checkout,
+  // a shallow clone or an unknown release all take.
+  const missing = R.changesBetween('1.19.900', '9.9.9', changeDeps());
+  assert.equal(missing.entries, undefined, 'no list at all');
+  assert.match(missing.error, /could not find those releases/);
+
+  const unreadable = R.changesBetween('1.19.900', '1.19.949', changeDeps({ logOk: false }));
+  assert.equal(unreadable.entries, undefined);
+  assert.match(unreadable.error, /could not read the core history/);
+});
+
+await t('a version that is not three numbers never reaches the shell', () => {
+  const d = changeDeps();
+  const r = R.changesBetween("1.19.900'; rm -rf /; echo '", '1.19.949', d);
+  assert.match(r.error, /could not work out which releases/);
+  assert.deepEqual(d.ran, [], 'and nothing was run at all');
+  assert.match(R.changesBetween(null, '1.19.949', changeDeps()).error, /could not work out/, 'an unknown starting point too');
+});
+
+await t('a long range is capped, and says how many it did not list', () => {
+  const many = Array.from({ length: R.CHANGE_CAP + 5 }, (_, i) => REC(`Merge b-${i}: summary number ${i}`)).join('');
+  const r = R.changesBetween('1.19.900', '1.19.949', changeDeps({ log: many }));
+  assert.equal(r.entries.length, R.CHANGE_CAP);
+  assert.equal(r.more, 5, 'the remainder is counted, not silently dropped');
+});
+
+await t('the dry run records the list beside the verdict, keyed to where the box IS', async () => {
+  // Both answers are about ONE move, so they are stored together — and `from` is stored
+  // with them because the list is only true of that starting point.
+  const d = makeDeps({ served: '1.19.762' });
+  d.queries.length = 0;
+  d.db = { query: async (sql, params) => {
+    d.queries.push({ sql, params });
+    if (/SELECT served_version/.test(sql)) return { rows: [{ served_version: '1.19.900' }] };
+    return { rows: [] };
+  } };
+  d.preflightUpgrade = () => ({ target: '1.19.949', ok: true, lines: [], error: null });
+  d.changesBetween = (from, to) => ({ from, to, entries: [{ text: 'a thing landed' }], more: 0 });
+  await R.preflightCoreUpgrade(inst(), d, intent({ target_version: '1.19.949' }));
+  const write = d.queries.find((q) => /INSERT INTO provisioning_core_version_snapshot/.test(q.sql));
+  const stored = JSON.parse(String(write.params[1]));
+  assert.equal(stored.changes.from, '1.19.900', 'the version the box is on right now');
+  assert.equal(stored.changes.to, '1.19.949');
+  assert.equal(stored.changes.entries[0].text, 'a thing landed');
+});
+
 console.log(`\ncore_upgrade_runner: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);