thevoidforge 21.0.0

package/dist/wizard/lib/patterns/financial-transaction.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Pattern: Financial Transaction (Branded Types + Hash-Chained Append Log)
+ *
+ * Key principles:
+ * - All money in integer cents (Cents branded type) — NEVER floating point
+ * - Append-only immutable logs — never rewrite, only append
+ * - Hash chain for tamper detection (SHA-256 of previous entry)
+ * - Atomic writes (write-to-temp + fsync + rename) per ADR-1
+ * - macOS: use F_FULLFSYNC instead of fsync for financial files (§9.18)
+ * - Single-writer architecture — only the heartbeat daemon writes financial state
+ *
+ * Agents: Dockson (treasury), Steris (budget), Vin (analytics)
+ *
+ * PRD Reference: §9.9, §9.17 (branded types), §9.18 (macOS fsync), ADR-1/ADR-3
+ */
+type Cents = number & {
+    readonly __brand: 'Cents';
+};
+type Percentage = number & {
+    readonly __brand: 'Percentage';
+};
+type Ratio = number & {
+    readonly __brand: 'Ratio';
+};
+type AdPlatform = 'meta' | 'google' | 'tiktok' | 'linkedin' | 'twitter' | 'reddit';
+type RevenueSource = 'stripe' | 'paddle';
+type BankSource = 'mercury' | 'brex';
+type TransactionSource = AdPlatform | RevenueSource | BankSource;
+declare function toCents(dollars: number): Cents;
+declare function toDollars(cents: Cents): number;
+interface Transaction {
+    id: string;
+    projectId: string;
+    type: 'revenue' | 'spend' | 'refund';
+    source: TransactionSource;
+    externalId: string;
+    amount: Cents;
+    currency: 'USD';
+    description: string;
+    metadata: Record<string, string>;
+    createdAt: string;
+    reconciledAt?: string;
+    reconciledStatus?: 'matched' | 'discrepancy' | 'pending';
+}
+interface Budget {
+    id: string;
+    projectId: string;
+    period: 'daily' | 'weekly' | 'monthly';
+    totalAmount: Cents;
+    currency: 'USD';
+    allocations: Array<{
+        platform: AdPlatform;
+        amount: Cents;
+        dailyCap: Cents;
+    }>;
+    safetyTiers: {
+        autoApproveBelow: Cents;
+        agentApproveBelow: Cents;
+        humanConfirmBelow: Cents;
+        hardStopAbove: Cents;
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+type CampaignStatus = 'draft' | 'pending_approval' | 'creating' | 'active' | 'paused' | 'completed' | 'error' | 'suspended' | 'deleting' | 'freeze_pending';
+type CampaignEventSource = 'cli' | 'daemon' | 'platform' | 'agent';
+interface CampaignStateEvent {
+    timestamp: string;
+    source: CampaignEventSource;
+    oldStatus: CampaignStatus;
+    newStatus: CampaignStatus;
+    reason: string;
+    ruleId?: string;
+}
+interface GrowthCampaign {
+    id: string;
+    projectId: string;
+    platform: AdPlatform;
+    externalId: string;
+    name: string;
+    status: CampaignStatus;
+    dailyBudget: Cents;
+    totalSpend: Cents;
+    metrics: {
+        impressions: number;
+        clicks: number;
+        conversions: number;
+        ctr: Percentage;
+        cpc: Cents;
+        roas: Ratio;
+    };
+    testGroupId?: string;
+    testVariant?: string;
+    testMetric?: 'ctr' | 'roas' | 'conversions';
+    events: CampaignStateEvent[];
+    createdAt: string;
+    updatedAt: string;
+    pausedAt?: string;
+    pauseReason?: string;
+}
+interface RevenueEvent {
+    id: string;
+    projectId: string;
+    source: RevenueSource;
+    type: 'charge' | 'subscription' | 'refund' | 'dispute';
+    amount: Cents;
+    currency: 'USD';
+    customerId?: string;
+    subscriptionId?: string;
+    metadata: Record<string, string>;
+    createdAt: string;
+}
+interface ReconciliationReport {
+    id: string;
+    date: string;
+    type: 'preliminary' | 'final';
+    projectId: string;
+    spend: Array<{
+        platform: AdPlatform;
+        voidforgeRecorded: Cents;
+        platformReported: Cents;
+        discrepancy: Cents;
+        status: 'matched' | 'discrepancy' | 'unavailable';
+    }>;
+    revenue: Array<{
+        source: RevenueSource;
+        recorded: Cents;
+        reported: Cents;
+        discrepancy: Cents;
+        status: 'matched' | 'discrepancy' | 'unavailable';
+    }>;
+    netPosition: Cents;
+    blendedRoas: Ratio;
+    alerts: string[];
+}
+type CultivationSystemState = 'inactive' | 'active' | 'frozen' | 'partial_freeze' | 'recovering' | 'degraded' | 'recovery_failed';
+interface HashChainedEntry<T> {
+    data: T;
+    prevHash: string;
+    hash: string;
+    walIntentId?: string;
+}
+declare function computeHash(data: unknown, prevHash: string): string;
+declare function createChainedEntry<T>(data: T, prevHash: string, walIntentId?: string): HashChainedEntry<T>;
+declare function verifyChain<T>(entries: HashChainedEntry<T>[]): {
+    valid: boolean;
+    brokenAt?: number;
+};
+declare function atomicWrite(filePath: string, content: string): Promise<void>;
+declare function appendToLog<T>(logPath: string, data: T, prevHash: string, walIntentId?: string): Promise<HashChainedEntry<T>>;
+declare function idempotentAppend<T>(logPath: string, data: T, prevHash: string, walIntentId: string, recentEntries: HashChainedEntry<T>[]): Promise<HashChainedEntry<T> | null>;
+declare const TREASURY_DIR: string;
+declare const SPEND_LOG: string;
+declare const REVENUE_LOG: string;
+declare const PENDING_OPS: string;
+declare const BUDGETS_FILE: string;
+declare function formatCurrency(cents: Cents, detail?: boolean): string;
+declare function formatRoas(roas: Ratio): string;
+declare function formatPercentage(pct: Percentage, showSign?: boolean): string;
+export type { Transaction, Budget, GrowthCampaign, RevenueEvent, ReconciliationReport, CampaignStatus, CampaignEventSource, CampaignStateEvent, CultivationSystemState, HashChainedEntry, Cents, Percentage, Ratio, AdPlatform, RevenueSource, BankSource, TransactionSource, };
+export { toCents, toDollars, computeHash, createChainedEntry, verifyChain, atomicWrite, appendToLog, idempotentAppend, formatCurrency, formatRoas, formatPercentage, TREASURY_DIR, SPEND_LOG, REVENUE_LOG, PENDING_OPS, BUDGETS_FILE, };

package/dist/wizard/lib/patterns/financial-transaction.js

@@ -0,0 +1,132 @@
+/**
+ * Pattern: Financial Transaction (Branded Types + Hash-Chained Append Log)
+ *
+ * Key principles:
+ * - All money in integer cents (Cents branded type) — NEVER floating point
+ * - Append-only immutable logs — never rewrite, only append
+ * - Hash chain for tamper detection (SHA-256 of previous entry)
+ * - Atomic writes (write-to-temp + fsync + rename) per ADR-1
+ * - macOS: use F_FULLFSYNC instead of fsync for financial files (§9.18)
+ * - Single-writer architecture — only the heartbeat daemon writes financial state
+ *
+ * Agents: Dockson (treasury), Steris (budget), Vin (analytics)
+ *
+ * PRD Reference: §9.9, §9.17 (branded types), §9.18 (macOS fsync), ADR-1/ADR-3
+ */
+import { createHash } from 'node:crypto';
+import { appendFile, open, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+function toCents(dollars) {
+    return Math.round(dollars * 100);
+}
+function toDollars(cents) {
+    return cents / 100;
+}
+function computeHash(data, prevHash) {
+    const payload = JSON.stringify(data) + prevHash;
+    return createHash('sha256').update(payload).digest('hex');
+}
+function createChainedEntry(data, prevHash, walIntentId) {
+    const hash = computeHash(data, prevHash);
+    return { data, prevHash, hash, walIntentId };
+}
+function verifyChain(entries) {
+    for (let i = 0; i < entries.length; i++) {
+        const expected = computeHash(entries[i].data, entries[i].prevHash);
+        if (expected !== entries[i].hash) {
+            return { valid: false, brokenAt: i };
+        }
+        if (i > 0 && entries[i].prevHash !== entries[i - 1].hash) {
+            return { valid: false, brokenAt: i };
+        }
+    }
+    return { valid: true };
+}
+// ── Atomic File Write ─────────────────────────────────
+// write-to-temp + fsync (F_FULLFSYNC on macOS) + rename
+// Per ADR-1: all mutable financial file writes use this pattern.
+async function atomicWrite(filePath, content) {
+    const tempPath = filePath + '.tmp.' + process.pid;
+    // Write to temp file
+    const fd = await open(tempPath, 'w');
+    try {
+        await fd.writeFile(content, 'utf-8');
+        // Durable sync — F_FULLFSYNC on macOS, fsync on Linux (§9.18)
+        if (platform() === 'darwin') {
+            // macOS: fsync() does NOT guarantee physical durability
+            // Must use fcntl(fd, F_FULLFSYNC) — 51 is the macOS constant
+            // Node.js datasync maps to fdatasync, not F_FULLFSYNC
+            // In production: use native addon or child_process to call fcntl(fd, 51)
+            // For now: document the gap — datasync is sufficient for crash safety, not power loss
+            await fd.datasync();
+        }
+        else {
+            await fd.sync();
+        }
+    }
+    finally {
+        await fd.close();
+    }
+    // Atomic rename — on POSIX, rename is atomic
+    await rename(tempPath, filePath);
+}
+// ── Append-Only Log ───────────────────────────────────
+// For spend-log.jsonl and revenue-log.jsonl
+async function appendToLog(logPath, data, prevHash, walIntentId) {
+    const entry = createChainedEntry(data, prevHash, walIntentId);
+    const line = JSON.stringify(entry) + '\n';
+    await appendFile(logPath, line, 'utf-8');
+    return entry;
+}
+// ── Idempotent Append (ADR-3 WAL replay) ──────────────
+// Before appending during WAL replay, check if the intent ID exists in recent entries.
+async function idempotentAppend(logPath, data, prevHash, walIntentId, recentEntries) {
+    // Check if this WAL intent was already applied
+    const existing = recentEntries.find(e => e.walIntentId === walIntentId);
+    if (existing) {
+        return null; // Already applied — skip
+    }
+    return appendToLog(logPath, data, prevHash, walIntentId);
+}
+// ── Storage Layout ────────────────────────────────────
+// ~/.voidforge/treasury/
+// ├── vault.enc                 # financial vault (AES-256-GCM, Argon2id)
+// ├── budgets.json              # active budget allocations per project
+// ├── spend-log.jsonl           # append-only spend log (immutable, hash-chained)
+// ├── revenue-log.jsonl         # append-only revenue log (immutable, hash-chained)
+// ├── pending-ops.jsonl         # WAL for platform API operations (ADR-3)
+// ├── campaigns/
+// │   └── {projectId}/
+// │       ├── meta-{id}.json
+// │       └── google-{id}.json
+// ├── reconciliation/
+// │   ├── 2026-03-17.json
+// │   └── 2026-03-16.json
+// └── reports/
+//     └── 2026-03.json          # monthly summary
+const TREASURY_DIR = join(homedir(), '.voidforge', 'treasury');
+const SPEND_LOG = join(TREASURY_DIR, 'spend-log.jsonl');
+const REVENUE_LOG = join(TREASURY_DIR, 'revenue-log.jsonl');
+const PENDING_OPS = join(TREASURY_DIR, 'pending-ops.jsonl');
+const BUDGETS_FILE = join(TREASURY_DIR, 'budgets.json');
+// ── Number Formatting (§9.15.4) ───────────────────────
+function formatCurrency(cents, detail = false) {
+    const dollars = toDollars(cents);
+    if (dollars >= 100_000) {
+        return dollars >= 1_000_000 ? `$${(dollars / 1_000_000).toFixed(1)}M` : `$${Math.round(dollars / 1000)}K`;
+    }
+    if (detail)
+        return `$${dollars.toFixed(2)}`;
+    if (cents < 0)
+        return `-$${Math.abs(dollars).toLocaleString('en-US', { maximumFractionDigits: 0 })}`;
+    return `$${dollars.toLocaleString('en-US', { maximumFractionDigits: 0 })}`;
+}
+function formatRoas(roas) {
+    return `${roas.toFixed(1)}x`;
+}
+function formatPercentage(pct, showSign = false) {
+    const sign = showSign && pct > 0 ? '+' : '';
+    return `${sign}${pct.toFixed(1)}%`;
+}
+export { toCents, toDollars, computeHash, createChainedEntry, verifyChain, atomicWrite, appendToLog, idempotentAppend, formatCurrency, formatRoas, formatPercentage, TREASURY_DIR, SPEND_LOG, REVENUE_LOG, PENDING_OPS, BUDGETS_FILE, };

package/dist/wizard/lib/patterns/funding-plan.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Pattern: Funding Plan (Core Data Structure + Pure Logic)
+ *
+ * Key principles:
+ * - The FundingPlan is the central data structure connecting:
+ *     stablecoin source → off-ramp → bank settlement → platform billing
+ * - Plans are IMMUTABLE once approved — state transitions only, no field edits
+ * - Hash-chained for tamper-evident audit trail (per financial-transaction.ts)
+ * - All monetary values use branded integer cents (Cents type)
+ * - Pure logic functions: no I/O, no side effects, fully testable
+ * - Single-writer: only Heartbeat daemon creates and transitions FundingPlans
+ *
+ * Agents: Dockson (treasury), Heartbeat daemon
+ *
+ * PRD Reference: §12.1, §12.2, §12.4, §12.5, §12.6, §13, §15
+ */
+type Cents = number & {
+    readonly __brand: 'Cents';
+};
+declare function toCents(dollars: number): Cents;
+declare function toDollars(cents: Cents): number;
+type StablecoinProviderType = 'circle' | 'bridge' | 'manual';
+interface StablecoinFundingSource {
+    id: string;
+    provider: StablecoinProviderType;
+    asset: string;
+    network: string;
+    sourceAccountId: string;
+    whitelistedDestinationBankId: string;
+    status: 'active' | 'suspended' | 'unconfigured';
+}
+type BankProvider = 'mercury' | 'external';
+interface OperatingBankAccount {
+    id: string;
+    provider: BankProvider;
+    accountId: string;
+    currency: 'USD';
+    availableBalanceCents: Cents;
+    reservedBalanceCents: Cents;
+    minimumBufferCents: Cents;
+}
+type CapabilityState = 'FULLY_FUNDABLE' | 'MONITORED_ONLY' | 'UNSUPPORTED';
+type BillingMode = 'monthly_invoicing' | 'direct_debit' | 'extended_credit' | 'manual_bank_transfer' | 'card_only' | 'unknown';
+type AdPlatform = 'google' | 'meta';
+interface PlatformBillingProfile {
+    platform: AdPlatform;
+    capabilityState: CapabilityState;
+    billingMode: BillingMode;
+    externalAccountId: string;
+    billingSetupId?: string;
+    invoiceGroupId?: string;
+    paymentProfileId?: string;
+    fundingSourceId?: string;
+    currency: 'USD';
+    nextDueDate?: string;
+    status: 'active' | 'degraded' | 'suspended' | 'unconfigured';
+}
+type FundingPlanStatus = 'DRAFT' | 'APPROVED' | 'PENDING_SETTLEMENT' | 'SETTLED' | 'FAILED' | 'FROZEN';
+type FundingPlanReason = 'LOW_BUFFER' | 'INVOICE_DUE' | 'RUNWAY_SHORTFALL' | 'MANUAL_REQUEST';
+type ApprovalMode = 'policy_auto' | 'vault_manual' | 'totp_required';
+type TargetPlatform = AdPlatform | 'shared_buffer';
+interface FundingPlan {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    reason: FundingPlanReason;
+    sourceFundingId: string;
+    destinationBankId: string;
+    targetPlatform: TargetPlatform;
+    requiredCents: Cents;
+    reservedCents: Cents;
+    status: FundingPlanStatus;
+    approvalMode: ApprovalMode;
+    approvedAt?: string;
+    approvedBy?: string;
+    settledAt?: string;
+    failureReason?: string;
+    idempotencyKey: string;
+    previousHash: string;
+    hash: string;
+}
+type TransferDirection = 'crypto_to_fiat' | 'bank_to_platform' | 'platform_debit';
+type TransferStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
+interface TransferRecord {
+    id: string;
+    fundingPlanId: string;
+    providerTransferId: string;
+    bankTransactionId?: string;
+    direction: TransferDirection;
+    amountCents: Cents;
+    feesCents: Cents;
+    netAmountCents: Cents;
+    currency: 'USD';
+    reference: string;
+    status: TransferStatus;
+    initiatedAt: string;
+    completedAt?: string;
+    previousHash: string;
+    hash: string;
+}
+type ReconciliationResult = 'MATCHED' | 'WITHIN_THRESHOLD' | 'MISMATCH';
+interface ReconciliationRecord {
+    id: string;
+    platform: AdPlatform;
+    date: string;
+    spendCents: Cents;
+    bankSettledCents: Cents;
+    invoiceCents: Cents;
+    varianceCents: Cents;
+    result: ReconciliationResult;
+    notes: string;
+    createdAt: string;
+    previousHash: string;
+    hash: string;
+}
+declare function computePlanHash(plan: Omit<FundingPlan, 'hash'>, previousHash: string): string;
+declare function computeTransferHash(record: Omit<TransferRecord, 'hash'>, previousHash: string): string;
+declare function computeReconciliationHash(record: Omit<ReconciliationRecord, 'hash'>, previousHash: string): string;
+declare function createFundingPlan(reason: FundingPlanReason, sourceFundingId: string, destinationBankId: string, targetPlatform: TargetPlatform, requiredCents: Cents, previousHash: string): FundingPlan;
+declare function approvePlan(plan: FundingPlan, approvalMode: ApprovalMode, approvedBy: string): FundingPlan;
+declare function transitionPlan(plan: FundingPlan, newStatus: FundingPlanStatus, reason?: string): FundingPlan;
+declare function calculateRunway(bankBalanceCents: Cents, dailySpendRateCents: Cents): number;
+declare function shouldTriggerOfframp(bankBalanceCents: Cents, bufferThresholdCents: Cents, pendingSpendCents: Cents, pendingOfframpCents: Cents): boolean;
+declare function calculateRequiredOfframp(bankBalanceCents: Cents, bufferThresholdCents: Cents, pendingSpendCents: Cents, pendingOfframpCents: Cents, minimumOfframpCents: Cents): Cents;
+declare function reconcileTransfer(transferAmountCents: Cents, bankTransactionCents: Cents, platformSpendCents: Cents, thresholdBps: number, // basis points tolerance (e.g., 50 = 0.5%)
+platform: AdPlatform, date: string, previousHash: string): ReconciliationRecord;
+interface PendingObligation {
+    id: string;
+    platform: AdPlatform;
+    amountCents: Cents;
+    dueDate: string;
+    overdue: boolean;
+}
+declare function prioritizeObligations(obligations: PendingObligation[]): PendingObligation[];
+export type { Cents, StablecoinProviderType, StablecoinFundingSource, BankProvider, OperatingBankAccount, CapabilityState, BillingMode, AdPlatform, PlatformBillingProfile, FundingPlanStatus, FundingPlanReason, ApprovalMode, TargetPlatform, FundingPlan, TransferDirection, TransferStatus, TransferRecord, ReconciliationResult, ReconciliationRecord, PendingObligation, };
+export { toCents, toDollars, computePlanHash, computeTransferHash, computeReconciliationHash, createFundingPlan, approvePlan, transitionPlan, calculateRunway, shouldTriggerOfframp, calculateRequiredOfframp, reconcileTransfer, prioritizeObligations, };

package/dist/wizard/lib/patterns/funding-plan.js

@@ -0,0 +1,200 @@
+/**
+ * Pattern: Funding Plan (Core Data Structure + Pure Logic)
+ *
+ * Key principles:
+ * - The FundingPlan is the central data structure connecting:
+ *     stablecoin source → off-ramp → bank settlement → platform billing
+ * - Plans are IMMUTABLE once approved — state transitions only, no field edits
+ * - Hash-chained for tamper-evident audit trail (per financial-transaction.ts)
+ * - All monetary values use branded integer cents (Cents type)
+ * - Pure logic functions: no I/O, no side effects, fully testable
+ * - Single-writer: only Heartbeat daemon creates and transitions FundingPlans
+ *
+ * Agents: Dockson (treasury), Heartbeat daemon
+ *
+ * PRD Reference: §12.1, §12.2, §12.4, §12.5, §12.6, §13, §15
+ */
+import { createHash } from 'node:crypto';
+function toCents(dollars) {
+    return Math.round(dollars * 100);
+}
+function toDollars(cents) {
+    return cents / 100;
+}
+// ── Hash Chain Helpers ──────────────────────────────
+function computePlanHash(plan, previousHash) {
+    const payload = JSON.stringify({
+        id: plan.id,
+        reason: plan.reason,
+        sourceFundingId: plan.sourceFundingId,
+        destinationBankId: plan.destinationBankId,
+        requiredCents: plan.requiredCents,
+        status: plan.status,
+        createdAt: plan.createdAt,
+        idempotencyKey: plan.idempotencyKey,
+    }) + previousHash;
+    return createHash('sha256').update(payload).digest('hex');
+}
+function computeTransferHash(record, previousHash) {
+    const payload = JSON.stringify({
+        id: record.id,
+        fundingPlanId: record.fundingPlanId,
+        providerTransferId: record.providerTransferId,
+        amountCents: record.amountCents,
+        feesCents: record.feesCents,
+        status: record.status,
+        initiatedAt: record.initiatedAt,
+    }) + previousHash;
+    return createHash('sha256').update(payload).digest('hex');
+}
+function computeReconciliationHash(record, previousHash) {
+    const payload = JSON.stringify({
+        id: record.id,
+        platform: record.platform,
+        date: record.date,
+        spendCents: record.spendCents,
+        bankSettledCents: record.bankSettledCents,
+        invoiceCents: record.invoiceCents,
+        varianceCents: record.varianceCents,
+        result: record.result,
+    }) + previousHash;
+    return createHash('sha256').update(payload).digest('hex');
+}
+// ── Pure Logic: Funding Plan Creation ───────────────
+function createFundingPlan(reason, sourceFundingId, destinationBankId, targetPlatform, requiredCents, previousHash) {
+    const now = new Date().toISOString();
+    const id = crypto.randomUUID();
+    const idempotencyKey = crypto.randomUUID();
+    const draft = {
+        id,
+        createdAt: now,
+        updatedAt: now,
+        reason,
+        sourceFundingId,
+        destinationBankId,
+        targetPlatform,
+        requiredCents,
+        reservedCents: 0,
+        status: 'DRAFT',
+        approvalMode: 'policy_auto', // default; upgraded by approval logic
+        idempotencyKey,
+        previousHash,
+    };
+    const hash = computePlanHash(draft, previousHash);
+    return { ...draft, hash };
+}
+// ── Pure Logic: Plan Approval ───────────────────────
+function approvePlan(plan, approvalMode, approvedBy) {
+    if (plan.status !== 'DRAFT') {
+        throw new Error(`Cannot approve plan in status ${plan.status} — must be DRAFT`);
+    }
+    const now = new Date().toISOString();
+    const approved = {
+        ...plan,
+        status: 'APPROVED',
+        approvalMode,
+        approvedBy,
+        approvedAt: now,
+        updatedAt: now,
+        previousHash: plan.hash,
+    };
+    const hash = computePlanHash(approved, plan.hash);
+    return { ...approved, hash };
+}
+// ── Pure Logic: Plan State Transitions ──────────────
+function transitionPlan(plan, newStatus, reason) {
+    // Validate allowed transitions
+    const allowedTransitions = {
+        'DRAFT': ['APPROVED', 'FROZEN'],
+        'APPROVED': ['PENDING_SETTLEMENT', 'FROZEN', 'FAILED'],
+        'PENDING_SETTLEMENT': ['SETTLED', 'FAILED', 'FROZEN'],
+        'SETTLED': [], // terminal state
+        'FAILED': ['DRAFT'], // can retry by creating new draft
+        'FROZEN': ['DRAFT'], // can unfreeze to draft for re-approval
+    };
+    const allowed = allowedTransitions[plan.status];
+    if (!allowed.includes(newStatus)) {
+        throw new Error(`Invalid transition: ${plan.status} → ${newStatus}. Allowed: ${allowed.join(', ') || 'none (terminal)'}`);
+    }
+    const now = new Date().toISOString();
+    const transitioned = {
+        ...plan,
+        status: newStatus,
+        updatedAt: now,
+        settledAt: newStatus === 'SETTLED' ? now : plan.settledAt,
+        failureReason: newStatus === 'FAILED' ? reason : plan.failureReason,
+        previousHash: plan.hash,
+    };
+    const hash = computePlanHash(transitioned, plan.hash);
+    return { ...transitioned, hash };
+}
+// ── Pure Logic: Runway Calculation ──────────────────
+function calculateRunway(bankBalanceCents, dailySpendRateCents) {
+    if (dailySpendRateCents <= 0)
+        return Infinity;
+    return Math.floor(bankBalanceCents / dailySpendRateCents);
+}
+// ── Pure Logic: Off-ramp Trigger Decision ───────────
+function shouldTriggerOfframp(bankBalanceCents, bufferThresholdCents, pendingSpendCents, pendingOfframpCents) {
+    // Available balance after accounting for pending obligations
+    const effectiveBalance = (bankBalanceCents - pendingSpendCents + pendingOfframpCents);
+    return effectiveBalance < bufferThresholdCents;
+}
+// ── Pure Logic: Required Off-ramp Amount ────────────
+function calculateRequiredOfframp(bankBalanceCents, bufferThresholdCents, pendingSpendCents, pendingOfframpCents, minimumOfframpCents) {
+    const deficit = (bufferThresholdCents + pendingSpendCents - bankBalanceCents - pendingOfframpCents);
+    if (deficit <= 0)
+        return 0;
+    // Round up to minimum off-ramp amount if below provider minimum
+    return Math.max(deficit, minimumOfframpCents);
+}
+// ── Pure Logic: Reconciliation ──────────────────────
+function reconcileTransfer(transferAmountCents, bankTransactionCents, platformSpendCents, thresholdBps, // basis points tolerance (e.g., 50 = 0.5%)
+platform, date, previousHash) {
+    const invoiceCents = transferAmountCents; // what was transferred
+    const varianceCents = Math.abs(invoiceCents - bankTransactionCents);
+    // Determine result based on variance threshold
+    let result;
+    if (varianceCents === 0) {
+        result = 'MATCHED';
+    }
+    else {
+        const varianceBps = invoiceCents > 0
+            ? (varianceCents / invoiceCents) * 10_000
+            : 0;
+        result = varianceBps <= thresholdBps ? 'WITHIN_THRESHOLD' : 'MISMATCH';
+    }
+    const id = crypto.randomUUID();
+    const now = new Date().toISOString();
+    const record = {
+        id,
+        platform,
+        date,
+        spendCents: platformSpendCents,
+        bankSettledCents: bankTransactionCents,
+        invoiceCents,
+        varianceCents,
+        result,
+        notes: result === 'MISMATCH'
+            ? `Variance ${varianceCents} cents exceeds ${thresholdBps}bps threshold`
+            : result === 'WITHIN_THRESHOLD'
+                ? `Variance ${varianceCents} cents within ${thresholdBps}bps threshold`
+                : 'Exact match',
+        createdAt: now,
+        previousHash,
+    };
+    const hash = computeReconciliationHash(record, previousHash);
+    return { ...record, hash };
+}
+function prioritizeObligations(obligations) {
+    return [...obligations].sort((a, b) => {
+        // Overdue items first
+        if (a.overdue && !b.overdue)
+            return -1;
+        if (!a.overdue && b.overdue)
+            return 1;
+        // Then by due date (earliest first)
+        return new Date(a.dueDate).getTime() - new Date(b.dueDate).getTime();
+    });
+}
+export { toCents, toDollars, computePlanHash, computeTransferHash, computeReconciliationHash, createFundingPlan, approvePlan, transitionPlan, calculateRunway, shouldTriggerOfframp, calculateRequiredOfframp, reconcileTransfer, prioritizeObligations, };