space-data-module-sdk 0.8.4 → 0.8.5

package/src/field-stream/index.d.ts

@@ -0,0 +1,31 @@
+export function encodeUnsignedFieldStreamPolicyForProviderSignature(
+  policy: unknown,
+): Uint8Array;
+
+export function verifyFieldStreamPolicyProviderSignature(
+  policy: unknown,
+  options: {
+    providerPublicKey: Uint8Array | ArrayBuffer | ArrayBufferView;
+    verify(
+      publicKey: Uint8Array,
+      payload: Uint8Array,
+      signature: Uint8Array,
+    ): boolean | Promise<boolean>;
+  },
+): Promise<unknown>;
+
+export function encodeUnsignedFieldStreamMessageForProviderSignature(
+  message: unknown,
+): Uint8Array;
+
+export function verifyFieldStreamMessageProviderSignature(
+  message: unknown,
+  options: {
+    providerPublicKey: Uint8Array | ArrayBuffer | ArrayBufferView;
+    verify(
+      publicKey: Uint8Array,
+      payload: Uint8Array,
+      signature: Uint8Array,
+    ): boolean | Promise<boolean>;
+  },
+): Promise<unknown>;

package/src/field-stream/index.js

@@ -0,0 +1,119 @@
+import * as flatbuffers from "flatbuffers";
+
+import { FSP } from "spacedatastandards.org/lib/js/FSP/main.js";
+import { FSM } from "spacedatastandards.org/lib/js/FSM/main.js";
+
+const PROVIDER_SIGNATURE_LENGTH = 64;
+
+export function encodeUnsignedFieldStreamPolicyForProviderSignature(policy) {
+  const root = fieldStreamPolicyRoot(policy);
+  const unsignedPolicy = root.unpack();
+  unsignedPolicy.PROVIDER_SIGNATURE = [];
+  const builder = new flatbuffers.Builder(1024);
+  const offset = unsignedPolicy.pack(builder);
+  FSP.finishFSPBuffer(builder, offset);
+  return builder.asUint8Array();
+}
+
+export async function verifyFieldStreamPolicyProviderSignature(policy, options = {}) {
+  const root = fieldStreamPolicyRoot(policy);
+  const providerSignature = readProviderSignature(root.providerSignatureArray?.(), "field stream policy");
+  const providerPublicKey = cloneBytes(options.providerPublicKey);
+  if (providerPublicKey.length === 0) {
+    throw new TypeError("verifyFieldStreamPolicyProviderSignature requires providerPublicKey.");
+  }
+  if (typeof options.verify !== "function") {
+    throw new TypeError("verifyFieldStreamPolicyProviderSignature requires verify.");
+  }
+  const payload = encodeUnsignedFieldStreamPolicyForProviderSignature(root);
+  const verified = await options.verify(providerPublicKey, payload, providerSignature);
+  if (!verified) {
+    throw new Error("field stream policy provider signature verification failed");
+  }
+  return root;
+}
+
+export function encodeUnsignedFieldStreamMessageForProviderSignature(message) {
+  const root = fieldStreamMessageRoot(message);
+  const unsignedMessage = root.unpack();
+  unsignedMessage.PROVIDER_SIGNATURE = [];
+  const builder = new flatbuffers.Builder(1024);
+  const offset = unsignedMessage.pack(builder);
+  FSM.finishFSMBuffer(builder, offset);
+  return builder.asUint8Array();
+}
+
+export async function verifyFieldStreamMessageProviderSignature(message, options = {}) {
+  const root = fieldStreamMessageRoot(message);
+  const providerSignature = readProviderSignature(root.providerSignatureArray?.(), "field stream message");
+  const providerPublicKey = cloneBytes(options.providerPublicKey);
+  if (providerPublicKey.length === 0) {
+    throw new TypeError("verifyFieldStreamMessageProviderSignature requires providerPublicKey.");
+  }
+  if (typeof options.verify !== "function") {
+    throw new TypeError("verifyFieldStreamMessageProviderSignature requires verify.");
+  }
+  const payload = encodeUnsignedFieldStreamMessageForProviderSignature(root);
+  const verified = await options.verify(providerPublicKey, payload, providerSignature);
+  if (!verified) {
+    throw new Error("field stream message provider signature verification failed");
+  }
+  return root;
+}
+
+function fieldStreamPolicyRoot(policy) {
+  if (policy && typeof policy.POLICY_ID === "function" && typeof policy.unpack === "function") {
+    return policy;
+  }
+  const bytes = cloneBytes(policy);
+  if (bytes.length === 0) {
+    throw new TypeError("field stream policy is required");
+  }
+  const buffer = new flatbuffers.ByteBuffer(bytes);
+  if (!FSP.bufferHasIdentifier(buffer)) {
+    throw new Error("field stream policy identifier mismatch");
+  }
+  return FSP.getRootAsFSP(buffer);
+}
+
+function fieldStreamMessageRoot(message) {
+  if (message && typeof message.MESSAGE_ID === "function" && typeof message.unpack === "function") {
+    return message;
+  }
+  const bytes = cloneBytes(message);
+  if (bytes.length === 0) {
+    throw new TypeError("field stream message is required");
+  }
+  const buffer = new flatbuffers.ByteBuffer(bytes);
+  if (!FSM.bufferHasIdentifier(buffer)) {
+    throw new Error("field stream message identifier mismatch");
+  }
+  return FSM.getRootAsFSM(buffer);
+}
+
+function readProviderSignature(signature, label) {
+  const bytes = cloneBytes(signature);
+  if (bytes.length !== PROVIDER_SIGNATURE_LENGTH) {
+    throw new Error(`${label} provider signature must be ${PROVIDER_SIGNATURE_LENGTH} bytes`);
+  }
+  if (bytes.every((byte) => byte === 0)) {
+    throw new Error(`${label} provider signature must not be all zeroes`);
+  }
+  return bytes;
+}
+
+function cloneBytes(bytes) {
+  if (!bytes) {
+    return new Uint8Array();
+  }
+  if (bytes instanceof Uint8Array) {
+    return new Uint8Array(bytes);
+  }
+  if (ArrayBuffer.isView(bytes)) {
+    return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength).slice();
+  }
+  if (bytes instanceof ArrayBuffer) {
+    return new Uint8Array(bytes).slice();
+  }
+  return new Uint8Array(bytes);
+}

