Document internal component boundaries

docs/internal/state.md

@@ -1,13 +1,13 @@
 # State Internals
 
-This document describes the implemented filesystem state boundary.
+This document describes filesystem state in `internal/state`.
 
 ## Purpose
 
-`internal/state` owns durable artifact paths, atomic JSON writes, metadata, and
-prior comparable snapshot lookup.
+`internal/state` owns managed artifact paths, atomic JSON writes, persisted
+metadata, prior snapshot lookup, and read-only artifact inspection helpers.
 
-## Inputs and Outputs
+## Inputs And Outputs
 
 Inputs:
 
@@ -15,26 +15,27 @@ Inputs:
 - resolved report definition and valid period
 - briefing package
 - prompt input data package
-- `scriptorium render` result
-- rendered report path preparation
+- Scriptorium render result
+- rendered report path preparation request
+- RunID for inspection lookups
 
 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
+- 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
-- 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.
+- 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
 
@@ -47,25 +48,35 @@ Outputs:
 Workspace subdirectories must be relative paths that stay under
 `workspace.root`.
 
-## State Behavior
+## External Adapters Used
 
-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.
+- 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
 
-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.
+- 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
 
@@ -77,5 +88,5 @@ Inspect:
 ## Invariants
 
 - Managed paths stay under the configured workspace root.
-- Metadata links the artifacts produced for a run.
+- Metadata links artifacts produced for a run.
 - Prior lookup is based on structured metadata, not rendered report text.