@knolo/core 3.1.3 → 3.2.0

package/README.md

@@ -1,176 +1,328 @@
+# 📦 `@knolo/core`
 
+`@knolo/core` is the **deterministic retrieval engine and pack runtime** behind Knolo.
 
-# 📦 `@knolo/core`
+It lets you:
+
+* Build structured knowledge packs
+* Mount portable `.knolo` artifacts
+* Run deterministic lexical retrieval
+* Optionally apply hybrid semantic reranking
+* Enforce strict runtime contracts for advanced workflows
+
+No vector database required.
+No cloud dependency required.
+Works fully offline.
+
+---
+
+# 🧠 What It Is
+
+`@knolo/core` is **not**:
 
-# @knolo/core
+* A vector database wrapper
+* A hosted RAG service
+* A probabilistic similarity engine
 
-KnoLo Core is a **local-first knowledge base engine for small language models (LLMs)**.
+It is:
 
-It allows you to package structured documents into a compact `.knolo` file and query them deterministically — **no embeddings, no vector databases, no cloud required**.
+* A versioned binary pack format
+* A deterministic lexical retrieval engine
+* An optional semantic rerank layer
+* A portable knowledge runtime
 
-Designed for:
-- On-device LLMs
-- Deterministic AI systems
-- Agent routing
-- Air-gapped or privacy-first environments
+You build once.
+You mount anywhere — Node, browser, React Native, serverless, offline.
 
 ---
 
-## ✨ Why KnoLo?
+# 📊 Retrieval Characteristics
 
-Traditional RAG systems require:
-- Embeddings
-- Vector databases
-- External services
-- Non-deterministic similarity scoring
+Lexical retrieval is:
 
-KnoLo uses:
-- Structured indexing
-- Namespace-based routing
-- Deterministic query resolution
-- Compact `.knolo` bundles
+* Deterministic
+* Reproducible
+* Stable across runs
+* Independent of embeddings
 
-This makes it:
-- Fast
-- Reproducible
-- Lightweight
-- Fully local
+Hybrid reranking is:
+
+* Optional
+* Deterministic for fixed vectors
+* Lexical-first (semantic never replaces grounding)
+
+In benchmark testing (March 2026):
+
+* **Recall@5:** 1.000
+* **MRR@5:** 0.867
+* **nDCG@5:** 0.900
+
+Strong ranking quality without requiring a vector database.
 
 ---
 
-## 📦 Installation
+# 📦 Installation
 
 ```bash
 npm install @knolo/core
-````
+```
 
 ---
 
-## 🚀 Basic Usage
+# 🚀 Core Concepts
 
-### 1️⃣ Mount a Knowledge Pack
+## 1️⃣ Build a Pack
+
+```ts
+import { buildPack } from "@knolo/core";
+
+const bytes = await buildPack(docs, {
+  semantic: {
+    enabled: false
+  }
+});
+```
+
+`buildPack` produces a versioned `.knolo` binary artifact.
+
+You can write it to disk or store it in object storage.
+
+---
+
+## 2️⃣ Mount a Pack
+
+### Node.js (local path convenience)
+
+```ts
+import { mountPack } from "@knolo/core/node";
+
+const pack = await mountPack({
+  src: "./dist/knowledge.knolo"
+});
+```
+
+### React Native / Expo (URL or bytes)
 
 ```ts
 import { mountPack } from "@knolo/core";
 
-const pack = await mountPack("./dist/knowledge.knolo");
+const ab = await (await fetch(PACK_URL)).arrayBuffer();
+const pack = await mountPack({ src: new Uint8Array(ab) });
 ```
 
+You can mount from:
+
+* URL string (runtime-safe entry)
+* Buffer / Uint8Array
+* Local file path in Node via `@knolo/core/node`
+* Object storage download
+
+Mount-time validation ensures:
+
+* Pack version compatibility
+* Metadata integrity
+* Optional agent registry validation
+
 ---
 
-### 2️⃣ Query the Pack
+## 3️⃣ Query (Deterministic Lexical Retrieval)
 
 ```ts
 import { query } from "@knolo/core";
 
-const results = query(pack, {
-  namespace: "mobile",
-  q: "debounce vs throttle"
+const hits = query(pack, "debounce vs throttle", {
+  topK: 5
 });
 
-console.log(results);
+for (const hit of hits) {
+  console.log(hit.text);
+  console.log(hit.metadata); // { score, source, namespace, id }
+}
 ```
 
