knodin 0.5.0

package/dist/src/doctor.js

@@ -0,0 +1,380 @@
+import child_process from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { detectSupportedAgents } from "./agent-integration.js";
+import { inspectLifecycleHealth } from "./lifecycle-health.js";
+import { trustedUpdateStatus } from "./update-policy.js";
+function defaultRun(command, args, options = {}) {
+    const result = child_process.spawnSync(command, args, {
+        encoding: "utf-8",
+        input: options.input,
+        timeout: 5_000,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? result.error?.message ?? "",
+    };
+}
+function managerEvidence(executable, env) {
+    const explicit = [
+        ["mise", env.MISE_DATA_DIR ?? env.MISE_ENV, "MISE_DATA_DIR or MISE_ENV is set"],
+        ["volta", env.VOLTA_HOME, "VOLTA_HOME is set"],
+        ["nvm", env.NVM_BIN ?? env.NVM_DIR, "NVM_BIN or NVM_DIR is set"],
+        ["fnm", env.FNM_DIR ?? env.FNM_MULTISHELL_PATH, "FNM_DIR or FNM_MULTISHELL_PATH is set"],
+        ["asdf", env.ASDF_DIR ?? env.ASDF_DATA_DIR, "ASDF_DIR or ASDF_DATA_DIR is set"],
+        ["homebrew", env.HOMEBREW_PREFIX, "HOMEBREW_PREFIX is set"],
+    ];
+    for (const [name, value, evidence] of explicit) {
+        if (value)
+            return { name, confidence: "high", evidence: [evidence] };
+    }
+    const lower = executable.toLowerCase();
+    for (const [needle, name] of [
+        ["/.local/share/mise/", "mise"],
+        ["/.volta/", "volta"],
+        ["/.nvm/", "nvm"],
+        ["/fnm", "fnm"],
+        ["/.asdf/", "asdf"],
+        ["/homebrew/", "homebrew"],
+    ]) {
+        if (lower.includes(needle)) {
+            return {
+                name,
+                confidence: "medium",
+                evidence: [`resolved executable path contains ${needle}; path heuristic only`],
+            };
+        }
+    }
+    return {
+        name: "unknown",
+        confidence: "low",
+        evidence: ["no manager-owned environment evidence; executable path alone is inconclusive"],
+    };
+}
+function symlinkChain(executable) {
+    const chain = [path.resolve(executable)];
+    for (let count = 0; count < 16; count++) {
+        const current = chain.at(-1);
+        if (!current)
+            break;
+        try {
+            if (!fs.lstatSync(current).isSymbolicLink()) {
+                const canonical = fs.realpathSync(current);
+                if (canonical !== current)
+                    chain.push(canonical);
+                break;
+            }
+            const target = fs.readlinkSync(current);
+            const resolved = path.resolve(path.dirname(current), target);
+            if (chain.includes(resolved))
+                break;
+            chain.push(resolved);
+        }
+        catch {
+            break;
+        }
+    }
+    return chain;
+}
+function executableCandidates(env) {
+    const candidates = [];
+    for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+        if (!directory)
+            continue;
+        const candidate = path.join(directory, process.platform === "win32" ? "knodin.cmd" : "knodin");
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            const resolved = fs.realpathSync(candidate);
+            if (!candidates.includes(resolved))
+                candidates.push(resolved);
+        }
+        catch {
+            // Not an executable candidate.
+        }
+    }
+    return candidates;
+}
+function runtimeTarget(command) {
+    const [executable, ...arguments_] = command;
+    if (!executable)
+        return "";
+    const basename = path.basename(executable).toLowerCase();
+    if (basename === "node" ||
+        basename === "node.exe" ||
+        basename === "bun" ||
+        basename === "tsx" ||
+        basename === "tsx.cmd") {
+        const valueFlags = new Set([
+            "--import",
+            "--loader",
+            "--experimental-loader",
+            "--require",
+            "-r",
+        ]);
+        for (let index = 0; index < arguments_.length; index++) {
+            const argument = arguments_[index];
+            if (valueFlags.has(argument)) {
+                index++;
+                continue;
+            }
+            if (argument.startsWith("-"))
+                continue;
+            return argument;
+        }
+    }
+    return executable;
+}
+function sanitizeRegistry(raw) {
+    const value = raw.trim();
+    try {
+        const parsed = new URL(value);
+        parsed.username = "";
+        parsed.password = "";
+        parsed.search = "";
+        parsed.hash = "";
+        return parsed.toString();
+    }
+    catch {
+        return "unknown";
+    }
+}
+function readAgentConfig(agent, file) {
+    try {
+        const content = fs.readFileSync(file, "utf-8");
+        if (agent === "claude" && path.basename(file) === ".claude.json") {
+            const present = content.includes('"knodin"');
+            return { agent, file, present, command: present ? "knodin" : null, args: ["serve"] };
+        }
+        if (file.endsWith(".toml")) {
+            const sectionStart = content.indexOf('[mcp_servers."knodin"]');
+            const sectionTail = sectionStart >= 0 ? content.slice(sectionStart) : "";
+            const nextSection = sectionTail.indexOf("\n[", 1);
+            const block = nextSection >= 0 ? sectionTail.slice(0, nextSection) : sectionTail;
+            const command = /^[ \t]*command[ \t]*=[ \t]*"([^"\r\n]+)"/m.exec(block)?.[1];
+            const args = /^[ \t]*args[ \t]*=[ \t]*\[([^\]]*)\]/m
+                .exec(block)?.[1]
+                ?.split(",")
+                .map((value) => value.trim().replace(/^"|"$/g, ""))
+                .filter(Boolean);
+            return {
+                agent,
+                file,
+                present: sectionStart >= 0,
+                command: command ?? null,
+                args: args ?? [],
+            };
+        }
+        const document = JSON.parse(content);
+        const registration = document.mcpServers?.knodin;
+        return {
+            agent,
+            file,
+            present: registration !== undefined,
+            command: typeof registration?.command === "string" ? registration.command : null,
+            args: Array.isArray(registration?.args)
+                ? registration.args.filter((value) => typeof value === "string")
+                : [],
+        };
+    }
+    catch {
+        return { agent, file, present: false, command: null, args: [] };
+    }
+}
+function configuredAgentCommands(repo) {
+    const candidates = [
+        { agent: "claude", file: ".mcp.json" },
+        { agent: "codex", file: ".codex/config.toml" },
+        { agent: "gemini", file: ".gemini/settings.json" },
+        { agent: "antigravity", file: ".agents/mcp_config.json" },
+    ];
+    return candidates.map(({ agent, file }) => readAgentConfig(agent, path.join(repo, file)));
+}
+function personalAgentCommands(homeDir) {
+    return [
+        readAgentConfig("claude", path.join(homeDir, ".claude.json")),
+        readAgentConfig("codex", path.join(homeDir, ".codex", "config.toml")),
+        readAgentConfig("gemini", path.join(homeDir, ".gemini", "settings.json")),
+        readAgentConfig("antigravity", path.join(homeDir, ".agents", "mcp_config.json")),
+    ];
+}
+function installedPackageVersion(executable) {
+    let directory = path.dirname(executable);
+    for (let depth = 0; depth < 6; depth++) {
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(directory, "package.json"), "utf-8"));
+            if (manifest.name === "knodin" && typeof manifest.version === "string")
+                return manifest.version;
+        }
+        catch {
+            // Continue toward the package root.
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return "unknown";
+}
+function managerRemediation(manager, version) {
+    if (manager === "mise")
+        return `mise use --global npm:knodin@${version}`;
+    if (manager === "volta")
+        return `volta install knodin@${version}`;
+    if (manager === "homebrew")
+        return "brew update && brew upgrade knodin";
+    if (manager === "nvm")
+        return `nvm use 24 && npm install --global --ignore-scripts knodin@${version}`;
+    if (manager === "fnm")
+        return `fnm use 24 && npm install --global --ignore-scripts knodin@${version}`;
+    if (manager === "asdf")
+        return `asdf set nodejs 24 && npm install --global --ignore-scripts knodin@${version}`;
+    return `npm install --global --ignore-scripts knodin@${version}`;
+}
+function parseMcp(output) {
+    const messages = output
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+    const initialize = messages.find(({ id }) => id === 1);
+    const tools = messages.find(({ id }) => id === 2);
+    const initializeResult = initialize?.result;
+    const toolsResult = tools?.result;
+    const names = (toolsResult?.tools ?? []).flatMap(({ name }) => typeof name === "string" ? [name] : []);
+    return {
+        initialize: initializeResult?.serverInfo ? "ok" : "failed",
+        toolsList: names.length > 0 ? "ok" : "failed",
+        serverVersion: typeof initializeResult?.serverInfo?.version === "string"
+            ? initializeResult.serverInfo.version
+            : undefined,
+        toolNames: names,
+    };
+}
+function mcpProbe(command, run) {
+    const input = [
+        JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2025-11-25",
+                capabilities: {},
+                clientInfo: { name: "knodin-doctor", version: "1" },
+            },
+        }),
+        JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }),
+        JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }),
+        "",
+    ].join("\n");
+    const [executable, ...args] = command;
+    if (!executable)
+        return { initialize: "failed", toolsList: "failed", toolNames: [], stderr: "no command" };
+    const result = run(executable, args, { input });
+    return { ...parseMcp(result.stdout), stderr: result.status === 0 ? undefined : result.stderr };
+}
+export async function diagnoseInstallation(repoPath, options) {
+    const repo = path.resolve(repoPath);
+    const env = options.env ?? process.env;
+    const run = options.run ?? defaultRun;
+    const executable = runtimeTarget(options.runtimeCommand);
+    const chain = symlinkChain(executable);
+    const candidates = executableCandidates(env);
+    const npmPrefix = run("npm", ["config", "get", "prefix"]);
+    const npmRegistry = run("npm", ["config", "get", "registry"]);
+    const mcp = mcpProbe(options.runtimeCommand, run);
+    const runtimeVersion = mcp.serverVersion;
+    const lifecycle = inspectLifecycleHealth(repo);
+    const detectedAgents = detectSupportedAgents();
+    const repositoryCommands = configuredAgentCommands(repo);
+    const personalCommands = personalAgentCommands(options.homeDir ?? os.homedir());
+    const clients = repositoryCommands
+        .filter(({ agent }) => options.client === undefined || options.client === agent)
+        .map((repository) => {
+        const personal = personalCommands.find(({ agent }) => agent === repository.agent);
+        const configured = repository.present || personal?.present === true;
+        return {
+            client: repository.agent,
+            detected: detectedAgents.includes(repository.agent),
+            repository,
+            personal,
+            server: {
+                initialize: mcp.initialize,
+                toolsList: mcp.toolsList,
+                toolNames: mcp.toolNames,
+            },
+            activeSessionExposure: "unknown",
+            note: repository.agent === "claude"
+                ? ".mcp.json is Claude project configuration, not a universal MCP registration."
+                : "Configuration presence does not prove that the active client session loaded it.",
+            remediation: configured
+                ? "Restart or reload the client, then verify its active tools list."
+                : `Run \`knodin configure --scope personal\` or \`knodin configure --scope team\` for ${repository.agent}.`,
+        };
+    });
+    const manager = managerEvidence(chain.at(-1) ?? executable, env);
+    const packageVersion = installedPackageVersion(chain.at(-1) ?? executable);
+    return {
+        schemaVersion: 1,
+        status: options.graph.status === "healthy" &&
+            mcp.initialize === "ok" &&
+            mcp.toolsList === "ok" &&
+            candidates.length <= 1
+            ? "healthy"
+            : "attention-required",
+        versions: {
+            package: packageVersion,
+            cli: runtimeVersion ?? "unknown",
+            source: options.currentVersion,
+            agree: runtimeVersion === options.currentVersion &&
+                (packageVersion === "unknown" || packageVersion === options.currentVersion),
+        },
+        runtime: {
+            node: process.version,
+            platform: process.platform,
+            arch: process.arch,
+        },
+        npm: {
+            prefix: npmPrefix.status === 0 ? npmPrefix.stdout.trim() : "unknown",
+            registry: npmRegistry.status === 0 ? sanitizeRegistry(npmRegistry.stdout) : "unknown",
+        },
+        manager,
+        executable: {
+            resolved: chain.at(-1) ?? executable,
+            chain,
+            candidates,
+            conflicts: candidates.filter((candidate) => candidate !== chain.at(-1)),
+        },
+        agents: {
+            detected: detectedAgents,
+            configuredCommands: repositoryCommands,
+            clients,
+        },
+        mcp,
+        lifecycle,
+        graph: options.graph,
+        update: trustedUpdateStatus({
+            currentVersion: options.currentVersion,
+            stateHome: options.cacheHome,
+            installMethod: manager.name,
+            env,
+        }),
+        remediation: {
+            manager: managerRemediation(manager.name, options.currentVersion),
+            duplicates: candidates.length > 1
+                ? "Remove only the unintended manager-owned installation, then rerun `knodin doctor`."
+                : null,
+            graph: options.graph.status === "healthy"
+                ? null
+                : "Run `knodin repair`, then `knodin status --deep`.",
+        },
+    };
+}

