@dikolab/kbdb 0.3.0 → 0.3.1

package/src/shared/sync/functions/resolve-conflict.function.ts

@@ -0,0 +1,31 @@
+import type { ConflictResolution } from '../typings/conflict-resolution.type.ts';
+import type { ExportEntry } from '../typings/export-entry.interface.ts';
+
+/**
+ * Determines the conflict resolution action for
+ * an incoming section.
+ *
+ * Rules applied in order:
+ * 1. Same kbid exists -> skip
+ * 2. Same source_key, incoming is newer -> supersede
+ * 3. Same source_key, incoming is not newer -> skip
+ * 4. No match -> add
+ */
+export function resolveConflict(
+   incoming: ExportEntry,
+   existingKbids: ReadonlySet<string>,
+   existingBySourceKey: ReadonlyMap<string, ExportEntry>,
+): ConflictResolution {
+   if (existingKbids.has(incoming.kbid)) {
+      return 'skip';
+   }
+
+   const existing = existingBySourceKey.get(incoming.sourceKey);
+   if (existing !== undefined) {
+      const incomingTime = new Date(incoming.createdAt).getTime();
+      const existingTime = new Date(existing.createdAt).getTime();
+      return incomingTime > existingTime ? 'supersede' : 'skip';
+   }
+
+   return 'add';
+}

package/src/shared/sync/functions/serialize-export-entry.function.ts

@@ -0,0 +1,18 @@
+import type { ExportEntry } from '../typings/export-entry.interface.ts';
+
+/**
+ * Serializes an export entry to a flat file format.
+ *
+ * Format: TOML frontmatter delimited by `+++` lines,
+ * followed by the body content.
+ */
+export function serializeExportEntry(entry: ExportEntry): string {
+   const frontmatter = [
+      `kbid = "${entry.kbid}"`,
+      `sourceKey = "${entry.sourceKey}"`,
+      `heading = "${entry.heading}"`,
+      `createdAt = "${entry.createdAt}"`,
+   ].join('\n');
+
+   return `+++\n${frontmatter}\n+++\n${entry.body}`;
+}

package/src/shared/sync/index.ts

@@ -0,0 +1,9 @@
+export { resolveConflict } from './functions/resolve-conflict.function.ts';
+export { buildImportReport } from './functions/build-import-report.function.ts';
+export { serializeExportEntry } from './functions/serialize-export-entry.function.ts';
+export { parseExportEntry } from './functions/parse-export-entry.function.ts';
+export type { ExportEntry } from './typings/export-entry.interface.ts';
+export type { ExportOptions } from './typings/export-options.interface.ts';
+export type { ImportOptions } from './typings/import-options.interface.ts';
+export type { ImportReport } from './typings/import-report.interface.ts';
+export type { ConflictResolution } from './typings/conflict-resolution.type.ts';

package/src/shared/sync/typings/conflict-resolution.type.ts

@@ -0,0 +1,8 @@
+/**
+ * Conflict resolution strategy.
+ *
+ * - 'skip': same kbid -> skip
+ * - 'supersede': same source_key -> replace if newer
+ * - 'add': no match -> add
+ */
+export type ConflictResolution = 'skip' | 'supersede' | 'add';

package/src/shared/sync/typings/export-entry.interface.ts

@@ -0,0 +1,13 @@
+/** A single entry in an export manifest. */
+export interface ExportEntry {
+   /** Section kbid. */
+   readonly kbid: string;
+   /** Source key. */
+   readonly sourceKey: string;
+   /** Section heading. */
+   readonly heading: string;
+   /** Content body. */
+   readonly body: string;
+   /** Created timestamp (ISO). */
+   readonly createdAt: string;
+}

package/src/shared/sync/typings/export-options.interface.ts

@@ -0,0 +1,9 @@
+/** Options for export operation. */
+export interface ExportOptions {
+   /** Export format. */
+   readonly format: 'git' | 'archive';
+   /** Output directory or file path. */
+   readonly outputPath: string;
+   /** Exclude vector indexes. */
+   readonly excludeVectors: boolean;
+}

package/src/shared/sync/typings/import-options.interface.ts

@@ -0,0 +1,7 @@
+/** Options for import operation. */
+export interface ImportOptions {
+   /** Source path (exported directory or archive). */
+   readonly fromPath: string;
+   /** Dry-run mode. */
+   readonly dryRun: boolean;
+}

package/src/shared/sync/typings/import-report.interface.ts

@@ -0,0 +1,15 @@
+/** Report of an import operation. */
+export interface ImportReport {
+   /** Sections added. */
+   readonly sectionsAdded: number;
+   /** Sections skipped (same kbid). */
+   readonly sectionsSkipped: number;
+   /** Sections superseded (same source_key, newer). */
+   readonly sectionsSuperseded: number;
+   /** Documents added. */
+   readonly documentsAdded: number;
+   /** Documents skipped. */
+   readonly documentsSkipped: number;
+   /** Whether rebuild is required. */
+   readonly rebuildRequired: boolean;
+}

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

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

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