@inflexa-ai/harness 0.45.0 → 0.46.0

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

@@ -15,12 +15,17 @@
  *
  * The primitive admits a flat object input only. Thus a destination is four optional fields, and not a
  * nested union. A conflict between the flat fields refuses before the core runs.
+ *
+ * Inside a durable step, a mutation stores its result for the thread and the step, in the transaction of
+ * the document and under the lock of the row. A rerun of the step after the landing, before its
+ * checkpoint, gives the stored result. Thus a rerun of `add_block` does not refuse its own block id, and a
+ * rerun of `remove_block` does not refuse its own removed target.
  */
 import { type Result } from "neverthrow";
 import { z } from "zod";
 import type { Scope } from "../../auth/types.js";
 import type { Logger } from "../../lib/logger.js";
-import { type ProvenanceSeam } from "../../provenance/seam.js";
+import { type ProvenanceSeam, type SessionProvenanceEvent } from "../../provenance/seam.js";
 import { type DraftRefusal } from "../../report-model/draft-operations.js";
 import { type OutlineEntry, type ReadableBlock } from "../../report-model/draft-read.js";
 import type { ReportWarning } from "../../report-model/block-walk.js";
@@ -81,11 +86,11 @@ export type ReadBlockInput = z.infer<typeof readBlockInput>;
 export type SetTitleInput = z.infer<typeof setTitleInput>;
 export type FinishDraftInput = z.infer<typeof finishDraftInput>;
 /** One container that an operation changed, and the child order inside it after the operation. */
-export interface ChangedContainer {
+export type ChangedContainer = {
     /** The section that holds the children. It is absent when the container is the root. */
     parentId?: string;
     children: OutlineEntry[];
-}
+};
 /**
  * The closed set of tool-layer refusal reasons.
  *
@@ -105,10 +110,10 @@ export type SessionRefusalReason = "no-thread-scope" | "absent-state" | "wrong-t
  * state, or a gateway that cannot give the state. It sits beside the core `DraftRefusal`, and it never
  * widens the closed reason set of the core.
  */
-export interface SessionRefusal {
+export type SessionRefusal = {
     reason: SessionRefusalReason;
     detail: string;
-}
+};
 /**
  * The result of a mutation tool. A refusal carries the typed reason, from the core or from the tool layer.
  *
@@ -120,13 +125,15 @@ export interface SessionRefusal {
  *
  * A move across two containers reports both. An operation that changes no child order reports none.
  */
