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

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

2.3 KiB Raw Blame History