@bongos/core 1.19.732 → 1.19.734

package/tests/agents_spend_guard.mjs

@@ -0,0 +1,272 @@
+// tests/agents_spend_guard.mjs — the spend guard and the per-payer spend ceiling
+// (task 1003884).
+//
+// Two independent walls, tested apart because they fail in different directions:
+//
+//   1. the CONFIG-LOAD guard (src/modules.js) — a module that declares it meters
+//      money for its callers is not ENABLED at all on an instance whose join door
+//      is `open` with no payer configured;
+//   2. the per-payer MONTHLY CEILING (modules/agents/lib/spend-ceiling.js) — a
+//      payer who has spent their month cannot fire, and so, deliberately, cannot
+//      anyone whose ceiling could not be established.
+//
+// The second is where task 1001393's defect is pinned: that spend brake read
+// month-to-date spend from a database it could not reach and FAILED OPEN, so it
+// never tripped. Several cases below exist only to assert this one fails closed.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync } from 'node:fs';
+// Imported BY NAME rather than destructured off a default import: knip cannot
+// follow a name through `import mod from '...'` + `const { x } = mod`, so the
+// guard's tested exports would read as dead code and the ratchet would block the
+// merge on a file whose every export is genuinely used right here.
+import { resolveModules, spendRefusals, metersSpend, PAYERS, warnSpendRefusal } from '../src/modules.js';
+import { validateManifest } from '../src/module-loader/manifest-schema.js';
+import ceilingMod from '../modules/agents/lib/spend-ceiling.js';
+import spawnMod from '../modules/agents/spawn.js';
+
+const { createSpendCeiling, payerFor, monthStartUtc, DEFAULT_CAP_USD } = ceilingMod;
+const { plannedRow } = spawnMod;
+
+// A registry with one metered module and one ordinary one, so every assertion can
+// show that the guard bites the declaring module and NOTHING else.
+const REG = {
+  metered: { default: false, contributes: {}, _spend: { requiresPayer: true } },
+  plain: { default: false, contributes: {} },
+};
+const BOTH_ON = { modules: { metered: true, plain: true } };
+const silent = () => {};
+const resolve = (spendGuard, extra = {}) =>
+  resolveModules({ instance: BOTH_ON, registry: REG, spendGuard, warn: silent, ...extra });
+
+// ---------------------------------------------------------------------------
+// 1. the config-load guard
+// ---------------------------------------------------------------------------
+
+test('an OPEN join door with NO payer refuses the metered module — and only that one', () => {
+  const m = resolve({ joinDoorOpen: true, payer: null });
+  assert.equal(m.metered, false, 'anyone can sign up and nobody is on the hook — it must not mount');
+  assert.equal(m.plain, true, 'a module that never said it spends money is untouched');
+});
+
+test('a CLOSED join door leaves it enabled: the people who can call it were let in deliberately', () => {
+  assert.equal(resolve({ joinDoorOpen: false, payer: null }).metered, true);
+});
+
+test('an open door WITH a payer leaves it enabled — somebody is on the hook, and the ceiling bounds them', () => {
+  for (const payer of PAYERS) {
+    assert.equal(resolve({ joinDoorOpen: true, payer }).metered, true, payer);
+  }
+});
+
+test('anything that is not one of the two payer words is NO payer', () => {
+  // The direction that matters: a typo, a stale value, or a word a newer core
+  // understands must never read as "somebody is paying".
+  for (const bad of ['Project', 'BUILDER', 'none', '', ' project', 'owner', null, undefined, 0, true]) {
+    assert.equal(resolve({ joinDoorOpen: true, payer: bad }).metered, false, JSON.stringify(bad));
+  }
+});
+
+test('the refusal outranks the env override — it is a wall, not another precedence level', () => {
+  // <PREFIX>_MODULE_METERED=1 is the highest-precedence way to turn a module on,
+  // and it is exactly the knob a cheap deploy reaches for. It must not lift this.
+  const m = resolveModules({
+    instance: { modules: { metered: false } },
+    env: { BONGOS_MODULE_METERED: '1' },
+    envPrefix: 'BONGOS',
+    registry: REG,
+    spendGuard: { joinDoorOpen: true, payer: null },
+    warn: silent,
+  });
+  assert.equal(m.metered, false, 'env cannot buy its way past the guard');
+});
+
+test('the refusal is LOUD: it names the module, the two payer words and the env var that lifts it', () => {
+  const said = [];
+  resolveModules({
+    instance: BOTH_ON, registry: REG, envPrefix: 'MERCURY',
+    spendGuard: { joinDoorOpen: true, payer: null },
+    warn: (key, prefix) => said.push([key, prefix]),
+  });
+  assert.deepEqual(said, [['metered', 'MERCURY']], 'exactly the refused module, under this pack\'s prefix');
+
+  // And the default warner writes something an operator can act on, under the
+  // instance's OWN prefix rather than a hardcoded one.
+  const lines = [];
+  warnSpendRefusal('metered', 'MERCURY', { warn: (s) => lines.push(s) });
+  assert.equal(lines.length, 1);
+  assert.match(lines[0], /metered/);
+  assert.match(lines[0], /MERCURY_SPEND_PAYER/, 'names the variable, under the right prefix');
+  for (const p of PAYERS) assert.match(lines[0], new RegExp(p), `names the ${p} payer`);
+});
+
+test('callers that know nothing about spend resolve exactly as before', () => {
+  // Every existing call site passes no spendGuard. The default must change nothing
+  // — the fail-closed reading belongs to loadModules, where "unknown" can arise.
+  assert.equal(resolveModules({ instance: BOTH_ON, registry: REG }).metered, true);
+});
+
+test('metersSpend reads the module\'s own declaration, and only a literal true', () => {
+  assert.equal(metersSpend({ _spend: { requiresPayer: true } }), true);
+  for (const bad of [undefined, null, {}, { _spend: {} }, { _spend: { requiresPayer: 'true' } }, { _spend: { requiresPayer: 1 } }]) {
+    assert.equal(metersSpend(bad), false, JSON.stringify(bad));
+  }
+});
+
+test('spendRefusals never names a module that was already off', () => {
+  const off = { metered: false, plain: false };
+  assert.deepEqual(spendRefusals(off, REG, { joinDoorOpen: true, payer: null }), []);
+});
+
+test('the manifest declaration is a CLOSED key set — a typo must not read as "no spend"', () => {
+  const base = { key: 'x', title: 't', description: 'd', coreVersion: '^1.0.0', contributes: {} };
+  assert.equal(validateManifest({ ...base, spend: { requiresPayer: true } }).valid, true);
+  assert.equal(validateManifest({ ...base, spend: { requirespayer: true } }).valid, false,
+    'a misspelled key silently declaring NO spend is the direction that costs money');
+  assert.equal(validateManifest({ ...base, spend: { requiresPayer: 'yes' } }).valid, false);
+  assert.equal(validateManifest({ ...base, spend: true }).valid, false);
+});
+
+test('the agents module actually declares it — the guard guards something', () => {
+  // The whole chain is inert if the manifest never says so, and that failure is
+  // invisible: everything still resolves, nothing is ever refused.
+  const manifest = JSON.parse(readFileSync(new URL('../modules/agents/module.json', import.meta.url), 'utf8'));
+  assert.equal(manifest.spend && manifest.spend.requiresPayer, true);
+  assert.equal(manifest.default, false, 'and it still ships disabled');
+});
+
+// ---------------------------------------------------------------------------
+// 2. who pays for one fire
+// ---------------------------------------------------------------------------
+
+test('payerFor: `builder` bills the caller, everything else bills the project', () => {
+  assert.deepEqual(payerFor('builder', 7), { payer_kind: 'builder', payer_builder_id: 7 });
+  assert.deepEqual(payerFor('project', 7), { payer_kind: 'project', payer_builder_id: null });
+  assert.deepEqual(payerFor('none', 7), { payer_kind: 'project', payer_builder_id: null });
+  assert.deepEqual(payerFor(null, 7), { payer_kind: 'project', payer_builder_id: null });
+});
+
+test('an event fire has no caller, so it can only be the project — never nobody', () => {
+  // Nobody asked for it, so there is nobody to bill; falling to "no payer" would
+  // make the event path the one unbounded route through the ceiling.
+  assert.deepEqual(payerFor('builder', null), { payer_kind: 'project', payer_builder_id: null });
+  assert.deepEqual(payerFor('builder', undefined), { payer_kind: 'project', payer_builder_id: null });
+});
+
+test('every ledger row carries a payer — including a no-go, which cost nothing', () => {
+  const go = plannedRow({ definition: { id: 1, name: 'a' }, gate: { decision: 'go' }, requestedByBuilderId: 4, spendPayer: 'builder' });
+  assert.equal(go.payer_kind, 'builder');
+  assert.equal(go.payer_builder_id, 4);
+
+  const nogo = plannedRow({ definition: { id: 1, name: 'a' }, gate: { decision: 'no-go', reason: 'x' }, requestedByBuilderId: 4, spendPayer: 'builder' });
+  assert.equal(nogo.status, 'skipped');
+  assert.equal(nogo.payer_kind, 'builder', 'a refusal is still a fire somebody would have been billed for');
+});
+
+test('who ASKED and who PAYS are different columns, and differ under a project payer', () => {
+  const row = plannedRow({ definition: { id: 1, name: 'a' }, gate: { decision: 'go' }, requestedByBuilderId: 9, spendPayer: 'project' });
+  assert.equal(row.requested_by_builder_id, 9);
+  assert.equal(row.payer_kind, 'project');
+  assert.equal(row.payer_builder_id, null, 'the project pays; the asker is recorded but not billed');
+});
+
+// ---------------------------------------------------------------------------
+// 3. the per-payer monthly ceiling — every branch fails CLOSED
+// ---------------------------------------------------------------------------
+
+const poolOf = (spent) => ({ query: async () => ({ rows: [{ spent }] }) });
+const AT = Date.UTC(2026, 8, 13, 12, 0, 0); // 2026-09-13
+const PROJECT = { payer_kind: 'project', payer_builder_id: null };
+
+test('under the cap: allowed, with the arithmetic shown', () => {
+  const c = createSpendCeiling({ capUsd: 25, now: () => AT });
+  return c.check(poolOf('4.5000'), PROJECT).then((r) => {
+    assert.equal(r.ok, true);
+    assert.equal(r.spentUsd, 4.5);
+    assert.equal(r.remainingUsd, 20.5);
+    assert.equal(r.reason, null);
+  });
+});
+
+test('at or past the cap: refused, and the refusal says which', async () => {
+  const c = createSpendCeiling({ capUsd: 25, now: () => AT });
+  for (const spent of ['25', '25.0001', '900']) {
+    const r = await c.check(poolOf(spent), PROJECT);
+    assert.equal(r.ok, false, spent);
+    assert.equal(r.reason, 'spend_cap_reached', spent);
+    assert.equal(r.remainingUsd, 0, spent);
+  }
+});
+
+test('AN UNREADABLE LEDGER REFUSES — the exact defect task 1001393 was filed about', async () => {
+  // That brake read month-to-date spend from a DB it could not reach and fell
+  // through to "go ahead". "I cannot tell what has been spent" is the moment a
+  // ceiling matters most.
+  const throws = { query: async () => { throw new Error('ECONNREFUSED'); } };
+  const r = await createSpendCeiling({ capUsd: 25, now: () => AT }).check(throws, PROJECT);
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'ledger_unreadable');
+  assert.equal(r.spentUsd, null, 'it must not claim a sum it does not have');
+});
+
+test('a missing pool, and a sum that is not a number, are the same "I do not know"', async () => {
+  const c = createSpendCeiling({ capUsd: 25, now: () => AT });
+  assert.equal((await c.check(null, PROJECT)).reason, 'ledger_unreadable');
+  assert.equal((await c.check({}, PROJECT)).reason, 'ledger_unreadable');
+  for (const junk of ['abc', null, undefined, -1]) {
+    assert.equal((await c.check(poolOf(junk), PROJECT)).ok, false, JSON.stringify(junk));
+  }
+});
+
+test('NO CAP IS NOT AN INFINITE CAP — an unbounded ceiling is the defect wearing a cap\'s name', async () => {
+  for (const cap of [0, -5, Number.NaN, Number.POSITIVE_INFINITY, null, 'lots']) {
+    const r = await createSpendCeiling({ capUsd: cap, now: () => AT }).check(poolOf('0'), PROJECT);
+    assert.equal(r.ok, false, String(cap));
+    assert.equal(r.reason, 'no_spend_cap_configured', String(cap));
+  }
+});
+
+test('no payer to bill: refused, matching fire-budget\'s reading of an unidentified caller', async () => {
+  const c = createSpendCeiling({ capUsd: 25, now: () => AT });
+  for (const p of [null, undefined, {}, { payer_kind: 'nobody' }, { payer_kind: 'builder', payer_builder_id: null }]) {
+    const r = await c.check(poolOf('0'), p);
+    assert.equal(r.ok, false, JSON.stringify(p));
+    assert.equal(r.reason, 'no_payer', JSON.stringify(p));
+  }
+});
+
+test('the window is the calendar month, and the sum is scoped to THIS payer', async () => {
+  let captured = null;
+  const spy = { query: async (_sql, params) => { captured = params; return { rows: [{ spent: '1' }] }; } };
+  await createSpendCeiling({ capUsd: 25, now: () => AT })
+    .check(spy, { payer_kind: 'builder', payer_builder_id: 12 });
+  assert.deepEqual(captured[0], new Date(Date.UTC(2026, 8, 1)), 'since the 1st, UTC');
+  assert.equal(captured[1], 'builder');
+  assert.equal(captured[2], 12, 'one builder\'s month, not every builder\'s');
+});
+
+test('monthStartUtc is the 1st at midnight UTC, including on the 1st itself', () => {
+  assert.deepEqual(monthStartUtc(Date.UTC(2026, 0, 31, 23, 59)), new Date(Date.UTC(2026, 0, 1)));
+  assert.deepEqual(monthStartUtc(Date.UTC(2026, 0, 1, 0, 0)), new Date(Date.UTC(2026, 0, 1)));
+});
+
+test('the default cap is a real, small, finite number — a default is what an unthinking instance gets', () => {
+  assert.ok(Number.isFinite(DEFAULT_CAP_USD) && DEFAULT_CAP_USD > 0);
+  assert.ok(DEFAULT_CAP_USD <= 100, 'generous defaults are how an unbounded bill arrives');
+});
+
+test('the ceiling RECORDS NOTHING — the ledger is the only tally', async () => {
+  // fire-budget.check deliberately records the fire it admits. This one must not:
+  // a second tally is the "two disagreeing answers to what did agents cost" that
+  // fire-budget's own header refuses to become.
+  const c = createSpendCeiling({ capUsd: 25, now: () => AT });
+  const writes = [];
+  const pool = { query: async (sql) => { writes.push(sql); return { rows: [{ spent: '1' }] }; } };
+  await c.check(pool, PROJECT);
+  await c.check(pool, PROJECT);
+  assert.equal(writes.length, 2, 'two reads');
+  for (const sql of writes) {
+    assert.match(sql, /^\s*SELECT/i, 'reads only');
+    assert.doesNotMatch(sql, /INSERT|UPDATE|DELETE/i);
+  }
+});

