thevoidforge 21.0.0

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

@@ -0,0 +1,171 @@
+/**
+ * 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 { request as httpsRequest } from 'node:https';
+const MERCURY_HOST = 'api.mercury.com';
+// ── HTTP helper ──────────────────────────────────────
+async function mercuryGet(path, apiKey, params) {
+    const query = params ? '?' + new URLSearchParams(params).toString() : '';
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: MERCURY_HOST,
+            path: `/api/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('Mercury API timeout')); });
+        req.end();
+    });
+}
+// ── Mercury Bank Adapter ─────────────────────────────
+export class MercuryBankAdapter {
+    apiKey;
+    accountId;
+    constructor(apiKey, accountId) {
+        this.apiKey = apiKey;
+        this.accountId = accountId;
+    }
+    async connect(_credentials) {
+        try {
+            const { status, body } = await mercuryGet('/accounts', this.apiKey);
+            if (status === 200) {
+                const data = JSON.parse(body);
+                const accounts = data.accounts ?? [];
+                if (accounts.length === 0) {
+                    return { connected: false, error: 'No accounts found' };
+                }
+                const primary = accounts[0];
+                this.accountId = primary.id;
+                return {
+                    connected: true,
+                    accountId: primary.id,
+                    accountName: primary.name ?? 'Mercury Account',
+                    currency: 'USD',
+                };
+            }
+            // VG-R1-005: Wrap error-path JSON.parse
+            try {
+                const error = JSON.parse(body);
+                return { connected: false, error: error.message ?? error.error ?? `HTTP ${status}` };
+            }
+            catch {
+                return { connected: false, error: `HTTP ${status}` };
+            }
+        }
+        catch (err) {
+            return { connected: false, error: err instanceof Error ? err.message : 'Connection failed' };
+        }
+    }
+    async detectCurrency(_credentials) {
+        // Mercury is USD-only
+        return 'USD';
+    }
+    async getTransactions(range, cursor) {
+        if (!this.accountId) {
+            throw new Error('Mercury: must call connect() before getTransactions()');
+        }
+        const params = {
+            start: range.start,
+            end: range.end,
+            limit: '100',
+        };
+        if (cursor)
+            params.offset = cursor;
+        try {
+            const { status, body } = await mercuryGet(`/account/${this.accountId}/transactions`, this.apiKey, params);
+            if (status !== 200) {
+                // VG-R1-005: Wrap error-path JSON.parse
+                let errorMsg = `HTTP ${status}`;
+                try {
+                    const error = JSON.parse(body);
+                    errorMsg = error.message ?? errorMsg;
+                }
+                catch { /* non-JSON response */ }
+                throw new Error(errorMsg);
+            }
+            const data = JSON.parse(body);
+            const txns = data.transactions ?? [];
+            const transactions = txns
+                .filter(t => t.status === 'sent' || t.status === 'received' || t.status === 'pending')
+                .map(t => ({
+                externalId: t.id ?? '',
+                type: mapMercuryKind(t.kind, t.amount),
+                amount: Math.round((t.amount ?? 0) * 100),
+                currency: 'USD',
+                description: t.note ?? t.counterpartyName ?? 'Mercury transaction',
+                metadata: {},
+                createdAt: t.createdAt ?? new Date().toISOString(),
+            }));
+            const total = data.total ?? 0;
+            const offset = cursor ? parseInt(cursor, 10) : 0;
+            const hasMore = offset + txns.length < total;
+            const nextCursor = hasMore ? String(offset + txns.length) : undefined;
+            return {
+                transactions,
+                hasMore,
+                cursor: nextCursor,
+            };
+        }
+        catch (err) {
+            throw new Error(`Mercury getTransactions failed: ${err instanceof Error ? err.message : 'Unknown error'}`);
+        }
+    }
+    async getBalance() {
+        if (!this.accountId) {
+            throw new Error('Mercury: must call connect() before getBalance()');
+        }
+        try {
+            const { status, body } = await mercuryGet(`/account/${this.accountId}`, this.apiKey);
+            if (status !== 200) {
+                let errorMsg = `HTTP ${status}`;
+                try {
+                    const error = JSON.parse(body);
+                    errorMsg = error.message ?? errorMsg;
+                }
+                catch { /* non-JSON response */ }
+                throw new Error(errorMsg);
+            }
+            const data = JSON.parse(body);
+            const available = Math.round((data.availableBalance ?? data.currentBalance ?? 0) * 100);
+            const pending = Math.round(((data.currentBalance ?? 0) - (data.availableBalance ?? data.currentBalance ?? 0)) * 100);
+            return {
+                available: available,
+                pending: pending,
+                currency: 'USD',
+            };
+        }
+        catch (err) {
+            throw new Error(`Mercury getBalance failed: ${err instanceof Error ? err.message : 'Unknown error'}`);
+        }
+    }
+}
+// ── Helpers ──────────────────────────────────────────
+function mapMercuryKind(kind, amount) {
+    // Mercury transaction kinds: externalTransfer, internalTransfer, outgoingPayment, incomingPayment, etc.
+    // Map to revenue-source-adapter types based on direction (amount sign)
+    if (kind === 'incomingPayment' || (amount !== undefined && amount > 0))
+        return 'charge';
+    if (kind === 'outgoingPayment' || (amount !== undefined && amount < 0))
+        return 'refund';
+    return 'charge';
+}

