59 lines
2.8 KiB
Markdown
59 lines
2.8 KiB
Markdown
# 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](../operations.md) 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:
|
|
|
|
```sh
|
|
go test ./internal/state
|
|
```
|