diff --git a/build-logic/src/test/kotlin/dev/tramai/build/quality/ModuleCatalogMutationTest.kt b/build-logic/src/test/kotlin/dev/tramai/build/quality/ModuleCatalogMutationTest.kt index 55cc722d3..7915af5bc 100644 --- a/build-logic/src/test/kotlin/dev/tramai/build/quality/ModuleCatalogMutationTest.kt +++ b/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 { assertLegacyDescriptionParity(catalog) } + assertTrue( + failure.message?.contains("tramai-core") == true, + "parity failure must name the edited module, got ${failure.message}", + ) } } diff --git a/docs/LONG-TERM-ROADMAP-0.7-0.10.md b/docs/LONG-TERM-ROADMAP-0.7-0.10.md index 79b99bc8b..fea4b2a99 100644 --- a/docs/LONG-TERM-ROADMAP-0.7-0.10.md +++ b/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: diff --git a/docs/ROADMAP-0.7.0-RELEASE-CUT.md b/docs/ROADMAP-0.7.0-RELEASE-CUT.md index a7f1b4068..262732f37 100644 --- a/docs/ROADMAP-0.7.0-RELEASE-CUT.md +++ b/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 diff --git a/docs/ROADMAP-0.8.0-GOVERNANCE-DX-AND-INTELLIGENCE.md b/docs/ROADMAP-0.8.0-GOVERNANCE-DX-AND-INTELLIGENCE.md index f729641bb..6a1b7bb02 100644 --- a/docs/ROADMAP-0.8.0-GOVERNANCE-DX-AND-INTELLIGENCE.md +++ b/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 ``` diff --git a/docs/design/ECOSYSTEM-GOVERNANCE-STRATEGY.md b/docs/design/ECOSYSTEM-GOVERNANCE-STRATEGY.md index 62f2fa69d..ed304bc33 100644 --- a/docs/design/ECOSYSTEM-GOVERNANCE-STRATEGY.md +++ b/docs/design/ECOSYSTEM-GOVERNANCE-STRATEGY.md @@ -1,8 +1,8 @@ -# TramAI 0.7.0 — Ecosystem Governance, Simulation, and Contract-Testing Addendum +# TramAI — Ecosystem Governance, Cross-Runtime Authority, Simulation, and Contract-Testing Strategy -> **Status:** Normative companion to `docs/ROADMAP-0.7.0.md` -> **Target:** TramAI 0.7.0 architecture and sequencing -> **Scope:** Strategic/architectural amendments derived from the 2026 JVM AI framework landscape +> **Status:** Cross-release design strategy; release ownership is defined by the authoritative 0.7/0.8 roadmaps +> **Target:** 0.7 architecture constraints + one reference external-runtime authority proof; 0.8 simulation/testing/debugger/adapter DX; later compensation execution where justified +> **Scope:** Strategic/architectural guidance derived from the 2026 JVM AI framework landscape > **Primary decision:** TramAI must remain valuable even when AI workloads are authored with another JVM framework. > **Positioning consequence:** **Build AI workloads with the framework that fits. Govern their execution with TramAI.** @@ -31,16 +31,14 @@ The strategic implication is not to abandon TramAI's runtime. It is to define a > TramAI's durable differentiation is **governance authority**, not generic agent authoring. -A company should not need to rewrite a Koog, Spring AI, LangChain4j, ADK, Genkit, or custom JVM workload merely to gain TramAI governance. +A company should not need to rewrite a Koog, Spring AI, LangChain4j, Embabel, Google ADK Java, or custom JVM workload merely to gain TramAI governance. -This addendum therefore strengthens four areas of the 0.7.0 roadmap: +This strategy has four release-owned consequences: -1. **cross-runtime governance boundary**; -2. **policy simulation / decision preview**; -3. **governance contract testing**; -4. **developer-local governance UX**. - -It also records a later architectural opportunity around **tool reversibility and compensation semantics**. +1. **0.7:** preserve a framework-independent governance boundary and prove it once against a non-TramAI JVM runtime; +2. **0.7:** preserve explicit enforcement/evidence provenance so observation cannot masquerade as prevention; +3. **0.8:** productize policy simulation, governance contract testing, local governance debugging, and adapter compatibility/TCK work over the same authoritative evaluator; +4. **0.8/later:** introduce capability provenance and tool effect/reversibility semantics, with automated compensation execution deferred until concrete use cases justify it. --- @@ -194,23 +192,20 @@ The local developer workflow is therefore a governance control surface, not cosm --- -## 4. Must-ship boundary amendments - -The six existing P0 capabilities in the main roadmap remain authoritative. - -Add the following architectural requirement to the P0 boundary: - -7. **Cross-runtime governance contract** defining how non-TramAI-authored JVM workloads can be identified, evaluated, observed, and—where integration strength permits—constrained without duplicating the policy engine. +## 4. Release ownership and must-ship boundary -Add the following P0/P1 capability: +The authoritative release roadmaps decide what blocks each release. This design note does not expand them implicitly. -8. **Policy Simulation / Decision Preview** using the authoritative policy/selection evaluator with all external side effects disabled. +For **0.7**, the must-ship consequences are: -Add the following P1 capability: +1. core workload/decision/evidence semantics do not require TramAI to own the agent runtime; +2. deterministic policy/authorization meaning remains side-effect-free so later simulation/testing can reuse it; +3. evidence preserves source/enforcement provenance and does not upgrade observation into proof of prevention; +4. one **reference external-runtime authority proof** (XR1, using Spring AI) demonstrates `ALLOW`, `DENY`, and `REQUIRE_APPROVAL` across a non-TramAI execution boundary without a second policy model. -9. **Governance Contract Testing** enabling deterministic CI assertions over classification, provider/model eligibility, tool approval, fallback, and other governance decisions. +For **0.8**, productize the broader DX layer described below: policy simulation/decision preview, governance contract testing, local governance debugger, adapter SDK/TCK and additional runtime integrations, plus capability/effect semantics where justified. -These additions do not require shipping production-grade adapters for every JVM framework in 0.7.0. The P0 requirement is the architecture and contract that prevents TramAI from becoming impossible to integrate later. +0.7 does **not** require production-grade adapters for every JVM framework, a public simulation API, a governance-testing SDK, or debugger UX. --- @@ -379,20 +374,21 @@ Therefore: 7. Replayed decision IDs must not accidentally authorize a different action. 8. Evidence must distinguish adapter-reported facts from TramAI-observed/enforced facts. -### 0.2.6 Initial adapter targets +### 0.2.6 Reference proof and later adapter targets -0.7.0 does **not** require all of these to ship. +0.7 XR1 uses **Spring AI** as the single reference external-runtime authority proof. It is intentionally narrow and may use an experimental integration surface. -Candidates for post-contract adapters: +0.8 candidates after XR1 include: -- Spring AI; - Koog; - LangChain4j; +- Embabel; +- Google ADK Java; - plain HTTP/custom JVM model clients; - MCP tool execution boundaries; -- generic OpenAI-compatible provider call boundary. +- generic OpenAI-compatible provider call boundaries. -The first production adapter should be selected by adoption value and ability to provide meaningful enforcement, not brand visibility. +Broader production adapters should be selected by adoption value and ability to provide meaningful enforcement, not brand visibility. ### 0.2.7 Acceptance criteria @@ -411,7 +407,7 @@ The first production adapter should be selected by adoption value and ability to ## Epic 1.2: Authoritative policy simulation -**Priority:** P0/P1 +**Priority:** 0.8 — Governance DX & Intelligence **Goal:** Allow developers/operators to ask "what would TramAI decide?" without executing a provider call, tool, workflow action, approval side effect, or network request. ### 1.2.1 Core invariant @@ -598,7 +594,7 @@ Diff mode may be P1 if basic simulation is P0/P1. ## Epic 5.2: Local governance debugger -**Priority:** P1, with P0 architectural compatibility +**Priority:** 0.8 — Governance DX & Intelligence; 0.7 preserves the structured decision/provenance inputs it needs **Goal:** Make TramAI governance understandable during development before a workload reaches an operational control plane. ### 5.2.1 Principle @@ -680,7 +676,7 @@ Rules: ## Epic D.1: Deterministic governance test kit -**Priority:** P1 +**Priority:** 0.8 — Governance DX & Intelligence **Goal:** Let teams prove governance invariants in CI without network calls, real models, or real tool side effects. ### D.1.1 Why this differs from generic AI testing @@ -840,7 +836,7 @@ SARIF is exploratory and should not block the initial test kit. ## Epic E.1: Reversibility metadata -**Priority:** P2 / later than the 0.7.0 core +**Priority:** 0.8 candidate for effect metadata; automated compensation execution is later/optional **Goal:** Allow governance decisions to account for whether a tool's external effect can be reversed or compensated. ### E.1.1 Motivation @@ -905,11 +901,11 @@ A "compensatable" action must never be presented as equivalent to a transaction Compensation can fail and may require separate authorization. -### E.1.5 0.7.0 decision +### E.1.5 Release ownership -Do not block 0.7.0 on compensation execution. +0.7 establishes only the honesty boundary: cancellation/fencing future execution must not be represented as compensation of already-produced external effects. -However, avoid tool-governance APIs that make future effect/reversibility metadata impossible to add cleanly. +0.8 may add effect/reversibility metadata where useful. A general compensation/saga execution engine remains later/optional and must never pretend compensatable is equivalent to transactional rollback. --- @@ -1107,21 +1103,11 @@ TramAI can provide the deterministic result without claiming that passing CI equ ## 8. Reference workflow amendment -Extend the primary 0.7.0 reference workflow with a pre-execution simulation and an external-runtime variant. +0.7 proves the native governed loop and one external-runtime authority boundary. 0.8 adds pre-execution simulation, contract testing, and debugger workflows over the same semantics. -### 8.1 Native flow +### 8.1 Native 0.7 flow ```text -Developer changes provider/tool policy - ↓ -Governance contract tests run - ↓ -Policy simulation shows candidate routes - ↓ -No unexpected governance regression - ↓ -Deploy - ↓ Sensitive document enters ↓ Classification @@ -1137,6 +1123,22 @@ Execution Semantic trace + evidence ``` +### 8.1a 0.8 developer preflight extension + +```text +Developer changes provider/tool policy + ↓ +Governance contract tests run + ↓ +Policy simulation shows candidate routes + ↓ +No unexpected governance regression + ↓ +Deploy + ↓ +execute through the same authoritative semantics +``` + ### 8.2 External-runtime flow ```text @@ -1163,73 +1165,46 @@ Evidence records include enforcement provenance ### 8.3 Demonstration acceptance criteria -At least one 0.7.x demonstration should eventually prove that TramAI governance is conceptually independent from agent authoring. +0.7 XR1 is the required reference proof that TramAI governance is conceptually independent from agent authoring. -The demo does not require every external framework. One adapter is enough to validate the boundary. +The proof does not require every external framework. One Spring AI integration boundary is enough to validate the architecture; broader adapter productization moves to 0.8. --- ## 9. Execution-order amendments -The main roadmap's dependency ordering remains valid, with these insertions. - -### Milestone A — Architecture contract - -Existing: - -1. control-plane authority/read-model/command ADR; -2. control-plane module/API scaffold; -3. safe projection rules. - -Add: - -4. **External-runtime governance boundary ADR/SPI**; -5. **enforcement-mode and evidence-provenance model**. +The authoritative 0.7 execution board remains the source of sequencing truth. -These should land before public adapter APIs are committed. +### 0.7 — preserve and prove authority -### Milestone B — Selection and workload identity - -After candidate eligibility and workload identity: - -6. **Policy simulation core using authoritative selection/policy evaluator**; -7. stable decision/reason normalization suitable for execution, simulation, and tests. - -### Milestone C — Projection layer - -Add projection support for: - -- enforcement mode; -- external runtime identity; -- simulation records/summaries where persisted; -- evidence provenance. +1. Finish 0.7.1 identity/authority without cross-runtime scope churn. +2. In 0.7.2, keep policy/authorization evaluation deterministic and side-effect-free. +3. In 0.7.3, establish reusable decision identity/reason semantics rather than provider-selection-only representations. +4. Run **XR1 — Spring AI external-runtime authority proof** after 0.7.3 semantics exist and before 0.7.4 evidence/projection contracts are frozen. +5. In 0.7.4, finalize runtime/integration identity plus enforcement/evidence provenance informed by XR1. +6. In 0.7.5–0.7.8, preserve provenance through reconstruction, control, cancellation, and Dashboard explanation without adding a second policy engine. -### Milestone D — Dashboard 2.0 +### 0.8 — productize governance DX -Add: +After 0.7 proves the authority boundary: -- local governance debugger affordances; -- "why" views based on structured decisions; -- simulation/decision-preview UI; -- explicit governance coverage/enforcement-mode display. +- policy simulation / decision preview and diff; +- governance contract-testing module; +- local governance debugger; +- adapter SDK/SPI plus compatibility TCK; +- additional adapters based on adoption value; +- capability provenance and registration/discovery/exposure semantics; +- tool effect/reversibility metadata; +- compensation execution only if concrete scenarios justify it. -### Milestone F — Expansion +### Deferred beyond the immediate 0.8 core -Add: - -- governance contract testing module; -- first external-runtime adapter proof; -- simulation diff mode if not already delivered. - -### Deferred / post-0.7.0 - -- broad framework adapter matrix; -- tool compensation execution; -- external-runtime discovery across the enterprise; -- remote agent marketplace/inventory connectors. +- universal adapter coverage for every AI framework; +- enterprise-wide external-runtime discovery; +- remote agent marketplace/inventory connectors; +- generic distributed transaction/saga engine. --- - ## 10. Proposed module boundaries Names are provisional. @@ -1350,47 +1325,50 @@ Add to Section 9 of the main roadmap. - UI/evidence language never upgrades OBSERVED into ENFORCED. - External adapter identity is authenticated/registered according to the declared threat model for authoritative mode. -### 13.2 Simulation gates +### 13.2 0.8 simulation gates - Simulation performs zero external side effects. - Simulation and execution share the authoritative evaluator. - Simulation results are type-distinct from executable authorization/evidence of enforcement. - Deterministic parity tests are green. -### 13.3 Governance-test gates +### 13.3 0.8 governance-test gates -If the testing module ships in 0.7.0: +When the testing module ships: - it runs offline; - it cannot invoke real tools/providers by default; - failures expose structured reason paths; - production evaluator code is exercised directly. -### 13.4 Developer UX gate +### 13.4 0.8 developer UX gate -For the reference workflow, a developer can answer "why was this denied/approved/routed?" from structured local/control-plane output without reverse-engineering logs or frontend policy code. +A developer can answer "why was this denied/approved/routed?" from structured local/control-plane output without reverse-engineering logs or frontend policy code. --- ## 14. Success-metric amendments -Add product/architecture metrics: +Split metrics by release ownership: + +### 0.7 metrics + +| Metric | Target | +|---|---:| +| XR1 denied operations executed at the declared authoritative boundary | 0 | +| XR1 approval-required operations executed before approval | 0 | +| External-reference evidence records that preserve enforcement provenance | 100% | +| OBSERVED/INSTRUMENTED facts presented as AUTHORITATIVE | 0 | +| Generic framework-specific concepts leaked into core governance semantics | 0 known intentional violations | + +### 0.8 metrics | Metric | Target | |---|---:| | Simulation/runtime deterministic decision parity | 100% for declared deterministic fixtures | | Simulation external side effects | 0 | -| External workloads with explicit enforcement mode | 100% | -| Evidence records that preserve enforcement provenance | 100% | | Governance test assertions using production evaluator | 100% | -| OBSERVED integrations presented as AUTHORITATIVE | 0 | -| Generic framework-specific concepts leaked into core governance model | 0 known intentional violations | - -Longer-term adoption metric: - -> At least one non-TramAI-authored JVM workload can participate in TramAI governance without rewriting its agent/workflow into a TramAI-native abstraction. - -This may be a 0.7.x proof rather than a hard 0.7.0 GA gate if implementation scope becomes excessive. +| Supported external adapters with explicit enforcement mode | 100% | --- @@ -1438,7 +1416,7 @@ The framework landscape suggests the following product discipline. ## 17. Architecture decision summary -After this amendment, the 0.7.0 architecture should satisfy the following statement: +After the 0.7/0.8 split recorded by the authoritative roadmaps, the architecture should satisfy the following statement: > TramAI may execute a workload itself, or it may govern an execution boundary owned by another JVM AI runtime. In either case, authoritative TramAI governance semantics remain typed, deterministic, explainable, headless, testable, and evidence-producing. The control plane displays those semantics without becoming a second policy engine. Where TramAI cannot guarantee enforcement, it says so explicitly. diff --git a/docs/roadmap/0.7.0/CHECKPOINT-0.7-XR1-EXTERNAL-RUNTIME-AUTHORITY-PROOF.md b/docs/roadmap/0.7.0/CHECKPOINT-0.7-XR1-EXTERNAL-RUNTIME-AUTHORITY-PROOF.md new file mode 100644 index 000000000..a03208dfe --- /dev/null +++ b/docs/roadmap/0.7.0/CHECKPOINT-0.7-XR1-EXTERNAL-RUNTIME-AUTHORITY-PROOF.md @@ -0,0 +1,92 @@ +# Checkpoint 0.7-XR1 — External Runtime Authority Proof + +**Status:** ⚪ Planned +**Placement:** after 0.7.3 decision semantics; before 0.7.4 evidence/projection contracts are frozen +**Reference runtime:** Spring AI +**Change class:** architecture/release proof + +## Executive decision + +Prove that TramAI can authoritatively govern a declared execution boundary initiated by a **non-TramAI-authored JVM AI workload** without requiring the workload to be rewritten as a TramAI workflow and without introducing a second policy model. + +This is a narrow architecture proof. It is not a productionized framework-adapter programme. + +## Required flow + +```text +Spring AI workload + ↓ +tool/action intent + ↓ +TramAI workload + configuration + run correlation + ↓ +authoritative TramAI governance evaluator + ↓ +ALLOW / DENY / REQUIRE_APPROVAL + ↓ +execute / reject / governed suspension + ↓ +correlated outcome + evidence +``` + +The exact Spring AI integration mechanism is implementation-specific and may remain experimental. + +## Core invariants + +```text +external runtime != governance authority +governed workload != TramAI-authored workflow +DENY => no execution at the declared boundary +REQUIRE_APPROVAL => no execution before authoritative approval +adapter failure in authoritative mode => no silent fail-open +observed != enforced +projection/query state cannot authorize execution +``` + +## Required proof + +1. **ALLOW** — an allowed action executes exactly through the declared governed boundary and the outcome correlates to the TramAI decision. +2. **DENY** — a denied action does not execute. +3. **REQUIRE_APPROVAL** — the action cannot execute before approval; after valid approval the continuation preserves workload/run/decision identity. +4. **Identity continuity** — workload, configuration/version, run, policy/decision and correlation identity survive the external-runtime boundary. +5. **Failure semantics** — loss/unavailability of the governance call does not silently become permission where the integration declares authoritative enforcement. +6. **No second policy model** — Spring-specific code translates execution intent but does not recreate TramAI authorization or approval semantics. +7. **Evidence provenance** — emitted evidence identifies the external runtime/integration and represents only the enforcement strength TramAI can prove. +8. **No projection bypass** — the adapter cannot authorize by writing directly to control-plane read models, evidence stores or UI state. + +## Enforcement-strength requirement + +The reference proof must be **authoritative at the specific declared boundary**: TramAI's denial must be able to prevent that operation. + +0.7 may introduce an internal/preview representation capable of distinguishing concepts equivalent to: + +```text +AUTHORITATIVE +INSTRUMENTED +OBSERVED +IMPORTED +``` + +Exact names and public API stability are deferred to the 0.7.4 evidence/projection work. + +The integration must never imply that governing one Spring AI boundary proves every possible execution path in the host application is governed. + +## Non-goals + +- production-quality Spring Boot starter or five-minute adoption flow; +- broad Spring AI feature coverage; +- Koog, LangChain4j, Embabel, ADK or other adapter implementation; +- stable public adapter SPI; +- automatic framework discovery; +- policy simulation/decision preview; +- governance contract-testing SDK; +- Dashboard-specific policy behavior; +- MCP/A2A productization. + +Those belong to later roadmap work unless a narrow seam is required to complete this proof safely. + +## Exit + +XR1 is complete when a non-TramAI-authored Spring AI workload demonstrates the same authoritative TramAI governance meaning used by native execution, and the findings are sufficient for 0.7.4 to finalize evidence authority/provenance without assuming TramAI owns the agent runtime. + +If the proof requires a second policy model or reveals that core workload/decision semantics are inherently TramAI-workflow-specific, stop and report the architectural mismatch before 0.7.4 contracts are frozen. diff --git a/docs/roadmap/0.7.0/EPIC-0.7.2-POLICY-TRUST-ZONES.md b/docs/roadmap/0.7.0/EPIC-0.7.2-POLICY-TRUST-ZONES.md index 560286f1a..1abc1d5d8 100644 --- a/docs/roadmap/0.7.0/EPIC-0.7.2-POLICY-TRUST-ZONES.md +++ b/docs/roadmap/0.7.0/EPIC-0.7.2-POLICY-TRUST-ZONES.md @@ -6,7 +6,7 @@ ## Executive decision -Resolve classification, concrete provider-deployment trust topology, effective policy, and the provider-bound data-release decision before a model invocation can cross a trust boundary. Authorization answers whether a provider may be used; the provider-input release boundary separately answers what exact representation of the governed input that provider may receive. +Resolve classification, concrete provider-deployment trust topology, effective policy, and the provider-bound data-release decision before a model invocation can cross a trust boundary. Authorization answers whether a provider may be used; the provider-input release boundary separately answers what exact representation of the governed input that provider may receive. The governance decision path must remain deterministic and side-effect-free so later execution, external-runtime integration, simulation, and testing can reuse one meaning rather than invent parallel policy engines. ## Scope @@ -24,6 +24,7 @@ Resolve classification, concrete provider-deployment trust topology, effective p - fail closed before invocation when required input minimization/inspection cannot be completed; - emit safe typed evidence for provider-input release/minimization without persisting raw matched sensitive values; - stable safe reason paths for denial/constraint decisions; +- a side-effect-free deterministic evaluation boundary for classification/policy/release meaning; - typed evidence sufficient for downstream projection/reconstruction. ## Non-goals @@ -52,6 +53,8 @@ providerBoundInput = projection(canonicalInput, selectedDeployment, effectivePol providerBoundInput transformation never mutates canonicalInput fallback to a different deployment => derive a new providerBoundInput required minimization/inspection failure => no provider invocation +same authoritative facts + same effective policy => same governance decision +policy evaluation itself performs no provider/tool/network side effects safe evidence never contains raw matched sensitive values ``` @@ -65,7 +68,7 @@ The provider-input release decision is distinct from provider authorization. A p | 0.7.2b | Provider deployment + named zone contract | Introduce/normalize deployment identity and named-zone/category association | | 0.7.2c | Classification-before-exposure integration | Move/guard orchestration ordering so required classification precedes eligibility/exposure | | 0.7.2d | Provider-input data-release/minimization contract | Define canonical input vs provider-bound projection, typed release outcomes, fail-closed transformation semantics, provider-specific recomputation, and safe evidence | -| 0.7.2e | Restrictive policy composition | Deterministic org/environment/workload intersection with no widening path; provider-input release obligations derive from the same effective policy authority | +| 0.7.2e | Restrictive policy composition | Deterministic org/environment/workload intersection with no widening path; provider-input release obligations derive from the same effective policy authority; evaluation remains side-effect-free | | 0.7.2f | Missing/unknown/failure semantics | Fail closed where classification/topology or required provider-input minimization/inspection is unavailable | | 0.7.2g | Reason/evidence model | Stable safe reasons for classification/trust/policy/data-release outcomes without raw sensitive values | | 0.7.2h | Adversarial/TCK/mutation proof | Prove ordering, no downgrade, no brand trust, no widening, no pre-release invocation, no cross-provider projection reuse, and no fail-open sanitizer path | @@ -84,10 +87,12 @@ The provider-input release decision is distinct from provider authorization. A p - Lower scope cannot authorize something denied above it. - Missing required classification/topology cannot silently become permissive. - Decisions expose safe stable reasons usable by 0.7.3/0.7.4. +- Equivalent authoritative facts under the same policy/configuration produce the same deterministic decision for the supported profile. +- Decision evaluation can be exercised with provider/tool/network traps and produces no external side effects. ## Adversarial proof -Reject implementations that classify after exposure, downgrade an explicit strong class, infer EU/local trust from vendor name, union policies instead of intersecting them, treat unknown as allow, invoke the provider before the release/minimization decision, mutate canonical input in place, reuse an OpenAI-authorized/minimized projection after fallback to a different provider deployment, expose raw matched values in evidence, or pass raw input through when required DLP/minimization fails. +Reject implementations that classify after exposure, downgrade an explicit strong class, infer EU/local trust from vendor name, union policies instead of intersecting them, treat unknown as allow, invoke the provider before the release/minimization decision, mutate canonical input in place, reuse an OpenAI-authorized/minimized projection after fallback to a different provider deployment, expose raw matched values in evidence, pass raw input through when required DLP/minimization fails, or make policy evaluation itself depend on an external provider/tool/network side effect. ## Mutation expectations diff --git a/docs/roadmap/0.7.0/EPIC-0.7.3-AUTHORIZED-SELECTION.md b/docs/roadmap/0.7.0/EPIC-0.7.3-AUTHORIZED-SELECTION.md index eb58d34e8..d4feed375 100644 --- a/docs/roadmap/0.7.0/EPIC-0.7.3-AUTHORIZED-SELECTION.md +++ b/docs/roadmap/0.7.0/EPIC-0.7.3-AUTHORIZED-SELECTION.md @@ -32,6 +32,7 @@ optimization signals can rank but cannot authorize - selection/non-selection reason paths; - constrained fallback/retry; - decision/configuration identity/digest where required for evidence; +- reusable governance-decision identity/envelope semantics that bind workload/run/policy/authority/reasons without becoming provider-selection-specific; - safe historical decision evidence. ## Non-goals @@ -39,7 +40,8 @@ optimization signals can rank but cannot authorize - rich adaptive routing; - machine-learned routing; - FinOps optimization; -- broad cost/quality strategy productization. +- broad cost/quality strategy productization; +- productionized external-runtime adapter SDKs or a broad framework-integration matrix. ## Tasks @@ -50,7 +52,7 @@ optimization signals can rank but cannot authorize | 0.7.3c | Authorized-set derivation | Compute governance-authorized candidates from 0.7.2 contracts | | 0.7.3d | Viability stage | Apply runtime constraints only after authorization | | 0.7.3e | Selection/fallback fencing | Ensure selection/retry/fallback cannot escape viable authorized set | -| 0.7.3f | Decision identity/evidence | Persist enough context to explain historical selection safely | +| 0.7.3f | Decision identity/evidence | Persist enough workload/run/policy/decision/authority context to explain historical selection safely and to support the XR1 external-runtime authority proof without inventing a second decision model | | 0.7.3g | Adversarial/mutation/provider proof | Prove ineligible routes never become selected via fallback/preference | | 0.7.3h | Integration/docs | Final API/architecture docs and Epic acceptance | @@ -60,6 +62,13 @@ optimization signals can rank but cannot authorize - Policy-ineligible candidates cannot become selected through retry/fallback/preference. - Rejected/non-selected candidates expose structured safe reasons. - Historical evidence identifies the relevant workload/config/policy/routing context. +- Decision identity and structured reasons are not coupled to TramAI owning the workflow runtime or to provider selection as the only future decision family. + +## Post-Epic release checkpoint + +After 0.7.3 decision semantics are available, run [XR1 — External Runtime Authority Proof](CHECKPOINT-0.7-XR1-EXTERNAL-RUNTIME-AUTHORITY-PROOF.md) using Spring AI as the reference non-TramAI runtime. XR1 must complete before 0.7.4 evidence/projection contracts are considered frozen. + +XR1 is a release architecture proof, not an expansion of this Epic into framework-adapter productization. ## Adversarial proof diff --git a/docs/roadmap/0.7.0/EPIC-0.7.4-EVIDENCE-PROJECTION.md b/docs/roadmap/0.7.0/EPIC-0.7.4-EVIDENCE-PROJECTION.md index c8da5729d..fd6b69c43 100644 --- a/docs/roadmap/0.7.0/EPIC-0.7.4-EVIDENCE-PROJECTION.md +++ b/docs/roadmap/0.7.0/EPIC-0.7.4-EVIDENCE-PROJECTION.md @@ -2,7 +2,7 @@ **Branch:** `epic/0.7.4-evidence-projection` **Status:** ⚪ Planned -**Dependencies:** 0.7.1 HARD; 0.7.2/0.7.3 SOFT +**Dependencies:** 0.7.1 HARD; 0.7.2/0.7.3 SOFT; XR1 required before evidence/projection contracts are frozen ## Executive decision @@ -11,7 +11,7 @@ Project authoritative runtime truth into a stable operational read model without ## Architecture ```text -runtime authority → typed evidence → projection/read model → query API → clients +runtime authority / governed external boundary → typed evidence → projection/read model → query API → clients ``` OTEL and best-effort telemetry may mirror facts but remain non-authoritative. @@ -20,6 +20,8 @@ OTEL and best-effort telemetry may mirror facts but remain non-authoritative. - typed governance evidence/events; - workload/run/config/classification/policy/routing/approval/control correlation; +- runtime/framework/integration identity where relevant to evidence interpretation; +- explicit evidence source, enforcement strength, and provenance sufficient to distinguish enforced, instrumented, observed, and imported facts; - idempotent projection application; - ordering/version handling; - explicit projection lag/consistency/source authority; @@ -40,11 +42,11 @@ OTEL and best-effort telemetry may mirror facts but remain non-authoritative. | ID | Candidate | Required result | |---|---|---| | 0.7.4a | Evidence baseline audit | Inventory authoritative events/stores, audit evidence and telemetry gaps | -| 0.7.4b | Governance evidence schema | Typed/versioned evidence families with identity and source authority | +| 0.7.4b | Governance evidence schema | Typed/versioned evidence families with identity, source authority, runtime/integration context where relevant, and explicit enforcement/evidence provenance | | 0.7.4c | Projection contract | Idempotency, ordering/version, lag and rebuild semantics | | 0.7.4d | Materialized read model | Durable/queryable operational projection without mutation authority | | 0.7.4e | Query API | Stable headless workload/run/decision/control-state query contracts | -| 0.7.4f | Safe exposure/OTEL mapping | Protected-payload defaults and non-authoritative telemetry distinction | +| 0.7.4f | Safe exposure/OTEL mapping | Protected-payload defaults; observed/instrumented/imported evidence remains distinguishable from authoritative enforcement; OTEL never upgrades telemetry into proof of prevention | | 0.7.4g | Adversarial/rebuild/mutation proof | Duplicate/reorder/stale/missing-source and privacy discriminators | | 0.7.4h | Integration/docs | Evidence schema/query docs and Epic acceptance | @@ -55,6 +57,8 @@ projection cannot create or widen authority same authoritative event applied twice => same projection as once projection lag is never presented as stronger authority than source missing evidence != inferred success +observed telemetry != proof of enforcement +integration/client metadata cannot self-upgrade enforcement strength protected payloads are excluded by default ``` @@ -65,7 +69,9 @@ protected payloads are excluded by default - Duplicate/reordered evidence obeys explicit semantics. - Projection lag/source authority is observable. - Query/telemetry defaults do not leak protected payloads. +- The XR1 Spring AI reference path can be projected without pretending TramAI authored the workload. +- Clients can distinguish a TramAI-enforced boundary from instrumented, observed, or imported evidence. ## Adversarial proof -Reject projection-side policy decisions, duplicate evidence changing final state incorrectly, stale event overwriting newer version, unavailable source reported as PASS/current, and payload leakage through generic DTO/telemetry. +Reject projection-side policy decisions, duplicate evidence changing final state incorrectly, stale event overwriting newer version, unavailable source reported as PASS/current, payload leakage through generic DTO/telemetry, observed telemetry represented as authoritative prevention, client-supplied enforcement strength accepted without authoritative validation, and external-runtime evidence projected as though TramAI authored or governed boundaries it did not control. diff --git a/docs/roadmap/0.7.0/EPIC-0.7.5-TIMELINE-RECONSTRUCTION.md b/docs/roadmap/0.7.0/EPIC-0.7.5-TIMELINE-RECONSTRUCTION.md index 8020ddc5b..158ab6d2c 100644 --- a/docs/roadmap/0.7.0/EPIC-0.7.5-TIMELINE-RECONSTRUCTION.md +++ b/docs/roadmap/0.7.0/EPIC-0.7.5-TIMELINE-RECONSTRUCTION.md @@ -15,6 +15,7 @@ reconstruction != re-execution missing historical evidence remains missing current configuration is never silently substituted for historical configuration best-effort telemetry remains distinguishable from authoritative evidence +reconstruction preserves historical enforcement/evidence provenance rather than upgrading it ``` ## Scope @@ -22,6 +23,7 @@ best-effort telemetry remains distinguishable from authoritative evidence - semantic run event model; - deterministic ordering/grouping rules; - authoritative vs best-effort/missing markers; +- preservation of evidence source, enforcement strength, and runtime/integration provenance from 0.7.4; - reconstruction input contract and completeness model; - historical configuration/policy/topology identity resolution; - side-effect-free reconstruction API/result; @@ -38,7 +40,7 @@ best-effort telemetry remains distinguishable from authoritative evidence | ID | Candidate | Required result | |---|---|---| | 0.7.5a | Timeline/reconstruction audit | Characterize available evidence and missing historical identities | -| 0.7.5b | Semantic timeline contract | Typed governance transitions and authority/source markers | +| 0.7.5b | Semantic timeline contract | Typed governance transitions plus authority/source/enforcement-provenance markers that remain truthful for native and external-runtime evidence | | 0.7.5c | Timeline projection/query | Deterministic semantic ordering from 0.7.4 evidence | | 0.7.5d | Reconstruction contract | Inputs, completeness states, historical identity requirements | | 0.7.5e | Side-effect-free reconstructor | Produce historical governed narrative/state without external invocation | @@ -52,6 +54,7 @@ best-effort telemetry remains distinguishable from authoritative evidence - Missing evidence is visible. - Reconstruction causes zero provider/tool/approval/network/workflow side effects. - Historical configuration is used when available; absence is explicit. +- A reconstructed external-runtime event retains whether it was authoritatively enforced, instrumented, observed, or imported according to the evidence available at execution time. ## Adversarial proof diff --git a/docs/roadmap/0.7.0/EPIC-0.7.6-AUTH-RUNTIME-CONTROL.md b/docs/roadmap/0.7.0/EPIC-0.7.6-AUTH-RUNTIME-CONTROL.md index 8fd99d6e8..4542abfae 100644 --- a/docs/roadmap/0.7.0/EPIC-0.7.6-AUTH-RUNTIME-CONTROL.md +++ b/docs/roadmap/0.7.0/EPIC-0.7.6-AUTH-RUNTIME-CONTROL.md @@ -12,7 +12,7 @@ Expose privileged control-plane commands only through an identity-provider-neutr - generic OIDC/Spring Security integration boundary; - authenticated control-plane principal; -- capability-based server-side authorization; +- operator/control-plane capability-based server-side authorization, explicitly distinct from runtime capabilities such as tools, MCP operations, remote agents, models, or network destinations; - command/target/version/precondition contracts; - typed lifecycle/control commands for supported P0 operations; - actor/reason/previous/resulting-state/evidence correlation; @@ -31,7 +31,7 @@ Expose privileged control-plane commands only through an identity-provider-neutr | ID | Candidate | Required result | |---|---|---| | 0.7.6a | Security/control baseline audit | Map current auth hooks, lifecycle APIs, stores and unsafe direct mutations | -| 0.7.6b | Principal + capability contract | IdP-neutral authenticated identity and server-side capability model | +| 0.7.6b | Principal + operator capability contract | IdP-neutral authenticated identity and server-side operator/control-plane capability model; terminology must not collapse operator authority with runtime capability governance | | 0.7.6c | OIDC/Spring boundary | Generic adapter/integration seam without vendor authority semantics in core | | 0.7.6d | Typed control commands | Target identity, expected version/precondition, reason and supported lifecycle operations | | 0.7.6e | Runtime authorization path | Authenticate → authorize → validate → mutate authority; no bypass store path | @@ -46,6 +46,7 @@ UI visibility != authorization privileged mutation requires authenticated actor + server-side authorization stale command cannot silently overwrite newer authoritative state dashboard/client cannot directly mutate authoritative persistence +operator capability != runtime capability ``` ## Acceptance criteria @@ -54,6 +55,7 @@ dashboard/client cannot directly mutate authoritative persistence - Authorization is enforced server-side and is IdP-neutral at the governance boundary. - Successful controls are attributable and reconstructable. - Direct-store/client bypasses are absent from supported control paths. +- Operator authorization vocabulary is unambiguous and does not become the canonical representation for runtime tool/MCP/model capabilities. ## Adversarial proof diff --git a/docs/roadmap/0.7.0/EPIC-0.7.7-SUSPENDED-RUN-CANCELLATION.md b/docs/roadmap/0.7.0/EPIC-0.7.7-SUSPENDED-RUN-CANCELLATION.md index acc8d7791..9f8849db2 100644 --- a/docs/roadmap/0.7.0/EPIC-0.7.7-SUSPENDED-RUN-CANCELLATION.md +++ b/docs/roadmap/0.7.0/EPIC-0.7.7-SUSPENDED-RUN-CANCELLATION.md @@ -12,6 +12,7 @@ Make cancellation of a persisted suspended run an authoritative terminal lifecyc ```text cancelled(run) => no subsequent authoritative execution(run) +cancelled(run) != already-produced external effects compensated ``` Once cancellation wins, no model, tool, approval continuation, network action, or workflow side effect may resume that run. @@ -26,13 +27,16 @@ Once cancellation wins, no model, tool, approval continuation, network action, o - restart survival; - idempotent repeated cancellation; - terminal evidence/timeline/reconstruction support; -- cleanup behavior that cannot erase authoritative cancellation semantics. +- cleanup behavior that cannot erase authoritative cancellation semantics; +- evidence semantics that distinguish fencing future execution from compensating or reversing side effects that already occurred. ## Non-goals - redesigning all approval lifetime/replacement semantics; - generic distributed workflow engine rewrite; -- application-emulated cancellation flags. +- application-emulated cancellation flags; +- generic saga/compensation engine; +- claiming that terminal cancellation automatically reverses an email, payment, deployment, external API mutation, or other already-completed side effect. ## Tasks @@ -55,6 +59,7 @@ Once cancellation wins, no model, tool, approval continuation, network action, o - Repeated cancellation is idempotent. - Late approval cannot authorize continuation. - Cancellation remains visible to timeline/reconstruction. +- Timeline/evidence never represents cancellation itself as proof that external side effects completed before cancellation were reversed or compensated. ## Adversarial proof @@ -68,7 +73,7 @@ Required scenarios: 6. cleanup/checkpoint removal after cancellation; 7. stale worker attempts continuation after cancellation. -Any model/tool/network/workflow side effect after authoritative cancellation is a release blocker. +Any model/tool/network/workflow side effect after authoritative cancellation is a release blocker. A run cancelled after an earlier external side effect must also remain reconstructable without implying that cancellation compensated that already-completed effect. ## Mutation expectations diff --git a/docs/roadmap/0.7.0/EPIC-0.7.8-DASHBOARD-INTEGRATION.md b/docs/roadmap/0.7.0/EPIC-0.7.8-DASHBOARD-INTEGRATION.md index 73e51a271..96412d05c 100644 --- a/docs/roadmap/0.7.0/EPIC-0.7.8-DASHBOARD-INTEGRATION.md +++ b/docs/roadmap/0.7.0/EPIC-0.7.8-DASHBOARD-INTEGRATION.md @@ -12,6 +12,7 @@ Deliver Dashboard 2.0 as a first-party, replaceable client of the headless contr - workload inventory/detail; - identity/version/owner/purpose/environment/lifecycle posture; +- runtime/framework identity plus integration/enforcement provenance where relevant, without implying that TramAI authored external workloads; - effective classification/policy/trust posture; - provider/model authorization/selection reasons; - semantic run timeline; @@ -35,7 +36,7 @@ Deliver Dashboard 2.0 as a first-party, replaceable client of the headless contr |---|---|---| | 0.7.8a | Dashboard baseline/API inventory | Remove/avoid hidden authority assumptions; map required headless APIs | | 0.7.8b | Control-plane client layer | Typed client models for workload/run/decision/timeline/control/reconstruction | -| 0.7.8c | Workload/detail surface | P0 governance posture and recent operational state | +| 0.7.8c | Workload/detail surface | P0 governance posture, recent operational state, runtime/framework identity, and truthful integration/enforcement provenance | | 0.7.8d | Semantic run/timeline surface | Render authoritative/best-effort/missing distinctions | | 0.7.8e | Approval/control surface | Only server-authorized actions; stale/denied states handled safely | | 0.7.8f | Reconstruction/evidence surface | Expose availability/completeness without re-execution | @@ -56,6 +57,7 @@ protected payloads remain hidden by default - Full P0 loop is usable headlessly and through Dashboard 2.0. - UI displays structured reasons/evidence from control-plane contracts rather than recreating decisions. +- The XR1 reference external workload can display its runtime separately from TramAI governance authority and cannot be visually upgraded from observed/instrumented evidence to authoritative enforcement. - Authorized controls flow through typed server APIs. - Reference sensitive-input scenario proves classification → policy → authorized route → evidence → observation/control → reconstruction. - Persisted suspended-run scenario proves authoritative cancellation and no-reactivation. @@ -63,4 +65,4 @@ protected payloads remain hidden by default ## Adversarial proof -Reject hidden frontend authorization, direct persistence access, reconstructed policy logic in TypeScript/UI, stale controls without server rejection, protected-payload default exposure, and reconstruction implemented as rerun/retry. +Reject hidden frontend authorization, direct persistence access, reconstructed policy logic in TypeScript/UI, stale controls without server rejection, protected-payload default exposure, reconstruction implemented as rerun/retry, or UI language that represents observed/instrumented external-runtime evidence as authoritative TramAI enforcement. diff --git a/docs/roadmap/0.7.0/README.md b/docs/roadmap/0.7.0/README.md index e23cc62e7..b178f2346 100644 --- a/docs/roadmap/0.7.0/README.md +++ b/docs/roadmap/0.7.0/README.md @@ -63,6 +63,7 @@ Status values: `⚪ Planned` · `🟡 Active` · `🟣 Review` · `✅ Complete` ### Wave B — Authoritative decisions - 0.7.3 Authorized provider/model selection +- [XR1 External-runtime authority proof](CHECKPOINT-0.7-XR1-EXTERNAL-RUNTIME-AUTHORITY-PROOF.md) — Spring AI reference integration; required before 0.7.4 evidence/projection contracts are frozen ### Wave C — Evidence & observability - 0.7.4 Evidence/projection/query API @@ -87,7 +88,11 @@ providerBoundInput = projection(canonicalInput, selectedDeployment, effectivePol provider-specific transformation never mutates canonicalInput provider-changing fallback => recompute providerBoundInput required minimization/inspection failure => no provider invocation +governed workload != TramAI-authored workflow +same authoritative facts + same policy/configuration => same governance decision +observed != enforced cancelled(run) => no subsequent authoritative execution(run) +cancelled(run) != already-produced external effects compensated reconstruction != re-execution Dashboard != policy authority ``` @@ -102,7 +107,8 @@ Dashboard != policy authority 4. the reference control-plane scenario, provider-input release/minimization scenario, and persisted-cancellation scenario pass end to end; 5. no deferred 0.8/0.9/0.10 scope has leaked into the release without an explicit release-cut change; 6. `release/0.7.0 → master` is a certification/promotion PR, not a first-time integration event; -7. the 0.7.1 integration-closure gates are met — API migration hashes bound to the frozen head, the release-sovereign population pin certified from measurement, and analyzer/build-logic changes kept out of the runtime promotion transition — and meeting them did **not** involve weakening `analyzer-runtime-separation` ([TASK-0.7.1i](TASK-0.7.1i-INTEGRATION-CLOSURE.md)). +7. the 0.7.1 integration-closure gates are met — API migration hashes bound to the frozen head, the release-sovereign population pin certified from measurement, and analyzer/build-logic changes kept out of the runtime promotion transition — and meeting them did **not** involve weakening `analyzer-runtime-separation` ([TASK-0.7.1i](TASK-0.7.1i-INTEGRATION-CLOSURE.md)); +8. the [XR1 external-runtime authority proof](CHECKPOINT-0.7-XR1-EXTERNAL-RUNTIME-AUTHORITY-PROOF.md) proves that one non-TramAI-authored JVM workload can cross an authoritative TramAI governance boundary without a second policy model or an overstated enforcement claim. ## Execution documents @@ -110,4 +116,5 @@ Dashboard != policy authority - [`DEPENDENCIES.md`](DEPENDENCIES.md) - [`QUALITY-GATES.md`](QUALITY-GATES.md) - [`SPEC-TEMPLATE.md`](SPEC-TEMPLATE.md) +- [`CHECKPOINT-0.7-XR1-EXTERNAL-RUNTIME-AUTHORITY-PROOF.md`](CHECKPOINT-0.7-XR1-EXTERNAL-RUNTIME-AUTHORITY-PROOF.md) - Epic specs linked in the board above.