feat(coordination): support dynamic contract and occurrence evolution

.cz.toml

@@ -2,5 +2,5 @@
 name = "cz_conventional_commits"
 tag_format = "v$version"
 version_scheme = "semver"
-version = "3.0.0-rc.3"
+version = "3.0.0-rc.4"
 update_changelog_on_bump = true

.github/scripts/prepare-rc-release.js

@@ -4,7 +4,7 @@ const { execFileSync } = require('node:child_process');
 const fs = require('node:fs');
 
 const CZ_TOML = '.cz.toml';
-const RELEASE_AUTHORITY = 'docs/releases/3.0.0-rc.3.md';
+const RELEASE_AUTHORITY = 'docs/releases/3.0.0-rc.4.md';
 const MAIN_REF = process.env.RC_BASE_REF || 'origin/main';
 const VALID_BUMPS = new Set(['major', 'minor', 'patch']);
 
@@ -110,9 +110,9 @@ function nextVersionForCurrentRc(currentVersion, latestTaggedRc) {
 }
 
 function authorityRelease(content) {
-  const match = content.match(/^RC3_VERSION:\s*(\S+)\s*$/m);
+  const match = content.match(/^RC4_VERSION:\s*(\S+)\s*$/m);
   if (!match) {
-    throw new Error(`Release authority is missing RC3_VERSION: ${RELEASE_AUTHORITY}`);
+    throw new Error(`Release authority is missing RC4_VERSION: ${RELEASE_AUTHORITY}`);
   }
   return match[1];
 }

.github/scripts/prepare-rc-release.test.js

@@ -33,23 +33,23 @@ test('advances an RC after the current tag exists', () => {
 });
 
 test('reads the release bound by the current authority', () => {
-  assert.equal(authorityRelease('RC3_VERSION: 3.0.0-rc.3\n'), '3.0.0-rc.3');
+  assert.equal(authorityRelease('RC4_VERSION: 3.0.0-rc.4\n'), '3.0.0-rc.4');
   assert.throws(
     () => authorityRelease('# missing marker\n'),
-    /Release authority is missing RC3_VERSION/,
+    /Release authority is missing RC4_VERSION/,
   );
 });
 
 test('rejects a prepared RC that differs from its authority', () => {
   assert.doesNotThrow(() => assertAuthorityRelease(
-    '3.0.0-rc.3',
-    'RC3_VERSION: 3.0.0-rc.3\n',
+    '3.0.0-rc.4',
+    'RC4_VERSION: 3.0.0-rc.4\n',
   ));
   assert.throws(
     () => assertAuthorityRelease(
-      '3.0.0-rc.4',
-      'RC3_VERSION: 3.0.0-rc.3\n',
+      '3.0.0-rc.5',
+      'RC4_VERSION: 3.0.0-rc.4\n',
     ),
-    /Prepared RC 3\.0\.0-rc\.4 does not match authorized release 3\.0\.0-rc\.3/,
+    /Prepared RC 3\.0\.0-rc\.5 does not match authorized release 3\.0\.0-rc\.4/,
   );
 });

.gitignore

@@ -4,3 +4,6 @@ build/
 out/
 *.class
 .DS_Store
+
+# Optional local Round 13 baseline; never a release input.
+Archive.zip

CHANGELOG.md

@@ -3,6 +3,33 @@
 This project follows Semantic Versioning. Release candidates may still refine
 the new 3.x API before the first stable 3.0.0 release.
 
+## 3.0.0-rc.4 - dynamic contract and occurrence evolution candidate
+
+### Added
+
+- Automatic managed-occurrence resolution for exact current state and complete
+  new authored initial documents.
+- Typed resource demands, non-publishing suspension/retry, active-path rebind,
+  atomic managed publication, and dynamic cycle formation and dissolution.
+- Runtime contract generalization plus typed document-transition and
+  operation-route evidence.
+
+### Changed
+
+- The Maven Central graph is pinned to Language `3.1.0-rc.22`, BEX
+  `1.1.0-rc.4`, Repository `3.0.0-rc.21`, and Coordination
+  `3.0.0-rc.4`.
+- The rc.4 readiness gate is bound to the sealed dynamic-evolution handoff and
+  rebuilds fresh release artifacts from the published dependency graph.
+
+### Known limitations
+
+- Existing-session authored-initial attachment, retained historical epoch
+  catch-up, authoritative external Timeline completeness, Mandates, and
+  production multi-node durability remain unsupported.
+- The candidate remains in-memory, one-JVM, and sequential. It is not stable or
+  production-ready.
+
 ## 3.0.0-rc.3 - bounded external-pilot cyclic-topology SDK candidate
 
 ### Added
@@ -29,9 +56,18 @@ the new 3.x API before the first stable 3.0.0 release.
   the standalone staged-consumer fixture were retired from the live build.
 - Every test now follows the enforced lowercase `// given`, `// when`,
   `// then` structure.
+- Integration and slow scenario suites now share a private, non-published
+  `testSupport` layer instead of scenarios compiling against integration-test
+  output. Built-JAR consumer examples keep authored YAML in named resources so
+  the Java tests emphasize the application flow.
 - Managed-draft plans are preflighted before journal append and retained only
   while retry can make progress; terminal results retire the plan without
   erasing rollback evidence.
+- Developer documentation now has one canonical SDK journey for exact provider
+  entries and evolving managed closures, with current cycle, multi-Timeline,
+  operation-created lineage, ordering, diagnostics, migration, and deployment
+  guidance. Stale examples that selected the legacy engine as the public API
+  have been replaced or explicitly profile-labeled.
 
 ### Known limitations
 

CONTRIBUTING.md

@@ -31,15 +31,20 @@ the changelog, and run `git diff --check`.
 
 ## Design rules
 
-- Keep `blue.coordination.api` immutable and small.
-- Never expose `blue.coordination.internal` in a public signature.
-- Append never routes or processes; the sequential drain coordinator owns
-  canonical entry selection.
-- One document transition is the atomic commit boundary. Do not add a
-  whole-engine rollback snapshot.
-- Keep Process Embedded binding topology immutable and cursor progress separate.
+- Keep `blue.coordination.sdk` immutable and application-focused.
+- Keep `blue.coordination.api` as the explicit low-level host and compatibility
+  boundary; never present its plain `inMemory()` profile as the SDK default.
+- Never expose `blue.coordination.internal` in a normal application signature.
+- Append never chooses recipients or invokes PROCESS; the environment owns
+  canonical entry and closure selection.
+- Preserve the copy-on-write atomic boundary for one connected affected
+  Contracts closure. Do not add a whole-engine rollback snapshot or collapse
+  disconnected closure outcomes.
+- Keep managed occurrence lineage, active/inactive topology generations, and
+  historical progress as distinct exact evidence.
 - Unsupported semantics fail with a `CoordinationException` and stable error
-  code; never silently approximate them.
+  code at the low-level boundary or a documented SDK validation exception or
+  `Diagnostic` at the facade boundary; never silently approximate them.
 - Every semantic guarantee or fixed regression needs an executable test.
 - Performance work must report frozen semantic and Coordination host time
   separately.

DYNAMIC_EVOLUTION_COORDINATION_HANDOFF_RECEIPT.md

