feat(wallet): reconciliation job, admin report, and unattributed-deposit findings

docs/catalog.json

@@ -955,6 +955,7 @@
     "tag.rule.upserted",
     "wallet.deposit.completed",
     "wallet.manual_adjustment.created",
+    "wallet.reconciliation.alert",
     "wallet.withdrawal.approved",
     "wallet.withdrawal.completed",
     "wallet.withdrawal.failed",

packages/core/src/audit/plugin.ts

@@ -580,6 +580,19 @@ export async function mapEventToRecord(
     };
   }
 
+  // System-driven: a reconciliation run's open findings exceeded the configured
+  // threshold. resource = the run itself; after carries counts only, NEVER a finding's
+  // payload (an address or tx hash must never reach the audit log through this event).
+  if (topic === 'wallet.reconciliation.alert') {
+    return {
+      ...base,
+      actorType: 'system',
+      resourceType: 'wallet_job_run',
+      resourceId: str(p['runId']),
+      after: { openFindings: p['openFindings'] ?? null, threshold: p['threshold'] ?? null },
+    };
+  }
+
   // Wallet events carry the txn ref in transactionId; surface it as resourceId so
   // a transaction reference is searchable (it otherwise stays buried in `after`).
   // actorId = the resolved playerId (the wallet owner).
@@ -656,6 +669,7 @@ const SUBSCRIBED_TOPICS: DomainEventName[] = [
   'wallet.withdrawal.approved',
   'wallet.withdrawal.rejected',
   'wallet.withdrawal.failed',
+  'wallet.reconciliation.alert',
   'gaming.round.started',
   'gaming.round.ended',
   'chat.user.blocked',

packages/core/src/contracts/adapters/audit.ts

@@ -25,7 +25,10 @@ export type DirectAuditAction =
   | 'wallet.auto_withdrawal_rule.deleted'
   | 'wallet.auto_withdrawal_config.set'
   | 'wallet.manual_adjustment.created'
-  | 'wallet.custody.sweep_cycle';
+  | 'wallet.custody.sweep_cycle'
+  | 'wallet.reconciliation_run.completed'
+  | 'wallet.reconciliation_run.failed'
+  | 'wallet.reconciliation_finding.resolved';
 
 /**
  * Every value the audit `action` column legitimately holds: a cross-module domain

packages/core/src/contracts/schemas/events.ts

@@ -174,6 +174,15 @@ export const domainEventSchemas = {
       reason: z.string(),
     })
     .extend(authContextBase.shape),
+  // A reconciliation run's open-findings count exceeded the operator's configured
+  // threshold. System-driven (no player/admin actor) - the resource is the run itself,
+  // never a finding's payload (an address or tx hash must never reach the audit log
+  // through this event - see docs/standards/audit.md).
+  'wallet.reconciliation.alert': z.object({
+    runId: UuidSchema,
+    openFindings: z.number().int().nonnegative(),
+    threshold: z.number().int().nonnegative(),
+  }),
 
   'gaming.round.started': z.object({
     roundId: UuidSchema,

packages/core/src/testing/mock.ts

@@ -12,6 +12,7 @@ import {
   type AuditWritePort,
   type ClientMeta,
   type IdentityReader,
+  type JobQueueAdapter,
   type PaymentAdapter,
   type PaymentProviderRegistry,
   type PaymentWebhookVerifier,
@@ -134,6 +135,17 @@ export const makePaymentProviderRegistry = (
   };
 };
 
+/** JobQueueAdapter double whose `enqueue` is a vitest mock, for a router test that only
+ * needs to assert a job was enqueued, never that it actually ran. */
+export const makeJobQueue = (): JobQueueAdapter & { enqueue: Mock } =>
+  mock<JobQueueAdapter & { enqueue: Mock }>({
+    enqueue: vi.fn(async () => ({ id: 'test-job' })),
+    schedule: vi.fn(async () => undefined),
+    unschedule: vi.fn(async () => undefined),
+    registerWorker: vi.fn(),
+    close: vi.fn(async () => undefined),
+  });
+
 export const makeIdentityReader = (): IdentityReader =>
   mock<IdentityReader>({
     getLastLoginAt: vi.fn().mockResolvedValue(null),

packages/core/src/wallet/__tests__/reconciliation-diff.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { diffDeposit } from '../service/reconciliation.service.js';
+
+const depositEvent = (over: Partial<Parameters<typeof diffDeposit>[0]> = {}) => ({
+  kind: 'deposit' as const,
+  address: 'bc1qxyz',
+  amount: '1',
+  currency: 'BTC',
+  txHash: '0xabc',
+  externalId: 'vendor-ext-1',
+  ...over,
+});
+
+const ledgerRow = (
+  over: Partial<{ id: string; currency: string; amount: string; network: string | null }> = {},
+) => ({
+  id: 'tx-1',
+  currency: 'BTC',
+  amount: '1',
+  network: null,
+  ...over,
+});
+
+describe('diffDeposit', () => {
+  it('flags missing_deposit when no ledger row matches the vendor event', () => {
+    expect(diffDeposit(depositEvent(), undefined)).toBe('missing_deposit');
+  });
+
+  it('flags currency_mismatch when the ledger row settled in a different currency', () => {
+    const event = depositEvent({ currency: 'ETH' });
+    const tx = ledgerRow({ currency: 'BTC' });
+
+    expect(diffDeposit(event, tx)).toBe('currency_mismatch');
+  });
+
+  it('flags currency_mismatch case-insensitively as a genuine mismatch, not a false positive', () => {
+    const event = depositEvent({ currency: 'btc' });
+    const tx = ledgerRow({ currency: 'BTC' });
+
+    expect(diffDeposit(event, tx)).toBeNull();
+  });
+
+  it('flags amount_mismatch when the currencies agree but the amounts differ', () => {
+    const event = depositEvent({ amount: '2' });
+    const tx = ledgerRow({ amount: '1' });
+
+    expect(diffDeposit(event, tx)).toBe('amount_mismatch');
+  });
+
+  it('never routes an amount compare through float - "1" and "1.00" reconcile exactly', () => {
+    const event = depositEvent({ amount: '1.00' });
+    const tx = ledgerRow({ amount: '1' });
+
+    expect(diffDeposit(event, tx)).toBeNull();
+  });
+
+  it('reconciles (returns null) when currency and amount both match', () => {
+    const event = depositEvent();
+    const tx = ledgerRow();
+
+    expect(diffDeposit(event, tx)).toBeNull();
+  });
+});