Skip to content

v0.13.0

Choose a tag to compare

@arkstack-dev arkstack-dev released this 28 Oct 19:09
· 4 commits to main since this release
v0.13.0
4a76a39

title: "Exeris Kernel v0.13.0 — Release Notes"
type: release-notes
visibility: public
owning-repo: exeris-kernel
status: active
last-verified: 2026-10-28

Exeris Kernel v0.13.0 — Release Notes

Artifacts eu.exeris:*:0.13.0
Date 2026-10-28
Predecessor 0.12.0
Framing Pre-1.0 / TRL-3. Per-surface semver policy: docs/stability-matrix.md.

Scope of these notes. They describe behaviour published in this repository, taken from the
[0.13.0] section of CHANGELOG.md and the 0.12.x → 0.13 sections of
MIGRATION.md. The changelog lists every entry; these notes group them by area
and say what a consumer does about each.

Summary

0.13.0 is the last release line before the 1.0 release candidates. Its work falls into seven groups.

  • The SPI stability promotions of ADR-100. spi.http (the whole package), spi.security with
    security.identity, spi.events, spi.crypto, spi.scheduling and spi.storage.blob are stable,
    joining transport, persistence, flow and memory. The SPI compatibility gate fails a binary- or
    source-incompatible change to them, and they are semver-binding from 1.0. spi.contract, spi.graph,
    spi.time and spi.websocket stay preview.
  • GraalVM native-image as an opt-in build (ADR-103). The Core, Community and Kafka jars ship
    reachability metadata and Community ships the image build arguments it needs.
  • A bound on a stream's outbound queue. TransportStream#write blocks at the bound, and
    queueWrite never waits for the peer.
  • HTTP/2 conformance fixes. The h2c upgrade, flow control, request bodies above 64 KiB, frame-size
    validation, HPACK and a stream route over HTTP/2.
  • Row-level-security hardening. The reference policies refuse a tenant-less request and pin the
    shared-scope tag, and a boot refuses a database role that bypasses RLS.
  • The licence and entitlement contract (ADR-088, ADR-089). The boot verifies a signed manifest and
    enforces scoped issuer keys and a developer-licence workload ceiling.
  • Flow and build. A finished saga keeps its snapshot row, EdDSA tokens verify, and the tests move to
    Testcontainers 2.0.5.

The release carries breaking changes on declared surfaces; the section Breaking changes and upgrade
below names each with its MIGRATION.md heading.

SPI stability (ADR-100)

  • The promoted packages and the preview set are listed above and in
    docs/stability-matrix.md. No signature changed with the promotion.
  • The ScopedValue slots of the preview surfaces move to holders in their own packages so that a
    stable signature names no preview type: spi.contract.ContractKernelProviders,
    spi.graph.GraphKernelProviders and spi.time.TimeKernelProviders. The KernelProviders names for
    the graph and time slots (GRAPH_PROVIDER, GRAPH_ENGINE, graphEngine(), TIME_SOURCE,
    timeSource()) are deprecated for removal in the first 1.0 release candidate; each is the same
    ScopedValue instance the holder declares, so a binding through either name is visible through both.
    StableSignatureArchitectureTest enforces the rule.
  • EventEngineStats gains publishFailedTotal(); the seven-argument constructor remains and reports zero.

