Files
clean-architecture-backend-…/docs/superpowers/specs/2026-09-18-jpa-runtime-master-switch.md
T

1.9 KiB

JPA Runtime Master Switch

Problem

PersistenceJpaAutoConfiguration is gated by ca-skeleton.persistence-jpa.enabled, but its sibling PersistenceJpaRuntimeConfig is independently listed in Boot auto-configuration imports and only checks app.jpa-platform.addons-enabled.

Because Boot loads both import candidates independently, setting the JPA master switch false can still create provider policy, runtime-role verifier and retry-listener beans from the runtime sibling.

The current focused test also locks this leak in: it loads PersistenceJpaRuntimeConfig without the JPA master switch and expects those beans to exist.

Decision

Both JPA leaf auto-configuration entries must be structurally subordinate to ca-skeleton.persistence-jpa.enabled=true.

PersistenceJpaRuntimeConfig keeps its existing secondary app.jpa-platform.addons-enabled switch, but the master switch is mandatory and evaluated as the capability ownership boundary.

Focused tests state the master explicitly:

  • JPA on + addons default/on -> runtime beans exist.
  • JPA off -> no runtime beans, even when addons would otherwise default on.
  • JPA on + addons off -> no runtime beans.

No bootstrap-side workaround or bean-count guard is added. The leaf that publishes the independent Boot import candidate owns its own master condition.

Verified result

  • Focused RED reproduced the leak: JPA master off still created runtime beans before the production fix.
  • PersistenceJpaRuntimeConfig now requires ca-skeleton.persistence-jpa.enabled=true in addition to the addons switch.
  • JPA on + addons default/on composes the runtime beans.
  • JPA off contributes no HibernateProviderPolicy or PostgreSqlRuntimeRoleVerifier.
  • JPA on + addons off contributes no runtime beans.
  • persistence-jpa check: PASS.
  • verifyJpaApiSurface: unchanged.
  • app-bootstrap test, architectureTest and systemTest: PASS.
  • git diff --check: PASS.