heyspex 0.1.0 → 0.2.0

package/spexharness/src/session-record.mjs

@@ -0,0 +1,815 @@
+// spexharness/src/session-record.mjs
+//
+// The harness's session record: what one bounded loop run (spexharness/src/loop.mjs) did.
+// A record carries the run itself — what was asked, the tool calls made in order, and what
+// the model produced — plus the events the harness saw (events.mjs) with the decision
+// decide.mjs made for each. This is the ONLY thing this module builds: the record. Per the
+// owner's ruling (research HS-9XWJ-KB6H, filed 2026-08-26), no training path, export, or
+// collector is built on top of it here — the classifier log, SpexDoctrine and any future
+// adapter work are separate mechanisms on the same engine, none feeding another's training
+// data from this module.
+//
+// Shape and persistence are modeled on dev-factory/lib/run-events.mjs — not a fresh
+// implementation of "append-only JSONL that survives a crash mid-write": one JSONL line per
+// record (open "a" + one writeSync + close, so concurrent writers never interleave into a
+// corrupt line), and a corrupt/partial trailing line is skipped on read rather than thrown.
+// The domain is different (one line = one whole session's record, not one lifecycle
+// transition), so this is a sibling module, not a re-export of run-events.mjs.
+//
+// Pure-ish: the record-building helpers (createSessionRecord, recordEvent, recordToolCall,
+// finishSessionRecord) do no I/O; only appendSessionRecord/readSessionRecords touch disk.
+//
+// ---------------------------------------------------------------------------------------
+// DURABLE SESSION STORE (task HS-WJIR, epic HS-Y646 AC4)
+// ---------------------------------------------------------------------------------------
+// The JSONL half above is per-machine: a record appended on `specops-gpu0` is invisible to a
+// seat opened on another box. The epic's fourth criterion — "a session closed on one machine
+// is resumed by id on another with its claims and WIP intact" — needs a shared store, so the
+// second half of this module adds one: a session record keyed by session id that carries the
+// session's CLAIMS, its hand-off WIP block and its TOOL-CALL LOG, backed by Neon.
+//
+// Storage is behind a two-method backend (`read`/`write`, plus optional `list`/`delete`) and
+// is INJECTABLE. Neon is the default; the tests inject an in-memory backend, so no test in
+// this package ever needs a live database or a DATABASE_URL. That split is the same posture
+// the rest of the harness takes with its loaders (see session-bootstrap.mjs's `loaders`).
+//
+// The Neon path is not a new connection style: it is the plain-.mjs pattern the repo already
+// uses off the Next.js app — a lazy `await import('@neondatabase/serverless')`, `neon(url)`,
+// and DATABASE_URL_UNPOOLED ?? DATABASE_URL ?? ~/.heyspex/credentials.yaml (identical to
+// scripts/backfill-active-claims-to-neon.mjs's --direct-db path). The row shape mirrors
+// spex-console's `wip_ledger` (`payload jsonb` + `updated_at`) rather than exploding the
+// record into columns, because the record's interior is the harness's own evolving shape and
+// the console never queries into it.
+
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { redactRecord } from './redact.mjs';
+
+/**
+ * Create a fresh, empty session record. Mutated in place by the record* helpers below as a
+ * loop runs, then persisted once via {@link appendSessionRecord}.
+ *
+ * @param {{ sessionId?: string|null, ask?: unknown }} [opts]
+ * @returns {{
+ *   sessionId: string|null,
+ *   ask: unknown,
+ *   startedAt: string,
+ *   events: Array<{ point: string, ts: number, decision: object|null }>,
+ *   toolCalls: Array<{ name: string|null, input: unknown, output: unknown }>,
+ *   confirms: Array<{ id: string|null, stepIndex: number|null, skill: string|null, approved: boolean, used: boolean, at: string }>,
+ *   output: string|null,
+ *   endedAt: string|null,
+ * }}
+ */
+export function createSessionRecord({ sessionId = null, ask = null } = {}) {
+  return {
+    sessionId,
+    ask, // what was asked — the run's initiating prompt/intent
+    startedAt: new Date().toISOString(),
+    events: [], // ordered — every gate-checked event point the harness saw, with its decision
+    toolCalls: [], // ordered — every tool call the loop made
+    // ordered — every confirm point a skill (skill-invoke.mjs's invokeSkill) or a scripted
+    // run (scripted-mode.mjs's scriptedConfirmHandler) answered, approved or not. This is the
+    // durable record spexharness/src/gates/confirm-gate.mjs reads to decide whether a
+    // promote/file tool call may proceed ([[HS-U0MC-NYPR-TASK-add-a-gate-that-refuses-a-promote-or]]).
+    confirms: [],
+    output: null, // what the model produced — the loop's final answer text
+    endedAt: null,
+  };
+}
+
+/**
+ * Append one answered confirm point to the record, in the order it was answered. The shape
+ * mirrors skill-invoke.mjs's own `confirms` entries (`{ id, stepIndex, approved, cues }`) so a
+ * caller wiring `invokeSkill`'s per-step confirm callback can record here with no translation.
+ * `skill` is optional context a caller may supply (skill-invoke.mjs's `plan.skill`) so
+ * {@link consumeApprovedConfirm} can match on it when no `id` is available.
+ *
+ * `used` starts `false` — an approval is a single-use token
+ * ([[HS-U0MC-NYPR-TASK-add-a-gate-that-refuses-a-promote-or]] QC fix: a session that answered
+ * ONE confirm must not unlock EVERY later confirm-required exit). Only
+ * {@link consumeApprovedConfirm} ever flips it to `true`.
+ *
+ * @param {ReturnType<typeof createSessionRecord>} record
+ * @param {{ id?: string|null, stepIndex?: number|null, skill?: string|null, approved: boolean }} confirm
+ * @returns {ReturnType<typeof createSessionRecord>} the same record, for chaining.
+ */
+export function recordConfirm(record, { id = null, stepIndex = null, skill = null, approved } = {}) {
+  record.confirms.push({
+    id,
+    stepIndex: stepIndex ?? null,
+    skill: skill ?? null,
+    approved: Boolean(approved),
+    used: false,
+    at: new Date().toISOString(),
+  });
+  return record;
+}
+
+/**
+ * Has ANY confirm point on `record` been recorded as approved? A read-only existence check —
+ * it does NOT consume anything and is unaffected by a prior {@link consumeApprovedConfirm}
+ * call, so it stays useful for "did this session ever answer a confirm at all" reporting.
+ * The engine's `before_tool` decision itself must never be gated on this alone — see
+ * {@link consumeApprovedConfirm}, which is the predicate spexharness/src/gates/confirm-gate.mjs
+ * actually runs before letting a promote/file tool call through.
+ *
+ * @param {{ confirms?: Array<{ approved?: boolean }> }|null|undefined} record
+ * @returns {boolean}
+ */
+export function hasApprovedConfirm(record) {
+  return Array.isArray(record?.confirms) && record.confirms.some((c) => c && c.approved === true);
+}
+
+/**
+ * Consume ONE approved, not-yet-used confirm off `record` and return whether one was found.
+ * This is the fix for the QC finding on {@link hasApprovedConfirm}'s old ANY-check: that
+ * predicate never marked anything used, so one approved confirm (e.g. a `/hs-capture`
+ * confirm) satisfied every later confirm-required exit in the session with no further
+ * confirm answered — filing 40 specs, then submitting for review, all on one "yes". A
+ * confirm is now a single-use token: the first gated call that consumes it marks it
+ * `used: true` on `record` (mutating in place, so the SAME record object a caller keeps
+ * passing to the gate sees the consumption on the very next check), and every subsequent
+ * confirm-required action needs a FRESH approved-and-unused entry.
+ *
+ * Matching (most to least specific, first match wins — matches the granularity the caller
+ * actually has available; see spexharness/src/gates/confirm-gate.mjs's header for why a
+ * bare `before_tool` event usually carries none of this):
+ *   1. `query.id` given — exact `id` match required (skill-invoke.mjs's `confirmPoint.id`,
+ *      e.g. `"hs-promote.step-3"`, or a caller-minted confirm id).
+ *   2. else `query.namespace` given — the entry's id must be that namespace exactly, or sit
+ *      under it (`<namespace>` + `.` / `:` / `/` + rest). See {@link confirmIdMatchesNamespace}.
+ *   3. else `query.skill` and/or `query.stepIndex` given — match whichever of those the
+ *      caller supplied, against entries that recorded the same field.
+ *   4. else (no query fields at all) — the oldest unused approved entry, in recorded order,
+ *      SKIPPING every namespace-BOUND entry (see {@link isNamespaceBoundConfirmId}): a
+ *      confirm answered for another gate's ask (`dev-server-control:start`) or for a
+ *      specific tool-level exit (`tool:heyspex_file_spec`) is bound to that ask and must be
+ *      claimed by name, never picked up by an unqualified "oldest unused" sweep.
+ * In every case only `approved === true && used !== true` entries are eligible.
+ *
+ * A caller-supplied `confirm: async () => true` handler can never satisfy this by itself —
+ * this function (and the gate calling it) reads only `record.confirms`, never a callback's
+ * return value, so a handler wired straight to `true` with no matching entry actually
+ * `recordConfirm`-ed on the session still gets refused.
+ *
+ * @param {ReturnType<typeof createSessionRecord>|null|undefined} record
+ * @param {{ id?: string|null, namespace?: string|null, skill?: string|null, stepIndex?: number|null }} [query]
+ * @returns {boolean} true (and marks the matched entry `used: true`) iff a match was consumed.
+ */
+export function consumeApprovedConfirm(
+  record,
+  { id = null, namespace = null, skill = null, stepIndex = null } = {},
+) {
+  if (!Array.isArray(record?.confirms)) return false;
+
+  const eligible = (c) => c && c.approved === true && c.used !== true;
+
+  let match = null;
+  if (id != null) {
+    match = record.confirms.find((c) => eligible(c) && c.id === id) ?? null;
+  } else if (namespace != null) {
+    match = record.confirms.find((c) => eligible(c) && confirmIdMatchesNamespace(c.id, namespace)) ?? null;
+  } else if (skill != null || stepIndex != null) {
+    match = record.confirms.find((c) => {
+      if (!eligible(c)) return false;
+      if (isNamespaceBoundConfirmId(c.id)) return false; // bound to another ask — claim by name only
+      if (skill != null && c.skill !== skill) return false;
+      if (stepIndex != null && c.stepIndex !== stepIndex) return false;
+      return true;
+    }) ?? null;
+  } else {
+    match = record.confirms.find((c) => eligible(c) && !isNamespaceBoundConfirmId(c.id)) ?? null;
+  }
+
+  if (!match) return false;
+  match.used = true;
+  return true;
+}
+
+/**
+ * The delimiters a confirm id uses between a namespace and the rest of the id. `.` is the
+ * skill-step shape (`hs-capture.step-2` — skill-invoke.mjs's `confirmPoint.id`); `:` is the
+ * BOUND shape a gate or a tool-level exit mints (`dev-server-control:start`,
+ * `tool:heyspex_file_spec`); `/` is accepted for symmetry with path-shaped ids.
+ */
+const CONFIRM_NAMESPACE_DELIMITERS = Object.freeze(['.', ':', '/']);
+
+/**
+ * Is `confirmId` inside `namespace`? True when the id IS the namespace, or sits under it
+ * behind one of {@link CONFIRM_NAMESPACE_DELIMITERS} — so `"hs-capture"` matches
+ * `"hs-capture.step-2"` (every confirm point of that skill), and `"tool:heyspex_file_spec"`
+ * matches only itself, never `"tool:heyspex_push_plan"`.
+ *
+ * @param {unknown} confirmId
+ * @param {string} namespace
+ * @returns {boolean}
+ */
+export function confirmIdMatchesNamespace(confirmId, namespace) {
+  if (typeof confirmId !== 'string' || typeof namespace !== 'string' || namespace === '') return false;
+  if (confirmId === namespace) return true;
+  return CONFIRM_NAMESPACE_DELIMITERS.some((d) => confirmId.startsWith(`${namespace}${d}`));
+}
+
+/**
+ * Is this confirm id BOUND to one specific ask — i.e. minted by a gate or an exit that
+ * names its own namespace with a `:` (`dev-server-control:start` from
+ * gates/dev-server-task-reminder.mjs's `confirmIdFor`, `tool:heyspex_file_spec` from
+ * gates/confirm-gate.mjs's `toolConfirmId`)?
+ *
+ * Why the distinction exists (regression R2, 2026-09-09): with no binding, the unqualified
+ * "oldest unused approved" fallback let a confirm answered for the dev-server RESTART ask be
+ * spent by the very next `heyspex_file_spec` — one ask silently authorizing an unrelated
+ * exit. A bound id is claimed by `id`/`namespace` only; the unqualified fallback skips it.
+ * A bare skill-step id (`hs-capture.step-2`) is NOT bound — it keeps the coarse behaviour
+ * confirm-gate.mjs's header documents for a front that cannot say which exit it is at.
+ *
+ * @param {unknown} confirmId
+ * @returns {boolean}
+ */
+export function isNamespaceBoundConfirmId(confirmId) {
+  return typeof confirmId === 'string' && confirmId.includes(':');
+}
+
+/**
+ * Append one harness event (from events.mjs) and the decision decide.mjs made for it
+ * (from decide.mjs) to the record, in the order it happened.
+ *
+ * @param {ReturnType<typeof createSessionRecord>} record
+ * @param {{ point: string, ts?: number }} event
+ * @param {object|null} [decision] the decide() result, or null when the event carries no decision
+ * @returns {ReturnType<typeof createSessionRecord>} the same record, for chaining.
+ */
+export function recordEvent(record, event, decision = null) {
+  record.events.push({ point: event?.point ?? null, ts: event?.ts ?? Date.now(), decision });
+  return record;
+}
+
+/**
+ * Append one tool call to the record, in the order it happened.
+ *
+ * @param {ReturnType<typeof createSessionRecord>} record
+ * @param {{ name?: string|null, input?: unknown, output?: unknown }} toolCall
+ * @returns {ReturnType<typeof createSessionRecord>} the same record, for chaining.
+ */
+export function recordToolCall(record, { name = null, input = null, output = null } = {}) {
+  record.toolCalls.push({ name, input, output });
+  return record;
+}
+
+/**
+ * Seal the record with the run's final output and an end timestamp. Safe to call more than
+ * once (e.g. a caller that finishes a record on every loop exit path); the last call wins.
+ *
+ * @param {ReturnType<typeof createSessionRecord>} record
+ * @param {string|null} [output]
+ * @returns {ReturnType<typeof createSessionRecord>} the same record, for chaining.
+ */
+export function finishSessionRecord(record, output = null) {
+  record.output = output ?? null;
+  record.endedAt = new Date().toISOString();
+  return record;
+}
+
+/**
+ * Persist one session record as a single JSONL line. Mirrors
+ * dev-factory/lib/run-events.mjs's append-only, line-atomic write (open "a" + one
+ * writeSync + close) so concurrent writers from different fronts never interleave into a
+ * corrupt line.
+ *
+ * Redacted via {@link redactRecord} ([[HS-Y424-NYPR-TASK-add-one-redaction-module-that-strips]])
+ * before serialization — a fixture key, a bearer token, or a marked ingested-prose block never
+ * reaches this file. Redaction produces a COPY for the write; the `record` object this function
+ * returns (for chaining) is the caller's own, untouched.
+ *
+ * @param {string} filePath
+ * @param {object} record
+ * @returns {object} the same record, for chaining.
+ */
+export function appendSessionRecord(filePath, record) {
+  if (!filePath) throw new Error('spexharness/session-record: filePath is required');
+  mkdirSync(dirname(filePath), { recursive: true });
+  const line = `${JSON.stringify(redactRecord(record))}\n`;
+  const fd = openSync(filePath, 'a');
+  try {
+    writeSync(fd, line);
+  } finally {
+    closeSync(fd);
+  }
+  return record;
+}
+
+/**
+ * Read all session records from a file, oldest first. Missing file → []. A corrupt/partial
+ * trailing line (e.g. the process died mid-write) is skipped rather than throwing — mirrors
+ * run-events.mjs readRunEvents' corrupt-safe read.
+ *
+ * @param {string} filePath
+ * @returns {object[]}
+ */
+export function readSessionRecords(filePath) {
+  if (!filePath || !existsSync(filePath)) return [];
+  const text = readFileSync(filePath, 'utf8');
+  const records = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      records.push(JSON.parse(trimmed));
+    } catch {
+      // corrupt/partial line — skip, don't throw
+    }
+  }
+  return records;
+}
+
+/* =========================================================================================
+ * Durable session store — claims + hand-off WIP + tool-call log, resumable by id.
+ * ========================================================================================= */
+
+/** The Neon table the durable session record lives in. */
+export const SESSION_RECORD_TABLE = 'harness_session_records';
+
+/** Postgres identifiers are not parameterizable — anything spliced into SQL passes this. */
+function assertIdentifier(name, what = 'table') {
+  if (typeof name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`spexharness/session-record: invalid ${what} identifier ${JSON.stringify(name)}`);
+  }
+  return name;
+}
+
+/**
+ * The idempotent DDL for the durable session table. Exported (rather than hidden) so a
+ * migration runner, a provisioning script or a test can assert against the exact shape —
+ * the Neon backend runs it lazily on first use unless `ensureSchema: false`.
+ *
+ * @param {string} [table]
+ * @returns {string}
+ */
+export function sessionRecordSchemaSql(table = SESSION_RECORD_TABLE) {
+  const t = assertIdentifier(table);
+  return `CREATE TABLE IF NOT EXISTS ${t} (
+  session_id text PRIMARY KEY,
+  seat_id text,
+  front text,
+  machine text,
+  record jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+)`;
+}
+
+/**
+ * @typedef {object} DurableSessionRecord
+ * @property {string} sessionId       the resume key — the only thing another machine needs.
+ * @property {string|null} seatId     the seat the session runs as.
+ * @property {string|null} front      the entry point that opened it ('chat', 'deepseek', …).
+ * @property {string|null} machine    the machine that last wrote the record.
+ * @property {unknown} ask            what was asked.
+ * @property {Array<object>} claims   the specs this session holds.
+ * @property {unknown} wip            the hand-off WIP block (null when there is none).
+ * @property {Array<object>} events   harness events with their decisions, in order.
+ * @property {Array<object>} toolCalls the session's tool-call log, in order.
+ * @property {string|null} output     what the model produced.
+ * @property {Array<{machine: string|null, at: string}>} resumes  every pick-up of this id.
+ * @property {string} startedAt
+ * @property {string} updatedAt
+ * @property {string|null} endedAt
+ */
+
+/**
+ * Create a durable session record: everything {@link createSessionRecord} carries, plus the
+ * three things a resume on another machine needs — `claims`, `wip` and the identity
+ * (`seatId`/`front`/`machine`) of the seat that opened it.
+ *
+ * Deliberately a SEPARATE constructor rather than a change to createSessionRecord: loop.mjs
+ * builds the plain record today and must keep getting exactly that shape.
+ *
+ * @param {{ sessionId?: string|null, seatId?: string|null, front?: string|null,
+ *           machine?: string|null, ask?: unknown, claims?: Array<object>, wip?: unknown }} [opts]
+ * @returns {DurableSessionRecord}
+ */
+export function createDurableSessionRecord({
+  sessionId = null,
+  seatId = null,
+  front = null,
+  machine = undefined,
+  ask = null,
+  claims = [],
+  wip = null,
+} = {}) {
+  const now = new Date().toISOString();
+  return {
+    ...createSessionRecord({ sessionId, ask }),
+    seatId,
+    front,
+    machine: machine === undefined ? currentMachine() : machine,
+    claims: Array.isArray(claims) ? claims.slice() : [],
+    wip,
+    resumes: [],
+    startedAt: now,
+    updatedAt: now,
+  };
+}
+
+/** The machine identity stamped on a write — hostname, or null when it can't be read. */
+export function currentMachine() {
+  try {
+    return process.env.HEYSPEX_MACHINE || hostname() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fill in a record read back from storage so a caller never has to defend against a row
+ * written by an older shape (or by a different front): the three collections are always
+ * arrays, and the scalar fields are always present.
+ *
+ * @param {object|null} raw
+ * @returns {DurableSessionRecord|null}
+ */
+export function normalizeSessionRecord(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  return {
+    sessionId: raw.sessionId ?? null,
+    seatId: raw.seatId ?? null,
+    front: raw.front ?? null,
+    machine: raw.machine ?? null,
+    ask: raw.ask ?? null,
+    claims: Array.isArray(raw.claims) ? raw.claims : [],
+    wip: raw.wip ?? null,
+    events: Array.isArray(raw.events) ? raw.events : [],
+    toolCalls: Array.isArray(raw.toolCalls) ? raw.toolCalls : [],
+    output: raw.output ?? null,
+    resumes: Array.isArray(raw.resumes) ? raw.resumes : [],
+    startedAt: raw.startedAt ?? null,
+    updatedAt: raw.updatedAt ?? null,
+    endedAt: raw.endedAt ?? null,
+  };
+}
+
+/** Structural copy — the store hands out copies so a caller's edits never mutate the store. */
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+/* ------------------------------------------------------------------------- backends --- */
+
+/**
+ * In-memory session backend. This is what the tests inject: same contract as the Neon
+ * backend (async, copy-on-read, copy-on-write), no database. Also useful to a front running
+ * fully offline, where a session simply does not survive the process.
+ *
+ * @param {Iterable<[string, object]>|Record<string, object>} [seed]
+ * @returns {{ read: Function, write: Function, list: Function, delete: Function, size: () => number }}
+ */
+export function createMemorySessionBackend(seed = undefined) {
+  const rows = new Map(
+    seed == null ? [] : (Symbol.iterator in Object(seed) ? seed : Object.entries(seed)),
+  );
+  return {
+    async read(sessionId) {
+      const row = rows.get(sessionId);
+      return row ? normalizeSessionRecord(clone(row)) : null;
+    },
+    async write(sessionId, record) {
+      rows.set(sessionId, clone(record));
+      return normalizeSessionRecord(clone(record));
+    },
+    async list({ seatId = null, limit = 100 } = {}) {
+      const all = [...rows.values()].map((row) => normalizeSessionRecord(clone(row)));
+      const filtered = seatId ? all.filter((r) => r.seatId === seatId) : all;
+      filtered.sort((a, b) => String(b.updatedAt ?? '').localeCompare(String(a.updatedAt ?? '')));
+      return filtered.slice(0, limit);
+    },
+    async delete(sessionId) {
+      return rows.delete(sessionId);
+    },
+    size: () => rows.size,
+  };
+}
+
+/**
+ * Resolve the Neon connection string the same way the repo's other plain-.mjs Neon callers
+ * do: `DATABASE_URL_UNPOOLED` first (the durable session store is a handful of point
+ * lookups, not a hot pool), then `DATABASE_URL`, then `~/.heyspex/credentials.yaml`.
+ *
+ * @param {{ env?: Record<string, string|undefined>, home?: string }} [opts] injectable for tests.
+ * @returns {string}
+ */
+export function loadHarnessDatabaseUrl({ env = process.env, home = undefined } = {}) {
+  const fromEnv = env.DATABASE_URL_UNPOOLED ?? env.DATABASE_URL;
+  if (fromEnv) return fromEnv;
+  let credentialsPath;
+  try {
+    credentialsPath = join(home ?? homedir(), '.heyspex', 'credentials.yaml');
+  } catch {
+    credentialsPath = null;
+  }
+  if (credentialsPath && existsSync(credentialsPath)) {
+    const yaml = readFileSync(credentialsPath, 'utf8');
+    const unpooled = yaml.match(/^database_url_unpooled:\s*(.+)$/m)?.[1]?.trim();
+    const pooled = yaml.match(/^database_url:\s*(.+)$/m)?.[1]?.trim();
+    const url = unpooled || pooled;
+    if (url) return url;
+  }
+  throw new Error(
+    'spexharness/session-record: no DATABASE_URL configured (env DATABASE_URL_UNPOOLED/DATABASE_URL or ~/.heyspex/credentials.yaml)',
+  );
+}
+
+/** neon()'s two return shapes: rows array (default) or { rows } under fullResults. */
+function firstRow(result) {
+  if (Array.isArray(result)) return result[0] ?? null;
+  if (result && Array.isArray(result.rows)) return result.rows[0] ?? null;
+  return null;
+}
+
+function allRows(result) {
+  if (Array.isArray(result)) return result;
+  if (result && Array.isArray(result.rows)) return result.rows;
+  return [];
+}
+
+/** jsonb comes back parsed; a text column (or a stand-in driver) may hand back a string. */
+function decodeRecordColumn(value) {
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Neon-backed session backend — the default. The driver import is LAZY (first call, not
+ * module load) so importing this module in an offline/test context costs nothing and needs
+ * no DATABASE_URL, and the schema DDL is idempotent and runs at most once per backend.
+ *
+ * @param {{
+ *   sql?: ((text: string, params?: unknown[]) => Promise<unknown>)|null,
+ *   databaseUrl?: string|null,
+ *   table?: string,
+ *   ensureSchema?: boolean,
+ * }} [options] `sql` injects a query function (a live `neon()` handle the caller already
+ *   holds, or a stand-in); otherwise one is built from {@link loadHarnessDatabaseUrl}.
+ * @returns {{ read: Function, write: Function, list: Function, delete: Function }}
+ */
+export function createNeonSessionBackend(options = {}) {
+  const { sql: injectedSql = null, databaseUrl = null, table = SESSION_RECORD_TABLE, ensureSchema = true } = options;
+  const t = assertIdentifier(table);
+
+  let sqlPromise = null;
+  let schemaPromise = null;
+
+  async function connect() {
+    if (injectedSql) return injectedSql;
+    if (!sqlPromise) {
+      sqlPromise = (async () => {
+        const { neon } = await import('@neondatabase/serverless');
+        return neon(databaseUrl ?? loadHarnessDatabaseUrl());
+      })();
+    }
+    return sqlPromise;
+  }
+
+  async function ready() {
+    const sql = await connect();
+    if (ensureSchema) {
+      if (!schemaPromise) schemaPromise = Promise.resolve(sql(sessionRecordSchemaSql(t), []));
+      await schemaPromise;
+    }
+    return sql;
+  }
+
+  return {
+    async read(sessionId) {
+      const sql = await ready();
+      const row = firstRow(await sql(`SELECT record FROM ${t} WHERE session_id = $1`, [sessionId]));
+      return row ? normalizeSessionRecord(decodeRecordColumn(row.record)) : null;
+    },
+    async write(sessionId, record) {
+      const sql = await ready();
+      // Redacted before it ever reaches Neon — same module, same contract as
+      // appendSessionRecord's JSONL write (HS-Y424): a fixture key, a bearer
+      // token, or a marked ingested-prose block never lands in this row.
+      await sql(
+        `INSERT INTO ${t} (session_id, seat_id, front, machine, record, updated_at)
+         VALUES ($1, $2, $3, $4, $5::jsonb, now())
+         ON CONFLICT (session_id) DO UPDATE SET
+           seat_id = EXCLUDED.seat_id,
+           front = EXCLUDED.front,
+           machine = EXCLUDED.machine,
+           record = EXCLUDED.record,
+           updated_at = now()`,
+        [sessionId, record.seatId ?? null, record.front ?? null, record.machine ?? null, JSON.stringify(redactRecord(record))],
+      );
+      return normalizeSessionRecord(clone(record));
+    },
+    async list({ seatId = null, limit = 100 } = {}) {
+      const sql = await ready();
+      const result = seatId
+        ? await sql(
+            `SELECT record FROM ${t} WHERE seat_id = $1 ORDER BY updated_at DESC LIMIT $2`,
+            [seatId, limit],
+          )
+        : await sql(`SELECT record FROM ${t} ORDER BY updated_at DESC LIMIT $1`, [limit]);
+      return allRows(result).map((row) => normalizeSessionRecord(decodeRecordColumn(row.record)));
+    },
+    async delete(sessionId) {
+      const sql = await ready();
+      const result = await sql(`DELETE FROM ${t} WHERE session_id = $1 RETURNING session_id`, [sessionId]);
+      return allRows(result).length > 0;
+    },
+  };
+}
+
+/* ---------------------------------------------------------------------------- store --- */
+
+function requireSessionId(sessionId) {
+  if (!sessionId || typeof sessionId !== 'string') {
+    throw new Error('spexharness/session-record: sessionId is required');
+  }
+  return sessionId;
+}
+
+/**
+ * The durable session store. Every method is async and keyed by session id; the store holds
+ * no state of its own, so two store handles over the same backend — including two on
+ * DIFFERENT machines — see exactly the same session.
+ *
+ * @param {{ backend?: object, machine?: string|null, neon?: object }} [options]
+ *   `backend` injects storage (the tests pass {@link createMemorySessionBackend}); omitted,
+ *   it defaults to {@link createNeonSessionBackend} (constructed lazily — no connection is
+ *   opened until a method is actually called). `neon` is passed through to that default.
+ * @returns {object}
+ */
+export function createSessionStore(options = {}) {
+  const { backend: injectedBackend = null, machine = undefined, neon: neonOptions = undefined } = options;
+  const writerMachine = machine === undefined ? currentMachine() : machine;
+
+  let backendInstance = injectedBackend;
+  function backend() {
+    if (!backendInstance) backendInstance = createNeonSessionBackend(neonOptions ?? {});
+    return backendInstance;
+  }
+
+  /** Read a session, or throw with the id — every mutation goes through this. */
+  async function mustRead(sessionId) {
+    const record = await backend().read(requireSessionId(sessionId));
+    if (!record) {
+      throw new Error(`spexharness/session-record: no session record for id ${sessionId}`);
+    }
+    return record;
+  }
+
+  /** Stamp the writer + time and persist. */
+  async function persist(record) {
+    const next = { ...record, machine: writerMachine, updatedAt: new Date().toISOString() };
+    return backend().write(next.sessionId, next);
+  }
+
+  /** Read-modify-write one session. */
+  async function mutate(sessionId, fn) {
+    const record = await mustRead(sessionId);
+    return persist(fn(record) ?? record);
+  }
+
+  return {
+    /** The backend in use — exposed so a caller can assert which storage it got. */
+    backend,
+
+    /**
+     * Create (or replace) a session record under `sessionId` and persist it. Returns the
+     * stored record. Idempotent by id: calling it twice with the same id restarts the record.
+     */
+    async createSession(init = {}) {
+      const sessionId = requireSessionId(init.sessionId ?? null);
+      const record = createDurableSessionRecord({ ...init, sessionId, machine: writerMachine });
+      return persist(record);
+    },
+
+    /** Persist an already-built record (e.g. one a loop mutated in memory). */
+    async saveSession(record) {
+      return persist({ ...normalizeSessionRecord(record), sessionId: requireSessionId(record?.sessionId) });
+    },
+
+    /** The full session record for `sessionId`, or null when the id is unknown. */
+    async getSession(sessionId) {
+      return backend().read(requireSessionId(sessionId));
+    },
+
+    /**
+     * Pick a session up by id — the resume path. Returns the full record (claims, WIP and
+     * tool-call log intact) and records the pick-up in `resumes`, so a hand-off is auditable
+     * rather than silent. Unknown id → null, so a caller can branch on "no session there".
+     */
+    async resumeSession(sessionId, { machine: onMachine = writerMachine } = {}) {
+      const record = await backend().read(requireSessionId(sessionId));
+      if (!record) return null;
+      record.resumes = [...record.resumes, { machine: onMachine ?? null, at: new Date().toISOString() }];
+      return persist(record);
+    },
+
+    /** Append one tool call to the session's log, in the order it happened. */
+    async appendToolCall(sessionId, { name = null, input = null, output = null } = {}) {
+      return mutate(sessionId, (record) => {
+        record.toolCalls = [...record.toolCalls, { name, input, output }];
+        return record;
+      });
+    },
+
+    /** Append several tool calls in one write — the same order, one round trip. */
+    async appendToolCalls(sessionId, toolCalls = []) {
+      return mutate(sessionId, (record) => {
+        record.toolCalls = [
+          ...record.toolCalls,
+          ...toolCalls.map(({ name = null, input = null, output = null } = {}) => ({ name, input, output })),
+        ];
+        return record;
+      });
+    },
+
+    /** Append one harness event + its decision, mirroring {@link recordEvent}'s shape. */
+    async appendEvent(sessionId, event, decision = null) {
+      return mutate(sessionId, (record) => {
+        record.events = [
+          ...record.events,
+          { point: event?.point ?? null, ts: event?.ts ?? Date.now(), decision },
+        ];
+        return record;
+      });
+    },
+
+    /** Replace the session's claim set wholesale. */
+    async updateClaims(sessionId, claims = []) {
+      return mutate(sessionId, (record) => {
+        record.claims = Array.isArray(claims) ? claims.slice() : [];
+        return record;
+      });
+    },
+
+    /** Add one claim, replacing any existing claim on the same `specId` (claims are a set). */
+    async addClaim(sessionId, claim) {
+      if (!claim?.specId) throw new Error('spexharness/session-record: claim.specId is required');
+      return mutate(sessionId, (record) => {
+        record.claims = [
+          ...record.claims.filter((c) => c?.specId !== claim.specId),
+          { claimedAt: new Date().toISOString(), ...claim },
+        ];
+        return record;
+      });
+    },
+
+    /** Drop the claim on `specId`. A spec that was not claimed is a no-op, not an error. */
+    async releaseClaim(sessionId, specId) {
+      return mutate(sessionId, (record) => {
+        record.claims = record.claims.filter((c) => c?.specId !== specId);
+        return record;
+      });
+    },
+
+    /** Replace the session's hand-off WIP block. */
+    async updateWip(sessionId, wip) {
+      return mutate(sessionId, (record) => {
+        record.wip = wip ?? null;
+        return record;
+      });
+    },
+
+    /** Merge fields into the hand-off WIP block, keeping what is already there. */
+    async mergeWip(sessionId, patch = {}) {
+      return mutate(sessionId, (record) => {
+        const base = record.wip && typeof record.wip === 'object' && !Array.isArray(record.wip) ? record.wip : {};
+        record.wip = { ...base, ...patch };
+        return record;
+      });
+    },
+
+    /** Seal the session with its final output and an end timestamp. */
+    async finishSession(sessionId, output = null) {
+      return mutate(sessionId, (record) => {
+        record.output = output ?? null;
+        record.endedAt = new Date().toISOString();
+        return record;
+      });
+    },
+
+    /** Sessions in the store, newest first (backends that support listing). */
+    async listSessions(opts = {}) {
+      const b = backend();
+      if (typeof b.list !== 'function') return [];
+      return b.list(opts);
+    },
+
+    /** Remove a session record. Returns whether a row was actually removed. */
+    async deleteSession(sessionId) {
+      const b = backend();
+      if (typeof b.delete !== 'function') return false;
+      return b.delete(requireSessionId(sessionId));
+    },
+  };
+}