Files
clean-architecture-backend-…/docs/jpa/experimental-support-matrix.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

3.1 KiB

Experimental Support Matrix

Experimental code is library code in dev.caskeleton.adapter.outbound.persistence.experimental. Nothing composes it and no setting turns it on: a deployment that wants one of these creates the entry point in its own adapter code, and that call is the opt-in. None of it is part of the Stable composition, and JpaModuleBoundaryTest keeps Stable packages from depending on it.

Feature Entry point Evidence (PostgreSQL lane unless noted) State
Shared-schema multi-tenancy (column) tenant.TenantContext, tenant.TenantAwareRepositoryGuard TenantColumnIsolationTest Experimental
PostgreSQL RLS multi-tenancy rls.RlsTenantSessionBinder, rls.RlsPolicyVerifier RlsIsolationFailureTest Experimental
Schema-per-tenant schema.SchemaMultiTenantConnectionProvider, schema.SchemaTenantMigrationOrchestrator SchemaTenantMigrationContractTest Experimental
Database-per-tenant pool budget database.TenantDataSourceRegistry, database.TenantPoolBudget TenantPoolCapacityContractTest Experimental
Consistency-aware read replica replica.ConsistencyAwareDataSourceRouter (you implement ReplicaLagMonitor) ReadAfterWriteRoutingContractTest Experimental
Jakarta Persistence 4.0, Hibernate ORM 8, PostgreSQL 19 none — probes in .github/workflows/jpa-next.yml record NOT_EXECUTABLE Jpa4CompatibilityTest, Hibernate8CompatibilityTest, PostgreSql19CompatibilityTest (unit-lane version canaries) Not executable

The backend.jpa.experimental.* flags and ExperimentalFeatureGate that used to front these were removed on 2026-09-25: no code read the flags from configuration, so setting one did nothing, and the gate only checked a map the caller built itself.

Known constraints

  • Tenant context is fail-closed. An unbound tenant in a shared-schema deployment means a query with no tenant predicate, which returns every tenant's rows.
  • A Hibernate filter is not the security boundary. It does not apply to native SQL, bulk DML, getReference, or the second-level cache.
  • RLS requires all three of: ENABLE ROW LEVEL SECURITY, FORCE ROW LEVEL SECURITY (the owner is otherwise exempt from its own policies), and a runtime role without BYPASSRLS.
  • Tenant bindings are transaction-local. A session-local setting survives the connection's return to the pool.
  • readOnly=true never routes to a replica on its own. Read-after-write uses a consistency token or the primary.
  • Unavailable replica lag evidence means the primary. Absence of evidence is not evidence of freshness.
  • Per-tenant pools are bounded globally. Fifty tenants with a modest pool each is five hundred connections against a server that permits a hundred.
  • Tenant ids never become metric tags. Tenant cardinality is unbounded by definition.

Lanes never change Stable

A compatibility lane publishes nothing and changes no Stable contract. If Hibernate 8 generates different SQL for the fetch-pagination gate, that is a finding about Hibernate 8 — the 7.x gate keeps asserting what 7.x must do, because that is what deployments run.