space-data-module-sdk 0.2.6 → 0.2.8

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

@@ -90,8 +90,77 @@ export class ProtocolSpec implements flatbuffers.IUnpackableObject<ProtocolSpecT
       : null;
   }
 
+  wireId(): string | null;
+  wireId(optionalEncoding: flatbuffers.Encoding): string | Uint8Array | null;
+  wireId(optionalEncoding?: any): string | Uint8Array | null {
+    const offset = this.bb!.__offset(this.bb_pos, 14);
+    return offset
+      ? this.bb!.__string(this.bb_pos + offset, optionalEncoding)
+      : null;
+  }
+
+  transportKind(): string | null;
+  transportKind(
+    optionalEncoding: flatbuffers.Encoding,
+  ): string | Uint8Array | null;
+  transportKind(optionalEncoding?: any): string | Uint8Array | null {
+    const offset = this.bb!.__offset(this.bb_pos, 16);
+    return offset
+      ? this.bb!.__string(this.bb_pos + offset, optionalEncoding)
+      : null;
+  }
+
+  role(): string | null;
+  role(optionalEncoding: flatbuffers.Encoding): string | Uint8Array | null;
+  role(optionalEncoding?: any): string | Uint8Array | null {
+    const offset = this.bb!.__offset(this.bb_pos, 18);
+    return offset
+      ? this.bb!.__string(this.bb_pos + offset, optionalEncoding)
+      : null;
+  }
+
+  specUri(): string | null;
+  specUri(optionalEncoding: flatbuffers.Encoding): string | Uint8Array | null;
+  specUri(optionalEncoding?: any): string | Uint8Array | null {
+    const offset = this.bb!.__offset(this.bb_pos, 20);
+    return offset
+      ? this.bb!.__string(this.bb_pos + offset, optionalEncoding)
+      : null;
+  }
+
+  autoInstall(): boolean {
+    const offset = this.bb!.__offset(this.bb_pos, 22);
+    return offset ? !!this.bb!.readInt8(this.bb_pos + offset) : true;
+  }
+
+  advertise(): boolean {
+    const offset = this.bb!.__offset(this.bb_pos, 24);
+    return offset ? !!this.bb!.readInt8(this.bb_pos + offset) : false;
+  }
+
+  discoveryKey(): string | null;
+  discoveryKey(
+    optionalEncoding: flatbuffers.Encoding,
+  ): string | Uint8Array | null;
+  discoveryKey(optionalEncoding?: any): string | Uint8Array | null {
+    const offset = this.bb!.__offset(this.bb_pos, 26);
+    return offset
+      ? this.bb!.__string(this.bb_pos + offset, optionalEncoding)
+      : null;
+  }
+
+  defaultPort(): number {
+    const offset = this.bb!.__offset(this.bb_pos, 28);
+    return offset ? this.bb!.readUint16(this.bb_pos + offset) : 0;
+  }
+
+  requireSecureTransport(): boolean {
+    const offset = this.bb!.__offset(this.bb_pos, 30);
+    return offset ? !!this.bb!.readInt8(this.bb_pos + offset) : false;
+  }
+
   static startProtocolSpec(builder: flatbuffers.Builder) {
-    builder.startObject(5);
+    builder.startObject(14);
   }
 
   static addProtocolId(
@@ -129,6 +198,60 @@ export class ProtocolSpec implements flatbuffers.IUnpackableObject<ProtocolSpecT
     builder.addFieldOffset(4, descriptionOffset, 0);
   }
 
+  static addWireId(
+    builder: flatbuffers.Builder,
+    wireIdOffset: flatbuffers.Offset,
+  ) {
+    builder.addFieldOffset(5, wireIdOffset, 0);
+  }
+
+  static addTransportKind(
+    builder: flatbuffers.Builder,
+    transportKindOffset: flatbuffers.Offset,
+  ) {
+    builder.addFieldOffset(6, transportKindOffset, 0);
+  }
+
+  static addRole(builder: flatbuffers.Builder, roleOffset: flatbuffers.Offset) {
+    builder.addFieldOffset(7, roleOffset, 0);
+  }
+
+  static addSpecUri(
+    builder: flatbuffers.Builder,
+    specUriOffset: flatbuffers.Offset,
+  ) {
+    builder.addFieldOffset(8, specUriOffset, 0);
+  }
+
+  static addAutoInstall(
+    builder: flatbuffers.Builder,
+    autoInstall: boolean,
+  ) {
+    builder.addFieldInt8(9, +autoInstall, +true);
+  }
+
+  static addAdvertise(builder: flatbuffers.Builder, advertise: boolean) {
+    builder.addFieldInt8(10, +advertise, +false);
+  }
+
+  static addDiscoveryKey(
+    builder: flatbuffers.Builder,
+    discoveryKeyOffset: flatbuffers.Offset,
+  ) {
+    builder.addFieldOffset(11, discoveryKeyOffset, 0);
+  }
+
+  static addDefaultPort(builder: flatbuffers.Builder, defaultPort: number) {
+    builder.addFieldInt16(12, defaultPort, 0);
+  }
+
+  static addRequireSecureTransport(
+    builder: flatbuffers.Builder,
+    requireSecureTransport: boolean,
+  ) {
+    builder.addFieldInt8(13, +requireSecureTransport, +false);
+  }
+
   static endProtocolSpec(builder: flatbuffers.Builder): flatbuffers.Offset {
     const offset = builder.endObject();
     builder.requiredField(offset, 4); // protocol_id
@@ -143,6 +266,15 @@ export class ProtocolSpec implements flatbuffers.IUnpackableObject<ProtocolSpecT
     inputPortIdOffset: flatbuffers.Offset,
     outputPortIdOffset: flatbuffers.Offset,
     descriptionOffset: flatbuffers.Offset,
+    wireIdOffset: flatbuffers.Offset,
+    transportKindOffset: flatbuffers.Offset,
+    roleOffset: flatbuffers.Offset,
+    specUriOffset: flatbuffers.Offset,
+    autoInstall: boolean,
+    advertise: boolean,
+    discoveryKeyOffset: flatbuffers.Offset,
+    defaultPort: number,
+    requireSecureTransport: boolean,
   ): flatbuffers.Offset {
     ProtocolSpec.startProtocolSpec(builder);
     ProtocolSpec.addProtocolId(builder, protocolIdOffset);
@@ -150,6 +282,15 @@ export class ProtocolSpec implements flatbuffers.IUnpackableObject<ProtocolSpecT
     ProtocolSpec.addInputPortId(builder, inputPortIdOffset);
     ProtocolSpec.addOutputPortId(builder, outputPortIdOffset);
     ProtocolSpec.addDescription(builder, descriptionOffset);
+    ProtocolSpec.addWireId(builder, wireIdOffset);
+    ProtocolSpec.addTransportKind(builder, transportKindOffset);
+    ProtocolSpec.addRole(builder, roleOffset);
+    ProtocolSpec.addSpecUri(builder, specUriOffset);
+    ProtocolSpec.addAutoInstall(builder, autoInstall);
+    ProtocolSpec.addAdvertise(builder, advertise);
+    ProtocolSpec.addDiscoveryKey(builder, discoveryKeyOffset);
+    ProtocolSpec.addDefaultPort(builder, defaultPort);
+    ProtocolSpec.addRequireSecureTransport(builder, requireSecureTransport);
     return ProtocolSpec.endProtocolSpec(builder);
   }
 
@@ -160,6 +301,15 @@ export class ProtocolSpec implements flatbuffers.IUnpackableObject<ProtocolSpecT
       this.inputPortId(),
       this.outputPortId(),
       this.description(),
+      this.wireId(),
+      this.transportKind(),
+      this.role(),
+      this.specUri(),
+      this.autoInstall(),
+      this.advertise(),
+      this.discoveryKey(),
+      this.defaultPort(),
+      this.requireSecureTransport(),
     );
   }
 
@@ -169,6 +319,15 @@ export class ProtocolSpec implements flatbuffers.IUnpackableObject<ProtocolSpecT
     _o.inputPortId = this.inputPortId();
     _o.outputPortId = this.outputPortId();
     _o.description = this.description();
+    _o.wireId = this.wireId();
+    _o.transportKind = this.transportKind();
+    _o.role = this.role();
+    _o.specUri = this.specUri();
+    _o.autoInstall = this.autoInstall();
+    _o.advertise = this.advertise();
+    _o.discoveryKey = this.discoveryKey();
+    _o.defaultPort = this.defaultPort();
+    _o.requireSecureTransport = this.requireSecureTransport();
   }
 }
 
@@ -179,6 +338,15 @@ export class ProtocolSpecT implements flatbuffers.IGeneratedObject {
     public inputPortId: string | Uint8Array | null = null,
     public outputPortId: string | Uint8Array | null = null,
     public description: string | Uint8Array | null = null,
+    public wireId: string | Uint8Array | null = null,
+    public transportKind: string | Uint8Array | null = null,
+    public role: string | Uint8Array | null = null,
+    public specUri: string | Uint8Array | null = null,
+    public autoInstall: boolean = true,
+    public advertise: boolean = false,
+    public discoveryKey: string | Uint8Array | null = null,
+    public defaultPort: number = 0,
+    public requireSecureTransport: boolean = false,
   ) {}
 
   pack(builder: flatbuffers.Builder): flatbuffers.Offset {
@@ -192,6 +360,19 @@ export class ProtocolSpecT implements flatbuffers.IGeneratedObject {
       this.outputPortId !== null ? builder.createString(this.outputPortId!) : 0;
     const description =
       this.description !== null ? builder.createString(this.description!) : 0;
+    const wireId =
+      this.wireId !== null ? builder.createString(this.wireId!) : 0;
+    const transportKind =
+      this.transportKind !== null
+        ? builder.createString(this.transportKind!)
+        : 0;
+    const role = this.role !== null ? builder.createString(this.role!) : 0;
+    const specUri =
+      this.specUri !== null ? builder.createString(this.specUri!) : 0;
+    const discoveryKey =
+      this.discoveryKey !== null
+        ? builder.createString(this.discoveryKey!)
+        : 0;
 
     return ProtocolSpec.createProtocolSpec(
       builder,
@@ -200,6 +381,15 @@ export class ProtocolSpecT implements flatbuffers.IGeneratedObject {
       inputPortId,
       outputPortId,
       description,
+      wireId,
+      transportKind,
+      role,
+      specUri,
+      this.autoInstall,
+      this.advertise,
+      discoveryKey,
+      this.defaultPort,
+      this.requireSecureTransport,
     );
   }
 }

package/src/index.d.ts

@@ -2,6 +2,12 @@
 
 export type PayloadWireFormat = "flatbuffer" | "aligned-binary";
 export type InvokeSurface = "direct" | "command";
+export type ProtocolTransportKindName =
+  | "libp2p"
+  | "http"
+  | "ws"
+  | "wasi-pipe";
+export type ProtocolRoleName = "handle" | "dial" | "both";
 
 export interface PayloadTypeRef {
   schemaName?: string;
@@ -15,6 +21,28 @@ export interface PayloadTypeRef {
   requiredAlignment?: number;
 }
 
+export function clonePayloadTypeRef(
+  value?: PayloadTypeRef | null | Record<string, unknown>,
+): PayloadTypeRef;
+
+export function normalizePayloadWireFormatName(
+  value?: PayloadWireFormat | string | null,
+): PayloadWireFormat | null;
+
+export function getPayloadTypeWireFormat(
+  typeRef?: PayloadTypeRef | null,
+): PayloadWireFormat;
+
+export function payloadTypeRefsMatch(
+  expectedTypeRef?: PayloadTypeRef | null,
+  actualTypeRef?: PayloadTypeRef | null,
+): boolean;
+
+export function selectPreferredPayloadTypeRef(
+  port?: { acceptedTypeSets?: Array<{ allowedTypes?: PayloadTypeRef[] }> } | null,
+  options?: { preferredWireFormat?: PayloadWireFormat | string | null },
+): PayloadTypeRef;
+
 export type AllowedType = PayloadTypeRef;
 
 export interface AcceptedTypeSet {
@@ -46,17 +74,61 @@ export interface ExternalInterface {
   capability?: string;
 }
 
+export interface HostCapabilityManifest {
+  capability: string;
+  scope?: string;
+  required?: boolean;
+  description?: string;
+}
+
+export interface TimerSpec {
+  timerId: string;
+  methodId: string;
+  inputPortId?: string | null;
+  defaultIntervalMs?: number | bigint;
+  description?: string | null;
+}
+
+export interface ProtocolSpec {
+  protocolId: string;
+  methodId: string;
+  inputPortId?: string | null;
+  outputPortId?: string | null;
+  description?: string | null;
+  wireId?: string | null;
+  transportKind?: ProtocolTransportKindName | string | null;
+  role?: ProtocolRoleName | string | null;
+  specUri?: string | null;
+  autoInstall?: boolean;
+  advertise?: boolean;
+  discoveryKey?: string | null;
+  defaultPort?: number;
+  requireSecureTransport?: boolean;
+}
+
+export interface BuildArtifact {
+  artifactId: string;
+  kind?: string | null;
+  path: string;
+  target?: string | null;
+  entrySymbol?: string | null;
+}
+
 export interface PluginManifest {
   pluginId: string;
   name: string;
   version: string;
   pluginFamily: string;
-  capabilities?: string[];
+  capabilities?: Array<string | HostCapabilityManifest>;
   invokeSurfaces?: InvokeSurface[];
   runtimeTargets?: string[];
   externalInterfaces?: ExternalInterface[];
   methods: MethodManifest[];
+  timers?: TimerSpec[];
+  protocols?: ProtocolSpec[];
   schemasUsed?: PayloadTypeRef[];
+  buildArtifacts?: BuildArtifact[];
+  abiVersion?: number;
 }
 
 export function encodePluginManifest(manifest: PluginManifest): Uint8Array;
@@ -151,6 +223,7 @@ export interface ComplianceReport {
 }
 
 export const RecommendedCapabilityIds: readonly string[];
+export const StandaloneWasiCapabilityIds: readonly string[];
 
 export function validatePluginManifest(
   manifest: unknown,
@@ -421,6 +494,53 @@ export {
   withSharedEmception,
 } from "./compiler/emception.js";
 
+export type {
+  CapabilityRuntimeSurface,
+  HarnessInputFrame,
+  HarnessInvokeScenario,
+  HarnessRawScenario,
+  ManifestHarnessPlan,
+} from "./testing/index.js";
+
+export {
+  describeCapabilityRuntimeSurface,
+  generateManifestHarnessPlan,
+  materializeHarnessScenario,
+  serializeHarnessPlan,
+} from "./testing/index.js";
+
+export type {
+  AuthPolicy,
+  DeploymentPlanIssue,
+  DeploymentPlanValidationReport,
+  DeploymentBindingModeName,
+  InputBinding,
+  InputBindingSourceKindName,
+  ModuleDeploymentPlan,
+  PublicationBinding,
+  ResolvedProtocolInstallation,
+  ScheduleBinding,
+  ScheduleBindingKindName,
+  ServiceBinding,
+} from "./deployment/index.js";
+
+export {
+  DEPLOYMENT_PLAN_FORMAT_VERSION,
+  DeploymentBindingMode,
+  InputBindingSourceKind,
+  ScheduleBindingKind,
+  createDeploymentPlanBundleEntry,
+  findDeploymentPlanEntry,
+  normalizeDeploymentBindingModeName,
+  normalizeDeploymentPlan,
+  normalizeInputBindingSourceKindName,
+  normalizeProtocolRoleName,
+  normalizeProtocolTransportKindName,
+  normalizeScheduleBindingKindName,
+  readDeploymentPlanFromBundle,
+  validateDeploymentPlan,
+} from "./deployment/index.js";
+
 // --- Standards ---
 
 export interface StandardsEntry {
@@ -451,9 +571,10 @@ export const DEFAULT_HASH_ALGORITHM: string;
 export function createSingleFileBundle(options: {
   wasmBytes: Uint8Array;
   manifest: PluginManifest;
-  authorization: SignedEnvelope;
+  authorization?: SignedEnvelope | unknown;
   transportEnvelope?: EncryptedEnvelope | null;
-  entries?: Record<string, unknown>;
+  deploymentPlan?: ModuleDeploymentPlan;
+  entries?: Array<Record<string, unknown>>;
 }): Promise<{ wasmBytes: Uint8Array }>;
 
 export function parseSingleFileBundle(
@@ -961,10 +1082,24 @@ export const InvokeSurface: {
   COMMAND: string;
 };
 
+export const ProtocolTransportKind: {
+  LIBP2P: ProtocolTransportKindName;
+  HTTP: ProtocolTransportKindName;
+  WS: ProtocolTransportKindName;
+  WASI_PIPE: ProtocolTransportKindName;
+};
+
+export const ProtocolRole: {
+  HANDLE: ProtocolRoleName;
+  DIAL: ProtocolRoleName;
+  BOTH: ProtocolRoleName;
+};
+
 export const RuntimeTarget: {
   NODE: string;
   BROWSER: string;
   WASI: string;
+  WASMEDGE: string;
   SERVER: string;
   DESKTOP: string;
   EDGE: string;

package/src/index.js

@@ -7,6 +7,8 @@ export * from "./bundle/index.js";
 export * from "./standards/index.js";
 export * from "./host/index.js";
 export * from "./invoke/index.js";
+export * from "./testing/index.js";
+export * from "./deployment/index.js";
 export {
   DefaultInvokeExports,
   DefaultManifestExports,
@@ -14,5 +16,7 @@ export {
   ExternalInterfaceDirection,
   ExternalInterfaceKind,
   InvokeSurface,
+  ProtocolRole,
+  ProtocolTransportKind,
   RuntimeTarget,
 } from "./runtime/constants.js";

package/src/manifest/index.js

@@ -6,6 +6,13 @@ export {
 } from "../generated/orbpro/stream/flat-buffer-type-ref.js";
 export { decodePluginManifest, encodePluginManifest } from "./codec.js";
 export { toEmbeddedPluginManifest } from "./normalize.js";
+export {
+  clonePayloadTypeRef,
+  getPayloadTypeWireFormat,
+  normalizePayloadWireFormatName,
+  payloadTypeRefsMatch,
+  selectPreferredPayloadTypeRef,
+} from "./typeRefs.js";
 export {
   generateEmbeddedManifestSource,
   writeEmbeddedManifestArtifacts,

package/src/manifest/normalize.js

@@ -13,6 +13,7 @@ import {
   TimerSpecT,
 } from "../generated/orbpro/manifest.js";
 import { FlatBufferTypeRefT } from "../generated/orbpro/stream/flat-buffer-type-ref.js";
+import { ProtocolRole, ProtocolTransportKind } from "../runtime/constants.js";
 
 const pluginFamilyByName = Object.freeze({
   sensor: PluginFamily.SENSOR,
@@ -81,6 +82,31 @@ const invokeSurfaceByName = Object.freeze({
   command: InvokeSurface.COMMAND,
 });
 
+const protocolTransportKindByName = Object.freeze({
+  libp2p: ProtocolTransportKind.LIBP2P,
+  http: ProtocolTransportKind.HTTP,
+  ws: ProtocolTransportKind.WS,
+  websocket: ProtocolTransportKind.WS,
+  "wasi-pipe": ProtocolTransportKind.WASI_PIPE,
+  wasi_pipe: ProtocolTransportKind.WASI_PIPE,
+  pipe: ProtocolTransportKind.WASI_PIPE,
+});
+
+const protocolRoleByName = Object.freeze({
+  handle: ProtocolRole.HANDLE,
+  handler: ProtocolRole.HANDLE,
+  dial: ProtocolRole.DIAL,
+  both: ProtocolRole.BOTH,
+});
+
+function normalizeOptionalString(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const normalized = String(value).trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
 function normalizeSchemaHash(value) {
   if (!value) {
     return [];
@@ -177,6 +203,41 @@ function normalizeInvokeSurfaces(value) {
   return normalized;
 }
 
+function normalizeBoolean(value, fallback = false) {
+  if (value === undefined || value === null) {
+    return fallback;
+  }
+  return value === true;
+}
+
+function normalizeProtocolTransportKind(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const normalized = String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-");
+  if (normalized.length === 0) {
+    return null;
+  }
+  return protocolTransportKindByName[normalized] ?? normalized;
+}
+
+function normalizeProtocolRole(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const normalized = String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-");
+  if (normalized.length === 0) {
+    return null;
+  }
+  return protocolRoleByName[normalized] ?? normalized;
+}
+
 function toFlatBufferTypeRefT(value = {}) {
   if (value instanceof FlatBufferTypeRefT) {
     return value;
@@ -274,11 +335,20 @@ function toProtocolSpecT(value = {}) {
     return value;
   }
   return new ProtocolSpecT(
-    value.protocolId ?? null,
-    value.methodId ?? null,
-    value.inputPortId ?? null,
-    value.outputPortId ?? null,
-    value.description ?? null,
+    normalizeOptionalString(value.protocolId),
+    normalizeOptionalString(value.methodId),
+    normalizeOptionalString(value.inputPortId),
+    normalizeOptionalString(value.outputPortId),
+    normalizeOptionalString(value.description),
+    normalizeOptionalString(value.wireId),
+    normalizeProtocolTransportKind(value.transportKind),
+    normalizeProtocolRole(value.role),
+    normalizeOptionalString(value.specUri),
+    normalizeBoolean(value.autoInstall, true),
+    normalizeBoolean(value.advertise, false),
+    normalizeOptionalString(value.discoveryKey),
+    normalizeUnsignedInteger(value.defaultPort),
+    normalizeBoolean(value.requireSecureTransport, false),
   );
 }
 
@@ -322,12 +392,6 @@ export function toEmbeddedPluginManifest(input = {}) {
       "externalInterfaces are not yet representable in the embedded FlatBuffer manifest schema and were omitted from the compiled artifact.",
     );
   }
-  if (Array.isArray(input.runtimeTargets) && input.runtimeTargets.length > 0) {
-    warnings.push(
-      "runtimeTargets are not yet representable in the embedded FlatBuffer manifest schema and were omitted from the compiled artifact.",
-    );
-  }
-
   const capabilities = Array.isArray(input.capabilities)
     ? input.capabilities
         .map((entry) => toHostCapabilityT(entry, warnings))
@@ -358,6 +422,13 @@ export function toEmbeddedPluginManifest(input = {}) {
         : [],
       Number(input.abiVersion ?? 1),
       normalizeInvokeSurfaces(input.invokeSurfaces),
+      Array.isArray(input.runtimeTargets)
+        ? input.runtimeTargets
+            .map((value) =>
+              typeof value === "string" ? value.trim() : String(value ?? "").trim(),
+            )
+            .filter(Boolean)
+        : [],
     ),
     warnings,
   };