@dikolab/kbdb 0.1.0

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

@@ -0,0 +1,14 @@
+/** A single ranked result returned by a search query. */
+export interface SearchResult {
+    /** Knowledge-base identifier for the matched section. */
+    readonly kbid: string;
+    /** Relevance score assigned by the ranking engine. */
+    readonly score: number;
+    /** Terms that matched within this section. */
+    readonly matches: readonly {
+        /** The matched term. */
+        readonly term: string;
+        /** Number of times the term appears in the section. */
+        readonly frequency: number;
+    }[];
+}

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

@@ -0,0 +1,26 @@
+/** A content section stored in the knowledge-base. */
+export interface Section {
+    /** Knowledge-base identifier for this section. */
+    readonly kbid: string;
+    /** Parent document identifier, if the section belongs to one. */
+    readonly docid?: string;
+    /** Semantic type label assigned to the section. */
+    readonly sectionType: string;
+    /** Raw text content of the section. */
+    readonly content: string;
+    /** Byte size of the stored content. */
+    readonly size: number;
+    /** Unix epoch timestamp (ms) when the section was created. */
+    readonly createdAt: number;
+    /** SHA-256 checksum of the stored content. */
+    readonly checksum: string;
+}
+/** Parameters required to add or update a section. */
+export interface AddSectionParams {
+    /** Semantic type label to assign to the section. */
+    readonly sectionType: string;
+    /** Raw text content for the section. */
+    readonly content: string;
+    /** Parent document identifier to associate the section with. */
+    readonly docid?: string;
+}

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

