# Spice self-hosting and recovery

Spice dogfooding is a toolchain acceptance concern. Its implementation, generated
production target, compiler/CLI packages, development loop, bootstrap compiler,
and performance budgets live in
[`spice-framework/toolchain`](https://github.com/spice-framework/toolchain).
This core repository retains the public contracts that the generated toolchain
application consumes.

## Two-stage boundary

The standalone toolchain has two explicit stages:

```text
ordinary-Go stage-zero bootstrap
    -> compiler + generator + guarded filesystem
    -> regenerates/checks the committed production target

production Spice CLI
    -> imports only its committed generated target
    -> uses typed generated construction and direct calls
```

Stage zero must never import generated application packages. The production
entrypoint imports only its dedicated generated target. Parser, type checker,
renderer, LSP, and guarded filesystem code remain ordinary Go implementation;
dogfooding does not pretend they are runtime-managed beans.

## Required toolchain proof

The toolchain repository's complete gate must:

1. build stage zero with Go 1.26.5, `-trimpath`, and offline product inputs;
2. reject generated-application dependencies in the stage-zero graph;
3. verify the committed production target and its source mirrors are fresh;
4. build the stage-one CLI as a complete package, never a temporary source
   fragment;
5. run version, annotation, bean-explanation, module, generation, build, Run,
   Debug, LSP, and development-loop paths;
6. generate an isolated valid-Go application from zero owned output;
7. snapshot its manifest and generated bytes, remove only owned output, and
   reproduce it byte-for-byte;
8. reject manual edits, collisions, symlink escapes, stale ownership, and
   invalid annotation source;
9. damage the toolchain's generated target, recover it with stage zero, and
   reproduce the accepted bytes;
10. run shuffled/race tests, coverage, fuzz, security, offline, and reviewed
    latency/allocation budgets.

A failed generation never replaces the last-known-good process. Run and Debug
operate on the complete package with generated files and must never emit naked
`@`, omit the generated entry seam, or route through a `gocommand-*`
single-file fragment.

## Generated debugging contract

The production target uses the same consuming-application layout documented in
[`application.md`](/framework/application/). Stable subsystem files keep construction
and lifecycle code readable. Every handwritten source unit that requires
annotation-derived glue has one deterministic mirror below
`internal/spicegen/<target>/sources`. Generated interface assertions and
source provenance live in those mirrors rather than cluttering handwritten
library code.

The ownership manifest is not plugin selection or runtime metadata. It records
only generated paths and digests so removal and recovery stay bounded.

## Dependency-injection dogfood

The production CLI is assembled from explicit provider factories and typed
interface bindings. Its generated graph must prove:

- exact constructor selection and direct calls;
- typed `@Implements` candidates and generated method-set assertions;
- deterministic qualifier, primary/fallback, collection, and name selection;
- immediate cleanup registration and reverse rollback/shutdown;
- no reflection, service locator, runtime scan, or global mutable container;
- a typed component snapshot usable by black-box tests.

The toolchain's bean-explanation and source-navigation commands expose why each
candidate was selected and map handwritten declarations to generated adapters.

## Application and editor evidence

[`spice-framework/petclinic`](https://github.com/spice-framework/petclinic)
and [`spice-framework/commerce`](https://github.com/spice-framework/commerce)
own complete consumer workflows against immutable core and toolchain versions.
They prove generation, configuration, modules, web, security, data, lifecycle,
mail, failure behavior, generated-source inspection, and focused testing.

[`spice-framework/goland`](https://github.com/spice-framework/goland) owns
installed-plugin Windows/Linux proof for concealment, syntax colors, completion,
documentation, navigation, whole-package Run, and native Go/Delve Debug.
[`spice-framework/zed`](https://github.com/spice-framework/zed) owns its
secondary LSP adapter contract.

## Core responsibility

This repository does not run toolchain dogfood, bootstrap, CLI smoke, editor UI,
or generated-target freshness gates. Its `make verify` proves the 51 public
annotation/runtime/test-support packages, standard-library-only module graph,
API maturity and architecture boundaries that the external dogfood consumes.
Cross-repository release readiness is coordinated against exact immutable
revisions by
[`spice-framework/development`](https://github.com/spice-framework/development).