voidforge-build 23.9.1

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

package/dist/wizard/lib/patterns/oauth-token-lifecycle.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Pattern: OAuth Token Lifecycle
+ *
+ * Key principles:
+ * - Refresh at 80% of TTL (not at expiry — prevents race conditions)
+ * - Multi-grant-type support (authorization_code, refresh_token)
+ * - Vault integration — tokens encrypted at rest in financial vault
+ * - Failure escalation: retry 3x → pause platform → alert → requires_reauth
+ * - Token stored as encrypted blob in vault, keyed by platform name
+ * - Session token (daemon) rotates every 24 hours (§9.19.15)
+ *
+ * Agents: Breeze (platform relations), Dockson (vault)
+ *
+ * PRD Reference: §9.5 (token refresh strategy), §9.18 (vault session), §9.19.15
+ */
+type AdPlatform = 'meta' | 'google' | 'tiktok' | 'linkedin' | 'twitter' | 'reddit';
+interface OAuthTokenSet {
+    platform: AdPlatform;
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+    tokenType: string;
+    scopes: string[];
+    grantedAt: string;
+    lastRefreshedAt: string;
+}
+type TokenHealth = 'healthy' | 'expiring_soon' | 'expired' | 'refresh_failed' | 'requires_reauth' | 'revoked';
+interface TokenStatus {
+    platform: AdPlatform;
+    health: TokenHealth;
+    expiresAt: string;
+    lastRefresh: string;
+    consecutiveFailures: number;
+    error?: string;
+}
+interface PlatformTokenConfig {
+    platform: AdPlatform;
+    accessTokenTtlHours: number;
+    refreshTokenTtlDays: number;
+    refreshEndpoint: string;
+    revokeEndpoint?: string;
+}
+declare const PLATFORM_CONFIGS: PlatformTokenConfig[];
+declare const REFRESH_AT_TTL_PERCENT = 0.8;
+declare const MAX_CONSECUTIVE_FAILURES = 3;
+/**
+ * Check if a token needs refresh.
+ * Returns true if the token is past 80% of its TTL.
+ */
+declare function needsRefresh(token: OAuthTokenSet): boolean;
+/**
+ * Determine the health status of a token.
+ */
+declare function getTokenHealth(token: OAuthTokenSet, failures: number): TokenHealth;
+interface RefreshResult {
+    success: boolean;
+    newTokens?: OAuthTokenSet;
+    error?: string;
+    requiresReauth?: boolean;
+}
+/**
+ * Handle a refresh failure. Implements the escalation:
+ * 1st failure: retry after 30s
+ * 2nd failure: retry after 60s
+ * 3rd failure: pause campaigns on this platform, set requires_reauth, alert
+ *
+ * The `invalid_grant` error means the refresh token itself is expired/revoked.
+ * This does NOT count toward the 3-failure pause trigger (§9.18) —
+ * it goes straight to requires_reauth.
+ */
+declare function handleRefreshFailure(platform: AdPlatform, error: string, consecutiveFailures: number): {
+    action: 'retry' | 'pause_and_alert' | 'reauth';
+    retryAfterMs?: number;
+};
+declare function tokenVaultKey(platform: AdPlatform): string;
+/**
+ * Serialize tokens for vault storage.
+ * The vault stores strings — tokens are JSON-serialized.
+ */
+declare function serializeTokens(tokens: OAuthTokenSet): string;
+declare function deserializeTokens(data: string): OAuthTokenSet;
+declare const SESSION_TOKEN_TTL_MS: number;
+declare const SESSION_TOKEN_GRACE_MS: number;
+interface SessionTokenState {
+    current: string;
+    previous?: string;
+    rotatedAt: number;
+    previousExpiresAt?: number;
+}
+declare function shouldRotateSessionToken(state: SessionTokenState): boolean;
+declare function rotateSessionToken(state: SessionTokenState, newToken: string): SessionTokenState;
+declare function validateSessionToken(provided: string, state: SessionTokenState): boolean;
+export type { OAuthTokenSet, TokenHealth, TokenStatus, PlatformTokenConfig, RefreshResult, SessionTokenState };
+export { PLATFORM_CONFIGS, REFRESH_AT_TTL_PERCENT, MAX_CONSECUTIVE_FAILURES, needsRefresh, getTokenHealth, handleRefreshFailure, tokenVaultKey, serializeTokens, deserializeTokens, SESSION_TOKEN_TTL_MS, SESSION_TOKEN_GRACE_MS, shouldRotateSessionToken, rotateSessionToken, validateSessionToken, };

package/dist/wizard/lib/patterns/oauth-token-lifecycle.js

@@ -0,0 +1,139 @@
+/**
+ * Pattern: OAuth Token Lifecycle
+ *
+ * Key principles:
+ * - Refresh at 80% of TTL (not at expiry — prevents race conditions)
+ * - Multi-grant-type support (authorization_code, refresh_token)
+ * - Vault integration — tokens encrypted at rest in financial vault
+ * - Failure escalation: retry 3x → pause platform → alert → requires_reauth
+ * - Token stored as encrypted blob in vault, keyed by platform name
+ * - Session token (daemon) rotates every 24 hours (§9.19.15)
+ *
+ * Agents: Breeze (platform relations), Dockson (vault)
+ *
+ * PRD Reference: §9.5 (token refresh strategy), §9.18 (vault session), §9.19.15
+ */
+const PLATFORM_CONFIGS = [
+    { platform: 'meta', accessTokenTtlHours: 1440, refreshTokenTtlDays: 0, refreshEndpoint: 'https://graph.facebook.com/v19.0/oauth/access_token' },
+    { platform: 'google', accessTokenTtlHours: 1, refreshTokenTtlDays: 0, refreshEndpoint: 'https://oauth2.googleapis.com/token' },
+    { platform: 'tiktok', accessTokenTtlHours: 24, refreshTokenTtlDays: 365, refreshEndpoint: 'https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/' },
+    { platform: 'linkedin', accessTokenTtlHours: 1440, refreshTokenTtlDays: 365, refreshEndpoint: 'https://www.linkedin.com/oauth/v2/accessToken' },
+    { platform: 'twitter', accessTokenTtlHours: 0, refreshTokenTtlDays: 0, refreshEndpoint: '' }, // OAuth 1.0a — tokens don't expire
+    { platform: 'reddit', accessTokenTtlHours: 1, refreshTokenTtlDays: 0, refreshEndpoint: 'https://www.reddit.com/api/v1/access_token' },
+];
+// ── Refresh Logic ─────────────────────────────────────
+const REFRESH_AT_TTL_PERCENT = 0.80; // Refresh at 80% of TTL
+const MAX_CONSECUTIVE_FAILURES = 3;
+/**
+ * Check if a token needs refresh.
+ * Returns true if the token is past 80% of its TTL.
+ */
+function needsRefresh(token) {
+    const config = PLATFORM_CONFIGS.find(c => c.platform === token.platform);
+    if (!config || config.accessTokenTtlHours === 0)
+        return false; // Never expires (Twitter OAuth 1.0a)
+    const expiresAt = new Date(token.expiresAt).getTime();
+    const lastRefresh = new Date(token.lastRefreshedAt).getTime();
+    const ttlMs = config.accessTokenTtlHours * 60 * 60 * 1000;
+    const refreshAt = lastRefresh + (ttlMs * REFRESH_AT_TTL_PERCENT);
+    return Date.now() >= refreshAt;
+}
+/**
+ * Determine the health status of a token.
+ */
+function getTokenHealth(token, failures) {
+    if (failures >= MAX_CONSECUTIVE_FAILURES)
+        return 'requires_reauth';
+    const now = Date.now();
+    const expiresAt = new Date(token.expiresAt).getTime();
+    if (expiresAt < now)
+        return 'expired';
+    const config = PLATFORM_CONFIGS.find(c => c.platform === token.platform);
+    if (!config || config.accessTokenTtlHours === 0)
+        return 'healthy'; // Never expires
+    const ttlMs = config.accessTokenTtlHours * 60 * 60 * 1000;
+    const warningAt = expiresAt - (ttlMs * 0.2); // Warn at 80% consumed
+    if (now >= warningAt)
+        return 'expiring_soon';
+    if (failures > 0)
+        return 'refresh_failed';
+    return 'healthy';
+}
+/**
+ * Handle a refresh failure. Implements the escalation:
+ * 1st failure: retry after 30s
+ * 2nd failure: retry after 60s
+ * 3rd failure: pause campaigns on this platform, set requires_reauth, alert
+ *
+ * The `invalid_grant` error means the refresh token itself is expired/revoked.
+ * This does NOT count toward the 3-failure pause trigger (§9.18) —
+ * it goes straight to requires_reauth.
+ */
+function handleRefreshFailure(platform, error, consecutiveFailures) {
+    // invalid_grant = refresh token revoked/expired — immediate reauth
+    if (error.includes('invalid_grant') || error.includes('revoked')) {
+        return { action: 'reauth' };
+    }
+    const newCount = consecutiveFailures + 1;
+    if (newCount >= MAX_CONSECUTIVE_FAILURES) {
+        return { action: 'pause_and_alert' };
+    }
+    // Exponential backoff: 30s, 60s
+    const retryAfterMs = 30000 * Math.pow(2, consecutiveFailures);
+    return { action: 'retry', retryAfterMs };
+}
+// ── Vault Integration ─────────────────────────────────
+// Tokens are stored in the financial vault, keyed by platform name.
+// The daemon reads them at startup and holds them in memory.
+// On refresh, the daemon writes the updated token back to the vault.
+const TOKEN_VAULT_KEY_PREFIX = 'growth/tokens/';
+function tokenVaultKey(platform) {
+    return TOKEN_VAULT_KEY_PREFIX + platform;
+}
+/**
+ * Serialize tokens for vault storage.
+ * The vault stores strings — tokens are JSON-serialized.
+ */
+function serializeTokens(tokens) {
+    return JSON.stringify(tokens);
+}
+function deserializeTokens(data) {
+    return JSON.parse(data);
+}
+// ── Session Token Rotation (§9.19.15) ─────────────────
+// The daemon session token (heartbeat.token) rotates every 24 hours.
+// During rotation, accept both old and new tokens for 30-second grace period.
+const SESSION_TOKEN_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const SESSION_TOKEN_GRACE_MS = 30 * 1000; // 30 seconds
+function shouldRotateSessionToken(state) {
+    return Date.now() - state.rotatedAt >= SESSION_TOKEN_TTL_MS;
+}
+function rotateSessionToken(state, newToken) {
+    return {
+        current: newToken,
+        previous: state.current,
+        rotatedAt: Date.now(),
+        previousExpiresAt: Date.now() + SESSION_TOKEN_GRACE_MS,
+    };
+}
+function validateSessionToken(provided, state) {
+    const { timingSafeEqual } = require('node:crypto');
+    // Check current token
+    if (provided.length === state.current.length) {
+        const a = Buffer.from(provided);
+        const b = Buffer.from(state.current);
+        if (timingSafeEqual(a, b))
+            return true;
+    }
+    // Check previous token during grace period
+    if (state.previous && state.previousExpiresAt && Date.now() < state.previousExpiresAt) {
+        if (provided.length === state.previous.length) {
+            const a = Buffer.from(provided);
+            const b = Buffer.from(state.previous);
+            if (timingSafeEqual(a, b))
+                return true;
+        }
+    }
+    return false;
+}
+export { PLATFORM_CONFIGS, REFRESH_AT_TTL_PERCENT, MAX_CONSECUTIVE_FAILURES, needsRefresh, getTokenHealth, handleRefreshFailure, tokenVaultKey, serializeTokens, deserializeTokens, SESSION_TOKEN_TTL_MS, SESSION_TOKEN_GRACE_MS, shouldRotateSessionToken, rotateSessionToken, validateSessionToken, };

package/dist/wizard/lib/patterns/outbound-rate-limiter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Pattern: Outbound Rate Limiter
+ *
+ * Key principles:
+ * - Token bucket per-platform with configurable capacity and refill rate
+ * - Safety margin reservation: hold back 10% of capacity for health checks
+ * - Queue overflow handling: reject with RATE_LIMITED error, don't block forever
+ * - Per-platform configuration (Meta: 200/hr, Google: 15000/day, etc.)
+ * - Exponential backoff on 429 responses from platforms
+ * - Daily quota tracking for platforms with daily limits (Google, LinkedIn)
+ *
+ * Agents: Breeze (platform relations), Wax (paid ads)
+ *
+ * PRD Reference: §9.5 (rate limit strategy), §9.17 (outbound-rate-limiter.ts)
+ */
+type AdPlatform = 'meta' | 'google' | 'tiktok' | 'linkedin' | 'twitter' | 'reddit';
+interface PlatformRateConfig {
+    platform: AdPlatform;
+    capacity: number;
+    refillRate: number;
+    dailyQuota?: number;
+    burstAllowed: boolean;
+    safetyMargin: number;
+    backoffBase: number;
+    maxRetries: number;
+}
+declare const PLATFORM_RATES: Record<AdPlatform, PlatformRateConfig>;
+declare class OutboundRateLimiter {
+    private tokens;
+    private lastRefill;
+    private dailyUsed;
+    private dailyResetAt;
+    private readonly config;
+    private readonly effectiveCapacity;
+    constructor(platform: AdPlatform);
+    /**
+     * Acquire a token. Resolves when a token is available.
+     * Throws if the daily quota is exhausted.
+     */
+    acquire(): Promise<void>;
+    /**
+     * Execute a request with automatic retry on 429 responses.
+     * Uses exponential backoff with platform-specific base delay.
+     */
+    executeWithRetry<T>(fn: () => Promise<T>): Promise<T>;
+    /** Get current rate limiter status for monitoring */
+    getStatus(): {
+        tokens: number;
+        capacity: number;
+        dailyUsed: number;
+        dailyQuota: number | undefined;
+    };
+    /** Reserve N tokens for a batch operation. Returns false if insufficient. */
+    canReserve(count: number): boolean;
+    private refill;
+    private checkDailyReset;
+    private nextMidnightUTC;
+}
+declare class RateLimitError extends Error {
+    readonly platform: string;
+    readonly retryAfterMs: number;
+    constructor(platform: string, message: string, retryAfterMs: number);
+}
+declare function isRateLimitResponse(err: unknown): boolean;
+declare function getLimiter(platform: AdPlatform): OutboundRateLimiter;
+export { OutboundRateLimiter, RateLimitError, PLATFORM_RATES, getLimiter, isRateLimitResponse };
+export type { PlatformRateConfig };