@hla4ts/spacekit 0.1.0

package/src/spacefom-bootstrap.ts

@@ -0,0 +1,596 @@
+import {
+  decodeHLAinteger64Time,
+  encodeHLAinteger64Interval,
+  encodeHLAinteger64Time,
+  handleToHex,
+  type AttributeHandleValueMap,
+  type LogicalTime,
+  type LogicalTimeInterval,
+  type ObjectInstanceHandle,
+  type RTIAmbassador,
+} from "@hla4ts/hla-api";
+import type { FederateHandlers } from "./types.ts";
+import { buildDeclarativeFomFromDecorators } from "./decorators.ts";
+import type {
+  DynamicalEntityAttributes,
+  ExecutionConfigurationAttributes,
+  PhysicalEntityAttributes,
+  ReferenceFrameAttributes,
+} from "./spacefom-entities.ts";
+import { ExecutionConfiguration, ReferenceFrame, PhysicalEntity, DynamicalEntity } from "./spacefom-entities.ts";
+import {
+  SpaceFomExecutionMode,
+  SpaceFomSyncPointLabels,
+  type SpaceTimeCoordinateState,
+} from "@hla4ts/spacefom";
+
+export interface SpaceFomLateJoinerOptions {
+  syncPoints?: {
+    initializationCompleted?: string;
+    shutdown?: string;
+    mtrRun?: string;
+    mtrFreeze?: string;
+  };
+  waitForInitializationCompleted?: boolean;
+  autoCompleteInitialization?: boolean;
+  subscribeExecutionConfiguration?: boolean;
+  subscribeReferenceFrame?: boolean;
+  subscribePhysicalEntity?: boolean;
+  subscribeDynamicalEntity?: boolean;
+  requestAttributeUpdates?: boolean;
+  waitForExco?: boolean;
+  waitForReferenceFrameTree?: boolean;
+  referenceFrameTimeoutMs?: number;
+  enableTimeManagement?: boolean;
+  lookaheadMicros?: bigint;
+  advanceToHltb?: boolean;
+  awaitTimeAdvanceGrant?: boolean;
+  onExecutionConfigurationUpdate?: (payload: {
+    state: SpaceFomBootstrapState;
+  }) => void;
+  onExecutionModeChange?: (payload: {
+    current: SpaceFomExecutionMode;
+    next?: SpaceFomExecutionMode;
+    previousCurrent?: SpaceFomExecutionMode;
+    previousNext?: SpaceFomExecutionMode;
+    state: SpaceFomBootstrapState;
+  }) => void;
+  onTimeRegulationEnabled?: (payload: {
+    timeMicros: bigint;
+    state: SpaceFomBootstrapState;
+  }) => void;
+  onTimeConstrainedEnabled?: (payload: {
+    timeMicros: bigint;
+    state: SpaceFomBootstrapState;
+  }) => void;
+  onTimeAdvanceGrant?: (payload: {
+    timeMicros: bigint;
+    state: SpaceFomBootstrapState;
+  }) => void;
+}
+
+type SpaceFomLateJoinerOptionsResolved = Required<
+  Omit<
+    SpaceFomLateJoinerOptions,
+    | "onExecutionConfigurationUpdate"
+    | "onExecutionModeChange"
+    | "onTimeRegulationEnabled"
+    | "onTimeConstrainedEnabled"
+    | "onTimeAdvanceGrant"
+  >
+> &
+  Pick<
+    SpaceFomLateJoinerOptions,
+    | "onExecutionConfigurationUpdate"
+    | "onExecutionModeChange"
+    | "onTimeRegulationEnabled"
+    | "onTimeConstrainedEnabled"
+    | "onTimeAdvanceGrant"
+  >;
+
+export interface SpaceFomReferenceFrameSnapshot {
+  objectInstance: ObjectInstanceHandle;
+  name?: string;
+  parentName?: string;
+  state?: SpaceTimeCoordinateState;
+}
+
+export interface SpaceFomBootstrapState {
+  excoInstance?: ObjectInstanceHandle;
+  rootFrameName?: string;
+  scenarioTimeEpoch?: number;
+  lctsMicros?: bigint;
+  currentExecutionMode?: SpaceFomExecutionMode;
+  nextExecutionMode?: SpaceFomExecutionMode;
+  nextModeScenarioTime?: number;
+  nextModeCteTime?: number;
+  initializationCompletedAnnounced?: boolean;
+  initializationCompletedAuto?: boolean;
+  shutdownAnnounced?: boolean;
+  mtrRunAnnounced?: boolean;
+  mtrFreezeAnnounced?: boolean;
+  referenceFrameTreeReady?: boolean;
+  lastGrantedTimeMicros?: bigint;
+  timeRegulationEnabledTimeMicros?: bigint;
+  timeConstrainedEnabledTimeMicros?: bigint;
+  referenceFrames?: SpaceFomReferenceFrameSnapshot[];
+}
+
+interface SpaceFomReferenceFrameRecord extends SpaceFomReferenceFrameSnapshot {
+  key: string;
+}
+
+const SPACEFOM_DECLARATIVE = buildDeclarativeFomFromDecorators({
+  objectClasses: [ExecutionConfiguration, ReferenceFrame, PhysicalEntity, DynamicalEntity],
+  register: false,
+});
+
+export class SpaceFomLateJoinerBootstrap {
+  readonly handlers: FederateHandlers;
+  private readonly _options: SpaceFomLateJoinerOptionsResolved;
+  private _initCompletedResolve!: () => void;
+  private _initCompletedReject!: (err: Error) => void;
+  private _timeRegulationResolve!: () => void;
+  private _timeConstrainedResolve!: () => void;
+  private _timeAdvanceResolve?: () => void;
+  private _excoReadyResolve!: () => void;
+  private _referenceFrameReadyResolve!: () => void;
+  private _shutdownTriggered = false;
+  private _excoReady = false;
+  private _referenceFrameTreeReady = false;
+  private _initCompletedResolved = false;
+  private _initCompletedPromise: Promise<void>;
+  private _timeRegulationPromise: Promise<void>;
+  private _timeConstrainedPromise: Promise<void>;
+  private _timeAdvancePromise: Promise<void> | null = null;
+  private _excoReadyPromise: Promise<void>;
+  private _referenceFrameReadyPromise: Promise<void>;
+  private _state: SpaceFomBootstrapState = {};
+  private readonly _executionConfiguration = SPACEFOM_DECLARATIVE.getObjectAdapter<ExecutionConfigurationAttributes>(ExecutionConfiguration.className)!;
+  private readonly _referenceFrame = SPACEFOM_DECLARATIVE.getObjectAdapter<ReferenceFrameAttributes>(ReferenceFrame.className)!;
+  private readonly _physicalEntity = SPACEFOM_DECLARATIVE.getObjectAdapter<PhysicalEntityAttributes>(PhysicalEntity.className)!;
+  private readonly _dynamicalEntity = SPACEFOM_DECLARATIVE.getObjectAdapter<DynamicalEntityAttributes>(DynamicalEntity.className)!;
+  private readonly _referenceFramesByInstance = new Map<string, SpaceFomReferenceFrameRecord>();
+  private readonly _referenceFramesByName = new Map<string, SpaceFomReferenceFrameRecord>();
+
+  constructor(options: SpaceFomLateJoinerOptions = {}) {
+    this._options = {
+      syncPoints: {
+        initializationCompleted:
+          options.syncPoints?.initializationCompleted ??
+          SpaceFomSyncPointLabels.initializationCompleted,
+        shutdown: options.syncPoints?.shutdown ?? SpaceFomSyncPointLabels.mtrShutdown,
+        mtrRun: options.syncPoints?.mtrRun ?? SpaceFomSyncPointLabels.mtrRun,
+        mtrFreeze: options.syncPoints?.mtrFreeze ?? SpaceFomSyncPointLabels.mtrFreeze,
+      },
+      waitForInitializationCompleted: options.waitForInitializationCompleted ?? false,
+      autoCompleteInitialization: options.autoCompleteInitialization ?? true,
+      subscribeExecutionConfiguration: options.subscribeExecutionConfiguration ?? true,
+      subscribeReferenceFrame: options.subscribeReferenceFrame ?? true,
+      subscribePhysicalEntity: options.subscribePhysicalEntity ?? true,
+      subscribeDynamicalEntity: options.subscribeDynamicalEntity ?? true,
+      requestAttributeUpdates: options.requestAttributeUpdates ?? true,
+      waitForExco: options.waitForExco ?? true,
+      waitForReferenceFrameTree: options.waitForReferenceFrameTree ?? true,
+      referenceFrameTimeoutMs: options.referenceFrameTimeoutMs ?? 0,
+      enableTimeManagement: options.enableTimeManagement ?? true,
+      lookaheadMicros: options.lookaheadMicros ?? 1_000_000n,
+      advanceToHltb: options.advanceToHltb ?? true,
+      awaitTimeAdvanceGrant: options.awaitTimeAdvanceGrant ?? true,
+      onExecutionConfigurationUpdate: options.onExecutionConfigurationUpdate,
+      onExecutionModeChange: options.onExecutionModeChange,
+      onTimeRegulationEnabled: options.onTimeRegulationEnabled,
+      onTimeConstrainedEnabled: options.onTimeConstrainedEnabled,
+      onTimeAdvanceGrant: options.onTimeAdvanceGrant,
+    };
+
+    this._initCompletedPromise = new Promise((resolve, reject) => {
+      this._initCompletedResolve = resolve;
+      this._initCompletedReject = reject;
+    });
+    this._timeRegulationPromise = new Promise((resolve) => {
+      this._timeRegulationResolve = resolve;
+    });
+    this._timeConstrainedPromise = new Promise((resolve) => {
+      this._timeConstrainedResolve = resolve;
+    });
+    this._excoReadyPromise = new Promise((resolve) => {
+      this._excoReadyResolve = resolve;
+    });
+    this._referenceFrameReadyPromise = new Promise((resolve) => {
+      this._referenceFrameReadyResolve = resolve;
+    });
+
+    this.handlers = {
+      announceSynchronizationPoint: (label) => {
+        if (label === this._options.syncPoints.shutdown) {
+          this._shutdownTriggered = true;
+          this._state.shutdownAnnounced = true;
+          if (!this._initCompletedResolved) {
+            this._initCompletedReject(
+              new Error("Federation shutting down (mtr_shutdown announced).")
+            );
+          }
+          return;
+        }
+        if (label === this._options.syncPoints.initializationCompleted) {
+          this._state.initializationCompletedAnnounced = true;
+          this._resolveInitializationCompleted();
+        }
+        if (label === this._options.syncPoints.mtrRun) {
+          this._state.mtrRunAnnounced = true;
+        }
+        if (label === this._options.syncPoints.mtrFreeze) {
+          this._state.mtrFreezeAnnounced = true;
+        }
+      },
+      discoverObjectInstance: (objectInstance, objectClass, objectInstanceName) => {
+        if (this._executionConfiguration.isResolved) {
+          const excoHandle = this._executionConfiguration.classHandle;
+          if (handleToHex(objectClass) === handleToHex(excoHandle)) {
+            this._state.excoInstance = objectInstance;
+            return;
+          }
+        }
+        if (this._referenceFrame.isResolved) {
+          const frameHandle = this._referenceFrame.classHandle;
+          if (handleToHex(objectClass) === handleToHex(frameHandle)) {
+            this._registerReferenceFrame(objectInstance, objectInstanceName);
+          }
+        }
+      },
+      reflectAttributeValues: (objectInstance, attributeValues) => {
+        this._applyAttributes(objectInstance, attributeValues);
+      },
+      reflectAttributeValuesWithTime: (objectInstance, attributeValues) => {
+        this._applyAttributes(objectInstance, attributeValues);
+      },
+      timeRegulationEnabled: (time) => {
+        this._state.timeRegulationEnabledTimeMicros = decodeHLAinteger64Time(time);
+        this._timeRegulationResolve();
+        this._options.onTimeRegulationEnabled?.({
+          timeMicros: this._state.timeRegulationEnabledTimeMicros,
+          state: this.state,
+        });
+      },
+      timeConstrainedEnabled: (time) => {
+        this._state.timeConstrainedEnabledTimeMicros = decodeHLAinteger64Time(time);
+        this._timeConstrainedResolve();
+        this._options.onTimeConstrainedEnabled?.({
+          timeMicros: this._state.timeConstrainedEnabledTimeMicros,
+          state: this.state,
+        });
+      },
+      timeAdvanceGrant: (time) => {
+        this._state.lastGrantedTimeMicros = decodeHLAinteger64Time(time);
+        if (this._timeAdvanceResolve) {
+          this._timeAdvanceResolve();
+          this._timeAdvanceResolve = undefined;
+          this._timeAdvancePromise = null;
+        }
+        this._options.onTimeAdvanceGrant?.({
+          timeMicros: this._state.lastGrantedTimeMicros,
+          state: this.state,
+        });
+      },
+    };
+  }
+
+  get state(): SpaceFomBootstrapState {
+    return {
+      ...this._state,
+      referenceFrames: Array.from(this._referenceFramesByInstance.values()).map((frame) => ({
+        objectInstance: frame.objectInstance,
+        name: frame.name,
+        parentName: frame.parentName,
+        state: frame.state,
+      })),
+    };
+  }
+
+  async run(rti: RTIAmbassador): Promise<SpaceFomBootstrapState> {
+    if (this._shutdownTriggered) {
+      throw new Error("Shutdown sync point already announced.");
+    }
+    if (this._options.waitForExco && !this._options.subscribeExecutionConfiguration) {
+      throw new Error("waitForExco requires subscribeExecutionConfiguration.");
+    }
+    if (this._options.waitForReferenceFrameTree && !this._options.subscribeReferenceFrame) {
+      throw new Error("waitForReferenceFrameTree requires subscribeReferenceFrame.");
+    }
+    if (this._options.advanceToHltb && !this._options.enableTimeManagement) {
+      throw new Error("advanceToHltb requires enableTimeManagement.");
+    }
+    if (this._options.advanceToHltb && !this._options.subscribeExecutionConfiguration) {
+      throw new Error("advanceToHltb requires subscribeExecutionConfiguration.");
+    }
+
+    await this._resolveHandles(rti);
+    await this._subscribe(rti);
+    if (this._options.requestAttributeUpdates) {
+      await this._requestAttributeUpdates(rti);
+    }
+
+    if (this._options.waitForInitializationCompleted) {
+      await this._initCompletedPromise;
+      this._throwIfShutdown();
+    }
+    if (this._options.waitForExco) {
+      await this._excoReadyPromise;
+      this._throwIfShutdown();
+    }
+    if (this._options.waitForReferenceFrameTree) {
+      await this._waitForReferenceFrameTree();
+      this._throwIfShutdown();
+    }
+    if (this._options.enableTimeManagement) {
+      await this._enableTimeManagement(rti);
+      this._throwIfShutdown();
+    }
+    if (this._options.advanceToHltb) {
+      await this._advanceToHltb(rti);
+      this._throwIfShutdown();
+    }
+    return this.state;
+  }
+
+  private _throwIfShutdown(): void {
+    if (this._shutdownTriggered) {
+      throw new Error("Federation shutting down (mtr_shutdown announced).");
+    }
+  }
+
+  private async _resolveHandles(rti: RTIAmbassador): Promise<void> {
+    if (this._options.subscribeExecutionConfiguration) {
+      await this._executionConfiguration.resolve(rti);
+    }
+    if (this._options.subscribeReferenceFrame) {
+      await this._referenceFrame.resolve(rti);
+    }
+    if (this._options.subscribePhysicalEntity) {
+      await this._physicalEntity.resolve(rti);
+    }
+    if (this._options.subscribeDynamicalEntity) {
+      await this._dynamicalEntity.resolve(rti);
+    }
+  }
+
+  private async _subscribe(rti: RTIAmbassador): Promise<void> {
+    if (this._options.subscribeExecutionConfiguration) {
+      await this._executionConfiguration.subscribe(rti);
+    }
+    if (this._options.subscribeReferenceFrame) {
+      await this._referenceFrame.subscribe(rti);
+    }
+    if (this._options.subscribePhysicalEntity) {
+      await this._physicalEntity.subscribe(rti);
+    }
+    if (this._options.subscribeDynamicalEntity) {
+      await this._dynamicalEntity.subscribe(rti);
+    }
+  }
+
+  private async _requestAttributeUpdates(rti: RTIAmbassador): Promise<void> {
+    const tag = new Uint8Array();
+    if (this._options.subscribeExecutionConfiguration) {
+      await rti.requestClassAttributeValueUpdate(
+        this._executionConfiguration.classHandle,
+        this._executionConfiguration.attributeHandleSet,
+        tag
+      );
+    }
+    if (this._options.subscribeReferenceFrame) {
+      await rti.requestClassAttributeValueUpdate(
+        this._referenceFrame.classHandle,
+        this._referenceFrame.attributeHandleSet,
+        tag
+      );
+    }
+  }
+
+  private _applyAttributes(objectInstance: ObjectInstanceHandle, values: AttributeHandleValueMap): void {
+    if (this._state.excoInstance && handleToHex(objectInstance) === handleToHex(this._state.excoInstance)) {
+      this._applyExcoAttributes(values);
+      return;
+    }
+    const refFrameKey = handleToHex(objectInstance);
+    if (this._referenceFramesByInstance.has(refFrameKey)) {
+      this._applyReferenceFrameAttributes(refFrameKey, values);
+    }
+  }
+
+  private _applyExcoAttributes(values: AttributeHandleValueMap): void {
+    const decoded = this._executionConfiguration.decode(values) as Partial<ExecutionConfigurationAttributes>;
+    const previousCurrent = this._state.currentExecutionMode;
+    const previousNext = this._state.nextExecutionMode;
+
+    if (decoded.root_frame_name !== undefined) this._state.rootFrameName = decoded.root_frame_name;
+    if (decoded.scenario_time_epoch !== undefined) this._state.scenarioTimeEpoch = decoded.scenario_time_epoch;
+    if (decoded.current_execution_mode !== undefined) {
+      this._state.currentExecutionMode = decoded.current_execution_mode as SpaceFomExecutionMode;
+    }
+    if (decoded.next_execution_mode !== undefined) {
+      this._state.nextExecutionMode = decoded.next_execution_mode as SpaceFomExecutionMode;
+    }
+    if (decoded.next_mode_scenario_time !== undefined) this._state.nextModeScenarioTime = decoded.next_mode_scenario_time;
+    if (decoded.next_mode_cte_time !== undefined) this._state.nextModeCteTime = decoded.next_mode_cte_time;
+    if (decoded.least_common_time_step !== undefined) this._state.lctsMicros = decoded.least_common_time_step;
+
+    if (
+      (decoded.current_execution_mode !== undefined &&
+        decoded.current_execution_mode !== previousCurrent) ||
+      (decoded.next_execution_mode !== undefined &&
+        decoded.next_execution_mode !== previousNext)
+    ) {
+      if (this._state.currentExecutionMode !== undefined) {
+        this._options.onExecutionModeChange?.({
+          current: this._state.currentExecutionMode,
+          next: this._state.nextExecutionMode,
+          previousCurrent,
+          previousNext,
+          state: this.state,
+        });
+      }
+    }
+
+    this._options.onExecutionConfigurationUpdate?.({ state: this.state });
+    this._autoResolveInitializationIfNeeded();
+    this._checkExcoReady();
+    this._checkReferenceFrameTreeReady();
+  }
+
+  private _registerReferenceFrame(objectInstance: ObjectInstanceHandle, objectInstanceName?: string): void {
+    const key = handleToHex(objectInstance);
+    if (this._referenceFramesByInstance.has(key)) return;
+    const record: SpaceFomReferenceFrameRecord = {
+      key,
+      objectInstance,
+      name: objectInstanceName,
+    };
+    this._referenceFramesByInstance.set(key, record);
+    if (record.name) {
+      this._referenceFramesByName.set(record.name, record);
+    }
+  }
+
+  private _applyReferenceFrameAttributes(instanceKey: string, values: AttributeHandleValueMap): void {
+    const record = this._referenceFramesByInstance.get(instanceKey);
+    if (!record) return;
+    const decoded = this._referenceFrame.decode(values) as Partial<ReferenceFrameAttributes>;
+    const previousName = record.name;
+
+    if (decoded.name !== undefined) record.name = decoded.name;
+    if (decoded.parent_name !== undefined) record.parentName = decoded.parent_name;
+    if (decoded.state !== undefined) record.state = decoded.state;
+
+    if (record.name && record.name !== previousName) {
+      if (previousName) {
+        this._referenceFramesByName.delete(previousName);
+      }
+      this._referenceFramesByName.set(record.name, record);
+    } else if (record.name && !this._referenceFramesByName.has(record.name)) {
+      this._referenceFramesByName.set(record.name, record);
+    }
+
+    this._checkReferenceFrameTreeReady();
+  }
+
+  private _checkExcoReady(): void {
+    if (this._excoReady) return;
+    const hasLcts = this._state.lctsMicros !== undefined;
+    const hasExecutionMode = this._state.currentExecutionMode !== undefined;
+    const hasRootFrame = !this._options.waitForReferenceFrameTree || !!this._state.rootFrameName;
+    if (hasLcts && hasExecutionMode && hasRootFrame) {
+      this._excoReady = true;
+      this._excoReadyResolve();
+    }
+  }
+
+  private _checkReferenceFrameTreeReady(): void {
+    if (this._referenceFrameTreeReady) return;
+    if (!this._options.waitForReferenceFrameTree) return;
+    const rootName = this._state.rootFrameName;
+    if (!rootName) return;
+    const rootFrame = this._referenceFramesByName.get(rootName);
+    if (!rootFrame) return;
+
+    for (const frame of this._referenceFramesByName.values()) {
+      if (!frame.name) continue;
+      let current: SpaceFomReferenceFrameRecord | undefined = frame;
+      const visited = new Set<string>();
+      while (current?.parentName) {
+        if (visited.has(current.parentName)) return;
+        visited.add(current.parentName);
+        const parent = this._referenceFramesByName.get(current.parentName);
+        if (!parent) return;
+        current = parent;
+      }
+    }
+
+    this._referenceFrameTreeReady = true;
+    this._state.referenceFrameTreeReady = true;
+    this._referenceFrameReadyResolve();
+  }
+
+  private _autoResolveInitializationIfNeeded(): void {
+    if (this._initCompletedResolved || !this._options.autoCompleteInitialization) return;
+    const mode = this._state.currentExecutionMode;
+    if (
+      mode === undefined ||
+      mode === SpaceFomExecutionMode.Uninitialized ||
+      mode === SpaceFomExecutionMode.Initializing
+    ) {
+      return;
+    }
+    this._state.initializationCompletedAuto = true;
+    this._resolveInitializationCompleted();
+  }
+
+  private _resolveInitializationCompleted(): void {
+    if (this._initCompletedResolved) return;
+    this._initCompletedResolved = true;
+    this._initCompletedResolve();
+  }
+
+  private async _waitForReferenceFrameTree(): Promise<void> {
+    if (this._referenceFrameTreeReady) return;
+    const timeoutMs = this._options.referenceFrameTimeoutMs;
+    if (timeoutMs <= 0) {
+      await this._referenceFrameReadyPromise;
+      return;
+    }
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error("Timed out waiting for reference frame tree."));
+      }, timeoutMs);
+      this._referenceFrameReadyPromise
+        .then(() => {
+          clearTimeout(timer);
+          resolve();
+        })
+        .catch((err) => {
+          clearTimeout(timer);
+          reject(err);
+        });
+    });
+  }
+
+  private async _enableTimeManagement(rti: RTIAmbassador): Promise<void> {
+    const lookahead: LogicalTimeInterval = encodeHLAinteger64Interval(this._options.lookaheadMicros);
+    await rti.enableTimeRegulation(lookahead);
+    await rti.enableTimeConstrained();
+    await Promise.all([this._timeRegulationPromise, this._timeConstrainedPromise]);
+  }
+
+  private async _advanceToHltb(rti: RTIAmbassador): Promise<void> {
+    if (!this._state.lctsMicros) {
+      throw new Error("ExCO least_common_time_step not received; cannot compute HLTB.");
+    }
+    const galt = await rti.queryGALT();
+    if (!galt.logicalTimeIsValid || !galt.logicalTime) {
+      throw new Error("GALT not valid; cannot compute HLTB.");
+    }
+    const galtMicros = decodeHLAinteger64Time(galt.logicalTime);
+    const hltbMicros = computeHltb(galtMicros, this._state.lctsMicros);
+    const time: LogicalTime = encodeHLAinteger64Time(hltbMicros);
+
+    if (this._options.awaitTimeAdvanceGrant) {
+      this._timeAdvancePromise = new Promise((resolve) => {
+        this._timeAdvanceResolve = resolve;
+      });
+    }
+
+    await rti.timeAdvanceRequest(time);
+
+    if (this._options.awaitTimeAdvanceGrant && this._timeAdvancePromise) {
+      await this._timeAdvancePromise;
+    }
+  }
+}
+
+export function computeHltb(galtMicros: bigint, lctsMicros: bigint): bigint {
+  if (lctsMicros <= 0n) {
+    throw new Error("LCTS must be positive.");
+  }
+  return ((galtMicros / lctsMicros) + 1n) * lctsMicros;
+}

package/src/spacefom-config.ts

@@ -0,0 +1,25 @@
+import { parseSpacekitEnv, type SpacekitEnvDefaults } from "./env.ts";
+import type { SpacekitAppOptions } from "./see-app.ts";
+
+export interface SpaceFomConfigOptions<T extends Record<string, unknown>> {
+  env?: Record<string, string | undefined>;
+  envDefaults?: SpacekitEnvDefaults;
+  app?: Partial<SpacekitAppOptions>;
+  extras?: (env: Record<string, string | undefined>) => T;
+}
+
+export function createSpaceFomConfig<T extends Record<string, unknown> = Record<string, never>>(
+  options: SpaceFomConfigOptions<T> = {}
+): { app: SpacekitAppOptions } & T {
+  const env = options.env ?? process.env;
+  const base = parseSpacekitEnv({
+    env,
+    defaults: options.envDefaults,
+  });
+  const app: SpacekitAppOptions = {
+    ...base,
+    ...options.app,
+  };
+  const extras = options.extras ? options.extras(env) : ({} as T);
+  return { app, ...extras };
+}

package/src/spacefom-decorators.test.ts

@@ -0,0 +1,27 @@
+import { expect, test } from "bun:test";
+import { buildDeclarativeFomFromDecorators } from "./decorators.ts";
+import { ModeTransitionRequest } from "./spacefom-interactions.ts";
+import { PhysicalEntity } from "./spacefom-entities.ts";
+
+test("ModeTransitionRequest decorator metadata builds schema", () => {
+  const declarative = buildDeclarativeFomFromDecorators({
+    interactionClasses: [ModeTransitionRequest],
+  });
+
+  const schema = declarative.getInteractionSchema<{ execution_mode: number }>(
+    "HLAinteractionRoot.ModeTransitionRequest"
+  );
+  expect(schema?.parameters.execution_mode?.dataType).toBe("HLAinteger16LE");
+});
+
+test("PhysicalEntity decorator metadata builds canonical schema", () => {
+  const declarative = buildDeclarativeFomFromDecorators({
+    objectClasses: [PhysicalEntity],
+  });
+
+  const schema = declarative.getObjectSchema<{ parent_reference_frame: string; state: unknown }>(
+    "HLAobjectRoot.PhysicalEntity"
+  );
+  expect(schema?.attributes.parent_reference_frame?.dataType).toBe("HLAunicodeString");
+  expect(schema?.attributes.state?.dataType).toBe("SpaceTimeCoordinateState");
+});