TagMemoEngine.js

// TagMemoEngine.js
// 🌟 浪潮算法独立模块 (TagMemo Engine)
// 包含：浪潮增强、EPA 投影、残差金字塔分析、有序双向共现矩阵 (V8.2)、脉冲传播等核心逻辑

const path = require('path');
const crypto = require('crypto');
const EPAModule = require('./EPAModule');
const ResidualPyramid = require('./ResidualPyramid');

class TagMemoEngine {
    constructor(db, tagIndex, config, ragParams) {
        this.db = db;
        this.tagIndex = tagIndex;
        this.config = config;
        this.ragParams = ragParams;

        this.epa = null;
        this.residualPyramid = null;
        this.tagCooccurrenceMatrix = null;
        this.tagIntrinsicResiduals = null;

        // 🌟 TagMemo V7.1: 矩阵计算防抖系统
        this._accumulatedTagChanges = 0;
        this._matrixRebuildTimer = null;
        this._matrixRebuildScheduleLogged = false;
        this._isMatrixRebuilding = false;
        // 🌟 V8: 距离场缓存（供测地线重排使用）
        this.lastEnergyField = null;

        // 🌟 V8.2-γ: 持久化的 Tag 对语义距离 (内存 Map: "a:b" → cosineSim)
        // 边视角的语义邻近度，与 tagIntrinsicResiduals (节点视角) 正交。
        this.tagPairSimilarities = new Map();
        // embedding 模型签名 (含维度)，跨模型自动失效
        this.modelSig = this._computeModelSig();
        // 是否在本进程内已经触发过冷启动 sim 预计算
        this._pairSimColdStartDone = false;
    }

    /**
     * 🌟 V8.2: 计算 embedding 模型签名（必须包含维度，
     * 防止 VECTORDB_DIMENSION 切换后读到维度错位的 BLOB）
     */
    _computeModelSig() {
        // EmbeddingModelSig 表示“向量语义空间签名”，与实际请求渠道解耦。
        // 未配置时回退到主 embedding 模型名，保持旧版本行为。
        const modelName = this.config?.modelSig || this.config?.model || 'unknown-model';
        const dim = this.config?.dimension || 0;
        return crypto.createHash('sha256')
            .update(`${modelName}:${dim}`)
            .digest('hex')
            .slice(0, 16);
    }

    _decodeVectorBlob(blob, dim, label = 'vector') {
        if (blob instanceof Float32Array) {
            return blob.length === dim ? blob : null;
        }
        if (!blob || typeof blob.length !== 'number') {
            return null;
        }

        const expectedBytes = dim * Float32Array.BYTES_PER_ELEMENT;
        if (blob.length !== expectedBytes) {
            console.warn(`[TagMemoEngine] ⚠️ Invalid ${label} blob length: expected ${expectedBytes}, got ${blob.length}`);
            return null;
        }

        if (blob.byteOffset % Float32Array.BYTES_PER_ELEMENT === 0) {
            return new Float32Array(blob.buffer, blob.byteOffset, dim);
        }

        const copied = Buffer.from(blob);
        return new Float32Array(copied.buffer, copied.byteOffset, dim);
    }

    _queryByChunks(sqlPrefix, values, sqlSuffix = '', chunkSize = 500) {
        if (!Array.isArray(values) || values.length === 0) return [];
        const rows = [];

        for (let i = 0; i < values.length; i += chunkSize) {
            const batch = values.slice(i, i + chunkSize);
            const placeholders = batch.map(() => '?').join(',');
            rows.push(...this.db.prepare(`${sqlPrefix} IN (${placeholders})${sqlSuffix}`).all(...batch));
        }

        return rows;
    }

    async initialize() {
        // 初始化 EPA 和残差金字塔模块
        this.epa = new EPAModule(this.db, {
            dimension: this.config.dimension,
            vexusIndex: this.tagIndex,
            nodeResidual: this.ragParams.KnowledgeBaseManager?.nodeResidualGain || 0.05,
        });
        await this.epa.initialize();

        this.residualPyramid = new ResidualPyramid(this.tagIndex, this.db, {
            dimension: this.config.dimension
        });

        // 🌟 V8.2-γ: 冷启动钩子
        // 若 tag_pair_similarity 表为空（首次启动 / 模型签名变化），
        // 必须 await 阻塞预计算，否则 buildDirectedCooccurrenceMatrix 拿到的 getSim() 全是 fallback，
        // semanticGain 会均匀压平整张矩阵，当天召回质量异常。
        try {
            const cnt = this.db.prepare(
                'SELECT COUNT(*) as c FROM tag_pair_similarity WHERE model_sig = ?'
            ).get(this.modelSig)?.c || 0;

            if (cnt === 0) {
                console.log(`[TagMemoEngine] 🧊 V8.2 cold start: pairwise similarity cache empty for model_sig=${this.modelSig}, computing now...`);
                await this.recomputePairwiseSimilarities({ blocking: true });
                this._pairSimColdStartDone = true;
            } else {
                console.log(`[TagMemoEngine] 🌡️ V8.2 warm start: ${cnt} cached pairwise similarities for model_sig=${this.modelSig}`);
            }
        } catch (e) {
            console.warn('[TagMemoEngine] ⚠️ V8.2 cold start check failed (table may not exist yet):', e.message);
        }

        // 加载矩阵依赖的持久化底座：边相似度 + 节点内生残差
        this.loadPairwiseSimilarities();
        this.loadIntrinsicResiduals();

        // 启动时构建共现矩阵：确保 reverseAnchorBoost 能吃到已加载残差
        this.buildDirectedCooccurrenceMatrix();
    }

    /**
     * 更新热调控参数
     */
    updateRagParams(params) {
        this.ragParams = params;
        if (this.epa) {
            // 如果 EPA 支持动态更新参数，可以在这里调用
        }
    }

