@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/app/data-profile-view.js

@@ -11,6 +11,7 @@
  * older consumers already handled. Nothing it drops is unavailable — the full record is
  * on the row, and consumers that want the resolved structure read it directly.
  */
+import { presentFirst } from "../lib/present.js";
 /**
  * Every number the observations reported, side by side and de-duplicated.
  *
@@ -40,7 +41,7 @@ function examplesOf(dimension) {
     return [];
 }
 function fromGroup(group) {
-    const format = group.formats.length === 1 ? group.formats[0].format : undefined;
+    const format = group.formats.length === 1 ? presentFirst(group.formats, "the single group format").format : undefined;
     return {
         id: group.id,
         name: group.name,
@@ -48,9 +49,9 @@ function fromGroup(group) {
         description: group.description,
         count: group.count,
         pattern: group.displayPattern,
-        ...(format ? { format } : {}),
-        ...(group.slots ? { slotIds: group.slots.map((slot) => slot.id) } : {}),
-        ...(group.unclassified ? { unclassified: true } : {}),
+        format: format ? format : undefined,
+        slotIds: group.slots?.map((slot) => slot.id),
+        unclassified: group.unclassified ? true : undefined,
     };
 }
 /** The dataset's structure, from whichever field the snapshot carries it in. */
@@ -64,7 +65,7 @@ export function profileGroups(result) {
         description: kind.description,
         count: kind.count,
         pattern: kind.pathPattern,
-        ...(kind.format ? { format: kind.format } : {}),
+        format: kind.format ? kind.format : undefined,
     }));
 }
 /** What varies across the dataset, from whichever field the snapshot carries it in. */
@@ -74,14 +75,14 @@ export function profileDimensions(result) {
             label: dimension.label,
             cardinalities: dimensionCardinalities(dimension),
             exampleValues: examplesOf(dimension),
-            ...(dimension.description ? { description: dimension.description } : {}),
+            description: dimension.description ? dimension.description : undefined,
         }));
     }
     return (result.axes ?? []).map((axis) => ({
         label: axis.label,
         cardinalities: [axis.cardinality],
         exampleValues: axis.exampleValues ?? [],
-        ...(axis.description ? { description: axis.description } : {}),
+        description: axis.description ? axis.description : undefined,
     }));
 }
 /**
@@ -96,7 +97,7 @@ export function profileFileRecords(result) {
         return result.groups.flatMap((group) => (group.memberAnnotations ?? []).map((annotation) => ({
             path: annotation.path,
             description: annotation.note,
-            ...(group.formats.length === 1 ? { format: group.formats[0].format } : {}),
+            format: group.formats.length === 1 ? presentFirst(group.formats, "the single group format").format : undefined,
         })));
     }
     return result.files ?? [];

package/dist/app/in-process-turn.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A chat turn in the process of a test, with no workflow. The turn of `chat-turn.ts` runs over a transport that
+ * streams to an emit sink and runs each write directly, thus a test drives the storage and the loop of a turn with
+ * no DBOS engine. A host reaches a turn through the turn workflow only, and `inProcessChatTurns` gives the test of
+ * a host the same surface over this turn.
+ */
+import { type ChatTurns } from "./chat-turn-workflow.js";
+import type { LoopOptions } from "../loop/run-loop.js";
+import type { EmitFn } from "../loop/types.js";
+import type { PromptCachePolicy } from "../providers/types.js";
+import type { AgentDefinition } from "../loop/types.js";
+import { type ChatTurnRan, type ChatTurnRefusal, type ChatTurnSession, type OpenChatTurnParams, type RunChatTurnDeps } from "./chat-turn.js";
+/** The transport values of a turn in process. */
+export type InProcessRunParams = {
+    readonly session: ChatTurnSession;
+    readonly emit: EmitFn;
+    readonly signal: AbortSignal;
+    readonly author?: string;
+    /** Absent counts from the open. */
+    readonly startedAtMs?: number;
+    readonly promptCache?: PromptCachePolicy;
+    /** The decision of the user on a call that asks for approval. Absent: the loop denies the call. */
+    readonly approve?: LoopOptions["approve"];
+};
+export type InProcessTurnParams = OpenChatTurnParams & InProcessRunParams;
+export type InProcessTurnResult = ChatTurnRefusal | ChatTurnRan;
+/** A prepared turn with its agent. Call `run` one time: each call stores a new opening of the same user message. */
+export type InProcessOpenTurn = {
+    readonly kind: "ready";
+    readonly agent: AgentDefinition;
+    readonly run: (params: InProcessRunParams) => Promise<ChatTurnRan>;
+};
+/** Prepare a turn and resolve its agent. A refusal comes back before any row of the turn exists. */
+export declare function openInProcessTurn(deps: RunChatTurnDeps, params: OpenChatTurnParams): Promise<InProcessOpenTurn | ChatTurnRefusal>;
+/** Open a turn in process and run it. */
+export declare function runInProcessTurn(deps: RunChatTurnDeps, params: InProcessTurnParams): Promise<InProcessTurnResult>;
+/**
+ * The chat turns of a host test, over the turn in process: `open` starts the turn at once, `read` gives its frames
+ * with the end frame of a turn workflow, `stop` aborts it, and `outcome` gives its end. An ask has no answer here,
+ * thus a call that asks for an approval is denied.
+ */
+export declare function inProcessChatTurns(deps: RunChatTurnDeps): ChatTurns;

