@bongos/core 1.21.124 → 1.21.126

package/tests/module_test_runner.mjs

@@ -0,0 +1,294 @@
+// tests/module_test_runner.mjs — the separate testing environment for a published
+// module's own tests (task 1004460): the control plane dispatches a run to a
+// private repo's GitHub Actions and PULLS the result back, accepting it only from
+// the run whose run-name carries the pending row's nonce. No network, no DB:
+// GitHub is a fake fetch, the DB an append-only fake.
+//
+// Run:  node tests/module_test_runner.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const runner = require('../scripts/gds/module-test-runner.js');
+const { runnerConfig, maybeDispatch, collectResults, sweepTick, readZipEntry, validateSignal, runName, artifactName } = runner;
+
+const CFG = { repo: 'owner/module-tests', token: 't0ken', coreRepo: 'owner/core' };
+const VER = { id: 7, module_key: 'weather', version: '1.0.0', artifact_path: 'weather/weather-1.0.0.tgz' };
+const quiet = { warn() {}, error() {} };
+
+// A minimal zip writer (stored or deflated), enough to stand in for an artifact.
+function makeZip(entries, { deflate = true } = {}) {
+  const locals = []; const centrals = []; let offset = 0;
+  for (const [name, data] of Object.entries(entries)) {
+    const raw = Buffer.from(data);
+    const body = deflate ? zlib.deflateRawSync(raw) : raw;
+    const n = Buffer.from(name);
+    const lh = Buffer.alloc(30); lh.writeUInt32LE(0x04034b50, 0); lh.writeUInt16LE(deflate ? 8 : 0, 8);
+    lh.writeUInt32LE(body.length, 18); lh.writeUInt32LE(raw.length, 22); lh.writeUInt16LE(n.length, 26);
+    const ch = Buffer.alloc(46); ch.writeUInt32LE(0x02014b50, 0); ch.writeUInt16LE(deflate ? 8 : 0, 10);
+    ch.writeUInt32LE(body.length, 20); ch.writeUInt32LE(raw.length, 24); ch.writeUInt16LE(n.length, 28); ch.writeUInt32LE(offset, 42);
+    locals.push(lh, n, body); centrals.push(ch, n); offset += 30 + n.length + body.length;
+  }
+  const cd = Buffer.concat(centrals);
+  const eocd = Buffer.alloc(22); eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(Object.keys(entries).length, 8); eocd.writeUInt16LE(Object.keys(entries).length, 10);
+  eocd.writeUInt32LE(cd.length, 12); eocd.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, cd, eocd]);
+}
+
+function fakeDb() {
+  const signals = []; let clock = 0;
+  return {
+    signals,
+    async query(sql, params = []) {
+      if (/ORDER BY measured_at DESC, id DESC LIMIT 1/.test(sql) && !/CROSS JOIN LATERAL/.test(sql)) {
+        const mine = signals.filter((s) => String(s.version_id) === String(params[0]) && s.part === 'tests');
+        return { rows: mine.length ? [mine[mine.length - 1]] : [] };
+      }
+      if (/CROSS JOIN LATERAL/.test(sql)) {
+        assert.match(sql, /FROM store_module_versions v/, 'driven from the versions, not the whole signal history');
+        const cur = {};
+        for (const s of signals.filter((x) => x.part === 'tests')) cur[s.version_id] = s;
+        return { rows: Object.values(cur).filter((r) => r.outcome === 'pending' && r.detail && r.detail.runner) };
+      }
+      if (/INSERT INTO module_assessment_signals/.test(sql)) {
+        signals.push({ id: signals.length + 1, version_id: params[0], part: 'tests', outcome: 'pending', reason: params[1], detail: JSON.parse(params[2]), t: ++clock });
+        return { rows: [] };
+      }
+      throw new Error(`unexpected SQL: ${sql.slice(0, 80)}`);
+    },
+  };
+}
+
+// A fake GitHub: records every call, answers by route.
+function fakeGitHub(routes = {}) {
+  const calls = [];
+  const fetchImpl = async (url, init = {}) => {
+    const method = init.method || 'GET';
+    calls.push({ method, url, body: init.body ? JSON.parse(init.body) : null, auth: init.headers && init.headers.Authorization });
+    for (const [pattern, answer] of Object.entries(routes)) {
+      const [m, re] = pattern.split(' ');
+      if (m === method && new RegExp(re).test(url)) {
+        const a = typeof answer === 'function' ? answer(url, init) : answer;
+        if (a instanceof Response) return a;
+        return new Response(a === null ? null : JSON.stringify(a), { status: a === null ? 204 : 200 });
+      }
+    }
+    return new Response('{"message":"not found"}', { status: 404 });
+  };
+  return { calls, fetchImpl };
+}
+
+const dispatchRoutes = {
+  'POST /git/blobs$': { sha: 'blob1' },
+  'POST /git/trees$': { sha: 'tree1' },
+  'POST /git/commits$': { sha: 'commit1' },
+  'POST /git/refs$': { ref: 'x' },
+  'POST /dispatches$': null,
+};
+
+// ---------------------------------------------------------------------------
+test('unconfigured: no runner, so Tests stays plain pending and nothing is sent', async () => {
+  assert.equal(runnerConfig({}), null);
+  assert.equal(runnerConfig({ MODULE_TEST_REPO: 'a/b' }), null, 'a repo with no token is not configured');
+  const db = fakeDb();
+  assert.equal(await maybeDispatch(VER, { db, env: {} }), null);
+  assert.equal(db.signals.length, 0);
+});
+
+test('config: owner/name is required, the core repo falls back to git origin', () => {
+  assert.throws(() => runnerConfig({ MODULE_TEST_REPO: 'nope', MODULE_TEST_TOKEN: 'x' }), /owner\/name/);
+  const c = runnerConfig({ MODULE_TEST_REPO: 'o/r', MODULE_TEST_TOKEN: 'x' }, { origin: () => 'o/core' });
+  assert.deepEqual(c, { repo: 'o/r', token: 'x', coreRepo: 'o/core', ref: 'main' });
+  assert.equal(runnerConfig({ MODULE_TEST_REPO: 'o/r', MODULE_TEST_TOKEN: 'x', MODULE_TEST_REF: 'trunk' }, { origin: () => 'o/core' }).ref, 'trunk');
+});
+
+test('dispatch pushes the tarball to a throwaway branch, dispatches, and records the nonce', async () => {
+  const db = fakeDb();
+  const gh = fakeGitHub(dispatchRoutes);
+  const r = await maybeDispatch(VER, { db, cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('tgz'), coreRef: () => 'abc123', log: quiet });
+  assert.match(r.nonce, /^[0-9a-f]{32}$/);
+  assert.equal(r.branch, `module-test/${r.nonce}`);
+  assert.deepEqual(gh.calls.map((c) => `${c.method} ${c.url.replace('https://api.github.com/repos/owner/module-tests', '')}`), [
+    'POST /git/blobs', 'POST /git/trees', 'POST /git/commits', 'POST /git/refs', 'POST /actions/workflows/module-tests.yml/dispatches']);
+  assert.deepEqual(gh.calls[2].body.parents, [], 'an orphan commit: the branch carries only the tarball');
+  assert.equal(gh.calls[3].body.ref, `refs/heads/module-test/${r.nonce}`);
+  assert.equal(gh.calls[4].body.ref, 'main');
+  assert.deepEqual(gh.calls[4].body.inputs, { version_id: '7', module_key: 'weather', nonce: r.nonce, core_repo: 'owner/core', core_ref: 'abc123' });
+  assert.equal(db.signals.length, 1);
+  assert.equal(db.signals[0].outcome, 'pending');
+  assert.equal(db.signals[0].detail.runner.nonce, r.nonce);
+});
+
+test('a version with a real Tests result, or a run already in flight, is not dispatched again', async () => {
+  for (const existing of [{ outcome: 'scored', detail: {} }, { outcome: 'pending', detail: { runner: { nonce: 'a'.repeat(32) } } }]) {
+    const db = fakeDb();
+    db.signals.push({ id: 1, version_id: 7, part: 'tests', ...existing });
+    const gh = fakeGitHub(dispatchRoutes);
+    assert.equal(await maybeDispatch(VER, { db, cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('x'), coreRef: () => 'c', log: quiet }), null);
+    assert.equal(gh.calls.length, 0);
+  }
+});
+
+test('a plain pending (from before the runner was set up) is dispatched', async () => {
+  const db = fakeDb();
+  db.signals.push({ id: 1, version_id: 7, part: 'tests', outcome: 'pending', detail: {} });
+  const gh = fakeGitHub(dispatchRoutes);
+  assert.ok(await maybeDispatch(VER, { db, cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('x'), coreRef: () => 'c', log: quiet }));
+});
+
+test('a failed dispatch deletes the branch, records nothing and never throws', async () => {
+  const db = fakeDb();
+  const gh = fakeGitHub({ ...dispatchRoutes, 'POST /dispatches$': () => new Response('{"message":"nope"}', { status: 422 }), 'DELETE /git/refs/heads/module-test/': null });
+  assert.equal(await maybeDispatch(VER, { db, cfg: CFG, fetchImpl: gh.fetchImpl, readTarball: async () => Buffer.from('x'), coreRef: () => 'c', log: quiet }), null);
+  assert.equal(gh.calls.at(-1).method, 'DELETE');
+  assert.equal(db.signals.length, 0);
+});
+
+// ---------------------------------------------------------------------------
+test('readZipEntry reads deflated and stored entries, and refuses an oversized one', () => {
+  const z = makeZip({ 'other.txt': 'x', 'signal.json': '{"a":1}' });
+  assert.equal(readZipEntry(z, 'signal.json').toString(), '{"a":1}');
+  assert.equal(readZipEntry(makeZip({ 'signal.json': 'plain' }, { deflate: false }), 'signal.json').toString(), 'plain');
+  assert.equal(readZipEntry(z, 'missing.json'), null);
+  assert.throws(() => readZipEntry(makeZip({ 'signal.json': 'x'.repeat(2000) }), 'signal.json', { maxBytes: 1000 }), /over 1000 bytes/);
+  assert.throws(() => readZipEntry(Buffer.from('not a zip at all, definitely not'), 'signal.json'), /not a zip/);
+});
+
+test('validateSignal holds the payload to its run and to the stored shape', () => {
+  const base = { version_id: '7', nonce: 'n', outcome: 'scored', score: 80, sample_size: 5, reason: 'r', detail: { files: [{ file: 'tests/a.mjs', passed: true, extra: 'dropped' }] } };
+  const ok = validateSignal(base, { versionId: 7, nonce: 'n' });
+  assert.deepEqual(ok, { outcome: 'scored', score: 80, sample_size: 5, reason: 'r', detail: { files: [{ file: 'tests/a.mjs', passed: true }] } });
+  assert.throws(() => validateSignal({ ...base, nonce: 'other' }, { versionId: 7, nonce: 'n' }), /different version or run/);
+  assert.throws(() => validateSignal({ ...base, version_id: '8' }, { versionId: 7, nonce: 'n' }), /different version or run/);
+  assert.throws(() => validateSignal({ ...base, score: 101 }, { versionId: 7, nonce: 'n' }), /0–100/);
+  assert.throws(() => validateSignal({ ...base, outcome: 'passed' }, { versionId: 7, nonce: 'n' }), /unknown outcome/);
+  assert.equal(validateSignal({ ...base, outcome: 'no_data', score: 99 }, { versionId: 7, nonce: 'n' }).score, null);
+});
+
+// ---------------------------------------------------------------------------
+const NONCE = 'b'.repeat(32);
+function pendingDb(at = new Date().toISOString()) {
+  const db = fakeDb();
+  db.signals.push({ id: 1, version_id: 7, part: 'tests', outcome: 'pending', detail: { runner: { nonce: NONCE, branch: `module-test/${NONCE}`, dispatched_at: at } } });
+  return db;
+}
+const recorded = [];
+const insert = async (id, s) => { recorded.push({ id, ...s }); };
+const recompose = async () => {};
+
+test('collect takes only the run whose run-name carries the nonce, and only its artifact of that name', async () => {
+  recorded.length = 0;
+  const payload = { version_id: '7', nonce: NONCE, outcome: 'scored', score: 50, sample_size: 2, reason: '1 of 2 failed', detail: { files: [] } };
+  const forged = { ...payload, score: 100 };
+  const gh = fakeGitHub({
+    'GET /workflows/module-tests.yml/runs': { runs: [
+      { id: 900, display_title: runName(8, 'c'.repeat(32)), status: 'completed', conclusion: 'success' },
+      { id: 901, display_title: runName(7, NONCE), status: 'completed', conclusion: 'success' },
+    ] },
+    // run 900 (another version's run) uploads an artifact claiming version 7's name
+    'GET /runs/900/artifacts': { artifacts: [{ name: artifactName(7, NONCE), archive_download_url: 'https://dl/900', expired: false }] },
+    'GET /runs/901/artifacts': { artifacts: [{ name: 'tarball-x', archive_download_url: 'https://dl/no' }, { name: artifactName(7, NONCE), archive_download_url: 'https://dl/901', expired: false }] },
+    'GET ^https://dl/900': () => new Response(makeZip({ 'signal.json': JSON.stringify(forged) })),
+    'GET ^https://dl/901': () => new Response(null, { status: 302, headers: { location: 'https://blob/901' } }),
+    'GET ^https://blob/901': () => new Response(makeZip({ 'signal.json': JSON.stringify(payload) })),
+    'DELETE /git/refs/heads/': null,
+  });
+  const res = await collectResults({ db: pendingDb(), cfg: CFG, fetchImpl: gh.fetchImpl, insert, recompose });
+  assert.deepEqual(res, [{ version_id: 7, status: 'recorded', outcome: 'scored' }]);
+  assert.equal(recorded[0].score, 50, 'the forged artifact in run 900 was never read');
+  assert.deepEqual(recorded[0].detail.runner, { nonce: NONCE, run_id: 901 });
+  assert.ok(!gh.calls.some((c) => c.url.includes('/runs/900/')), 'another run is never even listed');
+  const blob = gh.calls.find((c) => c.url === 'https://blob/901');
+  assert.equal(blob.auth, undefined, 'the token is not sent past the redirect');
+  assert.equal(gh.calls.at(-1).method, 'DELETE', 'the branch is deleted once the result is in');
+});
+
+test('collect waits on an unfinished run, and gives up on one past the age limit', async () => {
+  recorded.length = 0;
+  const gh = fakeGitHub({ 'GET /runs\\?': { runs: [{ id: 1, display_title: runName(7, NONCE), status: 'in_progress' }] }, 'DELETE /git/refs/': null });
+  assert.deepEqual(await collectResults({ db: pendingDb(), cfg: CFG, fetchImpl: gh.fetchImpl, insert, recompose }), [{ version_id: 7, status: 'waiting' }]);
+  assert.equal(recorded.length, 0);
+  const old = new Date(Date.now() - 7 * 3600_000).toISOString();
+  const res = await collectResults({ db: pendingDb(old), cfg: CFG, fetchImpl: gh.fetchImpl, insert, recompose });
+  assert.deepEqual(res, [{ version_id: 7, status: 'expired', outcome: 'not_scored' }]);
+  assert.match(recorded[0].reason, /did not finish in time/);
+});
+
+test('a run that never started is waited on, then expires as not_scored', async () => {
+  recorded.length = 0;
+  const gh = fakeGitHub({ 'GET /runs\\?': { runs: [] }, 'DELETE /git/refs/': null });
+  assert.deepEqual(await collectResults({ db: pendingDb(), cfg: CFG, fetchImpl: gh.fetchImpl, insert, recompose }), [{ version_id: 7, status: 'waiting' }]);
+  const old = new Date(Date.now() - 7 * 3600_000).toISOString();
+  const res = await collectResults({ db: pendingDb(old), cfg: CFG, fetchImpl: gh.fetchImpl, insert, recompose });
+  assert.deepEqual(res, [{ version_id: 7, status: 'expired', outcome: 'not_scored' }]);
+  assert.match(recorded[0].reason, /never started/);
+  assert.equal(gh.calls.at(-1).method, 'DELETE', 'its branch is still cleaned up');
+});
+
+test('the sweeper keeps going while a run is out or a sweep fails, and stops once nothing waits', async () => {
+  const tick = (res) => sweepTick({ db: {}, cfg: CFG, log: quiet, collect: async () => { if (res instanceof Error) throw res; return res; } });
+  assert.equal(await tick([{ version_id: 7, status: 'waiting' }, { version_id: 8, status: 'recorded' }]), true);
+  assert.equal(await tick(new Error('GitHub down')), true, 'a failed sweep is retried, not abandoned');
+  assert.equal(await tick([{ version_id: 7, status: 'recorded' }]), false);
+  assert.equal(await tick([]), false);
+});
+
+test('a run that ended with no result artifact records not_scored, never a zero', async () => {
+  recorded.length = 0;
+  const gh = fakeGitHub({ 'GET /runs\\?': { runs: [{ id: 5, display_title: runName(7, NONCE), status: 'completed', conclusion: 'failure' }] }, 'GET /runs/5/artifacts': { artifacts: [] }, 'DELETE /git/refs/': null });
+  await collectResults({ db: pendingDb(), cfg: CFG, fetchImpl: gh.fetchImpl, insert, recompose });
+  assert.equal(recorded[0].outcome, 'not_scored');
+  assert.equal(recorded[0].score, null);
+  assert.match(recorded[0].reason, /ended \(failure\) without a result/);
+});
+
+test('nothing pending: collect does not call GitHub', async () => {
+  const gh = fakeGitHub({});
+  assert.deepEqual(await collectResults({ db: fakeDb(), cfg: CFG, fetchImpl: gh.fetchImpl, insert, recompose }), []);
+  assert.equal(gh.calls.length, 0);
+});
+
+// ---------------------------------------------------------------------------
+test('--tarball keeps the gate: outside the testing environment it refuses before reading anything', () => {
+  let out;
+  try {
+    execFileSync(process.execPath, ['scripts/gds/module-assess-tests.js', '--tarball', 'does-not-exist.tgz', '--key', 'weather', '--json'],
+      { cwd: ROOT, env: { PATH: process.env.PATH, SystemRoot: process.env.SystemRoot }, encoding: 'utf8', stdio: 'pipe' });
+  } catch (e) { out = e; }
+  assert.ok(out, 'it exits non-zero');
+  assert.match(out.stderr, /separate testing environment/);
+});
+
+test('the workflow template: no permissions for the job that runs module code, nonce in the run-name, no inputs in shell', () => {
+  const yml = fs.readFileSync(path.join(ROOT, 'scripts/gds/module-test-runner/module-tests.yml'), 'utf8');
+  assert.match(yml, /^permissions: \{\}$/m);
+  assert.match(yml, /^run-name: module-tests \$\{\{ inputs\.version_id \}\} \$\{\{ inputs\.nonce \}\}$/m);
+  assert.equal(runName(7, 'n'), 'module-tests 7 n', 'collect matches the template\'s run-name');
+  const testJob = yml.slice(yml.indexOf('\n  test:'));
+  assert.match(testJob, /permissions: \{\}/);
+  assert.match(testJob, /MODULE_TEST_SANDBOX=1/);
+  // Module code runs as an unprivileged user whose packets the firewall rejects off loopback.
+  const cut = testJob.indexOf('Cut the network');
+  const run = testJob.indexOf("Run the module's own tests");
+  assert.ok(cut > testJob.indexOf('npm ci') && cut < run, 'the network is cut after the install and before module code runs');
+  assert.match(testJob, /--uid-owner moduletest -o lo -j ACCEPT/);
+  assert.match(testJob, /--uid-owner moduletest -j REJECT/);
+  assert.match(testJob.slice(run), /sudo -u moduletest -H env -i /, 'module code runs as moduletest with a cleared environment');
+  assert.match(testJob, /name: "module-tests-\$\{\{ inputs\.version_id \}\}-\$\{\{ inputs\.nonce \}\}"/);
+  assert.equal(artifactName(7, 'n'), 'module-tests-7-n');
+  // A `run:` block never interpolates an input (script injection): inputs reach shell only via env.
+  for (const block of yml.split(/\n\s+run: /).slice(1)) {
+    const body = block.split(/\n\s+- /)[0];
+    assert.doesNotMatch(body, /\$\{\{/, `a run block interpolates an expression: ${body.slice(0, 60)}`);
+  }
+  assert.doesNotMatch(yml, /secrets\./, 'the workflow reads no secrets');
+});

package/tests/project_catalog_routes.mjs

@@ -239,7 +239,7 @@ test('the OWNER READ self-heals the projection, with the row it just read (task
 });
 
 test('a REFUSED read heals NOTHING — the repair only ever rides an own-scoped request', async () => {
-  // instanceAccessDenied answers 404 for someone else's instance, and the heal must sit
+  // requireProjectOwner answers 404 for someone else's instance, and the heal must sit
   // BEHIND that gate: an unauthenticated or wrong-owner read must never make the platform
   // write a catalog row on a stranger's behalf.
   instance = { ...BASE_ROW, owner_builder_id: 99 };

package/tests/provisioning_module_selection.mjs

@@ -494,7 +494,7 @@ await ta('PATCH /detail: a body with only a null modules key is still nothing to
 });
 
 await ta('PATCH /detail: another builder’s project is a 404, not a module change', async () => {
-  // The ownership wall is instanceAccessDenied's, shared with every sibling
+  // The ownership wall is requireProjectOwner's, shared with every sibling
   // route — pinned here because this key is new on it.
   detailRow = { id: 41, owner_builder_id: 99, slug: 'not-mine', status: 'active', type: 'game', modules: null, detail: {} };
   lastUpdatedRow = null;

package/tests/provisioning_project_owner_gate.mjs

@@ -0,0 +1,271 @@
+// tests/provisioning_project_owner_gate.mjs
+//
+// requireProjectOwner — the one owner-or-archon gate on the 14 own-scoped
+// /provisioning/instances/:id routes (task 1004159, ADR 0328 decision 2). It replaced three
+// hand-written copies of the rule and gave teardown, domain and github-app the archon
+// override they lacked.
+//
+// Covers:
+//   • the gate itself: the owner and an archon are admitted; a metic is NOT (the gate is a
+//     plain rank test, never provisioning.fleet.manage, whose floor is metic); a missing row
+//     and a foreign row are the same 404; archonOverride:false; a bad id is a 400 that never
+//     reaches the loader; a loader failure is an opaque 500
+//   • the three WIDENED routes: an archon acts on another builder's project, and the intent,
+//     the event's actor and the event's owner all say so — never 'api:self'
+//   • the gate runs before the body validator, so a stranger's malformed request is a 404
+//   • the structure: every /provisioning/instances/:id route in the three files mounts the
+//     gate (force-teardown excepted), and the old copies are gone
+//
+// DB-free: data access is stubbed on the cached module object (the provisioning_restart.mjs
+// pattern), over the real router and the real error envelope.
+//
+// Run:  node tests/provisioning_project_owner_gate.mjs
+
+import assert from 'node:assert/strict';
+import { test, before, after } from 'node:test';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const api = require(path.join(ROOT, 'src/module-api.js'));
+const provisioning = require(path.join(ROOT, 'modules/provisioning/provisioning.js'));
+const { requireProjectOwner, projectActor } = require(path.join(ROOT, 'modules/provisioning/route-helpers.js'));
+
+const OWNER = { id: 7, github_login: 'owner', rank: 'thetes' };
+const ARCHON = { id: 999, github_login: 'fleet-support', rank: 'archon' };
+const METIC = { id: 55, github_login: 'stranger', rank: 'metic' };
+const ROW = { id: 18, owner_builder_id: 7, slug: 'mercury', status: 'active', hosting_shape: 'cloud-host', domain: null, target_ref: 'owner/mercury' };
+
+// ── the gate, called directly ───────────────────────────────────────────────────────
+function fakeRes() {
+  return { out: null, fail(code, opts) { this.out = { code, status: typeof opts === 'number' ? opts : opts.status, message: opts && opts.message }; } };
+}
+async function runGate(gate, { builder, id = '18' }) {
+  const req = { params: { id }, builder, method: 'POST', path: `/provisioning/instances/${id}/teardown` };
+  const res = fakeRes();
+  let nexted = false;
+  await gate(req, res, () => { nexted = true; });
+  return { req, res, nexted };
+}
+const loads = [];
+const loader = (rows) => async (id) => { loads.push(id); return rows[id] ? { ...rows[id] } : null; };
+
+test('the owner is admitted and the row rides on req.project', async () => {
+  const { req, res, nexted } = await runGate(requireProjectOwner(loader({ 18: ROW })), { builder: OWNER });
+  assert.equal(nexted, true);
+  assert.equal(res.out, null);
+  assert.equal(req.project.slug, 'mercury');
+  assert.equal(projectActor(req), 'api:self');
+});
+
+test('an archon is admitted on another builder’s project, and the actor names that archon', async () => {
+  const { req, nexted } = await runGate(requireProjectOwner(loader({ 18: ROW })), { builder: ARCHON });
+  assert.equal(nexted, true);
+  assert.equal(projectActor(req), 'api:archon:999');
+});
+
+test('a metic is NOT admitted: the gate is a rank test, not provisioning.fleet.manage (floor metic)', async () => {
+  const { req, res, nexted } = await runGate(requireProjectOwner(loader({ 18: ROW })), { builder: METIC });
+  assert.equal(nexted, false);
+  assert.deepEqual([res.out.code, res.out.status], ['instance_not_found', 404]);
+  assert.equal(req.project, undefined, 'a refused request carries no row');
+});
+
+test('a missing row is the same 404 a foreign one gets — for an archon too', async () => {
+  for (const builder of [OWNER, ARCHON]) {
+    const { res, nexted } = await runGate(requireProjectOwner(loader({})), { builder });
+    assert.equal(nexted, false);
+    assert.deepEqual([res.out.code, res.out.status], ['instance_not_found', 404]);
+  }
+});
+
+test('archonOverride:false refuses an archon on a foreign project and still admits the owner', async () => {
+  const gate = requireProjectOwner(loader({ 18: ROW }), { archonOverride: false });
+  assert.equal((await runGate(gate, { builder: ARCHON })).res.out.status, 404);
+  assert.equal((await runGate(gate, { builder: OWNER })).nexted, true);
+});
+
+test('a malformed id is 400 bad_id and never reaches the loader', async () => {
+  loads.length = 0;
+  const { res, nexted } = await runGate(requireProjectOwner(loader({ 18: ROW })), { builder: OWNER, id: 'not-a-number' });
+  assert.equal(nexted, false);
+  assert.deepEqual([res.out.code, res.out.status], ['bad_id', 400]);
+  assert.deepEqual(loads, []);
+});
+
+test('a loader that throws is an opaque 500 — neither the 404 nor the error text', async () => {
+  const gate = requireProjectOwner(async () => { throw new Error('relation "provisioning_instances" does not exist'); });
+  const { res, nexted } = await runGate(gate, { builder: OWNER });
+  assert.equal(nexted, false);
+  assert.deepEqual(res.out, { code: 'instance_read_failed', status: 500, message: 'internal error' });
+});
+
+// ── the three widened routes, over the real router ──────────────────────────────────
+let builder = OWNER;
+let row = null;
+const events = [];
+const enqueues = [];
+const manifests = [];
+api.requireBuilder = (req, _res, next) => { req.builder = { ...builder }; next(); };
+api.requirePermission = () => (_req, _res, next) => next();
+api.branding = () => ({ domains: { publicOrigin: 'https://cb.test', instanceBase: 'cb.test' }, identity: { productName: 'Cloud Bongos' } });
+provisioning.getInstanceById = async (_db, id) => (row && String(id) === String(row.id) ? { ...row } : null);
+provisioning.recordEvent = async (_db, e) => { events.push(e); };
+provisioning.enqueueTeardown = async (_db, id, requestedBy) => { enqueues.push({ action: 'teardown', id, requestedBy }); return { created: true, superseded: false }; };
+provisioning.enqueueIntent = async (_db, id, action, requestedBy) => { enqueues.push({ action, id, requestedBy }); return { intent: { id: 9, action, state: 'pending' }, created: true }; };
+provisioning.getOpenIntent = async () => null;
+provisioning.getInstanceByDomain = async () => null;
+provisioning.updateInstanceDomain = async (_db, id, domain) => ({ ...row, id, domain });
+provisioning.createOAuthManifest = async (_db, m) => { manifests.push(m); return { id: 1, ...m }; };
+provisioning.getLatestOAuthManifestForInstance = async () => null;
+
+const express = require('express');
+const { attachFail } = require(path.join(ROOT, 'src/bongos/middleware/error-envelope.js'));
+let server, base;
+before(async () => {
+  const app = express();
+  app.use(express.json());
+  app.use(attachFail);
+  app.use('/api/bongos', require(path.join(ROOT, 'modules/provisioning/routes/provisioning.js'))());
+  server = app.listen(0);
+  await new Promise((r) => server.once('listening', r));
+  base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+});
+after(() => server.close());
+
+function post(p, body = {}) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request(`${base}${p}`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+    }, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; });
+      res.on('end', () => resolve({ status: res.statusCode, body: JSON.parse(d), raw: d }));
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+function as(who, inst) {
+  builder = who;
+  row = inst;
+  events.length = 0; enqueues.length = 0; manifests.length = 0;
+}
+
+test('teardown: an archon tears down another builder’s project, audited as the archon', async () => {
+  as(ARCHON, { ...ROW });
+  const r = await post('/provisioning/instances/18/teardown');
+  assert.equal(r.status, 200, r.raw);
+  assert.deepEqual(enqueues, [{ action: 'teardown', id: 18, requestedBy: 'api:archon:999' }]);
+  assert.equal(events.length, 1);
+  assert.equal(events[0].actor, 'api:archon:999');
+  assert.equal(events[0].ownerBuilderId, 7, 'the event belongs to the project’s owner, not the archon');
+  assert.match(events[0].detail, /teardown requested by archon fleet-support/);
+  assert.doesNotMatch(events[0].detail, /by owner/);
+});
+
+test('teardown: the owner’s own request still reads as the owner’s', async () => {
+  as(OWNER, { ...ROW });
+  const r = await post('/provisioning/instances/18/teardown');
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(enqueues[0].requestedBy, 'api:self');
+  assert.equal(events[0].actor, 'api:self');
+  assert.equal(events[0].detail, 'teardown requested by owner');
+});
+
+test('domain: an archon sets another builder’s address, and the intent and events name the archon', async () => {
+  as(ARCHON, { ...ROW });
+  const r = await post('/provisioning/instances/18/domain', { domain: 'mercury.example.com' });
+  assert.equal(r.status, 200, r.raw);
+  assert.deepEqual(enqueues, [{ action: 'domain-attach', id: 18, requestedBy: 'api:archon:999' }]);
+  assert.ok(events.length >= 1);
+  for (const e of events) {
+    assert.equal(e.actor, 'api:archon:999');
+    assert.equal(e.ownerBuilderId, 7);
+  }
+});
+
+test('domain: an archon’s re-kick of a stopped address is recorded as the archon’s', async () => {
+  as(ARCHON, { ...ROW, domain: 'mercury.example.com', last_verified_up: false });
+  const r = await post('/provisioning/instances/18/domain', { domain: 'mercury.example.com' });
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(r.body.queued, true);
+  assert.equal(enqueues[0].requestedBy, 'api:archon:999');
+  assert.equal(events[0].actor, 'api:archon:999');
+  assert.match(events[0].detail, /archon re-kick/);
+});
+
+test('github-app: an archon mints the link for another builder’s project, audited as the archon', async () => {
+  as(ARCHON, { ...ROW, domain: 'mercury.example.com' });
+  const r = await post('/provisioning/instances/18/github-app');
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(manifests.length, 1);
+  assert.equal(manifests[0].requestedBy, 7, 'requested_by is the owner every later manifest event is filed under');
+  assert.equal(events.length, 1);
+  assert.equal(events[0].actor, 'api:archon:999');
+  assert.equal(events[0].ownerBuilderId, 7);
+});
+
+test('github-app: the owner’s own mint is still api:self', async () => {
+  as(OWNER, { ...ROW, domain: 'mercury.example.com' });
+  const r = await post('/provisioning/instances/18/github-app');
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(events[0].actor, 'api:self');
+});
+
+test('the three widened routes stay closed to a non-archon stranger: 404, nothing queued or recorded', async () => {
+  for (const [p, body] of [['teardown', {}], ['domain', { domain: 'mercury.example.com' }], ['github-app', {}]]) {
+    as(METIC, { ...ROW, domain: 'mercury.example.com' });
+    const r = await post(`/provisioning/instances/18/${p}`, body);
+    assert.equal(r.status, 404, `${p}: ${r.raw}`);
+    assert.equal(r.body.error.code, 'instance_not_found');
+    assert.deepEqual([enqueues.length, events.length, manifests.length], [0, 0, 0], p);
+  }
+});
+
+test('the gate runs before the body validator: a stranger’s malformed request is the same 404', async () => {
+  as(METIC, { ...ROW });
+  const bad = await post('/provisioning/instances/18/domain', { domain: 'not a hostname' });
+  assert.equal(bad.status, 404, bad.raw);
+  as(OWNER, { ...ROW });
+  const own = await post('/provisioning/instances/18/domain', { domain: 'not a hostname' });
+  assert.equal(own.status, 400, 'the owner still gets the validator’s answer');
+  assert.equal(own.body.error.code, 'bad_domain');
+});
+
+// ── the structure ───────────────────────────────────────────────────────────────────
+const ROUTE_FILES = ['provisioning.js', 'disconnect.js', 'env-manifest.js']
+  .map((f) => path.join(ROOT, 'modules/provisioning/routes', f));
+const read = (f) => fs.readFileSync(f, 'utf8').replace(/\r\n/g, '\n');
+
+test('every /provisioning/instances/:id route in the three files mounts the gate (force-teardown excepted)', () => {
+  const declared = [];
+  for (const f of ROUTE_FILES) {
+    for (const line of read(f).split('\n')) {
+      const m = /router\.(get|post|patch|put|delete)\('(\/provisioning\/instances\/:id[^']*)'/.exec(line);
+      if (!m || m[2].endsWith('/force-teardown')) continue;
+      declared.push(`${m[1]} ${m[2]}`);
+      assert.match(line, /requireBuilder, (?:\w+, )?requireProjectOwner\(loadInstance\), async \(req, res\) =>/, `${m[1]} ${m[2]}`);
+    }
+  }
+  assert.equal(declared.length, 14, `the 14 own-scoped routes, found: ${declared.join(' · ')}`);
+});
+
+test('the three old copies of the rule are gone', () => {
+  const dir = path.join(ROOT, 'modules/provisioning');
+  const src = fs.readdirSync(dir, { recursive: true }).map(String)
+    .filter((f) => f.endsWith('.js') && !f.split(path.sep).includes('tests'))
+    .map((f) => read(path.join(dir, f))).join('\n');
+  assert.doesNotMatch(src, /function instanceAccessDenied|function resolveOwnInstance/);
+  for (const f of ROUTE_FILES) {
+    // `inst.` only: the create route's re-request check compares its NEW row, which no gate can load
+    assert.doesNotMatch(read(f), /\binst\.owner_builder_id\) [!=]== String\(req\.builder\.id\)/, `${path.basename(f)} compares owners inline`);
+    assert.doesNotMatch(read(f), /rank [!=]== 'archon'/, `${path.basename(f)} tests the rank inline`);
+  }
+});