package/tests/agents_write_routes.mjs

@@ -42,7 +42,7 @@ const ARMED = Object.freeze({
   created_at: 'T0', updated_at: 'T0',
 });
 
-function fakePool({ definition = ARMED, runId = 42 } = {}) {
+function fakePool({ definition = ARMED, runId = 42, spentUsd = '0' } = {}) {
   const calls = [];
   return {
     calls,
@@ -60,6 +60,12 @@ function fakePool({ definition = ARMED, runId = 42 } = {}) {
       if (/^\s*INSERT INTO agents_definitions/.test(sql)) return { rows: [{ ...ARMED, name: params[0], enabled: false }] };
       if (/^\s*UPDATE agents_definitions/.test(sql)) return { rows: [{ ...definition, enabled: /enabled = true/.test(sql) }], rowCount: 1 };
       if (/^\s*DELETE FROM agents_definitions/.test(sql)) return { rows: [], rowCount: 1 };
+      // THE SPEND CEILING'S READ (task 1003884), and it must be tested BEFORE the
+      // generic agents_runs branch below — the same anchoring lesson that branch's
+      // own comment records about SELECT vs DELETE. Matched last, the ceiling's
+      // SUM would be answered with a ledger ROW, which has no `spent` column, and
+      // the ceiling would correctly refuse every fire in this file as unreadable.
+      if (/SUM\(cost_usd\)/.test(sql)) return { rows: [{ spent: spentUsd }] };
       if (/FROM agents_runs/.test(sql)) {
         // The ownership filter is params[1]; the fake honours it so the IDOR test
         // exercises the real WHERE clause rather than a stub that ignores it.
@@ -184,6 +190,50 @@ await t('the persona and the caller\'s input BOTH reach the model', async () =>
   assert.match(lastPrompt, /why is it so\?/);
 });
 
+await t('the fire records WHO PAYS beside who asked (task 1003884)', async () => {
+  const pool = fakePool();
+  api.pool = pool;
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/invoke')(req({ params: { name: 'historian' } }), res);
+  const row = pool.insertedRun();
+  assert.equal(row.requested_by_builder_id, 5, 'who asked');
+  // The neutral pack ships spend_payer 'none', which attributes to the PROJECT —
+  // that is who the money actually comes from, and it is what keeps a closed-door
+  // instance working exactly as it did (ADR 0282).
+  assert.equal(row.payer_kind, 'project', 'who is on the hook');
+  assert.equal(row.payer_builder_id, null);
+});
+
+await t('A PAYER AT THE CAP IS REFUSED 402, and nothing is spawned or ledgered', async () => {
+  // The ceiling is wired ahead of the definition read, so an exhausted payer costs
+  // not even a SELECT. 402 rather than fire-budget's 429 on purpose: "the money is
+  // gone" and "too fast, try later" are different operator problems.
+  const pool = fakePool({ spentUsd: '9999' });
+  api.pool = pool;
+  lastPrompt = null;
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/invoke')(req({ params: { name: 'historian' } }), res);
+
+  assert.equal(res.out.status, 402);
+  assert.equal(res.out.failed.code, 'spend_cap_reached');
+  assert.equal(res.out.failed.details.reason, 'spend_cap_reached');
+  assert.equal(res.out.failed.details.payer_kind, 'project');
+  assert.equal(pool.insertedRun(), null, 'a refused fire writes no run');
+  assert.equal(lastPrompt, null, 'and calls no model');
+});
+
+await t('AN UNREADABLE LEDGER REFUSES THE FIRE — the ceiling fails closed at the route too', async () => {
+  // The lib-level case is in tests/agents_spend_guard.mjs; this one proves the
+  // route honours it rather than falling through, which is the half that task
+  // 1001393's failed-open brake actually got wrong.
+  api.pool = { async query() { throw new Error('ECONNREFUSED'); } };
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/invoke')(req({ params: { name: 'historian' } }), res);
+  assert.equal(res.out.status, 402);
+  assert.equal(res.out.failed.details.reason, 'ledger_unreadable');
+  assert.equal(res.out.failed.details.spent_usd, null, 'it claims no sum it does not have');
+});
+
 await t('a body key the schema does not name is refused rather than ignored', async () => {
   api.pool = fakePool();
   const res = fakeRes();

package/tests/bump_version.mjs

@@ -171,7 +171,84 @@ test('publish.yml wires the terminator: guard step present, every armed step gat
   assert.ok(PUBLISH_YML.includes('id: relhead'), 'the Already released? guard step exists');
   assert.match(PUBLISH_YML, /isReleaseCommit/, 'the guard delegates to bump-version.js — single source');
   const gates = (PUBLISH_YML.match(/steps\.relhead\.outputs\.release_head == 'false'/g) || []).length;
-  assert.ok(gates >= 7, `every post-guard armed step must carry the gate (setup-node, install, resolve, bump, pack, publish, tag) — found ${gates}`);
+  assert.ok(gates >= 7, `every post-guard armed step must carry the gate (setup-node, install, resolve, bump, pack, publish, record, tag) — found ${gates}`);
+});
+
+// ---- the release ORDER: publish before push (task 1003914) ----
+//
+// The bug this pins: publish.yml used to push the bump commit to main BEFORE
+// packaging and publishing. A failure in either left main permanently declaring
+// a version that never reached npm, and the cascade terminator above then made
+// it unretryable — HEAD was this lane's own release commit, so every following
+// run no-opped and only a fresh work merge moved past the hole. 1.19.716-723
+// were minted and lost that way on 2026-09-13.
+//
+// These are source-order assertions because a workflow's step order IS its
+// source; there is nothing to execute here. They key on the actual COMMANDS,
+// never on prose, so a comment rewrite can't make them pass falsely.
+
+const BRANCH_PUSH = ['git', 'push', 'origin', 'HEAD:main'].join(' ');
+
+test('the bump commit is pushed only AFTER npm publish — the irreversible step goes last', () => {
+  const publishAt = PUBLISH_YML.indexOf('npm publish "$TGZ"');
+  const pushAt = PUBLISH_YML.indexOf(BRANCH_PUSH);
+  assert.ok(publishAt !== -1, 'publish.yml must publish the packaged tarball');
+  assert.ok(pushAt !== -1, 'publish.yml must push the bump commit to main somewhere');
+  assert.ok(
+    publishAt < pushAt,
+    'the push to main must come AFTER npm publish. Pushing first makes a failed publish burn the version number permanently and unretryably (task 1003914).',
+  );
+});
+
+test('the push to main happens exactly once, and not inside the bump step', () => {
+  const pushes = PUBLISH_YML.split(BRANCH_PUSH).length - 1;
+  assert.equal(pushes, 1, `exactly one push of the bump to main — found ${pushes}`);
+  // The bump step runs from `id: bump` up to the next step's `- name:`.
+  const bumpAt = PUBLISH_YML.indexOf('id: bump');
+  assert.ok(bumpAt !== -1, 'the bump step must carry id: bump');
+  const nextStepAt = PUBLISH_YML.indexOf('\n      - name:', bumpAt);
+  const bumpStep = PUBLISH_YML.slice(bumpAt, nextStepAt === -1 ? undefined : nextStepAt);
+  assert.ok(
+    !bumpStep.includes(BRANCH_PUSH),
+    'the bump step must COMMIT only — its push moved to the record step so a pack/publish failure discards a purely local commit',
+  );
+  assert.ok(bumpStep.includes('git commit -m'), 'the bump step still commits locally — package-core stamps the version found AT the ref');
+});
+
+test('an already-published version is success, not a wedge', () => {
+  // Publish-then-failed-push leaves a version on npm with no release commit.
+  // The next run reads it as free (laneReleasedVersions is git-based), bumps to
+  // it, and npm refuses the duplicate. Without this branch that run fails, and
+  // so does every run after it — the lane wedges with no way out but a human.
+  const pubAt = PUBLISH_YML.indexOf('id: pub');
+  assert.ok(pubAt !== -1, 'the publish step must carry id: pub');
+  const pubStep = PUBLISH_YML.slice(pubAt, PUBLISH_YML.indexOf('\n      # PUBLISH VERDICT'));
+  assert.match(
+    pubStep,
+    /cannot publish over\|previously published\|EPUBLISHCONFLICT/,
+    'the publish step must recognise npm refusing a duplicate version',
+  );
+  assert.match(pubStep, /already=true/, 'and must record that it took the already-present branch');
+  assert.match(
+    pubStep,
+    /exit "\$RC"/,
+    'every OTHER publish failure must still fail the step — the tolerance is narrow on purpose',
+  );
+});
+
+test('the record step gates on a bump actually having been made', () => {
+  const recAt = PUBLISH_YML.indexOf('- name: Record the release on main');
+  assert.ok(recAt !== -1, 'the record step exists');
+  const recStep = PUBLISH_YML.slice(recAt, PUBLISH_YML.indexOf('\n      # PUBLISH VERDICT'));
+  assert.match(
+    recStep,
+    /steps\.bump\.outputs\.to != ''/,
+    'nothing to push when no bump was made (taken == false) — the step must skip rather than push an empty HEAD',
+  );
+  assert.ok(
+    !recStep.includes('git rebase'),
+    'no rebase-retry: the tarball was built from the pre-rebase tree, so rebasing would leave source_commit naming a SHA that is not on main',
+  );
 });
 
 // ---------------------------------------------------------------------------

package/tests/currency_label.mjs

@@ -54,11 +54,16 @@ test('clientBranding exposes project policy — the settings read-back (task 100
   // `artistGate` joined in task 1003575 (ADR 0241) and is the ONE key here whose
   // fallback is not today's behaviour: 'strict' is the owner's ruling, safe as a
   // default because it can only ever delay a pin move, never a builder's ship.
+  // `spendPayer` joined in task 1003884 (ADR 0282) — who pays when a module spends
+  // money for whoever called it. Its fallback IS today's behaviour ('none'), and it
+  // is published for a reason of its own: it is the one key that can REFUSE a
+  // module, so an owner looking at a module that will not turn on needs the
+  // instance's own answer rather than the platform's record of what they saved.
   assert.deepEqual(clientBranding({}).project,
-    { platformVisibility: 'public', joinability: 'apply', visibility: 'public', joinGrant: 'full', artistGate: 'strict' });
+    { platformVisibility: 'public', joinability: 'apply', visibility: 'public', joinGrant: 'full', artistGate: 'strict', spendPayer: 'none' });
   assert.deepEqual(
-    clientBranding({ project: { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth', joinGrant: 'view', artistGate: 'off' } }).project,
-    { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth', joinGrant: 'view', artistGate: 'off' },
+    clientBranding({ project: { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth', joinGrant: 'view', artistGate: 'off', spendPayer: 'builder' } }).project,
+    { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth', joinGrant: 'view', artistGate: 'off', spendPayer: 'builder' },
     'what the instance actually resolved (env override included) is what it publishes');
 });
 
@@ -81,7 +86,7 @@ test('clientBranding is a SMALL allow-list — no server-only field leaks to the
   // public for the same read-back reason as its neighbours. Its companion stamp
   // (artistGateSince) deliberately does NOT: that is platform bookkeeping the server
   // reads, and no browser surface has a question it answers.
-  assert.deepEqual(Object.keys(projected.project).sort(), ['artistGate', 'joinGrant', 'joinability', 'platformVisibility', 'visibility']);
+  assert.deepEqual(Object.keys(projected.project).sort(), ['artistGate', 'joinGrant', 'joinability', 'platformVisibility', 'spendPayer', 'visibility']);
   for (const leak of ['domains', 'repo', 'db', 'envPrefix', 'llmProjectName']) {
     assert.equal(projected[leak], undefined, `${leak} must not reach the client`);
   }

package/tests/dead_feature_claim.mjs

@@ -0,0 +1,176 @@
+// tests/dead_feature_claim.mjs — the runtime-dead severity floor (task 1002665).
+//
+// Evidence: on the task 1002648 ship the Quality worker found that the new PATCH
+// needs_migration path threw at runtime, wrote "the feature is entirely
+// non-operational", filed it at severity `nit`, and the grade PASSed. The dead
+// feature merged to main; it was caught only because the builder read the prose.
+//
+// Two halves are proved here. The FLOOR raises such a finding to `major` so the
+// worker's own logic and every reader see the severity its own words imply. The
+// CLASSIFIER is deliberately narrow, and most of these cases exist to prove what
+// it does NOT match — a false positive costs a builder a manual-confirm round,
+// so conditional defects, praise for deleted code, and the ambiguous word
+// "unreachable" all have to stay out.
+//
+// Run:  node tests/dead_feature_claim.mjs
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { deadFeatureClaim, issueClaimsRuntimeDead, applyDeadFeatureFloor } = require('../modules/grading/dead-feature-claim.js');
+const { parseCommon, applySeverityGatePolicy } = require('../modules/grading/grader-workers/worker-verdict.js');
+
+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}`); }
+}
+function eq(actual, expected, msg) {
+  if (actual !== expected) throw new Error(`${msg || 'mismatch'}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+}
+function truthy(v, msg) { if (!v) throw new Error(msg || `expected truthy, got ${JSON.stringify(v)}`); }
+function falsy(v, msg) { if (v) throw new Error(msg || `expected falsy, got ${JSON.stringify(v)}`); }
+
+// ---- the claim classifier: what it MUST catch ----------------------------
+
+test('the exact 1002648 wording is a dead-feature claim', () => {
+  truthy(deadFeatureClaim('TASK_SETTER_COLUMNS lacks needs_migration, so the feature is entirely non-operational'));
+});
+
+test('non-operational, with or without the hyphen', () => {
+  truthy(deadFeatureClaim('this path is nonoperational'));
+  truthy(deadFeatureClaim('this path is non-operational'));
+});
+
+test('always-throws and never-runs claims', () => {
+  truthy(deadFeatureClaim('the new helper always throws because the key is absent'));
+  truthy(deadFeatureClaim('this branch never executes'));
+  truthy(deadFeatureClaim('the handler can never run — nothing dispatches to it'));
+  truthy(deadFeatureClaim('the route throws at runtime on the first call'));
+});
+
+test('completely/entirely broken and dead on arrival', () => {
+  truthy(deadFeatureClaim('the migration is completely broken'));
+  truthy(deadFeatureClaim('this endpoint is dead on arrival'));
+});
+
+test('the claim is returned, not just a boolean, so the audit trail can quote it', () => {
+  eq(deadFeatureClaim('the feature is entirely non-operational'), 'non-operational');
+});
+
+// ---- the claim classifier: what it MUST NOT catch ------------------------
+
+test('a CONDITIONAL defect is not a dead-feature claim — the scores judge those', () => {
+  falsy(deadFeatureClaim('this would always throw if the id were null'));
+  falsy(deadFeatureClaim('if the cache is cold the loader never runs'));
+});
+
+test('praise for what the diff REMOVED is not a dead-feature claim', () => {
+  falsy(deadFeatureClaim('the old branch used to always throw; this fixes it'));
+  falsy(deadFeatureClaim('this path is no longer non-operational'));
+  falsy(deadFeatureClaim('previously the handler never executed'));
+  falsy(deadFeatureClaim('before this change the route was completely broken'));
+});
+
+test('"unreachable" is NOT matched — a reviewer writes it to praise a dead-code deletion', () => {
+  falsy(deadFeatureClaim('the old fallback is now unreachable and was deleted'));
+  falsy(deadFeatureClaim('this line is unreachable'));
+});
+
+test('empty and non-string input are safe', () => {
+  falsy(deadFeatureClaim(''));
+  falsy(deadFeatureClaim(null));
+  falsy(deadFeatureClaim(undefined));
+  falsy(deadFeatureClaim({ summary: 'always throws' }));
+});
+
+// ---- issueClaimsRuntimeDead reads the SUMMARY only -----------------------
+
+test('only the summary is read — a file path with an unlucky name never raises a severity', () => {
+  falsy(issueClaimsRuntimeDead({ severity: 'nit', file: 'tests/always-throws.test.js', summary: 'rename this' }));
+  truthy(issueClaimsRuntimeDead({ severity: 'nit', file: 'x.js', summary: 'the setter always throws' }));
+});
+
+test('a malformed issue entry is not a claim', () => {
+  falsy(issueClaimsRuntimeDead(null));
+  falsy(issueClaimsRuntimeDead('always throws'));
+});
+
+// ---- the floor -----------------------------------------------------------
+
+test('a nit that asserts the feature is dead is raised to major', () => {
+  const out = applyDeadFeatureFloor([{ severity: 'nit', file: 'db.js', summary: 'the feature is entirely non-operational' }]);
+  eq(out[0].severity, 'major');
+  eq(out[0].severity_reported, 'nit', 'what the worker actually said is preserved');
+  eq(out[0].severity_floor, 'runtime_dead');
+  eq(out[0].severity_floor_claim, 'non-operational');
+});
+
+test('minor is raised too; major and blocker are left exactly as reported', () => {
+  const out = applyDeadFeatureFloor([
+    { severity: 'minor', summary: 'always throws' },
+    { severity: 'major', summary: 'always throws' },
+    { severity: 'blocker', summary: 'always throws' },
+  ]);
+  eq(out[0].severity, 'major');
+  eq(out[0].severity_floor, 'runtime_dead');
+  eq(out[1].severity_floor, undefined, 'an already-major finding is not re-stamped');
+  eq(out[2].severity, 'blocker', 'a blocker is never lowered to major');
+});
+
+test('an UNKNOWN severity is raised — an unrecognised label must not buy an exemption', () => {
+  const out = applyDeadFeatureFloor([{ severity: 'trivial', summary: 'always throws' }]);
+  eq(out[0].severity, 'major');
+  eq(out[0].severity_reported, 'trivial');
+});
+
+test('findings with no dead-feature claim pass through untouched, same array', () => {
+  const input = [{ severity: 'nit', summary: 'comment style' }];
+  eq(applyDeadFeatureFloor(input), input, 'the input array itself is returned when nothing changed');
+});
+
+test('the floor does not mutate the caller\'s objects', () => {
+  const it = { severity: 'nit', summary: 'always throws' };
+  applyDeadFeatureFloor([it]);
+  eq(it.severity, 'nit', 'the original entry is untouched');
+});
+
+test('a non-array is returned as-is rather than throwing', () => {
+  eq(applyDeadFeatureFloor(null), null);
+  eq(applyDeadFeatureFloor(undefined), undefined);
+});
+
+// ---- the wiring: every worker parses through parseCommon -----------------
+//
+// parseCommon is the one place all four workers turn their own JSON into issues,
+// so the floor belongs there. Without this test the floor could be unwired from
+// parseCommon and every unit above would still pass.
+
+test('parseCommon applies the floor, so all four workers get it', () => {
+  const { issues } = parseCommon({ issues: [{ severity: 'nit', file: 'db.js', summary: 'the feature is entirely non-operational' }] });
+  eq(issues[0].severity, 'major');
+  eq(issues[0].severity_floor, 'runtime_dead');
+});
+
+test('parseCommon still bounds and filters issues[] exactly as before', () => {
+  const { issues } = parseCommon({ issues: [null, 'junk', { severity: 'nit', summary: 'fine' }] });
+  eq(issues.length, 1, 'non-object entries are dropped');
+  eq(parseCommon({ issues: Array.from({ length: 80 }, () => ({ severity: 'nit', summary: 'x' })) }).issues.length, 50,
+    'the 50-entry bound is unchanged');
+  eq(parseCommon({ issues: 'not an array' }).issues.length, 0);
+});
+
+test('the raised severity reaches the worker\'s own severity gate: a dead-feature fail is no longer downgraded', () => {
+  const { issues } = parseCommon({ issues: [{ severity: 'nit', file: 'db.js', summary: 'the new setter always throws' }] });
+  const result = applySeverityGatePolicy(
+    { verdict: 'fail', scores: { code_quality: 4 }, issues, notes_md: '' },
+    { threshold: 6 }
+  );
+  eq(result.verdict, 'fail', 'a fail backed by a floor-raised finding stays a fail');
+  eq(result.policy_downgrade, undefined);
+});
+
+console.log('');
+console.log(`dead_feature_claim: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);