sdn-flow

sdn-flow composes signed modules into typed flow graphs, compiles those graphs into deployable WebAssembly runtimes, and provides host surfaces for loading, starting, and serving those flows.

It builds on space-data-module-sdk, which defines the module artifact, single-file bundle, capability vocabulary, and module ABI. sdn-flow owns the flow graph, compiled flow descriptors, hosted runtime planning, deployment client, and installed-flow startup layers.

Project Scope

This repo covers the full flow path:

• normalized flow programs and runtime descriptors
• designer-facing graph inspection and requirement summaries
• compilation from flow graph to one generated C++ translation unit
• emception-backed compilation to one deployable .wasm runtime artifact
• deployment packaging built on canonical module auth and transport records
• hosted runtime planning for browser, JS server, Go-oriented, and vendor runtime profiles
• installed-flow startup surfaces for browser, Deno, Bun, and Node hosts

Flow Artifact

A compiled flow is one runtime artifact with:

• WebAssembly bytes
• an embedded FlatBuffer manifest
• exported runtime, invocation, and descriptor symbols
• embedded signed module dependencies
• deployment metadata for local or remote rollout

The compiler path uses a native C++ source generator compiled to WebAssembly plus an emception-compatible compiler adapter, so the flow graph always converges on the same runtime artifact format.

Runtime Portability

Flows generated by sdn-flow are runtime-neutral compiled WebAssembly artifacts. A host can run the output anywhere it can:

• instantiate WebAssembly
• read FlatBuffers
• implement the canonical module and flow ABI surface

That is the same runtime family already exercised in the companion flatbuffers/wasm work:

• browser
• Node.js
• C#
• Go
• Java
• Kotlin
• Python
• Rust
• Swift

This repo currently ships turnkey startup surfaces for browser, Deno, Bun, and Node, and it includes environment profiles for go-sdn and WasmEdge-style hosts. Non-JS runtimes consume the same compiled artifact through the runtime, invocation, and descriptor ABIs exposed from src/host.

Relationship To Module SDK

space-data-module-sdk is the canonical module contract:

• manifest schema and embedded manifest exports
• module capability vocabulary
• compliance rules
• module signing and transport envelopes
• sds.bundle single-file packaging
• module hostcall/import ABI

sdn-flow layers flow composition on top of that contract:

• program structure and graph normalization
• compiled flow runtime descriptor and invocation ABI
• dependency composition for multi-module runtimes
• deployment clients and hosted runtime plans
• startup surfaces for hosts that launch compiled flows

Install

npm install sdn-flow

Compile A Flow

import {
  EmceptionCompilerAdapter,
  SignedArtifactCatalog,
  normalizeProgram,
} from "sdn-flow";

const program = normalizeProgram(flowJson);

const compiler = new EmceptionCompilerAdapter({
  emception,
  artifactCatalog: new SignedArtifactCatalog(),
  manifestBuilder: async () => manifestBytes,
});

const artifact = await compiler.compile({
  program,
});

The compiled artifact carries the exported symbols needed by hosts to inspect and run the flow without reinterpreting the source graph.

Start A Host

For JS-family hosts, the quickest path is a workspace file plus the environment-neutral auto-host entrypoint:

import { startInstalledFlowAutoHost } from "sdn-flow";

await startInstalledFlowAutoHost({
  workspacePath: "./workspace.json",
});

For Node-based startup from the command line:

sdn-flow-host --workspace ./workspace.json
sdn-flow-host --workspace ./workspace.json --engine node

That CLI is a thin wrapper over startInstalledFlowAutoHost(...) with startup summary output and SIGINT / SIGTERM shutdown handling.

Host Surfaces

The host package is organized around a few layers:

• createInstalledFlowHost(...) Discover or register plugin packages, load a program, and start the runtime.
• createInstalledFlowService(...) Keep timer and HTTP-trigger services running for a loaded flow.
• createInstalledFlowApp(...) Boot from workspace.json, persist startup state, and refresh the runtime against workspace changes.
• startInstalledFlowAutoHost(...) Select the matching startup surface for browser, Deno, Bun, or Node from workspace metadata.
• createNpmPackageManager(...) Tie workspace package references to real install, update, and remove flows.

For hosts that load compiled artifacts directly, bindCompiledRuntimeAbi(...), bindCompiledInvocationAbi(...), and bindCompiledDescriptorAbi(...) expose the low-level contract used to inspect and execute a compiled flow artifact.

Runtime Families

| Layer | Coverage | |---|---| | Compiled flow artifact | Browser, Node.js, C#, Go, Java, Kotlin, Python, Rust, Swift | | Turnkey startup surfaces in this repo | Browser, Deno, Bun, Node | | Checked-in environment profiles | sdn-js, go-sdn, WasmEdge-style vendor profile |

The built-in host planners focus on the engines exercised by the current examples and startup helpers. The compiled flow artifact itself stays portable across the broader runtime set above.

Examples

• Bootstrap Examples
• Environment Demos
• Single-Plugin Flow
• Field-Protected Catalog Entry Flow
• ISS Proximity OEM Flow

Notable environment profiles:

• sdn-js-catalog-gateway Shared JS-host profile with Deno as the preferred single-file deployment target.
• go-sdn-omm-service Go-oriented service deployment profile.
• wasmedge-udp-spooler Vendor-profile example for extension-backed UDP and filesystem handling.

Package Surface

• sdn-flow
• sdn-flow/runtime
• sdn-flow/designer
• sdn-flow/host
• sdn-flow/auth
• sdn-flow/transport
• sdn-flow/deploy
• sdn-flow/compiler
• sdn-flow/compliance

Documentation

• Architecture
• Host Capability Model
• Plugin Architecture
• Plugin Manifest
• Compatibility Model
• Plugin Compliance Checks

Development

npm install
npm test

Node.js >=20 is required. The compile path uses ../emception for generated C++ to WebAssembly builds.

License

MIT