@inflexa-ai/harness 0.20.0 → 0.21.0

package/dist/state/report-versions.d.ts

@@ -1,14 +1,17 @@
 /**
- * The report version store -- the append-only record of report versions.
+ * The report version store -- the one recorded version of each report thread.
  *
- * A version is one immutable row. It holds the block document, the pinned
- * snapshot, and the anchor. The store records a version and reads a version. It
- * never updates a recorded row, thus a correction is a new version.
+ * A version is one row. It holds the block document, the pinned snapshot, and the
+ * anchor. The store records a version and reads a version. A record on a thread
+ * that holds a version replaces the document, the snapshot, and the anchor of that
+ * row, whole. The version id stays, thus a consumer that names the version keeps
+ * its name.
  *
  * A thread holds at most one version, and a named unique constraint on the thread
- * id enforces it. The record reads nothing before the insert. A second record for
- * one thread trips the constraint, and the store maps that trip to the typed
- * refusal thread_already_holds_version.
+ * id enforces it. The record reads nothing before the write, and the constraint
+ * routes it: a fresh thread takes the insert arm, and a thread that holds a version
+ * takes the replace arm. The store writes the full triple each time, thus a partial
+ * update is not representable.
  *
  * The store keeps the snapshot and the anchor as given, and it never pins a
  * snapshot. A read parses the stored document and the stored snapshot with the
@@ -42,9 +45,14 @@ export interface RecordVersionInput {
     /** The earlier version that this one reuses. The parent must belong to the same analysis. */
     readonly parentVersionId?: string;
 }
-/** The stable reference of a freshly recorded version. */
+/** The stable reference of a recorded version, and how the record landed. */
 export interface RecordedVersionRef {
     readonly versionId: string;
+    /**
+     * `created` minted the row. `replaced` wrote over the one version of the
+     * thread, under the same version id.
+     */
+    readonly outcome: "created" | "replaced";
 }
 /**
  * A record the store refuses as data, before or in place of a row. Distinct from
@@ -54,9 +62,9 @@ export interface RecordedVersionRef {
  * refuses a malformed document or a malformed snapshot here as typed data, and
  * no row lands.
  *
- * A second record for one thread is `thread_already_holds_version`. The unique
- * constraint on the thread id trips, and the record maps that one constraint by
- * its name. Every other constraint trip stays a `DbError`.
+ * A second record for one thread is no refusal. The unique constraint on the
+ * thread id routes it into the replace arm, and the row carries the new triple.
+ * Every constraint trip stays a `DbError`.
  *
  * A `parentVersionId` naming no row is not one of these -- the self foreign key
  * refuses an unknown parent id, and `tryMutation` classifies that refusal as the
@@ -76,10 +84,6 @@ export type RecordVersionError = {
     readonly analysisId: string;
     readonly parentVersionId: string;
     readonly parentAnalysisId: string;
-} | {
-    readonly type: "thread_already_holds_version";
-    readonly op: string;
-    readonly threadId: string;
 } | DbError;
 /**
  * A stored row that a read cannot parse with the current schemas. It names the
@@ -109,8 +113,9 @@ export interface ReportVersionStore {
     /**
      * Record a version. The record parses the document, refuses a malformed value
      * as data with no row, and refuses a parent from a different analysis. It reads
-     * nothing before the insert. A second record for one thread refuses with
-     * thread_already_holds_version. The snapshot and the anchor store as given.
+     * nothing before the write. A record on a thread that holds a version replaces
+     * that row whole, under the same version id. The snapshot and the anchor store
+     * as given, and the reference names a creation or a replacement.
      */
     record(input: RecordVersionInput): ResultAsync<RecordedVersionRef, RecordVersionError>;
     /** One version by its id, or `null` when no row holds it. */

package/dist/state/report-versions.js

