@openora/core 0.4.0 → 0.4.1-canary.100

package/dist/wallet/service/custody-sweep.service.js

@@ -0,0 +1,354 @@
+import { randomUUID } from 'node:crypto';
+import * as z from 'zod';
+import { moneyCompare, moneyScaleBy, mapConcurrent, createLogger, } from '@openora/core/server';
+import { queue, UuidSchema, } from '@openora/core/contracts';
+import { and, eq, inArray, isNotNull, isNull } from 'drizzle-orm';
+import { walletAsset, walletCustodySweep, walletJobRun, } from '../schema/index.js';
+import { recordReconciliationFinding } from './reconciliation-finding.service.js';
+const logger = createLogger('wallet-custody-sweep');
+export const CUSTODY_SWEEP_JOB_NAME = 'wallet-custody-sweep';
+export const CUSTODY_SWEEP_QUEUE = queue('wallet.custody-sweep');
+// `runId` is only present when an admin's on-demand POST /wallet/custody/sweep/run
+// enqueued this tick - the router mints it up front so it can hand the caller back a
+// runId synchronously, before the job actually runs. A cron tick omits it and the
+// service mints its own.
+export const CustodySweepJobPayloadSchema = z.object({ runId: UuidSchema.optional() });
+const IN_FLIGHT_STATUSES = ['pending', 'processing', 'unknown'];
+/**
+ * Pure gate over a single custody balance, in the exact order
+ * docs/adapters/payment.md diagram D3 specifies: dust floor, then the fee-multiple
+ * floor, then the fee ceiling (overridden only when the pool is running dry).
+ *
+ * `poolBalance` is null whenever the caller hasn't fetched it (no ceiling breach yet,
+ * the adapter has no `getPoolBalance`, or the asset has no `poolLiquidityFloor`) - null
+ * always means "the ceiling stays absolute", never an accidental override.
+ */
+export function gateSweepBalance(args) {
+    if (moneyCompare(args.amount, args.minDeposit) < 0) {
+        return 'dust';
+    }
+    const feeFloor = moneyScaleBy(args.estimatedFee, args.feeMultiple);
+    if (moneyCompare(args.amount, feeFloor) < 0) {
+        return 'fee';
+    }
+    if (args.sweepFeeCeiling !== null && moneyCompare(args.estimatedFee, args.sweepFeeCeiling) > 0) {
+        const poolBelowFloor = args.poolLiquidityFloor !== null &&
+            args.poolBalance !== null &&
+            moneyCompare(args.poolBalance, args.poolLiquidityFloor) < 0;
+        if (!poolBelowFloor) {
+            return 'ceiling';
+        }
+    }
+    return 'sweep';
+}
+/**
+ * Owns the custody sweep cron: moves vendor-side per-player custody balances into the
+ * pooled account they're paid out of. Deliberately separate from WalletService (which
+ * is already ~2000 lines) and deliberately never touches wallet_balance/wallet_transaction
+ * - the player was credited at deposit time, this only moves the vendor's own money
+ * between its own containers. See docs/adapters/payment.md, "Custody: pooling, sweeping
+ * and reconciliation".
+ */
+export class CustodySweepService {
+    drizzle;
+    paymentProviders;
+    audit;
+    platformConfig;
+    constructor({ drizzle, paymentProviders, audit, platformConfig }) {
+        this.drizzle = drizzle;
+        this.paymentProviders = paymentProviders;
+        this.audit = audit;
+        this.platformConfig = platformConfig;
+    }
+    /**
+     * Runs one sweep cycle. No-ops (returns null, touches nothing) when
+     * `platformConfig.wallet.sweep` is absent - an operator who hasn't configured sweep
+     * policy still gets a scheduled job, it just never claims a run. Also returns null
+     * when another cycle already owns the claim.
+     */
+    async runCycle(requestedRunId) {
+        const sweepConfig = this.platformConfig?.wallet?.sweep;
+        if (!sweepConfig) {
+            return null;
+        }
+        const claim = await this.claimRun(requestedRunId, sweepConfig.staleRunAfterMinutes);
+        if (!claim) {
+            return null;
+        }
+        const { runId, jobRunId } = claim;
+        const summary = {
+            considered: 0,
+            swept: 0,
+            skippedDust: 0,
+            skippedFee: 0,
+            skippedCeiling: 0,
+            inFlight: 0,
+            failed: 0,
+            unknown: 0,
+        };
+        // Everything past the claim runs guarded: an adapter that throws (a vendor 5xx is
+        // the ordinary case) would otherwise leave this run's row with finishedAt NULL, and
+        // the partial unique index would then block every subsequent cycle until the
+        // staleness takeover window elapsed. A failed cycle must free its own slot.
+        try {
+            await this.resolveInFlightSweeps(sweepConfig.concurrency);
+            const poolBalanceCache = new Map();
+            for (const providerName of this.paymentProviders.names()) {
+                const adapter = this.paymentProviders.get(providerName)?.adapter;
+                // sweepToPool is checked here, not after a claim row exists: an adapter that
+                // advertises listSweepableBalances without it would otherwise claim a container,
+                // throw, and park an `unknown` row that holds the in-flight guard forever.
+                if (!adapter?.listSweepableBalances) {
+                    continue;
+                }
+                if (!adapter.sweepToPool) {
+                    logger.error({ providerName }, 'provider lists sweepable balances but cannot sweep them; skipping');
+                    continue;
+                }
+                // listSweepableBalances is unbounded; sweeping is throughput work, so the cron
+                // cadence drains the backlog rather than one cycle chasing it all.
+                const balances = (await adapter.listSweepableBalances()).slice(0, sweepConfig.batchSize);
+                summary.considered += balances.length;
+                await mapConcurrent(balances, sweepConfig.concurrency, (balance) => this.processBalance({
+                    providerName,
+                    adapter,
+                    balance,
+                    runId,
+                    sweepConfig,
+                    summary,
+                    poolBalanceCache,
+                }));
+            }
+        }
+        catch (err) {
+            await this.finishRun(jobRunId, runId, summary, 'failed', err);
+            throw err;
+        }
+        await this.finishRun(jobRunId, runId, summary);
+        return { runId, summary };
+    }
+    // The insert IS the claim: the partial unique index on wallet_job_run(job_name) WHERE
+    // finished_at IS NULL means a conflicting insert can only mean another cycle already
+    // owns it. A run whose startedAt outlives `staleAfterMinutes` is presumed crashed and
+    // taken over: marked abandoned, then re-claimed inside the same transaction.
+    async claimRun(requestedRunId, staleAfterMinutes) {
+        const runId = requestedRunId ?? randomUUID();
+        return this.drizzle.db.transaction(async (txn) => {
+            const [inserted] = await txn
+                .insert(walletJobRun)
+                .values({ jobName: CUSTODY_SWEEP_JOB_NAME, runId })
+                .onConflictDoNothing()
+                .returning();
+            if (inserted) {
+                return { runId, jobRunId: inserted.id };
+            }
+            const [existing] = await txn
+                .select()
+                .from(walletJobRun)
+                .where(and(eq(walletJobRun.jobName, CUSTODY_SWEEP_JOB_NAME), isNull(walletJobRun.finishedAt)))
+                .for('update');
+            if (!existing) {
+                // The owning run finished between our failed insert and this read - let the
+                // next tick claim cleanly instead of racing a second insert here.
+                return null;
+            }
+            const staleMs = staleAfterMinutes * 60_000;
+            if (Date.now() - existing.startedAt.getTime() < staleMs) {
+                return null;
+            }
+            await txn
+                .update(walletJobRun)
+                .set({ status: 'abandoned', finishedAt: new Date() })
+                .where(eq(walletJobRun.id, existing.id));
+            const [takenOver] = await txn
+                .insert(walletJobRun)
+                .values({ jobName: CUSTODY_SWEEP_JOB_NAME, runId })
+                .returning();
+            if (!takenOver) {
+                throw new Error('wallet-custody-sweep: failed to claim run after abandoning a stale one');
+            }
+            return { runId, jobRunId: takenOver.id };
+        });
+    }
+    // Reusing getWithdrawalStatus for a sweep is deliberate: its {status, txHash} shape
+    // is generic to any vendor transaction (a withdrawal or a sweep), and a sweep's
+    // externalId is exactly the reference such a lookup needs.
+    async resolveInFlightSweeps(concurrency) {
+        const rows = await this.drizzle.db
+            .select()
+            .from(walletCustodySweep)
+            .where(and(inArray(walletCustodySweep.status, IN_FLIGHT_STATUSES), isNotNull(walletCustodySweep.externalId)));
+        await mapConcurrent(rows, concurrency, async (row) => {
+            const adapter = this.paymentProviders.get(row.providerName)?.adapter;
+            if (!adapter?.getWithdrawalStatus || !row.externalId) {
+                return;
+            }
+            const result = await adapter.getWithdrawalStatus(row.externalId);
+            if (!result || result.status === 'processing') {
+                return;
+            }
+            await this.drizzle.db
+                .update(walletCustodySweep)
+                .set({ status: result.status, txHash: result.txHash ?? row.txHash })
+                .where(eq(walletCustodySweep.id, row.id));
+        });
+    }
+    async assetFor(currency, network) {
+        const [row] = await this.drizzle.db
+            .select()
+            .from(walletAsset)
+            .where(and(eq(walletAsset.currency, currency), eq(walletAsset.network, network)));
+        return row ?? null;
+    }
+    async hasInFlightSweep(userId, currency, network) {
+        const [row] = await this.drizzle.db
+            .select({ id: walletCustodySweep.id })
+            .from(walletCustodySweep)
+            .where(and(eq(walletCustodySweep.userId, userId), eq(walletCustodySweep.currency, currency), eq(walletCustodySweep.network, network), inArray(walletCustodySweep.status, IN_FLIGHT_STATUSES)));
+        return row !== undefined;
+    }
+    async getPoolBalanceCached(cache, adapter, currency, network) {
+        if (!adapter.getPoolBalance) {
+            return null;
+        }
+        const key = `${currency}:${network}`;
+        const cached = cache.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const balance = await adapter.getPoolBalance(currency, network);
+        cache.set(key, balance);
+        return balance;
+    }
+    async processBalance({ providerName, adapter, balance, runId, sweepConfig, summary, poolBalanceCache, }) {
+        const asset = await this.assetFor(balance.currency, balance.network);
+        if (!asset) {
+            // Funds sitting in a container the operator has no policy for must be visible,
+            // not a log line.
+            await recordReconciliationFinding(this.drizzle.db, {
+                runId,
+                providerName,
+                kind: 'unconfigured_asset',
+                currency: balance.currency,
+                network: balance.network,
+                amount: balance.amount,
+                // No vendor reference exists for this finding, and the condition recurs every
+                // single cycle until an operator configures the asset - without a stable
+                // stand-in one missing catalog row files a finding every cron tick, drowning
+                // the real findings and pinning the alert threshold permanently over the line.
+                // The asset, not the player, is the subject: one row to act on, not one per
+                // affected container.
+                externalId: `unconfigured:${providerName}:${balance.currency}:${balance.network}`,
+                detail: `no wallet_asset configured for ${balance.currency}/${balance.network}`,
+            });
+            return;
+        }
+        const gateArgs = {
+            amount: balance.amount,
+            estimatedFee: balance.estimatedFee,
+            minDeposit: asset.minDeposit,
+            feeMultiple: sweepConfig.feeMultiple,
+            sweepFeeCeiling: asset.sweepFeeCeiling,
+            poolLiquidityFloor: asset.poolLiquidityFloor,
+        };
+        let decision = gateSweepBalance({ ...gateArgs, poolBalance: null });
+        // Only fetch the pool balance when the ceiling actually blocks - it's an extra
+        // vendor call, not a free one.
+        if (decision === 'ceiling' && asset.poolLiquidityFloor) {
+            const poolBalance = await this.getPoolBalanceCached(poolBalanceCache, adapter, balance.currency, balance.network);
+            decision = gateSweepBalance({ ...gateArgs, poolBalance });
+        }
+        if (decision === 'dust') {
+            summary.skippedDust += 1;
+            return;
+        }
+        if (decision === 'fee') {
+            summary.skippedFee += 1;
+            return;
+        }
+        if (decision === 'ceiling') {
+            summary.skippedCeiling += 1;
+            return;
+        }
+        if (await this.hasInFlightSweep(balance.userId, balance.currency, balance.network)) {
+            summary.inFlight += 1;
+            return;
+        }
+        const [claimed] = await this.drizzle.db
+            .insert(walletCustodySweep)
+            .values({
+            userId: balance.userId,
+            providerName,
+            currency: balance.currency,
+            network: balance.network,
+            amount: balance.amount,
+            estimatedFee: balance.estimatedFee,
+            status: 'pending',
+            runId,
+        })
+            .onConflictDoNothing()
+            .returning();
+        if (!claimed) {
+            // Another cycle claimed this (userId, currency, network) between the check above
+            // and this insert - the partial unique index is the real guard, this is a race.
+            summary.inFlight += 1;
+            return;
+        }
+        // Deliberately outside any transaction - sweepToPool is a real vendor call
+        // (docs/standards/money.md: treat external payment calls as non-transactional).
+        // The claim row above already holds the durable guard.
+        try {
+            const result = await adapter.sweepToPool?.(balance, { idempotencyKey: claimed.id });
+            if (!result) {
+                throw new Error(`provider "${providerName}" advertised listSweepableBalances but has no sweepToPool`);
+            }
+            await this.drizzle.db
+                .update(walletCustodySweep)
+                // poolRef records WHICH pool received the funds, not just that a transfer
+                // happened. Player funds must stay separate from operator funds, and that is
+                // the question a regulator asks; without it the ledger cannot answer it.
+                .set({
+                status: 'processing',
+                externalId: result.externalId,
+                poolRef: result.poolRef ?? null,
+            })
+                .where(eq(walletCustodySweep.id, claimed.id));
+            summary.swept += 1;
+        }
+        catch (err) {
+            // A thrown sweepToPool cannot distinguish "the vendor never saw it" from "the
+            // vendor accepted it and the response was lost" - moving to `failed` on the
+            // second case would let the next cycle sweep the same container again and
+            // double-transfer real custody funds. `unknown` keeps the in-flight guard held
+            // (see IN_FLIGHT_STATUSES) until reconciliation or an operator resolves it.
+            logger.warn({ err, sweepId: claimed.id }, 'sweepToPool threw; parking sweep as unknown');
+            await this.drizzle.db
+                .update(walletCustodySweep)
+                .set({ status: 'unknown' })
+                .where(eq(walletCustodySweep.id, claimed.id));
+            summary.unknown += 1;
+        }
+    }
+    async finishRun(jobRunId, runId, summary, status = 'completed', err) {
+        const error = err === undefined ? {} : { error: err instanceof Error ? err.message : String(err) };
+        await this.drizzle.db.transaction(async (txn) => {
+            await txn
+                .update(walletJobRun)
+                .set({ finishedAt: new Date(), status, summary: { ...summary, ...error } })
+                .where(eq(walletJobRun.id, jobRunId));
+            // One entry for the whole cycle, never one per swept balance -
+            // AuditService.recordInTransaction takes a single global advisory lock (the audit
+            // log is a hash chain), so one row per container at thousands of containers would
+            // serialize the entire platform's audit stream behind this job. wallet_custody_sweep
+            // rows are the per-move record; this is the cycle record, joined on runId.
+            await this.audit.recordInTransaction(txn, {
+                actorType: 'system',
+                action: 'wallet.custody.sweep_cycle',
+                resourceType: 'wallet_job_run',
+                resourceId: runId,
+                after: { runId, status, ...summary, ...error },
+            });
+        });
+    }
+}
+//# sourceMappingURL=custody-sweep.service.js.map

