@dikolab/kbdb 0.2.2 → 0.3.1

package/src/shared/mcp/typings/mcp-server-state.interface.ts

@@ -0,0 +1,17 @@
+import type { McpLogLevel } from './log-types.interface.ts';
+
+/**
+ * Mutable runtime state shared by `McpServer` and its request
+ * handler. Extracted as an interface so the handler can be
+ * tested independently of the full server class.
+ */
+export interface McpServerState {
+   /** Advertised capabilities received from the MCP host. */
+   hostCapabilities: Record<string, unknown> | null;
+   /** Currently configured log level, or `null` when unset. */
+   logLevel: McpLogLevel | null;
+   /** Set of URI strings that the host has subscribed to. */
+   readonly subscriptions: Set<string>;
+   /** Filesystem path used as the KB context root. */
+   readonly contextPath: string;
+}

package/src/shared/mcp/typings/mcp-tool-annotations.interface.ts

@@ -0,0 +1,32 @@
+/**
+ * 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;
+}

package/src/shared/mcp/typings/mcp-tool-definition.interface.ts

@@ -0,0 +1,16 @@
+import type { McpToolAnnotations } from './mcp-tool-annotations.interface.ts';
+
+/** 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;
+}

package/src/shared/mcp/typings/mcp-tool-result.interface.ts

@@ -0,0 +1,19 @@
+/**
+ * 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;
+}

package/src/shared/mcp/typings/mcp-worker-client.interface.ts

@@ -0,0 +1,243 @@
+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';
+import type { McpContentResult } from './mcp-content-result.model.ts';
+import type { McpIntegrityCheckResult } from './mcp-integrity-check-result.model.ts';
+import type { McpGcResult } from './mcp-gc-result.model.ts';
+import type { McpRebuildResult } from './mcp-rebuild-result.model.ts';
+import type { McpExportResult } from './mcp-export-result.model.ts';
+
+/**
+ * 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;
+      /**
+       * Search algorithm: `'lexical'`, `'vector'`, or `'hybrid'`.
+       * Defaults to `'lexical'` when omitted.
+       */
+      readonly algo?: string;
+      /** Maximum number of results to return. */
+      readonly limit?: number;
+      /** Number of results to skip for pagination. */
+      readonly offset?: number;
+   }): Promise<{
+      readonly items: readonly {
+         readonly kbid: string;
+         readonly heading: string | null;
+         readonly type: string;
+         readonly docids: readonly string[];
+         readonly score: number;
+         readonly snippet: string;
+         readonly matched_terms: readonly string[];
+         /** Fields that contained matches (heading, body, code). */
+         readonly matched_fields?: readonly string[];
+         /** ISO 8601 creation timestamp of the section. */
+         readonly created_at?: string;
+      }[];
+      readonly total: number;
+      readonly offset: number;
+      readonly limit: number;
+      readonly has_more: boolean;
+      /**
+       * `true` when results came from an automatic AND-to-OR
+       * fallback query relaxation.
+       */
+      readonly relaxed?: boolean;
+   }>;
+
+   /**
+    * 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;
+      /** Optional tags for scoping and filtering. */
+      readonly tags?: string[];
+      /**
+       * When `true`, replaces an existing section that has the same
+       * source key (supersession).
+       */
+      readonly replace?: boolean;
+   }): 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>;
+
+   /**
+    * Retrieves full content and context for one or more sections by
+    * their knowledge-base identifiers.
+    *
+    * @param params - section identifier(s) and optional expansion depth
+    * @returns a single result or array of results depending on input
+    */
+   recall(params: {
+      /** Single section identifier. */
+      readonly kbid?: string;
+      /** Batch section identifiers. */
+      readonly kbids?: readonly string[];
+      /** Expansion depth (0-3, default: 0). */
+      readonly depth?: number;
+   }): Promise<unknown>;
+
+   /**
+    * Exports the database to a target directory as a self-contained
+    * snapshot (sections, documents, catalog -- no indexes).
+    *
+    * @param params - optional export parameters
+    * @returns export report with the resolved path and file counts
+    */
+   export(params?: {
+      readonly path?: string;
+   }): Promise<McpExportResult>;
+
+   /** Destroys the IPC socket and clears the connection state. */
+   disconnect(): void;
+}

package/src/shared/mcp/typings/tool-call-result.model.ts

@@ -0,0 +1,18 @@
+/** Shape of a content item in an MCP tool call response. */
+export interface ToolContent {
+   /** Content type identifier, typically `'text'`. */
+   readonly type: string;
+   /** The text payload. */
+   readonly text: string;
+}
+
+/**
+ * Result returned by any MCP tool call handler, containing one or
+ * more content items and an optional error flag.
+ */
+export interface ToolCallResult {
+   /** One or more content items describing the result. */
+   readonly content: ToolContent[];
+   /** Set to `true` when the tool encountered an error. */
+   readonly isError?: boolean;
+}

package/src/shared/sync/functions/build-import-report.function.ts

@@ -0,0 +1,40 @@
+import type { ConflictResolution } from '../typings/conflict-resolution.type.ts';
+import type { ExportEntry } from '../typings/export-entry.interface.ts';
+import type { ImportReport } from '../typings/import-report.interface.ts';
+
+/** A resolution record pairing an entry with its resolution. */
+interface ResolutionRecord {
+   /** The export entry being resolved. */
+   readonly entry: ExportEntry;
+   /** The resolution applied to the entry. */
+   readonly resolution: ConflictResolution;
+}
+
+/**
+ * Builds an import report from resolution results.
+ *
+ * Counts each resolution type and determines whether
+ * a database rebuild is required after the import.
+ */
+export function buildImportReport(
+   resolutions: readonly ResolutionRecord[],
+): ImportReport {
+   let sectionsAdded = 0;
+   let sectionsSkipped = 0;
+   let sectionsSuperseded = 0;
+
+   for (const { resolution } of resolutions) {
+      if (resolution === 'add') sectionsAdded++;
+      else if (resolution === 'skip') sectionsSkipped++;
+      else sectionsSuperseded++;
+   }
+
+   return {
+      sectionsAdded,
+      sectionsSkipped,
+      sectionsSuperseded,
+      documentsAdded: sectionsAdded,
+      documentsSkipped: sectionsSkipped,
+      rebuildRequired: sectionsAdded > 0 || sectionsSuperseded > 0,
+   };
+}

package/src/shared/sync/functions/parse-export-entry.function.ts

@@ -0,0 +1,45 @@
+import type { ExportEntry } from '../typings/export-entry.interface.ts';
+
+/** Extracts a quoted string value for a TOML key. */
+function extractField(lines: string[], key: string): string {
+   for (const line of lines) {
+      const prefix = `${key} = "`;
+      if (line.startsWith(prefix) && line.endsWith('"')) {
+         return line.slice(prefix.length, -1);
+      }
+   }
+   throw new Error(`Missing required field: ${key}`);
+}
+
+/**
+ * Parses a serialized export entry.
+ *
+ * Expects TOML frontmatter delimited by `+++` lines,
+ * followed by the body content.
+ *
+ * @throws {Error} if the frontmatter delimiters are absent
+ *   or required fields are missing.
+ */
+export function parseExportEntry(content: string): ExportEntry {
+   const firstDelim = content.indexOf('+++');
+   if (firstDelim === -1) {
+      throw new Error('Missing opening +++ delimiter');
+   }
+   const afterFirst = firstDelim + 3;
+   const secondDelim = content.indexOf('+++', afterFirst);
+   if (secondDelim === -1) {
+      throw new Error('Missing closing +++ delimiter');
+   }
+
+   const frontmatter = content.slice(afterFirst, secondDelim).trim();
+   const body = content.slice(secondDelim + 3).replace(/^\n/, '');
+   const lines = frontmatter.split('\n');
+
+   return {
+      kbid: extractField(lines, 'kbid'),
+      sourceKey: extractField(lines, 'sourceKey'),
+      heading: extractField(lines, 'heading'),
+      createdAt: extractField(lines, 'createdAt'),
+      body,
+   };
+}

package/src/shared/sync/functions/resolve-conflict.function.ts

@@ -0,0 +1,31 @@
+import type { ConflictResolution } from '../typings/conflict-resolution.type.ts';
+import type { ExportEntry } from '../typings/export-entry.interface.ts';
+
+/**
+ * Determines the conflict resolution action for
+ * an incoming section.
+ *
+ * Rules applied in order:
+ * 1. Same kbid exists -> skip
+ * 2. Same source_key, incoming is newer -> supersede
+ * 3. Same source_key, incoming is not newer -> skip
+ * 4. No match -> add
+ */
+export function resolveConflict(
+   incoming: ExportEntry,
+   existingKbids: ReadonlySet<string>,
+   existingBySourceKey: ReadonlyMap<string, ExportEntry>,
+): ConflictResolution {
+   if (existingKbids.has(incoming.kbid)) {
+      return 'skip';
+   }
+
+   const existing = existingBySourceKey.get(incoming.sourceKey);
+   if (existing !== undefined) {
+      const incomingTime = new Date(incoming.createdAt).getTime();
+      const existingTime = new Date(existing.createdAt).getTime();
+      return incomingTime > existingTime ? 'supersede' : 'skip';
+   }
+
+   return 'add';
+}

package/src/shared/sync/functions/serialize-export-entry.function.ts

@@ -0,0 +1,18 @@
+import type { ExportEntry } from '../typings/export-entry.interface.ts';
+
+/**
+ * Serializes an export entry to a flat file format.
+ *
+ * Format: TOML frontmatter delimited by `+++` lines,
+ * followed by the body content.
+ */
+export function serializeExportEntry(entry: ExportEntry): string {
+   const frontmatter = [
+      `kbid = "${entry.kbid}"`,
+      `sourceKey = "${entry.sourceKey}"`,
+      `heading = "${entry.heading}"`,
+      `createdAt = "${entry.createdAt}"`,
+   ].join('\n');
+
+   return `+++\n${frontmatter}\n+++\n${entry.body}`;
+}

package/src/shared/sync/index.ts

@@ -0,0 +1,9 @@
+export { resolveConflict } from './functions/resolve-conflict.function.ts';
+export { buildImportReport } from './functions/build-import-report.function.ts';
+export { serializeExportEntry } from './functions/serialize-export-entry.function.ts';
+export { parseExportEntry } from './functions/parse-export-entry.function.ts';
+export type { ExportEntry } from './typings/export-entry.interface.ts';
+export type { ExportOptions } from './typings/export-options.interface.ts';
+export type { ImportOptions } from './typings/import-options.interface.ts';
+export type { ImportReport } from './typings/import-report.interface.ts';
+export type { ConflictResolution } from './typings/conflict-resolution.type.ts';

package/src/shared/sync/typings/conflict-resolution.type.ts

@@ -0,0 +1,8 @@
+/**
+ * Conflict resolution strategy.
+ *
+ * - 'skip': same kbid -> skip
+ * - 'supersede': same source_key -> replace if newer
+ * - 'add': no match -> add
+ */
+export type ConflictResolution = 'skip' | 'supersede' | 'add';

package/src/shared/sync/typings/export-entry.interface.ts

@@ -0,0 +1,13 @@
+/** A single entry in an export manifest. */
+export interface ExportEntry {
+   /** Section kbid. */
+   readonly kbid: string;
+   /** Source key. */
+   readonly sourceKey: string;
+   /** Section heading. */
+   readonly heading: string;
+   /** Content body. */
+   readonly body: string;
+   /** Created timestamp (ISO). */
+   readonly createdAt: string;
+}

package/src/shared/sync/typings/export-options.interface.ts

@@ -0,0 +1,9 @@
+/** Options for export operation. */
+export interface ExportOptions {
+   /** Export format. */
+   readonly format: 'git' | 'archive';
+   /** Output directory or file path. */
+   readonly outputPath: string;
+   /** Exclude vector indexes. */
+   readonly excludeVectors: boolean;
+}

package/src/shared/sync/typings/import-options.interface.ts

@@ -0,0 +1,7 @@
+/** Options for import operation. */
+export interface ImportOptions {
+   /** Source path (exported directory or archive). */
+   readonly fromPath: string;
+   /** Dry-run mode. */
+   readonly dryRun: boolean;
+}

package/src/shared/sync/typings/import-report.interface.ts

