@dikolab/kbdb 0.1.6 → 0.2.0

package/docs/modules/typescript/shared/runtime/module.md

@@ -0,0 +1,27 @@
+# runtime -- Runtime Detection
+
+**Source:** `src/shared/runtime/`
+
+## Responsibility
+
+Detect whether the process is running on Deno or
+Node.js, and provide cross-runtime access to CLI
+arguments.
+
+## Directory Layout
+
+```
+src/shared/runtime/
+   index.ts
+   functions/
+      detect-runtime.function.ts
+      get-args.function.ts
+   typings/
+      runtime.type.ts
+```
+
+## Exports
+
+- [Functions](functions.md) -- `detectRuntime`,
+  `getArgs`
+- [Typings](typings.md) -- `Runtime`

package/docs/modules/typescript/shared/runtime/typings.md

@@ -0,0 +1,13 @@
+# runtime/typings -- Runtime Type Definitions
+
+**Source:** `src/shared/runtime/typings/`
+
+## Runtime
+
+```ts
+type Runtime = 'deno' | 'node';
+```
+
+Discriminant for the two supported JavaScript runtimes.
+
+No spec -- typings are compile-time only.

package/docs/modules/typescript/shared/version/module.md

@@ -0,0 +1,27 @@
+# version -- Package Version
+
+**Source:** `src/shared/version/`
+
+## Responsibility
+
+Exposes the current package version as a constant.
+Exported from the library API (`mod.ts`). Currently the
+only public export.
+
+## Exports
+
+- `version` -- `'0.0.1'`
+
+## Directory Layout
+
+```
+src/shared/version/
+   index.ts
+   constants/
+      version.constant.ts
+```
+
+## Spec
+
+- `version.spec.ts` -- Validates the version string
+  format.

package/docs/modules/typescript/shared/wasm-codec/functions.md

