@obsidicore/cascade-engine 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Obsidicore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cascade/checkpoints.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Step-Level Checkpointing
+ *
+ * Every step is checkpointed independently — crash loses only the current step.
+ * Idempotent upserts via content-addressable keys + ON CONFLICT DO UPDATE.
+ * Buffer in SQLite, commit to JSONL only after step completes.
+ */
+import { CascadeRoundState, CascadePhase } from './engine.js';
+export interface Checkpoint {
+    taskId: string;
+    roundIndex: number;
+    stepIndex: number;
+    stepName: string;
+    status: 'pending' | 'running' | 'done' | 'failed' | 'skipped';
+    stateSnapshot?: string;
+    errorMessage?: string;
+    createdAt: string;
+    completedAt?: string;
+}
+/**
+ * Save a checkpoint for the current step.
+ */
+export declare function saveCheckpoint(state: CascadeRoundState, status: Checkpoint['status'], errorMessage?: string): void;
+/**
+ * Get all checkpoints for a cascade, organized by round.
+ */
+export declare function getCheckpoints(cascadeId: string): Record<number, Checkpoint[]>;
+/**
+ * Find the last successful checkpoint to resume from.
+ */
+export declare function findResumePoint(cascadeId: string): {
+    roundIndex: number;
+    phase: CascadePhase;
+    state: CascadeRoundState | null;
+} | null;
+/**
+ * Check idempotency cache for a previously computed result.
+ */
+export declare function checkIdempotency(key: string): any | null;
+/**
+ * Store a result in the idempotency cache.
+ */
+export declare function cacheIdempotent(key: string, result: any, ttlMinutes?: number): void;
+/**
+ * Get a compact progress summary for the cascade.
+ */
+export declare function getProgressSummary(cascadeId: string): {
+    totalRounds: number;
+    completedRounds: number;
+    currentPhase: string;
+    completedSteps: number;
+    failedSteps: number;
+    lastActivity: string;
+};
+//# sourceMappingURL=checkpoints.d.ts.map

package/dist/cascade/checkpoints.js

