@dikolab/kbdb 0.3.2 → 0.4.1

package/dist/src/shared/cli/typings/dispatch-client.type.d.ts

@@ -17,6 +17,7 @@ import type { AgentGetClient } from './agent-get-client.interface.ts';
 import type { AgentDeleteClient } from '../functions/run-agent-delete.function.ts';
 import type { RecallClient } from '../functions/run-recall.function.ts';
 import type { ExportClient } from '../functions/run-export.function.ts';
+import type { ImportClient } from '../functions/run-import.function.ts';
 /**
  * Intersection of all data-command client interfaces.
  *
@@ -24,4 +25,4 @@ import type { ExportClient } from '../functions/run-export.function.ts';
  * intersection combines them so `dispatchCommand` can route
  * to any command handler with full type safety.
  */
-export type DispatchClient = SearchClient & LearnClient & UnlearnClient & ContentClient & CheckClient & GcClient & RebuildClient & StatusClient & DbMigrateClient & SkillLearnClient & SkillListClient & SkillGetClient & SkillDeleteClient & AgentCreateClient & AgentListClient & AgentGetClient & AgentDeleteClient & RecallClient & ExportClient;
+export type DispatchClient = SearchClient & LearnClient & UnlearnClient & ContentClient & CheckClient & GcClient & RebuildClient & StatusClient & DbMigrateClient & SkillLearnClient & SkillListClient & SkillGetClient & SkillDeleteClient & AgentCreateClient & AgentListClient & AgentGetClient & AgentDeleteClient & RecallClient & ExportClient & ImportClient;

package/dist/src/shared/cli/typings/search-display.model.d.ts

@@ -50,4 +50,10 @@ export interface PagedSearchDisplay {
      * empty.
      */
     relaxed: boolean;
+    /** Server-side computation time in milliseconds. */
+    elapsed_ms?: number;
+    /** Algorithm that produced these results. */
+    search_mode?: string;
+    /** Retrieval strategy used (e.g. `'lexical'`, `'rrf'`). */
+    retrieval_method?: string;
 }

package/dist/src/shared/embedding/classes/api-embedding-provider.class.d.ts

@@ -0,0 +1,33 @@
+import type { EmbeddingProvider } from '../typings/embedding-provider.interface.ts';
+/**
+ * HTTP API embedding provider compatible with the OpenAI
+ * embeddings API format.
+ *
+ * Sends texts to a remote endpoint and maps the response
+ * `data[].embedding` arrays to `Float32Array[]`.
+ */
+export declare class ApiEmbeddingProvider implements EmbeddingProvider {
+    /** Remote endpoint URL for embedding requests. */
+    private readonly endpoint;
+    /** Number of dimensions in the returned vectors. */
+    private readonly dims;
+    /** Model name sent in the request body. */
+    private readonly model;
+    /**
+     * @param endpoint - URL to POST embedding requests to
+     * @param dimensions - number of vector dimensions expected
+     * @param model - optional model name; defaults to `'api'`
+     */
+    constructor(endpoint: string, dimensions: number, model?: string);
+    /**
+     * Posts texts to the endpoint and returns one `Float32Array`
+     * per input.
+     *
+     * @throws {Error} when the HTTP response status is not 2xx
+     */
+    embed(texts: string[]): Promise<Float32Array[]>;
+    /** Returns the configured number of embedding dimensions. */
+    dimensions(): number;
+    /** Returns the configured model name, defaulting to `'api'`. */
+    modelName(): string;
+}

package/dist/src/shared/embedding/classes/onnx-embedding-provider.class.d.ts

@@ -0,0 +1,33 @@
+import type { EmbeddingProvider } from '../typings/embedding-provider.interface.ts';
+/**
+ * ONNX Runtime embedding provider.
+ *
+ * Satisfies the `EmbeddingProvider` contract with the correct
+ * structure but defers actual inference to Phase 3+. Calling
+ * `embed()` throws until `onnxruntime-node` is available and
+ * wired in.
+ *
+ * @throws {Error} on `embed()` when ONNX Runtime is not available
+ */
+export declare class OnnxEmbeddingProvider implements EmbeddingProvider {
+    /** Path to the ONNX model file. */
+    private readonly model;
+    /** Number of embedding dimensions the model produces. */
+    private readonly dims;
+    /**
+     * @param model - filesystem path to the ONNX model file
+     * @param dimensions - number of dimensions the model produces
+     */
+    constructor(model: string, dimensions: number);
+    /**
+     * Not yet implemented.
+     *
+     * @throws {Error} always -- ONNX Runtime is an optional peer
+     *   dependency not yet wired
+     */
+    embed(_texts: string[]): Promise<Float32Array[]>;
+    /** Returns the configured number of embedding dimensions. */
+    dimensions(): number;
+    /** Returns the configured model file path. */
+    modelName(): string;
+}

