space-data-module-sdk 0.8.3 → 0.8.5

package/src/index.d.ts

@@ -1,3 +1,10 @@
+import type { ModuleDeploymentPlan } from "./deployment/index.js";
+import type {
+  HarnessInputFrame,
+  ModuleHarness,
+  RuntimeHostTestModuleDefinition,
+} from "./testing/index.js";
+
 // --- Manifest ---
 
 export type PayloadWireFormat = "flatbuffer" | "aligned-binary";
@@ -12,6 +19,7 @@ export type ProtocolRoleName = "handle" | "dial" | "both";
 export interface PayloadTypeRef {
   schemaName?: string;
   fileIdentifier?: string;
+  schemaVersion?: string;
   schemaHash?: string | number[] | Uint8Array;
   acceptsAnyFlatbuffer?: boolean;
   wireFormat?: PayloadWireFormat;
@@ -38,6 +46,16 @@ export function payloadTypeRefsMatch(
   actualTypeRef?: PayloadTypeRef | null,
 ): boolean;
 
+export function payloadSchemaIdentitiesEqual(
+  leftTypeRef?: PayloadTypeRef | null,
+  rightTypeRef?: PayloadTypeRef | null,
+): boolean;
+
+export function alignedPayloadLayoutsCompatible(
+  leftTypeRef?: PayloadTypeRef | null,
+  rightTypeRef?: PayloadTypeRef | null,
+): boolean;
+
 export function selectPreferredPayloadTypeRef(
   port?: { acceptedTypeSets?: Array<{ allowedTypes?: PayloadTypeRef[] }> } | null,
   options?: { preferredWireFormat?: PayloadWireFormat | string | null },
@@ -48,6 +66,7 @@ export type AllowedType = PayloadTypeRef;
 export interface AcceptedTypeSet {
   setId: string;
   allowedTypes: PayloadTypeRef[];
+  allowedWireFormats?: PayloadWireFormat[];
 }
 
 export interface PortManifest {
@@ -114,6 +133,39 @@ export interface BuildArtifact {
   entrySymbol?: string | null;
 }
 
+export interface PluginFlowNode {
+  nodeId: string;
+  pluginId: string;
+  methodId?: string | null;
+  kind?: string | null;
+  dispatchModel?: string | null;
+  config?: Uint8Array | number[];
+  uiX?: number;
+  uiY?: number;
+}
+
+export interface PluginFlowEdge {
+  edgeId?: string | null;
+  fromNodeId: string;
+  fromPortId: string;
+  toNodeId: string;
+  toPortId: string;
+}
+
+export interface PluginFlowTrigger {
+  triggerId: string;
+  kind?: string | null;
+  source?: string | null;
+  defaultIntervalMs?: number | bigint;
+  httpPath?: string | null;
+}
+
+export interface PluginFlowTriggerBinding {
+  triggerId: string;
+  targetNodeId: string;
+  targetPortId: string;
+}
+
 export interface PluginManifest {
   pluginId: string;
   name: string;
@@ -128,6 +180,10 @@ export interface PluginManifest {
   protocols?: ProtocolSpec[];
   schemasUsed?: PayloadTypeRef[];
   buildArtifacts?: BuildArtifact[];
+  flowNodes?: PluginFlowNode[];
+  flowEdges?: PluginFlowEdge[];
+  flowTriggers?: PluginFlowTrigger[];
+  flowTriggerBindings?: PluginFlowTriggerBinding[];
   abiVersion?: number;
 }
 
@@ -149,6 +205,30 @@ export function writeEmbeddedManifestArtifacts(options: {
 
 // --- Invoke ---
 
+export interface InvokeArenaTransferToken {}
+
+export interface InvokeArenaLease {
+  readonly arena: Uint8Array;
+  readonly generation: number;
+  readonly closed: boolean;
+  advance(
+    nextArena?: Uint8Array | ArrayBuffer | ArrayBufferView,
+  ): number;
+  close(): void;
+  createTransferToken(
+    frame: InvokeFrame,
+    options?: {
+      ownership?: number | string;
+      mutability?: number | string;
+    },
+  ): InvokeArenaTransferToken;
+}
+
+export function createInvokeArenaLease(
+  arena: Uint8Array | ArrayBuffer | ArrayBufferView,
+  options?: { generation?: number },
+): InvokeArenaLease;
+
 export interface InvokeFrame {
   portId?: string | null;
   typeRef?: PayloadTypeRef | null;
@@ -156,8 +236,11 @@ export interface InvokeFrame {
   offset?: number;
   size?: number;
   ownership?: number | string;
+  arenaLease?: InvokeArenaLease;
+  arenaGeneration?: number;
   generation?: number;
   mutability?: number | string;
+  frameId?: bigint | number | string;
   traceId?: bigint | number | string;
   streamId?: number;
   sequence?: bigint | number | string;
@@ -169,32 +252,84 @@ export interface PluginInvokeRequestEnvelope {
   methodId: string;
   inputs?: InvokeFrame[];
   inputFrames?: InvokeFrame[];
+  externalArena?: Uint8Array | ArrayBuffer | ArrayBufferView;
   payloadArena?: Uint8Array;
+  traceId?: bigint | number | string;
+  outputStreamCap?: number;
 }
 
 export interface PluginInvokeResponseEnvelope {
   statusCode?: number;
+  status?: number;
   yielded?: boolean;
   backlogRemaining?: number;
   outputs?: InvokeFrame[];
   outputFrames?: InvokeFrame[];
+  externalArena?: Uint8Array | ArrayBuffer | ArrayBufferView;
   payloadArena?: Uint8Array;
   errorCode?: string | null;
   errorMessage?: string | null;
+  traceId?: bigint | number | string;
+}
+
+export interface DecodedPluginInvokeRequestEnvelope
+  extends PluginInvokeRequestEnvelope {
+  envelope: "PIV";
+  arenaLease: InvokeArenaLease;
+}
+
+export interface DecodedPluginInvokeResponseEnvelope
+  extends PluginInvokeResponseEnvelope {
+  envelope: "PIV";
+  arenaLease: InvokeArenaLease;
+}
+
+export interface DecodePluginInvokeEnvelopeOptions {
+  externalArena?: Uint8Array | ArrayBuffer | ArrayBufferView;
+  arenaLease?: InvokeArenaLease;
 }
 
 export function encodePluginInvokeRequest(
   request: PluginInvokeRequestEnvelope,
 ): Uint8Array;
+export function writePluginInvokeRequestToArena(
+  request: PluginInvokeRequestEnvelope,
+  arena: Uint8Array | ArrayBuffer | ArrayBufferView,
+): Uint8Array;
 export function decodePluginInvokeRequest(
   data: Uint8Array | ArrayBuffer | ArrayBufferView,
-): PluginInvokeRequestEnvelope;
+  options?: DecodePluginInvokeEnvelopeOptions,
+): DecodedPluginInvokeRequestEnvelope;
 export function encodePluginInvokeResponse(
   response: PluginInvokeResponseEnvelope,
 ): Uint8Array;
 export function decodePluginInvokeResponse(
   data: Uint8Array | ArrayBuffer | ArrayBufferView,
-): PluginInvokeResponseEnvelope;
+  options?: DecodePluginInvokeEnvelopeOptions,
+): DecodedPluginInvokeResponseEnvelope;
+/**
+ * Alignment (bytes) guaranteed for the payload arena base of every encoded
+ * invoke envelope, as an absolute address at every host<->module hop.
+ */
+export const INVOKE_ARENA_ALIGNMENT: number;
+export function assertAlignedInvokeBuffer(
+  bytes: Uint8Array,
+  arenaArray: Uint8Array | null,
+  kind: "request" | "response",
+  arenaAlignment?: number,
+): void;
+/**
+ * Zero-copy module-to-module hop: reuse a decoded output frame (payload view
+ * and type metadata) as an input frame for the next invocation without any
+ * decode/re-serialize round-trip.
+ */
+export function forwardOutputFrameAsInput(
+  outputFrame: InvokeFrame,
+  overrides?: Partial<InvokeFrame> & {
+    copyCanonical?: boolean;
+    arenaTransfer?: InvokeArenaTransferToken;
+  },
+): InvokeFrame;
 export function normalizeInvokeSurfaceName(
   value: InvokeSurface | number | string | null | undefined,
 ): InvokeSurface | null;
@@ -240,7 +375,7 @@ export function validatePluginArtifact(options: {
 
 export function validateManifestWithStandards(
   manifest: PluginManifest,
-  options?: { sourceName?: string },
+  options?: { sourceName?: string; catalog?: StandardsEntry[]; standardsRoot?: string },
 ): Promise<ComplianceReport>;
 
 export function validateArtifactWithStandards(options: {
@@ -249,6 +384,8 @@ export function validateArtifactWithStandards(options: {
   wasmPath?: string;
   exportNames?: string[];
   sourceName?: string;
+  catalog?: StandardsEntry[];
+  standardsRoot?: string;
 }): Promise<ComplianceReport>;
 
 export function loadManifestFromFile(manifestPath: string): Promise<PluginManifest>;
@@ -639,6 +776,90 @@ export interface EncryptedEnvelope {
 
 export function generateX25519Keypair(): Promise<X25519Keypair>;
 
+export interface MarketplaceArtifactBinding {
+  listingId: string;
+  moduleId: string;
+  version: string;
+  encryptedCid: string;
+  encryptedHash: Uint8Array | ArrayBuffer | ArrayBufferView | number[] | string;
+  providerId: string;
+  policyId: string;
+  keyEpoch: string;
+  manifestHash: Uint8Array | ArrayBuffer | ArrayBufferView | number[] | string;
+  contentKeyId?: string;
+}
+
+export interface MarketplaceContentRecipient {
+  recipientPeerId: string;
+  recipientKeyId: string;
+  publicKey: Uint8Array | ArrayBuffer | ArrayBufferView | number[] | string;
+  grantId: string;
+  scope: string;
+  expiresAtMs?: number;
+}
+
+export interface MarketplaceContentKeyWrap {
+  algorithm: string;
+  contentKeyId: string;
+  recipientPeerId: string;
+  recipientKeyId: string;
+  providerId: string;
+  encryptedCid: string;
+  grantId: string;
+  scope: string;
+  expiresAtMs: number;
+  providerEphemeralPublicKey: Uint8Array;
+  nonce: Uint8Array;
+  aad: Uint8Array;
+  ciphertext: Uint8Array;
+  tag: Uint8Array;
+}
+
+export interface MarketplaceProtectedContent {
+  algorithm: "AES-256-GCM";
+  contentKeyId: string;
+  artifact: {
+    listingId: string;
+    moduleId: string;
+    version: string;
+    encryptedCid: string;
+    encryptedHash: string;
+    providerId: string;
+    policyId: string;
+    keyEpoch: string;
+    manifestHash: string;
+    contentKeyId: string;
+  };
+  aad: Uint8Array;
+  encryptedPayload: {
+    algorithm: "AES-256-GCM";
+    nonce: Uint8Array;
+    aad: Uint8Array;
+    ciphertext: Uint8Array;
+    tag: Uint8Array;
+  };
+  wrappedKeys: MarketplaceContentKeyWrap[];
+}
+
+export function createMarketplaceContentAad(
+  artifact: MarketplaceArtifactBinding,
+): Uint8Array;
+
+export function protectMarketplaceContent(options: {
+  plaintext: Uint8Array | ArrayBuffer | ArrayBufferView | number[];
+  artifact: MarketplaceArtifactBinding;
+  recipients: MarketplaceContentRecipient[];
+  contentKey?: Uint8Array | ArrayBuffer | ArrayBufferView | number[] | null;
+  contentNonce?: Uint8Array | ArrayBuffer | ArrayBufferView | number[] | null;
+  providerWrapKeyPair?: X25519Keypair | null;
+  wrapNonce?: Uint8Array | ArrayBuffer | ArrayBufferView | number[] | null;
+}): Promise<MarketplaceProtectedContent>;
+
+export function decryptMarketplaceContentKeyWrap(options: {
+  wrap: MarketplaceContentKeyWrap;
+  recipientPrivateKey: Uint8Array | ArrayBuffer | ArrayBufferView | number[] | string;
+}): Promise<Uint8Array>;
+
 export function encryptBytesForRecipient(options: {
   plaintext: Uint8Array | ArrayBuffer;
   recipientPublicKey: Uint8Array | string;
@@ -763,6 +984,7 @@ export interface GuestLinkArtifact {
   symbolPrefix: string;
   methodSymbols: Record<string, string>;
   threadModel: ModuleThreadModelName;
+  capabilities: string[];
   objectBytes: Uint8Array;
 }
 
@@ -807,7 +1029,15 @@ export function compileModuleFromSource(options: {
   language?: string;
   threadModel?: ModuleThreadModelName;
   outputPath?: string;
+  importedMemory?: boolean;
+  sharedMemory?: boolean;
+  initialMemoryBytes?: number;
+  maximumMemoryBytes?: number;
+  emscriptenRoot?: string;
   allowUndefinedImports?: boolean;
+  guestLinkCapabilities?: string[];
+  catalog?: StandardsEntry[];
+  standardsRoot?: string;
 }): Promise<CompilationResult>;
 
 export function cleanupCompilation(
@@ -821,6 +1051,8 @@ export function protectModuleArtifact(options: {
   artifactId?: string;
   recipientPublicKeyHex?: string;
   mnemonic?: string;
+  publishTimestamp?: string;
+  publishTimestampMs?: number;
   target?: string | DeploymentTarget;
   targetUrl?: string;
   capabilities?: string[];
@@ -834,6 +1066,12 @@ export function createRecipientKeypairHex(): Promise<{
   privateKeyHex: string;
 }>;
 
+export function getFlatbuffersCppRuntimeHeaders(): Promise<
+  Record<string, string>
+>;
+
+export function getInvokeCppSchemaHeaders(): Promise<Record<string, string>>;
+
 export type {
   EmceptionCommandResult,
   SharedEmceptionFileContent,
@@ -922,17 +1160,24 @@ export interface StandardsEntry {
   hash: string | null;
   version: string | null;
   files: string[];
+  rootTypeName?: string | null;
+  idl?: string;
+  source?: string;
 }
 
-export function loadStandardsCatalog(): Promise<StandardsEntry[]>;
-export function loadKnownTypeCatalog(): Promise<StandardsEntry[]>;
+export function loadStandardsCatalog(options?: {
+  standardsRoot?: string;
+}): Promise<StandardsEntry[]>;
+export function loadKnownTypeCatalog(options?: {
+  standardsRoot?: string;
+}): Promise<StandardsEntry[]>;
 export function resolveStandardsTypeRef(
   typeRef: PayloadTypeRef,
   catalog?: StandardsEntry[],
 ): StandardsEntry | null;
 export function validateManifestAgainstStandardsCatalog(
   manifest: PluginManifest,
-  options?: { sourceName?: string; catalog?: StandardsEntry[] },
+  options?: { sourceName?: string; catalog?: StandardsEntry[]; standardsRoot?: string },
 ): Promise<{ catalog: StandardsEntry[]; issues: ComplianceIssue[] }>;
 
 // --- Bundle ---
@@ -1087,8 +1332,7 @@ export interface HostcallBridge {
   imports: Record<string, Record<string, (...args: number[]) => number>>;
   getLastEnvelope(): unknown;
   getLastResponseBytes(): Uint8Array;
-  getLastResponseText(): string;
-  getLastResponseJson(): unknown;
+  getLastResponseEnvelope(): unknown;
 }
 
 export interface BrowserFilesystemShim {
@@ -1625,7 +1869,7 @@ export function dispatchNodeHostSyncOperation(
 export function createNodeHostSyncDispatcher(
   host: NodeHost,
 ): (operation: string, params?: unknown) => unknown;
-export function createJsonHostcallBridge(options: {
+export function createHostcallBridge(options: {
   dispatch: (operation: string, params?: unknown) => unknown;
   getMemory: () => { buffer: ArrayBuffer | SharedArrayBuffer };
   moduleName?: string;
@@ -1675,8 +1919,29 @@ export interface BrowserModuleHarness {
   invokeRaw(
     requestBytes: Uint8Array | ArrayBuffer | ArrayBufferView,
   ): Promise<Uint8Array>;
+  invokeDirect(request: {
+    methodId?: string | null;
+    /**
+     * Browser direct invoke requires this to be a full view of the active
+     * SharedArrayBuffer-backed module memory; foreign arenas and
+     * payload-bearing frames are rejected.
+     */
+    externalArena?: Uint8Array | ArrayBuffer | ArrayBufferView;
+    inputs?: HarnessInputFrame[];
+  }): Promise<{
+    statusCode: number;
+    errorCode?: string | null;
+    errorMessage?: string | null;
+    outputs: HarnessInputFrame[];
+  }>;
   invoke(request: {
     methodId?: string | null;
+    /**
+     * Browser direct invoke requires this to be a full view of the active
+     * SharedArrayBuffer-backed module memory; foreign arenas and
+     * payload-bearing frames are rejected.
+     */
+    externalArena?: Uint8Array | ArrayBuffer | ArrayBufferView;
     inputs?: HarnessInputFrame[];
   }): Promise<{
     statusCode: number;
@@ -1694,13 +1959,406 @@ export function createBrowserModuleHarness(options?: {
   hostOptions?: BrowserHostOptions;
   args?: string[];
   env?: Record<string, string>;
+  manifest?: PluginManifest | Record<string, unknown>;
   surface?: "direct" | "command";
   performance?: {
     now(): number;
     timeOrigin: number;
   };
+  wasmMemory?: WebAssembly.Memory;
+  memory?: WebAssembly.Memory;
+  sharedMemory?: boolean;
+  allowRawInvoke?: boolean;
+  initialMemoryBytes?: number;
+  maximumMemoryBytes?: number;
   logOutput?: boolean;
+  hostcallDispatch?: (operation: string, params: unknown) => unknown;
 }): Promise<BrowserModuleHarness>;
+
+// --- Async in-WASM host bridge (WS6.1): worker harness + SAB channel ---
+export interface WorkerModuleHarness {
+  runtime: { kind: "worker"; inner?: unknown };
+  host: unknown;
+  buffer: SharedArrayBuffer;
+  exports: string[];
+  callExport(name: string, ...args: unknown[]): Promise<unknown>;
+  invoke(request: unknown): Promise<unknown>;
+  invokeRaw(requestBytes: Uint8Array): Promise<unknown>;
+  readMemory(ptr: number, length: number): Promise<Uint8Array>;
+  readManifest(): Promise<Uint8Array | null>;
+  destroy(): Promise<void>;
+}
+export function createWorkerModuleHarness(options: {
+  wasmSource: Uint8Array | ArrayBuffer;
+  host?: unknown;
+  hostOptions?: BrowserHostOptions;
+  dispatchHost?: (operation: string, params: unknown) => Promise<unknown>;
+  maxHostcallResponseBytes?: number;
+  hostcallTimeoutMs?: number;
+  workerUrl?: URL | string;
+  harnessOptions?: Record<string, unknown>;
+}): Promise<WorkerModuleHarness>;
+export function createSabHostcallBuffer(options?: {
+  maxResponseBytes?: number;
+}): SharedArrayBuffer;
+export function createSabHostcallClientDispatch(options: {
+  buffer: SharedArrayBuffer;
+  postRequest: (request: { operation: string; params: unknown }) => void;
+  timeoutMs?: number;
+}): (operation: string, params?: unknown) => unknown;
+export function createSabHostcallServer(options: {
+  buffer: SharedArrayBuffer;
+  dispatch: (operation: string, params: unknown) => Promise<unknown> | unknown;
+}): { handleRequest(request: { operation: string; params?: unknown }): Promise<void> };
+
+// --- Browser cron/timer driver (WS6.3) ---
+export interface ModuleTimerRunRecord {
+  timerId: string;
+  methodId: string;
+  trigger: "scheduled" | "manual";
+  status: "running" | "ok" | "error" | "skipped";
+  startedAt: number;
+  finishedAt?: number;
+  message?: string;
+}
+export interface ModuleTimerInfo {
+  timerId: string;
+  methodId: string;
+  description: string;
+  defaultIntervalMs: number;
+  intervalMs: number;
+  enabled: boolean;
+  scheduled: boolean;
+}
+export interface ModuleTimerDriver {
+  listTimers(): ModuleTimerInfo[];
+  runHistory(timerId: string): ModuleTimerRunRecord[];
+  start(): ModuleTimerInfo[];
+  runNow(timerId: string): Promise<unknown>;
+  stop(): void;
+}
+export function createModuleTimerDriver(options: {
+  harness?: { invoke(request: unknown): Promise<unknown> };
+  invoke?: (request: { methodId: string; inputs: unknown[] }) => Promise<unknown>;
+  manifestBytes?: Uint8Array;
+  manifest?: Record<string, unknown>;
+  timers?: Array<Record<string, unknown>>;
+  schedules?: Record<string, { enabled?: boolean; intervalMs?: number }>;
+  minIntervalMs?: number;
+  maxRunHistory?: number;
+  setIntervalImpl?: (fn: () => void, ms: number) => unknown;
+  clearIntervalImpl?: (handle: unknown) => void;
+  now?: () => number;
+  onRun?: (run: ModuleTimerRunRecord) => void;
+}): ModuleTimerDriver;
+
+// --- JS flow-runtime host (WS3.2 / Phase 3 routing ABI) ---
+export type FlowFrameOwnership =
+  | "host-owned"
+  | "plugin-owned"
+  | "transferred"
+  | "unknown";
+export type FlowFrameMutability =
+  | "immutable"
+  | "single-writer-mutable"
+  | "append-only"
+  | "unknown";
+
+export interface FlowFrameData {
+  portId: string;
+  bytes: Uint8Array;
+  typeRef: PayloadTypeRef | null;
+  wireFormat: PayloadWireFormat;
+  alignment: number;
+  ownership: FlowFrameOwnership;
+  mutability: FlowFrameMutability;
+  frameId: bigint;
+  arenaGeneration: number;
+  streamId: number;
+  sequence: number;
+  endOfStream: boolean;
+}
+
+export interface FlowTriggerFrameOptions {
+  portId?: string;
+  bytes?: Uint8Array | ArrayBuffer;
+  typeRef?: PayloadTypeRef | null;
+  wireFormat?: PayloadWireFormat | 0 | 1;
+  alignment?: number;
+  ownership?:
+    | Exclude<FlowFrameOwnership, "unknown">
+    | "producer-owned"
+    | "borrowed"
+    | "shared"
+    | 0
+    | 1
+    | 2;
+  mutability?:
+    | Exclude<FlowFrameMutability, "unknown">
+    | "mutable"
+    | 0
+    | 1
+    | 2;
+  frameId?: bigint | number | string;
+  traceToken?: bigint | number | string;
+  streamId?: number;
+  sequence?: number;
+  endOfStream?: boolean;
+}
+
+export interface FlowOutputFrame extends FlowTriggerFrameOptions {
+  bytes?: Uint8Array | ArrayBuffer;
+}
+
+export interface FlowNodeDispatchDescriptor {
+  nodeIdPtr: number;
+  nodeIndex: number;
+  dependencyIdPtr: number;
+  dependencyIndex: number;
+  pluginIdPtr: number;
+  methodIdPtr: number;
+  dispatchModelPtr: number;
+  entrypointPtr: number;
+  manifestBytesSymbolPtr: number;
+  manifestSizeSymbolPtr: number;
+  initSymbolPtr: number;
+  destroySymbolPtr: number;
+  mallocSymbolPtr: number;
+  freeSymbolPtr: number;
+  streamInvokeSymbolPtr: number;
+  nodeId: string;
+  dependencyId: string;
+  pluginId: string;
+  methodId: string;
+  dispatchModel: string;
+}
+
+export interface FlowDependencyDescriptor {
+  dependencyIdPtr: number;
+  pluginIdPtr: number;
+  versionPtr: number;
+  sha256Ptr: number;
+  signaturePtr: number;
+  signerPublicKeyPtr: number;
+  entrypointPtr: number;
+  manifestBytesSymbolPtr: number;
+  manifestSizeSymbolPtr: number;
+  initSymbolPtr: number;
+  destroySymbolPtr: number;
+  mallocSymbolPtr: number;
+  freeSymbolPtr: number;
+  streamInvokeSymbolPtr: number;
+  wasmBytesPtr: number;
+  wasmSize: number;
+  manifestBytesPtr: number;
+  manifestSize: number;
+  dependencyId: string;
+  pluginId: string;
+  version: string;
+  sha256: string | null;
+  signature: string | null;
+  signerPublicKey: string | null;
+}
+
+export interface FlowEdgeDescriptor {
+  fromNode: number;
+  fromPortPtr: number;
+  toNode: number;
+  toPortPtr: number;
+  schemaNamePtr: number;
+  fileIdentifierPtr: number;
+  schemaVersionPtr: number;
+  schemaHashPtr: number;
+  schemaHashSize: number;
+  rootTypeNamePtr: number;
+  canonicalFallbackAvailable: number;
+  alignedEligible: number;
+  alignedLayoutFields: number;
+  alignedByteLength: number;
+  alignedFixedStringLength: number;
+  alignedRequiredAlignment: number;
+  /** OPAQUE byte route (SDS $PLG 1.0.13): no SDS identity, no aligned layout. */
+  opaque: number;
+  fromPort: string;
+  toPort: string;
+  schemaName: string;
+  fileIdentifier: string;
+  schemaVersion: string | null;
+  schemaHash: Uint8Array;
+  rootTypeName: string;
+}
+
+export interface FlowRoutingState {
+  alignedSharedRoutes: bigint;
+  alignedCopiedRoutes: bigint;
+  canonicalRoutes: bigint;
+  rejectedFrames: bigint;
+}
+
+export interface FlowNodeState {
+  invocationCount: bigint;
+  consumedFrames: bigint;
+  queuedFrames: number;
+  backlogRemaining: number;
+  lastStatus: number;
+  ready: boolean;
+  yielded: boolean;
+}
+
+export interface FlowIngressState {
+  totalReceived: bigint;
+  totalDropped: bigint;
+  queuedFrames: number;
+}
+
+export interface FlowEngineBodyReference {
+  token: bigint;
+  generation: bigint;
+  fnv1a64: bigint;
+  enginePtr: number;
+  size: number;
+  frames: number;
+  used: number;
+  bytes: Uint8Array;
+}
+
+export interface FlowHandlerInvocation {
+  nodeIndex: number;
+  pluginId: string;
+  methodId: string;
+  dependencyId: string;
+  nodeId: string;
+  frames: FlowFrameData[];
+}
+
+export interface FlowHandlerResult {
+  statusCode?: number;
+  backlogRemaining?: number;
+  yielded?: boolean;
+  outputs?: FlowOutputFrame[];
+  errorCode?: string | null;
+  errorMessage?: string | null;
+  error?: unknown;
+}
+
+export type FlowHandler = (
+  invocation: FlowHandlerInvocation,
+) => Promise<FlowHandlerResult | void> | FlowHandlerResult | void;
+export type FlowHandlerMap = Record<string, FlowHandler>;
+
+export interface FlowDrainOptions {
+  maxIterations?: number;
+  frameBudget?: number;
+}
+
+export interface FlowDrainResult {
+  iterations: number;
+  nodesInvoked: number;
+  handlersSkipped: number;
+}
+
+export interface FlowRuntimeHost {
+  instance: WebAssembly.Instance;
+  memory: WebAssembly.Memory;
+  nodeCount: number;
+  /** Number of real route edges in the compiled graph. */
+  edgeCount: number;
+  /** Number of all type descriptor rows, including trigger-only identities. */
+  typeDescriptorCount: number;
+  triggerCount: number;
+  dependencyCount: number;
+  resetState(): void;
+  readCString(ptr: number, maxLength?: number): string;
+  getNodeDispatchDescriptor(index: number): FlowNodeDispatchDescriptor;
+  getDependencyDescriptor(index: number): FlowDependencyDescriptor;
+  getEdgeDescriptor(index: number): FlowEdgeDescriptor;
+  getTypeDescriptor(index: number): FlowEdgeDescriptor | null;
+  getRoutingState(): FlowRoutingState;
+  getNodeState(index: number): FlowNodeState;
+  getIngressState(index: number): FlowIngressState;
+  resolveEngineBodyRef(
+    token: bigint | number | string,
+  ): FlowEngineBodyReference | null;
+  enqueueTrigger(triggerIndex: number): void;
+  enqueueTriggerFrame(
+    triggerIndex: number,
+    frame?: FlowTriggerFrameOptions,
+  ): number;
+  drain(
+    handlers?: FlowHandlerMap,
+    options?: FlowDrainOptions,
+  ): Promise<FlowDrainResult>;
+}
+
+export interface FlowRuntimeHostOptions {
+  wasmSource?: Uint8Array | ArrayBuffer;
+  wasmBytes?: Uint8Array | ArrayBuffer;
+  wasmModule?: WebAssembly.Module;
+  args?: string[];
+  env?: Record<string, string>;
+  logOutput?: boolean;
+  extraImports?: WebAssembly.Imports;
+  legacyHostImportCompat?: boolean;
+  engineLink?: {
+    exports: WebAssembly.Exports & { memory: WebAssembly.Memory };
+  } | null;
+}
+
+export const FLOW_INVALID_INDEX: number;
+export function createFlowRuntimeHost(
+  options: FlowRuntimeHostOptions,
+): Promise<FlowRuntimeHost>;
+
+export interface ModuleSignatureVerificationPolicy {
+  trustedPublicKeys?: string[] | string;
+  requireSignature?: boolean;
+}
+
+export interface IsomorphicFlowChildOptions {
+  pluginId: string;
+  wasmSource: Uint8Array | ArrayBuffer | ArrayBufferView;
+  manifest?: PluginManifest | Record<string, unknown>;
+  surface?: "direct" | "command";
+  verifySignature?: false | ModuleSignatureVerificationPolicy;
+  host?: BrowserHost | RuntimeHost | Record<string, unknown>;
+  hostcallDispatch?: (operation: string, params: unknown) => unknown;
+  imports?: WebAssembly.Imports;
+}
+
+export interface IsomorphicFlowChildRecord {
+  nodeId: string;
+  pluginId: string;
+  sha256: string;
+  descriptor: FlowDependencyDescriptor;
+  config: Uint8Array;
+  configInputPortId: string | null;
+  harness: BrowserModuleHarness;
+}
+
+export interface IsomorphicFlowDrainOptions extends FlowDrainOptions {
+  handlers?: FlowHandlerMap;
+}
+
+export interface IsomorphicFlowRuntimeHost
+  extends Omit<FlowRuntimeHost, "drain"> {
+  parent: FlowRuntimeHost;
+  children: Map<string, IsomorphicFlowChildRecord>;
+  drain(options?: IsomorphicFlowDrainOptions): Promise<FlowDrainResult>;
+  destroy(): void;
+}
+
+export interface IsomorphicFlowRuntimeHostOptions
+  extends FlowRuntimeHostOptions {
+  /** Exact signed artifact bytes are required; precompiled modules are rejected. */
+  wasmModule?: never;
+  verifySignature?: false | ModuleSignatureVerificationPolicy;
+  children?: IsomorphicFlowChildOptions[];
+}
+
+export function createIsomorphicFlowRuntimeHost(
+  options: IsomorphicFlowRuntimeHostOptions,
+): Promise<IsomorphicFlowRuntimeHost>;
+
 export interface ModuleFlatBufferStreamPumpStats {
   bytesReceived: number;
   chunksReceived: number;
@@ -1840,7 +2498,7 @@ export interface LicensingGrantModuleDescriptor {
   moduleVersion?: string;
   requiredScope?: string;
   keyId?: string;
-  allowedDomains: string[];
+  allowedXpubs: string[];
   maxGrantTimeoutMs: number;
   encrypted: boolean;
 }
@@ -1963,6 +2621,54 @@ export function validateLicensingGrant(
   },
 ): LicensingGrantMessage;
 
+export function encodeUnsignedLicensingGrantForProviderSignature(
+  grant: LicensingGrantMessage,
+): Uint8Array;
+
+export function verifyLicensingGrantProviderSignature(
+  grant: LicensingGrantMessage,
+  options: {
+    requestedAtMs?: number;
+    verify(
+      publicKey: Uint8Array,
+      payload: Uint8Array,
+      signature: Uint8Array,
+    ): boolean | Promise<boolean>;
+  },
+): Promise<LicensingGrantMessage>;
+
+export function encodeUnsignedFieldStreamPolicyForProviderSignature(
+  policy: unknown,
+): Uint8Array;
+
+export function verifyFieldStreamPolicyProviderSignature(
+  policy: unknown,
+  options: {
+    providerPublicKey: Uint8Array | ArrayBuffer | ArrayBufferView;
+    verify(
+      publicKey: Uint8Array,
+      payload: Uint8Array,
+      signature: Uint8Array,
+    ): boolean | Promise<boolean>;
+  },
+): Promise<unknown>;
+
+export function encodeUnsignedFieldStreamMessageForProviderSignature(
+  message: unknown,
+): Uint8Array;
+
+export function verifyFieldStreamMessageProviderSignature(
+  message: unknown,
+  options: {
+    providerPublicKey: Uint8Array | ArrayBuffer | ArrayBufferView;
+    verify(
+      publicKey: Uint8Array,
+      payload: Uint8Array,
+      signature: Uint8Array,
+    ): boolean | Promise<boolean>;
+  },
+): Promise<unknown>;
+
 export function extractGrantModuleDescriptor(
   grant: LicensingGrantMessage,
 ): LicensingGrantModuleDescriptor;