space-data-module-sdk 0.8.12 → 0.8.13

package/include/orbpro/orbpro_propagator_abi.h

@@ -0,0 +1,312 @@
+/* ===========================================================================
+ * 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
+ *
+ * Edit the .fbs and regenerate. A hand edit here is erased by the next run and
+ * failed by the gate in between — which is the point: this file existing in
+ * five hand-maintained copies is the drift that
+ * graph/findings/official-harness-shapes.md §3 forbids.
+ * ===========================================================================
+ */
+
+#ifndef ORBPRO_PROPAGATOR_ABI_H
+#define ORBPRO_PROPAGATOR_ABI_H
+
+#include <stdint.h>
+#include <stddef.h> /* offsetof */
+
+/* The ABI locks below must compile in both C and C++ — first-party
+ * modules are C++ (sgp4_plugin.cpp, poly_coverage_module.cpp) while the
+ * reference module and the header's own examples are C. */
+#if defined(__cplusplus)
+#define ORBPRO_ABI_STATIC_ASSERT(cond, msg) static_assert(cond, msg)
+#else
+#define ORBPRO_ABI_STATIC_ASSERT(cond, msg) _Static_assert(cond, msg)
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ========================================================================= */
+/* ReferenceFrame */
+/* ========================================================================= */
+
+/** ReferenceFrame */
+typedef enum {
+    ORBPRO_FRAME_TEME = 0,
+    ORBPRO_FRAME_J2000 = 1,
+    ORBPRO_FRAME_ICRF = 2,
+    ORBPRO_FRAME_ECEF = 3,
+    ORBPRO_FRAME_MCI = 4,
+    ORBPRO_FRAME_MCMF = 5,
+} OrbProReferenceFrame;
+
+/* ========================================================================= */
+/* StateFlags */
+/* ========================================================================= */
+
+/**
+ * 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.
+ */
+typedef enum {
+    ORBPRO_STATE_NONE = 0,
+    ORBPRO_STATE_VALID = 1,
+    ORBPRO_STATE_IN_ECLIPSE = 2,
+    ORBPRO_STATE_DECAYED = 4,
+    ORBPRO_STATE_MANEUVERING = 8,
+    ORBPRO_STATE_EXTRAPOLATED = 16,
+    ORBPRO_STATE_HAS_COVARIANCE = 32,
+} OrbProStateFlags;
+
+/* ========================================================================= */
+/* OrbProStateVector — 64 bytes, 8-byte aligned */
+/* ========================================================================= */
+
+/**
+ * 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
+ *
+ * Binary layout (derived from the IDL, not hand-written):
+ *
+ *   Offset  Size  Field
+ *   ------  ----  -----------------------------------------
+ *        0     8  epoch
+ *        8    24  position
+ *       32    24  velocity
+ *       56     1  reference_frame
+ *       57     3  (alignment padding — MUST be written as zero)
+ *       60     4  flags
+ */
+typedef struct {
+    double epoch; /**< Julian date of this state. */
+    double position[3]; /**< Position [x, y, z] in METERS. */
+    double velocity[3]; /**< Velocity [vx, vy, vz] in METERS PER SECOND. */
+    uint8_t reference_frame; /**< Reference frame of position/velocity. One byte; the three bytes that follow are alignment padding and MUST be written as zero. */
+    uint8_t _reserved[3]; /**< Alignment padding at offset 57. MUST be 0. */
+    uint32_t flags; /**< StateFlags bitfield. */
+} OrbProStateVector;
+
+ORBPRO_ABI_STATIC_ASSERT(sizeof(OrbProStateVector) == 64,
+    "OrbProStateVector must be 64 bytes");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProStateVector, epoch) == 0,
+    "OrbProStateVector.epoch must be at offset 0");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProStateVector, position) == 8,
+    "OrbProStateVector.position must be at offset 8");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProStateVector, velocity) == 32,
+    "OrbProStateVector.velocity must be at offset 32");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProStateVector, reference_frame) == 56,
+    "OrbProStateVector.reference_frame must be at offset 56");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProStateVector, flags) == 60,
+    "OrbProStateVector.flags must be at offset 60");
+
+/**
+ * Zero an entire OrbProStateVector, INCLUDING its alignment padding.
+ * Start every write here — see the note above about scratch buffers.
+ */
+static inline void orbpro_state_init(OrbProStateVector* value) {
+    for (size_t i = 0; i < sizeof(*value); ++i) {
+        ((unsigned char*)value)[i] = 0;
+    }
+}
+
+/**
+ * Set OrbProStateVector.reference_frame AND clear the 3 padding byte(s)
+ * that follow it. USE THIS instead of assigning the field directly.
+ */
+static inline void orbpro_state_set_reference_frame(OrbProStateVector* value, OrbProReferenceFrame v) {
+    value->reference_frame = (uint8_t)v;
+    ((unsigned char*)value)[57] = 0;
+    ((unsigned char*)value)[58] = 0;
+    ((unsigned char*)value)[59] = 0;
+}
+
+/* ========================================================================= */
+/* OrbProOrbitalElements — 64 bytes, 8-byte aligned */
+/* ========================================================================= */
+
+/**
+ * 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.
+ *
+ * Binary layout (derived from the IDL, not hand-written):
+ *
+ *   Offset  Size  Field
+ *   ------  ----  -----------------------------------------
+ *        0     8  semi_major_axis
+ *        8     8  eccentricity
+ *       16     8  inclination
+ *       24     8  raan
+ *       32     8  arg_periapsis
+ *       40     8  true_anomaly
+ *       48     8  epoch
+ *       56     8  reserved
+ */
+typedef struct {
+    double semi_major_axis; /**< Semi-major axis in KILOMETRES. */
+    double eccentricity; /**< Orbital eccentricity (0 = circular, <1 = ellipse). */
+    double inclination; /**< Inclination in RADIANS. */
+    double raan; /**< Right ascension of the ascending node in RADIANS. */
+    double arg_periapsis; /**< Argument of periapsis in RADIANS. */
+    double true_anomaly; /**< True anomaly in RADIANS. */
+    double epoch; /**< Epoch as a Julian date. */
+    double reserved; /**< Reserved, MUST be written as 0. */
+} OrbProOrbitalElements;
+
+ORBPRO_ABI_STATIC_ASSERT(sizeof(OrbProOrbitalElements) == 64,
+    "OrbProOrbitalElements must be 64 bytes");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOrbitalElements, semi_major_axis) == 0,
+    "OrbProOrbitalElements.semi_major_axis must be at offset 0");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOrbitalElements, eccentricity) == 8,
+    "OrbProOrbitalElements.eccentricity must be at offset 8");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOrbitalElements, inclination) == 16,
+    "OrbProOrbitalElements.inclination must be at offset 16");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOrbitalElements, raan) == 24,
+    "OrbProOrbitalElements.raan must be at offset 24");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOrbitalElements, arg_periapsis) == 32,
+    "OrbProOrbitalElements.arg_periapsis must be at offset 32");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOrbitalElements, true_anomaly) == 40,
+    "OrbProOrbitalElements.true_anomaly must be at offset 40");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOrbitalElements, epoch) == 48,
+    "OrbProOrbitalElements.epoch must be at offset 48");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOrbitalElements, reserved) == 56,
+    "OrbProOrbitalElements.reserved must be at offset 56");
+
+/**
+ * Zero an entire OrbProOrbitalElements, INCLUDING its alignment padding.
+ * Start every write here — see the note above about scratch buffers.
+ */
+static inline void orbpro_elements_init(OrbProOrbitalElements* value) {
+    for (size_t i = 0; i < sizeof(*value); ++i) {
+        ((unsigned char*)value)[i] = 0;
+    }
+}
+
+/* ========================================================================= */
+/* OrbProOMMRecord — 88 bytes, 8-byte aligned */
+/* ========================================================================= */
+
+/**
+ * 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.
+ *
+ * Binary layout (derived from the IDL, not hand-written):
+ *
+ *   Offset  Size  Field
+ *   ------  ----  -----------------------------------------
+ *        0     8  epoch_jd
+ *        8     8  mean_motion
+ *       16     8  eccentricity
+ *       24     8  inclination
+ *       32     8  ra_of_asc_node
+ *       40     8  arg_of_pericenter
+ *       48     8  mean_anomaly
+ *       56     8  bstar
+ *       64     8  mean_motion_dot
+ *       72     8  mean_motion_ddot
+ *       80     4  norad_cat_id
+ *       84     4  (alignment padding — MUST be written as zero)
+ */
+typedef struct {
+    double epoch_jd; /**< Epoch as a Julian date (callers convert ISO 8601 -> JD). */
+    double mean_motion; /**< Mean motion in REV/DAY. */
+    double eccentricity; /**< Eccentricity (unitless). */
+    double inclination; /**< Inclination in DEGREES. */
+    double ra_of_asc_node; /**< Right ascension of the ascending node in DEGREES. */
+    double arg_of_pericenter; /**< Argument of pericenter in DEGREES. */
+    double mean_anomaly; /**< Mean anomaly in DEGREES. */
+    double bstar; /**< B* drag term in 1/earth-radii. */
+    double mean_motion_dot; /**< First derivative of mean motion, REV/DAY^2. */
+    double mean_motion_ddot; /**< Second derivative of mean motion, REV/DAY^3. */
+    uint32_t norad_cat_id; /**< NORAD catalog number — the identity authority for this record. */
+    uint8_t _reserved[4]; /**< Alignment padding at offset 84. MUST be 0. */
+} OrbProOMMRecord;
+
+ORBPRO_ABI_STATIC_ASSERT(sizeof(OrbProOMMRecord) == 88,
+    "OrbProOMMRecord must be 88 bytes");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOMMRecord, epoch_jd) == 0,
+    "OrbProOMMRecord.epoch_jd must be at offset 0");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOMMRecord, mean_motion) == 8,
+    "OrbProOMMRecord.mean_motion must be at offset 8");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOMMRecord, eccentricity) == 16,
+    "OrbProOMMRecord.eccentricity must be at offset 16");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOMMRecord, inclination) == 24,
+    "OrbProOMMRecord.inclination must be at offset 24");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOMMRecord, ra_of_asc_node) == 32,
+    "OrbProOMMRecord.ra_of_asc_node must be at offset 32");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOMMRecord, arg_of_pericenter) == 40,
+    "OrbProOMMRecord.arg_of_pericenter must be at offset 40");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOMMRecord, mean_anomaly) == 48,
+    "OrbProOMMRecord.mean_anomaly must be at offset 48");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOMMRecord, bstar) == 56,
+    "OrbProOMMRecord.bstar must be at offset 56");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOMMRecord, mean_motion_dot) == 64,
+    "OrbProOMMRecord.mean_motion_dot must be at offset 64");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOMMRecord, mean_motion_ddot) == 72,
+    "OrbProOMMRecord.mean_motion_ddot must be at offset 72");
+ORBPRO_ABI_STATIC_ASSERT(offsetof(OrbProOMMRecord, norad_cat_id) == 80,
+    "OrbProOMMRecord.norad_cat_id must be at offset 80");
+
+/**
+ * Zero an entire OrbProOMMRecord, INCLUDING its alignment padding.
+ * Start every write here — see the note above about scratch buffers.
+ */
+static inline void orbpro_omm_init(OrbProOMMRecord* value) {
+    for (size_t i = 0; i < sizeof(*value); ++i) {
+        ((unsigned char*)value)[i] = 0;
+    }
+}
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* ORBPRO_PROPAGATOR_ABI_H */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.8.12",
+  "version": "0.8.13",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
   "types": "./src/index.d.ts",
