sdn-flow 0.2.0

package/.claude/SKILLS.md

@@ -0,0 +1,7 @@
+# Shared SDN Skills
+
+## Available skills
+
+1. SDN Plugin ABI & Compliance
+   - Path: `.claude/skills/sdn-plugin-abi-compliance/SKILL.md`
+   - Use when touching plugin manifests, plugin API/ABI exports, compiled artifact compliance, or cross-repo SDN plugin architecture.

package/.claude/skills/sdn-plugin-abi-compliance/SKILL.md

@@ -0,0 +1,56 @@
+# SDN Plugin ABI & Compliance
+
+Use this skill whenever a task touches:
+
+- plugin API/ABI rules
+- manifest shape
+- embedded manifest exports
+- plugin compliance gates
+- cross-repo SDN plugin architecture
+
+## Canonical source of truth
+
+- `docs/PLUGIN_ARCHITECTURE.md`
+- `docs/PLUGIN_MANIFEST.md`
+- `docs/HOST_CAPABILITY_MODEL.md`
+- `docs/PLUGIN_COMPATIBILITY.md`
+- `docs/PLUGIN_COMPLIANCE_CHECKS.md`
+
+## Hard rules
+
+1. A plugin is a degenerate one-node flow.
+2. Deployable artifacts embed a FlatBuffer manifest.
+3. Plugin artifacts expose:
+   - `plugin_get_manifest_flatbuffer`
+   - `plugin_get_manifest_flatbuffer_size`
+4. Hosts bridge capabilities; they do not fork the plugin ABI.
+5. Capability and external-interface requirements must be explicit.
+
+## Compliance workflow
+
+1. Validate the manifest contract first.
+2. Validate compiled ABI exports when a `.wasm` artifact exists.
+3. Do not invent repo-local ABI variants.
+4. Use the shared checker in this repo instead of copying new compliance logic elsewhere.
+
+## Commands
+
+Repo scan:
+
+```bash
+node tools/run-plugin-compliance-check.mjs --repo-root .
+```
+
+If a repo needs targeted scanning, add `sdn-plugin-compliance.json` at its root
+and keep only manifest paths or scan directories there.
+
+Manifest plus wasm artifact:
+
+```bash
+node tools/run-plugin-compliance-check.mjs --manifest ./manifest.json --wasm ./dist/plugin.wasm
+```
+
+## Cross-repo rule
+
+Other Space Data Network repos should call this checker through thin wrapper
+scripts only. The actual API/ABI logic must live here in `sdn-flow`.

package/.claude/todo/001-js-host-startup-and-deno.md

