How Halvr enforces spend before a provider call.

The Next.js application owns authentication, project settings, provider credentials, billing, dashboard reads, and the provider-compatible proxy endpoint. PostgreSQL is the transactional system of record for users, projects, keys, settings, request compatibility data, audits, and durable sink receipts.

Three Redis roles are isolated: budget Redis stores non-evicting reservations and rolling usage buckets; cache Redis can evict response entries; stream Redis durably transports usage events. ClickHouse serves analytical facts and Cloudflare R2 stores time-windowed NDJSON audit batches.

Halvr authenticates the project key, derives customer, feature, session, and tool context, resolves routing, and applies policy. Exact and semantic cache hits return before provider-spend reservation because they do not create a new provider charge.

A cache miss must resolve to an active catalog price or an explicitly priced custom endpoint. Halvr estimates input tokens and a policy-bounded output ceiling, converts the estimate to integer micro-USD, and sends all applicable scopes to one Lua reservation operation.

Reconciliation is idempotent. While a reservation is active, one atomic operation applies actual cost minus estimated cost and moves the record to RECONCILED. A larger actual amount is allowed for the completed request, recorded as an overage, and visible to future budget checks.

Provider failure releases the full estimate. Expiration remains conservative and keeps the estimate in the live bucket because Halvr cannot assume a timed-out process spent nothing. Late results become durable adjustments instead of mutating a fenced terminal reservation.

The proxy writes canonical events to stream Redis before response completion where billing or audit durability matters. Consumers are asynchronous, but the stream append is not a fire-and-forget task after the response.

Every sink deduplicates on the request idempotency key, event type, and deterministic phase. ClickHouse uses a versioned replacing strategy, R2 writes deterministic batched object keys, and PostgreSQL receipts record successful delivery independently for each sink.

Free and Performance plans fail closed. Managed-Spend also defaults closed but can explicitly enable a five-minute fail-open window. The runtime billing entitlement overrides stale project configuration, so a lower plan cannot activate degraded admission by changing a row.

A degraded request carries its original budget scopes in the durable usage event. The budget-recovery consumer applies actual cost to the original UTC buckets after Redis recovers, using a 34-day idempotency fence so redelivery cannot charge twice.

Budget Redis v1 is a single-node service, or must be client-sharded by project. The multi-scope Lua operation passes keys through arguments and is not compatible with arbitrary Redis Cluster slots. It uses AOF persistence and a no-eviction policy because losing live buckets would make enforcement optimistic.

Stream and budget workloads remain isolated so telemetry volume cannot evict or delay the budget hot path. Stream trimming is skipped while any known consumer group has pending entries.