+Properties:
+
+* Fully deterministic
+* No embedding dependency
+* Namespace-aware
+* Evaluation-friendly scoring
+
 ---
 
-### 3️⃣ Resolve an Agent
+# 🔀 Optional: Hybrid Semantic Rerank
 
-```ts
-import { resolveAgent } from "@knolo/core";
+Semantic rerank runs **after lexical retrieval**.
+
+It never replaces lexical grounding.
+
+## Build with embeddings
 
-const resolved = resolveAgent(pack, {
-  agentId: "support-agent",
-  query: "Explain debounce vs throttle",
+```ts
+const bytes = await buildPack(docs, {
+  semantic: {
+    enabled: true,
+    modelId: "text-embedding-3-small",
+    embeddings,
+    quantization: {
+      type: "int8_l2norm",
+      perVectorScale: true
+    }
+  }
 });
 ```
 
-Supports patch variables:
+## Query with rerank
 
 ```ts
-resolveAgent(pack, {
-  agentId: "support-agent",
-  patch: { tone: "formal" },
+import { hasSemantic } from "@knolo/core";
+
+const hits = query(pack, "react native throttling issue", {
+  topK: 8,
+  semantic: {
+    enabled: hasSemantic(pack),
+    mode: "rerank",
+    topN: 50,
+    minLexConfidence: 0.35,
+    blend: { enabled: true, wLex: 0.75, wSem: 0.25 },
+    queryEmbedding
+  }
 });
 ```
 
+Design principles:
+
+* Lexical-first
+* Deterministic scoring
+* No external vector store
+* Quantized embedding storage inside pack
+
 ---
 
-## 🤖 Agents
+# 🤖 Optional: Agent Metadata & Routing
+
+Knolo is a knowledge engine first.
 
-Agents are defined inside the pack metadata.
+However, packs may optionally embed structured metadata for:
 
-Phase 2 features include:
+* System prompts
+* Namespace restrictions
+* Tool policies
+* Routing hints
 
-* Agent routing profiles
-* Deterministic route validation
-* Tool policies (`allow_all`, `mixed`, `unknown`)
-* Registry validation at mount-time
+Agent registries are validated once at `mountPack()`.
+
+These features are additive and do not affect retrieval.
 
 ---
 
-## 🛠 Tool Policy Helpers
+# 🛠 Runtime Contracts (Advanced)
+
+For strict deterministic workflows:
+
+## RouteDecisionV1
 
 ```ts
-import { isToolAllowed, assertToolAllowed } from "@knolo/core";
+type RouteDecisionV1 = {
+  type: "route_decision";
+  intent?: string;
+  entities?: Record<string, unknown>;
+  candidates: { agentId: string; score: number }[];
+  selected: string;
+};
+```
+
+## ToolCallV1
+
+```ts
+type ToolCallV1 = {
+  type: "tool_call";
+  callId: string;
+  tool: string;
+  args: Record<string, unknown>;
+};
+```
+
+Helpers:
 
-isToolAllowed(agent, "web-search");
-assertToolAllowed(agent, "database-read");
+```ts
+import {
+  isRouteDecisionV1,
+  validateRouteDecisionV1,
+  isToolAllowed,
+  assertToolCallAllowed
+} from "@knolo/core";
 ```
 
-Default behavior:
+Enables:
+
+* Deterministic routing validation
+* Policy enforcement
+* Tool permission checks
+* Structured AI pipelines
 
-* If no policy → allow all
-* Explicit deny → deterministic error
+These are optional — not required for standard retrieval usage.
 
 ---
 
-## 📁 .knolo Format
+# 📁 `.knolo` Pack Format
 
-A `.knolo` file contains:
+Binary layout:
 
-* Indexed documents
-* Namespaces
-* Agent registry
-* Metadata
-* Routing profiles
+```
+[metaLen][meta]
+[lexLen][lexicon]
+[postCount][postings]
+[blocksLen][blocks]
+[semantic?]
+```
 
-Built using `@knolo/cli`.
+Properties:
 
----
+* Versioned
+* Compact
+* Immutable
+* Semantic section auto-detected
+* Designed for fast mount + query
 
-## 🧠 Design Philosophy
+---
 
-KnoLo is built around:
+# ⚙️ Design Guarantees
 
-* Determinism over probability
-* Structure over embeddings
-* Local-first AI
-* Small model optimization
-* Agent-native architecture
+* Deterministic lexical retrieval
+* Deterministic hybrid rerank (fixed vectors)
+* No vector database required
+* No cloud dependency required
+* Works offline
+* Works in React Native / Expo
+* Portable binary artifacts
 
 ---
 
-## 🔐 Use Cases
+# 🔐 Ideal For
 
-* On-device assistants
-* Enterprise internal knowledge
-* Mobile AI apps
-* Secure environments
-* Offline-first systems
+* Local-first AI systems
+* Offline assistants
+* On-device LLM retrieval
+* Secure / air-gapped environments
+* Deterministic RAG pipelines
+* Evaluation-heavy workflows
 
 ---
 
-## 🗺 Roadmap
+# 🗺 Roadmap
 
-* Rust core implementation
+* Incremental pack updates
+* Evaluation tooling
+* Performance introspection APIs
 * WASM builds
-* Multi-language SDKs
-* Advanced agent routing
-* Deterministic tool orchestration
+* Continued local-first optimization
 
 ---
 
-## 📄 License
+# 📄 License
+
+Apache-2.0
+
+
 
-MIT
 

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-export { mountPack, hasSemantic } from './pack.js';
+export { mountPack, hasSemantic } from './pack.runtime.js';
 export { query, lexConfidence, validateQueryOptions, validateSemanticQueryOptions, } from './query.js';
 export { makeContextPatch } from './patch.js';
 export { buildPack } from './builder.js';
 export { quantizeEmbeddingInt8L2Norm, encodeScaleF16, decodeScaleF16, } from './semantic.js';
 export { listAgents, getAgent, resolveAgent, buildSystemPrompt, isToolAllowed, assertToolAllowed, validateAgentRegistry, validateAgentDefinition, } from './agent.js';
-export type { MountOptions, PackMeta, Pack } from './pack.js';
+export type { MountOptions, PackMeta, Pack } from './pack.runtime.js';
 export type { QueryOptions, Hit } from './query.js';
 export type { ContextPatch } from './patch.js';
 export type { BuildInputDoc, BuildPackOptions } from './builder.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-export { mountPack, hasSemantic } from './pack.js';
+export { mountPack, hasSemantic } from './pack.runtime.js';
 export { query, lexConfidence, validateQueryOptions, validateSemanticQueryOptions, } from './query.js';
 export { makeContextPatch } from './patch.js';
 export { buildPack } from './builder.js';

package/dist/node.d.ts

@@ -0,0 +1,2 @@
+export { mountPack, hasSemantic } from './pack.node.js';
+export type { MountOptions, PackMeta, Pack } from './pack.node.js';

package/dist/node.js

@@ -0,0 +1 @@
+export { mountPack, hasSemantic } from './pack.node.js';

package/dist/pack.d.ts

@@ -1,35 +1,2 @@
-import type { AgentRegistry } from './agent.js';
-export type MountOptions = {
-    src: string | ArrayBufferLike | Uint8Array;
-};
-export type PackMeta = {
-    version: number;
-    stats: {
-        docs: number;
-        blocks: number;
-        terms: number;
-        avgBlockLen?: number;
-    };
-    agents?: AgentRegistry;
-};
-export type Pack = {
-    meta: PackMeta;
-    lexicon: Map<string, number>;
-    postings: Uint32Array;
-    blocks: string[];
-    headings?: (string | null)[];
-    docIds?: (string | null)[];
-    namespaces?: (string | null)[];
-    blockTokenLens?: number[];
-    semantic?: {
-        version: 1;
-        modelId: string;
-        dims: number;
-        encoding: 'int8_l2norm';
-        perVectorScale: boolean;
-        vecs: Int8Array;
-        scales?: Uint16Array;
-    };
-};
-export declare function hasSemantic(pack: Pack): boolean;
-export declare function mountPack(opts: MountOptions): Promise<Pack>;
+export { mountPack, hasSemantic } from './pack.runtime.js';
+export type { MountOptions, PackMeta, Pack } from './pack.runtime.js';

package/dist/pack.js

@@ -1,175 +1 @@
-/*
- * pack.ts
- *
- * Mount `.knolo` packs across Node, browsers, and RN/Expo. Tolerant of:
- *  - blocks as string[] (v1) or object[] with { text, heading?, docId?, namespace?, len? }
- *  - meta.stats.avgBlockLen (optional)
- * Includes RN/Expo-safe TextDecoder via ponyfill.
- */
-import { getTextDecoder } from './utils/utf8.js';
-import { validateAgentRegistry } from './agent.js';
-export function hasSemantic(pack) {
-    return Boolean(pack.semantic && pack.semantic.dims > 0 && pack.semantic.vecs.length > 0);
-}
-export async function mountPack(opts) {
-    const buf = await resolveToBuffer(opts.src);
-    const dv = new DataView(buf);
-    const dec = getTextDecoder();
-    let offset = 0;
-    // meta
-    const metaLen = dv.getUint32(offset, true);
-    offset += 4;
-    const metaJson = dec.decode(new Uint8Array(buf, offset, metaLen));
-    offset += metaLen;
-    const meta = JSON.parse(metaJson);
-    if (meta.agents) {
-        validateAgentRegistry(meta.agents);
-    }
-    // lexicon
-    const lexLen = dv.getUint32(offset, true);
-    offset += 4;
-    const lexJson = dec.decode(new Uint8Array(buf, offset, lexLen));
-    offset += lexLen;
-    const lexEntries = JSON.parse(lexJson);
-    const lexicon = new Map(lexEntries);
-    // postings
-    const postCount = dv.getUint32(offset, true);
-    offset += 4;
-    const postings = new Uint32Array(postCount);
-    for (let i = 0; i < postCount; i++) {
-        postings[i] = dv.getUint32(offset, true);
-        offset += 4;
-    }
-    // blocks (v1: string[]; v2/v3: {text, heading?, docId?, namespace?, len?}[])
-    const blocksLen = dv.getUint32(offset, true);
-    offset += 4;
-    const blocksJson = dec.decode(new Uint8Array(buf, offset, blocksLen));
-    offset += blocksLen;
-    const parsed = JSON.parse(blocksJson);
-    let blocks = [];
-    let headings;
-    let docIds;
-    let namespaces;
-    let blockTokenLens;
-    if (Array.isArray(parsed) && parsed.length && typeof parsed[0] === 'string') {
-        // v1
-        blocks = parsed;
-    }
-    else if (Array.isArray(parsed)) {
-        blocks = [];
-        headings = [];
-        docIds = [];
-        namespaces = [];
-        blockTokenLens = [];
-        for (const it of parsed) {
-            if (it && typeof it === 'object') {
-                blocks.push(String(it.text ?? ''));
-                headings.push(it.heading ?? null);
-                docIds.push(it.docId ?? null);
-                namespaces.push(it.namespace ?? null);
-                blockTokenLens.push(typeof it.len === 'number' ? it.len : 0);
-            }
-            else {
-                blocks.push(String(it ?? ''));
-                headings.push(null);
-                docIds.push(null);
-                namespaces.push(null);
-                blockTokenLens.push(0);
-            }
-        }
-    }
-    else {
-        blocks = [];
-    }
-    let semantic;
-    if (offset < buf.byteLength) {
-        const semLen = dv.getUint32(offset, true);
-        offset += 4;
-        const semJson = dec.decode(new Uint8Array(buf, offset, semLen));
-        offset += semLen;
-        const sem = JSON.parse(semJson);
-        const semBlobLen = dv.getUint32(offset, true);
-        offset += 4;
-        const semBlob = new Uint8Array(buf, offset, semBlobLen);
-        semantic = parseSemanticSection(sem, semBlob);
-    }
-    return {
-        meta,
-        lexicon,
-        postings,
-        blocks,
-        headings,
-        docIds,
-        namespaces,
-        blockTokenLens,
-        semantic,
-    };
-}
-function parseSemanticSection(sem, blob) {
-    const vectors = sem?.blocks?.vectors;
-    const scales = sem?.blocks?.scales;
-    const vecs = new Int8Array(blob.buffer, blob.byteOffset + Number(vectors?.byteOffset ?? 0), Number(vectors?.length ?? 0));
-    let scaleView;
-    if (scales) {
-        const scaleLen = Number(scales.length ?? 0);
-        const scaleOffset = Number(scales.byteOffset ?? 0);
-        const dv = new DataView(blob.buffer, blob.byteOffset + scaleOffset, scaleLen * 2);
-        scaleView = new Uint16Array(scaleLen);
-        for (let i = 0; i < scaleLen; i++) {
-            scaleView[i] = dv.getUint16(i * 2, true);
-        }
-    }
-    return {
-        version: 1,
-        modelId: String(sem?.modelId ?? ''),
-        dims: Number(sem?.dims ?? 0),
-        encoding: 'int8_l2norm',
-        perVectorScale: Boolean(sem?.perVectorScale),
-        vecs,
-        scales: scaleView,
-    };
-}
-async function resolveToBuffer(src) {
-    if (typeof src === 'string') {
-        if (isNodeRuntime() && isLikelyLocalPath(src)) {
-            return await readLocalFileAsBuffer(src);
-        }
-        const res = await fetch(src);
-        return await res.arrayBuffer();
-    }
-    if (src instanceof Uint8Array) {
-        if (src.byteOffset === 0 && src.byteLength === src.buffer.byteLength) {
-            return src.buffer;
-        }
-        const copy = src.slice();
-        return copy.buffer;
-    }
-    return src;
-}
-function isNodeRuntime() {
-    const p = globalThis
-        .process;
-    return !!p?.versions?.node;
-}
-function isLikelyLocalPath(value) {
-    if (value.startsWith('file://'))
-        return true;
-    if (value.startsWith('./') ||
-        value.startsWith('../') ||
-        value.startsWith('/') ||
-        value.startsWith('~'))
-        return true;
-    if (/^[A-Za-z]:[\\/]/.test(value))
-        return true; // Windows absolute path
-    if (/^[A-Za-z][A-Za-z\d+.-]*:/.test(value))
-        return false; // URL scheme
-    return true; // plain relative path like "knowledge.knolo"
-}
-async function readLocalFileAsBuffer(pathOrFileUrl) {
-    const { readFile } = await import('node:fs/promises');
-    const filePath = pathOrFileUrl.startsWith('file://')
-        ? decodeURIComponent(new URL(pathOrFileUrl).pathname)
-        : pathOrFileUrl;
-    const data = await readFile(filePath);
-    return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
-}
+export { mountPack, hasSemantic } from './pack.runtime.js';

package/dist/pack.node.d.ts

@@ -0,0 +1,4 @@
+import type { MountOptions, Pack } from './pack.runtime.js';
+export { hasSemantic } from './pack.runtime.js';
+export type { MountOptions, PackMeta, Pack } from './pack.runtime.js';
+export declare function mountPack(opts: MountOptions): Promise<Pack>;

package/dist/pack.node.js

@@ -0,0 +1,35 @@
+import { mountPackFromBuffer, toArrayBuffer } from './pack.runtime.js';
+export { hasSemantic } from './pack.runtime.js';
+export async function mountPack(opts) {
+    const buf = await resolveToBuffer(opts.src);
+    return mountPackFromBuffer(buf);
+}
+async function resolveToBuffer(src) {
+    if (typeof src === 'string') {
+        if (isLikelyLocalPath(src)) {
+            const { readFile } = await import('node:fs/promises');
+            const filePath = src.startsWith('file://')
+                ? decodeURIComponent(new URL(src).pathname)
+                : src;
+            const data = await readFile(filePath);
+            return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+        }
+        const res = await fetch(src);
+        return await res.arrayBuffer();
+    }
+    return toArrayBuffer(src);
+}
+function isLikelyLocalPath(value) {
+    if (value.startsWith('file://'))
+        return true;
+    if (value.startsWith('./') ||
+        value.startsWith('../') ||
+        value.startsWith('/') ||
+        value.startsWith('~'))
+        return true;
+    if (/^[A-Za-z]:[\\/]/.test(value))
+        return true;
+    if (/^[A-Za-z][A-Za-z\d+.-]*:/.test(value))
+        return false;
+    return true;
+}

package/dist/pack.runtime.d.ts

@@ -0,0 +1,37 @@
+import type { AgentRegistry } from './agent.js';
+export type MountOptions = {
+    src: string | ArrayBufferLike | Uint8Array;
+};
+export type PackMeta = {
+    version: number;
+    stats: {
+        docs: number;
+        blocks: number;
+        terms: number;
+        avgBlockLen?: number;
+    };
+    agents?: AgentRegistry;
+};
+export type Pack = {
+    meta: PackMeta;
+    lexicon: Map<string, number>;
+    postings: Uint32Array;
+    blocks: string[];
+    headings?: (string | null)[];
+    docIds?: (string | null)[];
+    namespaces?: (string | null)[];
+    blockTokenLens?: number[];
+    semantic?: {
+        version: 1;
+        modelId: string;
+        dims: number;
+        encoding: 'int8_l2norm';
+        perVectorScale: boolean;
+        vecs: Int8Array;
+        scales?: Uint16Array;
+    };
+};
+export declare function hasSemantic(pack: Pack): boolean;
+export declare function mountPack(opts: MountOptions): Promise<Pack>;
+export declare function mountPackFromBuffer(buf: ArrayBuffer): Pack;
+export declare function toArrayBuffer(src: ArrayBufferLike | Uint8Array): ArrayBuffer;

package/dist/pack.runtime.js

@@ -0,0 +1,146 @@
+/*
+ * pack.runtime.ts
+ *
+ * Runtime-safe pack mounting for browser and React Native environments.
+ * No Node stdlib imports are allowed in this module.
+ */
+import { getTextDecoder } from './utils/utf8.js';
+import { validateAgentRegistry } from './agent.js';
+export function hasSemantic(pack) {
+    return Boolean(pack.semantic && pack.semantic.dims > 0 && pack.semantic.vecs.length > 0);
+}
+export async function mountPack(opts) {
+    const buf = await resolveToBuffer(opts.src);
+    return mountPackFromBuffer(buf);
+}
+export function mountPackFromBuffer(buf) {
+    const dv = new DataView(buf);
+    const dec = getTextDecoder();
+    let offset = 0;
+    const metaLen = dv.getUint32(offset, true);
+    offset += 4;
+    const metaJson = dec.decode(new Uint8Array(buf, offset, metaLen));
+    offset += metaLen;
+    const meta = JSON.parse(metaJson);
+    if (meta.agents) {
+        validateAgentRegistry(meta.agents);
+    }
+    const lexLen = dv.getUint32(offset, true);
+    offset += 4;
+    const lexJson = dec.decode(new Uint8Array(buf, offset, lexLen));
+    offset += lexLen;
+    const lexEntries = JSON.parse(lexJson);
+    const lexicon = new Map(lexEntries);
+    const postCount = dv.getUint32(offset, true);
+    offset += 4;
+    const postings = new Uint32Array(postCount);
+    for (let i = 0; i < postCount; i++) {
+        postings[i] = dv.getUint32(offset, true);
+        offset += 4;
+    }
+    const blocksLen = dv.getUint32(offset, true);
+    offset += 4;
+    const blocksJson = dec.decode(new Uint8Array(buf, offset, blocksLen));
+    offset += blocksLen;
+    const parsed = JSON.parse(blocksJson);
+    let blocks = [];
+    let headings;
+    let docIds;
+    let namespaces;
+    let blockTokenLens;
+    if (Array.isArray(parsed) && parsed.length && typeof parsed[0] === 'string') {
+        blocks = parsed;
+    }
+    else if (Array.isArray(parsed)) {
+        blocks = [];
+        headings = [];
+        docIds = [];
+        namespaces = [];
+        blockTokenLens = [];
+        for (const it of parsed) {
+            if (it && typeof it === 'object') {
+                blocks.push(String(it.text ?? ''));
+                headings.push(it.heading ?? null);
+                docIds.push(it.docId ?? null);
+                namespaces.push(it.namespace ?? null);
+                blockTokenLens.push(typeof it.len === 'number' ? it.len : 0);
+            }
+            else {
+                blocks.push(String(it ?? ''));
+                headings.push(null);
+                docIds.push(null);
+                namespaces.push(null);
+                blockTokenLens.push(0);
+            }
+        }
+    }
+    let semantic;
+    if (offset < buf.byteLength) {
+        const semLen = dv.getUint32(offset, true);
+        offset += 4;
+        const semJson = dec.decode(new Uint8Array(buf, offset, semLen));
+        offset += semLen;
+        const sem = JSON.parse(semJson);
+        const semBlobLen = dv.getUint32(offset, true);
+        offset += 4;
+        const semBlob = new Uint8Array(buf, offset, semBlobLen);
+        semantic = parseSemanticSection(sem, semBlob);
+    }
+    return {
+        meta,
+        lexicon,
+        postings,
+        blocks,
+        headings,
+        docIds,
+        namespaces,
+        blockTokenLens,
+        semantic,
+    };
+}
+function parseSemanticSection(sem, blob) {
+    const vectors = sem?.blocks?.vectors;
+    const scales = sem?.blocks?.scales;
+    const vecs = new Int8Array(blob.buffer, blob.byteOffset + Number(vectors?.byteOffset ?? 0), Number(vectors?.length ?? 0));
+    let scaleView;
+    if (scales) {
+        const scaleLen = Number(scales.length ?? 0);
+        const scaleOffset = Number(scales.byteOffset ?? 0);
+        const dv = new DataView(blob.buffer, blob.byteOffset + scaleOffset, scaleLen * 2);
+        scaleView = new Uint16Array(scaleLen);
+        for (let i = 0; i < scaleLen; i++) {
+            scaleView[i] = dv.getUint16(i * 2, true);
+        }
+    }
+    return {
+        version: 1,
+        modelId: String(sem?.modelId ?? ''),
+        dims: Number(sem?.dims ?? 0),
+        encoding: 'int8_l2norm',
+        perVectorScale: Boolean(sem?.perVectorScale),
+        vecs,
+        scales: scaleView,
+    };
+}
+async function resolveToBuffer(src) {
+    if (typeof src === 'string') {
+        try {
+            const res = await fetch(src);
+            return await res.arrayBuffer();
+        }
+        catch {
+            throw new Error('mountPack({src: string}) expects a URL in React Native. For local files, load bytes in your app and pass Uint8Array/ArrayBuffer.');
+        }
+    }
+    return toArrayBuffer(src);
+}
+export function toArrayBuffer(src) {
+    if (src instanceof Uint8Array) {
+        if (src.byteOffset === 0 && src.byteLength === src.buffer.byteLength) {
+            return src.buffer;
+        }
+        const copy = src.slice();
+        return copy.buffer;
+    }
+    return src;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knolo/core",
-  "version": "3.1.3",
+  "version": "3.2.0",
   "type": "module",
   "description": "Local-first knowledge packs for small LLMs.",
   "keywords": [
@@ -19,8 +19,14 @@
   ],
   "exports": {
     ".": {
+      "react-native": "./dist/index.js",
+      "browser": "./dist/index.js",
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./node": {
+      "import": "./dist/node.js",
+      "types": "./dist/node.d.ts"
     }
   },
   "sideEffects": false,
@@ -28,9 +34,10 @@
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build",
     "smoke": "node scripts/smoke.mjs",
-    "test": "npm run build && node scripts/test.mjs",
-    "format": "prettier --write src/agent.ts src/pack.ts src/builder.ts src/index.ts scripts/test.mjs ../../README.md",
-    "format:check": "prettier --check src/agent.ts src/pack.ts src/builder.ts src/index.ts scripts/test.mjs ../../README.md"
+    "test": "npm run build && node scripts/check-runtime-no-node.mjs && node scripts/test.mjs",
+    "format": "prettier --write src/agent.ts src/pack.ts src/pack.runtime.ts src/pack.node.ts src/node.ts src/builder.ts src/index.ts scripts/test.mjs scripts/check-runtime-no-node.mjs ../../README.md README.md",
+    "format:check": "prettier --check src/agent.ts src/pack.ts src/pack.runtime.ts src/pack.node.ts src/node.ts src/builder.ts src/index.ts scripts/test.mjs scripts/check-runtime-no-node.mjs ../../README.md README.md",
+    "check:runtime-no-node": "node scripts/check-runtime-no-node.mjs"
   },
   "devDependencies": {
     "@types/node": "^20.11.0",