@planu/cli 0.27.0 → 0.29.0

package/dist/engine/tool-groups/group-manager.d.ts

@@ -0,0 +1,35 @@
+import type { ToolSlot, GroupStatus, GroupActivationResult } from '../../types/index.js';
+export declare class GroupManager {
+    private readonly groups;
+    private readonly enabledState;
+    private readonly toolMap;
+    private readonly notifyChanged;
+    constructor(toolMap: Map<string, ToolSlot>, notifyChanged: () => void);
+    /** Load groups from config, restore persisted state, apply to toolMap. */
+    init(): Promise<void>;
+    /** Enable all tools in a group. */
+    enableGroup(groupId: string): GroupActivationResult;
+    /** Disable all tools in a group. */
+    disableGroup(groupId: string): GroupActivationResult;
+    /** Toggle a group based on its current state. */
+    toggleGroup(groupId: string): GroupActivationResult;
+    /** Return runtime status for all groups, including a virtual 'ungrouped' group. */
+    getGroupStatus(): GroupStatus[];
+    /** Return the group ID that contains the given tool, or undefined. */
+    getToolGroup(toolName: string): string | undefined;
+    /** Count of tools currently enabled in toolMap. */
+    getActiveToolCount(): number;
+    /** Total tools registered in toolMap. */
+    getTotalToolCount(): number;
+    /** Load persisted group states from disk. */
+    private loadPersistedState;
+    /** Write current group states to disk. */
+    private persistState;
+    /** Apply enabled/disabled state to all tools in a group via toolMap. */
+    private applyGroupState;
+    /** Build a successful GroupActivationResult for a given group and action. */
+    private buildActivationResult;
+    /** Build a failed GroupActivationResult (group not found or locked). */
+    private buildErrorResult;
+}
+//# sourceMappingURL=group-manager.d.ts.map

package/dist/engine/tool-groups/group-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-manager.d.ts","sourceRoot":"","sources":["../../../src/engine/tool-groups/group-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,QAAQ,EACR,WAAW,EACX,qBAAqB,EAGtB,MAAM,kBAAkB,CAAC;AAQ1B,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuB;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAa;gBAE/B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,aAAa,EAAE,MAAM,IAAI;IAOrE,0EAA0E;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B,mCAAmC;IACnC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB;IAcnD,oCAAoC;IACpC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB;IAqBpD,iDAAiD;IACjD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB;IAuBnD,mFAAmF;IACnF,cAAc,IAAI,WAAW,EAAE;IAwC/B,sEAAsE;IACtE,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IASlD,mDAAmD;IACnD,kBAAkB,IAAI,MAAM;IAU5B,yCAAyC;IACzC,iBAAiB,IAAI,MAAM;IAI3B,6CAA6C;YAC/B,kBAAkB;IAUhC,0CAA0C;YAC5B,YAAY;IAY1B,wEAAwE;IACxE,OAAO,CAAC,eAAe;IAoBvB,6EAA6E;IAC7E,OAAO,CAAC,qBAAqB;IAgB7B,wEAAwE;IACxE,OAAO,CAAC,gBAAgB;CAezB"}

package/dist/engine/tool-groups/group-manager.js

