@timmeck/brain-core 2.25.1 → 2.27.0

package/dist/metacognition/meta-cognition-layer.js

@@ -0,0 +1,402 @@
+import { getLogger } from '../utils/logger.js';
+// ── Migration ───────────────────────────────────────────
+export function runMetaCognitionMigration(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS engine_metrics (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      engine TEXT NOT NULL,
+      cycle INTEGER NOT NULL,
+      insights INTEGER NOT NULL DEFAULT 0,
+      journal_entries INTEGER NOT NULL DEFAULT 0,
+      anomalies INTEGER NOT NULL DEFAULT 0,
+      predictions INTEGER NOT NULL DEFAULT 0,
+      thoughts INTEGER NOT NULL DEFAULT 0,
+      errors INTEGER NOT NULL DEFAULT 0,
+      duration_ms INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_engine_metrics_engine ON engine_metrics(engine, cycle);
+
+    CREATE TABLE IF NOT EXISTS engine_report_cards (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      engine TEXT NOT NULL,
+      grade TEXT NOT NULL,
+      health_score REAL NOT NULL,
+      value_score REAL NOT NULL,
+      signal_to_noise REAL NOT NULL,
+      combined_score REAL NOT NULL,
+      evaluated_at TEXT DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_report_cards_engine ON engine_report_cards(engine);
+
+    CREATE TABLE IF NOT EXISTS cycle_frequency_adjustments (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      engine TEXT NOT NULL,
+      old_frequency INTEGER NOT NULL,
+      new_frequency INTEGER NOT NULL,
+      reason TEXT NOT NULL,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS meta_trends (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      cycle INTEGER NOT NULL,
+      learning_rate REAL NOT NULL DEFAULT 0,
+      discovery_rate REAL NOT NULL DEFAULT 0,
+      knowledge_quality REAL NOT NULL DEFAULT 0,
+      gap_closure_rate REAL NOT NULL DEFAULT 0,
+      total_principles INTEGER NOT NULL DEFAULT 0,
+      total_hypotheses INTEGER NOT NULL DEFAULT 0,
+      prediction_accuracy REAL NOT NULL DEFAULT 0,
+      emergence_count INTEGER NOT NULL DEFAULT 0,
+      timestamp TEXT DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_meta_trends_cycle ON meta_trends(cycle);
+  `);
+}
+// ── MetaCognition Layer ─────────────────────────────────
+export class MetaCognitionLayer {
+    db;
+    log = getLogger();
+    /** Current frequency multiplier per engine: 1 = every cycle, 2 = every 2 cycles, etc. */
+    engineFrequencies = new Map();
+    constructor(db) {
+        this.db = db;
+        runMetaCognitionMigration(db);
+    }
+    /** Record metrics for a single engine step in a cycle. */
+    recordStep(engine, cycle, metrics) {
+        // Upsert: if we already recorded this engine+cycle, add to it
+        const existing = this.db.prepare('SELECT id, insights, journal_entries, anomalies, predictions, thoughts, errors, duration_ms FROM engine_metrics WHERE engine = ? AND cycle = ?').get(engine, cycle);
+        if (existing) {
+            this.db.prepare(`
+        UPDATE engine_metrics SET
+          insights = insights + ?, journal_entries = journal_entries + ?, anomalies = anomalies + ?,
+          predictions = predictions + ?, thoughts = thoughts + ?, errors = errors + ?,
+          duration_ms = duration_ms + ?
+        WHERE id = ?
+      `).run(metrics.insights ?? 0, metrics.journal_entries ?? 0, metrics.anomalies ?? 0, metrics.predictions ?? 0, metrics.thoughts ?? 0, metrics.errors ?? 0, metrics.duration_ms ?? 0, existing.id);
+        }
+        else {
+            this.db.prepare(`
+        INSERT INTO engine_metrics (engine, cycle, insights, journal_entries, anomalies, predictions, thoughts, errors, duration_ms)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(engine, cycle, metrics.insights ?? 0, metrics.journal_entries ?? 0, metrics.anomalies ?? 0, metrics.predictions ?? 0, metrics.thoughts ?? 0, metrics.errors ?? 0, metrics.duration_ms ?? 0);
+        }
+    }
+    /** Evaluate all engines based on recent metrics. Returns report cards. */
+    evaluate(windowCycles = 10) {
+        // Get all engines that have metrics in the last windowCycles
+        const engines = this.db.prepare(`
+      SELECT DISTINCT engine FROM engine_metrics
+      WHERE cycle > (SELECT COALESCE(MAX(cycle), 0) FROM engine_metrics) - ?
+    `).all(windowCycles);
+        const cards = [];
+        for (const { engine } of engines) {
+            const metrics = this.db.prepare(`
+        SELECT insights, journal_entries, anomalies, predictions, thoughts, errors, duration_ms
+        FROM engine_metrics WHERE engine = ?
+        ORDER BY cycle DESC LIMIT ?
+      `).all(engine, windowCycles);
+            if (metrics.length === 0)
+                continue;
+            // Health Score: low errors, reasonable duration
+            const avgErrors = metrics.reduce((s, m) => s + m.errors, 0) / metrics.length;
+            const avgDuration = metrics.reduce((s, m) => s + m.duration_ms, 0) / metrics.length;
+            const healthScore = Math.max(0, Math.min(1, (1 - Math.min(avgErrors / 3, 1)) * 0.6 + // fewer errors = healthier
+                (1 - Math.min(avgDuration / 5000, 1)) * 0.4));
+            // Value Score: producing useful outputs (insights, journal entries, predictions)
+            const avgInsights = metrics.reduce((s, m) => s + m.insights, 0) / metrics.length;
+            const avgJournal = metrics.reduce((s, m) => s + m.journal_entries, 0) / metrics.length;
+            const avgPredictions = metrics.reduce((s, m) => s + m.predictions, 0) / metrics.length;
+            const valueScore = Math.min(1, (avgInsights * 0.4 + avgJournal * 0.3 + avgPredictions * 0.3));
+            // Signal-to-Noise: useful outputs / total thoughts
+            const avgThoughts = metrics.reduce((s, m) => s + m.thoughts, 0) / metrics.length;
+            const signalToNoise = avgThoughts > 0
+                ? Math.min(1, (avgInsights + avgJournal + avgPredictions) / avgThoughts)
+                : 0;
+            // Combined Score
+            const combinedScore = healthScore * 0.3 + valueScore * 0.5 + signalToNoise * 0.2;
+            // Grade
+            const grade = this.scoreToGrade(combinedScore);
+            const card = {
+                engine, grade, health_score: healthScore, value_score: valueScore,
+                signal_to_noise: signalToNoise, combined_score: combinedScore,
+            };
+            cards.push(card);
+            // Persist
+            this.db.prepare(`
+        INSERT INTO engine_report_cards (engine, grade, health_score, value_score, signal_to_noise, combined_score)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `).run(engine, grade, healthScore, valueScore, signalToNoise, combinedScore);
+        }
+        return cards;
+    }
+    /** Adjust engine frequencies based on report cards. A=more often, D/F=less often. */
+    adjustFrequencies(cards) {
+        const adjustments = [];
+        for (const card of cards) {
+            const currentFreq = this.engineFrequencies.get(card.engine) ?? 1;
+            let newFreq = currentFreq;
+            if (card.grade === 'A' && currentFreq > 1) {
+                newFreq = currentFreq - 1; // Run more often
+            }
+            else if (card.grade === 'D' || card.grade === 'F') {
+                newFreq = Math.min(currentFreq + 1, 10); // Run less often, cap at 10
+            }
+            // B and C: keep current frequency
+            if (newFreq !== currentFreq) {
+                this.engineFrequencies.set(card.engine, newFreq);
+                const adjustment = {
+                    engine: card.engine,
+                    old_frequency: currentFreq,
+                    new_frequency: newFreq,
+                    reason: `Grade ${card.grade}: combined=${card.combined_score.toFixed(2)}`,
+                };
+                adjustments.push(adjustment);
+                this.db.prepare(`
+          INSERT INTO cycle_frequency_adjustments (engine, old_frequency, new_frequency, reason)
+          VALUES (?, ?, ?, ?)
+        `).run(card.engine, currentFreq, newFreq, adjustment.reason);
+                this.log.info(`[metacognition] ${card.engine}: freq ${currentFreq} → ${newFreq} (grade ${card.grade})`);
+            }
+        }
+        return adjustments;
+    }
+    /** Check if an engine should run this cycle based on its frequency. */
+    shouldRun(engine, cycle) {
+        const freq = this.engineFrequencies.get(engine) ?? 1;
+        return cycle % freq === 0;
+    }
+    /** Get engine frequency. */
+    getFrequency(engine) {
+        return this.engineFrequencies.get(engine) ?? 1;
+    }
+    /** Get report card for a specific engine. */
+    getReportCard(engine) {
+        const row = this.db.prepare(`
+      SELECT engine, grade, health_score, value_score, signal_to_noise, combined_score, evaluated_at
+      FROM engine_report_cards WHERE engine = ? ORDER BY id DESC LIMIT 1
+    `).get(engine);
+        return row;
+    }
+    /** Get all latest report cards. */
+    getLatestReportCards() {
+        return this.db.prepare(`
+      SELECT r.engine, r.grade, r.health_score, r.value_score, r.signal_to_noise, r.combined_score, r.evaluated_at
+      FROM engine_report_cards r
+      INNER JOIN (SELECT engine, MAX(id) as max_id FROM engine_report_cards GROUP BY engine) latest
+      ON r.id = latest.max_id
+      ORDER BY r.combined_score DESC
+    `).all();
+    }
+    /** Get trend for an engine over time. */
+    getTrend(engine, limit = 10) {
+        return this.db.prepare(`
+      SELECT engine, grade, health_score, value_score, signal_to_noise, combined_score, evaluated_at
+      FROM engine_report_cards WHERE engine = ? ORDER BY id DESC LIMIT ?
+    `).all(engine, limit);
+    }
+    // ── Meta-Trends ────────────────────────────────────────
+    /** Record a trend data point for the current cycle. */
+    recordTrend(cycle, stats) {
+        const learningRate = cycle > 0 ? stats.newPrinciples / cycle : 0;
+        const discoveryRate = cycle > 0 ? stats.newHypotheses / cycle : 0;
+        const knowledgeQuality = stats.totalPrinciples > 0
+            ? Math.min(1, stats.predictionAccuracy * 0.5 + (stats.totalPrinciples / Math.max(stats.totalHypotheses, 1)) * 0.5)
+            : 0;
+        const gapClosureRate = cycle > 0 ? stats.closedGaps / cycle : 0;
+        this.db.prepare(`
+      INSERT INTO meta_trends (cycle, learning_rate, discovery_rate, knowledge_quality, gap_closure_rate,
+        total_principles, total_hypotheses, prediction_accuracy, emergence_count)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(cycle, learningRate, discoveryRate, knowledgeQuality, gapClosureRate, stats.totalPrinciples, stats.totalHypotheses, stats.predictionAccuracy, stats.emergenceCount);
+        this.log.debug(`[metacognition] Recorded trend for cycle ${cycle}: lr=${learningRate.toFixed(4)}, dr=${discoveryRate.toFixed(4)}`);
+    }
+    /** Get trend data from the last N cycles. */
+    getMetaTrend(windowCycles = 20) {
+        const rows = this.db.prepare(`
+      SELECT cycle, learning_rate, discovery_rate, knowledge_quality, gap_closure_rate,
+        total_principles, total_hypotheses, prediction_accuracy, emergence_count, timestamp
+      FROM meta_trends ORDER BY cycle DESC LIMIT ?
+    `).all(windowCycles);
+        return rows.map(r => this.toMetaTrend(r)).reverse(); // Chronological order
+    }
+    /** Long-term analysis: aggregate over a time period and determine trend direction. */
+    getLongTermAnalysis(days = 7) {
+        const rows = this.db.prepare(`
+      SELECT learning_rate, discovery_rate, knowledge_quality, gap_closure_rate
+      FROM meta_trends
+      WHERE timestamp >= datetime('now', '-' || ? || ' days')
+      ORDER BY cycle ASC
+    `).all(days);
+        if (rows.length === 0) {
+            return {
+                days,
+                avgLearningRate: 0,
+                avgDiscoveryRate: 0,
+                avgKnowledgeQuality: 0,
+                avgGapClosureRate: 0,
+                trendDirection: 'stagnating',
+                peakLearningRate: 0,
+                peakDiscoveryRate: 0,
+            };
+        }
+        let sumLR = 0, sumDR = 0, sumKQ = 0, sumGCR = 0;
+        let peakLR = 0, peakDR = 0;
+        for (const r of rows) {
+            const lr = r.learning_rate;
+            const dr = r.discovery_rate;
+            const kq = r.knowledge_quality;
+            const gcr = r.gap_closure_rate;
+            sumLR += lr;
+            sumDR += dr;
+            sumKQ += kq;
+            sumGCR += gcr;
+            peakLR = Math.max(peakLR, lr);
+            peakDR = Math.max(peakDR, dr);
+        }
+        const n = rows.length;
+        const avgLR = sumLR / n;
+        const avgDR = sumDR / n;
+        const avgKQ = sumKQ / n;
+        const avgGCR = sumGCR / n;
+        // Determine direction by comparing first half vs second half
+        const mid = Math.floor(n / 2);
+        let trendDirection = 'stagnating';
+        if (mid > 0 && n - mid > 0) {
+            let firstHalfAvg = 0, secondHalfAvg = 0;
+            for (let i = 0; i < mid; i++) {
+                firstHalfAvg += rows[i].knowledge_quality;
+            }
+            firstHalfAvg /= mid;
+            for (let i = mid; i < n; i++) {
+                secondHalfAvg += rows[i].knowledge_quality;
+            }
+            secondHalfAvg /= (n - mid);
+            const diff = secondHalfAvg - firstHalfAvg;
+            if (diff > 0.05)
+                trendDirection = 'rising';
+            else if (diff < -0.05)
+                trendDirection = 'falling';
+            else
+                trendDirection = 'stagnating';
+        }
+        return {
+            days,
+            avgLearningRate: avgLR,
+            avgDiscoveryRate: avgDR,
+            avgKnowledgeQuality: avgKQ,
+            avgGapClosureRate: avgGCR,
+            trendDirection,
+            peakLearningRate: peakLR,
+            peakDiscoveryRate: peakDR,
+        };
+    }
+    /** Detect seasonal patterns: which hours/days produce the best metrics. */
+    detectSeasonalPatterns() {
+        const patterns = [];
+        const metrics = ['learning_rate', 'discovery_rate', 'knowledge_quality', 'gap_closure_rate'];
+        for (const metric of metrics) {
+            // Peak hour of day
+            const hourPeak = this.db.prepare(`
+        SELECT CAST(strftime('%H', timestamp) AS INTEGER) as hour, AVG(${metric}) as avg_val
+        FROM meta_trends
+        GROUP BY hour
+        ORDER BY avg_val DESC
+        LIMIT 1
+      `).get();
+            // Peak day of week (0=Sunday, 6=Saturday)
+            const dayPeak = this.db.prepare(`
+        SELECT CAST(strftime('%w', timestamp) AS INTEGER) as dow, AVG(${metric}) as avg_val
+        FROM meta_trends
+        GROUP BY dow
+        ORDER BY avg_val DESC
+        LIMIT 1
+      `).get();
+            if (hourPeak && dayPeak) {
+                patterns.push({
+                    metric: metric.replace(/_/g, ' '),
+                    peakHour: hourPeak.hour,
+                    peakDayOfWeek: dayPeak.dow,
+                    avgAtPeak: hourPeak.avg_val,
+                });
+            }
+        }
+        return patterns;
+    }
+    // ── Meta-Trend Helpers ─────────────────────────────────
+    toMetaTrend(row) {
+        return {
+            cycle: row.cycle,
+            learningRate: row.learning_rate,
+            discoveryRate: row.discovery_rate,
+            knowledgeQuality: row.knowledge_quality,
+            gapClosureRate: row.gap_closure_rate,
+            totalPrinciples: row.total_principles,
+            totalHypotheses: row.total_hypotheses,
+            predictionAccuracy: row.prediction_accuracy,
+            emergenceCount: row.emergence_count,
+            timestamp: row.timestamp,
+        };
+    }
+    getLatestTrend() {
+        const row = this.db.prepare(`
+      SELECT cycle, learning_rate, discovery_rate, knowledge_quality, gap_closure_rate,
+        total_principles, total_hypotheses, prediction_accuracy, emergence_count, timestamp
+      FROM meta_trends ORDER BY cycle DESC LIMIT 1
+    `).get();
+        return row ? this.toMetaTrend(row) : null;
+    }
+    getCurrentTrendDirection() {
+        const rows = this.db.prepare(`
+      SELECT knowledge_quality FROM meta_trends ORDER BY cycle DESC LIMIT 10
+    `).all();
+        if (rows.length < 4)
+            return 'stagnating';
+        const mid = Math.floor(rows.length / 2);
+        // rows are DESC, so first half = recent, second half = older
+        let recentAvg = 0, olderAvg = 0;
+        for (let i = 0; i < mid; i++)
+            recentAvg += rows[i].knowledge_quality;
+        recentAvg /= mid;
+        for (let i = mid; i < rows.length; i++)
+            olderAvg += rows[i].knowledge_quality;
+        olderAvg /= (rows.length - mid);
+        const diff = recentAvg - olderAvg;
+        if (diff > 0.05)
+            return 'rising';
+        if (diff < -0.05)
+            return 'falling';
+        return 'stagnating';
+    }
+    /** Get status summary. */
+    getStatus() {
+        const cards = this.getLatestReportCards();
+        const recentAdj = this.db.prepare(`
+      SELECT engine, old_frequency, new_frequency, reason, created_at
+      FROM cycle_frequency_adjustments ORDER BY id DESC LIMIT 10
+    `).all();
+        const totalMetrics = this.db.prepare('SELECT COUNT(*) as c FROM engine_metrics').get().c;
+        return {
+            totalEngines: cards.length,
+            reportCards: cards,
+            recentAdjustments: recentAdj,
+            cycleMetrics: totalMetrics,
+            latestTrend: this.getLatestTrend(),
+            trendDirection: this.getCurrentTrendDirection(),
+        };
+    }
+    scoreToGrade(score) {
+        if (score >= 0.8)
+            return 'A';
+        if (score >= 0.6)
+            return 'B';
+        if (score >= 0.4)
+            return 'C';
+        if (score >= 0.2)
+            return 'D';
+        return 'F';
+    }
+}
+//# sourceMappingURL=meta-cognition-layer.js.map

package/dist/metacognition/meta-cognition-layer.js.map

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

package/dist/metacognition/parameter-registry.d.ts

@@ -0,0 +1,71 @@
+import type Database from 'better-sqlite3';
+export interface ParameterDefinition {
+    engine: string;
+    name: string;
+    value: number;
+    min: number;
+    max: number;
+    description: string;
+    category?: string;
+}
+export interface ParameterChange {
+    id?: number;
+    engine: string;
+    name: string;
+    old_value: number;
+    new_value: number;
+    changed_by: string;
+    reason: string;
+    created_at?: string;
+}
+export interface ParameterSnapshot {
+    id?: number;
+    label: string;
+    data_json: string;
+    created_at?: string;
+}
+export interface RegisteredParameter {
+    engine: string;
+    name: string;
+    value: number;
+    min: number;
+    max: number;
+    description: string;
+    category: string;
+}
+export declare function runParameterRegistryMigration(db: Database.Database): void;
+export declare class ParameterRegistry {
+    private db;
+    private log;
+    constructor(db: Database.Database);
+    /** Register a tunable parameter. Inserts if new, does NOT overwrite existing values. */
+    register(def: ParameterDefinition): void;
+    /** Register multiple parameters at once. */
+    registerAll(defs: ParameterDefinition[]): void;
+    /** Get current value. Returns undefined if not registered. */
+    get(engine: string, name: string): number | undefined;
+    /** Get full parameter definition. */
+    getDefinition(engine: string, name: string): RegisteredParameter | undefined;
+    /** Set a parameter value with bounds validation and change tracking. */
+    set(engine: string, name: string, value: number, changedBy: string, reason: string): boolean;
+    /** List all parameters, optionally filtered by engine. */
+    list(engine?: string): RegisteredParameter[];
+    /** Get change history for a parameter. */
+    getHistory(engine: string, name: string, limit?: number): ParameterChange[];
+    /** Get all recent changes across all parameters. */
+    getRecentChanges(limit?: number): ParameterChange[];
+    /** Create a snapshot of all current parameter values. */
+    snapshot(label: string): number;
+    /** Restore parameters from a snapshot. */
+    restore(snapshotId: number, changedBy?: string): number;
+    /** List all snapshots. */
+    listSnapshots(limit?: number): ParameterSnapshot[];
+    /** Get summary stats. */
+    getStatus(): {
+        totalParameters: number;
+        totalChanges: number;
+        totalSnapshots: number;
+        engines: string[];
+        recentChanges: ParameterChange[];
+    };
+}

package/dist/metacognition/parameter-registry.js

@@ -0,0 +1,162 @@
+import { getLogger } from '../utils/logger.js';
+// ── Migration ───────────────────────────────────────────
+export function runParameterRegistryMigration(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS parameter_registry (
+      engine TEXT NOT NULL,
+      name TEXT NOT NULL,
+      value REAL NOT NULL,
+      min_value REAL NOT NULL,
+      max_value REAL NOT NULL,
+      description TEXT NOT NULL DEFAULT '',
+      category TEXT NOT NULL DEFAULT 'general',
+      updated_at TEXT DEFAULT (datetime('now')),
+      PRIMARY KEY (engine, name)
+    );
+
+    CREATE TABLE IF NOT EXISTS parameter_changes (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      engine TEXT NOT NULL,
+      name TEXT NOT NULL,
+      old_value REAL NOT NULL,
+      new_value REAL NOT NULL,
+      changed_by TEXT NOT NULL,
+      reason TEXT NOT NULL DEFAULT '',
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_param_changes_engine ON parameter_changes(engine, name);
+
+    CREATE TABLE IF NOT EXISTS parameter_snapshots (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      label TEXT NOT NULL,
+      data_json TEXT NOT NULL,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+  `);
+}
+// ── Registry ───────────────────────────────────────────
+export class ParameterRegistry {
+    db;
+    log = getLogger();
+    constructor(db) {
+        this.db = db;
+        runParameterRegistryMigration(db);
+    }
+    /** Register a tunable parameter. Inserts if new, does NOT overwrite existing values. */
+    register(def) {
+        const existing = this.db.prepare('SELECT value FROM parameter_registry WHERE engine = ? AND name = ?').get(def.engine, def.name);
+        if (existing)
+            return; // Already registered — keep current value
+        this.db.prepare(`
+      INSERT INTO parameter_registry (engine, name, value, min_value, max_value, description, category)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(def.engine, def.name, def.value, def.min, def.max, def.description, def.category ?? 'general');
+    }
+    /** Register multiple parameters at once. */
+    registerAll(defs) {
+        for (const def of defs)
+            this.register(def);
+    }
+    /** Get current value. Returns undefined if not registered. */
+    get(engine, name) {
+        const row = this.db.prepare('SELECT value FROM parameter_registry WHERE engine = ? AND name = ?').get(engine, name);
+        return row?.value;
+    }
+    /** Get full parameter definition. */
+    getDefinition(engine, name) {
+        const row = this.db.prepare('SELECT engine, name, value, min_value, max_value, description, category FROM parameter_registry WHERE engine = ? AND name = ?').get(engine, name);
+        if (!row)
+            return undefined;
+        return { engine: row.engine, name: row.name, value: row.value, min: row.min_value, max: row.max_value, description: row.description, category: row.category };
+    }
+    /** Set a parameter value with bounds validation and change tracking. */
+    set(engine, name, value, changedBy, reason) {
+        const current = this.db.prepare('SELECT value, min_value, max_value FROM parameter_registry WHERE engine = ? AND name = ?').get(engine, name);
+        if (!current) {
+            this.log.warn(`[parameter-registry] Parameter not found: ${engine}.${name}`);
+            return false;
+        }
+        // Clamp to bounds
+        const clamped = Math.max(current.min_value, Math.min(current.max_value, value));
+        if (clamped === current.value)
+            return false; // No change
+        // Record change
+        this.db.prepare(`
+      INSERT INTO parameter_changes (engine, name, old_value, new_value, changed_by, reason)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(engine, name, current.value, clamped, changedBy, reason);
+        // Update value
+        this.db.prepare(`
+      UPDATE parameter_registry SET value = ?, updated_at = datetime('now') WHERE engine = ? AND name = ?
+    `).run(clamped, engine, name);
+        this.log.info(`[parameter-registry] ${engine}.${name}: ${current.value} → ${clamped} (by ${changedBy}: ${reason})`);
+        return true;
+    }
+    /** List all parameters, optionally filtered by engine. */
+    list(engine) {
+        const query = engine
+            ? 'SELECT engine, name, value, min_value, max_value, description, category FROM parameter_registry WHERE engine = ? ORDER BY engine, name'
+            : 'SELECT engine, name, value, min_value, max_value, description, category FROM parameter_registry ORDER BY engine, name';
+        const rows = (engine ? this.db.prepare(query).all(engine) : this.db.prepare(query).all());
+        return rows.map(r => ({ engine: r.engine, name: r.name, value: r.value, min: r.min_value, max: r.max_value, description: r.description, category: r.category }));
+    }
+    /** Get change history for a parameter. */
+    getHistory(engine, name, limit = 20) {
+        return this.db.prepare(`
+      SELECT id, engine, name, old_value, new_value, changed_by, reason, created_at
+      FROM parameter_changes WHERE engine = ? AND name = ?
+      ORDER BY id DESC LIMIT ?
+    `).all(engine, name, limit);
+    }
+    /** Get all recent changes across all parameters. */
+    getRecentChanges(limit = 50) {
+        return this.db.prepare(`
+      SELECT id, engine, name, old_value, new_value, changed_by, reason, created_at
+      FROM parameter_changes ORDER BY id DESC LIMIT ?
+    `).all(limit);
+    }
+    /** Create a snapshot of all current parameter values. */
+    snapshot(label) {
+        const params = this.list();
+        const data = {};
+        for (const p of params) {
+            if (!data[p.engine])
+                data[p.engine] = {};
+            data[p.engine][p.name] = p.value;
+        }
+        const result = this.db.prepare(`
+      INSERT INTO parameter_snapshots (label, data_json) VALUES (?, ?)
+    `).run(label, JSON.stringify(data));
+        return result.lastInsertRowid;
+    }
+    /** Restore parameters from a snapshot. */
+    restore(snapshotId, changedBy = 'snapshot_restore') {
+        const row = this.db.prepare('SELECT data_json FROM parameter_snapshots WHERE id = ?').get(snapshotId);
+        if (!row)
+            return 0;
+        const data = JSON.parse(row.data_json);
+        let count = 0;
+        for (const [engine, params] of Object.entries(data)) {
+            for (const [name, value] of Object.entries(params)) {
+                if (this.set(engine, name, value, changedBy, `Restored from snapshot #${snapshotId}`)) {
+                    count++;
+                }
+            }
+        }
+        return count;
+    }
+    /** List all snapshots. */
+    listSnapshots(limit = 20) {
+        return this.db.prepare('SELECT id, label, data_json, created_at FROM parameter_snapshots ORDER BY id DESC LIMIT ?').all(limit);
+    }
+    /** Get summary stats. */
+    getStatus() {
+        const totalParams = this.db.prepare('SELECT COUNT(*) as c FROM parameter_registry').get().c;
+        const totalChanges = this.db.prepare('SELECT COUNT(*) as c FROM parameter_changes').get().c;
+        const totalSnapshots = this.db.prepare('SELECT COUNT(*) as c FROM parameter_snapshots').get().c;
+        const engines = this.db.prepare('SELECT DISTINCT engine FROM parameter_registry ORDER BY engine').all().map(r => r.engine);
+        const recentChanges = this.getRecentChanges(10);
+        return { totalParameters: totalParams, totalChanges, totalSnapshots, engines, recentChanges };
+    }
+}
+//# sourceMappingURL=parameter-registry.js.map

package/dist/metacognition/parameter-registry.js.map

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