@obsidicore/cascade-engine 0.2.0

package/dist/graph/entities.js

@@ -0,0 +1,187 @@
+/**
+ * Knowledge Graph — Entity CRUD + Recursive CTE Traversal
+ *
+ * Edge-table pattern with SQLite recursive CTEs.
+ * Performance: 10K edges <50ms, 100K 50-500ms.
+ * ALWAYS ≤3 hop depth limit.
+ */
+import { getDb } from '../db/index.js';
+// --- Entity CRUD ---
+export function upsertEntity(name, entityType, properties = {}, tier = 'working', importance = 0.5) {
+    const db = getDb();
+    const propsJson = JSON.stringify(properties);
+    db.prepare(`INSERT INTO kg_entities (name, entity_type, properties, tier, importance)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(name, entity_type) DO UPDATE SET
+      properties = json_patch(properties, excluded.properties),
+      importance = MAX(importance, excluded.importance),
+      last_accessed = datetime('now'),
+      access_count = access_count + 1`)
+        .run(name, entityType, propsJson, tier, importance);
+    return db.prepare('SELECT id FROM kg_entities WHERE name = ? AND entity_type = ?').get(name, entityType).id;
+}
+export function getEntity(name, entityType) {
+    const db = getDb();
+    const row = db.prepare('SELECT * FROM kg_entities WHERE name = ? AND entity_type = ?').get(name, entityType);
+    if (!row)
+        return null;
+    // Touch access count
+    db.prepare('UPDATE kg_entities SET access_count = access_count + 1, last_accessed = datetime(\'now\') WHERE id = ?').run(row.id);
+    return rowToEntity(row);
+}
+export function getEntityById(id) {
+    const db = getDb();
+    const row = db.prepare('SELECT * FROM kg_entities WHERE id = ?').get(id);
+    return row ? rowToEntity(row) : null;
+}
+export function searchEntities(query, limit = 20) {
+    const db = getDb();
+    const rows = db.prepare(`SELECT * FROM kg_entities
+    WHERE name LIKE ? OR entity_type LIKE ?
+    ORDER BY importance DESC, access_count DESC LIMIT ?`)
+        .all(`%${query}%`, `%${query}%`, limit);
+    return rows.map(rowToEntity);
+}
+export function getEntitiesByTier(tier) {
+    const db = getDb();
+    const rows = db.prepare('SELECT * FROM kg_entities WHERE tier = ? ORDER BY importance DESC')
+        .all(tier);
+    return rows.map(rowToEntity);
+}
+// --- Edge CRUD ---
+export function upsertEdge(sourceId, targetId, relationType, weight = 1.0, properties = {}) {
+    const db = getDb();
+    db.prepare(`INSERT INTO kg_edges (source_id, target_id, relation_type, weight, properties)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(source_id, target_id, relation_type) DO UPDATE SET
+      weight = MAX(weight, excluded.weight),
+      activation_count = activation_count + 1,
+      last_activated = datetime('now')`)
+        .run(sourceId, targetId, relationType, weight, JSON.stringify(properties));
+    return db.prepare('SELECT id FROM kg_edges WHERE source_id = ? AND target_id = ? AND relation_type = ?')
+        .get(sourceId, targetId, relationType).id;
+}
+export function getEdgesFrom(entityId) {
+    const db = getDb();
+    const rows = db.prepare('SELECT * FROM kg_edges WHERE source_id = ? ORDER BY weight DESC')
+        .all(entityId);
+    return rows.map(rowToEdge);
+}
+export function getEdgesTo(entityId) {
+    const db = getDb();
+    const rows = db.prepare('SELECT * FROM kg_edges WHERE target_id = ? ORDER BY weight DESC')
+        .all(entityId);
+    return rows.map(rowToEdge);
+}
+// --- Graph Traversal ---
+/**
+ * Traverse the graph from a starting entity using recursive CTE.
+ * ALWAYS bounded to maxHops ≤ 3.
+ */
+export function traverse(startId, maxHops = 2, minWeight = 0.0, relationFilter) {
+    const db = getDb();
+    const hops = Math.min(maxHops, 3); // HARD LIMIT
+    const startEntity = db.prepare('SELECT name FROM kg_entities WHERE id = ?').get(startId);
+    if (!startEntity)
+        return [];
+    let relationClause = '';
+    const params = [startId, startEntity.name, hops, minWeight];
+    if (relationFilter) {
+        relationClause = 'AND e.relation_type = ?';
+        params.push(relationFilter);
+    }
+    const sql = `
+    WITH RECURSIVE graph_walk(entity_id, depth, path, visited) AS (
+      SELECT ?, 0, ?, ',' || CAST(? AS TEXT) || ','
+      UNION ALL
+      SELECT e.target_id, gw.depth + 1,
+        gw.path || ' -[' || e.relation_type || ']-> ' || tgt.name,
+        gw.visited || CAST(e.target_id AS TEXT) || ','
+      FROM graph_walk gw
+      JOIN kg_edges e ON e.source_id = gw.entity_id
+      JOIN kg_entities tgt ON tgt.id = e.target_id
+      WHERE gw.depth < ?
+        AND e.weight >= ?
+        AND gw.visited NOT LIKE '%,' || CAST(e.target_id AS TEXT) || ',%'
+        ${relationClause}
+    )
+    SELECT DISTINCT
+      ent.*, gw.depth, gw.path
+    FROM graph_walk gw
+    JOIN kg_entities ent ON ent.id = gw.entity_id
+    WHERE gw.depth > 0
+    ORDER BY gw.depth, ent.importance DESC`;
+    // Fix params order: startId, startName, startId (for visited), hops, minWeight, [relationFilter]
+    const queryParams = [startId, startEntity.name, startId, hops, minWeight];
+    if (relationFilter)
+        queryParams.push(relationFilter);
+    const rows = db.prepare(sql).all(...queryParams);
+    // Increment activation counts for traversed edges
+    db.prepare(`UPDATE kg_edges SET activation_count = activation_count + 1, last_activated = datetime('now')
+    WHERE source_id = ?`).run(startId);
+    return rows.map((row) => ({
+        entity: rowToEntity(row),
+        depth: row.depth,
+        path: row.path.split(' -> '),
+        edgeType: '',
+    }));
+}
+/**
+ * Find orphan entities (no incoming or outgoing edges).
+ */
+export function findOrphans() {
+    const db = getDb();
+    const rows = db.prepare(`SELECT e.* FROM kg_entities e
+    WHERE NOT EXISTS (SELECT 1 FROM kg_edges WHERE source_id = e.id)
+    AND NOT EXISTS (SELECT 1 FROM kg_edges WHERE target_id = e.id)`)
+        .all();
+    return rows.map(rowToEntity);
+}
+/**
+ * Get graph statistics.
+ */
+export function getGraphStats() {
+    const db = getDb();
+    const entityCount = db.prepare('SELECT COUNT(*) as n FROM kg_entities').get().n;
+    const edgeCount = db.prepare('SELECT COUNT(*) as n FROM kg_edges').get().n;
+    const avgDegree = entityCount > 0 ? (2 * edgeCount) / entityCount : 0;
+    const tierRows = db.prepare('SELECT tier, COUNT(*) as n FROM kg_entities GROUP BY tier').all();
+    const tierCounts = {};
+    for (const row of tierRows)
+        tierCounts[row.tier] = row.n;
+    const communityCounts = db.prepare('SELECT COUNT(DISTINCT community_id) as n FROM kg_entities WHERE community_id IS NOT NULL').get().n;
+    const orphanCount = db.prepare(`SELECT COUNT(*) as n FROM kg_entities e
+    WHERE NOT EXISTS (SELECT 1 FROM kg_edges WHERE source_id = e.id)
+    AND NOT EXISTS (SELECT 1 FROM kg_edges WHERE target_id = e.id)`).get().n;
+    return { entityCount, edgeCount, avgDegree, tierCounts, communityCounts, orphanCount };
+}
+// --- Helpers ---
+function rowToEntity(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        entityType: row.entity_type,
+        properties: JSON.parse(row.properties || '{}'),
+        communityId: row.community_id,
+        betweenness: row.betweenness,
+        tier: row.tier,
+        accessCount: row.access_count,
+        importance: row.importance,
+        lastAccessed: row.last_accessed,
+        createdAt: row.created_at,
+    };
+}
+function rowToEdge(row) {
+    return {
+        id: row.id,
+        sourceId: row.source_id,
+        targetId: row.target_id,
+        relationType: row.relation_type,
+        weight: row.weight,
+        properties: JSON.parse(row.properties || '{}'),
+        activationCount: row.activation_count,
+        lastActivated: row.last_activated,
+        createdAt: row.created_at,
+    };
+}
+//# sourceMappingURL=entities.js.map

