@dikolab/kbdb 0.1.0

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

@@ -0,0 +1,50 @@
+/**
+ * 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;
+}
+/**
+ * Decodes a list of `SectionRecord` values from WASM binary output.
+ *
+ * Reads a leading u32 count followed by that many encoded records.
+ * Each record is decoded in field order as produced by the Rust
+ * `SectionRecord::encode` implementation.
+ *
+ * @param bytes - raw bytes returned by a WASM section-list export
+ * @returns decoded array of section records, empty when count is zero
+ */
+export declare function decodeSectionRecords(bytes: Uint8Array): SectionRecord[];

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

@@ -0,0 +1,5 @@
+export interface DecodeResult<T> {
+    value: T;
+    bytesRead: number;
+}
+export declare function decodeString(bytes: Uint8Array, offset: number): DecodeResult<string>;

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

@@ -0,0 +1,2 @@
+import type { DecodeResult } from './decode-string.function.ts';
+export declare function decodeU32(bytes: Uint8Array, offset: number): DecodeResult<number>;

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

@@ -0,0 +1,2 @@
+import type { DecodeResult } from './decode-string.function.ts';
+export declare function decodeU64(bytes: Uint8Array, offset: number): DecodeResult<bigint>;

package/dist/src/shared/wasm-codec/functions/encode-add-section-params.function.d.ts

@@ -0,0 +1,10 @@
+export interface AddSectionInput {
+    sectionType: 'text' | 'code' | 'image';
+    mimeType?: string;
+    content: string;
+    title?: string | null;
+    description?: string | null;
+    docid?: string | null;
+    typeName?: string | null;
+}
+export declare function encodeAddSectionParams(params: AddSectionInput): Uint8Array;

package/dist/src/shared/wasm-codec/functions/encode-group-params.function.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Encodes parameters for the `worker_group_sections` WASM call into
+ * a single byte buffer: title, kbid list, then doc type tag.
+ *
+ * @param title - human-readable document title
+ * @param kbids - identifiers of the sections to group
+ * @param docType - application-level document type tag; defaults to
+ *   empty string when not specified
+ */
+export declare function encodeGroupParams(title: string, kbids: string[], docType?: string): Uint8Array;

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

@@ -0,0 +1 @@
+export declare function encodeIdentifierList(ids: string[]): Uint8Array;

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

@@ -0,0 +1 @@
+export declare function encodeKbidList(kbids: string[]): Uint8Array;

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

@@ -0,0 +1 @@
+export declare function encodeOptionString(value: string | null | undefined): Uint8Array;

package/dist/src/shared/wasm-codec/functions/encode-search-params.function.d.ts

@@ -0,0 +1 @@
+export declare function encodeSearchParams(query: string, mode?: string, limit?: number): Uint8Array;

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

@@ -0,0 +1 @@
+export declare function encodeSectionType(kind: 'text' | 'code' | 'image', mimeType?: string): Uint8Array;

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

@@ -0,0 +1 @@
+export declare function encodeString(value: string): Uint8Array;

package/dist/src/shared/wasm-codec/functions/encode-type-filter-param.function.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Encodes a type filter string as raw UTF-8 bytes for WASM input.
+ *
+ * Used to pass a type name to WASM exports such as
+ * `worker_list_by_type` and `worker_list_docs_by_type`, which accept
+ * a plain UTF-8 byte slice without a length prefix.
+ *
+ * @param typeStr - the type name to filter by (e.g. `'article'`)
+ * @returns UTF-8 encoded bytes ready to pass to the WASM export
+ */
+export declare function encodeTypeFilterParam(typeStr: string): Uint8Array;

package/dist/src/shared/wasm-codec/functions/encode-u32.function.d.ts

@@ -0,0 +1 @@
+export declare function encodeU32(value: number): Uint8Array;

package/dist/src/shared/wasm-codec/functions/encode-update-section-params.function.d.ts

