Merge pull request #61 from runcycles/claude/add-ledger-allocation-aWj3W

Fix debt handling: allow reservations when debt within overdraft limit

Author: amavashev

.claude/settings.json

@@ -12,5 +12,26 @@
                 ]
             }
         ]
+    },
+    "attribution": {
+        "commit": "",
+        "pr": ""
+    },
+    "permissions": {
+        "allow": [
+            "Bash(git add:*)",
+            "Bash(git commit:*)",
+            "Bash(git push:*)",
+            "Bash(git pull:*)",
+            "Bash(git status:*)",
+            "Bash(git diff:*)",
+            "Bash(git log:*)"
+        ],
+        "deny": [
+            "mcp__github__create_or_update_file",
+            "mcp__github__push_files",
+            "mcp__github__create_or_update_files",
+            "mcp__github__delete_file"
+        ]
     }
-}
+}

AUDIT.md

@@ -45,7 +45,7 @@ Two-pass audit covering:
 - Response headers (X-Request-Id, X-Cycles-Tenant, X-RateLimit-*)
 - Lua script atomicity for reserve, commit, release, extend, event, expire
 - Dry-run response rules (reservation_id/expires_at_ms absent, affected_scopes populated)
-- Overdraft/debt model (ALLOW_WITH_OVERDRAFT, is_over_limit, DEBT_OUTSTANDING)
+- Overdraft/debt model (ALLOW_WITH_OVERDRAFT, is_over_limit, DEBT_OUTSTANDING — only blocks when overdraft_limit=0; ALLOW_WITH_OVERDRAFT falls back to ALLOW_IF_AVAILABLE when overdraft_limit=0)
 - Grace period semantics (commits accepted through expires_at_ms + grace_period_ms)
 - Subject.dimensions round-tripping
 - Unit mismatch detection on commit and event

CLAUDE.md

@@ -1,5 +1,17 @@
 # Cycles Protocol Server
 
+## Git Rules — STRICT
+- ALWAYS use native git for ALL commits and pushes
+- NEVER use mcp__github__ tools for committing or pushing
+- Use mcp__github__ ONLY for: PRs, Issues, GitHub Actions
+- Write commit messages to a temp file, then: git commit -F <file>
+- NEVER use --no-gpg-sign flag
+
+# Cycles strict rules
+- yaml API specs always the authority
+- always udated AUDIT.md files when making changes to server, admin, client repos
+- maintain at least 95% or higher test coverage for all code repos
+
 ## Maven Builds
 
 In Claude Code remote environments, use `mvn-proxy` instead of `mvn` for all Maven commands.

cycles-protocol-service/README.md

@@ -160,8 +160,8 @@ When `overage_policy` is omitted from the request, the server resolves it from t
 
 - If `overdraft_limit` is absent or `0`, no overdraft is permitted (`ALLOW_WITH_OVERDRAFT` behaves as `ALLOW_IF_AVAILABLE`).
 - **`debt`** is created when `overage_policy=ALLOW_WITH_OVERDRAFT` and the commit delta exceeds remaining budget.
-- When `debt > 0`, **new reservations** against that scope are blocked with `409 DEBT_OUTSTANDING`.
-- When `debt > overdraft_limit`, the scope enters **over-limit** state (`is_over_limit=true`). New reservations are then blocked with `409 OVERDRAFT_LIMIT_EXCEEDED` (takes precedence over `DEBT_OUTSTANDING`).
+- When `debt > 0` and no `overdraft_limit` is configured (absent or `0`), **new reservations** against that scope are blocked with `409 DEBT_OUTSTANDING`. When an `overdraft_limit > 0` is set, debt within the limit does **not** block new reservations.
+- When `debt > overdraft_limit`, the scope enters **over-limit** state (`is_over_limit=true`). New reservations are then blocked with `409 OVERDRAFT_LIMIT_EXCEEDED`.
 - Debt does **not** block direct events (`/v1/events`); events always apply their own `overage_policy`.
 - Existing active reservations MAY be committed or released normally while a scope is over-limit.
 - Overdraft limit checks are per-commit and are **not** atomic across concurrent commits — concurrent commits may independently pass the check, causing total debt to temporarily exceed `overdraft_limit`. This is by design; the `is_over_limit` flag prevents further damage.
@@ -593,7 +593,7 @@ All errors use this envelope:
 | `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; new reservations blocked |
+| `DEBT_OUTSTANDING` | 409 | Scope has unresolved debt with no overdraft limit; new reservations blocked |
 | `RESERVATION_EXPIRED` | 410 | Operation attempted after expiry window |
 | `INTERNAL_ERROR` | 500 | Unexpected server error |
 

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

@@ -662,21 +662,16 @@ void shouldReturnSameDecisionOnReplay() {
         }
 
         @Test
-        void shouldReturnDenyWithReasonCodeWhenDebtOutstanding() {
-            // Spec: /decide SHOULD return decision=DENY with reason_code=DEBT_OUTSTANDING when debt > 0
-            // Create debt: drain budget then overdraft commit
-            String drain = createReservationAndGetId(TENANT_A, API_KEY_SECRET_A, 950_000);
-            post("/v1/reservations/" + drain + "/commit", API_KEY_SECRET_A, commitBody(950_000));
-
-            Map<String, Object> overdraftBody = reservationBody(TENANT_A, 1000);
-            overdraftBody.put("overage_policy", "ALLOW_WITH_OVERDRAFT");
-            ResponseEntity<Map> reserveResp = post("/v1/reservations", API_KEY_SECRET_A, overdraftBody);
-            String overdraftResId = (String) reserveResp.getBody().get("reservation_id");
-            post("/v1/reservations/" + overdraftResId + "/commit",
-                    API_KEY_SECRET_A, commitBody(100_000));
-            // debt > 0 now
+        void shouldReturnDenyWithReasonCodeWhenDebtOutstandingAndNoOverdraftLimit() {
+            // Spec (decide): "If the subject scope has debt > 0 ... server SHOULD return
+            // decision=DENY with reason_code=DEBT_OUTSTANDING"
+            // This applies when overdraft_limit=0 (no policy allowing debt).
+            try (Jedis jedis = jedisPool.getResource()) {
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "overdraft_limit", "0");
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "debt", "5000");
+            }
 
-            // /decide MUST NOT return 409, SHOULD return 200 with decision=DENY
+            // /decide MUST NOT return 409 — returns 200 with decision=DENY
             ResponseEntity<Map> resp = post("/v1/decide", API_KEY_SECRET_A,
                     decisionBody(TENANT_A, 100));
 
@@ -685,6 +680,22 @@ void shouldReturnDenyWithReasonCodeWhenDebtOutstanding() {
             assertThat(resp.getBody().get("reason_code")).isEqualTo("DEBT_OUTSTANDING");
         }
 
+        @Test
+        void shouldReturnAllowWhenDebtWithinOverdraftLimit() {
+            // Spec: "When debt > 0, new reservations MUST be rejected ... (unless explicitly
+            // allowed by policy)." — overdraft_limit > 0 is the explicit policy.
+            // /decide mirrors this: debt within limit → ALLOW.
+            try (Jedis jedis = jedisPool.getResource()) {
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "debt", "5000");
+            }
+
+            ResponseEntity<Map> resp = post("/v1/decide", API_KEY_SECRET_A,
+                    decisionBody(TENANT_A, 100));
+
+            assertThat(resp.getStatusCode().value()).isEqualTo(200);
+            assertThat(resp.getBody().get("decision")).isEqualTo("ALLOW");
+        }
+
         @Test
         void shouldReturnAffectedScopesInDecision() {
             ResponseEntity<Map> resp = post("/v1/decide", API_KEY_SECRET_A,
@@ -1876,6 +1887,90 @@ void shouldRejectEventWhenOverdraftLimitExceeded() {
             assertThat(resp.getBody().get("error")).isEqualTo("OVERDRAFT_LIMIT_EXCEEDED");
         }
 
+        @Test
+        void shouldFallbackToAllowIfAvailableWhenOverdraftLimitZeroOnCommit() {
+            // Spec: "If overdraft_limit is absent or 0, no overdraft is permitted
+            // (behaves as ALLOW_IF_AVAILABLE)."
+            // ALLOW_IF_AVAILABLE: "cap delta to available remaining (minimum across
+            // all affected scopes, floor 0), charge estimate + capped_delta, and set
+            // is_over_limit=true on scopes where the full delta could not be covered."
+            try (Jedis jedis = jedisPool.getResource()) {
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "overdraft_limit", "0");
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "remaining", "50000");
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "spent", "950000");
+            }
+
+            // Reserve 1000, then commit 100_000 (overage delta=99_000 > remaining=49_000)
+            // With overdraft_limit=0, should cap like ALLOW_IF_AVAILABLE, not reject.
+            Map<String, Object> body = reservationBody(TENANT_A, 1000);
+            body.put("overage_policy", "ALLOW_WITH_OVERDRAFT");
+            ResponseEntity<Map> reserveResp = post("/v1/reservations", API_KEY_SECRET_A, body);
+            String resId = (String) reserveResp.getBody().get("reservation_id");
+
+            ResponseEntity<Map> commitResp = post(
+                    "/v1/reservations/" + resId + "/commit",
+                    API_KEY_SECRET_A, commitBody(100_000));
+
+            // Spec: commit always succeeds with ALLOW_IF_AVAILABLE fallback (never rejects)
+            assertThat(commitResp.getStatusCode().value()).isEqualTo(200);
+            // Spec: "charged = estimate + capped_delta" — must be less than actual
+            Map<String, Object> charged = (Map<String, Object>) commitResp.getBody().get("charged");
+            long chargedAmount = ((Number) charged.get("amount")).longValue();
+            assertThat(chargedAmount).isLessThan(100_000);
+            assertThat(chargedAmount).isGreaterThan(0);
+
+            // Spec: "set is_over_limit=true on scopes where full delta could not be covered"
+            ResponseEntity<Map> balanceResp = get(
+                    "/v1/balances?tenant=" + TENANT_A, API_KEY_SECRET_A);
+            var balances = (java.util.List<Map<String, Object>>) balanceResp.getBody().get("balances");
+            Map<String, Object> bal = balances.get(0);
+            assertThat(bal.get("is_over_limit")).isEqualTo(true);
+
+            // Spec: ALLOW_IF_AVAILABLE "never creates debt"
+            Map<String, Object> debt = (Map<String, Object>) bal.get("debt");
+            long debtAmount = debt != null ? ((Number) debt.get("amount")).longValue() : 0;
+            assertThat(debtAmount).isEqualTo(0);
+        }
+
+        @Test
+        void shouldFallbackToAllowIfAvailableWhenOverdraftLimitZeroOnEvent() {
+            // Spec: "If overdraft_limit is absent or 0, no overdraft is permitted
+            // (behaves as ALLOW_IF_AVAILABLE)."
+            // ALLOW_IF_AVAILABLE for events: "cap the charge to available remaining ...
+            // and set is_over_limit=true on scopes where the full amount could not be covered."
+            try (Jedis jedis = jedisPool.getResource()) {
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "overdraft_limit", "0");
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "remaining", "50000");
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "spent", "950000");
+            }
+
+            // Event for 500_000 (exceeds remaining 50_000)
+            Map<String, Object> body = eventBody(TENANT_A, 500_000);
+            body.put("overage_policy", "ALLOW_WITH_OVERDRAFT");
+
+            ResponseEntity<Map> resp = post("/v1/events", API_KEY_SECRET_A, body);
+
+            // Spec: event always succeeds (never rejects with ALLOW_IF_AVAILABLE)
+            assertThat(resp.getStatusCode().value()).isEqualTo(201);
+            // Spec: "charged field present when ... caps the event charge to remaining budget"
+            assertThat(resp.getBody().get("charged")).isNotNull();
+            Map<String, Object> charged = (Map<String, Object>) resp.getBody().get("charged");
+            long chargedAmount = ((Number) charged.get("amount")).longValue();
+            assertThat(chargedAmount).isEqualTo(50_000);
+
+            // Spec: "set is_over_limit=true on scopes where full amount could not be covered"
+            ResponseEntity<Map> balanceResp = get(
+                    "/v1/balances?tenant=" + TENANT_A, API_KEY_SECRET_A);
+            var balances = (java.util.List<Map<String, Object>>) balanceResp.getBody().get("balances");
+            Map<String, Object> bal = balances.get(0);
+            assertThat(bal.get("is_over_limit")).isEqualTo(true);
+
+            // Spec: ALLOW_IF_AVAILABLE "never creates debt"
+            Map<String, Object> debt = (Map<String, Object>) bal.get("debt");
+            long debtAmount = debt != null ? ((Number) debt.get("amount")).longValue() : 0;
+            assertThat(debtAmount).isEqualTo(0);
+        }
+
         @Test
         void shouldMaintainLedgerInvariantAfterCommit() {
             // allocated = remaining + spent + reserved + debt (spec invariant)
@@ -2378,34 +2473,39 @@ void shouldReturnSignedAmountForRemaining() {
     class DebtOutstanding {
 
         @Test
-        void shouldRejectNewReservationWhenDebtOutstanding() {
-            // Drain budget so overdraft commit creates debt.
-            // Budget: allocated=1_000_000, overdraft_limit=100_000
-            String drain = createReservationAndGetId(TENANT_A, API_KEY_SECRET_A, 950_000);
-            post("/v1/reservations/" + drain + "/commit", API_KEY_SECRET_A, commitBody(950_000));
-            // remaining=50_000
-
-            // Create overdraft reservation and commit to create debt
-            Map<String, Object> overdraftBody = reservationBody(TENANT_A, 1000);
-            overdraftBody.put("overage_policy", "ALLOW_WITH_OVERDRAFT");
-            ResponseEntity<Map> reserveResp = post("/v1/reservations", API_KEY_SECRET_A, overdraftBody);
-            String overdraftResId = (String) reserveResp.getBody().get("reservation_id");
-            // remaining=49_000
-
-            // Commit with overage that creates debt: delta=99_000, remaining=49_000
-            // funded=49_000, deficit=50_000 ≤ 100_000 → allowed
-            post("/v1/reservations/" + overdraftResId + "/commit",
-                    API_KEY_SECRET_A, commitBody(100_000));
-            // Now debt=50_000 > 0
+        void shouldRejectNewReservationWhenDebtOutstandingAndNoOverdraftLimit() {
+            // Spec: "When debt > 0, new reservations MUST be rejected with 409
+            // DEBT_OUTSTANDING (unless explicitly allowed by policy)."
+            // overdraft_limit=0 means no policy allowing debt → MUST reject.
+            try (Jedis jedis = jedisPool.getResource()) {
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "overdraft_limit", "0");
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "debt", "1000");
+            }
 
-            // New reservation should be blocked with DEBT_OUTSTANDING
             ResponseEntity<Map> newResp = post("/v1/reservations", API_KEY_SECRET_A,
                     reservationBody(TENANT_A, 100));
 
             assertThat(newResp.getStatusCode().value()).isEqualTo(409);
             assertThat(newResp.getBody().get("error")).isEqualTo("DEBT_OUTSTANDING");
         }
 
+        @Test
+        void shouldAllowNewReservationWhenDebtWithinOverdraftLimit() {
+            // Spec: "When debt > 0, new reservations MUST be rejected ... (unless
+            // explicitly allowed by policy)." — overdraft_limit > 0 is the explicit
+            // policy that tolerates debt up to the limit.
+            // Budget: allocated=1_000_000, overdraft_limit=100_000, debt=5_000.
+            try (Jedis jedis = jedisPool.getResource()) {
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "debt", "5000");
+            }
+
+            ResponseEntity<Map> newResp = post("/v1/reservations", API_KEY_SECRET_A,
+                    reservationBody(TENANT_A, 100));
+
+            assertThat(newResp.getStatusCode().value()).isEqualTo(200);
+            assertThat(newResp.getBody().get("decision")).isEqualTo("ALLOW");
+        }
+
         @Test
         void shouldAllowCommitAndReleaseOnExistingReservationsDespiteDebt() {
             // Spec: existing reservations may commit/release normally even when debt > 0
@@ -2483,18 +2583,15 @@ void shouldReturnOverdraftLimitExceededWhenOverLimit() {
         }
 
         @Test
-        void shouldReturnDebtOutstandingWhenNotOverLimit() {
-            // When debt > 0 but is_over_limit=false, should return DEBT_OUTSTANDING
-            String drain = createReservationAndGetId(TENANT_A, API_KEY_SECRET_A, 950_000);
-            post("/v1/reservations/" + drain + "/commit", API_KEY_SECRET_A, commitBody(950_000));
-
-            Map<String, Object> overdraftBody = reservationBody(TENANT_A, 1000);
-            overdraftBody.put("overage_policy", "ALLOW_WITH_OVERDRAFT");
-            ResponseEntity<Map> reserveResp = post("/v1/reservations", API_KEY_SECRET_A, overdraftBody);
-            String overdraftResId = (String) reserveResp.getBody().get("reservation_id");
-            post("/v1/reservations/" + overdraftResId + "/commit",
-                    API_KEY_SECRET_A, commitBody(100_000));
-            // debt=50_000 > 0, is_over_limit=false
+        void shouldReturnDebtOutstandingWhenNotOverLimitAndNoOverdraftLimit() {
+            // Spec precedence: is_over_limit check → DEBT_OUTSTANDING check → BUDGET_EXCEEDED.
+            // "When is_over_limit=true, server MUST return OVERDRAFT_LIMIT_EXCEEDED ...
+            //  This takes precedence over DEBT_OUTSTANDING."
+            // Here is_over_limit=false, overdraft_limit=0, debt>0 → DEBT_OUTSTANDING.
+            try (Jedis jedis = jedisPool.getResource()) {
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "overdraft_limit", "0");
+                jedis.hset("budget:tenant:" + TENANT_A + ":TOKENS", "debt", "5000");
+            }
 
             ResponseEntity<Map> newResp = post("/v1/reservations", API_KEY_SECRET_A,
                     reservationBody(TENANT_A, 100));

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

@@ -202,7 +202,8 @@ private ReservationCreateResponse evaluateDryRun(Jedis jedis, ReservationCreateR
                     .build();
             }
             long debt = Long.parseLong(budget.getOrDefault("debt", "0"));
-            if (debt > 0) {
+            long overdraftLimit = Long.parseLong(budget.getOrDefault("overdraft_limit", "0"));
+            if (debt > 0 && overdraftLimit == 0) {
                 return ReservationCreateResponse.builder()
                     .decision(Enums.DecisionEnum.DENY)
                     .reasonCode("DEBT_OUTSTANDING")
@@ -689,7 +690,8 @@ public DecisionResponse decide(DecisionRequest request, String tenant) {
                     break;
                 }
                 long debt = Long.parseLong(budget.getOrDefault("debt", "0"));
-                if (debt > 0) {
+                long overdraftLimit = Long.parseLong(budget.getOrDefault("overdraft_limit", "0"));
+                if (debt > 0 && overdraftLimit == 0) {
                     response = DecisionResponse.builder()
                         .decision(Enums.DecisionEnum.DENY)
                         .reasonCode("DEBT_OUTSTANDING")