@aiwg/cli 2026.10.3 → 2026.10.5

package/dist/src/artifacts/corpus-views/ref-parser.js

@@ -326,11 +326,13 @@ export function loadCorpus(root) {
         const venue = classifyFirst(`${venueRaw ?? ''} ${text.slice(0, 3500)}`.toLowerCase(), VENUE_PATTERNS) ||
             (venueRaw ? String(venueRaw).trim() : null);
         const { tier, paramsM } = extractParams(text);
+        const radar = extractRadar(root, refId);
         records.push({
             refId,
             sourceType: normalizeSourceType({ type: asStr(fm.type), sourceType: asStr(fm.source_type), venue }, srcTypeReg),
             referencedByProjects: extractReferencedByProjects(text),
             title: extractTitle(text, fm),
+            grade: radar?.gradeCurrent ?? asStr(fm.grade),
             path: filePath,
             year: extractYear(text, fm, citation),
             authors,
@@ -343,7 +345,7 @@ export function loadCorpus(root) {
             paramsM,
             incoming,
             outgoing,
-            radar: extractRadar(root, refId),
+            radar,
             discovery: extractDiscovery(citation),
             funders: extractFunders(citation),
         });

package/dist/src/artifacts/corpus-views/renderers.js

@@ -242,9 +242,9 @@ function renderPipeline(ctx) {
 // Cadence → window math lives in corpus-config.ts (the one staleness helper, #1498/#1502).
 /** GRADE display order; unknown grades fall after, 'Ungraded' last. */
 const GRADE_ORDER = ['A', 'A-', 'B', 'B-', 'C', 'C-', 'D'];
-/** Papers grouped by current GRADE (radar `grade-current`); no-radar → Ungraded. (#1492) */
+/** Papers grouped by current GRADE, falling back to reference frontmatter. */
 function renderByGrade(ctx) {
-    const groups = groupBy(ctx.records, (r) => [r.radar?.gradeCurrent || 'Ungraded']);
+    const groups = groupBy(ctx.records, (r) => [r.grade || 'Ungraded']);
     const lines = header('Index: Papers by GRADE', ctx, ctx.records.length);
     const names = [...groups.keys()].sort((a, b) => {
         if (a === 'Ungraded')
@@ -284,7 +284,7 @@ function renderStaleQueue(ctx) {
     const lines = header('Index: Radar Stale-Refresh Queue', ctx, ctx.records.length);
     lines.push(`Overdue = days since last refresh minus the cadence window. ${staleCount} of ${rows.length} radar-tracked papers are overdue.`, '', '| REF | Title | GRADE | Cadence | Last Refreshed | Overdue (days) | Stale |', '|---|---|---|---|---|---:|---|');
     for (const { r, cadence, last, overdue } of sorted) {
-        lines.push(`| ${r.refId} | ${r.title.slice(0, 70)} | ${r.radar.gradeCurrent ?? '—'} | ${cadence} | ${last} | ${overdue} | ${overdue > 0 ? 'yes' : 'no'} |`);
+        lines.push(`| ${r.refId} | ${r.title.slice(0, 70)} | ${r.grade ?? '—'} | ${cadence} | ${last} | ${overdue} | ${overdue > 0 ? 'yes' : 'no'} |`);
     }
     return lines.join('\n') + '\n';
 }

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

@@ -2,7 +2,8 @@ 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 { getGraphIndexDir, OPERATIONAL_DISCOVERY_TYPES } from './types.js';
+import { getFrameworkIndexBaseDir } from './framework-index-paths.js';
 import { loadGraphIndexFile } from './index-reader.js';
 import { loadFortemiCoreExport, loadFortemiCoreMetadataEntries, scoreStaticRecord } from './fortemi-core-query-adapter.js';
 import { discoverCapability } from './query-engine.js';
@@ -185,8 +186,9 @@ export function calculateDiscoveryMetrics(records, resultSets) {
             .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']));
+function indexBytes(cwd, backend) {
+    const root = backend === 'local' ? getGraphIndexDir(cwd, 'framework')
+        : path.join(getFrameworkIndexBaseDir(cwd), 'fortemi-core', 'framework');
     let total = 0;
     const visit = (target) => {
         if (!fs.existsSync(target))
@@ -259,7 +261,7 @@ export async function evaluateDiscovery(options) {
         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 },
+        performance: { p50_latency_ms: round(percentile(latencies, 0.5), 3), p95_latency_ms: round(percentile(latencies, 0.95), 3), index_bytes: indexBytes(options.cwd, 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,

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

@@ -1,7 +1,11 @@
+import { selectPrebuiltRelations } from './relations.js';
+import { resolveFrameworkIndexRoot } from './framework-index-paths.js';
+import { extractRuleBindings } from './index-builder.js';
 import fs from "node:fs";
 import { createHash } from "node:crypto";
 import { bm25Rank } from "./fulltext.js";
-import { getFortemiCorePrebuiltStatus, getFortemiCoreSyncStatus } from "./fortemi-core-sync.js";
+import { consumeFortemiCoreExport, getFortemiCorePrebuiltStatus, getFortemiCoreSyncStatus } from "./fortemi-core-sync.js";
+import { loadGraphIndexFile } from "./index-reader.js";
 import { operationalStateQueryProjection, } from "./operational-state.js";
 function tokenize(text) {
     return text
@@ -167,6 +171,14 @@ export function loadFortemiCoreExport(cwd, graph = "project", sourcePaths) {
             };
         }
     }
+    // A content-validated shipped corpus does not need the source metadata index.
+    // This also avoids preferring a much larger locally materialized text cache.
+    if (graph === 'framework' && selectPrebuiltRelations(cwd).reader) {
+        const prebuilt = getFortemiCorePrebuiltStatus(graph, resolveFrameworkIndexRoot(cwd));
+        if (prebuilt.built && !prebuilt.stale) {
+            return { exported: JSON.parse(fs.readFileSync(prebuilt.exportPath, 'utf8')) };
+        }
+    }
     let status = getFortemiCoreSyncStatus(cwd, graph);
     // The packaged framework index is a bootstrap fallback for an absent shared
     // cache. Once a shared cache exists, its stale state proves that the local
@@ -178,6 +190,20 @@ export function loadFortemiCoreExport(cwd, graph = "project", sourcePaths) {
             status = prebuilt;
         }
     }
+    // A packaged bootstrap cache can also predate a source checkout's index.
+    // Validate it against the same current data as the shared cache before use.
+    if (status.source === "prebuilt") {
+        const current = loadGraphIndexFile(cwd, "metadata.json", graph);
+        if (current &&
+            Date.parse(current.builtAt) > Date.parse(status.sourceIndexBuiltAt ?? status.generatedAt ?? "")) {
+            status = {
+                ...status,
+                stale: true,
+                sourceIndexNewer: true,
+                reason: "source index is newer than the Fortemi Core static cache",
+            };
+        }
+    }
     if (!status.optedIn) {
         return {
             reason: `Fortemi Core static index is not materialized for graph '${graph}'. Run 'aiwg index sync${graph === "project" ? "" : ` --graph ${graph}`}' first, or pass '--backend local' to use the legacy local index.`,
@@ -185,12 +211,13 @@ export function loadFortemiCoreExport(cwd, graph = "project", sourcePaths) {
     }
     if (!status.built || status.stale) {
         return {
+            ...(status.sourceIndexNewer ? { sourceIndexNewer: true } : {}),
             reason: `${status.reason ??
                 `Fortemi Core static index for graph '${graph}' is stale or incomplete`}. Re-run 'aiwg index sync${graph === "project" ? "" : ` --graph ${graph}`}' or pass '--backend local' to use the legacy local index.`,
         };
     }
     try {
-        const exported = JSON.parse(fs.readFileSync(status.exportPath, "utf-8"));
+        const exported = consumeFortemiCoreExport(status.exportPath, status.exportChecksum);
         if (exported.schema_version !== "aiwg.fortemi.index.export.v2") {
             return {
                 reason: `Fortemi Core static index has schema '${exported.schema_version}', expected 'aiwg.fortemi.index.export.v2'. Re-run 'aiwg index sync'.`,
@@ -255,13 +282,19 @@ function entryFromRecord(record) {
             && typeof indexedScript.runtime === "string"
             ? indexedScript
             : undefined,
+        ...extractRuleBindings(indexedFrontmatter),
+        ...(Array.isArray(indexedFrontmatter.aiwg_governed_paths) ? { governedPaths: indexedFrontmatter.aiwg_governed_paths.filter((value) => typeof value === "string") } : {}),
         operationalState: record.operational_state,
     };
 }
 export function loadFortemiCoreMetadataEntries(cwd, graph = "project", sourcePaths) {
     const loaded = loadFortemiCoreExport(cwd, graph, sourcePaths);
     if (!loaded.exported)
-        return { entries: [], reason: loaded.reason };
+        return {
+            entries: [],
+            reason: loaded.reason,
+            ...(loaded.sourceIndexNewer ? { sourceIndexNewer: true } : {}),
+        };
     return { entries: loaded.exported.items.map(entryFromRecord) };
 }
 export async function queryFortemiCoreAiwgDiscovery(cwd, options) {

package/dist/src/artifacts/fortemi-core-sync.js

@@ -1,15 +1,18 @@
 import fs from "node:fs";
 import path from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { parse as parseYaml } from "yaml";
 import { GRAPH_CONFIGS, getProjectIndexRoot, loadGlobalGraphConfigs } from "./types.js";
 import { buildAiwgFortemiIndexExport, } from "./browser-export.js";
 import { loadGraphIndexFile } from "./index-reader.js";
+import { getFrameworkIndexBaseDir } from './framework-index-paths.js';
 function syncDir(cwd, graph) {
     loadGlobalGraphConfigs();
+    if (graph === 'framework')
+        return path.join(getFrameworkIndexBaseDir(cwd), 'fortemi-core', graph);
     const config = GRAPH_CONFIGS[graph];
-    if (graph === "framework" || config?.shared) {
+    if (config?.shared) {
         const xdgData = process.env.XDG_DATA_HOME ?? path.join(process.env.HOME ?? cwd, ".local", "share");
         return path.join(xdgData, "aiwg", "index", "fortemi-core", graph);
     }
@@ -36,6 +39,47 @@ function prebuiltDir(graph) {
 function sha256(text) {
     return createHash("sha256").update(text).digest("hex");
 }
+// Status checks and the query reader often inspect the same large export.
+// Keep at most two private snapshots, and never retain an object exposed to a
+// caller: query results have always been fresh, mutable objects.
+const exportSnapshots = new Map();
+function exportSignature(file) {
+    const stat = fs.statSync(file, { bigint: true });
+    return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
+}
+function readExportSnapshot(file, expectedChecksum) {
+    const signature = exportSignature(file);
+    const cached = exportSnapshots.get(file);
+    // The manifest checksum is part of the snapshot identity. Filesystems may
+    // preserve every stat field across a same-size rewrite within one timestamp
+    // tick, while the manifest already names the replacement's checksum.
+    if (cached?.signature === signature &&
+        cached.checksum === expectedChecksum)
+        return cached;
+    exportSnapshots.delete(file);
+    const text = fs.readFileSync(file, "utf-8");
+    const exported = JSON.parse(text);
+    const snapshot = { signature, exported, checksum: sha256(text) };
+    // A concurrent replacement cannot publish a snapshot under the wrong stamp.
+    if (exportSignature(file) === signature) {
+        exportSnapshots.set(file, snapshot);
+        while (exportSnapshots.size > 2)
+            exportSnapshots.delete(exportSnapshots.keys().next().value);
+    }
+    return snapshot;
+}
+/** Transfer a checked snapshot to the query reader without sharing mutable results. */
+export function consumeFortemiCoreExport(file, expectedChecksum) {
+    try {
+        const snapshot = readExportSnapshot(file, expectedChecksum);
+        if (snapshot.checksum !== expectedChecksum)
+            throw new Error("export checksum does not match manifest");
+        return snapshot.exported;
+    }
+    finally {
+        exportSnapshots.delete(file);
+    }
+}
 function readManifest(manifestPath) {
     return readManifestResult(manifestPath).manifest;
 }
@@ -59,11 +103,91 @@ function sourceIndexBuiltAt(cwd, graph) {
     const index = loadGraphIndexFile(cwd, "metadata.json", graph);
     return typeof index?.builtAt === "string" ? index.builtAt : null;
 }
+/**
+ * Emit the v2 JSON document without stringifying a collection or a whole record.
+ * Strings are escaped in bounded slices too: a single large text field must not
+ * reintroduce V8's string limit. Preserve pretty-print bytes for stable checksums.
+ */
+function* jsonTokens(value, maxChars, depth = 0, ancestors = new Set()) {
+    if (value && typeof value === "object" && "toJSON" in value && typeof value.toJSON === "function") {
+        value = value.toJSON();
+    }
+    if (typeof value === "string") {
+        yield '"';
+        const sliceChars = Math.floor(maxChars / 6); // A control character can expand to \uXXXX.
+        for (let start = 0; start < value.length;) {
+            let end = Math.min(start + sliceChars, value.length);
+            // Keep surrogate pairs together, including when UTF-8 encoding each write.
+            if (end < value.length && /[\uD800-\uDBFF]/.test(value[end - 1]) && /[\uDC00-\uDFFF]/.test(value[end]))
+                end--;
+            yield JSON.stringify(value.slice(start, end)).slice(1, -1);
+            start = end;
+        }
+        yield '"';
+    }
+    else if (value && typeof value === "object") {
+        if (ancestors.has(value))
+            throw new TypeError("Converting circular structure to JSON");
+        ancestors.add(value);
+        const array = Array.isArray(value);
+        const entries = Array.isArray(value) ? value.map((item, index) => [String(index), item])
+            : Object.entries(value).filter(([, item]) => item !== undefined && typeof item !== "function" && typeof item !== "symbol");
+        yield array ? "[" : "{";
+        for (let i = 0; i < entries.length; i++) {
+            yield (i === 0 ? "\n" : ",\n") + "  ".repeat(depth + 1);
+            const [key, item] = entries[i];
+            if (!array) {
+                yield* jsonTokens(key, maxChars, depth + 1, ancestors);
+                yield ": ";
+            }
+            yield* jsonTokens(item, maxChars, depth + 1, ancestors);
+        }
+        if (entries.length)
+            yield "\n" + "  ".repeat(depth);
+        yield array ? "]" : "}";
+        ancestors.delete(value);
+    }
+    else {
+        yield JSON.stringify(value) ?? "null";
+    }
+}
+/** Write and hash the same bounded chunks; publish only complete exports. */
+function writeExport(file, exported, maxChars) {
+    const hash = createHash("sha256");
+    const fd = fs.openSync(file, "w");
+    try {
+        const flush = (chunk) => {
+            const bytes = Buffer.from(chunk, "utf-8");
+            hash.update(bytes);
+            for (let offset = 0; offset < bytes.length;)
+                offset += fs.writeSync(fd, bytes, offset, bytes.length - offset);
+        };
+        let pending = "";
+        for (const token of jsonTokens(exported, maxChars)) {
+            if (pending.length + token.length > maxChars) {
+                flush(pending);
+                pending = "";
+            }
+            pending += token;
+        }
+        flush(pending);
+        flush("\n");
+        return hash.digest("hex");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 export function syncFortemiCoreIndex(cwd, options = {}) {
     const graph = options.graph ?? "project";
     const dir = syncDir(cwd, graph);
     const exportPath = path.join(dir, "aiwg-fortemi-index-v2.json");
     const manifestPath = path.join(dir, "manifest.json");
+    const maxChars = options.maxChunkChars ?? 64 * 1024;
+    if (!Number.isSafeInteger(maxChars) || maxChars < 64)
+        throw new Error("maxChunkChars must be an integer of at least 64");
+    fs.mkdirSync(dir, { recursive: true });
+    const temporaryPath = path.join(dir, `.export-${randomUUID()}.tmp`);
     const previous = readManifest(manifestPath);
     const sourceBuiltAt = sourceIndexBuiltAt(cwd, graph);
     const buildExport = (generatedAt) => {
@@ -74,12 +198,11 @@ export function syncFortemiCoreIndex(cwd, options = {}) {
             generatedAt,
             schemaVersion: "v2",
         });
-        const json = JSON.stringify(exported, null, 2) + "\n";
+        const checksum = writeExport(temporaryPath, exported, maxChars);
         const recordsWithConcepts = exported.items.filter((item) => (item.skos_concepts?.length ?? 0) > 0).length;
         return {
             generatedAt,
-            json,
-            checksum: sha256(json),
+            checksum,
             itemCount: exported.items.length,
             skosCoverage: {
                 records_with_concepts: recordsWithConcepts,
@@ -91,36 +214,40 @@ export function syncFortemiCoreIndex(cwd, options = {}) {
             },
         };
     };
-    let built = buildExport(options.generatedAt ?? previous?.generated_at ?? new Date().toISOString());
-    let status = "created";
-    if (previous) {
-        if (previous.export_checksum === built.checksum) {
-            status = "unchanged";
-        }
-        else {
-            status = "updated";
-            if (options.generatedAt === undefined) {
-                built = buildExport(new Date().toISOString());
+    try {
+        let built = buildExport(options.generatedAt ?? previous?.generated_at ?? new Date().toISOString());
+        let status = "created";
+        if (previous) {
+            if (previous.export_checksum === built.checksum) {
+                status = "unchanged";
+            }
+            else {
+                status = "updated";
+                if (options.generatedAt === undefined) {
+                    built = buildExport(new Date().toISOString());
+                }
             }
         }
+        fs.renameSync(temporaryPath, exportPath);
+        const manifest = {
+            schema_version: "aiwg.fortemi.core-sync.v1",
+            backend: "fortemi-core",
+            graph,
+            generated_at: built.generatedAt,
+            export_path: path.relative(cwd, exportPath),
+            export_schema_version: "aiwg.fortemi.index.export.v2",
+            export_checksum: built.checksum,
+            item_count: built.itemCount,
+            skos_coverage: built.skosCoverage,
+            status,
+            source_index_built_at: sourceBuiltAt,
+        };
+        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+        return manifest;
+    }
+    finally {
+        fs.rmSync(temporaryPath, { force: true });
     }
-    fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(exportPath, built.json, "utf-8");
-    const manifest = {
-        schema_version: "aiwg.fortemi.core-sync.v1",
-        backend: "fortemi-core",
-        graph,
-        generated_at: built.generatedAt,
-        export_path: path.relative(cwd, exportPath),
-        export_schema_version: "aiwg.fortemi.index.export.v2",
-        export_checksum: built.checksum,
-        item_count: built.itemCount,
-        skos_coverage: built.skosCoverage,
-        status,
-        source_index_built_at: sourceBuiltAt,
-    };
-    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
-    return manifest;
 }
 export function getFortemiCoreSyncStatus(cwd, graph = "project") {
     const dir = syncDir(cwd, graph);
@@ -149,9 +276,8 @@ export function getFortemiCoreSyncStatus(cwd, graph = "project") {
     let exportChecksumMatches = false;
     if (exportExists) {
         try {
-            const exportText = fs.readFileSync(exportPath, "utf-8");
-            const exported = JSON.parse(exportText);
-            exportChecksumMatches = sha256(exportText) === manifest.export_checksum;
+            const { exported, checksum } = readExportSnapshot(exportPath, manifest.export_checksum);
+            exportChecksumMatches = checksum === manifest.export_checksum;
             if (exportChecksumMatches) {
                 if (exported.schema_version !== manifest.export_schema_version) {
                     exportReadReason = `export schema '${exported.schema_version}' does not match manifest '${manifest.export_schema_version}'`;
@@ -182,6 +308,7 @@ export function getFortemiCoreSyncStatus(cwd, graph = "project") {
         exportPath,
         built: exportExists,
         stale,
+        ...(sourceIsNewer ? { sourceIndexNewer: true } : {}),
         itemCount: manifest.item_count,
         exportChecksum: manifest.export_checksum,
         generatedAt: manifest.generated_at,
@@ -195,8 +322,8 @@ export function getFortemiCoreSyncStatus(cwd, graph = "project") {
                     : null,
     };
 }
-export function getFortemiCorePrebuiltStatus(graph = "framework") {
-    const dir = prebuiltDir(graph) ?? path.join(process.cwd(), "prebuilt", "fortemi-core", graph);
+export function getFortemiCorePrebuiltStatus(graph = "framework", packageRoot) {
+    const dir = (packageRoot ? path.join(packageRoot, "prebuilt", "fortemi-core", graph) : prebuiltDir(graph)) ?? path.join(process.cwd(), "prebuilt", "fortemi-core", graph);
     const manifestPath = path.join(dir, "manifest.json");
     const exportPath = path.join(dir, "aiwg-fortemi-index-v2.json");
     const { manifest, reason: manifestReadReason } = readManifestResult(manifestPath);
@@ -222,8 +349,7 @@ export function getFortemiCorePrebuiltStatus(graph = "framework") {
     let reason = null;
     if (exportExists) {
         try {
-            const exportText = fs.readFileSync(exportPath, "utf-8");
-            const exported = JSON.parse(exportText);
+            const { exported, checksum } = readExportSnapshot(exportPath, prebuiltManifest.export_checksum);
             if (prebuiltManifest.schema_version !== "aiwg.fortemi.prebuilt.v1" ||
                 prebuiltManifest.backend !== "fortemi-core" ||
                 prebuiltManifest.graph !== graph ||
@@ -231,7 +357,7 @@ export function getFortemiCorePrebuiltStatus(graph = "framework") {
                 prebuiltManifest.export_schema_version !== "aiwg.fortemi.index.export.v2") {
                 reason = "prebuilt manifest is incompatible with the requested graph";
             }
-            else if (sha256(exportText) !== prebuiltManifest.export_checksum) {
+            else if (checksum !== prebuiltManifest.export_checksum) {
                 reason = "prebuilt export checksum does not match manifest";
             }
             else if (exported.schema_version !== prebuiltManifest.export_schema_version) {

package/dist/src/artifacts/framework-capabilities.js

@@ -0,0 +1,171 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { getGraphIndexDir } from './types.js';
+import { frameworkSourceDigest } from './framework-source-digest.js';
+import { acquireDirectoryLock, DirectoryLockContentionError } from './prebuilt-build-lock.js';
+import { FRAMEWORK_CORPUS_KINDS as CORPUS_KINDS, resolveFrameworkCorpusRoot } from './framework-index-paths.js';
+export { resolveFrameworkCorpusRoot } from './framework-index-paths.js';
+function readText(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/** Resolve HEAD without spawning git, including worktrees and packed refs. */
+function gitHead(root) {
+    let gitDir = path.join(root, '.git');
+    const pointer = readText(gitDir).trim();
+    if (pointer.startsWith('gitdir: '))
+        gitDir = path.resolve(root, pointer.slice(8));
+    const head = readText(path.join(gitDir, 'HEAD')).trim();
+    if (!head.startsWith('ref: '))
+        return head;
+    const ref = head.slice(5);
+    const common = readText(path.join(gitDir, 'commondir')).trim();
+    const commonDir = common ? path.resolve(gitDir, common) : gitDir;
+    return readText(path.join(gitDir, ref)).trim()
+        || readText(path.join(commonDir, ref)).trim()
+        || readText(path.join(commonDir, 'packed-refs')).split('\n').find(line => line.endsWith(` ${ref}`))
+        || head;
+}
+/**
+ * Root/version identity plus the portable corpus digest. Its per-root stat
+ * receipt avoids rereading unchanged source contents and detects uncommitted
+ * edits as well as manifest/package/HEAD changes.
+ */
+function sourceFingerprint(root) {
+    const hash = createHash('sha256').update('framework-capabilities-v2');
+    hash.update(path.resolve(root));
+    try {
+        hash.update(JSON.parse(readText(path.join(root, 'package.json'))).version ?? '');
+    }
+    catch { /* fixture root */ }
+    hash.update(gitHead(root));
+    hash.update(frameworkSourceDigest(root));
+    for (const kind of CORPUS_KINDS) {
+        const dir = path.join(root, 'agentic/code', kind);
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        hash.update(kind).update(readText(path.join(dir, 'manifest.json')));
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            hash.update(entry.name).update(readText(path.join(dir, entry.name, 'manifest.json')));
+        }
+    }
+    return hash.digest('hex');
+}
+/** Stat signatures also notice manual rebuilds, deleted caches, and replacement indexes. */
+function fileSignature(file) {
+    try {
+        const stat = fs.statSync(file, { bigint: true });
+        return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+    }
+    catch {
+        return '';
+    }
+}
+function readReceipt(file) {
+    try {
+        return JSON.parse(readText(file));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reconcile only when a cheap source/index receipt changes. Contenders serve an
+ * existing index after a short wait; cold starts wait for the first builder.
+ * The shared directory lock recovers owners proven dead on this host.
+ */
+export async function refreshFrameworkCapabilities(root, syncFortemi = true, options = {}) {
+    const corpusRoot = resolveFrameworkCorpusRoot(root);
+    if (!corpusRoot)
+        return;
+    root = corpusRoot;
+    const dir = getGraphIndexDir(root, 'framework');
+    const receiptPath = path.join(dir, 'capability-sources.json');
+    const metadataPath = path.join(dir, 'metadata.json');
+    const fortemiDir = path.join(path.dirname(dir), 'fortemi-core', 'framework');
+    const fortemiSignature = () => [
+        'manifest.json', 'aiwg-fortemi-index-v2.json',
+    ].map(file => fileSignature(path.join(fortemiDir, file))).join('|');
+    const source = sourceFingerprint(root);
+    const current = () => ({
+        source, index: fileSignature(metadataPath), relations: fileSignature(path.join(dir, 'relations.json')), ...(syncFortemi ? { fortemi: fortemiSignature() } : {}),
+    });
+    const matches = (receipt, probe) => Boolean(!options.force && receipt && probe.index && probe.relations && receipt.relations === probe.relations && receipt.source === probe.source
+        && receipt.index === probe.index && (!syncFortemi || receipt.fortemi === probe.fortemi));
+    if (matches(readReceipt(receiptPath), current()))
+        return;
+    let release;
+    try {
+        release = await acquireDirectoryLock(path.join(dir, 'capability-refresh.lock'), {
+            timeoutMs: fs.existsSync(metadataPath) ? 150 : 60_000,
+            pollMs: 25,
+            reclaimDeadOwner: true,
+        });
+    }
+    catch (error) {
+        if (error instanceof DirectoryLockContentionError && fs.existsSync(metadataPath))
+            return;
+        throw error;
+    }
+    try {
+        // Another process may have completed reconciliation while we waited.
+        const receipt = readReceipt(receiptPath);
+        const probe = current();
+        if (matches(receipt, probe))
+            return;
+        if (options.force || !receipt || !probe.index || receipt.source !== source || receipt.index !== probe.index || !probe.relations || receipt.relations !== probe.relations) {
+            const { buildIndex } = await import('./index-builder.js');
+            await buildIndex(root, { graph: 'framework', explicit: false, quiet: true });
+        }
+        // A forced source scan can be a no-op. The prior successful receipt still
+        // validates the exact index/export files, so avoid hashing the export again.
+        const updated = current();
+        const cacheUnchanged = receipt && updated.index && receipt.source === source
+            && receipt.index === updated.index && receipt.fortemi === updated.fortemi;
+        if (syncFortemi && !cacheUnchanged) {
+            const { getFortemiCoreSyncStatus, syncFortemiCoreIndex } = await import('./fortemi-core-sync.js');
+            const status = getFortemiCoreSyncStatus(root, 'framework');
+            const indexChanged = receipt?.index ? receipt.index !== updated.index : probe.index !== updated.index;
+            if (indexChanged || !status.built || status.stale)
+                syncFortemiCoreIndex(root, { graph: 'framework' });
+        }
+        // Publish only after success. A failed rebuild/sync is retried next call.
+        const temp = `${receiptPath}.${process.pid}.tmp`;
+        fs.writeFileSync(temp, JSON.stringify(current()));
+        fs.renameSync(temp, receiptPath);
+    }
+    finally {
+        await release();
+    }
+}
+/** Installation is recorded in project config, independently of index coverage. */
+export async function isCorpusBundleInstalled(cwd, root, kind, id) {
+    if (!kind || !id)
+        return false;
+    const { readAiwgConfigCandidate } = await import('../config/aiwg-config.js');
+    const config = await readAiwgConfigCandidate(cwd);
+    if (!config)
+        return false;
+    if (config.installed[id] || (kind === 'framework' && config.installed.all))
+        return true;
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(root, 'agentic/code', `${kind}s`, id, 'manifest.json'), 'utf8'));
+        return (manifest.modeAliases ?? []).some(alias => Boolean(config.installed[alias]));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=framework-capabilities.js.map