@ably/ai-transport 0.0.1 → 0.1.0

package/src/core/transport/client-transport.ts

@@ -1,7 +1,7 @@
 /**
  * Core client-side transport, parameterized by codec.
  *
- * Composes StreamRouter and ConversationTree to handle the full client-side
+ * Composes StreamRouter and Tree to handle the full client-side
  * lifecycle. Subscribes to the Ably channel on construction. The same
  * subscription, decoder, and channel are reused across turns.
  *
@@ -16,13 +16,14 @@ import {
   EVENT_CANCEL,
   EVENT_TURN_END,
   EVENT_TURN_START,
+  HEADER_AMEND,
   HEADER_CANCEL_ALL,
   HEADER_CANCEL_CLIENT_ID,
   HEADER_CANCEL_OWN,
   HEADER_CANCEL_TURN_ID,
+  HEADER_FORK_OF,
   HEADER_MSG_ID,
   HEADER_PARENT,
-  HEADER_ROLE,
   HEADER_TURN_CLIENT_ID,
   HEADER_TURN_ID,
   HEADER_TURN_REASON,
@@ -33,25 +34,26 @@ import type { Logger } from '../../logger.js';
 import { LogLevel, makeLogger } from '../../logger.js';
 import { getHeaders } from '../../utils.js';
 import type { DecoderOutput, MessageAccumulator, StreamDecoder } from '../codec/types.js';
-import { createConversationTree } from './conversation-tree.js';
-import { decodeHistory } from './decode-history.js';
 import { buildTransportHeaders } from './headers.js';
 import type { StreamRouter } from './stream-router.js';
 import { createStreamRouter } from './stream-router.js';
+import type { DefaultTree } from './tree.js';
+import { createTree } from './tree.js';
 import type {
   ActiveTurn,
   CancelFilter,
   ClientTransport,
   ClientTransportOptions,
   CloseOptions,
-  ConversationTree,
-  LoadHistoryOptions,
-  MessageWithHeaders,
-  PaginatedMessages,
+  EventsNode,
+  MessageNode,
   SendOptions,
+  Tree,
   TurnEndReason,
   TurnLifecycleEvent,
+  View,
 } from './types.js';
+import { createView, type DefaultView } from './view.js';
 
 /**
  * Returned from `on()` when the transport is already closed — the subscription
@@ -60,15 +62,21 @@ import type {
 // eslint-disable-next-line @typescript-eslint/no-empty-function -- intentional no-op
 const noopUnsubscribe = (): void => {};
 
+// ---------------------------------------------------------------------------
+// Internal state machine
+// ---------------------------------------------------------------------------
+
+enum ClientTransportState {
+  READY = 'ready',
+  CLOSED = 'closed',
+}
+
 // ---------------------------------------------------------------------------
 // Event map for the transport's typed EventEmitter
 // ---------------------------------------------------------------------------
 
 interface ClientTransportEventsMap {
-  message: undefined;
-  turn: TurnLifecycleEvent;
   error: Ably.ErrorInfo;
-  'ably-message': undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -97,15 +105,13 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
   private readonly _fetchFn: typeof globalThis.fetch;
   private readonly _logger: Logger;
 
-  // Typed event emitter for all transport events
+  // Typed event emitter — only 'error' remains on the transport
   private readonly _emitter: EventEmitter<ClientTransportEventsMap>;
 
   // Relay detection — tracks msg-ids of optimistic inserts for reconciliation
   private readonly _ownMsgIds = new Set<string>();
   private readonly _ownTurnIds = new Set<string>();
 
-  // Track clientId per turn for getActiveTurnIds()
-  private readonly _turnClientIds = new Map<string, string>();
   // Track msgIds per turn for cleanup on turn-end
   private readonly _turnMsgIds = new Map<string, Set<string>>();
 
@@ -113,29 +119,40 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
   // A single .delete(turnId) cleans up all three.
   private readonly _turnObservers = new Map<string, TurnObserverState<TEvent, TMessage>>();
 
-  // Raw Ably message log
-  private readonly _ablyMessages: Ably.InboundMessage[] = [];
-
-  // History pagination: withheld messages hidden from getMessages()
-  private readonly _withheldKeys = new Set<string>();
+  // Callbacks to resolve pending waitForTurn promises on close, preventing leaked subscriptions.
+  private readonly _closeResolvers: (() => void)[] = [];
 
   // Sub-components
-  private readonly _tree: ConversationTree<TMessage>;
+  private readonly _tree: DefaultTree<TMessage>;
+  private readonly _view: DefaultView<TEvent, TMessage>;
+  private readonly _views = new Set<DefaultView<TEvent, TMessage>>();
   private readonly _router: StreamRouter<TEvent>;
   private readonly _decoder: StreamDecoder<TEvent, TMessage>;
 
+  // Spec: AIT-CT10, AIT-CT10a
+  readonly tree: Tree<TMessage>;
+  readonly view: View<TEvent, TMessage>;
+
   // Channel subscription — subscribe() returns a Promise that resolves when the channel attaches
   private readonly _attachPromise: Promise<unknown>;
   private readonly _onMessage: (msg: Ably.InboundMessage) => void;
 
-  private _closed = false;
+  private _state = ClientTransportState.READY;
+  private _hasAttachedOnce: boolean;
+  private readonly _onChannelStateChange: Ably.channelEventCallback;
+
+  // Events staged locally via stageEvents(). Flushed into the eventNodes
+  // parameter of _internalSend on the next send operation.
+  private _pendingLocalEvents: EventsNode<TEvent>[] = [];
 
   constructor(options: ClientTransportOptions<TEvent, TMessage>) {
     this._channel = options.channel;
     this._codec = options.codec;
     this._clientId = options.clientId;
-    this._api = options.api ?? '/api/chat';
+    this._api = options.api;
     this._credentials = options.credentials;
+    // CAST: TS can't narrow options.headers/body inside a closure because the outer
+    // object is mutable. The truthiness check on the preceding line guarantees non-nullish.
     this._headersFn =
       typeof options.headers === 'function'
         ? options.headers
@@ -154,23 +171,37 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
     });
 
     this._emitter = new EventEmitter<ClientTransportEventsMap>(this._logger);
+    this._hasAttachedOnce = this._channel.state === 'attached';
 
     // Compose sub-components
-    this._tree = createConversationTree<TMessage>(this._codec.getMessageKey.bind(this._codec), this._logger);
+    this._tree = createTree<TMessage>(this._logger);
+    this._view = createView<TEvent, TMessage>({
+      tree: this._tree,
+      channel: this._channel,
+      codec: this._codec,
+      sendDelegate: this._internalSend.bind(this),
+      logger: this._logger,
+      onClose: () => this._views.delete(this._view),
+    });
     this._router = createStreamRouter<TEvent>(this._codec.isTerminal.bind(this._codec), this._logger);
     this._decoder = this._codec.createDecoder();
 
-    // Seed tree with initial messages
+    this._views.add(this._view);
+
+    // Public accessors (typed as narrow interfaces)
+    this.tree = this._tree;
+    this.view = this._view;
+
+    // Seed tree with initial messages — transport assigns its own msgId
     if (options.messages) {
       let prevMsgId: string | undefined;
       for (const msg of options.messages) {
-        const msgId = this._codec.getMessageKey(msg);
-        const seedHeaders: Record<string, string> = {};
+        const msgId = crypto.randomUUID();
+        const seedHeaders: Record<string, string> = { [HEADER_MSG_ID]: msgId };
         if (prevMsgId) seedHeaders[HEADER_PARENT] = prevMsgId;
         this._tree.upsert(msgId, msg, seedHeaders);
         prevMsgId = msgId;
       }
-      this._emitter.emit('message');
     }
 
     // Spec: AIT-CT2
@@ -179,6 +210,15 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
       this._handleMessage(ablyMessage);
     };
     this._attachPromise = this._channel.subscribe(this._onMessage);
+
+    // Listen for channel state changes that break message continuity.
+    // _hasAttachedOnce is seeded from the channel's current state so that
+    // pre-attached channels are handled correctly. It distinguishes the
+    // initial attach (expected) from a genuine discontinuity.
+    this._onChannelStateChange = (stateChange: Ably.ChannelStateChange) => {
+      this._handleChannelStateChange(stateChange);
+    };
+    this._channel.on(this._onChannelStateChange);
   }
 
   // ---------------------------------------------------------------------------
@@ -186,10 +226,7 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
   // ---------------------------------------------------------------------------
 
   private _handleMessage(ablyMessage: Ably.InboundMessage): void {
-    if (this._closed) return;
-
-    this._ablyMessages.push(ablyMessage);
-    this._emitter.emit('ably-message');
+    if (this._state === ClientTransportState.CLOSED) return;
 
     try {
       // Spec: AIT-CT16a
@@ -199,9 +236,18 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
         const turnId = headers[HEADER_TURN_ID];
         const turnCid = headers[HEADER_TURN_CLIENT_ID] ?? '';
         if (turnId) {
-          this._turnClientIds.set(turnId, turnCid);
-          this._emitter.emit('turn', { type: EVENT_TURN_START, turnId, clientId: turnCid });
+          this._tree.trackTurn(turnId, turnCid);
+          const parentRaw = headers[HEADER_PARENT];
+          const forkOf = headers[HEADER_FORK_OF];
+          this._tree.emitTurn({
+            type: EVENT_TURN_START,
+            turnId,
+            clientId: turnCid,
+            ...(parentRaw !== undefined && { parent: parentRaw }),
+            ...(forkOf !== undefined && { forkOf }),
+          });
         }
+        this._tree.emitAblyMessage(ablyMessage);
         return;
       }
 
@@ -214,7 +260,7 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
         if (turnId) {
           this._router.closeStream(turnId);
           this._turnObservers.delete(turnId);
-          this._turnClientIds.delete(turnId);
+          this._tree.untrackTurn(turnId);
           // Clean up per-turn relay-detection state
           const msgIds = this._turnMsgIds.get(turnId);
           if (msgIds) {
@@ -222,8 +268,9 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
             this._turnMsgIds.delete(turnId);
           }
           this._ownTurnIds.delete(turnId);
-          this._emitter.emit('turn', { type: EVENT_TURN_END, turnId, clientId: turnCid, reason });
+          this._tree.emitTurn({ type: EVENT_TURN_END, turnId, clientId: turnCid, reason });
         }
+        this._tree.emitAblyMessage(ablyMessage);
         return;
       }
 
@@ -232,6 +279,18 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
       const headers = getHeaders(ablyMessage);
       const serial = ablyMessage.serial;
 
+      // Cross-turn events target an existing message from a prior turn,
+      // bypassing the current turn's accumulator.
+      const amendTarget = headers[HEADER_AMEND];
+      if (amendTarget) {
+        for (const output of outputs) {
+          if (output.kind === 'event') {
+            this._handleAmendmentEvent(amendTarget, output);
+          }
+        }
+        return;
+      }
+
       // Always update observer headers, even when the decoder produces no outputs.
       // This ensures header transitions (e.g. x-ably-status: streaming → aborted)
       // are captured for events that the decoder suppresses (AIT-CD8: aborted
@@ -248,6 +307,11 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
           this._handleEventOutput(output, headers);
         }
       }
+
+      // Emit ably-message AFTER decode/upsert so that View subscribers can
+      // find the node in _lastVisibleIds (which is refreshed by tree 'update'
+      // events triggered during upsert).
+      this._tree.emitAblyMessage(ablyMessage);
     } catch (error) {
       const cause = error instanceof Ably.ErrorInfo ? error : undefined;
       this._emitter.emit(
@@ -319,6 +383,79 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
     if (this._codec.isTerminal(event)) this._turnObservers.delete(turnId);
   }
 
+  /**
+   * Handle a cross-turn event targeting an existing message from a prior turn.
+   * Creates a temporary accumulator, seeds it with the existing message,
+   * processes the event, and upserts the updated message into the tree.
+   * @param targetMsgId - The x-ably-msg-id of the message to update.
+   * @param output - The decoded event output to apply.
+   */
+  private _handleAmendmentEvent(targetMsgId: string, output: DecoderOutput<TEvent, TMessage>): void {
+    this._logger.trace('ClientTransport._handleAmendmentEvent();', { targetMsgId });
+
+    const existingNode = this._tree.getNode(targetMsgId);
+    if (!existingNode) {
+      this._logger.debug('ClientTransport._handleAmendmentEvent(); target not found, dropping', { targetMsgId });
+      return;
+    }
+
+    const accumulator = this._codec.createAccumulator();
+    accumulator.initMessage(targetMsgId, existingNode.message);
+    accumulator.processOutputs([output]);
+
+    const updatedMsg = accumulator.messages.at(-1);
+    if (updatedMsg) {
+      this._tree.upsert(targetMsgId, updatedMsg, existingNode.headers, existingNode.serial);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Channel state change handler
+  // ---------------------------------------------------------------------------
+
+  // Spec: AIT-CT19, AIT-CT19a
+  private _handleChannelStateChange(stateChange: Ably.ChannelStateChange): void {
+    if (this._state === ClientTransportState.CLOSED) return;
+
+    const { current, resumed } = stateChange;
+
+    // Track the initial attach so we don't treat it as a discontinuity
+    if (current === 'attached' && !this._hasAttachedOnce) {
+      this._hasAttachedOnce = true;
+      return;
+    }
+
+    // Continuity-breaking states:
+    // - FAILED, SUSPENDED, DETACHED: no more messages expected (or gap)
+    // - ATTACHED with resumed: false (UPDATE): messages were lost
+    const continuityLost =
+      current === 'failed' || current === 'suspended' || current === 'detached' || (current === 'attached' && !resumed);
+
+    if (!continuityLost) return;
+
+    this._logger.error('ClientTransport._handleChannelStateChange(); channel continuity lost', {
+      current,
+      resumed,
+      previous: stateChange.previous,
+    });
+
+    const err = new Ably.ErrorInfo(
+      `unable to deliver events; channel continuity lost (${current}${current === 'attached' ? ', resumed: false' : ''})`,
+      ErrorCode.ChannelContinuityLost,
+      500,
+      stateChange.reason,
+    );
+
+    // As with cancellation (_closeMatchingTurnStreams), do not clear
+    // _ownTurnIds or _turnObservers here — late events must still accumulate
+    // into the tree. The turn-end handler cleans up observers.
+    for (const turnId of this._ownTurnIds) {
+      this._router.errorStream(turnId, err);
+    }
+
+    this._emitter.emit('error', err);
+  }
+
   // ---------------------------------------------------------------------------
   // Tree mutation + notification helpers
   // ---------------------------------------------------------------------------
@@ -330,10 +467,9 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
    * @param serial - Ably serial for tree ordering.
    */
   private _upsertAndNotify(message: TMessage, headers: Record<string, string>, serial?: string): void {
-    const key = this._codec.getMessageKey(message);
-    const msgId = headers[HEADER_MSG_ID] ?? key;
+    const msgId = headers[HEADER_MSG_ID];
+    if (!msgId) return;
     this._tree.upsert(msgId, message, headers, serial);
-    this._emitter.emit('message');
   }
 
   // ---------------------------------------------------------------------------
@@ -380,6 +516,18 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
     const observer = this._turnObservers.get(turnId);
     if (!observer) return;
 
+    // Sync the accumulator with the tree before processing. If the message
+    // was updated externally (via cross-turn events), initMessage syncs the
+    // accumulator's state so the update isn't lost when processing
+    // late turn events like finish-step/finish.
+    const msgId = observer.headers[HEADER_MSG_ID];
+    if (msgId) {
+      const treeNode = this._tree.getNode(msgId);
+      if (treeNode) {
+        observer.accumulator.initMessage(msgId, treeNode.message);
+      }
+    }
+
     observer.accumulator.processOutputs([output]);
 
     const messages = observer.accumulator.messages;
@@ -398,13 +546,10 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
     }
 
     if (message) {
-      this._tree.upsert(
-        observer.headers[HEADER_MSG_ID] ?? this._codec.getMessageKey(message),
-        message,
-        { ...observer.headers },
-        observer.serial,
-      );
-      this._emitter.emit('message');
+      const msgId = observer.headers[HEADER_MSG_ID];
+      if (msgId) {
+        this._tree.upsert(msgId, message, { ...observer.headers }, observer.serial);
+      }
     }
   }
 
