voidforge-build 23.9.1

package/dist/wizard/lib/financial/funding-policy.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Funding Policy — the 7 deterministic rules from PRD Section 15.
+ *
+ * Pure logic — no API calls, no file I/O, fully testable.
+ * Each rule evaluates independently and returns an allow/deny/freeze decision.
+ * All rules are evaluated on every cycle; the most restrictive decision wins.
+ *
+ * PRD Reference: §15 (Rules Engine V1)
+ * Agents: Dockson (treasury), Heartbeat daemon
+ */
+import type { Cents, CapabilityState } from '../patterns/funding-plan.js';
+interface TreasuryState {
+    /** Current bank available balance in cents */
+    bankBalanceCents: Cents;
+    /** Minimum operating buffer floor in cents */
+    minimumBufferCents: Cents;
+    /** Reserved balance (earmarked for pending settlements) */
+    reservedCents: Cents;
+    /** Proposed off-ramp amount in cents (0 if no off-ramp proposed) */
+    proposedOfframpCents: Cents;
+    /** Maximum allowed daily treasury movement in cents */
+    maxDailyMovementCents: Cents;
+    /** Whether a Google invoice is due within the threshold window */
+    googleInvoiceDueSoon: boolean;
+    /** Google invoice amount in cents (0 if none) */
+    googleInvoiceCents: Cents;
+    /** Whether Meta uses direct debit billing */
+    metaUsesDirectDebit: boolean;
+    /** Meta forecasted 7-day spend in cents */
+    metaForecast7DayCents: Cents;
+    /** Current debit protection buffer in cents */
+    debitProtectionBufferCents: Cents;
+    /** Whether a reconciliation discrepancy currently exists */
+    discrepancyExists: boolean;
+    /** Whether a platform budget raise is being proposed */
+    proposingBudgetRaise: boolean;
+    /** Capability state of the platform being funded */
+    platformCapability: CapabilityState;
+    /** Whether autonomous funding is being claimed */
+    claimingAutonomousFunding: boolean;
+}
+interface PolicyDecision {
+    rule: number;
+    action: 'allow' | 'deny' | 'freeze';
+    reason: string;
+}
+interface PolicyThresholds {
+    /** Days before Google invoice due date to start prioritizing */
+    googleInvoiceWindowDays: number;
+    /** Multiplier for debit protection buffer over forecast */
+    debitProtectionMultiplier: number;
+}
+declare const DEFAULT_THRESHOLDS: PolicyThresholds;
+export declare function evaluatePolicy(state: TreasuryState, _thresholds?: PolicyThresholds): PolicyDecision[];
+export declare function aggregateDecisions(decisions: PolicyDecision[]): {
+    action: 'allow' | 'deny' | 'freeze';
+    blockingRules: PolicyDecision[];
+};
+export type { TreasuryState, PolicyDecision, PolicyThresholds };
+export { DEFAULT_THRESHOLDS };

package/dist/wizard/lib/financial/funding-policy.js

