@dikolab/kbdb 0.3.0 → 0.3.2

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

@@ -0,0 +1,220 @@
+import type { AddSectionResult } from '../../worker-client/typings/add-section-result.model.ts';
+import type { RemoveSectionResult } from './remove-section-result.model.ts';
+import type { SectionRecord } from '../../wasm-codec/functions/decode-section-records.function.ts';
+import type { DocumentManifest } from '../../wasm-codec/functions/decode-document-manifest.function.ts';
+import type { McpContentResult } from './mcp-content-result.model.ts';
+import type { McpIntegrityCheckResult } from './mcp-integrity-check-result.model.ts';
+import type { McpGcResult } from './mcp-gc-result.model.ts';
+import type { McpRebuildResult } from './mcp-rebuild-result.model.ts';
+import type { McpExportResult } from './mcp-export-result.model.ts';
+/**
+ * Interface for the worker client dependency consumed by the MCP
+ * server. Defines the knowledge-base operations the server exposes
+ * as MCP tools and resources without coupling to the concrete
+ * `WorkerClient` class.
+ */
+export interface McpWorkerClient {
+    /**
+     * Searches the knowledge base using the given parameters.
+     *
+     * @param params - query string and optional search options
+     * @returns ranked list of matching section summaries
+     */
+    search(params: {
+        /** Natural language query text. */
+        readonly query: string;
+        /** Search mode: 'sections', 'documents', or 'stats'. */
+        readonly mode?: string;
+        /**
+         * Search algorithm: `'lexical'`, `'vector'`, or `'hybrid'`.
+         * Defaults to `'lexical'` when omitted.
+         */
+        readonly algo?: string;
+        /** Maximum number of results to return. */
+        readonly limit?: number;
+        /** Number of results to skip for pagination. */
+        readonly offset?: number;
+    }): Promise<{
+        readonly items: readonly {
+            readonly kbid: string;
+            readonly heading: string | null;
+            readonly type: string;
+            readonly docids: readonly string[];
+            readonly score: number;
+            readonly snippet: string;
+            readonly matched_terms: readonly string[];
+            /** Fields that contained matches (heading, body, code). */
+            readonly matched_fields?: readonly string[];
+            /** ISO 8601 creation timestamp of the section. */
+            readonly created_at?: string;
+        }[];
+        readonly total: number;
+        readonly offset: number;
+        readonly limit: number;
+        readonly has_more: boolean;
+        /**
+         * `true` when results came from an automatic AND-to-OR
+         * fallback query relaxation.
+         */
+        readonly relaxed?: boolean;
+    }>;
+    /**
+     * Adds a new section to the knowledge base.
+     *
+     * @param params - content type, raw content, and optional metadata
+     * @returns the assigned knowledge-base identifier
+     */
+    addSection(params: {
+        /** Semantic type label for the section content. */
+        readonly sectionType: string;
+        /** Raw text or base64-encoded content for the section. */
+        readonly content: string;
+        /** Optional section title. Required for image/* types. */
+        readonly title?: string;
+        /** Optional section description. */
+        readonly description?: string;
+        /** Optional document ID to group this section under. */
+        readonly docid?: string;
+        /** Optional tags for scoping and filtering. */
+        readonly tags?: string[];
+        /**
+         * When `true`, replaces an existing section that has the same
+         * source key (supersession).
+         */
+        readonly replace?: boolean;
+    }): Promise<AddSectionResult>;
+    /**
+     * Removes a section from the knowledge base.
+     *
+     * @param kbid - knowledge-base identifier of the section to remove
+     * @returns removal result with `removed` flag and elapsed time
+     */
+    removeSection(kbid: string): Promise<RemoveSectionResult>;
+    /**
+     * Retrieves one or more sections by their identifiers.
+     *
+     * @param kbids - list of knowledge-base identifiers to fetch
+     * @returns sections in the order their IDs were requested
+     */
+    readSections(kbids: string[]): Promise<{
+        /** Knowledge-base identifier for this section. */
+        kbid: string;
+        /** Semantic type label assigned to the section. */
+        sectionType: string;
+        /** Raw text content of the section. */
+        content: string;
+        /** Byte size of the stored content. */
+        size: number;
+    }[]>;
+    /**
+     * Retrieves a full document record including its ordered sections.
+     *
+     * @param docid - identifier of the document to retrieve
+     * @returns the document record as returned by the daemon
+     */
+    retrieveDocument(docid: string): Promise<unknown>;
+    /**
+     * Composes a rendered Markdown document from one or more kbid
+     * or docid identifiers.
+     *
+     * @param ids - list of kbid or docid identifiers (may be mixed)
+     * @returns composed Markdown result with character count
+     */
+    content(ids: string[]): Promise<McpContentResult>;
+    /**
+     * Returns database metadata and status from the daemon.
+     *
+     * @returns document count, section count, and timing statistics
+     */
+    dbStatus(): Promise<{
+        /** Whether the daemon has finished loading its WASM modules. */
+        initialized: boolean;
+        /** Absolute path to the context directory the daemon serves. */
+        contextPath: string;
+        /** In-memory cache statistics. */
+        cacheStats: {
+            /** Number of content entries currently cached. */
+            contentCount: number;
+            /** Number of index entries currently cached. */
+            indexCount: number;
+        };
+    }>;
+    /**
+     * 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<McpIntegrityCheckResult>;
+    /**
+     * Removes unreferenced sections from the database.
+     *
+     * @returns a report of sections removed and bytes freed
+     */
+    gc(): Promise<McpGcResult>;
+    /**
+     * Reconstructs all index files from section files and document
+     * manifests on disk.
+     *
+     * @returns a report of sections and terms re-indexed
+     */
+    rebuildIndexes(): Promise<McpRebuildResult>;
+    /**
+     * Retrieves all sections whose type name matches the given string.
+     *
+     * @param sectionType - the application-level type name to filter by
+     * @returns all section records with a matching type name
+     */
+    listByType(sectionType: string): Promise<SectionRecord[]>;
+    /**
+     * Retrieves all documents whose type name matches the given string.
+     *
+     * @param docType - the application-level document type to filter by
+     * @returns all document manifests with a matching type name
+     */
+    listDocumentsByType(docType: string): Promise<DocumentManifest[]>;
+    /**
+     * Groups a set of sections under a named document.
+     *
+     * @param title - human-readable document title
+     * @param kbids - identifiers of the sections to group
+     * @returns the assigned document identifier
+     */
+    groupSections(title: string, kbids: string[], docType?: string): Promise<string>;
+    /**
+     * Removes the document grouping for the given document.
+     *
+     * The sections themselves are not deleted; only the grouping
+     * record is removed.
+     *
+     * @param docid - identifier of the document grouping to remove
+     */
+    removeGrouping(docid: string): Promise<void>;
+    /**
+     * Retrieves full content and context for one or more sections by
+     * their knowledge-base identifiers.
+     *
+     * @param params - section identifier(s) and optional expansion depth
+     * @returns a single result or array of results depending on input
+     */
+    recall(params: {
+        /** Single section identifier. */
+        readonly kbid?: string;
+        /** Batch section identifiers. */
+        readonly kbids?: readonly string[];
+        /** Expansion depth (0-3, default: 0). */
+        readonly depth?: number;
+    }): Promise<unknown>;
+    /**
+     * Exports the database to a target directory as a self-contained
+     * snapshot (sections, documents, catalog -- no indexes).
+     *
+     * @param params - optional export parameters
+     * @returns export report with the resolved path and file counts
+     */
+    export(params?: {
+        readonly path?: string;
+    }): Promise<McpExportResult>;
+    /** Destroys the IPC socket and clears the connection state. */
+    disconnect(): void;
+}