package/dist/graph/entities.js.map

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

package/dist/graph/queries.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Advanced Graph Queries
+ *
+ * Includes the "money query" (hybrid vector + graph + FTS),
+ * bridge detection, and community-boundary analysis.
+ */
+/**
+ * Find entities that bridge two communities (high betweenness).
+ * These are the most valuable for cross-domain reasoning.
+ */
+export declare function findBridgeEntities(minBetweenness?: number, limit?: number): any[];
+/**
+ * Find entities with high degree (potential hubs).
+ * Guards against hub-and-spoke collapse with max edge alert.
+ */
+export declare function findHubs(maxEdges?: number): {
+    hubs: any[];
+    overconnected: any[];
+};
+/**
+ * Find entities that are semantically similar but topologically distant.
+ * These are Luhmann's "surprises" — the most valuable latent connections.
+ * (Requires embedding data — returns candidates for LLM analysis)
+ */
+export declare function findLatentBridgeCandidates(minHops?: number): any[];
+/**
+ * Compute structural entropy H_SI = -Σ(d_v/2m) × log2(d_v/2m)
+ * Fast proxy for graph complexity — O(n).
+ */
+export declare function computeStructuralEntropy(): {
+    entropy: number;
+    avgDegree: number;
+    giantComponentFraction: number;
+};
+/**
+ * Check phase transition indicators.
+ * Pre-threshold → maximize breadth. Post-threshold → exploit structure.
+ */
+export declare function checkPhaseTransition(): {
+    phase: 'pre_percolation' | 'near_threshold' | 'post_percolation';
+    indicators: Record<string, number>;
+    recommendation: string;
+};
+/**
+ * Find contradictions in the graph — edges where both 'supports' and 'contradicts' exist.
+ */
+export declare function findContradictions(): any[];
+//# sourceMappingURL=queries.d.ts.map

