refactor: extract optional runtime shutdown boundary (#3632)

docs/architecture/migration-progress.md

@@ -5,15 +5,15 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block
 ## Current Context
 
 - Issue: [`rustfs/backlog#660`](https://github.com/rustfs/backlog/issues/660)
-- Branch: `overtrue/arch-ops-profiler-capability-tests`
+- Branch: `overtrue/arch-optional-runtime-sidecar-boundary`
 - Baseline: latest `origin/main`
-  (`71809ba02ea405c3a2f0e4cb82ff608915dd519c`).
-- PR type for this branch: `contract`
+  (`e6391598f0b62a66ca6eac405c26b53a9a77d5f1`).
+- PR type for this branch: `pure-move`
 - Runtime behavior changes: none.
-- Rust code changes: add the `ops.profiler.v1` extension capability snapshot
-  contract for disabled, unsupported, and enabled profiler runtime states.
+- Rust code changes: move optional protocol shutdown ownership from
+  `startup_services` into the optional runtime boundary.
 - CI/script changes: none.
-- Docs changes: record the X-013 profiler capability snapshot slice.
+- Docs changes: record the R-021 optional runtime shutdown boundary slice.
 
 ## Phase 0 Tasks
 
@@ -2016,6 +2016,20 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block
     guards, diff hygiene, Rust risk scan, branch freshness check, and
     pre-commit quality gate.
 
+- [x] `R-021` Extract optional runtime shutdown boundary.
+  - Do: add `startup_optional_runtimes` and move optional protocol shutdown
+    ownership/logging out of `startup_services`.
+  - Acceptance: optional protocol shutdown plan order stays FTP, FTPS, WebDAV,
+    SFTP; stopping logs remain before event notifier/audit/profiling shutdown;
+    signal/wait remains after S3/console HTTP shutdown; later optional
+    sidecars have an explicit owner without startup behavior changes.
+  - Must preserve: protocol initialization, protocol shutdown signaling and
+    waiting, shutdown order, profiling/audit/event notifier shutdown, HTTP
+    shutdown, readiness state, and fatal boundaries.
+  - Verification: focused startup optional runtime/service tests, RustFS lib
+    check, migration/layer guards, formatting, diff hygiene, Rust risk scan,
+    branch freshness check, pre-commit quality gate, and three-expert review.
+
 ## Next PRs
 
 1. `pure-move`: continue larger lifecycle hook slices for optional runtime
@@ -2027,9 +2041,9 @@ Status values: `[ ]` not started, `[~]` in progress, `[x]` complete, `[!]` block
 
 | Expert | Status | Notes |
 |---|---|---|
-| Quality/architecture | passed | X-013 keeps the capability snapshot contract in `rustfs-extension-schema`, reuses explicit profiler backend/runtime DTOs, and adds no runtime dependency edges. |
-| Migration preservation | passed | Runtime profiling, admin pprof routes, exporters, storage paths, telemetry, sidecar startup, and plugin execution are untouched; validation only rejects unsafe snapshot declarations. |
-| Testing/verification | passed | Extension schema tests cover enabled, disabled, unsupported, snapshot JSON shape, disabled external runtime policy, and startup-fatal rejection; focused checks, guards, formatting, diff hygiene, and final pre-commit passed. |
+| Quality/architecture | passed | R-021 isolates optional runtime shutdown ownership in `startup_optional_runtimes` and keeps `startup_services` as the startup/shutdown orchestrator. |
+| Migration preservation | passed | Protocol startup, shutdown order, readiness, HTTP shutdown, event notifier, audit, and profiling behavior remain unchanged. |
+| Testing/verification | passed | Focused optional runtime and startup service tests pass; remaining checks and final pre-commit are tracked below before push. |
 
 ## Verification Notes
 
@@ -2057,6 +2071,19 @@ Passed before push:
   - `make pre-commit`: passed.
   - Three-expert review: passed.
 
+- Issue #660 R-021 current slice:
+  - `cargo test -p rustfs --lib startup_optional_runtimes -- --nocapture`:
+    passed.
+  - `cargo test -p rustfs --lib startup_services -- --nocapture`: passed.
+  - `cargo check -p rustfs --lib`: passed.
+  - `./scripts/check_architecture_migration_rules.sh`: passed.
+  - `./scripts/check_layer_dependencies.sh`: passed.
+  - `cargo fmt --all --check`: passed.
+  - `git diff --check`: passed.
+  - Rust risk scan on changed Rust files: passed.
+  - `make pre-commit`: passed.
+  - Three-expert review: passed.
+
 - Issue #660 R-020 current slice:
   - `cargo test -p rustfs --lib startup_profiling -- --nocapture`: passed.
   - `cargo check -p rustfs --lib`: passed.

docs/architecture/profiling-numa-capability-inventory.md

@@ -80,9 +80,9 @@ Future sidecars for profiling, eBPF, or NUMA must preserve these invariants:
 - Verify optional profiler sidecar and Wasm runtimes stay disabled by default
   and cannot declare a startup fatal boundary.
 
-`R-017`:
+`R-021`:
 
-- If a runtime service sidecar is added later, start it from the startup service
-  boundary with explicit shutdown ownership.
+- If a runtime service sidecar is added later, enter it through the optional
+  runtime boundary with explicit shutdown ownership.
 - Preserve current service order, KMS/audit/notification fatal boundaries, and
   scanner/heal startup semantics.

docs/architecture/runtime-lifecycle.md

@@ -31,6 +31,14 @@ Disallowed responsibilities:
 - Hide globals behind a service-locator API.
 - Change startup side effects while moving code.
 
+## Optional Runtime Boundary
+
+`startup_optional_runtimes` owns shutdown for optional runtime services that are
+not readiness or fatal startup boundaries. The current owner set is protocol
+servers only. Future optional sidecars must enter this boundary with explicit
+shutdown handles and status snapshots instead of adding ad hoc shutdown work to
+`startup_services`.
+
 ## AppContext Foundation
 
 Early AppContext work should split resolver files and add compatibility tests before

docs/architecture/startup-timeline.md

@@ -71,9 +71,9 @@ new startup semantics.
 |---|---|---|---|---|---|
 | `STOP-001` | `rustfs/src/startup_services.rs` | Cancel runtime token and move service state to `Stopping`. | Notifies cancellation-aware background tasks. | Non-fatal. | Service state moves to `Stopping`; readiness stages are not cleared here |
 | `STOP-002` | `rustfs/src/startup_services.rs` | Stop scanner/background services and AHM services according to enable flags. | Calls ECStore background shutdown and heal/scanner shutdown helpers. | Non-fatal in this path. | No readiness-stage change |
-| `STOP-003` | `rustfs/src/startup_services.rs` | Signal optional FTP/FTPS/WebDAV/SFTP protocol servers. | Collects protocol shutdown futures. | Non-fatal in this path. | No readiness-stage change |
+| `STOP-003` | `rustfs/src/startup_optional_runtimes.rs` | Plan optional runtime shutdown and log stopping state for FTP/FTPS/WebDAV/SFTP protocol servers. | Collects protocol shutdown handles. | Non-fatal in this path. | No readiness-stage change |
 | `STOP-004` | `rustfs/src/startup_services.rs` and `rustfs/src/startup_profiling.rs` | Stop event notifier, audit system, and profiling tasks. | Stops notifier and profiling tasks; audit stop failures are logged. | Non-fatal in this path. | No readiness-stage change |
-| `STOP-005` | `rustfs/src/startup_services.rs` | Stop S3 and console HTTP servers, wait for protocol shutdowns, then mark service state `Stopped`. | HTTP shutdown happens after notifier/audit/profiling shutdown in current order. | Join failures are logged by shutdown handles; this path does not return errors. | Service state moves to `Stopped`; readiness stages are not cleared here |
+| `STOP-005` | `rustfs/src/startup_services.rs` and `rustfs/src/startup_optional_runtimes.rs` | Stop S3 and console HTTP servers, signal and wait for optional protocol shutdowns, then mark service state `Stopped`. | HTTP shutdown happens after notifier/audit/profiling shutdown in current order. | Join failures are logged by shutdown handles; this path does not return errors. | Service state moves to `Stopped`; readiness stages are not cleared here |
 
 ## Migration Rules