Module: tramai-bom

One-liner: Bill of materials — a single-import Maven BOM (Gradle java-platform) that aligns versions of all Tramai publishable modules so consumers never worry about cross-module version mismatches. Module type: platformGroup: dev.tramai, Version: 0.6.0Module file: build.gradle.kts + the tramai.java-platform convention plugin (the constraint list is derived from the module manifest, never hand-maintained)

L1: Quick Start (30-second read)

What

tramai-bom is a Gradle java-platform (published as a Maven BOM with packaging=pom) that declares version constraints for every Tramai module that is published with the release. It contains no source code: the tramai.java-platform convention plugin reads the module manifest and adds one api constraint per published, release-included project, so the constraint set cannot drift from the catalogue.

When a consumer imports the BOM, all Tramai dependencies resolve to the same version without the consumer needing to specify individual versions.

Why

In 0.6.0 TramAI publishes 44 modules through the BOM (45 published artifacts including tramai-bom itself). They have deep internal dependencies — provider adapters on the core contracts, Spring starters on tramai-spring-core, the sovereign starters on the security and persistence modules:

Without a BOM, a consumer who mixes versions (e.g., tramai-core:0.6.0 with tramai-engine:0.6.0) risks NoSuchMethodError, binary-incompatible SPI types, or broken annotation processing at runtime. The BOM eliminates this category of error entirely.

When to use the BOM

• Always — in any multi-module Tramai project that consumes two or more Tramai modules.
• Often — even in single-module usage, because adopting another module later requires no version changes.
• Never — if you only use exactly one Tramai module and are comfortable managing its version directly (not recommended for future-proofing).

L2: Usage — Maven BOM Import

Gradle (Kotlin DSL)

dependencies {
    // 1. Import the BOM
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))

    // 2. Declare Tramai modules without versions
    implementation("dev.tramai:tramai-orchestration")
    implementation("dev.tramai:tramai-openai")
    implementation("dev.tramai:tramai-testing")
}

Gradle's platform() notation activates the version constraints from the BOM. All three modules resolve to 0.6.0 — the version declared in the BOM for each.

To override a single module version (e.g., to test a snapshot):

implementation("dev.tramai:tramai-openai:0.6.1") // an explicit version wins over the BOM constraint

Maven

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>dev.tramai</groupId>
            <artifactId>tramai-bom</artifactId>
            <version>0.6.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>dev.tramai</groupId>
        <artifactId>tramai-orchestration</artifactId>
        <!-- version inherited from BOM -->
    </dependency>
</dependencies>

The BOM's packaging=pom is verified at publication time — the CI pipeline checks that no accidental JAR is emitted for tramai-bom.

L3: Version Alignment

How it works

tramai-bom uses Gradle's java-platform plugin, which produces a Maven BOM POM with a <dependencyManagement> section.

The build.gradle.kts is straightforward:

The entire build script is:

plugins {
    `java-platform`
    id("tramai.java-platform")
}

The convention plugin allows dependency management on the platform and adds the constraints from the manifest:

// TramaiJavaPlatformPlugin — build-logic
project.dependencies.constraints {
    val bomModulePaths = ModuleManifest.bomModulePaths(project.rootProject.rootDir) // published + release-included, minus tramai-bom
    bomModulePaths.forEach { path ->
        add("api", project.dependencies.project(mapOf("path" to path)))
    }
}

When published, Gradle resolves each project() reference to the current project version (tramaiVersion, default 0.6.0). The resulting POM contains a <dependencyManagement> block that lists every module with its resolved version.

Versions it pins

The BOM pins every published, release-included module except tramai-bom itself — 44 artifacts:

Modules classified publishability: internal in the manifest (tramai-dashboard, tramai-mcp, tramai-memory-store, tramai-server, tramai-spring-consumer-boundary, tramai-spring-consumer-selective) are not pinned, because they are not published. The nine :examples:* projects are excluded too (publishability: excluded, releaseInclusion: excluded). The catalogue tracks 60 Gradle projects in total; tramai-bom constrains 44 of them.

External (third-party) dependencies like OkHttp, Jackson, or OpenTelemetry SDK are not pinned by tramai-bom — those are managed by each module's own dependency declarations and the consumer's own platform constraints.

Verification

The root build.gradle.kts applies the tramai.release-verification plugin, which registers a typed verifyPublicationMetadata task. It checks, for every publishable module:

• The generated Maven POM's group, version, project URL, SCM coordinates, license, developer, and description match the expected values
• The set of modules covered matches the manifest's set of publishable modules, and the set of modules publishing a JAR is that list minus tramai-bom

That last point is how "the BOM publishes no JAR" is enforced: tramai-bom is in the pom-only set, so no accidental JAR, -sources.jar, or -javadoc.jar can slip out of the platform module. The task has no output artifact (caching is disabled by design).