Skip to content

feat!: introduce the graph-focused Coordination 3.0 runtime - #13

Merged
piotr-blue merged 16 commits into
nextfrom
feature/graph-focused-approach
Aug 13, 2026
Merged

feat!: introduce the graph-focused Coordination 3.0 runtime#13
piotr-blue merged 16 commits into
nextfrom
feature/graph-focused-approach

Conversation

@piotr-blue

Copy link
Copy Markdown
Contributor

Summary

  • Replace the legacy 2.x planning and fragmentation runtime with a compact Java 17 graph-focused Coordination engine.
  • Add deterministic whole-document and Timeline Entry processing, immutable revisions, managed embedded documents, historical catch-up, shared-child reuse, nested settlement, canonical ordering, and idempotent retries.
  • Add initialization-event forwarding, structural metrics, public-JAR consumer tests, and realistic NBA, PayNote, and Playground scenarios.
  • Remove deprecated 2.x runtime surfaces, compatibility shims, obsolete benchmarks, and outdated architecture documentation.

Dependencies and CI

  • Use published Maven Central dependencies by default:
    • blue.repo:blue-repo-java:3.0.0-rc.21
    • blue.bex:blue-bex-core:1.1.0-rc.3
    • blue.bex:blue-bex-contracts:1.1.0-rc.3
  • Keep local composite dependencies only as an explicit diagnostic option.
  • Run clean verification on Java 17 and Java 21 in GitHub Actions.
  • Fix RC version selection so the release workflow respects the declared 3.0 RC series.
  • Keep release staging fail-closed until final evidence is complete.

Verification

  • 342 tests across 85 classes passed on Java 17 and Java 21.
  • Published dependency preflight passed.
  • releaseCheck passed on Java 17 and Java 21.
  • Extracted-source tests and published-artifact smoke passed.
  • RC version-selection tests passed.

Release status

The branch is build-ready, but not yet publication-ready.

The retained Round 13 campaign is historical after the dependency change and previously failed two absolute performance limits:

  • append p95: 18.680667 ms — hard limit 1.000000 ms
  • Coordination-host p95: 872.356126 ms — hard limit 250.000000 ms

stageRelease therefore remains intentionally blocked until performance is remediated and a fresh published-artifact campaign produces final passing evidence.

Breaking change

This establishes the 3.x API baseline. Removed 2.x planning, fragmentation, session-store, and fast-path APIs are not preserved through compatibility shims.

…cessor for benchmarks

