@hla4ts/spacekit 0.1.0

package/src/app.ts

@@ -0,0 +1,1018 @@
+import { decodeHLAinteger64Time, handleToHex, type LogicalTime, type RTIAmbassador } from "@hla4ts/hla-api";
+import type { FomOutputFormat, ModelIdentification, FomOutputOptions, FomModel, SharingType } from "@hla4ts/fom-codegen";
+import { renderFomXml } from "@hla4ts/fom-codegen";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { DeclarativeFom } from "./declarative.ts";
+import {
+  DeclarativeRuntime,
+  type DeclarativeRuntimeOptions,
+  type DeclarativeObjectHandlers,
+  type DeclarativeInteractionHandlers,
+  type DeclarativePublicationSummary,
+} from "./declarative-runtime.ts";
+import { ObjectClassAdapter, InteractionClassAdapter } from "./object-model.ts";
+import type { ObjectInstanceAdapter } from "./object-model.ts";
+import { SpacekitFederate } from "./federate.ts";
+import { TimeAdvanceController } from "./time-advance.ts";
+import type { FederateHandlers, SpacekitFederateConfig } from "./types.ts";
+import type { LogLevel, SpacekitLogger } from "./env.ts";
+import { createConsoleLogger, isDebugEnabled, withDebugEnabled } from "./logger.ts";
+import { bindEntity, consumeEntityChanges, getEntityBinding, type SpacekitEntity } from "./entity.ts";
+import type { FomClassConstructor } from "./decorators.ts";
+import {
+  getDecoratedInteractionClassMetadata,
+  getDecoratedInteractionClassName,
+  getDecoratedObjectClassMetadata,
+  getDecoratedObjectClassName,
+  registerDecoratedClasses,
+} from "./decorators.ts";
+
+export interface SpacekitBootstrapper {
+  handlers: FederateHandlers;
+  run(rti: RTIAmbassador): Promise<unknown>;
+}
+
+export interface SpacekitAppConfig {
+  federate: SpacekitFederateConfig;
+  handlers?: FederateHandlers;
+  declarative?: DeclarativeFom;
+  runtime?: DeclarativeRuntimeOptions;
+  bootstrap?: SpacekitBootstrapper;
+  fomExport?: {
+    enabled?: boolean;
+    path?: string;
+    format?: FomOutputFormat;
+    modelIdentification?: ModelIdentification;
+    indent?: string;
+    inferParentStubs?: boolean;
+  };
+  logging?: {
+    logger?: SpacekitLogger;
+    level?: LogLevel;
+    scope?: string;
+  };
+}
+
+export interface RegisterObjectOptions {
+  name?: string;
+  reserveName?: boolean;
+  reservationTimeoutMs?: number;
+}
+
+export interface TrackRecord<T extends object> {
+  key: string;
+  instance: ObjectInstanceAdapter<T>;
+  name?: string;
+  tracked: boolean;
+  updateCount: number;
+  lastValues?: Partial<T>;
+  lastTime?: LogicalTime;
+}
+
+export interface TrackOptions<T extends object> {
+  filter?: (record: TrackRecord<T>) => boolean;
+  onDiscover?: (payload: { record: TrackRecord<T> }) => void;
+  onUpdate?: (payload: { record: TrackRecord<T>; values: Partial<T>; time?: LogicalTime }) => void;
+  onRemove?: (payload: { record: TrackRecord<T> }) => void;
+}
+
+interface PendingEntity<T extends object> {
+  entity: SpacekitEntity<T>;
+  options?: RegisterObjectOptions;
+  resolve: (instance: ObjectInstanceAdapter<T>) => void;
+  reject: (err: Error) => void;
+}
+
+interface ObjectSchemaProvider<T extends object> {
+  schema?: () => import("./declarative.ts").DeclarativeObjectClass<T>;
+}
+
+interface InteractionSchemaProvider<T extends object> {
+  schema?: () => import("./declarative.ts").DeclarativeInteractionClass<T>;
+}
+
+export class SpacekitApp {
+  readonly declarative: DeclarativeFom;
+  readonly runtime: DeclarativeRuntime;
+  readonly federate: SpacekitFederate;
+  readonly bootstrap?: SpacekitBootstrapper;
+  readonly logger: SpacekitLogger;
+  readonly timeController: TimeAdvanceController;
+  private readonly _appConfig: SpacekitAppConfig;
+  private readonly _entities = new Set<SpacekitEntity<object>>();
+  private readonly _pendingEntities: Array<PendingEntity<object>> = [];
+  private _runtimePrepared = false;
+  private _started = false;
+  private readonly _reservationHandlers: FederateHandlers;
+  private readonly _pendingReservations = new Map<
+    string,
+    { resolve: () => void; reject: (err: Error) => void; timeout?: ReturnType<typeof setTimeout> }
+  >();
+  private _bootstrapState: unknown;
+  private readonly _debugEnabled: boolean;
+  private _shutdownRequested = false;
+  private _shutdownInProgress = false;
+  private readonly _shutdownHandlers: Array<{ signal: NodeJS.Signals; handler: () => void }> = [];
+  private _gracefulShutdownEnabled = false;
+
+  constructor(config: SpacekitAppConfig) {
+    this._appConfig = config;
+    this.declarative = config.declarative ?? new DeclarativeFom();
+    this.runtime = new DeclarativeRuntime(this.declarative, config.runtime);
+    this.bootstrap = config.bootstrap;
+    this.timeController = new TimeAdvanceController();
+    this.logger =
+      config.logging?.logger ??
+      createConsoleLogger({
+        level: config.logging?.level ?? "info",
+        scope: config.logging?.scope ?? "spacekit",
+      });
+    this._debugEnabled = config.logging?.level === "debug" || isDebugEnabled(this.logger);
+    withDebugEnabled(this.logger, this._debugEnabled);
+    this._reservationHandlers = this._createReservationHandlers();
+
+    this.federate = new SpacekitFederate(config.federate, this.runtime.handlers);
+    this.federate.addHandlers(this._reservationHandlers);
+    this.federate.addHandlers(this.timeController.handlers);
+    if (this.bootstrap) {
+      this.federate.addHandlers(this.bootstrap.handlers);
+    }
+    if (config.handlers) {
+      this.federate.addHandlers(config.handlers);
+    }
+  }
+
+  get rtiAmbassador(): RTIAmbassador | null {
+    return this.federate.rtiAmbassador;
+  }
+
+  get bootstrapState(): unknown {
+    return this._bootstrapState;
+  }
+
+  get isStarted(): boolean {
+    return this._started;
+  }
+
+  get isShutdownRequested(): boolean {
+    return this._shutdownRequested;
+  }
+
+  get debugEnabled(): boolean {
+    return this._debugEnabled;
+  }
+
+  get currentTimeMicros(): bigint | null {
+    return this.timeController.lastGrantedTimeMicros;
+  }
+
+  defineObjectClass<T extends object>(schema: import("./declarative.ts").DeclarativeObjectClass<T>) {
+    const adapter = this.declarative.defineObjectClass(schema);
+    if (this._debugEnabled) {
+      this.runtime.addObjectHandlers(adapter, {
+        discover: ({ instance }) => {
+          this.logger.debug("Object discovered.", {
+            className: adapter.className,
+            instanceName: instance.objectInstanceName ?? "(unnamed)",
+          });
+        },
+        update: ({ values, time }) => {
+          this.logger.debug("Object update.", {
+            className: adapter.className,
+            time,
+            values,
+          });
+        },
+        remove: ({ instance }) => {
+          this.logger.debug("Object removed.", {
+            className: adapter.className,
+            instanceName: instance.objectInstanceName ?? "(unnamed)",
+          });
+        },
+      });
+    }
+    return adapter;
+  }
+
+  defineInteractionClass<T extends object>(
+    schema: import("./declarative.ts").DeclarativeInteractionClass<T>
+  ) {
+    const adapter = this.declarative.defineInteractionClass(schema);
+    if (this._debugEnabled) {
+      this.runtime.addInteractionHandlers(adapter, {
+        receive: ({ values, time }) => {
+          this.logger.debug("Interaction received.", {
+            className: adapter.className,
+            time,
+            values,
+          });
+        },
+      });
+    }
+    return adapter;
+  }
+
+  onObject<T extends object>(
+    target: ObjectClassAdapter<T> | FomClassConstructor,
+    handlers: DeclarativeObjectHandlers<T>
+  ): void {
+    const adapter =
+      target instanceof ObjectClassAdapter
+        ? target
+        : this._ensureObjectAdapterFromClass<T>(target);
+    this.runtime.registerObjectHandlers(adapter, handlers);
+  }
+
+  onInteraction<T extends object>(
+    target: InteractionClassAdapter<T> | FomClassConstructor,
+    handlers:
+      | DeclarativeInteractionHandlers<T>
+      | ((payload: { values: Partial<T>; time?: LogicalTime }) => void)
+  ): void {
+    const adapter =
+      target instanceof InteractionClassAdapter
+        ? target
+        : this._ensureInteractionAdapterFromClass<T>(target);
+    const resolvedHandlers: DeclarativeInteractionHandlers<T> =
+      typeof handlers === "function"
+        ? {
+            receive: ({ values, time }) => {
+              handlers({ values, time });
+            },
+          }
+        : handlers;
+    this.runtime.registerInteractionHandlers(adapter, resolvedHandlers);
+  }
+
+  listen<T extends object>(
+    target: ObjectClassAdapter<T> | InteractionClassAdapter<T> | FomClassConstructor,
+    handlers:
+      | DeclarativeObjectHandlers<T>
+      | DeclarativeInteractionHandlers<T>
+      | ((
+          payload:
+            | { values: Partial<T>; time?: LogicalTime }
+            | {
+                values: Partial<T>;
+                instance: ObjectInstanceAdapter<T>;
+              }
+        ) => void)
+  ): void {
+    if (target instanceof ObjectClassAdapter) {
+      if (typeof handlers === "function") {
+        this.onObject(target, {
+          update: ({ values, instance }) => {
+            handlers({ values, instance });
+          },
+        });
+        return;
+      }
+      this.onObject(target, handlers as DeclarativeObjectHandlers<T>);
+      return;
+    }
+    if (target instanceof InteractionClassAdapter) {
+      if (typeof handlers === "function") {
+        this.onInteraction(target, ({ values, time }) => handlers({ values, time }));
+        return;
+      }
+      this.onInteraction(target, handlers as DeclarativeInteractionHandlers<T>);
+      return;
+    }
+
+    try {
+      this.onObject(target, handlers as DeclarativeObjectHandlers<T>);
+      return;
+    } catch {}
+
+    this.onInteraction(target, handlers as DeclarativeInteractionHandlers<T>);
+  }
+
+  track<T extends object>(
+    target: ObjectClassAdapter<T> | FomClassConstructor,
+    options: TrackOptions<T> = {}
+  ): Map<string, TrackRecord<T>> {
+    const records = new Map<string, TrackRecord<T>>();
+    const resolveRecord = (instance: ObjectInstanceAdapter<T>): TrackRecord<T> => {
+      const key = handleToHex(instance.objectInstance);
+      const existing = records.get(key);
+      if (existing) return existing;
+      const created: TrackRecord<T> = {
+        key,
+        instance,
+        tracked: false,
+        updateCount: 0,
+      };
+      records.set(key, created);
+      return created;
+    };
+
+    this.onObject(target, {
+      discover: ({ instance, objectInstanceName }) => {
+        const record = resolveRecord(instance);
+        if (objectInstanceName) record.name = objectInstanceName;
+        if (!record.tracked && (!options.filter || options.filter(record))) {
+          record.tracked = true;
+          options.onDiscover?.({ record });
+        }
+      },
+      update: ({ instance, values, time }) => {
+        const record = resolveRecord(instance);
+        if (values && "name" in values && typeof values.name === "string") {
+          record.name = values.name;
+        }
+        if (!record.tracked && options.filter && !options.filter(record)) {
+          return;
+        }
+        if (!record.tracked) {
+          record.tracked = true;
+          options.onDiscover?.({ record });
+        }
+        record.lastValues = values;
+        record.lastTime = time;
+        record.updateCount += 1;
+        options.onUpdate?.({ record, values, time });
+      },
+      remove: ({ instance }) => {
+        const key = handleToHex(instance.objectInstance);
+        const record = records.get(key);
+        if (record) {
+          if (record.tracked) {
+            options.onRemove?.({ record });
+          }
+          records.delete(key);
+        }
+      },
+    });
+
+    return records;
+  }
+
+  async start(options?: { entities?: Array<SpacekitEntity<object>> }): Promise<void> {
+    this._shutdownRequested = false;
+    const pendingRegistrations: Array<Promise<ObjectInstanceAdapter<object>>> = [];
+    if (options?.entities) {
+      for (const entity of options.entities) {
+        pendingRegistrations.push(this.registerEntity(entity));
+      }
+    }
+
+    await this.exportFomXml();
+    this.logger.info("Connecting to RTI...");
+    await this.federate.start();
+    this.logger.info("Connected and joined federation.");
+    const rti = this._requireRti();
+    const summary = this.runtime.getPublicationSummary();
+    await this.runtime.prepare(rti);
+    this._runtimePrepared = true;
+    this._logPublicationSummary(summary);
+    if (this.bootstrap) {
+      this._bootstrapState = await this.bootstrap.run(rti);
+      this.logger.info("Bootstrap complete.");
+    }
+    await this._flushPendingEntities();
+    await Promise.all(pendingRegistrations);
+    this._started = true;
+  }
+
+  async stop(options: { resignTimeoutMs?: number; disconnectTimeoutMs?: number } = {}): Promise<void> {
+    if (this._shutdownInProgress) return;
+    this._shutdownInProgress = true;
+    this._shutdownRequested = true;
+    this.logger.info("Stopping SpacekitApp...");
+    await this.federate.stop({
+      resignTimeoutMs: options.resignTimeoutMs,
+      disconnectTimeoutMs: options.disconnectTimeoutMs,
+      onError: (phase, error) => {
+        this.logger.warn("Shutdown step failed.", { phase, error });
+      },
+    });
+    this.logger.info("Disconnected.");
+    this._shutdownInProgress = false;
+  }
+
+  requestShutdown(reason?: string): void {
+    if (this._shutdownRequested) return;
+    this._shutdownRequested = true;
+    this.logger.info("Shutdown requested.", { reason });
+  }
+
+  enableGracefulShutdown(options: {
+    signals?: NodeJS.Signals[];
+    exitOnSecondSignal?: boolean;
+  } = {}): () => void {
+    if (this._gracefulShutdownEnabled) {
+      return () => {};
+    }
+    this._gracefulShutdownEnabled = true;
+    const signals = options.signals ?? ["SIGINT", "SIGTERM"];
+    const exitOnSecondSignal = options.exitOnSecondSignal ?? true;
+    let signalCount = 0;
+    const handler = (): void => {
+      signalCount += 1;
+      const reason = signalCount === 1 ? "signal" : "signal (forced)";
+      this.requestShutdown(reason);
+      void this.stop().catch((err) => {
+        this.logger.error("Shutdown error.", { error: err });
+      });
+      if (exitOnSecondSignal && signalCount > 1) {
+        process.exit(1);
+      }
+    };
+
+    for (const signal of signals) {
+      process.on(signal, handler);
+      this._shutdownHandlers.push({ signal, handler });
+    }
+
+    return () => {
+      for (const { signal, handler: registered } of this._shutdownHandlers) {
+        process.off(signal, registered);
+      }
+      this._shutdownHandlers.length = 0;
+      this._gracefulShutdownEnabled = false;
+    };
+  }
+
+  async exportFomXml(): Promise<{ path: string; xml: string }> {
+    const config = this.federateConfig.fomExport;
+    if (config?.enabled === false) {
+      return { path: "", xml: "" };
+    }
+    const format = config?.format ?? "fdd";
+    const outputPath = this._resolveFomExportPath(config?.path);
+    const xml = this._buildFomXml({
+      format,
+      modelIdentification: config?.modelIdentification,
+      indent: config?.indent,
+      inferParentStubs: config?.inferParentStubs,
+    });
+
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, xml, "utf8");
+    this.logger.info("FOM XML exported.", { path: outputPath, format });
+    return { path: outputPath, xml };
+  }
+
+  async reserveObjectInstanceName(name: string, timeoutMs = 10000): Promise<void> {
+    if (this._pendingReservations.has(name)) {
+      throw new Error(`Reservation already pending: ${name}`);
+    }
+    const rti = this._requireRti();
+    this.logger.info("Reserving object instance name...", { name });
+    await new Promise<void>((resolve, reject) => {
+      const timeout =
+        timeoutMs > 0
+          ? setTimeout(() => {
+              this._pendingReservations.delete(name);
+              reject(new Error(`Name reservation timed out: ${name}`));
+            }, timeoutMs)
+          : undefined;
+      this._pendingReservations.set(name, { resolve, reject, timeout });
+      rti.reserveObjectInstanceName(name).catch((err) => {
+        if (timeout) clearTimeout(timeout);
+        this._pendingReservations.delete(name);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      });
+    });
+  }
+
+  async registerObject<T extends object>(
+    adapter: ObjectClassAdapter<T>,
+    options: RegisterObjectOptions = {}
+  ): Promise<ObjectInstanceAdapter<T>> {
+    const rti = this._requireRti();
+    if (options.reserveName && options.name) {
+      await this.reserveObjectInstanceName(options.name, options.reservationTimeoutMs);
+    }
+    if (!adapter.isResolved) {
+      await adapter.resolve(rti);
+    }
+    const instance = await adapter.registerInstance(rti, options.name);
+    this.logger.info("Registered object instance.", {
+      className: adapter.className,
+      name: options.name ?? instance.objectInstanceName ?? "(unnamed)",
+    });
+    return instance;
+  }
+
+  async registerEntity<T extends object>(
+    entity: SpacekitEntity<T>,
+    options: RegisterObjectOptions = {}
+  ): Promise<ObjectInstanceAdapter<T>> {
+    const existing = getEntityBinding(entity);
+    if (existing) {
+      return existing.instance as ObjectInstanceAdapter<T>;
+    }
+    this._ensureObjectAdapterFromEntity(entity);
+    if (!this.rtiAmbassador || !this._runtimePrepared) {
+      return new Promise<ObjectInstanceAdapter<T>>((resolve, reject) => {
+        this._pendingEntities.push({
+          entity: entity as unknown as SpacekitEntity<object>,
+          options,
+          resolve: resolve as (instance: ObjectInstanceAdapter<object>) => void,
+          reject,
+        });
+      });
+    }
+    return this._registerEntityNow(entity, options);
+  }
+
+  async registerEntities<T extends object>(
+    entities: Array<SpacekitEntity<T>>,
+    options: RegisterObjectOptions = {}
+  ): Promise<Array<ObjectInstanceAdapter<T>>> {
+    const results: Array<ObjectInstanceAdapter<T>> = [];
+    for (const entity of entities) {
+      results.push(await this.registerEntity(entity, options));
+    }
+    return results;
+  }
+
+  registerInteractionClass<T extends object>(ctor: FomClassConstructor): InteractionClassAdapter<T> {
+    const adapter = this._ensureInteractionAdapterFromClass<T>(ctor);
+    if (this._runtimePrepared && this.rtiAmbassador) {
+      void this._prepareInteractionAdapter(adapter);
+    }
+    return adapter;
+  }
+
+  registerInteractionClasses(ctors: FomClassConstructor[]): InteractionClassAdapter<object>[] {
+    return ctors.map((ctor) => this.registerInteractionClass<object>(ctor));
+  }
+
+  registerObjectClass<T extends object>(ctor: FomClassConstructor): ObjectClassAdapter<T> {
+    const adapter = this._ensureObjectAdapterFromClass<T>(ctor);
+    if (this._runtimePrepared && this.rtiAmbassador) {
+      void this._prepareObjectAdapter(adapter);
+    }
+    return adapter;
+  }
+
+  registerObjectClasses(ctors: FomClassConstructor[]): ObjectClassAdapter<object>[] {
+    return ctors.map((ctor) => this.registerObjectClass<object>(ctor));
+  }
+
+  async register(...items: Array<SpacekitEntity<object> | FomClassConstructor>): Promise<void> {
+    for (const item of items) {
+      if (typeof item === "function") {
+        try {
+          this.registerObjectClass(item);
+          continue;
+        } catch {}
+        try {
+          this.registerInteractionClass(item);
+          continue;
+        } catch {}
+        throw new Error(`Unable to register class without schema metadata: ${item.name}`);
+      }
+      if (!this._runtimePrepared) {
+        void this.registerEntity(item);
+        continue;
+      }
+      await this.registerEntity(item);
+    }
+  }
+
+  async sendInteraction<T extends object>(
+    adapter: InteractionClassAdapter<T>,
+    values: Partial<T>,
+    userSuppliedTag: Uint8Array = new Uint8Array(),
+    time?: LogicalTime
+  ): Promise<void> {
+    const rti = this._requireRti();
+    if (!adapter.isResolved) {
+      await adapter.resolve(rti);
+    }
+    await adapter.send(rti, values, userSuppliedTag, time);
+    if (this._debugEnabled) {
+      this.logger.debug("Interaction sent.", { className: adapter.className, values, time });
+    }
+  }
+
+  async send<T extends object>(
+    target: InteractionClassAdapter<T> | FomClassConstructor,
+    values: Partial<T>,
+    userSuppliedTag: Uint8Array = new Uint8Array(),
+    time?: LogicalTime
+  ): Promise<void> {
+    const adapter =
+      target instanceof InteractionClassAdapter
+        ? target
+        : this.registerInteractionClass<T>(target);
+    await this.sendInteraction(adapter, values, userSuppliedTag, time);
+  }
+
+  async reply<T extends object>(
+    target: InteractionClassAdapter<T> | FomClassConstructor,
+    values: Partial<T>,
+    options: { tag?: Uint8Array; time?: LogicalTime } = {}
+  ): Promise<void> {
+    await this.send(target, values, options.tag ?? new Uint8Array(), options.time);
+  }
+
+  async respond<T extends object>(
+    target: InteractionClassAdapter<T> | FomClassConstructor,
+    values: Partial<T>,
+    options: { tag?: Uint8Array; time?: LogicalTime } = {}
+  ): Promise<void> {
+    await this.reply(target, values, options);
+  }
+
+  async updateObject<T extends object>(
+    instance: ObjectInstanceAdapter<T>,
+    values: Partial<T>,
+    userSuppliedTag: Uint8Array = new Uint8Array(),
+    time?: LogicalTime
+  ): Promise<void> {
+    const rti = this._requireRti();
+    await instance.updateAttributes(rti, values, userSuppliedTag, time);
+    if (this._debugEnabled) {
+      this.logger.debug("Object updated.", {
+        className: instance.className,
+        instanceName: instance.objectInstanceName ?? "(unnamed)",
+        values,
+        time,
+      });
+    }
+  }
+
+  async syncEntity<T extends object>(
+    entity: SpacekitEntity<T>,
+    time?: LogicalTime,
+    userSuppliedTag: Uint8Array = new Uint8Array()
+  ): Promise<void> {
+    const binding = getEntityBinding(entity);
+    if (!binding) {
+      throw new Error("Entity is not registered with this SpacekitApp.");
+    }
+    const changes = consumeEntityChanges(entity);
+    if (Object.keys(changes).length === 0) {
+      return;
+    }
+    await this.updateObject(binding.instance, changes, userSuppliedTag, time);
+  }
+
+  async sync(
+    entities?: SpacekitEntity<object> | Array<SpacekitEntity<object>>,
+    time?: LogicalTime,
+    userSuppliedTag: Uint8Array = new Uint8Array()
+  ): Promise<void> {
+    if (!entities) {
+      for (const entity of this._entities) {
+        await this.syncEntity(entity, time, userSuppliedTag);
+      }
+      return;
+    }
+    if (Array.isArray(entities)) {
+      for (const entity of entities) {
+        await this.syncEntity(entity, time, userSuppliedTag);
+      }
+      return;
+    }
+    await this.syncEntity(entities, time, userSuppliedTag);
+  }
+
+  async deleteObject<T extends object>(
+    instance: ObjectInstanceAdapter<T>,
+    userSuppliedTag: Uint8Array = new Uint8Array(),
+    time?: LogicalTime
+  ): Promise<void> {
+    const rti = this._requireRti();
+    await instance.deleteInstance(rti, userSuppliedTag, time);
+    this.logger.info("Deleted object instance.", {
+      className: instance.className,
+      instanceName: instance.objectInstanceName ?? "(unnamed)",
+    });
+  }
+
+  async advanceTo(timeMicros: bigint): Promise<bigint> {
+    const rti = this._requireRti();
+    if (this._debugEnabled) {
+      this.logger.debug("Requesting time advance.", { timeMicros: timeMicros.toString() });
+    }
+    const result = await this.timeController.advanceTo(rti, timeMicros);
+    if (this._debugEnabled) {
+      this.logger.debug("Time advance grant received.", { timeMicros: result.toString() });
+    }
+    return result;
+  }
+
+  async queryLogicalTimeMicros(): Promise<bigint> {
+    const rti = this._requireRti();
+    const logicalTime = await rti.queryLogicalTime();
+    return decodeHLAinteger64Time(logicalTime);
+  }
+
+  addHandlers(handlers: FederateHandlers): void {
+    this.federate.addHandlers(handlers);
+  }
+
+  protected async beforeRegisterEntity<T extends object>(_entity: SpacekitEntity<T>): Promise<void> {
+    return;
+  }
+
+  protected shouldRegisterClassInFom(_ctor: Function, _kind: "object" | "interaction"): boolean {
+    return true;
+  }
+
+  private get federateConfig(): SpacekitAppConfig {
+    return this._appConfig;
+  }
+
+  private _requireRti(): RTIAmbassador {
+    const rti = this.rtiAmbassador;
+    if (!rti) {
+      throw new Error("SpacekitApp is not started yet.");
+    }
+    return rti;
+  }
+
+  private async _flushPendingEntities(): Promise<void> {
+    if (this._pendingEntities.length === 0) return;
+    const pending = [...this._pendingEntities];
+    this._pendingEntities.length = 0;
+    for (const item of pending) {
+      try {
+        const instance = await this._registerEntityNow(item.entity, item.options);
+        item.resolve(instance);
+      } catch (err) {
+        item.reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+  }
+
+  private async _registerEntityNow<T extends object>(
+    entity: SpacekitEntity<T>,
+    options: RegisterObjectOptions = {}
+  ): Promise<ObjectInstanceAdapter<T>> {
+    await this.beforeRegisterEntity(entity);
+    const adapter = this._ensureObjectAdapterFromEntity(entity);
+    await this._prepareObjectAdapter(adapter);
+
+    const resolvedOptions = { ...options };
+    if (!resolvedOptions.name) {
+      const named = (entity as { name?: string }).name;
+      if (typeof named === "string" && named.length > 0) {
+        resolvedOptions.name = named;
+      }
+    }
+    if (resolvedOptions.reserveName === undefined && resolvedOptions.name) {
+      resolvedOptions.reserveName = true;
+    }
+
+    const instance = await this.registerObject(adapter, resolvedOptions);
+    bindEntity(entity, { app: this, adapter, instance });
+    this._entities.add(entity as unknown as SpacekitEntity<object>);
+    return instance;
+  }
+
+  private _ensureObjectAdapterFromEntity<T extends object>(
+    entity: SpacekitEntity<T>
+  ): ObjectClassAdapter<T> {
+    const ctor = entity.constructor as FomClassConstructor;
+    return this._ensureObjectAdapterFromClass(ctor);
+  }
+
+  private _ensureObjectAdapterFromClass<T extends object>(
+    ctor: FomClassConstructor
+  ): ObjectClassAdapter<T> {
+    const className = this._resolveObjectClassName(ctor);
+    if (!className) {
+      throw new Error(`Unable to resolve object class name for ${ctor.name}.`);
+    }
+    let adapter = this.declarative.getObjectAdapter<T>(className);
+    if (!adapter) {
+      const shouldRegister = this.shouldRegisterClassInFom(ctor, "object");
+      if (getDecoratedObjectClassMetadata(ctor)) {
+        registerDecoratedClasses(this.declarative, {
+          objectClasses: [ctor],
+          register: shouldRegister,
+        });
+      } else if (typeof (ctor as ObjectSchemaProvider<T>).schema === "function") {
+        const schema = (ctor as ObjectSchemaProvider<T>).schema!();
+        adapter = this.declarative.defineObjectClass(schema, { register: shouldRegister });
+      } else {
+        throw new Error(`Missing schema metadata for ${ctor.name}.`);
+      }
+      adapter = this.declarative.getObjectAdapter<T>(className);
+    }
+    if (!adapter) {
+      throw new Error(`Object adapter not found for ${className}.`);
+    }
+    return adapter;
+  }
+
+  private _ensureInteractionAdapterFromClass<T extends object>(
+    ctor: FomClassConstructor
+  ): InteractionClassAdapter<T> {
+    const className = this._resolveInteractionClassName(ctor);
+    if (!className) {
+      throw new Error(`Unable to resolve interaction class name for ${ctor.name}.`);
+    }
+    let adapter = this.declarative.getInteractionAdapter<T>(className);
+    if (!adapter) {
+      const shouldRegister = this.shouldRegisterClassInFom(ctor, "interaction");
+      if (getDecoratedInteractionClassMetadata(ctor)) {
+        registerDecoratedClasses(this.declarative, {
+          interactionClasses: [ctor],
+          register: shouldRegister,
+        });
+      } else if (typeof (ctor as InteractionSchemaProvider<T>).schema === "function") {
+        const schema = (ctor as InteractionSchemaProvider<T>).schema!();
+        adapter = this.declarative.defineInteractionClass(schema, { register: shouldRegister });
+      } else {
+        throw new Error(`Missing schema metadata for ${ctor.name}.`);
+      }
+      adapter = this.declarative.getInteractionAdapter<T>(className);
+    }
+    if (!adapter) {
+      throw new Error(`Interaction adapter not found for ${className}.`);
+    }
+    return adapter;
+  }
+
+  private async _prepareObjectAdapter<T extends object>(
+    adapter: ObjectClassAdapter<T>
+  ): Promise<void> {
+    if (!this._runtimePrepared || !this.rtiAmbassador) return;
+    if (!adapter.isResolved) {
+      await adapter.resolve(this.rtiAmbassador);
+    }
+    const schema = this.declarative.getObjectSchema<T>(adapter.className);
+    if (!schema?.sharing) return;
+    if (shouldPublish(schema.sharing)) {
+      await adapter.publish(this.rtiAmbassador);
+    }
+    if (shouldSubscribe(schema.sharing)) {
+      await adapter.subscribe(this.rtiAmbassador);
+    }
+  }
+
+  private async _prepareInteractionAdapter<T extends object>(
+    adapter: InteractionClassAdapter<T>
+  ): Promise<void> {
+    if (!this._runtimePrepared || !this.rtiAmbassador) return;
+    if (!adapter.isResolved) {
+      await adapter.resolve(this.rtiAmbassador);
+    }
+    const schema = this.declarative.getInteractionSchema<T>(adapter.className);
+    if (!schema?.sharing) return;
+    if (shouldPublish(schema.sharing)) {
+      await adapter.publish(this.rtiAmbassador);
+    }
+    if (shouldSubscribe(schema.sharing)) {
+      await adapter.subscribe(this.rtiAmbassador);
+    }
+  }
+
+  private _resolveObjectClassName(ctor: Function): string | undefined {
+    const direct =
+      (ctor as { className?: string }).className ??
+      getDecoratedObjectClassName(ctor) ??
+      getDecoratedObjectClassMetadata(ctor)?.name;
+    if (direct) return direct;
+    const provider = ctor as ObjectSchemaProvider<object>;
+    if (typeof provider.schema === "function") {
+      return provider.schema().name;
+    }
+    return undefined;
+  }
+
+  private _resolveInteractionClassName(ctor: Function): string | undefined {
+    const direct =
+      (ctor as { className?: string }).className ??
+      getDecoratedInteractionClassName(ctor) ??
+      getDecoratedInteractionClassMetadata(ctor)?.name;
+    if (direct) return direct;
+    const provider = ctor as InteractionSchemaProvider<object>;
+    if (typeof provider.schema === "function") {
+      return provider.schema().name;
+    }
+    return undefined;
+  }
+
+  private _createReservationHandlers(): FederateHandlers {
+    return {
+      objectInstanceNameReservationSucceeded: (name) => {
+        const pending = this._pendingReservations.get(name);
+        if (!pending) return;
+        if (pending.timeout) clearTimeout(pending.timeout);
+        pending.resolve();
+        this._pendingReservations.delete(name);
+        this.logger.info("Object instance name reserved.", { name });
+      },
+      objectInstanceNameReservationFailed: (name) => {
+        const pending = this._pendingReservations.get(name);
+        if (!pending) return;
+        if (pending.timeout) clearTimeout(pending.timeout);
+        pending.reject(new Error(`Object instance name reservation failed: ${name}`));
+        this._pendingReservations.delete(name);
+        this.logger.error("Object instance name reservation failed.", { name });
+      },
+    };
+  }
+
+  private _logPublicationSummary(summary: DeclarativePublicationSummary): void {
+    this.logger.info("Publish/subscribe configured.", {
+      objectPublish: summary.objectClasses.publish,
+      objectSubscribe: summary.objectClasses.subscribe,
+      interactionPublish: summary.interactions.publish,
+      interactionSubscribe: summary.interactions.subscribe,
+    });
+  }
+
+  private _resolveFomExportPath(override?: string): string {
+    if (override) return path.resolve(override);
+    const federateType = this.federateConfig.federate.federateType;
+    return path.resolve("fom", `${federateType}.xml`);
+  }
+
+  private _buildFomXml(options: {
+    format: FomOutputFormat;
+    modelIdentification?: ModelIdentification;
+    indent?: string;
+    inferParentStubs?: boolean;
+  }): string {
+    const extension = this.federateConfig.federate.fom?.extension;
+    if (extension?.xml) {
+      return extension.xml;
+    }
+    if (extension?.registry) {
+      return this._registryToXml(extension.registry, options);
+    }
+    if (extension?.model) {
+      return this._modelToXml(extension.model, options);
+    }
+    return this._registryToXml(this.declarative.registry, options);
+  }
+
+  private _registryToXml(
+    registry: import("@hla4ts/fom-codegen").FomRegistry,
+    options: {
+      format: FomOutputFormat;
+      modelIdentification?: ModelIdentification;
+      indent?: string;
+      inferParentStubs?: boolean;
+    }
+  ): string {
+    const outputOptions: FomOutputOptions = {
+      format: options.format,
+      indent: options.indent,
+      inferParentStubs: options.inferParentStubs,
+    };
+    if (options.format === "omt" && options.modelIdentification) {
+      registry.setModelIdentification(options.modelIdentification);
+    }
+    if (options.format === "omt" && !options.modelIdentification) {
+      registry.setModelIdentification(this._defaultModelIdentification());
+    }
+    return registry.toXml(outputOptions);
+  }
+
+  private _modelToXml(
+    model: FomModel,
+    options: {
+      format: FomOutputFormat;
+      modelIdentification?: ModelIdentification;
+      indent?: string;
+      inferParentStubs?: boolean;
+    }
+  ): string {
+    const outputOptions: FomOutputOptions = {
+      format: options.format,
+      indent: options.indent,
+      inferParentStubs: options.inferParentStubs,
+    };
+    if (options.format === "omt") {
+      const modelIdentification = options.modelIdentification ?? this._defaultModelIdentification();
+      const merged: FomModel = { ...model, modelIdentification };
+      return renderFomXml(merged, outputOptions);
+    }
+    return renderFomXml(model, outputOptions);
+  }
+
+  private _defaultModelIdentification(): ModelIdentification {
+    const federateType = this.federateConfig.federate.federateType;
+    const now = new Date();
+    const y = now.getUTCFullYear();
+    const m = String(now.getUTCMonth() + 1).padStart(2, "0");
+    const d = String(now.getUTCDate()).padStart(2, "0");
+    return {
+      name: `${federateType}-extension`,
+      type: "FOM",
+      version: "1.0.0",
+      modificationDate: `${y}-${m}-${d}`,
+      securityClassification: "U",
+      description: "Generated by @hla4ts/spacekit",
+    };
+  }
+}
+
+function shouldPublish(sharing: SharingType): boolean {
+  return sharing === "Publish" || sharing === "PublishSubscribe";
+}
+
+function shouldSubscribe(sharing: SharingType): boolean {
+  return sharing === "Subscribe" || sharing === "PublishSubscribe";
+}