@dikolab/kbdb 0.3.0 → 0.3.1

package/src/shared/wasm-codec/functions/decode-wasm-list.function.ts

@@ -0,0 +1,31 @@
+import { decodeU32 } from './decode-u32.function.ts';
+import type { ItemDecoder } from '../typings/item-decoder.type.ts';
+
+export type { ItemDecoder };
+
+/**
+ * Decodes a length-prefixed list from WASM binary output.
+ *
+ * Wire format: u32 item count, then that many items decoded
+ * sequentially by `decode`.
+ *
+ * @param bytes - raw binary buffer
+ * @param offset - byte position of the u32 count
+ * @param decode - decoder function for each item
+ * @returns decoded item array and total bytes consumed
+ */
+export function decodeWasmList<T>(
+   bytes: Uint8Array,
+   offset: number,
+   decode: ItemDecoder<T>,
+): { items: T[]; bytesRead: number } {
+   const count = decodeU32(bytes, offset);
+   let pos = offset + count.bytesRead;
+   const items: T[] = [];
+   for (let i = 0; i < count.value; i++) {
+      const result = decode(bytes, pos);
+      pos += result.bytesRead;
+      items.push(result.value);
+   }
+   return { items, bytesRead: pos - offset };
+}

package/src/shared/wasm-codec/typings/add-section-input.model.ts

@@ -0,0 +1,45 @@
+/**
+ * Parameters for adding a new section to the knowledge base.
+ *
+ * Maps to the Rust `AddSectionParams` struct encoded for the
+ * `worker_add_section` WASM export.
+ */
+export interface AddSectionInput {
+   /** Semantic content category. */
+   sectionType: 'text' | 'code' | 'image';
+   /** MIME type; required for `code` and `image` section types. */
+   mimeType?: string;
+   /** Raw section content. */
+   content: string;
+   /** Optional section heading. */
+   title?: string | null;
+   /** Optional description summary. */
+   description?: string | null;
+   /** Optional document identifier to attach the section to. */
+   docid?: string | null;
+   /**
+    * Application-level type name for the section (e.g. `'skill'`,
+    * `'fact'`). `null` means no custom type.
+    */
+   typeName?: string | null;
+   /**
+    * Absolute path of the source file being learned. `undefined`
+    * means stdin input or programmatic API call.
+    */
+   sourcePath?: string;
+   /**
+    * ISO 8601 modified time of the source file. `undefined` means
+    * no source file exists.
+    */
+   sourceMtime?: string;
+   /**
+    * User-supplied tags for scoping and filtering. Defaults to
+    * an empty list when not provided.
+    */
+   tags?: string[];
+   /**
+    * When `true`, supersede any existing section with the same
+    * source key. Defaults to `false`.
+    */
+   replace?: boolean;
+}

package/src/shared/wasm-codec/typings/add-section-result.model.ts

@@ -0,0 +1,28 @@
+import type { NearDuplicate } from './near-duplicate.model.ts';
+
+/**
+ * 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[];
+}

package/src/shared/wasm-codec/typings/document-manifest.model.ts

@@ -0,0 +1,20 @@
+import type { DocumentSection } from './document-section.model.ts';
+
+/**
+ * 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[];
+}

package/src/shared/wasm-codec/typings/document-section.model.ts

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

package/src/shared/wasm-codec/typings/item-decoder.type.ts

@@ -0,0 +1,10 @@
+import type { DecodeResult } from '../functions/decode-string.function.ts';
+
+/**
+ * A function that decodes one item from a binary buffer at the
+ * given byte offset, returning the decoded value and bytes consumed.
+ */
+export type ItemDecoder<T> = (
+   bytes: Uint8Array,
+   offset: number,
+) => DecodeResult<T>;

package/src/shared/wasm-codec/typings/near-duplicate.model.ts

@@ -0,0 +1,16 @@
+/**
+ * A near-duplicate section identified during add-section indexing.
+ */
+export interface NearDuplicate {
+   /** Knowledge-base identifier of the near-duplicate section. */
+   readonly kbid: string;
+   /** Similarity score (0.0–1.0). */
+   readonly similarity: number;
+   /**
+    * Detection method that produced this match.
+    *
+    * Optional for backward compatibility with WASM-decoded results
+    * that do not carry method information.
+    */
+   readonly method?: 'jaccard' | 'cosine';
+}

package/src/shared/wasm-codec/typings/paged-search-result.model.ts

@@ -0,0 +1,22 @@
+import type { SectionMatch } from './section-match.model.ts';
+
+/**
+ * Paginated search response envelope returned by the WASM engine.
+ */
+export interface PagedSearchResult {
+   /** Matching sections for the current page. */
+   items: SectionMatch[];
+   /** Total number of matches across all pages. */
+   total: number;
+   /** Number of results skipped (pagination offset). */
+   offset: number;
+   /** Maximum results per page. */
+   limit: number;
+   /** Whether more results exist beyond this page. */
+   has_more: boolean;
+   /**
+    * Whether the engine fell back to relaxed (OR-mode) search
+    * after strict (AND-mode) returned no results.
+    */
+   relaxed: boolean;
+}

package/src/shared/wasm-codec/typings/section-match.model.ts

