# RFC 0003: Spice-Native Stage and Tool Model - **Status:** accepted for preview - **Depends on:** ADR 0001 and Spice typed DI contracts ## Decision Stages are generic exact transforms: `Stage[Input, Output].Process(context.Context, Input) (Output, error)`. Each instantiation is a distinct Go interface resolved at generated construction time, not a universal middleware type. Executable tools are likewise narrow Go interfaces. Replaceable defaults are fallback beans. Application or starter implementations are normal candidates; ambiguity requires an application-owned typed primary or qualifier. Decoration uses ordered typed collections and never mutates an existing bean registry. The default stage pipeline is a constructor-injected immutable slice. Ordering uses Spice `@Order`, then canonical bean name and source position for deterministic diagnostics. A stage receives only its typed input, output, and context; it cannot look up other stages or tools by arbitrary runtime string. Tools are exposed to models as immutable definitions but execute only through one `ToolDispatcher`. The dispatcher owns a canonical map built from `map[string]tool.Tool` injection, rejects name/definition mismatches, snapshots definitions for each model request, enforces call/progress correlation, contains panics, and preserves cancellation. Policy, telemetry, retry, and runtime-plugin support are ordered typed dispatcher decorators. `ApplyToolDispatchDecorators` applies the already Spice-ordered collection to the merged dispatcher: the first decorator is outermost. Nil, panicking, nil-returning, and definition-changing decorators fail construction. Every wrapper is guarded by the same immutable definition snapshot, so it cannot dispatch an undeclared tool. Each definition has mandatory `Effect` (`read_only` or `mutating`) and `ReplaySafety` (`safe`, `idempotent`, or `unsafe`) metadata. Capabilities are an unordered set normalized to lexical order before storage, cloning, fingerprinting, or exposure. Read-only tools must be replay-safe and cannot declare `filesystem.write`, `process.execute`, `network.access`, or `environment.write`; contradictory metadata fails dispatcher construction. Replay-safe is reserved for read-only tools; mutating tools must declare either idempotent or unsafe replay. `Execute(context.Context, tool.Call, tool.Reporter)` returns `(tool.Result, error)`. A problem result is a completed, model-visible tool outcome. A Go error is infrastructure failure and must itself be exactly one valid `*tool.ExecutionError` correlated to the active call. Error wrappers, joins, and sibling failures are rejected so unbounded or unrelated data cannot bypass validation. The dispatcher rejects a simultaneous result and error, untyped errors, mismatched call IDs, uncertain outcomes from read-only tools, and retry advice for replay-unsafe tools. Uncertain outcomes always prohibit retry. Accepted typed errors are returned without replacing their error chain, so cancellation remains discoverable through `errors.Is`. When progress reporting and execution both fail, the dispatcher returns one generic-text `DispatchFailure`. Its normal unwrap path contains only the validated execution failure; reporter durability is available explicitly via `ReporterFailure` and cannot inject a cancellation sentinel into `errors.Is`. ## Annotation mapping `@Stage`, `@Tool`, and `@ModelProvider` descriptors emit only existing generic Spice provider and bean metadata contributions: name, aliases, qualifiers, fallback/primary, and order. Exact interface-returning factories need no interface-binding contribution. The ordinary Go signature establishes the typed boundary and may use the standard optional cleanup/error provider forms; handlers do not guess assignability from readable type strings. The generic compiler remains authoritative for exact identity, aliases, cleanup, and error forms. They do not emit an agent registry entry. Descriptor handlers are typed Go functions in canonical files and the compiler consumes only generic contributions. ## Dynamic tools The compiled graph may contain one runtime-plugin-backed `ToolPlanSource`. A source leases either its current immutable plan for a new run or one exact `PlanID` for snapshot recovery. A lease owns a dispatcher, canonical defensive copies of its definitions, and an idempotent observable release. An ID must never be reused for changed definitions or behavior. The kernel validates source results, releases a lease returned alongside an error or wrong ID, and contains source/decorator/definition panics without exposing recovered text. `StaticToolPlanSource` adapts an ordinary compiled dispatcher for embedded applications. The source—not Go structural copying—guarantees behavior remains stable while leased. Release callbacks only decrement references and must not block; drain and process shutdown are source-owned asynchronous work. Dynamic tools do not add compiled stages or mutate static DI. ## Rejected alternatives - String-keyed runtime stage registries hide type errors and source navigation. - Universal middleware functions erase lifecycle and capability contracts. - Allowing tools to publish events directly bypasses canonical sequencing and future permission interception. - Automatic interface scanning makes dependency selection dependent on ambient packages rather than source declarations. ## Acceptance Generated fixtures prove fallback replacement, deterministic ambiguity, typed primary/qualifier resolution, ordered decorators, named tool maps, test overrides, capability snapshots, panic/cancellation, and absence of registry/reflection source. A future permission stress prototype must intercept every executable route without kernel changes. The in-module `CompositionProof` target is the canonical compiled-composition fixture. It returns exact aliased interfaces from the agent annotations, uses the official typed `@Primary` and parameter `@Qualifier` metadata, and commits the ordinary generated graph, ownership manifest, and source mappings. Its application tests execute construction, selection, ordered transforms, canonical map injection, typed override, rollback, and reverse cleanup. The separate negative fixtures are compiled by the real CLI and retain stable source-positioned diagnostics.