@dikolab/kbdb 0.2.2 → 0.3.1

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

@@ -0,0 +1,31 @@
+/**
+ * A single ranked result item from a paged search response.
+ */
+export interface SectionMatch {
+    /** Knowledge-base identifier for the matched section. */
+    kbid: string;
+    /** Section heading, or `null` when untitled. */
+    heading: string | null;
+    /** MIME type of the section content. */
+    type: string;
+    /** Document IDs this section belongs to. */
+    docids: string[];
+    /** Relevance score from the ranking engine. */
+    score: number;
+    /**
+     * Confidence modifier (0.0–1.0) applied after relaxed search.
+     * Always 1.0 for strict-mode results.
+     */
+    confidence: number;
+    /** KWIC snippet (~150 chars around the best match). */
+    snippet: string;
+    /** Query terms that matched within this section. */
+    matched_terms: string[];
+    /**
+     * Document fields that contained at least one matched term
+     * (e.g. `'title'`, `'body'`).
+     */
+    matched_fields: string[];
+    /** ISO 8601 creation timestamp of the section. */
+    created_at: string;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Trailing backward-compatible fields of a section record.
+ *
+ * These fields were added after the initial wire format. When
+ * decoding legacy binary output that stops before these fields,
+ * each defaults to `null` or `[]`.
+ */
+export interface SectionRecordTrailing {
+    /**
+     * Stable logical identity derived from source path and heading.
+     * `null` for stdin input or sections without a source path.
+     */
+    sourceKey: string | null;
+    /**
+     * Absolute path of the source file that was learned.
+     * `null` for stdin input or programmatic API calls.
+     */
+    sourcePath: string | null;
+    /**
+     * ISO 8601 modified time of the source file at learn time.
+     * `null` when no source file exists.
+     */
+    sourceMtime: string | null;
+    /**
+     * ISO 8601 timestamp of the last supersession.
+     * `null` on first creation.
+     */
+    updatedAt: string | null;
+    /** User-supplied tags for scoping and filtering. */
+    tags: string[];
+    /**
+     * The kbid of the section this one replaced via supersession.
+     * `null` on first creation or non-superseding additions.
+     */
+    supersedes: string | null;
+    /** Number of bytes consumed from the buffer. */
+    bytesRead: number;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * A single section record decoded from WASM binary output.
+ *
+ * Represents a stored knowledge-base section with all its metadata
+ * and token counts as returned by `worker_read_sections` or
+ * `worker_list_by_type`.
+ */
+export interface SectionRecord {
+    /** Unique knowledge-base identifier for this section. */
+    kbid: string;
+    /** Document identifier this section belongs to, or `null`. */
+    docid: string | null;
+    /** Semantic type discriminant: `'text'`, `'code'`, or `'image'`. */
+    sectionType: string;
+    /** MIME type string, present only for `'code'` and `'image'` types. */
+    mimeType?: string;
+    /** Human-readable title for the section, or `null`. */
+    title: string | null;
+    /** Optional description of the section content, or `null`. */
+    description: string | null;
+    /** Raw text or base64-encoded content of the section. */
+    content: string;
+    /** Byte size of the stored content. */
+    size: number;
+    /** Section creation timestamp as a Unix epoch value. */
+    createdAt: bigint;
+    /** Integrity checksum of the stored content. */
+    checksum: string;
+    /** Total number of tokens in the section. */
+    tokenCount: number;
+    /** Number of heading tokens in the section. */
+    headingTokenCount: number;
+    /** Number of body tokens in the section. */
+    bodyTokenCount: number;
+    /** Number of code tokens in the section. */
+    codeTokenCount: number;
+    /** Application-level type name assigned to this section. */
+    typeName: string;
+    /**
+     * Stable logical identity derived from source path and heading.
+     * `null` for stdin input or sections without a source path.
+     */
+    sourceKey: string | null;
+    /**
+     * Absolute path of the source file that was learned.
+     * `null` for stdin input or programmatic API calls.
+     */
+    sourcePath: string | null;
+    /**
+     * ISO 8601 modified time of the source file at learn time.
+     * `null` when no source file exists.
+     */
+    sourceMtime: string | null;
+    /**
+     * ISO 8601 timestamp of the last supersession.
+     * `null` on first creation.
+     */
+    updatedAt: string | null;
+    /** User-supplied tags for scoping and filtering. */
+    tags: string[];
+    /**
+     * The kbid of the section this one replaced via supersession.
+     * `null` on first creation or non-superseding additions.
+     */
+    supersedes: string | null;
+}

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

@@ -0,0 +1,12 @@
+/** Result of decoding a section type discriminant from binary output. */
+export interface SectionTypeResult {
+    /** Semantic section category: `'text'`, `'code'`, or `'image'`. */
+    sectionType: string;
+    /**
+     * MIME type string, present only for `'code'` and `'image'`
+     * types.
+     */
+    mimeType?: string;
+    /** Number of bytes consumed from the buffer. */
+    bytesRead: number;
+}

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

@@ -13,6 +13,7 @@ import type { VersionStatus } from '../typings/version-status.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 { RecallParams, RecallResult } from '../typings/recall-result.model.ts';
+import type { ExportResult } from '../typings/export-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
@@ -221,6 +222,21 @@ export declare class WorkerClient {
      * @returns all document manifests with a matching type name
      */
     listDocumentsByType(docType: string): Promise<DocumentManifest[]>;
+    /**
+     * Exports the database to a target directory on disk.
+     *
+     * Copies section files, document manifests, and `catalog.toml`
+     * to `params.path`. Index files are not exported because they
+     * are derivable from the section and document data.
+     *
+     * @param params - optional export parameters
+     * @param params.path - target directory path; defaults to
+     *   `./kbdb-export/` when not provided
+     * @returns export report with the resolved path and file counts
+     */
+    export(params?: {
+        path?: string;
+    }): Promise<ExportResult>;
     /**
      * Sends a JSON-RPC 2.0 request and awaits the response.
      *

package/dist/src/shared/worker-client/functions/handle-ipc-data.function.d.ts

@@ -0,0 +1,16 @@
+import type { PendingCall } from '../typings/pending-call.interface.ts';
+/**
+ * Processes an incoming data chunk from the IPC socket.
+ *
+ * Appends the chunk to `buffer`, splits on newline boundaries,
+ * parses complete JSON-RPC response lines, and resolves or rejects
+ * the matching pending call. Returns the updated buffer with any
+ * incomplete trailing line retained.
+ *
+ * @param data - raw string chunk received from the socket
+ * @param buffer - partial line buffer from the previous call
+ * @param pending - map of outstanding request IDs to their
+ *   resolve/reject pairs; mutated by this function
+ * @returns the updated buffer (incomplete trailing line, if any)
+ */
+export declare function handleIpcData(data: string, buffer: string, pending: Map<number, PendingCall>): string;

package/dist/src/shared/worker-client/functions/send-ipc-request.function.d.ts

@@ -0,0 +1,19 @@
+import type { Socket } from 'node:net';
+import type { PendingCall } from '../typings/pending-call.interface.ts';
+/**
+ * Sends a JSON-RPC 2.0 request over `socket` and registers the
+ * `resolve`/`reject` pair in `pending` so the response can be
+ * matched back.
+ *
+ * @param socket - connected IPC socket
+ * @param pending - map of outstanding request IDs to their
+ *   resolve/reject pairs; mutated by this function
+ * @param nextId - the request ID to assign; must be the current
+ *   value of the caller's monotonic counter
+ * @param contextId - 16-character context identifier sent as `ctx`
+ * @param method - JSON-RPC method name
+ * @param params - method parameters (merged with `ctx`)
+ * @throws {Error} when the socket is not connected (`socket` is
+ *   null) -- call the check before invoking this function
+ */
+export declare function sendIpcRequest(socket: Socket, pending: Map<number, PendingCall>, nextId: number, contextId: string, method: string, params: unknown): Promise<unknown>;

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

@@ -12,7 +12,7 @@ export type { Section, AddSectionParams, } from './typings/section.model.ts';
 export type { StatusResult } from './typings/status-result.model.ts';
 export type { WorkerClientError } from './typings/worker-client-error.interface.ts';
 export type { DaemonInfo } from './typings/daemon-info.model.ts';
-export type { AddSectionResult } from './typings/add-section-result.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';

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

@@ -1,22 +1,38 @@
+/**
+ * A near-duplicate section reported after adding a new section.
+ */
+export interface NearDuplicateEntry {
+    /** Knowledge-base identifier of the near-duplicate section. */
+    readonly kbid: string;
+    /** Jaccard similarity score (0.0--1.0). */
+    readonly similarity: number;
+    /** Detection method that produced this match. */
+    readonly method?: 'jaccard' | 'cosine';
+}
 /** Result returned by the daemon after adding a new section. */
 export interface AddSectionResult {
     /** Knowledge-base identifier assigned to the section. */
     readonly kbid: string;
-    /** MIME type of the stored section. */
-    readonly type: string;
-    /** Section title, if provided. */
-    readonly title?: string;
-    /** Section description, if provided. */
-    readonly description?: string;
-    /** Total token count for the section. */
-    readonly token_count: number;
-    /** Number of unique terms indexed for this section. */
-    readonly indexed_terms_count: number;
-    /** Time taken to process and store the section, in milliseconds. */
-    readonly elapsed_ms: number;
     /**
-     * `true` when the content already existed and the provided docid
-     * was added to the existing section's `docids` list.
+     * Number of unique terms indexed for the section.
+     * Present in the current binary-decoded response format.
+     */
+    readonly indexed_terms_count?: number;
+    /**
+     * Wall-clock time the add operation took, in milliseconds.
+     * Present in the current binary-decoded response format.
+     */
+    readonly elapsed_ms?: 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 attached: boolean;
+    readonly near_duplicates?: NearDuplicateEntry[];
 }

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

@@ -0,0 +1,14 @@
+/**
+ * Report returned by the daemon after exporting the database to a
+ * target directory.
+ */
+export interface ExportResult {
+    /** Absolute path to the directory where files were written. */
+    readonly path: string;
+    /** Number of section files copied to the export directory. */
+    readonly sections_exported: number;
+    /** Number of document manifest files copied. */
+    readonly documents_exported: number;
+    /** Wall-clock time the export operation took, in milliseconds. */
+    readonly elapsed_ms: number;
+}

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

@@ -9,4 +9,10 @@ export interface GcResult {
     readonly removed_bytes: number;
     /** Time taken to complete garbage collection, in milliseconds. */
     readonly elapsed_ms: number;
+    /**
+     * Number of sections whose source_path file no longer contains
+     * their heading text. Advisory; not auto-removed by gc.
+     * Absent on older daemon versions.
+     */
+    readonly stale_sources?: number;
 }

package/dist/src/shared/worker-client/typings/json-rpc-response.interface.d.ts

@@ -0,0 +1,16 @@
+/** Shape of a JSON-RPC 2.0 error object from the daemon. */
+export interface JsonRpcError {
+    /** Numeric JSON-RPC error code. */
+    readonly code: number;
+    /** Human-readable error message. */
+    readonly message: string;
+}
+/** Shape of a JSON-RPC 2.0 response from the daemon. */
+export interface JsonRpcResponse {
+    /** Monotonically increasing request identifier. */
+    readonly id: number;
+    /** Result payload; present on success. */
+    readonly result?: unknown;
+    /** Error detail; present on failure. */
+    readonly error?: JsonRpcError;
+}

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

@@ -0,0 +1,7 @@
+/** Pending JSON-RPC call awaiting a response from the daemon. */
+export interface PendingCall {
+    /** Resolves with the result when the daemon responds. */
+    resolve: (v: unknown) => void;
+    /** Rejects with an error when the daemon returns an error. */
+    reject: (e: Error) => void;
+}

package/dist/src/shared/worker-client/typings/recall-document.model.d.ts

@@ -0,0 +1,16 @@
+/** A document record included at depth >= 1. */
+export interface RecallDocument {
+    /** Unique document identifier. */
+    readonly docid: string;
+    /** Human-readable document title. */
+    readonly title: string;
+    /** Ordered list of section summaries belonging to this document. */
+    readonly sections: readonly {
+        /** Knowledge-base identifier of the section. */
+        readonly kbid: string;
+        /** Section heading text, or `null` when absent. */
+        readonly heading: string | null;
+        /** Semantic type label for the section. */
+        readonly type: string;
+    }[];
+}

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

@@ -0,0 +1,15 @@
+/** Parameters for a recall operation. */
+export interface RecallParams {
+    /** Single section identifier to recall. */
+    readonly kbid?: string;
+    /** Batch of section identifiers to recall. */
+    readonly kbids?: readonly string[];
+    /**
+     * Context expansion depth (0-3).
+     *
+     * At depth 0 only the section itself is returned.
+     * Higher values include progressively more context:
+     * documents, siblings, and references.
+     */
+    readonly depth?: number;
+}

package/dist/src/shared/worker-client/typings/recall-reference.model.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A section that references or is referenced by the recalled
+ * section.
+ */
+export interface RecallReference {
+    /**
+     * Knowledge-base identifier of the referencing/referenced
+     * section.
+     */
+    readonly kbid: string;
+    /**
+     * Heading text of the referencing section, or `null` when
+     * absent.
+     */
+    readonly heading: string | null;
+    /** Semantic type label of the referencing section. */
+    readonly type: string;
+    /**
+     * Application-level marker type (e.g. `'see_also'`, `'link'`).
+     */
+    readonly marker_type: string;
+    /**
+     * Short excerpt from the referencing section surrounding the
+     * marker.
+     */
+    readonly context_snippet: string;
+    /**
+     * Whether the reference is `'forward'` (outgoing) or `'back'`
+     * (incoming).
+     */
+    readonly direction: 'forward' | 'back';
+}

package/dist/src/shared/worker-client/typings/recall-sibling.model.d.ts

@@ -0,0 +1,11 @@
+/** A sibling section adjacent to the recalled section. */
+export interface RecallSibling {
+    /** Knowledge-base identifier of the sibling section. */
+    readonly kbid: string;
+    /** Sibling heading text, or `null` when absent. */
+    readonly heading: string | null;
+    /** Semantic type label for the sibling section. */
+    readonly type: string;
+    /** Full text content of the sibling section. */
+    readonly content: string;
+}

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

@@ -0,0 +1,40 @@
+import type { RecallDocument } from './recall-document.model.ts';
+import type { RecallReference } from './recall-reference.model.ts';
+import type { RecallSibling } from './recall-sibling.model.ts';
+/** Full content and context for a recalled knowledge-base section. */
+export interface RecallResult {
+    /** Knowledge-base identifier of the recalled section. */
+    readonly kbid: string;
+    /** Section heading text, or `null` when absent. */
+    readonly heading: string | null;
+    /** Semantic type label for the section. */
+    readonly type: string;
+    /** Full text content of the section. */
+    readonly content: string;
+    /** Identifiers of documents that contain this section. */
+    readonly docids: readonly string[];
+    /**
+     * Full document records containing this section.
+     *
+     * Populated when `depth >= 1`.
+     */
+    readonly documents?: readonly RecallDocument[];
+    /**
+     * Sections that contain a marker pointing back to this section.
+     *
+     * Populated when `depth >= 1`.
+     */
+    readonly back_references?: readonly RecallReference[];
+    /**
+     * Sections adjacent to this section in the same document.
+     *
+     * Populated when `depth >= 1`.
+     */
+    readonly siblings?: readonly RecallSibling[];
+    /**
+     * Sections that this section points to via markers.
+     *
+     * Populated when `depth >= 1`.
+     */
+    readonly references?: readonly RecallReference[];
+}

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

@@ -14,6 +14,18 @@ export interface SearchResult {
     readonly snippet: string;
     /** Query terms that matched within this section. */
     readonly matched_terms: readonly string[];
+    /**
+     * Fields that contained at least one match
+     * (e.g. `'heading'`, `'body'`).
+     */
+    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. */
+    readonly created_at?: string;
 }
 /** Paginated search result envelope. */
 export interface PagedSearchResult {

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

@@ -23,4 +23,20 @@ export interface AddSectionParams {
     readonly content: string;
     /** Parent document identifier to associate the section with. */
     readonly docid?: string;
+    /** Human-readable heading for the section. */
+    readonly title?: string;
+    /** Short summary or description of the section. */
+    readonly description?: string;
+    /** Application-defined tags for scoping and filtering. */
+    readonly tags?: string[];
+    /**
+     * When `true`, supersedes an existing section with the same
+     * source key (derived from `sourcePath` and `title`).
+     */
+    readonly replace?: boolean;
+    /**
+     * Absolute path to the source file. Required for supersession
+     * via source key when `replace` is `true`.
+     */
+    readonly sourcePath?: string;
 }

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

@@ -0,0 +1,17 @@
+/**
+ * Typed JSON-RPC error thrown inside WorkerDaemon dispatch.
+ *
+ * Carries a numeric JSON-RPC error code alongside the standard
+ * `Error` message so that `handleRequest` can build a well-formed
+ * JSON-RPC error response without an additional type check.
+ */
+export declare class IpcError extends Error {
+    /** JSON-RPC error code. */
+    readonly code: number;
+    /**
+     * @param code - JSON-RPC error code (e.g. `-32601` for
+     *   method-not-found, `-32000` for application errors)
+     * @param message - human-readable error description
+     */
+    constructor(code: number, message: string);
+}

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

@@ -25,6 +25,14 @@ export declare class WorkerDaemon {
     private _idleTimer;
     private _server;
     private readonly _wasmDir;
+    /** Queue of waiters for the single-writer lock. */
+    private _writeQueue;
+    /** Whether the write lock is currently held. */
+    private _writeLocked;
+    /** Whether the startup integrity check passed. */
+    private _integrityOk;
+    /** Integrity errors found at startup, if any. */
+    private _integrityErrors;
     /**
      * @param ctx - context ID (16-hex characters), the first 16 of
      *   the SHA-256 hash of `targetDir`
@@ -133,7 +141,34 @@ export declare class WorkerDaemon {
     private handleIntegrityCheck;
     private handleGc;
     private handleRebuild;
+    private handleExport;
+    private scanNearDuplicates;
+    private extractTermSet;
+    /**
+     * Acquires the write lock.
+     *
+     * If the lock is free it is granted immediately. If it is held the
+     * caller is queued and its promise resolves once the lock is
+     * released by the current holder.
+     */
+    private acquireWriteLock;
+    /**
+     * Releases the write lock.
+     *
+     * If waiters are queued the next one is granted the lock
+     * immediately. Otherwise the lock is marked free.
+     */
+    private releaseWriteLock;
     private initWorkerContext;
+    /**
+     * Runs a database integrity check immediately after context
+     * initialisation.
+     *
+     * Stores the result in `_integrityOk` and `_integrityErrors`.
+     * Logs a warning to stderr when issues are found so operators
+     * are alerted without aborting the daemon.
+     */
+    private runStartupIntegrityCheck;
     private getExport;
     private wasmAlloc;
     private wasmFree;

package/dist/src/shared/worker-daemon/constants/wasm-method-map.constant.d.ts

@@ -0,0 +1,16 @@
+import type { DaemonConfig } from '../typings/daemon-config.interface.ts';
+/**
+ * Maps incoming IPC method names to `kb-worker.wasm` export names.
+ *
+ * Both camelCase and snake_case variants of each method are
+ * included so that clients may use either convention.
+ */
+export declare const WASM_METHOD_MAP: Readonly<Partial<Record<string, string>>>;
+/** Prefix shared by all IPC config-accessor method names. */
+export declare const CONFIG_PREFIX = "config_";
+/**
+ * Maps config IPC key suffixes to `DaemonConfig` property names.
+ *
+ * A client sends `config_timeout_ms` to read `config.timeoutMs`.
+ */
+export declare const CONFIG_KEY_MAP: Readonly<Partial<Record<string, keyof DaemonConfig>>>;

package/dist/src/shared/worker-daemon/functions/build-ipc-error-response.function.d.ts

@@ -0,0 +1,9 @@
+import type { IpcResponse } from '../typings/ipc-handler.interface.ts';
+/**
+ * Builds a JSON-RPC 2.0 error response object.
+ *
+ * @param id - request identifier to echo back in the response
+ * @param code - JSON-RPC error code
+ * @param message - human-readable error description
+ */
+export declare function buildIpcErrorResponse(id: number | string, code: number, message: string): IpcResponse;

package/dist/src/shared/worker-daemon/functions/check-catalog-version.function.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reads `catalog.toml` in `targetDir` and validates its version
+ * against `DB_FORMAT_VERSION`.
+ *
+ * @param targetDir - absolute path to the `.kbdb` directory
+ * @throws {Error} when the catalog cannot be read, is missing a
+ *   version, or the version is incompatible with the current engine
+ */
+export declare function checkCatalogVersion(targetDir: string): void;

package/dist/src/shared/worker-daemon/functions/check-preconditions.function.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Validates startup preconditions for the worker daemon.
+ *
+ * Checks that `targetDir` exists, is readable and writable, and
+ * that `catalog.toml` reports a compatible format version.
+ *
+ * @param targetDir - absolute path to the `.kbdb` directory
+ * @throws {Error} when any precondition fails
+ */
+export declare function checkPreconditions(targetDir: string): void;

package/dist/src/shared/worker-daemon/functions/detect-stale-pid.function.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Checks whether a PID file contains a stale process ID.
+ *
+ * Reads the PID from the file and checks whether the process is
+ * still running using `process.kill(pid, 0)`. If the process is
+ * dead, or the PID is unparseable, removes the PID file and
+ * returns `true`. Returns `false` when the process is alive or
+ * the file does not exist.
+ *
+ * @param pidPath - absolute path to the PID file to inspect
+ * @returns `true` if the PID file is stale (process dead or
+ *   content invalid) and was removed; `false` if the process is
+ *   alive or the file does not exist
+ */
+export declare function detectStalePid(pidPath: string): boolean;