feat: add candidate-key pagination for selective transactions

[flemzord]

Summary

Adds an experimental candidate-key pagination path for selective transaction list queries.

The new path is disabled by default and can be enabled with:

--experimental-transaction-candidate-pagination

When enabled, it only applies to transaction pagination when all of these are true:

• pagination column is id
• order is descending
• the request is not a reverse page
• the query has a positive selective transaction filter (account, source, destination, or metadata[...])

The generated shape materializes candidate transaction keys first, pages those keys, then joins back to fetch full transaction rows. Non-matching queries keep the existing pagination path.

Validation

• go test ./...
• go test ./internal/storage/common ./internal/storage/ledger ./internal/storage/driver ./internal/storage ./cmd
• go test -tags it ./internal/storage/ledger -run 'TestTransactionsCandidateKeyPagination|TestTransactions' -count=1
• go test -race -tags it ./internal/storage/ledger -run 'TestTransactionsCandidateKeyPagination|TestHasPositiveSelectiveTransactionFilter' -count=1
• go test -tags it ./internal/api/v1 ./internal/api/v2 ./internal/controller/ledger -run 'Transactions|ListTransactions' -count=1
• go test -tags it ./internal/storage/common ./internal/storage/driver ./internal/storage -count=1
• git diff --check

Notes

go test -tags it ./internal/storage/ledger -count=1 currently fails on TestVolumesAggregate/filter_using_metadata_and_PIT. I reproduced the same failure on a clean detached worktree at the original HEAD, so it is pre-existing and unrelated to this PR.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 005e512f-90e5-4d68-9b61-004d7dcc348f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/transaction-candidate-pagination

---

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 and usage tips.}

[gfyrag]

Reviewed current draft head a04db84a718a9ae188aa9eca96b79cc00c907b78.

Findings:

1. Blocking: this PR does not currently merge into main.

GitHub reports mergeable=false, and local git merge-tree confirms conflicts in cmd/serve.go, internal/storage/common/resource.go, internal/storage/driver/module.go, internal/storage/ledger/resource_transactions.go, and internal/storage/ledger/store.go. The conflicts overlap current-main storage changes, including scoped-select config and later transaction filter fixes, so the rebase/merge needs careful resolution before this can be reviewed as merge-ready.

2. Docs are missing for the new CLI/config flag.

The PR adds --experimental-transaction-candidate-pagination and config wiring, but there is no update to docs/ops/cli.md or other docs. I did not find any mention of the flag or candidate-key pagination in docs/ or openapi.yml.

3. Test gap: production wiring is not exercised.

The candidate pagination tests enable the option by constructing ledgerstore.New(...) directly, bypassing the real serve -> storage.NewFXModule -> driver.NewFXModule -> ledgerstore.NewFactory path. The wiring is simple, but a small test around the storage module wiring would catch regressions.

I did not find a current correctness issue in the candidate-key pagination algorithm itself on the submitted head. The CTE shape pages materialized (ledger,id) candidates, rejoins full rows, and preserves final dataset.id DESC ordering; next/previous cursor behavior matches the default path in the added integration coverage.

Checks run:

• git diff --check origin/main...HEAD
• go test ./internal/storage/ledger
• go test ./internal/storage/common
• go test ./internal/storage/...
• go test -tags it ./internal/storage/ledger -run 'TestTransactionsCandidateKeyPagination(MatchesDefault|SQLShape)$' -count=1
• go test -tags it ./internal/storage/ledger -run 'TestTransactions' -count=1
• go build ./...
• GOROOT= go build ./...

I did not run full just pre-commit because this was review-only and that target can rewrite files.