132 lines
6.2 KiB
Markdown
132 lines
6.2 KiB
Markdown
---
|
|
id: pg-fix-bigint-stamp-overflow
|
|
name: Guard pg's server-side stamp arithmetic against i64 extremes (review 004 item 5, implementation)
|
|
status: completed
|
|
depends_on: [pg-decide-stamp-arithmetic-side]
|
|
scope: moderate
|
|
risk: medium
|
|
impact: component
|
|
level: implementation
|
|
tags: [review-004-fixes, postgres-engine, queues]
|
|
---
|
|
|
|
## Description
|
|
|
|
Implement the guard decided by `pg-decide-stamp-arithmetic-side`, per
|
|
`docs/reviews/004-pre-release-general-review.md` §"Findings recorded,
|
|
not fixed" item 5. The sites: the claim statement (`queue.rs:386`),
|
|
heartbeat (`:912`), retry-reschedule (`:1000`), retention-sweep
|
|
(`:714`), and the lock stamp (`lock.rs:91`) — server-side sums over
|
|
consumer-supplied i64s whose overflow fails the UPDATE with "bigint
|
|
out of range", sticky per row (one extreme-stamped row poisons every
|
|
later claim/heartbeat/sweep that touches it).
|
|
|
|
Per the decision of record: clamp/validate at the enqueue seam, or
|
|
`LEAST`/`GREATEST`-guard the server expressions — do not re-deciding;
|
|
if the implementation surfaces a reason the decision can't stand as
|
|
written, stop and record the discrepancy instead of deviating.
|
|
|
|
**Tests** (against the live harness server): a row stamped with
|
|
`visibility_timeout_s = i64::MAX` must not poison claim/heartbeat —
|
|
the row is claimable/heartbeatable per the decided semantics and
|
|
*other rows are unaffected*; the retention `i64::MIN` arm pinned
|
|
similarly. The sticky-failure property is the thing being retired:
|
|
before the fix, one extreme row fails every claim UPDATE that sums
|
|
against it.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [x] The decided guard lands at the decided sites; no re-deciding
|
|
(any discrepancy recorded, not deviated around)
|
|
- [x] An `i64::MAX`-stamped row no longer makes claim/heartbeat
|
|
UPDATEs fail — pinned by test against the live server, with the
|
|
other-rows-unaffected assertion
|
|
- [x] The retention `i64::MIN` arm pinned (sweep behavior per the
|
|
decided semantics)
|
|
- [x] The decision's annotation/contract text updated if the
|
|
reachable failure set changed
|
|
- [x] `cargo test -p alkstore-postgres` (harness server), clippy
|
|
`-D warnings`, fmt clean; workspace gates green server-less
|
|
|
|
## References
|
|
|
|
- docs/reviews/004-pre-release-general-review.md §"Findings recorded,
|
|
not fixed" item 5 (the finding, the sticky-failure mechanism)
|
|
- tasks/pg-decide-stamp-arithmetic-side.md (the decision of record
|
|
this implements)
|
|
- alkstore-postgres/src/queue.rs:386/714/912/1000, lock.rs:91 (the
|
|
stamp sites)
|
|
|
|
## Notes
|
|
|
|
**The decision stands as written; one form refinement, recorded
|
|
here.** The decision's verbatim guard form writes the sum as
|
|
`$N::numeric`, but a bare `$N::numeric` cast changes Postgres's
|
|
parameter-type inference — the parameter infers `numeric` and
|
|
tokio-postgres's `i64` binding fails with `WrongType { postgres:
|
|
Numeric, rust: "i64" }` (caught by the first live test run, both
|
|
tests). The realized form is the **`($N::bigint)::numeric` chain**:
|
|
the inner `::bigint` cast pins the parameter's inferred type (the
|
|
client keeps binding `i64`), the outer `::numeric` lifts the
|
|
arithmetic into the overflow-free domain. Clamp domain, sites, and
|
|
extreme-stamped observables are unchanged — this refines *how* the
|
|
sum computes, not the decision. The pin lives in
|
|
`resolution.rs`'s `saturating_stamp_expr` doc (the one owner both
|
|
files call).
|
|
|
|
**One owner for the guard.** The form lives in
|
|
`resolution.rs`::`saturating_stamp_expr` (the engine's arithmetic
|
|
home, "one owner per formula" — ADR-012 §2); the six sites call it:
|
|
`queue.rs:385` (claim deadline), `:721` (retention sweep),
|
|
`:927` (retry reschedule), `:1016` (heartbeat renewal), `lock.rs:95`
|
|
(try_lock insert), `:222` (renew). Line numbers drifted a few lines
|
|
from the decision's refs (the doc-only decision pinned decision-time
|
|
lines); the site *set* is exactly the decision's six.
|
|
|
|
**No contract/annotation text change.** The reachable-failure-set
|
|
change was recorded by the decision itself (ADR-023 §2's 2026-10-11
|
|
annotation: "bigint out of range" leaves pg's reachable surface);
|
|
the implementation changes nothing further — the acceptance
|
|
criterion's "if changed" clause is satisfied vacuously.
|
|
|
|
**Test coverage beyond the description's minimum**: the description
|
|
pins claim/heartbeat (`i64::MAX` stamp) and the retention
|
|
`i64::MIN` arm; the landed test also pins the retention
|
|
`Some(i64::MAX)` delete-nothing arm, the retry override extremes
|
|
(`Some(i64::MIN)` rides exact → ready-now reclaim;
|
|
`Some(i64::MAX)` → `i64::MAX` ready-~never), and both lock arms
|
|
(`ttl = i64::MAX` insert and renew → `i64::MAX` expiry, normal ttl
|
|
rides exact). All six decision sites are behaviorally pinned, not
|
|
just the four the review named.
|
|
|
|
**One flake fixed before merge**: the first full-crate run failed
|
|
once in the new queue test — the `heartbeat(i64::MIN)` exact-ride
|
|
window was anchored to the test-start clock read and, under the
|
|
loaded parallel suite, the server-side `now` inside the heartbeat
|
|
drifted past `now + 2`. Re-anchored to a fresh read immediately
|
|
before the heartbeat (the family's bounded-wait convention); two
|
|
consecutive full-crate harness runs green after the fix.
|
|
|
|
## Summary
|
|
|
|
The decision-of-record guard landed: every pg server-side stamp
|
|
sum/subtraction computes in `numeric` and saturates to the i64
|
|
domain before the `::bigint` cast —
|
|
`LEAST(GREATEST(<sum>, -9223372036854775808), 9223372036854775807)::bigint`
|
|
— via one owner (`resolution.rs::saturating_stamp_expr`) called at
|
|
all six sites of record (claim deadline, retry reschedule, heartbeat
|
|
renewal, retention sweep; lock insert + renew). The sticky-poison
|
|
property is retired: an `i64::MAX`-stamped row claims to the
|
|
saturated `i64::MAX` deadline, heartbeats land, neighbors claim
|
|
unaffected, `"bigint out of range"` is unreachable through every
|
|
guarded op.
|
|
|
|
Verified: `cargo test -p alkstore-postgres` against the live harness
|
|
server (`pglo-poc` :15432) — 135 lib + 25 suite + 9 schema green,
|
|
two consecutive full runs (the two new tests:
|
|
`extreme_stamps_saturate_and_no_longer_poison_queue_ops`,
|
|
`extreme_ttl_stamps_saturate_without_overflow`); workspace gates
|
|
server-less green (build, full `cargo test` incl. the skipped-clean
|
|
pg rows, clippy `-D warnings` all targets, fmt); fuzz corpus gate
|
|
green (`fuzz/shared` 6 passed); `RUSTDOCFLAGS="-D warnings" cargo
|
|
doc --no-deps` clean. |