space-data-module-sdk 0.5.15 → 0.5.19

package/README.md

@@ -14,6 +14,8 @@ This repository is the source of truth for module-level concerns:
 - the `sds.bundle` single-file container
 - deployment authorization plus SDS publication records (`REC`, `PNM`, `ENC`)
 - the first canonical module hostcall/import ABI surface
+- the canonical runtime-host model for append-only standards rows, host-managed
+  runtime regions, and dynamic module installation/loading
 - shared module-level testing/runtime harnesses, including the WasmEdge
   process runner used by package-level validation suites
 
@@ -36,6 +38,28 @@ specific validation suites, including conjunction replay/V&V, are expected to
 sit on top of these shared harnesses instead of defining their own runtime
 process model.
 
+## Canonical Runtime Host
+
+The SDK now owns the durable runtime identity model used by OrbPro, browser and
+server SDN hosts, and the evolving WasmEdge harness:
+
+- standards rows are addressed only by `($SCHEMA_FILE_ID, rowId)`
+- `rowId` is append-only and never reused
+- aligned-binary runtime state is addressed only by `(regionId, recordIndex)`
+- raw pointers remain internal execution details and are not durable APIs
+
+The minimal host surface lives under `src/runtime-host/` and covers three
+responsibilities:
+
+- `createFlatSqlRuntimeStore()` for append-only row handles and row resolution
+- `createRuntimeRegionStore()` for host-allocated aligned-binary regions and
+  externally backed record-view descriptors
+- `createModuleRegistry()` for dynamic install/load/unload/invoke
+
+`createRuntimeHost()` composes those stores into the canonical SDK host model.
+OrbPro layers entity/view helpers on top of that host instead of inventing a
+separate durable identity model.
+
 ## Module Artifact Model
 
 A compliant module built with this SDK is always a valid `.wasm` artifact with:
@@ -165,6 +189,11 @@ the preferred server-side target when the guest needs network-oriented runtime
 features such as sockets or TLS. Plain `wasi` remains the strict portability
 baseline; `wasmedge` is the practical higher-capability target.
 
+If a manifest declares `runtimeTargets: ["browser", "wasmedge"]`, this SDK
+treats that as the explicit "one binary for both" profile. That pair now
+defaults to a shared `single-thread` artifact so the compiled wasm can be loaded
+unchanged by the browser harness and the WasmEdge harness.
+
 ## WasmEdge Pthreads
 
 `space-data-module-sdk` is also the source of truth for module thread-model
@@ -173,6 +202,7 @@ selection.
 - `compileModuleFromSource({ threadModel })` accepts an explicit thread model.
 - If `threadModel` is omitted, the SDK resolves it from `manifest.runtimeTargets`.
 - `runtimeTargets: ["wasmedge"]` defaults to `emscripten-pthreads`.
+- `runtimeTargets: ["browser", "wasmedge"]` defaults to `single-thread`.
 - Other targets currently default to `single-thread`.
 
 WasmEdge-targeted pthread builds do not use the embedded `sdn-emception`
@@ -190,11 +220,32 @@ If a runtime cannot interoperate with the guest pthread contract directly,
 document that as a wrapper requirement instead of changing the guest artifact
 semantics.
 
+## Browser + WasmEdge Isomorphism
+
+The supported isomorphic profile and browser edge shims are documented in
+[`docs/browser-wasmedge-isomorphic.md`](./docs/browser-wasmedge-isomorphic.md).
+
+The checked-in same-artifact demo lives in
+[`examples/isomorphic-loader`](./examples/isomorphic-loader):
+
+- [`build-demo.mjs`](./examples/isomorphic-loader/build-demo.mjs) compiles the
+  shared artifact
+- [`browser-demo.html`](./examples/isomorphic-loader/browser-demo.html) and
+  [`browser-demo.mjs`](./examples/isomorphic-loader/browser-demo.mjs) load that
+  artifact in the browser harness with browser edge shims
+- [`wasmedge-demo.mjs`](./examples/isomorphic-loader/wasmedge-demo.mjs) loads
+  that same artifact in WasmEdge
+
 ## Testing
 
 This repo now exposes a manifest-driven harness generator from
 `space-data-module-sdk/testing` and two complementary integration suites:
 