package/dist/app/in-process-turn.js

@@ -0,0 +1,139 @@
+/**
+ * A chat turn in the process of a test, with no workflow. The turn of `chat-turn.ts` runs over a transport that
+ * streams to an emit sink and runs each write directly, thus a test drives the storage and the loop of a turn with
+ * no DBOS engine. A host reaches a turn through the turn workflow only, and `inProcessChatTurns` gives the test of
+ * a host the same surface over this turn.
+ */
+import { randomUUID } from "node:crypto";
+import { toChatFrame } from "../contracts/chat-frame.js";
+import { chatTurnEndOf } from "./chat-turn-workflow.js";
+import { createConversationDisplayRecorder } from "../memory/conversation-display-recorder.js";
+import { prepareChatTurn, runOpenTurn, userTextOf, } from "./chat-turn.js";
+/** Prepare a turn and resolve its agent. A refusal comes back before any row of the turn exists. */
+export async function openInProcessTurn(deps, params) {
+    const openedAtMs = Date.now();
+    let prepared;
+    try {
+        prepared = await prepareChatTurn(deps, params);
+    }
+    catch (cause) {
+        return { kind: "prepare_failed", cause };
+    }
+    if (prepared.kind === "not_found")
+        return prepared;
+    const agent = deps.agents.forThread(prepared.threadType);
+    if (agent.isErr())
+        return { kind: "agent_unresolved", threadType: prepared.threadType };
+    const ready = prepared;
+    return {
+        kind: "ready",
+        agent: agent.value,
+        run: (run) => {
+            const recorder = createConversationDisplayRecorder({ userText: userTextOf(ready.userMessage), agentId: agent.value.id, sink: run.emit });
+            return runOpenTurn(deps, params, ready, agent.value, { session: run.session, author: run.author, startedAtMs: run.startedAtMs ?? openedAtMs, promptCache: run.promptCache }, {
+                signal: run.signal,
+                emit: recorder.emit,
+                onText: (text) => recorder.emit({ type: "text-delta", text }),
+                recorder,
+                durably: (_name, write) => write(),
+                approve: run.approve,
+            });
+        },
+    };
+}
+/** Open a turn in process and run it. */
+export async function runInProcessTurn(deps, params) {
+    const { analysisId, threadId, userInput, ...run } = params;
+    const opened = await openInProcessTurn(deps, { analysisId, threadId, userInput });
+    if (opened.kind !== "ready")
+        return opened;
+    return opened.run(run);
+}
+function createFrameLog() {
+    const frames = [];
+    let closed = false;
+    let waiters = [];
+    const wake = () => {
+        const woken = waiters;
+        waiters = [];
+        for (const resolve of woken)
+            resolve();
+    };
+    return {
+        push(frame) {
+            frames.push(frame);
+            wake();
+        },
+        close() {
+            closed = true;
+            wake();
+        },
+        async *read() {
+            for (let index = 0;; index += 1) {
+                while (index >= frames.length) {
+                    if (closed)
+                        return;
+                    await new Promise((resolve) => waiters.push(resolve));
+                }
+                const frame = frames[index];
+                if (frame !== undefined)
+                    yield frame;
+            }
+        },
+    };
+}
+/**
+ * The chat turns of a host test, over the turn in process: `open` starts the turn at once, `read` gives its frames
+ * with the end frame of a turn workflow, `stop` aborts it, and `outcome` gives its end. An ask has no answer here,
+ * thus a call that asks for an approval is denied.
+ */
+export function inProcessChatTurns(deps) {
+    const turns = new Map();
+    return {
+        async open(session, request) {
+            const opened = await openInProcessTurn(deps, { analysisId: request.analysisId, threadId: request.threadId, userInput: request.userInput });
+            if (opened.kind !== "ready")
+                return opened;
+            const turnId = randomUUID();
+            const rootSource = { agentId: opened.agent.id, callPath: [opened.agent.id] };
+            const log = createFrameLog();
+            const controller = new AbortController();
+            const end = opened
+                .run({
+                session,
+                emit: (event) => {
+                    const frame = toChatFrame(event, rootSource);
+                    if (frame !== null)
+                        log.push(structuredClone(frame));
+                },
+                signal: controller.signal,
+                author: request.author,
+                startedAtMs: request.startedAtMs,
+                promptCache: request.promptCache,
+            })
+                .then((ran) => {
+                const turnEnd = chatTurnEndOf(ran);
+                log.push(turnEnd.status === "failed"
+                    ? { type: "error", message: turnEnd.reason ?? "The turn failed.", reason: turnEnd.code, source: rootSource }
+                    : { type: "finish", source: rootSource, turnUsage: turnEnd.turnUsage });
+                return turnEnd;
+            })
+                .catch(() => null)
+                .finally(() => log.close());
+            turns.set(turnId, { log, controller, end });
+            return { kind: "started", turnId, agent: opened.agent };
+        },
+        read(turnId) {
+            const turn = turns.get(turnId);
+            if (turn === undefined)
+                throw new Error(`No turn ${turnId} runs in this process.`);
+            return turn.log.read();
+        },
+        stop(turnId) {
+            turns.get(turnId)?.controller.abort(new DOMException("The user stopped the turn.", "AbortError"));
+            return Promise.resolve();
+        },
+        answer: () => Promise.resolve("not_found"),
+        outcome: (turnId) => turns.get(turnId)?.end ?? Promise.resolve(null),
+    };
+}

