79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
---
|
|
id: pg-decide-stamp-arithmetic-side
|
|
name: Decide which side guards pg's server-side stamp arithmetic (review 004 item 5, decision)
|
|
status: pending
|
|
depends_on: []
|
|
scope: narrow
|
|
risk: low
|
|
impact: component
|
|
level: implementation
|
|
tags: [review-004-fixes, postgres-engine, decision, contract]
|
|
---
|
|
|
|
## Description
|
|
|
|
The decision that must precede the BIGINT-overflow fix, per
|
|
`docs/reviews/004-pre-release-general-review.md` §"Findings recorded,
|
|
not fixed" item 5: pg's claim, heartbeat, retry-reschedule, and
|
|
retention-sweep statements compute server-side sums over
|
|
consumer-supplied i64 values (`queue.rs:386/912/1000/714`,
|
|
`lock.rs:91`) — one row stamped with `visibility_timeout_s = i64::MAX`
|
|
(or retention `i64::MIN`) makes every claim/heartbeat UPDATE fail with
|
|
"bigint out of range", and the failure is *sticky* per row. The
|
|
client-side resolution is saturated (`resolution.rs`); the row-stamp
|
|
arithmetic is not.
|
|
|
|
Decide which side owns the guard:
|
|
|
|
- **(a) Clamp/validate at the enqueue seam** — consumer i64s bounded
|
|
at entry, matching `resolution.rs`'s client-side saturation posture
|
|
and the sibling engines' stamp arithmetic (sqlite/mem saturate per
|
|
review 004 inline fix 6 — the engine-uniformity argument).
|
|
- **(b) `LEAST`/`GREATEST`-guard the server expressions** — defense at
|
|
the arithmetic site; no entry-point change, but the stored stamps
|
|
are silently clamped server-side.
|
|
|
|
**Contract-adjacent — this is why it's its own task.** The choice
|
|
changes which failures are reachable through the public surface, which
|
|
touches ADR-023 §2's totality wording. Check the window state first:
|
|
as of the decomposition (2026-10-11) no publish tag exists, so the
|
|
class-1 window is presumed open — verify, and if open, land the
|
|
decision with a dated ADR-023 §2-style annotation (the failure-set
|
|
change is class-1-legal pre-publish, the review-004 inline fix 5
|
|
precedent). If the window has closed, raise with the user before
|
|
pinning anything.
|
|
|
|
The decision must name the guard form precisely: the clamp domain,
|
|
which sites it applies to (enqueue vs the stamp sites), and what the
|
|
observable behavior of an extreme-stamped row becomes.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] The decision of record: which side owns the guard, with the
|
|
ADR-023 §2 totality argument and the sibling-engine uniformity
|
|
check written down
|
|
- [ ] The window state verified and recorded; a dated annotation
|
|
landed if class-1, or user sign-off if post-publish
|
|
- [ ] The guard form is precise (clamp domain, sites, the
|
|
extreme-stamped row's observable semantics) — enough for
|
|
`pg-fix-bigint-stamp-overflow` to implement without re-deciding
|
|
- [ ] The decision recorded where the family keeps such records (ADR
|
|
annotation / task Notes + contract text if the wording needs it)
|
|
|
|
## References
|
|
|
|
- docs/reviews/004-pre-release-general-review.md §"Findings recorded,
|
|
not fixed" item 5 (the finding, the which-side question, the
|
|
contract-adjacency)
|
|
- docs/architecture/decisions/023-fourth-review-round.md §2 (the
|
|
totality wording the choice touches)
|
|
- alkstore-postgres/src/resolution.rs (the client-side saturation
|
|
posture), queue.rs / lock.rs (the stamp sites)
|
|
|
|
## Notes
|
|
|
|
> To be filled by implementation agent
|
|
|
|
## Summary
|
|
|
|
> To be filled on completion |