@dikolab/kbdb 0.3.1 → 0.4.0

package/dist/src/shared/worker-client/classes/worker-client.class.d.ts

@@ -14,6 +14,7 @@ import type { SectionRecord } from '../../wasm-codec/functions/decode-section-re
 import type { DocumentManifest } from '../../wasm-codec/functions/decode-document-manifest.function.ts';
 import type { RecallParams, RecallResult } from '../typings/recall-result.model.ts';
 import type { ExportResult } from '../typings/export-result.model.ts';
+import type { ImportResult } from '../typings/import-result.model.ts';
 /**
  * IPC client that communicates with the worker daemon over a Unix
  * domain socket (or Windows named pipe) using JSON-RPC 2.0 with
@@ -25,6 +26,7 @@ import type { ExportResult } from '../typings/export-result.model.ts';
 export declare class WorkerClient {
     private readonly socketPath;
     private readonly contextId;
+    private readonly requestTimeoutMs?;
     /** Underlying socket; `null` when not connected. */
     private socket;
     /** Monotonically increasing request ID counter. */
@@ -38,16 +40,33 @@ export declare class WorkerClient {
      *   (or Windows named pipe path)
      * @param contextId - 16-character context identifier sent as
      *   `ctx` in every JSON-RPC request
+     * @param requestTimeoutMs - per-request timeout in ms
+     *   (0 or undefined disables the timeout)
      */
-    constructor(socketPath: string, contextId: string);
+    constructor(socketPath: string, contextId: string, requestTimeoutMs?: number | undefined);
+    /** Whether the underlying socket is connected. */
+    get isConnected(): boolean;
     /**
      * Establishes the IPC connection to the worker daemon.
      *
+     * Retries up to 5 times with exponential backoff on
+     * transient errors (`ENOENT`, `ECONNREFUSED`).
+     *
      * @throws {Error} if the connection cannot be established
      */
     connect(): Promise<void>;
     /** Destroys the IPC socket and clears the connection state. */
     disconnect(): void;
+    /**
+     * Single connection attempt with keepalive and
+     * post-connect failure handlers.
+     */
+    private tryConnect;
+    /**
+     * Rejects all pending calls and marks the client as
+     * disconnected.
+     */
+    private handleSocketFailure;
     /**
      * Searches the knowledge base.
      *
@@ -236,7 +255,18 @@ export declare class WorkerClient {
      */
     export(params?: {
         path?: string;
+        format?: string;
     }): Promise<ExportResult>;
+    /**
+     * Imports an exported database from the given path.
+     *
+     * @param params - source path and dry-run flag
+     * @returns import report with counts and timing
+     */
+    import(params: {
+        from: string;
+        dryRun: boolean;
+    }): Promise<ImportResult>;
     /**
      * Sends a JSON-RPC 2.0 request and awaits the response.
      *

package/dist/src/shared/worker-client/constants/request-timeout.constant.d.ts

@@ -0,0 +1,2 @@
+/** Default per-request timeout for daemon IPC calls (ms). */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;

package/dist/src/shared/worker-client/constants/retry-defaults.constant.d.ts

@@ -0,0 +1,2 @@
+/** Default number of retries on request timeout. */
+export declare const DEFAULT_RETRY_COUNT = 5;

package/dist/src/shared/worker-client/functions/get-or-create-client.function.d.ts

@@ -0,0 +1,20 @@
+import type { WorkerClient } from '../classes/worker-client.class.ts';
+import type { WorkerClientOptions } from '../typings/worker-client-options.interface.ts';
+/**
+ * Returns a cached `WorkerClient` for the given context
+ * path, or creates and caches a new one if the cached
+ * client is disconnected or absent.
+ *
+ * Intended for library consumers and the MCP server. CLI
+ * one-shots should use `createWorkerClient()` directly.
+ *
+ * @param options - optional configuration forwarded to
+ *   `createWorkerClient`
+ * @returns a connected `WorkerClient`
+ */
+export declare function getOrCreateClient(options?: WorkerClientOptions): Promise<WorkerClient>;
+/**
+ * Clears the internal client cache. Intended for tests
+ * that need isolation between runs.
+ */
+export declare function clearClientCache(): void;

package/dist/src/shared/worker-client/functions/retry-on-timeout.function.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Retries an operation when the daemon responds with
+ * a `REQUEST_TIMEOUT` error. Each retry disconnects
+ * the current client, creates a fresh one (which
+ * auto-spawns the daemon), and re-runs the operation.
+ *
+ * @param createClient - factory that returns a connected client
+ * @param operation - the work to perform with the client
+ * @param maxRetries - maximum retry attempts
+ * @returns the final client and result
+ */
+export declare function retryOnTimeout<TClient extends {
+    disconnect(): void;
+}, TResult>(createClient: () => Promise<TClient>, operation: (client: TClient) => Promise<TResult>, maxRetries: number): Promise<{
+    client: TClient;
+    result: TResult;
+}>;

package/dist/src/shared/worker-client/index.d.ts

@@ -1,5 +1,6 @@
 export { WorkerClient } from './classes/worker-client.class.ts';
 export { createWorkerClient } from './functions/create-worker-client.function.ts';
+export { getOrCreateClient, clearClientCache, } from './functions/get-or-create-client.function.ts';
 export { resolveDbPath } from './functions/resolve-db-path.function.ts';
 export { computeContextId } from './functions/compute-context-id.function.ts';
 export { discoverDaemon } from './functions/discover-daemon.function.ts';
@@ -15,9 +16,11 @@ export type { DaemonInfo } from './typings/daemon-info.model.ts';
 export type { AddSectionResult, NearDuplicateEntry, } from './typings/add-section-result.model.ts';
 export type { RemoveSectionResult } from './typings/remove-section-result.model.ts';
 export type { ContentResult } from './typings/content-result.model.ts';
-export type { IntegrityCheckResult, IntegrityError, } from './typings/integrity-check-result.model.ts';
+export type { IntegrityCheckResult, IntegrityError, SemanticContradictionEntry, } from './typings/integrity-check-result.model.ts';
 export type { GcResult } from './typings/gc-result.model.ts';
 export type { RebuildResult } from './typings/rebuild-result.model.ts';
 export type { MigrateResult } from './typings/migrate-result.model.ts';
 export type { VersionCompatibility, VersionStatus, } from './typings/version-status.model.ts';
 export type { RecallParams, RecallResult, RecallDocument, RecallSibling, RecallReference, } from './typings/recall-result.model.ts';
+export type { ImportResult } from './typings/import-result.model.ts';
+export type { ExportResult } from './typings/export-result.model.ts';

package/dist/src/shared/worker-client/typings/import-result.model.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Report returned after importing an exported database into the
+ * current knowledge base.
+ */
+export interface ImportResult {
+    /** Number of sections imported. */
+    readonly sections_imported: number;
+    /** Number of documents imported. */
+    readonly documents_imported: number;
+    /** Whether a rebuild was triggered after import. */
+    readonly rebuilt: boolean;
+    /** Whether this was a dry-run (no writes). */
+    readonly dry_run: boolean;
+    /** Wall-clock time in milliseconds. */
+    readonly elapsed_ms: number;
+}

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

@@ -16,6 +16,24 @@ export interface IntegrityError {
     /** Human-readable description of the specific problem. */
     readonly detail: string;
 }
+/**
+ * Advisory finding: two sections whose embedding vectors point in
+ * opposite directions, indicating potential semantic conflict.
+ *
+ * Does not affect the `ok` field of `IntegrityCheckResult`.
+ */
+export interface SemanticContradictionEntry {
+    /** 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;
+}
 /**
  * Report returned by the daemon after running an integrity check
  * on the knowledge-base database.
@@ -33,4 +51,10 @@ export interface IntegrityCheckResult {
     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: SemanticContradictionEntry[];
 }

package/dist/src/shared/worker-client/typings/search-params.model.d.ts

@@ -11,4 +11,8 @@ export interface SearchParams {
     readonly limit?: number;
     /** Number of results to skip (pagination offset). */
     readonly offset?: number;
+    /** Search algorithm: `'lexical'`, `'vector'`, or `'hybrid'`. */
+    readonly algo?: string;
+    /** Use relaxed (OR) matching for the query. */
+    readonly relaxed?: boolean;
 }

package/dist/src/shared/worker-client/typings/search-result.model.d.ts

@@ -39,4 +39,10 @@ export interface PagedSearchResult {
     readonly limit: number;
     /** Whether more results exist beyond this page. */
     readonly has_more: boolean;
+    /** Whether the engine relaxed the query to produce results. */
+    readonly relaxed?: boolean;
+    /** Algorithm that produced these results. */
+    readonly search_mode?: string;
+    /** Retrieval strategy used (e.g. `'lexical'`, `'rrf'`). */
+    readonly retrieval_method?: string;
 }

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

@@ -27,4 +27,11 @@ export interface WorkerClientOptions {
      * `spawnDaemon` needs no runtime-specific path logic.
      */
     readonly workerScript?: string;
+    /**
+     * Per-request timeout in milliseconds for daemon IPC
+     * calls. When a request exceeds this duration, the
+     * Promise rejects with a `REQUEST_TIMEOUT` error.
+     * Defaults to `undefined` (no timeout).
+     */
+    readonly requestTimeoutMs?: number;
 }

package/dist/src/shared/worker-daemon/classes/worker-daemon.class.d.ts

@@ -21,6 +21,7 @@ export declare class WorkerDaemon {
     get connectionCount(): number;
     private _connectionCount;
     private _wasmModules;
+    private _embeddingProvider;
     private _idleAt;
     private _idleTimer;
     private _server;
@@ -121,6 +122,7 @@ export declare class WorkerDaemon {
     private dispatch;
     private dispatchWasm;
     private handleSearch;
+    private runLexicalSearch;
     private handleResultStatus;
     private handleGetResult;
     private handleAddSection;
@@ -142,6 +144,9 @@ export declare class WorkerDaemon {
     private handleGc;
     private handleRebuild;
     private handleExport;
+    private handleImport;
+    private countFiles;
+    private collectFiles;
     private scanNearDuplicates;
     private extractTermSet;
     /**

package/dist/src/shared/worker-daemon/functions/create-ipc-server.function.d.ts

@@ -1,18 +1,18 @@
 import type { Server } from 'node:net';
 import type { IpcHandler } from '../typings/ipc-handler.interface.ts';
 /**
- * Creates a Unix socket (or named pipe on Windows) IPC server that
- * reads newline-delimited JSON-RPC requests and writes responses.
+ * Creates a Unix socket (or named pipe on Windows) IPC
+ * server that reads newline-delimited JSON-RPC requests
+ * and writes responses.
  *
- * Each line received on a socket connection is parsed as an
- * `IpcRequest`, dispatched to `handler`, and the resulting
- * `IpcResponse` is written back as a newline-terminated JSON string.
- * A malformed line that cannot be parsed results in a JSON-RPC
- * parse-error response (`-32700`).
+ * Resolves after the server is bound and listening.
+ * Accepted connections have `SO_KEEPALIVE` enabled at
+ * a 30-second interval.
  *
- * @param socketPath - path to the Unix domain socket or Windows
- *   named pipe
- * @param handler - async function invoked for each valid request
+ * @param socketPath - path to the Unix domain socket or
+ *   Windows named pipe
+ * @param handler - async function invoked for each valid
+ *   request
  * @returns the listening `net.Server` instance
  */
-export declare function createIpcServer(socketPath: string, handler: IpcHandler): Server;
+export declare function createIpcServer(socketPath: string, handler: IpcHandler): Promise<Server>;

package/dist/src/shared/worker-daemon/functions/embed-after-learn.function.d.ts

@@ -0,0 +1,13 @@
+import type { EmbeddingProvider } from '../../embedding/typings/embedding-provider.interface.ts';
+/**
+ * Embeds a section's content and appends it to `vectors.idx`.
+ *
+ * Skips silently when embeddings are disabled (no provider or
+ * zero dimensions) or when the content is empty.
+ *
+ * @param provider - embedding provider (undefined = disabled)
+ * @param targetDir - path to the `.kbdb` directory
+ * @param kbid - section identifier to embed
+ * @param content - section text content
+ */
+export declare function embedAfterLearn(provider: EmbeddingProvider | undefined, targetDir: string, kbid: string, content: string): Promise<void>;

package/dist/src/shared/worker-daemon/functions/handle-hybrid-search.function.d.ts

@@ -0,0 +1,44 @@
+import type { EmbeddingProvider } from '../../embedding/typings/embedding-provider.interface.ts';
+/** Lexical search result from WASM decoder. */
+interface LexicalResult {
+    items: LexicalItem[];
+    total: number;
+    offset: number;
+    limit: number;
+    has_more: boolean;
+    relaxed: boolean;
+}
+/** A single item from the lexical search result. */
+interface LexicalItem {
+    kbid: string;
+    heading: string | null;
+    type: string;
+    docids: string[];
+    score: number;
+    confidence: number;
+    snippet: string;
+    matched_terms: string[];
+    matched_fields: string[];
+    created_at: string;
+}
+/** Search result with search_mode and retrieval_method. */
+interface FusedSearchResult extends LexicalResult {
+    search_mode: string;
+    retrieval_method: string;
+}
+/**
+ * Fuses lexical search results with vector search results.
+ *
+ * When `algo` is `'lexical'`, returns the lexical result as-is.
+ * When `algo` is `'hybrid'`, runs vector search against
+ * `vectors.idx` and fuses via RRF. When `algo` is `'vector'`,
+ * returns vector-only results.
+ *
+ * @param lexical - decoded lexical result from WASM
+ * @param algo - search algorithm: lexical, hybrid, or vector
+ * @param query - the original search query text
+ * @param provider - embedding provider (undefined = disabled)
+ * @param targetDir - path to the `.kbdb` directory
+ */
+export declare function fuseSearchResults(lexical: LexicalResult, algo: string, query: string, provider: EmbeddingProvider | undefined, targetDir: string): Promise<FusedSearchResult>;
+export {};

package/dist/src/shared/worker-daemon/functions/handle-import.function.d.ts

@@ -0,0 +1,14 @@
+import type { HandlerContext } from '../typings/handler-context.interface.ts';
+import type { ImportResult } from '../../worker-client/typings/import-result.model.ts';
+/**
+ * Handles the `importDb` IPC method.
+ *
+ * Reads sections and documents from an exported directory and
+ * feeds them back through the WASM add-section pipeline. When
+ * `dryRun` is `true`, counts files without writing.
+ *
+ * @param ctx - handler context with WASM modules
+ * @param params - `sourcePath` and `dryRun` flag
+ * @returns import report with counts and timing
+ */
+export declare function handleImport(ctx: HandlerContext, params: Record<string, unknown>): Promise<ImportResult>;

package/dist/src/shared/worker-daemon/functions/handle-read-ops.function.d.ts

@@ -4,8 +4,9 @@ import type { HandlerContext } from '../typings/handler-context.interface.ts';
  *
  * Encodes parameters, invokes the `worker_search` token pipeline,
  * waits synchronously for the result, and decodes the paged result.
+ * When `algo` is `'hybrid'` or `'vector'`, fuses with vector search.
  */
-export declare function handleSearch(ctx: HandlerContext, params: Record<string, unknown>): unknown;
+export declare function handleSearch(ctx: HandlerContext, params: Record<string, unknown>): Promise<unknown>;
 /**
  * Handles the `get_result_status` IPC method.
  */
@@ -28,6 +29,11 @@ export declare function handleRetrieveDoc(ctx: HandlerContext, params: Record<st
 export declare function handleCompose(ctx: HandlerContext, params: Record<string, unknown>): unknown;
 /**
  * Handles the `integrityCheck` IPC method.
+ *
+ * Runs the WASM integrity check and, when an embedding provider is
+ * available, appends an advisory `stale_vectors` field if the
+ * `vectors.idx` is outdated. The `ok` flag is not affected by stale
+ * vectors.
  */
 export declare function handleIntegrityCheck(ctx: HandlerContext): unknown;
 /**

package/dist/src/shared/worker-daemon/functions/handle-write-ops.function.d.ts

@@ -2,10 +2,12 @@ import type { HandlerContext } from '../typings/handler-context.interface.ts';
 /**
  * Handles the `addSection` IPC method.
  *
- * Encodes the section input, delegates to `worker_add_section`, and
- * runs a near-duplicate scan when the WASM result reports none.
+ * Encodes the section input, delegates to `worker_add_section`,
+ * runs a near-duplicate scan when the WASM result reports none,
+ * and embeds the section content when an embedding provider is
+ * configured.
  */
-export declare function handleAddSection(ctx: HandlerContext, params: Record<string, unknown>): unknown;
+export declare function handleAddSection(ctx: HandlerContext, params: Record<string, unknown>): Promise<unknown>;
 /**
  * Handles the `updateSection` IPC method.
  */
@@ -40,5 +42,8 @@ export declare function handleInvalidateAll(ctx: HandlerContext): unknown;
 export declare function handleGc(ctx: HandlerContext): unknown;
 /**
  * Handles the `rebuildIndexes` IPC method.
+ *
+ * Invokes the WASM keyword-index rebuild and, when an embedding
+ * provider is configured, also rebuilds the vector index.
  */
-export declare function handleRebuild(ctx: HandlerContext): unknown;
+export declare function handleRebuild(ctx: HandlerContext): Promise<unknown>;

package/dist/src/shared/worker-daemon/typings/handler-context.interface.d.ts

@@ -1,5 +1,6 @@
 import type { DaemonConfig } from './daemon-config.interface.ts';
 import type { WasmModules } from './wasm-modules.interface.ts';
+import type { EmbeddingProvider } from '../../embedding/typings/embedding-provider.interface.ts';
 /**
  * Runtime context passed to all IPC request handler functions.
  *
@@ -15,4 +16,6 @@ export interface HandlerContext {
     readonly config: DaemonConfig;
     /** Loaded WASM module instances. */
     readonly modules: WasmModules;
+    /** Embedding provider for vector/hybrid search. */
+    readonly embeddingProvider?: EmbeddingProvider;
 }

package/dist/wasm/fs-database/kbdb_fs_database.d.ts

@@ -3,84 +3,42 @@ declare namespace wasm_bindgen {
     /* eslint-disable */
 
     /**
-     * Adds a section. `ptr`/`len` point to an encoded `AddSectionParams`.
-     *
-     * On success: writes an encoded `AddSectionResult` to the return slot and
-     * returns 0.  When `params.replace` is true and a section with the same
-     * `source_key` exists, the superseded section's index entries are removed
-     * and the returned `AddSectionResult.superseded` is set to its kbid.
-     * On error: writes error message to return slot, returns -1.
+     * Adds a section.
      */
     export function db_add_section(ptr: number, len: number): number;
 
     /**
      * Adds a section's terms to the inverted and positional indexes.
-     * `ptr`/`len` point to encoded
-     * (kbid_str, term_count, [(term_str, pos_count, [positions], heading_tf, body_tf, code_tf)]).
      */
     export function db_add_to_index(ptr: number, len: number): number;
 
     /**
-     * Checks database integrity. Returns 0 on success.
-     * On success a summary string is placed in the return slot.
+     * Checks database integrity.
      */
     export function db_check_integrity(_ptr: number, _len: number): number;
 
     /**
-     * Reads `catalog.toml` from the path at `ptr`/`len` and returns the version
-     * status without modifying state.
-     *
-     * On success, the return slot contains 8 bytes:
-     * - bytes 0-3: `catalog_version` as little-endian u32
-     * - bytes 4-7: `required_version` (DB_FORMAT_VERSION) as little-endian u32
-     *
-     * Return value:
-     * - 0: compatible (versions match)
-     * - 1: needs migration (catalog version < required)
-     * - 2: too new (catalog version > required)
-     * - -1: I/O or parse error (message in return slot)
-     *
-     * Note: this export accepts a path directly and does NOT require `db_init`
-     * to have been called first.
+     * Reads `catalog.toml` and returns the version status.
      */
     export function db_check_version(ptr: number, len: number): number;
 
     /**
      * Exports the database to a target directory.
-     *
-     * `ptr`/`len` point to a UTF-8 string containing the target path.
-     *
-     * Copies `sections/`, `documents/`, and `catalog.toml` to the target.
-     * Indexes are not copied because they can be rebuilt from the data.
-     *
-     * The target path may be absolute or relative. It is an external output
-     * destination, not a database-internal path, so no path validation is
-     * applied to it.
-     *
-     * On success a summary string is placed in the return slot:
-     * `path={target}\nsections_exported={N}\ndocuments_exported={M}`
      */
     export function db_export(ptr: number, len: number): number;
 
     /**
-     * Runs garbage collection. Returns 0 on success.
-     * On success a summary string is placed in the return slot.
+     * Runs garbage collection.
      */
     export function db_gc(_ptr: number, _len: number): number;
 
     /**
      * Returns back-references pointing to a section.
-     * `ptr`/`len` point to a UTF-8 kbid string.
-     * On success encodes `u32 count` followed by entries (peer_id, marker_type,
-     * context_snippet) into the return slot.
      */
     export function db_get_back_refs(ptr: number, len: number): number;
 
     /**
      * Returns forward references for a section.
-     * `ptr`/`len` point to a UTF-8 kbid string.
-     * On success encodes `u32 count` followed by entries (peer_id, marker_type,
-     * context_snippet) into the return slot.
      */
     export function db_get_forward_refs(ptr: number, len: number): number;
 
@@ -94,118 +52,91 @@ declare namespace wasm_bindgen {
 
     /**
      * Initialises a new empty catalog at the current context path.
-     * Writes the default catalog to disk and returns 0 on success.
      */
     export function db_init_catalog(_ptr: number, _len: number): number;
 
     /**
-     * Creates the full directory scaffold for a new database at `ptr`/`len` path.
-     *
-     * Creates directories, seeds `catalog.toml` (stamped with `DB_FORMAT_VERSION`),
-     * empty index files, `worker.toml`, and `.gitignore`.
-     *
-     * Returns 0 on success. Returns -1 with an error message in the return slot
-     * if the directory already exists or any I/O fails.
-     *
-     * Note: this export accepts a path directly and does NOT require `db_init`
-     * to have been called first.
+     * Creates the full directory scaffold for a new database.
      */
     export function db_init_directory(ptr: number, len: number): number;
 
     /**
-     * Lists all document manifests. No input parameters (`ptr`/`len` are ignored).
-     *
-     * On success encodes a `u32 count` followed by each `DocumentManifest` into
-     * the return slot and returns 0. On error writes an error message and returns -1.
+     * Lists all document manifests.
      */
     export function db_list_documents(_ptr: number, _len: number): number;
 
     /**
-     * Lists all section records. No input parameters (`ptr`/`len` are ignored).
-     *
-     * On success encodes a `u32 count` followed by each `SectionRecord` into the
-     * return slot and returns 0. On error writes an error message and returns -1.
+     * Lists all section records.
      */
     export function db_list_sections(_ptr: number, _len: number): number;
 
     /**
      * Executes a query plan against the loaded indexes.
-     * `ptr`/`len` point to an encoded `QueryPlan`.
-     * On success writes encoded `Vec<RawMatch>` to the return slot.
      */
     export function db_query(ptr: number, len: number): number;
 
     /**
-     * Reads the catalog. Returns 0 on success.
-     * On success the serialised catalog TOML text is in the return slot.
+     * Reads the catalog.
      */
     export function db_read_catalog(_ptr: number, _len: number): number;
 
     /**
      * Reads corpus statistics from `<ctx>/corpus.bin`.
-     * On success places encoded `CorpusStats` bytes in the return slot.
      */
     export function db_read_corpus_stats(_ptr: number, _len: number): number;
 
     /**
-     * Reads a document manifest. `ptr`/`len` point to a UTF-8 docid string.
+     * Reads a document manifest.
      */
     export function db_read_document(ptr: number, len: number): number;
 
     /**
-     * Reads a section by kbid. `ptr`/`len` point to a UTF-8 kbid string.
+     * Reads a section by kbid.
      */
     export function db_read_section(ptr: number, len: number): number;
 
     /**
-     * Reads multiple sections. `ptr`/`len` point to encoded `Vec<KbId>` (count + kbids).
+     * Reads multiple sections.
      */
     export function db_read_sections(ptr: number, len: number): number;
 
     /**
      * Rebuilds indexes from scratch.
-     *
-     * Clears the existing inverted and positional indexes, then drives the
-     * section-scan rebuild loop. Full per-field tokenization is handled by
-     * `kb-worker.wasm` orchestration; this function provides the read-pass
-     * scaffolding and the final index write.
      */
     export function db_rebuild_index(_ptr: number, _len: number): number;
 
     /**
-     * Removes a document manifest. `ptr`/`len` point to a UTF-8 docid string.
+     * Removes a document manifest.
      */
     export function db_remove_document(ptr: number, len: number): number;
 
     /**
      * Removes a section's entries from the indexes.
-     * `ptr`/`len` point to a UTF-8 kbid string.
      */
     export function db_remove_from_index(ptr: number, len: number): number;
 
     /**
-     * Removes a section by kbid. `ptr`/`len` point to a UTF-8 kbid string.
+     * Removes a section by kbid.
      */
     export function db_remove_section(ptr: number, len: number): number;
 
     /**
-     * Updates a section. `ptr`/`len` point to encoded (old_kbid_str, AddSectionParams).
+     * Updates a section.
      */
     export function db_update_section(ptr: number, len: number): number;
 
     /**
-     * Writes/updates the catalog. `ptr`/`len` point to encoded catalog TOML text.
+     * Writes/updates the catalog.
      */
     export function db_write_catalog(ptr: number, len: number): number;
 
     /**
      * Writes corpus statistics to `<ctx>/corpus.bin`.
-     * `ptr`/`len` point to 12 bytes of encoded `CorpusStats`.
      */
     export function db_write_corpus_stats(ptr: number, len: number): number;
 
     /**
-     * Writes a document manifest. `ptr`/`len` point to an encoded `DocumentManifest`.
+     * Writes a document manifest.
      */
     export function db_write_document(ptr: number, len: number): number;