space-data-module-sdk 0.5.15 → 0.5.18

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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.5.15",
+  "version": "0.5.18",
   "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,10 @@
     "./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"
+    },
     "./testing": "./src/testing/index.js",
     "./standards": "./src/standards/index.js",
     "./schemas/*": "./schemas/*"
@@ -50,15 +54,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/bundle/codec.js

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

package/src/compliance/pluginCompliance.js

@@ -366,7 +366,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";

package/src/index.d.ts

@@ -258,6 +258,144 @@ export function loadComplianceConfig(
   rootDirectory: string,
 ): Promise<{ path: string; config: Record<string, unknown> } | null>;
 export function getWasmExportNames(wasmBytes: Uint8Array): string[];
+
+// --- Runtime Host ---
+
+export interface RowHandle {
+  schemaFileId: string;
+  rowId: number;
+}
+
+export interface RuntimeRowView {
+  handle: RowHandle;
+  payload: unknown;
+}
+
+export interface RuntimeRowQueryResult {
+  columns: string[];
+  rows: unknown[][];
+  rowCount: number;
+}
+
+export interface FlatSqlRuntimeStore {
+  appendRow(options: { schemaFileId: string; payload?: unknown }): RowHandle;
+  listRows(schemaFileId?: string | null): RuntimeRowView[];
+  query(sql: string): RuntimeRowQueryResult;
+  resolveRow(handle: RowHandle): RuntimeRowView | null;
+}
+
+export interface RuntimeRegionDescriptor {
+  regionId: number;
+  layoutId: string;
+  recordByteLength: number;
+  alignment: number;
+  recordCount: number;
+}
+
+export interface RuntimeRegionRecord {
+  regionId: number;
+  recordIndex: number;
+  layoutId: string;
+  recordByteLength: number;
+  alignment: number;
+  byteLength: number;
+  bytes: Uint8Array;
+}
+
+export interface RuntimeRegionExternalRecordView {
+  regionId: number;
+  recordIndex: number;
+  layoutId: string;
+  recordByteLength: number;
+  alignment: number;
+  byteOffset?: number;
+  buffer?: ArrayBufferLike;
+  elementType?: string;
+  elementCount?: number;
+  strideElements?: number;
+  [key: string]: unknown;
+}
+
+export interface RuntimeRegionRecordViewRequest {
+  regionId: number;
+  recordIndex: number;
+}
+
+export interface RuntimeRegionStore {
+  allocateRegion(options: {
+    layoutId: string;
+    recordByteLength: number;
+    alignment?: number;
+    initialRecords?: Array<Uint8Array | ArrayBuffer | ArrayBufferView | null | undefined>;
+  }): RuntimeRegionDescriptor;
+  registerExternalRegion(options: {
+    layoutId: string;
+    recordByteLength: number;
+    alignment?: number;
+    recordCount?: number;
+    getRecordCount?: (regionId: number) => number;
+    resolveRecordView?: (query: {
+      regionId: number;
+      recordIndex: number;
+      layoutId: string;
+      recordByteLength: number;
+      alignment: number;
+    }) =>
+      | Omit<
+          RuntimeRegionExternalRecordView,
+          "regionId" | "recordIndex" | "layoutId" | "recordByteLength" | "alignment"
+        >
+      | null
+      | undefined;
+  }): RuntimeRegionDescriptor;
+  setRegionRecordCount(regionId: number, recordCount: number): RuntimeRegionDescriptor | null;
+  describeRegion(regionId: number): RuntimeRegionDescriptor | null;
+  resolveRecord(options: RuntimeRegionRecordViewRequest): RuntimeRegionRecord | null;
+  resolveRecordView(
+    options: RuntimeRegionRecordViewRequest,
+  ): RuntimeRegionRecord | RuntimeRegionExternalRecordView | null;
+}
+
+export interface InstalledRuntimeModule {
+  moduleId: string;
+  metadata: unknown;
+  methodIds: string[];
+}
+
+export interface RuntimeModuleRegistry {
+  installModule(definition: {
+    moduleId: string;
+    methods?: Record<string, (...args: unknown[]) => unknown>;
+    metadata?: unknown;
+  }): InstalledRuntimeModule;
+  invokeModule(
+    moduleId: string,
+    methodId: string,
+    ...args: unknown[]
+  ): Promise<unknown>;
+  listModules(): InstalledRuntimeModule[];
+  loadModule(moduleId: string): {
+    moduleId: string;
+    methods: Record<string, (...args: unknown[]) => unknown>;
+    metadata: unknown;
+  } | null;
+  unloadModule(moduleId: string): boolean;
+}
+
+export interface RuntimeHost {
+  rows: FlatSqlRuntimeStore;
+  regions: RuntimeRegionStore;
+  moduleRegistry: RuntimeModuleRegistry;
+}
+
+export function createFlatSqlRuntimeStore(): FlatSqlRuntimeStore;
+export function createRuntimeRegionStore(): RuntimeRegionStore;
+export function createModuleRegistry(): RuntimeModuleRegistry;
+export function createRuntimeHost(options?: {
+  rows?: FlatSqlRuntimeStore;
+  regions?: RuntimeRegionStore;
+  moduleRegistry?: RuntimeModuleRegistry;
+}): RuntimeHost;
 export function getWasmExportNamesFromFile(wasmPath: string): Promise<string[]>;
 
 // --- Auth ---