Remove outdated classes including `StaticPayloadValidator`, `CoordinationRepositoryCompatibilityNodeProvider`, and legacy `RepositoryTypeAliasPreprocessor`. Migrate a tailored version of `RepositoryTypeAliasPreprocessor` to benchmarks for alias-related tests. Introduce new processors for timelines and coordination document splitting.
Remove `DeclaredTypeEventMatcherBenchmark`, `CoordinationRepositoryCompatibilityNodeProvider`, and `FixedRepositoryBoundSourceProvider`. These classes no longer align with the current architecture and have been deemed obsolete.
Add `basic-tests.gradle` to configure basic Java 17 acceptance tests using the myOS runtime. Include schemas for myOS round4 evidence and failure cases. Provide initial test cases (`BasicCounterTest`, `BasicPayNoteFieldTest`) and shared `BasicTestMetrics` for focused diagnostics and metrics reporting.
…ment`

Remove `BasicPayNoteFieldTest` and `EmbeddedOnlyDocumentEnvironment` as they are no longer relevant to the current testing and processing architecture.
This change deletes `ActivePathSet`, `AppAwareTimelineChannelProcessor`, and `Rc15RuntimeSupport` along with unused imports and legacy runtime implementations. These components are no longer required, reducing code complexity and improving maintainability.
Delete obsolete architecture documentation, including files related to embedded collections, fragmentation, runtime registration, subscription projection, engine processes, and quality exceptions. These documents no longer reflect the current system design and are no longer relevant.
Deleted outdated ADR documentation, simplifying the repository and removing redundant or unused references to design decisions. This cleanup reduces maintenance overhead by focusing on current architecture and plans.
Delete obsolete architecture documentation, including files related to embedded collections, fragmentation, runtime registration, subscription projection, engine processes, and quality exceptions. These documents no longer reflect the current system design and are no longer relevant.
…endency manifest

Introduce tests for release candidate (RC) version parsing, version advancement, and evidence validation in `prepare-rc-release.test.js`. Add a frozen script to generate the Round 13 published dependency manifest, ensuring reproducibility and verification of published artifacts.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a3fd2775b2

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread build.gradle Outdated
Comment on lines +113 to +114
implementation 'blue.repo:blue-repo-java:3.0.0-rc.21'
implementation 'blue.bex:blue-bex-core:1.1.0-rc.3'

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Expose processor dependencies on the compile classpath

With blue.repo and blue.bex-core published as implementation/runtime dependencies, consumers compiling against the published artifact do not get those classes on their compile classpath. The artifact exposes them in public signatures such as CoordinationProcessors.registerTimelineSubtype(... TimelineChannel ...), CoordinationProcessorOptions.Builder.bexEngine(BexEngine), and CoordinationBexIntrinsics.common(), so any consumer using the documented processor surface will fail to compile unless they manually add transitive dependencies that the POM/Gradle metadata should provide. Mark the public signature dependencies as api and update the publication POM check accordingly.

Useful? React with 👍 / 👎.

working-directory: blue-quickjs
- name: Run clean RC verification
run: >-
./gradlew --no-daemon clean releaseCheck

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Avoid gating every CI build on interim RC evidence

This workflow runs releaseCheck on every push/PR, but the committed canonical evidence is still INTERIM/PENDING_VERIFICATION with publicRcReady: BLOCKED and candidateCommit: null. releaseCheck rejects those values, so every build in this workflow will fail before tests can pass until final evidence is committed. Use a non-final verification task here or commit final PASS evidence before wiring releaseCheck into normal CI.

Useful? React with 👍 / 👎.

'src/integrationTest/resources/examples/playground/five-occurrence-initialization-host.yaml':
'b1e94c039d0fd0df70b0c803ebe921a290d1590bac69a9073fe4910ca8939b6b',
'src/scenarioTest/java/blue/coordination/integration/PlaygroundFiveOccurrenceEvidence.java':
'cbb936435d13c4bf5678fc6addedbf625801a4edc52c453c8a441caa1a2bf8d3'

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Replace the placeholder shim hash

When the documented Round 13 same-machine A/B preflight or verification reaches baselineTreeBinding, it compares each allowed baseline shim's computed projectSha256 against this pinned map. This value is not a SHA-256 digest because it contains added, so it cannot equal any sha256(readFileSync(...)) result and the evidence import will always fail once this added shim is present. Replace it with the actual 64-hex hash for the shim file.

Useful? React with 👍 / 👎.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 88c23934f4

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread build.gradle
Comment on lines +1033 to +1036
if (!buildText.contains(
"tasks.register('round13PlaygroundSample'")
|| !file('src/scenarioTest/java/blue/coordination/integration/PlaygroundFiveOccurrenceEvidence.java')
.isFile()) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Fix the proof-target check so documentation verification can run

When verifyDocumentation validates the Round 13 performance proof, this condition passes the result of the || expression into buildText.contains(...) instead of separately checking the build text and helper file. In a FINAL Round 13 evidence file that includes sourceSet: "performance", the task either throws a Groovy missing-method error for String.contains(Boolean) or always records the proof target as missing, so releaseCheck/stageRelease cannot complete even when the round13PlaygroundSample task and helper source are present.

Useful? React with 👍 / 👎.

Comment on lines +16 to +17
const RUNTIME_SCHEMA = 'blue-coordination-round13-five-occurrence-runtime-v3';
const PROVENANCE_SCHEMA = 'blue-coordination-round13-runtime-provenance-v3';

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep the verifier schema in sync with retained evidence

The retained Round 13 files advertised by the release notes are still schemaId v2, but --verify now accepts only these v3 constants; running node scripts/round13-ab-evidence.mjs --verify --candidate $PWD --runtime docs/releases/evidence/round13/five-occurrence-runtime.json --provenance docs/releases/evidence/round13/runtime-provenance.json --markdown docs/releases/evidence/round13/five-occurrence-runtime.md exits with Canonical schema ID differs. That leaves the documented independent validation path for the committed campaign receipts unusable until the evidence is regenerated as v3 or the verifier keeps v2 compatibility.

Useful? React with 👍 / 👎.

Comment on lines +207 to +209
public synchronized int rowCount() {
return rows.size();
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Count route rows, not route keys

When more than one document subscribes to the same operation/channel/timeline event key, rows holds one map entry with multiple RouteRows, but this gauge returns only the number of keys. CoordinationEngine.metrics().routeRowCount() and the Round 13 samples therefore under-report the active route rows in shared-route workloads; sum the list sizes instead.

Useful? React with 👍 / 👎.

@piotr-blue piotr-blue changed the title Feature/graph focused approach feat!: introduce the graph-focused Coordination 3.0 runtime Aug 13, 2026
@piotr-blue
piotr-blue merged commit 7d63137 into next Aug 13, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant