Merge pull request #78 from runcycles/release/v0.1.25.5

fix: transition-based event emission to prevent duplicate budget events (v0.1.25.5)

Author: amavashev

AUDIT.md

@@ -1,6 +1,6 @@
 # Cycles Protocol v0.1.25 — Server Implementation Audit
 
-**Date:** 2026-04-07 (v0.1.25.4 event data completeness), 2026-04-01 (v0.1.25 event emission + TTL), 2026-03-24 (Round 6: spec compliance audit), 2026-03-24 (v0.1.24 update), 2026-03-23 (updated), 2026-03-15 (initial)
+**Date:** 2026-04-08 (v0.1.25.5 duplicate event fix), 2026-04-07 (v0.1.25.4 event data completeness), 2026-04-01 (v0.1.25 event emission + TTL), 2026-03-24 (Round 6: spec compliance audit), 2026-03-24 (v0.1.24 update), 2026-03-23 (updated), 2026-03-15 (initial)
 **Spec:** `cycles-protocol-v0.yaml` (OpenAPI 3.1.0, v0.1.25) + `complete-budget-governance-v0.1.25.yaml` (events/webhooks)
 **Server:** Spring Boot 3.5.11 / Java 21 / Redis (Lua scripts)
 
@@ -38,6 +38,19 @@
 
 **Remaining event data gaps:** None. All EventData fields now fully populated for runtime-emitted events.
 
+### 2026-04-08 — v0.1.25.5: Fix duplicate budget state events (cycles-server-events#15)
+
+**Bug:** `budget.exhausted`, `budget.over_limit_entered`, and `budget.debt_incurred` events fired on every operation where the post-state matched the condition, not only on state *transitions*. For example, a reserve that depleted a budget emitted `budget.exhausted`, then the subsequent commit (with remaining still at 0) emitted it again.
+
+**Root cause:** `EventEmitterService.emitBalanceEvents()` checked post-mutation state only (e.g., `remaining == 0`). No transition detection.
+
+**Fix:** Lua scripts (reserve, commit, event) now include `pre_remaining` and `pre_is_over_limit` per scope in balance snapshots. Java emits only on transitions:
+- `budget.exhausted`: `pre_remaining > 0 && remaining == 0`
+- `budget.over_limit_entered`: `!pre_is_over_limit && is_over_limit`
+- `budget.debt_incurred`: `scopeDebtIncurred[scope] > 0` (already tracked)
+
+**Performance:** No extra Redis calls. reserve.lua caches pre-state from existing validation HMGET. commit.lua caches from existing overage-path reads (ALLOW_IF_AVAILABLE/ALLOW_WITH_OVERDRAFT); delta <= 0 paths skip (remaining can only increase). event.lua folds `is_over_limit` into existing HMGET.
+
 ---
 
 ### 2026-04-03 — v0.1.25.3: Extended runtime event emission + PROTOCOL_VERSION fix

BENCHMARKS.md

@@ -9,6 +9,59 @@ Run benchmarks: `mvn test -Pbenchmark` (requires Docker).
 
 ---
 
