brainclaw 1.25.0 → 1.26.0

package/dist/commands/code-map.js

@@ -15,10 +15,7 @@ function badgeLine(badge) {
     const detail = detailKeys.length
         ? ` (${detailKeys.map((k) => `${k}=${JSON.stringify(badge.details[k])}`).join(', ')})`
         : '';
-    // pln#601 — lead with the coarse rollup (uniform across all read surfaces), then
-    // the precise status + details. `coarse` may be absent on legacy/hand-built badges.
-    const coarse = badge.coarse ? `${badge.coarse} · ` : '';
-    return `Freshness: ${coarse}${badge.status}${detail}`;
+    return `Freshness: ${badge.freshness}${detail}`;
 }
 export async function runCodeMap(subcommand, args, options = {}) {
     const normalized = (subcommand ?? '').trim().toLowerCase();

package/dist/commands/mcp.js

@@ -1097,7 +1097,7 @@ async function _executeMcpToolCallInner(payload) {
                 const status = await be.status({ cwd, cascade: args.cascade === true });
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `Code Map: ${status.store_exists ? 'store present' : 'no store'} — freshness=${status.freshness_badge.status}` }],
+                        content: [{ type: 'text', text: `Code Map: ${status.store_exists ? 'store present' : 'no store'} — freshness=${status.freshness_badge.freshness}` }],
                         structuredContent: { ...status, freshness_badge: status.freshness_badge },
                     }),
                 };
@@ -1108,7 +1108,7 @@ async function _executeMcpToolCallInner(payload) {
                 const cascadeNote = result.cascade ? ` cascade=${result.cascade.children_refreshed} child(ren)+root` : '';
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `Code Map refresh [${result.scope}]: ran=${result.ran} freshness=${result.freshness_badge.status}${cascadeNote}${result.lock_status ? ` (${result.lock_status})` : ''}` }],
+                        content: [{ type: 'text', text: `Code Map refresh [${result.scope}]: ran=${result.ran} freshness=${result.freshness_badge.freshness}${cascadeNote}${result.lock_status ? ` (${result.lock_status})` : ''}` }],
                         structuredContent: { ...result, freshness_badge: result.freshness_badge },
                     }),
                 };
@@ -1122,7 +1122,7 @@ async function _executeMcpToolCallInner(payload) {
                 const result = await be.find({ query, limit, cwd });
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `Code Map find "${result.query}": ${result.matches.length} match(es), freshness=${result.freshness_badge.status}` }],
+                        content: [{ type: 'text', text: `Code Map find "${result.query}": ${result.matches.length} match(es), freshness=${result.freshness_badge.freshness}` }],
                         structuredContent: { ...result, freshness_badge: result.freshness_badge },
                     }),
                 };
@@ -1143,7 +1143,7 @@ async function _executeMcpToolCallInner(payload) {
                 const result = await be.exportGraph({ target, targetKind, direction, depth, maxNodes, maxEdges, minConfidence, format, cwd });
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `Code Map export "${result.target}": ${result.nodes.length} node(s), ${result.edges.length} edge(s), depth=${result.limits.max_depth}, freshness=${result.freshness_badge.status}` }],
+                        content: [{ type: 'text', text: `Code Map export "${result.target}": ${result.nodes.length} node(s), ${result.edges.length} edge(s), depth=${result.limits.max_depth}, freshness=${result.freshness_badge.freshness}` }],
                         structuredContent: { ...result, freshness_badge: result.freshness_badge },
                     }),
                 };
@@ -1159,7 +1159,7 @@ async function _executeMcpToolCallInner(payload) {
                 const result = await be.impact({ target, depth, limit, cwd });
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `Code Map impact "${result.target}": ${result.risk.counters.direct_dependents} direct, ${result.risk.counters.transitive_dependents} transitive dependent(s), risk=${result.risk.score}, freshness=${result.freshness_badge.status}` }],
+                        content: [{ type: 'text', text: `Code Map impact "${result.target}": ${result.risk.counters.direct_dependents} direct, ${result.risk.counters.transitive_dependents} transitive dependent(s), risk=${result.risk.score}, freshness=${result.freshness_badge.freshness}` }],
                         structuredContent: { ...result, freshness_badge: result.freshness_badge },
                     }),
                 };
