@dikolab/kbdb 0.3.1 → 0.4.0

package/dist/src/shared/cli/functions/run-search.function.d.ts

@@ -49,6 +49,12 @@ interface RawSearchResponse {
      * May be absent from older daemon versions.
      */
     readonly relaxed?: boolean;
+    /** Server-side computation time in milliseconds. */
+    readonly elapsed_ms?: number;
+    /** Algorithm that produced these results. */
+    readonly search_mode?: string;
+    /** Retrieval strategy used (e.g. `'lexical'`, `'rrf'`). */
+    readonly retrieval_method?: string;
 }
 /**
  * Minimal client interface required by `runSearch`.
@@ -68,6 +74,7 @@ export interface SearchClient {
         limit?: number;
         offset?: number;
         algo?: string;
+        relaxed?: boolean;
     }): Promise<RawSearchResponse>;
 }
 /**

package/dist/src/shared/cli/functions/run-unlearn.function.d.ts

@@ -1,4 +1,5 @@
 import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { PrefixResolver } from './resolve-kbid-prefix.function.ts';
 /** Removal result returned by `UnlearnClient.removeSection`. */
 interface RemoveSectionResult {
     /** `true` when the section was found and successfully removed. */
@@ -11,8 +12,10 @@ interface RemoveSectionResult {
  *
  * Decouples the CLI function from the concrete `WorkerClient`
  * implementation, making it straightforward to test with mocks.
+ * Extends `PrefixResolver` so short kbid prefixes can be resolved
+ * before each section is removed.
  */
-export interface UnlearnClient {
+export interface UnlearnClient extends PrefixResolver {
     /**
      * Removes a section from the knowledge base.
      *
@@ -32,14 +35,16 @@ export interface UnlearnResult {
  * Removes the knowledge-base sections identified by `options.args`
  * via the provided client.
  *
- * Each kbid in `options.args` is processed independently. If a kbid
- * does not exist in the knowledge base, `removed` is set to `false`
- * rather than throwing.
+ * Short kbid prefixes in `options.args` are resolved to full
+ * identifiers before removal. Each kbid is processed independently.
+ * If a kbid does not exist in the knowledge base, `removed` is set
+ * to `false` rather than throwing.
  *
  * @param client - unlearn client to delegate removal to
  * @param options - parsed CLI options whose `args` list the kbids to
  *   remove
  * @returns one `UnlearnResult` per kbid processed
+ * @throws when a prefix matches no section or is ambiguous
  */
 export declare function runUnlearn(client: UnlearnClient, options: CliOptions): Promise<UnlearnResult[]>;
 export {};

package/dist/src/shared/cli/functions/run-worker-restart.function.d.ts

@@ -0,0 +1,11 @@
+import type { CommandResult } from '../typings/command-result.model.ts';
+/**
+ * Restarts the worker daemon by stopping any running instance.
+ *
+ * The daemon auto-spawns on the next CLI command, so restart
+ * only needs to stop the current instance.
+ *
+ * @param dbDir - absolute path to the `.kbdb` directory
+ * @returns command result indicating success or failure
+ */
+export declare function runWorkerRestart(dbDir: string): Promise<CommandResult>;

package/dist/src/shared/cli/functions/run-worker-stop.function.d.ts

@@ -0,0 +1,11 @@
+import type { CommandResult } from '../typings/command-result.model.ts';
+/**
+ * Stops the worker daemon for the resolved database path.
+ *
+ * Discovers the daemon via its PID file and sends `SIGTERM`.
+ * Returns success when the daemon was stopped or was not running.
+ *
+ * @param dbDir - absolute path to the `.kbdb` directory
+ * @returns command result indicating success or failure
+ */
+export declare function runWorkerStop(dbDir: string): Promise<CommandResult>;

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

@@ -18,6 +18,8 @@ export { isStdinTty } from './functions/is-stdin-tty.function.ts';
 export { promptUser } from './functions/prompt-user.function.ts';
 export { dispatchCommand } from './functions/dispatch-command.function.ts';
 export { runCli } from './functions/run-cli.function.ts';
+export { runWorkerStop } from './functions/run-worker-stop.function.ts';
+export { runWorkerRestart } from './functions/run-worker-restart.function.ts';
 export { HELP_TEXT } from './constants/help-text.constant.ts';
 export type { CliOptions, OutputFormat, SearchMode, } from './typings/cli-options.interface.ts';
 export type { LearnResult } from './typings/learn-result.model.ts';

package/dist/src/shared/cli/typings/cli-deps.interface.d.ts

@@ -11,6 +11,8 @@ import type { DisconnectableClient } from './disconnectable-client.interface.ts'
 export interface CliDeps {
     /** Returns `true` when stdin is an interactive terminal. */
     isStdinTty: () => boolean;
+    /** Returns `true` when stdout is an interactive terminal. */
+    isStdoutTty: () => boolean;
     /**
      * Prompts the user with the given question and resolves with
      * their trimmed response.
@@ -25,6 +27,7 @@ export interface CliDeps {
      */
     createWorkerClient: (opts: {
         contextPath: string;
+        requestTimeoutMs?: number;
     }) => Promise<DisconnectableClient>;
     /**
      * Finds the `.kbdb` directory starting from the given base path.
@@ -44,5 +47,5 @@ export interface CliDeps {
      *
      * @param contextPath - absolute path to the `.kbdb` directory
      */
-    startMcpServer?: (contextPath: string) => Promise<void>;
+    startMcpServer?: (contextPath: string, clientFactory?: () => Promise<DisconnectableClient>, maxRetries?: number) => Promise<void>;
 }

package/dist/src/shared/cli/typings/cli-options.interface.d.ts

@@ -25,6 +25,8 @@ export interface CliOptions {
     dbPath?: string;
     /** Output format for results. Defaults to `'json'`. */
     format: OutputFormat;
+    /** When `true`, the user explicitly passed `--format`. */
+    formatExplicit?: boolean;
     /** Search mode passed to the worker daemon. Defaults to `'sections'`. */
     mode: SearchMode;
     /** Search algorithm: `'lexical'`, `'vector'`, or `'hybrid'`. */
@@ -65,6 +67,21 @@ export interface CliOptions {
      * instead of creating a sibling.
      */
     replace?: boolean;
+    /** When `true`, uses OR mode directly. */
+    relaxed?: boolean;
+    /** Source path for `import --from`. */
+    from?: string;
+    /** When `true`, previews changes without writing. */
+    dryRun?: boolean;
+    /**
+     * Export format: `'git'` (flat dir) or `'archive'`.
+     * Defaults to `'git'`.
+     */
+    exportFormat?: 'git' | 'archive';
+    /** Per-request timeout in milliseconds for daemon IPC calls. */
+    timeoutMs?: number;
+    /** Maximum retry count on request timeout (default 5). */
+    retry?: number;
     /** Positional arguments following the sub-command. */
     args: string[];
 }

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/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,12 @@
+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.
+ *
+ * - `'none'` or missing config → `NullEmbeddingProvider`
+ * - `'onnx'` → `OnnxEmbeddingProvider`
+ * - `'api'` → `ApiEmbeddingProvider`
+ *
+ * @param config - embedding configuration from `worker.toml`
+ */
+export declare function createEmbeddingProvider(config: EmbeddingConfig | undefined): 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,11 +1,17 @@
 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 { 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 type { EmbeddingProvider } from './typings/embedding-provider.interface.ts';
 export type { EmbeddingConfig } from './typings/embedding-config.interface.ts';
@@ -14,3 +20,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/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.0";

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;
 }