@inflexa-ai/harness 0.45.0 → 0.46.0

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 read (`loadAll`). */
-export interface StoredMessage {
+/** One stored message, as returned by the display reads (`loadAll` and `loadPage`). */
+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,15 +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 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 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.
@@ -195,12 +219,8 @@ export interface ThreadHistory {
     /**
      * Return a thread's messages oldest-first for UI display, grouped into turns.
      * It gives each row, and the view of the agent loop is `loadRecent`'s job.
-     *
-     * There is no paginated form, because a page could never cost less: the read
-     * selects and parses every row of the thread and would slice only afterwards,
-     * so a page saves no query and no parse. It would only truncate the answer,
-     * which is a way to lose turns and not a way to save work. A reader wanting a
-     * window takes one here, where it knows what it is bounding.
+     * It selects and parses every row of the thread, thus its work grows with the
+     * thread. {@link ThreadHistory.loadPage} bounds that work.
      *
      * Grouped rather than flat because the grouping is what the read computes and
      * what a turn count means, and `.flat()` recovers the rows in `seq` order for
@@ -209,6 +229,23 @@ export interface ThreadHistory {
      * this read already found.
      */
     loadAll(threadId: string): ResultAsync<StoredMessage[][], DbError>;
+    /**
+     * Return the newest whole turns of a thread for UI display, up to `limit` turns, oldest-first.
+     * With `before`, it returns the newest whole turns below the turn that the cursor names.
+     * The rows are the same as the rows of {@link ThreadHistory.loadAll}.
+     *
+     * The read selects and parses only the rows of its page, thus its work does not grow with
+     * the turns before the page. The page edges inside the thread are turn starts, so the read
+     * never truncates a turn, also for a cursor that is not a turn start: the turn of the cursor
+     * row is then the newest turn of the page, and it is whole. The rows before the first turn
+     * start make one group, and the group counts as a turn.
+     *
+     * The cursor is the `seq` of the opening row of the oldest turn of the page. A `seq` never
+     * moves and a retract removes only the tail, thus a cursor stays correct across a later
+     * append and a later retract. A `limit` that is not finite reads as 1, and each other
+     * `limit` reads as its integer part with a minimum of 1.
+     */
+    loadPage(threadId: string, options: LoadPageOptions): ResultAsync<TurnPage, DbError>;
     /**
      * Remove the thread's most recent turn — every row from the last
      * genuine-user-start `seq` onward, and its turn record — in a single transaction.
@@ -259,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.
@@ -275,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 {};

package/dist/memory/thread-history.js

@@ -25,11 +25,12 @@ import { metrics } from "@opentelemetry/api";
 import { ResultAsync, ok, okAsync } from "neverthrow";
 import { stripNulCharacters } from "../input-sanitization.js";
 import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
+import { presentFirst } from "../lib/present.js";
 import { hasReportedUsage } from "../loop/metrics.js";
 import { countTokens } from "./count-tokens.js";
 import { conversationView, groupTurns, isGenuineUserStart } from "./conversation-view.js";
 import { HARNESS_PROVIDER_NAMESPACE, SYNTHETIC_MESSAGE_KEY, envelopeMessage, parseStoredMessageEnvelope, syntheticRecordMessage, } from "./ai-sdk-message-storage.js";
-import { conversationDisplayPart, envelopeDisplayMessages, parseStoredDisplayEnvelope, } from "./conversation-display-storage.js";
+import { conversationDisplayPart, envelopeDisplayMessages, isStoredSourcePart, parseStoredDisplayEnvelope, } from "./conversation-display-storage.js";
 /** A resolved `ok(undefined)` ResultAsync — the empty/seed transaction step. */
 function okVoid() {
     return new ResultAsync(Promise.resolve(ok(undefined)));
@@ -56,7 +57,9 @@ export function conversationRecordTurn(text, displayParts) {
             {
                 id: randomUUID(),
                 role: "system",
-                parts: displayParts !== undefined && displayParts.length > 0 ? displayParts.map(conversationDisplayPart) : [{ type: "text", text, state: "done" }],
+                parts: displayParts !== undefined && displayParts.length > 0
+                    ? displayParts.filter(isStoredSourcePart).map(conversationDisplayPart)
+                    : [{ type: "text", text, state: "done" }],
             },
         ],
     };
@@ -128,12 +131,12 @@ function nextSeq(client, threadId, op) {
         const { rows } = await client.query("SELECT COALESCE(MAX(seq), -1)::text AS max_seq FROM messages WHERE thread_id = $1", [
             threadId,
         ]);
-        return Number(rows[0].max_seq) + 1;
+        return Number(presentFirst(rows, "the max-seq row").max_seq) + 1;
     });
 }
 /** Insert the rows of one group, from `startSeq` on. */
 function insertGroup(client, threadId, startSeq, group, op) {
-    const { modelMessages: messages, displayMessages, author } = group;
+    const { modelMessages: messages, displayMessages, author, key } = group;
     // The display projection rides the group's FIRST row, so one SELECT of a
     // thread's rows yields every envelope in order with no join and no grouping.
     // Whichever row that is — a genuine user message opening a turn, or the lone
@@ -154,19 +157,21 @@ function insertGroup(client, threadId, startSeq, group, op) {
     return messages.reduce((chain, message, i) => chain.andThen(() => tryMutation(`${op}.insert`, () => client.query(
     // `message_envelope::json`, never `::jsonb`; `display_envelope::jsonb`,
     // never `::json` — see the column comments in the state-init DDL.
-    `INSERT INTO messages (thread_id, seq, message_envelope, display_envelope, tokens, author)
-                     VALUES ($1, $2, $3::json, $4::jsonb, $5, $6)
+    `INSERT INTO messages (thread_id, seq, message_envelope, display_envelope, tokens, author, round_key)
+                     VALUES ($1, $2, $3::json, $4::jsonb, $5, $6, $7)
                      ON CONFLICT (thread_id, seq) DO UPDATE
                        SET message_envelope = EXCLUDED.message_envelope,
                            display_envelope = EXCLUDED.display_envelope,
                            tokens = EXCLUDED.tokens,
-                           author = EXCLUDED.author`, [
+                           author = EXCLUDED.author,
+                           round_key = EXCLUDED.round_key`, [
         threadId,
         startSeq + i,
         serializeEnvelope(message),
         i === 0 ? displayEnvelope : null,
         countTokens(message.content),
         i === authorRow ? turnAuthor : null,
+        i === 0 ? (key ?? null) : null,
     ])).map(() => undefined)), okVoid());
 }
 /** Move `cortex_analysis_threads.updated_at` forward inside the write transaction. */
@@ -209,6 +214,16 @@ function touchThread(client, threadId, op) {
         .map(() => undefined)
         .orElse(() => okVoid()));
 }