-export type MutationResult = {
-    applied: true;
-    changed: ChangedContainer[];
-} | {
+export type MutationResult = LandedResult | {
     applied: false;
     refusal: DraftRefusal | SessionRefusal;
 };
+/** The result of a mutation that landed its document. A durable step stores it, and a rerun of the step gives it again. */
+export type LandedResult = {
+    applied: true;
+    changed: ChangedContainer[];
+};
 /** The result of `read_outline`. A load that gives no state refuses instead of an outline. */
 export type OutlineResult = {
     outline: OutlineEntry[];
@@ -160,10 +167,10 @@ export type FinishToolResult = {
     refused: SessionRefusal;
 };
 /** The state of one report thread: the document under composition, and the frozen snapshot. */
-export interface ReportSessionState {
+export type ReportSessionState = {
     readonly document: DraftDocument;
     readonly snapshot: ReportSnapshot;
-}
+};
 /**
  * The concurrency token that a load hands out and a persist compares against. It is the prior document
  * that the load read, or `null` before the first document lands. The persist lands only when the row still
@@ -191,6 +198,8 @@ export type SessionStateLoad = {
     token: SessionStateToken;
     seenDocumentHash: string | null;
     derivations: readonly DerivationRecord[];
+    /** The stored result of the call that the load names, when an earlier run of that call landed. */
+    landed?: unknown;
 } | {
     outcome: "absent";
 } | {
@@ -200,15 +209,31 @@ export type SessionStateLoad = {
     outcome: "failed";
     detail: string;
 };
-/** The outcome of a gateway persist. `conflict` means that a concurrent turn landed first. */
+/**
+ * The outcome of a gateway persist. `conflict` means that a concurrent turn landed first. `replayed` means
+ * that an earlier run of the call landed, and it carries the stored result of that run.
+ */
 export type SessionStatePersist = {
     outcome: "persisted";
 } | {
     outcome: "conflict";
+} | {
+    outcome: "replayed";
+    landed: unknown;
 } | {
     outcome: "failed";
     detail: string;
 };
+/**
+ * The authoring call of a persist: the key of its durable step, and the result that it gives when the document lands.
+ * The result carries the events of the act, thus a rerun that finds the result can emit them again.
+ */
+export type LandingCall = {
+    readonly key: string;
+    readonly result: LandedResult & {
+        readonly events: readonly SessionProvenanceEvent[];
+    };
+};
 /**
  * The outcome of a gateway stamp. `stamped` wrote the marker. `absent` means that no row holds the thread.
  * `failed` is a transient store fault that names its cause. Each arm is plain data, thus a stamp never
@@ -246,9 +271,11 @@ export type SeenStampResult = {
  * the gateway over the durable store. A load gives the state, a typed absence, or a typed failure. A
  * persist gives success, or a typed failure.
  */
-export interface ReportSessionStateGateway {
-    load(threadId: string): Promise<SessionStateLoad>;
-    persist(threadId: string, document: DraftDocument, expected: SessionStateToken): Promise<SessionStatePersist>;
+export type ReportSessionStateGateway = {
+    /** `callKey` names the durable step of a mutation, and the found load then carries the stored result of an earlier run. */
+    load(threadId: string, callKey?: string): Promise<SessionStateLoad>;
+    /** A persist with a `call` stores the result of the call in the transaction of the document. */
+    persist(threadId: string, document: DraftDocument, expected: SessionStateToken, call?: LandingCall): Promise<SessionStatePersist>;
     /**
      * Stamp the hash of the rendered draft on the session state. The preview calls it when the page lands,
      * thus the runtime knows which draft the page shows.
@@ -260,12 +287,12 @@ export interface ReportSessionStateGateway {
      * rendered hash existed to copy, thus the eyes tell a real stamp from a missed one.
      */
     stampSeen(threadId: string): Promise<SeenStampResult>;
-}
+};
 /**
  * The thread of a call, its analysis, the loaded state, the concurrency token that the persist compares
  * against, the seen-document hash of the look-before-record rule, and the derivations of the session.
  */
-export interface OpenedThread {
+export type OpenedThread = {
     readonly threadId: string;
     readonly analysisId: string;
     readonly state: ReportSessionState;
@@ -274,7 +301,9 @@ export interface OpenedThread {
     readonly seenDocumentHash: string | null;
     /** The derivations of the session, in the order that the records landed. */
     readonly derivations: readonly DerivationRecord[];
-}
+    /** The stored result of an earlier run of the call that the open names. */
+    readonly landed?: unknown;
+};
 /**
  * Resolve the report thread of a call, and load its state through the gateway.
  *
@@ -290,9 +319,9 @@ export interface OpenedThread {
  * The authoring tools and the preview tool share this one resolution, thus the two surfaces accept the
  * same thread id and map a load outcome onto a refusal the same way.
  */
-export declare function openReportThread(gateway: ReportSessionStateGateway, scope: Scope): Promise<Result<OpenedThread, SessionRefusal>>;
+export declare function openReportThread(gateway: ReportSessionStateGateway, scope: Scope, callKey?: string): Promise<Result<OpenedThread, SessionRefusal>>;
 /** The eight authoring tools. */
-export interface ReportAuthoringTools {
+export type ReportAuthoringTools = {
     readonly add_block: Tool<AddBlockInput, MutationResult>;
     readonly change_block: Tool<ChangeBlockInput, MutationResult>;
     readonly remove_block: Tool<RemoveBlockInput, MutationResult>;
@@ -301,17 +330,19 @@ export interface ReportAuthoringTools {
     readonly read_outline: Tool<ReadOutlineInput, OutlineResult>;
     readonly read_block: Tool<ReadBlockInput, ReadBlockResult>;
     readonly finish_draft: Tool<FinishDraftInput, FinishToolResult>;
-}
+};
 /**
  * The optional deps of the authoring surface. The gateway is the one mandatory part, thus it stays a
  * parameter of its own and this bag holds what a composition can leave out.
  */
-export interface ReportAuthoringToolDeps {
+export type ReportAuthoringToolDeps = {
     /** The provenance seam; an unbound session emit emits nothing and each tool acts the same. */
     readonly provenance?: ProvenanceSeam;
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
-}
+    /** The key of the durable step that runs the call, `undefined` outside one. Defaults to {@link durableStepKey}. */
+    readonly stepKey?: () => string | undefined;
+};
 /**
  * Make the eight authoring tools over a session-state gateway.
  *

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

@@ -15,12 +15,19 @@
  *
  * The primitive admits a flat object input only. Thus a destination is four optional fields, and not a
  * nested union. A conflict between the flat fields refuses before the core runs.
+ *
+ * Inside a durable step, a mutation stores its result for the thread and the step, in the transaction of
+ * the document and under the lock of the row. A rerun of the step after the landing, before its
+ * checkpoint, gives the stored result. Thus a rerun of `add_block` does not refuse its own block id, and a
+ * rerun of `remove_block` does not refuse its own removed target.
  */
 import { err, ok } from "neverthrow";
 import { basename } from "node:path";
 import { z } from "zod";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { capCodePoints, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
+import { parseJsonAs } from "../../lib/parse-json.js";
+import { parseUnknownRecord } from "../../lib/unknown-containers.js";
 import { bindSessionEmit } from "../../provenance/seam.js";
 import { isSafeId } from "../../workspace/paths.js";
 import { addBlock, changeBlock, locate, moveBlock, removeBlock, setTitle, } from "../../report-model/draft-operations.js";
@@ -28,6 +35,7 @@ import { buildOutline, childOutline, readBlock } from "../../report-model/draft-
 import { finishDraft } from "../../report-model/draft-finish.js";
 import { AuthoringBlockSchema } from "../../report-model/authoring-grammar.js";
 import { defineTool } from "../define-tool.js";
+import { durableStepKey } from "../workspace/edit-file.js";
 /**
  * The block payload.
  *
@@ -39,8 +47,8 @@ import { defineTool } from "../define-tool.js";
  * 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 draft grammar and refuses `malformed-block` as typed data in the ok
+ * The `z.unknown()` member keeps the runtime parse permissive. Thus a malformed payload still reaches
+ * the 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. A payload that carries a hash rides the same arm, and the stamp drops the value before the
  * parse.
@@ -98,6 +106,33 @@ const setTitleInput = z.object({
     title: z.string().min(1).describe("The title of the whole report."),
 });
 const finishDraftInput = z.object({});
+/** Each kind of a draft block. The record type names each kind, thus a new kind fails the build here. */
+const DRAFT_BLOCK_KINDS = {
+    section: true,
+    text: true,
+    claim: true,
+    metric: true,
+    table: true,
+    chart: true,
+    figure: true,
+    citation: true,
+};
+/** The events that a stored result carries. The harness wrote each one, thus a check of the event type is enough. */
+const StoredEventsSchema = z.object({
+    events: z.array(z.custom((value) => z.object({ type: z.string() }).safeParse(value).success)),
+});
+const LandedResultSchema = z.object({
+    applied: z.literal(true),
+    changed: z.array(z.object({
+        parentId: z.string().optional(),
+        children: z.array(z.object({
+            id: z.string(),
+            kind: z.custom((value) => typeof value === "string" && Object.hasOwn(DRAFT_BLOCK_KINDS, value)),
+            depth: z.number(),
+            label: z.string(),
+        })),
+    })),
+});
 /**
  * Resolve the report thread of a call, and load its state through the gateway.
  *
@@ -113,12 +148,12 @@ const finishDraftInput = z.object({});
  * The authoring tools and the preview tool share this one resolution, thus the two surfaces accept the
  * same thread id and map a load outcome onto a refusal the same way.
  */
-export async function openReportThread(gateway, scope) {
-    if (scope.kind !== "analysis" || scope.threadId === undefined || !isSafeId(scope.threadId)) {
+export async function openReportThread(gateway, scope, callKey) {
+    if (scope.threadId === undefined || !isSafeId(scope.threadId)) {
         return err({ reason: "no-thread-scope", detail: "the scope of the call names no usable report thread id" });
     }
     const { threadId, analysisId } = scope;
-    const loaded = await gateway.load(threadId);
+    const loaded = await gateway.load(threadId, callKey);
     if (loaded.outcome === "absent") {
         return err({ reason: "absent-state", detail: `no report session exists for the thread ${threadId}, and this condition is permanent` });
     }
@@ -141,6 +176,7 @@ export async function openReportThread(gateway, scope) {
         token: loaded.token,
         seenDocumentHash: loaded.seenDocumentHash,
         derivations: loaded.derivations,
+        landed: loaded.landed,
     });
 }
 /** Read an absentable field. An explicit `null` and an omitted key both mean that the model gave no value. */
@@ -216,7 +252,7 @@ function decodeBlockPayload(block) {
         return block;
     }
     try {
-        return JSON.parse(block);
+        return parseJsonAs(block, z.json());
     }
     catch {
         return block;
@@ -232,7 +268,7 @@ function readId(block) {
 }
 /** 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;
+    return parseUnknownRecord(value)?.[field];
 }
 function readStringField(block, field) {
     const value = fieldOf(block, field);
@@ -357,16 +393,6 @@ function containerIn(document, parentId) {
     const children = located !== undefined && located.block.kind === "section" ? located.block.blocks : [];
     return { parentId, children: childOutline(children, located?.path.length ?? 0) };
 }
-/**
- * Every tool of this surface runs inline.
- *
- * A tool loads the state of its thread, applies the pure operation, and persists the result in one body.
- * The reported outline must agree with the row that the body just wrote. A step-mode tool goes through
- * `DBOS.runStep`, which caches the result of a step and replays it without a fresh load. A replay could
- * then report an outline that the current row no longer holds. Inline mode reads and writes the row in one
- * lifetime, thus the outline never drifts from the state.
- */
-const AUTHORING_EXECUTION_MODE = "inline";
 /**
  * Make the eight authoring tools over a session-state gateway.
  *
@@ -379,6 +405,7 @@ const AUTHORING_EXECUTION_MODE = "inline";
  */
 export function createReportAuthoringTools(gateway, deps = {}) {
     const observe = bindSessionEmit(deps.provenance, (deps.logger ?? createNoopLogger()).named("report-authoring"));
+    const stepKey = deps.stepKey ?? durableStepKey;
     /**
      * Resolve the thread of the call, and load its state.
      *
@@ -387,6 +414,39 @@ export function createReportAuthoringTools(gateway, deps = {}) {
      * operation.
      */
     const openThread = (ctx) => openReportThread(gateway, ctx.session.scope);
+    const refuse = (refusal) => ({ applied: false, refusal });
+    /**
+     * The stored result of an earlier run of the call. The row holds what `land` stored, and a row that does not parse refuses.
+     *
+     * A crash between the persist and the emit of the earlier run loses its events, thus the rerun emits the stored
+     * events again. A consumer can get an act two times, never zero times. The parse of the result drops the events,
+     * thus the model reads the result alone.
+     */
+    const replayed = (landed) => {
+        const parsed = LandedResultSchema.safeParse(landed);
+        if (!parsed.success) {
+            return refuse({ reason: "state-unavailable", detail: "the stored result of an earlier run of this call does not parse" });
+        }
+        const stored = StoredEventsSchema.safeParse(landed);
+        for (const observed of stored.success ? stored.data.events : []) {
+            observe(observed);
+        }
+        return parsed.data;
+    };
+    /**
+     * Resolve the thread of a mutation, and load its state with the stored result of an earlier run of the
+     * call. A rerun of a landed call gives that result, and it never reaches the core, which would refuse
+     * the landing of its own earlier run.
+     */
+    const openMutation = async (ctx) => {
+        const callKey = stepKey();
+        const opened = await openReportThread(gateway, ctx.session.scope, callKey);
+        if (opened.isErr())
+            return { done: refuse(opened.error) };
+        if (opened.value.landed !== undefined)
+            return { done: replayed(opened.value.landed) };
+        return { opened: { ...opened.value, callKey } };
+    };
     /**
      * Persist a landing, and report the containers that the operation changed.
      *
@@ -396,7 +456,8 @@ export function createReportAuthoringTools(gateway, deps = {}) {
      * tool reports `applied: true` only after the row holds the new document.
      *
      * The persist is a compare-and-swap against the token that the load read. A concurrent turn that landed
-     * first turns the persist into a conflict, and the tool refuses with `stale-state`.
+     * first turns the persist into a conflict, and the tool refuses with `stale-state`. Inside a durable
+     * step, the result lands in the transaction of the document, thus a rerun of the step gives it again.
      *
      * `events` gives the observations of the operation, and they emit after the persist landed. Thus one
      * site owns the rule, and a refusal, a conflict, and a persist fault each emit nothing. It reads the two
@@ -404,12 +465,18 @@ export function createReportAuthoringTools(gateway, deps = {}) {
      * added block sits in the second alone. A caller that cannot name the block of its own operation gives
      * no event.
      */
-    const land = async (threadId, token, previous, result, holders, events) => {
+    const land = async (opened, result, holders, events) => {
         if (result.isErr()) {
             return { applied: false, refusal: result.error };
         }
+        const previous = opened.state.document;
         const next = result.value;
-        const persisted = await gateway.persist(threadId, next, token);
+        // A move inside one container names the same holder two times.
+        const unique = [...new Set(holders(previous, next))];
+        const landed = { applied: true, changed: unique.map((parentId) => containerIn(next, parentId)) };
+        const observed = events(previous, next);
+        const call = opened.callKey === undefined ? undefined : { key: opened.callKey, result: { ...landed, events: observed } };
+        const persisted = await gateway.persist(opened.threadId, next, opened.token, call);
         if (persisted.outcome === "conflict") {
             return {
                 applied: false,
@@ -419,14 +486,14 @@ export function createReportAuthoringTools(gateway, deps = {}) {
         if (persisted.outcome === "failed") {
             return { applied: false, refusal: { reason: "state-unavailable", detail: persisted.detail } };
         }
-        for (const observed of events(previous, next)) {
-            observe(observed);
+        if (persisted.outcome === "replayed") {
+            return replayed(persisted.landed);
         }
-        // A move inside one container names the same holder two times.
-        const unique = [...new Set(holders(previous, next))];
-        return { applied: true, changed: unique.map((parentId) => containerIn(next, parentId)) };
+        for (const event of observed) {
+            observe(event);
+        }
+        return landed;
     };
-    const refuse = (refusal) => ({ applied: false, refusal });
     const add_block = defineTool({
         id: "add_block",
         description: "Add one block to the draft. The block can be a section that carries its child blocks, thus one call can add a whole section with its atoms. " +
@@ -437,7 +504,6 @@ export function createReportAuthoringTools(gateway, deps = {}) {
             "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 block = decodeBlockPayload(input.block);
             const kind = readKind(block);
@@ -448,18 +514,19 @@ export function createReportAuthoringTools(gateway, deps = {}) {
             return subject === undefined ? `add ${kind}` : `add ${kind} ${subject}`;
         },
         execute: async (input, ctx) => {
-            const opened = await openThread(ctx);
-            if (opened.isErr()) {
-                return ok(refuse(opened.error));
+            const opening = await openMutation(ctx);
+            if ("done" in opening) {
+                return ok(opening.done);
             }
-            const { threadId, analysisId, state, token } = opened.value;
+            const { opened } = opening;
+            const { threadId, analysisId, state } = opened;
             const destination = toDestination(input);
             if (destination.isErr()) {
                 return ok(refuse(destination.error));
             }
             const block = decodeBlockPayload(input.block);
             const addedId = readId(block);
-            return ok(await land(threadId, token, state.document, addBlock(state.document, { block, destination: destination.value }, state.snapshot), (_previous, next) => [addedId === undefined ? undefined : holderIdOf(next, addedId)], 
+            return ok(await land(opened, addBlock(state.document, { block, destination: destination.value }, state.snapshot), (_previous, next) => [addedId === undefined ? undefined : holderIdOf(next, addedId)], 
             // The grammar requires an id on the payload, thus a landed add always names one. A
             // payload with no id reaches the core, which refuses it, and no event is due.
             (_previous, next) => (addedId === undefined ? [] : addedActsOf({ analysisId, threadId }, next, addedId))));
@@ -471,19 +538,19 @@ export function createReportAuthoringTools(gateway, deps = {}) {
             "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}`,
         execute: async (input, ctx) => {
-            const opened = await openThread(ctx);
-            if (opened.isErr()) {
-                return ok(refuse(opened.error));
+            const opening = await openMutation(ctx);
+            if ("done" in opening) {
+                return ok(opening.done);
             }
-            const { threadId, analysisId, state, token } = opened.value;
+            const { opened } = opening;
+            const { threadId, analysisId, state } = opened;
             const operation = toChangeOperation(input);
             if (operation.isErr()) {
                 return ok(refuse(operation.error));
             }
-            return ok(await land(threadId, token, state.document, changeBlock(state.document, operation.value, state.snapshot), (_previous, next) => [holderIdOf(next, input.targetId)], 
+            return ok(await land(opened, changeBlock(state.document, operation.value, state.snapshot), (_previous, next) => [holderIdOf(next, input.targetId)], 
             // A change is permitted to change the kind, thus the event states the kind that the
             // document holds after the act.
             (_previous, next) => blockActOf("change-block", { analysisId, threadId }, next, input.targetId)));
@@ -493,15 +560,15 @@ export function createReportAuthoringTools(gateway, deps = {}) {
         id: "remove_block",
         description: "Remove one block by its id. A removed section takes its whole subtree with it, and the id is free for a later add.",
         inputSchema: removeBlockInput,
-        executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `remove ${input.targetId}`,
         execute: async (input, ctx) => {
-            const opened = await openThread(ctx);
-            if (opened.isErr()) {
-                return ok(refuse(opened.error));
+            const opening = await openMutation(ctx);
+            if ("done" in opening) {
+                return ok(opening.done);
             }
-            const { threadId, analysisId, state, token } = opened.value;
-            return ok(await land(threadId, token, state.document, removeBlock(state.document, { targetId: input.targetId }, state.snapshot), (previous) => [holderIdOf(previous, input.targetId)], 
+            const { opened } = opening;
+            const { threadId, analysisId, state } = opened;
+            return ok(await land(opened, removeBlock(state.document, { targetId: input.targetId }, state.snapshot), (previous) => [holderIdOf(previous, input.targetId)], 
             // The next document holds no removed block, thus the event states the kind that the
             // previous one carried.
             (previous) => blockActOf("remove-block", { analysisId, threadId }, previous, input.targetId)));
@@ -512,19 +579,19 @@ export function createReportAuthoringTools(gateway, deps = {}) {
         description: "Move one block by its id to a new destination. Name the destination with `parentId` and one of `place`, `before`, or `after`. " +
             "A section cannot move into its own subtree.",
         inputSchema: moveBlockInput,
-        executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `move ${input.targetId}`,
         execute: async (input, ctx) => {
-            const opened = await openThread(ctx);
-            if (opened.isErr()) {
-                return ok(refuse(opened.error));
+            const opening = await openMutation(ctx);
+            if ("done" in opening) {
+                return ok(opening.done);
             }
-            const { threadId, analysisId, state, token } = opened.value;
+            const { opened } = opening;
+            const { threadId, analysisId, state } = opened;
             const destination = toDestination(input);
             if (destination.isErr()) {
                 return ok(refuse(destination.error));
             }
-            return ok(await land(threadId, token, state.document, moveBlock(state.document, { targetId: input.targetId, destination: destination.value }, state.snapshot), (previous, next) => [holderIdOf(previous, input.targetId), holderIdOf(next, input.targetId)], (_previous, next) => blockActOf("move-block", { analysisId, threadId }, next, input.targetId)));
+            return ok(await land(opened, moveBlock(state.document, { targetId: input.targetId, destination: destination.value }, state.snapshot), (previous, next) => [holderIdOf(previous, input.targetId), holderIdOf(next, input.targetId)], (_previous, next) => blockActOf("move-block", { analysisId, threadId }, next, input.targetId)));
         },
     });
     const set_title = defineTool({
@@ -532,16 +599,16 @@ export function createReportAuthoringTools(gateway, deps = {}) {
         description: "Set the title of the report document. A draft starts with no title, and a document needs one. " +
             "The title names the whole report, and it is not the title of a section.",
         inputSchema: setTitleInput,
-        executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `title the report ${input.title}`,
         // The title sits on the document, thus no container changes its child order.
         execute: async (input, ctx) => {
-            const opened = await openThread(ctx);
-            if (opened.isErr()) {
-                return ok(refuse(opened.error));
+            const opening = await openMutation(ctx);
+            if ("done" in opening) {
+                return ok(opening.done);
             }
-            const { threadId, analysisId, state, token } = opened.value;
-            return ok(await land(threadId, token, state.document, ok(setTitle(state.document, input.title)), () => [], () => [
+            const { opened } = opening;
+            const { threadId, analysisId, state } = opened;
+            return ok(await land(opened, ok(setTitle(state.document, input.title)), () => [], () => [
                 {
                     type: "set-title",
                     analysisId,
@@ -557,7 +624,6 @@ export function createReportAuthoringTools(gateway, deps = {}) {
             "A label that ends with the character … is clipped. Use the outline as the primary view of the draft, " +
             "and read one block when the label is not enough.",
         inputSchema: readOutlineInput,
-        executionMode: AUTHORING_EXECUTION_MODE,
         // The input carries no field, thus a hook can only restate the name of the tool.
         describeCall: "none",
         execute: async (_input, ctx) => {
@@ -574,16 +640,17 @@ export function createReportAuthoringTools(gateway, deps = {}) {
             "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,
         describeCall: (input) => `read ${input.targetId}`,
         execute: async (input, ctx) => {
             const opened = await openThread(ctx);
             if (opened.isErr()) {
                 return ok({ refused: opened.error });
             }
-            const block = readBlock(opened.value.state.document, input.targetId);
-            const result = block !== undefined ? { found: true, block } : { found: false };
-            return ok(result);
+            return readBlock(opened.value.state.document, input.targetId).match((block) => ok(block !== undefined ? { found: true, block } : { found: false }), (refused) => err({
+                error: `the stored block ${refused.id} does not match the authoring grammar, thus it cannot be read`,
+                retryable: false,
+                cause: refused.cause,
+            }));
         },
     });
     const finish_draft = defineTool({
@@ -593,7 +660,6 @@ export function createReportAuthoringTools(gateway, deps = {}) {
             "preview_report and record_report_version run the same check before they act, thus a finish directly before one of them does that check a second time. " +
             "Use it to make sure that the draft passes the whole document schema, the id rule, and the structural tier.",
         inputSchema: finishDraftInput,
-        executionMode: AUTHORING_EXECUTION_MODE,
         // The input carries no field, thus a hook can only restate the name of the tool.
         describeCall: "none",
         execute: async (_input, ctx) => {