    /**
     * 🌟 TagMemo 浪潮 + EPA + Residual Pyramid + Worldview Gating + LIF Spike Propagation (V6)
     */
    applyTagBoost(vector, baseTagBoost, coreTags = [], coreBoostFactor = 1.33) {
        const debug = false;
        const originalFloat32 = vector instanceof Float32Array ? vector : new Float32Array(vector);
        const dim = originalFloat32.length;

        try {
            // 🌟 V8: 清空旧距离场，防止跨调用数据泄露
            this.lastEnergyField = null;

            // [1] EPA 分析 (逻辑深度与共振) - 识别"你在哪个世界"
            const epaResult = this.epa.project(originalFloat32);
            const resonance = this.epa.detectCrossDomainResonance(originalFloat32);
            const queryWorld = epaResult.dominantAxes[0]?.label || 'Unknown';

            // [2] 残差金字塔分析 (新颖度与覆盖率) - 90% 能量截断
            const pyramid = this.residualPyramid.analyze(originalFloat32);
            const features = pyramid.features;

            // [3] 动态调整策略
            const config = this.ragParams?.KnowledgeBaseManager || {};
            const logicDepth = epaResult.logicDepth;        // 0~1, 高=逻辑聚焦
            const entropyPenalty = epaResult.entropy;       // 0~1, 高=信息散乱
            const resonanceBoost = Math.log(1 + resonance.resonance);

            // 核心公式：结合 EPA 和残差特征
            const actRange = config.activationMultiplier || [0.5, 1.5];
            const activationMultiplier = actRange[0] + features.tagMemoActivation * (actRange[1] - actRange[0]);
            const dynamicBoostFactor = (logicDepth * (1 + resonanceBoost) / (1 + entropyPenalty * 0.5)) * activationMultiplier;

            const boostRange = config.dynamicBoostRange || [0.3, 2.0];
            const effectiveTagBoost = baseTagBoost * Math.max(boostRange[0], Math.min(boostRange[1], dynamicBoostFactor));

            // 🌟 动态核心加权优化 (Dynamic Core Boost Optimization)
            // 目标范围：1.20 (20%) ~ 1.40 (40%)
            // 逻辑：逻辑深度越高（意图明确）或覆盖率越低（新领域需要锚点），核心标签权重越高
            const coreMetric = (logicDepth * 0.5) + ((1 - features.coverage) * 0.5);
            const coreRange = config.coreBoostRange || [1.20, 1.40];
            const dynamicCoreBoostFactor = coreRange[0] + (coreMetric * (coreRange[1] - coreRange[0]));

            if (debug) {
                console.log(`[TagMemo-V6] World=${queryWorld}, Depth=${logicDepth.toFixed(3)}, Resonance=${resonance.resonance.toFixed(3)}`);
                console.log(`[TagMemo-V6] Coverage=${features.coverage.toFixed(3)}, Explained=${(pyramid.totalExplainedEnergy * 100).toFixed(1)}%`);
                console.log(`[TagMemo-V6] Effective Boost: ${effectiveTagBoost.toFixed(3)}, Dynamic Core Boost: ${dynamicCoreBoostFactor.toFixed(3)}`);
            }

            // [4] 收集金字塔中的所有 Tags 并应用“世界观门控”与“语言补偿”
            const allTags = [];
            const seenTagIds = new Set();

            // 🌟 莱恩的鲁棒分流法：鸭子类型分离输入参数
            const coreTagStrings = [];
            const hardGhostObjects = [];
            const softGhostObjects = [];

            if (Array.isArray(coreTags)) {
                coreTags.forEach(t => {
                    if (typeof t === 'string') {
                        coreTagStrings.push(t.toLowerCase());
                    } else if (t && t.name && t.vector) {
                        // 如果带有向量，说明是幽灵对象，按 isCore 再次分流
                        if (t.isCore) hardGhostObjects.push(t);
                        else softGhostObjects.push(t);
                    }
                });
            }
            // 这个 Set 只管原生的字符串补全逻辑
            const coreTagSet = new Set(coreTagStrings);

            // 🛡️ 防御性检查：确保 pyramid.levels 存在且为数组
            const levels = Array.isArray(pyramid.levels) ? pyramid.levels : [];

            levels.forEach(level => {
                // 🛡️ 防御性检查：确保 level.tags 存在且为数组
                const tags = Array.isArray(level.tags) ? level.tags : [];

                tags.forEach(t => {
                    if (!t || seenTagIds.has(t.id)) return;

                    // 🌟 核心 Tag 增强逻辑 (Spotlight)
                    // 安全访问 t.name
                    const tagName = t.name ? t.name.toLowerCase() : '';
                    const isCore = tagName && coreTagSet.has(tagName);
                    // 🌟 个体相关度微调：如果核心标签本身与查询高度相关，在动态基准上给予额外奖励 (0.95 ~ 1.05x)
                    const individualRelevance = t.similarity || 0.5;
                    const coreBoost = isCore ? (dynamicCoreBoostFactor * (0.95 + individualRelevance * 0.1)) : 1.0;

                    // A. 语言置信度补偿 (Language Confidence Gating)
                    // 如果是纯英文技术词汇且当前不是技术语境，引入惩罚
                    let langPenalty = 1.0;
                    if (this.config.langConfidenceEnabled) {
                        // 扩展技术噪音检测：非中文且符合技术命名特征（允许空格以覆盖如 Dadroit JSON Viewer）
                        // 安全访问 t.name
                        const tName = t.name || '';
                        const isTechnicalNoise = !/[\u4e00-\u9fa5]/.test(tName) && /^[A-Za-z0-9\-_.\s]+$/.test(tName) && tName.length > 3;
                        const isTechnicalWorld = queryWorld !== 'Unknown' && /^[A-Za-z0-9\-_.]+$/.test(queryWorld);

                        if (isTechnicalNoise && !isTechnicalWorld) {
                            // 🌟 阶梯式语言补偿：不再一刀切
                            // 如果是政治/社会世界观，减轻对英文实体的压制（可能是 Trump, Musk 等重要实体）
                            // 🌟 更加鲁棒的世界观判定：使用模糊匹配
                            const isSocialWorld = /Politics|Society|History|Economics|Culture/i.test(queryWorld);
                            const comp = config.languageCompensator || {};
                            const basePenalty = queryWorld === 'Unknown'
                                ? (comp.penaltyUnknown ?? this.config.langPenaltyUnknown)
                                : (comp.penaltyCrossDomain ?? this.config.langPenaltyCrossDomain);
                            langPenalty = isSocialWorld ? Math.sqrt(basePenalty) : basePenalty; // 使用平方根软化惩罚
                        }
                    }

                    // B. 世界观门控 (Worldview Gating)
                    // 简单实现：如果 Tag 本身有向量，检查其与查询世界的正交性
                    // 这里暂用 layerDecay 代替复杂的实时投影以保证性能
                    const layerDecay = Math.pow(0.7, level.level);

                    allTags.push({
                        ...t,
                        adjustedWeight: (t.contribution || t.weight || 0) * layerDecay * langPenalty * coreBoost,
                        isCore: isCore
                    });
                    seenTagIds.add(t.id);
                });
            });

            // [4.5] 仿脑认知扩散 (Spike Propagation / Lif-Router)
            // 🔧 重构 V7：动量与残差张力驱动的虫洞跃迁 (Wormhole Routing)
            if (allTags.length > 0 && this.tagCooccurrenceMatrix) {
                const srConfig = config.spikeRouting || {};
                const MAX_SAFE_HOPS = srConfig.maxSafeHops ?? 4;
                const BASE_MOMENTUM = srConfig.baseMomentum ?? 2.0;
                const FIRING_THRESHOLD = srConfig.firingThreshold ?? 0.10;
                const BASE_DECAY = srConfig.baseDecay ?? 0.25;
                const WORMHOLE_DECAY = srConfig.wormholeDecay ?? 0.70;
                const TENSION_THRESHOLD = srConfig.tensionThreshold ?? 1.0;
                const MAX_EMERGENT_NODES = srConfig.maxEmergentNodes ?? 50;
                const MAX_NEIGHBORS_PER_NODE = srConfig.maxNeighborsPerNode ?? 20;

                // 1. 初始注入：带有“动量(TTL)”的脉冲发射器
                let activeSpikes = new Map();      // id -> { energy, momentum }
                const accumulatedEnergy = new Map(); // id -> energySum 全局能量累加器
                
                allTags.forEach(t => {
                    activeSpikes.set(t.id, { energy: t.adjustedWeight, momentum: BASE_MOMENTUM });
                    accumulatedEnergy.set(t.id, t.adjustedWeight);
                });

                // 2. 迭代扩散网络 (基于动量与张力驱动)
                for (let hop = 0; hop < MAX_SAFE_HOPS; hop++) {
                    const nextSpikes = new Map();
                    let propagated = false;

                    for (const [nodeId, spike] of activeSpikes.entries()) {
                        if (spike.energy < FIRING_THRESHOLD || spike.momentum < 0) continue;

                        const synapses = this.tagCooccurrenceMatrix.get(nodeId);
                        if (!synapses) continue;

                        const sortedSynapses = Array.from(synapses.entries())
                            .sort((a, b) => b[1] - a[1])
                            .slice(0, MAX_NEIGHBORS_PER_NODE);

                        for (const [neighborId, coocWeight] of sortedSynapses) {
                            // TagMemo V7: Wormhole Routing
                            // 张力 = 目标节点的残差新颖度 * 边权重
                            const neighborResidual = this.tagIntrinsicResiduals?.get(neighborId) ?? 1.0;
                            const tension = coocWeight * neighborResidual;
                            
                            // 虫洞判定
                            const isWormhole = tension >= TENSION_THRESHOLD;
                            
                            // 能量衰减与动量消耗策略
                            const decayFactor = isWormhole ? WORMHOLE_DECAY : BASE_DECAY;
                            const momentumCost = isWormhole ? 0 : 1.0; // 穿越虫洞豁免动量消耗

                            const injectedCurrent = spike.energy * coocWeight * decayFactor;
                            
                            if (injectedCurrent < 0.01) continue;
                            
                            const nextMomentum = spike.momentum - momentumCost;
                            if (nextMomentum < 0 && !isWormhole) continue; // 动量耗尽且非虫洞，则停止传播

                            // 聚合到达同一节点的脉冲
                            const existing = nextSpikes.get(neighborId);
                            if (existing) {
                                existing.energy += injectedCurrent;
                                existing.momentum = Math.max(existing.momentum, nextMomentum); // 继承最优动量
                            } else {
                                nextSpikes.set(neighborId, { energy: injectedCurrent, momentum: nextMomentum });
                            }
                        }
                    }

                    // 3. 将新一波激发的电流叠加到全局激活总图中
                    for (const [nid, newSpike] of nextSpikes.entries()) {
                        const currentSum = accumulatedEnergy.get(nid) || 0;
                        accumulatedEnergy.set(nid, currentSum + newSpike.energy);
                        if (newSpike.energy > 0.01) propagated = true;
                    }

                    if (!propagated) break;
                    
                    // 下一跳的火种
                    activeSpikes = nextSpikes;
                }

                // 🌟 V8: 缓存距离场（供 geodesicRerank 使用）
                this.lastEnergyField = accumulatedEnergy;

                // 4. 将涌现出来的高电位节点，重新塞回到 allTags
                const allTagsMap = new Map();
                allTags.forEach(t => allTagsMap.set(t.id, t));

                const newAllTags = [];
                const emergentCandidates = [];
                seenTagIds.clear();

                for (const [nid, emergentEnergy] of accumulatedEnergy.entries()) {
                    if (allTagsMap.has(nid)) {
                        // 原始就有这个 Tag (种子节点)
                        const existingTag = allTagsMap.get(nid);
                        // 🌟 小克的精妙细节：取 max，防止种子被双向/循环共现不合理膨胀
                        existingTag.adjustedWeight = Math.max(existingTag.adjustedWeight, emergentEnergy);
                        newAllTags.push(existingTag);
                        seenTagIds.add(nid);
                    } else {
                        // 纯粹因为拓扑传导「涌现」出来的关联节点
                        emergentCandidates.push({
                            id: nid,
                            adjustedWeight: emergentEnergy,
                            isPullback: true // 涌现节点标记
                        });
                    }
                }
                
                // 🔧 涌现节点强截断
                emergentCandidates.sort((a, b) => b.adjustedWeight - a.adjustedWeight);
                const topEmergent = emergentCandidates.slice(0, MAX_EMERGENT_NODES);
                topEmergent.forEach(t => {
                    newAllTags.push(t);
                    seenTagIds.add(t.id);
                });

                if (debug && topEmergent.length > 0) {
                    console.log(`[TagMemo-V7 Spike] Seeds=${allTagsMap.size}, Emergent=${topEmergent.length} (capped from ${emergentCandidates.length}), Total=${newAllTags.length}`);
                }
                
                // 将 allTags 指向经历过脉冲洗礼的完整网络
                allTags.length = 0;
                allTags.push(...newAllTags);
            }

            // [4.6] 核心 Tag 补全 (确保聚光灯不遗漏)
            if (coreTagSet.size > 0) {
                const missingCoreTags = Array.from(coreTagSet).filter(ct =>
                    !allTags.some(at => at.name && at.name.toLowerCase() === ct)
                );

                if (missingCoreTags.length > 0) {
                    try {
                        const placeholders = missingCoreTags.map(() => '?').join(',');
                        const rows = this.db.prepare(`SELECT id, name, vector FROM tags WHERE name IN (${placeholders})`).all(...missingCoreTags);

                        // 获取当前 pyramid 的最大权重作为基准
                        const maxBaseWeight = allTags.length > 0 ? Math.max(...allTags.map(t => t.adjustedWeight / 1.33)) : 1.0;

                        rows.forEach(row => {
                            if (!seenTagIds.has(row.id)) {
                                allTags.push({
                                    id: row.id,
                                    name: row.name,
                                    // 虚拟召回的核心标签使用动态计算的加权因子
                                    adjustedWeight: maxBaseWeight * dynamicCoreBoostFactor,
                                    isCore: true,
                                    isVirtual: true // 标记为非向量召回
                                });
                                seenTagIds.add(row.id);
                            }
                        });
                    } catch (e) {
                        console.warn('[TagMemo-V6] Failed to supplement core tags:', e.message);
                    }
                }
            }

            // [4.7] 🎈 注入幽灵节点 (暗度陈仓)
            let ghostIdCounter = -1; // 专属负数 ID
            const ghostVectorMap = new Map();
            // 获取当前基准权重
            const maxBaseWeight = allTags.length > 0 ? Math.max(...allTags.map(t => t.adjustedWeight / 1.33)) : 1.0;

            const injectGhosts = (ghosts, isCore) => {
                ghosts.forEach(ghost => {
                    const gid = ghostIdCounter--;
                    // 1. 塞进 allTags 参与拓扑运算
                    allTags.push({
                        id: gid,
                        name: ghost.name,
                        adjustedWeight: maxBaseWeight * (isCore ? dynamicCoreBoostFactor : 1.0),
                        isCore: isCore,
                        isVirtual: true
                    });
                    // 2. 存入幽灵字典备用
                    ghostVectorMap.set(gid, {
                        id: gid,
                        name: ghost.name,
                        vector: ghost.vector // Float32Array 本体
                    });
                    seenTagIds.add(gid);
                });
            };

            injectGhosts(hardGhostObjects, true);
            injectGhosts(softGhostObjects, false);

            if (allTags.length === 0) return { vector: originalFloat32, info: null };

            // [5] 批量获取向量与名称（chunked IN，避免 SQLite 参数数量上限）
            const dbTagIds = allTags.filter(t => t.id > 0).map(t => t.id);
            const tagRows = this._queryByChunks('SELECT id, name, vector FROM tags WHERE id', dbTagIds);
            const tagDataMap = new Map(tagRows.map(r => [r.id, r]));

            // 🌟 终极闭环：把幽灵向量混入正规军的 Map 里！
            for (const [gid, ghostData] of ghostVectorMap.entries()) {
                tagDataMap.set(gid, ghostData);
            }

            // [5.5] 语义去重 (Semantic Deduplication)
            // 目的：消除冗余标签（如“委内瑞拉局势”与“委内瑞拉危机”），为多样性腾出空间
            const deduplicatedTags = [];
            const sortedTags = [...allTags].sort((a, b) => b.adjustedWeight - a.adjustedWeight);

            for (const tag of sortedTags) {
                const data = tagDataMap.get(tag.id);
                const vec = data ? this._decodeVectorBlob(data.vector, dim, `tag:${tag.id}`) : null;
                if (!vec) continue;

                let isRedundant = false;

                for (const existing of deduplicatedTags) {
                    const existingData = tagDataMap.get(existing.id);
                    const existingVec = existingData ? this._decodeVectorBlob(existingData.vector, dim, `tag:${existing.id}`) : null;
                    if (!existingVec) continue;

                    // 计算余弦相似度
                    let dot = 0, normA = 0, normB = 0;
                    for (let d = 0; d < dim; d++) {
                        dot += vec[d] * existingVec[d];
                        normA += vec[d] * vec[d];
                        normB += existingVec[d] * existingVec[d];
                    }
                    const similarity = dot / (Math.sqrt(normA) * Math.sqrt(normB));

                    const dedupThreshold = config.deduplicationThreshold ?? 0.88;
                    if (similarity > dedupThreshold) {
                        isRedundant = true;
                        // 权重合并：将冗余标签的部分能量转移给代表性标签，并保留 Core 属性
                        existing.adjustedWeight += tag.adjustedWeight * 0.2;
                        if (tag.isCore) existing.isCore = true;
                        break;
                    }
                }

                if (!isRedundant) {
                    if (!tag.name) tag.name = data.name; // 补全名称
                    deduplicatedTags.push(tag);
                }
            }

            // [6] 构建上下文向量
            const contextVec = new Float32Array(dim);
            let totalWeight = 0;

            for (const t of deduplicatedTags) {
                const data = tagDataMap.get(t.id);
                const v = data ? this._decodeVectorBlob(data.vector, dim, `tag:${t.id}`) : null;
                if (v) {
                    for (let d = 0; d < dim; d++) contextVec[d] += v[d] * t.adjustedWeight;
                    totalWeight += t.adjustedWeight;
                }
            }

            if (totalWeight > 0) {
                // 归一化上下文向量
                let mag = 0;
                for (let d = 0; d < dim; d++) {
                    contextVec[d] /= totalWeight;
                    mag += contextVec[d] * contextVec[d];
                }
                mag = Math.sqrt(mag);
                if (mag > 1e-9) for (let d = 0; d < dim; d++) contextVec[d] /= mag;
            } else {
                return { vector: originalFloat32, info: null };
            }

            // [6] 最终融合 (clamp 防止外推：boost > 1 时原向量会被反向叠加)
            const alpha = Math.min(1.0, effectiveTagBoost);
            const fused = new Float32Array(dim);
            let fusedMag = 0;
            for (let d = 0; d < dim; d++) {
                fused[d] = (1 - alpha) * originalFloat32[d] + alpha * contextVec[d];
                fusedMag += fused[d] * fused[d];
            }

            fusedMag = Math.sqrt(fusedMag);
            if (fusedMag > 1e-9) for (let d = 0; d < dim; d++) fused[d] /= fusedMag;

            return {
                vector: fused,
                info: {
                    // 🌟 标记核心 Tag 召回情况 (安全映射)
                    coreTagsMatched: deduplicatedTags.filter(t => t.isCore && t.name).map(t => t.name),
                    // 仅返回权重足够高的 Tag，过滤掉被压制的噪音，提升召回纯净度
                    matchedTags: (() => {
                        if (deduplicatedTags.length === 0) return [];
                        const maxWeight = Math.max(...deduplicatedTags.map(t => t.adjustedWeight));
                        return deduplicatedTags.filter(t => {
                            // 🌟 核心修正：Core Tags 必须始终包含在 Normal Tags 中，防止排挤效应
                            if (t.isCore) return true;

                            const tName = t.name || '';
                            const isTech = !/[\u4e00-\u9fa5]/.test(tName) && /^[A-Za-z0-9\-_.\s]+$/.test(tName);
                            if (isTech) {
                                // 🌟 软化 TF-IDF 压制：将英文实体的过滤门槛从 0.2 降至 0.08
                                return t.adjustedWeight > maxWeight * (config.techTagThreshold ?? 0.08);
                            }
                            // 🌟 进一步降低门槛：从 0.03 降至 0.015
                            // 理由：Normal 必须是 Core 的超集，且要容纳高频背景主语
                            return t.adjustedWeight > maxWeight * (config.normalTagThreshold ?? 0.015);
                        }).map(t => t.name).filter(Boolean);
                    })(),
                    boostFactor: effectiveTagBoost,
                    epa: { logicDepth, entropy: entropyPenalty, resonance: resonance.resonance },
                    pyramid: { coverage: features.coverage, novelty: features.novelty, depth: features.depth }
                }
            };

        } catch (e) {
            console.error('[TagMemoEngine] TagMemo V6 CRITICAL FAIL:', e);
            return { vector: originalFloat32, info: null };
        }
    }