package/dist/wallet/service/custody-sweep.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custody-sweep.service.js","sourceRoot":"","sources":["../../../src/wallet/service/custody-sweep.service.ts"],"names":[],"mappings":"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"}

package/dist/wallet/service/reconciliation-finding.service.d.ts

@@ -0,0 +1,39 @@
+import type { DrizzleDb, DrizzleTx } from '@openora/core/server';
+import type { WalletReconciliationFindingKind } from '@openora/core/contracts';
+/**
+ * Sentinel `runId` for a finding produced OUTSIDE any reconciliation job cycle - the
+ * live webhook path (`WalletService.creditDepositByAddress`) hits an unattributable
+ * deposit in real time, not on a poll. `runId` is NOT NULL on the table, so this fixed
+ * zero-uuid documents "no job run owns this row", mirroring the audit plugin's
+ * SYSTEM_ACTOR sentinel for "no admin acted here".
+ */
+export declare const LIVE_WEBHOOK_RUN_ID = "00000000-0000-0000-0000-000000000000";
+export type ReconciliationFindingInput = {
+    runId: string;
+    providerName: string;
+    kind: WalletReconciliationFindingKind;
+    currency?: string | null;
+    network?: string | null;
+    amount?: string | null;
+    address?: string | null;
+    tag?: string | null;
+    txHash?: string | null;
+    /**
+     * The dedup key: a partial unique index on (kind, externalId) makes a duplicate
+     * insert for the same underlying vendor event or job re-run a silent no-op. Pass a
+     * stable stand-in (eg the source row's own id) when no vendor externalId exists, so
+     * a finding with no natural external reference still dedupes across re-runs.
+     */
+    externalId?: string | null;
+    transactionId?: string | null;
+    detail?: string | null;
+};
+/**
+ * The single write path for a reconciliation finding - never a raw `insert` scattered
+ * across WalletService and ReconciliationService (both import this, neither imports the
+ * other, so there is no cycle). A finding is a report, never a credit instruction (see
+ * the schema's own comment): this never touches a balance or a transaction row, only
+ * records that something needs a human look.
+ */
+export declare function recordReconciliationFinding(db: DrizzleDb | DrizzleTx, input: ReconciliationFindingInput): Promise<void>;
+//# sourceMappingURL=reconciliation-finding.service.d.ts.map