+/** The `seq` of the first row of a group that a write stored before, by the key of the group. */
+function storedGroupSeq(client, threadId, key, op) {
+    if (key === undefined)
+        return okAsync(undefined);
+    return tryQuery(`${op}.storedKey`, async () => {
+        const { rows } = await client.query("SELECT seq::text AS seq FROM messages WHERE thread_id = $1 AND round_key = $2", [threadId, key]);
+        const row = rows[0];
+        return row === undefined ? undefined : Number(row.seq);
+    });
+}
 /** Add the `open` record of a turn. The upsert replaces a record whose rows are gone, because the opening row holds its key now. */
 function openTurnRecord(client, threadId, startSeq) {
     return tryMutation("thread-history.writeTurn.openRecord", () => client.query(`INSERT INTO cortex_thread_turns (thread_id, start_seq, status)
@@ -224,46 +239,146 @@ function closeTurnRecord(client, threadId, startSeq, close) {
                 SET status = $3, reason = $4, reported_usage = $5::jsonb, turn_duration_ms = $6, closed_at = NOW()
               WHERE thread_id = $1 AND start_seq = $2 AND status = 'open'`, [threadId, startSeq, close.status, close.reason === undefined ? null : stripNulCharacters(close.reason), rollup, close.turnDurationMs ?? null])).map(() => undefined);
 }
