eric/weatherreporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Add secure prompt debug storage

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-31 04:20:30 +00:00
parent a52a6ed22a
commit 6064af2295
3 changed files with 681 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/internal/state.md
View File

@@ -19,6 +19,8 @@ the paths safe to use below the configured workspace.
| 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` |
| Render preflight | `preflight/<group>/<date>/render.<run-id>.json` |
| Notification record | `notifications/<group>/<date>/distributor.<run-id>.json` |
| Managed report | `reports/<group>/<date>/report.<run-id>.md` |
@@ -40,17 +42,37 @@ single-report artifact identifiers.
## Metadata and durable writes
`Metadata` is the durable inventory for a run. It records its schema version,
run identity, generated and valid timestamps, artifact group, source
content and provenance, and the module snapshot, data-package, preflight,
report, generated-artifact, and notification locations when present.
run identity, generated and valid timestamps, artifact group, source content
and provenance, and the module snapshot, data-package, prompt preparation,
prompt execution, report, generated-artifact, and notification locations when
present. New prompt records use `weatherreporter.metadata.v2`; historic
`weatherreporter.metadata.v1` records remain readable and retain their legacy
JSON field names when inspected.
`BuildMetadataFromBriefingMetadata` establishes the common fields; the
application adds locations as artifacts are produced. `SaveMetadata` requires
the run ID and the module snapshot, data-package, preflight, and metadata
paths. The package also saves module snapshots, data packages, preflight
records, generated-text artifacts, render contexts, and notifications. JSON
writes use `fileutil.WriteJSONAtomic`, so readers do not observe a partially
written state file.
`BuildMetadataFromBriefingMetadata` establishes legacy common fields, while
`BuildPromptMetadataFromBriefingMetadata` establishes the V2 record. The
application adds locations only after the corresponding artifacts are
produced. `SaveMetadata` requires the run ID, module snapshot, data package,
metadata path, and the matching preparation reference for its schema. The
package also saves module snapshots, data packages, prompt preparation and
execution records, legacy preflight records, generated-text artifacts, render
contexts, and notifications. JSON writes use atomic replacement, so readers do
not observe a partially written state file.
## Explicit prompt debug storage
`PromptDebugWriter` is a separate, opt-in boundary for content-rich prompt
diagnostics. It is constructed with an explicit absolute operator root, rather
than a workspace-derived path. A blank root produces a disabled writer that
does not access the filesystem.
Enabled debug captures are grouped as
`<root>/<report-id>/<valid-date>/<run-id>/` and contain `preparation.json` and
`execution.json`. The writer rejects symlinks, unsafe path segments, path
escape, and non-directory roots; it creates its directories with `0700` and
writes files atomically with `0600`. Normal state discovery and inspection do
not read this root. Its wire records map only approved project-owned fields;
credentials and dependency objects are not persisted.
The data package itself follows the shared
[prompt-input contract](prompt-input.md). Report text, templates, and external