space-data-module-sdk 0.2.0 → 0.2.6

package/README.md

@@ -27,6 +27,11 @@ A module built with this SDK is a `.wasm` artifact with:
 - exported manifest accessors:
   - `plugin_get_manifest_flatbuffer`
   - `plugin_get_manifest_flatbuffer_size`
+- canonical invoke exports when the artifact supports direct in-memory calls:
+  - `plugin_invoke_stream`
+  - `plugin_alloc`
+  - `plugin_free`
+- an exported `_start` entry when the artifact supports WASI command mode
 - optional `sds.bundle` custom-section payloads for:
   - manifest bytes
   - deployment authorization
@@ -37,6 +42,45 @@ A module built with this SDK is a `.wasm` artifact with:
 The module contract stays the same whether the artifact is loaded directly,
 wrapped in a deployment envelope, or shipped as one bundled `.wasm` file.
 
+## Canonical Invoke ABI
+
+Modules can now declare one or both canonical invoke surfaces in
+`manifest.invokeSurfaces`:
+
+- `direct`: in-memory invocation through `plugin_invoke_stream`
+- `command`: WASI command-mode invocation through `_start`
+
+Both surfaces consume and produce the same FlatBuffer envelopes:
+
+- `PluginInvokeRequest`
+- `PluginInvokeResponse`
+
+Those envelopes route SDS payload frames by `portId` using
+`TypedArenaBuffer.fbs` and a shared payload arena. Command mode reads one
+request from `stdin` and writes one response to `stdout`. Direct mode takes the
+same request bytes from guest memory and returns response bytes in guest
+memory.
+
+For simple single-input / single-output methods, command mode also supports a
+degenerate raw shortcut:
+
+```bash
+wasmedge module.wasm --method echo < input.fb > output.fb
+```
+
+That shortcut is only valid when the method declares exactly one input port and
+at most one output port.
+
+Source-built modules can include `space_data_module_invoke.h` and use the
+generated helper functions to read the active invocation inputs and emit SDS
+outputs. The reference invoke examples live in
+[`examples/invoke-echo`](./examples/invoke-echo):
+
+- `manifest.direct.json`
+- `manifest.command.json`
+- `manifest.hybrid.json`
+- `module.c`
+
 ## Runtime Portability
 
 The module format is language-neutral. A host can load modules from this SDK
@@ -135,6 +179,33 @@ The reference path lives in
 - the `go` and `python` directories show non-JS readers against the same
   bundle contract
 
+## Module Publication
+
+Packages that publish SDN modules now use the canonical `sdn-module`
+publication descriptor. That descriptor covers:
+
+- standalone module packages
+- attached module artifacts shipped inside another language library
+- discovery of bundled wasm, sidecar signatures, and encrypted transport
+  FlatBuffers
+
+The full standard is in
+[`docs/module-publication-standard.md`](./docs/module-publication-standard.md),
+with concrete examples under [`examples/publishing`](./examples/publishing).
+
+For npm packages, the simplest form is:
+
+```json
+{
+  "name": "@example/orbit-lib",
+  "version": "1.2.3",
+  "sdn-module": "./dist/orbit-lib.module.wasm"
+}
+```
+
+When signature or transport metadata is published in the same file, it belongs
+inside `sds.bundle`, not as raw bytes after the end of the wasm binary.
+
 ## Host ABI
 
 This repo also defines the module-facing capability vocabulary and the first
@@ -222,8 +293,12 @@ npm test
 npm run check:compliance
 ```
 
-Node.js `>=20` is required. Native compilation paths use Emscripten
-(`emcc` / `em++`) when available.
+Node.js `>=20` is required. The compiler uses `sdn-emception` and `flatc-wasm`
+by default.
+
+If another repo needs the same compiler runtime, the package also exposes a
+shared emception session at `space-data-module-sdk/compiler/emception` with
+helpers for serialized command execution and virtual filesystem access.
 
 ## License
 

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.2.0",
+  "version": "0.2.6",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
   "types": "./src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DigitalArsenal/space-data-module-sdk.git"
+  },
   "bin": {
-    "space-data-module": "./bin/space-data-module.js"
+    "space-data-module": "bin/space-data-module.js"
   },
   "exports": {
     ".": "./src/index.js",
@@ -14,7 +18,10 @@
     "./auth": "./src/auth/index.js",
     "./transport": "./src/transport/index.js",
     "./compiler": "./src/compiler/index.js",
+    "./compiler/emception": "./src/compiler/emception.js",
     "./bundle": "./src/bundle/index.js",
+    "./invoke": "./src/invoke/index.js",
+    "./runtime": "./src/runtime/index.js",
     "./standards": "./src/standards/index.js",
     "./schemas/*": "./schemas/*"
   },
@@ -31,13 +38,15 @@
     "prepublishOnly": "npm test && npm run check:compliance"
   },
   "dependencies": {
-    "sdn-emception": "1.0.0",
+    "flatc-wasm": "25.12.19-wasm.43",
     "flatbuffers": "^25.9.23",
     "hd-wallet-wasm": "1.6.0",
+    "sdn-emception": "1.0.0",
     "spacedatastandards.org": "23.3.3-0.3.4"
   },
   "devDependencies": {
-    "express": "^4.21.2"
+    "express": "^4.21.2",
+    "flatsql": "^0.4.0"
   },
   "engines": {
     "node": ">=20.0.0"

package/schemas/PluginInvokeRequest.fbs

@@ -0,0 +1,18 @@
+include "TypedArenaBuffer.fbs";
+
+namespace orbpro.invoke;
+
+/// Canonical invoke envelope consumed by direct ABI and command-mode execution.
+table PluginInvokeRequest {
+  /// Stable method identifier from PluginManifest.methods.
+  method_id: string (required);
+
+  /// Input frames for the invocation, routed by TypedArenaBuffer.port_id.
+  input_frames: [orbpro.stream.TypedArenaBuffer];
+
+  /// Arena backing all input frame payload bytes.
+  payload_arena: [ubyte];
+}
+
+root_type PluginInvokeRequest;
+file_identifier "PINQ";

package/schemas/PluginInvokeResponse.fbs

@@ -0,0 +1,30 @@
+include "TypedArenaBuffer.fbs";
+
+namespace orbpro.invoke;
+
+/// Canonical invoke result emitted by direct ABI and command-mode execution.
+table PluginInvokeResponse {
+  /// Method-specific status code. Zero conventionally indicates success.
+  status_code: int = 0;
+
+  /// True when the method yielded before fully draining queued work.
+  yielded: bool = false;
+
+  /// Remaining backlog, if known.
+  backlog_remaining: uint32 = 0;
+
+  /// Output frames produced by the invocation, routed by port_id.
+  output_frames: [orbpro.stream.TypedArenaBuffer];
+
+  /// Arena backing all output frame payload bytes.
+  payload_arena: [ubyte];
+
+  /// Stable machine-readable error code when invocation fails.
+  error_code: string;
+
+  /// Human-readable error message when invocation fails.
+  error_message: string;
+}
+
+root_type PluginInvokeResponse;
+file_identifier "PINS";

package/schemas/PluginManifest.fbs

@@ -68,6 +68,12 @@ enum DrainPolicy : ubyte {
   DRAIN_TO_EMPTY = 2
 }
 
+/// Canonical module invocation surfaces supported by an artifact.
+enum InvokeSurface : ubyte {
+  DIRECT = 0,
+  COMMAND = 1
+}
+
 /// Accepted schema family for a port.
 table AcceptedTypeSet {
   /// Stable type-set identifier.
@@ -163,6 +169,7 @@ table PluginManifest {
   schemas_used: [orbpro.stream.FlatBufferTypeRef];
   build_artifacts: [BuildArtifact];
   abi_version: uint32 = 1;
+  invoke_surfaces: [InvokeSurface];
 }
 
 root_type PluginManifest;

package/schemas/TypedArenaBuffer.fbs

@@ -1,11 +1,17 @@
 // OrbPro Plugin SDK - Typed Arena Buffer Schema
 //
-// Canonical descriptor for schema-tagged FlatBuffer frames moving through
+// Canonical descriptor for schema-tagged payload frames moving through
 // arena-backed plugin streams.
 
 namespace orbpro.stream;
 
-/// FlatBuffer schema identity for a stream frame or accepted port type.
+/// Logical payload wire format for a stream frame or accepted port type.
+enum PayloadWireFormat : ubyte {
+  Flatbuffer = 0,
+  AlignedBinary = 1
+}
+
+/// Payload schema identity for a stream frame or accepted port type.
 table FlatBufferTypeRef {
   /// Logical schema name, for example `OMM.fbs`.
   schema_name: string;
@@ -18,6 +24,21 @@ table FlatBufferTypeRef {
 
   /// True when this port/type set accepts any FlatBuffer frame.
   accepts_any_flatbuffer: bool = false;
+
+  /// Payload wire format. Defaults to regular FlatBuffer framing.
+  wire_format: PayloadWireFormat = Flatbuffer;
+
+  /// Root or layout type name for aligned-binary payloads.
+  root_type_name: string;
+
+  /// Fixed string length for aligned-binary schemas when required.
+  fixed_string_length: uint16 = 0;
+
+  /// Fixed byte length for aligned-binary payloads.
+  byte_length: uint32 = 0;
+
+  /// Required byte alignment for aligned-binary payloads.
+  required_alignment: uint16 = 0;
 }
 
 /// Ownership mode for an arena-backed frame.

package/src/bundle/codec.js

@@ -66,6 +66,25 @@ function normalizeString(value, fallback = null) {
   return String(value);
 }
 
+function normalizePayloadWireFormat(value) {
+  if (value === 1) {
+    return "aligned-binary";
+  }
+  const normalized = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-");
+  return normalized === "aligned-binary" ? "aligned-binary" : "flatbuffer";
+}
+
+function normalizeUnsignedInteger(value, fallback = 0) {
+  const normalized = Number(value ?? fallback);
+  if (!Number.isFinite(normalized)) {
+    return fallback;
+  }
+  return Math.max(0, Math.trunc(normalized));
+}
+
 function normalizeByteArray(value, { encoding = null } = {}) {
   if (value === undefined || value === null) {
     return [];
@@ -124,6 +143,11 @@ function normalizeTypeRef(value) {
     normalizeString(value.fileIdentifier),
     normalizeByteArray(value.schemaHash),
     Boolean(value.acceptsAnyFlatbuffer),
+    normalizePayloadWireFormat(value.wireFormat),
+    normalizeString(value.rootTypeName),
+    normalizeUnsignedInteger(value.fixedStringLength),
+    normalizeUnsignedInteger(value.byteLength),
+    normalizeUnsignedInteger(value.requiredAlignment),
   );
 }