From 1a643b2c9d5ef4fa4b5cbc8629937a2cebc760fa Mon Sep 17 00:00:00 2001 From: yuluo-yx Date: Sat, 24 Oct 2026 02:50:29 +0800 Subject: [PATCH 1/3] refactor(persistence): target durable adapters at loop core --- docs/architecture/persistence-ownership.md | 50 +++++++++++++++++++ .../argi-graph-persistence-jdbc/pom.xml | 4 +- .../argi-graph-persistence-mongodb/pom.xml | 4 +- .../argi-graph-persistence-redis/pom.xml | 8 +-- pom.xml | 1 + 5 files changed, 59 insertions(+), 8 deletions(-) create mode 100644 docs/architecture/persistence-ownership.md diff --git a/docs/architecture/persistence-ownership.md b/docs/architecture/persistence-ownership.md new file mode 100644 index 000000000..35ddc100f --- /dev/null +++ b/docs/architecture/persistence-ownership.md @@ -0,0 +1,50 @@ +# 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. +- 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..c7afe6317 100644 --- a/graph-persistence/argi-graph-persistence-jdbc/pom.xml +++ b/graph-persistence/argi-graph-persistence-jdbc/pom.xml @@ -43,8 +43,8 @@ io.github.agentic-ai-java - argi-graph-core - ${argi.version} + argi-loop-core + ${argi.loop.version} diff --git a/graph-persistence/argi-graph-persistence-mongodb/pom.xml b/graph-persistence/argi-graph-persistence-mongodb/pom.xml index 81cb2283e..4cd8d94ee 100644 --- a/graph-persistence/argi-graph-persistence-mongodb/pom.xml +++ b/graph-persistence/argi-graph-persistence-mongodb/pom.xml @@ -39,8 +39,8 @@ io.github.agentic-ai-java - argi-graph-core - ${argi.version} + argi-loop-core + ${argi.loop.version} diff --git a/graph-persistence/argi-graph-persistence-redis/pom.xml b/graph-persistence/argi-graph-persistence-redis/pom.xml index 376dcb41f..04d9a5c66 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} @@ -51,8 +51,8 @@ io.github.agentic-ai-java - argi-graph-core - ${argi.version} + argi-loop-core + ${argi.loop.version} test-jar test diff --git a/pom.xml b/pom.xml index e87d24c80..acf1ed494 100644 --- a/pom.xml +++ b/pom.xml @@ -157,6 +157,7 @@ 2.1.0-RC2-SNAPSHOT 2.1.0-RC1 + 2.1.0-RC2-SNAPSHOT 17 From 6c538d2d6d30c43afa832eca9de6f5fd06ba47c4 Mon Sep 17 00:00:00 2001 From: yuluo-yx Date: Sat, 24 Oct 2026 02:51:59 +0800 Subject: [PATCH 2/3] test(persistence): retain legacy backend compatibility fixtures --- docs/architecture/persistence-ownership.md | 2 ++ graph-persistence/argi-graph-persistence-jdbc/pom.xml | 7 +++++++ graph-persistence/argi-graph-persistence-mongodb/pom.xml | 7 +++++++ graph-persistence/argi-graph-persistence-redis/pom.xml | 7 +++++++ 4 files changed, 23 insertions(+) diff --git a/docs/architecture/persistence-ownership.md b/docs/architecture/persistence-ownership.md index 35ddc100f..a81fd0b1c 100644 --- a/docs/architecture/persistence-ownership.md +++ b/docs/architecture/persistence-ownership.md @@ -29,6 +29,8 @@ versions, leases, retention and recovery tests stay here. - 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. diff --git a/graph-persistence/argi-graph-persistence-jdbc/pom.xml b/graph-persistence/argi-graph-persistence-jdbc/pom.xml index c7afe6317..4342bb057 100644 --- a/graph-persistence/argi-graph-persistence-jdbc/pom.xml +++ b/graph-persistence/argi-graph-persistence-jdbc/pom.xml @@ -47,6 +47,13 @@ ${argi.loop.version} + + io.github.agentic-ai-java + argi-graph-core + ${argi.version} + test + + org.postgresql postgresql diff --git a/graph-persistence/argi-graph-persistence-mongodb/pom.xml b/graph-persistence/argi-graph-persistence-mongodb/pom.xml index 4cd8d94ee..d0a68ed22 100644 --- a/graph-persistence/argi-graph-persistence-mongodb/pom.xml +++ b/graph-persistence/argi-graph-persistence-mongodb/pom.xml @@ -43,6 +43,13 @@ ${argi.loop.version} + + io.github.agentic-ai-java + argi-graph-core + ${argi.version} + test + + org.mongodb mongodb-driver-sync diff --git a/graph-persistence/argi-graph-persistence-redis/pom.xml b/graph-persistence/argi-graph-persistence-redis/pom.xml index 04d9a5c66..26707f702 100644 --- a/graph-persistence/argi-graph-persistence-redis/pom.xml +++ b/graph-persistence/argi-graph-persistence-redis/pom.xml @@ -57,6 +57,13 @@ test + + io.github.agentic-ai-java + argi-graph-core + ${argi.version} + test + + org.springframework.boot spring-boot-starter-test From 919743150246e33f7dc3c1f74a9f977a13b88fcf Mon Sep 17 00:00:00 2001 From: yuluo-yx Date: Sat, 24 Oct 2026 02:52:51 +0800 Subject: [PATCH 3/3] chore(build): preserve loop version property --- pom.xml | 1 + 1 file changed, 1 insertion(+) diff --git a/pom.xml b/pom.xml index acf1ed494..18172bec4 100644 --- a/pom.xml +++ b/pom.xml @@ -158,6 +158,7 @@ 2.1.0-RC2-SNAPSHOT 2.1.0-RC1 2.1.0-RC2-SNAPSHOT + 2.1.0-RC2-SNAPSHOT 17