Files
clean-architecture-backend-…/docs/superpowers/specs/2026-09-19-runtime-profile-access-boundary.md
T

2.1 KiB

Runtime Profile Access Boundary

Goal

Finish the remaining BOOT-002 requirement: production bootstrap code must not read Spring active profiles ad hoc after the runtime vocabulary has already been centralized in shared-contract RuntimeEnvironment.

Boundary

shared-contract RuntimeEnvironment remains framework-free and owns only vocabulary/semantics:

  • local
  • dev
  • prod
  • profile -> RuntimeEnvironment resolution
  • production/test interpretation

app-bootstrap owns one Spring-aware bridge:

  • RuntimeProfileSnapshot.from(Environment)
  • immutable copy of active profile names
  • delegation to RuntimeEnvironment for environment resolution and production/test interpretation

No other app-bootstrap production class calls Environment#getActiveProfiles directly.

Why a bootstrap bridge instead of changing RuntimeEnvironment

shared-contract is deliberately Java-stdlib-only and is also consumed by non-Spring adapter leaves. Making RuntimeEnvironment accept Spring Environment would reverse that boundary. The bridge keeps Spring extraction in the composition root while preserving one vocabulary/decision implementation.

Compatibility

  • active profile order is preserved;
  • supplementary profiles remain visible;
  • profileless contexts remain empty;
  • production still means exactly the RuntimeEnvironment.PROD vocabulary;
  • test remains a test-only profile, not a deployable RuntimeEnvironment;
  • logging and management surfaces that expose active profiles retain their current string behavior.

Enforcement

Add an ArchUnit rule over app-bootstrap production classes:

  • RuntimeProfileSnapshot is the only class allowed to call Environment#getActiveProfiles;
  • new direct callers fail architectureTest.

Verified result

  • app-bootstrap production calls Environment#getActiveProfiles exactly once, inside RuntimeProfileSnapshot;
  • RuntimeProfileSnapshot focused unit tests: PASS;
  • RuntimeProfileAccessArchitectureTest: PASS;
  • ArchRuleDiscoveryContractTest includes and discovers the new rule: PASS;
  • shared-contract check, including RuntimeEnvironment tests: PASS;
  • app-bootstrap Spotless, full test and full architectureTest: PASS;
  • git diff --check: PASS.