+- browser/isomorphic helpers:
+  - `createBrowserModuleHarness(...)`
+  - `detectArtifactProfile(...)`
+  - `loadModule(...)`
+
 - shared process-level helpers for command-surface runtimes:
   - `createPluginInvokeProcessClient(...)`
   - `resolveWasmEdgePluginLaunchPlan(...)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.5.15",
+  "version": "0.5.19",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
   "types": "./src/index.d.ts",
@@ -31,6 +31,15 @@
     "./deployment": "./src/deployment/index.js",
     "./invoke": "./src/invoke/index.js",
     "./runtime": "./src/runtime/index.js",
+    "./runtime-host": {
+      "types": "./src/index.d.ts",
+      "default": "./src/runtime-host/index.js"
+    },
+    "./host/browser": "./src/host/browserHost.js",
+    "./host/browser-edge-shims": "./src/host/browserEdgeShims.js",
+    "./host/wasi-shim": "./src/host/wasiShim.js",
+    "./host/isomorphic": "./src/host/isomorphicLoader.js",
+    "./testing/browser": "./src/testing/browserModuleHarness.js",
     "./testing": "./src/testing/index.js",
     "./standards": "./src/standards/index.js",
     "./schemas/*": "./schemas/*"
@@ -50,15 +59,15 @@
     "prepublishOnly": "npm test && npm run check:compliance"
   },
   "dependencies": {
-    "flatc-wasm": "25.12.19-wasm.43",
     "flatbuffers": "^25.9.23",
+    "flatc-wasm": "25.12.19-wasm.43",
+    "flatsql": "^0.4.0",
     "hd-wallet-wasm": "1.6.0",
     "sdn-emception": "1.0.0",
     "spacedatastandards.org": "git+https://github.com/DigitalArsenal/spacedatastandards.org.git#09af351a1"
   },
   "devDependencies": {
-    "express": "^4.21.2",
-    "flatsql": "^0.4.0"
+    "express": "^4.21.2"
   },
   "engines": {
     "node": ">=20.0.0"

package/schemas/HostStorageAbi.fbs

@@ -0,0 +1,53 @@
+namespace orbpro.hoststorage;
+
+table RowHandle {
+  schema_file_id: string (required);
+  row_id: uint64;
+}
+
+table RuntimeRegionRecord {
+  region_id: uint64;
+  record_index: uint32;
+  layout_id: string (required);
+  record_byte_length: uint32;
+  byte_length: uint32;
+  alignment: uint16 = 1;
+  bytes: [ubyte];
+}
+
+table ResolveRowViewRequest {
+  handle: RowHandle;
+}
+
+table ResolveRowViewResult {
+  handle: RowHandle;
+  found: bool = false;
+}
+
+table ResolveRegionRecordRequest {
+  region_id: uint64;
+  record_index: uint32;
+}
+
+table ResolveRegionRecordResult {
+  record: RuntimeRegionRecord;
+  found: bool = false;
+}
+
+table AllocateRuntimeRegionRequest {
+  layout_id: string (required);
+  record_byte_length: uint32;
+  alignment: uint16 = 1;
+  initial_record_count: uint32;
+}
+
+table AllocateRuntimeRegionResult {
+  region_id: uint64;
+  layout_id: string (required);
+  record_byte_length: uint32;
+  alignment: uint16 = 1;
+  record_count: uint32;
+}
+
+root_type ResolveRowViewRequest;
+file_identifier "HSTR";

package/src/browser.js

@@ -6,3 +6,9 @@ export * from "./capabilities.js";
 export * from "./deployment/index.js";
 export * from "./invoke/index.js";
 export * from "./runtime/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";

package/src/bundle/codec.js

@@ -1,4 +1,4 @@
-import * as flatbuffers from "flatbuffers";
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 
 import {
   CanonicalizationRuleT,

package/src/compiler/compileModule.js

@@ -142,6 +142,9 @@ function resolveThreadModel({ manifest, threadModel } = {}) {
         .map((target) => String(target ?? "").trim().toLowerCase())
         .filter(Boolean)
     : [];
+  if (runtimeTargets.includes(RuntimeTarget.BROWSER)) {
+    return ModuleThreadModel.SINGLE_THREAD;
+  }
   if (runtimeTargets.includes(RuntimeTarget.WASMEDGE)) {
     return ModuleThreadModel.EMSCRIPTEN_PTHREADS;
   }

package/src/compliance/pluginCompliance.js

@@ -30,7 +30,6 @@ const ExternalInterfaceKindSet = new Set(Object.values(ExternalInterfaceKind));
 const ProtocolRoleSet = new Set(Object.values(ProtocolRole));
 const ProtocolTransportKindSet = new Set(Object.values(ProtocolTransportKind));
 const BrowserIncompatibleCapabilitySet = new Set([
-  "filesystem",
   "pipe",
   "network",
   "tcp",
@@ -366,7 +365,7 @@ function validateAllowedType(type, issues, location) {
       "Allowed type fixedStringLength",
       { min: 0 },
     );
-    validateIntegerField(
+    validateOptionalIntegerField(
       issues,
       type.byteLength,
       `${location}.byteLength`,

package/src/generated/orbpro/invoke/plugin-invoke-request.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from 'flatbuffers';
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 import { TypedArenaBuffer } from '../../orbpro/stream/typed-arena-buffer.js';
 /**
  * Canonical invoke envelope consumed by direct ABI and command-mode execution.

package/src/generated/orbpro/invoke/plugin-invoke-response.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from 'flatbuffers';
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 import { TypedArenaBuffer } from '../../orbpro/stream/typed-arena-buffer.js';
 /**
  * Canonical invoke result emitted by direct ABI and command-mode execution.

package/src/generated/orbpro/manifest/accepted-type-set.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from "flatbuffers";
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 import { FlatBufferTypeRef, } from "../../orbpro/stream/flat-buffer-type-ref.js";
 /**
  * Accepted schema family for a port.

package/src/generated/orbpro/manifest/build-artifact.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from "flatbuffers";
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 /**
  * Build artifact emitted by the plugin toolchain.
  */

package/src/generated/orbpro/manifest/host-capability.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from "flatbuffers";
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 import { CapabilityKind } from "../../orbpro/manifest/capability-kind.js";
 /**
  * One host capability dependency.

package/src/generated/orbpro/manifest/method-manifest.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from "flatbuffers";
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 import { DrainPolicy } from "../../orbpro/manifest/drain-policy.js";
 import { PortManifest, } from "../../orbpro/manifest/port-manifest.js";
 /**

package/src/generated/orbpro/manifest/plugin-manifest.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from 'flatbuffers';
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 import { BuildArtifact } from '../../orbpro/manifest/build-artifact.js';
 import { HostCapability } from '../../orbpro/manifest/host-capability.js';
 import { MethodManifest } from '../../orbpro/manifest/method-manifest.js';

package/src/generated/orbpro/manifest/port-manifest.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from "flatbuffers";
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 import { AcceptedTypeSet, } from "../../orbpro/manifest/accepted-type-set.js";
 /**
  * One input or output port on a method.

package/src/generated/orbpro/manifest/protocol-spec.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from "flatbuffers";
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 /**
  * Protocol handler declared by a plugin.
  */

package/src/generated/orbpro/manifest/timer-spec.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from "flatbuffers";
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 /**
  * Timer entry declared by a plugin.
  */

package/src/generated/orbpro/module/canonicalization-rule.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from 'flatbuffers';
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 /**
  * Canonicalization rule applied before hashing or signature verification.
  */

package/src/generated/orbpro/module/module-bundle-entry.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from 'flatbuffers';
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 import { ModuleBundleEntryRole } from '../../orbpro/module/module-bundle-entry-role.js';
 import { ModulePayloadEncoding } from '../../orbpro/module/module-payload-encoding.js';
 import { FlatBufferTypeRef } from '../../orbpro/stream/flat-buffer-type-ref.js';

package/src/generated/orbpro/module/module-bundle.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from 'flatbuffers';
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 import { CanonicalizationRule } from '../../orbpro/module/canonicalization-rule.js';
 import { ModuleBundleEntry } from '../../orbpro/module/module-bundle-entry.js';
 /**

package/src/generated/orbpro/stream/flat-buffer-type-ref.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from "flatbuffers";
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 import { PayloadWireFormat } from "../../orbpro/stream/payload-wire-format.js";
 function normalizePayloadWireFormat(value) {
     if (value === PayloadWireFormat.ALIGNED_BINARY) {

package/src/generated/orbpro/stream/typed-arena-buffer.js

@@ -1,6 +1,6 @@
 // automatically generated by the FlatBuffers compiler, do not modify
 /* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
-import * as flatbuffers from "flatbuffers";
+import * as flatbuffers from "flatbuffers/mjs/flatbuffers.js";
 import { BufferMutability } from "../../orbpro/stream/buffer-mutability.js";
 import { BufferOwnership } from "../../orbpro/stream/buffer-ownership.js";
 import { FlatBufferTypeRef, } from "../../orbpro/stream/flat-buffer-type-ref.js";