@inflexa-ai/harness 0.20.0 → 0.21.0

package/dist/report-model/block-walk.js

@@ -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,6 +13,8 @@
  * The walk resolves nothing and it opens no file. It reports what the tree holds, and a caller decides
  * which part it needs.
  */
+import { channelColumn } from "../contracts/report-blocks.js";
+import { holdsADriftedExponent } from "../report-render/number-format.js";
 /**
  * A free-standing token that looks like a number, with an optional decimal part and an optional percent
  * sign.
@@ -25,6 +28,13 @@
  * the report.
  */
 const NUMERAL_PATTERN = /(?<![A-Za-z0-9])-?\d+(?:\.\d+)?%?/g;
+/**
+ * A free-standing token that states a number in an exponent form, for example `4.3e-05`.
+ *
+ * The left boundary is the one of the numeral scan, thus a token inside a name never matches. The exponent
+ * itself carries an optional sign, because a written form gives one and a shown form never does.
+ */
+const EXPONENT_PATTERN = /(?<![A-Za-z0-9])-?\d+(?:\.\d+)?[eE][+-]?\d+/g;
 /** Warn for each free-standing numeral that the prose of one block carries. */
 export function numeralWarnings(blockId, prose) {
     const warnings = [];
@@ -33,6 +43,73 @@ export function numeralWarnings(blockId, prose) {
     }
     return warnings;
 }