+/** The columns of a display-read row, and the join that the turn record needs. Both display reads select them. */
+const STORED_ROW_COLUMNS = `messages.seq::text AS seq, messages.message_envelope, messages.display_envelope, messages.reported_usage,
+                messages.turn_duration_ms::text AS turn_duration_ms, messages.author, messages.created_at,
+                turns.status AS turn_status, turns.reason AS turn_reason, turns.reported_usage AS turn_usage,
+                turns.turn_duration_ms::text AS turn_record_duration_ms`;
+function storedRowFrom(turnJoinBounds = "") {
+    return `FROM messages
+         LEFT JOIN cortex_thread_turns turns ON turns.thread_id = messages.thread_id AND turns.start_seq = messages.seq${turnJoinBounds}`;
+}
+/** The largest `bigint`, the bound of a cursor that the caller did not give. */
+const MAX_SEQ = "9223372036854775807";
+/** The smallest `bigint`, below every `seq`. */
+const MIN_SEQ = "'-9223372036854775808'";
+const PAGE_LOWER_BOUND = `COALESCE((SELECT seq FROM page_lower), ${MIN_SEQ}::bigint)`;
+const PAGE_UPPER_BOUND = `COALESCE((SELECT seq FROM page_upper), ${MAX_SEQ}::bigint)`;
 /**
- * Create a `ThreadHistory` bound to a Postgres pool — a factory closure
- * capturing `pool` (dependency injection per the harness-durable-runtime spec). The `messages` table is
- * provisioned by the project's state-init DDL.
+ * The statement of one page of the display read (`$1` thread, `$2` cursor or `NULL`, `$3` limit).
+ *
+ * One statement reads one snapshot, thus an append or a retract cannot add a turn between the
+ * read of the page edges and the read of the rows. The parts:
  *
- * `logger` serves exactly one purpose: reporting a stored display part the
- * current vocabulary had to drop. It is optional because the read returns the
- * same messages either way — the drop reports a deploy, not a failed read — and
- * requiring it would break every call site over a diagnostic.
+ * - `page_walk`: a walk down from the cursor, one row for each step, that counts the turn starts
+ *   and stops at the `$3`-th. Each step is a `LIMIT 1` read of the primary key `(thread_id, seq)`
+ *   that evaluates the start predicate in the select list.
+ * - `page_lower`: the row where the walk reached `$3` starts, else `NULL`. A page that is not
+ *   full reaches the start of the thread and holds the rows before the first turn start.
+ * - `page_climb` and `page_upper`: a walk up from the cursor to the first turn start at or above
+ *   it, else `NULL`. For a cursor that a page gave this is the cursor row. For a cursor inside a
+ *   turn it is the start of the next turn, thus the turn of the cursor stays whole.
+ * - `page_next`: `page_lower` when a row lies below it. The `EXISTS` reads no envelope.
+ *
+ * The start predicate is never a `WHERE` condition of a scan that has an `ORDER BY` and a `LIMIT`.
+ * The planner has no statistics for a JSON path, so it estimates that very few rows match. It then
+ * chooses a bitmap scan and a sort of each row of the thread, and it evaluates the predicate on the
+ * envelope of each row (a tool result can be many KB). A walk of `LIMIT 1` reads of the key does
+ * not depend on that estimate, and its work grows with the rows of the page.
+ *
+ * An absent cursor, `page_lower`, and `page_upper` each become a `bigint` extreme through
+ * `COALESCE`, never a `NULL` in a comparison: `seq >= NULL` matches no row, and a form such as
+ * `($2 IS NULL OR seq < $2)` is a filter, which would visit each newer row. Each bound is an
+ * index condition on `(thread_id, seq)`. The join to the turn records carries the same bounds,
+ * because the planner estimates a bounded range as a fixed fraction of the thread and then reads
+ * each turn record of the thread through a hash join.
  */
