fix(retention-gc): bind cursor windows to stable evidence

[khaliqgant]

Summary

• project expiry onto the same LIMITed existing-row scan so dry-run work is bounded by at most 1,000 observed rows
• carry exact stable candidate IDs into token and audit mutations through one json_each(?) bind
• recheck expiry and per-org retention at deletion time, with fail-closed evidence validation
• preserve the existing-row cursor so sparse production tables still converge inside the 96-hour no-wrap bound

Why

PR #65 capped result rows but not rows examined: its numeric-range COUNT and DELETE still walked an adversarial live-repopulated range. This fresh successor removes rowids from the mutation identity and removes the second numeric-range COUNT entirely. PR #65 remains the durable rejected artifact.

Red-first proof

Commit 1df040887bfe1377d35ae8b959ee679b5e2f2d80 changes tests only. On unchanged 0.2.21 source, both token and audit races fail at the intended assertion after scanning original rowids {1, 2000}, deleting max rowid 2000, and normally reinserting live rows that reuse 2..2000:

• focused run: 0 pass / 2 fail
• actual expiredCount=1; expected 2 retained original stable candidates
• backend observations are normalized so node:sqlite null-prototype rows and better-sqlite3 plain rows exercise the same assertion

Green proof

Observed runtime: Node v22.22.2, matching the server CI job.

• exact token + audit race tests: 2/2
• retention suite: 15/15
• full server suite: 411/411
• server typecheck: PASS
• server build: PASS
• npm pack --dry-run: dist/engine/retention-gc.{js,d.ts} present with additive candidate evidence and all four existing cursor APIs
• git diff --check: PASS
• no package manifest or lockfile change; release workflow retains version ownership

Work-bound measurement

SQLite 3.51 -stats, exact final query shapes, adversarial dense live spans 100,000 and 1,000,000:

Statement	100k VM steps	1m VM steps
token scan	10,010	10,010
token exact-ID delete	50	50
audit scan + config lookup	25,015	25,015
audit exact-ID delete	75	75
rejected numeric-range COUNT	700,008	7,000,008

All final queries reported Fullscan Steps 0 and Sort Operations 0. Absolute VM counts are advisory because SQLite builds vary; the safety gates are the flat 10x span comparison plus structural and semantic tests.

Safety invariant

scanned <= 1000, candidates <= scanned, point lookups <= candidates, deleted <= candidates.

This PR does not publish, deploy, run prod SQL, change retention from 90 days, or touch Cloud/KV.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[coderabbitai]

Warning

Review limit reached

@khaliqgant, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 6 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7ef111ef-9320-46c0-b3c8-8c31a1fed854

📥 Commits

Reviewing files that changed from the base of the PR and between 9225108 and b31f9f8.

📒 Files selected for processing (2)

• packages/server/src/__tests__/retention-gc.test.ts
• packages/server/src/engine/retention-gc.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/retention-gc-bounded-evidence

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}