kibi-cli 2.36.0 → 2.39.0

package/dist/search-hints.js

@@ -0,0 +1,187 @@
+import { createHash } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { runtimeDirectory } from "./engine.js";
+import { NON_GOVERNING_STATUSES, queryGraphEdges, } from "./intent-search.js";
+import { composeSearchHints, } from "./plugins/compose-search-hints.js";
+import { isProvenanceStub } from "./provenance-stub.js";
+import { loadMarkdownBodySync } from "./search-ranking.js";
+import { tokenSourceHash } from "./search-token-cache.js";
+/**
+ * Below this top score a lexical answer is weak enough to show hints. On
+ * Kibi's own KB, 17 of 18 reworded questions the ranker got wrong scored
+ * below it, against 6 of 30 gold questions it got right. Host-owned, so no
+ * provider can move it.
+ */
+// implements REQ-kibi-search-hints-host
+export const SEARCH_HINT_WEAK_SCORE = 0.44;
+/** Requirements shown as hints. */
+// implements REQ-kibi-search-hints-host
+export const SEARCH_HINT_LIMIT = 10;
+/** Entities asked of the provider before they are lifted to requirements. */
+const PROVIDER_LIMIT = 20;
+/** Text a provider sees per entity: title, statement, then body. */
+const ENTITY_TEXT_CHARS = 2000;
+/** A provider's first call in a process may build its index. */
+const FIRST_CALL_TIMEOUT_MS = 3000;
+const WARM_CALL_TIMEOUT_MS = 500;
+/** Providers that answered once in this process; later calls get less time. */
+const warmedProviders = new WeakSet();
+/** Why a lexical answer needs hints, or null when it is strong enough. */
+// implements REQ-kibi-search-hints-host
+export function searchHintsTrigger(analysis) {
+    if (analysis.abstained || analysis.topScore === null)
+        return "abstained";
+    return analysis.topScore < SEARCH_HINT_WEAK_SCORE ? "weak" : null;
+}
+function isCurrent(entity) {
+    const status = String(entity.status).trim().toLowerCase();
+    return (!NON_GOVERNING_STATUSES.has(status) &&
+        status !== "closed" &&
+        !isProvenanceStub(entity));
+}
+function entityBody(entity, bodies, workspaceRoot) {
+    // The ranking may not have read every body; read the rest so an entity's
+    // text, and so its cached vector, never depends on the query.
+    const source = entity.source;
+    if (typeof source !== "string")
+        return "";
+    if (!bodies.has(source))
+        bodies.set(source, loadMarkdownBodySync(source, workspaceRoot));
+    return bodies.get(source);
+}
+function entityText(entity, bodies, workspaceRoot) {
+    return [
+        entity.title,
+        entity.semantic_text,
+        entityBody(entity, bodies, workspaceRoot),
+    ]
+        .filter((part) => typeof part === "string" && part !== "")
+        .join("\n")
+        .slice(0, ENTITY_TEXT_CHARS);
+}
+/** The current entities a provider may hint at, as the search loaded them. */
+// implements REQ-kibi-search-hints-host
+export function searchHintsEntities(entities, bodies, workspaceRoot) {
+    const seen = new Set();
+    const rows = [];
+    for (const entity of entities) {
+        const id = String(entity.id ?? "");
+        if (id === "" || seen.has(id) || !isCurrent(entity))
+            continue;
+        seen.add(id);
+        const text = entityText(entity, bodies, workspaceRoot);
+        rows.push({
+            id,
+            type: String(entity.type ?? ""),
+            title: String(entity.title ?? ""),
+            text,
+            hash: tokenSourceHash([text]),
+        });
+    }
+    return rows;
+}
+function cacheDirectory(workspaceRoot) {
+    const workspace = createHash("sha256")
+        .update(path.resolve(workspaceRoot))
+        .digest("hex")
+        .slice(0, 24);
+    const directory = path.join(runtimeDirectory(), `search-hints-${workspace}`);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    return directory;
+}
+/**
+ * A hint on a scenario, test, fact or ADR is shown as the current
+ * requirement it belongs to, so the agent re-asks about what governs; an
+ * entity no current requirement links to is shown as itself.
+ */
+async function liftToRequirements(prolog, hints, byId) {
+    const isRequirement = (id) => byId.get(id)?.type === "req";
+    const seeds = new Set(hints.map((hint) => hint.id).filter((id) => !isRequirement(id)));
+    const requirementsOf = new Map();
+    for (const edge of await queryGraphEdges(prolog, [...seeds]))
+        for (const [seed, other] of [
+            [edge.from, edge.to],
+            [edge.to, edge.from],
+        ])
+            if (seeds.has(seed) && isRequirement(other))
+                requirementsOf.set(seed, (requirementsOf.get(seed) ?? new Set()).add(other));
+    const items = [];
+    const shown = new Set();
+    for (const hint of hints) {
+        const linked = requirementsOf.get(hint.id);
+        for (const target of linked ? [...linked].sort() : [hint.id]) {
+            if (shown.has(target))
+                continue;
+            shown.add(target);
+            items.push({
+                id: target,
+                title: byId.get(target).title,
+                score: hint.score,
+                ...(target !== hint.id ? { via: hint.id } : {}),
+            });
+        }
+    }
+    return items;
+}
+/**
+ * Ask the configured kibi.search-hints.v1 provider which current entities a
+ * weakly answered question is probably about. Returns undefined when the
+ * answer is strong or no provider is configured. Hints never change the
+ * ranked results, the governing answer or abstention.
+ */
+// implements REQ-kibi-search-hints-host
+export async function buildSearchHints(options) {
+    const trigger = searchHintsTrigger(options.analysis);
+    if (trigger === null)
+        return undefined;
+    const { resolution } = options;
+    if (resolution.replace === null && resolution.shadow.length === 0)
+        return undefined;
+    const entities = searchHintsEntities(options.entities, options.bodies, options.workspaceRoot);
+    if (entities.length === 0)
+        return undefined;
+    const composed = await composeSearchHints(resolution, {
+        query: options.query,
+        limit: PROVIDER_LIMIT,
+        entities,
+        cacheDirectory: cacheDirectory(options.workspaceRoot),
+    }, {
+        operationName: "kb_search",
+        timeoutMs: (binding) => warmedProviders.has(binding.capability)
+            ? WARM_CALL_TIMEOUT_MS
+            : FIRST_CALL_TIMEOUT_MS,
+    });
+    for (const binding of [resolution.replace, ...resolution.shadow])
+        if (binding)
+            warmedProviders.add(binding.capability);
+    const byId = new Map(entities.map((entity) => [entity.id, entity]));
+    const answered = new Set(options.governingIds.slice(0, 3));
+    const items = (await liftToRequirements(options.prolog, composed.hints, byId))
+        .filter((item) => !answered.has(item.id))
+        .slice(0, SEARCH_HINT_LIMIT);
+    const shadow = composed.shadowComparisons.map((comparison) => ({
+        provider: comparison.stamp,
+        items: comparison.hints,
+    }));
+    return {
+        trigger,
+        provider: composed.stamp,
+        items,
+        ...(shadow.length > 0 ? { shadow } : {}),
+        ...(composed.diagnostics.length > 0
+            ? { diagnostics: composed.diagnostics }
+            : {}),
+    };
+}
+/** The sentence a search answer's text adds when hints are shown. */
+// implements REQ-kibi-search-hints-host
+export function searchHintsNote(hints) {
+    if (hints === undefined || hints.items.length === 0)
+        return "";
+    const named = hints.items
+        .slice(0, 5)
+        .map((item) => `${item.title} (${item.id})`)
+        .join("; ");
+    return ` The lexical answer is weak; by meaning the KB may describe this as: ${named}. Re-ask in those words or pass them as semanticFacets.aliases, then read the governing requirement with kb_query. Hints are suggestions, not governing requirements.`;
+}

