@bongos/core 1.19.316 → 1.19.318

package/modules/lifecycle/db-rank-authz.js

@@ -0,0 +1,446 @@
+// modules/lifecycle/db-rank-authz.js — rank ladder, claim permissions, rank changes + the xenos→thetes graduation.
+//
+// Carved out of modules/lifecycle/db.js by task 1003204 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original db.js lines 148-560 unchanged. db.js remains the facade that
+// re-exports every name, so every existing db call site is unchanged.
+//
+// THE BOUNDARY (ADR 0093 §1): this file reaches core ONLY through the published
+// doorway ../../src/module-api.js — never a core internal, never a sibling module.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { pool, LIVE_RANK_LADDER, RANK_TIER } = api;
+const seams = api;
+const { matchProtected } = api.permissionPathCheck;
+
+// -------------------------------------------------------------------------
+// Builders
+// -------------------------------------------------------------------------
+
+
+const RANKS = [
+  'olympian', 'hermes', 'oracle', 'demigod',
+  'archon', 'strategos', 'boule', 'aristoi', 'hippeis', 'zeugitai',
+  'metic', 'thetes', 'xenos', 'periokoi', 'doulos', 'helot',
+];
+
+// 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.
+
+const THETES_GRADUATION_THRESHOLD = 3;
+
+function qualifiesForThetesGraduation(rank, shippedCount) {
+  return rank === 'xenos' && Number(shippedCount) >= THETES_GRADUATION_THRESHOLD;
+}
+
+// GENERAL_QUEUE_RANKS — the live ranks allowed to claim any ready task (the
+// whole general queue). Everything NOT in this set is sandboxed (see
+// xenosClaimAllowed). LIVE_RANK_LADDER minus the sandboxed entry rank 'xenos':
+// thetes (graduated newcomer, #692 / ADR 0034) and up — derived (BV1.R108).
+
+const GENERAL_QUEUE_RANKS = new Set(LIVE_RANK_LADDER.filter((r) => r !== 'xenos'));
+
+// xenosClaimAllowed — the row-level half of the three-rank model (#360 / ADR
+// 0018; renamed in V3.R15 #239 to newcomer_friendly). The sandboxed entry rank
+// may claim a task ONLY if it's been explicitly opened (newcomer_friendly ===
+// true); the live general-queue ranks claim any ready task.
+//
+// #510: FAIL CLOSED. The old test was `if (rank !== 'xenos') return true`, which
+// failed OPEN — ANY rank that wasn't the literal string 'xenos' (a reserved rank
+// like 'helot', a legacy value, or a future typo) skipped the sandbox and could
+// claim any ready task. We now allowlist the live general-queue ranks instead:
+// the sandbox applies to 'xenos' AND every reserved/unknown/typo rank. The
+// privileged set is {thetes, metic, archon}, NOT just {metic, archon} — thetes
+// is the live graduated-newcomer rank (#692 / ADR 0034) and by design claims the
+// whole general queue (asserted in tests/rank_gate.mjs). This matches the
+// fail-closed posture rankAllowsTask already takes for unknown ranks.
+//
+// The parameter is named `newcomerFriendly` (the V3.R15 canonical name).
+// Pure + exported so tests/rank_gate.mjs can exercise it without a DB; claimTask
+// + claimTasksBatch both call it (composed with rankAllowsTask).
+
+// BV1.R106 (ADR 0151): this rank rule is no longer the primary gate — the claim
+// paths decide the queue axis on the PERMISSIONS `task.claim.any` /
+// `task.claim.newcomer` (claim-eligibility.js) and keep this as the fallback for a
+// builder whose role row the run-once compat backfill never created. It stays
+// exported: tests/rank_gate.mjs pins it, and it is the oracle the parity test in
+// tests/government_claim_eligibility.mjs compares the permission predicate against.
+
+function xenosClaimAllowed(rank, newcomerFriendly) {
+  if (GENERAL_QUEUE_RANKS.has(rank)) return true;
+  return newcomerFriendly === true;
+}
+
+// claimPermissionsFor — the builder's effective permission set for the claim
+// decision, read through the `governance` kernel PORT (never by importing the
+// module — the one-way rule, ADR 0083). Returns a Set, or NULL when authority
+// cannot be ESTABLISHED, which claimEligibilityAllows reads as "fall back to the
+// incumbent rank rule":
+//   • the governance module is not mounted (no port), or the resolver throws;
+//   • the builder resolves to ZERO permissions — i.e. they hold no role row.
+//     governance_002's backfill is run-once and nothing yet re-assigns a rank-role
+//     when a builder is created or re-ranked, so this is a live gap, not a theory.
+// Every seeded rank-role grants at least twelve permissions, so an empty set never
+// means "a real role that grants nothing" today.
+//
+// Called BEFORE the claim transaction opens: authority is a per-request read (ADR
+// 0016 — resolved server-side, uncached), and taking a second pool connection while
+// a tx holds FOR UPDATE locks is a needless deadlock/exhaustion hazard.
+async function claimPermissionsFor(builderId) {
+  const governance = seams.resolveOptional('government');
+  if (!governance || typeof governance.resolveBuilderPermissions !== 'function') return null;
+  try {
+    const keys = await governance.resolveBuilderPermissions(builderId);
+    if (!keys || keys.length === 0) return null;
+    return new Set(keys);
+  } catch (err) {
+    console.error('[gds] claim eligibility: permission resolve failed, falling back to the rank rule', err);
+    return null;
+  }
+}
+
+// V3.R82 (#301): the INVERSE of newcomer_friendly. Some tasks raise the floor
+// instead of opening the door — `requires_rank` is a per-task MINIMUM rank
+// that a builder must meet to claim. Default 'xenos' means "no extra gate"
+// (any builder can claim, subject to the existing xenos sandbox rule).
+//
+// The LIVE ranks form an ordered tier (ADR 0018; thetes added #692 / ADR 0034):
+//   xenos (1) < thetes (2) < metic (3) < archon (4)
+// A 'thetes' clears any requires_rank='xenos' (the default) task — i.e. the
+// whole general queue — but is blocked from requires_rank='metic'/'archon'.
+// Reserved ranks aren't live — if one is somehow stored on a builder row, we
+// fail closed (treat as below xenos / refuse). The DB CHECK on
+// tasks.requires_rank enforces the same enum so the column never holds a value
+// this helper can't compare.
+//
+// Pure + exported so tests/rank_gate.mjs can exercise it without a DB.
+// claimTask + claimTasksBatch both call it after xenosClaimAllowed; the two
+// gates compose without contradiction (see migration 044 for the rationale).
+
+// BV1.R108: no longer a hand-copied literal — the canonical map is DERIVED from
+// LIVE_RANK_LADDER in db-kernel and reaches this module through the doorway.
+// The local name survives because ~10 helpers below and the module export read it.
+const REQUIRES_RANK_TIER = RANK_TIER;
+
+function rankAllowsTask(builderRank, requiredRank) {
+  // Tasks default to requires_rank='xenos' (the NOT NULL DEFAULT on the
+  // column), so a null/undefined here means "no extra gate" — treat as xenos.
+  const needed = REQUIRES_RANK_TIER[requiredRank ?? 'xenos'];
+  if (!needed) {
+    // Bad value in the column (shouldn't happen — DB CHECK blocks it).
+    // Fail closed: refuse the claim so a future rank can't be silently bypassed.
+    return false;
+  }
+  const have = REQUIRES_RANK_TIER[builderRank];
+  if (!have) {
+    // Builder rank not in the live three. Fail closed.
+    return false;
+  }
+  return have >= needed;
+}
+
+// deriveRequiredRank — task 1498 / ADR 0085. The per-task requires_rank floor
+// (V3.R82 #301) shipped INERT: no create/edit path ever set it, so every task
+// sat at the 'xenos' default and the claim gate never bit. We now DERIVE a floor
+// from what a task touches + its sensitivity, reusing the SAME protected-path
+// matcher the trust boundary uses (permission-path-check.matchProtected) — one
+// source of truth for "this is sensitive" (ADR 0043). A task that touches the
+// rank/authz/ship-grade/deploy/migration core, or is flagged security_sensitive,
+// floors at 'metic' (the first trusted working rank — exactly the paths a
+// sub-Metic builder already cannot push to). Everything else stays 'xenos' (the
+// open general queue). NEVER auto-assigns 'archon': "only the Archon may claim
+// this" is a deliberate manual override, not something to infer.
+// Pure + exported so tests/rank_gate.mjs can exercise it without a DB.
+
+function deriveRequiredRank(touches, securitySensitive) {
+  if (securitySensitive === true) return 'metic';
+  const files = Array.isArray(touches) ? touches : [];
+  if (files.length > 0 && matchProtected(files).length > 0) return 'metic';
+  return 'xenos';
+}
+
+// highestRank — the higher-authority of two ranks (treating null/undefined/
+// unknown as the 'xenos' floor, tier 1). Composes the derived FLOOR with an
+// explicit/override rank: stored requires_rank is always max(floor, requested),
+// so an override can only RAISE the bar, never drop below the safety floor
+// (fail-closed). Pure + exported.
+
+function highestRank(a, b) {
+  const ta = REQUIRES_RANK_TIER[a] || 1;
+  const tb = REQUIRES_RANK_TIER[b] || 1;
+  const winner = ta >= tb ? a : b;
+  return REQUIRES_RANK_TIER[winner] ? winner : 'xenos';
+}
+
+// LIVE rank ladder, lowest→highest. The promotion ladder for the manual
+// one-rung rule (#707). Indexes are 0-based; live tier = index + 1, matching
+// REQUIRES_RANK_TIER.
+// LIVE_RANK_LADDER moved to ./db-kernel (BV1.R69 / ADR 0091 §2: the rank ladder
+// is a kernel primitive). Imported + re-exported at the top of this file; the
+// 0-based indexing note above still applies to the uses just below.
+
+// singleRungPromotionError — #707. The Archon rule: a MANUAL promotion may
+// advance a builder EXACTLY one live rung at a time (xenos→thetes→metic→archon).
+// Returns null when the change is allowed (a one-rung promotion, a demotion, a
+// lateral move, or an off-ladder/reserved rank on either side), or a structured
+// error object when a promotion skips ≥1 rung (e.g. xenos→metic, thetes→archon).
+// Pure + exported so tests/rank_gate.mjs can exercise it without a DB. Only the
+// manual chokepoint (setBuilderRank) enforces it; auto-graduation (always +1)
+// bypasses it.
+
+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)
+  };
+}
+
+// foldWorktreeName — task 1002522. The ONE normalization of an incoming
+// worktree_name, applied at every ingest point so the app guard
+// (shouldRefuseSessionClaim) and its DB backstop (core_204's index, keyed on
+// (creator_session_id, COALESCE(worktree_name, ''))) can never disagree about
+// which claims share a working tree.
+//
+// The index folds NULL to '' — so to Postgres an EMPTY-string name IS the
+// worktree-less group. The guard compared raw values, where '' !== null: it
+// waved through a ''-named claim beside a worktree-less one, and the INSERT
+// then failed the backstop with a 23505 the caller never earned. Whitespace-only
+// is the same case wearing a coat (`.claude/worktrees/<blank>` is the repo root,
+// not a tree), so it folds too, and surrounding whitespace is trimmed rather
+// than stored — an untrimmed name would key the index differently from the
+// trimmed one the guard compared.
+//
+// Fold ONCE, at ingest: claimTask/claimTasksBatch normalize before the INSERT,
+// so every stored name is already trimmed-or-NULL and the guard's comparison of
+// stored rows is exact. Pure + exported for DB-free tests.
+function foldWorktreeName(name) {
+  if (name == null) return null;
+  const trimmed = String(name).trim();
+  return trimmed === '' ? null : trimmed;
+}
+
+// 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.
+
+function disambiguateWorktreeName(desired, taken) {
+  if (desired === null || desired === undefined || desired === '') return desired;
+  const takenSet = taken instanceof Set ? taken : new Set(taken || []);
+  if (!takenSet.has(desired)) return desired;
+  for (let suffix = 2; ; suffix++) {
+    const candidate = `${desired}-${suffix}`;
+    if (!takenSet.has(candidate)) return candidate;
+  }
+}
+
+// setBuilderRank — the single chokepoint for rank changes (V3.R07 #232).
+// Transactional: re-reads the target's current rank under FOR UPDATE, flips
+// it, and writes an audit row to credit_log. The audit row's delta encodes
+// direction (V3.R28 / #249 ceremony):
+//   - Promotion (newIdx < oldIdx) → delta = +5 — small celebratory bonus so
+//     drachmae mirrors authority. The trigger on credit_log will roll +5 into
+//     builders.total_credits.
+//   - Demotion (newIdx > oldIdx)  → delta = 0  — audit-only, no shaming
+//     deduction. Demotions are dignified.
+//   - Cross-ladder (one rank not in RANKS — should be impossible since the
+//     API gates on RANKS, but the DB CHECK on builders.rank is the backstop)
+//     → delta = 0, treated as audit-only.
+// reason is always 'rank_change' so downstream queries (GET /me/pending-rank-
+// change, audit replay) can join on it cleanly. The full old→new + actor go
+// into the `description` column added by migration 031 — no parsing required.
+// The legacy `reason` text format ("rank_change: <old>→<new> by builder#<actor>")
+// is preserved verbatim too, so historical credit_log rows from before R28
+// remain parseable by the same code path.
+//
+// Returns the updated builder row, or throws { code:'BUILDER_NOT_FOUND' } /
+// { code:'RANK_UNCHANGED' }.
+// syncGovernanceRankRole — keep government_builder_ranks in step with builders.rank
+// (BV1.R95b, ADR 0151). This module's rank writer backs the automatic xenos→thetes
+// graduation, which had the same hole as the Archon-driven path: the rank moved and
+// the role did not, so a freshly-graduated Thetes kept the xenos role.
+//
+// Resolved through the `government.rankSync` kernel port (never a sibling require —
+// ADR 0083) and run on the CALLER's transaction client, so the rotation commits
+// atomically with the ship + graduation. A missing port (governance disabled) skips:
+// no role ⇒ zero permissions, fail-closed.
+//
+// TWINNED with src/bongos/db.js (the boundary-forced _applyRankChangeTx duplication,
+// ADR 0091 §2) — keep the two in sync.
+async function syncGovernanceRankRole(client, builderId, rank) {
+  const roleSync = seams.resolveOptional('government.rankSync');
+  if (!roleSync || typeof roleSync.syncRank !== 'function') return null;
+  return roleSync.syncRank(client, { builderId, rank });
+}
+
+// _applyRankChangeTx — the in-transaction CORE of a rank change, shared by the
+// Archon-driven setBuilderRank and the automatic xenos→thetes graduation in the
+// confirm paths (#692 / ADR 0034). Runs inside the CALLER's transaction/client
+// — it does NOT open or commit one. Locks the builder row, flips the rank,
+// writes the credit_log audit row (+5 ceremony on promotion, 0 otherwise), and
+// — on demotion — revokes live sessions so a stale token can't replay old
+// authority. Returns the audit shape (incl. the builder's `status`, so the
+// caller can fire the post-commit box reconcile on its OWN connection).
+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]
+  );
+
+  // BV1.R95b — rotate the seeded rank-role IN THIS TRANSACTION (removing the old one,
+  // not merely adding the new). Not try/catch-wrapped: a failure must roll the rank
+  // change back rather than leave rank and role disagreeing. See the twin in
+  // src/bongos/db.js.
+  await syncGovernanceRankRole(client, 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 maybeAutoGraduateToThetes(client, builderId) {
+  if (builderId == null) return null;
+  const { rows } = await client.query(`SELECT rank FROM builders WHERE id = $1`, [builderId]);
+  const rank = rows[0]?.rank;
+  if (rank !== 'xenos') return null;
+  const { rows: c } = await client.query(
+    `SELECT count(*)::int AS n FROM tasks
+      WHERE shipped_by = $1 AND status = 'shipped'`,
+    [builderId]
+  );
+  if (!qualifiesForThetesGraduation(rank, c[0].n)) return null;
+  return _applyRankChangeTx(client, {
+    builderId,
+    newRank: 'thetes',
+    actorBuilderId: builderId,
+    reasonNote: `auto-graduation: ${c[0].n} shipped tasks (#692)`,
+  });
+}
+
+// countShippedTasksForBuilder — #766. The number of successfully shipped tasks
+// attributed to a builder (tasks.shipped_by, status='shipped'). Drives the
+// onboarding checklist's "N of 3" ship counter (the 'ship_three' terminal
+// stage) and is the same count maybeAutoGraduateToThetes gates on. Returns 0
+// for a null/unknown builder.
+
+async function countShippedTasksForBuilder(builderId) {
+  if (builderId == null) return 0;
+  const { rows } = await pool.query(
+    `SELECT count(*)::int AS n FROM tasks WHERE shipped_by = $1 AND status = 'shipped'`,
+    [builderId]
+  );
+  return rows[0]?.n ?? 0;
+}
+
+// getLatestRankChangeForBuilder — V3.R28 / #249.
+// Returns the most recent credit_log row with reason='rank_change' for the
+// given builder, parsed into a shape the SessionStart hook + /me/pending-
+// rank-change route can consume directly. Returns null when the builder has
+// never had a rank change. The parser tolerates both the post-R28 format
+// (delta carries +5 / 0, description carries the legacy "a→b by #N" text)
+// and the pre-R28 format (reason carries the full text, description NULL).
+
+module.exports = {
+  RANKS,
+  REQUIRES_RANK_TIER,
+  THETES_GRADUATION_THRESHOLD,
+  claimPermissionsFor,
+  countShippedTasksForBuilder,
+  deriveRequiredRank,
+  disambiguateWorktreeName,
+  foldWorktreeName,
+  highestRank,
+  maybeAutoGraduateToThetes,
+  qualifiesForThetesGraduation,
+  rankAllowsTask,
+  singleRungPromotionError,
+  xenosClaimAllowed,
+};

package/modules/lifecycle/db-shared.js

@@ -0,0 +1,115 @@
+// modules/lifecycle/db-shared.js — shared SQL fragments + small pure helpers used across the lifecycle data layer.
+//
+// Carved out of modules/lifecycle/db.js by task 1003204 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original db.js lines 55-147 unchanged. db.js remains the facade that
+// re-exports every name, so every existing db call site is unchanged.
+//
+// THE BOUNDARY (ADR 0093 §1): this file reaches core ONLY through the published
+// doorway ../../src/module-api.js — never a core internal, never a sibling module.
+
+'use strict';
+
+
+// ---------------------------------------------------------------------------
+// Shared SQL fragments + small pure helpers (task 1087, C3 — dedup audit
+// 2026-06-14 §2A/§2B db-tx/db-deep). Each is behavior-neutral: the SQL helpers
+// produce strings byte-identical to the inlined copies they replace (modulo
+// whitespace, which SQL ignores), and the query helpers run the identical query
+// with the identical bound params. Per-site DRIFT that a naive merge would
+// break is preserved at the call site (documented per helper).
+// ---------------------------------------------------------------------------
+
+// median of a numeric array (sorts a COPY; the caller's array is left intact).
+function median(arr) {
+  const s = [...arr].sort((a, b) => a - b);
+  const mid = Math.floor(s.length / 2);
+  return s.length % 2 === 0 ? (s[mid - 1] + s[mid]) / 2 : s[mid];
+}
+
+// Smoke tasks (`__smoke__*`) are excluded from every public/analytics feed.
+// Unqualified `title` is safe to drop into a `tasks t LEFT JOIN builders b`
+// query too, since `builders` has no `title` column (audit §2B db-deep).
+
+const SMOKE_NOT_LIKE = `title NOT LIKE '\\_\\_smoke\\_\\_%' ESCAPE '\\'`;
+
+// stale-claim predicate over (claims c LEFT JOIN session_pulses sp): a claim is
+// stale when its last pulse — or, with no pulse, its claim time — is older than
+// the `param` ($N) hours value. NOTE: the two pulse.js sweeper copies use
+// `interval '1 minute'` (a different unit) in a separate module, so they are
+// intentionally NOT shared here (audit §2B db-deep).
+
+const staleClaimHourPredicate = (param) =>
+  `(sp.last_pulse_at IS NOT NULL
+                    AND sp.last_pulse_at < now() - (${param}::int * interval '1 hour'))
+               OR (sp.last_pulse_at IS NULL
+                    AND c.claimed_at    < now() - (${param}::int * interval '1 hour'))`;
+
+// grade pass-count fragment: SUM of passed-as-1. `col` is the (possibly
+// alias-qualified) boolean column ('passed' or 'g.passed'); { where } restricts
+// the sum to quality-graded rows via FILTER (task 1002652 — every aggregate
+// site passes gradeQualityWhere, and keeps coalesce on because FILTER can zero
+// out a group). { coalesce: false } preserved for callers that want a raw SUM.
+
+const gradePassCount = (col, { coalesce = true, where = null } = {}) => {
+  const filter = where ? ` FILTER (WHERE ${where})` : '';
+  const inner = `SUM(CASE WHEN ${col} THEN 1 ELSE 0 END)${filter}`;
+  return coalesce ? `COALESCE(${inner}, 0)::int` : `${inner}::int`;
+};
+
+// Quality-graded row predicate (task 1002652). Two task_grades shapes carry
+// score 0 / passed=false that are NOT quality verdicts and must never enter an
+// aggregate: a grader OUTAGE (#943 — signals.panel_outcome='unavailable',
+// rubric axes json-null) and a panel row whose gating axis
+// (functional_fidelity / code_quality) is json-null (an errored worker, not a
+// judged 0). jsonb_typeof + COALESCE keep legacy rows counted (missing keys /
+// SQL-NULL rubric_scores → typeof NULL → '' ≠ 'null') and keep the predicate
+// NULL-safe under NOT (a bare NULL operand would drop rows from the
+// n_unavailable bucket).
+
+const gradeQualityWhere = (alias = '') => {
+  const a = alias ? `${alias}.` : '';
+  return `(COALESCE(${a}signals->>'panel_outcome','') <> 'unavailable'
+           AND COALESCE(jsonb_typeof(${a}rubric_scores->'functional_fidelity'),'') <> 'null'
+           AND COALESCE(jsonb_typeof(${a}rubric_scores->'code_quality'),'') <> 'null')`;
+};
+
+// 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).
+
+async function mostRecentClaimHolderId(client, taskId) {
+  const { rows } = await client.query(
+    `SELECT builder_id FROM claims WHERE task_id = $1 ORDER BY claimed_at DESC, id DESC LIMIT 1`,
+    [taskId]
+  );
+  return rows[0]?.builder_id ?? null;
+}
+
+module.exports = {
+  SMOKE_NOT_LIKE,
+  gradePassCount,
+  gradeQualityWhere,
+  median,
+  mostRecentClaimHolderId,
+  sealSessionLog,
+  staleClaimHourPredicate,
+};