@bongos/core 1.19.812 → 1.19.813

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.812",
-  "core_contract": "1.19.812",
-  "source_commit": "b0747d044e08c53ffda8cc93bceafef59787e27a",
+  "core_version": "1.19.813",
+  "core_contract": "1.19.813",
+  "source_commit": "62a2b5a5f9bb96162fdb7d1be299d9fd50b6f7e3",
   "source_ref": "HEAD",
-  "built_at": "2026-09-17T06:53:39.832Z",
+  "built_at": "2026-09-17T07:11:52.940Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 488,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2208,
+    "functional_verbatim": 2209,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2722,
-  "tree_sha256": "7ce723b60b68f0cb665f81b47e71bdcec72bd1ddc5fe8c4e22c9ad0a07b79440",
+  "file_count": 2723,
+  "tree_sha256": "911e2248028f57d2233c75dde64c923ba2cb3642f6aa99b8607b405bd8ca9b03",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2537,7 +2537,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "3478aad2e6df54281dea8fcab1695cb6f943da2d3b9f5fe2ca9a6ec902061d5b"
+      "sha256": "d3749c214cb091b1df2679417ab828c6f9989c62592fe213d06c2d0365ec781b"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5534,10 +5534,15 @@
       "mode": "0000644",
       "sha256": "76ffab3052ce0b48d0b78451a2e34d5cd3c5300410f0856b4a6667cbe708ba2b"
     },
