# @toolctrl/plugin-runtime

Phase 06 Task #21 foundation — host-side runtime for WebAssembly plugins.

Runtime is staging/foundation only until external WASM sandbox security signoff; do not treat third-party plugin execution as production-enabled yet.

## Scope

- Manifest schema (Zod) with capability declarations
- Ed25519 signature verification against a trusted-keys allowlist
- WebAssembly sandbox wrapper on Node 22's built-in `WebAssembly`, with memory-page caps and host-function fuel charging
- Capability gateway: deny-by-default host-function access
- Hook registry/fanout contracts for the foundation hook set
- Crash tracker, audit helpers, migrations guardrails, and lifecycle integration helpers

## Deferred

See `../../docs/features/plugins.md` and `../../docs/architecture/plugin-hooks.md` for
current status. Still-deferred runtime work:

- Hot-reload (operator restarts pod)
- Marketplace integration (#24 backlog)
- Additional hook points beyond the registered foundation set
- Higher-risk host bindings (`http.outbound`, `secret.read`, `db.read`, `db.write`) until security review/tests are complete
- Plugin secret storage and encrypted settings bindings
- Live debugging in plugin-dev mode

## Runtime choice

**Default: Node's built-in `WebAssembly` (V8) with memory-page limits and host-function fuel charging; per-instruction fuel remains deferred.**

Rationale: native Wasmtime bindings for Node (`@bytecodealliance/jco`, `@bytecodealliance/preview2-shim`) are still pre-1.0 and add a ~40 MB build asset. For the foundation we ship a portable wrapper around Node 22's `WebAssembly` runtime — sufficient for memory limits (`WebAssembly.Memory` max-page bounds) and an instruction-budget gate via host-fn fuel charging on each capability call.

**Fallback / upgrade path:** Wasmer (`@wasmer/sdk`) is API-compatible with the wrapper's contract and can be swapped in if we need richer per-instruction fuel. Wasmtime via `jco` becomes the production choice once the Component-Model is GA on Node. This is documented in `docs/architecture/plugin-system.md`.