@inflexa-ai/harness 0.17.0 → 0.19.0

package/dist/contracts/report-blocks.js

@@ -0,0 +1,117 @@
+/**
+ * The composable block tree of a report.
+ *
+ * A block is one of eight kinds. The shape of each kind carries its grammar. A `text` block has no
+ * binding field, thus an unbound claim is unrepresentable. A `metric` value slot admits one scalar
+ * reference only, thus a numeric literal cannot sit there. No atom holds a child-block array, thus a
+ * chart inside a metric is unrepresentable. The grammar is the shape, and not a separate pass.
+ *
+ * The tree is recursive: a `section` holds child blocks, and a child can be another section.
+ *
+ * Every object schema here and in the reference module is strict. A strict object makes an extra field
+ * a parse failure, and not a field that the parser strips in silence. Thus a forbidden field, such as a
+ * binding on a `text` block or a child-block array on an atom, is rejected. The absence of a field is a
+ * rule only when an extra field fails the parse.
+ */
+import { z } from "zod";
+import { ArtifactFileReferenceSchema, ArtifactTableReferenceSchema, CitationReferenceSchema, ReferenceSchema, ScalarReferenceSchema, } from "./report-reference.js";
+/** The chart vocabulary. Each value names one plot form. */
+const ChartTypeSchema = z.enum(["bar", "line", "scatter", "histogram", "box", "heatmap", "pie"]);
+/** The mapping from a data column to a visual channel. Each channel is optional. */
+const ChartEncodingSchema = z.strictObject({
+    x: z.string().optional().describe("The column on the x axis."),
+    y: z.string().optional().describe("The column on the y axis."),
+    group: z.string().optional().describe("The column that splits and colors the series."),
+    value: z.string().optional().describe("The value column for a pie or heatmap."),
+});
+/** Prose with no binding. The absence of a binding field is the rule for this kind. */
+export const TextBlockSchema = z.strictObject({
+    kind: z.literal("text"),
+    id: z.string().min(1).describe("The stable identity of the block."),
+    content: z.strictObject({ prose: z.string() }),
+});
+/** Prose with at least one reference that justifies it. */
+export const ClaimBlockSchema = z.strictObject({
+    kind: z.literal("claim"),
+    id: z.string().min(1).describe("The stable identity of the block."),
+    content: z.strictObject({ prose: z.string() }),
+    bindings: z.array(ReferenceSchema).min(1).describe("The evidence that justifies the claim."),
+});
+/** A labeled number whose value comes from one scalar reference. */
+export const MetricBlockSchema = z.strictObject({
+    kind: z.literal("metric"),
+    id: z.string().min(1).describe("The stable identity of the block."),
+    label: z.string(),
+    value: ScalarReferenceSchema.describe("The one scalar reference that gives the metric value."),
+});
+/** A whole-table artifact rendered as a table. */
+export const TableBlockSchema = z.strictObject({
+    kind: z.literal("table"),
+    id: z.string().min(1).describe("The stable identity of the block."),
+    title: z.string().optional(),
+    binding: ArtifactTableReferenceSchema.describe("The whole-table artifact to render."),
+    caption: z.string().optional(),
+});
+/** A whole-table artifact rendered as a chart, with the plot form and the channel mapping. */
+export const ChartBlockSchema = z.strictObject({
+    kind: z.literal("chart"),
+    id: z.string().min(1).describe("The stable identity of the block."),
+    title: z.string().optional(),
+    binding: ArtifactTableReferenceSchema.describe("The whole-table artifact to plot."),
+    chartType: ChartTypeSchema,
+    encoding: ChartEncodingSchema,
+    caption: z.string().optional(),
+});
+/** A static image artifact. An image has no per-cell address, thus it is pinned whole-file. */
+export const FigureBlockSchema = z.strictObject({
+    kind: z.literal("figure"),
+    id: z.string().min(1).describe("The stable identity of the block."),
+    binding: ArtifactFileReferenceSchema.describe("The image artifact, pinned whole-file by path and hash."),
+    caption: z.string().optional(),
+});
+/** An external source, rendered from a citation reference. */
+export const CitationBlockSchema = z.strictObject({
+    kind: z.literal("citation"),
+    id: z.string().min(1).describe("The stable identity of the block."),
+    binding: CitationReferenceSchema,
+    note: z.string().optional(),
+});
+/**
+ * The seven atoms, as one tuple.
+ *
+ * A section is the only kind whose rules differ between a finished report and a draft. Thus the atoms are
+ * the shared part, and every union of block kinds spreads this tuple beside its own section member. A
+ * ninth kind lands here one time, and each union gets it.
+ */
+export const ATOM_BLOCK_SCHEMAS = [
+    TextBlockSchema,
+    ClaimBlockSchema,
+    MetricBlockSchema,
+    TableBlockSchema,
+    ChartBlockSchema,
+    FigureBlockSchema,
+    CitationBlockSchema,
+];
+/**
+ * A section holds at least one child block, thus an empty section is invalid. The `blocks` field is a
+ * `z.lazy` and not a getter, so the discriminated union reads the `kind` discriminator at construction
+ * time without a reference to `BlockSchema` before it exists.
+ */
+export const SectionBlockSchema = z.strictObject({
+    kind: z.literal("section"),
+    id: z.string().min(1),
+    title: z.string(),
+    blocks: z.lazy(() => z.array(BlockSchema).min(1)),
+});
+/** The block union. A `z.ZodType<Block>` annotation gives the recursive members a stable type. */
+export const BlockSchema = z.discriminatedUnion("kind", [SectionBlockSchema, ...ATOM_BLOCK_SCHEMAS]);
+/**
+ * The root of a report. It holds at least one section, thus an empty report is invalid.
+ *
+ * The title carries `min(1)`, because an untitled report is incomplete in the same way that an empty
+ * section is. A draft relaxes it, and this schema gates it one time, at the finish.
+ */
+export const ReportDocumentSchema = z.strictObject({
+    title: z.string().min(1),
+    sections: z.array(SectionBlockSchema).min(1).describe("The top-level sections, each with at least one block."),
+});

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