package/dist/src/shared/mcp/typings/tool-call-result.model.d.ts

@@ -0,0 +1,17 @@
+/** Shape of a content item in an MCP tool call response. */
+export interface ToolContent {
+    /** Content type identifier, typically `'text'`. */
+    readonly type: string;
+    /** The text payload. */
+    readonly text: string;
+}
+/**
+ * Result returned by any MCP tool call handler, containing one or
+ * more content items and an optional error flag.
+ */
+export interface ToolCallResult {
+    /** One or more content items describing the result. */
+    readonly content: ToolContent[];
+    /** Set to `true` when the tool encountered an error. */
+    readonly isError?: boolean;
+}

package/dist/src/shared/sync/functions/build-import-report.function.d.ts

@@ -0,0 +1,18 @@
+import type { ConflictResolution } from '../typings/conflict-resolution.type.ts';
+import type { ExportEntry } from '../typings/export-entry.interface.ts';
+import type { ImportReport } from '../typings/import-report.interface.ts';
+/** A resolution record pairing an entry with its resolution. */
+interface ResolutionRecord {
+    /** The export entry being resolved. */
+    readonly entry: ExportEntry;
+    /** The resolution applied to the entry. */
+    readonly resolution: ConflictResolution;
+}
+/**
+ * Builds an import report from resolution results.
+ *
+ * Counts each resolution type and determines whether
+ * a database rebuild is required after the import.
+ */
+export declare function buildImportReport(resolutions: readonly ResolutionRecord[]): ImportReport;
+export {};

