@ably/ai-transport 0.1.0 → 0.3.0

package/src/core/codec/codec-event.ts

@@ -0,0 +1,27 @@
+/**
+ * `toCodecEvents` — tag a decoded message's events with their wire direction.
+ *
+ * A decoded message is already split into inputs and outputs by the decoder
+ * (driven by the Ably message name — the authoritative direction signal). This
+ * helper folds that split into the ordered {@link CodecEvent} stream the reducer
+ * consumes, so the direction is carried explicitly rather than re-inferred from
+ * each event's shape. Inputs are tagged before outputs, preserving the wire
+ * order within a single message (a message is single-direction, so the relative
+ * order of the two groups is immaterial).
+ */
+
+import type { CodecEvent, CodecInputEvent, CodecOutputEvent, DecodedMessage } from './types.js';
+
+/**
+ * Tag a decoded message's events with their wire direction.
+ * @template TInput - The codec's input union.
+ * @template TOutput - The codec's output union.
+ * @param decoded - The decoder's input/output split for one inbound message.
+ * @returns The events as a direction-tagged {@link CodecEvent} list, inputs first.
+ */
+export const toCodecEvents = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent>(
+  decoded: DecodedMessage<TInput, TOutput>,
+): CodecEvent<TInput, TOutput>[] => [
+  ...decoded.inputs.map((event): CodecEvent<TInput, TOutput> => ({ direction: 'input', event })),
+  ...decoded.outputs.map((event): CodecEvent<TInput, TOutput> => ({ direction: 'output', event })),
+];

package/src/core/codec/decoder.ts

@@ -3,27 +3,24 @@
  *
  * Handles the Ably message action patterns (create, append, update, delete)
  * and delegates to domain-specific hooks for event building and discrete
- * event decoding.
+ * event decoding. Stream trackers are version-guarded: a delivery whose
+ * `Message.version.serial` the tracker has already incorporated decodes to
+ * nothing, so the same decoder instance can serve both the live
+ * subscription and history hydration without double-decoding.
  *
  * Domain decoders call `createDecoderCore(hooks, options)` and provide hooks
- * for stream classification, event building, and discrete decoding.
+ * for stream classification, event building, and discrete decoding. Hooks
+ * return a flat `TEvent[]` — no event-vs-message union. Per-message routing
+ * concerns (`codec-message-id`) are handled by the SDK via `ReducerMeta`, not
+ * here.
  */
 
 import type * as Ably from 'ably';
 
-import { HEADER_MSG_ID, HEADER_STATUS, HEADER_STREAM, HEADER_STREAM_ID } from '../../constants.js';
+import { HEADER_STATUS, HEADER_STREAM, HEADER_STREAM_ID } from '../../constants.js';
 import type { Logger } from '../../logger.js';
-import { getHeaders } from '../../utils.js';
-import type { DecoderOutput, MessagePayload, StreamTrackerState } from './types.js';
-
-/**
- * Wrap a domain event as a single-element decoder output array.
- * @param event - The domain event to wrap.
- * @returns A single-element array containing the event as a decoder output.
- */
-export const eventOutput = <TEvent, TMessage>(event: TEvent): DecoderOutput<TEvent, TMessage>[] => [
-  { kind: 'event', event },
-];
+import { getCodecHeaders, getTransportHeaders } from '../../utils.js';
+import type { MessagePayload, StreamTrackerState } from './types.js';
 
 // ---------------------------------------------------------------------------
 // Options
