57 lines
2.5 KiB
Markdown
57 lines
2.5 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. 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.
|