Merge remote-tracking branch 'origin/main' into build/publishing-convention-plugin

# Conflicts:
#	gradle.properties

Author: OmarAlJarrah

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+# Run the full Gradle build on every pull request and on pushes to main.
+# `./gradlew build` runs the complete quality gate: tests, ktlint, detekt,
+# apiCheck (binary-compatibility), explicit-API strict mode, allWarningsAsErrors,
+# and the aggregate 80% Kover line-coverage floor.
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+# Cancel superseded runs on the same ref so only the latest commit of a branch/PR builds.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          # The styleguide directory is a git submodule; fetch it so the working tree matches local checkouts.
+          submodules: recursive
+
+      # Install a single Temurin JDK 21. The build's Gradle daemon runs on this JVM, and the
+      # foojay-resolver-convention plugin (settings.gradle.kts) auto-provisions the JDK 8 and
+      # JDK 11 toolchains the Java-8 and JDK-11 modules require. JDK 21 also satisfies the
+      # virtual-threads module's toolchain. JDK 21 (rather than the newest LTS) is deliberate:
+      # detekt 1.23.x crashes on JDK 25+, so keeping the daemon on 21 keeps the detekt gate green.
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+
+      # Built-in Gradle dependency and build caching, plus wrapper validation.
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Build
+        run: ./gradlew build

AUDIT.md

@@ -85,9 +85,12 @@ Layered, from the bottom up:
 
 - **Java 8 bytecode everywhere except** `sdk-transport-jdkhttp` (11) and `sdk-async-virtualthreads` (21).
   Avoid `InputStream.transferTo` (9+), `Thread.threadId()` (19+), records, sealed `permits` in Java-8
-  modules. A module that genuinely needs a newer JDK must override **both** `jvmToolchain(N)` **and**
+  modules. A module that genuinely needs a newer JDK must override **all three** of `jvmToolchain(N)`,
+  the `java { sourceCompatibility / targetCompatibility = VERSION_N + toolchain }` block, and
   `compilerOptions { jvmTarget.set(JvmTarget.JVM_N) }` in its own build script — overriding only the
-  toolchain produces Java-8-format bytecode referencing newer stdlib symbols (`NoSuchMethodError` on JDK 8).
+  toolchain produces Java-8-format bytecode referencing newer stdlib symbols (`NoSuchMethodError` on JDK 8),
+  and omitting the `java {}` block trips Gradle's `compileJava`/`compileKotlin` JVM-target validation. See
+  `docs/architecture.md` (Cross-Compile Toolchain Discipline).
 - **MIT license header in every source file.** Each `.kt`, `.java`, and `.kts` file starts with the 6-line
   `Copyright (c) 2026 dexpace and Omar Aljarrah` / `SPDX-License-Identifier: MIT` block — copy it from any
   existing file when creating new ones. Nothing enforces this automatically; it is a review convention.

CLAUDE.md

@@ -7,6 +7,7 @@
 
 <h1 align="center">Java SDKs Platform</h1>
 
