@bongos/core 1.20.5 → 1.20.7

package/modules/lifecycle/criterion-uat-db.js

@@ -0,0 +1,267 @@
+'use strict';
+
+// criterion-uat-db.js — the SQL and the one transaction behind a UAT sign-off
+// (task 1004392, goal 1000089; ADR 0351). The decisions are pure in
+// criterion-uat.js; this file gathers the facts they need, asks, and writes.
+//
+// THE SIGN-OFF IS ONE TRANSACTION: lock the criterion, re-read its linked work
+// under the lock, decide, insert the sign-off row, and close the criterion (and
+// cascade its goal and version) through the SAME autoSatisfyShippedCriteria the
+// ship hook and the reconciler sweep use. One close path, so a criterion closed
+// by a sign-off and one closed by the sweep can never mean different things.
+//
+// THE LIVE READING is taken BEFORE the transaction, because it can reach the npm
+// registry and a network call has no business holding a row lock. It is keyed on
+// the linked shipped task ids read at that moment; the transaction re-reads them
+// under the lock and refuses (`linked_work_changed`) if the set moved in between,
+// so a reading can never be applied to work it did not look at.
+
+const api = require('../../src/module-api');
+const doneWhen = require('./done-when.js');
+const uat = require('./criterion-uat.js');
+
+// The optional port a deploy-reading module provides (npm-release on the Bongos
+// hall): { readTaskWhere(taskId) → { stage, partial } | null }. Most instances
+// have none, and then the signer attests (the owner's 2026-09-29 decision).
+const DEPLOY_PORT = 'deploy.taskWhere';
+
+// Linked tasks with what the ladder needs: status, who shipped it, and when.
+async function linkedTasks(exec, criterionId) {
+  const { rows } = await exec.query(
+    `SELECT t.id, t.status, t.shipped_by, t.shipped_at
+       FROM task_criteria tc
+       JOIN tasks t ON t.id = tc.task_id
+      WHERE tc.criterion_id = $1
+      ORDER BY t.id`,
+    [criterionId]
+  );
+  return rows;
+}
+
+// PURE — fold linked task rows into the counts + the open ones + the shippers.
+function summarizeLinked(tasks) {
+  const terminal = (s) => s === 'shipped' || s === 'abandoned';
+  const shipped = tasks.filter((t) => t.status === 'shipped');
+  return {
+    counts: {
+      linked: tasks.length,
+      unshipped: tasks.filter((t) => !terminal(t.status)).length,
+      shipped: shipped.length,
+    },
+    remaining: tasks.filter((t) => !terminal(t.status)),
+    shipperIds: [...new Set(shipped.map((t) => t.shipped_by).filter((b) => b != null).map(String))],
+    shippedIds: shipped.map((t) => String(t.id)),
+    // The newest linked ship: a sign-off older than this is stale (the same rule
+    // the auto-close SQL applies with candidate.last_ship).
+    lastShip: shipped.reduce((m, t) => (t.shipped_at && (!m || new Date(t.shipped_at) > m) ? new Date(t.shipped_at) : m), null),
+  };
+}
+
+// PURE — split the sign-offs into the CURRENT one (what counts) and a STALE one
+// (the newest sign-off that predates the newest linked ship). A reader must never
+// see a sign-off beside 'Awaiting UAT' without being told it no longer counts.
+function currentSignoff(signoffs, lastShip) {
+  const real = (signoffs || []).filter((r) => r.kind === 'uat' || r.kind === 'backend_signoff');
+  const current = real.find((r) => !lastShip || new Date(r.created_at) >= lastShip) || null;
+  return { current, stale: current ? null : real[0] || null };
+}
+
+async function isBackendOnly(exec, criterionId) {
+  const { rows } = await exec.query(
+    'SELECT 1 FROM lifecycle_criterion_backend_only WHERE criterion_id = $1', [criterionId]
+  );
+  return rows.length > 0;
+}
+
+// The deploy readings for these shipped tasks, or null when this instance has
+// no deploy reading (no provider). A provider that throws answers a PARTIAL
+// reading, which foldLiveReadings treats as unavailable — an outage must not
+// block a person, it only moves "is it live" back to their word.
+//
+// The BATCH form (readTasksWhere) is preferred: the registry and release-notes
+// half of the reading does not depend on the task, so a per-task loop re-fetched
+// it once per linked task. The per-task form stays as the fallback for a
+// provider that only offers it.
+async function readLive(taskIds, deps = {}) {
+  const port = deps.deployPort !== undefined ? deps.deployPort : api.resolveOptional(DEPLOY_PORT);
+  if (!port) return null;
+  if (typeof port.readTasksWhere === 'function') {
+    let byId;
+    try {
+      byId = (await port.readTasksWhere(taskIds)) || {};
+    } catch {
+      return taskIds.map((id) => ({ task_id: id, stage: null, partial: true }));
+    }
+    return taskIds.map((id) => {
+      const r = byId[String(id)];
+      return r ? { task_id: id, stage: r.stage, partial: !!r.partial } : { task_id: id, stage: null, partial: true };
+    });
+  }
+  if (typeof port.readTaskWhere !== 'function') return null;
+  const readings = [];
+  for (const id of taskIds) {
+    try {
+      const r = await port.readTaskWhere(id);
+      readings.push(r ? { task_id: id, stage: r.stage, partial: !!r.partial } : { task_id: id, stage: null, partial: true });
+    } catch {
+      readings.push({ task_id: id, stage: null, partial: true });
+    }
+  }
+  return readings;
+}
+
+// signOff — record a UAT (kind 'uat') or a backend sign-off, and close the
+// criterion if that makes it done. Returns { ok:true, signoff, closed } or
+// { ok:false, refusal } (never throws on a refusal).
+async function signOff({ criterionId, kind, signerId, recording = null, liveAttested = false, note = null }, deps = {}) {
+  const id = Number(criterionId);
+  if (!uat.SIGNOFF_KINDS.includes(kind) || kind === 'override') {
+    return { ok: false, refusal: { code: 'bad_kind', status: 400, message: 'A sign-off is either a UAT or a backend sign-off.' } };
+  }
+  if (recording != null) {
+    if (uat.criterionIdFromName(recording) !== id) {
+      return { ok: false, refusal: { code: 'recording_not_for_this_criterion', status: 400, message: 'That recording was uploaded for a different criterion.' } };
+    }
+  }
+
+  // Test seams: a fake pool + transaction runner (NODE_ENV=test only, the #538
+  // precedent), so the whole ladder and the write run in a DB-free test.
+  const testing = process.env.NODE_ENV === 'test';
+  const pool = (testing && deps.pool) || api.pool;
+  const withTx = (testing && deps.withTx) || api.withTx;
+
+  // Before the lock: the linked set as it stands now, and its deploy reading.
+  const before = summarizeLinked(await linkedTasks(pool, id));
+  const readings = await readLive(before.shippedIds, deps);
+  const live = uat.foldLiveReadings(readings);
+  const owner = deps.ownerId !== undefined ? { id: deps.ownerId } : await api.getFoundingBuilder();
+
+  return withTx(async (client) => {
+    const { rows: crit } = await client.query(
+      'SELECT id, satisfied, goal_id, version_id FROM done_when_criteria WHERE id = $1 FOR UPDATE', [id]
+    );
+    const criterion = crit[0] || null;
+    const now = criterion ? summarizeLinked(await linkedTasks(client, id)) : before;
+    if (criterion && now.shippedIds.join(',') !== before.shippedIds.join(',')) {
+      return { ok: false, refusal: { code: 'linked_work_changed', status: 409, message: 'The work linked to this criterion changed while you were signing off. Try again.' } };
+    }
+    const backendOnly = criterion ? await isBackendOnly(client, id) : false;
+    const refusal = uat.signoffRefusal({
+      criterion, counts: now.counts, remaining: now.remaining, backendOnly, kind,
+      signerId, ownerId: owner ? owner.id : null, shipperIds: now.shipperIds,
+      recording, live, liveAttested,
+    });
+    if (refusal) return { ok: false, refusal };
+
+    const { rows: ins } = await client.query(
+      `INSERT INTO lifecycle_criterion_uats (criterion_id, kind, signed_off_by, recording_file, live_basis, note)
+       VALUES ($1, $2, $3, $4, $5, $6)
+       RETURNING id, criterion_id, kind, signed_off_by, recording_file, live_basis, note, created_at`,
+      [id, kind, signerId, recording, uat.liveBasis(live), uat.normalizeNote(note)]
+    );
+    const closed = await doneWhen.autoSatisfyShippedCriteria(client, { criterionId: id });
+    return { ok: true, signoff: ins[0], closed };
+  }, { pool });
+}
+
+// recordOverride — the /satisfy escape hatch, which now has to give a reason and
+// leaves a row saying so (the state reads "Satisfied (override)", never UAT).
+async function recordOverride(exec, { criterionId, signerId, reason }) {
+  const { rows } = await exec.query(
+    `INSERT INTO lifecycle_criterion_uats (criterion_id, kind, signed_off_by, live_basis, note)
+     VALUES ($1, 'override', $2, 'not_checked', $3)
+     RETURNING id, kind, created_at`,
+    [criterionId, signerId, uat.normalizeNote(reason)]
+  );
+  return rows[0];
+}
+
+// Every sign-off on a criterion, newest first, with who signed.
+async function listSignoffs(criterionId, deps = {}) {
+  const exec = deps.pool || api.pool;
+  const { rows } = await exec.query(
+    `SELECT u.id, u.kind, u.signed_off_by, b.github_login AS signed_off_by_login,
+            u.recording_file, u.live_basis, u.note, u.created_at
+       FROM lifecycle_criterion_uats u
+       LEFT JOIN builders b ON b.id = u.signed_off_by
+      WHERE u.criterion_id = $1
+      ORDER BY u.created_at DESC, u.id DESC`,
+    [criterionId]
+  );
+  return rows;
+}
+
+// The criterion's full UAT picture for GET /done-when/:id/uat and the skill.
+async function uatView(criterionId, deps = {}) {
+  const exec = deps.pool || api.pool;
+  const { rows: crit } = await exec.query(
+    'SELECT id, criterion_id, criterion_md, satisfied, goal_id, version_id FROM done_when_criteria WHERE id = $1', [criterionId]
+  );
+  if (!crit.length) return null;
+  const tasks = await linkedTasks(exec, criterionId);
+  const s = summarizeLinked(tasks);
+  const [signoffs, backendOnly] = await Promise.all([listSignoffs(criterionId, { pool: exec }), isBackendOnly(exec, criterionId)]);
+  const state = uat.uatState({ ...s.counts, satisfied: crit[0].satisfied, latestKind: signoffs[0] ? signoffs[0].kind : null });
+  return {
+    criterion: crit[0],
+    uat_state: state,
+    uat_label: uat.stateLabel(state),
+    backend_only: backendOnly,
+    checks: {
+      code: uat.codeMet(s.counts),
+      live: state === uat.UAT_STATES.AWAITING_UAT ? uat.foldLiveReadings(await readLive(s.shippedIds, deps)) : null,
+      // Only a CURRENT sign-off is the UAT check; one that predates newer linked
+      // work is reported separately as stale, never as passed.
+      uat: currentSignoff(signoffs, s.lastShip).current,
+      stale_uat: currentSignoff(signoffs, s.lastShip).stale,
+    },
+    linked_tasks: tasks.map((t) => ({ id: String(t.id), status: t.status, shipped_by: t.shipped_by == null ? null : String(t.shipped_by) })),
+    signoffs,
+  };
+}
+
+// Mark or unmark backend-only. `authorize(client, criterion)` is the caller's
+// authority gate (the criterion-authoring wall), run INSIDE this transaction with
+// the criterion locked so the decision and the write see the same rows; it
+// returns null to allow or a refusal. This refuses once the criterion is past
+// OPEN, because the flag decides whether a recording is required and must not be
+// chosen by whoever is closing it.
+async function setBackendOnly({ criterionId, builderId, backendOnly, authorize }, deps = {}) {
+  const testing = process.env.NODE_ENV === 'test';
+  const withTx = (testing && deps.withTx) || api.withTx;
+  return withTx(async (client) => {
+    const { rows: crit } = await client.query(
+      'SELECT id, satisfied, goal_id, version_id FROM done_when_criteria WHERE id = $1 FOR UPDATE', [criterionId]
+    );
+    if (!crit.length) return { ok: false, refusal: { code: 'criterion_not_found', status: 404, message: 'No such criterion.' } };
+    const denied = await authorize(client, crit[0]);
+    if (denied) return { ok: false, refusal: denied };
+    const s = summarizeLinked(await linkedTasks(client, criterionId));
+    if (crit[0].satisfied || uat.codeMet(s.counts)) {
+      return { ok: false, refusal: { code: 'backend_only_locked', status: 409, message: 'Backend-only is set while a criterion is still open. This one is already awaiting UAT or closed, so it can no longer change.' } };
+    }
+    if (backendOnly) {
+      await client.query(
+        `INSERT INTO lifecycle_criterion_backend_only (criterion_id, marked_by) VALUES ($1, $2)
+         ON CONFLICT (criterion_id) DO NOTHING`, [criterionId, builderId]
+      );
+    } else {
+      await client.query('DELETE FROM lifecycle_criterion_backend_only WHERE criterion_id = $1', [criterionId]);
+    }
+    return { ok: true, backend_only: !!backendOnly };
+  }, { pool: (testing && deps.pool) || api.pool });
+}
+
+module.exports = {
+  DEPLOY_PORT,
+  linkedTasks,
+  summarizeLinked,
+  currentSignoff,
+  isBackendOnly,
+  readLive,
+  signOff,
+  recordOverride,
+  listSignoffs,
+  uatView,
+  setBackendOnly,
+};

package/modules/lifecycle/criterion-uat.js

@@ -0,0 +1,303 @@
+'use strict';
+
+// criterion-uat.js — the UAT a criterion must pass before it closes, as pure
+// decisions plus the recording store (task 1004392, goal 1000089; ADR 0351).
+//
+// WHY. ADR 0183 let a criterion close the moment every task linked to it
+// shipped. That checked that SOME work shipped, never that the work did what the
+// criterion's words say, or that it reached the live site. wa7-government closed
+// on six Board Room navigation tasks while the configurable ranks and project-
+// type recommendations it describes did not exist on the live site. So shipped
+// code is now the first of three checks:
+//
+//   Code  every linked task is done (>=1 shipped, none still open) — automatic
+//   Live  the shipped work is running on the deployed site — read where the
+//         instance can tell, otherwise attested by the signer
+//   UAT   a signed-in person performed the criterion on the live site and a
+//         recording is stored; a BACKEND-ONLY criterion has no screen, so it takes
+//         a recording-free sign-off instead
+//
+// A criterion whose Code check passes reads AWAITING UAT (the owner's
+// 2026-09-29 ask: people must see that the baseline looks met). It closes only
+// when a CURRENT sign-off exists — one no older than the newest linked ship,
+// because work shipped after a sign-off is work nobody checked.
+//
+// WHO MAY SIGN OFF. Anyone who holds the review permission AND did not ship any
+// of the criterion's linked tasks. The project owner is the one exception, so a
+// solo project can never deadlock on its own work (the owner's "any other
+// builder or the owner").
+//
+// This file has NO database and NO express: the state derivation and the
+// refusal ladder are pure so every answer is pinned by a DB-free test, and the
+// store unit-tests against a temp dir. The SQL lives in criterion-uat-db.js.
+//
+// THE RECORDING STORE mirrors task-visuals.js (the same allowlist + magic-byte
+// sniff + server-minted name + resolveSafe shape, re-stated rather than shared
+// because the two differ in kind and cap), for video instead of images.
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const fsSync = require('node:fs');
+const crypto = require('node:crypto');
+
+// ── the states ──────────────────────────────────────────────────────────────
+
+// One vocabulary for every reader (the goal page, /status, the sky, the skill).
+const UAT_STATES = Object.freeze({
+  OPEN: 'open',                         // linked work still open, or none linked
+  AWAITING_UAT: 'awaiting_uat',         // Code passed; no current sign-off
+  SATISFIED_UAT: 'satisfied_uat',       // closed on a recorded UAT
+  SATISFIED_BACKEND: 'satisfied_backend', // closed on a backend-only sign-off
+  SATISFIED_OVERRIDE: 'satisfied_override', // closed through /satisfy with a reason
+  CLOSED_BEFORE_UAT: 'closed_before_uat', // satisfied before this rule existed
+});
+
+const SIGNOFF_KINDS = Object.freeze(['uat', 'backend_signoff', 'override']);
+
+// PURE — has the Code check passed? Every linked task is terminal and at least
+// one actually SHIPPED. The second clause is ADR 0183's delivery guard, kept: a
+// criterion whose linked tasks were all ABANDONED delivered nothing, so it is not
+// awaiting a UAT — it is waiting for a person to decide whether it still means
+// anything (the /goal-review residue).
+function codeMet({ linked, unshipped, shipped }) {
+  return Number(linked) > 0 && Number(unshipped) === 0 && Number(shipped) >= 1;
+}
+
+// PURE — the one derivation of a criterion's state. `latestKind` is the kind of
+// its newest sign-off row (null when it has none). A satisfied criterion with no
+// row closed before this rule existed, which the owner chose to leave closed.
+function uatState({ satisfied, linked, unshipped, shipped, latestKind = null }) {
+  if (satisfied) {
+    if (latestKind === 'uat') return UAT_STATES.SATISFIED_UAT;
+    if (latestKind === 'backend_signoff') return UAT_STATES.SATISFIED_BACKEND;
+    if (latestKind === 'override') return UAT_STATES.SATISFIED_OVERRIDE;
+    return UAT_STATES.CLOSED_BEFORE_UAT;
+  }
+  return codeMet({ linked, unshipped, shipped }) ? UAT_STATES.AWAITING_UAT : UAT_STATES.OPEN;
+}
+
+// PURE — the plain-words label for a state, so the CLI, the skill and the API
+// say the same thing.
+function stateLabel(state) {
+  return {
+    open: 'Open',
+    awaiting_uat: 'Awaiting UAT',
+    satisfied_uat: 'Satisfied (UAT)',
+    satisfied_backend: 'Satisfied (backend sign-off)',
+    satisfied_override: 'Satisfied (override)',
+    closed_before_uat: 'Closed before UAT',
+  }[state] || String(state);
+}
+
+// ── the Live check ──────────────────────────────────────────────────────────
+
+// The deploy stages (modules/npm-release/work.js placeTasks) that mean "this
+// task's code is running on this site".
+const LIVE_STAGES = Object.freeze(['live_unreleased', 'released']);
+
+// PURE — fold per-task deploy readings into one answer. `readings` is
+// [{ task_id, stage, partial }] for every linked SHIPPED task, or null when the
+// instance has no deploy reading at all. Answers:
+//   { available:false }                      nothing to read here → the signer attests
+//   { available:true, live:true }            every shipped task runs here
+//   { available:true, live:false, not_live } the tasks that do not, yet
+// A PARTIAL reading (the notes or the registry could not be read) is treated as
+// unavailable rather than as "not live": refusing a sign-off because a reading
+// failed would block a person on an outage, and attestation is the honest
+// fallback the owner chose for instances that cannot read it at all.
+function foldLiveReadings(readings) {
+  if (!Array.isArray(readings)) return { available: false };
+  if (readings.some((r) => !r || r.partial)) return { available: false };
+  const notLive = readings.filter((r) => !LIVE_STAGES.includes(r.stage)).map((r) => ({ task_id: String(r.task_id), stage: r.stage || null }));
+  return notLive.length ? { available: true, live: false, not_live: notLive } : { available: true, live: true };
+}
+
+// ── the sign-off refusal ladder ─────────────────────────────────────────────
+
+// PURE — may this person sign this criterion off now? Returns null (allowed) or
+// { code, status, message, ...detail }. The ORDER is the order a person would
+// want to be told: is there anything to sign, is it the right kind of sign-off,
+// are you allowed to, is the evidence there, is it live.
+//
+//   criterion      { satisfied }
+//   counts         { linked, unshipped, shipped }
+//   remaining      [{ id, status }] linked tasks still open (named in the refusal)
+//   backendOnly    boolean
+//   kind           'uat' | 'backend_signoff'
+//   signerId       the authenticated builder
+//   ownerId        the project owner (getFoundingBuilder), or null
+//   shipperIds     builder ids that shipped a linked task
+//   recording      a stored recording name, or null
+//   live           foldLiveReadings(...) output
+//   liveAttested   the signer ticked "this is on the live site"
+function signoffRefusal({ criterion, counts, remaining = [], backendOnly, kind, signerId, ownerId = null, shipperIds = [], recording = null, live = { available: false }, liveAttested = false }) {
+  if (!criterion) return { code: 'criterion_not_found', status: 404, message: 'No such criterion.' };
+  if (criterion.satisfied) {
+    return { code: 'criterion_already_satisfied', status: 409, message: 'This criterion is already closed.' };
+  }
+  if (!codeMet(counts)) {
+    return {
+      code: 'criterion_not_awaiting_uat', status: 409,
+      message: Number(counts.linked) === 0
+        ? 'This criterion has no linked tasks, so there is no shipped work to test yet. Link the tasks that deliver it first.'
+        : Number(counts.shipped) === 0 && Number(counts.unshipped) === 0
+          ? 'Every task linked to this criterion was abandoned, so nothing was delivered to test. Decide in /goal-review whether it still means anything.'
+          : 'Some linked work is still open. A UAT tests finished work, so it opens once every linked task is done.',
+      remaining: remaining.map((t) => ({ id: String(t.id), status: t.status })),
+    };
+  }
+  if (kind === 'uat' && backendOnly) {
+    return { code: 'criterion_is_backend_only', status: 409, message: 'This criterion is marked backend-only, so it takes a backend sign-off, not a recording.' };
+  }
+  if (kind === 'backend_signoff' && !backendOnly) {
+    return { code: 'criterion_needs_recording', status: 409, message: 'This criterion is user-facing, so it needs a UAT recording. Only a criterion marked backend-only when it was written can be signed off without one.' };
+  }
+  const signer = String(signerId);
+  const isOwner = ownerId != null && String(ownerId) === signer;
+  if (!isOwner && shipperIds.map(String).includes(signer)) {
+    return { code: 'signer_shipped_this_work', status: 403, message: 'You shipped work linked to this criterion, so someone else has to sign it off. Any other reviewer, or the project owner, can.' };
+  }
+  if (kind === 'uat' && !recording) {
+    return { code: 'uat_recording_required', status: 400, message: 'Upload the recording of you doing this on the live site first.' };
+  }
+  if (live.available && !live.live) {
+    return { code: 'work_not_live', status: 409, message: 'Some of this work is shipped but not running on the site yet, so it cannot be tested there. Sign off once it is deployed.', not_live: live.not_live || [] };
+  }
+  if (!live.available && !liveAttested) {
+    return { code: 'live_attestation_required', status: 400, message: 'This site cannot tell on its own whether the work is live. Confirm that you tested it on the live site.' };
+  }
+  return null;
+}
+
+// PURE — how "it is live" was established, for the stored row.
+function liveBasis(live) {
+  return live && live.available ? 'deploy_reading' : 'attested';
+}
+
+// ── the recording store ─────────────────────────────────────────────────────
+
+const EXT_BY_TYPE = Object.freeze({ 'video/mp4': 'mp4', 'video/webm': 'webm' });
+const TYPE_BY_EXT = Object.freeze({ mp4: 'video/mp4', webm: 'video/webm' });
+const MAX_RECORDING_BYTES = 100 * 1024 * 1024; // the owner's cap, 2026-09-29
+const MAX_NOTE_LENGTH = 2000;
+
+// Server-minted, carries the criterion id. This regex is the whole path-traversal
+// wall, and it matches the column CHECK in lifecycle_015.
+const NAME_RE = /^uat-(\d{1,12})-[0-9a-f]{16}\.(mp4|webm)$/;
+
+// Outside the git tree so a deploy never wipes it; env override for tests.
+function recordingsDir() {
+  return process.env.UAT_RECORDINGS_DIR || path.join(__dirname, '..', '..', 'var', 'uat-recordings');
+}
+
+function isSafeName(name) {
+  return typeof name === 'string' && NAME_RE.test(name);
+}
+
+function criterionIdFromName(name) {
+  const m = typeof name === 'string' ? NAME_RE.exec(name) : null;
+  return m ? Number(m[1]) : null;
+}
+
+function resolveSafe(name, { dir = recordingsDir() } = {}) {
+  if (!isSafeName(name)) return null;
+  const root = path.resolve(dir);
+  const p = path.resolve(root, name);
+  if (p !== path.join(root, name) || !p.startsWith(root + path.sep)) return null;
+  return p;
+}
+
+function contentTypeForName(name) {
+  return TYPE_BY_EXT[String(name).split('.').pop().toLowerCase()] || 'application/octet-stream';
+}
+
+// PURE — are these bytes really the claimed container? mp4 carries an `ftyp` box
+// at offset 4; webm is EBML (1A 45 DF A3).
+function sniffMatches(buf, ext) {
+  if (!buf || buf.length < 12) return false;
+  if (ext === 'mp4') return buf[4] === 0x66 && buf[5] === 0x74 && buf[6] === 0x79 && buf[7] === 0x70;
+  if (ext === 'webm') return buf[0] === 0x1a && buf[1] === 0x45 && buf[2] === 0xdf && buf[3] === 0xa3;
+  return false;
+}
+
+// PURE — screen one upload. { ok:true, ext } or { ok:false, reason }; never throws.
+function screenRecording(buf, contentType) {
+  const ext = EXT_BY_TYPE[String(contentType || '').split(';')[0].trim().toLowerCase()];
+  if (!ext) return { ok: false, reason: 'bad_type' };
+  if (!buf || buf.length === 0) return { ok: false, reason: 'empty' };
+  if (buf.length > MAX_RECORDING_BYTES) return { ok: false, reason: 'too_big', bytes: buf.length };
+  if (!sniffMatches(buf, ext)) return { ok: false, reason: 'sniff_mismatch' };
+  return { ok: true, ext };
+}
+
+// The words for a refused upload, shared by the route and the CLI.
+function screenMessage(reason) {
+  return {
+    bad_type: 'A UAT recording must be an mp4 or webm video.',
+    empty: 'The file is empty.',
+    too_big: `The recording is over the ${MAX_RECORDING_BYTES / 1024 / 1024} MB cap. Record a shorter pass, or lower the resolution.`,
+    sniff_mismatch: 'The file does not look like the video type it claims to be.',
+  }[reason] || 'The recording was refused. Try recording it again as an mp4 or webm.';
+}
+
+async function persistRecording(buf, { criterionId, contentType, dir = recordingsDir() } = {}) {
+  const id = Number(criterionId);
+  if (!Number.isInteger(id) || id <= 0 || String(id).length > 12) return { ok: false, reason: 'bad_criterion_id' };
+  const screened = screenRecording(buf, contentType);
+  if (!screened.ok) return screened;
+  const file = `uat-${id}-${crypto.randomBytes(8).toString('hex')}.${screened.ext}`;
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(path.join(dir, file), buf, { mode: 0o640 });
+  return { ok: true, file, bytes: buf.length };
+}
+
+// The CLI intake: read a recording off disk and screen it exactly as the server
+// will. { ok:true, buf, contentType } or { ok:false, message }.
+function readRecordingFile(file) {
+  const resolved = path.resolve(String(file || ''));
+  let buf;
+  try {
+    if (!fsSync.statSync(resolved).isFile()) return { ok: false, message: 'that path is not a file.' };
+    buf = fsSync.readFileSync(resolved);
+  } catch (err) {
+    return { ok: false, message: err && err.code === 'ENOENT' ? 'no such file.' : (err && err.message) || 'could not be read.' };
+  }
+  const contentType = TYPE_BY_EXT[path.extname(resolved).slice(1).toLowerCase()];
+  if (!contentType) return { ok: false, message: 'a UAT recording must be an .mp4 or .webm file.' };
+  const screened = screenRecording(buf, contentType);
+  if (!screened.ok) return { ok: false, message: screenMessage(screened.reason) };
+  return { ok: true, buf, contentType };
+}
+
+// PURE — a note: trimmed, bounded; empty → null.
+function normalizeNote(note) {
+  const s = String(note == null ? '' : note).trim().slice(0, MAX_NOTE_LENGTH);
+  return s || null;
+}
+
+module.exports = {
+  UAT_STATES,
+  SIGNOFF_KINDS,
+  LIVE_STAGES,
+  codeMet,
+  uatState,
+  stateLabel,
+  foldLiveReadings,
+  signoffRefusal,
+  liveBasis,
+  EXT_BY_TYPE,
+  TYPE_BY_EXT,
+  MAX_RECORDING_BYTES,
+  MAX_NOTE_LENGTH,
+  recordingsDir,
+  isSafeName,
+  criterionIdFromName,
+  resolveSafe,
+  contentTypeForName,
+  sniffMatches,
+  screenRecording,
+  screenMessage,
+  persistRecording,
+  readRecordingFile,
+  normalizeNote,
+};

