@cleocode/core 2026.9.16 → 2026.9.17

package/dist/nexus/freshness.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Code-graph index freshness — disclosed on every graph query, and repaired
+ * inline when the repair is small (T12316).
+ *
+ * A graph answer from a stale index is a confident answer about code that no
+ * longer exists. The check compares the published generation's file manifest
+ * against the working tree: a file whose size and mtime are unchanged keeps its
+ * recorded hash, and only a metadata mismatch is re-hashed, so a checkout or
+ * `touch` that changed no bytes is not reported stale.
+ *
+ * Code placed in `packages/core/` per Package-Boundary Check — verified against AGENTS.md.
+ *
+ * @task T12316
+ * @module nexus/freshness
+ */
+import type { GraphIndexFreshness } from '@cleocode/contracts';
+/** Command that refreshes the index; incremental by default since T12315. */
+export declare const NEXUS_REFRESH_COMMAND = "cleo nexus analyze";
+/** Default number of stale files an index query may refresh inline. */
+export declare const DEFAULT_AUTO_REFRESH_MAX_FILES = 25;
+/** Default wall-clock budget for an inline refresh. */
+export declare const DEFAULT_AUTO_REFRESH_BUDGET_MS = 60000;
+/** Options for {@link assessNexusIndexFreshness}. */
+export interface NexusFreshnessOptions {
+    /** Files of the queried symbol(s); their own staleness is reported separately. */
+    symbolFiles?: readonly string[];
+    /** Maximum stale paths listed in the result. @defaultValue 10 */
+    sampleLimit?: number;
+}
+/**
+ * A freshness verdict plus the complete stale set it was computed from, so the
+ * files of a symbol identified only AFTER the query can still be judged.
+ */
+export interface NexusFreshnessAssessment {
+    /** Disclosed freshness facts. */
+    freshness: GraphIndexFreshness;
+    /** Every stale path (modified, added, deleted or unreadable). */
+    staleFiles: ReadonlySet<string>;
+}
+/**
+ * Judge the queried symbol's own files against an assessment.
+ * @param assessment - Assessment taken before the query ran.
+ * @param files - Files of the queried symbol(s), e.g. from {@link querySymbolFiles}.
+ * @returns The freshness facts with `symbolFileStale`/`symbolFile` set when files are known.
+ */
+export declare function judgeSymbolFiles(assessment: NexusFreshnessAssessment, files: readonly string[]): GraphIndexFreshness;
+/** Auto-refresh policy, read from `nexus.autoRefresh.*` config unless given. */
+export interface NexusAutoRefreshPolicy {
+    /** Whether queries may refresh the index inline. @defaultValue true */
+    enabled: boolean;
+    /** Most stale files a query refreshes inline. @defaultValue 25 */
+    maxFiles: number;
+    /** Wall-clock budget; a refresh estimated to exceed it is not started. @defaultValue 60000 */
+    budgetMs: number;
+}
+/**
+ * Assess how far the published code graph lags the working tree.
+ *
+ * @param projectRoot - Project whose graph database is inspected.
+ * @param options - Symbol files to judge individually and the stale-path sample size.
+ * @returns Freshness facts; `status: 'unknown'` carries a `reason` and is never a pass.
+ * @example
+ * ```ts
+ * const freshness = await assessNexusIndexFreshness('/repo', { symbolFiles: ['src/a.ts'] });
+ * if (freshness.status === 'stale') console.error(freshness.refreshCommand);
+ * ```
+ */
+export declare function assessNexusIndexFreshness(projectRoot: string, options?: NexusFreshnessOptions): Promise<GraphIndexFreshness>;
+/**
+ * Read the auto-refresh policy from `nexus.autoRefresh.*`, applying defaults.
+ * @param projectRoot - Project whose merged config is read.
+ * @returns The effective policy.
+ */
+export declare function readNexusAutoRefreshPolicy(projectRoot: string): Promise<NexusAutoRefreshPolicy>;
+/**
+ * Assess freshness and, when only a few files are stale, refresh the index
+ * inline before the caller answers from it.
+ *
+ * A refresh runs only when `0 < stale ≤ maxFiles` and the recorded cost
+ * estimate fits `budgetMs`; the budget also cancels the run at its next phase
+ * boundary, and publication is atomic, so an abandoned refresh leaves the
+ * previous graph intact. Every decision — refreshed, skipped or failed — is
+ * disclosed in `autoRefresh`, and the returned freshness describes the index
+ * the caller is about to read.
+ *
+ * @param projectRoot - Project whose graph is about to be queried.
+ * @param policy - Explicit policy; read from config when omitted.
+ * @returns Freshness of the index as it stands after any refresh, with its stale set.
+ */
+export declare function ensureNexusIndexFresh(projectRoot: string, policy?: NexusAutoRefreshPolicy): Promise<NexusFreshnessAssessment>;
+/**
+ * Collect the source files a graph query answer is about.
+ *
+ * Graph node ids are `<file>::<symbol>`, so a target id names its file; an
+ * explicit `filePath` is used when present. Only the answer's own target (or,
+ * for symbol lookups, each matched symbol) is considered — callers listed in
+ * the answer are not "the queried symbol".
+ *
+ * @param data - A query operation's result payload.
+ * @returns Repository-relative files of the queried symbol(s); empty when none are identifiable.
+ */
+export declare function querySymbolFiles(data: unknown): string[];
+/**
+ * Assess (and when small, repair) index freshness before a graph query.
+ *
+ * Never throws: a failed assessment is returned as `status: 'unknown'` with its
+ * reason, so it neither blocks the query nor is ever mistaken for fresh.
+ *
+ * @param projectRoot - Project whose graph is about to be queried.
+ * @returns The assessment to judge the answer against.
+ */
+export declare function assessNexusFreshnessForQuery(projectRoot: string): Promise<NexusFreshnessAssessment>;
+/**
+ * Disclose a non-fresh index as an envelope warning
+ * (`W_NEXUS_INDEX_STALE` / `W_NEXUS_INDEX_FRESHNESS_UNKNOWN`), and an inline
+ * refresh that just happened as `W_NEXUS_INDEX_REFRESHED` (info). Warnings
+ * reach `meta.warnings` through the active collector — never stderr, which
+ * would break the one-envelope stream contract (T9775).
+ *
+ * @param subject - What answered, e.g. `nexus impact`.
+ * @param freshness - Freshness of the index the answer came from.
+ */
+export declare function discloseNexusFreshness(subject: string, freshness: GraphIndexFreshness): void;
+/**
+ * Merge a freshness verdict into envelope extensions' `_nexus` block.
+ * @param extensions - Envelope extensions, possibly already carrying `_nexus`.
+ * @param freshness - Freshness of the index the answer came from.
+ * @returns New extensions with `_nexus.indexFreshness` and `_nexus.freshness` set.
+ */
+export declare function withNexusFreshnessMeta(extensions: Record<string, unknown>, freshness: GraphIndexFreshness): Record<string, unknown>;
+//# sourceMappingURL=freshness.d.ts.map

