@inflexa-ai/harness 0.19.0 → 0.19.1

package/dist/report-model/reference-resolver.d.ts

@@ -71,9 +71,15 @@ export type ResolvedValue = {
  * The `Ok` channel carries the resolved value. The `Err` channel carries the `UnresolvedReference`,
  * which names the reason and the detail that a reference did not bind. The validator collects each such
  * `Err` into its report, thus a caller reads the reason as data and resolution never throws.
+ *
+ * `prepare` is an optional batch step that runs one time before the per-reference loop. A realization
+ * that reads storage groups the references by artifact, reads each file one time, and fills a cache.
+ * `resolve` then answers from the cache. The method is optional, thus a realization without it keeps the
+ * per-reference behavior and the extension breaks no caller.
  */
 export interface ReferenceResolver {
     resolve(reference: Reference, snapshot: ReportSnapshot): Promise<Result<ResolvedValue, UnresolvedReference>>;
+    prepare?(references: readonly Reference[], snapshot: ReportSnapshot): Promise<void>;
 }
 /**
  * Give back each name in `columns` that no row holds, in the order of `columns`.

package/dist/report-model/validate.js

@@ -54,6 +54,11 @@ export function checkChartEncoding(entry, value) {
  */
 export async function resolveDocumentReferences(sections, snapshot, resolver) {
     const { references } = walkBlocks(sections);
+    // A realization that reads storage batches its reads here, one time before the loop. It fills a cache
+    // that each `resolve` then answers from. A realization without `prepare` keeps the per-reference read.
+    if (resolver.prepare !== undefined) {
+        await resolver.prepare(references.map((entry) => entry.reference), snapshot);
+    }
     const resolved = await allWithConcurrency(references.map((entry) => () => resolver.resolve(entry.reference, snapshot).then((result) => ({ entry, result }))), RESOLUTION_CONCURRENCY);
     const failures = [];
     const resolvedByBlock = new Map();

package/dist/report-render/page.d.ts

@@ -118,10 +118,33 @@ export declare const ECHARTS_THEME: {
         };
     };
 };
+/**
+ * The name of the readiness event, and the name of the window sentinel that guards a late listener. The
+ * bootstrap below emits both names, thus this module owns them. A capture that waits for the page reads the
+ * same two constants, thus the emitter and the waiter cannot disagree over a rename.
+ */
+export declare const THEME_READY_EVENT = "inflexa-theme-ready";
+export declare const THEME_READY_SENTINEL = "__inflexaThemeReady";
+/**
+ * The navigation budget and the readiness budget of one page capture, in milliseconds. The readiness budget
+ * bounds the wait for the event that the bootstrap dispatches. Every capture of this page reads the same two
+ * budgets, thus two capture sites cannot drift apart.
+ */
+export declare const PAGE_NAV_TIMEOUT_MS = 20000;
+export declare const PAGE_READY_TIMEOUT_MS = 8000;
 /**
  * The page-side script that wires each chart. It finds every chart container, reads the option JSON from
  * the sibling `<script type="application/json">` element, and initializes ECharts with the registered
  * theme. The skeleton registers the theme before this script runs. A resize handler keeps each chart
  * fit to the window.
+ *
+ * The script signals readiness when the bootstrap completes, and immediately when no chart exists. It sets
+ * the `window.__inflexaThemeReady` sentinel and dispatches the `inflexa-theme-ready` event on the document.
+ * A reader that captures the page keys on this signal, thus the capture returns when the page is ready and
+ * not at a timeout. The sentinel guards a listener that registers after the dispatch, thus a late listener
+ * still resolves.
+ *
+ * Each chart initializes inside a guard. One malformed option is exactly the fault that a look must
+ * diagnose, thus it must never stop a sibling chart and it must never withhold the readiness signal.
  */
 export declare const CHART_BOOTSTRAP: string;

package/dist/report-render/page.js

@@ -274,14 +274,42 @@ export const ECHARTS_THEME = {
         splitLine: { lineStyle: { color: "#f1f5f9", type: "dashed" } },
     },
 };
