space-data-module-sdk 0.8.16 → 0.8.18

package/include/orbpro/orbpro_propagator_abi.h

@@ -82,6 +82,64 @@ typedef enum {
     ORBPRO_STATE_HAS_COVARIANCE = 32,
 } OrbProStateFlags;
 
+/* ========================================================================= */
+/* ErrorCode */
+/* ========================================================================= */
+
+/**
+ * The negative return codes every propagator export shares.
+ *
+ * These were documented in docs/propagator-abi.md and declared NOWHERE, so
+ * every module hand-typed them as literals and the contract lived only in
+ * prose. A propagator that returns -1 for everything is unconformable — the
+ * host cannot tell a bad entity index from an uninitialized module, so it
+ * cannot place the failure on the degradation ladder — and the cheapest way
+ * to end up there is having no names to return.
+ *
+ * VALUES ARE FROZEN. New classes are appended downward.
+ */
+typedef enum {
+    ORBPRO_PROP_OK = 0,
+    ORBPRO_PROP_NOT_INITIALIZED = -1,    /**< No elements or ephemeris ingested yet. */
+    ORBPRO_PROP_BAD_ENTITY_INDEX = -2,    /**< Entity index at or beyond the entity count. */
+    ORBPRO_PROP_NULL_OUTPUT = -3,    /**< The caller passed a null output pointer. */
+    ORBPRO_PROP_BAD_INPUT = -4,    /**< Malformed or short input buffer. */
+    ORBPRO_PROP_NOT_CONVERGED = -5,    /**< The solve failed to converge. */
+    ORBPRO_PROP_UNPHYSICAL = -6,    /**< The elements describe no closed orbit, or the result is not a number. */
+    ORBPRO_PROP_UNSUPPORTED_FORMAT = -7,    /**< The ephemeris container is not one this module reads, or AUTO could not identify it, or its declared frame has no member on the ReferenceFrame roster. */
+    ORBPRO_PROP_EPOCH_OUT_OF_RANGE = -8,    /**< The requested epoch lies outside every segment the loaded ephemeris covers. A refusal, never a silent extrapolation: a caller cannot detect an extrapolated state from the value alone. */
+} OrbProPropagatorError;
+
+/* ========================================================================= */
+/* EphemerisFormat */
+/* ========================================================================= */
+
+/**
+ * The container an ephemeris-driven propagator was handed on
+ * `plugin_init_ephemeris`. A format is DATA, not identity: one ephemeris
+ * provider reads every member below behind this discriminator rather than
+ * shipping one artifact per container, because the interpolation, the time
+ * scale handling and the frame rotation are shared and splitting them
+ * re-creates the five-mirror drift this file exists to end.
+ *
+ * AUTO is the honest default: every container here is self-identifying in its
+ * first bytes (`DAF/SPK ` / `NAIF/DAF`, the OEM version keyword, the STK
+ * `stk.v.` banner, the SP3 `#d` line, the Code-500 fixed header block), so a
+ * caller that does not know what it fetched says so rather than guessing. A
+ * module that cannot identify the bytes returns UNSUPPORTED_FORMAT; it never
+ * falls back to a default container.
+ *
+ * VALUES ARE FROZEN AND ARE NEVER RENUMBERED. New containers are APPENDED.
+ */
+typedef enum {
+    ORBPRO_EPHEM_FORMAT_AUTO = 0,    /**< Identify the container from its own leading bytes. */
+    ORBPRO_EPHEM_FORMAT_CCSDS_OEM_KVN = 1,    /**< CCSDS Orbit Ephemeris Message, keyword-value notation. */
+    ORBPRO_EPHEM_FORMAT_SPK_DAF = 2,    /**< NAIF Double Precision Array File carrying SPK segments. */
+    ORBPRO_EPHEM_FORMAT_CODE500 = 3,    /**< Fixed-record binary ephemeris, 500-word logical records. */
+    ORBPRO_EPHEM_FORMAT_STK_EPHEMERIS = 4,    /**< Ephemeris interchange text with a scenario epoch and typed data blocks. */
+    ORBPRO_EPHEM_FORMAT_SP3_D = 5,    /**< Precise orbit product, revision d. */
+} OrbProEphemerisFormat;
+
 /* ========================================================================= */
 /* OrbProStateVector — 64 bytes, 8-byte aligned */
 /* ========================================================================= */

package/include/orbpro/orbpro_solver_abi.h

@@ -0,0 +1,183 @@
+/* ===========================================================================
+ * SCHEMA-DERIVED ABI CONTRACT.
+ *
+ * Source of truth : schemas/orbpro/Solver.fbs
+ * Contract        : pull/supply maneuver-family solver ABI
+ *
+ * A solver has no propagator import. plugin_solver_next yields a candidate;
+ * the host evaluates it through the selected propagator/objective ports and
+ * returns the answer through plugin_solver_supply.
+ * ===========================================================================
+ */
+
+#ifndef ORBPRO_SOLVER_ABI_H
+#define ORBPRO_SOLVER_ABI_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+#if defined(__cplusplus)
+#define ORBPRO_SOLVER_STATIC_ASSERT(cond, msg) static_assert(cond, msg)
+#else
+#define ORBPRO_SOLVER_STATIC_ASSERT(cond, msg) _Static_assert(cond, msg)
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define ORBPRO_SOLVER_MAX_DIMENSION 16u
+#define ORBPRO_SOLVER_MAX_JACOBIAN_VALUES 256u
+
+typedef enum {
+  ORBPRO_SOLVER_NEWTON_RAPHSON = 0,
+  ORBPRO_SOLVER_BROYDEN = 1,
+  ORBPRO_SOLVER_MODIFIED_BROYDEN = 2,
+  ORBPRO_SOLVER_SQP = 3,
+} OrbProSolverAlgorithm;
+
+typedef enum {
+  ORBPRO_SOLVER_DIFFERENCE_FORWARD = 0,
+  ORBPRO_SOLVER_DIFFERENCE_CENTRAL = 1,
+  ORBPRO_SOLVER_DIFFERENCE_ANALYTIC_STM = 2,
+} OrbProSolverDifferenceMode;
+
+typedef enum {
+  ORBPRO_SOLVER_STATUS_IDLE = 0,
+  ORBPRO_SOLVER_STATUS_NEEDS_EVALUATION = 1,
+  ORBPRO_SOLVER_STATUS_CONVERGED = 2,
+  ORBPRO_SOLVER_STATUS_INVALID_PROBLEM = 3,
+  ORBPRO_SOLVER_STATUS_EVALUATION_FAILED = 4,
+  ORBPRO_SOLVER_STATUS_SINGULAR_JACOBIAN = 5,
+  ORBPRO_SOLVER_STATUS_BUDGET_EXCEEDED = 6,
+  ORBPRO_SOLVER_STATUS_STALLED = 7,
+  ORBPRO_SOLVER_STATUS_INFEASIBLE = 8,
+} OrbProSolverStatus;
+
+typedef enum {
+  ORBPRO_SOLVER_EVALUATE_VALUES = 0,
+  ORBPRO_SOLVER_EVALUATE_VALUES_AND_JACOBIAN = 1,
+} OrbProSolverEvaluationKind;
+
+typedef struct {
+  uint8_t algorithm;
+  uint8_t difference_mode;
+  uint16_t _reserved0;
+  uint32_t maximum_iterations;
+  uint32_t maximum_evaluations;
+  uint32_t variable_count;
+  uint32_t goal_count;
+  uint32_t equality_constraint_count;
+  uint32_t inequality_constraint_count;
+  double residual_tolerance;
+  double step_tolerance;
+  double constraint_tolerance;
+  double kkt_tolerance;
+} OrbProSolverSettings;
+
+ORBPRO_SOLVER_STATIC_ASSERT(sizeof(OrbProSolverSettings) == 64,
+                            "OrbProSolverSettings must be 64 bytes");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverSettings, variable_count) == 12,
+                            "OrbProSolverSettings.variable_count offset");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverSettings, equality_constraint_count) == 20,
+                            "OrbProSolverSettings.equality_constraint_count offset");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverSettings, residual_tolerance) == 32,
+                            "OrbProSolverSettings.residual_tolerance offset");
+
+typedef struct {
+  uint64_t request_id;
+  uint8_t kind;
+  uint8_t _reserved0[3];
+  uint32_t variable_count;
+  double variables[ORBPRO_SOLVER_MAX_DIMENSION];
+} OrbProSolverEvaluationRequest;
+
+ORBPRO_SOLVER_STATIC_ASSERT(sizeof(OrbProSolverEvaluationRequest) == 144,
+                            "OrbProSolverEvaluationRequest must be 144 bytes");
+
+typedef struct {
+  uint64_t request_id;
+  uint8_t valid;
+  uint8_t _reserved0[3];
+  uint32_t goal_count;
+  uint32_t constraint_count;
+  uint32_t jacobian_rows;
+  uint32_t jacobian_columns;
+  double goals[ORBPRO_SOLVER_MAX_DIMENSION];
+  double objective;
+  double constraints[ORBPRO_SOLVER_MAX_DIMENSION];
+  double jacobian[ORBPRO_SOLVER_MAX_JACOBIAN_VALUES];
+} OrbProSolverEvaluation;
+
+ORBPRO_SOLVER_STATIC_ASSERT(sizeof(OrbProSolverEvaluation) == 2344,
+                            "OrbProSolverEvaluation must be 2344 bytes");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverEvaluation, goals) == 32,
+                            "OrbProSolverEvaluation.goals offset");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverEvaluation, objective) == 160,
+                            "OrbProSolverEvaluation.objective offset");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverEvaluation, constraints) == 168,
+                            "OrbProSolverEvaluation.constraints offset");
+
+typedef struct {
+  uint32_t iteration;
+  uint32_t evaluation_count;
+  uint32_t variable_count;
+  uint32_t goal_count;
+  double variables[ORBPRO_SOLVER_MAX_DIMENSION];
+  double values[ORBPRO_SOLVER_MAX_DIMENSION];
+  double residual_norm;
+  double step_norm;
+  double jacobian_condition;
+  double maximum_constraint_violation;
+  double kkt_residual;
+  uint8_t accepted;
+  uint8_t _reserved0[7];
+} OrbProSolverIteration;
+
+ORBPRO_SOLVER_STATIC_ASSERT(sizeof(OrbProSolverIteration) == 320,
+                            "OrbProSolverIteration must be 320 bytes");
+
+typedef struct {
+  uint8_t status;
+  uint8_t _reserved0[3];
+  uint32_t iteration_count;
+  uint32_t evaluation_count;
+  uint32_t variable_count;
+  uint32_t value_count;
+  double variables[ORBPRO_SOLVER_MAX_DIMENSION];
+  double values[ORBPRO_SOLVER_MAX_DIMENSION];
+  double objective;
+  double residual_norm;
+  double maximum_constraint_violation;
+  double kkt_residual;
+} OrbProSolverResult;
+
+ORBPRO_SOLVER_STATIC_ASSERT(sizeof(OrbProSolverResult) == 312,
+                            "OrbProSolverResult must be 312 bytes");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverResult, variables) == 24,
+                            "OrbProSolverResult.variables offset");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverResult, objective) == 280,
+                            "OrbProSolverResult.objective offset");
+
+static inline void orbpro_solver_zero(void* value, size_t size) {
+  size_t index;
+  for (index = 0; index < size; ++index) ((uint8_t*)value)[index] = 0;
+}
+
+int32_t plugin_solver_configure(const OrbProSolverSettings* settings,
+                                const double* initial_variables,
+                                const double* lower_bounds,
+                                const double* upper_bounds,
+                                const double* desired_values,
+                                const double* perturbations);
+int32_t plugin_solver_begin(void);
+int32_t plugin_solver_next(OrbProSolverEvaluationRequest* request);
+int32_t plugin_solver_supply(const OrbProSolverEvaluation* evaluation);
+int32_t plugin_solver_result(OrbProSolverResult* result);
+int32_t plugin_solver_iteration(uint32_t index, OrbProSolverIteration* result);
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* ORBPRO_SOLVER_ABI_H */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.8.16",
+  "version": "0.8.18",
   "license": "Apache-2.0",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
@@ -97,6 +97,7 @@
     "gate:parity": "node ./bin/space-data-module.js parity-gate",
     "gate:parity-negative-control": "node ./bin/space-data-module.js parity-gate --gate-manifest ./parity/negative-control.json --expect-fail",
     "conformance:self-test": "node ./bin/space-data-module.js conformance propagator --self-test",
+    "conformance:estimation:self-test": "node ./bin/space-data-module.js conformance estimation --self-test",
     "test:stream-ingest": "node --test test/runtime-host-stream-ingest.test.js",
     "test:module-stream": "node --test test/module-flatbuffer-stream-pump.test.js",
     "benchmark:stream-1gib": "SPACE_DATA_MODULE_SDK_ENABLE_1GB_STREAM_TEST=1 node --test test/runtime-host-stream-ingest.test.js",
@@ -109,6 +110,7 @@
     "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",
+    "check:estimation-abi": "node scripts/check-estimation-abi.mjs",
     "check:reference-frame": "node scripts/check-reference-frame-uniqueness.mjs",
     "generate:propagator-abi": "node scripts/generate-propagator-abi.mjs",
     "generate:vectors": "node ./examples/single-file-bundle/generate-vectors.mjs",
@@ -123,7 +125,7 @@
     "flatsql": "^2.0.0",
     "hd-wallet-wasm": "2.0.28",
     "sdn-emception": "1.0.0",
-    "spacedatastandards.org": "1.200.0"
+    "spacedatastandards.org": "1.206.0"
   },
   "devDependencies": {
     "esbuild": "^0.28.0",

package/schemas/orbpro/Estimation.fbs

@@ -0,0 +1,244 @@
+include "Propagator.fbs";
+
+namespace orbpro.estimation;
+
+// Estimation family ABI. This schema is the single source of truth for the
+// fixed-layout C boundary and the request/result wire. Propagation is an
+// inverted port protocol: the guest emits state/STM requests and consumes the
+// supplied Propagator.fbs answers. It imports no provider-specific function.
+
+enum EstimatorKind : ubyte (abi, abi_c_name: "OrbProEstimatorKind", abi_c_prefix: "ORBPRO_ESTIMATOR_") {
+  BATCH_WEIGHTED_LEAST_SQUARES = 0,
+  EXTENDED_KALMAN_FILTER = 1,
+  UNSCENTED_KALMAN_FILTER = 2,
+  EXTENDED_KALMAN_FILTER_WITH_RTS = 3
+}
+
+enum MeasurementKind : ushort (abi, abi_c_name: "OrbProMeasurementKind", abi_c_prefix: "ORBPRO_MEASUREMENT_") {
+  RANGE = 0,
+  RANGE_RATE = 1,
+  DOPPLER = 2,
+  AZIMUTH_ELEVATION = 3,
+  X_EAST_Y_NORTH = 4,
+  X_SOUTH_Y_EAST = 5,
+  RIGHT_ASCENSION_DECLINATION = 6,
+  POSITION_VECTOR = 7,
+  SEQUENTIAL_RANGE = 8,
+  PSEUDONOISE_RANGE = 9,
+  TIME_CORRELATED_PHASE = 10,
+  RELAY_RANGE = 11,
+  RELAY_DOPPLER = 12,
+  RELAY_DIFFERENCED_DOPPLER = 13,
+  BISTATIC_RANGE = 14,
+  SKIN_RANGE = 15,
+  CROSSLINK_RANGE = 16,
+  CROSSLINK_RANGE_RATE = 17,
+  LASER_RANGE = 18,
+  TIME_DIFFERENCE_OF_ARRIVAL = 19,
+  FREQUENCY_DIFFERENCE_OF_ARRIVAL = 20
+}
+
+enum ProcessNoiseKind : ubyte (abi, abi_c_name: "OrbProProcessNoiseKind", abi_c_prefix: "ORBPRO_PROCESS_NOISE_") {
+  NONE = 0,
+  STATE_NOISE_COMPENSATION = 1,
+  DYNAMIC_MODEL_COMPENSATION = 2
+}
+
+enum TroposphereKind : ubyte (abi, abi_c_name: "OrbProTroposphereKind", abi_c_prefix: "ORBPRO_TROPOSPHERE_") {
+  NONE = 0,
+  HOPFIELD_SAASTAMOINEN = 1,
+  MARINI = 2
+}
+
+enum IonosphereKind : ubyte (abi, abi_c_name: "OrbProIonosphereKind", abi_c_prefix: "ORBPRO_IONOSPHERE_") {
+  NONE = 0,
+  TOTAL_ELECTRON_CONTENT = 1,
+  REFERENCE_PROFILE = 2
+}
+
+enum InitialOrbitKind : ubyte (abi, abi_c_name: "OrbProInitialOrbitKind", abi_c_prefix: "ORBPRO_IOD_") {
+  GAUSS = 0,
+  LAPLACE = 1,
+  GIBBS = 2,
+  HERRICK_GIBBS = 3
+}
+
+enum EstimationStatus : int (abi, abi_c_name: "OrbProEstimationStatus", abi_c_prefix: "ORBPRO_ESTIMATION_") {
+  INTERNAL = -20,
+  PROPAGATOR_PROTOCOL = -19,
+  BUFFER_TOO_SMALL = -18,
+  NOT_CONVERGED = -5,
+  BAD_INPUT = -4,
+  NULL_OUTPUT = -3,
+  NOT_CONFIGURED = -1,
+  OK = 0
+}
+
+struct EstimationEpoch (abi, abi_c_name: "OrbProEstimationEpoch", abi_c_helper_prefix: "orbpro_estimation_epoch_") {
+  jd_day:double;
+  seconds:double;
+}
+
+/// One observation in SI units. The first value_count lanes of value and
+/// sigma are meaningful. station_position_m is in the request frame.
+struct EstimationObservation (abi, abi_c_name: "OrbProEstimationObservation", abi_c_helper_prefix: "orbpro_estimation_observation_") {
+  epoch:EstimationEpoch;
+  value:[double:4];
+  sigma:[double:4];
+  station_position_m:[double:3];
+  station_velocity_mps:[double:3];
+  station_east:[double:3];
+  station_north:[double:3];
+  station_up:[double:3];
+  remote_position_m:[double:3];
+  remote_velocity_mps:[double:3];
+  frequency_hz:double;
+  transmitter_delay_seconds:double;
+  receiver_delay_seconds:double;
+  transponder_delay_seconds:double;
+  elevation_rad:double;
+  station_latitude_rad:double;
+  station_height_m:double;
+  pressure_hpa:double;
+  temperature_k:double;
+  relative_humidity:double;
+  wavelength_m:double;
+  total_electron_content:double;
+  total_electron_content_rate_per_second:double;
+  turnaround_numerator:uint;
+  turnaround_denominator:uint;
+  kind:MeasurementKind;
+  value_count:ubyte;
+  flags:ubyte;
+  transmitter_index:uint;
+  receiver_index:uint;
+}
+
+struct EstimationErrorModel (abi, abi_c_name: "OrbProEstimationErrorModel", abi_c_helper_prefix: "orbpro_estimation_error_model_") {
+  noise_sigma:double;
+  bias:double;
+  bias_sigma:double;
+  correlation_time_seconds:double;
+  minimum_value:double;
+  maximum_value:double;
+  sigma_edit_threshold:double;
+  random_seed:ulong;
+  measurement_kind:MeasurementKind;
+  troposphere:TroposphereKind;
+  ionosphere:IonosphereKind;
+  flags:ubyte;
+}
+
+/// Fixed configuration copied byte-for-byte in every runtime. initial_state
+/// is Cartesian [x,y,z,vx,vy,vz] in metres and metres per second; covariance
+/// is row-major 6 by 6 in matching SI units.
+struct EstimationConfig (abi, abi_c_name: "OrbProEstimationConfig", abi_c_helper_prefix: "orbpro_estimation_config_") {
+  initial_epoch:EstimationEpoch;
+  initial_state:[double:6];
+  initial_covariance:[double:36];
+  process_noise_spectral_density:[double:6];
+  state_convergence_tolerance:double;
+  rms_convergence_tolerance:double;
+  sigma_edit_threshold:double;
+  dynamic_model_correlation_time_seconds:double;
+  maximum_iterations:uint;
+  reference_frame:orbpro.propagator.ReferenceFrame;
+  estimator:EstimatorKind;
+  process_noise:ProcessNoiseKind;
+  flags:ushort;
+}
+
+struct EstimationState (abi, abi_c_name: "OrbProEstimationState", abi_c_helper_prefix: "orbpro_estimation_state_") {
+  epoch:EstimationEpoch;
+  state:[double:6];
+  covariance:[double:36];
+  residual_rms:double;
+  recovered_noise_sigma:double;
+  iteration_count:uint;
+  accepted_count:uint;
+  rejected_count:uint;
+  reference_frame:orbpro.propagator.ReferenceFrame;
+  converged:ubyte;
+  smoothed:ubyte;
+  estimator:EstimatorKind;
+}
+
+struct FilterEpoch (abi, abi_c_name: "OrbProFilterEpoch", abi_c_helper_prefix: "orbpro_filter_epoch_") {
+  epoch:EstimationEpoch;
+  filtered_state:[double:6];
+  filtered_covariance:[double:36];
+  smoothed_state:[double:6];
+  smoothed_covariance:[double:36];
+  normalized_innovation_squared:double;
+}
+
+/// State and state-transition matrix supplied by the propagator port. The STM
+/// maps deviations at the estimator epoch to this sample epoch.
+struct EstimationPropagatorSample (abi, abi_c_name: "OrbProEstimationPropagatorSample", abi_c_helper_prefix: "orbpro_estimation_propagator_sample_") {
+  epoch:EstimationEpoch;
+  state:[double:6];
+  stm:[double:36];
+}
+
+struct InitialOrbitRequest (abi, abi_c_name: "OrbProInitialOrbitRequest", abi_c_helper_prefix: "orbpro_initial_orbit_request_") {
+  // Three inertial position vectors for Gibbs and Herrick-Gibbs.
+  positions_m:[double:9];
+  // Three observer positions followed by the three topocentric angle pairs
+  // used by Gauss and Laplace. The method selects which input set is read.
+  observer_positions_m:[double:9];
+  right_ascensions_rad:[double:3];
+  declinations_rad:[double:3];
+  epochs:EstimationEpoch;
+  interval_12_seconds:double;
+  interval_23_seconds:double;
+  gravitational_parameter_m3_s2:double;
+  method:InitialOrbitKind;
+}
+
+struct InitialOrbitResult (abi, abi_c_name: "OrbProInitialOrbitResult", abi_c_helper_prefix: "orbpro_initial_orbit_result_") {
+  epoch:EstimationEpoch;
+  state:[double:6];
+  iterations:uint;
+  reference_frame:orbpro.propagator.ReferenceFrame;
+  status:EstimationStatus;
+}
+
+/// Request/result wire. observations are decoded from $TDM/$CRD before they
+/// cross this family boundary; their source record identifiers remain on the
+/// request for a complete provenance trail.
+table EstimationRequest {
+  config:EstimationConfig;
+  observations:[EstimationObservation];
+  error_models:[EstimationErrorModel];
+  source_record_ids:[string];
+  propagator_port_id:string (required);
+  propagator_capability:string (required);
+  trace_id:string;
+}
+
+table EstimationResult {
+  status:EstimationStatus = OK;
+  estimate:EstimationState;
+  filter_history:[FilterEpoch];
+  residuals:[double];
+  /// Row-major 6x6 covariance blocks, one per batch iteration, in iteration
+  /// order. Empty for sequential estimators.
+  iteration_covariances:[double];
+  rejected_observation_indices:[uint];
+  odr_record:[ubyte];
+  ocm_record:[ubyte];
+  error_message:string;
+  trace_id:string;
+}
+
+table EstimationEnvelope {
+  request:EstimationRequest;
+  result:EstimationResult;
+  propagator_samples:[EstimationPropagatorSample];
+  simulated_observations:[EstimationObservation];
+  initial_orbit_request:InitialOrbitRequest;
+  initial_orbit_result:InitialOrbitResult;
+}
+
+root_type EstimationEnvelope;
+file_identifier "$EST";

package/schemas/orbpro/Propagator.fbs

@@ -165,6 +165,70 @@ enum PropagatorSourceKind : ubyte {
   SDP8 = 12
 }
 
+/// The negative return codes every propagator export shares.
+///
+/// These were documented in docs/propagator-abi.md and declared NOWHERE, so
+/// every module hand-typed them as literals and the contract lived only in
+/// prose. A propagator that returns -1 for everything is unconformable — the
+/// host cannot tell a bad entity index from an uninitialized module, so it
+/// cannot place the failure on the degradation ladder — and the cheapest way
+/// to end up there is having no names to return.
+///
+/// VALUES ARE FROZEN. New classes are appended downward.
+enum ErrorCode : byte (abi, abi_c_name: "OrbProPropagatorError", abi_c_prefix: "ORBPRO_PROP_") {
+  OK = 0,
+  /// No elements or ephemeris ingested yet.
+  NOT_INITIALIZED = -1,
+  /// Entity index at or beyond the entity count.
+  BAD_ENTITY_INDEX = -2,
+  /// The caller passed a null output pointer.
+  NULL_OUTPUT = -3,
+  /// Malformed or short input buffer.
+  BAD_INPUT = -4,
+  /// The solve failed to converge.
+  NOT_CONVERGED = -5,
+  /// The elements describe no closed orbit, or the result is not a number.
+  UNPHYSICAL = -6,
+  /// The ephemeris container is not one this module reads, or AUTO could not
+  /// identify it, or its declared frame has no member on the ReferenceFrame
+  /// roster.
+  UNSUPPORTED_FORMAT = -7,
+  /// The requested epoch lies outside every segment the loaded ephemeris
+  /// covers. A refusal, never a silent extrapolation: a caller cannot detect
+  /// an extrapolated state from the value alone.
+  EPOCH_OUT_OF_RANGE = -8
+}
+
+/// The container an ephemeris-driven propagator was handed on
+/// `plugin_init_ephemeris`. A format is DATA, not identity: one ephemeris
+/// provider reads every member below behind this discriminator rather than
+/// shipping one artifact per container, because the interpolation, the time
+/// scale handling and the frame rotation are shared and splitting them
+/// re-creates the five-mirror drift this file exists to end.
+///
+/// AUTO is the honest default: every container here is self-identifying in its
+/// first bytes (`DAF/SPK ` / `NAIF/DAF`, the OEM version keyword, the STK
+/// `stk.v.` banner, the SP3 `#d` line, the Code-500 fixed header block), so a
+/// caller that does not know what it fetched says so rather than guessing. A
+/// module that cannot identify the bytes returns UNSUPPORTED_FORMAT; it never
+/// falls back to a default container.
+///
+/// VALUES ARE FROZEN AND ARE NEVER RENUMBERED. New containers are APPENDED.
+enum EphemerisFormat : ubyte (abi, abi_c_name: "OrbProEphemerisFormat", abi_c_prefix: "ORBPRO_EPHEM_FORMAT_") {
+  /// Identify the container from its own leading bytes.
+  AUTO = 0,
+  /// CCSDS Orbit Ephemeris Message, keyword-value notation.
+  CCSDS_OEM_KVN = 1,
+  /// NAIF Double Precision Array File carrying SPK segments.
+  SPK_DAF = 2,
+  /// Fixed-record binary ephemeris, 500-word logical records.
+  CODE500 = 3,
+  /// Ephemeris interchange text with a scenario epoch and typed data blocks.
+  STK_EPHEMERIS = 4,
+  /// Precise orbit product, revision d.
+  SP3_D = 5
+}
+
 /// Orbital state vector — 64 bytes, 8-byte aligned. Mirrors
 /// `OrbProStateVector` in orbpro-integration/sdk/include/orbpro_propagator.h
 /// byte for byte: