brainclaw 1.25.0 → 1.26.1

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

@@ -26,6 +26,12 @@ function coercePaths(raw) {
         return raw.filter((p) => typeof p === 'string');
     return [];
 }
+function optionalString(raw) {
+    return typeof raw === 'string' ? raw : undefined;
+}
+function optionalCount(raw) {
+    return typeof raw === 'number' && Number.isFinite(raw) ? raw : undefined;
+}
 function toRelatedMemoryItem(kind, item) {
     return {
         id: typeof item.id === 'string' ? item.id : '',
@@ -33,6 +39,15 @@ function toRelatedMemoryItem(kind, item) {
         text: typeof item.text === 'string' ? item.text : '',
         tags: coerceTags(item.tags),
         related_paths: coercePaths(item.related_paths),
+        created_at: optionalString(item.created_at),
+        last_confirmed_at: optionalString(item.last_confirmed_at),
+        last_infirmed_at: optionalString(item.last_infirmed_at),
+        confirmation_count: optionalCount(item.confirmation_count),
+        infirmation_count: optionalCount(item.infirmation_count),
+        saved_me_count: optionalCount(item.saved_me_count),
+        misled_me_count: optionalCount(item.misled_me_count),
+        verified_at: optionalString(item.verified_at),
+        verify_cmd: optionalString(item.verify_cmd),
     };
 }
 /**

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

@@ -11,8 +11,9 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { getLifecycleStats } from '../memory-lifecycle.js';
 import { hashContent } from './extractor.js';
-import { coarseFreshness } from './freshness.js';
+import { makeFreshnessBadge } from './freshness.js';
 import { readImportsIndex, readManifest, readResolutionIndex, readShard, readSymbolsIndex, } from './store.js';
 // --- lazy read-path freshness budget (spec §6.1) ---
 /** Default per-query lazy-check budget (spec §6.1). */
@@ -50,6 +51,7 @@ function budgetExhausted(checker) {
 }
 export function newAccumulator() {
     return {
+        checkedPaths: new Set(),
         staleChangedPaths: new Set(),
         missingPaths: new Set(),
         uncheckedPaths: new Set(),
@@ -76,6 +78,7 @@ function validateEntry(entry, checker, acc, projectRoot, maxParseFileBytes, cwd,
     if (cached !== undefined)
         return cached;
     const abs = path.join(projectRoot, entry.path);
+    acc.checkedPaths.add(entry.path);
     let stat;
     try {
         stat = fs.statSync(abs);
@@ -151,46 +154,26 @@ export function validateStoreEntry(entry, checker, acc, cwd, preferredDirName) {
  * change/deletion yields `stale_changed_files`; else the manifest base status.
  */
 export function deriveBadge(base, acc, budgetExhausted, hadConfidentMatch, emptyIndex) {
-    const details = {};
-    if (acc.staleChangedPaths.size > 0) {
-        details.stale_changed_files = [...acc.staleChangedPaths].sort();
-    }
-    if (acc.missingPaths.size > 0) {
-        details.deleted_files = [...acc.missingPaths].sort();
-    }
-    if (acc.uncheckedPaths.size > 0) {
-        details.unchecked_files = [...acc.uncheckedPaths].sort();
-    }
-    let status = base;
-    if (emptyIndex && base !== 'missing_index') {
-        // §6.1 — zero confident matches: hint refresh rather than imply absence.
-        details.hint = 'missing_index_or_refresh';
-    }
-    if (acc.staleChangedPaths.size > 0 || acc.missingPaths.size > 0) {
-        status = 'stale_changed_files';
-    }
-    // §6.1.6 — `partial` means the lazy-check budget (file count / wall clock) ran
-    // out before we could validate everything. Reserve it for that cause only:
-    // unchecked-for-other-reasons (oversized file per §6.1.4, missing shard,
-    // unreadable file) must NOT be mislabeled as budget exhaustion. When the budget
-    // truly ran out, `partial` wins the top-line status — the agent should refresh
-    // before trusting the result — and the confirmed-stale list still rides along
-    // in `details.stale_changed_files`.
-    if (budgetExhausted || acc.budgetSkippedPaths.size > 0) {
-        status = 'partial';
-        details.partial_reason = 'lazy_check_budget_exhausted';
-        details.budget = { ...LAZY_BUDGET };
-    }
-    // pln#593 #2 — distinguish INDEX freshness (manifest state) from THIS call's
-    // read-path spot-check. When the call-level status diverges from the index
-    // status (a budget-limited `partial`, or a per-file `stale_changed_files` over a
-    // `fresh` index), surface the index status so an agent does not read
-    // status()=fresh vs find()/brief()=partial as a contradiction: it's "index
-    // <index_status>, this call's spot-check <status>".
-    if (status !== base)
-        details.index_status = base;
+    const hasStale = acc.staleChangedPaths.size > 0 || acc.missingPaths.size > 0;
+    const partial = budgetExhausted || acc.budgetSkippedPaths.size > 0;
+    const spotStatus = partial ? 'partial' : hasStale ? 'stale' : acc.checkedPaths.size > 0 ? 'fresh' : 'not_run';
+    const hint = emptyIndex && base !== 'missing_index' ? 'missing_index_or_refresh' : undefined;
     void hadConfidentMatch;
-    return { status, coarse: coarseFreshness(status), details };
+    // `base` stays the top-level index classification. A stale or budget-limited
+    // candidate spot-check is honest evidence, but it must not turn find()/brief()
+    // into a different badge than status()/work() for the same index state.
+    return makeFreshnessBadge(base, {
+        spotCheck: {
+            status: spotStatus,
+            checked_files: acc.checkedPaths.size,
+            stale_changed_files: [...acc.staleChangedPaths].sort(),
+            deleted_files: [...acc.missingPaths].sort(),
+            unchecked_files: [...acc.uncheckedPaths].sort(),
+            budget_exhausted: partial,
+            partial_reason: partial ? 'lazy_check_budget_exhausted' : null,
+        },
+        extra: hint ? { hint } : undefined,
+    });
 }
 const DEFAULT_FIND_LIMIT = 20;
 /** Lowercase token normalization mirroring indexes.ts (spec §5.6 keys). */
@@ -411,7 +394,7 @@ export function find(query, limit, ctx) {
         return {
             query,
             matches: [],
-            freshness_badge: { status: 'missing_index', coarse: 'missing', details: { hint: 'run refresh' } },
+            freshness_badge: makeFreshnessBadge('missing_index', { extra: { hint: 'run refresh' } }),
         };
     }
     const capped = r.matches.slice(0, limit ?? DEFAULT_FIND_LIMIT);
@@ -420,43 +403,178 @@ export function find(query, limit, ctx) {
 }
 /** spec §11 — cap related memory at top 5 by relevance. */
 export const RELATED_MEMORY_CAP = 5;
+const MEMORY_JOIN_MIN_IDENTIFIER_LENGTH = 4;
+const MEMORY_JOIN_STOP_WORDS = new Set([
+    'default', 'module', 'index', 'main', 'test', 'tests', 'spec', 'react', 'node',
+]);
+function stableNames(names) {
+    const byNormalized = new Map();
+    for (const raw of names) {
+        const name = raw.trim();
+        const normalized = normIdent(name);
+        if (!normalized || byNormalized.has(normalized))
+            continue;
+        byNormalized.set(normalized, name);
+    }
+    return [...byNormalized.values()].sort((a, b) => a.localeCompare(b));
+}
+/** Avoid joining a prose memory to generic import noise such as `default` or `React`. */
+function memoryJoinTerms(names) {
+    return stableNames(names).filter((name) => {
+        const normalized = normIdent(name);
+        return normalized.length >= MEMORY_JOIN_MIN_IDENTIFIER_LENGTH
+            && !MEMORY_JOIN_STOP_WORDS.has(normalized)
+            && !isTestHelperSymbol(name);
+    });
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Identifier-aware, case-insensitive text match. The surrounding guards keep
+ * `Auth` from matching `author`, while still matching `ENTITY_REGISTRY` in a
+ * prose trap written as `entity_registry`.
+ */
+function textMentionsIdentifier(text, identifier) {
+    const escaped = escapeRegExp(identifier);
+    return new RegExp(`(^|[^A-Za-z0-9_$])${escaped}(?=$|[^A-Za-z0-9_$])`, 'i').test(text);
+}
+function isLifecycleMemoryKind(kind) {
+    return kind === 'decision' || kind === 'constraint' || kind === 'trap';
+}
+function validDate(value) {
+    if (!value)
+        return null;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Make memory age explicit on the brief response. `verify_cmd` marks a
+ * perishable fact, so its empirical verification wins over the gentler
+ * lifecycle curve: missing verification is `unverified`, and one older than
+ * 30 days is `stale` (the same threshold used by memory anti-staleness).
+ */
+function describeMemoryFreshness(item) {
+    const verifiedAt = item.verified_at ?? null;
+    const verificationMs = validDate(item.verified_at);
+    const nowMs = Date.now();
+    if (item.verify_cmd) {
+        if (verificationMs === null) {
+            return { status: 'unverified', as_of: item.created_at ?? null, age_days: null, verified_at: verifiedAt };
+        }
+        const ageDays = Math.max(0, Math.floor((nowMs - verificationMs) / 86_400_000));
+        if (ageDays > 30)
+            return { status: 'stale', as_of: item.verified_at, age_days: ageDays, verified_at: verifiedAt };
+    }
+    if (!isLifecycleMemoryKind(item.kind) || validDate(item.created_at) === null) {
+        return { status: 'unknown', as_of: item.created_at ?? null, age_days: null, verified_at: verifiedAt };
+    }
+    const stats = getLifecycleStats({
+        entity: item.kind,
+        created_at: item.created_at,
+        last_confirmed_at: item.last_confirmed_at,
+        last_infirmed_at: item.last_infirmed_at,
+        confirmation_count: item.confirmation_count,
+        infirmation_count: item.infirmation_count,
+        saved_me_count: item.saved_me_count,
+        misled_me_count: item.misled_me_count,
+        nowMs,
+    });
+    return {
+        status: stats.classification,
+        as_of: stats.anchor_at,
+        age_days: stats.age_days,
+        verified_at: verifiedAt,
+    };
+}
 /**
  * Match memory items to a set of candidate file paths + the query symbol name
  * by (spec §11): related_paths, tags, or a literal file-path mention in the
  * memory text. Returns the top `RELATED_MEMORY_CAP` by relevance.
  */
-export function attachRelatedMemory(items, paths, symbolNames) {
+export function attachRelatedMemory(items, paths, symbolNames, importNames = []) {
     const pathSet = new Set(paths.map((p) => p.replace(/\\/g, '/')));
     const baseNames = new Set(paths.map((p) => path.basename(p)));
     const symLower = new Set(symbolNames.map((s) => s.toLowerCase()));
+    const symbolTerms = memoryJoinTerms(symbolNames);
+    const importTerms = memoryJoinTerms(importNames);
     const scored = [];
     for (const item of items) {
         let score = 0;
+        const sources = new Set();
         // related_paths — strongest signal.
         for (const rp of item.related_paths ?? []) {
             const norm = rp.replace(/\\/g, '/');
-            if (pathSet.has(norm))
+            if (pathSet.has(norm)) {
                 score += 5;
-            else if (baseNames.has(path.basename(norm)))
+                sources.add('related_path');
+            }
+            else if (baseNames.has(path.basename(norm))) {
                 score += 3;
+                sources.add('related_path_basename');
+            }
         }
         // literal file-path mention in the memory text.
         const text = item.text ?? '';
         for (const p of pathSet) {
-            if (text.includes(p))
+            if (text.includes(p)) {
                 score += 2;
+                sources.add('path_mention');
+            }
         }
         for (const bn of baseNames) {
-            if (text.includes(bn))
+            if (text.includes(bn)) {
                 score += 1;
+                sources.add('path_basename_mention');
+            }
         }
         // tags matching a symbol name (e.g. tag "App" / "useAuth").
         for (const tag of item.tags ?? []) {
-            if (symLower.has(tag.toLowerCase()))
+            if (symLower.has(tag.toLowerCase())) {
                 score += 2;
+                sources.add('symbol_tag');
+            }
+        }
+        // pln#601 amendment — response-local join from MEMORY TEXT to the names
+        // defined/imported by the brief target. We only admit identifier-shaped,
+        // non-test-helper terms and retain the exact terms as inspectable evidence.
+        const matchedSymbols = symbolTerms.filter((term) => textMentionsIdentifier(text, term));
+        const matchedImports = importTerms.filter((term) => textMentionsIdentifier(text, term));
+        if (matchedSymbols.length > 0) {
+            score += 4 * matchedSymbols.length;
+            sources.add('symbol_text');
+        }
+        if (matchedImports.length > 0) {
+            score += 3 * matchedImports.length;
+            sources.add('import_text');
+        }
+        if (score > 0) {
+            let confidence = 0.6;
+            if (sources.has('related_path'))
+                confidence = 1;
+            else if (sources.has('path_mention'))
+                confidence = 0.95;
+            else if (sources.has('related_path_basename'))
+                confidence = 0.85;
+            else if (sources.has('symbol_text'))
+                confidence = 0.82;
+            else if (sources.has('import_text'))
+                confidence = 0.72;
+            else if (sources.has('symbol_tag'))
+                confidence = 0.65;
+            const evidence = {
+                sources: [...sources].sort(),
+                matched_symbols: matchedSymbols,
+                matched_imports: matchedImports,
+                confidence,
+            };
+            // Clone: these response annotations must never mutate the records returned
+            // by the memory reader or be persisted into Code Map shards.
+            scored.push({
+                item: { ...item, match_evidence: evidence, memory_freshness: describeMemoryFreshness(item) },
+                score,
+            });
         }
-        if (score > 0)
-            scored.push({ item, score });
     }
     scored.sort((a, b) => b.score - a.score || a.item.id.localeCompare(b.item.id));
     return scored.slice(0, RELATED_MEMORY_CAP).map((s) => s.item);
@@ -649,6 +767,24 @@ function reverseDeps(resolutionIndex, definingPaths, definingByNodeId) {
     }
     return [...byPath.values()];
 }
+function targetMemoryTerms(definingPaths, definingFileIds, nodeIndex, cwd, preferredDirName) {
+    const symbols = [...nodeIndex.values()]
+        .filter((entry) => definingPaths.has(entry.path))
+        .map((entry) => entry.name);
+    const imports = new Set();
+    for (const fileId of new Set(definingFileIds)) {
+        const shard = readShard(fileId, cwd, preferredDirName);
+        if (!shard)
+            continue;
+        for (const node of shard.nodes) {
+            if (node.kind !== 'module')
+                continue;
+            for (const imported of node.imported_names)
+                imports.add(imported);
+        }
+    }
+    return { symbolNames: stableNames(symbols), importNames: stableNames([...imports]) };
+}
 /**
  * Heuristic: does the brief target denote a file PATH rather than a bare symbol
  * name? A path separator or a supported source extension marks a path target —
@@ -694,6 +830,8 @@ export function briefInStore(target, ctx, checker, acc) {
         return {
             defining: [],
             definingPaths: new Set(),
+            memorySymbolNames: [],
+            memoryImportNames: [],
             matchKind: 'none',
             confident: [],
             base: 'missing_index',
@@ -749,6 +887,7 @@ export function briefInStore(target, ctx, checker, acc) {
             confidentDefiningFileIds.set(e.path, e.file_id);
     }
     const nodeIndex = buildNodeIdIndex(symbolsIndex);
+    const memoryTerms = targetMemoryTerms(definingPaths, defining.map((entry) => entry.file_id), nodeIndex, ctx.cwd, ctx.preferredDirName);
     const fwd = forwardDeps(confidentDefiningFileIds, nodeIndex, ctx.cwd, ctx.preferredDirName);
     const rev = reverseDeps(resolutionIndex, definingPaths, definingByNodeId);
     const ranked = rankFiles(defining, fwd, rev, symbolsIndex, importsIndex, target);
@@ -763,13 +902,25 @@ export function briefInStore(target, ctx, checker, acc) {
             continue;
         confident.push(rf);
     }
-    return { defining, definingPaths, matchKind, confident, base, hasIndex: true, emptyRanked: ranked.length === 0, acc };
+    return {
+        defining,
+        definingPaths,
+        memorySymbolNames: memoryTerms.symbolNames,
+        memoryImportNames: memoryTerms.importNames,
+        matchKind,
+        confident,
+        base,
+        hasIndex: true,
+        emptyRanked: ranked.length === 0,
+        acc,
+    };
 }
 /**
  * Attach related-memory ids per reading-list entry (spec §11). Shared by the
  * single-store brief() and the workspace aggregation so both surface memory identically.
  */
-export function attachMemoryIds(capped, related) {
+export function attachMemoryIds(capped, related, targetPaths = new Set()) {
+    const normalizedTargetPaths = new Set([...targetPaths].map((p) => p.replace(/\\/g, '/')));
     return capped.map((f) => {
         const ids = related
             .filter((m) => {
@@ -777,7 +928,9 @@ export function attachMemoryIds(capped, related) {
             const base2 = path.basename(fileNorm);
             const inPaths = (m.related_paths ?? []).some((rp) => rp.replace(/\\/g, '/') === fileNorm || path.basename(rp) === base2);
             const inText = (m.text ?? '').includes(fileNorm) || (m.text ?? '').includes(base2);
-            return inPaths || inText;
+            const symbolTextMatch = (m.match_evidence?.matched_symbols.length ?? 0) > 0
+                || (m.match_evidence?.matched_imports.length ?? 0) > 0;
+            return inPaths || inText || (normalizedTargetPaths.has(fileNorm) && symbolTextMatch);
         })
             .map((m) => m.id);
         return { path: f.path, reason: f.reason, score: f.score, related_memory_ids: ids };
@@ -792,7 +945,7 @@ export function brief(target, limit, ctx, memoryReader) {
             target,
             suggested_files_to_read: [],
             related_memory: [],
-            freshness_badge: { status: 'missing_index', coarse: 'missing', details: { hint: 'run refresh' } },
+            freshness_badge: makeFreshnessBadge('missing_index', { extra: { hint: 'run refresh' } }),
         };
     }
     const cap = Math.min(limit ?? BRIEF_FILE_CAP, BRIEF_FILE_CAP);
@@ -800,11 +953,9 @@ export function brief(target, limit, ctx, memoryReader) {
     const capped = reserveSourceSlots(r.confident, cap, r.definingPaths);
     // Related memory (spec §11): match by the candidate paths + symbol names.
     const candidatePaths = capped.map((f) => f.path);
-    const symbolNames = [...new Set(r.defining.map((e) => e.name))];
-    if (symbolNames.length === 0)
-        symbolNames.push(target);
-    const related = attachRelatedMemory(memoryReader(ctx), candidatePaths, symbolNames);
-    const suggested = attachMemoryIds(capped, related);
+    const symbolNames = r.memorySymbolNames.length > 0 ? r.memorySymbolNames : [target];
+    const related = attachRelatedMemory(memoryReader(ctx), candidatePaths, symbolNames, r.memoryImportNames);
+    const suggested = attachMemoryIds(capped, related, r.definingPaths);
     const badge = deriveBadge(r.base, acc, checker.exhausted, capped.length > 0, r.emptyRanked);
     return { target, suggested_files_to_read: suggested, related_memory: related, freshness_badge: badge };
 }

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

@@ -55,7 +55,7 @@ function edgesArrayEqual(a, b) {
     for (let i = 0; i < a.length; i++) {
         const x = a[i];
         const y = b[i];
-        if (x.id !== y.id || x.from !== y.from || x.to !== y.to || x.kind !== y.kind || x.confidence !== y.confidence) {
+        if (x.id !== y.id || x.from !== y.from || x.to !== y.to || x.kind !== y.kind || x.confidence !== y.confidence || x.origin !== y.origin) {
             return false;
         }
     }
@@ -101,9 +101,12 @@ export async function resolveProjectImports(input) {
         const provider = registry.providerForLang(shard.lang);
         // Non-pass-owned edges are preserved byte-identical (same order). Filtering BOTH
         // pass-owned kinds also strips any stale A/B edge from a prior run (idempotency).
-        const kept = shard.edges.filter((e) => !PASS_OWNED_EDGE_KINDS.has(e.kind));
+        const kept = shard.edges.filter((e) => !PASS_OWNED_EDGE_KINDS.has(e.kind) && e.origin !== 'usage_import');
         // Fresh pass-owned set (A resolves_to + B imports_symbol). Empty when no resolver.
         const fresh = [];
+        const seen = new Set();
+        // module + imported-name → unique target proven by imports_symbol below.
+        const resolvedImportedBindings = new Map();
         let freshSymbolCount = 0;
         if (provider?.resolveImport) {
             const seen = new Set();
@@ -149,11 +152,33 @@ export async function resolveProjectImports(input) {
                             continue; // dedup (duplicate names / re-imports)
                         seen.add(symId);
                         fresh.push({ id: symId, from: mod.id, to: target.id, kind: 'imports_symbol', confidence, source });
+                        resolvedImportedBindings.set(`${r.source}\0${name}`, target);
                         freshSymbolCount++;
                     }
                 }
             }
         }
+        // P4 imported-binding usages are emitted only after the exact `imports_symbol`
+        // proof above. If a module is unresolved, ambiguous, wildcard/default, or its
+        // target no longer exports the symbol, no call/reference edge survives.
+        for (const candidate of shard.reference_candidates ?? []) {
+            const target = resolvedImportedBindings.get(`${candidate.module}\0${candidate.imported_name}`);
+            if (!target)
+                continue;
+            const id = edgeId({ projectId, from: candidate.from, to: target.id, kind: candidate.kind });
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            fresh.push({
+                id,
+                from: candidate.from,
+                to: target.id,
+                kind: candidate.kind,
+                confidence: Math.min(clampConfidence(candidate.confidence), 1.0),
+                source: candidate.source,
+                origin: 'usage_import',
+            });
+        }
         // Single deterministic order over A+B so re-runs are byte-identical (from, to, kind).
         fresh.sort((a, b) => {
             if (a.from !== b.from)

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

@@ -193,6 +193,7 @@ export function readResolutionIndex(cwd, preferredDirName) {
     // 'toString' (a path or node id) can't resolve to an inherited prototype member.
     parsed.data.dependents_by_file = Object.assign(Object.create(null), parsed.data.dependents_by_file);
     parsed.data.dependents_by_symbol = Object.assign(Object.create(null), parsed.data.dependents_by_symbol);
+    parsed.data.usages_by_symbol = Object.assign(Object.create(null), parsed.data.usages_by_symbol);
     return parsed.data;
 }
 export function writeResolutionIndex(index, cwd, preferredDirName) {

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

@@ -110,6 +110,30 @@ export const EdgeSchema = z.object({
     })
         .nullable()
         .optional(),
+    /**
+     * Optional provenance for P4 usage edges. It lets the project resolver replace
+     * only import-derived usages on a later refresh without deleting lexical calls
+     * already proven inside the source file.
+     */
+    origin: z.enum(['usage_local', 'usage_import', 'usage_textual']).optional(),
+});
+/** P4's three deliberately non-interchangeable usage classifications. */
+export const UsageKindSchema = z.enum(['calls', 'references', 'possible_textual_match']);
+/**
+ * An import-binding usage that is lexical in one file but needs the project-wide
+ * import pass before its target symbol is known. This is persisted on the shard,
+ * never surfaced as a `calls`/`references` edge until that target is unique.
+ */
+export const ReferenceCandidateSchema = z.object({
+    from: z.string(),
+    kind: z.enum(['calls', 'references']),
+    module: z.string(),
+    imported_name: z.string(),
+    confidence: z.number().default(1.0),
+    source: z.object({
+        path: z.string(),
+        line: z.number().int().nullable().optional(),
+    }),
 });
 // --- Per-file shard (spec §5.3) ---
 export const ShardFreshnessSchema = z.object({
@@ -136,6 +160,8 @@ export const FileShardSchema = z.object({
     freshness: ShardFreshnessSchema,
     nodes: z.array(NodeSchema).default([]),
     edges: z.array(EdgeSchema).default([]),
+    /** Deferred P4 imported-binding usages; resolved by the whole-project pass. */
+    reference_candidates: z.array(ReferenceCandidateSchema).optional(),
     diagnostics: z.array(z.unknown()).default([]),
 });
 // --- manifest.json (spec §5.1) ---
@@ -282,6 +308,19 @@ export const DependencyIndexEntrySchema = z.object({
  * read-path scan of every shard. Forward deps are read straight from a target's own
  * shard, so they need no index.
  */
+/** A persisted, high-confidence P4 usage cause targeting one symbol. */
+export const UsageReasonSchema = z.object({
+    kind: z.enum(['calls', 'references']),
+    caller_node_id: z.string(),
+    confidence: z.number(),
+    source_line: z.number().int().nullable().optional(),
+});
+/** One importing file's lexical uses of a target symbol. */
+export const UsageIndexEntrySchema = z.object({
+    path: z.string(),
+    file_id: Sha256Hash,
+    reasons: z.array(UsageReasonSchema).default([]),
+});
 export const ResolutionIndexSchema = z.object({
     schema_version: z.number().int().default(CODE_MAP_SCHEMA_VERSION),
     project_id: z.string(),
@@ -290,6 +329,8 @@ export const ResolutionIndexSchema = z.object({
     dependents_by_file: z.record(z.string(), z.array(DependencyIndexEntrySchema)).default({}),
     /** Keys are TARGET symbol node ids (reverse `imports_symbol`). */
     dependents_by_symbol: z.record(z.string(), z.array(DependencyIndexEntrySchema)).default({}),
+    /** Keys are TARGET symbol ids; only proven P4 call/reference usages are indexed. */
+    usages_by_symbol: z.record(z.string(), z.array(UsageIndexEntrySchema)).default({}),
 });
 // --- .lock (spec §5.8) ---
 export const CodeLockSchema = z.object({
@@ -307,20 +348,25 @@ export const CodeLockSchema = z.object({
     stale_after_ms: z.number().int(),
 });
 /**
- * spec §9 (pln#601) — the COARSE, surface-uniform rollup of the detailed 7-value
- * {@link FreshnessStatus}. find/brief/status/work each expose their own precise
- * status, but an agent wants one consistent top-line signal to decide "trust this
- * or refresh first" without memorizing which `stale_*` variant applies. `coarse`
- * collapses the detail: every `stale_*` → `stale`, `missing_index` → `missing`,
- * `partial`/`fresh` unchanged. Derived (never independently authored) via
- * `coarseFreshness()` so it can never contradict `status`.
+ * The one agent-facing freshness signal. Detailed index causes and per-call
+ * spot-check observations intentionally live under `FreshnessBadge.details`.
  */
 export const CoarseFreshnessSchema = z.enum(['fresh', 'stale', 'partial', 'missing']);
 /** Freshness badge attached to every agent-facing read response (spec §9). */
 export const FreshnessBadgeSchema = z.object({
+    /**
+     * Stable top-line signal shared by work/status/find/brief. It MUST NOT be
+     * changed by a query's bounded spot-check: that observation belongs in
+     * `details.spot_check`, so an agent never sees incompatible badges for the
+     * same index state.
+     */
+    freshness: CoarseFreshnessSchema,
+    /**
+     * Detailed index classification retained for API compatibility. It describes
+     * the index only (never a query spot-check); new consumers branch on
+     * `freshness` and inspect `details` for the reason.
+     */
     status: FreshnessStatusSchema,
-    /** pln#601 — coarse rollup of `status`, uniform across all read surfaces. */
-    coarse: CoarseFreshnessSchema.optional(),
     details: z.record(z.string(), z.unknown()).default({}),
 });
 //# sourceMappingURL=types.js.map

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

@@ -47,6 +47,12 @@ export const UniversalEdgeKinds = [
     'resolves_to',
     'imports_symbol',
     'tests_for',
+    // P4 usages: a direct lexical invocation, a non-call lexical binding use, or
+    // an explicitly low-confidence text/property hint. Only `calls` is a proven
+    // invocation; consumers must never promote `possible_textual_match`.
+    'calls',
+    'references',
+    'possible_textual_match',
     'extends',
     'implements',
     'annotates',