paracosm 0.4.346 → 0.4.377

package/dist/cli/rate-limiter.js

@@ -0,0 +1,193 @@
+/**
+ * IP-based rate limiter with optional JSON-file persistence.
+ *
+ * Extracted from server-app.ts so the quota machinery can be unit-tested
+ * without spinning up the whole HTTP server and so createMarsServer reads
+ * more like a route file. Behavior is unchanged.
+ *
+ * Three buckets keyed by IP:
+ *   - simStore / maxPerDay:        /setup (most expensive action, daily)
+ *   - compileStore / maxCompilePerDay: /compile (~$0.10 per call, daily)
+ *   - chatStore / maxChatPerHour:  /chat (hourly, users legitimately
+ *                                  burst but scripts/loops flatten the
+ *                                  budget if unlimited)
+ *
+ * When a persistencePath is supplied, state is loaded on construct and
+ * flushed on every mutation via a 500ms-debounced atomic write
+ * (tmp + rename). pm2 restarts preserve user quotas. Missing or corrupt
+ * files self-heal at next mutation.
+ *
+ * @module paracosm/cli/rate-limiter
+ */
+import { readFileSync, existsSync, writeFileSync, renameSync } from 'node:fs';
+export class IpRateLimiter {
+    simStore = new Map();
+    compileStore = new Map();
+    chatStore = new Map();
+    maxPerDay;
+    maxCompilePerDay;
+    maxChatPerHour;
+    cleanupTimer;
+    persistencePath = null;
+    persistTimer = null;
+    constructor(maxPerDay = 3, maxCompilePerDay = 5, maxChatPerHour = 200, persistencePath = null) {
+        this.maxPerDay = maxPerDay;
+        this.maxCompilePerDay = maxCompilePerDay;
+        this.maxChatPerHour = maxChatPerHour;
+        this.persistencePath = persistencePath;
+        this.cleanupTimer = setInterval(() => this.cleanup(), 60 * 60 * 1000);
+        this.load();
+    }
+    /** Load persisted state from disk. Silently tolerates missing/corrupt files. */
+    load() {
+        if (!this.persistencePath)
+            return;
+        try {
+            if (!existsSync(this.persistencePath))
+                return;
+            const raw = readFileSync(this.persistencePath, 'utf-8');
+            const data = JSON.parse(raw);
+            const now = Date.now();
+            const hydrate = (store, src) => {
+                if (!src)
+                    return;
+                for (const [ip, entry] of Object.entries(src)) {
+                    if (entry?.resetAt && entry.resetAt > now)
+                        store.set(ip, entry);
+                }
+            };
+            hydrate(this.simStore, data.sim);
+            hydrate(this.compileStore, data.compile);
+            hydrate(this.chatStore, data.chat);
+        }
+        catch {
+            // Missing file, permission denied, corrupt JSON — start fresh.
+        }
+    }
+    /** Debounced flush to disk. Writes atomically via tmp+rename. */
+    persist() {
+        if (!this.persistencePath)
+            return;
+        if (this.persistTimer)
+            return;
+        this.persistTimer = setTimeout(() => {
+            this.persistTimer = null;
+            if (!this.persistencePath)
+                return;
+            try {
+                const dump = (s) => {
+                    const out = {};
+                    for (const [ip, e] of s)
+                        out[ip] = e;
+                    return out;
+                };
+                const payload = JSON.stringify({
+                    sim: dump(this.simStore),
+                    compile: dump(this.compileStore),
+                    chat: dump(this.chatStore),
+                });
+                const tmp = `${this.persistencePath}.tmp`;
+                writeFileSync(tmp, payload, 'utf-8');
+                renameSync(tmp, this.persistencePath);
+            }
+            catch {
+                // Disk full, permission denied — swallow; logs would be noisy.
+            }
+        }, 500);
+    }
+    /** Extract client IP, respecting reverse proxy headers (nginx, Cloudflare, etc.) */
+    static getIp(req) {
+        const xff = req.headers['x-forwarded-for'];
+        if (xff) {
+            const first = (Array.isArray(xff) ? xff[0] : xff).split(',')[0].trim();
+            if (first)
+                return first;
+        }
+        const realIp = req.headers['x-real-ip'];
+        if (realIp)
+            return Array.isArray(realIp) ? realIp[0] : realIp;
+        const cfIp = req.headers['cf-connecting-ip'];
+        if (cfIp)
+            return Array.isArray(cfIp) ? cfIp[0] : cfIp;
+        return req.socket.remoteAddress || 'unknown';
+    }
+    nextReset(kind) {
+        if (kind === 'daily') {
+            const tomorrow = new Date();
+            tomorrow.setUTCHours(24, 0, 0, 0);
+            return tomorrow.getTime();
+        }
+        const nextHour = new Date();
+        nextHour.setUTCMinutes(60, 0, 0);
+        return nextHour.getTime();
+    }
+    bump(store, ip, limit, kind, mutate) {
+        const now = Date.now();
+        let entry = store.get(ip);
+        let mutated = false;
+        if (!entry || now >= entry.resetAt) {
+            entry = { count: 0, resetAt: this.nextReset(kind) };
+            store.set(ip, entry);
+            mutated = true;
+        }
+        const allowed = entry.count < limit;
+        if (allowed && mutate) {
+            entry.count++;
+            mutated = true;
+        }
+        const remaining = Math.max(0, limit - entry.count);
+        if (mutated)
+            this.persist();
+        return { allowed, remaining, resetAt: entry.resetAt, limit };
+    }
+    /** Check the simulation-per-day quota without consuming it. */
+    check(ip) {
+        return this.bump(this.simStore, ip, this.maxPerDay, 'daily', false);
+    }
+    /** Record a simulation start. Prefer `check` + `record` for legacy callers. */
+    record(ip) {
+        const entry = this.simStore.get(ip);
+        if (entry) {
+            entry.count++;
+            this.persist();
+        }
+    }
+    /** Check AND consume a slot for /compile (daily bucket, ~$0.10/call). */
+    consumeCompile(ip) {
+        return this.bump(this.compileStore, ip, this.maxCompilePerDay, 'daily', true);
+    }
+    /** Check AND consume a slot for /chat (hourly bucket). */
+    consumeChat(ip) {
+        return this.bump(this.chatStore, ip, this.maxChatPerHour, 'hourly', true);
+    }
+    /** Get stats for monitoring endpoints. */
+    stats() {
+        const dump = (s) => [...s.entries()].map(([ip, e]) => ({ ip, count: e.count, resetAt: new Date(e.resetAt).toISOString() }));
+        return {
+            totalIps: this.simStore.size + this.compileStore.size + this.chatStore.size,
+            sim: dump(this.simStore),
+            compile: dump(this.compileStore),
+            chat: dump(this.chatStore),
+        };
+    }
+    cleanup() {
+        const now = Date.now();
+        let mutated = false;
+        for (const store of [this.simStore, this.compileStore, this.chatStore]) {
+            for (const [ip, entry] of store) {
+                if (now >= entry.resetAt) {
+                    store.delete(ip);
+                    mutated = true;
+                }
+            }
+        }
+        if (mutated)
+            this.persist();
+    }
+    destroy() {
+        clearInterval(this.cleanupTimer);
+        if (this.persistTimer)
+            clearTimeout(this.persistTimer);
+    }
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/cli/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/cli/rate-limiter.ts"],"names":[],"mappings":"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"}

package/dist/cli/retry-stats.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Cross-run schema-retry aggregation for production reliability telemetry.
+ *
+ * Each simulation reports per-schema `{ attempts, calls, fallbacks }` in
+ * its cost payload (see [cost-tracker.ts](../runtime/cost-tracker.ts)).
+ * This module sums those per-run buckets across the last N runs so the
+ * dashboard and `/retry-stats` endpoint can surface live reliability
+ * metrics without running an expensive replay.
+ *
+ * Metrics surfaced per schema across the aggregated window:
+ *
+ * - `calls`      — total schema-validated LLM calls on this schema
+ * - `attempts`   — total attempts (≥ calls; > calls when retries happened)
+ * - `avgAttempts`— attempts / calls. 1.0 = first-try success; > 1.0
+ *                  means the model is retrying on validation failures
+ *                  and maxRetries / schema discipline should be tuned
+ * - `fallbacks`  — runs where retries were exhausted and the caller's
+ *                  empty skeleton was returned instead of a validated object
+ * - `fallbackRate` — fallbacks / calls. > 0 means the run served
+ *                   degraded data on at least one turn for this schema
+ * - `runsPresent`— number of runs in the window where this schema
+ *                  appeared at least once (not every run exercises every
+ *                  schema: agriculture dept only fires on some turns)
+ *
+ * @module paracosm/cli/retry-stats
+ */
+/** Per-run payload emitted by the cost tracker. Keys are schema names. */
+export type PerRunSchemaRetries = Record<string, {
+    attempts: number;
+    calls: number;
+    fallbacks: number;
+}>;
+/** Aggregate rollup across N runs. */
+export interface SchemaRetryStats {
+    runCount: number;
+    schemas: Record<string, {
+        calls: number;
+        attempts: number;
+        fallbacks: number;
+        /** attempts / calls; rounded to two decimals. */
+        avgAttempts: number;
+        /** fallbacks / calls; rounded to four decimals. */
+        fallbackRate: number;
+        /** Count of runs in the window where this schema appeared. */
+        runsPresent: number;
+    }>;
+}
+/**
+ * Fold an array of per-run `schemaRetries` payloads into a single
+ * aggregate rollup. Safe with empty / missing entries — an empty run
+ * (`{}`) still contributes to `runCount` but doesn't add to any
+ * per-schema bucket.
+ */
+export declare function aggregateSchemaRetries(runs: PerRunSchemaRetries[]): SchemaRetryStats;
+/**
+ * Per-run forge-stats payload emitted by the cost tracker once any
+ * forge attempt (approved or rejected) has been captured. Mirrors the
+ * shape of {@link CostTracker.finalCost}'s `forgeStats` field.
+ */
+export interface PerRunForgeStats {
+    attempts: number;
+    approved: number;
+    rejected: number;
+    /** Sum of judge confidence across approved forges; divide by approved for avg. */
+    approvedConfidenceSum: number;
+    /** Count of unique tool names attempted this run. Optional for back-compat
+     *  with v2 entries that predate unique tracking. */
+    uniqueNames?: number;
+    /** Count of unique names that got approved at least once. */
+    uniqueApproved?: number;
+    /** Count of unique names that were only ever rejected. */
+    uniqueTerminalRejections?: number;
+    /** Rejection-reason histogram. Optional for back-compat with entries
+     *  written before 2026-04-18. */
+    rejectionReasons?: {
+        schema_extra_field: number;
+        shape_check: number;
+        parse_error: number;
+        judge_correctness: number;
+        other: number;
+    };
+}
+/** Aggregate rollup across N runs' forge stats. */
+export interface ForgeStatsRollup {
+    totalAttempts: number;
+    approved: number;
+    rejected: number;
+    /** approved / totalAttempts, rounded to 4 decimals. 0 when no attempts. */
+    approvalRate: number;
+    /** approvedConfidenceSum / approved, rounded to 2 decimals. 0 when no approvals. */
+    avgApprovedConfidence: number;
+    /** Sum of unique names attempted across all runs. */
+    totalUniqueNames: number;
+    /** Sum of unique names approved at least once across all runs. */
+    totalUniqueApproved: number;
+    /** Sum of unique names that were only rejected across all runs. */
+    totalUniqueTerminalRejections: number;
+    /** totalUniqueApproved / totalUniqueNames, rounded to 4 decimals. The
+     *  "eventually-approved" rate — closer to the real quality signal than
+     *  raw approvalRate when the retry loop re-forges under the same name. */
+    uniqueApprovalRate: number;
+    /** Summed rejection-reason histogram across all runs. Lets operators
+     *  see the failure-mode distribution over time (e.g. did the
+     *  2026-04-18 forge-guidance prompt fix cut schema_extra_field). */
+    rejectionReasons: {
+        schema_extra_field: number;
+        shape_check: number;
+        parse_error: number;
+        judge_correctness: number;
+        other: number;
+    };
+    /** Count of runs in the window that recorded at least one forge attempt. */
+    runsPresent: number;
+}
+/**
+ * Fold an array of per-run forge-stats payloads into a single rollup
+ * for the /retry-stats response. Runs without any forge activity are
+ * counted in the window's runCount (see aggregateSchemaRetries) but do
+ * not contribute to the forge rollup (they have `attempts===0`).
+ */
+export declare function aggregateForgeStats(runs: PerRunForgeStats[]): ForgeStatsRollup;
+/**
+ * Per-run cache-stats payload emitted by the cost tracker when the
+ * provider returned non-zero cache counters (Anthropic reports these
+ * on every call). Matches {@link CostTracker.finalCost}'s `cacheStats`.
+ */
+export interface PerRunCacheStats {
+    readTokens: number;
+    creationTokens: number;
+    savingsUSD: number;
+}
+/** Aggregate prompt-cache rollup across N runs. */
+export interface CacheStatsRollup {
+    totalReadTokens: number;
+    totalCreationTokens: number;
+    /** Sum of savingsUSD across runs; rounded to 4 decimals. */
+    totalSavingsUSD: number;
+    /** readTokens / (readTokens + creationTokens), rounded to 4 decimals.
+     *  Healthy caching shows ratios > 0.7 — most traffic is replays. */
+    readRatio: number;
+    /** Count of runs that reported any cache activity. */
+    runsPresent: number;
+}
+/**
+ * Fold an array of per-run cache-stats payloads into a rollup. Runs
+ * without cache activity (OpenAI with opaque counters, or very short
+ * runs that never crossed the auto-cache threshold) are skipped.
+ */
+export declare function aggregateCacheStats(runs: PerRunCacheStats[]): CacheStatsRollup;
+/**
+ * Per-run provider-error counters. Keys match the classifier's
+ * ProviderErrorKind; `total` is the sum for dashboard rendering
+ * convenience.
+ */
+export interface PerRunProviderErrors {
+    auth: number;
+    quota: number;
+    rate_limit: number;
+    network: number;
+    unknown: number;
+    total: number;
+}
+/** Aggregate provider-error rollup across N runs. */
+export interface ProviderErrorsRollup {
+    auth: number;
+    quota: number;
+    rate_limit: number;
+    network: number;
+    unknown: number;
+    total: number;
+    /** Count of runs that recorded at least one provider error. */
+    runsPresent: number;
+}
+/**
+ * Fold per-run provider-error counters into a rollup. Runs without any
+ * classified errors are skipped (total === 0).
+ */
+export declare function aggregateProviderErrors(runs: PerRunProviderErrors[]): ProviderErrorsRollup;
+//# sourceMappingURL=retry-stats.d.ts.map

package/dist/cli/retry-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-stats.d.ts","sourceRoot":"","sources":["../../src/cli/retry-stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,0EAA0E;AAC1E,MAAM,MAAM,mBAAmB,GAAG,MAAM,CACtC,MAAM,EACN;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CACvD,CAAC;AAEF,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CACb,MAAM,EACN;QACE,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,iDAAiD;QACjD,WAAW,EAAE,MAAM,CAAC;QACpB,mDAAmD;QACnD,YAAY,EAAE,MAAM,CAAC;QACrB,8DAA8D;QAC9D,WAAW,EAAE,MAAM,CAAC;KACrB,CACF,CAAC;CACH;AAOD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,mBAAmB,EAAE,GAC1B,gBAAgB,CA4BlB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,qBAAqB,EAAE,MAAM,CAAC;IAC9B;wDACoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;qCACiC;IACjC,gBAAgB,CAAC,EAAE;QACjB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,qBAAqB,EAAE,MAAM,CAAC;IAC9B,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mEAAmE;IACnE,6BAA6B,EAAE,MAAM,CAAC;IACtC;;8EAE0E;IAC1E,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;wEAEoE;IACpE,gBAAgB,EAAE;QAChB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,CA+C9E;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,4DAA4D;IAC5D,eAAe,EAAE,MAAM,CAAC;IACxB;wEACoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,CAoB9E;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qDAAqD;AACrD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,EAAE,GAAG,oBAAoB,CAe1F"}

package/dist/cli/retry-stats.js

@@ -0,0 +1,167 @@
+/**
+ * Cross-run schema-retry aggregation for production reliability telemetry.
+ *
+ * Each simulation reports per-schema `{ attempts, calls, fallbacks }` in
+ * its cost payload (see [cost-tracker.ts](../runtime/cost-tracker.ts)).
+ * This module sums those per-run buckets across the last N runs so the
+ * dashboard and `/retry-stats` endpoint can surface live reliability
+ * metrics without running an expensive replay.
+ *
+ * Metrics surfaced per schema across the aggregated window:
+ *
+ * - `calls`      — total schema-validated LLM calls on this schema
+ * - `attempts`   — total attempts (≥ calls; > calls when retries happened)
+ * - `avgAttempts`— attempts / calls. 1.0 = first-try success; > 1.0
+ *                  means the model is retrying on validation failures
+ *                  and maxRetries / schema discipline should be tuned
+ * - `fallbacks`  — runs where retries were exhausted and the caller's
+ *                  empty skeleton was returned instead of a validated object
+ * - `fallbackRate` — fallbacks / calls. > 0 means the run served
+ *                   degraded data on at least one turn for this schema
+ * - `runsPresent`— number of runs in the window where this schema
+ *                  appeared at least once (not every run exercises every
+ *                  schema: agriculture dept only fires on some turns)
+ *
+ * @module paracosm/cli/retry-stats
+ */
+const round = (v, precision) => {
+    const f = Math.pow(10, precision);
+    return Math.round(v * f) / f;
+};
+/**
+ * Fold an array of per-run `schemaRetries` payloads into a single
+ * aggregate rollup. Safe with empty / missing entries — an empty run
+ * (`{}`) still contributes to `runCount` but doesn't add to any
+ * per-schema bucket.
+ */
+export function aggregateSchemaRetries(runs) {
+    const rollup = new Map();
+    for (const run of runs) {
+        if (!run)
+            continue;
+        for (const [schemaName, bucket] of Object.entries(run)) {
+            const existing = rollup.get(schemaName) ?? { calls: 0, attempts: 0, fallbacks: 0, runsPresent: 0 };
+            existing.calls += bucket.calls;
+            existing.attempts += bucket.attempts;
+            existing.fallbacks += bucket.fallbacks;
+            existing.runsPresent += 1;
+            rollup.set(schemaName, existing);
+        }
+    }
+    const schemas = {};
+    for (const [name, r] of rollup.entries()) {
+        schemas[name] = {
+            calls: r.calls,
+            attempts: r.attempts,
+            fallbacks: r.fallbacks,
+            avgAttempts: r.calls > 0 ? round(r.attempts / r.calls, 2) : 0,
+            fallbackRate: r.calls > 0 ? round(r.fallbacks / r.calls, 4) : 0,
+            runsPresent: r.runsPresent,
+        };
+    }
+    return { runCount: runs.length, schemas };
+}
+/**
+ * Fold an array of per-run forge-stats payloads into a single rollup
+ * for the /retry-stats response. Runs without any forge activity are
+ * counted in the window's runCount (see aggregateSchemaRetries) but do
+ * not contribute to the forge rollup (they have `attempts===0`).
+ */
+export function aggregateForgeStats(runs) {
+    let totalAttempts = 0;
+    let approved = 0;
+    let rejected = 0;
+    let approvedConfidenceSum = 0;
+    let totalUniqueNames = 0;
+    let totalUniqueApproved = 0;
+    let totalUniqueTerminalRejections = 0;
+    let runsPresent = 0;
+    const rejectionReasons = {
+        schema_extra_field: 0,
+        shape_check: 0,
+        parse_error: 0,
+        judge_correctness: 0,
+        other: 0,
+    };
+    for (const run of runs) {
+        if (!run || run.attempts === 0)
+            continue;
+        totalAttempts += run.attempts;
+        approved += run.approved;
+        rejected += run.rejected;
+        approvedConfidenceSum += run.approvedConfidenceSum;
+        totalUniqueNames += run.uniqueNames ?? 0;
+        totalUniqueApproved += run.uniqueApproved ?? 0;
+        totalUniqueTerminalRejections += run.uniqueTerminalRejections ?? 0;
+        if (run.rejectionReasons) {
+            rejectionReasons.schema_extra_field += run.rejectionReasons.schema_extra_field;
+            rejectionReasons.shape_check += run.rejectionReasons.shape_check;
+            rejectionReasons.parse_error += run.rejectionReasons.parse_error;
+            rejectionReasons.judge_correctness += run.rejectionReasons.judge_correctness;
+            rejectionReasons.other += run.rejectionReasons.other;
+        }
+        runsPresent += 1;
+    }
+    return {
+        totalAttempts,
+        approved,
+        rejected,
+        approvalRate: totalAttempts > 0 ? round(approved / totalAttempts, 4) : 0,
+        avgApprovedConfidence: approved > 0 ? round(approvedConfidenceSum / approved, 2) : 0,
+        totalUniqueNames,
+        totalUniqueApproved,
+        totalUniqueTerminalRejections,
+        uniqueApprovalRate: totalUniqueNames > 0 ? round(totalUniqueApproved / totalUniqueNames, 4) : 0,
+        rejectionReasons,
+        runsPresent,
+    };
+}
+/**
+ * Fold an array of per-run cache-stats payloads into a rollup. Runs
+ * without cache activity (OpenAI with opaque counters, or very short
+ * runs that never crossed the auto-cache threshold) are skipped.
+ */
+export function aggregateCacheStats(runs) {
+    let totalReadTokens = 0;
+    let totalCreationTokens = 0;
+    let totalSavingsUSD = 0;
+    let runsPresent = 0;
+    for (const run of runs) {
+        if (!run || (run.readTokens === 0 && run.creationTokens === 0))
+            continue;
+        totalReadTokens += run.readTokens;
+        totalCreationTokens += run.creationTokens;
+        totalSavingsUSD += run.savingsUSD;
+        runsPresent += 1;
+    }
+    const denom = totalReadTokens + totalCreationTokens;
+    return {
+        totalReadTokens,
+        totalCreationTokens,
+        totalSavingsUSD: round(totalSavingsUSD, 4),
+        readRatio: denom > 0 ? round(totalReadTokens / denom, 4) : 0,
+        runsPresent,
+    };
+}
+/**
+ * Fold per-run provider-error counters into a rollup. Runs without any
+ * classified errors are skipped (total === 0).
+ */
+export function aggregateProviderErrors(runs) {
+    const rollup = {
+        auth: 0, quota: 0, rate_limit: 0, network: 0, unknown: 0, total: 0, runsPresent: 0,
+    };
+    for (const run of runs) {
+        if (!run || run.total === 0)
+            continue;
+        rollup.auth += run.auth;
+        rollup.quota += run.quota;
+        rollup.rate_limit += run.rate_limit;
+        rollup.network += run.network;
+        rollup.unknown += run.unknown;
+        rollup.total += run.total;
+        rollup.runsPresent += 1;
+    }
+    return rollup;
+}
+//# sourceMappingURL=retry-stats.js.map

package/dist/cli/retry-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-stats.js","sourceRoot":"","sources":["../../src/cli/retry-stats.ts"],"names":[],"mappings":"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"}

package/dist/cli/run-a.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run-a.d.ts.map

package/dist/cli/run-a.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-a.d.ts","sourceRoot":"","sources":["../../src/cli/run-a.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC"}

package/dist/cli/run-a.js

@@ -0,0 +1,13 @@
+/**
+ * Mars Genesis: Leader A (first entry in leaders.json)
+ * Edit leaders.json to change who this runs.
+ *
+ * Usage:
+ *   npx tsx src/run-a.ts              # full 12 turns
+ *   npx tsx src/run-a.ts 3            # 3-turn smoke test
+ *   npx tsx src/run-a.ts 5 --live     # 5 turns + live web search
+ */
+process.argv.splice(2, 0, '--leader', '0');
+await import('./run.js');
+export {};
+//# sourceMappingURL=run-a.js.map

package/dist/cli/run-a.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-a.js","sourceRoot":"","sources":["../../src/cli/run-a.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;AAC3C,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC"}

package/dist/cli/run-b.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run-b.d.ts.map

package/dist/cli/run-b.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-b.d.ts","sourceRoot":"","sources":["../../src/cli/run-b.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC"}

package/dist/cli/run-b.js

@@ -0,0 +1,13 @@
+/**
+ * Mars Genesis: Leader B (second entry in leaders.json)
+ * Edit leaders.json to change who this runs.
+ *
+ * Usage:
+ *   npx tsx src/run-b.ts              # full 12 turns
+ *   npx tsx src/run-b.ts 3            # 3-turn smoke test
+ *   npx tsx src/run-b.ts 5 --live     # 5 turns + live web search
+ */
+process.argv.splice(2, 0, '--leader', '1');
+await import('./run.js');
+export {};
+//# sourceMappingURL=run-b.js.map

package/dist/cli/run-b.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-b.js","sourceRoot":"","sources":["../../src/cli/run-b.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;AAC3C,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC"}

package/dist/cli/run.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Mars Genesis: General-purpose standalone simulation runner.
+ *
+ * Reads leader configs via `resolveLeaders` which walks a priority
+ * chain: --leaders flag, $CWD/leaders.json, $CWD/config/leaders.json,
+ * bundled config/leaders.json, bundled config/leaders.example.json.
+ * CLI flags on top of that override individual leader fields.
+ *
+ * Usage:
+ *   npx tsx src/run.ts --leader 0                         # Leader A
+ *   npx tsx src/run.ts --leader 1 5                       # Leader B, 5 turns
+ *   npx tsx src/run.ts --leader 0 --live                  # live web search
+ *   npx tsx src/run.ts --name "Custom" --openness 0.8 3   # Override fields
+ *   npx tsx src/run.ts --leaders ./my-leaders.json        # Custom config file
+ */
+export {};
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG"}