+/**
+ * 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 function exponentWarnings(blockId, prose) {
+    const warnings = [];
+    for (const match of prose.matchAll(EXPONENT_PATTERN)) {
+        if (holdsADriftedExponent(match[0])) {
+            warnings.push({ blockId, kind: "exponent-form", detail: match[0] });
+        }
+    }
+    return warnings;
+}
+/** Each advisory warning that the prose of one block carries. */
+function proseWarnings(blockId, prose) {
+    return [...numeralWarnings(blockId, prose), ...exponentWarnings(blockId, prose)];
+}
+/**
+ * Each column that the grammar of one chart names.
+ *
+ * The quick path names its four channels and its label. A composition names the channels of each series,
+ * the lower bound of a band, the label of each series, and the column of each rank rule. A transform rides
+ * beside its column, thus a transformed channel names the same column as a plain one.
+ *
+ * A name comes back one time, in the order that the grammar states it. Thus a refusal names each absent
+ * column one time.
+ */
+function chartColumns(block) {
+    const columns = [];
+    const add = (column) => {
+        if (column !== undefined && !columns.includes(column))
+            columns.push(column);
+    };
+    const addChannel = (channel) => {
+        if (channel !== undefined)
+            add(channelColumn(channel));
+    };
+    const encoding = block.encoding;
+    if (encoding !== undefined) {
+        addChannel(encoding.x);
+        addChannel(encoding.y);
+        addChannel(encoding.group);
+        addChannel(encoding.value);
+        add(encoding.label);
+    }
+    const composition = block.composition;
+    if (composition !== undefined) {
+        for (const series of composition.series) {
+            addChannel(series.encoding.x);
+            addChannel(series.encoding.y);
+            addChannel(series.encoding.y0);
+            addChannel(series.encoding.group);
+            add(series.encoding.label);
+        }
+        for (const annotation of composition.annotations ?? []) {
+            if (annotation.kind === "point-labels")
+                add(annotation.column);
+        }
+    }
+    return columns;
+}
 /**
  * Walk a block tree, and report each reference, each repeated id, and each free numeral.
  *
@@ -58,10 +135,15 @@ export function walkBlocks(blocks) {
                 }
                 return;
             case "text":
-                warnings.push(...numeralWarnings(block.id, block.content.prose));
+                warnings.push(...proseWarnings(block.id, block.content.prose));
+                // An item of a list states a point, the same as a sentence of the prose. Thus a free
+                // figure inside an item carries the same honesty concern, and the walk reads both.
+                for (const item of block.content.list?.items ?? []) {
+                    warnings.push(...proseWarnings(block.id, item));
+                }
                 return;
             case "claim":
-                warnings.push(...numeralWarnings(block.id, block.content.prose));
+                warnings.push(...proseWarnings(block.id, block.content.prose));
                 for (const binding of block.bindings) {
                     references.push({ blockId: block.id, reference: binding });
                 }
@@ -69,12 +151,9 @@ export function walkBlocks(blocks) {
             case "metric":
                 references.push({ blockId: block.id, reference: block.value });
                 return;
-            case "chart": {
-                const encoding = block.encoding;
-                const encodingColumns = [encoding.x, encoding.y, encoding.group, encoding.value].filter((column) => column !== undefined);
-                references.push({ blockId: block.id, reference: block.binding, encodingColumns });
+            case "chart":
+                references.push({ blockId: block.id, reference: block.binding, encodingColumns: chartColumns(block) });
                 return;
-            }
             case "table":
             case "figure":
             case "citation":
@@ -87,3 +166,29 @@ export function walkBlocks(blocks) {
     }
     return { references, repeatedIds: [...repeated].sort(), warnings };
 }
+/**
+ * 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 function referencedPaths(references) {
+    const paths = new Set();
+    for (const entry of references) {
+        const reference = entry.reference;
+        if (reference.kind === "citation") {
+            continue;
+        }
+        if (reference.kind === "derivation") {
+            for (const input of reference.inputs) {
+                paths.add(input.path);
+            }
+            continue;
+        }
+        paths.add(reference.path);
+    }
+    return paths;
+}

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

@@ -5,14 +5,23 @@
  * draft one time: the full document schema, the unique ids, and the structural tier over every reference.
  *
  * The finish opens no file, and it reads the snapshot alone. Thus it runs the structural tier only, and
- * the value tier stays in the gate of the report pipeline. The chart encoding-column match needs the rows
- * behind a binding, thus it stays with the value tier.
+ * the value tier stays in the gate of the report pipeline. The structural tier matches the columns of a
+ * chart wherever the snapshot can answer, and the value tier matches them again over the rows that it
+ * reads.
  *
  * The free-numeral scan needs no file, thus the finish runs it and reports each hit as a warning. A
  * warning never makes a draft invalid, and it rides beside the outcome in either case. Without the
  * channel a caller could not read the one signal that catches a figure typed into prose with no metric
  * block behind it.
  *
+ * The exponent-form scan rides the same channel. A sentence can state a number in a notation that the page
+ * never prints, and such a sentence disagrees with the card beside it. Thus the prose notation and the page
+ * notation cannot drift in silence.
+ *
+ * The unused-derivation scan rides the same channel. The records and the draft both sit in memory, thus the
+ * scan opens no file either. A derivation whose output path no binding names warns, and the derived bytes
+ * stay until the record prunes them.
+ *
  * The result is plain data. A gap is an expected outcome, not an error, thus the finish never throws. On
  * a pass the finish gives the valid document, and it does not change the draft.
  */
@@ -53,8 +62,17 @@ export type FinishResult = {
     gaps: FinishGap[];
     warnings: ReportWarning[];
 };
+/**
+ * One derivation of the session, as the finish reads it. The finish needs the output path alone, because
+ * the used set is the paths that the bindings name.
+ */
+export interface SessionDerivation {
+    readonly outputPath: string;
+}
 /**
  * Finish a draft. The finish validates the schema, the unique ids, and the structural resolution of each
- * reference, and it reports each gap as data. It warns about each free numeral in prose.
+ * reference, and it reports each gap as data. It warns about each free numeral in prose, and about each
+ * exponent form that the page never prints. It warns about each derivation of the session that no binding
+ * names.
  */
-export declare function finishDraft(draft: DraftDocument, snapshot: ReportSnapshot): FinishResult;
+export declare function finishDraft(draft: DraftDocument, snapshot: ReportSnapshot, derivations?: readonly SessionDerivation[]): FinishResult;

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

@@ -5,25 +5,56 @@
  * draft one time: the full document schema, the unique ids, and the structural tier over every reference.
  *
  * The finish opens no file, and it reads the snapshot alone. Thus it runs the structural tier only, and