package/dist/wizard/lib/financial/stablecoin/sandbox-stablecoin.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Sandbox Stablecoin Adapter — full implementation for development/demo.
+ *
+ * Returns realistic fake data matching the StablecoinSetup + StablecoinAdapter
+ * interfaces. Every method returns valid-shaped data. No throws.
+ * This IS a full implementation for a sandbox provider (No Stubs Doctrine).
+ *
+ * Simulates a USDC wallet with ~$50,000 starting balance, realistic off-ramp
+ * lifecycle (pending -> processing -> completed over 3 polls), and deterministic
+ * fee estimates.
+ */
+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 SandboxStablecoinSetup implements StablecoinSetup {
+    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 SandboxStablecoinAdapter implements StablecoinAdapter {
+    private balanceCents;
+    private transfers;
+    constructor(initialBalanceDollars?: number);
+    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/sandbox-stablecoin.js

@@ -0,0 +1,202 @@
+/**
+ * Sandbox Stablecoin Adapter — full implementation for development/demo.
+ *
+ * Returns realistic fake data matching the StablecoinSetup + StablecoinAdapter
+ * interfaces. Every method returns valid-shaped data. No throws.
+ * This IS a full implementation for a sandbox provider (No Stubs Doctrine).
+ *
+ * Simulates a USDC wallet with ~$50,000 starting balance, realistic off-ramp
+ * lifecycle (pending -> processing -> completed over 3 polls), and deterministic
+ * fee estimates.
+ */
+import { randomUUID } from 'node:crypto';
+import { toCents, computeTransferHash } from './base.js';
+// ── Setup Implementation ─────────────────────────────
+export class SandboxStablecoinSetup {
+    async authenticate(_credentials) {
+        return {
+            valid: true,
+            accountId: `sandbox_wallet_${randomUUID().slice(0, 8)}`,
+            permissions: ['read_balances', 'initiate_payouts', 'read_payouts'],
+        };
+    }
+    async verifySupportedAssets(_credentials) {
+        return [
+            {
+                asset: 'USDC',
+                network: 'ETH',
+                contractAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+                minRedemption: toCents(100),
+            },
+            {
+                asset: 'USDC',
+                network: 'SOL',
+                contractAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+                minRedemption: toCents(50),
+            },
+        ];
+    }
+    async verifyLinkedBank(_credentials) {
+        return {
+            linked: true,
+            bankId: 'sandbox_bank_001',
+            bankName: 'Sandbox Mercury Account',
+            accountLast4: '4242',
+        };
+    }
+    async getInitialBalances(_credentials) {
+        return [
+            {
+                provider: 'circle',
+                asset: 'USDC',
+                network: 'ETH',
+                balanceCents: toCents(50_000),
+                lastUpdated: new Date().toISOString(),
+            },
+        ];
+    }
+}
+// ── Runtime Adapter Implementation ───────────────────
+export class SandboxStablecoinAdapter {
+    balanceCents;
+    transfers = new Map();
+    constructor(initialBalanceDollars = 50_000) {
+        this.balanceCents = toCents(initialBalanceDollars);
+    }
+    async getBalances() {
+        const now = new Date().toISOString();
+        const stablecoin = [
+            {
+                provider: 'circle',
+                asset: 'USDC',
+                network: 'ETH',
+                balanceCents: this.balanceCents,
+                lastUpdated: now,
+            },
+        ];
+        return {
+            stablecoin,
+            fiat: [],
+            totalStablecoinCents: this.balanceCents,
+            totalFiatAvailableCents: 0,
+        };
+    }
+    async quoteRedemption(amountCents) {
+        // Sandbox fee: flat $10 per off-ramp
+        const feeCents = toCents(10);
+        return {
+            provider: 'circle',
+            sourceAsset: 'USDC',
+            sourceNetwork: 'ETH',
+            requestedCents: amountCents,
+            estimatedFeeCents: feeCents,
+            estimatedNetCents: (amountCents - feeCents),
+            estimatedSettlementMinutes: 60,
+            expiresAt: new Date(Date.now() + 10 * 60 * 1000).toISOString(),
+        };
+    }
+    async initiateOfframp(plan, previousHash) {
+        const feeCents = toCents(10);
+        const netCents = (plan.requiredCents - feeCents);
+        const now = new Date().toISOString();
+        const id = randomUUID();
+        const providerTransferId = `sandbox_xfer_${randomUUID().slice(0, 12)}`;
+        // Deduct from simulated balance
+        this.balanceCents = (this.balanceCents - plan.requiredCents);
+        const record = {
+            id,
+            fundingPlanId: plan.id,
+            providerTransferId,
+            provider: 'circle',
+            direction: 'crypto_to_fiat',
+            sourceAsset: 'USDC',
+            sourceNetwork: 'ETH',
+            amountCents: plan.requiredCents,
+            feesCents: feeCents,
+            netAmountCents: netCents,
+            destinationBankId: plan.destinationBankId,
+            status: 'pending',
+            initiatedAt: now,
+            idempotencyKey: plan.idempotencyKey,
+            previousHash,
+        };
+        const hash = computeTransferHash(record, previousHash);
+        const fullRecord = { ...record, hash };
+        this.transfers.set(id, { record: fullRecord, pollCount: 0 });
+        return fullRecord;
+    }
+    async getTransferStatus(transferId) {
+        const state = this.transfers.get(transferId);
+        if (!state) {
+            // Return failed status for unknown IDs — unknown transfers should not
+            // be reported as completed (could cause false settlement in reconciliation).
+            return {
+                transferId,
+                providerTransferId: 'unknown',
+                status: 'failed',
+                amountCents: 0,
+                feesCents: 0,
+                initiatedAt: new Date().toISOString(),
+                providerRawStatus: 'not_found',
+            };
+        }
+        // Simulate lifecycle: pending (poll 0) -> processing (poll 1) -> completed (poll 2+)
+        state.pollCount += 1;
+        let status;
+        let rawStatus;
+        let completedAt;
+        if (state.pollCount <= 1) {
+            status = 'pending';
+            rawStatus = 'pending';
+        }
+        else if (state.pollCount === 2) {
+            status = 'processing';
+            rawStatus = 'processing';
+        }
+        else {
+            status = 'completed';
+            rawStatus = 'complete';
+            completedAt = new Date().toISOString();
+            // Update stored record status
+            state.record = { ...state.record, status: 'completed', completedAt };
+        }
+        return {
+            transferId: state.record.id,
+            providerTransferId: state.record.providerTransferId,
+            status,
+            amountCents: state.record.amountCents,
+            feesCents: state.record.feesCents,
+            initiatedAt: state.record.initiatedAt,
+            completedAt,
+            estimatedCompletionAt: status !== 'completed'
+                ? new Date(Date.now() + 60 * 60 * 1000).toISOString()
+                : undefined,
+            providerRawStatus: rawStatus,
+        };
+    }
+    async cancelTransfer(transferId) {
+        const state = this.transfers.get(transferId);
+        if (!state) {
+            return { cancelled: false, reason: 'Transfer not found' };
+        }
+        if (state.record.status === 'completed') {
+            return { cancelled: false, reason: 'Transfer already completed' };
+        }
+        if (state.record.status === 'processing') {
+            return { cancelled: false, reason: 'Transfer is processing — cannot cancel' };
+        }
+        // Refund the balance and mark cancelled
+        this.balanceCents = (this.balanceCents + state.record.amountCents);
+        state.record = { ...state.record, status: 'cancelled' };
+        return { cancelled: true };
+    }
+    async listCompletedTransfers(_dateRange) {
+        const completed = [];
+        for (const state of this.transfers.values()) {
+            if (state.record.status === 'completed') {
+                completed.push(state.record);
+            }
+        }
+        return completed;
+    }
+}

package/dist/wizard/lib/financial/treasury-planner.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Treasury Planner — pure logic module for runway forecasting and plan generation.
+ *
+ * No API calls, no file I/O — fully testable deterministic functions.
+ * All monetary values use branded integer cents (Cents type).
+ *
+ * PRD Reference: §12.4 (FundingPlan), §12.5 (TransferRecord), §15 (Rules Engine)
+ * Agents: Dockson (treasury), Heartbeat daemon
+ */
+import type { Cents, FundingPlan, OperatingBankAccount, StablecoinFundingSource, PendingObligation } from '../patterns/funding-plan.js';
+interface CampaignSpendProjection {
+    campaignId: string;
+    platform: 'google' | 'meta';
+    dailyBudgetCents: Cents;
+    status: 'active' | 'paused';
+}
+interface FundingPlanConfig {
+    /** Minimum off-ramp amount (provider-enforced) */
+    minimumOfframpCents: Cents;
+    /** Target buffer above minimum — the "comfort zone" */
+    bufferTargetCents: Cents;
+    /** Maximum single off-ramp amount per day */
+    maxDailyOfframpCents: Cents;
+    /** Days of runway to maintain as target */
+    targetRunwayDays: number;
+}
+interface OfframpDecision {
+    shouldOfframp: boolean;
+    reason: string;
+    amountCents: Cents;
+}
+interface ObligationInput {
+    id: string;
+    platform: 'google' | 'meta';
+    type: 'invoice' | 'debit' | 'buffer';
+    amountCents: Cents;
+    dueDate: string;
+    overdue: boolean;
+}
+export declare function calculateRunway(bankBalanceCents: Cents, dailySpendRateCents: Cents): number;
+export declare function forecastSpend(campaigns: CampaignSpendProjection[], days: number): Cents;
+export declare function shouldTriggerOfframp(bankBalanceCents: Cents, bufferThresholdCents: Cents, pendingSpendCents: Cents): OfframpDecision;
+export declare function calculateRequiredOfframp(bankBalanceCents: Cents, bufferTargetCents: Cents, pendingObligationsCents: Cents, feeEstimateCents: Cents): Cents;
+export declare function prioritizeAllObligations(invoices: ObligationInput[], debits: ObligationInput[], bufferNeeds: ObligationInput[]): PendingObligation[];
+export declare function generateFundingPlan(source: StablecoinFundingSource, bank: OperatingBankAccount, obligations: ObligationInput[], config: FundingPlanConfig, previousHash: string): FundingPlan | null;
+export declare function calculateDailySpendRate(campaigns: CampaignSpendProjection[]): Cents;
+export declare function forecastRunway(bankBalanceCents: Cents, campaigns: CampaignSpendProjection[], pendingObligationsCents: Cents): {
+    runwayDays: number;
+    dailySpendCents: Cents;
+    effectiveBalanceCents: Cents;
+};
+export type { CampaignSpendProjection, FundingPlanConfig, OfframpDecision, ObligationInput, };

package/dist/wizard/lib/financial/treasury-planner.js

@@ -0,0 +1,128 @@
+/**
+ * Treasury Planner — pure logic module for runway forecasting and plan generation.
+ *
+ * No API calls, no file I/O — fully testable deterministic functions.
+ * All monetary values use branded integer cents (Cents type).
+ *
+ * PRD Reference: §12.4 (FundingPlan), §12.5 (TransferRecord), §15 (Rules Engine)
+ * Agents: Dockson (treasury), Heartbeat daemon
+ */
+import { toCents, createFundingPlan, prioritizeObligations, } from '../patterns/funding-plan.js';
+// ── Runway Calculation ───────────────────────────────
+// Returns the number of days the current bank balance can sustain spend.
+export function calculateRunway(bankBalanceCents, dailySpendRateCents) {
+    if (dailySpendRateCents <= 0)
+        return Infinity;
+    return Math.floor(bankBalanceCents / dailySpendRateCents);
+}
+// ── Spend Forecast ───────────────────────────────────
+// Projects total spend over N days based on active campaign budgets.
+export function forecastSpend(campaigns, days) {
+    if (days <= 0)
+        return 0;
+    const dailyTotal = campaigns
+        .filter(c => c.status === 'active')
+        .reduce((sum, c) => sum + c.dailyBudgetCents, 0);
+    return Math.round(dailyTotal * days);
+}
+// ── Off-ramp Trigger Decision ────────────────────────
+// Determines whether an off-ramp should be triggered and why.
+export function shouldTriggerOfframp(bankBalanceCents, bufferThresholdCents, pendingSpendCents) {
+    const effectiveBalance = (bankBalanceCents - pendingSpendCents);
+    if (effectiveBalance < bufferThresholdCents) {
+        const deficit = (bufferThresholdCents - effectiveBalance);
+        return {
+            shouldOfframp: true,
+            reason: `Effective balance $${(effectiveBalance / 100).toFixed(2)} below buffer threshold $${(bufferThresholdCents / 100).toFixed(2)} — deficit $${(deficit / 100).toFixed(2)}`,
+            amountCents: deficit,
+        };
+    }
+    return {
+        shouldOfframp: false,
+        reason: `Effective balance $${(effectiveBalance / 100).toFixed(2)} above buffer threshold $${(bufferThresholdCents / 100).toFixed(2)}`,
+        amountCents: 0,
+    };
+}
+// ── Required Off-ramp Amount ─────────────────────────
+// Calculates the exact off-ramp amount needed, clamped to provider constraints.
+export function calculateRequiredOfframp(bankBalanceCents, bufferTargetCents, pendingObligationsCents, feeEstimateCents) {
+    // How much fiat we need: buffer + obligations + fees - current balance
+    const required = (bufferTargetCents + pendingObligationsCents + feeEstimateCents - bankBalanceCents);
+    if (required <= 0)
+        return 0;
+    return required;
+}
+// ── Obligation Prioritization ────────────────────────
+// Sorts obligations by urgency: overdue first, then by due date.
+export function prioritizeAllObligations(invoices, debits, bufferNeeds) {
+    const all = [...invoices, ...debits, ...bufferNeeds].map(o => ({
+        id: o.id,
+        platform: o.platform,
+        amountCents: o.amountCents,
+        dueDate: o.dueDate,
+        overdue: o.overdue,
+    }));
+    return prioritizeObligations(all);
+}
+// ── Funding Plan Generation ──────────────────────────
+// Creates a FundingPlan based on current treasury state and obligations.
+export function generateFundingPlan(source, bank, obligations, config, previousHash) {
+    // Sum all pending obligation amounts
+    const totalObligationsCents = obligations.reduce((sum, o) => sum + o.amountCents, 0);
+    // Calculate how much additional fiat we need
+    const requiredCents = calculateRequiredOfframp(bank.availableBalanceCents, config.bufferTargetCents, totalObligationsCents, toCents(10));
+    // No funding needed
+    if (requiredCents <= 0)
+        return null;
+    // Clamp to maximum daily off-ramp
+    const clampedCents = Math.min(requiredCents, config.maxDailyOfframpCents);
+    // Enforce minimum off-ramp amount
+    if (clampedCents < config.minimumOfframpCents) {
+        // If the required amount is below provider minimum but > 0, round up to minimum
+        const finalCents = config.minimumOfframpCents;
+        return createFundingPlan(determineFundingReason(obligations, bank), source.id, bank.id, determinePlatformTarget(obligations), finalCents, previousHash);
+    }
+    return createFundingPlan(determineFundingReason(obligations, bank), source.id, bank.id, determinePlatformTarget(obligations), clampedCents, previousHash);
+}
+// ── Daily Spend Rate ─────────────────────────────────
+// Calculates the average daily spend rate from active campaigns.
+export function calculateDailySpendRate(campaigns) {
+    return campaigns
+        .filter(c => c.status === 'active')
+        .reduce((sum, c) => (sum + c.dailyBudgetCents), 0);
+}
+// ── Runway Forecast ──────────────────────────────────
+// Combines balance, spend rate, and pending obligations into a runway projection.
+export function forecastRunway(bankBalanceCents, campaigns, pendingObligationsCents) {
+    const dailySpendCents = calculateDailySpendRate(campaigns);
+    const effectiveBalanceCents = (bankBalanceCents - pendingObligationsCents);
+    const runwayDays = calculateRunway(Math.max(effectiveBalanceCents, 0), dailySpendCents);
+    return { runwayDays, dailySpendCents, effectiveBalanceCents };
+}
+// ── Private Helpers ──────────────────────────────────
+function determineFundingReason(obligations, bank) {
+    // Check for overdue invoices first
+    const hasOverdue = obligations.some(o => o.overdue);
+    if (hasOverdue)
+        return 'INVOICE_DUE';
+    // Check for upcoming invoices within 7 days
+    const sevenDaysOut = Date.now() + 7 * 24 * 60 * 60 * 1000;
+    const hasUpcoming = obligations.some(o => o.type === 'invoice' && new Date(o.dueDate).getTime() <= sevenDaysOut);
+    if (hasUpcoming)
+        return 'INVOICE_DUE';
+    // Check if bank is below minimum buffer
+    if (bank.availableBalanceCents < bank.minimumBufferCents)
+        return 'LOW_BUFFER';
+    // Default: runway shortfall
+    return 'RUNWAY_SHORTFALL';
+}
+function determinePlatformTarget(obligations) {
+    // If all obligations are for one platform, target that platform
+    const platforms = new Set(obligations.map(o => o.platform));
+    if (platforms.size === 1) {
+        const platform = [...platforms][0];
+        return platform;
+    }
+    // Mixed or no obligations: shared buffer
+    return 'shared_buffer';
+}

package/dist/wizard/lib/financial-core.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Financial core — re-exports from the financial-transaction pattern for wizard runtime use.
+ * ARCH-R2-012: Production code should not import from docs/patterns/ directly.
+ */
+export { atomicWrite, appendToLog, idempotentAppend, toCents, toDollars, formatCurrency, formatRoas, formatPercentage, SPEND_LOG, REVENUE_LOG, TREASURY_DIR } from './patterns/financial-transaction.js';
+export type { Cents, ReconciliationReport, Transaction, Budget, GrowthCampaign, RevenueEvent } from './patterns/financial-transaction.js';

package/dist/wizard/lib/financial-core.js

@@ -0,0 +1,5 @@
+/**
+ * Financial core — re-exports from the financial-transaction pattern for wizard runtime use.
+ * ARCH-R2-012: Production code should not import from docs/patterns/ directly.
+ */
+export { atomicWrite, appendToLog, idempotentAppend, toCents, toDollars, formatCurrency, formatRoas, formatPercentage, SPEND_LOG, REVENUE_LOG, TREASURY_DIR } from './patterns/financial-transaction.js';

package/dist/wizard/lib/financial-vault.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Financial Vault — Separate encrypted storage for ad platform and bank credentials.
+ *
+ * Key differences from the infrastructure vault (vault.ts):
+ * - Stored at ~/.voidforge/treasury/vault.enc (not ~/.voidforge/vault.enc)
+ * - Uses scrypt key derivation (memory-hard, unlike PBKDF2 in the infra vault)
+ *   Note: PRD specifies Argon2id but Node.js has no built-in Argon2id.
+ *   scrypt is the closest built-in memory-hard KDF. Zero-dependency constraint wins.
+ * - Separate password from the infrastructure vault
+ * - TOTP 2FA required for write operations (see totp.ts)
+ *
+ * PRD Reference: §9.11 (Financial Security), ADR-4 (TOTP storage), §9.18 (macOS fsync)
+ *
+ * Threat model: compromise of the infrastructure vault should NOT automatically
+ * compromise the financial vault. Different password, different file, different KDF.
+ */
+/** Store a financial credential */
+export declare function financialVaultSet(password: string, key: string, value: string): Promise<void>;
+/** Retrieve a financial credential */
+export declare function financialVaultGet(password: string, key: string): Promise<string | null>;
+/** Delete a financial credential */
+export declare function financialVaultDelete(password: string, key: string): Promise<void>;
+/** Check if the financial vault exists */
+export declare function financialVaultExists(): boolean;
+/** Verify password can decrypt the vault */
+export declare function financialVaultUnlock(password: string): Promise<boolean>;
+/** List stored keys (requires password) */
+export declare function financialVaultKeys(password: string): Promise<string[]>;
+/** Zero the in-memory cache — call on SIGTERM, vault timeout, or manual lock */
+export declare function financialVaultLock(): void;
+/** Return the vault file path */
+export declare function financialVaultPath(): string;
+/** Return the treasury directory path */
+export declare function treasuryDir(): string;