@inflexa-ai/harness 0.18.0 → 0.19.0

package/dist/report-model/validate.js

@@ -17,7 +17,7 @@ import { columnsHeldByNoRow } from "./reference-resolver.js";
  * A production resolver reads storage for each reference, and a large report holds hundreds of them. An
  * unbounded fan-out would open one read for each reference at the same moment.
  */
-const RESOLUTION_CONCURRENCY = 8;
+export const RESOLUTION_CONCURRENCY = 8;
 /**
  * Match each column that a chart encoding names against the table that its binding resolved to.
  *
@@ -25,7 +25,7 @@ const RESOLUTION_CONCURRENCY = 8;
  * bound resolver broke its own contract. That is reported and never ignored, because a chart with no
  * table behind it renders nothing and a silent skip would pass it as grounded.
  */
-function checkChartEncoding(entry, value) {
+export function checkChartEncoding(entry, value) {
     const encodingColumns = entry.encodingColumns;
     if (encodingColumns === undefined || encodingColumns.length === 0) {
         return undefined;
@@ -43,6 +43,34 @@ function checkChartEncoding(entry, value) {
         detail: `the encoding names column ${absent.join(", ")}, which the bound table does not hold`,
     };
 }
+/**
+ * Resolve each reference of a block tree under the concurrency bound, and run the chart-encoding match.
+ *
+ * The walk collects each reference one time, `allWithConcurrency` bounds the fan-out, and
+ * `checkChartEncoding` catches a chart that plots a column which the bound table does not hold. The record
+ * gate and the preview share this one pass, thus the two refuse the same references. A value-bearing block
+ * whose reference resolved carries its value in the map. A claim or a citation reference reads no value
+ * from the map. The walk collects every failure, thus a reviewer sees each block that broke.
+ */
+export async function resolveDocumentReferences(sections, snapshot, resolver) {
+    const { references } = walkBlocks(sections);
+    const resolved = await allWithConcurrency(references.map((entry) => () => resolver.resolve(entry.reference, snapshot).then((result) => ({ entry, result }))), RESOLUTION_CONCURRENCY);
+    const failures = [];
+    const resolvedByBlock = new Map();
+    for (const { entry, result } of resolved) {
+        if (result.isErr()) {
+            failures.push({ blockId: entry.blockId, failure: result.error });
+            continue;
+        }
+        const encodingFailure = checkChartEncoding(entry, result.value);
+        if (encodingFailure !== undefined) {
+            failures.push({ blockId: entry.blockId, failure: encodingFailure });
+            continue;
+        }
+        resolvedByBlock.set(entry.blockId, result.value);
+    }
+    return { resolvedByBlock, failures };
+}
 /** Resolve each reference, collect the schema conformance and the resolution outcomes, and warn on prose. */
 export async function validateReport(document, snapshot, resolver) {
     const parsed = ReportDocumentSchema.safeParse(document);
@@ -53,21 +81,8 @@ export async function validateReport(document, snapshot, resolver) {
         }));
         return { valid: false, schemaIssues, warnings: [] };
     }
