Reserve Funds Without Counting a Captured Payment Twice

A customer has 97600 USD minor units posted to their deposit account. An outgoing authorization reserves 30000. After 12000 is captured, how much remains available?

The answer is 67600. Posted funds fall to 85600, while the uncaptured reservation falls to 18000. Subtracting the original 30000 again would report 55600 and count the captured 12000 twice.

This tutorial makes that bridge explicit, then implements the reservation lifecycle with durable operation identity and atomic journal posting. Operations staff can explain the remaining reservation; engineers can verify what concurrent requests and failed captures leave behind. Every example concerns fictional Cedar Teaching Bank, not a real customer's payment.

A reservation is a promise of capacity

The Available/Ledger Balance Calculation tutorial distinguishes posted deposit balance from spendable capacity. This topic owns the write decisions that keep that distinction coherent.

Let L be a credit-normal customer deposit liability balance, H effective remaining outgoing holds, and A available capacity. Cedar's selected teaching product uses A=L−H, with credit limit zero and pending incoming contributing nothing. A new reserve q must satisfy q<=A. Exact equality is permitted; one minor unit above is rejected.

A hold does not itself debit the financial ledger. Capture does: debit the customer's deposit liability and credit a trusted settlement-payable liability. Actual cash settlement comes later. This bank perspective follows Double-Entry Posting Engine; debit does not universally mean the same direction for every account type.

Real providers separate authorization and capture, but supported methods, deadlines and capabilities vary. Stripe's documentation provides one bounded comparison. Cedar's explicit lifecycle is a teaching choice, with no adopted card-network window or claimed provider integration.

Keep the full hold decomposition

Each hold retains scoped entity/ledger/account/currency identity, original amount, cumulative captured amount, cumulative released amount, remaining amount, created/updated/expiry timestamps, version and stored status.

original = captured + released + remaining

All amounts are exact decimal strings. Original is positive through 30 digits; the other components are nonnegative through 30 digits. USD-only writes use exponent 2. Python integers, TypeScript BigInt and SQL numeric sums avoid binary floating-point money.

An active hold has positive remaining and no released amount; earlier partial captures may exist. Captured, released and expired are terminal states with remaining zero. A final partial capture can close as captured while also releasing unused remainder. Released/expired rows may retain earlier captured value.

Terminal state is not the whole time rule. An active stored row may remain after its deadline because a worker has not yet persisted expiry. Reads count its remaining amount only while as_of<expires_at. At exact equality it contributes zero and reports effective_expired. A late worker cannot keep the customer's capacity reserved indefinitely in this variant.

Capture and release require trusted processing strictly before expiry. Expire requires processing at or after it. Supplying an earlier economic date cannot rescue a request that reaches the control after the deadline.

Follow the independently calculated bridge

The corrected Stage 1 Ada opening is 97600. Reserve 30000 and availability becomes 67600. Capture 12000 with final_capture=false: posted becomes 85600, remaining becomes 18000, and availability stays 67600.

Open the full-size capture bridge.

The unchanged availability is an identity:

(97600−12000) − (30000−12000) = 67600

Now capture 10000 with final_capture=true. Posted becomes 75600. The remaining 8000 is released without a financial debit, so effective holds become zero and available funds become 75600. The hold preserves 30000 = 22000 captured + 8000 released + 0 remaining.

The settlement payable increases 22000 while cash is unchanged. Ada 75600 plus Cora 2400 plus settlement payable 22000 still equals synthetic cash 100000. These are author-derived checks from synthetic inputs, not a fee tariff or settlement observation. Independent arithmetic fixture.

The selected partial/final distinction must be explicit. A provider may require special capability to retain uncaptured funds; Stripe's capture API documents its own optional behavior. Cedar does not silently inherit a provider default.

Make commands versioned and retryable

Every command includes its full scope, hold ID, durable hold-operation ID, action and versioned schema. Reserve adds amount and expiry. Capture adds expected version, amount, an actual boolean final_capture, journal identities and economic/source/booking fields. Release and expire add expected version and release all remaining capacity.