package/dist/src/shared/sync/functions/parse-export-entry.function.d.ts

@@ -0,0 +1,11 @@
+import type { ExportEntry } from '../typings/export-entry.interface.ts';
+/**
+ * Parses a serialized export entry.
+ *
+ * Expects TOML frontmatter delimited by `+++` lines,
+ * followed by the body content.
+ *
+ * @throws {Error} if the frontmatter delimiters are absent
+ *   or required fields are missing.
+ */
+export declare function parseExportEntry(content: string): ExportEntry;

package/dist/src/shared/sync/functions/resolve-conflict.function.d.ts

@@ -0,0 +1,13 @@
+import type { ConflictResolution } from '../typings/conflict-resolution.type.ts';
+import type { ExportEntry } from '../typings/export-entry.interface.ts';
+/**
+ * Determines the conflict resolution action for
+ * an incoming section.
+ *
+ * Rules applied in order:
+ * 1. Same kbid exists -> skip
+ * 2. Same source_key, incoming is newer -> supersede
+ * 3. Same source_key, incoming is not newer -> skip
+ * 4. No match -> add
+ */
+export declare function resolveConflict(incoming: ExportEntry, existingKbids: ReadonlySet<string>, existingBySourceKey: ReadonlyMap<string, ExportEntry>): ConflictResolution;

package/dist/src/shared/sync/functions/serialize-export-entry.function.d.ts

@@ -0,0 +1,8 @@
+import type { ExportEntry } from '../typings/export-entry.interface.ts';
+/**
+ * Serializes an export entry to a flat file format.
+ *
+ * Format: TOML frontmatter delimited by `+++` lines,
+ * followed by the body content.
+ */
+export declare function serializeExportEntry(entry: ExportEntry): string;

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

@@ -0,0 +1,9 @@
+export { resolveConflict } from './functions/resolve-conflict.function.ts';
+export { buildImportReport } from './functions/build-import-report.function.ts';
+export { serializeExportEntry } from './functions/serialize-export-entry.function.ts';
+export { parseExportEntry } from './functions/parse-export-entry.function.ts';
+export type { ExportEntry } from './typings/export-entry.interface.ts';
+export type { ExportOptions } from './typings/export-options.interface.ts';
+export type { ImportOptions } from './typings/import-options.interface.ts';
+export type { ImportReport } from './typings/import-report.interface.ts';
+export type { ConflictResolution } from './typings/conflict-resolution.type.ts';

package/dist/src/shared/sync/typings/conflict-resolution.type.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Conflict resolution strategy.
+ *
+ * - 'skip': same kbid -> skip
+ * - 'supersede': same source_key -> replace if newer
+ * - 'add': no match -> add
+ */
+export type ConflictResolution = 'skip' | 'supersede' | 'add';

package/dist/src/shared/sync/typings/export-entry.interface.d.ts

@@ -0,0 +1,13 @@
+/** A single entry in an export manifest. */
+export interface ExportEntry {
+    /** Section kbid. */
+    readonly kbid: string;
+    /** Source key. */
+    readonly sourceKey: string;
+    /** Section heading. */
+    readonly heading: string;
+    /** Content body. */
+    readonly body: string;
+    /** Created timestamp (ISO). */
+    readonly createdAt: string;
+}

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

@@ -0,0 +1,9 @@
+/** Options for export operation. */
+export interface ExportOptions {
+    /** Export format. */
+    readonly format: 'git' | 'archive';
+    /** Output directory or file path. */
+    readonly outputPath: string;
+    /** Exclude vector indexes. */
+    readonly excludeVectors: boolean;
+}

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

@@ -0,0 +1,7 @@
+/** Options for import operation. */
+export interface ImportOptions {
+    /** Source path (exported directory or archive). */
+    readonly fromPath: string;
+    /** Dry-run mode. */
+    readonly dryRun: boolean;
+}

