@shrkcrft/inspector 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/search-document-id.js

@@ -0,0 +1,72 @@
+/**
+ * One row per prefix. `Record<SearchDocumentPrefix, …>` makes a prefix added
+ * to the type without a row here a compile error.
+ */
+const PREFIXES = Object.freeze({
+    knowledge: { referenceKind: 'knowledge', searchKind: 'knowledge' },
+    rule: { referenceKind: 'rule', searchKind: 'rule' },
+    path: { referenceKind: 'path-convention', searchKind: 'path' },
+    template: { referenceKind: 'template', searchKind: 'template' },
+    pipeline: { referenceKind: 'pipeline', searchKind: 'pipeline' },
+    boundary: { referenceKind: 'boundary-rule', searchKind: 'boundary' },
+    construct: { referenceKind: 'construct', searchKind: 'construct' },
+    playbook: { referenceKind: 'playbook', searchKind: 'playbook' },
+    // No id registry: presets, packs, bundles, sessions, construct facets and
+    // docs are indexed, but nothing answers "does this id exist?" for them, so a
+    // key naming one is UNVERIFIED — never "missing".
+    preset: { referenceKind: null, searchKind: 'preset' },
+    pack: { referenceKind: null, searchKind: 'pack' },
+    bundle: { referenceKind: null, searchKind: 'bundle' },
+    session: { referenceKind: null, searchKind: 'session' },
+    facet: { referenceKind: null, searchKind: 'construct-facet' },
+    doc: { referenceKind: null, searchKind: 'doc' },
+});
+/** Every search-document prefix, in declaration order. */
+export const SEARCH_DOCUMENT_PREFIXES = Object.freeze(Object.keys(PREFIXES));
+/** Prefix → the id registry its ids resolve against (`null` = none). */
+export const SEARCH_DOCUMENT_ID_KINDS = Object.freeze(Object.fromEntries(SEARCH_DOCUMENT_PREFIXES.map((p) => [p, PREFIXES[p].referenceKind])));
+/** `searchDocumentId('knowledge', 'auth.login')` → `knowledge:auth.login`. */
+export function searchDocumentId(prefix, id) {
+    return `${prefix}:${id}`;
+}
+/**
+ * `<prefix>:<id>` → `{ prefix, id }`, split on the FIRST `:`. `null` when the
+ * key has no `:` or either side is empty. The prefix is NOT validated — pair
+ * with {@link isSearchDocumentPrefix}.
+ */
+export function parseSearchDocumentId(key) {
+    const at = key.indexOf(':');
+    if (at <= 0 || at === key.length - 1)
+        return null;
+    return { prefix: key.slice(0, at), id: key.slice(at + 1) };
+}
+/** True when `prefix` is one `buildSearchIndex` emits. */
+export function isSearchDocumentPrefix(prefix) {
+    return Object.prototype.hasOwnProperty.call(PREFIXES, prefix);
+}
+/** The `SearchKind` value the prefix's documents carry, or `undefined`. */
+export function searchKindForPrefix(prefix) {
+    return isSearchDocumentPrefix(prefix) ? PREFIXES[prefix].searchKind : undefined;
+}
+/** The prefix whose documents carry `searchKind` (`construct-facet` → `facet`). */
+export function searchDocumentPrefixForKind(searchKind) {
+    return SEARCH_DOCUMENT_PREFIXES.find((p) => PREFIXES[p].searchKind === searchKind);
+}
+/** The prefix whose ids live in `kind`'s registry (`path-convention` → `path`). */
+export function searchDocumentPrefixForReferenceKind(kind) {
+    return SEARCH_DOCUMENT_PREFIXES.find((p) => PREFIXES[p].referenceKind === kind);
+}
+/**
+ * The registry entry a search-document id names: `knowledge:gamma.entry` →
+ * `{ referenceKind: 'knowledge', id: 'gamma.entry' }`. `undefined` when the id
+ * does not parse, its prefix is not one the index emits, or its prefix has no
+ * id registry (`doc:`, `preset:`, `facet:`, …) — such a document exists, but
+ * no registry can be asked about it.
+ */
+export function searchDocumentReference(docId) {
+    const parsed = parseSearchDocumentId(docId);
+    if (!parsed || !isSearchDocumentPrefix(parsed.prefix))
+        return undefined;
+    const referenceKind = PREFIXES[parsed.prefix].referenceKind;
+    return referenceKind === null ? undefined : { referenceKind, id: parsed.id };
+}