@@ -0,0 +1,14 @@
+/** Diagnostic status returned by the worker daemon. */
+export interface StatusResult {
+    /** Whether the daemon has finished loading its WASM modules. */
+    readonly initialized: boolean;
+    /** Absolute path to the context directory the daemon serves. */
+    readonly contextPath: string;
+    /** In-memory cache statistics. */
+    readonly cacheStats: {
+        /** Number of content entries currently cached. */
+        readonly contentCount: number;
+        /** Number of index entries currently cached. */
+        readonly indexCount: number;
+    };
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Compatibility status categories returned by a database version check.
+ *
+ * - `'compatible'` -- database version matches the WASM engine version
+ * - `'needs_migration'` -- database is older and must be migrated with
+ *   `kbdb --migrate`
+ * - `'too_new'` -- database was created by a newer version of kbdb;
+ *   upgrade the kbdb binary
+ */
+export type VersionCompatibility = 'compatible' | 'needs_migration' | 'too_new';
+/**
+ * Version compatibility status returned by a database version check.
+ */
+export interface VersionStatus {
+    /** The format version stored in the database's `catalog.toml`. */
+    readonly currentVersion: number;
+    /**
+     * The format version required by the current WASM engine.
+     * Equivalent to `DB_FORMAT_VERSION` from the Rust shared crate.
+     */
+    readonly requiredVersion: number;
+    /** Compatibility result between the database and WASM engine. */
+    readonly status: VersionCompatibility;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * An error returned by the worker daemon over JSON-RPC,
+ * carrying a numeric error code alongside the message.
+ */
+export interface WorkerClientError extends Error {
+    /** JSON-RPC error code returned by the daemon. */
+    readonly code: number;
+}

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

@@ -0,0 +1,30 @@
+/** Options for configuring a WorkerClient connection. */
+export interface WorkerClientOptions {
+    /**
+     * Path to the directory containing the `.kbdb` database
+     * folder. Defaults to `process.cwd()` when omitted.
+     */
+    readonly dbPath?: string;
+    /**
+     * Absolute path to the context directory. When provided,
+     * skips the `.kbdb` discovery step performed by `dbPath`.
+     */
+    readonly contextPath?: string;
+    /**
+     * When `true` (default), automatically spawns the worker
+     * daemon if it is not already running before connecting.
+     * Set to `false` to require a running daemon.
+     */
+    readonly autoSpawn?: boolean;
+    /**
+     * Maximum milliseconds to wait for the daemon PID file to
+     * appear after spawning. Defaults to 10 000 ms.
+     */
+    readonly connectTimeoutMs?: number;
+    /**
+     * Absolute path to the worker daemon script. Resolved
+     * once at the entry point and injected here so that
+     * `spawnDaemon` needs no runtime-specific path logic.
+     */
+    readonly workerScript?: string;
+}

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

@@ -0,0 +1,147 @@
+import type { DaemonConfig } from '../typings/daemon-config.interface.ts';
+import type { WasmModules } from '../typings/wasm-modules.interface.ts';
+import type { IpcRequest, IpcResponse } from '../typings/ipc-handler.interface.ts';
+/**
+ * Core daemon class that manages the full worker daemon lifecycle.
+ *
+ * Orchestrates WASM module loading, IPC server creation, request
+ * routing to `kb-worker.wasm` exports, idle timeout tracking, and
+ * graceful shutdown. The daemon validates startup preconditions before
+ * loading WASM modules and rejects IPC requests whose `ctx` param does
+ * not match the daemon's context ID.
+ */
+export declare class WorkerDaemon {
+    /** Context ID (16-character hex SHA-256 prefix). */
+    readonly ctx: string;
+    /** Absolute path to the `.kbdb` directory. */
+    readonly targetDir: string;
+    /** Parsed daemon configuration from `worker.toml`. */
+    readonly config: DaemonConfig;
+    /** Number of currently active IPC client connections. */
+    get connectionCount(): number;
+    private _connectionCount;
+    private _wasmModules;
+    private _idleAt;
+    private _idleTimer;
+    private _server;
+    private readonly _wasmDir;
+    /**
+     * @param ctx - context ID (16-hex characters), the first 16 of
+     *   the SHA-256 hash of `targetDir`
+     * @param targetDir - absolute path to the `.kbdb` directory
+     * @param config - parsed daemon configuration
+     * @param wasmDir - path to the WASM build output directory
+     */
+    constructor(ctx: string, targetDir: string, config: DaemonConfig, wasmDir?: string);
+    /**
+     * Validates startup preconditions before WASM module loading.
+     *
+     * Checks that the database directory exists, is readable and
+     * writable, and that `catalog.toml` reports a compatible version.
+     *
+     * @throws {Error} if any precondition fails -- `startDaemon`
+     *   catches this, prints to stderr, and exits with code 1
+     */
+    checkPreconditions(): void;
+    /**
+     * Starts the daemon: loads WASM modules, writes the PID file,
+     * creates the IPC socket, and begins listening for connections.
+     *
+     * Call `checkPreconditions()` before `start()` to validate the
+     * database directory. The daemon will not start if any precondition
+     * fails.
+     *
+     * @throws when WASM module loading fails or the IPC socket cannot
+     *   be created
+     */
+    start(): Promise<void>;
+    /**
+     * Gracefully shuts down the daemon.
+     *
+     * Stops accepting new connections, clears the idle timer, purges
+     * WASM state, removes the PID file and IPC socket file, then exits
+     * the process.
+     */
+    stop(): void;
+    /**
+     * Handles a single JSON-RPC 2.0 request.
+     *
+     * Validates context, then routes to a daemon-state handler or a
+     * WASM export. Requests whose `ctx` param does not match the
+     * daemon's context ID are rejected with error code `-32001`.
+     *
+     * @param request - incoming JSON-RPC request
+     * @returns the JSON-RPC response
+     */
+    handleRequest(request: IpcRequest): Promise<IpcResponse>;
+    /**
+     * Increments the active connection count.
+     *
+     * Call when a new IPC client connects.
+     */
+    incrementConnections(): void;
+    /**
+     * Decrements the active connection count, clamped to zero.
+     *
+     * Call when an IPC client disconnects.
+     */
+    decrementConnections(): void;
+    /**
+     * Injects pre-built WASM modules for unit testing.
+     *
+     * This method exists solely to support unit tests that cannot
+     * load real WASM binaries. It must not be called in production
+     * code -- production code uses `start()` to load modules.
+     *
+     * @param modules - pre-built WASM module instances
+     * @internal
+     */
+    injectModulesForTesting(modules: WasmModules): void;
+    /** Resets the idle timer; triggers stop() when it fires. */
+    private resetIdleTimer;
+    /** Reads catalog.toml and validates the version field. */
+    private checkCatalogVersion;
+    /** Builds a JSON-RPC error response. */
+    private errorResponse;
+    /**
+     * Dispatches a request method to the appropriate handler.
+     *
+     * Handles daemon-state methods (`status`, `idle_at`,
+     * `config_{key}`) inline and routes WASM methods to the
+     * correct calling convention for each export.
+     */
+    private dispatch;
+    private dispatchWasm;
+    private handleSearch;
+    private handleResultStatus;
+    private handleGetResult;
+    private handleAddSection;
+    private handleUpdateSection;
+    private handleReadSections;
+    private handleGroupSections;
+    private handleCompose;
+    private handleRemoveSection;
+    private handleRetrieveDoc;
+    private handleRemoveGrouping;
+    private handleInitDirectory;
+    private handleInvalidate;
+    private handleListByType;
+    private handleListDocsByType;
+    private handleInvalidateAll;
+    private handleDbStatus;
+    private handleIntegrityCheck;
+    private handleGc;
+    private handleRebuild;
+    private initWorkerContext;
+    private getExport;
+    private wasmAlloc;
+    private wasmFree;
+    private wasmWrite;
+    private readReturnSlot;
+    private callWasmSync;
+    private callWasmZeroArg;
+    private invokeWasmRaw;
+    private handleCheckVersion;
+    /** Returns a daemon config value by config method name. */
+    private handleConfigMethod;
+}

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

@@ -0,0 +1,24 @@
+/** Default maximum number of items held in daemon memory. */
+export declare const DEFAULT_ITEM_LIMIT = 1000;
+/** Default maximum number of index entries held in daemon memory. */
+export declare const DEFAULT_INDEX_LIMIT = 100;
+/**
+ * Default idle timeout in milliseconds before the daemon shuts
+ * down automatically (5 minutes).
+ */
+export declare const DEFAULT_TIMEOUT_MS = 300000;
+/**
+ * Default time-to-live in milliseconds for each cached item
+ * (1 minute).
+ */
+export declare const DEFAULT_ITEM_TTL_MS = 60000;
+/** Filename of the daemon configuration file inside `.kbdb/`. */
+export declare const WORKER_TOML_FILENAME = "worker.toml";
+/**
+ * Database format version the daemon supports.
+ *
+ * Read from `catalog.toml` at startup. If the catalog version
+ * differs, the daemon prints a structured error to stderr and
+ * exits with code 1 before loading any WASM modules.
+ */
+export declare const DB_FORMAT_VERSION = 1;

package/dist/src/shared/worker-daemon/functions/create-host-imports.function.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Minimal filesystem operations required by the host imports.
+ *
+ * The default implementation delegates to `node:fs` synchronous
+ * APIs. Tests inject a stub to avoid touching the real filesystem.
+ */
+export interface FsAdapter {
+    /** Read entire file as a Buffer. */
+    readFileSync(path: string): Buffer;
+    /** Write data buffer to file. */
+    writeFileSync(path: string, data: Uint8Array): void;
+    /** Rename `oldPath` to `newPath`. */
+    renameSync(oldPath: string, newPath: string): void;
+    /** Delete a file. */
+    unlinkSync(path: string): void;
+    /** List directory entries as strings. */
+    readdirSync(path: string): string[];
+    /** Create a directory (and parents) recursively. */
+    mkdirSync(path: string): void;
+    /** Return true if the path exists. */
+    existsSync(path: string): boolean;
+}
+/**
+ * A mutable reference to the WASM linear memory.
+ *
+ * The `memory` field starts as `null` and is wired up after the
+ * `kb-worker` WASM module is instantiated (the module exports its
+ * own memory rather than importing one). Host import functions
+ * read `memory` at call time, not at creation time, so the ref
+ * can be populated after the import record is built.
+ */
+export interface MemoryRef {
+    memory: WebAssembly.Memory | null;
+}
+/**
+ * A mutable reference to the WASM allocator function.
+ *
+ * The `alloc` field starts as `null` and is wired up after the
+ * `kb-worker` WASM module is instantiated. Host import functions
+ * that must allocate memory in WASM linear memory check this
+ * reference before proceeding and return -1 when it is null.
+ */
+export interface AllocatorRef {
+    /**
+     * Allocates `size` bytes in WASM linear memory and returns the
+     * byte offset of the allocated region, or `null` when the
+     * allocator is not yet available.
+     */
+    alloc: ((size: number) => number) | null;
+}
+/**
+ * Creates the host I/O import functions required by `kb-worker.wasm`.
+ *
+ * All functions read the WASM linear memory through `memoryRef`,
+ * a deferred reference wired up after module instantiation (the
+ * module exports its own memory). Paths from WASM are resolved
+ * relative to `contextPath`.
+ *
+ * @param contextPath - absolute path to the `.kbdb` database directory
+ * @param memoryRef - deferred reference to the WASM module's
+ *   exported memory; wired after instantiation
+ * @param fs - filesystem adapter; defaults to real `node:fs` operations
+ * @param allocator - reference to the WASM allocator; wired after
+ *   `kb-worker` instantiation. Defaults to a null (uninitialized) ref.
+ * @returns a record of host import functions keyed by their WASM import
+ *   names
+ */
+export declare function createHostImports(contextPath: string, memoryRef?: MemoryRef, fs?: FsAdapter, allocator?: AllocatorRef): Record<string, WebAssembly.ImportValue>;

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

@@ -0,0 +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.
+ *
+ * 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`).
+ *
+ * @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;

package/dist/src/shared/worker-daemon/functions/load-wasm-modules.function.d.ts

@@ -0,0 +1,19 @@
+import type { DaemonConfig } from '../typings/daemon-config.interface.ts';
+import type { WasmModules } from '../typings/wasm-modules.interface.ts';
+/**
+ * Loads and instantiates the `kb-worker` WASM module.
+ *
+ * `kb-worker.wasm` statically links the `fs-database` and
+ * `query-parser` crates, so only one module needs to be
+ * instantiated.  The module exports its own linear memory;
+ * host I/O imports read it through a deferred `MemoryRef`
+ * that is wired up immediately after instantiation.
+ *
+ * @param config - daemon configuration, used to supply the context
+ *   path to the host I/O imports
+ * @param wasmDir - absolute path to the directory containing the
+ *   compiled WASM subdirectories (`query-parser/`, `fs-database/`,
+ *   `kb-worker/`)
+ * @throws when the WASM file cannot be read or instantiated
+ */
+export declare function loadWasmModules(config: DaemonConfig, wasmDir: string): Promise<WasmModules>;

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

@@ -0,0 +1,12 @@
+import type { DaemonConfig } from '../typings/daemon-config.interface.ts';
+/**
+ * Reads the `worker.toml` configuration file from the given
+ * context directory and returns a `DaemonConfig`.
+ *
+ * Falls back to all-default values when the file is absent or
+ * unreadable.
+ *
+ * @param contextPath - absolute path to the `.kbdb` context
+ *   directory
+ */
+export declare function readConfig(contextPath: string): DaemonConfig;

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

@@ -0,0 +1,26 @@
+/** Result of the worker entry point. */
+export interface WorkerResult {
+    /** Error message (if any). */
+    error?: string;
+    /** Process exit code. `0` means success. */
+    exitCode: number;
+}
+/**
+ * Injectable dependencies for the worker entry point.
+ */
+export interface WorkerDeps {
+    existsSync: (path: string) => boolean;
+    startDaemon: (contextPath: string, wasmDir?: string) => Promise<void>;
+    wasmDir?: string;
+}
+/**
+ * Worker daemon entry point extracted from `src/worker.ts`.
+ *
+ * Validates the context path argument, resolves it to an
+ * absolute path, checks existence, and delegates to
+ * `startDaemon`.
+ *
+ * @param argv - raw arguments (expects `[contextPath]`)
+ * @param deps - injectable dependencies
+ */
+export declare function runWorker(argv: string[], deps: WorkerDeps): Promise<WorkerResult>;

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

@@ -0,0 +1,13 @@
+/**
+ * Starts the worker daemon for the given knowledge-base context.
+ *
+ * Reads configuration from `worker.toml` in the context directory,
+ * validates startup preconditions (directory exists, accessible, and
+ * database version compatible), and then starts the `WorkerDaemon`.
+ *
+ * Signal handlers for `SIGTERM` and `SIGINT` trigger a graceful stop.
+ * Precondition failures are printed to stderr and cause exit code 1.
+ *
+ * @param contextPath - absolute path to the `.kbdb` context directory
+ */
+export declare function startDaemon(contextPath: string, wasmDir?: string): Promise<void>;

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

@@ -0,0 +1,9 @@
+export { readConfig } from './functions/read-config.function.ts';
+export { startDaemon } from './functions/start-daemon.function.ts';
+export { createIpcServer } from './functions/create-ipc-server.function.ts';
+export { loadWasmModules } from './functions/load-wasm-modules.function.ts';
+export type { DaemonConfig } from './typings/daemon-config.interface.ts';
+export type { WasmModules } from './typings/wasm-modules.interface.ts';
+export type { IpcRequest, IpcResponse, IpcHandler, } from './typings/ipc-handler.interface.ts';
+export { runWorker } from './functions/run-worker.function.ts';
+export type { WorkerResult, WorkerDeps, } from './functions/run-worker.function.ts';

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

@@ -0,0 +1,13 @@
+/** Configuration for the worker daemon process. */
+export interface DaemonConfig {
+    /** Absolute path to the knowledge-base context directory. */
+    readonly contextPath: string;
+    /** Maximum number of items held in memory at once. */
+    readonly itemLimit: number;
+    /** Maximum number of index entries held in memory at once. */
+    readonly indexLimit: number;
+    /** Idle timeout in milliseconds before the daemon shuts down. */
+    readonly timeoutMs: number;
+    /** Time-to-live in milliseconds for each cached item. */
+    readonly itemTtlMs: number;
+}

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

@@ -0,0 +1,36 @@
+/** A JSON-RPC 2.0 request sent to the daemon over IPC. */
+export interface IpcRequest {
+    /** JSON-RPC version string -- always `'2.0'`. */
+    readonly jsonrpc: '2.0';
+    /** Request identifier, echoed back in the response. */
+    readonly id: number | string;
+    /** Method name to invoke on the daemon. */
+    readonly method: string;
+    /** Optional method parameters. */
+    readonly params?: unknown;
+}
+/** Error detail included in a failed JSON-RPC response. */
+export interface IpcErrorDetail {
+    /** JSON-RPC error code. */
+    readonly code: number;
+    /** Human-readable error message. */
+    readonly message: string;
+    /** Optional additional error data. */
+    readonly data?: unknown;
+}
+/** A JSON-RPC 2.0 response returned by the daemon over IPC. */
+export interface IpcResponse {
+    /** JSON-RPC version string -- always `'2.0'`. */
+    readonly jsonrpc: '2.0';
+    /** Identifier matching the originating request. */
+    readonly id: number | string;
+    /** Successful result payload. Present on success. */
+    readonly result?: unknown;
+    /** Error detail. Present on failure. */
+    readonly error?: IpcErrorDetail;
+}
+/**
+ * Function that handles a single IPC request and returns a
+ * JSON-RPC response.
+ */
+export type IpcHandler = (request: IpcRequest) => Promise<IpcResponse>;

package/dist/src/shared/worker-daemon/typings/wasm-modules.interface.d.ts

@@ -0,0 +1,7 @@
+/** Loaded and instantiated WASM module instances. */
+export interface WasmModules {
+    /** Linear memory exported by the kb-worker WASM module. */
+    readonly memory: WebAssembly.Memory;
+    /** Instantiated kb-worker WASM module. */
+    readonly kbWorker: WebAssembly.Instance;
+}

package/dist/src/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;