@@ -0,0 +1,391 @@
+# wasm-codec/functions -- Codec Functions
+
+*One encode or decode function per file. Encoders
+build `Uint8Array` buffers; decoders parse them into
+typed TypeScript values.*
+
+## Source
+
+`src/shared/wasm-codec/functions/`
+
+---
+
+## Encoder Functions
+
+### `encodeString`
+
+**File:** `encode-string.function.ts`
+
+Encodes a UTF-8 string as a little-endian `u32`
+length prefix followed by the UTF-8 bytes.
+
+```ts
+function encodeString(value: string): Uint8Array;
+```
+
+### `encodeU32`
+
+**File:** `encode-u32.function.ts`
+
+Encodes an unsigned 32-bit integer as 4 bytes,
+little-endian.
+
+```ts
+function encodeU32(value: number): Uint8Array;
+```
+
+### `encodeOptionString`
+
+**File:** `encode-option-string.function.ts`
+
+Encodes an optional string. Writes `0x00` for `null`
+or `undefined`; writes `0x01` followed by the encoded
+string for a present value.
+
+```ts
+function encodeOptionString(
+   value: string | null | undefined,
+): Uint8Array;
+```
+
+### `encodeSectionType`
+
+**File:** `encode-section-type.function.ts`
+
+Encodes a section type discriminant. Writes `0x00`
+for `text` (no MIME), `0x01` + MIME for `code`, or
+`0x02` + MIME for `image`.
+
+```ts
+function encodeSectionType(
+   kind: 'text' | 'code' | 'image',
+   mimeType?: string,
+): Uint8Array;
+```
+
+### `encodeAddSectionParams`
+
+**File:** `encode-add-section-params.function.ts`
+
+Encodes parameters for the `worker_add_section` WASM
+export: section type, content, optional title,
+optional description, and optional docid, in that
+order.
+
+```ts
+function encodeAddSectionParams(
+   params: AddSectionInput,
+): Uint8Array;
+```
+
+```ts
+interface AddSectionInput {
+   sectionType: 'text' | 'code' | 'image';
+   mimeType?: string;
+   content: string;
+   title?: string | null;
+   description?: string | null;
+   docid?: string | null;
+}
+```
+
+### `encodeUpdateSectionParams`
+
+**File:** `encode-update-section-params.function.ts`
+
+Encodes parameters for the `worker_update_section`
+WASM export: the old KB ID as an encoded string
+followed by the full `AddSectionInput` encoding.
+
+```ts
+function encodeUpdateSectionParams(
+   oldKbid: string,
+   params: AddSectionInput,
+): Uint8Array;
+```
+
+### `encodeKbidList`
+
+**File:** `encode-kbid-list.function.ts`
+
+Encodes a list of KB IDs as a `u32` count followed
+by each ID encoded as a length-prefixed string.
+Returns an empty `Uint8Array` for an empty list.
+
+```ts
+function encodeKbidList(kbids: string[]): Uint8Array;
+```
+
+### `encodeGroupParams`
+
+**File:** `encode-group-params.function.ts`
+
+Encodes parameters for the `worker_group_sections`
+WASM export: the document title followed by a
+`encodeKbidList` encoding of the section IDs.
+
+```ts
+function encodeGroupParams(
+   title: string,
+   kbids: string[],
+): Uint8Array;
+```
+
+### `encodeIdentifierList`
+
+**File:** `encode-identifier-list.function.ts`
+
+Encodes a list of arbitrary string identifiers (kbid
+or docid) as a `u32` count followed by each ID as a
+length-prefixed string. Returns an empty `Uint8Array`
+for an empty list.
+
+```ts
+function encodeIdentifierList(
+   ids: string[],
+): Uint8Array;
+```
+
+### `encodeSearchParams`
+
+**File:** `encode-search-params.function.ts`
+
+Encodes search parameters as a newline-delimited
+UTF-8 string: `query\nmode\nlimit`.
+
+```ts
+function encodeSearchParams(
+   query: string,
+   mode?: string,
+   limit?: number,
+): Uint8Array;
+```
+
+`mode` defaults to `'and'`; `limit` defaults to `20`.
+
+---
+
+## Decoder Functions
+
+### `decodeString`
+
+**File:** `decode-string.function.ts`
+
+Reads a length-prefixed UTF-8 string from a byte
+buffer at the given offset.
+
+```ts
+function decodeString(
+   bytes: Uint8Array,
+   offset: number,
+): DecodeResult<string>;
+
+interface DecodeResult<T> {
+   value: T;
+   bytesRead: number;
+}
+```
+
+### `decodeU32`
+
+**File:** `decode-u32.function.ts`
+
+Reads a little-endian `u32` from a byte buffer at the
+given offset.
+
+```ts
+function decodeU32(
+   bytes: Uint8Array,
+   offset: number,
+): DecodeResult<number>;
+```
+
+### `decodeF32`
+
+**File:** `decode-f32.function.ts`
+
+Reads a little-endian IEEE 754 `f32` from a byte
+buffer at the given offset.
+
+```ts
+function decodeF32(
+   bytes: Uint8Array,
+   offset: number,
+): DecodeResult<number>;
+```
+
+### `decodeU64`
+
+**File:** `decode-u64.function.ts`
+
+Reads a little-endian `u64` from a byte buffer at the
+given offset. Returns a `bigint`.
+
+```ts
+function decodeU64(
+   bytes: Uint8Array,
+   offset: number,
+): DecodeResult<bigint>;
+```
+
+### `decodeScoredResults`
+
+**File:** `decode-scored-results.function.ts`
+
+Decodes the binary response from `worker_search`
+into an array of scored results.
+
+```ts
+function decodeScoredResults(
+   bytes: Uint8Array,
+): ScoredResult[];
+
+interface ScoredResult {
+   kbid: string;
+   score: number;
+   matches: TermMatch[];
+}
+
+interface TermMatch {
+   term: string;
+   frequency: number;
+}
+```
+
+Wire format: `u32` count, then for each result:
+kbid (length-prefixed string), score (`f32`), match
+count (`u32`), then for each match: term (string),
+frequency (`f32`).
+
+### `decodeSectionRecords`
+
+**File:** `decode-section-records.function.ts`
+
+Decodes the binary response from `worker_read_sections`
+into an array of section records.
+
+```ts
+function decodeSectionRecords(
+   bytes: Uint8Array,
+): SectionRecord[];
+
+interface SectionRecord {
+   kbid: string;
+   docid: string | null;
+   sectionType: string;
+   mimeType?: string;
+   title: string | null;
+   description: string | null;
+   content: string;
+   size: number;
+   createdAt: bigint;
+   checksum: string;
+   tokenCount: number;
+   headingTokenCount: number;
+   bodyTokenCount: number;
+   codeTokenCount: number;
+}
+```
+
+### `decodeDocumentManifest`
+
+**File:** `decode-document-manifest.function.ts`
+
+Decodes the binary response from `worker_retrieve_doc`
+into a document manifest.
+
+```ts
+function decodeDocumentManifest(
+   bytes: Uint8Array,
+): DocumentManifest;
+
+interface DocumentManifest {
+   docid: string;
+   title: string;
+   createdAt: bigint;
+   sections: DocumentSection[];
+}
+
+interface DocumentSection {
+   kbid: string;
+   position: number;
+}
+```
+
+### `decodeComposeOutput`
+
+**File:** `decode-compose-output.function.ts`
+
+Decodes the binary response from `worker_compose`
+into a Markdown string and character count.
+
+```ts
+function decodeComposeOutput(
+   bytes: Uint8Array,
+): ComposeOutput;
+
+interface ComposeOutput {
+   markdown: string;
+   totalChars: bigint;
+}
+```
+
+Wire format: length-prefixed Markdown string followed
+by a `u64` character count.
+
+### `decodeKeyValueText`
+
+**File:** `decode-key-value-text.function.ts`
+
+Parses a newline-delimited `key=value` text response
+into a `Record<string, string>`. Used to decode
+responses from `worker_status`, `worker_check_integrity`,
+and `worker_garbage_collect`.
+
+```ts
+function decodeKeyValueText(
+   text: string,
+): Record<string, string>;
+```
+
+Lines without a `=` separator are silently skipped.
+
+### `decodeRemoveFlag`
+
+**File:** `decode-remove-flag.function.ts`
+
+Decodes a single-byte boolean response from
+`worker_remove_section`. Returns `true` when the
+first byte is `0x01`.
+
+```ts
+function decodeRemoveFlag(bytes: Uint8Array): boolean;
+```
+
+## Testing
+
+Each function has a `.spec.ts` at the module root:
+
+```
+src/shared/wasm-codec/
+├── encode-string.spec.ts
+├── encode-u32.spec.ts
+├── encode-option-string.spec.ts
+├── encode-section-type.spec.ts
+├── encode-add-section-params.spec.ts
+├── encode-update-section-params.spec.ts
+├── encode-kbid-list.spec.ts
+├── encode-group-params.spec.ts
+├── encode-identifier-list.spec.ts
+├── encode-search-params.spec.ts
+├── decode-string.spec.ts
+├── decode-u32.spec.ts
+├── decode-f32.spec.ts
+├── decode-u64.spec.ts
+├── decode-scored-results.spec.ts
+├── decode-section-records.spec.ts
+├── decode-document-manifest.spec.ts
+├── decode-compose-output.spec.ts
+├── decode-key-value-text.spec.ts
+└── decode-remove-flag.spec.ts
+```

