@aiwg/cli 2026.10.5 → 2026.10.6

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

@@ -18,7 +18,7 @@ import { parseDecisionJson, parseDecisionYaml } from '../decision/entry.js';
 import { validateGateDocument } from '../gates/schema.js';
 import { INDEX_EXTRACTOR_VERSION, INDEX_VERSION, INDEX_DIR, OPERATIONAL_DISCOVERY_TYPES, PHASE_DIRECTORIES, GRAPH_CONFIGS, TEMPLATE_INDEX_EXTENSIONS, resolveGraphScanDir, loadUserGraphConfigs, loadGlobalGraphConfigs, resolveGraphBackendType, } from './types.js';
 import { parseCitationSidecar, citationResultToEdges, buildRefToPathMap } from './citation-parser.js';
-import { writeIndexFile, resolveIndexDir, loadGraphIndexFile } from './index-reader.js';
+import { writeIndexFile, resolveIndexDir, loadGraphIndexFile, publishIndexFiles } from './index-reader.js';
 import { loadManifest, writeManifest, statMatches, makeEntry } from './checksum-manifest.js';
 import { FRAMEWORK_RELATIONS_REVISION } from './framework-source-digest.js';
 import { normalizeOperationalState } from './operational-state.js';
@@ -26,6 +26,9 @@ import { DEFAULT_PROJECT_AIWG_DIR, resolveProjectAiwgDir, } from '../config/proj
 import { normalizeStateTransferProjection } from './state-transfer.js';
 import { resolveIndexWorkers, runIndexPreparation } from './index-preparation.js';
 import { collectGraphIndexFiles, findArtifactFiles, indexPathFor } from './index-files.js';
