space-data-module-sdk 0.5.14 → 0.5.18

package/src/index.d.ts

@@ -11,7 +11,7 @@ export type ProtocolRoleName = "handle" | "dial" | "both";
 
 export interface PayloadTypeRef {
   schemaName?: string;
-  fileIdentifier?: string | null;
+  fileIdentifier?: string;
   schemaHash?: string | number[] | Uint8Array;
   acceptsAnyFlatbuffer?: boolean;
   wireFormat?: PayloadWireFormat;
@@ -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 ---
@@ -662,12 +800,30 @@ export type {
   HarnessInvokeScenario,
   HarnessRawScenario,
   ManifestHarnessPlan,
+  ModuleHarness,
+  ModuleHarnessRuntimeDescriptor,
+  PublicationProtectionDemoAlignedType,
+  PublicationProtectionDemoSummary,
+  PluginInvokeProcessClient,
+  PluginInvokeProcessLaunchPlan,
+  WasmEdgeRunnerBuildPlan,
 } from "./testing/index.js";
 
 export {
+  buildWasmEdgeEmscriptenPthreadRunner,
+  buildWasmEdgeSpawnEnv,
+  createPublicationProtectionDemoManifest,
+  createPublicationProtectionDemoSummary,
+  createModuleHarness,
+  createPluginInvokeProcessClient,
+  createWasmEdgeStreamProcessClient,
   describeCapabilityRuntimeSurface,
   generateManifestHarnessPlan,
   materializeHarnessScenario,
+  resolveModuleHarnessLaunchPlan,
+  resolveWasmEdgeRunnerBuildPlan,
+  resolveWasmEdgeRunnerSourcePath,
+  resolveWasmEdgePluginLaunchPlan,
   serializeHarnessPlan,
 } from "./testing/index.js";
 

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,
@@ -12,7 +12,7 @@ import { InvokeSurface } from "../generated/orbpro/manifest/invoke-surface.js";
 import { BufferMutability } from "../generated/orbpro/stream/buffer-mutability.js";
 import { BufferOwnership } from "../generated/orbpro/stream/buffer-ownership.js";
 import { FlatBufferTypeRefT } from "../generated/orbpro/stream/flat-buffer-type-ref.js";
-import { TypedArenaBuffer, TypedArenaBufferT } from "../generated/orbpro/stream/typed-arena-buffer.js";
+import { TypedArenaBufferT } from "../generated/orbpro/stream/typed-arena-buffer.js";
 import { toUint8Array } from "../runtime/bufferLike.js";
 
 function toByteBuffer(data) {
@@ -149,20 +149,22 @@ function normalizeArenaFrame(frame = {}, offset) {
 
 function packArenaFrames(frames = []) {
   const packedFrames = [];
-  const arena = [];
+  const normalizedFrames = [];
   let offset = 0;
   for (const frame of frames) {
     const normalized = normalizeArenaFrame(frame, offset);
-    for (let index = 0; index < normalized.padding; index += 1) {
-      arena.push(0);
-    }
-    arena.push(...normalized.payload);
     offset = normalized.buffer.offset + normalized.buffer.size;
     packedFrames.push(normalized.buffer);
+    normalizedFrames.push(normalized);
+  }
+
+  const arena = new Uint8Array(offset);
+  for (const normalized of normalizedFrames) {
+    arena.set(normalized.payload, normalized.buffer.offset);
   }
   return {
     frames: packedFrames,
-    arena: Uint8Array.from(arena),
+    arena,
   };
 }
 

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/runtime-host/flatsqlRuntimeStore.js

@@ -0,0 +1,217 @@
+import { DirectAccessor, FlatSQLDatabase } from "flatsql";
+
+const RUNTIME_ROW_TABLE = "RuntimeHostRow";
+const RUNTIME_ROW_SCHEMA = `
+table RuntimeHostRow {
+  schemaFileId: string;
+  rowId: ulong;
+  payloadJson: string;
+}
+`;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function clonePayload(payload) {
+  if (payload === null || payload === undefined) {
+    return payload ?? null;
+  }
+  if (typeof structuredClone === "function") {
+    return structuredClone(payload);
+  }
+  if (ArrayBuffer.isView(payload)) {
+    return payload.slice(0);
+  }
+  if (payload instanceof ArrayBuffer) {
+    return payload.slice(0);
+  }
+  if (typeof payload === "object") {
+    return JSON.parse(JSON.stringify(payload));
+  }
+  return payload;
+}
+
+function normalizeSchemaFileId(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError("schemaFileId must be a non-empty string");
+  }
+  return value.trim();
+}
+
+function normalizeRowHandle(handle) {
+  if (!handle || typeof handle !== "object") {
+    throw new TypeError("row handle is required");
+  }
+  const schemaFileId = normalizeSchemaFileId(handle.schemaFileId);
+  const rowId = Number(handle.rowId);
+  if (!Number.isInteger(rowId) || rowId <= 0) {
+    throw new TypeError("rowId must be a positive integer");
+  }
+  return { schemaFileId, rowId };
+}
+
+function escapeSqlStringLiteral(value) {
+  return String(value).replaceAll("'", "''");
+}
+
+function serializePayload(payload) {
+  if (payload === null || payload === undefined) {
+    return {
+      kind: "json",
+      value: null,
+    };
+  }
+  if (ArrayBuffer.isView(payload)) {
+    return {
+      kind: "bytes",
+      bytes: Array.from(
+        new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength),
+      ),
+    };
+  }
+  if (payload instanceof ArrayBuffer) {
+    return {
+      kind: "bytes",
+      bytes: Array.from(new Uint8Array(payload)),
+    };
+  }
+  return {
+    kind: "json",
+    value: clonePayload(payload),
+  };
+}
+
+function deserializePayload(payloadJson) {
+  const payload = JSON.parse(String(payloadJson ?? "null"));
+  if (payload?.kind === "bytes") {
+    return Uint8Array.from(payload.bytes ?? []);
+  }
+  if (payload?.kind === "json") {
+    return clonePayload(payload.value);
+  }
+  return clonePayload(payload);
+}
+
+function createRuntimeRowAccessor() {
+  const accessor = new DirectAccessor();
+  accessor.registerAccessor(RUNTIME_ROW_TABLE, (data, path) => {
+    const row = JSON.parse(decoder.decode(data));
+    let current = row;
+    for (const segment of Array.isArray(path) ? path : []) {
+      if (current === null || current === undefined) {
+        return null;
+      }
+      current = current[segment];
+    }
+    return current ?? null;
+  });
+  accessor.registerBuilder(RUNTIME_ROW_TABLE, (fields) =>
+    encoder.encode(
+      JSON.stringify({
+        schemaFileId: normalizeSchemaFileId(fields.schemaFileId),
+        rowId: Number(fields.rowId),
+        payloadJson: String(fields.payloadJson ?? "null"),
+      }),
+    ),
+  );
+  return accessor;
+}
+
+function cloneQueryResult(result) {
+  return {
+    columns: Array.from(result?.columns ?? []),
+    rows: (result?.rows ?? []).map((row) =>
+      Array.isArray(row) ? row.map((value) => clonePayload(value)) : row,
+    ),
+    rowCount: Number(result?.rowCount ?? 0),
+  };
+}
+
+function rowViewFromQueryRow(row) {
+  return {
+    handle: {
+      schemaFileId: String(row[0]),
+      rowId: Number(row[1]),
+    },
+    payload: deserializePayload(row[2]),
+  };
+}
+
+export function createFlatSqlRuntimeStore(options = {}) {
+  const accessor = options.accessor ?? createRuntimeRowAccessor();
+  const database =
+    options.database ??
+    FlatSQLDatabase.fromSchema(
+      RUNTIME_ROW_SCHEMA,
+      accessor,
+      options.databaseName ?? "runtime-host",
+    );
+  const nextRowIdBySchema = new Map();
+  const existingRows = database.query(
+    `SELECT schemaFileId, rowId FROM ${RUNTIME_ROW_TABLE} ORDER BY schemaFileId, rowId`,
+  );
+  for (const row of existingRows.rows ?? []) {
+    const schemaFileId = normalizeSchemaFileId(row[0]);
+    const rowId = Number(row[1]);
+    if (Number.isInteger(rowId) && rowId > 0) {
+      nextRowIdBySchema.set(
+        schemaFileId,
+        Math.max(nextRowIdBySchema.get(schemaFileId) ?? 0, rowId),
+      );
+    }
+  }
+
+  function appendRow({ schemaFileId, payload = null }) {
+    const normalizedSchemaFileId = normalizeSchemaFileId(schemaFileId);
+    const nextRowId = (nextRowIdBySchema.get(normalizedSchemaFileId) ?? 0) + 1;
+    nextRowIdBySchema.set(normalizedSchemaFileId, nextRowId);
+    database.insert(RUNTIME_ROW_TABLE, {
+      schemaFileId: normalizedSchemaFileId,
+      rowId: nextRowId,
+      payloadJson: JSON.stringify(serializePayload(payload)),
+    });
+    return {
+      schemaFileId: normalizedSchemaFileId,
+      rowId: nextRowId,
+    };
+  }
+
+  function resolveRow(handle) {
+    const normalizedHandle = normalizeRowHandle(handle);
+    return (
+      listRows(normalizedHandle.schemaFileId).find(
+        (row) => row.handle.rowId === normalizedHandle.rowId,
+      ) ?? null
+    );
+  }
+
+  function listRows(schemaFileId = null) {
+    const normalizedSchemaFileId =
+      schemaFileId === null || schemaFileId === undefined
+        ? null
+        : normalizeSchemaFileId(schemaFileId);
+    const result =
+      normalizedSchemaFileId === null
+        ? database.query(
+            `SELECT schemaFileId, rowId, payloadJson FROM ${RUNTIME_ROW_TABLE} ORDER BY schemaFileId, rowId`,
+          )
+        : database.query(
+            `SELECT schemaFileId, rowId, payloadJson FROM ${RUNTIME_ROW_TABLE} WHERE schemaFileId = '${escapeSqlStringLiteral(normalizedSchemaFileId)}' ORDER BY rowId`,
+          );
+    return (result.rows ?? []).map(rowViewFromQueryRow);
+  }
+
+  function query(sql) {
+    if (typeof sql !== "string" || sql.trim().length === 0) {
+      throw new TypeError("sql must be a non-empty string");
+    }
+    return cloneQueryResult(database.query(sql));
+  }
+
+  return {
+    appendRow,
+    listRows,
+    query,
+    resolveRow,
+  };
+}

package/src/runtime-host/index.js

@@ -0,0 +1,21 @@
+import { createFlatSqlRuntimeStore } from "./flatsqlRuntimeStore.js";
+import { createRuntimeRegionStore } from "./runtimeRegionStore.js";
+import { createModuleRegistry } from "./moduleRegistry.js";
+
+export function createRuntimeHost(options = {}) {
+  const rows = options.rows ?? createFlatSqlRuntimeStore();
+  const regions = options.regions ?? createRuntimeRegionStore();
+  const moduleRegistry = options.moduleRegistry ?? createModuleRegistry();
+
+  return {
+    rows,
+    regions,
+    moduleRegistry,
+  };
+}
+
+export {
+  createFlatSqlRuntimeStore,
+  createModuleRegistry,
+  createRuntimeRegionStore,
+};

package/src/runtime-host/moduleRegistry.js

@@ -0,0 +1,92 @@
+function normalizeModuleId(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError("moduleId must be a non-empty string");
+  }
+  return value.trim();
+}
+
+function cloneMetadata(value) {
+  if (value === null || value === undefined) {
+    return value ?? null;
+  }
+  if (typeof structuredClone === "function") {
+    return structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
+function toPublicModuleRecord(moduleRecord) {
+  return {
+    moduleId: moduleRecord.moduleId,
+    metadata: cloneMetadata(moduleRecord.metadata),
+    methodIds: Object.keys(moduleRecord.methods),
+  };
+}
+
+export function createModuleRegistry() {
+  const modules = new Map();
+
+  function installModule(definition) {
+    if (!definition || typeof definition !== "object") {
+      throw new TypeError("module definition is required");
+    }
+    const moduleId = normalizeModuleId(definition.moduleId);
+    const moduleRecord = {
+      moduleId,
+      methods: {
+        ...(definition.methods ?? {}),
+      },
+      metadata: cloneMetadata(definition.metadata),
+    };
+    modules.set(moduleId, moduleRecord);
+    return toPublicModuleRecord(moduleRecord);
+  }
+
+  function loadModule(moduleId) {
+    const moduleRecord = modules.get(normalizeModuleId(moduleId));
+    if (!moduleRecord) {
+      return null;
+    }
+    return {
+      moduleId: moduleRecord.moduleId,
+      methods: {
+        ...moduleRecord.methods,
+      },
+      metadata: cloneMetadata(moduleRecord.metadata),
+    };
+  }
+
+  function unloadModule(moduleId) {
+    return modules.delete(normalizeModuleId(moduleId));
+  }
+
+  function listModules() {
+    return Array.from(modules.values(), toPublicModuleRecord);
+  }
+
+  async function invokeModule(moduleId, methodId, ...args) {
+    const moduleRecord = modules.get(normalizeModuleId(moduleId));
+    if (!moduleRecord) {
+      throw new Error(`Unknown module: ${moduleId}`);
+    }
+    const method = moduleRecord.methods?.[methodId];
+    if (typeof method !== "function") {
+      throw new Error(`Unknown module method: ${moduleId}.${methodId}`);
+    }
+    return method.call(
+      {
+        moduleId: moduleRecord.moduleId,
+        metadata: cloneMetadata(moduleRecord.metadata),
+      },
+      ...args,
+    );
+  }
+
+  return {
+    installModule,
+    invokeModule,
+    listModules,
+    loadModule,
+    unloadModule,
+  };
+}