-    const { references, repeatedIds, warnings } = walkBlocks(parsed.data.sections);
-    const resolved = await allWithConcurrency(references.map((entry) => () => resolver.resolve(entry.reference, snapshot).then((result) => ({ entry, result }))), RESOLUTION_CONCURRENCY);
-    // Collect every failure. A reviewer must see each block that broke, thus the walk does not stop at
-    // the first unresolved reference. The `Err` channel carries the unresolved reference itself.
-    const resolutionFailures = [];
-    for (const { entry, result } of resolved) {
-        if (result.isErr()) {
-            resolutionFailures.push({ blockId: entry.blockId, failure: result.error });
-            continue;
-        }
-        const encodingFailure = checkChartEncoding(entry, result.value);
-        if (encodingFailure !== undefined) {
-            resolutionFailures.push({ blockId: entry.blockId, failure: encodingFailure });
-        }
-    }
+    const { repeatedIds, warnings } = walkBlocks(parsed.data.sections);
+    const { failures: resolutionFailures } = await resolveDocumentReferences(parsed.data.sections, snapshot, resolver);
     if (repeatedIds.length > 0 || resolutionFailures.length > 0) {
         return {
             valid: false,

package/dist/report-render/value-bridge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The value bridge: a resolved value maps onto a render value, keyed by block id.
+ *
+ * The resolver gives one `ResolvedValue` for each reference. The renderer takes a `RenderValues` map. The
+ * two models agree on a scalar, a table, and a citation, but they part on a figure. A `ResolvedValue`
+ * file echo carries a path and a hash, and a page needs a source string. Thus the bridge takes a
+ * caller-supplied policy that turns a file echo into a `src` string. The preview tool gives the concrete
+ * policy, because the page directory and its asset access are a session concern.
+ *
+ * The bridge is pure. It reads no file, it resolves no reference, and it imports nothing from the state
+ * layer or the tool layer. A block kind that carries no render value maps to no entry. A block kind whose
+ * resolved value has the wrong type becomes one typed mismatch. The bridge collects every mismatch, thus
+ * one call reports each fault at one time.
+ */
+import { type Result } from "neverthrow";
+import type { ResolvedValue } from "../report-model/reference-resolver.js";
+import type { RenderValues } from "./types.js";
+/** The block kinds that carry no render value. Each one renders from the block and the ledger alone. */
+type NoValueKind = "text" | "claim" | "citation" | "section";
+/** The block kinds that carry one render value under the block id in the map. */
+type ValueBearingKind = "metric" | "table" | "chart" | "figure";
+/** The file echo that a figure binding resolves to: a whole-file pin of a path and a hash. */
+export type ResolvedFile = Extract<ResolvedValue, {
+    type: "file";
+}>;
+/** The policy that turns a resolved file echo into a figure `src` string. The caller owns the policy. */
+export type FigureSourcePolicy = (file: ResolvedFile) => string;
+/**
+ * The resolution result of one block: the block id, the block kind, and the resolved value of its binding.
+ *
+ * A value-bearing kind carries the resolved value. A no-value kind carries none, thus a text block with
+ * no binding is representable and a value on it is not.
+ */
+export type BlockResolution = {
+    blockId: string;
+    kind: NoValueKind;
+} | {
+    blockId: string;
+    kind: ValueBearingKind;
+    resolved: ResolvedValue;
+};
+/**
+ * One typed mismatch between a block kind and a resolved value type. `blockId` names the block, and
+ * `blockKind` names the kind that sets the expectation. `expected` names the resolved type that the kind
+ * needs, and `actual` names the resolved type that arrived.
+ */
+export interface BridgeMismatch {
+    blockId: string;
+    blockKind: ValueBearingKind;
+    expected: ResolvedValue["type"];
+    actual: ResolvedValue["type"];
+}
+/**
+ * Map the resolved values of the blocks onto a `RenderValues` map.
+ *
+ * The bridge walks each resolution in order. A no-value kind adds no entry. A value-bearing kind whose
+ * resolved type matches adds one entry. A value-bearing kind whose resolved type does not match adds one
+ * mismatch. A run with a mismatch returns the mismatch list and no map. A run with no mismatch returns the
+ * complete map.
+ */
+export declare function bridgeValues(resolutions: readonly BlockResolution[], figureSrc: FigureSourcePolicy): Result<RenderValues, BridgeMismatch[]>;
+export {};

package/dist/report-render/value-bridge.js

@@ -0,0 +1,82 @@
+/**
+ * The value bridge: a resolved value maps onto a render value, keyed by block id.
+ *
+ * The resolver gives one `ResolvedValue` for each reference. The renderer takes a `RenderValues` map. The
+ * two models agree on a scalar, a table, and a citation, but they part on a figure. A `ResolvedValue`
+ * file echo carries a path and a hash, and a page needs a source string. Thus the bridge takes a
+ * caller-supplied policy that turns a file echo into a `src` string. The preview tool gives the concrete
+ * policy, because the page directory and its asset access are a session concern.
+ *
+ * The bridge is pure. It reads no file, it resolves no reference, and it imports nothing from the state
+ * layer or the tool layer. A block kind that carries no render value maps to no entry. A block kind whose
+ * resolved value has the wrong type becomes one typed mismatch. The bridge collects every mismatch, thus
+ * one call reports each fault at one time.
+ */
+import { err, ok } from "neverthrow";
+/**
+ * Map the resolved values of the blocks onto a `RenderValues` map.
+ *
+ * The bridge walks each resolution in order. A no-value kind adds no entry. A value-bearing kind whose
+ * resolved type matches adds one entry. A value-bearing kind whose resolved type does not match adds one
+ * mismatch. A run with a mismatch returns the mismatch list and no map. A run with no mismatch returns the
+ * complete map.
+ */
+export function bridgeValues(resolutions, figureSrc) {
+    const values = {};
+    const mismatches = [];
+    for (const resolution of resolutions) {
+        switch (resolution.kind) {
+            case "text":
+            case "claim":
+            case "citation":
+            case "section":
+                break;
+            case "metric": {
+                const value = resolution.resolved;
+                if (value.type !== "scalar") {
+                    mismatches.push(mismatch(resolution.blockId, "metric", "scalar", value.type));
+                    break;
+                }
+                values[resolution.blockId] = { type: "scalar", value: value.value };
+                break;
+            }
+            case "table":
+            case "chart": {
+                const value = resolution.resolved;
+                if (value.type !== "table") {
+                    mismatches.push(mismatch(resolution.blockId, resolution.kind, "table", value.type));
+                    break;
+                }
+                values[resolution.blockId] = tableValue(value);
+                break;
+            }
+            case "figure": {
+                const value = resolution.resolved;
+                if (value.type !== "file") {
+                    mismatches.push(mismatch(resolution.blockId, "figure", "file", value.type));
+                    break;
+                }
+                values[resolution.blockId] = { type: "figure", src: figureSrc(value) };
+                break;
+            }
+        }
+    }
+    if (mismatches.length > 0) {
+        return err(mismatches);
+    }
+    return ok(values);
+}
+/**
+ * Map a resolved table onto a render table. The explicit column order carries through when it is present,
+ * and it stays absent otherwise, thus the renderer keeps its first-row order as the default.
+ */
+function tableValue(value) {
+    if (value.columns !== undefined) {
+        return { type: "table", rows: value.rows, columns: value.columns };
+    }
+    return { type: "table", rows: value.rows };
+}
+/** Make one mismatch that names the block, its kind, the resolved type that it needs, and the type that arrived. */
+function mismatch(blockId, blockKind, expected, actual) {
+    return { blockId, blockKind, expected, actual };
+}

package/dist/runtime/assemble.d.ts

@@ -16,6 +16,7 @@
  */
 import { type Result } from "neverthrow";
 import { type ConversationAgentDeps } from "../agents/conversation-agent.js";
+import { type ReportSessionRuntime } from "../app/report-session-runtime.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ResourcePolicy } from "../config/resource-limits.js";
 import type { AgentDefinition } from "../loop/types.js";
@@ -26,6 +27,7 @@ import { type ExecuteTargetAssessmentDeps, type ExecuteTargetAssessmentInput, ty
 import { type DataProfileDeps, type DataProfileWorkflowInput } from "../tasks/data-profile.js";
 import { type CitationResolverConfig } from "../citations/resolve.js";
 import type { CitationResolver } from "../citations/types.js";
+import type { ReferenceResolver } from "../report-model/reference-resolver.js";
 /** Registered child sandbox-step callable the parent's child dispatch closes over. */
 export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxStepResult>;
 /**
@@ -78,6 +80,12 @@ export interface CoreRuntimeDeps {
     readonly usageRecorder?: UsageRecorder;
     /** Harness-owned citation capability configuration; no ambient lookup occurs. */
     readonly citationResolverConfig?: CitationResolverConfig;
+    /**
+     * Reference-resolution seam for the report preview. Absent by default, thus the
+     * preview tool degrades as data until an embedder wires a realization. The
+     * realization itself stays out of the harness.
+     */
+    readonly reportReferenceResolver?: ReferenceResolver;
 }
 /**
  * The refusal a thread type carries no agent yet. `report` is a valid
@@ -120,6 +128,13 @@ export interface CoreRuntime {
      * on the `Result` channel.
      */
     readonly agents: ThreadAgentResolver;
+    /**
+     * The turn-start anchor of a report session. A serving path runs it at the
+     * turn start, thus a report tool call never arrives before the session state
+     * exists. The gateway stays behind the tool boundary, thus the runtime exposes
+     * the anchor operation alone here, and a later change wires it at the turn start.
+     */
+    readonly reportSession: Pick<ReportSessionRuntime, "ensureSessionState">;
     readonly workflows: RegisteredWorkflows;
     readonly citationResolver: CitationResolver;
 }

package/dist/runtime/assemble.js

@@ -16,6 +16,8 @@
  */
 import { err, ok } from "neverthrow";
 import { createConversationAgent } from "../agents/conversation-agent.js";
+import { createReportSessionAgent } from "../agents/report-session-agent.js";
+import { createReportSessionRuntime } from "../app/report-session-runtime.js";
 import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { registerExecuteAnalysis } from "../workflows/execute-analysis.js";
 import { registerSandboxStep } from "../workflows/sandbox-step.js";
@@ -67,17 +69,37 @@ export function assembleCoreRuntime(deps) {
         usageRecorder,
         citationResolver,
     });
