@bongos/core 1.19.812 → 1.19.814

package/modules/lifecycle/abandon-authz.js

@@ -0,0 +1,132 @@
+// modules/lifecycle/abandon-authz.js — the PURE authorization decision behind
+// POST /tasks/:id/abandon: may THIS builder retire THIS task, right now?
+//
+// WHY IT IS ITS OWN FILE. Two authorities reach that transition and only one of
+// them is rank-shaped (ADR 0297):
+//
+//   • `task.abandon` (floor metic) — retire ANY task. Triage authority; the
+//     inverse of /promote, re-ranked to match it (ADR 0152).
+//   • `task.abandon.own` (floor xenos) — retire a task you CREATED, while it is
+//     still backlog/ready/blocked. The owner's 2026-07-25 request: "the creator
+//     of that task should be able to abandon that task directly inside of the
+//     UI." A predicate over tasks.created_by, which no rank floor can express —
+//     the ADR 0151 ownership axis.
+//
+// The second one is a rule about a ROW, so it cannot be a middleware and it must
+// not be re-derived at each call site. Carving it out follows the
+// goal-route-authz.js / shouldRefuseSessionClaim precedent: PURE and exported, so
+// every branch is pinned by a DB-free unit test instead of only through a live
+// route, and so the hall's display hint and the server's decision are provably
+// reading the same rule.
+//
+// PURE — no DB, no clock, no I/O. The caller resolves the RANK fact before its
+// transaction opens (request-scoped, uncached, ADR 0016) and supplies the ROW
+// fact from inside its FOR UPDATE lock. Splitting them is what makes the decision
+// both fresh and race-free: reading created_by outside the lock would be a TOCTOU
+// window, and resolving permissions inside it would hold a row lock across a
+// second pool acquire.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway.
+
+'use strict';
+
+// The statuses a CREATOR may retire their own task in. Deliberately the
+// not-yet-started, not-yet-judged window:
+//   • backlog / ready / blocked — the task is still a plan. Retiring it is the
+//     author withdrawing their own proposal, which is what the owner asked for.
+//   • active   — excluded here AND by the active-claim guard in abandonTask: a
+//     live claim means a session still owns the work.
+//   • completed / confirmed — excluded ON PURPOSE. Past the grader a retire is a
+//     correction to the ledger, not an author changing their mind, so it stays
+//     with the cross-owner `task.abandon` authority.
+//   • shipped / abandoned — never reached from here; abandonTask refuses shipped
+//     outright and treats abandoned as an idempotent no-op.
+const CREATOR_ABANDONABLE = Object.freeze(['backlog', 'ready', 'blocked']);
+
+// The permission pair this decision is spelled in, exported so the route, the
+// tests and the denial text all name the same two atoms.
+const ABANDON_ANY_KEY = 'task.abandon';
+const ABANDON_OWN_KEY = 'task.abandon.own';
+
+// Does this builder hold enough to be worth locking the row for? The cheap
+// pre-transaction half: `false` here is a flat 403 and no transaction is opened.
+// Holding only the own-scoped key is NOT an admit — it is permission to be ASKED
+// the ownership question, which is the whole point of the `.own` axis.
+function mayAttemptAbandon({ holdsAny = false, holdsOwn = false } = {}) {
+  return holdsAny === true || holdsOwn === true;
+}
+
+// The row-scoped verdict. ORDERED and FAIL-CLOSED — every path that is not an
+// explicit admit returns { ok: false } with a reason the caller can map to a
+// refusal, and the default at the bottom denies rather than falls through.
+//
+// `sameOwner` is INJECTED rather than hand-rolled: Postgres hands bigints back as
+// strings and JS code carries them as numbers, so 7 and '7' must compare equal
+// while null, '', objects and NaN must match nothing. That normalization already
+// exists once, in the government resolver, and duplicating it here is exactly how
+// an ownership comparison quietly widens. A caller that supplies no comparator
+// gets a strict scalar fallback with the same posture — never a loose `==`.
+function strictSameOwner(a, b) {
+  const norm = (v) => {
+    if (typeof v === 'number') return Number.isFinite(v) ? String(v) : null;
+    if (typeof v === 'bigint') return String(v);
+    if (typeof v === 'string') return v === '' ? null : v;
+    return null;
+  };
+  const left = norm(a);
+  const right = norm(b);
+  return left !== null && right !== null && left === right;
+}
+
+function abandonVerdict({
+  holdsAny = false,
+  holdsOwn = false,
+  builderId = null,
+  createdBy = null,
+  status = null,
+  sameOwner = strictSameOwner,
+} = {}) {
+  // The cross-owner branch: reaches every creator's row, so no predicate applies.
+  // Checked FIRST so a Metic+ is never refused by the creator-only window below —
+  // their authority is wider, not narrower.
+  if (holdsAny === true) return { ok: true, via: ABANDON_ANY_KEY };
+
+  if (holdsOwn !== true) {
+    return {
+      ok: false,
+      reason: 'missing_permission',
+      message: `missing permission: ${ABANDON_ANY_KEY} (floor: metic), or ${ABANDON_OWN_KEY} on a task you created`,
+    };
+  }
+
+  // An own-scoped key is never sufficient on its own — it is half a question, and
+  // this is the other half. A null created_by (every task filed before core_227,
+  // and every system vector) matches nobody, by construction.
+  const compare = typeof sameOwner === 'function' ? sameOwner : strictSameOwner;
+  if (!compare(createdBy, builderId)) {
+    return {
+      ok: false,
+      reason: 'not_task_creator',
+      message: `you did not create this task — retiring someone else's task needs ${ABANDON_ANY_KEY} (floor: metic)`,
+    };
+  }
+
+  if (!CREATOR_ABANDONABLE.includes(String(status))) {
+    return {
+      ok: false,
+      reason: 'creator_status_not_abandonable',
+      message: `this task is '${status}' — a creator can retire their own task only while it is ${CREATOR_ABANDONABLE.join(', ')}; past that it needs ${ABANDON_ANY_KEY} (floor: metic)`,
+    };
+  }
+
+  return { ok: true, via: ABANDON_OWN_KEY };
+}
+
+module.exports = {
+  CREATOR_ABANDONABLE,
+  ABANDON_ANY_KEY,
+  ABANDON_OWN_KEY,
+  mayAttemptAbandon,
+  abandonVerdict,
+  strictSameOwner,
+};

