@dikolab/kbdb 0.3.1 → 0.4.0

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

@@ -1,31 +0,0 @@
-/**
- * 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

@@ -1,38 +0,0 @@
-/**
- * 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

@@ -1,66 +0,0 @@
-/**
- * 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

@@ -1,12 +0,0 @@
-/** 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/classes/worker-client.class.ts

@@ -1,466 +0,0 @@
-import { connect } from 'node:net';
-import type { Socket } from 'node:net';
-import type { SearchParams } from '../typings/search-params.model.ts';
-import type { PagedSearchResult } 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';
-import type {
-   RecallParams,
-   RecallResult,
-} from '../typings/recall-result.model.ts';
-import type { ExportResult } from '../typings/export-result.model.ts';
-
-/** Pending JSON-RPC call awaiting a response from the daemon. */
-interface PendingCall {
-   resolve: (v: unknown) => void;
-   reject: (e: Error) => void;
-}
-
-/** Shape of a JSON-RPC 2.0 error object from the daemon. */
-interface JsonRpcError {
-   readonly code: number;
-   readonly message: string;
-}
-
-/** Shape of a JSON-RPC 2.0 response from the daemon. */
-interface JsonRpcResponse {
-   readonly id: number;
-   readonly result?: unknown;
-   readonly error?: JsonRpcError;
-}
-
-/**
- * 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 class WorkerClient {
-   /** Underlying socket; `null` when not connected. */
-   private socket: Socket | null = null;
-
-   /** Monotonically increasing request ID counter. */
-   private nextId = 1;
-
-   /** Map of outstanding request IDs to their resolve/reject pairs. */
-   private readonly pending = new Map<number, PendingCall>();
-
-   /** 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(
-      private readonly socketPath: string,
-      private readonly contextId: string,
-   ) {}
-
-   /**
-    * Establishes the IPC connection to the worker daemon.
-    *
-    * @throws {Error} if the connection cannot be established
-    */
-   async connect(): Promise<void> {
-      return new Promise<void>((resolve, reject) => {
-         this.socket = connect(this.socketPath, () => {
-            resolve();
-         });
-         this.socket.on('error', (err: Error) => {
-            reject(err);
-         });
-         this.socket.on('data', (chunk: Buffer) => {
-            this.handleData(chunk.toString());
-         });
-      });
-   }
-
-   /** Destroys the IPC socket and clears the connection state. */
-   disconnect(): void {
-      if (this.socket) {
-         this.socket.destroy();
-         this.socket = null;
-      }
-   }
-
-   /**
-    * Searches the knowledge base.
-    *
-    * @param params - query parameters including the search string
-    * @returns paginated search results with metadata
-    */
-   async search(params: SearchParams): Promise<PagedSearchResult> {
-      return this.call('search', params) as Promise<PagedSearchResult>;
-   }
-
-   /**
-    * 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 `RecallResult` when `kbid` is provided without
-    *   `kbids`, or a `RecallResult[]` when `kbids` is provided
-    */
-   async recall(
-      params: RecallParams,
-   ): Promise<RecallResult | RecallResult[]> {
-      return this.call('recall', params) as Promise<
-         RecallResult | RecallResult[]
-      >;
-   }
-
-   /**
-    * 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
-    */
-   async addSection(
-      params: AddSectionParams,
-   ): Promise<AddSectionResult> {
-      return this.call(
-         'addSection',
-         params,
-      ) as 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
-    */
-   async updateSection(
-      kbid: string,
-      params: AddSectionParams,
-   ): Promise<string> {
-      return this.call('updateSection', {
-         kbid,
-         ...params,
-      }) as 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
-    */
-   async removeSection(kbid: string): Promise<RemoveSectionResult> {
-      return this.call('removeSection', {
-         kbid,
-      }) as 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
-    */
-   async readSections(kbids: string[]): Promise<Section[]> {
-      return this.call('readSections', {
-         kbids,
-      }) as 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
-    */
-   async groupSections(
-      title: string,
-      kbids: string[],
-      docType?: string,
-   ): Promise<string> {
-      const result = (await this.call('groupSections', {
-         title,
-         kbids,
-         docType: docType ?? '',
-      })) as { docid: string } | string;
-      return typeof result === 'string' ? result : result.docid;
-   }
-
-   /**
-    * 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
-    */
-   async removeGrouping(docid: string): Promise<void> {
-      await this.call('removeGrouping', { docid });
-   }
-
-   /**
-    * 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
-    */
-   async retrieveDocument(docid: string): Promise<unknown> {
-      return this.call('retrieveDocument', { docid });
-   }
-
-   /**
-    * 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
-    */
-   async content(ids: string[]): Promise<ContentResult> {
-      return this.call('content', { ids }) as 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
-    */
-   async integrityCheck(): Promise<IntegrityCheckResult> {
-      return this.call(
-         'integrityCheck',
-         {},
-      ) as Promise<IntegrityCheckResult>;
-   }
-
-   /**
-    * Removes unreferenced sections from the database.
-    *
-    * @returns a report of sections removed and bytes freed
-    */
-   async gc(): Promise<GcResult> {
-      return this.call('gc', {}) as 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
-    */
-   async rebuildIndexes(): Promise<RebuildResult> {
-      return this.call('rebuildIndexes', {}) as Promise<RebuildResult>;
-   }
-
-   /**
-    * Invalidates the in-memory cache entry for a single section.
-    *
-    * @param kbid - identifier of the section to evict from cache
-    */
-   async invalidate(kbid: string): Promise<void> {
-      await this.call('invalidate', { kbid });
-   }
-
-   /** Clears all entries from the daemon's in-memory cache. */
-   async invalidateAll(): Promise<void> {
-      await this.call('invalidateAll', {});
-   }
-
-   /**
-    * Retrieves diagnostic status information from the daemon.
-    *
-    * @returns current initialization state and cache statistics
-    */
-   async status(): Promise<StatusResult> {
-      return this.call('status', {}) as 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
-    */
-   async dbStatus(): Promise<StatusResult> {
-      return this.call('dbStatus', {}) as 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
-    */
-   async initDirectory(targetPath: string): Promise<void> {
-      await this.call('initDirectory', { targetPath });
-   }
-
-   /**
-    * 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
-    */
-   async migrateDatabase(targetPath: string): Promise<MigrateResult> {
-      return this.call('migrateDatabase', {
-         targetPath,
-      }) as 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
-    */
-   async checkVersion(targetPath: string): Promise<VersionStatus> {
-      return this.call('checkVersion', {
-         targetPath,
-      }) as 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
-    */
-   async listByType(sectionType: string): Promise<SectionRecord[]> {
-      return this.call('listByType', {
-         sectionType,
-      }) as 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
-    */
-   async listDocumentsByType(
-      docType: string,
-   ): Promise<DocumentManifest[]> {
-      return this.call('listDocumentsByType', {
-         docType,
-      }) as Promise<DocumentManifest[]>;
-   }
-
-   /**
-    * Exports the database to a target directory on disk.
-    *
-    * Copies section files, document manifests, and `catalog.toml`
-    * to `params.path`. Index files are not exported because they
-    * are derivable from the section and document data.
-    *
-    * @param params - optional export parameters
-    * @param params.path - target directory path; defaults to
-    *   `./kbdb-export/` when not provided
-    * @returns export report with the resolved path and file counts
-    */
-   async export(params?: { path?: string }): Promise<ExportResult> {
-      return this.call('export', {
-         targetPath: params?.path || undefined,
-      }) as Promise<ExportResult>;
-   }
-
-   /**
-    * 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 async call(
-      method: string,
-      params: unknown,
-   ): Promise<unknown> {
-      const socket = this.socket;
-      if (!socket) {
-         throw new Error('not connected');
-      }
-
-      const id = this.nextId++;
-      const request = {
-         jsonrpc: '2.0',
-         id,
-         method,
-         params: { ctx: this.contextId, ...(params as object) },
-      };
-
-      return new Promise<unknown>((resolve, reject) => {
-         this.pending.set(id, { resolve, reject });
-         socket.write(JSON.stringify(request) + '\n');
-      });
-   }
-
-   /**
-    * 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(data: string): void {
-      this.buffer += data;
-      const lines = this.buffer.split('\n');
-      this.buffer = lines.pop() ?? '';
-
-      for (const line of lines) {
-         if (!line.trim()) continue;
-         try {
-            const response = JSON.parse(line) as JsonRpcResponse;
-            const pending = this.pending.get(response.id);
-            if (pending) {
-               this.pending.delete(response.id);
-               if (response.error) {
-                  const err = new Error(response.error.message);
-                  (err as unknown as Record<string, unknown>).code =
-                     response.error.code;
-                  pending.reject(err);
-               } else {
-                  pending.resolve(response.result);
-               }
-            }
-         } catch {
-            // Ignore unparseable lines
-         }
-      }
-   }
-}

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

@@ -1,18 +0,0 @@
-import { computeSha256 } from '../../hash/functions/compute-sha256.ts';
-
-/**
- * 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 async function computeContextId(
-   absolutePath: string,
-): Promise<string> {
-   const hash = await computeSha256(absolutePath);
-   return hash.slice(0, 16);
-}