@timmeck/brain-core 2.4.0 → 2.6.0

package/dist/research/agenda-engine.js

@@ -0,0 +1,264 @@
+import { getLogger } from '../utils/logger.js';
+// ── Migration ───────────────────────────────────────────
+export function runAgendaMigration(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS research_agenda (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      priority REAL NOT NULL,
+      question TEXT NOT NULL,
+      type TEXT NOT NULL,
+      estimated_cycles INTEGER NOT NULL,
+      expected_impact TEXT NOT NULL,
+      prerequisites TEXT NOT NULL DEFAULT '[]',
+      auto_executable INTEGER NOT NULL DEFAULT 0,
+      status TEXT NOT NULL DEFAULT 'open',
+      created_at TEXT DEFAULT (datetime('now')),
+      completed_at TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_agenda_status ON research_agenda(status);
+    CREATE INDEX IF NOT EXISTS idx_agenda_priority ON research_agenda(priority DESC);
+  `);
+}
+// ── Engine ──────────────────────────────────────────────
+export class ResearchAgendaEngine {
+    db;
+    config;
+    log = getLogger();
+    constructor(db, config) {
+        this.db = db;
+        this.config = {
+            brainName: config.brainName,
+            maxItems: config.maxItems ?? 50,
+        };
+        runAgendaMigration(db);
+    }
+    /** Generate research agenda from current state of knowledge. */
+    generate() {
+        const items = [];
+        // 1. Unconfirmed hypotheses → need testing
+        items.push(...this.findOpenHypotheses());
+        // 2. Knowledge gaps → areas with little data
+        items.push(...this.findKnowledgeGaps());
+        // 3. Unexplored correlations
+        items.push(...this.findUnexploredCorrelations());
+        // 4. Anomalies needing investigation
+        items.push(...this.findOpenAnomalies());
+        // 5. Parameter optimization opportunities
+        items.push(...this.findParameterSweeps());
+        // Deduplicate and persist
+        for (const item of items) {
+            this.upsertItem(item);
+        }
+        // Cleanup old completed/dismissed items
+        this.db.prepare(`
+      DELETE FROM research_agenda WHERE status IN ('completed', 'dismissed')
+      AND id NOT IN (SELECT id FROM research_agenda ORDER BY completed_at DESC LIMIT 20)
+    `).run();
+        return this.getAgenda();
+    }
+    /** Get the prioritized research agenda. */
+    getAgenda(limit = 20) {
+        return this.db.prepare(`
+      SELECT * FROM research_agenda WHERE status IN ('open', 'in_progress')
+      ORDER BY priority DESC LIMIT ?
+    `).all(limit).map(r => this.rowToItem(r));
+    }
+    /** Get the single most important next research question. */
+    getNext() {
+        const row = this.db.prepare(`
+      SELECT * FROM research_agenda WHERE status = 'open'
+      ORDER BY priority DESC LIMIT 1
+    `).get();
+        return row ? this.rowToItem(row) : null;
+    }
+    /** Reprioritize an agenda item. */
+    setPriority(id, priority) {
+        const result = this.db.prepare(`
+      UPDATE research_agenda SET priority = ? WHERE id = ?
+    `).run(Math.max(0, Math.min(1, priority)), id);
+        return result.changes > 0;
+    }
+    /** Add a user-defined research question. */
+    ask(question, type = 'hypothesis_test') {
+        const result = this.db.prepare(`
+      INSERT INTO research_agenda (priority, question, type, estimated_cycles, expected_impact, auto_executable, status)
+      VALUES (?, ?, ?, ?, ?, ?, 'open')
+    `).run(0.9, question, type, 5, 'User-requested investigation', 0);
+        return this.getById(Number(result.lastInsertRowid));
+    }
+    /** Mark an item as completed or dismissed. */
+    resolve(id, status) {
+        const result = this.db.prepare(`
+      UPDATE research_agenda SET status = ?, completed_at = datetime('now') WHERE id = ?
+    `).run(status, id);
+        return result.changes > 0;
+    }
+    getById(id) {
+        const row = this.db.prepare(`SELECT * FROM research_agenda WHERE id = ?`).get(id);
+        return row ? this.rowToItem(row) : null;
+    }
+    findOpenHypotheses() {
+        const items = [];
+        try {
+            const pending = this.db.prepare(`
+        SELECT COUNT(*) as c FROM hypotheses WHERE status IN ('proposed', 'testing')
+      `).get();
+            if (pending.c > 0) {
+                items.push({
+                    priority: 0.7,
+                    question: `${pending.c} hypotheses pending testing. Run hypothesis tests to confirm or reject.`,
+                    type: 'hypothesis_test',
+                    estimated_cycles: Math.ceil(pending.c / 3),
+                    expected_impact: 'Validate or reject pending theories about system behavior.',
+                    prerequisites: [],
+                    auto_executable: true,
+                    status: 'open',
+                });
+            }
+        }
+        catch { /* table might not exist */ }
+        return items;
+    }
+    findKnowledgeGaps() {
+        const items = [];
+        try {
+            // Find event types with few observations
+            const sparse = this.db.prepare(`
+        SELECT type, COUNT(*) as c FROM causal_events
+        GROUP BY type HAVING c < 10
+        ORDER BY c ASC LIMIT 5
+      `).all();
+            for (const s of sparse) {
+                items.push({
+                    priority: 0.5 + (1 - s.c / 10) * 0.3,
+                    question: `Only ${s.c} observations of "${s.type}". Need more data for reliable causal analysis.`,
+                    type: 'knowledge_gap',
+                    estimated_cycles: 10,
+                    expected_impact: `More data about "${s.type}" enables better causal inference.`,
+                    prerequisites: [],
+                    auto_executable: false,
+                    status: 'open',
+                });
+            }
+        }
+        catch { /* table might not exist */ }
+        return items;
+    }
+    findUnexploredCorrelations() {
+        const items = [];
+        try {
+            const eventTypes = this.db.prepare(`
+        SELECT DISTINCT type FROM causal_events ORDER BY type
+      `).all();
+            const existingEdges = new Set();
+            try {
+                const edges = this.db.prepare(`SELECT cause, effect FROM causal_edges`).all();
+                for (const e of edges)
+                    existingEdges.add(`${e.cause}→${e.effect}`);
+            }
+            catch { /* ignore */ }
+            // Find pairs not yet analyzed
+            let unexplored = 0;
+            for (let i = 0; i < eventTypes.length && unexplored < 3; i++) {
+                for (let j = i + 1; j < eventTypes.length; j++) {
+                    const key = `${eventTypes[i].type}→${eventTypes[j].type}`;
+                    const keyRev = `${eventTypes[j].type}→${eventTypes[i].type}`;
+                    if (!existingEdges.has(key) && !existingEdges.has(keyRev)) {
+                        unexplored++;
+                        if (unexplored <= 3) {
+                            items.push({
+                                priority: 0.4,
+                                question: `Is there a causal relationship between "${eventTypes[i].type}" and "${eventTypes[j].type}"?`,
+                                type: 'correlation_search',
+                                estimated_cycles: 1,
+                                expected_impact: 'Discover hidden relationships between event types.',
+                                prerequisites: [],
+                                auto_executable: true,
+                                status: 'open',
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        catch { /* table might not exist */ }
+        return items;
+    }
+    findOpenAnomalies() {
+        const items = [];
+        try {
+            const anomalies = this.db.prepare(`
+        SELECT type, title FROM self_insights
+        WHERE type = 'anomaly' AND timestamp > ?
+        ORDER BY timestamp DESC LIMIT 3
+      `).all(Date.now() - 86_400_000 * 7);
+            for (const a of anomalies) {
+                items.push({
+                    priority: 0.8,
+                    question: `Investigate anomaly: ${a.title}`,
+                    type: 'anomaly_investigation',
+                    estimated_cycles: 3,
+                    expected_impact: 'Understanding anomalies prevents degradation.',
+                    prerequisites: [],
+                    auto_executable: false,
+                    status: 'open',
+                });
+            }
+        }
+        catch { /* table might not exist */ }
+        return items;
+    }
+    findParameterSweeps() {
+        const items = [];
+        try {
+            const underOptimized = this.db.prepare(`
+        SELECT strategy, parameter, value, min_value, max_value
+        FROM strategy_parameters
+        WHERE parameter NOT IN (
+          SELECT DISTINCT parameter FROM strategy_adaptations WHERE timestamp > ?
+        )
+      `).all(Date.now() - 86_400_000 * 14);
+            if (underOptimized.length > 0) {
+                items.push({
+                    priority: 0.5,
+                    question: `${underOptimized.length} parameters haven't been optimized in 2+ weeks. Run parameter sweep.`,
+                    type: 'parameter_sweep',
+                    estimated_cycles: underOptimized.length * 2,
+                    expected_impact: 'Stale parameters may be suboptimal. Re-optimization could improve performance.',
+                    prerequisites: [],
+                    auto_executable: true,
+                    status: 'open',
+                });
+            }
+        }
+        catch { /* table might not exist */ }
+        return items;
+    }
+    upsertItem(item) {
+        // Check for similar existing items
+        const existing = this.db.prepare(`
+      SELECT id FROM research_agenda WHERE question = ? AND status = 'open' LIMIT 1
+    `).get(item.question);
+        if (existing)
+            return;
+        this.db.prepare(`
+      INSERT INTO research_agenda (priority, question, type, estimated_cycles, expected_impact, prerequisites, auto_executable, status)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(item.priority, item.question, item.type, item.estimated_cycles, item.expected_impact, JSON.stringify(item.prerequisites), item.auto_executable ? 1 : 0, item.status);
+    }
+    rowToItem(row) {
+        return {
+            id: row.id,
+            priority: row.priority,
+            question: row.question,
+            type: row.type,
+            estimated_cycles: row.estimated_cycles,
+            expected_impact: row.expected_impact,
+            prerequisites: JSON.parse(row.prerequisites || '[]'),
+            auto_executable: row.auto_executable === 1,
+            status: row.status,
+            created_at: row.created_at,
+        };
+    }
+}
+//# sourceMappingURL=agenda-engine.js.map

package/dist/research/agenda-engine.js.map

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

package/dist/research/anomaly-detective.d.ts

@@ -0,0 +1,62 @@
+import type Database from 'better-sqlite3';
+export type AnomalyType = 'statistical' | 'behavioral' | 'causal' | 'cross_domain' | 'drift';
+export type AnomalySeverity = 'low' | 'medium' | 'high' | 'critical';
+export interface Anomaly {
+    id?: number;
+    timestamp: number;
+    type: AnomalyType;
+    severity: AnomalySeverity;
+    title: string;
+    description: string;
+    metric: string;
+    expected_value: number;
+    actual_value: number;
+    deviation: number;
+    evidence: Record<string, unknown>;
+    resolved: boolean;
+    resolution?: string;
+}
+export interface DriftReport {
+    metric: string;
+    direction: 'increasing' | 'decreasing' | 'stable';
+    rate_per_day: number;
+    cumulative_change: number;
+    period_days: number;
+    significant: boolean;
+    description: string;
+}
+export interface AnomalyDetectiveConfig {
+    brainName: string;
+    /** Z-score threshold for statistical anomalies. Default: 2.0 */
+    zThreshold?: number;
+    /** EWMA smoothing factor (0-1). Default: 0.3 */
+    ewmaAlpha?: number;
+    /** Minimum data points for drift detection. Default: 7 */
+    minDriftPoints?: number;
+}
+export declare function runAnomalyDetectiveMigration(db: Database.Database): void;
+export declare class AnomalyDetective {
+    private db;
+    private config;
+    private log;
+    constructor(db: Database.Database, config: AnomalyDetectiveConfig);
+    /** Record a metric value for anomaly tracking. */
+    recordMetric(metric: string, value: number): void;
+    /** Check all tracked metrics for anomalies. */
+    detect(): Anomaly[];
+    /** Get current anomalies. */
+    getAnomalies(type?: AnomalyType, limit?: number): Anomaly[];
+    /** Investigate a specific anomaly — provide context and potential causes. */
+    investigate(anomalyId: number): Record<string, unknown> | null;
+    /** Get anomaly history (including resolved). */
+    getHistory(limit?: number): Anomaly[];
+    /** Get drift reports for all tracked metrics. */
+    getDriftReport(): DriftReport[];
+    /** Resolve an anomaly. */
+    resolve(anomalyId: number, resolution: string): boolean;
+    private detectStatisticalAnomaly;
+    private detectDrift;
+    private computeDriftReport;
+    private persistAnomaly;
+    private rowToAnomaly;
+}

package/dist/research/anomaly-detective.js

@@ -0,0 +1,318 @@
+import { getLogger } from '../utils/logger.js';
+// ── Migration ───────────────────────────────────────────
+export function runAnomalyDetectiveMigration(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS anomalies (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      timestamp INTEGER NOT NULL,
+      type TEXT NOT NULL,
+      severity TEXT NOT NULL,
+      title TEXT NOT NULL,
+      description TEXT NOT NULL,
+      metric TEXT NOT NULL,
+      expected_value REAL NOT NULL,
+      actual_value REAL NOT NULL,
+      deviation REAL NOT NULL,
+      evidence TEXT NOT NULL,
+      resolved INTEGER DEFAULT 0,
+      resolution TEXT,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_anomalies_type ON anomalies(type);
+    CREATE INDEX IF NOT EXISTS idx_anomalies_ts ON anomalies(timestamp);
+    CREATE INDEX IF NOT EXISTS idx_anomalies_resolved ON anomalies(resolved);
+
+    CREATE TABLE IF NOT EXISTS metric_history (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      metric TEXT NOT NULL,
+      value REAL NOT NULL,
+      timestamp INTEGER NOT NULL,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_metric_hist ON metric_history(metric, timestamp);
+  `);
+}
+// ── Engine ──────────────────────────────────────────────
+export class AnomalyDetective {
+    db;
+    config;
+    log = getLogger();
+    constructor(db, config) {
+        this.db = db;
+        this.config = {
+            brainName: config.brainName,
+            zThreshold: config.zThreshold ?? 2.0,
+            ewmaAlpha: config.ewmaAlpha ?? 0.3,
+            minDriftPoints: config.minDriftPoints ?? 7,
+        };
+        runAnomalyDetectiveMigration(db);
+    }
+    /** Record a metric value for anomaly tracking. */
+    recordMetric(metric, value) {
+        this.db.prepare(`
+      INSERT INTO metric_history (metric, value, timestamp)
+      VALUES (?, ?, ?)
+    `).run(metric, value, Date.now());
+    }
+    /** Check all tracked metrics for anomalies. */
+    detect() {
+        const anomalies = [];
+        const metrics = this.db.prepare(`
+      SELECT DISTINCT metric FROM metric_history
+    `).all();
+        for (const { metric } of metrics) {
+            const values = this.db.prepare(`
+        SELECT value, timestamp FROM metric_history
+        WHERE metric = ? ORDER BY timestamp ASC
+      `).all(metric);
+            if (values.length < 3)
+                continue;
+            // Statistical anomaly detection (Z-score)
+            const statistical = this.detectStatisticalAnomaly(metric, values);
+            if (statistical)
+                anomalies.push(statistical);
+            // Drift detection (EWMA)
+            const drift = this.detectDrift(metric, values);
+            if (drift)
+                anomalies.push(drift);
+        }
+        // Persist new anomalies
+        for (const a of anomalies) {
+            this.persistAnomaly(a);
+        }
+        return anomalies;
+    }
+    /** Get current anomalies. */
+    getAnomalies(type, limit = 20) {
+        let sql = `SELECT * FROM anomalies`;
+        const params = [];
+        if (type) {
+            sql += ` WHERE type = ?`;
+            params.push(type);
+        }
+        sql += ` ORDER BY timestamp DESC LIMIT ?`;
+        params.push(limit);
+        return this.db.prepare(sql).all(...params).map(r => this.rowToAnomaly(r));
+    }
+    /** Investigate a specific anomaly — provide context and potential causes. */
+    investigate(anomalyId) {
+        const anomaly = this.db.prepare(`SELECT * FROM anomalies WHERE id = ?`).get(anomalyId);
+        if (!anomaly)
+            return null;
+        const a = this.rowToAnomaly(anomaly);
+        // Get metric history around the anomaly
+        const window = 86_400_000; // 24h
+        const history = this.db.prepare(`
+      SELECT value, timestamp FROM metric_history
+      WHERE metric = ? AND timestamp BETWEEN ? AND ?
+      ORDER BY timestamp
+    `).all(a.metric, a.timestamp - window, a.timestamp + window);
+        // Look for related events in causal_events (if available)
+        let relatedEvents = [];
+        try {
+            relatedEvents = this.db.prepare(`
+        SELECT type, source, timestamp FROM causal_events
+        WHERE timestamp BETWEEN ? AND ?
+        ORDER BY timestamp DESC LIMIT 20
+      `).all(a.timestamp - 3_600_000, a.timestamp);
+        }
+        catch { /* table might not exist */ }
+        return {
+            anomaly: a,
+            metric_history: history,
+            related_events: relatedEvents,
+            context: {
+                metric_count: history.length,
+                avg_value: history.length > 0 ? history.reduce((s, h) => s + h.value, 0) / history.length : 0,
+                max_value: history.length > 0 ? Math.max(...history.map(h => h.value)) : 0,
+                min_value: history.length > 0 ? Math.min(...history.map(h => h.value)) : 0,
+            },
+        };
+    }
+    /** Get anomaly history (including resolved). */
+    getHistory(limit = 50) {
+        return this.db.prepare(`
+      SELECT * FROM anomalies ORDER BY timestamp DESC LIMIT ?
+    `).all(limit).map(r => this.rowToAnomaly(r));
+    }
+    /** Get drift reports for all tracked metrics. */
+    getDriftReport() {
+        const reports = [];
+        const metrics = this.db.prepare(`
+      SELECT DISTINCT metric FROM metric_history
+    `).all();
+        for (const { metric } of metrics) {
+            const values = this.db.prepare(`
+        SELECT value, timestamp FROM metric_history
+        WHERE metric = ? ORDER BY timestamp ASC
+      `).all(metric);
+            if (values.length < this.config.minDriftPoints)
+                continue;
+            const report = this.computeDriftReport(metric, values);
+            if (report)
+                reports.push(report);
+        }
+        return reports.sort((a, b) => Math.abs(b.rate_per_day) - Math.abs(a.rate_per_day));
+    }
+    /** Resolve an anomaly. */
+    resolve(anomalyId, resolution) {
+        const result = this.db.prepare(`
+      UPDATE anomalies SET resolved = 1, resolution = ? WHERE id = ?
+    `).run(resolution, anomalyId);
+        return result.changes > 0;
+    }
+    detectStatisticalAnomaly(metric, values) {
+        if (values.length < 5)
+            return null;
+        const nums = values.map(v => v.value);
+        const m = mean(nums);
+        const s = stddev(nums);
+        if (s === 0)
+            return null;
+        // Check latest value
+        const latest = values[values.length - 1];
+        const z = Math.abs(latest.value - m) / s;
+        if (z < this.config.zThreshold)
+            return null;
+        const severity = z > 4 ? 'critical' :
+            z > 3 ? 'high' :
+                z > 2.5 ? 'medium' : 'low';
+        return {
+            timestamp: latest.timestamp,
+            type: 'statistical',
+            severity,
+            title: `${metric} deviated ${z.toFixed(1)}σ from mean`,
+            description: `${metric} = ${latest.value.toFixed(3)} (mean: ${m.toFixed(3)}, σ: ${s.toFixed(3)}, z-score: ${z.toFixed(2)})`,
+            metric,
+            expected_value: m,
+            actual_value: latest.value,
+            deviation: z,
+            evidence: { mean: m, stddev: s, z_score: z, n: values.length },
+            resolved: false,
+        };
+    }
+    detectDrift(metric, values) {
+        if (values.length < this.config.minDriftPoints)
+            return null;
+        // EWMA on the values
+        const alpha = this.config.ewmaAlpha;
+        let ewma = values[0].value;
+        const ewmaValues = [ewma];
+        for (let i = 1; i < values.length; i++) {
+            ewma = alpha * values[i].value + (1 - alpha) * ewma;
+            ewmaValues.push(ewma);
+        }
+        // Check if EWMA trend is consistently increasing or decreasing
+        const recentWindow = Math.min(values.length, 10);
+        const recentEwma = ewmaValues.slice(-recentWindow);
+        let increasing = 0, decreasing = 0;
+        for (let i = 1; i < recentEwma.length; i++) {
+            if (recentEwma[i] > recentEwma[i - 1])
+                increasing++;
+            else if (recentEwma[i] < recentEwma[i - 1])
+                decreasing++;
+        }
+        const total = recentEwma.length - 1;
+        if (total < 3)
+            return null;
+        const driftRatio = Math.max(increasing, decreasing) / total;
+        if (driftRatio < 0.7)
+            return null; // Not a consistent trend
+        const direction = increasing > decreasing ? 'increasing' : 'decreasing';
+        const firstValue = recentEwma[0];
+        const lastValue = recentEwma[recentEwma.length - 1];
+        const change = lastValue - firstValue;
+        const pctChange = firstValue !== 0 ? (change / Math.abs(firstValue)) * 100 : 0;
+        if (Math.abs(pctChange) < 5)
+            return null; // Less than 5% drift — ignore
+        const severity = Math.abs(pctChange) > 30 ? 'high' :
+            Math.abs(pctChange) > 15 ? 'medium' : 'low';
+        return {
+            timestamp: Date.now(),
+            type: 'drift',
+            severity,
+            title: `${metric} is ${direction} (${pctChange > 0 ? '+' : ''}${pctChange.toFixed(1)}% drift)`,
+            description: `${metric} has been consistently ${direction} over the last ${recentWindow} measurements. EWMA: ${firstValue.toFixed(3)} → ${lastValue.toFixed(3)}.`,
+            metric,
+            expected_value: firstValue,
+            actual_value: lastValue,
+            deviation: Math.abs(pctChange),
+            evidence: { direction, change, pct_change: pctChange, window: recentWindow, drift_ratio: driftRatio },
+            resolved: false,
+        };
+    }
+    computeDriftReport(metric, values) {
+        if (values.length < 2)
+            return null;
+        const first = values[0];
+        const last = values[values.length - 1];
+        const periodMs = last.timestamp - first.timestamp;
+        const periodDays = periodMs / 86_400_000;
+        if (periodDays < 1)
+            return null;
+        const change = last.value - first.value;
+        const ratePerDay = change / periodDays;
+        // Simple linear regression significance
+        const xMean = values.reduce((s, v) => s + v.timestamp, 0) / values.length;
+        const yMean = values.reduce((s, v) => s + v.value, 0) / values.length;
+        let ssXY = 0, ssXX = 0, ssYY = 0;
+        for (const v of values) {
+            ssXY += (v.timestamp - xMean) * (v.value - yMean);
+            ssXX += (v.timestamp - xMean) ** 2;
+            ssYY += (v.value - yMean) ** 2;
+        }
+        const r = ssXX > 0 && ssYY > 0 ? ssXY / Math.sqrt(ssXX * ssYY) : 0;
+        const significant = Math.abs(r) > 0.5 && values.length >= 5;
+        const direction = Math.abs(ratePerDay) < 0.001 ? 'stable' :
+            ratePerDay > 0 ? 'increasing' : 'decreasing';
+        return {
+            metric,
+            direction,
+            rate_per_day: ratePerDay,
+            cumulative_change: change,
+            period_days: periodDays,
+            significant,
+            description: `${metric}: ${direction} at ${ratePerDay.toFixed(4)}/day over ${periodDays.toFixed(1)} days (r=${r.toFixed(2)})`,
+        };
+    }
+    persistAnomaly(a) {
+        // Avoid duplicates: same metric + type within 1 hour
+        const existing = this.db.prepare(`
+      SELECT id FROM anomalies WHERE metric = ? AND type = ? AND timestamp > ? LIMIT 1
+    `).get(a.metric, a.type, Date.now() - 3_600_000);
+        if (existing)
+            return;
+        this.db.prepare(`
+      INSERT INTO anomalies (timestamp, type, severity, title, description, metric,
+        expected_value, actual_value, deviation, evidence)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(a.timestamp, a.type, a.severity, a.title, a.description, a.metric, a.expected_value, a.actual_value, a.deviation, JSON.stringify(a.evidence));
+    }
+    rowToAnomaly(row) {
+        return {
+            id: row.id,
+            timestamp: row.timestamp,
+            type: row.type,
+            severity: row.severity,
+            title: row.title,
+            description: row.description,
+            metric: row.metric,
+            expected_value: row.expected_value,
+            actual_value: row.actual_value,
+            deviation: row.deviation,
+            evidence: JSON.parse(row.evidence),
+            resolved: row.resolved === 1,
+            resolution: row.resolution,
+        };
+    }
+}
+function mean(arr) {
+    return arr.length === 0 ? 0 : arr.reduce((a, b) => a + b, 0) / arr.length;
+}
+function stddev(arr) {
+    if (arr.length < 2)
+        return 0;
+    const m = mean(arr);
+    return Math.sqrt(arr.reduce((s, x) => s + (x - m) ** 2, 0) / (arr.length - 1));
+}
+//# sourceMappingURL=anomaly-detective.js.map