thevoidforge 21.0.0

package/dist/wizard/lib/reconciliation.js

@@ -0,0 +1,173 @@
+/**
+ * Reconciliation Engine — Two-pass financial reconciliation (§9.17).
+ *
+ * Compares VoidForge's recorded spend/revenue against platform-reported values.
+ * Runs daily: preliminary at midnight UTC, authoritative at 06:00 UTC.
+ *
+ * PRD Reference: §9.4 (reconciliation), §9.9 (ReconciliationReport), §9.17 (two-pass)
+ */
+import { readFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { atomicWrite, SPEND_LOG, REVENUE_LOG, TREASURY_DIR } from './financial-core.js';
+// ── Threshold Configuration (§9.17) ───────────────────
+const DISCREPANCY_IGNORE_THRESHOLD = 500; // $5 — timing noise
+const DISCREPANCY_ALERT_PERCENT = 5; // 5% relative threshold
+const DISCREPANCY_ALWAYS_ALERT = 5000; // $50 — always alert
+const TREND_DAYS = 7; // 7-day trend detection
+const TREND_THRESHOLD_PERCENT = 3; // 3-4% consistent discrepancy
+async function readSpendLogForDate(date) {
+    const platformTotals = new Map();
+    if (!existsSync(SPEND_LOG))
+        return platformTotals;
+    const content = await readFile(SPEND_LOG, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            if (!entry.data.timestamp.startsWith(date))
+                continue;
+            if (entry.data.action !== 'spend_check' && entry.data.action !== 'spend_execute')
+                continue;
+            const current = platformTotals.get(entry.data.platform) ?? 0;
+            platformTotals.set(entry.data.platform, (current + entry.data.amount));
+        }
+        catch { /* malformed line — skip */ }
+    }
+    return platformTotals;
+}
+async function readRevenueLogForDate(date) {
+    const sourceTotals = new Map();
+    if (!existsSync(REVENUE_LOG))
+        return sourceTotals;
+    const content = await readFile(REVENUE_LOG, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            if (!entry.data.timestamp.startsWith(date))
+                continue;
+            const current = sourceTotals.get(entry.data.source) ?? 0;
+            sourceTotals.set(entry.data.source, (current + entry.data.amount));
+        }
+        catch { /* malformed line */ }
+    }
+    return sourceTotals;
+}
+// ── Discrepancy Classification ────────────────────────
+function classifyDiscrepancy(recorded, reported) {
+    const diff = Math.abs(recorded - reported);
+    // Ignore <$5 (timing noise)
+    if (diff < DISCREPANCY_IGNORE_THRESHOLD)
+        return 'matched';
+    // Always alert >$50
+    if (diff >= DISCREPANCY_ALWAYS_ALERT)
+        return 'discrepancy';
+    // Alert on >5% relative discrepancy
+    const base = Math.max(recorded, reported, 1); // avoid division by zero
+    const percent = (diff / base) * 100;
+    if (percent >= DISCREPANCY_ALERT_PERCENT)
+        return 'discrepancy';
+    return 'matched';
+}
+// ── Main Reconciliation Function ──────────────────────
+export async function runReconciliation(projectId, date, type, platformSpendReports, // Platform-reported spend per platform
+revenueSourceReports) {
+    // Read VoidForge's own logs for this date
+    const vfSpend = await readSpendLogForDate(date);
+    const vfRevenue = await readRevenueLogForDate(date);
+    const alerts = [];
+    // ── Reconcile Spend ──────────────────
+    const spendResults = [];
+    const allPlatforms = new Set([...vfSpend.keys(), ...platformSpendReports.keys()]);
+    for (const platform of allPlatforms) {
+        const recorded = vfSpend.get(platform) ?? 0;
+        const reported = platformSpendReports.get(platform);
+        if (reported === undefined) {
+            spendResults.push({
+                platform: platform,
+                voidforgeRecorded: recorded,
+                platformReported: 0,
+                discrepancy: recorded,
+                status: 'unavailable',
+            });
+            alerts.push(`${platform}: platform data unavailable. Using VoidForge recorded spend + daily cap as worst-case estimate.`);
+            continue;
+        }
+        const discrepancy = Math.abs(recorded - reported);
+        const status = classifyDiscrepancy(recorded, reported);
+        spendResults.push({
+            platform: platform,
+            voidforgeRecorded: recorded,
+            platformReported: reported,
+            discrepancy,
+            status,
+        });
+        if (status === 'discrepancy' && type === 'final') {
+            alerts.push(`Reconciliation discrepancy: ${platform} reports $${(reported / 100).toFixed(2)} spent, ` +
+                `VoidForge recorded $${(recorded / 100).toFixed(2)} — $${(discrepancy / 100).toFixed(2)} difference`);
+        }
+    }
+    // ── Reconcile Revenue ────────────────
+    const revenueResults = [];
+    const allSources = new Set([...vfRevenue.keys(), ...revenueSourceReports.keys()]);
+    for (const source of allSources) {
+        const recorded = vfRevenue.get(source) ?? 0;
+        const reported = revenueSourceReports.get(source);
+        if (reported === undefined) {
+            revenueResults.push({
+                source: source,
+                recorded,
+                reported: 0,
+                discrepancy: recorded,
+                status: 'unavailable',
+            });
+            continue;
+        }
+        const discrepancy = Math.abs(recorded - reported);
+        const status = classifyDiscrepancy(recorded, reported);
+        revenueResults.push({
+            source: source,
+            recorded,
+            reported,
+            discrepancy,
+            status,
+        });
+        if (status === 'discrepancy' && type === 'final') {
+            alerts.push(`Revenue discrepancy: ${source} reports $${(reported / 100).toFixed(2)}, ` +
+                `VoidForge recorded $${(recorded / 100).toFixed(2)}`);
+        }
+    }
+    // ── Calculate Aggregates ─────────────
+    const totalRevenue = revenueResults.reduce((sum, r) => sum + (r.reported || r.recorded), 0);
+    const totalSpend = spendResults.reduce((sum, s) => sum + (s.platformReported || s.voidforgeRecorded), 0);
+    const netPosition = (totalRevenue - totalSpend);
+    const blendedRoas = totalSpend > 0 ? (totalRevenue / totalSpend) : 0;
+    // ── Build Report ─────────────────────
+    const report = {
+        id: randomUUID(),
+        date,
+        type,
+        projectId,
+        spend: spendResults,
+        revenue: revenueResults,
+        netPosition,
+        blendedRoas,
+        alerts,
+    };
+    // ── Write Report ─────────────────────
+    const reportDir = join(TREASURY_DIR, 'reconciliation');
+    await mkdir(reportDir, { recursive: true });
+    const reportPath = join(reportDir, `${date}.json`);
+    await atomicWrite(reportPath, JSON.stringify(report, null, 2));
+    return report;
+}
+// ── Currency Enforcement (ADR-6) ──────────────────────
+export function enforceCurrency(currency, platform) {
+    if (currency !== 'USD') {
+        throw new Error(`This ${platform} account uses ${currency}. VoidForge v11.x requires USD. ` +
+            `Change the account currency in the ${platform} dashboard, ` +
+            `or wait for multi-currency support (planned post-v11.3).`);
+    }
+}

