@inflexa-ai/harness 0.16.0 → 0.18.0

package/dist/runtime/assemble.d.ts

@@ -14,14 +14,18 @@
  * `applicationVersion` stamp because all registration happens in this one call,
  * before launch — a blue/green drain treats them as a single cohort.
  */
+import { type Result } from "neverthrow";
 import { type ConversationAgentDeps } from "../agents/conversation-agent.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ResourcePolicy } from "../config/resource-limits.js";
 import type { AgentDefinition } from "../loop/types.js";
+import type { ThreadType } from "../memory/thread-store.js";
 import { type ExecuteAnalysisDeps, type ExecuteAnalysisInput, type ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
 import { type SandboxStepDeps, type SandboxStepInput, type SandboxStepResult } from "../workflows/sandbox-step.js";
 import { type ExecuteTargetAssessmentDeps, type ExecuteTargetAssessmentInput, type ExecuteTargetAssessmentResult } from "../workflows/execute-target-assessment.js";
 import { type DataProfileDeps, type DataProfileWorkflowInput } from "../tasks/data-profile.js";
+import { type CitationResolverConfig } from "../citations/resolve.js";
+import type { CitationResolver } from "../citations/types.js";
 /** Registered child sandbox-step callable the parent's child dispatch closes over. */
 export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxStepResult>;
 /**
@@ -38,8 +42,8 @@ export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxSt
  * conversation side.
  */
 export interface CoreWorkflowDeps {
-    readonly sandboxStep: Omit<SandboxStepDeps, "usageRecorder">;
-    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => Omit<ExecuteAnalysisDeps, "usageRecorder">;
+    readonly sandboxStep: Omit<SandboxStepDeps, "usageRecorder" | "citationResolver">;
+    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => Omit<ExecuteAnalysisDeps, "usageRecorder" | "citationResolver">;
     readonly executeTargetAssessment: Omit<ExecuteTargetAssessmentDeps, "usageRecorder">;
     readonly dataProfile: Omit<DataProfileDeps, "usageRecorder">;
 }
@@ -56,7 +60,7 @@ export interface RegisteredWorkflows {
  * cannot wire a stale callable, a policy that diverges from the one the
  * workflows see, or a recorder that only half the agent tree reports to.
  */
-export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder">;
+export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder" | "citationResolver">;
 export interface CoreRuntimeDeps {
     readonly conversation: ConversationAssemblyDeps;
     readonly workflows: CoreWorkflowDeps;
@@ -72,9 +76,51 @@ export interface CoreRuntimeDeps {
      * `createNoopUsageRecorder()`.
      */
     readonly usageRecorder?: UsageRecorder;
+    /** Harness-owned citation capability configuration; no ambient lookup occurs. */
+    readonly citationResolverConfig?: CitationResolverConfig;
 }
+/**
+ * The refusal a thread type carries no agent yet. `report` is a valid
+ * `ThreadType` with no registered agent until its builder plugs in at assembly,
+ * so resolution has to have a typed way to say "not that one" without throwing.
+ * The channel is permanent, not interim: `ThreadType` grows over the product's
+ * life, and a bare-`AgentDefinition` return would force every future member to
+ * register an agent in the same commit that adds the member.
+ */
+export interface UnregisteredThreadType {
+    readonly type: "unregistered_thread_type";
+    readonly threadType: ThreadType;
+}
+/**
+ * How a thread's type selects the agent that runs its turns. Resolution is a
+ * synchronous record lookup, so the channel is plain `Result`, never
+ * `ResultAsync`: a registered type resolves to its assembled singleton, an
+ * unregistered one refuses on the error channel.
+ */
+export interface ThreadAgentResolver {
+    forThread(type: ThreadType): Result<AgentDefinition, UnregisteredThreadType>;
+}
+/**
+ * Wrap a type→agent registry as the resolution surface. Held apart from
+ * `assembleCoreRuntime` so the resolution contract — a registered type resolves
+ * to the very object the registry holds, an unregistered one refuses — is
+ * exercisable without the DBOS registration `assembleCoreRuntime` performs.
+ *
+ * The registry holds assembled singletons, so `forThread` returns the same
+ * `AgentDefinition` object on every call for a given type: construction-time
+ * captures (an embedder's delegating provider handles, closure-wired tools)
+ * stay valid across every turn.
+ */
+export declare function createThreadAgentResolver(registry: Partial<Record<ThreadType, AgentDefinition>>): ThreadAgentResolver;
 export interface CoreRuntime {
-    readonly conversationAgent: AgentDefinition;
+    /**
+     * Thread→agent resolution — the only way to reach an assembled agent by
+     * thread type. Holds the singletons this call built; `conversation` resolves
+     * to the assembled conversation agent, every not-yet-registered type refuses
+     * on the `Result` channel.
+     */
+    readonly agents: ThreadAgentResolver;
     readonly workflows: RegisteredWorkflows;
+    readonly citationResolver: CitationResolver;
 }
 export declare function assembleCoreRuntime(deps: CoreRuntimeDeps): CoreRuntime;

package/dist/runtime/assemble.js

@@ -14,17 +14,50 @@
  * `applicationVersion` stamp because all registration happens in this one call,
  * before launch — a blue/green drain treats them as a single cohort.
  */
+import { err, ok } from "neverthrow";
 import { createConversationAgent } from "../agents/conversation-agent.js";
 import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { registerExecuteAnalysis } from "../workflows/execute-analysis.js";
 import { registerSandboxStep } from "../workflows/sandbox-step.js";
 import { registerExecuteTargetAssessment, } from "../workflows/execute-target-assessment.js";
 import { registerDataProfileWorkflow } from "../tasks/data-profile.js";
+import { createCitationResolver } from "../citations/resolve.js";
+const _assertDomainError = true;
+/**
+ * Wrap a type→agent registry as the resolution surface. Held apart from
+ * `assembleCoreRuntime` so the resolution contract — a registered type resolves
+ * to the very object the registry holds, an unregistered one refuses — is
+ * exercisable without the DBOS registration `assembleCoreRuntime` performs.
+ *
+ * The registry holds assembled singletons, so `forThread` returns the same
+ * `AgentDefinition` object on every call for a given type: construction-time
+ * captures (an embedder's delegating provider handles, closure-wired tools)
+ * stay valid across every turn.
+ */
+export function createThreadAgentResolver(registry) {
+    return {
+        forThread: (type) => {
+            const agent = registry[type];
+            if (agent === undefined) {
+                const refusal = { type: "unregistered_thread_type", threadType: type };
+                return err(refusal);
+            }
+            return ok(agent);
+        },
+    };
+}
 export function assembleCoreRuntime(deps) {
     const { conversation, workflows: wf, resourcePolicy } = deps;
     const usageRecorder = deps.usageRecorder ?? createNoopUsageRecorder();
-    const sandboxStep = registerSandboxStep({ ...wf.sandboxStep, usageRecorder });
-    const executeAnalysis = registerExecuteAnalysis({ ...wf.buildExecuteAnalysis(sandboxStep), usageRecorder });
+    const citationResolver = createCitationResolver({
+        ...(deps.citationResolverConfig ?? {}),
+        ...(deps.citationResolverConfig?.ncbiApiKey !== undefined || conversation.bioKeys.ncbi === undefined ? {} : { ncbiApiKey: conversation.bioKeys.ncbi }),
+        ...(deps.citationResolverConfig?.semanticScholarApiKey !== undefined || conversation.bioKeys.semanticScholar === undefined
+            ? {}
+            : { semanticScholarApiKey: conversation.bioKeys.semanticScholar }),
+    });
+    const sandboxStep = registerSandboxStep({ ...wf.sandboxStep, citationResolver, usageRecorder });
+    const executeAnalysis = registerExecuteAnalysis({ ...wf.buildExecuteAnalysis(sandboxStep), citationResolver, usageRecorder });
     const executeTargetAssessment = registerExecuteTargetAssessment({ ...wf.executeTargetAssessment, usageRecorder });
     const dataProfile = registerDataProfileWorkflow({ ...wf.dataProfile, usageRecorder });
     const conversationAgent = createConversationAgent({
@@ -32,14 +65,25 @@ export function assembleCoreRuntime(deps) {
         executeAnalysisWorkflow: executeAnalysis,
         resourcePolicy,
         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.
+    const agents = {
+        conversation: conversationAgent,
+    };
     return {
-        conversationAgent,
+        agents: createThreadAgentResolver(agents),
         workflows: {
             executeAnalysis,
             sandboxStep,
             executeTargetAssessment,
             dataProfile,
         },
+        citationResolver,
     };
 }

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
@@ -36,7 +36,9 @@
  * releases whatever it acquired). Only `shutdown` swallows per-step failures —
  * once shutdown starts, exiting takes precedence (see `runShutdownSequence`).
  */
+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";
@@ -47,17 +49,32 @@ 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);
+    // Assembly registers `conversation` unconditionally, so this resolution can
+    // never refuse; `unwrapOrThrow` turns the impossible error branch into a
+    // boot-propagating throw rather than threading a Result through the boot
+    // sequence, whose steps already fail by propagation.
+    const conversationAgent = unwrapOrThrow(runtime.agents.forThread("conversation"));
     await backfillConversationDisplayEnvelopes({
         pool,
         resolveWorkspaceRoot: core.conversation.resolveWorkspaceRoot,
-        tools: runtime.conversationAgent.tools,
+        tools: conversationAgent.tools,
     });
     await deps.beforeLaunch?.();
     await launchDbos({ config: deps.dbos, logger });

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,37 @@ 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);
+
 -- 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.
@@ -275,12 +306,57 @@ CREATE TABLE IF NOT EXISTS cortex_analysis_threads (
   title       TEXT,
   created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  deleted_at  TIMESTAMPTZ
+  deleted_at  TIMESTAMPTZ,
+  thread_type TEXT NOT NULL DEFAULT 'conversation',
+  -- The cascade on this self-reference is a BACKSTOP, never the deletion path.
+  -- messages carries no foreign key to this table, so a cascade firing on its
+  -- own drops a descendant's metadata row while leaving that descendant's
+  -- messages rows behind with nothing naming them, beyond the reach of any
+  -- later thread-scoped or analysis-scoped reclamation. purgeThread therefore
+  -- walks the subtree and deletes its messages rows explicitly, to the same
+  -- depth the cascade reaches.
+  parent_thread_id TEXT REFERENCES cortex_analysis_threads(thread_id) ON DELETE CASCADE,
+  parent_seq  BIGINT
 );
 
+-- These three sit here, and not in the additive block further down, because the
+-- index below reads one of them. CREATE TABLE IF NOT EXISTS adds no column to a
+-- table that already exists, so on every database but a brand new one the column
+-- arrives from an ALTER -- and the whole additive block runs after this text. An
+-- index declared here over a column added there fails with 42703 on exactly the
+-- databases a migration exists to serve. Additive with no backfill either way: an
+-- existing row reads back as a root conversation thread with no anchor, which is
+-- what it is.
+ALTER TABLE cortex_analysis_threads
+  ADD COLUMN IF NOT EXISTS thread_type TEXT NOT NULL DEFAULT 'conversation';
+
+ALTER TABLE cortex_analysis_threads
+  ADD COLUMN IF NOT EXISTS parent_thread_id TEXT REFERENCES cortex_analysis_threads(thread_id) ON DELETE CASCADE;
+
+ALTER TABLE cortex_analysis_threads
+  ADD COLUMN IF NOT EXISTS parent_seq BIGINT;
+
 CREATE INDEX IF NOT EXISTS idx_cortex_analysis_threads_analysis
   ON cortex_analysis_threads(analysis_id) WHERE deleted_at IS NULL;
 
+-- Not partial, unlike the analysis index above. Two of the three readers of
+-- parent_thread_id carry no deleted_at predicate and cannot: the recursive
+-- subtree walk in thread-store.ts must reach archived descendants, and the
+-- referential trigger behind ON DELETE CASCADE is the database's own query.
+-- Postgres uses a partial index only where it can prove the predicate holds, so
+-- a partial index here leaves both to a sequential scan of the whole table.
+-- Over 150k rows that measured 28 ms per walk and 20 ms per cascade, against
+-- 0.06 ms and 0.10 ms with this one. The third reader, a listing filtered by
+-- parent, keeps an index scan either way.
+--
+-- The old partial index goes by name: CREATE INDEX IF NOT EXISTS keeps whatever
+-- definition already holds the name, so a database that built the partial one
+-- would never see this.
+DROP INDEX IF EXISTS idx_cortex_analysis_threads_parent;
+
+CREATE INDEX IF NOT EXISTS idx_cortex_analysis_threads_parent_fk
+  ON cortex_analysis_threads(parent_thread_id);
+
 -- Working memory — the harness WorkingMemory module's table, one row per
 -- analysis. The data column holds a JSONB object with four sections (goal,
 -- constraints, hypotheses, findings). Section updates are a read-modify-write

package/dist/state/purge-analysis.js

@@ -80,6 +80,7 @@ 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.analysisState", sql: "DELETE FROM cortex_analysis_state WHERE analysis_id = $1" },
 ];
 /**

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

@@ -0,0 +1,132 @@
+/**
+ * The report version store -- the append-only record of report versions.
+ *
+ * A version is one immutable row. It holds the block document, the pinned
+ * snapshot, and the anchor. The store records a version and reads a version. It
+ * never updates a recorded row, thus a correction is a new version.
+ *
+ * A thread holds at most one version, and a named unique constraint on the thread
+ * id enforces it. The record reads nothing before the insert. A second record for
+ * 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
+ * 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.
+ *
+ * A version outlives its thread. The anchor columns sit on the row, thus a
+ * deleted thread leaves a recorded version in place. Only a purge of the analysis
+ * removes the version, through the analysis-id cascade.
+ */
+import { type ResultAsync } from "neverthrow";
+import type { Pool } from "pg";
+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;
+}
+/** 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. */
+    readonly document: unknown;
+    /** The pinned snapshot, stored as given. */
+    readonly snapshot: ReportSnapshot;
+    readonly analysisId: string;
+    readonly threadId: string;
+    /** The parent conversation thread of the anchor, or `null` when a root has none. */
+    readonly parentThreadId: string | null;
+    /** The parent transcript position of the anchor, or `null` beside a null parent thread. */
+    readonly parentSeq: number | null;
+    /** The earlier version that this one reuses. The parent must belong to the same analysis. */
+    readonly parentVersionId?: string;
+}
+/** The stable reference of a freshly recorded version. */
+export interface RecordedVersionRef {
+    readonly versionId: string;
+}
+/**
+ * A record the store refuses as data, before or in place of a row. Distinct from
+ * `DbError`: the request describes a version that the store will not write.
+ *
+ * The store parses the document and the snapshot before any row. The store
+ * refuses a malformed document or a malformed snapshot here as typed data, and
+ * no row lands.
+ *
+ * A second record for one thread is `thread_already_holds_version`. The unique
+ * constraint on the thread id trips, and the record maps that one constraint by
+ * its name. Every other constraint trip stays a `DbError`.
+ *
+ * A `parentVersionId` naming no row is not one of these -- the self foreign key
+ * refuses an unknown parent id, and `tryMutation` classifies that refusal as the
+ * `constraint_violation` variant of `DbError`.
+ */
+export type RecordVersionError = {
+    readonly type: "malformed_document";
+    readonly op: string;
+    readonly issues: readonly SchemaIssue[];
+} | {
+    readonly type: "malformed_snapshot";
+    readonly op: string;
+    readonly issues: readonly SchemaIssue[];
+} | {
+    readonly type: "parent_analysis_mismatch";
+    readonly op: string;
+    readonly analysisId: string;
+    readonly parentVersionId: string;
+    readonly parentAnalysisId: string;
+} | {
+    readonly type: "thread_already_holds_version";
+    readonly op: string;
+    readonly threadId: string;
+} | DbError;
+/**
+ * A stored row that a read cannot parse with the current schemas. It names the
+ * version id and the part that failed, and it carries the reduced issues.
+ */
+export type VersionReadError = {
+    readonly type: "corrupt_version";
+    readonly op: string;
+    readonly versionId: string;
+    readonly part: "document" | "snapshot";
+    readonly issues: readonly SchemaIssue[];
+};
+/** One recorded version, as the store gives it back. */
+export interface RecordedVersion {
+    readonly versionId: string;
+    readonly analysisId: string;
+    readonly threadId: string;
+    readonly parentThreadId: string | null;
+    readonly parentSeq: number | null;
+    /** The earlier version that this one reuses, or `null` when it has none. */
+    readonly parentVersionId: string | null;
+    readonly document: ReportDocument;
+    readonly snapshot: ReportSnapshot;
+    readonly createdAt: Date;
+}
+export interface ReportVersionStore {
+    /**
+     * Record a version. The record parses the document, refuses a malformed value
+     * as data with no row, and refuses a parent from a different analysis. It reads
+     * nothing before the insert. A second record for one thread refuses with
+     * thread_already_holds_version. The snapshot and the anchor store as given.
+     */
+    record(input: RecordVersionInput): ResultAsync<RecordedVersionRef, RecordVersionError>;
+    /** One version by its id, or `null` when no row holds it. */
+    getVersion(versionId: string): ResultAsync<RecordedVersion | null, DbError | VersionReadError>;
+    /** The one version of a thread, or `null` for a thread with no version. */
+    getThreadVersion(threadId: string): ResultAsync<RecordedVersion | null, DbError | VersionReadError>;
+}
+export interface ReportVersionStoreDeps {
+    readonly pool: Pool;
+    readonly logger?: Logger;
+}
+/**
+ * Create a `ReportVersionStore` bound to a Postgres pool. The
+ * `cortex_report_versions` table is provisioned by the state-init DDL.
+ */
+export declare function createReportVersionStore({ pool }: ReportVersionStoreDeps): ReportVersionStore;