Merge pull request #76 from runcycles/release/v0.1.25.3

feat: v0.1.25.3 — extended runtime event emission

Author: amavashev

AUDIT.md

@@ -6,6 +6,44 @@
 
 ---
 
+### 2026-04-03 — v0.1.25.3: Extended runtime event emission + PROTOCOL_VERSION fix
+
+**Version bump:** 0.1.25.1 → 0.1.25.3 (0.1.25.2 was the case-insensitive scope fix below).
+
+**Fix:** `Enums.PROTOCOL_VERSION` was hardcoded to `"0.1.24"` — updated to `"0.1.25"` to match the current protocol spec.
+
+**New runtime event emissions (protocol spec v0.1.25 Webhook Event Guidance):**
+
+Added 4 new event types emitted from Java controllers (non-blocking, async via `EventEmitterService`):
+
+| Event Type | Detection | Emit Location |
+|---|---|---|
+| `budget.exhausted` | `remaining.amount == 0` in any post-operation balance | ReservationController (reserve, commit), EventController |
+| `budget.over_limit_entered` | `is_over_limit == true` in any post-operation balance | ReservationController (reserve, commit), EventController |
+| `budget.debt_incurred` | `debt.amount > 0` in any post-operation balance | ReservationController (reserve, commit), EventController |
+| `reservation.expired` | Expiry sweeper Lua returns `EXPIRED` status | ReservationExpiryService (post-expire HGETALL for tenant/scope context) |
+
+**Implementation approach:**
+- `EventEmitterService.emitBalanceEvents()` — new helper that inspects post-operation balances returned from Lua scripts. Called from ReservationController (after reserve and commit) and EventController (after event creation). No extra Redis calls — uses balances already on the response.
+- `ReservationExpiryService.emitExpiredEvent()` — after expire.lua succeeds, fetches the reservation hash (1 HGETALL) to get tenant_id, scope_path, estimate_amount, created_at_ms, expires_at_ms, extension_count for the event payload. Uses `ActorType.SYSTEM` since it's a background job.
+
+**Events NOT emitted (deferred — require new infrastructure):**
+- `budget.threshold_crossed` — needs per-scope threshold configuration + utilization % calculation
+- `budget.burn_rate_anomaly` — needs time-series rate tracking subsystem
+- `budget.over_limit_exited` — admin-only event (triggered by funding operations in cycles-server-admin)
+
+**Runtime event coverage:** 6 of 9 spec-suggested event types now emitted (was 2).
+
+**Modified files:**
+- `Enums.java` — PROTOCOL_VERSION "0.1.24" → "0.1.25"
+- `EventEmitterService.java` — added `emitBalanceEvents()` helper
+- `ReservationController.java` — wired `emitBalanceEvents()` after reserve and commit
+- `EventController.java` — wired `emitBalanceEvents()` after event creation
+- `ReservationExpiryService.java` — added `emitExpiredEvent()` post-expire hook
+- `pom.xml` — revision 0.1.25.1 → 0.1.25.3
+
+---
+
 ### 2026-04-03 — v0.1.25.2: Case-insensitive scope matching
 
 **Bug fix (defense-in-depth):** The admin API may have stored mixed-case scope values. `getBalances` lowercased query params but not the stored scope from Redis, causing case mismatches. Now lowercases `trueScope`/`scopePath` before segment matching in both `getBalances` and `listReservations`.

BENCHMARKS.md

@@ -9,6 +9,58 @@ Run benchmarks: `mvn test -Pbenchmark` (requires Docker).
 
 ---
 