package/src/flow/dependencyStreamBridge.js

@@ -0,0 +1,234 @@
+import { DrainPolicy } from "../generated/orbpro/manifest.js";
+import {
+  FlatBufferTypeRefT,
+  PayloadWireFormat,
+  TypedArenaBufferT,
+  BufferMutability,
+  BufferOwnership,
+} from "../generated/orbpro/stream.js";
+import {
+  decodeStreamInvokeResponse,
+  encodeStreamInvokeRequest,
+} from "./flowCodec.js";
+import { hasByteAddressableBuffer, toUint8Array } from "../runtime/bufferLike.js";
+
+function writeBytes(memory, pointer, data) {
+  const bytes = new Uint8Array(memory.buffer);
+  bytes.set(toUint8Array(data) ?? new Uint8Array(), Number(pointer) >>> 0);
+}
+
+function cloneBytes(memory, offset, size) {
+  const base = Number(offset) >>> 0;
+  const length = Number(size) >>> 0;
+  if (length === 0) {
+    return new Uint8Array();
+  }
+  return new Uint8Array(new Uint8Array(memory.buffer, base, length));
+}
+
+function normalizeBigInt(value, fallback = 0n) {
+  if (typeof value === "bigint") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return BigInt(value);
+  }
+  return fallback;
+}
+
+function normalizeTypeRef(typeRef = null) {
+  if (!typeRef) {
+    return null;
+  }
+  if (typeRef instanceof FlatBufferTypeRefT) {
+    return typeRef;
+  }
+  return new FlatBufferTypeRefT(
+    typeRef.schemaName ?? typeRef.schema_name ?? null,
+    typeRef.fileIdentifier ?? typeRef.file_identifier ?? null,
+    ArrayBuffer.isView(typeRef.schemaHash ?? typeRef.schema_hash)
+      ? Array.from(typeRef.schemaHash ?? typeRef.schema_hash)
+      : Array.isArray(typeRef.schemaHash ?? typeRef.schema_hash)
+        ? [...(typeRef.schemaHash ?? typeRef.schema_hash)]
+        : [],
+    Boolean(
+      typeRef.acceptsAnyFlatbuffer ?? typeRef.accepts_any_flatbuffer ?? false,
+    ),
+    typeRef.wireFormat ?? typeRef.wire_format ?? PayloadWireFormat.Flatbuffer,
+    typeRef.rootTypeName ?? typeRef.root_type_name ?? null,
+    Number(typeRef.fixedStringLength ?? typeRef.fixed_string_length ?? 0),
+    Number(typeRef.byteLength ?? typeRef.byte_length ?? 0),
+    Number(typeRef.requiredAlignment ?? typeRef.required_alignment ?? 0),
+  );
+}
+
+function getDependencyMemory(instantiatedDependency) {
+  const memory =
+    instantiatedDependency?.memory ??
+    instantiatedDependency?.exports?.memory ??
+    null;
+  if (!memory || !hasByteAddressableBuffer(memory)) {
+    throw new Error(
+      "Dependency stream bridge requires dependency WebAssembly.Memory.",
+    );
+  }
+  return memory;
+}
+
+function getDependencyAllocator(instantiatedDependency) {
+  const malloc =
+    instantiatedDependency?.resolvedExports?.malloc ??
+    instantiatedDependency?.exports?.malloc ??
+    null;
+  const free =
+    instantiatedDependency?.resolvedExports?.free ??
+    instantiatedDependency?.exports?.free ??
+    null;
+  if (typeof malloc !== "function" || typeof free !== "function") {
+    throw new Error(
+      "Dependency stream bridge requires dependency malloc/free exports.",
+    );
+  }
+  return { malloc, free };
+}
+
+function getDependencyRawInvoker(instantiatedDependency) {
+  const invokeRawStream = instantiatedDependency?.invokeRawStream ?? null;
+  if (typeof invokeRawStream !== "function") {
+    throw new Error(
+      "Dependency stream bridge requires instantiatedDependency.invokeRawStream().",
+    );
+  }
+  return invokeRawStream;
+}
+
+function stageInputFrames(instantiatedDependency, inputs = []) {
+  const memory = getDependencyMemory(instantiatedDependency);
+  const { malloc, free } = getDependencyAllocator(instantiatedDependency);
+  const stagedPointers = [];
+  const typedInputs = inputs.map((input = {}) => {
+    const payload = toUint8Array(
+      input.bytes ?? input.data ?? input.payloadBytes ?? new Uint8Array(),
+    );
+    const pointer =
+      payload.length > 0 ? Number(malloc(payload.length)) >>> 0 : 0;
+    if (pointer !== 0) {
+      writeBytes(memory, pointer, payload);
+      stagedPointers.push(pointer);
+    }
+    return new TypedArenaBufferT(
+      normalizeTypeRef(input.typeRef ?? input.type_ref ?? null),
+      input.portId ?? input.port_id ?? null,
+      Number(input.alignment ?? 8) >>> 0,
+      pointer,
+      payload.length >>> 0,
+      BufferOwnership.BORROWED,
+      Number(input.generation ?? 0) >>> 0,
+      BufferMutability.IMMUTABLE,
+      normalizeBigInt(input.traceToken ?? input.trace_token ?? 0),
+      Number(input.streamId ?? input.stream_id ?? 0) >>> 0,
+      normalizeBigInt(input.sequence ?? 0),
+      Boolean(input.endOfStream ?? input.end_of_stream ?? false),
+    );
+  });
+  return {
+    typedInputs,
+    release() {
+      for (const pointer of stagedPointers) {
+        free(pointer);
+      }
+    },
+  };
+}
+
+function normalizeOutputFrame(instantiatedDependency, output = {}) {
+  const memory = getDependencyMemory(instantiatedDependency);
+  const bytes =
+    typeof instantiatedDependency?.cloneBytes === "function"
+      ? instantiatedDependency.cloneBytes(output.offset, output.size)
+      : cloneBytes(memory, output.offset, output.size);
+  return {
+    typeRef: output.typeRef ?? null,
+    portId: output.portId ?? null,
+    alignment: output.alignment ?? 8,
+    offset: output.offset ?? 0,
+    size: output.size ?? bytes.length,
+    ownership: output.ownership,
+    generation: output.generation ?? 0,
+    mutability: output.mutability,
+    traceToken: Number(output.traceId ?? 0n),
+    streamId: output.streamId ?? 0,
+    sequence: Number(output.sequence ?? 0n),
+    endOfStream: output.endOfStream ?? false,
+    bytes,
+  };
+}
+
+function releaseOutputFrames(instantiatedDependency, outputs = []) {
+  const release =
+    instantiatedDependency?.release ??
+    instantiatedDependency?.resolvedExports?.free ??
+    null;
+  if (typeof release !== "function") {
+    return;
+  }
+  const released = new Set();
+  for (const output of outputs) {
+    const pointer = Number(output.offset ?? 0) >>> 0;
+    if (pointer === 0 || released.has(pointer)) {
+      continue;
+    }
+    release(pointer);
+    released.add(pointer);
+  }
+}
+
+export function createDependencyStreamBridge(options = {}) {
+  const drainPolicy = options.drainPolicy ?? DrainPolicy.DRAIN_UNTIL_YIELD;
+  const releaseOutputs = options.releaseOutputs !== false;
+
+  return function dependencyStreamBridge({
+    methodId,
+    inputs = [],
+    outputStreamCap = 0,
+    instantiatedDependency,
+  } = {}) {
+    const invokeRawStream = getDependencyRawInvoker(instantiatedDependency);
+    const stagedInputs = stageInputFrames(instantiatedDependency, inputs);
+    try {
+      const requestBytes = encodeStreamInvokeRequest({
+        methodId,
+        inputs: stagedInputs.typedInputs,
+        outputStreamCap,
+        drainPolicy,
+      });
+      const responseBytes = invokeRawStream(requestBytes);
+      if (!responseBytes || responseBytes.length === 0) {
+        return {
+          statusCode: 0,
+          backlogRemaining: 0,
+          yielded: false,
+          outputs: [],
+        };
+      }
+      const response = decodeStreamInvokeResponse(responseBytes);
+      const outputs = response.outputs.map((output) =>
+        normalizeOutputFrame(instantiatedDependency, output),
+      );
+      if (releaseOutputs) {
+        releaseOutputFrames(instantiatedDependency, response.outputs);
+      }
+      return {
+        statusCode: response.errorCode ?? 0,
+        backlogRemaining: response.backlogRemaining ?? 0,
+        yielded: response.yielded ?? false,
+        outputs,
+        errorMessage: response.errorMessage ?? null,
+      };
+    } finally {
+      stagedInputs.release();
+    }
+  };
+}
+
+export default createDependencyStreamBridge;

