@ably/ai-transport 0.1.0 → 0.3.0

package/dist/core/transport/tree.d.ts

@@ -1,171 +1,585 @@
 import { Logger } from '../../logger.js';
-import { MessageNode, Tree, TurnLifecycleEvent } from './types.js';
+import { CodecEvent, CodecInputEvent, CodecOutputEvent, Reducer } from '../codec/types.js';
+import { ConversationNode, OutputEvent, RunLifecycleEvent, RunNode, Tree } from './types.js';
 /**
- * Tree — materializes a branching conversation from a flat
- * oplog of Ably messages using serial-first ordering.
+ * Tree — materializes a branching conversation as a forest of nodes. Each turn
+ * is two nodes: a user {@link InputNode} keyed by its client-owned
+ * codec-message-id and an agent {@link RunNode} keyed by the agent-minted
+ * run-id, parented to the input node.
  *
- * Serial order (the total order assigned by Ably) is the primary mechanism
- * for linear message sequences. `x-ably-parent` and `x-ably-fork-of` headers
- * are only structurally meaningful at branch points — where the user is
- * interacting with a visible message and the client always has it loaded.
+ * Each node holds a per-node codec {@link TProjection} which the Tree folds
+ * from inbound events. The Tree owns the complete conversation state across
+ * every observed node. The {@link View} walks the parent chain to extract a
+ * flat message list for rendering.
  *
- * `upsert()` is the sole mutation method. Messages can arrive in any order
- * (live subscription, history pages, seed data) and the tree produces the
- * correct `flattenNodes()` output once all messages are present.
+ * `applyMessage()` is the entry point for inbound channel messages — it
+ * classifies a run-less user input into an input node (keyed by
+ * codec-message-id) or routes a run-bearing wire to its reply run (keyed by
+ * run-id), folds events into that node's projection, and maintains a secondary
+ * `codecMessageId -> nodeKey` index. `applyRunLifecycle()` handles run-start /
+ * run-suspend / run-resume / run-end events.
  *
- * The tree owns conversation state. `flattenNodes()` returns the linear node
- * list for the currently selected branches — this is what the transport's
- * `getMessages()` delegates to.
+ * Sibling structure: editing a prompt produces a sibling input node linked by
+ * {@link InputNode.forkOf}; regenerating a reply produces a sibling reply run
+ * sharing the same input-node parent (no fork-of).
  */
 import type * as Ably from 'ably';