package/modules/lifecycle/db-executor.js

@@ -0,0 +1,45 @@
+'use strict';
+
+// modules/lifecycle/db-executor.js — which thing runs the query (task 1003840).
+//
+// WHY THIS IS ONE FUNCTION AND NOT SEVEN COPIES. Every read in this module family
+// already carried the same hand-written line:
+//
+//   const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+//
+// Threading a transaction client through the criterion surface meant editing that
+// line in seven files. A rule about WHICH connection a write lands on is exactly
+// the rule you do not want seven copies of: get one wrong and a write silently
+// leaves the transaction it was supposed to be inside, which is invisible in
+// review and invisible at runtime until a race loses.
+//
+// THE ORDER MATTERS, and it is not the same for the two seams:
+//
+//   1. `deps.client` — a real transaction client, honoured ALWAYS. It is
+//      production behaviour, not a test affordance: when a caller has opened a
+//      transaction, every statement in that unit of work must run on that client
+//      or it is not in the transaction at all.
+//   2. `deps.pool` — the #538 test seam, honoured ONLY under NODE_ENV==='test',
+//      exactly as before. Unchanged so a stray deps.pool in production code still
+//      cannot redirect a write.
+//   3. the module's own pool — the default, unchanged.
+//
+// A caller that passes both gets the client, because the transaction is the
+// stronger claim.
+
+function executorFor(deps, defaultPool) {
+  if (deps && deps.client) return deps.client;
+  if (deps && deps.pool && process.env.NODE_ENV === 'test') return deps.pool;
+  return defaultPool;
+}
+
+// True when the caller is inside a transaction, which is the only place a row
+// lock means anything: `SELECT ... FOR UPDATE` on the pool takes a lock and
+// releases it on the next statement, so asking for one outside a transaction is
+// a false sense of safety rather than a cheap extra. Callers use this to refuse
+// rather than to silently downgrade.
+function inTransaction(deps) {
+  return Boolean(deps && deps.client);
+}
+
+module.exports = { executorFor, inTransaction };

