@inflexa-ai/harness 0.17.0 → 0.18.0

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,40 @@
+/**
+ * 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 ReportWarning } from "./block-walk.js";
+import { type ReferenceResolver, type ReportSnapshot } from "./reference-resolver.js";
+export type { ReportWarning };
+/** 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[];
+};
+/** 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>;

package/dist/report-model/validate.js

@@ -0,0 +1,80 @@
+/**
+ * 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 { ReportDocumentSchema } from "../contracts/report-blocks.js";
+import { allWithConcurrency } from "../lib/async-utils.js";
+import { walkBlocks } from "./block-walk.js";
+import { columnsHeldByNoRow } from "./reference-resolver.js";
+/**
+ * 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.
+ */
+const RESOLUTION_CONCURRENCY = 8;
+/**
+ * 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.
+ */
+function checkChartEncoding(entry, value) {
+    const encodingColumns = entry.encodingColumns;
+    if (encodingColumns === undefined || encodingColumns.length === 0) {
+        return undefined;
+    }
+    if (value.type !== "table") {
+        return { reference: entry.reference, reason: "locator-out-of-range", detail: `the chart binding resolved to a ${value.type} and not to a table` };
+    }
+    const absent = columnsHeldByNoRow(value.rows, encodingColumns);
+    if (absent.length === 0) {
+        return undefined;
+    }
+    return {
+        reference: entry.reference,
+        reason: "locator-out-of-range",
+        detail: `the encoding names column ${absent.join(", ")}, which the bound table does not hold`,
+    };
+}
+/** Resolve each reference, collect the schema conformance and the resolution outcomes, and warn on prose. */
+export async function validateReport(document, snapshot, resolver) {
+    const parsed = ReportDocumentSchema.safeParse(document);
+    if (!parsed.success) {
+        const schemaIssues = parsed.error.issues.map((issue) => ({
+            path: issue.path.map((segment) => String(segment)).join("."),
+            message: issue.message,
+        }));
+        return { valid: false, schemaIssues, warnings: [] };
+    }
+    const { references, repeatedIds, warnings } = walkBlocks(parsed.data.sections);
+    const resolved = await allWithConcurrency(references.map((entry) => () => resolver.resolve(entry.reference, snapshot).then((result) => ({ entry, result }))), RESOLUTION_CONCURRENCY);
+    // Collect every failure. A reviewer must see each block that broke, thus the walk does not stop at
+    // the first unresolved reference. The `Err` channel carries the unresolved reference itself.
+    const resolutionFailures = [];
+    for (const { entry, result } of resolved) {
+        if (result.isErr()) {
+            resolutionFailures.push({ blockId: entry.blockId, failure: result.error });
+            continue;
+        }
+        const encodingFailure = checkChartEncoding(entry, result.value);
+        if (encodingFailure !== undefined) {
+            resolutionFailures.push({ blockId: entry.blockId, failure: encodingFailure });
+        }
+    }
+    if (repeatedIds.length > 0 || resolutionFailures.length > 0) {
+        return {
+            valid: false,
+            ...(repeatedIds.length > 0 ? { duplicateIds: repeatedIds } : {}),
+            ...(resolutionFailures.length > 0 ? { resolutionFailures } : {}),
+            warnings,
+        };
+    }
+    return { valid: true, warnings };
+}

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

@@ -0,0 +1,33 @@
+/**
+ * The chart derivation of the report page.
+ *
+ * A chart block binds one whole-table artifact and a channel mapping. `deriveChartOption` turns the
+ * chart type, the encoding, and the resolved rows into one ECharts option object. The chart container
+ * markup lives beside this file, and it wraps the option that this derivation gives.
+ *
+ * The renderer computes no aggregate. Each plotted number stays traceable to one cell of the evidence
+ * artifact. A pie or a heatmap arrives one row per category or per cell, thus a repeated category or a
+ * repeated pair is a refusal and not a silent sum.
+ *
+ * The derivation is deterministic. Every object builds in one fixed key order, and the code reads no
+ * clock, no random value, and no locale. A string comparison uses the code-unit order (`<`) and never
+ * `localeCompare`, thus the same rows give the same bytes on every host.
+ */
+import { type Result } from "neverthrow";
+import type { ChartBlock } from "../contracts/report-blocks.js";
+import type { RenderProblem } from "./types.js";
+/** One cell of a resolved row. A cell is one string or one number. */
+type Cell = string | number;
+/** One resolved row of the bound table, keyed by column name. */
+export type ChartRow = Record<string, Cell>;
+/** The derived option object, ready for `normalizeEchartSpec` and the inline JSON. */
+export type EchartOption = Record<string, unknown>;
+/**
+ * Derive the ECharts option for a chart block, then pass it through `normalizeEchartSpec`.
+ *
+ * The normalizer owns the bottom legend, the save action, and the axis-label discipline. Thus the
+ * derivation sets no `title`, no `legend`, no `toolbox`, and no explicit series color. The theme palette
+ * assigns the series colors by their order.
+ */
+export declare function deriveChartOption(block: ChartBlock, rows: readonly ChartRow[], columns?: readonly string[]): Result<EchartOption, RenderProblem>;
+export {};