@ngockhoale/ukit 3.5.2 → 3.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. package/CHANGELOG.md +17 -90
  2. package/README.md +1 -0
  3. package/package.json +8 -1
  4. package/src/cli/commands/doctor.js +14 -2
  5. package/src/cli/commands/memory.js +30 -2
  6. package/src/core/memory/memoryHit.js +2 -0
  7. package/src/core/memory/mutateMemory.js +9 -0
  8. package/src/core/memory/projectIdentity.js +9 -2
  9. package/src/core/memory/recallEngine.js +86 -4
  10. package/src/core/memory/registryPrune.js +230 -0
  11. package/src/core/memory/retrieval.js +12 -3
  12. package/src/core/runtimeConfig.js +1 -1
  13. package/src/index/queryIndex.js +151 -20
  14. package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
  15. package/template_project/.claude/ukit/index/lib/index-core.mjs +149 -19
  16. package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
  17. package/template_project/.claude/ukit/index/route-task.mjs +4 -1
  18. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
  19. package/template_project/.claude/ukit/runtime/memory-recall.mjs +86 -4
  20. package/template_project/.claude/ukit/runtime/memory-validity.mjs +232 -0
  21. package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
  22. package/src/core/observability/evaluation/experimentPlan.js +0 -95
  23. package/src/core/observability/evaluation/perturbation.js +0 -273
  24. package/src/diagnostics/classifyHang.js +0 -246
  25. package/src/diagnostics/ompStallSnapshot.js +0 -199
  26. package/src/render/instructionRenderer.js +0 -290
  27. package/src/skill/auditSkill.js +0 -140
  28. package/template_project/instructions/overlays/repo.md +0 -9
@@ -4,10 +4,12 @@
4
4
  import fs from 'node:fs/promises';
5
5
  import path from 'node:path';
6
6
  import crypto from 'node:crypto';
7
+ import { execFile } from 'node:child_process';
7
8
 
8
9
  export const EDIT_GRAPH_FILE = 'edit-graph.json';
9
10
  const SCHEMA = 1;
10
11
  const CAP = 5;
12
+ const TOGETHER = 3;
11
13
  const MIN_TWIN = 200;
12
14
  const MAX_HASH = 512 * 1024;
13
15
  const MAX_LOAD = 2 * 1024 * 1024;
@@ -71,21 +73,133 @@ export function findTwinGroups(entries) {
71
73
  .sort((a, b) => cmp(a[0], b[0]));
72
74
  }
73
75
 