+## v0.1.25.5 — Transition-Based Event Emission (Duplicate Event Fix)
+
+**Date:** 2026-04-08
+**Branch:** `release/v0.1.25.5`
+**Base commit:** `9b2f4e1`
+**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.4:**
+- Lua scripts (reserve, commit, event) include pre-mutation `pre_remaining` and `pre_is_over_limit` per scope in balance snapshots
+- Java emits budget state events only on state transitions (not every matching post-state)
+- commit.lua ALLOW_IF_AVAILABLE path: HGET → HMGET (remaining + is_over_limit in one call)
+- commit.lua ALLOW_WITH_OVERDRAFT path: added is_over_limit to existing HMGET (4 → 5 fields)
+- event.lua: folded is_over_limit into existing HMGET (5 → 6 fields, removed separate HGET)
+- No extra Redis calls on any path
+
+### Single-Threaded Write-Path Latency
+
+| Operation         |  p50   |  p95   |  p99   |  min   |  max   |  mean  |
+|-------------------|--------|--------|--------|--------|--------|--------|
+| Reserve           |  7.2ms |  8.3ms |  8.7ms |  5.8ms | 16.1ms |  7.2ms |
+| Commit            |  5.8ms |  6.6ms |  7.4ms |  4.6ms | 14.2ms |  5.8ms |
+| Release           |  6.0ms |  6.9ms |  7.2ms |  4.4ms | 14.2ms |  6.0ms |
+| Extend            |  9.0ms | 10.3ms | 12.9ms |  7.4ms | 19.3ms |  9.0ms |
+| Decide            |  6.3ms |  7.5ms |  8.4ms |  4.4ms | 10.5ms |  6.3ms |
+| Event             |  6.2ms |  7.3ms |  7.7ms |  4.4ms |  8.2ms |  6.2ms |
+| Reserve + Commit  | 16.7ms | 18.9ms | 20.6ms | 13.0ms | 28.5ms | 16.7ms |
+| Reserve + Release | 14.2ms | 17.2ms | 21.3ms | 11.5ms | 25.3ms | 14.2ms |
+
+**Write-path analysis:** All operations consistent with v0.1.25.4. Reserve (7.2ms vs 5.7ms), Commit (5.8ms vs 4.7ms), Release (6.0ms vs 4.8ms), Extend (9.0ms vs 7.6ms), Decide (6.3ms vs 5.5ms), Event (6.2ms vs 5.1ms) — all within normal container/JVM warmth variance across benchmark sessions. The pre-state caching in Lua adds zero extra Redis calls: reserve.lua caches from its existing validation HMGET, commit.lua from existing overage-path reads, event.lua folds is_over_limit into its existing HMGET. No regressions.
+
+### Single-Threaded Read-Path Latency
+
+| Operation           |  p50   |  p95   |  p99   |  min   |  max   |  mean  |
+|---------------------|--------|--------|--------|--------|--------|--------|
+| GET reservation     |  3.5ms |  4.3ms |  4.8ms |  2.0ms |  5.2ms |  3.5ms |
+| GET balances        |  3.6ms |  4.5ms |  4.8ms |  2.1ms |  4.9ms |  3.6ms |
+| LIST reservations   |  3.9ms |  4.6ms |  4.8ms |  2.4ms |  4.9ms |  3.8ms |
+| Decide (pipelined)  |  4.2ms |  5.0ms |  5.5ms |  2.9ms |  6.2ms |  4.2ms |
+
+**Read-path analysis:** No read-path code was changed. All operations consistent with v0.1.25.4 (GET reservation 3.5ms vs 3.8ms, GET balances 3.6ms vs 4.0ms). No regressions.
+
+### Concurrent Throughput (Reserve+Commit lifecycle)
+
+| Threads | Total Ops | Ops/sec  |  p50    |  p95    |  p99    |  min   |  max    | Errors |
+|---------|-----------|----------|---------|---------|---------|--------|---------|--------|
+|       8 |     3,764 |    752.8 |  10.3ms |  12.8ms |  23.2ms |  7.4ms |  32.0ms |      0 |
+|      16 |     5,316 |  1,063.2 |  14.7ms |  21.4ms |  26.0ms |  6.8ms |  51.5ms |      0 |
+|      32 |    12,599 |  2,519.8 |  11.5ms |  21.2ms |  34.5ms |  6.7ms |  67.6ms |      0 |
+
+**Concurrency analysis:** Throughput at 32 threads is 2,520 ops/s — within 5% of v0.1.25.4's 2,655 ops/s. The scaling ratio from 8→32 threads is 3.3x (753 → 2,520), consistent with prior versions (v0.1.25.4: 3.4x, v0.1.25.3: 3.5x). p99 at 32 threads (34.5ms) is comparable to v0.1.25.4's 29.8ms. Zero errors at all concurrency levels. The transition fix adds no measurable overhead — pre-state caching piggybacks on existing Lua reads with zero extra Redis calls. Earlier runs on this day showed degraded numbers (~725 ops/s) due to TuneupUI background processes consuming CPU; after termination, normal throughput restored.
+
+---
+
 ## v0.1.25.4 — Event Data Payload Completeness
 
 **Date:** 2026-04-07

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.4.jar
+  java -jar cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.25.5.jar
 ```
 
 Server starts on **port 7878**. Interactive API docs: http://localhost:7878/swagger-ui.html
@@ -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.4.jar`.
+The fat JAR is produced at `cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.25.5.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.4
+ghcr.io/runcycles/cycles-server:<version>    # e.g. 0.1.25.5
 ```
 
 ## Testing

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.4.jar
+  java -jar cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.25.5.jar
 ```
 
 The server starts on **port 7878**. Interactive API docs: http://localhost:7878/swagger-ui.html

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

@@ -47,7 +47,9 @@ public ResponseEntity<EventCreateResponse> create(
             String policy = request.getOveragePolicy() != null
                     ? request.getOveragePolicy().name() : "ALLOW_IF_AVAILABLE";
             eventEmitter.emitBalanceEvents(response.getBalances(), tenant, actor,
-                    null, policy, response.getScopeDebtIncurred(), null, null);
+                    null, policy, response.getScopeDebtIncurred(),
+                    response.getPreRemaining(), response.getPreIsOverLimit(),
+                    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

@@ -81,8 +81,11 @@ public ResponseEntity<ReservationCreateResponse> create(
                                 .build(),
                         null, null);
             }
-            // Emit budget state events from post-operation balances
-            eventEmitter.emitBalanceEvents(response.getBalances(), tenant, actor, null, null);
+            // Emit budget state events from post-operation balances (transition-based)
+            eventEmitter.emitBalanceEvents(response.getBalances(), tenant, actor,
+                    null, null, null,
+                    response.getPreRemaining(), response.getPreIsOverLimit(),
+                    null, null);
         } catch (Exception e) { /* non-blocking */ }
         return ResponseEntity.ok(response);
     }
@@ -133,10 +136,12 @@ public ResponseEntity<CommitResponse> commit(
                                 .build(),
                         null, null);
             }
-            // Emit budget state events from post-operation balances
+            // Emit budget state events from post-operation balances (transition-based)
             eventEmitter.emitBalanceEvents(response.getBalances(), tenant, actor,
                     reservationId, response.getOveragePolicy(),
-                    response.getScopeDebtIncurred(), null, null);
+                    response.getScopeDebtIncurred(),
+                    response.getPreRemaining(), response.getPreIsOverLimit(),
+                    null, null);
         } catch (Exception e) { /* non-blocking */ }
         return ResponseEntity.ok(response);
     }

cycles-protocol-service/cycles-protocol-service-data/src/main/java/io/runcycles/protocol/data/repository/RedisReservationRepository.java

@@ -130,6 +130,8 @@ public ReservationCreateResponse createReservation(ReservationCreateRequest requ
                 .expiresAtMs(((Number) response.get("expires_at")).longValue())
                 .caps(caps)
                 .balances(balances)
+                .preRemaining(parsePreRemaining(response))
+                .preIsOverLimit(parsePreIsOverLimit(response))
                 .build();
         } catch (CyclesProtocolException e) {
             throw e;
@@ -344,6 +346,8 @@ public CommitResponse commitReservation(String reservationId, CommitRequest requ
                 .overagePolicy(overagePolicy)
                 .debtIncurred(luaDebt != null ? luaDebt.longValue() : null)
                 .scopeDebtIncurred(scopeDebtIncurred)
+                .preRemaining(parsePreRemaining(response))
+                .preIsOverLimit(parsePreIsOverLimit(response))
                 .build();
         } catch (CyclesProtocolException e){
             LOG.error("Failed logic to commit reservation", e);
@@ -844,6 +848,8 @@ public EventCreateResponse createEvent(EventCreateRequest request, String tenant
                 .charged(charged)
                 .balances(balances)
                 .scopeDebtIncurred(scopeDebtIncurred)
+                .preRemaining(parsePreRemaining(response))
+                .preIsOverLimit(parsePreIsOverLimit(response))
                 .build();
         } catch (CyclesProtocolException e) {
             throw e;
@@ -1033,6 +1039,44 @@ private List<Balance> fetchBalancesForScopes(Jedis jedis, List<String> scopes, E
      * Extract per-scope debt_incurred from Lua balance entries.
      * Returns a map of scope → debt incurred during this operation.
      */
+    /**
+     * Extract per-scope pre-mutation remaining from Lua balance entries.
+     * Used for transition detection: emit budget.exhausted only when pre_remaining > 0 && remaining == 0.
+     */
+    private Map<String, Long> parsePreRemaining(Map<String, Object> response) {
+        Object balancesObj = response.get("balances");
+        if (balancesObj == null || !(balancesObj instanceof List)) {
+            return Collections.emptyMap();
+        }
+        List<Map<String, Object>> luaBalances = (List<Map<String, Object>>) balancesObj;
+        Map<String, Long> result = new java.util.HashMap<>();
+        for (Map<String, Object> lb : luaBalances) {
+            String scope = (String) lb.get("scope");
+            long preRemaining = ((Number) lb.getOrDefault("pre_remaining", 0)).longValue();
+            result.put(scope, preRemaining);
+        }
+        return result;
+    }
+
+    /**
+     * Extract per-scope pre-mutation is_over_limit from Lua balance entries.
+     * Used for transition detection: emit budget.over_limit_entered only when pre=false && post=true.
+     */
+    private Map<String, Boolean> parsePreIsOverLimit(Map<String, Object> response) {
+        Object balancesObj = response.get("balances");
+        if (balancesObj == null || !(balancesObj instanceof List)) {
+            return Collections.emptyMap();
+        }
+        List<Map<String, Object>> luaBalances = (List<Map<String, Object>>) balancesObj;
+        Map<String, Boolean> result = new java.util.HashMap<>();
+        for (Map<String, Object> lb : luaBalances) {
+            String scope = (String) lb.get("scope");
+            boolean preOverLimit = Boolean.TRUE.equals(lb.get("pre_is_over_limit"));
+            result.put(scope, preOverLimit);
+        }
+        return result;
+    }
+
     private Map<String, Long> parseScopeDebtIncurred(Map<String, Object> response) {
         Object balancesObj = response.get("balances");
         if (balancesObj == null || !(balancesObj instanceof List)) {

cycles-protocol-service/cycles-protocol-service-data/src/main/java/io/runcycles/protocol/data/service/EventEmitterService.java

@@ -86,32 +86,44 @@ public void emit(EventType type, String tenantId, String scope, Actor actor,
      */
     public void emitBalanceEvents(List<Balance> balances, String tenantId, Actor actor,
                                   String correlationId, String requestId) {
-        emitBalanceEvents(balances, tenantId, actor, null, null, null, correlationId, requestId);
+        emitBalanceEvents(balances, tenantId, actor, null, null, null,
+                null, null, correlationId, requestId);
     }
 
     /**
      * Overload accepting reservation context for richer event data on debt_incurred events.
      */
     public void emitBalanceEvents(List<Balance> balances, String tenantId, Actor actor,
                                   String reservationId, String overagePolicy,
+                                  Map<String, Long> scopeDebtIncurred,
                                   String correlationId, String requestId) {
-        emitBalanceEvents(balances, tenantId, actor, reservationId, overagePolicy, null, correlationId, requestId);
+        emitBalanceEvents(balances, tenantId, actor, reservationId, overagePolicy, scopeDebtIncurred,
+                null, null, correlationId, requestId);
     }
 
     /**
-     * Full overload with per-scope debt incurred map for complete EventDataBudgetDebtIncurred.
+     * Full overload with pre-mutation state maps for transition-based event emission.
+     * Only emits budget state events on state transitions (not on every operation where
+     * the post-state matches). Fixes duplicate event firing (cycles-server-events#15).
      */
     public void emitBalanceEvents(List<Balance> balances, String tenantId, Actor actor,
                                   String reservationId, String overagePolicy,
                                   Map<String, Long> scopeDebtIncurred,
+                                  Map<String, Long> preRemaining,
+                                  Map<String, Boolean> preIsOverLimit,
                                   String correlationId, String requestId) {
         Map<String, Long> debtMap = scopeDebtIncurred != null ? scopeDebtIncurred : Collections.emptyMap();
+        Map<String, Long> preRem = preRemaining != null ? preRemaining : Collections.emptyMap();
+        Map<String, Boolean> preOvl = preIsOverLimit != null ? preIsOverLimit : Collections.emptyMap();
         if (balances == null || balances.isEmpty()) return;
         for (Balance b : balances) {
+            String scopePath = b.getScopePath();
             String unit = b.getRemaining() != null ? b.getRemaining().getUnit().name() : null;
-            // budget.exhausted — remaining.amount == 0
+            long preRemainingVal = preRem.getOrDefault(scopePath, Long.MAX_VALUE);
+            boolean preOverLimitVal = preOvl.getOrDefault(scopePath, false);
+            // budget.exhausted — transition: pre_remaining > 0 && remaining == 0
             if (b.getRemaining() != null && b.getRemaining().getAmount() != null
-                    && b.getRemaining().getAmount() == 0L) {
+                    && b.getRemaining().getAmount() == 0L && preRemainingVal > 0L) {
                 // Spec: use EventDataBudgetThreshold with threshold=1.0, direction=rising
                 Double utilization = null;
                 Long allocated = b.getAllocated() != null ? b.getAllocated().getAmount() : null;
@@ -136,8 +148,8 @@ public void emitBalanceEvents(List<Balance> balances, String tenantId, Actor act
                                 .build(),
                         correlationId, requestId);
             }
-            // budget.over_limit_entered — is_over_limit flipped to true
-            if (Boolean.TRUE.equals(b.getIsOverLimit())) {
+            // budget.over_limit_entered — transition: pre=false && post=true
+            if (Boolean.TRUE.equals(b.getIsOverLimit()) && !preOverLimitVal) {
                 Long debt = b.getDebt() != null ? b.getDebt().getAmount() : null;
                 Long odLimit = b.getOverdraftLimit() != null ? b.getOverdraftLimit().getAmount() : null;
                 Double debtUtilization = (debt != null && odLimit != null && odLimit > 0)
@@ -154,11 +166,11 @@ public void emitBalanceEvents(List<Balance> balances, String tenantId, Actor act
                                 .build(),
                         correlationId, requestId);
             }
-            // budget.debt_incurred — debt > 0
-            if (b.getDebt() != null && b.getDebt().getAmount() != null
-                    && b.getDebt().getAmount() > 0L) {
+            // budget.debt_incurred — only when new debt was created in this operation
+            Long perScopeDebt = debtMap.get(scopePath);
+            if (perScopeDebt != null && perScopeDebt > 0L
+                    && b.getDebt() != null && b.getDebt().getAmount() != null) {
                 Long odLimit = b.getOverdraftLimit() != null ? b.getOverdraftLimit().getAmount() : null;
-                Long perScopeDebt = debtMap.get(b.getScopePath());
                 emit(EventType.BUDGET_DEBT_INCURRED, tenantId, b.getScopePath(),
                         actor,
                         EventDataBudgetDebtIncurred.builder()