# State Internals

This document describes the implemented filesystem state boundary.

## Purpose

`internal/state` owns durable artifact paths, atomic JSON writes, metadata, and
prior comparable snapshot lookup.

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

Outputs:

- briefing snapshot JSON
- prompt input data package JSON
- render preflight JSON
- Markdown report path
- metadata JSON
- prior comparable snapshot metadata when available
- prior briefing package when loaded by path
- recent report records for inspection
- metadata and data package lookup by RunID

## 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. Metadata is stored beside briefing snapshots by report group and
valid local date. Prior snapshot lookup reads metadata for the same valid local
date and returns the latest earlier compatible run. Daily Today and Daily
Tomorrow are compatible with each other; 3-Day Outlook is compatible with prior
3-Day Outlook snapshots; Weekend Outlook is compatible with prior Weekend
Outlook snapshots for the same weekend window. The store can load a briefing
snapshot by path for structured comparison. The store can list metadata-backed
report records and load metadata or data packages by RunID for inspection. The
store prepares the managed Markdown report path before `scriptorium run` writes
it.

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