voidforge-build 23.9.1

package/dist/wizard/lib/financial/reconciliation-engine.js

@@ -0,0 +1,193 @@
+/**
+ * Three-Way Reconciliation Engine — pure logic for financial matching.
+ *
+ * Reconciles three data sources:
+ * 1. Provider transfers (stablecoin off-ramp records)
+ * 2. Bank transactions (settlement arrivals)
+ * 3. Platform spend (ad platform reported spend)
+ *
+ * No API calls, no file I/O — fully testable deterministic functions.
+ * Extends the existing reconciliation.ts pattern with stablecoin-specific matching.
+ *
+ * PRD Reference: §12.6 (ReconciliationRecord), §16 (Reporting and Reconciliation)
+ * Agents: Dockson (treasury), Heartbeat daemon
+ */
+// ── Variance Classification ──────────────────────────
+export function classifyVariance(varianceCents, referenceCents, thresholdBps) {
+    if (varianceCents === 0)
+        return 'MATCHED';
+    // Basis points: 1 bps = 0.01% = 1/10,000
+    if (referenceCents <= 0) {
+        // Can't compute percentage on zero reference — any variance is a mismatch
+        return varianceCents === 0 ? 'MATCHED' : 'MISMATCH';
+    }
+    const varianceBps = (varianceCents / referenceCents) * 10_000;
+    return varianceBps <= thresholdBps ? 'WITHIN_THRESHOLD' : 'MISMATCH';
+}
+// ── Transfer-to-Bank Matching ────────────────────────
+export function matchTransferToBank(transfer, transactions, thresholdBps = 50) {
+    // Only match completed transfers
+    if (transfer.status !== 'completed') {
+        return {
+            transferId: transfer.id,
+            bankTransactionId: null,
+            transferAmountCents: transfer.netAmountCents,
+            bankAmountCents: 0,
+            varianceCents: transfer.netAmountCents,
+            classification: 'MISMATCH',
+        };
+    }
+    // Find matching bank transaction by reference or amount proximity
+    let bestMatch = null;
+    let bestVariance = Infinity;
+    for (const txn of transactions) {
+        // Only match credits (incoming funds)
+        if (txn.type !== 'credit')
+            continue;
+        // Check reference match first (strongest signal)
+        const refMatch = transfer.reference &&
+            txn.reference.toLowerCase().includes(transfer.reference.toLowerCase());
+        const variance = Math.abs(transfer.netAmountCents - txn.amountCents);
+        // Reference match: accept with any variance within threshold
+        if (refMatch && variance < bestVariance) {
+            bestMatch = txn;
+            bestVariance = variance;
+        }
+        // Amount proximity match: must be within threshold
+        if (!refMatch && variance < bestVariance) {
+            const varianceBps = transfer.netAmountCents > 0
+                ? (variance / transfer.netAmountCents) * 10_000
+                : Infinity;
+            if (varianceBps <= thresholdBps * 2) {
+                // Use 2x threshold for amount-only matching (less confident)
+                bestMatch = txn;
+                bestVariance = variance;
+            }
+        }
+    }
+    if (!bestMatch) {
+        return {
+            transferId: transfer.id,
+            bankTransactionId: null,
+            transferAmountCents: transfer.netAmountCents,
+            bankAmountCents: 0,
+            varianceCents: transfer.netAmountCents,
+            classification: 'MISMATCH',
+        };
+    }
+    const varianceCents = Math.abs(transfer.netAmountCents - bestMatch.amountCents);
+    return {
+        transferId: transfer.id,
+        bankTransactionId: bestMatch.id,
+        transferAmountCents: transfer.netAmountCents,
+        bankAmountCents: bestMatch.amountCents,
+        varianceCents,
+        classification: classifyVariance(varianceCents, transfer.netAmountCents, thresholdBps),
+    };
+}
+// ── Bank-to-Platform-Spend Matching ──────────────────
+export function matchBankToSpend(bankTransaction, platformSpend, thresholdBps = 50) {
+    // Only match debits (outgoing payments to platforms)
+    if (bankTransaction.type !== 'debit')
+        return null;
+    // Find closest platform spend entry by amount
+    let bestMatch = null;
+    let bestVariance = Infinity;
+    for (const spend of platformSpend) {
+        const variance = Math.abs(bankTransaction.amountCents - spend.spendCents);
+        if (variance < bestVariance) {
+            bestMatch = spend;
+            bestVariance = variance;
+        }
+    }
+    if (!bestMatch)
+        return null;
+    const varianceCents = bestVariance;
+    const classification = classifyVariance(varianceCents, bankTransaction.amountCents, thresholdBps);
+    // Only return a match if it's within threshold or exact
+    if (classification === 'MISMATCH')
+        return null;
+    return {
+        bankTransactionId: bankTransaction.id,
+        platform: bestMatch.platform,
+        bankAmountCents: bankTransaction.amountCents,
+        spendAmountCents: bestMatch.spendCents,
+        varianceCents,
+        classification,
+    };
+}
+// ── Three-Way Reconciliation ─────────────────────────
+// The main reconciliation function that ties all three sources together.
+export function reconcileThreeWay(providerTransfers, bankTransactions, platformSpend, thresholdBps = 50) {
+    const transferMatches = [];
+    const spendMatches = [];
+    const matchedBankIds = new Set();
+    const matchedSpendIndices = new Set();
+    // Phase 1: Match provider transfers to bank transactions
+    const completedTransfers = providerTransfers.filter(t => t.status === 'completed');
+    const remainingBankTxns = [...bankTransactions];
+    for (const transfer of completedTransfers) {
+        const match = matchTransferToBank(transfer, remainingBankTxns, thresholdBps);
+        transferMatches.push(match);
+        if (match.bankTransactionId) {
+            matchedBankIds.add(match.bankTransactionId);
+            // Remove matched bank transaction from remaining pool
+            const idx = remainingBankTxns.findIndex(t => t.id === match.bankTransactionId);
+            if (idx >= 0)
+                remainingBankTxns.splice(idx, 1);
+        }
+    }
+    // Phase 2: Match remaining bank debits to platform spend
+    const remainingSpend = [...platformSpend];
+    for (const bankTxn of remainingBankTxns) {
+        if (matchedBankIds.has(bankTxn.id))
+            continue;
+        const match = matchBankToSpend(bankTxn, remainingSpend, thresholdBps);
+        if (match) {
+            spendMatches.push(match);
+            matchedBankIds.add(bankTxn.id);
+            // Remove matched spend from remaining pool
+            const spendIdx = remainingSpend.findIndex(s => s.spendCents === match.spendAmountCents && s.platform === match.platform);
+            if (spendIdx >= 0) {
+                matchedSpendIndices.add(platformSpend.indexOf(remainingSpend[spendIdx]));
+                remainingSpend.splice(spendIdx, 1);
+            }
+        }
+    }
+    // Phase 3: Identify unmatched items
+    const unmatchedTransfers = providerTransfers.filter(t => {
+        if (t.status !== 'completed')
+            return true;
+        const match = transferMatches.find(m => m.transferId === t.id);
+        return !match || match.bankTransactionId === null;
+    });
+    const unmatchedBankTransactions = bankTransactions.filter(t => !matchedBankIds.has(t.id));
+    const unmatchedSpend = platformSpend.filter((_, i) => !matchedSpendIndices.has(i));
+    // Phase 4: Calculate totals
+    const totalTransferredCents = completedTransfers.reduce((sum, t) => (sum + t.netAmountCents), 0);
+    const totalBankReceivedCents = bankTransactions
+        .filter(t => t.type === 'credit')
+        .reduce((sum, t) => (sum + t.amountCents), 0);
+    const totalPlatformSpendCents = platformSpend.reduce((sum, s) => (sum + s.spendCents), 0);
+    const overallVarianceCents = Math.abs(totalTransferredCents - totalBankReceivedCents);
+    const mismatchCount = transferMatches.filter(m => m.classification === 'MISMATCH').length;
+    const today = new Date().toISOString().split('T')[0];
+    return {
+        date: today,
+        transferMatches,
+        spendMatches,
+        unmatchedTransfers,
+        unmatchedBankTransactions,
+        unmatchedSpend,
+        totalTransferredCents,
+        totalBankReceivedCents,
+        totalPlatformSpendCents,
+        overallVarianceCents,
+        mismatchCount,
+    };
+}
+// ── Freeze Decision ──────────────────────────────────
+// Determines if operations should be frozen based on consecutive mismatches.
+export function shouldFreeze(mismatchCount, consecutiveCount, maxConsecutive) {
+    return consecutiveCount >= maxConsecutive || mismatchCount > maxConsecutive;
+}

