Merge branch 'feat/surf-event-bus' into feat/topology-redesign

Three conflicts, all where both branches had been working on the same RabbitMQ
consumer paths.

`RabbitConnectionProvider`: both sides added a different import. Kept both.

`RabbitConsumer.getChannel`: topology-redesign added the channel shutdown
listener and consumer recovery, and `createChannel` now takes the connection
generation; surf-event-bus had moved the blocking open onto `Dispatchers.IO`.
Kept the recovery machinery and wrapped its `createChannel(connectionGeneration)`
in `withContext(Dispatchers.IO)`, so the blocking AMQP round trip still leaves
the caller's dispatcher — the same reason `awaitOpen` hops to IO.

`RabbitListenerHandlerManager`: both branches fixed the same double-settle bug
in different ways. surf-event-bus guarded `settleWithRetry` with a `settled`
CAS; topology-redesign removed the race by construction, completing a
`CompletableDeferred` from `invokeOnCompletion` and racing it against the
response in a `select`, and added the `SurfRabbitConnectionException` requeue
and `CancellationException` branches. Took topology-redesign's structure and
routed its settlements through the CAS-guarded `settleWithRetry`, which the
already-merged tail of the same function calls too.

Verified: ./gradlew check -PrequireIntegration — 280 passed, 0 failed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ammodev

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - '**'
+      - '!version/*'
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: Build and test
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '25'
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+        with:
+          cache-read-only: ${{ github.ref != 'refs/heads/version/1.21.11' }}
+
+      # ubuntu-latest ships a running Docker daemon, so the integration tag must not be
+      # skipped here. -PrequireIntegration turns DockerAvailableCondition from "skip" into
+      # "fail", which is the whole point of running these on CI: a silent skip reports green
+      # while verifying nothing.
+      - name: Verify Docker is available
+        run: docker info
+
+      - name: Check
+        run: ./gradlew check -PrequireIntegration --stacktrace --no-daemon
+
+      - name: Upload test reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-reports
+          path: |
+            **/build/reports/tests/
+            **/build/test-results/
+          retention-days: 7
+          if-no-files-found: ignore

docker-compose.yml

@@ -0,0 +1,45 @@
+# Local development brokers for surf-eventbus.
+#
+# The integration test suite does NOT use this file — it starts its own throwaway containers
+# through Testcontainers. This is for running a real application against the bus by hand, and
+# for poking at the broker while debugging a failing suite.
+#
+#   docker compose up -d
+#   RabbitMQ management UI: http://localhost:15672  (surf / surf)
+#
+# The credentials below match the defaults in docs/development.md. They are deliberately weak;
+# nothing here should ever be exposed outside localhost.
+
+services:
+  rabbitmq:
+    image: rabbitmq:4-management
+    container_name: surf-eventbus-rabbitmq
+    ports:
+      - "5672:5672"
+      - "15672:15672"
+    environment:
+      RABBITMQ_DEFAULT_USER: surf
+      RABBITMQ_DEFAULT_PASS: surf
+      RABBITMQ_DEFAULT_VHOST: /
+    healthcheck:
+      test: [ "CMD", "rabbitmq-diagnostics", "-q", "ping" ]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    volumes:
+      - rabbitmq-data:/var/lib/rabbitmq
+
+  redis:
+    image: redis:7-alpine
+    container_name: surf-eventbus-redis
+    ports:
+      - "6379:6379"
+    command: [ "redis-server", "--requirepass", "surf", "--appendonly", "no" ]
+    healthcheck:
+      test: [ "CMD", "redis-cli", "-a", "surf", "ping" ]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  rabbitmq-data:

docs/audit-2026-08-01-repository.md

