@inflexa-ai/harness 0.18.0 → 0.19.1

package/dist/state/init.js

@@ -161,6 +161,37 @@ 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.
+--
+-- The two hash columns are the look-before-record markers. rendered_document_hash
+-- holds the hash of the draft that the last preview rendered. seen_document_hash
+-- holds the hash that the last eyes capture saw, copied from the rendered hash.
+-- Each is nullable, because a fresh session has run no preview and no eyes. The
+-- record refuses unless the seen hash equals the hash of the current draft.
+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,
+  rendered_document_hash TEXT,
+  seen_document_hash     TEXT,
+  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.
@@ -529,6 +560,11 @@ export async function initCortexState(pool, injected) {
                 "ALTER TABLE cortex_step_executions ADD COLUMN IF NOT EXISTS child_workflow_id TEXT",
                 "CREATE INDEX IF NOT EXISTS idx_cortex_step_exec_child_workflow " + "ON cortex_step_executions(child_workflow_id)",
                 "ALTER TABLE cortex_analysis_state ADD COLUMN IF NOT EXISTS seed_input_file_ids JSONB",
+                // The look-before-record markers of a report session. Nullable and
+                // unbackfilled: a session with no preview and no eyes carries neither hash,
+                // which is the honest state, thus an existing row reads back as never-seen.
+                "ALTER TABLE cortex_report_session_state ADD COLUMN IF NOT EXISTS rendered_document_hash TEXT",
+                "ALTER TABLE cortex_report_session_state ADD COLUMN IF NOT EXISTS seen_document_hash TEXT",
                 // Databases created before `data_profile_status` became nullable still
                 // carry the NOT NULL floor, which would reject a clear. Idempotent:
                 // dropping an absent NOT NULL no-ops, so this is a no-op on fresh DBs.

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,139 @@
+/**
+ * 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;
+    /** The hash of the draft that the last preview rendered, or `null` before the first preview. */
+    readonly renderedDocumentHash: string | null;
+    /** The hash that the last eyes capture saw, or `null` before the first look. */
+    readonly seenDocumentHash: string | 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";
+/**
+ * The outcome of a stamp. `stamped` wrote the hash on the row. `absent` means that no row holds the
+ * thread, thus the stamp wrote nothing. A stamp reads nothing before the write.
+ */
+export type StampOutcome = "stamped" | "absent";
+/**
+ * The outcome of the seen stamp. `stamped` copied a rendered hash onto the seen hash. `no-rendered`
+ * means that the row holds no rendered hash, thus no preview stamped one and the copy found none.
+ * `absent` means that no row holds the thread.
+ */
+export type SeenStampOutcome = "stamped" | "no-rendered" | "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>;
+    /**
+     * Stamp the rendered-document hash on the row. The preview calls it when the page lands, thus the row
+     * holds the hash of the draft that the page shows. `absent` means that no row holds the thread.
+     */
+    stampRendered(threadId: string, hash: string): ResultAsync<StampOutcome, DbError>;
+    /**
+     * Copy the rendered hash onto the seen hash. The eyes call it after a capture, thus the seen hash holds
+     * the hash of the draft that the picture shows, and never the current one. The operation reports whether
+     * a rendered hash existed to copy. `no-rendered` means that the row holds none, thus no preview stamped
+     * one. `absent` means that no row holds the thread.
+     */
+    stampSeen(threadId: string): ResultAsync<SeenStampOutcome, 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,177 @@
+/**
+ * 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, rendered_document_hash, seen_document_hash, 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,
+        renderedDocumentHash: row.rendered_document_hash,
+        seenDocumentHash: row.seen_document_hash,
+        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";
+        });
+    }
+    function stampRendered(threadId, hash) {
+        return tryMutation("report-session-state.stampRendered", async () => {
+            const { rowCount } = await pool.query({
+                text: "UPDATE cortex_report_session_state SET rendered_document_hash = $2 WHERE thread_id = $1",
+                values: [threadId, hash],
+            });
+            return (rowCount ?? 0) > 0 ? "stamped" : "absent";
+        });
+    }
+    function stampSeen(threadId) {
+        return tryMutation("report-session-state.stampSeen", async () => {
+            // The seen hash takes the rendered hash of the same row. A copy inside the statement keeps the
+            // two markers on one row, thus the eyes copy the rendered hash and never the current one. The
+            // `RETURNING` clause reads the copied rendered hash back, thus the caller tells a real stamp from
+            // a row that holds no rendered hash to copy.
+            const { rows } = await pool.query({
+                text: "UPDATE cortex_report_session_state SET seen_document_hash = rendered_document_hash WHERE thread_id = $1 RETURNING rendered_document_hash AS copied",
+                values: [threadId],
+            });
+            const row = rows[0];
+            if (row === undefined)
+                return "absent";
+            return row.copied === null ? "no-rendered" : "stamped";
+        });
+    }
+    return { readState, writeSnapshot, persistDocument, stampRendered, stampSeen };
+}

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. */

package/dist/state/report-versions.js

@@ -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.
@@ -21,42 +21,15 @@
  */
 import { randomUUID } from "node:crypto";
 import { err, errAsync, ok } from "neverthrow";
-import { z } from "zod";
 import { ReportDocumentSchema } from "../contracts/report-blocks.js";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
+import { parseSnapshot, reduceIssues } from "./snapshot-parse.js";
 /**
  * The name of the unique constraint on thread_id. Postgres reports it on a
  * duplicate-thread refusal, and the record matches it to map the trip to the
  * thread_already_holds_version refusal.
  */
 const THREAD_UNIQUE_CONSTRAINT = "cortex_report_versions_one_per_thread";
-/**
- * One pinned artifact of a stored snapshot. The value carries the content hash,
- * an optional file type, and optional rows. The `z.ZodType<ReportSnapshot>`
- * annotation below keeps this schema and the `ArtifactSnapshot` type of the
- * reference model in step, thus a change to one shows as a compile error there.
- */
-const ArtifactSnapshotSchema = z.object({
-    hash: z.string(),
-    fileType: z.string().nullable().optional(),
-    rows: z.array(z.record(z.string(), z.union([z.string(), z.number()]))).optional(),
-});
-/**
- * The stored-snapshot schema. The annotation ties the parse output to the
- * `ReportSnapshot` type of the reference model, thus the store and the structural
- * validation never disagree about the snapshot shape. The mint never fills `rows`,
- * but the schema admits what the type admits.
- */
-const ReportSnapshotSchema = z.object({
-    artifacts: z.record(z.string(), ArtifactSnapshotSchema),
-    citations: z.array(z.string()).optional(),
-});
-function reduceIssues(error) {
-    return error.issues.map((issue) => ({
-        path: issue.path.map((segment) => String(segment)).join("."),
-        message: issue.message,
-    }));
-}
 const _assertRecordError = true;
 const _assertReadError = true;
 /**
@@ -78,9 +51,9 @@ function rowToVersion(row) {
     if (!document.success) {
         return err({ type: "corrupt_version", op: "report-versions.read", versionId: row.version_id, part: "document", issues: reduceIssues(document.error) });
     }
-    const snapshot = ReportSnapshotSchema.safeParse(row.snapshot);
-    if (!snapshot.success) {
-        return err({ type: "corrupt_version", op: "report-versions.read", versionId: row.version_id, part: "snapshot", issues: reduceIssues(snapshot.error) });
+    const snapshot = parseSnapshot(row.snapshot);
+    if (snapshot.isErr()) {
+        return err({ type: "corrupt_version", op: "report-versions.read", versionId: row.version_id, part: "snapshot", issues: snapshot.error });
     }
     return ok({
         versionId: row.version_id,
@@ -90,7 +63,7 @@ function rowToVersion(row) {
         parentSeq: row.parent_seq === null ? null : Number(row.parent_seq),
         parentVersionId: row.parent_version_id,
         document: document.data,
-        snapshot: snapshot.data,
+        snapshot: snapshot.value,
         createdAt: row.created_at,
     });
 }
@@ -126,11 +99,11 @@ export function createReportVersionStore({ pool }) {
             return errAsync({ type: "malformed_document", op: "report-versions.record", issues: reduceIssues(parsed.error) });
         }
         const document = parsed.data;
-        // The parse guards the row against a caller bug through a cast. The store
-        // stores the given value, thus the parse changes no value.
-        const parsedSnapshot = ReportSnapshotSchema.safeParse(input.snapshot);
-        if (!parsedSnapshot.success) {
-            return errAsync({ type: "malformed_snapshot", op: "report-versions.record", issues: reduceIssues(parsedSnapshot.error) });
+        // The parse guards the row against a caller bug. The store stores the given
+        // value, thus the parse changes no value.
+        const parsedSnapshot = parseSnapshot(input.snapshot);
+        if (parsedSnapshot.isErr()) {
+            return errAsync({ type: "malformed_snapshot", op: "report-versions.record", issues: parsedSnapshot.error });
         }
         const insert = () => {
             const versionId = randomUUID();

package/dist/state/snapshot-parse.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The one parse of a stored report snapshot, shared by the two stores.
+ *
+ * The session-state store and the version store each hold a snapshot column, and
+ * each reads it back the same way. A path such as `__proto__` is an ordinary
+ * artifact key of the ledger, and the pin keeps it as an own member of a
+ * null-prototype map (`report-model/pin-snapshot.ts`). Each object-shaped schema
+ * of zod drops such a key, thus a store that parsed the map through one would
+ * resolve a reference to that artifact before a reload and refuse it as absent
+ * after one. The walk reads the own keys of the stored map, and it parses each
+ * value on its own, thus the two stores agree on the key set.
+ */
+import { type Result } from "neverthrow";
+import { z } from "zod";
+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;
+}
+/** Reduce a zod error to the dotted path and the message of each issue. */
+export declare function reduceIssues(error: z.ZodError): SchemaIssue[];
+/**
+ * Parse a stored snapshot.
+ *
+ * The artifacts map never goes through a zod object schema, for the reason that
+ * the module header gives: a zod object drops a `__proto__` key and the pin keeps
+ * it. The walk reads the own keys of the stored map, and it parses each value on
+ * its own.
+ *
+ * The `ReportSnapshot` return type ties this parse to the type of the reference
+ * model, thus a change to one shows as a compile error here.
+ */
+export declare function parseSnapshot(stored: unknown): Result<ReportSnapshot, SchemaIssue[]>;