package/src/flow/flatsqlLinkShim.js

@@ -0,0 +1,304 @@
+/**
+ * FlatSQL link shim (loop C.7 direct linkage) — a tiny, fixed wasm module
+ * whose ONLY memory is the FlatSQL engine's exported linear memory
+ * (`(import "flatsql" "memory")`). It is the B-iv "engine-import component"
+ * from sdn-server/docs/flatsql-component-linkage.md in its minimal form: no
+ * data segments, no globals, no stack — pure code — so it is position
+ * independent by construction and instantiates against ANY live engine
+ * instance (WasmEdge named-module registration server-side,
+ * `WebAssembly.instantiate(bytes, { flatsql: engineExports })` in the
+ * browser).
+ *
+ * A linked flow artifact owns its own linear memory (the emscripten heap the
+ * flow runtime needs) and imports the engine's *functions* directly
+ * (`flatsql.malloc/free/flatsql_*` — scalars cross fine). What core wasm
+ * cannot do is LOAD/STORE another instance's memory: this shim closes that
+ * gap. Its loads/stores address the ENGINE memory, so the flow crosses the
+ * memory boundary with direct in-wasm calls (zero hostcalls, zero host
+ * copies):
+ *
+ *   peek8/peek32/peek64  read engine memory (query results, error strings)
+ *   poke8/poke32         write engine memory (SQL text, TLV param blobs)
+ *   fnv1a64              word-folded FNV-1a 64 over an engine-memory range —
+ *                        bit-identical to decision-gate's fnv1a64_etag, the
+ *                        SDK's fnv1a64Hex, and sdn-server's
+ *                        FNV1a64WordFolded (the canonical stream/etag hash)
+ *   count_frames         size-prefixed frame count of an aligned stream in
+ *                        engine memory (the x-sdn-record-count rule:
+ *                        zero-length prefixes are padding; malformed = -1)
+ *
+ * The module bytes are deterministic (assembled below, no toolchain), so the
+ * SAME artifact ships in the SDK, in compiled flow bundles
+ * (dist/flatsql-link-shim.wasm), and embedded in sdn-server's flowrt —
+ * pinned by sha256 in each host's tests.
+ */
+
+// ---------------------------------------------------------------------------
+// Minimal wasm binary emitter (LEB128 + sections) — enough for this module.
+// ---------------------------------------------------------------------------
+
+function lebU(value) {
+  const out = [];
+  let v = value >>> 0;
+  do {
+    let byte = v & 0x7f;
+    v >>>= 7;
+    if (v !== 0) byte |= 0x80;
+    out.push(byte);
+  } while (v !== 0);
+  return out;
+}
+
+function lebS64(value) {
+  // Signed LEB128 for i64.const immediates (BigInt).
+  const out = [];
+  let v = BigInt.asIntN(64, BigInt(value));
+  for (;;) {
+    const byte = Number(v & 0x7fn);
+    v >>= 7n;
+    const signBit = (byte & 0x40) !== 0;
+    if ((v === 0n && !signBit) || (v === -1n && signBit)) {
+      out.push(byte);
+      return out;
+    }
+    out.push(byte | 0x80);
+  }
+}
+
+function lebS32(value) {
+  const out = [];
+  let v = value | 0;
+  for (;;) {
+    const byte = v & 0x7f;
+    v >>= 7;
+    const signBit = (byte & 0x40) !== 0;
+    if ((v === 0 && !signBit) || (v === -1 && signBit)) {
+      out.push(byte);
+      return out;
+    }
+    out.push(byte | 0x80);
+  }
+}
+
+function utf8(text) {
+  return Array.from(new TextEncoder().encode(text));
+}
+
+function section(id, payload) {
+  return [id, ...lebU(payload.length), ...payload];
+}
+
+function vec(entries) {
+  return [...lebU(entries.length), ...entries.flat()];
+}
+
+// Opcodes used below.
+const OP = {
+  block: 0x02,
+  loop: 0x03,
+  if: 0x04,
+  end: 0x0b,
+  br: 0x0c,
+  br_if: 0x0d,
+  return: 0x0f,
+  local_get: 0x20,
+  local_set: 0x21,
+  i32_load: 0x28,
+  i64_load: 0x29,
+  i32_load8_u: 0x2d,
+  i64_load8_u: 0x31,
+  i32_store: 0x36,
+  i32_store8: 0x3a,
+  i32_const: 0x41,
+  i64_const: 0x42,
+  i32_eqz: 0x45,
+  i32_lt_u: 0x49,
+  i32_gt_u: 0x4a,
+  i32_ge_u: 0x4f,
+  i32_add: 0x6a,
+  i32_sub: 0x6b,
+  i32_and: 0x71,
+  i64_add: 0x7c,
+  i64_mul: 0x7e,
+  i64_xor: 0x85,
+  void: 0x40,
+};
+
+const FNV_OFFSET_BASIS = 1469598103934665603n; // deployed decision-gate basis
+const FNV_PRIME = 1099511628211n;
+
+function func(localDecls, body) {
+  const locals = vec(localDecls.map(([count, type]) => [...lebU(count), type]));
+  const payload = [...locals, ...body, OP.end];
+  return [...lebU(payload.length), ...payload];
+}
+
+const I32 = 0x7f;
+const I64 = 0x7e;
+
+function memarg(align) {
+  return [...lebU(align), ...lebU(0)];
+}
+
+/** Assemble the shim module bytes (deterministic). */
+export function buildFlatsqlLinkShimWasm() {
+  const types = [
+    [0x60, ...vec([[I32]]), ...vec([[I32]])], // t0: (i32)->i32
+    [0x60, ...vec([[I32]]), ...vec([[I64]])], // t1: (i32)->i64
+    [0x60, ...vec([[I32], [I32]]), ...vec([])], // t2: (i32,i32)->()
+    [0x60, ...vec([[I32], [I32]]), ...vec([[I64]])], // t3: (i32,i32)->i64
+    [0x60, ...vec([[I32], [I32]]), ...vec([[I32]])], // t4: (i32,i32)->i32
+  ];
+
+  // Imports: (import "flatsql" "memory" (memory 0))
+  const imports = [
+    [
+      ...lebU(7), ...utf8("flatsql"),
+      ...lebU(6), ...utf8("memory"),
+      0x02, // memory import
+      0x00, ...lebU(0), // limits: min 0, no max
+    ],
+  ];
+
+  // Function indexes (imports contribute none): 0..6
+  const funcTypes = [0 /* peek8 */, 0 /* peek32 */, 1 /* peek64 */, 2 /* poke8 */, 2 /* poke32 */, 3 /* fnv1a64 */, 4 /* count_frames */];
+
+  const exports = [
+    [...lebU(5), ...utf8("peek8"), 0x00, ...lebU(0)],
+    [...lebU(6), ...utf8("peek32"), 0x00, ...lebU(1)],
+    [...lebU(6), ...utf8("peek64"), 0x00, ...lebU(2)],
+    [...lebU(5), ...utf8("poke8"), 0x00, ...lebU(3)],
+    [...lebU(6), ...utf8("poke32"), 0x00, ...lebU(4)],
+    [...lebU(7), ...utf8("fnv1a64"), 0x00, ...lebU(5)],
+    [...lebU(12), ...utf8("count_frames"), 0x00, ...lebU(6)],
+  ];
+
+  const peek8 = func([], [OP.local_get, 0, OP.i32_load8_u, ...memarg(0)]);
+  const peek32 = func([], [OP.local_get, 0, OP.i32_load, ...memarg(0)]);
+  const peek64 = func([], [OP.local_get, 0, OP.i64_load, ...memarg(0)]);
+  const poke8 = func([], [OP.local_get, 0, OP.local_get, 1, OP.i32_store8, ...memarg(0)]);
+  const poke32 = func([], [OP.local_get, 0, OP.local_get, 1, OP.i32_store, ...memarg(0)]);
+
+  // fnv1a64(ptr, len) -> i64 : word-folded FNV-1a 64 (8-byte LE words, byte tail).
+  // locals: 2 = hash (i64), 3 = end (i32), 4 = wend (i32)
+  const fnv = func(
+    [
+      [1, I64],
+      [2, I32],
+    ],
+    [
+      OP.i64_const, ...lebS64(FNV_OFFSET_BASIS), OP.local_set, 2,
+      OP.local_get, 0, OP.local_get, 1, OP.i32_add, OP.local_set, 3,
+      OP.local_get, 1, OP.i32_const, ...lebS32(-8), OP.i32_and, OP.local_get, 0, OP.i32_add, OP.local_set, 4,
+      // word loop
+      OP.block, OP.void,
+      OP.loop, OP.void,
+      OP.local_get, 0, OP.local_get, 4, OP.i32_ge_u, OP.br_if, 1,
+      OP.local_get, 2, OP.local_get, 0, OP.i64_load, ...memarg(0), OP.i64_xor,
+      OP.i64_const, ...lebS64(FNV_PRIME), OP.i64_mul, OP.local_set, 2,
+      OP.local_get, 0, OP.i32_const, 8, OP.i32_add, OP.local_set, 0,
+      OP.br, 0,
+      OP.end,
+      OP.end,
+      // byte tail loop
+      OP.block, OP.void,
+      OP.loop, OP.void,
+      OP.local_get, 0, OP.local_get, 3, OP.i32_ge_u, OP.br_if, 1,
+      OP.local_get, 2, OP.local_get, 0, OP.i64_load8_u, ...memarg(0), OP.i64_xor,
+      OP.i64_const, ...lebS64(FNV_PRIME), OP.i64_mul, OP.local_set, 2,
+      OP.local_get, 0, OP.i32_const, 1, OP.i32_add, OP.local_set, 0,
+      OP.br, 0,
+      OP.end,
+      OP.end,
+      OP.local_get, 2,
+    ],
+  );
+
+  // count_frames(ptr, len) -> i32 : size-prefixed frame count; zero-length
+  // prefixes skipped as padding; malformed framing returns -1.
+  // locals: 2 = count (i32), 3 = end (i32), 4 = frameSize (i32)
+  const countFrames = func(
+    [[3, I32]],
+    [
+      OP.local_get, 0, OP.local_get, 1, OP.i32_add, OP.local_set, 3,
+      OP.block, OP.void,
+      OP.loop, OP.void,
+      OP.local_get, 0, OP.local_get, 3, OP.i32_ge_u, OP.br_if, 1,
+      // if (end - ptr < 4) return -1
+      OP.local_get, 3, OP.local_get, 0, OP.i32_sub, OP.i32_const, 4, OP.i32_lt_u,
+      OP.if, OP.void, OP.i32_const, ...lebS32(-1), OP.return, OP.end,
+      OP.local_get, 0, OP.i32_load, ...memarg(0), OP.local_set, 4,
+      OP.local_get, 0, OP.i32_const, 4, OP.i32_add, OP.local_set, 0,
+      // if (frameSize == 0) continue
+      OP.local_get, 4, OP.i32_eqz, OP.br_if, 0,
+      // if (frameSize > end - ptr) return -1
+      OP.local_get, 4, OP.local_get, 3, OP.local_get, 0, OP.i32_sub, OP.i32_gt_u,
+      OP.if, OP.void, OP.i32_const, ...lebS32(-1), OP.return, OP.end,
+      OP.local_get, 0, OP.local_get, 4, OP.i32_add, OP.local_set, 0,
+      OP.local_get, 2, OP.i32_const, 1, OP.i32_add, OP.local_set, 2,
+      OP.br, 0,
+      OP.end,
+      OP.end,
+      OP.local_get, 2,
+    ],
+  );
+
+  const bytes = [
+    0x00, 0x61, 0x73, 0x6d, // \0asm
+    0x01, 0x00, 0x00, 0x00, // version 1
+    ...section(1, vec(types)),
+    ...section(2, vec(imports)),
+    ...section(3, vec(funcTypes.map((t) => lebU(t)))),
+    ...section(7, vec(exports)),
+    ...section(10, vec([peek8, peek32, peek64, poke8, poke32, fnv, countFrames])),
+  ];
+  return new Uint8Array(bytes);
+}
+
+/** The shim module bytes (assembled once at import). */
+export const FLATSQL_LINK_SHIM_WASM = buildFlatsqlLinkShimWasm();
+
+/** Import-module names the linked flow artifact resolves against. */
+export const FLATSQL_ENGINE_IMPORT_MODULE = "flatsql";
+export const FLATSQL_LINK_IMPORT_MODULE = "flatsql_link";
+
+/**
+ * Engine body-reference tokens minted by linked flow artifacts carry this
+ * magic in their high 32 bits ("SDNE"); hostcall-bridge tokens are small
+ * counters, so the namespaces can never collide.
+ */
+export const ENGINE_BODY_REF_TOKEN_MAGIC = 0x53444e45n << 32n;
+
+export function isEngineBodyRefToken(token) {
+  return (BigInt(token) & 0xffffffff00000000n) === ENGINE_BODY_REF_TOKEN_MAGIC;
+}
+
+/**
+ * Instantiate the shim against a live engine's exports. `engineExports` must
+ * expose the engine `memory`.
+ */
+export async function instantiateFlatsqlLinkShim(engineExports) {
+  const { instance } = await WebAssembly.instantiate(FLATSQL_LINK_SHIM_WASM.slice().buffer, {
+    [FLATSQL_ENGINE_IMPORT_MODULE]: { memory: engineExports.memory },
+  });
+  return instance;
+}
+
+/**
+ * Byte layout of one engine body-reference table entry exported by linked
+ * flow artifacts (sdn_flatsql_link_ref_table). Mirrors flow_runtime.cpp's
+ * SdnEngineRefEntry exactly (little-endian).
+ */
+export const ENGINE_REF_ENTRY_SIZE = 40;
+
+export function readEngineRefEntry(view, base) {
+  return {
+    token: view.getBigUint64(base + 0, true),
+    generation: view.getBigUint64(base + 8, true),
+    fnv1a64: view.getBigUint64(base + 16, true),
+    enginePtr: view.getUint32(base + 24, true),
+    size: view.getUint32(base + 28, true),
+    frames: view.getUint32(base + 32, true),
+    used: view.getUint32(base + 36, true),
+  };
+}