Phase 5: Runtime Plugins and Developer Loop

Objective and prerequisites

Support genuinely dynamic runtime tools without mutating compiled Spice DI. This phase depends on stable run plan snapshots, daemon negotiation, canonical tool dispatch, and cancellation semantics.

The Phase 5.0A prerequisite is complete in core: all tool definitions carry effect/replay metadata and all execution failures use the correlated typed outcome contract. The plugin host must translate protocol failures into that same contract; it may not introduce a parallel error or retry model.

The Phase 5.0B kernel seam is also complete: ToolPlanSource leases current or exact immutable plans, Run.PlanIdentity records the combined compiled/tool identity, resume fails closed on substitution, and release is exactly-once and terminal-authoritative. A source contractually performs only a non-blocking reference decrement during release; generation drain remains asynchronous and source-owned. This slice deliberately contains no plugin protocol, process host, daemon integration, or activation manager.

Runtime-plugin contracts

• One host process and one local gRPC connection exist per plugin generation.
• Configuration names an absolute executable path and pinned SHA-256 digest. Relative paths, PATH lookup, digest drift, and ambient plugin discovery fail.
• Every launch receives a cryptographically random handshake secret. Candidate manifest, protocol, digest, identity, capabilities, and bounds are verified before it may serve a future run.
• Activation is atomic for future runs. Existing runs retain a lease on their original immutable generation until terminal finalization.
• Failed candidates never alter the active generation. Old generations drain within a bound and are forcibly terminated only with explicit uncertainty reporting.
• Startup, message, stderr, call, cancellation, restart, drain, and shutdown are count/time/byte bounded. Crash replay is never automatic for a mutating tool whose outcome is uncertain.
• Initial plugin/v1 exposes tools only. Providers and portable views require additive protocol revisions; compiled stages and executable UI code are permanently excluded.

Cross-language conformance

Independent Go and Python 3.12+ fixtures implement the same public protocol. The Python fixture uses locked grpcio and Protobuf dependencies, starts from a clean environment, and passes the host-owned conformance suite without importing private Go implementation details.

Developer-loop contracts

spice dev watches daemon and terminal targets, debounces deterministic generation/builds, restarts them independently, and preserves the last-known-good process when a new generation fails. Diagnostics identify source locations and the active/failed generation; no partial generated tree is activated.

Implementation slices

1. Freeze plugin/v1 with Buf lint/breaking checks.
2. Implement manifest/digest verification and the fallback direct launcher.
3. Add generation manager, candidate handshake, atomic activation, leases, bounded stderr, restart policy, drain, and cleanup.
4. Provide optional Spice auto-configuration that decorates/injects the dynamic tool source through normal static DI.
5. Ship Go and Python echo/filesystem-neutral fixture tools and conformance CLI.
6. Integrate last-known-good spice dev for generated daemon/TUI targets.

Exclusions

Plugins are trusted native processes, not sandboxes. Capability declarations are input to later policy; they do not enforce security. Plugins cannot alter static DI, register compiled stages, contribute native widgets, listen remotely, or trigger hidden downloads/installations.

Verification

• Tests cover wrong digest, path swap, handshake secret, old/new protocol, malformed/oversized messages, stdout contamination, bounded stderr, timeout, cancellation, and process-tree cleanup.
• Crash scenarios include handshake, call, activation, drain, and shutdown. Candidate failures preserve the active generation; leased runs keep the old generation; uncertain mutating calls are never replayed.
• Conformance executes identical cases against Go and Python on Windows and Linux, including cancellation and unknown fields.
• Developer-loop tests change valid/invalid sources rapidly, prove debounce, byte-identical generation, independent restart, diagnostic stability, and last-known-good continuity.

Performance and completion evidence

Plugin handshake and activation budgets are baselined separately from tool work. Local call overhead targets the daemon event-latency budget and must not add an unbounded queue. Evidence includes digests, generation/lease timelines, process logs, conformance versions, and failure-injection results.

Status is in progress. The execution-outcome and kernel plan-lease prerequisites are implemented; plugin protocol, process-generation manager, fixtures, and developer loop remain pending.