knolo-core 0.1.4 → 0.2.1

package/README.md

@@ -1,23 +1,29 @@
 
-
 # 🧠 KnoLo Core
 
 [![npm version](https://img.shields.io/npm/v/knolo-core.svg)](https://www.npmjs.com/package/knolo-core)
 [![npm downloads](https://img.shields.io/npm/dm/knolo-core.svg)](https://www.npmjs.com/package/knolo-core)
 [![License](https://img.shields.io/npm/l/knolo-core.svg)](./LICENSE)
 
-**KnoLo Core** is a **local-first knowledge base system** for small language models (LLMs).
-It lets you package your own documents into a compact `.knolo` file and query them deterministically — **no embeddings, no vector DBs, no cloud**. Perfect for **on-device LLMs**.
+**KnoLo Core** is a **local-first knowledge base** for small LLMs.
+Package documents into a compact `.knolo` file and query them deterministically —
+**no embeddings, no vector DB, no cloud**. Ideal for **on‑device / offline** assistants.
 
 ---
 
-## ✨ Features
+## ✨ Highlights (v0.2.0)
+
+* 🔎 **Stronger relevance:**
 
-* 📦 **Single-file packs** (`.knolo`) you can ship or load offline
-* 🔎 **Deterministic lexical retrieval** (BM25L + phrase + heading boosts)
-* ⚡ **Tiny & fast** — runs in Node, browsers, and Expo
-* 📑 **Context Patches**: structured snippets optimized for LLM prompts
-* 🔒 **Privacy-first**: all data stays local
+  * **Required phrase enforcement** (quoted & `requirePhrases`)
+  * **Proximity bonus** using minimal term-span cover
+  * **Optional heading boosts** when headings are present
+* 🌀 **Duplicate-free results:** **near-duplicate suppression** + **MMR diversity**
+* 🧮 **KNS tie‑breaker:** lightweight numeric signature to stabilize close ties
+* ⚡ **Faster & leaner:** precomputed `avgBlockLen` in pack metadata
+* 📱 **Works in Expo/React Native:** safe TextEncoder/TextDecoder ponyfills
+* 📑 **Context Patches:** LLM‑friendly snippets for prompts
+* 🔒 **Local & private:** everything runs on device
 
 ---
 
@@ -27,7 +33,7 @@ It lets you package your own documents into a compact `.knolo` file and query th
 npm install knolo-core
 ```
 
-For local development (building from source):
+Dev from source:
 
 ```bash
 git clone https://github.com/yourname/knolo-core.git
@@ -38,113 +44,242 @@ npm run build
 
 ---
 
-## 🚀 Usage Examples
+## 🚀 Usage
 
-### 1. Node.js (in-memory build + query)
+### 1) Node.js (build → mount → query → patch)
 
-```js
+```ts
 import { buildPack, mountPack, query, makeContextPatch } from "knolo-core";
 
 const docs = [
-  { heading: "React Native Bridge", text: "The bridge sends messages between JS and native. You can throttle events to reduce jank." },
-  { heading: "Throttling", text: "Throttling reduces frequency of events to avoid flooding the bridge." },
-  { heading: "Debounce vs Throttle", text: "Debounce waits for silence, throttle guarantees a max rate." }
+  { id: "guide",   heading: "React Native Bridge", text: "The bridge sends messages between JS and native. You can throttle events..." },
+  { id: "throttle", heading: "Throttling",         text: "Throttling reduces frequency of events to avoid flooding the bridge." },
+  { id: "dvst",     heading: "Debounce vs Throttle", text: "Debounce waits for silence; throttle guarantees a max rate." }
 ];
 
-// Build a pack in memory
-const bytes = await buildPack(docs);
+const bytes = await buildPack(docs);              // build .knolo bytes
+const kb = await mountPack({ src: bytes });       // mount in-memory
+const hits = query(kb, '“react native” throttle', // quotes enforce phrase
+  { topK: 5, requirePhrases: ["max rate"] });
 
-// Mount it
-const kb = await mountPack({ src: bytes });
-
-// Query
-const hits = query(kb, "react native bridge throttling", { topK: 5 });
-console.log("Top hits:", hits);
+console.log(hits);
+/*
+[
+  { blockId: 2, score: 6.73, text: "...", source: "dvst" },
+  ...
+]
+*/
 
-// Turn into an LLM-friendly context patch
 const patch = makeContextPatch(hits, { budget: "small" });
-console.log("Context Patch:", patch);
+console.log(patch);
 ```
 
----
-
-### 2. CLI (build `.knolo` file)
+### 2) CLI (build a `.knolo` file)
 
-**Prepare `docs.json`:**
+Create `docs.json`:
 
 ```json
 [
-  { "heading": "Guide", "text": "Install deps.\n\n## Throttle\nLimit frequency of events." },
-  { "heading": "FAQ", "text": "What is throttling? It reduces event frequency." }
+  { "id": "guide", "heading": "Guide", "text": "Install deps...\n\n## Throttle\nLimit frequency of events." },
+  { "id": "faq",   "heading": "FAQ",   "text": "What is throttling? It reduces event frequency." }
 ]
 ```
 
-**Build the pack:**
+Build:
 
 ```bash
-# writes mypack.knolo
-npx knolo docs.json mypack.knolo
+# writes knowledge.knolo
+npx knolo docs.json knowledge.knolo
 ```
 
-**Query it in a script:**
+Then load it in your app:
 
-```js
+```ts
 import { mountPack, query } from "knolo-core";
-
-const kb = await mountPack({ src: "./mypack.knolo" });
+const kb = await mountPack({ src: "./knowledge.knolo" });
 const hits = query(kb, "throttle events", { topK: 3 });
-console.log(hits);
 ```
 
----
-
-### 3. React / Expo (load from asset)
+### 3) React / Expo
 
 ```ts
 import { Asset } from "expo-asset";
 import * as FileSystem from "expo-file-system";
-import { mountPack, query, makeContextPatch } from "knolo-core";
+import { mountPack, query } from "knolo-core";
 
-async function loadKnowledge() {
-  const asset = Asset.fromModule(require("./assets/mypack.knolo"));
+async function loadKB() {
+  const asset = Asset.fromModule(require("./assets/knowledge.knolo"));
   await asset.downloadAsync();
 
   const base64 = await FileSystem.readAsStringAsync(asset.localUri!, { encoding: FileSystem.EncodingType.Base64 });
   const bytes = Uint8Array.from(atob(base64), c => c.charCodeAt(0));
 
   const kb = await mountPack({ src: bytes.buffer });
-  const hits = query(kb, "bridge throttling", { topK: 5 });
-  return makeContextPatch(hits, { budget: "mini" });
+  return query(kb, `“react native” throttling`, { topK: 5 });
 }
 ```
 
 ---
 
-## 📑 API Quick Reference
+## 📑 API
+
+### `buildPack(docs) -> Promise<Uint8Array>`
+
+Builds a pack from an array of documents.
 
 ```ts
-// Build a pack from docs
-buildPack([{ heading: string, text: string }[]]) -> Promise<Uint8Array>
+type BuildInputDoc = {
+  id?: string;          // optional doc id (exposed as hit.source)
+  heading?: string;     // optional heading (used for boosts)
+  text: string;         // raw markdown accepted (lightly stripped)
+};
+```
+
+* Stores optional `heading` and `id` alongside each block.
+* Computes and persists `meta.stats.avgBlockLen` for faster queries.
+
+### `mountPack({ src }) -> Promise<Pack>`
+
+Loads a pack from a URL, `Uint8Array`, or `ArrayBuffer`.
+
+```ts
+type Pack = {
+  meta: { version: number; stats: { docs: number; blocks: number; terms: number; avgBlockLen?: number } };
+  lexicon: Map<string, number>;
+  postings: Uint32Array;
+  blocks: string[];
+  headings?: (string | null)[];
+  docIds?: (string | null)[];
+};
+```
+
+> **Compatibility:** v0.2.0 reads both v1 packs (string-only blocks) and v2 packs (objects with `text/heading/docId`).
 
-// Load a pack
-mountPack({ src: string | Uint8Array | ArrayBuffer }) -> Promise<Pack>
+### `query(pack, q, opts) -> Hit[]`
 
-// Query
-query(pack, "your query", { topK?: number, requirePhrases?: string[] }) -> Hit[]
+Deterministic lexical search with phrase enforcement, proximity, and de‑duplication.
 
-// Create LLM-friendly patch
-makeContextPatch(hits, { budget?: "mini" | "small" | "full" }) -> ContextPatch
+```ts
+type QueryOptions = {
+  topK?: number;                // default 10
+  requirePhrases?: string[];    // additional phrases to require (unquoted)
+};
+
+type Hit = {
+  blockId: number;
+  score: number;
+  text: string;
+  source?: string;              // docId if provided at build time
+};
+```
+
+**What happens under the hood (v0.2.0):**
+
+* Tokenize + **enforce all phrases** (quoted in `q` and `requirePhrases`)
+* Candidate generation via inverted index
+* **Proximity bonus** using minimal window covering all query terms
+* Optional **heading overlap boost** (when headings are present)
+* Tiny **KNS** numeric-signature tie‑breaker (\~±2% influence)
+* **Near-duplicate suppression** (5‑gram Jaccard) + **MMR** diversity for top‑K
+
+### `makeContextPatch(hits, { budget }) -> ContextPatch`
+
+Create structured snippets for LLM prompts.
+
+```ts
+type ContextPatch = {
+  background: string[];
+  snippets: Array<{ text: string; source?: string }>;
+  definitions: Array<{ term: string; def: string; evidence?: number[] }>;
+  facts: Array<{ s: string; p: string; o: string; evidence?: number[] }>;
+};
 ```
 
+Budgets: `"mini" | "small" | "full"`.
+
+---
+
+## 🧠 Relevance & De‑dupe Details
+
+* **Phrases:**
+  Quoted phrases in the query (e.g., `“react native”`) and any `requirePhrases` **must appear** in results. Candidates failing this are dropped before ranking.
+
+* **Proximity:**
+  We compute the **minimum span** that covers all query terms and apply a gentle multiplier:
+  `1 + 0.15 / (1 + span)` (bounded, stable).
+
+* **Heading Boost:**
+  If you provide headings at build time, overlap with query terms boosts the score proportionally to the fraction of unique query terms present in the heading.
+
+* **Duplicate Control:**
+  We use **5‑gram Jaccard** to filter near‑duplicates and **MMR** (λ≈0.8) to promote diversity within the top‑K.
+
+* **KNS Signature (optional spice):**
+  A tiny numeric signature provides deterministic tie‑breaking without changing the overall retrieval behavior.
+
+---
+
+## 🛠 Input Format & Pack Layout
+
+**Input docs:**
+`{ id?: string, heading?: string, text: string }`
+
+**Pack layout (binary):**
+`[metaLen:u32][meta JSON][lexLen:u32][lexicon JSON][postCount:u32][postings][blocksLen:u32][blocks JSON]`
+
+* `meta.stats.avgBlockLen` is persisted (v2).
+* `blocks JSON` may be:
+
+  * **v1:** `string[]` (text only)
+  * **v2:** `{ text, heading?, docId? }[]`
+
+The runtime auto‑detects either format.
+
 ---
 
-## 🔮 Roadmap
+## 🔁 Migration (0.1.x → 0.2.0)
+
+* **No API breaks.** `buildPack`, `mountPack`, `query`, `makeContextPatch` unchanged.
+* Packs built with 0.1.x still load and query fine.
+* If you want heading boosts and `hit.source`, pass `heading` and `id` to `buildPack`.
+* React Native/Expo users no longer need polyfills—ponyfills are included.
+
+---
+
+## ⚡ Performance Tips
+
+* Prefer multiple smaller blocks (≈512 tokens) over giant ones for better recall + proximity.
+* Provide `heading` for each block: cheap, high‑signal boost.
+* For large corpora, consider sharding packs by domain/topic to keep per‑pack size modest.
+
+---
+
+## ❓ FAQ
+
+**Q: Does this use embeddings?**
+No. Pure lexical retrieval (index, positions, BM25L, proximity, phrases).
+
+**Q: Can I run this offline?**
+Yes. Everything is local.
+
+**Q: How do I prevent duplicates?**
+It’s built in (Jaccard + MMR). You can tune λ and similarity threshold in code if you fork.
+
+**Q: Is RN/Expo supported?**
+Yes—TextEncoder/TextDecoder ponyfills are included.
+
+---
+
+## 🗺️ Roadmap
 
 * Multi-resolution packs (summaries + facts)
-* Overlay store for user notes
-* WASM core for very large packs
+* Overlay layers (user annotations)
+* WASM core for big-browser indexing
+* Delta updates / append-only patch packs
 
 ---
 
-👉 With **KnoLo**, you can **carry knowledge with your model** — no servers, no dependencies, just a tiny portable pack.
+## 📄 License
+
+Apache-2.0 — see [LICENSE](./LICENSE).
 

package/dist/builder.d.ts

@@ -3,9 +3,4 @@ export type BuildInputDoc = {
     heading?: string;
     text: string;
 };
-/** Build a `.knolo` pack from an array of input documents. At present each
- * document becomes a single block. Future versions may split documents into
- * multiple blocks based on headings or token count to improve retrieval
- * granularity.
- */
 export declare function buildPack(docs: BuildInputDoc[]): Promise<Uint8Array>;

package/dist/builder.js

@@ -1,34 +1,44 @@
 /*
  * builder.ts
  *
- * Provides a programmatic interface for building `.knolo` knowledge packs
- * from arrays of input documents. The input format accepts objects with
- * `id`, `heading` and `text` fields. The builder performs simple
- * Markdown stripping and calls the indexer to generate the inverted index. The
- * resulting pack binary can be persisted to disk or served directly to
- * clients.
+ * Build `.knolo` packs from input docs. Now persists optional headings/docIds
+ * and stores avgBlockLen in meta for faster/easier normalization at query-time.
  */
 import { buildIndex } from './indexer.js';
-/** Build a `.knolo` pack from an array of input documents. At present each
- * document becomes a single block. Future versions may split documents into
- * multiple blocks based on headings or token count to improve retrieval
- * granularity.
- */
+import { tokenize } from './tokenize.js';
+import { getTextEncoder } from './utils/utf8.js';
 export async function buildPack(docs) {
-    // Convert docs into blocks. For v0 each doc is a single block; heading is
-    // ignored except possibly for future heading boosting in ranking.
-    const blocks = docs.map((d, i) => ({ id: i, text: stripMd(d.text), heading: d.heading }));
+    // Prepare blocks (strip MD) and carry heading/docId for optional boosts.
+    const blocks = docs.map((d, i) => ({
+        id: i,
+        text: stripMd(d.text),
+        heading: d.heading,
+    }));
+    // Build index
     const { lexicon, postings } = buildIndex(blocks);
+    // Compute avg token length once (store in meta)
+    const totalTokens = blocks.reduce((sum, b) => sum + tokenize(b.text).length, 0);
+    const avgBlockLen = blocks.length ? totalTokens / blocks.length : 1;
     const meta = {
-        version: 1,
-        stats: { docs: docs.length, blocks: blocks.length, terms: lexicon.length },
+        version: 2,
+        stats: {
+            docs: docs.length,
+            blocks: blocks.length,
+            terms: lexicon.length,
+            avgBlockLen,
+        },
     };
-    // Encode sections to bytes
-    const enc = new TextEncoder();
+    // Persist blocks as objects to optionally carry heading/docId
+    const blocksPayload = blocks.map((b, i) => ({
+        text: b.text,
+        heading: b.heading ?? null,
+        docId: docs[i]?.id ?? null,
+    }));
+    // Encode sections
+    const enc = getTextEncoder();
     const metaBytes = enc.encode(JSON.stringify(meta));
     const lexBytes = enc.encode(JSON.stringify(lexicon));
-    const blocksBytes = enc.encode(JSON.stringify(blocks.map((b) => b.text)));
-    // Compute lengths and allocate output
+    const blocksBytes = enc.encode(JSON.stringify(blocksPayload));
     const totalLength = 4 + metaBytes.length +
         4 + lexBytes.length +
         4 + postings.length * 4 +
@@ -61,19 +71,12 @@ export async function buildPack(docs) {
 }
 /** Strip Markdown syntax with lightweight regexes (no deps). */
 function stripMd(md) {
-    // Remove code fences
-    let text = md.replace(/```[^```]*```/g, ' ');
-    // Remove inline code backticks
+    let text = md.replace(/```[\s\S]*?```/g, ' ');
     text = text.replace(/`[^`]*`/g, ' ');
-    // Remove emphasis markers (*, _, ~)
     text = text.replace(/[\*_~]+/g, ' ');
-    // Remove headings (#)
     text = text.replace(/^#+\s*/gm, '');
-    // Links [text](url) -> text
     text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
-    // Remove any remaining brackets
     text = text.replace(/[\[\]()]/g, ' ');
-    // Collapse whitespace
     text = text.replace(/\s+/g, ' ').trim();
     return text;
 }

package/dist/pack.d.ts

@@ -1,47 +1,21 @@
 export type MountOptions = {
     src: string | ArrayBufferLike | Uint8Array;
 };
-/** Metadata about the pack. Version numbers should increment with format
- *  changes, allowing the runtime to adapt accordingly. */
 export type PackMeta = {
     version: number;
     stats: {
         docs: number;
         blocks: number;
         terms: number;
+        avgBlockLen?: number;
     };
 };
-/**
- * A mounted pack exposing the inverted index, block text and optional field
- * metadata. The core runtime reads from these structures directly at query
- * time.
- */
 export type Pack = {
     meta: PackMeta;
-    /** Map of token to term identifier used in the postings list. */
     lexicon: Map<string, number>;
-    /** Flattened postings list where each term section starts with the termId
-     * followed by (blockId, positions..., 0) tuples, ending with a 0.
-     */
     postings: Uint32Array;
-    /** Array of block texts. Each block corresponds to a chunk of the original
-     * documents. The blockId used in the postings list indexes into this array.
-     */
     blocks: string[];
+    headings?: (string | null)[];
+    docIds?: (string | null)[];
 };
-/**
- * Load a `.knolo` pack from a variety of sources. The pack binary layout is
- * currently:
- *
- *  [metaLen:u32][meta JSON][lexLen:u32][lexicon JSON][postCount:u32][postings][blocksLen:u32][blocks JSON]
- *
- * All integers are little endian. `metaLen`, `lexLen` and `blocksLen` denote
- * the byte lengths of the subsequent JSON sections. `postCount` is the number
- * of 32‑bit integers in the postings array. This simple layout is sufficient
- * for v0 and avoids any additional dependencies beyond standard typed arrays.
- *
- * @param opts Options specifying how to load the pack. Accepts a URL string,
- *        ArrayBuffer, or Uint8Array.
- * @returns A Promise resolving to a mounted pack with the index and blocks.
- */
 export declare function mountPack(opts: MountOptions): Promise<Pack>;

package/dist/pack.js

@@ -1,45 +1,31 @@
 /*
  * pack.ts
  *
- * Defines the pack structure and implements the mountPack function that loads
- * a `.knolo` pack from a variety of sources. A pack consists of a header
- * containing metadata, followed by JSON‑encoded lexicon and blocks and a
- * flattened postings list encoded as a 32‑bit integer array. The pack is
- * portable across Node.js and browser environments.
- */
-/**
- * Load a `.knolo` pack from a variety of sources. The pack binary layout is
- * currently:
- *
- *  [metaLen:u32][meta JSON][lexLen:u32][lexicon JSON][postCount:u32][postings][blocksLen:u32][blocks JSON]
- *
- * All integers are little endian. `metaLen`, `lexLen` and `blocksLen` denote
- * the byte lengths of the subsequent JSON sections. `postCount` is the number
- * of 32‑bit integers in the postings array. This simple layout is sufficient
- * for v0 and avoids any additional dependencies beyond standard typed arrays.
- *
- * @param opts Options specifying how to load the pack. Accepts a URL string,
- *        ArrayBuffer, or Uint8Array.
- * @returns A Promise resolving to a mounted pack with the index and blocks.
+ * Mount `.knolo` packs across Node, browsers, and RN/Expo. Now tolerant of:
+ *  - blocks as string[] (v1) or object[] with { text, heading?, docId? } (v2)
+ *  - meta.stats.avgBlockLen (optional)
+ * Includes RN/Expo-safe TextDecoder via ponyfill.
  */
+import { getTextDecoder } from './utils/utf8.js';
 export async function mountPack(opts) {
     const buf = await resolveToBuffer(opts.src);
     const dv = new DataView(buf);
+    const dec = getTextDecoder();
     let offset = 0;
-    // Read meta section
+    // meta
     const metaLen = dv.getUint32(offset, true);
     offset += 4;
-    const metaJson = new TextDecoder().decode(new Uint8Array(buf, offset, metaLen));
+    const metaJson = dec.decode(new Uint8Array(buf, offset, metaLen));
     offset += metaLen;
     const meta = JSON.parse(metaJson);
-    // Read lexicon
+    // lexicon
     const lexLen = dv.getUint32(offset, true);
     offset += 4;
-    const lexJson = new TextDecoder().decode(new Uint8Array(buf, offset, lexLen));
+    const lexJson = dec.decode(new Uint8Array(buf, offset, lexLen));
     offset += lexLen;
     const lexEntries = JSON.parse(lexJson);
     const lexicon = new Map(lexEntries);
-    // Read postings (alignment-safe via DataView)
+    // postings
     const postCount = dv.getUint32(offset, true);
     offset += 4;
     const postings = new Uint32Array(postCount);
@@ -47,29 +33,49 @@ export async function mountPack(opts) {
         postings[i] = dv.getUint32(offset, true);
         offset += 4;
     }
-    // Read blocks
+    // blocks (v1: string[]; v2: {text, heading?, docId?}[])
     const blocksLen = dv.getUint32(offset, true);
     offset += 4;
-    const blocksJson = new TextDecoder().decode(new Uint8Array(buf, offset, blocksLen));
-    const blocks = JSON.parse(blocksJson);
-    return { meta, lexicon, postings, blocks };
+    const blocksJson = dec.decode(new Uint8Array(buf, offset, blocksLen));
+    const parsed = JSON.parse(blocksJson);
+    let blocks = [];
+    let headings;
+    let docIds;
+    if (Array.isArray(parsed) && parsed.length && typeof parsed[0] === 'string') {
+        // v1
+        blocks = parsed;
+    }
+    else if (Array.isArray(parsed)) {
+        blocks = [];
+        headings = [];
+        docIds = [];
+        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);
+            }
+            else {
+                blocks.push(String(it ?? ''));
+                headings.push(null);
+                docIds.push(null);
+            }
+        }
+    }
+    else {
+        blocks = [];
+    }
+    return { meta, lexicon, postings, blocks, headings, docIds };
 }
-/** Resolve the `src` field of MountOptions into an ArrayBuffer. Supports:
- *  - strings interpreted as URLs (via fetch)
- *  - Uint8Array and ArrayBuffer inputs
- */
 async function resolveToBuffer(src) {
     if (typeof src === 'string') {
         const res = await fetch(src);
-        const ab = await res.arrayBuffer();
-        return ab;
+        return await res.arrayBuffer();
     }
     if (src instanceof Uint8Array) {
-        // If the view covers the whole buffer, return it directly (cast to ArrayBuffer).
         if (src.byteOffset === 0 && src.byteLength === src.buffer.byteLength) {
             return src.buffer;
         }
-        // Otherwise, copy to a new buffer so we return exactly the bytes for this view.
         const copy = src.slice();
         return copy.buffer;
     }

package/dist/quality/diversify.d.ts

@@ -0,0 +1,13 @@
+export type HitLike = {
+    blockId: number;
+    score: number;
+    text: string;
+    source?: string;
+};
+export type DiversifyOptions = {
+    k: number;
+    lambda?: number;
+    simThreshold?: number;
+    sim?: (a: HitLike, b: HitLike) => number;
+};
+export declare function diversifyAndDedupe(hits: HitLike[], opts: DiversifyOptions): HitLike[];

package/dist/quality/diversify.js

@@ -0,0 +1,41 @@
+// src/quality/diversify.ts
+import { jaccard5 } from './similarity.js';
+export function diversifyAndDedupe(hits, opts) {
+    const { k, lambda = 0.8, simThreshold = 0.92, sim = (a, b) => jaccard5(a.text, b.text) } = opts;
+    const pool = [...hits].sort((a, b) => b.score - a.score);
+    const kept = [];
+    while (pool.length && kept.length < k) {
+        // compute MMR for current pool against kept
+        let bestIdx = 0;
+        let bestMMR = -Infinity;
+        for (let i = 0; i < pool.length; i++) {
+            const h = pool[i];
+            let maxSim = 0;
+            for (const s of kept) {
+                const v = sim(h, s);
+                if (v > maxSim)
+                    maxSim = v;
+                if (v >= simThreshold) {
+                    maxSim = v;
+                    break;
+                } // early out
+            }
+            // skip near-duplicates
+            if (maxSim >= simThreshold)
+                continue;
+            const mmr = lambda * h.score - (1 - lambda) * maxSim;
+            if (mmr > bestMMR) {
+                bestMMR = mmr;
+                bestIdx = i;
+            }
+        }
+        // if everything was a near-duplicate, just take the next best by score
+        const pick = pool.splice(bestMMR === -Infinity ? 0 : bestIdx, 1)[0];
+        if (!pick)
+            break;
+        // final dedupe check before push
+        if (!kept.some((x) => sim(x, pick) >= simThreshold))
+            kept.push(pick);
+    }
+    return kept;
+}

package/dist/quality/proximity.d.ts

@@ -0,0 +1,2 @@
+export declare function minCoverSpan(posMap?: Map<number, number[]>): number | null;
+export declare function proximityMultiplier(span: number | null, strength?: number): number;