Document output cache and debug state model

docs/internal/state.md

@@ -0,0 +1,56 @@
+# Run State Internals
+
+This document describes the implementation collaborators behind output, cache,
+and debug state. User-visible fields belong in [Configuration](../config.md),
+and layouts and lifecycle belong in [Operations](../operations.md).
+
+## Composition
+
+`internal/cli` is the only physical-path composition root. It resolves the
+effective configuration, selects exact roots, allocates requested debug bundles,
+constructs cache collaborators, writes logical output files, and reports paths.
+Pipeline modules receive interfaces and request data, never output, cache, or
+debug roots.
+
+## Output And Cache
+
+The pipeline runner returns logical output files. The CLI places them beneath
+the selected output root with confined, atomic writes.
+
+`internal/framework/chunkplan` owns source-addressed plan storage, validation,
+and atomic publication. Its store is constructed only when the selected mode is
+not `bypass`.
+
+`internal/framework/checkpoint` owns checkpoint identity, manifests, payload
+codecs, loader, and recorder. The CLI constructs both loader and recorder only
+for a `--resume` invocation. The serialized
+`workspace_schema_version` identifiers are frozen wire-compatibility fields;
+they do not describe a current public state surface.
+
+`internal/core/fileio` provides confined atomic file writes used by state
+collaborators. The chunk-plan store retains its stronger entry validation.
+
+## Debug Bundles
+
+`internal/core/debugbundle` allocates an explicitly requested per-run bundle
+with `summary/` and `trace/` roots. `SummaryWriter` persists redacted command,
+resolution, run, warning, and failure artifacts. `internal/framework/debug`
+implements the pipeline-facing trace recorder under the trace root.
+
+The CLI allocates a bundle before pipeline resolution and treats requested
+summary or trace persistence failures as command failures. The pipeline's debug
+boundaries redact sensitive metadata and credential-shaped bytes while allowing
+application-owned trace material. Debug data is never a checkpoint source or
+cache input.
+
+## Tests To Inspect
+
+- `internal/cli/state_surfaces_test.go`: debug allocation and configuration
+  boundaries.
+- `internal/cli/state_hardening_test.go`: independent roots, reuse, failures,
+  permissions, cleanup, and redaction.
+- `internal/core/debugbundle/*_test.go`: bundle allocation and summary writes.
+- `internal/framework/checkpoint/*_test.go`: checkpoint serialization and
+  reuse.
+- `internal/framework/chunkplan/store_test.go`: plan envelope, confinement,
+  publication, and permissions.