docs(ecstore): inventory api facade boundaries (#4025)

crates/ecstore/src/api/README.md

@@ -2,3 +2,6 @@
 
 Owns explicit facade and compatibility re-export paths during the ECStore
 internal layout migration. No runtime logic lives here.
+
+The current facade groups, external consumer boundaries, and shrink rules are
+recorded in `docs/architecture/ecstore-api-facade-inventory.md`.

docs/architecture/ecstore-api-facade-inventory.md

@@ -0,0 +1,67 @@
+# ECStore API Facade Inventory
+
+This inventory records the current `rustfs_ecstore::api` compatibility surface
+before any ECStore split PR removes or narrows re-exports. It is a planning and
+guardrail document only. It must not be used as approval to move lifecycle,
+replication, or `SetDisks` runtime behavior.
+
+## Facade Group Inventory
+
+| Facade group | Current role | Shrink posture |
+|---|---|---|
+| `storage`, `disk`, `layout`, `error`, `runtime`, `cluster`, `rpc` | Compatibility spine for storage, disk topology, runtime handles, cluster control, and internode calls. | Keep until replacement contracts compile in downstream boundary files. |
+| `bucket`, `config`, `tier`, `data_usage`, `capacity`, `notification`, `metrics`, `rebalance` | Domain and service facades still consumed through owner-local `storage_api` boundaries. | Narrow one group at a time after explicit aliases or wrappers exist. |
+| `set_disk`, `object`, `rio`, `bitrot`, `erasure`, `compression`, `cache`, `client`, `store_list` | Low-level object IO, reader, erasure, cache, and migration helper compatibility. | Keep stable while `SetDisks` remains the shared state carrier. |
+| `admin`, `event`, `global` | Admin, event hook, and legacy global compatibility. | Do not widen; replace mutable/global access with runtime-source contracts first. |
+
+## External Consumer Boundaries
+
+External `rustfs_ecstore::api` imports must stay in these local boundary files:
+
+| Boundary file | Current facade families |
+|---|---|
+| `rustfs/src/storage/storage_api.rs` | Broad RustFS storage owner bridge for admin, bucket, capacity, client, compression, cluster, config, data usage, disk, error, event, global, layout, metrics, notification, rebalance, rio, rpc, set disk, storage, and tier. |
+| `crates/scanner/src/storage_api.rs` | Scanner bridge for bucket lifecycle, replication, metadata, capacity, config, data usage, disk, error, runtime, set disk, storage, and tier. |
+| `crates/obs/src/metrics/storage_api.rs` | Metrics bridge for bucket bandwidth, lifecycle, replication, quota, capacity, data usage, error, runtime, and storage. |
+| `crates/iam/src/storage_api.rs` | IAM bridge for config, error, notification, runtime, and storage. |
+| `crates/heal/src/heal/storage_api.rs` | Heal bridge for data usage, disk, error, runtime, and storage. |
+| `crates/notify/src/storage_api.rs` | Notification bridge for config, runtime, and storage. |
+| `crates/protocols/src/swift/storage_api.rs` | Swift bridge for bucket metadata, bucket metadata system, error, runtime, and storage. |
+| `crates/s3select-api/src/storage_api.rs` | S3 Select bridge for error, runtime, set disk, and storage. |
+| `crates/e2e_test/src/storage_api.rs` | E2E harness bridge for bucket targets, disk walking, and RPC helpers. |
+| `crates/heal/tests/*/storage_api.rs`, `crates/scanner/tests/storage_api/mod.rs`, `fuzz/fuzz_targets/*_storage_api.rs` | Test and fuzz bridges for the same compatibility seams under test. |
+
+New production imports outside these boundary files are migration drift. Add a
+local boundary or storage-api contract first, then route consumers through it.
+
+## Split Dependency Inventory
+
+| Candidate | ECStore dependencies that block a crate split | Required owner contracts before movement |
+|---|---|---|
+| Lifecycle | Object API, `ECStore`, `SetDisks`, runtime sources/globals, bucket metadata/versioning/object lock/replication, disk, config, notification, audit, and tier services. | `LifecycleObjectStore`, `LifecycleMetadataStore`, `LifecycleRuntime`, `LifecycleReplicationSink`, and `LifecycleAuditSink`. |
+| Replication | Bucket target and metadata systems, bucket target client config, disk, object API, runtime sources, notification, and SetDisks lock timing. | `ReplicationStorage`, `ReplicationMetadataStore`, `ReplicationRuntime`, `ReplicationEventSink`, and `ReplicationLifecycleBridge`. |
+| SetDisks | Shared disks, endpoints, format state, namespace locks, cache, and implementations for object IO, namespace locking, bucket, object, list, multipart, and heal operations. | Pure shard source, disk error, bitrot IO, namespace lock, metrics label, and file metadata contracts before any operation family moves. |
+
+## Shrink Rules
+
+1. Do not remove a facade item until its downstream boundary has compile-time
+   coverage or a documented replacement.
+2. Do not add direct `rustfs_ecstore::api` imports outside the boundary files
+   listed above.
+3. Do not split lifecycle or replication into crates while they depend on
+   ECStore runtime state, queues, notification, audit, scanner, or SetDisks
+   internals.
+4. Do not replace `SetDisks` with multiple runtime structs in one PR. Move one
+   operation family only after contracts and focused tests exist.
+5. Remove or narrow one facade group per PR so rollback preserves object IO,
+   quorum, lifecycle/replication queues, scanner repair, notification/audit
+   events, and metadata compatibility.
+
+## First PR Checklist
+
+- inventory the facade group and all external boundary consumers;
+- add explicit aliases or wrappers before deleting any broad passthrough;
+- run `./scripts/check_architecture_migration_rules.sh`;
+- run focused compile or tests for the touched owner boundary;
+- keep runtime behavior unchanged unless the PR is explicitly a code-bearing
+  follow-up with its own rollback plan.

docs/architecture/ecstore-module-split-plan.md

@@ -137,7 +137,10 @@ Focused verification for the first code-bearing replication PR:
 ## Facade Shrink Plan
 
 The broad `rustfs_ecstore::api` facade remains a compatibility boundary, not a
-new architecture target. Shrinking it must be monotonic:
+new architecture target. The current facade groups and external consumers are
+recorded in
+[`ecstore-api-facade-inventory.md`](ecstore-api-facade-inventory.md).
+Shrinking it must be monotonic:
 
 1. Inventory every public facade group and consumer.
 2. Add compile-time coverage before removing or narrowing a facade item.

docs/architecture/overview.md

@@ -44,6 +44,9 @@ hot-path behavior must not drift during this migration.
 - [`ecstore-config-consumer-inventory.md`](ecstore-config-consumer-inventory.md):
   current `ecstore::config::{Config, KV, KVS}` definitions, consumers,
   migration risks, and do-not-change contract.
+- [`ecstore-api-facade-inventory.md`](ecstore-api-facade-inventory.md): current
+  `rustfs_ecstore::api` facade groups, external consumer boundaries, shrink
+  rules, and split dependency inventory.
 - [`config-model-boundary-adr.md`](config-model-boundary-adr.md): target crate,
   module path, dependency rules, and verification gates for moving the pure
   server-config model.

scripts/check_architecture_migration_rules.sh

@@ -70,6 +70,21 @@ require_source_contains "docs/architecture/global-state-crate-split-plan.md" "ru
 require_source_contains "docs/architecture/obs-ecstore-dependency-inventory.md" "## Dependency Inventory" "observability ECStore dependency inventory section"
 require_source_contains "docs/architecture/obs-ecstore-dependency-inventory.md" "## Extraction Plan" "observability ECStore extraction plan section"
 require_source_contains "docs/architecture/obs-ecstore-dependency-inventory.md" "crates/obs/src/metrics/storage_api.rs" "observability ECStore storage_api boundary"
+require_source_contains "docs/architecture/overview.md" "ecstore-api-facade-inventory.md" "architecture overview ECStore facade inventory link"
+require_source_contains "docs/architecture/ecstore-module-split-plan.md" "ecstore-api-facade-inventory.md" "ECStore split plan facade inventory link"
+require_source_contains "docs/architecture/ecstore-api-facade-inventory.md" "## Facade Group Inventory" "ECStore facade inventory group section"
+require_source_contains "docs/architecture/ecstore-api-facade-inventory.md" "## External Consumer Boundaries" "ECStore facade inventory consumer boundary section"
+require_source_contains "docs/architecture/ecstore-api-facade-inventory.md" "## Split Dependency Inventory" "ECStore split dependency inventory section"
+require_source_contains "docs/architecture/ecstore-api-facade-inventory.md" "## Shrink Rules" "ECStore facade shrink rules section"
+require_source_contains "docs/architecture/ecstore-api-facade-inventory.md" "rustfs/src/storage/storage_api.rs" "RustFS storage ECStore facade boundary inventory"
+require_source_contains "docs/architecture/ecstore-api-facade-inventory.md" "crates/scanner/src/storage_api.rs" "scanner ECStore facade boundary inventory"
+require_source_contains "docs/architecture/ecstore-api-facade-inventory.md" "crates/obs/src/metrics/storage_api.rs" "OBS ECStore facade boundary inventory"
+require_source_contains "docs/architecture/ecstore-api-facade-inventory.md" "crates/iam/src/storage_api.rs" "IAM ECStore facade boundary inventory"
+require_source_contains "docs/architecture/ecstore-api-facade-inventory.md" "crates/heal/src/heal/storage_api.rs" "heal ECStore facade boundary inventory"
+require_source_contains "docs/architecture/ecstore-api-facade-inventory.md" "crates/notify/src/storage_api.rs" "notify ECStore facade boundary inventory"
+require_source_contains "docs/architecture/ecstore-api-facade-inventory.md" "crates/protocols/src/swift/storage_api.rs" "Swift ECStore facade boundary inventory"
+require_source_contains "docs/architecture/ecstore-api-facade-inventory.md" "crates/s3select-api/src/storage_api.rs" "S3 Select ECStore facade boundary inventory"
+require_source_contains "docs/architecture/ecstore-api-facade-inventory.md" "Do not add direct \`rustfs_ecstore::api\` imports outside the boundary files" "ECStore facade new-import shrink rule"
 
 TMP_DIR="$(mktemp -d)"
 trap 'rm -rf "$TMP_DIR"' EXIT