# ADR 0007: Guarded Generated-File Ownership

> **Ownership update:** the guarded filesystem implementation lives in
> `github.com/spice-framework/toolchain`; this ADR remains its behavioral
> contract.

Status: Accepted (amended for manifest schema 5)

## Decision

`internal/genfs` is the only normal filesystem application layer for a
`compiler/generate.Plan`. It uses Go's rooted filesystem API and treats the
manifest as an ownership record, not a cache.

Before writing, it validates:

- an absolute selected module root and clean module-relative slash paths;
- no parent traversal, Windows device names, case-fold collisions, or
  manifest/output overlap;
- exact agreement between plan files, hashes, and manifest entries;
- no symlink in an existing output or manifest path component;
- a supported manifest schema and exact target identity;
- prior owned-file hashes and generated markers;
- absence of unowned expected-path collisions and unexpected unowned Spice
  generated markers.

Normal generation refuses to replace a manually edited owned file, refuses even
a byte-identical file without manifest ownership, and removes a stale file only
when its bytes still match the prior manifest and retain the generated marker.
Legacy generated-package ownership, schema-3 adjacent source shards, and the
schema-4 target monolith can migrate to the schema-5 concern-decomposed
application-package layout only when target identity is canonical and every
old owned file is unchanged; a manual edit blocks the migration.

## Apply protocol

One target lock is created with exclusive creation under `.spice/`. After
locking, state is re-read and validated. Changed files are written to
same-directory exclusive temporary files, synced, parsed when Go source,
hash-verified, and replaced with backup restoration on failure. Unchanged files
and manifests are not rewritten, preserving mtimes. The manifest is replaced
last as the commit marker.

The protocol is guarded and recoverable but is not described as a globally
atomic multi-file transaction.

## Commands

- `spice generate` renders and safely applies one selected application.
- `spice generate --check` is read-only and exits nonzero for any difference.
- `spice generate --diff` is read-only and prints a bounded deterministic diff.
- `spice build` safely generates, then runs `go build -trimpath ./...` in the
  selected module.

Generated files use `//go:build !spice_generate`. Spice reserves the
`spice_generate` tag for generation analysis and merges it with
caller/`GOFLAGS` tags so targeted regeneration can exclude stale output.
Verification and annotation listing load the ordinary committed program,
including generated dependencies imported by commands.