v0.9.0 — Hard Budget Enforcement

v0.9.0 — Hard Budget Enforcement & Atomic Cost Control

💰 The Problem v0.8.x Had

v0.8.x tracked costs but had a check-then-act race under concurrency:

sessionBudget = $1.00

Request A: checks remaining = $0.60 → allowed
Request B: checks remaining = $0.60 → allowed

Both execute. Total = $1.20. Budget violated.

🔒 The v0.9.0 Solution

Atomic Reservation System — check + reserve happens synchronously in one event loop tick:

Request A: reserve $0.60 → ✅ committed $0.60
Request B: reserve $0.60 → ❌ rejected (only $0.40 available)

How It Works

const client = new HilbrasClient({
  budget: {
    sessionBudget: 1.00,
    perRequestBudget: 0.10,
  },
});

// Reservation lifecycle: RESERVE → EXECUTE → SETTLE/RELEASE
const reservation = client.cost.reserve("req_1", 0.60);
if (!reservation) throw new Error("Budget exceeded");

// After execution:
client.cost.settle("req_1", 0.45); // actual < reserved → refund $0.15

// Or on failure:
client.cost.release("req_1"); // free the reservation

Committed Cost Tracking

const report = client.costReport();
report.totalReserved;    // Pending reservations
report.committedCost;    // actual + reserved
report.remainingBudget;  // sessionBudget - committed

What's New

Feature	Description
Atomic reservation	Synchronous check+reserve (JS event loop safe)
Committed cost	actual + reserved = true spending ceiling
Reservation lifecycle	reserve → settle (actual cost) or release (failure)
Over-reservation	Actual > reserved is allowed (settles to actual)
Under-reservation	Unused budget returns to available pool
No leaked reservations	Guaranteed after terminal execution
Backward compatible	record() API still works

676 Tests Passing

36 new reservation tests covering lifecycle, concurrency, integrity, adversarial, and invariants.

---

Changelog: https://github.com/Hilbras/Hilbras-ai-sdk/blob/main/CHANGELOG.md