merge: reconcile release/0.7.0 into the 0.7.1 epic so #440 stops conflicting

build-logic/src/test/kotlin/dev/tramai/build/quality/ModuleCatalogMutationTest.kt

@@ -4,6 +4,7 @@ import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.io.TempDir
 import java.io.File
 import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
 import kotlin.test.assertNotEquals
 import kotlin.test.assertNotNull
 import kotlin.test.assertTrue
@@ -455,16 +456,56 @@ class ModuleCatalogMutationTest {
         val catalog = ModuleCatalog.fromRootDir(tempDir).parse()
         assertEquals(emptySet(), codes(catalog), "catalog must parse clean, got ${codes(catalog)}")
 
+        assertLegacyDescriptionParity(catalog)
+    }
+
+    /**
+     * The parity oracle is frozen: it records the descriptions the removed
+     * `projectDescription()` compatibility function produced for the modules that
+     * existed at migration time. Parity is therefore defined for those modules —
+     * a module introduced later has no pre-B8 POM description to stay
+     * byte-identical to, but every pre-B8 module must still be published with an
+     * unchanged description.
+     */
+    private fun assertLegacyDescriptionParity(catalog: ModuleCatalog.CatalogResult) {
         val legacy = LegacyPublicationDescriptions.byModule()
-        catalog.modules.values
-            .filter { it.publishability == ModulePublishability.PUBLISHED }
-            .forEach { entry ->
-                val moduleName = entry.path.removePrefix(":")
-                assertEquals(
-                    legacy[moduleName],
-                    entry.description,
-                    "catalog description for $moduleName must exactly match the pre-B8 policy",
-                )
-            }
+        val published =
+            catalog.modules.values
+                .filter { it.publishability == ModulePublishability.PUBLISHED }
+                .associateBy { it.path.removePrefix(":") }
+
+        assertEquals(
+            emptySet(),
+            legacy.keys - published.keys,
+            "every pre-B8 published module must still be present and published in the catalog",
+        )
+        for ((moduleName, legacyDescription) in legacy) {
+            assertEquals(
+                legacyDescription,
+                published.getValue(moduleName).description,
+                "catalog description for $moduleName must exactly match the pre-B8 policy",
+            )
+        }
+    }
+
+    @Test
+    fun `D6 edited description of a pre-B8 module is rejected by the parity oracle`() {
+        fixtureDir()
+        val edited =
+            realCatalogText().replace(
+                "Core annotations, request models, provider registry, and exception types for Tramai.",
+                "Core annotations, request models, provider registry, and utility types for Tramai.",
+            )
+        assertNotEquals(realCatalogText(), edited, "mutation must change content")
+        writeCatalog(edited)
+
+        val catalog = ModuleCatalog.fromRootDir(tempDir).parse()
+        assertEquals(emptySet(), codes(catalog), "catalog must still parse clean")
+
+        val failure = assertFailsWith<AssertionError> { assertLegacyDescriptionParity(catalog) }
+        assertTrue(
+            failure.message?.contains("tramai-core") == true,
+            "parity failure must name the edited module, got ${failure.message}",
+        )
     }
 }

docs/LONG-TERM-ROADMAP-0.7-0.10.md

@@ -48,6 +48,8 @@ Authorized provider/model candidates + stable reason paths
         ↓
 Policy-constrained selection and execution
         ↓
+Reference external-runtime authority proof
+        ↓
 Authoritative typed governance evidence
         ↓
 Control-plane projection/query API
@@ -86,6 +88,7 @@ Unless an implementation finding makes one necessary for P0 correctness or secur
 - key rotation/KMS breadth;
 - Docker/Helm product packaging;
 - broad Spring adoption sugar;
+- broad framework-adapter matrix beyond the single 0.7 reference authority proof;
 - broad compliance-framework mapping.
 
 Those concerns remain valuable architectural inputs, but they belong to later release themes.
