@dikolab/kbdb 0.2.2 → 0.3.1

package/src/shared/wasm-codec/functions/decode-one-recall-result.function.ts

@@ -0,0 +1,86 @@
+import { decodeString } from './decode-string.function.ts';
+import { decodeOptionString } from './decode-option-string.function.ts';
+import { decodeWasmList } from './decode-wasm-list.function.ts';
+import { decodeRecallReference } from './decode-recall-reference.function.ts';
+import { decodeRecallSibling } from './decode-recall-sibling.function.ts';
+import { decodeRecallDocument } from './decode-recall-document.function.ts';
+import type { DecodeResult } from './decode-string.function.ts';
+import type {
+   RecallResult,
+   RecallDocument,
+   RecallSibling,
+   RecallReference,
+} from '../../worker-client/typings/recall-result.model.ts';
+
+/**
+ * Decodes a single `RecallResult` record from WASM binary output.
+ *
+ * Wire format: kbid, heading, section_type, content, docid list,
+ * document list, back_references list, siblings list,
+ * references list.
+ *
+ * @param bytes - raw binary buffer
+ * @param startOffset - byte position of the record start
+ * @returns decoded result and number of bytes consumed
+ */
+export function decodeOneRecallResult(
+   bytes: Uint8Array,
+   startOffset: number,
+): DecodeResult<RecallResult> {
+   let pos = startOffset;
+
+   const kbid = decodeString(bytes, pos);
+   pos += kbid.bytesRead;
+   const heading = decodeOptionString(bytes, pos);
+   pos += heading.bytesRead;
+   const sectionType = decodeString(bytes, pos);
+   pos += sectionType.bytesRead;
+   const content = decodeString(bytes, pos);
+   pos += content.bytesRead;
+
+   const docids = decodeWasmList(bytes, pos, decodeString);
+   pos += docids.bytesRead;
+
+   const documents = decodeWasmList<RecallDocument>(
+      bytes,
+      pos,
+      decodeRecallDocument,
+   );
+   pos += documents.bytesRead;
+
+   const back_references = decodeWasmList<RecallReference>(
+      bytes,
+      pos,
+      decodeRecallReference,
+   );
+   pos += back_references.bytesRead;
+
+   const siblings = decodeWasmList<RecallSibling>(
+      bytes,
+      pos,
+      decodeRecallSibling,
+   );
+   pos += siblings.bytesRead;
+
+   const references = decodeWasmList<RecallReference>(
+      bytes,
+      pos,
+      decodeRecallReference,
+   );
+   pos += references.bytesRead;
+
+   return {
+      value: {
+         kbid: kbid.value,
+         heading: heading.value,
+         type: sectionType.value,
+         content: content.value,
+         docids: docids.items,
+         documents: documents.items,
+         back_references: back_references.items,
+         siblings: siblings.items,
+         references: references.items,
+      },
+      bytesRead: pos - startOffset,
+   };
+}

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

@@ -0,0 +1,24 @@
+import type { DecodeResult } from './decode-string.function.ts';
+import { decodeString } from './decode-string.function.ts';
+
+/**
+ * Decodes an `Option<String>` from WASM binary output.
+ *
+ * Wire format: `u8` tag byte (`0x00` = `None`, any other value =
+ * `Some`) followed by a length-prefixed UTF-8 string when present.
+ *
+ * @param bytes - raw binary buffer
+ * @param offset - byte position of the tag byte
+ * @returns decoded nullable string and number of bytes consumed
+ */
+export function decodeOptionString(
+   bytes: Uint8Array,
+   offset: number,
+): DecodeResult<string | null> {
+   const tag = bytes[offset];
+   if (tag === 0x00) {
+      return { value: null, bytesRead: 1 };
+   }
+   const str = decodeString(bytes, offset + 1);
+   return { value: str.value, bytesRead: 1 + str.bytesRead };
+}

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