package/modules/lifecycle/db-goals.js

@@ -819,9 +819,10 @@ async function listCriteriaForGoal(goalId, deps = {}) {
   // unchanged apart from the two additive count columns.
   const { rows } = await activePool.query(
     `WITH crit AS (
-       SELECT id, version_id, criterion_id, criterion_md, satisfied, sort_order, goal_id
-         FROM done_when_criteria
-        WHERE goal_id = $1
+       SELECT d.id, d.version_id, d.criterion_id, d.criterion_md, d.satisfied, d.sort_order, d.goal_id,
+              ${doneWhen.uatReadColumnsSql('d')}
+         FROM done_when_criteria d
+        WHERE d.goal_id = $1
      ),
      counts AS (
        SELECT tc.criterion_id,
@@ -829,27 +830,39 @@ async function listCriteriaForGoal(goalId, deps = {}) {
               -- task 1002651 (migration 017's family): abandoned is a terminal
               -- state (deliberately cut), not pending work — it must not hold a
               -- criterion's "met — pending review" flip hostage forever.
-              count(*) FILTER (WHERE ${nonTerminalSql()})::int AS unshipped_tasks
+              count(*) FILTER (WHERE ${nonTerminalSql()})::int AS unshipped_tasks,
+              count(*) FILTER (WHERE t.status = 'shipped')::int AS shipped_tasks
          FROM task_criteria tc
          JOIN tasks t ON t.id = tc.task_id
         WHERE tc.criterion_id IN (SELECT id FROM crit)
         GROUP BY tc.criterion_id
      )
      SELECT c.id, c.version_id, c.criterion_id, c.criterion_md, c.satisfied,
-            c.sort_order, c.goal_id,
+            c.sort_order, c.goal_id, c.uat_kind, c.backend_only,
             COALESCE(n.linked_tasks, 0)    AS linked_tasks,
-            COALESCE(n.unshipped_tasks, 0) AS unshipped_tasks
+            COALESCE(n.unshipped_tasks, 0) AS unshipped_tasks,
+            COALESCE(n.shipped_tasks, 0)   AS shipped_tasks
        FROM crit c
        LEFT JOIN counts n ON n.criterion_id = c.id
       ORDER BY sort_order, id`,
     [goalId]
   );
-  return rows.map((r) => ({
-    ...r,
-    pending_review: doneWhen.isPendingReview({
-      satisfied: r.satisfied, linked: r.linked_tasks, unshipped: r.unshipped_tasks,
-    }),
-  }));
+  // task 1004392: the goal page reads each criterion's UAT state beside the
+  // older pending-review flag (piece 2 relabels the page; the fact is here now).
+  return rows.map(({ uat_kind: latestKind, ...r }) => {
+    const uat_state = doneWhen.uatState({
+      satisfied: r.satisfied, linked: r.linked_tasks, unshipped: r.unshipped_tasks, shipped: r.shipped_tasks, latestKind,
+    });
+    return {
+      ...r,
+      backend_only: r.backend_only === true,
+      pending_review: doneWhen.isPendingReview({
+        satisfied: r.satisfied, linked: r.linked_tasks, unshipped: r.unshipped_tasks,
+      }),
+      uat_state,
+      awaiting_uat: uat_state === 'awaiting_uat',
+    };
+  });
 }
 
 // listCriterionTextForGoals — every goal's done-when criterion prose, keyed by