@obsidicore/cascade-engine 0.2.0

package/dist/cascade/gates.js

@@ -0,0 +1,199 @@
+/**
+ * Quality Gates — Evaluation between cascade phases
+ *
+ * Four stopping gates (information-theoretic):
+ * 1. Compression plateau — MDL not decreasing
+ * 2. Diminishing returns — new findings below threshold
+ * 3. Entropy floor — knowledge graph structure stabilized
+ * 4. MDL increasing — model growing without explanatory gain
+ *
+ * Plus inter-phase gates that validate readiness to advance.
+ */
+import { getDb } from '../db/index.js';
+/**
+ * Check all four stopping conditions.
+ * If ANY gate says stop, cascade should conclude.
+ */
+export function evaluateStoppingGates(cascadeId) {
+    const db = getDb();
+    const cascade = db.prepare('SELECT * FROM cascades WHERE id = ?').get(cascadeId);
+    if (!cascade)
+        throw new Error(`Cascade ${cascadeId} not found`);
+    const gates = [];
+    // 1. Max rounds reached
+    const roundGate = {
+        gate: 'max_rounds',
+        passed: cascade.current_round < cascade.max_rounds,
+        value: cascade.current_round,
+        threshold: cascade.max_rounds,
+        description: `Round ${cascade.current_round}/${cascade.max_rounds}`,
+    };
+    gates.push(roundGate);
+    // 2. Token budget exhausted
+    const tokenGate = {
+        gate: 'token_budget',
+        passed: cascade.tokens_used < cascade.token_budget,
+        value: cascade.tokens_used,
+        threshold: cascade.token_budget,
+        description: `Tokens ${cascade.tokens_used}/${cascade.token_budget}`,
+    };
+    gates.push(tokenGate);
+    // 3. Diminishing returns — compare findings count between last 2 rounds
+    const findingsByRound = db.prepare(`SELECT cascade_round, COUNT(*) as n
+    FROM findings WHERE cascade_id = ? AND quarantined = 0
+    GROUP BY cascade_round ORDER BY cascade_round DESC LIMIT 2`)
+        .all(cascadeId);
+    if (findingsByRound.length >= 2) {
+        const currentRoundFindings = findingsByRound[0].n;
+        const prevRoundFindings = findingsByRound[1].n;
+        const ratio = prevRoundFindings > 0 ? currentRoundFindings / prevRoundFindings : 1;
+        const dimGate = {
+            gate: 'diminishing_returns',
+            passed: ratio > 0.3, // Stop if new findings < 30% of previous round
+            value: ratio,
+            threshold: 0.3,
+            description: `New findings ratio: ${Math.round(ratio * 100)}% (${currentRoundFindings} vs ${prevRoundFindings})`,
+        };
+        gates.push(dimGate);
+    }
+    // 4. Confidence convergence — average confidence above threshold
+    const avgConf = db.prepare(`SELECT AVG(confidence) as avg_conf
+    FROM findings WHERE cascade_id = ? AND quarantined = 0`)
+        .get(cascadeId);
+    if (avgConf?.avg_conf !== null) {
+        const confGate = {
+            gate: 'confidence_convergence',
+            passed: avgConf.avg_conf < 0.85, // Stop if avg confidence very high (saturated)
+            value: avgConf.avg_conf,
+            threshold: 0.85,
+            description: `Avg confidence: ${Math.round(avgConf.avg_conf * 1000) / 1000}`,
+        };
+        gates.push(confGate);
+    }
+    // 5. Entropy convergence — check recent entropy metrics
+    const entropyMetrics = db.prepare(`SELECT metric_value FROM metrics
+    WHERE cascade_id = ? AND metric_name = 'entropy'
+    ORDER BY recorded_at DESC LIMIT 3`)
+        .all(cascadeId);
+    if (entropyMetrics.length >= 3) {
+        const deltas = [];
+        for (let i = 0; i < entropyMetrics.length - 1; i++) {
+            deltas.push(Math.abs(entropyMetrics[i].metric_value - entropyMetrics[i + 1].metric_value));
+        }
+        const avgDelta = deltas.reduce((s, d) => s + d, 0) / deltas.length;
+        const entropyGate = {
+            gate: 'entropy_floor',
+            passed: avgDelta > 0.01, // Stop if entropy change < 1%
+            value: avgDelta,
+            threshold: 0.01,
+            description: `Entropy delta: ${Math.round(avgDelta * 10000) / 10000}`,
+        };
+        gates.push(entropyGate);
+    }
+    const shouldStop = gates.some(g => !g.passed);
+    let recommendation = 'Continue research.';
+    if (shouldStop) {
+        const failedGates = gates.filter(g => !g.passed).map(g => g.gate);
+        recommendation = `Stop: ${failedGates.join(', ')}. ${failedGates.includes('max_rounds') ? 'Maximum rounds reached.' :
+            failedGates.includes('token_budget') ? 'Token budget exhausted.' :
+                failedGates.includes('diminishing_returns') ? 'New findings dropping sharply — research saturated.' :
+                    failedGates.includes('confidence_convergence') ? 'High confidence across findings — answers converged.' :
+                        'Knowledge graph structure stabilized.'}`;
+    }
+    return { shouldStop, gates, recommendation };
+}
+/**
+ * Validate readiness to advance from one phase to the next.
+ * Returns issues that should be resolved before advancing.
+ */
+export function validatePhaseGate(cascadeId, fromPhase, toPhase) {
+    const db = getDb();
+    const issues = [];
+    switch (fromPhase) {
+        case 'identify': {
+            // Need at least 1 thread created
+            const threads = db.prepare('SELECT COUNT(*) as n FROM threads WHERE cascade_id = ? AND status IN (\'active\',\'done\')').get(cascadeId).n;
+            if (threads === 0)
+                issues.push('No research threads created. Decompose the question into sub-questions first.');
+            break;
+        }
+        case 'screen': {
+            // Need findings to have been screened (trust scores applied)
+            const unscored = db.prepare('SELECT COUNT(*) as n FROM findings WHERE cascade_id = ? AND trust_composite = 0.5 AND trust_signals_json IS NULL').get(cascadeId).n;
+            if (unscored > 0)
+                issues.push(`${unscored} findings haven't been trust-scored yet.`);
+            break;
+        }
+        case 'evaluate': {
+            // Need at least some findings with confidence > 0
+            const evaluated = db.prepare('SELECT COUNT(*) as n FROM findings WHERE cascade_id = ? AND quarantined = 0').get(cascadeId).n;
+            if (evaluated === 0)
+                issues.push('No non-quarantined findings. All findings were rejected or quarantined.');
+            break;
+        }
+        case 'consolidate': {
+            // Just check we have entities in the graph
+            // (consolidation creates entities — so this is post-facto)
+            break;
+        }
+        case 'mature': {
+            // Need at least 1 hypothesis
+            const hyps = db.prepare('SELECT COUNT(*) as n FROM hypotheses WHERE cascade_id = ?').get(cascadeId).n;
+            if (hyps === 0)
+                issues.push('No hypotheses to mature. Create at least one hypothesis from findings.');
+            break;
+        }
+        case 'prune': {
+            // No hard requirements — pruning is optional
+            break;
+        }
+        case 'synthesize': {
+            // Need findings to synthesize
+            const findings = db.prepare('SELECT COUNT(*) as n FROM findings WHERE cascade_id = ? AND quarantined = 0').get(cascadeId).n;
+            if (findings === 0)
+                issues.push('No findings to synthesize.');
+            break;
+        }
+        case 'observe': {
+            // Terminal — check stopping conditions
+            break;
+        }
+    }
+    return { ready: issues.length === 0, issues };
+}
+/**
+ * Calculate information-theoretic metrics for the current round.
+ */
+export function calculateRoundMetrics(cascadeId) {
+    const db = getDb();
+    const cascade = db.prepare('SELECT * FROM cascades WHERE id = ?').get(cascadeId);
+    if (!cascade)
+        throw new Error(`Cascade ${cascadeId} not found`);
+    const plan = cascade.plan_json ? JSON.parse(cascade.plan_json) : null;
+    const totalQuestions = plan?.questions?.length || 1;
+    // Coverage: what fraction of questions have findings
+    const questionsWithFindings = db.prepare(`SELECT COUNT(DISTINCT t.question) as n
+    FROM threads t JOIN findings f ON t.id = f.thread_id
+    WHERE t.cascade_id = ? AND f.quarantined = 0`)
+        .get(cascadeId);
+    const coverage = Math.min(1, (questionsWithFindings?.n || 0) / totalQuestions);
+    // Depth: average findings per question
+    const totalFindings = db.prepare('SELECT COUNT(*) as n FROM findings WHERE cascade_id = ? AND quarantined = 0').get(cascadeId).n;
+    const depth = Math.min(1, totalFindings / (totalQuestions * 10)); // 10 findings/question = max depth
+    // Confidence: average confidence of non-quarantined findings
+    const avgConf = db.prepare('SELECT AVG(confidence) as v FROM findings WHERE cascade_id = ? AND quarantined = 0').get(cascadeId)?.v || 0;
+    // Source quality: average trust score
+    const avgTrust = db.prepare('SELECT AVG(trust_composite) as v FROM findings WHERE cascade_id = ? AND quarantined = 0').get(cascadeId)?.v || 0.5;
+    // Graph density: 2|E|/(|V|(|V|-1)) — but capped at 1
+    const V = db.prepare('SELECT COUNT(*) as n FROM kg_entities').get().n;
+    const E = db.prepare('SELECT COUNT(*) as n FROM kg_edges').get().n;
+    const graphDensity = V > 1 ? Math.min(1, (2 * E) / (V * (V - 1))) : 0;
+    return {
+        coverage,
+        depth,
+        confidence: avgConf,
+        sourceQuality: avgTrust,
+        graphDensity,
+    };
+}
+//# sourceMappingURL=gates.js.map