@@ -0,0 +1,119 @@
+# Dynamic evolution Coordination handoff receipt
+
+Generated: 2026-08-26T03:37:29Z
+
+## Verdict
+
+**PASS.** Coordination's dynamic-evolution source is complete for the bounded
+local milestone and is available as a closed immutable handoff. Java 17 and
+Java 21 each executed the same 582-test release suite with zero failures,
+errors, or skips. A fresh final handoff reproduced the exact bytes used by the
+MyOS full gate.
+
+This is an invocation-local handoff. It does not publish, deploy, or replace
+the public `blue.coordination:blue-coordination-java:3.0.0-rc.3` coordinate,
+and it is not a production-readiness claim.
+
+## Source and ownership boundary
+
+| Role | Identity |
+| --- | --- |
+| Accepted Coordination base | `c6f9c80d0a33c6c209c7ba3d2b8bff89a223fc5f` |
+| Semantic source under test | `612f864ec7101bcac5a0cc596ad6b6f11cd10c98` |
+| Semantic source tree | `48c81c91b3232bd628b4fbb2a5d5e8bb49d888d4` |
+| Contracts source | `5a57bb82180fa31e868cd13fe41933a67a532d62` |
+| Contracts manifest | `sha256:6f719a206318a91f510da18f56ef34b863c95b062ef87a6784bef47737a09d52` |
+| Evidence branch | `feat/dynamic-contract-evolution-resume` |
+| Final alias | `feat/dynamic-contract-evolution-milestone` |
+
+There are 29 reviewed commits between the accepted Coordination base and the
+semantic source under test. They retain automatic managed occurrence
+resolution, active rebinds, exact current and new-initial resolution, typed
+demands, dynamic closure publication, runtime generalization, typed transition
+evidence, and typed operation-route deltas. The final `612f864` change only
+aligns test phase markers with the repository's release architecture gate.
+
+The commit containing this receipt is deliberately not the semantic source
+under test and cannot self-identify. Its commit ID is reported externally.
+
+## Release gates
+
+| Lane | Classes | Tests | Failures | Errors | Skipped | Duration |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Java 17 unit | 81 | 468 | 0 | 0 | 0 | included below |
+| Java 17 integration | 41 | 91 | 0 | 0 | 0 | included below |
+| Java 17 consumer | 3 | 9 | 0 | 0 | 0 | included below |
+| Java 17 scenario | 10 | 14 | 0 | 0 | 0 | included below |
+| **Java 17 total** | **135** | **582** | **0** | **0** | **0** | **2h 44m 9s** |
+| Java 21 unit | 81 | 468 | 0 | 0 | 0 | included below |
+| Java 21 integration | 41 | 91 | 0 | 0 | 0 | included below |
+| Java 21 consumer | 3 | 9 | 0 | 0 | 0 | included below |
+| Java 21 scenario | 10 | 14 | 0 | 0 | 0 | included below |
+| **Java 21 total** | **135** | **582** | **0** | **0** | **0** | **2h 28m 54s** |
+
+These are two JVM executions of the same 582 tests, not 1,164 distinct tests.
+Both release runs also passed production-shape and artifact checks, public API
+and SDK boundaries, test architecture, accepted-base binary compatibility,
+immutable dependency isolation, documentation and metadata gates, Javadocs,
+and extracted-source verification. The separate immutable-stage
+`dependencyPreflight` passed in four seconds, and final source worktrees were
+clean with `git diff --check` passing.
+
+Preserved evidence tree identities:
+
+| Evidence | SHA-256 |
+| --- | --- |
+| Java 17 XML | `c4268e29e998be7a1be2b155b5f416083a884dd12760a54e04f3925cee8e56b9` |
+| Java 17 reports | `dbe4a530f706dcc67ffb11b910ae419685ac39e494b5d776a76480da3a5ff590` |
+| Java 21 XML | `9499cdf69c2c24b3dcff40df9646a06df399a23766f64524241be86b08b84132` |
+| Java 21 reports | `5cdc7246f7d691991bb397700937e5e274905697d953d73fbc0b12d6eb617c50` |
+
+## Final immutable stage
+
+| Property | Value |
+| --- | --- |
+| Schema | `blue-coordination-staged-dependency-repository/1.0` |
+| Coordinate | `blue.coordination:blue-coordination-java:3.0.0-rc.3` |
+| Source commit | `612f864ec7101bcac5a0cc596ad6b6f11cd10c98` |
+| Manifest | `sha256:b1a8bdccdf1e7d188cfbca25c54eed0e48f52b06786486809bf46c854d0a9b09` |
+| Runtime JAR | `sha256:672edbc57dd786a0a9fe7fe7da3e7d1a4d577cd27a668188273ee21067c222b9` |
+| Sources JAR | `sha256:9a9931308de938defcd7965e412fcd5b9f216c2563f7b2412ed3fe78124d3685` |
+| Javadoc JAR | `sha256:b009ca76d83b15983785164dd31da67e0d221dd793715a72c4a38f24e7566787` |
+| POM | `sha256:ae56808fa7846405c47d01659ce9deb97377c316fe9d2fc5db8ff487ac61b8b7` |
+| Byte-equal repeat | `true` |
+| Isolated staged consumer | `PASS` |
+| Accepted-base compatibility | `PASS` — 109 baseline classes, 135 current, 26 additions, no removals |
+| Maven Local / remote fallback | `false` / `false` |
+
+The final repository was generated in a fresh detached clone and recursively
+compared with the provisional handoff. The comparison was empty. Therefore the
+MyOS full gate, which consumed the provisional path, consumed these exact final
+bytes and needs no dependency rerun.
+
+## Supported milestone behavior
+
+- Automatic managed occurrence resolution.
+- Automatic reuse of an exact current managed document.
+- Automatic creation from a complete new authored pre-initialization value.
+- Typed exact-resource suspension and retry with no partial publication.
+- Atomic managed publication and active-path rebind.
+- Dynamic cycle formation and dissolution.
+- Runtime generalization after contract mutation.
+- Retained typed document-transition, contract-patch, generated-write,
+  Channel/subscription, graph/component, and operation-route evidence.
+
+`automaticNewAuthoredInitialDocumentResolutionSupported=true` does not imply
+attachment to an already progressed session by supplying that session's old
+authored-initial value. That different case remains unsupported.
+
+## Declared later-round limits
+
+- No attachment through an existing session's authored-initial state.
+- No retained historical epoch attachment or retained-event catch-up.
+- No authoritative external Timeline import or completeness claim.
+- No Mandates or target-time eligibility.
+- No production multi-node durability.
+- Promoted descendants remain forward-only at the documented scalar-generation
+  boundary.
+
+Accordingly `productionReady`, `published`, and `deployed` are all `false`.

