@inflexa-ai/harness 0.19.2 → 0.21.0

package/dist/report-model/authoring-grammar.d.ts

@@ -0,0 +1,463 @@
+/**
+ * The block grammar that an agent writes and reads.
+ *
+ * The pinned snapshot owns the hash of each artifact reference. Thus an agent names the path alone, and the
+ * land path stamps the hash from the snapshot entry at that path. This grammar is the contract grammar with
+ * that one field dropped. The published input schema of a tool shows no hash, and a read of a block gives
+ * none back. Thus an agent never sees a hash, and it never mistypes one.
+ *
+ * The grammar composes from the contract schemas, and it does not copy them. Each block keeps its own
+ * fields, and only the reference-bearing field of a kind changes. Thus a new field of a block reaches this
+ * grammar the moment that the contract declares it.
+ *
+ * The stored form stays the contract form. The stamp fills the hash before the draft grammar parses the
+ * payload, thus the grounding and the resolution read the same pin as before.
+ */
+import { z } from "zod";
+/**
+ * The seven atoms of the authoring surface.
+ *
+ * A text block and a citation block bind no artifact, thus each one is the contract schema itself. The five
+ * others replace the one field that carries a pin.
+ */
+declare const AUTHORING_ATOM_SCHEMAS: readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    id: z.ZodString;
+    content: z.ZodObject<{
+        prose: z.ZodString;
+        list: z.ZodOptional<z.ZodObject<{
+            ordered: z.ZodBoolean;
+            items: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"claim">;
+    id: z.ZodString;
+    content: z.ZodObject<{
+        prose: z.ZodString;
+    }, z.core.$strict>;
+    bindings: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        format: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"artifact-value">;
+        path: z.ZodString;
+        unit: 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>;
+        snapshot: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        format: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"artifact-table">;
+        path: z.ZodString;
+        unit: z.ZodOptional<z.ZodString>;
+        rowBound: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            count: z.ZodNumber;
+            order: z.ZodOptional<z.ZodEnum<{
+                desc: "desc";
+                asc: "asc";
+            }>>;
+        }, z.core.$strict>>;
+        columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        columnMeanings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            count: "count";
+            identifier: "identifier";
+            category: "category";
+            "p-value": "p-value";
+            effect: "effect";
+        }>>>;
+        columnLabels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        run: z.ZodOptional<z.ZodString>;
+        snapshot: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        format: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"artifact-file">;
+        path: z.ZodString;
+        unit: z.ZodOptional<z.ZodString>;
+        run: z.ZodOptional<z.ZodString>;
+        snapshot: z.ZodOptional<z.ZodString>;
+    }, 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";
+        }>;
+        assert: z.ZodOptional<z.ZodObject<{
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            tolerance: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        inputs: z.ZodArray<z.ZodObject<{
+            format: z.ZodOptional<z.ZodString>;
+            kind: z.ZodLiteral<"artifact-value">;
+            path: z.ZodString;
+            unit: 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>;
+            snapshot: z.ZodOptional<z.ZodString>;
+        }, 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">>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"metric">;
+    id: z.ZodString;
+    label: z.ZodString;
+    value: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        format: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"artifact-value">;
+        path: z.ZodString;
+        unit: 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>;
+        snapshot: z.ZodOptional<z.ZodString>;
+    }, 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";
+        }>;
+        assert: z.ZodOptional<z.ZodObject<{
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            tolerance: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        inputs: z.ZodArray<z.ZodObject<{
+            format: z.ZodOptional<z.ZodString>;
+            kind: z.ZodLiteral<"artifact-value">;
+            path: z.ZodString;
+            unit: 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>;
+            snapshot: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"table">;
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    caption: z.ZodOptional<z.ZodString>;
+    binding: z.ZodObject<{
+        format: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"artifact-table">;
+        path: z.ZodString;
+        unit: z.ZodOptional<z.ZodString>;
+        rowBound: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            count: z.ZodNumber;
+            order: z.ZodOptional<z.ZodEnum<{
+                desc: "desc";
+                asc: "asc";
+            }>>;
+        }, z.core.$strict>>;
+        columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        columnMeanings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            count: "count";
+            identifier: "identifier";
+            category: "category";
+            "p-value": "p-value";
+            effect: "effect";
+        }>>>;
+        columnLabels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        run: z.ZodOptional<z.ZodString>;
+        snapshot: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    binding: z.ZodObject<{
+        format: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"artifact-table">;
+        path: z.ZodString;
+        unit: z.ZodOptional<z.ZodString>;
+        rowBound: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            count: z.ZodNumber;
+            order: z.ZodOptional<z.ZodEnum<{
+                desc: "desc";
+                asc: "asc";
+            }>>;
+        }, z.core.$strict>>;
+        columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        columnMeanings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            count: "count";
+            identifier: "identifier";
+            category: "category";
+            "p-value": "p-value";
+            effect: "effect";
+        }>>>;
+        columnLabels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        run: z.ZodOptional<z.ZodString>;
+        snapshot: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    kind: z.ZodLiteral<"chart">;
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    chartType: z.ZodOptional<z.ZodEnum<{
+        bar: "bar";
+        line: "line";
+        scatter: "scatter";
+        histogram: "histogram";
+        box: "box";
+        heatmap: "heatmap";
+        pie: "pie";
+        volcano: "volcano";
+        manhattan: "manhattan";
+        ma: "ma";
+        km: "km";
+    }>>;
+    encoding: z.ZodOptional<z.ZodObject<{
+        x: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            column: z.ZodString;
+            transform: z.ZodEnum<{
+                log10: "log10";
+                neg_log10: "neg_log10";
+                abs: "abs";
+                rank: "rank";
+            }>;
+        }, z.core.$strict>]>>;
+        y: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            column: z.ZodString;
+            transform: z.ZodEnum<{
+                log10: "log10";
+                neg_log10: "neg_log10";
+                abs: "abs";
+                rank: "rank";
+            }>;
+        }, z.core.$strict>]>>;
+        group: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            column: z.ZodString;
+            transform: z.ZodEnum<{
+                log10: "log10";
+                neg_log10: "neg_log10";
+                abs: "abs";
+                rank: "rank";
+            }>;
+        }, z.core.$strict>]>>;
+        value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            column: z.ZodString;
+            transform: z.ZodEnum<{
+                log10: "log10";
+                neg_log10: "neg_log10";
+                abs: "abs";
+                rank: "rank";
+            }>;
+        }, z.core.$strict>]>>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    orientation: z.ZodOptional<z.ZodEnum<{
+        vertical: "vertical";
+        horizontal: "horizontal";
+    }>>;
+    thresholds: z.ZodOptional<z.ZodObject<{
+        significance: z.ZodNumber;
+        effect: z.ZodNumber;
+    }, z.core.$strict>>;
+    composition: z.ZodOptional<z.ZodObject<{
+        series: z.ZodArray<z.ZodObject<{
+            form: z.ZodEnum<{
+                step: "step";
+                bar: "bar";
+                line: "line";
+                scatter: "scatter";
+                area: "area";
+            }>;
+            encoding: z.ZodObject<{
+                x: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    column: z.ZodString;
+                    transform: z.ZodEnum<{
+                        log10: "log10";
+                        neg_log10: "neg_log10";
+                        abs: "abs";
+                        rank: "rank";
+                    }>;
+                }, z.core.$strict>]>;
+                y: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    column: z.ZodString;
+                    transform: z.ZodEnum<{
+                        log10: "log10";
+                        neg_log10: "neg_log10";
+                        abs: "abs";
+                        rank: "rank";
+                    }>;
+                }, z.core.$strict>]>;
+                y0: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    column: z.ZodString;
+                    transform: z.ZodEnum<{
+                        log10: "log10";
+                        neg_log10: "neg_log10";
+                        abs: "abs";
+                        rank: "rank";
+                    }>;
+                }, z.core.$strict>]>>;
+                group: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    column: z.ZodString;
+                    transform: z.ZodEnum<{
+                        log10: "log10";
+                        neg_log10: "neg_log10";
+                        abs: "abs";
+                        rank: "rank";
+                    }>;
+                }, z.core.$strict>]>>;
+                label: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            name: z.ZodOptional<z.ZodString>;
+            orientation: z.ZodOptional<z.ZodEnum<{
+                vertical: "vertical";
+                horizontal: "horizontal";
+            }>>;
+        }, z.core.$strict>>;
+        annotations: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"reference-line">;
+            axis: z.ZodEnum<{
+                x: "x";
+                y: "y";
+            }>;
+            value: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"reference-band">;
+            axis: z.ZodEnum<{
+                x: "x";
+                y: "y";
+            }>;
+            from: z.ZodNumber;
+            to: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"point-labels">;
+            column: z.ZodString;
+            order: z.ZodEnum<{
+                desc: "desc";
+                asc: "asc";
+            }>;
+            n: z.ZodNumber;
+        }, z.core.$strict>], "kind">>>;
+        axes: z.ZodOptional<z.ZodObject<{
+            x: z.ZodOptional<z.ZodObject<{
+                title: z.ZodOptional<z.ZodString>;
+                scale: z.ZodOptional<z.ZodEnum<{
+                    log: "log";
+                    linear: "linear";
+                }>>;
+            }, z.core.$strict>>;
+            y: z.ZodOptional<z.ZodObject<{
+                title: z.ZodOptional<z.ZodString>;
+                scale: z.ZodOptional<z.ZodEnum<{
+                    log: "log";
+                    linear: "linear";
+                }>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    caption: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"figure">;
+    id: z.ZodString;
+    caption: z.ZodOptional<z.ZodString>;
+    binding: z.ZodObject<{
+        format: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"artifact-file">;
+        path: z.ZodString;
+        unit: z.ZodOptional<z.ZodString>;
+        run: z.ZodOptional<z.ZodString>;
+        snapshot: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"citation">;
+    id: z.ZodString;
+    binding: 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>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>];
+/**
+ * The section shape as a plain type. TypeScript cannot infer the block tree through the union cycle, thus
+ * the recursive members carry an explicit type.
+ */
+export interface AuthoringSectionBlock {
+    kind: "section";
+    id: string;
+    title: string;
+    blocks: AuthoringBlock[];
+}
+/** One block of any kind except a section, as an agent writes it and reads it. */
+export type AuthoringAtomBlock = z.infer<(typeof AUTHORING_ATOM_SCHEMAS)[number]>;
+/** One block of any of the eight kinds, as an agent writes it and reads it. */
+export type AuthoringBlock = AuthoringAtomBlock | AuthoringSectionBlock;
+/** The block union of the authoring surface. The annotation gives the recursive members a stable type. */
+export declare const AuthoringBlockSchema: z.ZodType<AuthoringBlock>;
+export {};

package/dist/report-model/authoring-grammar.js

@@ -0,0 +1,77 @@
+/**
+ * The block grammar that an agent writes and reads.
+ *
+ * The pinned snapshot owns the hash of each artifact reference. Thus an agent names the path alone, and the
+ * land path stamps the hash from the snapshot entry at that path. This grammar is the contract grammar with
+ * that one field dropped. The published input schema of a tool shows no hash, and a read of a block gives
+ * none back. Thus an agent never sees a hash, and it never mistypes one.
+ *
+ * The grammar composes from the contract schemas, and it does not copy them. Each block keeps its own
+ * fields, and only the reference-bearing field of a kind changes. Thus a new field of a block reaches this
+ * grammar the moment that the contract declares it.
+ *
+ * The stored form stays the contract form. The stamp fills the hash before the draft grammar parses the
+ * payload, thus the grounding and the resolution read the same pin as before.
+ */
+import { z } from "zod";
+import { ChartBlockSchema, CitationBlockSchema, ClaimBlockSchema, FigureBlockSchema, MetricBlockSchema, TableBlockSchema, TextBlockSchema, } from "../contracts/report-blocks.js";
+import { ArtifactFileReferenceSchema, ArtifactTableReferenceSchema, ArtifactValueReferenceSchema, CitationReferenceSchema, DerivationReferenceSchema, } from "../contracts/report-reference.js";
+/** A reference to one scalar value inside an artifact, by the path of the artifact and a locator. */
+const AuthoringValueReferenceSchema = ArtifactValueReferenceSchema.omit({ hash: true });
+/** A reference to a whole table artifact, by the path of the artifact. */
+const AuthoringTableReferenceSchema = ArtifactTableReferenceSchema.omit({ hash: true });
+/** A reference to a whole artifact file, by the path of the artifact. */
+const AuthoringFileReferenceSchema = ArtifactFileReferenceSchema.omit({ hash: true });
+/** A reference to a value computed from two scalar references. Each input names a path and no hash. */
+const AuthoringDerivationReferenceSchema = DerivationReferenceSchema.extend({
+    inputs: z
+        .array(AuthoringValueReferenceSchema)
+        .length(2)
+        .describe("The two input references. Each operation takes exactly two, and each one must resolve to a scalar."),
+});
+/** The full reference union of the authoring surface. A citation names an external id, thus it pins no artifact. */
+const AuthoringReferenceSchema = z.discriminatedUnion("kind", [
+    AuthoringValueReferenceSchema,
+    AuthoringTableReferenceSchema,
+    AuthoringFileReferenceSchema,
+    AuthoringDerivationReferenceSchema,
+    CitationReferenceSchema,
+]);
+/** The references of the authoring surface that resolve to one scalar value. */
+const AuthoringScalarReferenceSchema = z.discriminatedUnion("kind", [AuthoringValueReferenceSchema, AuthoringDerivationReferenceSchema]);
+/**
+ * The chart block of the authoring surface.
+ *
+ * A chart carries a rule over its own fields, and a schema with a rule refuses a replacement of one field.
+ * Thus this schema spreads the fields of the contract chart, and it replaces the binding. The rule itself
+ * stays out: the core parses each payload with the draft grammar, and that grammar carries the rule. This
+ * schema publishes the shape, and it types the read.
+ */
+const AuthoringChartBlockSchema = z.strictObject({
+    ...ChartBlockSchema.shape,
+    binding: AuthoringTableReferenceSchema.describe("The whole-table artifact to plot."),
+});
+/**
+ * The seven atoms of the authoring surface.
+ *
+ * A text block and a citation block bind no artifact, thus each one is the contract schema itself. The five
+ * others replace the one field that carries a pin.
+ */
+const AUTHORING_ATOM_SCHEMAS = [
+    TextBlockSchema,
+    ClaimBlockSchema.extend({ bindings: z.array(AuthoringReferenceSchema).min(1).describe("The evidence that justifies the claim.") }),
+    MetricBlockSchema.extend({ value: AuthoringScalarReferenceSchema.describe("The one scalar reference that gives the metric value.") }),
+    TableBlockSchema.extend({ binding: AuthoringTableReferenceSchema.describe("The whole-table artifact to render.") }),
+    AuthoringChartBlockSchema,
+    FigureBlockSchema.extend({ binding: AuthoringFileReferenceSchema.describe("The image artifact. It pins the whole file, and the path names it.") }),
+    CitationBlockSchema,
+];
+/** A section of the authoring surface permits zero child blocks, exactly as a draft section does. */
+const AuthoringSectionBlockSchema = z.strictObject({
+    kind: z.literal("section"),
+    id: z.string().min(1),
+    title: z.string(),
+    blocks: z.lazy(() => z.array(AuthoringBlockSchema)),
+});
+/** The block union of the authoring surface. The annotation gives the recursive members a stable type. */
+export const AuthoringBlockSchema = z.discriminatedUnion("kind", [AuthoringSectionBlockSchema, ...AUTHORING_ATOM_SCHEMAS]);

package/dist/report-model/block-walk.d.ts

@@ -1,10 +1,11 @@
 /**
  * The one walk over a block tree.
  *
- * A block kind decides where a reference sits, which prose carries a free numeral, and whether the block
- * holds children. Three consumers need that same knowledge: the mechanical validator, the draft finish,
- * and the draft operations. A switch for each consumer is a switch that a ninth block kind can miss in
- * silence, because each arm returns and none of them fails to build. Thus the walk lives here one time.
+ * A block kind decides where a reference sits, which text carries a free numeral or a drifted exponent
+ * form, and whether the block holds children. Three consumers need that same knowledge: the mechanical
+ * validator, the draft finish, and the draft operations. A switch for each consumer is a switch that a
+ * ninth block kind can miss in silence, because each arm returns and none of them fails to build. Thus the
+ * walk lives here one time.
  *
  * The walk reads a finished `Block` tree and a relaxed `DraftBlock` tree alike. The two differ only in the
  * section rules, and the section arm reads the children of either one.
@@ -12,7 +13,7 @@
  * The walk resolves nothing and it opens no file. It reports what the tree holds, and a caller decides
  * which part it needs.
  */
-import type { Block } from "../contracts/report-blocks.js";
+import { type Block } from "../contracts/report-blocks.js";
 import type { Reference } from "../contracts/report-reference.js";
 import type { DraftBlock } from "./draft.js";
 /** A block of a finished report, or a block of a draft. The atoms are the same shape in both. */
@@ -20,33 +21,65 @@ export type AnyBlock = Block | DraftBlock;
 /**
  * One reference that the walk met, tied to the block that carries it.
  *
- * `encodingColumns` is present for a `chart` only. A chart names its axes as free strings, thus the names
- * must be matched against the table that the binding resolves to. Nothing else can catch a chart that
- * plots a column which does not exist. The match needs the resolved rows, thus only a value-tier consumer
- * reads this field.
+ * `encodingColumns` is present for a `chart` only. A chart names its columns as free strings, thus the
+ * names must be matched against the table that the binding resolves to. Nothing else can catch a chart
+ * that plots a column which does not exist. The field carries every column that the chart grammar names,
+ * thus the structural tier and the value tier match the same set.
  */
 export interface CollectedReference {
     blockId: string;
     reference: Reference;
     encodingColumns?: string[];
 }
-/** An advisory warning about the content of one block. A warning never makes a report invalid. */
-export interface ReportWarning {
+/** An advisory warning about the prose of one block. The detail is the numeral that the prose carries. */
+export interface FreeNumeralWarning {
     blockId: string;
     kind: "free-numeral";
     detail: string;
 }
+/**
+ * An advisory warning about one exponent form that the prose of a block carries and the page never prints.
+ * The detail is the written form.
+ */
+export interface ExponentFormWarning {
+    blockId: string;
+    kind: "exponent-form";
+    detail: string;
+}
+/** One advisory warning about the prose of a block. */
+export type ProseWarning = FreeNumeralWarning | ExponentFormWarning;
+/**
+ * An advisory warning about one derivation that no binding of the document names. The detail is the output
+ * path of the record. The record stays, and the bytes are reproducible from the script and the sources.
+ */
+export interface UnusedDerivationWarning {
+    kind: "unused-derivation";
+    detail: string;
+}
+/** One advisory warning about a report. A warning never makes a report invalid. */
+export type ReportWarning = ProseWarning | UnusedDerivationWarning;
 /** What one walk over a block tree found. */
 export interface BlockWalk {
     /** Each reference, in document order, tied to the block that carries it. */
     references: CollectedReference[];
     /** Each id that more than one block holds, named one time, in sorted order. */
     repeatedIds: string[];
-    /** Each free numeral that prose carries. */
-    warnings: ReportWarning[];
+    /** Each free numeral and each drifted exponent form that prose carries. */
+    warnings: ProseWarning[];
 }
 /** Warn for each free-standing numeral that the prose of one block carries. */
-export declare function numeralWarnings(blockId: string, prose: string): ReportWarning[];
+export declare function numeralWarnings(blockId: string, prose: string): FreeNumeralWarning[];
+/**
+ * Warn for each exponent form of one block that the page never prints.
+ *
+ * The page owns the notation of a value. Thus a sentence that writes a second notation of the same number
+ * disagrees with the card beside it. The renderer answers which forms it prints, thus this scan states no
+ * rule of its own.
+ *
+ * The check is advisory, exactly as the numeral scan is. A prose exponent can be a quoted threshold that no
+ * cell carries, thus a hit warns and it never fails the report.
+ */
+export declare function exponentWarnings(blockId: string, prose: string): ExponentFormWarning[];
 /**
  * Walk a block tree, and report each reference, each repeated id, and each free numeral.
  *
@@ -54,3 +87,13 @@ export declare function numeralWarnings(blockId: string, prose: string): ReportW
  * to one block. The walk is pre-order, thus the references follow the document order.
  */
 export declare function walkBlocks(blocks: readonly AnyBlock[]): BlockWalk;
+/**
+ * Each artifact path that a set of collected references names.
+ *
+ * An artifact binding names one path. A derivation reference computes over two inputs, thus it names the
+ * path of each input and a table that feeds a derived scalar counts as named. A citation names no path.
+ *
+ * The set answers one question: which files does this document use. The finish reads it against the
+ * derivations of the session, and the record reads it again over the recorded document.
+ */
+export declare function referencedPaths(references: readonly CollectedReference[]): Set<string>;