fix: make sure that accounts don't automatically redelegate to unregistered and re-registered pools

[etorreborre]

This PR implements the FIXME section described in #878

Summary by CodeRabbit

• Bug Fixes
  • Accounts delegated to pools retiring at the epoch boundary are now automatically unbound.
  • Account deposit and rewards remain unchanged when delegations are cleared.
  • Delegations to pools that stay active are preserved.
• Observability
  • Added an accounts_unbound field/metric to epoch transition traces to report the number of accounts unbound.
• Tests
  • Added coverage to validate pool-retirement unbinding behavior, including for RocksDB.

[coderabbitai]

Walkthrough

The change introduces explicit account create/update values, unbinds accounts delegated to retiring pools during epoch transitions, records the unbound count in tracing schemas, and adds store and RocksDB integration coverage.

Changes

Retired-pool account unbinding

Layer / File(s)	Summary
Explicit account value shapes crates/amaru-ledger/src/store/columns/accounts.rs, crates/amaru-ledger/src/bootstrap.rs, crates/amaru-ledger/src/state/volatile/fragment.rs, crates/amaru-stores/src/lib.rs	Account writes now use AccountsValue::Create or AccountsValue::Update with named fields.
RocksDB account persistence crates/amaru-stores/src/rocksdb/ledger/columns/accounts.rs	RocksDB matches account writes by variant, preserving existing rewards during registration updates.
Epoch retirement and observability crates/amaru-ledger/src/store/epoch_transition.rs, crates/amaru-ledger/src/epoch_transition.rs, crates/amaru-observability/src/schemas.rs, docs/TRACES.md, docs/traces-schema.json	Delegations to retiring pools are cleared and the accounts_unbound count is recorded in trace schemas.
Integration coverage and release notes crates/amaru-stores/src/lib.rs, crates/amaru-stores/src/rocksdb/mod.rs, CHANGELOG.md	Tests verify retired delegations are cleared while balances and live delegations remain unchanged; the changelog references the fix.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant EpochTransition
  participant AccountsStore
  participant TraceSpan
  EpochTransition->>AccountsStore: inspect accounts during pool retirement
  AccountsStore-->>EpochTransition: unset delegations to retired pools
  EpochTransition->>TraceSpan: record accounts_unbound
  EpochTransition->>AccountsStore: update retired and remaining pool rows

Loading

Possibly related PRs

• pragma-org/amaru#265: Both changes touch the bootstrap account import path and its account value construction.

Suggested reviewers: ktorz

Poem

Retired pools drift off-screen,
Delegations clear, balances stay keen.
RocksDB guards each account’s state,
Trace counts mark the changing fate—
A tidy ledger fix, straight from the silver screen.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main fix: preventing accounts from automatically redelegating to pools after unregister/re-register cycles.
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.

✨ 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 etorreborre/feat/unregistered-pools

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

crates/amaru-ledger/src/state/volatile/fragment.rs (1)

410-424: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Ditch the inline commentary, mate — let the match speak for itself.

The logic's grand (Create-vs-Update split reads true to the new AccountsValue contract), but that freshly-bolted-on two-liner explaining the deposit semantics runs against the repo's own house rules.

As per coding guidelines: "Never include comments in code unless explicitly asked; use descriptive names instead."

