brainclaw 1.24.0 → 1.26.0

package/dist/core/code-map/backend.js

@@ -10,20 +10,69 @@
  */
 import { execFileSync } from 'node:child_process';
 import path from 'node:path';
-import { readManifest, storeExists } from './store.js';
+import { readManifest, readShard, storeExists } from './store.js';
 import { refresh as runRefresh } from './refresh.js';
-import { applyGitHeadDrift, withCoarse } from './freshness.js';
+import { applyGitHeadDrift, withFreshness } from './freshness.js';
 import { brief as runBrief, find as runFind } from './query.js';
+import { impact as runImpact } from './impact.js';
+import { exportSubgraph } from './export.js';
+import { fileId } from './ids.js';
 import { resolveTraversal, aggregateFind, aggregateBrief } from './aggregate.js';
 import { defaultMemoryReader } from './memory-reader.js';
 import { listNestedProjects, refreshWorkspaceCascade } from './cascade.js';
 import { loadConfig } from '../config.js';
 /** spec §9 caps the brief reading list at 12 files. */
 export const BRIEF_FILE_CAP = 12;
+/**
+ * Agent-facing file outline (P2b). The symbol count is deliberately bounded:
+ * an outline is a navigation aid, not a replacement for opening a generated
+ * source file. `symbol_count` always records the complete indexed count.
+ */
+export const OUTLINE_SYMBOL_CAP = 200;
+/** Diagnostics are useful context, but unbounded provider facts are not. */
+export const OUTLINE_DIAGNOSTIC_CAP = 20;
 function badge(status, details = {}) {
-    // pln#601 — stamp the coarse rollup at construction so every backend-built badge
-    // (status, missing_index fallbacks, find/brief base) carries it uniformly.
-    return withCoarse({ status, details });
+    // pln#601 — build the uniform freshness envelope for every backend surface
+    // It always includes index and spot-check details.
+    return withFreshness({ status, details });
+}
+/**
+ * Convert a user path into the POSIX project-relative identity used by shards.
+ * This is pure path arithmetic: outline must not stat, parse, or otherwise touch
+ * the live source file on its read path.
+ */
+function normalizeOutlinePath(requestedPath, projectRoot) {
+    const root = path.resolve(projectRoot);
+    const absolute = path.resolve(root, requestedPath);
+    const relative = path.relative(root, absolute);
+    if (!relative || relative === '.' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        return null;
+    }
+    return relative.replace(/\\/g, '/');
+}
+function outlineLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return OUTLINE_SYMBOL_CAP;
+    return Math.min(Math.max(Math.floor(limit), 0), OUTLINE_SYMBOL_CAP);
+}
+function compareOutlineSymbols(a, b) {
+    // Symbols normally always have spans. Keep malformed/legacy span-less nodes
+    // deterministic and at the end instead of trusting shard append order.
+    const as = a.span;
+    const bs = b.span;
+    if (as && bs) {
+        return as.start_line - bs.start_line
+            || as.start_col - bs.start_col
+            || as.end_line - bs.end_line
+            || as.end_col - bs.end_col
+            || a.name.localeCompare(b.name)
+            || a.node_id.localeCompare(b.node_id);
+    }
+    if (as)
+        return -1;
+    if (bs)
+        return 1;
+    return a.name.localeCompare(b.name) || a.node_id.localeCompare(b.node_id);
 }
 /**
  * Read the working tree's current commit at `root` (read-path git-HEAD drift,
@@ -244,6 +293,114 @@ export class JsonlBackend {
             freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
         };
     }
+    /**
+     * Explain a target's resolved blast radius. Unlike brief(), this deliberately
+     * stays store-local: impact only traverses persisted P1c/P1d edges and reports
+     * their concrete causes, with an opt-in bounded transitive walk.
+     */
+    async impact(input) {
+        const ctx = this.queryContext(input);
+        const out = runImpact(input.target, { depth: input.depth, limit: input.limit }, ctx);
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const base = badge(out.freshness_badge.status, out.freshness_badge.details);
+        return {
+            ...out,
+            freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
+        };
+    }
+    /**
+     * Export only a caller-selected, hard-bounded local graph. This stays
+     * store-local even at a multi-project root: implicit workspace graph dumps
+     * are intentionally unsupported.
+     */
+    async exportGraph(input) {
+        const ctx = this.queryContext(input);
+        const out = exportSubgraph(input.target, input, ctx);
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const base = badge(out.freshness_badge.status, out.freshness_badge.details);
+        return {
+            ...out,
+            freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
+        };
+    }
+    /**
+     * Return an indexed file's symbols in source order. This reads exactly one
+     * manifest and one deterministic shard; it never calls refresh, extractor, or
+     * the lazy live-file validator, so the response is a snapshot of the index.
+     */
+    async outline(input) {
+        const cwd = input.cwd ?? process.cwd();
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const root = manifest?.project_root ?? cwd;
+        const normalizedPath = normalizeOutlinePath(input.path.trim(), root) ?? input.path.trim().replace(/\\/g, '/');
+        const missing = () => ({
+            path: normalizedPath,
+            index_status: 'missing_index',
+            file_indexed: false,
+            parse_status: null,
+            symbol_count: 0,
+            symbols: [],
+            truncated: false,
+            diagnostics: [],
+            diagnostics_truncated: false,
+            freshness_badge: badge('missing_index', { hint: 'run refresh' }),
+        });
+        if (!manifest || manifest.freshness.status === 'missing_index')
+            return missing();
+        const freshnessBadge = this.withHeadDrift(badge(manifest.freshness.status, {
+            stale_file_count: manifest.freshness.stale_file_count,
+            partial_reason: manifest.freshness.partial_reason,
+        }), manifest, input.cwd);
+        const safePath = normalizeOutlinePath(input.path.trim(), root);
+        if (!safePath) {
+            return {
+                ...missing(),
+                index_status: 'file_not_indexed',
+                freshness_badge: freshnessBadge,
+            };
+        }
+        const shard = readShard(fileId(manifest.project_id, safePath), input.cwd, input.preferredDirName);
+        if (!shard || shard.path !== safePath) {
+            return {
+                path: safePath,
+                index_status: 'file_not_indexed',
+                file_indexed: false,
+                parse_status: null,
+                symbol_count: 0,
+                symbols: [],
+                truncated: false,
+                diagnostics: [],
+                diagnostics_truncated: false,
+                freshness_badge: freshnessBadge,
+            };
+        }
+        const allSymbols = shard.nodes
+            .filter((node) => node.kind === 'symbol')
+            .map((node) => ({
+            node_id: node.id,
+            name: node.name,
+            kind: node.kind,
+            subtype: node.subtype ?? null,
+            span: node.span ?? null,
+            exported: node.exported,
+            confidence: node.confidence,
+        }))
+            .sort(compareOutlineSymbols);
+        const limit = outlineLimit(input.limit);
+        const diagnostics = shard.diagnostics.slice(0, OUTLINE_DIAGNOSTIC_CAP);
+        return {
+            path: safePath,
+            index_status: 'indexed',
+            file_indexed: true,
+            parse_status: shard.parse_status,
+            symbol_count: allSymbols.length,
+            symbols: allSymbols.slice(0, limit).map(({ node_id: _nodeId, ...symbol }) => symbol),
+            truncated: allSymbols.length > limit,
+            diagnostics,
+            diagnostics_truncated: shard.diagnostics.length > diagnostics.length,
+            freshness_badge: freshnessBadge,
+        };
+    }
     /**
      * Annotate a read badge with git-HEAD drift vs the commit the index was built
      * against (`manifest.git.head`). trp_42688015 — a branch switch (whole-tree move)

package/dist/core/code-map/core.js

@@ -15,6 +15,7 @@ function fileOnlyResult(input, parseStatus) {
         imports: [],
         exports: [],
         tests: [],
+        usages: [],
         facts: [{ code: 'skipped_unsupported', message: `no provider for ${input.path}` }],
         attributes: { parseStatus },
     }, input);

package/dist/core/code-map/export.js

@@ -0,0 +1,212 @@
+/**
+ * Bounded Code Map subgraph export. Mermaid is rendered from this module's JSON
+ * model; it never takes a second, potentially different graph traversal.
+ */
+import path from 'node:path';
+import { withFreshness } from './freshness.js';
+import { listShards, readManifest } from './store.js';
+/** Absolute traversal and response ceilings: a whole-graph export is impossible. */
+export const CODE_EXPORT_MAX_DEPTH = 4;
+export const CODE_EXPORT_NODE_CAP = 100;
+export const CODE_EXPORT_EDGE_CAP = 200;
+/** Low-confidence extracted data is never included by default or opt-out. */
+export const CODE_EXPORT_MIN_CONFIDENCE = 0.5;
+function clampInteger(value, fallback, min, max) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.min(Math.max(Math.floor(value), min), max);
+}
+function clampConfidence(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return CODE_EXPORT_MIN_CONFIDENCE;
+    return Math.min(Math.max(value, CODE_EXPORT_MIN_CONFIDENCE), 1);
+}
+function normalizePath(value) {
+    return value.replace(/\\/g, '/');
+}
+function normalizeDirection(value) {
+    return value === 'outgoing' || value === 'incoming' || value === 'both' ? value : 'both';
+}
+function normalizeFormat(value) {
+    return value === 'mermaid' || value === 'json' ? value : 'json';
+}
+function normalizeTargetKind(value, target) {
+    return value === 'symbol' || value === 'file' ? value : inferTargetKind(target);
+}
+function inferTargetKind(target) {
+    return /[\\/]/.test(target)
+        || /\.(?:[cm]?[jt]sx?|py|php|java|go|rs|cs|rb|c|cc|cpp|cxx|h|hpp)$/i.test(target)
+        ? 'file'
+        : 'symbol';
+}
+/** No selector may address the project root itself or escape it. */
+function normalizeFileTarget(target, projectRoot) {
+    const root = path.resolve(projectRoot);
+    const absolute = path.resolve(root, target);
+    const relative = path.relative(root, absolute);
+    if (!relative || relative === '.' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        return null;
+    return normalizePath(relative);
+}
+function compareNodes(a, b) {
+    const as = a.span;
+    const bs = b.span;
+    return a.path.localeCompare(b.path)
+        || (as?.start_line ?? -1) - (bs?.start_line ?? -1)
+        || (as?.start_col ?? -1) - (bs?.start_col ?? -1)
+        || a.kind.localeCompare(b.kind)
+        || a.name.localeCompare(b.name)
+        || a.id.localeCompare(b.id);
+}
+function compareEdges(a, b) {
+    return a.from.localeCompare(b.from)
+        || a.to.localeCompare(b.to)
+        || a.kind.localeCompare(b.kind)
+        || (a.source?.path ?? '').localeCompare(b.source?.path ?? '')
+        || (a.source?.line ?? -1) - (b.source?.line ?? -1)
+        || a.id.localeCompare(b.id);
+}
+function graphNode(node) {
+    return { id: node.id, kind: node.kind, subtype: node.subtype ?? null, lang: node.lang, name: node.name, path: node.path,
+        span: node.span ?? null, exported: node.exported, confidence: node.confidence };
+}
+function graphEdge(edge) {
+    return { id: edge.id, from: edge.from, to: edge.to, kind: edge.kind, confidence: edge.confidence, source: edge.source ?? null };
+}
+function matchesRoot(node, target, targetKind, normalizedPath) {
+    return targetKind === 'file'
+        ? node.kind === 'file' && normalizedPath !== null && normalizePath(node.path) === normalizedPath
+        : node.kind === 'symbol' && node.name === target;
+}
+function usableEdge(edge, nodes, minConfidence) {
+    return edge.confidence >= minConfidence
+        && (nodes.get(edge.from)?.confidence ?? -Infinity) >= minConfidence
+        && (nodes.get(edge.to)?.confidence ?? -Infinity) >= minConfidence;
+}
+function touches(edge, nodeId, direction) {
+    return ((direction === 'outgoing' || direction === 'both') && edge.from === nodeId)
+        || ((direction === 'incoming' || direction === 'both') && edge.to === nodeId);
+}
+function neighbor(edge, nodeId) {
+    return edge.from === nodeId ? edge.to : edge.from;
+}
+function emptyOutput(target, targetKind, limits, freshness, format) {
+    const graph = {
+        target, target_kind: targetKind, root_node_ids: [], nodes: [], edges: [], limits,
+        truncated: { roots: false, nodes: false, edges: false, depth: false }, freshness_badge: freshness,
+    };
+    return format === 'mermaid' ? { ...graph, format, mermaid: toMermaid(graph) } : { ...graph, format };
+}
+/**
+ * Select a deterministic, confidence-filtered neighborhood from persisted shards.
+ * No refresh, parse, inference, service call, or unbounded response occurs here.
+ */
+export function exportSubgraph(targetInput, options, ctx) {
+    const target = targetInput.trim();
+    const targetKind = normalizeTargetKind(options?.targetKind, target);
+    const format = normalizeFormat(options?.format);
+    const limits = {
+        direction: normalizeDirection(options?.direction),
+        max_depth: clampInteger(options?.depth, 1, 0, CODE_EXPORT_MAX_DEPTH),
+        max_nodes: clampInteger(options?.maxNodes, CODE_EXPORT_NODE_CAP, 1, CODE_EXPORT_NODE_CAP),
+        max_edges: clampInteger(options?.maxEdges, CODE_EXPORT_EDGE_CAP, 0, CODE_EXPORT_EDGE_CAP),
+        min_confidence: clampConfidence(options?.minConfidence),
+    };
+    const manifest = readManifest(ctx.cwd, ctx.preferredDirName);
+    const missing = withFreshness({ status: 'missing_index', details: { hint: 'run refresh' } });
+    if (!manifest || manifest.freshness.status === 'missing_index' || !target)
+        return emptyOutput(target, targetKind, limits, missing, format);
+    const targetPath = targetKind === 'file' ? normalizeFileTarget(target, manifest.project_root) : null;
+    if (targetKind === 'file' && !targetPath) {
+        return emptyOutput(target, targetKind, limits, withFreshness({
+            status: manifest.freshness.status, details: { invalid_target: 'file path must be inside the indexed project' },
+        }), format);
+    }
+    const allNodes = new Map();
+    const allEdges = new Map();
+    for (const shard of listShards(ctx.cwd, ctx.preferredDirName).sort((a, b) => a.path.localeCompare(b.path) || a.file_id.localeCompare(b.file_id))) {
+        for (const node of shard.nodes)
+            if (!allNodes.has(node.id))
+                allNodes.set(node.id, node);
+        for (const edge of shard.edges)
+            if (!allEdges.has(edge.id))
+                allEdges.set(edge.id, edge);
+    }
+    const nodes = new Map([...allNodes.entries()].filter(([, node]) => node.confidence >= limits.min_confidence));
+    const edges = [...allEdges.values()].filter((edge) => usableEdge(edge, nodes, limits.min_confidence)).sort(compareEdges);
+    const roots = [...nodes.values()].filter((node) => matchesRoot(node, target, targetKind, targetPath)).sort(compareNodes);
+    const selected = new Set();
+    const rootNodeIds = [];
+    let rootsTruncated = false;
+    for (const root of roots) {
+        if (selected.size >= limits.max_nodes) {
+            rootsTruncated = true;
+            break;
+        }
+        selected.add(root.id);
+        rootNodeIds.push(root.id);
+    }
+    const selectedEdges = new Map();
+    const visited = new Set(rootNodeIds);
+    let nodesTruncated = false;
+    let edgesTruncated = false;
+    let depthTruncated = false;
+    let frontier = [...rootNodeIds];
+    for (let currentDepth = 0; frontier.length > 0; currentDepth++) {
+        const next = new Set();
+        frontier.sort((a, b) => compareNodes(nodes.get(a), nodes.get(b)));
+        for (const nodeId of frontier) {
+            const incident = edges.filter((edge) => touches(edge, nodeId, limits.direction));
+            if (currentDepth >= limits.max_depth) {
+                if (incident.some((edge) => !selectedEdges.has(edge.id)))
+                    depthTruncated = true;
+                continue;
+            }
+            for (const edge of incident) {
+                const adjacent = neighbor(edge, nodeId);
+                if (!selected.has(adjacent) && selected.size >= limits.max_nodes) {
+                    nodesTruncated = true;
+                    continue;
+                }
+                if (selectedEdges.size >= limits.max_edges && !selectedEdges.has(edge.id)) {
+                    edgesTruncated = true;
+                    continue;
+                }
+                selected.add(adjacent);
+                selectedEdges.set(edge.id, edge);
+                if (!visited.has(adjacent)) {
+                    visited.add(adjacent);
+                    next.add(adjacent);
+                }
+            }
+        }
+        frontier = [...next];
+    }
+    const graph = {
+        target, target_kind: targetKind, root_node_ids: rootNodeIds,
+        nodes: [...selected].map((id) => nodes.get(id)).filter((node) => node !== undefined).sort(compareNodes).map(graphNode),
+        edges: [...selectedEdges.values()].sort(compareEdges).map(graphEdge),
+        limits, truncated: { roots: rootsTruncated, nodes: nodesTruncated, edges: edgesTruncated, depth: depthTruncated },
+        freshness_badge: withFreshness({ status: manifest.freshness.status,
+            details: { stale_file_count: manifest.freshness.stale_file_count, partial_reason: manifest.freshness.partial_reason } }),
+    };
+    return format === 'mermaid' ? { ...graph, format, mermaid: toMermaid(graph) } : { ...graph, format };
+}
+function mermaidLabel(node) {
+    return JSON.stringify(`${node.name} (${node.kind})`.replace(/[\r\n]/g, ' '));
+}
+/** Deterministic textual projection of a graph already selected by exportSubgraph. */
+export function toMermaid(graph) {
+    const ids = new Map(graph.nodes.map((node, index) => [node.id, `n${index}`]));
+    const lines = ['flowchart TD'];
+    for (const node of graph.nodes)
+        lines.push(`  ${ids.get(node.id)}[${mermaidLabel(node)}]`);
+    for (const edge of graph.edges) {
+        const from = ids.get(edge.from);
+        const to = ids.get(edge.to);
+        if (from && to)
+            lines.push(`  ${from} -->|${edge.kind} · ${edge.confidence}| ${to}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=export.js.map

package/dist/core/code-map/finalizer.js

@@ -82,6 +82,9 @@ export function finalize(draft, input) {
     const byName = new Map();
     // node id -> index in `nodes`, so an export clause can flip `exported` in place.
     const nodeIndexById = new Map();
+    // P4 resolves provider draft ordinals to final symbol ids only here, after the
+    // identity authority has minted them. This keeps providers id-free.
+    const definitionIdsByOrdinal = new Map();
     const pushSymbol = (subtype, name, span, exported, confidence) => {
         const id = symNodeId(projectId, path, lang, subtype, name, span);
         nodeIndexById.set(id, nodes.length);
@@ -127,7 +130,8 @@ export function finalize(draft, input) {
     for (const item of items) {
         if (item.kind === 'def') {
             const d = item.ref;
-            pushSymbol(d.subtype, d.name, d.span, d.exported === true, d.confidence ?? 1.0);
+            const id = pushSymbol(d.subtype, d.name, d.span, d.exported === true, d.confidence ?? 1.0);
+            definitionIdsByOrdinal.set(d.ordinal, id);
         }
         else if (item.kind === 'import') {
             const im = item.ref;
@@ -179,6 +183,46 @@ export function finalize(draft, input) {
             });
         }
     }
+    // P4 lexical usages. Local targets are already proven by the provider's tree
+    // walk; imported bindings become candidates and are materialized only by the
+    // whole-project resolver when the target symbol is unique and importable.
+    const referenceCandidates = [];
+    for (const usage of draft.usages ?? []) {
+        const from = usage.fromDefinitionOrdinal === undefined
+            ? fileNode
+            : definitionIdsByOrdinal.get(usage.fromDefinitionOrdinal);
+        if (!from)
+            continue;
+        const confidence = usage.confidence ?? 1.0;
+        const source = { path, line: usage.span.start_line };
+        if (usage.target.kind === 'import') {
+            // Textual hints are deliberately local-only. An imported binding gets no
+            // graph edge until `resolveProjectImports` proves its target symbol.
+            if (usage.kind === 'calls' || usage.kind === 'references') {
+                referenceCandidates.push({
+                    from,
+                    kind: usage.kind,
+                    module: usage.target.module,
+                    imported_name: usage.target.importedName,
+                    confidence,
+                    source,
+                });
+            }
+            continue;
+        }
+        const to = definitionIdsByOrdinal.get(usage.target.definitionOrdinal);
+        if (!to)
+            continue;
+        edges.push({
+            id: edgeId({ projectId, from, to, kind: usage.kind }),
+            from,
+            to,
+            kind: usage.kind,
+            confidence,
+            source,
+            origin: usage.kind === 'possible_textual_match' ? 'usage_textual' : 'usage_local',
+        });
+    }
     const parseStatus = draft.attributes?.parseStatus ?? 'parsed';
     const diagnostics = draft.facts.map((f) => ({ ...f }));
     // Validate the finalized output against the durable schemas (spec §6).
@@ -186,6 +230,17 @@ export function finalize(draft, input) {
         NodeSchema.parse(n);
     for (const e of edges)
         EdgeSchema.parse(e);
-    return { parseStatus, nodes, edges, diagnostics };
+    const result = { parseStatus, nodes, edges, diagnostics };
+    // P1's oracle intentionally compares the enumerable JSON result. Keep the
+    // resolver hand-off available to refresh without changing that stable shape.
+    if (referenceCandidates.length > 0) {
+        Object.defineProperty(result, 'referenceCandidates', {
+            value: referenceCandidates,
+            enumerable: false,
+            configurable: false,
+            writable: false,
+        });
+    }
+    return result;
 }
 //# sourceMappingURL=finalizer.js.map

package/dist/core/code-map/freshness.js

@@ -8,7 +8,7 @@
  *    extractor_config + the active language set + (P1a) the registry's
  *    `configHashInputs()` (provider versions + every query-asset hash). Changing
  *    ignore rules, size caps, supported extensions, query budget, active langs, a
- *    provider version, OR a tags/imports `.scm` => stale_extractor.
+ *    provider version, query assets, OR local resolver config => stale_extractor.
  *    NOTE: grammar/engine hashes are deliberately NOT folded in (spec §6.2):
  *    stale_grammar (changed parse binary) is kept separable from stale_extractor.
  *  - `shardFreshnessStatus` — classify a stored shard against the current
@@ -45,9 +45,72 @@ export function coarseFreshness(status) {
         }
     }
 }
-/** pln#601 — stamp/refresh a badge's `coarse` rollup from its (possibly just-adjusted) status. */
-export function withCoarse(b) {
-    return { ...b, coarse: coarseFreshness(b.status) };
+/**
+ * Build the canonical, surface-uniform badge. `freshness` is derived solely from
+ * the index state supplied as `status`; a query's bounded spot-check is diagnostic
+ * evidence under `details.spot_check`, never a competing top-level badge.
+ */
+export function makeFreshnessBadge(status, options = {}) {
+    const spot = options.spotCheck ?? {};
+    return {
+        freshness: coarseFreshness(status),
+        status,
+        details: {
+            ...(options.extra ?? {}),
+            index: {
+                status,
+                stale_file_count: options.staleFileCount ?? 0,
+                partial_reason: options.partialReason ?? null,
+                git_head_changed: options.gitHeadChanged ?? null,
+            },
+            spot_check: {
+                status: spot.status ?? 'not_run',
+                checked_files: spot.checked_files ?? 0,
+                stale_changed_files: spot.stale_changed_files ?? [],
+                deleted_files: spot.deleted_files ?? [],
+                unchecked_files: spot.unchecked_files ?? [],
+                budget_exhausted: spot.budget_exhausted ?? false,
+                partial_reason: spot.partial_reason ?? null,
+            },
+        },
+    };
+}
+/**
+ * Compatibility normalizer for internal callers that previously constructed a
+ * `{ status, details }` badge. It preserves non-freshness metadata while always
+ * adding the two canonical detail sections.
+ */
+export function withFreshness(b) {
+    const raw = b.details ?? {};
+    const index = raw.index;
+    const spot = raw.spot_check;
+    const known = new Set([
+        'index', 'spot_check', 'stale_file_count', 'partial_reason', 'git_head_changed',
+        'stale_changed_files', 'deleted_files', 'unchecked_files', 'budget',
+    ]);
+    const extra = Object.fromEntries(Object.entries(raw).filter(([key]) => !known.has(key)));
+    const stringArray = (value) => Array.isArray(value) ? value.map(String).sort() : [];
+    const numberValue = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+    const nullableString = (value) => typeof value === 'string' ? value : value === null ? null : undefined;
+    const git = (index?.git_head_changed ?? raw.git_head_changed);
+    const gitHeadChanged = git && typeof git.index_head === 'string' && typeof git.current_head === 'string'
+        ? { index_head: git.index_head, current_head: git.current_head }
+        : null;
+    return makeFreshnessBadge(b.status, {
+        staleFileCount: numberValue(index?.stale_file_count ?? raw.stale_file_count),
+        partialReason: nullableString(index?.partial_reason ?? raw.partial_reason),
+        gitHeadChanged,
+        spotCheck: {
+            status: spot?.status,
+            checked_files: numberValue(spot?.checked_files),
+            stale_changed_files: stringArray(spot?.stale_changed_files ?? raw.stale_changed_files),
+            deleted_files: stringArray(spot?.deleted_files ?? raw.deleted_files),
+            unchecked_files: stringArray(spot?.unchecked_files ?? raw.unchecked_files),
+            budget_exhausted: spot?.budget_exhausted === true,
+            partial_reason: nullableString(spot?.partial_reason),
+        },
+        extra,
+    });
 }
 /** Stable serialization: sort object keys recursively so hashing is order-independent. */
 function stableStringify(value) {
@@ -69,11 +132,12 @@ function stableStringify(value) {
  * (dec#109 P0#3). Optional + omitted-vs-undefined hash the same so legacy callers
  * (config-only) keep a stable hash for that input combination.
  */
-export function computeExtractorConfigHash(config, activeLanguages, registryInputs) {
+export function computeExtractorConfigHash(config, activeLanguages, registryInputs, resolverConfigFingerprint) {
     const payload = {
         extractor_config: config,
         active_languages: [...activeLanguages].sort(),
         registry: registryInputs ?? null,
+        resolver_config: resolverConfigFingerprint ?? null,
     };
     return `sha256:${crypto.createHash('sha256').update(stableStringify(payload)).digest('hex')}`;
 }
@@ -164,16 +228,18 @@ export function summarizeFreshness(shards) {
  * actionable status; only the cause detail is added.
  */
 export function applyGitHeadDrift(badge, indexHead, currentHead) {
+    const normalized = withFreshness(badge);
+    const currentIndex = normalized.details.index;
     if (!indexHead || !currentHead || indexHead === currentHead)
-        return withCoarse(badge);
-    const status = badge.status === 'fresh' ? 'stale_git_head' : badge.status;
-    return {
-        status,
-        coarse: coarseFreshness(status),
-        details: {
-            ...badge.details,
-            git_head_changed: { index_head: indexHead, current_head: currentHead },
-        },
-    };
+        return normalized;
+    const status = normalized.status === 'fresh' ? 'stale_git_head' : normalized.status;
+    const extra = Object.fromEntries(Object.entries(normalized.details).filter(([key]) => key !== 'index' && key !== 'spot_check'));
+    return makeFreshnessBadge(status, {
+        staleFileCount: currentIndex.stale_file_count,
+        partialReason: currentIndex.partial_reason,
+        gitHeadChanged: { index_head: indexHead, current_head: currentHead },
+        spotCheck: normalized.details.spot_check,
+        extra,
+    });
 }
 //# sourceMappingURL=freshness.js.map