0.5.0 — Governed AI Workflows for the JVM

0.5.0 is the post-sovereignty maturation release. Where 0.4.0 added the sovereign runtime, policy boundaries, approval gateway, and evidence packs, 0.5.0 made that surface usable by ordinary application teams: it drew explicit API stability boundaries, hardened structured output, added governed workflow examples and diagnostics, turned human approval into a documented lifecycle, exported runtime decisions as reviewable evidence, and wrote down the tool permission model.

No new runtime execution model was introduced. The release is about making the existing governed workflow surface predictable, testable, and documentable.

What Changed Since 0.4.0

API Stability Boundaries

The workflow-facing API is now classified explicitly rather than implied. The boundary document records, for each declaration, whether it is stable, preview, internal, or deferred, and defines which stability claims may and may not be made.

Stable / RC+

• @AiService and @Operation annotations
• The ModelProvider SPI and provider adapters
• The tramai-standalone and tramai-spring runtime entry points
• ApprovalGateway, ApprovalRequestResult, and SovereignWorkflowResult — the workflow-facing golden path
• Store and runtime SPIs

Preview

• ApprovalDecisionControlPlane and ApprovalResumeControlPlane
• ApprovalInboxQueryService
• The REST approval control plane and the reviewer UI (disabled by default)
• The Java approval workflow facade: ApprovalRequestResults, HumanApprovalDecisions
• Runtime evidence exporters and the evidence bundle writer

Internal

JDBC persistence stores and their auto-configuration, encrypted resume credential custody, the approved-continuation auto-resume worker, worker lease coordination, and the OpenTelemetry/Micrometer/Actuator worker modules.

Deferred

A stable 1.0 public API, key rotation, a production-grade reviewer UI with enterprise IAM, a governed MCP connector, a compliance mapping framework, and a production signing/attestation system. See API Stability for the current tier of each module.

A workflow lifecycle model accompanies the boundary, describing how a governed workflow moves from request through contract binding, policy evaluation, provider and tool execution, structured-output repair, approval gates, audit and persistence, to a typed result or failure.

Structured Output Hardening

JavaBean schema support

Java DTOs with conventional bean accessors now contribute real properties, required fields, nested types, collection item schemas, and TramAI field annotations to generated structured-output contracts, and receive matching structural and annotation validation. Previously Java POJO properties were invisible to Kotlin reflection and produced empty schemas. Kotlin schema behavior is unchanged.

Out of scope: Java records, arbitrary immutable POJOs, Java nullability inference, and custom validators.

Annotation-driven validation

Validation now includes @AiRange and @AiMinItems, which contribute to both schema generation and validation failure reporting.

Repair feedback loop

Parse and validation failures replay the failed assistant output, append repair feedback as a user message, retry structured-output generation within the retry budget, and throw a diagnostic StructuredOutputException when the budget is exhausted. Regression tests pin each step of that loop.

Contract lifecycle

The structured-output contract lifecycle is documented end to end — return type, schema generation, validator annotations, provider parsing, validation, repair, retry exhaustion, typed result — including the future design boundary for custom validators.

Workflow Ergonomics

Governed workflow quickstart

An end-to-end conceptual quickstart for governed workflows covering typed contracts, step composition, policy gates, optional approval gates, persistence and audit notes, and testing without real model calls.

Runnable minimal example

examples/governed-workflow is a deterministic claim-triage workflow with a policy gate, an approval gate, and local step finalization. It runs four scenarios — low-risk pass, restricted-claim policy rejection, high-risk approval rejection, approved high-risk pass — with no external model and no credentials.

Testing and troubleshooting

• A testing guide explaining deterministic fake services, success and failure path tests, gate rejection assertions, diagnostic step trails, and when to use MockAiProvider.
• A troubleshooting guide organized as symptom → likely cause → inspect → fix, covering policy and approval gate rejections, provider failures, structured-output failures, observer trail mismatches, and persistence/resume expectation mismatches.
• Failure diagnostics smoke tests proving gate rejections expose exception type, gate name, rejection reason, and completed/failed step trails.

Approval Gates

Ergonomics guide

When to request human approval, the full lifecycle (requested, approved, denied, expired, invalid actor, missing role), and six practical patterns: approval before a high-risk action, approval after AI classification, denial as a first-class outcome, expired approval windows, role-based constraints, and approval evidence notes.

Resume example

examples/approval-resume demonstrates low-value bypass, high-value suspension, exactly-once resume after approval, and no reimbursement after denial, using embedded PostgreSQL — no Docker required. It exercises ApprovalGateway, ApprovalDecisionControlPlane, ApprovalResumeControlPlane, and SovereignTramaiRuntime.

Decision evidence

Approved and denied decisions emit durable, structured audit outbox evidence: aggregate type, event key, operation, actor, workflow run ID, correlation ID, approval status and version, and reason digest and length. Raw decision comments are never stored directly — only a digest and length. Repeat decisions return typed AlreadyApproved / AlreadyDenied results without creating duplicate mutation evidence.

Failure taxonomy

A guide classifying approval outcomes carries forward to decision-control-plane outcomes (Approved, Denied, AlreadyApproved, AlreadyDenied, Expired, NotFound, Conflict) with terminal versus retryable classification, evidence semantics, and the workflow-facing / operator-facing boundary.

Runtime Evidence Export

