[ISSUE #8180]♻️Establish architecture safety and foundation contracts

[mxsm]

Summary

• establish architecture dependency and ArcMut governance guards with CI enforcement
• add canonical model and security foundation crates while preserving legacy type identity
• harden flush, pending-request, task ownership, and graceful-shutdown contracts
• move business metrics managers to their owning crates and close observability dependency cycles
• publish Phase 1 delivery evidence and the complete M01-M12 execution checklist

Validation

• cargo fmt --all -- --check
• cargo clippy --workspace --no-deps --all-targets --all-features -- -D warnings
• affected crate unit and integration suites, including 100k task churn and 10k pending-request expiry
• observability feature matrix (21 check/clippy/test steps)
• RocksDB and RocketMQ MCP specialized gates
• runtime ownership, architecture dependency, ArcMut, routing, and diff guards
• standalone example, Tauri backend, and Web backend validation

Baseline findings

• error-hygiene guard still reports only unchanged pre-existing findings

• GPUI Clippy still reports three unchanged pre-existing collapsible_if findings

• Fixes [Refactor♻️] Establish architecture safety guards and foundation contracts #8180

Summary by CodeRabbit

• New Features

  • Added shared domain models for messages, topics, results, allocation, versions, and security contracts.
  • Improved request tracking with exactly-once completion, connection ownership, capacity limits, and timeout handling.
  • Added deadline-aware shutdown reporting across runtime, broker, remoting, and storage components.
  • Added typed flush errors, durable progress reporting, and store health visibility.
  • Enhanced tracing and metrics context propagation.

• Documentation

  • Added a comprehensive architecture migration plan, governance checklist, baselines, and phased delivery guidance.

• Tests

  • Expanded coverage for compatibility, allocation, security, lifecycle, dependency boundaries, and performance safeguards.

[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

Run ID: af077e81-539a-4676-bdb9-7ba34f2e723e

📥 Commits

Reviewing files that changed from the base of the PR and between 70ec1a1 and 1a93db2.

⛔ Files ignored due to path filters (4)

• Cargo.lock is excluded by !**/*.lock
• rocketmq-dashboard/rocketmq-dashboard-tauri/src-tauri/Cargo.lock is excluded by !**/*.lock
• rocketmq-dashboard/rocketmq-dashboard-web/backend/Cargo.lock is excluded by !**/*.lock
• rocketmq-example/Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (132)

• .github/workflows/rocketmq-rust-ci.yaml
• Cargo.toml
• docs/architecture-refactor-design.md
• docs/plans/architecture-refactor-migration/CHECKLIST.md
• docs/plans/architecture-refactor-migration/README.md
• docs/plans/architecture-refactor-migration/phase-1-safety-foundation/01-governance-and-baselines.md
• docs/plans/architecture-refactor-migration/phase-1-safety-foundation/02-correctness-and-lifecycle.md
• docs/plans/architecture-refactor-migration/phase-1-safety-foundation/03-foundation-contracts.md
• docs/plans/architecture-refactor-migration/phase-1-safety-foundation/PHASE-1-DELIVERY.md
• docs/plans/architecture-refactor-migration/phase-2-core-boundaries/04-protocol-extraction.md
• docs/plans/architecture-refactor-migration/phase-2-core-boundaries/05-transport-extraction.md
• docs/plans/architecture-refactor-migration/phase-2-core-boundaries/06-storage-boundary-extraction.md
• docs/plans/architecture-refactor-migration/phase-2-core-boundaries/07-legacy-and-client-edge-burn-down.md
• docs/plans/architecture-refactor-migration/phase-2-core-boundaries/08-proxy-three-way-split.md
• docs/plans/architecture-refactor-migration/phase-2-core-boundaries/09-facade-and-package-closeout.md
• docs/plans/architecture-refactor-migration/phase-3-production-readiness/10-durability-and-performance.md
• docs/plans/architecture-refactor-migration/phase-3-production-readiness/11-security-observability-cloud.md
• docs/plans/architecture-refactor-migration/phase-4-ai-native/12-ai-native-operations.md
• rocketmq-auth/Cargo.toml
• rocketmq-auth/src/authentication/provider/local_authentication_metadata_provider.rs
• rocketmq-auth/src/lib.rs
• rocketmq-auth/src/runtime_bridge.rs
• rocketmq-auth/tests/security_api_identity.rs
• rocketmq-broker/Cargo.toml
• rocketmq-broker/src/broker_runtime.rs
• rocketmq-broker/src/metrics/broker_metrics_manager.rs
• rocketmq-broker/src/metrics/broker_metrics_manager_impl.rs
• rocketmq-broker/src/processor/pull_message_processor.rs
• rocketmq-broker/src/processor/send_message_processor.rs
• rocketmq-broker/src/schedule/schedule_message_service.rs
• rocketmq-client/Cargo.toml
• rocketmq-client/src/base/query_result.rs
• rocketmq-client/src/consumer/allocate_message_queue_strategy.rs
• rocketmq-client/src/consumer/consumer_impl/observability.rs
• rocketmq-client/src/consumer/pull_result.rs
• rocketmq-client/src/consumer/pull_status.rs
• rocketmq-client/src/consumer/rebalance_strategy.rs
• rocketmq-client/src/consumer/rebalance_strategy/allocate_message_queue_averagely.rs
• rocketmq-client/src/consumer/rebalance_strategy/allocate_message_queue_averagely_by_circle.rs
• rocketmq-client/src/consumer/rebalance_strategy/allocate_message_queue_by_config.rs
• rocketmq-client/src/consumer/rebalance_strategy/allocate_message_queue_by_machine_room.rs
• rocketmq-client/src/consumer/rebalance_strategy/allocate_message_queue_by_machine_room_nearby.rs
• rocketmq-client/src/consumer/rebalance_strategy/allocate_message_queue_consistent_hash.rs
• rocketmq-client/src/producer/producer_impl/default_mq_producer_impl.rs
• rocketmq-client/src/producer/send_result.rs
• rocketmq-client/src/producer/send_status.rs
• rocketmq-client/tests/model_type_identity.rs
• rocketmq-client/tests/public_api_exports_test.rs
• rocketmq-common/Cargo.toml
• rocketmq-common/src/common.rs
• rocketmq-common/src/common/attribute/topic_message_type.rs
• rocketmq-common/src/common/config.rs
• rocketmq-common/src/common/consistenthash.rs
• rocketmq-common/src/common/consistenthash/consistent_hash_router.rs
• rocketmq-common/src/common/consistenthash/hash_function.rs
• rocketmq-common/src/common/consistenthash/node.rs
• rocketmq-common/src/common/consistenthash/virtual_node.rs
• rocketmq-common/src/common/message/message_queue.rs
• rocketmq-common/src/common/mq_version.rs
• rocketmq-common/src/lib.rs
• rocketmq-common/tests/model_type_identity.rs
• rocketmq-controller/Cargo.toml
• rocketmq-controller/src/manager/replicas_info_manager.rs
• rocketmq-controller/src/metrics/controller_metrics_manager.rs
• rocketmq-controller/src/metrics/controller_metrics_manager_impl.rs
• rocketmq-controller/src/openraft/state_machine.rs
• rocketmq-controller/tests/snapshot_test.rs
• rocketmq-doc/README.md
• rocketmq-doc/en/architecture-refactor-adr-013.md
• rocketmq-doc/en/architecture-refactor-m01-baseline.md
• rocketmq-model/Cargo.toml
• rocketmq-model/src/allocation.rs
• rocketmq-model/src/consistent_hash.rs
• rocketmq-model/src/lib.rs
• rocketmq-model/src/message.rs
• rocketmq-model/src/result.rs
• rocketmq-model/src/topic.rs
• rocketmq-model/src/version.rs
• rocketmq-model/tests/allocation_contracts.rs
• rocketmq-model/tests/model_contracts.rs
• rocketmq-observability/Cargo.toml
• rocketmq-observability/benches/observability_hot_path.rs
• rocketmq-observability/src/config.rs
• rocketmq-observability/src/metrics.rs
• rocketmq-observability/src/metrics/owner_instruments.rs
• rocketmq-observability/src/propagation.rs
• rocketmq-observability/src/trace.rs
• rocketmq-observability/src/trace/client.rs
• rocketmq-observability/tests/architecture_guards.rs
• rocketmq-remoting/src/base.rs
• rocketmq-remoting/src/base/pending_request_table.rs
• rocketmq-remoting/src/clients/client.rs
• rocketmq-remoting/src/clients/rocketmq_tokio_client.rs
• rocketmq-remoting/src/connection_v2.rs
• rocketmq-remoting/src/local.rs
• rocketmq-remoting/src/net/channel.rs
• rocketmq-remoting/src/protocol/remoting_command.rs
• rocketmq-remoting/src/remoting.rs
• rocketmq-remoting/src/remoting_server/rocketmq_tokio_server.rs
• rocketmq-remoting/src/rpc/rpc_response.rs
• rocketmq-remoting/tests/pending_request_table.rs
• rocketmq-runtime/src/context.rs
• rocketmq-runtime/src/lib.rs
• rocketmq-runtime/src/owner.rs
• rocketmq-runtime/src/shutdown_deadline.rs
• rocketmq-runtime/src/task_group.rs
• rocketmq-runtime/tests/runtime_model.rs
• rocketmq-runtime/tests/task_group_concurrency_model.rs
• rocketmq-security-api/Cargo.toml
• rocketmq-security-api/src/lib.rs
• rocketmq-security-api/tests/security_contracts.rs
• rocketmq-store/src/base/append_message_callback.rs
• rocketmq-store/src/base/message_store.rs
• rocketmq-store/src/consume_queue/mapped_file_queue.rs
• rocketmq-store/src/log_file/commit_log.rs
• rocketmq-store/src/log_file/flush_manager_impl/default_flush_manager.rs
• rocketmq-store/src/log_file/flush_manager_impl/group_commit_request.rs
• rocketmq-store/src/log_file/mapped_file.rs
• rocketmq-store/src/log_file/mapped_file/default_mapped_file_impl.rs
• rocketmq-store/src/message_store.rs
• rocketmq-store/src/message_store/local_file_message_store.rs
• rocketmq-store/src/message_store/rocksdb_message_store.rs
• rocketmq-store/src/store_error.rs
• rocketmq/src/schedule.rs
• scripts/arc-mut-baseline.json
• scripts/arc-mut-relocation-approvals.json
• scripts/arc_mut_guard.py
• scripts/architecture-dependency-baseline.json
• scripts/architecture-dependency-policy.json
• scripts/architecture_dependency_guard.py
• scripts/tests/test_arc_mut_guard.py
• scripts/tests/test_architecture_dependency_guard.py

🔥 Files not summarized due to errors (1)

• scripts/arc-mut-baseline.json: Server error: no LLM provider could handle the message

---

Walkthrough

This PR establishes architecture governance and migration documentation, adds canonical model and security crates, introduces deadline-aware runtime and remoting lifecycles, propagates typed storage flush failures, decouples observability from legacy crates, and preserves legacy paths through compatibility re-exports and adapters.

Changes

Architecture governance and migration plan

Layer / File(s)	Summary
Architecture policy, baselines, and CI enforcement .github/workflows/rocketmq-rust-ci.yaml, scripts/*, scripts/tests/*, rocketmq-doc/*	Adds dependency and shared-mutation guards, baseline policies, relocation approvals, fixture tests, CI execution on Ubuntu and Windows, and architecture migration documentation.
Migration roadmap and phase gates docs/architecture-refactor-design.md, docs/plans/architecture-refactor-migration/*	Documents target crate boundaries, lifecycle and durability contracts, security and observability constraints, phase milestones, validation commands, rollback rules, and delivery evidence.
Workspace foundation crates Cargo.toml, rocketmq-model/*, rocketmq-security-api/*	Adds the model and security API workspace members and defines runtime-neutral domain, allocation, result, version, authorization, signing, secret, and readiness contracts with tests.

Runtime, remoting, and storage contracts

Layer / File(s)	Summary
Absolute shutdown and dynamic task ownership rocketmq-runtime/*, rocketmq-broker/src/broker_runtime.rs, rocketmq-broker/src/schedule/*	Adds shared shutdown deadlines, leased dynamic task groups, pruning statistics, deadline-aware broker shutdown, unfinished-component reporting, and bounded scheduled-service shutdown.
Pending request completion rocketmq-remoting/src/base/pending_request_table.rs, rocketmq-remoting/src/clients/*, rocketmq-remoting/src/net/channel.rs, rocketmq-remoting/src/remoting.rs	Centralizes owner-scoped pending requests with capacity limits, RAII completion, timeout expiry, connection closure, and exactly-once response handling.
Typed flush and health reporting rocketmq-store/src/base/*, rocketmq-store/src/log_file/*, rocketmq-store/src/message_store/*, rocketmq-store/src/store_error.rs	Adds fallible flush progress, typed store error classification, health recording, graceful shutdown reports, and error propagation through group commit, local, and RocksDB stores.
Shared-mutation and header safety rocketmq/src/schedule.rs, rocketmq-remoting/src/protocol/remoting_command.rs, rocketmq-remoting/src/rpc/rpc_response.rs, rocketmq-store/src/base/append_message_callback.rs	Replaces selected unsafe mutable-sharing paths with mutex or unique-Arc access and deprecates shared-reference mutation escapes.

Canonical compatibility and observability paths

Layer / File(s)	Summary
Legacy model compatibility rocketmq-client/*, rocketmq-common/*, rocketmq-auth/*	Re-exports canonical model and security types through existing paths, adds owned pull-result adapters, and verifies type identity compatibility.
Observability boundary rocketmq-observability/*, rocketmq-broker/src/metrics/*, rocketmq-controller/src/metrics/*	Removes direct common-crate coupling, introduces owner instrument exports, maps exporter types explicitly, and changes tracing helpers to property-based generic contracts.
Controller event validation rocketmq-controller/src/manager/*, rocketmq-controller/src/openraft/*, rocketmq-controller/tests/*	Adds typed event payload validation and returns system-error responses when replica events do not match their declared event types.

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

Possibly related issues

• mxsm/rocketmq-rust#8182: Covers the broader architecture-boundary refactor implemented by the model/security crates, compatibility facades, dependency guards, and lifecycle changes.

Possibly related PRs

• mxsm/rocketmq-rust#7241: Overlaps with store graceful shutdown and flush sequencing.
• mxsm/rocketmq-rust#7520: Overlaps with dynamic task-group and shutdown behavior.
• mxsm/rocketmq-rust#7471: Overlaps with observability dependency and tracing boundary changes.

Suggested labels: architecture, documentation📝, github_actions, testing🧪

Suggested reviewers: TeslaRustor, SpaceXCN, rust-learn-now

Poem

I’m a rabbit with contracts to spare,
Guarding each boundary with care.
Deadlines hop, flush errors chime,
Models align in a tidy line.
CI watches the burrow at night—
Safe little paths, all wired right.

✨ 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 mxsm/architecture-refactor-safety-foundation

---

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