space-data-module-sdk 0.5.18 → 0.5.21

package/src/host/wasiShim.js

@@ -0,0 +1,286 @@
+/**
+ * Browser-compatible WASI preview1 shim.
+ *
+ * Provides the wasi_snapshot_preview1 import namespace so that standalone
+ * WASI modules (the same .wasm that runs in WasmEdge) can be instantiated
+ * directly in the browser via WebAssembly.instantiate().
+ *
+ * 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,
+ *   random_get
+ */
+
+const ERRNO_SUCCESS = 0;
+const ERRNO_BADF = 8;
+const ERRNO_INVAL = 28;
+const ERRNO_NOSYS = 52;
+const ERRNO_SPIPE = 70;
+
+const CLOCKID_REALTIME = 0;
+const CLOCKID_MONOTONIC = 1;
+
+const FILETYPE_CHARACTER_DEVICE = 2;
+
+export class WasiExitError extends Error {
+  constructor(code) {
+    super(`WASI exit with code ${code}`);
+    this.name = "WasiExitError";
+    this.code = code;
+  }
+}
+
+export function createBrowserWasiShim(options = {}) {
+  const args = options.args ?? [];
+  const env = options.env ?? {};
+  const stdinBytes = new Uint8Array(options.stdinBytes ?? []);
+  const logOutput = options.logOutput === true;
+  const performanceApi = options.performance ?? globalThis.performance ?? {
+    now: () => Date.now(),
+    timeOrigin: 0,
+  };
+  const cryptoApi = options.crypto ?? globalThis.crypto ?? null;
+  const stdoutChunks = [];
+  const stderrChunks = [];
+  let stdinOffset = 0;
+
+  let memory = null;
+
+  function setMemory(mem) {
+    memory = mem;
+  }
+
+  function getMemory() {
+    return memory;
+  }
+
+  function mem8() {
+    return new Uint8Array(memory.buffer);
+  }
+  function view() {
+    return new DataView(memory.buffer);
+  }
+
+  // --- Environment encoding helpers ---
+
+  const envEntries = Object.entries(env).map(([k, v]) => `${k}=${v}`);
+  const encodedEnvEntries = envEntries.map((e) => new TextEncoder().encode(e));
+  const encodedArgs = args.map((a) => new TextEncoder().encode(a));
+
+  // --- WASI functions ---
+
+  function clock_time_get(clockId, _precisionBigInt, resultPtr) {
+    let nanos;
+    if (clockId === CLOCKID_REALTIME) {
+      nanos = BigInt(
+        Math.round((performanceApi.timeOrigin + performanceApi.now()) * 1e6),
+      );
+    } else if (clockId === CLOCKID_MONOTONIC) {
+      nanos = BigInt(Math.round(performanceApi.now() * 1e6));
+    } else {
+      return ERRNO_INVAL;
+    }
+    view().setBigUint64(resultPtr, nanos, true);
+    return ERRNO_SUCCESS;
+  }
+
+  function fd_write(fd, iovsPtr, iovsLen, nwrittenPtr) {
+    if (fd !== 1 && fd !== 2) return ERRNO_BADF;
+
+    const target = fd === 1 ? stdoutChunks : stderrChunks;
+    let totalWritten = 0;
+    const dv = view();
+    const bytes = mem8();
+
+    for (let i = 0; i < iovsLen; i++) {
+      const base = iovsPtr + i * 8;
+      const ptr = dv.getUint32(base, true);
+      const len = dv.getUint32(base + 4, true);
+      target.push(bytes.slice(ptr, ptr + len));
+      totalWritten += len;
+    }
+
+    dv.setUint32(nwrittenPtr, totalWritten, true);
+    return ERRNO_SUCCESS;
+  }
+
+  function fd_read(fd, iovsPtr, iovsLen, nreadPtr) {
+    if (fd !== 0) {
+      view().setUint32(nreadPtr, 0, true);
+      return ERRNO_BADF;
+    }
+
+    const dv = view();
+    const bytes = mem8();
+    let totalRead = 0;
+
+    for (let i = 0; i < iovsLen; i += 1) {
+      if (stdinOffset >= stdinBytes.length) {
+        break;
+      }
+      const base = iovsPtr + i * 8;
+      const ptr = dv.getUint32(base, true);
+      const len = dv.getUint32(base + 4, true);
+      const remaining = stdinBytes.length - stdinOffset;
+      const count = Math.min(len, remaining);
+      bytes.set(stdinBytes.subarray(stdinOffset, stdinOffset + count), ptr);
+      stdinOffset += count;
+      totalRead += count;
+    }
+
+    dv.setUint32(nreadPtr, totalRead, true);
+    return ERRNO_SUCCESS;
+  }
+
+  function fd_close(fd) {
+    if (fd <= 2) return ERRNO_SUCCESS;
+    return ERRNO_BADF;
+  }
+
+  function fd_seek(fd, _offsetLo, _whence, _resultPtr) {
+    if (fd <= 2) return ERRNO_SPIPE;
+    return ERRNO_BADF;
+  }
+
+  function fd_fdstat_get(fd, bufPtr) {
+    if (fd > 2) return ERRNO_BADF;
+    const dv = view();
+    // filetype (u8) at offset 0 — CHARACTER_DEVICE
+    dv.setUint8(bufPtr, FILETYPE_CHARACTER_DEVICE);
+    // fdflags (u16) at offset 2
+    dv.setUint16(bufPtr + 2, 0, true);
+    // rights_base (u64) at offset 8
+    dv.setBigUint64(bufPtr + 8, 0n, true);
+    // rights_inheriting (u64) at offset 16
+    dv.setBigUint64(bufPtr + 16, 0n, true);
+    return ERRNO_SUCCESS;
+  }
+
+  function environ_sizes_get(countPtr, bufSizePtr) {
+    const dv = view();
+    dv.setUint32(countPtr, encodedEnvEntries.length, true);
+    let totalSize = 0;
+    for (const entry of encodedEnvEntries) {
+      totalSize += entry.length + 1; // null terminator
+    }
+    dv.setUint32(bufSizePtr, totalSize, true);
+    return ERRNO_SUCCESS;
+  }
+
+  function environ_get(environPtr, environBufPtr) {
+    const dv = view();
+    const bytes = mem8();
+    let bufOffset = environBufPtr;
+
+    for (let i = 0; i < encodedEnvEntries.length; i++) {
+      dv.setUint32(environPtr + i * 4, bufOffset, true);
+      bytes.set(encodedEnvEntries[i], bufOffset);
+      bufOffset += encodedEnvEntries[i].length;
+      bytes[bufOffset] = 0; // null terminator
+      bufOffset += 1;
+    }
+    return ERRNO_SUCCESS;
+  }
+
+  function args_sizes_get(argcPtr, argvBufSizePtr) {
+    const dv = view();
+    dv.setUint32(argcPtr, encodedArgs.length, true);
+    let totalSize = 0;
+    for (const arg of encodedArgs) {
+      totalSize += arg.length + 1;
+    }
+    dv.setUint32(argvBufSizePtr, totalSize, true);
+    return ERRNO_SUCCESS;
+  }
+
+  function args_get(argvPtr, argvBufPtr) {
+    const dv = view();
+    const bytes = mem8();
+    let bufOffset = argvBufPtr;
+
+    for (let i = 0; i < encodedArgs.length; i++) {
+      dv.setUint32(argvPtr + i * 4, bufOffset, true);
+      bytes.set(encodedArgs[i], bufOffset);
+      bufOffset += encodedArgs[i].length;
+      bytes[bufOffset] = 0;
+      bufOffset += 1;
+    }
+    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();
+    }
+    throw new WasiExitError(code);
+  }
+
+  // --- Output helpers ---
+
+  function flushOutput() {
+    if (stdoutChunks.length > 0) {
+      const combined = concatChunks(stdoutChunks);
+      if (logOutput) {
+        const text = new TextDecoder().decode(combined);
+        if (text) console.log(text);
+      }
+      stdoutChunks.length = 0;
+    }
+    if (stderrChunks.length > 0) {
+      const combined = concatChunks(stderrChunks);
+      if (logOutput) {
+        const text = new TextDecoder().decode(combined);
+        if (text) console.warn(text);
+      }
+      stderrChunks.length = 0;
+    }
+  }
+
+  function concatChunks(chunks) {
+    let totalLen = 0;
+    for (const chunk of chunks) totalLen += chunk.length;
+    const result = new Uint8Array(totalLen);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return result;
+  }
+
+  return {
+    imports: {
+      wasi_snapshot_preview1: {
+        clock_time_get,
+        fd_write,
+        fd_read,
+        fd_close,
+        fd_seek,
+        fd_fdstat_get,
+        environ_sizes_get,
+        environ_get,
+        args_sizes_get,
+        args_get,
+        random_get,
+        proc_exit,
+      },
+    },
+    setMemory,
+    getMemory,
+    flushOutput,
+    get stdout() {
+      return concatChunks(stdoutChunks);
+    },
+    get stderr() {
+      return concatChunks(stderrChunks);
+    },
+  };
+}

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;
@@ -1037,6 +1079,62 @@ export interface HostcallBridge {
   getLastResponseJson(): unknown;
 }
 
