@cleocode/core 2026.4.30 → 2026.4.35

package/dist/memory/extraction-gate.js

@@ -0,0 +1,459 @@
+/**
+ * Extraction Gate — Verification layer before BRAIN memory storage.
+ *
+ * Wraps all memory writes with three ordered checks:
+ *   A. Content-hash deduplication (always runs — fast, no embedding needed)
+ *   B. Cosine similarity deduplication (runs when embedding is available; skipped for trusted sources)
+ *   C. Confidence threshold enforcement (always runs)
+ *
+ * Trusted sources (manual, owner) bypass Check B but still run A and C.
+ *
+ * Design goals:
+ * - NEVER block the primary write path on error — all checks wrapped in try/catch
+ * - Degrade gracefully to hash-only dedup when embedding is unavailable
+ * - Contradiction detection uses a polarity-flip heuristic (no LLM required)
+ *
+ * @task T549 Wave 2-A
+ * @epic T549
+ */
+import { createHash } from 'node:crypto';
+import { isEmbeddingAvailable } from './brain-embedding.js';
+import { searchSimilar } from './brain-similarity.js';
+import { addGraphEdge } from './graph-auto-populate.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Cosine distance below which two entries are considered exact duplicates. */
+const DUPLICATE_THRESHOLD = 0.15;
+/** Cosine distance below which two entries are considered closely related. */
+const SIMILAR_THRESHOLD = 0.3;
+/** Minimum confidence score required to store an entry. */
+const MINIMUM_CONFIDENCE = 0.4;
+/**
+ * Negation markers used in polarity-flip contradiction detection.
+ * A contradiction is signalled when exactly one of two related entries
+ * contains one of these markers near shared keyword overlap.
+ */
+const NEGATION_MARKERS = [
+    'not',
+    'never',
+    'no longer',
+    'deprecated',
+    'removed',
+    'replaced',
+    'broken',
+    'avoid',
+    'do not',
+    "don't",
+    'invalid',
+    'obsolete',
+];
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Compute a short SHA-256 prefix over the normalised text content.
+ * Used for exact-duplicate detection without embedding.
+ */
+function contentHashPrefix(text) {
+    return createHash('sha256').update(text.trim().toLowerCase()).digest('hex').slice(0, 16);
+}
+/**
+ * Polarity-flip contradiction heuristic.
+ *
+ * Returns true when exactly one of the two texts carries a negation marker
+ * AND both texts share at least 3 meaningful keywords (>4 chars).
+ *
+ * This is intentionally approximate — false positives cause a supersede
+ * write (safe), false negatives allow a duplicate (harmless, caught later
+ * by cosine merge).
+ */
+function hasContradictingPolarity(existingText, newText) {
+    const existingLower = existingText.toLowerCase();
+    const newLower = newText.toLowerCase();
+    const existingNegated = NEGATION_MARKERS.some((m) => existingLower.includes(m));
+    const newNegated = NEGATION_MARKERS.some((m) => newLower.includes(m));
+    // Contradiction: exactly one of the two carries negation
+    if (existingNegated === newNegated)
+        return false;
+    // Require at least 3 shared meaningful keywords
+    const existingWords = new Set(existingLower.split(/\s+/).filter((w) => w.length > 4));
+    const newWords = new Set(newLower.split(/\s+/).filter((w) => w.length > 4));
+    const overlap = [...newWords].filter((w) => existingWords.has(w));
+    return overlap.length >= 3;
+}
+/**
+ * Mark an existing entry as invalid (superseded).
+ * Sets the invalid_at column to now on whichever typed table owns the entry.
+ *
+ * Determined by ID prefix conventions:
+ *   D...  → brain_decisions
+ *   P...  → brain_patterns
+ *   L...  → brain_learnings
+ *   O... / CM-... → brain_observations
+ */
+async function invalidateEntry(projectRoot, entryId) {
+    const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    try {
+        const { getBrainNativeDb, getBrainDb } = await import('../store/brain-sqlite.js');
+        await getBrainDb(projectRoot);
+        const nativeDb = getBrainNativeDb();
+        if (!nativeDb)
+            return;
+        // Route by ID prefix to correct table
+        if (entryId.startsWith('D-') || /^D\d/.test(entryId)) {
+            nativeDb
+                .prepare('UPDATE brain_decisions SET invalid_at = ? WHERE id = ? AND invalid_at IS NULL')
+                .run(now, entryId);
+        }
+        else if (entryId.startsWith('P-') || /^P\d/.test(entryId)) {
+            nativeDb
+                .prepare('UPDATE brain_patterns SET invalid_at = ? WHERE id = ? AND invalid_at IS NULL')
+                .run(now, entryId);
+        }
+        else if (entryId.startsWith('L-') || /^L\d/.test(entryId)) {
+            nativeDb
+                .prepare('UPDATE brain_learnings SET invalid_at = ? WHERE id = ? AND invalid_at IS NULL')
+                .run(now, entryId);
+        }
+        else {
+            // O-, O[base36], CM- → observations
+            nativeDb
+                .prepare('UPDATE brain_observations SET invalid_at = ? WHERE id = ? AND invalid_at IS NULL')
+                .run(now, entryId);
+        }
+    }
+    catch {
+        // Best-effort — invalidation failure must not block the primary write
+    }
+}
+/**
+ * Increment the citation_count of an existing entry by 1.
+ * Routes by the same ID-prefix convention as invalidateEntry.
+ */
+async function incrementCitationCount(projectRoot, entryId) {
+    try {
+        const { getBrainNativeDb, getBrainDb } = await import('../store/brain-sqlite.js');
+        await getBrainDb(projectRoot);
+        const nativeDb = getBrainNativeDb();
+        if (!nativeDb)
+            return;
+        if (entryId.startsWith('D-') || /^D\d/.test(entryId)) {
+            nativeDb
+                .prepare('UPDATE brain_decisions SET citation_count = citation_count + 1 WHERE id = ?')
+                .run(entryId);
+        }
+        else if (entryId.startsWith('P-') || /^P\d/.test(entryId)) {
+            nativeDb
+                .prepare('UPDATE brain_patterns SET citation_count = citation_count + 1 WHERE id = ?')
+                .run(entryId);
+        }
+        else if (entryId.startsWith('L-') || /^L\d/.test(entryId)) {
+            nativeDb
+                .prepare('UPDATE brain_learnings SET citation_count = citation_count + 1 WHERE id = ?')
+                .run(entryId);
+        }
+        else {
+            nativeDb
+                .prepare('UPDATE brain_observations SET citation_count = citation_count + 1 WHERE id = ?')
+                .run(entryId);
+        }
+    }
+    catch {
+        // Best-effort
+    }
+}
+/**
+ * Check A (degraded): SHA-256 content-hash deduplication only.
+ *
+ * Queries brain_observations for a matching content_hash within the last
+ * 24 hours. When a match is found, returns 'merged' so the caller avoids
+ * a duplicate insert.
+ *
+ * Only checks brain_observations because it is the only table that stores
+ * a content_hash column. For other memory types, hash dedup is not supported
+ * and this returns null.
+ */
+async function hashDedupCheck(projectRoot, text) {
+    try {
+        const { getBrainNativeDb, getBrainDb } = await import('../store/brain-sqlite.js');
+        await getBrainDb(projectRoot);
+        const nativeDb = getBrainNativeDb();
+        if (!nativeDb)
+            return { matched: false };
+        const hash = contentHashPrefix(text);
+        // Search across all observations (no time window — permanent dedup)
+        const rows = nativeDb
+            .prepare('SELECT id FROM brain_observations WHERE content_hash = ? AND invalid_at IS NULL LIMIT 1')
+            .all(hash);
+        if (rows.length > 0) {
+            return { matched: true, id: rows[0].id };
+        }
+    }
+    catch {
+        // Degrade gracefully — if dedup check fails, allow the write
+    }
+    return { matched: false };
+}
+/**
+ * Determine whether the candidate is from a trusted source that bypasses
+ * the similarity/contradiction checks (Checks B).
+ *
+ * Trusted: explicit candidate.trusted flag, source='manual', or
+ * sourceConfidence='owner' or 'task-outcome'.
+ */
+function isTrustedSource(candidate) {
+    if (candidate.trusted === true)
+        return true;
+    if (candidate.source === 'manual')
+        return true;
+    if (candidate.sourceConfidence === 'owner' || candidate.sourceConfidence === 'task-outcome') {
+        return true;
+    }
+    return false;
+}
+// ============================================================================
+// Core Gate Logic
+// ============================================================================
+/**
+ * Run a MemoryCandidate through the verification gate.
+ *
+ * Checks (in order):
+ *   A. Content-hash deduplication (always; degrades to observations-only when DB unavailable)
+ *   B. Cosine similarity deduplication + contradiction detection (skipped for trusted sources)
+ *   C. Confidence threshold >= 0.40 (always)
+ *
+ * The gate NEVER stores the entry itself — it only decides whether the caller
+ * should store, merge into an existing entry, queue as pending, or reject.
+ *
+ * To store after receiving action='stored', call the appropriate storage
+ * function (observeBrain, storeLearning, storePattern, storeDecision).
+ *
+ * @param projectRoot - Project root for brain.db access
+ * @param candidate - Candidate to verify
+ * @returns GateResult describing what should happen
+ */
+export async function verifyCandidate(projectRoot, candidate) {
+    try {
+        // -----------------------------------------------------------------------
+        // Check A: Content-hash dedup (always, fast)
+        // -----------------------------------------------------------------------
+        const hashCheck = await hashDedupCheck(projectRoot, candidate.text);
+        if (hashCheck.matched) {
+            // Bump citation count on the existing entry (fire-and-forget)
+            incrementCitationCount(projectRoot, hashCheck.id).catch(() => undefined);
+            return {
+                action: 'merged',
+                id: hashCheck.id,
+                reason: `exact-duplicate (hash match) of ${hashCheck.id}`,
+            };
+        }
+        // -----------------------------------------------------------------------
+        // Check B: Cosine similarity + contradiction (skip for trusted sources)
+        // -----------------------------------------------------------------------
+        const trusted = isTrustedSource(candidate);
+        if (!trusted && isEmbeddingAvailable()) {
+            try {
+                const similar = await searchSimilar(candidate.text, projectRoot, 5);
+                if (similar.length > 0) {
+                    const nearest = similar[0];
+                    if (nearest.distance < DUPLICATE_THRESHOLD) {
+                        // Near-identical — merge into existing
+                        incrementCitationCount(projectRoot, nearest.id).catch(() => undefined);
+                        return {
+                            action: 'merged',
+                            id: nearest.id,
+                            reason: `near-duplicate of ${nearest.id} (cosine distance=${nearest.distance.toFixed(3)})`,
+                            similarity: nearest.distance,
+                        };
+                    }
+                    if (nearest.distance < SIMILAR_THRESHOLD) {
+                        // Related — check for contradiction
+                        if (hasContradictingPolarity(nearest.text, candidate.text)) {
+                            // New text supersedes old — invalidate old entry
+                            await invalidateEntry(projectRoot, nearest.id);
+                            // Record supersession graph edge (fire-and-forget)
+                            // Note: we don't have the new entry's ID yet so we'll skip the edge here.
+                            // The caller should add the supersedes edge after storage using the returned existingId.
+                            return {
+                                action: 'stored',
+                                id: null,
+                                reason: `contradiction-supersedes ${nearest.id}`,
+                                similarity: nearest.distance,
+                            };
+                        }
+                        // Similar but not contradicting — store as new (link will be added post-storage)
+                        return {
+                            action: 'stored',
+                            id: null,
+                            reason: `similar-but-distinct to ${nearest.id} (distance=${nearest.distance.toFixed(3)})`,
+                            similarity: nearest.distance,
+                        };
+                    }
+                }
+            }
+            catch {
+                // Embedding/similarity check failed — degrade to hash-only (already passed above)
+            }
+        }
+        // -----------------------------------------------------------------------
+        // Check C: Confidence threshold
+        // -----------------------------------------------------------------------
+        if (candidate.confidence < MINIMUM_CONFIDENCE) {
+            return {
+                action: 'pending',
+                id: null,
+                reason: `confidence ${candidate.confidence.toFixed(2)} below minimum ${MINIMUM_CONFIDENCE}`,
+            };
+        }
+        // All checks passed — caller should store
+        return {
+            action: 'stored',
+            id: null,
+            reason: 'verified-new',
+        };
+    }
+    catch (err) {
+        // Safety net: gate errors must never block writes.
+        // Log a warning and allow the store to proceed.
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[extraction-gate] verifyCandidate error (allowing store): ${message}`);
+        return {
+            action: 'stored',
+            id: null,
+            reason: `gate-error-passthrough: ${message}`,
+        };
+    }
+}
+/**
+ * Run a batch of candidates through the verification gate sequentially.
+ *
+ * Sequential (not parallel) so that a 'merged' action on an earlier candidate
+ * is visible as an existing entry when later candidates run their similarity checks.
+ *
+ * @param projectRoot - Project root for brain.db access
+ * @param candidates - Array of candidates to verify
+ * @returns Array of GateResults in input order
+ */
+export async function verifyBatch(projectRoot, candidates) {
+    const results = [];
+    for (const candidate of candidates) {
+        results.push(await verifyCandidate(projectRoot, candidate));
+    }
+    return results;
+}
+// ============================================================================
+// Storage Routing
+// ============================================================================
+/**
+ * Store a verified candidate in the appropriate BRAIN table based on memoryType.
+ *
+ * Routes:
+ *   semantic    → brain_learnings  (storeLearning)
+ *   episodic    → brain_observations (observeBrain)
+ *   procedural  → brain_patterns   (storePattern)
+ *
+ * Called only after verifyCandidate returns action='stored'.
+ *
+ * @param projectRoot - Project root for brain.db access
+ * @param candidate - Verified candidate to store
+ * @returns ID of the newly created entry
+ */
+export async function storeVerifiedCandidate(projectRoot, candidate) {
+    const title = candidate.title ?? candidate.text.slice(0, 120);
+    switch (candidate.memoryType) {
+        case 'semantic': {
+            const { storeLearning } = await import('./learnings.js');
+            const row = await storeLearning(projectRoot, {
+                insight: candidate.text,
+                source: candidate.source,
+                confidence: candidate.confidence,
+                actionable: candidate.source === 'task-completion',
+            });
+            return row.id;
+        }
+        case 'episodic': {
+            const { observeBrain } = await import('./brain-retrieval.js');
+            const result = await observeBrain(projectRoot, {
+                text: candidate.text,
+                title,
+                sourceSessionId: candidate.sourceSessionId,
+                sourceType: candidate.source === 'manual' ? 'manual' : 'agent',
+            });
+            return result.id;
+        }
+        case 'procedural': {
+            const { storePattern } = await import('./patterns.js');
+            const row = await storePattern(projectRoot, {
+                type: 'workflow',
+                pattern: candidate.text,
+                context: title,
+            });
+            return row.id;
+        }
+        default: {
+            // Exhaustive fallback — should never reach here with correct types
+            const { observeBrain } = await import('./brain-retrieval.js');
+            const result = await observeBrain(projectRoot, {
+                text: candidate.text,
+                title,
+                sourceSessionId: candidate.sourceSessionId,
+                sourceType: candidate.source === 'manual' ? 'manual' : 'agent',
+            });
+            return result.id;
+        }
+    }
+}
+/**
+ * Full gate-and-store pipeline for a single candidate.
+ *
+ * Runs verifyCandidate then calls storeVerifiedCandidate when action='stored'.
+ * For 'merged', increments the existing entry's citation_count (already done inside verifyCandidate).
+ * For 'pending' and 'rejected', returns the GateResult with no storage.
+ *
+ * After storage, adds a supersedes edge when the gate returned a contradiction reason.
+ *
+ * @param projectRoot - Project root for brain.db access
+ * @param candidate - Candidate to verify and store
+ * @returns Final GateResult with the stored/merged entry ID populated
+ */
+export async function verifyAndStore(projectRoot, candidate) {
+    const gateResult = await verifyCandidate(projectRoot, candidate);
+    if (gateResult.action !== 'stored') {
+        return gateResult;
+    }
+    try {
+        const newId = await storeVerifiedCandidate(projectRoot, candidate);
+        // If this was a contradiction supersession, add a graph edge (best-effort)
+        if (gateResult.reason.startsWith('contradiction-supersedes ')) {
+            const oldId = gateResult.reason.replace('contradiction-supersedes ', '');
+            addGraphEdge(projectRoot, `observation:${newId}`, `observation:${oldId}`, 'supersedes', 1.0, 'extraction-gate').catch(() => undefined);
+        }
+        return { ...gateResult, id: newId };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            action: 'rejected',
+            id: null,
+            reason: `storage-error: ${message}`,
+        };
+    }
+}
+/**
+ * Full gate-and-store pipeline for a batch of candidates.
+ *
+ * Sequential execution ensures that earlier stores are visible to later similarity checks.
+ *
+ * @param projectRoot - Project root for brain.db access
+ * @param candidates - Array of candidates to verify and store
+ * @returns Array of final GateResults in input order
+ */
+export async function verifyAndStoreBatch(projectRoot, candidates) {
+    const results = [];
+    for (const candidate of candidates) {
+        results.push(await verifyAndStore(projectRoot, candidate));
+    }
+    return results;
+}
+//# sourceMappingURL=extraction-gate.js.map

package/dist/memory/extraction-gate.js.map

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

package/dist/memory/graph-auto-populate.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Graph auto-population helpers for CLEO BRAIN.
+ *
+ * Provides upsertGraphNode and addGraphEdge helpers that write to the
+ * brain_page_nodes and brain_page_edges tables whenever memory entries
+ * are created via the legitimate write paths (storeDecision, observeBrain,
+ * storePattern, storeLearning, and task completion).
+ *
+ * Design constraints:
+ * - All writes are BEST-EFFORT — never block or fail the primary operation.
+ * - All writes are gated on brain.autoCapture via isAutoCaptureEnabled.
+ * - Uses INSERT OR REPLACE (onConflictDoUpdate) for upsert semantics.
+ * - Edge inserts are idempotent via the composite PK (fromId, toId, edgeType).
+ *
+ * @task T537
+ * @epic T523
+ */
+import type { BrainEdgeType, BrainNodeType } from '../store/brain-schema.js';
+export type { BrainEdgeType, BrainNodeType };
+/**
+ * Upsert a graph node for a typed table entry.
+ *
+ * Uses INSERT OR REPLACE to handle both new and existing entries. If the
+ * node already exists (same id), its label, qualityScore, lastActivityAt,
+ * updatedAt, and metadataJson are refreshed while createdAt is preserved.
+ *
+ * The contentHash is derived from a SHA-256 prefix of the canonical content.
+ * External-reference nodes (task, session, epic) may pass an empty string for
+ * content; their hash will be null so duplicates are not rejected.
+ *
+ * This function is gated on brain.autoCapture. If the gate is disabled or any
+ * error occurs, it returns silently without throwing.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param nodeId - Stable composite ID in the form '<type>:<source-id>'.
+ * @param nodeType - Discriminated type from BRAIN_NODE_TYPES.
+ * @param label - Human-readable label (title, task ID, etc.).
+ * @param qualityScore - 0.0 (noise) to 1.0 (canonical).
+ * @param content - Canonical text used to derive the content hash.
+ * @param metadata - Optional type-specific metadata blob.
+ *
+ * @task T537
+ */
+export declare function upsertGraphNode(projectRoot: string, nodeId: string, nodeType: BrainNodeType, label: string, qualityScore: number, content: string, metadata?: Record<string, unknown>): Promise<void>;
+/**
+ * Add a directed, typed edge between two graph nodes (idempotent).
+ *
+ * The composite primary key (fromId, toId, edgeType) prevents duplicate edges
+ * of the same type. Conflicting rows are ignored so this is safe to call
+ * multiple times with the same arguments.
+ *
+ * This function is gated on brain.autoCapture. If the gate is disabled or any
+ * error occurs, it returns silently without throwing.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param fromId - Source node ID (brain_page_nodes.id).
+ * @param toId - Target node ID (brain_page_nodes.id or external nexus ID).
+ * @param edgeType - Typed relationship from BRAIN_EDGE_TYPES.
+ * @param weight - Edge confidence/weight (0.0–1.0). Defaults to 1.0.
+ * @param provenance - Human-readable note on why this edge was emitted.
+ *
+ * @task T537
+ */
+export declare function addGraphEdge(projectRoot: string, fromId: string, toId: string, edgeType: BrainEdgeType, weight?: number, provenance?: string): Promise<void>;
+//# sourceMappingURL=graph-auto-populate.d.ts.map

package/dist/memory/graph-auto-populate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-auto-populate.d.ts","sourceRoot":"","sources":["../../src/memory/graph-auto-populate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAM7E,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC;AAyB7C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC,CAyCf;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,aAAa,EACvB,MAAM,SAAM,EACZ,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAqBf"}