    /**
     * 获取向量的 EPA 分析数据（逻辑深度、共振等）
     */
    getEPAAnalysis(vector) {
        if (!this.epa || !this.epa.initialized) {
            return { logicDepth: 0.5, resonance: 0, entropy: 0.5, dominantAxes: [] };
        }
        const vec = vector instanceof Float32Array ? vector : new Float32Array(vector);
        const projection = this.epa.project(vec);
        const resonance = this.epa.detectCrossDomainResonance(vec);
        return {
            logicDepth: projection.logicDepth,
            entropy: projection.entropy,
            resonance: resonance.resonance,
            dominantAxes: projection.dominantAxes
        };
    }

    /**
     * 🌟 V8: 测地线重排 (Geodesic Rerank)
     * 复用 Spike Propagation 已计算的 accumulatedEnergy 距离场，
     * 对 KNN 候选 chunk 做基于"地形贴地距离"的二次重排。
     *
     * 三层防御链：
     *   L0: lastEnergyField 为空 → 整体退化（返回原数组）
     *   L1: chunk 的 hitCount < minGeoSamples → 该 chunk 的 geoScore = 0
     *   L2: 所有 chunk 的 maxGeo = 0 → 归一化跳过，全部走纯 KNN
     *
     * @param {Array<{id: BigInt|Number, score: Number}>} candidates - 原始 KNN 搜索结果
     * @param {object} options - 配置项
     * @param {number} [options.alpha=0.3] - 测地线分数混合权重 (0=纯KNN, 1=纯测地线)
     * @param {number} [options.minGeoSamples=4] - 最小采样密度门槛
     * @returns {Array} 重排后的完整数组（不截断）
     */
    geodesicRerank(candidates, options = {}) {
        // L0: 距离场为空 → 整体退化
        if (!this.lastEnergyField || this.lastEnergyField.size === 0) {
            return candidates;
        }
        if (!candidates || candidates.length === 0) {
            return candidates;
        }

        const alpha = Math.max(0, Math.min(1, options.alpha ?? 0.3));
        const minGeoSamples = options.minGeoSamples ?? 4;

        try {
            // Step 1: 批量查询 chunk_id → file_id 映射（chunked IN，避免 SQLite 参数数量上限）
            const chunkIds = candidates.map(c => Number(c.id)).filter(Number.isFinite);
            const chunkFileRows = this._queryByChunks('SELECT id, file_id FROM chunks WHERE id', chunkIds);
            const chunkFileMap = new Map(chunkFileRows.map(r => [r.id, r.file_id]));

            // Step 2: 收集所有需要查询的 file_ids，批量查询 file_id → tag_id[] 映射
            const uniqueFileIds = [...new Set(chunkFileRows.map(r => r.file_id))];
            const fileTagsMap = new Map(); // file_id → [tag_id, ...]

            if (uniqueFileIds.length > 0) {
                const fileTagRows = this._queryByChunks(
                    'SELECT file_id, tag_id FROM file_tags WHERE file_id',
                    uniqueFileIds
                );

                for (const row of fileTagRows) {
                    if (!fileTagsMap.has(row.file_id)) {
                        fileTagsMap.set(row.file_id, []);
                    }
                    fileTagsMap.get(row.file_id).push(row.tag_id);
                }
            }

            // Step 3: 对每个候选计算 geoScore
            const energyField = this.lastEnergyField;
            let maxGeo = 0;
            const geoData = candidates.map(c => {
                const chunkId = Number(c.id);
                const fileId = chunkFileMap.get(chunkId);
                if (fileId === undefined) {
                    return { candidate: c, geoScore: 0, hitCount: 0, totalEnergy: 0 };
                }

                const tagIds = fileTagsMap.get(fileId) || [];
                let totalEnergy = 0;
                let hitCount = 0;

                for (const tid of tagIds) {
                    const energy = energyField.get(tid);
                    if (energy !== undefined) {
                        totalEnergy += energy;
                        hitCount++;
                    }
                }

                // L1: 最小采样密度门槛
                const geoScore = hitCount >= minGeoSamples
                    ? totalEnergy / hitCount
                    : 0; // 密度不足 → 放弃测地线评估，退化为纯 KNN

                if (geoScore > maxGeo) maxGeo = geoScore;

                return { candidate: c, geoScore, hitCount, totalEnergy };
            });

            // L2: 所有 chunk 的 maxGeo = 0 → 归一化跳过，全部走纯 KNN 排序
            if (maxGeo === 0) {
                return candidates;
            }

            // Step 4: 归一化并混合分数
            const reranked = geoData.map(d => {
                const normalizedGeo = d.geoScore / maxGeo; // [0, 1]
                const knnScore = d.candidate.score || 0;
                const finalScore = (1 - alpha) * knnScore + alpha * normalizedGeo;

                return {
                    ...d.candidate,
                    score: finalScore,
                    original_knn_score: knnScore,
                    geo_score: d.geoScore,
                    normalized_geo: normalizedGeo,
                    geo_hit_count: d.hitCount
                };
            });

            // Step 5: 按 finalScore 降序排列（只重排，不截断）
            reranked.sort((a, b) => b.score - a.score);

            console.log(`[TagMemo-V8 Geodesic] α=${alpha}, minSamples=${minGeoSamples}, candidates=${candidates.length}, maxGeo=${maxGeo.toFixed(4)}, reranked=${reranked.filter(r => r.geo_score > 0).length} with geo contribution`);

            return reranked;

        } catch (e) {
            console.error('[TagMemoEngine] geodesicRerank failed, falling back to original order:', e.message);
            return candidates;
        }
    }