package/dist/wizard/lib/financial/registry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Financial provider and billing adapter registries.
+ *
+ * Tracks which stablecoin providers, bank adapters, and ad billing adapters
+ * are implemented. New providers are added here first (implemented: false)
+ * then built out.
+ */
+interface ProviderEntry {
+    readonly name: string;
+    readonly implemented: boolean;
+}
+export declare const STABLECOIN_PROVIDERS: Record<string, ProviderEntry>;
+export declare const BANK_ADAPTERS: Record<string, ProviderEntry>;
+export declare const BILLING_ADAPTERS: Record<string, ProviderEntry>;
+export type StablecoinProviderId = keyof typeof STABLECOIN_PROVIDERS;
+export type BankAdapterId = keyof typeof BANK_ADAPTERS;
+export type BillingAdapterId = keyof typeof BILLING_ADAPTERS;
+export { CircleSetup, CircleAdapter } from './stablecoin/circle.js';
+export { MercuryBankAdapter } from './stablecoin/mercury.js';
+export { GoogleBillingSetup, GoogleBillingAdapter } from './billing/google-billing.js';
+export { MetaBillingSetup, MetaBillingAdapter } from './billing/meta-billing.js';
+export { TikTokBillingSetup, TikTokBillingAdapter } from './billing/tiktok-billing.js';

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

