@plebeiantech/lat.md 0.12.3-fork.1

package/dist/src/knowledge/claude-memory.js

@@ -0,0 +1,204 @@
+import { execFile, } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+const CALL_TIMEOUT_MS = 2000;
+const MAX_FILE_BYTES = 64 * 1024;
+/** Escape regex metacharacters so a raw term can be interpolated safely. */
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Resolve the checkout whose memory store applies to `projectRoot`. Claude
+ * Code shares one memory store per repo, keyed on the *main* checkout's
+ * absolute path — a worktree has no store of its own. Without resolving to
+ * the main checkout, every lookup made from inside a worktree session
+ * silently finds nothing, which is invisible unless you know to check: it
+ * never errors, it just never matches. `git rev-parse --git-common-dir`
+ * inside a worktree returns the main checkout's `.git` dir; its parent is
+ * the main checkout. Outside a git repo (or on any failure) we fall back to
+ * `projectRoot` itself.
+ */
+function resolveMainCheckout(projectRoot) {
+    return new Promise((resolvePromise) => {
+        // Async execFile, not execFileSync: this runs on the UserPromptSubmit
+        // critical path alongside the bd and cq stores under
+        // `Promise.allSettled`, and a synchronous subprocess call here would
+        // block the event loop and prevent the other stores' I/O from
+        // overlapping with it.
+        // `stdio` isn't in the string-encoding overload's declared option type
+        // even though Node accepts it at runtime, hence the explicit cast.
+        const options = {
+            cwd: projectRoot,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: CALL_TIMEOUT_MS,
+            encoding: 'utf-8',
+        };
+        execFile('git', ['rev-parse', '--git-common-dir'], options, (error, stdout) => {
+            if (error || !stdout) {
+                resolvePromise(projectRoot);
+                return;
+            }
+            const out = stdout.trim();
+            if (!out) {
+                resolvePromise(projectRoot);
+                return;
+            }
+            const gitDir = resolve(projectRoot, out);
+            resolvePromise(dirname(gitDir));
+        });
+    });
+}
+/**
+ * Match Claude Code's own project-directory slug: every character that
+ * isn't a letter or digit becomes `-`, including `.` — a project root like
+ * `/Users/dave/projects/claude-code/lat.md` slugifies to
+ * `-Users-dave-projects-claude-code-lat-md`, verified against a real
+ * `~/.claude/projects/` listing. Replacing only `/` (the previous
+ * implementation) leaves dots in the slug and never matches the real
+ * directory, so the store silently finds nothing for any project root
+ * containing a dot.
+ */
+export function slugify(absPath) {
+    return absPath.replace(/[^a-zA-Z0-9]/g, '-');
+}
+// `resolveMainCheckout` spawns `git rev-parse` and `memoryDirFor` is called
+// once per matching tag within a single hook invocation, where the project
+// root and its main checkout never change mid-process. Memoize on
+// `projectRoot` so repeated `rank()` calls in one process spawn git at most
+// once per distinct root.
+const memoryDirCache = new Map();
+async function memoryDirFor(projectRoot) {
+    const cached = memoryDirCache.get(projectRoot);
+    if (cached !== undefined)
+        return cached;
+    const mainCheckout = await resolveMainCheckout(projectRoot);
+    const dir = join(homedir(), '.claude', 'projects', slugify(mainCheckout), 'memory');
+    memoryDirCache.set(projectRoot, dir);
+    return dir;
+}
+/** Strip a leading/trailing pair of double quotes, if both are present. */
+function unquote(value) {
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/** Pull a `key: value` line out of YAML-ish frontmatter, quotes stripped. */
+function frontmatterField(text, key) {
+    const re = new RegExp(`^${key}:\\s*(.*)$`, 'm');
+    const match = re.exec(text);
+    return match ? unquote(match[1].trim()) : undefined;
+}
+function readFileCapped(path) {
+    try {
+        const buf = readFileSync(path);
+        return buf.subarray(0, MAX_FILE_BYTES).toString('utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}
+async function query(q) {
+    try {
+        return await rank(q);
+    }
+    catch {
+        // Unconditional, for the same reason as the bd store: every individual
+        // filesystem call below is already guarded, and the contract is worth
+        // more than the assumption that the list of them stays complete.
+        return [];
+    }
+}
+// memoryDir -> ordered list of { key, text } for its non-symlinked .md
+// files. `federateTags` calls `rank()` once per matching document within a
+// single hook invocation, where the memory store on disk cannot change
+// between calls — so the directory listing and file contents are read once
+// per process and reused, instead of re-stat'ing and re-reading every file
+// on every call.
+const fileListCache = new Map();
+function loadFiles(memoryDir) {
+    const cached = fileListCache.get(memoryDir);
+    if (cached !== undefined)
+        return cached;
+    let result = [];
+    if (existsSync(memoryDir)) {
+        let entries = [];
+        try {
+            entries = readdirSync(memoryDir);
+        }
+        catch {
+            entries = [];
+        }
+        const files = [];
+        for (const entry of entries) {
+            if (!entry.endsWith('.md'))
+                continue;
+            const full = join(memoryDir, entry);
+            try {
+                // The directory name is derived from a filesystem path; a symlink here
+                // could point outside the memory store and leak an unrelated file's
+                // contents into a prompt, so symlinks are never followed.
+                if (lstatSync(full).isSymbolicLink())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            files.push(full);
+        }
+        for (const file of files) {
+            const text = readFileCapped(file);
+            if (text === undefined)
+                continue;
+            result.push({ key: file, text });
+        }
+    }
+    fileListCache.set(memoryDir, result);
+    return result;
+}
+async function rank(q) {
+    const memoryDir = await memoryDirFor(q.projectRoot);
+    const files = loadFiles(memoryDir);
+    if (files.length === 0)
+        return [];
+    // key -> { text, count }, built in first-seen (readdir) order so ties keep
+    // that order after the stable sort below, matching the bd store's rule.
+    const seen = new Map();
+    for (const { key, text } of files) {
+        seen.set(key, { text, count: 0 });
+    }
+    for (const term of q.terms) {
+        if (!term)
+            continue;
+        // `\b` is ASCII-only in JS regex, so it fails to bound a term like
+        // "café" (`\bcafé\b` never matches "a café here"). Lookarounds on
+        // "word character" via a Unicode-aware class, with the `u` flag, bound
+        // the match without excluding non-ASCII letters.
+        const wordRe = new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRegExp(term)}(?![\\p{L}\\p{N}_])`, 'iu');
+        for (const v of seen.values()) {
+            if (wordRe.test(v.text))
+                v.count += 1;
+        }
+    }
+    const hits = [...seen.entries()]
+        .filter(([, v]) => v.count > 0)
+        .map(([key, v]) => {
+        const name = frontmatterField(v.text, 'name');
+        const description = frontmatterField(v.text, 'description');
+        const basename = key.slice(memoryDir.length + 1).replace(/\.md$/, '');
+        return {
+            store: 'claude-memory',
+            key,
+            title: name ?? basename,
+            detail: description ?? '',
+            score: v.count,
+        };
+    });
+    hits.sort((a, b) => b.score - a.score);
+    return hits.slice(0, q.limit);
+}
+export const claudeMemoryStore = {
+    name: 'claude-memory',
+    query,
+};

package/dist/src/knowledge/cq.d.ts

@@ -0,0 +1,2 @@
+import type { Store } from './types.js';
+export declare const cqStore: Store;

package/dist/src/knowledge/cq.js

@@ -0,0 +1,74 @@
+import { createClient } from '@libsql/client';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import xdg from '@folder/xdg';
+/** Only letters (any script), digits, and internal hyphens survive. Terms
+ * originate in repository frontmatter, which is attacker-controlled the
+ * moment an agent runs `lat` in a repo nobody here owns — a term containing
+ * a double quote would break out of the quoted FTS5 MATCH string, so
+ * anything that doesn't match this shape is dropped before it ever reaches
+ * SQL. Unicode letters/digits are allowed (not just ASCII) so a tag written
+ * in a non-Latin script still reaches the store instead of being silently
+ * dropped — sqlite's FTS5 tokenizer handles them fine, and they carry no
+ * special meaning to the MATCH syntax the way quotes or parens would. */
+const SAFE_TERM = /^[\p{L}\p{N}][\p{L}\p{N}-]*$/u;
+function dbPath() {
+    return process.env.CQ_LOCAL_DB_PATH ?? join(xdg().data, 'cq', 'local.db');
+}
+export const cqStore = {
+    name: 'cq',
+    async query(q) {
+        try {
+            const path = dbPath();
+            if (!existsSync(path))
+                return [];
+            const terms = q.terms.filter((t) => SAFE_TERM.test(t));
+            if (terms.length === 0)
+                return [];
+            const match = terms.map((t) => `"${t}"`).join(' OR ');
+            const client = createClient({ url: `file:${path}` });
+            try {
+                // A client returning structured rows (rather than shelling out to the
+                // `sqlite3` CLI, whose one-row-per-line list output needs newlines
+                // flattened and a control character as column separator to survive a
+                // summary containing '\n' or '|') removes a whole class of parsing
+                // bugs by construction.
+                const result = await client.execute({
+                    sql: `SELECT rowid, summary, substr(action, 1, 400) AS action
+                FROM knowledge_units_fts
+                WHERE knowledge_units_fts MATCH ?
+                ORDER BY rank
+                LIMIT ?`,
+                    args: [match, q.limit],
+                });
+                const hits = [];
+                for (const row of result.rows) {
+                    const summary = row.summary;
+                    if (typeof summary !== 'string' || summary.length === 0)
+                        continue;
+                    const action = row.action;
+                    hits.push({
+                        store: 'cq',
+                        key: `cq:${row.rowid}`,
+                        title: summary,
+                        detail: typeof action === 'string' ? action : '',
+                        // cq ranks internally via bm25 and cannot attribute a match to
+                        // individual terms, so it reports the full term count and relies
+                        // on the caller's stable sort to preserve this query's order.
+                        score: terms.length,
+                    });
+                }
+                return hits;
+            }
+            finally {
+                client.close();
+            }
+        }
+        catch {
+            // Missing table, malformed FTS syntax, corrupt database, unexpected
+            // schema — every failure mode here is an absent-optional-store result,
+            // never a thrown error that could fail the user's prompt.
+            return [];
+        }
+    },
+};

package/dist/src/knowledge/index.d.ts

@@ -0,0 +1,49 @@
+import type { Store, TaggedDoc } from './types.js';
+/**
+ * Loads and returns the three built-in stores. A function, not a static
+ * array: cq.ts, bd.ts, and claude-memory.ts are owned by other agents and may
+ * not exist yet, so the import must happen dynamically at call time (inside
+ * federateTags, via this function) rather than at module load — a top-level
+ * static import would fail this module's typecheck while they're mid-write.
+ * Each import is wrapped individually so one missing/broken store module
+ * leaves the other two available, per the "every store is optional" contract
+ * in types.ts.
+ */
+export declare function DEFAULT_STORES(): Promise<Store[]>;
+export type FederateOptions = {
+    projectRoot: string;
+    /** Stores to query. Defaults to all three (loaded dynamically). */
+    stores?: Store[];
+    /** Max hits one store may return for one document. Default 3. */
+    perStoreLimit?: number;
+    /** Max terms taken from one tag list. Default 2. */
+    maxTerms?: number;
+    /** Max documents that actually EMIT a block. Default 3. */
+    maxEmitted?: number;
+    /** Max documents a lookup is attempted for. Default 20. */
+    maxAttempts?: number;
+    /** Document ids already surfaced. Mutated as documents are emitted. */
+    seen?: Set<string>;
+    /**
+     * Document ids that were looked up on a previous call and came back
+     * empty. Distinct from `seen`: an entry here is never emitted, so it must
+     * stay retryable (a store may later have something to say), but it should
+     * not re-spend an attempt on every call — otherwise a batch of zero-yield
+     * documents ahead of an answerable one starves that document forever,
+     * since nothing about the situation changes between calls. Skipping an
+     * already-attempted-empty document for free lets the attempt budget
+     * advance past it on the next call, rotating the scan window forward.
+     * Mutated as documents come back empty; not persisted by this function.
+     */
+    attemptedEmpty?: Set<string>;
+    /** Max documents queried concurrently. Default 4. */
+    concurrency?: number;
+    /** Overall wall-clock budget for the whole call, in ms. Default 5000. */
+    deadlineMs?: number;
+};
+export declare function federateTags(docs: TaggedDoc[], opts: FederateOptions): Promise<string | null>;
+/**
+ * Tagged documents for the given project-relative markdown paths, in order,
+ * deduped by path.
+ */
+export declare function taggedDocsForFiles(projectRoot: string, filePaths: string[]): Promise<TaggedDoc[]>;

package/dist/src/knowledge/index.js

@@ -0,0 +1,271 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseFrontmatter } from '../lattice.js';
+import { UNTRUSTED_NOTICE, quoteUntrusted, cleanUntrustedId, } from '../untrusted.js';
+import { tagsToTerms, capHits } from './ranking.js';
+const STORE_GROUP_LABELS = {
+    cq: 'cq:',
+    bd: 'bd memories:',
+    'claude-memory': 'Claude Code memory:',
+};
+function storeExportName(name) {
+    switch (name) {
+        case 'cq':
+            return 'cqStore';
+        case 'bd':
+            return 'bdStore';
+        case 'claude-memory':
+            return 'claudeMemoryStore';
+    }
+}
+/**
+ * Loads and returns the three built-in stores. A function, not a static
+ * array: cq.ts, bd.ts, and claude-memory.ts are owned by other agents and may
+ * not exist yet, so the import must happen dynamically at call time (inside
+ * federateTags, via this function) rather than at module load — a top-level
+ * static import would fail this module's typecheck while they're mid-write.
+ * Each import is wrapped individually so one missing/broken store module
+ * leaves the other two available, per the "every store is optional" contract
+ * in types.ts.
+ */
+export async function DEFAULT_STORES() {
+    const stores = [];
+    const specs = [
+        { path: './cq.js', name: 'cq' },
+        { path: './bd.js', name: 'bd' },
+        { path: './claude-memory.js', name: 'claude-memory' },
+    ];
+    for (const spec of specs) {
+        try {
+            const mod = await import(spec.path);
+            const store = mod[storeExportName(spec.name)];
+            if (store && typeof store.query === 'function') {
+                stores.push(store);
+            }
+        }
+        catch {
+            // Absent module, missing binary, etc. — treated as "store not present".
+        }
+    }
+    return stores;
+}
+async function queryStore(store, terms, projectRoot, limit) {
+    try {
+        return await store.query({ terms, projectRoot, limit });
+    }
+    catch {
+        // A store must never throw per its contract, but a caller-injected fake
+        // in tests might — treat a rejection the same as an empty result so one
+        // misbehaving store can't take down federation for every document.
+        return [];
+    }
+}
+/**
+ * Resolve `promise`, or `null` if `ms` elapses first.
+ *
+ * The abandoned promise keeps running — an in-flight store query cannot be
+ * cancelled — but nothing awaits it, so it cannot hold the prompt open. The
+ * timer is unref'd so a pending race never keeps the process alive.
+ */
+function raceDeadline(promise, ms) {
+    if (ms <= 0)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(null), ms);
+        timer.unref?.();
+        const settle = (value) => {
+            clearTimeout(timer);
+            resolve(value);
+        };
+        promise.then(settle, () => settle(null));
+    });
+}
+export async function federateTags(docs, opts) {
+    const stores = opts.stores ?? (await DEFAULT_STORES());
+    const perStoreLimit = opts.perStoreLimit ?? 3;
+    const maxTerms = opts.maxTerms ?? 2;
+    const maxEmitted = opts.maxEmitted ?? 3;
+    const maxAttempts = opts.maxAttempts ?? 20;
+    const seen = opts.seen ?? new Set();
+    const attemptedEmpty = opts.attemptedEmpty ?? new Set();
+    const concurrency = Math.max(1, opts.concurrency ?? 4);
+    const deadlineAt = Date.now() + (opts.deadlineMs ?? 5000);
+    // A document with a hit is buffered here by its original index rather
+    // than accepted immediately: under concurrency, several documents can
+    // resolve with hits before any of them has been checked against
+    // maxEmitted, so acceptance is decided once, in document order, after all
+    // workers finish. That is what keeps the final `seen`/emitted count
+    // identical to the fully-sequential version — see the acceptance step
+    // below — even though the queries themselves now overlap.
+    const candidates = new Map();
+    let attempts = 0;
+    let cursor = 0;
+    // Each worker pulls the next document off a shared cursor and races the
+    // others via Promise.all below. Everything up to and including the
+    // `attempts++` happens synchronously (no `await` in between), so — since
+    // JS runs one microtask at a time — the cursor, the skip checks, and the
+    // attempt count advance in exactly the same document order and with
+    // exactly the same skip/spend decisions as the single-worker (fully
+    // sequential) version. Only the store queries themselves overlap.
+    //
+    // One divergence, deliberate and bounded: `candidates.size` is a soft
+    // stopping signal standing in for the true accepted count, which isn't
+    // known until the acceptance step below runs. Workers claim their next
+    // document before any in-flight query has resolved, so up to
+    // `concurrency - 1` documents beyond the maxEmitted cutoff can still be
+    // attempted. That never yields FEWER accepted blocks (accepted is always
+    // <= candidates.size), and anything it records is true — a document marked
+    // attemptedEmpty really was queried and really came back empty. It costs
+    // at most a few extra queries per call and rotates through the list
+    // slightly faster than the sequential version would.
+    async function worker() {
+        for (;;) {
+            if (candidates.size >= maxEmitted || attempts >= maxAttempts)
+                return;
+            if (Date.now() >= deadlineAt)
+                return;
+            const index = cursor;
+            if (index >= docs.length)
+                return;
+            cursor++;
+            const doc = docs[index];
+            // A skip does NOT spend an attempt: other documents later in this same
+            // batch may be new, and letting them slide into the attempt window as
+            // earlier ones are skipped is what keeps a repeated batch from
+            // starving documents that have never been looked up.
+            if (seen.has(doc.id))
+                continue;
+            // A previous call already spent an attempt on this document and found
+            // nothing. Skipping it for free (no attempt spent) lets the attempt
+            // budget reach further into the list on this call than it did last
+            // time, instead of re-spending the same budget on the same dead end.
+            if (attemptedEmpty.has(doc.id))
+                continue;
+            // Tags are only chosen; empty means nothing to search on. Also free —
+            // don't spend an attempt on a document with nothing to query.
+            const terms = tagsToTerms(doc.tags, maxTerms);
+            if (terms.length === 0)
+                continue;
+            attempts++;
+            // Never pool tags from two documents: each document is queried with
+            // only its own terms, because two unrelated subjects intersect at
+            // nothing and pooling would just produce noise attributed to the
+            // wrong document.
+            // The deadline has to bound total wall clock, not just dispatch. bd and
+            // claude-memory cap their own subprocess calls at CALL_TIMEOUT_MS, but
+            // cq's libsql `execute` carries no timeout of its own, so a locked
+            // database file would otherwise hold this worker — and the prompt —
+            // open with no bound at all. Racing the queries against the remaining
+            // budget is what makes the deadline hard rather than advisory: an
+            // overrunning store is abandoned, never awaited.
+            const results = await raceDeadline(Promise.allSettled(stores.map((store) => queryStore(store, terms, opts.projectRoot, perStoreLimit))), deadlineAt - Date.now());
+            // Deadline expired mid-query. Return what has been gathered. The
+            // document is deliberately NOT marked attemptedEmpty: it was never
+            // answered, so a later call must be free to try it again.
+            if (results === null)
+                return;
+            const hitsByStore = new Map();
+            for (let i = 0; i < stores.length; i++) {
+                const result = results[i];
+                const hits = result.status === 'fulfilled' ? result.value : [];
+                if (hits.length > 0) {
+                    hitsByStore.set(stores[i].name, hits);
+                }
+            }
+            if (hitsByStore.size === 0) {
+                // Nothing found: don't mark seen, don't count as emitted. A document
+                // that produced nothing stays unmarked so a later run — once the
+                // stores have something to say — can still surface it.
+                attemptedEmpty.add(doc.id);
+                continue;
+            }
+            candidates.set(index, { doc, hitsByStore });
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, docs.length) }, () => worker()));
+    // Accept candidates in document order, exactly as the sequential version
+    // would have, and only up to maxEmitted — this is what turns the soft,
+    // racy `candidates.size` stop above into an exact budget. A candidate
+    // beyond the cutoff is dropped: not marked seen, not counted, left
+    // exactly as untouched as a document the sequential version never reached.
+    const acceptedIndices = [...candidates.keys()]
+        .sort((a, b) => a - b)
+        .slice(0, maxEmitted);
+    const blocks = acceptedIndices.map((index) => {
+        const { doc, hitsByStore } = candidates.get(index);
+        seen.add(doc.id);
+        return formatDocBlock(doc, hitsByStore, perStoreLimit);
+    });
+    if (blocks.length === 0)
+        return null;
+    // UNTRUSTED_NOTICE appears exactly once, at the top of the whole result —
+    // never once per document.
+    return [
+        UNTRUSTED_NOTICE,
+        'Section tags matched stored knowledge (auto-searched, verify before trusting):',
+        '',
+        blocks.join('\n\n'),
+    ].join('\n');
+}
+function formatDocBlock(doc, hitsByStore, perStoreLimit) {
+    // The heading lists the document's WHOLE authored tag list, even though
+    // only the first two (maxTerms) drove the search — that keeps the heading
+    // honest about what the document is tagged with. doc.id and doc.tags come
+    // from repository frontmatter and are as untrusted as any hit text, so
+    // both go through cleanUntrustedId before joining.
+    const cleanId = cleanUntrustedId(doc.id);
+    const cleanTags = doc.tags.map((tag) => cleanUntrustedId(tag));
+    const lines = [`${cleanId} (${cleanTags.join(', ')}):`];
+    for (const [storeName, hits] of hitsByStore) {
+        const capped = capHits(hits, perStoreLimit);
+        const hitLines = [];
+        for (const hit of capped) {
+            const title = quoteUntrusted(hit.title, 200);
+            if (!hit.detail) {
+                // Omit a hit whose detail is empty rather than printing empty
+                // quotes; keep just the title.
+                hitLines.push(`- ${title}`);
+                continue;
+            }
+            const detail = quoteUntrusted(hit.detail, 220);
+            hitLines.push(`- ${title} -> ${detail}`);
+        }
+        if (hitLines.length === 0)
+            continue;
+        lines.push(STORE_GROUP_LABELS[storeName]);
+        lines.push(...hitLines);
+    }
+    return lines.join('\n');
+}
+/**
+ * Tagged documents for the given project-relative markdown paths, in order,
+ * deduped by path.
+ */
+export async function taggedDocsForFiles(projectRoot, filePaths) {
+    const docs = [];
+    const seenPaths = new Set();
+    for (const filePath of filePaths) {
+        const id = filePath.split('\\').join('/');
+        if (seenPaths.has(id))
+            continue;
+        seenPaths.add(id);
+        let content;
+        try {
+            content = await readFile(join(projectRoot, filePath), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const fm = parseFrontmatter(content);
+        const rawTags = fm.raw['tags'];
+        const tags = Array.isArray(rawTags)
+            ? rawTags.filter((t) => typeof t === 'string')
+            : typeof rawTags === 'string'
+                ? [rawTags]
+                : [];
+        if (tags.length === 0)
+            continue;
+        docs.push({ id, tags });
+    }
+    return docs;
+}

package/dist/src/knowledge/ranking.d.ts

@@ -0,0 +1,17 @@
+import type { KnowledgeHit } from './types.js';
+/**
+ * Turn a frontmatter `tags:` value into search terms.
+ *
+ * Two terms by default: each store call costs a subprocess or a query, and
+ * two terms is the least that still lets matched-term-count ranking mean
+ * anything (a hit that matched both terms outranks one that matched one).
+ */
+export declare function tagsToTerms(value: unknown, maxTerms?: number): string[];
+/**
+ * Stable sort by score, descending, then cap. Scores are only ever compared
+ * within one store's hits — a store that cannot attribute a match to
+ * individual terms and reports one flat score should never be capped
+ * alongside a store that scores per-term, so callers must call this once per
+ * store's hit list, not once over a merged list.
+ */
+export declare function capHits(hits: KnowledgeHit[], limit: number): KnowledgeHit[];