@bongos/core 1.19.1038 → 1.19.1040

package/tests/npm_release_work.mjs

@@ -0,0 +1,350 @@
+// tests/npm_release_work.mjs — the npm-release module's "where is the work?" reading
+// (task 1002622): which stage every recent task has reached, and what each version carried.
+//
+// WHAT IS AT RISK. The owner's complaint was a deploy page that named none of the fifteen
+// tasks sitting between the version the hall ran and the newest one. The failure modes that
+// would bring that back are quiet ones: a task put in the wrong stage, a version whose notes
+// could not be read rendered as a version with no work, or a registry that did not answer
+// rendered as "nothing new". Each case below pins one of them.
+//
+// THE TRANSPORT IS FAKED, THE PARSING IS NOT. `get` returns a real stream of a real gzipped
+// tar built here, so the tar reader, gunzip, chunk boundaries and the registry's JSON are all
+// exercised as they run in production. Only the network is missing.
+//
+// Run:  node tests/npm_release_work.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import { EventEmitter } from 'node:events';
+import { Readable } from 'node:stream';
+import zlib from 'node:zlib';
+
+const require = createRequire(import.meta.url);
+const { readWork } = require('../modules/npm-release/work.js');
+const buildRouter = require('../modules/npm-release/routes/work.js');
+
+const ORIGIN = 'https://registry.npmjs.org';
+const PKG = '@bongos/core';
+
+// ---- a real tarball, built by hand ---------------------------------------------------
+
+function tarHeader(name, size, type = '0') {
+  const h = Buffer.alloc(512, 0);
+  h.write(name.slice(0, 100), 0, 'utf8');
+  h.write('0000644\0', 100, 'ascii');
+  h.write('0000000\0', 108, 'ascii');
+  h.write('0000000\0', 116, 'ascii');
+  h.write(`${size.toString(8).padStart(11, '0')}\0`, 124, 'ascii');
+  h.write('00000000000\0', 136, 'ascii');
+  h.write('        ', 148, 'ascii');
+  h.write(type, 156, 'ascii');
+  h.write('ustar\0', 257, 'ascii');
+  h.write('00', 263, 'ascii');
+  let sum = 0;
+  for (const b of h) sum += b;
+  h.write(`${sum.toString(8).padStart(6, '0')}\0 `, 148, 'ascii');
+  return h;
+}
+function tarEntry(name, data, type = '0') {
+  const body = Buffer.isBuffer(data) ? data : Buffer.from(data);
+  const pad = Buffer.alloc((512 - (body.length % 512)) % 512, 0);
+  return Buffer.concat([tarHeader(name, body.length, type), body, pad]);
+}
+function paxEntry(path) {
+  // A pax record is "<len> <key>=<value>\n", where <len> counts its own digits too.
+  const rec = (k, v) => {
+    const body = ` ${k}=${v}\n`;
+    let n = body.length + 1;
+    while (String(n).length + body.length !== n) n = String(n).length + body.length;
+    return `${n}${body}`;
+  };
+  return tarEntry('PaxHeader/x', rec('path', path), 'x');
+}
+/** A gzipped npm-shaped tarball. `notes` null leaves release-notes.json out. */
+function tarball({ notes, padBytes = 40000, pax = false } = {}) {
+  const parts = [
+    tarEntry('package/package.json', JSON.stringify({ name: PKG })),
+    // A large file BEFORE the notes, so the reader has to skip across many chunks.
+    tarEntry('package/big.js', Buffer.alloc(padBytes, 97)),
+  ];
+  if (notes) {
+    const json = JSON.stringify(notes);
+    if (pax) parts.push(paxEntry('package/release-notes.json'), tarEntry('package/SHORTNAME', json));
+    else parts.push(tarEntry('package/release-notes.json', json));
+  }
+  parts.push(Buffer.alloc(1024, 0));
+  return zlib.gzipSync(Buffer.concat(parts));
+}
+
+// ---- a fake registry -----------------------------------------------------------------
+
+function packument({ versions, latest, times }) {
+  const doc = { name: PKG, 'dist-tags': { latest }, versions: {}, time: {} };
+  for (const v of versions) {
+    doc.versions[v] = { version: v, dist: { tarball: `${ORIGIN}/@bongos/core/-/core-${v}.tgz` } };
+    doc.time[v] = times[v];
+  }
+  return doc;
+}
+
+/** `get` answering from `routes` (url → { status, body }), recording every URL asked for. */
+function fakeGet(routes) {
+  const asked = [];
+  const get = (url, opts, cb) => {
+    asked.push(url);
+    const req = new EventEmitter();
+    req.destroy = () => {};
+    setImmediate(() => {
+      const r = routes[url];
+      if (!r) { req.emit('error', new Error(`no route for ${url}`)); return; }
+      const body = Buffer.isBuffer(r.body) ? r.body : Buffer.from(typeof r.body === 'string' ? r.body : JSON.stringify(r.body));
+      // Small chunks, so a tar header lands across a chunk boundary.
+      const chunks = [];
+      for (let i = 0; i < body.length; i += 777) chunks.push(body.subarray(i, i + 777));
+      const res = Readable.from(chunks);
+      res.statusCode = r.status || 200;
+      cb(res);
+    });
+    return req;
+  };
+  return { get, asked };
+}
+
+function fakePool(tasks, titles = {}) {
+  const queries = [];
+  return {
+    queries,
+    async query(sql, params) {
+      queries.push({ sql, params });
+      if (/FROM tasks t/.test(sql)) return { rows: tasks };
+      if (/WHERE id = ANY/.test(sql)) return { rows: params[0].filter((id) => titles[id]).map((id) => ({ id, title: titles[id] })) };
+      throw new Error(`unexpected query: ${sql}`);
+    },
+  };
+}
+
+const freshStore = () => ({ packument: { at: 0, value: null, inflight: null }, notes: { version: null, at: 0, value: null, inflight: null } });
+
+// Versions 1.0.1 … 1.0.5, published a day apart, ending 2026-09-26T10:00Z.
+const TIMES = {
+  '1.0.1': '2026-09-22T10:00:00.000Z',
+  '1.0.2': '2026-09-23T10:00:00.000Z',
+  '1.0.3': '2026-09-24T10:00:00.000Z',
+  '1.0.4': '2026-09-25T10:00:00.000Z',
+  '1.0.5': '2026-09-26T10:00:00.000Z',
+};
+const NOTES = {
+  '1.0.1': [{ id: '11', text: 'An early fix.' }],
+  '1.0.2': [{ id: '12', text: 'Released and running.' }],
+  '1.0.3': [{ id: '13', text: 'Running here.' }, { text: 'A hand-landed change nobody numbered.' }],
+  '1.0.4': [],
+  '1.0.5': [{ id: '15', text: 'Published, not running yet.' }],
+};
+const INSTALLED_TO_103 = () => ({ '1.0.1': NOTES['1.0.1'], '1.0.2': NOTES['1.0.2'], '1.0.3': NOTES['1.0.3'] });
+
+const row = (id, status, at, extra = {}) => ({ id, title: `Task ${id} title`, status, at, value_summary: null, builder: 'Lars', ...extra });
+const TASKS = [
+  row('20', 'confirmed', '2026-09-26T11:00:00.000Z'),                        // done, not merged
+  row('15', 'shipped', '2026-09-26T09:00:00.000Z'),                          // in 1.0.5 > live 1.0.3
+  row('13', 'shipped', '2026-09-24T09:00:00.000Z'),                          // in 1.0.3 = live
+  row('12', 'shipped', '2026-09-23T09:00:00.000Z'),                          // in 1.0.2
+  row('21', 'shipped', '2026-09-26T12:00:00.000Z'),                          // after 1.0.5 went out
+  row('22', 'shipped', '2026-09-25T12:00:00.000Z'),                          // before it, named nowhere
+  row('23', 'shipped', '2026-09-24T08:00:00.000Z', { value_summary: 'A hand-landed change nobody numbered.' }),
+];
+
+function setup({ latest = '1.0.5', tgz = tarball({ notes: NOTES }), pkStatus = 200, tgzStatus = 200, installed = INSTALLED_TO_103, tasks = TASKS, titles = {} } = {}) {
+  const versions = Object.keys(TIMES);
+  const routes = {
+    [`${ORIGIN}/@bongos%2fcore`]: { status: pkStatus, body: pkStatus === 200 ? packument({ versions, latest, times: TIMES }) : 'nope' },
+    [`${ORIGIN}/@bongos/core/-/core-1.0.5.tgz`]: { status: tgzStatus, body: tgz },
+  };
+  const fg = fakeGet(routes);
+  const pool = fakePool(tasks, titles);
+  const store = freshStore();
+  const read = (over = {}) => readWork({ pool, pkg: PKG, live: '1.0.3', get: fg.get, store, installedNotes: installed, now: () => Date.parse('2026-09-26T13:00:00Z'), ...over });
+  return { read, asked: fg.asked, pool, store };
+}
+
+const ids = (list) => list.map((t) => t.id);
+
+// ---- the stages ---------------------------------------------------------------------
+
+test('every task lands in the stage it has actually reached', async () => {
+  const { read } = setup();
+  const d = await read();
+  assert.deepEqual(ids(d.stages.not_merged), ['20']);
+  assert.deepEqual(ids(d.stages.not_live), ['15']);
+  assert.deepEqual(ids(d.stages.released), ['13', '12', '23']);
+  assert.deepEqual(ids(d.stages.unversioned), ['21']);
+  assert.deepEqual(ids(d.stages.no_version), ['22']);
+  assert.deepEqual(d.stages.live_unreleased, []);
+  assert.equal(d.live, '1.0.3');
+  assert.equal(d.newest, '1.0.5');
+  assert.equal(d.released, '1.0.5');
+});
+
+test('a task published before this hall ran it says it was already offered', async () => {
+  const d = await setup().read();
+  const t = d.stages.not_live[0];
+  assert.equal(t.version, '1.0.5');
+  assert.equal(t.offered, true);
+});
+
+test('work running here but not released is its own stage', async () => {
+  // `latest` still on 1.0.2: 1.0.3 runs here and has not been released.
+  const d = await setup({ latest: '1.0.2' }).read();
+  assert.deepEqual(ids(d.stages.live_unreleased), ['13', '23']);
+  assert.deepEqual(ids(d.stages.released), ['12']);
+  assert.equal(d.stages.not_live[0].offered, undefined, 'not offered: 1.0.5 is past the release');
+});
+
+test('a merge with no task id is matched on the task\'s own ship summary', async () => {
+  const d = await setup().read();
+  const t = d.stages.released.find((x) => x.id === '23');
+  assert.equal(t.version, '1.0.3');
+});
+
+test('with no running version (another package), nothing is "not live"', async () => {
+  const d = await setup().read({ live: null });
+  assert.deepEqual(d.stages.not_live, []);
+  assert.ok(ids(d.stages.released).includes('15'));
+});
+
+// ---- where the notes come from --------------------------------------------------------
+
+test('notes past the installed copy are read out of the newest package', async () => {
+  const { read, asked } = setup();
+  const d = await read();
+  assert.ok(asked.includes(`${ORIGIN}/@bongos/core/-/core-1.0.5.tgz`));
+  assert.deepEqual(d.notes.source, { from: 'package', version: '1.0.5' });
+  assert.equal(d.notes.covers_to, '1.0.5');
+  assert.equal(d.notes.error, null);
+});
+
+test('a pax long-name header is followed to the notes file', async () => {
+  const d = await setup({ tgz: tarball({ notes: NOTES, pax: true }) }).read();
+  assert.equal(d.notes.covers_to, '1.0.5');
+  assert.deepEqual(ids(d.stages.not_live), ['15']);
+});
+
+test('when the installed notes already reach the newest version, nothing is downloaded', async () => {
+  const { read, asked } = setup({ installed: () => NOTES });
+  const d = await read();
+  assert.ok(!asked.some((u) => u.endsWith('.tgz')), 'no tarball download');
+  assert.deepEqual(d.notes.source, { from: 'installed', version: '1.0.5' });
+});
+
+test('a package without notes is an error, not an empty history', async () => {
+  const d = await setup({ tgz: tarball({ notes: null }) }).read();
+  assert.match(d.notes.error, /without release notes/);
+  // The installed copy stands in: the work up to 1.0.3 is still placed.
+  assert.deepEqual(d.notes.source, { from: 'installed', version: '1.0.3' });
+  assert.ok(ids(d.stages.released).includes('13'));
+  // 1.0.5 is listed as unread, never as "no work".
+  const v = d.history.versions.find((x) => x.version === '1.0.5');
+  assert.equal(v.entries, null);
+});
+
+test('a download that fails says so', async () => {
+  const d = await setup({ tgzStatus: 503 }).read();
+  assert.match(d.notes.error, /could not download 1\.0\.5/);
+});
+
+test('a registry that does not answer is reported, and the installed notes still place work', async () => {
+  const d = await setup({ pkStatus: 500 }).read();
+  assert.equal(d.registry.ok, false);
+  assert.match(d.registry.error, /500/);
+  assert.equal(d.newest, null);
+  assert.equal(d.released, null);
+  assert.ok(ids(d.stages.released).includes('13'), '1.0.3 work is still placed from the installed notes');
+});
+
+test('the package download is only ever followed on the registry\'s own origin', async () => {
+  const versions = Object.keys(TIMES);
+  const doc = packument({ versions, latest: '1.0.5', times: TIMES });
+  doc.versions['1.0.5'].dist.tarball = 'https://evil.example/core.tgz';
+  const fg = fakeGet({ [`${ORIGIN}/@bongos%2fcore`]: { body: doc } });
+  const d = await readWork({ pool: fakePool(TASKS), pkg: PKG, live: '1.0.3', get: fg.get, store: freshStore(), installedNotes: INSTALLED_TO_103 });
+  assert.ok(!fg.asked.some((u) => u.includes('evil.example')));
+  assert.match(d.notes.error, /no download/);
+});
+
+// ---- the cache --------------------------------------------------------------------------
+
+test('a second read within minutes asks the registry nothing new', async () => {
+  const { read, asked } = setup();
+  await read();
+  const before = asked.length;
+  await read();
+  assert.equal(asked.length, before);
+});
+
+test('a failed notes read is not retried on every page load', async () => {
+  const { read, asked } = setup({ tgzStatus: 503 });
+  await read();
+  await read();
+  assert.equal(asked.filter((u) => u.endsWith('.tgz')).length, 1);
+});
+
+// ---- the version history ----------------------------------------------------------------
+
+test('the history lists each version\'s tasks newest first, with titles from the ledger', async () => {
+  const d = await setup({ titles: { 11: 'Old fix title' } }).read();
+  const v = d.history.versions;
+  assert.deepEqual(v.map((x) => x.version), ['1.0.5', '1.0.4', '1.0.3', '1.0.2', '1.0.1']);
+  assert.equal(v[0].released, true);
+  assert.equal(v[2].live, true);
+  assert.deepEqual(v[1].entries, [], 'a housekeeping-only version is an empty list, not unread');
+  assert.equal(v[0].entries[0].title, 'Task 15 title');
+  assert.equal(v[4].entries[0].title, 'Old fix title', 'a task outside the window is looked up by id');
+  assert.equal(v[0].published_at, TIMES['1.0.5']);
+});
+
+test('the history pages with before + limit', async () => {
+  const { read } = setup();
+  const first = await read({ limit: 2 });
+  assert.deepEqual(first.history.versions.map((x) => x.version), ['1.0.5', '1.0.4']);
+  assert.equal(first.history.more, true);
+  const next = await read({ limit: 2, before: '1.0.4' });
+  assert.deepEqual(next.history.versions.map((x) => x.version), ['1.0.3', '1.0.2']);
+});
+
+test('the ledger window is clamped', async () => {
+  const { read, pool } = setup();
+  const windows = () => pool.queries.filter((q) => /FROM tasks t/.test(q.sql)).map((q) => q.params[0]);
+  await read({ days: '9999' });
+  await read({ days: 'nonsense' });
+  assert.deepEqual(windows(), [60, 14]);
+});
+
+// ---- the route ------------------------------------------------------------------------
+
+function routeLayers() {
+  const router = buildRouter({ read: async (args) => ({ ok: true, args }) });
+  const layer = router.stack.find((l) => l.route && l.route.path === '/npm-release/work');
+  return layer.route.stack.map((s) => s.handle);
+}
+
+test('the route is gated like the deploy page: a builder holding core.pin.move', async () => {
+  const handles = routeLayers();
+  assert.equal(handles.length, 3, 'requireBuilder, the permission gate, then the handler');
+  const src = (await import('node:fs')).readFileSync(new URL('../modules/npm-release/routes/work.js', import.meta.url), 'utf8');
+  assert.match(src, /api\.requireBuilder,\s*\n\s*api\.requirePermission\('core\.pin\.move'\)/);
+  assert.doesNotMatch(src, /api\.requireRank\(/);
+});
+
+test('the handler passes the query through and answers 500 plainly when the read throws', async () => {
+  const [, , ok] = routeLayers();
+  let body = null;
+  await ok({ query: { days: '7', before: '1.0.3', limit: '5' } }, { json(v) { body = v; } });
+  assert.equal(body.args.days, '7');
+  assert.equal(body.args.before, '1.0.3');
+
+  const router = buildRouter({ read: async () => { throw new Error('boom'); } });
+  const h = router.stack[0].route.stack.at(-1).handle;
+  let status = 0; let err = null;
+  await h({ query: {} }, { status(s) { status = s; return this; }, json(v) { err = v; } });
+  assert.equal(status, 500);
+  assert.equal(err.error.code, 'work_read_failed');
+});

package/tests/publish_integration_gate.mjs

@@ -0,0 +1,198 @@
+// tests/publish_integration_gate.mjs — npm publishing waits for the integration lane's
+// verdict on the commit it releases (task 1004290).
+//
+// WHY. publish.yml fires on `unit`, which is DB-free by design. The proof that the
+// PACKAGED core can migrate an empty database (tests/consumer_layout_boot.mjs, task
+// 1002863) runs in integration.yml, and until this gate its verdict arrived after the
+// publish and gated nothing. What is pinned here:
+//   1. the verdicts, from the real list-workflow-runs payload shape
+//   2. the wait: polls while running, stops at once on an unreadable API, times out loudly
+//   3. the lane is WIRED: actions:read, the step sits before any install/pack/publish, and
+//      every later armed step carries the integration go — so a new step cannot slip past
+//
+// Network-free: fetch, sleep and the clock are injected.
+//
+// Run:  node tests/publish_integration_gate.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const gate = require('../scripts/gds/publish-integration-gate.js');
+const { decideIntegrationGate, waitForIntegration, reportLines, main, runsUrl } = gate;
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+const SHA = '078e8b7b'.padEnd(40, '0');
+// The fields GitHub's list-workflow-runs answers with that the gate reads (from a real
+// integration run on main, 2026-09-26: run 36210...; trimmed to what matters).
+const ghRun = (run_number, status, conclusion) => ({
+  id: 36210000000 + run_number, run_number, event: 'push', head_sha: SHA, status, conclusion,
+  created_at: `2026-09-26T03:${String(run_number % 60).padStart(2, '0')}:00Z`,
+  html_url: `https://github.com/example-org/example-repo/actions/runs/${36210000000 + run_number}`,
+});
+const okJson = (body) => ({ ok: true, status: 200, json: async () => body });
+
+// ---- 1. the verdicts ----
+
+await test('decideIntegrationGate: success → go, running or absent → wait, cancelled → superseded, anything else → red', async () => {
+  assert.equal(decideIntegrationGate([ghRun(1, 'completed', 'success')]).verdict, 'go');
+  assert.equal(decideIntegrationGate([]).verdict, 'wait', 'the run has not been created yet');
+  assert.equal(decideIntegrationGate(undefined).verdict, 'wait');
+  for (const status of ['queued', 'in_progress', 'waiting', 'pending']) {
+    assert.equal(decideIntegrationGate([ghRun(1, status, null)]).verdict, 'wait', status);
+  }
+  assert.equal(decideIntegrationGate([ghRun(1, 'completed', 'cancelled')]).verdict, 'superseded');
+  for (const c of ['failure', 'timed_out', 'startup_failure', 'action_required', 'skipped', 'neutral', 'stale', null]) {
+    assert.equal(decideIntegrationGate([ghRun(1, 'completed', c)]).verdict, 'red', `fail-closed on ${c}`);
+  }
+});
+
+await test('decideIntegrationGate: the NEWEST run on the sha decides, whatever order the API lists them in', async () => {
+  assert.equal(decideIntegrationGate([ghRun(5, 'completed', 'failure'), ghRun(7, 'completed', 'success')]).verdict, 'go');
+  assert.equal(decideIntegrationGate([ghRun(7, 'completed', 'failure'), ghRun(5, 'completed', 'success')]).verdict, 'red');
+  assert.equal(decideIntegrationGate([ghRun(8, 'in_progress', null), ghRun(7, 'completed', 'success')]).verdict, 'wait');
+});
+
+await test('only PUSH runs are asked for: the weekly scheduled run carries HEAD\'s sha but tests only the parked set', async () => {
+  const u = runsUrl('example-org/example-repo', SHA);
+  assert.match(u, /\/actions\/workflows\/integration\.yml\/runs\?/);
+  assert.match(u, new RegExp(`head_sha=${SHA}`));
+  assert.match(u, /event=push/);
+  assert.ok(fs.existsSync(new URL('../.github/workflows/integration.yml', import.meta.url)), 'the workflow the gate names exists');
+});
+
+// ---- 2. the wait ----
+
+function clock() {
+  let t = 0;
+  return { now: () => t, sleep: async (ms) => { t += ms; } };
+}
+
+await test('waitForIntegration: polls while integration runs, then publishes on green', async () => {
+  const c = clock();
+  const replies = [okJson({ workflow_runs: [] }), okJson({ workflow_runs: [ghRun(3, 'in_progress', null)] }),
+    okJson({ workflow_runs: [ghRun(3, 'completed', 'success')] })];
+  const asked = [];
+  const r = await waitForIntegration({
+    sha: SHA, repo: 'example-org/example-repo', token: 't', timeoutMs: 600000, intervalMs: 20000,
+    fetchImpl: async (url, init) => { asked.push({ url, auth: init.headers.Authorization }); return replies.shift(); },
+    ...c,
+  });
+  assert.equal(r.verdict, 'go');
+  assert.equal(asked.length, 3);
+  assert.equal(asked[0].auth, 'Bearer t');
+  assert.equal(c.now(), 40000, 'slept between reads, not after the verdict');
+});
+
+await test('waitForIntegration: a 403/404 ends the wait at once (waiting cannot grant a permission)', async () => {
+  for (const status of [401, 403, 404]) {
+    const c = clock();
+    let calls = 0;
+    const r = await waitForIntegration({
+      sha: SHA, repo: 'o/r', token: 't', timeoutMs: 600000, intervalMs: 20000,
+      fetchImpl: async () => { calls++; return { ok: false, status, json: async () => ({}) }; }, ...c,
+    });
+    assert.equal(r.verdict, 'unreadable', String(status));
+    assert.equal(calls, 1);
+  }
+});
+
+await test('waitForIntegration: flaky reads are retried, and a lane with no verdict times out rather than publishing', async () => {
+  const c = clock();
+  let calls = 0;
+  const r = await waitForIntegration({
+    sha: SHA, repo: 'o/r', token: 't', timeoutMs: 60000, intervalMs: 20000,
+    fetchImpl: async () => {
+      calls++;
+      if (calls === 1) throw new Error('ECONNRESET');
+      if (calls === 2) return { ok: false, status: 502, json: async () => ({}) };
+      return okJson({ workflow_runs: [ghRun(3, 'in_progress', null)] });
+    },
+    ...c,
+  });
+  assert.equal(r.verdict, 'timeout');
+  assert.ok(calls >= 3, 'kept reading through the transient failures');
+});
+
+await test('reportLines: only a green lane says go; red, unreadable and timeout exit non-zero', async () => {
+  const base = { sha: SHA, run: ghRun(3, 'completed', 'failure'), why: 'HTTP 403', timeoutMin: 12 };
+  assert.deepEqual([reportLines('go', base).go, reportLines('go', base).code], [true, 0]);
+  assert.deepEqual([reportLines('superseded', base).go, reportLines('superseded', base).code], [false, 0]);
+  for (const v of ['red', 'unreadable', 'timeout']) {
+    const o = reportLines(v, base);
+    assert.equal(o.go, false, v);
+    assert.equal(o.code, 1, v);
+    assert.match(o.line, /^::error title=not published/, v);
+    assert.doesNotMatch(o.line.split('::')[1], /,/, `${v}: a comma in the title would split the annotation's properties`);
+  }
+  assert.match(reportLines('red', base).line, /task 1002863/, 'says what the red lane was proving');
+  assert.match(reportLines('unreadable', base).line, /actions: read/);
+});
+
+await test('main: writes go=… to GITHUB_OUTPUT and refuses bad arguments with exit 2', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'integ-gate-'));
+  try {
+    const out = path.join(dir, 'out');
+    const log = console.log;
+    const err = console.error;
+    console.log = () => {};
+    console.error = () => {};
+    try {
+      assert.equal(await main(['--sha', 'nope', '--repo', 'o/r'], { GH_TOKEN: 't', GITHUB_OUTPUT: out }), 2);
+      assert.equal(await main(['--sha', SHA, '--repo', 'o/r'], { GITHUB_OUTPUT: out }), 2, 'no token');
+      const realFetch = globalThis.fetch;
+      globalThis.fetch = async () => okJson({ workflow_runs: [ghRun(3, 'completed', 'success')] });
+      try {
+        assert.equal(await main(['--sha', SHA, '--repo', 'o/r'], { GH_TOKEN: 't', GITHUB_OUTPUT: out }), 0);
+      } finally { globalThis.fetch = realFetch; }
+    } finally { console.log = log; console.error = err; }
+    assert.equal(fs.readFileSync(out, 'utf8'), 'go=true\n');
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+// ---- 3. the wiring ----
+
+const YML = fs.readFileSync(new URL('../.github/workflows/publish.yml', import.meta.url), 'utf8');
+// Split the job into steps at each `      - ` list item (the job's step indentation).
+const steps = YML.split(/\n(?=      - (?:name|uses):)/).slice(1);
+const stepIndex = (re) => steps.findIndex((s) => re.test(s));
+
+await test('publish.yml can read the integration runs, and asks about the commit it packages', async () => {
+  assert.match(YML, /^permissions:[\s\S]*?^\s+actions: read$/m, 'the job token needs actions:read to list runs');
+  assert.doesNotMatch(YML, /actions: write/, 'read only');
+  const g = steps[stepIndex(/id: integ\n/)];
+  assert.ok(g, 'the integration gate step exists');
+  assert.match(g, /node scripts\/gds\/publish-integration-gate\.js --sha "\$\(git rev-parse HEAD\)"/, 'HEAD — the checkout is ref: main, not the trigger sha');
+  assert.match(g, /GH_TOKEN: \$\{\{ github\.token \}\}/);
+});
+
+await test('publish.yml: the gate runs before anything is installed, bumped, packed, published, recorded or tagged', async () => {
+  const at = stepIndex(/id: integ\n/);
+  assert.ok(at > stepIndex(/id: relhead\n/), 'after the cascade terminator (a carrier HEAD needs no gate)');
+  for (const re of [/actions\/setup-node@/, /run: npm ci\b/, /id: ver\n/, /id: bump\n/, /id: pack\n/, /id: pub\n/, /git push origin HEAD:main/, /git tag "core-v/]) {
+    const i = stepIndex(re);
+    assert.ok(i > at, `${re} must come after the integration gate (at ${i}, gate at ${at})`);
+  }
+});
+
+await test('publish.yml: every armed step after the gate also requires its go — no step can slip past it', async () => {
+  const at = stepIndex(/id: integ\n/);
+  const later = steps.slice(at + 1).filter((s) => /steps\.armed\.outputs\.armed == 'true'/.test(s));
+  assert.ok(later.length >= 9, `expected the install..tag chain after the gate, found ${later.length}`);
+  for (const s of later) {
+    const name = (/- (?:name: (.*)|uses: (.*))/.exec(s) || [])[1] || s.slice(0, 60);
+    assert.match(s, /steps\.integ\.outputs\.go == 'true'/, `"${name}" runs without the integration gate`);
+  }
+});
+
+console.log(`\npublish integration gate (task 1004290) tests: ${passed} passed, ${failed} failed`);
+process.exitCode = failed > 0 ? 1 : 0;

package/tests/render_check.mjs

@@ -34,7 +34,8 @@ test('the page a builder changed comes before the pages a shared file reaches, s
 
 test('a path that is not a rendered surface, or a page with no states file, reaches nothing', () => {
   assert.deepEqual(names(['src/bongos/db.js', 'modules/hall-ui/public/goal-map.states.json', 'modules/hall-ui/routes/x.js']), []);
-  assert.deepEqual(names(['modules/hall-ui/public/deploy.html']), [], 'a page without a states file does not fall back to the pages that link to it');
+  // blockers, not deploy: /deploy gained a states file with the npm-release module (task 1002622).
+  assert.deepEqual(names(['modules/hall-ui/public/blockers.html']), [], 'a page without a states file does not fall back to the pages that link to it');
 });
 
 test('fitFindings names every element from the structured facts, once per element across renders, with its largest measure', () => {
@@ -102,7 +103,7 @@ test('the CLI renders nothing, and says why, when no page a states file describe
   const none = cli('src/bongos/db.js');
   assert.equal(none.status, 0);
   assert.match(none.stdout, /no rendered surface changed/);
-  const noStates = cli('modules/hall-ui/public/deploy.html');
+  const noStates = cli('modules/hall-ui/public/blockers.html');
   assert.equal(noStates.status, 0);
   assert.match(noStates.stdout, /1 rendered-surface file\(s\) changed, but no <page>\.states\.json reaches them/);
 });