space-data-module-sdk 0.8.12 → 0.8.14

package/src/capabilities.js

@@ -77,12 +77,64 @@ export const BrowserIncompatibleCapabilityIds = Object.freeze([
   "process_exec",
   "wallet_sign",
   "ipfs",
+]);
+
+/**
+ * ENGINE-HOSTED capabilities: the three that reach into a live 3D engine —
+ * its scene graph, its entity collection, its render loop.
+ *
+ * These used to sit in `BrowserIncompatibleCapabilityIds`, which was exactly
+ * backwards and produced a compliance paradox: they are also in
+ * `RecommendedCapabilityIds`, so a module was simultaneously told to declare
+ * them and refused for declaring them alongside the only runtime where they
+ * can possibly work. The flow compiler compounded it by unconditionally
+ * subtracting `browser` from any composed flow whose capability union touched
+ * one — meaning no flow that needs the engine could ever target the runtime
+ * the engine lives in.
+ *
+ * The truth, established by sweep:
+ *   - The ONE implementation of `scene_access` in the stack is OrbPro's
+ *     `ProviderAccessPort` + the SDK's `providerAccessEngineAdapter`, both of
+ *     which require a live Cesium/OrbPro `Scene`. That is a BROWSER object.
+ *   - `NodeHostSupportedCapabilities` contains none of the three, and
+ *     `assertCapability()` fails them closed with `host-capability-unsupported`.
+ *   - `entity_access` and `render_hooks` have no serving implementation on any
+ *     runtime yet — only manifest-vocabulary codec entries. They are declared
+ *     engine-hosted here because that is where they can ever be served, not
+ *     because they are wired today.
+ *
+ * So they are wasmedge-incompatible, not browser-incompatible. (The `wasi`
+ * portability baseline already refuses them via
+ * `StandaloneWasiCapabilityIds` — nothing outside that five-member subset is
+ * admitted to a standalone WASI artifact.)
+ *
+ * Ruling: graph/findings/official-harness-shapes.md §8.4
+ * Task:   graph/tasks/harness-w0-immediate-fixes.md (W0.4)
+ */
+export const EngineHostedCapabilityIds = Object.freeze([
   "scene_access",
   "entity_access",
   "render_hooks",
 ]);
 
-/** Which capabilities each runtime leg cannot serve. */
+/**
+ * Capabilities the headless WasmEdge leg cannot serve. There is no scene, no
+ * entity collection and no render loop in a headless server runtime, and no
+ * adapter can invent one.
+ */
+export const WasmEdgeIncompatibleCapabilityIds = Object.freeze([
+  ...EngineHostedCapabilityIds,
+]);
+
+/**
+ * Which capabilities each runtime leg cannot serve.
+ *
+ * Consumed by `runtimeTargetGate.js` (load-time admission), the flow compiler's
+ * `collectFlowRuntimeTargets` (derived runtimeTargets), and
+ * `pluginCompliance.js` (publish-time declaration policy) — all three read
+ * THIS table, so a leg's policy is stated once.
+ */
 export const LegIncompatibleCapabilityIds = Object.freeze({
   browser: BrowserIncompatibleCapabilityIds,
+  wasmedge: WasmEdgeIncompatibleCapabilityIds,
 });

package/src/compliance/index.js

@@ -12,8 +12,11 @@ import {
 } from "./pluginCompliance.js";
 import {
   BrowserIncompatibleCapabilityIds,
+  EngineHostedCapabilityIds,
+  LegIncompatibleCapabilityIds,
   RecommendedCapabilityIds,
   StandaloneWasiCapabilityIds,
+  WasmEdgeIncompatibleCapabilityIds,
 } from "../capabilities.js";
 import { validateManifestAgainstStandardsCatalog } from "../standards/index.js";
 