+[![CI](https://github.com/dexpace/java-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/dexpace/java-sdk/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Kotlin](https://img.shields.io/badge/kotlin-2.3.21-7F52FF.svg?logo=kotlin&logoColor=white)](https://kotlinlang.org)
 ![JDK](https://img.shields.io/badge/JDK-8%2B-437291.svg?logo=openjdk&logoColor=white)
@@ -246,25 +247,28 @@ See [docs/pipelines.md](docs/pipelines.md) for the step-author walkthrough.
 |---|---|
 | `client` | `HttpClient`, `AsyncHttpClient` — the two transport SPIs (sync and async). |
 | `http.request` | `Request`, `RequestBody`, `FileRequestBody`, `LoggableRequestBody`, `Method`. |
-| `http.response` | `Response`, `ResponseBody`, `LoggableResponseBody`, `Status` (a value-carrying class with a total `fromCode`), `HttpResponseException`. |
-| `http.response.exception` | Typed `HttpException` hierarchy (`BadRequestException`, `RequestTimeoutException`, `TooManyRequestsException`, `ServiceUnavailableException`, …) with `retryable` derived from `RetryUtils.isRetryable`, plus `NetworkException` and `HttpExceptionFactory`. |
+| `http.response` | `Response`, `ResponseBody`, `LoggableResponseBody`, `Status` (a value-carrying class with a total `fromCode`), plus the raw-vs-parsed seam: `ResponseHandler<T>` (with dep-free `string()`/`empty()` handlers) and a lazy, parse-once `ParsedResponse<T>`. |
+| `http.response.exception` | Typed `HttpException` hierarchy (`BadRequestException`, `RequestTimeoutException`, `TooManyRequestsException`, `ServiceUnavailableException`, …) with `isRetryable` derived from `RetryUtils.isRetryable` and exposed via the `Retryable` interface, plus `NetworkException` and `HttpExceptionFactory`. |
 | `http.common` | `Headers`, `HttpHeaderName` (interned), `MediaType`, `Protocol`, `HttpRange`, `ETag`, `RequestConditions`. |
 | `http.context` | `CallContext` → `DispatchContext` → `RequestContext` → `ExchangeContext` chain, `ContextStore`. |
 | `http.pipeline` | Sync (`HttpStep` / `HttpPipeline` / `HttpPipelineBuilder` / `PipelineNext` / `Stage`) and async (`AsyncHttpStep` / `AsyncHttpPipeline` / `AsyncHttpPipelineBuilder` / `AsyncPipelineNext`) pipeline machinery, plus `AsyncPipelineBridges`. |
 | `http.pipeline.steps` | Concrete steps: `RetryStep`, `RedirectStep`, `AuthStep`, `KeyCredentialAuthStep`, `BearerTokenAuthStep`, `InstrumentationStep`, `SetDateStep`, and their `*Options` / `*Condition` types. |
 | `http.auth` | `Credential` sealed hierarchy (`KeyCredential`, `NamedKeyCredential`, `BearerToken`), `BearerTokenProvider`, `AuthScheme`, `AuthMetadata`, RFC 7235 challenge parser, `BasicChallengeHandler`, `DigestChallengeHandler`, `CompositeChallengeHandler`. |
 | `http.sse` | `ServerSentEventReader` (WHATWG spec), `ServerSentEvent`, `ServerSentEventListener`, `BufferedSource.readServerSentEvents()`. |
 | `http.paging` | `PagedIterable<T>`, `PagedResponse<T>`, `PagingOptions` with `byPage()` and `stream()` accessors. |
-| `pagination` | `Paginator<T>` (with a `maxPages` safety cap) over cursor / page-number / token / link-header `PaginationStrategy` implementations, plus `Page<T>` / `SimplePage<T>`. |
+| `pagination` | `Paginator<T>` (with a `maxPages` safety cap) over cursor / page-number / link-header `PaginationStrategy` implementations, plus `Page<T>` / `SimplePage<T>`. Token-style APIs use `CursorPaginationStrategy` with the query-param name set (e.g. `"page_token"`). |
 | `pipeline` | Recovery-aware primitives: `RequestPipeline`, `ResponsePipeline`, `ExecutionPipeline` over a sealed `ResponseOutcome`, with steps (`pipeline.step`, `pipeline.step.retry`) like `RetryStep`, `ResponseRecoveryStep`, `IdempotencyKeyStep`, `ClientIdentityStep`. |
-| `serde` | `Serde`, `Serializer`, `Deserializer` abstractions and `Tristate<T>` (absent / null / present). |
+| `serde` | `Serde`, `Serializer`, `Deserializer` abstractions, `Tristate<T>` (absent / null / present), and `SerdeException` (the unchecked failure adapters translate codec errors into). |
 | `io` | `Source`, `Sink`, `Buffer`, `BufferedSource`, `BufferedSink`, `IoProvider`, `Io`, `TeeSink`. |
 | `instrumentation` | `ClientLogger` (zero-alloc disabled path), `LoggingEvent`, `UrlRedactor`, `Tracer` / `NoopTracer`, `Span` / `NoopSpan`, `InstrumentationContext`. |
 | `instrumentation.metrics` | `Meter`, `LongCounter`, `DoubleHistogram`, `NoopMeter`. |
 | `config` | `Configuration` (system-property + env-var layered lookup), `ConfigurationBuilder`. |
 | `util` | `Clock`, `Uuids` (non-blocking v4), `DateTimeRfc1123`, `RetryUtils`, `ProxyOptions`, `Futures`. |
 | `generics` | `Builder<T>` — the generic builder interface every SDK builder implements. |
 
+Token-style APIs (`next_page_token`, `pageToken`, …) are served by `CursorPaginationStrategy`:
+construct it with the desired query-param name, e.g. `CursorPaginationStrategy(items, extractor, "page_token")`.
+
 ## Building
 
 ```bash

README.md

@@ -26,6 +26,7 @@ concerns.
 - [Cross-Cutting Design Decisions](#cross-cutting-design-decisions)
     - [Zero Dependencies](#zero-dependencies)
     - [JDK 8 Compatibility](#jdk-8-compatibility)
+    - [Cross-Compile Toolchain Discipline](#cross-compile-toolchain-discipline)
     - [Immutability and Builders](#immutability-and-builders)
     - [Virtual Thread Safety](#virtual-thread-safety)
     - [Internal Visibility](#internal-visibility)
@@ -271,6 +272,10 @@ Shipped pillar/step implementations live in `http.pipeline.steps`: `DefaultRedir
 `DefaultRetryStep`, `AuthStep` (+ `BearerTokenAuthStep` / `KeyCredentialAuthStep`),
 `DefaultInstrumentationStep`, and the redirect/retry option types.
 
+For why this layer uses ordered stages with pillar-uniqueness rather than nested `HttpClient`
+decorators — and the one cost that buys (the `next.copy()` re-drive contract) — see
+[Pipeline Mechanism](pipelines.md#why-ordered-stages-not-nested-decorators).
+
 #### Recovery-aware primitives (`org.dexpace.sdk.core.pipeline`)
 
 A lower-level layer that threads a sealed `ResponseOutcome` so recovery steps observe and
@@ -346,9 +351,12 @@ Two complementary surfaces for walking multi-page responses.
 |-----------------------------------------------------------------|-----------------------------------------------------------------------|
 | `Paginator<T>`                                                  | Lazily iterates pages by re-issuing requests through an `HttpClient`; carries a `maxPages` safety cap |
 | `PaginationStrategy<T>`                                         | Computes the next-page request (or stops) from the current page       |
-| `CursorPaginationStrategy` / `PageNumberPaginationStrategy` / `TokenPaginationStrategy` / `LinkHeaderPaginationStrategy` | The four shipped strategies |
+| `CursorPaginationStrategy` / `PageNumberPaginationStrategy` / `LinkHeaderPaginationStrategy` | The shipped strategies |
 | `PagedIterable<T>`                                              | First/next-page fetcher abstraction over `PagedResponse`, with its own `maxPages` cap |
 
+Token-style APIs (`next_page_token`, `pageToken`, …) are handled by `CursorPaginationStrategy`
+constructed with the query-param name set (e.g. `"page_token"`), so no separate token strategy is needed.
+
 ### Serialization
 
 **Package**: `org.dexpace.sdk.core.serde`
@@ -505,6 +513,58 @@ All code targets Java 8 bytecode (`jvmTarget = "1.8"`). Specific implications:
 - `ReentrantLock` (Java 5+) replaces `synchronized` for future-proofing with virtual threads
 - No `java.net.http.HttpClient` (Java 11+); the `HttpClient` interface is transport-agnostic
 
+### Cross-Compile Toolchain Discipline
+
+Most modules compile against Java 8 bytecode, but two need a newer JDK: `sdk-transport-jdkhttp`
+targets 11 (`java.net.http.HttpClient` was finalised in JEP 321) and `sdk-async-virtualthreads`
+targets 21 (virtual threads). Each of those modules raises its target by overriding **three**
+things in its own build script:
+
+```kotlin
+kotlin {
+    jvmToolchain(21)                       // which JDK compiles the module
+}
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_21   // Java-source level
+    targetCompatibility = JavaVersion.VERSION_21   // bytecode version `compileJava` emits
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(21))
+    }
+}
+
+tasks.withType<KotlinCompile>().configureEach {
+    compilerOptions {
+        jvmTarget.set(JvmTarget.JVM_21)    // bytecode version `compileKotlin` emits
+    }
+}
+```
+
+(`sdk-transport-jdkhttp` does the same with `11`/`VERSION_11`/`JVM_11`.) **All three** overrides
+are mandatory. The `java {}` block governs `compileJava` and keeps Gradle's JVM-target validation
+between `compileJava` and `compileKotlin` happy; a module that sets only the Kotlin toolchain and
+`jvmTarget` but omits the `java {}` block will trip that validation or compile its Java sources at
+the wrong level.
+
+The root build registers a `plugins.withId("org.jetbrains.kotlin.jvm")` callback that sets
+`jvmTarget` to `JVM_1_8` for every Kotlin module by default. A module that bumps only the
+toolchain — say to JDK 21 — but leaves `jvmTarget` at the inherited `1.8` will compile *against*
+the JDK 21 standard library while *emitting* Java-8-format class files. The result links fine on
+the build machine but references methods that do not exist on a Java 8 runtime, so a downstream
+Java 8 consumer fails at call time with `NoSuchMethodError`. Setting `jvmTarget` to match the
+toolchain makes the Kotlin compiler reject newer-than-target stdlib references at compile time
+instead, turning that runtime failure into a build error.
+
+This per-module override is the current, deliberately safe arrangement. The discipline matters
+under a hypothetical future consolidation onto a single newer toolchain (for build speed, or to
+sidestep the detekt-1.23.x crash on JDK 25+). If every module were compiled by, say, JDK 17 while
+the Java-8-target modules kept `jvmTarget = JVM_1_8`, those modules would again be compiling
+against a newer stdlib than they emit bytecode for. Guarding that arrangement requires a
+`--release 8` / `-Xjdk-release=8` flag on the Java-8-target modules so the compiler bounds the
+*visible* API to Java 8, not just the bytecode version. As long as each module that needs a newer
+runtime carries its own matched `jvmToolchain` + `jvmTarget` pair, no `--release` guard is needed;
+adopt one only if the toolchain is ever unified.
+
 ### Immutability and Builders
 
 All HTTP model classes follow the same pattern:
@@ -575,8 +635,8 @@ responds in a uniform way:
    subsequent blocking call also surfaces it.
 3. Throws `InterruptedIOException` (or the operation's natural failure exception with
    `InterruptedException` added as a suppressed cause).
-4. Classifies the interruption as **non-retryable** — `HttpResponseException.isRetryable`
-   returns `false` for an interrupt-driven failure.
+4. Classifies the interruption as **non-retryable** — an interrupt-driven failure is not a
+   `Retryable` condition, so the retry step never re-issues it.
 
 Loops bounded by user input (retry attempts, paged iteration, server-sent-event
 consumption, drain loops in body logging) check `Thread.currentThread().isInterrupted` at
@@ -653,8 +713,8 @@ they should construct a fresh one.
 |----------------------|-------------------------------------------------------------------------------------------------|
 | `io`                 | Source, Sink, BufferedSource, BufferedSink, Buffer, IoProvider, Io, TeeSink (internal)          |
 | `http.request`       | Request, RequestBody, FileRequestBody, LoggableRequestBody, Method                              |
-| `http.response`      | Response, ResponseBody, LoggableResponseBody, Status, HttpResponseException                     |
-| `http.response.exception` | HttpException, HttpExceptionFactory, RequestTimeoutException (and siblings), NetworkException |
+| `http.response`      | Response, ResponseBody, LoggableResponseBody, Status                                            |
+| `http.response.exception` | HttpException, HttpExceptionFactory, Retryable, RequestTimeoutException (and siblings), NetworkException |
 | `http.common`        | Headers, MediaType, CommonMediaTypes, Protocol, ETag, HttpRange, RequestConditions             |
 | `http.auth`          | Credential, KeyCredential, BearerToken, ChallengeHandler, Basic/Digest/CompositeChallengeHandler, AuthChallengeParser |
 | `http.context`       | CallContext, DispatchContext, RequestContext, ExchangeContext, ContextStore                     |

docs/architecture.md

@@ -14,6 +14,7 @@ and the concurrency decisions behind them.
     - [Architecture](#architecture)
     - [LoggableRequestBody — Tee-Write Strategy](#loggablerequestbody--tee-write-strategy)
     - [LoggableResponseBody — Drain-Once Strategy](#loggableresponsebody--drain-once-strategy)
+    - [Logged body size vs. the body the consumer receives](#logged-body-size-vs-the-body-the-consumer-receives)
     - [Reading a Snapshot](#reading-a-snapshot)
 - [Internal Stream Utilities](#internal-stream-utilities)
 - [Concurrency Design](#concurrency-design)
@@ -240,6 +241,45 @@ retains whatever bytes were read before the failure and caches the exception:
   post-mortem logging that records "what we got" alongside the exception.
 - `captureException` surfaces the cached exception (or `null`) without triggering a drain.
 
+### Logged body size vs. the body the consumer receives
+
+When `HttpLogLevel.BODY_AND_HEADERS` is enabled, the instrumentation step
+(`DefaultInstrumentationStep` / `DefaultAsyncInstrumentationStep`) wraps the response body in a
+`LoggableResponseBody` bounded to `HttpInstrumentationOptions.bodyPreviewMaxBytes` (default
+8 KiB, `DEFAULT_BODY_PREVIEW_MAX_BYTES`). Two consequences follow that are easy to miss when
+reading the logs:
+
+**1. The body delivered downstream can be larger than the logged preview.** The cap bounds only
+the in-memory *capture*, not the body. For a response larger than `bodyPreviewMaxBytes`, the
+step buffers the preview prefix and the wrapper then streams the full body to the consumer — it
+replays the captured prefix and continues from the live tail (see the bounded-capture diagram
+above). The preview you see in the log is a prefix; the consumer still reads every byte.
+
+**2. The logged size fields measure different things.** The step emits two size-related fields
+on the `http.response` event, and they are not the same number for an over-cap body:
+
+| Field                     | Source                                       | What it reports                                                                 |
+|---------------------------|----------------------------------------------|---------------------------------------------------------------------------------|
+| `response.body.size`      | `loggableBody.snapshot(bodyPreviewMaxBytes)` | Size of the **captured preview** — bounded by `bodyPreviewMaxBytes`             |
+| `response.body.preview`   | the same captured bytes, decoded as UTF-8    | The preview text (a prefix for an over-cap body)                                |
+| `response.content.length` | `response.body.contentLength()`              | The body's **true** length when the origin declared one (`Content-Length`); `-1` for unknown-length / streaming bodies |
+
+So `response.body.size` is the *captured/preview* size, **not** necessarily the full body size.
+When a body exceeds the cap, `response.body.size` saturates near `bodyPreviewMaxBytes` while
+`response.content.length` still shows the real length. Read `content.length` (not
+`body.size`) when you need the full size, and treat `body.preview` as a prefix that may be
+truncated. The two agree only when the whole body fit within the cap — exactly the case where
+`contentLength()` itself returns the captured size (see **`contentLength()`** above).
+
+**Streaming / unknown-length bodies (async path).** `DefaultAsyncInstrumentationStep` skips the
+capture entirely when `contentLength() < 0`, because the bounded drain would run on the
+future-completion thread and a slow producer could stall it. Such bodies stream to the consumer
+unwrapped, so they carry **no** `response.body.size` / `response.body.preview` fields at all —
+absence of those fields is expected for chunked or streaming responses, not a logging bug. The
+synchronous `DefaultInstrumentationStep` drains known-length and unknown-length bodies alike (it
+runs on the caller's thread), but the size-vs-preview distinction above applies to it just the
+same.
+
 ### Reading a Snapshot
 
 The only logging output is a raw `ByteArray`: