57 lines
2.4 KiB
Markdown
57 lines
2.4 KiB
Markdown
# Changes Internals
|
|
|
|
`internal/changes` deterministically compares a compatible prior module
|
|
snapshot with the current snapshot. It returns compact structured changes for
|
|
prompt input; it never reads state, finds a prior report, renders Markdown, or
|
|
compares generated text. Snapshot construction belongs to
|
|
[module internals](module.md), and prior-snapshot discovery belongs to
|
|
[state internals](state.md).
|
|
|
|
## Comparison inputs and output
|
|
|
|
Each comparator receives a prior snapshot, a current snapshot, and
|
|
`Thresholds`. A `Change` has a stable type and message plus previous and
|
|
current values where useful. Changes are sorted by type and then message, so
|
|
the same inputs always yield the same order.
|
|
|
|
Threshold values are supplied by application orchestration from the
|
|
[Recent Changes configuration](../config.md#recent_change); this package does
|
|
not load configuration or choose defaults. Numeric changes are emitted when
|
|
the absolute difference meets the configured threshold. Precipitation also
|
|
requires a change between its low, possible, likely, and high categories.
|
|
|
|
## Strategies
|
|
|
|
| Comparator | Required snapshot data | Compared values |
|
|
| --- | --- | --- |
|
|
| `CompareDaily` | `derived_daily_summary`, `derived_daypart_summaries` | Low and high temperature, daily precipitation probability and timing, peak gust, alerts, and aggregate indicators |
|
|
|
|
For daily comparison, `alert_digest` and `precip_timing` are optional: alerts
|
|
are compared when present, and timing is compared only when both snapshots
|
|
contain it.
|
|
|
|
The application selects a comparator only after state lookup establishes a
|
|
compatible prior snapshot. Daily, Today, and Tomorrow use the daily comparator.
|
|
Hourly reports do not produce a Recent Changes list.
|
|
|
|
## Missing data and failures
|
|
|
|
Required stanzas that are absent or cannot be decoded return an error with the
|
|
snapshot and stanza context. Optional stanzas may be absent. A snapshot with no
|
|
eligible predecessor is not a comparison failure: the caller supplies an empty
|
|
change list without invoking this package.
|
|
|
|
The package has no filesystem, transport, CLI, renderer, or persistence
|
|
behavior. It does not decide report compatibility or retain snapshots.
|
|
|
|
## Verification and invariants
|
|
|
|
Focused tests cover the daily strategy, threshold boundaries, indicator and
|
|
alert changes, and missing required stanzas:
|
|
|
|
```sh
|
|
go test ./internal/changes
|
|
```
|
|
|
|
Recent Changes always compare structured snapshot values, never report prose.
|