+/**
+ * The name of the readiness event, and the name of the window sentinel that guards a late listener. The
+ * bootstrap below emits both names, thus this module owns them. A capture that waits for the page reads the
+ * same two constants, thus the emitter and the waiter cannot disagree over a rename.
+ */
+export const THEME_READY_EVENT = "inflexa-theme-ready";
+export const THEME_READY_SENTINEL = "__inflexaThemeReady";
+/**
+ * The navigation budget and the readiness budget of one page capture, in milliseconds. The readiness budget
+ * bounds the wait for the event that the bootstrap dispatches. Every capture of this page reads the same two
+ * budgets, thus two capture sites cannot drift apart.
+ */
+export const PAGE_NAV_TIMEOUT_MS = 20_000;
+export const PAGE_READY_TIMEOUT_MS = 8_000;
 /**
  * The page-side script that wires each chart. It finds every chart container, reads the option JSON from
  * the sibling `<script type="application/json">` element, and initializes ECharts with the registered
  * theme. The skeleton registers the theme before this script runs. A resize handler keeps each chart
  * fit to the window.
+ *
+ * The script signals readiness when the bootstrap completes, and immediately when no chart exists. It sets
+ * the `window.__inflexaThemeReady` sentinel and dispatches the `inflexa-theme-ready` event on the document.
+ * A reader that captures the page keys on this signal, thus the capture returns when the page is ready and
+ * not at a timeout. The sentinel guards a listener that registers after the dispatch, thus a late listener
+ * still resolves.
+ *
+ * Each chart initializes inside a guard. One malformed option is exactly the fault that a look must
+ * diagnose, thus it must never stop a sibling chart and it must never withhold the readiness signal.
  */
 export const CHART_BOOTSTRAP = `(function () {
+  function signalReady() {
+    window.${THEME_READY_SENTINEL} = true;
+    document.dispatchEvent(new Event(${JSON.stringify(THEME_READY_EVENT)}));
+  }
   if (typeof echarts === "undefined") {
+    signalReady();
     return;
   }
   var containers = document.querySelectorAll("[data-echarts-id]");
@@ -291,9 +319,13 @@ export const CHART_BOOTSTRAP = `(function () {
     if (!optionScript || optionScript.getAttribute("type") !== "application/json") {
       continue;
     }
-    var option = JSON.parse(optionScript.textContent || "{}");
-    var chart = echarts.init(container, ${JSON.stringify(ECHARTS_THEME_NAME)});
-    chart.setOption(option);
+    try {
+      var option = JSON.parse(optionScript.textContent || "{}");
+      var chart = echarts.init(container, ${JSON.stringify(ECHARTS_THEME_NAME)});
+      chart.setOption(option);
+    } catch (cause) {
+      console.error("chart bootstrap failed for " + (container.getAttribute("data-echarts-id") || "(no id)") + ": " + (cause && cause.message ? cause.message : cause));
+    }
   }
   window.addEventListener("resize", function () {
     var nodes = document.querySelectorAll("[data-echarts-id]");
@@ -304,4 +336,5 @@ export const CHART_BOOTSTRAP = `(function () {
       }
     }
   });
+  signalReady();
 })();`;

package/dist/runtime/assemble.d.ts

@@ -25,8 +25,10 @@ import { type ExecuteAnalysisDeps, type ExecuteAnalysisInput, type ExecuteAnalys
 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 ExtractValuesResult, type ExtractValuesWorkflowInput } from "../tasks/extract-values.js";
 import { type CitationResolverConfig } from "../citations/resolve.js";
 import type { CitationResolver } from "../citations/types.js";
+import type { AuthContext } from "../auth/types.js";
 import type { ReferenceResolver } from "../report-model/reference-resolver.js";
 /** Registered child sandbox-step callable the parent's child dispatch closes over. */
 export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxStepResult>;
@@ -55,6 +57,7 @@ export interface RegisteredWorkflows {
     readonly sandboxStep: SandboxStepCallable;
     readonly executeTargetAssessment: (input: ExecuteTargetAssessmentInput) => Promise<ExecuteTargetAssessmentResult>;
     readonly dataProfile: (input: DataProfileWorkflowInput) => Promise<void>;
+    readonly extractValues: (input: ExtractValuesWorkflowInput) => Promise<ExtractValuesResult>;
 }
 /**
  * Conversation-agent deps minus the workflow callable, the resource policy, and
@@ -63,6 +66,19 @@ export interface RegisteredWorkflows {
  * workflows see, or a recorder that only half the agent tree reports to.
  */
 export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder" | "citationResolver">;
+/**
+ * What binds one reference resolver: the analysis whose pinned artifacts it reads, and the auth of the tool
+ * call that reads them. A resolver serves one analysis, thus the report tools build one for each call.
+ */
+export interface ReportResolverScope {
+    readonly analysisId: string;
+    readonly auth: AuthContext;
+}
+/**
+ * The factory that gives the reference resolver of one report tool call. The harness wires the production
+ * realization, and an embedder can bind its own at its composition root.
+ */
+export type MakeReportReferenceResolver = (scope: ReportResolverScope) => ReferenceResolver;
 export interface CoreRuntimeDeps {
     readonly conversation: ConversationAssemblyDeps;
     readonly workflows: CoreWorkflowDeps;
@@ -81,11 +97,19 @@ export interface CoreRuntimeDeps {
     /** Harness-owned citation capability configuration; no ambient lookup occurs. */
     readonly citationResolverConfig?: CitationResolverConfig;
     /**
-     * Reference-resolution seam for the report preview. Absent by default, thus the
-     * preview tool degrades as data until an embedder wires a realization. The
-     * realization itself stays out of the harness.
+     * The byte cap on the in-process host read of a report reference. A file over the
+     * cap falls through to the extraction arm. Absent, the resolver uses its 16 MiB
+     * default. The embedder tunes it here, thus a host changes it with no harness change.
+     */
+    readonly reportHostReadCapBytes?: number;
+    /**
+     * The report reference resolver of an embedder. A managed host reads its pinned
+     * artifacts from its own store, thus it binds a realization of the seam here and the
+     * report tools resolve through it. Absent, the harness wires the production resolver
+     * over the workspace tree and the extraction arm, which is the whole OSS path. A bound
+     * factory replaces that wiring, thus `reportHostReadCapBytes` then governs nothing.
      */
-    readonly reportReferenceResolver?: ReferenceResolver;
+    readonly makeReportReferenceResolver?: MakeReportReferenceResolver;
 }
 /**
  * The refusal a thread type carries no agent yet. `report` is a valid

package/dist/runtime/assemble.js

@@ -23,7 +23,11 @@ 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 { bindExtractionTrigger, createExtractionArm, registerExtractValuesWorkflow, } from "../tasks/extract-values.js";
 import { createCitationResolver } from "../citations/resolve.js";
+import { createThreadStore } from "../memory/thread-store.js";
+import { createArtifactReadStore, createProductionResolver } from "../report-model/production-resolver.js";
+import { createReportVersionStore } from "../state/report-versions.js";
 const _assertDomainError = true;
 /**
  * Wrap a type→agent registry as the resolution surface. Held apart from
@@ -62,6 +66,14 @@ export function assembleCoreRuntime(deps) {
     const executeAnalysis = registerExecuteAnalysis({ ...wf.buildExecuteAnalysis(sandboxStep), citationResolver, usageRecorder });
     const executeTargetAssessment = registerExecuteTargetAssessment({ ...wf.executeTargetAssessment, usageRecorder });
     const dataProfile = registerDataProfileWorkflow({ ...wf.dataProfile, usageRecorder });
+    // The extraction workflow shares the profile's sandbox and authorization rails, thus it draws the same
+    // three seams from the profile deps. The report resolver factory binds the extraction arm over this
+    // callable, thus a fall-through report reference reads its file out of process on the profile rails.
+    const extractValues = registerExtractValuesWorkflow({
+        sandboxClient: wf.dataProfile.sandboxClient,
+        runAuthorizer: wf.dataProfile.runAuthorizer,
+        ...(wf.dataProfile.logger ? { logger: wf.dataProfile.logger } : {}),
+    });
     const conversationAgent = createConversationAgent({
         ...conversation,
         executeAnalysisWorkflow: executeAnalysis,
@@ -73,9 +85,32 @@ export function assembleCoreRuntime(deps) {
     // runtime binds the per-session state to the thread behind the tool boundary,
     // thus one definition serves every report thread. Its preview tool writes the
     // page into the analysis tree and returns the path, thus the page write reaches
-    // no host seam. The optional reference resolver is the one seam it can use, and
-    // it is absent by default.
+    // no host seam.
     const reportSession = createReportSessionRuntime({ pool: conversation.pool, ...(conversation.logger ? { logger: conversation.logger } : {}) });
+    const reportVersionStore = createReportVersionStore({ pool: conversation.pool, ...(conversation.logger ? { logger: conversation.logger } : {}) });
+    const reportThreads = createThreadStore(conversation.pool);
+    // The read cache of the production report path, one for each recent analysis. A preview
+    // and the record that follows it are two tool calls over one draft, thus they meet the
+    // same artifacts. The store carries the streamed hash and the extracted rows between
+    // them, and each resolver still binds its own extraction arm below. Thus the auth of a
+    // call never outlives the call, and one unchanged file costs one hash and one container.
+    const reportArtifactReads = createArtifactReadStore();
+    // The reference resolver of the report path, and its production wiring. A resolver reads
+    // the pinned artifacts of one analysis, thus the factory binds one analysis and one auth
+    // for each tool call. The extraction arm falls through to the registered extract-values
+    // callable for an over-cap file or a host parse fault. The cap gates the host read, and
+    // the resolver defaults it to 16 MiB.
+    const makeProductionReportResolver = (scope) => {
+        const arm = createExtractionArm(bindExtractionTrigger({ runAuthorizer: conversation.runAuthorizer, workflow: extractValues }, { auth: scope.auth, analysisId: scope.analysisId }));
+        return createProductionResolver({
+            workspaceRoot: conversation.resolveWorkspaceRoot(scope.analysisId),
+            analysisId: scope.analysisId,
+            extractionArm: arm,
+            readCache: reportArtifactReads.forAnalysis(scope.analysisId),
+            ...(deps.reportHostReadCapBytes !== undefined ? { cap: deps.reportHostReadCapBytes } : {}),
+        });
+    };
+    const makeReportResolver = deps.makeReportReferenceResolver ?? makeProductionReportResolver;
     const reportAgent = createReportSessionAgent({
         model: conversation.model,
         pool: conversation.pool,
@@ -83,7 +118,10 @@ export function assembleCoreRuntime(deps) {
         workspaceFs: conversation.workspaceFs,
         gateway: reportSession.gateway,
         resolveWorkspaceRoot: conversation.resolveWorkspaceRoot,
-        ...(deps.reportReferenceResolver ? { resolver: deps.reportReferenceResolver } : {}),
+        store: reportVersionStore,
+        threads: reportThreads,
+        chrome: conversation.chrome,
+        makeResolver: makeReportResolver,
         ...(conversation.logger ? { logger: conversation.logger } : {}),
     });
     // The single registration point for every typed agent. A future thread type's
@@ -105,6 +143,7 @@ export function assembleCoreRuntime(deps) {
             sandboxStep,
             executeTargetAssessment,
             dataProfile,
+            extractValues,
         },
         citationResolver,
     };

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

@@ -17,6 +17,13 @@
  * (see {@link buildSessionSubPaths}).
  */
 export declare const STEP_SUBDIRS: readonly ["output", "scripts", "figures", "logs", "notebooks"];
+/**
+ * Container mountpoints of the two read-only stores. Exported because they are
+ * also the discovery tools' default read root: a host whose own process sees a
+ * store the way the sandbox does configures nothing further.
+ */
+export declare const LIBS_CONTAINER_PATH = "/mnt/libs";
+export declare const REFS_CONTAINER_PATH = "/mnt/refs";
 export interface MountPlanCoords {
     analysisId: string;
     runId: string;

package/dist/sandbox/mount-plan.js

@@ -18,8 +18,13 @@
  */
 import { assertSafeId } from "../workspace/paths.js";
 export const STEP_SUBDIRS = ["output", "scripts", "figures", "logs", "notebooks"];
-const LIBS_CONTAINER_PATH = "/mnt/libs";
-const REFS_CONTAINER_PATH = "/mnt/refs";
+/**
+ * Container mountpoints of the two read-only stores. Exported because they are
+ * also the discovery tools' default read root: a host whose own process sees a
+ * store the way the sandbox does configures nothing further.
+ */
+export const LIBS_CONTAINER_PATH = "/mnt/libs";
+export const REFS_CONTAINER_PATH = "/mnt/refs";
 /**
  * The step tail beneath an analysis's workspace root, in both container and
  * PVC-relative space. The harness owns this layout (workspace-layout spec).

package/dist/state/init.js

@@ -171,14 +171,22 @@ CREATE INDEX IF NOT EXISTS idx_cortex_report_versions_analysis
 -- 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,
-  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  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
@@ -552,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/report-session-state.d.ts

@@ -42,6 +42,10 @@ export interface ReportSessionState {
     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. */
@@ -69,6 +73,17 @@ export interface PersistDocumentInput {
  * 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.
@@ -100,6 +115,18 @@ export interface ReportSessionStateStore {
      * 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;

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

@@ -33,7 +33,7 @@ import { DraftDocumentSchema } from "../report-model/draft.js";
 import { parseSnapshot, reduceIssues } from "./snapshot-parse.js";
 const _assertReadError = true;
 /** The full row projection every read shares. */
-const STATE_COLUMNS = "thread_id, analysis_id, document, snapshot, created_at";
+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
@@ -77,6 +77,8 @@ function rowToState(row) {
         analysisId: row.analysis_id,
         document,
         snapshot,
+        renderedDocumentHash: row.rendered_document_hash,
+        seenDocumentHash: row.seen_document_hash,
         createdAt: row.created_at,
     });
 }
@@ -146,5 +148,30 @@ export function createReportSessionStateStore({ pool }) {
             return row.updated > 0 ? "persisted" : "conflict";
         });
     }
-    return { readState, writeSnapshot, persistDocument };
+    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/tasks/extract-values-script.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The fixed extraction script and its wire protocol.
+ *
+ * The extraction arm runs this one Python script in the sandbox. The script reads one JSON input: a list
+ * of path, format, and hash triples. For each triple the script hashes the file bytes with a streamed
+ * sha256 before any read. If the on-disk hash does not match the pinned hash, the script refuses the file
+ * as a typed error. If the hash matches, the script reads the file from the read-only analysis mount, and
+ * it parses the file by the carried format. A parquet file uses pyarrow. The script emits one JSON map:
+ * each path to its rows, or to a typed error. The script decides nothing else. It applies no filter and no
+ * projection.
+ *
+ * The host decides the format one time, and the request carries it. Thus the script derives no reader from
+ * an extension, and it refuses a request that names no format. The JSON arm obeys the strict host shape, an
+ * array of flat objects, thus a shape that the host refuses is a refusal here too and it never comes back
+ * as a table that pandas inferred.
+ *
+ * The harness holds the script as a string constant, thus the package ships no separate asset file. The
+ * script reaches the container as the argument of `python3 -c`. The input reaches the container as one
+ * environment variable.
+ */
+import { z } from "zod";
+/**
+ * The environment variable that carries the script input. The workflow body sets it to the JSON list of
+ * path, format, and hash triples. The script reads it back one time.
+ */
+export declare const EXTRACTION_INPUT_ENV = "CORTEX_EXTRACTION_REQUESTS";
+/**
+ * One artifact row, as plain cells. A text-backed format holds a numeric column as a string, thus a cell
+ * is a string or a number.
+ */
+declare const ExtractionRowSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+export type ExtractionRow = z.infer<typeof ExtractionRowSchema>;
+/**
+ * The outcome for one path. A clean read gives the rows. A per-file read fault gives a typed error, and
+ * the script still emits the map. The arm keeps the rows and drops the error, thus a failed path reads as
+ * an unread artifact downstream.
+ */
+declare const ExtractOutcomeSchema: z.ZodUnion<readonly [z.ZodObject<{
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+}, z.core.$strip>, z.ZodObject<{
+    error: z.ZodObject<{
+        type: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>]>;
+export type ExtractOutcome = z.infer<typeof ExtractOutcomeSchema>;
+/** The script output: each requested path to its outcome. */
+export declare const ExtractValuesResultSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+}, z.core.$strip>, z.ZodObject<{
+    error: z.ZodObject<{
+        type: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>]>>;
+export type ExtractValuesResult = z.infer<typeof ExtractValuesResultSchema>;
+/**
+ * The one extraction script. The workflow body runs it as the argument of `python3 -c`. The script reads
+ * the request list from `CORTEX_EXTRACTION_REQUESTS`, and it emits the value map to stdout.
+ *
+ * The Python comments obey the same Simplified Technical English rule as the harness comments.
+ */
+export declare const EXTRACTION_SCRIPT = "import hashlib\nimport json\nimport math\nimport os\nimport sys\n\nimport pandas as pd\n\n\ndef sha256_of(path):\n    # The host pins the exact bytes with a streamed sha256, in the \"sha256:<hex>\" form. Mirror that form\n    # here, and stream the file in blocks, thus a large file never loads fully into memory.\n    digest = hashlib.sha256()\n    with open(path, \"rb\") as handle:\n        for block in iter(lambda: handle.read(1024 * 1024), b\"\"):\n            digest.update(block)\n    return \"sha256:\" + digest.hexdigest()\n\n\ndef coerce_cell(value):\n    # A null cell becomes None, thus the record drops the key.\n    if value is None:\n        return None\n    # A numpy scalar becomes a plain Python scalar.\n    if hasattr(value, \"item\"):\n        try:\n            value = value.item()\n        except (ValueError, TypeError):\n            return str(value)\n    if isinstance(value, bool):\n        return \"true\" if value else \"false\"\n    if isinstance(value, float):\n        if math.isnan(value) or math.isinf(value):\n            return None\n        return value\n    if isinstance(value, int):\n        return value\n    if isinstance(value, str):\n        return value\n    return str(value)\n\n\ndef read_frame(path, fmt):\n    # pyarrow reads the parquet columnar format.\n    if fmt == \"parquet\":\n        return pd.read_parquet(path, engine=\"pyarrow\")\n    if fmt == \"tsv\":\n        # keep_default_na=False keeps a literal cell such as \"NA\" or an empty string as its text, and the\n        # host parser keeps it too. A default read turns each into NaN, and the row builder drops the key.\n        return pd.read_csv(path, sep=\"\\t\", dtype=str, keep_default_na=False)\n    if fmt == \"csv\":\n        # keep_default_na=False keeps a literal cell such as \"NA\" or an empty string as its text, thus a\n        # text cell survives and the row keeps the key.\n        return pd.read_csv(path, dtype=str, keep_default_na=False)\n    # The host decides the format for both arms. A request with no decided format is a protocol fault, thus\n    # the file refuses here and no reader guesses at it.\n    raise ValueError(\"the request names no supported format: \" + str(fmt))\n\n\ndef json_rows(path):\n    # The host reads a JSON table as an array of flat objects, and it refuses any other shape. Obey the\n    # same shape here. An inference pass would turn a shape that the host refuses into a different table.\n    with open(path, \"rb\") as handle:\n        value = json.load(handle)\n    if not isinstance(value, list):\n        raise ValueError(\"the JSON top-level value is not an array\")\n    rows = []\n    for item in value:\n        if not isinstance(item, dict):\n            raise ValueError(\"a JSON array item is not an object\")\n        row = {}\n        for key, cell in item.items():\n            if isinstance(cell, (dict, list)):\n                raise ValueError(\"a JSON cell holds a nested value\")\n            coerced = coerce_cell(cell)\n            if coerced is not None:\n                row[str(key)] = coerced\n        rows.append(row)\n    return rows\n\n\ndef rows_of(frame):\n    # A null cell becomes None before the record build, thus a missing cell drops.\n    clean = frame.astype(object).where(pd.notnull(frame), None)\n    records = clean.to_dict(orient=\"records\")\n    rows = []\n    for record in records:\n        row = {}\n        for key, value in record.items():\n            cell = coerce_cell(value)\n            if cell is not None:\n                row[str(key)] = cell\n        rows.append(row)\n    return rows\n\n\ndef rows_for(path, fmt):\n    # The JSON arm reads the strict host shape itself. Each other format reads through pandas.\n    if fmt == \"json\":\n        return json_rows(path)\n    return rows_of(read_frame(path, fmt))\n\n\ndef main():\n    raw = os.environ.get(\"CORTEX_EXTRACTION_REQUESTS\", \"[]\")\n    requests = json.loads(raw)\n    out = {}\n    for request in requests:\n        path = request[\"path\"]\n        fmt = request.get(\"format\")\n        expected = request[\"hash\"]\n        try:\n            # Hash the file before any read. A file that drifted from the pin never reaches the reader, thus\n            # the extraction never gives back drifted bytes for the gate to match against.\n            actual = sha256_of(path)\n            if actual != expected:\n                out[path] = {\n                    \"error\": {\n                        \"type\": \"hash-mismatch\",\n                        \"message\": f\"the pinned hash {expected} does not match the on-disk hash {actual}\",\n                    }\n                }\n                continue\n            out[path] = {\"rows\": rows_for(path, fmt)}\n        except Exception as exc:\n            # A per-file read fault lands as a typed error, and the map still holds each other path.\n            out[path] = {\"error\": {\"type\": \"read-fault\", \"message\": str(exc)}}\n    json.dump(out, sys.stdout)\n\n\nmain()\n";
+export {};