@@ -0,0 +1,201 @@
+import { readJson, writeJson } from '../../storage/base-store.js';
+import toolGroupsConfigJson from '../../config/tool-groups.json' with { type: 'json' };
+const STATE_PATH = 'data/global/tool-group-state.json';
+const toolGroupsConfig = toolGroupsConfigJson;
+export class GroupManager {
+    groups;
+    enabledState;
+    toolMap;
+    notifyChanged;
+    constructor(toolMap, notifyChanged) {
+        this.toolMap = toolMap;
+        this.notifyChanged = notifyChanged;
+        this.groups = new Map();
+        this.enabledState = new Map();
+    }
+    /** Load groups from config, restore persisted state, apply to toolMap. */
+    async init() {
+        for (const def of toolGroupsConfig.groups) {
+            this.groups.set(def.id, def);
+            this.enabledState.set(def.id, def.defaultEnabled);
+        }
+        const persisted = await this.loadPersistedState();
+        for (const [groupId, enabled] of persisted) {
+            if (this.groups.has(groupId)) {
+                this.enabledState.set(groupId, enabled);
+            }
+        }
+        for (const [groupId, enabled] of this.enabledState) {
+            this.applyGroupState(groupId, enabled);
+        }
+    }
+    /** Enable all tools in a group. */
+    enableGroup(groupId) {
+        const group = this.groups.get(groupId);
+        if (!group) {
+            return this.buildErrorResult(groupId, 'enable', `Group '${groupId}' does not exist.`);
+        }
+        this.enabledState.set(groupId, true);
+        this.applyGroupState(groupId, true);
+        void this.persistState();
+        this.notifyChanged();
+        return this.buildActivationResult(groupId, 'enable');
+    }
+    /** Disable all tools in a group. */
+    disableGroup(groupId) {
+        const group = this.groups.get(groupId);
+        if (!group) {
+            return this.buildErrorResult(groupId, 'disable', `Group '${groupId}' does not exist.`);
+        }
+        if (group.locked) {
+            return this.buildErrorResult(groupId, 'disable', `Group '${groupId}' is locked and cannot be disabled.`);
+        }
+        this.enabledState.set(groupId, false);
+        this.applyGroupState(groupId, false);
+        void this.persistState();
+        this.notifyChanged();
+        return this.buildActivationResult(groupId, 'disable');
+    }
+    /** Toggle a group based on its current state. */
+    toggleGroup(groupId) {
+        const group = this.groups.get(groupId);
+        if (!group) {
+            return this.buildErrorResult(groupId, 'toggle', `Group '${groupId}' does not exist.`);
+        }
+        const currentlyEnabled = this.enabledState.get(groupId) ?? group.defaultEnabled;
+        if (!currentlyEnabled) {
+            return this.enableGroup(groupId);
+        }
+        if (group.locked) {
+            return this.buildErrorResult(groupId, 'toggle', `Group '${groupId}' is locked and cannot be disabled.`);
+        }
+        return this.disableGroup(groupId);
+    }
+    /** Return runtime status for all groups, including a virtual 'ungrouped' group. */
+    getGroupStatus() {
+        const statuses = [];
+        const groupedTools = new Set();
+        for (const [groupId, def] of this.groups) {
+            for (const tool of def.tools) {
+                groupedTools.add(tool);
+            }
+            const enabled = this.enabledState.get(groupId) ?? def.defaultEnabled;
+            statuses.push({
+                id: groupId,
+                name: def.name,
+                description: def.description,
+                enabled,
+                tools: [...def.tools],
+                toolCount: def.tools.length,
+            });
+        }
+        const ungroupedTools = [];
+        for (const toolName of this.toolMap.keys()) {
+            if (!groupedTools.has(toolName)) {
+                ungroupedTools.push(toolName);
+            }
+        }
+        if (ungroupedTools.length > 0) {
+            statuses.push({
+                id: 'ungrouped',
+                name: 'Ungrouped',
+                description: 'Tools not assigned to any defined group.',
+                enabled: true,
+                tools: ungroupedTools,
+                toolCount: ungroupedTools.length,
+            });
+        }
+        return statuses;
+    }
+    /** Return the group ID that contains the given tool, or undefined. */
+    getToolGroup(toolName) {
+        for (const [groupId, def] of this.groups) {
+            if (def.tools.includes(toolName)) {
+                return groupId;
+            }
+        }
+        return undefined;
+    }
+    /** Count of tools currently enabled in toolMap. */
+    getActiveToolCount() {
+        let count = 0;
+        for (const slot of this.toolMap.values()) {
+            if (slot.enabled) {
+                count++;
+            }
+        }
+        return count;
+    }
+    /** Total tools registered in toolMap. */
+    getTotalToolCount() {
+        return this.toolMap.size;
+    }
+    /** Load persisted group states from disk. */
+    async loadPersistedState() {
+        const defaultState = { states: [], updatedAt: '' };
+        const persisted = await readJson(STATE_PATH, defaultState);
+        const result = new Map();
+        for (const entry of persisted.states) {
+            result.set(entry.groupId, entry.enabled);
+        }
+        return result;
+    }
+    /** Write current group states to disk. */
+    async persistState() {
+        const states = [];
+        for (const [groupId, enabled] of this.enabledState) {
+            states.push({ groupId, enabled, lastChanged: new Date().toISOString() });
+        }
+        const payload = {
+            states,
+            updatedAt: new Date().toISOString(),
+        };
+        await writeJson(STATE_PATH, payload);
+    }
+    /** Apply enabled/disabled state to all tools in a group via toolMap. */
+    applyGroupState(groupId, enabled) {
+        const def = this.groups.get(groupId);
+        /* v8 ignore next 3 */
+        if (!def) {
+            return;
+        }
+        for (const toolName of def.tools) {
+            const slot = this.toolMap.get(toolName);
+            if (!slot) {
+                continue;
+            }
+            if (enabled) {
+                slot.enable();
+            }
+            else {
+                slot.disable();
+            }
+        }
+    }
+    /** Build a successful GroupActivationResult for a given group and action. */
+    buildActivationResult(groupId, action) {
+        const newState = this.enabledState.get(groupId) ?? false;
+        return {
+            success: true,
+            group: groupId,
+            action,
+            newState,
+            allGroups: this.getGroupStatus(),
+            totalActiveTools: this.getActiveToolCount(),
+            totalTools: this.getTotalToolCount(),
+        };
+    }
+    /** Build a failed GroupActivationResult (group not found or locked). */
+    buildErrorResult(groupId, action, _message) {
+        return {
+            success: false,
+            group: groupId,
+            action,
+            newState: this.enabledState.get(groupId) ?? false,
+            allGroups: this.getGroupStatus(),
+            totalActiveTools: this.getActiveToolCount(),
+            totalTools: this.getTotalToolCount(),
+        };
+    }
+}
+//# sourceMappingURL=group-manager.js.map

