Add filesystem state metadata baseline

docs/internal/state.md

@@ -0,0 +1,69 @@
+# 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.