codestrate 0.6.2 → 0.6.3

package/dist/services/embedding.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Embedding client — LFM2.5-Embedding via llama-server HTTP API.
+ *
+ * Default mode is "auto": embedding-runtime downloads the GGUF model +
+ * llama-server binary and spawns a managed process. Document/query prefixes
+ * follow Liquid AI docs: "document: " / "query: ".
+ *
+ * Default endpoint: OpenAI-compatible POST /v1/embeddings on llama-server.
+ */
+import type { CIConfig } from "../types.js";
+export declare const DEFAULT_EMBEDDING_DIM = 1024;
+export declare const DEFAULT_EMBEDDING_URL = "http://127.0.0.1:18765";
+export declare const DOCUMENT_PREFIX = "document: ";
+export declare const QUERY_PREFIX = "query: ";
+export type EmbeddingRole = "query" | "document";
+export interface Embedder {
+    readonly dim: number;
+    readonly available: boolean;
+    embed(texts: string[], role: EmbeddingRole): Promise<number[][]>;
+    embedOne(text: string, role: EmbeddingRole): Promise<number[]>;
+}
+export declare function setEmbeddingRuntimeOverride(opts: {
+    url: string;
+    dim: number;
+}): void;
+export declare function clearEmbeddingRuntimeOverride(): void;
+export declare function getEmbeddingRuntimeOverride(): {
+    url: string;
+    dim: number;
+} | null;
+export declare class EmbedderUnavailableError extends Error {
+    constructor(message: string);
+}
+/** Cosine similarity in [0, 1] after normalizing (handles non-unit vectors). */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+export declare function l2Normalize(v: number[]): number[];
+/**
+ * OpenAI-compatible embeddings client for llama-server (`--embeddings`).
+ */
+export declare class HttpEmbedder implements Embedder {
+    readonly dim: number;
+    readonly available = true;
+    private readonly url;
+    private readonly model;
+    private readonly apiKey?;
+    private readonly timeoutMs;
+    private readonly batchSize;
+    constructor(opts?: {
+        url?: string;
+        model?: string;
+        apiKey?: string;
+        dim?: number;
+        timeoutMs?: number;
+        batchSize?: number;
+    });
+    embedOne(text: string, role: EmbeddingRole): Promise<number[]>;
+    embed(texts: string[], role: EmbeddingRole): Promise<number[][]>;
+    private embedBatch;
+}
+/** Deterministic mock embedder for tests (hash bag-of-words → fixed dim). */
+export declare class MockEmbedder implements Embedder {
+    readonly dim: number;
+    readonly available = true;
+    constructor(dim?: number);
+    embedOne(text: string, role: EmbeddingRole): Promise<number[]>;
+    embed(texts: string[], role: EmbeddingRole): Promise<number[][]>;
+    private hashEmbed;
+}
+/**
+ * Create embedder from CIConfig. Returns null when embedding is disabled.
+ * "auto" / "api" / "subprocess" all use HTTP once runtime is up.
+ * Call ensureEmbeddingRuntime() first for auto mode.
+ */
+export declare function createEmbedder(config: CIConfig): Embedder | null;
+/** True when embeddings should be attempted (not explicitly disabled). */
+export declare function isEmbeddingEnabled(config: CIConfig): boolean;
+/** Probe whether the embedding endpoint responds (best-effort). */
+export declare function probeEmbedder(embedder: Embedder): Promise<boolean>;
+//# sourceMappingURL=embedding.d.ts.map

package/dist/services/embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../src/services/embedding.ts"],"names":[],"mappings":"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"}

package/dist/services/embedding.js

