@inflexa-ai/harness 0.20.0 → 0.21.1

package/dist/tools/report-session/list-artifacts.js

@@ -0,0 +1,197 @@
+/**
+ * The pinned-artifact listing tool of a report session.
+ *
+ * The tool reads the frozen snapshot of the thread, and it gives the pinned set: the path, the content
+ * hash, the file type, and the header columns of a tabular artifact, plus the pinned citations with the
+ * short citation of each. Thus one call orients the agent, and a reference binds to a path or to a
+ * citation key of that set.
+ *
+ * The order is the code-unit order of the path. Two calls over one snapshot give one listing, thus the
+ * agent reads a stable set. A snapshot can pin many thousands of staged inputs, thus the listing stops at
+ * a cap and it carries the total count and a truncation marker.
+ *
+ * The columns come from a bounded header read of a listed entry. The path of a snapshot entry is
+ * untrusted, thus the read contains it with the one workspace-path resolver first. The extension gates
+ * the read, because a file type states a role and not a data format.
+ *
+ * An absent file, an unreadable file, and an unresolvable workspace root each give no columns and no
+ * error. Absence is a normal condition here: the listing is orientation, and the hash is the evidence.
+ */
+import { ok } from "neverthrow";
+import { open } from "node:fs/promises";
+import { extname } from "node:path";
+import { z } from "zod";
+import { resolveWorkspacePath } from "../../workspace/paths.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { tryFs } from "../../lib/fs-result.js";
+import { defaultErrorFields } from "../../lib/logger.js";
+import { citationRecordOf, fileTypeHoldsNoCell } from "../../report-model/reference-resolver.js";
+import { defineTool } from "../define-tool.js";
+import { openReportThread } from "../report-authoring/authoring-tools.js";
+/** The empty input. The tool lists the pinned set of the thread, thus it needs no field. */
+const listPinnedArtifactsInput = z.object({});
+/**
+ * The cap of the header read. A header line of an analysis output sits far under it, and a file with no
+ * newline at all costs this many bytes and no more.
+ */
+const HEADER_CAP_BYTES = 16 * 1024;
+/**
+ * The cap of the listing. A snapshot pins each staged input of the analysis, and such a set can hold
+ * many thousands of entries. One entry costs one file read, thus the cap bounds both the reply and the
+ * work of the call.
+ */
+const LISTING_CAP = 200;
+/**
+ * The two extensions that carry a header line, each with its delimiter.
+ *
+ * The extension decides, because the bytes carry no declaration and a file type states a role alone. A
+ * minified JSON under `output/` splits into hundreds of names that address nothing, and a binary splits
+ * into unreadable text. Thus an entry with another extension reads no header.
+ */
+const HEADER_DELIMITERS = new Map([
+    [".csv", ","],
+    [".tsv", "\t"],
+]);
+/** The header delimiter of a path, or `undefined` when the extension carries no header. */
+function delimiterOf(path) {
+    return HEADER_DELIMITERS.get(extname(path).toLowerCase());
+}
+/**
+ * Read the first line of a file under the cap, or give `undefined` when the bytes do not come back.
+ *
+ * The read takes a bounded byte window, thus a file of any size costs the cap. An absent file and a
+ * genuine read fault both give `undefined`, because the listing reports no error for a header.
+ */
+async function readHeaderLine(absolute) {
+    const head = await tryFs("listPinnedArtifacts.readHeader", async () => {
+        const handle = await open(absolute, "r");
+        try {
+            const buffer = Buffer.alloc(HEADER_CAP_BYTES);
+            const { bytesRead } = await handle.read(buffer, 0, HEADER_CAP_BYTES, 0);
+            return { text: buffer.subarray(0, bytesRead).toString("utf8"), filled: bytesRead === HEADER_CAP_BYTES };
+        }
+        finally {
+            await handle.close();
+        }
+    }, { path: absolute, onAbsent: () => undefined }).unwrapOr(undefined);
+    if (head === undefined) {
+        return undefined;
+    }
+    const line = head.text.split(/\r?\n/, 1)[0];
+    if (line.length === 0) {
+        return undefined;
+    }
+    return { line, cut: head.filled && !head.text.includes("\n") };
+}
+/**
+ * Split a header line into column names on the delimiter, or give `undefined` when no whole name comes
+ * out of it.
+ *
+ * A double quote makes a field that can hold the delimiter itself, thus the naive split gives wrong
+ * names. A cut line ends inside its last name, and an agent writes a column name into a locator. Both
+ * conditions give no columns, because a wrong name is worse than an absent one.
+ */
+function columnsOf(read, delimiter) {
+    if (read.line.includes('"')) {
+        return undefined;
+    }
+    const names = read.line.split(delimiter).map((name) => name.trim());
+    const whole = read.cut ? names.slice(0, -1) : names;
+    return whole.length > 0 ? whole : undefined;
+}
+/**
+ * The header columns of a file on disk, or `undefined` when the file gives none.
+ *
+ * `path` decides whether the file carries a header at all, and `absolute` is where the bytes sit. The
+ * derivation tool reads the columns of its own output the same way, thus the two surfaces describe a table
+ * with one rule.
+ */
+export async function readHeaderColumns(path, absolute) {
+    const delimiter = delimiterOf(path);
+    if (delimiter === undefined) {
+        return undefined;
+    }
+    const read = await readHeaderLine(absolute);
+    return read === undefined ? undefined : columnsOf(read, delimiter);
+}
+/**
+ * Make the pinned-artifact listing tool over the session-state gateway.
+ *
+ * The tool reads the thread id from the scope of the call, and it loads the snapshot through the gateway.
+ * Thus one factory serves every thread, and the tool holds no per-session value.
+ */
+export function createListPinnedArtifactsTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("list-pinned-artifacts");
+    return defineTool({
+        id: "list_pinned_artifacts",
+        description: "List the pinned evidence of this session. Each entry gives the path of an artifact, its content hash, its file type, " +
+            "and the header columns of a .csv or a .tsv file. Another extension, a header line that holds a double quote, and a " +
+            "file whose bytes do not read each give no columns. " +
+            `The listing gives a maximum of ${LISTING_CAP} entries: "total" gives the size of the pinned set, and "truncated" says that the ` +
+            "set holds more artifacts than this listing names. " +
+            '"citations" gives the pinned literature of this session. Each entry carries "key", the citation id in the "idKind:id" form, and ' +
+            '"citation", the short citation of the paper. A key that the pin recorded no citation for carries no "citation". A citation block ' +
+            "binds to a key of this list, thus take a key from here and never from a refusal. " +
+            "The pin freezes at the start of the session, thus a reference binds to an artifact of this pinned set. " +
+            "Read it to orient before you bind a block, and to choose the column that a locator names. " +
+            "A reference names the path alone: the session stamps the hash from this evidence.",
+        inputSchema: listPinnedArtifactsInput,
+        executionMode: "inline",
+        describeCall: "none",
+        // The size of the listing is what a watcher reads, and the cap makes that size differ from the
+        // pinned set. Thus a truncated listing names the total beside the count, and a whole listing names
+        // the count alone, because a total that equals the count says the same thing two times.
+        describeResult: (_input, result) => {
+            if (result.outcome !== "listed") {
+                return result.outcome;
+            }
+            const count = result.artifacts.length;
+            const listed = `${count} ${count === 1 ? "artifact" : "artifacts"}`;
+            return result.truncated ? `${listed} of ${result.total}` : listed;
+        },
+        execute: async (_input, ctx) => {
+            const opened = await openReportThread(deps.gateway, ctx.session.scope);
+            if (opened.isErr()) {
+                return ok({ outcome: "refused", refusal: opened.error });
+            }
+            const { threadId, analysisId, state } = opened.value;
+            const paths = Object.keys(state.snapshot.artifacts).sort();
+            // The cap cuts the tail of the same order, thus a truncated listing is a prefix of the whole
+            // listing and a second call over one snapshot names the same entries.
+            const listed = paths.slice(0, LISTING_CAP);
+            // The seam signals an unresolvable resource by a throw. The listing still serves the path and
+            // the hash of each entry, thus the fault costs the columns alone and never the whole call.
+            let root;
+            try {
+                root = deps.resolveWorkspaceRoot(analysisId);
+            }
+            catch (cause) {
+                logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
+            }
+            const artifacts = [];
+            for (const path of listed) {
+                const entry = state.snapshot.artifacts[path];
+                const fileType = entry.fileType;
+                const artifact = { path, hash: entry.hash, ...(typeof fileType === "string" ? { fileType } : {}) };
+                if (root !== undefined && !fileTypeHoldsNoCell(fileType)) {
+                    const resolved = resolveWorkspacePath({ workspaceRoot: root, analysisId, path });
+                    if (resolved.kind === "ok") {
+                        const columns = await readHeaderColumns(path, resolved.absolute);
+                        if (columns !== undefined) {
+                            artifact.columns = columns;
+                        }
+                    }
+                }
+                artifacts.push(artifact);
+            }
+            // The pin stores the citation keys sorted, thus the listing keeps that order. A snapshot that
+            // pinned no citation gives an empty list, and an empty list is a complete answer. A key with no
+            // pinned record lists bare, thus a stored pin that holds no record map still orients the agent.
+            const citations = (state.snapshot.citations ?? []).map((key) => {
+                const record = citationRecordOf(state.snapshot.citationRecords, key);
+                return record === undefined ? { key } : { key, citation: record.citation };
+            });
+            return ok({ outcome: "listed", artifacts, total: paths.length, truncated: paths.length > listed.length, citations });
+        },
+    });
+}

package/dist/tools/report-session/preview-report.d.ts

@@ -6,6 +6,12 @@
  * resolves each reference through the injected resolver, bridges the resolved values into the render model,
  * and renders the page.
  *
+ * The renderer writes no file. It gives the page and the data asset of each table, and this tool stages
+ * them beside the figures. It also writes the script of each derivation that the document references, from
+ * the text of the durable record. The shipped libraries and fonts stage under `assets/deps/`, and each
+ * report-side file at the root of `assets/`. The stage is authoritative over that root: what this preview
+ * wrote stays, and each other file goes.
+ *
  * The page and its staged assets land in `report-sessions/{threadId}/` under the workspace root. That
  * namespace belongs to this path alone, thus the tool never writes under the old `previews/` or `reports/`
  * trees. The result carries the absolute page path, thus a local host shows the page with no seam.

package/dist/tools/report-session/preview-report.js

@@ -6,6 +6,12 @@
  * resolves each reference through the injected resolver, bridges the resolved values into the render model,
  * and renders the page.
  *
+ * The renderer writes no file. It gives the page and the data asset of each table, and this tool stages
+ * them beside the figures. It also writes the script of each derivation that the document references, from
+ * the text of the durable record. The shipped libraries and fonts stage under `assets/deps/`, and each
+ * report-side file at the root of `assets/`. The stage is authoritative over that root: what this preview
+ * wrote stays, and each other file goes.
+ *
  * The page and its staged assets land in `report-sessions/{threadId}/` under the workspace root. That
  * namespace belongs to this path alone, thus the tool never writes under the old `previews/` or `reports/`
  * trees. The result carries the absolute page path, thus a local host shows the page with no seam.
@@ -25,19 +31,21 @@
  * control-flow exception propagate.
  */
 import { err, ok } from "neverthrow";
-import { copyFile, mkdir, writeFile } from "node:fs/promises";
-import { createRequire } from "node:module";
+import { copyFile, mkdir, readdir, rm, writeFile } from "node:fs/promises";
 import { extname, join } from "node:path";
+import { relative as relativePosix } from "node:path/posix";
 import { z } from "zod";
-import { resolveWorkspacePath } from "../../workspace/paths.js";
+import { reportSessionDir, resolveWorkspacePath } from "../../workspace/paths.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { describeFsError, tryFsWrite } from "../../lib/fs-result.js";
 import { defaultErrorFields } from "../../lib/logger.js";
+import { referencedPaths, walkBlocks } from "../../report-model/block-walk.js";
 import { computeDraftHash } from "../../report-model/draft-hash.js";
 import { finishDraft } from "../../report-model/draft-finish.js";
 import { resolveDocumentReferences } from "../../report-model/validate.js";
 import { bridgeValues } from "../../report-render/value-bridge.js";
-import { PAGE_ASSETS } from "../../report-render/assets.js";
+import { resolvePageAssetFromInstallation } from "../../report-render/asset-lookup.js";
+import { ASSETS_DIR, DEPS_DIR, derivationScriptName, PAGE_ASSETS, stagedSource, tableSidecarName } from "../../report-render/assets.js";
 import { renderReportPage } from "../../report-render/render.js";
 import { defineTool } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
