@dikolab/kbdb 0.1.0

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

@@ -0,0 +1,70 @@
+import { decodeString } from './decode-string.function.ts';
+import { decodeU32 } from './decode-u32.function.ts';
+import { decodeU64 } from './decode-u64.function.ts';
+import type {
+   DocumentManifest,
+   DocumentSection,
+} from './decode-document-manifest.function.ts';
+
+export type { DocumentManifest, DocumentSection };
+
+/**
+ * Decodes a WASM byte slice into an array of `DocumentManifest` values.
+ *
+ * The binary format is: u32 count, followed by count × DocumentManifest
+ * entries. Each entry contains: docid (string), title (string),
+ * createdAt (u64), docType (string), section count (u32), then each
+ * section's kbid (string) and position (u32).
+ *
+ * @param bytes - raw bytes returned by `worker_list_docs_by_type`
+ * @returns decoded array of document manifests, empty when count is zero
+ */
+export function decodeDocumentManifestList(
+   bytes: Uint8Array,
+): DocumentManifest[] {
+   let offset = 0;
+   const count = decodeU32(bytes, offset);
+   offset += count.bytesRead;
+
+   const manifests: DocumentManifest[] = [];
+   for (let i = 0; i < count.value; i++) {
+      const docid = decodeString(bytes, offset);
+      offset += docid.bytesRead;
+
+      const title = decodeString(bytes, offset);
+      offset += title.bytesRead;
+
+      const createdAt = decodeU64(bytes, offset);
+      offset += createdAt.bytesRead;
+
+      const docType = decodeString(bytes, offset);
+      offset += docType.bytesRead;
+
+      const secCount = decodeU32(bytes, offset);
+      offset += secCount.bytesRead;
+
+      const sections: DocumentSection[] = [];
+      for (let j = 0; j < secCount.value; j++) {
+         const kbid = decodeString(bytes, offset);
+         offset += kbid.bytesRead;
+
+         const position = decodeU32(bytes, offset);
+         offset += position.bytesRead;
+
+         sections.push({
+            kbid: kbid.value,
+            position: position.value,
+         });
+      }
+
+      manifests.push({
+         docid: docid.value,
+         title: title.value,
+         createdAt: createdAt.value,
+         docType: docType.value,
+         sections,
+      });
+   }
+
+   return manifests;
+}

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

@@ -0,0 +1,87 @@
+import { decodeString } from './decode-string.function.ts';
+import { decodeU32 } from './decode-u32.function.ts';
+import { decodeU64 } from './decode-u64.function.ts';
+
+/**
+ * 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;
+}
+
+/**
+ * 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[];
+}
+
+/**
+ * Decodes a single `DocumentManifest` from WASM binary output.
+ *
+ * Reads fields in the order: docid, title, createdAt, docType,
+ * section count, then each section's kbid and position.
+ *
+ * @param bytes - raw bytes returned by `worker_retrieve_doc`
+ * @returns the decoded document manifest
+ */
+export function decodeDocumentManifest(
+   bytes: Uint8Array,
+): DocumentManifest {
+   let offset = 0;
+
+   const docid = decodeString(bytes, offset);
+   offset += docid.bytesRead;
+
+   const title = decodeString(bytes, offset);
+   offset += title.bytesRead;
+
+   const createdAt = decodeU64(bytes, offset);
+   offset += createdAt.bytesRead;
+
+   const docType = decodeString(bytes, offset);
+   offset += docType.bytesRead;
+
+   const count = decodeU32(bytes, offset);
+   offset += count.bytesRead;
+
+   const sections: DocumentSection[] = [];
+   for (let i = 0; i < count.value; i++) {
+      const kbid = decodeString(bytes, offset);
+      offset += kbid.bytesRead;
+
+      const position = decodeU32(bytes, offset);
+      offset += position.bytesRead;
+
+      sections.push({
+         kbid: kbid.value,
+         position: position.value,
+      });
+   }
+
+   return {
+      docid: docid.value,
+      title: title.value,
+      createdAt: createdAt.value,
+      docType: docType.value,
+      sections,
+   };
+}

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

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

package/src/shared/wasm-codec/functions/decode-key-value-text.function.ts

@@ -0,0 +1,15 @@
+export function decodeKeyValueText(
+   text: string,
+): Record<string, string> {
+   const result: Record<string, string> = {};
+   for (const line of text.split('\n')) {
+      const idx = line.indexOf('=');
+      if (idx < 0) continue;
+      const key = line.slice(0, idx);
+      const value = line.slice(idx + 1);
+      if (key) {
+         result[key] = value;
+      }
+   }
+   return result;
+}

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

@@ -0,0 +1,3 @@
+export function decodeRemoveFlag(bytes: Uint8Array): boolean {
+   return bytes.length > 0 && bytes[0] === 0x01;
+}

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

@@ -0,0 +1,54 @@
+import { decodeString } from './decode-string.function.ts';
+import { decodeU32 } from './decode-u32.function.ts';
+import { decodeF32 } from './decode-f32.function.ts';
+
+export interface TermMatch {
+   term: string;
+   frequency: number;
+}
+
+export interface ScoredResult {
+   kbid: string;
+   score: number;
+   matches: TermMatch[];
+}
+
+export function decodeScoredResults(bytes: Uint8Array): ScoredResult[] {
+   let offset = 0;
+   const count = decodeU32(bytes, offset);
+   offset += count.bytesRead;
+
+   const results: ScoredResult[] = [];
+   for (let i = 0; i < count.value; i++) {
+      const kbid = decodeString(bytes, offset);
+      offset += kbid.bytesRead;
+
+      const score = decodeF32(bytes, offset);
+      offset += score.bytesRead;
+
+      const matchCount = decodeU32(bytes, offset);
+      offset += matchCount.bytesRead;
+
+      const matches: TermMatch[] = [];
+      for (let j = 0; j < matchCount.value; j++) {
+         const term = decodeString(bytes, offset);
+         offset += term.bytesRead;
+
+         const freq = decodeF32(bytes, offset);
+         offset += freq.bytesRead;
+
+         matches.push({
+            term: term.value,
+            frequency: freq.value,
+         });
+      }
+
+      results.push({
+         kbid: kbid.value,
+         score: score.value,
+         matches,
+      });
+   }
+
+   return results;
+}

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

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

@@ -0,0 +1,162 @@
+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;
+}
+
+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.
+ *
+ * @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;
+
+      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,
+      };
+      if (st.mimeType !== undefined) {
+         record.mimeType = st.mimeType;
+      }
+      records.push(record);
+   }
+
+   return records;
+}

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

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

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

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

@@ -0,0 +1,34 @@
+import { encodeSectionType } from './encode-section-type.function.ts';
+import { encodeString } from './encode-string.function.ts';
+import { encodeOptionString } from './encode-option-string.function.ts';
+
+export interface AddSectionInput {
+   sectionType: 'text' | 'code' | 'image';
+   mimeType?: string;
+   content: string;
+   title?: string | null;
+   description?: string | null;
+   docid?: string | null;
+   typeName?: string | null;
+}
+
+export function encodeAddSectionParams(
+   params: AddSectionInput,
+): Uint8Array {
+   const parts = [
+      encodeSectionType(params.sectionType, params.mimeType),
+      encodeString(params.content),
+      encodeOptionString(params.title),
+      encodeOptionString(params.description),
+      encodeOptionString(params.docid),
+      encodeOptionString(params.typeName),
+   ];
+   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

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

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

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

@@ -0,0 +1,14 @@
+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-search-params.function.ts

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

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

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

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

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

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