Merge pull request #80 from runcycles/fix/reserve-unit-mismatch

fix: distinguish UNIT_MISMATCH from BUDGET_NOT_FOUND on reserve/event/decide (v0.1.25.6)

Author: amavashev

AUDIT.md

@@ -1,11 +1,39 @@
 # Cycles Protocol v0.1.25 — Server Implementation Audit
 
-**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)
+**Date:** 2026-04-10 (v0.1.25.6 reserve/event UNIT_MISMATCH detection), 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)
 
 ---
 
+### 2026-04-10 — v0.1.25.6: Distinguish UNIT_MISMATCH from BUDGET_NOT_FOUND on reserve/event
+
+**Bug (runcycles/cycles-client-rust#8):** `POST /v1/reservations` with `Amount::tokens(1000)` against a scope whose budget was stored in `USD_MICROCENTS` returned `404 BUDGET_NOT_FOUND`. The client could not distinguish "no budget at this scope" from "budget exists but in a different unit" and had no hint toward the fix. `/v1/events` had the same latent bug.
+
+**Root cause:** `reserve.lua` / `event.lua` key budgets by `budget:<scope>:<unit>`. When the requested unit doesn't match the stored unit, the key doesn't exist, the scope is silently skipped, and `#budgeted_scopes == 0` falls through to `BUDGET_NOT_FOUND`. The existing `UNIT_MISMATCH` branch in `event.lua` only caught an internal inconsistency between key suffix and stored `unit` field — it did not catch the cross-unit case.
+
+**Fix:** On the empty-budgeted-scopes error path only, both scripts now probe the fixed `UnitEnum` set (`USD_MICROCENTS`, `TOKENS`, `CREDITS`, `RISK_POINTS`) via `EXISTS budget:<scope>:<unit_alt>` for each affected scope. If any alternate-unit budget exists, the script returns `UNIT_MISMATCH` (400) with `scope`, `requested_unit`, and `expected_units` in the error payload so the client can self-correct. Otherwise falls through to the existing `BUDGET_NOT_FOUND` (404).
+
+Cascade semantics preserved: scopes without a budget at the requested unit are still silently skipped during the main validation loop — the probe only fires when every affected scope missed. No hot-path change; the cost is paid once on the error path only.
+
+`evaluateDryRun` and `/v1/decide` (the non-Lua Java paths) get the symmetric probe via a shared `probeAlternateUnits` helper and throw `UNIT_MISMATCH` (400) to match the reserve/event behavior. Spec line 1131-1134 only prohibits 409 on `/decide` for debt/overdraft conditions; 400 for a request-validity error (wrong unit) is permitted and is consistent across all four entry points.
+
+**Modified files:**
+- `reserve.lua` — new `ARGV[15] = units_csv`; scopes now start at ARGV[16]; alternate-unit probe added to the empty-budgeted-scopes branch
+- `event.lua` — new `ARGV[14] = units_csv`; scopes now start at ARGV[15]; symmetric probe
+- `RedisReservationRepository.java` — `UNIT_CSV` constant derived once from `Enums.UnitEnum.values()`; passed into both `createReservation` and `createEvent` args; `evaluateDryRun` and `decide` mirror the probe via a shared `probeAlternateUnits(jedis, scope, requestedUnit)` helper; `handleScriptError` extracts `scope` / `requested_unit` / `expected_units` for reserve/event and falls back to the no-detail factory for commit.lua's legacy form
+- `CyclesProtocolException.java` — `unitMismatch(scope, requestedUnit, expectedUnits)` overload populating `details`
+- `ReservationLifecycleIntegrationTest.java` — `shouldRejectWhenNoBudgetExistsForUnit` renamed to `shouldRejectWithUnitMismatchWhenBudgetExistsInDifferentUnit` and flipped to expect 400 + details; added `shouldReturnBudgetNotFoundWhenNoBudgetAtAnyUnit` regression guard and `shouldReturnUnitMismatchOnDryRunWhenBudgetExistsInDifferentUnit`
+- `DecisionAndEventIntegrationTest.java` — `shouldRejectEventWithUnitMismatch` flipped from 404 `NOT_FOUND` to 400 `UNIT_MISMATCH` + details; added `shouldReturnBudgetNotFoundWhenNoBudgetAtAnyUnitOnEvent`, `shouldRejectDecideWithUnitMismatchWhenBudgetExistsInDifferentUnit`, and `shouldReturnDenyBudgetNotFoundOnDecideWhenNoBudgetAtAnyUnit`
+- `RedisReservationCoreOpsTest.java` — existing `shouldThrowUnitMismatch` asserts the no-detail fallback path; added `shouldThrowUnitMismatchWithDetailsFromReserve`
+- `CyclesProtocolExceptionTest.java` — coverage for the new factory overload (populated details + null-tolerant form)
+- `cycles-protocol-service/README.md` — error table entry for `UNIT_MISMATCH` broadened to include reserve + describe the `details.*` payload
+- `cycles-protocol-service/pom.xml` — `<revision>` bumped `0.1.25.5` → `0.1.25.6`
+
+**Closes:** runcycles/cycles-server#79. Addresses runcycles/cycles-client-rust#8.
+
+**Out of scope:** Client-side rust SDK changes (not needed — structured error is enough for the user to correct their call). Protocol YAML spec update lives in `runcycles/cycles-protocol` and is handled on a coordinated branch (adds `"404"` to `/v1/reservations` POST and `/v1/events` POST response lists + broadens normative UNIT_MISMATCH wording to cover reserve).
+
 ### 2026-04-07 — v0.1.25.4: Event data payload completeness
 
 **Compliance review** against protocol spec v0.1.25 + admin spec v0.1.25 found 5 event data payload gaps. Core protocol (endpoints, schemas, error codes, Lua scripts, idempotency, scope derivation, auth/tenancy) was fully compliant.
@@ -276,7 +304,7 @@ Two-pass audit covering:
 - RESERVATION_FINALIZED → 409
 - RESERVATION_EXPIRED → 410
 - NOT_FOUND → 404
-- UNIT_MISMATCH → 400 (enforced in commit.lua and event.lua)
+- UNIT_MISMATCH → 400 (enforced in reserve.lua, commit.lua, event.lua; reserve/event paths return `scope`, `requested_unit`, `expected_units` in details so the client can self-correct — see v0.1.25.6)
 - IDEMPOTENCY_MISMATCH → 409
 - INVALID_REQUEST → 400
 - INTERNAL_ERROR → 500

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.5.jar
+  java -jar cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.25.6.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.5.jar`.
+The fat JAR is produced at `cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.25.6.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.5
+ghcr.io/runcycles/cycles-server:<version>    # e.g. 0.1.25.6
 ```
 
 ## 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.5.jar
+  java -jar cycles-protocol-service-api/target/cycles-protocol-service-api-0.1.25.6.jar
 ```
 
 The server starts on **port 7878**. Interactive API docs: http://localhost:7878/swagger-ui.html
@@ -585,7 +585,7 @@ All errors use this envelope:
 | Code | HTTP | Meaning |
 |---|---|---|
 | `INVALID_REQUEST` | 400 | Missing or invalid field |
-| `UNIT_MISMATCH` | 400 | Commit unit differs from reservation unit, or event unit not supported for target scope |
+| `UNIT_MISMATCH` | 400 | Requested unit does not match the stored budget unit for the target scope. Raised by reserve/commit/event. Reserve and event responses include `details.scope`, `details.requested_unit`, and `details.expected_units` so the client can self-correct; commit uses the legacy no-detail form. |
 | `UNAUTHORIZED` | 401 | Missing or invalid API key |
 | `FORBIDDEN` | 403 | Tenant in request does not match API key |
 | `NOT_FOUND` | 404 | Reservation, budget, or resource not found |

cycles-protocol-service/cycles-protocol-service-api/src/test/java/io/runcycles/protocol/api/DecisionAndEventIntegrationTest.java

@@ -136,6 +136,45 @@ void shouldReturnAffectedScopesInDecision() {
             assertThat(resp.getStatusCode().value()).isEqualTo(200);
             assertThat(resp.getBody().get("affected_scopes")).isNotNull();
         }
+
+        @Test
+        void shouldRejectDecideWithUnitMismatchWhenBudgetExistsInDifferentUnit() {
+            // Budget seeded at tenant:tenant-a in TOKENS. Request USD_MICROCENTS on /decide →
+            // Java probe finds TOKENS at the scope → 400 UNIT_MISMATCH with expected_units.
+            // Spec line 1131-1134 only prohibits 409 on decide for debt/overdraft; 400 for a
+            // request-validity error (wrong unit) is permitted and consistent with reserve/event.
+            Map<String, Object> body = new HashMap<>();
+            body.put("idempotency_key", UUID.randomUUID().toString());
+            body.put("subject", Map.of("tenant", TENANT_A));
+            body.put("action", Map.of("kind", "llm.completion", "name", "test-model"));
+            body.put("estimate", Map.of("unit", "USD_MICROCENTS", "amount", 1000));
+
+            ResponseEntity<Map> resp = post("/v1/decide", API_KEY_SECRET_A, body);
+
+            assertThat(resp.getStatusCode().value()).isEqualTo(400);
+            assertThat(resp.getBody().get("error")).isEqualTo("UNIT_MISMATCH");
+            Map<String, Object> details = (Map<String, Object>) resp.getBody().get("details");
+            assertThat(details).isNotNull();
+            assertThat(details.get("scope")).isEqualTo("tenant:" + TENANT_A);
+            assertThat(details.get("requested_unit")).isEqualTo("USD_MICROCENTS");
+            assertThat((List<String>) details.get("expected_units")).contains("TOKENS");
+        }
+
+        @Test
+        void shouldReturnDenyBudgetNotFoundOnDecideWhenNoBudgetAtAnyUnit() {
+            // Regression guard: when no budget exists at ANY unit for the scope, decide still
+            // returns 200 DENY with reason_code=BUDGET_NOT_FOUND (the probe found nothing).
+            try (Jedis jedis = jedisPool.getResource()) {
+                jedis.del("budget:tenant:" + TENANT_A + ":TOKENS");
+            }
+
+            ResponseEntity<Map> resp = post("/v1/decide", API_KEY_SECRET_A,
+                    decisionBody(TENANT_A, 1000));
+
+            assertThat(resp.getStatusCode().value()).isEqualTo(200);
+            assertThat(resp.getBody().get("decision")).isEqualTo("DENY");
+            assertThat(resp.getBody().get("reason_code")).isEqualTo("BUDGET_NOT_FOUND");
+        }
     }
 
     @Nested
