@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/report-model/draft.js

@@ -23,8 +23,10 @@ export const DraftSectionBlockSchema = z.strictObject({
     title: z.string(),
     blocks: z.lazy(() => z.array(DraftBlockSchema)),
 });
+/** The draft block union, before the erasing annotation of {@link DraftBlockSchema}. */
+export const DraftBlockUnionSchema = z.discriminatedUnion("kind", [DraftSectionBlockSchema, ...ATOM_BLOCK_SCHEMAS]);
 /** The draft block union. A `z.ZodType<DraftBlock>` annotation gives the recursive members a stable type. */
-export const DraftBlockSchema = z.discriminatedUnion("kind", [DraftSectionBlockSchema, ...ATOM_BLOCK_SCHEMAS]);
+export const DraftBlockSchema = DraftBlockUnionSchema;
 /** The root of a draft. It permits zero sections, thus an empty draft is a legal state. */
 export const DraftDocumentSchema = z.strictObject({
     title: z.string(),

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

@@ -5,7 +5,7 @@
  */
 import { err, ok } from "neverthrow";
 import { asFiniteNumber, cellMatchesFilterValue, checkCitationAssertion, checkValueAssertion } from "./assert-rules.js";
-import { applyRowBound, columnsHeldByNoRow, fileTypeHoldsNoCell, snapshotEntry, } from "./reference-resolver.js";
+import { applyRowBound, columnsHeldByNoRow, fileTypeHoldsNoCell, snapshotEntry, snapshotRows, } from "./reference-resolver.js";
 /** 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 };
@@ -27,46 +27,61 @@ function resolveArtifactValue(reference, snapshot) {
     // cell that no real artifact holds. Thus the refusal comes before the read of the rows.
     const valueFileType = artifact.fileType;
     if (fileTypeHoldsNoCell(valueFileType)) {
-        return fail(reference, "unreadable-artifact", `the ${valueFileType} at ${reference.path} holds no cell to read`);
+        return fail(reference, "unreadable-artifact", `the ${String(valueFileType)} at ${reference.path} holds no cell to read`);
     }
     // An artifact with no rows is pinned whole, thus it addresses no cell and every locator over it lands
     // out of range.
-    const rows = artifact.rows ?? [];
+    const readRows = snapshotRows(artifact);
+    if (readRows.isErr()) {
+        return fail(reference, "unreadable-artifact", `the artifact at ${reference.path} holds a malformed row: ${readRows.error}`);
+    }
+    const rows = readRows.value;
     const locator = reference.locator;
     let selectedRow;
     if (locator.row !== undefined) {
-        if (locator.row < 0 || locator.row >= rows.length) {
+        const row = rows[locator.row];
+        if (row === undefined) {
             return fail(reference, "locator-out-of-range", `row ${locator.row} is outside the ${rows.length} rows`);
         }
-        selectedRow = rows[locator.row];
+        selectedRow = row;
     }
     else if (locator.rowFilter !== undefined) {
         const filter = locator.rowFilter;
         const matches = rows.filter((row) => cellMatchesFilterValue(row[filter.column], filter.value));
-        if (matches.length === 0) {
+        const match = matches[0];
+        if (match === undefined) {
             return fail(reference, "locator-out-of-range", `no row where ${filter.column} equals ${String(filter.value)}`);
         }
         if (matches.length > 1) {
             return fail(reference, "ambiguous-match", `${matches.length} rows where ${filter.column} equals ${String(filter.value)}`);
         }
-        selectedRow = matches[0];
+        selectedRow = match;
     }
     else {
         // The locator schema forbids a locator with neither selector. The resolver cannot depend on a
         // prior parse, thus it treats a row that no selector addresses as out of range.
         return fail(reference, "locator-out-of-range", "the locator selects no row");
     }
-    // A real table holds an empty cell, and a parser gives it back as an absent key, `undefined`, or
-    // `null`. None of the three is a value that a scalar reference can bind. An empty string is a value,
-    // thus it stays valid. The wider annotation admits the three, because the row type promises a value
-    // for each key that it holds.
+    // A real table holds an empty cell, and the snapshot parser gives it back as an absent
+    // key: `snapshotRows` drops a cell that parsed as `null` or `undefined`, so an absent key
+    // is the only absence. It is not a value that a scalar reference can bind. An empty
+    // string is a value, thus it stays valid.
     const cell = selectedRow[locator.column];
-    if (cell === undefined || cell === null) {
+    if (cell === undefined) {
         return fail(reference, "locator-out-of-range", `column ${locator.column} holds no value in the selected row`);
     }
     const valueFailure = checkValueAssertion(reference, reference.assert?.value, reference.assert?.tolerance, cell);
     return valueFailure !== undefined ? err(valueFailure) : ok({ type: "scalar", value: cell });
 }
+/**
+ * Put one own data property on a projected row.
+ *
+ * A plain assignment at the key `__proto__` reaches the prototype setter, thus the projection loses a
+ * column that the row holds. The definition makes an own data property for each key.
+ */
+function defineOwn(target, key, value) {
+    Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+}
 function resolveArtifactTable(reference, snapshot) {
     const artifact = snapshotEntry(snapshot, reference.path);
     if (artifact === undefined) {
@@ -77,13 +92,17 @@ function resolveArtifactTable(reference, snapshot) {
     }
     const tableFileType = artifact.fileType;
     if (fileTypeHoldsNoCell(tableFileType)) {
-        return fail(reference, "unreadable-artifact", `the ${tableFileType} at ${reference.path} holds no cell to read`);
+        return fail(reference, "unreadable-artifact", `the ${String(tableFileType)} at ${reference.path} holds no cell to read`);
     }
     // The bound ranks the rows as the artifact holds them, thus a bound over a column that the subset
     // below leaves out still ranks them. An unknown bound column addresses nothing, exactly as an unknown
     // subset column does.
     const bound = reference.rowBound;
-    const allRows = artifact.rows ?? [];
+    const readRows = snapshotRows(artifact);
+    if (readRows.isErr()) {
+        return fail(reference, "unreadable-artifact", `the artifact at ${reference.path} holds a malformed row: ${readRows.error}`);
+    }
+    const allRows = readRows.value;
     if (bound !== undefined && columnsHeldByNoRow(allRows, [bound.column]).length > 0) {
         return fail(reference, "locator-out-of-range", `the row bound names column ${bound.column}, which the table at ${reference.path} does not hold`);
     }
@@ -107,8 +126,9 @@ function resolveArtifactTable(reference, snapshot) {
     const projectedRows = rows.map((row) => {
         const projected = {};
         for (const column of columns) {
-            if (column in row) {
-                projected[column] = row[column];
+            const cell = row[column];
+            if (cell !== undefined) {
+                defineOwn(projected, column, cell);
             }
         }
         return projected;
@@ -145,6 +165,9 @@ async function resolveDerivation(reference, snapshot) {
     }
     const a = numbers[0];
     const b = numbers[1];
+    if (a === undefined || b === undefined) {
+        return fail(reference, "locator-out-of-range", `operation ${reference.op} needs two inputs, and the derivation holds ${numbers.length}`);
+    }
     let result;
     switch (reference.op) {
         case "ratio":

package/dist/report-model/pin-snapshot.d.ts

@@ -31,13 +31,13 @@ export type PinSnapshotError = {
     cause: unknown;
 };
 /** The construction options of the pin. */
-export interface PinReportSnapshotOptions {
+export type PinReportSnapshotOptions = {
     /**
      * The workspace-root seam of the caller. The citation evidence sits on disk, thus a composition
      * that binds no seam pins the artifact map alone.
      */
     readonly resolveWorkspaceRoot?: ResolveWorkspaceRoot;
-}
+};
 /**
  * Pin the snapshot of one analysis from the artifact ledger and from the synthesis records of its runs.
  *

package/dist/report-model/pin-snapshot.js

@@ -18,6 +18,9 @@
  */
 import { err, ok } from "neverthrow";
 import { readSynthesisText } from "../execution/run-synthesis.js";
+import { parseJsonAs } from "../lib/parse-json.js";
+import { parseUnknownRecord, UnknownRecordSchema } from "../lib/unknown-containers.js";
+import { nullProtoRecord } from "../lib/null-proto.js";
 import { queryAnalysisArtifacts } from "../state/artifacts.js";
 import { queryRunsByAnalysis } from "../state/runs.js";
 /** The page size of the run listing. The listing walks the pages until a short page ends the walk. */
@@ -56,16 +59,17 @@ function pushPmidCitations(list, entries) {
         return;
     }
     for (const reference of list) {
-        if (typeof reference !== "object" || reference === null) {
+        const fields = parseUnknownRecord(reference);
+        if (fields === undefined) {
             continue;
         }
-        const pmid = reference.pmid;
+        const pmid = fields.pmid;
         if (typeof pmid !== "string") {
             continue;
         }
         const id = pmid.trim();
         if (id.length > 0) {
-            const record = recordOf(reference);
+            const record = recordOf(fields);
             entries.push(record === undefined ? { key: `pmid:${id}` } : { key: `pmid:${id}`, record });
         }
     }
@@ -83,25 +87,23 @@ function pushPmidCitations(list, entries) {
  * description sits there.
  */
 function citationsOf(text) {
-    let parsed;
+    let fields;
     try {
-        parsed = JSON.parse(text);
+        fields = parseJsonAs(text, UnknownRecordSchema);
     }
     catch {
         return [];
     }
-    if (typeof parsed !== "object" || parsed === null) {
-        return [];
-    }
     const entries = [];
-    pushPmidCitations(parsed.keyReferences, entries);
-    const findings = parsed.findings;
+    pushPmidCitations(fields.keyReferences, entries);
+    const findings = fields.findings;
     if (Array.isArray(findings)) {
         for (const finding of findings) {
-            if (typeof finding !== "object" || finding === null) {
+            const findingFields = parseUnknownRecord(finding);
+            if (findingFields === undefined) {
                 continue;
             }
-            pushPmidCitations(finding.references, entries);
+            pushPmidCitations(findingFields.references, entries);
         }
     }
     return entries;
@@ -165,9 +167,7 @@ export async function pinReportSnapshot(pool, analysisId, options = {}) {
     const ledgerRows = await queryAnalysisArtifacts(pool, analysisId);
     if (ledgerRows.isErr())
         return err({ kind: "ledger-read-failed", cause: ledgerRows.error.cause });
-    // The ledger accepts any path. A null-prototype map keeps a key such as `__proto__` an ordinary
-    // entry, thus no path collides with a prototype slot.
-    const artifacts = Object.create(null);
+    const artifacts = nullProtoRecord();
     for (const row of ledgerRows.value) {
         artifacts[row.path] = { hash: row.hash, fileType: row.fileType };
     }

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

@@ -18,7 +18,7 @@
  * executable specification of the value tier. The two realizations are substitutable behind the seam.
  */
 import { type Result } from "neverthrow";
-import type { Suspension } from "../workflows/suspension.js";
+import type { SuspendingRefusal } from "../sandbox/sandbox-error.js";
 import { type ReferenceResolver } from "./reference-resolver.js";
 /** One artifact row, as plain cells. A text-backed format holds a numeric column as a string. */
 type Row = Record<string, string | number>;
@@ -29,27 +29,27 @@ type Row = Record<string, string | number>;
  * `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 {
+export type 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 {
+export type 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`. A suspension of the pass is
- * the `err`, and each reference of the batch reports its reason.
+ * from the map, and the reference at that path fails as `unreadable-artifact`. A refusal of the sandbox of the
+ * pass with the suspend flag is the `err`, and each reference of the batch reports its reason.
  *
  * 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<Result<ReadonlyMap<string, ExtractionArtifact>, Suspension>>;
-}
+export type ExtractionArm = {
+    extract(requests: readonly ExtractionRequest[]): Promise<Result<ReadonlyMap<string, ExtractionArtifact>, SuspendingRefusal>>;
+};
 /**
  * The disk facts of one artifact that outlive one resolver.
  *
@@ -58,11 +58,11 @@ export interface ExtractionArm {
  * 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 {
+export type 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
@@ -71,14 +71,14 @@ export interface ArtifactRead {
  * 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 {
+export type 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 {
+export type 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
@@ -93,13 +93,13 @@ export declare function createArtifactReadStore(): ArtifactReadStore;
  * `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 {
+export type 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.

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

@@ -21,8 +21,11 @@ import { err, ok } from "neverthrow";
 import { readFile, stat } from "node:fs/promises";
 import { extname } from "node:path";
 import { parquetReadObjects } from "hyparquet";
+import { z } from "zod";
+import { isWorkflowCancellation } from "../runtime/dbos.js";
 import { allWithConcurrency } from "../lib/async-utils.js";
 import { computeSha256File } from "../lib/fs-helpers.js";
+import { parseJsonAs } from "../lib/parse-json.js";
 import { resolveWorkspacePath } from "../workspace/paths.js";
 import { asFiniteNumber, cellMatchesFilterValue, checkCitationAssertion, checkValueAssertion } from "./assert-rules.js";
 import { applyRowBound, columnsHeldByNoRow, fileTypeHoldsNoCell, snapshotEntry, } from "./reference-resolver.js";
@@ -175,7 +178,7 @@ function parseRecords(text, delimiter) {
                 i += 1;
                 let closed = false;
                 while (i < n) {
-                    const ch = text[i];
+                    const ch = text.charAt(i);
                     if (ch === '"') {
                         if (text[i + 1] === '"') {
                             field += '"';
@@ -201,7 +204,7 @@ function parseRecords(text, delimiter) {
             }
             else {
                 while (i < n) {
-                    const ch = text[i];
+                    const ch = text.charAt(i);
                     if (ch === delimiter || ch === "\r" || ch === "\n") {
                         break;
                     }
@@ -241,10 +244,10 @@ export function parseDelimited(text, delimiter) {
     if (records === undefined) {
         return undefined;
     }
-    if (records.length === 0) {
+    const header = records[0];
+    if (header === undefined) {
         return [];
     }
-    const header = records[0];
     const seen = new Set();
     for (const name of header) {
         if (seen.has(name)) {
@@ -253,8 +256,7 @@ export function parseDelimited(text, delimiter) {
         seen.add(name);
     }
     const rows = [];
-    for (let r = 1; r < records.length; r += 1) {
-        const fields = records[r];
+    for (const fields of records.slice(1)) {
         // A blank line parses as one empty field, thus the walk drops it and reads no dialect into it. A
         // record with more than one field, or one non-empty field, still obeys the count check, thus a
         // genuinely ragged record falls through.
@@ -265,39 +267,36 @@ export function parseDelimited(text, delimiter) {
             return undefined;
         }
         const row = {};
-        for (let c = 0; c < header.length; c += 1) {
-            row[header[c]] = fields[c];
+        for (const [c, name] of header.entries()) {
+            const value = fields[c];
+            if (value !== undefined) {
+                row[name] = value;
+            }
         }
         rows.push(row);
     }
     return rows;
 }
+/** A cell of a JSON table: the scalars JSON carries. A non-finite number stays a cell — `JSON.parse`
+ * reads an over-large literal as Infinity, and the coercion drops it. A nested value is structural doubt. */
+const JsonTableCell = z.custom((cell) => cell === null || typeof cell === "number" || typeof cell === "string" || typeof cell === "boolean");
 /**
- * Parse a JSON file into rows. The strict shape is an array of flat objects. A parse fault, a top-level
- * value that is not an array, and a nested cell are structural doubt, thus each gives back `undefined` and
- * the file falls through.
+ * Parse a JSON file into rows. The strict shape is an array of flat objects with scalar cells. A parse
+ * fault, a top-level value that is not an array, and a nested cell are structural doubt, thus each gives
+ * back `undefined` and the file falls through.
  */
 function parseJsonTable(text) {
-    let value;
+    let table;
     try {
-        value = JSON.parse(text);
+        table = parseJsonAs(text, z.array(z.record(z.string(), JsonTableCell)));
     }
     catch {
         return undefined;
     }
-    if (!Array.isArray(value)) {
-        return undefined;
-    }
     const rows = [];
-    for (const item of value) {
-        if (item === null || typeof item !== "object" || Array.isArray(item)) {
-            return undefined;
-        }
+    for (const fields of table) {
         const row = {};
-        for (const [key, cell] of Object.entries(item)) {
-            if (cell !== null && typeof cell === "object") {
-                return undefined;
-            }
+        for (const [key, cell] of Object.entries(fields)) {
             const coerced = coerceCell(cell);
             if (coerced !== undefined) {
                 row[key] = coerced;
@@ -441,9 +440,12 @@ async function extractFallThrough(arm, requests) {
     try {
         answered = await arm.extract(requests.map((request) => ({ path: request.path, hash: request.hash, format: request.format })));
     }
-    catch {
+    catch (cause) {
         // The arm speaks the throw protocol for a genuine infrastructure fault. This boundary turns the
-        // throw into a value, thus each reference on the batch reads a failure as data.
+        // throw into a value, thus each reference on the batch reads a failure as data. A cancel of the
+        // workflow is not a fault of the read, thus it leaves to DBOS with no change.
+        if (isWorkflowCancellation(cause))
+            throw cause;
         for (const request of requests) {
             out.set(request.path, { kind: "unreadable", detail: `the extraction arm did not read the file at ${request.path}` });
         }
@@ -453,7 +455,7 @@ async function extractFallThrough(arm, requests) {
         for (const request of requests) {
             out.set(request.path, {
                 kind: "unavailable",
-                detail: `the analysis is suspended (${answered.error.reason}), thus the file at ${request.path} was not read`,
+                detail: `the host refused the sandbox (${answered.error.reason}), thus the file at ${request.path} was not read`,
             });
         }
         return out;
@@ -578,7 +580,7 @@ export function createProductionResolver(deps) {
             return err({ reference, reason: "hash-mismatch", detail: `expected ${reference.hash} but the artifact hash is ${identity.onDiskHash}` });
         }
         if (fileTypeHoldsNoCell(identity.fileType)) {
-            return err({ reference, reason: "unreadable-artifact", detail: `the ${identity.fileType} at ${reference.path} holds no cell to read` });
+            return err({ reference, reason: "unreadable-artifact", detail: `the ${String(identity.fileType)} at ${reference.path} holds no cell to read` });
         }
         const cells = await getCells(reference.path, identity);
         if (cells.kind === "unavailable") {
@@ -594,21 +596,23 @@ export function createProductionResolver(deps) {
         const locator = reference.locator;
         let selectedRow;
         if (locator.row !== undefined) {
-            if (locator.row < 0 || locator.row >= rows.length) {
+            const row = rows[locator.row];
+            if (row === undefined) {
                 return fail(reference, "locator-out-of-range", `row ${locator.row} is outside the ${rows.length} rows`);
             }
-            selectedRow = rows[locator.row];
+            selectedRow = row;
         }
         else if (locator.rowFilter !== undefined) {
             const filter = locator.rowFilter;
             const matches = rows.filter((row) => cellMatchesFilterValue(row[filter.column], filter.value));
-            if (matches.length === 0) {
+            const match = matches[0];
+            if (match === undefined) {
                 return fail(reference, "locator-out-of-range", `no row where ${filter.column} equals ${String(filter.value)}`);
             }
             if (matches.length > 1) {
                 return fail(reference, "ambiguous-match", `${matches.length} rows where ${filter.column} equals ${String(filter.value)}`);
             }
-            selectedRow = matches[0];
+            selectedRow = match;
         }
         else {
             // The locator schema forbids a locator with neither selector. The resolver cannot depend on a
@@ -617,8 +621,10 @@ export function createProductionResolver(deps) {
         }
         // A real table holds an empty cell, and a parse gives it back as an absent key. An absent key is
         // not a value that a scalar reference can bind. An empty string is a value, thus it stays valid.
+        // A cell that parsed as `null` never lands in a row: `coerceCell` drops it, so `null` is not
+        // an absence the resolver can meet here.
         const cell = selectedRow[locator.column];
-        if (cell === undefined || cell === null) {
+        if (cell === undefined) {
             return fail(reference, "locator-out-of-range", `column ${locator.column} holds no value in the selected row`);
         }
         const valueFailure = checkValueAssertion(reference, reference.assert?.value, reference.assert?.tolerance, cell);
@@ -660,8 +666,9 @@ export function createProductionResolver(deps) {
         const projectedRows = rows.map((row) => {
             const projected = {};
             for (const column of columns) {
-                if (column in row) {
-                    projected[column] = row[column];
+                const cell = row[column];
+                if (cell !== undefined) {
+                    projected[column] = cell;
                 }
             }
             return projected;
@@ -701,6 +708,9 @@ export function createProductionResolver(deps) {
         }
         const a = numbers[0];
         const b = numbers[1];
+        if (a === undefined || b === undefined) {
+            return fail(reference, "locator-out-of-range", `operation ${reference.op} needs two inputs, and the derivation holds ${numbers.length}`);
+        }
         let result;
         switch (reference.op) {
             case "ratio":
@@ -764,9 +774,9 @@ export function createProductionResolver(deps) {
         }
         // Compute the identity of each path, one read each, under the fan-out bound.
         const entries = [...byPath.entries()];
-        const identities = await allWithConcurrency(entries.map(([path]) => () => computeIdentity(workspaceRoot, analysisId, path, snapshot, readCache)), PREPARE_CONCURRENCY);
-        for (let e = 0; e < entries.length; e += 1) {
-            idCache.set(entries[e][0], identities[e]);
+        const identityPairs = await allWithConcurrency(entries.map(([path]) => async () => ({ path, identity: await computeIdentity(workspaceRoot, analysisId, path, snapshot, readCache) })), PREPARE_CONCURRENCY);
+        for (const { path, identity } of identityPairs) {
+            idCache.set(path, identity);
         }
         // Read cells for each cell-reading path whose on-disk hash matches an expected pin. A hash that no
         // pin expects means every reference at the path mismatches, thus no parse runs on a drifted file.
@@ -789,14 +799,12 @@ export function createProductionResolver(deps) {
                 pending.push(target);
             }
         }
-        const reads = await allWithConcurrency(pending.map((target) => () => hostReadCells(cap, target.path, target.identity)), PREPARE_CONCURRENCY);
+        const reads = await allWithConcurrency(pending.map((target) => async () => ({ target, read: await hostReadCells(cap, target.path, target.identity) })), PREPARE_CONCURRENCY);
         // Split the clean reads from the fall-throughs, then resolve every fall-through in one arm call. An
         // unsupported format reaches no arm, because no reader is decided for it.
         const fallThrough = [];
         const identityByPath = new Map();
-        for (let t = 0; t < pending.length; t += 1) {
-            const target = pending[t];
-            const read = reads[t];
+        for (const { target, read } of reads) {
             if (read.kind === "rows") {
                 cellsCache.set(target.path, { kind: "rows", rows: read.rows });
                 shareRows(readCache, target.identity, read.rows);

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

@@ -5,7 +5,7 @@
  * belief points at. The harness declares the seam here, thus a production realization can read storage,
  * and a fixture realization can read an in-memory snapshot. The two obey the same contract.
  */
-import type { Result } from "neverthrow";
+import { type Result } from "neverthrow";
 import type { Reference, RowBound, UnresolvedReference } from "../contracts/report-reference.js";
 /**
  * One pinned artifact: its content hash, and its rows as plain cells.
@@ -15,6 +15,9 @@ import type { Reference, RowBound, UnresolvedReference } from "../contracts/repo
  * skip a type inference pass, and resolution compares a numeral by its numeric value and never by its
  * JavaScript type.
  *
+ * A real parser gives an empty cell back as an absent key, `undefined`, or `null`, and a row admits all
+ * three. `snapshotRows` parses an entry's rows into the present cells that the resolution reads.
+ *
  * `rows` is optional because an image is pinned by its hash alone and holds no cells. An empty array in
  * that position would say that the artifact holds zero rows, which is a different and false claim. The
  * pin never populates `rows`. `rows` serves the fixture realization only, and that realization resolves
@@ -26,19 +29,32 @@ import type { Reference, RowBound, UnresolvedReference } from "../contracts/repo
  * `figure`, `script`, `log`, `notebook`, and `output`. Thus the field can refuse a kind of reference, and
  * it can never confirm one. An `output` covers a table and an image alike.
  */
-export interface ArtifactSnapshot {
+export type ArtifactSnapshot = {
     hash: string;
     fileType?: string | null;
-    rows?: Array<Record<string, string | number>>;
-}
+    rows?: Array<Record<string, string | number | null | undefined>>;
+};
+/**
+ * Give back the present cells of a snapshot entry's rows, or an empty array for an entry with no rows.
+ *
+ * The structural tier and the fixture resolver both read this one parse. Thus the two tiers can never
+ * disagree about the rows of one entry.
+ *
+ * A real parser gives an empty cell back as an absent key, `undefined`, or `null`; the parse admits each
+ * and yields the present cells, so the reads below see one absence shape only. The `Err` channel carries
+ * the account of a row that the artifact forbids: an entry of the rows list that is not a record, or a
+ * cell that is neither a string nor a number. The caller refuses the reference through its own channel,
+ * so a malformed row never throws out of resolution.
+ */
+export declare function snapshotRows(entry: ArtifactSnapshot | undefined): Result<Array<Record<string, string | number>>, string>;
 /**
  * One pinned citation record: the short citation of the paper, and the description that the synthesis
  * gave. The record is the bibliography of a citation key, and the key alone states the membership.
  */
-export interface CitationRecord {
+export type CitationRecord = {
     citation: string;
     description?: string;
-}
+};
 /** The pinned citation records, keyed by the citation key, for example `pmid:12345`. */
 export type CitationRecords = Record<string, CitationRecord>;
 /**
@@ -51,11 +67,11 @@ export type CitationRecords = Record<string, CitationRecord>;
  * membership role, thus a key with no record is a pinned citation and a stored pin with no map reads the
  * same as one that predates the map.
  */
-export interface ReportSnapshot {
+export type ReportSnapshot = {
     artifacts: Record<string, ArtifactSnapshot>;
     citations?: string[];
     citationRecords?: CitationRecords;
-}
+};
 /**
  * The concrete value that a reference resolves to. A scalar comes from one artifact cell or one
  * derivation. A table comes from a whole-table artifact. A file echoes the pin of a whole-file artifact,
@@ -97,10 +113,10 @@ export type ResolvedValue = {
  * `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 {
+export type 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`.
  *