+## v0.1.25.3 — Extended Runtime Event Emission + PROTOCOL_VERSION Fix
+
+**Date:** 2026-04-03
+**Branch:** `release/v0.1.25.3`
+**Base commit:** `32293e4`
+**Environment:** Windows 11 Pro, AMD Ryzen Threadripper 3990X 64-Core, Java 21.0.5, Docker 29.3.1, Redis 7 (Testcontainers)
+
+**Changes from v0.1.25.1:**
+- 4 new async event emissions: budget.exhausted, budget.over_limit_entered, budget.debt_incurred, reservation.expired
+- `EventEmitterService.emitBalanceEvents()` inspects post-operation balances (no extra Redis calls)
+- `ReservationExpiryService.emitExpiredEvent()` adds 1 HGETALL per expired reservation for event payload
+- Fixed `PROTOCOL_VERSION` constant: "0.1.24" → "0.1.25"
+- No changes to Lua scripts or core hot-path logic
+
+### Single-Threaded Write-Path Latency
+
+| Operation         |  p50   |  p95   |  p99   |  min   |  max   |  mean  |
+|-------------------|--------|--------|--------|--------|--------|--------|
+| Reserve           |  6.2ms |  7.3ms |  7.9ms |  4.6ms | 16.3ms |  6.3ms |
+| Commit            |  4.1ms |  5.2ms |  5.7ms |  3.1ms |  6.3ms |  4.1ms |
+| Release           |  4.8ms |  6.1ms |  6.5ms |  3.2ms |  6.9ms |  4.9ms |
+| Extend            |  7.4ms |  9.2ms | 10.2ms |  5.4ms | 19.3ms |  7.5ms |
+| Decide            |  5.5ms |  6.7ms |  7.0ms |  3.8ms | 20.5ms |  5.6ms |
+| Event             |  5.2ms |  6.2ms |  6.9ms |  3.3ms |  8.4ms |  5.2ms |
+| Reserve + Commit  | 14.9ms | 17.5ms | 18.4ms | 10.8ms | 23.7ms | 14.6ms |
+| Reserve + Release | 11.4ms | 15.5ms | 16.7ms |  8.7ms | 23.8ms | 11.9ms |
+
+**Write-path analysis:** All write operations are within noise of v0.1.25.1, confirming the new `emitBalanceEvents()` calls add zero measurable overhead. Commit improved slightly (4.1ms vs 5.6ms) — environmental variance from a warmer container. Reserve (6.2ms vs 6.9ms), Event (5.2ms vs 6.0ms), and Release (4.8ms vs 5.8ms) all show minor improvements attributable to container warmth. The new balance event emission runs on the existing async thread pool and only iterates the in-memory balances list (no Redis calls), so it does not touch the request hot path. Extend (7.4ms vs 8.6ms) is consistent with its Lua script complexity. No regressions detected.
+
+### Single-Threaded Read-Path Latency
+
+| Operation           |  p50   |  p95   |  p99   |  min   |  max   |  mean  |
+|---------------------|--------|--------|--------|--------|--------|--------|
+| GET reservation     |  2.8ms |  3.6ms |  4.0ms |  2.0ms |  5.3ms |  2.8ms |
+| GET balances        |  2.9ms |  3.7ms |  3.9ms |  2.1ms |  4.0ms |  2.9ms |
+| LIST reservations   |  3.3ms |  4.6ms |  5.2ms |  2.3ms |  5.9ms |  3.4ms |
+| Decide (pipelined)  |  3.5ms |  4.5ms |  5.7ms |  2.8ms |  6.9ms |  3.6ms |
+
+**Read-path analysis:** Read operations improved from v0.1.25.1 (GET reservation 2.8ms vs 4.0ms, GET balances 2.9ms vs 4.1ms, LIST 3.3ms vs 5.0ms, Decide 3.5ms vs 5.6ms). No read-path code was changed, so these improvements are environmental — the v0.1.25.1 benchmark session had higher GC pressure from a different container state. These numbers are now comparable to v0.1.24.3 baselines (GET reservation 2.8ms vs 2.8ms, GET balances 2.9ms vs 2.1ms), confirming the event emission infrastructure adds no sustained overhead to read operations.
+
+### Concurrent Throughput (Reserve+Commit lifecycle)
+
+| Threads | Total Ops | Ops/sec  |  p50    |  p95    |  p99    |  min   |  max    | Errors |
+|---------|-----------|----------|---------|---------|---------|--------|---------|--------|
+|       8 |     4,082 |    816.4 |   9.6ms |  11.6ms |  21.0ms |  7.1ms |  24.5ms |      0 |
+|      16 |     5,810 |  1,162.0 |  13.7ms |  19.2ms |  22.4ms |  6.1ms |  28.7ms |      0 |
+|      32 |    14,363 |  2,872.6 |  10.8ms |  15.1ms |  19.3ms |  6.6ms |  43.1ms |      0 |
+
+**Concurrency analysis:** Throughput at 32 threads is 2,873 ops/s — an 11% improvement over v0.1.25.1's 2,584 ops/s and 13% over v0.1.24.3's 2,534 ops/s. This is environmental variance (warmer container, Docker engine update from 29.2.1 to 29.3.1), not a code improvement. The scaling ratio from 8→32 threads is 3.5x (816 → 2,873 ops/s), consistent with prior versions. p99 at 32 threads (19.3ms) improved from v0.1.25.1's 27.2ms and v0.1.24.3's 22.7ms. Max latency (43.1ms) is consistent with expected Redis Lua serialization tail. Zero errors at all concurrency levels confirms the new balance event emission does not introduce contention — `emitBalanceEvents()` only reads the in-memory balance list on the async thread pool, never competing for Redis connections on the request path. The benchmark happy-path lifecycle (reserve+commit with sufficient budget) does not trigger any of the new events (no exhaustion, no over-limit, no debt), so the emit code path is a no-op during benchmarks. Real-world overhead would be one additional `emit()` call per triggered condition per scope — the same async fire-and-forget path already validated in v0.1.25.1.
+
+---
+
 ## v0.1.25.1 — Webhook Event Emission + TTL Retention
 
 **Date:** 2026-04-01