@@ -58,13 +66,6 @@ function assetFileName(file) {
 function figureSourcePolicy(file) {
     return `assets/${assetFileName(file)}`;
 }
-/**
- * The resolver of a package source. A manifest entry names a module specifier, and the resolution reads
- * the installation of the harness. Thus the staged bytes are the bytes of the pinned version.
- */
-const moduleResolver = createRequire(import.meta.url);
-/** The default asset lookup: the module resolution of the installation of the harness. */
-const resolvePageAssetFromInstallation = (specifier) => moduleResolver.resolve(specifier);
 /**
  * Pair each block with the resolved value of its binding, in document order.
  *
@@ -110,6 +111,77 @@ function collectResolutions(blocks, resolvedByBlock) {
     }
     return resolutions;
 }
+/**
+ * The sidecar of each table block of the document, in document order.
+ *
+ * A table card offers the whole table as a download, and the download is the pinned file itself and never a
+ * re-serialization of it. The card spells the staged name through `tableSidecarName`, thus the stage reads
+ * that same function and the link and the file cannot disagree.
+ *
+ * A chart binds a table too, and it holds no card. Thus the walk reads the table blocks alone.
+ */
+function collectTableSidecars(blocks) {
+    const sidecars = [];
+    const visit = (block) => {
+        if (block.kind === "section") {
+            for (const child of block.blocks) {
+                visit(child);
+            }
+            return;
+        }
+        if (block.kind === "table") {
+            sidecars.push({ blockId: block.id, name: tableSidecarName(block.binding.hash, block.binding.path), path: block.binding.path });
+        }
+    };
+    for (const block of blocks) {
+        visit(block);
+    }
+    return sidecars;
+}
+/**
+ * The derivation records that the document references, in the order that they landed.
+ *
+ * A binding names an output path, thus the used set is the intersection of the recorded paths and the paths
+ * of the document. The record of a dropped block stays in the durable state, and this walk leaves it out.
+ * Thus the page states the chain of what it shows, and the stage writes the script of what it states.
+ */
+function referencedDerivations(document, derivations) {
+    if (derivations.length === 0) {
+        return [];
+    }
+    const named = referencedPaths(walkBlocks(document.sections).references);
+    return derivations.filter((record) => named.has(record.outputPath));
+}
+/**
+ * The chain of one record, with the two relative links that its appendix entry carries.
+ *
+ * The script link names the staged asset through the shared name function, thus the link and the file that
+ * the stage writes cannot disagree. The output link is the path of the derived file against the directory of
+ * the page. The derived table already sits inside the session directory, thus the link needs no copy.
+ */
+function chainOf(record, sessionDir) {
+    return {
+        outputPath: record.outputPath,
+        sources: record.sources,
+        scriptHash: record.scriptHash,
+        scriptSource: stagedSource(derivationScriptName(record.scriptHash)),
+        outputSource: relativePosix(sessionDir, record.outputPath),
+    };
+}
+/**
+ * The script of each referenced derivation, keyed by its staged name.
+ *
+ * Two records of one script text carry one hash, thus they take one name and the map holds one entry. The
+ * name is content-addressed, thus an amended script stages beside no stale copy of itself and the sweep
+ * removes the name that the new page does not reference.
+ */
+function scriptAssets(records) {
+    const scripts = new Map();
+    for (const record of records) {
+        scripts.set(derivationScriptName(record.scriptHash), record.script);
+    }
+    return scripts;
+}
 /**
  * Resolve each reference of the document, and split the resolutions from the unresolved references.
  *
@@ -136,9 +208,14 @@ async function resolveDocument(document, resolver, snapshot) {
  * thus the containment test runs before any copy and reuses the one workspace-path resolver. A source
  * outside the root refuses and names the block, and no copy runs.
  *
- * The page references the chart runtime and the fonts under the same `assets/` directory, thus one copy
- * loop stages the figures and the manifest entries together. The manifest is never empty, thus the assets
- * directory exists beside every page.
+ * The page references the chart runtime and the fonts under `assets/deps/`, and each report-side file at
+ * the root of `assets/`. Each manifest entry names its own subpath, thus the copy loop reads the manifest
+ * and it spells no layout of its own. The manifest is never empty, thus both directories exist beside every
+ * page.
+ *
+ * The data assets and the derivation scripts are the parts that this preview produces rather than the disk.
+ * They write after the copies and before the page. The sweep then runs, and the root of the directory holds
+ * the closure of this page alone.
  */
 async function renderToWorkspace(args) {
     let root;
@@ -148,31 +225,47 @@ async function renderToWorkspace(args) {
     catch (cause) {
         return err({ kind: "fs", error: { type: "read_failed", op: "preview.resolveWorkspaceRoot", path: args.analysisId, cause } });
     }
-    const sessionDir = join(root, "report-sessions", args.threadId);
-    const assetsDir = join(sessionDir, "assets");
+    const sessionDir = join(root, reportSessionDir(args.threadId));
+    // The page addresses each staged file through `assetSource`, which spells the same segment. Thus the
+    // directory that receives the copies comes from that one constant, and never from a literal here.
+    const assetsDir = join(sessionDir, ASSETS_DIR);
+    const depsDir = join(assetsDir, DEPS_DIR);
     const pagePath = join(sessionDir, "index.html");
     // Each bound figure, contained and deduplicated by its staged name, mapped to its host source.
-    const sources = new Map();
+    const reportFiles = new Map();
     for (const resolution of args.resolutions) {
         if (resolution.kind !== "figure" || resolution.resolved.type !== "file") {
             continue;
         }
         const file = resolution.resolved;
         const name = assetFileName(file);
-        if (sources.has(name)) {
+        if (reportFiles.has(name)) {
             continue;
         }
         const resolved = resolveWorkspacePath({ workspaceRoot: root, analysisId: args.analysisId, path: file.path });
         if (resolved.kind !== "ok") {
             return err({ kind: "figure-out-of-scope", blockId: resolution.blockId, path: file.path });
         }
-        sources.set(name, resolved.absolute);
+        reportFiles.set(name, resolved.absolute);
     }
-    // Each manifest entry, mapped from its staged name to the file that the asset lookup gives. A specifier
-    // that does not resolve is a fault of the installation, thus it rides the `fs` kind.
+    // Each table sidecar: the pinned bytes themselves, under the name that the download link of the card
+    // spells. The path of a snapshot entry is untrusted, thus the containment test runs here too.
+    for (const sidecar of args.sidecars) {
+        if (reportFiles.has(sidecar.name)) {
+            continue;
+        }
+        const resolved = resolveWorkspacePath({ workspaceRoot: root, analysisId: args.analysisId, path: sidecar.path });
+        if (resolved.kind !== "ok") {
+            return err({ kind: "figure-out-of-scope", blockId: sidecar.blockId, path: sidecar.path });
+        }
+        reportFiles.set(sidecar.name, resolved.absolute);
+    }
+    // Each manifest entry, mapped from its staged subpath to the file that the asset lookup gives. A
+    // specifier that does not resolve is a fault of the installation, thus it rides the `fs` kind.
+    const depsFiles = new Map();
     for (const asset of PAGE_ASSETS) {
         try {
-            sources.set(asset.file, args.resolvePageAsset(asset.specifier));
+            depsFiles.set(asset.file, args.resolvePageAsset(asset.specifier));
         }
         catch (cause) {
             return err({ kind: "fs", error: { type: "read_failed", op: "preview.resolveAsset", path: asset.specifier, cause } });
@@ -182,22 +275,66 @@ async function renderToWorkspace(args) {
     if (madeSession.isErr()) {
         return err({ kind: "fs", error: madeSession.error });
     }
-    const madeAssets = await tryFsWrite("preview.mkdir", () => mkdir(assetsDir, { recursive: true }), { path: assetsDir });
+    // The recursive make covers the assets directory itself, thus one call answers for both levels.
+    const madeAssets = await tryFsWrite("preview.mkdir", () => mkdir(depsDir, { recursive: true }), { path: depsDir });
     if (madeAssets.isErr()) {
         return err({ kind: "fs", error: madeAssets.error });
     }
-    for (const [name, source] of sources) {
+    for (const [name, source] of [...reportFiles, ...depsFiles]) {
         const copied = await tryFsWrite("preview.copyFile", () => copyFile(source, join(assetsDir, name)), { path: source });
         if (copied.isErr()) {
             return err({ kind: "fs", error: copied.error });
         }
     }
+    // A data asset is source text that the renderer derived, and a script is the text of a durable record.
+    // Neither one sits on disk under its staged name, thus both write and neither one copies.
+    const texts = [...args.dataAssets.map((asset) => [asset.name, asset.bytes]), ...args.scripts];
+    for (const [name, text] of texts) {
+        const assetPath = join(assetsDir, name);
+        const wroteAsset = await tryFsWrite("preview.writeFile", () => writeFile(assetPath, text, "utf8"), { path: assetPath });
+        if (wroteAsset.isErr()) {
+            return err({ kind: "fs", error: wroteAsset.error });
+        }
+    }
     const wrote = await tryFsWrite("preview.writeFile", () => writeFile(pagePath, args.page, "utf8"), { path: pagePath });
     if (wrote.isErr()) {
         return err({ kind: "fs", error: wrote.error });
     }
+    const staged = new Set([...reportFiles.keys(), ...texts.map(([name]) => name)]);
+    await sweepAssets(assetsDir, staged, args.logger);
     return ok(pagePath);
 }
+/**
+ * Remove each report-side file of the assets directory that this preview did not stage.
+ *
+ * The stage is authoritative: the root of the directory holds the closure of the page and nothing else. A
+ * block that goes leaves a stale data asset, a stale sidecar, a stale figure, and the script of a derivation
+ * that nothing binds. Each one costs disk and misleads a reader who opens the directory. The staged set is
+ * what this run wrote, thus the sweep needs no read of the page.
+ *
+ * The `deps/` directory holds the shipped libraries and fonts. The manifest governs that set, and the stage
+ * writes each entry of it on every run. Thus the sweep passes over the directory whole.
+ *
+ * A sweep fault costs the cleanup alone. The page and its assets are on disk and complete, thus a failed
+ * listing and a failed removal each log and the preview still reports the page.
+ */
+async function sweepAssets(assetsDir, staged, logger) {
+    const listed = await tryFsWrite("preview.readdir", () => readdir(assetsDir), { path: assetsDir });
+    if (listed.isErr()) {
+        logger.warn("the assets directory did not list", { path: assetsDir, detail: describeFsError(listed.error) });
+        return;
+    }
+    for (const entry of listed.value) {
+        if (entry === DEPS_DIR || staged.has(entry)) {
+            continue;
+        }
+        const stale = join(assetsDir, entry);
+        const removed = await tryFsWrite("preview.rm", () => rm(stale, { force: true, recursive: true }), { path: stale });
+        if (removed.isErr()) {
+            logger.warn("a stale asset did not go", { path: stale, detail: describeFsError(removed.error) });
+        }
+    }
+}
 /**
  * Make the render-and-preview tool over the session-state gateway and the render seams.
  *
@@ -217,14 +354,19 @@ export function createPreviewReportTool(deps) {
         inputSchema: previewReportInput,
         executionMode: "inline",
         describeCall: "none",
+        // The page path is the one fact of a preview that a watcher wants, and it exists only in the
+        // result. Each other arm is a degraded condition whose kind already names it, thus the kind
+        // stands as the line. A stamp failure is such an arm: the page landed, but the marker did not,
+        // and a line that named the page would read as a clean pass.
+        describeResult: (_input, result) => (result.outcome === "rendered" ? `page ${result.pagePath}` : result.outcome),
         execute: async (_input, ctx) => {
             const opened = await openReportThread(deps.gateway, ctx.session.scope);
             if (opened.isErr()) {
                 return ok({ outcome: "refused", refusal: opened.error });
             }
-            const { threadId, analysisId, state } = opened.value;
+            const { threadId, analysisId, state, derivations } = opened.value;
             const { document: draft, snapshot } = state;
-            const finished = finishDraft(draft, snapshot);
+            const finished = finishDraft(draft, snapshot, derivations);
             if (!finished.valid) {
                 return ok({ outcome: "gaps", gaps: finished.gaps });
             }
@@ -251,7 +393,13 @@ export function createPreviewReportTool(deps) {
             if (bridged.isErr()) {
                 return ok({ outcome: "bridge-mismatch", mismatches: bridged.error });
             }
-            const rendered = renderReportPage(document, bridged.value);
+            // The citation records are the bibliography of the pin, and the derivation records are the chain
+            // of each derived path. Both ride the render call and never the value map, because the appendix
+            // reads them beside the cards and the value map is keyed by block. The chain carries the two
+            // relative links of its entry, thus the renderer states them and it stages nothing.
+            const used = referencedDerivations(document, derivations);
+            const sessionDir = reportSessionDir(threadId);
+            const rendered = renderReportPage(document, bridged.value, snapshot.citationRecords, used.map((record) => chainOf(record, sessionDir)));
             if (rendered.isErr()) {
                 return ok({ outcome: "render-problems", problems: rendered.error });
             }
@@ -261,7 +409,11 @@ export function createPreviewReportTool(deps) {
                 analysisId,
                 threadId,
                 resolutions,
-                page: rendered.value,
+                sidecars: collectTableSidecars(document.sections),
+                dataAssets: rendered.value.dataAssets,
+                scripts: scriptAssets(used),
+                page: rendered.value.html,
+                logger,
             });
             if (written.isErr()) {
                 const failure = written.error;

package/dist/tools/report-session/record-version.d.ts

@@ -1,9 +1,9 @@
 /**
  * The record tool of a report session.
  *
- * The tool records one version of the report. The store is append-only with no delete, thus a version that
- * the gate did not accept must never exist. The tool runs the whole gate first, and only a pass reaches the
- * store.
+ * The tool records one version of the report. A version that the gate did not accept must never stand, thus
+ * the tool runs the whole gate first, and only a pass reaches the store. The gate and the look rule run on
+ * every record, the first and each later one alike.
  *
  * The gate has three parts, in order of cost. The finish gates the schema, the unique ids, and the
  * structural tier, and a gap list returns as data. The look-before-record rule then compares the seen hash
@@ -18,8 +18,15 @@
  * before the resolver constructs.
  *
  * On a pass the store records the document that the gate validated, the pinned snapshot, and the anchor from
- * the thread row. The one-per-thread rule of the store bounds a concurrent race, and that refusal returns as
- * data. The outcome of a pass carries the version id.
+ * the thread row. A record on a thread that holds a version replaces that version whole, under the same
+ * version id. Thus the loop is unbounded: the agent amends, looks again, and records again, and the stored
+ * version equals the page that the last look accepted. A refused record leaves the stored version as it was.
+ * The outcome of a pass carries the version id, and it names a replacement.
+ *
+ * The prune runs after the version lands. It removes the output file of each derivation that the recorded
+ * document does not reference, under the `derived/` directory of the session alone. The records stay
+ * append-only, because the bytes are reproducible from the script and the sources. A failed removal logs and
+ * changes no outcome.
  */
 import { z } from "zod";
 import type { AuthContext } from "../../auth/types.js";
@@ -29,6 +36,7 @@ import { type FinishGap } from "../../report-model/draft-finish.js";
 import type { ReferenceResolver } from "../../report-model/reference-resolver.js";
 import { type ResolutionFailure, type SchemaIssue } from "../../report-model/validate.js";
 import type { ReportVersionStore } from "../../state/report-versions.js";
+import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
 import { type Tool } from "../define-tool.js";
 import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
 /** The empty input. The tool records the current draft of the thread, thus it needs no field. */
@@ -41,8 +49,8 @@ export type RecordVersionInput = z.infer<typeof recordVersionInput>;
  * `gaps` names each completeness gap of the draft. `never-seen` means that no eyes ran on the current draft.
  * `stale-look` means that the eyes ran, and the agent then changed the draft. `root-unresolvable` means that
  * the resolver construction cannot resolve the workspace root. `invalid` names each gate failure, and a
- * resolution failure carries the block that holds it. `already-recorded` means that the thread already holds
- * a version. `recorded` carries the version id.
+ * resolution failure carries the block that holds it. `recorded` carries the version id, and `replaced` is
+ * true when the record wrote over the earlier version of the thread.
  */
 export type RecordVersionResult = {
     outcome: "refused";
@@ -64,27 +72,31 @@ export type RecordVersionResult = {
     schemaIssues?: SchemaIssue[];
     duplicateIds?: string[];
     resolutionFailures?: ResolutionFailure[];
-} | {
-    outcome: "already-recorded";
 } | {
     outcome: "record-failed";
     detail: string;
 } | {
     outcome: "recorded";
     versionId: string;
+    replaced: boolean;
 };
 /**
  * The construction deps of the record tool.
  *
- * `store` is the append-only version store. `threads` reads the anchor of the report thread, thus the
+ * `store` is the version store. `threads` reads the anchor of the report thread, thus the
  * version carries the parent conversation and the transcript position. `makeResolver` is optional, because a
  * resolver realization can be absent, and the gate needs one. It binds one analysis, thus the tool makes the
  * resolver over the scope of the call.
+ *
+ * `resolveWorkspaceRoot` maps the analysis of the call onto its workspace root. The prune reaches the
+ * derived directory of the session under that root, thus the seam is mandatory: a composition that bound
+ * none would record a version and leave every unused derivation on disk.
  */
 export interface RecordVersionToolDeps {
     readonly gateway: ReportSessionStateGateway;
     readonly store: ReportVersionStore;
     readonly threads: Pick<ThreadStore, "getThread">;
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly makeResolver?: (scope: {
         analysisId: string;
         auth: AuthContext;