package/dist/search-ranking.d.ts

@@ -6,5 +6,12 @@ export interface SearchMatch {
 }
 export declare function rankEntities(entities: Record<string, unknown>[], query: string, workspaceRoot: string): Promise<SearchMatch[]>;
 export declare function loadMarkdownBody(source: string, workspaceRoot: string): Promise<string | null>;
+/**
+ * loadMarkdownBody, reading synchronously. Search reads the bodies of
+ * thousands of candidates at once; each asynchronous read is four thread-pool
+ * round trips (open, stat, read, close), which made reading them take ten
+ * times as long as reading them in turn.
+ */
+export declare function loadMarkdownBodySync(source: string, workspaceRoot: string): string | null;
 export declare function snippetFromMatchedLine(matchedLine: string | undefined): string | undefined;
 //# sourceMappingURL=search-ranking.d.ts.map

package/dist/search-ranking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-ranking.d.ts","sourceRoot":"","sources":["../src/search-ranking.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAgDD,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACnC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,EAAE,CAAC,CAqCxB;AAsGD,wBAAsB,gBAAgB,CAEpC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA6BxB;AA0JD,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,GAAG,SAAS,CAQpB"}
+{"version":3,"file":"search-ranking.d.ts","sourceRoot":"","sources":["../src/search-ranking.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAiDD,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACnC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,EAAE,CAAC,CAmCxB;AAsGD,wBAAsB,gBAAgB,CAEpC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB;AAED;;;;;GAKG;AAEH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,MAAM,GAAG,IAAI,CAQf;AA4ID,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,GAAG,SAAS,CAQpB"}

package/dist/search-ranking.js

@@ -1,3 +1,4 @@
+import syncFs from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { bodySnippetLine } from "./entity-body-context.js";
@@ -38,9 +39,8 @@ const SEARCH_STOP_WORDS = new Set([
 // implements REQ-mcp-search-discovery, REQ-002, REQ-003, REQ-bootstrap-provenance-stubs
 export async function rankEntities(entities, query, workspaceRoot) {
     const queryContext = buildSearchQueryContext(query);
-    if (!queryContext.rawTrimmedQuery || queryContext.signalTokens.length === 0) {
+    if (queryContext.signalTokens.length === 0)
         return [];
-    }
     const matches = [];
     for (const entity of entities) {
         const match = await rankEntity(entity, queryContext, workspaceRoot);
@@ -82,8 +82,8 @@ async function rankEntity(entity, queryContext, workspaceRoot) {
     const tags = Array.isArray(entity.tags)
         ? entity.tags.map((tag) => String(tag))
         : [];
-    const titleForms = buildSearchTextForms(title);
-    const idForms = buildSearchTextForms(id);
+    const titleForms = searchText(title);
+    const idForms = searchText(id);
     if (isExactSearchMatch(titleForms, queryContext.phrase)) {
         score += 100;
         reasons.push("exact title match");
@@ -101,12 +101,12 @@ async function rankEntity(entity, queryContext, workspaceRoot) {
         reasons.push("ID match");
     }
     const metadataFields = [type, source, owner, priority, severity];
-    const metadataMatched = metadataFields.some((field) => isPhraseSearchMatch(buildSearchTextForms(field), queryContext.phrase));
+    const metadataMatched = metadataFields.some((field) => isPhraseSearchMatch(searchText(field), queryContext.phrase));
     if (metadataMatched) {
         score += 20;
         reasons.push("metadata match");
     }
-    const matchingTags = tags.filter((tag) => isPhraseSearchMatch(buildSearchTextForms(tag), queryContext.phrase));
+    const matchingTags = tags.filter((tag) => isPhraseSearchMatch(searchText(tag), queryContext.phrase));
     if (matchingTags.length > 0) {
         score += 30;
         reasons.push("tag match");
@@ -120,7 +120,7 @@ async function rankEntity(entity, queryContext, workspaceRoot) {
         getInlineBodyText(entity);
     let snippet;
     if (bodyText) {
-        const bodyForms = buildSearchTextForms(bodyText);
+        const bodyForms = searchText(bodyText);
         if (isPhraseSearchMatch(bodyForms, queryContext.phrase)) {
             score += 15;
             reasons.push("markdown body match");
@@ -148,10 +148,37 @@ async function rankEntity(entity, queryContext, workspaceRoot) {
 export async function loadMarkdownBody(
 // implements REQ-007, REQ-mcp-search-discovery
 source, workspaceRoot) {
-    if (!source) {
+    const resolved = markdownBodyPath(source, workspaceRoot);
+    if (resolved === null)
+        return null;
+    try {
+        const fileContent = await fs.readFile(resolved, "utf8");
+        return stripFrontmatter(fileContent);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * loadMarkdownBody, reading synchronously. Search reads the bodies of
+ * thousands of candidates at once; each asynchronous read is four thread-pool
+ * round trips (open, stat, read, close), which made reading them take ten
+ * times as long as reading them in turn.
+ */
+// implements REQ-mcp-search-discovery
+export function loadMarkdownBodySync(source, workspaceRoot) {
+    const resolved = markdownBodyPath(source, workspaceRoot);
+    if (resolved === null)
+        return null;
+    try {
+        return stripFrontmatter(syncFs.readFileSync(resolved, "utf8"));
+    }
+    catch {
         return null;
     }
-    const normalizedSource = source.split("#", 1)[0]?.trim() ?? "";
+}
+function markdownBodyPath(source, workspaceRoot) {
+    const normalizedSource = source.replace(/#.*/, "").trim();
     if (!normalizedSource.endsWith(".md")) {
         return null;
     }
@@ -164,21 +191,13 @@ source, workspaceRoot) {
     if (!resolved.startsWith(normalizedRoot + path.sep)) {
         return null;
     }
-    try {
-        const fileContent = await fs.readFile(resolved, "utf8");
-        return stripFrontmatter(fileContent);
-    }
-    catch {
-        return null;
-    }
+    return resolved;
 }
 // implements REQ-mcp-search-discovery
 function stripFrontmatter(content) {
     const trimmedContent = content.trimStart();
-    if (!trimmedContent.startsWith("---")) {
-        return content;
-    }
-    const openingDelimiter = /^---[^\S\r\n]*(?:\r?\n|$)/.exec(trimmedContent);
+    // A delimiter at the very end leaves no room for a closing one.
+    const openingDelimiter = /^---[^\S\r\n]*\r?\n/.exec(trimmedContent);
     if (!openingDelimiter) {
         return content;
     }
@@ -193,37 +212,17 @@ function stripFrontmatter(content) {
 // implements REQ-mcp-search-discovery
 function buildSearchQueryContext(query) {
     return {
-        phrase: buildSearchTextForms(query),
-        signalTokens: tokenizeSignalTerms(query),
-        rawTrimmedQuery: query.trim(),
+        phrase: searchText(query),
+        signalTokens: Array.from(new Set(searchTokens(query).filter((token) => !SEARCH_STOP_WORDS.has(token)))),
     };
 }
 // implements REQ-mcp-search-discovery
-function buildSearchTextForms(value) {
-    const normalized = normalizeSearchText(value);
-    return {
-        normalized,
-        compact: normalized.replace(/\s+/g, ""),
-    };
+function searchTokens(value) {
+    return Array.from(value.toLowerCase().matchAll(/[a-z0-9]+/g), (match) => singularizeSimplePlural(match[0]));
 }
 // implements REQ-mcp-search-discovery
-function normalizeSearchText(value) {
-    return value
-        .trim()
-        .toLowerCase()
-        .replace(/[-_]+/g, " ")
-        .replace(/[^a-z0-9\s]+/g, " ")
-        .trim()
-        .split(/\s+/)
-        .filter(Boolean)
-        .map(singularizeSimplePlural)
-        .join(" ");
-}
-// implements REQ-mcp-search-discovery
-function tokenizeSignalTerms(value) {
-    return Array.from(new Set(normalizeSearchText(value)
-        .split(/\s+/)
-        .filter((token) => token && !SEARCH_STOP_WORDS.has(token))));
+function searchText(value) {
+    return searchTokens(value).join("");
 }
 // implements REQ-mcp-search-discovery
 function singularizeSimplePlural(token) {
@@ -237,18 +236,19 @@ function singularizeSimplePlural(token) {
     return token.slice(0, -1);
 }
 // implements REQ-mcp-search-discovery
+// implements REQ-mcp-search-discovery
+// The query phrase is never empty: a query without signal tokens ranks
+// nothing.
 function isExactSearchMatch(haystack, needle) {
-    return (haystack.normalized === needle.normalized ||
-        (needle.compact !== "" && haystack.compact === needle.compact));
+    return haystack === needle;
 }
 // implements REQ-mcp-search-discovery
 function isPhraseSearchMatch(haystack, needle) {
-    return (haystack.normalized.includes(needle.normalized) ||
-        (needle.compact !== "" && haystack.compact.includes(needle.compact)));
+    return haystack.includes(needle);
 }
 // implements REQ-mcp-search-discovery
 function countTokenMatches(haystack, tokens) {
-    return tokens.filter((token) => haystack.normalized.includes(token) || haystack.compact.includes(token)).length;
+    return tokens.filter((token) => haystack.includes(token)).length;
 }
 // implements REQ-mcp-search-discovery
 function getInlineBodyText(entity) {
@@ -267,13 +267,11 @@ function getInlineBodyText(entity) {
 }
 // implements REQ-mcp-search-discovery
 function buildSnippet(bodyText, queryForms, entity) {
-    const lines = bodyText
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .filter(Boolean);
+    const lines = bodyText.split(/\r?\n/).map((line) => line.trim());
     // The line that matches the query wins; otherwise the context prose, then
     // the first line.
-    const matchedLine = lines.find((line) => isPhraseSearchMatch(buildSearchTextForms(line), queryForms)) ?? bodySnippetLine(String(entity.type ?? ""), bodyText, entity);
+    const matchedLine = lines.find((line) => isPhraseSearchMatch(searchText(line), queryForms)) ??
+        bodySnippetLine(String(entity.type), bodyText, entity);
     return snippetFromMatchedLine(matchedLine);
 }
 export function snippetFromMatchedLine(matchedLine) {

package/dist/search-token-cache.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Entity tokens kept between searches. Every kb_search ranks nearly the whole
+ * KB, and each CLI call is a new process, so tokenizing every candidate again
+ * was most of a warm search. Each entry is keyed by entity and carries a hash
+ * of the text it was computed from, so an edited entity or body is
+ * tokenized again; the file also names the tokenizer it was built with, so a
+ * changed tokenizer starts an empty cache.
+ */
+export type CachedEntityTokens = Readonly<{
+    title: readonly string[];
+    metadata: readonly string[];
+    bodyTokens: readonly string[];
+    document: readonly string[];
+}>;
+/** Set to 0 to tokenize every search from scratch. */
+export declare const KIBI_SEARCH_TOKEN_CACHE_ENV = "KIBI_SEARCH_TOKEN_CACHE";
+export type SearchTokenCache = {
+    get(key: string, hash: string): CachedEntityTokens | undefined;
+    set(key: string, hash: string, tokens: CachedEntityTokens): void;
+    save(): void;
+};
+/** The hash an entry is checked against: every text its tokens come from. */
+export declare function tokenSourceHash(parts: readonly string[]): string;
+/**
+ * The token cache for `workspaceRoot`, built by `tokenizer` (a fingerprint
+ * of the tokenizing code). A cache that cannot be read starts empty and one
+ * that cannot be written is skipped: the cache only saves time.
+ */
+export declare function openSearchTokenCache(workspaceRoot: string, tokenizer: string): SearchTokenCache;
+//# sourceMappingURL=search-token-cache.d.ts.map

package/dist/search-token-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-token-cache.d.ts","sourceRoot":"","sources":["../src/search-token-cache.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AAGH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B,CAAC,CAAC;AAaH,sDAAsD;AACtD,eAAO,MAAM,2BAA2B,4BAA4B,CAAC;AAErE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAC;IAC/D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACjE,IAAI,IAAI,IAAI,CAAC;CACd,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEhE;AA2BD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAyClB"}

package/dist/search-token-cache.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { runtimeDirectory } from "./engine.js";
+/** Entries a cache file keeps; enough for a few branches of a large KB. */
+const MAX_ENTRIES = 50_000;
+/** Set to 0 to tokenize every search from scratch. */
+export const KIBI_SEARCH_TOKEN_CACHE_ENV = "KIBI_SEARCH_TOKEN_CACHE";
+/** The hash an entry is checked against: every text its tokens come from. */
+export function tokenSourceHash(parts) {
+    return createHash("sha1").update(JSON.stringify(parts)).digest("base64");
+}
+function cacheFile(workspaceRoot) {
+    const workspace = createHash("sha256")
+        .update(path.resolve(workspaceRoot))
+        .digest("hex")
+        .slice(0, 24);
+    return path.join(runtimeDirectory(), `search-tokens-${workspace}.json`);
+}
+function readCache(file, tokenizer) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (parsed.version !== 1 || parsed.tokenizer !== tokenizer)
+            return new Map();
+        return new Map(Object.entries(parsed.entries));
+    }
+    catch {
+        return new Map();
+    }
+}
+const NO_CACHE = {
+    get: () => undefined,
+    set: () => { },
+    save: () => { },
+};
+/**
+ * The token cache for `workspaceRoot`, built by `tokenizer` (a fingerprint
+ * of the tokenizing code). A cache that cannot be read starts empty and one
+ * that cannot be written is skipped: the cache only saves time.
+ */
+export function openSearchTokenCache(workspaceRoot, tokenizer) {
+    if (process.env[KIBI_SEARCH_TOKEN_CACHE_ENV] === "0")
+        return NO_CACHE;
+    let file;
+    try {
+        file = cacheFile(workspaceRoot);
+    }
+    catch {
+        return NO_CACHE;
+    }
+    const entries = readCache(file, tokenizer);
+    let dirty = false;
+    return {
+        get(key, hash) {
+            const entry = entries.get(key);
+            return entry !== undefined && entry.hash === hash ? entry : undefined;
+        },
+        set(key, hash, tokens) {
+            entries.delete(key);
+            entries.set(key, { hash, ...tokens });
+            dirty = true;
+        },
+        save() {
+            if (!dirty)
+                return;
+            dirty = false;
+            // Map order is insertion order and set() re-inserts, so the oldest
+            // entries are the ones dropped.
+            const kept = [...entries].slice(-MAX_ENTRIES);
+            const body = {
+                version: 1,
+                tokenizer,
+                entries: Object.fromEntries(kept),
+            };
+            const temporary = `${file}.${process.pid}.tmp`;
+            try {
+                writeFileSync(temporary, JSON.stringify(body), { mode: 0o600 });
+                renameSync(temporary, file);
+            }
+            catch {
+                // A runtime directory that is full or read-only only costs speed.
+                rmSync(temporary, { force: true });
+            }
+        },
+    };
+}

package/dist/traceability/impact-knowledge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"impact-knowledge.d.ts","sourceRoot":"","sources":["../../src/traceability/impact-knowledge.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EACL,KAAK,WAAW,EAIjB,MAAM,oBAAoB,CAAC;AAI5B,4EAA4E;AAE5E,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AAqFH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,yDAAoE,GAC5E,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAyCxB;AAGD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,GACX,WAAW,CAiBb;AAGD,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,GACnC,WAAW,CAoBb;AAGD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,EACpC,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,MAAM,EAAE,CAsBV;AAeD,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,GACX,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAiBxB"}
+{"version":3,"file":"impact-knowledge.d.ts","sourceRoot":"","sources":["../../src/traceability/impact-knowledge.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EACL,KAAK,WAAW,EAIjB,MAAM,oBAAoB,CAAC;AAI5B,4EAA4E;AAE5E,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AAuFH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,yDAAoE,GAC5E,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAyCxB;AAGD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,GACX,WAAW,CAiBb;AAGD,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,GACnC,WAAW,CAoBb;AAGD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,EACpC,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,MAAM,EAAE,CAsBV;AAeD,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,GACX,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAiBxB"}

package/dist/traceability/impact-knowledge.js

@@ -39,6 +39,8 @@ function semanticEntityFingerprint(result) {
             "required_evidence",
             "approved_by",
             "approval_ref",
+            "failure_side_waiver",
+            "failure_side_waiver_approved_by",
             "exempts_claims",
             "proof_contract",
             "proof_bindings",

package/dist/traceability/temp-kb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-kb.d.ts","sourceRoot":"","sources":["../../src/traceability/temp-kb.ts"],"names":[],"mappings":"AAMA,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAET;AACD,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;CACvB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CASvC;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAE/B,OAAO,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAA;CAAE,KAAK,aAAa,GACpE,IAAI,CAEN;AA+RD,iBAAe,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB/D;AAED,OAAO,EAAE,cAAc,EAAE,CAAC;AAe1B,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CA4Df;AAED,wBAAsB,YAAY,CAChC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,aAAa,CAAC,CA+CxB;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAkBrE;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BlE"}
+{"version":3,"file":"temp-kb.d.ts","sourceRoot":"","sources":["../../src/traceability/temp-kb.ts"],"names":[],"mappings":"AAMA,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAET;AACD,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;CACvB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CASvC;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAE/B,OAAO,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAA;CAAE,KAAK,aAAa,GACpE,IAAI,CAEN;AAySD,iBAAe,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB/D;AAED,OAAO,EAAE,cAAc,EAAE,CAAC;AAe1B,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CA4Df;AAED,wBAAsB,YAAY,CAChC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,aAAa,CAAC,CA+CxB;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAkBrE;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BlE"}

package/dist/traceability/temp-kb.js

@@ -55,6 +55,10 @@ const FACT_STRING_FIELDS = new Set([
     "canonical_key",
     "claim_key",
     "claim_text",
+    "dimension_waiver",
+    "dimension_waiver_approved_by",
+    "case_waiver",
+    "case_waiver_approved_by",
     "predicate_name",
     "predicate_namespace",
     "rule_hash",
@@ -187,7 +191,13 @@ function buildEntityAssertionGoal(entity, sourceFile) {
     if (entity.type === "req" && entity.semantic_inventory) {
         props.push(`semantic_inventory=${toPrologString(JSON.stringify(entity.semantic_inventory))}`);
     }
-    for (const field of ["approved_by", "approval_ref", "rationale"]) {
+    for (const field of [
+        "approved_by",
+        "approval_ref",
+        "failure_side_waiver",
+        "failure_side_waiver_approved_by",
+        "rationale",
+    ]) {
         const value = entity.type === "req" ? entity[field] : undefined;
         if (value !== undefined)
             props.push(`${field}=${toPrologString(value)}`);

package/dist/types/entities.d.ts

@@ -37,6 +37,14 @@ export interface FactFields {
     canonical_key?: string;
     claim_key?: string;
     claim_text?: string;
+    /** Why a quantifier word in claim_text ranges over nothing. */
+    dimension_waiver?: string;
+    /** The person who accepted the dimension waiver. */
+    dimension_waiver_approved_by?: string;
+    /** Why the fact's derived edge cases are covered some other way. */
+    case_waiver?: string;
+    /** The person who accepted the case waiver. */
+    case_waiver_approved_by?: string;
     predicate_name?: string;
     predicate_namespace?: string;
     predicate_arity?: number;
@@ -66,6 +74,10 @@ export type Requirement = BaseEntity & {
     approved_by?: string;
     /** Optional reference to the approval decision record. */
     approval_ref?: string;
+    /** Why the requirement has no failure side to test. */
+    failure_side_waiver?: string;
+    /** The person who accepted the failure-side waiver. */
+    failure_side_waiver_approved_by?: string;
     /** Why the requirement exists; explanation, not checked meaning. */
     rationale?: string;
     /** How firmly it was decided; absent reads as `default` when an agent wrote it, else `firm`. */

package/dist/types/entities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/types/entities.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAGD,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,EACN,SAAS,GACT,gBAAgB,GAChB,aAAa,GACb,MAAM,GACN,kBAAkB,GAClB,WAAW,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EACL,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,KAAK,GACL,SAAS,GACT,UAAU,GACV,WAAW,GACX,UAAU,CAAC;IACf,UAAU,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9C,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,kBAAkB,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,YAAY,CAAC;IAC3D,wBAAwB,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACnD,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,cAAc,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,cAAc,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC1C;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG;IACrC,IAAI,EAAE,KAAK,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC;IAC9C,gGAAgG;IAChG,iBAAiB,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC;IACpE,qFAAqF;IACrF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AACF,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AACzD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,sBAAsB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAChF,MAAM,MAAM,GAAG,GAAG,UAAU,GAAG;IAC7B,IAAI,EAAE,KAAK,CAAC;IACZ,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC;CAC/C,CAAC;AACF,MAAM,MAAM,IAAI,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AACjD,MAAM,MAAM,KAAK,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AACnD,MAAM,MAAM,MAAM,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AACrD,MAAM,MAAM,IAAI,GAAG,UAAU,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9D,MAAM,MAAM,MAAM,GACd,WAAW,GACX,QAAQ,GACR,UAAU,GACV,GAAG,GACH,IAAI,GACJ,KAAK,GACL,MAAM,GACN,IAAI,CAAC"}
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/types/entities.ts"],"names":[],"mappings":"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"}

package/dist/usage-telemetry.d.ts

@@ -0,0 +1,20 @@
+import type { Command } from "commander";
+/**
+ * Name why this command failed with a fixed identifier (an error code, a
+ * failing doctor check), for the event recorded at exit. The first note wins.
+ */
+export declare function noteCliErrorCategory(category: string | undefined): void;
+/** The error code of a failed JSON result printed by a command, if any. */
+export declare function noteCliResultError(stdout: string | undefined): void;
+/** Remember which registered command ran, for the event recorded at exit. */
+export declare function trackCommandPath(program: Command): () => string | undefined;
+export declare function finishCliTelemetry(input: {
+    readonly commandPath: string | undefined;
+    readonly packageVersion: string;
+    readonly startedAt: Date;
+    readonly exitCode: number;
+    /** The error the command threw, when it failed by throwing. */
+    readonly error?: unknown;
+    readonly env?: NodeJS.ProcessEnv;
+}): Promise<void>;
+//# sourceMappingURL=usage-telemetry.d.ts.map

package/dist/usage-telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-telemetry.d.ts","sourceRoot":"","sources":["../src/usage-telemetry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBzC;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAIvE;AAGD,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAanE;AAgBD,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,MAAM,GAAG,SAAS,CAc3E;AAGD,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC,GAAG,OAAO,CAAC,IAAI,CAAC,CAkChB"}