package/dist/src/shared/embedding/classes/tfidf-embedding-provider.class.d.ts

@@ -0,0 +1,28 @@
+import type { EmbeddingProvider } from '../typings/embedding-provider.interface.ts';
+/**
+ * Embedding provider backed by the `kbdb-default-embedding` WASM
+ * module.
+ *
+ * Delegates `embed()` to the `embedding_tfidf_batch` WASM export,
+ * reads the resulting `Float32Array` vectors from WASM linear memory,
+ * and returns them as a plain JavaScript array.
+ */
+export declare class TfidfEmbeddingProvider implements EmbeddingProvider {
+    private readonly _alloc;
+    private readonly _batch;
+    private readonly _retPtr;
+    private readonly _memory;
+    /** @param wasm - instantiated `kbdb-default-embedding` WASM module */
+    constructor(wasm: WebAssembly.Instance);
+    /**
+     * Embeds a batch of texts using TF-IDF computation in WASM.
+     *
+     * @param texts - input strings to embed
+     * @returns one 256-dimension `Float32Array` per input text
+     */
+    embed(texts: string[]): Promise<Float32Array[]>;
+    /** Returns 256 -- the fixed dimension count for TF-IDF vectors. */
+    dimensions(): number;
+    /** Returns `'tfidf-v1'`. */
+    modelName(): string;
+}

package/dist/src/shared/embedding/constants/tfidf-defaults.constant.d.ts

@@ -0,0 +1,4 @@
+/** Number of dimensions in a TF-IDF embedding vector. */
+export declare const TFIDF_DIMENSIONS = 256;
+/** Model name reported by the TF-IDF embedding provider. */
+export declare const TFIDF_MODEL_NAME = "tfidf-v1";

package/dist/src/shared/embedding/functions/append-vector-entry.function.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Appends a single vector entry to `vectors.idx`.
+ *
+ * Creates the file with a full header when it does not exist.
+ * When the file already exists, appends the record and updates
+ * the count in the header. Skips silently when `vector` is empty.
+ *
+ * @param dirPath - directory containing `vectors.idx`
+ * @param modelName - embedding model name
+ * @param dimensions - number of dimensions per vector
+ * @param kbid - section identifier
+ * @param vector - embedding vector to store
+ */
+export declare function appendVectorEntry(dirPath: string, modelName: string, dimensions: number, kbid: string, vector: Float32Array): void;

package/dist/src/shared/embedding/functions/create-embedding-provider.function.d.ts

@@ -0,0 +1,15 @@
+import type { EmbeddingConfig } from '../typings/embedding-config.interface.ts';
+import type { EmbeddingProvider } from '../typings/embedding-provider.interface.ts';
+/**
+ * Creates an embedding provider from the given configuration.
+ *
+ * - `undefined` + WASM instance → `TfidfEmbeddingProvider`
+ * - `undefined` without WASM → `NullEmbeddingProvider` (fallback)
+ * - `'none'` → `NullEmbeddingProvider`
+ * - `'onnx'` → `OnnxEmbeddingProvider`
+ * - `'api'` → `ApiEmbeddingProvider`
+ *
+ * @param config - embedding configuration from `worker.toml`
+ * @param wasmInstance - optional default-embedding WASM instance
+ */
+export declare function createEmbeddingProvider(config: EmbeddingConfig | undefined, wasmInstance?: WebAssembly.Instance): EmbeddingProvider;

package/dist/src/shared/embedding/functions/detect-stale-vectors.function.d.ts