    // ============================================================
    // 🌟 TagMemo V8.2-γ: 有序双向势能共现矩阵
    // 三轴解耦：
    //   - 拓扑层 (形): 双向共现 (是否邻接)
    //   - 方向层 (色): 顺逆流阻尼 (叙事方向)
    //   - 语义层 (质): 向量距离阻尼 (semanticGain) + 概念锚 boost (节点残差)
    // 七条工程纪律：
    //   1) 反转守卫 backwardWeight ≤ forwardWeight × 95% (保叙事方向公理)
    //   2) 冷启动阻塞 (在 initialize 中处理)
    //   3) model_sig 含 dimension (在 _computeModelSig 中处理)
    //   4) sim 预计算与矩阵重建共用 _isMatrixRebuilding 锁 (在 doMatrixRebuild 中处理)
    //   5) getSim 未命中 fallback = 0.1 (与噪声阈值 0.05 解耦)
    //   6) Gemini 分布建议先扫描再调 peak (留作运行时 ops 任务)
    //   7) tags.vector 重写时 DELETE 涉及该 tag 的 sim 行 (在 KnowledgeBaseManager 中处理)
    // ============================================================
    buildDirectedCooccurrenceMatrix() {
        console.log('[TagMemoEngine] 🧠 V8.2 Building ORDERED-BIDIRECTIONAL tag co-occurrence matrix (γ)...');
        try {
            // 势能参数
            const PHI_MAX = 0.9;
            const PHI_MIN = 0.5;

            // ---------- V8.2 灰度参数（rag_params.json: orderedCooccurrence） ----------
            const matrixConfig = this.ragParams?.KnowledgeBaseManager?.orderedCooccurrence || {};

            // 顺流：叙事方向 A → B
            const FORWARD_GAIN = matrixConfig.forwardGain ?? 1.0;

            // 逆流：回溯方向 B → A，默认保留但明显阻尼
            const RAW_REVERSE_GAIN = matrixConfig.reverseGain ?? 0.42;
            const MIN_REVERSE_GAIN = matrixConfig.minReverseGain ?? 0.25;
            const MAX_REVERSE_GAIN = matrixConfig.maxReverseGain ?? 0.70;
            const reverseGain = Math.max(
                MIN_REVERSE_GAIN,
                Math.min(MAX_REVERSE_GAIN, RAW_REVERSE_GAIN)
            );

            // Tag 序位距离衰减：相邻 Tag 强，远距离 Tag 弱（默认关闭，灰度逐步开）
            const DISTANCE_DECAY = matrixConfig.distanceDecay ?? 0.0;

            // β: 概念锚逆流增强（基于节点残差）
            // boolean 兼容数值 1/0（前端 UI 用数值表达 toggle）
            const rawAnchorBoost = matrixConfig.reverseAnchorBoost;
            const REVERSE_ANCHOR_BOOST = (rawAnchorBoost === true || rawAnchorBoost === 1)
                || (typeof rawAnchorBoost === 'number' && rawAnchorBoost >= 1);
            const REVERSE_ANCHOR_MAX = matrixConfig.reverseAnchorMax ?? 1.5;

            // γ: 语义增益（基于边向量距离）
            // 同时兼容嵌套对象 (semanticGain.{enabled,peak,sigma,lowSimFallback})
            // 与平铺数值字段 (semanticGainEnabled / semanticGainPeak / semanticGainSigma / semanticGainLowSimFallback)
            // 平铺写法是为了适配 AdminPanel-Vue RagTuning UI 的 nested 单层渲染约束。
            const semGainCfg = matrixConfig.semanticGain || {};
            const rawSemEnabled = semGainCfg.enabled ?? matrixConfig.semanticGainEnabled;
            const SEM_GAIN_ENABLED = (rawSemEnabled === true || rawSemEnabled === 1)
                || (typeof rawSemEnabled === 'number' && rawSemEnabled >= 1);
            const SEM_PEAK = semGainCfg.peak ?? matrixConfig.semanticGainPeak ?? 0.65;
            const SEM_SIGMA = semGainCfg.sigma ?? matrixConfig.semanticGainSigma ?? 0.25;
            const SEM_LOW_FALLBACK = semGainCfg.lowSimFallback ?? matrixConfig.semanticGainLowSimFallback ?? 0.1;

            // 反转守卫：逆流永远不超过顺流的 95%
            const REVERSE_INVERSION_GUARD = matrixConfig.reverseInversionGuard ?? 0.95;

            // ---------- 钟形语义增益 ----------
            // 低 sim 软底（0.40~0.55）+ 中段高斯钟形（peak 黄金区放大）+ 高 sim 抑制
            const semanticGain = (sim) => {
                if (!SEM_GAIN_ENABLED) return 1.0;
                if (!Number.isFinite(sim)) return 1.0;
                if (sim < 0.15) return 0.4 + sim * 1.0; // 软底 0.40 ~ 0.55
                return 0.5 + 0.8 * Math.exp(
                    -((sim - SEM_PEAK) ** 2) / (2 * SEM_SIGMA * SEM_SIGMA)
                );
            };

            // 包装 getSim，未命中走配置化 fallback
            const getSimSafe = (a, b) => {
                if (!SEM_GAIN_ENABLED) return SEM_LOW_FALLBACK;
                const v = this.getSim(a, b);
                return Number.isFinite(v) && v > 0 ? v : SEM_LOW_FALLBACK;
            };

            // ---------- Step 1: 双向共现 ----------
            const stmt = this.db.prepare(`
                SELECT file_id, tag_id, position
                FROM file_tags
                WHERE position > 0
                ORDER BY file_id, position ASC
            `);

            const matrix = new Map();
            let currentFileId = -1;
            let fileTags = [];

            // 可观测性指标
            let forwardEdges = 0;
            let backwardEdges = 0;
            let anchorBoostedEdges = 0;
            let invertedClampedEdges = 0;

            const addEdge = (from, to, weight) => {
                if (!Number.isFinite(weight) || weight <= 0) return false;
                if (!matrix.has(from)) matrix.set(from, new Map());
                const targetMap = matrix.get(from);
                targetMap.set(to, (targetMap.get(to) || 0) + weight);
                return true;
            };

            const processFileGroup = (tags, fid) => {
                const n = tags.length;
                if (n < 2 || n > 100) return; // 性能保护

                for (let i = 0; i < n; i++) {
                    for (let j = i + 1; j < n; j++) {
                        const t1 = tags[i];
                        const t2 = tags[j];

                        // 序位势能：越靠前的 tag 越像叙事源头
                        const phi1 = n > 1
                            ? PHI_MAX - (PHI_MAX - PHI_MIN) * (t1.pos - 1) / (n - 1)
                            : PHI_MAX;
                        const phi2 = n > 1
                            ? PHI_MAX - (PHI_MAX - PHI_MIN) * (t2.pos - 1) / (n - 1)
                            : PHI_MAX;

                        const delta = Math.max(1, t2.pos - t1.pos);

                        // 距离衰减
                        const distanceFactor = DISTANCE_DECAY > 0
                            ? Math.exp(-DISTANCE_DECAY * (delta - 1))
                            : 1.0;

                        const baseWeight = phi1 * phi2 * distanceFactor;

                        // γ: 语义增益（对称项，余弦距离天然对称）
                        const sim = getSimSafe(t1.id, t2.id);
                        const semGain = semanticGain(sim);

                        // 顺流：A → B
                        const forwardWeight = baseWeight * FORWARD_GAIN * semGain;

                        // 逆流：B → A
                        let dynamicReverseGain = reverseGain;

                        // β: 概念锚增强 — 高内生残差的源头 (t1) 更适合作为逆流回溯目标
                        // (B → A 时 A=t1，t1 的残差越大 → t1 越像独立锚点 → 逆流越通畅)
                        if (REVERSE_ANCHOR_BOOST && this.tagIntrinsicResiduals) {
                            const anchorMass = this.tagIntrinsicResiduals.get(t1.id) ?? 1.0;
                            const boost = Math.min(REVERSE_ANCHOR_MAX, anchorMass);
                            if (boost > 1.0) anchorBoostedEdges++;
                            dynamicReverseGain *= boost;
                        }

                        // 安全夹逼
                        dynamicReverseGain = Math.max(
                            MIN_REVERSE_GAIN,
                            Math.min(MAX_REVERSE_GAIN, dynamicReverseGain)
                        );

                        let backwardWeight = baseWeight * dynamicReverseGain * semGain;

                        // 🛡️ 反转守卫：逆流永远不超过顺流 × 95%
                        // 保 V8.2 的根本前提:叙事方向不对称
                        const cap = forwardWeight * REVERSE_INVERSION_GUARD;
                        if (backwardWeight > cap) {
                            backwardWeight = cap;
                            invertedClampedEdges++;
                        }

                        if (addEdge(t1.id, t2.id, forwardWeight)) forwardEdges++;
                        if (addEdge(t2.id, t1.id, backwardWeight)) backwardEdges++;
                    }
                }
            };

            for (const row of stmt.iterate()) {
                if (row.file_id !== currentFileId) {
                    if (fileTags.length > 0) processFileGroup(fileTags, currentFileId);
                    currentFileId = row.file_id;
                    fileTags = [];
                }
                fileTags.push({ id: row.tag_id, pos: row.position });
            }
            if (fileTags.length > 0) processFileGroup(fileTags, currentFileId);

            // ---------- Step 2: 旧数据 (position=0) 回退为无向等权重 ----------
            const legacyStmt = this.db.prepare(`
                SELECT ft1.tag_id as tag1, ft2.tag_id as tag2, COUNT(ft1.file_id) as cnt
                FROM file_tags ft1
                JOIN file_tags ft2
                    ON ft1.file_id = ft2.file_id
                    AND ft1.tag_id < ft2.tag_id
                WHERE ft1.position = 0 OR ft2.position = 0
                GROUP BY ft1.tag_id, ft2.tag_id
            `);

            const LEGACY_PHI = 0.7;
            for (const row of legacyStmt.iterate()) {
                // legacy 数据天然无方向，仍走 sim 调制保持语义一致性
                const sim = getSimSafe(row.tag1, row.tag2);
                const semGain = semanticGain(sim);
                const weight = row.cnt * LEGACY_PHI * LEGACY_PHI * semGain;

                if (addEdge(row.tag1, row.tag2, weight)) forwardEdges++;
                if (addEdge(row.tag2, row.tag1, weight)) backwardEdges++;
            }

            this.tagCooccurrenceMatrix = matrix;

            console.log(
                `[TagMemoEngine] ✅ V8.2 Ordered-bidirectional matrix built. ` +
                `sources=${matrix.size}, forward=${forwardEdges}, backward=${backwardEdges}, ` +
                `anchor_boosted=${anchorBoostedEdges}, inversion_clamped=${invertedClampedEdges}, ` +
                `reverseGain=${reverseGain.toFixed(3)}, distanceDecay=${DISTANCE_DECAY}, ` +
                `semGain=${SEM_GAIN_ENABLED ? `bell(peak=${SEM_PEAK}, σ=${SEM_SIGMA})` : 'disabled'}, ` +
                `anchorBoost=${REVERSE_ANCHOR_BOOST ? `≤${REVERSE_ANCHOR_MAX}x` : 'disabled'}, ` +
                `simCacheSize=${this.tagPairSimilarities.size}`
            );
        } catch (e) {
            console.error('[TagMemoEngine] ❌ Failed to build V8.2 ordered-bidirectional matrix:', e);
            this.tagCooccurrenceMatrix = new Map();
        }
    }

