promptspeak-mcp-server 0.1.0

package/dist/symbols/manager.js

@@ -0,0 +1,1000 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * PROMPTSPEAK SYMBOL MANAGER
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * Manages storage, retrieval, and validation of directive symbols.
+ * Now backed by SQLite for ACID transactions, concurrent safety, and performance.
+ *
+ * Migration from JSON to SQLite provides:
+ * - Atomic commits (no partial writes)
+ * - WAL mode for concurrent read/write
+ * - Indexed queries (O(log n) vs O(n))
+ * - Built-in integrity constraints
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createLogger } from '../core/logging/index.js';
+import { LRUCache } from '../multi_agent/lru-cache.js';
+const logger = createLogger('SymbolManager');
+import { CATEGORY_PREFIX } from './types.js';
+import { getAuditLogger, initializeAuditLogger } from './audit.js';
+import { initializeDatabase } from './database.js';
+import { createDefaultEpistemicMetadata } from './epistemic-types.js';
+import { runValidationPipeline, runSecurityValidation, } from './validation-pipeline.js';
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════════
+const SYMBOL_PREFIX = 'Ξ';
+const DATABASE_FILE = 'promptspeak.db';
+// ═══════════════════════════════════════════════════════════════════════════════
+// CACHE CONFIGURATION
+// ═══════════════════════════════════════════════════════════════════════════════
+/** Default cache TTL: 5 minutes */
+const CACHE_TTL_MS = 5 * 60 * 1000;
+/** Maximum cache size */
+const CACHE_MAX_SIZE = 1000;
+// ═══════════════════════════════════════════════════════════════════════════════
+// SYMBOL MANAGER CLASS
+// ═══════════════════════════════════════════════════════════════════════════════
+export class SymbolManager {
+    symbolsRoot;
+    db;
+    cache;
+    constructor(symbolsRoot) {
+        this.symbolsRoot = symbolsRoot;
+        this.cache = new LRUCache({
+            maxSize: CACHE_MAX_SIZE,
+            ttlMs: CACHE_TTL_MS,
+        });
+        // Ensure directories exist
+        if (!fs.existsSync(symbolsRoot)) {
+            fs.mkdirSync(symbolsRoot, { recursive: true });
+        }
+        // Initialize SQLite database
+        const dbPath = path.join(symbolsRoot, DATABASE_FILE);
+        this.db = initializeDatabase(dbPath);
+        // Initialize audit logger
+        const logsDir = path.join(symbolsRoot, '..', 'logs');
+        initializeAuditLogger(logsDir);
+        // Migrate from JSON if needed
+        this.migrateFromJsonIfNeeded();
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // JSON MIGRATION
+    // ═══════════════════════════════════════════════════════════════════════════
+    migrateFromJsonIfNeeded() {
+        const registryPath = path.join(this.symbolsRoot, 'registry.json');
+        if (!fs.existsSync(registryPath)) {
+            return; // No JSON registry to migrate
+        }
+        // Check if we already have symbols in SQLite
+        const stats = this.db.getStats();
+        if (stats.totalSymbols > 0) {
+            // Rename old registry to indicate migration complete
+            const backupPath = path.join(this.symbolsRoot, 'registry.json.migrated');
+            if (!fs.existsSync(backupPath)) {
+                fs.renameSync(registryPath, backupPath);
+                logger.info('JSON registry backed up to registry.json.migrated');
+            }
+            return;
+        }
+        logger.info('Migrating from JSON to SQLite...');
+        try {
+            const registryData = fs.readFileSync(registryPath, 'utf-8');
+            const registry = JSON.parse(registryData);
+            let migrated = 0;
+            let failed = 0;
+            // Use transaction for atomic migration
+            this.db.transaction(() => {
+                for (const [symbolId, entry] of Object.entries(registry.symbols)) {
+                    try {
+                        // Load symbol file
+                        const symbolPath = path.join(this.symbolsRoot, entry.path);
+                        if (fs.existsSync(symbolPath)) {
+                            const symbolData = fs.readFileSync(symbolPath, 'utf-8');
+                            const symbol = JSON.parse(symbolData);
+                            const result = this.db.insertSymbol(symbol);
+                            if (result.success) {
+                                migrated++;
+                            }
+                            else {
+                                logger.warn(`[Migration] Failed to migrate ${symbolId}: ${result.error}`);
+                                failed++;
+                            }
+                        }
+                    }
+                    catch (err) {
+                        logger.warn(`[Migration] Error migrating ${symbolId}`, undefined, err instanceof Error ? err : undefined);
+                        failed++;
+                    }
+                }
+            });
+            logger.info(`Migration complete: ${migrated} symbols migrated, ${failed} failed`);
+            // Backup the old registry
+            const backupPath = path.join(this.symbolsRoot, 'registry.json.migrated');
+            fs.renameSync(registryPath, backupPath);
+            logger.info('JSON registry backed up to registry.json.migrated');
+        }
+        catch (err) {
+            logger.error('Migration failed', err instanceof Error ? err : undefined);
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SYMBOL ID VALIDATION
+    // ═══════════════════════════════════════════════════════════════════════════
+    validateSymbolId(symbolId) {
+        // Check prefix
+        if (!symbolId.startsWith(`${SYMBOL_PREFIX}.`)) {
+            return {
+                valid: false,
+                symbolId,
+                error: `Must start with ${SYMBOL_PREFIX}.`,
+            };
+        }
+        const parts = symbolId.slice(2).split('.');
+        if (parts.length < 2) {
+            return {
+                valid: false,
+                symbolId,
+                error: `Must have at least 2 segments after ${SYMBOL_PREFIX}.`,
+            };
+        }
+        // Check for namespace (lowercase first segment) - v2.0 feature
+        let namespace;
+        let categoryIndex = 0;
+        if (parts[0] && /^[a-z][a-z0-9_]*$/.test(parts[0])) {
+            namespace = parts[0];
+            categoryIndex = 1;
+            // Must have category + entity after namespace
+            if (parts.length < categoryIndex + 2) {
+                return {
+                    valid: false,
+                    symbolId,
+                    error: `Must have category and entity after namespace.`,
+                };
+            }
+        }
+        // Validate segments (skip namespace if present)
+        for (let i = categoryIndex; i < parts.length; i++) {
+            const part = parts[i];
+            if (!/^[A-Z0-9_]+$/.test(part)) {
+                return {
+                    valid: false,
+                    symbolId,
+                    error: `Segment "${part}" contains invalid characters. Use A-Z, 0-9, _ only.`,
+                };
+            }
+            if (part.length === 0 || part.length > 50) {
+                return {
+                    valid: false,
+                    symbolId,
+                    error: `Segment "${part}" must be 1-50 characters.`,
+                };
+            }
+        }
+        const categoryPart = parts[categoryIndex];
+        // Check for 2-letter category prefix first (v2.0 subcategories)
+        if (categoryPart.length === 2 && CATEGORY_PREFIX[categoryPart]) {
+            return {
+                valid: true,
+                symbolId,
+                category: CATEGORY_PREFIX[categoryPart],
+                namespace,
+                inferred: false,
+                segments: parts.slice(categoryIndex),
+            };
+        }
+        // Check for 1-letter category prefix
+        if (categoryPart.length === 1 && CATEGORY_PREFIX[categoryPart]) {
+            return {
+                valid: true,
+                symbolId,
+                category: CATEGORY_PREFIX[categoryPart],
+                namespace,
+                inferred: false,
+                segments: parts.slice(categoryIndex),
+            };
+        }
+        // Check if it looks like a ticker (1-5 uppercase letters)
+        if (/^[A-Z]{1,5}$/.test(categoryPart)) {
+            return {
+                valid: true,
+                symbolId,
+                category: 'COMPANY',
+                namespace,
+                inferred: true,
+                segments: parts.slice(categoryIndex),
+            };
+        }
+        // List available prefixes for error message
+        const validPrefixes = Object.keys(CATEGORY_PREFIX).sort().join('/');
+        return {
+            valid: false,
+            symbolId,
+            error: `First segment "${categoryPart}" is not a valid category prefix (${validPrefixes}) or ticker.`,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // HASH CALCULATION
+    // ═══════════════════════════════════════════════════════════════════════════
+    calculateHash(symbol) {
+        // Include only semantic content, not metadata
+        const content = {
+            who: symbol.who,
+            what: symbol.what,
+            why: symbol.why,
+            where: symbol.where,
+            when: symbol.when,
+            how: symbol.how,
+            commanders_intent: symbol.commanders_intent,
+            requirements: symbol.requirements,
+            anti_requirements: symbol.anti_requirements,
+            key_terms: symbol.key_terms,
+        };
+        const json = JSON.stringify(content, Object.keys(content).sort());
+        return createHash('sha256').update(json).digest('hex').substring(0, 16);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CREATE SYMBOL
+    // ═══════════════════════════════════════════════════════════════════════════
+    create(request) {
+        // Validate symbol ID
+        const validation = this.validateSymbolId(request.symbolId);
+        if (!validation.valid) {
+            return {
+                success: false,
+                symbolId: request.symbolId,
+                version: 0,
+                hash: '',
+                path: '',
+                error: validation.error,
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // VALIDATION PIPELINE: Security + Epistemic validation
+        // ─────────────────────────────────────────────────────────────────────────
+        const pipelineResult = runValidationPipeline(request, 'CREATE', this.db, { runEpistemic: true });
+        if (!pipelineResult.passed) {
+            return {
+                success: false,
+                symbolId: request.symbolId,
+                version: 0,
+                hash: '',
+                path: '',
+                error: pipelineResult.error,
+            };
+        }
+        // Get epistemic metadata from pipeline result
+        const epistemicMetadata = pipelineResult.epistemic.metadata;
+        // ─────────────────────────────────────────────────────────────────────────
+        // Check if already exists
+        if (this.db.symbolExists(request.symbolId)) {
+            return {
+                success: false,
+                symbolId: request.symbolId,
+                version: 0,
+                hash: '',
+                path: '',
+                error: `Symbol ${request.symbolId} already exists. Use update instead.`,
+            };
+        }
+        const category = request.category || validation.category;
+        const now = new Date().toISOString();
+        // Build symbol
+        const symbol = {
+            symbolId: request.symbolId,
+            version: 1,
+            hash: '', // Calculated below
+            category,
+            subcategory: request.subcategory,
+            tags: request.tags,
+            who: request.who,
+            what: request.what,
+            why: request.why,
+            where: request.where,
+            when: request.when,
+            how: request.how,
+            commanders_intent: request.commanders_intent,
+            requirements: request.requirements,
+            anti_requirements: request.anti_requirements,
+            key_terms: request.key_terms,
+            created_at: now,
+            created_by: request.created_by,
+            parent_symbol: request.parent_symbol,
+            related_symbols: request.related_symbols,
+            source_dataset: request.source_dataset,
+            source_id: request.source_id,
+            source_data: request.source_data,
+            changelog: [{
+                    version: 1,
+                    change: 'Initial creation',
+                    timestamp: now,
+                    changed_by: request.created_by,
+                }],
+            // v2.1: Epistemic uncertainty tracking
+            epistemic: epistemicMetadata,
+        };
+        // Calculate hash
+        symbol.hash = this.calculateHash(symbol);
+        // Insert into database
+        const result = this.db.insertSymbol(symbol);
+        if (!result.success) {
+            return {
+                success: false,
+                symbolId: request.symbolId,
+                version: 0,
+                hash: '',
+                path: '',
+                error: result.error || 'Failed to insert symbol',
+            };
+        }
+        // Update cache
+        this.cache.set(request.symbolId, symbol);
+        // Log successful creation
+        const auditLogger = getAuditLogger();
+        if (auditLogger) {
+            auditLogger.logCreate(request.symbolId, true, pipelineResult.security.validation, {
+                category,
+                hash: symbol.hash,
+            });
+        }
+        this.db.insertAuditEntry({
+            eventType: 'SYMBOL_CREATE',
+            symbolId: request.symbolId,
+            details: { category, hash: symbol.hash },
+        });
+        return {
+            success: true,
+            symbolId: request.symbolId,
+            version: 1,
+            hash: symbol.hash,
+            path: `sqlite:${request.symbolId}`, // Indicate SQLite storage
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // GET SYMBOL
+    // ═══════════════════════════════════════════════════════════════════════════
+    get(request) {
+        // Check cache first (O(1) lookup)
+        const cached = this.cache.get(request.symbolId);
+        if (cached) {
+            if (!request.version || cached.version === request.version) {
+                return {
+                    found: true,
+                    symbol: request.include_changelog === false
+                        ? { ...cached, changelog: undefined }
+                        : cached,
+                };
+            }
+        }
+        // Query database
+        const symbol = this.db.getSymbol(request.symbolId);
+        if (!symbol) {
+            return {
+                found: false,
+                error: `Symbol ${request.symbolId} not found`,
+            };
+        }
+        // Check version if requested
+        if (request.version && symbol.version !== request.version) {
+            return {
+                found: false,
+                error: `Version ${request.version} not found. Current version is ${symbol.version}`,
+            };
+        }
+        // Update cache
+        this.cache.set(request.symbolId, symbol);
+        return {
+            found: true,
+            symbol: request.include_changelog === false
+                ? { ...symbol, changelog: undefined }
+                : symbol,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // UPDATE SYMBOL
+    // ═══════════════════════════════════════════════════════════════════════════
+    update(request) {
+        // Get existing symbol
+        const existing = this.get({ symbolId: request.symbolId });
+        if (!existing.found || !existing.symbol) {
+            return {
+                success: false,
+                symbolId: request.symbolId,
+                old_version: 0,
+                new_version: 0,
+                old_hash: '',
+                new_hash: '',
+                error: existing.error || `Symbol ${request.symbolId} not found`,
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // SECURITY: Validate update changes before applying
+        // ─────────────────────────────────────────────────────────────────────────
+        // Build content to validate (merged with existing values)
+        const contentToValidate = {
+            symbolId: request.symbolId,
+            who: request.changes.who || existing.symbol.who,
+            what: request.changes.what || existing.symbol.what,
+            why: request.changes.why || existing.symbol.why,
+            where: request.changes.where || existing.symbol.where,
+            when: request.changes.when || existing.symbol.when,
+            how: request.changes.how || existing.symbol.how,
+            commanders_intent: request.changes.commanders_intent || existing.symbol.commanders_intent,
+            requirements: request.changes.requirements || existing.symbol.requirements,
+            anti_requirements: request.changes.anti_requirements || existing.symbol.anti_requirements,
+        };
+        const securityResult = runSecurityValidation(contentToValidate, 'UPDATE', this.db);
+        if (!securityResult.passed) {
+            return {
+                success: false,
+                symbolId: request.symbolId,
+                old_version: existing.symbol.version,
+                new_version: 0,
+                old_hash: existing.symbol.hash,
+                new_hash: '',
+                error: securityResult.error,
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        const oldSymbol = existing.symbol;
+        const now = new Date().toISOString();
+        // Handle epistemic metadata merge separately to preserve full type
+        const { epistemic: epistemicChanges, ...otherChanges } = request.changes;
+        const mergedEpistemic = epistemicChanges
+            ? {
+                ...(oldSymbol.epistemic || createDefaultEpistemicMetadata()),
+                ...epistemicChanges,
+            }
+            : oldSymbol.epistemic;
+        // Build updated symbol
+        const updated = {
+            ...oldSymbol,
+            ...otherChanges,
+            epistemic: mergedEpistemic,
+            symbolId: oldSymbol.symbolId, // Cannot change ID
+            version: oldSymbol.version + 1,
+            hash: '', // Recalculated below
+            created_at: oldSymbol.created_at, // Cannot change
+            updated_at: now,
+            changelog: [
+                ...(oldSymbol.changelog || []),
+                {
+                    version: oldSymbol.version + 1,
+                    change: request.change_description,
+                    timestamp: now,
+                    changed_by: request.changed_by,
+                },
+            ],
+        };
+        // Recalculate hash
+        updated.hash = this.calculateHash(updated);
+        // Update in database
+        const result = this.db.updateSymbol(updated);
+        if (!result.success) {
+            return {
+                success: false,
+                symbolId: request.symbolId,
+                old_version: oldSymbol.version,
+                new_version: 0,
+                old_hash: oldSymbol.hash,
+                new_hash: '',
+                error: result.error || 'Failed to update symbol',
+            };
+        }
+        // Update cache
+        this.cache.set(request.symbolId, updated);
+        this.db.insertAuditEntry({
+            eventType: 'SYMBOL_UPDATE',
+            symbolId: request.symbolId,
+            details: {
+                oldVersion: oldSymbol.version,
+                newVersion: updated.version,
+                change: request.change_description,
+            },
+        });
+        return {
+            success: true,
+            symbolId: request.symbolId,
+            old_version: oldSymbol.version,
+            new_version: updated.version,
+            old_hash: oldSymbol.hash,
+            new_hash: updated.hash,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // LIST SYMBOLS
+    // ═══════════════════════════════════════════════════════════════════════════
+    list(request) {
+        const result = this.db.listSymbols({
+            category: request.category,
+            search: request.search,
+            createdAfter: request.created_after,
+            createdBefore: request.created_before,
+            limit: request.limit || 50,
+            offset: request.offset || 0,
+        });
+        // Convert to expected format
+        const symbols = result.symbols.map(entry => ({
+            symbolId: entry.symbolId,
+            category: entry.category,
+            version: entry.version,
+            hash: entry.hash,
+            commanders_intent: entry.commanders_intent_preview || '',
+            created_at: entry.created_at,
+            updated_at: entry.updated_at,
+        }));
+        return {
+            symbols,
+            total: result.total,
+            has_more: result.hasMore,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // DELETE SYMBOL
+    // ═══════════════════════════════════════════════════════════════════════════
+    delete(request) {
+        // Check if exists
+        if (!this.db.symbolExists(request.symbolId)) {
+            return {
+                success: false,
+                deleted: false,
+                error: `Symbol ${request.symbolId} not found`,
+            };
+        }
+        // Delete from database
+        const result = this.db.deleteSymbol(request.symbolId);
+        if (result.deleted) {
+            // Remove from cache
+            this.cache.delete(request.symbolId);
+            this.db.insertAuditEntry({
+                eventType: 'SYMBOL_DELETE',
+                symbolId: request.symbolId,
+                details: { reason: request.reason },
+            });
+        }
+        return {
+            success: true,
+            deleted: result.deleted,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // IMPORT SYMBOLS
+    // ═══════════════════════════════════════════════════════════════════════════
+    import(request) {
+        const symbolsCreated = [];
+        const errors = [];
+        let imported = 0;
+        // Parse data based on source
+        let rows = [];
+        if (request.source === 'json') {
+            if (Array.isArray(request.data)) {
+                rows = request.data;
+            }
+            else {
+                return {
+                    success: false,
+                    imported: 0,
+                    failed: 0,
+                    symbols_created: [],
+                    errors: [{ index: -1, error: 'JSON data must be an array' }],
+                };
+            }
+        }
+        else if (request.source === 'huggingface') {
+            // HuggingFace format: { rows: [{ row: {...} }, ...] }
+            const hfData = request.data;
+            if (hfData.rows && Array.isArray(hfData.rows)) {
+                rows = hfData.rows.map(r => r.row);
+            }
+            else {
+                return {
+                    success: false,
+                    imported: 0,
+                    failed: 0,
+                    symbols_created: [],
+                    errors: [{ index: -1, error: 'Invalid HuggingFace data format' }],
+                };
+            }
+        }
+        // Use transaction for atomic import
+        this.db.transaction(() => {
+            for (let i = 0; i < rows.length; i++) {
+                const row = rows[i];
+                try {
+                    // Generate symbol ID
+                    const symbolId = `${request.id_prefix}.${String(i + 1).padStart(3, '0')}`;
+                    // Apply transforms or use defaults
+                    const transform = request.transform || {};
+                    const defaults = request.defaults || {};
+                    const getValue = (field, fallback) => {
+                        const t = transform[field];
+                        if (typeof t === 'function') {
+                            const result = t(row);
+                            return Array.isArray(result) ? result[0] || fallback : String(result);
+                        }
+                        if (typeof t === 'string' && row[t] !== undefined)
+                            return String(row[t]);
+                        if (defaults[field])
+                            return String(defaults[field]);
+                        return fallback;
+                    };
+                    const getArrayValue = (field, fallback) => {
+                        const t = transform[field];
+                        if (typeof t === 'function')
+                            return t(row);
+                        if (typeof t === 'string' && row[t] !== undefined) {
+                            const val = row[t];
+                            if (Array.isArray(val))
+                                return val.map(String);
+                            if (typeof val === 'string')
+                                return [val];
+                        }
+                        if (defaults[field]) {
+                            const def = defaults[field];
+                            return Array.isArray(def) ? def.map(String) : [String(def)];
+                        }
+                        return fallback;
+                    };
+                    // Build create request
+                    const createRequest = {
+                        symbolId,
+                        category: request.category,
+                        who: getValue('who', 'Benchmark System'),
+                        what: getValue('what', String(row['question'] || row['query'] || 'Unknown')),
+                        why: getValue('why', 'Benchmark evaluation'),
+                        where: getValue('where', request.id_prefix),
+                        when: getValue('when', new Date().toISOString().split('T')[0]),
+                        how: {
+                            focus: getArrayValue('requirements', ['accuracy', 'completeness']),
+                            constraints: ['cite_sources'],
+                        },
+                        commanders_intent: getValue('commanders_intent', 'Provide accurate answer'),
+                        requirements: getArrayValue('requirements', ['Answer the question']),
+                        key_terms: getArrayValue('key_terms', []),
+                        source_dataset: request.id_prefix.replace(`${SYMBOL_PREFIX}.Q.`, '').toLowerCase(),
+                        source_id: String(i + 1),
+                        source_data: row,
+                    };
+                    const result = this.create(createRequest);
+                    if (result.success) {
+                        imported++;
+                        symbolsCreated.push(symbolId);
+                    }
+                    else {
+                        errors.push({ index: i, error: result.error || 'Unknown error' });
+                    }
+                }
+                catch (e) {
+                    errors.push({ index: i, error: String(e) });
+                }
+            }
+        });
+        return {
+            success: errors.length === 0,
+            imported,
+            failed: errors.length,
+            symbols_created: symbolsCreated,
+            errors: errors.length > 0 ? errors : undefined,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // EXPORT SYMBOLS (NEW - for JSON backup)
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Export all symbols to JSON format for backup/portability
+     */
+    exportToJson(outputPath) {
+        try {
+            const symbols = this.db.getAllSymbols();
+            const stats = this.db.getStats();
+            const exportData = {
+                version: '2.0.0',
+                exported_at: new Date().toISOString(),
+                format: 'sqlite-export',
+                stats: {
+                    total_symbols: stats.totalSymbols,
+                    by_category: stats.byCategory,
+                },
+                symbols,
+            };
+            const exportPath = outputPath || path.join(this.symbolsRoot, 'symbols-export.json');
+            fs.writeFileSync(exportPath, JSON.stringify(exportData, null, 2));
+            return {
+                success: true,
+                path: exportPath,
+                count: symbols.length,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                count: 0,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // EPISTEMIC VERIFICATION METHODS (v2.1)
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Verify a symbol claim - update its epistemic status based on human review.
+     * This is used to promote claims from INFERENCE → VERIFIED or mark as DISPUTED.
+     */
+    verifySymbol(request) {
+        // Get existing symbol
+        const existing = this.get({ symbolId: request.symbolId });
+        if (!existing.found || !existing.symbol) {
+            return {
+                success: false,
+                error: existing.error || `Symbol ${request.symbolId} not found`,
+            };
+        }
+        const oldEpistemic = existing.symbol.epistemic;
+        const oldStatus = oldEpistemic?.status || 'INFERENCE';
+        const oldConfidence = oldEpistemic?.confidence ?? 0.5;
+        // Determine new confidence
+        let newConfidence = request.new_confidence;
+        if (newConfidence === undefined) {
+            // Auto-calculate based on new status
+            switch (request.new_status) {
+                case 'VERIFIED':
+                    newConfidence = Math.max(oldConfidence, 0.9);
+                    break;
+                case 'CORROBORATED':
+                    newConfidence = Math.min(oldConfidence * 1.2, 0.85);
+                    break;
+                case 'DISPUTED':
+                    newConfidence = Math.min(oldConfidence * 0.3, 0.2);
+                    break;
+            }
+        }
+        // Build updated epistemic metadata
+        const updatedEpistemic = {
+            ...oldEpistemic,
+            status: request.new_status,
+            confidence: newConfidence,
+            requires_human_review: request.new_status === 'DISPUTED', // Re-review disputed
+            review_reason: request.new_status === 'DISPUTED'
+                ? `Disputed by ${request.reviewer}: ${request.notes || 'No reason provided'}`
+                : undefined,
+            verification_history: [
+                ...(oldEpistemic?.verification_history || []),
+                {
+                    event_type: request.new_status === 'VERIFIED' ? 'VERIFIED' :
+                        request.new_status === 'DISPUTED' ? 'DISPUTED' : 'CORROBORATED',
+                    timestamp: new Date().toISOString(),
+                    old_status: oldStatus,
+                    new_status: request.new_status,
+                    old_confidence: oldConfidence,
+                    new_confidence: newConfidence,
+                    reviewer: request.reviewer,
+                    evidence_added: request.evidence_added,
+                    notes: request.notes,
+                },
+            ],
+        };
+        // If evidence was added, update evidence basis
+        if (request.evidence_added && request.evidence_added.length > 0) {
+            updatedEpistemic.evidence_basis = {
+                ...(oldEpistemic?.evidence_basis || {
+                    sources_consulted: [],
+                    sources_not_consulted: [],
+                    cross_references_performed: false,
+                    alternative_explanations: [],
+                    methodology: 'Unknown',
+                }),
+                sources_consulted: [
+                    ...(oldEpistemic?.evidence_basis?.sources_consulted || []),
+                    ...request.evidence_added,
+                ],
+            };
+        }
+        // Update the symbol
+        const updateResult = this.update({
+            symbolId: request.symbolId,
+            changes: { epistemic: updatedEpistemic },
+            change_description: `Status changed to ${request.new_status} by ${request.reviewer}`,
+            changed_by: request.reviewer,
+        });
+        if (!updateResult.success) {
+            return {
+                success: false,
+                error: updateResult.error,
+            };
+        }
+        // Log verification event to database
+        this.db.insertVerificationEvent({
+            symbolId: request.symbolId,
+            eventType: request.new_status === 'VERIFIED' ? 'VERIFIED' :
+                request.new_status === 'DISPUTED' ? 'DISPUTED' : 'CORROBORATED',
+            oldStatus: oldStatus,
+            newStatus: request.new_status,
+            oldConfidence: oldConfidence,
+            newConfidence: newConfidence,
+            reviewer: request.reviewer,
+            evidenceAdded: request.evidence_added,
+            notes: request.notes,
+        });
+        // Log to audit
+        const auditEventType = request.new_status === 'DISPUTED' ? 'SYMBOL_DISPUTED' : 'SYMBOL_VERIFIED';
+        this.db.insertAuditEntry({
+            eventType: auditEventType,
+            symbolId: request.symbolId,
+            details: {
+                oldStatus,
+                newStatus: request.new_status,
+                oldConfidence,
+                newConfidence,
+                reviewer: request.reviewer,
+                notes: request.notes,
+            },
+        });
+        return { success: true };
+    }
+    /**
+     * List symbols that require human review due to epistemic concerns.
+     */
+    listUnverifiedSymbols(request) {
+        const result = this.db.listSymbolsNeedingReview({
+            claimType: request.claim_type,
+            minConfidence: request.min_confidence,
+            maxConfidence: request.max_confidence,
+            limit: request.limit || 50,
+            offset: request.offset || 0,
+        });
+        const symbols = result.symbols.map(row => {
+            const symbol = JSON.parse(row.data);
+            return {
+                symbolId: symbol.symbolId,
+                category: symbol.category,
+                commanders_intent: symbol.commanders_intent,
+                epistemic_status: symbol.epistemic?.status || 'INFERENCE',
+                confidence: symbol.epistemic?.confidence ?? 0.5,
+                review_reason: symbol.epistemic?.review_reason,
+                triggered_patterns: undefined, // Would need to re-validate to get these
+                created_at: symbol.created_at,
+            };
+        });
+        return {
+            symbols,
+            total: result.total,
+            has_more: (request.offset || 0) + symbols.length < result.total,
+        };
+    }
+    /**
+     * Add an alternative explanation to a symbol's evidence basis.
+     * This is crucial for preventing false positives in accusatory findings.
+     */
+    addAlternativeExplanation(request) {
+        // Get existing symbol
+        const existing = this.get({ symbolId: request.symbolId });
+        if (!existing.found || !existing.symbol) {
+            return {
+                success: false,
+                error: existing.error || `Symbol ${request.symbolId} not found`,
+            };
+        }
+        const oldEpistemic = existing.symbol.epistemic;
+        // Build new alternative explanation
+        const newAlternative = {
+            explanation: request.alternative,
+            likelihood: Math.max(0, Math.min(1, request.likelihood)),
+            reasoning: request.reasoning,
+            investigated: false,
+        };
+        // Update evidence basis
+        const updatedEvidenceBasis = {
+            ...(oldEpistemic?.evidence_basis || {
+                sources_consulted: [],
+                sources_not_consulted: [],
+                cross_references_performed: false,
+                alternative_explanations: [],
+                methodology: 'Unknown',
+            }),
+            alternative_explanations: [
+                ...(oldEpistemic?.evidence_basis?.alternative_explanations || []),
+                newAlternative,
+            ],
+        };
+        // Recalculate confidence based on alternative explanations
+        // If alternatives have high likelihood, reduce confidence in the original claim
+        const totalAlternativeLikelihood = updatedEvidenceBasis.alternative_explanations
+            .reduce((sum, alt) => sum + alt.likelihood, 0);
+        const confidenceReduction = Math.min(totalAlternativeLikelihood * 0.3, 0.4);
+        const newConfidence = Math.max(0.1, (oldEpistemic?.confidence ?? 0.5) - confidenceReduction);
+        // Build updated epistemic metadata
+        const updatedEpistemic = {
+            ...oldEpistemic,
+            evidence_basis: updatedEvidenceBasis,
+            confidence: newConfidence,
+            verification_history: [
+                ...(oldEpistemic?.verification_history || []),
+                {
+                    event_type: 'ALTERNATIVE_ADDED',
+                    timestamp: new Date().toISOString(),
+                    old_confidence: oldEpistemic?.confidence ?? 0.5,
+                    new_confidence: newConfidence,
+                    reviewer: request.added_by,
+                    notes: `Added alternative: "${request.alternative}" (likelihood: ${request.likelihood})`,
+                },
+            ],
+        };
+        // Update the symbol
+        const updateResult = this.update({
+            symbolId: request.symbolId,
+            changes: { epistemic: updatedEpistemic },
+            change_description: `Alternative explanation added by ${request.added_by}`,
+            changed_by: request.added_by,
+        });
+        if (!updateResult.success) {
+            return {
+                success: false,
+                error: updateResult.error,
+            };
+        }
+        // Log verification event
+        this.db.insertVerificationEvent({
+            symbolId: request.symbolId,
+            eventType: 'ALTERNATIVE_ADDED',
+            oldConfidence: oldEpistemic?.confidence ?? 0.5,
+            newConfidence: newConfidence,
+            reviewer: request.added_by,
+            notes: `Alternative: "${request.alternative}" (likelihood: ${request.likelihood})`,
+        });
+        return { success: true };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // UTILITY METHODS
+    // ═══════════════════════════════════════════════════════════════════════════
+    getStats() {
+        const dbStats = this.db.getStats();
+        return {
+            total_symbols: dbStats.totalSymbols,
+            by_category: dbStats.byCategory,
+        };
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+    reload() {
+        this.cache.clear();
+    }
+    /**
+     * Get database-specific stats
+     */
+    getDatabaseStats() {
+        return this.db.getStats();
+    }
+    /**
+     * Optimize the database
+     */
+    optimizeDatabase() {
+        this.db.optimize();
+    }
+    /**
+     * Check database integrity
+     */
+    checkIntegrity() {
+        return this.db.checkIntegrity();
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// SINGLETON INSTANCE
+// ═══════════════════════════════════════════════════════════════════════════════
+let symbolManager = null;
+export function initializeSymbolManager(symbolsRoot) {
+    symbolManager = new SymbolManager(symbolsRoot);
+    return symbolManager;
+}
+export function getSymbolManager() {
+    if (!symbolManager) {
+        throw new Error('SymbolManager not initialized. Call initializeSymbolManager first.');
+    }
+    return symbolManager;
+}
+//# sourceMappingURL=manager.js.map