@hla4ts/hla-api 0.1.0

package/src/rti-ambassador.ts

@@ -0,0 +1,1441 @@
+/**
+ * RTI Ambassador
+ *
+ * This module provides the high-level HLA 4 RTI Ambassador API for TypeScript.
+ * The RTI Ambassador is the main interface for federates to interact with the RTI.
+ */
+
+import { Session, type HlaCallbackRequestListener } from "@hla4ts/session";
+import { type Transport, TlsTransport, TcpTransport } from "@hla4ts/transport";
+import {
+  CallRequestCodec,
+  CallResponseCodec,
+  type CallRequest,
+  type CallResponse,
+  ResignAction,
+} from "@hla4ts/proto";
+
+import type { FederateAmbassador } from "./federate-ambassador.ts";
+import { CallbackDispatcher } from "./callback-dispatcher.ts";
+import {
+  NotConnected,
+  AlreadyConnected,
+  createExceptionFromProto,
+  CallNotAllowedFromWithinCallback,
+} from "./exceptions.ts";
+import {
+  convertJoinResult,
+  convertObjectInstanceHandle,
+  convertConfigurationResult,
+  convertLogicalTime,
+  convertLogicalTimeInterval,
+  convertTimeQueryReturn,
+  toProtoObjectClassHandle,
+  toProtoAttributeHandleSet,
+  toProtoInteractionClassHandle,
+  toProtoObjectInstanceHandle,
+  toProtoAttributeHandleValueMap,
+  toProtoParameterHandleValueMap,
+  toProtoLogicalTime,
+  toProtoLogicalTimeInterval,
+  toProtoFederateHandleSet,
+  toProtoRtiConfiguration,
+  toProtoCredentials,
+  toProtoFomModule,
+  toProtoFomModuleSet,
+} from "./converters.ts";
+import type {
+  ObjectClassHandle,
+  AttributeHandleSet,
+  InteractionClassHandle,
+  ObjectInstanceHandle,
+  AttributeHandleValueMap,
+  ParameterHandleValueMap,
+  UserSuppliedTag,
+  LogicalTime,
+  LogicalTimeInterval,
+  MessageRetractionReturn,
+  TimeQueryReturn,
+  JoinResult,
+  FederateHandleSet,
+  FomModule,
+  FomModuleSet,
+  ConfigurationResult,
+  ConnectionOptions,
+} from "./types.ts";
+
+// =============================================================================
+// RTI Ambassador Options
+// =============================================================================
+
+/**
+ * Options for creating an RTI Ambassador.
+ */
+export interface RTIAmbassadorOptions {
+  /** RTI host address */
+  host: string;
+
+  /** RTI port (default: 15165 for TLS, 15164 for TCP) */
+  port?: number;
+
+  /** Use TLS (default: true) */
+  useTls?: boolean;
+
+  /** Connection timeout in milliseconds (default: 30000) */
+  connectionTimeout?: number;
+
+  /** Response timeout in milliseconds (default: 180000) */
+  responseTimeout?: number;
+
+  /** TLS options (certificate paths, etc.) */
+  tlsOptions?: {
+    /** Path to CA certificate file */
+    ca?: string;
+    /** Path to client certificate file */
+    cert?: string;
+    /** Path to client private key file */
+    key?: string;
+    /** Skip server verification (INSECURE) */
+    rejectUnauthorized?: boolean;
+  };
+}
+
+// =============================================================================
+// RTI Ambassador
+// =============================================================================
+
+/**
+ * RTI Ambassador - Main interface for federate-to-RTI communication.
+ *
+ * The RTI Ambassador provides methods for all HLA services:
+ * - Federation Management (create, join, resign, destroy)
+ * - Declaration Management (publish, subscribe)
+ * - Object Management (register, update, delete, interactions)
+ * - Time Management (constrained, regulation, advance)
+ * - Ownership Management (acquire, divest)
+ * - Support Services (handle/name lookups)
+ *
+ * @example
+ * ```ts
+ * import { RTIAmbassador, BaseFederateAmbassador, CallbackModel } from '@hla4ts/hla-api';
+ *
+ * // Create federate ambassador
+ * class MyFederateAmbassador extends BaseFederateAmbassador {
+ *   discoverObjectInstance(objectInstance, objectClass, name) {
+ *     console.log(`Discovered: ${name}`);
+ *   }
+ * }
+ *
+ * // Create RTI ambassador
+ * const rtiAmbassador = new RTIAmbassador({ host: 'rti.example.com' });
+ *
+ * // Connect and join
+ * const federateAmbassador = new MyFederateAmbassador();
+ * await rtiAmbassador.connect(federateAmbassador, { callbackModel: CallbackModel.EVOKED });
+ * const joinResult = await rtiAmbassador.joinFederationExecution('MyFederate', 'FederateType', 'TestFederation');
+ *
+ * // ... do HLA operations ...
+ *
+ * // Clean up
+ * await rtiAmbassador.resignFederationExecution(ResignAction.DELETE_OBJECTS_THEN_DIVEST);
+ * await rtiAmbassador.disconnect();
+ * ```
+ */
+export class RTIAmbassador {
+  private readonly _options: Required<RTIAmbassadorOptions>;
+  private _transport: Transport | null = null;
+  private _session: Session | null = null;
+  private _callbackDispatcher: CallbackDispatcher | null = null;
+  private _inCallback = false;
+
+  /**
+   * Create a new RTI Ambassador.
+   *
+   * @param options - Connection options
+   */
+  constructor(options: RTIAmbassadorOptions) {
+    this._options = {
+      host: options.host,
+      port: options.port ?? (options.useTls !== false ? 15165 : 15164),
+      useTls: options.useTls ?? true,
+      connectionTimeout: options.connectionTimeout ?? 30000,
+      responseTimeout: options.responseTimeout ?? 180000,
+      tlsOptions: options.tlsOptions ?? {},
+    };
+  }
+
+  // ===========================================================================
+  // Connection Management
+  // ===========================================================================
+
+  /**
+   * Check if connected to the RTI.
+   */
+  get isConnected(): boolean {
+    return this._session?.isOperational ?? false;
+  }
+
+  /**
+   * Connect to the RTI.
+   *
+   * @param federateAmbassador - The federate ambassador to receive callbacks
+   * @param options - Connection options
+   * @returns Configuration result
+   */
+  async connect(
+    federateAmbassador: FederateAmbassador,
+    options: ConnectionOptions
+  ): Promise<ConfigurationResult> {
+    if (this._session) {
+      throw new AlreadyConnected("Already connected to RTI");
+    }
+
+    this._callbackDispatcher = new CallbackDispatcher(federateAmbassador);
+
+    // Create transport
+    if (this._options.useTls) {
+      this._transport = new TlsTransport({
+        host: this._options.host,
+        port: this._options.port,
+        ...this._options.tlsOptions,
+      });
+    } else {
+      this._transport = new TcpTransport({
+        host: this._options.host,
+        port: this._options.port,
+      });
+    }
+
+    // Create session
+    this._session = new Session(this._transport, {
+      connectionTimeout: this._options.connectionTimeout,
+      responseTimeout: this._options.responseTimeout,
+    });
+
+    // Create callback listener
+    const callbackListener: HlaCallbackRequestListener = {
+      onHlaCallbackRequest: (seqNum: number, callbackData: Uint8Array) => {
+        this._handleCallback(seqNum, callbackData);
+      },
+    };
+
+    try {
+      // Start session
+      await this._session.start(callbackListener);
+
+      // Send Connect request
+      let callRequest: CallRequest;
+      
+      if (options.credentials && options.rtiConfiguration) {
+        callRequest = {
+          connectWithConfigurationAndCredentialsRequest: {
+            rtiConfiguration: toProtoRtiConfiguration(options.rtiConfiguration),
+            credentials: toProtoCredentials(options.credentials),
+          },
+        };
+      } else if (options.credentials) {
+        callRequest = {
+          connectWithCredentialsRequest: {
+            credentials: toProtoCredentials(options.credentials),
+          },
+        };
+      } else if (options.rtiConfiguration) {
+        callRequest = {
+          connectWithConfigurationRequest: {
+            rtiConfiguration: toProtoRtiConfiguration(options.rtiConfiguration),
+          },
+        };
+      } else {
+        callRequest = {
+          connectRequest: {},
+        };
+      }
+
+      const response = await this._doHlaCall(callRequest);
+
+      // Extract configuration result
+      if (response.connectResponse) {
+        return convertConfigurationResult(response.connectResponse.configurationResult);
+      }
+      if (response.connectWithCredentialsResponse) {
+        return convertConfigurationResult(response.connectWithCredentialsResponse.configurationResult);
+      }
+      if (response.connectWithConfigurationResponse) {
+        return convertConfigurationResult(response.connectWithConfigurationResponse.configurationResult);
+      }
+      if (response.connectWithConfigurationAndCredentialsResponse) {
+        return convertConfigurationResult(response.connectWithConfigurationAndCredentialsResponse.configurationResult);
+      }
+
+      return { configurationUsed: false };
+    } catch (error) {
+      // Clean up on failure
+      this._cleanup();
+      throw error;
+    }
+  }
+
+  /**
+   * Disconnect from the RTI.
+   */
+  async disconnect(): Promise<void> {
+    if (!this._session) {
+      return; // Already disconnected
+    }
+
+    try {
+      // Send Disconnect request
+      await this._doHlaCall({ disconnectRequest: {} });
+    } finally {
+      // Terminate session
+      await this._session.terminate().catch(() => {});
+      this._cleanup();
+    }
+  }
+
+  /**
+   * Disconnect immediately without waiting for RTI responses.
+   */
+  async disconnectNow(): Promise<void> {
+    if (!this._session) {
+      return;
+    }
+    try {
+      await this._session.terminate(0);
+    } catch {
+      // Best effort; fall through to cleanup.
+    } finally {
+      this._cleanup();
+    }
+  }
+
+  // ===========================================================================
+  // Federation Management
+  // ===========================================================================
+
+  /**
+   * Create a federation execution.
+   *
+   * @param federationName - Name of the federation
+   * @param fomModule - FOM module
+   */
+  async createFederationExecution(federationName: string, fomModule: FomModule): Promise<void> {
+    await this._doHlaCall({
+      createFederationExecutionRequest: {
+        federationName,
+        fomModule: toProtoFomModule(fomModule),
+      },
+    });
+  }
+
+  /**
+   * Create a federation execution with time representation.
+   *
+   * @param federationName - Name of the federation
+   * @param fomModule - FOM module
+   * @param logicalTimeImplementationName - Name of the logical time factory
+   */
+  async createFederationExecutionWithTime(
+    federationName: string,
+    fomModule: FomModule,
+    logicalTimeImplementationName: string
+  ): Promise<void> {
+    await this._doHlaCall({
+      createFederationExecutionWithTimeRequest: {
+        federationName,
+        fomModule: toProtoFomModule(fomModule),
+        logicalTimeImplementationName,
+      },
+    });
+  }
+
+  /**
+   * Create a federation execution with multiple FOM modules.
+   *
+   * @param federationName - Name of the federation
+   * @param fomModules - FOM modules
+   */
+  async createFederationExecutionWithModules(
+    federationName: string,
+    fomModules: FomModuleSet
+  ): Promise<void> {
+    await this._doHlaCall({
+      createFederationExecutionWithModulesRequest: {
+        federationName,
+        fomModules: toProtoFomModuleSet(fomModules),
+      },
+    });
+  }
+
+  /**
+   * Create a federation execution with multiple FOM modules and time.
+   *
+   * @param federationName - Name of the federation
+   * @param fomModules - FOM modules
+   * @param logicalTimeImplementationName - Name of the logical time factory
+   */
+  async createFederationExecutionWithModulesAndTime(
+    federationName: string,
+    fomModules: FomModuleSet,
+    logicalTimeImplementationName: string
+  ): Promise<void> {
+    await this._doHlaCall({
+      createFederationExecutionWithModulesAndTimeRequest: {
+        federationName,
+        fomModules: toProtoFomModuleSet(fomModules),
+        logicalTimeImplementationName,
+      },
+    });
+  }
+
+  /**
+   * Destroy a federation execution.
+   *
+   * @param federationName - Name of the federation to destroy
+   */
+  async destroyFederationExecution(federationName: string): Promise<void> {
+    await this._doHlaCall({
+      destroyFederationExecutionRequest: { federationName },
+    });
+  }
+
+  /**
+   * List federation executions (async - results come via callback).
+   */
+  async listFederationExecutions(): Promise<void> {
+    await this._doHlaCall({ listFederationExecutionsRequest: {} });
+  }
+
+  /**
+   * List federation execution members (async - results come via callback).
+   *
+   * @param federationName - Name of the federation
+   */
+  async listFederationExecutionMembers(federationName: string): Promise<void> {
+    await this._doHlaCall({
+      listFederationExecutionMembersRequest: { federationName },
+    });
+  }
+
+  /**
+   * Join a federation execution.
+   *
+   * @param federateType - Type of the federate
+   * @param federationName - Name of the federation to join
+   * @returns Join result with federate handle and time implementation
+   */
+  async joinFederationExecution(
+    federateType: string,
+    federationName: string
+  ): Promise<JoinResult> {
+    this._throwIfInCallback("joinFederationExecution");
+    const response = await this._doHlaCall({
+      joinFederationExecutionRequest: { federateType, federationName },
+    });
+    return convertJoinResult(response.joinFederationExecutionResponse?.result);
+  }
+
+  /**
+   * Join a federation execution with a specific name.
+   *
+   * @param federateName - Name for this federate
+   * @param federateType - Type of the federate
+   * @param federationName - Name of the federation to join
+   * @returns Join result
+   */
+  async joinFederationExecutionWithName(
+    federateName: string,
+    federateType: string,
+    federationName: string
+  ): Promise<JoinResult> {
+    this._throwIfInCallback("joinFederationExecution");
+    const response = await this._doHlaCall({
+      joinFederationExecutionWithNameRequest: { federateName, federateType, federationName },
+    });
+    return convertJoinResult(response.joinFederationExecutionWithNameResponse?.result);
+  }
+
+  /**
+   * Join a federation execution with additional FOM modules.
+   *
+   * @param federateType - Type of the federate
+   * @param federationName - Name of the federation to join
+   * @param additionalFomModules - Additional FOM modules
+   * @returns Join result
+   */
+  async joinFederationExecutionWithModules(
+    federateType: string,
+    federationName: string,
+    additionalFomModules: FomModuleSet
+  ): Promise<JoinResult> {
+    this._throwIfInCallback("joinFederationExecution");
+    const response = await this._doHlaCall({
+      joinFederationExecutionWithModulesRequest: {
+        federateType,
+        federationName,
+        additionalFomModules: toProtoFomModuleSet(additionalFomModules),
+      },
+    });
+    return convertJoinResult(response.joinFederationExecutionWithModulesResponse?.result);
+  }
+
+  /**
+   * Join a federation execution with name and additional FOM modules.
+   *
+   * @param federateName - Name for this federate
+   * @param federateType - Type of the federate
+   * @param federationName - Name of the federation to join
+   * @param additionalFomModules - Additional FOM modules
+   * @returns Join result
+   */
+  async joinFederationExecutionWithNameAndModules(
+    federateName: string,
+    federateType: string,
+    federationName: string,
+    additionalFomModules: FomModuleSet
+  ): Promise<JoinResult> {
+    this._throwIfInCallback("joinFederationExecution");
+    const response = await this._doHlaCall({
+      joinFederationExecutionWithNameAndModulesRequest: {
+        federateName,
+        federateType,
+        federationName,
+        additionalFomModules: toProtoFomModuleSet(additionalFomModules),
+      },
+    });
+    return convertJoinResult(response.joinFederationExecutionWithNameAndModulesResponse?.result);
+  }
+
+  /**
+   * Resign from a federation execution.
+   *
+   * @param resignAction - Action to take when resigning
+   */
+  async resignFederationExecution(resignAction: ResignAction): Promise<void> {
+    this._throwIfInCallback("resignFederationExecution");
+    await this._doHlaCall({
+      resignFederationExecutionRequest: { resignAction },
+    });
+  }
+
+  // ===========================================================================
+  // Synchronization Point Services
+  // ===========================================================================
+
+  /**
+   * Register a federation synchronization point.
+   *
+   * @param label - Synchronization point label
+   * @param userSuppliedTag - User-supplied tag
+   */
+  async registerFederationSynchronizationPoint(
+    label: string,
+    userSuppliedTag: UserSuppliedTag
+  ): Promise<void> {
+    await this._doHlaCall({
+      registerFederationSynchronizationPointRequest: {
+        synchronizationPointLabel: label,
+        userSuppliedTag,
+      },
+    });
+  }
+
+  /**
+   * Register a federation synchronization point with a specific set of federates.
+   *
+   * @param label - Synchronization point label
+   * @param userSuppliedTag - User-supplied tag
+   * @param synchronizationSet - Set of federates to synchronize
+   */
+  async registerFederationSynchronizationPointWithSet(
+    label: string,
+    userSuppliedTag: UserSuppliedTag,
+    synchronizationSet: FederateHandleSet
+  ): Promise<void> {
+    await this._doHlaCall({
+      registerFederationSynchronizationPointWithSetRequest: {
+        synchronizationPointLabel: label,
+        userSuppliedTag,
+        synchronizationSet: toProtoFederateHandleSet(synchronizationSet),
+      },
+    });
+  }
+
+  /**
+   * Indicate that this federate has achieved a synchronization point.
+   *
+   * @param label - Synchronization point label
+   * @param successfully - Whether the synchronization was successful
+   */
+  async synchronizationPointAchieved(label: string, successfully: boolean = true): Promise<void> {
+    await this._doHlaCall({
+      synchronizationPointAchievedRequest: {
+        synchronizationPointLabel: label,
+        successfully,
+      },
+    });
+  }
+
+  // ===========================================================================
+  // Declaration Management
+  // ===========================================================================
+
+  /**
+   * Publish object class attributes.
+   *
+   * @param objectClass - Object class handle
+   * @param attributes - Set of attribute handles to publish
+   */
+  async publishObjectClassAttributes(
+    objectClass: ObjectClassHandle,
+    attributes: AttributeHandleSet
+  ): Promise<void> {
+    await this._doHlaCall({
+      publishObjectClassAttributesRequest: {
+        objectClass: toProtoObjectClassHandle(objectClass),
+        attributes: toProtoAttributeHandleSet(attributes),
+      },
+    });
+  }
+
+  /**
+   * Unpublish all attributes of an object class.
+   *
+   * @param objectClass - Object class handle
+   */
+  async unpublishObjectClass(objectClass: ObjectClassHandle): Promise<void> {
+    await this._doHlaCall({
+      unpublishObjectClassRequest: {
+        objectClass: toProtoObjectClassHandle(objectClass),
+      },
+    });
+  }
+
+  /**
+   * Unpublish specific attributes of an object class.
+   *
+   * @param objectClass - Object class handle
+   * @param attributes - Set of attribute handles to unpublish
+   */
+  async unpublishObjectClassAttributes(
+    objectClass: ObjectClassHandle,
+    attributes: AttributeHandleSet
+  ): Promise<void> {
+    await this._doHlaCall({
+      unpublishObjectClassAttributesRequest: {
+        objectClass: toProtoObjectClassHandle(objectClass),
+        attributes: toProtoAttributeHandleSet(attributes),
+      },
+    });
+  }
+
+  /**
+   * Publish an interaction class.
+   *
+   * @param interactionClass - Interaction class handle
+   */
+  async publishInteractionClass(interactionClass: InteractionClassHandle): Promise<void> {
+    await this._doHlaCall({
+      publishInteractionClassRequest: {
+        interactionClass: toProtoInteractionClassHandle(interactionClass),
+      },
+    });
+  }
+
+  /**
+   * Unpublish an interaction class.
+   *
+   * @param interactionClass - Interaction class handle
+   */
+  async unpublishInteractionClass(interactionClass: InteractionClassHandle): Promise<void> {
+    await this._doHlaCall({
+      unpublishInteractionClassRequest: {
+        interactionClass: toProtoInteractionClassHandle(interactionClass),
+      },
+    });
+  }
+
+  /**
+   * Subscribe to object class attributes.
+   *
+   * @param objectClass - Object class handle
+   * @param attributes - Set of attribute handles to subscribe to
+   */
+  async subscribeObjectClassAttributes(
+    objectClass: ObjectClassHandle,
+    attributes: AttributeHandleSet
+  ): Promise<void> {
+    await this._doHlaCall({
+      subscribeObjectClassAttributesRequest: {
+        objectClass: toProtoObjectClassHandle(objectClass),
+        attributes: toProtoAttributeHandleSet(attributes),
+      },
+    });
+  }
+
+  /**
+   * Subscribe to object class attributes passively.
+   *
+   * @param objectClass - Object class handle
+   * @param attributes - Set of attribute handles
+   */
+  async subscribeObjectClassAttributesPassively(
+    objectClass: ObjectClassHandle,
+    attributes: AttributeHandleSet
+  ): Promise<void> {
+    await this._doHlaCall({
+      subscribeObjectClassAttributesPassivelyRequest: {
+        objectClass: toProtoObjectClassHandle(objectClass),
+        attributes: toProtoAttributeHandleSet(attributes),
+      },
+    });
+  }
+
+  /**
+   * Unsubscribe from all attributes of an object class.
+   *
+   * @param objectClass - Object class handle
+   */
+  async unsubscribeObjectClass(objectClass: ObjectClassHandle): Promise<void> {
+    await this._doHlaCall({
+      unsubscribeObjectClassRequest: {
+        objectClass: toProtoObjectClassHandle(objectClass),
+      },
+    });
+  }
+
+  /**
+   * Unsubscribe from specific attributes of an object class.
+   *
+   * @param objectClass - Object class handle
+   * @param attributes - Set of attribute handles
+   */
+  async unsubscribeObjectClassAttributes(
+    objectClass: ObjectClassHandle,
+    attributes: AttributeHandleSet
+  ): Promise<void> {
+    await this._doHlaCall({
+      unsubscribeObjectClassAttributesRequest: {
+        objectClass: toProtoObjectClassHandle(objectClass),
+        attributes: toProtoAttributeHandleSet(attributes),
+      },
+    });
+  }
+
+  /**
+   * Subscribe to an interaction class.
+   *
+   * @param interactionClass - Interaction class handle
+   */
+  async subscribeInteractionClass(interactionClass: InteractionClassHandle): Promise<void> {
+    await this._doHlaCall({
+      subscribeInteractionClassRequest: {
+        interactionClass: toProtoInteractionClassHandle(interactionClass),
+      },
+    });
+  }
+
+  /**
+   * Subscribe to an interaction class passively.
+   *
+   * @param interactionClass - Interaction class handle
+   */
+  async subscribeInteractionClassPassively(interactionClass: InteractionClassHandle): Promise<void> {
+    await this._doHlaCall({
+      subscribeInteractionClassPassivelyRequest: {
+        interactionClass: toProtoInteractionClassHandle(interactionClass),
+      },
+    });
+  }
+
+  /**
+   * Unsubscribe from an interaction class.
+   *
+   * @param interactionClass - Interaction class handle
+   */
+  async unsubscribeInteractionClass(interactionClass: InteractionClassHandle): Promise<void> {
+    await this._doHlaCall({
+      unsubscribeInteractionClassRequest: {
+        interactionClass: toProtoInteractionClassHandle(interactionClass),
+      },
+    });
+  }
+
+  // ===========================================================================
+  // Object Management
+  // ===========================================================================
+
+  /**
+   * Reserve an object instance name.
+   *
+   * @param objectInstanceName - Name to reserve
+   */
+  async reserveObjectInstanceName(objectInstanceName: string): Promise<void> {
+    await this._doHlaCall({
+      reserveObjectInstanceNameRequest: { objectInstanceName },
+    });
+  }
+
+  /**
+   * Release a reserved object instance name.
+   *
+   * @param objectInstanceName - Name to release
+   */
+  async releaseObjectInstanceName(objectInstanceName: string): Promise<void> {
+    await this._doHlaCall({
+      releaseObjectInstanceNameRequest: { objectInstanceName },
+    });
+  }
+
+  /**
+   * Register a new object instance.
+   *
+   * @param objectClass - Object class handle
+   * @returns Handle of the registered object instance
+   */
+  async registerObjectInstance(objectClass: ObjectClassHandle): Promise<ObjectInstanceHandle> {
+    const response = await this._doHlaCall({
+      registerObjectInstanceRequest: {
+        objectClass: toProtoObjectClassHandle(objectClass),
+      },
+    });
+    return convertObjectInstanceHandle(response.registerObjectInstanceResponse?.result);
+  }
+
+  /**
+   * Register a new object instance with a specific name.
+   *
+   * @param objectClass - Object class handle
+   * @param objectInstanceName - Name for the object instance
+   * @returns Handle of the registered object instance
+   */
+  async registerObjectInstanceWithName(
+    objectClass: ObjectClassHandle,
+    objectInstanceName: string
+  ): Promise<ObjectInstanceHandle> {
+    const response = await this._doHlaCall({
+      registerObjectInstanceWithNameRequest: {
+        objectClass: toProtoObjectClassHandle(objectClass),
+        objectInstanceName,
+      },
+    });
+    return convertObjectInstanceHandle(response.registerObjectInstanceWithNameResponse?.result);
+  }
+
+  /**
+   * Update attribute values of an object instance.
+   *
+   * @param objectInstance - Object instance handle
+   * @param attributeValues - Map of attribute handles to values
+   * @param userSuppliedTag - User-supplied tag
+   */
+  async updateAttributeValues(
+    objectInstance: ObjectInstanceHandle,
+    attributeValues: AttributeHandleValueMap,
+    userSuppliedTag: UserSuppliedTag
+  ): Promise<void> {
+    await this._doHlaCall({
+      updateAttributeValuesRequest: {
+        objectInstance: toProtoObjectInstanceHandle(objectInstance),
+        attributeValues: toProtoAttributeHandleValueMap(attributeValues),
+        userSuppliedTag,
+      },
+    });
+  }
+
+  /**
+   * Update attribute values with a timestamp.
+   *
+   * @param objectInstance - Object instance handle
+   * @param attributeValues - Map of attribute handles to values
+   * @param userSuppliedTag - User-supplied tag
+   * @param time - Logical time
+   * @returns Message retraction info
+   */
+  async updateAttributeValuesWithTime(
+    objectInstance: ObjectInstanceHandle,
+    attributeValues: AttributeHandleValueMap,
+    userSuppliedTag: UserSuppliedTag,
+    time: LogicalTime
+  ): Promise<MessageRetractionReturn> {
+    const response = await this._doHlaCall({
+      updateAttributeValuesWithTimeRequest: {
+        objectInstance: toProtoObjectInstanceHandle(objectInstance),
+        attributeValues: toProtoAttributeHandleValueMap(attributeValues),
+        userSuppliedTag,
+        time: toProtoLogicalTime(time),
+      },
+    });
+    const result = response.updateAttributeValuesWithTimeResponse?.result;
+    return {
+      retractionHandleIsValid: result?.retractionHandleIsValid ?? false,
+      retractionHandle: result?.messageRetractionHandle?.data,
+    };
+  }
+
+  /**
+   * Send an interaction.
+   *
+   * @param interactionClass - Interaction class handle
+   * @param parameterValues - Map of parameter handles to values
+   * @param userSuppliedTag - User-supplied tag
+   */
+  async sendInteraction(
+    interactionClass: InteractionClassHandle,
+    parameterValues: ParameterHandleValueMap,
+    userSuppliedTag: UserSuppliedTag
+  ): Promise<void> {
+    await this._doHlaCall({
+      sendInteractionRequest: {
+        interactionClass: toProtoInteractionClassHandle(interactionClass),
+        parameterValues: toProtoParameterHandleValueMap(parameterValues),
+        userSuppliedTag,
+      },
+    });
+  }
+
+  /**
+   * Send an interaction with a timestamp.
+   *
+   * @param interactionClass - Interaction class handle
+   * @param parameterValues - Map of parameter handles to values
+   * @param userSuppliedTag - User-supplied tag
+   * @param time - Logical time
+   * @returns Message retraction info
+   */
+  async sendInteractionWithTime(
+    interactionClass: InteractionClassHandle,
+    parameterValues: ParameterHandleValueMap,
+    userSuppliedTag: UserSuppliedTag,
+    time: LogicalTime
+  ): Promise<MessageRetractionReturn> {
+    const response = await this._doHlaCall({
+      sendInteractionWithTimeRequest: {
+        interactionClass: toProtoInteractionClassHandle(interactionClass),
+        parameterValues: toProtoParameterHandleValueMap(parameterValues),
+        userSuppliedTag,
+        time: toProtoLogicalTime(time),
+      },
+    });
+    const result = response.sendInteractionWithTimeResponse?.result;
+    return {
+      retractionHandleIsValid: result?.retractionHandleIsValid ?? false,
+      retractionHandle: result?.messageRetractionHandle?.data,
+    };
+  }
+
+  /**
+   * Delete an object instance.
+   *
+   * @param objectInstance - Object instance handle
+   * @param userSuppliedTag - User-supplied tag
+   */
+  async deleteObjectInstance(
+    objectInstance: ObjectInstanceHandle,
+    userSuppliedTag: UserSuppliedTag
+  ): Promise<void> {
+    await this._doHlaCall({
+      deleteObjectInstanceRequest: {
+        objectInstance: toProtoObjectInstanceHandle(objectInstance),
+        userSuppliedTag,
+      },
+    });
+  }
+
+  /**
+   * Delete an object instance with a timestamp.
+   *
+   * @param objectInstance - Object instance handle
+   * @param userSuppliedTag - User-supplied tag
+   * @param time - Logical time
+   * @returns Message retraction info
+   */
+  async deleteObjectInstanceWithTime(
+    objectInstance: ObjectInstanceHandle,
+    userSuppliedTag: UserSuppliedTag,
+    time: LogicalTime
+  ): Promise<MessageRetractionReturn> {
+    const response = await this._doHlaCall({
+      deleteObjectInstanceWithTimeRequest: {
+        objectInstance: toProtoObjectInstanceHandle(objectInstance),
+        userSuppliedTag,
+        time: toProtoLogicalTime(time),
+      },
+    });
+    const result = response.deleteObjectInstanceWithTimeResponse?.result;
+    return {
+      retractionHandleIsValid: result?.retractionHandleIsValid ?? false,
+      retractionHandle: result?.messageRetractionHandle?.data,
+    };
+  }
+
+  /**
+   * Locally delete an object instance (remove from local object model without notifying others).
+   *
+   * @param objectInstance - Object instance handle
+   */
+  async localDeleteObjectInstance(objectInstance: ObjectInstanceHandle): Promise<void> {
+    await this._doHlaCall({
+      localDeleteObjectInstanceRequest: {
+        objectInstance: toProtoObjectInstanceHandle(objectInstance),
+      },
+    });
+  }
+
+  /**
+   * Request attribute value update for a specific object instance.
+   *
+   * @param objectInstance - Object instance handle
+   * @param attributes - Set of attributes to request
+   * @param userSuppliedTag - User-supplied tag
+   */
+  async requestInstanceAttributeValueUpdate(
+    objectInstance: ObjectInstanceHandle,
+    attributes: AttributeHandleSet,
+    userSuppliedTag: UserSuppliedTag
+  ): Promise<void> {
+    await this._doHlaCall({
+      requestInstanceAttributeValueUpdateRequest: {
+        objectInstance: toProtoObjectInstanceHandle(objectInstance),
+        attributes: toProtoAttributeHandleSet(attributes),
+        userSuppliedTag,
+      },
+    });
+  }
+
+  /**
+   * Request attribute value update for all objects of a class.
+   *
+   * @param objectClass - Object class handle
+   * @param attributes - Set of attributes to request
+   * @param userSuppliedTag - User-supplied tag
+   */
+  async requestClassAttributeValueUpdate(
+    objectClass: ObjectClassHandle,
+    attributes: AttributeHandleSet,
+    userSuppliedTag: UserSuppliedTag
+  ): Promise<void> {
+    await this._doHlaCall({
+      requestClassAttributeValueUpdateRequest: {
+        objectClass: toProtoObjectClassHandle(objectClass),
+        attributes: toProtoAttributeHandleSet(attributes),
+        userSuppliedTag,
+      },
+    });
+  }
+
+  // ===========================================================================
+  // Time Management
+  // ===========================================================================
+
+  /**
+   * Enable time regulation.
+   *
+   * @param lookahead - Lookahead interval
+   */
+  async enableTimeRegulation(lookahead: LogicalTimeInterval): Promise<void> {
+    await this._doHlaCall({
+      enableTimeRegulationRequest: {
+        lookahead: toProtoLogicalTimeInterval(lookahead),
+      },
+    });
+  }
+
+  /**
+   * Disable time regulation.
+   */
+  async disableTimeRegulation(): Promise<void> {
+    await this._doHlaCall({ disableTimeRegulationRequest: {} });
+  }
+
+  /**
+   * Enable time constrained mode.
+   */
+  async enableTimeConstrained(): Promise<void> {
+    await this._doHlaCall({ enableTimeConstrainedRequest: {} });
+  }
+
+  /**
+   * Disable time constrained mode.
+   */
+  async disableTimeConstrained(): Promise<void> {
+    await this._doHlaCall({ disableTimeConstrainedRequest: {} });
+  }
+
+  /**
+   * Request a time advance.
+   *
+   * @param time - Target logical time
+   */
+  async timeAdvanceRequest(time: LogicalTime): Promise<void> {
+    await this._doHlaCall({
+      timeAdvanceRequestRequest: {
+        time: toProtoLogicalTime(time),
+      },
+    });
+  }
+
+  /**
+   * Request a time advance available.
+   *
+   * @param time - Target logical time
+   */
+  async timeAdvanceRequestAvailable(time: LogicalTime): Promise<void> {
+    await this._doHlaCall({
+      timeAdvanceRequestAvailableRequest: {
+        time: toProtoLogicalTime(time),
+      },
+    });
+  }
+
+  /**
+   * Request next message.
+   *
+   * @param time - Target logical time
+   */
+  async nextMessageRequest(time: LogicalTime): Promise<void> {
+    await this._doHlaCall({
+      nextMessageRequestRequest: {
+        time: toProtoLogicalTime(time),
+      },
+    });
+  }
+
+  /**
+   * Request next message available.
+   *
+   * @param time - Target logical time
+   */
+  async nextMessageRequestAvailable(time: LogicalTime): Promise<void> {
+    await this._doHlaCall({
+      nextMessageRequestAvailableRequest: {
+        time: toProtoLogicalTime(time),
+      },
+    });
+  }
+
+  /**
+   * Flush the message queue.
+   *
+   * @param time - Target logical time
+   */
+  async flushQueueRequest(time: LogicalTime): Promise<void> {
+    await this._doHlaCall({
+      flushQueueRequestRequest: {
+        time: toProtoLogicalTime(time),
+      },
+    });
+  }
+
+  /**
+   * Modify the lookahead interval.
+   *
+   * @param lookahead - New lookahead interval
+   */
+  async modifyLookahead(lookahead: LogicalTimeInterval): Promise<void> {
+    await this._doHlaCall({
+      modifyLookaheadRequest: {
+        lookahead: toProtoLogicalTimeInterval(lookahead),
+      },
+    });
+  }
+
+  /**
+   * Query the Greatest Available Logical Time (GALT).
+   */
+  async queryGALT(): Promise<TimeQueryReturn> {
+    const response = await this._doHlaCall({ queryGALTRequest: {} });
+    return convertTimeQueryReturn(response.queryGALTResponse?.result);
+  }
+
+  /**
+   * Query the current logical time.
+   */
+  async queryLogicalTime(): Promise<LogicalTime> {
+    const response = await this._doHlaCall({ queryLogicalTimeRequest: {} });
+    return convertLogicalTime(response.queryLogicalTimeResponse?.result);
+  }
+
+  /**
+   * Query the Least Incoming Time Stamp (LITS).
+   */
+  async queryLITS(): Promise<TimeQueryReturn> {
+    const response = await this._doHlaCall({ queryLITSRequest: {} });
+    return convertTimeQueryReturn(response.queryLITSResponse?.result);
+  }
+
+  /**
+   * Query the current lookahead interval.
+   */
+  async queryLookahead(): Promise<LogicalTimeInterval> {
+    const response = await this._doHlaCall({ queryLookaheadRequest: {} });
+    return convertLogicalTimeInterval(response.queryLookaheadResponse?.result);
+  }
+
+  // ===========================================================================
+  // Support Services
+  // ===========================================================================
+
+  /**
+   * Get the handle for an object class by name.
+   *
+   * @param objectClassName - Name of the object class
+   * @returns Object class handle
+   */
+  async getObjectClassHandle(objectClassName: string): Promise<ObjectClassHandle> {
+    const response = await this._doHlaCall({
+      getObjectClassHandleRequest: { objectClassName },
+    });
+    return response.getObjectClassHandleResponse?.result?.data ?? new Uint8Array(0);
+  }
+
+  /**
+   * Get the name of an object class by handle.
+   *
+   * @param objectClass - Object class handle
+   * @returns Object class name
+   */
+  async getObjectClassName(objectClass: ObjectClassHandle): Promise<string> {
+    const response = await this._doHlaCall({
+      getObjectClassNameRequest: {
+        objectClass: toProtoObjectClassHandle(objectClass),
+      },
+    });
+    return response.getObjectClassNameResponse?.result ?? "";
+  }
+
+  /**
+   * Get the handle for an attribute by name.
+   *
+   * @param objectClass - Object class handle
+   * @param attributeName - Name of the attribute
+   * @returns Attribute handle
+   */
+  async getAttributeHandle(
+    objectClass: ObjectClassHandle,
+    attributeName: string
+  ): Promise<Uint8Array> {
+    const response = await this._doHlaCall({
+      getAttributeHandleRequest: {
+        objectClass: toProtoObjectClassHandle(objectClass),
+        attributeName,
+      },
+    });
+    return response.getAttributeHandleResponse?.result?.data ?? new Uint8Array(0);
+  }
+
+  /**
+   * Get the name of an attribute by handle.
+   *
+   * @param objectClass - Object class handle
+   * @param attribute - Attribute handle
+   * @returns Attribute name
+   */
+  async getAttributeName(
+    objectClass: ObjectClassHandle,
+    attribute: Uint8Array
+  ): Promise<string> {
+    const response = await this._doHlaCall({
+      getAttributeNameRequest: {
+        objectClass: toProtoObjectClassHandle(objectClass),
+        attribute: { data: attribute },
+      },
+    });
+    return response.getAttributeNameResponse?.result ?? "";
+  }
+
+  /**
+   * Get the handle for an interaction class by name.
+   *
+   * @param interactionClassName - Name of the interaction class
+   * @returns Interaction class handle
+   */
+  async getInteractionClassHandle(interactionClassName: string): Promise<InteractionClassHandle> {
+    const response = await this._doHlaCall({
+      getInteractionClassHandleRequest: { interactionClassName },
+    });
+    return response.getInteractionClassHandleResponse?.result?.data ?? new Uint8Array(0);
+  }
+
+  /**
+   * Get the name of an interaction class by handle.
+   *
+   * @param interactionClass - Interaction class handle
+   * @returns Interaction class name
+   */
+  async getInteractionClassName(interactionClass: InteractionClassHandle): Promise<string> {
+    const response = await this._doHlaCall({
+      getInteractionClassNameRequest: {
+        interactionClass: toProtoInteractionClassHandle(interactionClass),
+      },
+    });
+    return response.getInteractionClassNameResponse?.result ?? "";
+  }
+
+  /**
+   * Get the handle for a parameter by name.
+   *
+   * @param interactionClass - Interaction class handle
+   * @param parameterName - Name of the parameter
+   * @returns Parameter handle
+   */
+  async getParameterHandle(
+    interactionClass: InteractionClassHandle,
+    parameterName: string
+  ): Promise<Uint8Array> {
+    const response = await this._doHlaCall({
+      getParameterHandleRequest: {
+        interactionClass: toProtoInteractionClassHandle(interactionClass),
+        parameterName,
+      },
+    });
+    return response.getParameterHandleResponse?.result?.data ?? new Uint8Array(0);
+  }
+
+  /**
+   * Get the name of a parameter by handle.
+   *
+   * @param interactionClass - Interaction class handle
+   * @param parameter - Parameter handle
+   * @returns Parameter name
+   */
+  async getParameterName(
+    interactionClass: InteractionClassHandle,
+    parameter: Uint8Array
+  ): Promise<string> {
+    const response = await this._doHlaCall({
+      getParameterNameRequest: {
+        interactionClass: toProtoInteractionClassHandle(interactionClass),
+        parameter: { data: parameter },
+      },
+    });
+    return response.getParameterNameResponse?.result ?? "";
+  }
+
+  /**
+   * Get the handle for an object instance by name.
+   *
+   * @param objectInstanceName - Name of the object instance
+   * @returns Object instance handle
+   */
+  async getObjectInstanceHandle(objectInstanceName: string): Promise<ObjectInstanceHandle> {
+    const response = await this._doHlaCall({
+      getObjectInstanceHandleRequest: { objectInstanceName },
+    });
+    return response.getObjectInstanceHandleResponse?.result?.data ?? new Uint8Array(0);
+  }
+
+  /**
+   * Get the name of an object instance by handle.
+   *
+   * @param objectInstance - Object instance handle
+   * @returns Object instance name
+   */
+  async getObjectInstanceName(objectInstance: ObjectInstanceHandle): Promise<string> {
+    const response = await this._doHlaCall({
+      getObjectInstanceNameRequest: {
+        objectInstance: toProtoObjectInstanceHandle(objectInstance),
+      },
+    });
+    return response.getObjectInstanceNameResponse?.result ?? "";
+  }
+
+  // ===========================================================================
+  // Callback Handling
+  // ===========================================================================
+
+  /**
+   * Evoke a single callback.
+   *
+   * @param _approximateMinimumTimeInSeconds - Minimum time to wait for a callback
+   * @returns true if a callback was processed
+   */
+  async evokeCallback(_approximateMinimumTimeInSeconds: number): Promise<boolean> {
+    this._throwIfInCallback("evokeCallback");
+    // In this implementation, callbacks are handled immediately by the session layer
+    // This method is provided for API compatibility but may need enhancement
+    // for full evoked callback model support
+    return false;
+  }
+
+  /**
+   * Evoke multiple callbacks.
+   *
+   * @param _minimumTime - Minimum time to wait
+   * @param _maximumTime - Maximum time to wait
+   * @returns true if callbacks were processed
+   */
+  async evokeMultipleCallbacks(_minimumTime: number, _maximumTime: number): Promise<boolean> {
+    this._throwIfInCallback("evokeMultipleCallbacks");
+    // In this implementation, callbacks are handled immediately by the session layer
+    return false;
+  }
+
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+
+  /**
+   * Handle an incoming callback from the RTI.
+   */
+  private _handleCallback(seqNum: number, callbackData: Uint8Array): void {
+    if (!this._callbackDispatcher || !this._session) {
+      return;
+    }
+
+    this._inCallback = true;
+    try {
+      const responseData = this._callbackDispatcher.processCallback(callbackData);
+      this._session.sendHlaCallbackResponse(seqNum, responseData).catch((err) => {
+        console.error("[RTIAmbassador] Failed to send callback response:", err);
+      });
+    } finally {
+      this._inCallback = false;
+    }
+  }
+
+  /**
+   * Execute an HLA call and return the response.
+   */
+  private async _doHlaCall(callRequest: CallRequest): Promise<CallResponse> {
+    if (!this._session) {
+      throw new NotConnected("Not connected to RTI");
+    }
+
+    // Encode the request
+    const encodedRequest = CallRequestCodec.encode(callRequest).finish();
+
+    // Send and wait for response
+    const encodedResponse = await this._session.sendHlaCallRequest(encodedRequest);
+
+    // Decode response
+    const response = CallResponseCodec.decode(encodedResponse);
+
+    // Check for exception
+    if (response.exceptionData) {
+      throw createExceptionFromProto(response.exceptionData);
+    }
+
+    return response;
+  }
+
+  /**
+   * Throw if we're currently in a callback.
+   */
+  private _throwIfInCallback(methodName: string): void {
+    if (this._inCallback) {
+      throw new CallNotAllowedFromWithinCallback(
+        `Call to ${methodName} not allowed from within callback`
+      );
+    }
+  }
+
+  /**
+   * Clean up resources.
+   */
+  private _cleanup(): void {
+    this._session = null;
+    this._transport = null;
+    this._callbackDispatcher = null;
+  }
+}