    // 🌟 V8.2-γ: 加载持久化的 Tag 对语义相似度到内存 Map
    // 矩阵构建是热路径，不能每对 pair 查 SQLite。
    loadPairwiseSimilarities() {
        try {
            const rows = this.db.prepare(
                'SELECT tag_a, tag_b, similarity FROM tag_pair_similarity WHERE model_sig = ?'
            ).all(this.modelSig);

            this.tagPairSimilarities = new Map();
            for (const row of rows) {
                this.tagPairSimilarities.set(`${row.tag_a}:${row.tag_b}`, row.similarity);
            }
            console.log(`[TagMemoEngine] ✅ V8.2 Loaded ${this.tagPairSimilarities.size} pairwise similarities (model_sig=${this.modelSig})`);
        } catch (e) {
            console.warn('[TagMemoEngine] ⚠️ V8.2 pairwise similarity table not yet available:', e.message);
            this.tagPairSimilarities = new Map();
        }
    }

    /**
     * 🌟 V8.2-γ: 查询两个 tag 的持久化余弦相似度
     * 约定 a < b，未命中返回 0（由 buildDirectedCooccurrenceMatrix 包装为配置化 fallback）
     */
    getSim(idA, idB) {
        if (idA === idB) return 1.0;
        const [a, b] = idA < idB ? [idA, idB] : [idB, idA];
        const v = this.tagPairSimilarities.get(`${a}:${b}`);
        return Number.isFinite(v) ? v : 0;
    }