+const PAGE_SQL = `WITH RECURSIVE page_walk(seq, starts) AS (
+           SELECT COALESCE($2::bigint, ${MAX_SEQ}::bigint), 0::bigint
+           UNION ALL
+           SELECT below.seq, page_walk.starts + below.is_start::int
+             FROM page_walk
+            CROSS JOIN LATERAL (
+              SELECT messages.seq, COALESCE(${GENUINE_USER_START_SQL}, false) AS is_start FROM messages
+               WHERE messages.thread_id = $1 AND messages.seq < page_walk.seq
+               ORDER BY messages.seq DESC
+               LIMIT 1
+            ) below
+            WHERE page_walk.starts < $3::bigint
+         ),
+         page_lower AS (
+           SELECT (SELECT page_walk.seq FROM page_walk WHERE page_walk.starts = $3::bigint) AS seq
+         ),
+         page_climb(seq, is_start) AS (
+           SELECT above.seq, above.is_start FROM (
+             SELECT messages.seq, COALESCE(${GENUINE_USER_START_SQL}, false) AS is_start FROM messages
+              WHERE messages.thread_id = $1 AND messages.seq >= COALESCE($2::bigint, ${MAX_SEQ}::bigint)
+              ORDER BY messages.seq ASC
+              LIMIT 1
+           ) above
+           UNION ALL
+           SELECT above.seq, above.is_start
+             FROM page_climb
+            CROSS JOIN LATERAL (
+              SELECT messages.seq, COALESCE(${GENUINE_USER_START_SQL}, false) AS is_start FROM messages
+               WHERE messages.thread_id = $1 AND messages.seq > page_climb.seq
+               ORDER BY messages.seq ASC
+               LIMIT 1
+            ) above
+            WHERE NOT page_climb.is_start
+         ),
+         page_upper AS (
+           SELECT page_climb.seq FROM page_climb WHERE page_climb.is_start
+         ),
+         page_next AS (
+           SELECT page_lower.seq FROM page_lower
+            WHERE page_lower.seq IS NOT NULL
+              AND EXISTS (SELECT 1 FROM messages WHERE thread_id = $1 AND seq < page_lower.seq)
+         )
+         SELECT ${STORED_ROW_COLUMNS}, (SELECT seq::text FROM page_next) AS next_before
+         ${storedRowFrom(` AND turns.start_seq >= ${PAGE_LOWER_BOUND} AND turns.start_seq < ${PAGE_UPPER_BOUND}`)}
+         WHERE messages.thread_id = $1
+           AND messages.seq >= ${PAGE_LOWER_BOUND}
+           AND messages.seq < ${PAGE_UPPER_BOUND}
+         ORDER BY messages.seq ASC`;
+/** The limit that the page statement receives: an integer, at least 1, and a bigint-safe size. */
+function pageLimit(limit) {
+    return Number.isFinite(limit) ? Math.min(Math.max(1, Math.trunc(limit)), Number.MAX_SAFE_INTEGER) : 1;
+}
+/** `appendTurn` inside the transaction of the caller, thus another write of the caller commits with the turn or not at all. */
+export function appendTurnIn(client, threadId, turn) {
+    if (turn.modelMessages.length === 0)
+        return okVoid();
+    return lockThread(client, threadId, "thread-history.appendTurn")
+        .andThen(() => nextSeq(client, threadId, "thread-history.appendTurn"))
+        .andThen((startSeq) => insertGroup(client, threadId, startSeq, turn, "thread-history.appendTurn"))
+        .andThen(() => touchThread(client, threadId, "thread-history.appendTurn"));
+}
 export function createThreadHistory(pool, logger) {
     function appendTurn(threadId, turn) {
         if (turn.modelMessages.length === 0)
             return okVoid();
-        return withTransaction(pool, "thread-history.appendTurn", (client) => lockThread(client, threadId, "thread-history.appendTurn")
-            .andThen(() => nextSeq(client, threadId, "thread-history.appendTurn"))
-            .andThen((startSeq) => insertGroup(client, threadId, startSeq, turn, "thread-history.appendTurn"))
-            .andThen(() => touchThread(client, threadId, "thread-history.appendTurn")));
+        return withTransaction(pool, "thread-history.appendTurn", (client) => appendTurnIn(client, threadId, turn));
     }
     function writeTurn(threadId, write) {
         const { close } = write;
         const groups = [...(write.opening === undefined ? [] : [write.opening]), ...write.rounds, ...(close?.note === undefined ? [] : [close.note])];
         return withTransaction(pool, "thread-history.writeTurn", (client) => lockThread(client, threadId, "thread-history.writeTurn")
-            .andThen(() => nextSeq(client, threadId, "thread-history.writeTurn"))
-            .andThen((firstSeq) => {
-            const startSeq = write.opening === undefined ? write.startSeq : firstSeq;
-            const steps = [];
-            let seq = firstSeq;
-            for (const [index, group] of groups.entries()) {
-                const groupSeq = seq;
-                seq += group.modelMessages.length;
-                steps.push(() => insertGroup(client, threadId, groupSeq, group, "thread-history.writeTurn"));
-                if (index === 0 && write.opening !== undefined)
-                    steps.push(() => openTurnRecord(client, threadId, startSeq));
-            }
-            if (close !== undefined)
-                steps.push(() => closeTurnRecord(client, threadId, startSeq, close));
-            steps.push(() => touchThread(client, threadId, "thread-history.writeTurn"));
-            return steps.reduce((chain, step) => chain.andThen(step), okVoid()).map(() => ({ startSeq }));
+            // One transaction stores each group of a write, thus a stored first group means a stored write.
+            .andThen(() => storedGroupSeq(client, threadId, groups[0]?.key, "thread-history.writeTurn"))
+            .andThen((storedSeq) => {
+            if (storedSeq === undefined)
+                return writeGroups(client);
+            return okAsync({ startSeq: write.opening === undefined ? write.startSeq : storedSeq });
         }));
+        function writeGroups(client) {
+            return nextSeq(client, threadId, "thread-history.writeTurn").andThen((firstSeq) => {
+                const startSeq = write.opening === undefined ? write.startSeq : firstSeq;
+                const steps = [];
+                let seq = firstSeq;
+                for (const [index, group] of groups.entries()) {
+                    const groupSeq = seq;
+                    seq += group.modelMessages.length;
+                    steps.push(() => insertGroup(client, threadId, groupSeq, group, "thread-history.writeTurn"));
+                    if (index === 0 && write.opening !== undefined)
+                        steps.push(() => openTurnRecord(client, threadId, startSeq));
+                }
+                if (close !== undefined)
+                    steps.push(() => closeTurnRecord(client, threadId, startSeq, close));
+                steps.push(() => touchThread(client, threadId, "thread-history.writeTurn"));
+                return steps.reduce((chain, step) => chain.andThen(step), okVoid()).map(() => ({ startSeq }));
+            });
+        }
     }
     function loadRecent(threadId, options) {
         return tryQuery("thread-history.loadRecent", async () => {
@@ -279,7 +394,7 @@ export function createThreadHistory(pool, logger) {
             // nothing has no rollup at all. The two are different measurements
             // sharing a unit; see the column comments.
             `SELECT seq::text AS seq, message_envelope, tokens
-         FROM messages WHERE thread_id = $1 ORDER BY messages.seq ASC`, [threadId]);
+         FROM messages WHERE thread_id = $1 AND ($2::bigint IS NULL OR messages.seq <= $2::bigint) ORDER BY messages.seq ASC`, [threadId, options?.throughSeq ?? null]);
             const parsed = rows.map((row, index) => ({
                 index,
                 message: parseStoredMessageEnvelope(row.message_envelope, `${threadId}/${row.seq}`).message,
@@ -296,59 +411,77 @@ export function createThreadHistory(pool, logger) {
             return view.messages;
         });
     }
-    // Display reads are turn-bounded, not row-bounded. A serial-tool assistant
-    // turn is persisted as one row per step (plus its tool_result `user` rows),
-    // so a row-windowed page could split a turn — truncating the trailing
-    // report card/text out of the page the UI fetches. Read the thread and group
-    // into turns, so a turn always reloads intact. Threads are conversation-scoped
-    // and bounded, so reading every row here matches `loadRecent`'s existing
+    // A display read is turn-bounded, not row-bounded. A serial-tool assistant
+    // turn is persisted as one row per step (plus its tool_result rows), so a
+    // row-windowed read could split a turn and truncate the trailing report
+    // card or text out of what the UI fetches. Both reads group rows into turns,
+    // so a turn always reloads intact.
+    // Spread rather than `usage: r.reported_usage ?? undefined`, so a row with
+    // no rollup carries no `usage` KEY at all — absent, not present-and-undefined.
+    // The duration and the author obey the same rule, each from its own column.
+    // The creation time is unconditional: its column is NOT NULL, thus it has no
+    // absence to represent.
+    async function toStoredMessage(threadId, r) {
+        const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
+        const displayEnvelope = r.display_envelope == null ? undefined : await parseStoredDisplayEnvelope(r.display_envelope, `${threadId}/${r.seq}/display`, logger);
+        const row = {
+            seq: Number(r.seq),
+            envelope,
+            message: envelope.message,
+            displayEnvelope,
+            createdAt: r.created_at,
+        };
+        if (r.reported_usage !== null)
+            row.usage = r.reported_usage;
+        if (r.turn_duration_ms !== null)
+            row.durationMs = Number(r.turn_duration_ms);
+        if (r.author !== null)
+            row.author = r.author;
+        if (r.turn_status !== null) {
+            const turn = { status: r.turn_status };
+            if (r.turn_reason !== null)
+                turn.reason = r.turn_reason;
+            if (r.turn_usage !== null)
+                turn.usage = r.turn_usage;
+            if (r.turn_record_duration_ms !== null)
+                turn.durationMs = Number(r.turn_record_duration_ms);
+            row.turn = turn;
+        }
+        return row;
+    }
+    async function toTurns(threadId, rows) {
+        const stored = await Promise.all(rows.map((row) => toStoredMessage(threadId, row)));
+        return groupTurns(stored, (row) => isGenuineUserStart(row.message));
+    }
     async function readTurns(threadId) {
         const { rows } = await pool.query(
         // ORDER BY must qualify `messages.seq` — a bare `seq` would bind to the
         // `seq::text AS seq` output alias (Postgres resolves an unqualified
         // ORDER BY name to the output column), sorting the bigint as text:
         // "10" before "2". The qualified name forces the bigint column.
-        `SELECT messages.seq::text AS seq, messages.message_envelope, messages.display_envelope, messages.reported_usage,
-                messages.turn_duration_ms::text AS turn_duration_ms, messages.author, messages.created_at,
-                turns.status AS turn_status, turns.reason AS turn_reason, turns.reported_usage AS turn_usage,
-                turns.turn_duration_ms::text AS turn_record_duration_ms
-         FROM messages
-         LEFT JOIN cortex_thread_turns turns ON turns.thread_id = messages.thread_id AND turns.start_seq = messages.seq
+        `SELECT ${STORED_ROW_COLUMNS}
+         ${storedRowFrom()}
          WHERE messages.thread_id = $1
          ORDER BY messages.seq ASC`, [threadId]);
-        // Spread rather than `usage: r.reported_usage ?? undefined`, so a row with
-        // no rollup carries no `usage` KEY at all — absent, not present-and-undefined.
-        // The duration and the author obey the same rule, each from its own column.
-        // The creation time is unconditional: its column is NOT NULL, thus it has no
-        // absence to represent.
-        const stored = await Promise.all(rows.map(async (r) => {
-            const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
-            const displayEnvelope = r.display_envelope == null ? undefined : await parseStoredDisplayEnvelope(r.display_envelope, `${threadId}/${r.seq}/display`, logger);
-            const turn = r.turn_status === null
-                ? undefined
-                : {
-                    status: r.turn_status,
-                    ...(r.turn_reason === null ? {} : { reason: r.turn_reason }),
-                    ...(r.turn_usage === null ? {} : { usage: r.turn_usage }),
-                    ...(r.turn_record_duration_ms === null ? {} : { durationMs: Number(r.turn_record_duration_ms) }),
-                };
-            return {
-                seq: Number(r.seq),
-                envelope,
-                message: envelope.message,
-                ...(displayEnvelope ? { displayEnvelope } : {}),
-                ...(r.reported_usage === null ? {} : { usage: r.reported_usage }),
-                ...(r.turn_duration_ms === null ? {} : { durationMs: Number(r.turn_duration_ms) }),
-                ...(turn === undefined ? {} : { turn }),
-                ...(r.author === null ? {} : { author: r.author }),
-                createdAt: r.created_at,
-            };
-        }));
-        return groupTurns(stored, (row) => isGenuineUserStart(row.message));
+        return toTurns(threadId, rows);
+    }
+    async function readPage(threadId, options) {
+        const { rows } = await pool.query(PAGE_SQL, [
+            threadId,
+            options.before === undefined ? null : String(options.before),
+            pageLimit(options.limit),
+        ]);
+        // The cursor rides each row, and an empty page has no row. An empty page has no cursor either:
+        // `page_lower` is set only when its row is in the page.
+        const next = rows[0]?.next_before ?? null;
+        return { turns: await toTurns(threadId, rows), before: next === null ? null : Number(next) };
     }
     function loadAll(threadId) {
         return tryQuery("thread-history.loadAll", () => readTurns(threadId));
     }
+    function loadPage(threadId, options) {
+        return tryQuery("thread-history.loadPage", () => readPage(threadId, options));
+    }
     function retractLastTurn(threadId) {
         return withTransaction(pool, "thread-history.retractLastTurn", (client) => 
         // Take the SAME per-thread advisory lock `appendTurn` takes, and take it
@@ -379,7 +512,7 @@ export function createThreadHistory(pool, logger) {
                     (SELECT MAX(seq)::text FROM messages
                        WHERE thread_id = $1
                          AND ${GENUINE_USER_START_SQL}) AS boundary`, [threadId]);
-            return rows[0];
+            return presentFirst(rows, "the thread boundary row");
         }))
             .andThen(({ has_rows, boundary }) => {
             if (!has_rows)
@@ -424,7 +557,7 @@ export function createThreadHistory(pool, logger) {
         return tryQuery("thread-history.countUserTurnsAfter", () => pool.query(`SELECT COUNT(*)::text AS turns FROM messages
               WHERE thread_id = $1
                 AND seq > $2::bigint
-                AND ${GENUINE_USER_START_SQL}`, [threadId, seq])).map(({ rows }) => Number(rows[0].turns));
+                AND ${GENUINE_USER_START_SQL}`, [threadId, seq])).map(({ rows }) => Number(presentFirst(rows, "the user-turn count row").turns));
     }
-    return { appendTurn, writeTurn, loadRecent, loadAll, retractLastTurn, latestSeq, latestTurnAt, countUserTurnsAfter };
+    return { appendTurn, writeTurn, loadRecent, loadAll, loadPage, retractLastTurn, latestSeq, latestTurnAt, countUserTurnsAfter };
 }