@openora/core 0.4.1-canary.15 → 0.4.1-canary.151

package/dist/wallet/service/reconciliation.service.js

@@ -0,0 +1,685 @@
+import { randomUUID } from 'node:crypto';
+import { and, asc, count, desc, eq, gte, inArray, isNull, lt, sql } from 'drizzle-orm';
+import { createLogger, findOneOrThrow, makeConflictError, makeNotFoundError, moneyEquals, pageToOffset, serializeRow, } from '@openora/core/server';
+import { DEFAULT_PAYMENT_PROVIDER, } from '@openora/core/contracts';
+import { wallet, walletCustodySweep, walletJobRun, walletReconciliationFinding, walletTransaction, } from '../schema/index.js';
+import { OUT_OF_CYCLE_RUN_ID, recordReconciliationFinding, rgDecisionForLandedCredit, } from './reconciliation-finding.service.js';
+const logger = createLogger('wallet-reconciliation');
+export const ReconciliationFindingNotFoundError = makeNotFoundError('ReconciliationFinding');
+export const ReconciliationCreditTransactionNotFoundError = makeNotFoundError('ReconciliationCreditTransaction');
+export const ReconciliationCreditMismatchError = makeConflictError('ReconciliationCreditMismatchError', "The referenced transaction is not a manual credit matching this finding's currency and amount");
+/**
+ * Pure diff of one vendor deposit event against its (maybe absent) ledger row - the
+ * whole decision reconciliation makes for a deposit, extracted so it is unit-testable
+ * without a database. Never routes through moneyToNumber (see money.md): an exact
+ * decimal compare, not a float one.
+ */
+export function diffDeposit(event, tx) {
+    if (!tx) {
+        return 'missing_deposit';
+    }
+    if (tx.currency.toUpperCase() !== event.currency.toUpperCase()) {
+        return 'currency_mismatch';
+    }
+    if (!moneyEquals(tx.amount, event.amount)) {
+        return 'amount_mismatch';
+    }
+    return null;
+}
+function chunk(items, size) {
+    const chunks = [];
+    for (let i = 0; i < items.length; i += size) {
+        chunks.push(items.slice(i, i + size));
+    }
+    return chunks;
+}
+// Vendor listTransactions batches are thousands of rows; a well-under-the-parameter-
+// ceiling chunk size keeps every lookup a single inArray(...) round trip per chunk,
+// never one query per vendor transaction.
+const PROVIDER_REF_LOOKUP_CHUNK_SIZE = 1000;
+// A claimed run stuck this long is presumed crashed (the process died mid-cycle) rather
+// than still working, so the next tick may mark it `abandoned` and take the slot over.
+// Distinct from the vendor-side ambiguity thresholds: this one is about our own worker.
+const DEFAULT_STALE_RUN_AFTER_MINUTES = 30;
+/** Fallback when reconciliation runs without a `wallet.sweep` config block. */
+const DEFAULT_UNKNOWN_AFTER_MINUTES = 60;
+// A swap leg carries no payment provider name, but a finding needs one to be filed under.
+const SWAP_DESK_PROVIDER_LABEL = 'swap-desk';
+const JOB_NAME = 'wallet-reconciliation';
+/**
+ * Ceiling on catching up after an outage, as a multiple of `lookbackHours`. Recovering
+ * from a week of downtime must not ask a vendor for one unbounded page of history.
+ */
+const MAX_CATCH_UP_MULTIPLE = 7;
+function toFindingDto(row) {
+    return serializeRow(row, { dateFields: ['createdAt', 'resolvedAt'], decimalFields: [] });
+}
+/**
+ * Owns the reconciliation job cycle (claim -> per-provider diff -> stuck-withdrawal /
+ * stuck-sweep sweep -> finish + audit + alert) and the admin surface over its findings
+ * (list/resolve). Never credits or moves money itself - every finding is a report; the
+ * only paths that touch a balance are `WalletService.reconcileWithdrawalStatus` (already
+ * idempotent) and the pre-existing manual-adjustment path a `credited` resolution merely
+ * references.
+ */
+export class ReconciliationService {
+    drizzle;
+    events;
+    wallet;
+    paymentProviders;
+    audit;
+    platformConfig;
+    rgLimits;
+    constructor({ drizzle, events, wallet, paymentProviders, audit, platformConfig, rgLimits, }) {
+        this.drizzle = drizzle;
+        this.events = events;
+        this.wallet = wallet;
+        this.paymentProviders = paymentProviders;
+        this.audit = audit;
+        this.platformConfig = platformConfig;
+        this.rgLimits = rgLimits;
+    }
+    async listFindings(filter) {
+        const db = this.drizzle.db;
+        const conditions = [];
+        if (filter.status) {
+            conditions.push(eq(walletReconciliationFinding.status, filter.status));
+        }
+        if (filter.kind) {
+            conditions.push(eq(walletReconciliationFinding.kind, filter.kind));
+        }
+        if (filter.providerName) {
+            conditions.push(eq(walletReconciliationFinding.providerName, filter.providerName));
+        }
+        const where = conditions.length > 0 ? and(...conditions) : undefined;
+        const [rows, [{ n } = { n: 0 }]] = await Promise.all([
+            db
+                .select()
+                .from(walletReconciliationFinding)
+                .where(where)
+                .orderBy(desc(walletReconciliationFinding.createdAt), desc(walletReconciliationFinding.id))
+                .limit(filter.limit)
+                .offset(pageToOffset(filter.page, filter.limit)),
+            db.select({ n: count() }).from(walletReconciliationFinding).where(where),
+        ]);
+        return {
+            items: rows.map(toFindingDto),
+            total: Number(n),
+            page: filter.page,
+            limit: filter.limit,
+        };
+    }
+    /**
+     * Conditional `UPDATE ... WHERE status = 'open'` is the whole double-resolve guard -
+     * a second resolve of an already-resolved finding matches zero rows and returns the
+     * row unchanged, with no second audit entry. `credited` requires the referenced
+     * transaction to already exist (the manual-adjustment path creates it - this never
+     * credits anything itself) and match the finding's currency/amount exactly.
+     */
+    async resolveFinding(adminId, id, resolution, meta) {
+        const { dto, creditedBy } = await this.drizzle.db.transaction(async (txn) => {
+            let transactionId;
+            let resolutionNote = null;
+            let creditTx;
+            if (resolution.outcome === 'credited') {
+                const [finding] = await txn
+                    .select()
+                    .from(walletReconciliationFinding)
+                    .where(eq(walletReconciliationFinding.id, id));
+                if (!finding) {
+                    throw new ReconciliationFindingNotFoundError(id);
+                }
+                const [tx] = await txn
+                    .select()
+                    .from(walletTransaction)
+                    .where(eq(walletTransaction.id, resolution.transactionId));
+                if (!tx) {
+                    throw new ReconciliationCreditTransactionNotFoundError(resolution.transactionId);
+                }
+                if (tx.type !== 'manual_credit' ||
+                    finding.currency === null ||
+                    tx.currency.toUpperCase() !== finding.currency.toUpperCase() ||
+                    finding.amount === null ||
+                    !moneyEquals(tx.amount, finding.amount)) {
+                    throw new ReconciliationCreditMismatchError();
+                }
+                transactionId = tx.id;
+                creditTx = tx;
+            }
+            else {
+                resolutionNote = resolution.note;
+            }
+            const updated = await txn
+                .update(walletReconciliationFinding)
+                .set({
+                status: 'resolved',
+                resolvedBy: adminId,
+                resolvedAt: new Date(),
+                resolutionNote,
+                ...(transactionId ? { transactionId } : {}),
+            })
+                .where(and(eq(walletReconciliationFinding.id, id), eq(walletReconciliationFinding.status, 'open')))
+                .returning();
+            if (updated.length === 0) {
+                const [existing] = await txn
+                    .select()
+                    .from(walletReconciliationFinding)
+                    .where(eq(walletReconciliationFinding.id, id));
+                // Already resolved by a concurrent/earlier call: return it unchanged, no audit entry.
+                return {
+                    dto: toFindingDto(findOneOrThrow(existing ? [existing] : [], new ReconciliationFindingNotFoundError(id))),
+                    creditedBy: undefined,
+                };
+            }
+            const row = findOneOrThrow(updated, new ReconciliationFindingNotFoundError(id));
+            await this.audit.recordInTransaction(txn, {
+                actorId: adminId,
+                actorType: 'admin',
+                action: 'wallet.reconciliation_finding.resolved',
+                resourceType: 'wallet_reconciliation_finding',
+                resourceId: row.id,
+                before: { status: 'open' },
+                after: {
+                    status: row.status,
+                    outcome: resolution.outcome,
+                    transactionId: row.transactionId,
+                    resolutionNote: row.resolutionNote,
+                },
+                ...meta,
+            });
+            return { dto: toFindingDto(row), creditedBy: creditTx ? { row, tx: creditTx } : undefined };
+        });
+        if (creditedBy) {
+            await this.recordRgBreachForHandCredit(creditedBy.row, creditedBy.tx);
+        }
+        return dto;
+    }
+    /**
+     * The hand-credit counterpart of the gate `WalletService.creditDepositByAddress` runs.
+     * An admin resolving a deposit finding as `credited` puts on-chain money in the player's
+     * wallet through a `manual_credit`, which no deposit window counts and no limit refuses,
+     * so without this the poll-then-credit route is the one way past a deposit limit that
+     * leaves no trace. The credit IS the attempted move here, the opposite of the webhook
+     * path's `0`, because the gate does not count a `manual_credit` row at all.
+     *
+     * Never blocks the resolution: the admin's credit has already committed, and failing
+     * their request over a report would only lose the report - a retry finds the finding
+     * resolved and returns early. A write that fails is logged and lost; the audit row for
+     * the resolution still names the admin, the amount and the transaction.
+     */
+    async recordRgBreachForHandCredit(finding, tx) {
+        try {
+            const [holder] = await this.drizzle.db
+                .select({ userId: wallet.userId })
+                .from(wallet)
+                .where(eq(wallet.id, tx.walletId));
+            if (!holder) {
+                return;
+            }
+            const decision = await rgDecisionForLandedCredit(this.drizzle.db, this.rgLimits, { userId: holder.userId, attempted: tx.amount, currency: tx.currency }, { externalId: finding.externalId, txHash: finding.txHash });
+            if (!decision) {
+                return;
+            }
+            await recordReconciliationFinding(this.drizzle.db, {
+                runId: OUT_OF_CYCLE_RUN_ID,
+                providerName: finding.providerName,
+                kind: 'rg_limit_breach',
+                currency: tx.currency,
+                network: finding.network,
+                amount: tx.amount,
+                address: finding.address,
+                tag: finding.tag,
+                txHash: finding.txHash,
+                // The resolved finding's own id, not its externalId: the vendor id already keys
+                // a breach filed for the same deposit by the webhook path, and these two are
+                // separate credits of separate money whenever both exist.
+                externalId: finding.id,
+                transactionId: tx.id,
+                detail: `credited by hand past the player's ${decision.period} ${decision.limitType} limit of ${decision.limit} (${decision.used} in the window before this credit) - resolving finding ${finding.id}`,
+            }, this.audit);
+        }
+        catch (err) {
+            logger.error({ err, findingId: finding.id, transactionId: tx.id }, 'RG breach finding for a hand-credited deposit could not be recorded');
+        }
+    }
+    /**
+     * The window is anchored to the last completed run, not to the wall clock. BullMQ
+     * repeatable jobs are delayed jobs: a tick missed while no worker was running is
+     * skipped, never backfilled. Against a fixed `now - lookbackHours` window that means
+     * any outage longer than `lookbackHours` leaves a span nothing ever reconciles and
+     * nothing ever reports - the worst possible failure mode for a compensating control.
+     * Catching up is capped, and a capped window is reported rather than passed over.
+     */
+    async resolveWindow(until, lookbackHours) {
+        const lookbackStart = new Date(until.getTime() - lookbackHours * 3_600_000);
+        const [last] = await this.drizzle.db
+            .select({ finishedAt: walletJobRun.finishedAt })
+            .from(walletJobRun)
+            .where(and(eq(walletJobRun.jobName, JOB_NAME), eq(walletJobRun.status, 'completed')))
+            .orderBy(desc(walletJobRun.finishedAt))
+            .limit(1);
+        const anchor = last?.finishedAt;
+        if (!anchor || anchor >= lookbackStart) {
+            return { since: lookbackStart, unreconciledHours: 0 };
+        }
+        const floor = new Date(until.getTime() - lookbackHours * MAX_CATCH_UP_MULTIPLE * 3_600_000);
+        const since = anchor < floor ? floor : anchor;
+        return {
+            since,
+            unreconciledHours: Math.round((since.getTime() - anchor.getTime()) / 3_600_000),
+        };
+    }
+    /**
+     * Claim -> per-provider deposit/withdrawal diff -> stuck-withdrawal / stuck-sweep
+     * sweep -> finish + one audit entry + an alert past threshold. Returns null without
+     * doing any work when another cycle already owns the claim - the caller (cron tick or
+     * the on-demand route's worker) treats that as a normal, expected outcome.
+     */
+    async runCycle(runId = randomUUID()) {
+        const jobRunId = await this.claimRun(runId);
+        if (!jobRunId) {
+            return null;
+        }
+        const counts = {
+            missingDeposit: 0,
+            currencyMismatch: 0,
+            amountMismatch: 0,
+            withdrawalsReconciled: 0,
+            unknownAtProvider: 0,
+            stuckSweeps: 0,
+            stuckSwaps: 0,
+            swapFindingsClosed: 0,
+            unreconciledHours: 0,
+        };
+        try {
+            const cfg = this.platformConfig?.wallet?.reconciliation;
+            if (cfg) {
+                const until = new Date();
+                const { since, unreconciledHours } = await this.resolveWindow(until, cfg.lookbackHours);
+                counts.unreconciledHours = unreconciledHours;
+                if (unreconciledHours > 0) {
+                    logger.error({ runId, unreconciledHours, since }, 'wallet reconciliation: catch-up window capped, an earlier span stays unreconciled');
+                }
+                for (const providerName of this.paymentProviders.names()) {
+                    await this.reconcileProvider(runId, providerName, since, until, counts);
+                }
+                await this.reconcileStuckWithdrawals(runId, cfg.stuckAfterMinutes, cfg.batchSize, counts);
+                // Close first, then file: a leg the desk settled after it was reported stops
+                // describing a situation that no longer exists before this cycle adds more.
+                await this.resolveSettledSwapFindings(counts);
+                await this.reconcileStuckSwaps(runId, cfg.stuckSwapAfterMinutes ?? cfg.stuckAfterMinutes, cfg.batchSize, counts);
+                // Deliberately not gated on `wallet.sweep` being configured. An operator can
+                // adopt reconciliation without sweeping, and a stuck sweep is real player money
+                // parked vendor-side in an ambiguous state - the last finding class that should
+                // quietly switch itself off because a different feature's config block is absent.
+                await this.reconcileStuckSweeps(runId, this.platformConfig?.wallet?.sweep?.unknownAfterMinutes ?? DEFAULT_UNKNOWN_AFTER_MINUTES, cfg.batchSize, counts);
+            }
+            const openFindings = await this.countOpenFindings();
+            const status = cfg ? 'completed' : 'skipped';
+            await this.finishRun(jobRunId, status, { ...counts, openFindings });
+            await this.audit.record({
+                actorType: 'system',
+                action: cfg ? 'wallet.reconciliation_run.completed' : 'wallet.reconciliation_run.skipped',
+                resourceType: 'wallet_job_run',
+                resourceId: runId,
+                after: { runId, ...counts, openFindings },
+            });
+            if (cfg && openFindings > cfg.alertThreshold) {
+                logger.error({ runId, openFindings, threshold: cfg.alertThreshold }, 'wallet reconciliation: open findings exceed threshold');
+                this.events.emit('wallet.reconciliation.alert', {
+                    runId,
+                    openFindings,
+                    threshold: cfg.alertThreshold,
+                });
+            }
+            return { runId };
+        }
+        catch (err) {
+            await this.finishRun(jobRunId, 'failed', {
+                ...counts,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            await this.audit.record({
+                actorType: 'system',
+                action: 'wallet.reconciliation_run.failed',
+                resourceType: 'wallet_job_run',
+                resourceId: runId,
+                after: { runId, ...counts },
+            });
+            throw err;
+        }
+    }
+    async reconcileProvider(runId, providerName, since, until, counts) {
+        const provider = this.paymentProviders.get(providerName);
+        if (!provider?.adapter.listTransactions) {
+            return;
+        }
+        const events = await provider.adapter.listTransactions({ since, until });
+        // Every sweep (an internal transfer of vendor-side funds, never a ledger row) shows
+        // up in the vendor's own transaction list too - exclude it BEFORE diffing, or every
+        // sweep files a false missing_deposit/unmatched-withdrawal finding.
+        const swept = await this.sweptExternalIds(providerName, since);
+        const relevant = events.filter((event) => !swept.has(event.externalId));
+        const deposits = relevant.filter((event) => event.kind === 'deposit');
+        const withdrawals = relevant.filter((event) => event.kind === 'withdrawal');
+        await this.reconcileDeposits(runId, providerName, deposits, counts);
+        for (const event of withdrawals) {
+            // Reconciliation is the same normalization a webhook produces, polled instead of
+            // pushed - already idempotent, already guards on status === 'processing'.
+            await this.wallet.reconcileWithdrawalStatus(event, providerName);
+            counts.withdrawalsReconciled += 1;
+        }
+    }
+    async sweptExternalIds(providerName, since) {
+        const rows = await this.drizzle.db
+            .select({ externalId: walletCustodySweep.externalId })
+            .from(walletCustodySweep)
+            .where(and(eq(walletCustodySweep.providerName, providerName), gte(walletCustodySweep.createdAt, since)));
+        return new Set(rows.map((row) => row.externalId).filter((id) => id !== null));
+    }
+    async reconcileDeposits(runId, providerName, deposits, counts) {
+        if (deposits.length === 0) {
+            return;
+        }
+        const byExternalId = await this.batchLookupByProviderRefId(providerName, deposits.map((d) => d.externalId));
+        for (const event of deposits) {
+            const tx = byExternalId.get(event.externalId);
+            const result = diffDeposit(event, tx);
+            if (result === null) {
+                continue;
+            }
+            counts[result === 'missing_deposit'
+                ? 'missingDeposit'
+                : result === 'currency_mismatch'
+                    ? 'currencyMismatch'
+                    : 'amountMismatch'] += 1;
+            await recordReconciliationFinding(this.drizzle.db, {
+                runId,
+                providerName,
+                kind: result,
+                currency: event.currency,
+                network: event.network ?? tx?.network ?? null,
+                amount: event.amount,
+                address: event.address,
+                tag: event.tag ?? null,
+                txHash: event.txHash,
+                externalId: event.externalId,
+                transactionId: tx?.id ?? null,
+                detail: result === 'currency_mismatch'
+                    ? `ledger currency ${tx?.currency}, vendor reported ${event.currency}`
+                    : result === 'amount_mismatch'
+                        ? `ledger amount ${tx?.amount}, vendor reported ${event.amount}`
+                        : null,
+            }, this.audit);
+        }
+    }
+    // Single chunked inArray(...) batch read (chunks well under the parameter ceiling) -
+    // never one query per vendor transaction over a window that is routinely thousands of rows.
+    async batchLookupByProviderRefId(providerName, externalIds) {
+        const byExternalId = new Map();
+        for (const batch of chunk(externalIds, PROVIDER_REF_LOOKUP_CHUNK_SIZE)) {
+            const rows = await this.drizzle.db
+                .select()
+                .from(walletTransaction)
+                .where(and(eq(walletTransaction.providerName, providerName), inArray(walletTransaction.providerRefId, batch)));
+            for (const row of rows) {
+                if (row.providerRefId) {
+                    byExternalId.set(row.providerRefId, row);
+                }
+            }
+        }
+        return byExternalId;
+    }
+    // wallet_transaction_status_type_created_at_idx covers the WHERE - equality on status
+    // and type, then a range on createdAt, in that column order. The ORDER BY's leading
+    // correlated EXISTS is not indexable, so the matching set is sorted before LIMIT.
+    async reconcileStuckWithdrawals(runId, stuckAfterMinutes, batchSize, counts) {
+        const cutoff = new Date(Date.now() - stuckAfterMinutes * 60 * 1000);
+        // Mirrors the externalId this loop files below, which is the findings dedup key.
+        const alreadyReported = sql `EXISTS (
+      SELECT 1 FROM ${walletReconciliationFinding}
+      WHERE ${walletReconciliationFinding.kind} = 'unknown_at_provider'
+        AND ${walletReconciliationFinding.providerName}
+            = coalesce(${walletTransaction.providerName}, ${DEFAULT_PAYMENT_PROVIDER})
+        AND ${walletReconciliationFinding.externalId}
+            = coalesce(${walletTransaction.providerRefId}, ${walletTransaction.id}::text)
+    )`;
+        const stuck = await this.drizzle.db
+            .select()
+            .from(walletTransaction)
+            .where(and(eq(walletTransaction.status, 'processing'), eq(walletTransaction.type, 'withdrawal'), lt(walletTransaction.createdAt, cutoff)))
+            // Unreported first, then oldest. Findings dedupe on (kind, providerName, externalId), so a row
+            // already reported produces nothing on a re-run: ordering it last stops a
+            // permanent backlog from filling the batch and hiding newer stuck withdrawals,
+            // while still re-checking it at the vendor whenever the batch has room.
+            .orderBy(asc(alreadyReported), asc(walletTransaction.createdAt))
+            .limit(batchSize);
+        for (const tx of stuck) {
+            const providerName = tx.providerName ?? DEFAULT_PAYMENT_PROVIDER;
+            const provider = this.paymentProviders.get(providerName);
+            // Nothing to look up at all (crashed before the vendor ever responded with a
+            // reference) - still worth a finding, deduped on the transaction's own id.
+            if (!tx.providerRefId) {
+                counts.unknownAtProvider += 1;
+                await recordReconciliationFinding(this.drizzle.db, {
+                    runId,
+                    providerName,
+                    kind: 'unknown_at_provider',
+                    currency: tx.currency,
+                    network: tx.network,
+                    amount: tx.amount,
+                    transactionId: tx.id,
+                    externalId: tx.id,
+                    detail: 'withdrawal has no providerRefId to look up at the vendor',
+                }, this.audit);
+                continue;
+            }
+            const status = await provider?.adapter.getWithdrawalStatus?.(tx.providerRefId);
+            if (status) {
+                await this.wallet.reconcileWithdrawalStatus({
+                    kind: 'withdrawal',
+                    externalId: tx.providerRefId,
+                    status: status.status,
+                    ...(status.txHash ? { txHash: status.txHash } : {}),
+                }, providerName);
+                continue;
+            }
+            counts.unknownAtProvider += 1;
+            await recordReconciliationFinding(this.drizzle.db, {
+                runId,
+                providerName,
+                kind: 'unknown_at_provider',
+                currency: tx.currency,
+                network: tx.network,
+                amount: tx.amount,
+                transactionId: tx.id,
+                externalId: tx.providerRefId,
+                detail: 'vendor has no record of this withdrawal',
+            }, this.audit);
+        }
+    }
+    /**
+     * Closes `stuck_swap` findings the desk settled after they were reported - a
+     * report-side write only, matching what this table is for: it never touches a balance,
+     * a transaction status, or the swap itself. Without it a slow-but-healthy swap leaves
+     * an `open` finding describing a situation that no longer exists, and since
+     * `countOpenFindings` feeds `alertThreshold`, a growing pile of them alerts on nothing.
+     */
+    async resolveSettledSwapFindings(counts) {
+        const settled = sql `EXISTS (
+      SELECT 1 FROM ${walletTransaction}
+      WHERE ${walletTransaction.id} = ${walletReconciliationFinding.transactionId}
+        AND ${walletTransaction.status} <> 'processing'
+    )`;
+        const closed = await this.drizzle.db
+            .update(walletReconciliationFinding)
+            .set({
+            status: 'resolved',
+            resolvedAt: new Date(),
+            resolutionNote: 'the desk settled this swap after it was reported',
+        })
+            .where(and(eq(walletReconciliationFinding.kind, 'stuck_swap'), eq(walletReconciliationFinding.status, 'open'), settled))
+            .returning({ id: walletReconciliationFinding.id });
+        // `resolvedBy` stays null: no admin acted, and the audit entry's system actor is
+        // what says who did. A finding closed here never carries a `credited` outcome,
+        // because nothing on this path moves money.
+        for (const row of closed) {
+            counts.swapFindingsClosed += 1;
+            await this.audit.record({
+                actorType: 'system',
+                action: 'wallet.reconciliation_finding.resolved',
+                resourceType: 'wallet_reconciliation_finding',
+                resourceId: row.id,
+                before: { status: 'open' },
+                after: { status: 'resolved', outcome: 'settled_at_desk' },
+            });
+        }
+    }
+    // Human resolution only, like a stuck sweep. A swap_out held `processing` past the cutoff
+    // is money debited from the player with nothing credited back, and the desk may or may not
+    // have filled it - so neither a refund nor a credit is safe without someone looking.
+    //
+    // wallet_transaction_status_type_created_at_idx covers the WHERE, but the ORDER BY leads
+    // with the correlated EXISTS, which no index serves: every cycle sorts the whole matching
+    // set before LIMIT. That set is bounded in practice only because resolveSettledSwapFindings
+    // closes findings - not because the plan is cheap. Same shape as the sweep sibling.
+    async reconcileStuckSwaps(runId, stuckSwapAfterMinutes, batchSize, counts) {
+        const cutoff = new Date(Date.now() - stuckSwapAfterMinutes * 60 * 1000);
+        // Mirrors the externalId this loop files below, which is the findings dedup key.
+        const alreadyReported = sql `EXISTS (
+      SELECT 1 FROM ${walletReconciliationFinding}
+      WHERE ${walletReconciliationFinding.kind} = 'stuck_swap'
+        AND ${walletReconciliationFinding.providerName}
+            = coalesce(${walletTransaction.providerName}, ${SWAP_DESK_PROVIDER_LABEL})
+        AND ${walletReconciliationFinding.externalId}
+            = coalesce(${walletTransaction.providerRefId}, ${walletTransaction.id}::text)
+    )`;
+        const stuck = await this.drizzle.db
+            .select()
+            .from(walletTransaction)
+            .where(and(eq(walletTransaction.status, 'processing'), eq(walletTransaction.type, 'swap_out'), lt(walletTransaction.createdAt, cutoff)))
+            .orderBy(asc(alreadyReported), asc(walletTransaction.createdAt))
+            .limit(batchSize);
+        for (const tx of stuck) {
+            counts.stuckSwaps += 1;
+            await recordReconciliationFinding(this.drizzle.db, {
+                runId,
+                providerName: tx.providerName ?? SWAP_DESK_PROVIDER_LABEL,
+                kind: 'stuck_swap',
+                currency: tx.currency,
+                amount: tx.amount,
+                transactionId: tx.id,
+                // The desk's own reference when there is one, as every other kind in this table
+                // does, so an operator can join findings to desk records. A leg that died before
+                // `execute` returned has none, and falls back to the local id - the same
+                // `providerRefId ?? id` shape the sweep sibling files.
+                externalId: tx.providerRefId ?? tx.id,
+                detail: `swap_out ${tx.id} has been processing since ${tx.createdAt.toISOString()}`,
+            }, this.audit);
+        }
+    }
+    // wallet_custody_sweep_status_created_at_idx covers the WHERE; the ORDER BY's leading
+    // correlated EXISTS is not indexable, as in the two siblings above. Human resolution
+    // only - this NEVER touches the sweep row's status or releases its in-flight guard.
+    async reconcileStuckSweeps(runId, unknownAfterMinutes, batchSize, counts) {
+        const cutoff = new Date(Date.now() - unknownAfterMinutes * 60 * 1000);
+        const alreadyReportedSweep = sql `EXISTS (
+      SELECT 1 FROM ${walletReconciliationFinding}
+      WHERE ${walletReconciliationFinding.kind} = 'stuck_sweep'
+        AND ${walletReconciliationFinding.providerName} = ${walletCustodySweep.providerName}
+        AND ${walletReconciliationFinding.externalId}
+            = coalesce(${walletCustodySweep.externalId}, ${walletCustodySweep.id}::text)
+    )`;
+        const stuck = await this.drizzle.db
+            .select()
+            .from(walletCustodySweep)
+            .where(and(
+        // `pending` belongs here alongside `unknown`. A worker that dies between the
+        // claim insert and the vendor call leaves a `pending` row with no externalId:
+        // resolveInFlightSweeps skips it (nothing to poll) and the partial unique
+        // index still counts it as in-flight, so that container would never sweep
+        // again and nothing would say why. Same lost-response ambiguity as `unknown`,
+        // so it files a finding for a human rather than releasing the guard.
+        inArray(walletCustodySweep.status, ['pending', 'unknown']), lt(walletCustodySweep.createdAt, cutoff)))
+            // Same starvation guard as reconcileStuckWithdrawals: already-reported sweeps go
+            // last so a permanent backlog cannot hide newer stuck ones from the operator.
+            .orderBy(asc(alreadyReportedSweep), asc(walletCustodySweep.createdAt))
+            .limit(batchSize);
+        for (const sweep of stuck) {
+            counts.stuckSweeps += 1;
+            await recordReconciliationFinding(this.drizzle.db, {
+                runId,
+                providerName: sweep.providerName,
+                kind: 'stuck_sweep',
+                currency: sweep.currency,
+                network: sweep.network,
+                amount: sweep.amount,
+                txHash: sweep.txHash,
+                externalId: sweep.externalId ?? sweep.id,
+                detail: `custody sweep ${sweep.id} has been ${sweep.status} since ${sweep.updatedAt.toISOString()}`,
+            }, this.audit);
+        }
+    }
+    async countOpenFindings() {
+        const [row] = await this.drizzle.db
+            .select({ n: count() })
+            .from(walletReconciliationFinding)
+            .where(eq(walletReconciliationFinding.status, 'open'));
+        return Number(row?.n ?? 0);
+    }
+    /**
+     * The claim IS the insert - a partial unique index on (jobName) WHERE finishedAt IS
+     * NULL makes a conflicting insert the concurrency guard. A stale in-flight run (older
+     * than the configured staleness window - presumed crashed) is marked `abandoned` and its slot freed
+     * for this call to retry the claim once.
+     */
+    async claimRun(runId) {
+        const claimed = await this.retryClaim(runId);
+        if (claimed) {
+            return claimed;
+        }
+        const [existing] = await this.drizzle.db
+            .select()
+            .from(walletJobRun)
+            .where(and(eq(walletJobRun.jobName, JOB_NAME), isNull(walletJobRun.finishedAt)));
+        if (!existing) {
+            // The blocking run finished between our insert conflict and this read - retry once.
+            return this.retryClaim(runId);
+        }
+        const staleAfterMs = (this.platformConfig?.wallet?.reconciliation?.staleRunAfterMinutes ??
+            DEFAULT_STALE_RUN_AFTER_MINUTES) * 60_000;
+        if (existing.startedAt.getTime() >= Date.now() - staleAfterMs) {
+            // A live run genuinely owns the claim - return immediately, no retry loop.
+            return null;
+        }
+        const abandoned = await this.drizzle.db
+            .update(walletJobRun)
+            .set({ status: 'abandoned', finishedAt: new Date() })
+            .where(and(eq(walletJobRun.id, existing.id), isNull(walletJobRun.finishedAt)))
+            .returning({ id: walletJobRun.id });
+        if (abandoned.length === 0) {
+            // Someone else already resolved the stale run concurrently.
+            return null;
+        }
+        return this.retryClaim(runId);
+    }
+    async retryClaim(runId) {
+        const [inserted] = await this.drizzle.db
+            .insert(walletJobRun)
+            .values({ jobName: JOB_NAME, runId })
+            .onConflictDoNothing()
+            .returning({ id: walletJobRun.id });
+        return inserted?.id ?? null;
+    }
+    // Keyed on the claimed row's own id, never on runId: a job retried by the queue
+    // carries the same runId as the attempt that failed, so `WHERE run_id = ...` would
+    // reach back and rewrite that earlier row's `failed`/`abandoned` verdict to
+    // `completed` - erasing the only evidence that the first attempt went wrong.
+    async finishRun(jobRunId, status, summary) {
+        await this.drizzle.db
+            .update(walletJobRun)
+            .set({ finishedAt: new Date(), status, summary })
+            .where(eq(walletJobRun.id, jobRunId));
+    }
+}
+//# sourceMappingURL=reconciliation.service.js.map