TramAI - governed AI workflows for Java and Kotlin

Migration Guide

This page is the index of upgrade notes across TramAI release lines. For the current release, use the dedicated guide: Migrating to TramAI 0.6.0, which covers the move from 0.5.0 in full.

If you are on an older line, apply the sections below in order until you reach 0.5.0, then follow the 0.6.0 guide.

0.5.0 → 0.6.0

Five changes can require an edit. They are documented in detail in Migrating to TramAI 0.6.0:

  1. One Spring Boot starter coordinate — dev.tramai:tramai-spring-boot-starter replaces the old sovereign starter artifact.
  2. Runtime selection via tramai.profile (standard or sovereign), with sovereignty allowlists under tramai.sovereign.* and the old enable flag removed.
  3. JDBC store failures now surface as IllegalStateException instead of java.sql.SQLException; cancellation and domain exceptions propagate unwrapped.
  4. Multimodal image retrieval validates schemes, hosts, and resolved addresses against outbound SSRF rules.
  5. @ExperimentalTramaiInternalApi and @ExperimentalProviderTransportApi declarations are outside the stable compatibility promise.

Everything else in 0.6.0 is additive or internal. See the 0.6.0 changelog for the release description.

0.4.0 → 0.5.0

0.5.0 was the post-sovereignty maturation release. No foundation API was removed, but three behaviors changed in ways that can affect a running application:

  • JavaBean structured-output schemas. Java DTOs with conventional bean accessors now contribute real properties, required fields, nested types, collection item schemas, and TramAI field annotations to generated contracts, and receive matching validation. Previously Java POJO properties were invisible to Kotlin reflection and produced empty schemas. Java records and arbitrary immutable POJOs remain unsupported.
  • Validation coverage. @AiRange and @AiMinItems now participate in schema generation and validation, so output that previously passed can now fail and trigger the repair loop.
  • Runtime evidence layout. Tool enforcement events (BEFORE_TOOL_EXPOSURE, BEFORE_TOOL_EXECUTION, BEFORE_TOOL_RESULT_REINJECTION) moved into a dedicated tool.permission evidence family written to runtime-evidence/tool-permissions.jsonl, separated from policy.decision. Any bundle consumer that assumed a single policy file must be updated.

Also new in 0.5.0: the workflow API stability boundary, the governed workflow quickstart and testing guides, the approval ergonomics guide and failure taxonomy, runtime evidence exporters for policy, approval, and provider routing, the tool permission model, and the examples governed-workflow, approval-resume, and tool-governance.

Preview APIs in 0.5.0 include the approval control plane REST endpoints, the reviewer UI (disabled by default), the runtime evidence exporters, and the tool governance APIs. Deferred: a stable 1.0 public API, key rotation, a production-grade reviewer UI with enterprise IAM, a governed MCP connector, and a compliance mapping framework.

0.3.1 → 0.4.0

0.4.0 added the sovereignty layer around the existing runtime. It was an additive release on the public typed-service surface:

  • New modules: tramai-security, tramai-sovereign, tramai-persistence-file, tramai-persistence-jdbc, and the Spring Boot sovereign starters — including the standalone tramai-spring-boot-starter-sovereign, which 0.6.0 later replaced with tramai-spring-boot-starter plus tramai.profile.
  • Deny-by-default policy engine with explicit model, provider, tool, and permission allowlists; provider trust zones and classification-aware routing.
  • Approval gateway with token-bound resume, hash-chained audit, and deterministic evidence packs.
  • Local model artifact verification and an enforceable OFFLINE deployment mode.

If you did not adopt the sovereign runtime, your only change was the version bump. The typed-service, provider, structured-output, orchestration, and observability APIs remained the stable baseline. Sovereign and security APIs were implemented and documented but preview/evolving.

0.3.0 → 0.3.1

  • Bug fixes and API stabilization.
  • New optional modules: tramai-gemini, tramai-deepseek, tramai-bedrock, tramai-azure-openai.

0.2.0 → 0.3.0

  • tramai-security module added. Sovereign profiles available as experimental.
  • ToolCall.arguments renamed to argumentsJson.
  • Tool exposure became explicit-only: @Operation(tools = ["tool1"]). An empty list exposes zero tools.

0.1.0 → 0.2.0

  • Tramai { ... } builder DSL added. The Java Tramai.builder() pattern still works.
  • Module coordinates unchanged.
  • @Operation(model = "...") became required. Previously optional models now need explicit declaration.

Stay on the Current Version

Align every TramAI dependency through the BOM rather than pinning module versions individually:

dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
}

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>dev.tramai</groupId>
      <artifactId>tramai-bom</artifactId>
      <version>0.6.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
Previous