@@ -0,0 +1,15 @@
+/** Report of an import operation. */
+export interface ImportReport {
+   /** Sections added. */
+   readonly sectionsAdded: number;
+   /** Sections skipped (same kbid). */
+   readonly sectionsSkipped: number;
+   /** Sections superseded (same source_key, newer). */
+   readonly sectionsSuperseded: number;
+   /** Documents added. */
+   readonly documentsAdded: number;
+   /** Documents skipped. */
+   readonly documentsSkipped: number;
+   /** Whether rebuild is required. */
+   readonly rebuildRequired: boolean;
+}

package/src/shared/wasm-codec/functions/decode-add-section-result.function.ts

@@ -0,0 +1,112 @@
+import { decodeString } from './decode-string.function.ts';
+import { decodeU32 } from './decode-u32.function.ts';
+import { decodeU64 } from './decode-u64.function.ts';
+import { decodeF32 } from './decode-f32.function.ts';
+
+/**
+ * A near-duplicate section identified during add-section indexing.
+ */
+export interface NearDuplicate {
+   /** Knowledge-base identifier of the near-duplicate section. */
+   readonly kbid: string;
+   /** Jaccard similarity score (0.0–1.0). */
+   readonly similarity: number;
+}
+
+/**
+ * Decoded result of a `worker_add_section` WASM call.
+ *
+ * Mirrors the Rust `AddSectionResult` struct encoded via the
+ * `Encode` trait wire format.
+ */
+export interface AddSectionResult {
+   /** Knowledge-base identifier assigned to the new section. */
+   readonly kbid: string;
+   /** Number of unique terms indexed for the section. */
+   readonly indexedTermsCount: number;
+   /** Wall-clock time the add operation took, in milliseconds. */
+   readonly elapsedMs: 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 nearDuplicates: NearDuplicate[];
+}
+
+/**
+ * Decodes the binary `AddSectionResult` returned by the
+ * `worker_add_section` WASM export.
+ *
+ * Wire format (little-endian):
+ * - `kbid`: `u32` length + UTF-8 bytes
+ * - `indexed_terms_count`: `u32`
+ * - `elapsed_ms`: `u64`
+ * - `superseded`: `u8` flag (0=None, 1=Some) + optional `String`
+ * - `warnings`: `u32` count + each `String`
+ * - `near_duplicates`: `u32` count + each (`String` + `f32`)
+ */
+export function decodeAddSectionResult(
+   bytes: Uint8Array,
+): AddSectionResult {
+   let offset = 0;
+
+   const kbid = decodeString(bytes, offset);
+   offset += kbid.bytesRead;
+
+   const indexedTermsCount = decodeU32(bytes, offset);
+   offset += indexedTermsCount.bytesRead;
+
+   const elapsedMsBig = decodeU64(bytes, offset);
+   offset += elapsedMsBig.bytesRead;
+
+   // Decode Option<String> for superseded
+   const supersededTag = bytes[offset];
+   offset += 1;
+   let superseded: string | null = null;
+   if (supersededTag === 0x01) {
+      const supersededStr = decodeString(bytes, offset);
+      offset += supersededStr.bytesRead;
+      superseded = supersededStr.value;
+   }
+
+   // Decode Vec<String> for warnings
+   const warningCount = decodeU32(bytes, offset);
+   offset += warningCount.bytesRead;
+   const warnings: string[] = [];
+   for (let i = 0; i < warningCount.value; i++) {
+      const warning = decodeString(bytes, offset);
+      offset += warning.bytesRead;
+      warnings.push(warning.value);
+   }
+
+   // Decode Vec<(String, f32)> for near_duplicates
+   const dupCount = decodeU32(bytes, offset);
+   offset += dupCount.bytesRead;
+   const nearDuplicates: NearDuplicate[] = [];
+   for (let i = 0; i < dupCount.value; i++) {
+      const dupKbid = decodeString(bytes, offset);
+      offset += dupKbid.bytesRead;
+      const similarity = decodeF32(bytes, offset);
+      offset += similarity.bytesRead;
+      nearDuplicates.push({
+         kbid: dupKbid.value,
+         similarity: similarity.value,
+      });
+   }
+
+   return {
+      kbid: kbid.value,
+      indexedTermsCount: indexedTermsCount.value,
+      elapsedMs: Number(elapsedMsBig.value),
+      superseded,
+      warnings,
+      nearDuplicates,
+   };
+}