noteconnection 1.7.0 → 1.9.0

package/dist/src/learning/queryBackend.js

@@ -0,0 +1,1922 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalVectorGraphQueryBackend = exports.KeywordOnlyGraphQueryBackend = exports.LocalHybridGraphQueryBackend = void 0;
+exports.evaluateAnnRunbookHealth = evaluateAnnRunbookHealth;
+exports.normalizeGraphQueryBackendType = normalizeGraphQueryBackendType;
+exports.normalizeLocalVectorAccelerationFailureMode = normalizeLocalVectorAccelerationFailureMode;
+exports.createGraphQueryBackend = createGraphQueryBackend;
+exports.listGraphQueryBackendCatalog = listGraphQueryBackendCatalog;
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const graphClaimMatcher_1 = require("./graphClaimMatcher");
+function evaluateAnnRunbookHealth(params) {
+    const checks = [];
+    const threshold = params.failureThreshold ?? 3;
+    const minEffectiveness = params.minPrefilterEffectivenessRatio ?? 0.01;
+    // Check 1: Circuit state
+    const circuitHealthy = params.circuitState !== 'open';
+    checks.push({
+        name: 'circuit_state',
+        passed: circuitHealthy,
+        value: params.circuitState ?? 'unknown',
+        threshold: 'closed',
+        operator: 'eq',
+        message: circuitHealthy ? 'Circuit closed' : 'Circuit open — requests blocked',
+    });
+    // Check 2: Consecutive failures
+    const failuresHealthy = (params.consecutiveFailures ?? 0) < threshold;
+    checks.push({
+        name: 'consecutive_failures',
+        passed: failuresHealthy,
+        value: params.consecutiveFailures ?? 0,
+        threshold,
+        operator: 'lt',
+        message: failuresHealthy ? 'Within threshold' : `Exceeded threshold (${params.consecutiveFailures} >= ${threshold})`,
+    });
+    // Check 3: Prefilter effectiveness
+    const effectiveness = params.prefilterEffectivenessRatio ?? 1;
+    const prefilterHealthy = effectiveness >= minEffectiveness;
+    checks.push({
+        name: 'prefilter_effectiveness',
+        passed: prefilterHealthy,
+        value: effectiveness,
+        threshold: minEffectiveness,
+        operator: 'gte',
+        message: prefilterHealthy ? 'Effective prefilter' : 'Prefilter too narrow — may miss relevant atoms',
+    });
+    // Check 4: Representation consistency
+    const repHealthy = params.representationStatus !== 'mismatch';
+    checks.push({
+        name: 'representation_consistency',
+        passed: repHealthy || !params.representationStrictMode,
+        value: params.representationStatus ?? 'unknown',
+        threshold: 'aligned',
+        operator: 'eq',
+        message: repHealthy ? 'Aligned' : `Mismatch: ${params.representationStatus}`,
+    });
+    const failed = checks.filter(c => !c.passed);
+    const status = failed.length === 0 ? 'healthy'
+        : failed.length <= 1 && checks[0].passed ? 'degraded'
+            : 'unhealthy';
+    return {
+        status,
+        checks,
+        summary: failed.length === 0
+            ? 'All ANN health checks passed.'
+            : `${failed.length}/${checks.length} checks failed: ${failed.map(c => c.name).join(', ')}.`,
+        checkedAt: new Date().toISOString(),
+    };
+}
+const GRAPH_QUERY_BACKEND_CATALOG = [
+    {
+        backend: 'local_hybrid',
+        backendId: 'local-hybrid-v1',
+        label: 'Local Hybrid',
+        aliases: ['local_hybrid', 'local-hybrid', 'hybrid'],
+    },
+    {
+        backend: 'keyword_only',
+        backendId: 'keyword-only-v1',
+        label: 'Keyword Only',
+        aliases: ['keyword_only', 'keyword-only', 'keyword'],
+    },
+    {
+        backend: 'local_vector',
+        backendId: 'local-vector-v1',
+        label: 'Local Vector',
+        aliases: ['local_vector', 'local-vector', 'vector', 'semantic_vector', 'semantic-vector'],
+    },
+];
+const SEMANTIC_CONTENT_TOKEN_LIMIT = 180;
+const SEMANTIC_TITLE_TOKEN_LIMIT = 24;
+const SEMANTIC_KEYWORD_TOKEN_LIMIT = 40;
+const SEMANTIC_QUERY_TOKEN_LIMIT = 48;
+const SEMANTIC_CJK_NGRAM_LIMIT = 96;
+const LOCAL_VECTOR_INDEX_SCHEMA_VERSION = 2;
+const LOCAL_VECTOR_INDEX_BACKEND_ID = 'local-vector-v1';
+const LOCAL_VECTOR_INDEX_SIGNATURE_VERSION = 'local-vector-index-signature-v2';
+const LOCAL_VECTOR_ACCELERATION_ADAPTER_ID = 'local-vector-acceleration-ann-v1';
+const LOCAL_VECTOR_REPRESENTATION_VERSION = 'local-vector-representation-v2';
+const LOCAL_VECTOR_EMBEDDING_MODEL_ID = 'local-semantic-tfidf-unicode-v2';
+const LOCAL_VECTOR_ANN_MIN_ATOMS = 96;
+const LOCAL_VECTOR_ANN_TOP_QUERY_TOKENS = 8;
+const LOCAL_VECTOR_ANN_CANDIDATE_MULTIPLIER = 28;
+const LOCAL_VECTOR_ANN_CANDIDATE_MIN_FLOOR = 48;
+const LOCAL_VECTOR_ANN_SIGNATURE_PREFIX_BITS = 14;
+const LOCAL_VECTOR_ANN_SIGNATURE_SCORE_BONUS = 0.08;
+const LOCAL_VECTOR_ANN_HASH_CACHE_SOFT_LIMIT = 50000;
+const LOCAL_VECTOR_TOKEN_HASH_CACHE = new Map();
+function clamp(value, minValue, maxValue) {
+    return Math.min(maxValue, Math.max(minValue, value));
+}
+function normalizeSemanticToken(rawValue) {
+    return String(rawValue || '')
+        .trim()
+        .toLowerCase()
+        .normalize('NFKC')
+        .replace(/[^\p{L}\p{N}]+/gu, '');
+}
+function stemSemanticToken(rawValue) {
+    const token = normalizeSemanticToken(rawValue);
+    if (!token) {
+        return '';
+    }
+    if (!/^[a-z0-9]+$/.test(token)) {
+        return token;
+    }
+    if (token.endsWith('ies') && token.length > 4) {
+        return `${token.slice(0, -3)}y`;
+    }
+    if (token.endsWith('ing') && token.length > 5) {
+        return token.slice(0, -3);
+    }
+    if (token.endsWith('ed') && token.length > 4) {
+        return token.slice(0, -2);
+    }
+    if (token.endsWith('es') && token.length > 4 && !token.endsWith('ses')) {
+        return token.slice(0, -2);
+    }
+    if (token.endsWith('s')
+        && token.length > 3
+        && !token.endsWith('ss')
+        && !token.endsWith('is')
+        && !token.endsWith('us')) {
+        return token.slice(0, -1);
+    }
+    return token;
+}
+function buildCjkSemanticNgrams(rawText, limit) {
+    if (limit <= 0) {
+        return [];
+    }
+    const segments = String(rawText || '')
+        .normalize('NFKC')
+        .match(/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]+/gu) || [];
+    const tokens = [];
+    const seen = new Set();
+    for (const segment of segments) {
+        const chars = Array.from(segment);
+        if (chars.length === 1) {
+            const token = chars[0];
+            if (!seen.has(token)) {
+                seen.add(token);
+                tokens.push(token);
+            }
+            continue;
+        }
+        for (const gramSize of [2, 3]) {
+            if (chars.length < gramSize) {
+                continue;
+            }
+            for (let index = 0; index <= chars.length - gramSize; index += 1) {
+                const token = chars.slice(index, index + gramSize).join('');
+                if (!token || seen.has(token)) {
+                    continue;
+                }
+                seen.add(token);
+                tokens.push(token);
+                if (tokens.length >= limit) {
+                    return tokens;
+                }
+            }
+        }
+    }
+    return tokens;
+}
+function extractSemanticTokens(rawText, limit) {
+    if (limit <= 0) {
+        return [];
+    }
+    const tokens = String(rawText || '')
+        .normalize('NFKC')
+        .toLowerCase()
+        .match(/[\p{L}\p{N}]+(?:[_-][\p{L}\p{N}]+)*/gu) || [];
+    const collected = [];
+    const seen = new Set();
+    for (const token of tokens) {
+        const normalized = stemSemanticToken(token);
+        if (!normalized || seen.has(normalized)) {
+            continue;
+        }
+        seen.add(normalized);
+        collected.push(normalized);
+        if (collected.length >= limit) {
+            break;
+        }
+    }
+    if (collected.length >= limit) {
+        return collected;
+    }
+    const cjkTokens = buildCjkSemanticNgrams(rawText, Math.min(limit - collected.length, SEMANTIC_CJK_NGRAM_LIMIT));
+    for (const token of cjkTokens) {
+        if (!token || seen.has(token)) {
+            continue;
+        }
+        seen.add(token);
+        collected.push(token);
+        if (collected.length >= limit) {
+            break;
+        }
+    }
+    return collected;
+}
+function uniqueTokens(tokens) {
+    const unique = [];
+    const seen = new Set();
+    tokens.forEach((token) => {
+        if (!token || seen.has(token)) {
+            return;
+        }
+        seen.add(token);
+        unique.push(token);
+    });
+    return unique;
+}
+function uniqueNormalizedStrings(values) {
+    const unique = [];
+    const seen = new Set();
+    values.forEach((value) => {
+        const normalized = String(value || '')
+            .normalize('NFKC')
+            .toLowerCase()
+            .replace(/\s+/g, ' ')
+            .trim();
+        if (!normalized || seen.has(normalized)) {
+            return;
+        }
+        seen.add(normalized);
+        unique.push(normalized);
+    });
+    return unique;
+}
+function buildQueryTextVariants(context) {
+    return uniqueNormalizedStrings([
+        context.query,
+        ...(Array.isArray(context.queryVariants) ? context.queryVariants : []),
+    ]);
+}
+function buildAtomSemanticTokens(atom) {
+    const keywordTokens = uniqueTokens((atom.keywords || [])
+        .map((keyword) => stemSemanticToken(keyword))
+        .filter((token) => token.length > 0)
+        .slice(0, SEMANTIC_KEYWORD_TOKEN_LIMIT));
+    const titleTokens = extractSemanticTokens(atom.title, SEMANTIC_TITLE_TOKEN_LIMIT);
+    const contentTokens = extractSemanticTokens(atom.content, SEMANTIC_CONTENT_TOKEN_LIMIT);
+    const conceptTokens = (0, graphClaimMatcher_1.semanticFeatures)(`${atom.title} ${atom.content}`)
+        .filter((feature) => feature.startsWith('concept:'));
+    return uniqueTokens([...keywordTokens, ...titleTokens, ...contentTokens, ...conceptTokens]);
+}
+function buildQuerySemanticTokens(context) {
+    const directTokens = uniqueTokens((context.queryTokens || [])
+        .map((token) => stemSemanticToken(token))
+        .filter((token) => token.length > 0));
+    const variantTokens = buildQueryTextVariants(context).flatMap((variant) => (extractSemanticTokens(variant, SEMANTIC_QUERY_TOKEN_LIMIT)));
+    const fallbackTokens = extractSemanticTokens(context.query, SEMANTIC_QUERY_TOKEN_LIMIT);
+    const conceptTokens = (0, graphClaimMatcher_1.semanticFeatures)(buildQueryTextVariants(context).join(' '))
+        .filter((feature) => feature.startsWith('concept:'));
+    return uniqueTokens([...directTokens, ...variantTokens, ...fallbackTokens, ...conceptTokens]).slice(0, SEMANTIC_QUERY_TOKEN_LIMIT);
+}
+function computeJaccard(left, right) {
+    if (!left.length || !right.length) {
+        return 0;
+    }
+    const leftSet = new Set(left);
+    const rightSet = new Set(right);
+    let intersection = 0;
+    leftSet.forEach((token) => {
+        if (rightSet.has(token)) {
+            intersection += 1;
+        }
+    });
+    const union = leftSet.size + rightSet.size - intersection;
+    if (union <= 0) {
+        return 0;
+    }
+    return intersection / union;
+}
+function classifyGraphQueryIntent(query) {
+    const normalized = String(query || '').trim().toLowerCase();
+    if (!normalized) {
+        return 'generic';
+    }
+    if (normalized.includes('compare')
+        || normalized.includes('difference')
+        || normalized.includes('vs')
+        || normalized.includes('对比')
+        || normalized.includes('比较')
+        || normalized.includes('区别')
+        || normalized.includes('差异')) {
+        return 'compare';
+    }
+    if (normalized.includes('how to')
+        || normalized.includes('how do')
+        || normalized.includes('steps')
+        || normalized.includes('plan')
+        || normalized.includes('如何')
+        || normalized.includes('怎么')
+        || normalized.includes('步骤')
+        || normalized.includes('方案')) {
+        return 'how_to';
+    }
+    if (normalized.includes('what is')
+        || normalized.includes('why')
+        || normalized.includes('explain')
+        || normalized.includes('什么是')
+        || normalized.includes('为什么')
+        || normalized.includes('解释')) {
+        return 'explain';
+    }
+    return 'generic';
+}
+function buildAtomAnchorTokens(atom) {
+    return uniqueTokens([
+        ...extractSemanticTokens(atom.title, Math.max(SEMANTIC_TITLE_TOKEN_LIMIT, 10)),
+        ...extractSemanticTokens(atom.sourcePath, 10),
+        ...extractSemanticTokens(atom.documentId, 6),
+    ]);
+}
+function inferGraphAnchorAtomIds(context, querySemanticTokens) {
+    const queryVariants = buildQueryTextVariants(context);
+    const rankedAnchors = context.atoms
+        .map((atom, index) => {
+        const titleLower = String(atom.title || '').trim().toLowerCase();
+        const directMatchScore = titleLower && queryVariants.some((variant) => variant.includes(titleLower))
+            ? 1
+            : 0;
+        const anchorTokenOverlap = computeJaccard(querySemanticTokens, buildAtomAnchorTokens(atom));
+        const keywordOverlap = computeJaccard(querySemanticTokens, uniqueTokens((atom.keywords || []).map((keyword) => stemSemanticToken(keyword)).filter(Boolean)));
+        const score = Number((directMatchScore
+            + anchorTokenOverlap
+            + (keywordOverlap * 0.35)).toFixed(6));
+        return {
+            atomId: atom.id,
+            score,
+            index,
+        };
+    })
+        .filter((entry) => entry.score > 0)
+        .sort((left, right) => (right.score - left.score
+        || left.index - right.index));
+    if (rankedAnchors.length <= 0) {
+        return new Set();
+    }
+    const topScore = rankedAnchors[0].score;
+    return new Set(rankedAnchors
+        .filter((entry, index) => index < 3 && entry.score >= Math.max(0.2, topScore - 0.08))
+        .map((entry) => entry.atomId));
+}
+function buildGraphAdjacency(activeEdges) {
+    const outgoingByAtomId = new Map();
+    const incomingByAtomId = new Map();
+    const undirectedNeighborsByAtomId = new Map();
+    const degreeByAtomId = new Map();
+    const incidentRelationKindsByAtomId = new Map();
+    activeEdges.forEach((edge) => {
+        const confidence = clamp(Number(edge.confidence || 0), 0, 1);
+        const outgoing = outgoingByAtomId.get(edge.sourceAtomId) || [];
+        outgoing.push({
+            to: edge.targetAtomId,
+            relationKind: edge.relationKind,
+            confidence,
+        });
+        outgoingByAtomId.set(edge.sourceAtomId, outgoing);
+        const incoming = incomingByAtomId.get(edge.targetAtomId) || [];
+        incoming.push({
+            to: edge.sourceAtomId,
+            relationKind: edge.relationKind,
+            confidence,
+        });
+        incomingByAtomId.set(edge.targetAtomId, incoming);
+        const sourceUndirected = undirectedNeighborsByAtomId.get(edge.sourceAtomId) || [];
+        sourceUndirected.push(edge.targetAtomId);
+        undirectedNeighborsByAtomId.set(edge.sourceAtomId, sourceUndirected);
+        const targetUndirected = undirectedNeighborsByAtomId.get(edge.targetAtomId) || [];
+        targetUndirected.push(edge.sourceAtomId);
+        undirectedNeighborsByAtomId.set(edge.targetAtomId, targetUndirected);
+        degreeByAtomId.set(edge.sourceAtomId, (degreeByAtomId.get(edge.sourceAtomId) || 0) + 1);
+        degreeByAtomId.set(edge.targetAtomId, (degreeByAtomId.get(edge.targetAtomId) || 0) + 1);
+        const sourceKinds = incidentRelationKindsByAtomId.get(edge.sourceAtomId) || new Set();
+        sourceKinds.add(edge.relationKind);
+        incidentRelationKindsByAtomId.set(edge.sourceAtomId, sourceKinds);
+        const targetKinds = incidentRelationKindsByAtomId.get(edge.targetAtomId) || new Set();
+        targetKinds.add(edge.relationKind);
+        incidentRelationKindsByAtomId.set(edge.targetAtomId, targetKinds);
+    });
+    return {
+        outgoingByAtomId,
+        incomingByAtomId,
+        undirectedNeighborsByAtomId,
+        degreeByAtomId,
+        incidentRelationKindsByAtomId,
+    };
+}
+function buildUndirectedDistanceSignals(anchorAtomIds, undirectedNeighborsByAtomId, maxDepth) {
+    const distances = new Map();
+    const queue = [];
+    anchorAtomIds.forEach((anchorAtomId) => {
+        distances.set(anchorAtomId, 0);
+        queue.push({ atomId: anchorAtomId, distance: 0 });
+    });
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            continue;
+        }
+        if (current.distance >= maxDepth) {
+            continue;
+        }
+        const neighbors = undirectedNeighborsByAtomId.get(current.atomId) || [];
+        neighbors.forEach((neighborAtomId) => {
+            const nextDistance = current.distance + 1;
+            const existingDistance = distances.get(neighborAtomId);
+            if (typeof existingDistance === 'number' && existingDistance <= nextDistance) {
+                return;
+            }
+            distances.set(neighborAtomId, nextDistance);
+            queue.push({
+                atomId: neighborAtomId,
+                distance: nextDistance,
+            });
+        });
+    }
+    return distances;
+}
+function shouldReplaceDirectedPathSignal(current, next) {
+    if (!current) {
+        return true;
+    }
+    if (next.distance < current.distance) {
+        return true;
+    }
+    return next.distance === current.distance && next.averageConfidence > current.averageConfidence;
+}
+function buildDirectedPathSignals(anchorAtomIds, adjacencyByAtomId, maxDepth) {
+    const signals = new Map();
+    const queue = [];
+    anchorAtomIds.forEach((anchorAtomId) => {
+        signals.set(anchorAtomId, {
+            distance: 0,
+            averageConfidence: 1,
+            relationKinds: [],
+        });
+        queue.push({
+            atomId: anchorAtomId,
+            distance: 0,
+            confidenceSum: 0,
+            relationKinds: [],
+        });
+    });
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            continue;
+        }
+        if (current.distance >= maxDepth) {
+            continue;
+        }
+        const neighbors = adjacencyByAtomId.get(current.atomId) || [];
+        neighbors.forEach((neighbor) => {
+            const nextDistance = current.distance + 1;
+            const nextConfidenceSum = current.confidenceSum + clamp(Number(neighbor.confidence || 0), 0, 1);
+            const nextSignal = {
+                distance: nextDistance,
+                averageConfidence: Number((nextConfidenceSum / nextDistance).toFixed(4)),
+                relationKinds: current.relationKinds.includes(neighbor.relationKind)
+                    ? current.relationKinds
+                    : [...current.relationKinds, neighbor.relationKind],
+            };
+            const currentSignal = signals.get(neighbor.to);
+            if (!shouldReplaceDirectedPathSignal(currentSignal, nextSignal)) {
+                return;
+            }
+            signals.set(neighbor.to, nextSignal);
+            queue.push({
+                atomId: neighbor.to,
+                distance: nextDistance,
+                confidenceSum: nextConfidenceSum,
+                relationKinds: nextSignal.relationKinds,
+            });
+        });
+    }
+    return signals;
+}
+function buildGraphFeatureIndex(context, querySemanticTokens) {
+    const queryIntent = classifyGraphQueryIntent(context.query);
+    const anchorAtomIds = inferGraphAnchorAtomIds(context, querySemanticTokens);
+    const { outgoingByAtomId, incomingByAtomId, undirectedNeighborsByAtomId, degreeByAtomId, incidentRelationKindsByAtomId, } = buildGraphAdjacency(context.activeEdges);
+    const maxDegree = Array.from(degreeByAtomId.values()).reduce((maxValue, degree) => Math.max(maxValue, degree), 0);
+    return {
+        queryIntent,
+        anchorAtomIds,
+        degreeByAtomId,
+        maxDegree,
+        incidentRelationKindsByAtomId,
+        undirectedDistanceByAtomId: buildUndirectedDistanceSignals(anchorAtomIds, undirectedNeighborsByAtomId, 4),
+        pathToAnchorByAtomId: buildDirectedPathSignals(anchorAtomIds, incomingByAtomId, 4),
+        pathFromAnchorByAtomId: buildDirectedPathSignals(anchorAtomIds, outgoingByAtomId, 4),
+    };
+}
+function computeAnchorDistanceBonus(atomId, graphFeatureIndex) {
+    const distance = graphFeatureIndex.undirectedDistanceByAtomId.get(atomId);
+    if (typeof distance !== 'number') {
+        return 0;
+    }
+    if (distance <= 0) {
+        return graphFeatureIndex.queryIntent === 'compare' ? 0.22 : 0.3;
+    }
+    if (distance === 1) {
+        return 0.18;
+    }
+    if (distance === 2) {
+        return 0.1;
+    }
+    if (distance === 3) {
+        return 0.05;
+    }
+    return 0;
+}
+function computeDirectedPathBonus(signal, intent, direction) {
+    if (!signal || signal.distance <= 0) {
+        return 0;
+    }
+    const baseBonus = signal.distance === 1
+        ? 0.14
+        : signal.distance === 2
+            ? 0.09
+            : 0.05;
+    const confidenceBonus = clamp(signal.averageConfidence, 0, 1) * 0.12;
+    let relationBonus = 0;
+    if (signal.relationKinds.includes('prerequisite') && direction === 'to_anchor' && intent !== 'compare') {
+        relationBonus += intent === 'how_to' ? 0.12 : 0.07;
+    }
+    if (signal.relationKinds.includes('sequence') && direction === 'from_anchor' && intent === 'how_to') {
+        relationBonus += 0.08;
+    }
+    if (signal.relationKinds.includes('application') && direction === 'from_anchor' && intent === 'how_to') {
+        relationBonus += 0.06;
+    }
+    const compareBranchSignalPresent = signal.relationKinds.includes('contrast') || signal.relationKinds.includes('analogy');
+    if (compareBranchSignalPresent && intent === 'compare') {
+        relationBonus += signal.distance === 1 ? 0.32 : 0.18;
+    }
+    const maxBonus = compareBranchSignalPresent && intent === 'compare' ? 0.6 : 0.4;
+    return Number(clamp(baseBonus + confidenceBonus + relationBonus, 0, maxBonus).toFixed(6));
+}
+function computeRelationIntentBonus(atomId, graphFeatureIndex) {
+    const relationKinds = graphFeatureIndex.incidentRelationKindsByAtomId.get(atomId);
+    if (!relationKinds || relationKinds.size <= 0) {
+        return 0;
+    }
+    let bonus = 0;
+    if (graphFeatureIndex.queryIntent === 'compare') {
+        if (relationKinds.has('contrast'))
+            bonus += 0.24;
+        if (relationKinds.has('analogy'))
+            bonus += 0.16;
+        if (relationKinds.has('reference'))
+            bonus += 0.02;
+    }
+    else if (graphFeatureIndex.queryIntent === 'how_to') {
+        if (relationKinds.has('prerequisite'))
+            bonus += 0.1;
+        if (relationKinds.has('sequence'))
+            bonus += 0.08;
+        if (relationKinds.has('application'))
+            bonus += 0.08;
+        if (relationKinds.has('causal'))
+            bonus += 0.04;
+    }
+    else if (graphFeatureIndex.queryIntent === 'explain') {
+        if (relationKinds.has('causal'))
+            bonus += 0.1;
+        if (relationKinds.has('reference'))
+            bonus += 0.06;
+        if (relationKinds.has('prerequisite'))
+            bonus += 0.05;
+    }
+    else {
+        if (relationKinds.has('reference'))
+            bonus += 0.04;
+        if (relationKinds.has('causal'))
+            bonus += 0.04;
+    }
+    return Number(clamp(bonus, 0, 0.18).toFixed(6));
+}
+function computeTemporalValidityBonus(context, atomId) {
+    const temporalSignal = context.atomTemporalValidity && typeof context.atomTemporalValidity === 'object'
+        ? context.atomTemporalValidity[atomId]
+        : undefined;
+    if (!temporalSignal) {
+        return 0;
+    }
+    if (temporalSignal.isValid === false) {
+        return -Number((0.18 + Math.min(temporalSignal.reasonCount, 3) * 0.02).toFixed(6));
+    }
+    return 0;
+}
+function computeCompareBranchBonus(atomId, graphFeatureIndex) {
+    if (graphFeatureIndex.queryIntent !== 'compare') {
+        return 0;
+    }
+    const toAnchorSignal = graphFeatureIndex.pathToAnchorByAtomId.get(atomId);
+    const fromAnchorSignal = graphFeatureIndex.pathFromAnchorByAtomId.get(atomId);
+    const directContrastToAnchor = Boolean(toAnchorSignal
+        && toAnchorSignal.distance === 1
+        && (toAnchorSignal.relationKinds.includes('contrast') || toAnchorSignal.relationKinds.includes('analogy')));
+    const directContrastFromAnchor = Boolean(fromAnchorSignal
+        && fromAnchorSignal.distance === 1
+        && (fromAnchorSignal.relationKinds.includes('contrast') || fromAnchorSignal.relationKinds.includes('analogy')));
+    if (directContrastToAnchor || directContrastFromAnchor) {
+        return 0.24;
+    }
+    return 0;
+}
+function computeHubPenalty(atomId, graphFeatureIndex) {
+    if (graphFeatureIndex.maxDegree <= 0) {
+        return 0;
+    }
+    if (graphFeatureIndex.undirectedDistanceByAtomId.has(atomId)) {
+        return 0;
+    }
+    const degree = graphFeatureIndex.degreeByAtomId.get(atomId) || 0;
+    const normalizedDegree = degree / graphFeatureIndex.maxDegree;
+    if (normalizedDegree <= 0.7) {
+        return 0;
+    }
+    return Number(clamp((normalizedDegree - 0.7) * 0.25, 0, 0.12).toFixed(6));
+}
+function computeGraphFeatureScore(context, atomId, graphFeatureIndex) {
+    if (graphFeatureIndex.anchorAtomIds.size <= 0) {
+        return 0;
+    }
+    const anchorDistanceBonus = computeAnchorDistanceBonus(atomId, graphFeatureIndex);
+    const pathToAnchorBonus = computeDirectedPathBonus(graphFeatureIndex.pathToAnchorByAtomId.get(atomId), graphFeatureIndex.queryIntent, 'to_anchor');
+    const pathFromAnchorBonus = computeDirectedPathBonus(graphFeatureIndex.pathFromAnchorByAtomId.get(atomId), graphFeatureIndex.queryIntent, 'from_anchor');
+    const relationIntentBonus = computeRelationIntentBonus(atomId, graphFeatureIndex);
+    const temporalValidityBonus = computeTemporalValidityBonus(context, atomId);
+    const compareBranchBonus = computeCompareBranchBonus(atomId, graphFeatureIndex);
+    const hubPenalty = computeHubPenalty(atomId, graphFeatureIndex);
+    return Number((anchorDistanceBonus
+        + pathToAnchorBonus
+        + pathFromAnchorBonus
+        + relationIntentBonus
+        + temporalValidityBonus
+        + compareBranchBonus
+        - hubPenalty).toFixed(6));
+}
+function buildTokenFrequency(tokens) {
+    const frequency = new Map();
+    tokens.forEach((token) => {
+        if (!token) {
+            return;
+        }
+        frequency.set(token, (frequency.get(token) || 0) + 1);
+    });
+    return frequency;
+}
+function buildTfIdfWeights(frequency, docFrequency, totalDocs) {
+    const weights = new Map();
+    const maxTermCount = Math.max(1, ...Array.from(frequency.values()).map((value) => Math.max(0, Math.floor(Number(value) || 0))));
+    frequency.forEach((count, token) => {
+        const tf = Math.max(0, Math.floor(Number(count) || 0)) / maxTermCount;
+        const df = Math.max(1, Math.floor(Number(docFrequency.get(token) || 0)));
+        const idf = Math.log((1 + totalDocs) / (1 + df)) + 1;
+        weights.set(token, Number((tf * idf).toFixed(8)));
+    });
+    return weights;
+}
+function computeCosineSimilarity(left, right) {
+    if (left.size <= 0 || right.size <= 0) {
+        return 0;
+    }
+    let dot = 0;
+    let leftNorm = 0;
+    let rightNorm = 0;
+    left.forEach((weight, token) => {
+        const rightWeight = right.get(token) || 0;
+        dot += weight * rightWeight;
+        leftNorm += weight * weight;
+    });
+    right.forEach((weight) => {
+        rightNorm += weight * weight;
+    });
+    const denominator = Math.sqrt(leftNorm) * Math.sqrt(rightNorm);
+    if (!Number.isFinite(denominator) || denominator <= 0) {
+        return 0;
+    }
+    return dot / denominator;
+}
+function normalizeVectorIndexPath(rawValue) {
+    const trimmed = String(rawValue || '').trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    return path.resolve(trimmed);
+}
+function toSerializableWeightEntries(weights) {
+    const entries = [];
+    weights.forEach((weight, token) => {
+        if (!token) {
+            return;
+        }
+        const numericWeight = Number(weight);
+        if (!Number.isFinite(numericWeight) || numericWeight <= 0) {
+            return;
+        }
+        entries.push([token, Number(numericWeight.toFixed(8))]);
+    });
+    entries.sort((left, right) => left[0].localeCompare(right[0]));
+    return entries;
+}
+function toWeightMap(entries) {
+    const weightMap = new Map();
+    if (!Array.isArray(entries)) {
+        return weightMap;
+    }
+    entries.forEach((entry) => {
+        if (!Array.isArray(entry) || entry.length < 2) {
+            return;
+        }
+        const token = String(entry[0] || '').trim().toLowerCase();
+        const weight = Number(entry[1]);
+        if (!token || !Number.isFinite(weight) || weight <= 0) {
+            return;
+        }
+        weightMap.set(token, Number(weight.toFixed(8)));
+    });
+    return weightMap;
+}
+function computeLocalVectorSignature(atoms) {
+    const hash = (0, crypto_1.createHash)('sha256');
+    hash.update(LOCAL_VECTOR_INDEX_SIGNATURE_VERSION);
+    const sortedAtoms = [...atoms].sort((left, right) => left.id.localeCompare(right.id));
+    sortedAtoms.forEach((atom) => {
+        const sourceHash = String(atom.metadata?.sourceHash || '').trim();
+        const version = Number(atom.metadata?.version || 0);
+        hash.update(atom.id);
+        hash.update('\u0000');
+        hash.update(String(atom.updatedAt || ''));
+        hash.update('\u0000');
+        hash.update(sourceHash);
+        hash.update('\u0000');
+        hash.update(String(Number.isFinite(version) ? version : 0));
+        hash.update('\u0000');
+        if (!sourceHash) {
+            hash.update(String(atom.title || ''));
+            hash.update('\u0000');
+            hash.update(String(atom.content || ''));
+            hash.update('\u0000');
+            hash.update((atom.keywords || []).join('|'));
+        }
+        hash.update('\u0001');
+    });
+    return hash.digest('hex');
+}
+function getLocalVectorTokenHash64(token) {
+    const normalizedToken = String(token || '').trim().toLowerCase();
+    if (!normalizedToken) {
+        return 0n;
+    }
+    const cached = LOCAL_VECTOR_TOKEN_HASH_CACHE.get(normalizedToken);
+    if (typeof cached !== 'undefined') {
+        return cached;
+    }
+    const tokenHashHex = (0, crypto_1.createHash)('sha1')
+        .update(`local_vector_ann:${normalizedToken}`)
+        .digest('hex')
+        .slice(0, 16);
+    const tokenHash = BigInt(`0x${tokenHashHex}`);
+    if (LOCAL_VECTOR_TOKEN_HASH_CACHE.size >= LOCAL_VECTOR_ANN_HASH_CACHE_SOFT_LIMIT) {
+        const firstKey = LOCAL_VECTOR_TOKEN_HASH_CACHE.keys().next().value;
+        if (typeof firstKey === 'string') {
+            LOCAL_VECTOR_TOKEN_HASH_CACHE.delete(firstKey);
+        }
+    }
+    LOCAL_VECTOR_TOKEN_HASH_CACHE.set(normalizedToken, tokenHash);
+    return tokenHash;
+}
+function computeWeightedSimHash(weights) {
+    if (weights.size <= 0) {
+        return 0n;
+    }
+    const accumulator = new Array(64).fill(0);
+    weights.forEach((weight, token) => {
+        const numericWeight = Number(weight);
+        if (!Number.isFinite(numericWeight) || numericWeight <= 0) {
+            return;
+        }
+        const tokenHash = getLocalVectorTokenHash64(token);
+        for (let bitIndex = 0; bitIndex < 64; bitIndex += 1) {
+            const bitMask = (tokenHash >> BigInt(bitIndex)) & 1n;
+            accumulator[bitIndex] += bitMask === 1n ? numericWeight : -numericWeight;
+        }
+    });
+    let signature = 0n;
+    for (let bitIndex = 0; bitIndex < 64; bitIndex += 1) {
+        if (accumulator[bitIndex] >= 0) {
+            signature |= (1n << BigInt(bitIndex));
+        }
+    }
+    return signature;
+}
+function computeSimHashPrefix(signature, prefixBits) {
+    const normalizedBits = Math.max(1, Math.min(64, Math.floor(Number(prefixBits) || 0)));
+    const shiftBits = Math.max(0, 64 - normalizedBits);
+    const prefixValue = shiftBits > 0
+        ? (signature >> BigInt(shiftBits))
+        : signature;
+    const width = Math.max(1, Math.ceil(normalizedBits / 4));
+    return prefixValue.toString(16).padStart(width, '0');
+}
+function buildLocalVectorAnnStructures(entriesByAtomId) {
+    const tokenToAtomIds = new Map();
+    const signatureBuckets = new Map();
+    entriesByAtomId.forEach((entry, atomId) => {
+        entry.tokens.forEach((token) => {
+            if (!token) {
+                return;
+            }
+            const postingList = tokenToAtomIds.get(token) || [];
+            postingList.push(atomId);
+            tokenToAtomIds.set(token, postingList);
+        });
+        const prefix = entry.signaturePrefix;
+        if (!prefix) {
+            return;
+        }
+        const bucket = signatureBuckets.get(prefix) || [];
+        bucket.push(atomId);
+        signatureBuckets.set(prefix, bucket);
+    });
+    return {
+        tokenToAtomIds,
+        signatureBuckets,
+    };
+}
+function selectLocalVectorAnnCandidatesByDefaultStrategy(input) {
+    if (!input.annPrefilterEnabled) {
+        return {
+            used: false,
+            candidateAtomIds: [],
+            mode: 'full_scan',
+        };
+    }
+    if (input.atomCount < LOCAL_VECTOR_ANN_MIN_ATOMS) {
+        return {
+            used: false,
+            candidateAtomIds: [],
+            mode: 'full_scan',
+        };
+    }
+    const prioritizedTokens = uniqueTokens([
+        ...Array.from(input.queryWeights.entries())
+            .filter((entry) => entry[1] > 0)
+            .sort((left, right) => right[1] - left[1])
+            .map((entry) => entry[0]),
+        ...input.queryTokens,
+    ]).slice(0, LOCAL_VECTOR_ANN_TOP_QUERY_TOKENS);
+    if (prioritizedTokens.length <= 0) {
+        return {
+            used: false,
+            candidateAtomIds: [],
+            mode: 'full_scan',
+        };
+    }
+    const targetCandidateCount = Math.min(input.atomCount, Math.max(LOCAL_VECTOR_ANN_CANDIDATE_MIN_FLOOR, Math.max(1, input.topK) * LOCAL_VECTOR_ANN_CANDIDATE_MULTIPLIER));
+    const minimumCandidateCount = Math.min(input.atomCount, Math.max(Math.max(1, input.topK) * 2, Math.floor(LOCAL_VECTOR_ANN_CANDIDATE_MIN_FLOOR / 2)));
+    const candidateAtomIds = new Set();
+    let tokenPrefilterUsed = false;
+    prioritizedTokens.forEach((token) => {
+        if (candidateAtomIds.size >= targetCandidateCount) {
+            return;
+        }
+        const postingList = input.tokenToAtomIds.get(token);
+        if (!postingList || postingList.length <= 0) {
+            return;
+        }
+        tokenPrefilterUsed = true;
+        postingList.forEach((atomId) => {
+            if (candidateAtomIds.size >= targetCandidateCount) {
+                return;
+            }
+            const normalizedAtomId = String(atomId || '').trim();
+            if (normalizedAtomId) {
+                candidateAtomIds.add(normalizedAtomId);
+            }
+        });
+    });
+    let signaturePrefilterUsed = false;
+    if (candidateAtomIds.size < targetCandidateCount && input.queryWeights.size > 0) {
+        const querySignature = computeWeightedSimHash(new Map(input.queryWeights));
+        const queryPrefix = computeSimHashPrefix(querySignature, LOCAL_VECTOR_ANN_SIGNATURE_PREFIX_BITS);
+        const signatureBucket = input.signatureBuckets.get(queryPrefix);
+        if (signatureBucket && signatureBucket.length > 0) {
+            signaturePrefilterUsed = true;
+            signatureBucket.forEach((atomId) => {
+                if (candidateAtomIds.size >= targetCandidateCount) {
+                    return;
+                }
+                const normalizedAtomId = String(atomId || '').trim();
+                if (normalizedAtomId) {
+                    candidateAtomIds.add(normalizedAtomId);
+                }
+            });
+        }
+    }
+    if (!tokenPrefilterUsed || candidateAtomIds.size < minimumCandidateCount) {
+        return {
+            used: false,
+            candidateAtomIds: [],
+            mode: 'full_scan',
+        };
+    }
+    return {
+        used: true,
+        candidateAtomIds: Array.from(candidateAtomIds),
+        mode: signaturePrefilterUsed ? 'token_signature_prefilter' : 'token_prefilter',
+    };
+}
+const DEFAULT_LOCAL_VECTOR_ACCELERATION_ADAPTER = {
+    id: LOCAL_VECTOR_ACCELERATION_ADAPTER_ID,
+    syncIndex: () => ({
+        synced: true,
+    }),
+    selectCandidates: selectLocalVectorAnnCandidatesByDefaultStrategy,
+    getHealth: () => ({
+        status: 'ready',
+        message: 'local_ann_prefilter_active',
+        checkedAt: new Date().toISOString(),
+        indexSyncStatus: 'ready',
+        indexSyncMessage: 'local_adapter_index_sync_not_required',
+        representationVersion: LOCAL_VECTOR_REPRESENTATION_VERSION,
+        embeddingModelId: LOCAL_VECTOR_EMBEDDING_MODEL_ID,
+        representationStatus: 'aligned',
+        representationStatusReason: 'local_adapter_representation_aligned',
+    }),
+};
+async function selectLocalVectorAnnCandidates(params) {
+    const adapterId = String(params.accelerationAdapter?.id || '').trim() || LOCAL_VECTOR_ACCELERATION_ADAPTER_ID;
+    try {
+        params.signal?.throwIfAborted();
+        if (typeof params.accelerationAdapter.syncIndex === 'function') {
+            await params.accelerationAdapter.syncIndex({
+                signal: params.signal,
+                atomCount: params.index.atomCount,
+                tokenToAtomIds: params.index.tokenToAtomIds,
+                signatureBuckets: params.index.signatureBuckets,
+                representationVersion: LOCAL_VECTOR_REPRESENTATION_VERSION,
+                embeddingModelId: LOCAL_VECTOR_EMBEDDING_MODEL_ID,
+                embeddingDimension: params.index.documentFrequency.size,
+                indexSignature: params.index.signature,
+            });
+        }
+        params.signal?.throwIfAborted();
+        const rawSelection = await params.accelerationAdapter.selectCandidates({
+            signal: params.signal,
+            atomCount: params.index.atomCount,
+            queryTokens: [...params.queryTokens],
+            queryWeights: params.queryWeights,
+            topK: params.topK,
+            tokenToAtomIds: params.index.tokenToAtomIds,
+            signatureBuckets: params.index.signatureBuckets,
+            annPrefilterEnabled: params.annPrefilterEnabled,
+            representationVersion: LOCAL_VECTOR_REPRESENTATION_VERSION,
+            embeddingModelId: LOCAL_VECTOR_EMBEDDING_MODEL_ID,
+            embeddingDimension: params.index.documentFrequency.size,
+            indexSignature: params.index.signature,
+        });
+        params.signal?.throwIfAborted();
+        const mode = (rawSelection?.mode === 'token_prefilter'
+            || rawSelection?.mode === 'token_signature_prefilter'
+            || rawSelection?.mode === 'full_scan') ? rawSelection.mode : 'full_scan';
+        const candidateAtomIds = new Set(Array.isArray(rawSelection?.candidateAtomIds)
+            ? rawSelection.candidateAtomIds
+                .map((atomId) => String(atomId || '').trim())
+                .filter((atomId) => atomId.length > 0)
+            : []);
+        const used = rawSelection?.used === true
+            && mode !== 'full_scan'
+            && candidateAtomIds.size > 0;
+        return {
+            used,
+            candidateAtomIds: used ? candidateAtomIds : new Set(),
+            mode: used ? mode : 'full_scan',
+            adapterId,
+        };
+    }
+    catch (error) {
+        params.signal?.throwIfAborted();
+        const normalizedError = String(error?.message || error || 'unknown_error')
+            .replace(/\s+/g, ' ')
+            .trim()
+            .slice(0, 240);
+        if (params.failureMode === 'fail_closed') {
+            throw new Error(`vector_acceleration_adapter_failure:${adapterId}:${normalizedError || 'unknown_error'}`);
+        }
+        return {
+            used: false,
+            candidateAtomIds: new Set(),
+            mode: 'full_scan',
+            adapterId,
+            adapterError: normalizedError,
+        };
+    }
+}
+class LocalHybridGraphQueryBackend {
+    constructor() {
+        this.id = 'local-hybrid-v1';
+    }
+    async query(context) {
+        const queryVariants = buildQueryTextVariants(context);
+        const querySemanticTokens = buildQuerySemanticTokens(context);
+        const graphFeatureIndex = buildGraphFeatureIndex(context, querySemanticTokens);
+        const candidates = [];
+        for (const [candidateIndex, atom] of context.atoms.entries()) {
+            if (context.signal && candidateIndex % 128 === 0) {
+                await new Promise(resolve => setImmediate(resolve));
+                context.signal.throwIfAborted();
+            }
+            const titleLower = atom.title.toLowerCase();
+            const contentLower = atom.content.toLowerCase();
+            const keywordMatches = context.queryTokens.filter((token) => atom.keywords.includes(token)).length;
+            const titleMatchBonus = queryVariants.some((variant) => titleLower.includes(variant)) ? 2 : 0;
+            const contentMatchBonus = context.queryTokens.filter((token) => contentLower.includes(token)).length * 0.25;
+            const atomSemanticTokens = buildAtomSemanticTokens(atom);
+            const semanticSimilarity = computeJaccard(querySemanticTokens, atomSemanticTokens);
+            const semanticBonus = semanticSimilarity * 1.6;
+            const graphFeatureBonus = computeGraphFeatureScore(context, atom.id, graphFeatureIndex);
+            const score = keywordMatches + titleMatchBonus + contentMatchBonus + semanticBonus + graphFeatureBonus;
+            if (score > 0) {
+                candidates.push({
+                    atomId: atom.id,
+                    score: Number(clamp(score, 0, 100).toFixed(4)),
+                });
+            }
+        }
+        candidates.sort((left, right) => right.score - left.score);
+        const maxCandidates = Math.max(context.topK, Math.min(context.atoms.length, context.topK * 4));
+        return {
+            candidates: candidates.slice(0, maxCandidates),
+            trace: {
+                retrievalModes: ['keyword', 'semantic_similarity', 'graph_anchor_distance', 'graph_path_confidence', 'graph_intent_match', 'temporal_filter'],
+                modeWeights: {
+                    keyword: 0.32,
+                    semantic: 0.2,
+                    graph: 0.3,
+                    temporal: 0.18,
+                },
+            },
+        };
+    }
+    getDiagnostics() {
+        return {
+            backendId: this.id,
+            ready: true,
+        };
+    }
+}
+exports.LocalHybridGraphQueryBackend = LocalHybridGraphQueryBackend;
+class KeywordOnlyGraphQueryBackend {
+    constructor() {
+        this.id = 'keyword-only-v1';
+    }
+    async query(context) {
+        const queryVariants = buildQueryTextVariants(context);
+        const candidates = [];
+        for (const [candidateIndex, atom] of context.atoms.entries()) {
+            if (context.signal && candidateIndex % 128 === 0) {
+                await new Promise(resolve => setImmediate(resolve));
+                context.signal.throwIfAborted();
+            }
+            const titleLower = atom.title.toLowerCase();
+            const contentLower = atom.content.toLowerCase();
+            const keywordMatches = context.queryTokens.filter((token) => atom.keywords.includes(token)).length;
+            const titleMatchBonus = queryVariants.some((variant) => titleLower.includes(variant)) ? 2 : 0;
+            const contentMatchBonus = context.queryTokens.filter((token) => contentLower.includes(token)).length * 0.22;
+            const score = keywordMatches + titleMatchBonus + contentMatchBonus;
+            if (score > 0) {
+                candidates.push({
+                    atomId: atom.id,
+                    score: Number(clamp(score, 0, 100).toFixed(4)),
+                });
+            }
+        }
+        candidates.sort((left, right) => right.score - left.score);
+        const maxCandidates = Math.max(context.topK, Math.min(context.atoms.length, context.topK * 4));
+        return {
+            candidates: candidates.slice(0, maxCandidates),
+            trace: {
+                retrievalModes: ['keyword', 'temporal_filter'],
+                modeWeights: {
+                    keyword: 0.72,
+                    graph: 0.1,
+                    temporal: 0.18,
+                },
+            },
+        };
+    }
+    getDiagnostics() {
+        return {
+            backendId: this.id,
+            ready: true,
+        };
+    }
+}
+exports.KeywordOnlyGraphQueryBackend = KeywordOnlyGraphQueryBackend;
+class LocalVectorGraphQueryBackend {
+    constructor(options = {}) {
+        this.id = LOCAL_VECTOR_INDEX_BACKEND_ID;
+        this.activeIndex = null;
+        this.pendingIndexSignature = null;
+        this.pendingIndexBuild = null;
+        this.invalidated = false;
+        this.lastAnnSelectionMode = 'full_scan';
+        this.lastAnnCandidateCount = 0;
+        this.lastAnnAdapterId = LOCAL_VECTOR_ACCELERATION_ADAPTER_ID;
+        this.lastAnnAdapterHealthStatus = 'unknown';
+        this.lastAnnIndexSyncStatus = 'unknown';
+        this.lastAnnIndexSyncRequestCount = 0;
+        this.lastAnnIndexSyncSuccessCount = 0;
+        this.lastAnnIndexSyncFailureCount = 0;
+        this.lastAnnAdapterCircuitState = 'unknown';
+        this.lastAnnAdapterConsecutiveFailures = 0;
+        this.lastAnnAdapterRequestCount = 0;
+        this.lastAnnAdapterRetryCount = 0;
+        this.lastAnnAdapterShortCircuitCount = 0;
+        this.lastAnnAdapterSuccessCount = 0;
+        this.lastAnnAdapterFailureCount = 0;
+        this.lastAnnAdapterHalfOpenProbeSuccessCount = 0;
+        this.lastAnnAdapterHalfOpenProbeFailureCount = 0;
+        this.lastAnnAdapterLastRetryAfterMs = 0;
+        this.lastAnnRepresentationStatus = 'unknown';
+        this.localVectorIndexPath = normalizeVectorIndexPath(options.localVectorIndexPath);
+        this.localVectorAnnPrefilterEnabled = options.localVectorAnnPrefilterEnabled !== false;
+        const providedAdapter = options.localVectorAccelerationAdapter;
+        const normalizedAdapterId = String(providedAdapter?.id || '').trim();
+        this.localVectorAccelerationAdapter = (providedAdapter
+            && normalizedAdapterId
+            && typeof providedAdapter.selectCandidates === 'function')
+            ? providedAdapter
+            : DEFAULT_LOCAL_VECTOR_ACCELERATION_ADAPTER;
+        this.localVectorAccelerationFailureMode = normalizeLocalVectorAccelerationFailureMode(options.localVectorAccelerationFailureMode);
+        this.localVectorAccelerationRepresentationStrict =
+            options.localVectorAccelerationRepresentationStrict === true;
+        this.refreshAccelerationAdapterHealth();
+    }
+    async query(context) {
+        const indexAtoms = this.resolveIndexAtoms(context);
+        const index = await this.ensureIndex(indexAtoms);
+        const querySemanticTokens = buildQuerySemanticTokens(context);
+        const queryFrequency = buildTokenFrequency(querySemanticTokens);
+        const graphFeatureIndex = buildGraphFeatureIndex(context, querySemanticTokens);
+        const totalDocs = Math.max(1, index.atomCount);
+        const queryWeights = buildTfIdfWeights(queryFrequency, index.documentFrequency, totalDocs);
+        const querySignaturePrefix = computeSimHashPrefix(computeWeightedSimHash(queryWeights), LOCAL_VECTOR_ANN_SIGNATURE_PREFIX_BITS);
+        let annCandidateSelection;
+        try {
+            annCandidateSelection = await selectLocalVectorAnnCandidates({
+                signal: context.signal,
+                index,
+                queryTokens: querySemanticTokens,
+                queryWeights,
+                topK: context.topK,
+                annPrefilterEnabled: this.localVectorAnnPrefilterEnabled,
+                accelerationAdapter: this.localVectorAccelerationAdapter,
+                failureMode: this.localVectorAccelerationFailureMode,
+            });
+        }
+        catch (error) {
+            this.refreshAccelerationAdapterHealth();
+            this.lastAnnSelectionMode = 'full_scan';
+            this.lastAnnCandidateCount = index.atomCount;
+            this.lastAnnAdapterId = String(this.localVectorAccelerationAdapter?.id || '').trim()
+                || LOCAL_VECTOR_ACCELERATION_ADAPTER_ID;
+            this.lastAnnAdapterError = String(error?.message || error || 'unknown_error')
+                .replace(/\s+/g, ' ')
+                .trim()
+                .slice(0, 240);
+            this.lastError = this.lastAnnAdapterError;
+            throw error;
+        }
+        this.refreshAccelerationAdapterHealth();
+        this.lastAnnSelectionMode = annCandidateSelection.mode;
+        this.lastAnnAdapterId = annCandidateSelection.adapterId;
+        this.lastAnnAdapterError = annCandidateSelection.adapterError;
+        const representationTelemetry = this.resolveAccelerationRepresentationTelemetry(index);
+        if (this.localVectorAccelerationRepresentationStrict
+            && representationTelemetry.representationStatus === 'mismatch') {
+            const mismatchReason = String(representationTelemetry.representationStatusReason || 'representation_mismatch').trim().replace(/\s+/g, '_').slice(0, 200) || 'representation_mismatch';
+            const strictMismatchError = (`vector_acceleration_representation_mismatch:${this.lastAnnAdapterId || 'unknown'}:${mismatchReason}`);
+            this.lastAnnAdapterError = strictMismatchError;
+            this.lastError = strictMismatchError;
+            throw new Error(strictMismatchError);
+        }
+        const scopedAtomIds = new Set(context.atoms.map((atom) => atom.id));
+        const scopedAnnCandidateAtomIds = annCandidateSelection.used
+            ? Array.from(annCandidateSelection.candidateAtomIds.values())
+                .filter((atomId) => scopedAtomIds.has(atomId))
+            : [];
+        const annScopedPrefilterUsable = (annCandidateSelection.used
+            && scopedAtomIds.size > 0
+            && scopedAnnCandidateAtomIds.length > 0);
+        const atomIdsToScore = annScopedPrefilterUsable
+            ? scopedAnnCandidateAtomIds
+            : context.atoms.map((atom) => atom.id);
+        this.lastAnnCandidateCount = annScopedPrefilterUsable
+            ? scopedAnnCandidateAtomIds.length
+            : scopedAtomIds.size;
+        const accelerationMode = (this.localVectorAnnPrefilterEnabled
+            && annScopedPrefilterUsable
+            && annCandidateSelection.mode !== 'full_scan') ? 'ann_prefilter' : 'full_scan';
+        const vectorAccelerationTrace = {
+            mode: accelerationMode,
+            selectionMode: annCandidateSelection.mode,
+            failureMode: this.localVectorAccelerationFailureMode,
+            candidateCount: this.lastAnnCandidateCount,
+            adapterId: this.lastAnnAdapterId,
+            adapterError: this.lastAnnAdapterError,
+            healthStatus: this.lastAnnAdapterHealthStatus,
+            circuitState: this.lastAnnAdapterCircuitState,
+            lastRequestId: this.lastAnnAdapterLastRequestId,
+            lastErrorCode: this.lastAnnAdapterLastErrorCode,
+            lastRetryAfterMs: this.lastAnnAdapterLastRetryAfterMs > 0
+                ? this.lastAnnAdapterLastRetryAfterMs
+                : undefined,
+            representationVersion: representationTelemetry.representationVersion,
+            embeddingModelId: representationTelemetry.embeddingModelId,
+            embeddingDimension: representationTelemetry.embeddingDimension,
+            indexSignature: representationTelemetry.indexSignature,
+            representationStatus: representationTelemetry.representationStatus,
+            representationStatusReason: representationTelemetry.representationStatusReason,
+            representationStrictMode: this.localVectorAccelerationRepresentationStrict,
+        };
+        const candidates = [];
+        for (const [candidateIndex, atomId] of atomIdsToScore.entries()) {
+            if (context.signal && candidateIndex % 128 === 0) {
+                await new Promise(resolve => setImmediate(resolve));
+                context.signal.throwIfAborted();
+            }
+            const entry = index.entriesByAtomId.get(atomId);
+            if (!entry) {
+                continue;
+            }
+            const cosineSimilarity = computeCosineSimilarity(queryWeights, entry.weights);
+            const semanticOverlap = computeJaccard(querySemanticTokens, entry.tokens);
+            const graphFeatureBonus = computeGraphFeatureScore(context, atomId, graphFeatureIndex);
+            const signatureBonus = entry.signaturePrefix === querySignaturePrefix
+                ? LOCAL_VECTOR_ANN_SIGNATURE_SCORE_BONUS
+                : 0;
+            const score = (cosineSimilarity * 4.2) + (semanticOverlap * 1.1) + graphFeatureBonus + signatureBonus;
+            if (score <= 0) {
+                continue;
+            }
+            candidates.push({
+                atomId,
+                score: Number(clamp(score, 0, 100).toFixed(4)),
+            });
+        }
+        candidates.sort((left, right) => right.score - left.score);
+        const maxCandidates = Math.max(context.topK, Math.min(context.atoms.length, context.topK * 4));
+        return {
+            candidates: candidates.slice(0, maxCandidates),
+            trace: {
+                retrievalModes: [
+                    'vector_similarity',
+                    'semantic_similarity',
+                    'graph_anchor_distance',
+                    'graph_path_confidence',
+                    'graph_intent_match',
+                    'temporal_filter',
+                    ...(annScopedPrefilterUsable ? ['ann_prefilter'] : []),
+                ],
+                modeWeights: {
+                    vector: 0.58,
+                    semantic: 0.14,
+                    graph: 0.1,
+                    temporal: 0.18,
+                },
+                vectorAcceleration: vectorAccelerationTrace,
+            },
+        };
+    }
+    resolveIndexAtoms(context) {
+        const atomsById = new Map();
+        const candidateIndexAtoms = (Array.isArray(context.indexAtoms)
+            && context.indexAtoms.length >= context.atoms.length)
+            ? context.indexAtoms
+            : context.atoms;
+        candidateIndexAtoms.forEach((atom) => {
+            if (atom && atom.id) {
+                atomsById.set(atom.id, atom);
+            }
+        });
+        context.atoms.forEach((atom) => {
+            if (atom && atom.id && !atomsById.has(atom.id)) {
+                atomsById.set(atom.id, atom);
+            }
+        });
+        return Array.from(atomsById.values());
+    }
+    getDiagnostics() {
+        const index = this.activeIndex;
+        const ready = (Boolean(index) && !this.invalidated) || !this.lastError;
+        const status = (index && !this.invalidated)
+            ? 'ready'
+            : (this.lastError ? 'unavailable' : 'stale');
+        const accelerationMode = (this.localVectorAnnPrefilterEnabled
+            && this.lastAnnSelectionMode !== 'full_scan') ? 'ann_prefilter' : 'full_scan';
+        const representationTelemetry = index
+            ? this.resolveAccelerationRepresentationTelemetry(index)
+            : {
+                representationVersion: this.lastAnnRepresentationVersion,
+                embeddingModelId: this.lastAnnEmbeddingModelId,
+                embeddingDimension: this.lastAnnEmbeddingDimension,
+                indexSignature: this.lastAnnIndexSignature,
+                representationStatus: this.lastAnnRepresentationStatus,
+                representationStatusReason: this.lastAnnRepresentationStatusReason,
+            };
+        return {
+            backendId: this.id,
+            ready,
+            lastError: this.lastError,
+            vectorIndex: {
+                enabled: true,
+                status,
+                location: this.localVectorIndexPath,
+                signature: index?.signature,
+                builtAt: index?.builtAt,
+                atomCount: index?.atomCount,
+                loadedFromDisk: index?.loadedFromDisk,
+                persisted: index?.persisted,
+                acceleration: {
+                    enabled: this.localVectorAnnPrefilterEnabled,
+                    mode: accelerationMode,
+                    failureMode: this.localVectorAccelerationFailureMode,
+                    indexSyncStatus: this.lastAnnIndexSyncStatus,
+                    indexSyncMessage: this.lastAnnIndexSyncMessage,
+                    lastSyncAt: this.lastAnnIndexLastSyncAt,
+                    syncRequestCount: this.lastAnnIndexSyncRequestCount,
+                    syncSuccessCount: this.lastAnnIndexSyncSuccessCount,
+                    syncFailureCount: this.lastAnnIndexSyncFailureCount,
+                    syncedIndexSignature: this.lastAnnIndexSyncedSignature,
+                    syncedAtomCount: this.lastAnnIndexSyncedAtomCount,
+                    lastSelectionMode: this.lastAnnSelectionMode,
+                    lastCandidateCount: this.lastAnnCandidateCount,
+                    adapterId: this.lastAnnAdapterId,
+                    adapterError: this.lastAnnAdapterError,
+                    healthStatus: this.lastAnnAdapterHealthStatus,
+                    healthMessage: this.lastAnnAdapterHealthMessage,
+                    healthCheckedAt: this.lastAnnAdapterHealthCheckedAt,
+                    circuitState: this.lastAnnAdapterCircuitState,
+                    consecutiveFailures: this.lastAnnAdapterConsecutiveFailures,
+                    requestCount: this.lastAnnAdapterRequestCount,
+                    retryCount: this.lastAnnAdapterRetryCount,
+                    shortCircuitCount: this.lastAnnAdapterShortCircuitCount,
+                    successCount: this.lastAnnAdapterSuccessCount,
+                    failureCount: this.lastAnnAdapterFailureCount,
+                    halfOpenProbeSuccessCount: this.lastAnnAdapterHalfOpenProbeSuccessCount,
+                    halfOpenProbeFailureCount: this.lastAnnAdapterHalfOpenProbeFailureCount,
+                    lastSuccessAt: this.lastAnnAdapterLastSuccessAt,
+                    lastFailureAt: this.lastAnnAdapterLastFailureAt,
+                    circuitOpenedAt: this.lastAnnAdapterCircuitOpenedAt,
+                    lastRequestId: this.lastAnnAdapterLastRequestId,
+                    lastErrorCode: this.lastAnnAdapterLastErrorCode,
+                    lastRetryAfterMs: this.lastAnnAdapterLastRetryAfterMs > 0
+                        ? this.lastAnnAdapterLastRetryAfterMs
+                        : undefined,
+                    representationVersion: representationTelemetry.representationVersion,
+                    embeddingModelId: representationTelemetry.embeddingModelId,
+                    embeddingDimension: representationTelemetry.embeddingDimension,
+                    indexSignature: representationTelemetry.indexSignature,
+                    representationStatus: representationTelemetry.representationStatus,
+                    representationStatusReason: representationTelemetry.representationStatusReason,
+                    representationStrictMode: this.localVectorAccelerationRepresentationStrict,
+                },
+            },
+        };
+    }
+    invalidate(reason) {
+        this.invalidated = true;
+        this.invalidationReason = String(reason || '').trim().slice(0, 160) || undefined;
+    }
+    refreshAccelerationAdapterHealth() {
+        if (!this.localVectorAccelerationAdapter || typeof this.localVectorAccelerationAdapter.getHealth !== 'function') {
+            this.lastAnnAdapterHealthStatus = 'unknown';
+            this.lastAnnAdapterHealthMessage = 'adapter_health_not_reported';
+            this.lastAnnAdapterHealthCheckedAt = new Date().toISOString();
+            this.lastAnnIndexSyncStatus = 'unknown';
+            this.lastAnnIndexSyncMessage = 'adapter_health_not_reported';
+            this.lastAnnIndexLastSyncAt = undefined;
+            this.lastAnnIndexSyncRequestCount = 0;
+            this.lastAnnIndexSyncSuccessCount = 0;
+            this.lastAnnIndexSyncFailureCount = 0;
+            this.lastAnnIndexSyncedSignature = undefined;
+            this.lastAnnIndexSyncedAtomCount = undefined;
+            this.lastAnnAdapterCircuitState = 'unknown';
+            this.lastAnnAdapterConsecutiveFailures = 0;
+            this.lastAnnAdapterRequestCount = 0;
+            this.lastAnnAdapterRetryCount = 0;
+            this.lastAnnAdapterShortCircuitCount = 0;
+            this.lastAnnAdapterSuccessCount = 0;
+            this.lastAnnAdapterFailureCount = 0;
+            this.lastAnnAdapterHalfOpenProbeSuccessCount = 0;
+            this.lastAnnAdapterHalfOpenProbeFailureCount = 0;
+            this.lastAnnAdapterLastSuccessAt = undefined;
+            this.lastAnnAdapterLastFailureAt = undefined;
+            this.lastAnnAdapterCircuitOpenedAt = undefined;
+            this.lastAnnAdapterLastRequestId = undefined;
+            this.lastAnnAdapterLastErrorCode = undefined;
+            this.lastAnnAdapterLastRetryAfterMs = 0;
+            this.lastAnnRepresentationVersion = undefined;
+            this.lastAnnEmbeddingModelId = undefined;
+            this.lastAnnEmbeddingDimension = undefined;
+            this.lastAnnIndexSignature = undefined;
+            this.lastAnnRepresentationStatus = 'unknown';
+            this.lastAnnRepresentationStatusReason = 'adapter_health_not_reported';
+            return;
+        }
+        try {
+            const health = this.localVectorAccelerationAdapter.getHealth();
+            const normalizedStatus = String(health?.status || '').trim().toLowerCase();
+            this.lastAnnAdapterHealthStatus = (normalizedStatus === 'ready'
+                || normalizedStatus === 'degraded'
+                || normalizedStatus === 'unavailable'
+                || normalizedStatus === 'unknown') ? normalizedStatus : 'unknown';
+            this.lastAnnAdapterHealthMessage = String(health?.message || '').trim().slice(0, 240) || undefined;
+            this.lastAnnAdapterHealthCheckedAt = String(health?.checkedAt || '').trim() || new Date().toISOString();
+            const normalizedIndexSyncStatus = String(health?.indexSyncStatus || '').trim().toLowerCase();
+            this.lastAnnIndexSyncStatus = (normalizedIndexSyncStatus === 'ready'
+                || normalizedIndexSyncStatus === 'degraded'
+                || normalizedIndexSyncStatus === 'unavailable'
+                || normalizedIndexSyncStatus === 'unknown') ? normalizedIndexSyncStatus : 'unknown';
+            this.lastAnnIndexSyncMessage = String(health?.indexSyncMessage || '').trim().slice(0, 240) || undefined;
+            this.lastAnnIndexLastSyncAt = String(health?.lastSyncAt || '').trim() || undefined;
+            this.lastAnnIndexSyncRequestCount = Math.max(0, Math.floor(Number(health?.syncRequestCount || 0)));
+            this.lastAnnIndexSyncSuccessCount = Math.max(0, Math.floor(Number(health?.syncSuccessCount || 0)));
+            this.lastAnnIndexSyncFailureCount = Math.max(0, Math.floor(Number(health?.syncFailureCount || 0)));
+            this.lastAnnIndexSyncedSignature = String(health?.syncedIndexSignature || '').trim().slice(0, 200) || undefined;
+            this.lastAnnIndexSyncedAtomCount = Number.isFinite(Number(health?.syncedAtomCount))
+                ? Math.max(0, Math.floor(Number(health?.syncedAtomCount || 0)))
+                : undefined;
+            const normalizedCircuitState = String(health?.circuitState || '').trim().toLowerCase();
+            this.lastAnnAdapterCircuitState = (normalizedCircuitState === 'closed'
+                || normalizedCircuitState === 'open'
+                || normalizedCircuitState === 'half_open'
+                || normalizedCircuitState === 'unknown') ? normalizedCircuitState : 'unknown';
+            this.lastAnnAdapterConsecutiveFailures = Math.max(0, Math.floor(Number(health?.consecutiveFailures || 0)));
+            this.lastAnnAdapterRequestCount = Math.max(0, Math.floor(Number(health?.requestCount || 0)));
+            this.lastAnnAdapterRetryCount = Math.max(0, Math.floor(Number(health?.retryCount || 0)));
+            this.lastAnnAdapterShortCircuitCount = Math.max(0, Math.floor(Number(health?.shortCircuitCount || 0)));
+            this.lastAnnAdapterSuccessCount = Math.max(0, Math.floor(Number(health?.successCount || 0)));
+            this.lastAnnAdapterFailureCount = Math.max(0, Math.floor(Number(health?.failureCount || 0)));
+            this.lastAnnAdapterHalfOpenProbeSuccessCount = Math.max(0, Math.floor(Number(health?.halfOpenProbeSuccessCount || 0)));
+            this.lastAnnAdapterHalfOpenProbeFailureCount = Math.max(0, Math.floor(Number(health?.halfOpenProbeFailureCount || 0)));
+            this.lastAnnAdapterLastSuccessAt = String(health?.lastSuccessAt || '').trim() || undefined;
+            this.lastAnnAdapterLastFailureAt = String(health?.lastFailureAt || '').trim() || undefined;
+            this.lastAnnAdapterCircuitOpenedAt = String(health?.circuitOpenedAt || '').trim() || undefined;
+            this.lastAnnAdapterLastRequestId = String(health?.lastRequestId || '').trim() || undefined;
+            this.lastAnnAdapterLastErrorCode = String(health?.lastErrorCode || '').trim() || undefined;
+            this.lastAnnAdapterLastRetryAfterMs = Math.max(0, Math.floor(Number(health?.lastRetryAfterMs || 0)));
+            this.lastAnnRepresentationVersion = String(health?.representationVersion || '').trim().slice(0, 160) || undefined;
+            this.lastAnnEmbeddingModelId = String(health?.embeddingModelId || '').trim().slice(0, 160) || undefined;
+            this.lastAnnEmbeddingDimension = Number.isFinite(Number(health?.embeddingDimension))
+                ? Math.max(0, Math.floor(Number(health?.embeddingDimension || 0)))
+                : undefined;
+            this.lastAnnIndexSignature = String(health?.indexSignature || '')
+                .trim()
+                .replace(/[^a-zA-Z0-9:_-]+/g, '')
+                .slice(0, 200) || undefined;
+            const rawRepresentationStatus = String(health?.representationStatus || '').trim().toLowerCase();
+            this.lastAnnRepresentationStatus = (rawRepresentationStatus === 'aligned'
+                || rawRepresentationStatus === 'mismatch'
+                || rawRepresentationStatus === 'unknown') ? rawRepresentationStatus : 'unknown';
+            this.lastAnnRepresentationStatusReason = String(health?.representationStatusReason || '')
+                .trim()
+                .replace(/\s+/g, ' ')
+                .slice(0, 240) || undefined;
+        }
+        catch (error) {
+            this.lastAnnAdapterHealthStatus = 'unavailable';
+            this.lastAnnAdapterHealthMessage = String(error?.message || error).slice(0, 240);
+            this.lastAnnAdapterHealthCheckedAt = new Date().toISOString();
+            this.lastAnnIndexSyncStatus = 'unknown';
+            this.lastAnnIndexSyncMessage = 'adapter_health_probe_failed';
+            this.lastAnnIndexLastSyncAt = undefined;
+            this.lastAnnIndexSyncRequestCount = 0;
+            this.lastAnnIndexSyncSuccessCount = 0;
+            this.lastAnnIndexSyncFailureCount = 0;
+            this.lastAnnIndexSyncedSignature = undefined;
+            this.lastAnnIndexSyncedAtomCount = undefined;
+            this.lastAnnAdapterCircuitState = 'unknown';
+            this.lastAnnAdapterConsecutiveFailures = 0;
+            this.lastAnnAdapterRequestCount = 0;
+            this.lastAnnAdapterRetryCount = 0;
+            this.lastAnnAdapterShortCircuitCount = 0;
+            this.lastAnnAdapterSuccessCount = 0;
+            this.lastAnnAdapterFailureCount = 0;
+            this.lastAnnAdapterHalfOpenProbeSuccessCount = 0;
+            this.lastAnnAdapterHalfOpenProbeFailureCount = 0;
+            this.lastAnnAdapterLastSuccessAt = undefined;
+            this.lastAnnAdapterLastFailureAt = undefined;
+            this.lastAnnAdapterCircuitOpenedAt = undefined;
+            this.lastAnnAdapterLastRequestId = undefined;
+            this.lastAnnAdapterLastErrorCode = undefined;
+            this.lastAnnAdapterLastRetryAfterMs = 0;
+            this.lastAnnRepresentationVersion = undefined;
+            this.lastAnnEmbeddingModelId = undefined;
+            this.lastAnnEmbeddingDimension = undefined;
+            this.lastAnnIndexSignature = undefined;
+            this.lastAnnRepresentationStatus = 'unknown';
+            this.lastAnnRepresentationStatusReason = 'adapter_health_probe_failed';
+        }
+    }
+    resolveAccelerationRepresentationTelemetry(index) {
+        const expectedRepresentationVersion = LOCAL_VECTOR_REPRESENTATION_VERSION;
+        const expectedEmbeddingModelId = LOCAL_VECTOR_EMBEDDING_MODEL_ID;
+        const expectedEmbeddingDimension = Math.max(0, Math.floor(Number(index.documentFrequency.size || 0)));
+        const expectedIndexSignature = String(index.signature || '').trim().slice(0, 200);
+        const adapterId = String(this.lastAnnAdapterId || '').trim().toLowerCase();
+        const localAdapterPath = (!adapterId
+            || adapterId === LOCAL_VECTOR_ACCELERATION_ADAPTER_ID
+            || adapterId.includes('local-vector-acceleration'));
+        let representationVersion = this.lastAnnRepresentationVersion;
+        let embeddingModelId = this.lastAnnEmbeddingModelId;
+        let embeddingDimension = this.lastAnnEmbeddingDimension;
+        let indexSignature = this.lastAnnIndexSignature;
+        let representationStatus = this.lastAnnRepresentationStatus;
+        let representationStatusReason = this.lastAnnRepresentationStatusReason;
+        const mismatchReasons = [];
+        let comparableFields = 0;
+        if (representationVersion) {
+            comparableFields += 1;
+            if (representationVersion !== expectedRepresentationVersion) {
+                mismatchReasons.push('representation_version');
+            }
+        }
+        if (embeddingModelId) {
+            comparableFields += 1;
+            if (embeddingModelId !== expectedEmbeddingModelId) {
+                mismatchReasons.push('embedding_model_id');
+            }
+        }
+        if (typeof embeddingDimension === 'number' && embeddingDimension > 0) {
+            comparableFields += 1;
+            if (embeddingDimension !== expectedEmbeddingDimension) {
+                mismatchReasons.push('embedding_dimension');
+            }
+        }
+        if (indexSignature) {
+            comparableFields += 1;
+            if (indexSignature !== expectedIndexSignature) {
+                mismatchReasons.push('index_signature');
+            }
+        }
+        if (localAdapterPath) {
+            representationVersion = expectedRepresentationVersion;
+            embeddingModelId = expectedEmbeddingModelId;
+            embeddingDimension = expectedEmbeddingDimension;
+            indexSignature = expectedIndexSignature;
+            representationStatus = 'aligned';
+            representationStatusReason = 'local_adapter_representation_aligned';
+        }
+        else if (representationStatus === 'unknown') {
+            if (mismatchReasons.length > 0) {
+                representationStatus = 'mismatch';
+                representationStatusReason = `mismatch:${mismatchReasons.join(',')}`;
+            }
+            else if (comparableFields > 0) {
+                representationStatus = 'aligned';
+                representationStatusReason = representationStatusReason || 'adapter_representation_metadata_aligned';
+            }
+            else {
+                representationStatus = 'unknown';
+                representationStatusReason = representationStatusReason || 'adapter_representation_metadata_missing';
+            }
+        }
+        else if (representationStatus === 'mismatch' && !representationStatusReason) {
+            representationStatusReason = mismatchReasons.length > 0
+                ? `mismatch:${mismatchReasons.join(',')}`
+                : 'adapter_reported_mismatch';
+        }
+        else if (representationStatus === 'aligned' && !representationStatusReason) {
+            representationStatusReason = 'adapter_representation_metadata_aligned';
+        }
+        this.lastAnnRepresentationVersion = representationVersion || undefined;
+        this.lastAnnEmbeddingModelId = embeddingModelId || undefined;
+        this.lastAnnEmbeddingDimension = (typeof embeddingDimension === 'number'
+            && Number.isFinite(embeddingDimension)
+            && embeddingDimension > 0)
+            ? Math.floor(embeddingDimension)
+            : undefined;
+        this.lastAnnIndexSignature = indexSignature || undefined;
+        this.lastAnnRepresentationStatus = representationStatus;
+        this.lastAnnRepresentationStatusReason = representationStatusReason || undefined;
+        return {
+            representationVersion: this.lastAnnRepresentationVersion,
+            embeddingModelId: this.lastAnnEmbeddingModelId,
+            embeddingDimension: this.lastAnnEmbeddingDimension,
+            indexSignature: this.lastAnnIndexSignature,
+            representationStatus: this.lastAnnRepresentationStatus,
+            representationStatusReason: this.lastAnnRepresentationStatusReason,
+        };
+    }
+    async ensureIndex(atoms) {
+        const signature = computeLocalVectorSignature(atoms);
+        if (!this.invalidated && this.activeIndex && this.activeIndex.signature === signature) {
+            return this.activeIndex;
+        }
+        if (this.pendingIndexBuild && this.pendingIndexSignature === signature) {
+            return this.pendingIndexBuild;
+        }
+        this.pendingIndexSignature = signature;
+        this.pendingIndexBuild = this.loadOrBuildIndex(signature, atoms)
+            .finally(() => {
+            this.pendingIndexBuild = null;
+            this.pendingIndexSignature = null;
+        });
+        return this.pendingIndexBuild;
+    }
+    async loadOrBuildIndex(signature, atoms) {
+        const fromDisk = await this.tryLoadIndexFromDisk(signature);
+        if (fromDisk) {
+            this.activeIndex = fromDisk;
+            this.invalidated = false;
+            this.invalidationReason = undefined;
+            this.lastError = undefined;
+            return fromDisk;
+        }
+        const builtAt = new Date().toISOString();
+        const memoryIndex = this.buildIndexFromAtoms({
+            signature,
+            builtAt,
+            atoms,
+            loadedFromDisk: false,
+            persisted: false,
+        });
+        if (this.localVectorIndexPath) {
+            const persisted = await this.tryPersistIndexToDisk(memoryIndex);
+            memoryIndex.persisted = persisted;
+        }
+        this.activeIndex = memoryIndex;
+        this.invalidated = false;
+        this.invalidationReason = undefined;
+        if (memoryIndex.persisted || !this.localVectorIndexPath) {
+            this.lastError = undefined;
+        }
+        return memoryIndex;
+    }
+    buildIndexFromAtoms(params) {
+        const atomTokensById = new Map();
+        const documentFrequency = new Map();
+        params.atoms.forEach((atom) => {
+            const tokens = buildAtomSemanticTokens(atom);
+            atomTokensById.set(atom.id, tokens);
+            new Set(tokens).forEach((token) => {
+                documentFrequency.set(token, (documentFrequency.get(token) || 0) + 1);
+            });
+        });
+        const totalDocs = Math.max(1, params.atoms.length);
+        const entriesByAtomId = new Map();
+        atomTokensById.forEach((tokens, atomId) => {
+            const frequency = buildTokenFrequency(tokens);
+            const weights = buildTfIdfWeights(frequency, documentFrequency, totalDocs);
+            const signaturePrefix = computeSimHashPrefix(computeWeightedSimHash(weights), LOCAL_VECTOR_ANN_SIGNATURE_PREFIX_BITS);
+            entriesByAtomId.set(atomId, {
+                atomId,
+                tokens,
+                weights,
+                signaturePrefix,
+            });
+        });
+        const annStructures = buildLocalVectorAnnStructures(entriesByAtomId);
+        return {
+            signature: params.signature,
+            builtAt: params.builtAt,
+            atomCount: params.atoms.length,
+            documentFrequency,
+            entriesByAtomId,
+            tokenToAtomIds: annStructures.tokenToAtomIds,
+            signatureBuckets: annStructures.signatureBuckets,
+            loadedFromDisk: params.loadedFromDisk,
+            persisted: params.persisted,
+        };
+    }
+    buildSnapshot(index) {
+        const entries = Array.from(index.entriesByAtomId.values())
+            .map((entry) => ({
+            atomId: entry.atomId,
+            tokens: [...entry.tokens],
+            weights: toSerializableWeightEntries(entry.weights),
+        }))
+            .sort((left, right) => left.atomId.localeCompare(right.atomId));
+        const documentFrequency = Array.from(index.documentFrequency.entries())
+            .map(([token, count]) => [token, Math.max(0, Math.floor(Number(count) || 0))])
+            .filter(([token, count]) => Boolean(token) && count > 0)
+            .sort((left, right) => left[0].localeCompare(right[0]));
+        return {
+            schemaVersion: LOCAL_VECTOR_INDEX_SCHEMA_VERSION,
+            backendId: this.id,
+            signature: index.signature,
+            builtAt: index.builtAt,
+            atomCount: index.atomCount,
+            documentFrequency,
+            entries,
+        };
+    }
+    parseSnapshot(rawSnapshot) {
+        if (!rawSnapshot || typeof rawSnapshot !== 'object') {
+            return null;
+        }
+        const snapshot = rawSnapshot;
+        if (Number(snapshot.schemaVersion) !== LOCAL_VECTOR_INDEX_SCHEMA_VERSION
+            || String(snapshot.backendId || '') !== this.id
+            || !Array.isArray(snapshot.entries)
+            || !Array.isArray(snapshot.documentFrequency)) {
+            return null;
+        }
+        return {
+            schemaVersion: LOCAL_VECTOR_INDEX_SCHEMA_VERSION,
+            backendId: this.id,
+            signature: String(snapshot.signature || '').trim(),
+            builtAt: String(snapshot.builtAt || '').trim(),
+            atomCount: Math.max(0, Math.floor(Number(snapshot.atomCount || 0))),
+            documentFrequency: snapshot.documentFrequency,
+            entries: snapshot.entries,
+        };
+    }
+    snapshotToIndex(snapshot) {
+        const documentFrequency = new Map();
+        snapshot.documentFrequency.forEach((entry) => {
+            if (!Array.isArray(entry) || entry.length < 2) {
+                return;
+            }
+            const token = String(entry[0] || '').trim().toLowerCase();
+            const count = Math.max(0, Math.floor(Number(entry[1]) || 0));
+            if (!token || count <= 0) {
+                return;
+            }
+            documentFrequency.set(token, count);
+        });
+        const entriesByAtomId = new Map();
+        snapshot.entries.forEach((entry) => {
+            if (!entry || typeof entry !== 'object') {
+                return;
+            }
+            const atomId = String(entry.atomId || '').trim();
+            if (!atomId) {
+                return;
+            }
+            const tokens = Array.isArray(entry.tokens)
+                ? uniqueTokens(entry.tokens.map((token) => stemSemanticToken(token)).filter((token) => token.length > 0))
+                : [];
+            const weights = toWeightMap(entry.weights);
+            const signaturePrefix = computeSimHashPrefix(computeWeightedSimHash(weights), LOCAL_VECTOR_ANN_SIGNATURE_PREFIX_BITS);
+            entriesByAtomId.set(atomId, {
+                atomId,
+                tokens,
+                weights,
+                signaturePrefix,
+            });
+        });
+        const annStructures = buildLocalVectorAnnStructures(entriesByAtomId);
+        return {
+            signature: snapshot.signature,
+            builtAt: snapshot.builtAt || new Date().toISOString(),
+            atomCount: Math.max(snapshot.atomCount, entriesByAtomId.size),
+            documentFrequency,
+            entriesByAtomId,
+            tokenToAtomIds: annStructures.tokenToAtomIds,
+            signatureBuckets: annStructures.signatureBuckets,
+            loadedFromDisk: true,
+            persisted: true,
+        };
+    }
+    async tryLoadIndexFromDisk(signature) {
+        if (!this.localVectorIndexPath) {
+            return null;
+        }
+        try {
+            const content = await fs.promises.readFile(this.localVectorIndexPath, 'utf8');
+            const parsedSnapshot = this.parseSnapshot(JSON.parse(content));
+            if (!parsedSnapshot || parsedSnapshot.signature !== signature) {
+                return null;
+            }
+            const index = this.snapshotToIndex(parsedSnapshot);
+            return index;
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR') {
+                return null;
+            }
+            this.lastError = String(error?.message || error);
+            return null;
+        }
+    }
+    async tryPersistIndexToDisk(index) {
+        if (!this.localVectorIndexPath) {
+            return false;
+        }
+        const resolvedPath = path.resolve(this.localVectorIndexPath);
+        const directory = path.dirname(resolvedPath);
+        const tempPath = `${resolvedPath}.tmp`;
+        try {
+            await fs.promises.mkdir(directory, { recursive: true });
+            await fs.promises.writeFile(tempPath, JSON.stringify(this.buildSnapshot(index), null, 2), 'utf8');
+            await fs.promises.rename(tempPath, resolvedPath);
+            return true;
+        }
+        catch (error) {
+            this.lastError = String(error?.message || error);
+            return false;
+        }
+        finally {
+            try {
+                await fs.promises.unlink(tempPath);
+            }
+            catch (_cleanupError) {
+            }
+        }
+    }
+}
+exports.LocalVectorGraphQueryBackend = LocalVectorGraphQueryBackend;
+function normalizeGraphQueryBackendType(rawValue) {
+    const normalized = String(rawValue || '').trim().toLowerCase();
+    if (normalized === 'keyword_only' || normalized === 'keyword-only' || normalized === 'keyword') {
+        return 'keyword_only';
+    }
+    if (normalized === 'local_vector'
+        || normalized === 'local-vector'
+        || normalized === 'vector'
+        || normalized === 'semantic_vector'
+        || normalized === 'semantic-vector') {
+        return 'local_vector';
+    }
+    return 'local_hybrid';
+}
+function normalizeLocalVectorAccelerationFailureMode(rawValue) {
+    const normalized = String(rawValue || '').trim().toLowerCase();
+    if (normalized === 'fail_closed'
+        || normalized === 'fail-closed'
+        || normalized === 'strict'
+        || normalized === 'closed') {
+        return 'fail_closed';
+    }
+    return 'fail_open';
+}
+function createGraphQueryBackend(options = {}) {
+    const backend = normalizeGraphQueryBackendType(options.backend);
+    if (backend === 'keyword_only') {
+        return new KeywordOnlyGraphQueryBackend();
+    }
+    if (backend === 'local_vector') {
+        return new LocalVectorGraphQueryBackend({
+            localVectorIndexPath: options.localVectorIndexPath,
+            localVectorAnnPrefilterEnabled: options.localVectorAnnPrefilterEnabled,
+            localVectorAccelerationAdapter: options.localVectorAccelerationAdapter,
+            localVectorAccelerationFailureMode: normalizeLocalVectorAccelerationFailureMode(options.localVectorAccelerationFailureMode),
+            localVectorAccelerationRepresentationStrict: options.localVectorAccelerationRepresentationStrict === true,
+        });
+    }
+    return new LocalHybridGraphQueryBackend();
+}
+function listGraphQueryBackendCatalog() {
+    return GRAPH_QUERY_BACKEND_CATALOG.map((item) => ({
+        ...item,
+        aliases: [...item.aliases],
+    }));
+}