package/modules/lifecycle/db-goals.js

@@ -17,6 +17,7 @@ const { deriveRequiredRank, highestRank } = require('./db-rank-authz.js');
 const { nonTerminalSql, isTerminalStatus } = require('./task-status');
 const { maintenanceGoalTitle } = require('./goal-advisory.js');
 const { SMOKE_NOT_LIKE } = require('./db-shared.js');
+const { executorFor, inTransaction } = require('./db-executor.js');
 // BV1.R16 (task 1003603) — auto-close, shared with the done-when cascade so the
 // two achievement writers cannot drift apart (ADR 0263 §4).
 const { autoCloseVersionsForGoals } = require('./version-autoclose.js');
@@ -325,10 +326,22 @@ async function getGoalAdmission(goalId, deps = {}) {
 }
 
 
+// deps.client runs the read inside a caller's transaction; deps.forUpdate adds the
+// row lock (task 1003840). The lock is what actually closes the criterion routes'
+// check-then-write window: without it, re-reading inside the transaction still sees
+// a row another transaction is free to change before the write lands.
+//
+// forUpdate REFUSES outside a transaction rather than quietly dropping to a plain
+// read. FOR UPDATE on a pooled connection takes a lock and releases it at the end
+// of that implicit statement, so the caller would hold nothing while believing it
+// held something — the precise false sense of safety this task exists to remove.
 async function getGoal(id, deps = {}) {
-  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const activePool = executorFor(deps, pool);
+  if (deps.forUpdate && !inTransaction(deps)) {
+    throw new Error('getGoal({ forUpdate }) requires deps.client — a row lock outside a transaction holds nothing');
+  }
   const { rows } = await activePool.query(
-    `SELECT ${GOAL_COLS} FROM goals WHERE id = $1`,
+    `SELECT ${GOAL_COLS} FROM goals WHERE id = $1${deps.forUpdate ? ' FOR UPDATE' : ''}`,
     [id]
   );
   return rows[0] ?? null;
@@ -444,8 +457,15 @@ async function reorderGoals({ versionId, orderedIds }, deps = {}) {
 // the auto-achieve + archive/reopen on top). Bumps updated_at. Returns null if
 // the goal id is unknown.
 
+// THE WRITE achieveGoalIfComplete DELEGATES TO, so it must honour deps.client or
+// the auto-achieve leaves the caller's transaction (found in review of task
+// 1003840's first cut, where it was missed). Against real Postgres that is not
+// merely untransacted, it SELF-DEADLOCKS: the criterion route holds this goal row
+// FOR UPDATE on its transaction client, and this UPDATE on a pool connection
+// blocks on that lock — while the transaction is awaiting this UPDATE before it
+// can COMMIT and release it. Neither side can move.
 async function setGoalStatus({ goalId, status }, deps = {}) {
-  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const activePool = executorFor(deps, pool);
   const { rows } = await activePool.query(
     `UPDATE goals
         SET status = $2, updated_at = now()
@@ -467,8 +487,10 @@ async function setGoalStatus({ goalId, status }, deps = {}) {
 // siblings, so the flip logic is unit-testable with a fake client.
 
 async function achieveGoalIfComplete({ goalId }, deps = {}) {
-  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
-  const goal = await getGoal(goalId, deps);
+  const activePool = executorFor(deps, pool);
+  // The nested getGoal must NOT inherit forUpdate — this is a re-derive, not the
+  // authority read, and locking here would widen the transaction for no gain.
+  const goal = await getGoal(goalId, { ...deps, forUpdate: false });
   // Only an OPEN goal can auto-achieve. An already achieved/archived goal is left
   // exactly as-is — re-confirming a criterion must not churn its status.
   if (!goal || goal.status !== 'open') return { achieved: false, goal: goal ?? null };
@@ -512,7 +534,7 @@ async function achieveGoalIfComplete({ goalId }, deps = {}) {
   //
   // Runs on the caller's exec so it sees the flip above, which in the ship path is
   // still uncommitted. Never throws: autoCloseVersionsForGoals catches per version.
-  const exec = deps.client || ((deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool);
+  const exec = executorFor(deps, pool);
   const versionsClosed = await autoCloseVersionsForGoals(exec, [updated]);
   return { achieved: true, goal: updated, versionsClosed };
 }
@@ -829,7 +851,7 @@ async function isGoalMember({ goalId, builderId }, deps = {}) {
 // isGoalMember boolean.
 
 async function getGoalMember({ goalId, builderId }, deps = {}) {
-  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const activePool = executorFor(deps, pool);
   const { rows } = await activePool.query(
     `SELECT goal_id, builder_id, membership_kind, joined_at
        FROM goal_members

package/modules/lifecycle/db-ship.js

@@ -953,9 +953,39 @@ async function confirmTask({ taskId, builderId }, deps = {}) {
 //                           still owns the work; release it first so the abandon
 //                           can never race a ship in flight.
 // Any other status (backlog/ready/blocked/completed/confirmed) abandons. The
-// route is metic+archon-gated (ADR 0152; archon-only until then), and the abandon
-// + its reason are captured in audit_log by the writing middleware, so the
-// append-only ledger records who retired what. restoreTask (below) is the undo.
+// route carries the authority gate (ADR 0152, and the creator widening of task
+// 1002443), and the abandon + its reason are captured in audit_log by the writing
+// middleware, so the append-only ledger records who retired what. restoreTask
+// (below) is the undo.
+//
+// `authorize` (task 1002443) — the OPTIONAL row-scoped veto, and the reason this
+// function grew a parameter rather than the route growing a pre-flight read.
+//
+// The owner's 2026-07-25 request widened this transition from "a Metic may retire
+// any task" to "...or a builder may retire a task THEY created". That second half
+// is a predicate over a COLUMN OF THIS ROW (tasks.created_by), so a check made
+// before the transaction would be a TOCTOU window: the row can be re-attributed,
+// claimed, or shipped between the read and the write. The callback therefore runs
+// INSIDE the transaction, against the row this function has already locked FOR
+// UPDATE, and its verdict and the UPDATE commit or roll back together.
+//
+// It is deliberately PURE and DB-FREE. The authority question splits in two (the
+// ADR 0151 ownership axis): the RANK fact — does this builder hold the key — is
+// request-scoped and is resolved by the caller BEFORE the transaction opens; only
+// the OWNER fact needs the lock. Resolving permissions in here would acquire a
+// second pool connection while holding a row lock, which under a saturated pool is
+// a deadlock. So the caller closes over its already-resolved grants and hands in a
+// predicate; this function supplies the row.
+//
+// Contract: called with { taskId, createdBy, status }, returns { ok: true } or
+// { ok: false, reason, message }. FAIL-CLOSED — anything that is not an explicit
+// { ok: true } is a refusal, so a caller that returns undefined (or throws) denies
+// rather than admits. Omitting `authorize` entirely preserves the pre-1002443
+// behaviour for every caller whose route already gated the transition.
+//
+// It runs BEFORE the already-abandoned idempotent return, deliberately: a caller
+// with no authority over this row must not be able to read its state back as a
+// 200, and an unauthorized retry is a refusal, not a no-op.
 //
 // NOTE on dependencies: abandoning a task that is listed in another task's
 // dependencies[] does NOT auto-adjust those dependents — they will simply never
@@ -967,14 +997,16 @@ async function confirmTask({ taskId, builderId }, deps = {}) {
 // so a regression test can drive the txn with a SQL-aware fakeClient, same as
 // confirmTask / decideOverrideRequest. Production callers omit deps → module pool.
 
-async function abandonTask({ taskId, reason }, deps = {}) {
+async function abandonTask({ taskId, reason, authorize = null }, deps = {}) {
   const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
   const client = await activePool.connect();
   try {
     await client.query('BEGIN');
 
+    // created_by joins the locked SELECT (task 1002443) so the ownership predicate
+    // below reads the SAME row version the UPDATE will write.
     const { rows: taskRows } = await client.query(
-      `SELECT id, title, status FROM tasks WHERE id = $1 FOR UPDATE`,
+      `SELECT id, title, status, created_by FROM tasks WHERE id = $1 FOR UPDATE`,
       [taskId]
     );
     if (taskRows.length === 0) {
@@ -982,6 +1014,28 @@ async function abandonTask({ taskId, reason }, deps = {}) {
     }
     const task = taskRows[0];
 
+    // The row-scoped veto, under the lock and ahead of every status branch below —
+    // see the header for why both of those orderings are load-bearing. Fail-closed:
+    // only an explicit { ok: true } admits.
+    if (typeof authorize === 'function') {
+      let verdict;
+      try {
+        verdict = await authorize({ taskId, createdBy: task.created_by, status: task.status });
+      } catch (authErr) {
+        throw Object.assign(new Error('abandon authorization could not be established'), {
+          code: 'ABANDON_FORBIDDEN',
+          reason: 'authorize_threw',
+          cause: authErr,
+        });
+      }
+      if (!verdict || verdict.ok !== true) {
+        throw Object.assign(new Error((verdict && verdict.message) || 'not authorized to abandon this task'), {
+          code: 'ABANDON_FORBIDDEN',
+          reason: (verdict && verdict.reason) || 'not_authorized',
+        });
+      }
+    }
+
     if (task.status === 'abandoned') {
       await client.query('COMMIT');
       return { taskId, taskTitle: task.title, taskStatus: 'abandoned', previousStatus: 'abandoned', alreadyAbandoned: true };

package/modules/lifecycle/db-tasks.js

@@ -17,6 +17,7 @@ const { generalGoalTitle } = require('./goal-advisory.js');
 const { matchProtected } = api.permissionPathCheck;
 const { decorateGoalMembership, capNewcomerTasks } = require('./claim-feed.js');
 const { deriveRequiredRank, highestRank } = require('./db-rank-authz.js');
+const { executorFor } = require('./db-executor.js');
 
 // -------------------------------------------------------------------------
 // Tasks
@@ -334,16 +335,21 @@ async function updateTaskColumn(id, column, value) {
 // planning session uses. sort_order defaults to max(existing)+1 (mirrors the
 // criterion-proposal ratify path). Throws 23505 on a duplicate (version_id,
 // criterion_id) — the route maps that to 409.
-async function createCriterion({ versionId, criterionId, criterionMd, goalId = null, sortOrder = null }) {
+// deps.client threads the caller's transaction (task 1003840). BOTH statements
+// below must run on it: the MAX(sort_order) read and the INSERT that depends on
+// it are one decision, and splitting them across connections reopens a narrower
+// version of the same race — two creates reading the same next order.
+async function createCriterion({ versionId, criterionId, criterionMd, goalId = null, sortOrder = null }, deps = {}) {
+  const executor = executorFor(deps, pool);
   let order = sortOrder;
   if (order == null) {
-    const { rows: maxRows } = await pool.query(
+    const { rows: maxRows } = await executor.query(
       `SELECT COALESCE(MAX(sort_order), 0) + 1 AS next FROM done_when_criteria WHERE version_id = $1`,
       [versionId]
     );
     order = maxRows[0].next;
   }
-  const { rows } = await pool.query(
+  const { rows } = await executor.query(
     `INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, goal_id, sort_order)
      VALUES ($1, $2, $3, $4, $5)
      RETURNING id, version_id, criterion_id, criterion_md, goal_id, sort_order, satisfied`,
@@ -364,8 +370,8 @@ async function createCriterion({ versionId, criterionId, criterionMd, goalId = n
 // question this raises — that the goal exists and sits on the criterion's own
 // version, who may write it, and whether the move completes the goal; this is the
 // UPDATE and nothing else, exactly as updateTaskGoal below is for tasks.
-async function updateCriterionGoal(id, goalId) {
-  const { rows } = await pool.query(
+async function updateCriterionGoal(id, goalId, deps = {}) {
+  const { rows } = await executorFor(deps, pool).query(
     `UPDATE done_when_criteria SET goal_id = $1 WHERE id = $2
      RETURNING id, version_id, criterion_id, criterion_md, goal_id, sort_order, satisfied`,
     [goalId, id]

package/modules/lifecycle/db-versions.js

@@ -15,6 +15,7 @@ const { pool, withTx } = api;
 const doneWhen = require('./done-when.js');
 const { nonTerminalSql } = require('./task-status');
 const { SMOKE_NOT_LIKE } = require('./db-shared.js');
+const { executorFor, inTransaction } = require('./db-executor.js');
 // db-goals.js does NOT require this file, so this direction adds no require cycle
 // (fitness pins the count). createVersion needs it to seed a version's FIRST goal
 // in the same transaction — task 1003701.
@@ -30,10 +31,23 @@ async function listVersions() {
 }
 
 
-async function getVersion(id) {
-  const { rows } = await pool.query(
+// deps.client/deps.pool, so the criterion routes can read the version inside the
+// same transaction that authorizes and writes (task 1003840). A version's status
+// is one of the facts the decision rests on — reading it on a different connection
+// is reading it at a different instant.
+async function getVersion(id, deps = {}) {
+  // deps.forUpdate locks the version row too (task 1003840, round 2). The goal
+  // lock alone left one of the three named facts unguarded: closeVersion takes
+  // FOR UPDATE on this row, but under READ COMMITTED a PLAIN read is never
+  // blocked by another session's lock — so a freeze could still commit between
+  // this read and this transaction's COMMIT, and the criterion would land on a
+  // version that had closed. Locking makes the two serialize.
+  if (deps.forUpdate && !inTransaction(deps)) {
+    throw new Error('getVersion({ forUpdate }) requires deps.client — a row lock outside a transaction holds nothing');
+  }
+  const { rows } = await executorFor(deps, pool).query(
     `SELECT id, name, track, status, scope_doc_path, started_at, shipped_at, done_when
-       FROM versions WHERE id = $1`,
+       FROM versions WHERE id = $1${deps.forUpdate ? ' FOR UPDATE' : ''}`,
     [id]
   );
   return rows[0] ?? null;

package/modules/lifecycle/done-when.js

@@ -26,6 +26,7 @@
 const { pool } = require('../../src/module-api');
 const { nonTerminalSql } = require('./task-status');
 const { SMOKE_NOT_LIKE } = require('./db-shared.js');
+const { executorFor } = require('./db-executor.js');
 // BV1.R16 (task 1003603) — auto-close. Dependency-free module, so requiring it
 // here creates no cycle (db-versions.js requires THIS file, which is why the
 // rule could not live beside closeVersion).
@@ -101,10 +102,12 @@ async function criteriaGroupedByGoal(versionId) {
 // Fetch a single criterion by primary key. Used by the routes to validate
 // existence before writing (so a missing id returns 404 instead of a silent
 // no-op UPDATE).
-async function getCriterion(criterionId) {
+// deps.client so the PATCH route can read the criterion inside its transaction
+// (task 1003840) — its goal_id is the fact the authority decision rests on.
+async function getCriterion(criterionId, deps = {}) {
   const id = Number(criterionId);
   if (!Number.isFinite(id)) return null;
-  const { rows } = await pool.query(
+  const { rows } = await executorFor(deps, pool).query(
     `SELECT id, version_id, criterion_id, criterion_md, satisfied,
             satisfied_by_task_id, checked_at, sort_order, goal_id
        FROM done_when_criteria

package/modules/lifecycle/goal-edits.js

@@ -23,6 +23,7 @@
 // correction is a cohesive slice — the goal-authz.js / claim-feed.js precedent.
 
 const api = require('../../src/module-api');
+const { executorFor } = require('./db-executor.js');
 const { pool } = api;
 
 // ---------------------------------------------------------------------------
@@ -119,7 +120,10 @@ async function updateGoalProse({ goalId, patch = {} }, deps = {}) {
 // (criterionProseRefusal) so the route can answer 404 vs 409 distinctly; this
 // only writes. Returns { criterion, deltas } or null when it vanished mid-flight.
 async function updateCriterionProse({ criterionId, criterionMd }, deps = {}) {
-  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  // Read-then-write in its own right: the before-value it captures for the audit
+  // delta must come from the same transaction as the UPDATE, or the recorded
+  // "before" can be a value that was already gone (task 1003840).
+  const activePool = executorFor(deps, pool);
   const { rows: before } = await activePool.query(
     `SELECT id, criterion_md, satisfied FROM done_when_criteria WHERE id = $1`,
     [criterionId]

package/modules/lifecycle/routes/abandon-handler.js

@@ -0,0 +1,151 @@
+// modules/lifecycle/routes/abandon-handler.js — the HTTP half of
+// POST /tasks/:id/abandon: resolve the caller's authority, compose it with the
+// row-scoped decision, and map every refusal to its status code.
+//
+// WHY IT IS ITS OWN FILE. Two reasons, and the second is the real one:
+//
+//   1. tasks.js sits against the 1,500-line ratchet, and this handler grew when
+//      the route gained a second authority (task 1002443 / ADR 0297) — the same
+//      pressure that carved goal-route-authz.js out of goals.js.
+//   2. COMPOSITION is where this route can go wrong, and composition was the one
+//      layer no test could reach. `abandon-authz.js` pins the decision and
+//      `abandonTask` pins the transaction seam, both in isolation; a mistake in
+//      how the route wires them together — mapping a refusal to the wrong code,
+//      admitting when the government port is absent, reporting a denial that
+//      names the wrong atom — would have passed both. A plain exported function
+//      taking `{ req, res, deps }` is callable from a test with fakes, so that
+//      layer is now pinned too (tests/abandon_route.mjs).
+//
+// Everything it needs is INJECTED rather than imported: the router hands in its
+// own `db`, `governance` port, logger and validators. That is what makes the
+// handler testable without a live Express app or a DB, and it keeps the module
+// boundary intact — this file requires no core internal.
+
+'use strict';
+
+const abandonAuthz = require('../abandon-authz');
+
+// The atoms a denial should name. Both are a genuine way in, so a 403 that listed
+// only the metic-floor key would send a creator after the wrong permission.
+function requiredAtoms(governance) {
+  // The cross-owner escalation path is a DECLARED property of the own-scoped key
+  // (task 1003195), read from the catalog rather than hardcoded, so a change to
+  // that declaration reaches this route instead of silently disagreeing with it.
+  // Falls back to the named atom only when the port cannot answer — a catalog that
+  // has moved on must never be able to WIDEN this gate.
+  const declared = (governance && typeof governance.crossOwnerKeysFor === 'function')
+    ? governance.crossOwnerKeysFor(abandonAuthz.ABANDON_OWN_KEY)
+    : null;
+  const crossOwner = (Array.isArray(declared) && declared.length > 0)
+    ? declared
+    : [abandonAuthz.ABANDON_ANY_KEY];
+  return { crossOwner, required: [...crossOwner, abandonAuthz.ABANDON_OWN_KEY] };
+}
+
+// Floors resolve through the port at deny time, never hardcoded prose — a floor
+// that moves would otherwise leave a lie in the denial.
+function floorsFor(governance, keys) {
+  const out = {};
+  if (!governance || typeof governance.permissionFloor !== 'function') return out;
+  for (const k of keys) {
+    try {
+      const f = governance.permissionFloor(k);
+      if (f) out[k] = f;
+    } catch (_) { /* unknown atom — omit rather than guess */ }
+  }
+  return out;
+}
+
+// deps: { db, seams, log, validateOrRespond, parseId }
+function makeAbandonHandler(deps) {
+  const { db, seams, log, validateOrRespond, parseId } = deps;
+
+  return async function abandonHandler(req, res) {
+    if (validateOrRespond(req, res, {
+      reason: { type: 'string' },  // free-text retire reason (sliced to 2000 below)
+    })) return;
+    const id = parseId(req, res, { code: 'bad_task_id', positiveInt: true });
+    if (id === null) return;
+    const reason = typeof req.body?.reason === 'string' ? req.body.reason.slice(0, 2000) : '';
+
+    // FAIL-CLOSED on a missing government port, exactly as auth.requirePermission
+    // does: `government` is a core-domain, default:true module, so its absence means
+    // authority cannot be ESTABLISHED — and admitting there would make disabling a
+    // module a privilege escalation, the inversion ADR 0016 exists to prevent.
+    const governance = seams.resolveOptional('government');
+    const { crossOwner, required } = requiredAtoms(governance);
+    const denyUnestablished = () => res.fail('permission_forbidden', {
+      status: 403,
+      message: 'authority could not be established — denied fail-closed (ADR 0016); this route requires '
+        + `${crossOwner.join(', ')}, or ${abandonAuthz.ABANDON_OWN_KEY} on a task you created`,
+      details: { required, held: null, floors: null },
+    });
+    if (!governance || typeof governance.resolveBuilderPermissions !== 'function'
+        || typeof governance.sameOwner !== 'function') {
+      return denyUnestablished();
+    }
+    let held;
+    try {
+      held = new Set(await governance.resolveBuilderPermissions(req.builder.id));
+    } catch (permErr) {
+      log.error('[gds] POST /tasks/:id/abandon — permission resolve', permErr);
+      return denyUnestablished();
+    }
+
+    const holdsAny = crossOwner.some((k) => held.has(k));
+    // Necessary but NEVER sufficient: holding the own-scoped key is permission to be
+    // ASKED the ownership question, answered against the locked row below.
+    const holdsOwn = held.has(abandonAuthz.ABANDON_OWN_KEY);
+    const denyPermission = (message, reasonCode) => res.fail('permission_forbidden', {
+      status: 403,
+      message,
+      details: {
+        required,
+        held: required.filter((k) => held.has(k)),
+        floors: floorsFor(governance, required),
+        ...(reasonCode ? { reason: reasonCode } : {}),
+      },
+    });
+
+    // The cheap half — refuse without opening a transaction at all.
+    if (!abandonAuthz.mayAttemptAbandon({ holdsAny, holdsOwn })) {
+      return denyPermission(abandonAuthz.abandonVerdict({ holdsAny, holdsOwn }).message, null);
+    }
+
+    try {
+      const result = await db.abandonTask({
+        taskId: id,
+        reason,
+        // PURE and DB-free — closes over the grants resolved above and is handed the
+        // row under abandonTask's own lock. See that function's header, and
+        // abandon-authz.js for the decision itself.
+        authorize: ({ createdBy, status }) => abandonAuthz.abandonVerdict({
+          holdsAny,
+          holdsOwn,
+          builderId: req.builder.id,
+          createdBy,
+          status,
+          // The government resolver's own id normalization — never re-implemented
+          // here, because a duplicated owner comparison is how one quietly widens.
+          sameOwner: governance.sameOwner,
+        }),
+      });
+      res.json({ ok: true, ...result });
+    } catch (err) {
+      if (err.code === 'ABANDON_FORBIDDEN') {
+        return denyPermission(err.message, err.reason || null);
+      }
+      if (err.code === 'TASK_NOT_FOUND') return res.fail('task_not_found', 404);
+      if (err.code === 'CANNOT_ABANDON_SHIPPED') {
+        return res.fail('cannot_abandon_shipped', { status: 409, message: 'shipped tasks are immutable history' });
+      }
+      if (err.code === 'TASK_HAS_ACTIVE_CLAIM') {
+        return res.fail('task_has_active_claim', { status: 409, message: 'release the active claim before abandoning' });
+      }
+      log.error('[gds] POST /tasks/:id/abandon', err);
+      res.fail('abandon_failed', { status: 500, message: 'internal error' });
+    }
+  };
+}
+
+module.exports = { makeAbandonHandler, requiredAtoms, floorsFor };