# 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
- Scriptorium render result
- 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, 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 report family and valid-period start date for JSON
artifacts. Reports are written under the report 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 and selects the latest earlier compatible
snapshot. 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.

## 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.