npm - space-data-module-sdk - Versions diffs - 0.8.14 → 0.8.16 - Mend

space-data-module-sdk 0.8.14 → 0.8.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (125) hide show

package/bin/space-data-module.js +91 -0
package/docs/_shell/consumer-assets.html +5 -0
package/docs/browser-wasmedge-isomorphic.html +261 -0
package/docs/byo-wasm-quickstart.html +226 -0
package/docs/byo-wasm-quickstart.md +204 -0
package/docs/conformance.html +156 -0
package/docs/conformance.md +92 -0
package/docs/emception-shared-memory-verdict.md +209 -0
package/docs/events-abi.html +313 -0
package/docs/events-abi.md +530 -0
package/docs/families/analytics.html +178 -0
package/docs/families/analytics.md +104 -0
package/docs/families/attitude.html +157 -0
package/docs/families/attitude.md +36 -0
package/docs/families/behavior.html +157 -0
package/docs/families/behavior.md +36 -0
package/docs/families/breakup.html +157 -0
package/docs/families/breakup.md +36 -0
package/docs/families/conjunction.html +186 -0
package/docs/families/conjunction.md +121 -0
package/docs/families/data-source.html +318 -0
package/docs/families/effects.html +157 -0
package/docs/families/effects.md +36 -0
package/docs/families/environment.html +170 -0
package/docs/families/environment.md +73 -0
package/docs/families/estimation.html +190 -0
package/docs/families/estimation.md +128 -0
package/docs/families/gnc.html +157 -0
package/docs/families/gnc.md +36 -0
package/docs/families/maneuver.html +209 -0
package/docs/families/maneuver.md +206 -0
package/docs/families/obstruction.html +191 -0
package/docs/families/obstruction.md +96 -0
package/docs/families/propagator.html +333 -0
package/docs/families/propulsion.html +157 -0
package/docs/families/propulsion.md +36 -0
package/docs/families/reentry.html +157 -0
package/docs/families/reentry.md +36 -0
package/docs/families/rf.html +193 -0
package/docs/families/rf.md +136 -0
package/docs/families/scheduler.html +157 -0
package/docs/families/scheduler.md +36 -0
package/docs/families/sensor.html +157 -0
package/docs/families/sensor.md +36 -0
package/docs/families/signature.html +157 -0
package/docs/families/signature.md +36 -0
package/docs/flatsql-host-contract.html +176 -0
package/docs/flatsql-streaming-standard.html +375 -0
package/docs/gpu-module-abi.html +233 -0
package/docs/harness-family-matrix.md +135 -0
package/docs/index.html +216 -85
package/docs/isomorphic-pthreads.html +228 -0
package/docs/isomorphic-pthreads.md +84 -0
package/docs/isomorphic-sdn-runtime-plan.html +274 -0
package/docs/language-runtime-matrix.html +182 -0
package/docs/llms.txt +86 -0
package/docs/module-bundle-runtime-plan.html +146 -0
package/docs/module-publication-standard.html +503 -0
package/docs/node-red-default-node-parity.html +201 -0
package/docs/propagator-abi.md +73 -21
package/docs/protect-and-sign.html +181 -0
package/docs/protect-and-sign.md +120 -0
package/docs/protocol-installation.html +296 -0
package/docs/publication-submission.html +158 -0
package/docs/publication-submission.md +78 -0
package/docs/secrets-capability.html +206 -0
package/docs/styles.css +860 -167
package/docs/testing-harness.html +408 -0
package/docs/tri-runtime-parity-gate.html +182 -0
package/docs/tri-runtime-parity.html +203 -0
package/include/orbpro/orbpro_event_runner.h +951 -0
package/include/orbpro/orbpro_events_abi.h +565 -0
package/include/orbpro/orbpro_propagator_abi.h +17 -0
package/package.json +15 -5
package/schemas/orbpro/Events.fbs +501 -0
package/schemas/orbpro/Propagator.fbs +72 -9
package/schemas/orbpro/reference-frame-crosswalk.json +108 -0
package/schemas/orbpro/reference-frame.lock.json +98 -0
package/src/browser.js +13 -0
package/src/conformance/abiDriver.js +225 -0
package/src/conformance/index.js +151 -0
package/src/conformance/propagatorSuite.js +526 -0
package/src/conformance/selfTest.js +275 -0
package/src/conformance/selfTestCorpus.js +68 -0
package/src/conformance/twoBodyReference.js +132 -0
package/src/generated/orbpro/events-abi.js +206 -0
package/src/generated/orbpro/events-abi.ts +319 -0
package/src/generated/orbpro/propagator/reference-frame.js +17 -0
package/src/generated/orbpro/propagator/reference-frame.ts +91 -1
package/src/generated/orbpro/propagator-abi.js +17 -0
package/src/generated/orbpro/propagator-abi.ts +17 -0
package/src/generated/spacedatastandards/plg/CCT.d.ts +94 -0
package/src/generated/spacedatastandards/plg/CCT.d.ts.map +1 -0
package/src/generated/spacedatastandards/plg/CCT.js +208 -0
package/src/generated/spacedatastandards/plg/CCT.ts +281 -0
package/src/generated/spacedatastandards/plg/CCTCategory.d.ts +98 -0
package/src/generated/spacedatastandards/plg/CCTCategory.d.ts.map +1 -0
package/src/generated/spacedatastandards/plg/CCTCategory.js +177 -0
package/src/generated/spacedatastandards/plg/CCTCategory.ts +269 -0
package/src/generated/spacedatastandards/plg/CCTCategoryRollup.d.ts +54 -0
package/src/generated/spacedatastandards/plg/CCTCategoryRollup.d.ts.map +1 -0
package/src/generated/spacedatastandards/plg/CCTCategoryRollup.js +106 -0
package/src/generated/spacedatastandards/plg/CCTCategoryRollup.ts +144 -0
package/src/generated/spacedatastandards/plg/PLG.d.ts +46 -2
package/src/generated/spacedatastandards/plg/PLG.d.ts.map +1 -1
package/src/generated/spacedatastandards/plg/PLG.js +78 -5
package/src/generated/spacedatastandards/plg/PLG.ts +90 -5
package/src/generated/spacedatastandards/plg/capabilityClass.d.ts +181 -0
package/src/generated/spacedatastandards/plg/capabilityClass.d.ts.map +1 -0
package/src/generated/spacedatastandards/plg/capabilityClass.js +183 -0
package/src/generated/spacedatastandards/plg/capabilityClass.ts +208 -0
package/src/generated/spacedatastandards/plg/main.d.ts +4 -0
package/src/generated/spacedatastandards/plg/main.d.ts.map +1 -1
package/src/generated/spacedatastandards/plg/main.js +4 -0
package/src/generated/spacedatastandards/plg/main.ts +4 -0
package/src/generated/spacedatastandards/plg/pluginCategory.d.ts +40 -2
package/src/generated/spacedatastandards/plg/pluginCategory.d.ts.map +1 -1
package/src/generated/spacedatastandards/plg/pluginCategory.js +40 -2
package/src/generated/spacedatastandards/plg/pluginCategory.ts +40 -2
package/src/host/browserModuleHarness.js +8 -0
package/src/host/wasiThreadHost.js +189 -14
package/src/index.d.ts +18 -1
package/src/testing/isomorphicHarness.js +233 -0
package/src/transport/index.js +16 -0
package/src/transport/records.js +1015 -3

package/docs/flatsql-host-contract.html ADDED Viewed

@@ -0,0 +1,176 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="The current floor is ^2.0.0. The 1.x history below is what made the" />
+    <title>FlatSQL host contract — 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" aria-current="page"><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>FlatSQL host contract</h1>
+<p>The current floor is <strong><code>^2.0.0</code></strong>. The 1.x history below is what made the contract, and it still describes the contract 2.0.0 ships — see <a href="#the-200-floor-is-a-licence-change-not-a-port">The 2.0.0 floor is a licence change, not a port</a> at the end for why the major bump costs nothing here.</p>
+<h2 id="the-defect-the-bump-repairs"><a class="anchor" href="#the-defect-the-bump-repairs" aria-hidden="true">#</a>The defect the bump repairs</h2>
+<p>The SDK floored <code>flatsql</code> at <code>^0.4.2</code>. <code>^0.4.2</code> admits nothing in 1.x, so the floor sat a full major behind, and — the part that matters — the 0.4.x <code>wasm/flatsql-wasi.wasm</code> is an <strong>emscripten-glue artifact</strong>. Measured on the shipped bytes:</p>
+<div class="table-wrap"><table><thead><tr><th>version</th><th>imports</th><th>shape</th></tr></thead><tbody><tr><td>0.4.2</td><td><strong>69</strong></td><td>59 on <code>env</code>: ~40 <code>invoke_*</code> EH trampolines, <code>__cxa_*</code>, <code>__resumeException</code>, <code>llvm_eh_typeid_for</code>, 10 <code>__syscall_*</code>, <code>emscripten_notify_memory_growth</code></td></tr><tr><td>1.4.4</td><td><strong>13</strong></td><td>7 <code>flatsql_io_*</code> + 6 WASI preview1</td></tr></tbody></table></div>
+<p>Under the pinned WasmEdge 0.16.4:</p>
+<div class="codeblock"><pre><code>0.4.2 -&gt; instantiation failed: unknown import … &quot;env&quot; &quot;invoke_vi&quot;
+1.4.4 -&gt; links; blocked only on the DECLARED capability env.flatsql_io_open</code></pre></div>
+<p>Modules are EH-free and <code>emcc</code>-shaped artifacts are a browser-only trap, so <code>^0.4.2</code> pinned a <strong>non-isomorphic engine</strong>. That is an auto-reject under the module contract, and the tri-runtime parity gate now says so out loud: <code>flatsql-standalone :: FORBIDDEN import class [emscripten-eh, emscripten-runtime, emscripten-syscall] — 59 import(s)</code>.</p>
+<h2 id="what-the-bump-costs"><a class="anchor" href="#what-the-bump-costs" aria-hidden="true">#</a>What the bump costs</h2>
+<p>Nothing at the JS call sites. The SDK uses <code>FlatSQLDatabase.fromSchema</code>, <code>.query</code>, <code>.insert</code>, and <code>DirectAccessor.registerAccessor</code>/<code>.registerBuilder</code> (<code>src/runtime-host/flatsqlRuntimeStore.js</code>); all are present in 1.4.4, and the C ABI went 57 → 96 exports with <strong>zero removed</strong>.</p>
+<p>One real behavioral change surfaced, and it is a <em>fix</em>, not a break:</p>
+<blockquote><p><strong>0.4.2 silently ignored <code>ORDER BY</code>.</strong> <code>listRows()</code> is <code>SELECT … ORDER BY schemaFileId, rowId</code>, and on 0.4.2 it returned INSERTION order. 1.4.4 honours the clause. <code>test/runtime-host-stream-ingest.test.js</code> had encoded the broken behaviour (OMM-then-ENTM); it now asserts the sorted contract and checks payloads by handle instead of by position, so it cannot re-encode an engine bug as SDK semantics.</p></blockquote>
+<h2 id="the-host-contract-14x-makes-unconditional"><a class="anchor" href="#the-host-contract-14x-makes-unconditional" aria-hidden="true">#</a>The host contract 1.4.x makes unconditional</h2>
+<p>1.4.x imports these seven functions on module <code>env</code> <strong>unconditionally</strong>. A host that does not supply them cannot instantiate the artifact, so host wiring and the artifact bump land together or not at all:</p>
+<div class="codeblock"><pre><code>i32 flatsql_io_open(ptr path, i32 pathLen, i32 flags)
+i32 flatsql_io_read(i32 h, ptr dst, i32 len, f64 offset)
+i32 flatsql_io_write(i32 h, ptr src, i32 len, f64 offset)
+i32 flatsql_io_truncate(i32 h, f64 size)
+i32 flatsql_io_sync(i32 h)
+f64 flatsql_io_size(i32 h)
+i32 flatsql_io_close(i32 h)</code></pre></div>
+<p><strong>Offsets are <code>f64</code>, never <code>i64</code>.</strong> emscripten legalizes i64 across the JS boundary for the browser target and not for <code>STANDALONE_WASM</code>; using i64 would give one import two different signatures in the two lanes, which is the exact shape of a cross-runtime divergence.</p>
+<p>The SDK publishes this contract so consumers wire it identically in both lanes rather than each inventing it:</p>
+<div class="codeblock"><div class="codeblock-head">js</div><pre><code>import {
+  FLATSQL_IO_IMPORTS,       // the seven &quot;env.flatsql_io_*&quot; keys
+  FLATSQL_IO_SIGNATURES,    // params/result valtypes, f64 offsets
+  HOST_SURFACES,            // HOST_SURFACES[&quot;flatsql-engine&quot;]
+} from &quot;space-data-module-sdk/testing&quot;;</code></pre></div>
+<h2 id="what-the-sdk-does-not-do"><a class="anchor" href="#what-the-sdk-does-not-do" aria-hidden="true">#</a>What the SDK does NOT do</h2>
+<p>module-sdk does not link the VFS into its own artifacts, and that is by design: an SDK module exports <strong>zero</strong> <code>flatsql_io_*</code> imports. A module keeps the generic hook set, which rides inside the one sanctioned <code>space_data_module_host</code> bridge; a private import would be a NEW HOST CAPABILITY, and that is an owner decision, never a dependency bump. The SDK consumes flatsql through its <strong>JS API</strong> only (<code>src/runtime-host/flatsqlRuntimeStore.js</code>); flow artifacts receive the live engine from the caller as <code>engineLink</code> (<code>src/flow/flowRuntimeHost.js</code>), so the host that instantiates the engine is the host that supplies the seven imports.</p>
+<h2 id="evidence"><a class="anchor" href="#evidence" aria-hidden="true">#</a>Evidence</h2>
+<p><code>space-data-module parity-gate</code> — the <code>flatsql-standalone</code> artifact resolves through this repo's own dependency, so the gate always classifies the engine a consumer would actually load. At 1.4.4 it reports <code>in-surface (WASI + declared capabilities: 7)</code>, <code>satisfied</code> in the real-browser lane and <code>runner-cannot-supply-declared-capability</code> under the bare WasmEdge CLI, naming <code>env.flatsql_io_open</code> as the single blocker.</p>
+<h2 id="the-200-floor-is-a-licence-change-not-a-port"><a class="anchor" href="#the-200-floor-is-a-licence-change-not-a-port" aria-hidden="true">#</a>The 2.0.0 floor is a licence change, not a port</h2>
+<p><code>flatsql</code> 2.0.0 is 1.4.5's code republished under the <a href="https://polyformproject.org/licenses/noncommercial/1.0.0/">PolyForm Noncommercial License 1.0.0</a>. The major is semver signalling the licence, not an API break. Measured on the two published tarballs, every file is byte-identical except three:</p>
+<div class="codeblock"><pre><code>LICENSE       Apache-2.0 -&gt; PolyForm Noncommercial 1.0.0
+package.json  &quot;version&quot; and &quot;license&quot; only
+README.md     licence + contact section</code></pre></div>
+<p>The host contract above therefore carries over unchanged. On <code>wasm/flatsql-wasi.wasm</code>, 2.0.0 imports the same <strong>13</strong> — the seven <code>flatsql_io_*</code> on <code>env</code> plus six WASI preview1 — and exports the same <strong>102</strong> as 1.4.4, so the parity gate classifies the 2.0.0 engine exactly as it classified 1.4.4.</p>
+<p>Two consequences for anyone reading this floor:</p>
+<ul>
+<li><strong>Every pre-2.0.0 <code>flatsql</code> is withdrawn from npm.</strong> A pin below <code>^2.0.0</code> resolves to nothing. There is no supported lower floor.</li>
+<li><strong>Commercial use of the engine needs a licence</strong> from DigitalArsenal.io, Inc. (<a href="mailto:tj@digitalarsenal.io">tj@digitalarsenal.io</a>). The SDK stays MIT and consumes flatsql through its JS API only, but installing the SDK installs the engine, so the obligation reaches the SDK's consumers.</li>
+</ul>
+        <p class="doc-footer">
+          Source of truth for this page:
+          <code>docs/flatsql-host-contract.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="#the-defect-the-bump-repairs">The defect the bump repairs</a></li>
+<li><a class="depth-2" href="#what-the-bump-costs">What the bump costs</a></li>
+<li><a class="depth-2" href="#the-host-contract-14x-makes-unconditional">The host contract 1.4.x makes unconditional</a></li>
+<li><a class="depth-2" href="#what-the-sdk-does-not-do">What the SDK does NOT do</a></li>
+<li><a class="depth-2" href="#evidence">Evidence</a></li>
+<li><a class="depth-2" href="#the-200-floor-is-a-licence-change-not-a-port">The 2.0.0 floor is a licence change, not a port</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/flatsql-streaming-standard.html ADDED Viewed