package/dist/src/shared/sync/typings/import-report.interface.d.ts

@@ -0,0 +1,15 @@
+/** Report of an import operation. */
+export interface ImportReport {
+    /** Sections added. */
+    readonly sectionsAdded: number;
+    /** Sections skipped (same kbid). */
+    readonly sectionsSkipped: number;
+    /** Sections superseded (same source_key, newer). */
+    readonly sectionsSuperseded: number;
+    /** Documents added. */
+    readonly documentsAdded: number;
+    /** Documents skipped. */
+    readonly documentsSkipped: number;
+    /** Whether rebuild is required. */
+    readonly rebuildRequired: boolean;
+}

package/dist/src/shared/wasm-codec/functions/decode-one-recall-result.function.d.ts

@@ -0,0 +1,14 @@
+import type { DecodeResult } from './decode-string.function.ts';
+import type { RecallResult } from '../../worker-client/typings/recall-result.model.ts';
+/**
+ * Decodes a single `RecallResult` record from WASM binary output.
+ *
+ * Wire format: kbid, heading, section_type, content, docid list,
+ * document list, back_references list, siblings list,
+ * references list.
+ *
+ * @param bytes - raw binary buffer
+ * @param startOffset - byte position of the record start
+ * @returns decoded result and number of bytes consumed
+ */
+export declare function decodeOneRecallResult(bytes: Uint8Array, startOffset: number): DecodeResult<RecallResult>;

package/dist/src/shared/wasm-codec/functions/decode-option-string.function.d.ts

@@ -0,0 +1,12 @@
+import type { DecodeResult } from './decode-string.function.ts';
+/**
+ * Decodes an `Option<String>` from WASM binary output.
+ *
+ * Wire format: `u8` tag byte (`0x00` = `None`, any other value =
+ * `Some`) followed by a length-prefixed UTF-8 string when present.
+ *
+ * @param bytes - raw binary buffer
+ * @param offset - byte position of the tag byte
+ * @returns decoded nullable string and number of bytes consumed
+ */
+export declare function decodeOptionString(bytes: Uint8Array, offset: number): DecodeResult<string | null>;

package/dist/src/shared/wasm-codec/functions/decode-recall-document.function.d.ts

@@ -0,0 +1,14 @@
+import type { DecodeResult } from './decode-string.function.ts';
+import type { RecallDocument } from '../../worker-client/typings/recall-result.model.ts';
+/**
+ * Decodes a single `RecallDocument` record from WASM binary output.
+ *
+ * Wire format: docid (String), title (String), section_count (u32),
+ * then each section as kbid (String), heading (Option<String>),
+ * section_type (String).
+ *
+ * @param bytes - raw binary buffer
+ * @param offset - byte position of the record start
+ * @returns decoded document and number of bytes consumed
+ */
+export declare function decodeRecallDocument(bytes: Uint8Array, offset: number): DecodeResult<RecallDocument>;

package/dist/src/shared/wasm-codec/functions/decode-recall-reference.function.d.ts

@@ -0,0 +1,14 @@
+import type { DecodeResult } from './decode-string.function.ts';
+import type { RecallReference } from '../../worker-client/typings/recall-result.model.ts';
+/**
+ * Decodes a single `RecallReference` record from WASM binary output.
+ *
+ * Wire format: kbid (String), heading (Option<String>),
+ * section_type (String), marker_type (String),
+ * context_snippet (String), direction (String).
+ *
+ * @param bytes - raw binary buffer
+ * @param offset - byte position of the record start
+ * @returns decoded reference and number of bytes consumed
+ */
+export declare function decodeRecallReference(bytes: Uint8Array, offset: number): DecodeResult<RecallReference>;

package/dist/src/shared/wasm-codec/functions/decode-recall-sibling.function.d.ts

@@ -0,0 +1,13 @@
+import type { DecodeResult } from './decode-string.function.ts';
+import type { RecallSibling } from '../../worker-client/typings/recall-result.model.ts';
+/**
+ * Decodes a single `RecallSibling` record from WASM binary output.
+ *
+ * Wire format: kbid (String), heading (Option<String>),
+ * section_type (String), content (String).
+ *
+ * @param bytes - raw binary buffer
+ * @param offset - byte position of the record start
+ * @returns decoded sibling and number of bytes consumed
+ */
+export declare function decodeRecallSibling(bytes: Uint8Array, offset: number): DecodeResult<RecallSibling>;

