@dikolab/kbdb 0.1.0

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

@@ -0,0 +1,217 @@
+import type { AddSectionResult } from '../../worker-client/typings/add-section-result.model.ts';
+import type { RemoveSectionResult } from './remove-section-result.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';
+/** Result returned by content composition. */
+export interface McpContentResult {
+    /** 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;
+}
+/** A single integrity error found during a database check. */
+export interface McpIntegrityError {
+    /** The category of integrity violation detected. */
+    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;
+}
+/** Integrity check report returned by the daemon. */
+export interface McpIntegrityCheckResult {
+    /** `true` when all checks passed and no errors were found. */
+    readonly ok: boolean;
+    /** All integrity errors found; empty when `ok` is `true`. */
+    readonly errors: McpIntegrityError[];
+    /** 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;
+}
+/** Garbage collection report returned by the daemon. */
+export interface McpGcResult {
+    /** 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;
+}
+/** Index rebuild report returned by the daemon. */
+export interface McpRebuildResult {
+    /** 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;
+}
+/**
+ * Interface for the worker client dependency consumed by the MCP
+ * server. Defines the knowledge-base operations the server exposes
+ * as MCP tools and resources without coupling to the concrete
+ * `WorkerClient` class.
+ */
+export interface McpWorkerClient {
+    /**
+     * Searches the knowledge base using the given parameters.
+     *
+     * @param params - query string and optional search options
+     * @returns ranked list of matching section summaries
+     */
+    search(params: {
+        /** Natural language query text. */
+        readonly query: string;
+        /** Search mode: 'sections', 'documents', or 'stats'. */
+        readonly mode?: string;
+        /** Maximum number of results to return. */
+        readonly limit?: number;
+    }): Promise<{
+        /** Knowledge-base identifier of the matched section. */
+        kbid: string;
+        /** Relevance score assigned by the ranking engine. */
+        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;
+        }[];
+    }[]>;
+    /**
+     * Adds a new section to the knowledge base.
+     *
+     * @param params - content type, raw content, and optional metadata
+     * @returns the assigned knowledge-base identifier
+     */
+    addSection(params: {
+        /** Semantic type label for the section content. */
+        readonly sectionType: string;
+        /** Raw text or base64-encoded content for the section. */
+        readonly content: string;
+        /** Optional section title. Required for image/* types. */
+        readonly title?: string;
+        /** Optional section description. */
+        readonly description?: string;
+        /** Optional document ID to group this section under. */
+        readonly docid?: string;
+    }): Promise<AddSectionResult>;
+    /**
+     * Removes a section from the knowledge base.
+     *
+     * @param kbid - knowledge-base identifier of the section to remove
+     * @returns removal result with `removed` flag and elapsed time
+     */
+    removeSection(kbid: string): Promise<RemoveSectionResult>;
+    /**
+     * Retrieves one or more 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<{
+        /** Knowledge-base identifier for this section. */
+        kbid: string;
+        /** Semantic type label assigned to the section. */
+        sectionType: string;
+        /** Raw text content of the section. */
+        content: string;
+        /** Byte size of the stored content. */
+        size: number;
+    }[]>;
+    /**
+     * Retrieves a full document record including its ordered 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<McpContentResult>;
+    /**
+     * Returns database metadata and status from the daemon.
+     *
+     * @returns document count, section count, and timing statistics
+     */
+    dbStatus(): Promise<{
+        /** Whether the daemon has finished loading its WASM modules. */
+        initialized: boolean;
+        /** Absolute path to the context directory the daemon serves. */
+        contextPath: string;
+        /** In-memory cache statistics. */
+        cacheStats: {
+            /** Number of content entries currently cached. */
+            contentCount: number;
+            /** Number of index entries currently cached. */
+            indexCount: number;
+        };
+    }>;
+    /**
+     * 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<McpIntegrityCheckResult>;
+    /**
+     * Removes unreferenced sections from the database.
+     *
+     * @returns a report of sections removed and bytes freed
+     */
+    gc(): Promise<McpGcResult>;
+    /**
+     * Reconstructs all index files from section files and document
+     * manifests on disk.
+     *
+     * @returns a report of sections and terms re-indexed
+     */
+    rebuildIndexes(): Promise<McpRebuildResult>;
+    /**
+     * 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[]>;
+    /**
+     * Groups a set of sections under a named document.
+     *
+     * @param title - human-readable document title
+     * @param kbids - identifiers of the sections to group
+     * @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>;
+    /** Destroys the IPC socket and clears the connection state. */
+    disconnect(): void;
+}
+export type { RemoveSectionResult };

package/dist/src/shared/mcp/typings/mcp-types.interface.d.ts

@@ -0,0 +1,149 @@
+/** A JSON-RPC 2.0 request message sent to the MCP server. */
+export interface McpRequest {
+    /** JSON-RPC protocol version. Must always be '2.0'. */
+    readonly jsonrpc: '2.0';
+    /** Request identifier; absent for notifications. */
+    readonly id?: number | string;
+    /** RPC method name. */
+    readonly method: string;
+    /** Optional method parameters. */
+    readonly params?: Record<string, unknown>;
+}
+/** A JSON-RPC 2.0 response message sent from the MCP server. */
+export interface McpResponse {
+    /** JSON-RPC protocol version. Must always be '2.0'. */
+    readonly jsonrpc: '2.0';
+    /** Echoes the request identifier. */
+    readonly id: number | string;
+    /** Successful result payload; absent when error is set. */
+    readonly result?: unknown;
+    /** Error payload; absent when result is set. */
+    readonly error?: {
+        /** Numeric error code as defined by JSON-RPC or MCP. */
+        readonly code: number;
+        /** Human-readable error message. */
+        readonly message: string;
+        /** Optional additional error data. */
+        readonly data?: unknown;
+    };
+}
+/** A JSON-RPC 2.0 notification with no expected response. */
+export interface McpNotification {
+    /** JSON-RPC protocol version. Must always be '2.0'. */
+    readonly jsonrpc: '2.0';
+    /** Notification method name. */
+    readonly method: string;
+    /** Optional notification parameters. */
+    readonly params?: Record<string, unknown>;
+}
+/**
+ * Optional behavioral hints for an MCP tool, used by clients to
+ * decide how to present or invoke the tool safely.
+ */
+export interface McpToolAnnotations {
+    /**
+     * Human-readable title for the tool, suitable for display
+     * in client UIs.
+     */
+    readonly title?: string;
+    /**
+     * When `true`, the tool only reads data and does not modify
+     * any server-side state.
+     */
+    readonly readOnlyHint?: boolean;
+    /**
+     * When `true`, the tool may cause data loss or irreversible
+     * changes.
+     */
+    readonly destructiveHint?: boolean;
+    /**
+     * When `true`, calling the tool multiple times with the same
+     * arguments produces the same result with no additional side
+     * effects.
+     */
+    readonly idempotentHint?: boolean;
+    /**
+     * When `true`, the tool may interact with systems or data
+     * outside the immediate knowledge base context.
+     */
+    readonly openWorldHint?: boolean;
+}
+/** Definition of a single MCP tool exposed by the server. */
+export interface McpToolDefinition {
+    /** Unique tool name used to invoke it. */
+    readonly name: string;
+    /** Human-readable description of what the tool does. */
+    readonly description: string;
+    /** JSON Schema object describing the tool's input parameters. */
+    readonly inputSchema: Record<string, unknown>;
+    /**
+     * Optional behavioral hints that describe how the tool
+     * interacts with state.
+     */
+    readonly annotations?: McpToolAnnotations;
+}
+/** A URI template describing an MCP resource the server serves. */
+export interface McpResourceTemplate {
+    /** RFC 6570 URI template for the resource. */
+    readonly uriTemplate: string;
+    /** Human-readable resource name. */
+    readonly name: string;
+    /** Human-readable description of the resource. */
+    readonly description: string;
+    /** Optional MIME type for the resource content. */
+    readonly mimeType?: string;
+}
+/** Identity information for the MCP server. */
+export interface McpServerInfo {
+    /** Server name reported during MCP initialization. */
+    readonly name: string;
+    /** Server version string reported during MCP initialization. */
+    readonly version: string;
+}
+/** MCP capability flags advertised during initialization. */
+export interface McpCapabilities {
+    /** Indicates the server supports the tools capability. */
+    readonly tools?: Record<string, unknown>;
+    /** Indicates the server supports the resources capability. */
+    readonly resources?: Record<string, unknown>;
+    /** Indicates the server supports the prompts capability. */
+    readonly prompts?: Record<string, unknown>;
+    /** Indicates the server supports the logging capability. */
+    readonly logging?: Record<string, unknown>;
+    /**
+     * Indicates the server supports the completions capability,
+     * providing argument auto-completion for prompts and resources.
+     */
+    readonly completions?: Record<string, unknown>;
+}
+/**
+ * Result returned by `handleToolCall`. Successful tool responses
+ * carry `isError: true` for application-level failures rather than
+ * using JSON-RPC error responses.
+ */
+export interface McpToolResult {
+    /** One or more text content items describing the result. */
+    readonly content: readonly {
+        /** Content type identifier, always 'text'. */
+        readonly type: string;
+        /** Text payload of the content item. */
+        readonly text: string;
+    }[];
+    /**
+     * Set to `true` when the tool encountered an application-level
+     * error. Absent or `false` on success.
+     */
+    readonly isError?: boolean;
+}
+/** Result returned by `handleResourceRead`. */
+export interface McpResourceResult {
+    /** One or more content items for the requested resource URI. */
+    readonly contents: readonly {
+        /** The resource URI that was read. */
+        readonly uri: string;
+        /** MIME type of the content body. */
+        readonly mimeType: string;
+        /** Text body of the resource. */
+        readonly text: string;
+    }[];
+}

package/dist/src/shared/mcp/typings/prompt-types.interface.d.ts

@@ -0,0 +1,37 @@
+/** A single argument definition for an MCP prompt. */
+export interface McpPromptArgument {
+    /** Argument name used as the placeholder key. */
+    readonly name: string;
+    /** Human-readable description of the argument. */
+    readonly description?: string;
+    /** Whether the argument must be supplied at invocation time. */
+    readonly required?: boolean;
+}
+/** An MCP prompt entry returned by `prompts/list`. */
+export interface McpPrompt {
+    /** Unique prompt name used to invoke it via `prompts/get`. */
+    readonly name: string;
+    /** Human-readable description of what the prompt does. */
+    readonly description?: string;
+    /**
+     * Declared arguments the prompt accepts.
+     * Absent or empty when the prompt takes no arguments.
+     */
+    readonly arguments?: readonly McpPromptArgument[];
+}
+/** A single message in an MCP prompt response. */
+export interface McpPromptMessage {
+    /**
+     * Conversation role for this message.
+     * `'assistant'` for persona/system context, `'user'` for
+     * instructions directed at the model.
+     */
+    readonly role: 'user' | 'assistant';
+    /** Text content of the message. */
+    readonly content: {
+        /** Content type identifier, always `'text'`. */
+        readonly type: 'text';
+        /** The text payload. */
+        readonly text: string;
+    };
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Result returned by `McpWorkerClient.removeSection`. Reports
+ * whether the section was removed and the elapsed operation time.
+ */
+export interface RemoveSectionResult {
+    /** `true` when the section was found and removed. */
+    readonly removed: boolean;
+    /** Elapsed time for the remove operation in milliseconds. */
+    readonly elapsed_ms: number;
+}

package/dist/src/shared/mcp/typings/sampling-types.interface.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A single message in an MCP sampling conversation, sent to or
+ * received from a language model.
+ */
+export interface McpSamplingMessage {
+    /** Originating role for this message. */
+    readonly role: 'user' | 'assistant';
+    /** Text content of the message. */
+    readonly content: {
+        /** Content type discriminant, always `'text'`. */
+        readonly type: 'text';
+        /** The text body of the message. */
+        readonly text: string;
+    };
+}
+/**
+ * Request sent by the MCP server to the client to sample a language
+ * model. The client is responsible for selecting the model and
+ * forwarding the request.
+ */
+export interface McpSamplingRequest {
+    /** Ordered list of messages forming the conversation context. */
+    readonly messages: readonly McpSamplingMessage[];
+    /**
+     * Maximum number of tokens the model should generate in its
+     * response.
+     */
+    readonly maxTokens: number;
+}
+/**
+ * Result returned by the client after sampling a language model,
+ * containing the assistant's generated response.
+ */
+export interface McpSamplingResult {
+    /** Role of the response message, always `'assistant'`. */
+    readonly role: 'assistant';
+    /** Text content generated by the model. */
+    readonly content: {
+        /** Content type discriminant, always `'text'`. */
+        readonly type: 'text';
+        /** The generated text response. */
+        readonly text: string;
+    };
+    /** Identifier of the model that produced the response. */
+    readonly model: string;
+}

package/dist/src/shared/mcp/typings/skill-types.interface.d.ts

@@ -0,0 +1,28 @@
+/** A single argument definition for a skill. */
+export interface SkillArgument {
+    /** Argument name, used as the placeholder key. */
+    readonly name: string;
+    /** The expected value type. Defaults to `'string'` when omitted. */
+    readonly type?: 'string' | 'number' | 'boolean';
+    /** Human-readable description of the argument. */
+    readonly description?: string;
+    /** Whether the argument must be supplied at invocation time. */
+    readonly required?: boolean;
+}
+/** A reusable AI agent capability stored in the knowledge base. */
+export interface SkillDefinition {
+    /** Unique skill name used for lookup. */
+    readonly name: string;
+    /** Human-readable description of the skill. */
+    readonly description?: string;
+    /**
+     * Declared arguments for the skill body template.
+     * Extracted from `{{argName}}` placeholders.
+     */
+    readonly arguments?: readonly SkillArgument[];
+    /**
+     * Template body of the skill.
+     * May contain `{{argName}}` placeholders for variable substitution.
+     */
+    readonly body: string;
+}

package/dist/src/shared/mod.d.ts

@@ -0,0 +1 @@
+export { VERSION as version } from './version/constants/version.constant.ts';

package/dist/src/shared/platform/functions/get-ipc-path.function.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns the platform-appropriate IPC socket path for a given
+ * context identifier.
+ *
+ * On Windows, returns a named pipe path (`\\.\pipe\kbdb-<ctx>`).
+ * On POSIX systems, returns a Unix domain socket path under the
+ * system temp directory (`<tmpdir>/kbdb-<ctx>.sock`).
+ *
+ * @param ctx - unique context identifier embedded in the path
+ */
+export declare function getIpcPath(ctx: string): string;

package/dist/src/shared/platform/functions/get-tmpdir.function.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Returns the operating system's default temporary directory path.
+ */
+export declare function getTmpdir(): string;

package/dist/src/shared/platform/functions/is-process-alive.function.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Checks whether a process with the given PID is alive.
+ *
+ * Sends signal `0` to the process, which performs a permission
+ * check without sending an actual signal. Returns `true` if the
+ * process exists and is reachable, `false` otherwise.
+ *
+ * @param pid - the process identifier to probe
+ */
+export declare function isProcessAlive(pid: number): boolean;

package/dist/src/shared/platform/index.d.ts

@@ -0,0 +1,3 @@
+export { getTmpdir } from './functions/get-tmpdir.function.ts';
+export { isProcessAlive } from './functions/is-process-alive.function.ts';
+export { getIpcPath } from './functions/get-ipc-path.function.ts';

package/dist/src/shared/runtime/functions/detect-runtime.d.ts

@@ -0,0 +1,8 @@
+import type { Runtime } from '../typings/runtime.ts';
+/**
+ * Detects the current JavaScript runtime environment.
+ *
+ * Returns `'deno'` when the global `Deno` object is present,
+ * otherwise returns `'node'`.
+ */
+export declare function detectRuntime(): Runtime;

package/dist/src/shared/runtime/functions/get-args.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns the command-line arguments for the current runtime.
+ *
+ * In Deno, reads `Deno.args`; in Node.js, slices `process.argv`
+ * past the interpreter and script entries.
+ */
+export declare function getArgs(): string[];

package/dist/src/shared/runtime/index.d.ts

@@ -0,0 +1,3 @@
+export { detectRuntime } from './functions/detect-runtime.ts';
+export { getArgs } from './functions/get-args.ts';
+export type { Runtime } from './typings/runtime.ts';

package/dist/src/shared/runtime/typings/runtime.d.ts

@@ -0,0 +1,2 @@
+/** The runtime environment in which the library is executing. */
+export type Runtime = 'deno' | 'node';

package/dist/src/shared/version/constants/version.constant.d.ts

@@ -0,0 +1,2 @@
+/** Current package version, kept in sync with package.json. */
+export declare const VERSION = "0.1.0";

package/dist/src/shared/version/index.d.ts

@@ -0,0 +1 @@
+export { VERSION } from './constants/version.constant.ts';

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

@@ -0,0 +1,5 @@
+export interface ComposeOutput {
+    markdown: string;
+    totalChars: bigint;
+}
+export declare function decodeComposeOutput(bytes: Uint8Array): ComposeOutput;

package/dist/src/shared/wasm-codec/functions/decode-document-manifest-list.function.d.ts

@@ -0,0 +1,14 @@
+import type { DocumentManifest, DocumentSection } from './decode-document-manifest.function.ts';
+export type { DocumentManifest, DocumentSection };
+/**
+ * Decodes a WASM byte slice into an array of `DocumentManifest` values.
+ *
+ * The binary format is: u32 count, followed by count × DocumentManifest
+ * entries. Each entry contains: docid (string), title (string),
+ * createdAt (u64), docType (string), section count (u32), then each
+ * section's kbid (string) and position (u32).
+ *
+ * @param bytes - raw bytes returned by `worker_list_docs_by_type`
+ * @returns decoded array of document manifests, empty when count is zero
+ */
+export declare function decodeDocumentManifestList(bytes: Uint8Array): DocumentManifest[];

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

@@ -0,0 +1,40 @@
+/**
+ * A single section reference within a document manifest.
+ *
+ * Associates a knowledge-base identifier with the section's
+ * ordinal position in the document.
+ */
+export interface DocumentSection {
+    /** Knowledge-base identifier of the referenced section. */
+    kbid: string;
+    /** Zero-based position of this section within its document. */
+    position: number;
+}
+/**
+ * A document manifest decoded from WASM binary output.
+ *
+ * Represents a grouped document record with its ordered list of
+ * section references as returned by `worker_retrieve_doc`.
+ */
+export interface DocumentManifest {
+    /** Unique document identifier. */
+    docid: string;
+    /** Human-readable document title. */
+    title: string;
+    /** Document creation timestamp as a Unix epoch value. */
+    createdAt: bigint;
+    /** Application-level type name assigned to this document. */
+    docType: string;
+    /** Ordered list of section references belonging to the document. */
+    sections: DocumentSection[];
+}
+/**
+ * Decodes a single `DocumentManifest` from WASM binary output.
+ *
+ * Reads fields in the order: docid, title, createdAt, docType,
+ * section count, then each section's kbid and position.
+ *
+ * @param bytes - raw bytes returned by `worker_retrieve_doc`
+ * @returns the decoded document manifest
+ */
+export declare function decodeDocumentManifest(bytes: Uint8Array): DocumentManifest;

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

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

package/dist/src/shared/wasm-codec/functions/decode-key-value-text.function.d.ts

@@ -0,0 +1 @@
+export declare function decodeKeyValueText(text: string): Record<string, string>;

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

@@ -0,0 +1 @@
+export declare function decodeRemoveFlag(bytes: Uint8Array): boolean;

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

@@ -0,0 +1,10 @@
+export interface TermMatch {
+    term: string;
+    frequency: number;
+}
+export interface ScoredResult {
+    kbid: string;
+    score: number;
+    matches: TermMatch[];
+}
+export declare function decodeScoredResults(bytes: Uint8Array): ScoredResult[];

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

@@ -0,0 +1,13 @@
+import type { SectionRecord } from './decode-section-records.function.ts';
+export type { SectionRecord };
+/**
+ * Decodes a WASM byte slice into an array of `SectionRecord` values.
+ *
+ * Thin wrapper around `decodeSectionRecords` provided as the
+ * canonical entry point for list-response decoding from WASM exports
+ * such as `worker_list_by_type`.
+ *
+ * @param bytes - raw bytes returned by a WASM section-list export
+ * @returns decoded array of section records
+ */
+export declare function decodeSectionRecordList(bytes: Uint8Array): SectionRecord[];