For a new capture, the expected version must match, the hold must still be active before expiry, amount must not exceed remaining, and currently posted funds must cover that amount. Unknown keys, numeric money coercion, string booleans and malformed timestamps reject the whole candidate.

The operation identity is retained separately from the hold identity and capture journal identity. An exact accepted retry returns the original complete result, even after the hold later closes or current policy changes. A changed command under that identity conflicts. A failed attempt leaves no accepted identity, so its corrected retry can proceed. Idempotent Journal Posting explains that recovery boundary in detail.

Scope authorization still precedes replay; stable identity is not permission to retrieve another ledger's result. A newly identified capture also cannot adopt an independently posted journal as its own new side effect.

Commit the hold and journal together

In the PostgreSQL profile, all state-changing paths lock the same ledger-control row. The function checks trusted processing time after obtaining the lock, so a waiting capture cannot rely on when its client originally sent the request.

For capture, the function stages the new hold projection/version, builds the exact two-leg journal, invokes the reviewed posting core, appends an immutable hold event and accepted-operation result, then commits every effect together. If the journal's period validation fails, even the staged hold update rolls back. PostgreSQL's transaction boundary provides the platform mechanism; the acceptance test verifies this concrete implementation. Transactions, locking.

Reserve/release/expiry produce hold events but no financial journal. A separate hold-event counter therefore advances on these operations, while the journal sequence advances only when capture posts. Exact retries advance neither. The mutable hold projection is distinct from the immutable accepted event and journal history.

The hold-service login can execute the reviewed API and authorized current snapshot export. It cannot directly modify tables, switch to owner or call raw posting. Owner/bootstrap and unrelated posting authorities remain an explicit boundary: a hold guard cannot force an external debit path to obey a policy it did not invoke.

The current snapshot exporter also refuses to label a later projection with an earlier clock. Under the ledger lock it checks actual time against both journal and hold recording watermarks. It never reconstructs old hold state by filtering a current terminal row. Recording timestamps inside transactions are not exact physical COMMIT timestamps.

Verify the behavior on both surfaces

The portable Python/TypeScript models pass 54 scenarios / 98 complete actions with exact state/result/reason/nullability parity. Cases include partial/final/full capture, exact exhaustion, duplicate commands, release, expiry equality and one millisecond before, malformed money/booleans, huge integers, stale versions and invalid-journal rollback.

Those copied snapshots do not establish actual database contention or durability. The separate PostgreSQL 18.1 run uses its own task-owned loopback cluster and restricted authenticated sessions. Its 23 named groups verify competing reservations, duplicate captures producing one journal, capture/release in both orders, time checked after a real lock wait, staged hold/journal rollback, original replay after changed policy, direct-write denial, durable restart and the recording-watermark guards. SQL evidence, portable evidence, validation record.

The SQL test observes real processing before/after expiry; exact equality is deterministic in the portable cases. Controlled restart is not a hardware power-loss experiment. Local durability settings and role restrictions do not establish independent retention or production scalability.

Open the guided reservation lab. It bundles the actual TypeScript reference, records its source hash and lets you switch retained versus final first capture. Step the delayed-expiry worker, then compare releasing after a partial capture and an invalid journal. The static bridge above preserves the explanation without scripts.

The base SQL and reservation extension reproduce the isolated profile. The supplied runner initializes its own cluster rather than accepting a production DSN. The two actual current snapshots exported after partial and final capture are available separately for integration with the availability reader; the final snapshot closes the hold exactly.

The complete observed journal export also contains an independently read ledger-head sequence and a trusted first archive-observation receipt after acknowledged writes. It supports replay of the posted balance without inventing earlier archive availability or treating an in-transaction recording timestamp as physical COMMIT time.

Use the reservation for the decision it owns

This product reserves outgoing capacity and records exactly what was captured or released. It excludes incremental authorizations, hold extensions, partial releases, FX, overdraft facilities and card-network rule replication. Negative availability from unrelated external posting remains visible instead of being hidden by a clamp.

Historical example: not useful. Reproducible synthetic clocks, amounts and failure states teach the contract without invented customer incidents. Continue to Daily Simple Interest Accrual for a different calculation on trustworthy posted balances; a pending hold is not silently converted into a posted debit or interest rule.