@dikolab/kbdb 0.3.1 → 0.4.0

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

@@ -1,194 +0,0 @@
-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(
-   bytes: Uint8Array,
-   offset: number,
-): { value: string | null; bytesRead: number } {
-   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 };
-}
-
-/**
- * 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 {
-   let offset = 0;
-
-   const total = decodeU32(bytes, offset);
-   offset += total.bytesRead;
-
-   const resultOffset = decodeU32(bytes, offset);
-   offset += resultOffset.bytesRead;
-
-   const limit = decodeU32(bytes, offset);
-   offset += limit.bytesRead;
-
-   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;
-
-   const items: SectionMatch[] = [];
-   for (let i = 0; i < itemCount.value; i++) {
-      const kbid = decodeString(bytes, offset);
-      offset += kbid.bytesRead;
-
-      const heading = decodeOptionString(bytes, offset);
-      offset += heading.bytesRead;
-
-      const sectionType = decodeString(bytes, offset);
-      offset += sectionType.bytesRead;
-
-      const docidCount = decodeU32(bytes, offset);
-      offset += docidCount.bytesRead;
-      const docids: string[] = [];
-      for (let j = 0; j < docidCount.value; j++) {
-         const docid = decodeString(bytes, offset);
-         offset += docid.bytesRead;
-         docids.push(docid.value);
-      }
-
-      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;
-
-      const termCount = decodeU32(bytes, offset);
-      offset += termCount.bytesRead;
-      const matched_terms: string[] = [];
-      for (let j = 0; j < termCount.value; j++) {
-         const term = decodeString(bytes, offset);
-         offset += term.bytesRead;
-         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,
-      });
-   }
-
-   return {
-      items,
-      total: total.value,
-      offset: resultOffset.value,
-      limit: limit.value,
-      has_more: hasMore,
-      relaxed,
-   };
-}

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

@@ -1,80 +0,0 @@
-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-list.function.ts

@@ -1,20 +0,0 @@
-import { decodeSectionRecords } from './decode-section-records.function.ts';
-import type { SectionRecord } from './decode-section-records.function.ts';
-
-export type { SectionRecord };
-
-/**
- * Decodes a WASM byte slice into an array of `SectionRecord` values.
- *
- * Thin wrapper around `decodeSectionRecords` provided as the
- * canonical entry point for list-response decoding from WASM exports
- * such as `worker_list_by_type`.
- *
- * @param bytes - raw bytes returned by a WASM section-list export
- * @returns decoded array of section records
- */
-export function decodeSectionRecordList(
-   bytes: Uint8Array,
-): SectionRecord[] {
-   return decodeSectionRecords(bytes);
-}

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

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

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

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

@@ -1,249 +0,0 @@
-import { decodeString } from './decode-string.function.ts';
-import { decodeU32 } from './decode-u32.function.ts';
-import { decodeU64 } from './decode-u64.function.ts';
-
-/**
- * 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;
-}
-
-function decodeOptionString(
-   bytes: Uint8Array,
-   offset: number,
-): { value: string | null; bytesRead: number } {
-   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 };
-}
-
-function decodeSectionType(
-   bytes: Uint8Array,
-   offset: number,
-): {
-   sectionType: string;
-   mimeType?: string;
-   bytesRead: number;
-} {
-   const tag = bytes[offset];
-   if (tag === 0x00) {
-      return { sectionType: 'text', bytesRead: 1 };
-   }
-   const mime = decodeString(bytes, offset + 1);
-   const kind = tag === 0x01 ? 'code' : 'image';
-   return {
-      sectionType: kind,
-      mimeType: mime.value,
-      bytesRead: 1 + mime.bytesRead,
-   };
-}
-
-/**
- * Decodes a list of `SectionRecord` values from WASM binary output.
- *
- * Reads a leading u32 count followed by that many encoded records.
- * 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
- */
-export function decodeSectionRecords(
-   bytes: Uint8Array,
-): SectionRecord[] {
-   let offset = 0;
-   const count = decodeU32(bytes, offset);
-   offset += count.bytesRead;
-
-   const records: SectionRecord[] = [];
-   for (let i = 0; i < count.value; i++) {
-      const kbid = decodeString(bytes, offset);
-      offset += kbid.bytesRead;
-
-      const docid = decodeOptionString(bytes, offset);
-      offset += docid.bytesRead;
-
-      const st = decodeSectionType(bytes, offset);
-      offset += st.bytesRead;
-
-      const title = decodeOptionString(bytes, offset);
-      offset += title.bytesRead;
-
-      const description = decodeOptionString(bytes, offset);
-      offset += description.bytesRead;
-
-      const content = decodeString(bytes, offset);
-      offset += content.bytesRead;
-
-      const size = decodeU32(bytes, offset);
-      offset += size.bytesRead;
-
-      const createdAt = decodeU64(bytes, offset);
-      offset += createdAt.bytesRead;
-
-      const checksum = decodeString(bytes, offset);
-      offset += checksum.bytesRead;
-
-      const tokenCount = decodeU32(bytes, offset);
-      offset += tokenCount.bytesRead;
-
-      const headingTokenCount = decodeU32(bytes, offset);
-      offset += headingTokenCount.bytesRead;
-
-      const bodyTokenCount = decodeU32(bytes, offset);
-      offset += bodyTokenCount.bytesRead;
-
-      const codeTokenCount = decodeU32(bytes, offset);
-      offset += codeTokenCount.bytesRead;
-
-      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,
-         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,
-         sourcePath,
-         sourceMtime,
-         updatedAt,
-         tags,
-         supersedes,
-      };
-      if (st.mimeType !== undefined) {
-         record.mimeType = st.mimeType;
-      }
-      records.push(record);
-   }
-
-   return records;
-}