TramAI - governed AI workflows for Java and Kotlin

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

Version: 0.6.0
Status: Preview
Role: Opt-in Spring Boot starter for file-backed sovereign persistence.

Purpose

This add-on starter replaces the sovereign runtime's in-memory stores with the encrypted file-backed stores from tramai-persistence-file. It is opt-in: nothing changes unless you both add the dependency and set tramai.sovereign.persistence.type: file.

The auto-configuration runs before tramai-spring-sovereign, so its store beans exist when the base starter would otherwise create in-memory defaults — the base beans are @ConditionalOnMissingBean and back off. All stores you define yourself take precedence.

What it provides

BeanType
FileBackedSovereignStoresStore bundle, destroyMethod = "close" releases the exclusive file lock on context shutdown
→ AuditStore, ApprovalStore, ApprovalContinuationStore, SuspendedInvocationStoreThe four file-backed stores
FileSovereignOpsAuditOutboxStoreFile-backed sovereign ops audit outbox
SovereignFilePersistencePropertiestramai.sovereign.persistence.* binding
SovereignStoreKeyLoaderLoads the AES key from key-env or key-file

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-persistence-file")
}

tramai:
  profile: sovereign
  sovereign:
    persistence:
      type: file
      base-dir: ./data/tramai-sovereign
      encryption:
        key-env: TRAMAI_SOVEREIGN_STORE_KEY

# the key must be a base64-encoded 256-bit AES key
export TRAMAI_SOVEREIGN_STORE_KEY="$(openssl rand -base64 32)"

Key rules, enforced at startup:

  • Exactly one source: key-env or key-file — never both, never neither.
  • The value must decode to 32 bytes (base64-encoded 256-bit AES key).
  • Plaintext keys in YAML are not supported.
  • base-dir is required and its absence fails startup with tramai-sovereign-file-persistence-missing-base-dir.

When to use this starter

  • Single-node sovereign deployments that need durable approvals, continuations, audit and outbox state.
  • Air-gapped or offline deployments where no database is available.
  • You want file persistence plus the ops workers without a JDBC driver.

When NOT to use this starter

  • Several application nodes must share the same sovereign state — use tramai-spring-boot-starter-sovereign-persistence-jdbc.
  • The runtime is a test or demo where in-memory state is enough.
  • You want file persistence without the ops surface — this starter composes the ops starter, so that surface comes along.
Previous
Next