space-data-module-sdk 0.8.15 → 0.8.16

package/docs/llms.txt

@@ -0,0 +1,86 @@
+# Space Data Module SDK
+
+> Build a WebAssembly module that plugs into the Space Data Network and into
+> any consuming engine through a uniform harness ABI. One family per kind of
+> scenario behavior; one thirteen-section spine per family. Statuses below are
+> literal: only SHIPPED families have a ratified generated header, a
+> conformance kit and a reference module.
+
+Toolchain, non-negotiable: compile guest modules with
+`clang --target=wasm32-wasip1-threads` (pinned WASI SDK). `emcc -pthread` is
+FORBIDDEN — Emscripten's pthread model is browser-only and cannot thread under
+WasmEdge, which breaks tri-runtime isomorphism. Modules must be EH-free.
+
+## Start here
+
+- [Harness family matrix](https://digitalarsenal.github.io/space-data-module-sdk/): every family and its status.
+- [BYO-wasm quickstart](https://digitalarsenal.github.io/space-data-module-sdk/byo-wasm-quickstart.html): multi-TU C++ to a loadable artifact.
+- [Conformance kit](https://digitalarsenal.github.io/space-data-module-sdk/conformance.html): self-test commands and what each asserts.
+- [Protect and sign](https://digitalarsenal.github.io/space-data-module-sdk/protect-and-sign.html): artifact protection and signing.
+- [Publication and listing](https://digitalarsenal.github.io/space-data-module-sdk/publication-submission.html): publication records and submission.
+
+## Harness families
+
+### Dynamics
+
+- [Propagator](https://digitalarsenal.github.io/space-data-module-sdk/families/propagator.html) — SHIPPED. Advance a vehicle state to a requested epoch. The reference family: generated header, conformance kit, reference module.
+- [Maneuver](https://digitalarsenal.github.io/space-data-module-sdk/families/maneuver.html) — EXPERIMENTAL. Apply an impulsive or finite burn to a state and report the resulting trajectory change.
+- [Propulsion](https://digitalarsenal.github.io/space-data-module-sdk/families/propulsion.html) — PLANNED. Model thrust production and propellant consumption as a supplier to the maneuver family.
+- [Attitude](https://digitalarsenal.github.io/space-data-module-sdk/families/attitude.html) — PLANNED. Produce body orientation over time, independent of translational state.
+- [GNC](https://digitalarsenal.github.io/space-data-module-sdk/families/gnc.html) — PLANNED. Closed-loop guidance, navigation and control that commands the maneuver and attitude families.
+
+### Environment and interaction
+
+- [RF](https://digitalarsenal.github.io/space-data-module-sdk/families/rf.html) — DESIGNED. Link budgets, coverage and interference. Records-in/records-out RF needs no harness; the harness exists for RF that writes scene state.
+- [Sensor](https://digitalarsenal.github.io/space-data-module-sdk/families/sensor.html) — PLANNED. Detection geometry and sensor tasking: what an instrument can see, when.
+- [Signature](https://digitalarsenal.github.io/space-data-module-sdk/families/signature.html) — PLANNED. Observable signature models — radar cross section, optical magnitude, thermal.
+- [Environment](https://digitalarsenal.github.io/space-data-module-sdk/families/environment.html) — PLANNED. Atmosphere, gravity field, magnetic field, and radiation environment models consumed by other families.
+- [Obstruction](https://digitalarsenal.github.io/space-data-module-sdk/families/obstruction.html) — DESIGNED. Line-of-sight occlusion against arbitrary 3D geometry with per-material electromagnetic properties.
+
+### Event physics
+
+- [Breakup](https://digitalarsenal.github.io/space-data-module-sdk/families/breakup.html) — PLANNED. Fragmentation events producing a debris population that must match the standard breakup model.
+- [Reentry](https://digitalarsenal.github.io/space-data-module-sdk/families/reentry.html) — PLANNED. Atmospheric reentry survivability, ablation, and ground footprint.
+- [Conjunction](https://digitalarsenal.github.io/space-data-module-sdk/families/conjunction.html) — DESIGNED. Close-approach screening and probability of collision over a catalog.
+- [Effects](https://digitalarsenal.github.io/space-data-module-sdk/families/effects.html) — PLANNED. Visual and volumetric effects driven by an event physics family.
+
+### Estimation, data and logic
+
+- [Estimation](https://digitalarsenal.github.io/space-data-module-sdk/families/estimation.html) — EXPERIMENTAL. Orbit determination and filtering: observations in, estimated state and covariance out.
+- [Data source](https://digitalarsenal.github.io/space-data-module-sdk/families/data-source.html) — SHIPPED. Fetch, parse and normalize external provider data into standards records inside the module.
+- [Analytics](https://digitalarsenal.github.io/space-data-module-sdk/families/analytics.html) — EXPERIMENTAL. Derived figures of merit computed over a scenario. The event-location sub-harness is shaped and measured; the rest is planned.
+- [Scheduler](https://digitalarsenal.github.io/space-data-module-sdk/families/scheduler.html) — PLANNED. Ordering and tasking of activities across a scenario timeline.
+- [Behavior](https://digitalarsenal.github.io/space-data-module-sdk/families/behavior.html) — PLANNED. Scripted or reactive decision logic that drives other families.
+
+## Runtime contract
+
+- [Event locator ABI](https://digitalarsenal.github.io/space-data-module-sdk/events-abi.html)
+- [Module publication standard](https://digitalarsenal.github.io/space-data-module-sdk/module-publication-standard.html)
+- [Browser / WasmEdge isomorphism](https://digitalarsenal.github.io/space-data-module-sdk/browser-wasmedge-isomorphic.html)
+- [Isomorphic pthreads](https://digitalarsenal.github.io/space-data-module-sdk/isomorphic-pthreads.html)
+- [Tri-runtime parity](https://digitalarsenal.github.io/space-data-module-sdk/tri-runtime-parity.html)
+- [Tri-runtime parity gate](https://digitalarsenal.github.io/space-data-module-sdk/tri-runtime-parity-gate.html)
+- [Testing harness](https://digitalarsenal.github.io/space-data-module-sdk/testing-harness.html)
+- [Language and runtime matrix](https://digitalarsenal.github.io/space-data-module-sdk/language-runtime-matrix.html)
+- [FlatSQL host contract](https://digitalarsenal.github.io/space-data-module-sdk/flatsql-host-contract.html)
+- [FlatSQL streaming standard](https://digitalarsenal.github.io/space-data-module-sdk/flatsql-streaming-standard.html)
+- [Credential lanes](https://digitalarsenal.github.io/space-data-module-sdk/secrets-capability.html)
+- [Protocol installation](https://digitalarsenal.github.io/space-data-module-sdk/protocol-installation.html)
+- [GPU module ABI](https://digitalarsenal.github.io/space-data-module-sdk/gpu-module-abi.html)
+- [Module bundle runtime](https://digitalarsenal.github.io/space-data-module-sdk/module-bundle-runtime-plan.html)
+- [Isomorphic SDN runtime](https://digitalarsenal.github.io/space-data-module-sdk/isomorphic-sdn-runtime-plan.html)
+- [Node-RED node parity](https://digitalarsenal.github.io/space-data-module-sdk/node-red-default-node-parity.html)
+
+## Rules for an agent writing a module
+
+1. Read the family page for your family FIRST; implement the exact export set it names.
+2. Never invent an export, a struct field or an error code. If the page says a
+   family is DESIGNED or PLANNED, it has no stable ABI — do not ship against it.
+3. Use the family's `.fbs`-generated header as the wire contract; do not
+   hand-write struct layouts.
+4. Return the family's named negative error codes, never a generic -1, and never
+   NaN or unphysical values as a success result.
+5. Prove the module with the conformance self-test and the parity gate before
+   protecting, signing or publishing it.
+6. Internal engine JS registries are not a public contract and never an
+   extension point. Harness contracts are WASM ABIs only.

package/docs/module-bundle-runtime-plan.html

@@ -0,0 +1,146 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="This document is superseded by:" />
+    <title>Module bundle runtime — Space Data Module SDK</title>
+    <link rel="stylesheet" href="./styles.css" />
+    <!-- SDN_CONSUMER_ASSETS_START -->
+<link rel="stylesheet" href="https://static.spacedatanetwork.org/assets/hd-wallet-ui/2.0.28/sdn-wallet-public-client.c3f68d1cfd88478f10d836a5e829d1dfc6a10157972cf0f7d4d319d0636f2cc4.css" integrity="sha384-fICuhN4I9xqOK1F5vGGzl26opuO+xQIvTZXMSV76lWTBiQ6AfzztMGLLDw8yRT8i" crossorigin="anonymous">
+<script defer src="https://static.spacedatanetwork.org/assets/hd-wallet-ui/2.0.28/sdn-wallet-public-client.f611e7e151a3b5c38384272f8894a4c6634f0a29bf925b0e02e0e27f8db0bfff.js" integrity="sha384-R+QqsKoWJIS7iWrtPmgJ49DVnb1hSGjZokupbLInJd1PLp8RwQhtF/hnaerc33ci" crossorigin="anonymous" data-sdn-wallet-public-client="v1"></script>
+<script defer src="https://static.spacedatanetwork.org/assets/sdn-stack-nav/1.0.0/sdn-stack-nav.52fde607eee38ffa116188201f50258ed50bd18c9f06c1af9678f763147a8fe5.js" integrity="sha384-dgeojhJ8vTszHXIbv7O7nZcEzqD10oUYYJjBmPrV7+kLQEUlXLQD4ek5Q7HOFiO5" crossorigin="anonymous" data-nav-style-url="https://static.spacedatanetwork.org/assets/sdn-stack-nav/1.0.0/sdn-stack-nav.36a36359ce18322185e9ff179f88175bab67d5ad84a14d9c08a54f2ff27267e7.css" data-nav-style-integrity="sha384-c4M8Fg+kYaeOYYtJVr7jJsde24IhSWkWaRyAOHEZU9jozhRck089aw+mnHwxymds" data-wallet-client-url="https://static.spacedatanetwork.org/assets/hd-wallet-ui/2.0.28/sdn-wallet-public-client.f611e7e151a3b5c38384272f8894a4c6634f0a29bf925b0e02e0e27f8db0bfff.js" data-wallet-client-integrity="sha384-R+QqsKoWJIS7iWrtPmgJ49DVnb1hSGjZokupbLInJd1PLp8RwQhtF/hnaerc33ci" data-wallet-style-url="https://static.spacedatanetwork.org/assets/hd-wallet-ui/2.0.28/sdn-wallet-public-client.c3f68d1cfd88478f10d836a5e829d1dfc6a10157972cf0f7d4d319d0636f2cc4.css" data-wallet-style-integrity="sha384-fICuhN4I9xqOK1F5vGGzl26opuO+xQIvTZXMSV76lWTBiQ6AfzztMGLLDw8yRT8i" data-wallet-client-id="sdn-module-sdk-pages-v1" data-wallet-callback-uri="https://digitalarsenal.github.io/space-data-module-sdk/wallet-callback.html" data-wallet-registry-sha256="e1ce6fe903c9700484a8a87d96581c8cad97063dabf63030b4518a31a3bdaa93"></script>
+<!-- SDN_CONSUMER_ASSETS_END -->
+  </head>
+  <body>
+    <a class="skip-link" href="#main">Skip to content</a>
+    <sdn-stack-nav active="module-sdk"></sdn-stack-nav>
+    <header class="site-header">
+      <a class="site-brand" href="./">Space Data Module SDK</a>
+      <nav class="header-links" aria-label="Site">
+        <a href="./byo-wasm-quickstart.html">Quickstart</a>
+        <a href="./conformance.html">Conformance</a>
+        <a href="https://github.com/DigitalArsenal/space-data-module-sdk">GitHub</a>
+        <a class="stack-button" href="#stack">Stack</a>
+      </nav>
+    </header>
+    <div class="shell">
+      <nav class="sidebar" id="sidebar" aria-label="Documentation">
+<h2>Start here</h2><ul>
+<li><a href="./index.html"><span>Harness family matrix</span></a></li>
+<li><a href="./byo-wasm-quickstart.html"><span>BYO-wasm quickstart</span></a></li>
+<li><a href="./conformance.html"><span>Conformance kit</span></a></li>
+<li><a href="./protect-and-sign.html"><span>Protect and sign</span></a></li>
+<li><a href="./publication-submission.html"><span>Publication and listing</span></a></li>
+</ul>
+<h2>Dynamics</h2><ul>
+<li><a href="./families/propagator.html"><span>Propagator</span><span class="tag tag-shipped">shipped</span></a></li>
+<li><a href="./families/maneuver.html"><span>Maneuver</span><span class="tag tag-experimental">experimental</span></a></li>
+<li><a href="./families/propulsion.html"><span>Propulsion</span><span class="tag tag-planned">planned</span></a></li>
+<li><a href="./families/attitude.html"><span>Attitude</span><span class="tag tag-planned">planned</span></a></li>
+<li><a href="./families/gnc.html"><span>GNC</span><span class="tag tag-planned">planned</span></a></li>
+</ul>
+<h2>Environment and interaction</h2><ul>
+<li><a href="./families/rf.html"><span>RF</span><span class="tag tag-designed">designed</span></a></li>
+<li><a href="./families/sensor.html"><span>Sensor</span><span class="tag tag-planned">planned</span></a></li>
+<li><a href="./families/signature.html"><span>Signature</span><span class="tag tag-planned">planned</span></a></li>
+<li><a href="./families/environment.html"><span>Environment</span><span class="tag tag-planned">planned</span></a></li>
+<li><a href="./families/obstruction.html"><span>Obstruction</span><span class="tag tag-designed">designed</span></a></li>
+</ul>
+<h2>Event physics</h2><ul>
+<li><a href="./families/breakup.html"><span>Breakup</span><span class="tag tag-planned">planned</span></a></li>
+<li><a href="./families/reentry.html"><span>Reentry</span><span class="tag tag-planned">planned</span></a></li>
+<li><a href="./families/conjunction.html"><span>Conjunction</span><span class="tag tag-designed">designed</span></a></li>
+<li><a href="./families/effects.html"><span>Effects</span><span class="tag tag-planned">planned</span></a></li>
+</ul>
+<h2>Estimation, data and logic</h2><ul>
+<li><a href="./families/estimation.html"><span>Estimation</span><span class="tag tag-experimental">experimental</span></a></li>
+<li><a href="./families/data-source.html"><span>Data source</span><span class="tag tag-shipped">shipped</span></a></li>
+<li><a href="./families/analytics.html"><span>Analytics</span><span class="tag tag-experimental">experimental</span></a></li>
+<li><a href="./families/scheduler.html"><span>Scheduler</span><span class="tag tag-planned">planned</span></a></li>
+<li><a href="./families/behavior.html"><span>Behavior</span><span class="tag tag-planned">planned</span></a></li>
+</ul>
+<h2>Runtime contract</h2><ul>
+<li><a href="./events-abi.html"><span>Event locator ABI</span></a></li>
+<li><a href="./module-publication-standard.html"><span>Module publication standard</span></a></li>
+<li><a href="./browser-wasmedge-isomorphic.html"><span>Browser / WasmEdge isomorphism</span></a></li>
+<li><a href="./isomorphic-pthreads.html"><span>Isomorphic pthreads</span></a></li>
+<li><a href="./tri-runtime-parity.html"><span>Tri-runtime parity</span></a></li>
+<li><a href="./tri-runtime-parity-gate.html"><span>Tri-runtime parity gate</span></a></li>
+<li><a href="./testing-harness.html"><span>Testing harness</span></a></li>
+<li><a href="./language-runtime-matrix.html"><span>Language and runtime matrix</span></a></li>
+</ul>
+<h2>Host surfaces</h2><ul>
+<li><a href="./flatsql-host-contract.html"><span>FlatSQL host contract</span></a></li>
+<li><a href="./flatsql-streaming-standard.html"><span>FlatSQL streaming standard</span></a></li>
+<li><a href="./secrets-capability.html"><span>Credential lanes</span></a></li>
+<li><a href="./protocol-installation.html"><span>Protocol installation</span></a></li>
+<li><a href="./gpu-module-abi.html"><span>GPU module ABI</span></a></li>
+<li><a href="./module-bundle-runtime-plan.html" aria-current="page"><span>Module bundle runtime</span></a></li>
+<li><a href="./isomorphic-sdn-runtime-plan.html"><span>Isomorphic SDN runtime</span></a></li>
+<li><a href="./node-red-default-node-parity.html"><span>Node-RED node parity</span></a></li>
+</ul>
+      </nav>
+      <main class="doc" id="main">
+        <h1>Module bundle runtime</h1>
+<p>This document is superseded by:</p>
+<ul>
+<li>module-publication-standard.md</li>
+<li>isomorphic-sdn-runtime-plan.md</li>
+</ul>
+<p>The old document is no longer current because:</p>
+<ul>
+<li>the canonical publication model now explicitly allows appended <code>REC</code> records carrying <code>PNM</code> and <code>ENC</code></li>
+<li>the canonical runtime discussion has moved to the SDK runtime host model</li>
+<li>bundle/container concerns and runtime-host concerns are now documented separately</li>
+</ul>
+<p>Current rule summary:</p>
+<ul>
+<li>the executable artifact is still canonical <code>.wasm</code></li>
+<li>single-file bundle metadata is carried by an <code>MBL</code> record inside one appended <code>REC</code> trailer</li>
+<li>publication/signature/encryption metadata is carried in that same appended <code>REC</code> trailer when present</li>
+<li>runtime hosting is defined by the SDK runtime host, not by the bundle container itself</li>
+</ul>
+
+        <p class="doc-footer">
+          Source of truth for this page:
+          <code>docs/module-bundle-runtime-plan.md</code>. Regenerate with
+          <code>npm run build:docs</code>.
+        </p>
+      </main>
+
+    </div>
+    <section id="stack" class="section" aria-labelledby="stack-title">
+      <div class="section-head">
+        <p class="eyebrow">SDN Stack</p>
+        <h2 id="stack-title">Connected sites</h2>
+      </div>
+      <div class="link-list">
+        <a href="https://spacedatastandards.org/">
+          <span>Standards</span>
+          <small>Canonical schemas, record contracts, and generated bindings.</small>
+        </a>
+        <a href="https://digitalarsenal.github.io/flatbuffers/">
+          <span>FlatBuffers</span>
+          <small>Binary encoding, schema tooling, and runtime documentation.</small>
+        </a>
+        <a href="https://digitalarsenal.github.io/flatsql/">
+          <span>FlatSQL</span>
+          <small>SQL-style queries over FlatBuffer-backed datasets and streams.</small>
+        </a>
+        <a href="https://spacedatanetwork.org/">
+          <span>SDN</span>
+          <small>Distributed publication, discovery, delivery, and marketplace infrastructure.</small>
+        </a>
+        <a href="https://digitalarsenal.github.io/space-data-module-sdk/" class="active">
+          <span>Module SDK</span>
+          <small>WASM module packaging, validation, and host compatibility tooling.</small>
+        </a>
+      </div>
+    </section>
+    <footer class="site-footer">
+      Space Data Module SDK — Apache-2.0. Every ABI page renders a Markdown
+      source in <code>docs/</code>; edit the Markdown, never the HTML.
+    </footer>
+  </body>
+</html>