README.md

@@ -14,21 +14,28 @@ repositories {
 }
 
 dependencies {
-    implementation 'blue.coordination:blue-coordination-java:3.0.0-rc.3'
+    implementation 'blue.coordination:blue-coordination-java:3.0.0-rc.4'
 }
 ```
 
-`3.0.0-rc.3` is the bounded external-pilot candidate. It consumes Language
-`3.1.0-rc.21`, BEX `1.1.0-rc.4`, and Repository `3.0.0-rc.21` from Maven
+`3.0.0-rc.4` is the bounded external-pilot candidate. It consumes Language
+`3.1.0-rc.22`, BEX `1.1.0-rc.4`, and Repository `3.0.0-rc.21` from Maven
 Central and is compiled with `--release 17`. It is not a stable or production
 release. Version 3 is a breaking API reset; the removed 2.x planning,
 fragmentation, session-store, and fast-path APIs are not shimmed.
 
+For application development, follow the
+[complete SDK developer guide](docs/guides/developer-guide.md). It covers both
+processing an existing document/closure with a complete Timeline Entry and
+evolving an initially known closure through several Timelines, including
+cycles and operation-created managed documents. The
+[documentation index](docs/README.md) separates application guides, API
+reference, semantics, internals, and historical release evidence.
+
 ## Counter quickstart
 
 ```java
 import blue.coordination.sdk.BlueCoordination;
-import blue.coordination.sdk.ManagedClosure;
 import blue.coordination.sdk.ManagedDocument;
 
 try (BlueCoordination blue = BlueCoordination.inMemory()) {
@@ -162,24 +169,26 @@ lowercase `// given`, `// when`, `// then` sequence, enforced by
 `dependencyPreflight` resolves the exact conflict-free Blue graph from Maven
 Central. Repository rc.21 still advertises Language rc.20 transitively, so the
 build and published POM exclude that one edge and directly own Language
-rc.21. Local composites, Maven Local, and file-based staging repositories are
+rc.22. Local composites, Maven Local, and file-based staging repositories are
 retired from the live build.
 
 The release workflow runs the same gates, stages signed artifacts, publishes
-through JReleaser, and pushes the rc.3 tag only after publication succeeds. See
+through JReleaser, and pushes the rc.4 tag only after publication succeeds. See
 the [release procedure](docs/development/releasing.md) and
-[rc.3 release decision](docs/releases/3.0.0-rc.3.md).
+[rc.4 release decision](docs/releases/3.0.0-rc.4.md).
 
 `releaseCheck` does not read or execute `../blue-basic`. That sibling is
 retained only as a historical performance/metrics laboratory.
 
-Start with [START-HERE.md](START-HERE.md), then see the compact architecture,
-managed `Process Embedded` semantics, catch-up rules, performance
-interpretation, and limitations under `docs/`.
+Start with [START-HERE.md](START-HERE.md), continue with the
+[SDK developer guide](docs/guides/developer-guide.md), and use the
+[documentation index](docs/README.md) to find architecture, managed
+`Process Embedded` semantics, catch-up rules, operational behavior, and
+limitations.
 ## Historical release-candidate evidence
 
 The current release authority is the
-[3.0.0-rc.3 decision](docs/releases/3.0.0-rc.3.md). The documents below are
+[3.0.0-rc.4 decision](docs/releases/3.0.0-rc.4.md). The documents below are
 retained evidence for rc.1 and are not reused as current artifact hashes.
 
 The retained 3.0.0-rc.1 report covers the earlier Round 10.1 Process Embedded
@@ -202,12 +211,14 @@ See the [canonical RC report](docs/releases/3.0.0-rc.1-test-report.md),
 
 Developer references:
 
+- [Documentation index](docs/README.md)
+- [SDK developer guide](docs/guides/developer-guide.md)
 - [Build and test](docs/development/build-and-test.md)
 - [Test strategy](docs/development/test-strategy.md)
 - [Initialization causality](docs/semantics/initialization-causality.md)
 - [Shared NBA Game lifecycle](docs/examples/nba-shared-game-lifecycle.md)
 - [Five-occurrence Playground API example](docs/examples/playground-five-occurrence.md)
-- [3.0.0-rc.3 release decision](docs/releases/3.0.0-rc.3.md)
+- [3.0.0-rc.4 release decision](docs/releases/3.0.0-rc.4.md)
 - [Canonical RC evidence report](docs/releases/3.0.0-rc.1-test-report.md)
 - [Public API](docs/reference/public-api.md)
 - [SDK migration and ownership ledger](docs/reference/sdk-migration-and-ownership.md)