space-data-module-sdk 0.5.19 → 0.5.22

package/README.md

@@ -52,6 +52,10 @@ The minimal host surface lives under `src/runtime-host/` and covers three
 responsibilities:
 
 - `createFlatSqlRuntimeStore()` for append-only row handles and row resolution
+- `createFlatBufferStreamIngestor()` for little-endian size-prefixed FlatBuffer
+  transport ingest into host-owned row storage without JSON transcoding
+- `createModuleFlatBufferStreamPump()` for feeding those same FlatBuffer stream
+  chunks into a resident stateful module instance without JSON envelopes
 - `createRuntimeRegionStore()` for host-allocated aligned-binary regions and
   externally backed record-view descriptors
 - `createModuleRegistry()` for dynamic install/load/unload/invoke
@@ -60,6 +64,9 @@ responsibilities:
 OrbPro layers entity/view helpers on top of that host instead of inventing a
 separate durable identity model.
 
+The canonical FlatBuffer-to-FlatSQL streaming contract is documented in
+[`docs/flatsql-streaming-standard.md`](./docs/flatsql-streaming-standard.md).
+
 ## Module Artifact Model
 
 A compliant module built with this SDK is always a valid `.wasm` artifact with:
@@ -236,6 +243,12 @@ The checked-in same-artifact demo lives in
 - [`wasmedge-demo.mjs`](./examples/isomorphic-loader/wasmedge-demo.mjs) loads
   that same artifact in WasmEdge
 
+Large streamed FlatBuffer ingest should use either the runtime-host transport
+path or the resident-module stream pump, not one giant invoke envelope. See
+[`docs/flatsql-streaming-standard.md`](./docs/flatsql-streaming-standard.md)
+for the recommended browser/WasmEdge/FlatSQL split and the canonical
+direct-binary ingest contract.
+
 ## Testing
 
 This repo now exposes a manifest-driven harness generator from
@@ -260,10 +273,23 @@ This repo now exposes a manifest-driven harness generator from
 - `npm run test:host-surfaces`
   - authoritative Node-host coverage for HTTP, TCP, UDP, TLS, WebSocket, MQTT,
     process execution, timers, filesystem, and the sync `sdn_host` ABI
+- `npm run test:stream-ingest`
+  - correctness coverage for chunked size-prefixed FlatBuffer ingest into the
+    runtime-host row store
+- `npm run test:module-stream`
+  - correctness coverage for chunked FlatBuffer streaming into a resident
+    direct-surface module instance
+- `npm run benchmark:stream-1gib`
+  - env-gated local stress benchmark for 1 GiB total FlatBuffer transport ingest
+- `npm run benchmark:module-stream-1gib`
+  - env-gated local stress benchmark for 1 GiB total chunked module stream-pump
+    ingest
 
 The detailed edge cases and the current WASI-vs-host portability boundary are
 documented in
-[`docs/testing-harness.md`](./docs/testing-harness.md).
+[`docs/testing-harness.md`](./docs/testing-harness.md). The canonical
+FlatBuffer-to-FlatSQL ingest contract is documented in
+[`docs/flatsql-streaming-standard.md`](./docs/flatsql-streaming-standard.md).
 
 ## Install
 
@@ -437,6 +463,22 @@ For npm packages, the simplest form is:
 }
 ```
 
+For module repos themselves, the canonical compiled artifact should live at:
+
+```text
+dist/isomorphic/module.wasm
+```
+
+If the repo also ships a direct browser adapter, publish it under:
+
+```text
+dist/browser/module.js
+dist/browser/module.wasm
+```
+
+That keeps the shared browser/WasmEdge artifact path stable across repos while
+leaving the browser-specific adapter optional.
+
 When publication metadata is published in the same file, it belongs in an
 appended SDS `REC` trailer. Loaders scan from the end of the protected blob,
 resolve `PNM` / `ENC`, strip or decrypt as needed, and only then instantiate
@@ -492,16 +534,16 @@ Manifests can also declare coarse runtime targets for planning and compliance:
 
 ```bash
 # Validate a manifest + wasm pair
-npx space-data-module check --manifest ./manifest.json --wasm ./dist/module.wasm
+npx space-data-module check --manifest ./manifest.json --wasm ./dist/isomorphic/module.wasm
 
 # Compile C/C++ source and embed the manifest
-npx space-data-module compile --manifest ./manifest.json --source ./src/module.c --out ./dist/module.wasm
+npx space-data-module compile --manifest ./manifest.json --source ./src/module.c --out ./dist/isomorphic/module.wasm
 
 # Sign and encrypt a deployment payload
-npx space-data-module protect --manifest ./manifest.json --wasm ./dist/module.wasm --json
+npx space-data-module protect --manifest ./manifest.json --wasm ./dist/isomorphic/module.wasm --json
 
 # Emit a single-file bundled wasm
-npx space-data-module protect --manifest ./manifest.json --wasm ./dist/module.wasm --single-file-bundle --out ./dist/module.bundle.wasm
+npx space-data-module protect --manifest ./manifest.json --wasm ./dist/isomorphic/module.wasm --single-file-bundle --out ./dist/module.bundle.wasm
 ```
 
 ## Module Lab
@@ -534,8 +576,11 @@ npm run check:compliance
 ```
 
 Node.js `>=20` is required. The compiler uses `sdn-emception` and `flatc-wasm`
-by default for the embedded toolchain path. WasmEdge pthread builds require a
-system Emscripten toolchain on `PATH`.
+by default for the embedded toolchain path. For multi-repo module builds, use a
+repo-local `deps/emsdk` checkout by default instead of Homebrew or any other
+machine-global Emscripten install. Treat `PATH` Emscripten as an explicit escape
+hatch, not the default. WasmEdge pthread builds still require a system
+Emscripten toolchain on `PATH`.
 
 If another repo needs the same compiler runtime, the package also exposes a
 shared emception session at `space-data-module-sdk/compiler/emception` with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.5.19",
+  "version": "0.5.22",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
   "types": "./src/index.d.ts",
@@ -53,6 +53,10 @@
     "test": "node --test",
     "test:host-surfaces": "node --test test/node-host.test.js test/host-abi.test.js",
     "test:runtime-matrix": "SPACE_DATA_MODULE_SDK_ENABLE_RUNTIME_MATRIX=1 node --test test/runtime-matrix.test.js",
+    "test:stream-ingest": "node --test test/runtime-host-stream-ingest.test.js",
+    "test:module-stream": "node --test test/module-flatbuffer-stream-pump.test.js",
+    "benchmark:stream-1gib": "SPACE_DATA_MODULE_SDK_ENABLE_1GB_STREAM_TEST=1 node --test test/runtime-host-stream-ingest.test.js",
+    "benchmark:module-stream-1gib": "SPACE_DATA_MODULE_SDK_ENABLE_1GB_MODULE_STREAM_TEST=1 node --test test/module-flatbuffer-stream-pump.test.js",
     "start:lab": "node ./lab/server.js",
     "check:compliance": "node ./bin/space-data-module.js check --repo-root .",
     "generate:vectors": "node ./examples/single-file-bundle/generate-vectors.mjs",

package/src/AGENTS.md

@@ -0,0 +1,32 @@
+# AGENTS
+
+Apply the root `AGENTS.md` first. This file is a map for module authors reading
+the SDK source, not a prompt to edit SDK internals by default.
+
+## Use `src/` As A Reference Map
+
+- `src/manifest`, `src/compliance`, `src/standards`: manifest shape, type refs,
+  standards validation, and compliance warnings/errors.
+- `src/manifest/AGENTS.md`, `src/compliance/AGENTS.md`, `src/bundle/AGENTS.md`,
+  and `src/auth/AGENTS.md` provide narrower rules for those owners.
+- `src/compiler`: compile flow, manifest embedding, runtime targets, toolchains,
+  and artifact layout.
+- `src/bundle`: `sds.bundle`, wasm custom sections, and vector compatibility.
+- `src/host`: Node host, browser shims, `sdn_host`, WasmEdge runners, and
+  isomorphic loaders.
+- `src/runtime-host`: FlatSQL-backed runtime host, row/region identity, and
+  binary stream ingest.
+- `src/testing`: harnesses, browser module loading, process invoke clients, and
+  module-owned FlatBuffer stream pumps.
+- `src/auth`, `src/transport`, `src/deployment`: signing, encryption, REC/PNM/
+  ENC records, deployment plans, and publication protection.
+- `src/generated`: generated code. Do not hand-edit unless regeneration is part
+  of the task and you update the generation path or fixtures as needed.
+
+## Author Rules
+
+- Prefer public APIs and examples over editing `src/*`.
+- Read the nearest child `AGENTS.md` to understand which source files define the
+  contract you are using.
+- Only edit internals here when the task explicitly says to change the SDK
+  standard for everyone.

package/src/auth/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS
+
+This directory is the reference implementation for deployment authorization and
+signing helpers used by compliant module distribution.
+
+## What Authors Should Use It For
+
+- Keep signing and authorization flows deterministic and explicit.
+- Do not invent app-local signature records when a repo-level contract belongs
+  here.
+
+## Related Surfaces
+
+- `src/transport`
+- `src/deployment`
+- `test/transport-records.test.js`
+- `test/deployment-plan.test.js`
+
+## Note
+
+Use the exported helpers here rather than inventing your own signing records.
+Only edit this directory when you are intentionally changing the auth contract.

package/src/browser.js

@@ -6,9 +6,11 @@ export * from "./capabilities.js";
 export * from "./deployment/index.js";
 export * from "./invoke/index.js";
 export * from "./runtime/index.js";
+export * from "./runtime-host/index.js";
 export * from "./host/browserHost.js";
 export * from "./host/browserEdgeShims.js";
 export * from "./host/wasiShim.js";
 export * from "./host/abi.js";
 export * from "./host/isomorphicLoader.js";
 export { createBrowserModuleHarness, detectArtifactProfile } from "./testing/browserModuleHarness.js";
+export { createModuleFlatBufferStreamPump } from "./testing/moduleFlatbufferStreamPump.js";

package/src/bundle/AGENTS.md

@@ -0,0 +1,17 @@
+# AGENTS
+
+This directory is the reference implementation for `sds.bundle` and wasm
+custom-section packaging.
+
+## What Authors Should Use It For
+
+- `sds.bundle` is the single-file delivery format.
+- Put bundle data in a wasm custom section; do not append raw bytes after the
+  wasm binary.
+- Use the public bundle helpers and CLI from this repo rather than inventing a
+  custom one-file format.
+
+## Note
+
+Only edit this directory when you are intentionally changing bundle behavior for
+all consumers.

package/src/compiler/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS
+
+Apply the root and `src/AGENTS.md` files first. This directory tells module
+authors how the compiler behaves.
+
+## What Authors Should Take From This Directory
+
+- `compileModuleFromSource(...)` and the CLI are the canonical ways to produce a
+  compliant artifact.
+- Manifest embedding and required exports are generated together with the wasm
+  bytes.
+- Shared browser/WasmEdge artifacts should land at
+  `dist/isomorphic/module.wasm`.
+
+## Compiler Rules Authors Should Follow
+
+- Preserve the canonical manifest accessor exports and validate them together
+  with compiled wasm.
+- For shared browser/WasmEdge modules, emit the standalone artifact at
+  `dist/isomorphic/module.wasm`.
+- Optional browser adapters belong under `dist/browser/`.
+- Do not make browser/WasmEdge shared artifacts depend on pthread-style `env.*`
+  imports.
+- Prefer repo-local Emscripten or `sdn-emception`. Do not assume Homebrew
+  toolchains.
+
+## Key Files To Read
+
+- `compileModule.js`
+- `compileModuleFromSource.js`
+- `emception*.js`
+- `invokeGlue.js`
+
+## Note
+
+Do not edit compiler internals just to build one module. Only change this
+directory when you are intentionally changing the repo-wide compile contract.

