@dikolab/kbdb 0.2.2 → 0.3.1

package/src/shared/worker-client/functions/send-ipc-request.function.ts

@@ -0,0 +1,39 @@
+import type { Socket } from 'node:net';
+import type { PendingCall } from '../typings/pending-call.interface.ts';
+
+/**
+ * Sends a JSON-RPC 2.0 request over `socket` and registers the
+ * `resolve`/`reject` pair in `pending` so the response can be
+ * matched back.
+ *
+ * @param socket - connected IPC socket
+ * @param pending - map of outstanding request IDs to their
+ *   resolve/reject pairs; mutated by this function
+ * @param nextId - the request ID to assign; must be the current
+ *   value of the caller's monotonic counter
+ * @param contextId - 16-character context identifier sent as `ctx`
+ * @param method - JSON-RPC method name
+ * @param params - method parameters (merged with `ctx`)
+ * @throws {Error} when the socket is not connected (`socket` is
+ *   null) -- call the check before invoking this function
+ */
+export function sendIpcRequest(
+   socket: Socket,
+   pending: Map<number, PendingCall>,
+   nextId: number,
+   contextId: string,
+   method: string,
+   params: unknown,
+): Promise<unknown> {
+   const request = {
+      jsonrpc: '2.0',
+      id: nextId,
+      method,
+      params: { ctx: contextId, ...(params as object) },
+   };
+
+   return new Promise<unknown>((resolve, reject) => {
+      pending.set(nextId, { resolve, reject });
+      socket.write(JSON.stringify(request) + '\n');
+   });
+}

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