package/dist/src/engine/ann-hnsw.js

@@ -0,0 +1,271 @@
+/**
+ * Pure-TypeScript, dependency-free HNSW approximate nearest-neighbor index for
+ * the vector half of `search()` (R18).
+ *
+ * WHY THIS EXISTS, AND WHY IT IS OPT-IN. R16 removed R11(a)'s random-hyperplane
+ * LSH path after measuring it slower AND far less accurate (37% top-5 recall)
+ * than the exact cosine scan on a real 18.6k-symbol corpus. R11(a)'s only test
+ * passed because its 30-symbol fixture never exceeded the candidate floor, so it
+ * degenerated to an exact scan and never proved anything about real pruning.
+ *
+ * The durable lesson, now a hard gate: no approximate search path may engage BY
+ * DEFAULT without a measured >=95% top-10 recall vs the exact scan on a real
+ * corpus, with the method stated. This module is therefore OPT-IN ONLY, behind
+ * `RECKON_ANN=1`; `search()`'s default remains the exact scan at every corpus
+ * size. See scripts/ann-bench.ts for the recall/latency harness.
+ *
+ * MEASURED, GATE NOT CLEARED (so it stays opt-in). scripts/ann-bench.ts on
+ * /path/to/large-repository (18,639 symbols / 18,639 embeddings / schema 14), 20 queries,
+ * limit=10, two separate processes, one untimed warm-up, cold first-timed query
+ * excluded from the warm median, ef=200:
+ *   Exact scan:  warm median 38.11ms, min 34.97ms
+ *   ANN ef=200:  warm median 34.91ms, min 27.17ms
+ *   Recall vs exact: mean top-5 91.0%, mean top-10 88.0% (one query,
+ *     "resolve import path", scored 0%).
+ * 88.0% top-10 is far better than R11(a)'s LSH (43.3% top-10, AND slower) — the
+ * three queries LSH scored 0% on ("session token", "webhook handler", "metrics
+ * collection") here score 80/80/90% top-10 — but it misses the hard 95% floor,
+ * so the exact scan REMAINS the default. Recall is tunable via RECKON_ANN_EF (a
+ * larger ef trades latency for recall); default-engagement would require a fresh
+ * measurement clearing 95% at the corpus size where the path engages. Given the
+ * exact scan is 38ms at 18.6k and extrapolates sub-second to ~250k symbols,
+ * there is no corpus today where enabling this by default is worth doing.
+ *
+ * REMOVABILITY. The entire algorithm lives in this one file. It holds no stored
+ * state — the index is built in memory from the already-fetched embedding rows
+ * and cached per (repoPath, indexGeneration) by the caller, invalidated exactly
+ * like mapCache/flowsCache. If a future measurement finds it also fails the
+ * gate, deleting this file + the one guarded `if/else` seam + the cache Map in
+ * index.ts restores the exact scan with zero residue and no schema migration —
+ * the same clean-revert shape R11(a) had.
+ *
+ * DISTANCE KERNEL. Similarity is `embeddings.computeSimilarity` (dot product of
+ * L2-normalized vectors; higher = nearer), called via the namespace import so a
+ * degenerate "scan everything" implementation is observable at the integration
+ * layer (the gate test counts these calls and asserts real pruning).
+ */
+import * as embeddings from "./embeddings.js";
+const DEFAULT_M = 16;
+const DEFAULT_EF_CONSTRUCTION = 200;
+const DEFAULT_EF_SEARCH = 200;
+const DEFAULT_SEED = 0x9e3779b9;
+/** Deterministic PRNG so index topology (and thus recall) is reproducible. */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+class Hnsw {
+    nodes = [];
+    entryPoint = -1;
+    maxLevel = -1;
+    M;
+    Mmax0;
+    efConstruction;
+    mL;
+    rand;
+    constructor(params) {
+        this.M = params.M ?? DEFAULT_M;
+        this.Mmax0 = this.M * 2;
+        this.efConstruction = params.efConstruction ?? DEFAULT_EF_CONSTRUCTION;
+        this.mL = 1 / Math.log(this.M);
+        this.rand = mulberry32(params.seed ?? DEFAULT_SEED);
+    }
+    get size() {
+        return this.nodes.length;
+    }
+    randomLevel() {
+        return Math.floor(-Math.log(this.rand() || Number.MIN_VALUE) * this.mL);
+    }
+    sim(a, b) {
+        return embeddings.computeSimilarity(a, b);
+    }
+    insert(id, vec) {
+        const level = this.randomLevel();
+        const idx = this.nodes.length;
+        const node = {
+            id,
+            vec,
+            level,
+            neighbors: Array.from({ length: level + 1 }, () => []),
+        };
+        this.nodes.push(node);
+        if (this.entryPoint === -1) {
+            this.entryPoint = idx;
+            this.maxLevel = level;
+            return;
+        }
+        let ep = this.entryPoint;
+        // Descend from the top down to level+1 with a greedy 1-NN walk.
+        for (let lc = this.maxLevel; lc > level; lc--) {
+            ep = this.greedyDescend(vec, ep, lc).node;
+        }
+        // From min(level, maxLevel) down to 0, run the ef beam and connect.
+        for (let lc = Math.min(level, this.maxLevel); lc >= 0; lc--) {
+            const candidates = this.searchLayer(vec, [ep], this.efConstruction, lc).candidates;
+            const Mlevel = lc === 0 ? this.Mmax0 : this.M;
+            const selected = this.selectNeighbors(candidates, Mlevel);
+            node.neighbors[lc] = selected.slice();
+            // Add reciprocal links, pruning the neighbor's list back to its cap.
+            for (const nbr of selected) {
+                const nbrNode = this.nodes[nbr];
+                nbrNode.neighbors[lc].push(idx);
+                const cap = lc === 0 ? this.Mmax0 : this.M;
+                if (nbrNode.neighbors[lc].length > cap) {
+                    const rescored = nbrNode.neighbors[lc].map((n) => ({
+                        idx: n,
+                        score: this.sim(nbrNode.vec, this.nodes[n].vec),
+                    }));
+                    rescored.sort((x, y) => y.score - x.score);
+                    nbrNode.neighbors[lc] = rescored.slice(0, cap).map((r) => r.idx);
+                }
+            }
+            ep = candidates.length > 0 ? candidates[0].idx : ep;
+        }
+        if (level > this.maxLevel) {
+            this.maxLevel = level;
+            this.entryPoint = idx;
+        }
+    }
+    /**
+     * Greedy single-nearest walk at one layer. Returns the local optimum node
+     * index and the exact number of distance computations it performed (so the
+     * caller can report `stats.visited` as a true distance-call count).
+     */
+    greedyDescend(query, entry, level) {
+        let current = entry;
+        let currentScore = this.sim(query, this.nodes[current].vec);
+        let distanceComputations = 1;
+        let improved = true;
+        while (improved) {
+            improved = false;
+            for (const nbr of this.nodes[current].neighbors[level] ?? []) {
+                const s = this.sim(query, this.nodes[nbr].vec);
+                distanceComputations++;
+                if (s > currentScore) {
+                    currentScore = s;
+                    current = nbr;
+                    improved = true;
+                }
+            }
+        }
+        return { node: current, distanceComputations };
+    }
+    /**
+     * ef-wide best-first beam search at one layer from the given entry points.
+     * Returns the ef best candidates (sorted nearest-first) and the count of
+     * distance computations performed (the pruning instrumentation).
+     */
+    searchLayer(query, entries, ef, level) {
+        const visited = new Set();
+        // Max-heap-ish behavior via sorted arrays; corpora at this layer are small.
+        const candidateHeap = []; // frontier, best-first
+        const resultHeap = []; // ef best so far, worst-first
+        let distanceComputations = 0;
+        for (const e of entries) {
+            if (visited.has(e))
+                continue;
+            visited.add(e);
+            const s = this.sim(query, this.nodes[e].vec);
+            distanceComputations++;
+            candidateHeap.push({ idx: e, score: s });
+            resultHeap.push({ idx: e, score: s });
+        }
+        candidateHeap.sort((a, b) => b.score - a.score);
+        resultHeap.sort((a, b) => a.score - b.score);
+        while (candidateHeap.length > 0) {
+            const c = candidateHeap.shift();
+            if (!c)
+                break;
+            const worst = resultHeap[0];
+            if (worst && c.score < worst.score && resultHeap.length >= ef)
+                break;
+            for (const nbr of this.nodes[c.idx].neighbors[level] ?? []) {
+                if (visited.has(nbr))
+                    continue;
+                visited.add(nbr);
+                const s = this.sim(query, this.nodes[nbr].vec);
+                distanceComputations++;
+                const currentWorst = resultHeap[0];
+                if (resultHeap.length < ef || (currentWorst && s > currentWorst.score)) {
+                    insertSorted(candidateHeap, { idx: nbr, score: s }, true);
+                    insertSorted(resultHeap, { idx: nbr, score: s }, false);
+                    if (resultHeap.length > ef)
+                        resultHeap.shift();
+                }
+            }
+        }
+        const candidates = resultHeap.slice().sort((a, b) => b.score - a.score);
+        return { candidates, visited: distanceComputations };
+    }
+    selectNeighbors(candidates, M) {
+        return candidates
+            .slice()
+            .sort((a, b) => b.score - a.score)
+            .slice(0, M)
+            .map((c) => c.idx);
+    }
+    search(queryVec, efSearch, k) {
+        if (this.entryPoint === -1)
+            return { results: [], stats: { visited: 0 } };
+        const ef = Math.max(efSearch, k);
+        let ep = this.entryPoint;
+        let visited = 0;
+        for (let lc = this.maxLevel; lc > 0; lc--) {
+            // Upper-layer greedy-walk distance calls count toward the search budget.
+            const descent = this.greedyDescend(queryVec, ep, lc);
+            ep = descent.node;
+            visited += descent.distanceComputations;
+        }
+        const { candidates, visited: layer0Visited } = this.searchLayer(queryVec, [ep], ef, 0);
+        visited += layer0Visited;
+        const results = candidates
+            .slice(0, k)
+            .map((c) => ({ id: this.nodes[c.idx].id, score: c.score }));
+        return { results, stats: { visited } };
+    }
+}
+/** Inserts into a score-sorted array; `bestFirst` = descending, else ascending. */
+function insertSorted(arr, item, bestFirst) {
+    let lo = 0;
+    let hi = arr.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        const cmp = bestFirst ? arr[mid].score > item.score : arr[mid].score < item.score;
+        if (cmp)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    arr.splice(lo, 0, item);
+}
+/** Builds an in-memory HNSW index over the given embedding rows. */
+export function buildHnswIndex(rows, params = {}) {
+    const index = new Hnsw(params);
+    for (const row of rows)
+        index.insert(row.id, row.vec);
+    return index;
+}
+/**
+ * Whether the ANN path is engaged. OPT-IN ONLY: the exact scan is the default at
+ * every corpus size until the >=95% top-10 recall gate is measured-and-cleared
+ * at a corpus size where the path would actually engage (see module header).
+ */
+export function annEnabled() {
+    return process.env.RECKON_ANN === "1";
+}
+/** efSearch beam width, overridable via RECKON_ANN_EF (a benchmark knob). */
+export function annEfSearch() {
+    const raw = process.env.RECKON_ANN_EF;
+    if (raw) {
+        const n = Number.parseInt(raw, 10);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_EF_SEARCH;
+}