[ISSUE #9143]♻️Activate crash-durable mapped-file retirement

[mxsm]

Summary

• activate the crash-durable mapped-file lifecycle behind an explicit, default-off Store configuration
• bootstrap and reconcile lifecycle state under the retained exclusive Store-root lease before numeric segment publication
• route allocation, TTL, truncate, reset, delete-last, and derived-file retirement through durable incarnation, registry, queue-CAS, namespace, and reaper capabilities
• qualify native NTFS and Linux handle-relative/no-follow namespace operations without recursive or raw path deletion
• keep the activation gate simple: explicit opt-in, exclusive root lease, complete replay/reconciliation, and platform qualification; no signature, token, or force-bypass scheme

Safety properties

• a queue cannot forget an active identity before durable intent or exact verified-absence authority exists
• stale tickets cannot delete a same-path replacement with a different physical key or length
• startup fails closed on corrupt, unsupported, ambiguous, hard-linked, symlinked, or changing lifecycle inventory
• Store-owned retirement work is bounded, cancellable, drainable, and replayable after restart
• managed whole-Store destroy remains fail-closed for the M4 consumer-convergence milestone

Validation

• cargo test -p rocketmq-store-local --all-features -- --test-threads=1 (618 lib tests plus integration/doc targets)
• cargo test -p rocketmq-store --lib --all-features -- --test-threads=1 (684/684)
• focused deletion recovery, incarnation reuse, capability compile-fail, Windows namespace, retirement service, and Wave-B Store tests
• cargo clippy --workspace --no-deps --all-targets --all-features -- -D warnings
• cargo doc -p rocketmq-store-local --no-deps --all-features
• cargo +nightly-2026-07-05 check --locked --all-targets --all-features from fuzz/
• Windows and WSL Ubuntu 24.04 native lifecycle tests; WSL retirement 311/311 and Store Wave-B scenarios passed in a fresh isolated target
• ./scripts/runtime-audit.ps1 -SkipBaseline -EnforceBoundaryBaseline
• ./scripts/check-agents-routing.ps1
• 40 changed Rust files passed individual rustfmt --check; package-level Store/Store-local format check passed. Root cargo fmt --all -- --check remains blocked by Windows OS error 206.
• error architecture guard has no findings in this PR's changed source; its remaining 18 findings are unchanged default-branch Timer index source-stringification debt

Closes #9143

Summary by CodeRabbit

• New Features

  • Added opt-in managed mapped-file lifecycle support for local stores.
  • Added automatic startup bootstrap, queue recovery, durable segment allocation, and retirement handling.
  • Added support for managed CommitLog, consume queue, extension, and batch queue segments.
  • Added platform-specific lifecycle initialization for Linux and Windows.

• Bug Fixes

  • Improved cleanup and truncation safety by removing files only after successful validation and retirement.
  • Added stronger protection against invalid, inconsistent, or unsafe store layouts.

[rocketmq-rust-bot]

🔊@mxsm 🚀Thanks for your contribution🎉！

💡CodeRabbit(AI) will review your code first🔥！

Note

🚨The code review suggestions from CodeRabbit are to be used as a reference only, and the PR submitter can decide whether to make changes based on their own judgment. Ultimately, the project management personnel will conduct the final code review💥.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: eae53b69-9692-419e-8e49-c98d98f1f891

📥 Commits

Reviewing files that changed from the base of the PR and between 7d76e9f and 0a83ab1.

📒 Files selected for processing (40)

• rocketmq-store-local/src/base/allocate_mapped_file_service.rs
• rocketmq-store-local/src/base/allocate_mapped_file_service/managed.rs
• rocketmq-store-local/src/mapped_file.rs
• rocketmq-store-local/src/mapped_file/queue_lifecycle.rs
• rocketmq-store-local/src/mapped_file/retirement/activation.rs
• rocketmq-store-local/src/mapped_file/retirement/bootstrap.rs
• rocketmq-store-local/src/mapped_file/retirement/bootstrap/executor.rs
• rocketmq-store-local/src/mapped_file/retirement/bootstrap/executor/durable_unit.rs
• rocketmq-store-local/src/mapped_file/retirement/bootstrap/executor/platform.rs
• rocketmq-store-local/src/mapped_file/retirement/bootstrap/executor/platform/linux.rs
• rocketmq-store-local/src/mapped_file/retirement/bootstrap/executor/platform/unsupported.rs
• rocketmq-store-local/src/mapped_file/retirement/bootstrap/executor/platform/windows.rs
• rocketmq-store-local/src/mapped_file/retirement/bootstrap/inventory.rs
• rocketmq-store-local/src/mapped_file/retirement/bootstrap/types.rs
• rocketmq-store-local/src/mapped_file/retirement/bootstrap_tests.rs
• rocketmq-store-local/src/mapped_file/retirement/bootstrap_tests/executor.rs
• rocketmq-store-local/src/mapped_file/retirement/bootstrap_tests/foundation.rs
• rocketmq-store-local/src/mapped_file/retirement/bootstrap_tests/inventory.rs
• rocketmq-store-local/src/mapped_file/retirement/platform/linux.rs
• rocketmq-store-local/src/mapped_file/retirement/platform/windows.rs
• rocketmq-store-local/src/mapped_file/retirement/registry/queue_slot.rs
• rocketmq-store-local/src/mapped_file/retirement/replay/discovery/platform.rs
• rocketmq-store-local/src/mapped_file/retirement/service.rs
• rocketmq-store-local/src/mapped_file/retirement/service/creation.rs
• rocketmq-store-local/src/mapped_file/retirement/state/reconciliation.rs
• rocketmq-store-local/tests/mapped_file_queue_lifecycle.rs
• rocketmq-store/src/config/message_store_config.rs
• rocketmq-store/src/consume_queue/mapped_file_queue.rs
• rocketmq-store/src/log_file/commit_log.rs
• rocketmq-store/src/message_store/local_file_message_store.rs
• rocketmq-store/src/message_store/local_file_message_store/composition.rs
• rocketmq-store/src/message_store/local_file_message_store/dispatch.rs
• rocketmq-store/src/message_store/local_file_message_store/lifecycle.rs
• rocketmq-store/src/message_store/local_file_message_store/managed_recovery.rs
• rocketmq-store/src/message_store/local_file_message_store/root_lock.rs
• rocketmq-store/src/queue/batch_consume_queue.rs
• rocketmq-store/src/queue/consume_queue_ext.rs
• rocketmq-store/src/queue/local_file_consume_queue_store.rs
• rocketmq-store/src/queue/single_consume_queue.rs
• rocketmq-store/tests/message_store/local_file_message_store/unit.rs

---

Walkthrough

This change adds managed mapped-file lifecycle support. It introduces durable bootstrap and inventory validation, managed allocation and retirement, queue-generation reconciliation, Wave B configuration, platform-specific storage handling, and end-to-end lifecycle tests.

Changes

Managed allocation and retirement

Layer / File(s)	Summary
Managed allocation worker rocketmq-store-local/src/base/allocate_mapped_file_service*	Managed requests use the Store-owned worker, resource admission, completion waits, cancellation, lifecycle validation, and shutdown draining.
Managed queue cleanup rocketmq-store-local/src/consume_queue/mapped_file_queue.rs, rocketmq-store-local/src/mapped_file/queue_lifecycle.rs	Cleanup selects candidates without I/O before managed queues submit durable retirement intents. Legacy queues retain direct deletion.
Managed queue construction rocketmq-store/src/queue/*, rocketmq-store/src/consume_queue/mapped_file_queue.rs	Managed generations receive lifecycle runtimes and allocation services. Queue installation binds reconciled generations atomically.

Bootstrap and recovery

Layer / File(s)	Summary
Inventory scanning rocketmq-store-local/src/mapped_file/retirement/bootstrap/inventory.rs, rocketmq-store-local/src/mapped_file/retirement/activation.rs	Bootstrap validates namespaces, segment layouts, identities, queue lengths, and canonical paths before creating lifecycle artifacts.
Durable bootstrap executor rocketmq-store-local/src/mapped_file/retirement/bootstrap/executor*	The executor advances durable units, snapshots, markers, reconciliation phases, and recovery state through typed actions.
Platform foundations rocketmq-store-local/src/mapped_file/retirement/bootstrap/executor/platform*, rocketmq-store-local/src/mapped_file/retirement/platform/*	Linux and Windows implementations create and verify lifecycle artifacts, enforce namespace boundaries, and publish files with resumable operations.

Store activation

Layer / File(s)	Summary
Wave B configuration rocketmq-store/src/config/message_store_config.rs	Adds the disabled-by-default enableMappedFileLifecycleWaveB setting with default, export, and Serde coverage.
Managed recovery planning rocketmq-store/src/message_store/local_file_message_store/managed_recovery.rs	The Store validates queue routes, stages generations, handles extensions, and installs CommitLog and consume-queue generations.
Startup and shutdown wiring rocketmq-store/src/message_store/local_file_message_store/*, rocketmq-store/src/log_file/commit_log.rs	Store startup bootstraps or activates managed roots. Failed startup shuts down managed runtime and drains retirement work.

Validation

Layer / File(s)	Summary
Bootstrap tests rocketmq-store-local/src/mapped_file/retirement/bootstrap_tests/*	Tests cover execution ordering, failure recovery, artifact idempotency, fencing, inventory validation, and unsupported platforms.
Store lifecycle tests rocketmq-store/tests/message_store/local_file_message_store/unit.rs, rocketmq-store-local/tests/mapped_file_queue_lifecycle.rs	Tests cover managed startup, allocation, truncation, reset, last-file retirement, and non-mutating cleanup selection.

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

Possibly related PRs

• mxsm/rocketmq-rust#9137: Extends AllocateMappedFileService with related lifecycle, admission, and shutdown handling.
• mxsm/rocketmq-rust#9140: Provides related mapped-file lifecycle and lease behavior used by managed allocation and retirement.
• mxsm/rocketmq-rust#8263: Covers related mapped-file expiration and candidate-selection logic.

Suggested labels: enhancement✨

Suggested reviewers: rocketmq-rust-bot, spacexcn, teslarustor

Poem

A rabbit watched the segments bind,
While ledgers kept their steps aligned.
Queues retired by durable light,
Bootstrap files stayed safe and tight.
“Hop!” said the hare, “the paths are clear—”
Managed lifecycles now appear.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch mxsm/issue-9143-mapped-file-retirement-wave-b

---

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