@@ -1,14 +1,17 @@
 /**
- * The report version store -- the append-only record of report versions.
+ * The report version store -- the one recorded version of each report thread.
  *
- * A version is one immutable row. It holds the block document, the pinned
- * snapshot, and the anchor. The store records a version and reads a version. It
- * never updates a recorded row, thus a correction is a new version.
+ * A version is one row. It holds the block document, the pinned snapshot, and the
+ * anchor. The store records a version and reads a version. A record on a thread
+ * that holds a version replaces the document, the snapshot, and the anchor of that
+ * row, whole. The version id stays, thus a consumer that names the version keeps
+ * its name.
  *
  * A thread holds at most one version, and a named unique constraint on the thread
- * id enforces it. The record reads nothing before the insert. A second record for
- * one thread trips the constraint, and the store maps that trip to the typed
- * refusal thread_already_holds_version.
+ * id enforces it. The record reads nothing before the write, and the constraint
+ * routes it: a fresh thread takes the insert arm, and a thread that holds a version
+ * takes the replace arm. The store writes the full triple each time, thus a partial
+ * update is not representable.
  *
  * The store keeps the snapshot and the anchor as given, and it never pins a
  * snapshot. A read parses the stored document and the stored snapshot with the
@@ -25,9 +28,8 @@ import { ReportDocumentSchema } from "../contracts/report-blocks.js";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
 import { parseSnapshot, reduceIssues } from "./snapshot-parse.js";
 /**
- * The name of the unique constraint on thread_id. Postgres reports it on a
- * duplicate-thread refusal, and the record matches it to map the trip to the
- * thread_already_holds_version refusal.
+ * The name of the unique constraint on thread_id. The write names it as its
+ * conflict target, thus the replace arm binds to the one row of the thread.
  */
 const THREAD_UNIQUE_CONSTRAINT = "cortex_report_versions_one_per_thread";
 const _assertRecordError = true;
@@ -39,13 +41,30 @@ const _assertReadError = true;
  */
 const VERSION_COLUMNS = "version_id, analysis_id, thread_id, parent_thread_id, parent_seq::text AS parent_seq, parent_version_id, document, snapshot, created_at";
 /**
- * The insert. The row carries no ordinal, thus the statement writes the given
- * columns directly. `created_at` takes the column default.
+ * The write. The row carries no ordinal, thus the statement writes the given
+ * columns directly. A fresh thread takes the insert arm, and `created_at` takes
+ * the column default. A thread that holds a version trips the named constraint,
+ * and the conflict target turns the trip into the replace of that one row.
+ *
+ * The replace arm writes each given column, thus the stored row equals the input.
+ * It writes neither `version_id` nor `created_at`: the version keeps its name, and
+ * the row keeps the time of its first record.
+ *
+ * The returned id names the row that stands. It equals the minted id on the insert
+ * arm alone, thus the caller reads which arm ran.
  */
-const INSERT_SQL = `INSERT INTO cortex_report_versions
+const RECORD_SQL = `INSERT INTO cortex_report_versions
     (version_id, analysis_id, thread_id, parent_thread_id, parent_seq,
      parent_version_id, document, snapshot)
-  VALUES ($1, $2, $3, $4, $5::bigint, $6, $7::jsonb, $8::jsonb)`;
+  VALUES ($1, $2, $3, $4, $5::bigint, $6, $7::jsonb, $8::jsonb)
+  ON CONFLICT ON CONSTRAINT ${THREAD_UNIQUE_CONSTRAINT} DO UPDATE SET
+    analysis_id = EXCLUDED.analysis_id,
+    parent_thread_id = EXCLUDED.parent_thread_id,
+    parent_seq = EXCLUDED.parent_seq,
+    parent_version_id = EXCLUDED.parent_version_id,
+    document = EXCLUDED.document,
+    snapshot = EXCLUDED.snapshot
+  RETURNING version_id`;
 function rowToVersion(row) {
     const document = ReportDocumentSchema.safeParse(row.document);
     if (!document.success) {
@@ -67,16 +86,6 @@ function rowToVersion(row) {
         createdAt: row.created_at,
     });
 }