package/src/compliance/AGENTS.md

@@ -0,0 +1,16 @@
+# AGENTS
+
+This directory is the reference policy for what counts as a compliant module or
+artifact.
+
+## What Authors Should Use It For
+
+- Use the CLI and public validation helpers to understand whether a manifest or
+  artifact is compliant.
+- Read this directory when you need to know why a module was rejected.
+- Prefer fixing your module manifest or build output before changing policy here.
+
+## Note
+
+Only edit this directory when you are intentionally changing the compliance
+standard for all module authors.

package/src/host/AGENTS.md

@@ -0,0 +1,38 @@
+# AGENTS
+
+Apply the root and `src/AGENTS.md` files first. This directory explains the
+host/runtime boundary that compliant modules can rely on.
+
+## What Authors Should Take From This Directory
+
+- The portable shared path is standalone WASI, optionally plus `sdn_host`.
+- Browser helpers here are host-side shims and harnesses, not proof that raw
+  WasmEdge-native guest imports are browser-portable.
+- The isomorphic loader and browser harness show how the same artifact is meant
+  to run in both places.
+
+## Host Rules Authors Should Follow
+
+- Shared browser/WasmEdge artifacts must stay within standalone WASI plus the
+  optional `sdn_host` bridge. Raw WasmEdge-native extension imports are not
+  browser-isomorphic.
+- Browser shims are host-side replacements, not a promise that the guest can
+  import WasmEdge-native sockets, TLS, or filesystem extensions directly.
+- Keep the sync guest-host ABI narrow and deliberate. Avoid adding new hostcalls
+  unless the Node host, browser path, docs, and tests all agree on semantics.
+- Scope host capabilities tightly: filesystem roots, network allowlists, TLS,
+  exec, timers, and crypto should stay explicit.
+
+## Key Files To Read
+
+- `abi.js`
+- `browserEdgeShims.js`
+- `browserHost.js`
+- `isomorphicLoader.js`
+- `nodeHost.js`
+- `wasiShim.js`
+
+## Note
+
+Prefer using the exported host and harness surfaces rather than editing these
+files unless the task is explicitly to change the SDK host contract.

package/src/host/isomorphicLoader.js

@@ -18,6 +18,123 @@ const isBrowser =
   typeof globalThis.window !== "undefined" &&
   typeof globalThis.document !== "undefined";
 
