0.4.0 — Sovereign Runtime and Governed AI Operations

0.4.0 moves TramAI beyond the 0.3.1 foundation of typed services, providers, streaming, orchestration, memory, and observability into a governed runtime for enterprise and offline deployments.

The largest change is the sovereignty track: a secure-by-default runtime profile, explicit policy boundaries, approval suspension and resume, artifact verification, evidence packs, offline deployment checks, and Spring Boot operational starters.

Why Sovereign AI Work Is Needed

AI in backend systems is not just another API call. It can read sensitive business context, route that context to external providers, invoke tools, mutate systems, and produce decisions that need to be explained later. For prototypes, a normal provider client is enough. For production systems in regulated or security-sensitive environments, that is not sufficient.

The sovereign work exists because teams need to answer operational and audit questions before they can safely deploy AI workflows:

• Where can this data go? Customer records, contracts, health data, financial data, source code, and internal incidents cannot all be routed to the same provider class. The runtime needs explicit provider trust zones and data-classification routing.
• Which models are allowed? A production system needs a model allowlist, not "whatever model name was passed at runtime". Local models also need artifact integrity checks so a deployment can prove which files were used.
• Who approved high-risk actions? AI workflows often call tools that send emails, update tickets, retrieve secrets, trigger jobs, or write to business systems. High-risk actions need human approval, token-bound resume, expiry, version checks, and replay-safe consumption.
• Can we prove what happened? Observability shows performance and failures, but auditors need tamper-evident evidence of policy decisions, approvals, redactions, artifact verification, deployment mode, and supply-chain context.
• Can this run without egress? Some deployments must operate in disconnected or air-gapped environments. "Use Ollama locally" is not enough; the runtime must reject non-local providers and routes when offline mode is declared.
• Can operations run this safely? Approval queues, outbox workers, leases, REST control planes, Actuator health, Micrometer metrics, and persistent stores are needed so sovereign workflows survive restarts and can be operated by platform teams.

Without these controls, the burden falls on each application team to reinvent allowlists, routing rules, approval state machines, audit chains, evidence generation, and offline safeguards. That leads to inconsistent policy, gaps between environments, and security behavior that is hard to test.

0.4.0 makes those concerns first-class framework capabilities. The goal is not only to call models safely, but to make governed AI behavior explicit, testable, inspectable, and deployable in environments where data residency, approval, and evidence matter.

What Changed Since 0.3.1

0.3.1 was primarily a stability release. It kept the 0.3.0 public module surface and focused on streaming persistence, proxy-aware tool scanning, and reasoning-token usage accounting.

0.4.0 adds a new security and sovereignty layer around the existing runtime:

Sovereign Runtime

tramai-sovereign

The new tramai-sovereign module is an aggregator around tramai-standalone and tramai-security. It exposes SovereignTramai, a secure wrapper around the normal standalone builder.

SovereignTramai makes the security profile mandatory instead of optional:

• SovereignProfileConfiguration is required.
• ModelRegistry is required and always enabled.
• AuditStore is required for policy-decision audit events.
• At least one provider must be registered.
• Every provider must appear in allowedProviders.
• Every allowed provider must be registered.
• Every provider must have an explicit ProviderTrustZone.
• Every allowed model must have a primary route.
• Every fallback route must target an explicitly allowed fallback provider.
• Offline profiles must use only LOCAL providers and routes.

The result is fail-fast configuration. Misconfigured models, providers, trust zones, fallbacks, and offline routes fail during build(), before any AI operation runs.

SovereignProfileConfiguration

The profile is the central sovereignty contract. It defines:

• allowedModels
• allowedProviders
• allowedFallbackProviders
• allowedTools
• allowedPermissions
• providerZones
• deploymentMode

It rejects blank values, surrounding whitespace, wildcard-only entries, empty model/provider allowlists, fallback providers outside the provider allowlist, and providers without trust zones.

When converted into policy configuration, it starts from PolicyConfiguration.secure() and overlays only explicit allowlists. That means the default posture is deny-all, not permissive-with-overrides.