@@ -0,0 +1,2 @@
+import type { AddSectionInput } from './encode-add-section-params.function.ts';
+export declare function encodeUpdateSectionParams(oldKbid: string, params: AddSectionInput): Uint8Array;

package/dist/src/shared/wasm-codec/index.d.ts

@@ -0,0 +1,29 @@
+export { encodeString } from './functions/encode-string.function.ts';
+export { encodeU32 } from './functions/encode-u32.function.ts';
+export { encodeOptionString } from './functions/encode-option-string.function.ts';
+export { encodeSectionType } from './functions/encode-section-type.function.ts';
+export { encodeAddSectionParams } from './functions/encode-add-section-params.function.ts';
+export { encodeUpdateSectionParams } from './functions/encode-update-section-params.function.ts';
+export { encodeKbidList } from './functions/encode-kbid-list.function.ts';
+export { encodeGroupParams } from './functions/encode-group-params.function.ts';
+export { encodeIdentifierList } from './functions/encode-identifier-list.function.ts';
+export { encodeSearchParams } from './functions/encode-search-params.function.ts';
+export { encodeTypeFilterParam } from './functions/encode-type-filter-param.function.ts';
+export { decodeString } from './functions/decode-string.function.ts';
+export { decodeU32 } from './functions/decode-u32.function.ts';
+export { decodeF32 } from './functions/decode-f32.function.ts';
+export { decodeU64 } from './functions/decode-u64.function.ts';
+export { decodeScoredResults } from './functions/decode-scored-results.function.ts';
+export { decodeSectionRecords } from './functions/decode-section-records.function.ts';
+export { decodeSectionRecordList } from './functions/decode-section-record-list.function.ts';
+export { decodeDocumentManifest } from './functions/decode-document-manifest.function.ts';
+export { decodeDocumentManifestList } from './functions/decode-document-manifest-list.function.ts';
+export { decodeComposeOutput } from './functions/decode-compose-output.function.ts';
+export { decodeKeyValueText } from './functions/decode-key-value-text.function.ts';
+export { decodeRemoveFlag } from './functions/decode-remove-flag.function.ts';
+export type { DecodeResult } from './functions/decode-string.function.ts';
+export type { AddSectionInput } from './functions/encode-add-section-params.function.ts';
+export type { ScoredResult, TermMatch, } from './functions/decode-scored-results.function.ts';
+export type { SectionRecord } from './functions/decode-section-records.function.ts';
+export type { DocumentManifest, DocumentSection, } from './functions/decode-document-manifest.function.ts';
+export type { ComposeOutput } from './functions/decode-compose-output.function.ts';

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

