@dikolab/kbdb 0.2.1 → 0.3.0

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,36 @@
+/**
+ * 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;
+}
 /** 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/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/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/wasm/fs-database/kbdb_fs_database.d.ts

@@ -5,7 +5,10 @@ declare namespace wasm_bindgen {
     /**
      * Adds a section. `ptr`/`len` point to an encoded `AddSectionParams`.
      *
-     * On success: writes encoded kbid string to return slot, returns 0.
+     * 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.
      */
     export function db_add_section(ptr: number, len: number): number;
@@ -42,6 +45,23 @@ declare namespace wasm_bindgen {
      */
     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.
@@ -200,6 +220,7 @@ declare interface InitOutput {
     readonly db_add_to_index: (a: number, b: number) => number;
     readonly db_check_integrity: (a: number, b: number) => number;
     readonly db_check_version: (a: number, b: number) => number;
+    readonly db_export: (a: number, b: number) => number;
     readonly db_gc: (a: number, b: number) => number;
     readonly db_get_back_refs: (a: number, b: number) => number;
     readonly db_get_forward_refs: (a: number, b: number) => number;

package/dist/wasm/fs-database/kbdb_fs_database.js

@@ -7,7 +7,10 @@ let wasm_bindgen = (function(exports) {
     /**
      * Adds a section. `ptr`/`len` point to an encoded `AddSectionParams`.
      *
-     * On success: writes encoded kbid string to return slot, returns 0.
+     * 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.
      * @param {number} ptr
      * @param {number} len
@@ -72,6 +75,30 @@ let wasm_bindgen = (function(exports) {
     }
     exports.db_check_version = db_check_version;
 
+    /**
+     * 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}`
+     * @param {number} ptr
+     * @param {number} len
+     * @returns {number}
+     */
+    function db_export(ptr, len) {
+        const ret = wasm.db_export(ptr, len);
+        return ret;
+    }
+    exports.db_export = db_export;
+
     /**
      * Runs garbage collection. Returns 0 on success.
      * On success a summary string is placed in the return slot.

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

@@ -7,6 +7,7 @@ export const db_add_section: (a: number, b: number) => number;
 export const db_add_to_index: (a: number, b: number) => number;
 export const db_check_integrity: (a: number, b: number) => number;
 export const db_check_version: (a: number, b: number) => number;
+export const db_export: (a: number, b: number) => number;
 export const db_gc: (a: number, b: number) => number;
 export const db_get_back_refs: (a: number, b: number) => number;
 export const db_get_forward_refs: (a: number, b: number) => number;

package/dist/wasm/kb-worker/kbdb_worker.d.ts

@@ -5,7 +5,10 @@ declare namespace wasm_bindgen {
     /**
      * Adds a section. `ptr`/`len` point to an encoded `AddSectionParams`.
      *
-     * On success: writes encoded kbid string to return slot, returns 0.
+     * 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.
      */
     export function db_add_section(ptr: number, len: number): number;
@@ -42,6 +45,23 @@ declare namespace wasm_bindgen {
      */
     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.
@@ -344,6 +364,10 @@ declare namespace wasm_bindgen {
 
     /**
      * Adds a section. Returns 0 on success, -1 on error.
+     *
+     * On success the return slot holds the binary-encoded `AddSectionResult`
+     * (kbid + indexed_terms_count + elapsed_ms + superseded + warnings +
+     * near_duplicates) using the `Encode` trait wire format.
      */
     export function worker_add_section(ptr: number, len: number): number;
 
@@ -365,6 +389,19 @@ declare namespace wasm_bindgen {
      */
     export function worker_compose(ptr: number, len: number): number;
 
+    /**
+     * Exports the database to a target directory.
+     *
+     * `ptr`/`len` point to a UTF-8 string containing the target path.
+     *
+     * Delegates directly to `db_export` in `kbdb-fs-database`. Does not require
+     * the worker to have been initialised because the target path is given
+     * explicitly by the caller.
+     *
+     * Returns 0 on success, -1 on error (message in return slot).
+     */
+    export function worker_export(ptr: number, len: number): number;
+
     /**
      * Runs garbage collection and invalidates all cache entries.
      *
@@ -444,6 +481,14 @@ declare namespace wasm_bindgen {
 
     /**
      * Rebuilds all database indexes.
+     *
+     * First clears the existing inverted, positional, and reference indexes via
+     * `db_rebuild_index`. Then re-tokenizes every stored section and re-populates
+     * the indexes via `rebuild_all_section_indexes`.
+     *
+     * On success the return slot holds the number of reindexed sections as a
+     * little-endian `u32`, and 0 is returned. On error -1 is returned and an
+     * error message is in the return slot.
      */
     export function worker_rebuild_indexes(): number;
 
@@ -525,6 +570,7 @@ declare interface InitOutput {
     readonly worker_add_section: (a: number, b: number) => number;
     readonly worker_check_integrity: () => number;
     readonly worker_compose: (a: number, b: number) => number;
+    readonly worker_export: (a: number, b: number) => number;
     readonly worker_garbage_collect: () => number;
     readonly worker_get_result: (a: number) => number;
     readonly worker_group_sections: (a: number, b: number) => number;
@@ -565,6 +611,7 @@ declare interface InitOutput {
     readonly db_add_to_index: (a: number, b: number) => number;
     readonly db_check_integrity: (a: number, b: number) => number;
     readonly db_check_version: (a: number, b: number) => number;
+    readonly db_export: (a: number, b: number) => number;
     readonly db_gc: (a: number, b: number) => number;
     readonly db_get_back_refs: (a: number, b: number) => number;
     readonly db_get_forward_refs: (a: number, b: number) => number;

package/dist/wasm/kb-worker/kbdb_worker.js

@@ -7,7 +7,10 @@ let wasm_bindgen = (function(exports) {
     /**
      * Adds a section. `ptr`/`len` point to an encoded `AddSectionParams`.
      *
-     * On success: writes encoded kbid string to return slot, returns 0.
+     * 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.
      * @param {number} ptr
      * @param {number} len
@@ -72,6 +75,30 @@ let wasm_bindgen = (function(exports) {
     }
     exports.db_check_version = db_check_version;
 
+    /**
+     * 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}`
+     * @param {number} ptr
+     * @param {number} len
+     * @returns {number}
+     */
+    function db_export(ptr, len) {
+        const ret = wasm.db_export(ptr, len);
+        return ret;
+    }
+    exports.db_export = db_export;
+
     /**
      * Runs garbage collection. Returns 0 on success.
      * On success a summary string is placed in the return slot.
@@ -644,6 +671,10 @@ let wasm_bindgen = (function(exports) {
 
     /**
      * Adds a section. Returns 0 on success, -1 on error.
+     *
+     * On success the return slot holds the binary-encoded `AddSectionResult`
+     * (kbid + indexed_terms_count + elapsed_ms + superseded + warnings +
+     * near_duplicates) using the `Encode` trait wire format.
      * @param {number} ptr
      * @param {number} len
      * @returns {number}
@@ -684,6 +715,26 @@ let wasm_bindgen = (function(exports) {
     }
     exports.worker_compose = worker_compose;
 
+    /**
+     * Exports the database to a target directory.
+     *
+     * `ptr`/`len` point to a UTF-8 string containing the target path.
+     *
+     * Delegates directly to `db_export` in `kbdb-fs-database`. Does not require
+     * the worker to have been initialised because the target path is given
+     * explicitly by the caller.
+     *
+     * Returns 0 on success, -1 on error (message in return slot).
+     * @param {number} ptr
+     * @param {number} len
+     * @returns {number}
+     */
+    function worker_export(ptr, len) {
+        const ret = wasm.worker_export(ptr, len);
+        return ret;
+    }
+    exports.worker_export = worker_export;
+
     /**
      * Runs garbage collection and invalidates all cache entries.
      *
@@ -835,6 +886,14 @@ let wasm_bindgen = (function(exports) {
 
     /**
      * Rebuilds all database indexes.
+     *
+     * First clears the existing inverted, positional, and reference indexes via
+     * `db_rebuild_index`. Then re-tokenizes every stored section and re-populates
+     * the indexes via `rebuild_all_section_indexes`.
+     *
+     * On success the return slot holds the number of reindexed sections as a
+     * little-endian `u32`, and 0 is returned. On error -1 is returned and an
+     * error message is in the return slot.
      * @returns {number}
      */
     function worker_rebuild_indexes() {

package/dist/wasm/kb-worker/kbdb_worker_bg.wasm.d.ts

@@ -8,6 +8,7 @@ export const set_return: (a: number, b: number) => void;
 export const worker_add_section: (a: number, b: number) => number;
 export const worker_check_integrity: () => number;
 export const worker_compose: (a: number, b: number) => number;
+export const worker_export: (a: number, b: number) => number;
 export const worker_garbage_collect: () => number;
 export const worker_get_result: (a: number) => number;
 export const worker_group_sections: (a: number, b: number) => number;
@@ -48,6 +49,7 @@ export const db_add_section: (a: number, b: number) => number;
 export const db_add_to_index: (a: number, b: number) => number;
 export const db_check_integrity: (a: number, b: number) => number;
 export const db_check_version: (a: number, b: number) => number;
+export const db_export: (a: number, b: number) => number;
 export const db_gc: (a: number, b: number) => number;
 export const db_get_back_refs: (a: number, b: number) => number;
 export const db_get_forward_refs: (a: number, b: number) => number;