2026-05-29 17:40:38 +00:00
|
|
|
# State Internals
|
|
|
|
|
|
2026-07-31 05:03:02 +00:00
|
|
|
`internal/state` owns safe workspace paths, atomic artifact writes, metadata,
|
|
|
|
|
prior-snapshot lookup, and read-only inspection. Operators should use the
|
|
|
|
|
[operations guide](../operations.md) for lifecycle and retention.
|
2026-07-31 01:26:20 +00:00
|
|
|
|
2026-07-31 05:03:02 +00:00
|
|
|
## Artifact Paths
|
2026-07-31 01:26:20 +00:00
|
|
|
|
2026-07-31 05:03:02 +00:00
|
|
|
For each run, paths are grouped by artifact group and valid start date:
|
2026-07-31 01:26:20 +00:00
|
|
|
|
2026-07-31 05:03:02 +00:00
|
|
|
| Artifact | Location |
|
2026-07-31 01:26:20 +00:00
|
|
|
| --- | --- |
|
|
|
|
|
| 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` |
|
2026-07-31 04:20:30 +00:00
|
|
|
| Prompt preparation | `preflight/<group>/<date>/prompt_preparation.<run-id>.json` |
|
|
|
|
|
| Prompt execution | `snapshots/<group>/<date>/prompt_execution.<run-id>.json` |
|
2026-07-31 05:03:02 +00:00
|
|
|
| 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` |
|
2026-07-31 01:26:20 +00:00
|
|
|
| Managed report | `reports/<group>/<date>/report.<run-id>.md` |
|
2026-07-31 05:03:02 +00:00
|
|
|
| Notification | `notifications/<group>/<date>/distributor.<run-id>.json` |
|
2026-07-31 01:26:20 +00:00
|
|
|
|
2026-07-31 05:03:02 +00:00
|
|
|
Batch notification records are `notifications/batches/<batch>/<local-date>/distributor.<batch-run-id>.json`.
|
2026-07-31 01:26:20 +00:00
|
|
|
|
2026-07-31 05:03:02 +00:00
|
|
|
## Metadata And Debug Storage
|
2026-07-31 01:26:20 +00:00
|
|
|
|
2026-07-31 05:03:02 +00:00
|
|
|
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.
|
2026-07-31 01:26:20 +00:00
|
|
|
|
2026-07-31 05:03:02 +00:00
|
|
|
`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.
|
2026-07-31 04:20:30 +00:00
|
|
|
|
2026-07-31 05:03:02 +00:00
|
|
|
Focused checks:
|
2026-07-31 01:26:20 +00:00
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
go test ./internal/state
|
2026-05-29 20:49:19 +00:00
|
|
|
```
|