package/dist/src/shared/wasm-codec/functions/decode-section-match.function.d.ts

@@ -0,0 +1,15 @@
+import type { DecodeResult } from './decode-string.function.ts';
+import type { SectionMatch } from '../typings/section-match.model.ts';
+/**
+ * Decodes a single `SectionMatch` item from WASM binary output.
+ *
+ * Wire format per item: kbid, heading (Option<String>),
+ * section_type, docids (u32 count + String[]), score (f32),
+ * confidence (f32), snippet, matched_terms (u32 + String[]),
+ * matched_fields (u32 + String[]), created_at.
+ *
+ * @param bytes - raw binary buffer
+ * @param startOffset - byte position of the item start
+ * @returns decoded match and number of bytes consumed
+ */
+export declare function decodeSectionMatch(bytes: Uint8Array, startOffset: number): DecodeResult<SectionMatch>;

package/dist/src/shared/wasm-codec/functions/decode-section-record-trailing.function.d.ts

@@ -0,0 +1,14 @@
+import type { SectionRecordTrailing } from '../typings/section-record-trailing.model.ts';
+export type { SectionRecordTrailing };
+/**
+ * Decodes the trailing backward-compatible fields of a
+ * `SectionRecord` from WASM binary output.
+ *
+ * Fields present only in newer binary output; each is guarded by a
+ * length check. Missing fields default to `null` or `[]`.
+ *
+ * @param bytes - raw bytes from a WASM section-list export
+ * @param startOffset - byte position after the `typeName` field
+ * @returns decoded trailing fields and bytes consumed
+ */
+export declare function decodeSectionRecordTrailing(bytes: Uint8Array, startOffset: number): SectionRecordTrailing;

package/dist/src/shared/wasm-codec/functions/decode-section-record.function.d.ts

@@ -0,0 +1,14 @@
+import type { DecodeResult } from './decode-string.function.ts';
+import type { SectionRecord } from '../typings/section-record.model.ts';
+/**
+ * Decodes a single `SectionRecord` from WASM binary output.
+ *
+ * Reads all section fields in the order produced by the Rust
+ * `SectionRecord::encode` implementation. Trailing fields added
+ * after `typeName` default to `null` / `[]` when absent.
+ *
+ * @param bytes - raw bytes returned by a WASM section-list export
+ * @param startOffset - byte position of the record start
+ * @returns decoded record and number of bytes consumed
+ */
+export declare function decodeSectionRecord(bytes: Uint8Array, startOffset: number): DecodeResult<SectionRecord>;

package/dist/src/shared/wasm-codec/functions/decode-section-type.function.d.ts

@@ -0,0 +1,13 @@
+import type { SectionTypeResult } from '../typings/section-type-result.model.ts';
+export type { SectionTypeResult };
+/**
+ * Decodes a section type discriminant from WASM binary output.
+ *
+ * Wire format: `u8` tag (`0x00` = text, `0x01` = code,
+ * `0x02` = image), followed by a MIME string for code/image.
+ *
+ * @param bytes - raw binary buffer
+ * @param offset - byte position of the tag byte
+ * @returns section type, optional MIME type, and bytes consumed
+ */
+export declare function decodeSectionType(bytes: Uint8Array, offset: number): SectionTypeResult;

package/dist/src/shared/wasm-codec/functions/decode-wasm-list.function.d.ts

@@ -0,0 +1,17 @@
+import type { ItemDecoder } from '../typings/item-decoder.type.ts';
+export type { ItemDecoder };
+/**
+ * Decodes a length-prefixed list from WASM binary output.
+ *
+ * Wire format: u32 item count, then that many items decoded
+ * sequentially by `decode`.
+ *
+ * @param bytes - raw binary buffer
+ * @param offset - byte position of the u32 count
+ * @param decode - decoder function for each item
+ * @returns decoded item array and total bytes consumed
+ */
+export declare function decodeWasmList<T>(bytes: Uint8Array, offset: number, decode: ItemDecoder<T>): {
+    items: T[];
+    bytesRead: number;
+};

package/dist/src/shared/wasm-codec/typings/add-section-input.model.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Parameters for adding a new section to the knowledge base.
+ *
+ * Maps to the Rust `AddSectionParams` struct encoded for the
+ * `worker_add_section` WASM export.
+ */
+export interface AddSectionInput {
+    /** Semantic content category. */
+    sectionType: 'text' | 'code' | 'image';
+    /** MIME type; required for `code` and `image` section types. */
+    mimeType?: string;
+    /** Raw section content. */
+    content: string;
+    /** Optional section heading. */
+    title?: string | null;
+    /** Optional description summary. */
+    description?: string | null;
+    /** Optional document identifier to attach the section to. */
+    docid?: string | null;
+    /**
+     * Application-level type name for the section (e.g. `'skill'`,
+     * `'fact'`). `null` means no custom type.
+     */
+    typeName?: string | null;
+    /**
+     * Absolute path of the source file being learned. `undefined`
+     * means stdin input or programmatic API call.
+     */
+    sourcePath?: string;
+    /**
+     * ISO 8601 modified time of the source file. `undefined` means
+     * no source file exists.
+     */
+    sourceMtime?: string;
+    /**
+     * User-supplied tags for scoping and filtering. Defaults to
+     * an empty list when not provided.
+     */
+    tags?: string[];
+    /**
+     * When `true`, supersede any existing section with the same
+     * source key. Defaults to `false`.
+     */
+    replace?: boolean;
+}

package/dist/src/shared/wasm-codec/typings/add-section-result.model.d.ts

@@ -0,0 +1,27 @@
+import type { NearDuplicate } from './near-duplicate.model.ts';
+/**
+ * Decoded result of a `worker_add_section` WASM call.
+ *
+ * Mirrors the Rust `AddSectionResult` struct encoded via the
+ * `Encode` trait wire format.
+ */
+export interface AddSectionResult {
+    /** Knowledge-base identifier assigned to the new section. */
+    readonly kbid: string;
+    /** Number of unique terms indexed for the section. */
+    readonly indexedTermsCount: number;
+    /** Wall-clock time the add operation took, in milliseconds. */
+    readonly elapsedMs: number;
+    /**
+     * Knowledge-base identifier of the section that was superseded,
+     * or `null` if no supersession occurred.
+     */
+    readonly superseded: string | null;
+    /** Advisory warnings emitted during indexing. */
+    readonly warnings: string[];
+    /**
+     * Near-duplicate sections detected above the similarity threshold
+     * (Jaccard ≥ 0.85).
+     */
+    readonly nearDuplicates: NearDuplicate[];
+}

package/dist/src/shared/wasm-codec/typings/document-manifest.model.d.ts

@@ -0,0 +1,19 @@
+import type { DocumentSection } from './document-section.model.ts';
+/**
+ * A document manifest decoded from WASM binary output.
+ *
+ * Represents a grouped document record with its ordered list of
+ * section references as returned by `worker_retrieve_doc`.
+ */
+export interface DocumentManifest {
+    /** Unique document identifier. */
+    docid: string;
+    /** Human-readable document title. */
+    title: string;
+    /** Document creation timestamp as a Unix epoch value. */
+    createdAt: bigint;
+    /** Application-level type name assigned to this document. */
+    docType: string;
+    /** Ordered list of section references belonging to the document. */
+    sections: DocumentSection[];
+}

package/dist/src/shared/wasm-codec/typings/document-section.model.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A single section reference within a document manifest.
+ *
+ * Associates a knowledge-base identifier with the section's
+ * ordinal position in the document.
+ */
+export interface DocumentSection {
+    /** Knowledge-base identifier of the referenced section. */
+    kbid: string;
+    /** Zero-based position of this section within its document. */
+    position: number;
+}

package/dist/src/shared/wasm-codec/typings/item-decoder.type.d.ts

@@ -0,0 +1,6 @@
+import type { DecodeResult } from '../functions/decode-string.function.ts';
+/**
+ * A function that decodes one item from a binary buffer at the
+ * given byte offset, returning the decoded value and bytes consumed.
+ */
+export type ItemDecoder<T> = (bytes: Uint8Array, offset: number) => DecodeResult<T>;

package/dist/src/shared/wasm-codec/typings/near-duplicate.model.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A near-duplicate section identified during add-section indexing.
+ */
+export interface NearDuplicate {
+    /** Knowledge-base identifier of the near-duplicate section. */
+    readonly kbid: string;
+    /** Similarity score (0.0–1.0). */
+    readonly similarity: number;
+    /**
+     * Detection method that produced this match.
+     *
+     * Optional for backward compatibility with WASM-decoded results
+     * that do not carry method information.
+     */
+    readonly method?: 'jaccard' | 'cosine';
+}