@@ -0,0 +1,59 @@
+import { decodeString } from './decode-string.function.ts';
+import { decodeU32 } from './decode-u32.function.ts';
+import { decodeOptionString } from './decode-option-string.function.ts';
+import type { DecodeResult } from './decode-string.function.ts';
+import type { RecallDocument } from '../../worker-client/typings/recall-result.model.ts';
+
+/**
+ * Decodes a single `RecallDocument` record from WASM binary output.
+ *
+ * Wire format: docid (String), title (String), section_count (u32),
+ * then each section as kbid (String), heading (Option<String>),
+ * section_type (String).
+ *
+ * @param bytes - raw binary buffer
+ * @param offset - byte position of the record start
+ * @returns decoded document and number of bytes consumed
+ */
+export function decodeRecallDocument(
+   bytes: Uint8Array,
+   offset: number,
+): DecodeResult<RecallDocument> {
+   let pos = offset;
+
+   const docid = decodeString(bytes, pos);
+   pos += docid.bytesRead;
+
+   const title = decodeString(bytes, pos);
+   pos += title.bytesRead;
+
+   const sectionCount = decodeU32(bytes, pos);
+   pos += sectionCount.bytesRead;
+
+   const sections: RecallDocument['sections'][number][] = [];
+   for (let i = 0; i < sectionCount.value; i++) {
+      const secKbid = decodeString(bytes, pos);
+      pos += secKbid.bytesRead;
+
+      const secHeading = decodeOptionString(bytes, pos);
+      pos += secHeading.bytesRead;
+
+      const secType = decodeString(bytes, pos);
+      pos += secType.bytesRead;
+
+      sections.push({
+         kbid: secKbid.value,
+         heading: secHeading.value,
+         type: secType.value,
+      });
+   }
+
+   return {
+      value: {
+         docid: docid.value,
+         title: title.value,
+         sections,
+      },
+      bytesRead: pos - offset,
+   };
+}

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

@@ -0,0 +1,52 @@
+import { decodeString } from './decode-string.function.ts';
+import { decodeOptionString } from './decode-option-string.function.ts';
+import type { DecodeResult } from './decode-string.function.ts';
+import type { RecallReference } from '../../worker-client/typings/recall-result.model.ts';
+
+/**
+ * Decodes a single `RecallReference` record from WASM binary output.
+ *
+ * Wire format: kbid (String), heading (Option<String>),
+ * section_type (String), marker_type (String),
+ * context_snippet (String), direction (String).
+ *
+ * @param bytes - raw binary buffer
+ * @param offset - byte position of the record start
+ * @returns decoded reference and number of bytes consumed
+ */
+export function decodeRecallReference(
+   bytes: Uint8Array,
+   offset: number,
+): DecodeResult<RecallReference> {
+   let pos = offset;
+
+   const kbid = decodeString(bytes, pos);
+   pos += kbid.bytesRead;
+
+   const heading = decodeOptionString(bytes, pos);
+   pos += heading.bytesRead;
+
+   const sectionType = decodeString(bytes, pos);
+   pos += sectionType.bytesRead;
+
+   const markerType = decodeString(bytes, pos);
+   pos += markerType.bytesRead;
+
+   const contextSnippet = decodeString(bytes, pos);
+   pos += contextSnippet.bytesRead;
+
+   const direction = decodeString(bytes, pos);
+   pos += direction.bytesRead;
+
+   return {
+      value: {
+         kbid: kbid.value,
+         heading: heading.value,
+         type: sectionType.value,
+         marker_type: markerType.value,
+         context_snippet: contextSnippet.value,
+         direction: direction.value as 'forward' | 'back',
+      },
+      bytesRead: pos - offset,
+   };
+}

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

@@ -0,0 +1,43 @@
+import { decodeString } from './decode-string.function.ts';
+import { decodeOptionString } from './decode-option-string.function.ts';
+import type { DecodeResult } from './decode-string.function.ts';
+import type { RecallSibling } from '../../worker-client/typings/recall-result.model.ts';
+
+/**
+ * Decodes a single `RecallSibling` record from WASM binary output.
+ *
+ * Wire format: kbid (String), heading (Option<String>),
+ * section_type (String), content (String).
+ *
+ * @param bytes - raw binary buffer
+ * @param offset - byte position of the record start
+ * @returns decoded sibling and number of bytes consumed
+ */
+export function decodeRecallSibling(
+   bytes: Uint8Array,
+   offset: number,
+): DecodeResult<RecallSibling> {
+   let pos = offset;
+
+   const kbid = decodeString(bytes, pos);
+   pos += kbid.bytesRead;
+
+   const heading = decodeOptionString(bytes, pos);
+   pos += heading.bytesRead;
+
+   const sectionType = decodeString(bytes, pos);
+   pos += sectionType.bytesRead;
+
+   const content = decodeString(bytes, pos);
+   pos += content.bytesRead;
+
+   return {
+      value: {
+         kbid: kbid.value,
+         heading: heading.value,
+         type: sectionType.value,
+         content: content.value,
+      },
+      bytesRead: pos - offset,
+   };
+}

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-match.function.ts