@@ -0,0 +1,257 @@
+/**
+ * Embedding client — LFM2.5-Embedding via llama-server HTTP API.
+ *
+ * Default mode is "auto": embedding-runtime downloads the GGUF model +
+ * llama-server binary and spawns a managed process. Document/query prefixes
+ * follow Liquid AI docs: "document: " / "query: ".
+ *
+ * Default endpoint: OpenAI-compatible POST /v1/embeddings on llama-server.
+ */
+export const DEFAULT_EMBEDDING_DIM = 1024;
+export const DEFAULT_EMBEDDING_URL = "http://127.0.0.1:18765";
+export const DOCUMENT_PREFIX = "document: ";
+export const QUERY_PREFIX = "query: ";
+/** Set by embedding-runtime after managed/external server is healthy. */
+let runtimeOverride = null;
+export function setEmbeddingRuntimeOverride(opts) {
+    runtimeOverride = {
+        url: opts.url.replace(/\/$/, ""),
+        dim: opts.dim,
+    };
+}
+export function clearEmbeddingRuntimeOverride() {
+    runtimeOverride = null;
+}
+export function getEmbeddingRuntimeOverride() {
+    return runtimeOverride;
+}
+export class EmbedderUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EmbedderUnavailableError";
+    }
+}
+/** Cosine similarity in [0, 1] after normalizing (handles non-unit vectors). */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+export function l2Normalize(v) {
+    let n = 0;
+    for (const x of v)
+        n += x * x;
+    if (n === 0)
+        return v.slice();
+    const inv = 1 / Math.sqrt(n);
+    return v.map((x) => x * inv);
+}
+function withPrefix(text, role) {
+    const trimmed = text.trim();
+    if (role === "query") {
+        if (trimmed.startsWith(QUERY_PREFIX) || trimmed.startsWith("query:"))
+            return trimmed;
+        return QUERY_PREFIX + trimmed;
+    }
+    if (trimmed.startsWith(DOCUMENT_PREFIX) || trimmed.startsWith("document:"))
+        return trimmed;
+    return DOCUMENT_PREFIX + trimmed;
+}
+/**
+ * OpenAI-compatible embeddings client for llama-server (`--embeddings`).
+ */
+export class HttpEmbedder {
+    dim;
+    available = true;
+    url;
+    model;
+    apiKey;
+    timeoutMs;
+    batchSize;
+    constructor(opts = {}) {
+        this.url = (opts.url || DEFAULT_EMBEDDING_URL).replace(/\/$/, "");
+        this.model = opts.model || "LFM2.5-Embedding-350M";
+        this.apiKey = opts.apiKey;
+        this.dim = opts.dim ?? DEFAULT_EMBEDDING_DIM;
+        this.timeoutMs = opts.timeoutMs ?? 60_000;
+        this.batchSize = opts.batchSize ?? 16;
+    }
+    async embedOne(text, role) {
+        const [vec] = await this.embed([text], role);
+        if (!vec)
+            throw new EmbedderUnavailableError("Empty embedding response");
+        return vec;
+    }
+    async embed(texts, role) {
+        if (texts.length === 0)
+            return [];
+        const out = [];
+        for (let i = 0; i < texts.length; i += this.batchSize) {
+            const batch = texts.slice(i, i + this.batchSize);
+            const vectors = await this.embedBatch(batch, role);
+            out.push(...vectors);
+        }
+        return out;
+    }
+    async embedBatch(texts, role) {
+        const inputs = texts.map((t) => withPrefix(t, role));
+        const endpoint = `${this.url}/v1/embeddings`;
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiKey)
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(endpoint, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({
+                    input: inputs.length === 1 ? inputs[0] : inputs,
+                    model: this.model,
+                }),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                throw new EmbedderUnavailableError(`Embedding API ${res.status}: ${body.slice(0, 200) || res.statusText}`);
+            }
+            const json = (await res.json());
+            // OpenAI shape: { data: [{ embedding, index }, ...] }
+            if (Array.isArray(json.data)) {
+                const sorted = [...json.data].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+                return sorted.map((row) => {
+                    const emb = flattenEmbedding(row.embedding);
+                    if (emb.length === 0) {
+                        throw new EmbedderUnavailableError("Embedding API returned empty vector");
+                    }
+                    return l2Normalize(emb);
+                });
+            }
+            // Some llama.cpp builds return a bare embedding for single input
+            if (Array.isArray(json.embedding)) {
+                return [l2Normalize(flattenEmbedding(json.embedding))];
+            }
+            throw new EmbedderUnavailableError("Unrecognized embedding API response shape");
+        }
+        catch (err) {
+            if (err instanceof EmbedderUnavailableError)
+                throw err;
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new EmbedderUnavailableError(`Embedding API timeout after ${this.timeoutMs}ms (${endpoint})`);
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new EmbedderUnavailableError(`Embedding API request failed: ${msg}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+/** Deterministic mock embedder for tests (hash bag-of-words → fixed dim). */
+export class MockEmbedder {
+    dim;
+    available = true;
+    constructor(dim = 64) {
+        this.dim = dim;
+    }
+    async embedOne(text, role) {
+        const [v] = await this.embed([text], role);
+        return v;
+    }
+    async embed(texts, role) {
+        return texts.map((t) => this.hashEmbed(withPrefix(t, role)));
+    }
+    hashEmbed(text) {
+        const v = new Array(this.dim).fill(0);
+        const tokens = text.toLowerCase().split(/\W+/).filter(Boolean);
+        for (const tok of tokens) {
+            let h = 2166136261;
+            for (let i = 0; i < tok.length; i++) {
+                h ^= tok.charCodeAt(i);
+                h = Math.imul(h, 16777619);
+            }
+            const idx = Math.abs(h) % this.dim;
+            v[idx] = (v[idx] ?? 0) + 1;
+            // bigram shift
+            const idx2 = Math.abs(h >> 8) % this.dim;
+            v[idx2] = (v[idx2] ?? 0) + 0.5;
+        }
+        return l2Normalize(v);
+    }
+}
+function flattenEmbedding(emb) {
+    if (!emb)
+        return [];
+    if (Array.isArray(emb[0])) {
+        // token-level embeddings → mean pool
+        const rows = emb;
+        if (rows.length === 0)
+            return [];
+        const dim = rows[0].length;
+        const acc = new Array(dim).fill(0);
+        for (const row of rows) {
+            for (let i = 0; i < dim; i++)
+                acc[i] += row[i] ?? 0;
+        }
+        return acc.map((x) => x / rows.length);
+    }
+    return emb;
+}
+/**
+ * Create embedder from CIConfig. Returns null when embedding is disabled.
+ * "auto" / "api" / "subprocess" all use HTTP once runtime is up.
+ * Call ensureEmbeddingRuntime() first for auto mode.
+ */
+export function createEmbedder(config) {
+    const mode = config.embeddingMode ?? "auto";
+    if (mode === "none") {
+        return null;
+    }
+    if (process.env.CI_MCP_MOCK_EMBEDDER === "1") {
+        return new MockEmbedder(config.embeddingDim ?? DEFAULT_EMBEDDING_DIM);
+    }
+    const url = runtimeOverride?.url ??
+        config.embeddingApi?.url ??
+        DEFAULT_EMBEDDING_URL;
+    const dim = runtimeOverride?.dim ?? config.embeddingDim ?? DEFAULT_EMBEDDING_DIM;
+    return new HttpEmbedder({
+        url,
+        model: config.embeddingApi?.model ?? "LFM2.5-Embedding-350M",
+        apiKey: config.embeddingApi?.apiKey,
+        dim,
+    });
+}
+/** True when embeddings should be attempted (not explicitly disabled). */
+export function isEmbeddingEnabled(config) {
+    const env = process.env.CI_MCP_EMBEDDING_MODE?.trim().toLowerCase();
+    if (env === "none" || env === "0" || env === "off" || env === "false") {
+        return false;
+    }
+    if (process.env.CI_MCP_AUTO_EMBED === "0")
+        return false;
+    const mode = config.embeddingMode ?? "auto";
+    return mode !== "none";
+}
+/** Probe whether the embedding endpoint responds (best-effort). */
+export async function probeEmbedder(embedder) {
+    try {
+        const v = await embedder.embedOne("probe", "query");
+        return v.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=embedding.js.map

package/dist/services/embedding.js.map

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

package/dist/services/index-state.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Index lifecycle state — single source of readiness truth for the MCP server.
+ *
+ * Tools that need the symbol/graph index must consult this module instead of
+ * assuming empty results mean "nothing found". Failed or incomplete indexes
+ * surface as typed CiError metadata (partial/stale/retryable).
+ */
+import { type CiError } from "../types.js";
+export type IndexLifecycle = "not_started" | "indexing" | "ready" | "failed" | "empty";
+export interface IndexStateSnapshot {
+    lifecycle: IndexLifecycle;
+    /** True only when lifecycle === "ready" and index has usable data */
+    ready: boolean;
+    /** True when some data may be present but incomplete (e.g. graph failed) */
+    partial: boolean;
+    /** True when index is known stale vs HEAD (optional, set by status checks) */
+    stale: boolean;
+    errorMessage?: string;
+    symbolCount: number;
+    relationCount: number;
+    snapshotId?: string;
+    indexedAt?: string;
+}
+export declare function getIndexState(): IndexStateSnapshot;
+/** True once a successful index with symbols is available. */
+export declare function isIndexReady(): boolean;
+export declare function markIndexing(): void;
+export declare function markIndexReady(opts: {
+    symbolCount: number;
+    relationCount: number;
+    snapshotId?: string;
+    partial?: boolean;
+}): void;
+export declare function markIndexFailed(message: string, opts?: {
+    partial?: boolean;
+    symbolCount?: number;
+    relationCount?: number;
+    snapshotId?: string;
+}): void;
+export declare function markIndexEmpty(snapshotId?: string): void;
+export declare function markIndexStale(stale: boolean): void;
+/**
+ * Return a CiError when the index cannot serve reliable results.
+ * Returns null when ready (or partial-but-usable with symbols).
+ *
+ * Policy:
+ * - not_started / indexing → INDEX_NOT_READY (retryable)
+ * - failed with no symbols → INDEX_FAILED
+ * - failed with partial symbols → null + caller should attach partial meta
+ * - empty → INDEX_NOT_READY
+ */
+export declare function requireIndexReady(): CiError | null;
+/** Metadata to attach on successful tool responses for agent observability. */
+export declare function indexMeta(): {
+    indexLifecycle: IndexLifecycle;
+    partial: boolean;
+    stale: boolean;
+    snapshotId?: string;
+    symbolCount: number;
+};
+/**
+ * Build a standard MCP tool error payload from a CiError.
+ */
+export declare function ciErrorToolResult(err: CiError): {
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    structuredContent: Record<string, unknown>;
+    isError: true;
+};
+/** Test helper — reset singleton between unit tests. */
+export declare function _resetIndexStateForTests(): void;
+//# sourceMappingURL=index-state.d.ts.map

package/dist/services/index-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-state.d.ts","sourceRoot":"","sources":["../../src/services/index-state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,UAAU,GACV,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,cAAc,CAAC;IAC1B,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAC;IACf,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAWD,wBAAgB,aAAa,IAAI,kBAAkB,CAElD;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED,wBAAgB,YAAY,IAAI,IAAI,CAQnC;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,IAAI,CAcP;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IACL,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,IAAI,CAYN;AAED,wBAAgB,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAYxD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,GAAG,IAAI,CAmClD;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,IAAI;IAC3B,cAAc,EAAE,cAAc,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB,CAQA;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG;IAC/C,OAAO,EAAE,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1C,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,OAAO,EAAE,IAAI,CAAC;CACf,CAkBA;AAED,wDAAwD;AACxD,wBAAgB,wBAAwB,IAAI,IAAI,CAS/C"}

package/dist/services/index-state.js

@@ -0,0 +1,151 @@
+/**
+ * Index lifecycle state — single source of readiness truth for the MCP server.
+ *
+ * Tools that need the symbol/graph index must consult this module instead of
+ * assuming empty results mean "nothing found". Failed or incomplete indexes
+ * surface as typed CiError metadata (partial/stale/retryable).
+ */
+import { ciError } from "../types.js";
+let state = {
+    lifecycle: "not_started",
+    ready: false,
+    partial: false,
+    stale: false,
+    symbolCount: 0,
+    relationCount: 0,
+};
+export function getIndexState() {
+    return { ...state };
+}
+/** True once a successful index with symbols is available. */
+export function isIndexReady() {
+    return state.ready && state.lifecycle === "ready";
+}
+export function markIndexing() {
+    state = {
+        ...state,
+        lifecycle: "indexing",
+        ready: false,
+        partial: false,
+        errorMessage: undefined,
+    };
+}
+export function markIndexReady(opts) {
+    state = {
+        lifecycle: opts.symbolCount === 0 ? "empty" : "ready",
+        ready: opts.symbolCount > 0 && !opts.partial,
+        partial: opts.partial ?? false,
+        stale: false,
+        errorMessage: opts.partial
+            ? "Index is partial — graph population may be incomplete"
+            : undefined,
+        symbolCount: opts.symbolCount,
+        relationCount: opts.relationCount,
+        snapshotId: opts.snapshotId,
+        indexedAt: new Date().toISOString(),
+    };
+}
+export function markIndexFailed(message, opts) {
+    state = {
+        lifecycle: "failed",
+        ready: false,
+        partial: opts?.partial ?? false,
+        stale: false,
+        errorMessage: message,
+        symbolCount: opts?.symbolCount ?? state.symbolCount,
+        relationCount: opts?.relationCount ?? state.relationCount,
+        snapshotId: opts?.snapshotId ?? state.snapshotId,
+        indexedAt: state.indexedAt,
+    };
+}
+export function markIndexEmpty(snapshotId) {
+    state = {
+        lifecycle: "empty",
+        ready: false,
+        partial: false,
+        stale: false,
+        errorMessage: "Index is empty — no symbols extracted",
+        symbolCount: 0,
+        relationCount: 0,
+        snapshotId,
+        indexedAt: new Date().toISOString(),
+    };
+}
+export function markIndexStale(stale) {
+    state = { ...state, stale };
+}
+/**
+ * Return a CiError when the index cannot serve reliable results.
+ * Returns null when ready (or partial-but-usable with symbols).
+ *
+ * Policy:
+ * - not_started / indexing → INDEX_NOT_READY (retryable)
+ * - failed with no symbols → INDEX_FAILED
+ * - failed with partial symbols → null + caller should attach partial meta
+ * - empty → INDEX_NOT_READY
+ */
+export function requireIndexReady() {
+    switch (state.lifecycle) {
+        case "not_started":
+            return ciError("INDEX_NOT_READY", "Index has not started. Wait for auto-index or run ci_reindex (full profile).", { retryable: true });
+        case "indexing":
+            return ciError("INDEX_NOT_READY", "Index is still building. Retry shortly.", { retryable: true });
+        case "failed":
+            if (state.partial && state.symbolCount > 0) {
+                // Partial data available — callers may proceed with partial flag
+                return null;
+            }
+            return ciError("INDEX_FAILED", state.errorMessage ?? "Index build failed", { retryable: true, partial: state.partial, snapshotId: state.snapshotId });
+        case "empty":
+            return ciError("INDEX_NOT_READY", state.errorMessage ?? "Index is empty. Run ci_reindex (full profile) after indexing sources.", { retryable: true, snapshotId: state.snapshotId });
+        case "ready":
+            return null;
+        default:
+            return ciError("INTERNAL_ERROR", `Unknown index lifecycle: ${state.lifecycle}`);
+    }
+}
+/** Metadata to attach on successful tool responses for agent observability. */
+export function indexMeta() {
+    return {
+        indexLifecycle: state.lifecycle,
+        partial: state.partial,
+        stale: state.stale,
+        snapshotId: state.snapshotId,
+        symbolCount: state.symbolCount,
+    };
+}
+/**
+ * Build a standard MCP tool error payload from a CiError.
+ */
+export function ciErrorToolResult(err) {
+    const lines = [
+        `## Error: ${err.code}`,
+        err.message,
+        "",
+        `- retryable: ${err.retryable}`,
+        `- partial: ${err.partial}`,
+        `- stale: ${err.stale}`,
+    ];
+    if (err.snapshotId)
+        lines.push(`- snapshotId: ${err.snapshotId}`);
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: {
+            error: err,
+            ...indexMeta(),
+        },
+        isError: true,
+    };
+}
+/** Test helper — reset singleton between unit tests. */
+export function _resetIndexStateForTests() {
+    state = {
+        lifecycle: "not_started",
+        ready: false,
+        partial: false,
+        stale: false,
+        symbolCount: 0,
+        relationCount: 0,
+    };
+}
+//# sourceMappingURL=index-state.js.map

