diff --git a/docs/architecture/persistence-ownership.md b/docs/architecture/persistence-ownership.md new file mode 100644 index 000000000..a81fd0b1c --- /dev/null +++ b/docs/architecture/persistence-ownership.md @@ -0,0 +1,52 @@ +# Graph Persistence Ownership + +Status: adopted for the Core/Extensions split. Reviewed 2026-10-24. + +ARGI Core owns the graph persistence contracts and reference implementations. +This repository owns optional durable backends and their operational behavior. +The decision is tracked with Core issue +[#190](https://github.com/agentic-ai-java/argi/issues/190). + +## Owned modules + +| Module | Owner scope | Core contract consumed | +| --- | --- | --- | +| `argi-graph-persistence-jdbc` | H2, MySQL, PostgreSQL and Oracle checkpoint savers and `DatabaseStore` | `BaseCheckpointSaver`, `Store`, serializers | +| `argi-graph-persistence-mongodb` | MongoDB checkpoint saver | `BaseCheckpointSaver`, serializers | +| `argi-graph-persistence-redis` | Redis checkpoint saver, versioned CAS, leases, Redis Store and RunStore | checkpoint, lease and runtime contracts | + +These modules are the only maintenance locations for durable JDBC, MongoDB and +Redis graph persistence. Backend schemas, keys, transaction behavior, driver +versions, leases, retention and recovery tests stay here. + +## Compatibility rules + +- The modules consume `argi-loop-core`; no module depends on the removed + `argi-graph-core` coordinate for the persistence path. +- Existing Java package names in the Extensions adapters remain unchanged. +- Existing checkpoint fields, serializer markers, database table names, Redis + keys, namespace encoding and configuration meanings remain unchanged. +- The old Core backend classes are removed rather than kept as a second + implementation. Consumers migrate to the Extensions artifacts listed in the + module table. +- Cross-version compatibility tests may use the last published graph artifact + as a test-only historical writer; it is never a production dependency. +- The Extensions BOM must publish the persistence modules with the matching + Core version. + +## Required backend evidence + +Each module must keep tests for history/release, retention, serializer +compatibility, concurrent access and backend restart behavior. Redis additionally +must cover revision CAS, lease fencing and durable RunStore commit semantics. +Tests that require PostgreSQL, MySQL, Oracle, MongoDB or Redis must clearly +remain integration tests; an in-memory mock is not evidence of backend +durability. + +## Deliberate non-goals + +This migration does not rename `graph-persistence` artifacts, change wire +formats, change serializer ownership, or move the neutral `Store` and +`CheckpointSaver` contracts into Extensions. It also does not update unrelated +Extensions consumers of the historical graph coordinate; those belong to their +own migration tasks. diff --git a/graph-persistence/argi-graph-persistence-jdbc/pom.xml b/graph-persistence/argi-graph-persistence-jdbc/pom.xml index 7d4d96bea..4342bb057 100644 --- a/graph-persistence/argi-graph-persistence-jdbc/pom.xml +++ b/graph-persistence/argi-graph-persistence-jdbc/pom.xml @@ -41,10 +41,17 @@ + + io.github.agentic-ai-java + argi-loop-core + ${argi.loop.version} + + io.github.agentic-ai-java argi-graph-core ${argi.version} + test diff --git a/graph-persistence/argi-graph-persistence-mongodb/pom.xml b/graph-persistence/argi-graph-persistence-mongodb/pom.xml index 81cb2283e..d0a68ed22 100644 --- a/graph-persistence/argi-graph-persistence-mongodb/pom.xml +++ b/graph-persistence/argi-graph-persistence-mongodb/pom.xml @@ -37,10 +37,17 @@ + + io.github.agentic-ai-java + argi-loop-core + ${argi.loop.version} + + io.github.agentic-ai-java argi-graph-core ${argi.version} + test diff --git a/graph-persistence/argi-graph-persistence-redis/pom.xml b/graph-persistence/argi-graph-persistence-redis/pom.xml index 376dcb41f..26707f702 100644 --- a/graph-persistence/argi-graph-persistence-redis/pom.xml +++ b/graph-persistence/argi-graph-persistence-redis/pom.xml @@ -39,8 +39,8 @@ io.github.agentic-ai-java - argi-graph-core - ${argi.version} + argi-loop-core + ${argi.loop.version} @@ -49,11 +49,18 @@ ${redisson.version} + + io.github.agentic-ai-java + argi-loop-core + ${argi.loop.version} + test-jar + test + + io.github.agentic-ai-java argi-graph-core ${argi.version} - test-jar test diff --git a/pom.xml b/pom.xml index e87d24c80..18172bec4 100644 --- a/pom.xml +++ b/pom.xml @@ -157,6 +157,8 @@ 2.1.0-RC2-SNAPSHOT 2.1.0-RC1 + 2.1.0-RC2-SNAPSHOT + 2.1.0-RC2-SNAPSHOT 17