@@ -0,0 +1,16 @@
+import type { EmbeddingProvider } from '../typings/embedding-provider.interface.ts';
+import type { StaleVectorsReport } from '../typings/stale-vectors-report.model.ts';
+/**
+ * Checks whether `vectors.idx` in `targetDir` is stale relative to
+ * the given embedding provider.
+ *
+ * Returns `{ stale: false }` when the index does not exist yet, when
+ * embeddings are disabled (`provider.dimensions() === 0`), or when
+ * the model name and dimensions match the stored index header.
+ * Returns `{ stale: true, reason }` when the model name or vector
+ * dimensions differ from the stored header.
+ *
+ * @param targetDir - absolute path to the `.kbdb` directory
+ * @param provider - current embedding provider to compare against
+ */
+export declare function detectStaleVectors(targetDir: string, provider: EmbeddingProvider): StaleVectorsReport;

package/dist/src/shared/embedding/functions/parse-api-embedding-response.function.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validates and parses an OpenAI-compatible embedding API response.
+ *
+ * Narrows `unknown` to the expected response shape and converts
+ * each `embedding` array to a `Float32Array`.
+ *
+ * @param raw - the parsed JSON body from the embedding API
+ * @throws {Error} when the response does not match the expected
+ *   `{ data: [{ embedding: number[] }] }` shape
+ */
+export declare function parseApiEmbeddingResponse(raw: unknown): Float32Array[];

package/dist/src/shared/embedding/functions/rebuild-vectors.function.d.ts

@@ -0,0 +1,15 @@
+import type { EmbeddingProvider } from '../typings/embedding-provider.interface.ts';
+/**
+ * Re-embeds all section files and writes a fresh `vectors.idx`.
+ *
+ * Scans `targetDir/sections/<shard>/<kbid>.section`, extracts each
+ * body (after `\n---\n` separator or full content), embeds all texts
+ * in a single batch, and writes the result via `buildVectorIndex`.
+ *
+ * Returns 0 immediately when `provider.dimensions() === 0`.
+ *
+ * @param targetDir - absolute path to the `.kbdb` directory
+ * @param provider - embedding provider to use for vectorisation
+ * @returns number of sections embedded
+ */
+export declare function rebuildVectors(targetDir: string, provider: EmbeddingProvider): Promise<number>;

package/dist/src/shared/embedding/functions/scan-semantic-contradictions.function.d.ts

@@ -0,0 +1,13 @@
+import type { SemanticContradiction } from '../typings/semantic-contradiction.model.ts';
+/**
+ * Scans a `vectors.idx` file for pairs of sections whose cosine
+ * similarity is negative, indicating semantic opposition.
+ *
+ * Returns an empty array when the file does not exist, is empty,
+ * or contains fewer than two vectors. Each contradicting pair is
+ * reported once (in insertion order, i before j).
+ *
+ * @param filePath - absolute path to the `vectors.idx` file
+ * @returns detected semantic contradiction pairs, advisory only
+ */
+export declare function scanSemanticContradictions(filePath: string): SemanticContradiction[];

package/dist/src/shared/embedding/index.d.ts

@@ -1,12 +1,20 @@
 export { NullEmbeddingProvider } from './classes/null-embedding-provider.class.ts';
+export { OnnxEmbeddingProvider } from './classes/onnx-embedding-provider.class.ts';
+export { ApiEmbeddingProvider } from './classes/api-embedding-provider.class.ts';
+export { TfidfEmbeddingProvider } from './classes/tfidf-embedding-provider.class.ts';
+export { createEmbeddingProvider } from './functions/create-embedding-provider.function.ts';
 export { cosineSimilarity } from './functions/cosine-similarity.function.ts';
 export { rrfFuse } from './functions/rrf-fuse.function.ts';
 export { buildVectorIndex } from './functions/build-vector-index.function.ts';
 export { searchVectors } from './functions/search-vectors.function.ts';
+export { appendVectorEntry } from './functions/append-vector-entry.function.ts';
 export { readVectorIndexMeta } from './functions/read-vector-index-meta.function.ts';
 export { jaccardCoefficient } from './functions/jaccard-coefficient.function.ts';
 export { detectNearDuplicates } from './functions/detect-near-duplicates.function.ts';