@@ -437,39 +582,37 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
     // The observer must remain alive so that late server events (e.g. abort,
     // x-ably-status: aborted) arriving before turn-end are still accumulated
     // into the message store. The turn-end handler cleans up observers.
-    if (filter.all) {
-      for (const turnId of this._ownTurnIds) {
-        this._router.closeStream(turnId);
-      }
-    } else if (filter.own) {
-      for (const tid of this._ownTurnIds) {
-        this._router.closeStream(tid);
-      }
-    } else if (filter.clientId) {
-      for (const [tid, cid] of this._turnClientIds) {
-        if (cid === filter.clientId) {
-          this._router.closeStream(tid);
-        }
-      }
-    } else if (filter.turnId) {
-      this._router.closeStream(filter.turnId);
+    for (const turnId of this._getMatchingTurnIds(filter)) {
+      this._router.closeStream(turnId);
     }
   }
 
   private _getMatchingTurnIds(filter: CancelFilter): Set<string> {
     const matched = new Set<string>();
+    const activeTurns = this._tree.getActiveTurnIds();
+
     if (filter.all) {
-      for (const turnId of this._turnClientIds.keys()) matched.add(turnId);
+      for (const turnIds of activeTurns.values()) {
+        for (const turnId of turnIds) matched.add(turnId);
+      }
     } else if (filter.own) {
-      for (const [turnId, cid] of this._turnClientIds) {
-        if (cid === this._clientId) matched.add(turnId);
+      const ownTurns = activeTurns.get(this._clientId ?? '');
+      if (ownTurns) {
+        for (const turnId of ownTurns) matched.add(turnId);
       }
     } else if (filter.clientId) {
-      for (const [turnId, cid] of this._turnClientIds) {
-        if (cid === filter.clientId) matched.add(turnId);
+      const clientTurns = activeTurns.get(filter.clientId);
+      if (clientTurns) {
+        for (const turnId of clientTurns) matched.add(turnId);
+      }
+    } else if (filter.turnId) {
+      // Check if the turnId exists in any client's turns
+      for (const turnIds of activeTurns.values()) {
+        if (turnIds.has(filter.turnId)) {
+          matched.add(filter.turnId);
+          break;
+        }
       }
-    } else if (filter.turnId && this._turnClientIds.has(filter.turnId)) {
-      matched.add(filter.turnId);
     }
     return matched;
   }
@@ -478,125 +621,89 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
   // Input message helpers
   // ---------------------------------------------------------------------------
 
-  private _getMessagesWithHeaders(): MessageWithHeaders<TMessage>[] {
-    return this._tree.flatten().map((m) => ({
-      message: m,
-      headers: this.getMessageHeaders(m),
-    }));
-  }
-
-  /**
-   * Compute truncated history: everything before the target message.
-   * Used by regenerate so the LLM doesn't see the response being replaced.
-   * @param messageId - The msg-id to truncate history before.
-   * @returns Input messages preceding the target.
-   */
-  private _getHistoryBefore(messageId: string): MessageWithHeaders<TMessage>[] {
-    const all = this._getMessagesWithHeaders();
-    const idx = all.findIndex((inp) => inp.headers?.[HEADER_MSG_ID] === messageId);
-    return idx === -1 ? all : all.slice(0, idx);
-  }
-
   // ---------------------------------------------------------------------------
-  // History pagination helpers
+  // Public API
   // ---------------------------------------------------------------------------
 
-  private _processHistoryPage(page: PaginatedMessages<TMessage>): void {
-    for (const [i, message] of page.items.entries()) {
-      const headers = page.itemHeaders?.[i] ?? {};
-      const serial = page.itemSerials?.[i];
-      const key = this._codec.getMessageKey(message);
-      const msgId = headers[HEADER_MSG_ID] ?? key;
-      this._tree.upsert(msgId, message, headers, serial);
-    }
-    this._emitter.emit('message');
-
-    // Prepend raw Ably messages (older messages go at the beginning)
-    if (page.rawMessages && page.rawMessages.length > 0) {
-      this._ablyMessages.unshift(...page.rawMessages);
-      this._emitter.emit('ably-message');
-    }
-  }
-
-  private async _loadUntilVisible(
-    firstPage: PaginatedMessages<TMessage>,
-    target: number,
-    beforeKeys: Set<string>,
-  ): Promise<{ newVisible: TMessage[]; lastPage: PaginatedMessages<TMessage> }> {
-    this._processHistoryPage(firstPage);
-    let page = firstPage;
-
-    const newVisibleCount = (): number => {
-      let count = 0;
-      for (const m of this._tree.flatten()) {
-        if (!beforeKeys.has(this._codec.getMessageKey(m))) count++;
-      }
-      return count;
-    };
-
-    while (newVisibleCount() < target && page.hasNext()) {
-      const nextPage = await page.next();
-      if (!nextPage) break;
-      this._processHistoryPage(nextPage);
-      page = nextPage;
-    }
-
-    const newVisible = this._tree.flatten().filter((m) => !beforeKeys.has(this._codec.getMessageKey(m)));
-    return { newVisible, lastPage: page };
-  }
-
-  private _releaseWithheld(messages: TMessage[]): void {
-    for (const m of messages) {
-      this._withheldKeys.delete(this._codec.getMessageKey(m));
-    }
-    if (messages.length > 0) {
-      this._emitter.emit('message');
+  // Spec: AIT-CT10b
+  createView(): View<TEvent, TMessage> {
+    if (this._state === ClientTransportState.CLOSED) {
+      throw new Ably.ErrorInfo('unable to create view; transport is closed', ErrorCode.TransportClosed, 400);
     }
+    this._logger.trace('DefaultClientTransport.createView();');
+    const view = createView<TEvent, TMessage>({
+      tree: this._tree,
+      channel: this._channel,
+      codec: this._codec,
+      sendDelegate: this._internalSend.bind(this),
+      logger: this._logger,
+      onClose: () => this._views.delete(view),
+    });
+    this._views.add(view);
+    return view;
   }
 
-  // ---------------------------------------------------------------------------
-  // Public API
-  // ---------------------------------------------------------------------------
-
   // Spec: AIT-CT3, AIT-CT4
-  async send(input: TMessage | TMessage[], sendOptions?: SendOptions): Promise<ActiveTurn<TEvent>> {
-    if (this._closed) {
+  private async _internalSend(
+    input: TMessage | TMessage[],
+    sendOptions: SendOptions | undefined,
+    history: MessageNode<TMessage>[],
+    eventNodes?: EventsNode<TEvent>[],
+  ): Promise<ActiveTurn<TEvent>> {
+    if (this._state === ClientTransportState.CLOSED) {
       throw new Ably.ErrorInfo('unable to send; transport is closed', ErrorCode.TransportClosed, 400);
     }
     await this._attachPromise;
     // CAST: re-check after await — close() may have been called while waiting for attach.
-    // TypeScript's control flow narrows _closed to false after the first check, but the
-    // await yields and close() can mutate _closed concurrently.
-    if (this._closed as boolean) {
+    // TypeScript's control flow narrows _state after the first check, but the
+    // await yields and close() can mutate _state concurrently.
+    if ((this._state as ClientTransportState) === ClientTransportState.CLOSED) {
       throw new Ably.ErrorInfo('unable to send; transport is closed', ErrorCode.TransportClosed, 400);
     }
 
-    this._logger.trace('ClientTransport.send();');
+    // Spec: AIT-CT20
+    const state = this._channel.state;
+    if (state !== 'attached' && state !== 'attaching') {
+      throw new Ably.ErrorInfo(`unable to send; channel is ${state}`, ErrorCode.ChannelNotReady, 400);
+    }
+
+    this._logger.trace('ClientTransport._internalSend();');
 
     const msgs = Array.isArray(input) ? input : [input];
     const turnId = crypto.randomUUID();
     this._ownTurnIds.add(turnId);
+    this._tree.trackTurn(turnId, this._clientId ?? '');
+
+    // Flush any events staged via stageEvents() since the last send. They
+    // have already been applied to the tree, so merge them into the POST
+    // body without re-applying. External eventNodes (e.g. from view.update)
+    // have NOT been applied yet and need the optimistic tree update below.
+    const flushedStaged = this._pendingLocalEvents;
+    this._pendingLocalEvents = [];
+
+    // Optimistic tree updates for external cross-turn events — must happen
+    // before capturing history so the POST body includes the updated
+    // message state.
+    if (eventNodes && eventNodes.length > 0) {
+      this._applyEventsToTree(eventNodes);
+    }
+
+    const allEventNodes: EventsNode<TEvent>[] = [...flushedStaged, ...(eventNodes ?? [])];
 
     const msgIds = new Set<string>();
-    const postMessages: { message: TMessage; headers: Record<string, string> }[] = [];
+    const postMessages: MessageNode<TMessage>[] = [];
 
-    // Capture history BEFORE optimistic inserts. The optimistic messages are
-    // sent in the `messages` field — including them in `history` too would
-    // cause the server to see them twice.
-    const preInsertHistory = this._getMessagesWithHeaders();
+    // The View pre-computed the visible branch before calling this delegate,
+    // so preInsertHistory reflects the state before any optimistic inserts.
+    const preInsertHistory = history;
 
     // Spec: AIT-CT3d
     // Auto-compute parent from the current thread if not explicitly provided
     let autoParent: string | undefined;
     if (sendOptions?.parent === undefined && !sendOptions?.forkOf) {
-      const flat = this._tree.flatten();
-      if (flat.length > 0) {
-        const lastMsg = flat.at(-1);
-        if (lastMsg) {
-          const lastKey = this._codec.getMessageKey(lastMsg);
-          const lastNode = this._tree.getNodeByKey(lastKey);
-          autoParent = lastNode?.msgId ?? lastKey;
-        }
+      const lastNode = preInsertHistory.at(-1);
+      if (lastNode) {
+        autoParent = lastNode.msgId;
       }
     }
 
@@ -608,7 +715,7 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
       this._ownMsgIds.add(msgId);
       msgIds.add(msgId);
 
-      const resolvedParent = sendOptions?.parent === undefined ? autoParent : (sendOptions.parent ?? undefined);
+      const resolvedParent = sendOptions?.parent === undefined ? autoParent : sendOptions.parent;
 
       const optimisticHeaders = buildTransportHeaders({
         role: 'user',
@@ -622,10 +729,16 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
       // Optimistically insert each user message into the tree
       this._upsertAndNotify(message, optimisticHeaders);
 
-      // Include per-message parent so the server chains messages correctly.
-      const postHeaders: Record<string, string> = { [HEADER_MSG_ID]: msgId, [HEADER_ROLE]: 'user' };
-      if (resolvedParent) postHeaders[HEADER_PARENT] = resolvedParent;
-      postMessages.push({ message, headers: postHeaders });
+      // Build MessageNode for the POST body
+      postMessages.push({
+        kind: 'message',
+        message,
+        msgId,
+        parentId: resolvedParent,
+        forkOf: sendOptions?.forkOf,
+        headers: optimisticHeaders,
+        serial: undefined,
+      });
 
       // Spec: AIT-CT3e
       // Chain: each subsequent message in the batch parents off the previous
@@ -653,6 +766,7 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
       messages: postMessages,
       ...(sendOptions?.forkOf !== undefined && { forkOf: sendOptions.forkOf }),
       ...(postParent !== undefined && { parent: postParent }),
+      ...(allEventNodes.length > 0 && { events: allEventNodes }),
     };
 
     const postHeaders: Record<string, string> = {
@@ -674,90 +788,103 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
     })
       .then((response) => {
         if (!response.ok) {
-          this._emitter.emit(
-            'error',
-            new Ably.ErrorInfo(
-              `unable to send; HTTP POST to ${this._api} returned ${String(response.status)} ${response.statusText}`,
-              ErrorCode.TransportSendFailed,
-              response.status,
-            ),
+          const err = new Ably.ErrorInfo(
+            `unable to send; HTTP POST to ${this._api} returned ${String(response.status)} ${response.statusText}`,
+            ErrorCode.TransportSendFailed,
+            response.status,
           );
-          this._router.closeStream(turnId);
+          this._emitter.emit('error', err);
+          this._router.errorStream(turnId, err);
         }
       })
       .catch((error: unknown) => {
         const cause = error instanceof Ably.ErrorInfo ? error : undefined;
-        this._emitter.emit(
-          'error',
-          new Ably.ErrorInfo(
-            `unable to send; HTTP POST to ${this._api} failed: ${error instanceof Error ? error.message : String(error)}`,
-            ErrorCode.TransportSendFailed,
-            500,
-            cause,
-          ),
+        const err = new Ably.ErrorInfo(
+          `unable to send; HTTP POST to ${this._api} failed: ${error instanceof Error ? error.message : String(error)}`,
+          ErrorCode.TransportSendFailed,
+          500,
+          cause,
         );
-        this._router.closeStream(turnId);
+        this._emitter.emit('error', err);
+        this._router.errorStream(turnId, err);
       });
 
     return {
       stream,
       turnId,
       cancel: async () => this.cancel({ turnId }),
+      optimisticMsgIds: [...msgIds],
     };
   }
 
-  // Spec: AIT-CT5
-  async regenerate(messageId: string, sendOptions?: SendOptions): Promise<ActiveTurn<TEvent>> {
-    this._logger.trace('ClientTransport.regenerate();', { messageId });
-
-    const node = this._tree.getNode(messageId);
-    const parentId = node?.parentId;
-
-    return this.send([], {
-      ...sendOptions,
-      body: {
-        history: this._getHistoryBefore(messageId),
-        ...sendOptions?.body,
-      },
-      forkOf: messageId,
-      parent: parentId,
-    });
-  }
-
-  // Spec: AIT-CT6
-  async edit(
-    messageId: string,
-    newMessages: TMessage | TMessage[],
-    sendOptions?: SendOptions,
-  ): Promise<ActiveTurn<TEvent>> {
-    this._logger.trace('ClientTransport.edit();', { messageId });
-
-    const node = this._tree.getNode(messageId);
-    const parentId = node?.parentId;
-
-    return this.send(newMessages, {
-      ...sendOptions,
-      body: {
-        history: this._getHistoryBefore(messageId),
-        ...sendOptions?.body,
-      },
-      forkOf: messageId,
-      parent: parentId,
-    });
-  }
-
   // Spec: AIT-CT7, AIT-CT7a
   async cancel(filter?: CancelFilter): Promise<void> {
-    if (this._closed) return;
+    if (this._state === ClientTransportState.CLOSED) return;
     const resolved = filter ?? { own: true };
     this._logger.debug('ClientTransport.cancel();', { filter: resolved });
     await this._publishCancel(resolved);
     this._closeMatchingTurnStreams(resolved);
   }
 
+  stageEvents(msgId: string, events: TEvent[]): void {
+    this._logger.trace('ClientTransport.stageEvents();', { msgId, eventCount: events.length });
+    if (this._state === ClientTransportState.CLOSED) {
+      this._logger.warn('ClientTransport.stageEvents(); transport is closed', { msgId });
+      return;
+    }
+    if (!this._tree.getNode(msgId)) {
+      this._logger.warn('ClientTransport.stageEvents(); msgId not found in tree', { msgId });
+      return;
+    }
+    if (events.length === 0) return;
+    const node: EventsNode<TEvent> = { kind: 'event', msgId, events };
+    // Apply immediately so any subsequent useMessageSync / tree observer
+    // sees the merged state — no window where the staged event can be
+    // clobbered by an interleaved observer turn update.
+    this._applyEventsToTree([node]);
+    this._pendingLocalEvents.push(node);
+  }
+
+  stageMessage(msgId: string, message: TMessage): void {
+    this._logger.trace('ClientTransport.stageMessage();', { msgId });
+    if (this._state === ClientTransportState.CLOSED) {
+      this._logger.warn('ClientTransport.stageMessage(); transport is closed', { msgId });
+      return;
+    }
+    const existing = this._tree.getNode(msgId);
+    if (!existing) {
+      this._logger.warn('ClientTransport.stageMessage(); msgId not found in tree', { msgId });
+      return;
+    }
+    // Preserve structural metadata; only the message body changes.
+    this._tree.upsert(msgId, message, existing.headers, existing.serial);
+  }
+
+  // Apply events to the tree using the codec's accumulator. Shared by
+  // stageEvents (local staging) and _internalSend (external eventNodes
+  // arriving via view.update).
+  private _applyEventsToTree(eventNodes: EventsNode<TEvent>[]): void {
+    for (const node of eventNodes) {
+      const existingNode = this._tree.getNode(node.msgId);
+      if (!existingNode) continue;
+      const outputs = node.events.map((event) => ({
+        kind: 'event' as const,
+        event,
+        messageId: node.msgId,
+      }));
+      const accumulator = this._codec.createAccumulator();
+      accumulator.initMessage(node.msgId, existingNode.message);
+      accumulator.processOutputs(outputs);
+      const updatedMsg = accumulator.messages.at(-1);
+      if (updatedMsg) {
+        this._tree.upsert(node.msgId, updatedMsg, existingNode.headers, existingNode.serial);
+      }
+    }
+  }
+
   // Spec: AIT-CT18
   async waitForTurn(filter?: CancelFilter): Promise<void> {
-    if (this._closed) return;
+    if (this._state === ClientTransportState.CLOSED) return;
     const resolved = filter ?? { own: true };
     const remaining = this._getMatchingTurnIds(resolved);
     if (remaining.size === 0) return;
@@ -765,153 +892,42 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
     this._logger.debug('ClientTransport.waitForTurn();', { turnIds: [...remaining] });
 
     return new Promise<void>((resolve) => {
-      const handler = (event: TurnLifecycleEvent): void => {
+      let resolved = false;
+      const done = (): void => {
+        if (resolved) return;
+        resolved = true;
+        unsub();
+        const idx = this._closeResolvers.indexOf(done);
+        if (idx !== -1) this._closeResolvers.splice(idx, 1);
+        resolve();
+      };
+
+      const unsub = this._tree.on('turn', (event: TurnLifecycleEvent) => {
         if (event.type !== EVENT_TURN_END) return;
         remaining.delete(event.turnId);
-        if (remaining.size === 0) {
-          this._emitter.off('turn', handler);
-          resolve();
-        }
-      };
-      this._emitter.on('turn', handler);
+        if (remaining.size === 0) done();
+      });
+
+      // Resolve on transport close to prevent leaked subscriptions
+      this._closeResolvers.push(done);
     });
   }
 
-  // Spec: AIT-CT8, AIT-CT8a, AIT-CT8b, AIT-CT8c, AIT-CT8d
-  on(event: 'message' | 'ably-message', handler: () => void): () => void;
-  on(event: 'turn', handler: (event: TurnLifecycleEvent) => void): () => void;
-  on(event: 'error', handler: (error: Ably.ErrorInfo) => void): () => void;
-  on(
-    eventName: 'message' | 'turn' | 'error' | 'ably-message',
-    handler: (() => void) | ((event: TurnLifecycleEvent) => void) | ((error: Ably.ErrorInfo) => void),
-  ): () => void {
-    if (this._closed) return noopUnsubscribe;
-    // CAST: the overload signatures enforce correct handler types per event name.
-    // The implementation must cast to satisfy the EventEmitter's generic callback type.
+  // Spec: AIT-CT8, AIT-CT8c, AIT-CT8d
+  on(event: 'error', handler: (error: Ably.ErrorInfo) => void): () => void {
+    if (this._state === ClientTransportState.CLOSED) return noopUnsubscribe;
+    // CAST: the overload signature enforces the correct handler type.
     const cb = handler as (arg: ClientTransportEventsMap[keyof ClientTransportEventsMap]) => void;
-    this._emitter.on(eventName, cb);
+    this._emitter.on(event, cb);
     return () => {
-      this._emitter.off(eventName, cb);
+      this._emitter.off(event, cb);
     };
   }
 
-  // Spec: AIT-CT10
-  getTree(): ConversationTree<TMessage> {
-    return this._tree;
-  }
-
-  // Spec: AIT-CT17
-  getActiveTurnIds(): Map<string, Set<string>> {
-    const result = new Map<string, Set<string>>();
-    for (const [turnId, cid] of this._turnClientIds) {
-      let set = result.get(cid);
-      if (!set) {
-        set = new Set();
-        result.set(cid, set);
-      }
-      set.add(turnId);
-    }
-    return result;
-  }
-
-  getMessageHeaders(message: TMessage): Record<string, string> | undefined {
-    const key = this._codec.getMessageKey(message);
-    return this._tree.getNodeByKey(key)?.headers;
-  }
-
-  // Spec: AIT-CT9
-  getMessages(): TMessage[] {
-    if (this._withheldKeys.size === 0) return this._tree.flatten();
-    return this._tree.flatten().filter((m) => !this._withheldKeys.has(this._codec.getMessageKey(m)));
-  }
-
-  getMessagesWithHeaders(): MessageWithHeaders<TMessage>[] {
-    return this._getMessagesWithHeaders();
-  }
-
-  getAblyMessages(): Ably.InboundMessage[] {
-    return [...this._ablyMessages];
-  }
-
-  // Spec: AIT-CT11, AIT-CT11a, AIT-CT11b, AIT-CT11c
-  async history(opts?: LoadHistoryOptions): Promise<PaginatedMessages<TMessage>> {
-    if (this._closed) {
-      throw new Ably.ErrorInfo('unable to load history; transport is closed', ErrorCode.TransportClosed, 400);
-    }
-    this._logger.trace('ClientTransport.history();', { limit: opts?.limit });
-    const limit = opts?.limit ?? 100;
-
-    // Snapshot before loading — everything already in the tree stays visible
-    const beforeKeys = new Set(this._tree.flatten().map((m) => this._codec.getMessageKey(m)));
-
-    let lastPage = await decodeHistory(this._channel, this._codec, opts, this._logger);
-
-    const initial = await this._loadUntilVisible(lastPage, limit, beforeKeys);
-    lastPage = initial.lastPage;
-
-    // newVisible is chronological (oldest-first from flatten).
-    // For "load older" pagination: release the NEWEST `limit` now,
-    // withhold the older ones for subsequent next() calls.
-    const newVisible = initial.newVisible;
-
-    // Withhold ALL new visible messages first, then release the newest batch
-    for (const m of newVisible) {
-      this._withheldKeys.add(this._codec.getMessageKey(m));
-    }
-
-    const released = newVisible.slice(-limit);
-    // Mutable buffer of older messages, drained newest-first by successive next() calls
-    const withheldBuffer = newVisible.slice(0, -limit);
-    this._releaseWithheld(released);
-
-    const buildPage = (items: TMessage[]): PaginatedMessages<TMessage> => ({
-      items,
-      hasNext: () => withheldBuffer.length > 0 || lastPage.hasNext(),
-      next: async () => {
-        // Drain withheld buffer first (older messages, released newest-first)
-        if (withheldBuffer.length > 0) {
-          // Remove and return the newest `limit` items from the buffer
-          const batch = withheldBuffer.splice(-limit, limit);
-          this._releaseWithheld(batch);
-          return buildPage(batch);
-        }
-
-        // Buffer exhausted — load more pages from decodeHistory
-        if (!lastPage.hasNext()) return;
-
-        const nextInternal = await lastPage.next();
-        if (!nextInternal) return;
-
-        // Everything currently in the tree is "already known"
-        const alreadyKnown = new Set(beforeKeys);
-        for (const m of this._tree.flatten()) {
-          alreadyKnown.add(this._codec.getMessageKey(m));
-        }
-
-        const loaded = await this._loadUntilVisible(nextInternal, limit, alreadyKnown);
-        lastPage = loaded.lastPage;
-
-        const moreVisible = loaded.newVisible;
-        for (const m of moreVisible) {
-          this._withheldKeys.add(this._codec.getMessageKey(m));
-        }
-        // Remove and return the newest `limit` items; rest stays in buffer
-        const moreBatch = moreVisible.splice(-limit, limit);
-        withheldBuffer.push(...moreVisible);
-        this._releaseWithheld(moreBatch);
-
-        if (moreBatch.length === 0) return;
-        return buildPage(moreBatch);
-      },
-    });
-
-    return buildPage(released);
-  }
-
-  // Spec: AIT-CT12, AIT-CT12a, AIT-CT12b
+  // Spec: AIT-CT12, AIT-CT12a, AIT-CT12b, AIT-CT10c
   async close(options?: CloseOptions): Promise<void> {
-    if (this._closed) return;
-    this._closed = true;
+    if (this._state === ClientTransportState.CLOSED) return;
+    this._state = ClientTransportState.CLOSED;
     this._logger.info('ClientTransport.close();');
 
     // Best-effort cancel publish before tearing down local state
@@ -925,6 +941,7 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
     }
 
     this._channel.unsubscribe(this._onMessage);
+    this._channel.off(this._onChannelStateChange);
 
     // Close any remaining active streams
     for (const turnId of this._ownTurnIds) {
@@ -933,12 +950,13 @@ class DefaultClientTransport<TEvent, TMessage> implements ClientTransport<TEvent
 
     this._turnObservers.clear();
     this._emitter.off();
+    for (const v of this._views) v.close();
+    this._views.clear();
+    for (const resolve of this._closeResolvers) resolve();
+    this._closeResolvers.length = 0;
     this._ownTurnIds.clear();
     this._ownMsgIds.clear();
     this._turnMsgIds.clear();
-    this._turnClientIds.clear();
-    this._withheldKeys.clear();
-    this._ablyMessages.length = 0;
   }
 }