space-data-module-sdk 0.8.11 → 0.8.13

package/src/generated/orbpro/propagator-abi.js

@@ -0,0 +1,118 @@
+// ===========================================================================
+// GENERATED FILE — DO NOT EDIT.
+//
+// Source of truth : schemas/orbpro/Propagator.fbs
+// Generator       : scripts/generate-propagator-abi.mjs
+// Drift gate      : scripts/check-propagator-abi.mjs  (runs in `npm test`)
+// Contract        : docs/propagator-abi.md
+//
+// These constants exist so that no JavaScript consumer ever hard-codes a byte
+// offset again. Read a state vector with ORBPRO_STATE_VECTOR.offsets.position,
+// never with the literal 8.
+// ===========================================================================
+
+export const ReferenceFrame = Object.freeze({
+  TEME: 0,
+  J2000: 1,
+  ICRF: 2,
+  ECEF: 3,
+  MCI: 4,
+  MCMF: 5,
+});
+
+export const StateFlags = Object.freeze({
+  NONE: 0,
+  VALID: 1,
+  IN_ECLIPSE: 2,
+  DECAYED: 4,
+  MANEUVERING: 8,
+  EXTRAPOLATED: 16,
+  HAS_COVARIANCE: 32,
+});
+
+export const ORBPRO_STATE_VECTOR = Object.freeze({
+  name: "StateVector",
+  cName: "OrbProStateVector",
+  size: 64,
+  alignment: 8,
+  offsets: Object.freeze({
+    epoch: 0,
+    position: 8,
+    velocity: 32,
+    reference_frame: 56,
+    flags: 60,
+  }),
+  fields: Object.freeze({
+    epoch: Object.freeze({ offset: 0, size: 8, length: 1, view: "Float64" }),
+    position: Object.freeze({ offset: 8, size: 24, length: 3, view: "Float64" }),
+    velocity: Object.freeze({ offset: 32, size: 24, length: 3, view: "Float64" }),
+    reference_frame: Object.freeze({ offset: 56, size: 1, length: 1, view: "Uint8" }),
+    flags: Object.freeze({ offset: 60, size: 4, length: 1, view: "Uint32" }),
+  }),
+});
+
+export const ORBPRO_ORBITAL_ELEMENTS = Object.freeze({
+  name: "OrbitalElements",
+  cName: "OrbProOrbitalElements",
+  size: 64,
+  alignment: 8,
+  offsets: Object.freeze({
+    semi_major_axis: 0,
+    eccentricity: 8,
+    inclination: 16,
+    raan: 24,
+    arg_periapsis: 32,
+    true_anomaly: 40,
+    epoch: 48,
+    reserved: 56,
+  }),
+  fields: Object.freeze({
+    semi_major_axis: Object.freeze({ offset: 0, size: 8, length: 1, view: "Float64" }),
+    eccentricity: Object.freeze({ offset: 8, size: 8, length: 1, view: "Float64" }),
+    inclination: Object.freeze({ offset: 16, size: 8, length: 1, view: "Float64" }),
+    raan: Object.freeze({ offset: 24, size: 8, length: 1, view: "Float64" }),
+    arg_periapsis: Object.freeze({ offset: 32, size: 8, length: 1, view: "Float64" }),
+    true_anomaly: Object.freeze({ offset: 40, size: 8, length: 1, view: "Float64" }),
+    epoch: Object.freeze({ offset: 48, size: 8, length: 1, view: "Float64" }),
+    reserved: Object.freeze({ offset: 56, size: 8, length: 1, view: "Float64" }),
+  }),
+});
+
+export const ORBPRO_OMM_RECORD = Object.freeze({
+  name: "OMMRecord",
+  cName: "OrbProOMMRecord",
+  size: 88,
+  alignment: 8,
+  offsets: Object.freeze({
+    epoch_jd: 0,
+    mean_motion: 8,
+    eccentricity: 16,
+    inclination: 24,
+    ra_of_asc_node: 32,
+    arg_of_pericenter: 40,
+    mean_anomaly: 48,
+    bstar: 56,
+    mean_motion_dot: 64,
+    mean_motion_ddot: 72,
+    norad_cat_id: 80,
+  }),
+  fields: Object.freeze({
+    epoch_jd: Object.freeze({ offset: 0, size: 8, length: 1, view: "Float64" }),
+    mean_motion: Object.freeze({ offset: 8, size: 8, length: 1, view: "Float64" }),
+    eccentricity: Object.freeze({ offset: 16, size: 8, length: 1, view: "Float64" }),
+    inclination: Object.freeze({ offset: 24, size: 8, length: 1, view: "Float64" }),
+    ra_of_asc_node: Object.freeze({ offset: 32, size: 8, length: 1, view: "Float64" }),
+    arg_of_pericenter: Object.freeze({ offset: 40, size: 8, length: 1, view: "Float64" }),
+    mean_anomaly: Object.freeze({ offset: 48, size: 8, length: 1, view: "Float64" }),
+    bstar: Object.freeze({ offset: 56, size: 8, length: 1, view: "Float64" }),
+    mean_motion_dot: Object.freeze({ offset: 64, size: 8, length: 1, view: "Float64" }),
+    mean_motion_ddot: Object.freeze({ offset: 72, size: 8, length: 1, view: "Float64" }),
+    norad_cat_id: Object.freeze({ offset: 80, size: 4, length: 1, view: "Uint32" }),
+  }),
+});
+
+export const ORBPRO_PROPAGATOR_ABI = Object.freeze({
+  StateVector: ORBPRO_STATE_VECTOR,
+  OrbitalElements: ORBPRO_ORBITAL_ELEMENTS,
+  OMMRecord: ORBPRO_OMM_RECORD,
+});

