68 lines
3.2 KiB
Markdown
68 lines
3.2 KiB
Markdown
# 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. After validating every
|
|
logical name, the CLI exclusively creates the run directory beneath the
|
|
selected output root and performs confined, atomic file writes within it.
|
|
|
|
`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 a recorder whenever checkpoint
|
|
recording is enabled and constructs a loader 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.
|
|
|
|
After allocation, one CLI-owned state value accumulates the known report paths,
|
|
pipeline outcome counts, and validation status. A single guarded terminalization
|
|
operation writes the success report, or makes one attempt each to write the
|
|
failure report and error log. Terminal persistence failures are reported
|
|
separately and never replace the command's primary error.
|
|
|
|
## Tests To Inspect
|
|
|
|
- `internal/cli/run_contract_test.go`: command-owned state allocation,
|
|
terminalization, and output/report boundaries.
|
|
- `internal/cli/state_hardening_test.go`: independent roots, reuse, failures,
|
|
permissions, cleanup, and redaction.
|
|
- `internal/cli/production_contract_test.go`: production composition and
|
|
configuration validation at the CLI boundary.
|
|
- `internal/cli/example_contract_test.go`: maintained example ownership.
|
|
- `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.
|