package/dist/wizard/lib/revenue-types.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Revenue types — re-exports from the revenue-source-adapter pattern for wizard runtime use.
+ * ARCH-R2-012: Production code should not import from docs/patterns/ directly.
+ */
+export type { RevenueSourceAdapter, RevenueCredentials, ConnectionResult, TransactionPage, BalanceResult, DateRange } from './patterns/revenue-source-adapter.js';

package/dist/wizard/lib/revenue-types.js

@@ -0,0 +1 @@
+export {};

package/dist/wizard/lib/route-optimizer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Paris's Route Optimizer — ROI-weighted campaign sequencing (v12.3).
+ *
+ * Given multiple possible campaigns (from the proposal generator), Paris
+ * computes the optimal execution order based on estimated ROI, dependencies,
+ * risk, and urgency.
+ *
+ * PRD Reference: ROADMAP v12.3, DEEP_CURRENT.md Paris's role
+ */
+import type { CampaignProposal } from './campaign-proposer.js';
+import type { SituationModel } from './deep-current.js';
+interface RouteScore {
+    proposal: CampaignProposal;
+    roiScore: number;
+    urgencyScore: number;
+    riskScore: number;
+    totalScore: number;
+}
+/**
+ * Score and rank campaign proposals by optimal execution order.
+ * Returns proposals sorted by total score (highest first = execute first).
+ */
+export declare function optimizeRoute(proposals: CampaignProposal[], model: SituationModel): RouteScore[];
+/**
+ * Pick the single best campaign to execute next.
+ */
+export declare function pickBestCampaign(proposals: CampaignProposal[], model: SituationModel): CampaignProposal | null;
+export type { RouteScore };

