Q3: Preserve unknown session usage and expose cost read failures #797

Merged

toasterson merged 1 commit from fix/q3-honest-costs-20261019 into main

2026-10-19 15:17:56 +00:00

toasterson commented

2026-10-19 08:27:34 +00:00

Owner

Q3 — Honest session counts, usage and read failures

The old view counted a left-join placeholder as a session, summed BIGINT values through incompatible driver types, and converted all-null usage into zero totals. get_work_item_detail then erased query/decode errors and returned a false empty census.

Migration 154 follows applied migration 089: session-ID counts exclude placeholders, token operands/sums use NUMERIC without BIGINT addition overflow, and all-null usage stays unknown. The reader preserves exact values, reports coverage/partial usage, and emits explicit unavailable/query/decode/missing-row states instead of fabricated zeros. Normal fields retain JSON integer encoding; values beyond JavaScript's safe integer range use exact decimal strings, declared by numeric_encoding. Consumers must honor that additive encoding contract. See docs/ai/contracts/session-cost-summary.md.

The associated dashboard SUM(bigint) decoder now deliberately uses double precision for its existing floating-point ratio. Historical model/usage remains unknown; no executor-alias backfill.

Validation:

cargo test -p anima-server --lib --locked: 558 passed, 6 environment-dependent tests ignored.
Disposable local PostgreSQL 18 with full migration chain: zero/one/10,002 sessions, independent enumeration, missing usage, genuine zero, partial coverage, sums exceeding BIGINT and u64, dashboard aggregate decode, missing view, deliberately incompatible row type and missing row; all passed.
PostgreSQL cached-plan rejection is tested as a query failure; a fresh connection reaches the deliberate driver decode failure. Neither reports zero sessions.
Scoped formatting, diff and shell syntax checks. The ignored PostgreSQL regression has a unique nightly job alias.

Dependencies: none. S3 may add future typed usage observations; this read contract remains truthful before that arrives. No production DB write, live repair, claim/hold/lifecycle/budget change, merge, deployment or canary.

Solstice exact-head CI and independent AI review pending at creation. Local validation is distinct from CI/runtime acceptance. Do not merge: operator human gate.

Consumer compatibility: session_cost_summary now returns explicit availability/usage states and coverage counts. Unknown or unavailable totals are null. JSON-safe exact values remain numbers; values above2^53-1 are decimal strings with numeric_encoding indicating mixed encoding. Consumers must branch on availability, preserve null, and accept number|string rather than defaulting null/error to zero. See docs/ai/contracts/session-cost-summary.md. Independent Fable review approved; exact-head Solstice receipt remains pending.

## Q3 — Honest session counts, usage and read failures The old view counted a left-join placeholder as a session, summed BIGINT values through incompatible driver types, and converted all-null usage into zero totals. `get_work_item_detail` then erased query/decode errors and returned a false empty census. Migration 154 follows applied migration 089: session-ID counts exclude placeholders, token operands/sums use NUMERIC without BIGINT addition overflow, and all-null usage stays unknown. The reader preserves exact values, reports coverage/partial usage, and emits explicit unavailable/query/decode/missing-row states instead of fabricated zeros. Normal fields retain JSON integer encoding; values beyond JavaScript's safe integer range use exact decimal strings, declared by `numeric_encoding`. Consumers must honor that additive encoding contract. See `docs/ai/contracts/session-cost-summary.md`. The associated dashboard SUM(bigint) decoder now deliberately uses double precision for its existing floating-point ratio. Historical model/usage remains unknown; no executor-alias backfill. Validation: - `cargo test -p anima-server --lib --locked`: 558 passed, 6 environment-dependent tests ignored. - Disposable local PostgreSQL 18 with full migration chain: zero/one/10,002 sessions, independent enumeration, missing usage, genuine zero, partial coverage, sums exceeding BIGINT and u64, dashboard aggregate decode, missing view, deliberately incompatible row type and missing row; all passed. - PostgreSQL cached-plan rejection is tested as a query failure; a fresh connection reaches the deliberate driver decode failure. Neither reports zero sessions. - Scoped formatting, diff and shell syntax checks. The ignored PostgreSQL regression has a unique nightly job alias. Dependencies: none. S3 may add future typed usage observations; this read contract remains truthful before that arrives. No production DB write, live repair, claim/hold/lifecycle/budget change, merge, deployment or canary. Solstice exact-head CI and independent AI review pending at creation. Local validation is distinct from CI/runtime acceptance. **Do not merge: operator human gate.** Consumer compatibility: session_cost_summary now returns explicit availability/usage states and coverage counts. Unknown or unavailable totals are null. JSON-safe exact values remain numbers; values above2^53-1 are decimal strings with numeric_encoding indicating mixed encoding. Consumers must branch on availability, preserve null, and accept number|string rather than defaulting null/error to zero. See docs/ai/contracts/session-cost-summary.md. Independent Fable review approved; exact-head Solstice receipt remains pending.

toasterson added 1 commit

2026-10-19 08:27:35 +00:00