API Stability

TramAI 0.6.0 is pre-1.0. "Pre-1.0" does not mean "anything can change anywhere", but it does mean the compatibility promise is tiered and explicit. This page states the 0.6.0 tiers; treat anything outside the stable tier as able to move.

Stability Tiers In 0.6.0

Stable

• tramai-core — annotations, request and response models, the provider registry and routing plan, exception types.
• tramai-bom — version alignment for everything else. Depend on it rather than pinning module versions by hand.

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

Preview

Published in 0.6.0, preview maturity, no stability promise yet:

No provider adapter is stable in 0.6.0. Provider ids and routing behavior are documented on Providers and are what the adapters implement, but they are not covered by a stable compatibility contract at this release.

Internal

tramai-dashboard, tramai-mcp, tramai-memory-store, and tramai-server are implemented in the repository but are not published artifacts in 0.6.0. Do not build against them from a separate project, and do not read their repository docs as a consumer API. tramai-spring-consumer-boundary and tramai-spring-consumer-selective are internal test-support projects.

tramai-testing is the exception: internal maturity, but published, because test support has to be a real dependency. Treat its non-test-fixture API as internal too — see Testing.

Outside The Stable Promise

Two markers flag public declarations that exist only because modules in this repository cross a boundary — never because applications should call them:

Both are @RequiresOptIn, and both are registered as non-public markers in the binary-compatibility validator. That means they are removed from the tracked public API dump instead of silently entering the frozen surface: an unmarked new public declaration still fails the gate, but these marked internals stay free to change or move.

The experimental Codex/ChatGPT auth-file path (@ExperimentalCodexAuth) is a third such area, scoped to the OpenAI adapters.

How The Stable Surface Is Protected

• Kotlin binary-compatibility validation (apiCheck). Public API dumps are tracked for every publishable module. Unreviewed drift between releases fails the build; deliberate migrations are recorded with a rationale, and the two experimental markers are excluded via the non-public-marker list.
• Kotlin and Java consumer smoke compilation gates. Real consumer projects — examples/kotlin-consumer-smoke and examples/java-consumer-smoke — are compiled against the published surface, so a change that breaks an ordinary application consumer fails CI rather than a release.
• Architecture governance. A unified verify060Architecture gate enforces the ten-layer topology, module boundaries, and module-catalog enrollment. A new module that is not enrolled in the catalog does not build.
• Contributor change guides. Six documented change drills cover adding a provider, a workflow step, a store, an event, an approval state, and changing structured-output constraints.
• Coverage and mutation ratchets on critical packages. These harden behavior; they are not an API promise, so read them as quality evidence, not as stability.

Sovereign Runtime Is A Release-Candidate Boundary, Not 1.0

The sovereign runtime in 0.6.0 is a release candidate with an enterprise-proof scope. Stated plainly, it is:

• not a stable 1.0 API declaration
• not a production deployment certification
• not a compliance or certification claim

The documented boundary confirms it: store and runtime SPIs are RC+ stable, workflow ergonomics are preview, concrete JDBC implementations are internal, and key rotation, a production-grade reviewer UI, a production-grade admin REST surface, and 1.0-wide API stability are all deferred. Authentication, dashboards, and organization-specific alerting remain the operator's responsibility.

What that means in practice: if you are evaluating the sovereign runtime for regulated or high-assurance work, treat it as a release candidate you validate in your own environment, not as a certified platform.

Release Baseline Assumptions

TramAI 0.6.0 is documented against:

• Java 21+ as the language baseline — 21 for the language level and 25 for CI compilation and test runtime
• Kotlin-first APIs with a Java-friendly surface
• a framework-agnostic core with optional Spring integration

If one of those changes, treat it as a release-level change, not quiet drift.

Related Pages

• Limitations
• Configuration
• Module Catalog
• API Compatibility
• CI Integration