Native-image opt-in (ADR-103)

  • Core, Community and Kafka ship reachability metadata under
    META-INF/native-image/eu.exeris/<artifactId>/ (the SPI's file is empty). Community ships
    --enable-monitoring=jfr, two --add-opens and -H:+SharedArenaSupport, so an application builds an
    image with no configuration of its own for the kernel. GraalVM 25 or newer and OpenSSL 3 on the host.
  • A unit test per module checks the metadata against the module's declaration sites.
  • RequiresRoleProcessor emits reachability-metadata.json for the RoleCheckRegistry it generates
    (option exeris.requiresrole.nativeImageMetadataDir); without it a native image loads the empty,
    fail-closed registry and every @RequiresRole denies.
  • An Error thrown by a subsystem goes through the failure policy as SubsystemException
    (EX-BOOT-0002) instead of escaping KernelBootstrap raw (#619).
  • HotSpot/C2 stays the default and the only runtime with asserted performance targets.
  • Two modules, exeris-kernel-native-smoke and exeris-kernel-native-smoke-kafka, build the sample
    images the native-smoke job runs.

Transport: the outbound write bound (ADR-007, ADR-071)

  • transport.maxQueuedWriteBytes (default 256 KiB) bounds a stream's outbound queue; -1 removes it,
    0 and other negatives are refused at startup. A Community write parks its caller while the stream
    holds that many bytes the peer has not taken, never parks a reactor thread, and emits
    TransportWriteParkEvent once before its first park (#556).
  • TransportConfig gains the component maxQueuedWriteBytes after maxActiveStreams; the 0.12 nine- and
    eight-argument constructors remain and apply the default.
  • A transport's queueWrite returns without waiting for the peer and releases a loan once its bytes have
    left the stream's queue or the stream ends. AbstractTransportStreamTck gains QueueWriteDoesNotWait
    (binds every transport) and WriteBackpressure (behind supportsWriteBackpressure()).
  • A closed TransportStream says who closed it: TransportStreamClosedException, an
    IllegalStateException, carries EX-NET-4008 when the remote end was observed first and EX-NET-4009
    after a local close() or reset(). A Community TCP or TLS send that fails because the peer ended the
    stream throws it instead of TransportException (EX-NET-4002, which is its cause).
  • PaqsScheduler records a handler that ends with EX-NET-4008 as StreamLifecycle outcome
    PEER_CLOSED and no longer emits PaqsHandlerFailure for it; a handler failure it isolates is logged
    with the stream id, the engine name and the exception class name.
  • The Community HTTP/2 writer hands every frame to queueWrite, and a WebSocket egress no longer stalls a
    connection's pongs and close echo behind a data write to a peer that stopped reading.
  • A TLS write that meets a full send buffer stalls instead of resetting the connection; a write after a
    TLS peer's close_notify reports EX-NET-4008 instead of failing as a handshake error (#686, #714); a
    thread blocked in read is woken by every transition that ends the stream. The first failed socket call
    of a JVM reads its own errno instead of ENOENT.
  • The four stream JFR events carry protocolStreamId, and StreamBackpressurePark carries windowBytes.

HTTP and HTTP/2

  • h2c upgrade. The server consumes the client connection preface and answers the upgrade request on
    stream 1; curl --http2 and nghttp -u no longer receive GOAWAY(PROTOCOL_ERROR).
  • Flow control. A request body above 64 KiB completes; the session returns credit as it consumes DATA,
    enforces its receive windows (FLOW_CONTROL_ERROR) and refuses a stream with REFUSED_STREAM when its
    body would take the bodies buffered on one connection past http.maxRequestBodyBytes. Respond-once
    responses honour the peer's connection and stream windows.
  • Frame size. Inbound frames are validated against the server's own SETTINGS_MAX_FRAME_SIZE; an
    oversized frame is GOAWAY(FRAME_SIZE_ERROR) and an out-of-range peer value GOAWAY(PROTOCOL_ERROR).
  • HPACK. An oversized field section is refused with 431 and a malformed block closes the connection
    with GOAWAY(COMPRESSION_ERROR), with the dynamic table kept in step. Table entries and the field
    section are sized by their wire octets (new TCK group ObsTextOctets). Header names and values reach
    handlers one char per octet (ISO-8859-1), as on HTTP/1.1 (ADR-071); see Breaking changes and upgrade.
    AbstractHttp2HeaderLimitTck pins the three header limits on the wire.
  • Stream routes over HTTP/2. A stream route that arrives over ALPN h2, a prior-knowledge preface or an
    h2c upgrade reaches its stream handler; each stream runs on its own thread, parks on the smaller of
    the stream's and the connection's window and on exeris.http.stream.creditWindowBytes.
  • ALPN. The listener's ALPN list follows http.maxVersion (#533); a WSS listener never selects h2.
    An SSE event larger than http.stream.creditWindowBytes no longer parks emit forever on HTTP/1.1.
  • Peer address. HttpExchange#remoteAddress() and remotePort() report the immediate transport peer.
  • Provider selection. Two HttpProviders at equal priority resolve by implementation class name.
  • TLS. The Community server sends its whole certificate chain (#532); the crypto provider enforces
    CryptoProviderConfig#minimumTlsVersion, so the default TLSv1.3 floor now holds and crypto.tls.minVersion
    is read when a transport is built; a failed release no longer hides a failed client-engine binding (#558).
  • Route policy. A bound HttpRoutePolicy is asked about the route the router dispatches to, closing
    GHSA-6gmf-jp4g-gvmh (see Security). HttpRouter.routeMethod names that method.

Security

  • GHSA-6gmf-jp4g-gvmh (CWE-863; affects 0.11.0–0.12.0 with a policy bound). The dispatcher passed the raw
    request-target and method to HttpRoutePolicy, so under a policy answering permitAll() for unmatched
    routes, GET /p?x=1 and HEAD /p reached the GET /p handler without its requirement. The query is
    removed, a HEAD served from the GET route is asked as GET, and a HEAD rule governs only a request
    dispatched to a HEAD route.
  • The Community crypto provider enforces minimumTlsVersion. Contexts, listeners and verifying
    clients had no protocol floor, so a TLS 1.2-only peer completed a handshake against the default.
  • JWKS keys are installed only for signing with the algorithm their type verifies (ADR-040 A1). use
    must be absent or sig, alg absent or the one the key type verifies (RS256, EdDSA), and no other
    installed entry may publish the kid. A deployment whose signing key carries another label gets
    EX-SEC-2002 until the issuer corrects it.
  • RLS reference policies (ADR-012 §4c). The tenant arm raises (SQLSTATE 42501) on an absent key
    instead of reading an empty result or admitting a row owned by ''; the shared-scope WITH CHECK admits
    only '', NULL or the scope the request published, so a row's own column no longer grants visibility.
    The kernel does not install either policy; the text is in docs/subsystems/persistence.md and the
    RlsConnectionInterceptor javadoc.

Persistence and RLS (ADR-012 §4c)

  • A boot with a row-level-security interceptor on PostgreSQL probes the connected role and stops with
    EX-PERS-5009 when it is a superuser or has BYPASSRLS; persistence.rlsAllowBypassRole=true boots it.
    New: PersistenceProviderException.rlsBypassRole, the eu.exeris.kernel.persistence.RlsBypassRole JFR
    event and AbstractRlsBypassRoleCheckTck.
  • AbstractSharedScopeAccessMatrixTck gains retagScope, the shared-scope tag cells, foreignScope() and
    tenantlessOwner(); PersistenceIsolationLeakTck asserts that a tenant-less context is refused. The
    matrix is bound on uuid keys by CommunityPersistenceSharedScopeUuidIT.
  • KernelProviders.TRANSACTIONAL_EXECUTOR publishes the Community TransactionalExecutor; retry comes from
    persistence.transaction.retry.maxAttempts (default 1) and persistence.transaction.retry.baseDelayMs
    (default 50), and a maxAttempts below 1 fails the boot.

Licence and entitlement contract (ADR-088, ADR-089)

  • Phase 0 of KernelBootstrap.boot() reads license-manifest.json (or license.manifest.path), checks it
    against ADR-088's v1 schema, canonicalizes it per RFC 8785 and verifies its Ed25519 signature against an
    embedded TrustedIssuerKeyStore before the orchestrator runs. The result is the ExecutionContract in
    spi.contract (preview), and every gate decision is recorded as ContractResolvedEvent, which now also
    carries keyId and developerLicence.
  • Each pinned key (exeris-prod-2026-k1, exeris-dev-2026-k1, exeris-ent-2026-k1) carries a scope: the
    environments it may entitle, a maximum validity, a workload ceiling and the class of artifact it may
    entitle. A scope breach is HARD and is reported as EX-LIC-0009 to EX-LIC-0013. exeris-root-2026-k1
    is no longer a trust root.
  • A declared EntitlementRequirement with no manifest stops the boot (EX-LIC-0005) in every environment.
    A kernel with no requirement on the classpath boots under the Community fallback.
  • EntitlementRequirement gains an abstract entitlementClass(); ExecutionEnvironment.requiresEntitlement()
    is renamed isProductionClass(). More than one license-manifest.json on the classpath stops the boot
    with EX-LIC-0001.
  • Under a developer key, and only when a requirement is declared, DeveloperWorkloadAdmission holds the
    kernel to 50 requests per second and 10 connections: a driver closes a refused connection, answers a
    refused request 429 with Retry-After: 1, and stamps Exeris-License: development on every final
    response. The mechanism is inert for every other contract (WorkloadAdmission.UNGATED).
  • Core: ContractBootstrapStep.run returns a ContractDecision; IssuerKeyResolver.resolve returns a
    TrustedIssuerKey; the scope types and LicenseManifestVerifier.verifyScoped are public with
    @since 0.13 so a tool that signs licences checks a manifest against the rules the kernel applies.
  • TCK: AbstractExecutionContractTck, AbstractLicenseManifestCryptoTck, AbstractEntitlementRequirementTck,
    AbstractWorkloadAdmissionTck and AbstractTransportWorkloadAdmissionTck.

Authentication: EdDSA (ADR-040 A1)

  • The Community OIDC validator installs a JWKS entry of type OKP on curve Ed25519 and verifies tokens
    whose header names EdDSA (or Ed25519) with the JDK's default provider; no dependency is added.
  • The key decides the algorithm: a header naming another algorithm than its key's is denied with
    EX-SEC-2002 before any signature is checked. ES*, PS* and Ed448 stay unsupported.
    AbstractSecurityProviderTck.PerKeyAlgorithmPinContract pins the rule.

Flow, events, graph and scheduling

  • Flow (ADR-013 A1). A finished saga keeps a COMPLETED row whenever a snapshot store is bound, and
    the engine no longer calls FlowSnapshotStore.delete. A resubmit or a choreography Start after a
    terminal-catalog eviction or an engine restart is absorbed as terminal; lookupParked returns empty and
    a wake is refused with NOT_PARKED. (#764) A Start for an instance the engine already holds is a
    no-op and emits the JFR event eu.exeris.kernel.flow.ChoreographyStartIgnored.
  • Events (ADR-101). EventDescriptor carries an isolationOrdinal, EventBus.subscribeScoped delivers
    only events published under the subscriber's isolation key, and the Kafka binding carries the ordinal in
    the exeris-isolation-ordinal header. The JDBC outbox and event log gain isolation_ordinal (migration
    V0.13.0__add_event_isolation_ordinal.sql). A publish under a bound but unregistered key is refused with
    EX-EVENT-6009. On a brokered bus a normal return from publish means the client accepted the record;
    a record the client rejects throws EX-EVENT-6009 (delivery-failed), and an asynchronous failure is
    recorded as KafkaPublishFailedEvent and counted in publishFailedTotal(). publishAndAwait still
    waits for the broker.
  • Graph (ADR-102, preview). A multi-hop path primitive (GraphPathSpec, traversePath,
    streamPathJson, buildPathQuery) runs as one statement or one query on Community. Every traversal
    honours the descriptor's direction; a traversal under an unscopable tenant context is refused before
    any I/O; a path-length bound above 64 is refused; findShortestPath(UUID, UUID) is deprecated for
    removal and throws EX-GRPH-5002. The SQL/PGQ deleteNode removes the node's connected edges (#468).
    The published Community churn-to-data contract is < 23x.
  • Scheduling (ADR-057 A1). A declared @Schedule job runs with no PrincipalContext, and no declaration
    passes the build-time refusal at 1.0, so @Schedule stays reserved.
  • Bootstrap (ADR-007 §5). KernelBootstrap.shutdown() and Builder#registerShutdownHook(boolean); a
    standalone boot() registers one JVM shutdown hook, so a SIGTERM runs the ordered stop instead of
    exiting without draining. A subsystem's initialize() is bounded by a 300-second deadline
    (EX-BOOT-0003; Builder#initializeDeadline(Duration)), and a second concurrent boot() on one
    instance throws IllegalStateException.
  • Native symbols. Core binds OPENSSL_cleanse as CoreOpenSslRuntime#cleanse(MemorySegment); no call
    site invokes it yet. AbstractAbiSymbolResolutionTck fails when a REQUIRED symbol does not resolve.

Build and tooling

  • Testcontainers 2.0.5. exeris-kernel-bom manages the testcontainers-* artifacts; no module has
    JUnit 4 on its test classpath. Surefire and Failsafe are on 3.6.0 with every execution selecting the
    classes it selected on 3.2.5 (#577).
  • The Central bundle is clean on Maven 3.10 (central-publishing-maven-plugin 0.12.0), and the release
    dry run builds it; tools/central-bundle-gate/central-bundle-gate.sh fails a malformed bundle.
  • central-verify verifies release candidates and skips tags that are not releases; spi-api-diff --history
    labels each transition with the stability configuration at its old ref.
  • The TLS matrix refuses a class that executed fewer tests than its floor
    (.github/scripts/tls-matrix-floor.sh).

Breaking changes and upgrade

Each entry below changes behaviour a consumer acts on, and the step is under the named heading of
MIGRATION.md. Eleven come from the changelog's ### Breaking section, which has
eighteen entries in all (the ones without a migration step are listed after the table); two, boot() registering a shutdown hook and a tenant publish needing a
registered key, are listed under ### Changed and carry a migration step as well.

Change MIGRATION.md heading
The reference policy raises when the tenant key is absent 0.12.x → 0.13 — the reference policy raises when the tenant key is absent (ADR-012 §4c.3)
The shared-scope reference policy pins the tag on write 0.12.x → 0.13 — the shared-scope reference policy pins the tag on write (ADR-012 §4c.2)
A role that bypasses RLS stops the boot 0.12.x → 0.13 — RLS deployments must not connect as a role that bypasses RLS (ADR-012 §4c.4)
write blocks, queueWrite never waits, TransportConfig gains a component 0.12.x → 0.13 — write blocks at the outbound bound, queueWrite never waits, TransportConfig gains a component (ADR-007, ADR-071)
A send to a peer that ended the stream throws the closed-stream signal 0.12.x → 0.13 — a send to a peer that ended the stream throws the closed-stream signal
Entitlement classes, a manifest in every environment, a developer licence 0.12.x → 0.13 — entitlement-requiring artifacts: a class, a manifest in every environment, a developer licence (ADR-088, ADR-089)
One licence manifest on the classpath 0.12.x → 0.13 — contract gate: one license manifest on the classpath (ADR-088)
A finished saga keeps its snapshot row 0.12.x → 0.13 — a finished saga keeps its snapshot row (ADR-013 A1)
boot() registers a shutdown hook 0.12.x → 0.13 — embedding hosts: disable the kernel's shutdown hook (ADR-007 §5)
A tenant publish needs a registered key 0.12.x → 0.13 — events: a tenant publish needs a registered key (ADR-101)
HTTP/2 header values arrive one char per octet 0.12.x → 0.13 — HTTP/2 header values reach handlers one char per octet (ADR-071)
JWKS use and alg are read 0.12.x → 0.13 — the Community OIDC validator reads each JWKS key's use and alg (ADR-040 A1)
Graph SPI methods, explicit shortest path, refused traversals 0.12.x → 0.13 — graph: multi-hop paths, explicit shortest path and refused traversals (ADR-102)

Breaking items the changelog lists without a separate migration section:

  • Preview SPI changes. EntitlementRequirement#entitlementClass() is abstract, and
    ExecutionEnvironment.requiresEntitlement() is isProductionClass().
  • Core. ContractBootstrapStep.run returns a ContractDecision, and IssuerKeyResolver.resolve returns
    a TrustedIssuerKey.
  • TCK bindings. AbstractSagaRecoveryTck gains createBoundedEngine(int); the provider TCKs need
    selectAmong(List); AbstractFailurePolicyTck needs bootCapturing; AbstractCryptoEngineTck needs
    bindToSocket unless honoursMinimumTlsVersion() returns false; AbstractTransportStreamTck,
    AbstractLicenseManifestCryptoTck and AbstractGracefulShutdownTck gain obligations described in their
    changelog entries. A binding that does not meet one fails the case instead of skipping it.

Known limitations and not covered

Taken from docs/ROADMAP.md and the changelog.

  • Licence contract. authorizedInstances is carried but not metered, and the workload envelope is
    enforced only under the developer licence. Offline revocation (BlockedManifestRegistry) is not
    implemented. The gate's cost against ADR-089's 5 ms threshold is not measured (#605).
  • Telemetry. No contract for events the kernel did not define: not started, no RFC. OTLP export and
    distributed tracing are not implemented.
  • Flow. Parallel steps (#584), a way to await a flow, and a step whose next step depends on its result
    (#582) are not started; none has an RFC. Field-level encryption and a principal session key (#585) are
    ruled in ADR-012's amendment and not implemented.
  • Streams. The carrier-pinning regression under N concurrent long-lived streams is not delivered, and a
    WebSocket emits engine start and stop events only.
  • Configuration. @Dynamic reload covers keys registered with KernelConfigRegistry; ConfigProvider.watch
    is a no-op on Community, and no ConfigChangeListener SPI exists.
  • HTTP client. One body codec binding, not two; the decode path takes Class<?> with no type-token
    overload.
  • HTTP limits. maxRequestBodyBytes, maxResponseBodyBytes, maxRequestHeaderCount and
    maxRequestHeaderSize are not asserted by a TCK case; the three HTTP/2 header keys are.
  • TLS. TLS 1.3 half-close is not supported. ES*, PS* and Ed448 tokens are not verified.
  • Native-image. Opt-in only. With Community's metadata deleted the sample image does not build (GraalVM
    25.0.2 stops on an internal compiler error in H2), so that module's path was not shown failing at run time.
  • Skip gates. A TCK contract a binding can decline by returning a null harness is not addressed.
  • Zeroization. No call site invokes CoreOpenSslRuntime#cleanse; the SensitiveBuffer SPI stays
    deferred with FIPS scope.
  • Bindings outside this repository. A transport, HTTP, persistence or crypto binding that binds a TCK
    suite changed in this release adopts its new cases when it moves to 0.13. Until then, HttpExchange
    peer addresses and the closed-stream type are reported only by Community.

Verification

Measured at the cut, 2026-10-28:

  • Full reactor at 0.13.0, mvn clean install on Temurin 25, with no eu.exeris artifact in the local
    repository so every module resolved from the reactor: BUILD SUCCESS, 0 failures.
  • The release branch's CI on its final milestone commit, 6228d3f, run
    40688077856: every job
    green — Build & TCK Verification, SPI Compatibility Gate, Persistence RLS/Interceptor Gate, Kafka
    Integration Gate, Recovery Continuity Gate, Transport Stress Gate, TLS OpenSSL 3.5.6 and TLS OpenSSL
    4.0.0. The per-job test reports are that run's artifacts.

How a release is judged:

  • A release is judged on the default build and the sequenced tagged gates of the release branch: the
    persistence RLS gate (the shared-scope and graph contract integration tests against PostgreSQL and
    Neo4j), the TLS matrix with its per-class executed-test floors, the Kafka integration gate, the SPI
    compatibility gate over the promoted packages, and the native-smoke job.
  • tools/spi-api-diff/spi-api-diff.sh compares two revisions of exeris-kernel-spi; its history page is
    spi-api-history.md.
  • The Central bundle is checked by tools/central-bundle-gate/central-bundle-gate.sh and the release
    workflow's dry run, which runs deploy -DskipUpload=true.