@@ -0,0 +1,230 @@
+import type { SearchParams } from '../typings/search-params.model.ts';
+import type { SearchResult } from '../typings/search-result.model.ts';
+import type { AddSectionParams, Section } from '../typings/section.model.ts';
+import type { StatusResult } from '../typings/status-result.model.ts';
+import type { AddSectionResult } from '../typings/add-section-result.model.ts';
+import type { RemoveSectionResult } from '../typings/remove-section-result.model.ts';
+import type { ContentResult } from '../typings/content-result.model.ts';
+import type { IntegrityCheckResult } from '../typings/integrity-check-result.model.ts';
+import type { GcResult } from '../typings/gc-result.model.ts';
+import type { RebuildResult } from '../typings/rebuild-result.model.ts';
+import type { MigrateResult } from '../typings/migrate-result.model.ts';
+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';
+/**
+ * IPC client that communicates with the worker daemon over a Unix
+ * domain socket (or Windows named pipe) using JSON-RPC 2.0 with
+ * newline-delimited message framing.
+ *
+ * Call `connect()` before any other method and `disconnect()` when
+ * done to release the underlying socket.
+ */
+export declare class WorkerClient {
+    private readonly socketPath;
+    private readonly contextId;
+    /** Underlying socket; `null` when not connected. */
+    private socket;
+    /** Monotonically increasing request ID counter. */
+    private nextId;
+    /** Map of outstanding request IDs to their resolve/reject pairs. */
+    private readonly pending;
+    /** Partial line buffer for split TCP/IPC frames. */
+    private buffer;
+    /**
+     * @param socketPath - absolute path to the daemon's IPC socket
+     *   (or Windows named pipe path)
+     * @param contextId - 16-character context identifier sent as
+     *   `ctx` in every JSON-RPC request
+     */
+    constructor(socketPath: string, contextId: string);
+    /**
+     * Establishes the IPC connection to the worker daemon.
+     *
+     * @throws {Error} if the connection cannot be established
+     */
+    connect(): Promise<void>;
+    /** Destroys the IPC socket and clears the connection state. */
+    disconnect(): void;
+    /**
+     * Searches the knowledge base.
+     *
+     * @param params - query parameters including the search string
+     * @returns ranked list of matching sections
+     */
+    search(params: SearchParams): Promise<SearchResult[]>;
+    /**
+     * Adds a new section to the knowledge base.
+     *
+     * @param params - section content and metadata
+     * @returns the result including the assigned knowledge-base
+     *   identifier and indexing statistics
+     */
+    addSection(params: AddSectionParams): Promise<AddSectionResult>;
+    /**
+     * Replaces an existing section's content and metadata.
+     *
+     * @param kbid - identifier of the section to update
+     * @param params - new content and metadata
+     * @returns the knowledge-base identifier of the updated section
+     */
+    updateSection(kbid: string, params: AddSectionParams): Promise<string>;
+    /**
+     * Removes a section from the knowledge base.
+     *
+     * @param kbid - identifier of the section to remove
+     * @returns removal result with `removed` flag and elapsed time
+     */
+    removeSection(kbid: string): Promise<RemoveSectionResult>;
+    /**
+     * Retrieves multiple sections by their identifiers.
+     *
+     * @param kbids - list of knowledge-base identifiers to fetch
+     * @returns sections in the order their IDs were requested
+     */
+    readSections(kbids: string[]): Promise<Section[]>;
+    /**
+     * Groups a set of sections under a named document.
+     *
+     * @param title - human-readable document title
+     * @param kbids - identifiers of the sections to group
+     * @param docType - application-level document type tag; omit or
+     *   pass an empty string for untagged documents
+     * @returns the assigned document identifier
+     */
+    groupSections(title: string, kbids: string[], docType?: string): Promise<string>;
+    /**
+     * Removes the document grouping for the given document.
+     *
+     * The sections themselves are not deleted; only the grouping
+     * record is removed.
+     *
+     * @param docid - identifier of the document grouping to remove
+     */
+    removeGrouping(docid: string): Promise<void>;
+    /**
+     * Retrieves a full document record including its sections.
+     *
+     * @param docid - identifier of the document to retrieve
+     * @returns the document record as returned by the daemon
+     */
+    retrieveDocument(docid: string): Promise<unknown>;
+    /**
+     * Composes a rendered Markdown document from one or more kbid
+     * or docid identifiers.
+     *
+     * @param ids - list of kbid or docid identifiers (may be mixed)
+     * @returns composed Markdown result with character count
+     */
+    content(ids: string[]): Promise<ContentResult>;
+    /**
+     * Runs an integrity check on the knowledge-base database.
+     *
+     * @returns a report of all issues found; `ok` is `true` when
+     *   no errors were detected
+     */
+    integrityCheck(): Promise<IntegrityCheckResult>;
+    /**
+     * Removes unreferenced sections from the database.
+     *
+     * @returns a report of sections removed and bytes freed
+     */
+    gc(): Promise<GcResult>;
+    /**
+     * Reconstructs all index files from section files and document
+     * manifests on disk. Text and code sections are re-tokenized;
+     * image sections are skipped.
+     *
+     * @returns a report of sections and terms re-indexed
+     */
+    rebuildIndexes(): Promise<RebuildResult>;
+    /**
+     * Invalidates the in-memory cache entry for a single section.
+     *
+     * @param kbid - identifier of the section to evict from cache
+     */
+    invalidate(kbid: string): Promise<void>;
+    /** Clears all entries from the daemon's in-memory cache. */
+    invalidateAll(): Promise<void>;
+    /**
+     * Retrieves diagnostic status information from the daemon.
+     *
+     * @returns current initialization state and cache statistics
+     */
+    status(): Promise<StatusResult>;
+    /**
+     * Returns database metadata and status from the daemon,
+     * including document count, section count, index size, and
+     * cache statistics.
+     *
+     * @returns database metadata from the daemon's cached state
+     */
+    dbStatus(): Promise<StatusResult>;
+    /**
+     * Initialises a new `.kbdb` database directory at the given path
+     * by sending an init request to the worker daemon.
+     *
+     * The daemon creates all required subdirectories and seed files via
+     * the `worker_init_directory` WASM export.
+     *
+     * @param targetPath - absolute path to the directory that will
+     *   contain the new `.kbdb` database
+     * @throws {Error} if the `.kbdb` directory already exists or the
+     *   daemon cannot create the layout
+     */
+    initDirectory(targetPath: string): Promise<void>;
+    /**
+     * Runs all pending database migrations for the `.kbdb` directory
+     * at the given path.
+     *
+     * Delegates to the `worker_migrate` WASM export on the daemon.
+     * Each migration step updates `catalog.toml` on success, so
+     * retrying after a partial failure is safe.
+     *
+     * @param targetPath - absolute path to the `.kbdb` database root
+     * @returns migration report with old version, new version, and
+     *   number of migration steps applied
+     */
+    migrateDatabase(targetPath: string): Promise<MigrateResult>;
+    /**
+     * Checks the format version of the `.kbdb` database at the given
+     * path against the version required by the current WASM engine.
+     *
+     * This is a read-only operation: it reads `catalog.toml` and
+     * returns the compatibility status without making any changes.
+     *
+     * @param targetPath - absolute path to the `.kbdb` database root
+     * @returns version compatibility report
+     */
+    checkVersion(targetPath: string): Promise<VersionStatus>;
+    /**
+     * Retrieves all sections whose type name matches the given string.
+     *
+     * @param sectionType - the application-level type name to filter by
+     * @returns all section records with a matching type name
+     */
+    listByType(sectionType: string): Promise<SectionRecord[]>;
+    /**
+     * Retrieves all documents whose type name matches the given string.
+     *
+     * @param docType - the application-level document type to filter by
+     * @returns all document manifests with a matching type name
+     */
+    listDocumentsByType(docType: string): Promise<DocumentManifest[]>;
+    /**
+     * Sends a JSON-RPC 2.0 request and awaits the response.
+     *
+     * @param method - the RPC method name
+     * @param params - parameters to include in the request
+     * @throws {Error} if not connected
+     * @throws {Error} when the daemon returns an error response
+     */
+    private call;
+    /**
+     * Processes incoming data from the socket, splitting on newlines
+     * and dispatching complete JSON-RPC response objects.
+     *
+     * @param data - raw string chunk received from the socket
+     */
+    private handleData;
+}