package/dist/wizard/lib/route-optimizer.js

@@ -0,0 +1,93 @@
+/**
+ * Paris's Route Optimizer — ROI-weighted campaign sequencing (v12.3).
+ *
+ * Given multiple possible campaigns (from the proposal generator), Paris
+ * computes the optimal execution order based on estimated ROI, dependencies,
+ * risk, and urgency.
+ *
+ * PRD Reference: ROADMAP v12.3, DEEP_CURRENT.md Paris's role
+ */
+// ── Scoring Weights ───────────────────────────────────
+const WEIGHTS = {
+    roi: 0.40,
+    urgency: 0.35,
+    risk: 0.25, // Inverted — lower risk gets higher score
+};
+// ── ROI Estimation ────────────────────────────────────
+function estimateRoi(proposal, model) {
+    // ROI = (dimension improvement potential) / (estimated effort)
+    const currentScore = proposal.dimensionScore;
+    const potentialGain = Math.min(30, 100 - currentScore); // Cap at 30-point improvement
+    const effort = proposal.estimatedSessions;
+    // Higher gain per session = higher ROI
+    const roiRatio = potentialGain / Math.max(effort, 1);
+    return Math.min(100, Math.round(roiRatio * 10)); // Scale to 0-100
+}
+// ── Urgency Scoring ───────────────────────────────────
+function scoreUrgency(proposal, model) {
+    const dim = proposal.dimension;
+    const score = proposal.dimensionScore;
+    // Critical defects are always urgent
+    if (dim === 'quality' && score < 30)
+        return 100;
+    // Security issues are urgent
+    if (dim === 'performance' && model.lastSiteScan && !model.lastSiteScan.security.https)
+        return 90;
+    // Low scores are more urgent
+    if (score < 20)
+        return 80;
+    if (score < 40)
+        return 60;
+    if (score < 60)
+        return 40;
+    // Revenue is urgent for OPERATING projects
+    if (dim === 'revenuePotential' && model.projectState === 'OPERATING')
+        return 70;
+    return 20; // Low urgency by default
+}
+// ── Risk Scoring ──────────────────────────────────────
+function scoreRisk(proposal) {
+    // Revenue/payment campaigns are higher risk (real money)
+    if (proposal.dimension === 'revenuePotential')
+        return 70;
+    // Feature campaigns have moderate risk (new code)
+    if (proposal.dimension === 'featureCompleteness')
+        return 50;
+    // Quality and performance campaigns are low risk
+    if (proposal.dimension === 'quality')
+        return 20;
+    if (proposal.dimension === 'performance')
+        return 25;
+    // Growth foundation is low risk (additive, no existing code modified)
+    if (proposal.dimension === 'growthReadiness')
+        return 30;
+    return 40;
+}
+// ── Route Optimization ────────────────────────────────
+/**
+ * Score and rank campaign proposals by optimal execution order.
+ * Returns proposals sorted by total score (highest first = execute first).
+ */
+export function optimizeRoute(proposals, model) {
+    const scored = proposals.map(proposal => {
+        const roiScore = estimateRoi(proposal, model);
+        const urgencyScore = scoreUrgency(proposal, model);
+        const riskScore = 100 - scoreRisk(proposal); // Invert: low risk = high score
+        const totalScore = Math.round(roiScore * WEIGHTS.roi +
+            urgencyScore * WEIGHTS.urgency +
+            riskScore * WEIGHTS.risk);
+        return { proposal, roiScore, urgencyScore, riskScore, totalScore };
+    });
+    // Sort by total score descending (best first)
+    scored.sort((a, b) => b.totalScore - a.totalScore);
+    return scored;
+}
+/**
+ * Pick the single best campaign to execute next.
+ */
+export function pickBestCampaign(proposals, model) {
+    if (proposals.length === 0)
+        return null;
+    const ranked = optimizeRoute(proposals, model);
+    return ranked[0].proposal;
+}

