feat(transactions): dry_run preview for create and refund

[Shivam8584]

Adds dry_run to POST /transactions and POST /refund-transaction/:id, answering "if I post this, would it succeed and what would the balances become" without writing anything.

Part one of two, per #330 — bulk and inflight follow in a second PR, where the cross-leg accumulator and multi-leg parent expansion carry most of the complexity. Corrections to the original issue text are in this comment.

POST /transactions   { "dry_run": true, "amount": 120, ... }   → 200

{
  "dry_run": true,
  "would_apply": true,
  "precise_amount": "12000",
  "balances": [
    { "role": "source",      "current_balance": "50000", "resulting_balance": "38000", ... },
    { "role": "destination", "current_balance": "0",     "resulting_balance": "12000", ... }
  ]
}

How it works

The projection runs the same arithmetic a real post runs — processBalances, and through it UpdateBalances and canProcessTransaction — against deep copies of the balances. Sharing the math rather than reimplementing it is the whole point: a preview that computed availability its own way would drift from enforcement the first time overdraft rules changed, and a preview that disagrees with reality is worse than none.

Three things the code made necessary that aren't obvious:

• POST /transactions doesn't reach RecordTransaction. It goes through QueueTransaction, which persists a QUEUED row and applies balances later in a worker. The projection drives the apply seam directly instead — threading a flag through the queue would still write a row.
• Resolving an @indicator writes. getOrCreateBalanceByIndicator creates the balance when it's missing, so resolution goes through read-only lookups and an unknown indicator is projected against a zeroed virtual balance rather than created.
• The apply path mutates in place. UpdateBalances writes PreciseAmount onto the transaction, and big.Int's Add/Sub mutate their receiver — so a plain struct copy would share the underlying integers and a "before" snapshot would silently show "after" values. Hence Clone() in the first commit.

Locks are taken so both balances are read as of one moment, but acquired directly rather than through executeWithLock: a preview shouldn't record hot-pair contention and steer hot-lane routing for real traffic.

Deliberate choices

No new error codes. A projected rejection is a 200 with would_apply: false — the request succeeded, the answer is "no". The rejection carries the same code a real post returns, resolved through the existing classifyMessage, so client-side handling for TXN_INSUFFICIENT_FUNDS works against a preview unchanged. codes.go is untouched.

dry_run stays out of model.Transaction. It describes what to do with the request, not the movement, so it lives at the transport boundary — which also makes it structurally impossible for a preview transaction to reach the writer by accident.

Where the ledger is permissive, the preview reports rather than invents a rule. The apply path performs no currency check, so a mismatched currency is projected with a note instead of rejected. A preview stricter than enforcement would be misleading.

dry_run wins over skip_queue, and always answers synchronously with 200.

Scope of the guarantee

A dry run changes no ledger state: no transaction row, no balance mutation, no queue entry, no webhook, no hook, and the reference is not consumed.

It is not byte-for-byte write-free at the HTTP layer — auth middleware still updates api_keys.last_used_at, and OTel spans are still emitted. Both are deliberate; a preview you can't trace is worse to operate.

One known wart: because permissions are gated by HTTP method rather than by effect, a preview on POST /transactions still requires write scope — awkward for the pre-flight UI check that motivates the feature. Happy to follow up separately if you'd like previews to be read-scope-accessible; it seemed like a permission-model change that didn't belong in a feature PR.

Tests

26 new tests. The ones that matter:

• Changes nothing — balances byte-identical including version (the optimistic-lock counter moves on any persisted write, so it's the sharpest tripwire); no transaction row; reference still usable by a real post afterwards; unknown @indicator not created. The service-level tests run against sqlmock, so an unexpected INSERT fails the test by itself rather than needing an assertion.
• Clone doesn't alias — every *big.Int checked with NotSame, plus mutate-the-clone-assert-the-original.
• Projection matches enforcement — insufficient funds, inflight-adjusted availability, zero amount rejected (validate runs inside UpdateBalances, so it errors rather than being a silent no-op).
• Bodiless refund still works — the new field is optional and POST /refund-transaction/:id with an empty body keeps meaning "refund normally".

Verified end to end against a running server: previewed a transaction, then really posted it — the projection matched the resulting balances field for field, and version was unchanged across the preview.

go test ./... passes apart from internal/search, which needs Typesense and fails identically on main.

[jerry-enebeli]

Hi @Shivam8584 taking a look