@inflexa-ai/harness 0.20.0 → 0.21.1

package/dist/sandbox/create-sandbox.d.ts

@@ -120,18 +120,23 @@ export interface CreateSandboxClientConfig {
  */
 export declare function composeAwaitOptions(base: AwaitExecOptions | undefined, transport: SandboxTransport, isAlive: NonNullable<AwaitExecOptions["isAlive"]>): AwaitExecOptions;
 /**
- * Backend-agnostic pre-creation of the writable step tree under the analysis's
+ * Backend-agnostic pre-creation of the writable tree under the analysis's
  * resolved workspace root. On Docker that root is the host dir the container
  * binds; on K8s it lives under the session PVC the sandbox pod mounts via
  * subPath. `mkdir(recursive)` is idempotent, so an existing tree (replay, retry)
- * is not an error. A read-only sandbox has no writable step mount, so there is
+ * is not an error. A read-only sandbox has no writable mount, so there is
  * nothing to pre-create.
  *
- * `stepTreeAccess: "world-writable"` chmods the step dir and each subdir so the
+ * The writable tree is the step directory with its five artifact subdirs, or the
+ * declared write tail as one directory. `sandboxWriteTail` decides which, so the
+ * directory the host makes and the directory the sandbox mounts are the same one,
+ * and the run path keeps the tree it always had.
+ *
+ * `stepTreeAccess: "world-writable"` chmods the directory and each subdir so the
  * uid-1000 sandbox workload can write them through engines that honor host bind
  * ownership. The chmod is explicit, not `mkdir`'s `mode` option: the process
  * umask masks `mkdir`'s mode, and on replay the dirs already exist so `mkdir`
- * would not touch them either way. Scoped to the step write tree — the
+ * would not touch them either way. Scoped to the write tree — the
  * read-only mount sources are never re-moded. Exported for tests.
  */
 export declare function precreateStepTree(deps: {

package/dist/sandbox/create-sandbox.js

@@ -14,14 +14,14 @@
 import { chmod, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { clampResources } from "../config/resource-limits.js";
-import { stepWritePrefix } from "../workspace/paths.js";
+import { tailWritePrefix } from "../workspace/paths.js";
 import { tryMutation } from "../lib/db-result.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { clearSandboxRef, setSandboxRef } from "../state/index.js";
 import { awaitExec } from "./await-exec.js";
 import { createDockerSandboxOps } from "./docker-client.js";
 import { createK8sSandboxOps } from "./k8s-client.js";
-import { STEP_SUBDIRS } from "./mount-plan.js";
+import { sandboxWriteTail } from "./mount-plan.js";
 import { submitExec } from "./submit-exec.js";
 import { toPersistedRef } from "./types.js";
 /**
@@ -35,33 +35,38 @@ export function composeAwaitOptions(base, transport, isAlive) {
     return { isAlive, ...base, transport };
 }
 /**
- * Backend-agnostic pre-creation of the writable step tree under the analysis's
+ * Backend-agnostic pre-creation of the writable tree under the analysis's
  * resolved workspace root. On Docker that root is the host dir the container
  * binds; on K8s it lives under the session PVC the sandbox pod mounts via
  * subPath. `mkdir(recursive)` is idempotent, so an existing tree (replay, retry)
- * is not an error. A read-only sandbox has no writable step mount, so there is
+ * is not an error. A read-only sandbox has no writable mount, so there is
  * nothing to pre-create.
  *
- * `stepTreeAccess: "world-writable"` chmods the step dir and each subdir so the
+ * The writable tree is the step directory with its five artifact subdirs, or the
+ * declared write tail as one directory. `sandboxWriteTail` decides which, so the
+ * directory the host makes and the directory the sandbox mounts are the same one,
+ * and the run path keeps the tree it always had.
+ *
+ * `stepTreeAccess: "world-writable"` chmods the directory and each subdir so the
  * uid-1000 sandbox workload can write them through engines that honor host bind
  * ownership. The chmod is explicit, not `mkdir`'s `mode` option: the process
  * umask masks `mkdir`'s mode, and on replay the dirs already exist so `mkdir`
- * would not touch them either way. Scoped to the step write tree — the
+ * would not touch them either way. Scoped to the write tree — the
  * read-only mount sources are never re-moded. Exported for tests.
  */
 export async function precreateStepTree(deps, meta) {
-    if (meta.readOnly)
+    const write = sandboxWriteTail(meta);
+    if (write === undefined)
         return;
-    const stepDir = stepWritePrefix({
-        workspaceRoot: deps.resolveWorkspaceRoot(meta.analysisId),
-        runId: meta.runId,
-        stepId: meta.stepId,
-    });
-    await mkdir(stepDir, { recursive: true });
-    await Promise.all(STEP_SUBDIRS.map((sub) => mkdir(join(stepDir, sub), { recursive: true })));
+    // `tailWritePrefix` (not a raw `join`) so every segment runs through the same
+    // id validation the mount builders apply — a crafted tail cannot escape the
+    // resolved root.
+    const writeDir = tailWritePrefix({ workspaceRoot: deps.resolveWorkspaceRoot(meta.analysisId), tail: write.tail });
+    await mkdir(writeDir, { recursive: true });
+    await Promise.all(write.subdirs.map((sub) => mkdir(join(writeDir, sub), { recursive: true })));
     if (deps.stepTreeAccess === "world-writable") {
-        await chmod(stepDir, 0o777);
-        await Promise.all(STEP_SUBDIRS.map((sub) => chmod(join(stepDir, sub), 0o777)));
+        await chmod(writeDir, 0o777);
+        await Promise.all(write.subdirs.map((sub) => chmod(join(writeDir, sub), 0o777)));
     }
 }
 export function createSandboxClient(config) {
@@ -122,6 +127,7 @@ export function createSandboxClient(config) {
     // poll loop's escalation probe are the same backend inspect.
     const isAlive = async (ref) => unwrapOrThrow(await ops.isAlive(ref));
     return {
+        transport,
         createSandbox: async (meta, identity) => {
             // The config states an engine fact (binds preserve host ownership);
             // which remediation that fact demands — today, a world-writable step

package/dist/sandbox/docker-client.js

@@ -33,9 +33,9 @@ import { join } from "node:path";
 import Docker from "dockerode";
 import { ResultAsync, err, ok } from "neverthrow";
 import { createNoopLogger } from "../lib/console-logger.js";
-import { stepWritePrefix } from "../workspace/paths.js";
+import { tailWritePrefix } from "../workspace/paths.js";
 import { trySandbox } from "./sandbox-error.js";
-import { buildMountPlan } from "./mount-plan.js";
+import { buildMountPlan, sandboxWriteTail } from "./mount-plan.js";
 /** Read the originating HTTP status off any `SandboxError` variant that carries one. */
 function statusOf(e) {
     return "status" in e ? e.status : undefined;
@@ -223,13 +223,16 @@ export function createDockerSandboxOps(config) {
                     refs: refsMounted,
                 });
                 const hostTreePath = config.resolveWorkspaceRoot(meta.analysisId);
-                // `stepWritePrefix` (not a raw `join`) so the RW bind source runs through
-                // the same id validation as the pre-created step tree — a crafted stepId
-                // cannot escape the resolved root into the container.
-                const hostStepPath = stepWritePrefix({ workspaceRoot: hostTreePath, runId: meta.runId, stepId: meta.stepId });
+                // `tailWritePrefix` (not a raw `join`) so the RW bind source runs through
+                // the same validation as the pre-created write tree — a crafted stepId or
+                // a crafted tail cannot escape the resolved root into the container. The
+                // tail is the step directory, or the one the caller declared.
+                const write = sandboxWriteTail(meta);
                 const binds = [
                     `${hostTreePath}:${plan.readonlyTreePath}:ro`,
-                    ...(plan.writableStepPath ? [`${hostStepPath}:${plan.writableStepPath}:rw`] : []),
+                    ...(write && plan.writableStepPath
+                        ? [`${tailWritePrefix({ workspaceRoot: hostTreePath, tail: write.tail })}:${plan.writableStepPath}:rw`]
+                        : []),
                     ...(libsMounted && config.libStorePath ? [`${config.libStorePath}:${plan.libsPath}:ro`] : []),
                     ...(refsMounted && config.refStorePath ? [`${config.refStorePath}:${plan.refsPath}:ro`] : []),
                 ];

package/dist/sandbox/mount-plan.d.ts

@@ -10,6 +10,17 @@
  * artifacts, lib store read-only at `/mnt/libs`, ref store read-only at
  * `/mnt/refs`.
  *
+ * A caller can declare its own `writableTail` in place of the step tail — a
+ * workspace-relative path that becomes the one read-write mount, with no step
+ * subdirectories under it. The session derivation declares one; the run path
+ * declares none and keeps the step tail. Thus a sandbox writes into the step
+ * directory or into the one declared tail, and nowhere else.
+ *
+ * The precedence is a refusal, not an order: `readOnly` and `writableTail` state
+ * opposite things about the same mount, thus a coordinate set that carries both
+ * throws here — the same as a crafted id. No caller can hold both and get a
+ * silently chosen winner.
+ *
  * Container paths are a function of `resourceId` alone — they never carry the
  * host location of the tree. Where that tree physically lives is the embedder's
  * (`resolveWorkspaceRoot`); the two are reconciled per backend: Docker binds the
@@ -34,6 +45,14 @@ export interface MountPlanCoords {
      * a generic read-only agent that must not mutate analysis files.
      */
     readOnly?: boolean;
+    /**
+     * The declared write tail: a workspace-relative path that takes the place of the
+     * step tail as the one read-write mount, with no step subdirectories under it.
+     * Each segment passes the safe-id discipline of the step builder. Absent keeps
+     * the step tail, thus the run path is unchanged. A tail beside `readOnly` is a
+     * contradiction, and the builders refuse it.
+     */
+    writableTail?: string;
 }
 export interface MountPlanStores {
     /** Lib store is mounted at `/mnt/libs` and its env is emitted. */
@@ -45,20 +64,21 @@ export interface MountPlan {
     /** Flat read-only mount of the whole analysis tree. */
     readonlyTreePath: string;
     /**
-     * Nested read-write mount for this step's artifacts, also the WorkingDir.
-     * Undefined for a read-only sandbox — no writable mount exists; the
-     * WorkingDir falls back to the read-only tree root.
+     * Nested read-write mount, also the WorkingDir: the step's artifact directory,
+     * or the declared write tail in its place. Undefined for a read-only sandbox —
+     * no writable mount exists; the WorkingDir falls back to the read-only tree
+     * root.
      */
     writableStepPath?: string;
-    /** Container WorkingDir: the writable step path, or the RO tree root in
+    /** Container WorkingDir: the writable mount, or the RO tree root in
      *  read-only mode. */
     workingDir: string;
     /** Container path of the lib store, present only when `libs`. */
     libsPath?: string;
     /** Container path of the ref store, present only when `refs`. */
     refsPath?: string;
-    /** Pre-created subdirectories under the writable step path. Empty when
-     *  read-only (nothing to pre-create). */
+    /** Pre-created subdirectories under the writable mount. Empty when read-only
+     *  (nothing to pre-create) and when a declared tail replaces the step tail. */
     stepSubdirs: readonly string[];
     /** Env merged into the sandbox container: provenance + lib-store vars. */
     env: Record<string, string>;
@@ -67,9 +87,27 @@ export interface MountPlan {
 export interface SessionSubPaths {
     /** Read-only mount of the whole analysis tree. */
     readonly ro: string;
-    /** Read-write mount of the step's artifact dir; absent when read-only. */
+    /** Read-write mount of the step's artifact dir, or of the declared tail; absent when read-only. */
     readonly rw?: string;
 }
+/** The one writable mount of a sandbox: its workspace-relative tail, and what the host pre-makes under it. */
+export interface SandboxWriteTail {
+    /** The tail beneath the workspace root, in both container and PVC-relative space. */
+    readonly tail: string;
+    /** The subdirectories the host pre-creates under the tail. A declared tail is one directory, thus none. */
+    readonly subdirs: readonly string[];
+}
+/**
+ * The write tail of a sandbox, or `undefined` when the sandbox holds no write mount.
+ *
+ * The one owner of the rule, read by the container path, the PVC subPath, and the
+ * host-side preparation alike. Thus the directory the harness makes and the
+ * directory the sandbox mounts are provably the same one.
+ *
+ * `readOnly` beside a declared tail states two opposite things about one mount, thus
+ * it throws rather than picking a winner.
+ */
+export declare function sandboxWriteTail(coords: MountPlanCoords): SandboxWriteTail | undefined;
 /**
  * K8s `subPath`s for the session-PVC mounts.
  *

package/dist/sandbox/mount-plan.js

@@ -10,13 +10,24 @@
  * artifacts, lib store read-only at `/mnt/libs`, ref store read-only at
  * `/mnt/refs`.
  *
+ * A caller can declare its own `writableTail` in place of the step tail — a
+ * workspace-relative path that becomes the one read-write mount, with no step
+ * subdirectories under it. The session derivation declares one; the run path
+ * declares none and keeps the step tail. Thus a sandbox writes into the step
+ * directory or into the one declared tail, and nowhere else.
+ *
+ * The precedence is a refusal, not an order: `readOnly` and `writableTail` state
+ * opposite things about the same mount, thus a coordinate set that carries both
+ * throws here — the same as a crafted id. No caller can hold both and get a
+ * silently chosen winner.
+ *
  * Container paths are a function of `resourceId` alone — they never carry the
  * host location of the tree. Where that tree physically lives is the embedder's
  * (`resolveWorkspaceRoot`); the two are reconciled per backend: Docker binds the
  * resolved root directly, K8s addresses it as a `subPath` into the session PVC
  * (see {@link buildSessionSubPaths}).
  */
-import { assertSafeId } from "../workspace/paths.js";
+import { assertSafeId, assertSafeTail } from "../workspace/paths.js";
 export const STEP_SUBDIRS = ["output", "scripts", "figures", "logs", "notebooks"];
 /**
  * Container mountpoints of the two read-only stores. Exported because they are
@@ -37,6 +48,31 @@ function stepTail(runId, stepId) {
     assertSafeId(stepId, "stepId");
     return `runs/${runId}/${stepId}`;
 }
+/**
+ * The write tail of a sandbox, or `undefined` when the sandbox holds no write mount.
+ *
+ * The one owner of the rule, read by the container path, the PVC subPath, and the
+ * host-side preparation alike. Thus the directory the harness makes and the
+ * directory the sandbox mounts are provably the same one.
+ *
+ * `readOnly` beside a declared tail states two opposite things about one mount, thus
+ * it throws rather than picking a winner.
+ */
+export function sandboxWriteTail(coords) {
+    // The two ids reach the sandbox name, the ownership labels, and the registry row on every path, not the
+    // step tail alone. Thus they take their validation before any branch, and a crafted id is refused even
+    // where no step directory is built.
+    assertSafeId(coords.runId, "runId");
+    assertSafeId(coords.stepId, "stepId");
+    if (coords.writableTail === undefined) {
+        return coords.readOnly ? undefined : { tail: stepTail(coords.runId, coords.stepId), subdirs: STEP_SUBDIRS };
+    }
+    if (coords.readOnly) {
+        throw new Error(`sandbox mount: a read-only sandbox cannot declare a write tail (got ${coords.writableTail})`);
+    }
+    // The segments come back validated, thus the join below re-splits nothing.
+    return { tail: assertSafeTail(coords.writableTail).join("/"), subdirs: [] };
+}
 /**
  * K8s `subPath`s for the session-PVC mounts.
  *
@@ -51,9 +87,10 @@ export function buildSessionSubPaths(coords, workspaceSubPath) {
     if (workspaceSubPath.length === 0 || workspaceSubPath.startsWith("/") || workspaceSubPath.split("/").includes("..")) {
         throw new Error(`buildSessionSubPaths: workspaceSubPath must be a non-empty PVC-root-relative path without '..' (got ${JSON.stringify(workspaceSubPath)})`);
     }
+    const write = sandboxWriteTail(coords);
     return {
         ro: workspaceSubPath,
-        rw: coords.readOnly ? undefined : `${workspaceSubPath}/${stepTail(coords.runId, coords.stepId)}`,
+        ...(write === undefined ? {} : { rw: `${workspaceSubPath}/${write.tail}` }),
     };
 }
 /**
@@ -68,19 +105,20 @@ function libStoreEnv() {
     };
 }
 export function buildMountPlan(coords, stores) {
-    const { analysisId, runId, stepId, readOnly } = coords;
+    const { analysisId } = coords;
     // `analysisId` becomes the RO mount point `/{analysisId}` even in read-only
     // mode (where `stepTail` — which validates runId/stepId — is not reached).
     assertSafeId(analysisId, "analysisId");
     const readonlyTreePath = `/${analysisId}`;
-    const writableStepPath = readOnly ? undefined : `${readonlyTreePath}/${stepTail(runId, stepId)}`;
+    const write = sandboxWriteTail(coords);
+    const writableStepPath = write === undefined ? undefined : `${readonlyTreePath}/${write.tail}`;
     return {
         readonlyTreePath,
         writableStepPath,
         workingDir: writableStepPath ?? readonlyTreePath,
         libsPath: stores.libs ? LIBS_CONTAINER_PATH : undefined,
         refsPath: stores.refs ? REFS_CONTAINER_PATH : undefined,
-        stepSubdirs: readOnly ? [] : STEP_SUBDIRS,
+        stepSubdirs: write?.subdirs ?? [],
         env: {
             PROVENANCE_WATCH_DIRS: readonlyTreePath,
             ...(stores.libs ? libStoreEnv() : {}),

package/dist/sandbox/types.d.ts

@@ -243,6 +243,12 @@ export interface CreateSandboxMeta {
     /** Enforced read-only: provision with no read-write step mount, only the
      *  read-only analysis tree for generic read-only agents. */
     readOnly?: boolean;
+    /** Workspace-relative path that becomes the one read-write mount, in place of
+     *  the step directory and with no step subdirectories under it. Each segment
+     *  passes the safe-id discipline of the step builder. Absent keeps the step
+     *  mount, thus a run provisions exactly as before. A tail beside `readOnly` is
+     *  a contradiction, and the mount builders refuse it. */
+    writableTail?: string;
     /** Host-supplied labels stamped onto the sandbox pod, verbatim. Opaque here:
      *  the harness reads no key and no value, it only sanitizes each value into a
      *  valid label. Absent ⇒ the pod carries the harness's own labels only. */

package/dist/state/init.js

@@ -129,15 +129,15 @@ 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.
+-- Report versions — one 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. A record on a
+-- thread that holds a version replaces that row whole, under the same version_id
+-- and the same created_at. 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.
 CREATE TABLE IF NOT EXISTS cortex_report_versions (
   version_id        TEXT PRIMARY KEY,
   analysis_id       TEXT NOT NULL
@@ -176,6 +176,13 @@ CREATE INDEX IF NOT EXISTS idx_cortex_report_versions_analysis
 -- 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.
+--
+-- The derivations column holds the derivation list of the session. One record
+-- carries the derived output path, the output hash, the source paths with their
+-- hashes, the script hash, and the script text. The column is nullable, because a
+-- session that derived nothing holds no list, and the read gives an empty list for
+-- such a row. The served membership merges the records onto the pin, and the pin
+-- itself never changes.
 CREATE TABLE IF NOT EXISTS cortex_report_session_state (
   thread_id              TEXT PRIMARY KEY,
   analysis_id            TEXT NOT NULL
@@ -183,6 +190,7 @@ CREATE TABLE IF NOT EXISTS cortex_report_session_state (
                            ON DELETE CASCADE,
   document               JSONB,
   snapshot               JSONB,
+  derivations            JSONB,
   rendered_document_hash TEXT,
   seen_document_hash     TEXT,
   created_at             TIMESTAMPTZ NOT NULL DEFAULT NOW()
@@ -310,6 +318,17 @@ CREATE INDEX IF NOT EXISTS idx_cortex_regulatory_chunks_metadata
 -- forces JSON on the envelope is about model content that is re-sent to the
 -- provider. This record is harness-generated, has a fixed field set, and never
 -- reaches a prompt, so it does not share that requirement.
+--
+-- turn_duration_ms holds the time that a whole turn took, in milliseconds, on
+-- the same row as reported_usage. It is a column of its own, and not a member of
+-- the rollup. The rollup is absent when a provider reported no quantity, and the
+-- host measures the duration apart from the token counts. Thus a member of the
+-- rollup would disappear with it. BIGINT, as cortex_step_executions.duration_ms
+-- is, because an int4 duration overflowed there.
+--
+-- Nullable with no default: absent means that nobody measured the turn, and a
+-- zero would claim that a turn took no time. A row written before this column
+-- existed is absent for the same reason, thus the migration needs no backfill.
 CREATE TABLE IF NOT EXISTS messages (
   thread_id     TEXT NOT NULL,
   seq           BIGINT NOT NULL,
@@ -321,6 +340,7 @@ CREATE TABLE IF NOT EXISTS messages (
   display_envelope JSONB,
   tokens        INTEGER NOT NULL,
   reported_usage JSONB,
+  turn_duration_ms BIGINT,
   created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   PRIMARY KEY (thread_id, seq)
 );
@@ -565,6 +585,10 @@ export async function initCortexState(pool, injected) {
                 // 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",
+                // The derivation list of a report session. Nullable and unbackfilled: a
+                // session that derived nothing holds no list, and the read gives an empty
+                // list for such a row.
+                "ALTER TABLE cortex_report_session_state ADD COLUMN IF NOT EXISTS derivations JSONB",
                 // 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.
@@ -575,6 +599,11 @@ export async function initCortexState(pool, injected) {
                 // row and every pre-existing message reads back with no rollup — which
                 // is the honest value, the figures having never been recorded.
                 "ALTER TABLE messages ADD COLUMN IF NOT EXISTS reported_usage JSONB",
+                // The turn's measured duration (see the CREATE TABLE comment). Purely
+                // additive: nullable with no default, thus the column rewrites no row,
+                // and every earlier message reads back with no duration — which is the
+                // honest value, because nobody measured those turns.
+                "ALTER TABLE messages ADD COLUMN IF NOT EXISTS turn_duration_ms BIGINT",
                 // Demote an existing JSONB envelope column to JSON (see the CREATE
                 // TABLE comment). Type-guarded because ALTER ... TYPE rewrites the
                 // whole table and this runs at every boot; scoped to

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

@@ -21,6 +21,12 @@
  * 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.
  *
+ * The row also holds the derivation list of the session. One record chains a derived
+ * table to the evidence that made it: the output path, the output hash, the source
+ * paths with their hashes, the script hash, and the script text. A record is
+ * immutable, and the append refuses a repeated output path. A row that holds no list
+ * reads as an empty list.
+ *
  * 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.
@@ -34,6 +40,33 @@ 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";
+/** One source of a derivation: the pinned path that the script read, and the hash of that path. */
+export interface DerivationSource {
+    readonly path: string;
+    readonly hash: string;
+}
+/**
+ * One derivation of a session.
+ *
+ * The record chains the derived table to the evidence that made it, thus a verifier mounts the same
+ * sources, runs the same script, and compares the output hash. The script text rides the record, thus the
+ * verifier needs no second store.
+ *
+ * `outputPath` is the workspace-root-relative path of the derived file, and it is the key that the served
+ * membership holds. A record is immutable, thus a new derivation takes a new output path.
+ */
+export interface DerivationRecord {
+    readonly outputPath: string;
+    readonly outputHash: string;
+    readonly sources: readonly DerivationSource[];
+    readonly scriptHash: string;
+    readonly script: string;
+}
+/**
+ * The outcome of an append. `appended` landed the record. `duplicate` means that a record already holds the
+ * output path, thus the list stays as it is. `absent` means that no row holds the thread.
+ */
+export type AppendDerivationOutcome = "appended" | "duplicate" | "absent";
 /** The state of one report session, as the store gives it back. */
 export interface ReportSessionState {
     readonly threadId: string;
@@ -42,6 +75,8 @@ export interface ReportSessionState {
     readonly document: DraftDocument | null;
     /** The pinned snapshot, or `null` before the pin writes it. */
     readonly snapshot: ReportSnapshot | null;
+    /** The derivations of the session, in the order that they landed. A row with no list reads as empty. */
+    readonly derivations: readonly DerivationRecord[];
     /** 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. */
@@ -92,7 +127,7 @@ export type SessionStateReadError = {
     readonly type: "corrupt_session_state";
     readonly op: string;
     readonly threadId: string;
-    readonly part: "document" | "snapshot";
+    readonly part: "document" | "snapshot" | "derivations";
     readonly issues: readonly SchemaIssue[];
 };
 export interface ReportSessionStateStore {
@@ -127,6 +162,12 @@ export interface ReportSessionStateStore {
      * one. `absent` means that no row holds the thread.
      */
     stampSeen(threadId: string): ResultAsync<SeenStampOutcome, DbError>;
+    /**
+     * Append one derivation record to the list of a thread. The output path is unique across the list,
+     * thus a repeated path refuses with `duplicate` and the stored list stays as it is. `absent` means
+     * that no row holds the thread.
+     */
+    appendDerivation(threadId: string, record: DerivationRecord): ResultAsync<AppendDerivationOutcome, DbError>;
 }
 export interface ReportSessionStateStoreDeps {
     readonly pool: Pool;

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

@@ -21,6 +21,12 @@
  * 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.
  *
+ * The row also holds the derivation list of the session. One record chains a derived
+ * table to the evidence that made it: the output path, the output hash, the source
+ * paths with their hashes, the script hash, and the script text. A record is
+ * immutable, and the append refuses a repeated output path. A row that holds no list
+ * reads as an empty list.
+ *
  * 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.
@@ -28,12 +34,22 @@
  * A purge of the analysis removes the row through the analysis-id cascade.
  */
 import { err, ok } from "neverthrow";
+import { z } from "zod";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
 import { DraftDocumentSchema } from "../report-model/draft.js";
 import { parseSnapshot, reduceIssues } from "./snapshot-parse.js";
+const DerivationSourceSchema = z.object({ path: z.string(), hash: z.string() });
+const DerivationRecordSchema = z.object({
+    outputPath: z.string(),
+    outputHash: z.string(),
+    sources: z.array(DerivationSourceSchema),
+    scriptHash: z.string(),
+    script: z.string(),
+});
+const DerivationListSchema = z.array(DerivationRecordSchema);
 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";
+const STATE_COLUMNS = "thread_id, analysis_id, document, snapshot, derivations, 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
@@ -72,11 +88,28 @@ function rowToState(row) {
         }
         snapshot = parsed.value;
     }
+    // A row that predates the list carries SQL NULL, and a session that derived nothing carries none
+    // either. Both read as an empty list, because a session with no derivation has none.
+    let derivations = [];
+    if (row.derivations !== null && row.derivations !== undefined) {
+        const parsed = DerivationListSchema.safeParse(row.derivations);
+        if (!parsed.success) {
+            return err({
+                type: "corrupt_session_state",
+                op: "report-session-state.read",
+                threadId: row.thread_id,
+                part: "derivations",
+                issues: reduceIssues(parsed.error),
+            });
+        }
+        derivations = parsed.data;
+    }
     return ok({
         threadId: row.thread_id,
         analysisId: row.analysis_id,
         document,
         snapshot,
+        derivations,
         renderedDocumentHash: row.rendered_document_hash,
         seenDocumentHash: row.seen_document_hash,
         createdAt: row.created_at,
@@ -173,5 +206,40 @@ export function createReportSessionStateStore({ pool }) {
             return row.copied === null ? "no-rendered" : "stamped";
         });
     }
-    return { readState, writeSnapshot, persistDocument, stampRendered, stampSeen };
+    function appendDerivation(threadId, record) {
+        return tryMutation("report-session-state.appendDerivation", async () => {
+            // One statement tells a duplicate from an absence, the same way the persist does. `existed`
+            // counts the row, and `appended` counts the update.
+            //
+            // The name rule sits in the qualification of the UPDATE, over the row that the statement locks.
+            // A read of the CTE would test the list as it stood at the start of the statement: two
+            // concurrent appends of one name would each pass that test, and both would land. Postgres
+            // re-evaluates the qualification of an UPDATE against the row that it waited for, thus the
+            // loser of the race sees the list of the winner and it appends nothing.
+            const { rows } = await pool.query({
+                text: `WITH target AS (
+    SELECT thread_id
+      FROM cortex_report_session_state
+     WHERE thread_id = $1
+  ), appended AS (
+    UPDATE cortex_report_session_state AS s
+       SET derivations = COALESCE(s.derivations, '[]'::jsonb) || $2::jsonb
+     WHERE s.thread_id = $1
+       AND NOT EXISTS (
+         SELECT 1 FROM jsonb_array_elements(COALESCE(s.derivations, '[]'::jsonb)) AS held WHERE held->>'outputPath' = $3
+       )
+    RETURNING 1
+  )
+  SELECT (SELECT COUNT(*) FROM target)::int AS existed, (SELECT COUNT(*) FROM appended)::int AS appended`,
+                // The record rides as a one-element array, thus the `||` operator appends one element and
+                // never merges the fields of an object into the list.
+                values: [threadId, JSON.stringify([record]), record.outputPath],
+            });
+            const row = rows[0];
+            if (row === undefined || row.existed === 0)
+                return "absent";
+            return row.appended > 0 ? "appended" : "duplicate";
+        });
+    }
+    return { readState, writeSnapshot, persistDocument, stampRendered, stampSeen, appendDerivation };
 }