package/dist/services/index-state.js.map

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

package/dist/services/index-worker.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Index Worker — content-hash based incremental indexing with atomic generation swap.
+ *
+ * Architecture:
+ * - Each index run produces an immutable "generation" stored in SQLite.
+ * - Files are hashed (SHA-256 of content) to detect changes.
+ * - Only changed files are re-parsed; unchanged entries carry forward.
+ * - Generation pointer is atomically swapped on success.
+ * - Supports cancellation via AbortSignal.
+ *
+ * This eliminates: full rebuilds on every index, blocking event loop,
+ * and mixed-state reads during indexing.
+ */
+export interface IndexChange {
+    /** Files that were added or modified (need re-indexing) */
+    changed: string[];
+    /** Files that were deleted */
+    removed: string[];
+    /** Files that are unchanged (carried forward) */
+    unchanged: string[];
+}
+/**
+ * Compare current file hashes against stored hashes to determine
+ * which files need re-indexing.
+ */
+export declare function computeIndexPlan(allFiles: {
+    path: string;
+    language: string;
+}[]): IndexChange;
+export interface IndexGeneration {
+    id: number;
+    timestamp: string;
+    fileCount: number;
+    symbolCount: number;
+    relationCount: number;
+    contentHashes: Record<string, string>;
+}
+/**
+ * Create a new index generation, atomically swapping the active pointer.
+ *
+ * Process:
+ * 1. Start SQLite transaction
+ * 2. Parse changed files
+ * 3. Remove stale entries
+ * 4. Insert new entries + carry-forward hashes
+ * 5. Update generation pointer
+ * 6. Commit
+ */
+export declare function createGeneration(allFiles: {
+    path: string;
+    language: string;
+}[], plan: IndexChange, repoPath: string, commitSha: string, repoFingerprint: string, signal?: AbortSignal): Promise<IndexGeneration>;
+/**
+ * Full re-index (no incremental).
+ */
+export declare function fullReindex(allFiles: {
+    path: string;
+    language: string;
+}[], repoPath: string, commitSha: string, repoFingerprint: string, signal?: AbortSignal): Promise<IndexGeneration>;
+//# sourceMappingURL=index-worker.d.ts.map

package/dist/services/index-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-worker.d.ts","sourceRoot":"","sources":["../../src/services/index-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA6BH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iDAAiD;IACjD,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAAE,GAC7C,WAAW,CAgDb;AAID,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAAE,EAC9C,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC,CAuF1B;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAAE,EAC9C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC,CAO1B"}