@@ -678,6 +816,7 @@ export {
   createPublicationProtectionDemoSummary,
   createModuleHarness,
   createPluginInvokeProcessClient,
+  createWasmEdgeStreamProcessClient,
   describeCapabilityRuntimeSurface,
   generateManifestHarnessPlan,
   materializeHarnessScenario,

package/src/index.js

@@ -7,6 +7,7 @@ export * from "./bundle/index.js";
 export * from "./capabilities.js";
 export * from "./standards/index.js";
 export * from "./host/index.js";
+export * from "./runtime-host/index.js";
 export * from "./invoke/index.js";
 export * from "./testing/index.js";
 export * from "./deployment/index.js";

package/src/invoke/codec.js

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

package/src/manifest/codec.js

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

package/src/manifest/typeRefs.js

@@ -1,31 +1,62 @@
 function cloneSchemaHash(value) {
   if (value instanceof Uint8Array) {
-    return new Uint8Array(value);
+    return value.byteLength > 0 ? new Uint8Array(value) : undefined;
   }
   if (Array.isArray(value)) {
-    return [...value];
+    return value.length > 0 ? [...value] : undefined;
   }
   return value ?? undefined;
 }
 
+function normalizeNullableString(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const normalized = String(value).trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function normalizeAlignedMetadataScalar(value) {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  const numeric = Number(value);
+  if (Number.isFinite(numeric)) {
+    return numeric === 0 ? undefined : numeric;
+  }
+  return value;
+}
+
 export function clonePayloadTypeRef(value = null) {
   if (!value || typeof value !== "object") {
-    return { acceptsAnyFlatbuffer: true };
+    return { acceptsAnyFlatbuffer: true, fileIdentifier: null };
   }
   return {
-    schemaName: value.schemaName ?? value.schema_name ?? undefined,
-    fileIdentifier: value.fileIdentifier ?? value.file_identifier ?? undefined,
+    schemaName: normalizeNullableString(
+      value.schemaName ?? value.schema_name,
+    ),
+    fileIdentifier: normalizeNullableString(
+      value.fileIdentifier ?? value.file_identifier,
+    ),
     schemaHash: cloneSchemaHash(value.schemaHash ?? value.schema_hash),
     acceptsAnyFlatbuffer: Boolean(
       value.acceptsAnyFlatbuffer ?? value.accepts_any_flatbuffer ?? false,
     ),
-    wireFormat: value.wireFormat ?? value.wire_format ?? undefined,
-    rootTypeName: value.rootTypeName ?? value.root_type_name ?? undefined,
-    fixedStringLength:
-      value.fixedStringLength ?? value.fixed_string_length ?? undefined,
-    byteLength: value.byteLength ?? value.byte_length ?? undefined,
-    requiredAlignment:
-      value.requiredAlignment ?? value.required_alignment ?? undefined,
+    wireFormat: normalizePayloadWireFormatName(
+      value.wireFormat ?? value.wire_format,
+    ),
+    rootTypeName: normalizeNullableString(
+      value.rootTypeName ?? value.root_type_name,
+    ),
+    fixedStringLength: normalizeAlignedMetadataScalar(
+      value.fixedStringLength ?? value.fixed_string_length,
+    ),
+    byteLength: normalizeAlignedMetadataScalar(
+      value.byteLength ?? value.byte_length,
+    ),
+    requiredAlignment: normalizeAlignedMetadataScalar(
+      value.requiredAlignment ?? value.required_alignment,
+    ),
   };
 }
 
@@ -33,6 +64,12 @@ export function normalizePayloadWireFormatName(value) {
   if (value === undefined || value === null || value === "") {
     return null;
   }
+  if (value === 1 || value === "1") {
+    return "aligned-binary";
+  }
+  if (value === 0 || value === "0") {
+    return "flatbuffer";
+  }
   const normalized = String(value).trim().toLowerCase().replace(/_/g, "-");
   if (normalized === "aligned-binary") {
     return "aligned-binary";