96 lines
2.5 KiB
Markdown
96 lines
2.5 KiB
Markdown
# Prompt Input Internals
|
|
|
|
This document describes YAML prompt data package construction in
|
|
`internal/promptinput`.
|
|
|
|
## Purpose
|
|
|
|
`internal/promptinput` converts report metadata, an ordered module snapshot,
|
|
Recent Changes, and source warnings into the `data_package` file passed to
|
|
Scriptorium.
|
|
|
|
The persisted data package is YAML with schema version
|
|
`weatherreporter.data_package.v2`. It is separate from the JSON module snapshot
|
|
used for inspection and comparison.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Inputs:
|
|
|
|
- report metadata from app/state orchestration
|
|
- `module.Snapshot`
|
|
- optional `[]changes.Change`
|
|
|
|
Outputs:
|
|
|
|
- `promptinput.Package` with schema version, RunID, report metadata, named
|
|
module stanzas, Recent Changes, and source warnings
|
|
- YAML bytes from `promptinput.MarshalYAML`
|
|
- YAML file written atomically by `promptinput.Save`
|
|
|
|
The YAML shape includes:
|
|
|
|
```yaml
|
|
schema_version: weatherreporter.data_package.v2
|
|
run_id: <run_id>
|
|
report:
|
|
id: <report_id>
|
|
prompt_id: <prompt_id>
|
|
briefing:
|
|
metadata: {}
|
|
current_conditions: {}
|
|
recent_changes:
|
|
items: []
|
|
```
|
|
|
|
The `briefing` mapping contains named module stanzas. Stanza order follows the
|
|
module snapshot output order.
|
|
|
|
## Boundaries
|
|
|
|
- This package owns prompt package schema, YAML marshaling, YAML loading, and
|
|
validation.
|
|
- It does not fetch weather data, derive forecast summaries, execute modules,
|
|
find prior snapshots, compare changes, choose artifact paths, or invoke
|
|
Scriptorium.
|
|
|
|
## Config Fields Used
|
|
|
|
None directly. Config-derived values such as timezone, units, and prompt
|
|
location are already present in report metadata and module stanzas before this
|
|
package runs.
|
|
|
|
## External Adapters Used
|
|
|
|
None.
|
|
|
|
## State Or Manifest Behavior
|
|
|
|
`promptinput.Save` writes YAML atomically. Managed workspace paths are owned by
|
|
`internal/state`.
|
|
|
|
## Skip And Resume Behavior
|
|
|
|
None. Recent Changes is always present as an `items` list and may be empty.
|
|
|
|
## Failure Behavior
|
|
|
|
Validation fails before render preflight when required top-level fields are
|
|
missing or inconsistent, when the valid period is invalid, or when no module
|
|
stanzas are present. Save failures include filesystem operation and path
|
|
context.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/promptinput/package_test.go`
|
|
- `internal/app/app_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Scriptorium receives structured YAML through `--input data_package=<path>`.
|
|
- Module stanza order is deterministic for generated snapshots.
|
|
- Recent Changes are provided by `internal/changes`; this package does not
|
|
infer changes from rendered report text.
|