@@ -1174,7 +1174,7 @@ async function _executeMcpToolCallInner(payload) {
                 const result = await be.outline({ path: outlinePath, limit, cwd });
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `Code Map outline "${result.path}": ${result.symbols.length}/${result.symbol_count} symbol(s), index=${result.index_status}, freshness=${result.freshness_badge.status}` }],
+                        content: [{ type: 'text', text: `Code Map outline "${result.path}": ${result.symbols.length}/${result.symbol_count} symbol(s), index=${result.index_status}, freshness=${result.freshness_badge.freshness}` }],
                         structuredContent: { ...result, freshness_badge: result.freshness_badge },
                     }),
                 };
@@ -1188,7 +1188,7 @@ async function _executeMcpToolCallInner(payload) {
             const result = await be.brief({ target, limit, cwd });
             return {
                 response: toolResponse({
-                    content: [{ type: 'text', text: `Code Map brief "${result.target}": ${result.suggested_files_to_read.length} file(s) to read, freshness=${result.freshness_badge.status}` }],
+                    content: [{ type: 'text', text: `Code Map brief "${result.target}": ${result.suggested_files_to_read.length} file(s) to read, freshness=${result.freshness_badge.freshness}` }],
                     structuredContent: { ...result, freshness_badge: result.freshness_badge },
                 }),
             };

package/dist/commands/session-start.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
-import { memoryExists, resolveEntityDir } from '../core/io.js';
+import { isSessionSnapshotRecordFilename, memoryExists, resolveEntityDir, sessionSnapshotRecordPaths } from '../core/io.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from '../core/migration.js';
 import { buildOperationalIdentity, loadAllSessions, saveCurrentSession } from '../core/identity.js';
 import { requireMinimumTrustLevel, resolveCurrentModel, resolveOrAutoRegisterAgentIdentity } from '../core/agent-registry.js';
@@ -25,11 +25,55 @@ import { loadHygienePolicy } from '../core/hygiene-policy.js';
 import { maybeCreateCheckpoint } from '../core/events/checkpoint.js';
 import { pullSignalsFromLinkedProjects, markSignalProcessed } from '../core/federation-transport.js';
 import { materializeFederationSignal } from '../core/federation-materialize.js';
-function sessionsDir(cwd) {
-    return resolveEntityDir('sessions', cwd ?? process.cwd(), 'read');
+/**
+ * pln#670 — snapshot writes always target the canonical directory ('write' mode).
+ * The previous 'read'-mode resolution meant a fresh store (no coordination/sessions
+ * yet) landed the snapshot in the legacy dir — the current_session home — where
+ * saveCurrentSession then clobbered it (same `<session_id>.json` name, same id).
+ */
+function sessionSnapshotWriteDir(cwd) {
+    return resolveEntityDir('sessions', cwd ?? process.cwd(), 'write');
 }
 function sessionSnapshotPath(sessionId, cwd) {
-    return path.join(sessionsDir(cwd), `${sessionId}.json`);
+    return path.join(sessionSnapshotWriteDir(cwd), `${sessionId}.snapshot.json`);
+}
+/**
+ * pln#670 — lazy migration of pre-split snapshot records: rename `<id>.json` to
+ * `<id>.snapshot.json` in the CANONICAL sessions directory only. The legacy
+ * directory is never scanned — it is the current_session home. Only files that
+ * validate as session_snapshot are touched; anything else is left in place.
+ */
+export function migrateLegacySnapshotNames(cwd) {
+    const dir = sessionSnapshotWriteDir(cwd);
+    if (!fs.existsSync(dir))
+        return 0;
+    let renamed = 0;
+    for (const file of fs.readdirSync(dir)) {
+        // Case-insensitive suffix checks (codex review P1): Windows filesystems
+        // match names case-insensitively — an upper-cased `.SNAPSHOT.json` is the
+        // same record a lower-case probe reads, and must not be re-suffixed.
+        if (!file.toLowerCase().endsWith('.json') || isSessionSnapshotRecordFilename(file))
+            continue;
+        const from = path.join(dir, file);
+        try {
+            // Discriminate on the RAW file — the migration loader zod-strips unknown
+            // keys, so a current_session record parses as a clean snapshot after it.
+            // Key PRESENCE, not value type (codex review P1): the invariant is
+            // "never touch a record CARRYING last_seen_at", and `last_seen_at: null`
+            // must be rejected too.
+            const raw = JSON.parse(fs.readFileSync(from, 'utf-8'));
+            if (Object.hasOwn(raw, 'last_seen_at'))
+                continue;
+            SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', from).document);
+            const to = path.join(dir, `${file.slice(0, -'.json'.length)}.snapshot.json`);
+            if (!fs.existsSync(to)) {
+                fs.renameSync(from, to);
+                renamed++;
+            }
+        }
+        catch { /* not a session_snapshot — leave it alone */ }
+    }
+    return renamed;
 }
 export async function runSessionStart(options = {}) {
     try {
@@ -155,7 +199,7 @@ export async function startSession(options = {}) {
         ...(model ? { model } : {}),
     };
     // Persist snapshot
-    const dir = sessionsDir(options.cwd);
+    const dir = sessionSnapshotWriteDir(options.cwd);
     if (!fs.existsSync(dir))
         fs.mkdirSync(dir, { recursive: true });
     saveVersionedJsonFile('session_snapshot', sessionSnapshotPath(snapshot.session_id, options.cwd), SessionSnapshotSchema.parse(snapshot));
@@ -218,6 +262,14 @@ export async function startSession(options = {}) {
                 inventoryAdvisory = lines;
         }
         catch { /* non-fatal — inventory scan failure should not block session start */ }
+        // pln#670 — lazy rename of pre-split snapshot records to the type-suffixed
+        // name. Session-start full maintenance is the natural sweep point (no daemon,
+        // feedback_lazy_reconcile_pattern); dual-read keeps unrenamed records readable
+        // in the meantime.
+        try {
+            migrateLegacySnapshotNames(options.cwd);
+        }
+        catch { /* non-fatal — name migration must never block session start */ }
         // pln#564 step B — cap the runtime-note tree on session start (no LLM gate,
         // unlike the compaction-phase archiveSessionNotes). Keeps the newest N
         // session/lifecycle notes per agent + all genuine observations, parks the
@@ -367,14 +419,33 @@ function isPidAlive(pid) {
     }
 }
 export function loadSessionSnapshot(sessionId, cwd) {
-    const p = sessionSnapshotPath(sessionId, cwd);
-    if (!fs.existsSync(p))
-        return undefined;
-    try {
-        return SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', p).document);
-    }
-    catch {
-        return undefined;
+    // pln#670 — probe the type-suffixed name first, then the pre-split `<id>.json`
+    // layouts. SessionSnapshotSchema is non-strict, so a current_session record for
+    // the same id would parse too (zod strips unknown keys) — the negative
+    // discriminant is `last_seen_at`, which only current_session carries.
+    for (const p of sessionSnapshotRecordPaths(sessionId, cwd)) {
+        if (!fs.existsSync(p))
+            continue;
+        try {
+            // Discriminate on the RAW file: the migration loader zod-strips unknown
+            // keys, so a current_session record would come back looking like a clean
+            // snapshot. Key PRESENCE, not value type (codex review P1) — a record
+            // carrying `last_seen_at: null` must be rejected too.
+            const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+            if (Object.hasOwn(raw, 'last_seen_at'))
+                continue;
+            const snapshot = SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', p).document);
+            // The filename is not a type-safe identity boundary by itself (codex
+            // review): querying `sess_x.snapshot` also constructs `sess_x.snapshot.json`
+            // — the snapshot of sess_x. Only return a payload that names the caller's id.
+            if (snapshot.session_id !== sessionId)
+                continue;
+            return snapshot;
+        }
+        catch {
+            continue;
+        }
     }
+    return undefined;
 }
 //# sourceMappingURL=session-start.js.map

package/dist/core/bootstrap.js

@@ -9,6 +9,7 @@ import { mutate } from './mutation-pipeline.js';
 import { BootstrapApplicationReceiptSchema, BootstrapInterviewAnswerSchema, BootstrapInterviewPlanSchema, BootstrapInterviewQuestionSchema, BootstrapImportPlanDocumentSchema, BootstrapProfileDocumentSchema, BootstrapSuggestionDocumentSchema, MemorySeedDocumentSchema, } from './schema.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { analyzeRepository, findNestedAgentsFiles } from './repo-analysis.js';
+import { isManagedByBrainclaw } from './project-discovery.js';
 import { buildExecutionContext, compactExecutionContext } from './execution-context.js';
 import { buildAgentToolingContext } from './agent-context.js';
 import { createInstruction, loadInstructions, saveInstruction } from './instructions.js';
@@ -256,15 +257,38 @@ function buildBootstrapArtifacts(input) {
         sourcesScanned.push('README');
         seeds.push(...extractReadmeSeeds(readmePath, input.target));
     }
+    // pln#671 — instruction files generated by `brainclaw export` derive FROM
+    // brainclaw memory: deriving seeds from them feeds the store its own output
+    // back as "new" knowledge. Seed extraction skips managed files; DETECTION
+    // (agentsPresent, native_instruction_files, source fingerprint) stays
+    // complete — that is environment inventory, not knowledge to import. The
+    // skip is traced in sources_scanned so the exclusion is never silent.
     const agentsPath = path.join(scanRoot, 'AGENTS.md');
     const agentsPresent = fs.existsSync(agentsPath);
     if (agentsPresent) {
-        sourcesScanned.push('AGENTS.md');
-        seeds.push(...extractAgentsSeeds(agentsPath, input.target));
+        if (isManagedByBrainclaw(agentsPath)) {
+            sourcesScanned.push('AGENTS.md (brainclaw-managed — skipped)');
+        }
+        else {
+            sourcesScanned.push('AGENTS.md');
+            seeds.push(...extractAgentsSeeds(agentsPath, input.target));
+        }
     }
     if (nativeInstructionFiles.length > 0) {
-        sourcesScanned.push('native_instructions');
-        seeds.push(...extractNativeInstructionSeeds(nativeInstructionFiles.map((relativePath) => path.join(scanRoot, relativePath)), scanRoot, input.target));
+        // AGENTS.md is handled by its own extractor above — keep it out of the
+        // native accounting so a managed AGENTS.md is not counted as skipped twice.
+        const nativeCandidates = nativeInstructionFiles
+            .filter((relativePath) => path.basename(relativePath) !== 'AGENTS.md');
+        const humanAuthored = nativeCandidates
+            .filter((relativePath) => !isManagedByBrainclaw(path.join(scanRoot, relativePath)));
+        const skippedManaged = nativeCandidates.length - humanAuthored.length;
+        if (humanAuthored.length > 0) {
+            sourcesScanned.push('native_instructions');
+            seeds.push(...extractNativeInstructionSeeds(humanAuthored.map((relativePath) => path.join(scanRoot, relativePath)), scanRoot, input.target));
+        }
+        if (skippedManaged > 0) {
+            sourcesScanned.push(`native_instructions (${skippedManaged} brainclaw-managed — skipped)`);
+        }
     }
     const manifestResult = extractManifestSeeds(scanRoot, input.target);
     if (manifestResult.seeds.length > 0) {

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

@@ -26,7 +26,7 @@ import path from 'node:path';
 import { loadConfig } from '../config.js';
 import { listNestedProjects } from './cascade.js';
 import { readManifest, readImportsIndex } from './store.js';
-import { coarseFreshness, applyGitHeadDrift } from './freshness.js';
+import { makeFreshnessBadge, applyGitHeadDrift } from './freshness.js';
 import { findInStore, briefInStore, makeLazyChecker, newAccumulator, deriveBadge, reserveSourceSlots, attachRelatedMemory, attachMemoryIds, validateStoreEntry, BRIEF_FILE_CAP, LAZY_BUDGET, } from './query.js';
 /** Same default cap as the single-store find (query.ts DEFAULT_FIND_LIMIT). */
 const DEFAULT_FIND_LIMIT = 20;
@@ -191,22 +191,11 @@ function statusRank(s) {
 function mergeBadges(perStore) {
     const total = perStore.length;
     const indexed = perStore.filter((p) => p.hasIndex);
-    const unindexed = perStore
-        .filter((p) => !p.hasIndex)
-        .map((p) => p.ref.relPath || '.')
-        .sort();
+    const unindexed = perStore.filter((p) => !p.hasIndex).map((p) => p.ref.relPath || '.').sort();
     if (indexed.length === 0) {
-        return {
-            status: 'missing_index',
-            coarse: 'missing',
-            details: {
-                traversal: 'workspace',
-                projects_indexed: 0,
-                projects_total: total,
-                unindexed_projects: unindexed,
-                hint: 'run refresh --cascade',
-            },
-        };
+        return makeFreshnessBadge('missing_index', {
+            extra: { traversal: 'workspace', projects_indexed: 0, projects_total: total, unindexed_projects: unindexed, hint: 'run refresh --cascade' },
+        });
     }
     let worst = indexed[0].badge.status;
     for (const p of indexed) {
@@ -221,12 +210,11 @@ function mergeBadges(perStore) {
     };
     if (unindexed.length)
         details.unindexed_projects = unindexed;
-    // Merge the per-store detail path-sets, prefixing each with its store's
-    // workspace-relative dir so a bare `src/index.ts` isn't ambiguous across packages.
     const prefixMerge = (key) => {
         const out = [];
         for (const p of indexed) {
-            const arr = p.badge.details?.[key];
+            const spot = p.badge.details.spot_check;
+            const arr = spot?.[key];
             if (Array.isArray(arr)) {
                 for (const f of arr)
                     out.push(p.ref.relPath ? `${p.ref.relPath}/${String(f)}` : String(f));
@@ -234,16 +222,25 @@ function mergeBadges(perStore) {
         }
         return out.sort();
     };
-    for (const key of ['stale_changed_files', 'deleted_files', 'unchecked_files']) {
-        const merged = prefixMerge(key);
-        if (merged.length)
-            details[key] = merged;
-    }
-    const partialStore = indexed.find((p) => p.badge.status === 'partial');
-    if (partialStore) {
-        details.partial_reason = partialStore.badge.details?.partial_reason ?? 'lazy_check_budget_exhausted';
-    }
-    return { status: worst, coarse: coarseFreshness(worst), details };
+    const spotChecks = indexed.map((p) => p.badge.details.spot_check);
+    const spotStatus = spotChecks.some((spot) => spot?.status === 'partial')
+        ? 'partial'
+        : spotChecks.some((spot) => spot?.status === 'stale')
+            ? 'stale'
+            : spotChecks.some((spot) => spot?.status === 'fresh') ? 'fresh' : 'not_run';
+    const partialSpot = spotChecks.find((spot) => spot?.status === 'partial');
+    return makeFreshnessBadge(worst, {
+        spotCheck: {
+            status: spotStatus,
+            checked_files: spotChecks.reduce((sum, spot) => sum + (spot?.checked_files ?? 0), 0),
+            stale_changed_files: prefixMerge('stale_changed_files'),
+            deleted_files: prefixMerge('deleted_files'),
+            unchecked_files: prefixMerge('unchecked_files'),
+            budget_exhausted: spotChecks.some((spot) => spot?.budget_exhausted === true),
+            partial_reason: partialSpot?.partial_reason ?? null,
+        },
+        extra: details,
+    });
 }
 /**
  * Aggregated find across a resolved multi-project workspace. Shares ONE lazy budget
@@ -426,9 +423,15 @@ export function aggregateBrief(target, limit, resolved, currentHead, memoryReade
     const seen = new Set();
     const mergedDefiningPaths = new Set();
     const symbolNames = new Set();
+    const memorySymbolNames = new Set();
+    const memoryImportNames = new Set();
     for (const p of contributing) {
         for (const e of p.r.defining)
             symbolNames.add(e.name);
+        for (const name of p.r.memorySymbolNames)
+            memorySymbolNames.add(name);
+        for (const name of p.r.memoryImportNames)
+            memoryImportNames.add(name);
         for (const dp of p.r.definingPaths)
             mergedDefiningPaths.add(p.ref.relPath ? `${p.ref.relPath}/${dp}` : dp);
         for (const rf of p.r.confident) {
@@ -460,8 +463,10 @@ export function aggregateBrief(target, limit, resolved, currentHead, memoryReade
     const capped = reserveSourceSlots(merged, cap, mergedDefiningPaths);
     if (symbolNames.size === 0)
         symbolNames.add(target);
-    const related = attachRelatedMemory(memoryReader({ cwd: resolved.root }), capped.map((f) => f.path), [...symbolNames]);
-    const baseEntries = attachMemoryIds(capped, related);
+    if (memorySymbolNames.size === 0)
+        memorySymbolNames.add(target);
+    const related = attachRelatedMemory(memoryReader({ cwd: resolved.root }), capped.map((f) => f.path), [...memorySymbolNames], [...memoryImportNames]);
+    const baseEntries = attachMemoryIds(capped, related, mergedDefiningPaths);
     const suggested = baseEntries.map((s, i) => ({
         ...s,
         project: capped[i].project,

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

@@ -12,7 +12,7 @@ import { execFileSync } from 'node:child_process';
 import path from 'node:path';
 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';
@@ -32,9 +32,9 @@ 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.

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

@@ -3,7 +3,7 @@
  * model; it never takes a second, potentially different graph traversal.
  */
 import path from 'node:path';
-import { withCoarse } from './freshness.js';
+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;
@@ -113,12 +113,12 @@ export function exportSubgraph(targetInput, options, ctx) {
         min_confidence: clampConfidence(options?.minConfidence),
     };
     const manifest = readManifest(ctx.cwd, ctx.preferredDirName);
-    const missing = withCoarse({ status: 'missing_index', details: { hint: 'run refresh' } });
+    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, withCoarse({
+        return emptyOutput(target, targetKind, limits, withFreshness({
             status: manifest.freshness.status, details: { invalid_target: 'file path must be inside the indexed project' },
         }), format);
     }
@@ -187,7 +187,7 @@ export function exportSubgraph(targetInput, options, ctx) {
         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: withCoarse({ status: manifest.freshness.status,
+        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 };

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

@@ -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) {
@@ -165,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