@inflexa-ai/harness 0.17.0 → 0.19.0

package/dist/report-render/views/values.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The value markup: the metric card, the data table, the figure, and the inline citation.
+ *
+ * The caller resolves each value, and it narrows the value to the shape that the block needs. The runtime
+ * escapes every interpolated string, thus a hostile label, a hostile cell, a hostile caption, or a
+ * hostile source reaches the page as text.
+ */
+import type { CitationBlock, FigureBlock, MetricBlock, TableBlock } from "../../contracts/report-blocks.js";
+import type { ReferenceLedger } from "../references.js";
+import type { RenderValue } from "../types.js";
+/** The scalar value that a metric renders from. */
+type ScalarValue = Extract<RenderValue, {
+    type: "scalar";
+}>;
+/** The table value that a table renders from. */
+type TableValue = Extract<RenderValue, {
+    type: "table";
+}>;
+/** The figure value that a figure renders from. */
+type FigureValue = Extract<RenderValue, {
+    type: "figure";
+}>;
+/** Render a metric block as a stat card with the label and the scalar value. */
+export declare function renderMetric(block: MetricBlock, value: ScalarValue): string;
+/**
+ * Render a table block. The header holds one cell for each column, and the body holds one row for each
+ * resolved row. A zero-row table renders the header alone. The title and the caption render only when the
+ * block carries one. An absent cell renders as an empty cell, thus a ragged row keeps its shape.
+ */
+export declare function renderTable(block: TableBlock, value: TableValue): string;
+/**
+ * Render a figure block. The source rides the `src` attribute, and the caption renders below the image.
+ * The caption also fills the `alt` attribute, thus the escape keeps a hostile source and a hostile caption
+ * inside their slots.
+ */
+export declare function renderFigure(block: FigureBlock, value: FigureValue): string;
+/**
+ * Render a citation block as a short line. The binding joins the ledger like a claim binding, thus one
+ * shared source keeps one number. The optional note renders after the marker.
+ */
+export declare function renderCitation(block: CitationBlock, ledger: ReferenceLedger): string;
+export {};

package/dist/report-render/views/values.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "hono/jsx/jsx-runtime";
+import { Marker } from "./references-view.js";
+/** Render a metric block as a stat card with the label and the scalar value. */
+export function renderMetric(block, value) {
+    return String(_jsxs("div", { class: "corner-accents border border-slate-200 bg-white p-6", children: [_jsx("div", { class: "font-mono text-3xl font-bold", style: "color: #576dea;", children: value.value }), _jsx("div", { class: "font-mono text-xs font-medium text-slate-500 mt-2 uppercase tracking-wider", children: block.label })] }));
+}
+/**
+ * The column order of a table. The value columns win when they are present. The keys of the first row
+ * give the order otherwise, in first-appearance order.
+ */
+function tableColumns(value) {
+    if (value.columns !== undefined) {
+        return value.columns;
+    }
+    const first = value.rows[0];
+    return first !== undefined ? Object.keys(first) : [];
+}
+/**
+ * Render a table block. The header holds one cell for each column, and the body holds one row for each
+ * resolved row. A zero-row table renders the header alone. The title and the caption render only when the
+ * block carries one. An absent cell renders as an empty cell, thus a ragged row keeps its shape.
+ */
+export function renderTable(block, value) {
+    const columns = tableColumns(value);
+    return String(_jsxs("div", { class: "report-table mb-8", children: [block.title !== undefined ? (_jsx("div", { class: "font-mono text-xs font-semibold uppercase tracking-widest text-primary-500 mb-3", children: block.title })) : null, _jsx("div", { class: "corner-accents border border-slate-200 bg-white overflow-hidden", children: _jsx("div", { class: "overflow-x-auto", children: _jsxs("table", { class: "w-full text-sm", children: [_jsx("thead", { children: _jsx("tr", { class: "border-b border-slate-200 bg-slate-50", children: columns.map((column) => (_jsx("th", { class: "px-4 py-3 text-left font-mono text-[11px] font-semibold text-slate-500 uppercase tracking-wider", children: column }))) }) }), _jsx("tbody", { children: value.rows.map((row) => (_jsx("tr", { class: "report-row border-b border-slate-100 last:border-b-0", children: columns.map((column) => (_jsx("td", { class: "px-4 py-2.5 text-slate-700", children: row[column] }))) }))) })] }) }) }), block.caption !== undefined ? _jsx("p", { class: "text-sm text-slate-400 mt-2", children: block.caption }) : null] }));
+}
+/**
+ * Render a figure block. The source rides the `src` attribute, and the caption renders below the image.
+ * The caption also fills the `alt` attribute, thus the escape keeps a hostile source and a hostile caption
+ * inside their slots.
+ */
+export function renderFigure(block, value) {
+    const caption = block.caption;
+    return String(_jsxs("figure", { class: "report-figure mb-8", children: [_jsx("img", { src: value.src, alt: caption !== undefined ? caption : "", class: "max-w-full h-auto border border-slate-200" }), caption !== undefined ? _jsx("figcaption", { class: "text-sm text-slate-400 mt-2", children: caption }) : null] }));
+}
+/**
+ * Render a citation block as a short line. The binding joins the ledger like a claim binding, thus one
+ * shared source keeps one number. The optional note renders after the marker.
+ */
+export function renderCitation(block, ledger) {
+    const n = ledger.mark(block.binding);
+    return String(_jsxs("p", { class: "report-citation text-sm text-slate-500", children: [_jsx(Marker, { n: n }), block.note !== undefined ? (_jsxs(_Fragment, { children: [" ", _jsx("span", { class: "text-slate-600", children: block.note })] })) : null] }));
+}

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/runtime/boot.d.ts

