feat(spring-data): add Spring Data JPA query plan adapter

[alexolivier]

Summary

New cerbos-spring-data adapter (0.1.0-alpha.1) that converts a Cerbos PlanResources response into a org.springframework.data.jpa.domain.Specification<T> for use with JpaSpecificationExecutor.

• Supports @OneToMany, @ManyToMany, @ManyToOne, @ElementCollection, and arbitrarily deep nested relations via correlated EXISTS subqueries with explicit parent-query tracking through a sealed Scope interface.
• AlwaysAllowed returns a Specification whose predicate is null (Spring Data's canonical "no restriction" signal — omits the WHERE clause entirely). AlwaysDenied returns cb.disjunction(). Conditional wraps the translated Specification; the lambda is re-invoked per query (including Spring Data's separate COUNT pass), so callers must not cache the produced Predicate.
• spring-data-jpa and jakarta.persistence-api are declared compileOnly, so the published POM does not pin Jakarta Persistence on consumers — the consuming app's Spring Boot BOM controls versions (mirrors Spring Data JPA's treatment of hibernate-core as <optional>true</optional>).
• Unsupported operators throw IllegalArgumentException with a message naming the operator. Consumers can register per-operator overrides via Map<String, OperatorFunction>.
• CI workflow (spring-data.yaml) runs on JDK 17 and 21.
• Marked alpha to invite feedback on AttributeMapping.field / AttributeMapping.relation before 1.0.

Operator coverage

Cerbos operator	JPA Criteria translation
and / or / not	cb.and / cb.or / cb.not
eq / ne	cb.equal / cb.notEqual (auto isNull/isNotNull for null RHS)
lt / gt / le / ge	cb.lessThan / greaterThan / lessThanOrEqualTo / greaterThanOrEqualTo
in	path.in(values) or correlated EXISTS for collections
contains / startsWith / endsWith	cb.like(...) with _/%/\ escaping (three-arg form)
isSet(field, true/false)	cb.isNotNull / cb.isNull
hasIntersection(coll, [values])	Correlated EXISTS with IN
hasIntersection(coll.map(x, x.f), [values])	Correlated EXISTS with projected IN
size(coll) > 0 (and >= 1)	Correlated EXISTS
size(coll) == 0 (and <= 0, < 1)	NOT EXISTS
exists / exists_one / all / except / filter	Correlated EXISTS / (SELECT COUNT) = 1 / NOT EXISTS(... AND NOT) / EXISTS(... AND NOT) / treated as exists
Bare boolean variable	cb.equal(path, true)
eq(field, add(const, const))	Constant-fold, then cb.equal(field, folded)
eq(value, add(const, field))	Solve for field (string prefix/suffix strip; numeric subtract); unsolvable cases collapse to 1=0 / 1=1
DeMorgan/negation wrappers (not(and(...)), not(contains(...)), etc.)	cb.not composes over every leaf handler

Not yet supported

Throw IllegalArgumentException with the operator name and (where applicable) a pointer at the supported alternative. Override via OperatorFunction to unblock per-dialect.

Construct	Example CEL	Why
Arithmetic (sub/mult/div/mod) and add outside eq/ne	R.attr.aNumber + 1 > 2	Criteria API has no value-expression engine for column arithmetic.
Regex	R.attr.aString.matches("^foo.*")	No portable regex predicate in JPA; override per-dialect.
List indexing	R.attr.tags[0] == "x"	JPA collections are unordered.
Type casts (int(...) / double(...) / string(...))	int(R.attr.aString) > 0	No portable CAST in Criteria.
Ternary	(R.attr.aBool ? R.attr.aNumber : 0) > 0	CEL emits this as if(cond, then, else); no CASE WHEN value-expression builder.
size(string)	size(R.attr.aString) > 0	Only size(collection) is supported.
Field-to-field comparison	R.attr.aString == R.attr.id	Leaf operators require exactly one variable + one value operand.
eq(map(...), [...])	R.attr.tags.map(t, t.id) == ["tag1", "tag2"]	Use hasIntersection(map(...), [...]).
size(filter(...)) <op> N	size(R.attr.tags.filter(...)) > 0	Use exists(coll, lambda).
size(coll) <op> N for N > 0	size(R.attr.tags) > 5	Only emptiness checks.
Hierarchy operators	hierarchy.overlaps(...)	Not yet ported from the Prisma adapter.

Test coverage

161 tests across two suites against a real Cerbos PDP — Testcontainers by default, or an externally-managed PDP via CERBOS_HOST/CERBOS_PORT + docker-compose.yml for Prisma-style sidecar runs. Audit + decision logs stream to stdout so every PlanResources call is verifiable.

• SpringDataQueryPlanAdapterTest — unit tests that build protobuf operands directly and run them against an empty H2 schema (catches mapping/type errors via Hibernate SQL generation).
• SpringDataIntegrationTest — integration tests against the policy actions in /policies/resource.yaml, including the cross-adapter scenarios from test: add DeMorgan/negation query plan scenarios across adapters #222 (DeMorgan), feat: CEL arithmetic, regex, casts, ternary, size across adapters #223 (CEL primitives), test: add minor operator/comparison shapes across adapters #234 (minor operator shapes), and test: collection macro composition (all-nested, map-compared, filter-count-gt) #235 (collection macro composition).

Throw-tests assert the exception message contains the operator name, so a future change can't silently regress to a less-helpful message or a different exception type.

Test plan

• gradle test --rerun-tasks — 161/161 pass (JDK 17, ghcr.io/cerbos/cerbos:latest via Testcontainers)
• ./scripts/run-e2e.sh — external-PDP mode (docker compose); confirm PlanResources calls served ≥ 150 in the audit summary
• CI matrix passes on JDK 17 + 21
• Sanity check: README quick-start snippet compiles against the published jar shape

Follow-ups

• Three-level-nesting integration test (correlating the same Join into a nested subquery is spec-legal but lacks an authoritative Hibernate test fixture — confirm no cross-join with spring.jpa.show-sql=true).
• MySQL/MariaDB LIKE collation note (Hibernate 6.4+ auto-escapes backslashes; consumers may need noBackslashEscapesEnabled=true or an OperatorFunction override for contains/startsWith/endsWith).
• Hierarchy operators port from the Prisma adapter (~250 LoC).