@bongos/core 1.19.811 → 1.19.813

package/modules/hall-ui/public/settings-specialities.js

@@ -0,0 +1,241 @@
+// modules/hall-ui/public/settings-specialities.js — the "Your specialities" panel
+// on /builders/settings (task 1003855; ADR 0296).
+//
+// WHAT A SPECIALITY IS, for anyone reading this file first: a craft says HOW you
+// work (engineer / ideator / artist / ui); a speciality says what you work ON and
+// how you, as a subject-matter expert, want to be engaged inside that craft. The
+// contract you write here is injected into every session where you hold a claim
+// in that craft.
+//
+// Its own file rather than more of settings.js, on the settings-interaction.js /
+// settings-sessions.js precedent and for the same stated reason: settings.js sits
+// against the 1500-line size ratchet. Self-contained — it shares nothing with the
+// rest of the page but `window.OTB` and the generated client, both loaded before it.
+//
+// TRAINING IS TWO-FOLD, and only half of it is visible here. Documents you add are
+// the half you drive; the other half accumulates on its own from learnings captured
+// while you work in the speciality. The counts row says which is which, so "it
+// knows 4 things" is never mistaken for "I typed 4 things".
+
+(() => {
+  'use strict';
+
+  const API = '/api/bongos';
+  const { escapeHtml, $ } = window.OTB;
+  const toast = (msg) => window.OTB.toast(msg);
+
+  const state = { rows: [], openId: null, busy: false };
+
+  const el = (id) => document.getElementById(id);
+  const statusLine = (msg) => { const s = el('specialities-status'); if (s) s.textContent = msg || ''; };
+
+  async function call(method, path, body) {
+    const res = await fetch(`${API}${path}`, {
+      method,
+      credentials: 'same-origin',
+      headers: body ? { 'Content-Type': 'application/json', Accept: 'application/json' } : { Accept: 'application/json' },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    if (res.status === 401) { window.location.assign(`${API}/auth/web/start`); return null; }
+    let data = null;
+    try { data = await res.json(); } catch { /* an empty body is legal on some paths */ }
+    if (!res.ok) {
+      // Surface the field-level reason when the server sent one — a bare
+      // "failed" on a form with five fields is useless.
+      const detail = data && data.details && Array.isArray(data.details.errors)
+        ? data.details.errors.map((e) => `${e.field}: ${e.code}`).join(', ')
+        : (data && data.message) || `HTTP ${res.status}`;
+      throw new Error(detail);
+    }
+    return data;
+  }
+
+  const VISIBILITY_COPY = {
+    private: 'Only you',
+    project: 'Anyone in the owning project',
+    public: 'Anyone on this instance',
+  };
+
+
+  // THE INSTRUCTION THE ADOPTER IS AGREEING TO. A speciality someone else wrote
+  // puts their prose into YOUR sessions, which is the only place in this product
+  // where that happens — so it is shown in full before "Use this", never folded
+  // away behind a summary. Shown for your own too, because seeing what actually
+  // reaches a session is the point either way.
+  function contractHtml(s) {
+    if (!s.contract_md) return '';
+    const theirs = !s.mine;
+    return `
+      <details class="speciality-contract"${theirs ? ' open' : ''}>
+        <summary>${theirs ? 'What this adds to your sessions — written by someone else' : 'What this adds to your sessions'}</summary>
+        <pre class="speciality-contract__body">${escapeHtml(s.contract_md)}</pre>
+        ${theirs ? '<p class="prow__hint">You did not write this. Read it before using the speciality — it reaches every session where you hold work in that craft, and it is passed to Claude as this author\'s stated preferences, not as instructions it must obey.</p>' : ''}
+      </details>`;
+  }
+
+  function cardHtml(s) {
+    const trained = Number(s.documentCount || 0);
+    const learned = Number(s.learningCount || 0);
+    const open = String(state.openId) === String(s.id);
+    return `
+      <li class="prow speciality-card" data-id="${escapeHtml(String(s.id))}">
+        <div class="prow__main">
+          <div class="prow__label">
+            <strong>${escapeHtml(s.name)}</strong>
+            <span class="speciality-craft">${escapeHtml(s.discipline)}</span>
+            ${s.active ? '<span class="speciality-badge speciality-badge--on">active</span>' : ''}
+          </div>
+          <p class="prow__hint">${escapeHtml(s.summary || 'No summary yet.')}</p>
+          ${contractHtml(s)}
+          <p class="prow__hint speciality-counts">
+            Trained on <strong>${trained}</strong> document${trained === 1 ? '' : 's'} you added
+            · learned <strong>${learned}</strong> thing${learned === 1 ? '' : 's'} from your sessions
+            · shared with: ${escapeHtml(VISIBILITY_COPY[s.visibility] || s.visibility || 'only you')}
+          </p>
+        </div>
+        <div class="prow__actions">
+          ${s.mine ? `<button type="button" class="btn btn--quiet" data-act="train" data-id="${escapeHtml(String(s.id))}">${open ? 'Close' : 'Train'}</button>` : ''}
+          ${s.active
+            ? `<button type="button" class="btn btn--quiet" data-act="abandon" data-id="${escapeHtml(String(s.id))}">Stop using</button>`
+            : `<button type="button" class="btn" data-act="adopt" data-id="${escapeHtml(String(s.id))}" ${s.adoptable ? '' : 'disabled'}>Use this</button>`}
+        </div>
+        ${open ? trainHtml(s) : ''}
+      </li>`;
+  }
+
+  function trainHtml(s) {
+    return `
+      <form class="speciality-train" data-id="${escapeHtml(String(s.id))}">
+        <p class="prow__hint">
+          Add something you wrote — notes, a standard, a worked example. It is indexed
+          for recall, not pasted into every session, so length costs you nothing.
+        </p>
+        <label class="speciality-field">
+          <span>Title</span>
+          <input type="text" name="title" maxlength="200" required placeholder="How we price a swap" />
+        </label>
+        <label class="speciality-field">
+          <span>The document</span>
+          <textarea name="body_md" rows="6" required placeholder="Paste or write it here."></textarea>
+        </label>
+        <div class="speciality-actions">
+          <button type="submit" class="btn">Add to what it knows</button>
+        </div>
+      </form>`;
+  }
+
+  function render() {
+    const host = el('specialities-rows');
+    if (!host) return;
+    if (!state.rows.length) {
+      host.innerHTML = `<li class="prow"><div class="prow__main">
+        <p class="prow__hint">No specialities yet. Create one below — it takes a name and a craft, and you can train it afterwards.</p>
+      </div></li>`;
+      return;
+    }
+    host.innerHTML = state.rows.map(cardHtml).join('');
+  }
+
+  async function load() {
+    try {
+      const [cat, mine] = await Promise.all([call('GET', '/specialities'), call('GET', '/me/specialities')]);
+      if (!cat) return;
+      const activeIds = new Set(((mine && mine.adoptions) || []).filter((a) => a.active).map((a) => String(a.id)));
+      state.rows = ((cat && cat.specialities) || []).map((s) => ({ ...s, active: activeIds.has(String(s.id)) }));
+      render();
+      statusLine('');
+    } catch (err) {
+      statusLine(`Could not load specialities — ${err.message}`);
+    }
+  }
+
+  async function act(action, id) {
+    if (state.busy) return;
+    state.busy = true;
+    try {
+      if (action === 'adopt') { await call('POST', `/specialities/${id}/adopt`); toast('Using this speciality.'); }
+      if (action === 'abandon') { await call('POST', `/specialities/${id}/abandon`); toast('Stopped using it.'); }
+      await load();
+    } catch (err) {
+      statusLine(err.message);
+    } finally {
+      state.busy = false;
+    }
+  }
+
+  function wire() {
+    const host = el('specialities-rows');
+    if (host) {
+      host.addEventListener('click', (e) => {
+        const btn = e.target.closest('button[data-act]');
+        if (!btn) return;
+        const { act: action, id } = btn.dataset;
+        if (action === 'train') { state.openId = String(state.openId) === String(id) ? null : id; render(); return; }
+        act(action, id);
+      });
+
+      host.addEventListener('submit', async (e) => {
+        const form = e.target.closest('form.speciality-train');
+        if (!form) return;
+        e.preventDefault();
+        const title = form.elements.title.value.trim();
+        const body = form.elements.body_md.value.trim();
+        // Validate before calling: an empty field should say so inline rather
+        // than round-trip to a 400.
+        if (!title || !body) { statusLine('A document needs both a title and some content.'); return; }
+        try {
+          const out = await call('POST', `/specialities/${form.dataset.id}/documents`, { title, body_md: body });
+          toast(out && out.skipped ? 'It already knew that one.' : 'Added.');
+          state.openId = null;
+          await load();
+        } catch (err) { statusLine(err.message); }
+      });
+    }
+
+    const create = el('speciality-create');
+    if (create) {
+      create.addEventListener('submit', async (e) => {
+        e.preventDefault();
+        const name = create.elements.name.value.trim();
+        const discipline = create.elements.discipline.value;
+        if (!name) { statusLine('Give it a name.'); return; }
+        if (!discipline) { statusLine('Pick which craft it sits under.'); return; }
+        try {
+          await call('POST', '/specialities', {
+            name,
+            discipline,
+            summary: create.elements.summary.value.trim(),
+            contract_md: create.elements.contract_md.value.trim(),
+            visibility: create.elements.visibility.value,
+            sellable: create.elements.sellable.checked,
+          });
+          create.reset();
+          toast('Speciality created.');
+          await load();
+        } catch (err) { statusLine(err.message); }
+      });
+
+      // The server refuses private+sellable (there is nobody it could be sold
+      // to). Mirror that here so the checkbox cannot be left in a state the save
+      // will reject.
+      const vis = create.elements.visibility;
+      const sell = create.elements.sellable;
+      const sync = () => {
+        const isPrivate = vis.value === 'private';
+        sell.disabled = isPrivate;
+        if (isPrivate) sell.checked = false;
+      };
+      vis.addEventListener('change', sync);
+      sync();
+    }
+  }
+
+  function boot() {
+    if (!el('specialities-rows')) return; // panel not on this page
+    wire();
+    load();
+  }
+
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', boot);
+  else boot();
+})();

package/modules/hall-ui/public/settings.css

@@ -161,3 +161,59 @@ select.voices__select { min-width: 140px; }
 /* the box panel is the shell's (.setup__box, box-panel.js); inside a settings
    panel it sits on the glass rather than a second card */
 .settings-groups .setup__box { margin: var(--sp-sm) 0 0; background: var(--glass); border-color: var(--glass-edge); border-radius: var(--radius-sm); }
+
+/* Specialities panel (task 1003855, ADR 0296). A speciality is a named bundle of
+   knowledge and terms under a craft; this styles the list, the train form and the
+   create form. Tokens only — no literal colours, so light/dark follow the page. */
+.speciality-craft {
+  font-size: 0.78rem;
+  text-transform: lowercase;
+  opacity: 0.72;
+  margin-left: 0.4rem;
+}
+.speciality-badge {
+  font-size: 0.7rem;
+  padding: 0.05rem 0.4rem;
+  border-radius: 0.5rem;
+  margin-left: 0.4rem;
+  border: 1px solid currentColor;
+}
+.speciality-counts { opacity: 0.82; }
+.speciality-card { flex-wrap: wrap; }
+.speciality-train,
+.speciality-create {
+  flex-basis: 100%;
+  margin-top: 0.75rem;
+  padding-top: 0.75rem;
+  border-top: 1px solid var(--rule, rgba(128, 128, 128, 0.25));
+  display: flex;
+  flex-direction: column;
+  gap: 0.6rem;
+}
+.speciality-create__h { margin: 0; font-size: 0.95rem; }
+.speciality-field { display: flex; flex-direction: column; gap: 0.25rem; }
+.speciality-field > span { font-size: 0.85rem; }
+.speciality-field small { display: block; opacity: 0.7; font-weight: normal; }
+.speciality-field input[type='text'],
+.speciality-field select,
+.speciality-field textarea {
+  width: 100%;
+  box-sizing: border-box;
+}
+/* The checkbox row reads as one sentence, so it runs inline rather than stacked. */
+.speciality-field--check { flex-direction: row; align-items: flex-start; gap: 0.5rem; }
+.speciality-field--check input { margin-top: 0.2rem; }
+.speciality-actions { display: flex; gap: 0.5rem; }
+/* The adopted contract, shown in full before "Use this" — another builder's prose
+   reaching your sessions is the one thing here that must never be folded away. */
+.speciality-contract { flex-basis: 100%; margin-top: 0.5rem; font-size: 0.85rem; }
+.speciality-contract > summary { cursor: pointer; opacity: 0.85; }
+.speciality-contract__body {
+  white-space: pre-wrap;
+  margin: 0.4rem 0 0;
+  padding: 0.5rem 0.65rem;
+  border-left: 2px solid var(--rule, rgba(128, 128, 128, 0.35));
+  border-radius: 0;
+  font-family: inherit;
+  opacity: 0.92;
+}

package/modules/hall-ui/public/settings.html

@@ -269,6 +269,70 @@
               <p class="settings-status" id="interaction-status" role="status" aria-live="polite"></p>
             </section>
 
+            <!-- SPECIALITIES — a named bundle of knowledge + terms UNDER a craft
+                 (task 1003855, ADR 0296). GET/POST /api/bongos/specialities,
+                 POST /specialities/:id/{adopt,abandon,documents}. No rank gate:
+                 a speciality is how an expert's knowledge enters the platform,
+                 and gating that by rank would mean only trusted builders could
+                 be experts. -->
+            <section class="scroll" id="specialities-scroll" aria-labelledby="specialities-h" data-group="preferences" hidden>
+              <h2 id="specialities-h" class="scroll__h">Your specialities</h2>
+              <p class="scroll__lede">
+                A craft says how you work. A speciality says what you work on — and how you,
+                as someone who knows the subject, want to be engaged inside it. Whichever one
+                you are using reaches every session where you hold a claim in that craft.
+                Train it by adding things you have written; it also picks things up on its own
+                as you work.
+              </p>
+              <ul class="prows" id="specialities-rows"></ul>
+
+              <form id="speciality-create" class="speciality-create">
+                <h3 class="speciality-create__h">Create one</h3>
+                <label class="speciality-field">
+                  <span>Name</span>
+                  <input type="text" name="name" maxlength="80" required placeholder="Economics" />
+                </label>
+                <label class="speciality-field">
+                  <span>Craft it sits under</span>
+                  <select name="discipline" required>
+                    <option value="">Pick one…</option>
+                    <option value="engineer">Engineer</option>
+                    <option value="ideator">Ideator</option>
+                    <option value="artist">Artist</option>
+                    <option value="ui">UI design</option>
+                  </select>
+                </label>
+                <label class="speciality-field">
+                  <span>Summary <small>(optional)</small></span>
+                  <input type="text" name="summary" maxlength="500" placeholder="Markets, incentives, and how to price them." />
+                </label>
+                <label class="speciality-field">
+                  <span>How Claude should engage you in it <small>(optional)</small></span>
+                  <textarea name="contract_md" rows="4" maxlength="4000" placeholder="Argue from mechanism, not vibes. Always name the assumption a number rests on."></textarea>
+                </label>
+                <label class="speciality-field">
+                  <span>Who can use it</span>
+                  <select name="visibility">
+                    <option value="private">Only me</option>
+                    <option value="project">Anyone in the owning project</option>
+                    <option value="public">Anyone on this instance</option>
+                  </select>
+                </label>
+                <label class="speciality-field speciality-field--check">
+                  <input type="checkbox" name="sellable" />
+                  <span>
+                    May be offered for sale later
+                    <small>Records your decision only — there is no marketplace yet, and nothing is listed anywhere.</small>
+                  </span>
+                </label>
+                <div class="speciality-actions">
+                  <button type="submit" class="btn">Create speciality</button>
+                </div>
+              </form>
+
+              <p class="settings-status" id="specialities-status" role="status" aria-live="polite"></p>
+            </section>
+
             <!-- WANDERING — how readily the agent opens off-task threads (task 1268).
                  GET/PATCH /api/bongos/me/wandering. Rank sets the default + ceiling; the
                  server clamps, so options above the rank cap render disabled. -->
@@ -398,6 +462,7 @@
      the same precedent and for the same reason — settings.js is against the
      1500-line ratchet, and this panel shares nothing with the rest of the page. -->
 <script src="/builders/settings-interaction.js?v=2026-09-15-interaction"></script>
+<script src="/builders/settings-specialities.js?v=2026-09-17-specialities"></script>
 <!-- task 1002518: the card-richness ladder. Own file on the same precedent —
      the panel grew from one switch to a rung picker with a derived default, and
      settings.js is against the 1500-line ratchet. -->

package/modules/lifecycle/db-claim-reads.js

@@ -21,7 +21,11 @@ async function getActiveClaimsForBuilder(builderId) {
     `SELECT c.id AS claim_id, c.task_id, c.worktree_name, c.claimed_at,
             c.head_sha, c.reserved_migration_number,
             c.release_requested_by, c.release_requested_at, c.release_requested_note,
-            t.title, t.touches, t.priority, t.credits_reward, t.version_id, t.module_key
+            t.title, t.touches, t.priority, t.credits_reward, t.version_id, t.module_key,
+            -- task 1003855: the craft of the claimed work. A speciality contract is
+            -- craft-scoped, so the Conductor needs to know which craft is in play
+            -- before it can pick the right one to inject.
+            t.discipline
        FROM claims c JOIN tasks t ON t.id = c.task_id
       WHERE c.builder_id = $1 AND c.released_at IS NULL
       ORDER BY c.claimed_at`,

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]