@@ -0,0 +1,85 @@
+1. Add explicit JS-host engine modeling for `node`, `deno`, `bun`, and `browser`. (done)
+
+2. Keep one `sdn-js` adapter family while allowing environment-specific compatibility summaries. (done)
+
+3. Add installed plugin package discovery for Node/JS hosts so packages can be scanned from directories with `manifest.json` and optional `plugin.js`. (done)
+
+4. Add environment-neutral installed plugin loading so browser/Deno hosts can supply in-memory manifests/modules instead of filesystem discovery. (done)
+
+5. Add a bootstrap API that discovers/registers installed plugins and loads a flow program into a runtime. (done)
+
+6. Make the bootstrap API usable for Node-RED-style “install nodes and startup” flows. (done)
+   Done:
+   - `createInstalledFlowHost(...)`
+   - package discovery and registration
+   - flow program load + runtime drain bootstrap
+   - `createInstalledFlowService(...)`
+   - portable timer trigger scheduling
+   - portable HTTP request trigger dispatch
+   - `host.refreshPlugins(...)`
+   - `service.refresh(...)`
+   - runnable top-level bootstrap examples and scripts for each concrete host adapter
+   - persisted package catalog plus package-manager-driven install/update/remove flows
+
+7. Add Deno-oriented host-plan support so `sdn-js` deployments can declare `engine: "deno"` and document single-file deployment intent. (done)
+
+8. Add compatibility reporting so the same flow can be evaluated against `browser`, `deno`, `node`, and other supported engines with explicit unsupported capabilities. (done)
+
+9. Add tests for plugin discovery, installed-package registration, startup bootstrap, and browser/deno compatibility summaries. (done)
+
+10. Update README and environment examples once the bootstrap and engine model land. (done)
+
+11. Add a fetch-style host adapter so Deno/browser/Bun/modern Node can bind installed flows to a shared `Request`/`Response` entrypoint. (done)
+
+12. Add a persisted workspace/bootstrap layer so installed-flow hosts can boot from one workspace file with flow paths, plugin roots, and host defaults. (done)
+
+13. Add explicit workspace package-catalog mutation so hosts can persist install/uninstall operations and refresh the runtime against that state. (done)
+
+14. Add a host-plan launcher that can auto-bind installed-flow HTTP listeners through an injected serve adapter. (done)
+
+15. Add concrete Deno- and Node-oriented HTTP host adapters on top of the installed-flow launcher surface. (done)
+
+16. Add concrete browser/worker fetch-host adapters on top of the installed-flow launcher surface. (done)
+
+17. Add concrete Bun HTTP host adapters on top of the installed-flow launcher surface. (done)
+
+18. Add runnable top-level bootstrap examples/scripts for Deno, Node, Bun, and browser worker hosts. (done)
+   Goal:
+   - one small checked-in startup entrypoint per concrete host adapter
+   - direct use of `workspace.json` plus the new host adapter surfaces
+   - clear examples of how a host actually boots and stays up in each environment
+
+19. Add external package-manager and persistence integration beyond the local workspace catalog. (done)
+   Done:
+   - persisted `packageCatalog` / `installedPackages` normalization in workspace state
+   - `installWorkspacePackageReference(...)`, `updateWorkspacePackageReference(...)`, and `removeWorkspacePackageReference(...)`
+   - `app.installPackageReference(...)`, `app.updatePackageReference(...)`, and `app.removePackageReference(...)`
+   - generic `createCommandPackageManager(...)` adapter
+   - concrete `createNpmPackageManager(...)` adapter
+   - workspace tests for package-reference persistence and runtime refresh alignment
+
+20. Add one environment-neutral installed-flow startup entrypoint that can select the concrete host adapter from workspace/runtime metadata. (done)
+   Done:
+   - `resolveInstalledFlowAutoHostEngine(...)`
+   - `startInstalledFlowAutoHost(...)`
+   - dispatch to browser, Deno, Bun, and Node startup surfaces
+   - explicit starter injection hooks for tests and embedded hosts
+
+21. Add a checked-in auto-host bootstrap script that starts from `workspace.json` through the environment-neutral startup surface. (done)
+   Done:
+   - `examples/bootstrap/start-auto-host.mjs`
+   - direct startup from the checked-in `sdn-js-catalog-gateway/workspace.json`
+   - bootstrap coverage proving the example dispatches through `startInstalledFlowAutoHost(...)`
+
+22. Add a simple host CLI that boots one workspace through the auto-host surface. (done)
+   Done:
+   - `bin/sdn-flow-host.js`
+   - `--workspace` and optional `--engine` override support
+   - startup summary plus `SIGINT`/`SIGTERM` shutdown hooks
+   - CLI coverage for parsing, help text, and startup dispatch
+
+23. Publish root AGENTS guidance for module and flow builders. (done)
+   Done:
+   - root `AGENTS.md` in `space-data-module-sdk` for compliant module authors
+   - rewritten root `AGENTS.md` in `sdn-flow` for compliant flow and host authors
+   - explicit integration-test lists for module, bundle, compiler, startup, and environment changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DigitalArsenal.io, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# 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
+
+```bash
+npm install sdn-flow
+```
+
+## Compile A Flow
+
+```js
+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:
+
+```js
+import { startInstalledFlowAutoHost } from "sdn-flow";
+
+await startInstalledFlowAutoHost({
+  workspacePath: "./workspace.json",
+});
+```
+
+For Node-based startup from the command line:
+
+```bash
+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](./examples/bootstrap/README.md)
+- [Environment Demos](./examples/environments/README.md)
+- [Single-Plugin Flow](./examples/flows/single-plugin-flow.json)
+- [Field-Protected Catalog Entry Flow](./examples/flows/field-protected-catalog-entry/README.md)
+- [ISS Proximity OEM Flow](./examples/flows/iss-proximity-oem/README.md)
+
+Notable environment profiles:
+
+- [`sdn-js-catalog-gateway`](./examples/environments/sdn-js-catalog-gateway/README.md)
+  Shared JS-host profile with Deno as the preferred single-file deployment
+  target.
+- [`go-sdn-omm-service`](./examples/environments/go-sdn-omm-service/README.md)
+  Go-oriented service deployment profile.
+- [`wasmedge-udp-spooler`](./examples/environments/wasmedge-udp-spooler/README.md)
+  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](./docs/ARCHITECTURE.md)
+- [Host Capability Model](./docs/HOST_CAPABILITY_MODEL.md)
+- [Plugin Architecture](./docs/PLUGIN_ARCHITECTURE.md)
+- [Plugin Manifest](./docs/PLUGIN_MANIFEST.md)
+- [Compatibility Model](./docs/PLUGIN_COMPATIBILITY.md)
+- [Plugin Compliance Checks](./docs/PLUGIN_COMPLIANCE_CHECKS.md)
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+Node.js `>=20` is required. The compile path uses `../emception` for generated
+C++ to WebAssembly builds.
+
+## License
+
+[MIT](./LICENSE)

