@bongos/core 1.20.5 → 1.20.7

package/scripts/gds/uat.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// scripts/gds/uat.js — see, and sign off, a criterion's UAT from a session
+// (task 1004392, goal 1000089; ADR 0351). The CLI half of /goal-uat.
+//
+// WHY. A criterion no longer closes because its linked tasks shipped. It reads
+// "Awaiting UAT" until someone who did not ship the work performs it on the live
+// site and signs it off with a recording (or, for a criterion marked
+// backend-only, a recording-free sign-off). This is how a session does that
+// before the hall has buttons for it (task 1004402), and what /goal-uat drives.
+//
+// Usage:
+//   node scripts/gds/uat.js --queue [--version V]            every criterion awaiting UAT
+//   node scripts/gds/uat.js <criterion-id>                    its three checks + sign-offs
+//   node scripts/gds/uat.js <criterion-id> --recording <file.mp4|.webm> [--live-attested] [--note "..."]
+//   node scripts/gds/uat.js <criterion-id> --backend-signoff [--live-attested] [--note "..."]
+//   node scripts/gds/uat.js <criterion-id> --backend-only on|off
+//
+// <criterion-id> is the criterion's numeric id (the `id` /status and the queue
+// print), not its slug. --live-attested is only needed where this site cannot
+// tell on its own whether the work is live; the server says so when it is.
+
+const { apiCall, arg, argText, hasFlag, cliExit } = require('./cli-lib');
+const uat = require('../../modules/lifecycle/criterion-uat');
+
+const API = '/api/bongos';
+
+function refusalText(data) {
+  const e = data && data.error;
+  if (!e) return 'the server refused it.';
+  const msg = typeof e === 'string' ? e : (e.message || e.code);
+  const extra = [];
+  const details = (typeof e === 'object' && e.details) || data;
+  if (details && Array.isArray(details.remaining) && details.remaining.length) {
+    extra.push(`still open: ${details.remaining.map((t) => `task ${t.id} (${t.status})`).join(', ')}`);
+  }
+  if (details && Array.isArray(details.not_live) && details.not_live.length) {
+    extra.push(`not live yet: ${details.not_live.map((t) => `task ${t.task_id}${t.stage ? ` (${t.stage})` : ''}`).join(', ')}`);
+  }
+  return [msg, ...extra].join('\n  ');
+}
+
+async function showQueue() {
+  const version = arg('--version');
+  const q = version ? `?version=${encodeURIComponent(version)}` : '';
+  const r = await apiCall('GET', `${API}/done-when/pending-review${q}`);
+  if (!r.ok) { console.error(`Could not read the queue: ${refusalText(r.data)}`); return 1; }
+  const rows = (r.data.criteria || []).filter((c) => c.awaiting_uat);
+  if (!rows.length) { console.log('Nothing is awaiting UAT.'); return 0; }
+  console.log(`${rows.length} criteri${rows.length === 1 ? 'on' : 'a'} awaiting UAT:\n`);
+  for (const c of rows) {
+    const tag = c.backend_only ? '  [backend-only]' : '';
+    console.log(`  criterion ${c.id}  ${c.criterion_id}${tag}`);
+    console.log(`    goal ${c.goal_id ?? '-'}${c.goal_title ? ` "${c.goal_title}"` : ''}${c.is_last_in_goal ? '  (last open criterion: signing it off can achieve the goal)' : ''}`);
+  }
+  return 0;
+}
+
+async function showOne(id) {
+  const r = await apiCall('GET', `${API}/done-when/${id}/uat`);
+  if (!r.ok) { console.error(`Could not read criterion ${id}: ${refusalText(r.data)}`); return 1; }
+  const v = r.data;
+  console.log(`criterion ${v.criterion.id}  ${v.criterion.criterion_id}  — ${v.uat_label}${v.backend_only ? '  [backend-only]' : ''}\n`);
+  console.log(String(v.criterion.criterion_md || '').trim());
+  console.log('');
+  console.log(`  Code  ${v.checks.code ? 'passed' : 'not yet'}  (${v.linked_tasks.length} linked: ${v.linked_tasks.map((t) => `${t.id} ${t.status}`).join(', ') || 'none'})`);
+  const live = v.checks.live;
+  console.log(`  Live  ${live == null ? '-' : !live.available ? 'this site cannot tell; the signer confirms it' : live.live ? 'running on the site' : `not yet: ${(live.not_live || []).map((t) => t.task_id).join(', ')}`}`);
+  const s = v.checks.uat;
+  console.log(`  UAT   ${s ? `${s.kind === 'uat' ? 'recorded' : 'backend sign-off'} by ${s.signed_off_by_login || s.signed_off_by} on ${String(s.created_at).slice(0, 10)}` : 'not yet'}`);
+  return 0;
+}
+
+async function signOff(id, kind) {
+  let recording = null;
+  if (kind === 'uat') {
+    const file = arg('--recording');
+    const read = uat.readRecordingFile(file);
+    if (!read.ok) { console.error(`Recording refused: ${read.message}`); return 1; }
+    const up = await apiCall('POST', `${API}/done-when/${id}/uat/recording`, null, { rawBody: read.buf, contentType: read.contentType });
+    if (!up.ok) { console.error(`Upload refused: ${refusalText(up.data)}`); return 1; }
+    recording = up.data.recording;
+    console.log(`Uploaded the recording (${Math.round(up.data.bytes / 1024 / 1024 * 10) / 10} MB).`);
+  }
+  const body = { kind };
+  if (recording) body.recording = recording;
+  if (hasFlag('--live-attested')) body.live_attested = true;
+  const note = argText('--note');
+  if (note) body.note = note;
+  const r = await apiCall('POST', `${API}/done-when/${id}/uat`, body);
+  if (!r.ok) { console.error(`Sign-off refused: ${refusalText(r.data)}`); return 1; }
+  console.log(r.data.criterion_closed ? `Signed off. Criterion ${id} is now closed.` : `Signed off, but criterion ${id} did not close yet.`);
+  for (const g of r.data.achieved_goals || []) console.log(`  That was the goal's last criterion: goal ${g} is achieved.`);
+  return 0;
+}
+
+async function setBackendOnly(id, value) {
+  if (value !== 'on' && value !== 'off') { console.error('--backend-only takes on or off.'); return 1; }
+  const r = await apiCall('PUT', `${API}/done-when/${id}/backend-only`, { backend_only: value === 'on' });
+  if (!r.ok) { console.error(`Refused: ${refusalText(r.data)}`); return 1; }
+  console.log(`Criterion ${id} is ${r.data.backend_only ? 'now marked backend-only' : 'no longer backend-only'}.`);
+  return 0;
+}
+
+async function main() {
+  if (hasFlag('--queue')) return showQueue();
+  const id = process.argv[2];
+  if (!id || !/^\d{1,12}$/.test(id)) {
+    console.error('usage: node scripts/gds/uat.js <criterion-id> [--recording f | --backend-signoff | --backend-only on|off]  |  --queue');
+    return 2;
+  }
+  if (arg('--backend-only')) return setBackendOnly(id, arg('--backend-only'));
+  if (hasFlag('--backend-signoff')) return signOff(id, 'backend_signoff');
+  if (arg('--recording')) return signOff(id, 'uat');
+  return showOne(id);
+}
+
+main().then((code) => cliExit(code), (err) => {
+  console.error(`uat: ${err && err.message}`);
+  cliExit(1);
+});

