feat: require TransactionRunner in okapi-spring-boot autoconfig (KOJAK-67)

[endrju19]

Summary

Closes the silent JDBC auto-commit fallback in OutboxAutoConfiguration that allowed duplicate delivery across processor instances when no PlatformTransactionManager was on the classpath. Replaces it with a fail-fast bean factory plus a structured safety net for the multi-DataSource / multi-PTM / proxy edge cases discovered during review.

Why this matters

Under the prior code path, scheduler ticks ran in JDBC auto-commit when no PTM was registered. FOR UPDATE SKIP LOCKED released its row lock as soon as the SELECT statement returned — before updateAfterProcessing finished — so a second processor instance could claim the same entry and deliver it again. Zero error, zero log, invisible until horizontal scaling.

What changed

Production (okapi-spring-boot):

• New @Bean okapiTransactionRunner factory — derives SpringTransactionRunner from PlatformTransactionManager (qualifier > getIfUnique > distinct error); honours a user-supplied @Bean TransactionTemplate when present; gated by @ConditionalOnExpression so publish-only deployments (both schedulers disabled) start without requiring a PTM. Returns the TransactionRunner interface deliberately so a user-supplied @Bean TransactionRunner of any impl suppresses the factory via @ConditionalOnMissingBean (documented inline).
• New okapi.transaction-manager-qualifier property (mirror of okapi.datasource-qualifier), including spring-configuration-metadata.json entry for IDE autocomplete.
• validatePtmDataSourceMatch — fails fast when an RTM-based PTM is bound to a different DataSource than okapi's outbox; also fails fast when the PTM is non-extractable AND ≥2 DataSource beans exist AND neither qualifier is set (multi-DS ambiguity guard); logs an actionable WARN for non-extractable PTMs in single-DS or qualified setups; INFO breadcrumb in single-DS contexts; rewraps BeanNotOfRequiredTypeException with okapi-specific context. extractDataSource walks the superclass chain, recognising user subclasses of JpaTransactionManager / HibernateTransactionManager.
• unwrapDataSource returns a sealed Unwrapped { Resolved | Unresolvable(reason: CYCLE | NULL_TARGET) } instead of an overloaded DataSource; validatePtmDataSourceMatch branches on three explicit cases. Cycle detection uses IdentityHashMap (reference identity), defending against custom DataSource impls whose equals() delegates to their target.
• OutboxProcessorScheduler / OutboxPurgerScheduler constructors take a non-null TransactionRunner (was nullable TransactionTemplate).
• SpringTransactionRunner.transactionTemplate stays internal — the field is visible to same-module tests only, not part of the published API.

Tests:

• OutboxAutoConfigurationTransactionRunnerTest — slice + unit tests covering multi-PTM, qualifier resolution, RTM/non-RTM/JPA-RTM validation, property binding, publish-only mode, user-template honoured, and Unwrapped cases (Resolved / Unresolvable.CYCLE / Unresolvable.NULL_TARGET).
• TransactionTemplateHijackProofTest — two clean contract tests: ADOPTS Boot's auto-TransactionTemplate verbatim (shouldBeSameInstanceAs), VALIDATES the multi-DS safety net is not bypassed.
• SpringObjectProviderSemanticsAssumptionsTest — pins Spring 7 ObjectProvider.getIfUnique / ResourceTransactionManager contract so framework upgrades surface loudly.
• ExposedSpringBridgeEndToEndTest — Postgres testcontainer + Exposed SpringTransactionManager bridge, including a multi-instance amplification test and a purger E2E proving the bridged PTM works end-to-end.
• JpaTransactionManagerFailFastTest / JpaTransactionManagerMatchedDataSourceTest / JpaPtmClassesReflectionGuardTest — fail-fast and match paths for the JPA branch + bit-rot guard on JPA_HIBERNATE_PTM_CLASSES.
• WrongPtmMultiDataSourceFailFastTest — deterministic startup-failure assertion for the multi-DS ambiguity guard, plus a companion test proving okapi.transaction-manager-qualifier is the escape hatch. Replaces the earlier flaky WrongPtmDataSourceAmplificationProofTest (race-dependent positive assertion, semantically inverted).

Build / infrastructure:

• okapi-spring-boot: opt-in PIT mutation testing via -PenableMutationTesting=true. Plugin and tool versions live in gradle/libs.versions.toml (project convention).
• okapi-integration-tests: spring7-transaction + assertj + spring-boot-test for the Exposed bridge end-to-end coverage.

Docs:

• CHANGELOG.md [Unreleased] ### Changed (BREAKING) entries for the constructor change and the new multi-DS ambiguity fail-fast.
• README migration note in the okapi-spring-boot section — covers (a) the new TransactionRunner requirement for autoconfig users, (b) multi-DataSource disambiguation, (c) the direct-constructor path for non-autoconfig consumers.

Test plan

• ./gradlew check passes (Postgres + MySQL + Kafka testcontainers, all modules)
• Multi-instance amplification covered by ExposedSpringBridgeEndToEndTest's mutation-verified concurrent processors test
• BUG C1 / BUG C2 demonstration tests written RED first, prove the underlying bugs existed before the fix, now serve as permanent regression guards
• Property binding tests pin the okapi.transaction-manager-qualifier YAML contract
• Liquibase E2E tests (issue Use dedicated okapi_databasechangelog tables to isolate library migration state #37) still pass post-rebase
• Branch rebased onto latest origin/main

Out of scope (separate follow-up tickets)

These pre-existing concerns surfaced during review but are NOT part of this PR's scope — they live in okapi-core or predate this change:

• Core OutboxScheduler / OutboxPurger still accept a nullable TransactionRunner? = null and fall back to non-transactional execution — Ktor / direct-core users can still hit the original auto-commit bug. Tracked in core: require non-null TransactionRunner in OutboxScheduler / OutboxPurger (breaking) #51 (breaking, no escape hatch).
• OutboxScheduler.tick() / OutboxPurger.tick() swallow-and-retry-forever — log+retry on every exception with no escalation or listener callback for consecutive failures.
• OutboxStatus.from() throws on a corrupt status string, halting the entire pipeline.
• SpringTransactionRunner.runInTransaction uses !! — NPE risk for nullable generic types (currently unreachable, future-fragile).

Each of the above is a self-contained problem worth its own ticket and dedicated test coverage.