Library compatibility

KetraTerm's published libraries support Kotlin and Java hosts. The current 0.x API snapshots are a development baseline, not a stable API freeze or a promise of compatibility with earlier 0.x releases. Starting at 1.0, releases within one major version preserve supported source, binary, and behavioral contracts.

Supported boundary

Offering	Published JVM modules
Headless pipeline	protocol, parser, core, host, input, render-api, render-cache, transport-api, session
Swing view	ui-swing
Local processes and shell metadata	pty, shell-integration
Completion	completion, completion-host
Swing host controls	ui-swing-host

Names have the ketraterm- prefix. The constraints-only BOM and dependency-only headless/Swing entry points are additional metadata publications. Use one KetraTerm version throughout the dependency graph; see installation and Maven setup.

Public/protected declarations in published libraries are supported contracts. Kotlin internal/private declarations are excluded, except published inline bridges that already-compiled callers can reference. Workspace, completion persistence, app, testkit, benchmarks, and IntelliJ product implementation APIs are outside the supported publication boundary.

Kotlin 2.4 and JDK 25 are the minimum supported consumer versions. The build uses Kotlin 2.4.20, JVM target 25, and JVM default-method compatibility bridges. Consumer checks exercise Kotlin 2.4.0/2.4.20 and both Gradle metadata and POM-only resolution. A host replacing dependencies with a platform runtime must verify that runtime separately.

Evolution rules

Preserve JVM signatures, Kotlin metadata, defaults, and documented semantics.
Preserve constructor, copy, component, and default-call shapes of value data classes. Adding a defaulted constructor field can still break binaries.
Grow configurable snapshots through their existing builder/update entry points; preserve existing property types and defaults.
Preserve overloads and Kotlin default-call methods. Java overload generation does not make Kotlin default-argument changes binary compatible.
Treat interfaces as implementer contracts. New abstract members and new enum/sealed variants need source and compiled-consumer assessment.
Preserve public packed values, encoded enum order, constants, and inline bridge behavior; signature checks cannot detect semantic drift.
Keep public dependency types available through publication metadata.
During a stable major version, deprecate with a replacement before removal; incompatible removal belongs in a new major release.

OSC 22 sink migration

External sinks must implement setPointerShape(TerminalPointerShape?); null restores the host pointer default. Recompile sink implementations and Kotlin delegates.

OSC 21 color migration

Custom TerminalCommandSink implementations must implement applyColorRequest(TerminalColorRequest) and consume the borrowed batch synchronously. Custom TerminalModeController implementations must implement applyColorRequest(TerminalColorRequest, Boolean) with ordered mutations and permission-controlled replies. Recompile these implementations and Kotlin delegates. Existing palette constructor and copy signatures remain available.

Color-stack support also requires pushColors() and popColors() on both interfaces. Recompile custom implementations and Kotlin delegates; the core methods follow the color-stack contract.

Verification and baseline changes

Supported modules use explicit API mode and checked-in ABI snapshots. Published consumer fixtures compile and run independent Java/Kotlin clients; retained binaries test upgrades without recompilation. Deliberate linkage-failure controls check that the upgrade harness detects missing symbols.

./gradlew publicationChecks runs the library publication gates against a local repository without uploading. The consumer fixture guide explains individual checks and baseline refreshes. A deliberate development baseline refresh must record the break and migration; it cannot be presented as proof of compatibility with the earlier API or retained clients.

ABI checks do not establish threading, lifecycle, coordinate, or protocol correctness. Those require semantic tests and the module contracts. Product release verification remains separate; see the gap map.

Color-reset and change-report baseline decision

The 0.x color-reset and mode 2031/2048 migration deliberately establishes a new retained-client baseline. Existing method signatures remain available, but the required additions to TerminalCommandSink, TerminalModeController, TerminalResponseChannel, and TerminalBuffer change their implementer contracts. Retained pre-feature Kotlin by delegates do not contain forwarding methods for these additions: the Swing consumer fails with AbstractMethodError when host assembly calls setChangeNotificationsAllowed.

