@aiwg/cli 2026.7.19 → 2026.7.21

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

@@ -7,4 +7,5 @@
  */
 export { run } from '../cli/router.js';
 export * from '../resources/index.js';
+export * from '../sessions/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/api/index.js

@@ -7,4 +7,5 @@
  */
 export { run } from '../cli/router.js';
 export * from '../resources/index.js';
+export * from '../sessions/index.js';
 //# sourceMappingURL=index.js.map

package/dist/src/artifacts/browser-export.js

@@ -508,6 +508,13 @@ function recordForEntry(cwd, entry, graphName, dependencyGraph, privacy, schemaV
                 ...(entry.operationalState
                     ? { operational_state: entry.operationalState }
                     : {}),
+                ...(entry.stateTransfer
+                    ? {
+                        state_transfer: {
+                            deleted_at: entry.stateTransfer.deletedAt,
+                        },
+                    }
+                    : {}),
             }
             : {}),
         updated_at: entry.updated,

package/dist/src/artifacts/citation-parser.js

@@ -8,7 +8,7 @@
  * - **Incoming**: corpus papers that cite this work (column: "REF") → `cited-by` edges
  *
  * Supported node-id forms (#105):
- * - `REF-\d+`                      research-paper IDs (REF-001, REF-029, ...)
+ * - `REF-\d+[a-z]?`                research-paper IDs (REF-001, REF-434a, ...)
  * - `PROF-[POFG]-[a-z0-9-]+`       entity-profile IDs:
  *     - `PROF-P-*` people, `PROF-O-*` orgs, `PROF-F-*` funders, `PROF-G-*` groups
  *
@@ -26,17 +26,43 @@ import { parseFrontmatter } from './index-builder.js';
  * Match a single node identifier (REF-* or PROF-*) anywhere in a string.
  * Used by `extractRefsFromTable` to pull every ID out of a table cell.
  */
-const NODE_ID_PATTERN = /(?:REF-\d+|PROF-[POFG]-[a-z0-9-]+)/g;
+const NODE_ID_PATTERN = /(?:REF-\d+[a-z]?|PROF-[POFG]-[a-z0-9-]+)/g;
 /**
  * Validate that a string is a complete node identifier.
  * Used by `parseCitationSidecar` and `buildRefToPathMap` to gate
  * frontmatter `ref` values.
  */
-const NODE_ID_FULL = /^(?:REF-\d+|PROF-[POFG]-[a-z0-9-]+)$/;
+const NODE_ID_FULL = /^(?:REF-\d+[a-z]?|PROF-[POFG]-[a-z0-9-]+)$/;
+/** Explicit column aliases used by historical citation-sidecar variants. */
+const CITATION_REF_COLUMNS = [
+    'Inducted REF',
+    'REF',
+    'Corpus REF',
+    'In-corpus REF',
+];
+/**
+ * Preserve the corpus snapshot's legacy edge semantics: every node ID on a
+ * pipe-delimited line inside an outgoing/incoming section is a declaration.
+ * Explicit column parsing remains the primary path, while this compatibility
+ * scan covers malformed rows and prose continuations that historical corpus
+ * snapshots already count.
+ */
+function extractSectionNodeIds(section) {
+    const refs = [];
+    for (const line of section.split('\n')) {
+        if (!line.includes('|'))
+            continue;
+        NODE_ID_PATTERN.lastIndex = 0;
+        const matches = line.match(NODE_ID_PATTERN);
+        if (matches)
+            refs.push(...matches);
+    }
+    return [...new Set(refs)];
+}
 /**
  * Test whether a string is a valid sidecar node identifier.
  *
- * Accepts `REF-\d+` and `PROF-[POFG]-[a-z0-9-]+`. Returns false for any
+ * Accepts `REF-\d+[a-z]?` and `PROF-[POFG]-[a-z0-9-]+`. Returns false for any
  * other input (including unrelated `PROF-` prefixed strings that don't
  * match the four-letter type code form).
  */
@@ -54,34 +80,71 @@ export function isNodeId(value) {
  * @returns Array of node identifiers found
  */
 export function extractRefsFromTable(tableText, columnName) {
-    const lines = tableText.split('\n').filter(l => l.trim().startsWith('|'));
-    if (lines.length < 3)
-        return []; // Need header + separator + at least one row
-    // Parse header to find column index
-    const headerCells = lines[0].split('|').map(c => c.trim()).filter(Boolean);
-    const colIndex = headerCells.findIndex(h => h.toLowerCase() === columnName.toLowerCase());
-    if (colIndex === -1)
-        return [];
-    // Skip header (line 0) and separator (line 1), parse data rows
+    const aliases = (Array.isArray(columnName) ? columnName : [columnName])
+        .map(name => name.trim().toLowerCase());
+    const tableBlocks = [];
+    let currentBlock = [];
+    for (const line of tableText.split('\n')) {
+        if (line.trim().startsWith('|')) {
+            currentBlock.push(line);
+        }
+        else if (currentBlock.length > 0) {
+            tableBlocks.push(currentBlock);
+            currentBlock = [];
+        }
+    }
+    if (currentBlock.length > 0)
+        tableBlocks.push(currentBlock);
+    const parseRow = (line) => {
+        let row = line.trim();
+        if (row.startsWith('|'))
+            row = row.slice(1);
+        if (row.endsWith('|'))
+            row = row.slice(0, -1);
+        return row.split('|').map(cell => cell.trim());
+    };
     const refs = [];
-    for (let i = 2; i < lines.length; i++) {
-        const cells = lines[i].split('|').map(c => c.trim()).filter(Boolean);
-        if (colIndex >= cells.length)
+    for (const lines of tableBlocks) {
+        const headerCells = parseRow(lines[0]);
+        const colIndex = headerCells.findIndex(header => {
+            const normalized = header.toLowerCase().replace(/[`*_]/g, '').trim();
+            return aliases.some(alias => normalized === alias ||
+                normalized.startsWith(`${alias} /`) ||
+                normalized.startsWith(`${alias} (`));
+        });
+        if (lines.length < 3 || colIndex === -1) {
+            // Legacy sidecars sometimes have headerless continuation rows or a
+            // generic table whose rows were extended with a final REF cell. The
+            // corpus snapshot has always treated every in-section table REF as an
+            // outgoing/incoming declaration, so retain that compatibility fallback.
+            const dataLines = lines.length >= 3 ? lines.slice(2) : lines;
+            for (const line of dataLines) {
+                NODE_ID_PATTERN.lastIndex = 0;
+                const refMatches = line.match(NODE_ID_PATTERN);
+                if (refMatches)
+                    refs.push(...refMatches);
+            }
             continue;
-        const value = cells[colIndex].trim();
-        // Skip empty, dash, or em-dash values
-        if (!value || value === '—' || value === '-' || value === '–')
-            continue;
-        // Extract node-id pattern(s) (REF-* or PROF-*) from the cell.
-        // Reset the lastIndex defensively — NODE_ID_PATTERN is a module-level
-        // /g RegExp shared across calls.
-        NODE_ID_PATTERN.lastIndex = 0;
-        const refMatches = value.match(NODE_ID_PATTERN);
-        if (refMatches) {
-            refs.push(...refMatches);
+        }
+        // Skip this table's header and separator, preserving all interior cells.
+        for (let i = 2; i < lines.length; i++) {
+            const cells = parseRow(lines[i]);
+            if (colIndex >= cells.length)
+                continue;
+            // Historical rows may expand the named REF cell into an issue/REF pair
+            // or append placeholder cells without extending the header. Scan from
+            // the named column through the remainder of the row; columns before the
+            // alias (title/authors/year) remain excluded.
+            const value = cells.slice(colIndex).join(' | ');
+            if (!value || value === '—' || value === '-' || value === '–')
+                continue;
+            NODE_ID_PATTERN.lastIndex = 0;
+            const refMatches = value.match(NODE_ID_PATTERN);
+            if (refMatches)
+                refs.push(...refMatches);
         }
     }
-    return refs;
+    return [...new Set(refs)];
 }
 /**
  * Parse a citation sidecar markdown file into structured edges.
@@ -102,17 +165,15 @@ export function parseCitationSidecar(content) {
     for (const section of sections) {
         const sectionLower = section.toLowerCase();
         if (sectionLower.startsWith('outgoing')) {
-            // Outgoing table: extract from "Inducted REF" column
-            cites = extractRefsFromTable(section, 'Inducted REF');
+            cites.push(...extractRefsFromTable(section, CITATION_REF_COLUMNS));
+            cites.push(...extractSectionNodeIds(section));
         }
         else if (sectionLower.startsWith('incoming')) {
-            // Incoming table: extract from "REF" column
-            // The incoming section may have subsections (### Corpus Cross-References)
-            // Look for tables anywhere in this section
-            citedBy = extractRefsFromTable(section, 'REF');
+            citedBy.push(...extractRefsFromTable(section, CITATION_REF_COLUMNS));
+            citedBy.push(...extractSectionNodeIds(section));
         }
     }
-    return { ref, cites, citedBy };
+    return { ref, cites: [...new Set(cites)], citedBy: [...new Set(citedBy)] };
 }
 /**
  * Convert a CitationParseResult into TypedEdge arrays for the dependency graph.

package/dist/src/artifacts/cli.js

@@ -134,7 +134,7 @@ function parseAiwgVersionFlag(args) {
         return undefined;
     const value = args[indices[0] + 1];
     if (!value || value.startsWith('--')) {
-        console.error('Error: --aiwg-version requires an exact calendar-semver version or channel name');
+        console.error('Error: --aiwg-version requires an exact calendar-semver version, SemVer range, sha256 digest, or channel name');
         process.exit(1);
     }
     try {
@@ -257,6 +257,9 @@ export async function main(args) {
         case 'dedup-report':
             await handleDedup(subcommandArgs);
             break;
+        case 'eval-discovery':
+            await handleEvalDiscovery(subcommandArgs);
+            break;
         case 'watch':
             await handleWatch(subcommandArgs);
             break;
@@ -283,7 +286,7 @@ export async function main(args) {
             break;
         default:
             console.error(`Error: Unknown index subcommand '${subcommand}'`);
-            console.log('Available: build, query, discover, show, export, sync, migrate-legacy, deps, stats, status, list, neighbors, set, embed, similar, dedup-report, watch');
+            console.log('Available: build, query, discover, show, export, sync, migrate-legacy, deps, stats, status, list, neighbors, set, embed, similar, dedup-report, eval-discovery, watch');
             process.exit(1);
     }
 }
@@ -306,6 +309,7 @@ function printIndexUsage() {
     console.log('  embed      Build the semantic embedding index for a graph (opt-in deps)');
     console.log('  similar    Semantic neighbors of a node (requires embed)');
     console.log('  dedup-report  Near-duplicate node pairs above a similarity threshold');
+    console.log('  eval-discovery  Benchmark operational capability discovery relevance');
     console.log('  watch      Start a filesystem watcher for automatic incremental index updates');
     console.log('');
     console.log('Options:');
@@ -332,9 +336,59 @@ function printIndexUsage() {
     console.log('  aiwg index deps .aiwg/requirements/UC-001.md');
     console.log('  aiwg index stats --json');
     console.log('  aiwg index stats --graph project');
+    console.log('  aiwg index eval-discovery --queries test/fixtures/artifacts/discovery-relevance.jsonl --backend local --strategy lexical');
     console.log('  aiwg index neighbors --graph citation-network --node REF-008 --direction in --edge-type cites');
     console.log('  aiwg index set --graph citation-network --op intersection --node-a REF-008 --node-b REF-016 --direction in');
 }
+async function handleEvalDiscovery(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log('Usage: aiwg index eval-discovery --queries <jsonl> --backend <local|fortemi-core> --strategy <lexical|dense|hybrid-rrf|rerank|chunk-multivector> [options]');
+        console.log('');
+        console.log('Options:');
+        console.log('  --queries <path>   Versioned relevance JSONL fixture (required)');
+        console.log('  --backend <name>   local or fortemi-core (required)');
+        console.log('  --strategy <name>  lexical, dense, hybrid-rrf, rerank, or chunk-multivector');
+        console.log('  --out <path>       Write the JSON report to a file');
+        console.log('  --json             Emit JSON instead of the readable summary');
+        return;
+    }
+    const queries = parseFlagValue(args, '--queries', 'Error: --queries requires a JSONL path');
+    if (!queries) {
+        console.error('Error: --queries is required');
+        process.exit(1);
+    }
+    const backend = parseFlagValue(args, '--backend', 'Error: --backend requires local or fortemi-core');
+    if (backend !== 'local' && backend !== 'fortemi-core') {
+        console.error('Error: --backend must be local or fortemi-core');
+        process.exit(1);
+    }
+    const strategy = parseFlagValue(args, '--strategy', 'Error: --strategy requires a value') ?? 'lexical';
+    const { DISCOVERY_EVAL_STRATEGIES, evaluateDiscovery, formatDiscoveryEvalSummary } = await import('./discovery-eval.js');
+    if (!DISCOVERY_EVAL_STRATEGIES.includes(strategy)) {
+        console.error(`Error: --strategy must be ${DISCOVERY_EVAL_STRATEGIES.join(', ')}`);
+        process.exit(1);
+    }
+    try {
+        const report = await evaluateDiscovery({
+            cwd: process.cwd(),
+            fixturePath: path.resolve(queries),
+            backend,
+            strategy: strategy,
+        });
+        const serialized = `${JSON.stringify(report, null, 2)}\n`;
+        const out = parseFlagValue(args, '--out', 'Error: --out requires a path');
+        if (out) {
+            const fs = await import('node:fs');
+            fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+            fs.writeFileSync(path.resolve(out), serialized);
+        }
+        console.log(args.includes('--json') ? serialized.trimEnd() : formatDiscoveryEvalSummary(report));
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+}
 /**
  * Handle 'index watch' command — filesystem watcher daemon for auto-index updates.
  *
@@ -1308,7 +1362,7 @@ async function handleDiscover(args) {
     if (!phrase) {
         console.error('Error: aiwg index discover requires a search phrase');
         console.log('');
-        console.log('Usage: aiwg index discover "<phrase>" [--type <kinds>] [--limit N] [--json|--format json|text] [--pretty|--compact] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <exact-or-channel>] [--offline]');
+        console.log('Usage: aiwg index discover "<phrase>" [--type <kinds>] [--limit N] [--json|--format json|text] [--pretty|--compact] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]');
         console.log('');
         console.log('Examples:');
         console.log('  aiwg index discover "create intake"');
@@ -1388,8 +1442,8 @@ async function handleShow(args) {
     }
     const HELP_TEXT = [
         '',
-        'Usage: aiwg show <type> <name> [--json] [--first] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <exact-or-channel>] [--offline]',
-        '       aiwg show metadata <id-or-name-or-path> [--json] [--first] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <exact-or-channel>] [--offline]',
+        'Usage: aiwg show <type> <name> [--json] [--first] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]',
+        '       aiwg show metadata <id-or-name-or-path> [--json] [--first] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]',
         '       aiwg index show <type> <name> ...',
         '',
         `Types: ${OPERATIONAL_SHOW_TYPES.join(' | ')}`,

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

@@ -108,6 +108,21 @@ export const DISCOVER_FACETS = [
         ],
         capabilities: ['new-project', 'new-bundle'],
     },
+    {
+        facet: 'feature-domain',
+        label: 'Project-local bundle lifecycle',
+        intents: [
+            'project-local bundle',
+            'create project-local bundle',
+            'deploy project-local bundle',
+            'doctor project-local bundle',
+            'promote bundle',
+            'promote project-local',
+            'graduate project-local bundle',
+            'graduate to upstream',
+        ],
+        capabilities: ['new-bundle', 'use', 'aiwg-doctor', 'promote'],
+    },
     {
         facet: 'provider-capability',
         label: 'Provider capability routing (native vs emulated)',

package/dist/src/artifacts/discovery-eval.js

@@ -0,0 +1,290 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { OPERATIONAL_DISCOVERY_TYPES } from './types.js';
+import { loadGraphIndexFile } from './index-reader.js';
+import { loadFortemiCoreExport, loadFortemiCoreMetadataEntries, scoreStaticRecord } from './fortemi-core-query-adapter.js';
+import { discoverCapability } from './query-engine.js';
+export const DISCOVERY_EVAL_SCHEMA = 'aiwg.discovery-relevance.v1';
+export const DISCOVERY_EVAL_REPORT_SCHEMA = 'aiwg.discovery-eval-report.v1';
+export const DISCOVERY_EVAL_STRATEGIES = ['lexical', 'dense', 'hybrid-rrf', 'rerank', 'chunk-multivector'];
+const round = (value, digits = 6) => {
+    const scale = 10 ** digits;
+    return Math.round(value * scale) / scale;
+};
+function percentile(values, p) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.ceil(p * sorted.length) - 1] ?? sorted[sorted.length - 1];
+}
+function stringArray(value, label, line) {
+    if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== 'string' || item.trim() === '')) {
+        throw new Error(`Discovery relevance fixture line ${line}: ${label} must be a non-empty string array`);
+    }
+    return value;
+}
+export function parseDiscoveryRelevanceJsonl(content) {
+    const records = [];
+    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 (error) {
+            throw new Error(`Discovery relevance fixture line ${line}: malformed JSON (${error instanceof Error ? error.message : String(error)})`);
+        }
+        if (value.schema !== DISCOVERY_EVAL_SCHEMA)
+            throw new Error(`Discovery relevance fixture line ${line}: unsupported schema`);
+        if (typeof value.id !== 'string' || value.id.trim() === '')
+            throw new Error(`Discovery relevance fixture line ${line}: id must be a non-empty string`);
+        if (ids.has(value.id))
+            throw new Error(`Discovery relevance fixture line ${line}: duplicate query id '${value.id}'`);
+        ids.add(value.id);
+        if (typeof value.query !== 'string' || value.query.trim() === '')
+            throw new Error(`Discovery relevance fixture line ${line}: query must be a non-empty string`);
+        if (!OPERATIONAL_DISCOVERY_TYPES.includes(String(value.target_type))) {
+            throw new Error(`Discovery relevance fixture line ${line}: invalid target_type '${String(value.target_type)}'`);
+        }
+        const classes = ['exact-name', 'capability', 'process-step', 'hard-negative', 'cross-type'];
+        if (!classes.includes(String(value.query_class)))
+            throw new Error(`Discovery relevance fixture line ${line}: invalid query_class '${String(value.query_class)}'`);
+        records.push({
+            schema: DISCOVERY_EVAL_SCHEMA, id: value.id, query: value.query,
+            target_type: value.target_type,
+            relevant_ids: stringArray(value.relevant_ids, 'relevant_ids', line),
+            hard_negative_ids: stringArray(value.hard_negative_ids, 'hard_negative_ids', line),
+            query_class: value.query_class,
+            ...(typeof value.notes === 'string' ? { notes: value.notes } : {}),
+        });
+    }
+    if (records.length === 0)
+        throw new Error('Discovery relevance fixture contains no queries');
+    return records;
+}
+export function validateOperationalCoverage(records, minimum = 10) {
+    for (const type of OPERATIONAL_DISCOVERY_TYPES) {
+        const count = records.filter((record) => record.target_type === type).length;
+        if (count < minimum)
+            throw new Error(`Discovery relevance fixture requires at least ${minimum} '${type}' queries; found ${count}`);
+    }
+}
+function terms(text) {
+    return [...new Set(text.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim().split(/\s+/).filter((term) => term.length > 1))];
+}
+function identity(entry) { return `${entry.type}:${entry.name ?? entry.title}`.toLowerCase(); }
+function matches(item, expected) {
+    const needle = expected.toLowerCase();
+    return item.id.toLowerCase() === needle || `${item.type}:${item.name}`.toLowerCase() === needle;
+}
+function fields(entry) {
+    return [entry.name ?? '', entry.title, entry.capability ?? '', entry.summary, ...(entry.triggers ?? []), ...(entry.searchTerms ?? []), entry.path].filter(Boolean);
+}
+function cosine(left, right) {
+    const a = terms(left);
+    const b = terms(right);
+    if (!a.length || !b.length)
+        return 0;
+    const set = new Set(b);
+    return a.filter((term) => set.has(term)).length / Math.sqrt(a.length * b.length);
+}
+function prototypeRank(entries, query, strategy, limit) {
+    const dense = entries.map((entry) => ({ entry, score: cosine(query, fields(entry).join(' ')) }));
+    const lexical = entries.map((entry) => {
+        const queryTerms = terms(query);
+        const values = fields(entry).map((field) => field.toLowerCase());
+        const hits = queryTerms.filter((term) => values.some((value) => value.includes(term))).length;
+        return { entry, score: (values.some((value) => value === query.toLowerCase()) ? 1 : 0) + (queryTerms.length ? hits / queryTerms.length : 0) };
+    });
+    let ranked;
+    if (strategy === 'dense')
+        ranked = dense;
+    else if (strategy === 'chunk-multivector')
+        ranked = entries.map((entry) => ({ entry, score: Math.max(...fields(entry).map((field) => cosine(query, field)), 0) }));
+    else if (strategy === 'rerank')
+        ranked = [...lexical].sort((a, b) => b.score - a.score).slice(0, 50)
+            .map((candidate) => ({ entry: candidate.entry, score: candidate.score + 0.35 * cosine(query, fields(candidate.entry).join(' ')) }));
+    else {
+        const fused = new Map();
+        for (const list of [lexical, dense]) {
+            [...list].sort((a, b) => b.score - a.score || identity(a.entry).localeCompare(identity(b.entry))).forEach((candidate, rank) => {
+                const key = identity(candidate.entry);
+                const current = fused.get(key) ?? { entry: candidate.entry, score: 0 };
+                current.score += 1 / (61 + rank);
+                fused.set(key, current);
+            });
+        }
+        ranked = [...fused.values()];
+    }
+    return ranked.filter((candidate) => candidate.score > 0)
+        .sort((a, b) => b.score - a.score || identity(a.entry).localeCompare(identity(b.entry))).slice(0, limit)
+        .map(({ entry, score }) => ({ id: identity(entry), type: entry.type, name: entry.name ?? entry.title, score: round(score) }));
+}
+async function currentRank(cwd, query, backend, limit) {
+    const output = [];
+    const original = console.log;
+    console.log = (...args) => output.push(args.map(String).join(' '));
+    try {
+        await discoverCapability(cwd, { phrase: query.query, typeFilter: [query.target_type], graph: 'framework', backend, limit, json: true, jsonPretty: false, includePaths: false });
+    }
+    finally {
+        console.log = original;
+    }
+    const envelope = JSON.parse(output.join(''));
+    return envelope.results.map((item) => ({ id: item.id, type: item.type, name: item.name ?? item.title, score: item.score }));
+}
+function fortemiStaticRank(exported, query, limit) {
+    const queryTerms = query.query.toLowerCase().split(/[^a-z0-9-]+/).map((term) => term.trim()).filter((term) => term.length > 2);
+    return exported.items
+        .filter((record) => (record.search?.type ?? record.type.replace(/^aiwg:/, '')) === query.target_type)
+        .map((record) => ({ record, ...scoreStaticRecord(record, queryTerms) }))
+        .filter((item) => item.score > 0)
+        .sort((a, b) => b.score - a.score || a.record.source.path.localeCompare(b.record.source.path))
+        .slice(0, limit)
+        .map(({ record, score }) => ({
+        id: `${query.target_type}:${record.name ?? record.search?.name ?? record.title}`.toLowerCase(),
+        type: query.target_type,
+        name: record.name ?? record.search?.name ?? record.title,
+        score: round(score),
+    }));
+}
+function loadEntries(cwd, backend) {
+    if (backend === 'fortemi-core') {
+        const loaded = loadFortemiCoreMetadataEntries(cwd, 'framework');
+        if (!loaded.entries.length)
+            throw new Error(loaded.reason ?? 'Fortemi Core framework index is empty');
+        return loaded.entries;
+    }
+    const index = loadGraphIndexFile(cwd, 'metadata.json', 'framework');
+    if (!index)
+        throw new Error('Local framework index is missing; run `aiwg index build --graph framework`');
+    return Object.values(index.entries);
+}
+export function calculateDiscoveryMetrics(records, resultSets) {
+    const ranks = records.map((record, index) => {
+        const rank = (resultSets[index] ?? []).findIndex((item) => record.relevant_ids.some((id) => matches(item, id)));
+        return rank < 0 ? null : rank + 1;
+    });
+    const hit = (k) => ranks.filter((rank) => rank !== null && rank <= k).length / records.length;
+    const perType = {};
+    for (const type of OPERATIONAL_DISCOVERY_TYPES) {
+        const selected = records.map((record, index) => ({ record, index })).filter(({ record }) => record.target_type === type);
+        perType[type] = round(selected.filter(({ index }) => ranks[index] !== null && ranks[index] <= 3).length / selected.length);
+    }
+    return {
+        query_count: records.length, hit_at_1: round(hit(1)), hit_at_3: round(hit(3)), hit_at_5: round(hit(5)),
+        mrr: round(ranks.reduce((sum, rank) => sum + (rank === null ? 0 : 1 / rank), 0) / records.length),
+        ndcg_at_10: round(ranks.reduce((sum, rank) => sum + (rank === null || rank > 10 ? 0 : 1 / Math.log2(rank + 1)), 0) / records.length),
+        per_type_recall_at_3: perType,
+        hard_negative_intrusion_at_5: round(records.filter((record, index) => (resultSets[index] ?? []).slice(0, 5)
+            .some((item) => record.hard_negative_ids.some((id) => matches(item, id)))).length / records.length),
+    };
+}
+function indexBytes(backend) {
+    const root = path.join(process.env.XDG_DATA_HOME ?? path.join(os.homedir(), '.local', 'share'), 'aiwg', 'index', ...(backend === 'local' ? ['framework'] : ['fortemi-core', 'framework']));
+    let total = 0;
+    const visit = (target) => {
+        if (!fs.existsSync(target))
+            return;
+        const stat = fs.statSync(target);
+        if (stat.isFile())
+            total += stat.size;
+        else
+            for (const child of fs.readdirSync(target))
+                visit(path.join(target, child));
+    };
+    visit(root);
+    return total;
+}
+export async function evaluateDiscovery(options) {
+    const records = parseDiscoveryRelevanceJsonl(fs.readFileSync(options.fixturePath, 'utf8'));
+    validateOperationalCoverage(records);
+    const limit = options.limit ?? 10;
+    const entries = loadEntries(options.cwd, options.backend);
+    const fortemiExport = options.backend === 'fortemi-core' && options.strategy === 'lexical'
+        ? loadFortemiCoreExport(options.cwd, 'framework')
+        : null;
+    if (fortemiExport && !fortemiExport.exported) {
+        throw new Error(fortemiExport.reason ?? 'Fortemi Core framework export is unavailable');
+    }
+    const resultSets = [];
+    const latencies = [];
+    let peakRss = process.memoryUsage().rss;
+    for (const record of records) {
+        const start = performance.now();
+        resultSets.push(options.strategy === 'lexical'
+            ? options.backend === 'fortemi-core'
+                ? fortemiStaticRank(fortemiExport.exported, record, limit)
+                : await currentRank(options.cwd, record, options.backend, limit)
+            : prototypeRank(entries.filter((entry) => entry.type === record.target_type), record.query, options.strategy, limit));
+        latencies.push(performance.now() - start);
+        peakRss = Math.max(peakRss, process.memoryUsage().rss);
+    }
+    const metrics = calculateDiscoveryMetrics(records, resultSets);
+    const cpus = os.cpus();
+    let parity;
+    if (options.backend === 'fortemi-core' && options.strategy === 'lexical') {
+        const localSets = [];
+        for (const record of records)
+            localSets.push(await currentRank(options.cwd, record, 'local', limit));
+        const differingQueries = [];
+        let topOneAgreements = 0;
+        let topFiveOverlap = 0;
+        for (let index = 0; index < records.length; index++) {
+            const fortemi = resultSets[index];
+            const local = localSets[index];
+            const key = (item) => item ? `${item.type}:${item.name}`.toLowerCase() : '';
+            if (key(fortemi[0]) === key(local[0]))
+                topOneAgreements++;
+            else
+                differingQueries.push(records[index].id);
+            const localFive = new Set(local.slice(0, 5).map((item) => key(item)));
+            topFiveOverlap += fortemi.slice(0, 5).filter((item) => localFive.has(key(item))).length / Math.max(1, Math.min(5, local.length, fortemi.length));
+        }
+        parity = {
+            compared_to: 'local:lexical',
+            top_1_agreement: round(topOneAgreements / records.length),
+            top_5_overlap: round(topFiveOverlap / records.length),
+            differing_queries: differingQueries,
+        };
+    }
+    return {
+        schema: DISCOVERY_EVAL_REPORT_SCHEMA,
+        corpus: { path: path.relative(options.cwd, options.fixturePath).replace(/\\/g, '/'), schema: DISCOVERY_EVAL_SCHEMA, query_count: records.length },
+        configuration: { backend: options.backend, strategy: options.strategy, limit, graph: 'framework' },
+        hardware: { platform: os.platform(), arch: os.arch(), cpu_model: cpus[0]?.model ?? 'unknown', logical_cpus: cpus.length, total_memory_bytes: os.totalmem(), node: process.version },
+        metrics,
+        performance: { p50_latency_ms: round(percentile(latencies, 0.5), 3), p95_latency_ms: round(percentile(latencies, 0.95), 3), index_bytes: indexBytes(options.backend), peak_resident_memory_bytes: peakRss },
+        ...(parity ? { parity } : {}),
+        adoption_gate: {
+            baseline: 'local:lexical', no_per_type_hit_at_3_regression: null, aggregate_mrr_improvement: null,
+            mrr_95pct_confidence_interval: null, latency_ceiling_ms: options.latencyCeilingMs ?? 250,
+            storage_ceiling_ratio: options.storageCeilingRatio ?? 2, clears_gate: null,
+            decision: 'Run the full strategy matrix and compare against local:lexical before adoption.',
+        },
+        queries: records.map((record, index) => {
+            const rank = resultSets[index].findIndex((item) => record.relevant_ids.some((id) => matches(item, id)));
+            return { id: record.id, target_type: record.target_type, relevant_rank: rank < 0 ? null : rank + 1, reciprocal_rank: rank < 0 ? 0 : round(1 / (rank + 1)), latency_ms: round(latencies[index], 3), results: resultSets[index] };
+        }),
+    };
+}
+export function formatDiscoveryEvalSummary(report) {
+    const m = report.metrics;
+    return [
+        `Discovery evaluation: ${report.configuration.backend}:${report.configuration.strategy}`,
+        `Corpus: ${report.corpus.query_count} queries (${report.corpus.path})`, '',
+        'Metric                Value', `Hit@1                 ${m.hit_at_1.toFixed(4)}`, `Hit@3                 ${m.hit_at_3.toFixed(4)}`,
+        `Hit@5                 ${m.hit_at_5.toFixed(4)}`, `MRR                   ${m.mrr.toFixed(4)}`, `nDCG@10               ${m.ndcg_at_10.toFixed(4)}`,
+        `Hard-negative@5       ${m.hard_negative_intrusion_at_5.toFixed(4)}`, `p50 latency           ${report.performance.p50_latency_ms.toFixed(3)} ms`,
+        `p95 latency           ${report.performance.p95_latency_ms.toFixed(3)} ms`, `Index bytes           ${report.performance.index_bytes}`,
+        `Peak resident memory  ${report.performance.peak_resident_memory_bytes}`, '', 'Per-type Hit@3:',
+        ...Object.entries(m.per_type_recall_at_3).map(([type, value]) => `  ${type.padEnd(10)} ${value.toFixed(4)}`), '',
+        `Decision: ${report.adoption_gate.decision}`,
+    ].join('\n');
+}
+//# sourceMappingURL=discovery-eval.js.map

package/dist/src/artifacts/fortemi-core-query-adapter.js

@@ -19,7 +19,7 @@ function includesAny(text, terms) {
     }
     return matches;
 }
-function scoreStaticRecord(record, terms) {
+export function scoreStaticRecord(record, terms) {
     const fields = [
         { name: "title", text: record.title, weight: 3 },
         { name: "name", text: record.name ?? record.search?.name ?? "", weight: 3 },

package/dist/src/artifacts/fortemi-shard-export.js

@@ -5,7 +5,7 @@ async function loadFortemiShardConverter() {
     let core;
     try {
         core = (await import(
-        /* @vite-ignore */ "@fortemi/core/aiwg-index"));
+        /* @vite-ignore */ "@fortemi/core/aiwg-index-shard"));
     }
     catch {
         throw new Error("Portable Fortemi shard export requires @fortemi/core with aiwgFortemiIndexToKnowledgeShard.");