[v0.10.0-rc1] Request Cancellation

AGENTS.md

@@ -17,6 +17,15 @@ Main modules:
 
 - Minimal supported Java version is 8.
 - Follow `docs/ai-review.md` for compatibility, breaking-change, and review instructions.
+- Follow `AI_POLICY.md`: take the same responsibility for generated code as hand-written code, don't
+  submit code you don't understand, and respect licensing when reproducing any external code.
+
+## When to pause and ask
+
+- Before implementing a new feature, a large behavior change, or anything touching public API,
+  configuration, protocol handling, serialization, or JDBC/R2DBC behavior: check whether an approved
+  issue or proposal already covers it. If not, say so and ask before implementing instead of proceeding silently — see `CONTRIBUTING.md`.
+- Do not modify CI workflow files (`.github/workflows/**`). CI changes are restricted; raise it with the user first.
 
 ## Setup and test commands
 
@@ -29,6 +38,11 @@ Prefer targeted Maven commands over full-repo runs.
 - `mvn -pl jdbc-v2 test`
 - `mvn -pl clickhouse-data test`
 
+Also compile examples or packaging modules (e.g. `packages/clickhouse-jdbc-all`) when a change affects examples, packaging, public APIs, or other user-facing behavior — running the touched module's tests alone isn't enough.
+
+Run benchmarks under `clickhouse-benchmark` when a change touches a performance-sensitive path (see
+`docs/ai-review.md`); this is optional and only worth doing when performance is actually in question.
+
 Avoid broad dependency, formatting, or unrelated cleanup churn unless required by the task.
 
 ## Editing expectations
@@ -37,10 +51,40 @@ Avoid broad dependency, formatting, or unrelated cleanup churn unless required b
 - Read nearby code and follow existing local patterns before introducing new abstractions.
 - Prefer focused tests near the affected module over repo-wide runs.
 
+## Scope discipline
+
+- One logical change per commit/PR: a feature, a bug fix, a refactor, or a doc update. Don't mix.
+- Implement the smallest change that solves the problem. Defer polish, extra configuration, and
+  optimization to follow-ups rather than expanding scope.
+- Flag it if a change is growing large: ~400 LOC starts to hurt reviewability, 800+ LOC needs to be
+  split into smaller changes.
+
+## Testing expectations
+
+- Add negative tests when a change affects validation, error handling, parsing, serialization, or
+  compatibility-sensitive behavior. The test should prove the failure path produces the correct
+  result/exception, not just that the original bug no longer reproduces.
+- Don't pad coverage: add a test only when it covers a distinct scenario, edge case, module, type,
+  format, or failure mode. Avoid duplicating existing coverage.
+- Favor scenario coverage (boundary values, invalid input, nullable/nested interactions) over raw
+  coverage percentage.
+- Keep tests compact, readable, and focused on the scenario being verified. Reduce duplication in test setup and assertions so a reviewer can quickly see what behavior is being tested.
+
+## Closeout checklist
+
+- Run the affected module's tests locally (see "Setup and test commands") before treating a change as done. Don't hand off a change with failing or unrun tests.
+- Update `CHANGELOG.md` for user-facing changes: what the problem was, how it was fixed, and a link to the issue.
+- Update `docs/features.md` when a `client-v2` or `jdbc-v2` feature is added, removed, or its behavior intentionally changes.
+- In the final summary: state compatibility impact explicitly, describe any user-visible behavior
+  change, and link the related issue (note that one should be created if it's missing).
+
 ## Review expectations
 
 For review requests, follow `docs/ai-review.md` as the shared review standard across AI agents.
 
+Before treating implementation work as done, self-review your own diff against `docs/ai-review.md` —
+not only when a review is explicitly requested.
+
 ## Optional nested AGENTS.md
 
 If a module develops its own conventions, add a nested `AGENTS.md` inside that module.

CHANGELOG.md

@@ -46,6 +46,17 @@
   previously set in milliseconds but mistakenly retrieved and used in seconds in some places. Now it correctly uses
   milliseconds consistently. (https://github.com/ClickHouse/clickhouse-java/issues/2358)
 
+- **[client-v2]** HTTP `503 Service Unavailable` responses are now surfaced as a connection-style failure (
+  `java.net.ConnectException`) and are retried by default. Previously a `503` was treated as a server error (
+  `ServerException`) and fell under the `ServerRetryable` fault cause. It has been moved to the `ConnectTimeout` fault
+  cause category so that connectivity/availability failures are handled uniformly with other connection errors. Callers
+  that specifically excluded `ServerRetryable` to avoid retrying `503` should now adjust their
+  `client_retry_on_failures` configuration to exclude `ConnectTimeout` instead.
+
+- **[client-v2]** Unexpected/unknown HTTP status codes (those the client cannot interpret as a ClickHouse response) now
+  throw a `ClientException` instead of a `ServerException`. Since the client cannot meaningfully handle these responses,
+  they are reported as a client-side error rather than being attributed to the server.
+
 ### New Features
 
 - **[jdbc-v2, client-v2]** Implemented SSL modes configuration. Now it is possible to set `ssl_mode` to `DISABLED`, 
@@ -101,6 +112,12 @@
   supported but will be removed. Please migrate to the new property. 
   (https://github.com/ClickHouse/clickhouse-java/issues/2858)
 
+- **[client-v2]** Added `Client#cancelTransportRequest(String queryId)` to cancel an in-flight request that has not yet
+  received a response from the server, identified by the query id supplied in the operation settings. This aborts the
+  request on the client side (cancels the underlying IO operation) but does **not** issue a `KILL QUERY` on the server,
+  so a query that already started executing may continue to run server-side. It is recommended to use operation timeout
+  settings where possible; this API is intended for explicitly aborting a request from the client.
+
 ### Improvements 
 
 - **[jdbc-v2, client-v2]** Added support of hostnames with underscore (`_`) in them. Now it is possible to specify endpoint 

CONTRIBUTING.md

@@ -45,10 +45,9 @@ We all know that large PRs (400+ lines of code) are hard to review and it is mor
 
 For a new feature, implement the smallest change that solves the problem. Polish, additional configuration, optimization, and extensions can be addressed in the follow-up PRs. 
 
-For self and AI review use following guids:
+For self and AI review use following guides:
 - `docs/ai-review.md`
 - `docs/changes_checklist.md`
-- `docs/highlevel-changes-checklist.md`
 - `docs/features.md` for changes that touch `client-v2` or `jdbc-v2`
 
 ### Testing Expectations