@@ -0,0 +1,123 @@
+/**
+ * Step-Level Checkpointing
+ *
+ * Every step is checkpointed independently — crash loses only the current step.
+ * Idempotent upserts via content-addressable keys + ON CONFLICT DO UPDATE.
+ * Buffer in SQLite, commit to JSONL only after step completes.
+ */
+import { getDb } from '../db/index.js';
+import { PHASE_ORDER } from './engine.js';
+/**
+ * Save a checkpoint for the current step.
+ */
+export function saveCheckpoint(state, status, errorMessage) {
+    const db = getDb();
+    const idempotencyKey = `${state.cascadeId}:${state.roundIndex}:${state.stepIndex}:${state.phase}`;
+    db.prepare(`INSERT INTO cascade_checkpoints
+    (task_id, round_index, step_index, step_name, status, state_snapshot, idempotency_key, error_message)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(task_id, round_index, step_index) DO UPDATE SET
+      status = excluded.status,
+      state_snapshot = COALESCE(excluded.state_snapshot, state_snapshot),
+      error_message = excluded.error_message,
+      completed_at = CASE WHEN excluded.status IN ('done','failed','skipped') THEN datetime('now') ELSE completed_at END`)
+        .run(state.cascadeId, state.roundIndex, state.stepIndex, state.phase, status, JSON.stringify(state), idempotencyKey, errorMessage);
+}
+/**
+ * Get all checkpoints for a cascade, organized by round.
+ */
+export function getCheckpoints(cascadeId) {
+    const db = getDb();
+    const rows = db.prepare(`SELECT * FROM cascade_checkpoints
+    WHERE task_id = ? ORDER BY round_index, step_index`)
+        .all(cascadeId);
+    const byRound = {};
+    for (const row of rows) {
+        if (!byRound[row.round_index])
+            byRound[row.round_index] = [];
+        byRound[row.round_index].push({
+            taskId: row.task_id,
+            roundIndex: row.round_index,
+            stepIndex: row.step_index,
+            stepName: row.step_name,
+            status: row.status,
+            stateSnapshot: row.state_snapshot,
+            errorMessage: row.error_message,
+            createdAt: row.created_at,
+            completedAt: row.completed_at,
+        });
+    }
+    return byRound;
+}
+/**
+ * Find the last successful checkpoint to resume from.
+ */
+export function findResumePoint(cascadeId) {
+    const db = getDb();
+    const last = db.prepare(`SELECT * FROM cascade_checkpoints
+    WHERE task_id = ? AND status = 'done'
+    ORDER BY round_index DESC, step_index DESC LIMIT 1`)
+        .get(cascadeId);
+    if (!last)
+        return null;
+    const state = last.state_snapshot ? JSON.parse(last.state_snapshot) : null;
+    const phaseIdx = PHASE_ORDER.indexOf(last.step_name);
+    const nextPhase = phaseIdx >= 0 && phaseIdx < PHASE_ORDER.length - 1
+        ? PHASE_ORDER[phaseIdx + 1]
+        : 'identify'; // Start new round
+    return {
+        roundIndex: phaseIdx >= PHASE_ORDER.length - 1 ? last.round_index + 1 : last.round_index,
+        phase: nextPhase,
+        state,
+    };
+}
+/**
+ * Check idempotency cache for a previously computed result.
+ */
+export function checkIdempotency(key) {
+    const db = getDb();
+    // Clean expired entries
+    db.prepare("DELETE FROM idempotency_cache WHERE expires_at IS NOT NULL AND expires_at < datetime('now')").run();
+    const cached = db.prepare('SELECT result_json FROM idempotency_cache WHERE key = ?').get(key);
+    return cached ? JSON.parse(cached.result_json) : null;
+}
+/**
+ * Store a result in the idempotency cache.
+ */
+export function cacheIdempotent(key, result, ttlMinutes = 60) {
+    const db = getDb();
+    db.prepare(`INSERT INTO idempotency_cache (key, result_json, expires_at)
+    VALUES (?, ?, datetime('now', '+' || ? || ' minutes'))
+    ON CONFLICT(key) DO UPDATE SET
+      result_json = excluded.result_json,
+      expires_at = excluded.expires_at`)
+        .run(key, JSON.stringify(result), ttlMinutes);
+}
+/**
+ * Get a compact progress summary for the cascade.
+ */
+export function getProgressSummary(cascadeId) {
+    const db = getDb();
+    const cascade = db.prepare('SELECT current_round, max_rounds FROM cascades WHERE id = ?').get(cascadeId);
+    if (!cascade)
+        throw new Error(`Cascade ${cascadeId} not found`);
+    const stats = db.prepare(`SELECT
+    COUNT(CASE WHEN status = 'done' THEN 1 END) as completed,
+    COUNT(CASE WHEN status = 'failed' THEN 1 END) as failed,
+    MAX(COALESCE(completed_at, created_at)) as last_activity
+    FROM cascade_checkpoints WHERE task_id = ?`)
+        .get(cascadeId);
+    const currentStep = db.prepare(`SELECT step_name FROM cascade_checkpoints
+    WHERE task_id = ? AND status IN ('running','pending')
+    ORDER BY round_index DESC, step_index DESC LIMIT 1`)
+        .get(cascadeId);
+    return {
+        totalRounds: cascade.max_rounds,
+        completedRounds: cascade.current_round,
+        currentPhase: currentStep?.step_name || 'idle',
+        completedSteps: stats?.completed || 0,
+        failedSteps: stats?.failed || 0,
+        lastActivity: stats?.last_activity || 'never',
+    };
+}
+//# sourceMappingURL=checkpoints.js.map

package/dist/cascade/checkpoints.js.map

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

package/dist/cascade/engine.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Cascade Engine — Core FSM Loop
+ *
+ * Implements the research cascade state machine:
+ *   IDENTIFY → SCREEN → EVALUATE → CONSOLIDATE → MATURE → PRUNE → SYNTHESIZE → OBSERVE → (loop|done)
+ *
+ * The AGENT orchestrates. This engine TRACKS STATE.
+ * The engine provides methods that MCP tools call; the LLM decides when/how to call them.
+ */
+export type CascadePhase = 'identify' | 'screen' | 'evaluate' | 'consolidate' | 'mature' | 'prune' | 'synthesize' | 'observe';
+export interface CascadeRoundState {
+    cascadeId: string;
+    roundIndex: number;
+    phase: CascadePhase;
+    stepIndex: number;
+    explorationBudget: number;
+    searchQueries: string[];
+    findingsThisRound: number;
+    startedAt: string;
+}
+export interface StopCondition {
+    name: string;
+    met: boolean;
+    value: number;
+    threshold: number;
+    description: string;
+}
+export declare const PHASE_ORDER: CascadePhase[];
+/**
+ * Initialize a new round of research.
+ * Sets up the round state and calculates exploration budget.
+ */
+export declare function initRound(cascadeId: string): CascadeRoundState;
+/**
+ * Advance to the next phase in the cascade loop.
+ * Returns the new phase, or null if the round is complete.
+ */
+export declare function advancePhase(state: CascadeRoundState): CascadePhase | null;
+/**
+ * Mark current phase as complete.
+ */
+export declare function completePhase(state: CascadeRoundState): void;
+/**
+ * Resume from the last successful checkpoint.
+ */
+export declare function resumeFromCheckpoint(cascadeId: string): CascadeRoundState | null;
+/**
+ * Generate search queries for the IDENTIFY phase.
+ * Uses UCB to balance exploration vs exploitation across threads.
+ */
+export declare function generateSearchPlan(cascadeId: string): {
+    explorationQueries: string[];
+    exploitationQueries: string[];
+};
+/**
+ * Create a research thread (a sub-question being investigated).
+ */
+export declare function createThread(cascadeId: string, question: string, type: 'technical' | 'discovery' | 'classification' | 'validation', agentName?: string, modelUsed?: string): string;
+/**
+ * Complete a thread and update its UCB values.
+ */
+export declare function completeThread(threadId: string, reward: number): void;
+/**
+ * Get round summary for synthesis.
+ */
+export declare function getRoundSummary(cascadeId: string, roundIndex: number): {
+    findings: any[];
+    hypotheses: any[];
+    newEntities: number;
+    newEdges: number;
+};
+//# sourceMappingURL=engine.d.ts.map

