@inflexa-ai/harness 0.45.1 → 0.46.2

package/dist/memory/conversation-display-storage.d.ts

@@ -49,18 +49,28 @@ export type ConversationUIData = {
         })[];
     };
 };
-export interface ConversationDisplayMetadata {
+export type ConversationDisplayMetadata = {
     interrupted?: boolean;
-}
+};
 export type ConversationUIMessage = UIMessage<ConversationDisplayMetadata, ConversationUIData>;
-export interface StoredDisplayEnvelope {
+export type StoredDisplayEnvelope = {
     readonly kind: "ai-sdk-ui-messages";
     readonly aiSdkMajor: 7;
     readonly schemaVersion: typeof SUPPORTED_DISPLAY_SCHEMA_VERSION;
     readonly messages: ConversationUIMessage[];
-}
+};
 export declare function envelopeDisplayMessages(messages: readonly ConversationUIMessage[]): StoredDisplayEnvelope;
 export declare function parseStoredDisplayEnvelope(value: unknown, identity: string, logger?: Logger): Promise<StoredDisplayEnvelope>;
+/** The message-part arm a stored data part round-trips from: the payload is the arm minus its discriminant. */
+export type StoredSourcePart = Extract<Exclude<MessagePart, {
+    type: "text";
+}>, {
+    type: ToolCallPart["type"] | PresentationPart["type"] | PlanPart["type"] | RunCardPart["type"] | PlanApprovalPart["type"] | FileReferencePart["type"] | AskPart["type"] | ChildSessionStartedPart["type"] | ReportRenderedPart["type"] | CompactionPart["type"] | SubAgentActivityPart["type"];
+}>;
+/** Whether `part` is an arm the stored vocabulary can hold; anything else cannot become a stored card. */
+export declare function isStoredSourcePart(part: Exclude<MessagePart, {
+    type: "text";
+}>): part is StoredSourcePart;
 /**
  * Build the stored form of one non-text message part.
  *
@@ -72,9 +82,7 @@ export declare function parseStoredDisplayEnvelope(value: unknown, identity: str
  * lifetime changes — rather than at each reader. An entry of a sub-agent call
  * closes the same way, and an `incomplete` entry has no end time.
  */
-export declare function conversationDisplayPart(part: Exclude<MessagePart, {
-    type: "text";
-}>): DataUIPart<ConversationUIData>;
+export declare function conversationDisplayPart(part: StoredSourcePart): DataUIPart<ConversationUIData>;
 /**
  * Read the durable representation back as chat messages.
  *

package/dist/memory/conversation-display-storage.js

@@ -14,8 +14,11 @@
  * ({@link conversationUIToChatMessages}) is a near-identity rather than a
  * reconstruction.
  */
-import { validateUIMessages } from "ai";
+import { errorMessageOf } from "../lib/thrown.js";
+import { textOf } from "../lib/unknown-text.js";
+import { isDataUIPart, validateUIMessages } from "ai";
 import { z } from "zod";
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
 import { AskPartSchema, ChildSessionStartedPartSchema, CompactionPartSchema, FileReferencePartSchema, PlanApprovalPartSchema, PlanPartSchema, PresentationPartSchema, ReportRenderedPartSchema, RunCardPartSchema, SubAgentActivityEntrySchema, SubAgentActivityPartSchema, } from "../contracts/schemas/chat-parts.js";
 import { ToolCallOutcomeSchema } from "../contracts/schemas/chat-events.js";
 export const SUPPORTED_DISPLAY_SCHEMA_VERSION = 1;
