fix: reject negative costs, allow exact-zero budget, emit metric on exhaustion (§9.6) (#62 #84 #85 #97)

CostBudget::consume() now throws InvalidArgumentException for negative cost
metric values (no decrement) and only treats a counter as exhausted when it
goes negative, so a metric that lands exactly on zero is within budget.
JobContext::emitMetric() emits the consuming sample with budget_remaining='0'
before re-throwing BudgetExhaustedException.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: nficano

src/Runtime/CostBudget.php

@@ -58,17 +58,27 @@ public function consume(string $metricName, int|float $value, string $unit): ?st
         if (!str_starts_with($metricName, 'cost.') || $metricName === 'cost.budget.remaining') {
             return null;
         }
-        if (!isset($this->remaining[$unit]) || $value < 0) {
-            return null;
-        }
         if (\is_float($value) && (!is_finite($value) || is_nan($value))) {
             throw new InvalidArgumentException('cost metric value must be finite', [
                 'metric' => $metricName,
                 'value' => $value,
             ]);
         }
+        // §9.6: "Negative values are rejected and produce no decrement."
+        if ($value < 0) {
+            throw new InvalidArgumentException('cost metric value must not be negative', [
+                'metric' => $metricName,
+                'value' => $value,
+            ]);
+        }
+        if (!isset($this->remaining[$unit])) {
+            return null;
+        }
         $this->remaining[$unit] -= self::numericToScaled($value);
-        if ($this->remaining[$unit] <= 0) {
+        // A metric that consumes exactly the remaining balance lands on zero
+        // and is still within budget; only an overspend (negative remaining)
+        // exhausts the counter.
+        if ($this->remaining[$unit] < 0) {
             throw new BudgetExhaustedException($unit, $this->format($this->remaining[$unit]));
         }
         return $this->format($this->remaining[$unit]);

src/Runtime/JobContext.php

@@ -7,6 +7,7 @@
 use Amp\Cancellation;
 use Amp\DeferredCancellation;
 use Arcp\Envelope\Priority;
+use Arcp\Errors\BudgetExhaustedException;
 use Arcp\Errors\DeadlineExceededException;
 use Arcp\Errors\PermissionDeniedException;
 use Arcp\Ids\JobId;
@@ -102,7 +103,18 @@ public function emitLog(string $level, string $message, array $attributes = []):
     public function emitMetric(string $name, int|float $value, string $unit, array $dims = []): void
     {
         $job = $this->runtime->jobs->tryGet($this->jobId);
-        $remaining = $job?->budget?->consume($name, $value, $unit);
+        try {
+            $remaining = $job?->budget?->consume($name, $value, $unit);
+        } catch (BudgetExhaustedException $e) {
+            // Surface the consuming sample to observers before unwinding so
+            // the metric that exhausted the budget is not lost.
+            $dims['budget_remaining'] = '0';
+            $this->runtime->emit($this->session, new MetricEvent($name, $value, $unit, $dims), [
+                'job_id' => $this->jobId,
+                'trace_id' => $this->traceId,
+            ]);
+            throw $e;
+        }
         if ($remaining !== null) {
             $dims['budget_remaining'] = $remaining;
         }

tests/Integration/JobLifecycleTest.php

@@ -292,7 +292,7 @@ public function testCostBudgetExhaustionFailsJob(): void
             public function invoke(array $arguments, JobContext $ctx, ?Cancellation $cancellation = null): mixed
             {
                 $ctx->emitMetric('cost.search', 0.60, 'USD');
-                $ctx->emitMetric('cost.search', 0.40, 'USD');
+                $ctx->emitMetric('cost.search', 0.50, 'USD');
                 return ['ok' => true];
             }
         });

tests/Unit/Runtime/CostBudgetTest.php

@@ -79,4 +79,29 @@ public function testPatternAcceptsExactlySixDecimals(): void
         $budget = CostBudget::fromPatterns(['USD:0.000001']);
         self::assertSame(['USD' => '0.000001'], $budget->remaining());
     }
+
+    public function testConsumeRejectsNegativeValue(): void
+    {
+        $budget = CostBudget::fromPatterns(['USD:1.00']);
+        try {
+            $budget->consume('cost.refund', -1, 'USD');
+            self::fail('expected InvalidArgumentException');
+        } catch (InvalidArgumentException) {
+            // §9.6: negative values are rejected and produce no decrement.
+        }
+        self::assertSame(['USD' => '1'], $budget->remaining());
+    }
+
+    public function testConsumingExactRemainingReturnsZeroWithoutExhausting(): void
+    {
+        $budget = CostBudget::fromPatterns(['USD:1.00']);
+        self::assertSame('0', $budget->consume('cost.inference', 1.00, 'USD'));
+    }
+
+    public function testConsumingBeyondRemainingExhausts(): void
+    {
+        $budget = CostBudget::fromPatterns(['USD:1.00']);
+        $this->expectException(\Arcp\Errors\BudgetExhaustedException::class);
+        $budget->consume('cost.inference', 1.01, 'USD');
+    }
 }

tests/Unit/Runtime/V11FeaturesTest.php

@@ -42,7 +42,8 @@ public function testCostBudgetThrowsWhenExhausted(): void
     {
         $budget = CostBudget::fromPatterns(['USD:0.10']);
         $this->expectException(BudgetExhaustedException::class);
-        $budget->consume('cost.search', 0.10, 'USD');
+        // Overspending the counter (not merely landing on zero) exhausts it.
+        $budget->consume('cost.search', 0.11, 'USD');
     }
 
     public function testCostBudgetSubsetUsesRemainingBudget(): void