package/bin/sdn-flow-host.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import path from "node:path";
+import process from "node:process";
+
+import { startInstalledFlowAutoHost } from "../src/index.js";
+
+function normalizeString(value, fallback = null) {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : fallback;
+}
+
+export function formatSdnFlowHostUsage() {
+  return [
+    "Usage: sdn-flow-host --workspace <workspace.json> [--engine <engine>]",
+    "",
+    "Options:",
+    "  -w, --workspace <path>   Path to the installed-flow workspace.json file.",
+    "  -e, --engine <engine>    Optional runtime override: node, deno, bun, browser.",
+    "  -h, --help               Show this help text.",
+  ].join("\n");
+}
+
+export function parseSdnFlowHostCliArgs(argv = []) {
+  const args = Array.isArray(argv) ? [...argv] : [];
+  let workspacePath = null;
+  let engine = null;
+  let help = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "-h" || token === "--help") {
+      help = true;
+      continue;
+    }
+    if (token === "-w" || token === "--workspace") {
+      workspacePath = normalizeString(args[index + 1], null);
+      index += 1;
+      continue;
+    }
+    if (token === "-e" || token === "--engine") {
+      engine = normalizeString(args[index + 1], null);
+      index += 1;
+      continue;
+    }
+    if (!token.startsWith("-") && workspacePath === null) {
+      workspacePath = normalizeString(token, null);
+      continue;
+    }
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  return {
+    workspacePath,
+    engine,
+    help,
+  };
+}
+
+function summarizeStartedHost(host) {
+  const startupSummary = host?.startup?.workspace ?? null;
+  const listenerCount = Array.isArray(host?.listeners)
+    ? host.listeners.length
+    : Array.isArray(host?.bindingContexts)
+      ? host.bindingContexts.length
+      : 0;
+
+  return {
+    workspaceId:
+      startupSummary?.workspaceId ?? host?.app?.getSummary?.().workspaceId ?? null,
+    programId:
+      startupSummary?.programId ?? host?.app?.getSummary?.().programId ?? null,
+    engine: startupSummary?.engine ?? host?.app?.getSummary?.().engine ?? null,
+    listenerCount,
+  };
+}
+
+function installShutdownHooks(host, options = {}) {
+  if (
+    options.registerSignalHandlers === false ||
+    typeof host?.stop !== "function" ||
+    typeof process.on !== "function"
+  ) {
+    return;
+  }
+
+  let stopping = false;
+  const stopHost = async () => {
+    if (stopping) {
+      return;
+    }
+    stopping = true;
+    await host.stop();
+    if (options.exitProcess !== false) {
+      process.exit(0);
+    }
+  };
+
+  process.on("SIGINT", () => {
+    void stopHost();
+  });
+  process.on("SIGTERM", () => {
+    void stopHost();
+  });
+}
+
+export async function runSdnFlowHostCli(argv = process.argv.slice(2), options = {}) {
+  const parsed = parseSdnFlowHostCliArgs(argv);
+  const log = options.log ?? console.log.bind(console);
+
+  if (parsed.help) {
+    log(formatSdnFlowHostUsage());
+    return {
+      kind: "help",
+      args: parsed,
+    };
+  }
+
+  if (!parsed.workspacePath) {
+    throw new Error("sdn-flow-host requires --workspace <workspace.json>.");
+  }
+
+  const resolvedWorkspacePath = path.resolve(parsed.workspacePath);
+  const host = await (
+    options.startInstalledFlowAutoHost ?? startInstalledFlowAutoHost
+  )({
+    ...options.startOptions,
+    workspacePath: resolvedWorkspacePath,
+    ...(parsed.engine ? { engine: parsed.engine } : {}),
+  });
+  const summary = summarizeStartedHost(host);
+
+  if (options.quiet !== true) {
+    log(
+      `Started ${summary.workspaceId ?? "installed-flow workspace"} (${summary.engine ?? "unknown"}) from ${resolvedWorkspacePath}${
+        summary.listenerCount > 0
+          ? ` with ${summary.listenerCount} listener${summary.listenerCount === 1 ? "" : "s"}`
+          : ""
+      }.`,
+    );
+  }
+
+  installShutdownHooks(host, options);
+
+  return {
+    kind: "started",
+    args: {
+      ...parsed,
+      workspacePath: resolvedWorkspacePath,
+    },
+    host,
+    summary,
+  };
+}
+
+if (import.meta.main) {
+  try {
+    await runSdnFlowHostCli();
+  } catch (error) {
+    console.error(
+      typeof error?.message === "string" ? error.message : String(error),
+    );
+    console.error("");
+    console.error(formatSdnFlowHostUsage());
+    process.exit(1);
+  }
+}