2.8 KiB
State Internals
internal/state owns safe workspace paths, atomic artifact writes, metadata,
prior-snapshot lookup, and read-only inspection. Operators should use the
operations guide for lifecycle and retention.
Artifact Paths
For each run, paths are grouped by artifact group and valid start date:
| Artifact | Location |
|---|---|
| Module snapshot | snapshots/<group>/<date>/modules.<run-id>.json |
| Metadata | snapshots/<group>/<date>/metadata.<run-id>.json |
| Data package | data-packages/<group>/<date>/data_package.<run-id>.yaml |
| Prompt preparation | preflight/<group>/<date>/prompt_preparation.<run-id>.json |
| Prompt execution | snapshots/<group>/<date>/prompt_execution.<run-id>.json |
| Raw generated text | snapshots/<group>/<date>/generated_text_raw.<run-id>.json |
| Validated generated text | snapshots/<group>/<date>/generated_text.<run-id>.json |
| Render context | snapshots/<group>/<date>/render_context.<run-id>.json |
| Managed report | reports/<group>/<date>/report.<run-id>.md |
| Notification | notifications/<group>/<date>/distributor.<run-id>.json |
Batch notification records are notifications/batches/<batch>/<local-date>/distributor.<batch-run-id>.json.
Metadata And Debug Storage
New metadata is weatherreporter.metadata.v2 and gains preparation and
execution paths only after those artifacts are saved. Legacy V1 records remain
readable; their historic preflight and generated-text-result fields are mapped
to the corresponding preparation and execution views during inspection. New
runs never write V1 records.
Prompt preparation and execution records are validated on both save and load. They require exact report/prompt identity, complete timing, internally consistent provenance, and status-appropriate validation or bounded classified errors. Completed preparation and execution provenance retain the selected logical profile ID and resolved backend/model, but never profile endpoints or credentials. Completed execution provenance keeps Promptkit's run identity distinct from the Weatherreporter run identity.
For a completed prompt run, the execution record is atomically replaced after each downstream artifact is saved. Its path set therefore records the raw and normalized generated text, render context, managed report, requested output copy, and notification artifact actually reached without changing the original Promptkit outcome.
PromptDebugWriter is separate from workspace state. An empty root disables
it. An enabled absolute root is checked for safe directories and symlinks, then
stores preparation.json and execution.json beneath
<root>/<report-id>/<valid-date>/<run-id>/. Directories are 0700; files are
atomic 0600. Normal state discovery does not read this root.
Focused checks:
go test ./internal/state