@@ -18,7 +18,10 @@ export type {
 export type { StatusResult } from './typings/status-result.model.ts';
 export type { WorkerClientError } from './typings/worker-client-error.interface.ts';
 export type { DaemonInfo } from './typings/daemon-info.model.ts';
-export type { AddSectionResult } from './typings/add-section-result.model.ts';
+export type {
+   AddSectionResult,
+   NearDuplicateEntry,
+} from './typings/add-section-result.model.ts';
 export type { RemoveSectionResult } from './typings/remove-section-result.model.ts';
 export type { ContentResult } from './typings/content-result.model.ts';
 export type {

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

@@ -1,22 +1,39 @@
+/**
+ * A near-duplicate section reported after adding a new section.
+ */
+export interface NearDuplicateEntry {
+   /** Knowledge-base identifier of the near-duplicate section. */
+   readonly kbid: string;
+   /** Jaccard similarity score (0.0--1.0). */
+   readonly similarity: number;
+   /** Detection method that produced this match. */
+   readonly method?: 'jaccard' | 'cosine';
+}
+
 /** Result returned by the daemon after adding a new section. */
 export interface AddSectionResult {
    /** Knowledge-base identifier assigned to the section. */
    readonly kbid: string;
-   /** MIME type of the stored section. */
-   readonly type: string;
-   /** Section title, if provided. */
-   readonly title?: string;
-   /** Section description, if provided. */
-   readonly description?: string;
-   /** Total token count for the section. */
-   readonly token_count: number;
-   /** Number of unique terms indexed for this section. */
-   readonly indexed_terms_count: number;
-   /** Time taken to process and store the section, in milliseconds. */
-   readonly elapsed_ms: number;
    /**
-    * `true` when the content already existed and the provided docid
-    * was added to the existing section's `docids` list.
+    * Number of unique terms indexed for the section.
+    * Present in the current binary-decoded response format.
+    */
+   readonly indexed_terms_count?: number;
+   /**
+    * Wall-clock time the add operation took, in milliseconds.
+    * Present in the current binary-decoded response format.
+    */
+   readonly elapsed_ms?: number;
+   /**
+    * Knowledge-base identifier of the section that was superseded,
+    * or `null` if no supersession occurred.
+    */
+   readonly superseded?: string | null;
+   /** Advisory warnings emitted during indexing. */
+   readonly warnings?: string[];
+   /**
+    * Near-duplicate sections detected above the similarity threshold
+    * (Jaccard >= 0.85).
     */
-   readonly attached: boolean;
+   readonly near_duplicates?: NearDuplicateEntry[];
 }

package/src/shared/worker-client/typings/export-result.model.ts

@@ -0,0 +1,14 @@
+/**
+ * Report returned by the daemon after exporting the database to a
+ * target directory.
+ */
+export interface ExportResult {
+   /** Absolute path to the directory where files were written. */
+   readonly path: string;
+   /** Number of section files copied to the export directory. */
+   readonly sections_exported: number;
+   /** Number of document manifest files copied. */
+   readonly documents_exported: number;
+   /** Wall-clock time the export operation took, in milliseconds. */
+   readonly elapsed_ms: number;
+}

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

@@ -9,4 +9,10 @@ export interface GcResult {
    readonly removed_bytes: number;
    /** Time taken to complete garbage collection, in milliseconds. */
    readonly elapsed_ms: number;
+   /**
+    * Number of sections whose source_path file no longer contains
+    * their heading text. Advisory; not auto-removed by gc.
+    * Absent on older daemon versions.
+    */
+   readonly stale_sources?: number;
 }

package/src/shared/worker-client/typings/json-rpc-response.interface.ts

@@ -0,0 +1,17 @@
+/** Shape of a JSON-RPC 2.0 error object from the daemon. */
+export interface JsonRpcError {
+   /** Numeric JSON-RPC error code. */
+   readonly code: number;
+   /** Human-readable error message. */
+   readonly message: string;
+}
+
+/** Shape of a JSON-RPC 2.0 response from the daemon. */
+export interface JsonRpcResponse {
+   /** Monotonically increasing request identifier. */
+   readonly id: number;
+   /** Result payload; present on success. */
+   readonly result?: unknown;
+   /** Error detail; present on failure. */
+   readonly error?: JsonRpcError;
+}

package/src/shared/worker-client/typings/pending-call.interface.ts

@@ -0,0 +1,7 @@
+/** Pending JSON-RPC call awaiting a response from the daemon. */
+export interface PendingCall {
+   /** Resolves with the result when the daemon responds. */
+   resolve: (v: unknown) => void;
+   /** Rejects with an error when the daemon returns an error. */
+   reject: (e: Error) => void;
+}

package/src/shared/worker-client/typings/recall-document.model.ts

@@ -0,0 +1,16 @@
+/** A document record included at depth >= 1. */
+export interface RecallDocument {
+   /** Unique document identifier. */
+   readonly docid: string;
+   /** Human-readable document title. */
+   readonly title: string;
+   /** Ordered list of section summaries belonging to this document. */
+   readonly sections: readonly {
+      /** Knowledge-base identifier of the section. */
+      readonly kbid: string;
+      /** Section heading text, or `null` when absent. */
+      readonly heading: string | null;
+      /** Semantic type label for the section. */
+      readonly type: string;
+   }[];
+}

package/src/shared/worker-client/typings/recall-params.model.ts

@@ -0,0 +1,15 @@
+/** Parameters for a recall operation. */
+export interface RecallParams {
+   /** Single section identifier to recall. */
+   readonly kbid?: string;
+   /** Batch of section identifiers to recall. */
+   readonly kbids?: readonly string[];
+   /**
+    * Context expansion depth (0-3).
+    *
+    * At depth 0 only the section itself is returned.
+    * Higher values include progressively more context:
+    * documents, siblings, and references.
+    */
+   readonly depth?: number;
+}

package/src/shared/worker-client/typings/recall-reference.model.ts

@@ -0,0 +1,32 @@
+/**
+ * A section that references or is referenced by the recalled
+ * section.
+ */
+export interface RecallReference {
+   /**
+    * Knowledge-base identifier of the referencing/referenced
+    * section.
+    */
+   readonly kbid: string;
+   /**
+    * Heading text of the referencing section, or `null` when
+    * absent.
+    */
+   readonly heading: string | null;
+   /** Semantic type label of the referencing section. */
+   readonly type: string;
+   /**
+    * Application-level marker type (e.g. `'see_also'`, `'link'`).
+    */
+   readonly marker_type: string;
+   /**
+    * Short excerpt from the referencing section surrounding the
+    * marker.
+    */
+   readonly context_snippet: string;
+   /**
+    * Whether the reference is `'forward'` (outgoing) or `'back'`
+    * (incoming).
+    */
+   readonly direction: 'forward' | 'back';
+}

package/src/shared/worker-client/typings/recall-sibling.model.ts

@@ -0,0 +1,11 @@
+/** A sibling section adjacent to the recalled section. */
+export interface RecallSibling {
+   /** Knowledge-base identifier of the sibling section. */
+   readonly kbid: string;
+   /** Sibling heading text, or `null` when absent. */
+   readonly heading: string | null;
+   /** Semantic type label for the sibling section. */
+   readonly type: string;
+   /** Full text content of the sibling section. */
+   readonly content: string;
+}

package/src/shared/worker-client/typings/recall-single-result.model.ts

@@ -0,0 +1,41 @@
+import type { RecallDocument } from './recall-document.model.ts';
+import type { RecallReference } from './recall-reference.model.ts';
+import type { RecallSibling } from './recall-sibling.model.ts';
+
+/** Full content and context for a recalled knowledge-base section. */
+export interface RecallResult {
+   /** Knowledge-base identifier of the recalled section. */
+   readonly kbid: string;
+   /** Section heading text, or `null` when absent. */
+   readonly heading: string | null;
+   /** Semantic type label for the section. */
+   readonly type: string;
+   /** Full text content of the section. */
+   readonly content: string;
+   /** Identifiers of documents that contain this section. */
+   readonly docids: readonly string[];
+   /**
+    * Full document records containing this section.
+    *
+    * Populated when `depth >= 1`.
+    */
+   readonly documents?: readonly RecallDocument[];
+   /**
+    * Sections that contain a marker pointing back to this section.
+    *
+    * Populated when `depth >= 1`.
+    */
+   readonly back_references?: readonly RecallReference[];
+   /**
+    * Sections adjacent to this section in the same document.
+    *
+    * Populated when `depth >= 1`.
+    */
+   readonly siblings?: readonly RecallSibling[];
+   /**
+    * Sections that this section points to via markers.
+    *
+    * Populated when `depth >= 1`.
+    */
+   readonly references?: readonly RecallReference[];
+}

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

@@ -14,6 +14,18 @@ export interface SearchResult {
    readonly snippet: string;
    /** Query terms that matched within this section. */
    readonly matched_terms: readonly string[];
+   /**
+    * Fields that contained at least one match
+    * (e.g. `'heading'`, `'body'`).
+    */
+   readonly matched_fields?: readonly string[];
+   /**
+    * Normalised confidence score (0.0-1.0) relative to the top result.
+    * May be absent from older daemon versions.
+    */
+   readonly confidence?: number;
+   /** ISO 8601 creation timestamp of the section. */
+   readonly created_at?: string;
 }
 
 /** Paginated search result envelope. */

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

@@ -24,4 +24,20 @@ export interface AddSectionParams {
    readonly content: string;
    /** Parent document identifier to associate the section with. */
    readonly docid?: string;
+   /** Human-readable heading for the section. */
+   readonly title?: string;
+   /** Short summary or description of the section. */
+   readonly description?: string;
+   /** Application-defined tags for scoping and filtering. */
+   readonly tags?: string[];
+   /**
+    * When `true`, supersedes an existing section with the same
+    * source key (derived from `sourcePath` and `title`).
+    */
+   readonly replace?: boolean;
+   /**
+    * Absolute path to the source file. Required for supersession
+    * via source key when `replace` is `true`.
+    */
+   readonly sourcePath?: string;
 }

package/src/shared/worker-daemon/classes/ipc-error.class.ts

@@ -0,0 +1,22 @@
+/**
+ * Typed JSON-RPC error thrown inside WorkerDaemon dispatch.
+ *
+ * Carries a numeric JSON-RPC error code alongside the standard
+ * `Error` message so that `handleRequest` can build a well-formed
+ * JSON-RPC error response without an additional type check.
+ */
+export class IpcError extends Error {
+   /** JSON-RPC error code. */
+   readonly code: number;
+
+   /**
+    * @param code - JSON-RPC error code (e.g. `-32601` for
+    *   method-not-found, `-32000` for application errors)
+    * @param message - human-readable error description
+    */
+   constructor(code: number, message: string) {
+      super(message);
+      this.code = code;
+      this.name = 'IpcError';
+   }
+}