feat(core): bound sealed-tree descriptors and raise directory ceiling

[FeathBow]

Summary

• Replace all-directory descriptor retention with confined root-relative reopening for assessment, proof, rewalk, sealing, purge, and recovery.
• Store descriptor-free directory and durable-permission evidence while preserving existing traversal and mutation ordering.
• Revalidate strong identity, ownership, backend, mount, directory type, and ACL evidence at every reopened component.
• Raise the root-inclusive production ceiling from 256 to 1,023 directories, exactly reserving one of the existing 1,024 active recovery permissions for the source-parent seal.
• Add full production clean → undo → clean --purge coverage at the new ceiling under a 64-FD soft limit.

Compatibility. This PR does not change activation or seal-WAL wire versions; manifest v1/v2 structures; the v2 fingerprint codec or golden vectors; the content-proof version; transaction state transitions; or the content, entry, manifest, path-byte, and depth limits. The larger ceiling is therefore migration-free. A request for 1,024 tree directories is rejected before item transaction mutation because it would require 1,025 active permissions when the source-parent seal is included.

Internal-only hardlink topology support and ordinary xattr support are not part of this PR; the latter requires a separate proof-schema design. Public docs are updated separately.

Validation

Passed locally on this branch:

cargo fmt --all -- --check
cargo test --workspace --all-targets --locked --quiet
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo check --workspace --release --locked --target x86_64-unknown-linux-musl
cargo check --workspace --all-targets --locked --target x86_64-unknown-linux-musl
git diff --check

The workspace run included 425 degu unit tests, 80 clean integration tests, and 402 degu-core unit tests. Recovery fixtures use canonical paths, cannot silently skip certification/identity failures, and pin schema-v2 compatibility collection explicitly. The 1,023-directory APFS lifecycle ran in separate processes with RLIMIT_NOFILE=64 and completed clean, undo, re-clean, and purge.

Both release and all-targets musl cross-checks pass from macOS; Linux CI remains responsible for runtime and final-link evidence.

Safety

• Reopening begins from the retained certified root; it never falls back to an absolute descendant path.
• Every component uses no-follow directory opens and is checked against recorded strong identity/incarnation, current owner, backend, mount, directory kind, and ACL certification.
• Reopener race hooks only inject the race; the final descriptor and namespace-binding revalidation is compiled into the production path. Tests prove fail-closed behavior for replacement, move, detach, and mode/evidence drift before child intent or fchmod.
• Seal operations transiently reopen one exact directory, apply the WAL-bound mode change, revalidate, and release the descriptor.
• Recovery retains data-only permission plans and transiently reopens one permission target at a time for forward verification, undo, purge verification, generic restore, and quarantine restore. Every lookup controller from the authenticated anchor through the final parent is rechecked for namespace exclusivity during both plan construction and reopen.
• Purge preserves existing postorder, per-entry validation, progress journaling, and final parent fsync behavior.
• The remaining final check-to-syscall window against a hostile same-UID namespace writer is an existing POSIX authority limit and is not broadened or claimed solved here.

Summary by CodeRabbit

• Bug Fixes

  • Improved protection against directory replacement, identity changes, permission drift, and transient filesystem changes during assessment and recovery.
  • Invalid directory paths now produce clearer failure results while preserving the affected path.
  • Production checks now consistently validate the canonical source before changes begin.

• Reliability

  • Reduced file-descriptor usage for large directory trees, improving operation under constrained system limits.
  • Recovery and restoration workflows now perform additional validation before modifying filesystem contents.

• Limits

  • Standardized recovery capacity at 1,024 permission operations and a production directory boundary of 1,023 directories.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f6880567-b2e9-4329-a8ef-48c70cc3e46f

📥 Commits

Reviewing files that changed from the base of the PR and between c8afa55 and 15727dd.

📒 Files selected for processing (14)

• crates/degu-core/src/backend.rs
• crates/degu-core/src/backend/held.rs
• crates/degu-core/src/backend/held/tests.rs
• crates/degu-core/src/seal/wal.rs
• crates/degu-core/src/staging.rs
• crates/degu-core/src/staging/recovery.rs
• crates/degu-core/src/staging/recovery/tests.rs
• crates/degu-core/src/staging/rename.rs
• crates/degu-core/src/staging/rename/tests.rs
• crates/degu-core/src/staging/tests.rs
• crates/degu-core/tests/held_tree_policy_facade.rs
• crates/degu/src/lifecycle/stage/production.rs
• crates/degu/tests/clean/lifecycle.rs
• crates/degu/tests/clean/sealed_admission.rs

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

---

📝 Walkthrough

Walkthrough

The change replaces retained descendant descriptors with authenticated directory evidence and bounded root-relative reopening. Held-tree operations, startup recovery, permission limits, production preflight, and integration tests now use the new model.

Changes

Tree recovery and lifecycle

Layer / File(s)	Summary
Held-tree evidence and reopening crates/degu-core/src/backend/held.rs, crates/degu-core/src/backend/held/tests.rs	Held-tree collection, assessment, purge, sealing, and exact rewalk retain only the root descriptor. Descendants reopen from validated directory evidence.
Descriptor-free recovery plans crates/degu-core/src/staging/recovery.rs, crates/degu-core/src/staging/rename.rs	Startup recovery stores anchor-based permission plans and reopens entries before verification or mutation.
Recovery and race validation crates/degu-core/src/staging/recovery/tests.rs, crates/degu-core/src/staging/rename/tests.rs	Tests cover evidence validation, transient races, replacement handling, canonical paths, restoration, and bounded descriptor usage.
Shared limits and production gates crates/degu-core/src/backend.rs, crates/degu-core/src/seal/wal.rs, crates/degu-core/src/staging.rs, crates/degu-core/src/staging/tests.rs, crates/degu-core/tests/held_tree_policy_facade.rs, crates/degu/src/lifecycle/stage/production.rs, crates/degu/tests/clean/*	Recovery uses a shared 1,024-operation limit. Held-tree capacity is 1,023 directories. Production preflight uses the canonical source before mutation. Boundary tests cover assessment, admission, and restoration.

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

Merge Risk: ⚪ Minimal · up to 15727

The change is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: bounded sealed-tree descriptor usage and the increased directory ceiling.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
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 feat/bounded-sealed-tree

---

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