@@ -82,12 +85,9 @@ export function envelopeDisplayMessages(messages) {
         kind: "ai-sdk-ui-messages",
         aiSdkMajor: 7,
         schemaVersion: SUPPORTED_DISPLAY_SCHEMA_VERSION,
-        messages: structuredClone(messages),
+        messages: structuredClone([...messages]),
     };
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 /**
  * Strip every `data-*` part the current vocabulary cannot render.
  *
@@ -109,36 +109,47 @@ function dropUnrenderableDataParts(messages, identity, logger) {
     const unknownKey = [];
     const schemaMismatch = [];
     const filtered = messages.map((message) => {
-        if (!isRecord(message) || !Array.isArray(message.parts))
+        const record = parseUnknownRecord(message);
+        if (record === undefined || !Array.isArray(record.parts))
             return message;
-        const parts = message.parts.filter((part) => {
-            if (!isRecord(part) || typeof part.type !== "string" || !part.type.startsWith("data-"))
+        const parts = record.parts.filter((part) => {
+            const partRecord = parseUnknownRecord(part);
+            if (partRecord === undefined || typeof partRecord.type !== "string" || !partRecord.type.startsWith("data-"))
                 return true;
-            const key = part.type.slice("data-".length);
+            const key = partRecord.type.slice("data-".length);
             // `Object.hasOwn` before the index: a part typed `data-constructor`
             // would otherwise resolve up the prototype chain to something that is
             // not a schema at all, and throw where it should have been dropped.
-            if (!Object.hasOwn(dataSchemas, key)) {
-                unknownKey.push(part.type);
+            // `Object.entries` lists own keys only, so the lookup refuses a
+            // prototype name the same way.
+            const schema = dataSchemaOf(key);
+            if (schema === undefined) {
+                unknownKey.push(partRecord.type);
                 return false;
             }
-            if (!dataSchemas[key].safeParse(part.data).success) {
-                schemaMismatch.push(part.type);
+            if (!schema.safeParse(partRecord.data).success) {
+                schemaMismatch.push(partRecord.type);
                 return false;
             }
             return true;
         });
-        return parts.length === message.parts.length ? message : { ...message, parts };
+        return parts.length === record.parts.length ? message : { ...record, parts };
     });
     if (unknownKey.length > 0 || schemaMismatch.length > 0) {
-        logger?.warn("dropped unrenderable stored display parts", {
-            identity,
-            ...(unknownKey.length > 0 ? { unknownKey: [...new Set(unknownKey)] } : {}),
-            ...(schemaMismatch.length > 0 ? { schemaMismatch: [...new Set(schemaMismatch)] } : {}),
-        });
+        const fields = { identity };
+        if (unknownKey.length > 0)
+            fields.unknownKey = [...new Set(unknownKey)];
+        if (schemaMismatch.length > 0)
+            fields.schemaMismatch = [...new Set(schemaMismatch)];
+        logger?.warn("dropped unrenderable stored display parts", fields);
     }
     return filtered;
 }
+/** The schema behind one stored data-part key, or `undefined` when the key was retired or never stood. */
+function dataSchemaOf(key) {
+    const entry = Object.entries(dataSchemas).find(([name]) => name === key);
+    return entry?.[1];
+}
 export async function parseStoredDisplayEnvelope(value, identity, logger) {
     const header = DisplayEnvelopeHeaderSchema.safeParse(value);
     if (!header.success) {
@@ -153,13 +164,27 @@ export async function parseStoredDisplayEnvelope(value, identity, logger) {
         return { ...header.data, messages };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = errorMessageOf(error) ?? textOf(error);
         throw new Error(`Invalid stored conversation display envelope at ${identity}: ${message}`, { cause: error });
     }
 }
-/** The data-part key a message part is stored under — its `type` minus the `data-` prefix. */
-function displayPartType(part) {
-    return (part.type === "tool-call" ? "data-tool-call" : part.type);
+const STORED_SOURCE_TYPES = [
+    "tool-call",
+    "data-presentation",
+    "data-plan",
+    "data-run-card",
+    "data-plan-approval",
+    "data-file-reference",
+    "data-ask",
+    "data-child-session-started",
+    "data-report-rendered",
+    "data-compaction",
+    "data-subagent-activity",
+];
+const STORED_SOURCE_TYPE_SET = new Set(STORED_SOURCE_TYPES);
+/** Whether `part` is an arm the stored vocabulary can hold; anything else cannot become a stored card. */
+export function isStoredSourcePart(part) {
+    return STORED_SOURCE_TYPE_SET.has(part.type);
 }
 function closedEntry(entry) {
     if (entry.outcome !== undefined)
@@ -185,13 +210,57 @@ function displayPartId(part) {
  * closes the same way, and an `incomplete` entry has no end time.
  */
 export function conversationDisplayPart(part) {
-    const { type: _type, ...rest } = part;
-    const data = part.type === "tool-call"
-        ? { ...rest, outcome: part.outcome ?? "incomplete" }
-        : part.type === "data-subagent-activity"
-            ? { ...rest, entries: part.entries.map(closedEntry) }
-            : rest;
-    return { type: displayPartType(part), id: displayPartId(part), data };
+    const id = displayPartId(part);
+    switch (part.type) {
+        case "tool-call": {
+            const { type: _type, ...payload } = part;
+            return { type: "data-tool-call", id, data: { ...payload, outcome: part.outcome ?? "incomplete" } };
+        }
+        case "data-presentation": {
+            const { type: _type, ...data } = part;
+            return { type: "data-presentation", id, data };
+        }
+        case "data-plan": {
+            const { type: _type, ...data } = part;
+            return { type: "data-plan", id, data };
+        }
+        case "data-run-card": {
+            const { type: _type, ...data } = part;
+            return { type: "data-run-card", id, data };
+        }
+        case "data-plan-approval": {
+            const { type: _type, ...data } = part;
+            return { type: "data-plan-approval", id, data };
+        }
+        case "data-file-reference": {
+            const { type: _type, ...data } = part;
+            return { type: "data-file-reference", id, data };
+        }
+        case "data-ask": {
+            const { type: _type, ...data } = part;
+            return { type: "data-ask", id, data };
+        }
+        case "data-child-session-started": {
+            const { type: _type, ...data } = part;
+            return { type: "data-child-session-started", id, data };
+        }
+        case "data-report-rendered": {
+            const { type: _type, ...data } = part;
+            return { type: "data-report-rendered", id, data };
+        }
+        case "data-compaction": {
+            const { type: _type, ...data } = part;
+            return { type: "data-compaction", id, data };
+        }
+        case "data-subagent-activity": {
+            const { type: _type, ...payload } = part;
+            return { type: "data-subagent-activity", id, data: { ...payload, entries: part.entries.map(closedEntry) } };
+        }
+        default: {
+            const unreachable = part;
+            return unreachable;
+        }
+    }
 }
 /**
  * Read the durable representation back as chat messages.
@@ -214,19 +283,55 @@ export function conversationUIToChatMessages(messages) {
                 parts.push({ type: "tool-call", ...part.data });
                 continue;
             }
-            if (part.type.startsWith("data-")) {
-                const data = part;
-                parts.push({ type: data.type, ...data.data });
+            if (isDataUIPart(part)) {
+                switch (part.type) {
+                    case "data-presentation":
+                        parts.push({ type: "data-presentation", ...part.data });
+                        break;
+                    case "data-plan":
+                        parts.push({ type: "data-plan", ...part.data });
+                        break;
+                    case "data-run-card":
+                        parts.push({ type: "data-run-card", ...part.data });
+                        break;
+                    case "data-plan-approval":
+                        parts.push({ type: "data-plan-approval", ...part.data });
+                        break;
+                    case "data-file-reference":
+                        parts.push({ type: "data-file-reference", ...part.data });
+                        break;
+                    case "data-ask":
+                        parts.push({ type: "data-ask", ...part.data });
+                        break;
+                    case "data-child-session-started":
+                        parts.push({ type: "data-child-session-started", ...part.data });
+                        break;
+                    case "data-report-rendered":
+                        parts.push({ type: "data-report-rendered", ...part.data });
+                        break;
+                    case "data-compaction":
+                        parts.push({ type: "data-compaction", ...part.data });
+                        break;
+                    case "data-subagent-activity":
+                        parts.push({ type: "data-subagent-activity", ...part.data });
+                        break;
+                    default: {
+                        const unhandled = part;
+                        throw new Error(`stored display part has no chat-part arm: ${String(unhandled)}`);
+                    }
+                }
             }
         }
         if (parts.length === 0)
             continue;
-        out.push({
+        const chat = {
             id: message.id,
             role: message.role,
             parts,
-            ...(message.metadata?.interrupted ? { interrupted: true } : {}),
-        });
+        };
+        if (message.metadata?.interrupted)
+            chat.interrupted = true;
+        out.push(chat);
     }
     return out;
 }

package/dist/memory/conversation-view.d.ts

@@ -35,15 +35,15 @@ export declare function isGenuineUserStart(message: ModelMessage): boolean;
  * (`loadAll`) share it, each supplying its own start predicate.
  */
 export declare function groupTurns<T>(rows: readonly T[], isStart: (row: T) => boolean): T[][];
-export interface ConversationViewOptions {
+export type ConversationViewOptions = {
     /** Keep the first turn in front of the view: the seed of a report thread. */
     readonly keepFirstTurn?: boolean;
-}
-export interface ConversationView {
+};
+export type ConversationView = {
     readonly messages: ModelMessage[];
     /** `sources[i]` is the index of the input message that gives `messages[i]`. */
     readonly sources: number[];
-}
+};
 export declare function conversationView(messages: readonly ModelMessage[], options: ConversationViewOptions): ConversationView;
 /** The message with no reasoning part, or `undefined` for an assistant message with no part left. */
 export declare function withoutReasoning(message: ModelMessage): ModelMessage | undefined;

package/dist/memory/conversation-view.js

@@ -4,6 +4,7 @@
  * turns of the body without their reasoning. The loop and the reader call this one function, thus the
  * next turn reads back the prefix that the last request sent.
  */
+import { presentAt, presentLast } from "../lib/present.js";
 import { compactionExchangeOf, compactionMarkerOf, isSyntheticUserMessage, requestInputTokensOf } from "./ai-sdk-message-storage.js";
 /**
  * A turn starts on a `user` message that a human actually sent. Two kinds of
@@ -43,7 +44,7 @@ export function groupTurns(rows, isStart) {
             turns.push([row]);
         }
         else {
-            turns[turns.length - 1].push(row);
+            presentLast(turns, "the open turn").push(row);
         }
     }
     return turns;
@@ -66,7 +67,7 @@ function viewParts(messages, options) {
     let headEnd = 0;
     if (options.keepFirstTurn === true) {
         while (headEnd < messages.length) {
-            const message = messages[headEnd];
+            const message = presentAt(messages, headEnd, "the head message");
             if (isCompactionMessage(message) || (headEnd > 0 && isGenuineUserStart(message)))
                 break;
             headEnd++;
@@ -76,7 +77,7 @@ function viewParts(messages, options) {
     let front;
     let body = [];
     for (let source = headEnd; source < messages.length; source++) {
-        const message = messages[source];
+        const message = presentAt(messages, source, "the message at the source index");
         if (compactionExchangeOf(message) !== undefined)
             continue;
         const marker = compactionMarkerOf(message);
@@ -115,7 +116,7 @@ export function withoutReasoning(message) {
  */
 export function lastRequestInputTokens(messages) {
     for (let at = messages.length - 1; at >= 0; at--) {
-        const message = messages[at];
+        const message = presentAt(messages, at, "the message at the index");
         if (compactionMarkerOf(message) !== undefined)
             return undefined;
         const tokens = requestInputTokensOf(message);

package/dist/memory/count-tokens.js

@@ -8,7 +8,9 @@
  * callers treat the budget as a soft target with a safety margin below the
  * true context limit.
  */
+import { textOf } from "../lib/unknown-text.js";
 import { getEncoding } from "js-tiktoken";
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
 let encoder;
 function enc() {
     encoder ??= getEncoding("cl100k_base");
@@ -27,16 +29,16 @@ function enc() {
  * Each other output arm is plain JSON, thus it is stringified whole.
  */
 function toolResultText(output) {
-    if (typeof output !== "object" || output === null)
+    const out = parseUnknownRecord(output);
+    if (out === undefined)
         return JSON.stringify(output ?? {});
-    const out = output;
     if (out.type !== "content" || !Array.isArray(out.value))
         return JSON.stringify(out);
     const texts = [];
     for (const item of out.value) {
-        if (typeof item !== "object" || item === null)
+        const nested = parseUnknownRecord(item);
+        if (nested === undefined)
             continue;
-        const nested = item;
         if (nested.type === "text" && typeof nested.text === "string")
             texts.push(nested.text);
     }
@@ -52,9 +54,9 @@ function toolResultText(output) {
 function tokenizableText(block) {
     if (typeof block === "string")
         return block;
-    if (typeof block !== "object" || block === null)
+    const part = parseUnknownRecord(block);
+    if (part === undefined)
         return JSON.stringify(block);
-    const part = block;
     switch (part.type) {
         case "text":
             return typeof part.text === "string" ? part.text : "";
@@ -66,9 +68,9 @@ function tokenizableText(block) {
         case "image":
             return "";
         case "tool-call":
-            return `${String(part.toolName ?? "")} ${JSON.stringify(part.input ?? {})}`;
+            return `${textOf(part.toolName ?? "")} ${JSON.stringify(part.input ?? {})}`;
         case "tool-result": {
-            return `${String(part.toolName ?? "")} ${toolResultText(part.output)}`;
+            return `${textOf(part.toolName ?? "")} ${toolResultText(part.output)}`;
         }
         default:
             return JSON.stringify(part);

package/dist/memory/derive-thread-title.d.ts

@@ -1,14 +1 @@
-/**
- * Derive a deterministic thread title from the user's first message.
- * Pure function — no I/O, no global state.
- *
- * Rules:
- * 1. Collapse runs of whitespace to a single space.
- * 2. Trim.
- * 3. Empty / whitespace-only input → `"Untitled"`.
- * 4. If length ≤ `max`, return unchanged.
- * 5. Else slice to `max`, walk back to the last space (word boundary),
- *    append the real ellipsis `…` (U+2026). If no space exists inside
- *    the window, hard-slice at `max` and append `…`.
- */
 export declare function deriveThreadTitle(text: string, max?: number): string;

package/dist/memory/derive-thread-title.js

@@ -11,8 +11,9 @@
  *    append the real ellipsis `…` (U+2026). If no space exists inside
  *    the window, hard-slice at `max` and append `…`.
  */
+import { collapseWhitespace } from "../lib/text.js";
 export function deriveThreadTitle(text, max = 40) {
-    const normalized = text.replace(/\s+/g, " ").trim();
+    const normalized = collapseWhitespace(text);
     if (normalized.length === 0)
         return "Untitled";
     if (normalized.length <= max)

package/dist/memory/message-backfill.d.ts

@@ -1,8 +1,15 @@
 import type { QueryResultRow } from "pg";
 /** The query method of a `pg` client, which the migration transaction also supplies. */
-export interface BackfillClient {
-    query<R extends QueryResultRow>(text: string, values?: unknown[]): Promise<{
-        rows: R[];
+export type BackfillClient<Row extends QueryResultRow = QueryResultRow> = {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Row[];
     }>;
-}
-export declare function backfillAiSdkMessageEnvelopes(client: BackfillClient): Promise<void>;
+};
+type LegacyRow = {
+    readonly thread_id: string;
+    readonly seq: string;
+    readonly role: string;
+    readonly content_jsonb: string | Array<Record<string, unknown>>;
+};
+export declare function backfillAiSdkMessageEnvelopes(client: BackfillClient<LegacyRow>): Promise<void>;
+export {};

package/dist/memory/message-backfill.js

@@ -1,3 +1,5 @@
+import { errorMessageOf } from "../lib/thrown.js";
+import { textOf } from "../lib/unknown-text.js";
 import { envelopeMessage, legacyAnthropicToModelMessage } from "./ai-sdk-message-storage.js";
 export async function backfillAiSdkMessageEnvelopes(client) {
     // Legacy Anthropic columns (`role`, `content_jsonb`) are temporary and
@@ -22,7 +24,7 @@ export async function backfillAiSdkMessageEnvelopes(client) {
             ]);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
+            const message = errorMessageOf(err) ?? textOf(err);
             throw new Error(`Failed to backfill AI SDK message envelope for ${identity}: ${message}`, { cause: err });
         }
     }
@@ -31,8 +33,8 @@ export async function backfillAiSdkMessageEnvelopes(client) {
          WHERE message_envelope IS NULL
          ORDER BY thread_id, seq
          LIMIT 1`);
-    if (remaining.rows.length > 0) {
-        const row = remaining.rows[0];
+    const [row] = remaining.rows;
+    if (row !== undefined) {
         throw new Error(`AI SDK message backfill left an unmigrated row at ${row.thread_id}/${row.seq}`);
     }
 }

package/dist/memory/thread-history.d.ts

@@ -22,15 +22,15 @@
  */
 import type { ModelMessage } from "ai";
 import { ResultAsync } from "neverthrow";
-import type { Pool } from "pg";
 import type { TokenUsageRollup } from "../contracts/usage.js";
-import { type DbError } from "../lib/db-result.js";
+import { type Connectable, type DbError, type TransactionQuerier } from "../lib/db-result.js";
 import type { Logger } from "../lib/logger.js";
+import type { Querier } from "../state/db.js";
 import { type StoredMessageEnvelope } from "./ai-sdk-message-storage.js";
 import type { MessagePart } from "../contracts/message.js";
 import { type ConversationUIMessage, type StoredDisplayEnvelope } from "./conversation-display-storage.js";
 /** One stored message, as returned by the display reads (`loadAll` and `loadPage`). */
-export interface StoredMessage {
+export type StoredMessage = {
     readonly seq: number;
     readonly envelope: StoredMessageEnvelope;
     readonly message: ModelMessage;
@@ -69,7 +69,7 @@ export interface StoredMessage {
      * behind it.
      */
     readonly createdAt?: Date;
-}
+};
 /**
  * One atomic group of rows: the exact provider-facing history, and the display
  * projection of what the user was shown.
@@ -79,7 +79,7 @@ export interface StoredMessage {
  * what the transcript replays. Neither is derived from the other, and a failed
  * write commits neither.
  */
-export interface ConversationTurn {
+export type ConversationTurn = {
     /** Exact provider-facing history; token accounting and model reads use only this projection. */
     readonly modelMessages: readonly ModelMessage[];
     /** Complete ordered AI SDK UI messages recorded from the live display event stream. */
@@ -94,7 +94,12 @@ export interface ConversationTurn {
      * envelope, because a `text` parameter carrying 0x00 fails the statement.
      */
     readonly author?: string;
-}
+    /**
+     * The key of the group in its turn, stored on its first row. A turn workflow gives each group a key, thus a
+     * write that runs again after its commit finds the key and stores nothing.
+     */
+    readonly key?: string;
+};
 /**
  * The append a host uses to record out-of-band work in a thread — an analysis
  * run's outcome, typically.
@@ -116,7 +121,7 @@ export declare function conversationRecordTurn(text: string, displayParts?: read
 /** The status of a chat turn: `open` while it runs, then its outcome. */
 export type TurnStatus = "open" | "done" | "aborted" | "failed";
 /** The close of a chat turn. It sets the outcome on the turn record, one time. */
-export interface TurnClose {
+export type TurnClose = {
     readonly status: Exclude<TurnStatus, "open">;
     /** The reason of a failure. */
     readonly reason?: string;
@@ -125,7 +130,7 @@ export interface TurnClose {
     readonly turnDurationMs?: number;
     /** The note of a failure or of an abort, stored after the rounds. */
     readonly note?: ConversationTurn;
-}
+};
 /**
  * One write of a chat turn. The opening adds the turn record, and a later write names the turn by
  * `startSeq`. The `never` members make a write with both keys fail to compile.
@@ -141,17 +146,17 @@ export type TurnWrite = {
     readonly rounds: readonly ConversationTurn[];
     readonly close?: TurnClose;
 };
-export interface TurnWriteResult {
+export type TurnWriteResult = {
     /** The `seq` of the user row that opens the turn, which keys its turn record. */
     readonly startSeq: number;
-}
+};
 /** The turn record of a chat turn, as the display read gives it. */
-export interface StoredTurnRecord {
+export type StoredTurnRecord = {
     readonly status: TurnStatus;
     readonly reason?: string;
     readonly usage?: TokenUsageRollup;
     readonly durationMs?: number;
-}
+};
 /**
  * The result of `retractLastTurn`. `retracted` carries `messages` — the number
  * of rows removed — so a caller can assert exactly what came off the tail. The
@@ -168,29 +173,34 @@ export type RetractOutcome = {
     kind: "no-user-turn";
 };
 /** The read options of {@link ThreadHistory.loadRecent}. */
-export interface LoadRecentOptions {
+export type LoadRecentOptions = {
     /** Keep the first turn of the thread, the seed of a report thread, in front of the latest summary. */
     readonly keepFirstTurn?: boolean;
-}
+    /**
+     * Read the rows up to this `seq` only. A row never changes after its write, thus a turn workflow that reads up
+     * to the last row before its turn reads the same view on a replay.
+     */
+    readonly throughSeq?: number;
+};
 /** The options of {@link ThreadHistory.loadPage}. */
-export interface LoadPageOptions {
+export type LoadPageOptions = {
     /** The cursor that the previous page gave. Absent for the newest page. */
     readonly before?: number;
     /** The maximum count of turns in the page. */
     readonly limit: number;
-}
+};
 /** One page of the display read, as {@link ThreadHistory.loadPage} gives it. */
-export interface TurnPage {
+export type TurnPage = {
     /** The whole turns of the page, oldest-first. */
     readonly turns: StoredMessage[][];
     /** The cursor of the next older page, or `null` when the page holds the oldest row of the thread. */
     readonly before: number | null;
-}
+};
 /**
  * The conversation message store. Two methods, by design — no generic row
  * insert (see the harness-thread-store spec). `threadId` is the conversation scope — one UI thread.
  */
-export interface ThreadHistory {
+export type ThreadHistory = {
     /**
      * Append one group, for example a record of a host — every message written in a
      * single transaction with a `seq` monotonically increasing per thread.
@@ -286,7 +296,7 @@ export interface ThreadHistory {
      * one adds to the count.
      */
     countUserTurnsAfter(threadId: string, seq: number): ResultAsync<number, DbError>;
-}
+};
 /**
  * Drop the memoized instruments so the next `loadRecent` rebinds to a
  * freshly-registered `MeterProvider`. Test-only.
@@ -302,4 +312,9 @@ export declare function __resetThreadHistoryMetricsForTest(): void;
  * same messages either way — the drop reports a deploy, not a failed read — and
  * requiring it would break every call site over a diagnostic.
  */
-export declare function createThreadHistory(pool: Pool, logger?: Logger): ThreadHistory;
+/** What this module reads of the pool: the direct `query` plus the transactional `connect`. */
+type ThreadHistoryPool = Querier & Connectable;
+/** `appendTurn` inside the transaction of the caller, thus another write of the caller commits with the turn or not at all. */
+export declare function appendTurnIn(client: TransactionQuerier, threadId: string, turn: ConversationTurn): ResultAsync<void, DbError>;
+export declare function createThreadHistory(pool: ThreadHistoryPool, logger?: Logger): ThreadHistory;
+export {};