    /**
     * 🛡️ V8.2-fix: Rust 任务（独立 SQLite 连接）写入完成后，
     * 强制 better-sqlite3 走一次 wal_checkpoint(TRUNCATE)，把 -wal/-shm 清空。
     *
     * 背景：Rust 端通过 rusqlite 开新连接做 DELETE+INSERT 后 commit，会写到 -wal。
     * JS 端 better-sqlite3 是另一个进程内连接，下次读取时本应通过 -shm 的 mmap
     * frame index 拿到新数据。但在虚拟化/网络文件系统（典型如 Docker Desktop on
     * Windows/macOS 的 bind mount 走 9P/grpc-fuse）上，跨进程 mmap 共享内存
     * 一致性保证不足，会让 JS 端读到"半新半旧"的页视图，进而触发 SQLITE_CORRUPT
     * 这种"幻觉损坏"——整库元数据 / sqlite_master 完好，但特定表 BTree 遍历必崩。
     *
     * TRUNCATE 模式会强制把 WAL 全部回写主库并把 -wal 截断到 0 字节，下一次读
     * 直接走主库的"经典模式"，绕开 mmap 同步路径。
     *
     * 健康环境下代价 ~50-200ms（取决于 WAL 累积量），属于可忽略量级。
     */
    _checkpointAfterRustWrite(tag) {
        try {
            this.db.pragma('wal_checkpoint(TRUNCATE)');
        } catch (e) {
            console.warn(`[TagMemoEngine] ⚠️ wal_checkpoint after ${tag} failed: ${e.message}`);
        }
    }