+export interface BrowserFilesystemShim {
+  filesystemRoot?: string;
+  resolvePath(path?: string): string;
+  readFile(
+    path: string,
+    options?: { encoding?: string | null },
+  ): Promise<string | Uint8Array>;
+  writeFile(
+    path: string,
+    value: Uint8Array | ArrayBuffer | ArrayBufferView | string,
+    options?: { encoding?: string | null },
+  ): Promise<{ path: string }>;
+  appendFile(
+    path: string,
+    value: Uint8Array | ArrayBuffer | ArrayBufferView | string,
+    options?: { encoding?: string | null },
+  ): Promise<{ path: string }>;
+  deleteFile(path: string): Promise<{ path: string }>;
+  mkdir(
+    path: string,
+    options?: { recursive?: boolean },
+  ): Promise<{ path: string }>;
+  readdir(path?: string): Promise<NodeHostFilesystemEntry[]>;
+  stat(path: string): Promise<NodeHostFilesystemStat>;
+  rename(
+    fromPath: string,
+    toPath: string,
+  ): Promise<{ from: string; to: string }>;
+}
+
+export interface BrowserEdgeShims {
+  fetch?: (...args: any[]) => Promise<any>;
+  WebSocket?: any;
+  crypto?: any;
+  performance?: {
+    now(): number;
+    timeOrigin: number;
+  };
+  filesystem?: BrowserFilesystemShim;
+}
+
+export interface BrowserHostOptions {
+  capabilities?: string[];
+  edgeShims?: BrowserEdgeShims;
+  contextStore?: Map<string, Map<string, unknown>>;
+  fetch?: (...args: any[]) => Promise<any>;
+  WebSocket?: any;
+  crypto?: any;
+  performance?: {
+    now(): number;
+    timeOrigin: number;
+  };
+  filesystem?: BrowserFilesystemShim;
+  filesystemRoot?: string;
+}
+
 export interface NodeHostOptions {
   manifest?: PluginManifest;
   grantedCapabilities?: string[];
@@ -1072,6 +1170,12 @@ export class HostFilesystemScopeError extends Error {
   filesystemRoot: string | null;
 }
 
+export class BrowserFilesystemScopeError extends Error {
+  code: string;
+  requestedPath: string | null;
+  filesystemRoot: string | null;
+}
+
 export class NodeHost {
   runtimeTarget: string;
   filesystemRoot: string;
@@ -1322,14 +1426,93 @@ export class NodeHost {
   invoke(operation: string, params?: Record<string, any>): Promise<any>;
 }
 
+export class BrowserHost {
+  runtimeTarget: string;
+  filesystemRoot: string;
+  clock: {
+    now(): number;
+    monotonicNow(): number;
+    nowIso(): string;
+  };
+  random: {
+    bytes(length: number): Uint8Array;
+  };
+  timers: {
+    delay(ms: number): Promise<void>;
+  };
+  schedule: {
+    parse(expression: string): CronSchedule;
+    matches(expression: string | CronSchedule, date?: Date | number | string): boolean;
+    next(expression: string | CronSchedule, from?: Date | number | string): Date;
+  };
+  http: {
+    request<TBody = unknown>(options: NodeHostHttpRequest): Promise<NodeHostHttpResponse<TBody>>;
+  };
+  websocket: {
+    exchange<TBody = unknown>(options: {
+      url: string;
+      protocols?: string | string[];
+      message?: Uint8Array | ArrayBuffer | ArrayBufferView | string | null;
+      responseType?: "bytes" | "utf8" | "json";
+      timeoutMs?: number;
+      expectResponse?: boolean;
+    }): Promise<NodeHostWebSocketResponse<TBody>>;
+  };
+  context: {
+    get(scope: string, key: string): unknown;
+    set(scope: string, key: string, value: unknown): void;
+    delete(scope: string, key: string): void;
+    listKeys(scope: string): string[];
+    listScopes(): string[];
+  };
+  crypto: {
+    sha256(data: Uint8Array | ArrayBuffer | ArrayBufferView | string): Promise<Uint8Array>;
+    sha512(data: Uint8Array | ArrayBuffer | ArrayBufferView | string): Promise<Uint8Array>;
+    aesGcmEncrypt(options: {
+      key: Uint8Array | ArrayBuffer | ArrayBufferView;
+      plaintext: Uint8Array | ArrayBuffer | ArrayBufferView;
+      iv?: Uint8Array | ArrayBuffer | ArrayBufferView;
+    }): Promise<{ ciphertext: Uint8Array; iv: Uint8Array | ArrayBuffer | ArrayBufferView }>;
+    aesGcmDecrypt(options: {
+      key: Uint8Array | ArrayBuffer | ArrayBufferView;
+      ciphertext: Uint8Array | ArrayBuffer | ArrayBufferView;
+      iv: Uint8Array | ArrayBuffer | ArrayBufferView;
+    }): Promise<Uint8Array>;
+  };
+  filesystem: BrowserFilesystemShim;
+  constructor(options?: BrowserHostOptions);
+  listCapabilities(): string[];
+  listSupportedCapabilities(): string[];
+  listOperations(): string[];
+  hasCapability(capability: string): boolean;
+  assertCapability(capability: string, operation?: string | null): void;
+}
+
 export const NodeHostSupportedCapabilities: readonly string[];
 export const NodeHostSupportedOperations: readonly string[];
+export const BrowserHostSupportedCapabilities: readonly string[];
+export const BrowserHostSupportedOperations: readonly string[];
 export const DEFAULT_HOSTCALL_IMPORT_MODULE: string;
 export const HOSTCALL_STATUS_OK: number;
 export const HOSTCALL_STATUS_ERROR: number;
 export const NodeHostSyncHostcallOperations: readonly string[];
 
 export function createNodeHost(options?: NodeHostOptions): NodeHost;
+export function createBrowserHost(options?: BrowserHostOptions): BrowserHost;
+export function createMemoryFilesystemEdgeShim(options?: {
+  filesystemRoot?: string;
+}): BrowserFilesystemShim;
+export function createBrowserEdgeShims(options?: {
+  fetch?: (...args: any[]) => Promise<any>;
+  WebSocket?: any;
+  crypto?: any;
+  performance?: {
+    now(): number;
+    timeOrigin: number;
+  };
+  filesystem?: BrowserFilesystemShim;
+  filesystemRoot?: string;
+}): BrowserEdgeShims;
 export function parseCronExpression(expression: string): CronSchedule;
 export function matchesCronExpression(
   expression: string | CronSchedule,
@@ -1361,6 +1544,148 @@ export function createNodeHostSyncHostcallBridge(options: {
   maxRequestBytes?: number;
   maxResponseBytes?: number;
 }): HostcallBridge;
+export class WasiExitError extends Error {
+  code: number;
+}
+export interface BrowserWasiShim {
+  imports: Record<string, Record<string, (...args: number[]) => number>>;
+  setMemory(mem: { buffer: ArrayBuffer | SharedArrayBuffer }): void;
+  getMemory(): { buffer: ArrayBuffer | SharedArrayBuffer } | null;
+  flushOutput(): void;
+  stdout: Uint8Array;
+  stderr: Uint8Array;
+}
+export function createBrowserWasiShim(options?: {
+  args?: string[];
+  env?: Record<string, string>;
+  stdinBytes?: Uint8Array | ArrayBuffer | ArrayBufferView;
+  logOutput?: boolean;
+  performance?: {
+    now(): number;
+    timeOrigin: number;
+  };
+}): BrowserWasiShim;
+export interface BrowserModuleHarness {
+  runtime: {
+    kind: "browser";
+    profile: string;
+    surface: string;
+  };
+  instance: WebAssembly.Instance;
+  module: WebAssembly.Module;
+  host: BrowserHost;
+  bridge: HostcallBridge | null;
+  wasi: BrowserWasiShim;
+  invokeRaw(
+    requestBytes: Uint8Array | ArrayBuffer | ArrayBufferView,
+  ): Promise<Uint8Array>;
+  invoke(request: {
+    methodId?: string | null;
+    inputs?: HarnessInputFrame[];
+  }): Promise<{
+    statusCode: number;
+    errorCode?: string | null;
+    errorMessage?: string | null;
+    outputs: HarnessInputFrame[];
+  }>;
+  readManifest(): Uint8Array | null;
+  destroy(): void;
+}
+export function detectArtifactProfile(wasmModule: WebAssembly.Module): string;
+export function createBrowserModuleHarness(options?: {
+  wasmSource: Uint8Array | ArrayBuffer | string | WebAssembly.Module | unknown;
+  host?: BrowserHost;
+  hostOptions?: BrowserHostOptions;
+  args?: string[];
+  env?: Record<string, string>;
+  surface?: "direct" | "command";
+  performance?: {
+    now(): number;
+    timeOrigin: number;
+  };
+  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;
+  hostOptions?: BrowserHostOptions;
+  args?: string[];
+  env?: Record<string, string | undefined>;
+  surface?: "direct" | "command";
+  runtimeKind?: "wasmedge" | "process";
+  wasmEdgeBinary?: string;
+  wasmEdgeRunnerBinary?: string;
+  enableThreads?: boolean;
+  hostProfile?: "runtime-host";
+  modules?: RuntimeHostTestModuleDefinition[];
+  defaultModuleId?: string;
+  metadata?: unknown;
+  command?: string;
+  cwd?: string;
+}): Promise<BrowserModuleHarness | ModuleHarness>;
+export function inspectModule(source: Uint8Array | ArrayBuffer | WebAssembly.Module): Promise<{
+  profile: string;
+  exports: string[];
+  imports: WebAssembly.ModuleImportDescriptor[];
+}>;
 
 // --- Runtime constants ---
 

package/src/manifest/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS
+
+You are in `src/manifest`, which owns the manifest schema codecs and
+normalization rules.
+
+## Rules
+
+- 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.
+- If you change a manifest field or normalization rule, update the compiler,
+  compliance checks, and any affected examples/tests together.
+
+## Check Before You Finish
+
+- `npm test`
+- `npm run check:compliance`
+- `node --test test/module-sdk.test.js test/compliance.test.js`

package/src/runtime-host/AGENTS.md

@@ -0,0 +1,32 @@
+# AGENTS
+
+Apply the root and `src/AGENTS.md` files first.
+
+## Area Ownership
+
+This directory owns the canonical runtime-host storage model: row handles,
+region handles, FlatSQL-backed storage, and binary FlatBuffer ingest on the host
+side.
+
+## 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
+
+- `flatbufferStreamIngestor.js`
+- `flatsqlRuntimeStore.js`
+- `index.js`
+
+## Verification
+
+- `npm run test:stream-ingest`
+- `node --test test/flatsql-local-node.test.js`
+- `npm run benchmark:stream-1gib` for large-stream changes