voidforge-build 23.9.1

package/dist/wizard/lib/patterns/daemon-process.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Pattern: Daemon Process (Heartbeat)
+ *
+ * Key principles:
+ * - PID file with flock to prevent concurrent instances
+ * - Unix domain socket for IPC (ADR-1: single writer)
+ * - Session token auth (rotated every 24 hours)
+ * - Graceful shutdown on SIGTERM (10s deadline)
+ * - Sleep/wake recovery with tiered catch-up
+ * - Core dumps disabled for processes holding vault keys
+ * - Log rotation: daily or at 10MB, retain 7 days
+ * - macOS: F_FULLFSYNC for financial files
+ *
+ * Agents: Dockson (treasury), Heartbeat daemon
+ *
+ * PRD Reference: §9.7, §9.18, §9.19.2, §9.20.11
+ */
+import { createServer } from 'node:net';
+declare const PID_FILE: string;
+declare const SOCKET_PATH: string;
+declare const TOKEN_FILE: string;
+declare const STATE_FILE: string;
+declare const LOG_FILE: string;
+type DaemonState = 'starting' | 'healthy' | 'degraded' | 'recovering' | 'recovery_failed' | 'shutting_down' | 'stopped';
+interface HeartbeatState {
+    pid: number;
+    state: DaemonState;
+    startedAt: string;
+    lastHeartbeat: string;
+    lastEventId: number;
+    cultivationState: string;
+    activePlatforms: string[];
+    activeCampaigns: number;
+    todaySpend: number;
+    dailyBudget: number;
+    alerts: string[];
+    tokenHealth: Record<string, {
+        status: string;
+        expiresAt: string;
+    }>;
+    lastAgentMessage?: {
+        agent: string;
+        text: string;
+        timestamp: string;
+    };
+    stablecoinBalanceCents?: number;
+    bankBalanceCents?: number;
+    runwayDays?: number;
+    fundingFrozen?: boolean;
+    pendingTransferCount?: number;
+}
+declare function writePidFile(): Promise<void>;
+declare function checkStalePid(): Promise<boolean>;
+declare function removePidFile(): Promise<void>;
+declare function generateSessionToken(): Promise<string>;
+declare function validateToken(provided: string, expected: string): boolean;
+declare function createSocketServer(sessionToken: string, handleRequest: (method: string, path: string, body: unknown, auth: {
+    hasToken: boolean;
+    vaultPassword: string;
+    totpCode: string;
+}) => Promise<{
+    status: number;
+    body: unknown;
+}>): ReturnType<typeof createServer>;
+declare function startSocketServer(server: ReturnType<typeof createServer>): Promise<void>;
+declare function writeState(state: HeartbeatState): Promise<void>;
+declare function setupSignalHandlers(cleanup: () => Promise<void>, server: ReturnType<typeof createServer>): void;
+interface ScheduledJob {
+    name: string;
+    intervalMs: number;
+    handler: () => Promise<void>;
+    lastRun: number;
+}
+declare class JobScheduler {
+    private jobs;
+    private timer;
+    private lastTick;
+    add(name: string, intervalMs: number, handler: () => Promise<void>): void;
+    start(): void;
+    stop(): void;
+    private tick;
+}
+declare function createLogger(logPath: string): {
+    log: (msg: string) => void;
+    close: () => void;
+};
+export { writePidFile, checkStalePid, removePidFile, generateSessionToken, validateToken, createSocketServer, startSocketServer, writeState, setupSignalHandlers, JobScheduler, createLogger, PID_FILE, SOCKET_PATH, TOKEN_FILE, STATE_FILE, LOG_FILE, };
+export type { DaemonState, HeartbeatState, ScheduledJob };

package/dist/wizard/lib/patterns/daemon-process.js

