@inflexa-ai/harness 0.17.0 → 0.18.0

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

@@ -0,0 +1,109 @@
+/**
+ * The read-back surface of a draft.
+ *
+ * The agent holds the outline as its primary view. The outline gives one entry for each block: the id,
+ * the kind, the nesting depth, and a short label. It carries no binding and no full prose. Thus the full
+ * tree stays out of the agent context.
+ *
+ * A read of one block by its id gives the full block. The agent pulls a block only when it needs one. A
+ * section gives its own fields and the ids of its children, and never the subtree. The outline already
+ * names every descendant, thus a subtree here would return the whole tree that the outline exists to keep
+ * out.
+ */
+import { locate } from "./draft-operations.js";
+/** The label keeps a prose head of at most this many code points. A clipped label ends with the marker. */
+const PROSE_CLIP = 80;
+/** The marker that a clipped label ends with. It counts toward `PROSE_CLIP`. */
+const CLIP_MARKER = "…";
+/**
+ * Clip a label to `PROSE_CLIP` code points, and mark a clipped label.
+ *
+ * The cut counts code points and not UTF-16 units, because a cut at a fixed index splits a surrogate pair
+ * whenever an astral character straddles the boundary. A lone surrogate has no UTF-8 encoding, thus the
+ * agent would read a replacement character in place of the character the author wrote.
+ *
+ * A clipped label carries the marker, because a bare head and a whole short label read the same. Without
+ * the marker the agent cannot tell whether the prose ends there, and it acts on a truncated claim as if it
+ * were the whole one.
+ */
+function clip(text) {
+    const points = [...text];
+    if (points.length <= PROSE_CLIP) {
+        return text;
+    }
+    return `${points.slice(0, PROSE_CLIP - CLIP_MARKER.length).join("")}${CLIP_MARKER}`;
+}
+/**
+ * The short label of one block.
+ *
+ * A section, a metric, a table, and a chart give a titled name. A figure and a citation give a caption or
+ * a note. A text and a claim carry prose. Every one of them clips: a caption, a note, and a title are free
+ * prose too, thus an unclipped arm would put a paragraph into each outline that names the block.
+ *
+ * A block with an absent optional field gives an empty label.
+ */
+function labelOf(block) {
+    switch (block.kind) {
+        case "section":
+            return clip(block.title);
+        case "metric":
+            return clip(block.label);
+        case "table":
+            return clip(block.title ?? "");
+        case "chart":
+            return clip(block.title ?? "");
+        case "figure":
+            return clip(block.caption ?? "");
+        case "citation":
+            return clip(block.note ?? "");
+        case "text":
+            return clip(block.content.prose);
+        case "claim":
+            return clip(block.content.prose);
+    }
+}
+/**
+ * Build the outline of a draft. The walk is pre-order, thus the entries follow the document order. A
+ * section comes before its children, and a child sits one depth deeper than its parent.
+ */
+export function buildOutline(draft) {
+    const entries = [];
+    const visit = (block, depth) => {
+        entries.push({ id: block.id, kind: block.kind, depth, label: labelOf(block) });
+        if (block.kind === "section") {
+            for (const child of block.blocks) {
+                visit(child, depth + 1);
+            }
+        }
+    };
+    for (const section of draft.sections) {
+        visit(section, 0);
+    }
+    return entries;
+}
+/**
+ * Build the outline of one container: an entry for each direct child, and nothing deeper.
+ *
+ * A landed operation reports the container that it changed, and the whole outline would grow the context
+ * by the size of the draft on every call. The child order is what the agent cannot know on its own, and a
+ * descendant did not move, thus one level answers the question that a landing raises.
+ *
+ * `depth` is the depth of the children, thus the entries read the same as the entries of a full outline.
+ */
+export function childOutline(blocks, depth) {
+    return blocks.map((block) => ({ id: block.id, kind: block.kind, depth, label: labelOf(block) }));
+}
+/**
+ * Read one block by its id. An atom gives the block as it is, with its bindings. A section gives its own
+ * fields and the id of each child. A block that no id holds gives `undefined`.
+ */
+export function readBlock(draft, id) {
+    const found = locate(draft, id)?.block;
+    if (found === undefined) {
+        return undefined;
+    }
+    if (found.kind === "section") {
+        return { kind: "section", id: found.id, title: found.title, childIds: found.blocks.map((child) => child.id) };
+    }
+    return found;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * The draft grammar of a report document under composition.
+ *
+ * An edit refuses what is wrong, and the finish refuses what is missing. Thus a draft permits emptiness,
+ * and the contract does not. The draft admits an empty section list and an empty section, and the
+ * completeness rules of `ReportDocumentSchema` gate one time, at the finish.
+ *
+ * The grammar composes from the contract atoms, and it does not copy them. The draft spreads
+ * `ATOM_BLOCK_SCHEMAS`, and the relaxed section is the only new part. Thus a ninth block kind reaches the
+ * draft the moment that the contract declares it, and the draft never drifts from the contract.
+ *
+ * The recursion mirrors `SectionBlockSchema`. The `blocks` field is a `z.lazy` and not a getter. Thus the
+ * discriminated union reads the `kind` discriminator at construction time, and it needs no reference to
+ * `DraftBlockSchema` before it exists. The relaxed rule holds at every depth, because a nested section is
+ * a `DraftSectionBlock` too.
+ */
+import { z } from "zod";
+import { type AtomBlock } from "../contracts/report-blocks.js";
+/**
+ * The draft section shape as a plain type. TypeScript cannot infer the block tree through the union
+ * cycle, thus the recursive members carry an explicit type. `DraftSectionBlock` and `DraftBlock` break
+ * the cycle.
+ */
+export interface DraftSectionBlock {
+    kind: "section";
+    id: string;
+    title: string;
+    blocks: DraftBlock[];
+}
+/** One draft block of any of the eight kinds. The atoms keep the contract shape, and only the section relaxes. */
+export type DraftBlock = AtomBlock | DraftSectionBlock;
+/** A draft section permits zero child blocks, thus an empty section is a legal draft state. */
+export declare const DraftSectionBlockSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"section">;
+    id: z.ZodString;
+    title: z.ZodString;
+    blocks: z.ZodLazy<z.ZodArray<z.ZodType<DraftBlock, unknown, z.core.$ZodTypeInternals<DraftBlock, unknown>>>>;
+}, z.core.$strict>;
+/** The draft block union. A `z.ZodType<DraftBlock>` annotation gives the recursive members a stable type. */
+export declare const DraftBlockSchema: z.ZodType<DraftBlock>;
+/** The root of a draft. It permits zero sections, thus an empty draft is a legal state. */
+export declare const DraftDocumentSchema: z.ZodObject<{
+    title: z.ZodString;
+    sections: z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"section">;
+        id: z.ZodString;
+        title: z.ZodString;
+        blocks: z.ZodLazy<z.ZodArray<z.ZodType<DraftBlock, unknown, z.core.$ZodTypeInternals<DraftBlock, unknown>>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type DraftDocument = z.infer<typeof DraftDocumentSchema>;

package/dist/report-model/draft.js

@@ -0,0 +1,32 @@
+/**
+ * The draft grammar of a report document under composition.
+ *
+ * An edit refuses what is wrong, and the finish refuses what is missing. Thus a draft permits emptiness,
+ * and the contract does not. The draft admits an empty section list and an empty section, and the
+ * completeness rules of `ReportDocumentSchema` gate one time, at the finish.
+ *
+ * The grammar composes from the contract atoms, and it does not copy them. The draft spreads
+ * `ATOM_BLOCK_SCHEMAS`, and the relaxed section is the only new part. Thus a ninth block kind reaches the
+ * draft the moment that the contract declares it, and the draft never drifts from the contract.
+ *
+ * The recursion mirrors `SectionBlockSchema`. The `blocks` field is a `z.lazy` and not a getter. Thus the
+ * discriminated union reads the `kind` discriminator at construction time, and it needs no reference to
+ * `DraftBlockSchema` before it exists. The relaxed rule holds at every depth, because a nested section is
+ * a `DraftSectionBlock` too.
+ */
+import { z } from "zod";
+import { ATOM_BLOCK_SCHEMAS } from "../contracts/report-blocks.js";
+/** A draft section permits zero child blocks, thus an empty section is a legal draft state. */
+export const DraftSectionBlockSchema = z.strictObject({
+    kind: z.literal("section"),
+    id: z.string().min(1),
+    title: z.string(),
+    blocks: z.lazy(() => z.array(DraftBlockSchema)),
+});
+/** 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]);
+/** 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(),
+    sections: z.array(DraftSectionBlockSchema),
+});

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

@@ -0,0 +1,8 @@
+/**
+ * A local, in-memory realization of the reference resolver. It reads only the snapshot that it is given,
+ * thus it needs no storage and no network. A test and a benchmark use it to exercise the resolution and
+ * assertion rules without a host.
+ */
+import { type ReferenceResolver } from "./reference-resolver.js";
+/** Make a resolver that reads only the snapshot. It holds no state, thus one instance serves every call. */
+export declare function createFixtureResolver(): ReferenceResolver;

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

@@ -0,0 +1,252 @@
+/**
+ * A local, in-memory realization of the reference resolver. It reads only the snapshot that it is given,
+ * thus it needs no storage and no network. A test and a benchmark use it to exercise the resolution and
+ * assertion rules without a host.
+ */
+import { err, ok } from "neverthrow";
+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 };
+    return err(failure);
+}
+/** A short account of a derivation input, for a detail that names which input broke the arithmetic. */
+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) {
+        return fail(reference, "artifact-missing", `no artifact at ${reference.path}`);
+    }
+    if (artifact.hash !== reference.hash) {
+        return fail(reference, "hash-mismatch", `expected ${reference.hash} but the artifact hash is ${artifact.hash}`);
+    }
+    // A caller supplies the rows of a fixture. A fixture that supplies rows for a figure would resolve a
+    // 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`);
+    }
+    // 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 locator = reference.locator;
+    let selectedRow;
+    if (locator.row !== undefined) {
+        if (locator.row < 0 || locator.row >= rows.length) {
+            return fail(reference, "locator-out-of-range", `row ${locator.row} is outside the ${rows.length} rows`);
+        }
+        selectedRow = rows[locator.row];
+    }
+    else if (locator.rowFilter !== undefined) {
+        const filter = locator.rowFilter;
+        const matches = rows.filter((row) => 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)}`);
+        }
+        if (matches.length > 1) {
+            return fail(reference, "ambiguous-match", `${matches.length} rows where ${filter.column} equals ${String(filter.value)}`);
+        }
+        selectedRow = matches[0];
+    }
+    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.
+    const cell = selectedRow[locator.column];
+    if (cell === undefined || cell === null) {
+        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 });
+}
+function resolveArtifactTable(reference, snapshot) {
+    const artifact = snapshotEntry(snapshot, reference.path);
+    if (artifact === undefined) {
+        return fail(reference, "artifact-missing", `no artifact at ${reference.path}`);
+    }
+    if (artifact.hash !== reference.hash) {
+        return fail(reference, "hash-mismatch", `expected ${reference.hash} but the artifact hash is ${artifact.hash}`);
+    }
+    const tableFileType = artifact.fileType;
+    if (fileTypeHoldsNoCell(tableFileType)) {
+        return fail(reference, "unreadable-artifact", `the ${tableFileType} at ${reference.path} holds no cell to read`);
+    }
+    const rows = artifact.rows ?? [];
+    const columns = reference.columns;
+    if (columns === undefined) {
+        return ok({ type: "table", rows });
+    }
+    // A name that no row holds addresses nothing. Without this check a projection onto an invented column
+    // gives an empty cell for each row and still resolves, which is the fabrication that grounding exists
+    // to reject.
+    const absent = columnsHeldByNoRow(rows, columns);
+    if (absent.length > 0) {
+        return fail(reference, "locator-out-of-range", `the table at ${reference.path} holds no column ${absent.join(", ")}`);
+    }
+    // Project each row onto the requested columns. A table tolerates a ragged row, thus a column that a
+    // given row lacks is left out of that row and is not a failure.
+    const projectedRows = rows.map((row) => {
+        const projected = {};
+        for (const column of columns) {
+            if (column in row) {
+                projected[column] = row[column];
+            }
+        }
+        return projected;
+    });
+    return ok({ type: "table", rows: projectedRows, columns });
+}
+function resolveArtifactFile(reference, snapshot) {
+    const artifact = snapshotEntry(snapshot, reference.path);
+    if (artifact === undefined) {
+        return fail(reference, "artifact-missing", `no artifact at ${reference.path}`);
+    }
+    if (artifact.hash !== reference.hash) {
+        return fail(reference, "hash-mismatch", `expected ${reference.hash} but the artifact hash is ${artifact.hash}`);
+    }
+    return ok({ type: "file", path: reference.path, hash: artifact.hash });
+}
+async function resolveDerivation(reference, snapshot) {
+    const numbers = [];
+    for (const input of reference.inputs) {
+        const inputResult = await resolve(input, snapshot);
+        if (inputResult.isErr()) {
+            // Keep the inner reason so a reviewer sees the real cause, for example a missing artifact under
+            // the derivation. The derivation itself did not fail on its own terms.
+            return fail(reference, inputResult.error.reason, inputResult.error.detail);
+        }
+        const resolved = inputResult.value;
+        const numeric = resolved.type === "scalar" ? asFiniteNumber(resolved.value) : undefined;
+        if (numeric === undefined) {
+            // The arithmetic needs a finite number. A cell that holds text does not address a usable
+            // scalar, thus the closest reason is that the coordinate is out of range.
+            return fail(reference, "locator-out-of-range", `input ${describeReference(input)} did not resolve to a finite number`);
+        }
+        numbers.push(numeric);
+    }
+    const a = numbers[0];
+    const b = numbers[1];
+    let result;
+    switch (reference.op) {
+        case "ratio":
+            result = a / b;
+            break;
+        case "delta":
+            result = a - b;
+            break;
+        case "pctChange":
+            // A fraction, not a percent. A change of one half gives 0.5, thus an author asserts 0.5 and a
+            // `unit` of `%` only tells a renderer how to show it.
+            result = (a - b) / b;
+            break;
+    }
+    if (!Number.isFinite(result)) {
+        return fail(reference, "locator-out-of-range", `operation ${reference.op} does not yield a finite value, because the divisor is zero`);
+    }
+    const valueFailure = checkValueAssertion(reference, reference.assert?.value, reference.assert?.tolerance, result);
+    return valueFailure !== undefined ? err(valueFailure) : ok({ type: "scalar", value: result });
+}
+function resolveCitation(reference, snapshot) {
+    const key = `${reference.idKind}:${reference.id}`;
+    if (snapshot.citations === undefined || !snapshot.citations.includes(key)) {
+        return fail(reference, "artifact-missing", `the citation ${key} is not in the pinned evidence`);
+    }
+    const value = { type: "citation", id: key };
+    const citationFailure = checkCitationAssertion(reference, reference.assert?.value, key);
+    return citationFailure !== undefined ? err(citationFailure) : ok(value);
+}
+async function resolve(reference, snapshot) {
+    switch (reference.kind) {
+        case "artifact-value":
+            return resolveArtifactValue(reference, snapshot);
+        case "artifact-table":
+            return resolveArtifactTable(reference, snapshot);
+        case "artifact-file":
+            return resolveArtifactFile(reference, snapshot);
+        case "derivation":
+            return resolveDerivation(reference, snapshot);
+        case "citation":
+            return resolveCitation(reference, snapshot);
+    }
+}
+/** Make a resolver that reads only the snapshot. It holds no state, thus one instance serves every call. */
+export function createFixtureResolver() {
+    return { resolve };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * The mint of a report snapshot, which is the membership boundary of one report session.
+ *
+ * A report session freezes at one moment, and the analysis continues after that anchor. The snapshot
+ * states which artifacts existed at the anchor, and that is a question that no other record answers.
+ * Thus a session never cites an artifact that a later run produced.
+ *
+ * The artifact ledger holds one row for each path, and it keeps no history. Thus the set at a past
+ * moment is not recoverable later, and the mint must run at the anchor itself.
+ */
+import { type Result } from "neverthrow";
+import type { Querier } from "../state/db.js";
+import type { ReportSnapshot } from "./reference-resolver.js";
+/**
+ * The reason that the mint gave no snapshot. The read of the ledger is the one operation that can
+ * fail. An analysis with no registered artifact is a normal answer, thus absence is not a member of
+ * this set. `cause` carries the underlying fault for a log.
+ */
+export type MintSnapshotError = {
+    kind: "ledger-read-failed";
+    cause: unknown;
+};
+/**
+ * Mint the snapshot of one analysis from the artifact ledger.
+ *
+ * The mint copies no cell and no byte. An entry pins identity alone, thus the snapshot grows with the
+ * count of artifacts and never with the size of the data. A read of an artifact belongs to the value
+ * tier, which runs one time for each report version.
+ */
+export declare function mintReportSnapshot(pool: Querier, analysisId: string): Promise<Result<ReportSnapshot, MintSnapshotError>>;

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

@@ -0,0 +1,40 @@
+/**
+ * The mint of a report snapshot, which is the membership boundary of one report session.
+ *
+ * A report session freezes at one moment, and the analysis continues after that anchor. The snapshot
+ * states which artifacts existed at the anchor, and that is a question that no other record answers.
+ * Thus a session never cites an artifact that a later run produced.
+ *
+ * The artifact ledger holds one row for each path, and it keeps no history. Thus the set at a past
+ * moment is not recoverable later, and the mint must run at the anchor itself.
+ */
+import { err, ok } from "neverthrow";
+import { queryAnalysisArtifacts } from "../state/artifacts.js";
+/**
+ * Mint the snapshot of one analysis from the artifact ledger.
+ *
+ * The mint copies no cell and no byte. An entry pins identity alone, thus the snapshot grows with the
+ * count of artifacts and never with the size of the data. A read of an artifact belongs to the value
+ * tier, which runs one time for each report version.
+ */
+export async function mintReportSnapshot(pool, analysisId) {
+    let ledgerRows;
+    try {
+        ledgerRows = await queryAnalysisArtifacts(pool, analysisId);
+    }
+    catch (cause) {
+        // The query speaks the throw protocol of the `pg` driver. This is the thin wrapper that turns
+        // that throw into a value, thus each caller above reads a failure as data.
+        return err({ kind: "ledger-read-failed", 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);
+    for (const row of ledgerRows) {
+        artifacts[row.path] = { hash: row.hash, fileType: row.fileType };
+    }
+    // The mint fills no citation. No store holds the citation ids of an analysis, and validation
+    // matches a citation against the external authorities and never against a minted list. Thus such
+    // a list would state nothing that a later read consumes.
+    return ok({ artifacts });
+}

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

@@ -0,0 +1,113 @@
+/**
+ * The seam that turns a report reference into a concrete value, and the value model that it gives back.
+ *
+ * A reference is authored belief. A resolver reads the pinned evidence and gives the value that the
+ * 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 { Reference, UnresolvedReference } from "../contracts/report-reference.js";
+/**
+ * One pinned artifact: its content hash, and its rows as plain cells.
+ *
+ * A cell is a string or a number, because a realization gives back whatever its store holds. A
+ * text-backed artifact such as a CSV gives a numeric column as a string. Thus a realization is free to
+ * skip a type inference pass, and resolution compares a numeral by its numeric value and never by its
+ * JavaScript type.
+ *
+ * `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
+ * mint never populates `rows`. `rows` serves the fixture realization only, and that realization resolves
+ * from the snapshot itself. A production snapshot pins identity, and a value comes from a read of the
+ * artifact.
+ *
+ * `fileType` states a role, and it does not state a data format. `inferArtifactType` in
+ * `src/schemas/artifact-manifest.ts` gives each value that the ledger holds, and the values are
+ * `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 {
+    hash: string;
+    fileType?: string | null;
+    rows?: Array<Record<string, string | number>>;
+}
+/**
+ * The pinned evidence that a resolver reads. The `artifacts` map is keyed by the analysis-relative path,
+ * the same path that an artifact reference names and the same key as `cortex_artifacts.path`. That path
+ * is unique across the analysis, thus one map holds the artifacts of every run without a collision.
+ * `citations` holds each known external id as an `idKind:id` string, for example `pmid:12345`.
+ */
+export interface ReportSnapshot {
+    artifacts: Record<string, ArtifactSnapshot>;
+    citations?: string[];
+}
+/**
+ * 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,
+ * for example an image. A citation echo confirms that an external id is in the pinned evidence.
+ */
+export type ResolvedValue = {
+    type: "scalar";
+    value: string | number;
+} | {
+    type: "table";
+    rows: Array<Record<string, string | number>>;
+    columns?: string[];
+} | {
+    type: "file";
+    path: string;
+    hash: string;
+} | {
+    type: "citation";
+    id: string;
+};
+/**
+ * The capability seam that resolves one reference against a snapshot.
+ *
+ * The method is async because a production realization reads storage. A synchronous signature would
+ * force a local realization onto every host, thus the seam stays async even when a realization is
+ * in-memory.
+ *
+ * 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.
+ */
+export interface ReferenceResolver {
+    resolve(reference: Reference, snapshot: ReportSnapshot): Promise<Result<ResolvedValue, UnresolvedReference>>;
+}
+/**
+ * Give back each name in `columns` that no row holds, in the order of `columns`.
+ *
+ * A table tolerates a ragged row, thus a column that only some rows hold is present. A column that no
+ * row holds is a name that addresses nothing, and it is the difference between a sparse table and a
+ * column that does not exist.
+ *
+ * A table with no rows gives back nothing. There is no evidence to contradict any name, and an empty
+ * result table is a real scientific outcome that must not fail for the shape of its emptiness.
+ */
+export declare function columnsHeldByNoRow(rows: Array<Record<string, string | number>>, columns: readonly string[]): string[];
+/**
+ * Give back `true` for a file type that holds no cell for a reference to address.
+ *
+ * The file type states a role, and it does not state a data format. Thus the rule runs one way only. It
+ * refuses a kind, and it never confirms one. An `output` gives back `false`, because it covers a table and
+ * an image alike. Only a read of the artifact settles which one it is. An absent file type gives back
+ * `false` for the same reason.
+ *
+ * The structural tier and a resolver both read this one predicate. Thus the two tiers can never disagree
+ * about one reference.
+ */
+export declare function fileTypeHoldsNoCell(fileType: string | null | undefined): boolean;
+/**
+ * Give back the snapshot entry at `path`, or `undefined` when the map holds no such own key.
+ *
+ * An agent authors a report reference, thus the path is untrusted text. The `artifacts` map can be a
+ * plain object: a fixture literal, or a `JSON.parse` of a stored snapshot. A bracket lookup on a plain
+ * object with a path such as `constructor` finds an inherited member. Then the refusal reads
+ * `hash-mismatch`, but the true answer is `artifact-missing`. The `Object.hasOwn` guard admits an own
+ * key only, thus an inherited member reads as absent.
+ *
+ * The structural tier and the fixture resolver both read this one lookup. Thus the two tiers can never
+ * disagree about membership.
+ */
+export declare function snapshotEntry(snapshot: ReportSnapshot, path: string): ArtifactSnapshot | undefined;