package/dist/app/message-assembly.d.ts

@@ -12,7 +12,7 @@ import type { LoopMessage } from "../loop/types.js";
 import type { ThreadHistory } from "../memory/thread-history.js";
 import type { ThreadType } from "../memory/thread-store.js";
 import type { WorkingMemoryStore } from "../memory/working-memory.js";
-export interface AssembleMessagesArgs {
+export type AssembleMessagesArgs = {
     /** The conversation thread — a UI-generated UUID, never the analysisId. */
     readonly threadId: string;
     /** The type of the thread. A `report` thread gets no working-memory record, and its view keeps the seed. */
@@ -31,19 +31,25 @@ export interface AssembleMessagesArgs {
     readonly workingMemory: WorkingMemoryStore;
     /** Diagnostic seam for the history repair record; omitted falls back to no-op. */
     readonly logger?: Logger;
-}
-export interface AssembledMessages {
+    /** Read the thread up to this `seq` only (see `LoadRecentOptions.throughSeq`). */
+    readonly throughSeq?: number;
+};
+export type AssembledMessages = {
     /** The view of the thread before the turn. */
     readonly history: LoopMessage[];
     /** The sanitized user input as its own message — the genuine turn start. */
     readonly userMessage: ModelMessage;
     /** The context records after the user message. The turn stores them with the user message. */
     readonly contextRecords: readonly ModelMessage[];
-}
+};
 /**
  * Assemble the message array for one chat turn. Async — it reads the view of
  * the thread and renders working memory.
  */
 export declare function assembleMessages(args: AssembleMessagesArgs): Promise<AssembledMessages>;
+/** The user input as the message of the turn. Sanitization applies one time, here, to the new user input only. */
+export declare function sanitizedUserMessage(userInput: string): ModelMessage;
+/** The view of the thread before the turn, with a not-run result for each stored call that has no result. */
+export declare function loadHistoryView(args: Pick<AssembleMessagesArgs, "threadId" | "threadType" | "history" | "logger" | "throughSeq">): Promise<LoopMessage[]>;
 /** The context records of one turn, in the order analysis context, run activity, working memory. */
 export declare function contextRecordsFor(args: Pick<AssembleMessagesArgs, "threadType" | "analysisId" | "analysisContext" | "runActivityContext" | "workingMemory">, history: readonly ModelMessage[]): Promise<ModelMessage[]>;

package/dist/app/message-assembly.js

@@ -16,7 +16,18 @@ import { normalizeUnicode, redactSecrets } from "../input-sanitization.js";
  * the thread and renders working memory.
  */
 export async function assembleMessages(args) {
-    const history = unwrapOrThrow(await args.history.loadRecent(args.threadId, { keepFirstTurn: args.threadType === "report" }));
+    const history = await loadHistoryView(args);
+    const userMessage = sanitizedUserMessage(args.userInput);
+    const contextRecords = await contextRecordsFor(args, history);
+    return { history, userMessage, contextRecords };
+}
+/** The user input as the message of the turn. Sanitization applies one time, here, to the new user input only. */
+export function sanitizedUserMessage(userInput) {
+    return { role: "user", content: normalizeUnicode(redactSecrets(userInput)) };
+}
+/** The view of the thread before the turn, with a not-run result for each stored call that has no result. */
+export async function loadHistoryView(args) {
+    const history = unwrapOrThrow(await args.history.loadRecent(args.threadId, { keepFirstTurn: args.threadType === "report", throughSeq: args.throughSeq }));
     // Read-side safety net for the wire contract: every tool call carries a
     // result. The loop upholds it at every exit, but the store outlives any one
     // writer — a row an older build wrote, or a hand-edited database, can carry
@@ -33,13 +44,7 @@ export async function assembleMessages(args) {
             tools: repaired.map((d) => d.toolName),
         });
     }