+async function createWasmEdgeCommandHarness(options = {}) {
+  const [
+    { spawn },
+    { readFile },
+    pathModule,
+    { encodePluginInvokeRequest, decodePluginInvokeResponse },
+    { buildWasmEdgeSpawnEnv },
+    { DefaultInvokeExports },
+    { toUint8Array },
+  ] = await Promise.all([
+    import("node:child_process"),
+    import("node:fs/promises"),
+    import("node:path"),
+    import("../invoke/codec.js"),
+    import("../testing/processInvoke.js"),
+    import("../runtime/constants.js"),
+    import("../runtime/bufferLike.js"),
+  ]);
+  const path = pathModule.default ?? pathModule;
+  const wasmPath = path.resolve(String(options.wasmSource));
+  const wasmBytes = await readFile(wasmPath);
+  const inspection = await inspectModule(wasmBytes);
+
+  if (!inspection.exports.includes(DefaultInvokeExports.commandSymbol)) {
+    throw new Error(
+      "Standalone WasmEdge loading requires a command-surface artifact with the _start export.",
+    );
+  }
+
+  const command = options.wasmEdgeBinary ?? "wasmedge";
+  const args = [
+    ...(options.enableThreads === false ? [] : ["--enable-threads"]),
+    wasmPath,
+    ...(Array.isArray(options.args) ? options.args : []),
+  ];
+  const launchPlan = {
+    command,
+    args,
+    env: buildWasmEdgeSpawnEnv(options.env),
+    cwd: options.cwd ?? process.cwd(),
+    wasmPath,
+  };
+
+  async function invokeRaw(requestBytes) {
+    const normalizedRequest = toUint8Array(requestBytes);
+    if (!normalizedRequest) {
+      throw new TypeError(
+        "Expected Uint8Array, ArrayBufferView, or ArrayBuffer request bytes.",
+      );
+    }
+
+    return new Promise((resolve, reject) => {
+      const child = spawn(launchPlan.command, launchPlan.args, {
+        cwd: launchPlan.cwd,
+        env: launchPlan.env,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      const stdoutChunks = [];
+      const stderrChunks = [];
+
+      function formatFailure(message, cause = null) {
+        const stderrText = Buffer.concat(stderrChunks).toString("utf8").trim();
+        const details = stderrText ? `${message}\n${stderrText}` : message;
+        return cause ? new Error(details, { cause }) : new Error(details);
+      }
+
+      child.stdout.on("data", (chunk) => {
+        stdoutChunks.push(Buffer.from(chunk));
+      });
+      child.stderr.on("data", (chunk) => {
+        stderrChunks.push(Buffer.from(chunk));
+      });
+      child.on("error", (error) => {
+        reject(
+          formatFailure(
+            "Failed to launch WasmEdge command harness.",
+            error,
+          ),
+        );
+      });
+      child.on("close", (code, signal) => {
+        if (code !== 0 || signal !== null) {
+          reject(
+            formatFailure(
+              `WasmEdge command harness exited with ${
+                signal ? `signal ${signal}` : `code ${code}`
+              }.`,
+            ),
+          );
+          return;
+        }
+        resolve(new Uint8Array(Buffer.concat(stdoutChunks)));
+      });
+      child.stdin.end(Buffer.from(normalizedRequest));
+    });
+  }
+
+  return {
+    runtime: {
+      kind: "wasmedge",
+      profile: inspection.profile,
+      surface: "command",
+    },
+    launchPlan,
+    invokeRaw,
+    async invoke(request = {}) {
+      const requestBytes = encodePluginInvokeRequest(request);
+      const responseBytes = await invokeRaw(requestBytes);
+      return decodePluginInvokeResponse(responseBytes);
+    },
+    readManifest() {
+      return null;
+    },
+    async destroy() {},
+  };
+}
+
 /**
  * Load a WASM module isomorphically.
  *
@@ -46,6 +163,22 @@ export async function loadModule(options = {}) {
 
   const runtimeKind = options.runtimeKind ?? "wasmedge";
   if (runtimeKind === "wasmedge") {
+    const runtimeHostRequested =
+      String(options.hostProfile ?? "").trim().toLowerCase() === "runtime-host" ||
+      Array.isArray(options.modules) ||
+      (typeof options.defaultModuleId === "string" &&
+        options.defaultModuleId.trim().length > 0);
+    if (!runtimeHostRequested && !options.wasmEdgeRunnerBinary) {
+      const { readFile } = await import("node:fs/promises");
+      const inspection = await inspectModule(await readFile(source));
+      if (
+        (inspection.profile === "standalone" || inspection.profile === "sdn-abi") &&
+        inspection.exports.includes("_start")
+      ) {
+        return createWasmEdgeCommandHarness(options);
+      }
+    }
+
     return createModuleHarness({
       runtime: {
         kind: "wasmedge",

package/src/host/wasiShim.js

@@ -7,7 +7,8 @@
  *
  * Covers the 11 imports observed across all SDN plugin standalone builds:
  *   clock_time_get, fd_write, fd_read, fd_close, fd_seek, fd_fdstat_get,
- *   environ_sizes_get, environ_get, proc_exit, args_get, args_sizes_get
+ *   environ_sizes_get, environ_get, proc_exit, args_get, args_sizes_get,
+ *   random_get
  */
 
 const ERRNO_SUCCESS = 0;
@@ -38,6 +39,7 @@ export function createBrowserWasiShim(options = {}) {
     now: () => Date.now(),
     timeOrigin: 0,
   };
+  const cryptoApi = options.crypto ?? globalThis.crypto ?? null;
   const stdoutChunks = [];
   const stderrChunks = [];
   let stdinOffset = 0;
@@ -206,6 +208,14 @@ export function createBrowserWasiShim(options = {}) {
     return ERRNO_SUCCESS;
   }
 
+  function random_get(bufPtr, bufLen) {
+    if (!cryptoApi?.getRandomValues) {
+      return ERRNO_NOSYS;
+    }
+    cryptoApi.getRandomValues(mem8().subarray(bufPtr, bufPtr + bufLen));
+    return ERRNO_SUCCESS;
+  }
+
   function proc_exit(code) {
     if (logOutput) {
       flushOutput();
@@ -259,6 +269,7 @@ export function createBrowserWasiShim(options = {}) {
         environ_get,
         args_sizes_get,
         args_get,
+        random_get,
         proc_exit,
       },
     },

package/src/index.d.ts

@@ -277,6 +277,22 @@ export interface RuntimeRowQueryResult {
   rowCount: number;
 }
 
+export interface FlatBufferStreamIngestStats {
+  bytesReceived: number;
+  chunksReceived: number;
+  framesDecoded: number;
+  framesAppended: number;
+  framesRouted: number;
+  parseErrors: number;
+}
+
+export interface FlatBufferStreamIngestContext {
+  rawFileIdentifier: string;
+  schemaFileId: string;
+  rows: FlatSqlRuntimeStore;
+  stats: FlatBufferStreamIngestStats;
+}
+
 export interface FlatSqlRuntimeStore {
   appendRow(options: { schemaFileId: string; payload?: unknown }): RowHandle;
   listRows(schemaFileId?: string | null): RuntimeRowView[];
@@ -284,6 +300,13 @@ export interface FlatSqlRuntimeStore {
   resolveRow(handle: RowHandle): RuntimeRowView | null;
 }
 
+export interface FlatBufferStreamIngestor {
+  rows: FlatSqlRuntimeStore;
+  stats: FlatBufferStreamIngestStats;
+  pushBytes(data: Uint8Array | ArrayBuffer | ArrayBufferView): number;
+  finish(): 0;
+}
+
 export interface RuntimeRegionDescriptor {
   regionId: number;
   layoutId: string;
@@ -388,6 +411,25 @@ export interface RuntimeHost {
   moduleRegistry: RuntimeModuleRegistry;
 }
 
+export function createFlatBufferStreamIngestor(options?: {
+  rows?: FlatSqlRuntimeStore;
+  frameRouter?:
+    | ((
+        payload: Uint8Array,
+        context: FlatBufferStreamIngestContext,
+      ) => boolean | void)
+    | Record<
+        string,
+        (
+          payload: Uint8Array,
+          context: FlatBufferStreamIngestContext,
+        ) => boolean | void
+      >;
+  appendFrame?: (
+    payload: Uint8Array,
+    context: FlatBufferStreamIngestContext,
+  ) => void;
+}): FlatBufferStreamIngestor;
 export function createFlatSqlRuntimeStore(): FlatSqlRuntimeStore;
 export function createRuntimeRegionStore(): RuntimeRegionStore;
 export function createModuleRegistry(): RuntimeModuleRegistry;
@@ -1563,6 +1605,64 @@ export function createBrowserModuleHarness(options?: {
   };
   logOutput?: boolean;
 }): Promise<BrowserModuleHarness>;
+export interface ModuleFlatBufferStreamPumpStats {
+  bytesReceived: number;
+  chunksReceived: number;
+  framesDecoded: number;
+  framesInvoked: number;
+  invokes: number;
+  parseErrors: number;
+}
+export interface ModuleFlatBufferStreamPumpContext {
+  rawFileIdentifier: string;
+  schemaFileId: string;
+  methodId: string;
+  portId: string;
+  streamId: number;
+  sequence: number;
+  stats: ModuleFlatBufferStreamPumpStats;
+}
+export interface ModuleFlatBufferStreamPump {
+  stats: ModuleFlatBufferStreamPumpStats;
+  lastResponse: PluginInvokeResponseEnvelope | null;
+  pushBytes(data: Uint8Array | ArrayBuffer | ArrayBufferView): Promise<number>;
+  finish(): Promise<PluginInvokeResponseEnvelope | null>;
+}
+export function createModuleFlatBufferStreamPump(options: {
+  harness?: {
+    invoke(
+      request: PluginInvokeRequestEnvelope,
+    ): Promise<PluginInvokeResponseEnvelope>;
+  };
+  invoke?: (
+    request: PluginInvokeRequestEnvelope,
+  ) => Promise<PluginInvokeResponseEnvelope>;
+  methodId: string;
+  portId: string;
+  maxFramesPerInvoke?: number;
+  streamId?: number;
+  sequenceStart?: number;
+  typeResolver?: (
+    payload: Uint8Array,
+    context: ModuleFlatBufferStreamPumpContext,
+  ) => PayloadTypeRef | null | undefined;
+  frameTemplate?:
+    | Partial<InvokeFrame>
+    | ((
+        payload: Uint8Array,
+        context: ModuleFlatBufferStreamPumpContext,
+      ) => Partial<InvokeFrame> | null | undefined);
+  onResponse?: (
+    response: PluginInvokeResponseEnvelope,
+    context: {
+      methodId: string;
+      portId: string;
+      frames: InvokeFrame[];
+      isFinalBatch: boolean;
+      stats: ModuleFlatBufferStreamPumpStats;
+    },
+  ) => void | Promise<void>;
+}): ModuleFlatBufferStreamPump;
 export function loadModule(options?: {
   wasmSource: Uint8Array | ArrayBuffer | string | WebAssembly.Module | unknown;
   host?: BrowserHost;

package/src/manifest/AGENTS.md

@@ -0,0 +1,15 @@
+# AGENTS
+
+This directory is the reference implementation for manifest encoding,
+normalization, and round-trip behavior.
+
+## What Authors Should Use It For
+
+- Keep manifest encode/decode round-trips stable.
+- Prefer canonical SDS schema names and file identifiers; do not add repo-local
+  aliases when a standards name already exists.
+
+## Note
+
+Use the public manifest helpers from this repo to build manifests. Only edit
+this directory when you are intentionally changing the manifest standard.

package/src/runtime-host/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS
+
+Apply the root and `src/AGENTS.md` files first. This directory shows the
+host-owned storage and ingest path available to module authors.
+
+## What Authors Should Take From This Directory
+
+- Host-owned durable identity is `(schemaFileId, rowId)` for rows and
+  `(regionId, recordIndex)` for aligned-binary regions.
+- The canonical ingest path is direct FlatBuffer bytes, not JSON.
+- If the host owns persistence, use these helpers. If a module owns state, keep
+  the stream binary and use the resident-module pump path from `src/testing`.
+
+## Storage And Streaming Rules
+
+- Keep durable row identity host-owned as `(schemaFileId, rowId)`.
+- Keep runtime aligned-binary identity host-owned as `(regionId, recordIndex)`.
+- The canonical ingest path is binary FlatBuffer bytes, not JSON.
+- Use size-prefixed FlatBuffer frames for streaming transport.
+- Do not coerce row payloads through JSON serialization.
+- If the host owns persistence, use runtime-host ingest helpers.
+- If a resident module owns state, keep the stream binary and push into the
+  module through the harness/pump path rather than inventing JSON wrappers.
+
+## Key Files To Read
+
+- `flatbufferStreamIngestor.js`
+- `flatsqlRuntimeStore.js`
+- `index.js`
+
+## Note
+
+Do not edit this directory just to store data for one module. Use the exported
+helpers unless you are intentionally changing the runtime-host contract.