package/dist/cascade/gates.js.map

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

package/dist/cascade/research.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Research Integration — Search/fetch pipeline
+ *
+ * Provides structured interfaces for research operations.
+ * The LLM performs actual web_search/web_fetch — this module
+ * structures the inputs/outputs and tracks the process.
+ */
+export interface SearchPlan {
+    cascadeId: string;
+    roundIndex: number;
+    queries: SearchQuery[];
+    explorationBudget: number;
+}
+export interface SearchQuery {
+    query: string;
+    type: 'exploration' | 'exploitation' | 'validation';
+    priority: number;
+    threadId?: string;
+}
+export interface RawFinding {
+    claim: string;
+    evidence?: string;
+    sourceUrl?: string;
+    sourceType?: 'primary' | 'secondary' | 'tertiary';
+    rawConfidence?: number;
+}
+/**
+ * Build a search plan from cascade state.
+ * Generates queries based on questions, existing findings, and gaps.
+ */
+export declare function buildSearchPlan(cascadeId: string): SearchPlan;
+/**
+ * Classify a query to determine which model should handle it.
+ * Returns routing info for multi-model dispatch.
+ */
+export declare function classifyQuery(query: string): {
+    type: 'technical' | 'discovery' | 'classification' | 'validation';
+    suggestedModel: string;
+    suggestedAgent: string;
+    reasoning: string;
+};
+/**
+ * Batch store findings from a research round.
+ * Returns count of new vs duplicate findings.
+ */
+export declare function batchStoreFindings(cascadeId: string, roundIndex: number, threadId: string | undefined, findings: RawFinding[]): {
+    stored: number;
+    duplicates: number;
+};
+//# sourceMappingURL=research.d.ts.map