+import { acquireDirectoryLock } from './prebuilt-build-lock.js';
+import { graphIndexDigest, indexAdapterRegistry, recordIndexVerification } from './index-adapters.js';
+import { loadMemoryRecord } from '../memory/maintenance-record.js';
 function absoluteEntryPath(cwd, entryPath, graph) {
     if ((!graph || graph === 'project') && entryPath.startsWith(`${DEFAULT_PROJECT_AIWG_DIR}/`)) {
         return path.join(resolveProjectAiwgDir(cwd), entryPath.slice(DEFAULT_PROJECT_AIWG_DIR.length + 1));
@@ -369,6 +372,9 @@ function inferType(data, filePath) {
                     // Rules/RULES-INDEX.md is a curated index file, not a rule.
                     if (basename === 'rules-index' || basename === 'index')
                         break;
+                    // <rule>.core.md is a delivery body (#3450), not a separate rule.
+                    if (/\.core\.md$/i.test(filePath))
+                        break;
                     if (isMarkdown)
                         return 'rule';
                     break;
@@ -836,27 +842,73 @@ function resolveInstallRootHint() {
     catch { /* fall through */ }
     return '<aiwg install root>';
 }
+/** Current source identities for rule bindings; no search index or graph is written. */
+export async function collectRuleBindingEntries(cwd, scope) {
+    const fileStats = new Map();
+    const files = await collectGraphIndexFiles(cwd, undefined, { scope, fileStats });
+    return files.flatMap(fullPath => {
+        const stat = fileStats.get(fullPath) ?? fs.statSync(fullPath);
+        const entry = extractIndexArtifact({ fullPath, relativePath: indexPathFor(cwd, fullPath),
+            mtimeMs: stat.mtimeMs, birthtimeMs: stat.birthtimeMs, sizeBytes: stat.size }, true).entry;
+        return entry && ['skill', 'agent', 'flow'].includes(entry.type) ? [entry] : [];
+    });
+}
 /** Shared serial/worker read, checksum and extraction. No index output or global reduction. */
 export function prepareIndexArtifact(job) {
+    const warnings = [];
+    const result = extractIndexArtifact(job, false, warnings);
+    return { ...result, ...(warnings.length ? { warnings } : {}) };
+}
+function extractIndexArtifact(job, bindingOnly, warnings = []) {
     const { fullPath, relativePath } = job;
     const content = fs.readFileSync(fullPath, 'utf8');
     const checksum = computeChecksum(content);
     if (job.existingChecksum === checksum)
         return { checksum };
     const { data, body } = parseFrontmatter(content);
+    let memoryRecord;
+    if (data.memoryRecord !== undefined) {
+        try {
+            memoryRecord = loadMemoryRecord(data.memoryRecord);
+        }
+        catch (error) {
+            warnings.push(`${relativePath}: invalid memoryRecord metadata quarantined: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const inferredType = inferType(data, relativePath);
+    const bindingType = ['skill', 'agent', 'flow'].includes(inferredType);
+    // Only YAML flows can promote an otherwise unrelated document to a binding target.
+    if (bindingOnly && !bindingType && !/\.ya?ml$/i.test(relativePath))
+        return { checksum };
     // YAML Flow documents (workflow.aiwg.io/v1) are pure YAML, not
     // markdown+frontmatter — detect them up front so they classify and
     // become discoverable (#1540).
     const flow = parseFlowDoc(content, relativePath);
+    if (bindingOnly && !flow && !bindingType)
+        return { checksum };
     const decision = flow ? null : parseDecisionDoc(content, relativePath);
     const gatePack = flow || decision ? null : parseGatePackDoc(content, relativePath);
-    const inferredType = inferType(data, relativePath);
+    if (bindingOnly && (decision || gatePack))
+        return { checksum };
     const physicalType = inferType({ ...data, type: undefined }, relativePath);
     const runbook = flow || decision || gatePack ? null : parseRunbookDoc(data, body, relativePath);
     const schemaDoc = inferredType === 'schema' ? parseSchemaDoc(content, relativePath) : null;
     const title = flow?.name ?? decision?.name ?? gatePack?.name ?? schemaDoc?.title ?? extractTitle(data, body);
     const phase = typeof data.phase === 'string' ? data.phase : inferPhase(relativePath);
     const type = flow?.type ?? decision?.type ?? gatePack?.type ?? (runbook ? 'runbook' : inferredType);
+    // Binding resolution consumes only identity and title. Keep the same canonical
+    // classification (including declarative flows and runbooks), without extracting
+    // search terms, mentions, links, or constructing a persistent graph.
+    if (bindingOnly)
+        return { checksum, entry: {
+                path: relativePath, type, title, phase,
+                ...(memoryRecord ? { memoryRecord } : {}),
+                name: flow?.name ?? decision?.name ?? gatePack?.name ?? schemaDoc?.name
+                    ?? (OPERATIONAL_DISCOVERY_TYPES.includes(type)
+                        ? extractCanonicalName(data, relativePath) : undefined),
+                tags: [], dependencies: [], dependents: [], checksum,
+                created: '', updated: '', summary: '',
+            } };
     const tags = flow?.tags ?? decision?.tags ?? gatePack?.tags ?? (Array.isArray(data.tags) ? data.tags.map(String) : []);
     const summary = flow?.description ?? decision?.description ?? gatePack?.description ?? schemaDoc?.capability ?? runbook?.capability ?? extractSummary(data, body);
     const dependencies = extractMentions(content);
@@ -882,6 +934,8 @@ export function prepareIndexArtifact(job) {
     // remain searchable even when the rendered title strips the hyphen.
     const name = flow?.name ?? decision?.name ?? gatePack?.name ?? schemaDoc?.name ?? (isDiscoverable ? extractCanonicalName(data, relativePath) : undefined);
     const entry = {
+        ...(memoryRecord ? { memoryRecord } : {}),
+        ...(typeof data.memoryCategory === 'string' ? { memoryCategory: data.memoryCategory } : {}),
         path: relativePath,
         type,
         ...(kind ? { kind } : {}),
@@ -910,6 +964,67 @@ export function prepareIndexArtifact(job) {
     return { checksum, entry };
 }
 export async function buildIndex(cwd, options = {}) {
+    loadUserGraphConfigs(cwd);
+    loadGlobalGraphConfigs();
+    const scanDirs = options.scope ? [path.join(cwd, options.scope)] : options.graph
+        ? GRAPH_CONFIGS[options.graph]?.scanDirs.map(dir => resolveGraphScanDir(cwd, dir)) ?? []
+        : [resolveProjectAiwgDir(cwd)];
+    if (!scanDirs.some(dir => fs.existsSync(dir))) {
+        // Keep the owner's missing-root diagnostic/exit path before creating output directories.
+        await buildIndexSnapshot(cwd, options, () => '');
+        return;
+    }
+    const directory = options.outputDir
+        ? path.join(options.outputDir, options.graph ? `.aiwg/.index/${options.graph}` : INDEX_DIR)
+        : resolveIndexDir(cwd, options.graph);
+    // Manual and background builds acquire the same per-output owner lock.
+    const release = await acquireDirectoryLock(`${directory}.build.lock`, {
+        timeoutMs: options.lockWaitMs ?? 180_000, reclaimDeadOwner: true,
+    });
+    let staging;
+    const start = Date.now();
+    let owned;
+    try {
+        const adapter = !options.scope && !options.includeIgnored
+            ? indexAdapterRegistry(cwd).find(item => item.name === (options.graph ?? 'project')) : undefined;
+        owned = adapter && directory === path.dirname(adapter.statePath) ? adapter : undefined;
+        const observation = { selection: {} };
+        const preparePublication = () => {
+            fs.mkdirSync(directory, { recursive: true });
+            return staging ??= fs.mkdtempSync(path.join(directory, '.build-'));
+        };
+        await buildIndexSnapshot(cwd, options, preparePublication, owned ? observation : undefined);
+        // A receipt hit verifies the existing snapshot directly against the scan's
+        // stats. There is no extraction interval to recheck. Real builds still probe
+        // again after preparation so concurrent source changes remain pending.
+        const after = owned ? observation.unchanged ? observation.before
+            : await graphIndexDigest(cwd, options.graph, { selection: observation.selection }) : undefined;
+        // All extraction and backend work has succeeded before any live file moves.
+        if (owned)
+            recordIndexVerification(owned, cwd, { before: observation.before, after, wallMs: Date.now() - start }, staging);
+        if (staging)
+            publishIndexFiles(staging, directory);
+    }
+    catch (error) {
+        if (owned) {
+            try {
+                recordIndexVerification(owned, cwd, { error: error instanceof Error ? error.message : String(error), wallMs: Date.now() - start });
+            }
+            catch { /* Preserve the original build failure if recording is unavailable. */ }
+        }
+        throw error;
+    }
+    finally {
+        try {
+            if (staging)
+                fs.rmSync(staging, { recursive: true, force: true });
+        }
+        finally {
+            await release();
+        }
+    }
+}
+async function buildIndexSnapshot(cwd, options, preparePublication, observation) {
     const { force = false, verbose = false, scope, includeIgnored = false, outputDir, graph, explicit = true } = options;
     const workers = resolveIndexWorkers(options.workers);
     const startTime = Date.now();
@@ -979,10 +1094,12 @@ export async function buildIndex(cwd, options = {}) {
     // effectiveOutputCwd is used for backward-compat loadMetadataIndex calls
     const effectiveOutputCwd = outputDir ?? cwd;
     if (graph === 'source') {
+        if (observation)
+            observation.before = await graphIndexDigest(cwd, graph, { selection: observation.selection });
         const { buildSourceGraphIndex } = await import('./source-graph.js');
         await buildSourceGraphIndex({
             cwd,
-            outputDir: indexOutputDir,
+            outputDir: preparePublication(),
             effectiveOutputCwd,
             verbose,
         });
@@ -1001,7 +1118,7 @@ export async function buildIndex(cwd, options = {}) {
         : loadManifest(indexOutputDir);
     const useFilenameMetadata = graphConfig?.nodeStrategy === 'filename-metadata';
     const reusable = !useFilenameMetadata && !graphConfig?.metadataSupplements?.length && !graphConfig?.edgeExtraction;
-    const fileStats = !force && reusable ? new Map() : undefined;
+    const fileStats = observation || (!force && reusable) ? new Map() : undefined;
     const nextManifestEntries = {};
     const manifestStats = {
         checked: 0,
@@ -1011,7 +1128,9 @@ export async function buildIndex(cwd, options = {}) {
         pruned: 0,
     };
     // Collect files from all scan directories
-    const files = await collectGraphIndexFiles(cwd, graph, { scope, includeIgnored, fileStats });
+    const files = await collectGraphIndexFiles(cwd, graph, { scope, includeIgnored, fileStats, selection: observation?.selection });
+    if (observation)
+        observation.before = await graphIndexDigest(cwd, graph, { files, fileStats });
     const entries = {};
     const tagIndex = {};
     const depGraph = {};
@@ -1052,7 +1171,7 @@ export async function buildIndex(cwd, options = {}) {
     };
     const entriesDigest = (values) => createHash('sha256').update(JSON.stringify(values)).digest('hex');
     const writeBuildManifest = (values) => {
-        writeManifest(indexOutputDir, { version: 1, generated: new Date().toISOString(), entries: values,
+        writeManifest(publicationDir, { version: 1, generated: new Date().toISOString(), entries: values,
             ...(reusable ? { receipt: {
                     indexVersion: INDEX_VERSION, extractorVersion: INDEX_EXTRACTOR_VERSION, buildConfigHash,
                     sourceRoot: path.resolve(cwd), metadataSignature: fileSignature('metadata.json'), entriesDigest: entriesDigest(values),
@@ -1086,11 +1205,16 @@ export async function buildIndex(cwd, options = {}) {
             manifestStats.checked = files.length;
             manifestStats.statSkipped = files.length;
             const buildTimeMs = Date.now() - startTime;
+            // Only stats changes on a receipt hit; its existing atomic writer is
+            // sufficient under the owner lock, without staging or backup copies.
             writeIndexFile(effectiveOutputCwd, 'stats.json', { ...stats, builtAt: new Date().toISOString(), buildTimeMs }, indexOutputDir);
+            if (observation)
+                observation.unchanged = true;
             reportBuild(buildTimeMs, files.length);
             return;
         }
     }
+    const publicationDir = preparePublication();
     const existingIndex = force ? null : outputDir
         ? loadIndexFromDir(indexOutputDir, 'metadata.json')
         : loadGraphIndexFile(effectiveOutputCwd, 'metadata.json', graph);
@@ -1121,6 +1245,10 @@ export async function buildIndex(cwd, options = {}) {
                 ...(!force && existingEntries[relativePath] ? { existingChecksum: existingEntries[relativePath].checksum } : {}) });
         }
     const preparation = await runIndexPreparation(jobs, prepareIndexArtifact, import.meta.url, workers, options.onDiagnostic ?? (message => console.warn(`Index preparation: ${message}`)));
+    for (const result of preparation.results)
+        for (const warning of result.warnings ?? []) {
+            (options.onDiagnostic ?? (message => console.warn(`Index preparation: ${message}`)))(warning);
+        }
     const preparedArtifacts = new Map(jobs.map((job, index) => [job.fullPath, preparation.results[index]]));
     for (const fullPath of files) {
         const relativePath = indexPathFor(cwd, fullPath, graph);
@@ -1221,14 +1349,15 @@ export async function buildIndex(cwd, options = {}) {
             const projectionNeedsRepair = graph === 'framework' && !relationsReceiptMatches();
             if (graph === 'framework') {
                 const { writeRelations } = await import('./relations-builder.js');
-                await writeRelations(entries, effectiveOutputCwd, indexOutputDir, force || !relationsReceiptMatches());
+                if (force || !relationsReceiptMatches())
+                    await writeRelations(entries, effectiveOutputCwd, publicationDir, true);
             }
             const buildTimeMs = Date.now() - startTime;
             writeIndexFile(effectiveOutputCwd, 'stats.json', {
                 ...stats,
                 builtAt: new Date().toISOString(),
                 buildTimeMs,
-            }, indexOutputDir);
+            }, publicationDir);
             // Preserve no-op manifest bytes after output-only timestamp drift.
             // Renew receipts only for changed source stats or repaired projections.
             if (manifestStats.checksumSkipped > 0 || projectionNeedsRepair)
@@ -1354,7 +1483,7 @@ export async function buildIndex(cwd, options = {}) {
     }
     if (graph === 'framework') {
         const { writeRelations } = await import('./relations-builder.js');
-        await writeRelations(entries, effectiveOutputCwd, indexOutputDir, force || !relationsReceiptMatches());
+        await writeRelations(entries, effectiveOutputCwd, publicationDir, force || !relationsReceiptMatches(), indexOutputDir);
     }
     const buildTimeMs = Date.now() - startTime;
     // Write index files
@@ -1366,13 +1495,13 @@ export async function buildIndex(cwd, options = {}) {
         buildTimeMs,
         entries,
     };
-    writeIndexFile(effectiveOutputCwd, 'metadata.json', index, indexOutputDir);
-    writeIndexFile(effectiveOutputCwd, 'tags.json', tagIndex, indexOutputDir);
-    writeIndexFile(effectiveOutputCwd, 'dependencies.json', depGraph, indexOutputDir);
+    writeIndexFile(effectiveOutputCwd, 'metadata.json', index, publicationDir);
+    writeIndexFile(effectiveOutputCwd, 'tags.json', tagIndex, publicationDir);
+    writeIndexFile(effectiveOutputCwd, 'dependencies.json', depGraph, publicationDir);
     // Materialize the configured backend and always retain dependencies.json as
     // the stable compatibility/export contract.
     const { createGraphBackend } = await import('./graph-backend.js');
-    const persistentPath = backendType === 'sqlite' ? path.join(indexOutputDir, 'graph.db') : undefined;
+    const persistentPath = backendType === 'sqlite' ? path.join(publicationDir, 'graph.db') : undefined;
     let selectedBackend;
     try {
         selectedBackend = await createGraphBackend(backendType, persistentPath);
@@ -1430,7 +1559,7 @@ export async function buildIndex(cwd, options = {}) {
             orphanedArtifacts: orphaned,
             mostReferenced,
         },
-    }, indexOutputDir);
+    }, publicationDir);
     writeBuildManifest(nextManifestEntries);
     // Report
     reportBuild(buildTimeMs, total);

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

@@ -87,9 +87,14 @@ export async function collectGraphIndexFiles(cwd, graph, options = {}) {
         throw new Error(`Unknown graph: ${graph}`);
     }
     const artifactRoot = resolveProjectAiwgDir(cwd);
-    const excludedDirs = [path.join(cwd, DEFAULT_PROJECT_AIWG_DIR), artifactRoot]
-        .flatMap(root => INDEX_SCRATCH_DIRS.map(name => path.resolve(root, name)));
-    const excludedPaths = new Set(excludedDirs);
+    const artifactRoots = [path.join(cwd, DEFAULT_PROJECT_AIWG_DIR), artifactRoot];
+    // Aggregate owner state contains history, tombstones and transaction payloads.
+    // It is not an ordinary artifact: only each owner's public projection is a
+    // retrieval surface, never the backing store or maintenance receipts.
+    const privateDirs = ['context/compound-memory', 'memory/transactions', 'memory/maintenance'];
+    const privateFiles = ['memory/line-memory.meta.json', 'memory/line-memory.config.json', 'memory/line-memory.lock'];
+    const excludedDirs = artifactRoots.flatMap(root => [...INDEX_SCRATCH_DIRS, ...privateDirs].map(name => path.resolve(root, name)));
+    const excludedPaths = new Set([...excludedDirs, ...artifactRoots.flatMap(root => privateFiles.map(name => path.resolve(root, name)))]);
     // A directory's ancestors are shared by thousands of sibling artifacts.
     // Cache only within this scan so the next build still notices new symlinks.
     const safePaths = new Map();
@@ -109,7 +114,7 @@ export async function collectGraphIndexFiles(cwd, graph, options = {}) {
         }
         const inputPath = file;
         file = path.resolve(file);
-        if (excludedDirs.some(dir => process.platform === 'win32'
+        if (excludedPaths.has(file) || excludedDirs.some(dir => process.platform === 'win32'
             ? pathContains(dir, file) : file === dir || file.startsWith(dir + path.sep)))
             return false;
         if (knownStat && !knownStat.isSymbolicLink() && safePaths.get(path.dirname(file)) === true) {
@@ -190,6 +195,10 @@ export async function collectGraphIndexFiles(cwd, graph, options = {}) {
         }
     }
     let sources = [...files];
+    const candidates = [...sources].sort();
+    if (options.selection?.files && JSON.stringify(candidates) === JSON.stringify(options.selection.candidates)) {
+        return [...options.selection.files];
+    }
     if (!options.includeIgnored) {
         // Many projects ignore the whole artifact root (`.aiwg/`). Honoring that
         // would empty the index, so ignore rules apply only beneath a scan root
@@ -225,6 +234,8 @@ export async function collectGraphIndexFiles(cwd, graph, options = {}) {
             if (!selected.has(file))
                 options.fileStats.delete(file);
     }
+    if (options.selection)
+        Object.assign(options.selection, { candidates, files: [...sources] });
     return sources;
 }
 //# sourceMappingURL=index-files.js.map

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

@@ -11,6 +11,7 @@
 import fs from 'fs';
 import path from 'path';
 import { getGraphIndexDir, getProjectIndexRoot } from './types.js';
+import { loadManifest, writeManifest } from './checksum-manifest.js';
 /**
  * Load a JSON file from the index directory
  *
@@ -109,4 +110,47 @@ export function loadGraphIndexFile(cwd, filename, graph) {
         return null;
     }
 }
+/** Publish a prepared snapshot with the existing atomic file writes under the owner lock. */
+export function publishIndexFiles(staging, directory) {
+    const files = fs.readdirSync(staging).filter(file => fs.statSync(path.join(staging, file)).isFile())
+        .sort((a, b) => Number(a === 'metadata.json') - Number(b === 'metadata.json'));
+    const backups = path.join(staging, '.previous');
+    fs.mkdirSync(backups);
+    for (const file of files) {
+        const target = path.join(directory, file);
+        if (fs.existsSync(target))
+            fs.copyFileSync(target, path.join(backups, file));
+    }
+    const published = [];
+    try {
+        for (const file of files) {
+            fs.renameSync(path.join(staging, file), path.join(directory, file));
+            published.push(file);
+        }
+        // Receipts bind to final inode signatures, after the atomic renames.
+        if (files.includes('checksum-manifest.json')) {
+            const manifest = loadManifest(directory);
+            const signature = (file) => {
+                const stat = fs.statSync(path.join(directory, file), { bigint: true });
+                return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(':');
+            };
+            if (manifest.receipt) {
+                manifest.receipt.metadataSignature = signature('metadata.json');
+                if (manifest.receipt.relations)
+                    manifest.receipt.relations.signature = signature('relations.json');
+                writeManifest(directory, manifest);
+            }
+        }
+    }
+    catch (error) {
+        for (const file of published.reverse()) {
+            const backup = path.join(backups, file);
+            if (fs.existsSync(backup))
+                fs.renameSync(backup, path.join(directory, file));
+            else
+                fs.rmSync(path.join(directory, file), { force: true });
+        }
+        throw error;
+    }
+}
 //# sourceMappingURL=index-reader.js.map