perf(core): bound v3 purge state

[FeathBow]

Summary

• Build deepest-first purge order through bounded hierarchical scratch runs and seal the result into an authenticated anonymous descriptor-only plan, instead of retaining a complete deletion plan and directory evidence until execution.
• Consume one plan record at a time, retaining only its root-to-target ancestor chain.
• Authenticate the complete plan before the first unlink and reauthenticate frames during consumption.
• Preserve monotonic WAL claim, progress, and outcome ordering, and exact restart resumption.
• Remove the unused PurgePlanWriter store field and its lifetime.

Validation

Passed locally on this branch:

cargo test -p degu-core --lib staging::rename::tests --locked
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo fmt --all -- --check
git diff --check

The targeted staging suite ran 81 tests with 0 failures.

Safety

• Purge remains held-FD-relative, no-follow, and identity checked immediately before each unlink and rmdir.
• A corrupt first or later frame, a live replacement, a sync failure, or a progress mismatch stops the run. It never invents completion and never deletes an unverified replacement.

Summary by CodeRabbit

• New Features

  • Added streamed purge support for version 3 tree manifests, including large and deeply nested trees.
  • Added authenticated purge-plan processing with strict ordering and integrity validation.
  • Added support for purging trees containing non-UTF-8 paths.
  • Added accurate purge progress reporting and replay.

• Bug Fixes

  • Purge-plan authorization or construction failures can now be retried instead of blocking recovery.
  • Added safeguards against tampered plans, corrupted metadata, unsafe replacements, and unsupported file attributes.
  • Improved cleanup after interrupted purge preparation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: bd239ae9-062c-407f-b410-3243ce49b44f

📥 Commits

Reviewing files that changed from the base of the PR and between bc8138a and add9fc0.

📒 Files selected for processing (8)

• crates/degu-core/src/backend/held.rs
• crates/degu-core/src/backend/held/tests.rs
• crates/degu-core/src/seal/sidecar.rs
• crates/degu-core/src/seal/sidecar/scratch.rs
• crates/degu-core/src/staging.rs
• crates/degu-core/src/staging/recovery.rs
• crates/degu-core/src/staging/recovery/stream_v3.rs
• crates/degu-core/src/staging/rename/tests.rs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds authenticated purge plans for v3 held-tree manifests. It builds bounded postorder plans, validates records during streamed deletion, integrates the flow with recovery, and adds retry, corruption, path, xattr, replay, and file-descriptor tests.

Changes

Streamed v3 purge

Layer / File(s)	Summary
Manifest encoding and streamed deletion crates/degu-core/src/backend/held.rs, crates/degu-core/src/backend/held/tests.rs	V3 records retain exact canonical bytes. V3PurgePlanBuilder emits path-keyed records with ancestor evidence. StreamedV3Purger validates and removes entries in postorder.
Authenticated purge-plan storage crates/degu-core/src/seal/sidecar/scratch.rs, crates/degu-core/src/seal/sidecar.rs	Scratch runs support purge postorder. TreePurgePlan stores authenticated frames, validates bounds and integrity, and cleans up scratch runs.
Recovery authorization and execution crates/degu-core/src/staging/recovery.rs, crates/degu-core/src/staging/recovery/stream_v3.rs, crates/degu-core/src/staging.rs, crates/degu-core/src/staging/rename/tests.rs	Recovery builds and authenticates streamed v3 plans before mutation, executes streamed deletion, and treats plan failures as retryable. Tests cover corruption, replacement protection, non-UTF-8 paths, replay, xattrs, root-only trees, and deep trees.

Estimated code review effort: 5 (Critical) | ~120 minutes

Merge Risk: ⚪ Minimal · up to add9f

No concrete correctness, security, integrity, or availability issue remains that should block merging.

Sequence Diagram(s)

sequenceDiagram
  participant VerifiedPurgeSession
  participant TreeSidecarStore
  participant TreePurgePlan
  participant StreamedV3Purger
  participant WAL
  VerifiedPurgeSession->>TreeSidecarStore: build and seal v3 purge plan
  VerifiedPurgeSession->>TreePurgePlan: authenticate plan
  VerifiedPurgeSession->>StreamedV3Purger: execute plan records
  StreamedV3Purger->>WAL: journal removal progress
  StreamedV3Purger->>VerifiedPurgeSession: remove root and finish

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 43.75% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 80 functions across 8 files.	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 and concisely describes the main change: bounding v3 purge state through streamed, bounded purge planning and execution.
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.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch perf/held-tree-bounded-purge

---

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