@bongos/core 1.17.0

package/modules/sessions/db.js

@@ -0,0 +1,326 @@
+'use strict';
+
+// modules/sessions/db.js — the session-records db slice (BV1.R82 / ADR 0093 §1).
+//
+// The BFG session-inefficiency evaluator's data plane (ADR 0027): the
+// session_records corpus the hall + the BFG search/deep-dive over. Carved out of
+// the ~5k-LOC src/bongos/db.js monolith alongside its route (routes/sessions.js) and
+// the BFG scorer (bfg.js). The module owns the QUERIES; the session_records table
+// + its migrations stay in core migrations/ (pre-module-system; the additive rule
+// — a NEW session migration belongs in modules/sessions/migrations/).
+//
+// THE BOUNDARY (the one rule): this slice reaches the kernel ONLY through the
+// published doorway `../../src/module-api.js` — the shared `pool`, the `withTx`
+// transaction primitive, and the economy `reward` kernel PORT (resolved, never a
+// sibling-module require). It must never `require()` a core internal directly.
+//
+// The token-reward half (upsertSessionRecordWithReward) is the ONE place a
+// session write touches another domain: it resolves the `reward` port and awards
+// the cost-plus session token reward INSIDE its own transaction, passing the tx
+// `client` so the credit write commits atomically with the digest upsert. The
+// economy module computes the drachmae; sessions owns the digest row. This is the
+// kernel-mediated module↔module seam (ADR 0083 / 0093 §2) — no module ever holds
+// a reference to another.
+
+const api = require('../../src/module-api');
+const { pool } = api;
+// `seams` is the doorway's kernel-mediated seam surface (resolveOptional/resolve).
+// upsertSessionRecordWithReward resolves the economy `reward` port through it —
+// the module↔module seam, never a sibling-module require (BV1.R77 / ADR 0093 §2).
+const seams = api;
+
+// -------------------------------------------------------------------------
+// Session records (BFG session-inefficiency evaluator — 6D.1, ADR 0027)
+// -------------------------------------------------------------------------
+
+// upsertSessionRecord — store/refresh one session's scrubbed digest. Keyed on
+// session_id (the Claude Code CLAUDE_CODE_SESSION_ID), so a session that ships
+// several tasks upserts ONCE and accumulates task_ids (set-union) rather than
+// creating duplicate rows. detail + metrics are jsonb; task_ids is bigint[].
+// builderId is taken from the authenticated caller at the route — never the
+// body — so a builder can only ever write their OWN session.
+// upsertSessionRecordTx — the session-digest upsert SQL, parameterized on an
+// `executor` (a pg Pool OR a connected client) so it can run standalone
+// (auto-commit) or inside a transaction alongside the token-reward award.
+// `modelUsage` is the per-model token map (task 1005) stored verbatim as jsonb
+// for audit + priced server-side for the cost-plus reward.
+async function upsertSessionRecordTx(executor, {
+  sessionId,
+  builderId,
+  taskIds = [],
+  drachmaeEarned = 0,
+  totalTokens = 0,
+  durationSeconds = null,
+  startedAt = null,
+  endedAt = null,
+  detail = [],
+  metrics = {},
+  modelUsage = {},
+}) {
+  const ids = Array.isArray(taskIds)
+    ? taskIds.map((n) => Number(n)).filter(Number.isFinite)
+    : [];
+  const { rows } = await executor.query(
+    `INSERT INTO session_records
+       (session_id, builder_id, task_ids, drachmae_earned, total_tokens,
+        duration_seconds, started_at, ended_at, detail, metrics, model_usage)
+     VALUES ($1, $2, $3::bigint[], $4, $5, $6, $7, $8, $9::jsonb, $10::jsonb, $11::jsonb)
+     ON CONFLICT (session_id) DO UPDATE SET
+       task_ids = (
+         SELECT COALESCE(array_agg(DISTINCT e ORDER BY e), '{}')
+         FROM unnest(session_records.task_ids || EXCLUDED.task_ids) AS e
+       ),
+       -- drachmae accumulates: each ship uploads once with the credit_log delta
+       -- for THAT ship's task(s), so summing across uploads = the session total.
+       drachmae_earned  = session_records.drachmae_earned + EXCLUDED.drachmae_earned,
+       total_tokens     = EXCLUDED.total_tokens,
+       duration_seconds = EXCLUDED.duration_seconds,
+       started_at       = EXCLUDED.started_at,
+       ended_at         = EXCLUDED.ended_at,
+       detail           = EXCLUDED.detail,
+       metrics          = EXCLUDED.metrics,
+       model_usage      = EXCLUDED.model_usage,
+       uploaded_at      = now()
+     -- Ownership guard: a row can only ever be updated by its own builder, so a
+     -- builder who guesses another's session_id cannot overwrite their record.
+     WHERE session_records.builder_id = EXCLUDED.builder_id
+     RETURNING id, session_id, builder_id, task_ids, drachmae_earned,
+               total_tokens, duration_seconds, uploaded_at`,
+    [
+      sessionId,
+      builderId,
+      ids,
+      Math.trunc(Number(drachmaeEarned) || 0),
+      Math.trunc(Number(totalTokens) || 0),
+      durationSeconds == null ? null : Math.trunc(Number(durationSeconds)),
+      startedAt,
+      endedAt,
+      JSON.stringify(detail ?? []),
+      JSON.stringify(metrics ?? {}),
+      JSON.stringify(modelUsage ?? {}),
+    ]
+  );
+  return rows[0] || null; // null only on the ownership-guard no-op (foreign session_id)
+}
+
+// Standalone (auto-commit) upsert — preserved signature for the backfill script
+// + tests that call it directly on the pool. No token reward on this path.
+async function upsertSessionRecord(opts) {
+  return upsertSessionRecordTx(pool, opts);
+}
+
+// upsertSessionRecordWithReward — ONE transaction: upsert the session digest
+// (incl. model_usage), then compute + award the idempotent cost-plus token
+// reward (task 1005, ADR 0054) and mirror token_reward_drachmae onto the row.
+// Returns the record augmented with { tokenReward }. The token reward is a
+// SEPARATE credit_log row (reason='session.token_reward'); total_credits is
+// bumped by the credit_log trigger only, never double-counted here.
+async function upsertSessionRecordWithReward(opts) {
+  return api.withTx(async (client) => {
+    const record = await upsertSessionRecordTx(client, opts);
+    let tokenReward = { drachmae: 0, trueCostUsd: 0, awarded: false, unknownModels: [] };
+    if (record) {
+      // record is non-null only when the ownership guard passed (the row is the
+      // caller's), so the reward is always attributed to the verified owner.
+      // Token reward lives in modules/economy/ (BV1.R77 / ADR 0093 §1-2):
+      // resolve the `reward` kernel port and award inside this same txn (the
+      // module↔module seam — no sibling require).
+      // task 1676: pass totalTokens so the reward can fall back to pricing the
+      // session's real token total when modelUsage is empty/unpriceable — the
+      // dev-box/CI agent path that historically paid $0 cost-plus (ADR 0097).
+      tokenReward = await seams.resolveOptional('reward').awardSessionTokenReward(
+        client, opts.builderId, opts.sessionId, opts.modelUsage || {}, opts.totalTokens || 0
+      );
+      if (tokenReward.awarded && tokenReward.drachmae > 0) {
+        await client.query(
+          `UPDATE session_records
+              SET token_reward_drachmae = token_reward_drachmae + $2
+            WHERE session_id = $1 AND builder_id = $3`,
+          [opts.sessionId, tokenReward.drachmae, opts.builderId]
+        );
+      }
+    }
+    return record ? { ...record, tokenReward } : null;
+  });
+}
+
+// ---- 6D.2: session search + fetch (read side, ADR 0027) -------------------
+
+// Safe ORDER BY whitelist — the ONLY value interpolated into the search SQL, so
+// it must never come raw from input. Unknown keys fall back to 'recent'. Pure +
+// exported so the mapping is unit-tested (SQL-injection guard).
+const SESSION_ORDER = Object.freeze({
+  recent: 'sr.uploaded_at DESC',
+  tool_errors: "COALESCE((sr.metrics->>'tool_error_count')::int, 0) DESC, sr.uploaded_at DESC",
+  tokens: 'sr.total_tokens DESC, sr.uploaded_at DESC',
+  duration: 'sr.duration_seconds DESC NULLS LAST, sr.uploaded_at DESC',
+  drachmae: 'sr.drachmae_earned DESC, sr.uploaded_at DESC',
+});
+function resolveSessionOrder(key) {
+  return Object.prototype.hasOwnProperty.call(SESSION_ORDER, key) ? SESSION_ORDER[key] : SESSION_ORDER.recent;
+}
+function clampSessionLimit(n) {
+  if (n == null) return 25; // absent → default (null/undefined treated alike)
+  const x = Number(n);
+  if (!Number.isFinite(x)) return 25;
+  return Math.max(1, Math.min(100, Math.trunc(x)));
+}
+// Pagination offset for the corpus search. Absent/garbage → 0 (first page).
+// Floors at 0 and caps at a sane ceiling so a hostile ?offset=1e30 can't ask
+// Postgres to skip an absurd row count. Pure + exported (unit-tested).
+function clampSessionOffset(n) {
+  if (n == null) return 0;
+  const x = Number(n);
+  if (!Number.isFinite(x)) return 0;
+  return Math.max(0, Math.min(1_000_000, Math.trunc(x)));
+}
+
+// sessionFilterClause — the shared parameterized WHERE used by BOTH searchSessions
+// (the page) and summarizeSessions (the corpus-wide tally), so the two can never
+// drift out of sync. Every filter is a bound parameter ($1..$7); nothing from the
+// caller is interpolated. Returns { clause, params } where clause is the body of
+// a WHERE (no leading 'WHERE'). Pure.
+function sessionFilterClause(f = {}) {
+  const clause = `($1::text   IS NULL OR b.rank = $1)
+        AND ($2::int    IS NULL OR b.karma >= $2)
+        AND ($3::int    IS NULL OR sr.drachmae_earned >= $3)
+        AND ($4::bigint IS NULL OR sr.total_tokens >= $4)
+        AND ($5::int    IS NULL OR COALESCE((sr.metrics->>'tool_error_count')::int, 0) >= $5)
+        AND ($6::int    IS NULL OR sr.duration_seconds >= $6)
+        AND ($7::int    IS NULL OR (now() - b.created_at) <= ($7 * interval '1 day'))`;
+  const params = [
+    f.rank ?? null,
+    f.minKarma ?? null,
+    f.minDrachmae ?? null,
+    f.minTokens ?? null,
+    f.minToolErrors ?? null,
+    f.minDurationSec ?? null,
+    f.maxTenureDays ?? null,
+  ];
+  return { clause, params };
+}
+
+// Summary projection (NO detail jsonb — that's only returned by getSessionById
+// for a deep-dive). Joins builders for the rank/karma/drachmae/tenure facets.
+const SESSION_SUMMARY_COLS = `
+  sr.id, sr.session_id, sr.builder_id, b.github_login, b.rank, b.karma,
+  b.total_credits AS builder_drachmae,
+  ROUND(EXTRACT(EPOCH FROM (now() - b.created_at)) / 86400)::int AS tenure_days,
+  sr.task_ids, sr.drachmae_earned, sr.total_tokens, sr.duration_seconds,
+  COALESCE((sr.metrics->>'tool_error_count')::int, 0)  AS tool_errors,
+  COALESCE((sr.metrics->>'assistant_turns')::int, 0)   AS assistant_turns,
+  sr.uploaded_at`;
+
+// searchSessions — cross-builder search over the corpus, filtered by session
+// facets AND joined builder facets (rank / karma / drachmae / tenure). All
+// filters are bound parameters; ORDER BY + LIMIT are whitelisted/clamped, so
+// there is no injection surface. Caller (route) gates this to the BFG principal
+// (Archon for now) and audits it.
+async function searchSessions(filters = {}) {
+  const f = filters || {};
+  const orderBy = resolveSessionOrder(f.order);
+  const limit = clampSessionLimit(f.limit);
+  const offset = clampSessionOffset(f.offset);
+  const { clause, params } = sessionFilterClause(f);
+  // limit/offset are clamped integers, never raw input — safe to interpolate;
+  // keeping them out of the param list keeps the $-indices aligned with the
+  // shared clause (which owns $1..$7).
+  const { rows } = await pool.query(
+    `SELECT ${SESSION_SUMMARY_COLS}
+       FROM session_records sr
+       JOIN builders b ON b.id = sr.builder_id
+      WHERE ${clause}
+      ORDER BY ${orderBy}
+      LIMIT ${limit} OFFSET ${offset}`,
+    params
+  );
+  return rows;
+}
+
+// summarizeSessions — corpus-wide aggregates for the SAME filter set as
+// searchSessions (so the Ledger's "Tally" reflects every matching session, not
+// just the visible page). Returns total row count + summed token/turn/error/
+// drachmae figures + distinct-builder count. Uses the shared filter clause so it
+// can't drift from the page query. Read-only; the route gates + audits it.
+async function summarizeSessions(filters = {}) {
+  const { clause, params } = sessionFilterClause(filters || {});
+  const { rows } = await pool.query(
+    `SELECT
+        COUNT(*)::int                                                       AS total,
+        COUNT(DISTINCT sr.builder_id)::int                                  AS builders,
+        COALESCE(SUM(sr.total_tokens), 0)::bigint                           AS tokens,
+        COALESCE(SUM(COALESCE((sr.metrics->>'assistant_turns')::int, 0)),0)::bigint AS turns,
+        COALESCE(SUM(COALESCE((sr.metrics->>'tool_error_count')::int, 0)),0)::bigint AS tool_errors,
+        COALESCE(SUM(sr.drachmae_earned), 0)::bigint                        AS drachmae
+       FROM session_records sr
+       JOIN builders b ON b.id = sr.builder_id
+      WHERE ${clause}`,
+    params
+  );
+  const r = rows[0] || {};
+  // bigint columns arrive as strings from pg — coerce to Number for the JSON
+  // (these totals are well within Number's safe-integer range).
+  return {
+    total: Number(r.total) || 0,
+    builders: Number(r.builders) || 0,
+    tokens: Number(r.tokens) || 0,
+    turns: Number(r.turns) || 0,
+    tool_errors: Number(r.tool_errors) || 0,
+    drachmae: Number(r.drachmae) || 0,
+  };
+}
+
+// getSessionById — one session's FULL record (incl. detail jsonb) for deep-dive.
+async function getSessionById(id) {
+  const { rows } = await pool.query(
+    `SELECT ${SESSION_SUMMARY_COLS}, sr.detail, sr.metrics
+       FROM session_records sr
+       JOIN builders b ON b.id = sr.builder_id
+      WHERE sr.id = $1`,
+    [Number(id)]
+  );
+  return rows[0] || null;
+}
+
+// listSessionsByBuilder — a builder's OWN sessions (self-serve summary list).
+async function listSessionsByBuilder(builderId, limit = 25) {
+  const { rows } = await pool.query(
+    `SELECT ${SESSION_SUMMARY_COLS}
+       FROM session_records sr
+       JOIN builders b ON b.id = sr.builder_id
+      WHERE sr.builder_id = $1
+      ORDER BY sr.uploaded_at DESC
+      LIMIT ${clampSessionLimit(limit)}`,
+    [builderId]
+  );
+  return rows;
+}
+
+// filterTaskIdsClaimedBy — the subset of taskIds the builder actually claimed
+// (the ownership signal for a session). Used by POST /sessions to drop foreign
+// task IDs so a builder can't pollute their session_records.task_ids with work
+// they never did.
+async function filterTaskIdsClaimedBy(builderId, taskIds) {
+  const ids = Array.isArray(taskIds) ? taskIds.map(Number).filter(Number.isFinite) : [];
+  if (ids.length === 0) return [];
+  const { rows } = await pool.query(
+    `SELECT DISTINCT task_id FROM claims WHERE builder_id = $1 AND task_id = ANY($2::bigint[])`,
+    [builderId, ids]
+  );
+  return rows.map((r) => Number(r.task_id));
+}
+
+module.exports = {
+  // write side (6D.1)
+  upsertSessionRecord,
+  upsertSessionRecordWithReward, // route entry point — upsert + token reward (task 1005)
+  // search + fetch (6D.2)
+  searchSessions,
+  summarizeSessions,
+  getSessionById,
+  listSessionsByBuilder,
+  filterTaskIdsClaimedBy,
+  resolveSessionOrder,
+  clampSessionLimit,
+  clampSessionOffset,
+};