+    {
+      "path": "modules/lifecycle/db-executor.js",
+      "mode": "0000644",
+      "sha256": "b810e4488b35fe70508cae1c6583112033def4726d71af2e7efc7b18c495ba27"
+    },
     {
       "path": "modules/lifecycle/db-goals.js",
       "mode": "0000644",
-      "sha256": "2d9b4d62072ec588446d8098a08a2a300df42fa93e62b39086e80da1a95f1141"
+      "sha256": "b4d1c8bd2254f93519a88302072c2f524a1acb4152382fb09bdc22b1ef95f0ed"
     },
     {
       "path": "modules/lifecycle/db-grade.js",
@@ -5567,12 +5572,12 @@
     {
       "path": "modules/lifecycle/db-tasks.js",
       "mode": "0000644",
-      "sha256": "b26ba2c82bea0ee71e3db888bf531cee605aac90fa5ded2bcffe548cce650f4f"
+      "sha256": "87b075187493e8026f99912dceb7195d09564bfe3f969f344141661c60ef6558"
     },
     {
       "path": "modules/lifecycle/db-versions.js",
       "mode": "0000644",
-      "sha256": "7eaaafc9414bf77c12c57eefde02ddf1c67601f4b6b15ded3692bc3765ac036b"
+      "sha256": "4b0681bf2bc7cd40a0a7bcdc9d2fab033c735390555be54b0a1083e5fa231abd"
     },
     {
       "path": "modules/lifecycle/db.js",
@@ -5587,7 +5592,7 @@
     {
       "path": "modules/lifecycle/done-when.js",
       "mode": "0000644",
-      "sha256": "186a830fbb63ff5510af78ba4fe77cd94325571eed2809ace7817c66fb4155ba"
+      "sha256": "200e7c0937fefb97703927a699bff40b9c5061fae29c6779b998542a00724a22"
     },
     {
       "path": "modules/lifecycle/est-advisory.js",
@@ -5627,7 +5632,7 @@
     {
       "path": "modules/lifecycle/goal-edits.js",
       "mode": "0000644",
-      "sha256": "f00d1bb6bd57624679295f33d55ad1d81a9479789a78d4325f13948b9559f9f5"
+      "sha256": "c22a0782ddf7a93deb40f700a2afab15a313925647bbdf424db777da5aa29aa1"
     },
     {
       "path": "modules/lifecycle/goal-rollup.js",
@@ -5762,7 +5767,7 @@
     {
       "path": "modules/lifecycle/routes/done-when.js",
       "mode": "0000644",
-      "sha256": "9370fd1fc8a4a1ff864c1e85321b05a74bb45150ef8eb92cefdbbd85524bbe27"
+      "sha256": "13acccfc01be1760dc016519ccb430c448b237d6e02db83aa01815b2e45db7de"
     },
     {
       "path": "modules/lifecycle/routes/gate-approvals.js",
@@ -7767,12 +7772,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "2a7a58719ee7045ba87756d837dd6c059a099e04b4e86ee4a5c8cc9e2c42b50e"
+      "sha256": "e5b6e6ec23435368ffb25a25943670922f08c4a9f9a7a12e8a12d62e9bc48691"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "46f70444019c4bb61f50098fb4e9d1f2b05cc66142c6f59ea36a17c8e722e636"
+      "sha256": "beca5540ada5fdee92caf4c003fdd683ba0ac71218eb54fc9520db7b1e23a74e"
     },
     {
       "path": "public-docs/index.html",
@@ -9662,7 +9667,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "7532469124e010639f2fcf10257a9ffad594d90f3a15a67647c9a9c052ded87e"
+      "sha256": "c2878962ff1e2c457ea2eee7e6d1d0a6310a103d64ac1c4a1617e4081bc08ac5"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10527,12 +10532,12 @@
     {
       "path": "tests/criterion_authoring_gate.mjs",
       "mode": "0000644",
-      "sha256": "970db80cf43dba855bf9bd331434add458ab16e719f06710487094a3a578ec53"
+      "sha256": "ebe63de3ffcc33b5848e4226c5d2746d0662a04b9997518469ee98c9515e25d4"
     },
     {
       "path": "tests/criterion_goal_attach.mjs",
       "mode": "0000644",
-      "sha256": "979589fd08dc41da3c837513452353aa87f7653620fad22c8a9115d4d7d13b90"
+      "sha256": "58a0685287cb34b1cad88d0b0d0024e801068f8a7f07f53702857076c554bcad"
     },
     {
       "path": "tests/criterion_progress.mjs",

package/docs/module-api-changelog.md

@@ -2098,5 +2098,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.810 with no explicit bump. run 35189324772. (task 1002620)
   1.19.812 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.811 with no explicit bump. run 35191850392. (task 1002620)
+  1.19.813 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.812 with no explicit bump. run 35193306517. (task 1002620)
 ---------------------------------------------------------------------------
 ```

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-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/done-when.js

@@ -130,40 +130,58 @@ module.exports = function buildDoneWhenRouter() {
       goal_id: { type: 'integer', min: 1 },
       sort_order: { type: 'integer', min: 0 },
     })) return;
-    const version = await db.getVersion(versionId);
-    if (!version) return res.fail('version_not_found', { status: 404, message: `No version '${versionId}'.` });
     // bad_goal_id now means exactly what it says: the goal is absent or belongs
     // to another version. (The unauthorized case rendered through this same
     // helper until task 1002614 — see the mask note in authorizeCriterionCreate.)
     const badGoalId = () => res.fail('bad_goal_id', { status: 400, message: `goal_id ${req.body.goal_id} does not exist on version '${versionId}'.` });
-    // A goal_id, if given, must exist AND belong to this version.
-    let goal = null;
-    if (req.body.goal_id != null) {
-      goal = await db.getGoal(req.body.goal_id);
-      if (!goal || String(goal.version_id) !== String(versionId)) return badGoalId();
-    }
-    // ADR 0154: the authority wall. Checked AFTER the goal's version linkage so a
-    // bad ref is still the clearer 400. Membership is only read when a goal was
-    // named and the caller isn't an Archon — a primary-key hit on
-    // goal_members (goal_id, builder_id) (migration 160), on a low-frequency route.
-    const actorMembership = (goal && req.builder.rank !== 'archon')
-      ? await db.getGoalMember({ goalId: goal.id, builderId: req.builder.id })
-      : null;
-    const decision = authorizeCriterionCreate({
-      goal, version, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
-    });
-    if (!decision.ok) {
-      return res.status(decision.status).json(decision.body);
-    }
     try {
-      const criterion = await db.createCriterion({
-        versionId,
-        criterionId: req.body.criterion_id,
-        criterionMd: req.body.criterion_md,
-        goalId: req.body.goal_id ?? null,
-        sortOrder: req.body.sort_order ?? null,
-      });
-      res.status(201).json({ ok: true, criterion });
+      // RESOLVE, DECIDE and WRITE in ONE transaction, with the goal row LOCKED
+      // (task 1003840). Before this, the three facts the decision rests on — the
+      // version's status, the goal's owner/version linkage, the actor's
+      // membership — were read on the pool, and the INSERT landed afterwards on
+      // another connection. Between the two, the goal could be transferred or
+      // closed, the membership revoked, or the version frozen, and the write
+      // would land on authority that no longer held.
+      //
+      // The LOCK is the part that closes it. A bare transaction around the same
+      // sequence would still read the stale rows; the lock makes a concurrent
+      // transfer wait behind this one instead of racing it.
+      const outcome = await api.withTx(async (client) => {
+        const version = await db.getVersion(versionId, { client, forUpdate: true });
+        if (!version) return { fail: ['version_not_found', { status: 404, message: `No version '${versionId}'.` }] };
+        // A goal_id, if given, must exist AND belong to this version.
+        let goal = null;
+        if (req.body.goal_id != null) {
+          goal = await db.getGoal(req.body.goal_id, { client, forUpdate: true });
+          if (!goal || String(goal.version_id) !== String(versionId)) return { badGoal: true };
+        }
+        // ADR 0154: the authority wall. Checked AFTER the goal's version linkage so a
+        // bad ref is still the clearer 400. Membership is only read when a goal was
+        // named and the caller isn't an Archon — a primary-key hit on
+        // goal_members (goal_id, builder_id) (migration 160), on a low-frequency route.
+        const actorMembership = (goal && req.builder.rank !== 'archon')
+          ? await db.getGoalMember({ goalId: goal.id, builderId: req.builder.id }, { client })
+          : null;
+        const decision = authorizeCriterionCreate({
+          goal, version, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
+        });
+        if (!decision.ok) return { decision };
+        const criterion = await db.createCriterion({
+          versionId,
+          criterionId: req.body.criterion_id,
+          criterionMd: req.body.criterion_md,
+          goalId: req.body.goal_id ?? null,
+          sortOrder: req.body.sort_order ?? null,
+        }, { client });
+        return { criterion };
+      }, { pool: api.pool });
+      // Responses are sent AFTER the transaction resolves, never from inside it:
+      // a refusal must roll back rather than commit a half-written unit of work,
+      // and a 201 must not be promised before the COMMIT succeeds.
+      if (outcome.badGoal) return badGoalId();
+      if (outcome.fail) return res.fail(outcome.fail[0], outcome.fail[1]);
+      if (outcome.decision) return res.status(outcome.decision.status).json(outcome.decision.body);
+      res.status(201).json({ ok: true, criterion: outcome.criterion });
     } catch (err) {
       if (err && err.code === '23505') {
         return res.fail('criterion_exists', { status: 409, message: `criterion_id '${req.body.criterion_id}' already exists on version '${versionId}'.` });
@@ -294,64 +312,82 @@ module.exports = function buildDoneWhenRouter() {
     }
     const id = parseId(req, res, { param: 'criterionId', code: 'bad_criterion_id' });
     if (id === null) return;
-    const existing = await doneWhen.getCriterion(id);
-    if (!existing) return res.fail('criterion_not_found', 404);
-    const version = await db.getVersion(existing.version_id);
-    // The ownership wall, resolved exactly as the CREATE route resolves it: the
-    // goal + version, and membership read only for a non-Archon. One closure, so
-    // both ends of a move are decided by the same code rather than a copy.
-    const authorizeFor = async (goal) => {
-      const actorMembership = (goal && req.builder.rank !== 'archon')
-        ? await db.getGoalMember({ goalId: goal.id, builderId: req.builder.id })
-        : null;
-      return authorizeCriterionCreate({
-        goal, version, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
-      });
-    };
-    const currentGoal = existing.goal_id != null ? await db.getGoal(existing.goal_id) : null;
-    const authority = await authorizeFor(currentGoal);
-    if (!authority.ok) return res.status(authority.status).json(authority.body);
+    // Resolve, authorize and write inside ONE transaction, both goal rows LOCKED
+    // (task 1003840) — the same window the CREATE route above had, and the same
+    // cure. A move reads authority at BOTH ends, so both ends are locked: losing
+    // the race at either would move a criterion under authority that had just
+    // been revoked. Locking in a stable order (source before destination) is what
+    // keeps two concurrent moves from deadlocking on each other's rows.
+    const outcome = await api.withTx(async (client) => {
+      const existing = await doneWhen.getCriterion(id, { client });
+      if (!existing) return { fail: ['criterion_not_found', 404] };
+      const version = await db.getVersion(existing.version_id, { client, forUpdate: true });
+      // The ownership wall, resolved exactly as the CREATE route resolves it: the
+      // goal + version, and membership read only for a non-Archon. One closure, so
+      // both ends of a move are decided by the same code rather than a copy.
+      const authorizeFor = async (goal) => {
+        const actorMembership = (goal && req.builder.rank !== 'archon')
+          ? await db.getGoalMember({ goalId: goal.id, builderId: req.builder.id }, { client })
+          : null;
+        return authorizeCriterionCreate({
+          goal, version, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
+        });
+      };
+      const targetGoalId = movingGoal ? (req.body.goal_id ?? null) : null;
+
+      // Lock BOTH ends in ASCENDING GOAL ID, never in the order the route happens
+      // to need them (task 1003840, round 2 — the first cut locked source then
+      // destination, which is call order, not a canonical one). Two opposite
+      // moves, 5→10 and 10→5, would then take the two locks in opposite orders
+      // and deadlock; Postgres aborts one rather than corrupting anything, but an
+      // avoidable abort is still an outage for whoever loses. A single agreed
+      // order means they queue instead.
+      const lockIds = [...new Set([
+        existing.goal_id != null ? Number(existing.goal_id) : null,
+        targetGoalId !== null ? Number(targetGoalId) : null,
+      ].filter((v) => v != null))].sort((a, b) => a - b);
+      const locked = new Map();
+      for (const gid of lockIds) locked.set(gid, await db.getGoal(gid, { client, forUpdate: true }));
+
+      const currentGoal = existing.goal_id != null ? locked.get(Number(existing.goal_id)) ?? null : null;
+      const authority = await authorizeFor(currentGoal);
+      if (!authority.ok) return { decision: authority };
 
-    const targetGoalId = movingGoal ? (req.body.goal_id ?? null) : null;
-    if (movingGoal) {
-      let targetGoal = null;
-      if (targetGoalId !== null) {
-        targetGoal = await db.getGoal(targetGoalId);
-        // Same refusal the CREATE route gives, for the same reason: a criterion may
-        // never cross versions, which would put it in one version's rollup and the
-        // other's goal at once.
-        if (!targetGoal || String(targetGoal.version_id) !== String(existing.version_id)) {
-          return res.fail('bad_goal_id', { status: 400, message: `goal_id ${targetGoalId} does not exist on version '${existing.version_id}'.` });
+      if (movingGoal) {
+        let targetGoal = null;
+        if (targetGoalId !== null) {
+          targetGoal = locked.get(Number(targetGoalId)) ?? null;
+          // Same refusal the CREATE route gives, for the same reason: a criterion may
+          // never cross versions, which would put it in one version's rollup and the
+          // other's goal at once.
+          if (!targetGoal || String(targetGoal.version_id) !== String(existing.version_id)) {
+            return { fail: ['bad_goal_id', { status: 400, message: `goal_id ${targetGoalId} does not exist on version '${existing.version_id}'.` }] };
+          }
         }
+        const destination = await authorizeFor(targetGoal);
+        if (!destination.ok) return { decision: destination };
       }
-      const destination = await authorizeFor(targetGoal);
-      if (!destination.ok) return res.status(destination.status).json(destination.body);
-    }
 
-    let criterion = existing;
-    let deltas = [];
-    let unchanged = false;
-    if (changingProse) {
-      const refusal = goalEdits.criterionProseRefusal(existing);
-      if (refusal) return res.fail(refusal.code, refusal.status, refusal.message ? { message: refusal.message } : undefined);
-      const result = await goalEdits.updateCriterionProse({ criterionId: id, criterionMd: req.body.criterion_md });
-      if (!result) return res.fail('criterion_not_found', 404);
-      await goalEdits.recordProseEdit('criterion', id, req, result.deltas);
-      criterion = result.criterion;
-      deltas = result.deltas;
-      unchanged = !!result.unchanged;
-    }
-    const achievedGoals = [];
-    const fromGoalId = existing.goal_id ?? null;
+      let criterion = existing;
+      let deltas = [];
+      let unchanged = false;
+      if (changingProse) {
+        const refusal = goalEdits.criterionProseRefusal(existing);
+        if (refusal) return { refusal };
+        const result = await goalEdits.updateCriterionProse({ criterionId: id, criterionMd: req.body.criterion_md }, { client });
+        if (!result) return { fail: ['criterion_not_found', 404] };
+        criterion = result.criterion;
+        deltas = result.deltas;
+        unchanged = !!result.unchanged;
+      }
+      const achievedGoals = [];
+      const fromGoalId = existing.goal_id ?? null;
     // A move to where it already is writes nothing at all — not the row, not the
     // audit, not a re-derive. Nothing about the world changed.
-    if (movingGoal && fromGoalId !== targetGoalId) {
-      const moved = await db.updateCriterionGoal(id, targetGoalId);
-      if (!moved) return res.fail('criterion_not_found', 404);
-      criterion = moved;
-      await goalEdits.recordCriterionGoalMove(
-        { criterionId: id, fromGoalId, toGoalId: targetGoalId }, req
-      );
+      if (movingGoal && fromGoalId !== targetGoalId) {
+        const moved = await db.updateCriterionGoal(id, targetGoalId, { client });
+        if (!moved) return { fail: ['criterion_not_found', 404] };
+        criterion = moved;
       // BOTH ENDS are re-derived, because a move changes what each of them still
       // needs. The destination is the obvious half — adopting an already-satisfied
       // criterion can be the thing that completes a goal. The SOURCE is the half
@@ -361,13 +397,41 @@ module.exports = function buildDoneWhenRouter() {
       // will ever close again — no later ship re-checks it, because no task under
       // it changed. achieveGoalIfComplete is conservative and idempotent (open
       // goals only, and it never un-achieves), so asking twice is two reads.
-      for (const goalId of [fromGoalId, targetGoalId]) {
-        if (goalId === null) continue;
-        const outcome = await db.achieveGoalIfComplete({ goalId });
-        if (outcome && outcome.achieved) achievedGoals.push(goalId);
+        for (const goalId of [fromGoalId, targetGoalId]) {
+          if (goalId === null) continue;
+          const achieved = await db.achieveGoalIfComplete({ goalId }, { client });
+          if (achieved && achieved.achieved) achievedGoals.push(goalId);
+        }
       }
+      return { criterion, deltas, unchanged, achievedGoals, moved: movingGoal && fromGoalId !== targetGoalId, fromGoalId, targetGoalId };
+    }, { pool: api.pool });
+
+    // Everything below runs only after COMMIT. The audit writes in particular
+    // belong out here: they are announcements of a change that happened, so
+    // recording one for a unit of work that rolled back would put an edit in the
+    // ledger that never landed — the ledger lying, which is the one thing it
+    // must not do.
+    if (outcome.fail) return res.fail(outcome.fail[0], outcome.fail[1]);
+    if (outcome.decision) return res.status(outcome.decision.status).json(outcome.decision.body);
+    if (outcome.refusal) {
+      const r = outcome.refusal;
+      return res.fail(r.code, r.status, r.message ? { message: r.message } : undefined);
     }
-    return res.json({ ok: true, criterion, deltas, unchanged, achieved_goals: achievedGoals });
+    if (outcome.deltas && outcome.deltas.length) {
+      await goalEdits.recordProseEdit('criterion', id, req, outcome.deltas);
+    }
+    if (outcome.moved) {
+      await goalEdits.recordCriterionGoalMove(
+        { criterionId: id, fromGoalId: outcome.fromGoalId, toGoalId: outcome.targetGoalId }, req
+      );
+    }
+    return res.json({
+      ok: true,
+      criterion: outcome.criterion,
+      deltas: outcome.deltas,
+      unchanged: outcome.unchanged,
+      achieved_goals: outcome.achievedGoals,
+    });
   }, { errorCode: 'criterion_update_failed' }));
 
   // Auth: flip a criterion back to unsatisfied (rare; for corrections).

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.812",
+  "version": "1.19.813",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.812",
+      "version": "1.19.813",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.812",
+  "version": "1.19.813",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.812'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.813'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/criterion_authoring_gate.mjs

@@ -144,8 +144,29 @@ await test('authority is checked BEFORE goal state — an owner sees goal_not_op
 
 await test('bad_goal_id now means exactly what it says — the mask branch is gone from the route', () => {
   assert.match(doneWhenSrc, /const badGoalId = \(\) => res\.fail\('bad_goal_id'/, 'one helper builds the absent/foreign refusal');
-  assert.match(doneWhenSrc, /if \(!goal \|\| String\(goal\.version_id\) !== String\(versionId\)\) return badGoalId\(\);/, 'absent/foreign goal path');
+  // The absent/foreign check and the refusal it renders are now separated by the
+  // transaction boundary (task 1003840): the check runs inside withTx and returns
+  // a sentinel, because sending a response from inside the transaction would
+  // commit a unit of work the route is in the middle of refusing. So the chain is
+  // asserted in two links rather than as one literal line — the invariant is
+  // "an absent or foreign goal reaches badGoalId and nothing else", which is what
+  // this test was always about.
+  assert.match(
+    doneWhenSrc,
+    /if \(!goal \|\| String\(goal\.version_id\) !== String\(versionId\)\) return \{ badGoal: true \};/,
+    'absent/foreign goal path still refuses, inside the transaction',
+  );
+  assert.match(
+    doneWhenSrc,
+    /if \(outcome\.badGoal\) return badGoalId\(\);/,
+    'and that sentinel is rendered by badGoalId once the transaction resolves',
+  );
   assert.doesNotMatch(doneWhenSrc, /maskAsBadGoalId/, 'no code path renders an authorization refusal as bad_goal_id');
+  // The sentinel must be answered exactly where it is raised — a second producer
+  // with no consumer, or vice versa, is how a refusal quietly becomes a 201.
+  const raised = (doneWhenSrc.match(/badGoal: true/g) || []).length;
+  const answered = (doneWhenSrc.match(/outcome\.badGoal/g) || []).length;
+  assert.equal(raised, answered, 'every badGoal sentinel raised is answered');
 });
 
 await test('a SHIPPED version is refused (409) — closed scope', () => {

package/tests/criterion_goal_attach.mjs

@@ -36,21 +36,54 @@ const api = require('../src/module-api.js');
 // db.updateCriterionGoal instead would leave its SQL with no coverage at all —
 // a mutation that made the UPDATE write nothing stayed green until this landed.
 const sqlLog = [];
+
+// One statement handler, shared by the pool and by the transaction client it
+// hands out, so a statement is recorded identically wherever it runs — otherwise
+// "the UPDATE reached the pool" would quietly stop being true the moment the
+// route started using a transaction, and the assertions would pass over nothing.
+const runSql = async (sql, params, via = 'pool') => {
+  sqlLog.push({ sql, params, via });
+  if (/UPDATE done_when_criteria/.test(sql)) {
+    const [goalId, id] = params;
+    criterion = { ...criterion, id: Number(id), goal_id: goalId };
+    return { rows: [{ ...criterion }] };
+  }
+  if (/COALESCE\(MAX\(sort_order\)/.test(sql)) return { rows: [{ next: 7 }] };
+  if (/INSERT INTO done_when_criteria/.test(sql)) {
+    const [versionId, criterionId, criterionMd, goalId, sortOrder] = params;
+    return { rows: [{ id: 99, version_id: versionId, criterion_id: criterionId, criterion_md: criterionMd, goal_id: goalId, sort_order: sortOrder, satisfied: false }] };
+  }
+  if (/^\s*(BEGIN|COMMIT|ROLLBACK)\s*$/i.test(sql)) return { rows: [] };
+  throw new Error(`unexpected SQL reached the pool: ${sql}`);
+};
+
+// connect() makes withTx work against the fake (task 1003840). Every client it
+// returns is recorded, so a test can assert the transaction BOUNDARY — that a
+// write happened between BEGIN and COMMIT — not merely that the write happened.
+const clients = [];
 Object.defineProperty(api, 'pool', {
   configurable: true,
   value: {
-    query: async (sql, params) => {
-      sqlLog.push({ sql, params });
-      if (/UPDATE done_when_criteria/.test(sql)) {
-        const [goalId, id] = params;
-        criterion = { ...criterion, id: Number(id), goal_id: goalId };
-        return { rows: [{ ...criterion }] };
-      }
-      throw new Error(`unexpected SQL reached the pool: ${sql}`);
+    query: (sql, params) => runSql(sql, params, 'pool'),
+    connect: async () => {
+      const client = {
+        query: (sql, params) => runSql(sql, params, 'client'),
+        release: () => { client.released = true; },
+        released: false,
+      };
+      clients.push(client);
+      return client;
     },
   },
 });
 
+// The statements of the LAST transaction, in order — BEGIN … COMMIT included.
+function txStatements() {
+  const begin = sqlLog.findIndex((q) => /^\s*BEGIN\s*$/i.test(q.sql));
+  if (begin === -1) return [];
+  return sqlLog.slice(begin).map((q) => q.sql.trim().split(/\s+/).slice(0, 3).join(' '));
+}
+
 const db = require('../modules/lifecycle/db.js');
 const doneWhen = require('../modules/lifecycle/done-when.js');
 const goalEdits = require('../modules/lifecycle/goal-edits.js');
@@ -71,6 +104,7 @@ function resetWorld() {
   actor = METIC;
   completable = new Set([3]);
   sqlLog.length = 0;
+  clients.length = 0;
   calls = { achieve: [], auditMove: [], prose: [] };
   // Derived from the SQL the real updateCriterionGoal actually sent, as
   // [criterionId, goalId] — so "nothing was written" means no UPDATE reached the
@@ -140,6 +174,15 @@ async function patch(body) {
   return { status: res.status, body: await res.json().catch(() => ({})) };
 }
 
+async function post(versionId, body) {
+  const res = await fetch(`${base}/versions/${versionId}/done-when`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  return { status: res.status, body: await res.json().catch(() => ({})) };
+}
+
 let passed = 0, failed = 0;
 async function test(name, fn) {
   resetWorld();
@@ -342,6 +385,188 @@ await test('the UPDATE sets goal_id from the parameter, keyed by criterion id',
   assert.deepEqual(update.params, [3, 55]);
 });
 
+
+// ---- the TOCTOU window (task 1003840) --------------------------------------
+//
+// The route used to resolve its facts on the pool, decide, and then write on
+// another connection. Between the decision and the write the goal could be
+// transferred or closed and the membership revoked, and the write would land on
+// authority that no longer held. These pin the three properties that close it:
+// one transaction, the authority read LOCKED inside it, and nothing written (or
+// announced) when the decision refuses.
+
+// Record what the route ASKS FOR, since getGoal is stubbed here and its SQL never
+// reaches the recording pool.
+const goalReads = [];
+const versionReads = [];
+const realGetGoal = db.getGoal;
+const realGetVersion = db.getVersion;
+db.getGoal = async (id, deps = {}) => { goalReads.push({ id: Number(id), deps }); return realGetGoal(id, deps); };
+db.getVersion = async (id, deps = {}) => { versionReads.push({ id, deps }); return realGetVersion(id, deps); };
+
+await test('the authority read is LOCKED and inside the transaction (task 1003840)', async () => {
+  actor = ARCHON;
+  goalReads.length = 0;
+  await patch({ goal_id: 3 });
+  assert.ok(goalReads.length > 0, 'the route read a goal at all');
+  for (const r of goalReads) {
+    assert.ok(r.deps && r.deps.client, `goal ${r.id} was read OUTSIDE the transaction`);
+    assert.equal(r.deps.forUpdate, true, `goal ${r.id} was read without FOR UPDATE — a re-read that is not locked still races`);
+  }
+});
+
+await test('the write lands BETWEEN begin and commit (task 1003840)', async () => {
+  actor = ARCHON;
+  await patch({ goal_id: 3 });
+  const seq = sqlLog.map((q) => q.sql.trim().split(/\s+/).slice(0, 2).join(' ').toUpperCase());
+  const begin = seq.findIndex((x) => x.startsWith('BEGIN'));
+  const update = seq.findIndex((x) => x.startsWith('UPDATE DONE_WHEN_CRITERIA'));
+  const commit = seq.findIndex((x) => x.startsWith('COMMIT'));
+  assert.ok(begin !== -1, 'a transaction was opened');
+  assert.ok(update !== -1, 'the move was written');
+  assert.ok(commit !== -1, 'the transaction was committed');
+  assert.ok(begin < update && update < commit,
+    `expected BEGIN < UPDATE < COMMIT, got ${begin} / ${update} / ${commit}`);
+  // ORDER IS NOT ENOUGH. A write sent to the POOL while a transaction happens to
+  // be open still lands between BEGIN and COMMIT in this log, and is exactly the
+  // bug — it is outside the transaction and rolls back with nothing. Caught by
+  // probing: dropping the client from updateCriterionGoal left the ordering
+  // assertion green. So the connection is asserted, not just the sequence.
+  const writes = sqlLog.filter((q) => /UPDATE done_when_criteria/.test(q.sql));
+  assert.ok(writes.length > 0, 'the move was written');
+  for (const w of writes) {
+    assert.equal(w.via, 'client', 'the write must run ON the transaction client, not the pool');
+  }
+});
+
+await test('the transaction client is always released (task 1003840)', async () => {
+  // A leaked client is a pool slot that never comes back; under load that is an
+  // outage, and it would not show up in any assertion about the response.
+  actor = ARCHON;
+  await patch({ goal_id: 3 });
+  assert.ok(clients.length > 0, 'a client was checked out');
+  for (const c of clients) assert.equal(c.released, true, 'every checked-out client is released');
+});
+
+await test('a REFUSED move writes nothing and announces nothing (task 1003840)', async () => {
+  // The rollback path. A refusal must leave no row written and no audit entry:
+  // recording a move that did not happen would put an edit in the ledger that
+  // never landed.
+  actor = METIC;                       // not the owner of goal 3
+  goals.set(3, { id: 3, version_id: V1, owner_builder_id: 999, status: 'open' });
+  const res = await patch({ goal_id: 3 });
+  assert.ok(res.status >= 400, `expected a refusal, got ${res.status}`);
+  assert.deepEqual(calls.updateGoal, [], 'no UPDATE reached the pool');
+  assert.deepEqual(calls.auditMove, [], 'no move was announced for a write that never landed');
+  assert.equal(clients.every((c) => c.released), true, 'the client is released on the refusal path too');
+});
+
+await test('FOR UPDATE outside a transaction is refused, not silently downgraded (task 1003840)', async () => {
+  // The lock is the whole fix, so asking for one where it cannot be held must be
+  // an error rather than a quiet plain read — otherwise a future caller drops the
+  // client, keeps the flag, and believes it is safe.
+  // The REAL implementation, not this file's stub of it: db.getGoal is replaced
+  // above, so asserting against that would only prove the stub ignores the flag.
+  // It throws before touching a pool, so this needs no database.
+  const realGoals = require('../modules/lifecycle/db-goals.js');
+  await assert.rejects(
+    () => realGoals.getGoal(3, { forUpdate: true }),
+    /requires deps\.client/,
+    'forUpdate without a client must throw',
+  );
+});
+
+
+// ---- CREATE route: the same machinery, the same proof (task 1003840, round 2) --
+//
+// The first cut shipped the CREATE route's transaction with no runtime coverage —
+// only a source-regex on the sentinel shape — while its PATCH sibling got four
+// behavioural tests. Identical machinery deserves identical proof: a regex cannot
+// tell whether the INSERT actually ran on the transaction client.
+
+await test('CREATE: the goal is locked, inside the transaction (task 1003840)', async () => {
+  actor = ARCHON;
+  goalReads.length = 0;
+  const r = await post(V1, { criterion_id: 'C9', criterion_md: 'x', goal_id: 3 });
+  assert.equal(r.status, 201, JSON.stringify(r.body));
+  assert.ok(goalReads.length > 0, 'the route read the goal');
+  for (const g of goalReads) {
+    assert.ok(g.deps && g.deps.client, 'the goal was read OUTSIDE the transaction');
+    assert.equal(g.deps.forUpdate, true, 'the goal was read without FOR UPDATE');
+  }
+});
+
+await test('CREATE: the INSERT runs ON the transaction client (task 1003840)', async () => {
+  actor = ARCHON;
+  await post(V1, { criterion_id: 'C9', criterion_md: 'x', goal_id: 3 });
+  const inserts = sqlLog.filter((q) => /INSERT INTO done_when_criteria/.test(q.sql));
+  assert.equal(inserts.length, 1, 'exactly one INSERT');
+  assert.equal(inserts[0].via, 'client', 'the INSERT must not leave the transaction');
+  // Its sort_order read is part of the SAME decision and must share the client,
+  // or two concurrent creates can read the same next order.
+  const maxRead = sqlLog.find((q) => /COALESCE\(MAX\(sort_order\)/.test(q.sql));
+  assert.ok(maxRead, 'the sort_order read happened');
+  assert.equal(maxRead.via, 'client', 'the read that decides sort_order shares the transaction');
+});
+
+await test('CREATE: a refusal writes nothing and releases the client (task 1003840)', async () => {
+  actor = METIC;
+  goals.set(3, { id: 3, version_id: V1, owner_builder_id: 999, status: 'open' });
+  const r = await post(V1, { criterion_id: 'C9', criterion_md: 'x', goal_id: 3 });
+  assert.ok(r.status >= 400, `expected a refusal, got ${r.status}`);
+  assert.equal(sqlLog.filter((q) => /INSERT INTO done_when_criteria/.test(q.sql)).length, 0, 'nothing was inserted');
+  assert.ok(clients.length > 0 && clients.every((c) => c.released), 'the client is released on the refusal path');
+});
+
+await test('the VERSION is locked too, not only the goal (task 1003840)', async () => {
+  // The task names three facts; the first cut locked one. A plain read is never
+  // blocked by another session's row lock under READ COMMITTED, so an unlocked
+  // version could still be frozen between this read and this COMMIT.
+  actor = ARCHON;
+  versionReads.length = 0;
+  await post(V1, { criterion_id: 'C9', criterion_md: 'x', goal_id: 3 });
+  assert.ok(versionReads.length > 0, 'the route read the version');
+  for (const v of versionReads) {
+    assert.ok(v.deps && v.deps.client, 'the version was read outside the transaction');
+    assert.equal(v.deps.forUpdate, true, 'the version was read without FOR UPDATE');
+  }
+});
+
+await test('a move locks both goals in ASCENDING ID ORDER, not call order (task 1003840)', async () => {
+  // Call order is source-then-destination, so 10->5 and 5->10 running at once
+  // would take the two locks in opposite orders and deadlock. One agreed order
+  // makes them queue. Asserted for the descending move, where the two differ.
+  actor = ARCHON;
+  goals.set(10, { id: 10, version_id: V1, owner_builder_id: ARCHON.id, status: 'open' });
+  criterion.goal_id = 10;
+  goalReads.length = 0;
+  const r = await patch({ goal_id: 3 });
+  assert.equal(r.status, 200, JSON.stringify(r.body));
+  const lockOrder = goalReads.filter((g) => g.deps && g.deps.forUpdate).map((g) => g.id);
+  assert.deepEqual(lockOrder, [...lockOrder].sort((a, b) => a - b),
+    `goals were locked in ${lockOrder.join(',')} — not ascending id order`);
+  assert.deepEqual(lockOrder, [3, 10], 'both ends are locked, lowest id first');
+});
+
+await test('setGoalStatus writes on the transaction client (task 1003840)', async () => {
+  // The auto-achieve's actual writer. Missed in the first cut, where it kept its
+  // own copy of the pool rule — so the UPDATE ran on the pool while the route
+  // held that same row FOR UPDATE on its client: a self-deadlock against real
+  // Postgres, not merely an untransacted write.
+  const realGoals = require('../modules/lifecycle/db-goals.js');
+  const seen = [];
+  const fakeClient = { query: async (sql, params) => { seen.push({ sql, params }); return { rows: [{ id: 3, status: 'achieved' }] }; } };
+  await realGoals.setGoalStatus({ goalId: 3, status: 'achieved' }, { client: fakeClient });
+  assert.equal(seen.length, 1, 'the UPDATE reached the injected client');
+  assert.match(seen[0].sql, /UPDATE goals/);
+  assert.deepEqual(seen[0].params, [3, 'achieved']);
+});
+
+// The wrapper installed above is removed, so nothing after this file's own tests
+// inherits a patched module export.
+db.getGoal = realGetGoal;
+db.getVersion = realGetVersion;
+
 await new Promise((r) => server.close(r));
 console.log(`\ncriterion_goal_attach: ${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);