ADR 0010: Two-stage recoverable self-hosting

Ownership update: ADR 0012 moved every implementation path below to the standalone github.com/spice-framework/toolchain module. The architectural decision remains active for that repository and is no longer implemented in core.

Status: Accepted

Context

Spice should use its own application model for Spice-owned applications and libraries. Making the only compiler executable depend on generated output, however, would create a bootstrap cycle: a missing or damaged generated target could require that same target in order to regenerate it.

The production command also needs to prove real framework value rather than wrapping its existing dispatch behind a cosmetic annotation. It must exercise typed construction, imported library defaults, module validation, lifecycle, generated source mapping, and typed test replacement.

Decision

Spice uses two executable stages:

• cmd/spice-bootstrap is an ordinary-Go recovery compiler. It imports internal/cli and compiler packages but no generated application package.
• cmd/spice is the production application. It imports the committed internal/spicegen/spice target, constructs and starts it, invokes its typed Command component, and stops it with a fresh bounded context.

internal/spiceapp owns the application marker and module declaration. internal/autoconfigure contributes the reviewed fallback runtime, 13 independent CLI handler factories, and the command factory through an explicit blank import. The generated target constructs each handler as a distinct interface bean, injects the ordered []cli.Handler collection into the command, and exposes every node through typed Components and BeanOverrides.

The compiler, CLI, development loop, guarded generator filesystem, LSP, and application marker declare an executable Modulith canvas. Compiler packages consumed across a module boundary are explicit named interfaces. Canonical auto-configuration descriptors stay auxiliary and cannot contribute module metadata.

Compiler, generator, CLI implementation, and guarded-filesystem packages may not import the production generated target. The repository bootstrap gate audits that stage zero has no generated dependency and stage one has exactly the spice generated target tree. It verifies target freshness using both executables and retains an isolated zero-output deterministic recovery proof.

Boundaries

• Stage zero is recovery infrastructure, not a second product implementation.
• Both commands delegate to the same internal/cli behavior.
• Stage zero assembles the same exported runtime and handler factories manually; stage one obtains them through generated dependency injection.
• Generated construction performs no reflection, runtime package scan, global registration, or string-based lookup.
• The production manifest and generated Go are committed and guarded by normal ownership checks.
• Missing production output must always be recoverable with stage zero and the repository vendor graph while network access is disabled.

Consequences

• Spice’s shipped command exercises the same generated application contract offered to users.
• Self-hosting cannot strand the compiler behind its own generated output.
• CLI application tests use exact typed overrides and normal lifecycle cleanup.
• A typed handler override must flow into the generated interface collection, and production LSP/configuration behavior must execute through that graph.
• Any production graph change must regenerate the Spice target and pass both dependency audits.
• Parser, type checker, and renderer packages remain ordinary Go rather than being forced into runtime bean semantics.