@cleocode/core 2026.4.9 → 2026.4.11

package/dist/lifecycle/tessera-engine.js

@@ -0,0 +1,249 @@
+/**
+ * Tessera Instantiation Engine
+ *
+ * Provides template management and instantiation for parameterized
+ * WarpChain workflows. Wraps buildDefaultChain() with template
+ * variables and manages the template registry.
+ *
+ * @task T5409
+ */
+import { validateChain } from '../validation/chain-validation.js';
+import { addChain, createInstance, showChain } from './chain-store.js';
+import { buildDefaultChain } from './default-chain.js';
+const DEFAULT_TESSERA_ID = 'tessera-rcasd';
+const TASK_ID_PATTERN = /^T\d+$/;
+const PLACEHOLDER_EXACT = /^\{\{\s*([A-Za-z0-9_]+)\s*\}\}$/;
+const PLACEHOLDER_GLOBAL = /\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g;
+function valueType(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    return typeof value;
+}
+function hasOwn(obj, key) {
+    return Object.hasOwn(obj, key);
+}
+function validateVariableType(name, varDef, value) {
+    switch (varDef.type) {
+        case 'string': {
+            if (typeof value !== 'string') {
+                throw new Error(`Invalid variable type for "${name}": expected string, got ${valueType(value)}`);
+            }
+            return;
+        }
+        case 'number': {
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                throw new Error(`Invalid variable type for "${name}": expected finite number, got ${valueType(value)}`);
+            }
+            return;
+        }
+        case 'boolean': {
+            if (typeof value !== 'boolean') {
+                throw new Error(`Invalid variable type for "${name}": expected boolean, got ${valueType(value)}`);
+            }
+            return;
+        }
+        case 'taskId':
+        case 'epicId': {
+            if (typeof value !== 'string') {
+                throw new Error(`Invalid variable type for "${name}": expected ${varDef.type}, got ${valueType(value)}`);
+            }
+            if (!TASK_ID_PATTERN.test(value)) {
+                throw new Error(`Invalid variable format for "${name}": expected ${varDef.type} like "T1234", got "${value}"`);
+            }
+            return;
+        }
+        default: {
+            throw new Error(`Unsupported variable type for "${name}": ${String(varDef.type)}`);
+        }
+    }
+}
+function substituteTemplateValue(value, variables, path) {
+    if (typeof value === 'string') {
+        const exact = value.match(PLACEHOLDER_EXACT);
+        if (exact) {
+            const variableName = exact[1];
+            if (!hasOwn(variables, variableName)) {
+                throw new Error(`Unknown template variable "${variableName}" at ${path}`);
+            }
+            return variables[variableName];
+        }
+        return value.replace(PLACEHOLDER_GLOBAL, (_full, variableName) => {
+            if (!hasOwn(variables, variableName)) {
+                throw new Error(`Unknown template variable "${variableName}" at ${path}`);
+            }
+            return String(variables[variableName]);
+        });
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry, index) => substituteTemplateValue(entry, variables, `${path}[${index}]`));
+    }
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            out[key] = substituteTemplateValue(nested, variables, `${path}.${key}`);
+        }
+        return out;
+    }
+    return value;
+}
+function resolveVariables(template, inputVariables) {
+    const variableKeys = Object.keys(template.variables).sort();
+    const allowedVariables = new Set(variableKeys);
+    for (const key of Object.keys(inputVariables).sort()) {
+        if (!allowedVariables.has(key)) {
+            throw new Error(`Unknown variable: ${key}. Allowed variables: ${variableKeys.join(', ')}`);
+        }
+    }
+    const resolvedVariables = {};
+    for (const key of variableKeys) {
+        const varDef = template.variables[key];
+        const hasInput = hasOwn(inputVariables, key);
+        const inputValue = hasInput ? inputVariables[key] : undefined;
+        if (inputValue === undefined) {
+            if (varDef.required) {
+                throw new Error(`Missing required variable: ${key}`);
+            }
+            if (hasOwn(template.defaultValues, key)) {
+                const defaultValue = template.defaultValues[key];
+                validateVariableType(key, varDef, defaultValue);
+                resolvedVariables[key] = defaultValue;
+            }
+            else if (varDef.default !== undefined) {
+                validateVariableType(key, varDef, varDef.default);
+                resolvedVariables[key] = varDef.default;
+            }
+            continue;
+        }
+        validateVariableType(key, varDef, inputValue);
+        resolvedVariables[key] = inputValue;
+    }
+    return resolvedVariables;
+}
+/**
+ * Build the default RCASD Tessera template.
+ *
+ * Wraps buildDefaultChain() with template variables:
+ * - epicId (required, type 'epicId')
+ * - projectName (optional, type 'string', default 'unnamed')
+ * - skipResearch (optional, type 'boolean', default false)
+ *
+ * @task T5409
+ */
+export function buildDefaultTessera() {
+    const chain = buildDefaultChain();
+    return {
+        ...chain,
+        id: DEFAULT_TESSERA_ID,
+        tessera: DEFAULT_TESSERA_ID,
+        variables: {
+            epicId: {
+                name: 'epicId',
+                type: 'epicId',
+                description: 'The epic task ID to bind this pipeline to',
+                required: true,
+            },
+            projectName: {
+                name: 'projectName',
+                type: 'string',
+                description: 'Name of the project for labeling',
+                required: false,
+                default: 'unnamed',
+            },
+            skipResearch: {
+                name: 'skipResearch',
+                type: 'boolean',
+                description: 'Whether to skip the research stage',
+                required: false,
+                default: false,
+            },
+        },
+        archetypes: ['lifecycle', 'rcasd'],
+        defaultValues: {
+            projectName: 'unnamed',
+            skipResearch: false,
+        },
+        category: 'lifecycle',
+    };
+}
+/** In-memory template registry. */
+const templates = new Map();
+/** Ensure the default template is registered. */
+function ensureDefaults() {
+    if (!templates.has(DEFAULT_TESSERA_ID)) {
+        templates.set(DEFAULT_TESSERA_ID, buildDefaultTessera());
+    }
+}
+/**
+ * Instantiate a Tessera template into a concrete WarpChainInstance.
+ *
+ * Steps:
+ * 1. Validate all required variables are provided
+ * 2. Apply defaults for missing optional variables
+ * 3. Construct concrete WarpChain from template
+ * 4. Validate chain via validateChain()
+ * 5. Store via createInstance() from chain-store
+ * 6. Return instance
+ *
+ * @task T5409
+ */
+export async function instantiateTessera(template, input, projectRoot) {
+    // 1. Resolve and validate input variables
+    const inputVariables = input.variables && typeof input.variables === 'object' ? input.variables : {};
+    const resolvedVariables = resolveVariables(template, inputVariables);
+    // 2. Build chain from template with deep substitution
+    const chainSeed = {
+        id: template.id,
+        name: template.name,
+        version: template.version,
+        description: template.description,
+        shape: template.shape,
+        gates: template.gates,
+        tessera: template.id,
+        metadata: template.metadata,
+    };
+    const substituted = substituteTemplateValue(chainSeed, resolvedVariables, 'chain');
+    const chain = substituted;
+    chain.metadata = {
+        ...(chain.metadata ?? {}),
+        variables: resolvedVariables,
+    };
+    // 3. Validate the chain
+    const validation = validateChain(chain);
+    if (validation.errors.length > 0) {
+        throw new Error(`Tessera chain validation failed: ${validation.errors.join('; ')}`);
+    }
+    // 4. Store chain if not already stored, then create instance
+    const existing = await showChain(chain.id, projectRoot);
+    if (!existing) {
+        await addChain(chain, projectRoot);
+    }
+    // 5. Create and return instance
+    return createInstance({
+        chainId: chain.id,
+        epicId: input.epicId,
+        variables: resolvedVariables,
+    }, projectRoot);
+}
+/**
+ * List all registered Tessera templates.
+ *
+ * @task T5409
+ */
+export function listTesseraTemplates() {
+    ensureDefaults();
+    return Array.from(templates.values());
+}
+/**
+ * Find a Tessera template by ID.
+ *
+ * @task T5409
+ */
+export function showTessera(id) {
+    ensureDefaults();
+    return templates.get(id) ?? null;
+}
+//# sourceMappingURL=tessera-engine.js.map