package/docs/modules/typescript/shared/wasm-codec/module.md

@@ -0,0 +1,98 @@
+# wasm-codec -- WASM Binary Codec Module
+
+*Encodes TypeScript values into the binary wire format
+consumed by `kb-worker.wasm` and decodes binary
+responses back into typed TypeScript values.*
+
+## Source
+
+`src/shared/wasm-codec/`
+
+## Responsibility
+
+The wasm-codec module provides the binary serialization
+layer between the TypeScript host and the Rust WASM
+engine. Each function handles one specific encode or
+decode operation -- there is no general-purpose codec
+framework.
+
+**Encoders** convert TypeScript values into
+`Uint8Array` buffers that can be written into WASM
+linear memory via the host bridge. Conventions:
+
+- Strings are encoded as a little-endian `u32` length
+  prefix followed by UTF-8 bytes.
+- Optional strings use a `0x00` tag byte for `null`
+  or `0x01` followed by the encoded string.
+- Section types use a `0x00` tag for `text`, `0x01`
+  for `code`, or `0x02` for `image`, followed by the
+  MIME type string for non-text types.
+- Lists use a little-endian `u32` count prefix
+  followed by each element in sequence.
+
+**Decoders** parse `Uint8Array` responses from WASM
+exports into typed TypeScript values. Each decoder
+returns the parsed value directly (not a
+`{ value, offset }` pair at the top level, though
+primitive helpers do return `DecodeResult<T>` for
+composability).
+
+The module has no runtime dependencies on the WASM
+binary itself -- it only manipulates `Uint8Array`
+buffers using `DataView` and `TextEncoder`/
+`TextDecoder`.
+
+## Directory Layout
+
+```
+src/shared/wasm-codec/
+├── index.ts
+└── functions/
+    ├── decode-compose-output.function.ts
+    ├── decode-document-manifest.function.ts
+    ├── decode-f32.function.ts
+    ├── decode-key-value-text.function.ts
+    ├── decode-remove-flag.function.ts
+    ├── decode-scored-results.function.ts
+    ├── decode-section-records.function.ts
+    ├── decode-string.function.ts
+    ├── decode-u32.function.ts
+    ├── decode-u64.function.ts
+    ├── encode-add-section-params.function.ts
+    ├── encode-group-params.function.ts
+    ├── encode-identifier-list.function.ts
+    ├── encode-kbid-list.function.ts
+    ├── encode-option-string.function.ts
+    ├── encode-search-params.function.ts
+    ├── encode-section-type.function.ts
+    ├── encode-string.function.ts
+    ├── encode-u32.function.ts
+    └── encode-update-section-params.function.ts
+```
+
+## Exports
+
+- **[functions.md](functions.md)** -- all encode and
+  decode functions plus exported data types
+  (`AddSectionInput`, `ScoredResult`, `TermMatch`,
+  `SectionRecord`, `DocumentManifest`,
+  `DocumentSection`, `ComposeOutput`, `DecodeResult`).
+
+## Usage
+
+The module is used exclusively by
+`WorkerDaemon.handleRequest` and its private dispatch
+helpers. Callers encode parameters before calling a
+WASM export and decode the response bytes after the
+call returns.
+
+```ts
+import {
+   encodeSearchParams,
+   decodeScoredResults,
+} from '../../wasm-codec/index.ts';
+
+const encoded = encodeSearchParams(query, mode, limit);
+// ... write encoded to WASM memory, call export ...
+const results = decodeScoredResults(responseBytes);
+```