98 lines
3.0 KiB
Markdown
98 lines
3.0 KiB
Markdown
# State Internals
|
|
|
|
This document describes filesystem state in `internal/state`.
|
|
|
|
## Purpose
|
|
|
|
`internal/state` owns managed artifact paths, atomic JSON writes, persisted
|
|
metadata, prior snapshot lookup, and read-only artifact inspection helpers.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Inputs:
|
|
|
|
- workspace configuration
|
|
- resolved report definition and valid period
|
|
- briefing package
|
|
- prompt input data package
|
|
- preflight artifact
|
|
- rendered report path preparation request
|
|
- RunID for inspection lookups
|
|
|
|
Outputs:
|
|
|
|
- briefing snapshot JSON path
|
|
- prompt input data package JSON path
|
|
- render preflight JSON path
|
|
- managed Markdown report path
|
|
- metadata JSON path
|
|
- prior comparable snapshot metadata
|
|
- loaded briefing or data package
|
|
- recent report records for inspection
|
|
|
|
## Boundaries
|
|
|
|
- This package owns managed workspace layout, path validation, filesystem
|
|
writes, and metadata reads.
|
|
- It does not fetch weather data, derive forecasts, build prompt input content,
|
|
compare briefing contents, invoke Scriptorium, import adapter result types, or
|
|
parse CLI flags.
|
|
|
|
## 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`.
|
|
|
|
## External Adapters Used
|
|
|
|
- local filesystem
|
|
|
|
## State Or Manifest Behavior
|
|
|
|
Managed paths are grouped by the report definition's artifact group and
|
|
valid-period start date for JSON artifacts. Reports are written under the same
|
|
artifact group. Metadata is stored beside briefing snapshots and links
|
|
briefing, data package, preflight, and report paths. Report listing walks
|
|
metadata files under the snapshots directory.
|
|
|
|
Prior snapshot lookup reads metadata through the shared lookup path and selects
|
|
the latest earlier snapshot whose report ID is compatible according to the
|
|
current report definition. Daily Today and Daily Tomorrow are compatible with
|
|
each other for the same valid local date. 3-Day Outlook compares with prior
|
|
3-Day snapshots for the same valid local date. Weekend Outlook compares with
|
|
prior Weekend snapshots for the same weekend window. Storm Report currently has
|
|
no prior lookup because its comparison strategy is not searched by the
|
|
filesystem store.
|
|
|
|
## Skip And Resume Behavior
|
|
|
|
There is no resume workflow. Missing metadata directories return no inspection
|
|
records or no prior snapshot rather than creating state.
|
|
|
|
## Failure Behavior
|
|
|
|
- Invalid workspace paths return validation errors.
|
|
- Missing required metadata fields prevent metadata writes.
|
|
- JSON writes use a temporary file followed by rename where practical.
|
|
- Read and decode failures include path context.
|
|
- Unknown RunIDs produce an actionable lookup error.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/state/filesystem_test.go`
|
|
- `internal/app/app_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Managed paths stay under the configured workspace root.
|
|
- Metadata links artifacts produced for a run.
|
|
- Prior lookup is based on structured metadata, not rendered report text.
|