@bongos/core 1.19.1032 → 1.19.1033

package/tests/db_backup_offsite.mjs

@@ -0,0 +1,81 @@
+// tests/db_backup_offsite.mjs — the weekly offsite copy sizes what it ships the same way
+// on every platform (task 1004170).
+//
+// THE BUG. db-backup-offsite.sh read both of its sizes — the local dump it picks and the
+// ciphertext it uploads — with GNU-only `stat -c '%s'`, which BSD/macOS stat refuses
+// outright. Every run on a Mac died before it encrypted anything, and CI's Linux never
+// saw it, because nothing ran the script at all. The empty-ciphertext guard rides on the
+// second of those sizes, so it is pinned here too.
+//
+// The script runs for real under macOS-shaped `stat` and `wc` (tests/helpers.mjs), with
+// stub `age` and `python3` first on PATH: nothing is encrypted, no bucket is touched and
+// no network is used.
+//
+// Run:  node --test tests/db_backup_offsite.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { macShapedTools } from './helpers.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SCRIPT = path.join(ROOT, 'scripts', 'gds', 'db-backup-offsite.sh');
+const skip = process.platform === 'win32' ? 'needs a POSIX bash + coreutils (runs in CI)' : false;
+// The script's env-var prefix, built rather than written — the same reason as in
+// tests/db_backup_nightly.mjs: the legacy-literal ratchet counts the spelled-out form.
+const ENV = 'gds_'.toUpperCase();
+
+const DUMP_NAME = 'smallproj-2026-09-20T000000Z.sql.gz';
+const DUMP = '--\n-- PostgreSQL database dump complete\n--\n';
+const CIPHER = 'age-encryption.org/v1\n-> X25519 stub\n';
+
+// `cipher` is what the stub age writes to its -o file. The stub python3 answers the
+// boto3 probe and, for the upload program, records the object key it was handed.
+function runOffsite({ cipher = CIPHER } = {}) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'db-offsite-'));
+  const bin = path.join(tmp, 'bin');
+  const dir = path.join(tmp, 'backups');
+  const uploads = path.join(tmp, 'uploads.log');
+  fs.mkdirSync(bin);
+  fs.mkdirSync(dir);
+  macShapedTools(bin);
+  fs.writeFileSync(path.join(dir, DUMP_NAME), DUMP);
+  fs.writeFileSync(path.join(tmp, 'cipher'), cipher);
+  fs.writeFileSync(path.join(bin, 'age'),
+    `#!/bin/bash\nwhile [ $# -gt 0 ]; do [ "$1" = -o ] && out="$2"; shift; done\ncp "${path.join(tmp, 'cipher')}" "$out"\n`, { mode: 0o755 });
+  fs.writeFileSync(path.join(bin, 'python3'),
+    `#!/bin/bash\n[ "$1" = -c ] && exit 0\ncat > /dev/null\necho "$${ENV}OFFSITE_KEY" >> "${uploads}"\n`, { mode: 0o755 });
+  const r = spawnSync('bash', [SCRIPT], {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      PATH: `${bin}:${process.env.PATH}`,
+      [`${ENV}BACKUP_DB`]: 'smallproj',
+      [`${ENV}BACKUP_DIR`]: dir,
+      [`${ENV}SPACES_ENV`]: path.join(tmp, 'no-such-spaces.env'),
+      [`${ENV}OFFSITE_AGE_RECIPIENT`]: 'age1stubrecipient',
+      SPACES_KEY: 'k', SPACES_SECRET: 's', SPACES_BUCKET: 'b', SPACES_REGION: 'r', SPACES_ENDPOINT: 'https://example.invalid',
+    },
+  });
+  const sent = fs.existsSync(uploads) ? fs.readFileSync(uploads, 'utf8').split('\n').filter(Boolean) : [];
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr, sent };
+}
+
+test('it sizes the dump and its ciphertext on macOS as on Linux, then ships it (task 1004170)', { skip }, () => {
+  const r = runOffsite();
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, new RegExp(`\\(${Buffer.byteLength(DUMP)} bytes → ${Buffer.byteLength(CIPHER)} encrypted\\)`),
+    'both sizes are the real byte counts, unpadded');
+  assert.deepEqual(r.sent, [`gds-offsite/${DUMP_NAME}.age`]);
+});
+
+test('an empty ciphertext is refused, never uploaded as a backup', { skip }, () => {
+  const r = runOffsite({ cipher: '' });
+  assert.equal(r.status, 2, r.stderr);
+  assert.match(r.stderr, /encryption produced an empty file/);
+  assert.deepEqual(r.sent, [], 'nothing reached the bucket');
+});

package/tests/hall_records.mjs