package/dist/graph/queries.js

@@ -0,0 +1,176 @@
+/**
+ * Advanced Graph Queries
+ *
+ * Includes the "money query" (hybrid vector + graph + FTS),
+ * bridge detection, and community-boundary analysis.
+ */
+import { getDb } from '../db/index.js';
+/**
+ * Find entities that bridge two communities (high betweenness).
+ * These are the most valuable for cross-domain reasoning.
+ */
+export function findBridgeEntities(minBetweenness = 0.1, limit = 10) {
+    const db = getDb();
+    return db.prepare(`SELECT e.*, COUNT(DISTINCT e2.community_id) as communities_bridged
+    FROM kg_entities e
+    JOIN kg_edges ed ON ed.source_id = e.id
+    JOIN kg_entities e2 ON e2.id = ed.target_id
+    WHERE e.betweenness >= ?
+    AND e.community_id IS NOT NULL
+    AND e2.community_id IS NOT NULL
+    AND e.community_id != e2.community_id
+    GROUP BY e.id
+    ORDER BY e.betweenness DESC
+    LIMIT ?`)
+        .all(minBetweenness, limit);
+}
+/**
+ * Find entities with high degree (potential hubs).
+ * Guards against hub-and-spoke collapse with max edge alert.
+ */
+export function findHubs(maxEdges = 50) {
+    const db = getDb();
+    const hubs = db.prepare(`SELECT e.id, e.name, e.entity_type, e.tier,
+    (SELECT COUNT(*) FROM kg_edges WHERE source_id = e.id) +
+    (SELECT COUNT(*) FROM kg_edges WHERE target_id = e.id) as degree
+    FROM kg_entities e
+    ORDER BY degree DESC LIMIT 20`)
+        .all();
+    const overconnected = hubs.filter(h => h.degree > maxEdges);
+    return { hubs, overconnected };
+}
+/**
+ * Find entities that are semantically similar but topologically distant.
+ * These are Luhmann's "surprises" — the most valuable latent connections.
+ * (Requires embedding data — returns candidates for LLM analysis)
+ */
+export function findLatentBridgeCandidates(minHops = 4) {
+    const db = getDb();
+    // Find pairs with no short path between them
+    // This is approximate — full shortest path on all pairs is too expensive
+    // Instead, find entities in different communities with no direct edges
+    return db.prepare(`SELECT
+    e1.id as entity1_id, e1.name as entity1_name, e1.entity_type as entity1_type,
+    e2.id as entity2_id, e2.name as entity2_name, e2.entity_type as entity2_type,
+    e1.community_id as community1, e2.community_id as community2
+    FROM kg_entities e1
+    JOIN kg_entities e2 ON e1.id < e2.id
+    WHERE e1.community_id IS NOT NULL
+    AND e2.community_id IS NOT NULL
+    AND e1.community_id != e2.community_id
+    AND e1.tier IN ('working', 'core')
+    AND e2.tier IN ('working', 'core')
+    AND NOT EXISTS (
+      SELECT 1 FROM kg_edges
+      WHERE (source_id = e1.id AND target_id = e2.id)
+      OR (source_id = e2.id AND target_id = e1.id)
+    )
+    ORDER BY e1.importance + e2.importance DESC
+    LIMIT 20`)
+        .all();
+}
+/**
+ * Compute structural entropy H_SI = -Σ(d_v/2m) × log2(d_v/2m)
+ * Fast proxy for graph complexity — O(n).
+ */
+export function computeStructuralEntropy() {
+    const db = getDb();
+    const entityCount = db.prepare('SELECT COUNT(*) as n FROM kg_entities').get().n;
+    const edgeCount = db.prepare('SELECT COUNT(*) as n FROM kg_edges').get().n;
+    if (entityCount === 0 || edgeCount === 0) {
+        return { entropy: 0, avgDegree: 0, giantComponentFraction: 0 };
+    }
+    const m2 = 2 * edgeCount; // sum of degrees
+    const avgDegree = m2 / entityCount;
+    // Get degree distribution
+    const degrees = db.prepare(`SELECT
+    (SELECT COUNT(*) FROM kg_edges WHERE source_id = e.id) +
+    (SELECT COUNT(*) FROM kg_edges WHERE target_id = e.id) as degree
+    FROM kg_entities e`)
+        .all();
+    // H_SI = -Σ(d_v/2m) × log2(d_v/2m)
+    let entropy = 0;
+    for (const { degree } of degrees) {
+        if (degree > 0) {
+            const p = degree / m2;
+            entropy -= p * Math.log2(p);
+        }
+    }
+    // Giant component fraction — approximate via BFS from highest-degree node
+    const giantComponentFraction = estimateGiantComponentFraction(db, entityCount);
+    return { entropy, avgDegree, giantComponentFraction };
+}
+/**
+ * Approximate giant component fraction by BFS from the highest-degree node.
+ */
+function estimateGiantComponentFraction(db, totalNodes) {
+    if (totalNodes === 0)
+        return 0;
+    // Start from highest-degree node
+    const start = db.prepare(`SELECT e.id,
+    (SELECT COUNT(*) FROM kg_edges WHERE source_id = e.id) +
+    (SELECT COUNT(*) FROM kg_edges WHERE target_id = e.id) as degree
+    FROM kg_entities e ORDER BY degree DESC LIMIT 1`).get();
+    if (!start)
+        return 0;
+    // BFS via recursive CTE — UNION deduplicates automatically (no self-reference needed)
+    const reachable = db.prepare(`WITH RECURSIVE component(id) AS (
+    SELECT ?
+    UNION
+    SELECT e.target_id FROM component c JOIN kg_edges e ON e.source_id = c.id
+    UNION
+    SELECT e.source_id FROM component c JOIN kg_edges e ON e.target_id = c.id
+  )
+  SELECT COUNT(*) as n FROM component`)
+        .get(start.id);
+    return reachable.n / totalNodes;
+}
+/**
+ * Check phase transition indicators.
+ * Pre-threshold → maximize breadth. Post-threshold → exploit structure.
+ */
+export function checkPhaseTransition() {
+    const { entropy, avgDegree, giantComponentFraction } = computeStructuralEntropy();
+    const indicators = {
+        avgDegree,
+        giantComponentFraction,
+        entropy,
+    };
+    if (avgDegree < 0.8 || giantComponentFraction < 0.3) {
+        return {
+            phase: 'pre_percolation',
+            indicators,
+            recommendation: 'Graph is sparse. Maximize breadth — every new edge moves toward criticality. Focus on exploration.',
+        };
+    }
+    if (avgDegree >= 0.8 && avgDegree <= 1.5 && giantComponentFraction >= 0.3 && giantComponentFraction <= 0.7) {
+        return {
+            phase: 'near_threshold',
+            indicators,
+            recommendation: 'Near percolation threshold! Adjacent possible growing combinatorially. Balance exploration and exploitation.',
+        };
+    }
+    return {
+        phase: 'post_percolation',
+        indicators,
+        recommendation: 'Post-percolation. Exploit structure — target community-boundary contradictions as research frontiers.',
+    };
+}
+/**
+ * Find contradictions in the graph — edges where both 'supports' and 'contradicts' exist.
+ */
+export function findContradictions() {
+    const db = getDb();
+    return db.prepare(`SELECT
+    e1.source_id, s.name as source_name,
+    e1.target_id, t.name as target_name,
+    e1.relation_type as rel1, e1.weight as w1,
+    e2.relation_type as rel2, e2.weight as w2
+    FROM kg_edges e1
+    JOIN kg_edges e2 ON e1.source_id = e2.source_id AND e1.target_id = e2.target_id
+    JOIN kg_entities s ON s.id = e1.source_id
+    JOIN kg_entities t ON t.id = e1.target_id
+    WHERE e1.relation_type = 'supports' AND e2.relation_type = 'contradicts'`)
+        .all();
+}
+//# sourceMappingURL=queries.js.map