package/dist/wallet/service/reconciliation-finding.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconciliation-finding.service.d.ts","sourceRoot":"","sources":["../../../src/wallet/service/reconciliation-finding.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,yBAAyB,CAAC;AAG/E;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,yCAAyC,CAAC;AAE1E,MAAM,MAAM,0BAA0B,GAAG;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,+BAA+B,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,EAAE,EAAE,SAAS,GAAG,SAAS,EACzB,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,IAAI,CAAC,CAkBf"}

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

@@ -0,0 +1,36 @@
+import { walletReconciliationFinding } from '../schema/index.js';
+/**
+ * Sentinel `runId` for a finding produced OUTSIDE any reconciliation job cycle - the
+ * live webhook path (`WalletService.creditDepositByAddress`) hits an unattributable
+ * deposit in real time, not on a poll. `runId` is NOT NULL on the table, so this fixed
+ * zero-uuid documents "no job run owns this row", mirroring the audit plugin's
+ * SYSTEM_ACTOR sentinel for "no admin acted here".
+ */
+export const LIVE_WEBHOOK_RUN_ID = '00000000-0000-0000-0000-000000000000';
+/**
+ * The single write path for a reconciliation finding - never a raw `insert` scattered
+ * across WalletService and ReconciliationService (both import this, neither imports the
+ * other, so there is no cycle). A finding is a report, never a credit instruction (see
+ * the schema's own comment): this never touches a balance or a transaction row, only
+ * records that something needs a human look.
+ */
+export async function recordReconciliationFinding(db, input) {
+    await db
+        .insert(walletReconciliationFinding)
+        .values({
+        runId: input.runId,
+        providerName: input.providerName,
+        kind: input.kind,
+        currency: input.currency ?? null,
+        network: input.network ?? null,
+        amount: input.amount ?? null,
+        address: input.address ?? null,
+        tag: input.tag ?? null,
+        txHash: input.txHash ?? null,
+        externalId: input.externalId ?? null,
+        transactionId: input.transactionId ?? null,
+        detail: input.detail ?? null,
+    })
+        .onConflictDoNothing();
+}
+//# sourceMappingURL=reconciliation-finding.service.js.map