package/dist/search-document-prefix.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Every `<prefix>` a search-document id (`<prefix>:<id>`) can carry — exactly
+ * the prefixes `buildSearchIndex` emits. See `search-document-id.ts`, the one
+ * codec for the format.
+ */
+export type SearchDocumentPrefix = 'knowledge' | 'rule' | 'path' | 'template' | 'pipeline' | 'preset' | 'pack' | 'boundary' | 'bundle' | 'session' | 'construct' | 'facet' | 'playbook' | 'doc';
+//# sourceMappingURL=search-document-prefix.d.ts.map

package/dist/search-document-prefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-document-prefix.d.ts","sourceRoot":"","sources":["../src/search-document-prefix.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAC5B,WAAW,GACX,MAAM,GACN,MAAM,GACN,UAAU,GACV,UAAU,GACV,QAAQ,GACR,MAAM,GACN,UAAU,GACV,QAAQ,GACR,SAAS,GACT,WAAW,GACX,OAAO,GACP,UAAU,GACV,KAAK,CAAC"}

package/dist/search-document-prefix.js

@@ -0,0 +1 @@
+export {};

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

@@ -1 +1 @@
-{"version":3,"file":"search-index.d.ts","sourceRoot":"","sources":["../src/search-index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAKvE,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,6BAA6B,CAAC;AAErC,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAEhE,oBAAY,UAAU;IACpB,SAAS,cAAc;IACvB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,GAAG,QAAQ;IACX,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,SAAS,cAAc;IACvB,cAAc,oBAAoB;IAClC,QAAQ,aAAa;IACrB,eAAe,qBAAqB;IACpC,OAAO,YAAY;CACpB;AAED,oBAAY,YAAY;IACtB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,GAAG,QAAQ;CACZ;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC;IACpD,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9B,qCAAqC;IACrC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;IAC5B,OAAO,EAAE,WAAW,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC,CAAC;CACzD;AA0FD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,qBAAqB,GAAG,eAAe,EAAE,CAgOrF;AAmHD,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,qBAAqB,GACjC,aAAa,CA2Df;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAe9D"}
+{"version":3,"file":"search-index.d.ts","sourceRoot":"","sources":["../src/search-index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAKvE,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,6BAA6B,CAAC;AAIrC,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAEhE,oBAAY,UAAU;IACpB,SAAS,cAAc;IACvB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,GAAG,QAAQ;IACX,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,SAAS,cAAc;IACvB,cAAc,oBAAoB;IAClC,QAAQ,aAAa;IACrB,eAAe,qBAAqB;IACpC,OAAO,YAAY;CACpB;AAED,oBAAY,YAAY;IACtB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,GAAG,QAAQ;CACZ;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC;IACpD,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9B,qCAAqC;IACrC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;IAC5B,OAAO,EAAE,WAAW,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC,CAAC;CACzD;AA0FD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,qBAAqB,GAAG,eAAe,EAAE,CAyNrF;AAmHD,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,qBAAqB,GACjC,aAAa,CA8Df;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAe9D"}

package/dist/search-index.js

@@ -5,6 +5,8 @@ import { listDevSessionsDetailed } from "./dev-session.js";
 import { listConstructs } from "./construct-registry.js";
 import { listPlaybooks } from "./playbook-registry.js";
 import { listSearchTuning, tuningBoostFor, } from "./search-tuning-registry.js";
+import { searchDocumentId } from "./search-document-id.js";
+import { tuningQueryTokens } from "./tuning-query-tokens.js";
 export const SEARCH_INDEX_SCHEMA = 'sharkcraft.search-index/v1';
 export var SearchKind;
 (function (SearchKind) {
@@ -111,7 +113,7 @@ function loadDocFiles(projectRoot) {
             const titleMatch = /^#\s+(.+)/m.exec(content);
             const title = titleMatch?.[1]?.trim() ?? f.replace(/\.md$/, '');
             out.push({
-                id: `doc:${f}`,
+                id: searchDocumentId('doc', f),
                 kind: SearchKind.Doc,
                 title,
                 content: safeContent(content, 1200),
@@ -130,7 +132,7 @@ export function buildSearchIndex(inspection) {
     for (const k of inspection.knowledgeEntries) {
         const src = inspection.entrySources.get(k.id);
         docs.push({
-            id: `knowledge:${k.id}`,
+            id: searchDocumentId('knowledge', k.id),
             kind: SearchKind.Knowledge,
             title: k.title ?? k.id,
             content: safeContent([k.summary ?? '', k.content ?? ''].filter(Boolean).join('\n\n'), 1200),
@@ -144,7 +146,7 @@ export function buildSearchIndex(inspection) {
     }
     for (const r of inspection.ruleService.list()) {
         docs.push({
-            id: `rule:${r.id}`,
+            id: searchDocumentId('rule', r.id),
             kind: SearchKind.Rule,
             title: r.title ?? r.id,
             content: safeContent(r.summary ?? r.content ?? '', 800),
@@ -163,7 +165,7 @@ export function buildSearchIndex(inspection) {
     for (const p of inspection.pathService.list()) {
         const meta = (p.metadata ?? {});
         docs.push({
-            id: `path:${p.id}`,
+            id: searchDocumentId('path', p.id),
             kind: SearchKind.Path,
             title: p.title ?? p.id,
             content: safeContent(meta.description ?? p.summary ?? p.content ?? '', 400),
@@ -179,7 +181,7 @@ export function buildSearchIndex(inspection) {
     for (const t of inspection.templateRegistry.list()) {
         const src = inspection.templateSources.get(t.id);
         docs.push({
-            id: `template:${t.id}`,
+            id: searchDocumentId('template', t.id),
             kind: SearchKind.Template,
             title: t.name ?? t.id,
             content: safeContent(t.description ?? '', 800),
@@ -194,7 +196,7 @@ export function buildSearchIndex(inspection) {
     for (const p of inspection.pipelineRegistry.list()) {
         const src = inspection.pipelineSources.get(p.id);
         docs.push({
-            id: `pipeline:${p.id}`,
+            id: searchDocumentId('pipeline', p.id),
             kind: SearchKind.Pipeline,
             title: p.title ?? p.id,
             content: safeContent(p.description ?? '', 800),
@@ -210,7 +212,7 @@ export function buildSearchIndex(inspection) {
         for (const p of presets) {
             const src = inspection.presetSources?.get(p.id);
             docs.push({
-                id: `preset:${p.id}`,
+                id: searchDocumentId('preset', p.id),
                 kind: SearchKind.Preset,
                 title: p.name ?? p.id,
                 content: safeContent(p.description ?? '', 400),
@@ -224,7 +226,7 @@ export function buildSearchIndex(inspection) {
     }
     for (const pack of inspection.packs.validPacks ?? []) {
         docs.push({
-            id: `pack:${pack.packageName}`,
+            id: searchDocumentId('pack', pack.packageName),
             kind: SearchKind.Pack,
             title: pack.packageName,
             content: safeContent(pack.manifest?.info?.description ?? '', 400),
@@ -238,7 +240,7 @@ export function buildSearchIndex(inspection) {
     for (const r of inspection.boundaryRegistry.list()) {
         const rb = r;
         docs.push({
-            id: `boundary:${r.id}`,
+            id: searchDocumentId('boundary', r.id),
             kind: SearchKind.Boundary,
             title: rb.title ?? r.id,
             content: safeContent(rb.description ?? rb.message ?? '', 400),
@@ -251,20 +253,12 @@ export function buildSearchIndex(inspection) {
             },
         });
     }
-    // Policies (registered checks).
-    try {
-        const cfg = inspection.config;
-        void cfg;
-    }
-    catch {
-        /* ignore */
-    }
     // Bundles, sessions.
     try {
         const bundles = listFeatureBundles(inspection.projectRoot);
         for (const b of bundles) {
             docs.push({
-                id: `bundle:${b.id}`,
+                id: searchDocumentId('bundle', b.id),
                 kind: SearchKind.Bundle,
                 title: b.task ?? b.id,
                 content: safeContent(b.task ?? '', 400),
@@ -280,7 +274,7 @@ export function buildSearchIndex(inspection) {
         const sessions = listDevSessionsDetailed(inspection.projectRoot);
         for (const s of sessions) {
             docs.push({
-                id: `session:${s.id}`,
+                id: searchDocumentId('session', s.id),
                 kind: SearchKind.Session,
                 title: s.task || s.id,
                 source: SearchSource.Session,
@@ -296,7 +290,7 @@ export function buildSearchIndex(inspection) {
         const constructs = listConstructs(inspection);
         for (const c of constructs) {
             docs.push({
-                id: `construct:${c.id}`,
+                id: searchDocumentId('construct', c.id),
                 kind: SearchKind.Construct,
                 title: c.title ?? c.id,
                 content: safeContent(c.description ?? '', 600),
@@ -307,7 +301,7 @@ export function buildSearchIndex(inspection) {
             });
             for (const f of facetsFor(c)) {
                 docs.push({
-                    id: `facet:${c.id}:${f.id}`,
+                    id: searchDocumentId('facet', `${c.id}:${f.id}`),
                     kind: SearchKind.ConstructFacet,
                     title: `${c.id} / ${f.kind}: ${f.value}`,
                     content: safeContent(f.description ?? '', 200),
@@ -324,7 +318,7 @@ export function buildSearchIndex(inspection) {
         const playbooks = listPlaybooks(inspection);
         for (const p of playbooks) {
             docs.push({
-                id: `playbook:${p.id}`,
+                id: searchDocumentId('playbook', p.id),
                 kind: SearchKind.Playbook,
                 title: p.title ?? p.id,
                 content: safeContent(p.description ?? '', 600),
@@ -462,6 +456,9 @@ export function searchIndex(index, options, inspection) {
     }
     const tokens = tokenize(query.toLowerCase());
     const tuning = options.tuning ?? (inspection ? listSearchTuning(inspection) : []);
+    // Scoring keeps its own tokens; trigger matching reads THE tuning tokenizer,
+    // the same one the task ranker, the context re-ranker and `why` read.
+    const tuningTokens = tuningQueryTokens(query);
     const hits = [];
     for (const doc of index) {
         const { score, matchedFields, reasons } = scoreDocument(doc, query, tokens, options);
@@ -470,7 +467,7 @@ export function searchIndex(index, options, inspection) {
         let finalScore = score;
         let finalReasons = options.explain ? [...reasons] : [];
         if (tuning.length > 0) {
-            const boost = tuningBoostFor({ id: doc.id, kind: doc.kind, ...(doc.tags ? { tags: doc.tags } : {}), source: doc.source }, tokens, tuning);
+            const boost = tuningBoostFor({ id: doc.id, kind: doc.kind, ...(doc.tags ? { tags: doc.tags } : {}), source: doc.source }, tuningTokens, tuning);
             if (boost.delta !== 0) {
                 finalScore += boost.delta;
                 if (options.explain)

package/dist/search-tuning-explain.d.ts

@@ -49,11 +49,17 @@ export interface ISearchTuningExplainReport {
         mergeStrategy?: 'sum' | 'max';
     }[];
     matched: readonly ITuningMatch[];
+    /**
+     * Every boost the ±cap changed. A per-boost clamp names its tuning and key;
+     * the global total cap is a row with `key: 'total'` and the `docId` it
+     * discarded tuning on (it used to be applied silently).
+     */
     cappedBoosts: readonly {
         tuningId: string;
         key: string;
         original: number;
         clamped: number;
+        docId?: string;
     }[];
     topResults: readonly IPerHitTuningExplain[];
     warnings: readonly {

package/dist/search-tuning-explain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-tuning-explain.d.ts","sourceRoot":"","sources":["../src/search-tuning-explain.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,4BAA4B,wCAAwC,CAAC;AAElF,MAAM,WAAW,2BAA2B;IAC1C,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,iFAAiF;IACjF,WAAW,CAAC,EAAE,SAAS;QACrB,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,KAAK,GAAG,KAAK,CAAC;QACxB,YAAY,EAAE,SAAS;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC7D,QAAQ,EAAE,MAAM,CAAC;KAClB,EAAE,CAAC;CACL;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,SAAS,EAAE,SAAS;QAAE,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CAC3E;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,OAAO,4BAA4B,CAAC;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,SAAS;QACtB,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;KAC/B,EAAE,CAAC;IACJ,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,YAAY,EAAE,SAAS;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9F,UAAU,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC5C,QAAQ,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3E;AAyCD,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,0BAA0B,CAAC,CA0ErC;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,0BAA0B,GAAG,MAAM,CA0DtF;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,0BAA0B,GAAG,MAAM,CAiClF"}
+{"version":3,"file":"search-tuning-explain.d.ts","sourceRoot":"","sources":["../src/search-tuning-explain.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGvE,eAAO,MAAM,4BAA4B,wCAAwC,CAAC;AAElF,MAAM,WAAW,2BAA2B;IAC1C,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,iFAAiF;IACjF,WAAW,CAAC,EAAE,SAAS;QACrB,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,KAAK,GAAG,KAAK,CAAC;QACxB,YAAY,EAAE,SAAS;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC7D,QAAQ,EAAE,MAAM,CAAC;KAClB,EAAE,CAAC;CACL;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,SAAS,EAAE,SAAS;QAAE,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CAC3E;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,OAAO,4BAA4B,CAAC;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,SAAS;QACtB,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;KAC/B,EAAE,CAAC;IACJ,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC;;;;OAIG;IACH,YAAY,EAAE,SAAS;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9G,UAAU,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC5C,QAAQ,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3E;AAiCD,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,0BAA0B,CAAC,CAmFrC;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,0BAA0B,GAAG,MAAM,CA0DtF;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,0BAA0B,GAAG,MAAM,CAiClF"}

package/dist/search-tuning-explain.js

@@ -1,13 +1,7 @@
 import { buildSearchIndex, searchIndex } from "./search-index.js";
 import { listSearchTuning, listSearchTuningIssues, loadSearchTuning, tuningBoostFor, } from "./search-tuning-registry.js";
+import { tuningQueryTokens } from "./tuning-query-tokens.js";
 export const SEARCH_TUNING_EXPLAIN_SCHEMA = 'sharkcraft.search-tuning-explain/v1';
-function tokenize(query) {
-    return query
-        .toLowerCase()
-        .split(/[\s,\.;:\/]+/)
-        .map((t) => t.trim())
-        .filter((t) => t.length > 1);
-}
 function describeBoost(entry, tokens) {
     const matchedTags = entry.boostTags ? Object.keys(entry.boostTags) : [];
     const matchedKinds = [];
@@ -49,19 +43,18 @@ export async function explainSearchTuning(inspection, query, options = {}) {
     await loadSearchTuning(inspection);
     const tuning = listSearchTuning(inspection);
     const issues = listSearchTuningIssues(inspection);
-    const tokens = tokenize(query);
+    // THE trigger tokenizer — the one `searchIndex` hands `tuningBoostFor`.
+    const tokens = tuningQueryTokens(query);
     const matched = tuning.map((t) => describeBoost(t, tokens));
+    // Structured fields from the loader, not a regex over the message text.
     const cappedBoosts = issues
         .filter((i) => i.code === 'boost-clamped')
-        .map((i) => {
-        const parsed = /Boost for "([^"]+)" clamped to (\S+) \(was (\S+)\)/.exec(i.message);
-        return {
-            ...(i.tuningId ? { tuningId: i.tuningId } : { tuningId: '(unknown)' }),
-            key: parsed?.[1] ?? '?',
-            clamped: parsed ? Number(parsed[2]) : 0,
-            original: parsed ? Number(parsed[3]) : 0,
-        };
-    });
+        .map((i) => ({
+        tuningId: i.tuningId ?? '(unknown)',
+        key: i.key ?? '?',
+        clamped: i.clamped ?? 0,
+        original: i.original ?? 0,
+    }));
     const index = buildSearchIndex(inspection);
     const opts = { query, limit: Math.max(5, options.topN ?? 5), explain: true };
     const baseline = searchIndex(index, { ...opts, tuning: [] });
@@ -79,6 +72,15 @@ export async function explainSearchTuning(inspection, query, options = {}) {
             ...(h.document.tags ? { tags: h.document.tags } : {}),
             source: h.document.source,
         }, tokens, tuning);
+        if (boost.capped) {
+            cappedBoosts.push({
+                tuningId: '(combined)',
+                key: 'total',
+                docId: h.document.id,
+                original: boost.capped.raw,
+                clamped: boost.capped.applied,
+            });
+        }
         topResults.push({
             docId: h.document.id,
             title: h.document.title,

package/dist/search-tuning-key-probes.d.ts

@@ -0,0 +1,16 @@
+import type { ISearchTuningKeyProbe } from './i-search-tuning-key-probe.js';
+import { type ISearchTuningEntry } from './search-tuning-registry.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+/**
+ * THE boost-key probes (round 13): every (entry, key) declared in an id boost
+ * map, with the maps it sits in, the entry's expectEmpty markers on it, and
+ * THE key resolver's answer (resolved once per distinct key). `lintSearchTuning`
+ * settles and words them (`search tuning doctor`, the self-config doctor), and
+ * `collectUnresolvableReferences` reads them for `packs contributions` — one
+ * answer to "could this boost key be checked?".
+ *
+ * Callers load the entries (`loadSearchTuning`) and warm the reference
+ * registries (`warmReferenceRegistries`) first.
+ */
+export declare function searchTuningKeyProbes(inspection: ISharkcraftInspection, entries: readonly ISearchTuningEntry[]): readonly ISearchTuningKeyProbe[];
+//# sourceMappingURL=search-tuning-key-probes.d.ts.map

package/dist/search-tuning-key-probes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-tuning-key-probes.d.ts","sourceRoot":"","sources":["../src/search-tuning-key-probes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAI5E,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GACrC,SAAS,qBAAqB,EAAE,CAkDlC"}

package/dist/search-tuning-key-probes.js

@@ -0,0 +1,65 @@
+import { isSearchDocumentPrefix, searchKindForPrefix } from "./search-document-id.js";
+import { resolveSearchTuningKey } from "./search-tuning-key-resolver.js";
+import { SEARCH_TUNING_BOOST_IDS, searchTuningTaskHintBoostIdsPath, } from "./search-tuning-registry.js";
+/**
+ * THE boost-key probes (round 13): every (entry, key) declared in an id boost
+ * map, with the maps it sits in, the entry's expectEmpty markers on it, and
+ * THE key resolver's answer (resolved once per distinct key). `lintSearchTuning`
+ * settles and words them (`search tuning doctor`, the self-config doctor), and
+ * `collectUnresolvableReferences` reads them for `packs contributions` — one
+ * answer to "could this boost key be checked?".
+ *
+ * Callers load the entries (`loadSearchTuning`) and warm the reference
+ * registries (`warmReferenceRegistries`) first.
+ */
+export function searchTuningKeyProbes(inspection, entries) {
+    const resolutions = new Map();
+    const resolve = (key) => {
+        let r = resolutions.get(key);
+        if (!r) {
+            r = resolveSearchTuningKey(inspection, key);
+            resolutions.set(key, r);
+        }
+        return r;
+    };
+    const probes = [];
+    for (const e of entries) {
+        const ledger = new Map((e.expectEmptyUnits ?? []).map((m) => [`${m.list} ${m.unit}`, m]));
+        const maps = [
+            [SEARCH_TUNING_BOOST_IDS, e.boostIds],
+            ...(e.taskHints ?? []).map((h, i) => [searchTuningTaskHintBoostIdsPath(i), h.boostIds]),
+        ];
+        // One probe per (entry, key): the same key in three maps is one declaration
+        // (one finding, `declared 3 times`), carrying every map and every marker.
+        const byKey = new Map();
+        for (const [list, map] of maps) {
+            for (const key of Object.keys(map ?? {})) {
+                const d = byKey.get(key) ?? { lists: [], marks: [] };
+                d.lists.push(list);
+                const mark = ledger.get(`${list} ${key}`);
+                if (mark)
+                    d.marks.push(mark);
+                byKey.set(key, d);
+            }
+        }
+        for (const [key, d] of byKey) {
+            const resolution = resolve(key);
+            const kind = resolution.prefix !== undefined && isSearchDocumentPrefix(resolution.prefix)
+                ? (searchKindForPrefix(resolution.prefix) ?? resolution.prefix)
+                : undefined;
+            const excludedKind = kind !== undefined && e.appliesToKinds && !e.appliesToKinds.includes(kind) ? kind : undefined;
+            probes.push({
+                tuningId: e.id,
+                key,
+                lists: d.lists,
+                marks: d.marks,
+                resolution,
+                ...(e.appliesToKinds ? { appliesToKinds: e.appliesToKinds } : {}),
+                ...(excludedKind !== undefined ? { excludedKind } : {}),
+                ...(e.sourceFile ? { sourceFile: e.sourceFile } : {}),
+                ...(e.packageName ? { packageName: e.packageName } : {}),
+            });
+        }
+    }
+    return probes;
+}

package/dist/search-tuning-key-resolution.d.ts

@@ -0,0 +1,25 @@
+import type { ReferenceKind } from './reference-registry.js';
+import type { SearchTuningKeyStatus } from './search-tuning-key-status.js';
+/** The answer {@link resolveSearchTuningKey} gives for one boost key. */
+export interface ISearchTuningKeyResolution {
+    /** The boost key exactly as declared. */
+    readonly key: string;
+    readonly status: SearchTuningKeyStatus;
+    /** The `<prefix>` when the key parsed as `<prefix>:<id>`. */
+    readonly prefix?: string;
+    /** The right-hand id — the WHOLE key when it has no prefix. */
+    readonly id: string;
+    /** The registry the id was (or would be) resolved in. */
+    readonly referenceKind?: ReferenceKind;
+    /**
+     * The key to write instead: the prefixed form of an unprefixed key, the
+     * nearest registered id of a missing one, or the nearest real prefix of an
+     * unknown kind.
+     */
+    readonly suggestion?: string;
+    /** Every prefixed form an unprefixed key resolves as (when more than one kind lists it). */
+    readonly suggestions?: readonly string[];
+    /** Why — always set for `unverified`, so the skip is never silent. */
+    readonly reason?: string;
+}
+//# sourceMappingURL=search-tuning-key-resolution.d.ts.map

package/dist/search-tuning-key-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-tuning-key-resolution.d.ts","sourceRoot":"","sources":["../src/search-tuning-key-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAE3E,yEAAyE;AACzE,MAAM,WAAW,0BAA0B;IACzC,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B"}

package/dist/search-tuning-key-resolution.js

@@ -0,0 +1 @@
+export {};

package/dist/search-tuning-key-resolver.d.ts

@@ -0,0 +1,4 @@
+import type { ISearchTuningKeyResolution } from './search-tuning-key-resolution.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare function resolveSearchTuningKey(inspection: ISharkcraftInspection, key: string): ISearchTuningKeyResolution;
+//# sourceMappingURL=search-tuning-key-resolver.d.ts.map

package/dist/search-tuning-key-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-tuning-key-resolver.d.ts","sourceRoot":"","sources":["../src/search-tuning-key-resolver.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAEpF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAiBvE,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,EACjC,GAAG,EAAE,MAAM,GACV,0BAA0B,CA4E5B"}

package/dist/search-tuning-key-resolver.js

@@ -0,0 +1,107 @@
+/**
+ * THE resolver for search-tuning boost keys.
+ *
+ * A boost key is a search-document id, `<kind>:<id>` — the matcher
+ * (`tuningBoostFor`) compares `boostIds[doc.id]` against the WHOLE document id.
+ * The self-config doctor used to look that whole prefixed key up in BARE-id
+ * registries, so every correctly prefixed key (which fires) was reported
+ * "unknown", and a bare key (which can never fire) passed. On a healthy pack
+ * that was 200 false warnings inviting the deletion of correct config, and on
+ * shrk itself it certified 33 dead entries.
+ *
+ * The key is split on its FIRST `:` by THE codec (`search-document-id.ts`), and
+ * the right-hand id is resolved WITHIN the named kind through THE id resolver
+ * (`reference-registry.ts`). Callers must `warmReferenceRegistries` first.
+ */
+import { nearestIds } from "./nearest-id.js";
+import { emptyReferenceKinds, referenceIdExists, referenceIdsFor, referenceKindOf, } from "./reference-registry.js";
+import { isSearchDocumentPrefix, parseSearchDocumentId, SEARCH_DOCUMENT_ID_KINDS, SEARCH_DOCUMENT_PREFIXES, searchDocumentId, } from "./search-document-id.js";
+import { SearchTuningKeyStatus } from "./search-tuning-key-status.js";
+/** Every prefixed key a BARE id resolves as, with the kind it resolved in, in prefix order. */
+function prefixedFormsOf(inspection, bareId) {
+    const out = [];
+    for (const prefix of SEARCH_DOCUMENT_PREFIXES) {
+        const kind = SEARCH_DOCUMENT_ID_KINDS[prefix];
+        if (kind !== null && referenceIdExists(inspection, kind, bareId)) {
+            out.push({ key: searchDocumentId(prefix, bareId), kind });
+        }
+    }
+    return out;
+}
+export function resolveSearchTuningKey(inspection, key) {
+    const parsed = parseSearchDocumentId(key);
+    if (parsed && isSearchDocumentPrefix(parsed.prefix)) {
+        const { prefix, id } = parsed;
+        const kind = SEARCH_DOCUMENT_ID_KINDS[prefix];
+        if (kind === null) {
+            return {
+                key,
+                status: SearchTuningKeyStatus.Unverified,
+                prefix,
+                id,
+                reason: `\`${prefix}:\` documents have no id registry, so "${id}" cannot be checked`,
+            };
+        }
+        if (emptyReferenceKinds(inspection, [kind]).length > 0) {
+            return {
+                key,
+                status: SearchTuningKeyStatus.Unverified,
+                prefix,
+                id,
+                referenceKind: kind,
+                reason: `no ${kind} is registered in this workspace (or its registry did not load), so "${id}" cannot be checked`,
+            };
+        }
+        if (referenceIdExists(inspection, kind, id)) {
+            return { key, status: SearchTuningKeyStatus.Resolved, prefix, id, referenceKind: kind };
+        }
+        const near = nearestIds(id, referenceIdsFor(inspection, kind), 1)[0];
+        return {
+            key,
+            status: SearchTuningKeyStatus.Missing,
+            prefix,
+            id,
+            referenceKind: kind,
+            ...(near ? { suggestion: searchDocumentId(prefix, near.id) } : {}),
+        };
+    }
+    // Not `<known prefix>:<id>`. A WHOLE key that resolves as a bare id is the
+    // common mistake: it reads right and never fires.
+    const forms = prefixedFormsOf(inspection, key);
+    if (forms.length > 0) {
+        return {
+            key,
+            status: SearchTuningKeyStatus.Unprefixed,
+            id: key,
+            // The kind the bare id DID resolve in (the field's contract: "the
+            // registry the id was resolved in"). Without it a consumer labelling the
+            // target had nothing but `unknown` for an id that exists (round 12, 12.4).
+            referenceKind: forms[0].kind,
+            suggestion: forms[0].key,
+            ...(forms.length > 1 ? { suggestions: forms.map((f) => f.key) } : {}),
+        };
+    }
+    if (parsed) {
+        const near = nearestIds(parsed.prefix, SEARCH_DOCUMENT_PREFIXES, 1)[0];
+        return {
+            key,
+            status: SearchTuningKeyStatus.UnknownKind,
+            prefix: parsed.prefix,
+            id: parsed.id,
+            ...(near ? { suggestion: `${near.id}:${parsed.id}` } : {}),
+            reason: `"${parsed.prefix}" is not a search-document kind (${SEARCH_DOCUMENT_PREFIXES.join(', ')})`,
+        };
+    }
+    // Registered — but as a kind the search index never emits (a decision, a
+    // policy, a scaffold pattern): no boost key can target it at all.
+    const registeredAs = referenceKindOf(inspection, key);
+    return {
+        key,
+        status: SearchTuningKeyStatus.Unprefixed,
+        id: key,
+        ...(registeredAs ? { referenceKind: registeredAs } : {}),
+        reason: registeredAs
+            ? `"${key}" is a registered ${registeredAs}, but ${registeredAs} entries are not search documents, so no boost key can target it`
+            : 'it has no `<kind>:` prefix, and no registry lists it as a bare id either',
+    };
+}

package/dist/search-tuning-key-status.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What resolving one search-tuning boost key (`boostIds` /
+ * `taskHints[].boostIds`) against the live registries found.
+ *
+ * A boost key is a SEARCH-DOCUMENT id (`<kind>:<id>`, see
+ * `search-document-id.ts`): the matcher compares it to `doc.id` whole.
+ */
+export declare enum SearchTuningKeyStatus {
+    /** `<kind>:<id>` whose id is registered under that kind — the boost can fire. */
+    Resolved = "resolved",
+    /** `<kind>:<id>` whose id is NOT registered under that kind — dead. */
+    Missing = "missing",
+    /** A bare id (no `<kind>:` prefix) — no search document is keyed like that, so it never fires. */
+    Unprefixed = "unprefixed",
+    /** `<prefix>:<id>` whose prefix is not a search-document kind — dead. */
+    UnknownKind = "unknown-kind",
+    /**
+     * NOT checked: the kind has no id registry (preset, pack, bundle, session,
+     * facet, doc) or its registry is empty in this workspace. Never reported as
+     * missing — a check that cannot look must say so instead of guessing.
+     */
+    Unverified = "unverified"
+}
+//# sourceMappingURL=search-tuning-key-status.d.ts.map

package/dist/search-tuning-key-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-tuning-key-status.d.ts","sourceRoot":"","sources":["../src/search-tuning-key-status.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,oBAAY,qBAAqB;IAC/B,iFAAiF;IACjF,QAAQ,aAAa;IACrB,uEAAuE;IACvE,OAAO,YAAY;IACnB,kGAAkG;IAClG,UAAU,eAAe;IACzB,yEAAyE;IACzE,WAAW,iBAAiB;IAC5B;;;;OAIG;IACH,UAAU,eAAe;CAC1B"}

package/dist/search-tuning-key-status.js

@@ -0,0 +1,24 @@
+/**
+ * What resolving one search-tuning boost key (`boostIds` /
+ * `taskHints[].boostIds`) against the live registries found.
+ *
+ * A boost key is a SEARCH-DOCUMENT id (`<kind>:<id>`, see
+ * `search-document-id.ts`): the matcher compares it to `doc.id` whole.
+ */
+export var SearchTuningKeyStatus;
+(function (SearchTuningKeyStatus) {
+    /** `<kind>:<id>` whose id is registered under that kind — the boost can fire. */
+    SearchTuningKeyStatus["Resolved"] = "resolved";
+    /** `<kind>:<id>` whose id is NOT registered under that kind — dead. */
+    SearchTuningKeyStatus["Missing"] = "missing";
+    /** A bare id (no `<kind>:` prefix) — no search document is keyed like that, so it never fires. */
+    SearchTuningKeyStatus["Unprefixed"] = "unprefixed";
+    /** `<prefix>:<id>` whose prefix is not a search-document kind — dead. */
+    SearchTuningKeyStatus["UnknownKind"] = "unknown-kind";
+    /**
+     * NOT checked: the kind has no id registry (preset, pack, bundle, session,
+     * facet, doc) or its registry is empty in this workspace. Never reported as
+     * missing — a check that cannot look must say so instead of guessing.
+     */
+    SearchTuningKeyStatus["Unverified"] = "unverified";
+})(SearchTuningKeyStatus || (SearchTuningKeyStatus = {}));