package/dist/lifecycle/tessera-engine.js.map

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

package/dist/logger.js

@@ -0,0 +1,140 @@
+/**
+ * Centralized pino logger factory for CLEO.
+ *
+ * Singleton pattern. Uses pino-roll for automatic file rotation and retention.
+ * Custom formatters for uppercase level labels and ISO timestamps.
+ * Context via child loggers (getLogger('subsystem')).
+ *
+ * All diagnostic logging goes to files — stdout is reserved for structured
+ * CLI output. Fallback stderr logger if not yet initialized.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import pino from 'pino';
+let rootLogger = null;
+let currentLogDir = null;
+/**
+ * Convert bytes to a human-readable size string for pino-roll.
+ * pino-roll accepts '10m', '1g', '500k', etc.
+ */
+function bytesToSizeString(bytes) {
+    if (bytes >= 1024 * 1024 * 1024)
+        return `${Math.floor(bytes / (1024 * 1024 * 1024))}g`;
+    if (bytes >= 1024 * 1024)
+        return `${Math.floor(bytes / (1024 * 1024))}m`;
+    if (bytes >= 1024)
+        return `${Math.floor(bytes / 1024)}k`;
+    return `${bytes}`;
+}
+/**
+ * Initialize the root logger. Call once at startup.
+ *
+ * Uses pino-roll for automatic size+daily rotation with built-in retention.
+ * No custom rotation code needed.
+ *
+ * @param cleoDir      - Absolute path to .cleo directory
+ * @param config       - Logging configuration from CleoConfig.logging
+ * @param projectHash  - Stable project identity token bound to every log entry.
+ *                        Optional for backward compatibility; warns if absent.
+ * @returns The root pino logger instance
+ */
+export function initLogger(cleoDir, config, projectHash) {
+    const dest = join(cleoDir, config.filePath);
+    currentLogDir = dirname(dest);
+    // Log directory should already exist via ensureCleoStructure() which
+    // creates all REQUIRED_CLEO_SUBDIRS including 'logs'. The pino-roll
+    // transport has mkdir: true as a safety net for edge cases where the
+    // logger is initialized before scaffold (e.g. early startup fallback).
+    if (!existsSync(currentLogDir)) {
+        // Emit to stderr — stdout is reserved for structured output
+        process.stderr.write(`[cleo:logger] Log directory missing: ${currentLogDir} — pino-roll will create it\n`);
+    }
+    // Use pino-roll transport for automatic rotation and retention.
+    // pino.transport() runs in a worker thread; sync: true ensures
+    // no log loss on process exit (critical for CLI tools).
+    const transport = pino.transport({
+        target: 'pino-roll',
+        options: {
+            file: dest,
+            size: bytesToSizeString(config.maxFileSize),
+            frequency: 'daily',
+            dateFormat: 'yyyy-MM-dd',
+            mkdir: true,
+            limit: {
+                count: config.maxFiles,
+                removeOtherLogFiles: true,
+            },
+        },
+    });
+    // Build base object: projectHash and platform info appear in every log entry.
+    // Pino merges base with pid/hostname by default; we add our fields alongside.
+    const base = {
+        platform: process.platform,
+        arch: process.arch,
+        nodeVersion: process.version,
+    };
+    if (projectHash) {
+        base.projectHash = projectHash;
+    }
+    rootLogger = pino({
+        level: config.level,
+        base,
+        formatters: {
+            level: (label) => ({ level: label.toUpperCase() }),
+        },
+        timestamp: pino.stdTimeFunctions.isoTime,
+    }, transport);
+    // Warn after logger is initialized so the message goes to the log file
+    if (!projectHash) {
+        getLogger('engine').warn('projectHash not provided to initLogger; audit correlation will be incomplete');
+    }
+    return rootLogger;
+}
+/**
+ * Get a child logger bound to a subsystem name.
+ *
+ * Safe to call before initLogger — returns a stderr fallback logger
+ * so early startup code and tests never crash.
+ *
+ * @param subsystem - Logical subsystem name (e.g. 'audit', 'dispatch', 'migration')
+ */
+export function getLogger(subsystem) {
+    if (!rootLogger) {
+        // Fallback: stderr logger (stdout reserved for structured output)
+        return pino({
+            level: 'warn',
+            formatters: { level: (label) => ({ level: label.toUpperCase() }) },
+        }, pino.destination(2)).child({ subsystem });
+    }
+    return rootLogger.child({ subsystem });
+}
+/**
+ * Get the current log directory path.
+ * Useful for read APIs that need to scan log files.
+ */
+export function getLogDir() {
+    return currentLogDir;
+}
+/**
+ * Flush and close the logger. Call during graceful shutdown.
+ *
+ * Returns a Promise that resolves once the pino transport worker thread
+ * has processed all pending writes. Callers that cannot await (e.g. sync
+ * shutdown handlers) may fire-and-forget safely — the underlying flush
+ * will still occur before the process exits.
+ */
+export function closeLogger() {
+    return new Promise((resolve) => {
+        if (rootLogger) {
+            rootLogger.flush(() => {
+                rootLogger = null;
+                currentLogDir = null;
+                resolve();
+            });
+        }
+        else {
+            resolve();
+        }
+    });
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

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

package/dist/memory/auto-extract.js

@@ -0,0 +1,177 @@
+/**
+ * Auto-extract structured memory entries from task completions and session ends.
+ *
+ * Best-effort extraction: all functions wrap their logic in try/catch and
+ * must never throw — memory extraction must never block the calling flow.
+ *
+ * @task T-auto-extract
+ * @epic T5149
+ */
+import { storeDecision } from './decisions.js';
+import { storeLearning } from './learnings.js';
+import { storePattern } from './patterns.js';
+/**
+ * Extract and store memory entries when a task is completed.
+ *
+ * - Always stores a learning for the completed task.
+ * - Stores a second learning if the task had dependencies.
+ * - Detects recurring label patterns across recent completed tasks
+ *   and stores a success pattern when any label appears 3+ times.
+ */
+export async function extractTaskCompletionMemory(projectRoot, task, _parentTask) {
+    try {
+        // Always store a learning for this completion
+        await storeLearning(projectRoot, {
+            insight: `Completed: ${task.title} — ${task.description ?? ''}`,
+            source: `task-completion:${task.id}`,
+            confidence: 0.7,
+            actionable: true,
+        });
+        // Dependency chain learning
+        const deps = task.depends ?? [];
+        if (deps.length > 0) {
+            await storeLearning(projectRoot, {
+                insight: `Task ${task.id} depended on ${deps.join(', ')} — dependency chain completed successfully`,
+                source: `task-completion:${task.id}`,
+                confidence: 0.7,
+            });
+        }
+        // Pattern detection: look for recurring labels across recent done tasks
+        const { getAccessor } = await import('../store/data-accessor.js');
+        const accessor = await getAccessor(projectRoot);
+        let doneTasks;
+        try {
+            const { tasks } = await accessor.queryTasks({ status: 'done' });
+            doneTasks = tasks;
+        }
+        finally {
+            await accessor.close();
+        }
+        const recentDone = doneTasks.slice(-50);
+        const labelCounts = new Map();
+        for (const t of recentDone) {
+            for (const label of t.labels ?? []) {
+                const existing = labelCounts.get(label) ?? [];
+                existing.push(t.id);
+                labelCounts.set(label, existing);
+            }
+        }
+        for (const [label, taskIds] of labelCounts.entries()) {
+            if (taskIds.length >= 3) {
+                await storePattern(projectRoot, {
+                    type: 'success',
+                    pattern: `Recurring label "${label}" seen in ${taskIds.length} completed tasks`,
+                    context: `Auto-detected from task completion of ${task.id}`,
+                    impact: 'medium',
+                    examples: taskIds,
+                });
+            }
+        }
+    }
+    catch {
+        // Best-effort: must never throw
+    }
+}
+/**
+ * Extract and store memory entries when a session ends.
+ *
+ * - Stores a process decision summarising the session.
+ * - Stores a per-task learning for each completed task.
+ * - Stores a workflow pattern when 2+ completed tasks share a label.
+ */
+export async function extractSessionEndMemory(projectRoot, sessionData, taskDetails) {
+    try {
+        if (taskDetails.length > 0) {
+            await storeDecision(projectRoot, {
+                type: 'process',
+                decision: `Session ${sessionData.sessionId} completed ${taskDetails.length} tasks: ${taskDetails.map((t) => t.id).join(', ')}`,
+                rationale: `Session scope: ${sessionData.scope}. Duration: ${Math.round(sessionData.duration / 60)} min.`,
+                confidence: 'medium',
+            });
+        }
+        // Per-task learnings
+        for (const t of taskDetails) {
+            await storeLearning(projectRoot, {
+                insight: `Completed: ${t.title} — ${t.description ?? ''}`,
+                source: `session-end:${sessionData.sessionId}`,
+                confidence: 0.7,
+                actionable: true,
+            });
+        }
+        // Workflow pattern when 2+ tasks share a label
+        const labelCounts = new Map();
+        for (const t of taskDetails) {
+            for (const label of t.labels ?? []) {
+                const existing = labelCounts.get(label) ?? [];
+                existing.push(t.id);
+                labelCounts.set(label, existing);
+            }
+        }
+        for (const [label, taskIds] of labelCounts.entries()) {
+            if (taskIds.length >= 2) {
+                await storePattern(projectRoot, {
+                    type: 'workflow',
+                    pattern: `Session ${sessionData.sessionId} completed ${taskIds.length} tasks with label "${label}"`,
+                    context: `Auto-detected from session end: ${sessionData.sessionId}`,
+                    impact: 'medium',
+                    examples: taskIds,
+                });
+            }
+        }
+    }
+    catch {
+        // Best-effort: must never throw
+    }
+}
+/**
+ * Resolve an array of task IDs to their full Task objects.
+ * Tasks that cannot be found are silently excluded.
+ */
+export async function resolveTaskDetails(projectRoot, taskIds) {
+    if (taskIds.length === 0) {
+        return [];
+    }
+    const { getAccessor } = await import('../store/data-accessor.js');
+    const accessor = await getAccessor(projectRoot);
+    try {
+        return await accessor.loadTasks(taskIds);
+    }
+    finally {
+        await accessor.close();
+    }
+}
+/** Action words that indicate a meaningful assistant turn worth storing. */
+const ACTION_PATTERNS = /\b(implement|fix|add|create|update|remove|refactor|extract|migrate|resolve|complete|found|learned|discovered)\b/i;
+/**
+ * Extract key observations from a provider session transcript and store
+ * them in brain.db as learnings.
+ *
+ * Filters assistant lines that contain action words, stores up to 5 as
+ * learnings with 0.6 confidence. Always best-effort — never throws.
+ *
+ * @param projectRoot - Absolute path to project root.
+ * @param sessionId - The CLEO session ID being processed.
+ * @param transcript - Plain-text provider transcript (user/assistant turns).
+ * @task T144 @epic T134
+ */
+export async function extractFromTranscript(projectRoot, sessionId, transcript) {
+    try {
+        const lines = transcript.split('\n').filter((l) => l.trim().length > 20);
+        const actionLines = lines.filter((l) => ACTION_PATTERNS.test(l)).slice(0, 5);
+        if (actionLines.length === 0)
+            return;
+        const { storeLearning } = await import('./learnings.js');
+        for (const line of actionLines) {
+            await storeLearning(projectRoot, {
+                insight: line.trim().slice(0, 250),
+                source: `transcript:${sessionId}`,
+                confidence: 0.6,
+                actionable: false,
+            });
+        }
+    }
+    catch {
+        // Best-effort: must never throw
+    }
+}
+//# sourceMappingURL=auto-extract.js.map

package/dist/memory/auto-extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-extract.js","sourceRoot":"","sources":["../../src/memory/auto-extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,WAAmB,EACnB,IAAU,EACV,WAAkB;IAElB,IAAI,CAAC;QACH,8CAA8C;QAC9C,MAAM,aAAa,CAAC,WAAW,EAAE;YAC/B,OAAO,EAAE,cAAc,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,WAAW,IAAI,EAAE,EAAE;YAC/D,MAAM,EAAE,mBAAmB,IAAI,CAAC,EAAE,EAAE;YACpC,UAAU,EAAE,GAAG;YACf,UAAU,EAAE,IAAI;SACjB,CAAC,CAAC;QAEH,4BAA4B;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;QAChC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,aAAa,CAAC,WAAW,EAAE;gBAC/B,OAAO,EAAE,QAAQ,IAAI,CAAC,EAAE,gBAAgB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,4CAA4C;gBACnG,MAAM,EAAE,mBAAmB,IAAI,CAAC,EAAE,EAAE;gBACpC,UAAU,EAAE,GAAG;aAChB,CAAC,CAAC;QACL,CAAC;QAED,wEAAwE;QACxE,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,2BAA2B,CAAC,CAAC;QAClE,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,WAAW,CAAC,CAAC;QAChD,IAAI,SAAiB,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;YAChE,SAAS,GAAG,KAAK,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC;QACzB,CAAC;QAED,MAAM,UAAU,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;QAExC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAoB,CAAC;QAChD,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;YAC3B,KAAK,MAAM,KAAK,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;gBACnC,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;gBAC9C,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACpB,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QAED,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,CAAC;YACrD,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;gBACxB,MAAM,YAAY,CAAC,WAAW,EAAE;oBAC9B,IAAI,EAAE,SAAS;oBACf,OAAO,EAAE,oBAAoB,KAAK,aAAa,OAAO,CAAC,MAAM,kBAAkB;oBAC/E,OAAO,EAAE,yCAAyC,IAAI,CAAC,EAAE,EAAE;oBAC3D,MAAM,EAAE,QAAQ;oBAChB,QAAQ,EAAE,OAAO;iBAClB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;IAClC,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,WAAmB,EACnB,WAA8B,EAC9B,WAAmB;IAEnB,IAAI,CAAC;QACH,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,aAAa,CAAC,WAAW,EAAE;gBAC/B,IAAI,EAAE,SAAS;gBACf,QAAQ,EAAE,WAAW,WAAW,CAAC,SAAS,cAAc,WAAW,CAAC,MAAM,WAAW,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBAC9H,SAAS,EAAE,kBAAkB,WAAW,CAAC,KAAK,eAAe,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,QAAQ,GAAG,EAAE,CAAC,OAAO;gBACzG,UAAU,EAAE,QAAQ;aACrB,CAAC,CAAC;QACL,CAAC;QAED,qBAAqB;QACrB,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;YAC5B,MAAM,aAAa,CAAC,WAAW,EAAE;gBAC/B,OAAO,EAAE,cAAc,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,WAAW,IAAI,EAAE,EAAE;gBACzD,MAAM,EAAE,eAAe,WAAW,CAAC,SAAS,EAAE;gBAC9C,UAAU,EAAE,GAAG;gBACf,UAAU,EAAE,IAAI;aACjB,CAAC,CAAC;QACL,CAAC;QAED,+CAA+C;QAC/C,MAAM,WAAW,GAAG,IAAI,GAAG,EAAoB,CAAC;QAChD,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;YAC5B,KAAK,MAAM,KAAK,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;gBACnC,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;gBAC9C,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACpB,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QAED,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,CAAC;YACrD,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;gBACxB,MAAM,YAAY,CAAC,WAAW,EAAE;oBAC9B,IAAI,EAAE,UAAU;oBAChB,OAAO,EAAE,WAAW,WAAW,CAAC,SAAS,cAAc,OAAO,CAAC,MAAM,sBAAsB,KAAK,GAAG;oBACnG,OAAO,EAAE,mCAAmC,WAAW,CAAC,SAAS,EAAE;oBACnE,MAAM,EAAE,QAAQ;oBAChB,QAAQ,EAAE,OAAO;iBAClB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;IAClC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,WAAmB,EAAE,OAAiB;IAC7E,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,2BAA2B,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,WAAW,CAAC,CAAC;IAChD,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;YAAS,CAAC;QACT,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,eAAe,GACnB,kHAAkH,CAAC;AAErH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,WAAmB,EACnB,SAAiB,EACjB,UAAkB;IAElB,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;QACzE,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7E,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAErC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;QACzD,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,MAAM,aAAa,CAAC,WAAW,EAAE;gBAC/B,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;gBAClC,MAAM,EAAE,cAAc,SAAS,EAAE;gBACjC,UAAU,EAAE,GAAG;gBACf,UAAU,EAAE,KAAK;aAClB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;IAClC,CAAC;AACH,CAAC"}

package/dist/memory/brain-embedding.js

@@ -0,0 +1,66 @@
+/**
+ * Brain Embedding System
+ *
+ * Provides text-to-vector embedding for semantic search in brain.db.
+ * Uses a pluggable provider interface — real model integration
+ * (e.g. @huggingface/transformers with all-MiniLM-L6-v2) is separate
+ * from the embedding pipeline. When no provider is set, the system
+ * falls back to FTS5-only search gracefully.
+ *
+ * @epic T5149
+ * @task T5386
+ */
+/** Matches the brain_embeddings vec0 table: FLOAT[384]. */
+export const EMBEDDING_DIMENSIONS = 384;
+let currentProvider = null;
+/**
+ * Register an embedding provider for the brain system.
+ * Validates that the provider's dimensions match the vec0 table.
+ *
+ * @throws Error if provider dimensions do not match EMBEDDING_DIMENSIONS
+ */
+export function setEmbeddingProvider(provider) {
+    if (provider.dimensions !== EMBEDDING_DIMENSIONS) {
+        throw new Error(`Embedding provider dimensions (${provider.dimensions}) do not match vec0 table (${EMBEDDING_DIMENSIONS})`);
+    }
+    currentProvider = provider;
+}
+/** Get the currently registered embedding provider, or null. */
+export function getEmbeddingProvider() {
+    return currentProvider;
+}
+/** Clear the current embedding provider (useful for testing). */
+export function clearEmbeddingProvider() {
+    currentProvider = null;
+}
+/**
+ * Embed text into a float vector using the registered provider.
+ * Returns null when no provider is set or not available (FTS5-only fallback).
+ */
+export async function embedText(text) {
+    if (!currentProvider || !currentProvider.isAvailable())
+        return null;
+    return currentProvider.embed(text);
+}
+/** Check whether embedding is currently available. */
+export function isEmbeddingAvailable() {
+    return currentProvider?.isAvailable() ?? false;
+}
+/**
+ * Initialize the default local embedding provider.
+ *
+ * Loads the LocalEmbeddingProvider dynamically and registers it via
+ * setEmbeddingProvider(). Should be called once at startup when
+ * `brain.embedding.enabled` is true.
+ *
+ * Uses dynamic import to avoid loading the heavy @xenova/transformers
+ * bundle unless embedding is actually requested.
+ *
+ * @task T136 @epic T134
+ */
+export async function initDefaultProvider() {
+    const { LocalEmbeddingProvider } = await import('./embedding-local.js');
+    const provider = new LocalEmbeddingProvider();
+    setEmbeddingProvider(provider);
+}
+//# sourceMappingURL=brain-embedding.js.map

package/dist/memory/brain-embedding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-embedding.js","sourceRoot":"","sources":["../../src/memory/brain-embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH,2DAA2D;AAC3D,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAExC,IAAI,eAAe,GAA6B,IAAI,CAAC;AAErD;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAA2B;IAC9D,IAAI,QAAQ,CAAC,UAAU,KAAK,oBAAoB,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CACb,kCAAkC,QAAQ,CAAC,UAAU,8BAA8B,oBAAoB,GAAG,CAC3G,CAAC;IACJ,CAAC;IACD,eAAe,GAAG,QAAQ,CAAC;AAC7B,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,oBAAoB;IAClC,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,sBAAsB;IACpC,eAAe,GAAG,IAAI,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAY;IAC1C,IAAI,CAAC,eAAe,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE;QAAE,OAAO,IAAI,CAAC;IACpE,OAAO,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,oBAAoB;IAClC,OAAO,eAAe,EAAE,WAAW,EAAE,IAAI,KAAK,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,MAAM,EAAE,sBAAsB,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;IACxE,MAAM,QAAQ,GAAG,IAAI,sBAAsB,EAAE,CAAC;IAC9C,oBAAoB,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC"}