package/dist/nexus/freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.d.ts","sourceRoot":"","sources":["../../src/nexus/freshness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAQ/D,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAE1D,uEAAuE;AACvE,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD,uDAAuD;AACvD,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAKrD,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,iCAAiC;IACjC,SAAS,EAAE,mBAAmB,CAAC;IAC/B,iEAAiE;IACjE,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,wBAAwB,EACpC,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,mBAAmB,CASrB;AAED,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,QAAQ,EAAE,MAAM,CAAC;CAClB;AA6BD;;;;;;;;;;;GAWG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,mBAAmB,CAAC,CAG9B;AAwFD;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,sBAAsB,CAAC,CAwBjC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,sBAAsB,GAC9B,OAAO,CAAC,wBAAwB,CAAC,CA+DnC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAyBxD;AAED;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,wBAAwB,CAAC,CAoBnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,mBAAmB,GAAG,IAAI,CA0B5F;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,SAAS,EAAE,mBAAmB,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB"}

package/dist/nexus/freshness.js

@@ -0,0 +1,391 @@
+/**
+ * Code-graph index freshness — disclosed on every graph query, and repaired
+ * inline when the repair is small (T12316).
+ *
+ * A graph answer from a stale index is a confident answer about code that no
+ * longer exists. The check compares the published generation's file manifest
+ * against the working tree: a file whose size and mtime are unchanged keeps its
+ * recorded hash, and only a metadata mismatch is re-hashed, so a checkout or
+ * `touch` that changed no bytes is not reported stale.
+ *
+ * Code placed in `packages/core/` per Package-Boundary Check — verified against AGENTS.md.
+ *
+ * @task T12316
+ * @module nexus/freshness
+ */
+import { performance } from 'node:perf_hooks';
+import { getConfigValue } from '../config/registry.js';
+import { pushWarning } from '../output.js';
+import { getNexusDb } from '../store/nexus-sqlite.js';
+import { runNexusAnalysis } from './analyze-orchestrator.js';
+import { readFileManifest, readRunCost } from './graph-manifest.js';
+/** Command that refreshes the index; incremental by default since T12315. */
+export const NEXUS_REFRESH_COMMAND = 'cleo nexus analyze';
+/** Default number of stale files an index query may refresh inline. */
+export const DEFAULT_AUTO_REFRESH_MAX_FILES = 25;
+/** Default wall-clock budget for an inline refresh. */
+export const DEFAULT_AUTO_REFRESH_BUDGET_MS = 60_000;
+/** Share of changed files above which analysis rebuilds fully (mirrors the pipeline). */
+const FULL_REBUILD_RATIO = 0.3;
+/**
+ * Judge the queried symbol's own files against an assessment.
+ * @param assessment - Assessment taken before the query ran.
+ * @param files - Files of the queried symbol(s), e.g. from {@link querySymbolFiles}.
+ * @returns The freshness facts with `symbolFileStale`/`symbolFile` set when files are known.
+ */
+export function judgeSymbolFiles(assessment, files) {
+    const unique = [...new Set(files)];
+    if (unique.length === 0)
+        return assessment.freshness;
+    const stale = unique.find((file) => assessment.staleFiles.has(file));
+    return {
+        ...assessment.freshness,
+        symbolFileStale: stale !== undefined,
+        symbolFile: stale ?? unique[0],
+    };
+}
+/** Estimate a refresh from the last recorded run, or `null` when nothing is recorded. */
+function estimateRefreshMs(cost, staleFiles, fileCount) {
+    if (!cost)
+        return null;
+    const parseMs = cost.summary.phaseMs['parse'] ?? 0;
+    const parsed = cost.summary.parsedFiles;
+    const fixedMs = Math.max(0, cost.durationMs - parseMs);
+    const perFileMs = parsed > 0 ? parseMs / parsed : 0;
+    const full = fileCount > 0 && staleFiles / fileCount > FULL_REBUILD_RATIO;
+    const reparsed = full ? Math.max(parsed, cost.summary.resolvedFiles) : staleFiles;
+    return Math.round(fixedMs + reparsed * perFileMs);
+}
+/** Render an estimate for humans and agents alike. */
+function describeEstimate(ms, staleFiles, fileCount) {
+    if (staleFiles === 0)
+        return 'none needed';
+    const kind = fileCount > 0 && staleFiles / fileCount > FULL_REBUILD_RATIO
+        ? 'full rebuild'
+        : `incremental, re-parses ~${staleFiles} file(s)`;
+    if (ms === null)
+        return `unknown duration (${kind}; no previous analysis cost recorded)`;
+    return `~${Math.max(1, Math.round(ms / 1000))}s (${kind})`;
+}
+/**
+ * Assess how far the published code graph lags the working tree.
+ *
+ * @param projectRoot - Project whose graph database is inspected.
+ * @param options - Symbol files to judge individually and the stale-path sample size.
+ * @returns Freshness facts; `status: 'unknown'` carries a `reason` and is never a pass.
+ * @example
+ * ```ts
+ * const freshness = await assessNexusIndexFreshness('/repo', { symbolFiles: ['src/a.ts'] });
+ * if (freshness.status === 'stale') console.error(freshness.refreshCommand);
+ * ```
+ */
+export async function assessNexusIndexFreshness(projectRoot, options = {}) {
+    const assessment = await assessWithStaleSet(projectRoot, options.sampleLimit);
+    return judgeSymbolFiles(assessment, options.symbolFiles ?? []);
+}
+/** Walk the tree once and keep the full stale set alongside the disclosed facts. */
+async function assessWithStaleSet(projectRoot, sampleLimit = 10) {
+    const started = performance.now();
+    const base = {
+        refreshCommand: NEXUS_REFRESH_COMMAND,
+        stalePaths: [],
+    };
+    const db = await getNexusDb(projectRoot);
+    let manifest;
+    const none = new Set();
+    try {
+        manifest = readFileManifest(db);
+    }
+    catch (error) {
+        const freshness = {
+            ...base,
+            indexed: true,
+            status: 'unknown',
+            lastIndexedAt: null,
+            fileCount: 0,
+            staleFileCount: -1,
+            refreshEstimate: 'unknown',
+            checkMs: Math.round(performance.now() - started),
+            reason: `the recorded file manifest is unreadable: ${error instanceof Error ? error.message : String(error)}`,
+        };
+        return { freshness, staleFiles: none };
+    }
+    if (!manifest) {
+        const freshness = {
+            ...base,
+            indexed: false,
+            status: 'unknown',
+            lastIndexedAt: null,
+            fileCount: 0,
+            staleFileCount: -1,
+            refreshEstimate: 'unknown',
+            checkMs: Math.round(performance.now() - started),
+            reason: 'no file manifest is recorded — the project was never indexed, or its index predates ' +
+                `freshness tracking; run ${NEXUS_REFRESH_COMMAND} once`,
+        };
+        return { freshness, staleFiles: none };
+    }
+    const known = new Map();
+    for (const [path, size, mtimeMs, contentHash] of manifest.files)
+        known.set(path, { size, mtimeMs, contentHash });
+    const { walkRepositoryPaths } = await import('@cleocode/nexus/pipeline');
+    const unreadable = [];
+    const current = await walkRepositoryPaths(manifest.sourceRoot, undefined, (report) => {
+        if (report.status === 'failed')
+            unreadable.push(report.path);
+    }, manifest.includedRepositories, { knownFiles: known });
+    const stale = new Set(unreadable);
+    const seen = new Set();
+    for (const file of current) {
+        seen.add(file.path);
+        if (known.get(file.path)?.contentHash !== file.contentHash)
+            stale.add(file.path);
+    }
+    for (const path of known.keys())
+        if (!seen.has(path))
+            stale.add(path);
+    const fileCount = manifest.files.length;
+    const estimate = estimateRefreshMs(readRunCost(db), stale.size, fileCount);
+    const freshness = {
+        ...base,
+        indexed: true,
+        status: stale.size === 0 ? 'fresh' : 'stale',
+        lastIndexedAt: manifest.assessedAt,
+        fileCount,
+        staleFileCount: stale.size,
+        stalePaths: [...stale].sort().slice(0, sampleLimit),
+        refreshEstimate: describeEstimate(estimate, stale.size, fileCount),
+        checkMs: Math.round(performance.now() - started),
+    };
+    return { freshness, staleFiles: stale };
+}
+/**
+ * Read the auto-refresh policy from `nexus.autoRefresh.*`, applying defaults.
+ * @param projectRoot - Project whose merged config is read.
+ * @returns The effective policy.
+ */
+export async function readNexusAutoRefreshPolicy(projectRoot) {
+    const read = async (key) => {
+        try {
+            return await getConfigValue(`nexus.autoRefresh.${key}`, { projectRoot });
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const [enabled, maxFiles, budgetMs] = await Promise.all([
+        read('enabled'),
+        read('maxFiles'),
+        read('budgetMs'),
+    ]);
+    return {
+        enabled: typeof enabled === 'boolean' ? enabled : true,
+        maxFiles: typeof maxFiles === 'number' && Number.isInteger(maxFiles) && maxFiles >= 0
+            ? maxFiles
+            : DEFAULT_AUTO_REFRESH_MAX_FILES,
+        budgetMs: typeof budgetMs === 'number' && Number.isFinite(budgetMs) && budgetMs > 0
+            ? budgetMs
+            : DEFAULT_AUTO_REFRESH_BUDGET_MS,
+    };
+}
+/**
+ * Assess freshness and, when only a few files are stale, refresh the index
+ * inline before the caller answers from it.
+ *
+ * A refresh runs only when `0 < stale ≤ maxFiles` and the recorded cost
+ * estimate fits `budgetMs`; the budget also cancels the run at its next phase
+ * boundary, and publication is atomic, so an abandoned refresh leaves the
+ * previous graph intact. Every decision — refreshed, skipped or failed — is
+ * disclosed in `autoRefresh`, and the returned freshness describes the index
+ * the caller is about to read.
+ *
+ * @param projectRoot - Project whose graph is about to be queried.
+ * @param policy - Explicit policy; read from config when omitted.
+ * @returns Freshness of the index as it stands after any refresh, with its stale set.
+ */
+export async function ensureNexusIndexFresh(projectRoot, policy) {
+    const initial = await assessWithStaleSet(projectRoot);
+    const before = initial.freshness;
+    if (before.status !== 'stale')
+        return initial;
+    const effective = policy ?? (await readNexusAutoRefreshPolicy(projectRoot));
+    const skip = (reason) => ({
+        staleFiles: initial.staleFiles,
+        freshness: {
+            ...before,
+            autoRefresh: { refreshed: false, staleFiles: before.staleFileCount, durationMs: 0, reason },
+        },
+    });
+    if (!effective.enabled)
+        return skip('auto-refresh is disabled (nexus.autoRefresh.enabled = false)');
+    if (before.staleFileCount > effective.maxFiles)
+        return skip(`${before.staleFileCount} stale files exceed nexus.autoRefresh.maxFiles = ${effective.maxFiles}; ` +
+            'answered from the stale index');
+    const db = await getNexusDb(projectRoot);
+    const estimate = estimateRefreshMs(readRunCost(db), before.staleFileCount, before.fileCount);
+    if (estimate !== null && estimate > effective.budgetMs)
+        return skip(`estimated refresh ${Math.round(estimate / 1000)}s exceeds nexus.autoRefresh.budgetMs = ` +
+            `${effective.budgetMs}; answered from the stale index`);
+    const manifest = readFileManifest(db);
+    const started = performance.now();
+    try {
+        const result = await runNexusAnalysis({
+            projectRoot,
+            repoPath: manifest?.sourceRoot ?? projectRoot,
+            ...(manifest ? { includedRepositories: manifest.includedRepositories } : {}),
+            parserLimits: { signal: AbortSignal.timeout(effective.budgetMs) },
+        });
+        const after = await assessWithStaleSet(projectRoot);
+        return {
+            staleFiles: after.staleFiles,
+            freshness: {
+                ...after.freshness,
+                autoRefresh: {
+                    refreshed: result.summary.mode !== 'unchanged',
+                    staleFiles: before.staleFileCount,
+                    durationMs: Math.round(performance.now() - started),
+                    reason: `${result.summary.mode}: ${result.summary.reason}`,
+                },
+            },
+        };
+    }
+    catch (error) {
+        return {
+            staleFiles: initial.staleFiles,
+            freshness: {
+                ...before,
+                autoRefresh: {
+                    refreshed: false,
+                    staleFiles: before.staleFileCount,
+                    durationMs: Math.round(performance.now() - started),
+                    reason: `refresh failed, previous graph retained: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            },
+        };
+    }
+}
+/**
+ * Collect the source files a graph query answer is about.
+ *
+ * Graph node ids are `<file>::<symbol>`, so a target id names its file; an
+ * explicit `filePath` is used when present. Only the answer's own target (or,
+ * for symbol lookups, each matched symbol) is considered — callers listed in
+ * the answer are not "the queried symbol".
+ *
+ * @param data - A query operation's result payload.
+ * @returns Repository-relative files of the queried symbol(s); empty when none are identifiable.
+ */
+export function querySymbolFiles(data) {
+    const files = new Set();
+    const fromId = (id) => {
+        if (typeof id === 'string' && id.includes('::'))
+            files.add(id.slice(0, id.indexOf('::')));
+    };
+    const visit = (value) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return;
+        const record = value;
+        if (typeof record['filePath'] === 'string')
+            files.add(record['filePath']);
+        fromId(record['targetNodeId']);
+        fromId(record['nodeId']);
+        fromId(record['symbolId']);
+    };
+    visit(data);
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        const record = data;
+        for (const key of ['target', 'symbol', 'node'])
+            visit(record[key]);
+        // Symbol lookups (e.g. `context`) answer with one entry per matched symbol;
+        // each entry's own identity counts, never the callers nested inside it.
+        for (const key of ['results', 'matches']) {
+            const entries = record[key];
+            if (Array.isArray(entries))
+                for (const entry of entries)
+                    visit(entry);
+        }
+    }
+    return [...files];
+}
+/**
+ * Assess (and when small, repair) index freshness before a graph query.
+ *
+ * Never throws: a failed assessment is returned as `status: 'unknown'` with its
+ * reason, so it neither blocks the query nor is ever mistaken for fresh.
+ *
+ * @param projectRoot - Project whose graph is about to be queried.
+ * @returns The assessment to judge the answer against.
+ */
+export async function assessNexusFreshnessForQuery(projectRoot) {
+    try {
+        return await ensureNexusIndexFresh(projectRoot);
+    }
+    catch (error) {
+        return {
+            staleFiles: new Set(),
+            freshness: {
+                indexed: false,
+                status: 'unknown',
+                lastIndexedAt: null,
+                fileCount: 0,
+                staleFileCount: -1,
+                stalePaths: [],
+                refreshCommand: NEXUS_REFRESH_COMMAND,
+                refreshEstimate: 'unknown',
+                checkMs: 0,
+                reason: `freshness could not be assessed: ${error instanceof Error ? error.message : String(error)}`,
+            },
+        };
+    }
+}
+/**
+ * Disclose a non-fresh index as an envelope warning
+ * (`W_NEXUS_INDEX_STALE` / `W_NEXUS_INDEX_FRESHNESS_UNKNOWN`), and an inline
+ * refresh that just happened as `W_NEXUS_INDEX_REFRESHED` (info). Warnings
+ * reach `meta.warnings` through the active collector — never stderr, which
+ * would break the one-envelope stream contract (T9775).
+ *
+ * @param subject - What answered, e.g. `nexus impact`.
+ * @param freshness - Freshness of the index the answer came from.
+ */
+export function discloseNexusFreshness(subject, freshness) {
+    const refresh = freshness.autoRefresh;
+    if (refresh?.refreshed) {
+        pushWarning({
+            code: 'W_NEXUS_INDEX_REFRESHED',
+            severity: 'info',
+            message: `Refreshed the index inline before answering (${refresh.staleFiles} stale file(s), ${refresh.durationMs}ms): ${refresh.reason}`,
+        });
+    }
+    if (freshness.status === 'fresh')
+        return;
+    const symbol = freshness.symbolFileStale === true
+        ? ` The queried symbol's own file (${freshness.symbolFile}) is among them.`
+        : '';
+    const message = freshness.status === 'stale'
+        ? `${subject} answered from an index ${freshness.staleFileCount} file(s) behind the working tree ` +
+            `(indexed ${freshness.lastIndexedAt ?? 'at an unknown time'}; e.g. ${freshness.stalePaths.slice(0, 3).join(', ')}).${symbol} ` +
+            `Refresh: ${freshness.refreshCommand} — ${freshness.refreshEstimate}.` +
+            (refresh && !refresh.refreshed ? ` Not refreshed inline: ${refresh.reason}.` : '')
+        : `${subject} could not establish index freshness: ${freshness.reason ?? 'unknown reason'}.`;
+    pushWarning({
+        code: freshness.status === 'stale' ? 'W_NEXUS_INDEX_STALE' : 'W_NEXUS_INDEX_FRESHNESS_UNKNOWN',
+        severity: 'warn',
+        message,
+    });
+}
+/**
+ * Merge a freshness verdict into envelope extensions' `_nexus` block.
+ * @param extensions - Envelope extensions, possibly already carrying `_nexus`.
+ * @param freshness - Freshness of the index the answer came from.
+ * @returns New extensions with `_nexus.indexFreshness` and `_nexus.freshness` set.
+ */
+export function withNexusFreshnessMeta(extensions, freshness) {
+    const current = extensions['_nexus'];
+    const nexusMeta = current && typeof current === 'object' ? current : {};
+    return {
+        ...extensions,
+        _nexus: { ...nexusMeta, indexFreshness: freshness.status, freshness },
+    };
+}
+//# sourceMappingURL=freshness.js.map

package/dist/nexus/freshness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.js","sourceRoot":"","sources":["../../src/nexus/freshness.ts"],"names":[],"mappings":"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"}

package/dist/nexus/graph-manifest.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Compact per-generation bookkeeping for cheap freshness checks (T12316).
+ *
+ * The published `graph_assessment` carries every retained reference with its
+ * full evidence — 472 MB of JSON on this repository — so it cannot be read on
+ * the query path. The file manifest records only what a freshness check needs
+ * (path, size, mtime, content hash per indexed file), and the run summary
+ * records what the last analysis cost, so a refresh can be estimated before it
+ * is started. Both live in `_nexus_meta` next to the generation they describe.
+ *
+ * Code placed in `packages/core/` per Package-Boundary Check — verified against AGENTS.md.
+ *
+ * @task T12316
+ * @module nexus/graph-manifest
+ */
+import type { GraphIndexAssessment, GraphIndexRunSummary } from '@cleocode/contracts';
+import type { NodeSQLiteDatabase } from 'drizzle-orm/node-sqlite';
+/** One indexed file: `[path, size, mtimeMs, contentHash]`. */
+export type GraphManifestEntry = [path: string, size: number, mtimeMs: number, hash: string];
+/** Compact description of the files a published generation was built from. */
+export interface GraphFileManifest {
+    /** Generation the manifest describes. */
+    generation: string | null;
+    /** Canonical root the paths are relative to. */
+    sourceRoot: string;
+    /** Explicitly included nested repositories, needed to walk the same tree. */
+    includedRepositories: string[];
+    /** When the generation was assessed. */
+    assessedAt: string;
+    /** Every indexed file with a content hash. */
+    files: GraphManifestEntry[];
+}
+/** Cost record of the last analysis that published a generation. */
+export interface GraphRunCost {
+    /** Mode, counts and per-phase milliseconds of that run. */
+    summary: GraphIndexRunSummary;
+    /** End-to-end milliseconds, including provenance and publication. */
+    durationMs: number;
+    /** When the run finished. */
+    recordedAt: string;
+}
+/** Files with an observed size, mtime and hash, as recorded by an index scan. */
+interface ObservedFile {
+    path: string;
+    size?: number;
+    mtimeMs?: number;
+    contentHash?: string;
+}
+/**
+ * Build the manifest for a generation from its observed files.
+ * @param assessment - Assessment of the generation (source root, scope, timestamp).
+ * @param files - Files whose size, mtime and hash were observed; others are omitted.
+ * @returns The compact manifest.
+ */
+export declare function buildFileManifest(assessment: Pick<GraphIndexAssessment, 'generation' | 'sourceRoot' | 'includedRepositories' | 'assessedAt'>, files: readonly ObservedFile[]): GraphFileManifest;
+/**
+ * Write the manifest; call inside the transaction that publishes its generation.
+ * @param tx - Open transaction on the project graph database.
+ * @param manifest - Manifest of the generation being committed.
+ */
+export declare function writeFileManifest(tx: NodeSQLiteDatabase, manifest: GraphFileManifest): void;
+/**
+ * Remove the manifest; call when a generation is published without one, so a
+ * stale manifest can never describe a different generation.
+ * @param tx - Open transaction on the project graph database.
+ */
+export declare function clearFileManifest(tx: NodeSQLiteDatabase): void;
+/**
+ * Read the manifest of the committed generation.
+ * @param db - Project graph database.
+ * @returns The manifest, or `null` when the generation predates manifests.
+ * @throws When a stored manifest is malformed.
+ */
+export declare function readFileManifest(db: NodeSQLiteDatabase): GraphFileManifest | null;
+/**
+ * Record what the last publishing analysis cost; advisory, used for estimates.
+ * @param db - Project graph database.
+ * @param cost - Summary and duration of the run.
+ */
+export declare function writeRunCost(db: NodeSQLiteDatabase, cost: GraphRunCost): void;
+/**
+ * Read the last recorded run cost.
+ * @param db - Project graph database.
+ * @returns The cost, or `null` when none (or an unreadable one) is recorded.
+ */
+export declare function readRunCost(db: NodeSQLiteDatabase): GraphRunCost | null;
+export {};
+//# sourceMappingURL=graph-manifest.d.ts.map

package/dist/nexus/graph-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-manifest.d.ts","sourceRoot":"","sources":["../../src/nexus/graph-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEtF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAQlE,8DAA8D;AAC9D,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAE7F,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,KAAK,EAAE,kBAAkB,EAAE,CAAC;CAC7B;AAED,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,OAAO,EAAE,oBAAoB,CAAC;IAC9B,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;CACpB;AA0BD,iFAAiF;AACjF,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,IAAI,CACd,oBAAoB,EACpB,YAAY,GAAG,YAAY,GAAG,sBAAsB,GAAG,YAAY,CACpE,EACD,KAAK,EAAE,SAAS,YAAY,EAAE,GAC7B,iBAAiB,CAanB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,kBAAkB,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAG3F;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,kBAAkB,GAAG,IAAI,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,kBAAkB,GAAG,iBAAiB,GAAG,IAAI,CAMjF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAG7E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,kBAAkB,GAAG,YAAY,GAAG,IAAI,CAOvE"}