@@ -44,32 +41,29 @@ export interface DecoderCoreOptions {
 // ---------------------------------------------------------------------------
 
 /** Hooks that a domain codec provides to the decoder core for stream classification and event building. */
-export interface DecoderCoreHooks<TEvent, TMessage> {
+export interface DecoderCoreHooks<TEvent> {
   /**
    * Build domain events emitted when a new stream starts. May return multiple
    * events (e.g. a start event and a start-step event).
    */
-  buildStartEvents(tracker: StreamTrackerState): DecoderOutput<TEvent, TMessage>[];
+  buildStartEvents(tracker: StreamTrackerState): TEvent[];
 
   /** Build domain events for a text delta received on a stream. */
-  buildDeltaEvents(tracker: StreamTrackerState, delta: string): DecoderOutput<TEvent, TMessage>[];
+  buildDeltaEvents(tracker: StreamTrackerState, delta: string): TEvent[];
 
   /**
-   * Build domain events emitted when a stream finishes (x-ably-status:finished).
-   * Not called for aborted streams. The closing headers may differ from
-   * tracker.headers if the closing append carried updated headers.
+   * Build domain events emitted when a stream completes (status:complete).
+   * Not called for cancelled streams. The closing codec headers may differ
+   * from tracker.codecHeaders if the closing append carried updated headers.
    */
-  buildEndEvents(
-    tracker: StreamTrackerState,
-    closingHeaders: Record<string, string>,
-  ): DecoderOutput<TEvent, TMessage>[];
+  buildEndEvents(tracker: StreamTrackerState, closingCodecHeaders: Record<string, string>): TEvent[];
 
   /**
-   * Decode a discrete message (message.create where x-ably-stream is "false",
-   * or a non-streamable first-contact update). Handles user messages, lifecycle
-   * events, tool lifecycle, data-*, etc.
+   * Decode a discrete message (a `message.create` whose stream header is not
+   * "true", or a non-streamable first-contact update). Handles user messages,
+   * tool lifecycle, data-*, etc.
    */
-  decodeDiscrete(input: MessagePayload): DecoderOutput<TEvent, TMessage>[];
+  decodeDiscrete(input: MessagePayload): TEvent[];
 }
 
 // ---------------------------------------------------------------------------
@@ -77,9 +71,9 @@ export interface DecoderCoreHooks<TEvent, TMessage> {
 // ---------------------------------------------------------------------------
 
 /** The decoder core returned by {@link createDecoderCore}. */
-export interface DecoderCore<TEvent, TMessage> {
-  /** Decode a single Ably message into zero or more domain outputs. */
-  decode(message: Ably.InboundMessage): DecoderOutput<TEvent, TMessage>[];
+export interface DecoderCore<TEvent> {
+  /** Decode a single Ably message into zero or more domain TEvents. */
+  decode(message: Ably.InboundMessage): TEvent[];
 }
 
 // ---------------------------------------------------------------------------
@@ -87,70 +81,50 @@ export interface DecoderCore<TEvent, TMessage> {
 // ---------------------------------------------------------------------------
 
 // Spec: AIT-CD7
-class DefaultDecoderCore<TEvent, TMessage> implements DecoderCore<TEvent, TMessage> {
-  private readonly _hooks: DecoderCoreHooks<TEvent, TMessage>;
+class DefaultDecoderCore<TEvent> implements DecoderCore<TEvent> {
+  private readonly _hooks: DecoderCoreHooks<TEvent>;
   private readonly _logger: Logger | undefined;
   private readonly _onStreamUpdate: ((tracker: StreamTrackerState) => void) | undefined;
   private readonly _onStreamDelete: ((serial: string, tracker: StreamTrackerState | undefined) => void) | undefined;
   private readonly _serialState = new Map<string, StreamTrackerState>();
 
-  constructor(hooks: DecoderCoreHooks<TEvent, TMessage>, options: DecoderCoreOptions = {}) {
+  constructor(hooks: DecoderCoreHooks<TEvent>, options: DecoderCoreOptions = {}) {
     this._hooks = hooks;
     this._onStreamUpdate = options.onStreamUpdate;
     this._onStreamDelete = options.onStreamDelete;
     this._logger = options.logger?.withContext({ component: 'DecoderCore' });
   }
 
-  decode(message: Ably.InboundMessage): DecoderOutput<TEvent, TMessage>[] {
+  decode(message: Ably.InboundMessage): TEvent[] {
     const action = message.action;
 
     this._logger?.trace('DefaultDecoderCore.decode();', { action, serial: message.serial, name: message.name });
 
-    let outputs: DecoderOutput<TEvent, TMessage>[];
-
     switch (action) {
       // Spec: AIT-CD7a
       case 'message.create': {
         const payload = this._toPayload(message);
-
-        outputs =
-          payload.headers?.[HEADER_STREAM] === 'true'
-            ? this._decodeStreamedCreate(payload, message.serial)
-            : this._hooks.decodeDiscrete(payload);
-        break;
+        return payload.transportHeaders?.[HEADER_STREAM] === 'true'
+          ? this._decodeStreamedCreate(payload, message.serial, message.version.serial)
+          : this._hooks.decodeDiscrete(payload);
       }
 
       case 'message.append': {
-        outputs = this._decodeAppend(message);
-        break;
+        return this._decodeAppend(message);
       }
 
       case 'message.update': {
-        outputs = this._decodeUpdate(message);
-        break;
+        return this._decodeUpdate(message);
       }
 
       case 'message.delete': {
-        outputs = this._decodeDelete(message);
-        break;
+        return this._decodeDelete(message);
       }
 
       default: {
         return [];
       }
     }
-
-    // Tag all event outputs with the message ID from x-ably-msg-id for accumulator correlation.
-    const messageId = getHeaders(message)[HEADER_MSG_ID];
-    if (messageId) {
-      for (const output of outputs) {
-        if (output.kind === 'event') {
-          output.messageId = messageId;
-        }
-      }
-    }
-
-    return outputs;
   }
 
   // -------------------------------------------------------------------------
@@ -162,7 +136,8 @@ class DefaultDecoderCore<TEvent, TMessage> implements DecoderCore<TEvent, TMessa
       name: message.name ?? '',
       // CAST: Ably SDK types `data` as `any`; cast to unknown is the safe boundary type.
       data: message.data as unknown,
-      headers: getHeaders(message),
+      transportHeaders: getTransportHeaders(message),
+      codecHeaders: getCodecHeaders(message),
     };
   }
 
@@ -197,6 +172,99 @@ class DefaultDecoderCore<TEvent, TMessage> implements DecoderCore<TEvent, TMessa
     }
   }
 
+  // -------------------------------------------------------------------------
+  // Private: version guard
+  // -------------------------------------------------------------------------
+
+  /**
+   * Whether a delivery is already incorporated into (or out of contract for)
+   * an existing tracker, and so must decode to nothing. Covers two cases:
+   *
+   * - The delivery carries a `version.serial` at or below the tracker's —
+   *   the mutation it describes is already incorporated (a history aggregate
+   *   covered by live deltas, a resume retransmission, a whole-wire replay).
+   * - The tracker is closed — the stream has ended and its accumulated text
+   *   has been dropped, so nothing further can fold into it. In-contract
+   *   replays are already covered by the version check; this catches
+   *   out-of-contract version-less deliveries for an ended stream.
+   *
+   * A version-bearing delivery that passes advances the tracker's version.
+   * @param method - Calling method name, for log messages.
+   * @param serial - The message serial (the tracker's key).
+   * @param tracker - The existing tracker for the serial.
+   * @param version - The delivery's `Message.version.serial`, if present.
+   * @returns True when the delivery must decode to nothing.
+   */
+  private _alreadyIncorporated(
+    method: string,
+    serial: string,
+    tracker: StreamTrackerState,
+    version: string | undefined,
+  ): boolean {
+    if (version !== undefined && version <= tracker.version) {
+      this._logger?.debug(`DefaultDecoderCore.${method}(); delivery already incorporated`, {
+        serial,
+        version,
+        trackerVersion: tracker.version,
+      });
+      return true;
+    }
+    if (tracker.closed) {
+      this._logger?.debug(`DefaultDecoderCore.${method}(); stream closed, dropping delivery`, { serial, version });
+      return true;
+    }
+    if (version !== undefined) tracker.version = version;
+    return false;
+  }
+
+  /**
+   * Close a tracker, dropping its accumulated text. What remains is a
+   * `{version, closed}` tombstone: enough to recognise covered replays and
+   * out-of-contract post-close deliveries, without retaining the stream's
+   * full content for the decoder's lifetime.
+   * @param tracker - The tracker to close.
+   */
+  private _closeTracker(tracker: StreamTrackerState): void {
+    tracker.closed = true;
+    tracker.accumulated = '';
+  }
+
+  // -------------------------------------------------------------------------
+  // Private: terminal-status transition
+  // -------------------------------------------------------------------------
+
+  /**
+   * Apply a stream's terminal status (complete / cancelled) to a tracker. On
+   * `complete` it emits end events (read before the tracker is closed) and
+   * then closes the tracker; on `cancelled` it closes silently. Both the
+   * append and prefix-match update paths funnel through here so they can't
+   * diverge. Covered replays and post-close deliveries are filtered upstream
+   * by `_alreadyIncorporated`, so no closed-once guard is needed here.
+   * Returns whether a terminal transition fired (so callers can log it).
+   * @param tracker - The stream tracker to close.
+   * @param status - The status header value from the message (may be undefined).
+   * @param closingCodecHeaders - Codec headers from the closing message, passed to buildEndEvents.
+   * @param outputs - The output array end events are pushed into.
+   * @returns True when this call closed the tracker; false otherwise.
+   */
+  private _applyTerminalStatus(
+    tracker: StreamTrackerState,
+    status: string | undefined,
+    closingCodecHeaders: Record<string, string>,
+    outputs: TEvent[],
+  ): boolean {
+    if (status === 'complete') {
+      outputs.push(...this._hooks.buildEndEvents(tracker, closingCodecHeaders));
+      this._closeTracker(tracker);
+      return true;
+    }
+    if (status === 'cancelled') {
+      this._closeTracker(tracker);
+      return true;
+    }
+    return false;
+  }
+
   // -------------------------------------------------------------------------
   // Private: streamed message create
   // -------------------------------------------------------------------------
@@ -204,17 +272,29 @@ class DefaultDecoderCore<TEvent, TMessage> implements DecoderCore<TEvent, TMessa
   private _decodeStreamedCreate(
     payload: MessagePayload,
     serial: string | undefined,
-  ): DecoderOutput<TEvent, TMessage>[] {
+    version: string | undefined,
+  ): TEvent[] {
     if (!serial) return [];
 
-    const streamId = payload.headers?.[HEADER_STREAM_ID] ?? '';
-    const h = payload.headers ?? {};
+    const existing = this._serialState.get(serial);
+    if (existing) {
+      // A create is the message's first version, so a tracker for this serial
+      // has already incorporated it (resume retransmission, whole-wire replay).
+      this._logger?.debug('DefaultDecoderCore._decodeStreamedCreate(); duplicate create for tracked stream', {
+        serial,
+      });
+      return [];
+    }
+
+    const streamId = payload.transportHeaders?.[HEADER_STREAM_ID] ?? '';
 
     const tracker: StreamTrackerState = {
       name: payload.name,
       streamId,
       accumulated: '',
-      headers: { ...h },
+      codecHeaders: { ...payload.codecHeaders },
+      transportHeaders: { ...payload.transportHeaders },
+      version: version ?? serial,
       closed: false,
     };
     this._serialState.set(serial, tracker);
@@ -233,33 +313,42 @@ class DefaultDecoderCore<TEvent, TMessage> implements DecoderCore<TEvent, TMessa
   // -------------------------------------------------------------------------
 
   // Spec: AIT-CD8
-  private _decodeAppend(message: Ably.InboundMessage): DecoderOutput<TEvent, TMessage>[] {
+  private _decodeAppend(message: Ably.InboundMessage): TEvent[] {
     const serial = message.serial;
     if (!serial) return [];
 
     const tracker = this._serialState.get(serial);
     if (!tracker) {
-      // Unknown serial on append — treat as first-contact update
+      // Out of contract: the platform converts the first post-attach append
+      // of an in-flight message into a full-contents update, so an append
+      // should never be a stream's first contact. Keep the first-contact
+      // heuristic as a defensive fallback.
+      this._logger?.warn('DefaultDecoderCore._decodeAppend(); append with no tracker, treating as first contact', {
+        serial,
+      });
       return this._decodeUpdate(message);
     }
 
-    const h = getHeaders(message);
+    if (this._alreadyIncorporated('_decodeAppend', serial, tracker, message.version.serial)) return [];
+
+    const transport = getTransportHeaders(message);
+    const closingCodec = getCodecHeaders(message);
     const delta = typeof message.data === 'string' ? message.data : '';
-    const status = h[HEADER_STATUS];
-    const outputs: DecoderOutput<TEvent, TMessage>[] = [];
+    const status = transport[HEADER_STATUS];
+    const outputs: TEvent[] = [];
 
     if (delta.length > 0) {
       tracker.accumulated += delta;
       outputs.push(...this._hooks.buildDeltaEvents(tracker, delta));
     }
 
-    if (status === 'finished' && !tracker.closed) {
-      tracker.closed = true;
-      outputs.push(...this._hooks.buildEndEvents(tracker, h));
-      this._logger?.debug('DefaultDecoderCore._decodeAppend(); stream finished', { streamId: tracker.streamId });
-    } else if (status === 'aborted' && !tracker.closed) {
-      tracker.closed = true;
-      this._logger?.debug('DefaultDecoderCore._decodeAppend(); stream aborted', { streamId: tracker.streamId });
+    if (this._applyTerminalStatus(tracker, status, closingCodec, outputs)) {
+      this._logger?.debug(
+        `DefaultDecoderCore._decodeAppend(); stream ${status === 'complete' ? 'complete' : 'cancelled'}`,
+        {
+          streamId: tracker.streamId,
+        },
+      );
     }
 
     return outputs;
@@ -270,47 +359,46 @@ class DefaultDecoderCore<TEvent, TMessage> implements DecoderCore<TEvent, TMessa
   // -------------------------------------------------------------------------
 
   // Spec: AIT-CD9
-  private _decodeUpdate(message: Ably.InboundMessage): DecoderOutput<TEvent, TMessage>[] {
+  private _decodeUpdate(message: Ably.InboundMessage): TEvent[] {
     const serial = message.serial;
     if (!serial) return [];
 
     const payload = this._toPayload(message);
-    const h = payload.headers ?? {};
-    const isStreamed = h[HEADER_STREAM] === 'true';
-    const status = h[HEADER_STATUS];
+    const transport = payload.transportHeaders ?? {};
+    const codec = payload.codecHeaders ?? {};
+    const isStreamed = transport[HEADER_STREAM] === 'true';
+    const status = transport[HEADER_STATUS];
 
     const tracker = this._serialState.get(serial);
 
     if (!tracker) {
-      return this._decodeFirstContact(payload, isStreamed, status, serial);
+      return this._decodeFirstContact(payload, isStreamed, status, serial, message.version.serial);
     }
 
+    if (this._alreadyIncorporated('_decodeUpdate', serial, tracker, message.version.serial)) return [];
+
     // Updates to tracked streams use string data for prefix-match accumulation
     const data = this._stringData(message);
 
     // --- Tracker exists: prefix-match or replacement ---
     if (data.startsWith(tracker.accumulated)) {
       const delta = data.slice(tracker.accumulated.length);
-      const outputs: DecoderOutput<TEvent, TMessage>[] = [];
+      const outputs: TEvent[] = [];
 
       if (delta.length > 0) {
         tracker.accumulated = data;
         outputs.push(...this._hooks.buildDeltaEvents(tracker, delta));
       }
 
-      if (status === 'finished' && !tracker.closed) {
-        tracker.closed = true;
-        outputs.push(...this._hooks.buildEndEvents(tracker, h));
-      } else if (status === 'aborted' && !tracker.closed) {
-        tracker.closed = true;
-      }
+      this._applyTerminalStatus(tracker, status, codec, outputs);
 
       return outputs;
     }
 
     // --- Replacement (NOT a prefix match) ---
     tracker.accumulated = data;
-    tracker.headers = { ...h };
+    tracker.codecHeaders = { ...codec };
+    tracker.transportHeaders = { ...transport };
 
     this._invokeOnStreamUpdate(tracker);
 
@@ -322,14 +410,15 @@ class DefaultDecoderCore<TEvent, TMessage> implements DecoderCore<TEvent, TMessa
     isStreamed: boolean,
     status: string | undefined,
     serial: string,
-  ): DecoderOutput<TEvent, TMessage>[] {
+    version: string | undefined,
+  ): TEvent[] {
     // Non-streamed messages are discrete
     if (!isStreamed) {
       return this._hooks.decodeDiscrete(payload);
     }
 
-    const streamId = payload.headers?.[HEADER_STREAM_ID] ?? '';
-    const h = payload.headers ?? {};
+    const streamId = payload.transportHeaders?.[HEADER_STREAM_ID] ?? '';
+    const codec = payload.codecHeaders ?? {};
     const data = typeof payload.data === 'string' ? payload.data : '';
 
     this._logger?.debug('DefaultDecoderCore._decodeFirstContact(); first-contact stream', {
@@ -343,20 +432,26 @@ class DefaultDecoderCore<TEvent, TMessage> implements DecoderCore<TEvent, TMessa
       name: payload.name,
       streamId,
       accumulated: data,
-      headers: { ...h },
-      closed: status === 'finished' || status === 'aborted',
+      codecHeaders: { ...codec },
+      transportHeaders: { ...payload.transportHeaders },
+      version: version ?? serial,
+      closed: false,
     };
     this._serialState.set(serial, newTracker);
 
-    // Emit start + delta (if any) + end (if finished)
+    // Emit start + delta (if any) + end (if complete)
     const outputs = this._hooks.buildStartEvents(newTracker);
 
     if (data.length > 0) {
       outputs.push(...this._hooks.buildDeltaEvents(newTracker, data));
     }
 
-    if (status === 'finished') {
-      outputs.push(...this._hooks.buildEndEvents(newTracker, h));
+    if (status === 'complete') {
+      outputs.push(...this._hooks.buildEndEvents(newTracker, codec));
+    }
+
+    if (status === 'complete' || status === 'cancelled') {
+      this._closeTracker(newTracker);
     }
 
     return outputs;
@@ -367,7 +462,7 @@ class DefaultDecoderCore<TEvent, TMessage> implements DecoderCore<TEvent, TMessa
   // -------------------------------------------------------------------------
 
   // Spec: AIT-CD10
-  private _decodeDelete(message: Ably.InboundMessage): DecoderOutput<TEvent, TMessage>[] {
+  private _decodeDelete(message: Ably.InboundMessage): TEvent[] {
     const serial = message.serial;
     if (!serial) return [];
 
@@ -376,8 +471,10 @@ class DefaultDecoderCore<TEvent, TMessage> implements DecoderCore<TEvent, TMessa
     this._invokeOnStreamDelete(serial, tracker);
 
     if (tracker) {
-      tracker.accumulated = '';
-      tracker.closed = true;
+      // No need to advance the tracker's version here: `_closeTracker` leaves a
+      // closed tombstone, and `_alreadyIncorporated`'s closed check drops every
+      // later delivery regardless of version.
+      this._closeTracker(tracker);
     }
 
     this._logger?.debug('DefaultDecoderCore._decodeDelete();', { serial });
@@ -396,7 +493,7 @@ class DefaultDecoderCore<TEvent, TMessage> implements DecoderCore<TEvent, TMessa
  * @param options - Decoder configuration (callbacks, logger).
  * @returns A new {@link DecoderCore} instance.
  */
-export const createDecoderCore = <TEvent, TMessage>(
-  hooks: DecoderCoreHooks<TEvent, TMessage>,
+export const createDecoderCore = <TEvent>(
+  hooks: DecoderCoreHooks<TEvent>,
   options: DecoderCoreOptions = {},
-): DecoderCore<TEvent, TMessage> => new DefaultDecoderCore(hooks, options);
+): DecoderCore<TEvent> => new DefaultDecoderCore(hooks, options);