@@ -0,0 +1,80 @@
+import { decodeString } from './decode-string.function.ts';
+import { decodeU32 } from './decode-u32.function.ts';
+import { decodeF32 } from './decode-f32.function.ts';
+import { decodeOptionString } from './decode-option-string.function.ts';
+import type { DecodeResult } from './decode-string.function.ts';
+import type { SectionMatch } from '../typings/section-match.model.ts';
+
+/**
+ * Decodes a single `SectionMatch` item from WASM binary output.
+ *
+ * Wire format per item: kbid, heading (Option<String>),
+ * section_type, docids (u32 count + String[]), score (f32),
+ * confidence (f32), snippet, matched_terms (u32 + String[]),
+ * matched_fields (u32 + String[]), created_at.
+ *
+ * @param bytes - raw binary buffer
+ * @param startOffset - byte position of the item start
+ * @returns decoded match and number of bytes consumed
+ */
+export function decodeSectionMatch(
+   bytes: Uint8Array,
+   startOffset: number,
+): DecodeResult<SectionMatch> {
+   let pos = startOffset;
+
+   const kbid = decodeString(bytes, pos);
+   pos += kbid.bytesRead;
+   const heading = decodeOptionString(bytes, pos);
+   pos += heading.bytesRead;
+   const sectionType = decodeString(bytes, pos);
+   pos += sectionType.bytesRead;
+   const docidCount = decodeU32(bytes, pos);
+   pos += docidCount.bytesRead;
+   const docids: string[] = [];
+   for (let j = 0; j < docidCount.value; j++) {
+      const docid = decodeString(bytes, pos);
+      pos += docid.bytesRead;
+      docids.push(docid.value);
+   }
+   const score = decodeF32(bytes, pos);
+   pos += score.bytesRead;
+   const confidence = decodeF32(bytes, pos);
+   pos += confidence.bytesRead;
+   const snippet = decodeString(bytes, pos);
+   pos += snippet.bytesRead;
+   const termCount = decodeU32(bytes, pos);
+   pos += termCount.bytesRead;
+   const matched_terms: string[] = [];
+   for (let j = 0; j < termCount.value; j++) {
+      const term = decodeString(bytes, pos);
+      pos += term.bytesRead;
+      matched_terms.push(term.value);
+   }
+   const fieldCount = decodeU32(bytes, pos);
+   pos += fieldCount.bytesRead;
+   const matched_fields: string[] = [];
+   for (let j = 0; j < fieldCount.value; j++) {
+      const field = decodeString(bytes, pos);
+      pos += field.bytesRead;
+      matched_fields.push(field.value);
+   }
+   const createdAt = decodeString(bytes, pos);
+   pos += createdAt.bytesRead;
+
+   return {
+      value: {
+         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,
+      },
+      bytesRead: pos - startOffset,
+   };
+}

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

@@ -0,0 +1,75 @@
+import { decodeString } from './decode-string.function.ts';
+import { decodeU32 } from './decode-u32.function.ts';
+import { decodeOptionString } from './decode-option-string.function.ts';
+import type { SectionRecordTrailing } from '../typings/section-record-trailing.model.ts';
+
+export type { SectionRecordTrailing };
+
+/**
+ * Decodes the trailing backward-compatible fields of a
+ * `SectionRecord` from WASM binary output.
+ *
+ * Fields present only in newer binary output; each is guarded by a
+ * length check. Missing fields default to `null` or `[]`.
+ *
+ * @param bytes - raw bytes from a WASM section-list export
+ * @param startOffset - byte position after the `typeName` field
+ * @returns decoded trailing fields and bytes consumed
+ */
+export function decodeSectionRecordTrailing(
+   bytes: Uint8Array,
+   startOffset: number,
+): SectionRecordTrailing {
+   let pos = startOffset;
+
+   let sourceKey: string | null = null;
+   if (pos < bytes.length) {
+      const v = decodeOptionString(bytes, pos);
+      pos += v.bytesRead;
+      sourceKey = v.value;
+   }
+   let sourcePath: string | null = null;
+   if (pos < bytes.length) {
+      const v = decodeOptionString(bytes, pos);
+      pos += v.bytesRead;
+      sourcePath = v.value;
+   }
+   let sourceMtime: string | null = null;
+   if (pos < bytes.length) {
+      const v = decodeOptionString(bytes, pos);
+      pos += v.bytesRead;
+      sourceMtime = v.value;
+   }
+   let updatedAt: string | null = null;
+   if (pos < bytes.length) {
+      const v = decodeOptionString(bytes, pos);
+      pos += v.bytesRead;
+      updatedAt = v.value;
+   }
+   const tags: string[] = [];
+   if (pos < bytes.length) {
+      const tagCount = decodeU32(bytes, pos);
+      pos += tagCount.bytesRead;
+      for (let j = 0; j < tagCount.value; j++) {
+         const tagStr = decodeString(bytes, pos);
+         pos += tagStr.bytesRead;
+         tags.push(tagStr.value);
+      }
+   }
+   let supersedes: string | null = null;
+   if (pos < bytes.length) {
+      const v = decodeOptionString(bytes, pos);
+      pos += v.bytesRead;
+      supersedes = v.value;
+   }
+
+   return {
+      sourceKey,
+      sourcePath,
+      sourceMtime,
+      updatedAt,
+      tags,
+      supersedes,
+      bytesRead: pos - startOffset,
+   };
+}

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

