feat(executor): pre-flight OpEx fee check before bundle submission

[AquiGorka]

Summary

Adds a pre-flight check on the per-provider OpEx Stellar account before the executor signs and submits a Soroban bundle. When the PP root account cannot cover the simulated tx fee after subtracting Stellar minimum reserves, the bundle is moved straight to terminal FAILED with a typed InsufficientFees reason — no retry, no mempool retention, no on-chain submission attempt.

The structured detail (feePayerPubkey, availableXlm, requiredXlm, shortfallXlm, all stroop strings) is persisted on a new nullable failure_detail jsonb column on operations_bundles and surfaced through the existing entity-scoped bundle-status endpoint so the submitting wallet can read the cause via the response it already polls.

Why terminal-fail (not retry): the mempool is shared across providers, and there is no mechanism today to notify a provider admin that OpEx is underfunded — retained bundles would just clog the shared mempool for every provider. The user must refund OpEx and resubmit.

ClickUp: https://app.clickup.com/t/86c9xfd2e
Milestone: Testnet Hardening.

What changed

• Pre-flight check at src/core/service/executor/preflight-opex-balance.ts: reads the fee-payer's XLM balance + numSubEntries via Soroban getLedgerEntries, simulates the channel-invoke transaction via simulateTransaction to extract minResourceFee, then compares balance − (2 + numSubEntries) × BASE_RESERVE_STROOPS against NETWORK_FEE + minResourceFee.
• Typed error InsufficientFees (EXC_005) at src/core/service/executor/executor.errors.ts, carrying the four-field detail.
• Wired into Executor.executeNext between getTransactionExpiration and submitTransactionToNetwork. The catch site fast-paths error instanceof InsufficientFees before reaching the existing retry helper: it sets BundleStatus.FAILED, persists the detail to failure_detail, and does not touch retryCount.
• DTO + API surface: BundleDTO (toBundleDTO) and the bundle-status GET response schema both grew failureDetail: Record<string, unknown> | null. Null for success states and existing free-form failures — back-compat preserved.
• New env var BASE_RESERVE_STROOPS (optional, default 5_000_000). Soroban RPC does not expose base_reserve as a ConfigSettingEntry, so this is read from env per the project convention; override on protocol upgrade. Documented in .env.example.
• Drizzle migration 0018_add_failure_detail_to_bundles.sql (additive ADD COLUMN IF NOT EXISTS).
• Tests:
  • tests/unit/preflight-opex-balance.test.ts — 8 tests covering the math (sufficient / exact / shortfall-by-one / missing account / high subentry) and the typed-error instance contract.
  • tests/integration/service/executor-preflight-opex-fees.test.ts — 6 tests proving the catch-site persists FAILED + failure_detail without incrementing retryCount, and that the bundle-status DTO + response schema carry the four fields end-to-end.
• Test stub fixes (test: commit, drift from PR feat: migrate to new backend logging convention #105 / the router-factory migration): executor-retry.test.ts, verifier-retry.test.ts, and waitlist.test.ts now pass a real Logger (via newNoop()) and use buildWaitlistRouter({log}). test:integration goes from 82/17 to 99/0.

Migration note

0018_add_failure_detail_to_bundles.sql was force-added (migration files are gitignored by *.sql). Journal entries are chronological — idx 18 when=1780531200000 follows idx 17's 1780300000000.

Test plan

• deno fmt --check — clean (300 files)
• deno lint — clean (258 files)
• deno task test:unit — 64 / 0
• deno task test:integration — 99 / 0 (was 82/17 on main before this PR's test-stub fix)
• Local stack end-to-end on 0.7.2 (full local-dev infra-up.sh + setup-c + setup-pp):
  • happy-path bundle → COMPLETED, failureDetail: null
  • PP_1 root drained to 10,499,900 stroops (just above the 10M reserve) → next deposit goes to FAILED with failureDetail = { feePayerPubkey, availableXlm:"499900", requiredXlm:"1504155", shortfallXlm:"1004255" }
  • PP_1 re-funded via friendbot → subsequent bundle goes through normally
  • No submitTransactionToNetwork span recorded for the failed bundle in Jaeger — pre-flight throws before any submission attempt
• Reviewer pass on the catch-site bypass (one fast-path before the existing retry helper; deliberately no refactor of handleExecutionFailure)
• Reviewer pass on the migration ordering (idx 18 / when 1780531200000)