> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다. - 상태: 확인 안 함 - 작성일: 2026-09-19 - 요약: 가짜 조정 bean 없이 다중 인스턴스 런타임 계약을 세우는 설계다. - 현재 정본: `src/bootstrap/app/README.md` # Multi-instance Runtime Contract ## Goal Close tech-lead finding C2 without inventing placeholder coordination beans. ca-skeleton.runtime.multi-instance-enabled must describe a runtime capability that the shipped composition can actually provide. ## Current defect StartupSafetyValidator treats multi-instance mode as a promise that five named beans exist: - distributedLockProvider - cacheStampedeProtection - outboxLeaderElection - distributedRateLimiter - migrationStartupRunner Two names have no production definition at all. The unit test hides that by registering five plain Object beans, and the shipped distributed-lock system test had to register unrelated fake siblings just to prove the real JDBC lock composition. The list also conflates unrelated concerns: - cache refresh coordination is explicitly optional efficiency, not a correctness lock; - edge rate limiting has its own transport/provider activation contract; - outbox owns its own SKIP LOCKED coordination when the outbox capability is enabled; - migration startup is not an instance-coordination provider. ## Canonical meaning multi-instance-enabled=true selects the cross-instance implementation of the application DistributedLockPort. Therefore the runtime contract is: 1. capability dependency validation requires JPA/relational persistence; 2. persistence-jpa creates jdbcDistributedLock; 3. bootstrap creates the primary distributedLockProvider decorator; 4. StartupSafetyValidator verifies that the shipped distributed-lock provider exists and is a DistributedLockPort. No other capability is implicitly enabled by this switch. Capability-specific distributed guarantees remain capability-specific: - Redis edge rate limiting is required only when edge rate limiting is enabled and its provider is selected; - cache refresh coordination remains disabled unless a real CacheRefreshCoordinationPort implementation is explicitly composed in a future slice; - outbox coordination exists only with the outbox capability; - migration startup follows the migration setting. ## Fail-closed behavior When multi-instance mode is enabled but the distributed lock provider is absent or has the wrong type, startup fails through the existing ADAPTER_ENABLEMENT / exit-72 path. The validator does not accept arbitrary bean names as evidence for unrelated capabilities. ## Verification - unit: missing/wrong-type distributedLockProvider fails; correct typed provider passes; - system: real shipped H2/JPA composition starts with multi-instance enabled without any fake cache/rate-limit/outbox coordination beans, and exposes both jdbcDistributedLock and the metered distributedLockProvider; - existing JPA-off dependency failure remains; - app-bootstrap unit/system/architecture regressions stay green. ## Verified result - the shipped system proof first failed exactly because the stale five-bean validator still required nonexistent sibling capabilities; - StartupSafetyValidator now validates only the real distributedLockProvider contract and requires the bean to implement DistributedLockPort; - name-only Object placeholders fail closed; - the fake five-bean unit fixture is removed; - the shipped H2/JPA composition starts with multi-instance mode enabled without fake cache, rate-limit, outbox, or migration siblings; - CapabilityDependencyValidator still requires JPA when multi-instance mode is enabled; - persistence-jpa distributed-lock tests: PASS; - app-bootstrap Spotless, full test, full systemTest and architectureTest: PASS; - stale phantom-bean contract scan: 0; - git diff --check: PASS.