package/dist/src/shared/worker-client/functions/compute-context-id.function.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Computes a short context identifier for an absolute path.
+ *
+ * Hashes the path with SHA-256 and returns the first 16 hex
+ * characters. The result is stable for the same input and unique
+ * enough to avoid accidental collisions across typical path sets.
+ *
+ * @param absolutePath - the absolute filesystem path to identify
+ * @returns a 16-character lowercase hex string
+ */
+export declare function computeContextId(absolutePath: string): Promise<string>;

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

@@ -0,0 +1,18 @@
+import { WorkerClient } from '../classes/worker-client.class.ts';
+import type { WorkerClientOptions } from '../typings/worker-client-options.interface.ts';
+/**
+ * Creates and connects a `WorkerClient` to the worker daemon.
+ *
+ * Resolves the context path, derives a stable context identifier,
+ * and checks whether a daemon is already running. If no daemon is
+ * found and `autoSpawn` is not `false`, a new daemon process is
+ * spawned and the factory waits for its PID file to appear before
+ * connecting.
+ *
+ * @param options - optional configuration for path resolution,
+ *   auto-spawn behaviour, and connection timeout
+ * @returns a connected `WorkerClient` ready to send requests
+ * @throws {Error} if the `.kbdb` directory cannot be found
+ * @throws {Error} if the socket connection cannot be established
+ */
+export declare function createWorkerClient(options?: WorkerClientOptions): Promise<WorkerClient>;

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