@@ -0,0 +1,179 @@
+/**
+ * Funding Policy — the 7 deterministic rules from PRD Section 15.
+ *
+ * Pure logic — no API calls, no file I/O, fully testable.
+ * Each rule evaluates independently and returns an allow/deny/freeze decision.
+ * All rules are evaluated on every cycle; the most restrictive decision wins.
+ *
+ * PRD Reference: §15 (Rules Engine V1)
+ * Agents: Dockson (treasury), Heartbeat daemon
+ */
+const DEFAULT_THRESHOLDS = {
+    googleInvoiceWindowDays: 7,
+    debitProtectionMultiplier: 1.0,
+};
+// ── Rule Evaluators ──────────────────────────────────
+function evaluateRule1(state) {
+    // Rule 1: Maintain minimum operating buffer
+    const balanceAfterReserve = (state.bankBalanceCents - state.reservedCents);
+    if (balanceAfterReserve < state.minimumBufferCents) {
+        return {
+            rule: 1,
+            action: 'deny',
+            reason: `Balance after reserves ($${(balanceAfterReserve / 100).toFixed(2)}) below minimum buffer ($${(state.minimumBufferCents / 100).toFixed(2)}) — deny non-essential spend`,
+        };
+    }
+    return {
+        rule: 1,
+        action: 'allow',
+        reason: `Balance after reserves ($${(balanceAfterReserve / 100).toFixed(2)}) above minimum buffer ($${(state.minimumBufferCents / 100).toFixed(2)})`,
+    };
+}
+function evaluateRule2(state) {
+    // Rule 2: Never off-ramp more than max daily treasury movement
+    if (state.proposedOfframpCents > state.maxDailyMovementCents) {
+        return {
+            rule: 2,
+            action: 'deny',
+            reason: `Proposed off-ramp ($${(state.proposedOfframpCents / 100).toFixed(2)}) exceeds max daily movement ($${(state.maxDailyMovementCents / 100).toFixed(2)})`,
+        };
+    }
+    return {
+        rule: 2,
+        action: 'allow',
+        reason: `Proposed off-ramp ($${(state.proposedOfframpCents / 100).toFixed(2)}) within max daily movement ($${(state.maxDailyMovementCents / 100).toFixed(2)})`,
+    };
+}
+function evaluateRule3(state) {
+    // Rule 3: Never raise platform budget if bank balance after reserve falls below floor
+    if (!state.proposingBudgetRaise) {
+        return {
+            rule: 3,
+            action: 'allow',
+            reason: 'No budget raise proposed',
+        };
+    }
+    const balanceAfterReserve = (state.bankBalanceCents - state.reservedCents);
+    if (balanceAfterReserve < state.minimumBufferCents) {
+        return {
+            rule: 3,
+            action: 'deny',
+            reason: `Cannot raise platform budget — balance after reserve ($${(balanceAfterReserve / 100).toFixed(2)}) below floor ($${(state.minimumBufferCents / 100).toFixed(2)})`,
+        };
+    }
+    return {
+        rule: 3,
+        action: 'allow',
+        reason: `Budget raise permitted — balance after reserve ($${(balanceAfterReserve / 100).toFixed(2)}) above floor ($${(state.minimumBufferCents / 100).toFixed(2)})`,
+    };
+}
+function evaluateRule4(state) {
+    // Rule 4: If Google invoice due within threshold, prioritize invoice coverage
+    if (!state.googleInvoiceDueSoon) {
+        return {
+            rule: 4,
+            action: 'allow',
+            reason: 'No Google invoice due soon',
+        };
+    }
+    const availableForInvoice = (state.bankBalanceCents - state.reservedCents - state.minimumBufferCents);
+    if (availableForInvoice < state.googleInvoiceCents) {
+        return {
+            rule: 4,
+            action: 'deny',
+            reason: `Google invoice ($${(state.googleInvoiceCents / 100).toFixed(2)}) due soon but only $${(availableForInvoice / 100).toFixed(2)} available after reserves and buffer — prioritize invoice coverage over new expansion`,
+        };
+    }
+    return {
+        rule: 4,
+        action: 'allow',
+        reason: `Google invoice ($${(state.googleInvoiceCents / 100).toFixed(2)}) due soon — sufficient funds available ($${(availableForInvoice / 100).toFixed(2)})`,
+    };
+}
+function evaluateRule5(state) {
+    // Rule 5: If Meta uses direct debit, maintain debit protection buffer above 7-day forecast
+    if (!state.metaUsesDirectDebit) {
+        return {
+            rule: 5,
+            action: 'allow',
+            reason: 'Meta does not use direct debit',
+        };
+    }
+    if (state.debitProtectionBufferCents < state.metaForecast7DayCents) {
+        return {
+            rule: 5,
+            action: 'deny',
+            reason: `Debit protection buffer ($${(state.debitProtectionBufferCents / 100).toFixed(2)}) below Meta 7-day forecast ($${(state.metaForecast7DayCents / 100).toFixed(2)}) — maintain buffer before other operations`,
+        };
+    }
+    return {
+        rule: 5,
+        action: 'allow',
+        reason: `Debit protection buffer ($${(state.debitProtectionBufferCents / 100).toFixed(2)}) above Meta 7-day forecast ($${(state.metaForecast7DayCents / 100).toFixed(2)})`,
+    };
+}
+function evaluateRule6(state) {
+    // Rule 6: If discrepancy exists, freeze spend increases but allow monitoring
+    if (!state.discrepancyExists) {
+        return {
+            rule: 6,
+            action: 'allow',
+            reason: 'No reconciliation discrepancy detected',
+        };
+    }
+    return {
+        rule: 6,
+        action: 'freeze',
+        reason: 'Reconciliation discrepancy detected — freeze spend increases, allow read-only monitoring',
+    };
+}
+function evaluateRule7(state) {
+    // Rule 7: If platform capability is MONITORED_ONLY, never claim autonomous funding
+    if (state.platformCapability !== 'MONITORED_ONLY') {
+        return {
+            rule: 7,
+            action: 'allow',
+            reason: `Platform capability is ${state.platformCapability} — autonomous funding rules apply normally`,
+        };
+    }
+    if (state.claimingAutonomousFunding) {
+        return {
+            rule: 7,
+            action: 'deny',
+            reason: 'Platform capability is MONITORED_ONLY — cannot claim autonomous funding support',
+        };
+    }
+    return {
+        rule: 7,
+        action: 'allow',
+        reason: 'Platform is MONITORED_ONLY but no autonomous funding claimed — monitoring allowed',
+    };
+}
+// ── Main Policy Evaluator ────────────────────────────
+// Evaluates all 7 rules and returns all decisions.
+// The caller should enforce the most restrictive: freeze > deny > allow.
+export function evaluatePolicy(state, _thresholds = DEFAULT_THRESHOLDS) {
+    return [
+        evaluateRule1(state),
+        evaluateRule2(state),
+        evaluateRule3(state),
+        evaluateRule4(state),
+        evaluateRule5(state),
+        evaluateRule6(state),
+        evaluateRule7(state),
+    ];
+}
+// ── Decision Aggregator ──────────────────────────────
+// Reduces a list of decisions to a single most-restrictive action.
+export function aggregateDecisions(decisions) {
+    const freezeRules = decisions.filter(d => d.action === 'freeze');
+    if (freezeRules.length > 0) {
+        return { action: 'freeze', blockingRules: freezeRules };
+    }
+    const denyRules = decisions.filter(d => d.action === 'deny');
+    if (denyRules.length > 0) {
+        return { action: 'deny', blockingRules: denyRules };
+    }
+    return { action: 'allow', blockingRules: [] };
+}
+export { DEFAULT_THRESHOLDS };

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

@@ -0,0 +1,47 @@
+/**
+ * Platform-Specific Funding Planner — pure logic for Google invoice settlement,
+ * Meta debit protection, and multi-project portfolio rebalancing.
+ *
+ * No API calls, no file I/O — fully testable deterministic functions.
+ * All monetary values use branded integer cents (Cents type).
+ *
+ * PRD Reference: §12.3 (Platform Billing), §15 (Rules Engine)
+ * Agents: Dockson (treasury), Heartbeat daemon
+ */
+import type { Cents } from '../patterns/funding-plan.js';
+interface GoogleInvoice {
+    invoiceId: string;
+    amountCents: Cents;
+    dueDate: string;
+    status: 'pending' | 'overdue' | 'paid';
+}
+interface SettlementPlan {
+    invoiceId: string;
+    amountCents: Cents;
+    dueDate: string;
+    wireReference: string;
+    priority: number;
+    remainingBufferAfterCents: Cents;
+}
+interface ProjectTreasury {
+    projectId: string;
+    projectName: string;
+    bankBalanceCents: Cents;
+    minimumBufferCents: Cents;
+    dailySpendRateCents: Cents;
+    runwayDays: number;
+}
+interface RebalanceRecommendation {
+    fromProjectId: string;
+    toProjectId: string;
+    amountCents: Cents;
+    reason: string;
+}
+interface ExpectedDebit {
+    date: string;
+    amountCents: Cents;
+}
+export declare function planGoogleInvoiceSettlement(invoices: GoogleInvoice[], bankBalanceCents: Cents, bufferTargetCents: Cents): SettlementPlan[];
+export declare function planMetaDebitProtection(expectedDebits: ExpectedDebit[], bankBalanceCents: Cents, bufferTargetCents: Cents): Cents;
+export declare function generatePortfolioRebalancing(projects: ProjectTreasury[]): RebalanceRecommendation[];
+export type { GoogleInvoice, SettlementPlan, ExpectedDebit, ProjectTreasury, RebalanceRecommendation, };

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

@@ -0,0 +1,134 @@
+/**
+ * Platform-Specific Funding Planner — pure logic for Google invoice settlement,
+ * Meta debit protection, and multi-project portfolio rebalancing.
+ *
+ * No API calls, no file I/O — fully testable deterministic functions.
+ * All monetary values use branded integer cents (Cents type).
+ *
+ * PRD Reference: §12.3 (Platform Billing), §15 (Rules Engine)
+ * Agents: Dockson (treasury), Heartbeat daemon
+ */
+// ── Google Invoice Settlement Planner ────────────────
+// Prioritize by due date (nearest first). Reserve buffer after settlement.
+// Generate wire instructions for each invoice.
+export function planGoogleInvoiceSettlement(invoices, bankBalanceCents, bufferTargetCents) {
+    if (invoices.length === 0)
+        return [];
+    // Filter to actionable invoices (pending or overdue, not already paid)
+    const actionable = invoices.filter(inv => inv.status !== 'paid');
+    // Sort: overdue first, then by due date ascending
+    const sorted = [...actionable].sort((a, b) => {
+        if (a.status === 'overdue' && b.status !== 'overdue')
+            return -1;
+        if (a.status !== 'overdue' && b.status === 'overdue')
+            return 1;
+        return new Date(a.dueDate).getTime() - new Date(b.dueDate).getTime();
+    });
+    const plans = [];
+    let availableBalance = bankBalanceCents;
+    for (let i = 0; i < sorted.length; i++) {
+        const invoice = sorted[i];
+        const invoiceAmount = invoice.amountCents;
+        // Reserve buffer: only settle if we can still maintain buffer afterward
+        const balanceAfterSettlement = availableBalance - invoiceAmount;
+        if (balanceAfterSettlement < bufferTargetCents) {
+            // Cannot settle this invoice without breaching buffer
+            // Still include it in the plan but mark the buffer breach
+            if (availableBalance > bufferTargetCents) {
+                // Partial settlement up to buffer is not supported — skip
+                continue;
+            }
+            // Balance already below buffer — cannot settle any more
+            break;
+        }
+        const wireReference = `GOOG-INV-${invoice.invoiceId}-${Date.now().toString(36).toUpperCase()}`;
+        plans.push({
+            invoiceId: invoice.invoiceId,
+            amountCents: invoice.amountCents,
+            dueDate: invoice.dueDate,
+            wireReference,
+            priority: i + 1,
+            remainingBufferAfterCents: (balanceAfterSettlement),
+        });
+        availableBalance = balanceAfterSettlement;
+    }
+    return plans;
+}
+// ── Meta Debit Protection Planner ────────────────────
+// Forecast 7-day debit total and ensure bank balance covers debits + buffer.
+export function planMetaDebitProtection(expectedDebits, bankBalanceCents, bufferTargetCents) {
+    if (expectedDebits.length === 0)
+        return 0;
+    // Sum expected debits over the 7-day window
+    const now = Date.now();
+    const sevenDaysMs = 7 * 24 * 60 * 60 * 1000;
+    const cutoff = now + sevenDaysMs;
+    const totalExpectedDebits = expectedDebits
+        .filter(d => new Date(d.date).getTime() <= cutoff)
+        .reduce((sum, d) => sum + d.amountCents, 0);
+    // Required buffer: total debits + buffer target
+    const requiredBalance = totalExpectedDebits + bufferTargetCents;
+    const deficit = requiredBalance - bankBalanceCents;
+    // If balance already covers debits + buffer, no additional buffer needed
+    if (deficit <= 0)
+        return 0;
+    return deficit;
+}
+// ── Portfolio Rebalancing ────────────────────────────
+// For multi-project operators: suggest moving operating float from
+// overfunded to underfunded projects.
+export function generatePortfolioRebalancing(projects) {
+    if (projects.length < 2)
+        return [];
+    const recommendations = [];
+    // Calculate "excess" for each project: balance above (buffer + 30 days of spend)
+    const TARGET_RUNWAY_DAYS = 30;
+    const analyzed = projects.map(p => {
+        const targetBalance = p.minimumBufferCents +
+            p.dailySpendRateCents * TARGET_RUNWAY_DAYS;
+        const excess = p.bankBalanceCents - targetBalance;
+        return { project: p, targetBalanceCents: targetBalance, excessCents: excess };
+    });
+    // Split into overfunded and underfunded
+    const overfunded = analyzed
+        .filter(a => a.excessCents > 0)
+        .sort((a, b) => b.excessCents - a.excessCents); // most excess first
+    const underfunded = analyzed
+        .filter(a => a.excessCents < 0)
+        .sort((a, b) => a.excessCents - b.excessCents); // most deficit first
+    // Match overfunded to underfunded greedily
+    let overIdx = 0;
+    let underIdx = 0;
+    const remainingExcess = overfunded.map(o => o.excessCents);
+    const remainingDeficit = underfunded.map(u => Math.abs(u.excessCents));
+    while (overIdx < overfunded.length && underIdx < underfunded.length) {
+        const available = remainingExcess[overIdx];
+        const needed = remainingDeficit[underIdx];
+        if (available <= 0) {
+            overIdx++;
+            continue;
+        }
+        if (needed <= 0) {
+            underIdx++;
+            continue;
+        }
+        const transferAmount = Math.min(available, needed);
+        const fromProject = overfunded[overIdx].project;
+        const toProject = underfunded[underIdx].project;
+        recommendations.push({
+            fromProjectId: fromProject.projectId,
+            toProjectId: toProject.projectId,
+            amountCents: Math.round(transferAmount),
+            reason: `${fromProject.projectName} has ${overfunded[overIdx].project.runwayDays}d runway ` +
+                `(${TARGET_RUNWAY_DAYS}d target) — transfer to ${toProject.projectName} ` +
+                `which has ${toProject.runwayDays}d runway`,
+        });
+        remainingExcess[overIdx] -= transferAmount;
+        remainingDeficit[underIdx] -= transferAmount;
+        if (remainingExcess[overIdx] <= 0)
+            overIdx++;
+        if (remainingDeficit[underIdx] <= 0)
+            underIdx++;
+    }
+    return recommendations;
+}

package/dist/wizard/lib/financial/reconciliation-engine.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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
+ */
+type Cents = number & {
+    readonly __brand: 'Cents';
+};
+interface ProviderTransfer {
+    id: string;
+    providerTransferId: string;
+    amountCents: Cents;
+    feesCents: Cents;
+    netAmountCents: Cents;
+    status: 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
+    initiatedAt: string;
+    completedAt?: string;
+    reference?: string;
+}
+interface BankTransaction {
+    id: string;
+    amountCents: Cents;
+    date: string;
+    reference: string;
+    counterparty: string;
+    type: 'credit' | 'debit';
+}
+interface PlatformSpendEntry {
+    platform: 'google' | 'meta';
+    date: string;
+    spendCents: Cents;
+    invoiceId?: string;
+}
+type VarianceClassification = 'MATCHED' | 'WITHIN_THRESHOLD' | 'MISMATCH';
+interface TransferBankMatch {
+    transferId: string;
+    bankTransactionId: string | null;
+    transferAmountCents: Cents;
+    bankAmountCents: Cents;
+    varianceCents: Cents;
+    classification: VarianceClassification;
+}
+interface BankSpendMatch {
+    bankTransactionId: string;
+    platform: 'google' | 'meta';
+    bankAmountCents: Cents;
+    spendAmountCents: Cents;
+    varianceCents: Cents;
+    classification: VarianceClassification;
+}
+interface ReconciliationReport {
+    date: string;
+    transferMatches: TransferBankMatch[];
+    spendMatches: BankSpendMatch[];
+    unmatchedTransfers: ProviderTransfer[];
+    unmatchedBankTransactions: BankTransaction[];
+    unmatchedSpend: PlatformSpendEntry[];
+    totalTransferredCents: Cents;
+    totalBankReceivedCents: Cents;
+    totalPlatformSpendCents: Cents;
+    overallVarianceCents: Cents;
+    mismatchCount: number;
+}
+export declare function classifyVariance(varianceCents: Cents, referenceCents: Cents, thresholdBps: number): VarianceClassification;
+export declare function matchTransferToBank(transfer: ProviderTransfer, transactions: BankTransaction[], thresholdBps?: number): TransferBankMatch;
+export declare function matchBankToSpend(bankTransaction: BankTransaction, platformSpend: PlatformSpendEntry[], thresholdBps?: number): BankSpendMatch | null;
+export declare function reconcileThreeWay(providerTransfers: ProviderTransfer[], bankTransactions: BankTransaction[], platformSpend: PlatformSpendEntry[], thresholdBps?: number): ReconciliationReport;
+export declare function shouldFreeze(mismatchCount: number, consecutiveCount: number, maxConsecutive: number): boolean;
+export type { Cents, ProviderTransfer, BankTransaction, PlatformSpendEntry, VarianceClassification, TransferBankMatch, BankSpendMatch, ReconciliationReport, };