package/dist/wallet/service/reconciliation-finding.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconciliation-finding.service.js","sourceRoot":"","sources":["../../../src/wallet/service/reconciliation-finding.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,sCAAsC,CAAC;AAuB1E;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,EAAyB,EACzB,KAAiC;IAEjC,MAAM,EAAE;SACL,MAAM,CAAC,2BAA2B,CAAC;SACnC,MAAM,CAAC;QACN,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI;QAChC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI,IAAI;QACtB,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,IAAI;QAC1C,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;KAC7B,CAAC;SACD,mBAAmB,EAAE,CAAC;AAC3B,CAAC"}

package/dist/wallet/service/reconciliation.service.d.ts

@@ -0,0 +1,112 @@
+import { type DrizzleService, type EventBus } from '@openora/core/server';
+import { type AuditWritePort, type ClientMeta, type PaymentProviderRegistry, type PaymentWebhookEvent, type PlatformConfig, type User } from '@openora/core/contracts';
+import { type WalletJobRun, type WalletReconciliationFinding as WalletReconciliationFindingRow, type WalletTransaction } from '../schema/index.js';
+import type { ListReconciliationFindingsInput, ReconciliationResolution, WalletReconciliationFinding as WalletReconciliationFindingDto } from '../contract/index.js';
+import type { WalletService } from './wallet.service.js';
+export declare const ReconciliationFindingNotFoundError: new (id: string) => Error;
+export declare const ReconciliationCreditTransactionNotFoundError: new (id: string) => Error;
+export declare const ReconciliationCreditMismatchError: new () => Error;
+type LedgerMatch = Pick<WalletTransaction, 'id' | 'currency' | 'amount' | 'network'>;
+/**
+ * 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 declare function diffDeposit(event: Extract<PaymentWebhookEvent, {
+    kind: 'deposit';
+}>, tx: LedgerMatch | undefined): 'missing_deposit' | 'currency_mismatch' | 'amount_mismatch' | null;
+export type ReconciliationServiceDeps = {
+    drizzle: DrizzleService;
+    events: EventBus;
+    wallet: WalletService;
+    paymentProviders: PaymentProviderRegistry;
+    audit: AuditWritePort;
+    platformConfig?: PlatformConfig;
+};
+/**
+ * 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 declare class ReconciliationService {
+    private readonly drizzle;
+    private readonly events;
+    private readonly wallet;
+    private readonly paymentProviders;
+    private readonly audit;
+    private readonly platformConfig?;
+    constructor({ drizzle, events, wallet, paymentProviders, audit, platformConfig, }: ReconciliationServiceDeps);
+    listFindings(filter: ListReconciliationFindingsInput): Promise<{
+        items: {
+            id: string;
+            runId: string;
+            providerName: string;
+            kind: "missing_deposit" | "unattributed_deposit" | "amount_mismatch" | "currency_mismatch" | "status_mismatch" | "unknown_at_provider" | "unconfigured_asset" | "stuck_sweep";
+            currency: string | null;
+            network: string | null;
+            amount: string | null;
+            address: string | null;
+            tag: string | null;
+            txHash: string | null;
+            externalId: string | null;
+            transactionId: string | null;
+            detail: string | null;
+            status: "open" | "resolved";
+            resolvedBy: string | null;
+            resolvedAt: string | null;
+            resolutionNote: string | null;
+            createdAt: string;
+        }[];
+        total: number;
+        page: number;
+        limit: number;
+    }>;
+    /**
+     * 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.
+     */
+    resolveFinding(adminId: User['id'], id: WalletReconciliationFindingRow['id'], resolution: ReconciliationResolution, meta?: ClientMeta): Promise<WalletReconciliationFindingDto>;
+    /**
+     * 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.
+     */
+    private resolveWindow;
+    /**
+     * 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.
+     */
+    runCycle(runId?: WalletJobRun['runId']): Promise<{
+        runId: WalletJobRun['runId'];
+    } | null>;
+    private reconcileProvider;
+    private sweptExternalIds;
+    private reconcileDeposits;
+    private batchLookupByProviderRefId;
+    private reconcileStuckWithdrawals;
+    private reconcileStuckSweeps;
+    private countOpenFindings;
+    /**
+     * 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.
+     */
+    private claimRun;
+    private retryClaim;
+    private finishRun;
+}
+export {};
+//# sourceMappingURL=reconciliation.service.d.ts.map

