@bongos/core 1.17.0

package/src/bongos/db.js

@@ -0,0 +1,911 @@
+// src/bongos/db.js — the GDS core db RESIDUE after the lifecycle carve (BV1.R86 /
+// ADR 0093 §3). The build state machine (tasks·claims·versions·done-when·ship)
+// graduated to modules/lifecycle/db.js; what remains here is the non-lifecycle
+// residue the kernel + core read routes still own:
+//   • builder IDENTITY + admission (upsertBuilder, seatFirstAdminIfUnclaimed,
+//     getBuilderByGithubId, hasInvitedAccessRequest, linkAnthropicAccount,
+//     updateBuilderDisciplines) — auth.js imports these; they CANNOT live in a
+//     module (auth.js is kernel and may not require a module).
+//   • RANK + status MANAGEMENT (setBuilderRank/_applyRankChangeTx/RANKS,
+//     getLatestRankChangeForBuilder, deactivate/reactivateBuilder) — Archon-driven
+//     identity ops consumed by routes/builders.js, NOT the task lifecycle.
+//   • AUTH sessions (builder_sessions: createSession/lookupSession/revoke*/
+//     hasCliSession/SESSION_TTL_MS) — the token store auth.js drives.
+//   • TWIN / social reads (Discord link flow, karma feed, audit-log read, the
+//     grade-trend builderRollingAvgGrade the sessions BFG also consumes) + the
+//     security_docs store (the kernel security-PROPERTY plane, routes/security.js).
+//   • The art-pipeline Gemini-key leak (api.getBuilderGeminiKeyRow/…).
+// db-kernel.js (identity/audit/rank/withTx) stays the bounded kernel slice this
+// re-exports through, exactly as before (ADR 0091 §2). Pure SQL plumbing;
+// routing/auth lives elsewhere.
+//
+// sealSessionLog + _applyRankChangeTx (+ RANKS / singleRungPromotionError) + the
+// gradePassCount fragment are DELIBERATELY duplicated with modules/lifecycle/db.js
+// (ADR 0091 §2 boundary-forced duplication): the same close-row / rank-change /
+// grade-count SQL runs on both sides of the kernel↔module line — keep in sync.
+
+const { pool } = require('./pool');
+// Module seam (ADR 0083 / BV1.R43). The rank/status-change paths EMIT
+// `builder.box-reconcile-needed` AFTER COMMIT (best-effort) so the dev-box module
+// can reconcile a droplet a demotion/graduation implies — never a direct require
+// of the module.
+const seams = require('../module-seams');
+
+// Kernel db slice (BV1.R69 / ADR 0091 §2): builder IDENTITY (getBuilderById),
+// the AUDIT log (insertAuditLog), the RANK ladder (LIVE_RANK_LADDER), and the
+// transaction primitive (withTx) live in the bounded ./db-kernel slice the
+// published doorway resolves through. Re-exported below so every caller is
+// byte-identical; db-kernel depends only on ./pool, never ./db (one-way).
+const {
+  withTx, getBuilderById, listActiveBuilders, insertAuditLog, LIVE_RANK_LADDER,
+  // Auth/identity/admission + the rank vocabulary carved to db-kernel (ADR 0102,
+  // finishing ADR 0091 §1). Re-exported below so db.js's other importers + its own
+  // internal uses (setBuilderRank's RANKS.indexOf, etc.) stay byte-identical.
+  RANKS, SESSION_TTL_MS, upsertBuilder, seatFirstAdminIfUnclaimed,
+  getBuilderByGithubId, hasInvitedAccessRequest, createSession, lookupSession,
+} = require('./db-kernel');
+
+// gradePassCount removed with builderRollingAvgGrade (its only core user) — that
+// grade-TREND read carved to modules/grading/db.js (ADR 0102), with this one-line
+// fragment inlined there. The modules/lifecycle/db.js twin of it is unaffected.
+
+// The shared `bounds`/`days` DAY_SERIES_CTE for the costSummary day-series
+// queries moved with costSummary into modules/economy/cost.js (BV1.R77 / ADR
+// 0093 §§1-2) — its only two callers left the monolith.
+
+// Seal a session_logs row inside an open transaction (ended_at is NOT NULL in
+// the schema, so a "sealed" log = the closing row). `outcome` stays a PARAMETER
+// — resolveClaim passes a variable ('shipped'/'partial'/'abandoned'), the two
+// release paths pass the literal 'abandoned' (audit §2B db-tx).
+
+async function sealSessionLog(client, { builderId, taskId, claimId, startedAt, outcome, notesMd }) {
+  await client.query(
+    `INSERT INTO session_logs (builder_id, task_id, claim_id, started_at, ended_at, outcome, notes_md)
+     VALUES ($1, $2, $3, $4, now(), $5, $6)`,
+    [builderId, taskId, claimId, startedAt, outcome, notesMd]
+  );
+}
+
+// The builder on the most-recent claim for a task (the worker who did the
+// work). Returns null when the task has no claim on record at all — each caller
+// supplies its OWN fallback (confirmer / requester / grade-caller) at the call
+// site, so that per-site drift is preserved (audit §2B db-deep, #538/#661).
+
+// upsertBuilder — carved to ./db-kernel (ADR 0102). Imported + re-exported above.
+
+// First-admin bootstrap (R62 / task 1201, ADR 0062). Replaces migration 023's
+// hard-coded founding-Archon literal: a fresh install seats its CONFIGURED
+// firstAdmin login as Archon, in code, at that account's first enrollment. The
+// guard is atomic and conservative — it elevates the row ONLY while NO Archon
+// exists yet, so it can never be used to escalate later (once an owner exists,
+// every call is a no-op) and it is race-safe under concurrent enrollment. Login
+// match is case-insensitive. Returns true iff this call seated the Archon.
+
+// seatFirstAdminIfUnclaimed — carved to ./db-kernel (ADR 0102). Re-exported above.
+
+// getBuilderById — the canonical builder-identity read — moved to ./db-kernel
+// (BV1.R69 / ADR 0091 §2: identity is a kernel primitive). Imported +
+// re-exported at the top of this file, so all callers are unchanged.
+
+// V3.R10 (#235), criterion C3: store the Anthropic account a builder attested to
+// during /builder-setup. `email` is what the builder confirmed; `userId` is the
+// accountUuid Claude Code reported from ~/.claude.json oauthAccount. It is kept
+// as optional cosmetic attribution only — NOT an auth boundary; the
+// X-Anthropic-User identity pin was removed (task 1039 / idea 258).
+// Idempotent: re-linking (e.g. re-running setup, or a builder switching machines)
+// just overwrites the stored pair. Returns the updated identity columns.
+
+async function linkAnthropicAccount(builderId, { email, userId }) {
+  const { rows } = await pool.query(
+    `UPDATE builders
+        SET anthropic_email = $2, anthropic_user_id = $3
+      WHERE id = $1
+      RETURNING id, anthropic_email, anthropic_user_id`,
+    [builderId, email ?? null, userId ?? null]
+  );
+  return rows[0] ?? null;
+}
+
+// getBuilderCostStatus() + autonomousApiSpendMtd() carved into
+// modules/economy/cost.js (BV1.R77 / ADR 0093 §1-2). Core resolves them via the
+// `reward` kernel port (me.js cost status; autonomy-gate.js reads them as a CLI).
+
+// recordAutonomyRun() + lastAutonomyHead() (the autonomy_runs slice) carved into
+// modules/autonomy/db.js (BV1.R83 / ADR 0093 §1). The MAS autonomy gate
+// (scripts/gds/autonomy-gate.js, a CLI) reads them directly from the module; core
+// never calls them. The autonomy_runs TABLE (migration 126) stays in core
+// migrations/ (the shared-schema additive rule).
+
+// setBuilderMonthlyBudget() carved into modules/economy/cost.js (BV1.R77 / ADR
+// 0093 §1-2). routes/builders.js resolves it via the `reward` kernel port.
+
+// setBuilderBoxBlocked + its box_blocked UPDATE RELOCATED to modules/dev-box/db.js
+// (BV1.R68 / ADR 0091 §3): box-blocked is cleanly dev-box-owned — the module is
+// its only writer AND reader (core never reads box_blocked) — so the query left
+// the core monolith with the doorway re-export when the slice pattern landed.
+
+// Approval-gated entry (2026-05-30). The web hall sign-in no longer auto-creates
+// an account for any GitHub user — a first-time visitor must be approved first
+// (an Archon marks their access_request 'invited'). These three small lookups
+// back that gate (used in auth.js completeWebFlow and the access-request form).
+
+// Does a builder row already exist for this stable GitHub numeric id? Returns a
+// minimal row or null. github_id is the stable key (login can change).
+
+// getBuilderByGithubId — carved to ./db-kernel (ADR 0102). Re-exported above.
+
+// Has an Archon approved this login (an access_requests row at status='invited',
+// case-insensitive)? This is the approval signal that lets a first-time web
+// sign-in through — and that the form uses to say "you're already approved".
+
+// hasInvitedAccessRequest — carved to ./db-kernel (ADR 0102). Re-exported above.
+
+// Replace a builder's preferred_disciplines (migrations 027 + 086). Input is
+// deduped, order-normalized, and validated against the disciplines THIS INSTANCE
+// offers — core (engineer, ideator) plus any enabled feature module's disciplines
+// (the art-pipeline module adds 'artist'), resolved via src/modules.js (R59 /
+// task 1198). The DB CHECK still enforces the full known enum
+// (engineer|artist|ideator) as a backstop; this is the instance-aware
+// friendly-error layer, so a vanilla instance with the art pipeline off rejects
+// 'artist' instead of silently storing an unofferable discipline. Returns the
+// updated builder row, or throws { code: 'invalid_discipline', bad } if any
+// element is not offered by this instance.
+
+async function updateBuilderDisciplines(builderId, disciplines) {
+  const { enabledDisciplines } = require('../modules');
+  const offered = enabledDisciplines();
+  const list = Array.isArray(disciplines) ? disciplines : [];
+  const bad = list.filter((d) => !offered.includes(d));
+  if (bad.length) {
+    const err = new Error(`invalid discipline(s): ${bad.join(', ')}`);
+    err.code = 'invalid_discipline';
+    err.bad = bad;
+    throw err;
+  }
+  const normalized = offered.filter((d) => list.includes(d));
+  const { rows } = await pool.query(
+    `UPDATE builders
+        SET preferred_disciplines = $2
+      WHERE id = $1
+      RETURNING id, github_id, github_login, display_name, avatar_url, total_credits, karma, created_at, rank, preferred_disciplines`,
+    [builderId, normalized]
+  );
+  return rows[0] ?? null;
+}
+
+// The builder-PREFS db slice — the five per-builder preference jsonb columns on
+// `builders` (skill_model_prefs / sound_prefs / behavior_prefs / event_sound_prefs)
+// — was carved into modules/builder-settings/db.js (BV1.R80 / ADR 0093 §1). Core
+// no longer reads/writes them: the `/me/*-prefs` routes moved to the module, and
+// the `GET /me` aggregator resolves the `builder-settings` kernel port for the
+// wandering/render/needs slices instead of importing those helpers directly.
+
+// ---- per-builder Gemini key, encrypted at rest (migration 122 / task 1013) ----
+//
+// The plaintext key NEVER touches the DB — the caller encrypts it with
+// src/bongos/secret-box.js (master key in server env only) and passes the opaque
+// blob + the last-4 chars for masked display. These three helpers are the only
+// readers/writers of the gemini_key_* columns.
+
+// Set/replace the builder's own key. `enc` is the secret-box blob; `last4` is the
+// plaintext's last 4 chars (for "…ABCD" display — not a secret). Returns the
+// masked metadata, never the blob.
+
+// setBuilderGeminiKey / clearBuilderGeminiKey / getBuilderGeminiKeyRow RELOCATED to
+// modules/art-pipeline/db.js (ADR 0102) — the art module owns the gemini_key_*
+// credential store + registers the 'art.getBuilderGeminiKeyRow' port; core me.js
+// resolves that port (degrades to a no-key shape on a vanilla instance).
+
+// Remove the builder's own key (back to "not set"). Returns { set: false }.
+
+
+// Read the raw row for the builder's own key: { enc, last4, set_at }. `enc` is the
+// still-encrypted blob — the caller decrypts with secret-box when it needs the
+// plaintext (only the own-scoped /me/art-key delivery does). Returns
+// { enc: null, ... } when no key is set.
+
+
+// leaderboard() carved into modules/economy/credits.js (BV1.R77 / ADR 0093 §1-2).
+// Core read routes resolve it via the `reward` kernel port.
+
+// The full reserved rank ladder (matches the CHECK enum in migration 023).
+// LIVE in V3: 'archon' (top), 'metic' (Archon-approved working rank — full
+// claim/ship + triage/blocker/planning/priority; task #360 / ADR 0018),
+// 'thetes' (the GRADUATED-newcomer rank — added in #692 / ADR 0034: claims the
+// whole general queue but NO scope-shaping/trust powers; a Xenos auto-graduates
+// here after THETES_GRADUATION_THRESHOLD successfully SHIPPED tasks), and 'xenos' (the
+// sandboxed entry rank new builders default to since migration 029 — claims
+// ONLY newcomer_friendly tasks). The rest stay reserved so future ranks never
+// need a schema change. The DB CHECK is the backstop — this set lets the API
+// give a clean 400 instead of leaking a constraint-violation 500.
+//
+// ORDER IS LOAD-BEARING: setBuilderRank uses RANKS.indexOf to decide
+// promotion-vs-demotion (lower index = higher rank). So the live ladder must
+// read archon > metic > thetes > xenos — thetes sits BETWEEN metic and xenos.
+
+// RANKS — carved to ./db-kernel (ADR 0102); imported + re-exported above. Order is
+// load-bearing (setBuilderRank's RANKS.indexOf below) and stays TWINNED with
+// modules/lifecycle/db.js.
+
+// THETES auto-graduation (#692 / ADR 0034; trigger corrected in #704). A Xenos
+// who has this many SUCCESSFULLY SHIPPED tasks (tasks.status='shipped',
+// attributed via tasks.shipped_by) is promoted xenos→thetes the moment the Nth
+// ship lands. The signal is SHIPPED, not confirmed — a task only counts once it
+// is merged + deployed, per the Archon rule "after 3 tasks are successfully
+// shipped." Pure decision helper is exported so tests/rank_gate.mjs can exercise
+// the threshold without a DB.
+
+function singleRungPromotionError(oldRank, newRank) {
+  const a = REQUIRES_RANK_TIER[oldRank];
+  const b = REQUIRES_RANK_TIER[newRank];
+  if (!a || !b) return null;     // one side is off the live ladder — not our gate
+  if (b <= a) return null;       // demotion or lateral — unconstrained here
+  if (b - a === 1) return null;  // exactly one rung up — allowed
+  return {
+    code: 'MULTI_RUNG_PROMOTION',
+    from: oldRank,
+    to: newRank,
+    next_rung: LIVE_RANK_LADDER[a], // rank at tier a+1 (ladder is 0-based)
+  };
+}
+
+// disambiguateWorktreeName — V3.R51 (#270). Two simultaneously-ACTIVE claims
+// must never share a worktree_name: `.claude/worktrees/<name>` is a filesystem
+// path, and two live builders pointing at the same one would stomp each other.
+// This is NOT a refusal (unlike ALREADY_CLAIMED / TOUCHES_CONFLICT) — we
+// silently append a numeric suffix and let the claim succeed, returning the
+// disambiguated name so the caller knows what they actually got.
+//
+// `taken` is the set of worktree_names held by currently-ACTIVE claims only
+// (released_at IS NULL). A name freed by a resolved/shipped claim is freely
+// reusable WITHOUT a suffix — this is load-bearing for the overnight builder,
+// which reuses ONE worktree_name across sequential tasks (it ships, freeing the
+// claim, before claiming the next). Keying off historical claims would break it.
+//
+// Suffix scheme: "name" → "name-2" → "name-3" … (first collision becomes -2,
+// matching git-worktree / file-manager conventions). A null/empty desired name
+// has nothing to collide on, so it's returned unchanged. Pure + exported so
+// tests can exercise it without a DB; claimTask calls it inside the txn.
+
+async function _applyRankChangeTx(client, { builderId, newRank, actorBuilderId, reasonNote = null, enforceSingleRungPromotion = false }) {
+  const { rows } = await client.query(
+    `SELECT id, rank, status FROM builders WHERE id = $1 FOR UPDATE`,
+    [builderId]
+  );
+  const target = rows[0];
+  if (!target) throw { code: 'BUILDER_NOT_FOUND' };
+  const oldRank = target.rank;
+  if (oldRank === newRank) throw { code: 'RANK_UNCHANGED', rank: oldRank };
+
+  // #707 — manual promotions advance ONE live rung at a time. Checked here
+  // (atomic, under the FOR UPDATE lock) but only when the caller opts in; the
+  // automatic xenos→thetes graduation (always +1) does not.
+  if (enforceSingleRungPromotion) {
+    const rungErr = singleRungPromotionError(oldRank, newRank);
+    if (rungErr) throw rungErr;
+  }
+
+  const { rows: updated } = await client.query(
+    `UPDATE builders SET rank = $2 WHERE id = $1
+     RETURNING id, github_id, github_login, display_name, avatar_url, total_credits, created_at, rank`,
+    [builderId, newRank]
+  );
+
+  // V3.R28 / #249 — ceremony delta. Promotion (moving UP the ladder = lower
+  // index in RANKS) earns +5; demotion is audit-only (0).
+  const oldIdx = RANKS.indexOf(oldRank);
+  const newIdx = RANKS.indexOf(newRank);
+  const isPromotion = oldIdx !== -1 && newIdx !== -1 && newIdx < oldIdx;
+  const isDemotion = oldIdx !== -1 && newIdx !== -1 && newIdx > oldIdx;
+  const delta = isPromotion ? 5 : 0;
+  // reason is the join key for downstream pickup; the human-readable text stays
+  // in `description`. The "by builder#N" clause is load-bearing — the rank-change
+  // greeting parser (getLatestRankChangeForBuilder) matches on it — so an
+  // automatic promotion (#692) keeps it (actor = the builder themselves) and
+  // APPENDS the "auto-graduation: …" note rather than replacing it.
+  const description = reasonNote
+    ? `rank_change: ${oldRank}→${newRank} by builder#${actorBuilderId} (${reasonNote})`
+    : `rank_change: ${oldRank}→${newRank} by builder#${actorBuilderId}`;
+  await client.query(
+    `INSERT INTO credit_log (builder_id, task_id, delta, reason, description)
+     VALUES ($1, NULL, $2, 'rank_change', $3)`,
+    [builderId, delta, description]
+  );
+
+  // V3.R38 / #259 — DEMOTION hook for criterion C7 (rank-change-near-instant).
+  // Revoke every active session in the same transaction so the demoted builder's
+  // CLI tokens stop working on their next API call. Combined with requireBuilder
+  // re-reading rank from the DB per request (ADR 0016), this is belt-and-braces.
+  // Promotion never revokes — we don't log someone out for getting a raise.
+  let demotionRevoked = 0;
+  if (isDemotion) {
+    const { rowCount } = await client.query(
+      `UPDATE builder_sessions
+          SET revoked_at = now()
+        WHERE builder_id = $1 AND revoked_at IS NULL`,
+      [builderId]
+    );
+    demotionRevoked = rowCount;
+  }
+
+  return {
+    builder: updated[0],
+    previous_rank: oldRank,
+    status: target.status,
+    sessions_revoked: demotionRevoked,
+    direction: isPromotion ? 'promotion' : isDemotion ? 'demotion' : 'lateral',
+    credit_delta: delta,
+  };
+}
+
+
+async function setBuilderRank({ builderId, newRank, actorBuilderId }) {
+  const result = await withTx(async (client) => {
+    return _applyRankChangeTx(client, { builderId, newRank, actorBuilderId, enforceSingleRungPromotion: true });
+  });
+  // Source-access clawback (ADR 0031 §6 / #600). Post-commit, own connection,
+  // never throws — records the box reconcile this rank change implies (a demotion
+  // below the floor → deprovision; a graduation up → rescope). The CREDENTIAL
+  // layer is already cut off live on the next /box/source-access fetch; this
+  // just signals + audits the slower droplet-level reconcile.
+  await seams.emitAsync('builder.box-reconcile-needed', {
+    builderId, rank: newRank, status: result.status, actor: `rank-change:builder#${actorBuilderId}`,
+  });
+  return {
+    builder: result.builder,
+    previous_rank: result.previous_rank,
+    sessions_revoked: result.sessions_revoked,
+    direction: result.direction,
+    credit_delta: result.credit_delta,
+  };
+}
+
+// maybeAutoGraduateToThetes — #692 / ADR 0034 (trigger corrected #704). Call
+// INSIDE the SHIP transaction (shipTask) AFTER the task flips to 'shipped',
+// passing the task's attributed builder (tasks.shipped_by). If that builder is a
+// Xenos who now has THETES_GRADUATION_THRESHOLD successfully SHIPPED tasks,
+// promote them xenos→thetes atomically with the ship and return the rank-change
+// result (so the caller fires the post-commit box reconcile). Returns null when
+// no graduation happened. Idempotent: rank-guarded (only a current Xenos
+// graduates) and counts SHIPPED tasks by attribution, so it fires exactly once
+// per builder. The actor is the builder themselves — a system-driven promotion.
+
+async function getLatestRankChangeForBuilder(builderId) {
+  // Match both schemas:
+  //   post-R28: reason = 'rank_change'
+  //   pre-R28:  reason LIKE 'rank_change:%'
+  const { rows } = await pool.query(
+    `SELECT id, builder_id, delta, reason, description, recorded_at
+       FROM credit_log
+      WHERE builder_id = $1
+        AND (reason = 'rank_change' OR reason LIKE 'rank_change:%')
+      ORDER BY id DESC
+      LIMIT 1`,
+    [builderId]
+  );
+  const row = rows[0];
+  if (!row) return null;
+  // The "rank_change: <old>→<new> by builder#<actor>" string lives in
+  // `description` (post-R28) or `reason` (pre-R28).
+  const text = row.description || row.reason || '';
+  // Tolerant parser — fall back to nulls if anything's off.
+  const m = text.match(/rank_change:\s*([a-z]+)\s*→\s*([a-z]+)\s*by builder#(\d+)/i);
+  const oldRank = m ? m[1] : null;
+  const newRank = m ? m[2] : null;
+  const actorId = m ? Number(m[3]) : null;
+  // Direction by ladder index — same definition as setBuilderRank itself.
+  let direction = null;
+  if (oldRank && newRank) {
+    const oi = RANKS.indexOf(oldRank);
+    const ni = RANKS.indexOf(newRank);
+    if (oi !== -1 && ni !== -1) {
+      direction = ni < oi ? 'promotion' : ni > oi ? 'demotion' : 'lateral';
+    }
+  }
+  return {
+    id: row.id,
+    builder_id: row.builder_id,
+    old_rank: oldRank,
+    new_rank: newRank,
+    actor_builder_id: actorId,
+    delta: row.delta,
+    direction,
+    recorded_at: row.recorded_at,
+  };
+}
+
+// Graceful builder exit (V3.R88 #307). Deactivating a builder is reversible
+// and lossless: drachmae (credits) + credit_log, shipped tasks, and historical
+// session_logs all stay. What changes: status → inactive (blocks new claims via
+// claimTask's guard), rank → 'xenos' (sandboxed tier), active claims released
+// cleanly with a final 'abandoned' session_log sealing each, and the tasks
+// returned to 'ready' for someone else. Reactivation flips status back; rank
+// is NOT auto-restored (an Archon re-promotes deliberately via PATCH
+// /builders/:id/rank). Memory archival is local-first and handled by the
+// /builder-exit skill — the server never holds another builder's local memory
+// (the server-side memory store is criterion #54's job, not this task's).
+
+async function deactivateBuilder({ builderId, reason, actorBuilderId }) {
+  const { updated, activeClaims } = await withTx(async (client) => {
+    const { rows } = await client.query(
+      `SELECT id, rank, status FROM builders WHERE id = $1 FOR UPDATE`,
+      [builderId]
+    );
+    const target = rows[0];
+    if (!target) throw { code: 'BUILDER_NOT_FOUND' };
+    if (target.status === 'inactive') throw { code: 'ALREADY_INACTIVE' };
+
+    // Release every active claim, seal each with a final session_log, and
+    // return the task to 'ready' so the work isn't stranded.
+    const { rows: activeClaims } = await client.query(
+      `SELECT id AS claim_id, task_id, claimed_at FROM claims
+        WHERE builder_id = $1 AND released_at IS NULL FOR UPDATE`,
+      [builderId]
+    );
+    for (const c of activeClaims) {
+      await client.query(
+        `UPDATE claims SET released_at = now(), outcome = 'abandoned' WHERE id = $1`,
+        [c.claim_id]
+      );
+      // Only bounce the task back to 'ready' if it's still mid-flight.
+      await client.query(
+        `UPDATE tasks SET status = 'ready' WHERE id = $1 AND status = 'active'`,
+        [c.task_id]
+      );
+      // Seal an outstanding session_log (ended_at is NOT NULL in the schema,
+      // so "sealing" = writing the closing abandoned-on-exit row).
+      await sealSessionLog(client, {
+        builderId, taskId: c.task_id, claimId: c.claim_id, startedAt: c.claimed_at,
+        outcome: 'abandoned',
+        notesMd: `Claim released on builder exit (graceful deactivation by builder#${actorBuilderId}).`,
+      });
+    }
+
+    const { rows: updated } = await client.query(
+      `UPDATE builders
+          SET status = 'inactive', deactivated_at = now(),
+              deactivated_reason = $2, reactivated_at = NULL, rank = 'xenos'
+        WHERE id = $1
+        RETURNING id, github_id, github_login, display_name, avatar_url,
+                  total_credits, created_at, rank, status,
+                  deactivated_at, reactivated_at, deactivated_reason`,
+      [builderId, reason ?? null]
+    );
+    // Interim audit (→ audit_log when R36 lands). delta=0 = no-op for credits.
+    await client.query(
+      `INSERT INTO credit_log (builder_id, task_id, delta, reason)
+       VALUES ($1, NULL, 0, $2)`,
+      [builderId, `builder_exit: deactivated by builder#${actorBuilderId} (rank ${target.rank}→xenos)`]
+    );
+    // SECURITY (#871): revoke EVERY live session for the offboarded builder, in
+    // the same transaction. Before this, deactivateBuilder set status='inactive'
+    // + rank='xenos' via direct SQL (not setBuilderRank, which is the only path
+    // that revokes on demotion), so a deactivated/offboarded builder kept working
+    // CLI bearer tokens (which don't expire) and could still reach the API. This
+    // is the server-side teardown that pairs with the requireBuilder status gate;
+    // a genuine return requires re-auth (correct — they were offboarded).
+    await client.query(
+      `UPDATE builder_sessions SET revoked_at = now()
+        WHERE builder_id = $1 AND revoked_at IS NULL`,
+      [builderId]
+    );
+    return { updated, activeClaims };
+  });
+  // Source-access clawback (ADR 0031 §6 / #600): a deactivated builder loses
+  // their box → loses source. Post-commit, own connection, never throws. The
+  // builder is now status='inactive' (rank forced to xenos above), so the
+  // reconcile resolves to 'deprovision'. Their next /box/source-access fetch is
+  // already 403'd (inactive) — this signals the droplet teardown for `box.js
+  // reconcile` / the dormant sweep.
+  await seams.emitAsync('builder.box-reconcile-needed', {
+    builderId, rank: 'xenos', status: 'inactive', actor: `builder-exit:builder#${actorBuilderId}`,
+  });
+  return {
+    builder: updated[0],
+    claims_released: activeClaims.map((c) => c.task_id),
+    logs_sealed: activeClaims.length,
+  };
+}
+
+
+async function reactivateBuilder({ builderId, actorBuilderId }) {
+  return withTx(async (client) => {
+    const { rows } = await client.query(
+      `SELECT id, status FROM builders WHERE id = $1 FOR UPDATE`,
+      [builderId]
+    );
+    const target = rows[0];
+    if (!target) throw { code: 'BUILDER_NOT_FOUND' };
+    if (target.status !== 'inactive') throw { code: 'NOT_INACTIVE', status: target.status };
+
+    const { rows: updated } = await client.query(
+      `UPDATE builders
+          SET status = 'active', reactivated_at = now()
+        WHERE id = $1
+        RETURNING id, github_id, github_login, display_name, avatar_url,
+                  total_credits, created_at, rank, status,
+                  deactivated_at, reactivated_at, deactivated_reason`,
+      [builderId]
+    );
+    // Rank is intentionally left at whatever it is (xenos after a deactivation):
+    // an Archon re-promotes deliberately via PATCH /builders/:id/rank.
+    await client.query(
+      `INSERT INTO credit_log (builder_id, task_id, delta, reason)
+       VALUES ($1, NULL, 0, $2)`,
+      [builderId, `builder_exit: reactivated by builder#${actorBuilderId} (rank stays ${updated[0].rank})`]
+    );
+    return { builder: updated[0] };
+  });
+}
+
+// -------------------------------------------------------------------------
+// Sessions (auth tokens)
+// -------------------------------------------------------------------------
+//
+// V3.R38 / task #259 — short-lived sessions with refresh-on-use.
+// V3.R90 / task #400 (2026-05-29) — TTL widened from 1h to 24h.
+//
+//   * Every NEW session (CLI or web) defaults to a 24-hour TTL. The caller may
+//     still pass an explicit expiresAt to override (web flow uses 30 days for
+//     the cookie's max-age, but the SERVER-SIDE row still uses 24h + roll-on-use
+//     so a logged-out browser tab in someone's history can't be replayed weeks
+//     later).
+//   * Every successful lookupSession bumps BOTH last_used_at AND expires_at to
+//     NOW() + 24h. This is the "refresh-on-use" half: an actively-used session
+//     stays valid; an idle session expires after 24h. The bump is fire-and-
+//     forget — it's an optimization for the next request, not a precondition
+//     for THIS request, so we don't add request latency by awaiting it.
+//   * Migration 035 backfilled all pre-existing rows with a 24h grace runway
+//     so deploying the V3.R38 change didn't kick the supervisor / mid-flow
+//     builders. With the V3.R90 TTL = 24h, the refresh window matches that
+//     grace formula exactly — no further migration needed.
+//   * The 1h value originally backstopped C7 (rank-change-near-instant), but
+//     setBuilderRank already calls revokeAllSessionsForBuilder on every
+//     demotion (see below), so the TTL is no longer load-bearing for C7. Its
+//     remaining job is idle-session hygiene under C9 (security baseline).
+//     24h still kills idle sessions overnight; an active builder no longer
+//     gets kicked out over lunch.
+
+// Session TTL on refresh / creation, in milliseconds. Centralized so the
+// migration's grace formula, the test suite, and the code agree on one number.
+
+// SESSION_TTL_MS — carved to ./db-kernel (ADR 0102); imported + re-exported above.
+
+
+// createSession — carved to ./db-kernel (ADR 0102). Re-exported above.
+
+// Has this builder ever authenticated the GDS CLI? (#777) True once they've run
+// /builder-setup (or the box-connect bootstrap) — both mint a source='cli'
+// session via the device flow. Revoked/expired sessions still count (rows are
+// marked, never deleted — see revokeAllSessionsForBuilder), so this is a durable
+// "the CLI was signed in at least once" signal. Drives the onboarding checklist's
+// "Run /builder-setup" step (auto-ticks; no manual mark) — purely a display
+// signal, never gates graduation.
+
+async function hasCliSession(builderId) {
+  if (!Number.isFinite(Number(builderId))) return false;
+  const { rows } = await pool.query(
+    `SELECT EXISTS (
+       SELECT 1 FROM builder_sessions WHERE builder_id = $1 AND source = 'cli'
+     ) AS has`,
+    [builderId]
+  );
+  return rows[0] ? rows[0].has === true : false;
+}
+
+
+// lookupSession — carved to ./db-kernel (ADR 0102). Re-exported above.
+
+
+async function revokeSession(token) {
+  await pool.query(
+    `UPDATE builder_sessions SET revoked_at = now() WHERE token = $1 AND revoked_at IS NULL`,
+    [token]
+  );
+}
+
+// revokeSessionById — V3.R38 / #259. Kill ONE session by primary key. Returns
+// the number of rows revoked (0 if id didn't exist or was already revoked, 1
+// otherwise). Used by POST /api/gds/auth/revoke (Archon-only).
+
+async function revokeSessionById(sessionId) {
+  const { rowCount } = await pool.query(
+    `UPDATE builder_sessions
+        SET revoked_at = now()
+      WHERE id = $1 AND revoked_at IS NULL`,
+    [sessionId]
+  );
+  return rowCount;
+}
+
+// revokeAllSessionsForBuilder — V3.R38 / #259. Kill EVERY non-revoked session
+// for a single builder. Returns the count of sessions revoked. Used by:
+//   * POST /api/gds/auth/revoke-all (Archon-only direct call)
+//   * setBuilderRank when newRank < oldRank (rank-change-near-instant per C7)
+
+async function revokeAllSessionsForBuilder(builderId) {
+  const { rowCount } = await pool.query(
+    `UPDATE builder_sessions
+        SET revoked_at = now()
+      WHERE builder_id = $1 AND revoked_at IS NULL`,
+    [builderId]
+  );
+  return rowCount;
+}
+
+// -------------------------------------------------------------------------
+// Versions
+// -------------------------------------------------------------------------
+
+
+async function recentKarmaForBuilder(builderId, limit = 10) {
+  const n = Math.min(Math.max(Number(limit) || 10, 1), 500);
+  const { rows } = await pool.query(
+    `SELECT k.id, k.delta, k.reason, k.recorded_at,
+            k.granted_by,
+            gb.github_login   AS granted_by_login,
+            gb.display_name   AS granted_by_display_name
+       FROM karma_log k
+       LEFT JOIN builders gb ON gb.id = k.granted_by
+      WHERE k.builder_id = $1
+      ORDER BY k.recorded_at DESC, k.id DESC
+      LIMIT $2`,
+    [builderId, n]
+  );
+  return rows;
+}
+
+// V3.R26 (#246): rolling 30-day karma delta for this builder. Powers the
+// "karma trend" stat on the /builders profile card — the done-when "30-day
+// delta" criterion. Returns a plain integer (0 when no karma_log rows fall in
+// the window) so the UI can render it directly without null-handling. Cheap
+// single-aggregate query; safe to call alongside the karma feed.
+
+async function karmaDelta30d(builderId) {
+  const { rows } = await pool.query(
+    `SELECT COALESCE(SUM(delta), 0)::int AS delta_30d
+       FROM karma_log
+      WHERE builder_id = $1
+        AND recorded_at >= now() - interval '30 days'`,
+    [builderId]
+  );
+  return rows[0]?.delta_30d ?? 0;
+}
+
+// -------------------------------------------------------------------------
+// Discord foundation (Phase 3 F1, ADR 0033)
+// -------------------------------------------------------------------------
+// Account links are 1:1 both ways and exist only because a builder PERSONALLY
+// linked their Discord (F2's UI-first OAuth) — the bot never invents a mapping.
+// Every write the bot later triggers re-checks the linked builder's LIVE rank
+// (ADR 0033 §1). Applause is the cosmetic tier: open to anyone, never karma.
+
+// Link a Discord user to a builder. Idempotent for the SAME builder (re-link
+// updates discord_user_id). Returns { ok:true, link } on success, or
+// { ok:false, error:'discord_taken' } if that Discord id is already linked to a
+// DIFFERENT builder (UNIQUE(discord_user_id)) — surfaced so F2's route answers
+// cleanly instead of 500-ing.
+
+async function linkDiscord({ builderId, discordUserId }) {
+  try {
+    const { rows } = await pool.query(
+      `INSERT INTO discord_links (builder_id, discord_user_id)
+       VALUES ($1, $2)
+       ON CONFLICT (builder_id)
+         DO UPDATE SET discord_user_id = EXCLUDED.discord_user_id, linked_at = now()
+       RETURNING builder_id, discord_user_id, linked_at`,
+      [builderId, discordUserId]
+    );
+    return { ok: true, link: rows[0] };
+  } catch (err) {
+    if (err.code === '23505') return { ok: false, error: 'discord_taken' }; // unique_violation
+    throw err;
+  }
+}
+
+// Remove a builder's Discord link. Returns true if a row was deleted.
+
+async function unlinkDiscord(builderId) {
+  const { rowCount } = await pool.query(
+    `DELETE FROM discord_links WHERE builder_id = $1`,
+    [builderId]
+  );
+  return rowCount > 0;
+}
+
+// The Discord link for a builder (so the hall can show "linked as ..." + an
+// Unlink affordance), or null.
+
+async function getDiscordLink(builderId) {
+  const { rows } = await pool.query(
+    `SELECT builder_id, discord_user_id, linked_at FROM discord_links WHERE builder_id = $1`,
+    [builderId]
+  );
+  return rows[0] || null;
+}
+
+// Record one cosmetic applause (a Discord user reacted on a shipped task).
+// NEVER writes karma_log — that separation is load-bearing (ADR 0033 §3).
+// Re-reacting is a harmless no-op. Returns { counted } — true if new, false if
+// this user had already applauded this task.
+
+async function recordApplause({ targetTaskId, discordUserId }) {
+  const { rowCount } = await pool.query(
+    `INSERT INTO discord_applause (target_task_id, discord_user_id)
+     VALUES ($1, $2)
+     ON CONFLICT (target_task_id, discord_user_id) DO NOTHING`,
+    [targetTaskId, discordUserId]
+  );
+  return { counted: rowCount > 0 };
+}
+
+
+// -------------------------------------------------------------------------
+// Task grades (PMS-V2 task 197)
+// -------------------------------------------------------------------------
+
+// Last N grades for tasks shipped by this builder (passed=true OR false —
+// the failed grades are interesting too).
+//
+// V3.R18 (#209): rubric_scores + signals.issues are now part of the response
+// so /me can surface the v2 subagent's failure detail (functional_fidelity vs
+// code_quality + the issues array) without a follow-up call.
+
+// builderRollingAvgGrade RELOCATED to modules/grading/db.js (ADR 0102) — the
+// grade-TREND read behind the 'grade.builderRollingAvgGrade' port (core me.js +
+// the sessions BFG resolve it; degrades to a zero-grade shape when grading is off).
+
+// Per-builder grade breakdown over the last `days` days. Powers the MARKS
+// section of the Archon-only /watch page (#726) — "who is passing / failing
+// the grader". One row per builder who has at least one graded ship in the
+// window, joined through tasks.shipped_by. avg_score 0–10, pass_rate 0–1.
+
+async function listAuditLog({ limit = 100, offset = 0, builderId, method, surface } = {}) {
+  const where = [];
+  const params = [];
+  if (builderId) {
+    params.push(builderId);
+    where.push(`builder_id = $${params.length}`);
+  }
+  if (method) {
+    params.push(method);
+    where.push(`method = $${params.length}`);
+  }
+  if (surface) {
+    if (surface === 'none') {
+      where.push(`surface IS NULL`);
+    } else {
+      params.push(surface);
+      where.push(`surface = $${params.length}`);
+    }
+  }
+  const whereSql = where.length ? `WHERE ${where.join(' AND ')}` : '';
+  params.push(limit);
+  const limitParam = `$${params.length}`;
+  params.push(offset);
+  const offsetParam = `$${params.length}`;
+  const { rows } = await pool.query(
+    `SELECT id, builder_id, route, method, request_body_redacted,
+            response_status, ip, user_agent, surface, recorded_at
+       FROM audit_log
+       ${whereSql}
+       ORDER BY recorded_at DESC, id DESC
+       LIMIT ${limitParam} OFFSET ${offsetParam}`,
+    params
+  );
+  return rows;
+}
+
+// -------------------------------------------------------------------------
+// Session records (BFG session-inefficiency evaluator — 6D.1/6D.2, ADR 0027)
+// CARVED into modules/sessions/db.js (BV1.R82 / ADR 0093 §1): the
+// session_records data plane (upsertSessionRecord[WithReward], searchSessions,
+// summarizeSessions, getSessionById, listSessionsByBuilder, filterTaskIdsClaimedBy,
+// the order/limit/offset helpers + the shared filter clause) is now module-owned.
+// upsertSessionRecordWithReward resolves the economy `reward` kernel port inside
+// its own withTx; no core file calls these (the ship-time digest write is an HTTP
+// POST to the module's /sessions route). sumCreditsForTasks() left for
+// modules/economy/ at BV1.R77.
+// -------------------------------------------------------------------------
+
+// ---- 6D.6: grade-attempt log (ADR 0027) ----------------------------------
+
+// logGradeAttempt — append one grade ATTEMPT to grade_attempts (migration 064).
+// task_grades is upsert-unique (latest grade only), so this is the ONLY record
+// of re-grade thrash. BEST-EFFORT: it swallows its own errors and returns a
+// boolean — callers (db.applyGrade, post-commit) can never be broken by it. The
+// queryFn seam lets the unit test inject a throwing/recording stub (mirrors the
+// audit middleware's insertFn pattern).
+
+async function upsertSecurityDoc({ slug, title, contentMd }) {
+  const { rows } = await pool.query(
+    `INSERT INTO security_docs (slug, title, content_md)
+     VALUES ($1, $2, $3)
+     ON CONFLICT (slug) DO UPDATE
+       SET title      = EXCLUDED.title,
+           content_md = EXCLUDED.content_md,
+           updated_at = now()
+     RETURNING id, slug, title, content_md, created_at, updated_at`,
+    [slug, title, contentMd]
+  );
+  return rows[0];
+}
+
+// Fetch one doc (with content) by slug. Returns the row or null.
+
+async function getSecurityDoc(slug) {
+  const { rows } = await pool.query(
+    `SELECT id, slug, title, content_md, created_at, updated_at
+       FROM security_docs WHERE slug = $1`,
+    [slug]
+  );
+  return rows[0] ?? null;
+}
+
+// List doc METADATA — slug, title, updated_at, and the content size in chars
+// (char_length) — but NOT the content itself, so the list view never ships the
+// exploit bodies. Newest-updated first.
+
+async function listSecurityDocs() {
+  const { rows } = await pool.query(
+    `SELECT slug, title, updated_at, char_length(content_md) AS bytes
+       FROM security_docs
+      ORDER BY updated_at DESC, slug ASC`
+  );
+  return rows;
+}
+
+// ---------- server-side merge lease (task 585 / idea 124) ----------
+//
+// merge-lock.js serializes main-mutating merges within ONE machine (a filesystem lock). When
+// builders ship from DIFFERENT physical machines — each with its own checkout of main — a file
+// lock can't see across machines. This is the cross-machine counterpart: a TTL'd advisory lease
+// keyed on the merge target (default 'main'), handed out by the GDS API at merge time. Plain SQL,
+// NOT a session-scoped pg_advisory_lock (a pooled connection can't hold one across a builder's
+// local merge); a dead holder's lease auto-reclaims once expires_at passes. See
+// docs/recipes/multi-builder-merge.md and merge-lock.js (the intra-machine tier) — and
+// merge-lock.withServerMergeLease(), the composition helper a multi-machine ship wraps around it.
+
+// Atomically acquire OR renew the lease. Returns { acquired, holder, expires_at }; acquired=false
+// (with the current holder/expiry) means another holder owns an unexpired lease.
+// SECURITY (for the future route that wraps this): `holder` MUST be set server-side from the
+// authenticated builder's identity, never a client-supplied value — otherwise a builder could
+// forge a lease under another builder's name (or release theirs). holder is intentionally free
+// text (a machine/session label), not an FK, so the route owns that binding.
+
+module.exports = {
+  withTx,
+  upsertBuilder,
+  seatFirstAdminIfUnclaimed,
+  getBuilderById,
+  listActiveBuilders,
+  linkAnthropicAccount,
+  getBuilderByGithubId,
+  hasInvitedAccessRequest,
+  updateBuilderDisciplines,
+  RANKS,
+  setBuilderRank,
+  getLatestRankChangeForBuilder,
+  deactivateBuilder,
+  reactivateBuilder,
+  createSession,
+  lookupSession,
+  revokeSession,
+  revokeSessionById,
+  revokeAllSessionsForBuilder,
+  hasCliSession,
+  SESSION_TTL_MS,
+  LIVE_RANK_LADDER,
+  singleRungPromotionError,
+  recentKarmaForBuilder,
+  karmaDelta30d,
+  insertAuditLog,
+  listAuditLog,
+  linkDiscord,
+  unlinkDiscord,
+  getDiscordLink,
+  recordApplause,
+  upsertSecurityDoc,
+  getSecurityDoc,
+  listSecurityDocs,
+};