README.md

@@ -53,7 +53,7 @@ cd cycles-protocol-service
 
 # 4. Run
 REDIS_HOST=localhost REDIS_PORT=6379 \
-  java -jar cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.25.1.jar
+  java -jar cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.25.3.jar
 ```
 
 Server starts on **port 7878**. Interactive API docs: http://localhost:7878/swagger-ui.html
@@ -77,7 +77,7 @@ cycles-server-events (port 7980)
 Webhook receivers
 ```
 
-**Event emission:** Runtime operations (reserve denied, commit overage) emit events to the shared Redis dispatch queue. The events delivery service (`cycles-server-events`) picks them up and delivers via HTTP POST with HMAC-SHA256 signing.
+**Event emission:** Runtime operations emit events to the shared Redis dispatch queue. The events delivery service (`cycles-server-events`) picks them up and delivers via HTTP POST with HMAC-SHA256 signing.
 
 **Modules** (under `cycles-protocol-service/`):
 
@@ -117,7 +117,7 @@ mvn clean install
 ./build-all.sh
 ```
 
-The fat JAR is produced at `cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.25.1.jar`.
+The fat JAR is produced at `cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.25.3.jar`.
 
 ## Docker Deployment
 
@@ -136,7 +136,7 @@ Pre-built images are published to GitHub Container Registry on each release:
 
 ```
 ghcr.io/runcycles/cycles-server:latest
-ghcr.io/runcycles/cycles-server:<version>    # e.g. 0.1.25.1
+ghcr.io/runcycles/cycles-server:<version>    # e.g. 0.1.25.3
 ```
 
 ## Testing
@@ -172,9 +172,13 @@ Integration tests (`*IntegrationTest.java`) use [Testcontainers](https://www.tes
 
 ### Webhook Event Emission
 
-The runtime server emits events to the shared Redis dispatch queue when:
-- A reservation is **denied** (`reservation.denied`)
-- A commit has **actual > estimated** (`reservation.commit_overage`)
+The runtime server emits events to the shared Redis dispatch queue for:
+- `reservation.denied` — reserve or decide returned DENY
+- `reservation.commit_overage` — commit actual exceeded reservation estimate
+- `reservation.expired` — reservation TTL expired without commit/release (via background sweeper)
+- `budget.exhausted` — remaining budget reached 0 after an operation
+- `budget.over_limit_entered` — scope entered over-limit state (debt > overdraft_limit or ALLOW_IF_AVAILABLE cap)
+- `budget.debt_incurred` — commit/event created debt via ALLOW_WITH_OVERDRAFT
 
 These events are delivered by `cycles-server-events` to webhook subscribers via HTTP POST with HMAC-SHA256 signing. Event emission is non-blocking — failures are logged but never affect the API response.
 

cycles-protocol-service/README.md

@@ -70,7 +70,7 @@ docker run -d -p 6379:6379 redis:7-alpine
 
 # 4. Run
 REDIS_HOST=localhost REDIS_PORT=6379 \
-  java -jar cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.25.1.jar
+  java -jar cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.25.3.jar
 ```
 
 The server starts on **port 7878**. Interactive API docs: http://localhost:7878/swagger-ui.html
@@ -148,13 +148,13 @@ Beyond expires_at_ms:                  extend blocked (410)
 
 | Policy | Behaviour |
 |---|---|
