@inflexa-ai/harness 0.17.0 → 0.19.0

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/pin-snapshot.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The pin 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 pin 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 pin 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 PinSnapshotError = {
+    kind: "ledger-read-failed";
+    cause: unknown;
+};
+/**
+ * Pin the snapshot of one analysis from the artifact ledger.
+ *
+ * The pin 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 pinReportSnapshot(pool: Querier, analysisId: string): Promise<Result<ReportSnapshot, PinSnapshotError>>;

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

@@ -0,0 +1,40 @@
+/**
+ * The pin 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 pin must run at the anchor itself.
+ */
+import { err, ok } from "neverthrow";
+import { queryAnalysisArtifacts } from "../state/artifacts.js";
+/**
+ * Pin the snapshot of one analysis from the artifact ledger.
+ *
+ * The pin 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 pinReportSnapshot(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 pin 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 pinned 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
+ * pin 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;

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

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function columnsHeldByNoRow(rows, columns) {
+    if (rows.length === 0) {
+        return [];
+    }
+    return columns.filter((column) => !rows.some((row) => column in row));
+}
+/**
+ * The file type of an entry that holds no cell for a reference to address.
+ *
+ * The `satisfies` clause ties each literal to a member of `ArtifactType`. A renamed member of
+ * `ArtifactType` becomes a compile error here. A new member passes with no error, because the rule
+ * refuses a kind and never confirms one.
+ */
+const FILE_TYPES_WITH_NO_CELL = new Set(["figure", "script", "log", "notebook"]);
+/**
+ * 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 function fileTypeHoldsNoCell(fileType) {
+    return fileType !== undefined && fileType !== null && FILE_TYPES_WITH_NO_CELL.has(fileType);
+}
+/**
+ * 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 function snapshotEntry(snapshot, path) {
+    return Object.hasOwn(snapshot.artifacts, path) ? snapshot.artifacts[path] : undefined;
+}

package/dist/report-model/structural-validation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The structural tier of reference resolution.
+ *
+ * The tier answers from the pinned snapshot alone, and it opens no file. Thus an authoring operation can
+ * run it on each change, and it stays instant while a document grows.
+ *
+ * The value tier gives the value that a reference points at, and only a read of the artifact gives that
+ * value. As a result the costly read happens one time for each report version, and never for each edit.
+ */
+import { type Result } from "neverthrow";
+import type { Reference, UnresolvedReference } from "../contracts/report-reference.js";
+import { type ReportSnapshot } from "./reference-resolver.js";
+/**
+ * Validate one reference against the snapshot.
+ *
+ * The `Ok` channel carries no value. The tier answers membership, identity, and the file type, and a
+ * value comes from a read of the artifact. An `assert` is the authored belief about that value, thus this
+ * tier matches no assertion and a reference that carries one passes on its pin alone.
+ *
+ * The answer is synchronous, because the snapshot is already in memory.
+ */
+export declare function validateReferenceStructure(reference: Reference, snapshot: ReportSnapshot): Result<void, UnresolvedReference>;

package/dist/report-model/structural-validation.js

@@ -0,0 +1,68 @@
+/**
+ * The structural tier of reference resolution.
+ *
+ * The tier answers from the pinned snapshot alone, and it opens no file. Thus an authoring operation can
+ * run it on each change, and it stays instant while a document grows.
+ *
+ * The value tier gives the value that a reference points at, and only a read of the artifact gives that
+ * value. As a result the costly read happens one time for each report version, and never for each edit.
+ */
+import { err, ok } from "neverthrow";
+import { fileTypeHoldsNoCell, snapshotEntry } 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 };
+    return err(failure);
+}
+/** Validate the artifact pin of one reference: its membership in the snapshot, its identity, and the file type of its entry. */
+function validatePin(reference, snapshot) {
+    const entry = snapshotEntry(snapshot, reference.path);
+    if (entry === undefined) {
+        return fail(reference, "artifact-missing", `no artifact at ${reference.path}`);
+    }
+    if (entry.hash !== reference.hash) {
+        return fail(reference, "hash-mismatch", `expected ${reference.hash} but the artifact hash is ${entry.hash}`);
+    }
+    // An `artifact-file` pins the bytes of a whole file, thus each file type is valid for it. A figure
+    // block binds through `artifact-file`, and a rule that refused a `figure` here would fail each figure
+    // of each report.
+    const readsACell = reference.kind === "artifact-value" || reference.kind === "artifact-table";
+    const fileType = entry.fileType;
+    if (readsACell && fileTypeHoldsNoCell(fileType)) {
+        return fail(reference, "unreadable-artifact", `the ${fileType} at ${reference.path} holds no cell to read`);
+    }
+    return ok();
+}
+/**
+ * Validate one reference against the snapshot.
+ *
+ * The `Ok` channel carries no value. The tier answers membership, identity, and the file type, and a
+ * value comes from a read of the artifact. An `assert` is the authored belief about that value, thus this
+ * tier matches no assertion and a reference that carries one passes on its pin alone.
+ *
+ * The answer is synchronous, because the snapshot is already in memory.
+ */
+export function validateReferenceStructure(reference, snapshot) {
+    switch (reference.kind) {
+        case "artifact-value":
+        case "artifact-table":
+        case "artifact-file":
+            return validatePin(reference, snapshot);
+        case "derivation": {
+            // A derivation holds no pin of its own, thus it is grounded exactly when both of its inputs
+            // are grounded. The failure keeps the reason of the input, because the derivation itself did
+            // not fail on its own terms.
+            for (const input of reference.inputs) {
+                const inputResult = validatePin(input, snapshot);
+                if (inputResult.isErr()) {
+                    return fail(reference, inputResult.error.reason, inputResult.error.detail);
+                }
+            }
+            return ok();
+        }
+        case "citation":
+            // A citation holds an external id and no path, thus the snapshot has nothing to say about it.
+            // The citation authorities settle its truth at the value tier.
+            return ok();
+    }
+}

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

@@ -0,0 +1,72 @@
+/**
+ * The mechanical validator of a report document.
+ *
+ * The schemas already carry the grammar: a strict object rejects a forbidden field, a binding is present
+ * by construction, and a metric value slot admits one scalar reference only. Thus a schema parse failure
+ * is the grammar rejection, and the validator does not re-implement it. The validator adds the three
+ * checks that a schema cannot make: it makes sure that each block id occurs one time only, it resolves
+ * each reference against the pinned evidence, and it warns about a free numeral in prose.
+ */
+import type { UnresolvedReference } from "../contracts/report-reference.js";
+import { type AnyBlock, type CollectedReference, type ReportWarning } from "./block-walk.js";
+import { type ReferenceResolver, type ReportSnapshot, type ResolvedValue } from "./reference-resolver.js";
+export type { ReportWarning };
+/**
+ * The cap on how many references resolve at the same time.
+ *
+ * A production resolver reads storage for each reference, and a large report holds hundreds of them. An
+ * unbounded fan-out would open one read for each reference at the same moment.
+ */
+export declare const RESOLUTION_CONCURRENCY = 8;
+/** One schema conformance problem, reduced to a path and a message. */
+export interface SchemaIssue {
+    path: string;
+    message: string;
+}
+/** One reference that did not resolve, tied to the block that carries it. */
+export interface ResolutionFailure {
+    blockId: string;
+    failure: UnresolvedReference;
+}
+/**
+ * The result of validation. `valid` is false when the schema failed, a block id repeats, or a reference
+ * did not resolve. `duplicateIds` names each repeated id one time, in sorted order. The warnings ride
+ * along in either case.
+ */
+export type ReportValidation = {
+    valid: true;
+    warnings: ReportWarning[];
+} | {
+    valid: false;
+    schemaIssues?: SchemaIssue[];
+    duplicateIds?: string[];
+    resolutionFailures?: ResolutionFailure[];
+    warnings: ReportWarning[];
+};
+/**
+ * Match each column that a chart encoding names against the table that its binding resolved to.
+ *
+ * The binding schema admits a table reference only, thus a resolved value of another type means that the
+ * bound resolver broke its own contract. That is reported and never ignored, because a chart with no
+ * table behind it renders nothing and a silent skip would pass it as grounded.
+ */
+export declare function checkChartEncoding(entry: CollectedReference, value: ResolvedValue): UnresolvedReference | undefined;
+/** The resolved values and the failures of one resolution pass over the references of a block tree. */
+export interface ReferenceResolution {
+    /** The resolved value of each block whose reference resolved, keyed by its block id. */
+    resolvedByBlock: Map<string, ResolvedValue>;
+    /** Each reference that did not resolve, or whose chart encoding named an absent column. */
+    failures: ResolutionFailure[];
+}
+/**
+ * Resolve each reference of a block tree under the concurrency bound, and run the chart-encoding match.
+ *
+ * The walk collects each reference one time, `allWithConcurrency` bounds the fan-out, and
+ * `checkChartEncoding` catches a chart that plots a column which the bound table does not hold. The record
+ * gate and the preview share this one pass, thus the two refuse the same references. A value-bearing block
+ * whose reference resolved carries its value in the map. A claim or a citation reference reads no value
+ * from the map. The walk collects every failure, thus a reviewer sees each block that broke.
+ */
+export declare function resolveDocumentReferences(sections: readonly AnyBlock[], snapshot: ReportSnapshot, resolver: ReferenceResolver): Promise<ReferenceResolution>;
+/** Resolve each reference, collect the schema conformance and the resolution outcomes, and warn on prose. */
+export declare function validateReport(document: unknown, snapshot: ReportSnapshot, resolver: ReferenceResolver): Promise<ReportValidation>;