+export { detectStaleVectors } from './functions/detect-stale-vectors.function.ts';
+export { rebuildVectors } from './functions/rebuild-vectors.function.ts';
 export { JACCARD_THRESHOLD, JACCARD_BAND_MIN, COSINE_THRESHOLD, } from './constants/near-duplicate-thresholds.constant.ts';
+export { TFIDF_DIMENSIONS, TFIDF_MODEL_NAME, } from './constants/tfidf-defaults.constant.ts';
 export type { EmbeddingProvider } from './typings/embedding-provider.interface.ts';
 export type { EmbeddingConfig } from './typings/embedding-config.interface.ts';
 export type { VectorSearchResult } from './typings/vector-search-result.model.ts';
@@ -14,3 +22,4 @@ export type { VectorIndexMeta } from './typings/vector-index-meta.model.ts';
 export type { VectorIndexEntry } from './typings/vector-index-entry.model.ts';
 export type { NearDuplicateCandidate } from './typings/near-duplicate-candidate.model.ts';
 export type { NearDuplicateResult } from './typings/near-duplicate-result.model.ts';
+export type { StaleVectorsReport } from './typings/stale-vectors-report.model.ts';

package/dist/src/shared/embedding/typings/semantic-contradiction.model.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A pair of knowledge-base sections whose embedding vectors point
+ * in opposite directions, indicating they may convey conflicting
+ * information.
+ *
+ * Reported as an advisory finding — does not indicate data
+ * corruption; the sections may represent legitimately competing
+ * viewpoints or superseded content.
+ */
+export interface SemanticContradiction {
+    /** Knowledge-base identifier of the first section in the pair. */
+    readonly kbid_a: string;
+    /** Knowledge-base identifier of the second section in the pair. */
+    readonly kbid_b: string;
+    /**
+     * Cosine similarity score (negative, in range -1.0 to 0.0).
+     *
+     * More negative values indicate stronger semantic opposition.
+     */
+    readonly score: number;
+}

package/dist/src/shared/embedding/typings/stale-vectors-report.model.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Result of a stale vector detection check.
+ *
+ * Reports whether the `vectors.idx` file is considered stale
+ * relative to the current embedding provider.
+ */
+export type StaleVectorsReport = {
+    /** The index is current — no rebuild needed. */
+    readonly stale: false;
+    readonly reason?: undefined;
+} | {
+    /** The index is stale and must be rebuilt. */
+    readonly stale: true;
+    /** Human-readable explanation of what changed. */
+    readonly reason: string;
+};

package/dist/src/shared/log/constants/log-colors.constant.d.ts

@@ -0,0 +1,5 @@
+import { LogLevel } from '../typings/log-level.type.ts';
+/** ANSI escape sequence that resets all text formatting. */
+export declare const ANSI_RESET = "\u001B[0m";
+/** ANSI foreground color code applied to each log level's output. */
+export declare const LOG_COLORS: Record<LogLevel, string>;

package/dist/src/shared/log/constants/log-defaults.constant.d.ts

@@ -0,0 +1,3 @@
+import { LogLevel } from '../typings/log-level.type.ts';
+/** Default log level used when no CLI flag or env var is set. */
+export declare const DEFAULT_LOG_LEVEL = LogLevel.ERROR;

package/dist/src/shared/log/constants/log-icons.constant.d.ts

@@ -0,0 +1,3 @@
+import { LogLevel } from '../typings/log-level.type.ts';
+/** Single-character icon used as visual prefix for each log level. */
+export declare const LOG_ICONS: Record<LogLevel, string>;

package/dist/src/shared/log/functions/configure-log.function.d.ts

@@ -0,0 +1,12 @@
+import type { LogConfig } from '../typings/log-config.interface.ts';
+/**
+ * Applies a log configuration, setting the active log level and
+ * optionally overriding the output target for individual levels.
+ *
+ * Only levels listed in `config.outputs` are affected; all other
+ * level outputs remain unchanged. Calling this function multiple
+ * times is safe -- the last call's settings take effect.
+ *
+ * @param config - desired log level and optional per-level outputs
+ */
+export declare function configureLog(config: LogConfig): void;

package/dist/src/shared/log/functions/log.function.d.ts

