# 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
- rendered report path preparation

Outputs:

- briefing snapshot JSON
- prompt input data package JSON
- render preflight JSON
- Markdown report path
- metadata JSON
- prior Daily snapshot metadata when available
- prior Daily briefing package when loaded by path

## 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. The store can load a briefing snapshot
by path for structured comparison. 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.