@@ -11,9 +11,9 @@
  *      to a no-op so a library host never acquires process-wide telemetry (or a
  *      console banner) it did not ask for. An embedder that wants harness OTel
  *      passes `initOtel` / `shutdownOtel` here.
- *   2. `validateAgentSkills(skillsDir, SANDBOX_AGENT_META)` — pure fs stat, zero
- *      external deps. A `meta.skills` typo or a `skillsDir` / image drift dies in
- *      milliseconds, before any Postgres or DBOS cost is paid (agent-skill-assignment).
+ *   2. `validateAgentSkills(skillsDir, ...)` — pure fs stat, zero external deps.
+ *      A `meta.skills` typo or a `skillsDir` / image drift dies in milliseconds,
+ *      before any Postgres or DBOS cost is paid (agent-skill-assignment).
  *   3. `initCortexState(pool)` — app tables must exist before launch; recovery
  *      queries them on the first step.
  *   4. `assertConnectionBudget(...)` — needs the live pool; gates launch so a

package/dist/runtime/boot.js

@@ -11,9 +11,9 @@
  *      to a no-op so a library host never acquires process-wide telemetry (or a
  *      console banner) it did not ask for. An embedder that wants harness OTel
  *      passes `initOtel` / `shutdownOtel` here.
- *   2. `validateAgentSkills(skillsDir, SANDBOX_AGENT_META)` — pure fs stat, zero
- *      external deps. A `meta.skills` typo or a `skillsDir` / image drift dies in
- *      milliseconds, before any Postgres or DBOS cost is paid (agent-skill-assignment).
+ *   2. `validateAgentSkills(skillsDir, ...)` — pure fs stat, zero external deps.
+ *      A `meta.skills` typo or a `skillsDir` / image drift dies in milliseconds,
+ *      before any Postgres or DBOS cost is paid (agent-skill-assignment).
  *   3. `initCortexState(pool)` — app tables must exist before launch; recovery
  *      queries them on the first step.
  *   4. `assertConnectionBudget(...)` — needs the live pool; gates launch so a
@@ -38,6 +38,7 @@
  */
 import { unwrapOrThrow } from "../lib/result.js";
 import { SANDBOX_AGENT_META } from "../agents/sandbox/index.js";
+import { REPORT_BUILDER_AGENT_ID, REPORT_BUILDER_SKILLS } from "../agents/report-builder.js";
 import { validateAgentSkills } from "../agents/sandbox/validate-skills.js";
 import { initCortexState } from "../state/init.js";
 import { backfillConversationDisplayEnvelopes } from "../memory/conversation-display-backfill.js";
@@ -48,10 +49,20 @@ import { markDraining } from "./lifecycle.js";
 import { runShutdownSequence } from "./shutdown.js";
 const noop = () => { };
 const noopAsync = () => Promise.resolve();