package/src/generated/orbpro/propagator-abi.ts

@@ -0,0 +1,199 @@
+// ===========================================================================
+// GENERATED FILE — DO NOT EDIT.
+//
+// Source of truth : schemas/orbpro/Propagator.fbs
+// Generator       : scripts/generate-propagator-abi.mjs
+// Drift gate      : scripts/check-propagator-abi.mjs  (runs in `npm test`)
+// Contract        : docs/propagator-abi.md
+//
+// These constants exist so that no JavaScript consumer ever hard-codes a byte
+// offset again. Read a state vector with ORBPRO_STATE_VECTOR.offsets.position,
+// never with the literal 8.
+// ===========================================================================
+
+
+export enum ReferenceFrame {
+  TEME = 0,
+  J2000 = 1,
+  ICRF = 2,
+  ECEF = 3,
+  MCI = 4,
+  MCMF = 5,
+}
+
+/**
+ * StateVector.flags is a BITFIELD carrying any OR-combination of these, so it
+ * is declared `uint` on the struct rather than typed to this enum. The C
+ * enumerators are generated from here anyway — they are the contract.
+ */
+export enum StateFlags {
+  NONE = 0,
+  VALID = 1,
+  IN_ECLIPSE = 2,
+  DECAYED = 4,
+  MANEUVERING = 8,
+  EXTRAPOLATED = 16,
+  HAS_COVARIANCE = 32,
+}
+
+/** One field's placement inside an ABI struct. */
+export interface AbiField {
+  readonly offset: number;
+  readonly size: number;
+  /** Element count for array fields, 1 for scalars. */
+  readonly length: number;
+  /** DataView accessor suffix, e.g. "Float64" for getFloat64. */
+  readonly view: string;
+}
+
+/** One ABI struct's byte layout. */
+export interface AbiStruct {
+  readonly name: string;
+  readonly cName: string;
+  readonly size: number;
+  readonly alignment: number;
+  readonly offsets: Readonly<Record<string, number>>;
+  readonly fields: Readonly<Record<string, AbiField>>;
+}
+
+/**
+ * Orbital state vector — 64 bytes, 8-byte aligned. Mirrors
+ * `OrbProStateVector` in orbpro-integration/sdk/include/orbpro_propagator.h
+ * byte for byte:
+ *
+ *   0   8   epoch (Julian date, float64)
+ *   8   24  position (METERS)
+ *   32  24  velocity (METERS/SECOND)
+ *   56  1   reference_frame (ubyte)
+ *   57  3   padding, MUST be zero
+ *   60  4   flags (uint32)
+ *
+ * NORMATIVE UNITS: position METERS, velocity METERS/SECOND. There is no km
+ * variant and no host-side conversion — the engine hands these straight to
+ * Cesium Cartesian3, whose unit is metres, and both shipped propagators emit
+ * meters. The C header used to declare `reference_frame` as a uint32 at
+ * offset 56, wire-identical to this ubyte+padding only by little-endian
+ * accident; it now declares ubyte + 3 reserved so the two agree by
+ * construction.
+ *
+ * Ruling: graph/findings/official-harness-shapes.md §4.1 / §4.2
+ */
+export const ORBPRO_STATE_VECTOR: AbiStruct = {
+  name: "StateVector",
+  cName: "OrbProStateVector",
+  size: 64,
+  alignment: 8,
+  offsets: {
+    epoch: 0,
+    position: 8,
+    velocity: 32,
+    reference_frame: 56,
+    flags: 60,
+  },
+  fields: {
+    epoch: { offset: 0, size: 8, length: 1, view: "Float64" },
+    position: { offset: 8, size: 24, length: 3, view: "Float64" },
+    velocity: { offset: 32, size: 24, length: 3, view: "Float64" },
+    reference_frame: { offset: 56, size: 1, length: 1, view: "Uint8" },
+    flags: { offset: 60, size: 4, length: 1, view: "Uint32" },
+  },
+} as const;
+
+/**
+ * Keplerian orbital elements — the OPTIONAL initialization input accepted by
+ * `plugin_init_elements`. 64 bytes, 8-byte aligned.
+ *
+ * UNITS NOTE: `semi_major_axis` is KILOMETRES. That is deliberate and it is
+ * NOT an inconsistency with StateVector's metres: this is an INPUT element
+ * set, not an output state vector, and the two are different structs on
+ * different sides of the call. Do not "unify" them — see the normative units
+ * block in the generated C header.
+ */
+export const ORBPRO_ORBITAL_ELEMENTS: AbiStruct = {
+  name: "OrbitalElements",
+  cName: "OrbProOrbitalElements",
+  size: 64,
+  alignment: 8,
+  offsets: {
+    semi_major_axis: 0,
+    eccentricity: 8,
+    inclination: 16,
+    raan: 24,
+    arg_periapsis: 32,
+    true_anomaly: 40,
+    epoch: 48,
+    reserved: 56,
+  },
+  fields: {
+    semi_major_axis: { offset: 0, size: 8, length: 1, view: "Float64" },
+    eccentricity: { offset: 8, size: 8, length: 1, view: "Float64" },
+    inclination: { offset: 16, size: 8, length: 1, view: "Float64" },
+    raan: { offset: 24, size: 8, length: 1, view: "Float64" },
+    arg_periapsis: { offset: 32, size: 8, length: 1, view: "Float64" },
+    true_anomaly: { offset: 40, size: 8, length: 1, view: "Float64" },
+    epoch: { offset: 48, size: 8, length: 1, view: "Float64" },
+    reserved: { offset: 56, size: 8, length: 1, view: "Float64" },
+  },
+} as const;
+
+/**
+ * Binary OMM record — the mean-element ingest struct. 88 bytes, 8-byte
+ * aligned.
+ *
+ * !! THIS STRUCT IS ALSO AN ON-DISK FORMAT !!
+ * -----------------------------------------------------------------------
+ * It crosses the ABI (`plugin_init_omm`, `plugin_entity_add_omm`) AND is
+ * persisted verbatim as a SQLite BLOB by the first-party SGP4 module
+ * (`sgp4_plugin.cpp`, `sqlite3_bind_blob(..., &omm, sizeof(OrbProOMMRecord), ...)`).
+ * Until W1.1 it carried NO size or offset lock anywhere in the stack, so the
+ * layout that every stored blob depends on was held only by the field order
+ * of one hand-written C struct in one module.
+ *
+ * The layout declared here is that layout, EXACTLY as it has been written to
+ * disk — the four trailing padding bytes at offset 84 included. This is a
+ * description of the wire as it already exists, not a redesign of it; the
+ * generated locks now pin it. Migrating the format is explicitly out of
+ * scope and would invalidate every stored blob.
+ *
+ * UNITS: angles in DEGREES, mean motion in REV/DAY, bstar in 1/earth-radii.
+ * These are the SDS $OMM units, carried through unconverted.
+ */
+export const ORBPRO_OMM_RECORD: AbiStruct = {
+  name: "OMMRecord",
+  cName: "OrbProOMMRecord",
+  size: 88,
+  alignment: 8,
+  offsets: {
+    epoch_jd: 0,
+    mean_motion: 8,
+    eccentricity: 16,
+    inclination: 24,
+    ra_of_asc_node: 32,
+    arg_of_pericenter: 40,
+    mean_anomaly: 48,
+    bstar: 56,
+    mean_motion_dot: 64,
+    mean_motion_ddot: 72,
+    norad_cat_id: 80,
+  },
+  fields: {
+    epoch_jd: { offset: 0, size: 8, length: 1, view: "Float64" },
+    mean_motion: { offset: 8, size: 8, length: 1, view: "Float64" },
+    eccentricity: { offset: 16, size: 8, length: 1, view: "Float64" },
+    inclination: { offset: 24, size: 8, length: 1, view: "Float64" },
+    ra_of_asc_node: { offset: 32, size: 8, length: 1, view: "Float64" },
+    arg_of_pericenter: { offset: 40, size: 8, length: 1, view: "Float64" },
+    mean_anomaly: { offset: 48, size: 8, length: 1, view: "Float64" },
+    bstar: { offset: 56, size: 8, length: 1, view: "Float64" },
+    mean_motion_dot: { offset: 64, size: 8, length: 1, view: "Float64" },
+    mean_motion_ddot: { offset: 72, size: 8, length: 1, view: "Float64" },
+    norad_cat_id: { offset: 80, size: 4, length: 1, view: "Uint32" },
+  },
+} as const;
+
+/** Every ABI struct, keyed by its IDL name. */
+export const ORBPRO_PROPAGATOR_ABI: Readonly<Record<string, AbiStruct>> = {
+  StateVector: ORBPRO_STATE_VECTOR,
+  OrbitalElements: ORBPRO_ORBITAL_ELEMENTS,
+  OMMRecord: ORBPRO_OMM_RECORD,
+} as const;