package/dist/engine/tool-groups/group-manager.js.map

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

package/dist/engine/vector-store/hnsw.d.ts

@@ -0,0 +1,37 @@
+import type { HNSWConfig, HNSWSearchCandidate, HNSWSerializedState } from '../../types/index.js';
+/**
+ * HNSW (Hierarchical Navigable Small World) index.
+ * For corpus < flatSearchThreshold, delegates to brute-force flat search.
+ */
+export declare class HNSWIndex {
+    private readonly config;
+    private readonly nodes;
+    private entryPoint;
+    private maxLayer;
+    constructor(config?: Partial<HNSWConfig>);
+    /** Number of indexed vectors. */
+    get size(): number;
+    /** Insert a vector into the index. */
+    insert(id: string, vector: number[]): void;
+    /** Remove a vector from the index. */
+    remove(id: string): boolean;
+    /** Search for the top-K nearest neighbors. Uses flat search for small corpus. */
+    search(query: number[], topK: number): HNSWSearchCandidate[];
+    /** Brute-force flat search -- guaranteed recall = 1.0. */
+    private flatSearch;
+    /** HNSW graph search -- approximate, O(log n). */
+    private hnswSearch;
+    /** Greedy walk to the closest node in a given layer. */
+    private greedyClosest;
+    /** Search a single layer, returning ef closest candidates. */
+    private searchLayer;
+    /** Prune connections to keep at most M neighbors. */
+    private pruneConnections;
+    /** Random level for a new node (geometric distribution). */
+    private randomLevel;
+    /** Export the index for serialization. */
+    exportState(): HNSWSerializedState;
+    /** Import the index from serialized form. */
+    importState(state: HNSWSerializedState): void;
+}
+//# sourceMappingURL=hnsw.d.ts.map

package/dist/engine/vector-store/hnsw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hnsw.d.ts","sourceRoot":"","sources":["../../../src/engine/vector-store/hnsw.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,UAAU,EAEV,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAG9B;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IACrD,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,QAAQ,CAAK;gBAET,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC;IASxC,iCAAiC;IACjC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,sCAAsC;IACtC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IA8D1C,sCAAsC;IACtC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IA2C3B,iFAAiF;IACjF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,mBAAmB,EAAE;IAa5D,0DAA0D;IAC1D,OAAO,CAAC,UAAU;IASlB,kDAAkD;IAClD,OAAO,CAAC,UAAU;IAelB,wDAAwD;IACxD,OAAO,CAAC,aAAa;IA6CrB,8DAA8D;IAC9D,OAAO,CAAC,WAAW;IAuEnB,qDAAqD;IACrD,OAAO,CAAC,gBAAgB;IAexB,4DAA4D;IAC5D,OAAO,CAAC,WAAW;IASnB,0CAA0C;IAC1C,WAAW,IAAI,mBAAmB;IASlC,6CAA6C;IAC7C,WAAW,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI;CAS9C"}