package/dist/graph/queries.js.map

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

package/dist/hitl/dashboard.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Dashboard — ANSI output for cascade monitoring
+ *
+ * Plain ANSI header (metrics/phase) + scrolling stdout (NDJSON with --stream-json).
+ * NO TUIs (crash in tmux/SSH). Optional --tui flag for future.
+ *
+ * Quality review without reading everything:
+ * 4 metrics at round boundaries + 3-sentence LLM summary + identified gaps
+ */
+export interface DashboardData {
+    cascade: {
+        id: string;
+        question: string;
+        status: string;
+        round: number;
+        maxRounds: number;
+    };
+    quality: {
+        coverage: number;
+        depth: number;
+        confidence: number;
+        sourceQuality: number;
+    };
+    counts: {
+        findings: number;
+        quarantined: number;
+        hypotheses: number;
+        entities: number;
+        edges: number;
+    };
+    tokens: {
+        used: number;
+        budget: number;
+    };
+    explorationBudget: number;
+    pendingSteers: number;
+    interventions: string[];
+}
+/**
+ * Generate a compact ANSI dashboard string.
+ */
+export declare function renderDashboard(data: DashboardData): string;
+/**
+ * Build dashboard data from database state.
+ */
+export declare function buildDashboardData(cascadeId: string): DashboardData | null;
+/**
+ * Format a cascade status as NDJSON for streaming output.
+ */
+export declare function toNDJSON(data: DashboardData): string;
+//# sourceMappingURL=dashboard.d.ts.map

