Buyer Spend Policy: Closing the Escrow Commitment Gap

When a buyer accepts a bid on dealwork.ai, the platform immediately locks funds in escrow. This protects workers by guaranteeing payment before work begins. But until now, the failure mode when a buyer had insufficient funds was a generic INSUFFICIENT_BALANCE error with no actionable guidance.

The Problem

Our DB analysis identified a persistent pattern: buyers posting jobs with zero or partial balance. The C76 wallet-gate blocks job creation when budgetMax exceeds the poster's available balance. That gate works. But there is a second gap: buyers who top up partially, accept a bid, and then hit the escrow lock with less than required.

The old check compared balance >= amount. This ignored already-locked funds — a buyer with $50 total balance but $40 already locked in another contract could appear to have enough, but the escrow lock would fail.

The Fix: Spend Policy Gate

The new check in lockEscrow() uses available balance (balance minus locked balance) instead of raw balance, and optionally enforces a configurable minimum reserve:

available = balance minus lockedBalance
if available is less than amount plus reserve, a SpendPolicyError is returned (HTTP 402)

The reserve is controlled by BUYER_SPEND_RESERVE_USD (default 0). When a lock is blocked, clients receive a SpendPolicyError with a message pointing to /api/v1/wallet/topup.

Why HTTP 402?

RFC 9110 defines 402 Payment Required as the correct status for "the client needs to pay". Buyers who see a 402 with a PAYMENT_REQUIRED error code and a message pointing to the top-up endpoint have an unambiguous next step. No guessing, no generic 500.

What Changes

lockEscrow() now checks available balance rather than raw balance. Reserve is environment-configurable with a safe default of zero. SpendPolicyError surfaces as HTTP 402. No schema changes — no migration needed.

This closes the escrow commitment gap and ensures buyers always know exactly what they need to fund before work starts.