feat(storage): add config to disable alone-in-bucket query optimization

[sylr]

Forward-port of 81a2cc6 (originally landed on hotfix/v2.3/disable-ledger-predicate-optimization) to main.

What

newScopedSelect skips the ledger = ? predicate when a ledger is the only one in its bucket, to avoid a degraded ~100%-selectivity seq scan. This adds a --disable-ledger-scope-optimization serve flag that forces the predicate to always be emitted, as a performance/safety escape hatch. The config threads from the serve flag through storage.ModuleConfig and driver.ModuleConfig down to a new ledgerstore store option. Default keeps current behavior (optimization enabled).

Forward-port notes

• cmd/serve.go and internal/storage/module.go had conflicts: kept main's newer content (audit flags, servicefx.ProvideHealthCheck) and layered the new flag/config on top.
• store_scoped_select_test.go: adapted to bun v1.2.18 (main) — (*bun.DB).Formatter() was removed; switched the unit test to (*bun.DB).QueryGen(), which matches SelectQuery.AppendQuery's new schema.QueryGen signature.

Verification

• go build ./cmd/... ./internal/storage/... ✅
• go test ./internal/storage/ledger/ -run 'TestNewScopedSelect|TestWithDisableScopedSelectOptimization' ✅

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 3c601afc-b8af-4c9e-bac4-7f969e89e970

📥 Commits

Reviewing files that changed from the base of the PR and between edb0dbf and 1789924.

📒 Files selected for processing (5)

• cmd/serve.go
• internal/storage/driver/module.go
• internal/storage/ledger/store.go
• internal/storage/ledger/store_scoped_select_test.go
• internal/storage/module.go

🚧 Files skipped from review as they are similar to previous changes (3)

• internal/storage/driver/module.go
• internal/storage/module.go
• cmd/serve.go

---

Walkthrough

Adds a configurable kill switch that forces emitting ledger = ? in scoped select queries; the flag is exposed on the CLI, threaded through storage/driver module configs, wired into ledger store options, and validated by new SQL-generation tests.

Changes

Ledger scoped select optimization kill switch

Layer / File(s)	Summary
Ledger store scoped select kill switch internal/storage/ledger/store.go, internal/storage/ledger/store_scoped_select_test.go	Adds disableScopedSelectOptimization field to Store, updates newScopedSelect to include ledger = ? when the kill switch is set, provides WithDisableScopedSelectOptimization option, and adds tests covering alone-in-bucket, not-alone, and disabled optimization cases.
Storage/driver module configuration and wiring internal/storage/driver/module.go, internal/storage/module.go	Introduces ModuleConfig (driver) with DisableScopedSelectOptimization, updates driver.NewFXModule to accept that config and wire ledgerstore.WithDisableScopedSelectOptimization(...), and makes storage.NewFXModule forward the setting to the driver module.
CLI flag and serve command configuration cmd/serve.go	Adds DisableLedgerScopeOptimization to ServeCommandConfig, defines DisableLedgerScopeOptimizationFlag, registers --disable-ledger-scope-optimization on the serve command, and passes the flag into storage.NewFXModule's ModuleConfig.

Sequence Diagram(s)

sequenceDiagram
  participant ServeCommand
  participant storage.NewFXModule
  participant driver.NewFXModule
  participant LedgerStore

  ServeCommand->>storage.NewFXModule: call NewFXModule(ModuleConfig{DisableScopedSelectOptimization: bool})
  storage.NewFXModule->>driver.NewFXModule: forward driver.ModuleConfig{DisableScopedSelectOptimization: bool}
  driver.NewFXModule->>LedgerStore: construct ledger store with ledgerstore.WithDisableScopedSelectOptimization(bool)
  LedgerStore->>LedgerStore: newScopedSelect() uses disableScopedSelectOptimization to include/exclude "ledger = ?" predicate

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A tiny rabbit taps the flag so neat,
It threads through modules, quiet and fleet,
"ledger = ?" now may always show—
A hop, a test, the SQL flows. 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 18.18% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding configuration to disable the alone-in-bucket query optimization, which is the primary feature introduced across all modified files.
Description check	✅ Passed	The description is directly related to the changeset, explaining the forward-port, the optimization being disabled, configuration threading, conflict resolution, test adaptation, and verification performed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/disable-ledger-scope-optimization

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.2)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

---

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.}

[codecov]

Codecov Report

❌ Patch coverage is 50.00000% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.01%. Comparing base (140ed9b) to head (1789924).

Files with missing lines	Patch %	Lines
internal/storage/module.go	0.00%	4 Missing ⚠️
internal/storage/driver/module.go	25.00%	2 Missing and 1 partial ⚠️
cmd/serve.go	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1406      +/-   ##
==========================================
- Coverage   80.55%   80.01%   -0.55%     
==========================================
  Files         206      206              
  Lines       11293    11306      +13     
==========================================
- Hits         9097     9046      -51     
- Misses       1646     1659      +13     
- Partials      550      601      +51     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.