@hla4ts/session 0.1.0 → 0.1.1

package/src/session.ts

@@ -1,976 +1,976 @@
-/**
- * Federate Protocol Session
- *
- * Manages the lifecycle of a Federate Protocol session, including:
- * - Connection establishment and termination
- * - Session state machine
- * - Request/response correlation
- * - Heartbeat/keepalive
- * - Session resumption after disconnection
- */
-
-import {
-  type Transport,
-  type ReceivedMessage,
-  MessageType,
-  NO_SESSION_ID,
-  NewSessionStatus,
-} from "@hla4ts/transport";
-
-import {
-  SessionState,
-  isValidTransition,
-  isOperationalState,
-  type SessionOptions,
-  type HlaCallbackRequestListener,
-  type SessionStateListener,
-  type MessageSentListener,
-  DEFAULT_SESSION_OPTIONS,
-} from "./types.ts";
-
-import {
-  SequenceNumber,
-  AtomicSequenceNumber,
-  INITIAL_SEQUENCE_NUMBER,
-  NO_SEQUENCE_NUMBER,
-  isValidSequenceNumber,
-  nextSequenceNumber,
-} from "./sequence-number.ts";
-
-import { TimeoutTimer } from "./timeout-timer.ts";
-
-import {
-  createNewSessionMessage,
-  decodeNewSessionStatus,
-  createResumeRequestMessage,
-  decodeResumeStatus,
-  ResumeStatusCode,
-  createHeartbeatMessage,
-  decodeHeartbeatResponse,
-  createTerminateSessionMessage,
-  createHlaCallRequestMessage,
-  decodeHlaCallResponse,
-  decodeHlaCallbackRequest,
-  createHlaCallbackResponseMessage,
-} from "./messages.ts";
-
-import {
-  SessionLostError,
-  SessionAlreadyTerminatedError,
-  SessionIllegalStateError,
-  BadMessageError,
-  ConnectionTimeoutError,
-} from "./errors.ts";
-
-/**
- * Deferred promise helper for request/response correlation
- */
-interface DeferredPromise<T> {
-  promise: Promise<T>;
-  resolve: (value: T) => void;
-  reject: (reason: Error) => void;
-}
-
-function createDeferred<T>(): DeferredPromise<T> {
-  let resolve!: (value: T) => void;
-  let reject!: (reason: Error) => void;
-  const promise = new Promise<T>((res, rej) => {
-    resolve = res;
-    reject = rej;
-  });
-  return { promise, resolve, reject };
-}
-
-/**
- * Federate Protocol Session
- *
- * Manages a session with an HLA 4 RTI using the Federate Protocol.
- *
- * @example
- * ```ts
- * const transport = new TlsTransport({ host: 'rti.example.com', port: 15165 });
- * const session = new Session(transport);
- *
- * session.addStateListener((oldState, newState, reason) => {
- *   console.log(`State: ${oldState} -> ${newState} (${reason})`);
- * });
- *
- * await session.start({
- *   onHlaCallbackRequest: (seqNum, callback) => {
- *     // Handle callback
- *     session.sendHlaCallbackResponse(seqNum, response);
- *   }
- * });
- *
- * // Send HLA calls
- * const response = await session.sendHlaCallRequest(encodedCall);
- *
- * // When done
- * await session.terminate();
- * ```
- */
-export class Session {
-  private readonly _transport: Transport;
-  private readonly _options: Required<SessionOptions>;
-
-  // Session state
-  private _state: SessionState = SessionState.NEW;
-  private _sessionId: bigint = NO_SESSION_ID;
-
-  // Sequence number tracking
-  private readonly _nextOutgoingSeqNum = new SequenceNumber(INITIAL_SEQUENCE_NUMBER);
-  private readonly _lastReceivedSeqNum = new AtomicSequenceNumber(NO_SEQUENCE_NUMBER);
-
-  // Request/response correlation
-  private readonly _pendingRequests = new Map<number, DeferredPromise<Uint8Array>>();
-  private _terminationDeferred: DeferredPromise<void> | null = null;
-
-  // Timers
-  private _sessionTimeoutTimer: TimeoutTimer | null = null;
-  private _connectionTimeoutTimer: TimeoutTimer | null = null;
-  private _heartbeatIntervalHandle: ReturnType<typeof setInterval> | null = null;
-
-  // Callbacks
-  private _hlaCallbackListener: HlaCallbackRequestListener | null = null;
-  private readonly _stateListeners: SessionStateListener[] = [];
-  private _messageSentListener: MessageSentListener | null = null;
-
-  // Message history for resumption
-  private readonly _sentMessageHistory: Map<number, Uint8Array> = new Map();
-  private _oldestHistorySeqNum: number = INITIAL_SEQUENCE_NUMBER;
-
-  /**
-   * Create a new session.
-   *
-   * @param transport - The transport to use for communication
-   * @param options - Session configuration options
-   */
-  constructor(transport: Transport, options: SessionOptions = {}) {
-    this._transport = transport;
-    this._options = { ...DEFAULT_SESSION_OPTIONS, ...options };
-  }
-
-  // ==========================================================================
-  // Public API
-  // ==========================================================================
-
-  /**
-   * Get the session ID (0 if not yet established)
-   */
-  get id(): bigint {
-    return this._sessionId;
-  }
-
-  /**
-   * Get the current session state
-   */
-  get state(): SessionState {
-    return this._state;
-  }
-
-  /**
-   * Check if the session is in a state where operations are allowed
-   */
-  get isOperational(): boolean {
-    return isOperationalState(this._state);
-  }
-
-  /**
-   * Add a state change listener
-   */
-  addStateListener(listener: SessionStateListener): void {
-    this._stateListeners.push(listener);
-  }
-
-  /**
-   * Set the message sent listener
-   */
-  setMessageSentListener(listener: MessageSentListener): void {
-    this._messageSentListener = listener;
-  }
-
-  /**
-   * Start the session by connecting to the RTI and establishing a new session.
-   *
-   * @param callbackListener - Handler for incoming HLA callbacks
-   * @throws SessionLostError if the connection cannot be established
-   * @throws SessionIllegalStateError if not in NEW state
-   */
-  async start(callbackListener: HlaCallbackRequestListener): Promise<void> {
-    // Validate state
-    const beforeState = this._compareAndSetState(
-      SessionState.NEW,
-      SessionState.STARTING,
-      "Starting session"
-    );
-
-    if (beforeState === SessionState.TERMINATED) {
-      throw new SessionAlreadyTerminatedError("Cannot start a terminated session");
-    }
-    if (beforeState !== SessionState.NEW) {
-      throw new SessionIllegalStateError(beforeState, "start");
-    }
-
-    this._hlaCallbackListener = callbackListener;
-
-    try {
-      await this._performConnect();
-    } catch (error) {
-      this._compareAndSetState(
-        SessionState.STARTING,
-        SessionState.TERMINATED,
-        `Connection failed: ${error}`
-      );
-      throw error;
-    }
-
-    // Start session timeout timer
-    this._sessionTimeoutTimer = TimeoutTimer.createLazy(this._options.responseTimeout);
-    this._sessionTimeoutTimer.start(() => this._handleSessionTimeout());
-
-    // Start periodic heartbeat sending
-    this._startHeartbeatTimer();
-
-    // Transition to running
-    this._compareAndSetState(SessionState.STARTING, SessionState.RUNNING, "Session established");
-  }
-
-  /**
-   * Resume a dropped session.
-   *
-   * @returns true if resume succeeded
-   * @throws SessionLostError if the server refuses to resume
-   * @throws SessionIllegalStateError if not in DROPPED state
-   */
-  async resume(): Promise<boolean> {
-    const beforeState = this._compareAndSetState(
-      SessionState.DROPPED,
-      SessionState.RESUMING,
-      "Attempting resume"
-    );
-
-    if (beforeState === SessionState.TERMINATED) {
-      throw new SessionAlreadyTerminatedError("Cannot resume a terminated session");
-    }
-    if (beforeState !== SessionState.DROPPED) {
-      throw new SessionIllegalStateError(beforeState, "resume");
-    }
-
-    try {
-      await this._performResume();
-      // Restart heartbeat timer after resume
-      this._startHeartbeatTimer();
-      this._compareAndSetState(SessionState.RESUMING, SessionState.RUNNING, "Session resumed");
-      return true;
-    } catch (error) {
-      if (error instanceof SessionLostError) {
-        this._compareAndSetState(
-          SessionState.RESUMING,
-          SessionState.TERMINATED,
-          `Resume failed: ${error.message}`
-        );
-        throw error;
-      }
-      // Network error - back to dropped state
-      this._compareAndSetState(
-        SessionState.RESUMING,
-        SessionState.DROPPED,
-        `Resume connection failed: ${error}`
-      );
-      throw error;
-    }
-  }
-
-  /**
-   * Send a heartbeat message.
-   *
-   * @returns Promise that resolves when the heartbeat response is received
-   * @throws SessionIllegalStateError if not in operational state
-   */
-  async sendHeartbeat(): Promise<void> {
-    this._validateOperationalState("send heartbeat");
-
-    const seqNum = this._nextOutgoingSeqNum.getAndIncrement();
-    const message = createHeartbeatMessage(
-      seqNum,
-      this._sessionId,
-      this._lastReceivedSeqNum.get()
-    );
-
-    const deferred = createDeferred<Uint8Array>();
-    this._pendingRequests.set(seqNum, deferred);
-
-    try {
-      await this._sendMessage(message, seqNum);
-      await deferred.promise;
-    } finally {
-      this._pendingRequests.delete(seqNum);
-    }
-  }
-
-  /**
-   * Send an HLA call request.
-   *
-   * @param encodedHlaCall - Protobuf-encoded HLA call request
-   * @returns Promise that resolves with the protobuf-encoded response
-   * @throws SessionIllegalStateError if not in operational state
-   */
-  async sendHlaCallRequest(encodedHlaCall: Uint8Array): Promise<Uint8Array> {
-    this._validateOperationalState("send HLA call");
-
-    const seqNum = this._nextOutgoingSeqNum.getAndIncrement();
-    const message = createHlaCallRequestMessage(
-      seqNum,
-      this._sessionId,
-      this._lastReceivedSeqNum.get(),
-      encodedHlaCall
-    );
-
-    const deferred = createDeferred<Uint8Array>();
-    this._pendingRequests.set(seqNum, deferred);
-
-    try {
-      await this._sendMessage(message, seqNum);
-      return await deferred.promise;
-    } catch (error) {
-      this._pendingRequests.delete(seqNum);
-      throw error;
-    }
-  }
-
-  /**
-   * Send an HLA callback response.
-   *
-   * @param responseToSequenceNumber - Sequence number of the callback request
-   * @param encodedResponse - Protobuf-encoded callback response
-   * @throws SessionIllegalStateError if not in operational state
-   */
-  async sendHlaCallbackResponse(
-    responseToSequenceNumber: number,
-    encodedResponse: Uint8Array
-  ): Promise<void> {
-    this._validateOperationalState("send callback response");
-
-    const seqNum = this._nextOutgoingSeqNum.getAndIncrement();
-    const message = createHlaCallbackResponseMessage(
-      seqNum,
-      this._sessionId,
-      this._lastReceivedSeqNum.get(),
-      responseToSequenceNumber,
-      encodedResponse
-    );
-
-    await this._sendMessage(message, seqNum);
-  }
-
-  /**
-   * Terminate the session gracefully.
-   *
-   * @param timeoutMs - Timeout for termination (default: responseTimeout)
-   * @throws SessionLostError if termination times out
-   * @throws SessionIllegalStateError if in invalid state
-   */
-  async terminate(timeoutMs?: number): Promise<void> {
-    const timeout = timeoutMs ?? this._options.responseTimeout;
-
-    // Wait if resuming
-    if (this._state === SessionState.RESUMING) {
-      await this._waitForStateChange();
-    }
-
-    // If already terminated, nothing to do
-    if (this._state === SessionState.TERMINATED) {
-      return;
-    }
-
-    const beforeState = this._compareAndSetState(
-      SessionState.RUNNING,
-      SessionState.TERMINATING,
-      "Terminating session"
-    );
-
-    // Handle DROPPED state
-    if (beforeState === SessionState.DROPPED) {
-      this._compareAndSetState(
-        SessionState.DROPPED,
-        SessionState.TERMINATED,
-        "Terminated dropped session"
-      );
-      return;
-    }
-
-    if (beforeState !== SessionState.RUNNING) {
-      throw new SessionIllegalStateError(beforeState, "terminate");
-    }
-
-    // Send termination message
-    this._terminationDeferred = createDeferred<void>();
-    const seqNum = this._nextOutgoingSeqNum.getAndIncrement();
-    const message = createTerminateSessionMessage(
-      seqNum,
-      this._sessionId,
-      this._lastReceivedSeqNum.get()
-    );
-
-    try {
-      await this._sendMessage(message, seqNum);
-
-      // Wait for termination response with timeout
-      const timeoutPromise = new Promise<never>((_, reject) => {
-        setTimeout(
-          () => reject(new SessionLostError("Termination timed out")),
-          timeout
-        );
-      });
-
-      await Promise.race([this._terminationDeferred.promise, timeoutPromise]);
-    } catch (error) {
-      // Session is terminated either way
-      throw error;
-    } finally {
-      this._compareAndSetState(
-        SessionState.TERMINATING,
-        SessionState.TERMINATED,
-        "Session terminated"
-      );
-      this._cleanup();
-    }
-  }
-
-  // ==========================================================================
-  // Connection and Session Establishment
-  // ==========================================================================
-
-  /**
-   * Perform the initial connection and session establishment
-   */
-  private async _performConnect(): Promise<void> {
-    // Set up transport handlers
-    this._transport.setEventHandlers({
-      onMessage: (msg) => this._handleMessage(msg),
-      onClose: (hadError) => this._handleDisconnect(hadError),
-      onError: (err) => this._handleTransportError(err),
-    });
-
-    // Connect with timeout
-    const connectionTimeout = this._options.connectionTimeout;
-    this._connectionTimeoutTimer = TimeoutTimer.createLazy(connectionTimeout);
-
-    let connectionPromise: Promise<void>;
-    const timeoutPromise = new Promise<never>((_, reject) => {
-      this._connectionTimeoutTimer!.start(() => {
-        reject(new ConnectionTimeoutError(connectionTimeout));
-      });
-    });
-
-    try {
-      // Connect to transport
-      connectionPromise = this._transport.connect();
-      await Promise.race([connectionPromise, timeoutPromise]);
-
-      // Send new session message
-      const newSessionMsg = createNewSessionMessage();
-      await this._transport.send(newSessionMsg);
-
-      // Wait for new session status response
-      const statusResponse = await this._waitForNewSessionStatus();
-      
-      if (statusResponse.status !== NewSessionStatus.SUCCESS) {
-        throw new SessionLostError(
-          `Server unable to create session, reason: ${statusResponse.status}`
-        );
-      }
-    } finally {
-      this._connectionTimeoutTimer?.cancel();
-      this._connectionTimeoutTimer = null;
-    }
-  }
-
-  /**
-   * Wait for the CTRL_NEW_SESSION_STATUS response
-   */
-  private _waitForNewSessionStatus(): Promise<{ status: number; sessionId: bigint }> {
-    return new Promise((resolve, reject) => {
-      const restoreHandlers = () => {
-        // Restore normal message handlers after handshake
-        this._transport.setEventHandlers({
-          onMessage: (msg) => this._handleMessage(msg),
-          onClose: (hadError) => this._handleDisconnect(hadError),
-          onError: (err) => this._handleTransportError(err),
-        });
-      };
-
-      const handleStatus = (msg: ReceivedMessage) => {
-        if (msg.header.messageType === MessageType.CTRL_NEW_SESSION_STATUS) {
-          const status = decodeNewSessionStatus(msg.payload);
-          this._sessionId = msg.header.sessionId;
-          this._extendSessionTimer();
-          restoreHandlers(); // Restore handlers before resolving
-          resolve({ status, sessionId: msg.header.sessionId });
-        } else {
-          restoreHandlers(); // Restore handlers before rejecting
-          reject(new BadMessageError(
-            `Expected CTRL_NEW_SESSION_STATUS, got ${MessageType[msg.header.messageType]}`
-          ));
-        }
-      };
-
-      // Temporarily replace handler for handshake
-      this._transport.setEventHandlers({
-        onMessage: handleStatus,
-        onClose: () => {
-          restoreHandlers();
-          reject(new SessionLostError("Connection closed during handshake"));
-        },
-        onError: (err) => {
-          restoreHandlers();
-          reject(new SessionLostError(`Transport error: ${err.message}`, err));
-        },
-      });
-    });
-  }
-
-  /**
-   * Perform session resumption
-   */
-  private async _performResume(): Promise<void> {
-    const lastReceivedRtiMessage = this._lastReceivedSeqNum.get();
-    const oldestAvailableFederateMessage = this._oldestHistorySeqNum;
-
-    // Reconnect transport
-    await this._transport.connect();
-
-    // Send resume request
-    const resumeMsg = createResumeRequestMessage(
-      this._sessionId,
-      lastReceivedRtiMessage,
-      oldestAvailableFederateMessage
-    );
-    await this._transport.send(resumeMsg);
-
-    // Resume session timer
-    this._sessionTimeoutTimer?.resume();
-
-    // Wait for resume status
-    const statusResponse = await this._waitForResumeStatus();
-
-    if (statusResponse.status !== ResumeStatusCode.OK_TO_RESUME) {
-      throw new SessionLostError(
-        `Server refused to resume session, status: ${statusResponse.status}`
-      );
-    }
-
-    // Retransmit messages that the server hasn't received
-    const resumeFromNumber = nextSequenceNumber(statusResponse.lastReceivedFederateSequenceNumber);
-    await this._retransmitMessages(resumeFromNumber);
-  }
-
-  /**
-   * Wait for CTRL_RESUME_STATUS response
-   */
-  private _waitForResumeStatus(): Promise<{ status: number; lastReceivedFederateSequenceNumber: number }> {
-    return new Promise((resolve, reject) => {
-      const restoreHandlers = () => {
-        // Restore normal message handlers after resume handshake
-        this._transport.setEventHandlers({
-          onMessage: (msg) => this._handleMessage(msg),
-          onClose: (hadError) => this._handleDisconnect(hadError),
-          onError: (err) => this._handleTransportError(err),
-        });
-      };
-
-      const handleStatus = (msg: ReceivedMessage) => {
-        if (msg.header.messageType === MessageType.CTRL_RESUME_STATUS) {
-          this._extendSessionTimer();
-          const result = decodeResumeStatus(msg.payload);
-          restoreHandlers(); // Restore handlers before resolving
-          resolve(result);
-        } else {
-          restoreHandlers(); // Restore handlers before rejecting
-          reject(new BadMessageError(
-            `Expected CTRL_RESUME_STATUS, got ${MessageType[msg.header.messageType]}`
-          ));
-        }
-      };
-
-      this._transport.setEventHandlers({
-        onMessage: handleStatus,
-        onClose: () => {
-          restoreHandlers();
-          reject(new SessionLostError("Connection closed during resume"));
-        },
-        onError: (err) => {
-          restoreHandlers();
-          reject(new SessionLostError(`Transport error: ${err.message}`, err));
-        },
-      });
-    });
-  }
-
-  /**
-   * Retransmit messages from the history
-   */
-  private async _retransmitMessages(fromSeqNum: number): Promise<void> {
-    if (!isValidSequenceNumber(fromSeqNum)) {
-      // Retransmit all
-      for (const [_, message] of this._sentMessageHistory) {
-        await this._transport.send(message);
-      }
-      return;
-    }
-
-    // Find and retransmit starting from the specified sequence number
-    for (const [seqNum, message] of this._sentMessageHistory) {
-      if (seqNum >= fromSeqNum) {
-        await this._transport.send(message);
-      }
-    }
-  }
-
-  // ==========================================================================
-  // Message Handling
-  // ==========================================================================
-
-  /**
-   * Handle an incoming message from the transport
-   */
-  private _handleMessage(msg: ReceivedMessage): void {
-    const { header, payload } = msg;
-
-    // Validate session ID (except for CTRL_NEW_SESSION_STATUS which sets it)
-    if (
-      header.messageType !== MessageType.CTRL_NEW_SESSION_STATUS &&
-      header.sessionId !== this._sessionId
-    ) {
-      this._handleBadMessage(`Wrong session ID: ${header.sessionId}, expected ${this._sessionId}`);
-      return;
-    }
-
-    // Validate sequence number for non-control messages
-    if (
-      header.messageType >= MessageType.HLA_CALL_REQUEST &&
-      !isValidSequenceNumber(header.sequenceNumber)
-    ) {
-      this._handleBadMessage(`Invalid sequence number: ${header.sequenceNumber}`);
-      return;
-    }
-
-    switch (header.messageType) {
-      case MessageType.CTRL_HEARTBEAT_RESPONSE:
-        this._handleHeartbeatResponse(payload);
-        break;
-
-      case MessageType.CTRL_SESSION_TERMINATED:
-        this._handleSessionTerminated();
-        break;
-
-      case MessageType.HLA_CALL_RESPONSE:
-        this._handleHlaCallResponse(header.sequenceNumber, payload);
-        break;
-
-      case MessageType.HLA_CALLBACK_REQUEST:
-        this._handleHlaCallbackRequest(header.sequenceNumber, payload);
-        break;
-
-      default:
-        this._handleBadMessage(`Unexpected message type: ${header.messageType}`);
-    }
-  }
-
-  /**
-   * Handle heartbeat response
-   */
-  private _handleHeartbeatResponse(payload: Uint8Array): void {
-    this._extendSessionTimer();
-    const responseToSeqNum = decodeHeartbeatResponse(payload);
-    const deferred = this._pendingRequests.get(responseToSeqNum);
-    if (deferred) {
-      this._pendingRequests.delete(responseToSeqNum);
-      deferred.resolve(new Uint8Array(0));
-    }
-  }
-
-  /**
-   * Handle session terminated message
-   */
-  private _handleSessionTerminated(): void {
-    this._extendSessionTimer();
-    if (this._terminationDeferred) {
-      this._terminationDeferred.resolve();
-      this._terminationDeferred = null;
-    }
-  }
-
-  /**
-   * Handle HLA call response
-   */
-  private _handleHlaCallResponse(sequenceNumber: number, payload: Uint8Array): void {
-    this._trackHlaMessageReceived(sequenceNumber);
-    const response = decodeHlaCallResponse(payload);
-    const deferred = this._pendingRequests.get(response.responseToSequenceNumber);
-    if (deferred) {
-      this._pendingRequests.delete(response.responseToSequenceNumber);
-      deferred.resolve(response.hlaServiceReturnValueOrException);
-    }
-  }
-
-  /**
-   * Handle HLA callback request
-   */
-  private _handleHlaCallbackRequest(sequenceNumber: number, payload: Uint8Array): void {
-    const callback = decodeHlaCallbackRequest(payload);
-    this._hlaCallbackListener?.onHlaCallbackRequest(
-      sequenceNumber,
-      callback.hlaServiceCallbackWithParams
-    );
-    this._trackHlaMessageReceived(sequenceNumber);
-  }
-
-  /**
-   * Handle a bad message
-   */
-  private _handleBadMessage(reason: string): void {
-    console.error(`[Session ${this._sessionId}] Bad message: ${reason}`);
-    
-    // Schedule best-effort termination
-    this.terminate(0).catch(() => {
-      // Ignore termination errors
-    });
-  }
-
-  /**
-   * Track that we received an HLA message
-   */
-  private _trackHlaMessageReceived(sequenceNumber: number): void {
-    this._extendSessionTimer();
-    if (isValidSequenceNumber(sequenceNumber)) {
-      this._lastReceivedSeqNum.set(sequenceNumber);
-    }
-  }
-
-  // ==========================================================================
-  // Transport Events
-  // ==========================================================================
-
-  /**
-   * Handle transport disconnection
-   */
-  private _handleDisconnect(hadError: boolean): void {
-    // If we're in TERMINATING state and get an EOF, complete the termination
-    if (this._state === SessionState.TERMINATING) {
-      this._terminationDeferred?.resolve();
-      return;
-    }
-
-    // Transition to DROPPED if running
-    const oldState = this._compareAndSetState(
-      SessionState.RUNNING,
-      SessionState.DROPPED,
-      hadError ? "Connection lost with error" : "Connection closed"
-    );
-
-    if (oldState === SessionState.RUNNING) {
-      this._sessionTimeoutTimer?.pause();
-      this._stopHeartbeatTimer();
-    }
-  }
-
-  /**
-   * Handle transport error
-   */
-  private _handleTransportError(error: Error): void {
-    console.error(`[Session ${this._sessionId}] Transport error:`, error);
-    this._handleDisconnect(true);
-  }
-
-  // ==========================================================================
-  // Timer Management
-  // ==========================================================================
-
-  /**
-   * Handle session timeout
-   */
-  private _handleSessionTimeout(): void {
-    console.error(
-      `[Session ${this._sessionId}] Session timed out after ${this._options.responseTimeout}ms`
-    );
-    this._transport.disconnect().catch(() => {
-      // Ignore disconnect errors
-    });
-  }
-
-  /**
-   * Extend the session timeout timer
-   */
-  private _extendSessionTimer(): void {
-    this._sessionTimeoutTimer?.extend();
-  }
-
-  /**
-   * Start the periodic heartbeat timer
-   */
-  private _startHeartbeatTimer(): void {
-    // Clear any existing timer
-    this._stopHeartbeatTimer();
-
-    // Only start if heartbeat interval is configured and > 0
-    if (this._options.heartbeatInterval <= 0) {
-      return;
-    }
-
-    // Send heartbeats at regular intervals
-    this._heartbeatIntervalHandle = setInterval(() => {
-      // Only send heartbeat if we're in an operational state
-      if (this.isOperational) {
-        this.sendHeartbeat().catch((error) => {
-          // Log but don't throw - heartbeat failures shouldn't crash the session
-          // The timeout timer will handle detecting if the connection is truly dead
-          console.error(`[Session ${this._sessionId}] Heartbeat failed:`, error);
-        });
-      }
-    }, this._options.heartbeatInterval);
-  }
-
-  /**
-   * Stop the periodic heartbeat timer
-   */
-  private _stopHeartbeatTimer(): void {
-    if (this._heartbeatIntervalHandle !== null) {
-      clearInterval(this._heartbeatIntervalHandle);
-      this._heartbeatIntervalHandle = null;
-    }
-  }
-
-  // ==========================================================================
-  // State Management
-  // ==========================================================================
-
-  /**
-   * Compare and set state atomically
-   */
-  private _compareAndSetState(
-    expectedState: SessionState,
-    newState: SessionState,
-    reason: string
-  ): SessionState {
-    const oldState = this._state;
-    if (oldState !== expectedState) {
-      return oldState;
-    }
-
-    if (!isValidTransition(oldState, newState)) {
-      console.warn(`Invalid state transition: ${oldState} -> ${newState}`);
-      return oldState;
-    }
-
-    this._state = newState;
-    this._fireStateTransition(oldState, newState, reason);
-
-    // Handle cleanup on terminal state
-    if (newState === SessionState.TERMINATED) {
-      this._cleanup();
-    }
-
-    return oldState;
-  }
-
-  /**
-   * Fire state transition to listeners
-   */
-  private _fireStateTransition(
-    oldState: SessionState,
-    newState: SessionState,
-    reason: string
-  ): void {
-    for (const listener of this._stateListeners) {
-      try {
-        listener.onStateTransition(oldState, newState, reason);
-      } catch (error) {
-        console.error("Error in state listener:", error);
-      }
-    }
-  }
-
-  /**
-   * Validate that we're in an operational state
-   */
-  private _validateOperationalState(operation: string): void {
-    if (this._state === SessionState.TERMINATED) {
-      throw new SessionAlreadyTerminatedError();
-    }
-    if (!isOperationalState(this._state)) {
-      throw new SessionIllegalStateError(this._state, operation);
-    }
-  }
-
-  /**
-   * Wait for a state change
-   */
-  private _waitForStateChange(): Promise<SessionState> {
-    return new Promise((resolve) => {
-      const listener: SessionStateListener = {
-        onStateTransition: (_, newState) => {
-          resolve(newState);
-        },
-      };
-      this._stateListeners.push(listener);
-    });
-  }
-
-  // ==========================================================================
-  // Utilities
-  // ==========================================================================
-
-  /**
-   * Send a message and store in history for potential retransmission
-   */
-  private async _sendMessage(message: Uint8Array, seqNum: number): Promise<void> {
-    // Store in history
-    this._sentMessageHistory.set(seqNum, message);
-    
-    // Trim old history entries if needed (keep last 1000)
-    const maxHistorySize = 1000;
-    if (this._sentMessageHistory.size > maxHistorySize) {
-      const oldestToKeep = seqNum - maxHistorySize;
-      for (const [histSeqNum] of this._sentMessageHistory) {
-        if (histSeqNum < oldestToKeep) {
-          this._sentMessageHistory.delete(histSeqNum);
-          this._oldestHistorySeqNum = Math.max(this._oldestHistorySeqNum, histSeqNum + 1);
-        }
-      }
-    }
-
-    await this._transport.send(message);
-    this._messageSentListener?.onMessageSent();
-  }
-
-  /**
-   * Clean up resources on termination
-   */
-  private _cleanup(): void {
-    // Stop heartbeat timer
-    this._stopHeartbeatTimer();
-
-    // Cancel timers
-    this._sessionTimeoutTimer?.cancel();
-    this._sessionTimeoutTimer = null;
-    this._connectionTimeoutTimer?.cancel();
-    this._connectionTimeoutTimer = null;
-
-    // Fail all pending requests
-    const error = new SessionLostError("Session terminated");
-    for (const [_, deferred] of this._pendingRequests) {
-      deferred.reject(error);
-    }
-    this._pendingRequests.clear();
-
-    // Clear history
-    this._sentMessageHistory.clear();
-
-    // Disconnect transport
-    this._transport.disconnect().catch(() => {
-      // Ignore disconnect errors
-    });
-  }
-
-}
+/**
+ * Federate Protocol Session
+ *
+ * Manages the lifecycle of a Federate Protocol session, including:
+ * - Connection establishment and termination
+ * - Session state machine
+ * - Request/response correlation
+ * - Heartbeat/keepalive
+ * - Session resumption after disconnection
+ */
+
+import {
+  type Transport,
+  type ReceivedMessage,
+  MessageType,
+  NO_SESSION_ID,
+  NewSessionStatus,
+} from "@hla4ts/transport";
+
+import {
+  SessionState,
+  isValidTransition,
+  isOperationalState,
+  type SessionOptions,
+  type HlaCallbackRequestListener,
+  type SessionStateListener,
+  type MessageSentListener,
+  DEFAULT_SESSION_OPTIONS,
+} from "./types.ts";
+
+import {
+  SequenceNumber,
+  AtomicSequenceNumber,
+  INITIAL_SEQUENCE_NUMBER,
+  NO_SEQUENCE_NUMBER,
+  isValidSequenceNumber,
+  nextSequenceNumber,
+} from "./sequence-number.ts";
+
+import { TimeoutTimer } from "./timeout-timer.ts";
+
+import {
+  createNewSessionMessage,
+  decodeNewSessionStatus,
+  createResumeRequestMessage,
+  decodeResumeStatus,
+  ResumeStatusCode,
+  createHeartbeatMessage,
+  decodeHeartbeatResponse,
+  createTerminateSessionMessage,
+  createHlaCallRequestMessage,
+  decodeHlaCallResponse,
+  decodeHlaCallbackRequest,
+  createHlaCallbackResponseMessage,
+} from "./messages.ts";
+
+import {
+  SessionLostError,
+  SessionAlreadyTerminatedError,
+  SessionIllegalStateError,
+  BadMessageError,
+  ConnectionTimeoutError,
+} from "./errors.ts";
+
+/**
+ * Deferred promise helper for request/response correlation
+ */
+interface DeferredPromise<T> {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason: Error) => void;
+}
+
+function createDeferred<T>(): DeferredPromise<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (reason: Error) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+/**
+ * Federate Protocol Session
+ *
+ * Manages a session with an HLA 4 RTI using the Federate Protocol.
+ *
+ * @example
+ * ```ts
+ * const transport = new TlsTransport({ host: 'rti.example.com', port: 15165 });
+ * const session = new Session(transport);
+ *
+ * session.addStateListener((oldState, newState, reason) => {
+ *   console.log(`State: ${oldState} -> ${newState} (${reason})`);
+ * });
+ *
+ * await session.start({
+ *   onHlaCallbackRequest: (seqNum, callback) => {
+ *     // Handle callback
+ *     session.sendHlaCallbackResponse(seqNum, response);
+ *   }
+ * });
+ *
+ * // Send HLA calls
+ * const response = await session.sendHlaCallRequest(encodedCall);
+ *
+ * // When done
+ * await session.terminate();
+ * ```
+ */
+export class Session {
+  private readonly _transport: Transport;
+  private readonly _options: Required<SessionOptions>;
+
+  // Session state
+  private _state: SessionState = SessionState.NEW;
+  private _sessionId: bigint = NO_SESSION_ID;
+
+  // Sequence number tracking
+  private readonly _nextOutgoingSeqNum = new SequenceNumber(INITIAL_SEQUENCE_NUMBER);
+  private readonly _lastReceivedSeqNum = new AtomicSequenceNumber(NO_SEQUENCE_NUMBER);
+
+  // Request/response correlation
+  private readonly _pendingRequests = new Map<number, DeferredPromise<Uint8Array>>();
+  private _terminationDeferred: DeferredPromise<void> | null = null;
+
+  // Timers
+  private _sessionTimeoutTimer: TimeoutTimer | null = null;
+  private _connectionTimeoutTimer: TimeoutTimer | null = null;
+  private _heartbeatIntervalHandle: ReturnType<typeof setInterval> | null = null;
+
+  // Callbacks
+  private _hlaCallbackListener: HlaCallbackRequestListener | null = null;
+  private readonly _stateListeners: SessionStateListener[] = [];
+  private _messageSentListener: MessageSentListener | null = null;
+
+  // Message history for resumption
+  private readonly _sentMessageHistory: Map<number, Uint8Array> = new Map();
+  private _oldestHistorySeqNum: number = INITIAL_SEQUENCE_NUMBER;
+
+  /**
+   * Create a new session.
+   *
+   * @param transport - The transport to use for communication
+   * @param options - Session configuration options
+   */
+  constructor(transport: Transport, options: SessionOptions = {}) {
+    this._transport = transport;
+    this._options = { ...DEFAULT_SESSION_OPTIONS, ...options };
+  }
+
+  // ==========================================================================
+  // Public API
+  // ==========================================================================
+
+  /**
+   * Get the session ID (0 if not yet established)
+   */
+  get id(): bigint {
+    return this._sessionId;
+  }
+
+  /**
+   * Get the current session state
+   */
+  get state(): SessionState {
+    return this._state;
+  }
+
+  /**
+   * Check if the session is in a state where operations are allowed
+   */
+  get isOperational(): boolean {
+    return isOperationalState(this._state);
+  }
+
+  /**
+   * Add a state change listener
+   */
+  addStateListener(listener: SessionStateListener): void {
+    this._stateListeners.push(listener);
+  }
+
+  /**
+   * Set the message sent listener
+   */
+  setMessageSentListener(listener: MessageSentListener): void {
+    this._messageSentListener = listener;
+  }
+
+  /**
+   * Start the session by connecting to the RTI and establishing a new session.
+   *
+   * @param callbackListener - Handler for incoming HLA callbacks
+   * @throws SessionLostError if the connection cannot be established
+   * @throws SessionIllegalStateError if not in NEW state
+   */
+  async start(callbackListener: HlaCallbackRequestListener): Promise<void> {
+    // Validate state
+    const beforeState = this._compareAndSetState(
+      SessionState.NEW,
+      SessionState.STARTING,
+      "Starting session"
+    );
+
+    if (beforeState === SessionState.TERMINATED) {
+      throw new SessionAlreadyTerminatedError("Cannot start a terminated session");
+    }
+    if (beforeState !== SessionState.NEW) {
+      throw new SessionIllegalStateError(beforeState, "start");
+    }
+
+    this._hlaCallbackListener = callbackListener;
+
+    try {
+      await this._performConnect();
+    } catch (error) {
+      this._compareAndSetState(
+        SessionState.STARTING,
+        SessionState.TERMINATED,
+        `Connection failed: ${error}`
+      );
+      throw error;
+    }
+
+    // Start session timeout timer
+    this._sessionTimeoutTimer = TimeoutTimer.createLazy(this._options.responseTimeout);
+    this._sessionTimeoutTimer.start(() => this._handleSessionTimeout());
+
+    // Start periodic heartbeat sending
+    this._startHeartbeatTimer();
+
+    // Transition to running
+    this._compareAndSetState(SessionState.STARTING, SessionState.RUNNING, "Session established");
+  }
+
+  /**
+   * Resume a dropped session.
+   *
+   * @returns true if resume succeeded
+   * @throws SessionLostError if the server refuses to resume
+   * @throws SessionIllegalStateError if not in DROPPED state
+   */
+  async resume(): Promise<boolean> {
+    const beforeState = this._compareAndSetState(
+      SessionState.DROPPED,
+      SessionState.RESUMING,
+      "Attempting resume"
+    );
+
+    if (beforeState === SessionState.TERMINATED) {
+      throw new SessionAlreadyTerminatedError("Cannot resume a terminated session");
+    }
+    if (beforeState !== SessionState.DROPPED) {
+      throw new SessionIllegalStateError(beforeState, "resume");
+    }
+
+    try {
+      await this._performResume();
+      // Restart heartbeat timer after resume
+      this._startHeartbeatTimer();
+      this._compareAndSetState(SessionState.RESUMING, SessionState.RUNNING, "Session resumed");
+      return true;
+    } catch (error) {
+      if (error instanceof SessionLostError) {
+        this._compareAndSetState(
+          SessionState.RESUMING,
+          SessionState.TERMINATED,
+          `Resume failed: ${error.message}`
+        );
+        throw error;
+      }
+      // Network error - back to dropped state
+      this._compareAndSetState(
+        SessionState.RESUMING,
+        SessionState.DROPPED,
+        `Resume connection failed: ${error}`
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Send a heartbeat message.
+   *
+   * @returns Promise that resolves when the heartbeat response is received
+   * @throws SessionIllegalStateError if not in operational state
+   */
+  async sendHeartbeat(): Promise<void> {
+    this._validateOperationalState("send heartbeat");
+
+    const seqNum = this._nextOutgoingSeqNum.getAndIncrement();
+    const message = createHeartbeatMessage(
+      seqNum,
+      this._sessionId,
+      this._lastReceivedSeqNum.get()
+    );
+
+    const deferred = createDeferred<Uint8Array>();
+    this._pendingRequests.set(seqNum, deferred);
+
+    try {
+      await this._sendMessage(message, seqNum);
+      await deferred.promise;
+    } finally {
+      this._pendingRequests.delete(seqNum);
+    }
+  }
+
+  /**
+   * Send an HLA call request.
+   *
+   * @param encodedHlaCall - Protobuf-encoded HLA call request
+   * @returns Promise that resolves with the protobuf-encoded response
+   * @throws SessionIllegalStateError if not in operational state
+   */
+  async sendHlaCallRequest(encodedHlaCall: Uint8Array): Promise<Uint8Array> {
+    this._validateOperationalState("send HLA call");
+
+    const seqNum = this._nextOutgoingSeqNum.getAndIncrement();
+    const message = createHlaCallRequestMessage(
+      seqNum,
+      this._sessionId,
+      this._lastReceivedSeqNum.get(),
+      encodedHlaCall
+    );
+
+    const deferred = createDeferred<Uint8Array>();
+    this._pendingRequests.set(seqNum, deferred);
+
+    try {
+      await this._sendMessage(message, seqNum);
+      return await deferred.promise;
+    } catch (error) {
+      this._pendingRequests.delete(seqNum);
+      throw error;
+    }
+  }
+
+  /**
+   * Send an HLA callback response.
+   *
+   * @param responseToSequenceNumber - Sequence number of the callback request
+   * @param encodedResponse - Protobuf-encoded callback response
+   * @throws SessionIllegalStateError if not in operational state
+   */
+  async sendHlaCallbackResponse(
+    responseToSequenceNumber: number,
+    encodedResponse: Uint8Array
+  ): Promise<void> {
+    this._validateOperationalState("send callback response");
+
+    const seqNum = this._nextOutgoingSeqNum.getAndIncrement();
+    const message = createHlaCallbackResponseMessage(
+      seqNum,
+      this._sessionId,
+      this._lastReceivedSeqNum.get(),
+      responseToSequenceNumber,
+      encodedResponse
+    );
+
+    await this._sendMessage(message, seqNum);
+  }
+
+  /**
+   * Terminate the session gracefully.
+   *
+   * @param timeoutMs - Timeout for termination (default: responseTimeout)
+   * @throws SessionLostError if termination times out
+   * @throws SessionIllegalStateError if in invalid state
+   */
+  async terminate(timeoutMs?: number): Promise<void> {
+    const timeout = timeoutMs ?? this._options.responseTimeout;
+
+    // Wait if resuming
+    if (this._state === SessionState.RESUMING) {
+      await this._waitForStateChange();
+    }
+
+    // If already terminated, nothing to do
+    if (this._state === SessionState.TERMINATED) {
+      return;
+    }
+
+    const beforeState = this._compareAndSetState(
+      SessionState.RUNNING,
+      SessionState.TERMINATING,
+      "Terminating session"
+    );
+
+    // Handle DROPPED state
+    if (beforeState === SessionState.DROPPED) {
+      this._compareAndSetState(
+        SessionState.DROPPED,
+        SessionState.TERMINATED,
+        "Terminated dropped session"
+      );
+      return;
+    }
+
+    if (beforeState !== SessionState.RUNNING) {
+      throw new SessionIllegalStateError(beforeState, "terminate");
+    }
+
+    // Send termination message
+    this._terminationDeferred = createDeferred<void>();
+    const seqNum = this._nextOutgoingSeqNum.getAndIncrement();
+    const message = createTerminateSessionMessage(
+      seqNum,
+      this._sessionId,
+      this._lastReceivedSeqNum.get()
+    );
+
+    try {
+      await this._sendMessage(message, seqNum);
+
+      // Wait for termination response with timeout
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(
+          () => reject(new SessionLostError("Termination timed out")),
+          timeout
+        );
+      });
+
+      await Promise.race([this._terminationDeferred.promise, timeoutPromise]);
+    } catch (error) {
+      // Session is terminated either way
+      throw error;
+    } finally {
+      this._compareAndSetState(
+        SessionState.TERMINATING,
+        SessionState.TERMINATED,
+        "Session terminated"
+      );
+      this._cleanup();
+    }
+  }
+
+  // ==========================================================================
+  // Connection and Session Establishment
+  // ==========================================================================
+
+  /**
+   * Perform the initial connection and session establishment
+   */
+  private async _performConnect(): Promise<void> {
+    // Set up transport handlers
+    this._transport.setEventHandlers({
+      onMessage: (msg) => this._handleMessage(msg),
+      onClose: (hadError) => this._handleDisconnect(hadError),
+      onError: (err) => this._handleTransportError(err),
+    });
+
+    // Connect with timeout
+    const connectionTimeout = this._options.connectionTimeout;
+    this._connectionTimeoutTimer = TimeoutTimer.createLazy(connectionTimeout);
+
+    let connectionPromise: Promise<void>;
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      this._connectionTimeoutTimer!.start(() => {
+        reject(new ConnectionTimeoutError(connectionTimeout));
+      });
+    });
+
+    try {
+      // Connect to transport
+      connectionPromise = this._transport.connect();
+      await Promise.race([connectionPromise, timeoutPromise]);
+
+      // Send new session message
+      const newSessionMsg = createNewSessionMessage();
+      await this._transport.send(newSessionMsg);
+
+      // Wait for new session status response
+      const statusResponse = await this._waitForNewSessionStatus();
+      
+      if (statusResponse.status !== NewSessionStatus.SUCCESS) {
+        throw new SessionLostError(
+          `Server unable to create session, reason: ${statusResponse.status}`
+        );
+      }
+    } finally {
+      this._connectionTimeoutTimer?.cancel();
+      this._connectionTimeoutTimer = null;
+    }
+  }
+
+  /**
+   * Wait for the CTRL_NEW_SESSION_STATUS response
+   */
+  private _waitForNewSessionStatus(): Promise<{ status: number; sessionId: bigint }> {
+    return new Promise((resolve, reject) => {
+      const restoreHandlers = () => {
+        // Restore normal message handlers after handshake
+        this._transport.setEventHandlers({
+          onMessage: (msg) => this._handleMessage(msg),
+          onClose: (hadError) => this._handleDisconnect(hadError),
+          onError: (err) => this._handleTransportError(err),
+        });
+      };
+
+      const handleStatus = (msg: ReceivedMessage) => {
+        if (msg.header.messageType === MessageType.CTRL_NEW_SESSION_STATUS) {
+          const status = decodeNewSessionStatus(msg.payload);
+          this._sessionId = msg.header.sessionId;
+          this._extendSessionTimer();
+          restoreHandlers(); // Restore handlers before resolving
+          resolve({ status, sessionId: msg.header.sessionId });
+        } else {
+          restoreHandlers(); // Restore handlers before rejecting
+          reject(new BadMessageError(
+            `Expected CTRL_NEW_SESSION_STATUS, got ${MessageType[msg.header.messageType]}`
+          ));
+        }
+      };
+
+      // Temporarily replace handler for handshake
+      this._transport.setEventHandlers({
+        onMessage: handleStatus,
+        onClose: () => {
+          restoreHandlers();
+          reject(new SessionLostError("Connection closed during handshake"));
+        },
+        onError: (err) => {
+          restoreHandlers();
+          reject(new SessionLostError(`Transport error: ${err.message}`, err));
+        },
+      });
+    });
+  }
+
+  /**
+   * Perform session resumption
+   */
+  private async _performResume(): Promise<void> {
+    const lastReceivedRtiMessage = this._lastReceivedSeqNum.get();
+    const oldestAvailableFederateMessage = this._oldestHistorySeqNum;
+
+    // Reconnect transport
+    await this._transport.connect();
+
+    // Send resume request
+    const resumeMsg = createResumeRequestMessage(
+      this._sessionId,
+      lastReceivedRtiMessage,
+      oldestAvailableFederateMessage
+    );
+    await this._transport.send(resumeMsg);
+
+    // Resume session timer
+    this._sessionTimeoutTimer?.resume();
+
+    // Wait for resume status
+    const statusResponse = await this._waitForResumeStatus();
+
+    if (statusResponse.status !== ResumeStatusCode.OK_TO_RESUME) {
+      throw new SessionLostError(
+        `Server refused to resume session, status: ${statusResponse.status}`
+      );
+    }
+
+    // Retransmit messages that the server hasn't received
+    const resumeFromNumber = nextSequenceNumber(statusResponse.lastReceivedFederateSequenceNumber);
+    await this._retransmitMessages(resumeFromNumber);
+  }
+
+  /**
+   * Wait for CTRL_RESUME_STATUS response
+   */
+  private _waitForResumeStatus(): Promise<{ status: number; lastReceivedFederateSequenceNumber: number }> {
+    return new Promise((resolve, reject) => {
+      const restoreHandlers = () => {
+        // Restore normal message handlers after resume handshake
+        this._transport.setEventHandlers({
+          onMessage: (msg) => this._handleMessage(msg),
+          onClose: (hadError) => this._handleDisconnect(hadError),
+          onError: (err) => this._handleTransportError(err),
+        });
+      };
+
+      const handleStatus = (msg: ReceivedMessage) => {
+        if (msg.header.messageType === MessageType.CTRL_RESUME_STATUS) {
+          this._extendSessionTimer();
+          const result = decodeResumeStatus(msg.payload);
+          restoreHandlers(); // Restore handlers before resolving
+          resolve(result);
+        } else {
+          restoreHandlers(); // Restore handlers before rejecting
+          reject(new BadMessageError(
+            `Expected CTRL_RESUME_STATUS, got ${MessageType[msg.header.messageType]}`
+          ));
+        }
+      };
+
+      this._transport.setEventHandlers({
+        onMessage: handleStatus,
+        onClose: () => {
+          restoreHandlers();
+          reject(new SessionLostError("Connection closed during resume"));
+        },
+        onError: (err) => {
+          restoreHandlers();
+          reject(new SessionLostError(`Transport error: ${err.message}`, err));
+        },
+      });
+    });
+  }
+
+  /**
+   * Retransmit messages from the history
+   */
+  private async _retransmitMessages(fromSeqNum: number): Promise<void> {
+    if (!isValidSequenceNumber(fromSeqNum)) {
+      // Retransmit all
+      for (const [_, message] of this._sentMessageHistory) {
+        await this._transport.send(message);
+      }
+      return;
+    }
+
+    // Find and retransmit starting from the specified sequence number
+    for (const [seqNum, message] of this._sentMessageHistory) {
+      if (seqNum >= fromSeqNum) {
+        await this._transport.send(message);
+      }
+    }
+  }
+
+  // ==========================================================================
+  // Message Handling
+  // ==========================================================================
+
+  /**
+   * Handle an incoming message from the transport
+   */
+  private _handleMessage(msg: ReceivedMessage): void {
+    const { header, payload } = msg;
+
+    // Validate session ID (except for CTRL_NEW_SESSION_STATUS which sets it)
+    if (
+      header.messageType !== MessageType.CTRL_NEW_SESSION_STATUS &&
+      header.sessionId !== this._sessionId
+    ) {
+      this._handleBadMessage(`Wrong session ID: ${header.sessionId}, expected ${this._sessionId}`);
+      return;
+    }
+
+    // Validate sequence number for non-control messages
+    if (
+      header.messageType >= MessageType.HLA_CALL_REQUEST &&
+      !isValidSequenceNumber(header.sequenceNumber)
+    ) {
+      this._handleBadMessage(`Invalid sequence number: ${header.sequenceNumber}`);
+      return;
+    }
+
+    switch (header.messageType) {
+      case MessageType.CTRL_HEARTBEAT_RESPONSE:
+        this._handleHeartbeatResponse(payload);
+        break;
+
+      case MessageType.CTRL_SESSION_TERMINATED:
+        this._handleSessionTerminated();
+        break;
+
+      case MessageType.HLA_CALL_RESPONSE:
+        this._handleHlaCallResponse(header.sequenceNumber, payload);
+        break;
+
+      case MessageType.HLA_CALLBACK_REQUEST:
+        this._handleHlaCallbackRequest(header.sequenceNumber, payload);
+        break;
+
+      default:
+        this._handleBadMessage(`Unexpected message type: ${header.messageType}`);
+    }
+  }
+
+  /**
+   * Handle heartbeat response
+   */
+  private _handleHeartbeatResponse(payload: Uint8Array): void {
+    this._extendSessionTimer();
+    const responseToSeqNum = decodeHeartbeatResponse(payload);
+    const deferred = this._pendingRequests.get(responseToSeqNum);
+    if (deferred) {
+      this._pendingRequests.delete(responseToSeqNum);
+      deferred.resolve(new Uint8Array(0));
+    }
+  }
+
+  /**
+   * Handle session terminated message
+   */
+  private _handleSessionTerminated(): void {
+    this._extendSessionTimer();
+    if (this._terminationDeferred) {
+      this._terminationDeferred.resolve();
+      this._terminationDeferred = null;
+    }
+  }
+
+  /**
+   * Handle HLA call response
+   */
+  private _handleHlaCallResponse(sequenceNumber: number, payload: Uint8Array): void {
+    this._trackHlaMessageReceived(sequenceNumber);
+    const response = decodeHlaCallResponse(payload);
+    const deferred = this._pendingRequests.get(response.responseToSequenceNumber);
+    if (deferred) {
+      this._pendingRequests.delete(response.responseToSequenceNumber);
+      deferred.resolve(response.hlaServiceReturnValueOrException);
+    }
+  }
+
+  /**
+   * Handle HLA callback request
+   */
+  private _handleHlaCallbackRequest(sequenceNumber: number, payload: Uint8Array): void {
+    const callback = decodeHlaCallbackRequest(payload);
+    this._hlaCallbackListener?.onHlaCallbackRequest(
+      sequenceNumber,
+      callback.hlaServiceCallbackWithParams
+    );
+    this._trackHlaMessageReceived(sequenceNumber);
+  }
+
+  /**
+   * Handle a bad message
+   */
+  private _handleBadMessage(reason: string): void {
+    console.error(`[Session ${this._sessionId}] Bad message: ${reason}`);
+    
+    // Schedule best-effort termination
+    this.terminate(0).catch(() => {
+      // Ignore termination errors
+    });
+  }
+
+  /**
+   * Track that we received an HLA message
+   */
+  private _trackHlaMessageReceived(sequenceNumber: number): void {
+    this._extendSessionTimer();
+    if (isValidSequenceNumber(sequenceNumber)) {
+      this._lastReceivedSeqNum.set(sequenceNumber);
+    }
+  }
+
+  // ==========================================================================
+  // Transport Events
+  // ==========================================================================
+
+  /**
+   * Handle transport disconnection
+   */
+  private _handleDisconnect(hadError: boolean): void {
+    // If we're in TERMINATING state and get an EOF, complete the termination
+    if (this._state === SessionState.TERMINATING) {
+      this._terminationDeferred?.resolve();
+      return;
+    }
+
+    // Transition to DROPPED if running
+    const oldState = this._compareAndSetState(
+      SessionState.RUNNING,
+      SessionState.DROPPED,
+      hadError ? "Connection lost with error" : "Connection closed"
+    );
+
+    if (oldState === SessionState.RUNNING) {
+      this._sessionTimeoutTimer?.pause();
+      this._stopHeartbeatTimer();
+    }
+  }
+
+  /**
+   * Handle transport error
+   */
+  private _handleTransportError(error: Error): void {
+    console.error(`[Session ${this._sessionId}] Transport error:`, error);
+    this._handleDisconnect(true);
+  }
+
+  // ==========================================================================
+  // Timer Management
+  // ==========================================================================
+
+  /**
+   * Handle session timeout
+   */
+  private _handleSessionTimeout(): void {
+    console.error(
+      `[Session ${this._sessionId}] Session timed out after ${this._options.responseTimeout}ms`
+    );
+    this._transport.disconnect().catch(() => {
+      // Ignore disconnect errors
+    });
+  }
+
+  /**
+   * Extend the session timeout timer
+   */
+  private _extendSessionTimer(): void {
+    this._sessionTimeoutTimer?.extend();
+  }
+
+  /**
+   * Start the periodic heartbeat timer
+   */
+  private _startHeartbeatTimer(): void {
+    // Clear any existing timer
+    this._stopHeartbeatTimer();
+
+    // Only start if heartbeat interval is configured and > 0
+    if (this._options.heartbeatInterval <= 0) {
+      return;
+    }
+
+    // Send heartbeats at regular intervals
+    this._heartbeatIntervalHandle = setInterval(() => {
+      // Only send heartbeat if we're in an operational state
+      if (this.isOperational) {
+        this.sendHeartbeat().catch((error) => {
+          // Log but don't throw - heartbeat failures shouldn't crash the session
+          // The timeout timer will handle detecting if the connection is truly dead
+          console.error(`[Session ${this._sessionId}] Heartbeat failed:`, error);
+        });
+      }
+    }, this._options.heartbeatInterval);
+  }
+
+  /**
+   * Stop the periodic heartbeat timer
+   */
+  private _stopHeartbeatTimer(): void {
+    if (this._heartbeatIntervalHandle !== null) {
+      clearInterval(this._heartbeatIntervalHandle);
+      this._heartbeatIntervalHandle = null;
+    }
+  }
+
+  // ==========================================================================
+  // State Management
+  // ==========================================================================
+
+  /**
+   * Compare and set state atomically
+   */
+  private _compareAndSetState(
+    expectedState: SessionState,
+    newState: SessionState,
+    reason: string
+  ): SessionState {
+    const oldState = this._state;
+    if (oldState !== expectedState) {
+      return oldState;
+    }
+
+    if (!isValidTransition(oldState, newState)) {
+      console.warn(`Invalid state transition: ${oldState} -> ${newState}`);
+      return oldState;
+    }
+
+    this._state = newState;
+    this._fireStateTransition(oldState, newState, reason);
+
+    // Handle cleanup on terminal state
+    if (newState === SessionState.TERMINATED) {
+      this._cleanup();
+    }
+
+    return oldState;
+  }
+
+  /**
+   * Fire state transition to listeners
+   */
+  private _fireStateTransition(
+    oldState: SessionState,
+    newState: SessionState,
+    reason: string
+  ): void {
+    for (const listener of this._stateListeners) {
+      try {
+        listener.onStateTransition(oldState, newState, reason);
+      } catch (error) {
+        console.error("Error in state listener:", error);
+      }
+    }
+  }
+
+  /**
+   * Validate that we're in an operational state
+   */
+  private _validateOperationalState(operation: string): void {
+    if (this._state === SessionState.TERMINATED) {
+      throw new SessionAlreadyTerminatedError();
+    }
+    if (!isOperationalState(this._state)) {
+      throw new SessionIllegalStateError(this._state, operation);
+    }
+  }
+
+  /**
+   * Wait for a state change
+   */
+  private _waitForStateChange(): Promise<SessionState> {
+    return new Promise((resolve) => {
+      const listener: SessionStateListener = {
+        onStateTransition: (_, newState) => {
+          resolve(newState);
+        },
+      };
+      this._stateListeners.push(listener);
+    });
+  }
+
+  // ==========================================================================
+  // Utilities
+  // ==========================================================================
+
+  /**
+   * Send a message and store in history for potential retransmission
+   */
+  private async _sendMessage(message: Uint8Array, seqNum: number): Promise<void> {
+    // Store in history
+    this._sentMessageHistory.set(seqNum, message);
+    
+    // Trim old history entries if needed (keep last 1000)
+    const maxHistorySize = 1000;
+    if (this._sentMessageHistory.size > maxHistorySize) {
+      const oldestToKeep = seqNum - maxHistorySize;
+      for (const [histSeqNum] of this._sentMessageHistory) {
+        if (histSeqNum < oldestToKeep) {
+          this._sentMessageHistory.delete(histSeqNum);
+          this._oldestHistorySeqNum = Math.max(this._oldestHistorySeqNum, histSeqNum + 1);
+        }
+      }
+    }
+
+    await this._transport.send(message);
+    this._messageSentListener?.onMessageSent();
+  }
+
+  /**
+   * Clean up resources on termination
+   */
+  private _cleanup(): void {
+    // Stop heartbeat timer
+    this._stopHeartbeatTimer();
+
+    // Cancel timers
+    this._sessionTimeoutTimer?.cancel();
+    this._sessionTimeoutTimer = null;
+    this._connectionTimeoutTimer?.cancel();
+    this._connectionTimeoutTimer = null;
+
+    // Fail all pending requests
+    const error = new SessionLostError("Session terminated");
+    for (const [_, deferred] of this._pendingRequests) {
+      deferred.reject(error);
+    }
+    this._pendingRequests.clear();
+
+    // Clear history
+    this._sentMessageHistory.clear();
+
+    // Disconnect transport
+    this._transport.disconnect().catch(() => {
+      // Ignore disconnect errors
+    });
+  }
+
+}