@@ -0,0 +1,85 @@
+// tests/hall_records.mjs — the hall's page records live one file per family (task 1003499).
+//
+// WHY. modules/hall-ui/CLAUDE.md used to carry every page family's "**The X landed
+// next (task N)**" record, each appended immediately above the same heading. So every
+// concurrent hall task inserted at the SAME line and collided with every other one —
+// the file needed five hand-resolved merges in September 2026 alone, and each new
+// record made the next collision likelier. Git cannot conflict on two branches that
+// each ADD a file, so the records moved to modules/hall-ui/records/, one per family,
+// and CLAUDE.md keeps a pointer. This pins the convention, so the next record lands
+// as a file rather than as a fifteenth section of the one file every hall task edits.
+//
+// Run:  node tests/hall_records.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const DOC = path.join(ROOT, 'modules/hall-ui/CLAUDE.md');
+const DIR = path.join(ROOT, 'modules/hall-ui/records');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+const doc = fs.readFileSync(DOC, 'utf8').replace(/\r\n/g, '\n');
+const records = fs.existsSync(DIR) ? fs.readdirSync(DIR).filter((f) => f.endsWith('.md')).sort() : [];
+
+// The shape every record took: a bold lead-in naming a page family and saying it
+// "landed" (first / next / last / at / on). Anchored to a line start so prose that
+// merely uses the word stays legal.
+const RECORD_LEAD = /^\*\*(?:The|THE)\b[^*\n]*\blanded\b/gm;
+
+test('the hall doc carries no page record of its own', () => {
+  const leads = doc.match(RECORD_LEAD) || [];
+  assert.deepEqual(leads, [],
+    'a page record was added to modules/hall-ui/CLAUDE.md — give it its own file in modules/hall-ui/records/ instead (task 1003499)');
+});
+
+test('the hall doc points at the records, and says a new one is a new file', () => {
+  const at = doc.indexOf('### Page records');
+  assert.ok(at > 0, 'the "### Page records" pointer is gone, so nothing tells an agent the records exist');
+  const pointer = doc.slice(at, doc.indexOf('\n### ', at + 1));
+  assert.match(pointer, /\]\(records\/\)/, 'the pointer links the records directory');
+  assert.match(pointer, /head -n 1 modules\/hall-ui\/records\/\*\.md/, 'and says how to find the record for a page');
+  assert.match(pointer, /adds a NEW file/, 'and says a new record is a new file, not a new section here');
+});
+
+test('the records directory holds the records', () => {
+  assert.ok(records.length >= 11, `expected the moved records in modules/hall-ui/records/, found ${records.length}`);
+});
+
+test('every record opens with a one-line title naming its pages and its task', () => {
+  // `head -n 1 records/*.md` is the index — there is deliberately no hand-kept list,
+  // because a list every record appends to would be the same collision in a new place.
+  for (const f of records) {
+    const text = fs.readFileSync(path.join(DIR, f), 'utf8').replace(/\r\n/g, '\n');
+    const [first, blank, ...rest] = text.split('\n');
+    assert.match(first, /^# \S/, `${f}: line 1 must be the "# " title that head -n 1 lists`);
+    assert.match(first, /\btasks? \d{7}\b/, `${f}: the title names the task(s) the record belongs to`);
+    assert.equal(blank, '', `${f}: a blank line follows the title`);
+    assert.ok(rest.join('\n').trim().length > 200, `${f}: the record has a body`);
+    assert.equal((text.match(/^# /gm) || []).length, 1, `${f}: one title per file — a second one is a second record`);
+  }
+});
+
+test('every relative link in a record resolves from records/', () => {
+  // records/ sits one folder below CLAUDE.md, so a section copied out of it with its
+  // `../../docs/...` links intact points one level short — the trap this move met.
+  for (const f of records) {
+    const text = fs.readFileSync(path.join(DIR, f), 'utf8');
+    for (const [, href] of text.matchAll(/\]\(([^)\s]+)\)/g)) {
+      if (/^(?:[a-z]+:|#|\/)/i.test(href)) continue;
+      const target = path.resolve(DIR, href.split('#')[0]);
+      assert.ok(fs.existsSync(target), `${f}: link ${href} resolves to nothing (${path.relative(ROOT, target)})`);
+    }
+  }
+});
+
+console.log(`\nhall page records (task 1003499) tests: ${passed} passed, ${failed} failed`);
+process.exitCode = failed > 0 ? 1 : 0;

package/tests/helpers.mjs

@@ -987,3 +987,28 @@ export function namesFieldKey(src, key) {
     || new RegExp(`\\.${k}\\b`).test(src)
     || new RegExp(`=\\s*${k}\\b`).test(src);
 }
+
+// macShapedTools — write BSD/macOS-shaped `stat` and `wc` into binDir, for a shell
+// script under test to meet first on PATH (task 1004170).
+//
+// The backup scripts died on every Mac builder's machine and passed on CI's Linux, so
+// the red was invisible to anyone reading Actions. These bring the two differences to
+// any platform: BSD stat refuses GNU's `-c` outright, and BSD wc pads the number it
+// prints ("      11"). Only the stdin forms the scripts use are modelled (`wc -c < f`,
+// `... | wc -l`); any stat call other than `-c` fails loudly rather than pretend to be
+// BSD. Shared because both backup suites need the same pair.
+export function macShapedTools(binDir) {
+  const realWc = execFileSync('bash', ['-c', 'command -v wc'], { encoding: 'utf8' }).trim();
+  fs.writeFileSync(path.join(binDir, 'stat'), [
+    '#!/bin/bash',
+    'if [ "$1" = -c ]; then echo "stat: illegal option -- c" >&2; exit 1; fi',
+    'echo "macShapedTools: only the -c refusal is modelled, not BSD stat itself" >&2; exit 1',
+    '',
+  ].join('\n'), { mode: 0o755 });
+  fs.writeFileSync(path.join(binDir, 'wc'), [
+    '#!/bin/bash',
+    `n=$("${realWc}" "$@") || exit $?`,
+    'printf "%8s\\n" "${n//[[:space:]]/}"',
+    '',
+  ].join('\n'), { mode: 0o755 });
+}

package/tests/instance_db_migrated_on_code_move.mjs

@@ -24,6 +24,8 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { upgradeInvocation } from '../scripts/gds/provision-core-upgrade.js';
 import { migrateCmd, standaloneMigrateCmd, dbName } from '../scripts/gds/provision-repo.js';
+import { CORE_MIGRATE_SCRIPT } from '../scripts/gds/upgrade-migrate.js';
+import { INSTANCE_MIGRATE_SCRIPT } from '../scripts/gds/init.js';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const tenant = { slug: 'charter', db_name: 'charter_db', hosting_shape: 'co-tenant', port: 3107, status: 'active' };
@@ -35,7 +37,12 @@ test('bongos upgrade migrates before it restarts, and only --skip-migrate opts o
   assert.ok(migrate > 0, 'the upgrade flow runs migrate');
   assert.ok(restart > migrate, 'the restart that makes new code live comes AFTER migrate');
   assert.match(src.slice(migrate - 200, migrate), /if \(!opts\.skipMigrate\)/, 'the only way past migrate is the explicit flag');
-  assert.match(src, /run\('npm', \['run', 'migrate'\]/, 'migrate is the instance scaffold script, i.e. the core migrate.sh');
+  // WHICH command is upgrade-migrate.js's call (task 1004274): the instance's declared script,
+  // else the one a scaffold declares — the core migrate.sh either way, so an adopted project with
+  // no scripts is migrated rather than rolled back. tests/upgrade_migrate.mjs exercises both.
+  assert.match(src, /function runMigrate\([^)]*\) \{\n\s*const \{ cmd, args, env \} = require\('\.\/upgrade-migrate'\)\.migratePlan\(instanceDir\)/,
+    'the migrate step spawns what migratePlan decides');
+  assert.equal(`bash ${CORE_MIGRATE_SCRIPT}`, INSTANCE_MIGRATE_SCRIPT, 'migrate is the instance scaffold script, i.e. the core migrate.sh');
 });
 
 test('the control-plane runner targets the instance database, not its own', () => {

package/tests/plain_cards.mjs

@@ -167,7 +167,7 @@ test('the sign-in printers, the release refusals and the claim guard each print
     'scripts/gds/cli-lib.js': ['session_invalid', 'no_session'],
     'scripts/gds/release.js': ['no_active_claim', 'CLAIM_SESSION_MISMATCH'],
     'scripts/gds/claim.js': ['main_checkout_claim'],
-    'scripts/gds/ship-land.js': ['land_pending', 'reconcile_blocked'],
+    'scripts/gds/ship-land.js': ['land_pending', 'reconcile_blocked', 'merge_conflict'], // merge_conflict: task 1003499
     'scripts/gds/push-path-brief.js': ['no_push_credential'],
   };
   for (const [file, codes] of Object.entries(wired)) {

package/tests/redteam_patrol.mjs

@@ -83,7 +83,7 @@ test('disposition: red is reserved for findings that could not be recorded', ()
   // A dry run prints; it never claims to have filed, so it never fails.
   assert.deepEqual(p.disposition({ findingClasses: 3, doFile: false, blocker: null }),
     { action: 'dry-run', exitCode: 0 });
-  // Findings filed for adjudication = the patrol working as designed (ADR 0162).
+  // Findings filed for adjudication = the patrol working as designed (ADR 0158 §2).
   // If this ever became a failure, a weekly red would train everyone to ignore it.
   assert.deepEqual(p.disposition({ findingClasses: 3, doFile: true, blocker: null }),
     { action: 'file', exitCode: 0 });

package/tests/release_notes.mjs

@@ -0,0 +1,327 @@
+// tests/release_notes.mjs — the release summaries shipped INSIDE the core package
+// (task 1004218): generated from history at pack time, redacted like a doc, pinned like
+// every other file, and read back by the upgrade runner for a from→to range.
+//
+// WHAT IS ACTUALLY AT RISK, in the order it would hurt:
+//
+//   1. THE WRONG RELEASE GETS THE CREDIT. The obvious generator — split the log wherever a
+//      `release: core X.Y.Z` subject appears — credits a merge made on a branch before one
+//      release, but landed after it, to the EARLIER release. The history below contains
+//      exactly that shape, backdated, and every release is checked against the checkout
+//      reader's own `git log --merges <prev>..<release>` answer.
+//   2. A LEAK THAT WEDGES THE LANE. These are builder-written sentences, and the real
+//      history holds ones that name a prior instance. Shipped verbatim, the fail-closed leak
+//      scan would refuse every pack from then on — the history cannot be edited.
+//   3. A RANGE READ AS "NOTHING CHANGED". A range the notes do not reach must come back as
+//      a reason, never as an empty list, and the boundaries are `from` exclusive, `to`
+//      inclusive.
+//
+// Run:  node tests/release_notes.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  RELEASE_NOTES_FILE, parseChangeRecords, parseLogRecords, buildReleaseNotes, generateReleaseNotes,
+  serializeReleaseNotes, boundReleaseNotes, notesBetween,
+} from '../scripts/gds/release-notes.js';
+import {
+  releaseNotesArtifact, scanArtifactForLeaks, PRIOR_INSTANCE_FLOOR, buildTar, TAR_ROOT,
+  sha256hex, canonicalTreeHash, buildCoreManifest, withTarballInfo, reproducePinFromTree,
+} from '../scripts/gds/package-core.js';
+import {
+  readPackagedNotes, readInstalledNotes, parseChangeRecords as runnerParser,
+} from '../scripts/gds/provision-core-upgrade.js';
+import { buildRedactionRules, collectSensitiveLiterals } from '../scripts/gds/mirror-redact.js';
+
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-release-notes-test-'));
+process.on('exit', () => { try { fs.rmSync(TMP, { recursive: true, force: true }); } catch { /* best-effort */ } });
+
+const CARRIER = (v) => `release: core ${v} — CI auto-patch carrier (publish-on-merge, ADR 0161)`;
+
+// ---- a real core-shaped history ---------------------------------------------------
+//
+//   main:  C0 ─ M1 ─ R(1.0.1) ─────────────── M2 ─ R(1.0.2) ─ M3
+//           │   │                              │               │
+//           │   task-1                  feat ──┘        hand-3 ┘
+//           └─ F1 ─ N(nested merge, backdated to 2020) ─ S(merges main at 1.0.1)
+//
+// N was made on the branch long before 1.0.1 and landed with M2, after it. Its date puts
+// it at the very end of a date-ordered log, so a subject-split generator hands it to 1.0.1.
+function makeHistory() {
+  const dir = fs.mkdtempSync(path.join(TMP, 'repo-'));
+  const git = (args, env = {}) => execFileSync('git', args, {
+    cwd: dir, encoding: 'utf8', env: { ...process.env, ...env },
+  });
+  let n = 0;
+  const commit = (msg, env) => {
+    fs.writeFileSync(path.join(dir, `c${n++}.txt`), `${msg}\n`);   // a file each, so no branch conflicts
+    git(['add', '-A'], env);
+    git(['-c', 'commit.gpgsign=false', 'commit', '-q', '--no-verify', '-m', msg], env);
+  };
+  const merge = (branch, subject, body, env) => git(['-c', 'commit.gpgsign=false', 'merge', '-q', '--no-ff', '--no-verify',
+    '-m', subject, ...(body ? ['-m', body] : []), branch], env);
+  const old = (d) => ({ GIT_AUTHOR_DATE: d, GIT_COMMITTER_DATE: d });
+
+  git(['init', '-q', '-b', 'main']);
+  git(['config', 'user.email', 'test@example.com']);
+  git(['config', 'user.name', 'Test']);
+  commit('initial', old('2020-01-01T00:00:00Z'));
+  git(['checkout', '-q', '-b', 'feat']);
+  commit('feature work begins', old('2020-01-02T00:00:00Z'));
+  git(['checkout', '-q', '-b', 'sub-7']);
+  commit('a sub-branch', old('2020-01-03T00:00:00Z'));
+  git(['checkout', '-q', 'feat']);
+  merge('sub-7', 'Merge sub-7: The nested summary, merged on its branch long ago.', null, old('2020-01-04T00:00:00Z'));
+  git(['checkout', '-q', 'main']);
+  git(['checkout', '-q', '-b', 'task-1']);
+  commit('work for task 1');
+  git(['checkout', '-q', 'main']);
+  merge('task-1', 'Merge pull request #1 from an-owner/task-1', 'task 1001: The first summary.');
+  commit(CARRIER('1.0.1'));
+  git(['checkout', '-q', 'feat']);
+  merge('main', 'Merge origin/main into feat (pre-stage freshness, task 1068)');
+  git(['checkout', '-q', 'main']);
+  merge('feat', 'Merge pull request #2 from an-owner/task-2', 'task 1002: The second summary.');
+  commit(CARRIER('1.0.2'));
+  git(['checkout', '-q', '-b', 'hand-3']);
+  commit('work for the next release');
+  git(['checkout', '-q', 'main']);
+  merge('hand-3', 'Merge hand-3: An unreleased summary.');
+  const shaOf = (v) => git(['log', '--format=%H', '-1', '-F', `--grep=release: core ${v} `]).trim();
+  return { dir, git: (args) => git(args), shaOf };
+}
+
+const H = makeHistory();
+const repoGit = H.git;
+const texts = (list) => list.map((e) => e.text);
+
+test('each release is credited with EXACTLY what landed since the previous one — even a backdated branch merge', () => {
+  const r = generateReleaseNotes({ git: repoGit, ref: 'HEAD', version: '1.0.3' });
+  assert.equal(r.skipped, undefined);
+  assert.deepEqual(texts(r.notes['1.0.1']), ['The first summary.']);
+  assert.equal(r.notes['1.0.1'][0].id, '1001', 'the CI shape keeps its task id');
+  assert.deepEqual(texts(r.notes['1.0.2']), ['The second summary.', 'The nested summary, merged on its branch long ago.'],
+    'the nested merge LANDED with 1.0.2 — its 2020 date must not hand it to 1.0.1');
+  assert.ok(!texts(r.notes['1.0.2']).some((t) => /pre-stage freshness/.test(t)), 'the mechanics of landing stay dropped');
+});
+
+test('the answer is the checkout reader’s own range — git log --merges <prev>..<release>', () => {
+  // The fallback path asks git for this one range at a time; the generator must agree
+  // with it for every release, or the page would say different things on different boxes.
+  const { notes } = generateReleaseNotes({ git: repoGit, ref: 'HEAD', version: '1.0.3' });
+  const log = repoGit(['log', '--merges', '--format=%s%x1f%b%x1e', `${H.shaOf('1.0.1')}..${H.shaOf('1.0.2')}`]);
+  assert.deepEqual(texts(notes['1.0.2']).sort(), texts(parseChangeRecords(log)).sort());
+  assert.equal(runnerParser, parseChangeRecords, 'one parser, not two: the runner re-exports this one');
+});
+
+test('the unreleased tail belongs to the packed version only when that version has no release yet', () => {
+  const declared = generateReleaseNotes({ git: repoGit, ref: 'HEAD', version: '1.0.3' });
+  assert.deepEqual(texts(declared.notes['1.0.3']), ['An unreleased summary.'], 'a hand-declared version carries its own tail');
+  const released = generateReleaseNotes({ git: repoGit, ref: 'HEAD', version: '1.0.2' });
+  assert.deepEqual(Object.keys(released.notes), ['1.0.1', '1.0.2'], 'on a work merge the tail is the NEXT release’s, and is not guessed at');
+  const behind = generateReleaseNotes({ git: repoGit, ref: 'HEAD', version: '0.9.0' });
+  assert.deepEqual(Object.keys(behind.notes), ['1.0.1', '1.0.2'], 'a version older than the newest release never takes the tail');
+});
+
+test('a shallow clone produces NO notes, and says why — never a partial file that looks whole', () => {
+  const shallow = path.join(TMP, 'shallow');
+  execFileSync('git', ['clone', '-q', '--depth', '1', `file://${H.dir}`, shallow]);
+  const r = generateReleaseNotes({
+    git: (args) => execFileSync('git', ['-C', shallow, ...args], { encoding: 'utf8' }), ref: 'HEAD', version: '1.0.3',
+  });
+  assert.equal(r.notes, undefined);
+  assert.match(r.skipped, /shallow clone/);
+});
+
+test('a version released twice keeps both halves, and a repeated sentence once', () => {
+  const rec = (sha, parents, subject, body = '') => `${sha}\x1f${parents}\x1f${subject}\x1f${body}\x1e\n`;
+  const log = [
+    rec('e', 'd', CARRIER('2.0.0')),
+    rec('d', 'c x', 'Merge b-2: Second half.'),
+    rec('c', 'b', CARRIER('2.0.0')),
+    rec('b', 'a y', 'Merge b-1: First half.'),
+    rec('a', '', 'initial'),
+  ].join('');
+  const { notes } = buildReleaseNotes(parseLogRecords(log));
+  assert.deepEqual(texts(notes['2.0.0']), ['First half.', 'Second half.']);
+});
+
+// ---- the range ---------------------------------------------------------------------
+
+const NOTES = {
+  '1.19.900': [{ text: 'already live' }],
+  '1.19.901': [{ id: '1', text: 'first in range' }],
+  '1.19.920': [],
+  '1.19.949': [{ id: '3', text: 'the target itself' }, { text: 'first in range' }],
+  '1.19.950': [{ text: 'after the target' }],
+};
+
+test('(from, to]: from EXCLUSIVE, to INCLUSIVE, newest release first, a sentence said once', () => {
+  assert.deepEqual(texts(notesBetween(NOTES, '1.19.900', '1.19.949').entries), ['the target itself', 'first in range']);
+  assert.deepEqual(texts(notesBetween(NOTES, '1.19.901', '1.19.949').entries), ['the target itself', 'first in range'],
+    'starting AT 1.19.901 excludes its own entry — the one left is the target’s repeat of it');
+  assert.deepEqual(texts(notesBetween(NOTES, '1.19.949', '1.19.950').entries), ['after the target']);
+});
+
+test('a release of pure housekeeping is COVERED and empty — distinct from not covered', () => {
+  assert.deepEqual(notesBetween(NOTES, '1.19.901', '1.19.920'), { entries: [] });
+});
+
+test('a range the notes do not reach is refused with a reason, never an empty list', () => {
+  assert.match(notesBetween(NOTES, '1.19.900', '1.19.999').uncovered, /do not list core 1\.19\.999/);
+  assert.match(notesBetween(NOTES, '1.19.850', '1.19.949').uncovered, /begin at core 1\.19\.900, after 1\.19\.850/);
+  assert.match(notesBetween(null, '1.19.900', '1.19.949').uncovered, /not a list of releases/);
+  assert.match(notesBetween([], '1.19.900', '1.19.949').uncovered, /not a list of releases/);
+});
+
+test('a file off the network is re-checked, not trusted', () => {
+  const messy = {
+    '1.0.1': [],
+    '1.0.2': [null, { text: '' }, { text: 42 }, { id: 'x; rm -rf', text: 'kept, bad id dropped' }, { id: 12, text: 'y'.repeat(900) }],
+    'not-a-version': [{ text: 'ignored' }],
+    '1.0.3': 'not an array',
+  };
+  const { entries } = notesBetween(messy, '1.0.1', '1.0.2');
+  assert.deepEqual(entries[0], { text: 'kept, bad id dropped' });
+  assert.equal(entries[1].id, '12');
+  assert.ok(entries[1].text.length <= 400, 'bounded — it reaches a DOM');
+  assert.equal(entries.length, 2);
+});
+
+// ---- the bound -----------------------------------------------------------------------
+
+test('past the bound the OLDEST releases go, the fewest that fit, and the newest always stays', () => {
+  const big = {};
+  for (let i = 1; i <= 60; i++) big[`1.0.${i}`] = [{ text: `release ${i} ${'x'.repeat(200)}` }];
+  const full = serializeReleaseNotes(big).length;
+  const cap = Math.floor(full / 2);
+  const b = boundReleaseNotes(big, cap);
+  assert.ok(serializeReleaseNotes(b.notes).length <= cap);
+  assert.equal(b.dropped[0], '1.0.1', 'oldest first');
+  assert.ok('1.0.60' in b.notes);
+  const oneMore = [b.dropped[b.dropped.length - 1], ...Object.keys(b.notes)];
+  assert.ok(serializeReleaseNotes(Object.fromEntries(oneMore.map((v) => [v, big[v]]))).length > cap, 'no more dropped than needed');
+  assert.deepEqual(boundReleaseNotes(big, full).dropped, [], 'under the bound nothing moves');
+  // …and the reader then refuses what the trimmed file no longer holds.
+  assert.match(notesBetween(b.notes, '1.0.1', '1.0.60').uncovered, /begin at core/);
+  assert.ok(notesBetween(b.notes, Object.keys(b.notes)[0], '1.0.60').entries);
+});
+
+// ---- the neutral floor ---------------------------------------------------------------
+
+const floorExtra = { owners: [...PRIOR_INSTANCE_FLOOR.owners], tokens: [...PRIOR_INSTANCE_FLOOR.tokens], literals: [] };
+const rules = buildRedactionRules({}, floorExtra);
+const sensitiveLiterals = collectSensitiveLiterals({}, floorExtra);
+const OWNER = PRIOR_INSTANCE_FLOOR.owners[0];   // never typed here: this file ships too
+
+test('a summary naming a prior instance’s owner is REDACTED like a doc, and the scan then passes', () => {
+  const notes = { '1.0.1': [], '1.0.2': [{ id: '7', text: `Asking ${OWNER} for help now reaches them.` }] };
+  const art = releaseNotesArtifact(notes, { rules, sensitiveLiterals, envSecrets: [], knownDocNames: new Set() });
+  assert.deepEqual(art.leaks, []);
+  assert.equal(art.redacted, 1);
+  assert.ok(!art.buf.toString('utf8').toLowerCase().includes(OWNER.toLowerCase()));
+  assert.match(art.notes['1.0.2'][0].text, /^Asking example-owner for help/);
+  assert.deepEqual(scanArtifactForLeaks([{ path: RELEASE_NOTES_FILE, content: art.buf }]).literalHits, []);
+  // The post-build scan reads the generated file like any other: unredacted, it is flagged.
+  assert.ok(scanArtifactForLeaks([{ path: RELEASE_NOTES_FILE, content: serializeReleaseNotes(notes) }]).literalHits.length > 0);
+});
+
+test('residue AFTER redaction is reported as a leak — which main() treats as fatal', () => {
+  const notes = { '1.0.2': [{ text: `Asking ${OWNER} for help.` }] };
+  const blind = buildRedactionRules({}, {});   // a redactor that does not know the literal
+  const art = releaseNotesArtifact(notes, { rules: blind, sensitiveLiterals, envSecrets: [], knownDocNames: new Set() });
+  assert.ok(art.leaks.some((l) => /^doc:literal:/.test(l.label)), JSON.stringify(art.leaks));
+});
+
+// ---- packed, verified, downloaded, read back ------------------------------------------
+
+// The artifact the way main() assembles it: the notes staged beside package.json into ONE
+// file set, from which the pin is computed — then the pin reproduced from the unpacked tgz,
+// which is what --self-verify does at publish time.
+function pack({ withNotes = true } = {}) {
+  const gen = generateReleaseNotes({ git: repoGit, ref: 'HEAD', version: '1.0.3' });
+  const art = releaseNotesArtifact(gen.notes, { rules, sensitiveLiterals, envSecrets: [], knownDocNames: new Set() });
+  const files = [{ path: 'package.json', buf: Buffer.from('{"name":"@bongos/core","version":"1.0.3"}\n') }];
+  if (withNotes) files.push({ path: RELEASE_NOTES_FILE, buf: art.buf });
+  const filesMeta = files.map((f) => ({ path: f.path, mode: '100644', sha256: sha256hex(f.buf) }));
+  const tgz = buildTar(files.map((f) => ({ name: TAR_ROOT + f.path, mode: 0o644, buf: f.buf })));
+  const out = fs.mkdtempSync(path.join(TMP, 'dist-'));
+  const tgzPath = path.join(out, 'bongos-core-1.0.3.tgz');
+  fs.writeFileSync(tgzPath, tgz);
+  const sidecar = withTarballInfo(buildCoreManifest({
+    version: '1.0.3', coreContract: '1.0.3', sourceCommit: null, sourceRef: 'HEAD', builtAtIso: new Date(0).toISOString(),
+    files: filesMeta, treeHash: canonicalTreeHash(filesMeta),
+  }), { name: 'bongos-core-1.0.3.tgz', sha256: sha256hex(tgz), bytes: tgz.length });
+  return { art, tgzPath, sidecar };
+}
+
+// `npm pack` stood in for (no registry in a unit test); `tar` is the real one.
+function registry(tgzPath, asked = []) {
+  return (cmd, args, opts) => {
+    if (cmd !== 'npm') return spawnSync(cmd, args, opts);
+    asked.push(args[1]);
+    fs.copyFileSync(tgzPath, path.join(args[args.indexOf('--pack-destination') + 1], path.basename(tgzPath)));
+    return { status: 0, stdout: `${path.basename(tgzPath)}\n`, stderr: '' };
+  };
+}
+
+test('PACKED, SELF-VERIFIED, DOWNLOADED, READ BACK — and the range comes out right', () => {
+  const { art, tgzPath, sidecar } = pack();
+  // --self-verify: the pin reproduces from the unpacked tarball, notes file included.
+  const unpacked = fs.mkdtempSync(path.join(TMP, 'unpacked-'));
+  assert.equal(spawnSync('tar', ['-xzf', tgzPath, '-C', unpacked]).status, 0);
+  const rep = reproducePinFromTree({ treeRoot: path.join(unpacked, 'package'), sidecar, tgzPath });
+  assert.ok(rep.ok, rep.problems.join('; '));
+  assert.ok(sidecar.files.some((f) => f.path === RELEASE_NOTES_FILE), 'the notes are IN the pin, not beside it');
+
+  const asked = [];
+  const got = readPackagedNotes('1.0.3', { spawn: registry(tgzPath, asked), tmpDir: TMP });
+  assert.deepEqual(asked, ['@bongos/core@1.0.3'], 'the target’s own package is the one fetched');
+  assert.deepEqual(got.notes, art.notes, 'what comes out is what went in');
+  const r = notesBetween(got.notes, '1.0.1', '1.0.3');
+  assert.deepEqual(texts(r.entries), ['An unreleased summary.', 'The second summary.', 'The nested summary, merged on its branch long ago.'],
+    '1.0.1’s own summary is excluded; the target’s is included');
+  assert.deepEqual(fs.readdirSync(TMP).filter((n) => n.startsWith('bongos-release-notes-')), [], 'the download does not outlive the call');
+});
+
+test('a package published before the notes existed says so — the real tar, a real tarball without the file', () => {
+  const { tgzPath } = pack({ withNotes: false });
+  const got = readPackagedNotes('1.0.3', { spawn: registry(tgzPath), tmpDir: TMP });
+  assert.equal(got.notes, undefined);
+  assert.match(got.missing, /the core 1\.0\.3 package carries no release notes/);
+});
+
+test('every way the download can fail is named, and cleaned up', () => {
+  const fake = (npm, tar) => (cmd, args) => {
+    if (cmd === 'npm') {
+      if (npm.writes) fs.writeFileSync(path.join(args[args.indexOf('--pack-destination') + 1], 'bongos-core-9.9.9.tgz'), 'x');
+      return npm;
+    }
+    return tar;
+  };
+  const ok = { status: 0, stdout: '', stderr: '', writes: true };
+  const cases = [
+    [fake({ status: 1, stdout: '', stderr: 'npm error code E404\nnpm error 404 Not Found - GET https://registry.npmjs.org/x' }, null),
+      /could not download the core 9\.9\.9 package to read its release notes \(npm error 404 Not Found/],
+    [fake({ status: 0, stdout: '', stderr: '' }, null), /left no tarball/],
+    [fake(ok, { status: 2, stdout: '', stderr: 'tar: Error opening archive: Unrecognized archive format' }), /could not read the release notes out of the core 9\.9\.9 package/],
+    [fake(ok, { status: 0, stdout: '{not json', stderr: '' }), /not valid JSON/],
+    [fake({ error: new Error('spawnSync npm ETIMEDOUT'), status: null }, null), /ETIMEDOUT/],
+  ];
+  for (const [spawn, want] of cases) assert.match(readPackagedNotes('9.9.9', { spawn, tmpDir: TMP }).error, want);
+  let spawned = false;
+  assert.match(readPackagedNotes("9.9.9'; rm -rf /", { spawn: () => { spawned = true; } }).error, /could not work out/);
+  assert.equal(spawned, false, 'a version that is not three numbers reaches no command');
+  assert.deepEqual(fs.readdirSync(TMP).filter((n) => n.startsWith('bongos-release-notes-')), []);
+});
+
+test('the installed core’s own file: read when present, and a missing or broken one is not an answer', () => {
+  const at = (body) => ({ fs: { readFileSync: (p) => { assert.ok(p.endsWith(RELEASE_NOTES_FILE)); if (body === null) throw new Error('ENOENT'); return body; } } });
+  assert.deepEqual(readInstalledNotes(at('{"1.0.1":[]}')).notes, { '1.0.1': [] });
+  assert.match(readInstalledNotes(at(null)).missing, /carries no release notes/);
+  assert.match(readInstalledNotes(at('{bad')).error, /not valid JSON/);
+});

package/tests/shell_stat_portability.mjs

@@ -0,0 +1,49 @@
+// tests/shell_stat_portability.mjs — no shell script leans on one platform's `stat`
+// (task 1004170).
+//
+// THE BUG. GNU stat takes `-c FORMAT`; BSD/macOS stat refuses `-c` outright, and its own
+// `-f FORMAT` means "file system status" to GNU. Five scripts called `stat -c` alone, so
+// each died, or lost its answer, on every Mac, and passed on CI's Linux, so nobody
+// reading Actions saw it. Only one of the five had a test that ran it; the suites beside
+// each script now run them under macOS-shaped tools. This is the ratchet that stops a
+// sixth arriving without one.
+//
+// THE RULE, per line of every tracked shell script: a `stat -c` carries its BSD twin after
+// an `||` on the same line, and a `stat -f` never appears without one before it. A byte
+// count needs neither: POSIX `wc -c` answers it everywhere.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GNU = /(^|[^\w-])stat\s+(-c|--format|--printf)[\s=]/;
+const BSD = /(^|[^\w-])stat\s+-f\s/;
+
+// offending — the lines of `src` that ask stat in only one platform's dialect.
+function offending(src) {
+  return src.split('\n').map((l, i) => ({ n: i + 1, l })).filter(({ l }) => {
+    if (/^\s*#/.test(l)) return false;
+    const g = l.search(GNU);
+    const b = l.search(BSD);
+    if (g < 0 && b < 0) return false;
+    return !(g >= 0 && b > g && l.slice(g, b).includes('||'));
+  });
+}
+
+test('every tracked shell script asks stat in both dialects, or not at all', () => {
+  const files = execFileSync('git', ['ls-files', '*.sh'], { cwd: ROOT, encoding: 'utf8' }).split('\n').filter(Boolean);
+  assert.ok(files.length > 20, `the scan must see the scripts, got ${files.length}`);
+  const hits = files.flatMap((f) => offending(fs.readFileSync(path.join(ROOT, f), 'utf8')).map(({ n, l }) => `${f}:${n}: ${l.trim()}`));
+  assert.deepEqual(hits, [], "size: wc -c < f | tr -d '[:space:]'; anything else: stat -c FMT f || stat -f FMT f");
+});
+
+test('the rule catches a lone GNU or BSD stat, and passes the paired form and prose', () => {
+  assert.equal(offending("BYTES=$(stat -c '%s' \"$f\")").length, 1);
+  assert.equal(offending('U=$(stat -f %Su "$d")').length, 1);
+  assert.equal(offending('U=$(stat -c %U "$d" 2>/dev/null || stat -f %Su "$d" 2>/dev/null)').length, 0);
+  assert.equal(offending("  # was stat -c '%s', which BSD refuses").length, 0, 'a comment is not a call');
+});