# RFC 0001: Deterministic Kernel Boundary

- **Status:** accepted for preview
- **Applies to:** `github.com/spice-framework/spice-agent`
- **Stability:** pre-1.0

## Problem

Agent frameworks tend to accumulate provider clients, tool registries, UI state,
persistence, permission policy, and worker scheduling in one mutable runtime.
That makes deterministic testing and safe extension difficult and would bypass
Spice's generated dependency graph.

## Decision

The kernel owns only provider-neutral immutable values and one deterministic
single-agent state machine. `Engine.Start` receives a validated definition and
input. Providers, the canonical tool dispatcher, identifiers, clock, interaction
broker, required observers, and best-effort observers are constructor-injected
typed beans. The engine never receives or exposes a service registry.

The kernel owns:

- immutable run, turn, message, model-operation, tool-call, and interaction IDs;
- bounded messages and model/tool contracts;
- turn/tool-loop state transitions;
- event sequencing and authoritative replay;
- cancellation and panic containment;
- exactly-once lifecycle terminal finalization;
- provider-neutral safe snapshots and import validation;
- immutable static and leased dynamic execution-plan identity per run.

Provider implementations, tool implementations, daemon transport, UI,
persistence, approval policy, sandboxing, Git/MCP/indexing/telemetry, and
multi-agent scheduling remain outside the kernel.

## Trust and failure semantics

Providers and compiled tools are trusted concurrent in-process beans. Context
cancellation is cooperative; the kernel cannot force a function that ignores
context to return. Panics are contained at provider, stream, dispatcher, and
engine boundaries and normalized into terminal failure.

Each run acquires a `ToolPlanLease` after input validation and before ID
allocation or event mutation. The host snapshots definitions; the trusted
source guarantees stable executable behavior under a non-reusable `PlanID`.
All model requests and calls for that run use the leased dispatcher. Generated
compiled compatibility is checked before exact-plan resume and import mutation.
Release callbacks are non-blocking reference decrements; source draining is
asynchronous. The engine nevertheless bounds release, and timeout or failure
forces the single authoritative `RunFailed` event, snapshot status, and `Wait`
result.

All executable tools traverse one injected `ToolDispatcher`. The dispatcher
publishes an immutable capability/definition snapshot and validates active call
and progress correlation. Definitions explicitly classify external-state
effect and replay safety; capabilities form an unordered set returned in
canonical lexical order. Read-only definitions reject mutation-capable
filesystem, process, network, and environment capabilities. No tool may retain
a reporter after execution.

`tool.Tool.Execute` returns `(tool.Result, error)`. A valid `Result` whose
problem is set is model-visible terminal tool data and may continue the model
loop. An infrastructure failure returns a zero result and exactly one direct,
bounded, call-correlated `*tool.ExecutionError`; wrappers and joined siblings
are rejected. The error distinguishes a definitive
failure from an uncertain mutation outcome and supplies validated retry advice.
The dispatcher rejects untyped, uncorrelated, contradictory, or result-plus-error
outcomes and preserves `errors.Is` cancellation/deadline semantics.
A successfully returned, valid correlated result remains authoritative when
cancellation races after tool commit. Conversely, an extension returning a
cancellation sentinel while the run context remains active is an ordinary run
failure; lifecycle cancellation is derived only from authoritative context
state.

`Tool.Execute` itself must return exactly one direct `ExecutionError`. If a
progress reporter also failed, the dispatcher returns a bounded structured
`stage.DispatchFailure`: ordinary unwrapping reaches only the authoritative
execution outcome, while `ReporterFailure` exposes required-observer durability
for explicit two-step inspection without contaminating `errors.Is` cancellation.

Local event commit precedes required-observer acknowledgement. Once committed,
a sequence is never reused even if an observer reports failure. Bounded terminal
finalization uses a context independent of caller cancellation and surfaces a
typed durability error when completion cannot be established.

## Dependency rules

Kernel packages may depend on other provider-neutral core packages and the Go
standard library. They may not import OpenAI, coding tools, gRPC, Protobuf,
Bubble Tea, OS IPC, SQLite, Spice compiler/CLI entrypoints, or distribution
packages. Architecture tests enforce the direction.

## Rejected alternatives

- A runtime bean factory or service locator duplicates Spice and hides exact
  dependencies.
- A compiled `RuntimeGraph` permits wiring to differ from generated Go.
- Provider-specific message fields force all consumers to inherit provider churn.
- Kernel parent/child agent concepts prematurely constrain orchestration.
- Reflection dispatch weakens navigation, compile-time checks, and debugging.

## Consequences

Extension authors sometimes write small adapters or decorators instead of
registering arbitrary runtime objects. In exchange, embedded tests construct the
entire engine with ordinary Go, generated applications are inspectable, and
provider/tool/transport implementations evolve independently.

## Acceptance evidence

The boundary is proven only when a real provider, compiled tool, runtime tool,
required persistence observer, alternate client, and two-worker extension pass
without adding implementation concepts to the kernel. Dependency scans, race
tests, cancellation/panic tests, snapshot round trips, and generated DI source
are retained in the phase ledger.