Files
clean-architecture-backend-…/docs/superpowers/specs/2026-09-19-multi-instance-runtime-contract.md
T

83 lines
3.5 KiB
Markdown

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