    /**
     * 🌟 V8.2-γ: 触发 Rust 预计算成对语义相似度
     * - 默认增量模式（跳过已缓存且 model_sig 一致的 pair）
     * - 与 doMatrixRebuild 共用 _isMatrixRebuilding 锁
     */
    async recomputePairwiseSimilarities(opts = {}) {
        const { fullRebuild = false, blocking = false, minSimilarity = 0.05 } = opts;

        if (!this.tagIndex || !this.tagIndex.computePairwiseSimilarities) {
            console.warn('[TagMemoEngine] ⚠️ computePairwiseSimilarities is not available in VexusIndex (Rust binary may need rebuild)');
            return null;
        }

        // 锁串行：避免与矩阵重建撞车产生"嵌合矩阵"
        // blocking=true 用于冷启动场景，由调用方持锁
        if (!blocking && this._isMatrixRebuilding) {
            console.log('[TagMemoEngine] 🛡️ V8.2 sim recompute deferred: matrix rebuild in progress');
            return null;
        }

        console.log(`[TagMemoEngine] ⚡ V8.2 Triggering Rust pairwise similarity precomputation (model_sig=${this.modelSig}, fullRebuild=${fullRebuild})...`);
        try {
            const dbPath = path.join(path.dirname(this.db.name), 'knowledge_base.sqlite');
            const result = await this.tagIndex.computePairwiseSimilarities(
                dbPath,
                this.modelSig,
                minSimilarity,
                fullRebuild
            );
            // 🛡️ V8.2-fix: Rust 用独立连接写完后，强制本连接同步 -wal 视图
            this._checkpointAfterRustWrite('pairwise sim');
            console.log(
                `[TagMemoEngine] ✅ V8.2 Rust pairwise sim done: ` +
                `pairs=${result.pairCount}, computed=${result.computedCount}, ` +
                `skipped=${result.skippedCount}, stored=${result.storedCount}, ` +
                `elapsed=${result.elapsedMs.toFixed(2)}ms`
            );
            return result;
        } catch (e) {
            console.error('[TagMemoEngine] ❌ V8.2 Rust pairwise sim failed:', e.message || e);
            if (e.stack) console.error(e.stack);
            return null;
        }
    }

