@nanobpm/nano-workforce 0.189.0 → 0.189.2

package/app/adjudications.ts

@@ -0,0 +1,378 @@
+// Durable wait-answer adjudication memory (issue #806) — the app's record that "(this PR, this
+// question) was already adjudicated to X by a human at T", so a stateless convergence round that
+// re-derives the identical escalation condition auto-resumes with the recorded answer instead of
+// re-parking a human from scratch (PR #800 / proc 46310: the same design question escalated at
+// round 2 and again at round 13).
+//
+// A human adjudication is NOT GitHub-derivable — the convergence gate is intentionally stateless
+// w.r.t. GitHub, but a human's decision is a fact only the app can remember — so it is persisted
+// durably in `pr_adjudications` (migration 109), keyed by the PR and the canonical QUESTION
+// FINGERPRINT (the SAME `normalizeAdvisoryText` + `fingerprint` normalisation advisory acks key on,
+// exported from app/github.ts — no second fingerprint implementation).
+//
+// Two touch points on the CANONICAL escalation/answer path own this store (no parallel adjudication
+// store, no second suppression heuristic — derivation over duplication):
+//   • `pr.answer-escalation` (record-answer) calls `recordAdjudication` on answering a `wait-answer`,
+//     persisting the settled answer + adjudicator.
+//   • the poller (`pollUserTasks`) calls `matchAdjudication` before surfacing a NEW `wait-answer`;
+//     on a fingerprint match it auto-resumes through `completeEscalationAutoApplied` — which shares the
+//     canonical `completeUserTaskAttributed` door a human's `completeEscalationAsHuman` uses, but records
+//     the completion `auto_applied`/`reversible` (never laundering the replay into a first-class human
+//     decision) — attributed to the prior adjudicator.
+import type { DataLayer, GatewayDataSource } from "@nanobpm/urban";
+import { isUniqueConstraintFence } from "./dbFence.ts";
+import { questionFingerprint } from "./github.ts";
+
+/** One durable human adjudication of a convergence question, keyed by `(pr_key, question_fingerprint)`
+ *  (a `UNIQUE` constraint; `id` is the surrogate single-column PK for the `Table<T>` gateway). */
+export interface PrAdjudicationRow {
+  id: number;
+  pr_key: string;
+  /** The canonical `questionFingerprint` (app/github.ts) of the settled escalation question. */
+  question_fingerprint: string;
+  /** The human's settled answer, replayed verbatim on auto-resume. */
+  answer: string | null;
+  /** Who settled it (the prior adjudicator), attributed on auto-resume. */
+  adjudicated_by: string | null;
+  /** Whether the prior adjudicator was a `human` or an `agent` (ADR 0046), preserved so an auto-resume
+   *  replays with the ORIGINAL attribution kind — never laundering an agent decision into a human one. */
+  adjudicated_kind: string | null;
+  adjudicated_at: string;
+  /** A TOMBSTONE timestamp set when a human reverts the auto-applied completion that replayed this
+   *  decision (issue #806 review). While set, the row is no longer replayable — {@link matchAdjudication}
+   *  skips it — but it stays present so the `UNIQUE (pr_key, question_fingerprint)` fence makes a
+   *  redelivered `record-answer` for the SAME reverted completion a no-op (a plain DELETE would let that
+   *  redelivery recreate the row and undo the revert). A FRESH, non-reverted answer to the re-parked
+   *  question REVIVES it ({@link reviveTombstonedDecision}) — clearing the tombstone so the human's new
+   *  override is remembered — while the reverted completion's own redelivery stays rejected. NULL = live. */
+  invalidated_at: string | null;
+  /** The `task_completions.id` of the WINNING completion that produced this decision (issue #806 review).
+   *  A FIRST-HAND agent answer records its own adjudication with `auto_applied=0` and no
+   *  `source_adjudication_id`; this link lets {@link invalidateAdjudicationByCompletion} tombstone the
+   *  decision when a human reverts that reversible agent completion — not only a machine auto-apply.
+   *  INSERT-if-absent, so it stays pinned to the ORIGINAL first-hand winner. NULL for a legacy/
+   *  uncorrelated answer. */
+  source_completion_id: number | null;
+}
+
+export const prAdjudications = (data: DataLayer) => data.table<PrAdjudicationRow>("pr_adjudications", "id");
+
+/** Pure: the durable adjudication whose fingerprint matches `question` (via the canonical
+ *  `questionFingerprint`), or `undefined`. Only a row carrying a non-blank `answer` is returned — a
+ *  blank/absent answer is not a replayable decision (the `pr-escalation.form` requires a non-blank
+ *  answer, so auto-resuming with a blank one would fail validation), so it never suppresses a fresh
+ *  escalation. A TOMBSTONED row (`invalidated_at` set — a human reverted the auto-apply that replayed
+ *  it, issue #806 review) is likewise never returned, so a reverted decision re-parks a human instead of
+ *  auto-applying again. */
+export function matchAdjudication(
+  rows: readonly PrAdjudicationRow[],
+  question: string,
+): PrAdjudicationRow | undefined {
+  const fp = questionFingerprint(question);
+  return rows.find(
+    (r) =>
+      r.question_fingerprint === fp &&
+      typeof r.answer === "string" &&
+      r.answer.trim() !== "" &&
+      (r.invalidated_at == null || r.invalidated_at.trim() === ""),
+  );
+}
+
+/** Input to {@link recordAdjudication}. `expectedProcessKey` is the run generation this answer job
+ *  belongs to (the `pr.answer-escalation` job's own process-instance key); every write is fenced on it
+ *  (see {@link generationGuard}) so a pre-reset straggler cannot resurrect a stale adjudication for a
+ *  fresh run. `undefined` (a job carrying no instance key) fails open, matching the worker's staleness
+ *  gate — an unclassifiable job proceeds rather than dropping a legitimate operator answer. */
+interface RecordAdjudicationInput {
+  prKey: string;
+  question: string;
+  answer: string | undefined;
+  adjudicatedBy: string | undefined;
+  adjudicatedKind: string | undefined;
+  expectedProcessKey?: string | undefined;
+  /** The `task_completions.id` of the winning completion this answer settled (issue #806 review), stored
+   *  as `source_completion_id` so a later revert of that completion can tombstone the decision it created.
+   *  Undefined for a legacy/uncorrelated answer (recorded NULL). */
+  sourceCompletionId?: number | undefined;
+}
+
+/** A SQL predicate (+ bind params) that is TRUE only while this write still belongs to the CURRENT run
+ *  generation: no `pull_requests` row for `prKey` carries a `process_key` that is BOTH set AND different
+ *  from the writer's `expectedProcessKey`. Woven into the adjudication INSERT/UPDATE so the ownership
+ *  check and the write are ONE atomic statement — the fix `submitPr` advances `process_key` BEFORE it
+ *  clears the memory relies on (Copilot review of #806): an `answer-escalation` straggler that read the
+ *  old key, then paused across a re-submit that advanced the key and deleted the rows, finds this guard
+ *  false at write time and no-ops, so it cannot insert its stale adjudication after the reset for the
+ *  fresh run to auto-apply. When `expectedProcessKey` is absent the guard is a constant TRUE (fail open,
+ *  mirroring the worker gate — an unclassifiable job must not be silently dropped). Exported so the
+ *  `pr.answer-escalation` worker fences its escalation/PR transitions on the SAME generation predicate
+ *  as this store's adjudication writes (one guard, no second implementation — Copilot review of #806). */
+export function generationGuard(prKey: string, expectedProcessKey: string | undefined): { sql: string; params: unknown[] } {
+  if (expectedProcessKey == null || expectedProcessKey === "") return { sql: "1 = 1", params: [] };
+  return {
+    sql: `NOT EXISTS (SELECT 1 FROM "pull_requests" WHERE "pr_key" = ? AND "process_key" IS NOT NULL AND "process_key" <> ?)`,
+    params: [prKey, expectedProcessKey],
+  };
+}
+
+/** A SQL predicate (+ bind params) that is TRUE only while the WINNING completion `sourceCompletionId`
+ *  has NOT been reverted. Woven into the adjudication INSERT/UPDATE so recording a first-hand agent
+ *  answer's decision and the completion's reverted state are checked in ONE atomic statement — closing
+ *  the revert-before-record race (issue #806 review, Copilot): a human revert of a first-hand agent
+ *  completion runs {@link invalidateAdjudicationByCompletion}, but if the downstream `record-answer` job
+ *  has not yet inserted the `pr_adjudications` row, that tombstone changes zero rows and the later insert
+ *  would otherwise create a LIVE decision linked to an already-reverted completion — which the poller
+ *  then re-auto-applies, silently undoing the revert. Fencing the insert on `reverted = 0` makes the
+ *  revert-then-record ordering a no-op (the insert affects zero rows), the mirror of the record-then-revert
+ *  ordering the by-completion tombstone already covers; SQLite serialises the two writes, so whichever
+ *  commits first, the other observes it. When `sourceCompletionId` is absent (a legacy/uncorrelated
+ *  answer with no completion to check) the guard is a constant TRUE (fail open, mirroring
+ *  {@link generationGuard}) — an unlinkable answer must not be silently dropped. */
+export function notRevertedGuard(sourceCompletionId: number | undefined): { sql: string; params: unknown[] } {
+  if (sourceCompletionId == null) return { sql: "1 = 1", params: [] };
+  return {
+    sql: `NOT EXISTS (SELECT 1 FROM "task_completions" WHERE "id" = ? AND "reverted" = 1)`,
+    params: [sourceCompletionId],
+  };
+}
+
+/** A stricter revive fence than {@link notRevertedGuard}: the source completion must be a FIRST-HAND
+ *  human answer (`auto_applied = 0`) AND not reverted. `record-answer` runs not only for a human's
+ *  first-hand answer to the re-parked `wait-answer` but ALSO for `completeEscalationAutoApplied`
+ *  REPLAYS (`auto_applied = 1`, a machine re-application of an already-recorded decision). If such a
+ *  replay's `record-answer` is in flight while a human reverts the FIRST-HAND source completion, the
+ *  replay completion is itself still `reverted = 0`, so a bare {@link notRevertedGuard} would let the
+ *  machine replay clear the operator's tombstone and RESURRECT the reverted decision (Copilot review of
+ *  #806). Only a genuine human answer (`auto_applied = 0`) may revive; a machine replay is a no-op.
+ *  A missing completion also fails the EXISTS (safe — no revive), so an uncorrelated/legacy id cannot
+ *  launder a revive. */
+export function firstHandRevivableGuard(sourceCompletionId: number): { sql: string; params: unknown[] } {
+  return {
+    sql: `EXISTS (SELECT 1 FROM "task_completions" WHERE "id" = ? AND "auto_applied" = 0 AND "reverted" = 0)`,
+    params: [sourceCompletionId],
+  };
+}
+
+/** Persist a human adjudication of `question` for `prKey`, INSERT-if-absent so the ORIGINAL
+ *  adjudicator/answer is preserved across later auto-resumes (which re-run record-answer with the
+ *  same fingerprint). A blank answer is not a decision and is not recorded. Idempotent: a second
+ *  answer to the identical question keeps the first settled row — UNLESS that first row was recorded
+ *  with UNKNOWN provenance (a blank `adjudicated_by`, from an answer that could not be correlated to
+ *  an adjudicator). `pollUserTasks` refuses to auto-resume an unknown-provenance decision (it never
+ *  launders an unattributed replay into a human authority), so such a row keeps re-parking a human
+ *  every round; when a KNOWN adjudicator later answers the same question, promote the row to a
+ *  replayable decision — its answer AND attribution — so future rounds auto-resume instead of
+ *  re-parking forever (issue #806 review). A row that ALREADY carries known provenance stays immutable.
+ *  A TOMBSTONED row (a human reverted the auto-applied replay) is REVIVED by a fresh, non-reverted answer
+ *  to the re-parked question ({@link reviveTombstonedDecision}) — otherwise the override is never
+ *  remembered and the question re-parks forever (Copilot review of #806) — while a redelivery of the
+ *  reverted completion itself is still rejected.
+ *
+ *  Every write is fenced on the run generation ({@link generationGuard}) so a pre-reset straggler cannot
+ *  write after `submitPr` advances `process_key`, AND the blank→known promotion is a conditional
+ *  compare-and-set (see {@link healBlankProvenance}) so two concurrent known healers cannot clobber each
+ *  other's answer/adjudicator — only the first promotion of a blank row wins, keeping the documented
+ *  first-known decision immutable (Copilot review of #806). */
+export async function recordAdjudication(data: DataLayer, input: RecordAdjudicationInput): Promise<void> {
+  const answer = typeof input.answer === "string" ? input.answer.trim() : "";
+  if (answer === "") return;
+  const question = input.question.trim();
+  if (question === "") return;
+  const fp = questionFingerprint(question);
+  const db = data.open();
+  const guard = generationGuard(input.prKey, input.expectedProcessKey);
+  const revertGuard = notRevertedGuard(input.sourceCompletionId);
+  try {
+    // Conditional INSERT-if-absent: the `... SELECT ? … WHERE <generationGuard>` is atomic, so the
+    // ownership check and the insert are ONE statement — a stale straggler's guard is false and the
+    // insert affects zero rows (no separate read-then-write TOCTOU window). A concurrent/redelivered
+    // answer that already inserted the SAME fingerprint trips the `UNIQUE(pr_key, question_fingerprint)`
+    // fence, which we tolerate below exactly as the sequential no-op the winner's durable row yields.
+    // The insert is ALSO fenced on the source completion NOT being reverted ({@link notRevertedGuard}):
+    // if a human reverted this first-hand agent completion before `record-answer` inserted its row, the
+    // revert-time tombstone found nothing to invalidate, so without this fence the insert would create a
+    // LIVE decision linked to an already-reverted completion that the poller re-auto-applies (issue #806
+    // review, Copilot — the revert-before-record ordering). Fenced, the insert affects zero rows.
+    const res = await db.exec(
+      `INSERT INTO "pr_adjudications" ("pr_key","question_fingerprint","answer","adjudicated_by","adjudicated_kind","adjudicated_at","source_completion_id")
+       SELECT ?, ?, ?, ?, ?, ?, ? WHERE ${guard.sql} AND ${revertGuard.sql}`,
+      [input.prKey, fp, answer, input.adjudicatedBy?.trim() || null, input.adjudicatedKind?.trim() || null, new Date().toISOString(), input.sourceCompletionId ?? null, ...guard.params, ...revertGuard.params],
+    );
+    if (res.changed > 0) return; // fresh insert won under the current generation
+  } catch (err) {
+    // Tolerate ONLY the UNIQUE fence as the idempotent no-op the sequential path yields (the winner's
+    // ORIGINAL row is already durable) — never surface it as a spurious `pr.answer-escalation` incident.
+    // Any other error still propagates. This is the ONE canonical fence classifier (`app/dbFence.ts`),
+    // the same pattern as `deliveryConnector`'s claim insert and `WorldStore`'s checkpoint insert
+    // (derivation over duplication).
+    if (!isUniqueConstraintFence(err)) throw err;
+  }
+  // We reach here when the insert affected no row: either a row already exists (UNIQUE fence, or another
+  // writer's row already present) OR the generation guard was false (a stale straggler — leave it a
+  // no-op). Re-read the ACTUAL current row and apply the blank→known promotion the winner would have; a
+  // stale straggler's heal is likewise fenced to a no-op, and an already-attributed row is immutable.
+  const winner = await prAdjudications(data).find({ pr_key: input.prKey, question_fingerprint: fp });
+  if (winner.length === 0) return;
+  // A TOMBSTONED winner (a human reverted the auto-applied replay) is REVIVED by a fresh, non-reverted
+  // answer to the re-parked question (issue #806 review) — otherwise the human's override is never
+  // remembered and the question re-parks forever. If the revive fires, we are done; only a LIVE
+  // blank-provenance winner falls through to the blank→known heal (the two preconditions are disjoint,
+  // but returning early keeps the healer off a row the revive just settled).
+  if (await reviveTombstonedDecision(data, winner[0], answer, input)) return;
+  await healBlankProvenance(data, winner[0], answer, input);
+}
+
+/** REVIVE a TOMBSTONED adjudication with a FRESH, non-reverted answer (issue #806 review). After a human
+ *  reverts an auto-applied replay, {@link invalidateAdjudicationByCompletion} tombstones the decision
+ *  (`invalidated_at` set) so {@link matchAdjudication} skips it and the recurring question re-parks a
+ *  human every round. When that human then answers the re-parked `wait-answer`, the fresh answer's
+ *  `record-answer` INSERT trips the `UNIQUE(pr_key, question_fingerprint)` fence, and with ONLY the
+ *  blank→known heal below it no-ops (the tombstoned row already carries known provenance and `invalidated_at`)
+ *  — so the tombstone survives and the override is NEVER remembered (Copilot review of #806: the recurring
+ *  question re-parks a human forever instead of remembering the new decision).
+ *
+ *  This CONDITIONAL compare-and-set clears the tombstone and installs the fresh answer/adjudicator, but
+ *  ONLY for a NEW, non-reverted, FIRST-HAND completion. The `UPDATE … WHERE "invalidated_at" IS NOT NULL`
+ *  re-checks the tombstone precondition INSIDE the write (so it fires on a tombstoned row and no-ops on a
+ *  live one), and the {@link firstHandRevivableGuard} on the INCOMING completion makes a REDELIVERY of the
+ *  very completion that was reverted (its `sourceCompletionId` is `reverted = 1`) AND a machine
+ *  auto-apply REPLAY (`auto_applied = 1`, whose own `record-answer` also runs) affect zero rows — so
+ *  neither the reverted answer nor an in-flight replay can resurrect the decision it was reverted from,
+ *  while a genuinely new FIRST-HAND human answer IS remembered (Copilot review of #806). Run-generation fenced ({@link generationGuard}) like every other
+ *  write, so a pre-reset straggler cannot revive after a re-submit reset. A revive INSTALLS a first-hand
+ *  replayable decision, so it requires a KNOWN adjudicator AND a KNOWN (correlated) completion — an
+ *  unattributed answer cannot launder into a replayable authority (mirrors the auto-resume provenance
+ *  gate), and an UNCORRELATED answer (no `sourceCompletionId`, e.g. a legacy out-of-band resume) cannot
+ *  be told apart from a redelivery of the reverted completion, so it is a no-op that leaves the tombstone
+ *  intact. Returns whether a row was revived. */
+async function reviveTombstonedDecision(
+  data: DataLayer,
+  prior: PrAdjudicationRow,
+  answer: string,
+  input: { prKey: string; adjudicatedBy: string | undefined; adjudicatedKind: string | undefined; expectedProcessKey?: string | undefined; sourceCompletionId?: number | undefined },
+): Promise<boolean> {
+  // Only a tombstoned row is revivable; a live row is owned by the INSERT-if-absent / blank→known heal.
+  if (prior.invalidated_at == null || prior.invalidated_at.trim() === "") return false;
+  const nowBy = input.adjudicatedBy?.trim();
+  if (!nowBy) return false;
+  // A revive requires a KNOWN, correlated completion. Without a `sourceCompletionId` we cannot tell a
+  // genuinely NEW answer from an at-least-once REDELIVERY of the reverted completion's own record-answer
+  // (a legacy/uncorrelated answer carries none) — so an uncorrelated answer never revives, keeping the
+  // revert durable (Copilot review of #806). A correlated completion is additionally fenced on NOT being
+  // reverted below, so a redelivery of the reverted completion itself still no-ops.
+  if (input.sourceCompletionId == null) return false;
+  const db = data.open();
+  const guard = generationGuard(input.prKey, input.expectedProcessKey);
+  const reviveGuard = firstHandRevivableGuard(input.sourceCompletionId);
+  const res = await db.exec(
+    `UPDATE "pr_adjudications" SET "answer" = ?, "adjudicated_by" = ?, "adjudicated_kind" = ?, "adjudicated_at" = ?, "source_completion_id" = ?, "invalidated_at" = NULL
+     WHERE "id" = ? AND "invalidated_at" IS NOT NULL AND ${guard.sql} AND ${reviveGuard.sql}`,
+    [answer, nowBy, input.adjudicatedKind?.trim() || null, new Date().toISOString(), input.sourceCompletionId ?? null, prior.id, ...guard.params, ...reviveGuard.params],
+  );
+  return res.changed > 0;
+}
+
+/** Promote an UNKNOWN-provenance adjudication row to a replayable decision (issue #806 review). The
+ *  prior answer could not be attributed, so auto-resume fails open and the question re-parks a human
+ *  every round; a now-known adjudicator's answer heals the row — its answer AND attribution together, so
+ *  the replayed decision is the human's, not the earlier uncorrelated one. Only heal blank→known: a row
+ *  that ALREADY carries known provenance is immutable (INSERT-if-absent preserves the ORIGINAL). A no-op
+ *  when the prior row is already attributed or the incoming answer is still unattributed.
+ *
+ *  The promotion is a CONDITIONAL compare-and-set — the `UPDATE … WHERE "adjudicated_by" IS NULL OR
+ *  TRIM("adjudicated_by") = ''` re-checks the blank precondition INSIDE the write, so of two concurrent
+ *  known healers that both read the same blank row only the FIRST promotes it; the second's guard is
+ *  already false and its update affects zero rows, leaving the first healer's answer/adjudicator intact
+ *  (Copilot review of #806 — a read-then-unconditional-update would let the later writer clobber the
+ *  earlier known decision). The write is ALSO fenced on the run generation so a pre-reset straggler
+ *  cannot heal after a re-submit reset. The promotion also carries the healing answer's winning
+ *  completion into `source_completion_id` (issue #806 review) so a later revert of that completion can
+ *  tombstone the promoted decision — see the compare-and-set below. */
+async function healBlankProvenance(
+  data: DataLayer,
+  prior: PrAdjudicationRow,
+  answer: string,
+  input: { prKey: string; adjudicatedBy: string | undefined; adjudicatedKind: string | undefined; expectedProcessKey?: string | undefined; sourceCompletionId?: number | undefined },
+): Promise<void> {
+  const priorBy = prior.adjudicated_by?.trim();
+  const nowBy = input.adjudicatedBy?.trim();
+  if (priorBy || !nowBy) return;
+  // Never resurrect a TOMBSTONED row (a human reverted the auto-apply that replayed it, issue #806
+  // review) — a redelivered `record-answer` must not heal a reverted decision back into a replayable
+  // one. The write is also fenced on `invalidated_at IS NULL` below so the check is atomic with it.
+  if (prior.invalidated_at != null && prior.invalidated_at.trim() !== "") return;
+  const db = data.open();
+  const guard = generationGuard(input.prKey, input.expectedProcessKey);
+  const revertGuard = notRevertedGuard(input.sourceCompletionId);
+  // Carry the healing answer's WINNING completion into `source_completion_id` in the SAME compare-and-set
+  // (issue #806 review): the promoted decision is now the known adjudicator's, so if that answer came from
+  // a reversible first-hand agent completion, `revertAgentCompletion` must be able to tombstone it via
+  // `invalidateAdjudicationByCompletion`. Without this, a healed row keeps a NULL link and a revert of the
+  // healing completion leaves the overridden answer replayable — the poller re-auto-applies it, silently
+  // undoing the human's revert (the exact failure mode the completion link exists to prevent). `COALESCE`
+  // stamps the healer's completion when present and otherwise preserves any existing link (an uncorrelated
+  // heal never NULLs a link the original first-hand winner recorded). The UPDATE is ALSO fenced on the
+  // healing completion NOT being reverted ({@link notRevertedGuard}) so a promotion cannot relink a live
+  // row to an already-reverted completion (issue #806 review, Copilot — the revert-before-record ordering
+  // applied to the blank→known heal, the mirror of the INSERT fence above).
+  await db.exec(
+    `UPDATE "pr_adjudications" SET "answer" = ?, "adjudicated_by" = ?, "adjudicated_kind" = ?, "adjudicated_at" = ?, "source_completion_id" = COALESCE(?, "source_completion_id")
+     WHERE "id" = ? AND ("adjudicated_by" IS NULL OR TRIM("adjudicated_by") = '') AND "invalidated_at" IS NULL AND ${guard.sql} AND ${revertGuard.sql}`,
+    [answer, nowBy, input.adjudicatedKind?.trim() || null, new Date().toISOString(), input.sourceCompletionId ?? null, prior.id, ...guard.params, ...revertGuard.params],
+  );
+}
+
+/** Atomically clear ALL durable adjudications for `prKey` — the fresh-run boundary invalidation
+ *  `submitPr` performs on reopen (issue #806, Copilot review). A SINGLE `DELETE … WHERE pr_key = ?`
+ *  rather than a row-by-row `Table.delete` loop, so a crash mid-reset can never leave a PARTIALLY
+ *  cleared memory (some questions still replayable, others gone) — the whole PR's memory is wiped in
+ *  one statement or not at all. The caller advances `pull_requests.process_key` to the new run BEFORE
+ *  calling this, so any straggler answer job from the retired run is already fenced (its
+ *  `expectedProcessKey` no longer matches) and cannot re-insert between the advance and this wipe. */
+export async function resetAdjudications(data: DataLayer, prKey: string): Promise<void> {
+  await data.open().exec(`DELETE FROM "pr_adjudications" WHERE "pr_key" = ?`, [prKey]);
+}
+
+/** Invalidate a single durable adjudication by surrogate `id` — the decision is no longer replayable,
+ *  so the next convergence round that re-derives the question re-parks a human (issue #806, Copilot
+ *  review). Called from `revertAgentCompletion` when a human reverts the AUTO-APPLIED completion that
+ *  replayed this adjudication: marking the `task_completions` row reverted alone would NOT stop the
+ *  poller — it matches the unchanged `pr_adjudications` row and replays the same overridden answer on
+ *  the next derived task, silently undoing the human's revert.
+ *
+ *  Sets a TOMBSTONE (`invalidated_at`) rather than DELETING the row. A DELETE is NOT race-safe: the
+ *  reverted completion's `record-answer` job can be redelivered (at-least-once) AFTER the delete and
+ *  re-insert the SAME `(pr_key, question_fingerprint)` — its `generationGuard` still passes (a revert
+ *  does not advance the run generation), so the row comes back and the next poller pass re-auto-applies,
+ *  undoing the revert (Copilot review of #806). Keeping the row as a tombstone means that redelivered
+ *  insert trips the `UNIQUE (pr_key, question_fingerprint)` fence (a no-op) and `recordAdjudication` will
+ *  not resurrect it for the SAME reverted completion (its `notRevertedGuard` is false), while
+ *  `matchAdjudication` skips it — so the revert is a durable override. (A genuinely NEW, non-reverted
+ *  answer to the re-parked question does revive the tombstone via {@link reviveTombstonedDecision}, so
+ *  the human's follow-up decision is remembered.) The original decision's audit survives on the reverted
+ *  completion ledger row and on this tombstoned row.
+ *  Conditional on `invalidated_at IS NULL` so it is idempotent (a second revert/reset is a no-op) and
+ *  never overwrites the first invalidation time. The tombstone is cleared only by `resetAdjudications`
+ *  on a fresh-run re-submit. */
+export async function invalidateAdjudication(data: DataLayer, id: number, on?: GatewayDataSource): Promise<void> {
+  await (on ?? data.open()).exec(
+    `UPDATE "pr_adjudications" SET "invalidated_at" = ? WHERE "id" = ? AND "invalidated_at" IS NULL`,
+    [new Date().toISOString(), id],
+  );
+}
+
+/** TOMBSTONE the adjudication produced by a specific WINNING completion (issue #806 review), keyed on
+ *  `source_completion_id`. This is the FIRST-HAND agent-answer counterpart to {@link invalidateAdjudication}:
+ *  a first-hand agent completion of a `wait-answer` records its own adjudication with `auto_applied=0` and
+ *  NO `source_adjudication_id`, so reverting it cannot find the decision by adjudication id — it must be
+ *  found by the completion that created it. Without this the reverted answer stays live and the poller
+ *  re-auto-applies it, silently undoing the human's revert. Tombstones (does not DELETE) for the same
+ *  race-safety reason as {@link invalidateAdjudication}, and is conditional on `invalidated_at IS NULL`
+ *  so it is idempotent — a retry after a partial revert is a safe no-op. A completion settles at most one
+ *  question, so at most one row matches; a completion with no linked adjudication matches none (no-op). */
+export async function invalidateAdjudicationByCompletion(data: DataLayer, completionId: number, on?: GatewayDataSource): Promise<void> {
+  await (on ?? data.open()).exec(
+    `UPDATE "pr_adjudications" SET "invalidated_at" = ? WHERE "source_completion_id" = ? AND "invalidated_at" IS NULL`,
+    [new Date().toISOString(), completionId],
+  );
+}