package/dist/state/snapshot-parse.js

@@ -0,0 +1,82 @@
+/**
+ * The one parse of a stored report snapshot, shared by the two stores.
+ *
+ * The session-state store and the version store each hold a snapshot column, and
+ * each reads it back the same way. A path such as `__proto__` is an ordinary
+ * artifact key of the ledger, and the pin keeps it as an own member of a
+ * null-prototype map (`report-model/pin-snapshot.ts`). Each object-shaped schema
+ * of zod drops such a key, thus a store that parsed the map through one would
+ * resolve a reference to that artifact before a reload and refuse it as absent
+ * after one. The walk reads the own keys of the stored map, and it parses each
+ * value on its own, thus the two stores agree on the key set.
+ */
+import { err, ok } from "neverthrow";
+import { z } from "zod";
+/**
+ * One pinned artifact of a stored snapshot. The value carries the content hash, an
+ * optional file type, and optional rows.
+ */
+const ArtifactSnapshotSchema = z.object({
+    hash: z.string(),
+    fileType: z.string().nullable().optional(),
+    rows: z.array(z.record(z.string(), z.union([z.string(), z.number()]))).optional(),
+});
+/** The citation list of a stored snapshot. A snapshot with no list reads as an absent field. */
+const CitationsSchema = z.array(z.string()).optional();
+/** Reduce a zod error to the dotted path and the message of each issue. */
+export function reduceIssues(error) {
+    return error.issues.map((issue) => ({
+        path: issue.path.map((segment) => String(segment)).join("."),
+        message: issue.message,
+    }));
+}
+/** Put a prefix before the path of each issue, thus a nested parse names the key that failed. */
+function prefixIssues(prefix, issues) {
+    return issues.map((issue) => ({
+        path: issue.path === "" ? prefix : `${prefix}.${issue.path}`,
+        message: issue.message,
+    }));
+}
+/** A stored map is a plain object. An array and a null carry no own key that a map read can use. */
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Parse a stored snapshot.
+ *
+ * The artifacts map never goes through a zod object schema, for the reason that
+ * the module header gives: a zod object drops a `__proto__` key and the pin keeps
+ * it. The walk reads the own keys of the stored map, and it parses each value on
+ * its own.
+ *
+ * The `ReportSnapshot` return type ties this parse to the type of the reference
+ * model, thus a change to one shows as a compile error here.
+ */
+export function parseSnapshot(stored) {
+    if (!isPlainRecord(stored)) {
+        return err([{ path: "", message: "the stored snapshot is not an object" }]);
+    }
+    if (!isPlainRecord(stored.artifacts)) {
+        return err([{ path: "artifacts", message: "the artifacts map is not an object" }]);
+    }
+    const citations = CitationsSchema.safeParse(stored.citations);
+    if (!citations.success) {
+        return err(prefixIssues("citations", reduceIssues(citations.error)));
+    }
+    // The map takes a null prototype, the same as the pin, thus a path such as
+    // `__proto__` stays an ordinary entry and never reaches a prototype slot.
+    const artifacts = Object.create(null);
+    const issues = [];
+    for (const [path, value] of Object.entries(stored.artifacts)) {
+        const parsed = ArtifactSnapshotSchema.safeParse(value);
+        if (!parsed.success) {
+            issues.push(...prefixIssues(`artifacts.${path}`, reduceIssues(parsed.error)));
+            continue;
+        }
+        artifacts[path] = parsed.data;
+    }
+    if (issues.length > 0) {
+        return err(issues);
+    }
+    return citations.data === undefined ? ok({ artifacts }) : ok({ artifacts, citations: citations.data });
+}