Qualify existing reservation adapters for current wallet composition

Merged
SI
5d ago
+643-0

This successor integrates the existing API #1026 reservation adapters unchanged onto current main and corrects their wallet-composition documentation. Shared holds remain claims against the balance; pack holds are already deducted. Current refill, top-up and deduction writers are already atomic, so the old prerequisite text was stale.

Depends on https://github.com/recoupable/database/pull/134, which retains Database #115 and adds protection against legacy/pack debits consuming held funds, including a reproduced repeatable-read race. Original API #1026 and its branch remain untouched. No new HTTP/MCP operation or caller is enabled; adapter inputs, receipts and uncertainty classes remain byte-identical. Context's disabled request/pilot/module consumer is separate work under recoupable/app#2123; common accounting is #2105 milestone1, independent of hosting prices.

Validation: 696 focused API tests across122 files, production TypeScript, full lint and adapter formatting pass. Independent composition review passed; 11 original adapter/validation/test files verified byte-identical to #1026. Companion disposable SQL tests pass36 cases on PostgreSQL15/17 plus11 existing pack cases on17, with17 new composition tests independently rerun.

No production migration, grants, financial data, provider call, spending or pricing change. One-wallet enforcement and legacy pre-dispatch authorization remain prerequisites for live activation. Root retains review/merge/release authority; this draft is source preparation only.


Summary by cubic

Adds opt-in credit reservation adapters so paid AI work can hold credits before dispatch and settle exactly-once on the existing wallet, closing the race where concurrent requests all pass the balance preflight.

  • reserveCreditsOnce, settleCreditReservation, and releaseCreditReservation wrap the new database RPCs with validated inputs and typed receipts; no production caller is enabled.
  • Rolled-back database rejections (SQLSTATE 22023) throw CreditReservationRejected with the fixed reason, so callers can return a definite 402/409; lost replies and invalid receipts raise reconciliation errors that retain the same operation key.
  • Documents that shared holds are claims against the balance while pack holds are already deducted, so refill and top-up never see holds as consumption.

Activation requires the database reservation migration and wallet composition guard; this is source preparation only, with no spending, pricing, or financial data changes.