@dikolab/kbdb 0.2.2 → 0.3.1

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

@@ -0,0 +1,58 @@
+/** Raw daemon response from `integrityCheck`. */
+export interface RawIntegrityCheckResult {
+    /** `true` when all checks passed and no errors were found. */
+    readonly ok: boolean;
+    /** All integrity errors found; empty when `ok` is `true`. */
+    readonly errors: IntegrityError[];
+    /** Total number of sections examined. */
+    readonly sections_checked: number;
+    /** Total number of documents examined. */
+    readonly documents_checked: number;
+    /** Total number of marker references checked. */
+    readonly references_checked: number;
+    /** Time taken to complete the check, in milliseconds. */
+    readonly elapsed_ms: number;
+    /**
+     * Encoded divergent-content map.
+     *
+     * Format: `sk1:kbid1,kbid2;sk2:kbid3,kbid4`
+     *
+     * Each semicolon-separated segment is a source key followed by
+     * a colon and a comma-separated list of kbids. Absent when no
+     * divergent content exists.
+     */
+    readonly divergent_content?: string;
+}
+/** A single integrity error found during a database check. */
+export interface IntegrityError {
+    /**
+     * The category of integrity violation detected.
+     *
+     * - `'checksum_mismatch'` -- stored content does not match its hash
+     * - `'orphan_section'` -- section not referenced by any document
+     * - `'orphan_document'` -- document references no existing sections
+     * - `'broken_reference'` -- a marker references a non-existent entity
+     * - `'type_mismatch'` -- stored MIME type conflicts with content
+     * - `'circular_reference'` -- marker chain contains a cycle
+     */
+    readonly type: 'checksum_mismatch' | 'orphan_section' | 'orphan_document' | 'broken_reference' | 'type_mismatch' | 'circular_reference';
+    /** Identifier of the entity (kbid or docid) that has the issue. */
+    readonly entity: string;
+    /** Human-readable description of the specific problem. */
+    readonly detail: string;
+}
+/**
+ * Minimal client interface required by `runCheck`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface CheckClient {
+    /**
+     * Runs an integrity check on the knowledge-base database.
+     *
+     * @returns a report of all issues found; `ok` is `true` when
+     *   no errors were detected
+     */
+    integrityCheck(): Promise<RawIntegrityCheckResult>;
+}

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

@@ -0,0 +1,48 @@
+import type { CliOptions } from './cli-options.interface.ts';
+import type { InitResult } from '../functions/run-init.function.ts';
+import type { DisconnectableClient } from './disconnectable-client.interface.ts';
+/**
+ * Injectable dependencies for the CLI orchestrator.
+ *
+ * Every external side-effect is injected so the function
+ * is fully testable without touching process globals,
+ * filesystem, or network.
+ */
+export interface CliDeps {
+    /** Returns `true` when stdin is an interactive terminal. */
+    isStdinTty: () => boolean;
+    /**
+     * Prompts the user with the given question and resolves with
+     * their trimmed response.
+     *
+     * @param question - text to display before the input prompt
+     */
+    promptUser: (question: string) => Promise<string>;
+    /**
+     * Creates a worker client connected to the given database path.
+     *
+     * @param opts - connection options including the context path
+     */
+    createWorkerClient: (opts: {
+        contextPath: string;
+    }) => Promise<DisconnectableClient>;
+    /**
+     * Finds the `.kbdb` directory starting from the given base path.
+     *
+     * @param basePath - starting directory; defaults to `process.cwd()`
+     * @returns absolute path to `.kbdb` or `null` when not found
+     */
+    findDb: (basePath?: string) => string | null;
+    /**
+     * Initialises a new `.kbdb` database directory.
+     *
+     * @param options - parsed CLI options
+     */
+    runInit: (options: CliOptions) => InitResult;
+    /**
+     * Starts the MCP server using the given database path.
+     *
+     * @param contextPath - absolute path to the `.kbdb` directory
+     */
+    startMcpServer?: (contextPath: string) => Promise<void>;
+}

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

