@aiwg/cli 2026.10.5 → 2026.10.6

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

@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 import * as fs from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
@@ -7,13 +7,14 @@ import { findPackageRoot } from '../cli/find-package-root.js';
 import { projectAiwgPath, projectControlPath } from '../config/project-artifacts.js';
 import { getUserStateDir } from '../config/user-state.js';
 import { resolveIndexWorkers } from './index-preparation.js';
-import { collectGraphIndexFiles } from './index-files.js';
+import { resolveFrameworkIndexRoot } from './framework-index-paths.js';
 import { collectIndexStatus } from './index-status.js';
+import { graphIndexDigest, indexAdapterRegistry, selectIndexAdapters, indexFreshnessSnapshot, indexAdapterDigest, recordIndexVerification } from './index-adapters.js';
 import { getFortemiCoreSyncStatus, syncFortemiCoreIndex } from './fortemi-core-sync.js';
 import { acquireDirectoryLock, DirectoryLockContentionError } from './prebuilt-build-lock.js';
 import { resolveImportExclusions } from '../sessions/import-exclusions.js';
 import { resolveImportLimits } from '../sessions/import-limits.js';
-import { BUILTIN_GRAPH_CONFIGS, GRAPH_CONFIGS, INDEX_EXTRACTOR_VERSION, INDEX_VERSION, getGraphIndexDir, graphBuildOrder, loadGlobalGraphConfigs, loadUserGraphConfigs, resolveGraphBackendType, resolveGraphScanDir, } from './types.js';
+import { GRAPH_CONFIGS, getGraphIndexDir, graphBuildOrder, loadWorkspaceGraphs, resolveGraphScanDir, } from './types.js';
 function readJson(file, tolerateMalformed = true) {
     try {
         return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -29,14 +30,6 @@ function writeJson(file, value) {
     fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
     fs.renameSync(temporary, file);
 }
-/** The registry is process-global; reload it per workspace to avoid cross-project leakage. */
-function loadWorkspaceGraphs(workspace) {
-    for (const name of Object.keys(GRAPH_CONFIGS))
-        delete GRAPH_CONFIGS[name];
-    Object.assign(GRAPH_CONFIGS, structuredClone(BUILTIN_GRAPH_CONFIGS));
-    loadUserGraphConfigs(workspace);
-    loadGlobalGraphConfigs();
-}
 function workspacePaths(options) {
     const cwd = options.cwd ?? process.cwd();
     const found = new Map();
@@ -124,33 +117,38 @@ function planWorkspaceRefresh(options, workspaces) {
             loadWorkspaceGraphs(workspace);
             const graphs = collectIndexStatus(workspace).graphs
                 .sort((a, b) => graphBuildOrder(a.name, GRAPH_CONFIGS[a.name]) - graphBuildOrder(b.name, GRAPH_CONFIGS[b.name]) || a.name.localeCompare(b.name));
-            if (!options.only || options.only === 'graphs') {
+            const adapters = indexAdapterRegistry(workspace);
+            const selected = selectIndexAdapters(adapters, options.only);
+            const includes = (name) => selected.some(adapter => adapter.name === name);
+            if (!options.only || options.only === 'all' || options.only === 'graphs' || selected.some(adapter => adapter.group === 'graphs')) {
                 for (const graph of graphs) {
-                    if (graph.built || graph.defaultBuild || graph.origin === 'registered') {
+                    if (selected.some(adapter => adapter.group === 'graphs' && adapter.graph === graph.name)
+                        && (graph.built || graph.defaultBuild || graph.origin === 'registered'
+                            || (options.only && options.only !== 'all' && options.only !== 'graphs'))) {
                         jobs.push({ kind: 'graph', workspace, graph: graph.name, status: 'planned', wallMs: 0 });
                     }
                 }
             }
-            if (!options.only || options.only === 'caches') {
+            if (!options.only || options.only === 'all' || options.only === 'caches' || options.only?.startsWith('caches:')) {
                 for (const graph of graphs) {
                     // Refresh only local, opted-in caches; never create a new cache from a packaged prebuilt.
-                    if (fs.existsSync(getFortemiCoreSyncStatus(workspace, graph.name).location)) {
+                    if (includes(`caches:${graph.name}`) && fs.existsSync(getFortemiCoreSyncStatus(workspace, graph.name).location)) {
                         jobs.push({ kind: 'cache', workspace, graph: graph.name, status: 'planned', wallMs: 0 });
                     }
                 }
             }
-            if ((!options.only || options.only === 'sessions') && fs.existsSync(path.join(workspace, '.aiwg/sessions/catalog.sqlite'))) {
+            if (includes('sessions') && fs.existsSync(path.join(workspace, '.aiwg/sessions/catalog.sqlite'))) {
                 jobs.push({ kind: 'sessions', workspace, status: 'planned', wallMs: 0, noManifest: 0 });
             }
             for (const kind of ['runtime', 'issues']) {
-                if (options.only && options.only !== kind)
+                if (!includes(kind))
                     continue;
                 if (kind === 'issues' && !fs.existsSync(projectAiwgPath(workspace, 'issues')))
                     continue;
                 jobs.push({ kind, workspace, status: 'planned', wallMs: 0 });
             }
         }
-        if (!options.only || options.only === 'models') {
+        if (!options.only || options.only === 'all' || options.only === 'models') {
             jobs.push({ kind: 'models', scope: 'host', status: 'planned', wallMs: 0 });
         }
         return jobs;
@@ -177,23 +175,6 @@ export async function refreshResourceGate(workspace, live) {
     const result = preflight.evaluateDispatchGate(live ?? preflight.readLiveHostResources({ paths: [workspace] }), thresholds);
     return { ok: result.ok, reason: result.failures.map((failure) => failure.reason).join('; ') || undefined };
 }
-async function graphFingerprint(workspace, graph) {
-    const files = await collectGraphIndexFiles(workspace, graph);
-    // Source import resolution also depends on the compiler/package configuration.
-    if (graph === 'source') {
-        for (const file of ['tsconfig.json', 'package.json']) {
-            if (fs.existsSync(path.join(workspace, file)))
-                files.push(path.join(workspace, file));
-        }
-    }
-    const stats = [...new Set(files)].sort().map(file => {
-        const stat = fs.statSync(file);
-        return [file, stat.mtimeMs, stat.ctimeMs, stat.size];
-    });
-    return createHash('sha256').update(JSON.stringify([
-        INDEX_VERSION, INDEX_EXTRACTOR_VERSION, GRAPH_CONFIGS[graph], resolveGraphBackendType(graph), stats,
-    ])).digest('hex');
-}
 async function refreshWorkspaceRuntime(workspace, full, runtime) {
     const directory = projectAiwgPath(workspace, 'smiths', 'toolsmith');
     const output = path.join(directory, 'runtime.json');
@@ -237,34 +218,54 @@ async function refreshWorkspaceRuntime(workspace, full, runtime) {
 async function executeJob(job, options, aliases, runtime) {
     const workspace = job.workspace ?? process.env.HOME ?? homedir();
     if (job.kind === 'graph') {
+        const graphStart = Date.now();
         const graph = job.graph;
         const config = GRAPH_CONFIGS[graph];
-        if (!config.scanDirs.some(dir => fs.existsSync(resolveGraphScanDir(workspace, dir)))) {
+        const sourceWorkspace = graph === 'framework' ? resolveFrameworkIndexRoot(workspace) : workspace;
+        if (!config.scanDirs.some(dir => fs.existsSync(resolveGraphScanDir(sourceWorkspace, dir)))) {
             job.status = 'skipped';
             job.reason = 'scan directories missing';
             return;
         }
         const directory = getGraphIndexDir(workspace, graph);
         const markerPath = path.join(directory, 'refresh-state.json');
+        const fingerprint = await graphIndexDigest(sourceWorkspace, graph);
         const marker = readJson(markerPath);
         const metadata = readJson(path.join(directory, 'metadata.json'));
-        const fingerprint = await graphFingerprint(workspace, graph);
-        const outputs = ['metadata.json', 'dependencies.json', 'tags.json', 'stats.json'];
-        if (resolveGraphBackendType(graph) === 'sqlite')
-            outputs.push('graph.db');
-        if (!options.full && marker?.fingerprint === fingerprint && metadata?.builtAt === marker.builtAt
-            && outputs.every(file => fs.existsSync(path.join(directory, file)))) {
-            job.status = 'skipped';
-            job.reason = 'unchanged';
-            return;
+        const adapter = indexAdapterRegistry(workspace).find(item => item.name === graph);
+        if (!options.full && marker?.fingerprint === fingerprint && marker.builtAt === metadata?.builtAt
+            && indexFreshnessSnapshot(adapter, workspace).pendingWork === 0) {
+            const release = await acquireDirectoryLock(`${directory}.build.lock`, {
+                timeoutMs: options.lockWaitMs ?? 0, reclaimDeadOwner: true,
+            });
+            try {
+                const current = await graphIndexDigest(sourceWorkspace, graph);
+                if (current === fingerprint && indexFreshnessSnapshot(adapter, workspace).pendingWork === 0) {
+                    recordIndexVerification(adapter, workspace, { before: fingerprint, after: current, wallMs: Date.now() - graphStart });
+                    job.status = 'skipped';
+                    job.reason = 'unchanged';
+                    return;
+                }
+            }
+            finally {
+                await release();
+            }
         }
+        const beforeOutput = outputStamp(path.join(directory, 'metadata.json'));
         const { buildIndex } = await import('./index-builder.js');
-        await buildIndex(workspace, { graph, force: Boolean(options.full), explicit: false, quiet: true, workers: options.workers,
+        await buildIndex(sourceWorkspace, { graph, force: Boolean(options.full), explicit: false, quiet: true, workers: options.workers, lockWaitMs: options.lockWaitMs ?? 0,
             onDiagnostic: message => (job.diagnostics ??= []).push(message) });
         const built = readJson(path.join(directory, 'metadata.json'));
         if (!built)
             throw new Error(`graph did not produce metadata: ${graph}`);
-        writeJson(markerPath, { fingerprint, builtAt: built.builtAt });
+        const verification = readJson(path.join(directory, 'freshness.json'));
+        if (!options.full && beforeOutput && beforeOutput === outputStamp(path.join(directory, 'metadata.json'))) {
+            job.status = 'skipped';
+            job.reason = 'unchanged';
+        }
+        if (!verification?.pendingWork && verification?.lastVerifiedDigest === fingerprint) {
+            writeJson(markerPath, { fingerprint, builtAt: built.builtAt });
+        }
     }
     else if (job.kind === 'cache') {
         const status = getFortemiCoreSyncStatus(workspace, job.graph);
@@ -333,7 +334,8 @@ async function executeJob(job, options, aliases, runtime) {
             }
         }
     }
-    job.status = 'ok';
+    if (job.status !== 'skipped')
+        job.status = 'ok';
 }
 function outputStamp(file) {
     try {
@@ -385,6 +387,17 @@ export async function refreshIndexes(options = {}, dependencies = {}) {
                 .reduce((total, receipt) => total + (receipt.totals.excluded ?? 0), 0), 0),
             wallMs: Date.now() - start,
         };
+        report.indices = [];
+        for (const workspace of workspaces.keys()) {
+            loadWorkspaceGraphs(workspace);
+            for (const adapter of selectIndexAdapters(indexAdapterRegistry(workspace), options.only)) {
+                report.indices.push({ ...indexFreshnessSnapshot(adapter, workspace), workspace });
+            }
+        }
+        if (!jobs.length && options.only && report.indices.length && report.indices.every(index => index.status === 'unsupported')) {
+            report.status = 'deferred';
+            report.reason = 'unsupported';
+        }
         return report;
     };
     if (options.dryRun)
@@ -435,6 +448,8 @@ export async function refreshIndexes(options = {}, dependencies = {}) {
                 continue;
             }
             const jobStart = Date.now();
+            let adapter;
+            let beforeDigest;
             try {
                 const gateWorkspace = job.workspace ?? workspaces.keys().next().value ?? options.cwd ?? process.cwd();
                 const gate = await (dependencies.gate ?? refreshResourceGate)(gateWorkspace);
@@ -447,6 +462,15 @@ export async function refreshIndexes(options = {}, dependencies = {}) {
                 }
                 if (job.workspace)
                     loadWorkspaceGraphs(job.workspace);
+                const workspace = job.workspace ?? options.cwd ?? process.cwd();
+                adapter = indexAdapterRegistry(workspace).find(item => item.name === (job.kind === 'graph' ? job.graph
+                    : job.kind === 'cache' ? `caches:${job.graph}` : job.kind));
+                if (adapter?.supported && job.kind !== 'graph') {
+                    try {
+                        beforeDigest = await indexAdapterDigest(adapter, workspace);
+                    }
+                    catch { /* Owner reports unavailable dependencies. */ }
+                }
                 if (job.kind === 'cache' && jobs.some(other => other.kind === 'graph'
                     && other.workspace === job.workspace && other.graph === job.graph && other.status === 'error')) {
                     job.status = 'skipped';
@@ -471,13 +495,52 @@ export async function refreshIndexes(options = {}, dependencies = {}) {
                     await executeJob(job, options, aliases, discoverRuntime);
             }
             catch (error) {
-                job.status = 'error';
-                job.error = error instanceof Error ? error.message : String(error);
+                if (error instanceof DirectoryLockContentionError) {
+                    job.status = 'deferred';
+                    job.reason = 'lock-held';
+                    report.status = 'deferred';
+                }
+                else {
+                    job.status = 'error';
+                    job.error = error instanceof Error ? error.message : String(error);
+                }
             }
             finally {
                 job.wallMs = Date.now() - jobStart;
+                if (adapter) {
+                    const workspace = job.workspace ?? options.cwd ?? process.cwd();
+                    if (adapter.supported && job.kind !== 'graph' && job.status !== 'deferred') {
+                        try {
+                            let after;
+                            let probeError;
+                            try {
+                                after = await indexAdapterDigest(adapter, workspace);
+                            }
+                            catch (error) {
+                                probeError = String(error);
+                            }
+                            if (job.kind === 'runtime' && job.status === 'ok')
+                                beforeDigest = after;
+                            const partial = job.reason && job.reason !== 'unchanged';
+                            job.freshness = recordIndexVerification(adapter, workspace, { before: beforeDigest, after,
+                                error: job.error ?? probeError, pendingWork: partial ? 1 : 0, wallMs: job.wallMs });
+                        }
+                        catch (error) {
+                            job.freshness = { ...indexFreshnessSnapshot(adapter, workspace), status: 'degraded',
+                                pendingWork: 1, lastError: String(error) };
+                        }
+                    }
+                    else
+                        job.freshness = indexFreshnessSnapshot(adapter, workspace);
+                    if (job.freshness.pendingWork && !job.error && job.status !== 'deferred' && job.kind === 'graph'
+                        && job.reason !== 'scan directories missing') {
+                        job.status = 'deferred';
+                        job.reason = 'inputs changed during build';
+                        report.status = 'deferred';
+                    }
+                }
             }
-            if (job.status !== 'error' && job.reason !== 'graph failed'
+            if (job.status !== 'error' && job.status !== 'deferred' && job.reason !== 'graph failed'
                 && job.reason !== 'no authorized discovery manifest')
                 checkpoint.completed.push(key);
             writeJson(checkpointPath, checkpoint);
@@ -534,10 +597,6 @@ export async function runIndexRefresh(args, cwd = process.cwd(), signal) {
                 else if (flag === '--exclude')
                     (options.exclude ??= []).push(value);
                 else if (flag === '--only') {
-                    if (value !== 'graphs' && value !== 'sessions' && value !== 'caches'
-                        && value !== 'runtime' && value !== 'models' && value !== 'issues') {
-                        throw new Error('--only must be graphs, sessions, caches, runtime, models, or issues');
-                    }
                     options.only = value;
                 }
                 else {

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

@@ -18,8 +18,9 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { GRAPH_CONFIGS, BUILTIN_GRAPH_CONFIGS, getGraphIndexDir, getProjectIndexRoot, loadGlobalGraphConfigs, loadUserGraphConfigs, resolveGraphBackendType, } from './types.js';
+import { GRAPH_CONFIGS, BUILTIN_GRAPH_CONFIGS, getGraphIndexDir, getProjectIndexRoot, loadWorkspaceGraphs, resolveGraphBackendType, } from './types.js';
 import { getFortemiCoreSyncStatus, } from './fortemi-core-sync.js';
+import { indexAdapterRegistry, indexFreshnessSnapshot, selectIndexAdapters } from './index-adapters.js';
 function readBuiltMeta(indexDir) {
     try {
         const metaPath = path.join(indexDir, 'metadata.json');
@@ -42,12 +43,11 @@ function readBuiltMeta(indexDir) {
  *
  * @param nowMs - injectable clock for deterministic tests (defaults to Date.now()).
  */
-export function collectIndexStatus(cwd, nowMs) {
+export function collectIndexStatus(cwd, nowMs, only) {
     // Populate the registry from module + operator config, collecting warnings
     // instead of letting malformed defs vanish (#1624).
     const warnings = [];
-    loadUserGraphConfigs(cwd, warnings);
-    loadGlobalGraphConfigs(warnings);
+    loadWorkspaceGraphs(cwd, warnings);
     const now = nowMs ?? Date.now();
     const graphs = [];
     for (const [name, config] of Object.entries(GRAPH_CONFIGS)) {
@@ -99,6 +99,10 @@ export function collectIndexStatus(cwd, nowMs) {
     const built = graphs.filter((g) => g.built).length;
     return {
         graphs,
+        indices: selectIndexAdapters(indexAdapterRegistry(cwd), only).map(adapter => ({
+            ...indexFreshnessSnapshot(adapter, cwd, now), identity: adapter.identity, backend: adapter.backend,
+            operation: adapter.operation, roots: adapter.roots(cwd), exclusions: adapter.exclusions, outputPaths: adapter.outputPaths,
+        })),
         orphanIndexDirs,
         warnings,
         fortemiCore: getFortemiCoreSyncStatus(cwd),
@@ -111,9 +115,17 @@ export function collectIndexStatus(cwd, nowMs) {
         },
     };
 }
+/** Probe inputs through their owners; the legacy synchronous reader stays available. */
+export async function probeIndexStatus(cwd, only, nowMs = Date.now()) {
+    const report = collectIndexStatus(cwd, nowMs, only);
+    const adapters = new Map(indexAdapterRegistry(cwd).map(adapter => [adapter.name, adapter]));
+    report.indices = await Promise.all(report.indices.map(async (index) => ({ ...index,
+        ...await adapters.get(index.name).probe(cwd, nowMs) })));
+    return report;
+}
 /** Render `aiwg index status` (human table or JSON). */
 export async function showIndexStatus(cwd, opts = {}) {
-    const report = collectIndexStatus(cwd);
+    const report = await probeIndexStatus(cwd, opts.only);
     if (opts.json) {
         console.log(JSON.stringify(report, null, 2));
         return;
@@ -182,6 +194,9 @@ export async function showIndexStatus(cwd, opts = {}) {
         console.log(`⚠ ${missing} registered durable index(es) are not built. Run \`aiwg index build --all\`.`);
     }
     console.log('');
+    for (const index of report.indices) {
+        console.log(`  ${index.name}: ${index.status} (target ${index.policy.targetStaleAfterMs}ms, pending ${index.pendingWork})${index.lastError ? `: ${index.lastError}` : ''}`);
+    }
     console.log(`${report.summary.total} graph(s): ${report.summary.built} built, ${missing} missing, ` +
         `${report.summary.orphans} orphan(s), ${report.summary.warnings} warning(s).`);
 }