package/dist/cascade/engine.js

@@ -0,0 +1,170 @@
+/**
+ * Cascade Engine — Core FSM Loop
+ *
+ * Implements the research cascade state machine:
+ *   IDENTIFY → SCREEN → EVALUATE → CONSOLIDATE → MATURE → PRUNE → SYNTHESIZE → OBSERVE → (loop|done)
+ *
+ * The AGENT orchestrates. This engine TRACKS STATE.
+ * The engine provides methods that MCP tools call; the LLM decides when/how to call them.
+ */
+import { getDb, generateId } from '../db/index.js';
+export const PHASE_ORDER = [
+    'identify', 'screen', 'evaluate', 'consolidate',
+    'mature', 'prune', 'synthesize', 'observe',
+];
+// --- Engine Functions ---
+/**
+ * Initialize a new round of research.
+ * Sets up the round state and calculates exploration budget.
+ */
+export function initRound(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 roundIndex = cascade.current_round;
+    const explorationBudget = Math.max(0, 1 - roundIndex / cascade.max_rounds);
+    const state = {
+        cascadeId,
+        roundIndex,
+        phase: 'identify',
+        stepIndex: 0,
+        explorationBudget,
+        searchQueries: [],
+        findingsThisRound: 0,
+        startedAt: new Date().toISOString(),
+    };
+    // Create checkpoint for round start
+    db.prepare(`INSERT INTO cascade_checkpoints (task_id, round_index, step_index, step_name, status, state_snapshot)
+    VALUES (?, ?, 0, 'round_init', 'done', ?)
+    ON CONFLICT(task_id, round_index, step_index) DO UPDATE SET status = 'done'`)
+        .run(cascadeId, roundIndex, JSON.stringify(state));
+    return state;
+}
+/**
+ * Advance to the next phase in the cascade loop.
+ * Returns the new phase, or null if the round is complete.
+ */
+export function advancePhase(state) {
+    const currentIdx = PHASE_ORDER.indexOf(state.phase);
+    if (currentIdx < 0 || currentIdx >= PHASE_ORDER.length - 1)
+        return null;
+    const nextPhase = PHASE_ORDER[currentIdx + 1];
+    state.phase = nextPhase;
+    state.stepIndex++;
+    // Checkpoint
+    const db = getDb();
+    db.prepare(`INSERT INTO cascade_checkpoints (task_id, round_index, step_index, step_name, status, state_snapshot)
+    VALUES (?, ?, ?, ?, 'running', ?)
+    ON CONFLICT(task_id, round_index, step_index) DO UPDATE SET
+      status = 'running', state_snapshot = excluded.state_snapshot`)
+        .run(state.cascadeId, state.roundIndex, state.stepIndex, nextPhase, JSON.stringify(state));
+    return nextPhase;
+}
+/**
+ * Mark current phase as complete.
+ */
+export function completePhase(state) {
+    const db = getDb();
+    db.prepare(`UPDATE cascade_checkpoints SET status = 'done', completed_at = datetime('now')
+    WHERE task_id = ? AND round_index = ? AND step_index = ?`)
+        .run(state.cascadeId, state.roundIndex, state.stepIndex);
+}
+/**
+ * Resume from the last successful checkpoint.
+ */
+export function resumeFromCheckpoint(cascadeId) {
+    const db = getDb();
+    // Find the last completed checkpoint
+    const last = db.prepare(`SELECT * FROM cascade_checkpoints
+    WHERE task_id = ? AND status = 'done'
+    ORDER BY round_index DESC, step_index DESC LIMIT 1`)
+        .get(cascadeId);
+    if (!last?.state_snapshot)
+        return null;
+    const state = JSON.parse(last.state_snapshot);
+    // Advance past the completed step
+    const nextPhase = advancePhase(state);
+    if (!nextPhase) {
+        // Round was complete — start new round
+        return initRound(cascadeId);
+    }
+    return state;
+}
+/**
+ * Generate search queries for the IDENTIFY phase.
+ * Uses UCB to balance exploration vs exploitation across threads.
+ */
+export function generateSearchPlan(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 budget = Math.max(0, 1 - cascade.current_round / cascade.max_rounds);
+    // Get existing threads for UCB calculation
+    const threads = db.prepare('SELECT * FROM threads WHERE cascade_id = ?').all(cascadeId);
+    const totalVisits = threads.reduce((s, t) => s + (t.ucb_visits || 0), 0) || 1;
+    // UCB scoring for existing threads
+    const C = 1.414; // Exploration constant
+    for (const thread of threads) {
+        const visits = thread.ucb_visits || 1;
+        const reward = thread.ucb_reward || 0;
+        thread.ucb_score = reward / visits + C * Math.sqrt(Math.log(totalVisits) / visits);
+    }
+    // Split budget: exploration gets novel queries, exploitation deepens existing
+    const explorationCount = Math.ceil(questions.length * budget);
+    const exploitationCount = Math.max(1, questions.length - explorationCount);
+    return {
+        explorationQueries: questions.slice(0, explorationCount),
+        exploitationQueries: threads
+            .sort((a, b) => (b.ucb_score || 0) - (a.ucb_score || 0))
+            .slice(0, exploitationCount)
+            .map((t) => t.question),
+    };
+}
+/**
+ * Create a research thread (a sub-question being investigated).
+ */
+export function createThread(cascadeId, question, type, agentName, modelUsed) {
+    const db = getDb();
+    const id = generateId();
+    db.prepare(`INSERT INTO threads (id, cascade_id, question, type, status, agent_name, model_used, started_at)
+    VALUES (?, ?, ?, ?, 'active', ?, ?, datetime('now'))`)
+        .run(id, cascadeId, question, type, agentName, modelUsed);
+    return id;
+}
+/**
+ * Complete a thread and update its UCB values.
+ */
+export function completeThread(threadId, reward) {
+    const db = getDb();
+    db.prepare(`UPDATE threads SET
+    status = 'done', completed_at = datetime('now'),
+    ucb_visits = ucb_visits + 1,
+    ucb_reward = ucb_reward + ?
+    WHERE id = ?`)
+        .run(reward, threadId);
+}
+/**
+ * Get round summary for synthesis.
+ */
+export function getRoundSummary(cascadeId, roundIndex) {
+    const db = getDb();
+    const findings = db.prepare(`SELECT id, claim, confidence, trust_composite, grade_level
+    FROM findings WHERE cascade_id = ? AND cascade_round = ? AND quarantined = 0
+    ORDER BY confidence DESC`)
+        .all(cascadeId, roundIndex);
+    const hypotheses = db.prepare(`SELECT id, statement, affinity, status
+    FROM hypotheses WHERE cascade_id = ?
+    ORDER BY affinity DESC`)
+        .all(cascadeId);
+    // Approximate new entities/edges this round (by timestamp)
+    const newEntities = db.prepare(`SELECT COUNT(*) as n FROM kg_entities
+    WHERE created_at >= (SELECT MIN(created_at) FROM cascade_checkpoints WHERE task_id = ? AND round_index = ?)`).get(cascadeId, roundIndex)?.n || 0;
+    const newEdges = db.prepare(`SELECT COUNT(*) as n FROM kg_edges
+    WHERE created_at >= (SELECT MIN(created_at) FROM cascade_checkpoints WHERE task_id = ? AND round_index = ?)`).get(cascadeId, roundIndex)?.n || 0;
+    return { findings, hypotheses, newEntities, newEdges };
+}
+//# sourceMappingURL=engine.js.map

package/dist/cascade/engine.js.map

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

package/dist/cascade/gates.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+export interface GateResult {
+    gate: string;
+    passed: boolean;
+    value: number;
+    threshold: number;
+    description: string;
+}
+/**
+ * Check all four stopping conditions.
+ * If ANY gate says stop, cascade should conclude.
+ */
+export declare function evaluateStoppingGates(cascadeId: string): {
+    shouldStop: boolean;
+    gates: GateResult[];
+    recommendation: string;
+};
+/**
+ * Validate readiness to advance from one phase to the next.
+ * Returns issues that should be resolved before advancing.
+ */
+export declare function validatePhaseGate(cascadeId: string, fromPhase: string, toPhase: string): {
+    ready: boolean;
+    issues: string[];
+};
+/**
+ * Calculate information-theoretic metrics for the current round.
+ */
+export declare function calculateRoundMetrics(cascadeId: string): {
+    coverage: number;
+    depth: number;
+    confidence: number;
+    sourceQuality: number;
+    graphDensity: number;
+};
+//# sourceMappingURL=gates.d.ts.map