@@ -0,0 +1,85 @@
+import { decodeString } from './decode-string.function.ts';
+import { decodeU32 } from './decode-u32.function.ts';
+import { decodeU64 } from './decode-u64.function.ts';
+import { decodeOptionString } from './decode-option-string.function.ts';
+import { decodeSectionType } from './decode-section-type.function.ts';
+import { decodeSectionRecordTrailing } from './decode-section-record-trailing.function.ts';
+import type { DecodeResult } from './decode-string.function.ts';
+import type { SectionRecord } from '../typings/section-record.model.ts';
+
+/**
+ * Decodes a single `SectionRecord` from WASM binary output.
+ *
+ * Reads all section fields in the order produced by the Rust
+ * `SectionRecord::encode` implementation. Trailing fields added
+ * after `typeName` default to `null` / `[]` when absent.
+ *
+ * @param bytes - raw bytes returned by a WASM section-list export
+ * @param startOffset - byte position of the record start
+ * @returns decoded record and number of bytes consumed
+ */
+export function decodeSectionRecord(
+   bytes: Uint8Array,
+   startOffset: number,
+): DecodeResult<SectionRecord> {
+   let pos = startOffset;
+
+   const kbid = decodeString(bytes, pos);
+   pos += kbid.bytesRead;
+   const docid = decodeOptionString(bytes, pos);
+   pos += docid.bytesRead;
+   const st = decodeSectionType(bytes, pos);
+   pos += st.bytesRead;
+   const title = decodeOptionString(bytes, pos);
+   pos += title.bytesRead;
+   const description = decodeOptionString(bytes, pos);
+   pos += description.bytesRead;
+   const content = decodeString(bytes, pos);
+   pos += content.bytesRead;
+   const size = decodeU32(bytes, pos);
+   pos += size.bytesRead;
+   const createdAt = decodeU64(bytes, pos);
+   pos += createdAt.bytesRead;
+   const checksum = decodeString(bytes, pos);
+   pos += checksum.bytesRead;
+   const tokenCount = decodeU32(bytes, pos);
+   pos += tokenCount.bytesRead;
+   const headingTokenCount = decodeU32(bytes, pos);
+   pos += headingTokenCount.bytesRead;
+   const bodyTokenCount = decodeU32(bytes, pos);
+   pos += bodyTokenCount.bytesRead;
+   const codeTokenCount = decodeU32(bytes, pos);
+   pos += codeTokenCount.bytesRead;
+   const typeName = decodeString(bytes, pos);
+   pos += typeName.bytesRead;
+
+   const trailing = decodeSectionRecordTrailing(bytes, pos);
+   pos += trailing.bytesRead;
+
+   const record: SectionRecord = {
+      kbid: kbid.value,
+      docid: docid.value,
+      sectionType: st.sectionType,
+      title: title.value,
+      description: description.value,
+      content: content.value,
+      size: size.value,
+      createdAt: createdAt.value,
+      checksum: checksum.value,
+      tokenCount: tokenCount.value,
+      headingTokenCount: headingTokenCount.value,
+      bodyTokenCount: bodyTokenCount.value,
+      codeTokenCount: codeTokenCount.value,
+      typeName: typeName.value,
+      sourceKey: trailing.sourceKey,
+      sourcePath: trailing.sourcePath,
+      sourceMtime: trailing.sourceMtime,
+      updatedAt: trailing.updatedAt,
+      tags: trailing.tags,
+      supersedes: trailing.supersedes,
+   };
+   if (st.mimeType !== undefined) {
+      record.mimeType = st.mimeType;
+   }
+   return { value: record, bytesRead: pos - startOffset };
+}