@@ -122,7 +125,9 @@ See [`ROADMAP-0.8.0-GOVERNANCE-DX-AND-INTELLIGENCE.md`](ROADMAP-0.8.0-GOVERNANCE
 - governance contract testing;
 - developer-local governance debugger;
 - deterministic findings and richer incident analysis;
-- approval-lifetime and safe-replacement refinement where still needed.
+- approval-lifetime and safe-replacement refinement where still needed;
+- cross-runtime governance adapter SDK/TCK and additional framework integrations after the 0.7 reference proof;
+- runtime capability provenance and effect/reversibility semantics (`READ_ONLY`, `REVERSIBLE`, `COMPENSATABLE`, `IRREVERSIBLE`, `UNKNOWN`) where justified.
 
 ## Core invariants
 
@@ -279,6 +284,10 @@ Examples:
 | Learning traces | audit/telemetry must not silently become training-data collection |
 | Adaptive optimization | authorization, viability, and selection must remain distinct stages |
 | Helm/reference deployment | Dashboard/control plane must remain headless/API-first and not own policy authority |
+| Cross-runtime governance adapters | 0.7 workload identity, decisions, approval, and evidence must not depend on TramAI owning the agent runtime |
+| Governance simulation/testing | 0.7 deterministic policy/authorization evaluation must remain side-effect-free and reusable rather than embedding execution side effects into decision meaning |
+| Effect-aware governance/compensation | 0.7 cancellation and evidence must distinguish fencing future execution from reversing or compensating external effects that already occurred |
+| Enforcement provenance | 0.7 evidence/query contracts must preserve the difference between authoritative enforcement, partial instrumentation, observation, and imported evidence |
 
 Core rule:
 

docs/ROADMAP-0.7.0-RELEASE-CUT.md

@@ -247,6 +247,37 @@ P0 behavior is protected by deterministic tests, compatibility/TCK coverage wher
 - reconstruction side effects;
 - sensitive payload exposure.
 
+### Reference external-runtime authority proof
+
+0.7.0 must include one narrow proof that TramAI can authoritatively govern an execution boundary initiated by a **non-TramAI-authored JVM AI workload** without introducing a second policy model.
+
+The reference target is **Spring AI**. This is an architecture proof, not a productionized adapter programme.
+
+The proof must demonstrate, at the declared governed boundary:
+
+```text
+external runtime intent
+        ↓
+TramAI workload/run identity
+        ↓
+authoritative TramAI governance decision
+        ↓
+ALLOW / DENY / REQUIRE_APPROVAL
+        ↓
+execution or governed suspension
+```
+
+Required properties:
+
+- `DENY` prevents execution at the declared boundary;
+- `REQUIRE_APPROVAL` cannot execute before authoritative approval;
+- workload/configuration/run and decision correlation survive the external-runtime boundary;
+- an authoritative integration does not silently fail open when TramAI evaluation is unavailable;
+- the external runtime does not gain a second policy/authorization model;
+- evidence identifies the runtime/integration boundary and does not overstate TramAI's enforcement strength.
+
+The first integration contract may remain experimental. The stable commitment is the governance meaning, not a framework-shaped adapter API.
+
 ---
 
 # 4. Explicitly not part of 0.7.0
@@ -266,7 +297,9 @@ The following do **not** block 0.7.0 unless implementation proves that a narrow
 - dynamic tool-obligation lifecycle refinement;
 - broader metadata-classification ergonomics;
 - richer deterministic findings/incident analysis;
-- approval lifetime/replacement redesign beyond existing safety requirements.
+- approval lifetime/replacement redesign beyond existing safety requirements;
+- broad Spring AI / Koog / LangChain4j / Embabel adapter matrix beyond the single reference external-runtime authority proof;
+- productionized framework-adapter SDK/TCK ergonomics beyond what the reference proof requires.
 
 See [`ROADMAP-0.8.0-GOVERNANCE-DX-AND-INTELLIGENCE.md`](ROADMAP-0.8.0-GOVERNANCE-DX-AND-INTELLIGENCE.md).
 
@@ -344,6 +377,46 @@ The canonical/authoritative execution input remains distinct from provider-speci
 
 Existing model-output/tool-result DLP remains valid; 0.7 must preserve compatibility or provide an explicit migration path if implementation changes its public contracts.
 
+## J. Framework-independent governance authority
+
+A governed workload is not synonymous with a TramAI-authored workflow.
+
+Core workload identity, policy, decision, approval, and evidence semantics must remain usable when execution intent originates in another JVM AI runtime. Framework/runtime identity is metadata about the execution source, not the source of governance authority.
+
+```text
+governed workload != TramAI-authored workflow
+```
+
+## K. Deterministic, side-effect-free governance decisions
+
+Where a governance decision is defined as deterministic, equivalent authoritative facts under the same policy/configuration must produce the same pre-execution decision.
+
+```text
+same authoritative facts + same policy/configuration
+= same governance decision
+```
+
+The evaluator that determines policy/authorization meaning must not itself invoke providers, execute tools, create external side effects, or depend on Dashboard behavior. Public simulation remains 0.8 scope; 0.7 preserves the semantic boundary that makes simulation possible without a second engine.
+
+## L. Enforcement and evidence provenance
+
+Observation is not enforcement.
+
+Evidence/query contracts must preserve enough source/authority information to distinguish a TramAI-enforced decision from an instrumented, observed, or imported fact. Exact public enum names are an implementation decision.
+
+```text
+observed != enforced
+telemetry != proof of prevention
+```
+
+An external runtime or client must not be able to upgrade its own claimed enforcement strength merely by supplying metadata.
+
+## M. Stable semantics, experimental integrations
+
+0.7 should stabilize governance meaning before stabilizing framework-specific adapter APIs.
+
+Stable commitments should center on workload identity, policy/decision semantics, structured reasons, authority/provenance, and evidence correlation. Initial external-runtime integration APIs may remain experimental until at least one reference adapter has proved the boundary.
+
 ---
 
 # 6. Critical dependency graph
@@ -404,6 +477,7 @@ Classification/policy work may define provider-input release obligations before
 3. Policy-constrained selection/fallback.
 4. Provider-specific release/minimization integration immediately before invocation, including recomputation on provider-changing fallback/retry.
 5. Decision/configuration identity/digest where required for evidence.
+6. **Reference external-runtime authority proof using Spring AI**, after the 0.7.2/0.7.3 decision semantics exist and before 0.7.4 evidence/projection contracts are considered frozen.
 
 ## Wave C — evidence and control plane
 
@@ -454,6 +528,9 @@ into the provider invocation
         ↓
 Authoritative decision/evidence emitted
         ↓
+Reference external-runtime boundary proves the same governance authority
+without TramAI owning the agent runtime
+        ↓
 Control plane projects the run safely
         ↓
 Operator can inspect the semantic timeline

docs/ROADMAP-0.8.0-GOVERNANCE-DX-AND-INTELLIGENCE.md

@@ -109,6 +109,34 @@ Existing 0.7 safety defects remain P0 defects if discovered; broader lifecycle p
 
 Detailed design: [`design/APPROVAL-VALIDITY-REPLACEMENT-AND-LIFECYCLE.md`](design/APPROVAL-VALIDITY-REPLACEMENT-AND-LIFECYCLE.md).
 
+### 2.8 Cross-runtime governance DX and adapter compatibility
+
+- turn the 0.7 XR1 reference proof into a reusable adapter SDK/SPI only after the semantic boundary has been proven;
+- define an adapter compatibility/TCK profile for declared enforcement modes;
+- add additional runtime adapters based on adoption value, with candidates including Koog, LangChain4j, Embabel, ADK, MCP execution boundaries, and custom JVM runtimes;
+- preserve the rule that adapters depend inward on stable governance semantics rather than leaking framework-specific agent concepts into core;
+- support developer-local inspection of runtime/framework identity, boundary coverage, adapter health, and known bypass limitations;
+- keep adapter APIs experimental until native plus external paths demonstrate that the contract generalizes.
+
+Candidate TCK assertions include: `DENY` prevents execution at the declared authoritative boundary, `REQUIRE_APPROVAL` cannot execute early, identity/correlation is preserved, stale decisions cannot authorize a new action, fail-open/fail-closed behavior is explicit, and evidence does not overstate enforcement strength.
+
+### 2.9 Runtime capability provenance and effect semantics
+
+- model where executable capabilities originate, including native tools, MCP tools, remote agents, models/providers, external APIs, and network destinations;
+- keep capability registration/discovery/exposure distinct from permission to execute;
+- introduce effect/reversibility metadata where justified:
+
+```text
+READ_ONLY
+REVERSIBLE
+COMPENSATABLE
+IRREVERSIBLE
+UNKNOWN
+```
+
+- allow effect semantics to influence approval, risk findings, evidence, and incident response without pretending compensation is transactional rollback;
+- keep a full saga/compensation engine out of the release unless concrete use cases justify it separately.
+
 ---
 
 ## 3. Dependencies on 0.7
@@ -123,7 +151,9 @@ Detailed design: [`design/APPROVAL-VALIDITY-REPLACEMENT-AND-LIFECYCLE.md`](desig
 - control-plane projection/query;
 - authorized runtime control;
 - authoritative persisted suspended-run cancellation and future-resume fencing;
-- forensic reconstruction without side effects.
+- forensic reconstruction without side effects;
+- one reference external-runtime authority proof showing that governance semantics do not require TramAI to own the agent runtime;
+- evidence authority/provenance semantics that distinguish authoritative enforcement from instrumented, observed, or imported facts.
 
 0.8 may improve authoring and analysis around those contracts but must not redefine their authority model casually.
 
@@ -137,6 +167,7 @@ Detailed design: [`design/APPROVAL-VALIDITY-REPLACEMENT-AND-LIFECYCLE.md`](desig
 - governed raw-content learning capture, dataset export, FinOps breadth, or adaptive optimization owned by 0.10;
 - a generic business-rules engine;
 - a general ontology/knowledge-graph platform;
+- a promise to productize every JVM framework adapter in one release;
 - a second workflow executor;
 - a second policy engine;
 - a visual workflow builder as a release blocker;
@@ -161,6 +192,8 @@ execute through the same authoritative TramAI runtime
         ↓
 inspect structured reasons/debug information
         ↓
+govern at least one non-TramAI-authored JVM workload through the same semantic authority
+        ↓
 reconstruct/replay deterministic governance meaning where evidence permits
 ```