space-data-module-sdk 0.8.16 → 0.8.17

package/src/conformance/index.js

@@ -19,6 +19,8 @@ import path from "node:path";
 
 import { loadPropagatorArtifact } from "./abiDriver.js";
 import { computeVerdict, runPropagatorSuite } from "./propagatorSuite.js";
+import { runEstimationSuite } from "./estimationSuite.js";
+import { makeEstimationReferenceEvidence } from "./estimationReference.js";
 
 export { ErrorCode, REQUIRED_ABI_EXPORTS } from "./abiDriver.js";
 export {
@@ -34,14 +36,14 @@ export { runPropagatorSelfTest, formatSelfTestReport } from "./selfTest.js";
  * never coerced — the ANALYSIS fallback was the namespace corruption the
  * finding killed.
  */
-export const CONFORMANCE_FAMILIES = Object.freeze(["propagator"]);
+export const CONFORMANCE_FAMILIES = Object.freeze(["estimation", "propagator"]);
 
 export class UnknownConformanceFamilyError extends Error {
   constructor(family) {
     super(
       `no conformance kit for family "${family}" — kits exist for: ` +
         `${CONFORMANCE_FAMILIES.join(", ")}. A family with no kit can never be CORE ` +
-        "(finding §5); maneuver is Wave 2 (EXPERIMENTAL), OD is deferred by ruling.",
+        "(finding §5); maneuver remains Wave 2.",
     );
     this.name = "UnknownConformanceFamilyError";
     this.family = family;
@@ -93,6 +95,23 @@ export async function runConformance(options) {
   if (!CONFORMANCE_FAMILIES.includes(family)) {
     throw new UnknownConformanceFamilyError(options.family);
   }
+  if (family === "estimation") {
+    const evidence = options.evidence ?? JSON.parse(
+      await fs.readFile(path.resolve(options.evidencePath), "utf8"),
+    );
+    const evaluated = runEstimationSuite(evidence);
+    let artifact = evidence.artifact ?? null;
+    if (options.artifactPath) {
+      const artifactPath = path.resolve(options.artifactPath);
+      const artifactBytes = await fs.readFile(artifactPath);
+      artifact = {
+        path: artifactPath,
+        sha256: crypto.createHash("sha256").update(artifactBytes).digest("hex"),
+      };
+    }
+    return { family, artifact, corpus: null, evidence: options.evidencePath ?? null, ...evaluated };
+  }
+
   const artifactPath = path.resolve(options.artifactPath);
   const artifactBytes = await fs.readFile(artifactPath);
   const artifactSha256 = crypto
@@ -129,6 +148,24 @@ export async function runConformance(options) {
   };
 }
 
+export { runEstimationSuite } from "./estimationSuite.js";
+export { makeEstimationReferenceEvidence } from "./estimationReference.js";
+
+export async function runEstimationSelfTest() {
+  const controls = [];
+  for (const [id, mutate] of [
+    ["runtime-divergence", (e) => { e.runtime.threads["8"] = "different"; }],
+    ["ekf-ukf-alias", (e) => { e.filter.ekfUkfCovarianceDifference = 0; }],
+    ["covariance-placeholder", (e) => { e.invariants.actualOcmCovariance = false; }],
+  ]) {
+    const evidence = makeEstimationReferenceEvidence();
+    mutate(evidence);
+    const report = runEstimationSuite(evidence);
+    controls.push({ id, caught: report.verdict === "FAIL" });
+  }
+  return { ok: controls.every((control) => control.caught), controls };
+}
+
 export function formatConformanceReport(report) {
   const lines = [];
   lines.push(`conformance ${report.family} — ${report.verdict}`);

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

@@ -47,6 +47,27 @@ export const StateFlags = Object.freeze({
   HAS_COVARIANCE: 32,
 });
 
+export const ErrorCode = Object.freeze({
+  OK: 0,
+  NOT_INITIALIZED: -1,
+  BAD_ENTITY_INDEX: -2,
+  NULL_OUTPUT: -3,
+  BAD_INPUT: -4,
+  NOT_CONVERGED: -5,
+  UNPHYSICAL: -6,
+  UNSUPPORTED_FORMAT: -7,
+  EPOCH_OUT_OF_RANGE: -8,
+});
+
+export const EphemerisFormat = Object.freeze({
+  AUTO: 0,
+  CCSDS_OEM_KVN: 1,
+  SPK_DAF: 2,
+  CODE500: 3,
+  STK_EPHEMERIS: 4,
+  SP3_D: 5,
+});
+
 export const ORBPRO_STATE_VECTOR = Object.freeze({
   name: "StateVector",
   cName: "OrbProStateVector",

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

@@ -53,6 +53,56 @@ export enum StateFlags {
   HAS_COVARIANCE = 32,
 }
 
+/**
+ * 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.
+ */
+export enum ErrorCode {
+  OK = 0,
+  NOT_INITIALIZED = -1,
+  BAD_ENTITY_INDEX = -2,
+  NULL_OUTPUT = -3,
+  BAD_INPUT = -4,
+  NOT_CONVERGED = -5,
+  UNPHYSICAL = -6,
+  UNSUPPORTED_FORMAT = -7,
+  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.
+ */
+export enum EphemerisFormat {
+  AUTO = 0,
+  CCSDS_OEM_KVN = 1,
+  SPK_DAF = 2,
+  CODE500 = 3,
+  STK_EPHEMERIS = 4,
+  SP3_D = 5,
+}
+
 /** One field's placement inside an ABI struct. */
 export interface AbiField {
   readonly offset: number;

package/src/standards/sharedCatalog.js

@@ -219,6 +219,13 @@ const sharedModuleCatalogEntries = [
     fileIdentifier: "PRST",
     source: "orbpro-propagator",
   },
+  {
+    schemaCode: "ESTIMATION",
+    schemaName: "Estimation.fbs",
+    fileIdentifier: "$EST",
+    rootTypeName: "EstimationEnvelope",
+    source: "orbpro-estimation",
+  },
   {
     schemaCode: "ACCESSWINDOWREQUEST",
     schemaName: "AccessWindowRequest.fbs",

package/templates/estimation-module/README.md

@@ -0,0 +1,24 @@
+# Estimation reference module
+
+This is the force-model-blind reference implementation for the fixed
+estimation ABI. It demonstrates one covariance-form position update using an
+`OrbProEstimationPropagatorSample` supplied by the caller. It never propagates
+an orbit and never names a provider: production estimators obtain state and
+STM samples from the caller-selected `plugin_propagate` /
+`plugin_compute_stm` port.
+
+The reference export is:
+
+```c
+int32_t orbpro_estimation_reference_position_update(
+    const OrbProEstimationConfig*,
+    const OrbProEstimationObservation*,
+    const OrbProEstimationPropagatorSample*,
+    OrbProEstimationState*);
+```
+
+It accepts only a three-lane `POSITION_VECTOR` observation. That narrow shape
+is deliberate: the reference proves ABI layout, covariance update, typed
+refusal and deterministic bytes. The estimation conformance kit adjudicates
+full modules against Orekit, Vallado, media, Monte-Carlo and runtime evidence.
+It is not a second JS physics implementation.

package/templates/estimation-module/build.mjs

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compileModuleFromSource } from "space-data-module-sdk/compiler";
+
+const require = createRequire(import.meta.url);
+const root = fileURLToPath(new URL(".", import.meta.url));
+const manifest = JSON.parse(await fs.readFile(path.join(root, "plugin-manifest.json"), "utf8"));
+const source = await fs.readFile(path.join(root, "src/reference_estimation.cpp"), "utf8");
+const propagatorHeader = await fs.readFile(
+  require.resolve("space-data-module-sdk/include/orbpro/orbpro_propagator_abi.h"), "utf8");
+const estimationHeader = (await fs.readFile(
+  require.resolve("space-data-module-sdk/include/orbpro/orbpro_estimation_abi.h"), "utf8"))
+  .replace('#include "orbpro/orbpro_propagator_abi.h"', "");
+const translationUnit = source
+  .replace('#include "orbpro/orbpro_propagator_abi.h"', propagatorHeader)
+  .replace('#include "orbpro/orbpro_estimation_abi.h"', estimationHeader);
+const outputPath = path.join(root, "dist/isomorphic/module.wasm");
+await fs.rm(path.join(root, "dist"), { recursive: true, force: true });
+await fs.mkdir(path.dirname(outputPath), { recursive: true });
+const result = await compileModuleFromSource({
+  manifest,
+  sourceCode: translationUnit,
+  language: "c++",
+  outputPath,
+  threadModel: manifest.threadModel,
+});
+if (!result.report?.ok) throw new Error(JSON.stringify(result.report?.issues ?? [], null, 2));
+await fs.copyFile(path.join(root, "plugin-manifest.json"), path.join(root, "dist/plugin-manifest.json"));
+console.log(`Built ${path.relative(root, outputPath)} with ${result.compiler}`);

package/templates/estimation-module/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "space-data-network-module-estimation-reference",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "node build.mjs"
+  },
+  "dependencies": {
+    "space-data-module-sdk": "^0.8.16"
+  }
+}

package/templates/estimation-module/plugin-manifest.json

@@ -0,0 +1,34 @@
+{
+  "pluginId": "com.orbpro.estimation.reference",
+  "name": "Estimation ABI Reference",
+  "version": "0.1.0",
+  "description": "Force-model-blind covariance update reference for the ratified estimation ABI.",
+  "pluginFamily": "analysis",
+  "capabilities": [],
+  "externalInterfaces": [],
+  "invokeSurfaces": ["direct"],
+  "runtimeTargets": ["browser", "wasmedge"],
+  "threadModel": "wasi-sequential",
+  "sequentialJustification": {
+    "kind": "inherently-sequential-algorithm",
+    "detail": "One six-state covariance update is order-dependent and small; callers parallelize independent tracks. The artifact still uses the sanctioned wasm32-wasip1-threads compiler lane."
+  },
+  "methods": [
+    {
+      "methodId": "abi_probe",
+      "displayName": "ABI Probe",
+      "description": "Returns success after the artifact has instantiated; estimation data uses the fixed direct export documented in README.md.",
+      "inputPorts": [],
+      "outputPorts": [],
+      "maxBatch": 1,
+      "drainPolicy": "single-shot"
+    }
+  ],
+  "schemasUsed": [
+    {"schemaName": "Estimation.fbs", "fileIdentifier": "$EST", "rootTypeName": "EstimationEnvelope"}
+  ],
+  "buildArtifacts": [
+    {"artifactId": "estimation-reference-isomorphic", "kind": "wasm", "path": "dist/isomorphic/module.wasm", "target": "browser,wasmedge"}
+  ],
+  "abiVersion": 1
+}

package/templates/estimation-module/src/reference_estimation.cpp

@@ -0,0 +1,53 @@
+#include "orbpro/orbpro_propagator_abi.h"
+#include "orbpro/orbpro_estimation_abi.h"
+
+#include <cmath>
+#include <cstdint>
+
+#if defined(__wasm__)
+#define ESTIMATION_EXPORT(name) __attribute__((export_name(name))) extern "C"
+#else
+#define ESTIMATION_EXPORT(name) extern "C"
+#endif
+
+extern "C" int abi_probe(void) { return 0; }
+
+ESTIMATION_EXPORT("orbpro_estimation_reference_position_update")
+int32_t orbpro_estimation_reference_position_update(
+    const OrbProEstimationConfig* config,
+    const OrbProEstimationObservation* observation,
+    const OrbProEstimationPropagatorSample* sample,
+    OrbProEstimationState* output) {
+  if (config == nullptr || observation == nullptr || sample == nullptr || output == nullptr) {
+    return ORBPRO_ESTIMATION_NULL_OUTPUT;
+  }
+  if (observation->kind != ORBPRO_MEASUREMENT_POSITION_VECTOR ||
+      observation->value_count != 3) {
+    return ORBPRO_ESTIMATION_BAD_INPUT;
+  }
+
+  orbpro_estimation_state_init(output);
+  output->epoch[0] = sample->epoch[0];
+  output->epoch[1] = sample->epoch[1];
+  for (int axis = 0; axis < 6; ++axis) {
+    output->state[axis] = sample->state[axis];
+    for (int column = 0; column < 6; ++column) {
+      output->covariance[axis * 6 + column] = config->initial_covariance[axis * 6 + column];
+    }
+  }
+  for (int axis = 0; axis < 3; ++axis) {
+    const double prior = output->covariance[axis * 6 + axis];
+    const double sigma = observation->sigma[axis];
+    if (!(prior > 0.0) || !(sigma > 0.0) || !std::isfinite(sigma)) {
+      return ORBPRO_ESTIMATION_BAD_INPUT;
+    }
+    const double measurement_variance = sigma * sigma;
+    const double gain = prior / (prior + measurement_variance);
+    output->state[axis] += gain * (observation->value[axis] - output->state[axis]);
+    output->covariance[axis * 6 + axis] = (1.0 - gain) * prior;
+  }
+  output->accepted_count = 1;
+  output->converged = 1;
+  output->estimator = ORBPRO_ESTIMATOR_EXTENDED_KALMAN_FILTER;
+  return ORBPRO_ESTIMATION_OK;
+}