It tells you that the computed balance of the account on that date does not match the asserted amount. What went wrong is not specified — it could be: a missing transaction, a duplicate posting, a wrong amount on an existing transaction, a transaction on the wrong date, or a data entry typo.

What it doesn't tell you: when the error was introduced. The assertion date only establishes "the error occurred somewhere before this date." You need bisection (more assertions at earlier dates) to isolate the cause.

Date-based means the assertion checks the computed balance at the start of that calendar date, regardless of where the assertion appears in the file. This makes assertions order-independent — you can move them around in the file without changing their semantics.

File-order assertions (Ledger's approach) check the running balance at the point in the file where the assertion appears. Moving the assertion above or below a transaction changes whether it passes or fails. This is fragile: the same set of transactions can pass or fail depending on how the file is sorted.

Date-based is harder to use for intra-day disambiguation (two transactions on the same date cannot be separated by a date-based assertion), but it's much easier to reason about correctness.

Your only option is new Transfers. If debits are too high (the account shows less value than it should), submit a correcting Transfer that credits the account for the difference. If credits are too high, submit one that debits.

Convention:

1. Use code = CORRECTION (or whatever your enum value is for corrections)
2. Set user_data_128 to link back to the original erroneous Transfer's order ID
3. Document the correcting Transfer in your application's audit log

The historical record is never mutated. The correction is itself an auditable event with a timestamp. Reconstructing "what happened" is always possible: sum all Transfers (including corrections) for the account.

This is identical to how real accounting works: you never alter past entries, you post adjusting entries.

The discrepancy occurred between March 1 and April 5. Bisect:

1. Add a balance assertion at March 16. If it fails, the error is March 1–16. If it passes, the error is March 16–April 5.
2. Repeat: add an assertion at the midpoint of the failing range.
3. Continue until you isolate a single transaction or day.

At that point, compare that transaction against the bank statement to find the discrepancy (missing transaction, wrong amount, date mismatch).

This is why dense balance assertions have compounding value — not just as checkpoints, but as instruments that reduce bisection depth from O(n) to O(log n) over transaction count.

TigerBeetle rejects the pending transfer immediately with exceeds_credits. It does not wait until the transfer posts.

This is the "pessimistic" model: pending amounts are counted against the available balance immediately when the pending transfer is created. The rationale is that a pending transfer is a firm commitment — TigerBeetle guarantees that when the pending transfer eventually posts, it will not violate the balance invariant. The only way to guarantee this is to reserve the funds at pending time.

Consequence: you cannot create a pending transfer "speculatively" and hope it will be within limits by the time it posts. The limit is checked upfront.

flags.balancing_debit is a special modifier on a pending transfer that sets the transfer amount to the net credit balance of the debit account at the time of processing. In other words: instead of specifying a fixed amount, TigerBeetle computes max(0, credits_posted - debits_posted) on the debit account and uses that as the pending amount.

This is how the balance check works: if the destination account has a credit balance of X, the pending balancing_debit creates a pending debit of X on the destination and a pending credit of X on the control account. If X would cause the control account to violate credits_must_not_exceed_debits, the transfer — and the entire linked chain — fails.

The pending transfer is immediately voided (T3 in the recipe), so no funds actually move. The mechanism is purely an atomic balance probe.

Several things:

1. Window of invalidity: between the invalid state occurring and the batch job running, the system operated on incorrect data. If a user was shown a wrong balance and acted on it (a second withdrawal, a trade), the damage is already done.

2. At-scale detection latency: at high throughput, a $0.01 invariant violation per 1,000 transactions is financially material within hours. A daily batch check catches it only after 24 hours of compounding.

3. Race conditions in the batch job itself: computing the trial balance requires reading all accounts consistently. If transfers continue posting during the batch scan, the scan is not a consistent snapshot. You need either a full lock or a snapshot isolation — both expensive.

4. Structural enforcement is zero-cost at runtime: TigerBeetle's flag checks happen inside the already-running state machine. There is no additional overhead compared to no flags. The "batch job" approach has cost; the flag approach is essentially free.

Detective and preventive controls are complements. The batch job is the detective fallback; the flags are the primary prevention.

(a) ⌈log₂(31)⌉ = 5 steps. After 5 bisections you have narrowed to a single day (or transaction) among 31.

(b) The March 16 assertion passes (both agree at $4,050). The error is therefore in the March 16–31 window. Focus on the second half of March: add a March 24 assertion and repeat.

(c) In a single-entry system there is no trial balance invariant and no conservation property. "Correct" has no machine-checkable definition. You could not define what a balance assertion means because there is no counterpart posting to confirm. Any amount of missing, duplicated, or modified entries could produce a plausible balance. You would need to manually compare every transaction against an external record — no bisection is possible because there is no local invariant to test.

(a) The control account gets flags.credits_must_not_exceed_debits. This is the opposite of what we're enforcing on the destination (which has credit-normal balance). The control account's debit-normal flag is what creates the tripwire.

(b) After the $500 deposit posts (T1), Destination.credits_posted = 10,300. The balancing_debit pending transfer on T2 computes the destination's net credit balance: 10,300 - debits_posted. If debits_posted = 0, that's 10,300. T2 tries to create a pending credit of 10,300 on the control account. The control account has credits_must_not_exceed_debits and zero balance — 10,300 credits would immediately exceed its 0 debits. T2 fails with exceeds_debits.

(c) Because T1 and T2 are linked (flags.linked), T2's failure cascades: T1 is rolled back. The Destination account is unchanged — no deposit occurred. The entire batch fails atomically. The user's balance remains $9,800.

(a) Two Transfers:

T_reversal:
  debit_account_id:  fee_collection_account
  credit_account_id: user_account
  amount:            50_00  (the original wrong amount)
  code:              CORRECTION_REVERSAL (e.g., 1000)
  user_data_128:     original_order_id

T_correct:
  debit_account_id:  user_account
  credit_account_id: fee_collection_account
  amount:            5_00   (the correct amount)
  code:              FEE (e.g., 7)
  user_data_128:     original_order_id

These can be submitted as a linked pair to ensure they both apply or neither does.

(b) query_transfers shows three entries: the original wrong fee (+$50 debit), the reversal (-$50 correction credit), and the correct fee (+$5 debit). Net effect on the user account: -$5. An auditor reconstructs the final balance by summing all Transfer amounts — the three entries net to -$5, which is the correct fee. The $50 error is visible in history, as is its correction, with timestamps and user_data_128 linking all three to the original order.

(c) Regulatory reporting requires an immutable audit trail. If you directly mutate the balance, the error disappears. Regulators (and auditors) cannot see that an error occurred, when it was detected, or how it was resolved. The correction-as-Transfer approach preserves all of this: the error, the correction, the operator who submitted it, and the timestamp — all are permanent record. In regulated industries (banking, brokerage), this is not optional.