@@ -0,0 +1,14 @@
+import type { DaemonInfo } from '../typings/daemon-info.model.ts';
+export type { DaemonInfo };
+/**
+ * Discovers a running worker daemon for the given context.
+ *
+ * Reads the PID file at `<tmpdir>/kbdb-<contextId>.pid`. If the
+ * file exists and the process is alive, returns its PID and the
+ * expected socket path. If the file is stale (process dead or PID
+ * unparseable), removes the PID file and returns `null`.
+ *
+ * @param contextId - the 16-character context identifier
+ * @returns daemon location info, or `null` if no live daemon found
+ */
+export declare function discoverDaemon(contextId: string): DaemonInfo | null;

package/dist/src/shared/worker-client/functions/resolve-db-path.function.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolves the absolute path to the `.kbdb` database directory.
+ *
+ * Searches for a `.kbdb` sub-directory inside `targetDir`. When
+ * `targetDir` is omitted, `process.cwd()` is used as the base.
+ *
+ * @param targetDir - directory to search in; defaults to cwd
+ * @throws {Error} if no `.kbdb` directory exists at the resolved
+ *   path
+ */
+export declare function resolveDbPath(targetDir?: string): string;

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

@@ -0,0 +1,11 @@
+import type { Runtime } from '../../runtime/typings/runtime.ts';
+/**
+ * Spawns a detached worker daemon process for the given context.
+ *
+ * @param contextPath - absolute path to the context directory the
+ *   daemon should serve
+ * @param runtime - the current JavaScript runtime environment
+ * @param workerScript - absolute path to the worker daemon script,
+ *   resolved at the entry point by `resolveWorkerScript`
+ */
+export declare function spawnDaemon(contextPath: string, runtime: Runtime, workerScript?: string): void;

package/dist/src/shared/worker-client/functions/wait-for-daemon.function.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Waits for the worker daemon's PID file to appear on disk.
+ *
+ * Polls every 100 ms until the PID file at
+ * `<tmpdir>/kbdb-<contextId>.pid` exists or the timeout elapses.
+ *
+ * @param contextId - the 16-character context identifier
+ * @param timeoutMs - maximum wait time in milliseconds; defaults
+ *   to 10 000 ms
+ * @returns `true` if the PID file appeared before the timeout,
+ *   `false` otherwise
+ */
+export declare function waitForDaemon(contextId: string, timeoutMs?: number): Promise<boolean>;

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