♻️ Suggested tidy-up

     iterator.map(|(credential, Bind { left: pool, right: drep, value: deposit })| {
-        // A bound deposit denotes a (re-)registration within the window (see DiffBind::register);
-        // without one, only delegations changed and the account is known to exist already.
-        let value = match deposit {
+        let value = match deposit {
             Some(deposit) => AccountsValue::Create { pool, drep, deposit, rewards: 0 },
             None => AccountsValue::Update { pool, drep },
         };
         (credential, value)
     })

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/amaru-ledger/src/state/volatile/fragment.rs` around lines 410 - 424,
Remove the inline two-line comment inside add_accounts while leaving the
existing deposit match and AccountsValue::Create/Update behavior unchanged.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/amaru-ledger/src/store/epoch_transition.rs`:
- Around line 179-197: The pool-retirement handling currently scans every
account through with_accounts; replace this full-table traversal with a
pool-to-delegator lookup or equivalent delegation index. Update the retirement
branch to fetch only accounts delegated to pools in retirements, clear their
pool assignments, and preserve the accounts_unbound metric and existing error
propagation.

---

Nitpick comments:
In `@crates/amaru-ledger/src/state/volatile/fragment.rs`:
- Around line 410-424: Remove the inline two-line comment inside add_accounts
while leaving the existing deposit match and AccountsValue::Create/Update
behavior unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cbf6379f-71ea-4639-8dd2-d908aef21c4d

📥 Commits

Reviewing files that changed from the base of the PR and between 5c34172 and 13edd8e.

📒 Files selected for processing (12)

• CHANGELOG.md
• crates/amaru-ledger/src/bootstrap.rs
• crates/amaru-ledger/src/epoch_transition.rs
• crates/amaru-ledger/src/state/volatile/fragment.rs
• crates/amaru-ledger/src/store/columns/accounts.rs
• crates/amaru-ledger/src/store/epoch_transition.rs
• crates/amaru-observability/src/schemas.rs
• crates/amaru-stores/src/lib.rs
• crates/amaru-stores/src/rocksdb/ledger/columns/accounts.rs
• crates/amaru-stores/src/rocksdb/mod.rs
• docs/TRACES.md
• docs/traces-schema.json

💤 Files with no reviewable changes (1)

• crates/amaru-ledger/src/epoch_transition.rs

[codecov]

Codecov Report

❌ Patch coverage is 83.20611% with 22 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...maru-stores/src/rocksdb/ledger/columns/accounts.rs	52.63%	9 Missing ⚠️
crates/amaru-ledger/src/state/volatile/fragment.rs	0.00%	6 Missing ⚠️
crates/amaru-ledger/src/bootstrap.rs	0.00%	5 Missing ⚠️
crates/amaru-ledger/src/store/epoch_transition.rs	93.75%	1 Missing ⚠️
crates/amaru-stores/src/lib.rs	98.75%	1 Missing ⚠️

Files with missing lines	Coverage Δ
crates/amaru-ledger/src/epoch_transition.rs	0.00% <ø> (ø)
crates/amaru-ledger/src/store/columns/accounts.rs	100.00% <ø> (ø)
crates/amaru-observability/src/schemas.rs	100.00% <ø> (ø)
crates/amaru-stores/src/rocksdb/mod.rs	74.67% <100.00%> (+1.62%)	⬆️
crates/amaru-ledger/src/store/epoch_transition.rs	18.75% <93.75%> (+18.75%)	⬆️
crates/amaru-stores/src/lib.rs	98.50% <98.75%> (+0.04%)	⬆️
crates/amaru-ledger/src/bootstrap.rs	12.53% <0.00%> (-0.02%)	⬇️
crates/amaru-ledger/src/state/volatile/fragment.rs	37.22% <0.00%> (-0.66%)	⬇️
...maru-stores/src/rocksdb/ledger/columns/accounts.rs	75.67% <52.63%> (-1.14%)	⬇️

... and 5 files with indirect coverage changes

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/amaru-stores/src/rocksdb/ledger/columns/accounts.rs`:
- Line 48: Remove the inline implementation comment immediately preceding the
account creation logic; leave the surrounding behavior and code unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5978f82a-7ff3-4195-90c5-8259b3eec2a1

📥 Commits

Reviewing files that changed from the base of the PR and between 3d83b23 and a8d7764.

📒 Files selected for processing (12)

• CHANGELOG.md
• crates/amaru-ledger/src/bootstrap.rs
• crates/amaru-ledger/src/epoch_transition.rs
• crates/amaru-ledger/src/state/volatile/fragment.rs
• crates/amaru-ledger/src/store/columns/accounts.rs
• crates/amaru-ledger/src/store/epoch_transition.rs
• crates/amaru-observability/src/schemas.rs
• crates/amaru-stores/src/lib.rs
• crates/amaru-stores/src/rocksdb/ledger/columns/accounts.rs
• crates/amaru-stores/src/rocksdb/mod.rs
• docs/TRACES.md
• docs/traces-schema.json

💤 Files with no reviewable changes (1)

• crates/amaru-ledger/src/epoch_transition.rs

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

• crates/amaru-observability/src/schemas.rs
• docs/traces-schema.json
• docs/TRACES.md
• crates/amaru-ledger/src/state/volatile/fragment.rs
• crates/amaru-ledger/src/store/columns/accounts.rs
• crates/amaru-ledger/src/bootstrap.rs
• crates/amaru-ledger/src/store/epoch_transition.rs
• crates/amaru-stores/src/rocksdb/mod.rs
• crates/amaru-stores/src/lib.rs