feat(bridge): promote topup deposit audit row to Completed on crypto receive

[islandbitcoin]

Problem

Topup rows in the ERPNext Bridge Transfer Request audit trail were stuck at Fiat Received forever. The Bridge deposit webhook only ever wrote Fiat Received, the IBEX crypto receive wrote a separate ibex:<txHash> row at Settled, and nothing correlated the two — Completed was only reachable on the Cashout path. An operator couldn't tell a healthy finished topup from one stuck mid-conversion without manually hunting for the sibling ibex: row.

Design

Join the two sides of a topup on the IBEX destination tx hash, covering both webhook orderings:

1. Crypto receive arrives after the deposit webhooks (common case)
After writing the ibex:<txHash> settle row, the crypto-receive handler calls promoteBridgeDepositForCryptoReceive, which finds the deposit-side row (ibex_tx_hash = txHash, transaction_type = Topup, request_id not like "ibex:%") and promotes it to Completed, stamping the credited account_id/wallet_id and appending ibex_crypto_receive to source_systems_seen. Best-effort: a promotion failure logs + alerts (erpnext_promote_failed) but never fails the webhook — funds are already credited and the settle row exists. not_found is normal when Bridge's payment_processed event (which carries receipt.destination_tx_hash) hasn't stamped the deposit row yet; the reverse path below converges it.

2. Crypto receive arrives before the deposit's payment_processed webhook
writeBridgeDepositRequest now checks for an existing ibex:<txHash> settle row whenever the event carries receipt.destination_tx_hash, and writes the row as Completed directly. A failed check degrades to Fiat Received (never blocks the audit write).

Guard rails in upsertBridgeTransferRequest (load-bearing for the above):

• Topup statuses are monotonic (Pending < Fiat Received < Settled < Completed < Failed): Bridge webhook retries of earlier deposit events can no longer stomp a promoted row back to Fiat Received. Cashout rows keep their existing last-write-wins semantics.
• source_systems_seen merges as a set union on update instead of overwriting, so a promoted row keeps recording both bridge_deposit and ibex_crypto_receive.

No ERPNext-side changes needed: the doctype's status options and the transfer-requests admin page already handle Completed for topups.

Known limitation

If the payment_processed deposit event and the crypto receive race within the same sub-second window, both matching checks can miss (deposit row not yet stamped with the hash when promotion looks; ibex: row not yet written when the deposit write checks). The row self-heals on any subsequent Bridge webhook retry. The read-modify-write on promotion has no compare-and-swap, same as the existing upsert.

Tests

33 unit tests across the three touched specs (all passing), including:

• promotion: filter shape, account/wallet attribution, not_found, idempotent already_completed, write-failure error path
• deposit writer: Completed when settle row exists, no lookup without a destination hash, degrade-to-Fiat Received on lookup failure
• upsert guards: no Topup downgrade, forward moves allowed, cashout last-write-wins preserved, source_systems_seen union
• route: promotion called with credited account/wallet, webhook still succeeds on not_found and on promotion failure (with alert)

yarn tsc-check and eslint clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UXnQYUbKQe5wUCWEvdAau7