70 lines
1.8 KiB
Markdown
70 lines
1.8 KiB
Markdown
# State Internals
|
|
|
|
This document describes the implemented filesystem state boundary.
|
|
|
|
## Purpose
|
|
|
|
`internal/state` owns durable artifact paths, atomic JSON writes, metadata, and
|
|
prior Daily snapshot lookup.
|
|
|
|
## Inputs and Outputs
|
|
|
|
Inputs:
|
|
|
|
- workspace configuration
|
|
- resolved report definition and valid period
|
|
- briefing package
|
|
- prompt input data package
|
|
- `scriptorium render` result
|
|
|
|
Outputs:
|
|
|
|
- briefing snapshot JSON
|
|
- prompt input data package JSON
|
|
- render preflight JSON
|
|
- metadata JSON
|
|
- prior Daily snapshot metadata when available
|
|
|
|
## Boundaries
|
|
|
|
- This package owns managed workspace layout and narrow path validation.
|
|
- It does not fetch weather data, derive forecasts, build prompt inputs, invoke
|
|
`scriptorium`, or compare briefing contents.
|
|
|
|
## Config Fields Used
|
|
|
|
- `workspace.root`
|
|
- `workspace.snapshots_dir`
|
|
- `workspace.reports_dir`
|
|
- `workspace.data_packages_dir`
|
|
- `workspace.preflight_dir`
|
|
|
|
Workspace subdirectories must be relative paths that stay under
|
|
`workspace.root`.
|
|
|
|
## State Behavior
|
|
|
|
Managed artifact names use RunID, which is generated from report generation time
|
|
and report ID. Daily metadata is stored beside Daily briefing snapshots by valid
|
|
local date. Prior Daily snapshot lookup reads metadata for the same valid local
|
|
date and returns the latest earlier run.
|
|
|
|
## Failure Behavior
|
|
|
|
Writes are atomic where practical: JSON is written to a temporary file in the
|
|
target directory and then renamed into place. Invalid workspace paths and
|
|
missing required metadata fields produce actionable errors.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/state/filesystem_test.go`
|
|
- `internal/app/app_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Managed paths stay under the configured workspace root.
|
|
- Metadata links the artifacts produced for a run.
|
|
- Prior lookup is based on structured metadata, not rendered report text.
|