@@ -185,8 +224,9 @@ void shouldRejectEventWithMissingSubject() {
 
         @Test
         void shouldRejectEventWithUnitMismatch() {
-            // Spec: event actual.unit not supported for the target scope MUST return error
-            // Budget is seeded for TOKENS only; USD_MICROCENTS has no budget → BUDGET_NOT_FOUND
+            // Spec: event actual.unit not supported for the target scope MUST return UNIT_MISMATCH.
+            // Budget seeded for TOKENS at tenant:tenant-a; request USD_MICROCENTS → Lua probes
+            // alternate units, finds TOKENS, returns UNIT_MISMATCH (400) with expected_units.
             Map<String, Object> body = new HashMap<>();
             body.put("idempotency_key", UUID.randomUUID().toString());
             body.put("subject", Map.of("tenant", TENANT_A));
@@ -195,6 +235,26 @@ void shouldRejectEventWithUnitMismatch() {
 
             ResponseEntity<Map> resp = post("/v1/events", API_KEY_SECRET_A, body);
 
+            assertThat(resp.getStatusCode().value()).isEqualTo(400);
+            assertThat(resp.getBody().get("error")).isEqualTo("UNIT_MISMATCH");
+            Map<String, Object> details = (Map<String, Object>) resp.getBody().get("details");
+            assertThat(details).isNotNull();
+            assertThat(details.get("scope")).isEqualTo("tenant:" + TENANT_A);
+            assertThat(details.get("requested_unit")).isEqualTo("USD_MICROCENTS");
+            assertThat((List<String>) details.get("expected_units")).contains("TOKENS");
+        }
+
+        @Test
+        void shouldReturnBudgetNotFoundWhenNoBudgetAtAnyUnitOnEvent() {
+            // Remove the seeded TOKENS budget so the scope has no budget at ANY unit.
+            // Regression guard: event.lua probe falls through to BUDGET_NOT_FOUND (404).
+            try (Jedis jedis = jedisPool.getResource()) {
+                jedis.del("budget:tenant:" + TENANT_A + ":TOKENS");
+            }
+
+            ResponseEntity<Map> resp = post("/v1/events", API_KEY_SECRET_A,
+                    eventBody(TENANT_A, 500));
+
             assertThat(resp.getStatusCode().value()).isEqualTo(404);
             assertThat(resp.getBody().get("error")).isEqualTo("NOT_FOUND");
         }

cycles-protocol-service/cycles-protocol-service-api/src/test/java/io/runcycles/protocol/api/ReservationLifecycleIntegrationTest.java

@@ -173,16 +173,53 @@ void shouldRejectMissingIdempotencyKey() {
         }
 
         @Test
-        void shouldRejectWhenNoBudgetExistsForUnit() {
-            // No budget seeded for USD_MICROCENTS unit — Lua returns BUDGET_NOT_FOUND → 404
+        void shouldRejectWithUnitMismatchWhenBudgetExistsInDifferentUnit() {
+            // Budget seeded at tenant:tenant-a in TOKENS. Request USD_MICROCENTS → Lua probes
+            // alternate units, finds TOKENS, returns UNIT_MISMATCH (400) with expected_units.
             Map<String, Object> body = reservationBody(TENANT_A, 1000, "USD_MICROCENTS");
 
             ResponseEntity<Map> resp = post("/v1/reservations", API_KEY_SECRET_A, body);
 
+            assertThat(resp.getStatusCode().value()).isEqualTo(400);
+            assertThat(resp.getBody().get("error")).isEqualTo("UNIT_MISMATCH");
+            Map<String, Object> details = (Map<String, Object>) resp.getBody().get("details");
+            assertThat(details).isNotNull();
+            assertThat(details.get("scope")).isEqualTo("tenant:" + TENANT_A);
+            assertThat(details.get("requested_unit")).isEqualTo("USD_MICROCENTS");
+            assertThat((List<String>) details.get("expected_units")).contains("TOKENS");
+        }
+
+        @Test
+        void shouldReturnBudgetNotFoundWhenNoBudgetAtAnyUnit() {
+            // Remove the seeded TOKENS budget so the scope has no budget at ANY unit.
+            // Regression guard: BUDGET_NOT_FOUND (404) still wins when the probe finds nothing.
+            try (Jedis jedis = jedisPool.getResource()) {
+                jedis.del("budget:tenant:" + TENANT_A + ":TOKENS");
+            }
+
+            ResponseEntity<Map> resp = post("/v1/reservations", API_KEY_SECRET_A,
+                    reservationBody(TENANT_A, 1000, "TOKENS"));
+
             assertThat(resp.getStatusCode().value()).isEqualTo(404);
             assertThat(resp.getBody().get("error")).isEqualTo("NOT_FOUND");
         }
 
+        @Test
+        void shouldReturnUnitMismatchOnDryRunWhenBudgetExistsInDifferentUnit() {
+            // Symmetric probe in evaluateDryRun: dry_run with wrong unit should 400 UNIT_MISMATCH,
+            // not silently DENY with reason_code=BUDGET_NOT_FOUND.
+            Map<String, Object> body = reservationBody(TENANT_A, 1000, "USD_MICROCENTS");
+            body.put("dry_run", true);
+
+            ResponseEntity<Map> resp = post("/v1/reservations", API_KEY_SECRET_A, body);
+
+            assertThat(resp.getStatusCode().value()).isEqualTo(400);
+            assertThat(resp.getBody().get("error")).isEqualTo("UNIT_MISMATCH");
+            Map<String, Object> details = (Map<String, Object>) resp.getBody().get("details");
+            assertThat(details).isNotNull();
+            assertThat((List<String>) details.get("expected_units")).contains("TOKENS");
+        }
+
         @Test
         void shouldRejectSubjectWithOnlyDimensions() {
             Map<String, Object> body = new HashMap<>();

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

@@ -2,6 +2,8 @@
 
 import io.runcycles.protocol.model.Enums;
 import lombok.Getter;
+import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 
 /** Cycles Protocol v0.1.25 */
@@ -55,6 +57,16 @@ public static CyclesProtocolException idempotencyMismatch() {
     public static CyclesProtocolException unitMismatch() {
         return new CyclesProtocolException(Enums.ErrorCode.UNIT_MISMATCH, "Provided units does not match the stored ones", 400);
     }
+    public static CyclesProtocolException unitMismatch(String scope, String requestedUnit, List<String> expectedUnits) {
+        Map<String, Object> details = new LinkedHashMap<>();
+        if (scope != null) details.put("scope", scope);
+        if (requestedUnit != null) details.put("requested_unit", requestedUnit);
+        if (expectedUnits != null) details.put("expected_units", expectedUnits);
+        String message = String.format(
+            "Budget at scope '%s' exists but in a different unit (requested: %s, expected: %s)",
+            scope, requestedUnit, expectedUnits);
+        return new CyclesProtocolException(Enums.ErrorCode.UNIT_MISMATCH, message, 400, details);
+    }
     public static CyclesProtocolException reservationExpired() {
         return new CyclesProtocolException(Enums.ErrorCode.RESERVATION_EXPIRED, "Provided reservation has already expired", 410);
     }