@inflexa-ai/harness 0.19.2 → 0.21.0

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;

package/dist/tools/report-session/record-version.js

@@ -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,16 +18,28 @@
  * 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 { ok } from "neverthrow";
+import { rm } from "node:fs/promises";
+import { resolve as resolvePath, sep } from "node:path";
 import { z } from "zod";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { describeDbError } from "../../lib/db-result.js";
+import { describeFsError, tryFsWrite } from "../../lib/fs-result.js";
+import { referencedPaths, walkBlocks } from "../../report-model/block-walk.js";
 import { finishDraft } from "../../report-model/draft-finish.js";
 import { computeDraftHash } from "../../report-model/draft-hash.js";
 import { validateReport } from "../../report-model/validate.js";
+import { reportSessionDerivedDir, resolveWorkspacePath } from "../../workspace/paths.js";
 import { defineTool } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
 /** The empty input. The tool records the current draft of the thread, thus it needs no field. */
@@ -41,12 +53,66 @@ function describeRecordFailure(error) {
             return "the pinned snapshot is malformed";
         case "parent_analysis_mismatch":
             return "the parent version belongs to a different analysis";
-        case "thread_already_holds_version":
-            return "the thread already holds a recorded version";
         default:
             return describeDbError(error);
     }
 }
+/**
+ * Remove the output file of each derivation that the recorded document does not reference.
+ *
+ * The unused set is a set difference: a derivation is used when a binding of the recorded document names its
+ * output path. The document is the one that the gate validated, thus the prune reads what the version holds
+ * and never the draft.
+ *
+ * The prune reaches the `derived/` directory of the session alone. A record whose path resolves outside that
+ * directory is skipped, because this tool never removes a file that it does not own. A stale record from an
+ * earlier layout and a crafted path both land in that arm.
+ *
+ * The version already stands at this point. Thus each failure costs the cleanup alone: an unresolvable root,
+ * a path that escapes, and a failed removal each log and change no outcome. The records stay, and the bytes
+ * are reproducible from the script and the sources. The scope of the prune resolves inside the same guard as
+ * the root, because both builders throw and a throw here would read as a failure of a call that succeeded.
+ */
+async function pruneUnusedDerivations(args) {
+    if (args.derivations.length === 0) {
+        return;
+    }
+    const named = referencedPaths(walkBlocks(args.document.sections).references);
+    const unused = args.derivations.filter((record) => !named.has(record.outputPath));
+    if (unused.length === 0) {
+        return;
+    }
+    let root;
+    let derivedDir;
+    try {
+        root = args.resolveWorkspaceRoot(args.analysisId);
+        derivedDir = resolvePath(root, reportSessionDerivedDir(args.threadId));
+    }
+    catch (cause) {
+        args.logger.warn("the unused derivations did not prune", {
+            threadId: args.threadId,
+            analysisId: args.analysisId,
+            ...args.logger.errorFields(cause),
+        });
+        return;
+    }
+    for (const record of unused) {
+        const resolved = resolveWorkspacePath({ workspaceRoot: root, analysisId: args.analysisId, path: record.outputPath });
+        if (resolved.kind !== "ok" || !resolved.absolute.startsWith(derivedDir + sep)) {
+            args.logger.warn("an unused derivation sits outside the derived directory of the session", {
+                threadId: args.threadId,
+                analysisId: args.analysisId,
+                path: record.outputPath,
+            });
+            continue;
+        }
+        // An absent file is the normal condition of a prune that ran before, thus `force` treats it as done.
+        const removed = await tryFsWrite("record.rm", () => rm(resolved.absolute, { force: true }), { path: resolved.absolute });
+        if (removed.isErr()) {
+            args.logger.warn("an unused derivation did not go", { path: resolved.absolute, detail: describeFsError(removed.error) });
+        }
+    }
+}
 /**
  * Make the record tool over the session-state gateway, the version store, the thread store, and the
  * resolver.
@@ -61,18 +127,27 @@ export function createRecordVersionTool(deps) {
         description: "Record the current draft as one report version. The tool runs the whole gate first: it finishes the draft, " +
             "resolves each reference, matches each chart encoding, and matches each assert. An incomplete draft gives back the gap list, " +
             "and a failed reference gives back the block that broke. The tool records a version only after the eyes look at the current page. " +
-            "A thread holds one version, thus a second record gives back that the thread already holds one.",
+            "A thread holds one version, thus a later record replaces it whole. Amend the draft, look at the page again, and record again. " +
+            "After the version lands, the tool removes the file of each derived table that no block of the recorded report binds.",
         inputSchema: recordVersionInput,
         executionMode: "inline",
         describeCall: "none",
+        // The version id is the one durable product of the first record, thus the created arm names it. A
+        // later record writes over that same id, thus the line names the update and never reads as a
+        // refusal. Each other arm is a gate that refused, and the kind of the arm is what a watcher reads.
+        describeResult: (_input, result) => {
+            if (result.outcome !== "recorded")
+                return result.outcome;
+            return result.replaced ? "version updated" : `version ${result.versionId}`;
+        },
         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, seenDocumentHash } = opened.value;
+            const { threadId, analysisId, state, seenDocumentHash, 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 });
             }
@@ -127,10 +202,20 @@ export function createRecordVersionTool(deps) {
                 parentThreadId: thread.value.parentThreadId,
                 parentSeq: thread.value.parentSeq,
             });
-            return recorded.match((ref) => ok({ outcome: "recorded", versionId: ref.versionId }), (error) => {
-                if (error.type === "thread_already_holds_version") {
-                    return ok({ outcome: "already-recorded" });
-                }
+            if (recorded.isOk()) {
+                // The version stands from here. The prune reclaims the bytes of each derivation that the
+                // recorded document ignores, and it decides nothing about the outcome. It runs on each
+                // record, thus an output that an amend unbound goes at the next record.
+                await pruneUnusedDerivations({
+                    resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
+                    analysisId,
+                    threadId,
+                    document: finished.document,
+                    derivations,
+                    logger,
+                });
+            }
+            return recorded.match((ref) => ok({ outcome: "recorded", versionId: ref.versionId, replaced: ref.outcome === "replaced" }), (error) => {
                 logger.warn("the version did not record", { threadId, analysisId, reason: error.type });
                 return ok({ outcome: "record-failed", detail: describeRecordFailure(error) });
             });