@@ -27,6 +27,8 @@ export interface CliOptions {
     format: OutputFormat;
     /** Search mode passed to the worker daemon. Defaults to `'sections'`. */
     mode: SearchMode;
+    /** Search algorithm: `'lexical'`, `'vector'`, or `'hybrid'`. */
+    algo?: string;
     /** Maximum number of results to return. Defaults to 20. */
     limit: number;
     /** Number of results to skip for pagination. */
@@ -50,6 +52,19 @@ export interface CliOptions {
     body?: string;
     /** Comma-separated skill kbids for agent create. */
     skills?: string[];
+    /**
+     * Recall expansion depth (0-3). Clamped to 3.
+     * Defaults to 0.
+     */
+    depth?: number;
+    /** Comma-separated tags for scoping (learn, recall). */
+    tags?: string[];
+    /**
+     * When `true`, enables supersession by source key (learn).
+     * Re-learning edited content replaces the original section
+     * instead of creating a sibling.
+     */
+    replace?: boolean;
     /** Positional arguments following the sub-command. */
     args: string[];
 }

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

@@ -0,0 +1,26 @@
+import type { VersionStatus } from '../../worker-client/typings/version-status.model.ts';
+import type { MigrateResult } from '../../worker-client/typings/migrate-result.model.ts';
+import type { DispatchClient } from './dispatch-client.type.ts';
+/**
+ * Extension of `DispatchClient` with lifecycle methods needed by
+ * the CLI orchestrator.
+ *
+ * Adds version checking, migration, and disconnect so the orchestrator
+ * can manage a worker-client connection across all CLI commands.
+ */
+export interface DisconnectableClient extends DispatchClient {
+    /**
+     * Checks the database version against the worker engine.
+     *
+     * @param targetPath - absolute path to the `.kbdb` database root
+     */
+    checkVersion(targetPath: string): Promise<VersionStatus>;
+    /**
+     * Runs all pending database migrations.
+     *
+     * @param targetPath - absolute path to the `.kbdb` database root
+     */
+    migrateDatabase(targetPath: string): Promise<MigrateResult>;
+    /** Disconnects from the worker daemon and releases resources. */
+    disconnect(): void;
+}

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

@@ -0,0 +1,27 @@
+import type { SearchClient } from './search-client.interface.ts';
+import type { LearnClient } from './learn-client.interface.ts';
+import type { UnlearnClient } from '../functions/run-unlearn.function.ts';
+import type { ContentClient } from '../functions/run-content.function.ts';
+import type { CheckClient } from './check-client.interface.ts';
+import type { GcClient } from '../functions/run-gc.function.ts';
+import type { RebuildClient } from '../functions/run-rebuild.function.ts';
+import type { StatusClient } from '../functions/run-status.function.ts';
+import type { DbMigrateClient } from '../functions/run-db-migrate.function.ts';
+import type { SkillLearnClient } from '../functions/run-skill-learn.function.ts';
+import type { SkillListClient } from '../functions/run-skill-list.function.ts';
+import type { SkillGetClient } from '../functions/run-skill-get.function.ts';
+import type { SkillDeleteClient } from '../functions/run-skill-delete.function.ts';
+import type { AgentCreateClient } from './agent-create-client.interface.ts';
+import type { AgentListClient } from '../functions/run-agent-list.function.ts';
+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';
+/**
+ * Intersection of all data-command client interfaces.
+ *
+ * Each run* function defines its own minimal interface; this
+ * 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;

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

@@ -0,0 +1,52 @@
+/**
+ * Minimal client interface required by `runLearn`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface LearnClient {
+    /**
+     * Ingests a content section into the knowledge base.
+     *
+     * @param params - section metadata and raw text content
+     * @returns enriched result containing the new kbid plus
+     *   optional supersession, warnings, and near-duplicate info
+     */
+    addSection(params: {
+        sectionType: string;
+        content: string;
+        title?: string;
+        description?: string;
+        docid?: string;
+        tags?: string[];
+        replace?: boolean;
+        /**
+         * Absolute path to the source file. Required for supersession
+         * via source key when `replace` is `true`.
+         */
+        sourcePath?: string;
+    }): Promise<LearnAddSectionResult>;
+}
+/** Enriched add-section result returned by the daemon. */
+export interface LearnAddSectionResult {
+    /** Knowledge-base identifier assigned to the new section. */
+    readonly kbid: string;
+    /**
+     * Kbid of the section superseded via `--replace`,
+     * or `null` / `undefined` when none.
+     */
+    readonly superseded?: string | null;
+    /**
+     * Advisory warning strings (e.g. `"heading_missing"`).
+     * May be absent from older daemon versions.
+     */
+    readonly warnings?: string[];
+    /**
+     * Near-duplicate sections with similarity >= 0.85.
+     * May be absent from older daemon versions.
+     */
+    readonly near_duplicates?: {
+        readonly kbid: string;
+        readonly similarity: number;
+    }[];
+}

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