0.5.0 made runtime decisions exportable as reviewable evidence in the sovereign bundle's runtime-evidence/ section, as JSONL:

RuntimeEvidenceBundleWriter groups records by event type and replaces the section atomically, so stale or partially written evidence cannot survive. Every record carries strict sha256:<64 lowercase hex> digests.

Sanitisation rules are enforced, not advisory: raw provider and model names are never exported (only digests), fallback reason codes are allowlisted, unsafe metadata is excluded, and invalid tool decisions are skipped rather than exported.

The bundle verifier parses every line, checks event/file correspondence and allowed decision kinds, validates digest format and ISO-8601 timestamps, enforces per-family metadata allowlists, rejects unknown files, and requires a files[] manifest entry for every actual bundle file. A lifecycle test proves finalize → verify → tamper → reject → restore → re-finalize.

No automatic evidence export and no Spring auto-configuration of the exporters are included.

Tool Governance

Tool permission model

The governed tool permission model defines tool trust classes (INTERNAL, APPLICATION, EXTERNAL_API, DATA_ACCESS, STATE_CHANGING, HIGH_IMPACT, MCP_REMOTE), risk classes, permission decisions (ALLOW, DENY, REQUIRE_APPROVAL, REDACT_RESULT, ALLOW_INTERNAL_ONLY), default approval-required categories, enforcement points, and audit/evidence expectations.

Dedicated evidence family

Tool enforcement events — BEFORE_TOOL_EXPOSURE, BEFORE_TOOL_EXECUTION, BEFORE_TOOL_RESULT_REINJECTION — are partitioned into the dedicated tool.permission evidence family, separate from generic policy.decision. The policy exporter now excludes tool events as a regression guard.

Denial proofs

Engine and sovereign integration tests prove fail-closed behavior: a tool denied at BEFORE_TOOL_EXECUTION never executes, the denial is audited before the exception propagates, no result reinjection or provider continuation occurs afterwards, audit failure blocks execution, and policy is reevaluated before retries. Denied tools never appear as executed work in audit or evidence, and raw tool arguments and secrets are absent from both.

MCP boundary

The MCP governance boundary document states what TramAI can and cannot prove about MCP tools, how they map into the MCP_REMOTE trust class, token and audience rules (no passthrough, audience validation, no raw token logging), and audit expectations. TramAI does not implement a governed MCP connector in this release — the document defines the boundary only.

Product Adoption

• Canonical product positioning: tagline, one-sentence description, thirty-second explanation, problem thesis, product category, target audiences, use cases, and six pillars tied to implemented capabilities, with explicit claim boundaries per audience.
• README reorganized around the positioning and a zero-credential governed-workflow first run.
• A publication-ready introduction to governed AI workflows for JVM teams, with a companion conference-talk outline.
• An example selection guide distinguishing learning demos, provider-backed integrations, durable approval proofs, sovereign reference workflows, and offline verification harnesses.
• A dated, official-source comparison of TramAI, Spring AI 2.0.0, and LangChain4j 1.17.2, stating maturity boundaries without claiming feature absence, compliance, universal superiority, or drop-in compatibility.

New Examples

• examples/governed-workflow — deterministic claim triage with policy and approval gates.
• examples/approval-resume — durable approval suspension and resume with embedded PostgreSQL.
• examples/tool-governance — three deterministic scenarios covering ALLOW (customer lookup), DENY (account deletion), and REQUIRE_APPROVAL (payment processing), proving that exposure permission is independent from execution permission.

Upgrade Notes from 0.4.0

• JavaBean schemas behave differently. Java DTOs with bean accessors now contribute real properties. If you were working around empty Java schemas, remove the workaround.
• Validation may reject payloads it previously accepted. @AiRange and @AiMinItems now participate in validation, so previously-passing model output can fail and trigger repair.
• Tool events moved evidence families. BEFORE_TOOL_* events are now written to tool.permissions.jsonl instead of policy-decisions.jsonl. Update any bundle consumer that assumed a single policy file.
• Evidence bundles gained a file. runtime-evidence/tool-permissions.jsonl appears when tool permission evidence is exported, and the verifier requires a matching files[] entry.
• Approval decisions store digests, not comments. Do not expect raw decision comments in audit records.
• Preview APIs may still evolve. The approval control plane REST endpoints, reviewer UI, runtime evidence exporters, and tool governance APIs remain preview.

No breaking changes were made to the typed-service, provider, structured-output, or orchestration surfaces. This release does not freeze APIs.

Non-claims

TramAI 0.5.0 does not certify production readiness for every deployment configuration, does not provide legal, regulatory, or EU AI Act compliance, does not guarantee security certification, does not validate evidence truth (only structural tamper-evidence), and does not replace an audit or compliance review. It also does not ship a governed MCP connector, key rotation, a production-grade reviewer UI, or enterprise IAM.

Maven Central publication, tagging, and release signing are handled by the maintainer release sequence after the release commit is merged — they are not part of this release's code change.

Compatibility Notes

• TramAI 0.5.0 remains a pre-1.0 release line.
• The typed-service, provider, structured-output, orchestration, and observability APIs remain the stable baseline.
• Sovereign and security APIs are implemented and documented, but parts of the operational surface remain preview.
• Consumers on the 0.5.0 line align versions through the BOM: dev.tramai:tramai-bom:0.5.0.