@dikolab/kbdb 0.3.1 → 0.4.0

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

@@ -1,30 +0,0 @@
-import { decodeString } from './decode-string.function.ts';
-import type { SectionTypeResult } from '../typings/section-type-result.model.ts';
-
-export type { SectionTypeResult };
-
-/**
- * Decodes a section type discriminant from WASM binary output.
- *
- * Wire format: `u8` tag (`0x00` = text, `0x01` = code,
- * `0x02` = image), followed by a MIME string for code/image.
- *
- * @param bytes - raw binary buffer
- * @param offset - byte position of the tag byte
- * @returns section type, optional MIME type, and bytes consumed
- */
-export function decodeSectionType(
-   bytes: Uint8Array,
-   offset: number,
-): SectionTypeResult {
-   const tag = bytes[offset];
-   if (tag === 0x00) {
-      return { sectionType: 'text', bytesRead: 1 };
-   }
-   const mime = decodeString(bytes, offset + 1);
-   return {
-      sectionType: tag === 0x01 ? 'code' : 'image',
-      mimeType: mime.value,
-      bytesRead: 1 + mime.bytesRead,
-   };
-}

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

@@ -1,22 +0,0 @@
-const decoder = new TextDecoder();
-
-export interface DecodeResult<T> {
-   value: T;
-   bytesRead: number;
-}
-
-export function decodeString(
-   bytes: Uint8Array,
-   offset: number,
-): DecodeResult<string> {
-   const view = new DataView(
-      bytes.buffer,
-      bytes.byteOffset,
-      bytes.byteLength,
-   );
-   const len = view.getUint32(offset, true);
-   const value = decoder.decode(
-      bytes.subarray(offset + 4, offset + 4 + len),
-   );
-   return { value, bytesRead: 4 + len };
-}

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

@@ -1,16 +0,0 @@
-import type { DecodeResult } from './decode-string.function.ts';
-
-export function decodeU32(
-   bytes: Uint8Array,
-   offset: number,
-): DecodeResult<number> {
-   const view = new DataView(
-      bytes.buffer,
-      bytes.byteOffset,
-      bytes.byteLength,
-   );
-   return {
-      value: view.getUint32(offset, true),
-      bytesRead: 4,
-   };
-}

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

@@ -1,16 +0,0 @@
-import type { DecodeResult } from './decode-string.function.ts';
-
-export function decodeU64(
-   bytes: Uint8Array,
-   offset: number,
-): DecodeResult<bigint> {
-   const view = new DataView(
-      bytes.buffer,
-      bytes.byteOffset,
-      bytes.byteLength,
-   );
-   return {
-      value: view.getBigUint64(offset, true),
-      bytesRead: 8,
-   };
-}

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

@@ -1,31 +0,0 @@
-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/functions/encode-add-section-params.function.ts

@@ -1,102 +0,0 @@
-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),
-      encodeOptionString(params.title),
-      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);
-   let offset = 0;
-   for (const part of parts) {
-      result.set(part, offset);
-      offset += part.length;
-   }
-   return result;
-}

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

@@ -1,28 +0,0 @@
-import { encodeString } from './encode-string.function.ts';
-import { encodeKbidList } from './encode-kbid-list.function.ts';
-
-/**
- * Encodes parameters for the `worker_group_sections` WASM call into
- * a single byte buffer: title, kbid list, then doc type tag.
- *
- * @param title - human-readable document title
- * @param kbids - identifiers of the sections to group
- * @param docType - application-level document type tag; defaults to
- *   empty string when not specified
- */
-export function encodeGroupParams(
-   title: string,
-   kbids: string[],
-   docType = '',
-): Uint8Array {
-   const titleBytes = encodeString(title);
-   const listBytes = encodeKbidList(kbids);
-   const docTypeBytes = encodeString(docType);
-   const result = new Uint8Array(
-      titleBytes.length + listBytes.length + docTypeBytes.length,
-   );
-   result.set(titleBytes, 0);
-   result.set(listBytes, titleBytes.length);
-   result.set(docTypeBytes, titleBytes.length + listBytes.length);
-   return result;
-}

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

@@ -1,17 +0,0 @@
-import { encodeU32 } from './encode-u32.function.ts';
-import { encodeString } from './encode-string.function.ts';
-
-export function encodeIdentifierList(ids: string[]): Uint8Array {
-   if (ids.length === 0) {
-      return new Uint8Array(0);
-   }
-   const parts = [encodeU32(ids.length), ...ids.map(encodeString)];
-   const totalLen = parts.reduce((sum, p) => sum + p.length, 0);
-   const result = new Uint8Array(totalLen);
-   let offset = 0;
-   for (const part of parts) {
-      result.set(part, offset);
-      offset += part.length;
-   }
-   return result;
-}

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

@@ -1,17 +0,0 @@
-import { encodeU32 } from './encode-u32.function.ts';
-import { encodeString } from './encode-string.function.ts';
-
-export function encodeKbidList(kbids: string[]): Uint8Array {
-   if (kbids.length === 0) {
-      return new Uint8Array(0);
-   }
-   const parts = [encodeU32(kbids.length), ...kbids.map(encodeString)];
-   const totalLen = parts.reduce((sum, p) => sum + p.length, 0);
-   const result = new Uint8Array(totalLen);
-   let offset = 0;
-   for (const part of parts) {
-      result.set(part, offset);
-      offset += part.length;
-   }
-   return result;
-}

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

@@ -1,14 +0,0 @@
-import { encodeString } from './encode-string.function.ts';
-
-export function encodeOptionString(
-   value: string | null | undefined,
-): Uint8Array {
-   if (value == null) {
-      return new Uint8Array([0x00]);
-   }
-   const encoded = encodeString(value);
-   const result = new Uint8Array(1 + encoded.length);
-   result[0] = 0x01;
-   result.set(encoded, 1);
-   return result;
-}

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

@@ -1,68 +0,0 @@
-import { encodeU32 } from './encode-u32.function.ts';
-import { encodeString } from './encode-string.function.ts';
-
-/**
- * Encodes recall parameters to the binary format expected by the
- * `worker_recall` WASM export.
- *
- * Binary layout:
- * - `u8 tag`: `0` = single kbid, `1` = batch
- * - If tag=0: `u32 len + utf8` kbid
- * - If tag=1: `u32 count` + (`u32 len + utf8`) per kbid
- * - `u32 depth` (little-endian)
- *
- * When both `kbid` and `kbids` are provided, `kbids` takes precedence
- * and `kbid` is appended to the batch.
- *
- * @param params - recall parameters; at least one of `kbid` or
- *   `kbids` must be present
- */
-export function encodeRecallParams(params: {
-   kbid?: string;
-   kbids?: readonly string[];
-   depth?: number;
-}): Uint8Array {
-   const depth = params.depth ?? 0;
-   const depthBytes = encodeU32(depth);
-
-   // Batch: kbids provided (kbid optionally appended)
-   if (params.kbids !== undefined) {
-      const allKbids: string[] =
-         params.kbid !== undefined
-            ? [...params.kbids, params.kbid]
-            : [...params.kbids];
-
-      const countBytes = encodeU32(allKbids.length);
-      const encodedKbids = allKbids.map(encodeString);
-
-      const totalLen =
-         1 + // tag
-         countBytes.length +
-         encodedKbids.reduce((sum, b) => sum + b.length, 0) +
-         depthBytes.length;
-
-      const result = new Uint8Array(totalLen);
-      let offset = 0;
-      result[offset++] = 0x01; // tag = batch
-      result.set(countBytes, offset);
-      offset += countBytes.length;
-      for (const kbidBytes of encodedKbids) {
-         result.set(kbidBytes, offset);
-         offset += kbidBytes.length;
-      }
-      result.set(depthBytes, offset);
-      return result;
-   }
-
-   // Single kbid
-   const kbid = params.kbid ?? '';
-   const kbidBytes = encodeString(kbid);
-   const totalLen = 1 + kbidBytes.length + depthBytes.length;
-   const result = new Uint8Array(totalLen);
-   let offset = 0;
-   result[offset++] = 0x00; // tag = single
-   result.set(kbidBytes, offset);
-   offset += kbidBytes.length;
-   result.set(depthBytes, offset);
-   return result;
-}

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

@@ -1,12 +0,0 @@
-const encoder = new TextEncoder();
-
-export function encodeSearchParams(
-   query: string,
-   mode = 'and',
-   limit = 20,
-   offset = 0,
-): Uint8Array {
-   return encoder.encode(
-      `${query}\n${mode}\n${String(limit)}\n${String(offset)}`,
-   );
-}

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

@@ -1,18 +0,0 @@
-import { encodeString } from './encode-string.function.ts';
-
-export function encodeSectionType(
-   kind: 'text' | 'code' | 'image',
-   mimeType?: string,
-): Uint8Array {
-   if (kind === 'text') {
-      return new Uint8Array([0x00]);
-   }
-
-   const tag = kind === 'code' ? 0x01 : 0x02;
-   const mime = mimeType ?? 'text/plain';
-   const encoded = encodeString(mime);
-   const result = new Uint8Array(1 + encoded.length);
-   result[0] = tag;
-   result.set(encoded, 1);
-   return result;
-}

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

@@ -1,9 +0,0 @@
-const encoder = new TextEncoder();
-
-export function encodeString(value: string): Uint8Array {
-   const utf8 = encoder.encode(value);
-   const result = new Uint8Array(4 + utf8.length);
-   new DataView(result.buffer).setUint32(0, utf8.length, true);
-   result.set(utf8, 4);
-   return result;
-}

package/src/shared/wasm-codec/functions/encode-type-filter-param.function.ts

@@ -1,13 +0,0 @@
-/**
- * Encodes a type filter string as raw UTF-8 bytes for WASM input.
- *
- * Used to pass a type name to WASM exports such as
- * `worker_list_by_type` and `worker_list_docs_by_type`, which accept
- * a plain UTF-8 byte slice without a length prefix.
- *
- * @param typeStr - the type name to filter by (e.g. `'article'`)
- * @returns UTF-8 encoded bytes ready to pass to the WASM export
- */
-export function encodeTypeFilterParam(typeStr: string): Uint8Array {
-   return new TextEncoder().encode(typeStr);
-}

package/src/shared/wasm-codec/functions/encode-u32.function.ts

@@ -1,5 +0,0 @@
-export function encodeU32(value: number): Uint8Array {
-   const result = new Uint8Array(4);
-   new DataView(result.buffer).setUint32(0, value, true);
-   return result;
-}

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

@@ -1,16 +0,0 @@
-import { encodeString } from './encode-string.function.ts';
-import { encodeAddSectionParams } from './encode-add-section-params.function.ts';
-
-import type { AddSectionInput } from './encode-add-section-params.function.ts';
-
-export function encodeUpdateSectionParams(
-   oldKbid: string,
-   params: AddSectionInput,
-): Uint8Array {
-   const kbidBytes = encodeString(oldKbid);
-   const paramBytes = encodeAddSectionParams(params);
-   const result = new Uint8Array(kbidBytes.length + paramBytes.length);
-   result.set(kbidBytes, 0);
-   result.set(paramBytes, kbidBytes.length);
-   return result;
-}

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

@@ -1,49 +0,0 @@
-export { encodeString } from './functions/encode-string.function.ts';
-export { encodeU32 } from './functions/encode-u32.function.ts';
-export { encodeOptionString } from './functions/encode-option-string.function.ts';
-export { encodeSectionType } from './functions/encode-section-type.function.ts';
-export { encodeAddSectionParams } from './functions/encode-add-section-params.function.ts';
-export { encodeUpdateSectionParams } from './functions/encode-update-section-params.function.ts';
-export { encodeKbidList } from './functions/encode-kbid-list.function.ts';
-export { encodeGroupParams } from './functions/encode-group-params.function.ts';
-export { encodeIdentifierList } from './functions/encode-identifier-list.function.ts';
-export { encodeSearchParams } from './functions/encode-search-params.function.ts';
-export { encodeTypeFilterParam } from './functions/encode-type-filter-param.function.ts';
-export { decodeString } from './functions/decode-string.function.ts';
-export { decodeU32 } from './functions/decode-u32.function.ts';
-export { decodeF32 } from './functions/decode-f32.function.ts';
-export { decodeU64 } from './functions/decode-u64.function.ts';
-export { decodePagedSearchResult } from './functions/decode-scored-results.function.ts';
-export { decodeSectionRecords } from './functions/decode-section-records.function.ts';
-export { decodeSectionRecordList } from './functions/decode-section-record-list.function.ts';
-export { decodeDocumentManifest } from './functions/decode-document-manifest.function.ts';
-export { decodeDocumentManifestList } from './functions/decode-document-manifest-list.function.ts';
-export { decodeComposeOutput } from './functions/decode-compose-output.function.ts';
-export { decodeKeyValueText } from './functions/decode-key-value-text.function.ts';
-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,
-} from './functions/decode-scored-results.function.ts';
-export type { SectionRecord } from './functions/decode-section-records.function.ts';
-export type {
-   DocumentManifest,
-   DocumentSection,
-} from './functions/decode-document-manifest.function.ts';
-export type { ComposeOutput } from './functions/decode-compose-output.function.ts';
-export type {
-   RecallResult,
-   RecallDocument,
-   RecallSibling,
-   RecallReference,
-} from '../worker-client/typings/recall-result.model.ts';

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

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

@@ -1,28 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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

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

@@ -1,10 +0,0 @@
-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

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

@@ -1,22 +0,0 @@
-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;
-}