@dikolab/kbdb 0.2.1 → 0.3.0

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

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

@@ -2,22 +2,57 @@ import { decodeString } from './decode-string.function.ts';
 import { decodeU32 } from './decode-u32.function.ts';
 import { decodeF32 } from './decode-f32.function.ts';
 
+/**
+ * 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;
 }
 
+/**
+ * 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;
 }
 
 function decodeOptionString(
@@ -32,6 +67,29 @@ function decodeOptionString(
    return { value: str.value, bytesRead: 1 + str.bytesRead };
 }
 
+/**
+ * Decodes the binary `PagedSearchResult` returned by the
+ * `worker_get_result` WASM export after a `worker_search` call.
+ *
+ * Wire format (little-endian):
+ * - `total`: `u32`
+ * - `offset`: `u32`
+ * - `limit`: `u32`
+ * - `has_more`: `u8` (0/1)
+ * - `relaxed`: `u8` (0/1)
+ * - `item_count`: `u32`
+ * - Per item:
+ *   - `kbid`: `String`
+ *   - `heading`: `Option<String>`
+ *   - `section_type`: `String`
+ *   - `docids`: `u32` count + `String[]`
+ *   - `score`: `f32`
+ *   - `confidence`: `f32`
+ *   - `snippet`: `String`
+ *   - `matched_terms`: `u32` count + `String[]`
+ *   - `matched_fields`: `u32` count + `String[]`
+ *   - `created_at`: `String`
+ */
 export function decodePagedSearchResult(
    bytes: Uint8Array,
 ): PagedSearchResult {
@@ -49,6 +107,12 @@ export function decodePagedSearchResult(
    const hasMore = bytes[offset] === 1;
    offset += 1;
 
+   // relaxed flag added after has_more
+   const relaxed = offset < bytes.length && bytes[offset] === 1;
+   if (offset < bytes.length) {
+      offset += 1;
+   }
+
    const itemCount = decodeU32(bytes, offset);
    offset += itemCount.bytesRead;
 
@@ -75,6 +139,10 @@ export function decodePagedSearchResult(
       const score = decodeF32(bytes, offset);
       offset += score.bytesRead;
 
+      // confidence added after score
+      const confidence = decodeF32(bytes, offset);
+      offset += confidence.bytesRead;
+
       const snippet = decodeString(bytes, offset);
       offset += snippet.bytesRead;
 
@@ -87,14 +155,31 @@ export function decodePagedSearchResult(
          matched_terms.push(term.value);
       }
 
+      // matched_fields added after matched_terms
+      const fieldCount = decodeU32(bytes, offset);
+      offset += fieldCount.bytesRead;
+      const matched_fields: string[] = [];
+      for (let j = 0; j < fieldCount.value; j++) {
+         const field = decodeString(bytes, offset);
+         offset += field.bytesRead;
+         matched_fields.push(field.value);
+      }
+
+      // created_at added after matched_fields
+      const createdAt = decodeString(bytes, offset);
+      offset += createdAt.bytesRead;
+
       items.push({
          kbid: kbid.value,
          heading: heading.value,
          type: sectionType.value,
          docids,
          score: score.value,
+         confidence: confidence.value,
          snippet: snippet.value,
          matched_terms,
+         matched_fields,
+         created_at: createdAt.value,
       });
    }
 
@@ -104,5 +189,6 @@ export function decodePagedSearchResult(
       offset: resultOffset.value,
       limit: limit.value,
       has_more: hasMore,
+      relaxed,
    };
 }

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

@@ -40,6 +40,33 @@ export interface SectionRecord {
    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;
 }
 
 function decodeOptionString(
@@ -82,6 +109,12 @@ function decodeSectionType(
  * Each record is decoded in field order as produced by the Rust
  * `SectionRecord::encode` implementation.
  *
+ * Trailing fields (`sourceKey`, `sourcePath`, `sourceMtime`,
+ * `updatedAt`, `tags`, `supersedes`) were added after the initial
+ * format. When decoding legacy bytes that stop after `typeName`,
+ * those fields default to `null` / `[]`. This matches the Rust
+ * decoder's backward-compatibility guards.
+ *
  * @param bytes - raw bytes returned by a WASM section-list export
  * @returns decoded array of section records, empty when count is zero
  */
@@ -136,6 +169,54 @@ export function decodeSectionRecords(
       const typeName = decodeString(bytes, offset);
       offset += typeName.bytesRead;
 
+      // New trailing fields -- use length guards for backward compat.
+      let sourceKey: string | null = null;
+      if (offset < bytes.length) {
+         const v = decodeOptionString(bytes, offset);
+         offset += v.bytesRead;
+         sourceKey = v.value;
+      }
+
+      let sourcePath: string | null = null;
+      if (offset < bytes.length) {
+         const v = decodeOptionString(bytes, offset);
+         offset += v.bytesRead;
+         sourcePath = v.value;
+      }
+
+      let sourceMtime: string | null = null;
+      if (offset < bytes.length) {
+         const v = decodeOptionString(bytes, offset);
+         offset += v.bytesRead;
+         sourceMtime = v.value;
+      }
+
+      let updatedAt: string | null = null;
+      if (offset < bytes.length) {
+         const v = decodeOptionString(bytes, offset);
+         offset += v.bytesRead;
+         updatedAt = v.value;
+      }
+
+      let tags: string[] = [];
+      if (offset < bytes.length) {
+         const tagCount = decodeU32(bytes, offset);
+         offset += tagCount.bytesRead;
+         tags = [];
+         for (let j = 0; j < tagCount.value; j++) {
+            const tag = decodeString(bytes, offset);
+            offset += tag.bytesRead;
+            tags.push(tag.value);
+         }
+      }
+
+      let supersedes: string | null = null;
+      if (offset < bytes.length) {
+         const v = decodeOptionString(bytes, offset);
+         offset += v.bytesRead;
+         supersedes = v.value;
+      }
+
       const record: SectionRecord = {
          kbid: kbid.value,
          docid: docid.value,
@@ -151,6 +232,12 @@ export function decodeSectionRecords(
          bodyTokenCount: bodyTokenCount.value,
          codeTokenCount: codeTokenCount.value,
          typeName: typeName.value,
+         sourceKey,
+         sourcePath,
+         sourceMtime,
+         updatedAt,
+         tags,
+         supersedes,
       };
       if (st.mimeType !== undefined) {
          record.mimeType = st.mimeType;

package/src/shared/wasm-codec/functions/encode-add-section-params.function.ts

@@ -1,20 +1,83 @@
 import { encodeSectionType } from './encode-section-type.function.ts';
 import { encodeString } from './encode-string.function.ts';
 import { encodeOptionString } from './encode-option-string.function.ts';
+import { encodeU32 } from './encode-u32.function.ts';
 
+/**
+ * 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;
 }
 
+/**
+ * Encodes `AddSectionInput` as the binary format expected by the
+ * `worker_add_section` WASM export.
+ *
+ * Wire format (little-endian):
+ * - `SectionType` tag byte (+ optional MIME string for code/image)
+ * - `content`: `u32` length + UTF-8 bytes
+ * - `title`: `u8` flag + optional `String`
+ * - `description`: `u8` flag + optional `String`
+ * - `docid`: `u8` flag + optional `String`
+ * - `typeName`: `u8` flag + optional `String`
+ * - `sourcePath`: `u8` flag + optional `String`
+ * - `sourceMtime`: `u8` flag + optional `String`
+ * - `tags`: `u32` count + each `String`
+ * - `replace`: `u8` (0 or 1)
+ */
 export function encodeAddSectionParams(
    params: AddSectionInput,
 ): Uint8Array {
+   const tags = params.tags ?? [];
+   const tagParts: Uint8Array[] = [];
+   for (const tag of tags) {
+      tagParts.push(encodeString(tag));
+   }
+   const tagsCountBytes = encodeU32(tags.length);
+   const replaceByte = new Uint8Array([
+      params.replace === true ? 1 : 0,
+   ]);
+
    const parts = [
       encodeSectionType(params.sectionType, params.mimeType),
       encodeString(params.content),
@@ -22,6 +85,11 @@ export function encodeAddSectionParams(
       encodeOptionString(params.description),
       encodeOptionString(params.docid),
       encodeOptionString(params.typeName),
+      encodeOptionString(params.sourcePath),
+      encodeOptionString(params.sourceMtime),
+      tagsCountBytes,
+      ...tagParts,
+      replaceByte,
    ];
    const totalLen = parts.reduce((sum, p) => sum + p.length, 0);
    const result = new Uint8Array(totalLen);

package/src/shared/wasm-codec/index.ts

@@ -23,9 +23,14 @@ export { decodeKeyValueText } from './functions/decode-key-value-text.function.t
 export { decodeRemoveFlag } from './functions/decode-remove-flag.function.ts';
 export { encodeRecallParams } from './functions/encode-recall-params.function.ts';
 export { decodeRecallResult } from './functions/decode-recall-result.function.ts';
+export { decodeAddSectionResult } from './functions/decode-add-section-result.function.ts';
 
 export type { DecodeResult } from './functions/decode-string.function.ts';
 export type { AddSectionInput } from './functions/encode-add-section-params.function.ts';
+export type {
+   AddSectionResult,
+   NearDuplicate,
+} from './functions/decode-add-section-result.function.ts';
 export type {
    SectionMatch,
    PagedSearchResult,

package/src/shared/worker-client/classes/worker-client.class.ts

@@ -21,6 +21,7 @@ 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 {
@@ -381,6 +382,24 @@ export class WorkerClient {
       }) 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.
     *

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,37 @@
+/**
+ * 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;
+}
+
 /** 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/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;
 }