package/dist/wizard/lib/s3-deploy.d.ts

@@ -0,0 +1,19 @@
+/**
+ * S3 deploy — upload build directory to S3 bucket via SDK.
+ * No AWS CLI dependency (ADR-014). Uses @aws-sdk/client-s3 already in project.
+ */
+import type { ProvisionEmitter } from './provisioners/types.js';
+export interface S3DeployResult {
+    success: boolean;
+    deployUrl?: string;
+    filesUploaded?: number;
+    error?: string;
+}
+/**
+ * Upload all files from a build directory to an S3 bucket.
+ * Deletes stale files that no longer exist in the build directory.
+ */
+export declare function s3Deploy(bucket: string, buildDir: string, region: string, credentials: {
+    accessKeyId: string;
+    secretAccessKey: string;
+}, websiteUrl: string, emit: ProvisionEmitter): Promise<S3DeployResult>;

package/dist/wizard/lib/s3-deploy.js

@@ -0,0 +1,156 @@
+/**
+ * S3 deploy — upload build directory to S3 bucket via SDK.
+ * No AWS CLI dependency (ADR-014). Uses @aws-sdk/client-s3 already in project.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, extname, relative } from 'node:path';
+/** MIME type mapping for common static site file types. */
+const MIME_TYPES = {
+    '.html': 'text/html',
+    '.css': 'text/css',
+    '.js': 'application/javascript',
+    '.mjs': 'application/javascript',
+    '.json': 'application/json',
+    '.xml': 'text/xml',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.eot': 'application/vnd.ms-fontobject',
+    '.otf': 'font/otf',
+    '.txt': 'text/plain',
+    '.map': 'application/json',
+    '.webmanifest': 'application/manifest+json',
+};
+function getMimeType(filePath) {
+    return MIME_TYPES[extname(filePath).toLowerCase()] || 'application/octet-stream';
+}
+/** Cache control: immutable for hashed assets, revalidate for HTML/SW. */
+function getCacheControl(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    if (ext === '.html' || filePath.endsWith('sw.js') || filePath.endsWith('manifest.json') || filePath.endsWith('.webmanifest')) {
+        return 'public, max-age=0, must-revalidate';
+    }
+    return 'public, max-age=31536000, immutable';
+}
+/** Recursively list all files in a directory. */
+async function walkDir(dir) {
+    const files = [];
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...await walkDir(full));
+        }
+        else if (entry.isFile()) {
+            files.push(full);
+        }
+    }
+    return files;
+}
+/**
+ * Upload all files from a build directory to an S3 bucket.
+ * Deletes stale files that no longer exist in the build directory.
+ */
+export async function s3Deploy(bucket, buildDir, region, credentials, websiteUrl, emit) {
+    // Dynamic import of AWS SDK
+    let S3Client;
+    let s3Commands;
+    try {
+        const s3Mod = await import('@aws-sdk/client-s3');
+        S3Client = s3Mod.S3Client;
+        s3Commands = s3Mod;
+    }
+    catch {
+        emit({ step: 's3-deploy', status: 'error', message: 'AWS SDK not installed. Run: npm install @aws-sdk/client-s3' });
+        return { success: false, error: 'AWS SDK not installed' };
+    }
+    const s3 = new S3Client({ region, credentials });
+    // Step 1: Validate build directory exists
+    emit({ step: 's3-deploy', status: 'started', message: `Uploading ${buildDir} to s3://${bucket}` });
+    try {
+        const dirStat = await stat(buildDir);
+        if (!dirStat.isDirectory()) {
+            emit({ step: 's3-deploy', status: 'error', message: `Build directory "${buildDir}" is not a directory` });
+            return { success: false, error: 'Build directory is not a directory' };
+        }
+    }
+    catch {
+        emit({ step: 's3-deploy', status: 'error', message: `Build directory "${buildDir}" does not exist. Run your build command first (e.g., npm run build).` });
+        return { success: false, error: 'Build directory does not exist' };
+    }
+    // Step 2: List local files
+    const localFiles = await walkDir(buildDir);
+    if (localFiles.length === 0) {
+        emit({ step: 's3-deploy', status: 'error', message: `Build directory "${buildDir}" is empty` });
+        return { success: false, error: 'Build directory is empty' };
+    }
+    // Step 3: Upload all files
+    let uploaded = 0;
+    const localKeys = new Set();
+    for (const filePath of localFiles) {
+        const key = relative(buildDir, filePath).replace(/\\/g, '/'); // Windows compat
+        localKeys.add(key);
+        try {
+            const body = await readFile(filePath);
+            await s3.send(new s3Commands.PutObjectCommand({
+                Bucket: bucket,
+                Key: key,
+                Body: body,
+                ContentType: getMimeType(filePath),
+                CacheControl: getCacheControl(filePath),
+            }));
+            uploaded++;
+        }
+        catch (err) {
+            emit({ step: 's3-deploy', status: 'error', message: `Failed to upload ${key}`, detail: err.message });
+            return { success: false, error: `Upload failed for ${key}: ${err.message}` };
+        }
+        // Progress every 20 files
+        if (uploaded % 20 === 0) {
+            emit({ step: 's3-deploy', status: 'started', message: `Uploaded ${uploaded}/${localFiles.length} files...` });
+        }
+    }
+    // Step 4: Delete stale files from S3
+    emit({ step: 's3-cleanup', status: 'started', message: 'Removing stale files from S3' });
+    try {
+        let deleted = 0;
+        let continuationToken;
+        do {
+            const listRes = await s3.send(new s3Commands.ListObjectsV2Command({
+                Bucket: bucket,
+                ContinuationToken: continuationToken,
+            }));
+            const staleKeys = (listRes.Contents ?? [])
+                .map(obj => obj.Key)
+                .filter(key => !localKeys.has(key));
+            if (staleKeys.length > 0) {
+                await s3.send(new s3Commands.DeleteObjectsCommand({
+                    Bucket: bucket,
+                    Delete: { Objects: staleKeys.map(Key => ({ Key })) },
+                }));
+                deleted += staleKeys.length;
+            }
+            continuationToken = listRes.IsTruncated ? listRes.NextContinuationToken : undefined;
+        } while (continuationToken);
+        if (deleted > 0) {
+            emit({ step: 's3-cleanup', status: 'done', message: `Removed ${deleted} stale files` });
+        }
+        else {
+            emit({ step: 's3-cleanup', status: 'done', message: 'No stale files to remove' });
+        }
+    }
+    catch (err) {
+        emit({ step: 's3-cleanup', status: 'error', message: 'Failed to clean stale files', detail: err.message });
+        // Non-fatal — upload succeeded
+    }
+    emit({ step: 's3-deploy', status: 'done', message: `Uploaded ${uploaded} files to s3://${bucket}` });
+    return { success: true, deployUrl: websiteUrl, filesUploaded: uploaded };
+}

