Refresh deterministic domain documentation

docs/internal/changes.md

@@ -1,75 +1,61 @@
 # Changes Internals
 
-This document describes structured Recent Changes comparison.
+`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).
 
-## Purpose
+## Comparison inputs and output
 
-`internal/changes` compares current and prior module snapshots and emits
-compact change records for prompt input data packages.
+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.
 
-## Inputs And Outputs
+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.
 
-Inputs:
+## Strategies
 
-- prior module snapshot
-- current module snapshot
-- comparison thresholds from configuration
+| 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 |
+| `CompareThreeDay` | `derived_daypart_summaries` | Per-day temperatures, precipitation probability and timing, peak gust, indicators, and added or removed outlook days |
+| `CompareWeekend` | `derived_daypart_summaries` | The three-day values with weekend-prefixed change types |
 
-Outputs:
+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 multi-day comparators build their day map from daypart
+summaries. A missing or added day becomes a dedicated change rather than a
+comparison against invented data.
 
-- ordered `changes.Change` items with type, message, previous value, and current
-  value where useful
+The application selects a comparator only after state lookup establishes a
+compatible prior snapshot. Daily, Today, and Tomorrow use the daily comparator;
+Three-day and Weekend use their named comparators. Other report types, such as
+Storm, produce no Recent Changes list.
 
-## Boundaries
+## Missing data and failures
 
-- This package compares structured module snapshot data only.
-- It does not read filesystem state, find prior snapshots, render Markdown,
-  invoke Scriptorium, or compare generated report text.
+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.
 
-## Config Fields Used
+The package has no filesystem, transport, CLI, renderer, or persistence
+behavior. It does not decide report compatibility or retain snapshots.
 
-The app maps these fields into comparison thresholds:
+## Verification and invariants
 
-- `recent_change.temperature_degrees`
-- `recent_change.precip_probability_points`
-- `recent_change.wind_gust_miles_per_hour`
-- `recent_change.precip_timing_shift_minutes`
+Focused tests cover the daily, three-day, and weekend strategies, threshold
+boundaries, indicator and alert changes, and missing required stanzas:
 
-## External Adapters Used
+```sh
+go test ./internal/changes
+```
 
-None.
-
-## State Or Manifest Behavior
-
-None directly. The app loads prior module snapshots through `internal/state`
-before calling comparison functions.
-
-## Skip And Resume Behavior
-
-No resume behavior. When the app has no prior comparable snapshot, it sends an
-empty Recent Changes list without calling a comparison function.
-
-## Failure Behavior
-
-- Daily comparison requires `derived_daily_summary` and
-  `derived_daypart_summaries` stanzas. It also uses `alert_digest` and
-  `precip_timing` when present.
-- 3-Day comparison requires `derived_daypart_summaries`.
-- Weekend comparison requires `derived_daypart_summaries`.
-- Storm Report comparison returns no changes.
-
-## Tests
-
-Inspect:
-
-- `internal/changes/daily_test.go`
-- `internal/changes/three_day_test.go`
-- `internal/changes/weekend_test.go`
-- `internal/app/app_test.go`
-
-## Invariants
-
-- Recent Changes are based on structured snapshots, not Markdown report text.
-- Report compatibility is determined outside this package by report definitions
-  and state lookup.
-- Output stays compact enough for prompt input.
+Recent Changes always compare structured snapshot values, never report prose.