package/dist/cascade/research.js

@@ -0,0 +1,127 @@
+/**
+ * Research Integration — Search/fetch pipeline
+ *
+ * Provides structured interfaces for research operations.
+ * The LLM performs actual web_search/web_fetch — this module
+ * structures the inputs/outputs and tracks the process.
+ */
+import { getDb, contentHash } from '../db/index.js';
+// --- Functions ---
+/**
+ * Build a search plan from cascade state.
+ * Generates queries based on questions, existing findings, and gaps.
+ */
+export function buildSearchPlan(cascadeId) {
+    const db = getDb();
+    const cascade = db.prepare('SELECT * FROM cascades WHERE id = ?').get(cascadeId);
+    if (!cascade)
+        throw new Error(`Cascade ${cascadeId} not found`);
+    const plan = cascade.plan_json ? JSON.parse(cascade.plan_json) : null;
+    const questions = plan?.questions || [cascade.question];
+    const roundIndex = cascade.current_round;
+    const budget = Math.max(0, 1 - roundIndex / cascade.max_rounds);
+    const queries = [];
+    // Round 0 (SEED): all questions are exploration
+    if (roundIndex === 0) {
+        for (const q of questions) {
+            queries.push({ query: q, type: 'exploration', priority: 1.0 });
+        }
+    }
+    else {
+        // Later rounds: mix of exploration, exploitation, validation
+        const explorationCount = Math.ceil(questions.length * budget);
+        // Exploration: questions without enough findings
+        const threadCoverage = db.prepare(`SELECT t.question, COUNT(f.id) as finding_count
+      FROM threads t LEFT JOIN findings f ON t.id = f.thread_id AND f.quarantined = 0
+      WHERE t.cascade_id = ?
+      GROUP BY t.question
+      ORDER BY finding_count ASC`)
+            .all(cascadeId);
+        for (let i = 0; i < Math.min(explorationCount, threadCoverage.length); i++) {
+            queries.push({
+                query: threadCoverage[i].question,
+                type: 'exploration',
+                priority: 1.0 - i * 0.1,
+            });
+        }
+        // Exploitation: deepen high-confidence threads
+        const highConfThreads = db.prepare(`SELECT t.id, t.question, AVG(f.confidence) as avg_conf
+      FROM threads t JOIN findings f ON t.id = f.thread_id
+      WHERE t.cascade_id = ? AND f.quarantined = 0
+      GROUP BY t.id
+      HAVING avg_conf > 0.5
+      ORDER BY avg_conf DESC LIMIT 3`)
+            .all(cascadeId);
+        for (const thread of highConfThreads) {
+            queries.push({
+                query: thread.question,
+                type: 'exploitation',
+                priority: thread.avg_conf,
+                threadId: thread.id,
+            });
+        }
+        // Validation: cross-check low-confidence findings
+        const lowConfFindings = db.prepare(`SELECT claim FROM findings
+      WHERE cascade_id = ? AND quarantined = 0 AND confidence < 0.5
+      ORDER BY confidence ASC LIMIT 3`)
+            .all(cascadeId);
+        for (const f of lowConfFindings) {
+            queries.push({
+                query: `verify: ${f.claim}`,
+                type: 'validation',
+                priority: 0.8,
+            });
+        }
+    }
+    // Sort by priority
+    queries.sort((a, b) => b.priority - a.priority);
+    return { cascadeId, roundIndex, queries, explorationBudget: budget };
+}
+/**
+ * Classify a query to determine which model should handle it.
+ * Returns routing info for multi-model dispatch.
+ */
+export function classifyQuery(query) {
+    const lower = query.toLowerCase();
+    // Classification heuristics (simple — LLM should refine these)
+    if (lower.includes('verify') || lower.includes('validate') || lower.includes('confirm') || lower.includes('cross-check')) {
+        return { type: 'validation', suggestedModel: 'sonnet', suggestedAgent: 'cross-validator', reasoning: 'Validation query — cross-reference with independent sources' };
+    }
+    if (lower.includes('how') || lower.includes('implementation') || lower.includes('architecture') || lower.includes('benchmark') || lower.includes('performance')) {
+        return { type: 'technical', suggestedModel: 'opus', suggestedAgent: 'deep-investigator', reasoning: 'Technical deep-dive — needs strong reasoning' };
+    }
+    if (lower.includes('what if') || lower.includes('could') || lower.includes('explore') || lower.includes('design') || lower.includes('philosophy')) {
+        return { type: 'discovery', suggestedModel: 'sonnet', suggestedAgent: 'research-planner', reasoning: 'Discovery/open-ended — benefits from diverse exploration' };
+    }
+    if (lower.includes('categorize') || lower.includes('sort') || lower.includes('tag') || lower.includes('extract')) {
+        return { type: 'classification', suggestedModel: 'haiku', suggestedAgent: 'research-planner', reasoning: 'Classification task — lightweight model sufficient' };
+    }
+    // Default: technical
+    return { type: 'technical', suggestedModel: 'sonnet', suggestedAgent: 'deep-investigator', reasoning: 'Default routing — general research query' };
+}
+/**
+ * Batch store findings from a research round.
+ * Returns count of new vs duplicate findings.
+ */
+export function batchStoreFindings(cascadeId, roundIndex, threadId, findings) {
+    const db = getDb();
+    let stored = 0;
+    let duplicates = 0;
+    const insertStmt = db.prepare(`INSERT INTO findings (id, thread_id, cascade_id, claim, evidence, source_url, source_type, confidence, cascade_round)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET confidence = MAX(confidence, excluded.confidence)`);
+    const transaction = db.transaction(() => {
+        for (const f of findings) {
+            const id = contentHash(f.claim);
+            const existing = db.prepare('SELECT id FROM findings WHERE id = ?').get(id);
+            insertStmt.run(id, threadId, cascadeId, f.claim, f.evidence, f.sourceUrl, f.sourceType, f.rawConfidence ?? 0.5, roundIndex);
+            if (existing)
+                duplicates++;
+            else
+                stored++;
+        }
+    });
+    transaction();
+    return { stored, duplicates };
+}
+//# sourceMappingURL=research.js.map

