@inflexa-ai/harness 0.19.0 → 0.19.2

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/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;