package/modules/sessions/module.json

@@ -0,0 +1,10 @@
+{
+  "key": "sessions",
+  "title": "Sessions & BFG (session corpus · efficiency eval)",
+  "description": "The session-records corpus + its data plane (POST /sessions upload, the Archon-gated cross-builder /sessions/search + /sessions/:id deep-dive), the BFG 'read-the-room' cross-builder scorer (ADR 0026 §6B), and the session-pulse / stale-claim heartbeat helpers. A core-domain module carved out of the GDS core in BV1.R82 (ADR 0093 §1); default-on because every instance records its builders' sessions for the BFG. Like the memory module, sessions registers no port — core never calls back into it: the ship-time digest write is an HTTP POST to the module's own /sessions route, and the only outward dependency is the economy `reward` kernel PORT it resolves (session token reward + sumCreditsForTasks) at upload time.",
+  "coreVersion": "^1.10.0",
+  "default": true,
+  "contributes": { "routes": ["sessions"] },
+  "provides": [],
+  "consumes": []
+}

package/modules/sessions/pulse.js

@@ -0,0 +1,149 @@
+// modules/sessions/pulse.js — GDS session-pulse + stale-claim helpers.
+//
+// Task #37 — BUCKET C (Auto-logging). Provides the SQL plumbing for a
+// heartbeat-driven stale-claim detector. Pure DB helpers; no Express
+// routes here (route wiring is OUT of touches[] for this task and
+// deferred — see follow-up notes below).
+//
+// CARVED into modules/sessions/ (BV1.R82 / ADR 0093 §1) — a session-domain lib.
+// Reaches the kernel only through the published doorway `../../src/module-api.js`
+// (the shared `pool`); the CLI shell stays at scripts/gds/pulse.js.
+//
+// -------------------------------------------------------------------------
+// Open questions resolved per task description:
+//
+// 1. claims.pulse_lost_at column does NOT exist in migration 006
+//    (006 only adds the session_pulses table itself with PK claim_id +
+//    columns builder_id, last_pulse_at). Per the task's pragmatic-(b)
+//    decision, we DO NOT add a new migration here — adding one would
+//    introduce migrations/008_*.sql to touches[] and break drift
+//    discipline. Instead, sweepStaleClaims() returns the stale claim
+//    rows as data; a follow-up task is expected to add the marker
+//    column + UPDATE write + builder surface in /builder-start.
+//
+// 2. POST /api/gds/pulse route is NOT wired here — routes.js is out
+//    of touches[]. recordPulse() is exported for whichever future
+//    request handler is created. The CLI shell at scripts/gds/pulse.js
+//    posts to the intended endpoint and will start working once the
+//    route is mounted.
+//
+// Follow-up work (file new tasks when picked up):
+//   a) New migration adding claims.pulse_lost_at timestamptz.
+//   b) Route: POST /api/gds/pulse → recordPulse() (auth + claim
+//      ownership check).
+//   c) sweepStaleClaims() side-effect: UPDATE claims
+//      SET pulse_lost_at = now() WHERE id = ANY(...).
+//   d) Periodic sweep — 5-min setInterval inside the running Node
+//      process, or scheduled task.
+//   e) /builder-start surfaces "your previous claim went silent" using
+//      getStaleClaimsForBuilder().
+// -------------------------------------------------------------------------
+
+const { pool } = require('../../src/module-api');
+
+// Record a heartbeat for a claim. Idempotent UPSERT — the PK is
+// claim_id so repeated pulses just bump last_pulse_at.
+//
+// Caller is responsible for verifying the builder actually owns the
+// claim (do this in the route handler, not here).
+async function recordPulse(claimId, builderId) {
+  if (!Number.isFinite(Number(claimId)) || !Number.isFinite(Number(builderId))) {
+    throw new Error('recordPulse: claimId and builderId must be numeric');
+  }
+  const { rows } = await pool.query(
+    `INSERT INTO session_pulses (claim_id, builder_id, last_pulse_at)
+     VALUES ($1, $2, now())
+     ON CONFLICT (claim_id) DO UPDATE
+       SET last_pulse_at = now(),
+           builder_id    = EXCLUDED.builder_id
+     RETURNING claim_id, builder_id, last_pulse_at`,
+    [Number(claimId), Number(builderId)]
+  );
+  return rows[0];
+}
+
+// Identify claims that have gone silent. A claim is stale when it is
+// still open (released_at IS NULL) AND either:
+//   (a) it has a pulse row whose last_pulse_at is older than the
+//       threshold, or
+//   (b) it has no pulse row at all AND was claimed_at longer ago than
+//       the threshold (i.e. the builder never pulsed once, and they've
+//       had long enough that we assume they crashed).
+//
+// Returns: array of { claim_id, task_id, builder_id, claimed_at,
+// last_pulse_at } — caller (a future scheduled job) decides whether to
+// stamp a marker, release the claim, or notify the builder.
+//
+// This function is READ-ONLY by design (see open question #1 above);
+// the write-side marker is deferred to a follow-up task that owns
+// the migration.
+async function sweepStaleClaims({ thresholdMin = 30 } = {}) {
+  const threshold = Number(thresholdMin);
+  if (!Number.isFinite(threshold) || threshold <= 0) {
+    throw new Error('sweepStaleClaims: thresholdMin must be a positive number');
+  }
+  const { rows } = await pool.query(
+    `SELECT c.id          AS claim_id,
+            c.task_id     AS task_id,
+            c.builder_id  AS builder_id,
+            c.claimed_at  AS claimed_at,
+            sp.last_pulse_at AS last_pulse_at
+       FROM claims c
+       LEFT JOIN session_pulses sp ON sp.claim_id = c.id
+      WHERE c.released_at IS NULL
+        AND (
+              (sp.last_pulse_at IS NOT NULL
+                AND sp.last_pulse_at < now() - ($1::int * interval '1 minute'))
+           OR (sp.last_pulse_at IS NULL
+                AND c.claimed_at    < now() - ($1::int * interval '1 minute'))
+            )
+      ORDER BY c.claimed_at ASC`,
+    [threshold]
+  );
+  return rows;
+}
+
+// Stale claims that belong to a specific builder. Used by the future
+// /builder-start surface to warn the builder when their previous
+// claim has gone silent and may need release/reclaim.
+//
+// Today, "stale" is computed the same way as sweepStaleClaims() —
+// once a marker column exists (follow-up a), this can pivot to read
+// claims.pulse_lost_at IS NOT NULL instead.
+async function getStaleClaimsForBuilder(builderId, { thresholdMin = 30 } = {}) {
+  const builder = Number(builderId);
+  const threshold = Number(thresholdMin);
+  if (!Number.isFinite(builder)) {
+    throw new Error('getStaleClaimsForBuilder: builderId must be numeric');
+  }
+  if (!Number.isFinite(threshold) || threshold <= 0) {
+    throw new Error('getStaleClaimsForBuilder: thresholdMin must be a positive number');
+  }
+  const { rows } = await pool.query(
+    `SELECT c.id          AS claim_id,
+            c.task_id     AS task_id,
+            c.builder_id  AS builder_id,
+            c.claimed_at  AS claimed_at,
+            c.worktree_name AS worktree_name,
+            sp.last_pulse_at AS last_pulse_at
+       FROM claims c
+       LEFT JOIN session_pulses sp ON sp.claim_id = c.id
+      WHERE c.released_at IS NULL
+        AND c.builder_id = $1
+        AND (
+              (sp.last_pulse_at IS NOT NULL
+                AND sp.last_pulse_at < now() - ($2::int * interval '1 minute'))
+           OR (sp.last_pulse_at IS NULL
+                AND c.claimed_at    < now() - ($2::int * interval '1 minute'))
+            )
+      ORDER BY c.claimed_at ASC`,
+    [builder, threshold]
+  );
+  return rows;
+}
+
+module.exports = {
+  recordPulse,
+  sweepStaleClaims,
+  getStaleClaimsForBuilder,
+};