@noir-ai/context 1.0.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,763 @@
+import { Store, EmbedFn, FtsHit, VecHit } from '@noir-ai/store';
+export { EmbedFn, FtsHit, IndexDoc, Store, VecHit } from '@noir-ai/store';
+import { ProjectId } from '@noir-ai/core';
+export { ProjectId } from '@noir-ai/core';
+
+/**
+ * Logical source buckets a chunk can belong to. Reused by S7 (memory) —
+ * `'memory'` is reserved for that slice. The store treats `source` as a
+ * free-form string; this enum is the context package's contract for what a
+ * well-formed `source` value is.
+ */
+declare const SOURCES: readonly ["codebase", "docs", "spec", "memory"];
+type SourceKind = (typeof SOURCES)[number];
+/** Discriminant for {@link EmbedderConfig}. */
+type EmbedderKind = 'local' | 'remote' | 'ollama' | 'none';
+/**
+ * Local in-process embeddings via `@huggingface/transformers`
+ * (default `Xenova/all-MiniLM-L6-v2`, 384-dim → zero vec0 migration).
+ * The model is loaded lazily on first `embed()` call, never at import time.
+ */
+interface LocalEmbedderConfig {
+    kind: 'local';
+    /** HF repo id (defaults to `Xenova/all-MiniLM-L6-v2` in the factory). */
+    model?: string;
+}
+/**
+ * Opt-in remote embeddings (OpenAI / Voyage / Cohere). Provider-explicit:
+ * sends source text to a cloud endpoint. Vectors are L2-normalized and
+ * Matryoshka-truncated to `dim` client-side to stay vec0-compatible.
+ * NEVER the default (blueprint D6 — no silent paid calls).
+ */
+interface RemoteEmbedderConfig {
+    kind: 'remote';
+    /** Provider key, e.g. `'openai'` | `'voyage'` | `'cohere'`. */
+    provider: string;
+    /** API key. If absent the factory throws a clear "not configured" error. */
+    apiKey?: string;
+    /** Provider-specific model id. */
+    model: string;
+    /** Target dimensionality (must be 384 to match the vec0 table). */
+    dim: number;
+}
+/**
+ * Opt-in Ollama embeddings via a user-supplied base URL. Provider-explicit;
+ * never the default.
+ */
+interface OllamaEmbedderConfig {
+    kind: 'ollama';
+    /** Base URL of the Ollama server, e.g. `http://localhost:11434`. */
+    baseURL: string;
+    /** Ollama model tag. */
+    model: string;
+}
+/**
+ * Escape hatch: disable vectors entirely. `search` degrades to BM25-only
+ * (`degraded:true, mode:'bm25-only'`).
+ */
+interface NoneEmbedderConfig {
+    kind: 'none';
+}
+/**
+ * Discriminated configuration for the embedder factory (`createEmbedFn`,
+ * task t3). The core zod schema maps onto this via `resolveEmbedderConfig`
+ * (task t10) — that mapper is the only bridge between the two layers.
+ */
+type EmbedderConfig = LocalEmbedderConfig | RemoteEmbedderConfig | OllamaEmbedderConfig | NoneEmbedderConfig;
+/**
+ * Description of the active embedder, surfaced by `context_status` and
+ * recorded in store KV (`ctx:embedder`) so a model swap is detectable.
+ * For `kind:'none'`, `dim` is `0` and `model` is `undefined`.
+ */
+interface EmbedderInfo {
+    kind: EmbedderKind;
+    model?: string;
+    dim: number;
+}
+/** Metadata attached to every chunk (stored as `docs.meta` / `vec.meta`). */
+interface ChunkMeta {
+    /** Repo-relative or absolute path of the source file. */
+    path: string;
+    /**
+     * `sha256(path)` — stable parent-document id. The budget packer collapses
+     * duplicate parent-docs on this field so one file can't flood the results.
+     */
+    parentDocId: string;
+    /** 0-based position of this chunk within its parent file. */
+    chunkIndex: number;
+    /** Detected language / extension hint (e.g. `'typescript'`, `'markdown'`). */
+    language: string;
+    /** SHA-256 of this chunk's (post-identifier-explosion) content. */
+    sha256: string;
+}
+/**
+ * A unit of indexed content. One chunk → one `docs` row (FTS-synced) AND one
+ * `vec0` row under the SAME `id`, so RRF can join BM25 and kNN hits.
+ * `id` is `<sha256(path)>#chunk-<n>` (stable across re-indexing).
+ */
+interface Chunk {
+    id: string;
+    source: SourceKind;
+    content: string;
+    meta: ChunkMeta;
+}
+/** Pair of non-negative weights `[bm25Weight, kNNWeight]`; defaults `[0.5, 0.5]`. */
+type RRFWeights = [number, number];
+/**
+ * Retrieval mode actually used for a `search` call. `'hybrid'` = BM25 ∪ kNN
+ * fused by RRF; `'bm25-only'` = degraded fallback when the embedder is
+ * unavailable (`kind:'none'` or `embed()` threw).
+ */
+type SearchMode = 'hybrid' | 'bm25-only';
+/**
+ * Secondary metadata carried on a retriever hit. All optional: a BM25 hit
+ * reaches the retriever already enriched, while a kNN-only hit may only
+ * carry `id` + `source` until the retriever backfills the rest. The primary
+ * `path` / `parentDocId` fields live top-level on {@link RetrieverHit}
+ * (spec F6); this holds the remaining enrichment.
+ */
+interface RetrieverMeta {
+    language?: string;
+    sha256?: string;
+    chunkIndex?: number;
+}
+/**
+ * A single ranked result. `snippet` is FTS5 window-extracted
+ * (`snippet(docs_fts,0,'<<','>>','…',16)`) for BM25 hits, or a window around
+ * the chunk's first N tokens for kNN-only hits — never truncated mid-token.
+ *
+ * `path` and `parentDocId` are top-level (spec F6 enumerates the item as
+ * `{id, source, score, snippet, path, parentDocId}`): the retriever
+ * backfills them from the chunk's `meta` before the hit leaves `search()`,
+ * so they are always present at the public/MCP boundary.
+ */
+interface RetrieverHit {
+    id: string;
+    source: SourceKind;
+    /** RRF-fused rank score (rank-based; not a normalized similarity). */
+    score: number;
+    snippet: string;
+    /** Repo-relative or absolute path of the source file (backfilled from meta). */
+    path: string;
+    /** `sha256(path)` — stable parent-document id (backfilled from meta). */
+    parentDocId: string;
+    /** Secondary enrichment (language, sha256, chunkIndex). */
+    meta: RetrieverMeta;
+}
+/**
+ * Return value of `search`. `results` is packed greedily into `budgetTokens`
+ * (default ~4k): when the budget is exhausted before the ranked list,
+ * `truncated` is `true` and `consumedTokens` ~= `budgetTokens`.
+ */
+interface SearchResult {
+    results: RetrieverHit[];
+    /** Tokens accumulated across the returned snippets. */
+    consumedTokens: number;
+    /** `true` if the budget was hit before exhausting the ranked list. */
+    truncated: boolean;
+    /** `true` when the embedder was unavailable (BM25-only fallback, F8). */
+    degraded: boolean;
+    /** Retrieval mode actually used. */
+    mode: SearchMode;
+}
+/**
+ * Return value of `indexPaths`. Counts are mutually consistent: a chunk is
+ * either newly `indexed`, `skipped` (content-hash unchanged in KV), or part
+ * of a `deleted`/`failed` file. `totalChunks` is the running total tracked
+ * for the indexed paths after this call. `degraded` mirrors the search path
+ * (spec F10: `context_index -> {indexed, skipped, deleted, degraded}`).
+ */
+interface IndexResult {
+    /** Chunks newly written to `docs` + `vec0` this run. */
+    indexed: number;
+    /** Chunks whose SHA-256 matched KV (unchanged since last index). */
+    skipped: number;
+    /** Files removed since last index — their chunks + vectors were deleted. */
+    deleted: number;
+    /**
+     * True when the embedder was unavailable this run (docs indexed without
+     * vectors). Mirrors SearchResult.degraded / StoreStatus.degraded.
+     */
+    degraded: boolean;
+    /** Files that could not be read/parsed (binary, IO error, encoding). */
+    failed: number;
+    /** Total chunks now tracked for the indexed paths. */
+    totalChunks: number;
+}
+
+/** Default maximum estimated tokens per non-markdown chunk (spec DS-5). */
+declare const DEFAULT_CHUNK_MAX_TOKENS = 512;
+/** Default token overlap between consecutive non-markdown chunks (spec DS-5). */
+declare const DEFAULT_CHUNK_OVERLAP = 64;
+/**
+ * Cheap token estimate factor: ~1.3 tokens per whitespace-separated word (the
+ * canonical "1 word ≈ 1.3 tokens" heuristic). Good enough for windowing/budget
+ * packing without pulling in a tokenizer dep.
+ */
+declare const TOKEN_ESTIMATE_FACTOR = 1.3;
+/**
+ * Input to {@link chunkFile}. `path` + `content` are required; everything else
+ * has a sensible default. `maxTokens`/`overlap` flow from the resolved
+ * `context.chunk` config (task t10); `language`/`source` are inferred from the
+ * path when omitted so a bare `chunkFile({path, content})` call just works.
+ */
+interface ChunkOptions {
+    /** Repo-relative or absolute path of the source file. */
+    path: string;
+    /** Full text content of the file (the caller reads it; the chunker never does I/O). */
+    content: string;
+    /**
+     * Language hint (e.g. `'typescript'`, `'markdown'`). Inferred from the path
+     * extension when absent (see {@link inferLanguage}).
+     */
+    language?: string;
+    /**
+     * Override the inferred {@link SourceKind}. Defaults to `'docs'` for
+     * markdown and `'codebase'` otherwise; pass `'spec'`/`'memory'` when indexing
+     * those trees explicitly.
+     */
+    source?: SourceKind;
+    /** Max estimated tokens per code chunk (default {@link DEFAULT_CHUNK_MAX_TOKENS}). */
+    maxTokens?: number;
+    /** Token overlap between consecutive code chunks (default {@link DEFAULT_CHUNK_OVERLAP}). */
+    overlap?: number;
+}
+/**
+ * Split the identifiers in `text` into lowercase tokens, expanding
+ * camelCase / PascalCase / snake_case / kebab-case / digit boundaries.
+ *
+ * Examples:
+ *   `contextEngine`   → `context engine`
+ *   `ContextEngine`   → `context engine`
+ *   `XMLHttpRequest`  → `xml http request`
+ *   `myHTTPSConnection` → `my https connection`
+ *   `snake_case`/`kebab-case` → `snake case` / `kebab case`
+ *   `ctx:file:<path>` → `ctx file path`
+ *
+ * The stream is APPENDED to chunk content at index time (see
+ * {@link withIdentifierExplosion}) so identifier queries match under
+ * `porter unicode61` without a tokenizer migration. Pure/deterministic.
+ */
+declare function explodeIdentifiers(text: string): string;
+/**
+ * The canonical index-time content for a chunk: its clean text followed by the
+ * identifier-exploded token stream on a trailing line. Both the FTS row and
+ * the embedding are produced from this exact string (so identifier queries get
+ * a BM25 AND a semantic signal), and {@link chunkSha256} hashes this form to
+ * match the `ChunkMeta.sha256` contract ("post-identifier-explosion").
+ *
+ * `chunk.content` itself stays CLEAN (no explosion) so FTS5 window-extracted
+ * snippets read naturally — explosion is index-time-only (spec §7, DS-7).
+ */
+declare function withIdentifierExplosion(content: string): string;
+/**
+ * Cheap token-count proxy: ~1.3 tokens per whitespace-separated word (see
+ * {@link TOKEN_ESTIMATE_FACTOR}). Empty/whitespace-only text → 0. Used both
+ * for chunk windowing and (exported) for the retriever's budget packing.
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Best-effort language tag from the path extension (e.g. `.ts` → `'typescript'`).
+ * Unknown extensions fall back to `'text'`. Used as the `language` default and
+ * recorded per-file in the indexer's KV.
+ */
+declare function inferLanguage(path: string): string;
+/**
+ * Split a file's content into {@link Chunk}s.
+ *
+ * Markdown → heading-delimited sections; everything else → overlapping
+ * line/token windows. Each chunk's `id` is `<sha256(path)>#chunk-<n>` and
+ * `meta.parentDocId` is `sha256(path)` (stable across re-indexing), with
+ * `meta.sha256` over the post-identifier-explosion content (see
+ * {@link withIdentifierExplosion}). Empty content yields no chunks.
+ */
+declare function chunkFile(opts: ChunkOptions): Chunk[];
+
+/**
+ * User-facing context config shape — mirrors `NoirConfig['context']` (the zod
+ * block @noir-ai/core ships, slice S6). Declared locally with every field
+ * optional so this module type-checks WITHOUT a forward dependency on a core
+ * type (core never imports context — no cycle), AND so a config with no
+ * `context:` block (or a partial one) parses cleanly (AC-7 / NFR-6). The fully
+ * resolved zod output is structurally assignable to this permissive shape, so
+ * the mapper accepts `NoirConfig['context']` directly.
+ */
+interface ContextUserConfig {
+    embedder?: {
+        /** Default `'local'` (in-process transformers.js — offline, free, private). */
+        kind?: 'local' | 'remote' | 'ollama' | 'none';
+        /** Local HF repo id / remote provider model id / Ollama model tag. */
+        model?: string;
+        /** Remote provider key, e.g. `'openai'` (only meaningful when `kind:'remote'`). */
+        provider?: string;
+        /** Ollama base URL, e.g. `http://localhost:11434` (only when `kind:'ollama'`). */
+        baseURL?: string;
+        /** Target dimensionality (must be 384 to match the existing vec0 table). */
+        dim?: number;
+    };
+    /** Configured index roots (informational here; the daemon/indexer consume them). */
+    roots?: string[];
+    /** Default token budget for `search` (informational here; consumed by the retriever). */
+    budgetTokens?: number;
+}
+/**
+ * Resolve a user-facing {@link ContextUserConfig} into the discriminated
+ * {@link EmbedderConfig} the factory (`createEmbedFn`) consumes.
+ *
+ * - `undefined` / missing block ⇒ `{kind:'local'}` (the safe default — a config
+ *   with no `context:` block stays local-embedder-attempted, AC-7 / NFR-6).
+ * - `kind:'local'` ⇒ in-process transformers.js (model optional; factory
+ *   defaults to `Xenova/all-MiniLM-L6-v2`).
+ * - `kind:'none'` ⇒ vectors disabled; `search` degrades to BM25-only.
+ * - `kind:'remote'` / `'ollama'` ⇒ provider-explicit; the API key (remote) /
+ *   base URL (ollama) are resolved from env when absent in config. A missing
+ *   key is NOT an error here — the built embedder throws from `embed()` so the
+ *   engine degrades to BM25-only (F8) instead of crashing at construction.
+ *
+ * NEVER returns a remote/ollama config unless `kind` is explicitly that value —
+ * there is no path from the default to a silent paid call (blueprint D6).
+ */
+declare function resolveEmbedderConfig(ctx?: ContextUserConfig): EmbedderConfig;
+
+/** KV key holding the sorted list of indexed path keys. */
+declare const CTX_REGISTRY_KEY = "ctx:registry";
+/** KV key holding the recorded {@link EmbedderInfo} (model-swap detection). */
+declare const CTX_EMBEDDER_KEY = "ctx:embedder";
+/** Per-file record key prefix; the value is a {@link FileRecord} (or `null` tombstone). */
+declare const CTX_FILE_PREFIX = "ctx:file:";
+/**
+ * Per-file tracking record stored under {@link ctxFileKey}. `sha256` is the
+ * content-hash skip key; `chunkIds` lets a change/removal delete exactly the
+ * rows that belong to this file; `language` mirrors the chunker's inference.
+ */
+interface FileRecord {
+    /** SHA-256 of the file's UTF-8 content — the content-hash skip key (DS-4). */
+    sha256: string;
+    /** Chunk ids belonging to this file (for exact delete on change/removal). */
+    chunkIds: string[];
+    /** Detected language tag (mirrors the chunker's inference). */
+    language: string;
+}
+/** Build a `ctx:file:<key>` KV key. */
+declare function ctxFileKey(pathKey: string): string;
+/**
+ * Directory names never descended into during a walk (spec F1). Covers the
+ * common `.gitignore` entries without needing a gitignore parser — full
+ * `.gitignore` intersection (and `git diff --name-only` for incremental scope)
+ * is deferred v0 debt (grounds §10 indexing trigger).
+ */
+declare const SKIP_DIRS: Set<string>;
+/** True if the path's extension is a known binary type. */
+declare function isBinaryExt(pathOrName: string): boolean;
+/**
+ * True if `name` is a sensitive file that must NEVER be chunked, embedded, or
+ * indexed. Accepts a bare basename (`id_rsa`, `.env`, `cert.pem`) OR a
+ * `/`-separated relative path (`deploy/id_rsa`, `.aws/credentials`); the
+ * basename is extracted internally so prefix/suffix checks anchor on the file
+ * name rather than a path segment. Wired into the walk's skip decision
+ * alongside {@link isBinaryExt} so secrets never reach `indexDoc` / `upsertVec`.
+ */
+declare function isSensitive(name: string): boolean;
+/** Construction options for {@link createIndexer}. */
+interface IndexerOptions {
+    /** The daemon's store handle — the ONLY storage surface used (single writer). */
+    store: Store;
+    /** The resolved embedder. Failures here degrade the run (F8-style), never crash. */
+    embed: EmbedFn;
+    /** Active embedder description; recorded in KV for model-swap detection. */
+    info: EmbedderInfo;
+    /**
+     * Optional repository root. When provided, paths passed to
+     * {@link Indexer.indexPaths} are resolved against it AND stored repo-relative
+     * (portable `meta.path`, stable across checkouts). When omitted, paths resolve
+     * against `process.cwd()` and are stored absolute.
+     */
+    root?: string;
+}
+/** Per-call options for {@link Indexer.indexPaths}. */
+interface IndexPathOptions {
+    /** Chunk size override (flows from `context.chunk.maxTokens`). */
+    maxTokens?: number;
+    /** Chunk overlap override (flows from `context.chunk.overlap`). */
+    overlap?: number;
+    /**
+     * Override the source bucket for every file in this call (otherwise the
+     * chunker infers `'docs'` for markdown and `'codebase'` for everything else).
+     */
+    source?: SourceKind;
+}
+/** Return value of {@link Indexer.forget}. */
+interface ForgetResult {
+    /** Files removed from the index (their chunks + vectors were deleted). */
+    deleted: number;
+    /** Total chunks now tracked. */
+    totalChunks: number;
+}
+/** The indexer surface returned by {@link createIndexer}. */
+interface Indexer {
+    /**
+     * Walk + incrementally index `paths` (files or directories). Removed files
+     * under a re-scanned root are reconciled (deleted). Returns chunk/file counts
+     * + the `degraded` flag (spec F1/F3/F4, AC-1).
+     */
+    indexPaths(paths: string[], opts?: IndexPathOptions): Promise<IndexResult>;
+    /** Remove `paths` (files or dirs) from the index; deletes their chunks + vectors. */
+    forget(paths: string[]): Promise<ForgetResult>;
+    /** Drop every indexed chunk + vector, then re-index the registered roots from scratch. */
+    reindex(): Promise<IndexResult>;
+}
+/**
+ * Build an {@link Indexer} bound to a single store handle. Construction does no
+ * I/O and touches no KV — all work happens inside `indexPaths`/`forget`/`reindex`.
+ */
+declare function createIndexer(opts: IndexerOptions): Indexer;
+
+/**
+ * Default per-query hit cap applied to BOTH the BM25 and kNN legs so RRF has
+ * equal-depth lists to fuse (matches `Store.searchFt`'s default of 10; the
+ * store's `knn` default of 5 is intentionally raised here for fusion parity).
+ */
+declare const DEFAULT_SEARCH_LIMIT = 10;
+/** Default token budget for the greedy packer (spec §6 / config `budgetTokens`). */
+declare const DEFAULT_BUDGET_TOKENS = 4096;
+/**
+ * Default snippet window for kNN-only hydration, in (estimated) tokens. Mirrors
+ * the FTS5 `snippet(..., 16)` 16-token window used by `Store.searchFt` so a
+ * kNN-only hit's fallback window is the same width as a BM25 hit's window.
+ */
+declare const DEFAULT_SNIPPET_WINDOW_TOKENS = 16;
+/**
+ * Content + meta returned by the optional {@link RetrieverOptions.readDoc}
+ * hydrator. This is the shape needed to window-extract a snippet for a kNN-only
+ * hit (vec0 returns no meta, and the `Store` interface exposes no read-by-id).
+ */
+interface ChunkDoc {
+    /** Full chunk text (the hydrator decides the source: KV, a future getDoc, …). */
+    content: string;
+    /** The chunk's stored metadata, if available. */
+    meta?: ChunkMeta;
+}
+/** Tunables held for the life of the retriever (RRF + budget + hydration). */
+interface RetrieverOptions {
+    /** RRF constant `k` (defaults to {@link DEFAULT_RRF_K} = 60). */
+    k?: number;
+    /** RRF per-retriever weights `[bm25Weight, kNNWeight]` (default `[0.5, 0.5]`). */
+    weights?: RRFWeights;
+    /** Default token budget (overridable per `search()` call). */
+    budgetTokens?: number;
+    /** kNN-only snippet window width in tokens (default 16). */
+    snippetWindowTokens?: number;
+    /**
+     * Optional content/meta lookup for kNN-only hits. The store's `knn` returns
+     * only `{id, source, score}` (vec0 has no meta column) and the `Store`
+     * interface exposes no read-by-id, so without a hydrator a purely-semantic
+     * hit cannot be windowed. When provided and it hits, the chunk's content is
+     * prefix-windowed with `<<query-term>>` highlights (mirroring FTS5). When
+     * omitted or it misses, the hit is emitted with an empty snippet — degraded
+     * but ranked (F8). The engine (t8) wires this when a content source exists.
+     */
+    readDoc?: (id: string) => ChunkDoc | null;
+}
+/** Per-call options for {@link Retriever.search}. */
+interface SearchOptions {
+    /** Max hits requested from EACH leg before fusion (default 10). */
+    limit?: number;
+    /** Token budget for this call (defaults to the retriever's `budgetTokens`). */
+    budgetTokens?: number;
+    /** Restrict both legs to a single source bucket (passes through to the store). */
+    source?: string;
+}
+/** Constructor dependencies for {@link createRetriever}. */
+interface RetrieverDeps {
+    /** The store handle (the daemon's single-writer handle, or a read-only one). */
+    store: Store;
+    /** Query/chunk embedder. A throw on `embed(query)` ⇒ BM25-only fallback (F8). */
+    embed: EmbedFn;
+    /** Tunables + the optional kNN-only hydrator. */
+    opts?: RetrieverOptions;
+}
+/** The retriever surface returned by {@link createRetriever}. */
+interface Retriever {
+    search(query: string, opts?: SearchOptions): Promise<SearchResult>;
+}
+/**
+ * Build a best-effort prefix snippet for a kNN-only hit: the first
+ * `windowTokens` whitespace-separated words of `content`, with any word whose
+ * lowercase form is in the query-term set wrapped in `<<…>>` (mirroring FTS5's
+ * `<<match>>` marker convention so BM25 and kNN snippets read the same way).
+ *
+ * Unlike FTS5's `snippet()` this is a PREFIX window (FTS5 picks the densest
+ * window around match positions; vec0 gives us no match positions to center
+ * on). Content shorter than the window is returned whole (highlighted) — it is
+ * never padded or mid-word split.
+ */
+declare function windowSnippet(content: string, query: string, windowTokens: number): string;
+/**
+ * Build a hybrid retriever over an injected store + embedder.
+ *
+ * The retriever owns no state beyond its configured tunables; every `search`
+ * call is independent and side-effect-free (read-only against the store). It is
+ * the ONLY read path for context — `context_search` (t9) delegates here. Write
+ * (`indexDoc`/`upsertVec`) stays with the indexer/engine; the retriever never
+ * mutates the store.
+ */
+declare function createRetriever(deps: RetrieverDeps): Retriever;
+
+/**
+ * JSON returned by the `context_status` MCP tool (spec F11). Mirrors
+ * `StoreStatus` and adds the active embedder description + the indexed-file
+ * count (the size of the `ctx:registry` KV list the indexer maintains).
+ */
+interface ContextStatus {
+    ok: boolean;
+    /** Canonical project id (never a filesystem path — blueprint D6). */
+    projectId: string;
+    /** Rows in `docs` (live read off the single writer handle — no cache). */
+    docCount: number;
+    /** Rows in `vec0` (live read off the single writer handle — no cache). */
+    vecCount: number;
+    /** Number of files currently tracked in `ctx:registry`. */
+    indexedFiles: number;
+    /** Active embedder description (`kind:'none'` ⇒ `{kind:'none', dim:0}`). */
+    embedder: EmbedderInfo;
+    /**
+     * Persistent degradation flag: the store handle is read-only OR the embedder
+     * is disabled (`kind:'none'`). Per-query degradation lives on SearchResult.
+     */
+    degraded: boolean;
+}
+/** Construction options for {@link ContextEngine}. */
+interface ContextEngineOptions {
+    /**
+     * The daemon's store handle — the ONLY storage surface used (single writer).
+     * May be a read-only fallback handle; pass {@link storeDegraded} so `status()`
+     * can report it.
+     */
+    store: Store;
+    /**
+     * Project root. Paths passed to {@link ContextEngine.indexPaths} resolve
+     * against it and (because the indexer is root-bound) are stored repo-relative
+     * for portable `meta.path` across checkouts.
+     */
+    root: string;
+    /** Canonical project identifier (NEVER a filesystem path). */
+    projectId: ProjectId;
+    /**
+     * Resolved embedder config (from `resolveEmbedderConfig`). Construction never
+     * touches the network or native runtime — even `local` defers its dynamic
+     * import to the first `embed()` call.
+     */
+    embedderCfg: EmbedderConfig;
+    /**
+     * True when `store` was opened read-only (the daemon-down fallback). Threads
+     * the store's degraded story into the engine's persistent `degraded` flag so
+     * `status()` reports it and callers can branch on it.
+     */
+    storeDegraded?: boolean;
+}
+/**
+ * Noir's embedded hybrid retrieval engine — the `ctx.context` service.
+ *
+ * Constructed once per serve lifecycle (mirror `buildWorkflowEngine`) from the
+ * daemon's store handle + a resolved {@link EmbedderConfig}. Resolves the
+ * embedder, then owns the indexer (the only context writer) and the retriever
+ * (the only context reader). Public surface: {@link indexPaths}, {@link search},
+ * {@link status} — the three operations the `context_{index,search,status}` MCP
+ * tools (task t9) delegate to.
+ */
+declare class ContextEngine {
+    /** The daemon's single-writer store handle (possibly read-only). */
+    readonly store: Store;
+    /** Project root (paths resolve against this). */
+    readonly root: string;
+    /** Canonical project identifier. */
+    readonly projectId: ProjectId;
+    /** Description of the active embedder (surfaced by `status()`). */
+    readonly embedder: EmbedderInfo;
+    /**
+     * Persistent degradation flag (read-only store OR `kind:'none'`). Per-query
+     * degradation lives on {@link SearchResult}.
+     */
+    readonly degraded: boolean;
+    private readonly indexer;
+    private readonly retriever;
+    constructor(opts: ContextEngineOptions);
+    /**
+     * Incrementally index `paths` (files or directories) into the store. Delegates
+     * to the indexer (spec F1/F3/F4). The engine — through the indexer — is the
+     * ONLY context writer; the daemon stays the single writer via this handle.
+     */
+    indexPaths(paths: string[], opts?: IndexPathOptions): Promise<IndexResult>;
+    /**
+     * Hybrid search: BM25 ∪ cosine-kNN fused by RRF (k=60), collapsed by
+     * parent-doc, packed to a token budget with window-extracted snippets (spec
+     * F6/F7). Delegates to the retriever. The per-call `degraded`/`mode` on the
+     * returned {@link SearchResult} reflect THIS query's outcome (independent of
+     * the engine's persistent {@link degraded}).
+     */
+    search(query: string, opts?: SearchOptions): Promise<SearchResult>;
+    /**
+     * Snapshot the engine's state (spec F11; mirrors `buildStoreStatus`).
+     *
+     * `docCount`/`vecCount` are live reads off the single writer handle (no
+     * cache); `indexedFiles` is the size of the `ctx:registry` KV list maintained
+     * by the indexer; `embedder` describes the active provider; `degraded` is the
+     * persistent flag (read-only store OR `kind:'none'`).
+     */
+    status(): ContextStatus;
+}
+
+/**
+ * Build a deterministic embedder. The returned function maps each input string
+ * to a stable, unit-norm `EMBED_DIM`-wide `Float32Array` derived from a SHA-256
+ * hash of the text. Suitable for unit tests and as a BM25-companion fallback
+ * where a real vector signal is unavailable but the shape must be valid.
+ *
+ * @param dim output width (defaults to {@link EMBED_DIM} = 384)
+ */
+declare function fakeEmbedFn(dim?: number): EmbedFn;
+
+/** Default HF repo id — 384-dim, matches the vec0 table with zero migration. */
+declare const DEFAULT_LOCAL_MODEL = "Xenova/all-MiniLM-L6-v2";
+/**
+ * `~/.noir/models/` — user-global cache for downloaded ONNX weights.
+ * HOME-relative (NOT project `.noir/`) so projects stay portable. Centralized
+ * via `@noir-ai/core`'s `modelsDir()`; re-exported here so existing imports of
+ * `MODELS_DIR` keep resolving to the same path.
+ */
+declare const MODELS_DIR: string;
+interface LocalEmbedderOptions {
+    /** HF repo id (defaults to {@link DEFAULT_LOCAL_MODEL}). */
+    model?: string;
+}
+interface LocalEmbedder {
+    /** Embed function — loads the model lazily on first invocation. */
+    embed: EmbedFn;
+    /** Resolved model id. */
+    model: string;
+}
+/**
+ * Build a local in-process embedder. Construction is synchronous and never
+ * touches the network or the native runtime — the dynamic `import()` happens
+ * inside `embed()`, so `localEmbedder()` is safe to call at startup. Load
+ * failures surface as rejections from `embed()`; callers (retriever/engine)
+ * catch them and degrade to BM25-only (F8).
+ */
+declare function localEmbedder(opts?: LocalEmbedderOptions): LocalEmbedder;
+
+/**
+ * Fixed embedding width. Matches the S1 `vec0(float[384])` virtual table and
+ * the default `all-MiniLM-L6-v2` model. Remote/ollama vectors are truncated or
+ * required to be >= this width (see `remote.ts` / `ollama.ts`).
+ */
+declare const EMBED_DIM = 384;
+/**
+ * Return a unit-norm copy of `vec` (L2 normalization). The input is never
+ * mutated. Length is preserved: callers responsible for ensuring the vector is
+ * already `EMBED_DIM`-wide (truncate BEFORE normalizing — Matryoshka order
+ * matters; normalizing then truncating would distort directions).
+ *
+ * A zero-length or all-zero / non-finite input cannot be normalized; for those
+ * degenerate cases a fresh zeroed vector of the same length is returned rather
+ * than inventing directional signal or producing NaN. Real embedders never
+ * emit such vectors; this guard exists purely for robustness.
+ */
+declare function l2normalize(vec: Float32Array): Float32Array;
+
+interface OllamaEmbedderOptions {
+    /** Base URL of the Ollama server, e.g. `http://localhost:11434`. */
+    baseURL: string;
+    /** Ollama model tag, e.g. `nomic-embed-text`. */
+    model: string;
+    /** Target dimensionality (defaults to {@link EMBED_DIM}). */
+    dim?: number;
+}
+/**
+ * Build an Ollama embedder. Construction is synchronous and makes no network
+ * calls. Each `embed()` POSTs the source text to `<baseURL>/api/embeddings`.
+ */
+declare function ollamaEmbedder(opts: OllamaEmbedderOptions): EmbedFn;
+
+interface RemoteEmbedderOptions {
+    /** Provider key: `'openai'` | `'voyage'` | `'cohere'` (others fall back to the OpenAI shape). */
+    provider: string;
+    /** API key. If absent, `embed()` throws a clear "not configured" error. */
+    apiKey?: string;
+    /** Provider-specific model id. */
+    model: string;
+    /** Target dimensionality (must be 384 to match the vec0 table). */
+    dim?: number;
+}
+/**
+ * Build a remote (cloud) embedder. Construction is synchronous and makes no
+ * network calls. Each `embed()` call POSTs the source text to the provider.
+ */
+declare function remoteEmbedder(opts: RemoteEmbedderOptions): EmbedFn;
+
+/** Result of resolving an embedder config: a callable + describing metadata. */
+interface ResolvedEmbedder {
+    /** The `EmbedFn` the engine/retriever/indexer call. May throw on load/config failure. */
+    embed: EmbedFn;
+    /** Surfaced by `context_status` and recorded in store KV (`ctx:embedder`). */
+    info: EmbedderInfo;
+}
+/**
+ * Build an `{ embed, info }` pair from a config. Construction never touches the
+ * network or the native runtime — even `local` defers its dynamic import to the
+ * first `embed()` call. `kind:'none'` (and any load failure the caller lets
+ * propagate) yields BM25-only retrieval downstream (F8).
+ */
+declare function createEmbedFn(cfg: EmbedderConfig): ResolvedEmbedder;
+
+/**
+ * Canonical RRF constant (Cormack SIGIR'09). Larger values dampen the
+ * advantage of the top ranks.
+ */
+declare const DEFAULT_RRF_K = 60;
+/** Default per-retriever weights `[bm25Weight, kNNWeight]` (DS-3). */
+declare const DEFAULT_RRF_WEIGHTS: readonly [number, number];
+/** Options for {@link fuseRrf}. */
+interface FuseRrfOptions {
+    /**
+     * RRF constant `k`. Larger values flatten the top-rank advantage.
+     * Defaults to {@link DEFAULT_RRF_K} (60 — the canonical value).
+     */
+    k?: number;
+    /**
+     * Per-retriever weights `[bm25Weight, kNNWeight]`. Need not sum to 1: RRF is
+     * rank-based, not a normalized blend. Defaults to `[0.5, 0.5]`.
+     */
+    weights?: [number, number];
+}
+/** A fused result row from {@link fuseRrf}. */
+interface RrfResult {
+    /** Chunk id (the same id was indexed into both `docs` and `vec0`). */
+    id: string;
+    /** Source bucket from the originating hit (bm25's, else kNN's). */
+    source: string;
+    /**
+     * Fused RRF score `Σ w_i/(k+rank_i)`. Rank-based — NOT a normalized
+     * similarity; only meaningful for ordering within a single `fuseRrf` call.
+     */
+    score: number;
+}
+/**
+ * Fuse two pre-ranked retrieval lists via Reciprocal Rank Fusion.
+ *
+ * The input lists MUST be ordered best-first (the store returns them that way:
+ * `searchFt` ranks by BM25 relevance, `knn` by ascending distance). Position in
+ * the array IS the rank — the hits' raw `score` fields are intentionally
+ * ignored (DS-3: never sum raw BM25 + cosine).
+ *
+ * For each unique id: `score = w_bm25/(k + rank_bm25) + w_knn/(k + rank_knn)`,
+ * dropping a term when the id is absent from that list (no penalty, no
+ * normalization). Results sort by score descending; ties break by the doc's
+ * best (minimum) rank across both lists, then by first-seen insertion order
+ * (bm25 list first, then kNN-only docs) — all deterministic, so identical
+ * inputs always yield identical ordering (NFR-5).
+ *
+ * Pure and side-effect-free.
+ */
+declare function fuseRrf(bm25: ReadonlyArray<FtsHit>, knn: ReadonlyArray<VecHit>, opts?: FuseRrfOptions): RrfResult[];
+
+export { CTX_EMBEDDER_KEY, CTX_FILE_PREFIX, CTX_REGISTRY_KEY, type Chunk, type ChunkDoc, type ChunkMeta, type ChunkOptions, ContextEngine, type ContextEngineOptions, type ContextStatus, type ContextUserConfig, DEFAULT_BUDGET_TOKENS, DEFAULT_CHUNK_MAX_TOKENS, DEFAULT_CHUNK_OVERLAP, DEFAULT_LOCAL_MODEL, DEFAULT_RRF_K, DEFAULT_RRF_WEIGHTS, DEFAULT_SEARCH_LIMIT, DEFAULT_SNIPPET_WINDOW_TOKENS, EMBED_DIM, type EmbedderConfig, type EmbedderInfo, type EmbedderKind, type FileRecord, type ForgetResult, type FuseRrfOptions, type IndexPathOptions, type IndexResult, type Indexer, type IndexerOptions, type LocalEmbedder, type LocalEmbedderConfig, type LocalEmbedderOptions, MODELS_DIR, type NoneEmbedderConfig, type OllamaEmbedderConfig, type OllamaEmbedderOptions, type RRFWeights, type RemoteEmbedderConfig, type RemoteEmbedderOptions, type ResolvedEmbedder, type Retriever, type RetrieverDeps, type RetrieverHit, type RetrieverMeta, type RetrieverOptions, type RrfResult, SKIP_DIRS, SOURCES, type SearchMode, type SearchOptions, type SearchResult, type SourceKind, TOKEN_ESTIMATE_FACTOR, chunkFile, createEmbedFn, createIndexer, createRetriever, ctxFileKey, estimateTokens, explodeIdentifiers, fakeEmbedFn, fuseRrf, inferLanguage, isBinaryExt, isSensitive, l2normalize, localEmbedder, ollamaEmbedder, remoteEmbedder, resolveEmbedderConfig, windowSnippet, withIdentifierExplosion };