-    // Sanitization — applied once, here, to the new user input only.
-    const userMessage = {
-        role: "user",
-        content: normalizeUnicode(redactSecrets(args.userInput)),
-    };
-    const contextRecords = await contextRecordsFor(args, history);
-    return { history, userMessage, contextRecords };
+    return history;
 }
 /** The context records of one turn, in the order analysis context, run activity, working memory. */
 export async function contextRecordsFor(args, history) {

package/dist/app/report-session-runtime.d.ts

@@ -56,7 +56,7 @@ export type EnsureSessionStateResult = {
     kind: EnsureFailureKind;
     detail: string;
 };
-export interface ReportSessionRuntimeDeps {
+export type ReportSessionRuntimeDeps = {
     readonly pool: Pool;
     /**
      * The workspace-root seam of the pin. The citation evidence of an analysis sits on disk under the
@@ -64,7 +64,7 @@ export interface ReportSessionRuntimeDeps {
      */
     readonly resolveWorkspaceRoot?: ResolveWorkspaceRoot;
     readonly logger?: Logger;
-}
+};
 /**
  * The report session-state runtime. The gateway serves the authoring tools, and
  * `ensureSessionState` anchors the session. The spawn of a report session runs
@@ -72,7 +72,7 @@ export interface ReportSessionRuntimeDeps {
  * turn runs it at the turn start, and the gateway `load` runs it too. Thus a tool
  * call cannot arrive before the state exists.
  */
-export interface ReportSessionRuntime {
+export type ReportSessionRuntime = {
     readonly gateway: ReportSessionStateGateway;
     /**
      * The derivation ledger of the session state. The derivation tool appends one record for each
@@ -80,7 +80,7 @@ export interface ReportSessionRuntime {
      */
     readonly derivations: Pick<ReportSessionStateStore, "appendDerivation">;
     ensureSessionState(threadId: string): Promise<EnsureSessionStateResult>;
-}
+};
 /**
  * Build the report session-state runtime bound to a Postgres pool. The factory
  * closure captures the pool and constructs the session-state store and the thread

package/dist/app/report-session-runtime.js

@@ -34,6 +34,7 @@
  */
 import { createNoopLogger } from "../lib/console-logger.js";
 import { describeDbError } from "../lib/db-result.js";
+import { nullProtoRecord } from "../lib/null-proto.js";
 import { createThreadStore } from "../memory/thread-store.js";
 import { pinReportSnapshot } from "../report-model/pin-snapshot.js";
 import { createReportSessionStateStore, } from "../state/report-session-state.js";
@@ -58,7 +59,7 @@ function serveMembership(snapshot, derivations) {
     if (derivations.length === 0) {
         return snapshot;
     }
-    const artifacts = Object.create(null);
+    const artifacts = nullProtoRecord();
     for (const [path, entry] of Object.entries(snapshot.artifacts)) {
         artifacts[path] = entry;
     }
@@ -166,7 +167,7 @@ export function createReportSessionRuntime(deps) {
         };
     }
     const gateway = {
-        async load(threadId) {
+        async load(threadId, callKey) {
             const ensured = await ensureSessionState(threadId);
             if (ensured.outcome === "failed") {
                 switch (ensured.kind) {
@@ -178,27 +179,41 @@ export function createReportSessionRuntime(deps) {
                         return { outcome: "failed", detail: ensured.detail };
                 }
             }
-            return toLoad(ensured.state);
+            const loaded = toLoad(ensured.state);
+            if (callKey === undefined || loaded.outcome !== "found")
+                return loaded;
+            const stored = await store.readCallResult(threadId, callKey);
+            if (stored.isErr())
+                return { outcome: "failed", detail: describeDbError(stored.error) };
+            return stored.value === null ? loaded : { ...loaded, landed: stored.value.result };
         },
-        async persist(threadId, document, expected) {
-            const result = await store.persistDocument({ threadId, document, expected });
-            return result.match((outcome) => {
-                switch (outcome) {
-                    case "persisted":
-                        return { outcome: "persisted" };
-                    case "conflict":
-                        // A concurrent turn landed first. The turn refuses and reads the state again.
-                        return { outcome: "conflict" };
-                    case "absent":
-                        // The pin writes the row first. A persist that finds no row means the
-                        // pin-first invariant broke.
-                        log.error("the session-state persist matched no row", { threadId });
-                        return { outcome: "failed", detail: "no report session state row exists to persist the document" };
+        async persist(threadId, document, expected, call) {
+            const result = await store.persistDocument({ threadId, document, expected, call });
+            if (result.isErr()) {
+                log.error("the session-state persist failed", { threadId, ...log.errorFields(result.error.cause) });
+                return { outcome: "failed", detail: describeDbError(result.error) };
+            }
+            switch (result.value) {
+                case "persisted":
+                    return { outcome: "persisted" };
+                case "conflict":
+                    // A concurrent turn landed first. The turn refuses and reads the state again.
+                    return { outcome: "conflict" };
+                case "replayed": {
+                    // An earlier run of the call landed while this run waited on the row lock.
+                    const stored = call === undefined ? null : (await store.readCallResult(threadId, call.key)).unwrapOr(null);
+                    if (stored === null) {
+                        log.error("the stored result of an authoring call did not read back", { threadId });
+                        return { outcome: "failed", detail: "the stored result of an earlier run of this call did not read back" };
+                    }
+                    return { outcome: "replayed", landed: stored.result };
                 }
-            }, (error) => {
-                log.error("the session-state persist failed", { threadId, ...log.errorFields(error.cause) });
-                return { outcome: "failed", detail: describeDbError(error) };
-            });
+                case "absent":
+                    // The pin writes the row first. A persist that finds no row means the
+                    // pin-first invariant broke.
+                    log.error("the session-state persist matched no row", { threadId });
+                    return { outcome: "failed", detail: "no report session state row exists to persist the document" };
+            }
         },
         async stampRendered(threadId, hash) {
             const result = await store.stampRendered(threadId, hash);

package/dist/app/spawn-report-session.d.ts

@@ -5,11 +5,10 @@
  * The operation owns no table. It composes the reads and the writes that the
  * store, the thread history, and the working memory already give. `getThread`
  * finds the parent, and `latestSeq` gives the anchor. `listThreads` counts the
- * report children, and `createThread` writes the insert. `render` and
- * `appendTurn` make the seed, and `purgeThread` removes a child that holds no
- * seed. The two storage reads that this capability adds, `latestSeq` and
- * `countUserTurnsAfter`, live on the thread history, because that module owns
- * the `messages` table.
+ * report children, and `render` makes the seed. `createThread` writes the row
+ * and the seed in one transaction. The two storage reads that this capability
+ * adds, `latestSeq` and `countUserTurnsAfter`, live on the thread history,
+ * because that module owns the `messages` table.
  *
  * The reads and the insert take no lock and no transaction. A concurrent turn
  * can append between the anchor read and the insert, and a retract can cut the
@@ -18,8 +17,10 @@
  * past the parent's current end is a normal state a reader expects.
  *
  * A conversation thread id comes from the host UI. But the spawn is a harness
- * operation with no UI in front of it. Thus it mints a `randomUUID` and returns
- * the full row. A managed deployment gets the same behavior with no host code.
+ * operation with no UI in front of it. Thus the caller gives the child id, or
+ * the spawn mints a `randomUUID`, and the spawn returns the full row. A managed
+ * deployment gets the same behavior with no host code. A second spawn with the
+ * id of a child gives that child, and it writes nothing.
  *
  * The spawn also gates on the eyes of the composition. A report session records
  * a version only after a look at the rendered page, and only a browser can look.
@@ -32,9 +33,9 @@
  * The spawn seeds the context of the child at the anchor. It writes one message
  * that holds the brief and a copy of the working-memory render. The transcript
  * is append-only, thus the copy stays frozen at the anchor by construction, and
- * a later change to the working memory leaves it as it is. When the seed write
- * fails, the spawn purges the child, because a report thread with no context is
- * a dead end.
+ * a later change to the working memory leaves it as it is. The row and the seed
+ * commit in one transaction, because a report thread with no context is a dead
+ * end.
  *
  * The seed takes no redaction pass, and that is deliberate. The two parts are
  * agent-authored, the same trust tier as the working-memory render of a
@@ -59,8 +60,8 @@
  * the spawn.
  */
 import { ResultAsync } from "neverthrow";
-import type { Pool } from "pg";
-import type { DbError } from "../lib/db-result.js";
+import type { Querier } from "../state/db.js";
+import { type Connectable, type DbError } from "../lib/db-result.js";
 import { type ChromeConfig } from "../lib/chrome.js";
 import type { AcquireEyes } from "../lib/eyes.js";
 import type { Logger } from "../lib/logger.js";
@@ -98,10 +99,10 @@ export type SpawnRefusal = {
     readonly threadType: ThreadType;
 };
 /** The paging inputs `listReportSessions` forwards to the thread listing. */
-export interface ReportSessionPaging {
+export type ReportSessionPaging = {
     readonly page?: number;
     readonly perPage?: number;
-}
+};
 /**
  * The intent brief of one report session. The caller writes it at the moment of
  * the ask, and each field is short prose.
@@ -109,7 +110,7 @@ export interface ReportSessionPaging {
  * The brief carries intent alone. No field names a path, a dataset, or a format,
  * because the report session reads those from the workspace itself.
  */
-export interface ReportBrief {
+export type ReportBrief = {
     /** The question that the report must answer. */
     readonly objective: string;
     /** The reader of the report. */
@@ -120,25 +121,25 @@ export interface ReportBrief {
     readonly exclusions?: string;
     /** The points that the user did not decide yet. */
     readonly openQuestions?: string;
-}
+};
 /**
  * The report child that carries the greatest anchor. A tie on the anchor comes
  * from two concurrent spawns, and the newest `createdAt` wins it.
  */
-export interface NewestReportChild {
+export type NewestReportChild = {
     readonly threadId: string;
     readonly title: string | null;
     /** The `parentSeq` of the child — the point of the parent transcript that it was built on. */
     readonly anchor: number;
     readonly createdAt: Date;
-}
+};
 /**
  * The state that a caller reads before a new spawn. `newestChild` is `null` when
  * the parent holds no live report child, and an archived child reads the same
  * way, because a steer into hidden state is not permitted. An absent parent
  * reads the same way.
  */
-export interface ReportSessionDelta {
+export type ReportSessionDelta = {
     readonly newestChild: NewestReportChild | null;
     /**
      * The count of the parent turns that a person opened past the anchor of
@@ -149,7 +150,7 @@ export interface ReportSessionDelta {
      * gives no anchor to count from. No count query runs in that case.
      */
     readonly userTurnsSinceAnchor: number | null;
-}
+};
 /**
  * The construction inputs of the report-session operations.
  *
@@ -157,8 +158,8 @@ export interface ReportSessionDelta {
  * `capture`, and a `chrome` config that names a browser. One present route
  * passes the gate of the spawn.
  */
-export interface ReportSessionSpawnDeps {
-    readonly pool: Pool;
+export type ReportSessionSpawnDeps = {
+    readonly pool: Querier & Connectable;
     /**
      * The chrome config that the same composition gives to the eyes tool. The
      * spawn reads only whether it names a browser, thus the spawn and the tool
@@ -201,7 +202,7 @@ export interface ReportSessionSpawnDeps {
     readonly provenance?: ProvenanceSeam;
     /** Operational logging seam. An omitted logger falls back to the no-op. */
     readonly logger?: Logger;
-}
+};
 /**
  * Whether the composition gives a route to a look at the rendered page. The
  * three routes are the eyes seam, the capture seam, and a chrome config that
@@ -220,7 +221,7 @@ export interface ReportSessionSpawnDeps {
  * gate expression of the module, and a new route belongs here and nowhere else.
  */
 export declare function compositionHasEyes(deps: Pick<ReportSessionSpawnDeps, "chrome" | "capture" | "eyes">): boolean;
-export interface ReportSessionSpawn {
+export type ReportSessionSpawn = {
     /**
      * Make a `report` child of the parent conversation and return the full row.
      * The child takes the analysis of the parent, the parent thread id, and the
@@ -234,10 +235,14 @@ export interface ReportSessionSpawn {
      * Refused with a `SpawnRefusal`, no row written: a composition with no
      * eyes, an absent or archived parent, and a parent that is not a
      * conversation. A store refusal (`DbError`,
-     * `ThreadInputError`) passes through unchanged. A failed seed write purges
-     * the child and returns the fault, thus no context-less thread survives.
+     * `ThreadInputError`) passes through unchanged. The row and the seed
+     * commit in one transaction, thus a failed seed leaves no child.
+     *
+     * `childThreadId` names the child, and a spawn with no id mints a random
+     * one. A child with that id already stands after a first spawn, thus a
+     * second spawn gives it back and writes no second seed.
      */
-    spawnReportSession(parentThreadId: string, brief: ReportBrief): ResultAsync<Thread, SpawnRefusal | DbError | ThreadInputError>;
+    spawnReportSession(parentThreadId: string, brief: ReportBrief, childThreadId?: string): ResultAsync<Thread, SpawnRefusal | DbError | ThreadInputError>;
     /**
      * The report sessions of one analysis, through the thread listing narrowed
      * to the type `report`. It adds no predicate of its own, so its answer and
@@ -259,7 +264,7 @@ export interface ReportSessionSpawn {
      * and not by the anchor. It reads no model judgment, and it writes nothing.
      */
     reportSessionDelta(parentThreadId: string): ResultAsync<ReportSessionDelta, DbError>;
-}
+};
 /**
  * The page size of the walk over the report children of one parent. The
  * one-version policy keeps the count of children small, thus the walk reads one