# ADR 0001: The Spice Graph Is the Only Compiled Extension Graph

- **Status:** accepted
- **Date:** 2026-08-06
- **Scope:** all Spice Agent repositories

## Context

An early design proposed an agent-specific compiled extension manifest and
`RuntimeGraph` that would select stages, providers, tools, and UI components
beside Spice. That would create two dependency systems, two diagnostic models,
and two answers to which implementation an application executes.

Spice already provides exact interface binding, explicit `@Implements`, bean
names and aliases, qualifiers, primary/fallback selection, ordered collections,
scopes/lifecycle, module boundaries, starter manifests, explicit
auto-configuration, generated source mappings, and test overrides.

## Decision

The generated Spice bean graph is the sole compiled composition graph. Agent
annotations may provide ergonomic domain spelling, but their handlers emit only
generic Spice contributions. Static application dependencies are visible as
ordinary direct-call generated Go and are immutable after construction.

Compiled extension modules activate defaults only through explicit
`/autoconfigure` blank imports. Defaults are fallback beans. Application code
resolves multiple candidates through the normal typed primary/qualifier rules.
Ordered typed collections implement decoration; canonical bean names identify
static tool maps.

Runtime plugin generations remain separate because their processes do not exist
at compile time. One statically injected host/decorator owns that dynamic graph.
It may contribute leased runtime tools for future runs but never mutate Spice
DI, add compiled stages, or load executable UI code.

## Prohibited designs

- `extension.Manifest`, compiled `RuntimeGraph`, stage/provider/tool selection
  maps, mutable bean registries, service locators, or reflection-based lookup;
- package scanning or automatic interface discovery from ambient dependencies;
- compiler switches on agent annotation names instead of descriptor handler
  contributions;
- runtime plugin APIs that register static beans or native UI implementations.

Architecture tests search source/imports for these concepts and generated
fixtures prove the actual selected graph.

## Consequences

Positive consequences are one source of diagnostics, native Go navigation,
inspectable/debuggable generated code, deterministic selection, reusable Spice
testing, and no runtime compiler/container dependency.

The cost is that third-party static extensions must publish annotations,
descriptors, explicit interface bindings, and auto-configuration instead of one
untyped registration function. Dynamic needs require a process protocol and
cannot silently alter in-flight runs.

## Reconsideration rule

This decision may be revisited only by a generic Spice RFC demonstrating a
cross-domain capability the current typed contribution model cannot express.
Agent-specific convenience or schedule pressure is not sufficient evidence.