@@ -0,0 +1,375 @@
+<!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 defines the recommended standard for getting streamed" />
+    <title>FlatSQL streaming standard — 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" aria-current="page"><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>FlatSQL streaming standard</h1>
+<p>This document defines the recommended standard for getting streamed FlatBuffer payloads into FlatSQL-backed storage while keeping the same model portable across browser, server, OrbPro, and WasmEdge.</p>
+<h2 id="short-version"><a class="anchor" href="#short-version" aria-hidden="true">#</a>Short Version</h2>
+<p>Use three layers, not one:</p>
+<ol>
+<li>Transport stream: little-endian <code>u32</code> size prefix + one FlatBuffer payload per frame</li>
+<li>Module invoke ABI: SDS <code>$PIV</code> request/response envelopes with <code>TAB</code> frame descriptors</li>
+<li>Durable storage identity: host-owned append-only row handles and host-owned runtime regions</li>
+</ol>
+<p>Do not treat a module-owned mutable FlatSQL database as the canonical ABI. That can exist as an adapter or example, but it is not the durable cross-host contract.</p>
+<h2 id="canonical-transport"><a class="anchor" href="#canonical-transport" aria-hidden="true">#</a>Canonical Transport</h2>
+<p>The canonical transport for streamed FlatBuffers is:</p>
+<ul>
+<li><code>4-byte little-endian payload length</code></li>
+<li>followed by one FlatBuffer payload</li>
+<li>repeated until end of stream</li>
+<li>payload bytes stay binary end-to-end; the canonical ingest path does not transcode frames through JSON</li>
+</ul>
+<p>Each payload must carry a readable FlatBuffer file identifier. The runtime uses that identifier to derive the durable <code>schemaFileId</code>.</p>
+<p>This transport is intentionally separate from module invocation. It is the right shape for:</p>
+<ul>
+<li>WebSocket feeds</li>
+<li>HTTP chunk/file ingestion</li>
+<li>local file replay</li>
+<li>browser worker or server-side stream processing</li>
+</ul>
+<p>It is not the same thing as a SDS <code>$PIV</code> invoke envelope.</p>
+<h2 id="canonical-durable-storage"><a class="anchor" href="#canonical-durable-storage" aria-hidden="true">#</a>Canonical Durable Storage</h2>
+<p>The durable storage model is host-owned.</p>
+<p>Standards records are addressed by:</p>
+<ul>
+<li><code>($SCHEMA_FILE_ID, rowId)</code></li>
+</ul>
+<p>Rules:</p>
+<ul>
+<li><code>rowId</code> is append-only</li>
+<li><code>rowId</code> is never reused</li>
+<li>logical updates create new rows</li>
+<li>&quot;latest&quot; or &quot;upsert&quot; views are host-side projections or indexes</li>
+<li>row payloads remain raw binary or native in-memory values; the canonical runtime-host row path does not stringify payloads</li>
+</ul>
+<p>High-performance derived runtime state is addressed by:</p>
+<ul>
+<li><code>(regionId, recordIndex)</code></li>
+</ul>
+<p>Rules:</p>
+<ul>
+<li>the host allocates or registers regions</li>
+<li>regions are fixed-layout aligned-binary buffers</li>
+<li>regions are not indexed in FlatSQL</li>
+<li>raw pointers remain internal execution details only</li>
+</ul>
+<p>The stable storage ABI lives in <code>schemas/HostStorageAbi.fbs</code>.</p>
+<h2 id="canonical-module-abi"><a class="anchor" href="#canonical-module-abi" aria-hidden="true">#</a>Canonical Module ABI</h2>
+<p>When streamed payloads must cross into a module, use the invoke ABI:</p>
+<ul>
+<li>SDS <code>$PIV</code> <code>REQUEST</code></li>
+<li>SDS <code>$PIV</code> <code>RESPONSE</code></li>
+<li>SDS <code>TAB</code> frame descriptors</li>
+</ul>
+<p>Each input frame should preserve:</p>
+<ul>
+<li><code>portId</code></li>
+<li><code>typeRef</code></li>
+<li><code>streamId</code></li>
+<li><code>sequence</code></li>
+<li><code>endOfStream</code></li>
+<li>alignment metadata when required</li>
+</ul>
+<p>This is the correct way to tell a module &quot;these frames belong to the same logical stream.&quot;</p>
+<p>It is not a byte-streaming transport. The current invoke ABI is still buffer-oriented:</p>
+<ul>
+<li>the full request is materialized before <code>plugin_invoke_stream(...)</code></li>
+<li>the full response is materialized before it is returned</li>
+</ul>
+<p>So a single 1 GiB SDS <code>$PIV</code> invoke request is not the intended path.</p>
+<h2 id="flatsql-specific-rules"><a class="anchor" href="#flatsql-specific-rules" aria-hidden="true">#</a>FlatSQL-Specific Rules</h2>
+<p>If the goal is &quot;stream FlatBuffers into FlatSQL&quot;, standardize the host-side behavior first:</p>
+<ol>
+<li>split the outer size-prefixed transport stream into payload frames</li>
+<li>derive <code>schemaFileId</code> from the FlatBuffer file identifier</li>
+<li>append immutable host-owned rows</li>
+<li>maintain host-side logical indexes or latest-record projections as needed</li>
+<li>expose query and row-resolution APIs on top of that store</li>
+</ol>
+<p>That means the durable primitive is <code>append</code>, not <code>upsert</code>.</p>
+<p><code>upsert_records</code> is allowed as a higher-level adapter surface, but only if it is defined as:</p>
+<ul>
+<li>append new immutable row(s)</li>
+<li>update a logical index/view</li>
+<li>never rewrite an existing durable <code>rowId</code></li>
+</ul>
+<p>If a module or flow needs fast numeric state, keep that data in runtime regions, not in FlatSQL tables.</p>
+<h2 id="browser-and-wasmedge"><a class="anchor" href="#browser-and-wasmedge" aria-hidden="true">#</a>Browser and WasmEdge</h2>
+<p>The same transport/storage model should be used in both:</p>
+<ul>
+<li>browser: host-side stream ingest + host-owned rows/regions</li>
+<li>WasmEdge: host-side stream ingest + host-owned rows/regions</li>
+</ul>
+<p>Use module invocation for:</p>
+<ul>
+<li>compute batches</li>
+<li>typed transformation steps</li>
+<li>stateful direct-surface module sessions</li>
+</ul>
+<p>Use host-side stream ingest for:</p>
+<ul>
+<li>large continuous feeds</li>
+<li>catalog replay</li>
+<li>ingestion into host-owned FlatSQL-backed stores</li>
+<li>any workload that should not be forced through one contiguous invoke buffer</li>
+</ul>
+<p>The new helper for this outer transport path is <code>createFlatBufferStreamIngestor(...)</code>, exported from <code>space-data-module-sdk/runtime-host</code>.</p>
+<h2 id="streaming-into-a-module-owned-flatsql-engine"><a class="anchor" href="#streaming-into-a-module-owned-flatsql-engine" aria-hidden="true">#</a>Streaming Into A Module-Owned FlatSQL Engine</h2>
+<p>If the goal is not a host-owned durable store, but a stateful SDN module that imports <code>flatsql</code> internally and owns its own in-memory query state, use a persistent direct-surface module instance plus chunked binary invokes.</p>
+<p>Rules:</p>
+<ul>
+<li>do not change <code>flatsql</code> itself</li>
+<li>import <code>flatsql</code> inside the SDN module implementation</li>
+<li>keep the module instance resident across invokes</li>
+<li>feed it many small FlatBuffer frames, not one giant invoke envelope</li>
+<li>use command surface only for stateless one-shot work; use direct surface for resident FlatSQL state</li>
+</ul>
+<p>The SDK helper for this path is <code>createModuleFlatBufferStreamPump(...)</code>, exported from <code>space-data-module-sdk/testing</code> and the browser/root package surfaces.</p>
+<p>That helper:</p>
+<ul>
+<li>accepts the same outer size-prefixed FlatBuffer stream chunks</li>
+<li>decodes frames incrementally</li>
+<li>emits small SDS <code>$PIV</code> request batches into a live module instance</li>
+<li>preserves <code>streamId</code>, <code>sequence</code>, and final <code>endOfStream</code></li>
+<li>never routes payloads through JSON</li>
+</ul>
+<p>Example:</p>
+<div class="codeblock"><div class="codeblock-head">js</div><pre><code>import {
+  createBrowserModuleHarness,
+  createModuleFlatBufferStreamPump,
+} from &quot;space-data-module-sdk&quot;;
+const harness = await createBrowserModuleHarness({
+  wasmSource,
+  surface: &quot;direct&quot;,
+});
+const pump = createModuleFlatBufferStreamPump({
+  harness,
+  methodId: &quot;upsert_records&quot;,
+  portId: &quot;records&quot;,
+  maxFramesPerInvoke: 64,
+  typeResolver(_payload, context) {
+    return {
+      acceptsAnyFlatbuffer: true,
+      fileIdentifier: context.rawFileIdentifier,
+    };
+  },
+});
+await pump.pushBytes(chunkA);
+await pump.pushBytes(chunkB);
+await pump.finish();</code></pre></div>
+<p>This is the right shape for OrbPro-style browser ingest when:</p>
+<ul>
+<li>the raw FlatBuffer payloads are the source of truth</li>
+<li>the UI/runtime should not materialize JS record mirrors</li>
+<li>a resident module should own FlatSQL/query state directly</li>
+</ul>
+<p>It is still batch-oriented per invoke, but it removes the architectural anti-pattern of building one monolithic request envelope for a long-running stream.</p>
+<h2 id="example-import-path"><a class="anchor" href="#example-import-path" aria-hidden="true">#</a>Example Import Path</h2>
+<div class="codeblock"><div class="codeblock-head">js</div><pre><code>import {
+  createFlatBufferStreamIngestor,
+  createRuntimeHost,
+} from &quot;space-data-module-sdk/runtime-host&quot;;
+const host = createRuntimeHost();
+const ingestor = createFlatBufferStreamIngestor({
+  rows: host.rows,
+});
+ingestor.pushBytes(chunkA);
+ingestor.pushBytes(chunkB);
+ingestor.finish();
+const rows = host.rows.listRows(&quot;OMM&quot;);</code></pre></div>
+<h2 id="performance-guidance"><a class="anchor" href="#performance-guidance" aria-hidden="true">#</a>Performance Guidance</h2>
+<p>There are two distinct performance questions:</p>
+<ol>
+<li>Outer transport ingest throughput</li>
+<li>Module invoke throughput</li>
+</ol>
+<p>Do not mix them into one benchmark.</p>
+<h3 id="outer-transport-benchmark"><a class="anchor" href="#outer-transport-benchmark" aria-hidden="true">#</a>Outer Transport Benchmark</h3>
+<p>Use the runtime-host stream ingestor.</p>
+<p>Commands:</p>
+<div class="codeblock"><div class="codeblock-head">bash</div><pre><code>npm run test:stream-ingest
+npm run benchmark:stream-1gib</code></pre></div>
+<p>Optional tuning:</p>
+<ul>
+<li><code>SPACE_DATA_MODULE_SDK_STREAM_BENCH_BYTES</code></li>
+<li><code>SPACE_DATA_MODULE_SDK_STREAM_BENCH_PAYLOAD_BYTES</code></li>
+<li><code>SPACE_DATA_MODULE_SDK_STREAM_BENCH_CHUNK_BYTES</code></li>
+</ul>
+<p>The 1 GiB benchmark is env-gated on purpose. It is a local stress path, not a default suite member.</p>
+<h3 id="module-invoke-benchmark"><a class="anchor" href="#module-invoke-benchmark" aria-hidden="true">#</a>Module Invoke Benchmark</h3>
+<p>Benchmark direct invoke separately with many smaller requests and a tiny response. Treat the current invoke ABI as batch-oriented, not as a raw stream transport.</p>
+<p>Recommended total sizes:</p>
+<ul>
+<li>CI / regular local: <code>1 MiB</code>, <code>8 MiB</code>, <code>32 MiB</code>, <code>128 MiB</code></li>
+<li>local stress: <code>256 MiB</code> or higher in chunked totals</li>
+</ul>
+<p>Avoid a single 1 GiB request envelope on the current codepath.</p>
+<p>For the resident module-ingest shape, use:</p>
+<div class="codeblock"><div class="codeblock-head">bash</div><pre><code>npm run test:module-stream
+npm run benchmark:module-stream-1gib</code></pre></div>
+<p>That benchmark exercises the chunked module stream-pump path, not a single huge invoke buffer.</p>
+<h2 id="current-non-canonical-example"><a class="anchor" href="#current-non-canonical-example" aria-hidden="true">#</a>Current Non-Canonical Example</h2>
+<p><code>examples/flatsql-store-local</code> is still useful as an adapter example, but it is not the canonical durable identity model. It exposes a module-owned mutable logical database. The canonical model for cross-host durability is host-owned rows plus host-owned runtime regions.</p>
+<h2 id="body-reference-delivery-deliverref"><a class="anchor" href="#body-reference-delivery-deliverref" aria-hidden="true">#</a>Body-Reference Delivery (<code>&quot;deliver&quot;:&quot;ref&quot;</code>)</h2>
+<p>Loop C.5c adds an OPTIONAL near-zero-copy egress mode for capability hostcalls whose result is an aligned stream that the module passes through VERBATIM to an HTTP response body (the retrieval flow's flatbuffer branch). The election is always the GUEST's; hosts never invent it.</p>
+<ol>
+<li>The module adds <code>&quot;deliver&quot;:&quot;ref&quot;</code> to the hostcall payload (<code>storage.flatsql_query_stream</code> / <code>storage.flatsql_epoch_stream</code>).</li>
+<li>A ref-capable host keeps the materialized bytes in ITS memory, registers them on the calling instance's hostcall-bridge body-ref registry, and answers with NO binary segment:</li>
+</ol>
+<div class="codeblock"><div class="codeblock-head">json</div><pre><code>   {&quot;ok&quot;:true,&quot;result&quot;:{&quot;rows&quot;:N,&quot;columns&quot;:M,
+     &quot;ref&quot;:{&quot;token&quot;:T,&quot;size&quot;:S,&quot;frames&quot;:F,&quot;fnv1a64&quot;:&quot;&lt;16 hex&gt;&quot;}}}</code></pre></div>
+<ul>
+<li><code>token</code> — opaque, single-use, scoped to this module instance's bridge and the current exchange.</li>
+<li><code>size</code> — byte length of the referenced stream.</li>
+<li><code>frames</code> — size-prefixed frame count, skipping zero-length prefixes (the <code>x-sdn-record-count</code> rule); omitted when the framing is malformed.</li>
+<li><code>fnv1a64</code> — word-folded FNV-1a 64 content hash (<code>fnv1a64Hex</code> in <code>space-data-module-sdk/http</code> is the reference implementation; it is bit-identical to foundation/decision-gate's in-wasm hasher, so reference-mode entity tags equal hashed-stream entity tags).</li>
+</ul>
+<p>A host that does not understand <code>deliver</code> simply returns the byte segment as always; modules MUST fall back to verbatim byte passthrough.</p>
+<ol>
+<li>The module forwards the reference in-band as a small JSON descriptor frame <code>{&quot;$sdnbodyref&quot;:1,&quot;token&quot;:T,&quot;size&quot;:S,&quot;frames&quot;:F,&quot;fnv1a64&quot;:&quot;…&quot;}</code> (an aligned stream can never collide: it starts with a <code>u32le</code> size prefix, not <code>{</code>).</li>
+<li><code>foundation/http-respond</code> recognizes the descriptor on its body port and emits <code>$HTR</code> with <code>BODY_REF_TOKEN</code>/<code>BODY_REF_SIZE</code> set and NO inline body (schema <code>HttpResponseAbi.fbs</code>).</li>
+<li>The host egress substitutes the byte buffer registered under the token (Go: <code>flowrt.htrPipe</code> + <code>modulert.HostBridge.TakeBodyRef</code>; JS: <code>createBodyRefRegistry</code> from <code>space-data-module-sdk/http</code>). Tokens are single-use; hosts drop unconsumed references at end-of-exchange (304 and error paths never consume theirs).</li>
+</ol>
+<p>The stream bytes therefore never enter the flow's linear memory: the only byte movement left on a warm request is the host's socket write.</p>
+        <p class="doc-footer">
+          Source of truth for this page:
+          <code>docs/flatsql-streaming-standard.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="#short-version">Short Version</a></li>
+<li><a class="depth-2" href="#canonical-transport">Canonical Transport</a></li>
+<li><a class="depth-2" href="#canonical-durable-storage">Canonical Durable Storage</a></li>
+<li><a class="depth-2" href="#canonical-module-abi">Canonical Module ABI</a></li>
+<li><a class="depth-2" href="#flatsql-specific-rules">FlatSQL-Specific Rules</a></li>
+<li><a class="depth-2" href="#browser-and-wasmedge">Browser and WasmEdge</a></li>
+<li><a class="depth-2" href="#streaming-into-a-module-owned-flatsql-engine">Streaming Into A Module-Owned FlatSQL Engine</a></li>
+<li><a class="depth-2" href="#example-import-path">Example Import Path</a></li>
+<li><a class="depth-2" href="#performance-guidance">Performance Guidance</a></li>
+<li><a class="depth-3" href="#outer-transport-benchmark">Outer Transport Benchmark</a></li>
+<li><a class="depth-3" href="#module-invoke-benchmark">Module Invoke Benchmark</a></li>
+<li><a class="depth-2" href="#current-non-canonical-example">Current Non-Canonical Example</a></li>
+<li><a class="depth-2" href="#body-reference-delivery-deliverref">Body-Reference Delivery (<code>&quot;deliver&quot;:&quot;ref&quot;</code>)</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>