@@ -50,6 +53,9 @@ export async function validateArtifactWithStandards(options = {}) {
 
 export {
   BrowserIncompatibleCapabilityIds,
+  EngineHostedCapabilityIds,
+  LegIncompatibleCapabilityIds,
+  WasmEdgeIncompatibleCapabilityIds,
   findManifestFiles,
   getWasmExportNames,
   getWasmExportNamesFromFile,

package/src/compliance/pluginCompliance.js

@@ -13,7 +13,7 @@ import {
   RuntimeTarget,
 } from "../runtime/constants.js";
 import {
-  BrowserIncompatibleCapabilityIds,
+  LegIncompatibleCapabilityIds,
   RecommendedCapabilityIds,
   StandaloneWasiCapabilityIds,
 } from "../capabilities.js";
@@ -26,6 +26,10 @@ import {
   isPayloadSchemaHashValid,
   payloadSchemaIdentitiesEqual,
 } from "../manifest/typeRefs.js";
+import {
+  PluginFamilyNames,
+  pluginFamilyByName,
+} from "../manifest/normalize.js";
 import { isLegacyWildcardPort } from "./legacyWildcardPorts.js";
 import { SDS_MANIFEST_SECTION_NAME } from "../bundle/constants.js";
 import {
@@ -50,7 +54,18 @@ const ExternalInterfaceDirectionSet = new Set(
 const ExternalInterfaceKindSet = new Set(Object.values(ExternalInterfaceKind));
 const ProtocolRoleSet = new Set(Object.values(ProtocolRole));
 const ProtocolTransportKindSet = new Set(Object.values(ProtocolTransportKind));
-const BrowserIncompatibleCapabilitySet = new Set(BrowserIncompatibleCapabilityIds);
+// One entry per runtime leg that has a declaration policy, built from the
+// single table in capabilities.js. This used to be a browser-only constant,
+// which is why an engine-hosted capability could only ever be described as
+// "not available in the browser" — the exact inverse of the truth.
+const LegIncompatibleCapabilitySets = Object.freeze(
+  Object.fromEntries(
+    Object.entries(LegIncompatibleCapabilityIds).map(([leg, ids]) => [
+      leg,
+      new Set(ids),
+    ]),
+  ),
+);
 const StandaloneWasiProtocolTransportKindSet = new Set([
   ProtocolTransportKind.WASI_PIPE,
 ]);
@@ -126,6 +141,45 @@ function validateStringField(issues, value, location, label) {
   return true;
 }
 
+/**
+ * `pluginFamily` is an ENUM, not a free string.
+ *
+ * This used to be `validateStringField`, so any spelling passed compliance and
+ * `normalizePluginFamily` then silently coerced it to ANALYSIS — the two
+ * halves of the same defect. Compliance now enforces the same vocabulary the
+ * normalizer refuses on, so a bad family is caught at check time with the
+ * valid set named, instead of at load time as a mislabelled module.
+ *
+ * Ruling: graph/findings/official-harness-shapes.md §4.7 / §8.3
+ */
+function validatePluginFamilyField(issues, value, location) {
+  if (!isNonEmptyString(value)) {
+    pushIssue(
+      issues,
+      "error",
+      "missing-string",
+      "pluginFamily must be a non-empty string.",
+      location,
+    );
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (pluginFamilyByName[normalized] === undefined) {
+    pushIssue(
+      issues,
+      "error",
+      "unknown-plugin-family",
+      `pluginFamily "${value}" is not a member of the plugin family vocabulary. ` +
+        `Valid families: ${PluginFamilyNames.join(", ")}. ` +
+        `A new family is appended to schemas/PluginManifest.fbs (a projection ` +
+        `of the authoritative SDS pluginCategory), never invented in a manifest.`,
+      location,
+    );
+    return false;
+  }
+  return true;
+}
+
 function validateCapabilityEntry(capability, issues, location) {
   if (isNonEmptyString(capability)) {
     return capability;
@@ -1412,21 +1466,27 @@ function validateRuntimeTargets(runtimeTargets, declaredCapabilities, issues, so
       );
     }
   }
-  if (
-    seenTargets.has(RuntimeTarget.BROWSER) &&
-    Array.isArray(declaredCapabilities)
-  ) {
-    for (const capability of declaredCapabilities) {
-      if (!BrowserIncompatibleCapabilitySet.has(capability)) {
+  if (Array.isArray(declaredCapabilities)) {
+    // Check EVERY declared leg that has a policy, not just the browser. An
+    // engine-hosted capability (scene_access/entity_access/render_hooks) is
+    // browser-ONLY, so the conflict it can raise is against `wasmedge`.
+    for (const target of seenTargets) {
+      const incompatible = LegIncompatibleCapabilitySets[target];
+      if (!incompatible) {
         continue;
       }
-      pushIssue(
-        issues,
-        "error",
-        "capability-runtime-conflict",
-        `Capability "${capability}" is not available in the canonical browser runtime target.`,
-        `${sourceName}.capabilities`,
-      );
+      for (const capability of declaredCapabilities) {
+        if (!incompatible.has(capability)) {
+          continue;
+        }
+        pushIssue(
+          issues,
+          "error",
+          "capability-runtime-conflict",
+          `Capability "${capability}" is not available in the canonical ${target} runtime target.`,
+          `${sourceName}.capabilities`,
+        );
+      }
     }
   }
 }
@@ -1734,7 +1794,7 @@ export function validatePluginManifest(manifest, options = {}) {
   validateStringField(issues, manifest.pluginId, `${sourceName}.pluginId`, "pluginId");
   validateStringField(issues, manifest.name, `${sourceName}.name`, "name");
   validateStringField(issues, manifest.version, `${sourceName}.version`, "version");
-  validateStringField(issues, manifest.pluginFamily, `${sourceName}.pluginFamily`, "pluginFamily");
+  validatePluginFamilyField(issues, manifest.pluginFamily, `${sourceName}.pluginFamily`);
 
   const rawDeclaredCapabilities = manifest.capabilities;
   let declaredCapabilities = null;

package/src/flow/flowCompiler.js

@@ -56,7 +56,7 @@ import {
 } from "../compiler/pthreadArtifactGuard.js";
 import { resolveWasiThreadsToolchain } from "../compiler/wasiThreadsToolchain.js";
 import {
-  BrowserIncompatibleCapabilityIds,
+  LegIncompatibleCapabilityIds,
   validateArtifactWithStandards,
   validatePluginManifest,
 } from "../compliance/index.js";
@@ -904,9 +904,19 @@ function collectComponentDependencies({ nodePluginIds, dependencies, issues, cap
   return [...components.values()].sort((a, b) => a.pluginId.localeCompare(b.pluginId));
 }
 
-const BROWSER_RUNTIME_TARGET = "browser";
-const BrowserIncompatibleCapabilitySet = new Set(
-  BrowserIncompatibleCapabilityIds,
+// Per-leg incompatibility, read from the ONE table in capabilities.js rather
+// than a browser-only constant. An engine-hosted capability
+// (scene_access/entity_access/render_hooks) is browser-ONLY, so the leg it
+// narrows away is `wasmedge`; the old browser-only form could only ever
+// subtract `browser`, which is how a flow that needs the engine ended up
+// unable to target the runtime the engine lives in.
+const LegIncompatibleCapabilitySets = Object.freeze(
+  Object.fromEntries(
+    Object.entries(LegIncompatibleCapabilityIds).map(([leg, ids]) => [
+      leg,
+      new Set(ids),
+    ]),
+  ),
 );
 
 function declaredRuntimeTargets(manifest) {
@@ -938,9 +948,11 @@ function declaredRuntimeTargets(manifest) {
  * exactly that capability against a browser target. Deriving only from the
  * declarations left the commonest manifest shape re-creating the original
  * defect — the compiler stamping a target its own compliance pass then
- * rejects. So `browser` is also dropped whenever the flow's capability union
- * meets `BrowserIncompatibleCapabilityIds`, and the diagnostic names the
- * capability that cost it.
+ * rejects. So a leg is also dropped whenever the flow's capability union meets
+ * that leg's entry in `LegIncompatibleCapabilityIds`, and the diagnostic names
+ * the capability that cost it. That table is per-leg, not browser-only: the
+ * engine-hosted capabilities (scene_access/entity_access/render_hooks) narrow
+ * away `wasmedge`, in the other direction.
  *
  * This is the difference between a truthful manifest and a wish. The hardcoded
  * ["browser","wasmedge"] made every composition claim the browser, which made
@@ -1006,16 +1018,20 @@ function collectFlowRuntimeTargets({
     );
   }
 
-  const browserIncompatible = [...(capabilities ?? [])]
-    .filter((capability) => BrowserIncompatibleCapabilitySet.has(capability))
-    .sort();
-  if (browserIncompatible.length > 0) {
+  const unionCapabilities = [...(capabilities ?? [])];
+  for (const leg of COMPOSED_FLOW_RUNTIME_TARGET_UNIVERSE) {
+    const incompatible = LegIncompatibleCapabilitySets[leg];
+    if (!incompatible) continue;
+    const offending = unionCapabilities
+      .filter((capability) => incompatible.has(capability))
+      .sort();
+    if (offending.length === 0) continue;
     narrow(
-      (target) => target !== BROWSER_RUNTIME_TARGET,
+      (target) => target !== leg,
       () =>
-        `the flow's capability union contains ${browserIncompatible
+        `the flow's capability union contains ${offending
           .map((capability) => `"${capability}"`)
-          .join(", ")}, which the canonical browser runtime target cannot serve`,
+          .join(", ")}, which the canonical ${leg} runtime target cannot serve`,
     );
   }
 

package/src/generated/orbpro/manifest/plugin-family.d.ts

@@ -12,6 +12,14 @@ export declare enum PluginFamily {
     SDF = 7,
     INFRASTRUCTURE = 8,
     FLOW = 9,
-    BRIDGE = 10
+    BRIDGE = 10,
+    MANEUVER = 11,
+    ORBIT_DETERMINATION = 12,
+    FOUNDATION = 13,
+    PARSER = 14,
+    VALIDATOR = 15,
+    EXPORTER = 16,
+    PUBLISHER = 17,
+    BASILISK = 18
 }
 //# sourceMappingURL=plugin-family.d.ts.map

package/src/generated/orbpro/manifest/plugin-family.js

@@ -16,5 +16,13 @@ export var PluginFamily;
     PluginFamily[PluginFamily["INFRASTRUCTURE"] = 8] = "INFRASTRUCTURE";
     PluginFamily[PluginFamily["FLOW"] = 9] = "FLOW";
     PluginFamily[PluginFamily["BRIDGE"] = 10] = "BRIDGE";
+    PluginFamily[PluginFamily["MANEUVER"] = 11] = "MANEUVER";
+    PluginFamily[PluginFamily["ORBIT_DETERMINATION"] = 12] = "ORBIT_DETERMINATION";
+    PluginFamily[PluginFamily["FOUNDATION"] = 13] = "FOUNDATION";
+    PluginFamily[PluginFamily["PARSER"] = 14] = "PARSER";
+    PluginFamily[PluginFamily["VALIDATOR"] = 15] = "VALIDATOR";
+    PluginFamily[PluginFamily["EXPORTER"] = 16] = "EXPORTER";
+    PluginFamily[PluginFamily["PUBLISHER"] = 17] = "PUBLISHER";
+    PluginFamily[PluginFamily["BASILISK"] = 18] = "BASILISK";
 })(PluginFamily || (PluginFamily = {}));
 //# sourceMappingURL=plugin-family.js.map

package/src/generated/orbpro/manifest/plugin-family.ts

@@ -17,4 +17,12 @@ export enum PluginFamily {
   INFRASTRUCTURE = 8,
   FLOW = 9,
   BRIDGE = 10,
+  MANEUVER = 11,
+  ORBIT_DETERMINATION = 12,
+  FOUNDATION = 13,
+  PARSER = 14,
+  VALIDATOR = 15,
+  EXPORTER = 16,
+  PUBLISHER = 17,
+  BASILISK = 18,
 }

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;