@inflexa-ai/harness 0.17.0 → 0.18.0

package/dist/contracts/report-reference.d.ts

@@ -0,0 +1,459 @@
+/**
+ * A reference binds a report block to the evidence that justifies it. It is the one canonical way a
+ * block points at a value, a table, a derived quantity, or an external source.
+ *
+ * The reference lives here, in `contracts/`, because a consumer reads it back after a run. The consumer
+ * imports this module without the harness's own dependencies, thus it holds a reference as plain data.
+ *
+ * Resolution reads the evidence again at render time. The `assert` field is the authored belief, and
+ * the resolver matches the fresh read against it.
+ */
+import { type Result } from "neverthrow";
+import { z } from "zod";
+/**
+ * A reference to one scalar value inside an artifact, addressed by a locator. It resolves to a scalar,
+ * thus it carries the value assert.
+ */
+export declare const ArtifactValueReferenceSchema: z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    locator: z.ZodObject<{
+        column: z.ZodString;
+        rowFilter: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            op: z.ZodLiteral<"eq">;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        }, z.core.$strict>>;
+        row: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    assert: z.ZodOptional<z.ZodObject<{
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        tolerance: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    run: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    hash: z.ZodString;
+    snapshot: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"artifact-value">;
+}, z.core.$strict>;
+/**
+ * A reference to a whole table artifact. It carries no locator, because it binds every row.
+ *
+ * It carries no assert. A table is not one value, thus the only belief that an author can hold about it
+ * is its bytes, and the pinned `hash` already carries that belief.
+ */
+export declare const ArtifactTableReferenceSchema: z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    run: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    hash: z.ZodString;
+    snapshot: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"artifact-table">;
+}, z.core.$strict>;
+/**
+ * A reference to a whole artifact file, for example an image. It carries no locator and no columns,
+ * because a file is pinned whole and has no addressable cell inside it. It carries no assert, for the
+ * same reason as a table reference.
+ */
+export declare const ArtifactFileReferenceSchema: z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    run: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    hash: z.ZodString;
+    snapshot: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"artifact-file">;
+}, z.core.$strict>;
+/**
+ * A reference to an external source, addressed by an external identifier. It resolves to the prefixed
+ * key, thus its assert compares against that key and carries no hash.
+ */
+export declare const CitationReferenceSchema: z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"citation">;
+    idKind: z.ZodEnum<{
+        doi: "doi";
+        pmid: "pmid";
+        arxiv: "arxiv";
+    }>;
+    id: z.ZodString;
+    raw: z.ZodString;
+    assert: z.ZodOptional<z.ZodObject<{
+        value: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * The one reference kind that a derivation can consume.
+ *
+ * The arithmetic needs a scalar, and `artifact-value` is the only reference that resolves to one without
+ * itself being a derivation. A table, a file, and a citation resolve to something else, thus each is
+ * unrepresentable here rather than a parse that succeeds and then always fails at resolution. A
+ * derivation is out of the set too, thus a derivation over a derivation stays unrepresentable.
+ */
+export declare const DerivationInputReferenceSchema: z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    locator: z.ZodObject<{
+        column: z.ZodString;
+        rowFilter: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            op: z.ZodLiteral<"eq">;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        }, z.core.$strict>>;
+        row: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    assert: z.ZodOptional<z.ZodObject<{
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        tolerance: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    run: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    hash: z.ZodString;
+    snapshot: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"artifact-value">;
+}, z.core.$strict>;
+/**
+ * A reference to a value computed from other references. Each of the three operations takes two inputs,
+ * thus `inputs` holds exactly two scalar-resolving references and no other count is representable. The
+ * result is computed and not artifact-backed, thus its assert carries the value fields only.
+ */
+export declare const DerivationReferenceSchema: z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"derivation">;
+    op: z.ZodEnum<{
+        ratio: "ratio";
+        delta: "delta";
+        pctChange: "pctChange";
+    }>;
+    inputs: z.ZodArray<z.ZodObject<{
+        unit: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodString>;
+        locator: z.ZodObject<{
+            column: z.ZodString;
+            rowFilter: z.ZodOptional<z.ZodObject<{
+                column: z.ZodString;
+                op: z.ZodLiteral<"eq">;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            }, z.core.$strict>>;
+            row: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        assert: z.ZodOptional<z.ZodObject<{
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            tolerance: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        run: z.ZodOptional<z.ZodString>;
+        path: z.ZodString;
+        hash: z.ZodString;
+        snapshot: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"artifact-value">;
+    }, z.core.$strict>>;
+    assert: z.ZodOptional<z.ZodObject<{
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        tolerance: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** The full reference union. A block binds to one of these. */
+export declare const ReferenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    locator: z.ZodObject<{
+        column: z.ZodString;
+        rowFilter: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            op: z.ZodLiteral<"eq">;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        }, z.core.$strict>>;
+        row: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    assert: z.ZodOptional<z.ZodObject<{
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        tolerance: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    run: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    hash: z.ZodString;
+    snapshot: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"artifact-value">;
+}, z.core.$strict>, z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    run: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    hash: z.ZodString;
+    snapshot: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"artifact-table">;
+}, z.core.$strict>, z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    run: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    hash: z.ZodString;
+    snapshot: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"artifact-file">;
+}, z.core.$strict>, z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"derivation">;
+    op: z.ZodEnum<{
+        ratio: "ratio";
+        delta: "delta";
+        pctChange: "pctChange";
+    }>;
+    inputs: z.ZodArray<z.ZodObject<{
+        unit: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodString>;
+        locator: z.ZodObject<{
+            column: z.ZodString;
+            rowFilter: z.ZodOptional<z.ZodObject<{
+                column: z.ZodString;
+                op: z.ZodLiteral<"eq">;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            }, z.core.$strict>>;
+            row: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        assert: z.ZodOptional<z.ZodObject<{
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            tolerance: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        run: z.ZodOptional<z.ZodString>;
+        path: z.ZodString;
+        hash: z.ZodString;
+        snapshot: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"artifact-value">;
+    }, z.core.$strict>>;
+    assert: z.ZodOptional<z.ZodObject<{
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        tolerance: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"citation">;
+    idKind: z.ZodEnum<{
+        doi: "doi";
+        pmid: "pmid";
+        arxiv: "arxiv";
+    }>;
+    id: z.ZodString;
+    raw: z.ZodString;
+    assert: z.ZodOptional<z.ZodObject<{
+        value: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "kind">;
+/**
+ * The references that resolve to one scalar value. A metric's value slot admits only these, thus no
+ * numeric literal can sit in the slot: the type admits a reference only.
+ */
+export declare const ScalarReferenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    locator: z.ZodObject<{
+        column: z.ZodString;
+        rowFilter: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            op: z.ZodLiteral<"eq">;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        }, z.core.$strict>>;
+        row: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    assert: z.ZodOptional<z.ZodObject<{
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        tolerance: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    run: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    hash: z.ZodString;
+    snapshot: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"artifact-value">;
+}, z.core.$strict>, z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+    kind: z.ZodLiteral<"derivation">;
+    op: z.ZodEnum<{
+        ratio: "ratio";
+        delta: "delta";
+        pctChange: "pctChange";
+    }>;
+    inputs: z.ZodArray<z.ZodObject<{
+        unit: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodString>;
+        locator: z.ZodObject<{
+            column: z.ZodString;
+            rowFilter: z.ZodOptional<z.ZodObject<{
+                column: z.ZodString;
+                op: z.ZodLiteral<"eq">;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            }, z.core.$strict>>;
+            row: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        assert: z.ZodOptional<z.ZodObject<{
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            tolerance: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        run: z.ZodOptional<z.ZodString>;
+        path: z.ZodString;
+        hash: z.ZodString;
+        snapshot: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"artifact-value">;
+    }, z.core.$strict>>;
+    assert: z.ZodOptional<z.ZodObject<{
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        tolerance: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "kind">;
+/**
+ * The reason that a reference did not resolve.
+ *
+ * Two of the reasons are easy to confuse. `artifact-missing` means that the snapshot holds no entry for
+ * the path. `unreadable-artifact` means that the entry exists, and that the resolver cannot read the
+ * artifact as a table. Two conditions give the second reason. The file type refuses a read of a cell, or
+ * the bytes are unrecoverable.
+ */
+export declare const UnresolvedReasonSchema: z.ZodEnum<{
+    "artifact-missing": "artifact-missing";
+    "hash-mismatch": "hash-mismatch";
+    "locator-out-of-range": "locator-out-of-range";
+    "ambiguous-match": "ambiguous-match";
+    "assertion-failed": "assertion-failed";
+    "unreadable-artifact": "unreadable-artifact";
+}>;
+/** A reference that resolution could not bind, with the reason and an optional detail. */
+export declare const UnresolvedReferenceSchema: z.ZodObject<{
+    reference: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        unit: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodString>;
+        locator: z.ZodObject<{
+            column: z.ZodString;
+            rowFilter: z.ZodOptional<z.ZodObject<{
+                column: z.ZodString;
+                op: z.ZodLiteral<"eq">;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            }, z.core.$strict>>;
+            row: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        assert: z.ZodOptional<z.ZodObject<{
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            tolerance: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        run: z.ZodOptional<z.ZodString>;
+        path: z.ZodString;
+        hash: z.ZodString;
+        snapshot: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"artifact-value">;
+    }, z.core.$strict>, z.ZodObject<{
+        unit: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodString>;
+        columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        run: z.ZodOptional<z.ZodString>;
+        path: z.ZodString;
+        hash: z.ZodString;
+        snapshot: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"artifact-table">;
+    }, z.core.$strict>, z.ZodObject<{
+        unit: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodString>;
+        run: z.ZodOptional<z.ZodString>;
+        path: z.ZodString;
+        hash: z.ZodString;
+        snapshot: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"artifact-file">;
+    }, z.core.$strict>, z.ZodObject<{
+        unit: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"derivation">;
+        op: z.ZodEnum<{
+            ratio: "ratio";
+            delta: "delta";
+            pctChange: "pctChange";
+        }>;
+        inputs: z.ZodArray<z.ZodObject<{
+            unit: z.ZodOptional<z.ZodString>;
+            format: z.ZodOptional<z.ZodString>;
+            locator: z.ZodObject<{
+                column: z.ZodString;
+                rowFilter: z.ZodOptional<z.ZodObject<{
+                    column: z.ZodString;
+                    op: z.ZodLiteral<"eq">;
+                    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+                }, z.core.$strict>>;
+                row: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>;
+            assert: z.ZodOptional<z.ZodObject<{
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+                tolerance: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+            run: z.ZodOptional<z.ZodString>;
+            path: z.ZodString;
+            hash: z.ZodString;
+            snapshot: z.ZodOptional<z.ZodString>;
+            kind: z.ZodLiteral<"artifact-value">;
+        }, z.core.$strict>>;
+        assert: z.ZodOptional<z.ZodObject<{
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            tolerance: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        unit: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"citation">;
+        idKind: z.ZodEnum<{
+            doi: "doi";
+            pmid: "pmid";
+            arxiv: "arxiv";
+        }>;
+        id: z.ZodString;
+        raw: z.ZodString;
+        assert: z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>], "kind">;
+    reason: z.ZodEnum<{
+        "artifact-missing": "artifact-missing";
+        "hash-mismatch": "hash-mismatch";
+        "locator-out-of-range": "locator-out-of-range";
+        "ambiguous-match": "ambiguous-match";
+        "assertion-failed": "assertion-failed";
+        "unreadable-artifact": "unreadable-artifact";
+    }>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ArtifactValueReference = z.infer<typeof ArtifactValueReferenceSchema>;
+export type ArtifactTableReference = z.infer<typeof ArtifactTableReferenceSchema>;
+export type ArtifactFileReference = z.infer<typeof ArtifactFileReferenceSchema>;
+export type CitationReference = z.infer<typeof CitationReferenceSchema>;
+export type DerivationInputReference = z.infer<typeof DerivationInputReferenceSchema>;
+export type DerivationReference = z.infer<typeof DerivationReferenceSchema>;
+export type Reference = z.infer<typeof ReferenceSchema>;
+export type ScalarReference = z.infer<typeof ScalarReferenceSchema>;
+export type UnresolvedReason = z.infer<typeof UnresolvedReasonSchema>;
+export type UnresolvedReference = z.infer<typeof UnresolvedReferenceSchema>;
+/**
+ * Serialize a reference to a canonical URI.
+ *
+ * The payload is an opaque base64url of the canonical JSON, and not a structured URI with a field for
+ * each property. The reference object is the source of truth. A structured URI re-parses field by
+ * field, and it drifts from the object as the shape grows. An opaque payload cannot drift, because it
+ * round-trips the whole object.
+ */
+export declare function serializeReference(reference: Reference): string;
+/**
+ * The reason that a reference URI did not parse. Each of the four modes is distinct: a wrong prefix, a
+ * payload that is empty or holds a character outside the base64url alphabet, JSON that does not parse,
+ * and a value that the schema rejects. A caller reads the `kind` to tell them apart. `detail` carries no
+ * secret, thus a schema mismatch gives the kind alone.
+ */
+export type ParseReferenceError = {
+    kind: "bad-prefix" | "invalid-payload" | "invalid-json" | "schema-mismatch";
+    detail?: string;
+};
+/**
+ * Parse a reference URI. Each failure mode gives its own `Err` `kind`, thus a caller tells a wrong
+ * prefix from malformed bytes, malformed JSON, and a schema mismatch. This function never throws, thus a
+ * caller treats a failed parse as a normal condition.
+ */
+export declare function parseReference(uri: string): Result<Reference, ParseReferenceError>;