release: clarify AAS cadence and coverage limits

[NikolayS]

Summary

• documents that 2.0 weights retained raw and rollup appearances with the current ash.config.sample_interval, so changing cadence rescales history
• documents that successful idle ticks write no row, so stored activity cannot prove sampler coverage or distinguish idle sampling from an outage
• documents that intervals greater than one minute can assign a full tick to one minute and overstate minute extrema
• marks all affected AAS user stories partial and adds the limitation to the README, release notes, API/example blueprints, and the sample_interval catalog comment

Release decision

No genuinely low-risk behavioral fix exists this late in 2.0. A heartbeat alone would not fix historical weighting, while a per-row interval alone would not represent sampled idle time. The complete storage fix remains tracked for a later release in #137; this PR contains the release-local documentation and catalog containment, including #175's corrected no-observation language.

Rebase and conflict resolution

Hand-rebased onto current main at 28136cfcadb6628975363aaaf17dd7b46d2f6f1a.

The overlapping documentation was resolved by retaining:

• release: fix rollup_1h grain honesty #182's effective grain, per-window provenance, and rollup_1h_flat contracts
• release: reject inverted reader windows and clarify diagnostics #180's reader inversion, until-only defaults, report last-day default, rollup_1m-only report disclosure, and NULL+NOTICE behavior
• release: fix raw retention boundary #189's distinction between the logical raw_retention_start planning boundary and physical attribution evidence
• chore: retire pre-2.0 benchmark suite #187's statement that no maintained 2.0 benchmark replaces the retired suite

The examples-wide default sentence was also corrected after review: bare readers mean the last hour except report() (last day), while until-only means the preceding hour.

RED reproduction

On current main before this documentation/catalog change:

• the same 12 appearances read as backend_seconds = 12.00, avg_aas = 0.20 at a 1-second config, then 60.00 / 1.00 after changing only the current config to 5 seconds; the same 5× rescaling persisted after minute rollup and raw truncation
• 12 successful idle take_sample() calls stored zero rows and produced the same data_points = 0, NULL-AAS timeline representation as a minute with no sampler calls
• issue Design blocker: persist sampling cadence for trustworthy AAS #137's greater-than-one-minute reproduction assigns a whole coarse tick to one minute and can report a one-minute peak above observed concurrency

GREEN verification

Exact head 18a90f1fa54bc04db3fe2092af1515892ac7ebd4:

• fresh PostgreSQL 17 install from an exact archive: PASS
• installed ash.config.sample_interval catalog comment contains current-cadence rescaling, >1-minute extrema overstatement, and idle-vs-outage limitations: PASS
• all six changed files carry the intended limitation; all 8 user stories are marked partial: PASS
• neighboring release: fix rollup_1h grain honesty #182/release: reject inverted reader windows and clarify diagnostics #180/release: fix raw retention boundary #189/chore: retire pre-2.0 benchmark suite #187 contract guards: PASS
• git diff --check and stale wording scans: PASS
• static Codex review: no merge-blocking findings

Refs #137
Refs #175

[samo-agent]

Codex review (standing in for REV)

REV is not installed on this host. I ran an independent static codex review against exact rebased head 18a90f1fa54bc04db3fe2092af1515892ac7ebd4; it found no merge-blocking correctness issue. Separate exact-head Docker verification also passed.

Audit verdict

The #160 audit's surviving N8 verdict was: ash.timeline() cannot distinguish sampled-idle from uncovered time; fix the catalog comment now, while the architectural cadence/coverage fix remains issue #137. Issue #137 separately establishes that current-cadence weighting rescales retained history and that coarse cadences can fabricate minute extrema. This PR matches the release-local containment contract: it documents those limitations without pretending to solve storage.

RED

• Same 12 appearances: 12.00 backend_seconds / 0.20 avg_aas at 1 second, then 60.00 / 1.00 after changing only current config to 5 seconds; the 5× rescaling remained after rollup and raw truncation.
• Twelve successful idle sampler calls stored zero rows and were indistinguishable from a no-call minute (data_points = 0, AAS NULL).
• The >1-minute issue #137 case assigns the whole tick to one minute and can overstate minute extrema.

GREEN

• Fresh PG17 exact-archive install: PASS.
• Installed ash.config.sample_interval comment covers current-cadence rescaling, >1-minute overstatement, and idle-vs-outage ambiguity: PASS.
• README, release notes, API, examples, user stories, and catalog comment agree; 8/8 stories are partial: PASS.
• #182 grain/provenance, #180 window/report, #189 logical-vs-physical retention, and #187 benchmark wording survived the hand rebase: PASS.
• The stale examples-wide bare-call sentence found during review was corrected (report() no-bounds = last day; until-only = preceding hour).
• git diff --check: PASS.

Approved for merge once CI is green on this exact head.