@@ -29,6 +29,8 @@
       "types": "./src/licensing/index.d.ts",
       "default": "./src/licensing/index.js"
     },
+    "./include/*": "./include/*",
+    "./generated/propagator-abi": "./src/generated/orbpro/propagator-abi.js",
     "./compiler": "./src/compiler/index.js",
     "./compiler/emception": "./src/compiler/emception.js",
     "./bundle": "./src/bundle/index.js",
@@ -75,6 +77,7 @@
   "files": [
     "bin/",
     "docs/",
+    "include/",
     "parity/",
     "schemas/",
     "src/",
@@ -98,6 +101,8 @@
     "check:nav": "node scripts/check-sdn-stack-nav.mjs module-sdk docs/index.html docs/styles.css",
     "check:compliance": "node ./bin/space-data-module.js check --repo-root .",
     "check:generated-bindings": "node scripts/check-generated-bindings.mjs",
+    "check:propagator-abi": "node scripts/check-propagator-abi.mjs",
+    "generate:propagator-abi": "node scripts/generate-propagator-abi.mjs",
     "generate:vectors": "node ./examples/single-file-bundle/generate-vectors.mjs",
     "prepublishOnly": "npm test && npm run check:compliance"
   },

package/schemas/PluginManifest.fbs

@@ -7,6 +7,24 @@ include "TypedArenaBuffer.fbs";
 namespace orbpro.manifest;
 
 /// Canonical plugin family.