package/src/host/browserModuleHarness.js

@@ -49,6 +49,10 @@ import {
   resolveModuleSignaturePolicy,
   verifyModuleArtifact,
 } from "../bundle/signing.js";
+import {
+  assertArtifactRuntimeTarget,
+  RuntimeTargetError,
+} from "./runtimeTargetGate.js";
 // Artifact byte reduction is an ARTIFACT concern shared by all three runtimes,
 // so it lives on `space-data-module-sdk/bundle`. Re-exported here because a
 // caller loading a module in the browser needs it in the same breath.
@@ -259,6 +263,27 @@ function createImportedMemory(options = {}) {
   return new WebAssembly.Memory(descriptor);
 }
 
+const BROWSER_RUNTIME_TARGET = "browser";
+
+export { RuntimeTargetError };
+
+/**
+ * TRI-RUNTIME ISOMORPHISM, ENFORCED AT THE DOOR.
+ *
+ * This harness IS the browser leg of the tri-runtime contract, wherever the
+ * JavaScript happens to be running — asking it to load an artifact that does
+ * not declare the browser is asking for a divergence. The shared gate in
+ * `runtimeTargetGate.js` does the work; both declarations are consulted and
+ * the artifact's own embedded record wins on conflict.
+ */
+export function assertBrowserRuntimeTarget(wasmModule, manifest) {
+  assertArtifactRuntimeTarget({
+    wasmModule,
+    manifest,
+    leg: BROWSER_RUNTIME_TARGET,
+  });
+}
+
 function resolveManifestSurface(manifest) {
   const surfaces = Array.isArray(manifest?.invokeSurfaces)
     ? manifest.invokeSurfaces
@@ -471,6 +496,7 @@ export async function createBrowserModuleHarness(options = {}) {
   ownedArtifactBytes = null;
   wasmSource = null;
   options.wasmSource = null;
+  assertBrowserRuntimeTarget(wasmModule, options.manifest);
   const moduleImports = WebAssembly.Module.imports(wasmModule);
   const needsHostBridge = moduleImports.some(
     (entry) => entry.module === DEFAULT_HOSTCALL_IMPORT_MODULE,

package/src/host/isomorphicLoader.js

@@ -21,12 +21,14 @@
 import {
   createBrowserModuleHarness,
   toLoadableWasmBytes,
+  zeroWasmBytes,
 } from "./browserModuleHarness.js";
 import {
   resolveModuleSignaturePolicy,
   verifyModuleArtifact,
 } from "../bundle/signing.js";
 import { attachHostDispatch, inspectModule } from "./isomorphicLoaderCore.js";
+import { assertArtifactRuntimeTarget } from "./runtimeTargetGate.js";
 
 export { inspectModule, attachHostDispatch };
 
@@ -203,21 +205,65 @@ export async function loadModule(options = {}) {
     );
   }
 
-  if (signaturePolicy) {
+  const runtimeKind = options.runtimeKind ?? "wasmedge";
+
+  // ONE READ of the artifact, serving every question this function asks of the
+  // bytes: the signature, the runtime-target declaration, and the profile
+  // inspection below. Each of those used to open the file for itself. The
+  // plaintext buffer this function materialized is scrubbed the moment the
+  // last of them is answered, matching the browser harness's
+  // ownedArtifactBytes contract.
+  const runtimeHostRequested =
+    String(options.hostProfile ?? "").trim().toLowerCase() === "runtime-host" ||
+    Array.isArray(options.modules) ||
+    (typeof options.defaultModuleId === "string" &&
+      options.defaultModuleId.trim().length > 0);
+  // The profile inspection is the ONLY consumer here that needs a compiled
+  // module. The runtime-host path does not take it, and it must not start
+  // paying a V8 compile of the whole artifact on every load just because the
+  // runtime-target gate arrived — the gate reads a custom section, which is a
+  // byte-level question.
+  const needsCompiledModule =
+    runtimeKind === "wasmedge" &&
+    !runtimeHostRequested &&
+    !options.wasmEdgeRunnerBinary;
+  const needsBytes = Boolean(signaturePolicy) || runtimeKind === "wasmedge";
+  let artifactBytes = null;
+  let wasmModule = null;
+  let embeddedManifest = null;
+  if (needsBytes) {
     const { readFile } = await import("node:fs/promises");
-    await verifyModuleArtifact(await readFile(source), signaturePolicy);
+    artifactBytes = new Uint8Array(await readFile(source));
+    if (signaturePolicy) {
+      await verifyModuleArtifact(artifactBytes, signaturePolicy);
+    }
+    if (runtimeKind === "wasmedge") {
+      const { locateEmbeddedPlgManifest } = await import(
+        "../compliance/index.js"
+      );
+      embeddedManifest =
+        locateEmbeddedPlgManifest(artifactBytes)?.decoded ?? null;
+    }
+    if (needsCompiledModule) {
+      wasmModule = await WebAssembly.compile(toLoadableWasmBytes(artifactBytes));
+    }
+    zeroWasmBytes(artifactBytes);
+    artifactBytes = null;
   }
 
-  const runtimeKind = options.runtimeKind ?? "wasmedge";
   if (runtimeKind === "wasmedge") {
-    const runtimeHostRequested =
-      String(options.hostProfile ?? "").trim().toLowerCase() === "runtime-host" ||
-      Array.isArray(options.modules) ||
-      (typeof options.defaultModuleId === "string" &&
-        options.defaultModuleId.trim().length > 0);
-    if (!runtimeHostRequested && !options.wasmEdgeRunnerBinary) {
-      const { readFile } = await import("node:fs/promises");
-      const inspection = await inspectModule(await readFile(source));
+    // MIRROR OF THE BROWSER GATE. Enforcing the declaration on one leg only is
+    // itself a divergence between the legs: a `["browser"]`-only artifact
+    // handed to WasmEdge would run until it reached something WasmEdge does
+    // not serve, while the reverse case is refused at the door. Both legs read
+    // the same declaration and refuse the same way.
+    assertArtifactRuntimeTarget({
+      embeddedManifest,
+      manifest: options.manifest,
+      leg: "wasmedge",
+    });
+    if (needsCompiledModule) {
+      const inspection = await inspectModule(wasmModule);
       if (
         (inspection.profile === "standalone" || inspection.profile === "module-host-abi") &&
         inspection.exports.includes("_start")