@@ -0,0 +1,31 @@
+/**
+ * A single ranked result item from a paged search response.
+ */
+export interface SectionMatch {
+   /** Knowledge-base identifier for the matched section. */
+   kbid: string;
+   /** Section heading, or `null` when untitled. */
+   heading: string | null;
+   /** MIME type of the section content. */
+   type: string;
+   /** Document IDs this section belongs to. */
+   docids: string[];
+   /** Relevance score from the ranking engine. */
+   score: number;
+   /**
+    * Confidence modifier (0.0–1.0) applied after relaxed search.
+    * Always 1.0 for strict-mode results.
+    */
+   confidence: number;
+   /** KWIC snippet (~150 chars around the best match). */
+   snippet: string;
+   /** Query terms that matched within this section. */
+   matched_terms: string[];
+   /**
+    * Document fields that contained at least one matched term
+    * (e.g. `'title'`, `'body'`).
+    */
+   matched_fields: string[];
+   /** ISO 8601 creation timestamp of the section. */
+   created_at: string;
+}

package/src/shared/wasm-codec/typings/section-record-trailing.model.ts

@@ -0,0 +1,38 @@
+/**
+ * Trailing backward-compatible fields of a section record.
+ *
+ * These fields were added after the initial wire format. When
+ * decoding legacy binary output that stops before these fields,
+ * each defaults to `null` or `[]`.
+ */
+export interface SectionRecordTrailing {
+   /**
+    * Stable logical identity derived from source path and heading.
+    * `null` for stdin input or sections without a source path.
+    */
+   sourceKey: string | null;
+   /**
+    * Absolute path of the source file that was learned.
+    * `null` for stdin input or programmatic API calls.
+    */
+   sourcePath: string | null;
+   /**
+    * ISO 8601 modified time of the source file at learn time.
+    * `null` when no source file exists.
+    */
+   sourceMtime: string | null;
+   /**
+    * ISO 8601 timestamp of the last supersession.
+    * `null` on first creation.
+    */
+   updatedAt: string | null;
+   /** User-supplied tags for scoping and filtering. */
+   tags: string[];
+   /**
+    * The kbid of the section this one replaced via supersession.
+    * `null` on first creation or non-superseding additions.
+    */
+   supersedes: string | null;
+   /** Number of bytes consumed from the buffer. */
+   bytesRead: number;
+}

package/src/shared/wasm-codec/typings/section-record.model.ts

@@ -0,0 +1,66 @@
+/**
+ * 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;
+   /**
+    * Stable logical identity derived from source path and heading.
+    * `null` for stdin input or sections without a source path.
+    */
+   sourceKey: string | null;
+   /**
+    * Absolute path of the source file that was learned.
+    * `null` for stdin input or programmatic API calls.
+    */
+   sourcePath: string | null;
+   /**
+    * ISO 8601 modified time of the source file at learn time.
+    * `null` when no source file exists.
+    */
+   sourceMtime: string | null;
+   /**
+    * ISO 8601 timestamp of the last supersession.
+    * `null` on first creation.
+    */
+   updatedAt: string | null;
+   /** User-supplied tags for scoping and filtering. */
+   tags: string[];
+   /**
+    * The kbid of the section this one replaced via supersession.
+    * `null` on first creation or non-superseding additions.
+    */
+   supersedes: string | null;
+}

package/src/shared/wasm-codec/typings/section-type-result.model.ts

@@ -0,0 +1,12 @@
+/** Result of decoding a section type discriminant from binary output. */
+export interface SectionTypeResult {
+   /** Semantic section category: `'text'`, `'code'`, or `'image'`. */
+   sectionType: string;
+   /**
+    * MIME type string, present only for `'code'` and `'image'`
+    * types.
+    */
+   mimeType?: string;
+   /** Number of bytes consumed from the buffer. */
+   bytesRead: number;
+}

package/src/shared/worker-client/functions/handle-ipc-data.function.ts

@@ -0,0 +1,49 @@
+import type { PendingCall } from '../typings/pending-call.interface.ts';
+import type { JsonRpcResponse } from '../typings/json-rpc-response.interface.ts';
+
+/**
+ * Processes an incoming data chunk from the IPC socket.
+ *
+ * Appends the chunk to `buffer`, splits on newline boundaries,
+ * parses complete JSON-RPC response lines, and resolves or rejects
+ * the matching pending call. Returns the updated buffer with any
+ * incomplete trailing line retained.
+ *
+ * @param data - raw string chunk received from the socket
+ * @param buffer - partial line buffer from the previous call
+ * @param pending - map of outstanding request IDs to their
+ *   resolve/reject pairs; mutated by this function
+ * @returns the updated buffer (incomplete trailing line, if any)
+ */
+export function handleIpcData(
+   data: string,
+   buffer: string,
+   pending: Map<number, PendingCall>,
+): string {
+   const combined = buffer + data;
+   const lines = combined.split('\n');
+   const nextBuffer = lines.pop() ?? '';
+
+   for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+         const response = JSON.parse(line) as JsonRpcResponse;
+         const call = pending.get(response.id);
+         if (call !== undefined) {
+            pending.delete(response.id);
+            if (response.error !== undefined) {
+               const err = new Error(response.error.message);
+               (err as unknown as Record<string, unknown>)['code'] =
+                  response.error.code;
+               call.reject(err);
+            } else {
+               call.resolve(response.result);
+            }
+         }
+      } catch {
+         // Ignore unparseable lines
+      }
+   }
+
+   return nextBuffer;
+}

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/typings/add-section-result.model.ts

@@ -6,6 +6,8 @@ export interface NearDuplicateEntry {
    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. */

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-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';
+   }
+}