- * the value tier stays in the gate of the report pipeline. The chart encoding-column match needs the rows
- * behind a binding, thus it stays with the value tier.
+ * the value tier stays in the gate of the report pipeline. The structural tier matches the columns of a
+ * chart wherever the snapshot can answer, and the value tier matches them again over the rows that it
+ * reads.
  *
  * The free-numeral scan needs no file, thus the finish runs it and reports each hit as a warning. A
  * warning never makes a draft invalid, and it rides beside the outcome in either case. Without the
  * channel a caller could not read the one signal that catches a figure typed into prose with no metric
  * block behind it.
  *
+ * The exponent-form scan rides the same channel. A sentence can state a number in a notation that the page
+ * never prints, and such a sentence disagrees with the card beside it. Thus the prose notation and the page
+ * notation cannot drift in silence.
+ *
+ * The unused-derivation scan rides the same channel. The records and the draft both sit in memory, thus the
+ * scan opens no file either. A derivation whose output path no binding names warns, and the derived bytes
+ * stay until the record prunes them.
+ *
  * The result is plain data. A gap is an expected outcome, not an error, thus the finish never throws. On
  * a pass the finish gives the valid document, and it does not change the draft.
  */
 import { ReportDocumentSchema } from "../contracts/report-blocks.js";
-import { walkBlocks } from "./block-walk.js";
+import { referencedPaths, walkBlocks } from "./block-walk.js";
 import { validateReferenceStructure } from "./structural-validation.js";
+/**
+ * Warn for each derivation that no binding of the draft names.
+ *
+ * A derivation is used when a binding names its output path. Thus the scan is a set difference over the
+ * records and the collected references, and it reads no file. A warning names the output path, and it
+ * decides no outcome.
+ */
+function unusedDerivationWarnings(derivations, references) {
+    if (derivations.length === 0) {
+        return [];
+    }
+    const named = referencedPaths(references);
+    const warnings = [];
+    for (const record of derivations) {
+        if (!named.has(record.outputPath)) {
+            warnings.push({ kind: "unused-derivation", detail: record.outputPath });
+        }
+    }
+    return warnings;
+}
 /**
  * Finish a draft. The finish validates the schema, the unique ids, and the structural resolution of each
- * reference, and it reports each gap as data. It warns about each free numeral in prose.
+ * reference, and it reports each gap as data. It warns about each free numeral in prose, and about each
+ * exponent form that the page never prints. It warns about each derivation of the session that no binding
+ * names.
  */
