TramAI - governed AI workflows for Java and Kotlin

tramai-spring-boot-starter-sovereign-ops

Version: 0.6.0
Status: Preview
Role: The operational surface for a sovereign deployment: service beans only, no HTTP, no persistence binding.

Purpose

A sovereign deployment suspends work for human approval, persists audit events, and resumes continuations once a decision is made. This starter provides the services that do that: the approval decision/resume control plane, read operations over approvals, suspended invocations and audit streams, the audit-outbox worker (with recovery and dispatch) and the approved-continuation resume worker.

It is deliberately transport-neutral: it exposes service beans only. No HTTP endpoints, no persistence implementation, no metrics binding. Those live in the opt-in add-ons — -ops-rest, -ops-actuator, -ops-micrometer, -ops-observability and the sovereign persistence starters.

What it provides

TypeRole
SovereignAuditOperations, DefaultSovereignAuditOperationsPaged reads over audit streams
SovereignSuspendedInvocationOperations, DefaultSovereignSuspendedInvocationOperationsInspection of suspended invocations
SovereignApprovalOperations, DefaultSovereignApprovalOperationsApproval reads, and audited mutations when enabled
ApprovalDecisionControlPlane, ApprovalResumeControlPlaneDecision and resume orchestration
SovereignOpsApprovedContinuationResumeWorker + ApprovedContinuationResumeWorkerStatusSnapshotBackground resume of approved continuations
SovereignOpsAuditOutboxBackgroundWorker, SovereignOpsAuditOutboxOperations, SovereignOpsAuditOutboxStoreAudit outbox recovery, dispatch and status
SovereignOpsAuditOutboxWorkerObserver (+ …ObserverContribution)Observer SPI the metrics/observability add-ons plug into
SovereignOpsTransactionalApprovalGatewayCommits approval, suspended invocation, continuation and outbox intent in one transaction when a mutation store is available

Activation: the ops auto-configuration is active by default once the sovereign runtime is in the context (tramai.profile: sovereign); set tramai.sovereign.ops.enabled: false to suppress it. It is read-capable and mutation-disabled by default — inspection is safer than state mutation, so denyApproval is blocked until tramai.sovereign.ops.mutations-enabled: true. Mutations also require a durable outbox store — the auto-configured in-memory outbox makes them fail closed with tramai-sovereign-ops-audit-outbox-not-durable.

Properties — SovereignOpsProperties (tramai.sovereign.ops.*):

tramai:
  sovereign:
    ops:
      enabled: true          # default; set false to suppress the ops surface
      mutations-enabled: false
      max-page-size: 100
      outbox:
        worker:
          enabled: true          # audit outbox background worker
          interval: 30s
          batch-size: 100
          lease-enabled: false   # true for multi-node coordination
          lease-name: sovereign-ops-audit-outbox-worker
      approved-resume-worker:
        enabled: true
        interval: 5s
        batch-size: 50
      approval-gateway:
        non-transactional-fallback-enabled: false

The non-transactional DefaultApprovalGateway is not enabled by default: it is created only when no mutation store exists, the generic stores are present, a request factory is present, and the fallback flag is explicitly set. Missing any dependency means no gateway bean and an unaffected startup — which also means the application must supply its own ApprovalGatewayRequestFactory, since request construction is workflow-specific.

Dependencies

dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
    implementation("dev.tramai:tramai-spring-boot-starter")
    implementation("dev.tramai:tramai-spring-boot-starter-sovereign-ops")
}

When to use this starter

  • A sovereign deployment that needs human approval, resume, audit inspection or the outbox workers.
  • You want the ops services behind your own authentication layer rather than an HTTP surface.
  • You are composing the REST, Actuator, Micrometer or OpenTelemetry add-ons on top.

When NOT to use this starter

  • You expect HTTP endpoints out of the box — add -ops-rest, and put it behind your own authorization.
  • You expect metrics or tracing bindings — add -ops-micrometer or -ops-observability.
  • You are running the standard (non-sovereign) profile: the ops surface is sovereign-only.
Previous
Next