package/dist/hitl/dashboard.js

@@ -0,0 +1,135 @@
+/**
+ * Dashboard — ANSI output for cascade monitoring
+ *
+ * Plain ANSI header (metrics/phase) + scrolling stdout (NDJSON with --stream-json).
+ * NO TUIs (crash in tmux/SSH). Optional --tui flag for future.
+ *
+ * Quality review without reading everything:
+ * 4 metrics at round boundaries + 3-sentence LLM summary + identified gaps
+ */
+import { getDb } from '../db/index.js';
+// ANSI escape codes
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const CYAN = '\x1b[36m';
+const RESET = '\x1b[0m';
+/**
+ * Generate a compact ANSI dashboard string.
+ */
+export function renderDashboard(data) {
+    const lines = [];
+    // Header
+    lines.push(`${BOLD}${CYAN}═══ Research Cascade Dashboard ═══${RESET}`);
+    lines.push(`${BOLD}Q:${RESET} ${data.cascade.question.slice(0, 80)}`);
+    lines.push(`${BOLD}ID:${RESET} ${data.cascade.id}  ${BOLD}Status:${RESET} ${colorStatus(data.cascade.status)}  ${BOLD}Round:${RESET} ${data.cascade.round}/${data.cascade.maxRounds}`);
+    lines.push('');
+    // Quality metrics bar
+    lines.push(`${BOLD}Quality:${RESET}`);
+    lines.push(`  Coverage:   ${progressBar(data.quality.coverage, 20)} ${(data.quality.coverage * 100).toFixed(0)}%`);
+    lines.push(`  Depth:      ${progressBar(data.quality.depth, 20)} ${(data.quality.depth * 100).toFixed(0)}%`);
+    lines.push(`  Confidence: ${progressBar(data.quality.confidence, 20)} ${(data.quality.confidence * 100).toFixed(0)}%`);
+    lines.push(`  Source:     ${progressBar(data.quality.sourceQuality, 20)} ${(data.quality.sourceQuality * 100).toFixed(0)}%`);
+    lines.push('');
+    // Counts
+    lines.push(`${BOLD}Counts:${RESET} ${data.counts.findings} findings | ${data.counts.quarantined} quarantined | ${data.counts.hypotheses} hypotheses | ${data.counts.entities} entities | ${data.counts.edges} edges`);
+    // Budget
+    const tokenPct = data.tokens.budget > 0 ? data.tokens.used / data.tokens.budget : 0;
+    lines.push(`${BOLD}Tokens:${RESET} ${progressBar(tokenPct, 20)} ${data.tokens.used.toLocaleString()}/${data.tokens.budget.toLocaleString()}`);
+    lines.push(`${BOLD}Explore/Exploit:${RESET} ${(data.explorationBudget * 100).toFixed(0)}% exploration`);
+    // Alerts
+    if (data.pendingSteers > 0) {
+        lines.push(`${YELLOW}${BOLD}⚠ ${data.pendingSteers} pending steer events${RESET}`);
+    }
+    if (data.interventions.length > 0) {
+        lines.push(`${RED}${BOLD}! ${data.interventions.length} interventions:${RESET}`);
+        for (const i of data.interventions.slice(0, 3)) {
+            lines.push(`  ${RED}${i}${RESET}`);
+        }
+    }
+    lines.push(`${DIM}${CYAN}═══════════════════════════════════${RESET}`);
+    return lines.join('\n');
+}
+/**
+ * Build dashboard data from database state.
+ */
+export function buildDashboardData(cascadeId) {
+    const db = getDb();
+    const cascade = db.prepare('SELECT * FROM cascades WHERE id = ?').get(cascadeId);
+    if (!cascade)
+        return null;
+    const findingsCount = db.prepare('SELECT COUNT(*) as n FROM findings WHERE cascade_id = ? AND quarantined = 0').get(cascadeId).n;
+    const quarantinedCount = db.prepare('SELECT COUNT(*) as n FROM findings WHERE cascade_id = ? AND quarantined = 1').get(cascadeId).n;
+    const hypothesesCount = db.prepare('SELECT COUNT(*) as n FROM hypotheses WHERE cascade_id = ?').get(cascadeId).n;
+    const entityCount = db.prepare('SELECT COUNT(*) as n FROM kg_entities').get().n;
+    const edgeCount = db.prepare('SELECT COUNT(*) as n FROM kg_edges').get().n;
+    const pendingSteers = db.prepare('SELECT COUNT(*) as n FROM steer_events WHERE cascade_id = ? AND applied = 0').get(cascadeId).n;
+    // Calculate quality metrics
+    const plan = cascade.plan_json ? JSON.parse(cascade.plan_json) : null;
+    const totalQuestions = plan?.questions?.length || 1;
+    const avgConf = db.prepare('SELECT AVG(confidence) as v FROM findings WHERE cascade_id = ? AND quarantined = 0').get(cascadeId)?.v || 0;
+    const avgTrust = db.prepare('SELECT AVG(trust_composite) as v FROM findings WHERE cascade_id = ? AND quarantined = 0').get(cascadeId)?.v || 0.5;
+    return {
+        cascade: {
+            id: cascadeId,
+            question: cascade.question,
+            status: cascade.status,
+            round: cascade.current_round,
+            maxRounds: cascade.max_rounds,
+        },
+        quality: {
+            coverage: Math.min(1, findingsCount / (totalQuestions * 3)),
+            depth: Math.min(1, findingsCount / (totalQuestions * 10)),
+            confidence: avgConf,
+            sourceQuality: avgTrust,
+        },
+        counts: {
+            findings: findingsCount,
+            quarantined: quarantinedCount,
+            hypotheses: hypothesesCount,
+            entities: entityCount,
+            edges: edgeCount,
+        },
+        tokens: { used: cascade.tokens_used, budget: cascade.token_budget },
+        explorationBudget: Math.max(0, 1 - cascade.current_round / cascade.max_rounds),
+        pendingSteers,
+        interventions: [],
+    };
+}
+/**
+ * Render a simple ASCII progress bar.
+ */
+function progressBar(ratio, width) {
+    const clamped = Math.max(0, Math.min(1, ratio));
+    const filled = Math.round(clamped * width);
+    const empty = width - filled;
+    const color = clamped >= 0.7 ? GREEN : clamped >= 0.4 ? YELLOW : RED;
+    return `${color}${'█'.repeat(filled)}${DIM}${'░'.repeat(empty)}${RESET}`;
+}
+/**
+ * Color status text based on state.
+ */
+function colorStatus(status) {
+    switch (status) {
+        case 'planning': return `${CYAN}${status}${RESET}`;
+        case 'investigating': return `${GREEN}${status}${RESET}`;
+        case 'validating': return `${YELLOW}${status}${RESET}`;
+        case 'synthesizing': return `${GREEN}${status}${RESET}`;
+        case 'complete': return `${GREEN}${BOLD}${status}${RESET}`;
+        case 'stalled': return `${RED}${BOLD}${status}${RESET}`;
+        default: return status;
+    }
+}
+/**
+ * Format a cascade status as NDJSON for streaming output.
+ */
+export function toNDJSON(data) {
+    return JSON.stringify({
+        type: 'cascade_status',
+        timestamp: new Date().toISOString(),
+        ...data,
+    });
+}
+//# sourceMappingURL=dashboard.js.map

