@meetless/mla 0.1.4

package/dist/lib/rules/ce0-store.js

@@ -0,0 +1,683 @@
+"use strict";
+// The CE0 durable store: the local SQLite WAL database that backs the evidence-
+// consultation forcing function's three records
+// (notes/20260617-evidence-consultation-forcing-function-proposal.md Part VII,
+// P0.1-P0.6). It is the single CE0 runtime authority for "did this turn's
+// obligation get satisfied?", read with one local SQLite lookup off the PreToolUse
+// hot path. The doc mandates SQLite (with WAL) precisely so the obligation lifecycle
+// can be a transactional read/write rather than an append-log scan.
+//
+// SCOPE (Commit 4): the three record TABLES and their typed insert/read only. The
+// LocalTurnIdentity PARENT table and its BEGIN IMMEDIATE sequence allocation are the
+// next slice; deny, recovery, correction, checkpoint, and any rollout-mode column are
+// held seams and are deliberately absent. The offline per-subject CoverageAuditLabel
+// is a JSONL artifact (the `mla evidence` workflow), never a table here.
+//
+// The CLI intentionally does not depend on @meetless/utils (see kb-candidate.ts), so
+// the value shapes below are vendored with field names byte-identical to the utils CE0
+// types; the array fields persist as JSON text columns and round-trip across that
+// boundary without a translation layer.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Ce0StoreSchemaVersionError = exports.CE0_SCHEMA_VERSION = void 0;
+exports.defaultCe0StorePath = defaultCe0StorePath;
+exports.consultationRecordToReducerInput = consultationRecordToReducerInput;
+exports.openCe0Store = openCe0Store;
+exports.closeCe0Store = closeCe0Store;
+exports.insertTurnMemoryAssessment = insertTurnMemoryAssessment;
+exports.getTurnMemoryAssessment = getTurnMemoryAssessment;
+exports.listTurnMemoryAssessments = listTurnMemoryAssessments;
+exports.allocateTurnIdentity = allocateTurnIdentity;
+exports.openTurnAtomically = openTurnAtomically;
+exports.resolveLatestTurnIdentity = resolveLatestTurnIdentity;
+exports.insertTurnRuleObligation = insertTurnRuleObligation;
+exports.getTurnRuleObligation = getTurnRuleObligation;
+exports.listDeadlineClaimedObligations = listDeadlineClaimedObligations;
+exports.insertConsultationAttempt = insertConsultationAttempt;
+exports.appendConsultationAttempt = appendConsultationAttempt;
+exports.getConsultationAttempt = getConsultationAttempt;
+exports.listConsultationsForTurn = listConsultationsForTurn;
+exports.claimFirstStop = claimFirstStop;
+exports.recordStopResponseSnapshot = recordStopResponseSnapshot;
+exports.finalizeObligation = finalizeObligation;
+const path = __importStar(require("path"));
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const config_1 = require("../config");
+const ce0_sampling_bucket_1 = require("./ce0-sampling-bucket");
+const interception_schema_1 = require("./interception-schema");
+/** The CE0 local store path: one SQLite file per machine under the Meetless home (the
+ * obligation rows carry their own workspace_id, and every read/finalize filters by the
+ * resolved workspace). It lives HERE, on the lean store module, rather than on the heavy
+ * `mla evidence` command module, so the PreToolUse deny hot path can resolve the store
+ * path without pulling evidence.ts's analytics/observability graph (latency lever A,
+ * notes/20260615-...-consolidated-proposal.md). The `mla evidence` command re-exports it
+ * for backward compatibility. */
+function defaultCe0StorePath() {
+    return path.join(config_1.HOME, "ce0", "evidence.db");
+}
+/** Project a persisted consultation record onto the deterministic reducer's read subset. The
+ * reducer (requirement-subject) treats `result` as optional and never reads `source`, so the
+ * stored null becomes undefined and source is dropped. This is the SINGLE home of the
+ * record -> reducer-input mapping: both the offline export (`ce0-evidence`) and the finalization
+ * projector (`ce0-telemetry-project`) recompute the proof set over the same shape, so neither
+ * may carry its own copy and drift. */
+function consultationRecordToReducerInput(rec) {
+    return {
+        consultationId: rec.consultationId,
+        consultationSubjects: rec.consultationSubjects,
+        execution: rec.execution,
+        result: rec.result ?? undefined,
+        deliveredToAnsweringContext: rec.deliveredToAnsweringContext,
+        orderingToken: rec.orderingToken,
+    };
+}
+// ---------------------------------------------------------------------------
+// Schema. Exactly three tables. Array fields are JSON text; booleans are 0/1
+// integers; the obligation is unique per (turn, rule version) per the doc.
+// ---------------------------------------------------------------------------
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS turn_memory_assessment (
+  assessment_id         TEXT PRIMARY KEY,
+  workspace_id          TEXT NOT NULL,
+  session_id            TEXT NOT NULL,
+  local_turn_sequence   INTEGER NOT NULL,
+  requirement           TEXT NOT NULL,
+  markers_matched       TEXT NOT NULL,
+  exclusions_matched    TEXT NOT NULL,
+  classifier_version    TEXT NOT NULL,
+  marker_set_version    TEXT NOT NULL,
+  exclusion_set_version TEXT NOT NULL,
+  created_at            INTEGER NOT NULL,
+  sampling_bucket       TEXT NOT NULL,
+  prompt_hash           TEXT NOT NULL,
+  -- §2.3 asserted-answer half of the recall snapshot, all nullable: filled by a later UPDATE
+  -- (Stage A stamps stop_observed_at; best-effort Stage B fills response_hash + response_source_ref),
+  -- absent at the UserPromptSubmit insert and forever when Stage B cannot label the answer.
+  stop_observed_at      INTEGER,
+  response_hash         TEXT,
+  response_source_ref   TEXT,
+  UNIQUE (workspace_id, session_id, local_turn_sequence)
+);
+
+CREATE TABLE IF NOT EXISTS turn_rule_obligation (
+  obligation_id            TEXT PRIMARY KEY,
+  workspace_id             TEXT NOT NULL,
+  session_id               TEXT NOT NULL,
+  local_turn_sequence      INTEGER NOT NULL,
+  rule_id                  TEXT NOT NULL,
+  rule_version_id          TEXT NOT NULL,
+  required_subjects        TEXT NOT NULL,
+  subject_satisfaction     TEXT NOT NULL,
+  status                   TEXT NOT NULL,
+  state_version            INTEGER NOT NULL,
+  deadline_claimed_at      INTEGER,
+  deadline_claimed_version INTEGER,
+  response_hash            TEXT,
+  outcome                  TEXT,
+  canonical_payload_hash   TEXT NOT NULL,
+  UNIQUE (workspace_id, session_id, local_turn_sequence, rule_version_id),
+  -- §2.3: a finalized obligation carries exactly one terminal outcome, and only a finalized
+  -- one does. status = FINALIZED IFF outcome IS NOT NULL, enforced at the DB so no slice can
+  -- leave a half-finalized row (FINALIZED with no outcome, or an outcome on a live status).
+  CHECK ((status = 'FINALIZED') = (outcome IS NOT NULL))
+);
+
+CREATE TABLE IF NOT EXISTS consultation_attempt (
+  consultation_id                TEXT PRIMARY KEY,
+  workspace_id                   TEXT NOT NULL,
+  session_id                     TEXT NOT NULL,
+  local_turn_sequence            INTEGER NOT NULL,
+  source                         TEXT NOT NULL,
+  consultation_subjects          TEXT NOT NULL,
+  execution                      TEXT NOT NULL,
+  result                         TEXT,
+  delivered_to_answering_context INTEGER NOT NULL,
+  ordering_token                 INTEGER NOT NULL,
+  created_at                     INTEGER NOT NULL
+);
+`;
+/** The schema generation this code writes. Bump this whenever SCHEMA or INTERCEPTION_SCHEMA changes
+ * shape (a column added, dropped, or retyped). A store stamped with an older generation cannot be
+ * written by this code, so the opener refuses it instead of silently tolerating the drift. Because
+ * CE0 is an unshipped local harness ("local unshipped schema may be changed directly"), the resolution
+ * is a deliberate operator rebuild of the dev store, never an in-code migration / compatibility path. */
+exports.CE0_SCHEMA_VERSION = 1;
+/** Raised when `openCe0Store` is handed a populated store whose stamped schema generation is not the
+ * one this code writes. The opener refuses it loudly (and non-destructively) rather than returning a
+ * store whose writes would fail silently inside a fail-soft hook, the exact failure that let the live
+ * dogfood store drop 100% of its consultation captures undetected. */
+class Ce0StoreSchemaVersionError extends Error {
+    dbPath;
+    found;
+    expected;
+    constructor(dbPath, found, expected) {
+        super(`CE0 store at ${dbPath} is schema version ${found}, but this mla writes version ${expected}. ` +
+            `The store predates a schema change and its writes would fail silently; rebuild it ` +
+            `(delete the file and let it recreate, or restore from a current build).`);
+        this.dbPath = dbPath;
+        this.found = found;
+        this.expected = expected;
+        this.name = "Ce0StoreSchemaVersionError";
+    }
+}
+exports.Ce0StoreSchemaVersionError = Ce0StoreSchemaVersionError;
+/** Open (creating if needed) the CE0 store at `dbPath`, in WAL mode, with the schema
+ * applied. WAL keeps the PreToolUse reader off the writer's lock; a bounded busy_timeout
+ * keeps the hook from ever blocking behind a concurrent writer. The single bootstrap
+ * applies both the CE0 forcing-function schema and the rules interception schema
+ * (one database, one opener, no second migration framework).
+ *
+ * Before applying the schema, the opener reconciles the store's stamped generation: a brand-new
+ * (table-less) database is created at the current version, a store already at the current version is
+ * accepted, and a populated store at any OTHER version is REFUSED (it predates a schema change and the
+ * CREATE TABLE IF NOT EXISTS bootstrap cannot reshape its existing tables). Refusing loudly here turns a
+ * silent, fail-soft-swallowed write failure into a detectable one. */
+function openCe0Store(dbPath) {
+    const db = new better_sqlite3_1.default(dbPath);
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    db.pragma("busy_timeout = 50");
+    const found = db.pragma("user_version", { simple: true });
+    const tableCount = db
+        .prepare("SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'")
+        .get().n;
+    // A populated store carries its own generation; if it is not the one we write, its tables cannot be
+    // reshaped by CREATE TABLE IF NOT EXISTS and its writes would fail. A fresh (table-less) store has no
+    // generation yet and is simply stamped below.
+    if (tableCount > 0 && found !== exports.CE0_SCHEMA_VERSION) {
+        db.close();
+        throw new Ce0StoreSchemaVersionError(dbPath, found, exports.CE0_SCHEMA_VERSION);
+    }
+    db.exec(SCHEMA);
+    db.exec(interception_schema_1.INTERCEPTION_SCHEMA);
+    db.pragma(`user_version = ${exports.CE0_SCHEMA_VERSION}`);
+    return { db };
+}
+function closeCe0Store(store) {
+    store.db.close();
+}
+// ---------------------------------------------------------------------------
+// turn_memory_assessment
+// ---------------------------------------------------------------------------
+function insertTurnMemoryAssessment(store, rec) {
+    store.db
+        .prepare(`INSERT INTO turn_memory_assessment
+        (assessment_id, workspace_id, session_id, local_turn_sequence, requirement,
+         markers_matched, exclusions_matched, classifier_version, marker_set_version,
+         exclusion_set_version, created_at, sampling_bucket, prompt_hash,
+         stop_observed_at, response_hash, response_source_ref)
+       VALUES
+        (@assessment_id, @workspace_id, @session_id, @local_turn_sequence, @requirement,
+         @markers_matched, @exclusions_matched, @classifier_version, @marker_set_version,
+         @exclusion_set_version, @created_at, @sampling_bucket, @prompt_hash,
+         @stop_observed_at, @response_hash, @response_source_ref)`)
+        .run({
+        assessment_id: rec.assessmentId,
+        workspace_id: rec.workspaceId,
+        session_id: rec.sessionId,
+        local_turn_sequence: rec.localTurnSequence,
+        requirement: rec.requirement,
+        markers_matched: JSON.stringify(rec.markersMatched),
+        exclusions_matched: JSON.stringify(rec.exclusionsMatched),
+        classifier_version: rec.classifierVersion,
+        marker_set_version: rec.markerSetVersion,
+        exclusion_set_version: rec.exclusionSetVersion,
+        created_at: rec.createdAt,
+        sampling_bucket: rec.samplingBucket,
+        prompt_hash: rec.promptHash,
+        stop_observed_at: rec.stopObservedAt ?? null,
+        response_hash: rec.responseHash ?? null,
+        response_source_ref: rec.responseSourceRef ? JSON.stringify(rec.responseSourceRef) : null,
+    });
+}
+function mapAssessmentRow(row) {
+    const rec = {
+        assessmentId: row.assessment_id,
+        workspaceId: row.workspace_id,
+        sessionId: row.session_id,
+        localTurnSequence: row.local_turn_sequence,
+        requirement: row.requirement,
+        markersMatched: JSON.parse(row.markers_matched),
+        exclusionsMatched: JSON.parse(row.exclusions_matched),
+        classifierVersion: row.classifier_version,
+        markerSetVersion: row.marker_set_version,
+        exclusionSetVersion: row.exclusion_set_version,
+        createdAt: row.created_at,
+        samplingBucket: row.sampling_bucket,
+        promptHash: row.prompt_hash,
+    };
+    // §2.3 snapshot fields are OPTIONAL: a NULL column maps to an ABSENT key (not an `undefined` value),
+    // so a never-snapshotted assessment deep-equals the UserPromptSubmit insert shape that omitted them.
+    if (row.stop_observed_at != null)
+        rec.stopObservedAt = row.stop_observed_at;
+    if (row.response_hash != null)
+        rec.responseHash = row.response_hash;
+    if (row.response_source_ref != null) {
+        rec.responseSourceRef = JSON.parse(row.response_source_ref);
+    }
+    return rec;
+}
+function getTurnMemoryAssessment(store, assessmentId) {
+    const row = store.db
+        .prepare(`SELECT * FROM turn_memory_assessment WHERE assessment_id = ?`)
+        .get(assessmentId);
+    if (!row)
+        return null;
+    return mapAssessmentRow(row);
+}
+/** List every memory assessment in the workspace. The offline telemetry sweep
+ * (`mla evidence ce0-emit-telemetry`) projects one memory_requirement_assessed event per
+ * row (proposal §6.4: the precision/recall denominator). Unlike the obligation export,
+ * EVERY assessment is a telemetry fact regardless of requirement or any deadline claim, so
+ * there is no filter here. Deterministically ordered by (session, sequence, assessmentId) so
+ * a re-run projects the same events in the same order. */
+function listTurnMemoryAssessments(store, workspaceId) {
+    const rows = store.db
+        .prepare(`SELECT * FROM turn_memory_assessment
+        WHERE workspace_id = ?
+        ORDER BY session_id, local_turn_sequence, assessment_id`)
+        .all(workspaceId);
+    return rows.map(mapAssessmentRow);
+}
+/** Mint this turn's localTurnSequence (MAX+1 per workspace+session) and sampling bucket, then insert
+ * the assessment row. This is the side-effecting CORE shared by the two turn-opening entry points:
+ * `allocateTurnIdentity` wraps it in its own BEGIN IMMEDIATE, and `openTurnAtomically` runs it inside
+ * the same transaction as the obligation insert. It is deliberately NOT exported: every caller must go
+ * through one of those transaction boundaries so the sequence allocation stays serialized (the unique
+ * (workspace, session, sequence) index is the backstop). */
+function mintAndInsertAssessment(store, d) {
+    const { maxSeq } = store.db
+        .prepare(`SELECT MAX(local_turn_sequence) AS maxSeq
+         FROM turn_memory_assessment
+        WHERE workspace_id = ? AND session_id = ?`)
+        .get(d.workspaceId, d.sessionId);
+    const localTurnSequence = (maxSeq ?? 0) + 1;
+    const rec = {
+        ...d,
+        localTurnSequence,
+        // The bucket binds to the same natural key as the row's UNIQUE constraint, so it must be
+        // minted here, after the sequence, never on the draft (R3 P0.9; ce0-sampling-bucket.ts).
+        samplingBucket: (0, ce0_sampling_bucket_1.samplingBucketFor)({
+            workspaceId: d.workspaceId,
+            sessionId: d.sessionId,
+            localTurnSequence,
+        }),
+    };
+    insertTurnMemoryAssessment(store, rec);
+    return rec;
+}
+/** Mint this turn's LocalTurnIdentity and persist its assessment in one serialized
+ * transaction: `BEGIN IMMEDIATE; nextSequence = MAX(localTurnSequence) + 1; insert`.
+ * BEGIN IMMEDIATE takes the write lock up front so two UserPromptSubmit processes for
+ * the same (workspace, session) cannot read the same MAX and collide; the unique
+ * (workspace, session, sequence) index is the backstop. Returns the persisted record
+ * carrying the minted sequence. */
+function allocateTurnIdentity(store, draft) {
+    const mint = store.db.transaction((d) => mintAndInsertAssessment(store, d));
+    return mint.immediate(draft);
+}
+/** Open a turn ATOMICALLY (proposal §1.3 req 1 physical resolution, R4 P0.4): in ONE BEGIN IMMEDIATE
+ * transaction, mint the LocalTurnIdentity, insert the assessment, and (when the turn is REQUIRED)
+ * insert its obligation. `buildObligation` runs INSIDE the transaction so the obligation it returns can
+ * carry the localTurnSequence just minted; returning null is a non-REQUIRED turn whose only row is the
+ * assessment. If the obligation insert throws, the assessment insert and the sequence allocation roll
+ * back with it, so a REQUIRED turn is never left half-open (an assessment with no obligation to grade,
+ * which would silently undercount the graded obligation set against the assessed-REQUIRED set). */
+function openTurnAtomically(store, draft, buildObligation) {
+    const run = store.db.transaction((d) => {
+        const assessment = mintAndInsertAssessment(store, d);
+        const obligation = buildObligation(assessment);
+        if (obligation)
+            insertTurnRuleObligation(store, obligation);
+        return { assessment, obligation };
+    });
+    return run.immediate(draft);
+}
+/** Resolve the LocalTurnIdentity a later hook should inherit: the highest-sequence
+ * assessment for the (workspace, session), or null if the turn has none yet. */
+function resolveLatestTurnIdentity(store, coord) {
+    const row = store.db
+        .prepare(`SELECT workspace_id, session_id, local_turn_sequence
+         FROM turn_memory_assessment
+        WHERE workspace_id = ? AND session_id = ?
+        ORDER BY local_turn_sequence DESC
+        LIMIT 1`)
+        .get(coord.workspaceId, coord.sessionId);
+    if (!row)
+        return null;
+    return {
+        workspaceId: row.workspace_id,
+        sessionId: row.session_id,
+        localTurnSequence: row.local_turn_sequence,
+    };
+}
+// ---------------------------------------------------------------------------
+// turn_rule_obligation
+// ---------------------------------------------------------------------------
+function insertTurnRuleObligation(store, rec) {
+    store.db
+        .prepare(`INSERT INTO turn_rule_obligation
+        (obligation_id, workspace_id, session_id, local_turn_sequence, rule_id,
+         rule_version_id, required_subjects, subject_satisfaction, status, state_version,
+         deadline_claimed_at, deadline_claimed_version, response_hash, outcome,
+         canonical_payload_hash)
+       VALUES
+        (@obligation_id, @workspace_id, @session_id, @local_turn_sequence, @rule_id,
+         @rule_version_id, @required_subjects, @subject_satisfaction, @status, @state_version,
+         @deadline_claimed_at, @deadline_claimed_version, @response_hash, @outcome,
+         @canonical_payload_hash)`)
+        .run({
+        obligation_id: rec.obligationId,
+        workspace_id: rec.workspaceId,
+        session_id: rec.sessionId,
+        local_turn_sequence: rec.localTurnSequence,
+        rule_id: rec.ruleId,
+        rule_version_id: rec.ruleVersionId,
+        required_subjects: JSON.stringify(rec.requiredSubjects),
+        subject_satisfaction: JSON.stringify(rec.subjectSatisfaction),
+        status: rec.status,
+        state_version: rec.stateVersion,
+        deadline_claimed_at: rec.deadlineClaimedAt,
+        deadline_claimed_version: rec.deadlineClaimedVersion,
+        response_hash: rec.responseHash,
+        outcome: rec.outcome,
+        canonical_payload_hash: rec.canonicalPayloadHash,
+    });
+}
+function mapObligationRow(row) {
+    return {
+        obligationId: row.obligation_id,
+        workspaceId: row.workspace_id,
+        sessionId: row.session_id,
+        localTurnSequence: row.local_turn_sequence,
+        ruleId: row.rule_id,
+        ruleVersionId: row.rule_version_id,
+        requiredSubjects: JSON.parse(row.required_subjects),
+        subjectSatisfaction: JSON.parse(row.subject_satisfaction),
+        status: row.status,
+        stateVersion: row.state_version,
+        deadlineClaimedAt: row.deadline_claimed_at ?? null,
+        deadlineClaimedVersion: row.deadline_claimed_version ?? null,
+        responseHash: row.response_hash ?? null,
+        outcome: row.outcome ?? null,
+        canonicalPayloadHash: row.canonical_payload_hash,
+    };
+}
+function getTurnRuleObligation(store, obligationId) {
+    const row = store.db
+        .prepare(`SELECT * FROM turn_rule_obligation WHERE obligation_id = ?`)
+        .get(obligationId);
+    if (!row)
+        return null;
+    return mapObligationRow(row);
+}
+/** List every obligation in the workspace whose first-Stop deadline has been claimed (the
+ * frozen, due-resolved set the `mla evidence` export labels). A live obligation whose deadline
+ * is still null is NOT exportable: its eligibility boundary is not yet fixed. FINALIZED rows are
+ * INCLUDED here (this is a mechanical read of the claimed set); the export workflow, not the
+ * store, decides to skip already-labeled ones. Deterministically ordered by (session, sequence,
+ * obligationId) so the JSONL artifact is stable across runs. */
+function listDeadlineClaimedObligations(store, workspaceId) {
+    const rows = store.db
+        .prepare(`SELECT * FROM turn_rule_obligation
+        WHERE workspace_id = ? AND deadline_claimed_at IS NOT NULL
+        ORDER BY session_id, local_turn_sequence, obligation_id`)
+        .all(workspaceId);
+    return rows.map(mapObligationRow);
+}
+// ---------------------------------------------------------------------------
+// consultation_attempt
+// ---------------------------------------------------------------------------
+function insertConsultationAttempt(store, rec) {
+    store.db
+        .prepare(`INSERT INTO consultation_attempt
+        (consultation_id, workspace_id, session_id, local_turn_sequence,
+         source, consultation_subjects, execution, result, delivered_to_answering_context,
+         ordering_token, created_at)
+       VALUES
+        (@consultation_id, @workspace_id, @session_id, @local_turn_sequence,
+         @source, @consultation_subjects, @execution, @result, @delivered_to_answering_context,
+         @ordering_token, @created_at)`)
+        .run({
+        consultation_id: rec.consultationId,
+        workspace_id: rec.workspaceId,
+        session_id: rec.sessionId,
+        local_turn_sequence: rec.localTurnSequence,
+        source: rec.source,
+        consultation_subjects: JSON.stringify(rec.consultationSubjects),
+        execution: rec.execution,
+        result: rec.result,
+        delivered_to_answering_context: rec.deliveredToAnsweringContext ? 1 : 0,
+        ordering_token: rec.orderingToken,
+        created_at: rec.createdAt,
+    });
+}
+/** Record one governed-memory consultation, minting its orderingToken in the same serialized
+ * transaction: `BEGIN IMMEDIATE; nextToken = MAX(ordering_token) + 1; insert`. The token is a
+ * per-turn monotonic position (scoped to the (workspace, session, sequence) the consultation
+ * belongs to), NOT a wall clock: the first-Stop deadline claim reads the high-water token as
+ * the eligibility boundary, and the reducer breaks proof ties on it. BEGIN IMMEDIATE takes the
+ * write lock up front so two concurrent appends in one turn cannot read the same MAX. Returns
+ * the persisted record carrying the minted token. */
+function appendConsultationAttempt(store, draft) {
+    const mint = store.db.transaction((d) => {
+        const { maxTok } = store.db
+            .prepare(`SELECT MAX(ordering_token) AS maxTok
+           FROM consultation_attempt
+          WHERE workspace_id = ? AND session_id = ? AND local_turn_sequence = ?`)
+            .get(d.workspaceId, d.sessionId, d.localTurnSequence);
+        const rec = { ...d, orderingToken: (maxTok ?? 0) + 1 };
+        insertConsultationAttempt(store, rec);
+        return rec;
+    });
+    return mint.immediate(draft);
+}
+function mapConsultationRow(row) {
+    return {
+        consultationId: row.consultation_id,
+        workspaceId: row.workspace_id,
+        sessionId: row.session_id,
+        localTurnSequence: row.local_turn_sequence,
+        source: row.source,
+        consultationSubjects: JSON.parse(row.consultation_subjects),
+        execution: row.execution,
+        result: row.result ?? null,
+        deliveredToAnsweringContext: row.delivered_to_answering_context === 1,
+        orderingToken: row.ordering_token,
+        createdAt: row.created_at,
+    };
+}
+function getConsultationAttempt(store, consultationId) {
+    const row = store.db
+        .prepare(`SELECT * FROM consultation_attempt WHERE consultation_id = ?`)
+        .get(consultationId);
+    if (!row)
+        return null;
+    return mapConsultationRow(row);
+}
+/** List one turn's consultations, ordered by (orderingToken, consultationId): the same total
+ * order the satisfaction reducer imposes, so the export's raw facts read in eligibility order.
+ * Scoped to the exact (workspace, session, localTurnSequence) coordinate. */
+function listConsultationsForTurn(store, coord) {
+    const rows = store.db
+        .prepare(`SELECT * FROM consultation_attempt
+        WHERE workspace_id = ? AND session_id = ? AND local_turn_sequence = ?
+        ORDER BY ordering_token, consultation_id`)
+        .all(coord.workspaceId, coord.sessionId, coord.localTurnSequence);
+    return rows.map(mapConsultationRow);
+}
+/**
+ * §2.3 Stage A: the first Stop's immediate, I/O-free observation of a turn. In one serialized
+ * `BEGIN IMMEDIATE` transaction it does two things:
+ *   1. Stamps `stopObservedAt` on the turn's assessment for EVERY classified turn (REQUIRED or
+ *      not), if-null so a later Stop never overwrites the first observation. A NOT_REQUIRED /
+ *      UNKNOWN turn has an assessment but no obligation; it is still stamped, so the offline
+ *      false-negative recall sample carries the same answer evidence as a flagged turn.
+ *   2. When an obligation is present, freezes the eligibility boundary: it finds the obligation by
+ *      its unique turn key, reads the turn's high-water orderingToken (the boundary), and
+ *      CAS-advances stateVersion while writing the deadline fields. The status column is
+ *      deliberately untouched: the claim fixes the boundary, it does not declare the obligation
+ *      satisfied (satisfaction is recomputed offline over the frozen eligible set).
+ * The deadline claim is idempotent: once a deadline is set, a later Stop returns ALREADY_CLAIMED
+ * and never moves the boundary, so a consultation that arrives after the first Stop (a higher
+ * token) cannot retroactively become eligible. No filesystem read happens here; the response
+ * snapshot is the best-effort Stage B, outside this transaction. BEGIN IMMEDIATE serializes
+ * concurrent Stops so exactly one wins the claim and the first stamp.
+ */
+function claimFirstStop(store, coord, ruleVersionId, now) {
+    const run = store.db.transaction(() => {
+        // Stage A step 1: stamp the assessment if-null. A pure write, no I/O; a harmless no-op when no
+        // assessment row exists for the coord (e.g. a Stop for a turn CE0 never assessed).
+        store.db
+            .prepare(`UPDATE turn_memory_assessment
+            SET stop_observed_at = ?
+          WHERE workspace_id = ? AND session_id = ? AND local_turn_sequence = ?
+            AND stop_observed_at IS NULL`)
+            .run(now(), coord.workspaceId, coord.sessionId, coord.localTurnSequence);
+        // Stage A step 2: claim the obligation deadline, when an obligation is present.
+        const key = store.db
+            .prepare(`SELECT obligation_id FROM turn_rule_obligation
+          WHERE workspace_id = ? AND session_id = ? AND local_turn_sequence = ?
+            AND rule_version_id = ?`)
+            .get(coord.workspaceId, coord.sessionId, coord.localTurnSequence, ruleVersionId);
+        if (!key)
+            return { status: "NO_OBLIGATION" };
+        const obligation = getTurnRuleObligation(store, key.obligation_id);
+        if (obligation.deadlineClaimedAt !== null) {
+            return {
+                status: "ALREADY_CLAIMED",
+                claim: {
+                    obligationId: obligation.obligationId,
+                    deadlineClaimedAt: obligation.deadlineClaimedAt,
+                    deadlineClaimedVersion: obligation.deadlineClaimedVersion,
+                    stateVersion: obligation.stateVersion,
+                },
+            };
+        }
+        const { maxTok } = store.db
+            .prepare(`SELECT MAX(ordering_token) AS maxTok FROM consultation_attempt
+          WHERE workspace_id = ? AND session_id = ? AND local_turn_sequence = ?`)
+            .get(coord.workspaceId, coord.sessionId, coord.localTurnSequence);
+        const boundary = maxTok ?? 0;
+        const observed = obligation.stateVersion;
+        store.db
+            .prepare(`UPDATE turn_rule_obligation
+            SET deadline_claimed_at = ?, deadline_claimed_version = ?, state_version = ?
+          WHERE obligation_id = ? AND state_version = ? AND deadline_claimed_at IS NULL`)
+            .run(boundary, observed, observed + 1, obligation.obligationId, observed);
+        return {
+            status: "CLAIMED",
+            claim: {
+                obligationId: obligation.obligationId,
+                deadlineClaimedAt: boundary,
+                deadlineClaimedVersion: observed,
+                stateVersion: observed + 1,
+            },
+        };
+    });
+    return run.immediate();
+}
+/**
+ * §2.3 Stage B: record the best-effort response snapshot (`responseHash` + `responseSourceRef`) onto
+ * an already-stamped assessment, OUTSIDE and AFTER the Stage A deadline transaction. The two fields
+ * move together as one pair, never with `stopObservedAt` (proposal lines 1096-1098): Stage A stamped
+ * the observation, this fills the response evidence the offline exporter rehydrates from the pointer.
+ *
+ * Idempotent under repeated Stop continuations (P0.6): a later Stop may fill a snapshot that is still
+ * missing, but it may NEVER overwrite one that already completed. The guard is `response_hash IS NULL`
+ * checked inside one serialized `BEGIN IMMEDIATE` transaction, so concurrent Stops cannot both write.
+ * `stop_observed_at` is deliberately untouched here; only the response pair is written.
+ */
+function recordStopResponseSnapshot(store, coord, snapshot) {
+    const run = store.db.transaction(() => {
+        const existing = store.db
+            .prepare(`SELECT response_hash FROM turn_memory_assessment
+          WHERE workspace_id = ? AND session_id = ? AND local_turn_sequence = ?`)
+            .get(coord.workspaceId, coord.sessionId, coord.localTurnSequence);
+        if (!existing)
+            return { status: "NO_ASSESSMENT" };
+        if (existing.response_hash != null)
+            return { status: "ALREADY_RECORDED" };
+        store.db
+            .prepare(`UPDATE turn_memory_assessment
+            SET response_hash = ?, response_source_ref = ?
+          WHERE workspace_id = ? AND session_id = ? AND local_turn_sequence = ?
+            AND response_hash IS NULL`)
+            .run(snapshot.responseHash, JSON.stringify(snapshot.responseSourceRef), coord.workspaceId, coord.sessionId, coord.localTurnSequence);
+        return { status: "RECORDED" };
+    });
+    return run.immediate();
+}
+/**
+ * Write a turn obligation's terminal outcome and move it to FINALIZED, guarded by a
+ * compare-and-swap on stateVersion (the same token the deadline claim advances). The human
+ * labeler chooses the outcome offline (§2.3); this is the only thing that finalizes a due turn.
+ * In one serialized `BEGIN IMMEDIATE` transaction: read the stored stateVersion, fail closed as
+ * CAS_CONFLICT if it does not match the caller's expectation (a concurrent finalize or a stale
+ * label), else set status='FINALIZED', write the outcome, and advance stateVersion. The CAS makes
+ * a re-import of an already-finalized obligation a clean conflict, never a double-write.
+ */
+function finalizeObligation(store, cmd) {
+    const run = store.db.transaction(() => {
+        const obligation = getTurnRuleObligation(store, cmd.obligationId);
+        if (!obligation) {
+            return { status: "NO_OBLIGATION", obligationId: cmd.obligationId };
+        }
+        if (obligation.stateVersion !== cmd.expectedStateVersion) {
+            return {
+                status: "CAS_CONFLICT",
+                obligationId: cmd.obligationId,
+                expectedStateVersion: cmd.expectedStateVersion,
+                actualStateVersion: obligation.stateVersion,
+            };
+        }
+        const next = cmd.expectedStateVersion + 1;
+        store.db
+            .prepare(`UPDATE turn_rule_obligation
+            SET status = 'FINALIZED', outcome = ?, state_version = ?
+          WHERE obligation_id = ? AND state_version = ?`)
+            .run(cmd.outcome, next, cmd.obligationId, cmd.expectedStateVersion);
+        return {
+            status: "FINALIZED",
+            obligationId: cmd.obligationId,
+            outcome: cmd.outcome,
+            stateVersion: next,
+        };
+    });
+    return run.immediate();
+}