@@ -0,0 +1,26 @@
+/**
+ * Financial provider and billing adapter registries.
+ *
+ * Tracks which stablecoin providers, bank adapters, and ad billing adapters
+ * are implemented. New providers are added here first (implemented: false)
+ * then built out.
+ */
+export const STABLECOIN_PROVIDERS = {
+    sandbox: { name: 'Sandbox (Demo)', implemented: true },
+    circle: { name: 'Circle', implemented: true },
+    bridge: { name: 'Bridge', implemented: false },
+};
+export const BANK_ADAPTERS = {
+    mercury: { name: 'Mercury', implemented: true },
+};
+export const BILLING_ADAPTERS = {
+    google: { name: 'Google Ads Billing', implemented: true },
+    meta: { name: 'Meta Ads Billing', implemented: true },
+    tiktok: { name: 'TikTok Ads Billing', implemented: true },
+};
+// ── Re-exports for convenience ───────────────────────
+export { CircleSetup, CircleAdapter } from './stablecoin/circle.js';
+export { MercuryBankAdapter } from './stablecoin/mercury.js';
+export { GoogleBillingSetup, GoogleBillingAdapter } from './billing/google-billing.js';
+export { MetaBillingSetup, MetaBillingAdapter } from './billing/meta-billing.js';
+export { TikTokBillingSetup, TikTokBillingAdapter } from './billing/tiktok-billing.js';

package/dist/wizard/lib/financial/reporting.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 type { Cents } from '../patterns/funding-plan.js';
+import type { ReconciliationReport } from './reconciliation-engine.js';
+import type { CampaignSpendProjection, FundingPlanConfig } from './treasury-planner.js';
+interface DailyReportInput {
+    date: string;
+    revenueCents: Cents;
+    spendCents: Cents;
+    stablecoinBalanceCents: Cents;
+    pendingTransfersCents: Cents;
+    bankBalanceCents: Cents;
+    settledTodayCents: Cents;
+    reconciliation: ReconciliationReport | null;
+    activeCircuitBreakers: string[];
+    runwayDays: number;
+    fundingFrozen: boolean;
+    freezeReason: string | null;
+}
+export declare function generateDailyReport(input: DailyReportInput): string;
+interface TransferLedgerEntry {
+    id: string;
+    date: string;
+    direction: string;
+    amountCents: Cents;
+    feesCents: Cents;
+    netAmountCents: Cents;
+    status: string;
+    reference: string;
+}
+interface ReconciliationLedgerEntry {
+    id: string;
+    date: string;
+    platform: string;
+    spendCents: Cents;
+    bankSettledCents: Cents;
+    varianceCents: Cents;
+    result: string;
+}
+interface MonthlyLedger {
+    month: string;
+    generatedAt: string;
+    transfers: TransferLedgerEntry[];
+    reconciliations: ReconciliationLedgerEntry[];
+    summary: {
+        totalTransfersCents: Cents;
+        totalFeesCents: Cents;
+        totalNetTransferredCents: Cents;
+        totalSpendCents: Cents;
+        totalBankSettledCents: Cents;
+        totalVarianceCents: Cents;
+        transferCount: number;
+        reconciliationCount: number;
+        mismatchCount: number;
+    };
+}
+export declare function generateMonthlyLedger(month: string, transfers: TransferLedgerEntry[], reconciliations: ReconciliationLedgerEntry[]): MonthlyLedger;
+interface SimulationDay {
+    day: number;
+    date: string;
+    bankBalanceCents: Cents;
+    spendCents: Cents;
+    offrampTriggered: boolean;
+    offrampAmountCents: Cents;
+    policyBlocked: boolean;
+    freezeRisk: boolean;
+}
+interface SimulationResult {
+    config: {
+        startDate: string;
+        days: number;
+        startingBankBalanceCents: Cents;
+        bufferTargetCents: Cents;
+        maxDailyOfframpCents: Cents;
+    };
+    days: SimulationDay[];
+    summary: {
+        firstOfframpDay: number | null;
+        totalOfframpsCents: Cents;
+        offrampCount: number;
+        minimumBalanceCents: Cents;
+        minimumBalanceDay: number;
+        freezeRiskDays: number[];
+        finalBalanceCents: Cents;
+    };
+}
+export declare function simulateFunding(startDate: string, startingBankBalanceCents: Cents, config: FundingPlanConfig, campaigns: CampaignSpendProjection[], days: number, stablecoinAvailableCents: Cents, minimumBufferCents: Cents): SimulationResult;
+export type { DailyReportInput, TransferLedgerEntry, ReconciliationLedgerEntry, MonthlyLedger, SimulationDay, SimulationResult, };

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 {};