@inflexa-ai/harness 0.18.0 → 0.19.1

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

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

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

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

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

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

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

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

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

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

package/dist/report-model/{mint-snapshot.d.ts → pin-snapshot.d.ts}

@@ -1,30 +1,30 @@
 /**
- * The mint of a report snapshot, which is the membership boundary of one report session.
+ * 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 mint must run at the anchor itself.
+ * 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 mint gave no snapshot. The read of the ledger is the one operation that can
+ * 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 MintSnapshotError = {
+export type PinSnapshotError = {
     kind: "ledger-read-failed";
     cause: unknown;
 };
 /**
- * Mint the snapshot of one analysis from the artifact ledger.
+ * Pin 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
+ * 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 mintReportSnapshot(pool: Querier, analysisId: string): Promise<Result<ReportSnapshot, MintSnapshotError>>;
+export declare function pinReportSnapshot(pool: Querier, analysisId: string): Promise<Result<ReportSnapshot, PinSnapshotError>>;

package/dist/report-model/{mint-snapshot.js → pin-snapshot.js}

@@ -1,23 +1,23 @@
 /**
- * The mint of a report snapshot, which is the membership boundary of one report session.
+ * 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 mint must run at the anchor itself.
+ * 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";
 /**
- * Mint the snapshot of one analysis from the artifact ledger.
+ * Pin 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
+ * 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 mintReportSnapshot(pool, analysisId) {
+export async function pinReportSnapshot(pool, analysisId) {
     let ledgerRows;
     try {
         ledgerRows = await queryAnalysisArtifacts(pool, analysisId);
@@ -33,8 +33,8 @@ export async function mintReportSnapshot(pool, analysisId) {
     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
+    // 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/production-resolver.d.ts

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