@aiwg/cli 2026.10.4 → 2026.10.6

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

@@ -0,0 +1,339 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getUserStateDir } from '../config/user-state.js';
+import { projectAiwgPath, projectControlPath } from '../config/project-artifacts.js';
+import { validateIndexConfig } from '../config/aiwg-config.js';
+import { collectGraphIndexFiles, findArtifactFiles, INDEX_SCRATCH_DIRS } from './index-files.js';
+import { writeIndexFile } from './index-reader.js';
+import { GRAPH_CONFIGS, INDEX_VERSION, INDEX_EXTRACTOR_VERSION, getGraphIndexDir, resolveGraphBackendType, resolveGraphScanDir } from './types.js';
+import { acquireDirectoryLock, DirectoryLockContentionError } from './prebuilt-build-lock.js';
+import { resolveFrameworkIndexRoot } from './framework-index-paths.js';
+import { resolveProjectLocalSearchRoots } from '../extensions/project-local-paths.js';
+import { getFortemiCoreIndexDir } from './fortemi-core-sync.js';
+function json(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function canonical(root) {
+    try {
+        return fs.realpathSync(root);
+    }
+    catch {
+        return path.resolve(root);
+    }
+}
+function hashFiles(files, context) {
+    const hash = createHash('sha256').update(JSON.stringify(context));
+    for (const file of [...new Set(files)].sort()) {
+        hash.update('\0').update(file).update('\0').update(fs.readFileSync(file));
+    }
+    return hash.digest('hex');
+}
+/** Same authorized source set as the builder, including links and bundle roots. */
+export async function graphIndexDigest(cwd, graph, observation = {}) {
+    const fileStats = observation.fileStats ?? new Map();
+    const files = observation.files ? [...observation.files]
+        : graph === 'source' ? (await import('./source-graph.js')).collectSourceFiles(cwd, true)
+            : await collectGraphIndexFiles(cwd, graph, { selection: observation.selection, fileStats });
+    const ignoreRoots = graph && GRAPH_CONFIGS[graph]?.shared && graph !== 'framework' ? [] : [cwd];
+    if (graph)
+        ignoreRoots.push(...GRAPH_CONFIGS[graph].scanDirs.map(dir => resolveGraphScanDir(cwd, dir)));
+    for (const root of ignoreRoots) {
+        const ignoreFile = path.join(root, '.gitignore');
+        if (fs.existsSync(ignoreFile))
+            files.push(ignoreFile);
+    }
+    if (graph === 'source')
+        for (const file of ['tsconfig.json', 'package.json']) {
+            if (fs.existsSync(path.join(cwd, file)))
+                files.push(path.join(cwd, file));
+        }
+    // Supplements affect graph entries even though they are outside scanDirs.
+    for (const supplement of (graph ? GRAPH_CONFIGS[graph]?.metadataSupplements : undefined) ?? []) {
+        files.push(...findArtifactFiles(resolveGraphScanDir(cwd, supplement.scanDir)));
+    }
+    const inputs = [...new Set(files)].sort().map(file => {
+        const stat = fileStats.get(file) ?? fs.statSync(file);
+        return [file, stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs];
+    });
+    return createHash('sha256').update(JSON.stringify([graph && GRAPH_CONFIGS[graph]?.shared ? null : canonical(cwd), INDEX_VERSION, INDEX_EXTRACTOR_VERSION,
+        graph ? GRAPH_CONFIGS[graph] : null, resolveGraphBackendType(graph), inputs])).digest('hex');
+}
+export function resolveFreshnessPolicy(cwd, adapter) {
+    const config = json(projectControlPath(cwd, 'aiwg.config'))?.index;
+    const errors = validateIndexConfig(config && { freshness: config.freshness });
+    if (errors.length)
+        throw new Error(errors.join('; '));
+    const defaults = {
+        graphs: 3_600_000, sessions: 900_000, caches: 86_400_000, runtime: 21_600_000,
+        models: 86_400_000, issues: 300_000, datasets: 86_400_000,
+    };
+    return { index: adapter.name, targetStaleAfterMs: defaults[adapter.group], maxRetriesPerDay: 3,
+        measureConvergence: true, ...config?.freshness?.[adapter.group], ...config?.freshness?.[adapter.name] };
+}
+/** Registry is bounded by graph registrations and existing owner scopes. No host discovery. */
+export function indexAdapterRegistry(cwd) {
+    const adapters = [];
+    const add = (definition) => {
+        const adapter = { ...definition,
+            probe: (workspace, nowMs) => probeIndexAdapter(adapter, workspace, nowMs),
+            refresh: async (opts) => {
+                const { refreshIndexes } = await import('./index-refresh.js');
+                return refreshIndexes({ cwd: opts.cwd, only: adapter.name, full: opts.full,
+                    dryRun: opts.dryRun, signal: opts.signal });
+            },
+            convergence: last => {
+                const jobs = last.jobs.filter(job => definition.group === 'graphs' ? job.kind === 'graph' && job.graph === definition.graph
+                    : definition.group === 'caches' ? job.kind === 'cache' && job.graph === definition.graph : job.kind === definition.name);
+                return { converged: jobs.length > 0 && jobs.every(job => job.freshness?.status === 'fresh'
+                        && job.freshness.convergence?.converged !== false), wallMs: last.totals.wallMs,
+                    residualJobs: jobs.filter(job => job.freshness?.status !== 'fresh').length };
+            },
+        };
+        adapters.push(adapter);
+    };
+    for (const [graph, config] of Object.entries(GRAPH_CONFIGS)) {
+        const directory = getGraphIndexDir(cwd, graph);
+        const outputs = ['metadata.json', 'dependencies.json', 'tags.json', 'stats.json'];
+        if (resolveGraphBackendType(graph) === 'sqlite')
+            outputs.push('graph.db');
+        if (graph === 'framework')
+            outputs.push('relations.json');
+        add({ name: graph, graph, group: 'graphs', identity: canonical(directory),
+            backend: resolveGraphBackendType(graph), operation: 'buildIndex', supported: true,
+            exclusions: [...INDEX_SCRATCH_DIRS, 'symlinks', 'gitignored', 'hidden directories'],
+            roots: workspace => [...new Set([
+                    ...config.scanDirs.map(dir => canonical(resolveGraphScanDir(graph === 'framework' ? resolveFrameworkIndexRoot(workspace) : workspace, dir))),
+                    ...(graph === 'project' ? [canonical(workspace), ...resolveProjectLocalSearchRoots(workspace).map(root => canonical(root.rootPath))] : []),
+                ])],
+            outputPaths: outputs.map(file => path.join(directory, file)), statePath: path.join(directory, 'freshness.json') });
+        if (graph === 'framework') {
+            const owner = adapters[adapters.length - 1];
+            add({ ...owner, name: 'relationships', operation: 'buildIndex(framework):relations',
+                reason: 'Relationship projection shares the framework snapshot and owner lock' });
+        }
+        const cacheDirectory = getFortemiCoreIndexDir(cwd, graph);
+        if (fs.existsSync(cacheDirectory))
+            add({ name: `caches:${graph}`, graph, group: 'caches',
+                identity: canonical(cacheDirectory), backend: 'fortemi-core', operation: 'syncFortemiCoreIndex',
+                supported: true, exclusions: ['remote mutation'], roots: () => [canonical(directory)],
+                outputPaths: ['manifest.json', 'aiwg-fortemi-index-v2.json'].map(file => path.join(cacheDirectory, file)),
+                statePath: path.join(cacheDirectory, 'freshness.json') });
+    }
+    const scopes = [
+        { name: 'sessions', directory: path.join(cwd, '.aiwg/sessions'), backend: 'sqlite',
+            operation: 'refreshSessionCatalog', outputs: ['catalog.sqlite'] },
+        { name: 'runtime', directory: projectAiwgPath(cwd, 'smiths/toolsmith'), backend: 'json',
+            operation: 'RuntimeDiscovery', outputs: ['runtime.json', 'runtime-info.md'] },
+        { name: 'issues', directory: projectAiwgPath(cwd, 'issues'), backend: 'json',
+            operation: 'LocalIssueProviderCore.rebuildIssueIndex', outputs: ['index/issues.index.json'] },
+    ];
+    for (const scope of scopes) {
+        // Absent opt-in scopes are visible as unavailable; planning still respects opt-in.
+        add({ name: scope.name, group: scope.name, identity: canonical(scope.directory), backend: scope.backend,
+            operation: scope.operation, supported: true, exclusions: ['undeclared provider roots', 'auth and token files'],
+            roots: workspace => {
+                if (scope.name !== 'sessions')
+                    return [canonical(scope.directory)];
+                let config;
+                try {
+                    config = json(projectControlPath(workspace, 'aiwg.config'));
+                }
+                catch {
+                    return [];
+                }
+                const manifests = [path.join(workspace, '.aiwg/sessions/discovery-manifest.json'),
+                    ...(config?.sessions?.discovery_manifests ?? []).map(file => path.resolve(workspace, file))];
+                return [...new Set(manifests.flatMap(file => {
+                        try {
+                            const manifest = json(file);
+                            return Object.values(manifest?.authorizedRoots ?? {}).flat().map(canonical);
+                        }
+                        catch {
+                            return [];
+                        }
+                    }))];
+            }, outputPaths: scope.outputs.map(file => path.join(scope.directory, file)),
+            statePath: path.join(scope.directory, '.index', 'freshness.json') });
+    }
+    for (const name of ['models', 'datasets'])
+        add({ name, group: name,
+            identity: `${name}:${canonical(cwd)}`, backend: 'remote', operation: name === 'models'
+                ? 'resolveDynamicModelCatalog' : 'dataset owner', supported: false,
+            reason: `${name} has no local deterministic freshness probe; use its owning operation`,
+            roots: () => [], outputPaths: [], exclusions: ['remote-only owners'],
+            statePath: projectAiwgPath(cwd, '.index', `${name}-freshness.json`) });
+    return adapters;
+}
+export function selectIndexAdapters(adapters, only = 'all') {
+    if (only === 'all')
+        return adapters;
+    const selected = adapters.filter(adapter => adapter.name === only || adapter.group === only);
+    if (!selected.length && !['sessions', 'issues', 'caches'].includes(only))
+        throw new Error(`Unknown index: ${only}`);
+    return selected;
+}
+async function adapterDigest(adapter, cwd) {
+    if (adapter.group === 'graphs')
+        return graphIndexDigest(adapter.graph === 'framework' ? resolveFrameworkIndexRoot(cwd) : cwd, adapter.graph);
+    if (adapter.group === 'caches')
+        return hashFiles(['metadata.json', 'dependencies.json'].map(file => path.join(getGraphIndexDir(cwd, adapter.graph), file)), adapter.identity);
+    if (adapter.group === 'issues')
+        return hashFiles(['items', 'events', 'comments'].flatMap(dir => findArtifactFiles(projectAiwgPath(cwd, 'issues', dir), ['.md', '.json', '.jsonl'])), adapter.identity);
+    if (adapter.group === 'sessions') {
+        const { readDiscoveryManifest, discoverWorkspaceHistories } = await import('../sessions/workspace-discovery.js');
+        const config = json(projectControlPath(cwd, 'aiwg.config'));
+        const manifests = [path.join(cwd, '.aiwg/sessions/discovery-manifest.json'),
+            ...(config?.sessions?.discovery_manifests ?? []).map(file => path.resolve(cwd, file))];
+        const inputs = [];
+        for (const file of [...new Set(manifests)])
+            if (fs.existsSync(file)) {
+                const previous = await readDiscoveryManifest(file);
+                if (previous.workspaceId !== canonical(cwd))
+                    throw new Error('discovery manifest workspace mismatch');
+                const authorizedRoots = previous.authorizedRoots ?? {};
+                if (!previous.authorizedRoots)
+                    for (const source of previous.sources) {
+                        const roots = authorizedRoots[source.provider] ??= [];
+                        if (!roots.includes(source.authorizedRoot))
+                            roots.push(source.authorizedRoot);
+                    }
+                const current = await discoverWorkspaceHistories({ workspace: cwd,
+                    refreshFrom: { ...previous, authorizedRoots }, knownSources: previous.sources,
+                    exclude: config?.sessions?.import?.exclude });
+                inputs.push(current.manifestId);
+            }
+        if (!inputs.length)
+            throw new Error('no authorized discovery manifest');
+        return createHash('sha256').update(JSON.stringify([adapter.identity, inputs])).digest('hex');
+    }
+    // RuntimeDiscovery owns environmental discovery; its input receipt bounds this probe.
+    const runtime = json(adapter.outputPaths[0]);
+    if (!runtime?.inputFingerprint)
+        throw new Error('runtime input fingerprint unavailable');
+    return hashFiles([projectControlPath(cwd, 'aiwg.config')].filter(file => fs.existsSync(file)), runtime.inputFingerprint);
+}
+function outputDigest(adapter) {
+    if (!adapter.outputPaths.every(file => fs.existsSync(file)))
+        return undefined;
+    // The owner may renew stats on an unchanged build. Snapshot identity follows primary output.
+    const stat = fs.statSync(adapter.outputPaths[0], { bigint: true });
+    // Rename changes ctime during publication; inode, mtime and size survive it.
+    return createHash('sha256').update(JSON.stringify([adapter.identity, String(stat.dev), String(stat.ino),
+        String(stat.size), String(stat.mtimeNs)])).digest('hex');
+}
+/** Synchronous persisted view for existing reader callers; CLI/daemon also probe inputs. */
+export function indexFreshnessSnapshot(adapter, cwd, nowMs = Date.now(), digest) {
+    const fallback = { index: adapter.name, targetStaleAfterMs: 3_600_000,
+        maxRetriesPerDay: 3, measureConvergence: true };
+    let policy = fallback;
+    try {
+        policy = resolveFreshnessPolicy(cwd, adapter);
+        if (!adapter.supported)
+            return { name: adapter.name, status: 'unsupported', policy,
+                lastVerifiedDigest: null, lastVerifiedAt: null, dirtySince: null, dirtyAgeMs: null,
+                pendingWork: 0, lastError: null, reason: adapter.reason };
+        const state = json(adapter.statePath);
+        const outputs = outputDigest(adapter);
+        const age = state?.lastVerifiedAt ? Math.max(0, nowMs - Date.parse(state.lastVerifiedAt)) : Infinity;
+        const changed = !state || !outputs || outputs !== state.outputDigest || (digest !== undefined && state.lastVerifiedDigest !== digest);
+        const dirtySince = state?.dirtySince ?? (changed ? new Date(nowMs).toISOString()
+            : age > policy.targetStaleAfterMs ? new Date(Date.parse(state.lastVerifiedAt) + policy.targetStaleAfterMs).toISOString() : null);
+        return { name: adapter.name, policy,
+            status: !outputs ? 'unavailable' : state?.lastError ? 'degraded'
+                : changed || state?.pendingWork || age > policy.targetStaleAfterMs ? 'stale' : 'fresh',
+            lastVerifiedDigest: state?.lastVerifiedDigest ?? null, lastVerifiedAt: state?.lastVerifiedAt ?? null,
+            dirtySince, dirtyAgeMs: dirtySince ? Math.max(0, nowMs - Date.parse(dirtySince)) : null,
+            pendingWork: changed ? Math.max(1, state?.pendingWork ?? 0) : state?.pendingWork ?? 0,
+            lastError: state?.lastError ?? null, convergence: policy.measureConvergence && state?.convergence
+                ? { ...state.convergence, converged: state.convergence.residualJobs === 0
+                        && state.convergence.wallMs <= policy.targetStaleAfterMs } : undefined };
+    }
+    catch (error) {
+        return { name: adapter.name, status: 'degraded', policy, lastVerifiedDigest: null, lastVerifiedAt: null,
+            dirtySince: null, dirtyAgeMs: null, pendingWork: 1, lastError: String(error) };
+    }
+}
+export async function probeIndexAdapter(adapter, cwd, nowMs = Date.now()) {
+    const persisted = indexFreshnessSnapshot(adapter, cwd, nowMs);
+    if (!adapter.supported || persisted.status === 'unavailable')
+        return persisted;
+    try {
+        if (adapter.group === 'sessions') {
+            const { sessionRefreshAvailable } = await import('../sessions/refresh.js');
+            if (!sessionRefreshAvailable())
+                return { ...persisted, status: 'unavailable', pendingWork: 1,
+                    reason: 'sqlite unavailable' };
+        }
+        if (adapter.group === 'caches') {
+            const { getFortemiCoreSyncStatus } = await import('./fortemi-core-sync.js');
+            const cache = getFortemiCoreSyncStatus(cwd, adapter.graph);
+            if (cache.stale && !cache.sourceIndexNewer)
+                return { ...persisted, status: 'degraded',
+                    pendingWork: 1, lastError: cache.reason };
+        }
+        const digest = await adapterDigest(adapter, cwd);
+        let snapshot = indexFreshnessSnapshot(adapter, cwd, nowMs, digest);
+        // Preserve the first measured dirty observation without racing a publisher.
+        // Probe never builds or creates an absent index.
+        if (fs.existsSync(adapter.statePath)
+            && snapshot.status === 'stale' && snapshot.lastVerifiedDigest !== digest) {
+            let release;
+            try {
+                release = await acquireDirectoryLock(adapter.group === 'graphs'
+                    ? `${path.dirname(adapter.statePath)}.build.lock` : path.join(getUserStateDir(), 'index-refresh.lock'), { timeoutMs: 0 });
+                const state = json(adapter.statePath);
+                if (state && !state.dirtySince && state.lastVerifiedDigest !== digest) {
+                    writeIndexFile(cwd, path.basename(adapter.statePath), { ...state,
+                        dirtySince: new Date(nowMs).toISOString(), pendingWork: 1 }, path.dirname(adapter.statePath));
+                }
+                snapshot = indexFreshnessSnapshot(adapter, cwd, nowMs, digest);
+            }
+            catch (error) {
+                if (!(error instanceof DirectoryLockContentionError))
+                    throw error;
+            }
+            finally {
+                await release?.();
+            }
+        }
+        return snapshot;
+    }
+    catch (error) {
+        return { ...indexFreshnessSnapshot(adapter, cwd, nowMs), status: 'degraded',
+            pendingWork: 1, lastError: error instanceof Error ? error.message : String(error) };
+    }
+}
+export async function indexAdapterDigest(adapter, cwd) {
+    if (!adapter.supported)
+        return undefined;
+    return adapterDigest(adapter, cwd);
+}
+/** Call under the existing owner lock; failure never advances verification. */
+export function recordIndexVerification(adapter, cwd, opts, publicationDir) {
+    const now = opts.nowMs ?? Date.now();
+    let prior;
+    try {
+        prior = json(adapter.statePath);
+    }
+    catch { /* Replace corrupt receipt, never the snapshot. */ }
+    const complete = !opts.error && !!opts.before && opts.before === opts.after && !opts.pendingWork;
+    const policy = resolveFreshnessPolicy(cwd, adapter);
+    const state = { lastVerifiedDigest: complete ? opts.after : prior?.lastVerifiedDigest ?? null,
+        lastVerifiedAt: complete ? new Date(now).toISOString() : prior?.lastVerifiedAt ?? null,
+        dirtySince: complete ? null : prior?.dirtySince ?? new Date(now).toISOString(),
+        pendingWork: complete ? 0 : Math.max(1, opts.pendingWork ?? 0), lastError: opts.error ?? null,
+        outputDigest: complete ? outputDigest(publicationDir ? { ...adapter, outputPaths: adapter.outputPaths.map(file => fs.existsSync(path.join(publicationDir, path.basename(file))) ? path.join(publicationDir, path.basename(file)) : file) } : adapter) : prior?.outputDigest,
+        ...(policy.measureConvergence ? { convergence: { converged: complete && opts.wallMs <= policy.targetStaleAfterMs,
+                wallMs: opts.wallMs, residualJobs: complete ? 0 : Math.max(1, opts.pendingWork ?? 0) } } : {}) };
+    writeIndexFile(cwd, path.basename(adapter.statePath), state, publicationDir ?? path.dirname(adapter.statePath));
+    return indexFreshnessSnapshot(adapter, cwd, now, opts.after);
+}
+//# sourceMappingURL=index-adapters.js.map

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

@@ -18,14 +18,17 @@ 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';
 import { DEFAULT_PROJECT_AIWG_DIR, resolveProjectAiwgDir, } from '../config/project-artifacts.js';
 import { normalizeStateTransferProjection } from './state-transfer.js';
-import { runIndexPreparation } from './index-preparation.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,7 +964,69 @@ 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();
     const log = options.quiet ? (..._args) => { } : console.log;
     // Ensure user-defined graphs are loaded
@@ -978,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,
         });
@@ -1000,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,
@@ -1010,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 = {};
@@ -1051,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),
@@ -1085,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);
@@ -1119,7 +1244,11 @@ export async function buildIndex(cwd, options = {}) {
             jobs.push({ fullPath, relativePath, mtimeMs: stat.mtimeMs, birthtimeMs: stat.birthtimeMs, sizeBytes: stat.size,
                 ...(!force && existingEntries[relativePath] ? { existingChecksum: existingEntries[relativePath].checksum } : {}) });
         }
-    const preparation = await runIndexPreparation(jobs, prepareIndexArtifact, import.meta.url, options.workers);
+    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);
@@ -1220,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)
@@ -1353,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
@@ -1365,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);
@@ -1429,7 +1559,7 @@ export async function buildIndex(cwd, options = {}) {
             orphanedArtifacts: orphaned,
             mostReferenced,
         },
-    }, indexOutputDir);
+    }, publicationDir);
     writeBuildManifest(nextManifestEntries);
     // Report
     reportBuild(buildTimeMs, total);