-/**
- * Map an insert failure to a record refusal. A trip of the thread constraint is
- * thread_already_holds_version. Every other DbError stays unchanged.
- */
-function mapInsertError(error, threadId) {
-    if (error.type === "constraint_violation" && error.constraint === THREAD_UNIQUE_CONSTRAINT) {
-        return { type: "thread_already_holds_version", op: "report-versions.record", threadId };
-    }
-    return error;
-}
 /**
  * Create a `ReportVersionStore` bound to a Postgres pool. The
  * `cortex_report_versions` table is provisioned by the state-init DDL.
@@ -85,7 +94,7 @@ export function createReportVersionStore({ pool }) {
     /**
      * The analysis scope of a parent version, or `null` when no such row exists.
      * Absence is not a verdict here: an unknown parent id falls through to the
-     * insert, where the self foreign key refuses it as a `DbError`.
+     * write, where the self foreign key refuses it as a `DbError`.
      */
     function parentAnalysis(parentVersionId) {
         return tryQuery("report-versions.record.parentScope", () => pool.query({
@@ -105,13 +114,13 @@ export function createReportVersionStore({ pool }) {
         if (parsedSnapshot.isErr()) {
             return errAsync({ type: "malformed_snapshot", op: "report-versions.record", issues: parsedSnapshot.error });
         }
-        const insert = () => {
-            const versionId = randomUUID();
-            return tryMutation("report-versions.record.insert", async () => {
-                await pool.query({
-                    text: INSERT_SQL,
+        const write = () => {
+            const minted = randomUUID();
+            return tryMutation("report-versions.record.write", async () => {
+                const { rows } = await pool.query({
+                    text: RECORD_SQL,
                     values: [
-                        versionId,
+                        minted,
                         input.analysisId,
                         input.threadId,
                         input.parentThreadId,
@@ -121,11 +130,15 @@ export function createReportVersionStore({ pool }) {
                         JSON.stringify(input.snapshot),
                     ],
                 });
-                return { versionId };
-            }).mapErr((error) => mapInsertError(error, input.threadId));
+                // Each arm of the write returns its row. The replace arm keeps the
+                // version id of the row that stood, thus an id that differs from the
+                // minted one names a replacement.
+                const landed = rows[0]?.version_id ?? minted;
+                return { versionId: landed, outcome: landed === minted ? "created" : "replaced" };
+            });
         };
         if (input.parentVersionId === undefined) {
-            return insert();
+            return write();
         }
         const parentVersionId = input.parentVersionId;
         return parentAnalysis(parentVersionId).andThen((parentAnalysisId) => {
@@ -138,7 +151,7 @@ export function createReportVersionStore({ pool }) {
                     parentAnalysisId,
                 });
             }
-            return insert();
+            return write();
         });
     }
     function getVersion(versionId) {

package/dist/state/snapshot-parse.js

@@ -23,6 +23,11 @@ const ArtifactSnapshotSchema = z.object({
 });
 /** The citation list of a stored snapshot. A snapshot with no list reads as an absent field. */
 const CitationsSchema = z.array(z.string()).optional();
+/**
+ * The citation records of a stored snapshot, keyed by the citation key. A snapshot with no map reads as
+ * an absent field, thus a pin that predates the map loads the same as it did before.
+ */
+const CitationRecordsSchema = z.record(z.string(), z.object({ citation: z.string(), description: z.string().optional() })).optional();
 /** Reduce a zod error to the dotted path and the message of each issue. */
 export function reduceIssues(error) {
     return error.issues.map((issue) => ({
@@ -63,6 +68,10 @@ export function parseSnapshot(stored) {
     if (!citations.success) {
         return err(prefixIssues("citations", reduceIssues(citations.error)));
     }
+    const citationRecords = CitationRecordsSchema.safeParse(stored.citationRecords);
+    if (!citationRecords.success) {
+        return err(prefixIssues("citationRecords", reduceIssues(citationRecords.error)));
+    }
     // The map takes a null prototype, the same as the pin, thus a path such as
     // `__proto__` stays an ordinary entry and never reaches a prototype slot.
     const artifacts = Object.create(null);
@@ -78,5 +87,11 @@ export function parseSnapshot(stored) {
     if (issues.length > 0) {
         return err(issues);
     }
-    return citations.data === undefined ? ok({ artifacts }) : ok({ artifacts, citations: citations.data });
+    // An absent part stays absent in the parsed value. Thus a reload gives the same shape that the pin
+    // wrote, and an equality test over a stored snapshot holds across the round trip.
+    return ok({
+        artifacts,
+        ...(citations.data === undefined ? {} : { citations: citations.data }),
+        ...(citationRecords.data === undefined ? {} : { citationRecords: citationRecords.data }),
+    });
 }

package/dist/tools/define-tool.d.ts

@@ -116,6 +116,8 @@ export interface Tool<Input = unknown, Output = unknown> {
     readonly executionMode: ToolExecutionMode;
     /** See {@link ToolDefinition.describeCall}. Absent when the tool declares none. */
     describeCall?(input: Input): string;
+    /** See {@link ToolDefinition.describeResult}. Absent when the tool declares none. */
+    describeResult?(input: Input, result: Output): string;
     execute(input: Input, ctx: ToolContext): Promise<Result<Output, ToolError>>;
 }
 export interface ToolDefinition<Schema extends z.ZodType, Output> {
@@ -156,6 +158,36 @@ export interface ToolDefinition<Schema extends z.ZodType, Output> {
      * The hook never reaches the model.
      */
     describeCall: ((input: z.infer<Schema>) => string) | "none";
+    /**
+     * One line that names what THIS call PRODUCED — the outcome-time counterpart
+     * of `describeCall`. A page path, a recorded id, and a listed count are facts
+     * of the result, thus no hook over the input can name one. The finished event
+     * carries this line, and it carries the call detail when the hook gives
+     * nothing.
+     *
+     * The decision is OPTIONAL, unlike `describeCall`. A call always has an input
+     * to describe or an input that cannot distinguish it, thus that decision is
+     * forced. A result is different: a tool whose ok value adds no fact that a
+     * reader wants leaves the call detail to stand for the whole call. Thus the
+     * absent key is the whole of "this tool describes no result", and the `"none"`
+     * sentinel has no counterpart here.
+     *
+     * The hook runs on an ok outcome only. An error outcome already names itself,
+     * and a hook over a failed call reads a shape that does not exist.
+     *
+     * A hook is synchronous and pure — no I/O, no ambient state — and a
+     * description must never fail a call: the loop guards the call and drops the
+     * detail on any failure (see the tool-call-detail capability). The result
+     * arrives as the tool produced it, thus the hook reads a value of its own
+     * declared `Output` type and no parse stands between the two.
+     *
+     * Return whatever reads best. Normalization — one line, control characters
+     * removed, secrets redacted, length capped — happens once at the emit site,
+     * never here.
+     *
+     * The hook never reaches the model.
+     */
+    readonly describeResult?: (input: z.infer<Schema>, result: Output) => string;
     execute(input: z.infer<Schema>, ctx: ToolContext): Promise<Result<Output, ToolError>>;
 }
 /**

package/dist/tools/define-tool.js

@@ -75,6 +75,10 @@ export function defineTool(def) {
         // `typeof` is the discriminator, not equality with the sentinel, so a
         // hook that returns the string `"none"` still packages as a hook.
         ...(typeof def.describeCall === "function" ? { describeCall: def.describeCall } : {}),
+        // The same property-presence pattern as `describeCall`: a tool that
+        // declares no result hook carries no key, thus "has a hook" is one
+        // property check on either side.
+        ...(typeof def.describeResult === "function" ? { describeResult: def.describeResult } : {}),
         execute: def.execute,
     };
 }

package/dist/tools/detail-resolver.d.ts

@@ -15,8 +15,13 @@
  *   registry construction.
  *
  * It resolves through the same `computeDetail` the loop uses, so a reloaded
- * thread cannot show a different detail from the one the live turn showed.
- * Nothing is persisted: storage stays the pure model transcript.
+ * thread shows the same CALL detail the live turn showed.
+ *
+ * The bound is the input. A reload reconstructs from the persisted call alone, and a
+ * tool that describes its own RESULT names a fact that the input cannot carry — a page
+ * path, a recorded version. That line reaches the live surface on the finished event and
+ * it does not reappear here, thus a reloaded call falls back to its call detail. Nothing
+ * is persisted: storage stays the pure model transcript.
  */
 import { type ToolCallDetail } from "../loop/tool-detail.js";
 import type { Logger } from "../lib/logger.js";

package/dist/tools/detail-resolver.js

@@ -15,8 +15,13 @@
  *   registry construction.
  *
  * It resolves through the same `computeDetail` the loop uses, so a reloaded
- * thread cannot show a different detail from the one the live turn showed.
- * Nothing is persisted: storage stays the pure model transcript.
+ * thread shows the same CALL detail the live turn showed.
+ *
+ * The bound is the input. A reload reconstructs from the persisted call alone, and a
+ * tool that describes its own RESULT names a fact that the input cannot carry — a page
+ * path, a recorded version. That line reaches the live surface on the finished event and
+ * it does not reappear here, thus a reloaded call falls back to its call detail. Nothing
+ * is persisted: storage stays the pure model transcript.
  */
 import { computeDetail } from "../loop/tool-detail.js";
 import { createNoopLogger } from "../lib/console-logger.js";

package/dist/tools/iterate-report.d.ts

@@ -120,8 +120,8 @@ export declare const ReportBriefSchema: z.ZodObject<{
                 source: z.ZodString;
             }, z.core.$strip>>;
             chartType: z.ZodEnum<{
-                line: "line";
                 bar: "bar";
+                line: "line";
                 scatter: "scatter";
                 histogram: "histogram";
                 box: "box";

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

@@ -80,6 +80,7 @@ export function createPreviewSnapshotTool(state) {
                 return ok({
                     ok: true,
                     screenshotBase64: captured.screenshotBase64,
+                    coverage: captured.coverage,
                     consoleErrors: captured.consoleErrors,
                     failedRequests: captured.failedRequests,
                 });

package/dist/tools/report-authoring/authoring-tools.d.ts

@@ -22,12 +22,13 @@ import type { Scope } from "../../auth/types.js";
 import { type DraftRefusal } from "../../report-model/draft-operations.js";
 import { type OutlineEntry, type ReadableBlock } from "../../report-model/draft-read.js";
 import { type FinishResult } from "../../report-model/draft-finish.js";
-import { type DraftDocument } from "../../report-model/draft.js";
+import type { DraftDocument } from "../../report-model/draft.js";
 import type { ReportSnapshot } from "../../report-model/reference-resolver.js";
+import type { DerivationRecord } from "../../state/report-session-state.js";
 import { type Tool } from "../define-tool.js";
 /** The flat destination fields. An anchor is `before` or `after`, and a place is `start` or `end`. */
 declare const addBlockInput: z.ZodObject<{
-    block: z.ZodUnion<readonly [z.ZodType<import("../../report-model/draft.js").DraftBlock, unknown, z.core.$ZodTypeInternals<import("../../report-model/draft.js").DraftBlock, unknown>>, z.ZodUnknown]>;
+    block: z.ZodUnion<readonly [z.ZodType<import("../../report-model/authoring-grammar.js").AuthoringBlock, unknown, z.core.$ZodTypeInternals<import("../../report-model/authoring-grammar.js").AuthoringBlock, unknown>>, z.ZodUnknown]>;
     parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     place: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         end: "end";
@@ -44,7 +45,7 @@ declare const addBlockInput: z.ZodObject<{
 declare const changeBlockInput: z.ZodObject<{
     targetId: z.ZodString;
     title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    block: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<import("../../report-model/draft.js").DraftBlock, unknown, z.core.$ZodTypeInternals<import("../../report-model/draft.js").DraftBlock, unknown>>, z.ZodUnknown]>>;
+    block: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<import("../../report-model/authoring-grammar.js").AuthoringBlock, unknown, z.core.$ZodTypeInternals<import("../../report-model/authoring-grammar.js").AuthoringBlock, unknown>>, z.ZodUnknown]>>;
 }, z.core.$strip>;
 declare const removeBlockInput: z.ZodObject<{
     targetId: z.ZodString;
@@ -158,12 +159,17 @@ export interface ReportSessionState {
 export type SessionStateToken = DraftDocument | null;
 /**
  * The outcome of a gateway load. `found` carries the state, the analysis that owns the thread, the
- * concurrency token, and the seen-document hash of the look-before-record rule. `absent` and `wrong-type`
- * are permanent conditions, and `failed` is a transient fault that names its cause.
+ * concurrency token, the seen-document hash of the look-before-record rule, and the derivations of the
+ * session. `absent` and `wrong-type` are permanent conditions, and `failed` is a transient fault that names
+ * its cause.
  *
  * `seenDocumentHash` is the hash that the last eyes capture saw, or `null` before the first look. The record
  * tool compares it against the hash of the current draft, thus a never-seen page and a stale look each
  * refuse.
+ *
+ * `derivations` is the ledger of the session, in the order that the records landed. The snapshot already
+ * carries each derived path as a member, thus a tool that binds reads the snapshot. The records themselves
+ * carry the chain, and the finish, the appendix, and the prune each read them.
  */
 export type SessionStateLoad = {
     outcome: "found";
@@ -171,6 +177,7 @@ export type SessionStateLoad = {
     analysisId: string;
     token: SessionStateToken;
     seenDocumentHash: string | null;
+    derivations: readonly DerivationRecord[];
 } | {
     outcome: "absent";
 } | {
@@ -243,7 +250,7 @@ export interface ReportSessionStateGateway {
 }
 /**
  * The thread of a call, its analysis, the loaded state, the concurrency token that the persist compares
- * against, and the seen-document hash of the look-before-record rule.
+ * against, the seen-document hash of the look-before-record rule, and the derivations of the session.
  */
 export interface OpenedThread {
     readonly threadId: string;
@@ -252,6 +259,8 @@ export interface OpenedThread {
     readonly token: SessionStateToken;
     /** The hash that the last eyes capture saw, or `null` before the first look. */
     readonly seenDocumentHash: string | null;
+    /** The derivations of the session, in the order that the records landed. */
+    readonly derivations: readonly DerivationRecord[];
 }
 /**
  * Resolve the report thread of a call, and load its state through the gateway.

package/dist/tools/report-authoring/authoring-tools.js

@@ -17,27 +17,33 @@
  * nested union. A conflict between the flat fields refuses before the core runs.
  */
 import { err, ok } from "neverthrow";
+import { basename } from "node:path";
 import { z } from "zod";
+import { capCodePoints, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
 import { isSafeId } from "../../workspace/paths.js";
 import { addBlock, changeBlock, locate, moveBlock, removeBlock, setTitle, } from "../../report-model/draft-operations.js";
 import { buildOutline, childOutline, readBlock } from "../../report-model/draft-read.js";
 import { finishDraft } from "../../report-model/draft-finish.js";
-import { DraftBlockSchema } from "../../report-model/draft.js";
+import { AuthoringBlockSchema } from "../../report-model/authoring-grammar.js";
 import { defineTool } from "../define-tool.js";
 /**
  * The block payload.
  *
- * The published JSON Schema carries the whole draft grammar, because a tool is self-describing at attach
- * time and the schema is the only place where the model learns the shape of the eight block kinds. A bare
- * `z.unknown()` emits the empty schema, which tells the model nothing and leaves it to discover each
+ * The published JSON Schema carries the whole authoring grammar, because a tool is self-describing at
+ * attach time and the schema is the only place where the model learns the shape of the eight block kinds.
+ * A bare `z.unknown()` emits the empty schema, which tells the model nothing and leaves it to discover each
  * required field through one refusal at a time.
  *
+ * The grammar is the authoring one, thus no artifact reference of the published schema carries a hash. The
+ * pinned snapshot owns that value, and the land path stamps it from the path.
+ *
  * The `z.unknown()` member keeps the runtime parse permissive. Thus a malformed payload still reaches the
- * core, which parses it with the same grammar and refuses `malformed-block` as typed data in the ok
+ * core, which parses it with the draft grammar and refuses `malformed-block` as typed data in the ok
  * channel. A strict input schema would turn that designed refusal into a hard input-validation error from
- * the loop.
+ * the loop. A payload that carries a hash rides the same arm, and the stamp drops the value before the
+ * parse.
  */
-const blockPayload = z.union([DraftBlockSchema, z.unknown()]);
+const blockPayload = z.union([AuthoringBlockSchema, z.unknown()]);
 /**
  * A flat field that the model can leave out.
  *
@@ -119,7 +125,14 @@ export async function openReportThread(gateway, scope) {
             detail: `the scope names the analysis ${analysisId}, but the thread ${threadId} belongs to the analysis ${loaded.analysisId}`,
         });
     }
-    return ok({ threadId, analysisId, state: loaded.state, token: loaded.token, seenDocumentHash: loaded.seenDocumentHash });
+    return ok({
+        threadId,
+        analysisId,
+        state: loaded.state,
+        token: loaded.token,
+        seenDocumentHash: loaded.seenDocumentHash,
+        derivations: loaded.derivations,
+    });
 }
 /** Read an absentable field. An explicit `null` and an omitted key both mean that the model gave no value. */
 function given(value) {
@@ -208,15 +221,75 @@ function readKind(block) {
 function readId(block) {
     return readStringField(block, "id");
 }
+/** Read one field of an untyped payload, or `undefined` when the payload is not an object. */
+function fieldOf(value, field) {
+    return value !== null && typeof value === "object" ? value[field] : undefined;
+}
 function readStringField(block, field) {
-    if (block !== null && typeof block === "object") {
-        const value = block[field];
-        if (typeof value === "string") {
-            return value;
+    const value = fieldOf(block, field);
+    return typeof value === "string" ? value : undefined;
+}
+/** The pinned path of an untyped reference payload, or `undefined` when it names none. */
+function referencePath(reference) {
+    const path = readStringField(reference, "path");
+    return path === undefined || path.length === 0 ? undefined : path;
+}
+/**
+ * The artifact path that an untyped block payload binds, or `undefined` when the kind binds no path.
+ *
+ * Where a reference sits differs per kind, thus the walk reads the one field of each kind and never
+ * searches the payload. A claim can hold a citation first, which names no path, thus the walk takes the
+ * first binding that names one. A metric holds a scalar reference, and a derivation holds its own two
+ * inputs, thus the first input names the derived value. A text block, a citation block, and a section
+ * bind no artifact at all.
+ *
+ * The payload is model-authored and unvalidated here, thus each read is a guarded read and a wrong shape
+ * gives `undefined`.
+ */
+function boundArtifactPath(kind, block) {
+    if (kind === "table" || kind === "chart" || kind === "figure") {
+        return referencePath(fieldOf(block, "binding"));
+    }
+    if (kind === "claim") {
+        const bindings = fieldOf(block, "bindings");
+        if (!Array.isArray(bindings)) {
+            return undefined;
         }
+        for (const binding of bindings) {
+            const path = referencePath(binding);
+            if (path !== undefined) {
+                return path;
+            }
+        }
+        return undefined;
+    }
+    if (kind === "metric") {
+        const value = fieldOf(block, "value");
+        const direct = referencePath(value);
+        if (direct !== undefined) {
+            return direct;
+        }
+        const inputs = fieldOf(value, "inputs");
+        return Array.isArray(inputs) ? referencePath(inputs[0]) : undefined;
     }
     return undefined;
 }
+/**
+ * The subject that names one added block: the title of a section in quotes, or the file name of the
+ * artifact that the block binds. A block that names neither gives no subject, and the kind stands alone.
+ *
+ * The title is model-authored text of no fixed length, thus the needle bound cuts it before the emit-site
+ * cap can cut the quote that closes it. The file name is the base name alone, because the directory
+ * segments of an analysis path repeat across every block and the file name is what tells two apart.
+ */
+function addedSubject(kind, block) {
+    if (kind === "section") {
+        const title = readStringField(block, "title");
+        return title === undefined || title.length === 0 ? undefined : `"${capCodePoints(title, DETAIL_NEEDLE_MAX_LENGTH)}"`;
+    }
+    const path = boundArtifactPath(kind, block);
+    return path === undefined ? undefined : basename(path);
+}
 /**
  * The id of the section that holds a block, or `undefined` when the block sits at the root.
  *
@@ -299,12 +372,18 @@ export function createReportAuthoringTools(gateway) {
         description: "Add one block to the draft. The `block` schema gives the eight kinds and the fields of each one. " +
             "You choose the `id` of the block, and it must be unique in the draft. " +
             "Name the destination with `parentId` and one of `place`, `before`, or `after`. " +
-            "The root admits a section only, and an atom needs a section as its parent.",
+            "The root admits a section only, and an atom needs a section as its parent. " +
+            "A reference names the path of a pinned artifact, and the session stamps the hash from the pinned evidence.",
         inputSchema: addBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => {
-            const kind = readKind(decodeBlockPayload(input.block));
-            return kind !== undefined ? `add ${kind}` : "add a block";
+            const block = decodeBlockPayload(input.block);
+            const kind = readKind(block);
+            if (kind === undefined) {
+                return "add a block";
+            }
+            const subject = addedSubject(kind, block);
+            return subject === undefined ? `add ${kind}` : `add ${kind} ${subject}`;
         },
         execute: async (input, ctx) => {
             const opened = await openThread(ctx);
@@ -324,7 +403,8 @@ export function createReportAuthoringTools(gateway) {
     const change_block = defineTool({
         id: "change_block",
         description: "Change one block by its id. Give a `title` to retitle a section, or a `block` to replace an atom, and never both. " +
-            "The change keeps the id of the target, thus the `id` of the payload does not matter. A kind change is permitted.",
+            "The change keeps the id of the target, thus the `id` of the payload does not matter. A kind change is permitted. " +
+            "A reference names the path of a pinned artifact, and the session stamps the hash from the pinned evidence.",
         inputSchema: changeBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `change ${input.targetId}`,
@@ -416,7 +496,8 @@ export function createReportAuthoringTools(gateway) {
     });
     const read_block = defineTool({
         id: "read_block",
-        description: "Read one block by its id. An atom gives the full block with its bindings. A section gives its title and the id of each child, " +
+        description: "Read one block by its id. An atom gives the full block with its bindings. A binding gives its path and no hash, " +
+            "because the session owns the hash. A section gives its title and the id of each child, " +
             "because the outline already names every block under it. Use it when the outline label is not enough.",
         inputSchema: readBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
@@ -444,7 +525,7 @@ export function createReportAuthoringTools(gateway) {
             if (opened.isErr()) {
                 return ok({ refused: opened.error });
             }
-            return ok(finishDraft(opened.value.state.document, opened.value.state.snapshot));
+            return ok(finishDraft(opened.value.state.document, opened.value.state.snapshot, opened.value.derivations));
         },
     });
     return {