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

3.5 KiB

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.