-| `REJECT` *(default)* | Commit fails with `409 BUDGET_EXCEEDED` if actual exceeds reserved |
-| `ALLOW_IF_AVAILABLE` | Delta is atomically charged from remaining budget; fails with `409 BUDGET_EXCEEDED` if insufficient |
+| `REJECT` | Commit fails with `409 BUDGET_EXCEEDED` if actual exceeds reserved |
+| `ALLOW_IF_AVAILABLE` *(default)* | Commit always succeeds; delta charged from remaining budget if available, otherwise capped to available remaining and `is_over_limit` set on affected scopes |
 | `ALLOW_WITH_OVERDRAFT` | Delta creates debt up to `overdraft_limit`; fails with `409 OVERDRAFT_LIMIT_EXCEEDED` if `debt + delta > overdraft_limit` |
 
 The same three policies apply to `/v1/events` for direct debits.
 
-When `overage_policy` is omitted from the request, the server resolves it from the tenant's `default_commit_overage_policy` (set via the Admin API). If the tenant has no default configured, `REJECT` is used.
+When `overage_policy` is omitted from the request, the server resolves it from the tenant's `default_commit_overage_policy` (set via the Admin API). If the tenant has no default configured, `ALLOW_IF_AVAILABLE` is used.
 
 ### Debt and Overdraft
 
@@ -308,7 +308,7 @@ Reserve budget before executing an action. Returns `200 OK`.
 | `estimate.amount` | yes | — | ≥ 0 |
 | `ttl_ms` | no | tenant `default_reservation_ttl_ms` or `60000` | 1000–86400000 ms; capped to tenant `max_reservation_ttl_ms` |
 | `grace_period_ms` | no | `5000` | 0–60000 ms |
-| `overage_policy` | no | tenant `default_commit_overage_policy` or `REJECT` | see Overage Policies |
+| `overage_policy` | no | tenant `default_commit_overage_policy` or `ALLOW_IF_AVAILABLE` | see Overage Policies |
 | `dry_run` | no | `false` | evaluates without persisting if true |
 
 **Response** `200 OK`
@@ -477,7 +477,7 @@ List reservations for the effective tenant. Optional recovery/debug endpoint. Re
 
 ### GET /v1/reservations/{reservation_id}
 
-Fetch a single reservation by ID. Returns `200 OK` for `ACTIVE`, `COMMITTED`, and `RELEASED` statuses. Returns `410 Gone` for `EXPIRED` reservations.
+Fetch a single reservation by ID. Returns `200 OK` with the reservation's current status (`ACTIVE`, `COMMITTED`, `RELEASED`, or `EXPIRED`).
 
 **Response** `200 OK`
 
@@ -553,8 +553,8 @@ Record a direct debit without a prior reservation. Applied atomically across all
 
 | Overage policy | Behaviour |
 |---|---|
-| `REJECT` *(default)* | Returns `409 BUDGET_EXCEEDED` if `actual > remaining` on any derived scope |
-| `ALLOW_IF_AVAILABLE` | Applies atomically only if sufficient remaining exists; otherwise `409 BUDGET_EXCEEDED` |
+| `REJECT` | Returns `409 BUDGET_EXCEEDED` if `actual > remaining` on any derived scope |
+| `ALLOW_IF_AVAILABLE` *(default)* | Event always succeeds; charges available remaining, caps to available if insufficient, sets `is_over_limit` on affected scopes |
 | `ALLOW_WITH_OVERDRAFT` | Creates debt if insufficient; `409 OVERDRAFT_LIMIT_EXCEEDED` if `debt + actual > overdraft_limit` |
 
 `client_time_ms` is advisory only; server time governs all budget and expiry decisions. Debt and over-limit state do **not** block events — only the `overage_policy` logic applies.
@@ -590,10 +590,13 @@ All errors use this envelope:
 | `FORBIDDEN` | 403 | Tenant in request does not match API key |
 | `NOT_FOUND` | 404 | Reservation, budget, or resource not found |
 | `BUDGET_EXCEEDED` | 409 | Insufficient remaining budget |
+| `BUDGET_FROZEN` | 409 | Budget is frozen by operator (no mutations allowed) |
+| `BUDGET_CLOSED` | 409 | Budget has been permanently closed |
 | `RESERVATION_FINALIZED` | 409 | Reservation already committed or released |
 | `IDEMPOTENCY_MISMATCH` | 409 | Idempotency key reused with different parameters |
 | `OVERDRAFT_LIMIT_EXCEEDED` | 409 | `debt + delta > overdraft_limit`; or scope is over-limit |
 | `DEBT_OUTSTANDING` | 409 | Scope has unresolved debt with no overdraft limit; new reservations blocked |