-export function finishDraft(draft, snapshot) {
+export function finishDraft(draft, snapshot, derivations = []) {
     const gaps = [];
     const parsed = ReportDocumentSchema.safeParse(draft);
     if (!parsed.success) {
@@ -37,12 +68,13 @@ export function finishDraft(draft, snapshot) {
     }
     // The walk reads the draft tree, not the parse result. The draft is already typed, thus the walk stays
     // well-defined even when the schema parse fails, and a caller still gets the id and reference gaps.
-    const { references, repeatedIds, warnings } = walkBlocks(draft.sections);
+    const { references, repeatedIds, warnings: proseWarnings } = walkBlocks(draft.sections);
+    const warnings = [...proseWarnings, ...unusedDerivationWarnings(derivations, references)];
     for (const id of repeatedIds) {
         gaps.push({ kind: "duplicate-id", id });
     }
     for (const entry of references) {
-        const result = validateReferenceStructure(entry.reference, snapshot);
+        const result = validateReferenceStructure(entry.reference, snapshot, entry.encodingColumns);
         if (result.isErr()) {
             gaps.push({ kind: "unresolved-reference", blockId: entry.blockId, failure: result.error });
         }

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

@@ -88,6 +88,9 @@ export declare function setTitle(draft: DraftDocument, title: string): DraftDocu
  *
  * The root admits a section only, thus an atom at the root refuses. The validation covers the payload and
  * each of its descendants.
+ *
+ * The stamp runs before the parse. Thus a reference that names a path of the snapshot and no hash carries
+ * the hash of that path when the grammar reads it.
  */
 export declare function addBlock(draft: DraftDocument, operation: AddOperation, snapshot: ReportSnapshot): Result<DraftDocument, DraftRefusal>;
 /**

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

@@ -18,6 +18,7 @@
 import { err, ok } from "neverthrow";
 import { walkBlocks } from "./block-walk.js";
 import { DraftBlockSchema } from "./draft.js";
+import { stampReferenceHashes } from "./reference-stamp.js";
 import { validateReferenceStructure } from "./structural-validation.js";
 /**
  * Set the title of the document.
@@ -33,9 +34,16 @@ export function setTitle(draft, title) {
  *
  * The root admits a section only, thus an atom at the root refuses. The validation covers the payload and
  * each of its descendants.
+ *
+ * The stamp runs before the parse. Thus a reference that names a path of the snapshot and no hash carries
+ * the hash of that path when the grammar reads it.
  */
 export function addBlock(draft, operation, snapshot) {
-    const parsed = DraftBlockSchema.safeParse(operation.block);
+    const stamped = stampReferenceHashes(operation.block, snapshot);
+    if (stamped.isErr()) {
+        return err(stamped.error);
+    }
+    const parsed = DraftBlockSchema.safeParse(stamped.value);
     if (!parsed.success) {
         return err(malformed(parsed.error));
     }
@@ -75,10 +83,16 @@ export function changeBlock(draft, operation, snapshot) {
     if (payload === null || typeof payload !== "object") {
         return err({ reason: "malformed-block", detail: "the payload is not an object" });
     }
-    // The stamp sets the target id on the payload before the parse. Thus an id mismatch is
+    // The id stamp sets the target id on the payload before the parse. Thus an id mismatch is
     // unrepresentable, and a replacement always keeps the id of its target.
-    const stamped = { ...payload, id: operation.targetId };
-    const parsed = DraftBlockSchema.safeParse(stamped);
+    const withId = { ...payload, id: operation.targetId };
+    // The hash stamp then fills each absent reference hash from the snapshot, thus the grammar reads a
+    // complete pin. The two stamps are independent, because one reads the block and one reads a reference.
+    const hashed = stampReferenceHashes(withId, snapshot);
+    if (hashed.isErr()) {
+        return err(hashed.error);
+    }
+    const parsed = DraftBlockSchema.safeParse(hashed.value);
     if (!parsed.success) {
         return err(malformed(parsed.error));
     }
@@ -203,7 +217,7 @@ function commit(candidate, added, snapshot) {
     }
     const unresolved = [];
     for (const entry of walkBlocks([added]).references) {
-        validateReferenceStructure(entry.reference, snapshot).match(() => { }, (failure) => {
+        validateReferenceStructure(entry.reference, snapshot, entry.encodingColumns).match(() => { }, (failure) => {
             unresolved.push(failure);
         });
     }

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

@@ -9,8 +9,11 @@
  * section gives its own fields and the ids of its children, and never the subtree. The outline already
  * names every descendant, thus a subtree here would return the whole tree that the outline exists to keep
  * out.
+ *
+ * A read gives each binding with no hash. The pinned snapshot owns that value, thus an echoed hash would
+ * give the agent a value to mistype.
  */
-import type { AtomBlock } from "../contracts/report-blocks.js";
+import type { AuthoringAtomBlock } from "./authoring-grammar.js";
 import type { DraftBlock, DraftDocument } from "./draft.js";
 /**
  * One outline entry. It carries the id, the kind, the nesting depth, and a short label. A top-level
@@ -35,8 +38,8 @@ export interface ShallowSection {
     title: string;
     childIds: string[];
 }
-/** One block as the read surface gives it. An atom reads in full, and a section reads shallow. */
-export type ReadableBlock = AtomBlock | ShallowSection;
+/** One block as the read surface gives it. An atom reads in full and hash-free, and a section reads shallow. */
+export type ReadableBlock = AuthoringAtomBlock | ShallowSection;
 /**
  * Build the outline of a draft. The walk is pre-order, thus the entries follow the document order. A
  * section comes before its children, and a child sits one depth deeper than its parent.
@@ -53,7 +56,7 @@ export declare function buildOutline(draft: DraftDocument): OutlineEntry[];
  */
 export declare function childOutline(blocks: readonly DraftBlock[], depth: number): OutlineEntry[];
 /**
- * Read one block by its id. An atom gives the block as it is, with its bindings. A section gives its own
- * fields and the id of each child. A block that no id holds gives `undefined`.
+ * Read one block by its id. An atom gives the block with its bindings, and each binding gives no hash. A
+ * section gives its own fields and the id of each child. A block that no id holds gives `undefined`.
  */
 export declare function readBlock(draft: DraftDocument, id: string): ReadableBlock | undefined;

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

@@ -9,8 +9,12 @@
  * section gives its own fields and the ids of its children, and never the subtree. The outline already
  * names every descendant, thus a subtree here would return the whole tree that the outline exists to keep
  * out.
+ *
+ * A read gives each binding with no hash. The pinned snapshot owns that value, thus an echoed hash would
+ * give the agent a value to mistype.
  */
 import { locate } from "./draft-operations.js";
+import { stripReferenceHashes } from "./reference-stamp.js";
 /** The label keeps a prose head of at most this many code points. A clipped label ends with the marker. */
 const PROSE_CLIP = 80;
 /** The marker that a clipped label ends with. It counts toward `PROSE_CLIP`. */
@@ -40,6 +44,9 @@ function clip(text) {
  * a note. A text and a claim carry prose. Every one of them clips: a caption, a note, and a title are free
  * prose too, thus an unclipped arm would put a paragraph into each outline that names the block.
  *
+ * A text block carries its enumeration in the list, and the lead sentences above it can be empty. Such a
+ * block gives the first item, thus the outline names it and the agent reads which block it is.
+ *
  * A block with an absent optional field gives an empty label.
  */
 function labelOf(block) {
@@ -56,8 +63,15 @@ function labelOf(block) {
             return clip(block.caption ?? "");
         case "citation":
             return clip(block.note ?? "");
-        case "text":
-            return clip(block.content.prose);
+        case "text": {
+            const prose = block.content.prose;
+            if (prose.trim().length > 0) {
+                return clip(prose);
+            }
+            // An item passes the grammar with one space in it, thus the first item can name nothing. The
+            // walk takes the first item that holds text, and a list of blank items gives an empty label.
+            return clip(block.content.list?.items.find((item) => item.trim().length > 0) ?? "");
+        }
         case "claim":
             return clip(block.content.prose);
     }
@@ -94,8 +108,8 @@ export function childOutline(blocks, depth) {
     return blocks.map((block) => ({ id: block.id, kind: block.kind, depth, label: labelOf(block) }));
 }
 /**
- * Read one block by its id. An atom gives the block as it is, with its bindings. A section gives its own
- * fields and the id of each child. A block that no id holds gives `undefined`.
+ * Read one block by its id. An atom gives the block with its bindings, and each binding gives no hash. A
+ * section gives its own fields and the id of each child. A block that no id holds gives `undefined`.
  */
 export function readBlock(draft, id) {
     const found = locate(draft, id)?.block;
@@ -105,5 +119,7 @@ export function readBlock(draft, id) {
     if (found.kind === "section") {
         return { kind: "section", id: found.id, title: found.title, childIds: found.blocks.map((child) => child.id) };
     }
-    return found;
+    // The stored atom and the read atom differ in the stamped hash alone, and the walk removes that field.
+    // Thus the assertion states what the walk did.
+    return stripReferenceHashes(found);
 }

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

@@ -5,7 +5,7 @@
  */
 import { err, ok } from "neverthrow";
 import { asFiniteNumber, cellMatchesFilterValue, checkCitationAssertion, checkValueAssertion } from "./assert-rules.js";
-import { columnsHeldByNoRow, fileTypeHoldsNoCell, snapshotEntry, } from "./reference-resolver.js";
+import { applyRowBound, columnsHeldByNoRow, fileTypeHoldsNoCell, snapshotEntry, } from "./reference-resolver.js";
 /** 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 };
@@ -79,10 +79,21 @@ function resolveArtifactTable(reference, snapshot) {
     if (fileTypeHoldsNoCell(tableFileType)) {
         return fail(reference, "unreadable-artifact", `the ${tableFileType} at ${reference.path} holds no cell to read`);
     }
-    const rows = artifact.rows ?? [];
+    // The bound ranks the rows as the artifact holds them, thus a bound over a column that the subset
+    // below leaves out still ranks them. An unknown bound column addresses nothing, exactly as an unknown
+    // subset column does.
+    const bound = reference.rowBound;
+    const allRows = artifact.rows ?? [];
+    if (bound !== undefined && columnsHeldByNoRow(allRows, [bound.column]).length > 0) {
+        return fail(reference, "locator-out-of-range", `the row bound names column ${bound.column}, which the table at ${reference.path} does not hold`);
+    }
+    const rows = bound === undefined ? allRows : applyRowBound(allRows, bound);
+    // The page states the shown count against the count of the artifact. This read is the one place that
+    // holds both, thus a bounded table carries the pre-bound total out with its rows.
+    const total = bound === undefined ? {} : { total: allRows.length };
     const columns = reference.columns;
     if (columns === undefined) {
-        return ok({ type: "table", rows });
+        return ok({ type: "table", rows, ...total });
     }
     // A name that no row holds addresses nothing. Without this check a projection onto an invented column
     // gives an empty cell for each row and still resolves, which is the fabrication that grounding exists
@@ -102,7 +113,7 @@ function resolveArtifactTable(reference, snapshot) {
         }
         return projected;
     });
-    return ok({ type: "table", rows: projectedRows, columns });
+    return ok({ type: "table", rows: projectedRows, columns, ...total });
 }
 function resolveArtifactFile(reference, snapshot) {
     const artifact = snapshotEntry(snapshot, reference.path);

package/dist/report-model/pin-snapshot.d.ts

@@ -7,24 +7,42 @@
  *
  * 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 pin must run at the anchor itself.
+ *
+ * The snapshot carries the citation evidence beside the artifact map. The pinned set is the literature
+ * that the synthesis engaged, and two fields of a run synthesis carry it: the key references and the
+ * references of each finding. The records live in the run tree on disk. Thus the pin reads that tree
+ * through the workspace-root seam of the caller.
+ *
+ * A reference that carries a short citation also pins a bibliography record beside its key. The key list
+ * keeps the membership role, thus the record map is optional and it changes no resolution.
  */
 import { type Result } from "neverthrow";
 import type { Querier } from "../state/db.js";
+import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { ReportSnapshot } from "./reference-resolver.js";
 /**
- * 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.
+ * The reason that the pin gave no snapshot. The ledger read and the run listing are the two operations
+ * that can fail. An analysis with no registered artifact and an analysis with no synthesis on disk are
+ * normal answers, thus absence is not a member of this set. `cause` carries the underlying fault for a
+ * log.
  */
 export type PinSnapshotError = {
-    kind: "ledger-read-failed";
+    kind: "ledger-read-failed" | "run-listing-failed";
     cause: unknown;
 };
+/** The construction options of the pin. */
+export interface PinReportSnapshotOptions {
+    /**
+     * The workspace-root seam of the caller. The citation evidence sits on disk, thus a composition
+     * that binds no seam pins the artifact map alone.
+     */
+    readonly resolveWorkspaceRoot?: ResolveWorkspaceRoot;
+}
 /**
- * Pin the snapshot of one analysis from the artifact ledger.
+ * Pin the snapshot of one analysis from the artifact ledger and from the synthesis records of its runs.
  *
  * 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 pinReportSnapshot(pool: Querier, analysisId: string): Promise<Result<ReportSnapshot, PinSnapshotError>>;
+export declare function pinReportSnapshot(pool: Querier, analysisId: string, options?: PinReportSnapshotOptions): Promise<Result<ReportSnapshot, PinSnapshotError>>;