@aiwg/cli 2026.8.8 → 2026.8.10

package/dist/src/artifacts/corpus-tools/retrieval-lab.js

@@ -0,0 +1,356 @@
+/** Experimental hybrid corpus-retrieval benchmark. Never replaces research-query. @issue #2038 */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { bm25Rank, tokenizeText } from '../fulltext.js';
+import { loadGraphIndexFile } from '../index-reader.js';
+import { runResearchQuery } from '../../research/query-cli.js';
+export const RETRIEVAL_LAB_QUERY_SCHEMA = 'aiwg.corpus-retrieval-query/v1';
+export const RETRIEVAL_LAB_CONCEPT_SCHEMA = 'aiwg.concept-scheme/v1';
+export const RETRIEVAL_LAB_REPORT_SCHEMA = 'aiwg.corpus-retrieval-report/v1';
+export const RETRIEVAL_LAB_STRATEGIES = ['research-query', 'direct-rg', 'vector', 'bm25', 'graph-ppr', 'hybrid-rrf'];
+const round = (value, digits = 6) => {
+    const scale = 10 ** digits;
+    return Math.round(value * scale) / scale;
+};
+function stringArray(value, label, line) {
+    if (!Array.isArray(value) || value.length === 0 || value.some(item => typeof item !== 'string' || !item.trim())) {
+        throw new Error(`Retrieval query line ${line}: ${label} must be a non-empty string array`);
+    }
+    return value;
+}
+export function parseRetrievalQueries(content) {
+    const queries = [];
+    const ids = new Set();
+    for (const [offset, raw] of content.split(/\r?\n/).entries()) {
+        if (!raw.trim())
+            continue;
+        const line = offset + 1;
+        let value;
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`Retrieval query line ${line}: malformed JSON`);
+        }
+        if (value.schema !== RETRIEVAL_LAB_QUERY_SCHEMA)
+            throw new Error(`Retrieval query line ${line}: unsupported schema`);
+        if (typeof value.id !== 'string' || !value.id.trim() || ids.has(value.id))
+            throw new Error(`Retrieval query line ${line}: id must be unique and non-empty`);
+        if (typeof value.question !== 'string' || !value.question.trim())
+            throw new Error(`Retrieval query line ${line}: question must be non-empty`);
+        ids.add(value.id);
+        queries.push({
+            schema: RETRIEVAL_LAB_QUERY_SCHEMA,
+            id: value.id,
+            question: value.question,
+            expected_ids: stringArray(value.expected_ids, 'expected_ids', line),
+            expected_evidence: stringArray(value.expected_evidence, 'expected_evidence', line),
+        });
+    }
+    if (!queries.length)
+        throw new Error('Retrieval query fixture contains no queries');
+    return queries;
+}
+function normalizedScheme(scheme) {
+    return {
+        schema: RETRIEVAL_LAB_CONCEPT_SCHEMA,
+        id: scheme.id,
+        concepts: [...scheme.concepts].map(concept => ({
+            id: concept.id,
+            prefLabel: concept.prefLabel,
+            ...(concept.altLabels?.length ? { altLabels: [...concept.altLabels].sort() } : {}),
+            ...(concept.broader?.length ? { broader: [...concept.broader].sort() } : {}),
+            ...(concept.narrower?.length ? { narrower: [...concept.narrower].sort() } : {}),
+            ...(concept.related?.length ? { related: [...concept.related].sort() } : {}),
+        })).sort((a, b) => a.id.localeCompare(b.id)),
+    };
+}
+export function parseConceptScheme(content) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        throw new Error('Concept scheme is malformed JSON');
+    }
+    if (value.schema !== RETRIEVAL_LAB_CONCEPT_SCHEMA || typeof value.id !== 'string' || !value.id || !Array.isArray(value.concepts) || !value.concepts.length) {
+        throw new Error(`Concept scheme must use ${RETRIEVAL_LAB_CONCEPT_SCHEMA}`);
+    }
+    const ids = new Set();
+    for (const concept of value.concepts) {
+        const normalizedId = concept?.id?.toLowerCase();
+        if (!concept || typeof concept.id !== 'string' || !concept.id || typeof concept.prefLabel !== 'string' || !concept.prefLabel || ids.has(normalizedId)) {
+            throw new Error('Concept scheme contains a malformed or duplicate concept');
+        }
+        ids.add(normalizedId);
+        for (const relation of ['altLabels', 'broader', 'narrower', 'related']) {
+            if (concept[relation] !== undefined && (!Array.isArray(concept[relation]) || concept[relation].some(item => typeof item !== 'string'))) {
+                throw new Error(`Concept ${concept.id} has malformed ${relation}`);
+            }
+        }
+    }
+    for (const concept of value.concepts) {
+        for (const relation of ['broader', 'narrower', 'related']) {
+            for (const target of concept[relation] ?? [])
+                if (!ids.has(target.toLowerCase()))
+                    throw new Error(`Concept ${concept.id} references unknown ${relation} target ${target}`);
+        }
+    }
+    const scheme = normalizedScheme(value);
+    return { scheme, hash: createHash('sha256').update(JSON.stringify(scheme)).digest('hex') };
+}
+function documentId(entry) {
+    const text = [entry.name, entry.title, entry.path].filter(Boolean).join(' ');
+    return text.match(/\bREF-\d+\b/i)?.[0]?.toUpperCase() ?? path.basename(entry.path).replace(/\.[^.]+$/, '');
+}
+function isResearch(entry) {
+    const candidate = `${entry.type} ${entry.path}`.toLowerCase().replaceAll('\\', '/');
+    return /research-ref|research-profile|research-view|research-synthesis|kb-page|\/research\/|\/kb\//.test(candidate);
+}
+function readBody(root, entry) {
+    try {
+        return fs.readFileSync(path.resolve(root, entry.path), 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function featureVector(text, dimensions = 128) {
+    const vector = new Array(dimensions).fill(0);
+    for (const token of tokenizeText(text)) {
+        const digest = createHash('sha256').update(token).digest();
+        const index = digest.readUInt16BE(0) % dimensions;
+        vector[index] += (digest[2] & 1) ? 1 : -1;
+    }
+    const norm = Math.sqrt(vector.reduce((sum, item) => sum + item * item, 0));
+    return norm ? vector.map(item => item / norm) : vector;
+}
+function cosine(left, right) {
+    return left.reduce((sum, value, index) => sum + value * (right[index] ?? 0), 0);
+}
+function conceptText(concept) {
+    return [concept.prefLabel, ...(concept.altLabels ?? [])].join(' ');
+}
+function loadDocuments(root, scheme) {
+    const index = loadGraphIndexFile(root, 'metadata.json', 'project');
+    if (!index)
+        throw new Error('Project corpus index is missing; run `aiwg index build --graph project`');
+    const concepts = new Map(scheme.concepts.map(concept => [concept.id.toLowerCase(), concept]));
+    return Object.values(index.entries).filter(isResearch).map(entry => {
+        const body = readBody(root, entry);
+        const documentConcepts = entry.tags.map(tag => tag.toLowerCase()).filter(tag => concepts.has(tag));
+        const expanded = documentConcepts.map(id => conceptText(concepts.get(id))).join(' ');
+        const text = [entry.title, entry.name ?? '', entry.summary, entry.tags.join(' '), expanded, body].join('\n');
+        return { entry, id: documentId(entry), body, text, concepts: documentConcepts, vector: featureVector(text) };
+    });
+}
+function matchedTerms(query, text) {
+    const available = new Set(tokenizeText(text));
+    return [...new Set(tokenizeText(query))].filter(term => available.has(term)).sort();
+}
+function hit(document, score, query, graphConcepts = []) {
+    return { id: document.id, path: document.entry.path, title: document.entry.title, score: round(score), matched_terms: matchedTerms(query, document.text), graph_concepts: graphConcepts.sort() };
+}
+function directRank(documents, query) {
+    const terms = [...new Set(tokenizeText(query))];
+    return documents.map(document => ({ document, score: terms.reduce((sum, term) => sum + (document.text.toLowerCase().includes(term) ? 1 : 0), 0) }))
+        .filter(item => item.score > 0).sort((a, b) => b.score - a.score || a.document.id.localeCompare(b.document.id))
+        .map(item => hit(item.document, item.score / Math.max(1, terms.length), query));
+}
+function vectorRank(documents, query) {
+    const queryVector = featureVector(query);
+    return documents.map(document => ({ document, score: Math.max(0, cosine(queryVector, document.vector)) }))
+        .filter(item => item.score > 0).sort((a, b) => b.score - a.score || a.document.id.localeCompare(b.document.id))
+        .map(item => hit(item.document, item.score, query));
+}
+function lexicalRank(documents, query) {
+    const byId = new Map(documents.map(document => [document.id, document]));
+    return bm25Rank(documents.map(document => ({ id: document.id, text: document.text })), query)
+        .map(item => hit(byId.get(item.id), item.score, query));
+}
+function graphRank(documents, scheme, query, vector, lexical) {
+    const concepts = new Map(scheme.concepts.map(concept => [concept.id.toLowerCase(), concept]));
+    const documentById = new Map(documents.map(document => [document.id, document]));
+    const restart = new Map();
+    for (const concept of concepts.values()) {
+        const overlap = matchedTerms(query, conceptText(concept)).length;
+        if (overlap)
+            restart.set(concept.id.toLowerCase(), overlap);
+    }
+    for (const candidate of [...vector.slice(0, 5), ...lexical.slice(0, 5)]) {
+        for (const concept of documentById.get(candidate.id)?.concepts ?? [])
+            restart.set(concept, (restart.get(concept) ?? 0) + candidate.score * 0.25);
+    }
+    const totalRestart = [...restart.values()].reduce((sum, value) => sum + value, 0);
+    if (!totalRestart)
+        return [];
+    for (const [id, value] of restart)
+        restart.set(id, value / totalRestart);
+    let scores = new Map(restart);
+    const weights = { broader: 0.8, narrower: 1, related: 0.6 };
+    for (let iteration = 0; iteration < 20; iteration++) {
+        const next = new Map();
+        for (const [id, value] of restart)
+            next.set(id, value * 0.15);
+        for (const [source, score] of scores) {
+            const concept = concepts.get(source);
+            if (!concept)
+                continue;
+            const edges = Object.keys(weights).flatMap(type => (concept[type] ?? []).map(target => ({ target: target.toLowerCase(), weight: weights[type] })));
+            const denominator = edges.reduce((sum, edge) => sum + edge.weight, 0);
+            if (!denominator) {
+                next.set(source, (next.get(source) ?? 0) + score * 0.85);
+                continue;
+            }
+            for (const edge of edges) {
+                const target = concepts.get(edge.target);
+                const degree = (target?.broader?.length ?? 0) + (target?.narrower?.length ?? 0) + (target?.related?.length ?? 0);
+                const specificity = 1 / Math.log2(2 + degree);
+                next.set(edge.target, (next.get(edge.target) ?? 0) + score * 0.85 * (edge.weight / denominator) * specificity);
+            }
+        }
+        scores = next;
+    }
+    return documents.map(document => {
+        const contributing = document.concepts.filter(id => (scores.get(id) ?? 0) > 0);
+        const score = contributing.reduce((sum, id) => sum + (scores.get(id) ?? 0), 0) / Math.max(1, document.concepts.length);
+        return { document, score, contributing };
+    }).filter(item => item.score > 0).sort((a, b) => b.score - a.score || a.document.id.localeCompare(b.document.id))
+        .map(item => hit(item.document, item.score, query, item.contributing));
+}
+function rrf(lists, documents, query) {
+    const scores = new Map();
+    for (const list of lists)
+        list.forEach((item, rank) => scores.set(item.id, (scores.get(item.id) ?? 0) + 1 / (60 + rank + 1)));
+    const byId = new Map(documents.map(document => [document.id, document]));
+    return [...scores.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([id, score]) => {
+        const document = byId.get(id);
+        const graphConcepts = lists[2]?.find(item => item.id === id)?.graph_concepts ?? [];
+        return hit(document, score, query, graphConcepts);
+    });
+}
+function percentile(values, percentileValue) {
+    if (!values.length)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.ceil(sorted.length * percentileValue) - 1] ?? sorted[sorted.length - 1];
+}
+function strategyReport(queries, results, latencies) {
+    const ranks = queries.map((query, index) => {
+        const rank = results[index].findIndex(item => query.expected_ids.some(expected => expected.toLowerCase() === item.id.toLowerCase()));
+        return rank < 0 ? null : rank + 1;
+    });
+    const at = (limit) => round(ranks.filter(rank => rank !== null && rank <= limit).length / queries.length);
+    return {
+        metrics: {
+            hit_at_1: at(1), hit_at_3: at(3), hit_at_5: at(5),
+            mrr: round(ranks.reduce((sum, rank) => sum + (rank ? 1 / rank : 0), 0) / queries.length),
+            p95_latency_ms: round(percentile(latencies, 0.95), 3),
+        },
+        failures: queries.map((query, index) => ({ query, results: results[index] })).filter(item => !item.results.slice(0, 5).some(result => item.query.expected_ids.some(expected => expected.toLowerCase() === result.id.toLowerCase())))
+            .map(item => ({ query_id: item.query.id, expected_ids: item.query.expected_ids, returned_ids: item.results.slice(0, 5).map(result => result.id) })),
+    };
+}
+function selectionDiagnostics(results) {
+    const scores = results.slice(0, 5).map(item => item.score).filter(score => score > 0);
+    const total = scores.reduce((sum, score) => sum + score, 0);
+    if (!total)
+        return { confidence: 0, dispersion: 1 };
+    const probabilities = scores.map(score => score / total);
+    const entropy = -probabilities.reduce((sum, value) => sum + value * Math.log(value), 0);
+    const maxEntropy = Math.log(Math.max(2, probabilities.length));
+    return { confidence: round(probabilities[0]), dispersion: round(entropy / maxEntropy) };
+}
+export async function runRetrievalLab(options) {
+    const queries = parseRetrievalQueries(fs.readFileSync(options.queriesPath, 'utf8'));
+    const { scheme, hash } = parseConceptScheme(fs.readFileSync(options.conceptsPath, 'utf8'));
+    if (options.expectedSchemeHash && options.expectedSchemeHash.toLowerCase() !== hash) {
+        throw new Error(`Concept scheme drift invalidated benchmark: expected ${options.expectedSchemeHash.toLowerCase()}, observed ${hash}`);
+    }
+    const documents = loadDocuments(options.root, scheme);
+    if (!documents.length)
+        throw new Error('Project corpus index contains no research documents');
+    const limit = options.limit ?? 10;
+    const matrix = Object.fromEntries(RETRIEVAL_LAB_STRATEGIES.map(strategy => [strategy, []]));
+    const latencies = Object.fromEntries(RETRIEVAL_LAB_STRATEGIES.map(strategy => [strategy, []]));
+    for (const query of queries) {
+        let started = performance.now();
+        const current = await runResearchQuery(options.root, { question: query.question, backend: 'local', graph: 'project', depth: 'thorough', maxSources: limit });
+        matrix['research-query'].push(current.sources.map(source => ({ id: source.id, path: source.path, title: source.title, score: source.score, matched_terms: matchedTerms(query.question, [source.title, source.summary, source.tags.join(' ')].join(' ')), graph_concepts: [] })));
+        latencies['research-query'].push(performance.now() - started);
+        started = performance.now();
+        const direct = directRank(documents, query.question).slice(0, limit);
+        latencies['direct-rg'].push(performance.now() - started);
+        matrix['direct-rg'].push(direct);
+        const hybridStarted = performance.now();
+        started = hybridStarted;
+        const vector = vectorRank(documents, query.question).slice(0, limit);
+        latencies.vector.push(performance.now() - started);
+        matrix.vector.push(vector);
+        started = performance.now();
+        const lexical = lexicalRank(documents, query.question).slice(0, limit);
+        latencies.bm25.push(performance.now() - started);
+        matrix.bm25.push(lexical);
+        started = performance.now();
+        const graph = graphRank(documents, scheme, query.question, vector, lexical).slice(0, limit);
+        latencies['graph-ppr'].push(performance.now() - started);
+        matrix['graph-ppr'].push(graph);
+        const hybrid = rrf([vector, lexical, graph], documents, query.question).slice(0, limit);
+        latencies['hybrid-rrf'].push(performance.now() - hybridStarted);
+        matrix['hybrid-rrf'].push(hybrid);
+    }
+    const strategies = Object.fromEntries(RETRIEVAL_LAB_STRATEGIES.map(strategy => [strategy, strategyReport(queries, matrix[strategy], latencies[strategy])]));
+    const hybrid = strategies['hybrid-rrf'].metrics;
+    const baselines = [strategies['research-query'].metrics, strategies['direct-rg'].metrics];
+    const qualityBeats = baselines.every(baseline => hybrid.hit_at_5 >= baseline.hit_at_5 && hybrid.mrr >= baseline.mrr)
+        && baselines.some(baseline => hybrid.hit_at_5 > baseline.hit_at_5 || hybrid.mrr > baseline.mrr);
+    const acceptableLatency = hybrid.p95_latency_ms <= (options.latencyCeilingMs ?? 250);
+    const clears = qualityBeats && acceptableLatency;
+    const documentById = new Map(documents.map(document => [document.id, document]));
+    return {
+        schema: RETRIEVAL_LAB_REPORT_SCHEMA,
+        status: 'complete',
+        configuration: {
+            graph: 'project', vector: 'local-feature-hash-v1', lexical: 'bm25', graph_walk: 'typed-ppr-specificity-restart', fusion: 'rrf-k60',
+            concept_scheme_id: scheme.id, concept_scheme_hash: hash, expected_concept_scheme_hash: options.expectedSchemeHash?.toLowerCase() ?? null,
+        },
+        query_count: queries.length,
+        document_count: documents.length,
+        strategies,
+        queries: queries.map((query, index) => {
+            const results = Object.fromEntries(RETRIEVAL_LAB_STRATEGIES.map(strategy => [strategy, matrix[strategy][index]]));
+            const top = results['hybrid-rrf'].slice(0, 5);
+            const unsupported = top.filter(item => !item.matched_terms.length && !item.graph_concepts.length).map(item => item.id);
+            const selectedText = top.map(item => documentById.get(item.id)?.text ?? '').join('\n').toLowerCase();
+            const missingEvidence = query.expected_evidence.filter(evidence => !selectedText.includes(evidence.toLowerCase()));
+            return {
+                id: query.id, expected_ids: query.expected_ids, results,
+                source_selection: selectionDiagnostics(results['hybrid-rrf']),
+                faithfulness: { passed: unsupported.length === 0 && missingEvidence.length === 0, unsupported_top_ids: unsupported, missing_expected_evidence: missingEvidence },
+            };
+        }),
+        adoption_gate: {
+            replaces_current_query: false,
+            baseline: 'research-query', quality_beats_baselines: qualityBeats, acceptable_latency: acceptableLatency, clears_gate: clears,
+            decision: clears
+                ? 'Candidate cleared the lab gate; current research-query remains unchanged pending an explicit adoption decision.'
+                : 'HOLD: hybrid retrieval did not beat both baselines within the latency ceiling; current research-query remains unchanged.',
+        },
+    };
+}
+export function renderRetrievalLab(report) {
+    const lines = [
+        `Corpus retrieval lab: ${report.query_count} queries / ${report.document_count} documents`,
+        `Concept scheme: ${report.configuration.concept_scheme_id} (${report.configuration.concept_scheme_hash})`, '',
+        'Strategy         Hit@1   Hit@3   Hit@5   MRR     p95 ms',
+    ];
+    for (const strategy of RETRIEVAL_LAB_STRATEGIES) {
+        const metrics = report.strategies[strategy].metrics;
+        lines.push(`${strategy.padEnd(16)} ${metrics.hit_at_1.toFixed(3)}   ${metrics.hit_at_3.toFixed(3)}   ${metrics.hit_at_5.toFixed(3)}   ${metrics.mrr.toFixed(3)}   ${metrics.p95_latency_ms.toFixed(3)}`);
+    }
+    lines.push('', `Decision: ${report.adoption_gate.decision}`);
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=retrieval-lab.js.map

package/dist/src/artifacts/discover-facets.js

@@ -213,7 +213,7 @@ function facetActivation(phrase, entry) {
                 matchedIntent: raw,
             };
         }
-        if (p.includes(intent) || intent.includes(p)) {
+        if (p.includes(intent) || (pTokens.length > 1 && intent.includes(p))) {
             if (FLOOR_STRONG > best) {
                 best = FLOOR_STRONG;
                 matchedIntent = raw;
@@ -223,7 +223,7 @@ function facetActivation(phrase, entry) {
         const iTokens = intent.split(' ').filter(Boolean);
         if (iTokens.length > 1 && pTokens.length > 0) {
             const hits = iTokens.filter((t) => pTokens.includes(t)).length;
-            if (hits >= Math.ceil(iTokens.length / 2) && FLOOR_OVERLAP > best) {
+            if (hits >= 2 && hits >= Math.ceil(iTokens.length / 2) && FLOOR_OVERLAP > best) {
                 best = FLOOR_OVERLAP;
                 matchedIntent = raw;
             }

package/dist/src/artifacts/embedding-index.js

@@ -6,7 +6,7 @@
  * dense vectors using a small local model and stores them in an HNSW index for
  * fast similarity queries.
  *
- * Install: npm install @xenova/transformers hnswlib-node
+ * Enable with: aiwg features install embeddings
  *
  * @implements #730
  * @source @src/artifacts/types.ts
@@ -14,6 +14,7 @@
  */
 import fs from 'fs';
 import path from 'path';
+import { loadFeaturePackage } from '../features/runtime.js';
 /**
  * Default embedding model (all-MiniLM-L6-v2: ~22MB, 384 dims, ~5ms/embedding on CPU)
  */
@@ -141,13 +142,13 @@ async function embedEntryVector(embed, entry, options) {
 export async function checkEmbeddingDeps() {
     const missing = [];
     try {
-        await (new Function('m', 'return import(m)'))('@xenova/transformers');
+        await loadFeaturePackage('@xenova/transformers');
     }
     catch {
         missing.push('@xenova/transformers');
     }
     try {
-        await (new Function('m', 'return import(m)'))('hnswlib-node');
+        await loadFeaturePackage('hnswlib-node');
     }
     catch {
         missing.push('hnswlib-node');
@@ -168,9 +169,9 @@ export async function checkEmbeddingDeps() {
  * @returns Number of entries embedded
  */
 export async function buildEmbeddingIndex(entries, outputDir, model = DEFAULT_EMBEDDING_MODEL, options = {}) {
-    const transformersMod = await (new Function('m', 'return import(m)'))('@xenova/transformers');
+    const transformersMod = await loadFeaturePackage('@xenova/transformers');
     const { pipeline } = transformersMod;
-    const hnswlib = await (new Function('m', 'return import(m)'))('hnswlib-node');
+    const hnswlib = await loadFeaturePackage('hnswlib-node');
     const HierarchicalNSW = hnswlib.HierarchicalNSW ?? hnswlib.default?.HierarchicalNSW;
     if (!HierarchicalNSW) {
         throw new Error('hnswlib-node: HierarchicalNSW not found in module exports');
@@ -233,9 +234,9 @@ export async function semanticQuery(query, indexDir, topK = 10) {
     if (!manifest) {
         throw new Error(`No embedding index found at ${indexDir}/embeddings/`);
     }
-    const transformersMod = await (new Function('m', 'return import(m)'))('@xenova/transformers');
+    const transformersMod = await loadFeaturePackage('@xenova/transformers');
     const { pipeline } = transformersMod;
-    const hnswlib = await (new Function('m', 'return import(m)'))('hnswlib-node');
+    const hnswlib = await loadFeaturePackage('hnswlib-node');
     const HierarchicalNSW = hnswlib.HierarchicalNSW ?? hnswlib.default?.HierarchicalNSW;
     if (!HierarchicalNSW) {
         throw new Error('hnswlib-node: HierarchicalNSW not found in module exports');
@@ -320,7 +321,7 @@ export async function dedupReport(indexDir, threshold = 0.92, topK = 5) {
     if (!manifest) {
         throw new Error(`No embedding index found at ${indexDir}/embeddings/`);
     }
-    const hnswlib = await (new Function('m', 'return import(m)'))('hnswlib-node');
+    const hnswlib = await loadFeaturePackage('hnswlib-node');
     const HierarchicalNSW = hnswlib.HierarchicalNSW ?? hnswlib.default?.HierarchicalNSW;
     if (!HierarchicalNSW) {
         throw new Error('hnswlib-node: HierarchicalNSW not found in module exports');

package/dist/src/artifacts/graph-backend.js

@@ -32,7 +32,7 @@ export async function createGraphBackend(type = 'json') {
                 return GraphologyBackend.create();
             }
             catch {
-                throw new Error('graphology backend requires: npm install graphology graphology-types graphology-operators graphology-traversal');
+                throw new Error('graphology backend is unavailable; run `aiwg features install graph`');
             }
         }
         case 'sqlite': {
@@ -41,7 +41,7 @@ export async function createGraphBackend(type = 'json') {
                 return new SqliteGraphBackend();
             }
             catch {
-                throw new Error('sqlite backend requires: npm install better-sqlite3 @types/better-sqlite3');
+                throw new Error('sqlite backend is unavailable; run `aiwg features install sqlite`');
             }
         }
         default:

package/dist/src/artifacts/query-engine.js

@@ -18,8 +18,8 @@ import { parseFrontmatter } from './index-builder.js';
 import { applyFacetFusion, diagnoseFacetActivations, } from './discover-facets.js';
 import { recordTypeForEntry, stableRecordId, } from './browser-export.js';
 import { loadProviderModelMetadata } from '../models/provider-models.js';
+import { projectAiwgPath, projectControlPath } from '../config/project-artifacts.js';
 import { operationalStateQueryProjection, } from './operational-state.js';
-import { projectAiwgPath } from '../config/project-artifacts.js';
 function normalizeIndexedPath(entryPath) {
     return entryPath.replace(/\\/g, '/');
 }
@@ -82,6 +82,22 @@ function graphScope(graph) {
         return 'codebase';
     return 'custom';
 }
+function containsTokenSequence(haystack, needle) {
+    if (needle.length === 0 || haystack.length < needle.length)
+        return false;
+    for (let i = 0; i <= haystack.length - needle.length; i++) {
+        let matched = true;
+        for (let j = 0; j < needle.length; j++) {
+            if (haystack[i + j] !== needle[j]) {
+                matched = false;
+                break;
+            }
+        }
+        if (matched)
+            return true;
+    }
+    return false;
+}
 function withIndexProvenance(entry, graph) {
     return { ...entry, indexGraph: graph, indexScope: graphScope(graph) };
 }
@@ -375,11 +391,9 @@ function scoreEntryDetailed(entry, text, opts = {}) {
                 });
                 return finish(1.0008, 1.0008);
             }
-            else if (trigger.includes(lower) ||
-                lower.includes(trigger) ||
-                trigger.includes(rawLower) ||
-                rawLower.includes(trigger)) {
-                const triggerInsideQuery = lower.includes(trigger) || rawLower.includes(trigger);
+            else if (containsTokenSequence(triggerTokens, tokens) ||
+                containsTokenSequence(tokens, triggerTokens)) {
+                const triggerInsideQuery = containsTokenSequence(tokens, triggerTokens);
                 const containedCoverage = triggerInsideQuery
                     ? queryCoverage
                     : triggerTokens.length > 0
@@ -756,7 +770,7 @@ const DEFAULT_DISCOVER_TYPES = [...OPERATIONAL_DISCOVERY_TYPES];
 const DEFAULT_CAPABILITY_GRAPHS = ['project', 'user', 'framework'];
 function projectAllowsUserIndices(cwd) {
     try {
-        const configPath = projectAiwgPath(cwd, 'aiwg.config');
+        const configPath = projectControlPath(cwd, 'aiwg.config');
         if (!fs.existsSync(configPath))
             return true;
         const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));

package/dist/src/artifacts/repair.js

@@ -0,0 +1,47 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { PROJECT_CONTROL_PLANE_FILES, auditProjectArtifactHealth, } from '../config/project-artifacts.js';
+export async function repairProjectArtifacts(options) {
+    const projectDir = path.resolve(options.projectDir);
+    const before = auditProjectArtifactHealth(projectDir);
+    const copied = [];
+    const removed = [];
+    if (!before.external_configured) {
+        throw new Error('No external AIWG artifact corpus is configured for this project.');
+    }
+    if (!before.external_reachable) {
+        throw new Error(`External AIWG artifact corpus is unavailable: ${before.artifact_root}`);
+    }
+    if (before.divergent_control_files.length || before.divergent_local_corpus_files.length) {
+        throw new Error(`Automatic repair refused because local and external content diverges: ${[
+            ...before.divergent_control_files,
+            ...before.divergent_local_corpus_files,
+        ].join(', ')}`);
+    }
+    for (const relativePath of before.missing_local_control_files) {
+        const source = path.join(before.artifact_root, relativePath);
+        if (!PROJECT_CONTROL_PLANE_FILES.includes(relativePath) || !before.control_files.find((item) => item.file === relativePath)?.external) {
+            throw new Error(`Cannot restore missing local control-plane file from the external corpus: ${relativePath}`);
+        }
+        copied.push(relativePath);
+        if (options.apply) {
+            const destination = path.join(before.local_control_root, relativePath);
+            await mkdir(path.dirname(destination), { recursive: true });
+            await writeFile(destination, await readFile(source));
+        }
+    }
+    for (const relativePath of before.duplicated_local_corpus_files) {
+        removed.push(relativePath);
+        if (options.apply) {
+            await rm(path.join(before.local_control_root, relativePath), { force: false });
+        }
+    }
+    return {
+        applied: options.apply === true,
+        before,
+        after: options.apply ? auditProjectArtifactHealth(projectDir) : before,
+        copied,
+        removed,
+    };
+}
+//# sourceMappingURL=repair.js.map

package/dist/src/artifacts/types.js

@@ -12,7 +12,7 @@ import fs from 'fs';
 import os from 'node:os';
 import path from 'node:path';
 import { load as loadYaml } from 'js-yaml';
-import { DEFAULT_PROJECT_AIWG_DIR, projectAiwgPath, resolveProjectAiwgDir, } from '../config/project-artifacts.js';
+import { DEFAULT_PROJECT_AIWG_DIR, projectAiwgPath, projectControlPath, resolveProjectAiwgDir, } from '../config/project-artifacts.js';
 /**
  * Operational artifact kinds that belong on the broad capability-discovery
  * surface. This is intentionally narrower than every indexed artifact type:
@@ -411,7 +411,7 @@ export function loadUserGraphConfigs(cwd, diagnostics) {
     let fromDeprecatedYaml = false;
     // (a) Canonical: .aiwg/aiwg.config (JSON).
     try {
-        const aiwgConfigPath = projectAiwgPath(cwd, 'aiwg.config');
+        const aiwgConfigPath = projectControlPath(cwd, 'aiwg.config');
         if (fs.existsSync(aiwgConfigPath)) {
             const parsed = JSON.parse(fs.readFileSync(aiwgConfigPath, 'utf-8'));
             const idx = parsed.index;
@@ -451,7 +451,7 @@ export function loadUserGraphConfigs(cwd, diagnostics) {
         return loaded;
     if (fromDeprecatedYaml && !yamlIndexDeprecationWarned) {
         yamlIndexDeprecationWarned = true;
-        process.stderr.write('[aiwg index] note: index.graphs in .aiwg/config.yaml is deprecated — move the index block into .aiwg/aiwg.config (see docs/cli-reference.md, #1491).\n');
+        process.stderr.write('[aiwg index] note: index.graphs in .aiwg/config.yaml is deprecated — move the index block into .aiwg/aiwg.config (see docs/cli/reference.md, #1491).\n');
     }
     for (const [name, def] of Object.entries(graphs)) {
         if (name in BUILTIN_GRAPH_CONFIGS) {

package/dist/src/cli/command-log.js

@@ -4,7 +4,7 @@ import { createHash } from 'crypto';
 import path from 'path';
 import os from 'os';
 import { readAiwgConfig } from '../config/aiwg-config.js';
-import { PROJECT_AIWG_LOCATION_FILE, projectAiwgPath } from '../config/project-artifacts.js';
+import { PROJECT_AIWG_LOCATION_FILE, projectAiwgPath, projectControlPath, } from '../config/project-artifacts.js';
 const DEFAULT_MAX_BYTES = 1_048_576;
 const DEFAULT_REPORT_LIMIT = 20;
 export async function maybeAppendCommandLog(input) {
@@ -157,7 +157,7 @@ async function findProjectRoot(startDir) {
     while (current !== path.dirname(current)) {
         if (existsSync(path.join(current, '.aiwg')) ||
             existsSync(path.join(current, PROJECT_AIWG_LOCATION_FILE)) ||
-            existsSync(projectAiwgPath(current, 'aiwg.config'))) {
+            existsSync(projectControlPath(current, 'aiwg.config'))) {
             return current;
         }
         current = path.dirname(current);