refactor: narrow startup compatibility shims (#3677)

docs/architecture/crate-boundaries.md

@@ -130,6 +130,11 @@ Outer compatibility boundary modules must use `rustfs_ecstore::api` for ECStore
 public facade surfaces such as layout, storage owner, admin, metrics,
 notification, capacity, and bucket-name helpers.
 
+RustFS startup internals must stay crate-private after the startup owner split.
+Only `startup_entrypoint` remains a public startup module for the binary
+entrypoint; IAM bootstrap, optional runtime, and profiling startup shims must
+not be re-exported as public library modules.
+
 ECStore internal consumers must use `rustfs-storage-api` lifecycle helper DTOs
 directly for `ExpirationOptions` and `TransitionedObject`; ECStore keeps the
 old lifecycle paths only as downstream compatibility re-exports.

docs/architecture/migration-progress.md

@@ -2658,6 +2658,21 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block
     migration/layer guards, formatting, diff hygiene, Rust risk scan, branch
     freshness check, pre-commit quality gate, and three-expert review.
 
+- [x] `R-068` Narrow remaining startup compatibility shim visibility.
+  - Do: make the IAM bootstrap startup shim crate-private, remove the unused
+    optional-runtime and profiling forwarding shims, and keep the binary
+    entrypoint public.
+  - Acceptance: `startup_entrypoint` remains public for `rustfs/src/main.rs`,
+    while `startup_iam`, `startup_optional_runtimes`, and `startup_profiling`
+    no longer appear as public library modules; migration rules reject
+    restoring those public shim paths.
+  - Must preserve: binary startup entrypoint access, IAM readiness bootstrap
+    flow, embedded readiness publication, optional runtime shutdown wiring,
+    profiling shutdown behavior, and test-only IAM retry hook behavior.
+  - Verification: RustFS lib and bin check, focused startup checks,
+    migration/layer guards, formatting, diff hygiene, Rust risk scan, branch
+    freshness check, pre-commit quality gate, and three-expert review.
+
 - [x] `E-001/E-SET-001` Add ECStore layout skeleton and set-layout boundary.
   - Do: create the ECStore internal layout ownership buckets and pin static set
     layout versus runtime `Sets`/`SetDisks` orchestration boundaries before any
@@ -2900,21 +2915,31 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block
 
 ## Next PRs
 
-1. `pure-move`: continue the context-first runtime startup path by narrowing
-   remaining startup service ownership boundaries.
+1. `pure-move`: continue pruning startup public surface and owner boundaries.
 
 ## Pre-Push Review Log
 
 | Expert | Status | Notes |
 |---|---|---|
-| Quality/architecture | passed | API-072 adds an explicit ECStore facade for outer compatibility surfaces and routes storage, admin, scanner, observability, IAM, heal, Swift, S3 Select, and test compatibility imports through it. |
-| Migration preservation | passed | ECStore owner types, endpoint layout types, capacity helpers, local metrics collection, notification peer behavior, and storage init helpers remain re-exported without runtime behavior changes. |
-| Testing/verification | passed | ECStore and outer compatibility check suites, architecture/layer/unsafe guards, formatting, diff hygiene, Rust risk scan, and the full pre-commit gate passed. |
+| Quality/architecture | passed | R-068 keeps the binary startup entrypoint public while making remaining startup compatibility shims crate-private and guarding that surface. |
+| Migration preservation | passed | IAM readiness bootstrap, embedded readiness publication, optional runtime shutdown wiring, profiling shutdown behavior, and test-only IAM retry hook behavior stay in the same owner modules. |
+| Testing/verification | passed | RustFS lib/bin check, focused startup checks, architecture/layer/unsafe guards, formatting, diff hygiene, Rust risk scan, and pre-commit gate passed. |
 
 ## Verification Notes
 
 Passed before push:
 
+- Issue #660 R-068 current slice:
+  - `cargo check -p rustfs --lib --bins`: passed.
+  - `cargo test -p rustfs --lib startup_ -- --nocapture`: passed; 53 tests.
+  - `cargo fmt --all --check`: passed.
+  - `git diff --check`: passed.
+  - `./scripts/check_architecture_migration_rules.sh`: passed.
+  - `./scripts/check_layer_dependencies.sh`: passed.
+  - `./scripts/check_unsafe_code_allowances.sh`: passed.
+  - Rust risk scan on changed Rust files and guard script: passed; only existing test-only `expect` calls were present.
+  - `make pre-commit`: passed; nextest ran 6341 tests with 6341 passed, 111 skipped, and doctests passed.
+
 - Issue #660 API-072 current slice:
   - `cargo check --tests -p rustfs-ecstore`: passed.
   - `cargo check --tests -p rustfs -p rustfs-scanner -p rustfs-obs -p rustfs-iam -p rustfs-heal -p rustfs-protocols -p rustfs-s3select-api`: passed.

rustfs/src/lib.rs

@@ -77,14 +77,12 @@ pub(crate) mod startup_embedded;
 pub(crate) mod startup_embedded_optional;
 pub mod startup_entrypoint;
 pub(crate) mod startup_fs_guard;
-pub mod startup_iam;
+pub(crate) mod startup_iam;
 pub(crate) mod startup_lifecycle;
 pub(crate) mod startup_notification;
 pub(crate) mod startup_observability;
 pub(crate) mod startup_optional_runtime_sidecars;
-pub mod startup_optional_runtimes;
 pub(crate) mod startup_preflight;
-pub mod startup_profiling;
 pub(crate) mod startup_protocols;
 pub(crate) mod startup_runtime;
 pub(crate) mod startup_runtime_hooks;

rustfs/src/startup_iam.rs

@@ -282,7 +282,8 @@ fn should_fail_test_init_attempt() -> bool {
 /// call re-reads the environment variable by restoring the sentinel value.
 /// Intended for use in integration tests that share a process.
 #[doc(hidden)]
-pub fn reset_test_failure_counter() {
+#[allow(dead_code)]
+pub(crate) fn reset_test_failure_counter() {
     use std::sync::atomic::Ordering;
     TEST_REMAINING_FAILURES.store(u64::MAX, Ordering::SeqCst);
 }

rustfs/src/startup_optional_runtimes.rs

@@ -1,18 +0,0 @@
-// Copyright 2024 RustFS Team
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-pub use crate::startup_optional_runtime_sidecars::{
-    OptionalRuntimeServices, init_optional_runtime_services, prepare_optional_runtime_shutdowns,
-    shutdown_optional_runtime_services,
-};

rustfs/src/startup_profiling.rs

@@ -1,15 +0,0 @@
-// Copyright 2024 RustFS Team
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-pub use crate::startup_runtime_hooks::{init_profiling_runtime, shutdown_profiling_runtime};

rustfs/src/startup_shutdown.rs

@@ -173,7 +173,7 @@ pub async fn run_startup_shutdown_sequence(
         state = "stopping",
         "Profiling shutdown started"
     );
-    crate::startup_profiling::shutdown_profiling_runtime();
+    crate::startup_runtime_hooks::shutdown_profiling_runtime();
 
     info!(
         target: "rustfs::main::handle_shutdown",

scripts/check_architecture_migration_rules.sh

@@ -63,6 +63,7 @@ ECSTORE_OBJECT_API_EXTERNAL_ALIAS_EXPECTED_FILE="${TMP_DIR}/ecstore_object_api_e
 ECSTORE_OBJECT_API_EXTERNAL_ALIAS_ACTUAL_FILE="${TMP_DIR}/ecstore_object_api_external_alias_actual.txt"
 ECSTORE_OBJECT_API_EXTERNAL_ALIAS_DIFF_FILE="${TMP_DIR}/ecstore_object_api_external_alias_diff.txt"
 ECSTORE_OBJECT_API_UNAPPROVED_NAME_HITS_FILE="${TMP_DIR}/ecstore_object_api_unapproved_name_hits.txt"
+STARTUP_PUBLIC_SHIM_HITS_FILE="${TMP_DIR}/startup_public_shim_hits.txt"
 STORE_API_DELETE_DTO_REEXPORTS_FILE="${TMP_DIR}/store_api_delete_dto_reexports.txt"
 STORE_API_DELETE_DTO_INTERNAL_HITS_FILE="${TMP_DIR}/store_api_delete_dto_internal_hits.txt"
 STORE_API_LIFECYCLE_HELPER_DEFINITION_HITS_FILE="${TMP_DIR}/store_api_lifecycle_helper_definition_hits.txt"
@@ -213,6 +214,14 @@ require_source_line \
   "crates/storage-api/src/lib.rs" \
   "pub use admin::{DiskSetSelector, StorageAdminApi};" \
   "storage-api public admin contract re-export"
+require_source_line \
+  "rustfs/src/lib.rs" \
+  "pub mod startup_entrypoint;" \
+  "startup process entrypoint public module"
+require_source_line \
+  "rustfs/src/lib.rs" \
+  "pub(crate) mod startup_iam;" \
+  "startup IAM shim crate-private module"
 require_source_line \
   "crates/storage-api/src/lib.rs" \
   "pub use bucket::{BucketInfo, BucketOperations, BucketOptions, DeleteBucketOptions, MakeBucketOptions, SRBucketDeleteOp};" \
@@ -563,6 +572,15 @@ if [[ -s "$ECSTORE_OBJECT_API_UNAPPROVED_NAME_HITS_FILE" ]]; then
   report_failure "external storage compatibility boundaries must not expose new ECStore object_api names: $(paste -sd '; ' "$ECSTORE_OBJECT_API_UNAPPROVED_NAME_HITS_FILE")"
 fi
 
+(
+  cd "$ROOT_DIR"
+  rg -n --no-heading '^pub mod startup_(iam|optional_runtimes|profiling);' rustfs/src/lib.rs || true
+) >"$STARTUP_PUBLIC_SHIM_HITS_FILE"
+
+if [[ -s "$STARTUP_PUBLIC_SHIM_HITS_FILE" ]]; then
+  report_failure "startup compatibility shims must not be public library modules: $(paste -sd '; ' "$STARTUP_PUBLIC_SHIM_HITS_FILE")"
+fi
+
 (
   cd "$ROOT_DIR"
   rg -n --no-heading 'rustfs_ecstore::store_api(?:::\{[^}]*\b(?:ObjectIO|ObjectOperations|ListOperations|MultipartOperations|HealOperations|NamespaceLocking)\b|::(?:ObjectIO|ObjectOperations|ListOperations|MultipartOperations|HealOperations|NamespaceLocking)\b)' \