74
- export function rankTestsForSource({ source, stemMatches = [], importingTests = [], mentionCounts = {} } = {}) {
76
+ // Tiers (lower = earlier). coTests: [{path, count}] test files committed together
77
+ // with the source. A name/import edge that history confirms is the strongest signal,
78
+ // a repeated co-change alone comes next, then the name edges the history never saw.
79
+ export const STRONG_CO = 3;
80
+ // Grid-picked on the replay: a name edge alone outranks a weak (count 2) co-change.
81
+ export const TIER_ORDER = ['both', 'strong', 'name', 'weak'];
82
+ export function rankTestsForSource({ source, stemMatches = [], importingTests = [], mentionCounts = {}, coTests = [] } = {}, tuning = {}) {
83
+ const strongCo = tuning.strongCo ?? STRONG_CO;
84
+ const order = tuning.order ?? TIER_ORDER;
75
85
  const base = path.posix.basename(norm(source), path.posix.extname(norm(source))).toLowerCase();
76
86
  const generic = GENERIC.has(base) || base.length < 5;
77
87
  const count = (t) => Number((mentionCounts instanceof Map ? mentionCounts.get(t) : mentionCounts?.[t]) ?? 0);
78
- const rows = new Map();
79
- const add = (t, tier) => { if (!rows.has(t) || rows.get(t).tier > tier) rows.set(t, { t, tier }); };
88
+ const co = new Map((coTests ?? []).map((c) => [c.path, Number(c.count) || 0]));
89
+ const name = new Map(); // test -> best name tier: 0 stem, 1 import, 2 mention
90
+ const add = (t, tier) => { if (!name.has(t) || name.get(t) > tier) name.set(t, tier); };
80
91
  for (const t of stemMatches) add(t, 0);
81
92
  for (const t of importingTests) add(t, 1);
82
93
  if (!generic) {
83
94
  const names = mentionCounts instanceof Map ? [...mentionCounts.keys()] : Object.keys(mentionCounts ?? {});
84
95
  for (const t of names) if (count(t) > 0) add(t, 2);
85
96
  }
86
- return [...rows.values()]
87
- .sort((a, b) => a.tier - b.tier || (a.tier === 2 ? count(b.t) - count(a.t) : 0) || cmp(a.t, b.t))
88
- .map((r) => r.t);
97
+ const klass = (t) => {
98
+ const n = name.get(t);
99
+ const c = co.get(t) ?? 0;
100
+ if (n === undefined) return c >= strongCo ? 'strong' : 'weak'; // co-change only
101
+ return c > 0 ? 'both' : 'name'; // name edge confirmed by history / name edge alone
102
+ };
103
+ const tierOf = (t) => order.indexOf(klass(t)) * 4 + (name.get(t) ?? 0);
104
+ return [...new Set([...name.keys(), ...co.keys()])]
105
+ .sort((a, b) => tierOf(a) - tierOf(b) || (co.get(b) ?? 0) - (co.get(a) ?? 0) || count(b) - count(a) || cmp(a, b));
106
+ }
107
+
108
+ // Co-change model: how often two files were committed together. Commits touching
109
+ // more than MAX_COMMIT_FILES files (merge/squash/format noise) add no pairs but
110
+ // still count toward a file's own commit total. add/remove keep a sliding window
111
+ // cheap, which is how the history bench mines "strictly before this commit".
112
+ export const CO_MAX_COMMITS = 500;
113
+ export const CO_MAX_COMMIT_FILES = 50;
114
+ export const CO_MIN_COUNT = 2;
115
+
116
+ export function createCoChange({ maxCommitFiles = CO_MAX_COMMIT_FILES } = {}) {
117
+ const peers = new Map(); // file -> Map(other -> count)
118
+ const commits = new Map(); // file -> number of commits touching it
119
+ const bump = (map, key, d) => {
120
+ const n = (map.get(key) ?? 0) + d;
121
+ if (n > 0) map.set(key, n); else map.delete(key);
122
+ };
123
+ const apply = (files, d_) => {
124
+ const set = [...new Set((files ?? []).map(norm).filter(Boolean))];
125
+ for (const f of set) bump(commits, f, d_);
126
+ if (set.length < 2 || set.length > maxCommitFiles) return;
127
+ for (const a of set) {
128
+ if (!peers.has(a)) peers.set(a, new Map());
129
+ for (const b of set) if (a !== b) bump(peers.get(a), b, d_);
130
+ if (!peers.get(a).size) peers.delete(a);
131
+ }
132
+ };
133
+ return {
134
+ add: (files) => apply(files, 1),
135
+ remove: (files) => apply(files, -1),
136
+ commitsOf: (file) => commits.get(norm(file)) ?? 0,
137
+ // [{path, count, confidence}] strongest first (count desc, confidence desc, path asc).
138
+ peersOf(file, { minCount = CO_MIN_COUNT } = {}) {
139
+ const f = norm(file);
140
+ const total = commits.get(f) ?? 0;
141
+ const out = [];
142
+ for (const [p, count] of peers.get(f) ?? []) if (count >= minCount) out.push({ path: p, count, confidence: count / total });
143
+ return out.sort((x, y) => y.count - x.count || y.confidence - x.confidence || cmp(x.path, y.path));
144
+ },
145
+ };
146
+ }
147
+
148
+ // Co-changed peers of `source` that still exist, split into test files and the rest.
149
+ // Shared by the graph build and the history bench so both score the same evidence.
150
+ export function coChangeFor(model, source, { exists = () => true, minCount = CO_MIN_COUNT } = {}) {
151
+ const tests = [];
152
+ const files = [];
153
+ const src = norm(source);
154
+ for (const peer of model?.peersOf(src, { minCount }) ?? []) {
155
+ if (peer.path === src || !exists(peer.path)) continue;
156
+ (isTestSource(peer.path) ? tests : isTestPath(peer.path) ? [] : files).push(peer);
157
+ }
158
+ return { tests, files };
159
+ }
160
+
161
+ // "@@<sha>" header lines followed by the commit's file names (git log --name-only).
162
+ export function parseCoChangeLog(out) {
163
+ const list = [];
164
+ let cur = null;
165
+ for (const line of String(out ?? '').split('\n')) {
166
+ if (line.startsWith('@@')) {
167
+ const sha = line.slice(2).trim();
168
+ cur = /^[0-9a-f]{40}$/i.test(sha) ? { sha: sha.toLowerCase(), files: [] } : null;
169
+ if (cur) list.push(cur);
170
+ } else if (cur && line.trim()) {
171
+ cur.files.push(norm(line));
172
+ }
173
+ }
174
+ return list;
175
+ }
176
+
177
+ function git(rootDir, args, { signal, timeoutMs = 20_000 } = {}) {
178
+ return new Promise((resolve) => {
179
+ if (signal?.aborted) return resolve(null);
180
+ try {
181
+ execFile('git', args, { cwd: rootDir, maxBuffer: 64 * 1024 * 1024, timeout: timeoutMs, killSignal: 'SIGKILL', ...(signal ? { signal } : {}), windowsHide: true },
182
+ (error, stdout) => resolve(error ? null : String(stdout)));
183
+ } catch {
184
+ resolve(null);
185
+ }
186
+ });
187
+ }
188
+
189
+ export async function gitHead(rootDir, opts = {}) {
190
+ const sha = String(await git(rootDir, ['rev-parse', 'HEAD'], { timeoutMs: 5000, ...opts }) ?? '').trim();
191
+ return /^[0-9a-f]{40}$/i.test(sha) ? sha.toLowerCase() : null;
192
+ }
193
+
194
+ // Bounded history for the graph build. Graph build/refresh only, never the hook path.
195
+ // Non-git directory or any git failure -> null (graph still builds without co-change).
196
+ export async function mineCoChange(rootDir, { maxCommits = CO_MAX_COMMITS, signal, timeoutMs } = {}) {
197
+ const root = path.resolve(rootDir ?? '.');
198
+ const head = await gitHead(root, { signal });
199
+ if (!head) return null;
200
+ const log = await git(root, ['-c', 'core.quotePath=false', 'log', '--no-renames', '--name-only', '--format=@@%H', '-n', String(maxCommits)], { signal, timeoutMs });
201
+ if (log === null) return null;
202
+ return { head, commits: parseCoChangeLog(log).map((c) => c.files) };
89
203
  }
90
204
 
91
205
  function cleanPair(raw) {
@@ -107,9 +221,10 @@ async function readHints(root, readFile) {
107
221
  return {
108
222
  mirrors: Array.isArray(h.mirrors) ? h.mirrors : [],
109
223
  ignore: Array.isArray(h.ignoreMirrors) ? h.ignoreMirrors.filter((v) => typeof v === 'string').map(norm) : [],
224
+ coChange: h.coChange === true, // the "changed together" line only; test co-change is always mined
110
225
  };
111
226
  } catch {
112
- return { mirrors: [], ignore: [] };
227
+ return { mirrors: [], ignore: [], coChange: false };
113
228
  }
114
229
  }
115
230
 
@@ -169,7 +284,7 @@ export async function buildEditGraph({
169
284
 
170
285
  const acc = new Map();
171
286
  const slot = (p) => {
172
- if (!acc.has(p)) acc.set(p, { m: [], t: [], i: new Set(), d: new Set() });
287
+ if (!acc.has(p)) acc.set(p, { m: [], t: [], c: [], i: new Set(), d: new Set() });
173
288
  return acc.get(p);
174
289
  };
175
290
  for (const [key, k] of pairs) {
@@ -198,15 +313,26 @@ export async function buildEditGraph({
198
313
  if (signal?.aborted) throw new Error('edit-graph build aborted');
199
314
  const byStem = new Map();
200
315
  for (const t of testPaths) byStem.set(stemOf(t), [...(byStem.get(stemOf(t)) ?? []), t]);
316
+ // Co-change from bounded git history (async, abortable; null outside git or on any
317
+ // git failure, in which case the graph is the name/import graph only).
318
+ const mined = await mineCoChange(root, { signal });
319
+ if (signal?.aborted) throw new Error('edit-graph build aborted');
320
+ const model = createCoChange();
321
+ for (const files of mined?.commits ?? []) model.add(files);
201
322
  for (const src of [...sizes.keys()].sort(cmp)) {
202
323
  if (isTestPath(src) || !SRC_RE.test(src)) continue;
324
+ const co = coChangeFor(model, src, { exists: (p) => sizes.has(p) });
203
325
  const ranked = rankTestsForSource({
204
326
  source: src,
205
327
  stemMatches: byStem.get(stemOf(src)) ?? [],
206
328
  importingTests: [...(acc.get(src)?.i ?? [])].filter(isTestPath),
207
329
  mentionCounts: mentionCountsFor(src, tokens),
330
+ coTests: co.tests,
208
331
  }).slice(0, CAP);
209
332
  if (ranked.length) slot(src).t = ranked;
333
+ const twins = new Set((acc.get(src)?.m ?? []).map((x) => x.p));
334
+ const together = co.files.filter((x) => !twins.has(x.path) && !ignored.has(x.path)).slice(0, TOGETHER).map((x) => ({ p: x.path, n: x.count }));
335
+ if (hints.coChange && together.length) slot(src).c = together;
210
336
  }
211
337
 
212
338
  const out = {};
@@ -214,9 +340,11 @@ export async function buildEditGraph({
214
340
  const s = acc.get(p);
215
341
  const m = s.m.sort((x, y) => cmp(x.p, y.p) || cmp(x.k, y.k)).slice(0, CAP);
216
342
  const entry = { m, t: s.t, i: cap([...s.i]), d: cap([...s.d]) };
217
- if (m.length || entry.t.length || entry.i.length || entry.d.length) out[p] = entry;
343
+ if (s.c.length) entry.c = s.c;
344
+ if (m.length || entry.t.length || entry.i.length || entry.d.length || s.c.length) out[p] = entry;
218
345
  }
219
- return { schemaVersion: SCHEMA, generatedAt: new Date().toISOString(), indexDigest, files: out };
346
+ // head: the commit the co-change evidence was mined at; a moved HEAD triggers a rebuild.
347
+ return { schemaVersion: SCHEMA, generatedAt: new Date().toISOString(), indexDigest, head: mined?.head ?? null, files: out };
220
348
  }
221
349
 
222
350
  const graphPath = (rootDir) => path.join(path.resolve(rootDir), '.cache', 'index', EDIT_GRAPH_FILE);
@@ -255,6 +383,7 @@ export function neighboursOf(graph, filePath) {
255
383
  tests: strs(e?.t),
256
384
  importers: strs(e?.i),
257
385
  imports: strs(e?.d),
386
+ together: (Array.isArray(e?.c) ? e.c : []).filter((x) => typeof x?.p === 'string').map((x) => ({ path: x.p, count: Number(x.n) || 0 })),
258
387
  };
259
388
  }
260
389
 
@@ -264,7 +393,8 @@ export function neighboursOf(graph, filePath) {
264
393
  export async function ensureEditGraph({ rootDir, indexDigest, inputs, signal } = {}) {
265
394
  try {
266
395
  const previousGraph = await loadEditGraph(rootDir);
267
- if (previousGraph && indexDigest && previousGraph.indexDigest === indexDigest) return previousGraph;
396
+ const head = await gitHead(path.resolve(rootDir), { signal });
397
+ if (previousGraph && indexDigest && previousGraph.indexDigest === indexDigest && (previousGraph.head ?? null) === head) return previousGraph;
268
398
  const graph = await buildEditGraph({ rootDir, indexDigest, previousGraph, signal, ...(typeof inputs === 'function' ? await inputs() : inputs) });
269
399
  await writeEditGraph(rootDir, graph);
270
400
  return graph;
@@ -1301,7 +1301,7 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
1301
1301
  return QUERY_RESULT_CACHE.get(queryCacheKey);
1302
1302
  }
1303
1303
  const queryPromise = (async () => {
1304
- const { files, searchDescriptorsByFile } = await loadQuerySearchBundle(absoluteRoot);
1304
+ const { files, searchDescriptorsByFile, tokenWeights } = await loadQuerySearchBundle(absoluteRoot);
1305
1305
  const preferredArchetypes = inferPreferredArchetypes(queryDescriptor.tokens);
1306
1306
  const includeLikelyTestFiles = shouldIncludeLikelyTestFiles(queryDescriptor);
1307
1307
 
@@ -1312,8 +1312,10 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
1312
1312
  const searchDescriptor = searchDescriptorsByFile.get(filePath) ?? createFileSearchDescriptor({ filePath, symbols: [] });
1313
1313
  const { score, reasons } = scoreDirectFileMatch({
1314
1314
  queryDescriptor,
1315
+ rawQuery: normalizedQuery,
1315
1316
  filePath,
1316
1317
  searchDescriptor,
1318
+ tokenWeights,
1317
1319
  });
1318
1320
 
1319
1321
  if (score > 0) {
@@ -1355,9 +1357,12 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
1355
1357
  importersByTarget,
1356
1358
  testsMapBySource: testsBySource,
1357
1359
  });
1358
- const boosted = applyHotspotBoosts({ scores: relatedScores, hotspotScores });
1360
+ const boosted = capBoostLift({
1361
+ directScores,
1362
+ scores: applyHotspotBoosts({ scores: relatedScores, hotspotScores }),
1363
+ });
1359
1364
  return freezeQueryResults(
1360
- [...boosted.values()].sort((a, b) => b.score - a.score || a.filePath.localeCompare(b.filePath)).slice(0, limit),
1365
+ [...boosted.values()].map((entry) => ({ ...entry, score: finalizeScore(entry) })).sort((a, b) => b.score - a.score || a.filePath.localeCompare(b.filePath)).slice(0, limit),
1361
1366
  );
1362
1367
  })().catch((error) => {
1363
1368
  QUERY_RESULT_CACHE.delete(queryCacheKey);
@@ -3315,9 +3320,11 @@ async function loadQuerySearchBundle(rootDir) {
3315
3320
  const safeFiles = safeSchemaArtifact(files);
3316
3321
  const safeSymbols = safeSchemaArtifact(symbols);
3317
3322
  const symbolMap = groupBy(safeItems(safeSymbols), (item) => item.filePath);
3323
+ const searchDescriptorsByFile = buildFileSearchDescriptors(safeItems(safeFiles), symbolMap);
3318
3324
  return {
3319
3325
  files: safeFiles,
3320
- searchDescriptorsByFile: buildFileSearchDescriptors(safeItems(safeFiles), symbolMap),
3326
+ searchDescriptorsByFile,
3327
+ tokenWeights: buildTokenWeights(searchDescriptorsByFile),
3321
3328
  };
3322
3329
  })
3323
3330
  .catch((error) => {
@@ -3393,9 +3400,91 @@ function tokenize(query) {
3393
3400
  return tokenizeFoldedText(foldTextForSearch(addCamelBoundaries(query)));
3394
3401
  }
3395
3402
 
3396
- function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
3403
+ // ── Ranking constants (kept identical in src/index/queryIndex.js) ──
3404
+ const PATH_EXACT_SCORE = 60;
3405
+ const PATH_SUFFIX_SCORE = 48;
3406
+ const PATH_BASENAME_SCORE = 40;
3407
+ const SYMBOL_EXACT_SCORE = 40;
3408
+ const SYMBOL_DECAY = 0.35; // k-th best symbol of a file adds score * SYMBOL_DECAY^k
3409
+ const SYMBOL_REASON_LIMIT = 3;
3410
+ const MIN_SUBSTRING_TOKEN_LENGTH = 3;
3411
+ const BOOST_LIFT_RATIO = 0.2; // import/hotspot/archetype boosts may add at most this share of a direct score (+1)
3412
+ const BOOST_ONLY_RATIO = 0.3; // files with no direct match stay below this share of the best direct score
3413
+
3414
+ // Rarity weight per token in (0,1]: a token present in nearly every file is worth
3415
+ // ~ln2/ln(1+N), a token unique to one file is worth 1. Computed once per bundle.
3416
+ function buildTokenWeights(searchDescriptorsByFile) {
3417
+ const docFrequency = new Map();
3418
+ for (const descriptor of searchDescriptorsByFile.values()) {
3419
+ const seen = new Set(descriptor.path.tokens);
3420
+ for (const symbol of descriptor.symbols) {
3421
+ for (const token of symbol.descriptor.tokens) {
3422
+ seen.add(token);
3423
+ }
3424
+ }
3425
+ for (const token of seen) {
3426
+ docFrequency.set(token, (docFrequency.get(token) ?? 0) + 1);
3427
+ }
3428
+ }
3429
+ const total = searchDescriptorsByFile.size;
3430
+ const denominator = Math.log(1 + total) || 1;
3431
+ const weights = new Map();
3432
+ for (const [token, count] of docFrequency) {
3433
+ weights.set(token, Math.max(0.05, Math.log(1 + total / count) / denominator));
3434
+ }
3435
+ return weights;
3436
+ }
3437
+
3438
+ // Prior applied after scoring so an original beats its mirror copy on ties without
3439
+ // hiding the mirror: root installed copies < template_project < everything else.
3440
+ function mirrorPrior(filePath) {
3441
+ if (/^\.(?:claude|codex|omp)\//.test(filePath)) {
3442
+ return 0.88;
3443
+ }
3444
+ if (filePath.startsWith('template_project/')) {
3445
+ return 0.94;
3446
+ }
3447
+ return 1;
3448
+ }
3449
+
3450
+ function normalizePathQuery(rawQuery) {
3451
+ const value = String(rawQuery ?? '').trim().toLowerCase().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
3452
+ return value.length >= 3 && !/\s/.test(value) ? value : '';
3453
+ }
3454
+
3455
+ // Exact path / path-suffix (whole segments) / basename match for single-term queries.
3456
+ function scorePathQuery(pathQuery, filePath) {
3457
+ if (!pathQuery) {
3458
+ return null;
3459
+ }
3460
+ const lower = filePath.toLowerCase();
3461
+ const noExt = lower.replace(/\.[a-z0-9]+$/, '');
3462
+ if (pathQuery === lower) {
3463
+ return { score: PATH_EXACT_SCORE, reason: `path_exact:${filePath}` };
3464
+ }
3465
+ if (pathQuery.includes('/')) {
3466
+ if (noExt === pathQuery || lower.endsWith(`/${pathQuery}`) || noExt.endsWith(`/${pathQuery}`)) {
3467
+ return { score: PATH_SUFFIX_SCORE, reason: `path_suffix:${pathQuery}` };
3468
+ }
3469
+ return null;
3470
+ }
3471
+ const base = lower.slice(lower.lastIndexOf('/') + 1);
3472
+ if (pathQuery === base || pathQuery === base.replace(/\.[a-z0-9]+$/, '')) {
3473
+ return { score: PATH_BASENAME_SCORE, reason: `path_basename:${pathQuery}` };
3474
+ }
3475
+ return null;
3476
+ }
3477
+
3478
+ function scoreDirectFileMatch({ queryDescriptor, rawQuery = '', filePath, searchDescriptor, tokenWeights = null }) {
3397
3479
  let score = 0;
3398
3480
  const reasons = [];
3481
+ const weightOf = (token) => tokenWeights?.get(token) ?? 1;
3482
+
3483
+ const pathHit = scorePathQuery(normalizePathQuery(rawQuery), filePath);
3484
+ if (pathHit) {
3485
+ score += pathHit.score;
3486
+ reasons.push(pathHit.reason);
3487
+ }
3399
3488
 
3400
3489
  if (
3401
3490
  queryDescriptor.compact.length >= 6
@@ -3407,43 +3496,45 @@ function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
3407
3496
 
3408
3497
  for (const token of queryDescriptor.tokens) {
3409
3498
  if (searchDescriptor.path.tokens.has(token)) {
3410
- score += 3;
3499
+ score += 3 * weightOf(token);
3411
3500
  reasons.push(`path_token:${token}`);
3412
- } else if (searchDescriptor.path.rawLower.includes(token)) {
3413
- score += 1;
3501
+ } else if (token.length >= MIN_SUBSTRING_TOKEN_LENGTH && searchDescriptor.path.rawLower.includes(token)) {
3502
+ score += weightOf(token);
3414
3503
  reasons.push(`path_contains:${token}`);
3415
3504
  }
3416
3505
  }
3417
3506
 
3507
+ const symbolHits = [];
3418
3508
  for (const symbolDescriptor of searchDescriptor.symbols) {
3419
3509
  if (
3420
3510
  queryDescriptor.compact.length >= 4
3421
3511
  && symbolDescriptor.descriptor.compact === queryDescriptor.compact
3422
3512
  ) {
3423
- score += 8;
3424
- reasons.push(`symbol_exact:${symbolDescriptor.name}`);
3513
+ symbolHits.push({ score: SYMBOL_EXACT_SCORE, reasons: [`symbol_exact:${symbolDescriptor.name}`] });
3425
3514
  continue;
3426
3515
  }
3427
3516
 
3517
+ let symbolScore = 0;
3518
+ const symbolReasons = [];
3428
3519
  if (
3429
3520
  queryDescriptor.compact.length >= 6
3430
3521
  && symbolDescriptor.descriptor.compact.includes(queryDescriptor.compact)
3431
3522
  ) {
3432
- score += 5;
3433
- reasons.push(`symbol_compact:${symbolDescriptor.name}`);
3523
+ symbolScore += 5;
3524
+ symbolReasons.push(`symbol_compact:${symbolDescriptor.name}`);
3434
3525
  }
3435
3526
 
3436
3527
  let symbolContributed = false;
3437
3528
 
3438
3529
  for (const token of queryDescriptor.tokens) {
3439
3530
  if (symbolDescriptor.descriptor.tokens.has(token)) {
3440
- score += 3;
3531
+ symbolScore += 3 * weightOf(token);
3441
3532
  symbolContributed = true;
3442
- reasons.push(`symbol_token:${symbolDescriptor.name}:${token}`);
3443
- } else if (symbolDescriptor.descriptor.rawLower.includes(token)) {
3444
- score += 1;
3533
+ symbolReasons.push(`symbol_token:${symbolDescriptor.name}:${token}`);
3534
+ } else if (token.length >= MIN_SUBSTRING_TOKEN_LENGTH && symbolDescriptor.descriptor.rawLower.includes(token)) {
3535
+ symbolScore += weightOf(token);
3445
3536
  symbolContributed = true;
3446
- reasons.push(`symbol_contains:${symbolDescriptor.name}`);
3537
+ symbolReasons.push(`symbol_contains:${symbolDescriptor.name}`);
3447
3538
  }
3448
3539
  }
3449
3540
 
@@ -3453,15 +3544,54 @@ function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
3453
3544
  // from the stronger tiers above.
3454
3545
  if (!symbolContributed && queryDescriptor.compact.length >= 6) {
3455
3546
  if (symbolFuzzyMatches(queryDescriptor.compact, symbolDescriptor.descriptor.compact)) {
3456
- score += 3;
3457
- reasons.push(`symbol_fuzzy:${symbolDescriptor.name}`);
3547
+ symbolScore += 3;
3548
+ symbolReasons.push(`symbol_fuzzy:${symbolDescriptor.name}`);
3458
3549
  }
3459
3550
  }
3551
+
3552
+ if (symbolScore > 0) {
3553
+ symbolHits.push({ score: symbolScore, reasons: symbolReasons });
3554
+ }
3460
3555
  }
3461
3556
 
3557
+ // Best symbol dominates; further symbols add with sharp diminishing returns so
3558
+ // file size (symbol count) cannot outvote match quality.
3559
+ symbolHits.sort((a, b) => b.score - a.score);
3560
+ let decay = 1;
3561
+ symbolHits.forEach((hit, index) => {
3562
+ score += hit.score * decay;
3563
+ decay *= SYMBOL_DECAY;
3564
+ if (index < SYMBOL_REASON_LIMIT) {
3565
+ reasons.push(...hit.reasons);
3566
+ }
3567
+ });
3568
+
3462
3569
  return { score, reasons: [...new Set(reasons)], filePath };
3463
3570
  }
3464
3571
 
3572
+ // Import-graph, hotspot and archetype boosts are context, not evidence: they may
3573
+ // reorder near-equal direct matches but never lift a weak match over a strong one,
3574
+ // and files with no direct match stay below the best direct match.
3575
+ function capBoostLift({ directScores, scores }) {
3576
+ let maxDirect = 0;
3577
+ for (const entry of directScores.values()) {
3578
+ maxDirect = Math.max(maxDirect, entry.score);
3579
+ }
3580
+ for (const [filePath, entry] of scores) {
3581
+ const base = directScores.get(filePath)?.score;
3582
+ if (base === undefined) {
3583
+ entry.score = Math.min(entry.score, BOOST_ONLY_RATIO * maxDirect);
3584
+ } else {
3585
+ entry.score = base + Math.min(Math.max(entry.score - base, 0), BOOST_LIFT_RATIO * base + 1);
3586
+ }
3587
+ }
3588
+ return scores;
3589
+ }
3590
+
3591
+ function finalizeScore(entry) {
3592
+ return Number((entry.score * mirrorPrior(entry.filePath)).toFixed(2));
3593
+ }
3594
+
3465
3595
  // Fuzzy predicate shared by scoreDirectFileMatch and resolveSymbolCandidates:
3466
3596
  // ordered containment (either direction, on tokens or compacts) or a bounded
3467
3597
  // Damerau distance. Cheap length gates run first so the common non-fuzzy case
@@ -79,7 +79,7 @@ async function printEditHint({ rootDir, targetFile, intent }) {
79
79
  target = path.relative(path.resolve(rootDir), target).split(path.sep).join('/');
80
80
  if (!target || target.startsWith('..') || path.isAbsolute(target)) return; // outside the project: silent
81
81
  }
82
- const hint = await editHintFor({ projectRoot: rootDir, target, query: intent });
82
+ const hint = await editHintFor({ projectRoot: rootDir, target, query: intent, capture: true });
83
83
  if (hint.text) console.log(hint.text);
84
84
  } catch {
85
85
  // Hints are advisory; never fail the helper.
@@ -39,6 +39,7 @@ import {
39
39
  import { resolveRecordFreshness } from '../runtime/memory-freshness.mjs';
40
40
  import { resolveMemoryStage } from '../runtime/memory-flags.mjs';
41
41
  import { recallForHook, renderMarkdownDoc } from '../runtime/memory-recall.mjs';
42
+ import { withValidity, staleSuffix } from '../runtime/memory-validity.mjs';
42
43
  import {
43
44
  ROUTE_VERSION,
44
45
  ROUTE_CONTRACT_VERSION,
@@ -7272,7 +7273,9 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
7272
7273
  });
7273
7274
  const recalled = await recallForHook({
7274
7275
  projectRoot: rootDir, query: taskQuery, docs, config: memoryConfig, limit: 2,
7276
+ annotate: (pool) => withValidity(rootDir, pool),
7275
7277
  });
7278
+ const validityById = new Map(recalled.ranked.map((entry) => [entry.doc.id, entry.doc]));
7276
7279
  const rankedItems = recalled.ranked.map((entry) => (entry.doc.type === 'markdown'
7277
7280
  ? { id: entry.doc.id, type: 'markdown', doc: entry.doc }
7278
7281
  : itemById.get(entry.doc.id))).filter(Boolean);
@@ -7294,7 +7297,7 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
7294
7297
  return {
7295
7298
  line: rankedItems.map((item) => (item.type === 'markdown'
7296
7299
  ? renderMarkdownDoc(item.doc, 120)
7297
- : buildPreviousContextSnippet(item, freshnessById.get(item.id)))).join(' | '),
7300
+ : `${buildPreviousContextSnippet(item, freshnessById.get(item.id))}${staleSuffix(validityById.get(item.id))}`)).join(' | '),
7298
7301
  selectedIds: rankedItems.map((item) => item.id),
7299
7302
  fingerprint: buildCompactMachineKey('route-memory-v2', {
7300
7303
  taskQuery: normalize(taskQuery),
@@ -2,7 +2,10 @@
2
2
  // Standalone ESM; deterministic, no LLM, async fs only, never throws to callers.
3
3
  import fsp from 'node:fs/promises';
4
4
  import path from 'node:path';
5
- import { loadMarkdownDocs, normalizeMemorySources, rankDocs } from './memory-recall.mjs';
5
+ import {
6
+ demoteByValidity, dropSuperseded, fuseRanked, loadMarkdownDocs, normalizeMemorySources, rankDocs, STALE_MARKER,
7
+ } from './memory-recall.mjs';
8
+ import { withValidity } from './memory-validity.mjs';
6
9
  import { eligible, resolveProjectIdentityMirror } from './memory-policy.mjs';
7
10
  import { resolveMemoryStage } from './memory-flags.mjs';
8
11
 
@@ -49,17 +52,9 @@ export function extractAnchors(doc) {
49
52
 
50
53
  const byId = (a, b) => String(a.id ?? '').localeCompare(String(b.id ?? ''));
51
54
 
55
+ // Reciprocal rank fusion (3.5.3); same signature as the 3.5.2 priority merge.
52
56
  export function fuseLanes(lanes, { limit = Infinity } = {}) {
53
- const seen = new Set();
54
- const out = [];
55
- for (const lane of Array.isArray(lanes) ? lanes : []) {
56
- for (const id of lane ?? []) {
57
- if (seen.has(id)) continue;
58
- seen.add(id);
59
- out.push(id);
60
- }
61
- }
62
- return out.slice(0, limit);
57
+ return fuseRanked(lanes).map((e) => e.id).slice(0, limit);
63
58
  }
64
59
 
65
60
  function docEligible(doc, now) {
@@ -76,7 +71,7 @@ export function recallForTarget({ target, neighbours, docs, query = '', limit =
76
71
  const empty = { ranked: [], abstained: true };
77
72
  try {
78
73
  const now = Date.now();
79
- const pool = (Array.isArray(docs) ? docs : []).filter((d) => docEligible(d, now));
74
+ const pool = dropSuperseded((Array.isArray(docs) ? docs : []).filter((d) => docEligible(d, now)));
80
75
  if (pool.length === 0 || !target) return empty;
81
76
  const n = neighbours ?? {};
82
77
  const mirrors = new Set(paths(n.mirrors));
@@ -106,7 +101,9 @@ export function recallForTarget({ target, neighbours, docs, query = '', limit =
106
101
  if (!info.has(e.doc.id)) { info.set(e.doc.id, { doc: e.doc, tier: 4, via: 'query' }); }
107
102
  fill.push(e.doc.id);
108
103
  }
109
- const ranked = fuseLanes([...lanes, fill], { limit }).map((id) => info.get(id));
104
+ // Lanes: file/graph proximity (tier order kept inside the lane) and BM25 text.
105
+ // Source validity then demotes changed/missing-source notes below valid ones.
106
+ const ranked = demoteByValidity(fuseLanes([lanes.flat(), fill]).map((id) => info.get(id)), (e) => e.doc).slice(0, limit);
110
107
  return { ranked, abstained: ranked.length === 0 };
111
108
  } catch {
112
109
  return empty;
@@ -125,15 +122,23 @@ export function renderEditHint({ target, neighbours, memory = [], maxChars = 600
125
122
  for (const m of mirrors) lines.push(`mirror (${KIND_LABEL[m.kind] ?? 'declared'}): ${flat(m.path)}`);
126
123
  const tests = [...new Set(paths(n.tests))].sort().slice(0, 3);
127
124
  if (tests.length) lines.push(`tests: ${tests.map(flat).join(', ')}`);
125
+ // Opt-in (memory.editHints.coChange === true): the caller passes `together` only then.
126
+ const shown = new Set([...mirrors.map((m) => m.path), ...tests]);
127
+ const together = [...(Array.isArray(n.together) ? n.together : [])]
128
+ .map((t) => (typeof t === 'string' ? { path: t, count: 0 } : t)).filter((t) => t?.path && !shown.has(t.path))
129
+ .sort((a, b) => (b.count ?? 0) - (a.count ?? 0) || String(a.path).localeCompare(String(b.path)))
130
+ .slice(0, 3).map((t) => flat(t.path));
131
+ if (together.length) lines.push(`often changed together: ${together.join(', ')}`);
128
132
  const mem = [];
129
133
  for (const entry of (Array.isArray(memory) ? memory : []).slice(0, 2)) {
130
134
  const doc = entry?.doc ?? entry;
131
135
  if (!doc) continue;
132
136
  const label = doc.type === 'markdown' ? (doc.provenance ?? doc.id) : (doc.id ?? doc.provenance);
133
137
  const head = `- [${flat(label)} | ${flat(entry.via ?? 'query')}] `;
138
+ const tag = doc.validity ? ` ${STALE_MARKER}` : '';
134
139
  const body = flat(doc.text);
135
- const room = Math.max(0, LINE_CHARS - head.length);
136
- mem.push(head + (body.length > room ? `${body.slice(0, Math.max(0, room - 3))}...` : body));
140
+ const room = Math.max(0, LINE_CHARS - head.length - tag.length);
141
+ mem.push(head + (body.length > room ? `${body.slice(0, Math.max(0, room - 3))}...` : body) + tag);
137
142
  }
138
143
  if (lines.length === 0 && mem.length === 0) return '';
139
144
  const build = (m) => [`[UKit edit-graph] ${flat(target)}`, ...lines,
@@ -170,14 +175,14 @@ async function loadRecordDocs(projectRoot, config) {
170
175
  return records.filter((r) => r && typeof r === 'object' && !r.superseded_by && eligible(r, ctx).ok)
171
176
  .map((r) => ({
172
177
  id: `record:${r.id}`, type: r.type, provenance: r.provenance, text: String(r.text ?? ''),
173
- evidence: r.evidence, created_at: r.created_at ?? 0,
178
+ evidence: r.evidence, created_at: r.created_at ?? 0, supersedes: r.supersedes,
174
179
  }));
175
180
  }
176
181
 
177
182
  const EMPTY = { text: '', neighbours: null, memoryIds: [] };
178
183
 
179
184
  export async function editHintFor({
180
- projectRoot, target, config = null, query = '', exclude = {}, signal, deps = {}, memoryBudgetMs,
185
+ projectRoot, target, config = null, query = '', exclude = {}, signal, deps = {}, memoryBudgetMs, capture = false,
181
186
  } = {}) {
182
187
  try {
183
188
  if (process.env.UKIT_EDIT_HINTS === '0' || !projectRoot || !target) return EMPTY;
@@ -201,23 +206,40 @@ export async function editHintFor({
201
206
  let neighbours = {
202
207
  mirrors: sorted(raw?.mirrors), tests: sorted(raw?.tests),
203
208
  importers: sorted(raw?.importers), imports: sorted(raw?.imports),
209
+ together: cfg?.memory?.editHints?.coChange === true
210
+ ? (Array.isArray(raw?.together) ? raw.together : []).filter(keep)
211
+ .sort((a, b) => (b.count ?? 0) - (a.count ?? 0) || String(a.path).localeCompare(String(b.path)))
212
+ : [],
204
213
  };
205
- const probe = [...neighbours.mirrors.slice(0, 4).map((m) => m.path), ...neighbours.tests.slice(0, MAX_STAT - Math.min(4, neighbours.mirrors.length))];
206
- const alive = new Set((await Promise.all(probe.slice(0, MAX_STAT).map(async (p) => ((await exists(projectRoot, p)) ? p : null)))).filter(Boolean));
207
- const probed = new Set(probe.slice(0, MAX_STAT));
214
+ const shownPaths = new Set([...neighbours.mirrors.map((m) => m.path), ...neighbours.tests.map((t) => t?.path ?? t)]);
215
+ neighbours.together = neighbours.together.filter((t) => !shownPaths.has(t.path)).slice(0, 3);
216
+ const probe = [
217
+ ...neighbours.mirrors.slice(0, 4).map((m) => m.path),
218
+ ...neighbours.tests.slice(0, MAX_STAT - Math.min(4, neighbours.mirrors.length)),
219
+ ].slice(0, MAX_STAT);
220
+ const togetherProbe = neighbours.together.map((t) => t.path);
221
+ const toProbe = [...new Set([...probe, ...togetherProbe])];
222
+ const alive = new Set((await Promise.all(toProbe.map(async (p) => ((await exists(projectRoot, p)) ? p : null)))).filter(Boolean));
223
+ const probed = new Set(toProbe);
208
224
  const live = (p) => !probed.has(p) || alive.has(p);
209
225
  neighbours = {
210
226
  ...neighbours,
211
227
  mirrors: neighbours.mirrors.filter((m) => live(m.path)),
212
228
  tests: neighbours.tests.filter(live),
229
+ together: neighbours.together.filter((t) => live(t.path)),
213
230
  };
214
231
  if (signal?.aborted) return EMPTY;
215
232
  // Graph part is ready; memory gets its own sub-budget and never delays it.
216
233
  let timer;
217
- const lookup = deps.loadMemory ? deps.loadMemory() : Promise.all([
234
+ // Source validity rides inside the same budget; `capture` (passed only by
235
+ // `resolve-context --target`) also anchors never-seen items; a hook never writes.
236
+ const lookup = (deps.loadMemory ? deps.loadMemory() : Promise.all([
218
237
  loadRecordDocs(projectRoot, cfg),
219
238
  loadMarkdownDocs(projectRoot, normalizeMemorySources(cfg)),
220
- ]);
239
+ ])).then(async ([recs, mds]) => {
240
+ const all = await withValidity(projectRoot, [...recs, ...mds], { capture });
241
+ return [all.slice(0, recs.length), all.slice(recs.length)];
242
+ });
221
243
  lookup.catch(() => {});
222
244
  const loaded = Number.isFinite(memoryBudgetMs)
223
245
  ? await Promise.race([lookup, new Promise((resolve) => { timer = setTimeout(() => resolve(null), Math.max(1, memoryBudgetMs)); })])