-    // The single registration point for every typed agent. One entry today; a
-    // future thread type's agent plugs in here at assembly with no embedder
-    // change. `conversation` is required at the type level because boot resolves
-    // it unconditionally (`boot.ts` backfill) — a dropped registration must fail
-    // tsc here, not surface only as a boot-time throw. The `Partial` over the
-    // rest keeps the compiler honest that `report` has no agent yet.
+    // The report agent is a singleton over the conversation deps. The session
+    // runtime binds the per-session state to the thread behind the tool boundary,
+    // thus one definition serves every report thread. Its preview tool writes the
+    // page into the analysis tree and returns the path, thus the page write reaches
+    // no host seam. The optional reference resolver is the one seam it can use, and
+    // it is absent by default.
+    const reportSession = createReportSessionRuntime({ pool: conversation.pool, ...(conversation.logger ? { logger: conversation.logger } : {}) });
+    const reportAgent = createReportSessionAgent({
+        model: conversation.model,
+        pool: conversation.pool,
+        embedding: conversation.embedding,
+        workspaceFs: conversation.workspaceFs,
+        gateway: reportSession.gateway,
+        resolveWorkspaceRoot: conversation.resolveWorkspaceRoot,
+        ...(deps.reportReferenceResolver ? { resolver: deps.reportReferenceResolver } : {}),
+        ...(conversation.logger ? { logger: conversation.logger } : {}),
+    });
+    // The single registration point for every typed agent. A future thread type's
+    // agent plugs in here at assembly with no embedder change. `conversation` is
+    // required at the type level because boot resolves it unconditionally
+    // (`boot.ts` backfill). `report` is required now that its agent registers here,
+    // so a dropped registration fails tsc, and it does not surface only as a
+    // resolution refusal. The `Partial` over the rest keeps the compiler honest
+    // about a type that has no agent yet.
     const agents = {
         conversation: conversationAgent,
+        report: reportAgent,
     };
     return {
         agents: createThreadAgentResolver(agents),
+        reportSession: { ensureSessionState: reportSession.ensureSessionState },
         workflows: {
             executeAnalysis,
             sandboxStep,

package/dist/state/init.js

@@ -161,6 +161,29 @@ CREATE TABLE IF NOT EXISTS cortex_report_versions (
 CREATE INDEX IF NOT EXISTS idx_cortex_report_versions_analysis
   ON cortex_report_versions(analysis_id);
 
+-- Report session state — one mutable row for each report session thread. The row
+-- holds the in-progress draft document and the pinned snapshot of the session. The
+-- thread id is the primary key, thus one session binds to one thread. The document
+-- column and the snapshot column are each nullable, because the pin writes the
+-- snapshot first and the document lands later. A purge of the analysis removes the
+-- row through the analysis_id cascade. The explicit purge delete stays a backstop,
+-- the same as the plans delete, because a database whose table predates the key
+-- never acquires one. The thread id carries no foreign key, the same as the
+-- messages rows, thus a purge of a thread cannot reach this row through a cascade
+-- and purgeThread removes it by name.
+CREATE TABLE IF NOT EXISTS cortex_report_session_state (
+  thread_id     TEXT PRIMARY KEY,
+  analysis_id   TEXT NOT NULL
+                  REFERENCES cortex_analysis_state(analysis_id)
+                  ON DELETE CASCADE,
+  document      JSONB,
+  snapshot      JSONB,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_cortex_report_session_state_analysis
+  ON cortex_report_session_state(analysis_id);
+
 -- Target assessments — organization-scoped, snapshot-style target dossiers.
 -- Independent of analyses, projects, runs, and chat threads. The full
 -- dossier is persisted as JSONB on the row, no separate artifacts table.

package/dist/state/purge-analysis.js

@@ -81,6 +81,7 @@ const ANALYSIS_KEYED_DELETES = [
     { op: "purgeAnalysis.askGrants", sql: "DELETE FROM cortex_ask_grants WHERE analysis_id = $1" },
     { op: "purgeAnalysis.plans", sql: "DELETE FROM cortex_plans WHERE analysis_id = $1" },
     { op: "purgeAnalysis.reportVersions", sql: "DELETE FROM cortex_report_versions WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.reportSessionState", sql: "DELETE FROM cortex_report_session_state WHERE analysis_id = $1" },
     { op: "purgeAnalysis.analysisState", sql: "DELETE FROM cortex_analysis_state WHERE analysis_id = $1" },
 ];
 /**

package/dist/state/report-session-state.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The report session-state store -- the mutable working state of one report session.
+ *
+ * One row holds the state of one report session, keyed by the thread id. The row
+ * holds the in-progress draft document and the pinned snapshot. The row is mutable,
+ * and it differs from a recorded version this way. A session reads the state, writes
+ * the snapshot one time at the start, and persists the document as the composition
+ * proceeds.
+ *
+ * The snapshot writes at row creation. The write is insert-if-absent through
+ * ON CONFLICT DO NOTHING. Thus two concurrent first calls make one row, and the
+ * winner keeps its snapshot. The store reads the row back after the write, thus the
+ * caller sees the durable state whichever call won.
+ *
+ * The document column and the snapshot column are each nullable. A row exists with a
+ * snapshot and no document yet, because the pin writes the snapshot first and the
+ * document lands later. A null column reads as a null value.
+ *
+ * A read parses the stored document with the draft schema, and the stored snapshot
+ * with `parseSnapshot`. The document is the draft document, because an in-progress
+ * document can be incomplete. A column that fails a parse reads as a typed error, and
+ * it does not crash. An absent row reads as a normal absence.
+ *
+ * A persist is a compare-and-swap. The load reads the prior document, and the persist
+ * lands only when the row still holds it. Thus two concurrent turns cannot both land,
+ * and the loser reads the state again.
+ *
+ * A purge of the analysis removes the row through the analysis-id cascade.
+ */
+import { type ResultAsync } from "neverthrow";
+import type { Pool } from "pg";
+import { type DbError } from "../lib/db-result.js";
+import type { Logger } from "../lib/logger.js";
+import { type DraftDocument } from "../report-model/draft.js";
+import type { ReportSnapshot } from "../report-model/reference-resolver.js";
+import { type SchemaIssue } from "./snapshot-parse.js";
+/** The state of one report session, as the store gives it back. */
+export interface ReportSessionState {
+    readonly threadId: string;
+    readonly analysisId: string;
+    /** The in-progress draft document, or `null` before the first document lands. */
+    readonly document: DraftDocument | null;
+    /** The pinned snapshot, or `null` before the pin writes it. */
+    readonly snapshot: ReportSnapshot | null;
+    readonly createdAt: Date;
+}
+/** The snapshot and the anchor of a row to create. */
+export interface WriteSnapshotInput {
+    readonly threadId: string;
+    readonly analysisId: string;
+    /** The pinned snapshot, stored as given. */
+    readonly snapshot: ReportSnapshot;
+}
+/** The document to persist against an existing row, and the prior document that the load read. */
+export interface PersistDocumentInput {
+    readonly threadId: string;
+    /** The draft document, stored as given. */
+    readonly document: DraftDocument;
+    /**
+     * The prior document that the load read, or `null` before the first document lands.
+     * The persist lands only when the row still holds it, thus a concurrent turn that
+     * landed first turns this persist into a conflict.
+     */
+    readonly expected: DraftDocument | null;
+}
+/**
+ * The outcome of a persist. `persisted` landed the document. `conflict` means the row
+ * no longer holds the expected prior document, thus a concurrent turn landed first and
+ * this turn must read the state again. `absent` means no row holds the thread.
+ */
+export type PersistOutcome = "persisted" | "conflict" | "absent";
+/**
+ * A stored row that a read cannot parse with the current schemas. It names the
+ * thread id and the part that failed, and it carries the reduced issues.
+ */
+export type SessionStateReadError = {
+    readonly type: "corrupt_session_state";
+    readonly op: string;
+    readonly threadId: string;
+    readonly part: "document" | "snapshot";
+    readonly issues: readonly SchemaIssue[];
+};
+export interface ReportSessionStateStore {
+    /**
+     * The state of a thread, or `null` when no row holds it. A parse failure on a
+     * stored column reads as a typed error, and an absent row reads as a normal
+     * absence.
+     */
+    readState(threadId: string): ResultAsync<ReportSessionState | null, DbError | SessionStateReadError>;
+    /**
+     * Write the snapshot at row creation, insert-if-absent. Two concurrent first
+     * calls make one row through ON CONFLICT DO NOTHING, and the winner keeps its
+     * snapshot. The store reads the row back, thus the caller sees the durable state.
+     */
+    writeSnapshot(input: WriteSnapshotInput): ResultAsync<ReportSessionState, DbError | SessionStateReadError>;
+    /**
+     * Persist the document of a thread against the prior document that the load read.
+     * The row must exist, pinned by `writeSnapshot` first. The update lands only when
+     * the row still holds the prior document. `persisted` landed it, `conflict` means a
+     * concurrent turn landed first, and `absent` means no row holds the thread.
+     */
+    persistDocument(input: PersistDocumentInput): ResultAsync<PersistOutcome, DbError>;
+}
+export interface ReportSessionStateStoreDeps {
+    readonly pool: Pool;
+    readonly logger?: Logger;
+}
+/**
+ * Create a `ReportSessionStateStore` bound to a Postgres pool. The
+ * `cortex_report_session_state` table is provisioned by the state-init DDL.
+ */
+export declare function createReportSessionStateStore({ pool }: ReportSessionStateStoreDeps): ReportSessionStateStore;

package/dist/state/report-session-state.js

@@ -0,0 +1,150 @@
+/**
+ * The report session-state store -- the mutable working state of one report session.
+ *
+ * One row holds the state of one report session, keyed by the thread id. The row
+ * holds the in-progress draft document and the pinned snapshot. The row is mutable,
+ * and it differs from a recorded version this way. A session reads the state, writes
+ * the snapshot one time at the start, and persists the document as the composition
+ * proceeds.
+ *
+ * The snapshot writes at row creation. The write is insert-if-absent through
+ * ON CONFLICT DO NOTHING. Thus two concurrent first calls make one row, and the
+ * winner keeps its snapshot. The store reads the row back after the write, thus the
+ * caller sees the durable state whichever call won.
+ *
+ * The document column and the snapshot column are each nullable. A row exists with a
+ * snapshot and no document yet, because the pin writes the snapshot first and the
+ * document lands later. A null column reads as a null value.
+ *
+ * A read parses the stored document with the draft schema, and the stored snapshot
+ * with `parseSnapshot`. The document is the draft document, because an in-progress
+ * document can be incomplete. A column that fails a parse reads as a typed error, and
+ * it does not crash. An absent row reads as a normal absence.
+ *
+ * A persist is a compare-and-swap. The load reads the prior document, and the persist
+ * lands only when the row still holds it. Thus two concurrent turns cannot both land,
+ * and the loser reads the state again.
+ *
+ * A purge of the analysis removes the row through the analysis-id cascade.
+ */
+import { err, ok } from "neverthrow";
+import { tryMutation, tryQuery } from "../lib/db-result.js";
+import { DraftDocumentSchema } from "../report-model/draft.js";
+import { parseSnapshot, reduceIssues } from "./snapshot-parse.js";
+const _assertReadError = true;
+/** The full row projection every read shares. */
+const STATE_COLUMNS = "thread_id, analysis_id, document, snapshot, created_at";
+/**
+ * The insert. The row carries the snapshot at creation, and the document lands later
+ * through `persistDocument`. ON CONFLICT DO NOTHING keeps the first row, thus a
+ * second first call cannot replace the snapshot.
+ */
+const INSERT_SQL = `INSERT INTO cortex_report_session_state
+    (thread_id, analysis_id, snapshot)
+  VALUES ($1, $2, $3::jsonb)
+  ON CONFLICT (thread_id) DO NOTHING`;
+function rowToState(row) {
+    let document = null;
+    if (row.document !== null) {
+        const parsed = DraftDocumentSchema.safeParse(row.document);
+        if (!parsed.success) {
+            return err({
+                type: "corrupt_session_state",
+                op: "report-session-state.read",
+                threadId: row.thread_id,
+                part: "document",
+                issues: reduceIssues(parsed.error),
+            });
+        }
+        document = parsed.data;
+    }
+    let snapshot = null;
+    if (row.snapshot !== null) {
+        const parsed = parseSnapshot(row.snapshot);
+        if (parsed.isErr()) {
+            return err({
+                type: "corrupt_session_state",
+                op: "report-session-state.read",
+                threadId: row.thread_id,
+                part: "snapshot",
+                issues: parsed.error,
+            });
+        }
+        snapshot = parsed.value;
+    }
+    return ok({
+        threadId: row.thread_id,
+        analysisId: row.analysis_id,
+        document,
+        snapshot,
+        createdAt: row.created_at,
+    });
+}
+/**
+ * Create a `ReportSessionStateStore` bound to a Postgres pool. The
+ * `cortex_report_session_state` table is provisioned by the state-init DDL.
+ */
+export function createReportSessionStateStore({ pool }) {
+    function selectRow(op, threadId) {
+        return tryQuery(op, () => pool.query({
+            text: `SELECT ${STATE_COLUMNS} FROM cortex_report_session_state WHERE thread_id = $1`,
+            values: [threadId],
+        })).map(({ rows }) => rows[0] ?? null);
+    }
+    function readState(threadId) {
+        return selectRow("report-session-state.readState", threadId).andThen((row) => {
+            if (!row)
+                return ok(null);
+            return rowToState(row);
+        });
+    }
+    function writeSnapshot(input) {
+        return tryMutation("report-session-state.writeSnapshot", async () => {
+            await pool.query({
+                text: INSERT_SQL,
+                values: [input.threadId, input.analysisId, JSON.stringify(input.snapshot)],
+            });
+        })
+            .andThen(() => selectRow("report-session-state.writeSnapshot.readBack", input.threadId))
+            .andThen((row) => {
+            if (!row) {
+                // The insert-if-absent guarantees a row. Absence here is not a normal
+                // condition, thus it rides the error channel.
+                return err({
+                    type: "mutation_failed",
+                    op: "report-session-state.writeSnapshot.readBack",
+                    cause: new Error("row absent after insert-if-absent"),
+                });
+            }
+            return rowToState(row);
+        });
+    }
+    function persistDocument(input) {
+        return tryMutation("report-session-state.persistDocument", async () => {
+            // The prior document rides as SQL NULL when absent, thus the compare-and-swap
+            // matches a fresh row whose document column is null. A JSON `null` would be a
+            // distinct jsonb value, and it would never match the null column.
+            const expected = input.expected === null ? null : JSON.stringify(input.expected);
+            // One statement tells a conflict from an absence. `existed` counts the row, and
+            // `updated` counts the compare-and-swap. A row that exists but did not update
+            // holds a different prior document, thus a concurrent turn landed first.
+            const { rows } = await pool.query({
+                text: `WITH target AS (
+    SELECT 1 FROM cortex_report_session_state WHERE thread_id = $1
+  ), updated AS (
+    UPDATE cortex_report_session_state
+       SET document = $2::jsonb
+     WHERE thread_id = $1 AND document IS NOT DISTINCT FROM $3::jsonb
+    RETURNING 1
+  )
+  SELECT (SELECT COUNT(*) FROM target)::int AS existed, (SELECT COUNT(*) FROM updated)::int AS updated`,
+                values: [input.threadId, JSON.stringify(input.document), expected],
+            });
+            const row = rows[0];
+            if (row === undefined || row.existed === 0)
+                return "absent";
+            return row.updated > 0 ? "persisted" : "conflict";
+        });
+    }
+    return { readState, writeSnapshot, persistDocument };
+}

package/dist/state/report-versions.d.ts

@@ -10,7 +10,7 @@
  * one thread trips the constraint, and the store maps that trip to the typed
  * refusal thread_already_holds_version.
  *
- * The store keeps the snapshot and the anchor as given, and it never mints a
+ * The store keeps the snapshot and the anchor as given, and it never pins a
  * snapshot. A read parses the stored document and the stored snapshot with the
  * current schemas. A row that fails a parse reads as a typed error, and it does
  * not crash. An absent row reads as a normal absence.
@@ -25,11 +25,8 @@ import { type ReportDocument } from "../contracts/report-blocks.js";
 import { type DbError } from "../lib/db-result.js";
 import type { Logger } from "../lib/logger.js";
 import type { ReportSnapshot } from "../report-model/reference-resolver.js";
-/** One reduced schema issue -- the dotted path and the message, without the rest. */
-export interface SchemaIssue {
-    readonly path: string;
-    readonly message: string;
-}
+import { type SchemaIssue } from "./snapshot-parse.js";
+export type { SchemaIssue };
 /** The anchor and the payload of a version to record. */
 export interface RecordVersionInput {
     /** The block document. It rides as `unknown`, and the record parses it. */