package/src/bongos/route-rank-check.js

@@ -425,6 +425,15 @@ const MODULE_EXPECTED_RANKS = {
     // — but it is scope disposition, not an authority grant, so it delegates with the
     // rest. Pinned by atom so the guarded invariant is the permission, not its floor.
     'POST /done-when/:criterionId/unsatisfy': 'perm:criterion.unsatisfy',
+    // task 1004392 (ADR 0351): a criterion closes on a UAT sign-off. Uploading
+    // the recording and signing off ride `criterion.review`, the review queue's
+    // own atom, because the sign-off IS that review now; the wall that matters is
+    // in-handler (nobody who shipped the linked work may sign it off). Marking a
+    // criterion backend-only decides whether a recording is needed at all, so it
+    // is an AUTHORING act: `criterion.create` plus authorizeCriterionCreate.
+    'POST /done-when/:criterionId/uat/recording': 'perm:criterion.review',
+    'POST /done-when/:criterionId/uat': 'perm:criterion.review',
+    'PUT /done-when/:criterionId/backend-only': 'perm:criterion.create',
     // gate-surface PR approval from the hall (task 1179, ADR 0058 amendment). ADR 0157
     // SPLIT these two: the list route is `gate_approval.read` (metic — the Gate page
     // opens to the working rank), while APPROVING still clears the gate-review hard

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.5'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.7'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/auto_satisfy_criteria.mjs

@@ -139,12 +139,14 @@ await test('EXEC: shipTask passes its transaction CLIENT, and the reconciler pas
 await test('SCOPED vs UNSCOPED: the taskId parameter is what narrows the candidate set', async () => {
   const scoped = fakeExec({ rows: [] });
   await autoSatisfyShippedCriteria(scoped, { taskId: 42 });
-  assert.deepEqual(scoped.calls[0].params, [42]);
+  // task 1004392 added a second scope ($2, the sign-off route's criterionId); the ship
+  // hook leaves it null.
+  assert.deepEqual(scoped.calls[0].params, [42, null]);
   assert.match(scoped.calls[0].sql, /\$1::bigint IS NULL OR c\.id IN/, 'one SQL serves both shapes');
 
   const sweep = fakeExec({ rows: [] });
   await autoSatisfyShippedCriteria(sweep, {});
-  assert.deepEqual(sweep.calls[0].params, [null], 'unscoped passes NULL, which disables the narrowing clause');
+  assert.deepEqual(sweep.calls[0].params, [null, null], 'unscoped passes NULL, which disables the narrowing clause');
 });
 
 await test('NO-OP: nothing closed means no cascade query at all', async () => {

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();