thevoidforge 21.0.0

package/dist/wizard/lib/financial/reporting.js

@@ -0,0 +1,198 @@
+/**
+ * Financial Reporting + Export — daily reports, monthly ledgers, and funding simulation.
+ *
+ * Pure logic — no API calls, no file I/O, fully testable.
+ * All monetary values use branded integer cents (Cents type).
+ * Output formats: markdown (daily), JSON (monthly), simulation object.
+ *
+ * PRD Reference: §16 (Reporting and Reconciliation)
+ * Agents: Dockson (treasury), Heartbeat daemon
+ */
+import { forecastSpend } from './treasury-planner.js';
+import { evaluatePolicy, aggregateDecisions } from './funding-policy.js';
+// ── Shared Helpers ───────────────────────────────────
+function centsToUsd(cents) {
+    return `$${(cents / 100).toFixed(2)}`;
+}
+// ── Daily Report Generator ───────────────────────────
+export function generateDailyReport(input) {
+    const netCents = input.revenueCents - input.spendCents;
+    const netSign = netCents >= 0 ? '+' : '';
+    const lines = [
+        `# Treasury Daily Report — ${input.date}`,
+        '',
+        '## Revenue & Spend',
+        `| Metric | Amount |`,
+        `|--------|--------|`,
+        `| Revenue | ${centsToUsd(input.revenueCents)} |`,
+        `| Spend | ${centsToUsd(input.spendCents)} |`,
+        `| **Net** | **${netSign}${centsToUsd(netCents)}** |`,
+        '',
+        '## Stablecoin Position',
+        `| Metric | Amount |`,
+        `|--------|--------|`,
+        `| Stablecoin Balance | ${centsToUsd(input.stablecoinBalanceCents)} |`,
+        `| Pending Transfers | ${centsToUsd(input.pendingTransfersCents)} |`,
+        '',
+        '## Bank Position',
+        `| Metric | Amount |`,
+        `|--------|--------|`,
+        `| Bank Balance | ${centsToUsd(input.bankBalanceCents)} |`,
+        `| Settled Today | ${centsToUsd(input.settledTodayCents)} |`,
+        `| Runway | ${input.runwayDays === Infinity ? 'Unlimited' : `${input.runwayDays} days`} |`,
+        '',
+    ];
+    // Reconciliation section
+    if (input.reconciliation) {
+        const r = input.reconciliation;
+        lines.push('## Reconciliation', `| Metric | Value |`, `|--------|-------|`, `| Transfers Matched | ${r.transferMatches.length} |`, `| Spend Matched | ${r.spendMatches.length} |`, `| Unmatched Transfers | ${r.unmatchedTransfers.length} |`, `| Unmatched Bank Txns | ${r.unmatchedBankTransactions.length} |`, `| Overall Variance | ${centsToUsd(r.overallVarianceCents)} |`, `| Mismatches | ${r.mismatchCount} |`, '');
+    }
+    else {
+        lines.push('## Reconciliation', '', 'No reconciliation data for this date.', '');
+    }
+    // Circuit breakers
+    if (input.activeCircuitBreakers.length > 0 || input.fundingFrozen) {
+        lines.push('## Circuit Breakers', '');
+        if (input.fundingFrozen) {
+            lines.push(`**FUNDING FROZEN:** ${input.freezeReason ?? 'Unknown reason'}`, '');
+        }
+        for (const cb of input.activeCircuitBreakers) {
+            lines.push(`- ${cb}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+// ── Monthly Ledger Generator ─────────────────────────
+export function generateMonthlyLedger(month, transfers, reconciliations) {
+    const totalTransfersCents = transfers.reduce((sum, t) => sum + t.amountCents, 0);
+    const totalFeesCents = transfers.reduce((sum, t) => sum + t.feesCents, 0);
+    const totalNetTransferredCents = transfers.reduce((sum, t) => sum + t.netAmountCents, 0);
+    const totalSpendCents = reconciliations.reduce((sum, r) => sum + r.spendCents, 0);
+    const totalBankSettledCents = reconciliations.reduce((sum, r) => sum + r.bankSettledCents, 0);
+    const totalVarianceCents = reconciliations.reduce((sum, r) => sum + r.varianceCents, 0);
+    const mismatchCount = reconciliations.filter(r => r.result === 'MISMATCH').length;
+    return {
+        month,
+        generatedAt: new Date().toISOString(),
+        transfers,
+        reconciliations,
+        summary: {
+            totalTransfersCents,
+            totalFeesCents,
+            totalNetTransferredCents,
+            totalSpendCents,
+            totalBankSettledCents,
+            totalVarianceCents,
+            transferCount: transfers.length,
+            reconciliationCount: reconciliations.length,
+            mismatchCount,
+        },
+    };
+}
+// ── Funding Simulation ───────────────────────────────
+// Projects forward N days showing when off-ramp triggers,
+// expected bank balance trajectory, and freeze risk dates.
+export function simulateFunding(startDate, startingBankBalanceCents, config, campaigns, days, stablecoinAvailableCents, minimumBufferCents) {
+    const dailySpendCents = forecastSpend(campaigns, 1);
+    const simDays = [];
+    let bankBalance = startingBankBalanceCents;
+    let stablecoinRemaining = stablecoinAvailableCents;
+    let firstOfframpDay = null;
+    let totalOfframpsCents = 0;
+    let offrampCount = 0;
+    let minimumBalance = bankBalance;
+    let minimumBalanceDay = 0;
+    const freezeRiskDays = [];
+    const startMs = new Date(startDate).getTime();
+    const oneDayMs = 24 * 60 * 60 * 1000;
+    for (let d = 0; d < days; d++) {
+        const dayDate = new Date(startMs + d * oneDayMs).toISOString().slice(0, 10);
+        const spend = dailySpendCents;
+        // Deduct daily spend
+        bankBalance -= spend;
+        // Check if off-ramp should trigger
+        let offrampTriggered = false;
+        let offrampAmount = 0;
+        let policyBlocked = false;
+        let freezeRisk = false;
+        if (bankBalance < config.bufferTargetCents) {
+            // Need an off-ramp
+            const deficit = config.bufferTargetCents - bankBalance;
+            const clampedAmount = Math.min(deficit, config.maxDailyOfframpCents, stablecoinRemaining);
+            if (clampedAmount >= config.minimumOfframpCents && stablecoinRemaining > 0) {
+                // Simulate policy evaluation
+                const policyState = {
+                    bankBalanceCents: bankBalance,
+                    minimumBufferCents,
+                    reservedCents: 0,
+                    proposedOfframpCents: clampedAmount,
+                    maxDailyMovementCents: config.maxDailyOfframpCents,
+                    googleInvoiceDueSoon: false,
+                    googleInvoiceCents: 0,
+                    metaUsesDirectDebit: false,
+                    metaForecast7DayCents: 0,
+                    debitProtectionBufferCents: 0,
+                    discrepancyExists: false,
+                    proposingBudgetRaise: false,
+                    platformCapability: 'FULLY_FUNDABLE',
+                    claimingAutonomousFunding: true,
+                };
+                const decisions = evaluatePolicy(policyState);
+                const aggregate = aggregateDecisions(decisions);
+                if (aggregate.action === 'allow') {
+                    offrampTriggered = true;
+                    offrampAmount = clampedAmount;
+                    bankBalance += clampedAmount;
+                    stablecoinRemaining -= clampedAmount;
+                    totalOfframpsCents += clampedAmount;
+                    offrampCount++;
+                    if (firstOfframpDay === null)
+                        firstOfframpDay = d + 1;
+                }
+                else {
+                    policyBlocked = true;
+                }
+            }
+        }
+        // Freeze risk: balance below minimum buffer
+        if (bankBalance < minimumBufferCents) {
+            freezeRisk = true;
+            freezeRiskDays.push(d + 1);
+        }
+        // Track minimum balance
+        if (bankBalance < minimumBalance) {
+            minimumBalance = bankBalance;
+            minimumBalanceDay = d + 1;
+        }
+        simDays.push({
+            day: d + 1,
+            date: dayDate,
+            bankBalanceCents: Math.round(bankBalance),
+            spendCents: spend,
+            offrampTriggered,
+            offrampAmountCents: Math.round(offrampAmount),
+            policyBlocked,
+            freezeRisk,
+        });
+    }
+    return {
+        config: {
+            startDate,
+            days,
+            startingBankBalanceCents,
+            bufferTargetCents: config.bufferTargetCents,
+            maxDailyOfframpCents: config.maxDailyOfframpCents,
+        },
+        days: simDays,
+        summary: {
+            firstOfframpDay,
+            totalOfframpsCents: Math.round(totalOfframpsCents),
+            offrampCount,
+            minimumBalanceCents: Math.round(minimumBalance),
+            minimumBalanceDay,
+            freezeRiskDays,
+            finalBalanceCents: Math.round(bankBalance),
+        },
+    };
+}

package/dist/wizard/lib/financial/stablecoin/base.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Stablecoin adapter types — re-exports from the pattern file.
+ * ARCH-R2-012: Production code should not import from docs/patterns/ directly.
+ */
+export type { StablecoinSetup, StablecoinAdapter, StablecoinProvider, SupportedAsset, ProviderCredentials, StablecoinBalance, FiatBalance, CombinedBalances, OfframpQuote, TransferStatus, TransferRecord, TransferStatusDetail, FundingPlanRef, DateRange, } from '../../patterns/stablecoin-adapter.js';
+export { toCents, toDollars, computeTransferHash } from '../../patterns/stablecoin-adapter.js';

package/dist/wizard/lib/financial/stablecoin/base.js

@@ -0,0 +1 @@
+export { toCents, toDollars, computeTransferHash } from '../../patterns/stablecoin-adapter.js';

package/dist/wizard/lib/financial/stablecoin/circle.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Circle Stablecoin Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements StablecoinSetup (interactive CLI) + StablecoinAdapter (daemon runtime)
+ * for Circle's Business Account API v1.
+ *
+ * Circle API v1:
+ *   Base URL: https://api.circle.com/v1
+ *   Auth: Authorization: Bearer {apiKey}
+ *
+ * PRD Reference: §11.1A, §12.1, §12.4, §12.5
+ * No Stubs Doctrine: every method makes a real API call (except quoteRedemption — local computation).
+ */
+import type { StablecoinSetup, StablecoinAdapter, ProviderCredentials, SupportedAsset, StablecoinBalance, CombinedBalances, OfframpQuote, TransferRecord, TransferStatusDetail, FundingPlanRef, DateRange } from './base.js';
+type Cents = number & {
+    readonly __brand: 'Cents';
+};
+export declare class CircleSetup implements StablecoinSetup {
+    private apiKey;
+    constructor(apiKey: string);
+    authenticate(_credentials: ProviderCredentials): Promise<{
+        valid: boolean;
+        accountId?: string;
+        permissions?: string[];
+        error?: string;
+    }>;
+    verifySupportedAssets(_credentials: ProviderCredentials): Promise<SupportedAsset[]>;
+    verifyLinkedBank(_credentials: ProviderCredentials): Promise<{
+        linked: boolean;
+        bankId?: string;
+        bankName?: string;
+        accountLast4?: string;
+        error?: string;
+    }>;
+    getInitialBalances(_credentials: ProviderCredentials): Promise<StablecoinBalance[]>;
+}
+export declare class CircleAdapter implements StablecoinAdapter {
+    private apiKey;
+    private bankId;
+    constructor(config: {
+        apiKey: string;
+        bankId: string;
+    });
+    getBalances(): Promise<CombinedBalances>;
+    quoteRedemption(amountCents: Cents): Promise<OfframpQuote>;
+    initiateOfframp(plan: FundingPlanRef, previousHash: string): Promise<TransferRecord>;
+    getTransferStatus(transferId: string): Promise<TransferStatusDetail>;
+    cancelTransfer(_transferId: string): Promise<{
+        cancelled: boolean;
+        reason?: string;
+    }>;
+    listCompletedTransfers(dateRange: DateRange): Promise<TransferRecord[]>;
+}
+export {};

package/dist/wizard/lib/financial/stablecoin/circle.js

@@ -0,0 +1,367 @@
+/**
+ * Circle Stablecoin Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements StablecoinSetup (interactive CLI) + StablecoinAdapter (daemon runtime)
+ * for Circle's Business Account API v1.
+ *
+ * Circle API v1:
+ *   Base URL: https://api.circle.com/v1
+ *   Auth: Authorization: Bearer {apiKey}
+ *
+ * PRD Reference: §11.1A, §12.1, §12.4, §12.5
+ * No Stubs Doctrine: every method makes a real API call (except quoteRedemption — local computation).
+ */
+import { randomUUID } from 'node:crypto';
+import { request as httpsRequest } from 'node:https';
+import { toCents, toDollars, computeTransferHash } from './base.js';
+const CIRCLE_HOST = 'api.circle.com';
+// ── HTTP helpers ─────────────────────────────────────
+async function circleGet(path, apiKey, params) {
+    const query = params ? '?' + new URLSearchParams(params).toString() : '';
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: CIRCLE_HOST,
+            path: `/v1${path}${query}`,
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Accept': 'application/json',
+            },
+            timeout: 15000,
+        }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => { data += chunk.toString(); });
+            res.on('end', () => resolve({ status: res.statusCode ?? 500, body: data }));
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('Circle API timeout')); });
+        req.end();
+    });
+}
+async function circlePost(path, apiKey, body) {
+    const payload = JSON.stringify(body);
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: CIRCLE_HOST,
+            path: `/v1${path}`,
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+            },
+            timeout: 15000,
+        }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => { data += chunk.toString(); });
+            res.on('end', () => resolve({ status: res.statusCode ?? 500, body: data }));
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('Circle API timeout')); });
+        req.write(payload);
+        req.end();
+    });
+}
+/** Parse JSON response body; on failure return a descriptive error object. */
+function safeParseJson(body) {
+    // VG-R1-005: Wrap error-path JSON.parse in try/catch
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return { error: { message: 'Non-JSON response from Circle API' } };
+    }
+}
+/** Map Circle payout status strings to our TransferStatus union. */
+function mapCircleStatus(circleStatus) {
+    switch (circleStatus) {
+        case 'pending': return 'pending';
+        case 'processing': return 'processing';
+        case 'complete': return 'completed';
+        case 'failed': return 'failed';
+        default: return 'pending';
+    }
+}
+// ── Setup Implementation ─────────────────────────────
+export class CircleSetup {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async authenticate(_credentials) {
+        try {
+            const { status, body } = await circleGet('/configuration', this.apiKey);
+            if (status === 200) {
+                const data = safeParseJson(body);
+                const payments = data.data?.payments;
+                return {
+                    valid: true,
+                    accountId: payments?.masterWalletId,
+                    permissions: ['read_balances', 'initiate_payouts', 'read_payouts'],
+                };
+            }
+            const parsed = safeParseJson(body);
+            const err = parsed.error;
+            return { valid: false, error: err?.message ?? `HTTP ${status}` };
+        }
+        catch (err) {
+            return { valid: false, error: err instanceof Error ? err.message : 'Connection failed' };
+        }
+    }
+    async verifySupportedAssets(_credentials) {
+        // Circle supports USDC on multiple networks. The /configuration endpoint
+        // confirms available chains but does not list contract addresses per-chain.
+        // We return the known production USDC contract addresses for supported networks.
+        return [
+            { asset: 'USDC', network: 'ETH', contractAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', minRedemption: toCents(100) },
+            { asset: 'USDC', network: 'SOL', contractAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', minRedemption: toCents(100) },
+            { asset: 'USDC', network: 'MATIC', contractAddress: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359', minRedemption: toCents(100) },
+            { asset: 'USDC', network: 'AVAX', contractAddress: '0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e', minRedemption: toCents(100) },
+        ];
+    }
+    async verifyLinkedBank(_credentials) {
+        try {
+            const { status, body } = await circleGet('/businessAccount/banks/wires', this.apiKey);
+            if (status !== 200) {
+                const parsed = safeParseJson(body);
+                const err = parsed.error;
+                return { linked: false, error: err?.message ?? `HTTP ${status}` };
+            }
+            const parsed = safeParseJson(body);
+            const banks = parsed.data;
+            if (!banks || banks.length === 0) {
+                return { linked: false, error: 'No linked wire bank accounts found in Circle' };
+            }
+            const primary = banks[0];
+            const billingDetails = primary.billingDetails;
+            return {
+                linked: true,
+                bankId: primary.id,
+                bankName: billingDetails?.name,
+                accountLast4: primary.trackingRef
+                    ? primary.trackingRef.slice(-4)
+                    : undefined,
+            };
+        }
+        catch (err) {
+            return { linked: false, error: err instanceof Error ? err.message : 'Connection failed' };
+        }
+    }
+    async getInitialBalances(_credentials) {
+        try {
+            const { status, body } = await circleGet('/businessAccount/balances', this.apiKey);
+            if (status !== 200)
+                return [];
+            const parsed = safeParseJson(body);
+            const data = parsed.data;
+            const available = data?.available;
+            if (!available)
+                return [];
+            const now = new Date().toISOString();
+            return available
+                .filter(b => b.currency === 'USD')
+                .map(b => ({
+                provider: 'circle',
+                asset: 'USDC',
+                network: 'ETH',
+                balanceCents: toCents(parseFloat(b.amount)),
+                lastUpdated: now,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+}
+// ── Runtime Adapter Implementation ───────────────────
+export class CircleAdapter {
+    apiKey;
+    bankId;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.bankId = config.bankId;
+    }
+    async getBalances() {
+        const { status, body } = await circleGet('/businessAccount/balances', this.apiKey);
+        if (status !== 200) {
+            // VG-R1-005: safe parse
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.error?.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`Circle getBalances failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        const data = parsed.data;
+        const available = data?.available ?? [];
+        const now = new Date().toISOString();
+        const stablecoin = available
+            .filter(b => b.currency === 'USD')
+            .map(b => ({
+            provider: 'circle',
+            asset: 'USDC',
+            network: 'ETH',
+            balanceCents: toCents(parseFloat(b.amount)),
+            lastUpdated: now,
+        }));
+        const totalStablecoinCents = stablecoin.reduce((sum, b) => (sum + b.balanceCents), 0);
+        return {
+            stablecoin,
+            fiat: [],
+            totalStablecoinCents,
+            totalFiatAvailableCents: 0,
+        };
+    }
+    async quoteRedemption(amountCents) {
+        // Circle wire payout fee: typically $25 flat for domestic wire.
+        // No API endpoint for quotes — computed locally based on known fee structure.
+        const feeCents = toCents(25);
+        return {
+            provider: 'circle',
+            sourceAsset: 'USDC',
+            sourceNetwork: 'ETH',
+            requestedCents: amountCents,
+            estimatedFeeCents: feeCents,
+            estimatedNetCents: (amountCents - feeCents),
+            estimatedSettlementMinutes: 24 * 60, // 1 business day
+            expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
+        };
+    }
+    async initiateOfframp(plan, previousHash) {
+        const { status, body } = await circlePost('/businessAccount/payouts', this.apiKey, {
+            idempotencyKey: plan.idempotencyKey,
+            source: { type: 'wallet', id: 'master' },
+            destination: { type: 'wire', id: this.bankId },
+            amount: { amount: toDollars(plan.requiredCents).toFixed(2), currency: 'USD' },
+        });
+        if (status !== 200 && status !== 201) {
+            // VG-R1-005: safe parse
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.error?.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`Circle initiateOfframp failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        const payout = parsed.data;
+        const now = new Date().toISOString();
+        const id = randomUUID();
+        const feeCents = toCents(25);
+        const record = {
+            id,
+            fundingPlanId: plan.id,
+            providerTransferId: payout.id,
+            provider: 'circle',
+            direction: 'crypto_to_fiat',
+            sourceAsset: 'USDC',
+            sourceNetwork: 'ETH',
+            amountCents: plan.requiredCents,
+            feesCents: feeCents,
+            netAmountCents: (plan.requiredCents - feeCents),
+            destinationBankId: plan.destinationBankId,
+            status: 'pending',
+            initiatedAt: now,
+            idempotencyKey: plan.idempotencyKey,
+            previousHash,
+        };
+        const hash = computeTransferHash(record, previousHash);
+        return { ...record, hash };
+    }
+    async getTransferStatus(transferId) {
+        const { status, body } = await circleGet(`/businessAccount/payouts/${transferId}`, this.apiKey);
+        if (status !== 200) {
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.error?.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`Circle getTransferStatus failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        const payout = parsed.data;
+        const amount = payout.amount;
+        const fees = payout.fees;
+        const mappedStatus = mapCircleStatus(payout.status);
+        return {
+            transferId,
+            providerTransferId: payout.id,
+            status: mappedStatus,
+            amountCents: toCents(parseFloat(amount.amount)),
+            feesCents: fees ? toCents(parseFloat(fees.amount)) : 0,
+            initiatedAt: payout.createDate,
+            completedAt: mappedStatus === 'completed' ? payout.updateDate : undefined,
+            estimatedCompletionAt: mappedStatus !== 'completed'
+                ? new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString()
+                : undefined,
+            providerRawStatus: payout.status,
+        };
+    }
+    async cancelTransfer(_transferId) {
+        // Circle does not support programmatic payout cancellation via API.
+        // Wire payouts cannot be cancelled once submitted.
+        return {
+            cancelled: false,
+            reason: 'Circle does not support programmatic payout cancellation. Contact support for pending payouts.',
+        };
+    }
+    async listCompletedTransfers(dateRange) {
+        const params = {
+            destination: this.bankId,
+            status: 'complete',
+        };
+        const { status, body } = await circleGet('/businessAccount/payouts', this.apiKey, params);
+        if (status !== 200) {
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.error?.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`Circle listCompletedTransfers failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        const payouts = parsed.data ?? [];
+        const rangeStart = new Date(dateRange.start).getTime();
+        const rangeEnd = new Date(dateRange.end).getTime();
+        // Filter by date range client-side (Circle API pagination doesn't support date filters directly)
+        return payouts
+            .filter(p => {
+            const created = new Date(p.createDate).getTime();
+            return created >= rangeStart && created <= rangeEnd;
+        })
+            .map(p => {
+            const amount = p.amount;
+            const fees = p.fees;
+            const amountCents = toCents(parseFloat(amount.amount));
+            const feesCents = fees ? toCents(parseFloat(fees.amount)) : toCents(0);
+            // Use Circle payout ID as stable identifier instead of randomUUID()
+            // to ensure idempotent reads return consistent IDs for the same payout.
+            const id = p.id;
+            const record = {
+                id,
+                fundingPlanId: '',
+                providerTransferId: p.id,
+                provider: 'circle',
+                direction: 'crypto_to_fiat',
+                sourceAsset: 'USDC',
+                sourceNetwork: 'ETH',
+                amountCents,
+                feesCents,
+                netAmountCents: (amountCents - feesCents),
+                destinationBankId: this.bankId,
+                status: 'completed',
+                initiatedAt: p.createDate,
+                completedAt: p.updateDate,
+                idempotencyKey: '',
+                previousHash: '',
+            };
+            const hash = computeTransferHash(record, '');
+            return { ...record, hash };
+        });
+    }
+}

package/dist/wizard/lib/financial/stablecoin/mercury.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Mercury Bank Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements RevenueSourceAdapter for Mercury's REST API.
+ * Mercury is a bank, not a stablecoin provider — this reads bank balances
+ * and transactions for treasury visibility (same pattern as Stripe adapter).
+ *
+ * Mercury API v1:
+ *   Base URL: https://api.mercury.com/api/v1
+ *   Auth: Authorization: Bearer {apiKey}
+ *
+ * PRD Reference: §12.2 (Operating Bank Account)
+ * No Stubs Doctrine: every method makes a real API call.
+ */
+import type { RevenueSourceAdapter, RevenueCredentials, ConnectionResult, TransactionPage, BalanceResult, DateRange } from '../../revenue-types.js';
+export declare class MercuryBankAdapter implements RevenueSourceAdapter {
+    private apiKey;
+    private accountId;
+    constructor(apiKey: string, accountId?: string);
+    connect(_credentials?: RevenueCredentials): Promise<ConnectionResult>;
+    detectCurrency(_credentials?: RevenueCredentials): Promise<string>;
+    getTransactions(range: DateRange, cursor?: string): Promise<TransactionPage>;
+    getBalance(): Promise<BalanceResult>;
+}