@kb-labs/mind-core 2.93.0 → 2.96.0

package/dist/index.d.ts

@@ -1,402 +1,467 @@
-export * from '@kb-labs/mind-types';
-import { IStorage } from '@kb-labs/sdk';
+import { AgentSourceKind, IndexRequest, IndexResponse, SearchRequest, SearchResponse, QueryRequest, AgentResponse, ExploreRequest, ExploreResponse, ReindexRequest, DropRequest, DropResponse, SyncResponse, SyncListResponse, SyncStatusResponse, StatusResponse, HealthResponse, MindConfig, StageTrace, Trace, AgentWarning, AgentQueryMode, SnippetMode, AgentSource, SearchResult } from '@kb-labs/mind-contracts';
+import { M as MindServices } from './services-CdtgGHNc.js';
+import { IStorage, ILLM, ICache } from '@kb-labs/sdk';
 
 /**
- * @module @kb-labs/mind-core/error
- * Standardized error class for KB Labs Mind
- */
-declare class MindError extends Error {
-    code: string;
-    hint?: string | undefined;
-    meta?: unknown | undefined;
-    constructor(code: string, message: string, hint?: string | undefined, meta?: unknown | undefined);
+ * Adaptive source-file discovery via `globby` over the real filesystem.
+ *
+ * Reads the repo relative to `cwd` — NOT the platform `storage` adapter, which
+ * is a blob store that recurses into node_modules and chokes on pnpm symlink
+ * chains. Symlinks are not followed and dependency/build dirs are excluded.
+ *
+ * No language allowlist: we glob every file and KEEP whatever looks like source
+ * text, excluding only binaries, media, archives, data blobs, lockfiles and
+ * oversized/generated files. A new language (`.cs`, `.vue`, `.kt`, …) is indexed
+ * automatically — discovery adapts to the repo instead of being hand-curated.
+ *
+ * Returns paths relative to `cwd`.
+ */
+/** Scope the engine discovers against — config-driven include/exclude globs. */
+interface DiscoverScope {
+    /** Repo-relative roots/globs to index. Empty/undefined ⇒ whole repo. */
+    include?: string[];
+    /** Globs subtracted from the include set (added to the ignore list). */
+    exclude?: string[];
 }
-/**
- * Maps MindError codes to CLI exit codes
- */
-declare function getExitCode(err: MindError): number;
-/**
- * Error codes with their standard hints
- */
-declare const ERROR_HINTS: {
-    readonly MIND_NO_GIT: "Initialize git repository or run from a git repository";
-    readonly MIND_FS_TIMEOUT: "File system operation timed out - try increasing time budget";
-    readonly MIND_PARSE_ERROR: "Failed to parse file - check syntax and try again";
-    readonly MIND_PACK_BUDGET_EXCEEDED: "Context pack exceeds token budget - reduce content or increase budget";
-    readonly MIND_FORBIDDEN: "Operation not permitted - check file permissions";
-    readonly MIND_TIME_BUDGET: "Time budget exceeded - operation completed partially";
-    readonly MIND_BAD_FLAGS: "Invalid command line flags - check values and try again";
-    readonly MIND_INVALID_FLAG: "Invalid flag value - check format and try again";
-    readonly MIND_BUNDLE_TIMEOUT: "Bundle operation timed out - skipped bundle information";
-    readonly MIND_FEED_ERROR: "Mind feed operation failed - check logs for details";
-    readonly MIND_INIT_ERROR: "Mind initialization failed - check permissions and try again";
-    readonly MIND_UPDATE_ERROR: "Mind update operation failed - check logs for details";
-    readonly MIND_PACK_ERROR: "Mind pack operation failed - check logs for details";
-    readonly MIND_GIT_ERROR: "Git operation failed - check git repository status";
-    readonly MIND_INDEX_NOT_FOUND: "Mind indexes not found - run \"kb mind init\" first";
-    readonly MIND_INVALID_PATH: "Invalid file or directory path - check path exists and is accessible";
-    readonly MIND_DEPENDENCY_ERROR: "Dependency resolution failed - check package configuration";
-    readonly MIND_BUILD_ERROR: "Build operation failed - check configuration and try again";
-};
-type ErrorCode = keyof typeof ERROR_HINTS;
-/**
- * Create a MindError with standardized code and hint
- */
-declare function createMindError(code: ErrorCode, message: string, meta?: unknown): MindError;
-/**
- * Create a MindError from a generic error
- */
-declare function wrapError(error: unknown, code?: ErrorCode): MindError;
-/**
- * Check if an error is a MindError
- */
-declare function isMindError(error: unknown): error is MindError;
 
 /**
- * Pack and context types for KB Labs Mind
+ * Internal engine types (not wire contracts).
+ *
+ * A `Chunk` is the unit of indexing/retrieval. Chunks are stored two ways:
+ * - in the vector store (one `VectorRecord` per chunk, scoped by namespace=indexId)
+ *   for semantic search;
+ * - in a per-index `chunks.json` via `IStorage` as the corpus for BM25 and
+ *   listing/status.
  */
 
-type ContextSection = "intent_summary" | "product_overview" | "project_meta" | "api_signatures" | "recent_diffs" | "docs_overview" | "impl_snippets" | "configs_profiles";
-interface ContextBudget {
-    totalTokens: number;
-    caps: Partial<Record<ContextSection, number>>;
-    truncation: "start" | "middle" | "end";
+interface Chunk {
+    /** Stable id: `${path}#${startLine}-${endLine}`. */
+    id: string;
+    path: string;
+    startLine: number;
+    endLine: number;
+    text: string;
+    kind: AgentSourceKind;
 }
-type ContextSlice = "overview" | "api" | "diffs" | "snippets" | "configs" | "meta" | "docs";
-interface ContextPreset {
-    name: string;
-    weight: Partial<Record<ContextSlice, number>>;
+/** Metadata stored alongside each vector record. */
+interface ChunkMeta extends Record<string, unknown> {
+    path: string;
+    startLine: number;
+    endLine: number;
+    text: string;
+    kind: AgentSourceKind;
 }
-interface ITokenEstimator {
-    estimate(text: string): number;
-    truncate(text: string, maxTokens: number, mode: "start" | "middle" | "end"): string;
+/** Per-file bookkeeping. `hash` enables incremental (delta) re-indexing. */
+interface FileEntry {
+    chunks: number;
+    indexedAt: string;
+    /** Content hash; unchanged hash ⇒ file skipped on re-index. */
+    hash: string;
 }
+/** Persisted per-index corpus (source of truth for BM25 + listing). */
+interface IndexManifest {
+    indexId: string;
+    /** Chunks keyed by id. */
+    chunks: Chunk[];
+    /** Per-path bookkeeping for incremental sync. */
+    files: Record<string, FileEntry>;
+    updatedAt: string | null;
+}
+declare function chunkId(path: string, startLine: number, endLine: number): string;
+/** Derive a source kind from a file path. */
+declare function kindFromPath(path: string): AgentSourceKind;
 
 /**
- * Token estimation utilities for KB Labs Mind
+ * Sliding-window chunker (Phase 2 baseline; AST chunking is layered in Phase 3).
+ *
+ * Splits a file into line-aligned chunks of roughly `maxTokens` tokens with
+ * `overlapTokens` of overlap. Token count is approximated by whitespace words —
+ * good enough for windowing; real tokenization is not needed here.
  */
 
-/**
- * Default whitespace-aware token estimator
- * Algorithm: ~3.8-4.2 chars/token based on whitespace and code patterns
- */
-declare class DefaultTokenEstimator implements ITokenEstimator {
-    private readonly charsPerToken;
-    private readonly codeBonus;
-    private readonly punctuationWeight;
-    estimate(text: string): number;
-    truncate(text: string, maxTokens: number, mode: "start" | "middle" | "end"): string;
+interface ChunkOptions {
+    maxTokens: number;
+    overlapTokens: number;
 }
-/**
- * Default token estimator instance
- */
-declare const defaultTokenEstimator: DefaultTokenEstimator;
-/**
- * Estimate tokens using default strategy
- */
-declare function estimateTokens(text: string): number;
-/**
- * Truncate text to token limit using default strategy
- */
-declare function truncateToTokens(text: string, maxTokens: number, mode?: "start" | "middle" | "end"): string;
+declare function slidingWindowChunks(path: string, content: string, opts: ChunkOptions): Chunk[];
 
 /**
- * Hashing utilities for KB Labs Mind
- */
-/**
- * Compute SHA256 hash for string content
- */
-declare function sha256(content: string): string;
-/**
- * Compute SHA256 hash for Buffer content
- */
-declare function sha256Buffer(buffer: Buffer): string;
-/**
- * Compute SHA256 hash for file content (streaming for large files)
+ * Ingest pipeline: discover -> (hash-delta) -> chunk -> embed ->
+ * upsert(namespace=indexId), then persist the per-index manifest.
+ *
+ * Incremental by default: only files whose content hash changed since the last
+ * index are re-chunked/re-embedded; unchanged files keep their existing chunks
+ * (and vectors), removed files are pruned. `full` forces a clean rebuild.
  */
-declare function sha256File(filePath: string): Promise<string>;
+
+/** Staged progress events emitted during ingest (for CLI/REST progress UIs). */
+type IngestProgress = {
+    stage: 'discover';
+    files: number;
+} | {
+    stage: 'delta';
+    toIndex: number;
+    unchanged: number;
+    removed: number;
+} | {
+    stage: 'chunk';
+    chunks: number;
+} | {
+    stage: 'embed';
+    done: number;
+    total: number;
+} | {
+    stage: 'upsert';
+    count: number;
+} | {
+    stage: 'save';
+};
+interface IngestInput {
+    indexId: string;
+    /** Workspace root that source paths are resolved against. */
+    cwd: string;
+    /** Config-driven include/exclude globs for discovery. */
+    scope?: DiscoverScope;
+    chunk: ChunkOptions;
+    /** Use structure-aware chunking for code. */
+    ast: boolean;
+    /** Force a full rebuild instead of incremental delta. */
+    full?: boolean;
+    /** ISO timestamp for manifest bookkeeping (injectable for determinism). */
+    now: string;
+    /** Optional staged-progress sink (best-effort; never affects results). */
+    onProgress?: (event: IngestProgress) => void;
+}
+interface IngestResult {
+    filesIndexed: number;
+    chunks: number;
+    /** Files (re)embedded this run (new + changed). */
+    added: number;
+    updated: number;
+    /** Files removed from the index (gone from disk). */
+    removed: number;
+    /** Files skipped because their content hash was unchanged. */
+    unchanged: number;
+}
+declare function ingest(input: IngestInput, services: MindServices): Promise<IngestResult>;
 
 /**
- * Path utilities for KB Labs Mind
- */
-/**
- * Convert path to POSIX format (forward slashes)
- */
-declare function toPosix(filePath: string): string;
-/**
- * Convert POSIX path back to platform-specific format
- */
-declare function fromPosix(posixPath: string): string;
-/**
- * Find workspace root by looking for git repository or monorepo indicators
- * Searches up the directory tree from cwd
+ * Mind facade — the single object the plugin (CLI + REST) talks to.
+ *
+ * `createMind(services, config)` returns verbs that both the CLI commands and
+ * REST handlers call identically, so behaviour is shared by construction.
+ * Phase 2 ships `index` / `search` / `status`; `ask`, `sync`, `reindex` are
+ * layered in later phases.
  */
-declare function findWorkspaceRoot(cwd: string): Promise<string>;
+
+interface Mind {
+    index(req: IndexRequest, onProgress?: (event: IngestProgress) => void): Promise<IndexResponse>;
+    search(req: SearchRequest): Promise<SearchResponse>;
+    ask(req: QueryRequest): Promise<AgentResponse>;
+    explore(req: ExploreRequest): Promise<ExploreResponse>;
+    reindex(req: ReindexRequest): Promise<IndexResponse>;
+    drop(req: DropRequest): Promise<DropResponse>;
+    syncAdd(paths: string[], indexId?: string): Promise<SyncResponse>;
+    syncUpdate(paths: string[], indexId?: string): Promise<SyncResponse>;
+    syncDelete(paths: string[], indexId?: string): Promise<SyncResponse>;
+    syncList(indexId?: string): Promise<SyncListResponse>;
+    syncStatus(indexId?: string): Promise<SyncStatusResponse>;
+    status(indexId?: string): Promise<StatusResponse>;
+    health(): Promise<HealthResponse>;
+}
+interface CreateMindOptions {
+    /** Workspace root that source paths are resolved against (default: process.cwd()). */
+    cwd?: string;
+    /** Injectable clock for deterministic tests. */
+    now?: () => number;
+    /** Injectable ISO timestamp source for manifest bookkeeping. */
+    isoNow?: () => string;
+}
+declare function createMind(services: MindServices, config: MindConfig, options?: CreateMindOptions): Mind;
+
 /**
- * Make path relative to workspace root
+ * Pipeline primitive.
+ *
+ * Every stage is a pure function `(input, services) => output`. A `Tracer`
+ * times each stage and collects `StageTrace` entries so the full query flow
+ * (retrieve → fuse → rerank → verify → compress → synthesize) is observable.
+ * Modes (instant/auto/thinking) are just configs deciding which stages run —
+ * never separate code paths.
  */
-declare function makeRelativeToRoot(absolutePath: string, root: string): string;
+
+type Stage<I, O> = (input: I, services: MindServices) => Promise<O>;
+/** Monotonic clock; injectable so tests stay deterministic. */
+type Clock = () => number;
+/**
+ * Collects per-stage traces for one request. `run` times a stage and records
+ * its duration + output size.
+ */
+declare class Tracer {
+    private readonly requestId;
+    private readonly mode;
+    private readonly clock;
+    private readonly stages;
+    constructor(requestId: string, mode: string, clock?: Clock);
+    run<I, O>(stage: string, input: I, services: MindServices, fn: Stage<I, O>): Promise<O>;
+    /** Record a stage trace manually (for stages not wrapped by `run`). */
+    record(trace: StageTrace): void;
+    build(totalMs: number): Trace;
+}
+
 /**
- * Check if path should be ignored based on common patterns
+ * Structure-aware chunking for code (AST-lite).
+ *
+ * Splits a source file at top-level declaration boundaries (functions, classes,
+ * interfaces, etc.) so chunks align with logical units instead of arbitrary
+ * windows. Oversized blocks fall back to the sliding window. This is a
+ * dependency-free approximation of AST chunking; a tree-sitter backend can
+ * replace it later behind the same `chunkFile` entry without touching callers.
  */
-declare function shouldIgnorePath(filePath: string): boolean;
+
+declare function structuralChunks(path: string, content: string, opts: ChunkOptions): Chunk[];
+/** Dispatch: structure-aware for code when enabled, else sliding window. */
+declare function chunkFile(path: string, content: string, opts: ChunkOptions, ast: boolean): Chunk[];
 
 /**
- * Mathematical utility functions for KB Labs Mind
+ * BM25 keyword ranking over the in-memory chunk corpus.
+ *
+ * Self-contained Okapi BM25. Tokenization lowercases and splits on
+ * non-alphanumerics, additionally splitting camelCase and snake_case so code
+ * identifiers (`getUserId`, `user_id`) match natural-language queries.
  */
+
+interface Ranked {
+    id: string;
+    score: number;
+}
+declare function tokenize(text: string): string[];
+declare function bm25Search(chunks: Chunk[], query: string, limit: number): Ranked[];
+
 /**
- * Calculate cosine similarity between two vectors
- *
- * Cosine similarity measures the cosine of the angle between two vectors,
- * producing a value between -1 and 1, where:
- * - 1 means vectors point in the same direction (identical)
- * - 0 means vectors are orthogonal (no similarity)
- * - -1 means vectors point in opposite directions
- *
- * @param a - First vector (array of numbers)
- * @param b - Second vector (array of numbers)
- * @returns Similarity score [0-1], or 0 if vectors have different lengths or zero magnitudes
+ * Reciprocal Rank Fusion (RRF) with intent-adaptive weights.
  *
- * @example
- * ```typescript
- * const similarity = cosineSimilarity([1, 2, 3], [4, 5, 6]);
- * console.log(similarity); // ~0.974
- * ```
+ * Fuses ranked lists by `weight * 1/(k + rank)`. Weights shift the balance
+ * between the semantic (vector) and keyword (BM25) lists based on query intent.
  */
-declare function cosineSimilarity(a: number[], b: number[]): number;
+
+type QueryIntent = 'lookup' | 'concept' | 'architecture';
+/** Which retrieval signal surfaced a result — the "why" + proof-of-value vs grep. */
+type MatchedBy = 'lexical' | 'semantic' | 'both';
+interface WeightedList {
+    ranked: Ranked[];
+    weight: number;
+    /** Provenance label for this list (so the fused result knows where it came from). */
+    label?: Exclude<MatchedBy, 'both'>;
+}
+interface FusedRanked extends Ranked {
+    matchedBy: MatchedBy;
+}
+/** Vector/BM25 weighting per intent (vector favored for meaning, BM25 for exact terms). */
+declare function intentWeights(intent?: QueryIntent): {
+    vector: number;
+    bm25: number;
+};
+declare function rrfFuse(lists: WeightedList[], k: number): FusedRanked[];
+
 /**
- * Calculate dot product of two vectors
- *
- * @param a - First vector
- * @param b - Second vector
- * @returns Dot product, or 0 if vectors have different lengths
- *
- * @example
- * ```typescript
- * const dot = dotProduct([1, 2, 3], [4, 5, 6]);
- * console.log(dot); // 32
- * ```
+ * Retrieval pipeline: BM25 (over manifest corpus) + vector (platform store),
+ * fused with intent-adaptive RRF, mapped back to chunks.
  */
-declare function dotProduct(a: number[], b: number[]): number;
+
+interface RetrieveInput {
+    text: string;
+    indexId: string;
+    limit: number;
+    intent?: QueryIntent;
+    rrfK: number;
+    /** HyDE: embed an LLM-generated hypothetical doc for the vector search. */
+    hyde?: boolean;
+    /** Query expansion: append LLM-suggested related terms to the BM25 query. */
+    expand?: boolean;
+}
+interface RankedChunk {
+    chunk: Chunk;
+    /** Fused RRF score (best first). */
+    score: number;
+    /** Which signal surfaced this chunk (lexical/semantic/both) — provenance. */
+    matchedBy: MatchedBy;
+}
+interface RetrieveOutput {
+    /** Fused, ranked chunks (best first), truncated to `limit`. */
+    ranked: RankedChunk[];
+    /** Raw cosine confidence proxy from the vector list (top-3 avg). */
+    confidence: number;
+    /** Share of returned results found semantic-only (grep would miss them). */
+    semanticWinRate: number;
+}
+declare function retrieve(input: RetrieveInput, services: MindServices): Promise<RetrieveOutput>;
+
 /**
- * Calculate magnitude (L2 norm) of a vector
+ * Heuristic reranking of fused candidates.
  *
- * @param vec - Input vector
- * @returns Magnitude (Euclidean length)
+ * Lightweight, deterministic signals layered on the fused RRF score:
+ * - exact query-term coverage in the chunk text (keyword precision)
+ * - identifier hit: a query token appearing verbatim (good for code lookups)
  *
- * @example
- * ```typescript
- * const mag = magnitude([3, 4]);
- * console.log(mag); // 5
- * ```
+ * An optional LLM reranker can be layered later; this heuristic pass is always
+ * available and needs no model.
  */
-declare function magnitude(vec: number[]): number;
+
+declare function rerank(ranked: RankedChunk[], query: string): RankedChunk[];
+
 /**
- * Normalize a vector to unit length
+ * Semantic-ish dedup of ranked chunks via token-set Jaccard similarity.
  *
- * @param vec - Input vector
- * @returns Normalized vector (magnitude = 1), or original if magnitude is 0
- *
- * @example
- * ```typescript
- * const normalized = normalize([3, 4]);
- * console.log(normalized); // [0.6, 0.8]
- * ```
+ * Keeps the highest-ranked chunk and drops later near-duplicates (e.g. the same
+ * code re-surfaced by both BM25 and vector lists, or overlapping windows).
+ * Operates on the small post-fusion list, so O(n²) is fine.
  */
-declare function normalize(vec: number[]): number[];
+
+declare function dedupRanked(ranked: RankedChunk[], threshold?: number): RankedChunk[];
 
 /**
- * Base class for file-based stores with rotation support
+ * Anti-hallucination verification + confidence stack.
  *
- * Provides JSONL file rotation, segmentation by date, and automatic cleanup.
- * Used by history stores, feedback stores, and other persistent logging mechanisms.
+ * Each retrieved chunk is verified against the live source via `IStorage`:
+ * file exists (0.7) + snippet still present (0.3). The verification rate scales
+ * the retrieval confidence — a stale or fabricated source drags confidence down.
+ * Mirrors the legacy mind concept (source-verifier + confidence floor).
  */
 
-interface FileRotationOptions {
-    /**
-     * Base directory path for storing files
-     * @default '.kb/mind/store/'
-     */
-    basePath?: string;
-    /**
-     * Prefix for generated filenames
-     * @default 'store-'
-     */
-    filePrefix?: string;
-    /**
-     * Maximum number of records per file before rotation
-     * @default 1000
-     */
-    maxRecordsPerFile?: number;
-    /**
-     * Maximum number of files to keep (oldest deleted first)
-     * @default 30
-     */
-    maxFiles?: number;
+interface VerificationResult {
+    /** 0..1 fraction of (weighted) verification across chunks. */
+    rate: number;
+    /** Per-chunk verification score (0..1), aligned with input order. */
+    perChunk: number[];
+}
+declare function verifySources(ranked: RankedChunk[], storage: IStorage): Promise<VerificationResult>;
+interface ConfidenceResult {
+    confidence: number;
+    warnings: AgentWarning[];
 }
+/** Combine retrieval confidence with the verification rate; warn below floor. */
+declare function computeConfidence(retrievalConfidence: number, verificationRate: number, floor: number): ConfidenceResult;
+
 /**
- * Abstract base class for file-based stores with automatic rotation
- *
- * Features:
- * - JSONL format (one JSON object per line)
- * - Date-based file segmentation (YYYYMMDD-timestamp.jsonl)
- * - Automatic rotation when maxRecordsPerFile reached
- * - Automatic cleanup when maxFiles exceeded
- * - Sorted file iteration (oldest to newest)
+ * Field-checker — an anti-hallucination signal ported from the legacy engine.
  *
- * @example
- * ```typescript
- * class MyStore extends FileRotationStore<MyRecord> {
- *   async save(record: MyRecord): Promise<void> {
- *     return this.appendRecord(record);
- *   }
- *
- *   async find(criteria: any): Promise<MyRecord[]> {
- *     return this.readRecords((rec) => rec.id === criteria.id);
- *   }
- * }
- * ```
+ * An LLM answer that cites code should only name symbols that actually appear
+ * in the retrieved sources. We extract code-like symbols from the answer
+ * (backtick spans, camelCase/dotted/underscored identifiers, file names) and
+ * check each against the retrieved chunks (text + path). The grounded fraction
+ * folds into the confidence stack, and any ungrounded terms are surfaced as a
+ * warning — a cheap, deterministic guard against fabricated APIs.
  */
-declare abstract class FileRotationStore<TRecord> {
-    protected readonly storage: IStorage;
-    protected readonly basePath: string;
-    protected readonly filePrefix: string;
-    protected readonly maxRecordsPerFile: number;
-    protected readonly maxFiles: number;
-    constructor(storage: IStorage, options?: FileRotationOptions);
-    /**
-     * Append a record to the current writable file
-     *
-     * Automatically handles:
-     * - File rotation when maxRecordsPerFile exceeded
-     * - Cleanup when maxFiles exceeded
-     * - JSONL formatting
-     *
-     * @param record - Record to append
-     */
-    protected appendRecord(record: TRecord): Promise<void>;
-    /**
-     * Read records from all files, optionally filtering
-     *
-     * @param filter - Optional filter function
-     * @param limit - Maximum number of records to return
-     * @returns Array of records matching filter
-     */
-    protected readRecords(filter?: (record: TRecord) => boolean, limit?: number): Promise<TRecord[]>;
-    /**
-     * Get the current writable file path
-     *
-     * Creates a new segment if:
-     * - No files exist
-     * - Latest file has >= maxRecordsPerFile records
-     *
-     * @returns Path to writable file
-     */
-    protected getWritableFile(): Promise<string>;
-    /**
-     * Get all store files sorted by timestamp (oldest to newest)
-     *
-     * @returns Sorted array of file paths
-     */
-    protected getFilesSorted(): Promise<string[]>;
-    /**
-     * Generate a segment file path from timestamp
-     *
-     * Format: {filePrefix}YYYYMMDD-{timestamp}.jsonl
-     * Example: history-20251209-1733769000123.jsonl
-     *
-     * @param ts - Unix timestamp in milliseconds
-     * @returns Full file path
-     */
-    protected segmentPath(ts: number): string;
-    /**
-     * Enforce file rotation by deleting oldest files if maxFiles exceeded
-     */
-    protected enforceRotation(): Promise<void>;
-    /**
-     * Ensure path ends with trailing slash
-     */
-    protected ensureTrailingSlash(p: string): string;
+
+/** Extract code-like symbols from an answer (deduped, order-preserving). */
+declare function extractSymbols(answer: string): string[];
+interface FieldCheckResult {
+    /** 0..1 fraction of extracted symbols grounded in the sources. */
+    rate: number;
+    /** Symbols not found in any retrieved chunk. */
+    ungrounded: string[];
+    /** Number of symbols checked (0 → nothing to verify, rate defaults to 1). */
+    checked: number;
 }
+/** Check that symbols named in the answer appear in the retrieved sources. */
+declare function checkFields(answer: string, ranked: RankedChunk[]): FieldCheckResult;
 
 /**
- * JSON file operations for KB Labs Mind
- */
-/**
- * Read JSON file with error handling
- */
-declare function readJson<T = unknown>(filePath: string): Promise<T | null>;
-/**
- * Write JSON file atomically with sorted keys
- */
-declare function writeJson<T>(filePath: string, data: T): Promise<void>;
-/**
- * Compute hash of JSON content
+ * Query decomposition (multi-step reasoning) for richer agent modes.
+ *
+ * Asks the LLM to split a complex question into focused sub-queries. Degrades
+ * gracefully: if decomposition is disabled or the LLM returns nothing usable,
+ * it falls back to the original query alone.
  */
-declare function computeJsonHash(data: unknown): string;
+
+declare function decompose(query: string, llm: ILLM, maxSubqueries: number): Promise<string[]>;
 
 /**
- * @module @kb-labs/mind-core/verification
- * Mind index verification utilities
+ * Answer synthesis + frozen `AgentResponse` assembly.
  *
- * Moved from mind-gateway to break circular dependency (TASK-004)
+ * Produces the `agent-response-v1` contract consumed by CLAUDE.md and the
+ * task-rag skill. The response is validated against the contract zod before
+ * being returned, so a drift fails loudly here rather than silently downstream.
  */
-interface VerifyResult {
-    ok: boolean;
-    code: string | null;
-    inconsistencies: string[];
-    hint: string;
+
+declare function synthesizeAnswer(query: string, ranked: RankedChunk[], llm: ILLM, useLLM: boolean): Promise<string>;
+interface ToSourcesOptions {
+    snippet: SnippetMode;
+    staleByFile: Map<string, boolean>;
+}
+declare function toSources(ranked: RankedChunk[], opts: ToSourcesOptions): AgentSource[];
+interface BuildAgentResponseInput {
+    answer: string;
+    ranked: RankedChunk[];
+    confidence: number;
+    mode: AgentQueryMode;
+    requestId: string;
+    timingMs: number;
+    indexId: string;
+    floor: number;
+    snippet: SnippetMode;
+    staleByFile: Map<string, boolean>;
+    warnings?: AgentWarning[];
 }
+/** Assemble + validate the lean agent response. */
+declare function buildAgentResponse(input: BuildAgentResponseInput): AgentResponse;
+
 /**
- * Verify Mind index integrity
- *
- * Checks:
- * 1. Main index file exists (.kb/mind/index.json)
- * 2. Individual file hashes match (api-index, deps, recent-diff)
- * 3. Combined index checksum is valid
- * 4. Required files are present
+ * Query-history feedback loop via the platform cache (sorted set).
  *
- * @param cwd - Workspace root directory
- * @returns Verification result with inconsistencies list
- *
- * @example
- * ```typescript
- * const result = await verifyIndexes('/path/to/workspace');
- * if (!result.ok) {
- *   console.error('Inconsistencies:', result.inconsistencies);
- *   console.log('Hint:', result.hint);
- * }
- * ```
+ * Records queries per index (scored by timestamp) so the engine can learn from
+ * usage over time. Best-effort: cache failures never break a query.
  */
-declare function verifyIndexes(cwd: string): Promise<VerifyResult>;
 
-/**
- * Default configurations for KB Labs Mind
- */
+declare function recordQuery(cache: ICache, indexId: string, query: string, at: number): Promise<void>;
+declare function recentQueries(cache: ICache, indexId: string, sinceMs?: number): Promise<string[]>;
 
 /**
- * Default context budget
- */
-declare const DEFAULT_BUDGET: ContextBudget;
-/**
- * Default context preset
+ * Incremental document sync — add / update / delete specific paths in an index
+ * without a full rebuild. Operates on both the vector store (namespace=indexId)
+ * and the persisted manifest (BM25 corpus + bookkeeping).
  */
-declare const DEFAULT_PRESET: ContextPreset;
-/**
- * Default time budget for indexing operations (ms)
- */
-declare const DEFAULT_TIME_BUDGET_MS = 800;
-/**
- * Maximum file size to process (bytes)
- */
-declare const MAX_FILE_SIZE_BYTES: number;
+
+interface SyncOptions {
+    indexId: string;
+    /** Workspace root that source paths are resolved against. */
+    cwd: string;
+    chunk: ChunkOptions;
+    ast: boolean;
+    now: string;
+}
+interface SyncCounts {
+    added: number;
+    updated: number;
+    deleted: number;
+}
+declare function syncAdd(paths: string[], services: MindServices, opts: SyncOptions): Promise<SyncCounts>;
+declare function syncUpdate(paths: string[], services: MindServices, opts: SyncOptions): Promise<SyncCounts>;
+declare function syncDelete(paths: string[], services: MindServices, opts: SyncOptions): Promise<SyncCounts>;
+
 /**
- * Maximum lines per snippet
+ * Shape ranked chunks into lean wire `SearchResult`s (pointers, not payloads).
+ *
+ * `snippet` rides only as much text as the caller asked for (`--snippet`):
+ * none → nothing; line → the first meaningful line; full → truncated chunk.
  */
-declare const MAX_SNIPPET_LINES = 60;
+
+interface ToResultsOptions {
+    snippet: SnippetMode;
+    /** file → stale (on-disk drift since indexing). */
+    staleByFile: Map<string, boolean>;
+}
+declare function toSearchResults(ranked: RankedChunk[], opts: ToResultsOptions): SearchResult[];
+
 /**
- * Generator string for artifacts
+ * Per-index manifest persistence via `IStorage`.
+ *
+ * The manifest is the source of truth for the BM25 corpus and for
+ * listing/status. Vectors live in the vector store; the manifest holds chunk
+ * text + per-file bookkeeping. One manifest per index id.
  */
-declare function getGenerator(): string;
 
-export { DEFAULT_BUDGET, DEFAULT_PRESET, DEFAULT_TIME_BUDGET_MS, DefaultTokenEstimator, ERROR_HINTS, type ErrorCode, type FileRotationOptions, FileRotationStore, MAX_FILE_SIZE_BYTES, MAX_SNIPPET_LINES, MindError, type VerifyResult, computeJsonHash, cosineSimilarity, createMindError, defaultTokenEstimator, dotProduct, estimateTokens, findWorkspaceRoot, fromPosix, getExitCode, getGenerator, isMindError, magnitude, makeRelativeToRoot, normalize, readJson, sha256, sha256Buffer, sha256File, shouldIgnorePath, toPosix, truncateToTokens, verifyIndexes, wrapError, writeJson };
+declare function loadManifest(storage: IStorage, indexId: string): Promise<IndexManifest>;
+declare function saveManifest(storage: IStorage, manifest: IndexManifest): Promise<void>;
+
+export { type Chunk, type ChunkMeta, type Clock, type ConfidenceResult, type CreateMindOptions, type FieldCheckResult, type IndexManifest, type IngestInput, type IngestProgress, type IngestResult, type Mind, MindServices, type QueryIntent, type RankedChunk, type RetrieveInput, type RetrieveOutput, type Stage, type SyncCounts, type SyncOptions, Tracer, type VerificationResult, bm25Search, buildAgentResponse, checkFields, chunkFile, chunkId, computeConfidence, createMind, decompose, dedupRanked, extractSymbols, ingest, intentWeights, kindFromPath, loadManifest, recentQueries, recordQuery, rerank, retrieve, rrfFuse, saveManifest, slidingWindowChunks, structuralChunks, syncAdd, syncDelete, syncUpdate, synthesizeAnswer, toSearchResults, toSources, tokenize, verifySources };