package/dist/wizard/lib/safety-tiers.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Safety Tier Schema — Budget authorization and spend control.
+ *
+ * Half-open intervals for budget tiers (§9.17):
+ *   [0, 2500) cents/day: auto-approve (ongoing spend only — new campaigns need vault password)
+ *   [2500, 10000) cents/day: agent approval (Dockson + Steris)
+ *   [10000, 50000) cents/day: human confirmation + TOTP
+ *   >= 50000 cents/day: hard stop + TOTP + vault password
+ *
+ * Aggregate auto-approve limit: $100/day across all campaigns (§9.17)
+ * Hard stop buffer: platform cap set 10% below VoidForge hard stop (§9.17)
+ *
+ * Campaign creation rate limits (§9.19.14 + §9.20.3d):
+ *   Max 5 daemon-initiated campaigns per 24h
+ *   Max 10 active campaigns per platform
+ *   Burst detection: >3 within 15 minutes → pause and alert
+ *
+ * PRD Reference: §9.4, §9.17, §9.19.5, §9.19.14, §9.20.5
+ */
+type Cents = number & {
+    readonly __brand: 'Cents';
+};
+type SafetyTier = 'auto_approve' | 'agent_approve' | 'human_confirm' | 'hard_stop';
+interface SafetyTierConfig {
+    autoApproveBelow: Cents;
+    agentApproveBelow: Cents;
+    humanConfirmBelow: Cents;
+    hardStopAbove: Cents;
+    aggregateAutoApproveMax: Cents;
+    hardStopBuffer: number;
+}
+declare const DEFAULT_TIERS: SafetyTierConfig;
+interface TierResult {
+    tier: SafetyTier;
+    requiresVaultPassword: boolean;
+    requiresTotp: boolean;
+    reason: string;
+}
+/**
+ * Classify a daily budget amount into its safety tier.
+ * Also considers aggregate spend across all campaigns.
+ */
+declare function classifyTier(dailyBudget: Cents, aggregateDailySpend: Cents, config?: SafetyTierConfig): TierResult;
+/**
+ * Calculate the platform-level daily cap (10% below VoidForge hard stop).
+ * This is set on the ad platform side so the platform enforces the cap
+ * even if VoidForge crashes.
+ */
+declare function platformDailyCap(config?: SafetyTierConfig): Cents;
+interface RateLimitConfig {
+    maxPerDay: number;
+    maxActivePerPlatform: number;
+    burstThreshold: number;
+    burstWindowMs: number;
+}
+declare const DEFAULT_RATE_LIMITS: RateLimitConfig;
+interface RateLimitState {
+    creationsToday: number;
+    creationTimestamps: number[];
+    activeCampaignsByPlatform: Record<string, number>;
+}
+interface RateLimitResult {
+    allowed: boolean;
+    reason?: string;
+    burst?: boolean;
+}
+/**
+ * Check if a campaign creation is allowed by rate limits.
+ * Only applies to daemon-initiated creation (Tier 1/3).
+ * Human-triggered /grow Phase 4 is exempt (§9.20.3d).
+ */
+declare function checkCreationRateLimit(state: RateLimitState, platform: string, isDaemonInitiated: boolean, config?: RateLimitConfig): RateLimitResult;
+type AutonomousAction = 'pause_campaign' | 'kill_campaign' | 'evaluate_ab_test' | 'rebalance_budget' | 'generate_report' | 'refresh_token' | 'create_campaign' | 'resume_campaign' | 'increase_budget' | 'unfreeze' | 'modify_code';
+declare function isAutonomouslyAllowed(action: AutonomousAction): boolean;
+export type { SafetyTierConfig, TierResult, RateLimitConfig, RateLimitState, RateLimitResult, AutonomousAction, Cents };
+export { DEFAULT_TIERS, DEFAULT_RATE_LIMITS, classifyTier, platformDailyCap, checkCreationRateLimit, isAutonomouslyAllowed };