Files
clean-architecture-backend-…/docs/superpowers/specs/2026-09-19-capability-dependency-validation-context.md
T

3.0 KiB

Capability Dependency Validation Context

Goal

Close the remaining BOOT-004 exception after StartupValidationContext was introduced. Capability dependency validation still accumulates with a raw ArrayList and two startup entry points repeat the same list-empty-check / message-join / StartupFailures path.

Design

CapabilityDependencyValidator becomes the single owner of this validation flow.

  • dependency rules accumulate into StartupValidationContext opened for ADAPTER_ENABLEMENT;
  • violations(Environment) remains as a read-only diagnostic/test API and returns the context's copy;
  • requireSatisfied(Environment) evaluates the same rules and calls failIfViolated once;
  • CapabilityDependencyEnvironmentValidator and CapabilityDependencyStartupCheck both delegate to requireSatisfied and contain no accumulation or failure formatting.

GraphQL deployment-mode validation may continue to return a small list from its pure sub-rule; the parent collector absorbs it through rejectAll. The startup phase and typed exception are selected only by StartupValidationContext.

Compatibility

  • all existing dependency rule text remains unchanged;
  • all-off remains valid;
  • multiple dependency failures are still reported together;
  • the failure remains REQUIRED_ADAPTER_DISABLED / ADAPTER_ENABLEMENT;
  • both early EnvironmentPostProcessor startup and ApplicationContextRunner fallback paths keep the same rule set.

Final BOOT-004 residual

The repository-wide residual scan found one additional startup guard still matching the original BOOT-004 pattern: SecretSourceValidator maintained separate offenders and missing ArrayLists and threw after each method. That meant a production deployment with both a local/dev sentinel and a missing required secret reported only the sentinel on the first boot.

The closure uses one ENV_VALIDATION StartupValidationContext for the whole prod secret contract. Sentinel property names are de-duplicated with a LinkedHashSet because the same key can be enumerated by multiple property sources; that set is discovery/deduplication data, not a failure accumulator. Each discovered sentinel and missing required secret is rejected into the shared validation context, then the validator fails once at the end of the phase.

Verified result

  • CapabilityDependencyValidator accumulates through StartupValidationContext and both startup entry points delegate to requireSatisfied;
  • SecretSourceValidator uses one ENV_VALIDATION context for both sentinel and missing-secret violations;
  • a focused test proves sentinel and missing required secret are reported in one startup failure;
  • production raw startup validation ArrayLists with the historical violation variable shapes are 0; the only such accumulator is StartupValidationContext itself;
  • PostgreSqlTransportSecurityValidator urlSslModes is parsing data, not a startup failure accumulator;
  • DataSourceRequirement reasons is management/activation-report data and does not throw;
  • app-bootstrap Spotless, full TEST and full ARCHITECTURE regressions: PASS;
  • git diff --check: PASS.