+| `MAX_EXTENSIONS_EXCEEDED` | 409 | Tenant's `max_reservation_extensions` limit reached |
 | `RESERVATION_EXPIRED` | 410 | Operation attempted after expiry window |
 | `INTERNAL_ERROR` | 500 | Unexpected server error |
 

cycles-protocol-service/cycles-protocol-service-api/src/main/java/io/runcycles/protocol/api/controller/EventController.java

@@ -1,7 +1,9 @@
 package io.runcycles.protocol.api.controller;
 
 import io.runcycles.protocol.data.repository.RedisReservationRepository;
+import io.runcycles.protocol.data.service.EventEmitterService;
 import io.runcycles.protocol.model.*;
+import io.runcycles.protocol.model.event.*;
 import io.swagger.v3.oas.annotations.*;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
@@ -23,6 +25,9 @@ public class EventController extends BaseController {
     @Autowired
     private RedisReservationRepository repository;
 
+    @Autowired
+    private EventEmitterService eventEmitter;
+
     @PostMapping
     @Operation(operationId = "createEvent", summary = "Record a direct debit event without reservation")
     public ResponseEntity<EventCreateResponse> create(
@@ -35,6 +40,10 @@ public ResponseEntity<EventCreateResponse> create(
         authorizeTenant(request.getSubject().getTenant());
         String tenant = extractAuthTenantId();
         EventCreateResponse response = repository.createEvent(request, tenant);
+        try {
+            Actor actor = Actor.builder().type(ActorType.API_KEY).build();
+            eventEmitter.emitBalanceEvents(response.getBalances(), tenant, actor, null, null);
+        } catch (Exception e) { /* non-blocking */ }
         return ResponseEntity.status(HttpStatus.CREATED).body(response);
     }
 }

cycles-protocol-service/cycles-protocol-service-api/src/main/java/io/runcycles/protocol/api/controller/ReservationController.java

@@ -44,9 +44,10 @@ public ResponseEntity<ReservationCreateResponse> create(
         String tenant = extractAuthTenantId();
         ReservationCreateResponse response = repository.createReservation(request, tenant);
         try {
+            Actor actor = Actor.builder().type(ActorType.API_KEY).build();
             if (response.getDecision() == Enums.DecisionEnum.DENY) {
                 eventEmitter.emit(EventType.RESERVATION_DENIED, tenant, response.getScopePath(),
-                        Actor.builder().type(ActorType.API_KEY).build(),
+                        actor,
                         EventDataReservationDenied.builder()
                                 .scope(response.getScopePath())
                                 .reasonCode(response.getReasonCode())
@@ -55,6 +56,8 @@ public ResponseEntity<ReservationCreateResponse> create(
                                 .build(),
                         null, null);
             }
+            // Emit budget state events from post-operation balances
+            eventEmitter.emitBalanceEvents(response.getBalances(), tenant, actor, null, null);
         } catch (Exception e) { /* non-blocking */ }
         return ResponseEntity.ok(response);
     }
@@ -82,18 +85,21 @@ public ResponseEntity<CommitResponse> commit(
         authorizeTenant(tenant);
         CommitResponse response = repository.commitReservation(reservationId, request);
         try {
+            Actor actor = Actor.builder().type(ActorType.API_KEY).build();
             // Emit commit_overage only when actual charge exceeds the original reservation estimate
             if (response.getEstimateAmount() != null && response.getCharged() != null
                     && response.getCharged().getAmount() != null
                     && response.getCharged().getAmount() > response.getEstimateAmount()) {
                 eventEmitter.emit(EventType.RESERVATION_COMMIT_OVERAGE, tenant, null,
-                        Actor.builder().type(ActorType.API_KEY).build(),
+                        actor,
                         EventDataCommitOverage.builder()
                                 .reservationId(reservationId)
                                 .actualAmount(response.getCharged().getAmount())
                                 .build(),
                         null, null);
             }
+            // Emit budget state events from post-operation balances
+            eventEmitter.emitBalanceEvents(response.getBalances(), tenant, actor, null, null);
         } catch (Exception e) { /* non-blocking */ }
         return ResponseEntity.ok(response);
     }