@@ -0,0 +1,22 @@
+export { WorkerClient } from './classes/worker-client.class.ts';
+export { createWorkerClient } from './functions/create-worker-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';
+export { spawnDaemon } from './functions/spawn-daemon.function.ts';
+export { waitForDaemon } from './functions/wait-for-daemon.function.ts';
+export type { WorkerClientOptions } from './typings/worker-client-options.interface.ts';
+export type { SearchParams } from './typings/search-params.model.ts';
+export type { SearchResult } from './typings/search-result.model.ts';
+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 { 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 { 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';

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

@@ -0,0 +1,22 @@
+/** 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.
+     */
+    readonly attached: boolean;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Result returned by the daemon after composing a Markdown document
+ * from one or more kbid or docid identifiers.
+ */
+export interface ContentResult {
+    /** MIME type of the composed output, always `'text/markdown'`. */
+    readonly type: 'text/markdown';
+    /** The composed Markdown string. */
+    readonly data: string;
+    /** Character count of `data` (not byte count). */
+    readonly total: number;
+}

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

@@ -0,0 +1,7 @@
+/** Location information for a running worker daemon process. */
+export interface DaemonInfo {
+    /** PID of the running daemon process. */
+    readonly pid: number;
+    /** Absolute path to the daemon's IPC socket. */
+    readonly socketPath: string;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Report returned by the daemon after running garbage collection
+ * on the knowledge-base database.
+ */
+export interface GcResult {
+    /** Number of unreferenced sections removed. */
+    readonly removed_sections: number;
+    /** Total bytes freed by removing unreferenced sections. */
+    readonly removed_bytes: number;
+    /** Time taken to complete garbage collection, in milliseconds. */
+    readonly elapsed_ms: number;
+}

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

@@ -0,0 +1,36 @@
+/** A single integrity error found during a database check. */
+export interface IntegrityError {
+    /**
+     * The category of integrity violation detected.
+     *
+     * - `'checksum_mismatch'` -- stored content does not match its hash
+     * - `'orphan_section'` -- section not referenced by any document
+     * - `'orphan_document'` -- document references no existing sections
+     * - `'broken_reference'` -- a marker references a non-existent entity
+     * - `'type_mismatch'` -- stored MIME type conflicts with content
+     * - `'circular_reference'` -- marker chain contains a cycle
+     */
+    readonly type: 'checksum_mismatch' | 'orphan_section' | 'orphan_document' | 'broken_reference' | 'type_mismatch' | 'circular_reference';
+    /** Identifier of the entity (kbid or docid) that has the issue. */
+    readonly entity: string;
+    /** Human-readable description of the specific problem. */
+    readonly detail: string;
+}
+/**
+ * Report returned by the daemon after running an integrity check
+ * on the knowledge-base database.
+ */
+export interface IntegrityCheckResult {
+    /** `true` when all checks passed and no errors were found. */
+    readonly ok: boolean;
+    /** All integrity errors found; empty when `ok` is `true`. */
+    readonly errors: IntegrityError[];
+    /** Total number of sections examined. */
+    readonly sections_checked: number;
+    /** Total number of documents examined. */
+    readonly documents_checked: number;
+    /** Total number of marker references checked. */
+    readonly references_checked: number;
+    /** Time taken to complete the check, in milliseconds. */
+    readonly elapsed_ms: number;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Report returned by the daemon after running database migrations.
+ */
+export interface MigrateResult {
+    /** The database format version before migration. */
+    readonly oldVersion: number;
+    /** The database format version after migration. */
+    readonly newVersion: number;
+    /** Number of individual migration steps that were applied. */
+    readonly migrationsRun: number;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Report returned by the daemon after rebuilding all database indexes
+ * from section files and document manifests.
+ */
+export interface RebuildResult {
+    /** Number of text and code sections that were re-indexed. */
+    readonly sections_reindexed: number;
+    /** Total number of unique terms written to the rebuilt indexes. */
+    readonly terms_indexed: number;
+    /** Time taken to complete the rebuild, in milliseconds. */
+    readonly elapsed_ms: number;
+}

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

@@ -0,0 +1,7 @@
+/** Result returned by the daemon after removing a section. */
+export interface RemoveSectionResult {
+    /** `true` when the section was found and successfully removed. */
+    readonly removed: boolean;
+    /** Time taken to perform the removal, in milliseconds. */
+    readonly elapsed_ms: number;
+}

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

@@ -0,0 +1,12 @@
+/** Parameters for a search query sent to the worker daemon. */
+export interface SearchParams {
+    /** The search query string. */
+    readonly query: string;
+    /**
+     * Controls what entity type is returned.
+     * Defaults to `'sections'` when omitted.
+     */
+    readonly mode?: 'sections' | 'documents' | 'stats';
+    /** Maximum number of results to return. */
+    readonly limit?: number;
+}