@@ -0,0 +1,110 @@
+# Developing surf-eventbus
+
+Everything you need to build, test and run the bus locally.
+
+## Prerequisites
+
+| Tool | Version | Notes |
+|---|---|---|
+| JDK | 25 | The toolchain targets class-file major 69. CI uses Temurin 25. |
+| Docker | any recent | Required for the integration suite. Without it those tests **skip**. |
+| Gradle | — | Use the wrapper (`./gradlew`); it pins 9.6.1. |
+
+## Building
+
+```bash
+./gradlew build          # compile + test + ABI check
+./gradlew check          # everything CI runs
+./gradlew assemble       # jars only, no tests
+```
+
+## Running the tests
+
+```bash
+./gradlew check                        # the full suite, including integration tests
+./gradlew check -PskipIntegration      # skip everything that needs Docker
+./gradlew check -PrequireIntegration   # fail (don't skip) if Docker is missing — what CI does
+./gradlew lincheckTest                 # the concurrency tests, excluded from `test` by default
+```
+
+### About `-PrequireIntegration`
+
+Integration tests are tagged `integration` and guarded by `DockerAvailableCondition`. Without a
+Docker daemon they report *"integration test skipped, NOT verified"* and the build still goes
+green. That is a reasonable default on a laptop and a dangerous one on CI, so
+`.github/workflows/ci.yml` passes `-PrequireIntegration`, which turns the skip into a failure.
+
+Pass at most one of `-PskipIntegration` / `-PrequireIntegration`; the build rejects both together.
+
+The integration suite starts its own throwaway containers via Testcontainers. It does **not** use
+`docker-compose.yml` and does not need the brokers below to be running.
+
+## Running brokers locally
+
+For driving a real application against the bus by hand:
+
+```bash
+docker compose up -d       # rabbitmq:4-management on 5672/15672, redis:7 on 6379
+docker compose down -v     # tear down, including the rabbit volume
+```
+
+| Service | Address | Credentials |
+|---|---|---|
+| RabbitMQ | `localhost:5672` | `surf` / `surf`, vhost `/` |
+| RabbitMQ management UI | http://localhost:15672 | `surf` / `surf` |
+| Redis | `localhost:6379` | password `surf` |
+
+These credentials are deliberately trivial. Do not expose the compose stack beyond localhost.
+
+## Pointing the bus at them
+
+Configuration resolves per field as `env > plugin yaml > global yaml > built-in default`
+(`EventBusConfigResolver`). The quickest local route is the environment:
+
+```bash
+export SURF_EVENTBUS_RABBITMQ_HOST=localhost
+export SURF_EVENTBUS_RABBITMQ_PORT=5672
+export SURF_EVENTBUS_RABBITMQ_USERNAME=surf
+export SURF_EVENTBUS_RABBITMQ_PASSWORD=surf
+export SURF_EVENTBUS_RABBITMQ_VHOST=/
+
+export SURF_EVENTBUS_REDIS_HOST=localhost
+export SURF_EVENTBUS_REDIS_PORT=6379
+export SURF_EVENTBUS_REDIS_PASSWORD=surf
+```
+
+The yaml layers are `eventbus.yml` (global, next to the platform plugin's data folder) and
+`eventbus-plugin.yml` (per consuming plugin, in that plugin's own folder). Both are generated
+full of sentinels on first run and override nothing until edited.
+
+Two chunking flags additionally honour JVM system properties as a last resort before the built-in
+default — `surf.rabbitmq.outgoingRequestChunkingEnabled` and
+`surf.rabbitmq.outgoingResponseChunkingEnabled`. They are the only fields with this extra layer.
+
+## Module layout
+
+| Module | Contains |
+|---|---|
+| `surf-eventbus-api` | Public surface: `SurfEventBus`, annotations, config, codecs, ABI dump |
+| `surf-eventbus-core` | Implementations: dispatchers, RabbitMQ and Redis transports, retry, audit |
+| `surf-eventbus-ksp` | The `@RpcService` / `@QueryService` descriptor generator |
+| `surf-eventbus-platform` | Paper, Velocity and standalone bootstrap |
+
+## The ABI check
+
+`surf-eventbus-api` has a frozen ABI dump at `surf-eventbus-api/api/surf-eventbus-api.api`. Any
+change to the public surface fails `check` until the dump is regenerated:
+
+```bash
+./gradlew :surf-eventbus-api:checkKotlinAbi    # what `check` runs
+./gradlew :surf-eventbus-api:updateKotlinAbi   # regenerate, then review the diff before committing
+```
+
+Review that diff. It is the only automated guard against accidentally publishing an
+implementation type.
+
+## Benchmarks
+
+```bash
+./gradlew :surf-eventbus-core:jmh
+```

docs/development.md

@@ -111,6 +111,23 @@ Wire format and API both changed. A 1.6.x service and a 2.0 service cannot talk
 
 Stop everything, upgrade, start everything. There is no rolling upgrade path.
 
+Two identifiers that are *not* obvious from the API also changed, and both fail silently rather
+than loudly if a straggler is left running:
+
+| What | 1.6.x | 2.0 | If a 1.6.x process is still running |
+|---|---|---|---|
+| AMQP version header | `x-surf-rabbitmq-version` | `x-surf-eventbus-version` | Peers read each other as an unknown version, so version-gated behaviour is off. Degrades, does not crash. |
+| Redis sync key prefix | `surf-redis:sync:` | `surf.eventbus.sync:` | The two run **disjoint copies** of every `SyncMap`/`SyncSet`/`SyncList`/`SyncValue`. No error; the data simply diverges. |
+
+The sync prefix is the dangerous one: nothing anywhere reports that two halves of the fleet are
+maintaining separate state. There is no migration for existing keys — a sync structure is a
+cache of authoritative state elsewhere, so the intended procedure is to let the old keys expire
+rather than rewrite them. If some structure in your deployment is *not* reconstructible, copy
+those keys across before starting 2.0.
+
+Both constants are pinned by `WireConstantsTest`, so a later accidental rename fails the build
+rather than the fleet.
+
 ---
 
 ## Checklist
@@ -121,4 +138,6 @@ Stop everything, upgrade, start everything. There is no rolling upgrade path.
 - [ ] every `surf.service.*` queue deleted, or the vhost recreated
 - [ ] old `surf-rabbitmq-*` and surf-redis plugins removed from every server
 - [ ] all services stopped, upgraded, and started together
+- [ ] no 1.6.x process left running against the same Redis (silent sync-structure split)
+- [ ] any non-reconstructible `surf-redis:sync:*` keys copied to `surf.eventbus.sync:*`
 - [ ] someone knows the audit trail is best effort until its writer ships