@@ -0,0 +1,5 @@
+/** Injectable I/O for `runLearn` without real stdin. */
+export interface LearnIO {
+    /** Reads all stdin content and resolves with the full string. */
+    readStdin: () => Promise<string>;
+}

package/dist/src/shared/cli/typings/learn-result.model.d.ts

@@ -8,4 +8,23 @@ export interface LearnResult {
     size: number;
     /** `true` when the file was skipped without being ingested. */
     skipped: boolean;
+    /**
+     * Kbid of the section that was superseded via `--replace`,
+     * or `null` when no supersession occurred.
+     */
+    superseded: string | null;
+    /**
+     * Advisory warning strings returned by the engine
+     * (e.g. `"heading_missing"` when no title is provided).
+     */
+    warnings: string[];
+    /**
+     * Sections with content similarity >= 0.85 to this section.
+     * Each entry identifies a near-duplicate section and its
+     * similarity score.
+     */
+    near_duplicates: {
+        kbid: string;
+        similarity: number;
+    }[];
 }

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

@@ -0,0 +1,71 @@
+/**
+ * Minimal client interface required by `runSearch`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface SearchClient {
+    /**
+     * Searches the knowledge base and returns paginated results.
+     *
+     * @param params - query, mode, limit, and offset
+     */
+    search(params: {
+        query: string;
+        mode?: string;
+        /** Search algorithm: `'lexical'`, `'vector'`, or `'hybrid'`. */
+        algo?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<SearchClientResponse>;
+}
+/** Raw paginated search response from the daemon. */
+export interface SearchClientResponse {
+    /** Result items for the current page. */
+    readonly items: readonly SearchClientItem[];
+    /** Total number of matches across all pages. */
+    readonly total: number;
+    /** Number of results skipped. */
+    readonly offset: number;
+    /** Maximum results per page. */
+    readonly limit: number;
+    /** Whether more results exist beyond this page. */
+    readonly has_more: boolean;
+    /**
+     * When `true`, the engine relaxed the query to produce results.
+     * May be absent from older daemon versions.
+     */
+    readonly relaxed?: boolean;
+}
+/** A single raw search result item returned by the daemon. */
+export interface SearchClientItem {
+    /** Knowledge-base identifier of the matched section. */
+    readonly kbid: string;
+    /** Section heading, or null when untitled. */
+    readonly heading: string | null;
+    /** MIME type of the section content. */
+    readonly type: string;
+    /** Document IDs this section belongs to. */
+    readonly docids: readonly string[];
+    /** Relevance score from the ranking engine. */
+    readonly score: number;
+    /** KWIC excerpt centered on the highest-scoring matched term. */
+    readonly snippet: string;
+    /** Query terms that matched within this section. */
+    readonly matched_terms: readonly string[];
+    /**
+     * Fields that contained at least one match.
+     * May be absent from older daemon versions.
+     */
+    readonly matched_fields?: readonly string[];
+    /**
+     * Normalised confidence score (0.0-1.0) relative to the top result.
+     * May be absent from older daemon versions.
+     */
+    readonly confidence?: number;
+    /**
+     * ISO 8601 creation timestamp of the section.
+     * May be absent from older daemon versions.
+     */
+    readonly created_at?: string;
+}

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

@@ -10,10 +10,22 @@ export interface SearchDisplay {
     docids: readonly string[];
     /** Relevance score assigned by the ranking engine. */
     score: number;
+    /**
+     * Normalised confidence score (0.0-1.0) relative to the
+     * top result in this result set.
+     */
+    confidence: number;
     /** KWIC snippet from the WASM engine (~150 chars). */
     snippet: string;
     /** Query terms that matched within this section. */
     matched_terms: readonly string[];
+    /**
+     * Fields that contained at least one match:
+     * subset of `["heading", "body", "code"]`.
+     */
+    matched_fields: readonly string[];
+    /** ISO 8601 creation timestamp of the section. */
+    created_at: string;
     /**
      * CLI-side truncated content preview for terminal display.
      * Populated when `--content` / `-c` is used.
@@ -32,4 +44,10 @@ export interface PagedSearchDisplay {
     limit: number;
     /** Whether more results exist beyond this page. */
     has_more: boolean;
+    /**
+     * When `true`, the engine relaxed the query (e.g. dropped
+     * rare terms) to return results that would otherwise be
+     * empty.
+     */
+    relaxed: boolean;
 }

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

@@ -0,0 +1,20 @@
+import type { EmbeddingProvider } from '../typings/embedding-provider.interface.ts';
+/**
+ * No-op embedding provider used when embeddings are not configured.
+ *
+ * Satisfies the `EmbeddingProvider` contract without performing any
+ * computation. Use this as the default when no provider is selected
+ * in the config.
+ */
+export declare class NullEmbeddingProvider implements EmbeddingProvider {
+    /**
+     * Returns an empty `Float32Array` for each input text.
+     *
+     * @param texts - input strings (contents are ignored)
+     */
+    embed(texts: string[]): Promise<Float32Array[]>;
+    /** Always returns 0 -- no dimensions when disabled. */
+    dimensions(): number;
+    /** Always returns `'none'`. */
+    modelName(): string;
+}

package/dist/src/shared/embedding/constants/near-duplicate-thresholds.constant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimum Jaccard coefficient to flag a section as a near-duplicate
+ * directly via the Jaccard pass.
+ */
+export declare const JACCARD_THRESHOLD = 0.85;
+/**
+ * Lower bound of the Jaccard pre-filter band that triggers the
+ * cosine-similarity pass.
+ */
+export declare const JACCARD_BAND_MIN = 0.4;
+/**
+ * Minimum cosine similarity to flag a section as a near-duplicate
+ * via the cosine pass.
+ */
+export declare const COSINE_THRESHOLD = 0.92;

package/dist/src/shared/embedding/functions/build-vector-index.function.d.ts

@@ -0,0 +1,14 @@
+import type { VectorIndexEntry } from '../typings/vector-index-entry.model.ts';
+/**
+ * Writes a binary `vectors.idx` file to the given directory.
+ *
+ * Header: 32 bytes (magic KBVX, version u32, dimensions u32, count
+ * u32, model-name length u32, 12 reserved bytes). Followed by the
+ * model name (UTF-8) then records (64-byte kbid + dims*4 floats).
+ *
+ * @param dirPath - directory where `vectors.idx` will be written
+ * @param modelName - name of the embedding model used
+ * @param dimensions - vector dimension count
+ * @param entries - kbid/vector pairs to index
+ */
+export declare function buildVectorIndex(dirPath: string, modelName: string, dimensions: number, entries: VectorIndexEntry[]): Promise<void>;

package/dist/src/shared/embedding/functions/cosine-similarity.function.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Computes cosine similarity between two vectors.
+ *
+ * Returns `dot(a, b) / (||a|| * ||b||)`. Returns `0` when either
+ * vector has zero magnitude to avoid division by zero.
+ *
+ * @param a - first embedding vector
+ * @param b - second embedding vector
+ */
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;

package/dist/src/shared/embedding/functions/detect-near-duplicates.function.d.ts

@@ -0,0 +1,18 @@
+import type { EmbeddingProvider } from '../typings/embedding-provider.interface.ts';
+import type { NearDuplicateCandidate } from '../typings/near-duplicate-candidate.model.ts';
+import type { NearDuplicateResult } from '../typings/near-duplicate-result.model.ts';
+/**
+ * Two-pass near-duplicate detection.
+ *
+ * Pass 1: Jaccard coefficient (always runs).
+ * Pass 2: Cosine similarity on embeddings (only when `provider` is
+ * available and the Jaccard score falls in the pre-filter band
+ * [0.40, 0.85)).
+ *
+ * @param candidate - the new section to test against existing ones
+ * @param existing - known sections to compare against
+ * @param provider - optional embedding provider; when absent or null,
+ *   the cosine pass is skipped entirely
+ * @returns detected near-duplicates in the same order as `existing`
+ */
+export declare function detectNearDuplicates(candidate: NearDuplicateCandidate, existing: NearDuplicateCandidate[], provider?: EmbeddingProvider | null): NearDuplicateResult[];

package/dist/src/shared/embedding/functions/jaccard-coefficient.function.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Computes Jaccard coefficient between two token sets.
+ *
+ * `|A ∩ B| / |A ∪ B|`. Returns `0` if both sets are empty.
+ *
+ * @param a - first token set
+ * @param b - second token set
+ */
+export declare function jaccardCoefficient(a: ReadonlySet<string>, b: ReadonlySet<string>): number;

package/dist/src/shared/embedding/functions/read-vector-index-meta.function.d.ts

@@ -0,0 +1,10 @@
+import type { VectorIndexMeta } from '../typings/vector-index-meta.model.ts';
+/**
+ * Reads the 32-byte header from a `vectors.idx` file and returns
+ * the embedded `VectorIndexMeta`.
+ *
+ * @param filePath - absolute path to the `vectors.idx` file
+ * @throws {Error} if the file does not exist or the magic bytes do
+ *   not match the expected `KBVX` signature
+ */
+export declare function readVectorIndexMeta(filePath: string): VectorIndexMeta;

package/dist/src/shared/embedding/functions/rrf-fuse.function.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Fuses lexical and vector rankings using Reciprocal Rank Fusion.
+ *
+ * For each kbid in either map the fused score is:
+ * `1/(k + lexicalRank) + 1/(k + vectorRank)`.
+ * When a kbid appears in only one map the missing rank contributes
+ * `0` (treated as infinite rank -- no contribution).
+ *
+ * @param lexicalRanks - map of kbid to 1-based lexical rank position
+ * @param vectorRanks - map of kbid to 1-based vector rank position
+ * @param k - RRF smoothing constant (default 60)
+ * @returns map of kbid to fused RRF score
+ */
+export declare function rrfFuse(lexicalRanks: Map<string, number>, vectorRanks: Map<string, number>, k?: number): Map<string, number>;

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

@@ -0,0 +1,14 @@
+import type { VectorSearchResult } from '../typings/vector-search-result.model.ts';
+/**
+ * Brute-force linear scan of a `vectors.idx` file.
+ *
+ * Reads every stored vector, computes cosine similarity against
+ * `queryVector`, then returns the top `topN` results sorted by
+ * score descending.
+ *
+ * @param filePath - absolute path to the `vectors.idx` file
+ * @param queryVector - embedding to search against
+ * @param topN - maximum number of results to return
+ * @returns results sorted by descending cosine similarity score
+ */
+export declare function searchVectors(filePath: string, queryVector: Float32Array, topN: number): VectorSearchResult[];

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

@@ -0,0 +1,16 @@
+export { NullEmbeddingProvider } from './classes/null-embedding-provider.class.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 { 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 { 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';
+export type { VectorSearchResult } from './typings/vector-search-result.model.ts';
+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';

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

@@ -0,0 +1,20 @@
+/** Configuration for the embedding provider. */
+export interface EmbeddingConfig {
+    /**
+     * Provider type.
+     *
+     * - `'none'` -- embeddings disabled (default)
+     * - `'onnx'` -- local ONNX Runtime model
+     * - `'api'` -- remote HTTP embedding API
+     */
+    readonly provider: 'none' | 'onnx' | 'api';
+    /** Model name or path (for onnx/api providers). */
+    readonly model?: string;
+    /** API endpoint URL (for api provider). */
+    readonly endpoint?: string;
+    /**
+     * Number of dimensions the model produces
+     * (required for api provider).
+     */
+    readonly dimensions?: number;
+}

package/dist/src/shared/embedding/typings/embedding-provider.interface.d.ts

@@ -0,0 +1,23 @@
+/** Pluggable embedding provider interface. */
+export interface EmbeddingProvider {
+    /**
+     * Compute embedding vectors for text inputs.
+     *
+     * @param texts - list of text strings to embed
+     * @returns a Float32Array embedding for each input text,
+     *   in the same order
+     */
+    embed(texts: string[]): Promise<Float32Array[]>;
+    /**
+     * Number of dimensions in the embedding vector.
+     *
+     * Returns 0 when embeddings are disabled.
+     */
+    dimensions(): number;
+    /**
+     * Name of the underlying model.
+     *
+     * Returns `'none'` when embeddings are disabled.
+     */
+    modelName(): string;
+}

package/dist/src/shared/embedding/typings/near-duplicate-candidate.model.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A document section candidate for near-duplicate detection.
+ *
+ * Carries the token set for Jaccard comparison and an optional
+ * embedding vector for cosine-similarity comparison.
+ */
+export interface NearDuplicateCandidate {
+    /** Knowledge-base identifier for this section. */
+    readonly kbid: string;
+    /**
+     * Set of lowercased word tokens extracted from the section body.
+     *
+     * Used by the Jaccard coefficient pass.
+     */
+    readonly tokens: Set<string>;
+    /**
+     * Optional embedding vector for this section.
+     *
+     * When present and a provider is available, used as the
+     * cosine-similarity pass input.
+     */
+    readonly embedding?: Float32Array;
+}

package/dist/src/shared/embedding/typings/near-duplicate-result.model.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A near-duplicate detected by the two-pass detection algorithm.
+ *
+ * Reports which existing section matched the candidate and which
+ * detection method produced the match.
+ */
+export interface NearDuplicateResult {
+    /** Knowledge-base identifier of the matched existing section. */
+    readonly kbid: string;
+    /**
+     * Similarity score of the match (0.0–1.0).
+     *
+     * Jaccard matches use the Jaccard coefficient; cosine matches use
+     * cosine similarity.
+     */
+    readonly score: number;
+    /**
+     * Detection method that produced this match.
+     *
+     * - `'jaccard'`: Jaccard coefficient >= 0.85
+     * - `'cosine'`: cosine similarity >= 0.92 with Jaccard 0.40–0.84
+     */
+    readonly method: 'jaccard' | 'cosine';
+}

package/dist/src/shared/embedding/typings/vector-index-entry.model.d.ts

@@ -0,0 +1,12 @@
+/** A single record written into the vector index file. */
+export interface VectorIndexEntry {
+    /**
+     * Knowledge-base identifier for this section.
+     *
+     * Stored as a fixed 64-byte UTF-8 field in the index file;
+     * truncated or zero-padded as needed.
+     */
+    readonly kbid: string;
+    /** Embedding vector for this section. */
+    readonly vector: Float32Array;
+}

package/dist/src/shared/embedding/typings/vector-index-meta.model.d.ts

@@ -0,0 +1,11 @@
+/** Metadata for a vector index file. */
+export interface VectorIndexMeta {
+    /** Name of the embedding model used. */
+    readonly modelName: string;
+    /** Embedding vector dimensions. */
+    readonly dimensions: number;
+    /** Number of vectors stored. */
+    readonly count: number;
+    /** Schema version. */
+    readonly version: number;
+}