Runtime Encapsulation

SovereignTramaiRuntime wraps the lower-level TramaiRuntime and exposes only the methods needed for governed usage:

• create a typed service proxy
• register a service for resume after restart
• resume an approval-suspended execution
• use typed resume helpers
• close the owned runtime

This prevents unsafe standalone runtime methods from leaking into the sovereign API surface.

Policy and Routing

Deny-by-Default Policy Engine

tramai-security adds DefaultPolicyEngine, which evaluates the main enforcement points:

• before provider resolution
• before provider invocation
• before fallback
• before tool exposure
• before tool execution
• before tool result reinjection
• before response return
• before workflow resume

Unknown models, providers, tools, and permissions are denied unless explicitly allowed by the active policy configuration.

Tool execution also enforces security metadata. In sovereign mode, legacy tools without security metadata are rejected, and high-risk or explicitly approval-gated tools require human approval.

Trust Zones and Classification-Aware Routing

0.4.0 introduces provider trust zones:

• LOCAL
• EU_CLOUD
• GLOBAL_CLOUD

The sovereign profile always enables classification-aware routing through ProviderRoutingConfiguration.sovereignDefaults().

The default routing matrix is:

This turns data residency into a runtime-enforced policy instead of a documentation convention.

Approval Workflows

0.4.0 expands human-in-the-loop approval from low-level workflow suspension into a usable governed workflow surface.

Approval Coordination

DefaultApprovalGateCoordinator handles approval creation and resume authorization. It provides:

• generated approval IDs
• generated approval tokens
• SHA-256 token digests
• approval TTL enforcement
• expected-version checks
• workflow/tool/arguments/policy/workflow-digest binding
• actor ID validation
• replay-aware consumption of approved requests
• safe failure mapping

Resume is authorized only when the presented token and binding data match the original approval challenge. This is why sovereign mode intentionally allows the BEFORE_WORKFLOW_RESUME policy enforcement point: resume security is enforced by the approval coordinator before the workflow resumes.

Approval Gateway

The sovereign ops layer adds SovereignOpsTransactionalApprovalGateway.

It writes the approval request, suspended invocation, continuation, resume credential, inbox metadata, and optional audit outbox intent as one atomic mutation through the configured persistence store. This avoids split-brain approval state where a request exists without the data needed to resume it, or audit exists without the approval record.

Approval Result Model

The 0.4.0 sovereignty surface includes a workflow result model for governed execution:

• completed
• suspended for approval
• rejected
• expired

This lets application code return explicit governed states instead of treating approval suspension as an exceptional side channel.

Audit and Evidence

Hash-Chained Audit

tramai-security adds a hash-chained audit engine. Sovereign mode wires audit emitters for policy decisions and approval lifecycle events automatically.

Audit events include sequence information, previous-event hash, event hash, enforcement point, decision, actor context, reason code, and timestamp. This supports tamper-evident review of policy and approval activity.

Specialized emitters also connect DLP redactions and sovereign operations to the audit stream.

Evidence Packs

SovereignEvidencePackV1 is a deterministic JSON evidence artifact for audits and release/security reviews.

It records:

• schema version
• deployment mode
• allowed models
• allowed providers
• provider trust zones
• artifact verification settings
• local model artifact verification receipts
• optional zero-egress evidence
• optional audit-chain evidence
• optional SBOM/supply-chain evidence
• optional release-bundle evidence
• optional CI/CD attestation evidence
• generation timestamp

Evidence packs are designed to be safe for auditor review. They do not include prompts, payloads, tokens, secrets, stack traces, or filesystem paths.

Artifact Verification

0.4.0 adds build-time verification for local model artifacts.

When artifact verification is enabled, sovereign build validates every local-model primary route and fallback route through the configured ModelArtifactVerifier.

The implemented verifier checks local artifact manifests and model files for:

• missing manifests
• manifest identity drift
• aggregate digest mismatch
• missing files
• symlink rejection
• file size mismatch
• file digest mismatch
• traversal attempts
• directory substituted for file
• non-regular files
• total-size overflow
• access failures

Verification receipts are immutable and exposed through SovereignTramai.verificationReceipts(). These receipts can then be included in evidence packs.

DLP and Classification

tramai-security adds the DLP and classification primitives used by sovereign deployments:

• RuleBasedDlpInterceptor
• DLP redaction audit emitter
• document classification inputs and decisions
• rule-based document classifier
• classification routing decisions

DLP can be attached through the sovereign builder, and redaction audit can be bridged into the hash-chained audit engine.

Offline Deployment

SovereignDeploymentMode.OFFLINE makes air-gapped operation explicit and enforceable.

In offline mode, the builder rejects:

• registered providers whose trust zone is not LOCAL
• primary routes to non-local providers
• fallback routes to non-local providers
• default providers that are not local

The check runs before model registry lookup so offline violations fail early and deterministically.

Spring Boot Sovereign Operations

0.4.0 adds a full Spring Boot sovereignty stack.

Core Starter

tramai-spring-boot-starter-sovereign provides Spring auto-configuration and properties for constructing a sovereign runtime from application configuration.

Ops Starter

tramai-spring-boot-starter-sovereign-ops adds operational services around governed approvals and audit delivery:

• approval decision control plane
• approval resume control plane
• approval gateway auto-configuration
• suspended invocation operations
• runtime operations
• audit operations
• approval inbox metadata
• approved continuation resume queue
• approved continuation resume worker
• audit outbox dispatcher
• leased audit outbox background worker
• worker lease store SPI
• observer extension points
• in-memory development stores

Persistence Starters

0.4.0 includes dedicated sovereign persistence starters:

• tramai-spring-boot-starter-sovereign-persistence-file
• tramai-spring-boot-starter-sovereign-persistence-jdbc

The JDBC path includes stores for approvals, approval request mutations, audit outbox records, worker lease state, resume queue state, and status snapshots. The outbox and approval mutations are designed around atomic writes and leased background processing.

Operations Add-ons

The ops layer is split into focused starters:

• tramai-spring-boot-starter-sovereign-ops-rest
• tramai-spring-boot-starter-sovereign-ops-actuator
• tramai-spring-boot-starter-sovereign-ops-micrometer
• tramai-spring-boot-starter-sovereign-ops-observability

These expose the sovereign operations surface through REST/control-plane endpoints, health/Actuator integration, Micrometer metrics, and observability hooks.

Examples

The 0.4.0 codebase includes sovereign-focused examples:

• examples:sovereign-document-intelligence
• examples:sovereign-offline-verification
• examples:spring-sovereign-starter

These examples demonstrate document-intelligence governance, offline verification, and Spring Boot sovereign starter wiring.

Module Additions

The sovereignty track adds or elevates these modules as implemented framework surface:

• tramai-security
• tramai-sovereign
• tramai-persistence-file
• tramai-persistence-jdbc
• tramai-spring-boot-starter-sovereign
• tramai-spring-boot-starter-sovereign-persistence-file
• tramai-spring-boot-starter-sovereign-persistence-jdbc
• tramai-spring-boot-starter-sovereign-ops
• tramai-spring-boot-starter-sovereign-ops-actuator
• tramai-spring-boot-starter-sovereign-ops-micrometer
• tramai-spring-boot-starter-sovereign-ops-observability
• tramai-spring-boot-starter-sovereign-ops-rest

Compatibility Notes

• TramAI 0.4.0 remains a pre-1.0 release line.
• The foundational typed-service, provider, structured-output, orchestration, and observability APIs remain the stable baseline for most users.
• Sovereign/security APIs are implemented and documented, but parts of the operational surface are still preview/evolving.
• Consumers should use the BOM: dev.tramai:tramai-bom:0.4.0.
• Use tramai-sovereign when the application needs a hard security boundary. Use tramai-standalone or tramai-spring for ordinary application development.