package/dist/wallet/service/reconciliation.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconciliation.service.d.ts","sourceRoot":"","sources":["../../../src/wallet/service/reconciliation.service.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,QAAQ,EAQd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,IAAI,EAEV,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,2BAA2B,IAAI,8BAA8B,EAClE,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,+BAA+B,EAC/B,wBAAwB,EACxB,2BAA2B,IAAI,8BAA8B,EAC9D,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAKzD,eAAO,MAAM,kCAAkC,2BAA6C,CAAC;AAE7F,eAAO,MAAM,4CAA4C,2BAExD,CAAC;AAEF,eAAO,MAAM,iCAAiC,iBAG7C,CAAC;AAEF,KAAK,WAAW,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAC;AAErF;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,CAAC,mBAAmB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,EACxD,EAAE,EAAE,WAAW,GAAG,SAAS,GAC1B,iBAAiB,GAAG,mBAAmB,GAAG,iBAAiB,GAAG,IAAI,CAWpE;AAmCD,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,KAAK,EAAE,cAAc,CAAC;IACtB,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA0B;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAiB;gBAErC,EACV,OAAO,EACP,MAAM,EACN,MAAM,EACN,gBAAgB,EAChB,KAAK,EACL,cAAc,GACf,EAAE,yBAAyB;IAStB,YAAY,CAAC,MAAM,EAAE,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;IAiC1D;;;;;;OAMG;IACG,cAAc,CAClB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,EACnB,EAAE,EAAE,8BAA8B,CAAC,IAAI,CAAC,EACxC,UAAU,EAAE,wBAAwB,EACpC,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,8BAA8B,CAAC;IAkF1C;;;;;;;OAOG;YACW,aAAa;IAyB3B;;;;;OAKG;IACG,QAAQ,CACZ,KAAK,GAAE,YAAY,CAAC,OAAO,CAAgB,GAC1C,OAAO,CAAC;QAAE,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;YAqFrC,iBAAiB;YA2CjB,gBAAgB;YAahB,iBAAiB;YAgDjB,0BAA0B;YAoB1B,yBAAyB;YAmEzB,oBAAoB;YAsCpB,iBAAiB;IAQ/B;;;;;OAKG;YACW,QAAQ;YAkCR,UAAU;YAaV,SAAS;CAUxB"}