@@ -0,0 +1,271 @@
+/**
+ * Pattern: Daemon Process (Heartbeat)
+ *
+ * Key principles:
+ * - PID file with flock to prevent concurrent instances
+ * - Unix domain socket for IPC (ADR-1: single writer)
+ * - Session token auth (rotated every 24 hours)
+ * - Graceful shutdown on SIGTERM (10s deadline)
+ * - Sleep/wake recovery with tiered catch-up
+ * - Core dumps disabled for processes holding vault keys
+ * - Log rotation: daily or at 10MB, retain 7 days
+ * - macOS: F_FULLFSYNC for financial files
+ *
+ * Agents: Dockson (treasury), Heartbeat daemon
+ *
+ * PRD Reference: §9.7, §9.18, §9.19.2, §9.20.11
+ */
+import { createServer } from 'node:net';
+import { randomBytes } from 'node:crypto';
+import { readFile, unlink, mkdir, open, rename } from 'node:fs/promises';
+import { existsSync, createWriteStream } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+const VOIDFORGE_DIR = join(homedir(), '.voidforge');
+const RUN_DIR = join(VOIDFORGE_DIR, 'run');
+const PID_FILE = join(RUN_DIR, 'heartbeat.pid');
+const SOCKET_PATH = join(RUN_DIR, 'heartbeat.sock');
+const TOKEN_FILE = join(VOIDFORGE_DIR, 'heartbeat.token');
+const STATE_FILE = join(VOIDFORGE_DIR, 'heartbeat.json');
+const LOG_FILE = join(VOIDFORGE_DIR, 'heartbeat.log');
+// ── PID Management ────────────────────────────────────
+async function writePidFile() {
+    await mkdir(RUN_DIR, { recursive: true, mode: 0o700 });
+    const fh = await open(PID_FILE, 'w', 0o600);
+    try {
+        await fh.writeFile(String(process.pid));
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+}
+async function checkStalePid() {
+    if (!existsSync(PID_FILE))
+        return false;
+    try {
+        const pid = parseInt(await readFile(PID_FILE, 'utf-8'));
+        process.kill(pid, 0); // Check if process exists (throws if not)
+        return true; // Another daemon is alive
+    }
+    catch {
+        await unlink(PID_FILE).catch(() => { });
+        return false; // Stale PID — cleaned up
+    }
+}
+async function removePidFile() {
+    await unlink(PID_FILE).catch(() => { });
+}
+// ── Session Token ─────────────────────────────────────
+// Rotated every 24 hours (§9.19.15)
+async function generateSessionToken() {
+    const token = randomBytes(32).toString('hex');
+    await mkdir(RUN_DIR, { recursive: true, mode: 0o700 });
+    const tmpPath = TOKEN_FILE + '.tmp.' + process.pid;
+    const fh = await open(tmpPath, 'w', 0o600);
+    try {
+        await fh.writeFile(token);
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmpPath, TOKEN_FILE);
+    return token;
+}
+function validateToken(provided, expected) {
+    if (provided.length !== expected.length)
+        return false;
+    const a = Buffer.from(provided);
+    const b = Buffer.from(expected);
+    const { timingSafeEqual } = require('node:crypto');
+    return timingSafeEqual(a, b);
+}
+// ── Socket Server ─────────────────────────────────────
+// JSON-over-HTTP on Unix domain socket (§9.20.11)
+function createSocketServer(sessionToken, handleRequest) {
+    const MAX_REQUEST_SIZE = 1024 * 1024; // 1MB — R2-NIGHTWING-003: enforce during streaming
+    const server = createServer(async (conn) => {
+        let data = '';
+        let rejected = false;
+        conn.on('data', (chunk) => {
+            data += chunk.toString();
+            if (data.length > MAX_REQUEST_SIZE && !rejected) {
+                rejected = true;
+                conn.write('HTTP/1.1 413 Payload Too Large\r\nContent-Type: application/json\r\n\r\n{"ok":false,"error":"Request too large"}');
+                conn.end();
+            }
+        });
+        conn.on('end', async () => {
+            try {
+                // Parse HTTP-like request from the socket
+                const lines = data.split('\r\n');
+                const [method, path] = (lines[0] || 'GET /').split(' ');
+                // Extract auth headers — pass VALUES, not just presence (SEC-001 fix)
+                const authHeader = lines.find(l => l.toLowerCase().startsWith('authorization:'));
+                const token = authHeader ? authHeader.split(' ').pop() || '' : '';
+                const hasToken = validateToken(token, sessionToken);
+                const vaultHeader = lines.find(l => l.toLowerCase().startsWith('x-vault-password:'));
+                const vaultPassword = vaultHeader ? vaultHeader.substring(vaultHeader.indexOf(':') + 1).trim() : '';
+                const totpHeader = lines.find(l => l.toLowerCase().startsWith('x-totp-code:'));
+                const totpCode = totpHeader ? totpHeader.substring(totpHeader.indexOf(':') + 1).trim() : '';
+                // Parse body (after blank line)
+                const bodyStart = data.indexOf('\r\n\r\n');
+                if (rejected)
+                    return; // Already rejected during streaming
+                const body = bodyStart >= 0 ? JSON.parse(data.substring(bodyStart + 4) || '{}') : {};
+                const result = await handleRequest(method, path, body, {
+                    hasToken,
+                    vaultPassword, // Actual value for verification by handler
+                    totpCode, // Actual value for verification by handler
+                });
+                conn.write(`HTTP/1.1 ${result.status} OK\r\nContent-Type: application/json\r\n\r\n${JSON.stringify(result.body)}`);
+            }
+            catch (err) {
+                conn.write(`HTTP/1.1 500 Error\r\nContent-Type: application/json\r\n\r\n${JSON.stringify({ ok: false, error: 'Internal error' })}`);
+            }
+            conn.end();
+        });
+    });
+    return server;
+}
+async function startSocketServer(server) {
+    // Clean up stale socket
+    if (existsSync(SOCKET_PATH)) {
+        try {
+            const { connect } = require('node:net');
+            const testConn = connect(SOCKET_PATH);
+            await new Promise((resolve, reject) => {
+                testConn.on('connect', () => { testConn.destroy(); reject(new Error('Another daemon is running')); });
+                testConn.on('error', () => { resolve(); }); // ECONNREFUSED = stale socket
+            });
+            await unlink(SOCKET_PATH);
+        }
+        catch (err) {
+            if (err.message === 'Another daemon is running')
+                throw err;
+        }
+    }
+    await new Promise((resolve, reject) => {
+        server.listen(SOCKET_PATH, () => {
+            // Set socket permissions (§9.18)
+            require('node:fs').chmodSync(SOCKET_PATH, 0o600);
+            resolve();
+        });
+        server.on('error', reject);
+    });
+}
+// ── State File ────────────────────────────────────────
+async function writeState(state) {
+    const tmpPath = STATE_FILE + '.tmp.' + process.pid;
+    const fh = await open(tmpPath, 'w');
+    try {
+        await fh.writeFile(JSON.stringify(state, null, 2));
+        if (platform() === 'darwin') {
+            await fh.datasync(); // Best-effort on macOS; see §9.18 F_FULLFSYNC caveat
+        }
+        else {
+            await fh.sync();
+        }
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmpPath, STATE_FILE);
+}
+// ── Signal Handling ───────────────────────────────────
+function setupSignalHandlers(cleanup, server) {
+    let shuttingDown = false;
+    async function shutdown(signal) {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        // 10-second deadline for in-flight requests
+        const deadline = setTimeout(() => {
+            process.exit(1);
+        }, 10000);
+        try {
+            server.close();
+            await cleanup();
+            await removePidFile();
+            await unlink(SOCKET_PATH).catch(() => { });
+            clearTimeout(deadline);
+            process.exit(0);
+        }
+        catch {
+            clearTimeout(deadline);
+            process.exit(1);
+        }
+    }
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    // Disable core dumps — vault key in memory (§9.18)
+    try {
+        // @ts-expect-error — setrlimit not in Node.js types
+        if (process.setrlimit)
+            process.setrlimit('core', { soft: 0, hard: 0 });
+    }
+    catch { /* not available on all platforms */ }
+}
+class JobScheduler {
+    jobs = [];
+    timer = null;
+    lastTick = Date.now();
+    add(name, intervalMs, handler) {
+        this.jobs.push({ name, intervalMs, handler, lastRun: 0 });
+    }
+    start() {
+        this.lastTick = Date.now();
+        this.timer = setInterval(() => this.tick(), 1000);
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+    }
+    async tick() {
+        const now = Date.now();
+        const delta = now - this.lastTick;
+        this.lastTick = now;
+        // Sleep/wake detection (§9.18): if delta > 2x expected (2s), catch-up mode
+        if (delta > 2000) {
+            // Stagger overdue jobs over 5 minutes, prioritize token refresh
+            const overdue = this.jobs.filter(j => now - j.lastRun > j.intervalMs);
+            const sorted = overdue.sort((a, b) => {
+                if (a.name.includes('token'))
+                    return -1;
+                if (b.name.includes('token'))
+                    return 1;
+                return 0;
+            });
+            for (const job of sorted) {
+                try {
+                    await job.handler();
+                }
+                catch { /* logged by handler */ }
+                job.lastRun = now;
+            }
+            return;
+        }
+        // Normal tick: run due jobs
+        for (const job of this.jobs) {
+            if (now - job.lastRun >= job.intervalMs) {
+                try {
+                    await job.handler();
+                }
+                catch { /* logged by handler */ }
+                job.lastRun = now;
+            }
+        }
+    }
+}
+// ── Log Rotation ──────────────────────────────────────
+function createLogger(logPath) {
+    let stream = createWriteStream(logPath, { flags: 'a' });
+    return {
+        log(msg) {
+            stream.write(JSON.stringify({ ts: new Date().toISOString(), msg }) + '\n');
+        },
+        close() { stream.end(); }
+    };
+}
+export { writePidFile, checkStalePid, removePidFile, generateSessionToken, validateToken, createSocketServer, startSocketServer, writeState, setupSignalHandlers, JobScheduler, createLogger, PID_FILE, SOCKET_PATH, TOKEN_FILE, STATE_FILE, LOG_FILE, };

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

@@ -0,0 +1,171 @@
+/**
+ * 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;
+/**
+ * Get treasury directory for a project, or the global default.
+ * Per-project: {projectDir}/cultivation/treasury/
+ * Global (no arg): ~/.voidforge/treasury/
+ */
+declare function getTreasuryDir(projectDir?: string): string;
+declare function getSpendLog(projectDir?: string): string;
+declare function getRevenueLog(projectDir?: string): string;
+declare function getPendingOps(projectDir?: string): string;
+declare function getBudgetsFile(projectDir?: string): 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, getTreasuryDir, getSpendLog, getRevenueLog, getPendingOps, getBudgetsFile, };

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

@@ -0,0 +1,154 @@
+/**
+ * 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
+// Global treasury paths — used by vault, totp, and backup (which stay user-scoped).
+// Per-project code should use getTreasuryDir(projectDir) and derived path functions.
+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');
+/**
+ * Get treasury directory for a project, or the global default.
+ * Per-project: {projectDir}/cultivation/treasury/
+ * Global (no arg): ~/.voidforge/treasury/
+ */
+function getTreasuryDir(projectDir) {
+    return projectDir ? join(projectDir, 'cultivation', 'treasury') : TREASURY_DIR;
+}
+function getSpendLog(projectDir) {
+    return join(getTreasuryDir(projectDir), 'spend-log.jsonl');
+}
+function getRevenueLog(projectDir) {
+    return join(getTreasuryDir(projectDir), 'revenue-log.jsonl');
+}
+function getPendingOps(projectDir) {
+    return join(getTreasuryDir(projectDir), 'pending-ops.jsonl');
+}
+function getBudgetsFile(projectDir) {
+    return join(getTreasuryDir(projectDir), '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, getTreasuryDir, getSpendLog, getRevenueLog, getPendingOps, getBudgetsFile, };