package/dist/engine/vector-store/hnsw.js

@@ -0,0 +1,294 @@
+// engine/vector-store/hnsw.ts — HNSW index for approximate nearest neighbor search.
+// SPEC-075 AC-02: Pure TypeScript, O(log n), recall > 0.9.
+import { cosineSimilarity } from './similarity.js';
+/**
+ * HNSW (Hierarchical Navigable Small World) index.
+ * For corpus < flatSearchThreshold, delegates to brute-force flat search.
+ */
+export class HNSWIndex {
+    config;
+    nodes = new Map();
+    entryPoint = null;
+    maxLayer = 0;
+    constructor(config) {
+        this.config = {
+            M: config?.M ?? 16,
+            efConstruction: config?.efConstruction ?? 200,
+            efSearch: config?.efSearch ?? 50,
+            flatSearchThreshold: config?.flatSearchThreshold ?? 1000,
+        };
+    }
+    /** Number of indexed vectors. */
+    get size() {
+        return this.nodes.size;
+    }
+    /** Insert a vector into the index. */
+    insert(id, vector) {
+        const level = this.randomLevel();
+        const layers = [];
+        for (let i = 0; i <= level; i++) {
+            layers.push(new Map());
+        }
+        const node = { id, vector, layers };
+        if (this.nodes.size === 0) {
+            this.nodes.set(id, node);
+            this.entryPoint = id;
+            this.maxLayer = level;
+            return;
+        }
+        // Navigate from top to insertion level
+        /* v8 ignore start -- entryPoint always set when nodes.size > 0 */
+        let currentId = this.entryPoint ?? id;
+        /* v8 ignore stop */
+        for (let lc = this.maxLayer; lc > level; lc--) {
+            currentId = this.greedyClosest(currentId, vector, lc);
+        }
+        // Insert at each layer from level down to 0
+        for (let lc = Math.min(level, this.maxLayer); lc >= 0; lc--) {
+            const neighbors = this.searchLayer(currentId, vector, this.config.efConstruction, lc);
+            const selected = neighbors.slice(0, this.config.M);
+            for (const nb of selected) {
+                const sim = nb.similarity;
+                node.layers[lc]?.set(nb.id, sim);
+                const nbNode = this.nodes.get(nb.id);
+                /* v8 ignore start -- neighbor always exists and has layers at lc */
+                if (nbNode && lc < nbNode.layers.length) {
+                    /* v8 ignore stop */
+                    nbNode.layers[lc]?.set(id, sim);
+                    // Prune if too many connections
+                    /* v8 ignore start -- lc always within nbNode.layers bounds */
+                    if ((nbNode.layers[lc]?.size ?? 0) > this.config.M * 2) {
+                        /* v8 ignore stop */
+                        this.pruneConnections(nbNode, lc);
+                    }
+                }
+            }
+            const first = selected[0];
+            /* v8 ignore start -- searchLayer always returns at least one result */
+            if (first) {
+                /* v8 ignore stop */
+                currentId = first.id;
+            }
+        }
+        this.nodes.set(id, node);
+        if (level > this.maxLayer) {
+            this.maxLayer = level;
+            this.entryPoint = id;
+        }
+    }
+    /** Remove a vector from the index. */
+    remove(id) {
+        const node = this.nodes.get(id);
+        if (!node) {
+            return false;
+        }
+        // Remove references from neighbors
+        for (let lc = 0; lc < node.layers.length; lc++) {
+            const layer = node.layers[lc];
+            /* v8 ignore start -- defensive: layers always exist within bounds */
+            if (!layer) {
+                continue;
+            }
+            /* v8 ignore stop */
+            for (const neighborId of layer.keys()) {
+                const neighbor = this.nodes.get(neighborId);
+                /* v8 ignore start -- neighbor always exists in graph */
+                if (neighbor && lc < neighbor.layers.length) {
+                    /* v8 ignore stop */
+                    neighbor.layers[lc]?.delete(id);
+                }
+            }
+        }
+        this.nodes.delete(id);
+        // Update entry point if needed
+        if (this.entryPoint === id) {
+            /* v8 ignore start -- Map.keys().next().value always defined when size > 0 */
+            this.entryPoint = this.nodes.size > 0 ? (this.nodes.keys().next().value ?? null) : null;
+            /* v8 ignore stop */
+            this.maxLayer = 0;
+            for (const n of this.nodes.values()) {
+                if (n.layers.length - 1 > this.maxLayer) {
+                    this.maxLayer = n.layers.length - 1;
+                    this.entryPoint = n.id;
+                }
+            }
+        }
+        return true;
+    }
+    /** Search for the top-K nearest neighbors. Uses flat search for small corpus. */
+    search(query, topK) {
+        if (this.nodes.size === 0) {
+            return [];
+        }
+        // Flat search for small corpus
+        if (this.nodes.size < this.config.flatSearchThreshold) {
+            return this.flatSearch(query, topK);
+        }
+        return this.hnswSearch(query, topK);
+    }
+    /** Brute-force flat search -- guaranteed recall = 1.0. */
+    flatSearch(query, topK) {
+        const results = [];
+        for (const node of this.nodes.values()) {
+            results.push({ id: node.id, similarity: cosineSimilarity(query, node.vector) });
+        }
+        results.sort((a, b) => b.similarity - a.similarity);
+        return results.slice(0, topK);
+    }
+    /** HNSW graph search -- approximate, O(log n). */
+    hnswSearch(query, topK) {
+        /* v8 ignore start -- entryPoint always set when called (size > 0) */
+        let currentId = this.entryPoint ?? '';
+        /* v8 ignore stop */
+        // Traverse from top layer to layer 1
+        for (let lc = this.maxLayer; lc > 0; lc--) {
+            currentId = this.greedyClosest(currentId, query, lc);
+        }
+        // Search at layer 0 with efSearch candidates
+        const candidates = this.searchLayer(currentId, query, this.config.efSearch, 0);
+        return candidates.slice(0, topK);
+    }
+    /** Greedy walk to the closest node in a given layer. */
+    greedyClosest(startId, query, layer) {
+        let bestId = startId;
+        const startNode = this.nodes.get(startId);
+        /* v8 ignore start -- defensive: startId always valid when called internally */
+        if (!startNode) {
+            return bestId;
+        }
+        /* v8 ignore stop */
+        let bestSim = cosineSimilarity(query, startNode.vector);
+        let improved = true;
+        while (improved) {
+            improved = false;
+            const node = this.nodes.get(bestId);
+            /* v8 ignore start -- defensive: bestId always valid in walk */
+            if (!node || layer >= node.layers.length) {
+                break;
+            }
+            /* v8 ignore stop */
+            const neighbors = node.layers[layer];
+            /* v8 ignore start -- defensive: layer within bounds */
+            if (!neighbors) {
+                break;
+            }
+            /* v8 ignore stop */
+            for (const neighborId of neighbors.keys()) {
+                const neighbor = this.nodes.get(neighborId);
+                /* v8 ignore start -- defensive: neighbor always valid in graph */
+                if (!neighbor) {
+                    continue;
+                }
+                /* v8 ignore stop */
+                const sim = cosineSimilarity(query, neighbor.vector);
+                if (sim > bestSim) {
+                    bestSim = sim;
+                    bestId = neighborId;
+                    improved = true;
+                }
+            }
+        }
+        return bestId;
+    }
+    /** Search a single layer, returning ef closest candidates. */
+    searchLayer(startId, query, ef, layer) {
+        const visited = new Set([startId]);
+        const startNode = this.nodes.get(startId);
+        /* v8 ignore start -- defensive: startId always valid */
+        if (!startNode) {
+            return [];
+        }
+        /* v8 ignore stop */
+        const candidates = [
+            { id: startId, similarity: cosineSimilarity(query, startNode.vector) },
+        ];
+        const queue = [startId];
+        while (queue.length > 0) {
+            const currentId = queue.shift();
+            /* v8 ignore start -- defensive: queue checked non-empty */
+            if (!currentId) {
+                continue;
+            }
+            /* v8 ignore stop */
+            const current = this.nodes.get(currentId);
+            /* v8 ignore start -- defensive: currentId always valid */
+            if (!current || layer >= current.layers.length) {
+                continue;
+            }
+            /* v8 ignore stop */
+            const neighbors = current.layers[layer];
+            /* v8 ignore start -- defensive: layer within bounds */
+            if (!neighbors) {
+                continue;
+            }
+            /* v8 ignore stop */
+            for (const neighborId of neighbors.keys()) {
+                if (visited.has(neighborId)) {
+                    continue;
+                }
+                visited.add(neighborId);
+                const neighbor = this.nodes.get(neighborId);
+                /* v8 ignore start -- defensive: neighbor always in graph */
+                if (!neighbor) {
+                    continue;
+                }
+                /* v8 ignore stop */
+                const sim = cosineSimilarity(query, neighbor.vector);
+                candidates.push({ id: neighborId, similarity: sim });
+                queue.push(neighborId);
+                // Keep candidate list bounded
+                /* v8 ignore start -- requires corpus > ef*2 neighbors from a single node */
+                if (candidates.length > ef * 2) {
+                    candidates.sort((a, b) => b.similarity - a.similarity);
+                    candidates.length = ef;
+                }
+                /* v8 ignore stop */
+            }
+        }
+        candidates.sort((a, b) => b.similarity - a.similarity);
+        return candidates.slice(0, ef);
+    }
+    /** Prune connections to keep at most M neighbors. */
+    pruneConnections(node, layer) {
+        const layerMap = node.layers[layer];
+        /* v8 ignore start -- defensive: layer always valid when called */
+        if (!layerMap) {
+            return;
+        }
+        /* v8 ignore stop */
+        const entries = [...layerMap.entries()].sort((a, b) => b[1] - a[1]);
+        layerMap.clear();
+        for (const [id, sim] of entries.slice(0, this.config.M)) {
+            layerMap.set(id, sim);
+        }
+    }
+    /** Random level for a new node (geometric distribution). */
+    randomLevel() {
+        const ml = 1 / Math.log(this.config.M);
+        let level = 0;
+        while (Math.random() < ml && level < 16) {
+            level++;
+        }
+        return level;
+    }
+    /** Export the index for serialization. */
+    exportState() {
+        const nodes = [...this.nodes.values()].map((n) => ({
+            id: n.id,
+            vector: n.vector,
+            layers: n.layers.map((l) => [...l.entries()]),
+        }));
+        return { nodes, entryPoint: this.entryPoint, maxLayer: this.maxLayer };
+    }
+    /** Import the index from serialized form. */
+    importState(state) {
+        this.nodes.clear();
+        for (const n of state.nodes) {
+            const layers = n.layers.map((l) => new Map(l));
+            this.nodes.set(n.id, { id: n.id, vector: n.vector, layers });
+        }
+        this.entryPoint = state.entryPoint;
+        this.maxLayer = state.maxLayer;
+    }
+}
+//# sourceMappingURL=hnsw.js.map

package/dist/engine/vector-store/hnsw.js.map

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

package/dist/engine/vector-store/similarity.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Compute cosine similarity between two vectors.
+ * Returns a value in [0, 1] where 1 means identical direction.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Compute Jaccard similarity between two binary-ish vectors.
+ * Treats non-zero values as "present". Returns value in [0, 1].
+ */
+export declare function jaccardSimilarity(a: number[], b: number[]): number;
+/**
+ * Combined similarity: weighted average of cosine and jaccard.
+ * Default weights: 0.8 cosine + 0.2 jaccard.
+ */
+export declare function combinedSimilarity(a: number[], b: number[], cosineWeight?: number): number;
+/**
+ * Normalize a vector to unit length (L2 norm).
+ * Returns a new array. If the vector is zero, returns a zero vector.
+ */
+export declare function normalizeVector(v: number[]): number[];
+//# sourceMappingURL=similarity.d.ts.map

package/dist/engine/vector-store/similarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.d.ts","sourceRoot":"","sources":["../../../src/engine/vector-store/similarity.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CA2BjE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CA4BlE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,YAAY,SAAM,GAAG,MAAM,CAIvF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAUrD"}