package/dist/hitl/dashboard.js.map

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

package/dist/hitl/interventions.d.ts

@@ -0,0 +1,36 @@
+/**
+ * HITL Intervention Taxonomy
+ *
+ * BLOCKING: Round 0 hypothesis (always), hypothesis drift >0.6, round boundaries (15min timeout)
+ * ADVISORY: trust <0.4 (2min), circuit breaker open (1min), confidence <0.5 (3min)
+ * SILENT: search planning (log only)
+ *
+ * Each intervention point has a timeout — if no human response, auto-proceeds.
+ */
+export type InterventionLevel = 'blocking' | 'advisory' | 'silent';
+export interface Intervention {
+    id: string;
+    cascadeId: string;
+    level: InterventionLevel;
+    category: string;
+    description: string;
+    context: Record<string, any>;
+    timeoutMinutes: number;
+    createdAt: string;
+    resolvedAt?: string;
+    resolution?: 'approved' | 'rejected' | 'timeout' | 'redirected';
+    humanComment?: string;
+}
+/**
+ * Check all intervention rules and return any that are triggered.
+ */
+export declare function checkInterventions(cascadeId: string, context?: any): Intervention[];
+/**
+ * Check if there are any blocking interventions that must be resolved.
+ */
+export declare function hasBlockingInterventions(cascadeId: string): boolean;
+/**
+ * Format interventions for display.
+ */
+export declare function formatInterventions(interventions: Intervention[]): string;
+//# sourceMappingURL=interventions.d.ts.map