+/**
+ * Every agent whose declared packs must resolve before the first run. The
+ * report-builder is not in the sandbox catalog — it is not plannable — but it
+ * declares a pack all the same, and a missing one there surfaces as a failed
+ * render partway through a report rather than at boot.
+ */
+const SKILL_DECLARING_AGENTS = {
+    ...SANDBOX_AGENT_META,
+    [REPORT_BUILDER_AGENT_ID]: { id: REPORT_BUILDER_AGENT_ID, skills: REPORT_BUILDER_SKILLS },
+};
 export async function bootHarness(deps) {
     const { core, pool, skillsDir, logger } = deps;
     (deps.initTelemetry ?? noop)();
-    validateAgentSkills(skillsDir, SANDBOX_AGENT_META);
+    validateAgentSkills(skillsDir, SKILL_DECLARING_AGENTS);
     await initCortexState(pool);
     await assertConnectionBudget({ pool, logger, config: deps.connectionBudget });
     const runtime = assembleCoreRuntime(core);

package/dist/runtime/dbos.d.ts

@@ -38,7 +38,8 @@ export interface DbosConfig {
      */
     readonly logLevel?: string;
 }
-interface State {
+/** DBOS lifecycle facts a host's readiness probe reports on. */
+export interface DbosState {
     launched: boolean;
     recoveryStarted: boolean;
 }
@@ -85,9 +86,8 @@ export declare function sweepEphemeralWorkflows({ pool, logger: injectedLogger,
     executorId: string;
 }): Promise<void>;
 /** Snapshot of DBOS lifecycle state — read by the readiness probe. */
-export declare function dbosState(): State;
+export declare function dbosState(): DbosState;
 /** Test hook: force-reset state without calling DBOS. Test-only. */
 export declare function __resetDbosStateForTest(): void;
 /** Test hook: mark launched without calling DBOS. Test-only. */
-export declare function __setDbosStateForTest(next: Partial<State>): void;
-export {};
+export declare function __setDbosStateForTest(next: Partial<DbosState>): void;

package/dist/state/artifacts.d.ts

@@ -57,6 +57,22 @@ export interface StepArtifactRef {
  * slice of it — and so the same call replays to the same rows.
  */
 export declare function queryStepArtifactPaths(pool: Querier, resourceId: string, runId: string, stepId: string, limit: number): Promise<StepArtifactRef[]>;
+/** One registered artifact of an analysis, as a reader of the full artifact set names it. */
+export interface AnalysisArtifactRef {
+    /** Workspace-root-relative path (`runs/{runId}/{stepId}/output/de.csv`). */
+    path: string;
+    hash: string;
+    fileType: string | null;
+}
+/**
+ * Every artifact of one analysis, ordered by path so the same call gives the same rows.
+ *
+ * The query applies no filter. An input row is a member, the same as a step output. A row that carries
+ * `unrecoverable_at` is a member too, because the artifact existed at the moment of this read. If the
+ * query drops such a row, a later refusal says that the artifact never existed, and that reason is
+ * false.
+ */
+export declare function queryAnalysisArtifacts(pool: Querier, analysisId: string): Promise<AnalysisArtifactRef[]>;
 /** Count step-output artifacts produced by a run — for the run-completed card. */
 export declare function countArtifactsForRun(pool: Querier, analysisId: string, runId: string): Promise<number>;
 export declare function updateArtifactId(pool: Querier, resourceId: string, path: string, artifactId: string, fileType?: string | null): Promise<void>;

package/dist/state/artifacts.js

@@ -148,6 +148,24 @@ export async function queryStepArtifactPaths(pool, resourceId, runId, stepId, li
     });
     return result.rows.map((r) => ({ path: r.path, fileType: r.file_type ?? null }));
 }
+/**
+ * Every artifact of one analysis, ordered by path so the same call gives the same rows.
+ *
+ * The query applies no filter. An input row is a member, the same as a step output. A row that carries
+ * `unrecoverable_at` is a member too, because the artifact existed at the moment of this read. If the
+ * query drops such a row, a later refusal says that the artifact never existed, and that reason is
+ * false.
+ */
+export async function queryAnalysisArtifacts(pool, analysisId) {
+    const result = await pool.query({
+        text: `SELECT path, hash, file_type
+          FROM cortex_artifacts
+          WHERE analysis_id = $1
+          ORDER BY path`,
+        values: [analysisId],
+    });
+    return result.rows.map((r) => ({ path: r.path, hash: r.hash, fileType: r.file_type ?? null }));
+}
 /** Count step-output artifacts produced by a run — for the run-completed card. */
 export async function countArtifactsForRun(pool, analysisId, runId) {
     const result = await pool.query({

package/dist/state/init.js

@@ -130,6 +130,60 @@ CREATE TABLE IF NOT EXISTS cortex_plans (
 CREATE INDEX IF NOT EXISTS idx_cortex_plans_analysis
   ON cortex_plans(analysis_id, created_at DESC);
 
+-- Report versions — one immutable row for each recorded report version. A row
+-- holds the block document, the pinned snapshot, and the anchor. A thread holds
+-- at most one version. The named unique constraint on thread_id enforces the
+-- rule, because the report policy binds one version to each report session. The
+-- row outlives its thread. Thus the table has no foreign key to
+-- cortex_analysis_threads, and the row carries the anchor columns (thread_id,
+-- parent_thread_id, parent_seq) directly. A purge of the analysis removes the row
+-- through the analysis_id cascade. The table is append-only, and a correction is
+-- a new version, never an update to a recorded row.
+CREATE TABLE IF NOT EXISTS cortex_report_versions (
+  version_id        TEXT PRIMARY KEY,
+  analysis_id       TEXT NOT NULL
+                      REFERENCES cortex_analysis_state(analysis_id)
+                      ON DELETE CASCADE,
+  thread_id         TEXT NOT NULL,
+  -- Nullable pair: a root conversation anchor can be absent. A version with no
+  -- parent thread carries no parent_seq either.
+  parent_thread_id  TEXT,
+  parent_seq        BIGINT,
+  parent_version_id TEXT
+                      REFERENCES cortex_report_versions(version_id)
+                      ON DELETE SET NULL,
+  document          JSONB NOT NULL,
+  snapshot          JSONB NOT NULL,
+  created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  CONSTRAINT cortex_report_versions_one_per_thread UNIQUE (thread_id)
+);
+
+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

@@ -80,6 +80,8 @@ const ANALYSIS_KEYED_DELETES = [
     { op: "purgeAnalysis.asks", sql: "DELETE FROM cortex_asks WHERE analysis_id = $1" },
     { 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 };
+}