    // 🌟 TagMemo V7: 加载内生残差
    loadIntrinsicResiduals() {
        try {
            const rows = this.db.prepare(
                'SELECT tag_id, residual_energy FROM tag_intrinsic_residuals'
            ).all();
            
            this.tagIntrinsicResiduals = new Map();
            for (const row of rows) {
                // 归一化到 [0.5, 2.0] 范围，避免极端值
                const clamped = Math.max(0.5, Math.min(2.0, row.residual_energy));
                this.tagIntrinsicResiduals.set(row.tag_id, clamped);
            }
            console.log(`[TagMemoEngine] ✅ Loaded ${this.tagIntrinsicResiduals.size} intrinsic residuals`);
        } catch (e) {
            console.warn('[TagMemoEngine] ⚠️ No intrinsic residuals available:', e.message);
            this.tagIntrinsicResiduals = null;
        }
    }

    // 🌟 TagMemo V7.7: 混合调度器 (阈值门槛 + 滑动窗口防抖)
    scheduleMatrixRebuild(changeCount = 1) {
        if (changeCount <= 0) return; 
        
        this._accumulatedTagChanges += changeCount;
        
        // 动态计算 1% 阈值
        let threshold = 50; 
        try {
            const totalTags = this.db.prepare('SELECT COUNT(*) as count FROM tags').get()?.count || 0;
            threshold = Math.max(10, Math.min(200, Math.floor(totalTags * 0.01)));
        } catch (e) { /* ignore */ }

        // 仅在达到阈值后，才进入防抖逻辑（实现“大变动后的冷静期”）
        if (this._accumulatedTagChanges >= threshold) {
            // 无论如何先清除旧计时器，实现“滑动窗口”防抖
            if (this._matrixRebuildTimer) {
                clearTimeout(this._matrixRebuildTimer);
            }

            // 设定 5 分钟（300,000ms）的冷却防抖
            const COOLING_DELAY = 300000; 
            this._matrixRebuildTimer = setTimeout(() => {
                console.log(`[TagMemoEngine] 📈 Changes reached threshold (${this._accumulatedTagChanges} >= ${threshold}) and quiet period finished. Rebuilding matrix...`);
                this.doMatrixRebuild();
            }, COOLING_DELAY);
            
            if (this._matrixRebuildTimer.unref) this._matrixRebuildTimer.unref();

            // 仅在本轮防抖第一次达到阈值时提示
            if (!this._matrixRebuildScheduleLogged) {
                console.log(`[TagMemoEngine] 🛡️ Threshold reached. Matrix rebuild scheduled after 5min of quiescence.`);
                this._matrixRebuildScheduleLogged = true;
            }
        }
        // 低于阈值时不执行任何操作，不计入倒计时。
    }

    async doMatrixRebuild() {
        if (this._isMatrixRebuilding) {
            console.warn('[TagMemoEngine] Matrix rebuild already running; keeping accumulated changes for next debounce window.');
            if (!this._matrixRebuildTimer && this._accumulatedTagChanges > 0) {
                this._scheduleMatrixRebuildTimer(300000);
            }
            return;
        }

        const changesAtStart = this._accumulatedTagChanges;
        this._accumulatedTagChanges = 0;
        this._matrixRebuildTimer = null;
        this._matrixRebuildScheduleLogged = false;
        this._isMatrixRebuilding = true;

        try {
            // 🌟 V8.2-γ: 先补齐底座，再构建矩阵
            // 顺序：sim 预计算 → 加载 sim Map → 内生残差预计算/加载 → 构建 V8.2 双向矩阵
            await this.recomputePairwiseSimilarities({ blocking: true });
            this.loadPairwiseSimilarities();
            await this.recomputeIntrinsicResiduals();
            this.loadIntrinsicResiduals();
            this.buildDirectedCooccurrenceMatrix();
        } finally {
            this._isMatrixRebuilding = false;
            if (this._accumulatedTagChanges > 0) {
                console.log(`[TagMemoEngine] 🔁 ${this._accumulatedTagChanges} tag changes arrived during rebuild; scheduling follow-up debounce.`);
                this._scheduleMatrixRebuildTimer(300000);
            }
            console.log(`[TagMemoEngine] Matrix rebuild finished for ${changesAtStart} accumulated tag change(s).`);
        }
    }

    _scheduleMatrixRebuildTimer(delayMs) {
        if (this._matrixRebuildTimer) {
            clearTimeout(this._matrixRebuildTimer);
        }

        this._matrixRebuildScheduleLogged = true;
        this._matrixRebuildTimer = setTimeout(() => {
            console.log(`[TagMemoEngine] 📈 Follow-up quiet period finished. Rebuilding matrix for ${this._accumulatedTagChanges} accumulated change(s)...`);
            this.doMatrixRebuild();
        }, delayMs);

        if (this._matrixRebuildTimer.unref) this._matrixRebuildTimer.unref();
    }

    // 🌟 TagMemo V7: 触发 Rust 预计算内生残差
    async recomputeIntrinsicResiduals() {
        if (!this.tagIndex || !this.tagIndex.computeIntrinsicResiduals) {
            console.warn('[TagMemoEngine] computeIntrinsicResiduals is not available in VexusIndex');
            return;
        }
        
        console.log('[TagMemoEngine] ⚡ Triggering Rust intrinsic residual precomputation...');
        try {
            const dbPath = path.join(path.dirname(this.db.name), 'knowledge_base.sqlite');
            const result = await this.tagIndex.computeIntrinsicResiduals(dbPath);
            // 🛡️ V8.2-fix: Rust 用独立连接写完后，强制本连接同步 -wal 视图
            // 否则在 Docker bind mount 等虚拟文件系统上会读到不一致的页视图（SQLITE_CORRUPT 幻觉）
            this._checkpointAfterRustWrite('intrinsic residuals');
            console.log(`[TagMemoEngine] ✅ Rust precomputation complete: ${result.computedCount} computed, ${result.skippedCount} skipped in ${result.elapsedMs.toFixed(2)}ms`);
            
            // 重新加载结果
            this.loadIntrinsicResiduals();
        } catch (e) {
            console.error('[TagMemoEngine] ❌ Rust precomputation failed:', e.message || e);
            if (e.stack) console.error(e.stack);
        }
    }
}

module.exports = TagMemoEngine;