@@ -0,0 +1,28 @@
+import { LogLevel } from '../typings/log-level.type.ts';
+/** A function that receives a formatted log line. */
+type OutputFn = (message: string) => void;
+/**
+ * Sets the minimum log level. Messages below this level are
+ * suppressed. Used internally by `configureLog`.
+ */
+export declare function setLogLevel(level: LogLevel): void;
+/**
+ * Overrides the output function for a specific log level.
+ * Used internally by `configureLog`.
+ *
+ * @param level - the log level whose output to replace
+ * @param output - function that receives the formatted message
+ */
+export declare function setLogOutput(level: LogLevel, output: OutputFn): void;
+/**
+ * Writes a formatted, colorized log message to the configured
+ * output for the given level. Messages below the current level
+ * are silently discarded.
+ *
+ * Format: `\x1b[COLORm ICON [LEVEL_NAME] message\x1b[0m\n`
+ *
+ * @param message - the text to log
+ * @param level - severity level; defaults to `LogLevel.ERROR`
+ */
+export declare function log(message: string, level?: LogLevel): void;
+export {};

package/dist/src/shared/log/functions/parse-log-level.function.d.ts

@@ -0,0 +1,10 @@
+import { LogLevel } from '../typings/log-level.type.ts';
+/**
+ * Parses a string into a `LogLevel` enum value.
+ *
+ * Matching is case-insensitive. Returns `LogLevel.WARNING` for
+ * any unrecognized value, including empty strings.
+ *
+ * @param value - the raw string to parse (e.g. from a CLI flag)
+ */
+export declare function parseLogLevel(value: string): LogLevel;

package/dist/src/shared/log/functions/resolve-log-level.function.d.ts

@@ -0,0 +1,12 @@
+import type { LogLevel } from '../typings/log-level.type.ts';
+/**
+ * Resolves the active log level from CLI flags or the environment.
+ *
+ * Priority order:
+ * 1. `cliLevel` when provided (CLI flag takes highest priority)
+ * 2. `KBDB_LOG_LEVEL` environment variable, parsed via `parseLogLevel`
+ * 3. `DEFAULT_LOG_LEVEL` (`LogLevel.ERROR`) when neither is set
+ *
+ * @param cliLevel - explicit level passed from a CLI flag, if any
+ */
+export declare function resolveLogLevel(cliLevel?: LogLevel): LogLevel;

package/dist/src/shared/log/functions/write-stderr.function.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Writes a string to the process standard error stream.
+ *
+ * Works on both Node.js (via `process.stderr.write`) and Deno
+ * (via `Deno.stderr.writeSync`). Silently does nothing when
+ * neither runtime API is available.
+ *
+ * @param message - the string to write to stderr
+ */
+export declare function writeStderr(message: string): void;

package/dist/src/shared/log/index.d.ts

@@ -0,0 +1,10 @@
+export { LogLevel } from './typings/log-level.type.ts';
+export type { LogOutput } from './typings/log-output.interface.ts';
+export type { LogConfig } from './typings/log-config.interface.ts';
+export { log } from './functions/log.function.ts';
+export { configureLog } from './functions/configure-log.function.ts';
+export { parseLogLevel } from './functions/parse-log-level.function.ts';
+export { resolveLogLevel } from './functions/resolve-log-level.function.ts';
+export { LOG_ICONS } from './constants/log-icons.constant.ts';
+export { LOG_COLORS, ANSI_RESET, } from './constants/log-colors.constant.ts';
+export { DEFAULT_LOG_LEVEL } from './constants/log-defaults.constant.ts';

package/dist/src/shared/log/typings/log-config.interface.d.ts

@@ -0,0 +1,7 @@
+import type { LogLevel } from './log-level.type.ts';
+import type { LogOutput } from './log-output.interface.ts';
+/** Configuration for the log module. */
+export interface LogConfig {
+    readonly level: LogLevel;
+    readonly outputs?: Partial<Record<LogLevel, LogOutput>>;
+}

package/dist/src/shared/log/typings/log-level.type.d.ts

@@ -0,0 +1,7 @@
+/** Verbosity levels, ordered from most to least verbose. */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARNING = 2,
+    ERROR = 3
+}

package/dist/src/shared/log/typings/log-output.interface.d.ts

@@ -0,0 +1,4 @@
+/** Writable target for a single log level. */
+export interface LogOutput {
+    readonly write: (message: string) => void;
+}

package/dist/src/shared/mcp/classes/mcp-server.class.d.ts

@@ -1,6 +1,7 @@
 import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
 import type { McpResponse } from '../typings/mcp-types.interface.ts';
 import type { McpLogLevel } from '../typings/log-types.interface.ts';
+import type { AutoCaptureConfig } from '../../auto-capture/typings/auto-capture-config.interface.ts';
 /**
  * MCP server that speaks JSON-RPC 2.0 over stdio. Listens for
  * newline-delimited requests on `process.stdin`, dispatches each
@@ -9,15 +10,29 @@ import type { McpLogLevel } from '../typings/log-types.interface.ts';
  * `process.stdout`.
  */
 export declare class McpServer {
-    private readonly client;
+    private client;
     private readonly contextPath;
+    private readonly autoCaptureConfig;
+    private readonly clientFactory;
+    private readonly maxRetries;
+    private autoCaptureController;
     private initialized;
     private hostCapabilities;
     private logLevel;
     private readonly subscriptions;
     private nextRequestId;
     private readonly pendingRequests;
-    constructor(client: McpWorkerClient, contextPath?: string);
+    /**
+     * @param client - worker client providing knowledge-base operations
+     * @param contextPath - absolute path to the `.kbdb` directory
+     * @param autoCaptureConfig - optional auto-capture configuration;
+     *   when provided the server activates auto-capture on connection
+     * @param clientFactory - creates a fresh worker client (for retry)
+     * @param maxRetries - max retries on REQUEST_TIMEOUT
+     */
+    constructor(client: McpWorkerClient, contextPath?: string, autoCaptureConfig?: AutoCaptureConfig, clientFactory?: (() => Promise<McpWorkerClient>) | null, maxRetries?: number);
+    private reconnectClient;
+    private withRetry;
     listen(): Promise<void>;
     handleLineForTest(line: string): Promise<McpResponse | null>;
     /**
@@ -52,6 +67,11 @@ export declare class McpServer {
     private processLine;
     private handleRequest;
     private send;
+    /**
+     * Records a tool call in the auto-capture controller and fires
+     * a capture when the trigger condition is met.
+     */
+    private afterToolCall;
     /**
      * Runs an integrity check immediately after the MCP handshake
      * completes. Emits a `notifications/message` warning when the

package/dist/src/shared/mcp/functions/create-mcp-server.function.d.ts

@@ -1,11 +1,16 @@
 import { McpServer } from '../classes/mcp-server.class.ts';
 import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { AutoCaptureConfig } from '../../auto-capture/typings/auto-capture-config.interface.ts';
 /**
  * Factory that constructs a new `McpServer` bound to the given
  * worker client. Call `server.listen()` on the returned instance
  * to start processing stdio input.
  *
  * @param client - worker client providing knowledge-base operations
+ * @param contextPath - absolute path to the `.kbdb` directory
+ * @param autoCaptureConfig - optional auto-capture configuration;
+ *   when provided, the server activates auto-capture on client
+ *   connection and stops it on disconnect
  * @returns a configured `McpServer` ready to listen
  */
-export declare function createMcpServer(client: McpWorkerClient): McpServer;
+export declare function createMcpServer(client: McpWorkerClient, contextPath?: string, autoCaptureConfig?: AutoCaptureConfig, clientFactory?: (() => Promise<McpWorkerClient>) | null, maxRetries?: number): McpServer;

package/dist/src/shared/mcp/functions/has-sampling-capability.function.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns `true` when the host advertised the `sampling` capability
+ * during MCP initialization.
+ *
+ * @param hostCapabilities - capabilities object from the MCP
+ *   `initialize` request, or `null` when not yet set
+ */
+export declare function hasSamplingCapability(hostCapabilities: Record<string, unknown> | null): boolean;

package/dist/src/shared/mcp/functions/run-auto-capture.function.d.ts

@@ -0,0 +1,26 @@
+import type { AutoCaptureController } from '../../auto-capture/classes/auto-capture-controller.class.ts';
+import type { AutoCaptureConfig } from '../../auto-capture/typings/auto-capture-config.interface.ts';
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+/** Sampling request callback matching McpServer.sendRequest. */
+type RequestSampling = (messages: {
+    role: string;
+    content: {
+        type: string;
+        text: string;
+    };
+}[], maxTokens: number) => Promise<unknown>;
+/**
+ * Evaluates the auto-capture trigger and, when it fires, sends an
+ * MCP sampling request to the host and stores any returned knowledge.
+ *
+ * Silently ignores all errors so a capture failure never disrupts
+ * the MCP server's normal operation.
+ *
+ * @param controller - tracks session state and evaluates the trigger
+ * @param config - auto-capture configuration (provides dryRun flag)
+ * @param client - worker client used to persist captured knowledge
+ * @param hostCapabilities - capabilities from the MCP host
+ * @param requestSampling - sends a sampling request to the host
+ */
+export declare function runAutoCapture(controller: AutoCaptureController, config: AutoCaptureConfig, client: McpWorkerClient, hostCapabilities: Record<string, unknown> | null, requestSampling: RequestSampling): Promise<void>;
+export {};

package/dist/src/shared/mcp/typings/mcp-client.interface.d.ts

@@ -94,6 +94,8 @@ export interface McpWorkerClient {
         readonly offset?: number;
         /** Search algorithm: 'lexical', 'vector', or 'hybrid'. */
         readonly algo?: string;
+        /** Use relaxed (OR) matching for the query. */
+        readonly relaxed?: boolean;
     }): Promise<{
         readonly items: readonly {
             readonly kbid: string;

package/dist/src/shared/mcp/typings/mcp-integrity-check-result.model.d.ts

@@ -1,4 +1,22 @@
 import type { McpIntegrityError } from './mcp-integrity-error.model.ts';
+/**
+ * Advisory finding: two sections whose embedding vectors point in
+ * opposite directions, indicating potential semantic conflict.
+ *
+ * Reported as advisory only — does not flip `ok` to `false`.
+ */
+export interface McpSemanticContradiction {
+    /** Knowledge-base identifier of the first section in the pair. */
+    readonly kbid_a: string;
+    /** Knowledge-base identifier of the second section in the pair. */
+    readonly kbid_b: string;
+    /**
+     * Cosine similarity score (negative, in range -1.0 to 0.0).
+     *
+     * More negative values indicate stronger semantic opposition.
+     */
+    readonly score: number;
+}
 /** Integrity check report returned by the daemon. */
 export interface McpIntegrityCheckResult {
     /** `true` when all checks passed and no errors were found. */
@@ -13,4 +31,10 @@ export interface McpIntegrityCheckResult {
     readonly references_checked: number;
     /** Time taken to complete the check, in milliseconds. */
     readonly elapsed_ms: number;
+    /**
+     * Advisory list of section pairs with semantically contradictory
+     * embeddings. Empty when no embedding provider is configured or
+     * when no `vectors.idx` file is present. Never affects `ok`.
+     */
+    readonly semantic_contradictions: McpSemanticContradiction[];
 }

package/dist/src/shared/mcp/typings/mcp-worker-client.interface.d.ts

@@ -27,13 +27,15 @@ export interface McpWorkerClient {
         readonly mode?: string;
         /**
          * Search algorithm: `'lexical'`, `'vector'`, or `'hybrid'`.
-         * Defaults to `'lexical'` when omitted.
+         * Defaults to `'hybrid'` when omitted.
          */
         readonly algo?: string;
         /** Maximum number of results to return. */
         readonly limit?: number;
         /** Number of results to skip for pagination. */
         readonly offset?: number;
+        /** Use relaxed (OR) matching for the query. */
+        readonly relaxed?: boolean;
     }): Promise<{
         readonly items: readonly {
             readonly kbid: string;

package/dist/src/shared/version/constants/version.constant.d.ts

@@ -1,2 +1,2 @@
 /** Current package version, kept in sync with package.json. */
-export declare const VERSION = "0.2.2";
+export declare const VERSION = "0.4.1";

package/dist/src/shared/wasm-codec/typings/paged-search-result.model.d.ts

@@ -18,4 +18,6 @@ export interface PagedSearchResult {
      * after strict (AND-mode) returned no results.
      */
     relaxed: boolean;
+    /** Server-side computation time in milliseconds. */
+    elapsed_ms?: number;
 }