space-data-module-sdk 0.8.15 → 0.8.16

package/docs/byo-wasm-quickstart.md

@@ -0,0 +1,204 @@
+# BYO-wasm quickstart
+
+Bring your own WebAssembly. This is the vendor path: you compile your existing
+C or C++ with your own build system, against the pinned toolchain and the
+family ABI header, and hand the SDK a finished `module.wasm`. You do not need
+access to any private repository, and you do not have to route your source
+through the SDK's own compiler.
+
+If you would rather have the SDK drive the compiler for you, the
+`space-data-module compile` command exists and applies the same toolchain
+resolution described below. The BYO lane is the supported path for a vendor
+with an established build.
+
+## 1. The toolchain pin
+
+This is the only sanctioned toolchain for a guest module, and it is not
+negotiable:
+
+> Compile guest modules with `clang --target=wasm32-wasip1-threads` (WASI SDK,
+> pinned by the repository's CI workflows). This is the ONLY sanctioned
+> toolchain for `module.wasm`. `emcc -pthread` is FORBIDDEN for module
+> compilation: Emscripten's pthread model is browser-only and cannot thread
+> under WasmEdge, which breaks tri-runtime isomorphism (see
+> [Isomorphic pthreads](isomorphic-pthreads.html)). Modules must be EH-free.
+> `flowcc` composes a runtime from prebuilt objects; it is not a WASI rebuild
+> step.
+
+The template headers carry the same one-line doctrine:
+`Build: clang --target=wasm32-wasip1-threads (never emcc -pthread)`.
+
+### Toolchain triples
+
+| Purpose | Value |
+| --- | --- |
+| Compile target | `wasm32-wasip1-threads` |
+| Sysroot triple (threads libc / libc++) | `wasm32-wasip1-threads` |
+| Resource-dir triple (compiler-rt builtins) | `wasm32-unknown-wasip1-threads` |
+| Default drivers on `PATH` | `wasm32-wasi-clang`, `wasm32-wasi-clang++` |
+
+The SDK resolves the sysroot by looking for `lib/wasm32-wasip1-threads/libc.a`
+under, in order, `/opt/homebrew/share/wasi-sysroot`,
+`/usr/local/share/wasi-sysroot`, `/opt/wasi-sdk/share/wasi-sysroot`, and
+versioned Homebrew cellar paths. It resolves the resource directory by looking
+for `lib/wasm32-unknown-wasip1-threads/libclang_rt.builtins.a` under
+`/opt/homebrew/share/wasi-runtimes`, `/usr/local/share/wasi-runtimes`, and the
+versioned cellar equivalents.
+
+If nothing is found the SDK tells you exactly this:
+
+> Install a wasi-sdk / wasi-libc+wasi-runtimes toolchain with the
+> wasm32-wasip1-threads target (e.g. `brew install wasi-libc wasi-runtimes` or a
+> wasi-sdk release), or set the `SDN_WASI_*` env overrides.
+
+### Environment overrides
+
+Set these when your toolchain lives somewhere else — for example inside your own
+container image:
+
+| Variable | Overrides |
+| --- | --- |
+| `SDN_WASI_CLANG` | C driver binary |
+| `SDN_WASI_CLANGXX` | C++ driver binary |
+| `SDN_WASI_TARGET` | Compile target triple |
+| `SDN_WASI_SYSROOT` | Sysroot path |
+| `SDN_WASI_RESOURCE_DIR` | compiler-rt resource directory |
+
+## 2. The flag set
+
+Object files are compiled with atomics, no exceptions, and threads:
+
+```sh
+wasm32-wasi-clang++ \
+  --target=wasm32-wasip1-threads \
+  --sysroot="$WASI_SYSROOT" \
+  -resource-dir="$WASI_RESOURCE_DIR" \
+  -matomics -fno-exceptions -pthread \
+  -O2 -c src/my_module.cpp -o build/my_module.o
+```
+
+The link step adds the shared-memory and imported-memory contract:
+
+```sh
+wasm32-wasi-clang++ \
+  --target=wasm32-wasip1-threads \
+  --sysroot="$WASI_SYSROOT" \
+  -resource-dir="$WASI_RESOURCE_DIR" \
+  -pthread -matomics -mbulk-memory \
+  -Wl,--import-memory -Wl,--shared-memory -Wl,--max-memory=2147483648 \
+  -O2 build/*.o -o dist/isomorphic/module.wasm
+```
+
+`-pthread -matomics -mbulk-memory -Wl,--import-memory -Wl,--shared-memory
+-Wl,--max-memory=2147483648` is the enforced flag set. A module linked without
+it will not satisfy the parity gate.
+
+### Multi-translation-unit builds
+
+Nothing about the contract is single-file. Compile every translation unit with
+the object-file flags above and link them in one step. A minimal `Makefile`:
+
+```make
+WASI_SYSROOT ?= /opt/homebrew/share/wasi-sysroot
+WASI_RESOURCE_DIR ?= /opt/homebrew/share/wasi-runtimes
+CXX := wasm32-wasi-clang++
+
+TARGET_FLAGS := --target=wasm32-wasip1-threads \
+                --sysroot=$(WASI_SYSROOT) \
+                -resource-dir=$(WASI_RESOURCE_DIR)
+CXXFLAGS := $(TARGET_FLAGS) -matomics -fno-exceptions -pthread -O2 -Iinclude
+LDFLAGS  := $(TARGET_FLAGS) -pthread -matomics -mbulk-memory \
+            -Wl,--import-memory -Wl,--shared-memory \
+            -Wl,--max-memory=2147483648 -O2
+
+SRCS := $(wildcard src/*.cpp)
+OBJS := $(SRCS:src/%.cpp=build/%.o)
+
+dist/isomorphic/module.wasm: $(OBJS)
+	@mkdir -p $(dir $@)
+	$(CXX) $(LDFLAGS) $(OBJS) -o $@
+
+build/%.o: src/%.cpp
+	@mkdir -p build
+	$(CXX) $(CXXFLAGS) -c $< -o $@
+
+clean:
+	rm -rf build dist
+```
+
+Constraints that bite in practice:
+
+- **EH-free.** Compile with `-fno-exceptions`. Do not throw across the ABI
+  boundary; return a named negative error code instead.
+- **No `emcc`.** Not for one translation unit, not for a dependency, not
+  "temporarily for the browser build". One artifact serves every runtime.
+- **No host-specific imports.** The parity gate classifies your import set
+  against the declared host contract and fails on a forbidden import class.
+
+## 3. Implement the family ABI
+
+Pick your family from the [harness family matrix](index.html) and implement
+exactly the export set that family's page names. Include the family's generated
+ABI header from the SDK — do not hand-write the struct layouts, because the
+headers carry `_Static_assert` size and offset locks that are the whole point of
+the generated wire contract.
+
+```cpp
+#include <orbpro/orbpro_propagator_abi.h>
+```
+
+The SDK ships the headers under `include/` and exports them through the package
+(`space-data-module-sdk/include/*`), so a vendor consuming the SDK from npm gets
+the same bytes the generator produced.
+
+## 4. Declare the manifest
+
+A module carries an embedded manifest declaring its plugin id, family, invoke
+surface, runtime targets, methods, ports, and the standards record types it
+consumes and emits. See the
+[module publication standard](module-publication-standard.html) for the record
+layout and [conformance](conformance.html) for what is checked.
+
+> **Status: still being built.** There is no tool today that stamps a manifest
+> onto a binary produced by a foreign toolchain. Manifest normalization and
+> codecs exist for modules authored inside the SDK's own build path, but a
+> `manifest inject` verb for a BYO binary does not exist yet — it is Sprint 1 of
+> the third-party integration program. Until it lands, a BYO vendor supplies the
+> manifest JSON alongside the artifact and the manifest is attached for them.
+
+## 5. Prove it, then ship it
+
+```sh
+# ABI conformance for your family
+space-data-module conformance propagator --artifact ./dist/isomorphic/module.wasm
+
+# tri-runtime parity: browser + WasmEdge + Docker WasmEdge, byte-identical
+space-data-module parity \
+  --wasm ./dist/isomorphic/module.wasm \
+  --fixture ./fixtures/parity/basic.json \
+  --lanes browser,wasmedge,docker-wasmedge
+```
+
+Then continue with [Conformance kit](conformance.html),
+[Protect and sign](protect-and-sign.html), and
+[Publication and listing](publication-submission.html).
+
+## Honest gaps in this lane
+
+These are checked statements about the SDK today, not future tense for its own
+sake:
+
+- The toolchain flags and triples above are real and enforced, but they are
+  applied by the SDK's internal compiler resolver. The `Makefile` on this page
+  is a documented recipe assembled from those enforced values; the repository
+  does not yet ship a `Makefile`, `CMakeLists.txt` or `build.sh` template for a
+  hand-rolled multi-TU build.
+- `conformance --self-test` currently accepts only the `propagator` family. Any
+  other family argument raises an unknown-family error.
+- Manifest injection for foreign-compiled binaries does not exist yet.
+- There is no self-serve listing submission command yet. See
+  [Publication and listing](publication-submission.html).
+
+An escorted pilot is possible today: a vendor delivers a BYO artifact and the
+gates are run and the module listed by hand. The program above is what makes
+that self-serve.

package/docs/conformance.html

@@ -0,0 +1,156 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="Status: v1 — W1.4 of graph/tasks/official-harness-shapes-program.md," />
+    <title>Conformance kit — 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" aria-current="page"><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"><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>Conformance kit</h1>
+<p><strong>Status:</strong> v1 — W1.4 of <code>graph/tasks/official-harness-shapes-program.md</code>, implementing <code>graph/findings/official-harness-shapes.md</code> §5. Family kits: <code>propagator</code> (SHIP 1). Maneuver is Wave 2 (EXPERIMENTAL, fix-then-freeze); OD is deferred by ruling. <strong>A family with no kit can never be <code>CORE</code>.</strong></p>
+<p>WASM artifacts ONLY (owner ruling 2026-08-10: &quot;No JS propagator!!!! WASM ONLY&quot;). The runner instantiates a compiled <code>dist/isomorphic/module.wasm</code> and drives the family's ABI directly; there is no path that certifies a JavaScript object, because JS registries are internal engine plumbing, never a public contract.</p>
+<h2 id="commands"><a class="anchor" href="#commands" aria-hidden="true">#</a>Commands</h2>
+<div class="codeblock"><pre><code>space-data-module conformance propagator --artifact ./dist/isomorphic/module.wasm
+space-data-module conformance propagator --artifact ./dist/isomorphic/module.wasm \
+    --vectors ./vectors/vectors.json --json
+space-data-module conformance propagator --self-test    # must exit 0 BY failing</code></pre></div>
+<ul>
+<li><code>--artifact</code> — the compiled module. Its sha256 goes in the report; a conformance claim binds to CONTENT, not to a name.</li>
+<li><code>--vectors</code> — the module's corpus (<code>vectors.json</code> + <code>PROVENANCE.md</code>, the format proven by the reference module's <code>vectors/</code> suite). Default: the runner walks up from the artifact to the package root and takes <code>vectors/vectors.json</code>. <strong>The corpus is the module's own</strong>: Tier B anchors are model-specific, so a two-body corpus is never forced onto an SGP4 module, and a missing corpus is a NAMED GAP, never a silent pass.</li>
+<li><code>--leak-warmup / --leak-cycles / --leak-entities</code> — lifecycle-leak window overrides (defaults 20 / 200 / 256, the reference module's proven numbers).</li>
+<li>Exit codes: <code>PASS</code> and <code>PASS-WITH-GAPS</code> exit 0 (gaps are listed in the report); <code>FAIL</code> exits 1 with the offending check and case named.</li>
+</ul>
+<p>Library surface: <code>space-data-module-sdk/conformance</code> exports <code>runConformance</code>, <code>runPropagatorSuite</code>, <code>runPropagatorSelfTest</code>, <code>computeVerdict</code>, the ABI driver and the error-code table.</p>
+<h2 id="what-is-checked"><a class="anchor" href="#what-is-checked" aria-hidden="true">#</a>What is checked</h2>
+<div class="table-wrap"><table><thead><tr><th>Tier</th><th>Check</th><th>Source of authority</th></tr></thead><tbody><tr><td>0</td><td>real instantiation + required export set</td><td><a href="./families/propagator.html">propagator-abi.md</a> §The export set</td></tr><tr><td>0</td><td>cross-runtime byte-identity</td><td><strong>GAP here by design</strong> — the parity gate (<code>space-data-module parity-gate</code>) is the Tier 0 authority; this runner never re-certifies half of it</td></tr><tr><td>B</td><td>corpus anchors reproduced within band</td><td>the module's <code>vectors.json</code> (tolerance policy `abs + rel *</td><td>expected</td><td>`); NaN is its own failure class</td></tr><tr><td>C</td><td>vis-viva closure, period closure</td><td>corpus-declared invariants (<code>conformance.mu</code> from the corpus; ECEF un-rotation when the module declares frame 3) — run only where the corpus declares them applicable to the model</td></tr><tr><td>C</td><td>determinism as BYTES, surviving destroy/re-ingest</td><td>ABI §Parity envelope</td></tr><tr><td>C</td><td>frame/flags/reserved declared, corpus-consistent</td><td>ABI §Frames — a frame declaration that contradicts the module's own corpus is the silently-wrong-numbers defect</td></tr><tr><td>C</td><td>batch and single agree exactly</td><td>ABI §Threading — the batch path is the same physics</td></tr><tr><td>C</td><td>typed refusals (NOT_INITIALIZED / BAD_ENTITY_INDEX / unphysical ingest)</td><td>ABI §Error codes — the degradation ladder needs distinguishable codes</td></tr><tr><td>C</td><td>create RETURNS its handle</td><td>ABI §Identity — &quot;the entity I just created is count−1&quot; is the race the harness exists to kill (finding §4.4)</td></tr><tr><td>4</td><td>lifecycle leak: zero page growth after warm-up</td><td>ABI §Lifetime</td></tr><tr><td>4</td><td>destroy idempotent, refuses typed, comes back cleanly</td><td>ABI §Lifetime</td></tr><tr><td>4</td><td>leak-metric negative control</td><td>a gate never observed to fail is indistinguishable from one that cannot fail</td></tr></tbody></table></div>
+<h2 id="the-self-test"><a class="anchor" href="#the-self-test" aria-hidden="true">#</a>The self-test</h2>
+<p><code>--self-test</code> runs the SAME suite against mock propagators, each carrying ONE planted defect drawn from a real defect class the finding documented live:</p>
+<div class="table-wrap"><table><thead><tr><th>Planted defect</th><th>Real-world citation</th><th>Must be caught by</th></tr></thead><tbody><tr><td><code>units-km</code> (1000× error)</td><td>the <code>orbpro_propagator.h</code> km/meters contradiction (finding §4.1)</td><td><code>tierB/anchors</code></td></tr><tr><td><code>leaky-destroy</code></td><td><code>destroySource(){}</code> in both shipped propagators (§4.5)</td><td><code>tier4/lifecycle-leak</code></td></tr><tr><td><code>confident-nonsense</code> (accepts e ≥ 1)</td><td>the underground phasing orbit (§5)</td><td><code>tierC/typed-refusals</code></td></tr><tr><td><code>count-fallback</code> (returns success, not the handle)</td><td>three families deriving count−1 (§4.4)</td><td><code>tierC/create-returns-handle</code></td></tr><tr><td><code>frame-lies</code> (declares TEME, writes ECEF)</td><td>the Δv frame never pinned (§4.3)</td><td><code>tierC/frame-flags-reserved-declared</code></td></tr><tr><td><code>batch-divergence</code></td><td>batch path not the same physics</td><td><code>tierC/batch-single-agreement</code></td></tr><tr><td><code>nondeterministic</code></td><td>byte-determinism is the parity envelope's floor</td><td><code>tierC/determinism-byte-identity</code></td></tr><tr><td><code>missing-exports</code></td><td>destroy was optional once; it is not now</td><td><code>tier0/instantiation-and-exports</code></td></tr></tbody></table></div>
+<p>The self-test exits 0 only when the conformant baseline mock is clean AND every planted defect is caught by the check that owns it. It needs no toolchain, no artifact and no network — <code>npm run conformance:self-test</code>.</p>
+<h2 id="receipt-trust-wave-4-not-yet-wired"><a class="anchor" href="#receipt-trust-wave-4-not-yet-wired" aria-hidden="true">#</a>Receipt &amp; trust (Wave 4, not yet wired)</h2>
+<p>The conformance receipt travels as a bundle <code>ATTESTATION</code> entry (publisher-signed under bundle scope); the graduated listing requirement (receipt REQUIRED for <code>CORE</code>+<code>ANONYMOUS</code>, badge for <code>RECOMMENDED</code>) and the <code>SDN-CONFORMANCE-RECEIPT-V1</code> third-party attestor domain are W4.1/W4.2 of the program — see the finding §5 &quot;Receipt &amp; trust&quot;.</p>
+<h2 id="reference-implementation"><a class="anchor" href="#reference-implementation" aria-hidden="true">#</a>Reference implementation</h2>
+<p><code>space-data-network-modules propagator/keplerian-reference</code> is the exemplar the kit was generalized from: its <code>tests/</code> are the original expression of these checks, its <code>vectors/</code> suite is the corpus format, and <code>tests/sdk-conformance-runner.test.mjs</code> proves the runner reaches the same verdict on the same artifact — including the corrupted-corpus negative control.</p>
+
+        <p class="doc-footer">
+          Source of truth for this page:
+          <code>docs/conformance.md</code>. Regenerate with
+          <code>npm run build:docs</code>.
+        </p>
+      </main>
+<nav class="rail" aria-label="On this page"><h2>On this page</h2><ul><li><a class="depth-2" href="#commands">Commands</a></li>
+<li><a class="depth-2" href="#what-is-checked">What is checked</a></li>
+<li><a class="depth-2" href="#the-self-test">The self-test</a></li>
+<li><a class="depth-2" href="#receipt-trust-wave-4-not-yet-wired">Receipt &amp; trust (Wave 4, not yet wired)</a></li>
+<li><a class="depth-2" href="#reference-implementation">Reference implementation</a></li></ul></nav>
+    </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>

package/docs/emception-shared-memory-verdict.md

@@ -0,0 +1,209 @@
+# Can emception build the shared-memory wasm-engine? — verdict
+
+**Verdict: NO.** Recorded 2026-08-30 by `obc-05-emception-lane`
+(`graph/tasks/obc-05-emception-lane.md`, OrbPro Build Cutter program). Measured
+in headless Chromium against the real target's real flags. Three independent
+blockers, any one of them fatal; the third is the one that settles it.
+
+The user-module lane — Phase B — **works**, and ships. See §4.
+
+Harness, fixtures and the raw record:
+`OrbPro/packages/orbpro-integration/build-cutter/emception/`
+(`spike/run.mjs` produces `results/emception-lane.json`).
+
+---
+
+## 1. The question
+
+`packages/wasm-engine/build-sdn.sh` builds two Emscripten targets from
+`packages/wasm-engine/src/cpp/CMakeLists.txt`. One of them,
+**`wasm_engine_sdn_browser_shared`**, is the browser presentation artifact:
+`-s IMPORTED_MEMORY=1 -s SHARED_MEMORY=1 -matomics -mbulk-memory` on top of
+`-s STANDALONE_WASM=1`, with a 4 GiB ceiling.
+
+Could the Build Cutter recompile *that* target in a browser tab, with the
+runtime lock (`allowedDomains`, `compiledAtMs`, `ttlDays`) as compiled-in
+constants, so a cut's domain lock lives inside the WASM instead of only in the
+JS mirror?
+
+## 2. What was measured
+
+| | |
+| --- | --- |
+| Target | `wasm_engine_sdn_browser_shared` |
+| Compiler under test | `sdn-emception@1.0.0`, vendored same-origin |
+| Its Emscripten | **3.1.24** (`/emscripten/emscripten-version.txt`, read at run time) |
+| The engine's Emscripten | **6.0.1** (`build-sdn.sh`, `./emsdk install 6.0.1`) |
+| Page | headless Chromium, own ephemeral port, `COOP: same-origin` + `COEP: require-corp`, `crossOriginIsolated === true` |
+| Probe source | `fixtures/engine-lock-probe.cpp` — the lock's three fields as `constexpr`, the JS mirror's predicate, `std::atomic` and `std::thread` |
+| Flags | transcribed from `src/cpp/CMakeLists.txt`, not invented — `compileArgs.mjs` |
+
+## 3. The three blockers, verbatim
+
+### 3.1 The target is a CMake target, and there is no CMake
+
+`build-sdn.sh` runs `emcmake cmake -S src/cpp -B build-wasm` and then
+`cmake --build --target wasm_engine_sdn_browser_shared`. Emception ships
+`/emscripten/emcmake.py` but no `cmake`, no `make`, no `ninja` and no `git`
+(measured; `git` matters because the target's `CMakeLists.txt` pulls GLM in
+through `FetchContent_Declare(... GIT_REPOSITORY ...)`, and the tab has no
+network beyond its own origin).
+
+```
+$ emcmake cmake -S /working/build-cutter/src-cpp -B /working/build-cutter/build-wasm -DCMAKE_BUILD_TYPE=Release
+configure: cmake -S /working/build-cutter/src-cpp -B /working/build-cutter/build-wasm -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=/emscripten/cmake/Modules/Platform/Emscripten.cmake -DCMAKE_CROSSCOMPILING_EMULATOR=/usr/bin/node;--experimental-wasm-threads
+Not found: cmake
+emcmake: error: 'cmake -S /working/build-cutter/src-cpp -B /working/build-cutter/build-wasm -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=/emscripten/cmake/Modules/Platform/Emscripten.cmake -DCMAKE_CROSSCOMPILING_EMULATOR=/usr/bin/node;--experimental-wasm-threads' failed (returned 1)
+```
+
+### 3.2 The engine's own flags do not exist in this Emscripten
+
+Driving `em++` directly, bypassing CMake, with the target's exact flags:
+
+```
+$ em++ -c engine_lock_probe.cpp -std=c++17 -O3 -flto -ffast-math -fno-finite-math-only \
+    -DNDEBUG -msimd128 -fwasm-exceptions -sWASM_LEGACY_EXCEPTIONS=0 -matomics -mbulk-memory -o engine_lock_probe.o
+em++: error: Attempt to set a non-existent setting: 'WASM_LEGACY_EXCEPTIONS'
+ - did you mean one of ABORT_ON_WASM_EXCEPTIONS, LEGACY_SETTINGS?
+ - perhaps a typo in emcc's  -sX=Y  notation?
+ - (see src/settings.js for valid values)
+```
+
+The link step fails identically. Removing `-fwasm-exceptions` and
+`-sWASM_LEGACY_EXCEPTIONS=0` and asking again produces the next one:
+
+```
+em++: error: Attempt to set a non-existent setting: 'STACK_SIZE'
+ - did you mean one of ASYNCIFY_STACK_SIZE?
+```
+
+This is the 3.1.24-versus-6.0.1 gap, one setting at a time. The spike drops
+each named setting and re-asks (`engine-shared-link-relaxed-<n>`, advisory
+probes) rather than reporting only the first — the point is the size of the
+gap, not its first symptom.
+
+### 3.3 This Emscripten refuses the combination outright
+
+With every version-gated setting removed, the shared-memory link finally runs —
+and this is the answer:
+
+```
+$ em++ engine_lock_probe_relaxed.o -O3 -flto -s EXPORTED_FUNCTIONS=[...] -s MODULARIZE=1 \
+    -s EXPORT_NAME='WasmEngineSharedModule' -s EXPORT_ES6=1 -s STANDALONE_WASM=1 \
+    -s IMPORTED_MEMORY=1 -s SHARED_MEMORY=1 -matomics -mbulk-memory ... -o engine_shared_probe_relaxed.js
+
+error: library_pthread_stub.js:11: #error "STANDALONE_WASM does not support shared memories yet"
+
+warning: undefined symbol: main/__main_argc_argv (referenced by top-level compiled C/C++ code)
+warning: To build in STANDALONE_WASM mode without a main(), use emcc --no-entry
+```
+
+`STANDALONE_WASM=1` **and** `SHARED_MEMORY=1` is exactly what
+`wasm_engine_sdn_browser_shared` is, and Emscripten 3.1.24 refuses that pair
+from its own sources. Not a missing flag, not a missing tool — a refused
+combination. (The object file compiles clean: `-matomics -mbulk-memory
+-msimd128` produce a 12,196-byte object. Atomics are not the problem.)
+
+## 4. What this means, and what ships anyway
+
+**The lock stays in the JS mirror.** `obc-01`'s
+`isBundledWasmEngineKeyRuntimeAuthorized` (`packages/wasm-engine/index.mjs`)
+remains the shipped enforcement, with its hard `E79` refusal. `obc-04`'s engine
+slot takes the prebuilt engine blob, as it does today; the emception lane does
+not fill it.
+
+**Phase B ships.** A user's own C/C++ module compiles in the same worker, in
+the single-thread Emscripten profile, and is labelled development-grade:
+
+- fixture compiled and linked in **2.4–3.0 s**, producing a **597-byte** wasm;
+- instantiated and called **on the page**: `build_cutter_probe(0)` returns
+  `307385611`, `build_cutter_tag_length()` returns `31`;
+- stamped with `runtimeTargets: ["browser"]` in the `sds.manifest` `$PLG`
+  section, so `assertArtifactRuntimeTarget({leg: "wasmedge"})` throws
+  `RuntimeTargetError` — asserted against the real gate, and asserted again
+  against the UNSTAMPED artifact, which is admitted everywhere and proves the
+  stamp is the whole refusal;
+- refused by `assertSequentialArtifact(..., {target: "wasm32-emscripten"})`:
+  *"the sequential model is a concurrency exemption, NOT a toolchain
+  exemption."*
+
+This is the Janus boundary of 2026-08-14 holding: nothing a browser tab
+produces enters the isomorphic lane, and the refusal is mechanical.
+
+## 5. A second finding: the shipped `.pack.br` files are not the packs
+
+Not the question that was asked, but it blocks anyone who tries the obvious
+thing. `sdn-emception@1.0.0` ships both uncompressed and brotli packs, and its
+loader fetches the uncompressed ones — 143,151,779 B for the three it needs.
+Pointing the fetch at the `.pack.br` siblings (21,901,402 B) produces a
+compiler that cannot compile.
+
+| pack | `.pack` | `.pack.br` decompresses to | first entry |
+| --- | ---: | ---: | --- |
+| `wasm` | 69,661,854 | 69,661,854 | `wasm/binaryen-box.wasm` |
+| `cpython` | 9,129,156 | 9,129,487 | `usr/` |
+| `emscripten` | 64,360,769 | 31,286,982 | `./` — **not** `emscripten/` |
+
+The `.pack.br` files are a different build, not compressed copies:
+
+1. **The emscripten one is rooted at `.`**, so unpacking it where the prefixed
+   packs go scatters the emscripten tree across the filesystem root. Nothing
+   throws; the next thing to fail is `python: can't open file
+   '/emscripten/emcc.py': [Errno 44]`, stages later, with no hint of the cause.
+2. **It omits the prebuilt sysroot.** The real `emscripten.pack` carries 7,434
+   `emscripten/cache/sysroot/**` entries; the `.br` build carries none. Without
+   them the first link rebuilds libc (998 inputs), libc++, compiler_rt and the
+   rest inside the tab — **135 s, measured** — and then dies generating
+   `struct_info.json`, because that step compiles a probe and runs it under
+   emception's quicknode: `Error: not compiled for this environment`.
+
+Proven not to be an artifact of the change: with the loader **unpatched** on
+the 143 MB packs, the same fixture compiles in **3.9 s**
+(`node vendor.mjs --uncompressed`, kept as the A/B control).
+
+**What the lane does instead.** It compresses the *working* packs itself at
+vendor time (brotli q11, lgwin 24) and serves those. Measured:
+
+| | bytes |
+| --- | ---: |
+| Packs, upstream uncompressed lane | 143,151,779 |
+| Packs, this lane | **25,851,077** |
+| Cold page load + first compile, total served | **27,431,314** |
+| Second page load + second compile, total served | **26,919** (0 pack bytes) |
+| External-origin requests | **0** |
+
+A 5.2× reduction on the wire, and the second compile costs nothing because the
+service worker holds the packs. The task's ≤ 25 MB target is missed by 1.2 MB,
+and the reason is item 2 above: the prebuilt sysroot is what makes the
+difference between a 3 s compile and a 135 s failure, and it is 8.4 MB
+compressed. Trading it away to hit the number would be trading the working
+compiler for a byte count.
+
+### Escalation to `sdn-emception`
+
+Two changes, both upstream, both retiring code this lane carries:
+
+1. **Publish `.pack.br` files that are the `.pack` files compressed** — same
+   roots, same contents, including `emscripten/cache/sysroot/**`. Today's
+   `emscripten.pack.br` cannot build anything.
+2. **Take a `packs: "br"` constructor option**, so `#fetchAndUnpack` can be
+   pointed at them without a vendor-time overlay.
+
+Until then the overlay lives in
+`OrbPro/packages/orbpro-integration/build-cutter/emception/vendor.mjs`: two
+exact string rewrites, each required to match **exactly once**, so an
+`sdn-emception` refresh fails the build loudly instead of silently reverting
+the stack to a 143 MB download.
+
+## 6. Reproducing
+
+```sh
+cd OrbPro/packages/orbpro-integration/build-cutter/emception
+node vendor.mjs                 # copy the compiler same-origin, compress the packs
+node spike/run.mjs              # one headless run -> results/emception-lane.json
+node --test test/emception-lane.test.mjs
+node vendor.mjs --uncompressed  # the A/B control: unpatched loader, 143 MB packs
+```
+
+`node server.mjs` serves the lane at `http://127.0.0.1:8137/` for hand
+inspection. It is a dev-server page; it is not published.