@neuroverseos/nv-sim 0.1.2 → 0.1.6

package/dist/engine/auditTrace.js

@@ -0,0 +1,352 @@
+"use strict";
+/**
+ * NeuroverseOS — Persistent Audit Trace System
+ *
+ * Every governance decision, every rule that fired, every agent action —
+ * written to disk as an append-only JSONL audit log.
+ *
+ * Design principles:
+ *   - Append-only: never modify or delete entries
+ *   - Structured: every entry is a typed JSON object
+ *   - Queryable: filter by session, agent, verdict, time range
+ *   - Human-readable: each line is valid JSON, can be piped through jq
+ *   - Evidence chain: each entry links to its session and run context
+ *
+ * Storage format: JSONL (one JSON object per line)
+ * Default location: .neuroverse/audit/ relative to project root
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditTrail = void 0;
+exports.listAuditSessions = listAuditSessions;
+exports.loadAuditSession = loadAuditSession;
+exports.searchAuditTrails = searchAuditTrails;
+exports.formatAuditTrail = formatAuditTrail;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ============================================
+// AUDIT STORE
+// ============================================
+const DEFAULT_AUDIT_DIR = ".neuroverse/audit";
+/** Generate a unique entry ID */
+function entryId() {
+    return `aud_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+/**
+ * Persistent audit trail — appends governance decisions to disk.
+ *
+ * Usage:
+ *   const audit = new AuditTrail({ sessionId: "my-session" });
+ *   audit.logVerdict({ agent: "trader_1", verdict: "BLOCK", ... });
+ *   const entries = audit.query({ verdict: "BLOCK" });
+ */
+class AuditTrail {
+    dir;
+    sessionId;
+    filePath;
+    writeStream = null;
+    constructor(options) {
+        this.sessionId = options?.sessionId ?? `session_${Date.now().toString(36)}`;
+        this.dir = options?.dir ?? DEFAULT_AUDIT_DIR;
+        this.filePath = path.join(this.dir, `${this.sessionId}.jsonl`);
+        this.ensureDir();
+    }
+    ensureDir() {
+        if (!fs.existsSync(this.dir)) {
+            fs.mkdirSync(this.dir, { recursive: true });
+        }
+    }
+    getStream() {
+        if (!this.writeStream) {
+            this.writeStream = fs.createWriteStream(this.filePath, { flags: "a" });
+        }
+        return this.writeStream;
+    }
+    /** Append a raw audit entry */
+    append(entry) {
+        const line = JSON.stringify(entry) + "\n";
+        this.getStream().write(line);
+    }
+    /** Log a governance verdict */
+    logVerdict(data) {
+        this.append({
+            id: entryId(),
+            timestamp: new Date().toISOString(),
+            sessionId: this.sessionId,
+            type: "governance_verdict",
+            ...data,
+        });
+    }
+    /** Log an agent action (pre-governance) */
+    logAgentAction(data) {
+        this.append({
+            id: entryId(),
+            timestamp: new Date().toISOString(),
+            sessionId: this.sessionId,
+            type: "agent_action",
+            ...data,
+        });
+    }
+    /** Log simulation start/end */
+    logSimulation(data) {
+        this.append({
+            id: entryId(),
+            timestamp: new Date().toISOString(),
+            sessionId: this.sessionId,
+            ...data,
+        });
+    }
+    /** Log a rule change */
+    logRuleChange(data) {
+        this.append({
+            id: entryId(),
+            timestamp: new Date().toISOString(),
+            sessionId: this.sessionId,
+            type: "rule_change",
+            ...data,
+        });
+    }
+    /** Log a behavioral shift */
+    logBehavioralShift(data) {
+        this.append({
+            id: entryId(),
+            timestamp: new Date().toISOString(),
+            sessionId: this.sessionId,
+            type: "behavioral_shift",
+            ...data,
+        });
+    }
+    /** Log an AI provider call */
+    logAICall(data) {
+        this.append({
+            id: entryId(),
+            timestamp: new Date().toISOString(),
+            sessionId: this.sessionId,
+            type: "ai_call",
+            ...data,
+        });
+    }
+    /** Close the write stream */
+    close() {
+        if (this.writeStream) {
+            this.writeStream.end();
+            this.writeStream = null;
+        }
+    }
+    // ============================================
+    // QUERY API
+    // ============================================
+    /** Read all entries from this session's log file */
+    readAll() {
+        if (!fs.existsSync(this.filePath))
+            return [];
+        const content = fs.readFileSync(this.filePath, "utf-8");
+        return content
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((e) => e !== null);
+    }
+    /** Query entries with filters */
+    query(filters) {
+        let entries = this.readAll();
+        if (filters?.type) {
+            entries = entries.filter((e) => e.type === filters.type);
+        }
+        if (filters?.agent) {
+            entries = entries.filter((e) => "agent" in e && e.agent === filters.agent);
+        }
+        if (filters?.verdict) {
+            entries = entries.filter((e) => e.type === "governance_verdict" && e.verdict === filters.verdict);
+        }
+        if (filters?.runId) {
+            entries = entries.filter((e) => "runId" in e && e.runId === filters.runId);
+        }
+        if (filters?.after) {
+            entries = entries.filter((e) => e.timestamp >= filters.after);
+        }
+        if (filters?.before) {
+            entries = entries.filter((e) => e.timestamp <= filters.before);
+        }
+        return entries;
+    }
+    /** Get summary statistics */
+    summary() {
+        const entries = this.readAll();
+        const verdicts = entries.filter((e) => e.type === "governance_verdict");
+        return {
+            sessionId: this.sessionId,
+            totalEntries: entries.length,
+            entryTypes: countBy(entries, (e) => e.type),
+            verdictCounts: {
+                ALLOW: verdicts.filter((v) => v.verdict === "ALLOW").length,
+                BLOCK: verdicts.filter((v) => v.verdict === "BLOCK").length,
+                PAUSE: verdicts.filter((v) => v.verdict === "PAUSE").length,
+                MODIFY: verdicts.filter((v) => v.verdict === "MODIFY").length,
+            },
+            uniqueAgents: [...new Set(verdicts.map((v) => v.agent))],
+            uniqueRules: [...new Set(verdicts.flatMap((v) => v.rulesFired.map((r) => r.id)))],
+            timeRange: entries.length > 0
+                ? { start: entries[0].timestamp, end: entries[entries.length - 1].timestamp }
+                : null,
+            filePath: this.filePath,
+        };
+    }
+    /** Get the file path for this audit log */
+    getFilePath() {
+        return this.filePath;
+    }
+    /** Get the session ID */
+    getSessionId() {
+        return this.sessionId;
+    }
+}
+exports.AuditTrail = AuditTrail;
+// ============================================
+// CROSS-SESSION QUERIES
+// ============================================
+/**
+ * List all audit sessions on disk.
+ */
+function listAuditSessions(dir) {
+    const auditDir = dir ?? DEFAULT_AUDIT_DIR;
+    if (!fs.existsSync(auditDir))
+        return [];
+    return fs
+        .readdirSync(auditDir)
+        .filter((f) => f.endsWith(".jsonl"))
+        .map((f) => f.replace(/\.jsonl$/, ""));
+}
+/**
+ * Load a specific session's audit trail.
+ */
+function loadAuditSession(sessionId, dir) {
+    return new AuditTrail({ sessionId, dir });
+}
+/**
+ * Search across ALL audit sessions for entries matching filters.
+ */
+function searchAuditTrails(filters, dir) {
+    const sessions = listAuditSessions(dir);
+    const results = [];
+    for (const sessionId of sessions) {
+        const trail = loadAuditSession(sessionId, dir);
+        results.push(...trail.query(filters));
+    }
+    return results.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+}
+/**
+ * Format audit trail for human-readable display.
+ */
+function formatAuditTrail(entries, options) {
+    if (entries.length === 0)
+        return "  No audit entries found.\n";
+    const lines = [];
+    lines.push(`  ╔══════════════════════════════════════════════════════════════╗`);
+    lines.push(`  ║  NeuroverseOS — AUDIT TRAIL (${entries.length} entries)${" ".repeat(Math.max(0, 24 - String(entries.length).length))}║`);
+    lines.push(`  ╚══════════════════════════════════════════════════════════════╝\n`);
+    for (const entry of entries) {
+        const ts = entry.timestamp.replace("T", " ").slice(0, 19);
+        switch (entry.type) {
+            case "governance_verdict": {
+                const v = entry;
+                const icon = v.verdict === "BLOCK" ? "⛔" : v.verdict === "ALLOW" ? "✅" : v.verdict === "PAUSE" ? "⏸" : "🔄";
+                lines.push(`  ${icon} [${ts}] ${v.verdict} — ${v.agent}: ${v.action}`);
+                if (options?.verbose) {
+                    lines.push(`     Reason: ${v.reason}`);
+                    if (v.rulesFired.length > 0) {
+                        lines.push(`     Rules: ${v.rulesFired.map(r => r.id).join(", ")}`);
+                    }
+                }
+                break;
+            }
+            case "agent_action": {
+                const a = entry;
+                lines.push(`  🎯 [${ts}] ACTION — ${a.agent}: ${a.action} (magnitude: ${a.magnitude})`);
+                break;
+            }
+            case "simulation_start":
+            case "simulation_end": {
+                const s = entry;
+                const label = s.type === "simulation_start" ? "▶ START" : "■ END";
+                lines.push(`  ${label} [${ts}] Run ${s.runId}: ${s.scenario}`);
+                if (s.type === "simulation_end" && s.metrics && options?.verbose) {
+                    lines.push(`     Metrics: ${JSON.stringify(s.metrics)}`);
+                }
+                break;
+            }
+            case "rule_change": {
+                const r = entry;
+                const icon = r.changeType === "added" ? "➕" : r.changeType === "removed" ? "➖" : "📝";
+                lines.push(`  ${icon} [${ts}] RULE ${r.changeType.toUpperCase()}: ${r.ruleId} — ${r.description}`);
+                break;
+            }
+            case "behavioral_shift": {
+                const b = entry;
+                lines.push(`  🔀 [${ts}] SHIFT — ${b.agent}: ${b.fromBehavior} → ${b.toBehavior} (round ${b.round})`);
+                if (options?.verbose) {
+                    lines.push(`     Trigger: ${b.trigger}`);
+                }
+                break;
+            }
+            case "ai_call": {
+                const ai = entry;
+                const status = ai.success ? "✓" : "✗";
+                lines.push(`  🤖 [${ts}] AI ${status} — ${ai.provider}/${ai.action}${ai.durationMs ? ` (${ai.durationMs}ms)` : ""}`);
+                break;
+            }
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+// ============================================
+// HELPERS
+// ============================================
+function countBy(arr, fn) {
+    const counts = {};
+    for (const item of arr) {
+        const key = fn(item);
+        counts[key] = (counts[key] ?? 0) + 1;
+    }
+    return counts;
+}