package/dist/cascade/research.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * cascade-engine CLI
+ *
+ * Usage:
+ *   cascade-engine serve          Start MCP stdio server (default)
+ *   cascade-engine status         Show active cascades and DB stats
+ *   cascade-engine status <id>    Show detailed cascade status
+ *   cascade-engine graph          Show knowledge graph stats
+ *   cascade-engine notes          Show Zettelkasten note stats
+ *   cascade-engine reset          Delete the database and start fresh
+ *   cascade-engine db-path        Print the database file path
+ *   cascade-engine help           Show this help
+ *
+ * Environment:
+ *   CASCADE_DB_PATH   Override database location (default: ~/.cascade-engine/knowledge.db)
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * cascade-engine CLI
+ *
+ * Usage:
+ *   cascade-engine serve          Start MCP stdio server (default)
+ *   cascade-engine status         Show active cascades and DB stats
+ *   cascade-engine status <id>    Show detailed cascade status
+ *   cascade-engine graph          Show knowledge graph stats
+ *   cascade-engine notes          Show Zettelkasten note stats
+ *   cascade-engine reset          Delete the database and start fresh
+ *   cascade-engine db-path        Print the database file path
+ *   cascade-engine help           Show this help
+ *
+ * Environment:
+ *   CASCADE_DB_PATH   Override database location (default: ~/.cascade-engine/knowledge.db)
+ */
+import { getDb, closeDb } from './db/index.js';
+import { getGraphStats } from './graph/entities.js';
+import { getNoteStats } from './graph/amem.js';
+import { existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+const args = process.argv.slice(2);
+const command = args[0] || 'serve';
+async function main() {
+    switch (command) {
+        case 'serve':
+        case 'start': {
+            // Dynamic import to avoid loading the full MCP server for other commands
+            const { default: startServer } = await import('./server.js');
+            await startServer();
+            break;
+        }
+        case 'status': {
+            const db = getDb();
+            const cascadeId = args[1];
+            if (cascadeId) {
+                const cascade = db.prepare('SELECT * FROM cascades WHERE id = ? OR id LIKE ?')
+                    .get(cascadeId, `${cascadeId}%`);
+                if (!cascade) {
+                    console.log(`Cascade "${cascadeId}" not found.`);
+                    break;
+                }
+                const findings = db.prepare('SELECT COUNT(*) as n FROM findings WHERE cascade_id = ? AND quarantined = 0').get(cascade.id).n;
+                const quarantined = db.prepare('SELECT COUNT(*) as n FROM findings WHERE cascade_id = ? AND quarantined = 1').get(cascade.id).n;
+                const hypotheses = db.prepare('SELECT COUNT(*) as n FROM hypotheses WHERE cascade_id = ?').get(cascade.id).n;
+                console.log(`Cascade: ${cascade.id}`);
+                console.log(`Question: ${cascade.question}`);
+                console.log(`Status: ${cascade.status}`);
+                console.log(`Round: ${cascade.current_round}/${cascade.max_rounds}`);
+                console.log(`Findings: ${findings} (${quarantined} quarantined)`);
+                console.log(`Hypotheses: ${hypotheses}`);
+                console.log(`Tokens: ${cascade.tokens_used}/${cascade.token_budget}`);
+                console.log(`Created: ${cascade.created_at}`);
+            }
+            else {
+                const cascades = db.prepare("SELECT id, question, status, current_round, max_rounds, created_at FROM cascades ORDER BY updated_at DESC").all();
+                if (cascades.length === 0) {
+                    console.log('No cascades found. Start one with cascade_init.');
+                }
+                else {
+                    console.log(`${cascades.length} cascade(s):\n`);
+                    for (const c of cascades) {
+                        console.log(`  ${c.id.slice(0, 8)}  ${c.status.padEnd(13)} R${c.current_round}/${c.max_rounds}  ${c.question.slice(0, 60)}`);
+                    }
+                }
+                const findings = db.prepare('SELECT COUNT(*) as n FROM findings').get().n;
+                const entities = db.prepare('SELECT COUNT(*) as n FROM kg_entities').get().n;
+                const edges = db.prepare('SELECT COUNT(*) as n FROM kg_edges').get().n;
+                console.log(`\nDB totals: ${findings} findings, ${entities} entities, ${edges} edges`);
+            }
+            closeDb();
+            break;
+        }
+        case 'graph': {
+            const stats = getGraphStats();
+            console.log('Knowledge Graph:');
+            console.log(`  Entities: ${stats.entityCount}`);
+            console.log(`  Edges: ${stats.edgeCount}`);
+            console.log(`  Avg degree: ${stats.avgDegree.toFixed(2)}`);
+            console.log(`  Communities: ${stats.communityCounts}`);
+            console.log(`  Orphans: ${stats.orphanCount}`);
+            console.log(`  Tiers: ${JSON.stringify(stats.tierCounts)}`);
+            closeDb();
+            break;
+        }
+        case 'notes': {
+            const stats = getNoteStats();
+            console.log('Zettelkasten Notes:');
+            console.log(`  Total: ${stats.totalNotes}`);
+            console.log(`  Links: ${stats.totalLinks}`);
+            console.log(`  Orphans: ${stats.orphanCount}`);
+            console.log(`  Maturity: ${JSON.stringify(stats.maturityCounts)}`);
+            console.log(`  Types: ${JSON.stringify(stats.typeCounts)}`);
+            closeDb();
+            break;
+        }
+        case 'db-path': {
+            const home = process.env.HOME || process.env.USERPROFILE || '';
+            const dbPath = process.env.CASCADE_DB_PATH || join(home, '.cascade-engine', 'knowledge.db');
+            console.log(dbPath);
+            break;
+        }
+        case 'reset': {
+            const home = process.env.HOME || process.env.USERPROFILE || '';
+            const dbPath = process.env.CASCADE_DB_PATH || join(home, '.cascade-engine', 'knowledge.db');
+            if (existsSync(dbPath)) {
+                unlinkSync(dbPath);
+                // Clean up WAL and SHM files
+                if (existsSync(dbPath + '-wal'))
+                    unlinkSync(dbPath + '-wal');
+                if (existsSync(dbPath + '-shm'))
+                    unlinkSync(dbPath + '-shm');
+                console.log(`Deleted: ${dbPath}`);
+            }
+            else {
+                console.log('No database found.');
+            }
+            break;
+        }
+        case 'help':
+        case '--help':
+        case '-h': {
+            console.log(`cascade-engine — Progressive deep research MCP server
+
+Usage:
+  cascade-engine serve          Start MCP stdio server (default)
+  cascade-engine status         Show active cascades and DB stats
+  cascade-engine status <id>    Detailed cascade status
+  cascade-engine graph          Knowledge graph statistics
+  cascade-engine notes          Zettelkasten note statistics
+  cascade-engine db-path        Print database file path
+  cascade-engine reset          Delete database and start fresh
+  cascade-engine help           Show this help
+
+MCP Integration:
+  Add to your .mcp.json (Claude Code) or equivalent:
+
+  {
+    "mcpServers": {
+      "cascade-engine": {
+        "command": "cascade-engine",
+        "args": ["serve"]
+      }
+    }
+  }
+
+Environment:
+  CASCADE_DB_PATH   Override database location
+                    Default: ~/.cascade-engine/knowledge.db
+
+More info: https://github.com/geoff-obsidicore/Research-Cascade`);
+            break;
+        }
+        default:
+            console.error(`Unknown command: ${command}`);
+            console.error('Run "cascade-engine help" for usage.');
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error('Fatal:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/control/kalman.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Kalman Filter — Confidence fusion from multiple noisy sources
+ *
+ * K = P / (P + R)
+ * confidence += K × (measurement - confidence)
+ * uncertainty = (1 - K) × P
+ *
+ * High R (unreliable source) → low K → measurement discounted
+ * High P (uncertain claim) → high K → updated aggressively
+ */
+export interface KalmanState {
+    estimate: number;
+    uncertainty: number;
+}
+/**
+ * Create initial Kalman state for a new finding.
+ */
+export declare function createKalmanState(initialEstimate?: number, initialUncertainty?: number): KalmanState;
+/**
+ * Update Kalman estimate with a new measurement.
+ *
+ * @param state Current Kalman state
+ * @param measurement New confidence measurement (0-1)
+ * @param measurementNoise R — noise of the measurement source (higher = less reliable)
+ * @returns Updated state
+ */
+export declare function kalmanUpdate(state: KalmanState, measurement: number, measurementNoise: number): KalmanState;
+/**
+ * Fuse multiple measurements at once.
+ * Each measurement has its own noise level based on source reliability.
+ */
+export declare function fuseConfidence(measurements: {
+    value: number;
+    noise: number;
+}[], initialEstimate?: number, initialUncertainty?: number): KalmanState;
+/**
+ * Map source type to measurement noise.
+ * Lower noise = more trusted source.
+ */
+export declare function sourceToNoise(sourceType: string | undefined, trustScore: number): number;
+/**
+ * Batch update: apply multiple findings' confidence to a single claim.
+ * Returns the fused confidence and remaining uncertainty.
+ */
+export declare function batchFuseForClaim(existingConfidence: number, existingUncertainty: number, newMeasurements: {
+    confidence: number;
+    sourceType?: string;
+    trustScore: number;
+}[]): {
+    confidence: number;
+    uncertainty: number;
+};
+//# sourceMappingURL=kalman.d.ts.map