@bongos/core 1.20.5 → 1.20.6

package/tests/criterion_uat.mjs

@@ -0,0 +1,467 @@
+// tests/criterion_uat.mjs — task 1004392 / ADR 0351: a criterion closes on a UAT.
+//
+// What these protect, in order of how badly it would hurt:
+//
+//  1. THE CLOSE NEEDS A CURRENT SIGN-OFF. autoSatisfyShippedCriteria (the ship
+//     hook and the reconciler sweep) must not close a criterion on shipped tasks
+//     alone any more, and a sign-off OLDER than the newest linked ship must not
+//     count. Losing either reopens the exact hole wa7-government fell through.
+//  2. THE SIGNER WALL. Whoever shipped linked work is refused; the project owner
+//     is the one exception (a solo project must not deadlock). Asserted in the
+//     pure ladder AND through the real signOff transaction, so a refusal that
+//     exists in the ladder but is never consulted cannot pass.
+//  3. THE STATES people read ("Awaiting UAT", "Closed before UAT"), and that an
+//     all-abandoned criterion is NOT awaiting a UAT (nothing was delivered).
+//  4. THE RECORDING STORE: type + magic bytes + cap, and a name shape that equals
+//     the migration's CHECK.
+//
+// DB-free: fake executors script the rows and record the SQL. The real-SQL
+// semantics are the integration lane's; the shapes and the branching are here.
+//
+// Run:  node tests/criterion_uat.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync, mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { makeRunner } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const uat = require('../modules/lifecycle/criterion-uat.js');
+const uatDb = require('../modules/lifecycle/criterion-uat-db.js');
+const doneWhen = require('../modules/lifecycle/done-when.js');
+const { test, summary } = makeRunner();
+
+const S = uat.UAT_STATES;
+
+// ---- 1. the states ----------------------------------------------------------
+
+await test('STATE: shipped work with no sign-off reads Awaiting UAT', () => {
+  assert.equal(uat.uatState({ satisfied: false, linked: 3, unshipped: 0, shipped: 2 }), S.AWAITING_UAT);
+});
+
+await test('STATE: open linked work, or none linked, reads Open', () => {
+  assert.equal(uat.uatState({ satisfied: false, linked: 3, unshipped: 1, shipped: 2 }), S.OPEN);
+  assert.equal(uat.uatState({ satisfied: false, linked: 0, unshipped: 0, shipped: 0 }), S.OPEN);
+});
+
+await test('STATE: ALL-ABANDONED is not awaiting a UAT — nothing was delivered to test', () => {
+  // ADR 0183's delivery guard, kept as the Code check. /goal-review owns this row.
+  assert.equal(uat.uatState({ satisfied: false, linked: 2, unshipped: 0, shipped: 0 }), S.OPEN);
+  assert.equal(uat.codeMet({ linked: 2, unshipped: 0, shipped: 0 }), false);
+});
+
+await test('STATE: a satisfied criterion reads by the kind of its newest sign-off', () => {
+  const sat = { satisfied: true, linked: 1, unshipped: 0, shipped: 1 };
+  assert.equal(uat.uatState({ ...sat, latestKind: 'uat' }), S.SATISFIED_UAT);
+  assert.equal(uat.uatState({ ...sat, latestKind: 'backend_signoff' }), S.SATISFIED_BACKEND);
+  assert.equal(uat.uatState({ ...sat, latestKind: 'override' }), S.SATISFIED_OVERRIDE);
+  // The owner's decision 1: already-closed criteria stay closed and say so.
+  assert.equal(uat.uatState({ ...sat, latestKind: null }), S.CLOSED_BEFORE_UAT);
+  assert.equal(uat.stateLabel(S.CLOSED_BEFORE_UAT), 'Closed before UAT');
+  assert.equal(uat.stateLabel(S.AWAITING_UAT), 'Awaiting UAT');
+});
+
+await test('STATE: /status rollup carries uat_state + awaiting_uat + backend_only', () => {
+  const rows = [
+    { cnum: 1, id: 1, criterion_id: 'a', criterion_md: 'A', satisfied: false, goal_id: null, uat_kind: null, backend_only: false, task_id: 11, task_title: 't', task_status: 'shipped' },
+    { cnum: 2, id: 2, criterion_id: 'b', criterion_md: 'B', satisfied: true, goal_id: null, uat_kind: null, backend_only: true, task_id: 12, task_title: 't', task_status: 'shipped' },
+    { cnum: 3, id: 3, criterion_id: 'c', criterion_md: 'C', satisfied: false, goal_id: null, uat_kind: null, backend_only: false, task_id: 13, task_title: 't', task_status: 'abandoned' },
+  ];
+  const out = doneWhen.buildCriterionProgress('V', rows);
+  const [a, b, c] = out.criteria;
+  assert.equal(a.uat_state, S.AWAITING_UAT);
+  assert.equal(a.awaiting_uat, true);
+  assert.equal(b.uat_state, S.CLOSED_BEFORE_UAT);
+  assert.equal(b.backend_only, true);
+  // The asymmetry survives: all-abandoned is flagged for a person, not for a UAT.
+  assert.equal(c.pending_review, true);
+  assert.equal(c.awaiting_uat, false);
+  assert.ok(!('uat_kind' in a), 'the raw sign-off kind is folded into uat_state, not leaked beside it');
+});
+
+// ---- 2. the Live fold ------------------------------------------------------
+
+await test('LIVE: no reading, or a partial one, is unavailable (the signer attests)', () => {
+  assert.deepEqual(uat.foldLiveReadings(null), { available: false });
+  assert.deepEqual(uat.foldLiveReadings([{ task_id: '1', stage: 'released', partial: true }]), { available: false });
+});
+
+await test('LIVE: every task in a live stage is live; any other stage names the task', () => {
+  assert.deepEqual(uat.foldLiveReadings([{ task_id: '1', stage: 'released' }, { task_id: '2', stage: 'live_unreleased' }]), { available: true, live: true });
+  const r = uat.foldLiveReadings([{ task_id: '1', stage: 'released' }, { task_id: '2', stage: 'not_live' }]);
+  assert.equal(r.live, false);
+  assert.deepEqual(r.not_live, [{ task_id: '2', stage: 'not_live' }]);
+});
+
+// ---- 3. the sign-off ladder (pure) -----------------------------------------
+
+const MET = { linked: 2, unshipped: 0, shipped: 2 };
+const base = {
+  criterion: { satisfied: false }, counts: MET, backendOnly: false, kind: 'uat',
+  signerId: 50, ownerId: 3, shipperIds: ['7', '8'], recording: 'uat-1-0123456789abcdef.mp4',
+  live: { available: true, live: true },
+};
+const code = (over) => { const r = uat.signoffRefusal({ ...base, ...over }); return r && r.code; };
+
+await test('LADDER: a non-shipper with a recording on live work is allowed', () => {
+  assert.equal(uat.signoffRefusal(base), null);
+});
+
+await test('LADDER: whoever shipped linked work is refused — ids compare as strings', () => {
+  assert.equal(code({ signerId: 7 }), 'signer_shipped_this_work');
+  assert.equal(code({ signerId: '8' }), 'signer_shipped_this_work');
+});
+
+await test('LADDER: the project owner may sign off work they shipped (solo projects)', () => {
+  assert.equal(code({ signerId: 3, shipperIds: ['3'] }), null);
+});
+
+await test('LADDER: nothing to sign — closed, open work, or nothing delivered', () => {
+  assert.equal(code({ criterion: { satisfied: true } }), 'criterion_already_satisfied');
+  assert.equal(code({ counts: { linked: 2, unshipped: 1, shipped: 1 } }), 'criterion_not_awaiting_uat');
+  assert.equal(code({ counts: { linked: 2, unshipped: 0, shipped: 0 } }), 'criterion_not_awaiting_uat');
+  assert.equal(code({ criterion: null }), 'criterion_not_found');
+});
+
+await test('LADDER: the kind must match the criterion', () => {
+  assert.equal(code({ backendOnly: true }), 'criterion_is_backend_only');
+  assert.equal(code({ kind: 'backend_signoff', recording: null }), 'criterion_needs_recording');
+  assert.equal(code({ kind: 'backend_signoff', recording: null, backendOnly: true }), null);
+});
+
+await test('LADDER: a UAT needs its recording', () => {
+  assert.equal(code({ recording: null }), 'uat_recording_required');
+});
+
+await test('LADDER: not live is refused where readable; attestation is required where not', () => {
+  assert.equal(code({ live: { available: true, live: false, not_live: [] } }), 'work_not_live');
+  assert.equal(code({ live: { available: false } }), 'live_attestation_required');
+  assert.equal(code({ live: { available: false }, liveAttested: true }), null);
+  assert.equal(uat.liveBasis({ available: true, live: true }), 'deploy_reading');
+  assert.equal(uat.liveBasis({ available: false }), 'attested');
+});
+
+await test('LADDER: the shipper refusal outranks missing evidence (they are told the real reason)', () => {
+  assert.equal(code({ signerId: 7, recording: null, live: { available: false } }), 'signer_shipped_this_work');
+});
+
+// ---- 4. the close path ------------------------------------------------------
+
+function fakeExec(...results) {
+  const calls = [];
+  return { calls, async query(sql, params) { calls.push({ sql, params }); return results[calls.length - 1] || { rows: [] }; } };
+}
+
+await test('CLOSE (sql): the auto-close requires a CURRENT uat/backend sign-off row', async () => {
+  const exec = fakeExec({ rows: [] });
+  await doneWhen.autoSatisfyShippedCriteria(exec, {});
+  const sql = exec.calls[0].sql;
+  assert.match(sql, /EXISTS \(SELECT 1 FROM lifecycle_criterion_uats u/, 'a sign-off row must exist');
+  assert.match(sql, /u\.kind IN \('uat', 'backend_signoff'\)/, 'an override row is not a candidate — the override route satisfies directly');
+  assert.match(sql, /u\.created_at >= COALESCE\(candidate\.last_ship/, 'a sign-off older than the newest linked ship is stale');
+  assert.match(sql, /max\(t\.shipped_at\) FILTER \(WHERE t\.status = 'shipped'\) AS last_ship/);
+  // The delivery guard (ADR 0183) is still there.
+  assert.match(sql, /count\(\*\) FILTER \(WHERE t\.status = 'shipped'\) >= 1/);
+});
+
+await test('CLOSE: the criterionId scope binds $2 and leaves the task scope null', async () => {
+  const exec = fakeExec({ rows: [] });
+  await doneWhen.autoSatisfyShippedCriteria(exec, { criterionId: 42 });
+  assert.deepEqual(exec.calls[0].params, [null, 42]);
+  assert.match(exec.calls[0].sql, /\$2::bigint IS NULL OR c\.id = \$2::bigint/);
+  const shipScoped = fakeExec({ rows: [] });
+  await doneWhen.autoSatisfyShippedCriteria(shipScoped, { taskId: 9 });
+  assert.deepEqual(shipScoped.calls[0].params, [9, null], 'the ship hook still scopes by task');
+  await assert.rejects(() => doneWhen.autoSatisfyShippedCriteria(fakeExec(), { criterionId: 'x' }), /criterionId must be numeric/);
+});
+
+// ---- 5. signOff, through its real transaction ------------------------------
+
+// A SQL-routed fake: the same object is the pool and the transaction client.
+function signoffDb({ linked, linkedAfter = null, satisfied = false, backendOnly = false, closes = true }) {
+  const calls = [];
+  let linkedReads = 0;
+  const db = {
+    calls,
+    async query(sql, params) {
+      calls.push({ sql, params });
+      if (/FROM task_criteria tc/.test(sql) && /shipped_by/.test(sql)) {
+        linkedReads += 1;
+        return { rows: linkedReads > 1 && linkedAfter ? linkedAfter : linked };
+      }
+      if (/FROM done_when_criteria WHERE id = \$1 FOR UPDATE/.test(sql)) return { rows: [{ id: params[0], satisfied, goal_id: null, version_id: 'V' }] };
+      if (/lifecycle_criterion_backend_only/.test(sql)) return { rows: backendOnly ? [{ '?column?': 1 }] : [] };
+      if (/INSERT INTO lifecycle_criterion_uats/.test(sql)) return { rows: [{ id: 1, kind: params[1], live_basis: params[4] }] };
+      if (/WITH candidate AS/.test(sql)) return { rows: closes ? [{ id: params[1], goal_id: null }] : [] };
+      return { rows: [] };
+    },
+  };
+  return db;
+}
+const withTx = (db) => async (fn) => fn(db);
+const SHIPPED = [
+  { id: 11, status: 'shipped', shipped_by: 7, shipped_at: new Date() },
+  { id: 12, status: 'shipped', shipped_by: 8, shipped_at: new Date() },
+];
+const REC = 'uat-5-0123456789abcdef.webm';
+const inserts = (db) => db.calls.filter((c) => /INSERT INTO lifecycle_criterion_uats/.test(c.sql));
+
+await test('SIGNOFF: a non-shipper signs, the row is written, and the criterion closes in the same tx', async () => {
+  const db = signoffDb({ linked: SHIPPED });
+  const out = await uatDb.signOff(
+    { criterionId: 5, kind: 'uat', signerId: 50, recording: REC, liveAttested: true, note: '  checked the page  ' },
+    { pool: db, withTx: withTx(db), deployPort: null, ownerId: 3 },
+  );
+  assert.equal(out.ok, true, JSON.stringify(out.refusal));
+  const ins = inserts(db);
+  assert.equal(ins.length, 1);
+  assert.deepEqual(ins[0].params, [5, 'uat', 50, REC, 'attested', 'checked the page']);
+  const close = db.calls.find((c) => /WITH candidate AS/.test(c.sql));
+  assert.ok(close, 'the sign-off must run the close');
+  assert.deepEqual(close.params, [null, 5], 'scoped to THIS criterion');
+  assert.ok(db.calls.indexOf(close) > db.calls.indexOf(ins[0]), 'the close runs after the row it depends on');
+  assert.equal(out.closed.criteria.length, 1);
+});
+
+await test('SIGNOFF: a shipper is refused and NOTHING is written', async () => {
+  const db = signoffDb({ linked: SHIPPED });
+  const out = await uatDb.signOff(
+    { criterionId: 5, kind: 'uat', signerId: 7, recording: REC, liveAttested: true },
+    { pool: db, withTx: withTx(db), deployPort: null, ownerId: 3 },
+  );
+  assert.equal(out.ok, false);
+  assert.equal(out.refusal.code, 'signer_shipped_this_work');
+  assert.equal(inserts(db).length, 0);
+  assert.ok(!db.calls.some((c) => /WITH candidate AS/.test(c.sql)), 'a refusal never runs the close');
+});
+
+await test('SIGNOFF: the project owner may sign off their own shipped work', async () => {
+  const db = signoffDb({ linked: [{ id: 11, status: 'shipped', shipped_by: 3, shipped_at: new Date() }] });
+  const out = await uatDb.signOff(
+    { criterionId: 5, kind: 'uat', signerId: 3, recording: REC, liveAttested: true },
+    { pool: db, withTx: withTx(db), deployPort: null, ownerId: 3 },
+  );
+  assert.equal(out.ok, true, JSON.stringify(out.refusal));
+});
+
+await test('SIGNOFF: the deploy reading refuses work that is not live, and names it', async () => {
+  const db = signoffDb({ linked: SHIPPED });
+  const deployPort = { readTaskWhere: async (id) => ({ stage: id === '12' ? 'not_live' : 'released', partial: false }) };
+  const out = await uatDb.signOff(
+    { criterionId: 5, kind: 'uat', signerId: 50, recording: REC },
+    { pool: db, withTx: withTx(db), deployPort, ownerId: 3 },
+  );
+  assert.equal(out.refusal.code, 'work_not_live');
+  assert.deepEqual(out.refusal.not_live, [{ task_id: '12', stage: 'not_live' }]);
+});
+
+await test('SIGNOFF: a live reading is recorded as deploy_reading, and a THROWING reader falls back to attestation', async () => {
+  const live = signoffDb({ linked: SHIPPED });
+  const ok = await uatDb.signOff(
+    { criterionId: 5, kind: 'uat', signerId: 50, recording: REC },
+    { pool: live, withTx: withTx(live), deployPort: { readTaskWhere: async () => ({ stage: 'released' }) }, ownerId: 3 },
+  );
+  assert.equal(ok.ok, true);
+  assert.equal(inserts(live)[0].params[4], 'deploy_reading');
+  const broken = signoffDb({ linked: SHIPPED });
+  const out = await uatDb.signOff(
+    { criterionId: 5, kind: 'uat', signerId: 50, recording: REC },
+    { pool: broken, withTx: withTx(broken), deployPort: { readTaskWhere: async () => { throw new Error('registry down'); } }, ownerId: 3 },
+  );
+  assert.equal(out.refusal.code, 'live_attestation_required', 'an outage moves Live to the signer, never blocks them outright');
+});
+
+await test('SIGNOFF: linked work that changed between the reading and the lock is refused', async () => {
+  const db = signoffDb({ linked: SHIPPED, linkedAfter: [...SHIPPED, { id: 13, status: 'shipped', shipped_by: 9, shipped_at: new Date() }] });
+  const out = await uatDb.signOff(
+    { criterionId: 5, kind: 'uat', signerId: 50, recording: REC, liveAttested: true },
+    { pool: db, withTx: withTx(db), deployPort: null, ownerId: 3 },
+  );
+  assert.equal(out.refusal.code, 'linked_work_changed');
+  assert.equal(inserts(db).length, 0);
+});
+
+await test('SIGNOFF: a recording uploaded for another criterion is refused before any read', async () => {
+  const db = signoffDb({ linked: SHIPPED });
+  const out = await uatDb.signOff(
+    { criterionId: 6, kind: 'uat', signerId: 50, recording: REC, liveAttested: true },
+    { pool: db, withTx: withTx(db), deployPort: null, ownerId: 3 },
+  );
+  assert.equal(out.refusal.code, 'recording_not_for_this_criterion');
+  assert.equal(db.calls.length, 0);
+});
+
+await test('SIGNOFF: an override cannot be submitted through the sign-off path', async () => {
+  const out = await uatDb.signOff({ criterionId: 5, kind: 'override', signerId: 50 }, {});
+  assert.equal(out.refusal.code, 'bad_kind');
+});
+
+// ---- 6. the recording store -------------------------------------------------
+
+const mp4 = (n = 64) => { const b = Buffer.alloc(n); b.write('ftyp', 4, 'latin1'); return b; };
+const webm = (n = 64) => { const b = Buffer.alloc(n); b[0] = 0x1a; b[1] = 0x45; b[2] = 0xdf; b[3] = 0xa3; return b; };
+
+await test('STORE: mp4 and webm pass; a mislabelled or foreign file does not', () => {
+  assert.equal(uat.screenRecording(mp4(), 'video/mp4').ok, true);
+  assert.equal(uat.screenRecording(webm(), 'video/webm; codecs=vp9').ok, true);
+  assert.equal(uat.screenRecording(webm(), 'video/mp4').reason, 'sniff_mismatch');
+  assert.equal(uat.screenRecording(mp4(), 'image/png').reason, 'bad_type');
+  assert.equal(uat.screenRecording(Buffer.alloc(0), 'video/mp4').reason, 'empty');
+});
+
+await test('STORE: the 100 MB cap is exact', () => {
+  assert.equal(uat.MAX_RECORDING_BYTES, 100 * 1024 * 1024);
+  assert.equal(uat.screenRecording(mp4(uat.MAX_RECORDING_BYTES), 'video/mp4').ok, true);
+  assert.equal(uat.screenRecording(mp4(uat.MAX_RECORDING_BYTES + 1), 'video/mp4').reason, 'too_big');
+});
+
+await test('STORE: a stored name is server-minted, carries its criterion, and resolves only inside the dir', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'uat-store-'));
+  try {
+    const r = await uat.persistRecording(mp4(), { criterionId: 77, contentType: 'video/mp4', dir });
+    assert.equal(r.ok, true);
+    assert.match(r.file, /^uat-77-[0-9a-f]{16}\.mp4$/);
+    assert.equal(uat.criterionIdFromName(r.file), 77);
+    assert.ok(existsSync(uat.resolveSafe(r.file, { dir })));
+    for (const bad of ['../uat-1-0123456789abcdef.mp4', 'uat-1-0123456789abcdef.mp4/..', 'uat-1-xyz.mp4', 'task-1-0123456789abcdef.png']) {
+      assert.equal(uat.resolveSafe(bad, { dir }), null, bad);
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+await test('STORE: the app and the migration CHECK accept and refuse the same names', () => {
+  const sql = readFileSync(new URL('../modules/lifecycle/migrations/lifecycle_015_criterion_uat.sql', import.meta.url), 'utf8');
+  // This pattern uses only syntax POSIX and JS regexes read identically.
+  const check = new RegExp(/recording_file ~ '([^']+)'/.exec(sql)[1]);
+  const names = [
+    'uat-1-0123456789abcdef.mp4', 'uat-123456789012-fedcba9876543210.webm',
+    'uat-1234567890123-0123456789abcdef.mp4', 'uat-1-0123456789ABCDEF.mp4', 'uat-1-0123456789abcdef.mov',
+    'uat--0123456789abcdef.mp4', 'uat-1-0123456789abcde.mp4', 'x/uat-1-0123456789abcdef.mp4', 'uat-1-0123456789abcdef.mp4x',
+  ];
+  for (const n of names) assert.equal(uat.isSafeName(n), check.test(n), `app and DB disagree on ${n}`);
+  assert.ok(names.some((n) => uat.isSafeName(n)) && names.some((n) => !uat.isSafeName(n)), 'the probe set must hold both answers');
+});
+
+// ---- 7. the read behind GET /done-when/:id/uat ------------------------------
+
+// A SQL-routed fake for uatView: the criterion row, its linked tasks, its
+// sign-offs (newest first, as listSignoffs orders them), and the backend flag.
+function viewDb({ satisfied = false, linked, signoffs = [], backendOnly = false }) {
+  return {
+    async query(sql) {
+      if (/FROM done_when_criteria WHERE id = \$1/.test(sql)) return { rows: [{ id: 5, criterion_id: 'c', criterion_md: 'md', satisfied, goal_id: 3, version_id: 'V' }] };
+      if (/FROM task_criteria tc/.test(sql)) return { rows: linked };
+      if (/FROM lifecycle_criterion_uats u/.test(sql)) return { rows: signoffs };
+      if (/lifecycle_criterion_backend_only/.test(sql)) return { rows: backendOnly ? [{ x: 1 }] : [] };
+      throw new Error(`unexpected SQL: ${sql}`);
+    },
+  };
+}
+const T0 = new Date('2026-09-20T10:00:00Z');
+const T1 = new Date('2026-09-25T10:00:00Z');
+
+await test('VIEW: a sign-off older than the newest linked ship is reported STALE, never as the UAT check', async () => {
+  const linked = [{ id: 11, status: 'shipped', shipped_by: 7, shipped_at: T0 }, { id: 12, status: 'shipped', shipped_by: 8, shipped_at: T1 }];
+  const stale = { id: 1, kind: 'uat', signed_off_by: 50, created_at: new Date('2026-09-22T10:00:00Z') };
+  const v = await uatDb.uatView(5, { pool: viewDb({ linked, signoffs: [stale] }), deployPort: null });
+  assert.equal(v.uat_state, S.AWAITING_UAT);
+  assert.equal(v.checks.code, true);
+  assert.equal(v.checks.uat, null, 'work shipped after the sign-off, so it does not count');
+  assert.equal(v.checks.stale_uat.id, 1, 'and the reader is told why');
+  assert.deepEqual(v.checks.live, { available: false }, 'no deploy reading here: the signer will attest');
+});
+
+await test('VIEW: a current sign-off is the UAT check, and an override row never is', async () => {
+  const linked = [{ id: 11, status: 'shipped', shipped_by: 7, shipped_at: T0 }];
+  const override = { id: 3, kind: 'override', created_at: T1 };
+  const current = { id: 2, kind: 'backend_signoff', created_at: T1 };
+  const v = await uatDb.uatView(5, { pool: viewDb({ satisfied: true, linked, signoffs: [override, current], backendOnly: true }) });
+  assert.equal(v.checks.uat.id, 2);
+  assert.equal(v.checks.stale_uat, null);
+  assert.equal(v.backend_only, true);
+  assert.equal(v.uat_state, S.SATISFIED_OVERRIDE, 'the state reads by the NEWEST row, which is the override');
+  assert.equal(v.checks.live, null, 'Live is only read while a criterion is awaiting UAT');
+});
+
+await test('VIEW: Live is read from the deploy port while awaiting, and an unknown criterion is null', async () => {
+  const linked = [{ id: 11, status: 'shipped', shipped_by: 7, shipped_at: T0 }];
+  const port = { readTasksWhere: async (ids) => Object.fromEntries(ids.map((id) => [id, { stage: 'released' }])) };
+  const v = await uatDb.uatView(5, { pool: viewDb({ linked }), deployPort: port });
+  assert.deepEqual(v.checks.live, { available: true, live: true });
+  const none = { async query() { return { rows: [] }; } };
+  assert.equal(await uatDb.uatView(6, { pool: none }), null);
+});
+
+// ---- 8. readLive: one batch read, and every failure is a PARTIAL -------------
+
+await test('LIVE READ: the batch port is asked ONCE for every task, and a missing task is partial', async () => {
+  const calls = [];
+  const port = {
+    readTasksWhere: async (ids) => { calls.push(ids); return { 11: { stage: 'released' } }; },
+    readTaskWhere: async () => { throw new Error('the per-task form must not be used when the batch exists'); },
+  };
+  const r = await uatDb.readLive(['11', '12'], { deployPort: port });
+  assert.equal(calls.length, 1);
+  assert.deepEqual(r, [{ task_id: '11', stage: 'released', partial: false }, { task_id: '12', stage: null, partial: true }]);
+  const thrown = await uatDb.readLive(['11'], { deployPort: { readTasksWhere: async () => { throw new Error('down'); } } });
+  assert.deepEqual(thrown, [{ task_id: '11', stage: null, partial: true }]);
+  assert.equal(await uatDb.readLive(['11'], { deployPort: null }), null, 'no provider, no reading');
+});
+
+// ---- 9. backend-only: set while OPEN, never once the criterion is awaiting ---
+
+function flagDb({ satisfied = false, linked }) {
+  const calls = [];
+  return {
+    calls,
+    async query(sql, params) {
+      calls.push({ sql, params });
+      if (/FROM done_when_criteria WHERE id = \$1 FOR UPDATE/.test(sql)) return { rows: [{ id: params[0], satisfied, goal_id: 3, version_id: 'V' }] };
+      if (/FROM task_criteria tc/.test(sql)) return { rows: linked };
+      return { rows: [] };
+    },
+  };
+}
+const flagWrites = (db) => db.calls.filter((c) => /lifecycle_criterion_backend_only/.test(c.sql));
+const allow = async () => null;
+
+await test('BACKEND-ONLY: an open criterion can be marked and unmarked', async () => {
+  const open = [{ id: 11, status: 'active', shipped_by: null, shipped_at: null }];
+  const on = flagDb({ linked: open });
+  const r = await uatDb.setBackendOnly({ criterionId: 5, builderId: 50, backendOnly: true, authorize: allow }, { pool: on, withTx: withTx(on) });
+  assert.deepEqual(r, { ok: true, backend_only: true });
+  assert.match(flagWrites(on)[0].sql, /INSERT INTO lifecycle_criterion_backend_only/);
+  assert.deepEqual(flagWrites(on)[0].params, [5, 50]);
+  const off = flagDb({ linked: open });
+  await uatDb.setBackendOnly({ criterionId: 5, builderId: 50, backendOnly: false, authorize: allow }, { pool: off, withTx: withTx(off) });
+  assert.match(flagWrites(off)[0].sql, /DELETE FROM lifecycle_criterion_backend_only/);
+});
+
+await test('BACKEND-ONLY: LOCKED once the criterion is awaiting UAT or closed — the closer cannot skip the recording', async () => {
+  const shipped = [{ id: 11, status: 'shipped', shipped_by: 7, shipped_at: T0 }];
+  for (const [label, db] of [['awaiting', flagDb({ linked: shipped })], ['closed', flagDb({ satisfied: true, linked: shipped })]]) {
+    const r = await uatDb.setBackendOnly({ criterionId: 5, builderId: 50, backendOnly: true, authorize: allow }, { pool: db, withTx: withTx(db) });
+    assert.equal(r.refusal.code, 'backend_only_locked', label);
+    assert.equal(flagWrites(db).length, 0, `${label}: nothing written`);
+  }
+});
+
+await test('BACKEND-ONLY: the authority gate runs INSIDE the transaction, before any read of the work, and a refusal writes nothing', async () => {
+  const db = flagDb({ linked: [] });
+  const seen = [];
+  const r = await uatDb.setBackendOnly({
+    criterionId: 5, builderId: 50, backendOnly: true,
+    authorize: async (client, crit) => { seen.push([client === db, crit.goal_id]); return { code: 'goal_not_yours', status: 403, message: 'no' }; },
+  }, { pool: db, withTx: withTx(db) });
+  assert.equal(r.refusal.code, 'goal_not_yours');
+  assert.deepEqual(seen, [[true, 3]], 'the gate saw the locked row on the transaction client');
+  assert.equal(flagWrites(db).length, 0);
+  assert.ok(!db.calls.some((c) => /FROM task_criteria/.test(c.sql)), 'a refused caller learns nothing about the linked work');
+});
+
+summary();