-/** Internal tree surface used by View — not part of the public Tree API. */
-export interface TreeInternal<TMessage> extends Tree<TMessage> {
+/**
+ * How long (in ms, on the Ably message-timestamp timeline) a structurally
+ * complete run's event log is retained after the node's last observed
+ * activity. Bounds cross-publisher live delivery reorder: a wire can be
+ * delivered after a higher-serial wire by at most this window. Conservative
+ * placeholder pending confirmation of the actual cross-region bound.
+ */
+export declare const REORDER_WINDOW_MS = 120000;
+/**
+ * The primary key a node is indexed under: a reply run's `runId`, or an input
+ * node's `codecMessageId` (the client owns it before the agent mints a runId).
+ * @param node - The node to key.
+ * @returns The node's primary key.
+ */
+export declare const nodeKey: <TProjection>(node: ConversationNode<TProjection>) => string;
+/** Internal tree surface used by View and ClientSession — not part of the public Tree API. */
+export interface TreeInternal<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection> extends Tree<TOutput, TProjection> {
+    /**
+     * Walk the visible node chain (both input nodes and reply runs) along the
+     * selected branches, in chronological order. The View renders from this.
+     * @param selections - Per-group selected member key, keyed by group root.
+     * @returns The visible nodes in chronological order.
+     */
+    visibleNodes(selections?: Map<string, string>): ConversationNode<TProjection>[];
     /**
-     * Monotonic counter that increments on structural changes (node insert,
-     * delete, serial promotion/reorder) but NOT on content-only updates
-     * (existing node's message replaced). Allows the View to skip full
-     * tree walks when only message content changed.
+     * Get the "group root" key for a sibling group — the stable key the
+     * selection map is keyed by (the earliest edit version for input nodes, the
+     * original reply for a regenerate group).
+     */
+    getGroupRoot(key: string): string;
+    /**
+     * The reply runs parented at an input node (its codec-message-id), in
+     * iteration order. Empty when none have been observed. Used to resolve a
+     * user prompt to its reply run(s).
+     * @param inputCodecMessageId - The input node's codec-message-id.
+     * @returns The reply runs parented at that input.
+     */
+    getReplyRuns(inputCodecMessageId: string): RunNode<TProjection>[];
+    /**
+     * Apply an inbound channel message to the tree.
+     *
+     * Classifies the message and routes it to the owning node:
+     * 1. Run-less user input (no run-id, a `user`-role message carrying a
+     *    codec-message-id and input events): creates or promotes the input node
+     *    keyed by that codec-message-id, folds the input events.
+     * 2. Run-bearing wire (assistant output, continuation tool-resolution, or a
+     *    fresh agent-minted run): routes to the reply run by run-id (reconciling
+     *    an optimistic insert by codec-message-id), folds events.
+     * @param events - Decoded codec events, split by wire direction. Both are
+     *   folded into the node's projection, inputs first.
+     * @param events.inputs - Client-published events (`ai-input` wire).
+     * @param events.outputs - Agent-published events (`ai-output` wire).
+     * @param headers - Transport headers from the inbound Ably message.
+     * @param serial - Ably channel serial; undefined for optimistic inserts.
+     * @param timestamp - Ably server timestamp (epoch ms) of the message —
+     *   top-level `Message.timestamp`, the message's create time on every
+     *   delivery (an append's own receive time lives in `version.timestamp`) —
+     *   or undefined for optimistic inserts. Advances the Tree's event-log
+     *   retention clock and the owning node's last-activity time.
+     * @param version - The delivery's `Message.version.serial`, or undefined
+     *   when the delivery carried none (optimistic inserts, never-mutated
+     *   deliveries from sources that omit it). Guards the node's event log
+     *   against whole-wire replays: a delivery at or below the version already
+     *   decoded into its log entry is dropped.
      */
-    readonly structuralVersion: number;
+    applyMessage(events: {
+        inputs: TInput[];
+        outputs: TOutput[];
+    }, headers: Record<string, string>, serial?: string, timestamp?: number, version?: string): void;
     /**
-     * Flatten the tree along selected branches into a linear node list.
-     * The `selections` map provides the selected sibling's msgId at each
-     * fork point, keyed by group root msgId. Fork points not present in
-     * the map default to the latest sibling. If a selectedMsgId is not
-     * found in the sibling group (stale/deleted), falls back to latest.
+     * Apply a run-lifecycle event.
+     *
+     * - `start`: creates the reply run (if missing) or, for an existing run,
+     *   sets RunNode.state to 'active', promotes startSerial, and backfills
+     *   structural metadata (parent / forkOf / regenerates / invocationId).
+     * - `suspend`: sets RunNode.state to 'suspended' and records `endSerial`.
+     *   The run stays live so a resume under the same `runId` picks up where it
+     *   left off.
+     * - `resume`: re-activates an existing suspended Run (state back to
+     *   'active') without touching its structure or serials — a pure re-entry
+     *   signal. A no-op if the Run is not yet known.
+     * - `end`: sets RunNode.state to the terminal reason and records
+     *   `endSerial`.
+     *
+     * Always emits a 'run' event to subscribers.
+     * @param event - Lifecycle event payload, including the channel serial.
      */
-    flattenNodes(selections: Map<string, string>): MessageNode<TMessage>[];
+    applyRunLifecycle(event: RunLifecycleEvent): void;
     /**
-     * Get the "group root" msgId for a sibling group — the original message
-     * that all forks in the group trace back to.
+     * Get the node keyed by `key`, or undefined if `key` names no node. The
+     * key is a {@link nodeKey} — a runId (reply run) or an input node's
+     * codec-message-id — so the result is a {@link ConversationNode} union:
+     * narrow on `kind` before reading kind-specific fields. Pairs with
+     * {@link getNodeByCodecMessageId}, which resolves an arbitrary owned
+     * codec-message-id (including an assistant message's) to its node.
+     * @param key - The node key to look up.
+     * @returns The node, or undefined if not found.
      */
-    getGroupRoot(msgId: string): string;
+    getNode(key: string): ConversationNode<TProjection> | undefined;
     /**
-     * Get the sibling group that `msgId` belongs to, as full MessageNode objects.
-     * Allows callers to resolve index ↔ msgId without losing identity.
+     * Remove a node from the tree by its key ({@link nodeKey} — a runId or an
+     * input node's codec-message-id). Children become unreachable because their
+     * parent is no longer on the active path.
+     * @param key - The node key to remove.
      */
-    getSiblingNodes(msgId: string): MessageNode<TMessage>[];
+    delete(key: string): void;
     /** Forward a raw Ably message event to tree subscribers. */
     emitAblyMessage(msg: Ably.InboundMessage): void;
-    /** Forward a turn lifecycle event to tree subscribers. */
-    emitTurn(event: TurnLifecycleEvent): void;
-    /** Register an active turn. */
-    trackTurn(turnId: string, clientId: string): void;
-    /** Unregister an active turn. */
-    untrackTurn(turnId: string): void;
 }
-export declare class DefaultTree<TMessage> implements TreeInternal<TMessage> {
-    /** All nodes indexed by msgId (x-ably-msg-id). */
+export declare class DefaultTree<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection> implements TreeInternal<TInput, TOutput, TProjection> {
+    private readonly _codec;
+    private readonly _logger;
+    private readonly _emitter;
+    /**
+     * All nodes indexed by their primary key ({@link nodeKey}): a reply run's
+     * runId, or an input node's codec-message-id.
+     */
     private readonly _nodeIndex;
     /**
-     * All nodes sorted by serial (lexicographic). Null-serial messages
-     * (optimistic inserts, seed data) sort after all serial-bearing messages,
-     * ordered among themselves by insertion sequence.
+     * Maps every observed `codec-message-id` to its owning node's key
+     * ({@link nodeKey}). For a reply run that is the runId of every message the
+     * run published; for an input node it is the input's own codec-message-id.
+     * Resolves fork-of / parent codec-message-ids to node keys, routes
+     * continuation amend wires to existing nodes, and backs UI lookups that hold
+     * a codec-message-id.
      */
-    private readonly _sortedList;
+    private readonly _codecMessageIdToNodeKey;
     /**
-     * Parent index: parentId to set of child msgIds.
-     * Nodes with no parent are indexed under the key `null`.
+     * All nodes sorted by their sort serial ({@link sortSerial}: `startSerial`
+     * for runs, `serial` for input nodes), lexicographically. Nodes with no sort
+     * serial (optimistic) sort after all serial-bearing nodes, ordered among
+     * themselves by insertion sequence.
+     */
+    private readonly _sortedNodes;
+    /**
+     * Parent index: parent node key (the key its children's
+     * `parentCodecMessageId` resolves to) to the set of child node keys. Root
+     * nodes (no parent) are indexed under the key `undefined`. Kind-blind — a
+     * reply run and an input node parent off each other through the same index.
      */
     private readonly _parentIndex;
-    private readonly _emitter;
-    private readonly _logger;
-    /** Active turns: turnId → clientId. */
-    private readonly _turnClientIds;
+    /**
+     * Reverse edge: an input node's codec-message-id to the set of reply-run ids
+     * parented at it. Lets the View resolve a user prompt to its (selected) reply
+     * run, and groups regenerate siblings (which all parent at the same input
+     * node).
+     */
+    private readonly _replyRunsByInput;
     /** Monotonically increasing counter for insertion sequence. */
     private _seqCounter;
-    /** Incremented on structural changes; unchanged on content-only updates. */
+    /** Incremented on structural changes; unchanged on projection-only updates. */
     private _structuralVersion;
-    get structuralVersion(): number;
-    constructor(logger: Logger);
     /**
-     * Compare two nodes for sorted list ordering.
-     * Serial-bearing nodes sort by serial (lexicographic).
-     * Null-serial nodes sort after all serial-bearing nodes.
-     * Among null-serial nodes, sort by insertion sequence.
+     * Cached sibling-group lookups keyed by node key. The walk over forkOf
+     * chains and the per-parent fan-out are pure functions of the node
+     * graph, so the cache is keyed against {@link _structuralVersion}:
+     * any topology mutation drops the cache and the next lookup
+     * recomputes. Hits matter most during a single render pass where
+     * the View calls `getSiblingNodes` once per visible node plus extra
+     * per-message branch-anchor probes from React components.
+     */
+    private _siblingCache;
+    private _siblingCacheVersion;
+    /**
+     * Index from `event-id` header to the raw Ably message that carried it.
+     * Populated incrementally as messages arrive via {@link emitAblyMessage};
+     * reads back the raw message for the agent's input-event lookup
+     * ({@link findAblyMessageByEventId}). Bounded by the Tree's lifetime — cleared
+     * when the Tree is replaced on continuity loss / session close.
+     */
+    private readonly _eventIdIndex;
+    /**
+     * Event-log retention logical clock: the max Ably message timestamp (epoch
+     * ms) observed across every apply, 0 until the first timestamped one. Only
+     * ever advances — older-page history application carries smaller timestamps
+     * and leaves it (and therefore the sweep) untouched.
+     */
+    private _clock;
+    /**
+     * Keys of structurally complete run nodes (run-start and run-end both
+     * observed) whose event logs await the retention window, in completion
+     * order. Drained from the front whenever {@link _clock} advances; sweeping
+     * only at clock advances keeps a history page's batch atomic — applying an
+     * older page can never advance the clock, so a node cannot be swept between
+     * its run-start and the rest of its wires in the same page.
+     */
+    private readonly _sweepQueue;
+    constructor(codec: Reducer<CodecEvent<TInput, TOutput>, TProjection>, logger: Logger);
+    /**
+     * Compare two nodes (Run or input) for sorted list ordering.
+     * Serial-bearing nodes sort by their sort serial (`startSerial` for runs,
+     * `serial` for input nodes), lexicographically.
+     * Nodes with no sort serial sort after all serial-bearing nodes.
+     * Among them, sort by insertion sequence.
+     *
+     * Optimistic (null-serial) nodes intentionally tail-sort so they reorder
+     * into place when the server relay arrives and `applyMessage` promotes
+     * startSerial — see {@link applyMessage}'s `_removeSortedNode` /
+     * `_insertSortedNode` pair on the promotion path.
      * @param a - First node to compare.
      * @param b - Second node to compare.
      * @returns Negative if a sorts before b, positive if after, zero if equal.
      */
     private _compareNodes;
     /**
-     * Insert a node into sortedList at the correct position via binary search.
+     * Insert a node into the sorted list at the correct position via binary search.
      * @param internal - The node to insert.
      */
-    private _insertSorted;
+    private _insertSortedNode;
     /**
-     * Remove a node from sortedList.
+     * Remove a node from the sorted list.
      * @param internal - The node to remove.
      */
-    private _removeSorted;
+    private _removeSortedNode;
+    /**
+     * Insert a freshly-created node into the primary store, the parent index, and
+     * the sorted list, then bump the structural version. Kind-specific secondary
+     * indexing — the codec-message-id map for input nodes, the reply→input edge
+     * for reply runs — is the caller's responsibility.
+     * @param key - The node's primary key ({@link nodeKey}).
+     * @param entry - The internal node to insert.
+     * @param parentCodecMessageId - The node's structural parent, or undefined for a root.
+     */
+    private _insertNode;
+    /**
+     * Re-sort a node whose sort key just changed and bump the structural version.
+     * The caller mutates the serial field (`serial` for input nodes, `startSerial`
+     * for runs); this keeps the sorted list and version in step. Used on the
+     * optimistic-serial promotion paths when the server relay/echo arrives.
+     * @param entry - The internal node whose serial was just promoted.
+     */
+    private _promoteSerial;
+    /**
+     * Fold a batch of events into a node's projection in place, isolating each
+     * fold in a try/catch so a throwing reducer can't abort the rest of the batch
+     * or the surrounding apply.
+     * @param entry - The internal node whose projection is folded in place.
+     * @param events - The decoded events to fold, in wire order.
+     * @param serial - Ably channel serial; coerced to '' for an optimistic insert.
+     * @param messageId - The reducer routing key (codec-message-id), or undefined.
+     */
+    private _foldInto;
+    /**
+     * Record a serial-bearing wire in the node's event log and fold it. Events
+     * extending the log tail (the common case — in-order live delivery) fold
+     * incrementally onto the existing projection, identical to a bare
+     * {@link _foldInto}. Events that land earlier in the log (an earlier-serial
+     * wire delivered late — cross-publisher reorder, or a history page applying
+     * an older message after a newer one) cannot be folded incrementally without
+     * corrupting serial order, so the node is refolded from the whole log via
+     * {@link _refold}.
+     *
+     * Optimistic (serial-less) applies and empty event batches are not logged;
+     * an optimistic seed folds into the projection but never into the log, and
+     * marks the node `optimistic`. The first serial-bearing wire (the echo of
+     * the optimistic input, which re-delivers the seeded content) refolds the
+     * node from the log alone — rebuilding the projection without the seed
+     * rather than folding the echo on top of it. The codec therefore never sees
+     * the seed and its echo in one projection, and needs no seed-replacement
+     * logic. The seed must be a faithful preview of the echo, since the echo's
+     * content is what survives.
+     *
+     * Whole-wire replays are dropped at the log: each entry records the highest
+     * `Message.version.serial` decoded into it (`decodedThrough`), so a
+     * version-bearing delivery the entry has already incorporated — a second
+     * hydration over a populated Tree, a remounted View's re-fetch, an agent
+     * re-walk — records nothing and folds nothing. A newer version of a
+     * discrete wire (an edited discrete) is likewise dropped; propagating edits
+     * into projections is deliberately out of scope.
+     * @param entry - The internal node whose log and projection are updated.
+     * @param events - The decoded events to fold, in wire order.
+     * @param serial - Ably channel serial; undefined for an optimistic insert.
+     * @param messageId - The reducer routing key (codec-message-id), or undefined.
+     * @param version - The delivery's `Message.version.serial`, or undefined.
+     * @param streamed - Whether the delivery is part of a streamed wire.
+     */
+    private _recordAndFold;
+    /**
+     * Rebuild a node's projection from its event log in canonical serial order:
+     * a fresh {@link Reducer.init} folded through every logged event, each with
+     * its own wire's serial and messageId. Used when a late, earlier-serial wire
+     * makes incremental folding unsound. Reducer purity (a fold is a function of
+     * its inputs alone) is what makes the rebuild faithful; the per-fold
+     * try/catch mirrors {@link _foldInto} so one throwing event can't abort the
+     * rebuild.
+     *
+     * Rebuilds the projection only; the surrounding apply emits its usual
+     * `output` event carrying just the triggering wire's events. Consumers read
+     * the rebuilt state from `node.projection` (the View recomputes its message
+     * list from it), so on the refold path the event's `events` payload is not a
+     * delta of the full projection change.
+     * @param entry - The internal node whose projection is rebuilt in place.
+     */
+    private _refold;
+    /**
+     * Record activity on a node and advance the retention clock. Updates the
+     * node's `lastActivityTs` and the Tree-wide `_clock` to the given timestamp
+     * when it is newer; a clock advance drains the sweep queue. `undefined`
+     * (an optimistic local apply) advances nothing.
+     * @param entry - The node the activity belongs to.
+     * @param timestamp - Ably message timestamp (epoch ms), or undefined.
+     */
+    private _recordActivity;
+    /**
+     * Queue a run node's event log for retention sweeping once the node is
+     * structurally complete: its run-start (serial floor — no older history page
+     * can add to it) and its run-end (no further agent output) have both been
+     * observed. The actual drop happens in {@link _drainSweepQueue} once the
+     * reorder window has also lapsed. No-op for input nodes (never swept — no
+     * floor marker, and their logs are bounded by one user message), for nodes
+     * already queued or swept, and while either marker is missing.
+     * @param entry - The node to consider for sweeping.
+     */
+    private _maybeQueueSweep;
+    /**
+     * Drop the event logs of queued nodes whose retention window has lapsed:
+     * `lastActivityTs + REORDER_WINDOW_MS < _clock`. Drains from the front and
+     * stops at the first node still inside the window — completion order is
+     * time-ordered for live traffic, so this is amortised O(1) per apply, and
+     * stopping early only ever over-retains (memory, never correctness). Called
+     * only when the clock advances, so applying an older history page (smaller
+     * timestamps) can never sweep mid-batch. Deleted nodes are skipped.
+     */
+    private _drainSweepQueue;
     private _addToParentIndex;
     private _removeFromParentIndex;
     /**
-     * Get the sibling group that `msgId` belongs to.
+     * Resolve a node's structural parent to the parent node's key
+     * ({@link nodeKey}), or undefined for a root. The parent is named by a
+     * codec-message-id (`parentCodecMessageId`); this maps it through the
+     * codec-message-id index to the owning node's key (a runId for a reply run,
+     * a codec-message-id for an input node). Returns undefined when the parent
+     * hasn't been observed yet (the node is treated as a root until it arrives).
+     * @param node - The node whose parent to resolve.
+     * @returns The parent node's key, or undefined.
+     */
+    private _parentKeyOf;
+    /**
+     * Walk an input node's `forkOf` chain to the group root — the earliest edit
+     * version sharing the same structural parent. Stops at a missing target, a
+     * non-input target, a parent mismatch, or a cycle.
+     * @param node - The input node to walk from.
+     * @returns The group-root input node (the node itself when it is the root).
+     */
+    private _inputGroupRoot;
+    /**
+     * Get the sibling group that the node keyed by `key` belongs to. Kind-split:
+     *
+     * - **Reply runs** — every reply run sharing the same input-node parent is a
+     *   sibling (the original reply + its regenerators all parent at the same
+     *   input node M_user). No fork-of involved.
+     * - **Input nodes** — edit versions: nodes sharing a parent AND linked by a
+     *   `forkOf` chain to the group root.
      *
-     * A sibling group is: the original message + all messages whose `forkOf`
-     * points to the original (or transitively to a sibling). We find the
-     * group root by following `forkOf` chains to the earliest ancestor that
-     * has no `forkOf` (or whose `forkOf` target doesn't share the same parent).
-     * @param msgId - The msg-id to look up the sibling group for.
+     * Returned ordered by startSerial (original/oldest first). A group of one is
+     * returned as a single-element array (no branching).
+     * @param key - The node key ({@link nodeKey}) to look up the group for.
      * @returns The ordered list of sibling nodes.
      */
     private _getSiblingGroup;
     /**
-     * Check if `node` belongs to the sibling group rooted at `originalId`.
-     * A node is a sibling if it IS the original or its forkOf chain leads
-     * to the original (with the same parentId).
-     * @param node - The node to check.
-     * @param originalId - The group root to match against.
-     * @returns True if the node belongs to the sibling group.
+     * Whether `node` belongs to the sibling group anchored at `original`.
+     * Requires the same kind and the same structural parent; reply runs need
+     * nothing more (same-parent runs are regenerate siblings), input nodes must
+     * additionally be forkOf-linked to the original (edit versions).
+     * @param node - The candidate node.
+     * @param original - The group's anchor node.
+     * @returns True if `node` is a sibling of `original`.
      */
     private _isSiblingOf;
     /**
-     * Get the "group root" msgId for a sibling group — the original message
-     * that all forks trace back to.
-     * @param msgId - Any msg-id in the sibling group.
-     * @returns The msg-id of the group root.
-     */
-    getGroupRoot(msgId: string): string;
-    flattenNodes(selections: Map<string, string>): MessageNode<TMessage>[];
-    getSiblings(msgId: string): TMessage[];
-    getSiblingNodes(msgId: string): MessageNode<TMessage>[];
-    hasSiblings(msgId: string): boolean;
-    getNode(msgId: string): MessageNode<TMessage> | undefined;
-    getHeaders(msgId: string): Record<string, string> | undefined;
-    upsert(msgId: string, message: TMessage, headers: Record<string, string>, serial?: string): void;
-    delete(msgId: string): void;
-    getActiveTurnIds(): Map<string, Set<string>>;
-    on(event: 'update', handler: () => void): () => void;
-    on(event: 'ably-message', handler: (msg: Ably.InboundMessage) => void): () => void;
-    on(event: 'turn', handler: (event: TurnLifecycleEvent) => void): () => void;
+     * Get the "group root" key for a sibling group — the stable key the
+     * selection map is keyed by. For an input node (edit versions) that is the
+     * earliest fork-of ancestor; for a reply run (regenerate group) it is the
+     * oldest same-parent run (the original reply).
+     * @param key - Any node key in the sibling group.
+     * @returns The group root's key.
+     */
+    getGroupRoot(key: string): string;
     /**
-     * Forward a raw Ably message event to tree subscribers.
-     * @param msg - The raw Ably message to emit.
+     * Walk the visible node chain along the selected branches, kind-blind. An
+     * input node and a reply run reach each other through the same
+     * parent-membership check, so seed-only user→user chains and the
+     * input→reply→input weave both resolve here. Sibling groups (edit versions /
+     * regenerate runs) collapse to the selected member.
+     * @param selections - Per-group selected member key, keyed by group root.
+     * @returns The visible nodes (both kinds) in chronological order.
      */
-    emitAblyMessage(msg: Ably.InboundMessage): void;
+    visibleNodes(selections?: Map<string, string>): ConversationNode<TProjection>[];
+    getRunNode(runId: string): RunNode<TProjection> | undefined;
+    getNode(key: string): ConversationNode<TProjection> | undefined;
+    getNodeByCodecMessageId(codecMessageId: string): ConversationNode<TProjection> | undefined;
+    getReplyRuns(inputCodecMessageId: string): RunNode<TProjection>[];
+    getSiblingNodes(key: string): ConversationNode<TProjection>[];
+    applyMessage(events: {
+        inputs: TInput[];
+        outputs: TOutput[];
+    }, headers: Record<string, string>, serial?: string, timestamp?: number, version?: string): void;
+    /**
+     * Apply a run-less user input wire: create (or promote the serial of) the
+     * input node keyed by its codec-message-id, fold the input events into its
+     * own projection, and emit an `output` event (with empty outputs — input
+     * folds carry none) so the View observes the optimistic insert.
+     * @param codecMessageId - The input node's codec-message-id (its primary key).
+     * @param headers - Transport headers from the inbound Ably message.
+     * @param serial - Ably channel serial; undefined for an optimistic insert.
+     * @param timestamp - Ably server timestamp (epoch ms); undefined for an optimistic insert.
+     * @param version - The delivery's `Message.version.serial`, or undefined.
+     * @param all - The direction-tagged input events to fold, in wire order.
+     */
+    private _applyInputMessage;
+    /**
+     * Apply a reply-run wire (assistant output, continuation tool-resolution, or
+     * a fresh run keyed by the agent-minted run-id): create or reconcile the run
+     * node, fold its events, maintain the codec-message-id and reply→input
+     * indices, and emit the `output` event. Derives the codec-message-id,
+     * triggering-input id, fold list, and outputs from `events`/`headers`,
+     * mirroring `applyMessage`.
+     * @param wireRunId - The run-id from the inbound wire (the node's primary key).
+     * @param events - The decoded inputs and outputs from the wire.
+     * @param events.inputs - Client-published events (`ai-input` wire).
+     * @param events.outputs - Agent-published events (`ai-output` wire).
+     * @param headers - Transport headers from the inbound Ably message.
+     * @param serial - Ably channel serial; undefined for an optimistic insert.
+     * @param timestamp - Ably server timestamp (epoch ms); undefined for an optimistic insert.
+     * @param version - The delivery's `Message.version.serial`, or undefined.
+     */
+    private _applyRunMessage;
     /**
-     * Forward a turn lifecycle event to tree subscribers.
-     * @param event - The turn lifecycle event to emit.
+     * Record a reply run against its input-node parent (the reverse edge powering
+     * `getReplyRuns` and regenerate sibling grouping). A reply run's
+     * `parentCodecMessageId` is its input node's codec-message-id (the master
+     * invariant), so no resolution is needed.
+     * @param node - The reply run node.
+     * @param runId - The run's id.
      */
-    emitTurn(event: TurnLifecycleEvent): void;
+    private _indexReplyRun;
+    applyRunLifecycle(event: RunLifecycleEvent): void;
     /**
-     * Register an active turn.
-     * @param turnId - The turn's unique identifier.
-     * @param clientId - The client that owns the turn.
+     * Apply a run-start lifecycle event's structural effect: create the reply
+     * run if it doesn't exist yet, or backfill an optimistic / wire-created
+     * node's structure and metadata from the canonical run-start. Mutates
+     * `_structuralVersion` when the tree shape changes; the caller owns the
+     * `run`/`update` emits.
+     * @param event - The run-start lifecycle event.
      */
-    trackTurn(turnId: string, clientId: string): void;
+    private _applyRunStart;
     /**
-     * Unregister an active turn.
-     * @param turnId - The turn to untrack.
+     * Apply a run-suspend lifecycle event: pause the run without ending it —
+     * mark the node 'suspended' and record the serial it paused at, but keep the
+     * Run live so a resume under the same runId resumes it. Status/endSerial are
+     * content, not structure, so this never mutates `_structuralVersion`; the
+     * caller owns the emits.
+     * @param event - The run-suspend lifecycle event.
      */
-    untrackTurn(turnId: string): void;
+    private _applyRunSuspend;
+    /**
+     * Apply a run-resume lifecycle event: re-enter an already-started run by
+     * flipping a suspended run back to 'active'. Pure re-entry — it carries no
+     * parent/forkOf and does not promote startSerial (the original run-start owns
+     * the run's structure). Only a suspended run resumes: a no-op when the run
+     * isn't known (e.g. a resume replayed from a newer history page before its
+     * run-start) and a no-op for an already-active or terminal
+     * (complete/cancelled/error) run — a stray resume must never resurrect a run
+     * that has ended. The caller owns the emits.
+     * @param event - The run-resume lifecycle event.
+     */
+    private _applyRunResume;
+    /**
+     * Apply a run-end lifecycle event: record the terminal reason (and, for an
+     * error end, the error) as the node's state, plus the serial it ended at.
+     * State/endSerial are content, not structure, so this never mutates
+     * `_structuralVersion`; the caller owns the emits.
+     *
+     * A run-end for an unknown runId is a no-op: nothing else is known about the
+     * run yet, so there is no node to mark. When that happens during history
+     * replay (a page boundary falling just before the run-end, so the run's
+     * other wires arrive in later pages), the run is never marked terminal and
+     * its event log is retained for the Tree's lifetime — over-retention, never
+     * corruption.
+     * @param event - The run-end lifecycle event.
+     */
+    private _applyRunEnd;
+    delete(key: string): void;
+    /**
+     * Build a fresh RunNode from a wire message's headers. Used when an
+     * inbound message arrives before any run-start event for its runId.
+     * @param runId - The run-id from the inbound wire.
+     * @param headers - Transport headers from the inbound Ably message.
+     * @param serial - Ably channel serial; undefined for optimistic inserts.
+     * @returns A newly-allocated internal run node ready for insertion.
+     */
+    private _createRunFromHeaders;
+    /**
+     * Wrap a freshly-built conversation node in its internal envelope — sort
+     * sequence, event log, and retention/promotion state. The single home for
+     * those per-node fields, so a new field is added in one place rather than at
+     * every node-construction site.
+     * @param node - The conversation node to wrap.
+     * @param runStartSeen - Whether the run's ai-run-start has been observed
+     *   (run nodes only; always false for input nodes).
+     * @returns A newly-allocated internal node ready for insertion.
+     */
+    private _wrapNode;
+    /**
+     * Allocate a RunNode from already-resolved fields. Shared by the
+     * header-driven and lifecycle-driven run creators: both build the identical
+     * RunNode literal and stamp an insert sequence.
+     * @param params - The resolved run fields.
+     * @param params.runId - The run's id (its primary key).
+     * @param params.parentCodecMessageId - Structural parent codec-message-id, or undefined for a root.
+     * @param params.forkOf - The resolved fork target's node key (already mapped through the codec-message-id index), or undefined.
+     * @param params.regeneratesCodecMessageId - The codec-message-id this run regenerates, or undefined.
+     * @param params.clientId - The publishing client's id.
+     * @param params.invocationId - The agent invocation id.
+     * @param params.startSerial - Ably channel serial; undefined for optimistic inserts.
+     * @param params.runStartSeen - Whether the run's ai-run-start has been observed (true only for lifecycle-created runs).
+     * @returns A newly-allocated internal run node ready for insertion.
+     */
+    private _buildRunNode;
+    /**
+     * Build a fresh InputNode from a run-less user input wire's headers.
+     * @param codecMessageId - The input's codec-message-id (its primary key).
+     * @param headers - Transport headers from the inbound Ably message.
+     * @param serial - Ably channel serial; undefined for optimistic inserts.
+     * @returns A newly-allocated internal input node ready for insertion.
+     */
+    private _createInputNodeFromHeaders;
+    /**
+     * Build a fresh RunNode from a run-start lifecycle event. Used when a
+     * run-start event arrives before any message for its runId.
+     * @param event - The run-start lifecycle event from the agent, including
+     *   its channel serial.
+     * @returns A newly-allocated internal run node ready for insertion.
+     */
+    private _createRunFromLifecycle;
+    on(event: 'update', handler: () => void): () => void;
+    on(event: 'ably-message', handler: (msg: Ably.InboundMessage) => void): () => void;
+    on(event: 'run', handler: (event: RunLifecycleEvent) => void): () => void;
+    on(event: 'output', handler: (event: OutputEvent<TOutput>) => void): () => void;
+    /**
+     * Forward a raw Ably message event to tree subscribers. Also indexes the
+     * Ably message by `event-id` header (if present) for
+     * {@link findAblyMessageByEventId} lookups.
+     * @param msg - The raw Ably message to emit.
+     */
+    emitAblyMessage(msg: Ably.InboundMessage): void;
+    findAblyMessageByEventId(eventId: string): Ably.InboundMessage | undefined;
 }
 /**
- * Create a Tree that materializes branching history from a flat oplog.
+ * Create a Tree that materializes branching conversation history from a flat
+ * oplog of Ably messages as a two-node-per-turn forest (input node + reply run).
+ * @param codec - Codec used to fold inbound events into per-Run projections.
  * @param logger - Logger for diagnostic output.
- * @returns A new {@link DefaultTree} instance. The transport uses DefaultTree
- *   directly for internal methods (emitAblyMessage, emitTurn, trackTurn, untrackTurn).
- *   Public consumers see the narrower {@link Tree} interface.
+ * @returns A new {@link DefaultTree} instance. The session uses DefaultTree
+ *   directly for internal methods (applyMessage, applyRunLifecycle,
+ *   emitAblyMessage). Public consumers see the narrower {@link Tree} interface.
  */
-export declare const createTree: <TMessage>(logger: Logger) => DefaultTree<TMessage>;
+export declare const createTree: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection>(codec: Reducer<CodecEvent<TInput, TOutput>, TProjection>, logger: Logger) => DefaultTree<TInput, TOutput, TProjection>;