@inflexa-ai/harness 0.19.0 → 0.19.1

package/dist/providers/ai-sdk.js

@@ -1,5 +1,6 @@
 import { generateText, streamText, wrapLanguageModel, } from "ai";
 import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAI } from "@ai-sdk/openai";
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { APICallError } from "@ai-sdk/provider";
 import { retryWithExponentialBackoff } from "@ai-sdk/provider-utils";
@@ -28,6 +29,11 @@ export const RETRY_MAX_DELAY_MS = 30_000;
  *
  * Lower it per-config for servers that validate `prompt + max_tokens <= context`
  * (vLLM and similar) against a small-context model.
+ *
+ * The openai arm takes no value from this default. `@ai-sdk/openai` clamps
+ * nothing per model, and it puts the number on the wire as it is. Thus a model
+ * whose own cap is smaller answers 400 on each call. That arm sends no ceiling,
+ * and the server then enforces the true cap of the model.
  */
 export const DEFAULT_MAX_OUTPUT_TOKENS = 64_000;
 /**
@@ -370,9 +376,20 @@ function abortedStreamFailure(signal, reason, requestTimeoutMs) {
     return new Error(reason ?? "The provider aborted the stream.");
 }
 export function createAiSdkProvider(deps) {
-    const capabilities = { toolCalling: deps.capabilities?.toolCalling ?? true };
+    const capabilities = {
+        toolCalling: deps.capabilities?.toolCalling ?? true,
+        // Propagate a picture flag only when the caller states it. An absent
+        // flag stays absent, thus the loop degrades to the next placement for a
+        // wire that carries no picture there.
+        ...(deps.capabilities?.imageToolResults !== undefined ? { imageToolResults: deps.capabilities.imageToolResults } : {}),
+        ...(deps.capabilities?.imageUserMessages !== undefined ? { imageUserMessages: deps.capabilities.imageUserMessages } : {}),
+    };
     const logger = (deps.logger ?? createNoopLogger()).named("providers.ai-sdk");
     const maxOutputTokens = deps.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS;
+    // The sentinel hands the SDK no ceiling, thus the request carries none and the
+    // server enforces the cap of the model. One binding feeds the call and the
+    // stream, thus the two cannot disagree about the ceiling of a request.
+    const outputCeiling = maxOutputTokens === "provider-maximum" ? {} : { maxOutputTokens };
     const maxRetries = deps.maxRetries ?? RETRY_MAX_RETRIES;
     const requestTimeoutMs = deps.requestTimeoutMs;
     const requestedModelId = requestedModelIdOf(deps.model);
@@ -392,7 +409,7 @@ export function createAiSdkProvider(deps) {
                         messages: sanitizeMessages(req.messages),
                         tools: req.tools,
                         toolChoice: req.toolChoice ?? "auto",
-                        maxOutputTokens,
+                        ...outputCeiling,
                         stopWhen: [],
                         // The harness envelope owns retries; leaving the SDK default in
                         // place would multiply attempts (10 outer × 3 inner).
@@ -436,17 +453,19 @@ export function createAiSdkProvider(deps) {
                     messages: sanitizeMessages(req.messages),
                     tools: req.tools,
                     toolChoice: req.toolChoice ?? "auto",
-                    maxOutputTokens,
+                    ...outputCeiling,
                     stopWhen: [],
                     maxRetries: 0,
                     headers,
                     abortSignal: signal,
-                    // The SDK bounds each gap between two content chunks of the body.
-                    // Its timer arms at the first part of the provider stream, thus the
-                    // wait until the response starts stays with the fetch guard. A
-                    // chunk that carries no content, for example a keep-alive comment,
-                    // produces no part, thus it does not reset this bound.
-                    ...(requestTimeoutMs !== undefined ? { timeout: { chunkMs: requestTimeoutMs } } : {}),
+                    // The fetch guard bounds the wait until the headers. Past the
+                    // headers the SDK owns two bounds: `firstChunkMs` covers the wait
+                    // for the first content chunk, and `chunkMs` covers each later
+                    // gap. The two take the same value, thus each silent interval of
+                    // the stream has the one configured bound. A chunk that carries
+                    // no content, for example a keep-alive comment, produces no part,
+                    // thus it feeds neither bound.
+                    ...(requestTimeoutMs !== undefined ? { timeout: { firstChunkMs: requestTimeoutMs, chunkMs: requestTimeoutMs } } : {}),
                     providerOptions: req.providerOptions,
                 });
                 const iterator = result.fullStream[Symbol.asyncIterator]();
@@ -581,6 +600,28 @@ export function wrapFetchWithRequestTimeout(fetchImpl, requestTimeoutMs) {
         }
     };
 }
+/**
+ * Bind one explicit `store` directive onto each call of a model.
+ *
+ * The middleware merges the value into the `openai` namespace of
+ * `providerOptions`. It keeps each other namespace, and it keeps each other key
+ * of the `openai` namespace, thus a cache directive of a different vendor rides
+ * through untouched. The arm value wins over a request-level `store`, because
+ * the retention mode belongs to the connection and not to one turn. A thread
+ * that mixes the two modes replays a reference onto an item that the server
+ * never stored.
+ */
+function withStoreDirective(model, store) {
+    return wrapLanguageModel({
+        model,
+        middleware: {
+            transformParams: async ({ params }) => ({
+                ...params,
+                providerOptions: { ...params.providerOptions, openai: { ...params.providerOptions?.openai, store } },
+            }),
+        },
+    });
+}
 /**
  * Realize an `AiSdkProviderConfig` into a `ChatProvider` bound to that config's
  * connection and model. The model is closed into the returned provider here (it
@@ -604,16 +645,56 @@ export function createConfiguredAiSdkProvider(deps) {
             apiKey: config.apiKey,
             fetch: effectiveFetch,
         });
+        // The Anthropic Messages wire renders an image block inside a
+        // tool_result, thus the loop can send a picture. A custom baseURL can
+        // front a different backend that stringifies the block. Thus the
+        // harness asserts the capability only for the default endpoint. An
+        // absent flag means "cannot carry", thus a config with a custom baseURL
+        // must declare the capability. A config value overrides this default in
+        // both directions.
+        const pictureDefault = config.baseURL === undefined ? { imageToolResults: true } : {};
         return createAiSdkProvider({
             model: provider.chat(config.model),
             resolveBilling: deps.resolveBilling,
-            capabilities: config.capabilities,
+            capabilities: { ...pictureDefault, ...config.capabilities },
             logger: deps.logger,
             ...(config.maxOutputTokens !== undefined ? { maxOutputTokens: config.maxOutputTokens } : {}),
             ...(config.maxRetries !== undefined ? { maxRetries: config.maxRetries } : {}),
             ...(requestTimeoutMs !== undefined ? { requestTimeoutMs } : {}),
         });
     }
+    if (config.kind === "openai") {
+        const provider = createOpenAI({
+            baseURL: config.baseURL,
+            apiKey: config.apiKey,
+            fetch: effectiveFetch,
+        });
+        // The Responses wire renders an image block inside a function-call
+        // output, thus the loop can send a picture. A custom baseURL can front
+        // a different backend that stringifies the block. Thus the harness
+        // asserts the capability only for the default endpoint. An absent flag
+        // means "cannot carry", thus a config with a custom baseURL must
+        // declare the capability. A config value overrides this default in both
+        // directions.
+        const pictureDefault = config.baseURL === undefined ? { imageToolResults: true } : {};
+        return createAiSdkProvider({
+            // The explicit Responses binding pins the wire here. The bare
+            // factory callable of the package resolves to the same path today,
+            // but nothing in the package holds it there.
+            model: withStoreDirective(provider.responses(config.model), config.store ?? false),
+            resolveBilling: deps.resolveBilling,
+            capabilities: { ...pictureDefault, ...config.capabilities },
+            logger: deps.logger,
+            // The package puts this number on the wire as it is, and it clamps
+            // nothing per model. Thus the shared default of 64000 breaks each call
+            // to a model with a smaller cap, with a 400 that no retry can pass. An
+            // unset config sends no ceiling, and the server holds the reply at the
+            // cap of the model.
+            maxOutputTokens: config.maxOutputTokens ?? "provider-maximum",
+            ...(config.maxRetries !== undefined ? { maxRetries: config.maxRetries } : {}),
+            ...(requestTimeoutMs !== undefined ? { requestTimeoutMs } : {}),
+        });
+    }
     const provider = createOpenAICompatible({
         name: config.name,
         baseURL: config.baseURL,

package/dist/providers/types.d.ts

@@ -13,6 +13,23 @@ import type { ProviderError } from "./errors.js";
 export type { FinishReason, LanguageModel, ModelMessage, ProviderOptions, ToolSet };
 export interface ProviderCapabilities {
     readonly toolCalling: boolean;
+    /**
+     * Whether the wire can carry a picture inside a tool result. The loop moves a
+     * tool's picture into an image content block on the tool-result message. A
+     * wire that renders that block sets this flag. A wire that stringifies the
+     * block into text leaves it absent, and the loop then drops the picture and
+     * keeps the text, because base64 text floods the context and the model cannot
+     * see it. Absent means "cannot carry", never "unknown".
+     */
+    readonly imageToolResults?: boolean;
+    /**
+     * Whether the wire can carry a picture inside a user message. The loop uses
+     * this placement only when the tool result cannot carry the picture. The tool
+     * result then keeps its JSON text, and one user message after the tool message
+     * of the round carries the bytes. Absent means "cannot carry", never
+     * "unknown".
+     */
+    readonly imageUserMessages?: boolean;
 }
 export interface ChatRequest {
     readonly system: string;

package/dist/report-model/assert-rules.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The assert rules of the value tier. A resolver reads a fresh value, and these functions match it
+ * against the authored belief.
+ *
+ * Each realization of the resolver calls these functions. Thus one semantics exists, and the fixture
+ * stays the executable specification of the value tier.
+ */
+import type { Reference, UnresolvedReference } from "../contracts/report-reference.js";
+/**
+ * Read an authored value or a resolved cell as a finite number.
+ *
+ * A text-backed artifact such as a CSV holds every cell as a string, thus a numeric column arrives as
+ * `"0.01"` and not as `0.01`. A comparison that respects the JavaScript type would fail an author who
+ * states the number, and the arithmetic of a derivation could never run over a real CSV.
+ *
+ * The parse reads the whole string, thus `"12 genes"` stays text and never reads as 12. `Number` accepts
+ * the exponent form that a p-value uses, for example `"1.2e-45"`. A blank string is not a number, because
+ * `Number("")` gives 0 and an empty cell must never read as zero.
+ */
+export declare function asFiniteNumber(value: string | number): number | undefined;
+/**
+ * Match a row-filter value against a resolved cell.
+ *
+ * A text-backed artifact such as a CSV holds every cell as a string, thus a filter value of `3` must
+ * select the cell `"3"`. The compare reads both sides as a finite number, and it selects the row where the
+ * two numbers are equal. A side that is not a finite number compares by exact value, thus a text key
+ * selects by its exact text. The match is exact and carries no tolerance, because a filter names a
+ * discrete key and not a computed value with float noise.
+ */
+export declare function cellMatchesFilterValue(cell: string | number | null | undefined, filterValue: string | number): boolean;
+/**
+ * Match a resolved value against an authored one.
+ *
+ * The comparison is numeric whenever both sides read as a finite number, thus the CSV cell `"0.01"`
+ * matches the number 0.01 that an author states. An authored tolerance is an absolute difference, and it
+ * is the author's own statement of how close is close enough. With no tolerance the comparison is
+ * relative, because an exact match would fail on the float noise of a computed value. Any other pair
+ * matches on exact equality.
+ */
+export declare function valuesMatch(expected: string | number, actual: string | number, tolerance: number | undefined): boolean;
+/** Match a resolved scalar against the authored value, under the authored tolerance. */
+export declare function checkValueAssertion(reference: Reference, expected: string | number | undefined, tolerance: number | undefined, resolved: string | number): UnresolvedReference | undefined;
+/** Match the resolved citation key against the authored value. The key carries its `idKind:` prefix. */
+export declare function checkCitationAssertion(reference: Reference, expected: string | undefined, resolved: string): UnresolvedReference | undefined;

package/dist/report-model/assert-rules.js

@@ -0,0 +1,97 @@
+/**
+ * The assert rules of the value tier. A resolver reads a fresh value, and these functions match it
+ * against the authored belief.
+ *
+ * Each realization of the resolver calls these functions. Thus one semantics exists, and the fixture
+ * stays the executable specification of the value tier.
+ */
+/**
+ * The relative epsilon of a value match with no authored tolerance.
+ *
+ * Float arithmetic shifts a computed value in its last bits. For example, `0.3 - 0.1` gives
+ * 0.19999999999999998, and exact equality would report that noise as a fabrication.
+ *
+ * The epsilon absorbs the noise and nothing else. It is far below the difference that a rounded figure
+ * makes, thus an author who writes 0.05 against a true 0.0499 still fails. An author who wants a rounded
+ * figure to pass states a `tolerance`, which is the one place where the intent belongs.
+ */
+const RELATIVE_EPSILON = 1e-9;
+/**
+ * Read an authored value or a resolved cell as a finite number.
+ *
+ * A text-backed artifact such as a CSV holds every cell as a string, thus a numeric column arrives as
+ * `"0.01"` and not as `0.01`. A comparison that respects the JavaScript type would fail an author who
+ * states the number, and the arithmetic of a derivation could never run over a real CSV.
+ *
+ * The parse reads the whole string, thus `"12 genes"` stays text and never reads as 12. `Number` accepts
+ * the exponent form that a p-value uses, for example `"1.2e-45"`. A blank string is not a number, because
+ * `Number("")` gives 0 and an empty cell must never read as zero.
+ */
+export function asFiniteNumber(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (value.trim() === "") {
+        return undefined;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/**
+ * Match a row-filter value against a resolved cell.
+ *
+ * A text-backed artifact such as a CSV holds every cell as a string, thus a filter value of `3` must
+ * select the cell `"3"`. The compare reads both sides as a finite number, and it selects the row where the
+ * two numbers are equal. A side that is not a finite number compares by exact value, thus a text key
+ * selects by its exact text. The match is exact and carries no tolerance, because a filter names a
+ * discrete key and not a computed value with float noise.
+ */
+export function cellMatchesFilterValue(cell, filterValue) {
+    if (cell === null || cell === undefined) {
+        return false;
+    }
+    const cellNumber = asFiniteNumber(cell);
+    const filterNumber = asFiniteNumber(filterValue);
+    if (cellNumber !== undefined && filterNumber !== undefined) {
+        return cellNumber === filterNumber;
+    }
+    return cell === filterValue;
+}
+/** Name a value with its type, so that a failed match never reads as two identical values. */
+function describeValue(value) {
+    return typeof value === "string" ? `the string ${JSON.stringify(value)}` : `the number ${value}`;
+}
+/**
+ * Match a resolved value against an authored one.
+ *
+ * The comparison is numeric whenever both sides read as a finite number, thus the CSV cell `"0.01"`
+ * matches the number 0.01 that an author states. An authored tolerance is an absolute difference, and it
+ * is the author's own statement of how close is close enough. With no tolerance the comparison is
+ * relative, because an exact match would fail on the float noise of a computed value. Any other pair
+ * matches on exact equality.
+ */
+export function valuesMatch(expected, actual, tolerance) {
+    const expectedNumber = asFiniteNumber(expected);
+    const actualNumber = asFiniteNumber(actual);
+    if (expectedNumber !== undefined && actualNumber !== undefined) {
+        if (tolerance !== undefined) {
+            return Math.abs(expectedNumber - actualNumber) <= tolerance;
+        }
+        return Math.abs(expectedNumber - actualNumber) <= RELATIVE_EPSILON * Math.max(1, Math.abs(expectedNumber), Math.abs(actualNumber));
+    }
+    return expected === actual;
+}
+/** Match a resolved scalar against the authored value, under the authored tolerance. */
+export function checkValueAssertion(reference, expected, tolerance, resolved) {
+    if (expected === undefined || valuesMatch(expected, resolved, tolerance)) {
+        return undefined;
+    }
+    return { reference, reason: "assertion-failed", detail: `expected ${describeValue(expected)} but resolved ${describeValue(resolved)}` };
+}
+/** Match the resolved citation key against the authored value. The key carries its `idKind:` prefix. */
+export function checkCitationAssertion(reference, expected, resolved) {
+    if (expected === undefined || expected === resolved) {
+        return undefined;
+    }
+    return { reference, reason: "assertion-failed", detail: `expected ${String(expected)} but resolved citation ${resolved}` };
+}

package/dist/report-model/draft-hash.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The one hash of a draft document.
+ *
+ * The look-before-record rule rides two durable markers, and each marker holds a hash of the draft. A
+ * stamp writes a hash, and a compare reads one. Both call this one function, thus two serializations of one
+ * document cannot split.
+ *
+ * The function serializes the draft with sorted object keys, and it hashes the text with sha256. The sort
+ * makes the hash independent of key order. Thus two objects with the same values and a different key order
+ * give one hash, and a marker survives a round trip through storage.
+ */
+import type { DraftDocument } from "./draft.js";
+/** The sha256 hash of the draft, over a JSON serialization with sorted keys. */
+export declare function computeDraftHash(document: DraftDocument): string;

package/dist/report-model/draft-hash.js

@@ -0,0 +1,36 @@
+/**
+ * The one hash of a draft document.
+ *
+ * The look-before-record rule rides two durable markers, and each marker holds a hash of the draft. A
+ * stamp writes a hash, and a compare reads one. Both call this one function, thus two serializations of one
+ * document cannot split.
+ *
+ * The function serializes the draft with sorted object keys, and it hashes the text with sha256. The sort
+ * makes the hash independent of key order. Thus two objects with the same values and a different key order
+ * give one hash, and a marker survives a round trip through storage.
+ */
+import { createHash } from "node:crypto";
+/**
+ * Give back a copy of a value with each object key in sorted order, at every depth.
+ *
+ * An array keeps its order, because the order of an array is data. An object gets its keys in one canonical
+ * order, thus the serialization does not depend on the order that a producer wrote the keys.
+ */
+function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    if (value !== null && typeof value === "object") {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = canonicalize(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+/** The sha256 hash of the draft, over a JSON serialization with sorted keys. */
+export function computeDraftHash(document) {
+    const canonical = JSON.stringify(canonicalize(document));
+    return createHash("sha256").update(canonical).digest("hex");
+}

package/dist/report-model/fixture-resolver.js

@@ -4,18 +4,8 @@
  * assertion rules without a host.
  */
 import { err, ok } from "neverthrow";
+import { asFiniteNumber, cellMatchesFilterValue, checkCitationAssertion, checkValueAssertion } from "./assert-rules.js";
 import { columnsHeldByNoRow, fileTypeHoldsNoCell, snapshotEntry, } from "./reference-resolver.js";
-/**
- * The relative epsilon of a value match with no authored tolerance.
- *
- * Float arithmetic shifts a computed value in its last bits. For example, `0.3 - 0.1` gives
- * 0.19999999999999998, and exact equality would report that noise as a fabrication.
- *
- * The epsilon absorbs the noise and nothing else. It is far below the difference that a rounded figure
- * makes, thus an author who writes 0.05 against a true 0.0499 still fails. An author who wants a rounded
- * figure to pass states a `tolerance`, which is the one place where the intent belongs.
- */
-const RELATIVE_EPSILON = 1e-9;
 /** Build an `Err` that carries the unresolved reference. The `detail` key is present only when there is a detail to carry. */
 function fail(reference, reason, detail) {
     const failure = detail !== undefined ? { reference, reason, detail } : { reference, reason };
@@ -25,65 +15,6 @@ function fail(reference, reason, detail) {
 function describeReference(reference) {
     return `artifact value at ${reference.path} column ${reference.locator.column}`;
 }
-/**
- * Read an authored value or a resolved cell as a finite number.
- *
- * A text-backed artifact such as a CSV holds every cell as a string, thus a numeric column arrives as
- * `"0.01"` and not as `0.01`. A comparison that respects the JavaScript type would fail an author who
- * states the number, and the arithmetic of a derivation could never run over a real CSV.
- *
- * The parse reads the whole string, thus `"12 genes"` stays text and never reads as 12. `Number` accepts
- * the exponent form that a p-value uses, for example `"1.2e-45"`. A blank string is not a number, because
- * `Number("")` gives 0 and an empty cell must never read as zero.
- */
-function asFiniteNumber(value) {
-    if (typeof value === "number") {
-        return Number.isFinite(value) ? value : undefined;
-    }
-    if (value.trim() === "") {
-        return undefined;
-    }
-    const parsed = Number(value);
-    return Number.isFinite(parsed) ? parsed : undefined;
-}
-/** Name a value with its type, so that a failed match never reads as two identical values. */
-function describeValue(value) {
-    return typeof value === "string" ? `the string ${JSON.stringify(value)}` : `the number ${value}`;
-}
-/**
- * Match a resolved value against an authored one.
- *
- * The comparison is numeric whenever both sides read as a finite number, thus the CSV cell `"0.01"`
- * matches the number 0.01 that an author states. An authored tolerance is an absolute difference, and it
- * is the author's own statement of how close is close enough. With no tolerance the comparison is
- * relative, because an exact match would fail on the float noise of a computed value. Any other pair
- * matches on exact equality.
- */
-function valuesMatch(expected, actual, tolerance) {
-    const expectedNumber = asFiniteNumber(expected);
-    const actualNumber = asFiniteNumber(actual);
-    if (expectedNumber !== undefined && actualNumber !== undefined) {
-        if (tolerance !== undefined) {
-            return Math.abs(expectedNumber - actualNumber) <= tolerance;
-        }
-        return Math.abs(expectedNumber - actualNumber) <= RELATIVE_EPSILON * Math.max(1, Math.abs(expectedNumber), Math.abs(actualNumber));
-    }
-    return expected === actual;
-}
-/** Match a resolved scalar against the authored value, under the authored tolerance. */
-function checkValueAssertion(reference, expected, tolerance, resolved) {
-    if (expected === undefined || valuesMatch(expected, resolved, tolerance)) {
-        return undefined;
-    }
-    return { reference, reason: "assertion-failed", detail: `expected ${describeValue(expected)} but resolved ${describeValue(resolved)}` };
-}
-/** Match the resolved citation key against the authored value. The key carries its `idKind:` prefix. */
-function checkCitationAssertion(reference, expected, resolved) {
-    if (expected === undefined || expected === resolved) {
-        return undefined;
-    }
-    return { reference, reason: "assertion-failed", detail: `expected ${String(expected)} but resolved citation ${resolved}` };
-}
 function resolveArtifactValue(reference, snapshot) {
     const artifact = snapshotEntry(snapshot, reference.path);
     if (artifact === undefined) {
@@ -111,7 +42,7 @@ function resolveArtifactValue(reference, snapshot) {
     }
     else if (locator.rowFilter !== undefined) {
         const filter = locator.rowFilter;
-        const matches = rows.filter((row) => row[filter.column] === filter.value);
+        const matches = rows.filter((row) => cellMatchesFilterValue(row[filter.column], filter.value));
         if (matches.length === 0) {
             return fail(reference, "locator-out-of-range", `no row where ${filter.column} equals ${String(filter.value)}`);
         }

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

@@ -0,0 +1,124 @@
+/**
+ * The production realization of the reference resolver. It reads the pinned artifact on disk, and it
+ * gives the value that the belief points at.
+ *
+ * The realization holds three layers. Layer one is identity: membership through `snapshotEntry`, and a
+ * streamed hash compare with `computeSha256File`. A hash mismatch fails before any parse. Layer two is
+ * the host fast path: an in-process parse of a CSV, a TSV, a JSON, or a parquet file at or under the cap.
+ * Layer three is the fall-through: an over-cap file or a host parse fault goes to the extraction arm. On any
+ * doubt the read falls through, thus correctness never depends on the host parser. An extension that names
+ * no tabular format refuses here, because the host decides the format for both arms.
+ *
+ * A read of the bytes is the expensive part, thus an optional `ArtifactReadCache` outlives one resolver. It
+ * holds the streamed hash and the extracted rows against a stat signature. Two tool calls of one analysis
+ * share one cache, and each call still binds its own extraction arm with its own auth.
+ *
+ * The realization calls the shared assert functions in `assert-rules.ts`, and it mirrors the locator walk
+ * and the reason choices of `fixture-resolver.ts`. Thus one semantics exists, and the fixture stays the
+ * executable specification of the value tier. The two realizations are substitutable behind the seam.
+ */
+import { type ReferenceResolver } from "./reference-resolver.js";
+/**
+ * One artifact that the host fast path could not read, addressed for the extraction arm. The `hash` pins
+ * the exact bytes, thus the arm reads the same artifact that the identity layer verified.
+ *
+ * `format` carries the reader that the host decided. The arm never derives a reader from the extension,
+ * thus the host arm and the sandbox arm can never read one file two ways.
+ */
+export interface ExtractionRequest {
+    readonly path: string;
+    readonly hash: string;
+    readonly format: TabularFormat;
+}
+/** The rows that the extraction arm read for one artifact. Downstream the rows share the host path logic. */
+export interface ExtractionArtifact {
+    readonly rows: Array<Record<string, string | number>>;
+}
+/**
+ * The out-of-process read arm. One `extract` call covers every fall-through artifact of one document
+ * pass. The result maps each requested path to its rows. A path that the arm could not read is absent
+ * from the map, and the reference at that path fails as `unreadable-artifact`.
+ *
+ * The arm is a seam, thus a test stubs it. While no realization is wired, a fall-through reference fails
+ * with `extraction-unavailable`, and the detail names the absent arm.
+ */
+export interface ExtractionArm {
+    extract(requests: readonly ExtractionRequest[]): Promise<ReadonlyMap<string, ExtractionArtifact>>;
+}
+/**
+ * The disk facts of one artifact that outlive one resolver.
+ *
+ * `signature` states the bytes that the pass read: the size, the modification time, and the inode. A later
+ * pass compares its own stat against it before it trusts anything here, thus a file that changed on disk is
+ * read again. `rows` is present only for a clean read, because a read fault is transient and it must not
+ * stick to the analysis.
+ */
+export interface ArtifactRead {
+    readonly signature: string;
+    readonly hash: string;
+    readonly rows?: Array<Record<string, string | number>>;
+}
+/**
+ * The read cache of one analysis. It holds what a read of the bytes costs: the streamed hash, and the rows
+ * of a file that the host could not parse in process. Two resolvers of one analysis share one cache, thus a
+ * preview and the record that follows it hash one unchanged file one time and start one container.
+ *
+ * The cache holds no authorization and no session value. Each resolver still binds its own extraction arm
+ * over the auth of its own call.
+ */
+export interface ArtifactReadCache {
+    get(absolutePath: string): ArtifactRead | undefined;
+    set(absolutePath: string, read: ArtifactRead): void;
+}
+/** The read caches that the host process holds, one for each recent analysis. */
+export interface ArtifactReadStore {
+    forAnalysis(analysisId: string): ArtifactReadCache;
+}
+/**
+ * Make the read store of the report path. One host process serves many analyses, thus the store bounds both
+ * dimensions: how many analyses it holds, and how many artifacts one analysis holds. A dropped entry costs
+ * one read again, and it is never wrong.
+ */
+export declare function createArtifactReadStore(): ArtifactReadStore;
+/**
+ * The construction deps of the production resolver.
+ *
+ * `workspaceRoot` and `analysisId` contain the untrusted snapshot path through `resolveWorkspacePath`,
+ * the same containment as the preview tool. `cap` gates the cell extraction, and it defaults to 16 MiB.
+ * `extractionArm` is optional, because no sandbox realization is wired yet. `readCache` is optional, thus a
+ * resolver with no cache reads every artifact itself and its reads die with it.
+ */
+export interface ProductionResolverDeps {
+    readonly workspaceRoot: string;
+    readonly analysisId: string;
+    readonly cap?: number;
+    readonly extractionArm?: ExtractionArm;
+    readonly readCache?: ArtifactReadCache;
+}
+/**
+ * The tabular formats that the host fast path reads. The host decides which one a file is, one time, and it
+ * carries the decision to the extraction arm. Another extension names no format at all.
+ */
+export type TabularFormat = "csv" | "tsv" | "json" | "parquet";
+/**
+ * Read one value as a cell, or drop it.
+ *
+ * A parquet integer column decodes as a `bigint`, thus the coercion narrows it to a number. A `null` or an
+ * absent value is not a cell, thus it drops and the row omits the key. The fixture row omits an empty cell
+ * the same way. An object or an array is structural doubt, thus it drops too and the format falls through
+ * where the caller detects the loss.
+ *
+ * A non-finite number is not a cell either. A parquet float column holds a `NaN` or an `Infinity`, thus the
+ * coercion drops it and the row omits the key. The extraction script (`tasks/extract-values-script.ts`)
+ * drops the same value to `None`, thus the host arm and the sandbox arm read the same bytes the same way.
+ */
+export declare function coerceCell(value: unknown): string | number | undefined;
+/**
+ * Make the production resolver over the workspace root and the optional extraction arm.
+ *
+ * The resolver holds a per-pass cache. `prepare` groups the references by artifact, reads each file one
+ * time, and fills the cache. `resolve` then answers from the cache. A `resolve` with no prior `prepare`
+ * still answers, and it writes what it read into the same cache. Thus the cost is one read for each
+ * artifact on both paths, and never one read for each reference.
+ */
+export declare function createProductionResolver(deps: ProductionResolverDeps): ReferenceResolver;