feat(ledger): add setting to disable alone-in-bucket query optimization

[sylr]

What

Adds a ledger.disable-ledger-scope-optimization bool Settings key. When set to true, the operator sets DISABLE_LEDGER_SCOPE_OPTIMIZATION=true on the stateless ledger deployment.

This forces the ledger to always emit the ledger = ? predicate on read queries, disabling the "alone-in-bucket" optimization that skips it when a ledger is the only one in its bucket.

Why

Mirrors the --disable-ledger-scope-optimization serve flag introduced upstream in formancehq/ledger@222fb71, exposing it as an operator Settings escape hatch for operators who need the always-correct scoped query behavior independent of bucket population.

Scope

• Wired only into the stateless (serve) deployment, matching the upstream commit — the worker keeps the optimization on (correctness-neutral).
• Follows the existing pattern of experimental-* / schema-enforcement-mode settings.

Usage

apiVersion: formance.com/v1beta1
kind: Settings
metadata:
  name: ledger-disable-ledger-scope-optimization
spec:
  stacks: ["*"]
  key: ledger.disable-ledger-scope-optimization
  value: "true"

Changes

• internal/resources/ledgers/deployments.go — read the new setting in installLedgerStateless, emit the env var when enabled.
• docs/04-Modules/03-Ledger.md — new section with a Settings example.
• docs/09-Configuration reference/01-Settings.md — new settings-table row.
• docs/09-Configuration reference/settings.catalog.json — regenerated via generate-settings-catalog.

Verification

• go build ./internal/resources/ledgers/ passes.
• Settings catalog regenerated; new key auto-detected.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 43f08fcb-90bf-4327-bd8f-ddde8b75d485

📥 Commits

Reviewing files that changed from the base of the PR and between b101556 and 85436aa.

⛔ Files ignored due to path filters (1)

• docs/09-Configuration reference/settings.catalog.json is excluded by !**/*.json

📒 Files selected for processing (3)

• docs/04-Modules/03-Ledger.md
• docs/09-Configuration reference/01-Settings.md
• internal/resources/ledgers/deployments.go

---

Walkthrough

This PR adds a new configuration setting ledger.disable-ledger-scope-optimization to control ledger query optimization behavior. The setting is documented in the configuration reference and Ledger module guide, and is implemented in the deployment code where it conditionally sets an environment variable on the ledger container.

Changes

Ledger scope optimization disable setting

Layer / File(s)	Summary
Setting definition and implementation docs/09-Configuration reference/01-Settings.md, docs/04-Modules/03-Ledger.md, internal/resources/ledgers/deployments.go	Adds ledger.disable-ledger-scope-optimization boolean setting to configuration reference with description of its purpose. Ledger module documentation explains the setting and provides a Settings CRD YAML example. Deployment code reads the setting and appends DISABLE_LEDGER_SCOPE_OPTIMIZATION=true environment variable to the ledger container when enabled, with error handling for read failures.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

A setting hopped through configs bright, 🐰
Disabling hops that skip the light,
Now ledgers always show their way,
Optimization doesn't hide the day. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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 clearly and specifically describes the main change: adding a setting to disable the alone-in-bucket query optimization for the ledger module.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, covering what was added, why it was needed, scope of changes, usage examples, and verification steps.
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/ledger-disable-scope-optimization-setting

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