+///
+/// APPEND-ONLY. Ordinals are wire and MUST never be renumbered or reused.
+///
+/// This enum is a PROJECTION of the authoritative SDS vocabulary
+/// `pluginCategory` (spacedatastandards.org `schema/PLG/main.fbs`). SDS is the
+/// source of truth for what families exist; this enum is what the SDK code
+/// dispatches on. The two DO NOT share ordinals — they diverge from index 5
+/// onward (SDK `COMMS = 5`, SDS `EW = 5`) — so the SDK↔SDS mapping is BY NAME,
+/// declared explicitly in `src/manifest/normalize.js`
+/// (`sdsPluginCategoryByFamily`). Never convert one to the other numerically.
+///
+/// Unknown family strings used to be silently coerced to `ANALYSIS`, which
+/// mislabelled 19 first-party modules and made family-typed resolution work
+/// for propagators only. `normalizePluginFamily()` now REFUSES an unknown
+/// family, naming it and the valid vocabulary.
+///
+/// Ruling: graph/findings/official-harness-shapes.md §4.7 / §8.3
+/// Task:   graph/tasks/harness-w0-immediate-fixes.md (W0.3)
 enum PluginFamily : ubyte {
   SENSOR = 0,
   PROPAGATOR = 1,
@@ -18,7 +36,34 @@ enum PluginFamily : ubyte {
   SDF = 7,
   INFRASTRUCTURE = 8,
   FLOW = 9,
-  BRIDGE = 10
+  BRIDGE = 10,
+  /// Maneuver planning, targeting and trajectory optimization.
+  /// Projects onto SDS `pluginCategory.Maneuver`.
+  MANEUVER = 11,
+  /// Orbit determination: fitting an orbit to observations/ephemerides.
+  /// SDS has NO dedicated member yet — this projects onto
+  /// `pluginCategory.Analysis` until Themis mints one. That gap is filed as
+  /// graph/tasks/sds-plugin-category-projection-gaps.md.
+  ORBIT_DETERMINATION = 12,
+  /// Foundational math / utility library module (frames, time, numerics,
+  /// attitude, splines). Projects onto SDS `pluginCategory.Foundation`.
+  FOUNDATION = 13,
+  /// Parses raw upstream bytes into canonical SDS records.
+  /// Projects onto SDS `pluginCategory.Parser`.
+  PARSER = 14,
+  /// Validates records (integrity, physical bounds, continuity).
+  /// Projects onto SDS `pluginCategory.Validator`.
+  VALIDATOR = 15,
+  /// Exports records to external formats (CSV, etc.).
+  /// Projects onto SDS `pluginCategory.Exporter`.
+  EXPORTER = 16,
+  /// Publication: PNM signing + pub/sub announcement.
+  /// Projects onto SDS `pluginCategory.Publisher`.
+  PUBLISHER = 17,
+  /// Astrodynamics simulation / dynamics modelling.
+  /// Projects onto SDS `pluginCategory.Basilisk` (a legacy vocabulary key
+  /// retained there for wire compatibility).
+  BASILISK = 18
 }
 
 /// Host capability requested by a plugin.

package/schemas/orbpro/Propagator.fbs

@@ -2,7 +2,64 @@ include "BaseTypes.fbs";
 
 namespace orbpro.propagator;
 
-enum ReferenceFrame : ubyte {
+// =============================================================================
+// THE PROPAGATOR ABI LIVES HERE. THIS FILE IS THE SINGLE SOURCE OF TRUTH.
+// =============================================================================
+//
+// Every struct below marked `(abi)` is a BINARY CONTRACT that crosses the
+// WASM boundary between a third-party propagator module and the OrbPro engine.
+// The C header, the TypeScript byte-offset bindings and the size/offset locks
+// are all GENERATED from these declarations:
+//
+//   node scripts/generate-propagator-abi.mjs   # regenerate
+//   node scripts/check-propagator-abi.mjs      # the drift gate (runs in npm test)
+//
+// Do NOT hand-write a mirror of these structs anywhere. Five hand-vendored
+// copies of `StateVector` is what this lane exists to end, and the units
+// contradiction W0.1 fixed (km in the field comments, METERS in the layout
+// block three lines below) lived for months precisely because there was no
+// mechanical link between the IDL and the header.
+//
+// Contract document: docs/propagator-abi.md
+// Ruling: graph/findings/official-harness-shapes.md §3 / §7 SHIP-1
+// Task:   graph/tasks/harness-w1-propagator-abi-and-reference.md (W1.1)
+
+/// Marks a struct or enum as part of the binary propagator ABI. Generated
+/// artifacts are derived from exactly the declarations carrying this.
+attribute "abi";
+
+/// The C type name a generated ABI declaration takes. Part of the contract:
+/// third-party sources say `OrbProStateVector`, not `orbpro_propagator_StateVector`.
+attribute "abi_c_name";
+
+/// The C enumerator prefix for a generated ABI enum (ReferenceFrame's members
+/// are `ORBPRO_FRAME_*`, StateFlags' are `ORBPRO_STATE_*`).
+attribute "abi_c_prefix";
+
+/// The C helper-function prefix for a generated ABI struct: the generator emits
+/// `<prefix>init()` and a padding-clearing `<prefix>set_<field>()` for every
+/// enum field. Writing these by hand is how padding bytes go stale.
+attribute "abi_c_helper_prefix";
+
+// !! FOUR INCOMPATIBLE `ReferenceFrame` VOCABULARIES CROSS THIS SEAM !!
+// This is the `orbpro.propagator` one. Its NUMERIC values are NOT
+// interchangeable with the others; translate by NAMED TOKEN at every seam.
+//
+//   (A) orbpro.propagator (THIS)  TEME=0 J2000=1 ICRF=2 ECEF=3 MCI=4 MCMF=5
+//   (B) orbpro.plugins            ECI=0  ECEF=1  TEME=2 ICRF=3
+//       (PropagatorState.fbs / "PRST" — the wire the compiled sgp4, hpop,
+//        conjunction-assessment and sensor-shader modules already emit)
+//   (C) Cesium.ReferenceFrame     FIXED=0 INERTIAL=1
+//   (D) ConjunctionCommon.fbs     ECI=1
+//
+// ECI==0, TEME==0 and FIXED==0 all collide, and ECEF is 1 in (B) but 3 here.
+// (B)'s values are frozen by compiled WASM artifacts in the field, so
+// collapsing (A) and (B) is a wire break, not a Wave-0 edit — see
+// graph/tasks/sdk-reference-frame-enum-unification.md. The reference pattern
+// for a correct seam is propagator.hpop/index.js createSourceFromState.
+//
+// Ruling: graph/findings/official-harness-shapes.md §4.2 / §8.2
+enum ReferenceFrame : ubyte (abi, abi_c_name: "OrbProReferenceFrame", abi_c_prefix: "ORBPRO_FRAME_") {
   TEME = 0,
   J2000 = 1,
   ICRF = 2,
@@ -11,7 +68,10 @@ enum ReferenceFrame : ubyte {
   MCMF = 5
 }
 
-enum StateFlags : uint {
+/// 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.
+enum StateFlags : uint (abi, abi_c_name: "OrbProStateFlags", abi_c_prefix: "ORBPRO_STATE_") {
   NONE = 0,
   VALID = 1,
   IN_ECLIPSE = 2,
@@ -42,14 +102,112 @@ enum PropagatorSourceKind : ubyte {
   SDP8 = 12
 }
 
-struct StateVector {
+/// 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
+struct StateVector (abi, abi_c_name: "OrbProStateVector", abi_c_helper_prefix: "orbpro_state_") {
+  /// Julian date of this state.
   epoch:double;
+  /// Position [x, y, z] in METERS.
   position:orbpro.Vec3;
+  /// Velocity [vx, vy, vz] in METERS PER SECOND.
   velocity:orbpro.Vec3;
+  /// Reference frame of position/velocity. One byte; the three bytes that
+  /// follow are alignment padding and MUST be written as zero.
   reference_frame:ReferenceFrame;
+  /// StateFlags bitfield.
   flags:uint;
 }
 
+/// 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.
+struct OrbitalElements (abi, abi_c_name: "OrbProOrbitalElements", abi_c_helper_prefix: "orbpro_elements_") {
+  /// Semi-major axis in KILOMETRES.
+  semi_major_axis:double;
+  /// Orbital eccentricity (0 = circular, <1 = ellipse).
+  eccentricity:double;
+  /// Inclination in RADIANS.
+  inclination:double;
+  /// Right ascension of the ascending node in RADIANS.
+  raan:double;
+  /// Argument of periapsis in RADIANS.
+  arg_periapsis:double;
+  /// True anomaly in RADIANS.
+  true_anomaly:double;
+  /// Epoch as a Julian date.
+  epoch:double;
+  /// Reserved, MUST be written as 0.
+  reserved:double;
+}
+
+/// 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.
+struct OMMRecord (abi, abi_c_name: "OrbProOMMRecord", abi_c_helper_prefix: "orbpro_omm_") {
+  /// Epoch as a Julian date (callers convert ISO 8601 -> JD).
+  epoch_jd:double;
+  /// Mean motion in REV/DAY.
+  mean_motion:double;
+  /// Eccentricity (unitless).
+  eccentricity:double;
+  /// Inclination in DEGREES.
+  inclination:double;
+  /// Right ascension of the ascending node in DEGREES.
+  ra_of_asc_node:double;
+  /// Argument of pericenter in DEGREES.
+  arg_of_pericenter:double;
+  /// Mean anomaly in DEGREES.
+  mean_anomaly:double;
+  /// B* drag term in 1/earth-radii.
+  bstar:double;
+  /// First derivative of mean motion, REV/DAY^2.
+  mean_motion_dot:double;
+  /// Second derivative of mean motion, REV/DAY^3.
+  mean_motion_ddot:double;
+  /// NORAD catalog number — the identity authority for this record.
+  norad_cat_id:uint;
+}
+
 table PropagatorDescribeSourcesBatchRequest {
   catalogHandle:uint = 0;
   sourceHandles:[uint];

package/src/bundle/index.js

@@ -11,6 +11,7 @@ export {
   CONTENT_HASH_SIZE as SIGNATURE_STATEMENT_CONTENT_HASH_SIZE,
   DOMAIN_MODULE_PUBLICATION_V1,
   DOMAIN_UPDATE_MANIFEST_V1,
+  DOMAIN_UPDATE_SIGNAL_V1,
   SignatureDomainError,
   describe as describeSignatureDomain,
   domains as registeredSignatureDomains,

package/src/bundle/sigdomain.js

@@ -61,6 +61,24 @@ export const DOMAIN_MODULE_PUBLICATION_V1 = "SDN-MODULE-PUBLICATION-V1";
  */
 export const DOMAIN_UPDATE_MANIFEST_V1 = "SDN-UPDATE-MANIFEST-V1";
 
+/**
+ * An UPDATE SIGNAL: the small pub/sub nudge a publisher emits after an artifact
+ * is on the update feed, telling the fleet that a new version exists and where
+ * to fetch it (owner ruling 2026-08-09, "pushing an update signal to all
+ * installs to upgrade in place").
+ *
+ * A separate domain from {@link DOMAIN_UPDATE_MANIFEST_V1} even though the same
+ * bonded key signs both, and the separation is load-bearing in one direction: a
+ * signal is a POINTER, a manifest is an AUTHORIZATION. A signal signature is
+ * cheap, frequent and broadcast to anyone listening, so if the two shared a
+ * preimage space one could be replayed as authorization for bytes. The signal
+ * grants nothing — everything it names is re-fetched and re-verified against the
+ * signed manifest before a byte is swapped. Registered here so the JS registry
+ * still mirrors the node's exactly; a module verifier must REFUSE it, which the
+ * shared vectors pin.
+ */
+export const DOMAIN_UPDATE_SIGNAL_V1 = "SDN-UPDATE-SIGNAL-V1";
+
 /**
  * The CLOSED set of statement domains this SDK will verify. The map value is a
  * short human description: this table is the answer to "what can the bonded
@@ -76,6 +94,10 @@ const REGISTRY = new Map([
     DOMAIN_UPDATE_MANIFEST_V1,
     "update manifest, canonical manifest SHA-256 (reserved; no producer yet)",
   ],
+  [
+    DOMAIN_UPDATE_SIGNAL_V1,
+    "update signal, canonical signal SHA-256 (advisory pub/sub nudge; authorizes nothing)",
+  ],
 ]);
 
 const domainTextEncoder = new TextEncoder();