Recompile Kotlin delegates against the updated interfaces, even when their source is unchanged. Custom implementations must implement the new reset, subscription, notification-permission, and pixel-aware resize methods. These methods enforce terminal semantics and host authorization; they have no silent fallback defaults.

The chosen development migration records clients compiled against the reviewed new interfaces, with fixture sources, jar hashes, compiler/toolchain details, and staged dependency hashes in their provenance. Review sources, artifacts, provenance, and ABI snapshots together, then run the source-consumer and retained client checks described in the consumer guide. The refreshed baseline verifies subsequent upgrades of those recompiled clients; it does not establish binary compatibility with the pre-feature baseline or any earlier 0.x release.

Development migrations

These earlier 0.x changes require affected consumers to recompile. Detailed release history remains in the changelog.

Earlier shape	Current integration
Custom parser/core implementations or compiled Kotlin delegates before graphics commands	Implement `graphicsTransferGeneration` and `applyGraphicsCommand` on `TerminalCommandSink` and the core's `TerminalGraphics` role, now part of `TerminalBuffer`; core implementations also accept immutable images through `applyDecodedGraphicsCommand`. Recompile implementations and Kotlin delegates. Consume borrowed controls/data synchronously and preserve response permission. Existing render-frame providers retain empty-image defaults; providers supplying images must implement `copyImages` and its generation contract.
Session construction and synchronous UI mutation before decoded graphics	Existing construction signatures and Kotlin default arguments remain available; an additional overload accepts an independent cleanup dispatcher. Preserve `TerminalGraphicsOutputParser` in built-in parser decorators. Run gated settings/clear/geometry off UI threads; use Swing binding/mutation completion callbacks and `requestClose` for UI disposal. Connector startup/output must tolerate concurrent close. See the session contract.
Custom parser/core implementations or compiled Kotlin delegates before application mouse controls	Implement `TerminalCommandSink.setShiftMouseCaptureEnabled` and the core's `setAlternateScrollEnabled`/`setShiftMouseCaptureEnabled` methods, and recompile implementations/delegates. New `TerminalInputState` helpers decode the routing flags; existing packed fields retain their numeric meanings.
Custom `TerminalModeController` implementations or compiled Kotlin delegates before reverse wrap	Implement `setReverseWrap` and `setReverseWrapExtended` and recompile against the updated SPI to handle modes 45/1045. Existing caller methods retain their signatures; cursor-only flags are queried through DECRQM. See the cursor contract.
Custom terminal command/core implementations or compiled Kotlin delegates before color reset and change-report methods	Implement the new reset/subscription methods, `setChangeNotificationsAllowed`, and pixel-aware `TerminalBuffer.resize`; recompile implementations and delegates against the updated SPI. Existing resize overloads remain callable. See the baseline decision and core semantics.
Growing settings constructors, named-argument copies, destructuring	Immutable `create`/`copy` callbacks or Java builders; use getters.
Swing history/window-permission settings	Core/PTY history configuration and session host policy.
Session render-publisher access	`readPublishedFrame`; retain mutable producer references at assembly.
Public integer render leases	Scoped `readCurrent` or session reads; see reader ownership.
Constructor-bound suggestion provider/edit target	EDT provider/target setters and request-scoped editing authority.
Global suggestion feedback handler	Request-owned source/interaction observer with actual acceptance results.
Old suggestion show/request/candidate shapes	Begin, publish/collect, and present an interaction; update custom presentation to snapshot-based callbacks.
Pre-bound custom input encoder	`TerminalInputEncoderFactory` with session-owned output; implement synchronous input-policy updates.
Earlier buffer factory return type	`TerminalRenderBuffer`; changed JVM return descriptors require recompilation.
Non-null shortcut lookup	Handle null for legitimately unbound actions.
Workspace/persistence development artifacts	Product-only modules; library hosts own these concerns.

See configuration, session assembly, and Swing APIs for current usage.

View source on GitHub ↗