@ngockhoale/ukit 3.4.85 → 3.5.2
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.
- package/CHANGELOG.md +33 -1064
- package/bin/ukit +9 -0
- package/manifests/documentation.yaml +12 -0
- package/manifests/platform.full.yaml +23 -0
- package/package.json +1 -1
- package/src/cli/commands/install.js +12 -0
- package/src/cli/commands/memory.js +30 -3
- package/src/core/memory/episodeArchive.js +147 -0
- package/src/core/memory/episodes.js +199 -37
- package/src/core/memory/memoryHit.js +59 -40
- package/src/core/memory/mutateMemory.js +23 -3
- package/src/core/memory/recallEngine.js +423 -0
- package/src/core/memory/retrieval.js +55 -92
- package/src/core/observability/emit/lifecycle.js +30 -0
- package/src/core/runtimeConfig.js +7 -0
- package/src/index/buildIndex.js +22 -0
- package/src/index/impactContext.js +11 -1
- package/template_project/.claude/hooks/edit-hint.mjs +119 -0
- package/template_project/.claude/hooks/skill-router.sh +82 -51
- package/template_project/.claude/settings.json +2 -2
- package/template_project/.claude/ukit/index/edit-graph.mjs +274 -0
- package/template_project/.claude/ukit/index/lib/index-core.mjs +36 -1
- package/template_project/.claude/ukit/index/post-edit-verify.mjs +8 -5
- package/template_project/.claude/ukit/index/resolve-context.mjs +17 -0
- package/template_project/.claude/ukit/index/route-task.mjs +29 -48
- package/template_project/.claude/ukit/runtime/execution-ledger.mjs +45 -0
- package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs +62 -5
- package/template_project/.claude/ukit/runtime/memory-lanes.mjs +237 -0
- package/template_project/.claude/ukit/runtime/memory-recall.mjs +423 -0
- package/template_project/.claude/ukit/runtime/reinject-context.mjs +29 -45
- package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
- package/template_project/AGENTS.md +1 -1
- package/template_project/CLAUDE.md +1 -1
- package/template_project/instructions/core.md +1 -1
|
@@ -10,8 +10,9 @@ import { loadV2Records } from './storeV2Loader.js';
|
|
|
10
10
|
import { POLICY_VERSION, eligible, resolveEffectiveScope } from './policy.js';
|
|
11
11
|
import { loadRuntimeConfig } from '../runtimeConfig.js';
|
|
12
12
|
import { resolveMemoryStage, appendRolloutReceipt, latencyBandForMs } from './memoryFlags.js';
|
|
13
|
-
import {
|
|
14
|
-
import { buildMemoryHit,
|
|
13
|
+
import { normalize, tokenize } from './recordIndex.js';
|
|
14
|
+
import { buildMemoryHit, rankHitsDetailed } from './memoryHit.js';
|
|
15
|
+
import { loadMarkdownDocs, normalizeMemorySources, renderMarkdownDoc } from './recallEngine.js';
|
|
15
16
|
import { resolveRecordFreshness } from './memoryFreshness.js';
|
|
16
17
|
import { getHeadSha } from '../codeintel/freshness.js';
|
|
17
18
|
import { emitRetrievalQuery, emitMemoryRetrieved } from './memoryEmit.js';
|
|
@@ -233,21 +234,6 @@ export const LEGACY_SCOPE_MATCH = {
|
|
|
233
234
|
session: (record) => record.type === 'episode' || record.scope === 'session',
|
|
234
235
|
};
|
|
235
236
|
|
|
236
|
-
// TASK-003 (FR-005): both v2 search paths delegate ranking to rankHits.
|
|
237
|
-
// rankHits includes bonus-only (lexical=0) records; the index path can only
|
|
238
|
-
// surface token-matching candidates, so the scan path pre-filters to the
|
|
239
|
-
// same candidate pool (scoreRecordTokens > 0) — identical hits either way.
|
|
240
|
-
// Returns {hits, candidateCount} — the count feeds retrieval.query telemetry
|
|
241
|
-
// (DF2-FR08) without recomputing the pool.
|
|
242
|
-
function searchRecords(records, query, scope, limit, eligibleCtx, policy, now) {
|
|
243
|
-
const queryTokens = tokenize(query);
|
|
244
|
-
const candidates = records.filter((record) => scoreRecordTokens(record, queryTokens, now) > 0);
|
|
245
|
-
return {
|
|
246
|
-
hits: rankHits(candidates, { queryTokens, eligibleCtx, policy, scope, limit, now }),
|
|
247
|
-
candidateCount: candidates.length,
|
|
248
|
-
};
|
|
249
|
-
}
|
|
250
|
-
|
|
251
237
|
// Freshness is resolved post-limit only (≤ limit × MAX_EVIDENCE stats per
|
|
252
238
|
// call). Watermarks are caller-supplied; when omitted and a hit carries
|
|
253
239
|
// non-file evidence, `command` is filled lazily via getHeadSha (one bounded
|
|
@@ -269,6 +255,7 @@ async function attachFreshness(hits, records, { projectRoot, watermarks, now } =
|
|
|
269
255
|
}
|
|
270
256
|
await Promise.all(hits.map(async (hit) => {
|
|
271
257
|
const record = recordById.get(hit.id);
|
|
258
|
+
if (!record) return; // markdown-source hits carry no record evidence
|
|
272
259
|
hit.freshness = await resolveRecordFreshness(record, {
|
|
273
260
|
projectRoot,
|
|
274
261
|
watermarks: resolvedWatermarks,
|
|
@@ -287,37 +274,10 @@ const REQUESTED_SCOPE_TO_POLICY = { project: 'repo' };
|
|
|
287
274
|
// mismatch, absence, or error falls back to the lexical scan — the index
|
|
288
275
|
// narrows candidates, rankHits re-gates + scores (identical output either
|
|
289
276
|
// path: the index candidate pool is exactly the score>0 set the scan uses).
|
|
290
|
-
//
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
export function resetRecordIndexForTests() {
|
|
294
|
-
recordIndexes.clear();
|
|
295
|
-
}
|
|
296
|
-
|
|
297
|
-
function searchRecordsIndexed(records, query, scope, limit, eligibleCtx, policy, indexKey, generation, now) {
|
|
298
|
-
const queryTokens = tokenize(query);
|
|
299
|
-
if (queryTokens.length === 0) {
|
|
300
|
-
return searchRecords(records, query, scope, limit, eligibleCtx, policy, now);
|
|
301
|
-
}
|
|
302
|
-
try {
|
|
303
|
-
let index = recordIndexes.get(indexKey);
|
|
304
|
-
if (!index) {
|
|
305
|
-
index = createIndex();
|
|
306
|
-
recordIndexes.set(indexKey, index);
|
|
307
|
-
}
|
|
308
|
-
if (index.stats().generation !== generation) {
|
|
309
|
-
index.build(records, { generation });
|
|
310
|
-
}
|
|
311
|
-
const candidates = index.query(queryTokens, { limit: records.length })
|
|
312
|
-
.map((hit) => hit.record);
|
|
313
|
-
return {
|
|
314
|
-
hits: rankHits(candidates, { queryTokens, eligibleCtx, policy, scope, limit, now }),
|
|
315
|
-
candidateCount: candidates.length,
|
|
316
|
-
};
|
|
317
|
-
} catch {
|
|
318
|
-
return searchRecords(records, query, scope, limit, eligibleCtx, policy, now);
|
|
319
|
-
}
|
|
320
|
-
}
|
|
277
|
+
// 3.5.1: the persistent-less inverted index path was removed with the move to
|
|
278
|
+
// one BM25 engine (IDF needs the whole eligible set anyway). Kept as a no-op
|
|
279
|
+
// so existing test imports keep working.
|
|
280
|
+
export function resetRecordIndexForTests() {}
|
|
321
281
|
|
|
322
282
|
export async function search(query, scope = 'all', limit = 10, { projectRoot, projectId, projectAliases, index = true, watermarks, homeDir, now } = {}) {
|
|
323
283
|
const startedAt = Date.now();
|
|
@@ -360,44 +320,27 @@ export async function search(query, scope = 'all', limit = 10, { projectRoot, pr
|
|
|
360
320
|
includeUser: effective.includeUser,
|
|
361
321
|
};
|
|
362
322
|
|
|
323
|
+
// Markdown source (docs/MEMORY.md bullets by default): read-only documents,
|
|
324
|
+
// never copied into records.json. Missing file => no documents, no error.
|
|
325
|
+
const markdownDocs = scope === 'all' || scope === 'project' || scope === 'repo'
|
|
326
|
+
? await loadMarkdownDocs(projectRoot, normalizeMemorySources(config)).catch(() => [])
|
|
327
|
+
: [];
|
|
328
|
+
|
|
363
329
|
if (!v2AllowsLegacyFallback(state)) {
|
|
364
|
-
|
|
365
|
-
//
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
searchRecordsIndexed(records, query, scope, limit, eligibleCtx, policy, indexKey, generation, now);
|
|
372
|
-
await appendRolloutReceipt(projectRoot, {
|
|
373
|
-
plane: 'index', stage: 'shadow', outcome: 'ok', code: 'search',
|
|
374
|
-
latencyBand: latencyBandForMs(Date.now() - shadowStarted),
|
|
375
|
-
});
|
|
376
|
-
} catch {
|
|
377
|
-
await appendRolloutReceipt(projectRoot, {
|
|
378
|
-
plane: 'index', stage: 'shadow', outcome: 'error', code: 'search',
|
|
379
|
-
latencyBand: latencyBandForMs(Date.now() - shadowStarted),
|
|
380
|
-
});
|
|
381
|
-
}
|
|
382
|
-
}
|
|
383
|
-
const useIndex = index !== false && indexStage !== 'off' && indexStage !== 'shadow';
|
|
384
|
-
const { hits, candidateCount } = useIndex
|
|
385
|
-
? searchRecordsIndexed(
|
|
386
|
-
records, query, scope, limit, eligibleCtx, policy,
|
|
387
|
-
indexKey,
|
|
388
|
-
generation,
|
|
389
|
-
now,
|
|
390
|
-
)
|
|
391
|
-
: searchRecords(records, query, scope, limit, eligibleCtx, policy, now);
|
|
392
|
-
const results = await attachFreshness(hits, records, { projectRoot, watermarks, now });
|
|
393
|
-
emitQuery({ lane: 'v2', indexed: useIndex, candidateCount, results });
|
|
330
|
+
// One engine (recallEngine.js BM25): eligibility first, then IDF over the
|
|
331
|
+
// eligible set + markdown bullets, floor, explicit empty result.
|
|
332
|
+
const ranked = rankHitsDetailed(records, {
|
|
333
|
+
query, eligibleCtx, policy, scope, limit, now, extraDocs: markdownDocs,
|
|
334
|
+
});
|
|
335
|
+
const results = await attachFreshness(ranked.hits, records, { projectRoot, watermarks, now });
|
|
336
|
+
emitQuery({ lane: 'v2', indexed: false, candidateCount: ranked.candidateCount, results });
|
|
394
337
|
return results;
|
|
395
338
|
}
|
|
396
339
|
|
|
397
340
|
const items = await listMemoryItems(projectRoot, { homeDir });
|
|
398
341
|
const queryTokens = tokenize(query);
|
|
399
342
|
const inScope = items.filter((item) => withinScope(item, scope, projectId, projectAliases));
|
|
400
|
-
const
|
|
343
|
+
const legacyResults = inScope
|
|
401
344
|
.map((item) => ({
|
|
402
345
|
item,
|
|
403
346
|
score: scoreItem(item, queryTokens),
|
|
@@ -410,6 +353,10 @@ export async function search(query, scope = 'all', limit = 10, { projectRoot, pr
|
|
|
410
353
|
))
|
|
411
354
|
.slice(0, limit)
|
|
412
355
|
.map((entry) => buildSearchResult(entry.item, entry.score));
|
|
356
|
+
const markdownRanked = markdownDocs.length > 0
|
|
357
|
+
? rankHitsDetailed([], { query, limit, now, extraDocs: markdownDocs }).hits
|
|
358
|
+
: [];
|
|
359
|
+
const results = [...markdownRanked, ...legacyResults].slice(0, limit);
|
|
413
360
|
emitQuery({ lane: 'legacy', indexed: false, candidateCount: inScope.length, results });
|
|
414
361
|
return results;
|
|
415
362
|
}
|
|
@@ -533,6 +480,7 @@ function buildInjectionSnippet(item) {
|
|
|
533
480
|
|
|
534
481
|
|
|
535
482
|
function buildRecordSnippet(record) {
|
|
483
|
+
if (record.type === 'markdown') return renderMarkdownDoc(record);
|
|
536
484
|
const text = String(record.text ?? '').trim();
|
|
537
485
|
return `${record.type}=${text.length > 160 ? `${text.slice(0, 157)}...` : text}`;
|
|
538
486
|
}
|
|
@@ -676,21 +624,32 @@ export async function getContextInjection(
|
|
|
676
624
|
});
|
|
677
625
|
const rankedItems = await search(currentTask, 'all', Math.max(limit * 3, 8), { projectRoot, projectId, projectAliases, homeDir });
|
|
678
626
|
const eligibleCtx = { projectId: projectId ?? null, projectAliases, includeUser: recallPlan.includeUserMemory };
|
|
627
|
+
// Markdown-source hits (read-only bullets) are cited data with provenance
|
|
628
|
+
// `path:line`; they are never records and carry no evidence/freshness.
|
|
629
|
+
const markdownRecord = (entry) => ({
|
|
630
|
+
id: entry.id, type: 'markdown', text: entry.snippet, provenance: entry.provenance, evidence: [],
|
|
631
|
+
});
|
|
632
|
+
const markdownSelected = rankedItems.filter((entry) => entry.type === 'markdown').map(markdownRecord);
|
|
679
633
|
const selectedItems = v2Active
|
|
680
634
|
? dedupeItemsById(rankedItems
|
|
681
|
-
.map((entry) =>
|
|
635
|
+
.map((entry) => (entry.type === 'markdown'
|
|
636
|
+
? markdownRecord(entry)
|
|
637
|
+
: records.find((record) => record.id === entry.id)))
|
|
682
638
|
.filter(Boolean)
|
|
683
|
-
.filter((record) => eligible(record, eligibleCtx, policy).ok))
|
|
639
|
+
.filter((record) => record.type === 'markdown' || eligible(record, eligibleCtx, policy).ok))
|
|
684
640
|
.slice(0, Math.max(1, recallPlan.limit))
|
|
685
|
-
:
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
641
|
+
: [
|
|
642
|
+
...markdownSelected,
|
|
643
|
+
...selectContextItems({
|
|
644
|
+
items,
|
|
645
|
+
rankedItems: rankedItems.filter((entry) => entry.type !== 'markdown'),
|
|
646
|
+
projectId,
|
|
647
|
+
projectAliases,
|
|
648
|
+
limit: recallPlan.limit,
|
|
649
|
+
includeUserMemory: recallPlan.includeUserMemory,
|
|
650
|
+
allowProjectFallback: !String(currentTask ?? '').trim(),
|
|
651
|
+
}),
|
|
652
|
+
].slice(0, Math.max(1, recallPlan.limit));
|
|
694
653
|
|
|
695
654
|
if (selectedItems.length === 0) {
|
|
696
655
|
return '';
|
|
@@ -741,10 +700,14 @@ export async function getContextInjection(
|
|
|
741
700
|
const staleTag = (record) => (freshnessById.get(record.id)?.state === 'stale' ? ' [stale]' : '');
|
|
742
701
|
const rawBodyLines = v2Active
|
|
743
702
|
? selectedItems.map((record) => `- [${record.type}] ${buildRecordSnippet(record)}${staleTag(record)}`)
|
|
744
|
-
: selectedItems.map((item) =>
|
|
703
|
+
: selectedItems.map((item) => (item.type === 'markdown'
|
|
704
|
+
? `- [markdown] ${renderMarkdownDoc(item)}`
|
|
705
|
+
: `- [${item.type}] ${buildDetailedInjectionSnippet(item)}`));
|
|
745
706
|
const bodyLines = v2Active
|
|
746
707
|
? selectedItems.map((record) => `- ${buildRecordSnippet(record)}${staleTag(record)}`)
|
|
747
|
-
: selectedItems.map((item) =>
|
|
708
|
+
: selectedItems.map((item) => (item.type === 'markdown'
|
|
709
|
+
? `- ${renderMarkdownDoc(item)}`
|
|
710
|
+
: `- ${buildInjectionSnippet(item)}`));
|
|
748
711
|
const rawLines = ['## Previous Context', ...rawBodyLines];
|
|
749
712
|
const rawText = rawLines.join('\n');
|
|
750
713
|
const conciseText = ['## Previous Context', ...bodyLines].join('\n');
|
|
@@ -61,6 +61,7 @@
|
|
|
61
61
|
*/
|
|
62
62
|
|
|
63
63
|
import crypto from 'node:crypto';
|
|
64
|
+
import fs from 'node:fs';
|
|
64
65
|
import path from 'node:path';
|
|
65
66
|
import { createRecorder } from './recorder.js';
|
|
66
67
|
import { registerCrashCapture } from './crash.js';
|
|
@@ -406,6 +407,35 @@ export function recorderHealth({ projectRoot } = {}) {
|
|
|
406
407
|
};
|
|
407
408
|
}
|
|
408
409
|
|
|
410
|
+
/**
|
|
411
|
+
* flushAllRecorders({ deadlineMs }) — bounded drain of every memoized
|
|
412
|
+
* recorder. For short-lived CLI processes that never call startLifecycle:
|
|
413
|
+
* emit() only queues, so the entry point must flush before exit. Never
|
|
414
|
+
* throws; a failed/late flush keeps the recorder's own error policy
|
|
415
|
+
* (counters + last_error), and the deadline bounds the exit delay.
|
|
416
|
+
*/
|
|
417
|
+
export async function flushAllRecorders({ deadlineMs = DEFAULT_EXIT_DEADLINE_MS } = {}) {
|
|
418
|
+
const runs = [];
|
|
419
|
+
for (const [key, rec] of recorders) {
|
|
420
|
+
try {
|
|
421
|
+
if (rec.health().queue_depth > 0) {
|
|
422
|
+
// appendRecord's root check realpaths the segment root's PARENT, which
|
|
423
|
+
// a fresh project lacks (io_enoent would drop the whole queue).
|
|
424
|
+
runs.push(
|
|
425
|
+
fs.promises
|
|
426
|
+
.mkdir(observabilityRoot(key), { recursive: true })
|
|
427
|
+
.catch(() => {})
|
|
428
|
+
.then(() => rec.flush({ deadlineMs }))
|
|
429
|
+
.catch(() => {}),
|
|
430
|
+
);
|
|
431
|
+
}
|
|
432
|
+
} catch {
|
|
433
|
+
// never-throw
|
|
434
|
+
}
|
|
435
|
+
}
|
|
436
|
+
if (runs.length > 0) await Promise.all(runs);
|
|
437
|
+
}
|
|
438
|
+
|
|
409
439
|
/** Test/reset seam: detach every handle and drop all memoized recorders. */
|
|
410
440
|
export function resetForTests() {
|
|
411
441
|
detachLifecycle();
|
|
@@ -531,6 +531,8 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
|
|
|
531
531
|
maxArchivedSessions: 50,
|
|
532
532
|
maxPatternCandidates: 50,
|
|
533
533
|
redactSecrets: true,
|
|
534
|
+
sources: ['docs/MEMORY.md'],
|
|
535
|
+
editHints: { enabled: true, mirrors: [], ignoreMirrors: [] },
|
|
534
536
|
},
|
|
535
537
|
validation: {
|
|
536
538
|
enabled: true,
|
|
@@ -1188,6 +1190,11 @@ export function validateRuntimeConfig(config) {
|
|
|
1188
1190
|
pushPositiveNumberError(errors, config.memory.maxArchivedSessions, 'memory.maxArchivedSessions');
|
|
1189
1191
|
pushPositiveNumberError(errors, config.memory.maxPatternCandidates, 'memory.maxPatternCandidates');
|
|
1190
1192
|
pushBooleanError(errors, config.memory.redactSecrets, 'memory.redactSecrets');
|
|
1193
|
+
if (config.memory.sources !== undefined
|
|
1194
|
+
&& (!Array.isArray(config.memory.sources)
|
|
1195
|
+
|| config.memory.sources.some((entry) => typeof entry !== 'string'))) {
|
|
1196
|
+
errors.push('memory.sources must be an array of relative .md paths.');
|
|
1197
|
+
}
|
|
1191
1198
|
}
|
|
1192
1199
|
|
|
1193
1200
|
if (!isPlainObject(config.validation)) {
|
package/src/index/buildIndex.js
CHANGED
|
@@ -11,6 +11,8 @@ import { withAsyncLock } from '../../template_project/.claude/ukit/runtime/async
|
|
|
11
11
|
|
|
12
12
|
import { getArtifactPath, getIndexDir, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, isLikelyTestFilePath, normalizeRelative } from './paths.js';
|
|
13
13
|
import { importsNeedAliasContext, loadImportAliasContextState, resolveImportSpecifier } from './importResolution.js';
|
|
14
|
+
import { ensureEditGraph } from '../../template_project/.claude/ukit/index/edit-graph.mjs';
|
|
15
|
+
import { MIRROR_PAIRS } from './impactCatalog.js';
|
|
14
16
|
import { clearIndexArtifactCache } from './queryIndex.js';
|
|
15
17
|
import { clearRelatedTestArtifactCache } from './relatedTests.js';
|
|
16
18
|
|
|
@@ -582,6 +584,7 @@ async function buildCodeIndexInner({ rootDir = process.cwd(), changedFiles = nul
|
|
|
582
584
|
[INDEX_ARTIFACTS.relations]: relations.length,
|
|
583
585
|
},
|
|
584
586
|
});
|
|
587
|
+
await refreshEditGraph(absoluteRoot, sourceFingerprint.digest, fileRecords, codeFiles, imports, importAliasContext, signal);
|
|
585
588
|
const preservedRuntimeCaches = canReuseFilesArtifact
|
|
586
589
|
&& canReuseAllParsedArtifacts
|
|
587
590
|
&& canReuseTestsMap
|
|
@@ -1241,6 +1244,7 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
|
|
|
1241
1244
|
clearIndexArtifactCache(absoluteRoot);
|
|
1242
1245
|
clearRelatedTestArtifactCache(absoluteRoot);
|
|
1243
1246
|
}
|
|
1247
|
+
await refreshEditGraph(absoluteRoot, refreshedFingerprint.digest, mergedFileRecords, codeFiles, imports, importAliasContext, signal);
|
|
1244
1248
|
|
|
1245
1249
|
return {
|
|
1246
1250
|
indexDir,
|
|
@@ -2573,6 +2577,24 @@ function areSourceFingerprintsEqual(previousFingerprint, nextFingerprint) {
|
|
|
2573
2577
|
&& previousFingerprint?.digest === nextFingerprint?.digest;
|
|
2574
2578
|
}
|
|
2575
2579
|
|
|
2580
|
+
// Edit graph (mirror/test/import edges): rebuilt only when missing or its digest
|
|
2581
|
+
// differs from the index fingerprint. Never fails the index build.
|
|
2582
|
+
async function refreshEditGraph(rootDir, indexDigest, fileRecords, codeFiles, imports, aliasContext, signal) {
|
|
2583
|
+
await ensureEditGraph({
|
|
2584
|
+
rootDir,
|
|
2585
|
+
indexDigest,
|
|
2586
|
+
signal,
|
|
2587
|
+
inputs: () => {
|
|
2588
|
+
const resolved = buildResolvedImportMap(rootDir, imports, new Set(codeFiles.map((f) => f.filePath)), aliasContext);
|
|
2589
|
+
return {
|
|
2590
|
+
files: fileRecords,
|
|
2591
|
+
imports: resolved,
|
|
2592
|
+
declaredMirrors: MIRROR_PAIRS,
|
|
2593
|
+
};
|
|
2594
|
+
},
|
|
2595
|
+
});
|
|
2596
|
+
}
|
|
2597
|
+
|
|
2576
2598
|
async function writeArtifact(rootDir, artifactName, payload) {
|
|
2577
2599
|
const artifactPath = getArtifactPath(rootDir, artifactName);
|
|
2578
2600
|
const temporaryPath = `${artifactPath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
|
|
@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
|
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
|
|
4
4
|
import { getArtifactPath, INDEX_ARTIFACTS, isLikelyTestFilePath } from './paths.js';
|
|
5
|
+
import { loadEditGraph, neighboursOf } from '../../template_project/.claude/ukit/index/edit-graph.mjs';
|
|
5
6
|
import { classifyImpactRisk, findMirrorCounterparts } from './impactCatalog.js';
|
|
6
7
|
import { inferRelatedTestsFromArtifacts, loadRelatedTestArtifacts } from './relatedTests.js';
|
|
7
8
|
import { importsNeedAliasContext, loadImportAliasContext, resolveImportSpecifier } from './importResolution.js';
|
|
@@ -108,7 +109,16 @@ export async function resolveImpactContext({
|
|
|
108
109
|
const callItems = safeItems(callsArtifact);
|
|
109
110
|
const importItems = safeItems(importsArtifact);
|
|
110
111
|
const risk = classifyImpactRisk(normalizedChangedFiles);
|
|
111
|
-
const
|
|
112
|
+
const editGraph = await loadEditGraph(absoluteRoot);
|
|
113
|
+
const mirrorCounterparts = [...findMirrorCounterparts(normalizedChangedFiles)];
|
|
114
|
+
for (const changed of normalizedChangedFiles) {
|
|
115
|
+
for (const mirror of neighboursOf(editGraph, changed).mirrors) {
|
|
116
|
+
if (!mirrorCounterparts.some((m) => m.filePath === mirror.path && m.source === changed)) {
|
|
117
|
+
mirrorCounterparts.push({ filePath: mirror.path, reason: `edit-graph ${mirror.kind} mirror`, source: changed });
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
mirrorCounterparts.splice(budget.maxMirrors);
|
|
112
122
|
|
|
113
123
|
const changedFileSet = new Set(normalizedChangedFiles);
|
|
114
124
|
const changedSymbolSet = new Set(normalizedChangedSymbols);
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
// edit-hint.mjs — PostToolUse Edit|Write chain step (advisory, always code 0).
|
|
2
|
+
// After a successful edit of file X, hands the MODEL the edit-graph hint once per
|
|
3
|
+
// file per task (mirror to fix, tests to run, cited memory). Claude Code: JSON
|
|
4
|
+
// hookSpecificOutput.additionalContext; omp: the bridge appends stdout verbatim,
|
|
5
|
+
// so plain text. Async fs only; self-deadline 400 ms; any failure emits nothing.
|
|
6
|
+
import fsp from 'node:fs/promises';
|
|
7
|
+
import path from 'node:path';
|
|
8
|
+
|
|
9
|
+
const DEADLINE_MS = 400; // once per file per task; the step slot is 8 s
|
|
10
|
+
const MEMORY_MS = 250; // memory sub-budget: a miss still emits mirrors/tests
|
|
11
|
+
const MAX_SEEN = 200;
|
|
12
|
+
const MAX_BYTES = 16 * 1024;
|
|
13
|
+
const NONE = { code: 0, stdout: '', stderr: '' };
|
|
14
|
+
const safe = (v, d) => String(v || d).replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 80) || d;
|
|
15
|
+
const readJson = async (file) => {
|
|
16
|
+
try { return JSON.parse(await fsp.readFile(file, 'utf8')); } catch { return null; }
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
// Retention: over 64 entries, drop this step's own `<safe>.<safe>.json` files older than 7 days (max 32 deletions, 128 stats per run). Fire-and-forget.
|
|
20
|
+
async function prune(dir, keep) {
|
|
21
|
+
try {
|
|
22
|
+
const names = await fsp.readdir(dir);
|
|
23
|
+
if (names.length <= 64) return;
|
|
24
|
+
let left = 32;
|
|
25
|
+
let stats = 128;
|
|
26
|
+
for (const n of names) {
|
|
27
|
+
if (left <= 0 || stats <= 0) break;
|
|
28
|
+
if (n === keep || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.json$/.test(n)) continue;
|
|
29
|
+
stats -= 1;
|
|
30
|
+
try {
|
|
31
|
+
const f = path.join(dir, n);
|
|
32
|
+
if (Date.now() - (await fsp.stat(f)).mtimeMs <= 7 * 864e5) continue;
|
|
33
|
+
await fsp.unlink(f);
|
|
34
|
+
left -= 1;
|
|
35
|
+
} catch { /* ignore */ }
|
|
36
|
+
}
|
|
37
|
+
} catch { /* retention is best-effort */ }
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
async function hint(ctx, signal, commit) {
|
|
41
|
+
const { payload: p = {}, projectRoot, env = {} } = ctx;
|
|
42
|
+
if (env.UKIT_EDIT_HINTS === '0' || process.env.UKIT_EDIT_HINTS === '0') return NONE;
|
|
43
|
+
if (!['Edit', 'Write'].includes(p.tool_name) || !projectRoot) return NONE;
|
|
44
|
+
const res = p.tool_response;
|
|
45
|
+
if (res && (res.is_error === true || res.isError === true || res.success === false)) return NONE;
|
|
46
|
+
const raw = p.tool_input?.file_path;
|
|
47
|
+
if (typeof raw !== 'string' || !raw) return NONE;
|
|
48
|
+
const rel = path.relative(projectRoot, path.resolve(p.cwd || projectRoot, raw)).split(path.sep).join('/');
|
|
49
|
+
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return NONE;
|
|
50
|
+
|
|
51
|
+
const config = await readJson(path.join(projectRoot, '.ukit/storage/config.json'));
|
|
52
|
+
if (config?.memory?.editHints?.enabled === false) return NONE;
|
|
53
|
+
const route = await readJson(path.join(projectRoot, '.claude/ukit/skill-router-state.json'));
|
|
54
|
+
const session = safe(p.session_id, 'nosession');
|
|
55
|
+
const task = typeof route?.taskInstanceId === 'string' && route.taskInstanceId ? route.taskInstanceId : session;
|
|
56
|
+
const stateFile = path.join(projectRoot, '.ukit/storage/cache/edit-hints', `${session}.${safe(p.agent_id, 'main')}.json`);
|
|
57
|
+
const prev = await readJson(stateFile);
|
|
58
|
+
const st = prev && prev.task === task && Array.isArray(prev.seen)
|
|
59
|
+
? { task, seen: prev.seen.filter((x) => typeof x === 'string'), shownMem: Array.isArray(prev.shownMem) ? prev.shownMem.filter((x) => typeof x === 'string') : [] }
|
|
60
|
+
: { task, seen: [], shownMem: [] };
|
|
61
|
+
if (st.seen.includes(rel)) return NONE;
|
|
62
|
+
|
|
63
|
+
const lanes = await import('../ukit/runtime/memory-lanes.mjs');
|
|
64
|
+
const out = await lanes.editHintFor({
|
|
65
|
+
projectRoot, target: rel, config: config ?? {}, signal, memoryBudgetMs: MEMORY_MS,
|
|
66
|
+
exclude: { paths: st.seen, memoryIds: st.shownMem },
|
|
67
|
+
});
|
|
68
|
+
if (signal.aborted) return NONE;
|
|
69
|
+
// Memory missed its budget and there is no graph text: not "nothing to say", retry next edit.
|
|
70
|
+
if (out?.memoryMissed && !out.text) return NONE;
|
|
71
|
+
|
|
72
|
+
// Commit point: once state is being marked, finish and emit (a few ms of fs) so a
|
|
73
|
+
// deadline firing mid-write can never mark the file seen without delivering the hint.
|
|
74
|
+
commit.on = true;
|
|
75
|
+
st.seen.push(rel);
|
|
76
|
+
st.shownMem.push(...(out?.memoryIds || []));
|
|
77
|
+
st.seen = st.seen.slice(-MAX_SEEN);
|
|
78
|
+
st.shownMem = st.shownMem.slice(-MAX_SEEN);
|
|
79
|
+
let body = JSON.stringify(st);
|
|
80
|
+
while (body.length > MAX_BYTES && st.seen.length > 1) {
|
|
81
|
+
st.seen.shift();
|
|
82
|
+
st.shownMem.shift();
|
|
83
|
+
body = JSON.stringify(st);
|
|
84
|
+
}
|
|
85
|
+
try {
|
|
86
|
+
await fsp.mkdir(path.dirname(stateFile), { recursive: true });
|
|
87
|
+
const tmp = `${stateFile}.${process.pid}.tmp`;
|
|
88
|
+
await fsp.writeFile(tmp, body);
|
|
89
|
+
await fsp.rename(tmp, stateFile);
|
|
90
|
+
} catch { /* state is best-effort */ }
|
|
91
|
+
void prune(path.dirname(stateFile), path.basename(stateFile));
|
|
92
|
+
|
|
93
|
+
const text = typeof out?.text === 'string' ? out.text.trim() : '';
|
|
94
|
+
if (!text) return NONE;
|
|
95
|
+
const omp = p.ukit_harness === 'omp' || env.UKIT_HARNESS === 'omp';
|
|
96
|
+
const stdout = omp
|
|
97
|
+
? `${text}\n`
|
|
98
|
+
: `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } })}\n`;
|
|
99
|
+
return { code: 0, stdout, stderr: '' };
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
export async function runHook(ctx = {}) {
|
|
103
|
+
const ac = new AbortController();
|
|
104
|
+
const commit = { on: false };
|
|
105
|
+
const ms = Math.min(DEADLINE_MS, Number.isFinite(ctx.deadlineMs) ? ctx.deadlineMs : DEADLINE_MS);
|
|
106
|
+
const timer = setTimeout(() => ac.abort(), Math.max(1, ms));
|
|
107
|
+
const outer = ctx.signal;
|
|
108
|
+
if (outer) outer.aborted ? ac.abort() : outer.addEventListener('abort', () => ac.abort(), { once: true });
|
|
109
|
+
try {
|
|
110
|
+
return await Promise.race([
|
|
111
|
+
hint(ctx, ac.signal, commit),
|
|
112
|
+
new Promise((resolve) => ac.signal.addEventListener('abort', () => { if (!commit.on) resolve(NONE); }, { once: true })),
|
|
113
|
+
]);
|
|
114
|
+
} catch {
|
|
115
|
+
return NONE;
|
|
116
|
+
} finally {
|
|
117
|
+
clearTimeout(timer);
|
|
118
|
+
}
|
|
119
|
+
}
|
|
@@ -1116,6 +1116,7 @@ function applyTaskSemantics(contract, semantic) {
|
|
|
1116
1116
|
|
|
1117
1117
|
return {
|
|
1118
1118
|
configPath: path.join(storageRoot, 'config.json'),
|
|
1119
|
+
memoryRoot,
|
|
1119
1120
|
userMemoryPath: path.join(memoryRoot, 'user.json'),
|
|
1120
1121
|
projectsDir: path.join(memoryRoot, 'projects'),
|
|
1121
1122
|
sessionsDir: path.join(memoryRoot, 'sessions'),
|
|
@@ -2187,12 +2188,6 @@ function applyTaskSemantics(contract, semantic) {
|
|
|
2187
2188
|
.trim();
|
|
2188
2189
|
}
|
|
2189
2190
|
|
|
2190
|
-
function tokenizeMemoryText(text) {
|
|
2191
|
-
return normalizeMemoryText(text)
|
|
2192
|
-
.split(/\s+/)
|
|
2193
|
-
.filter((token) => token && !STOPWORDS.has(token) && token.length > 1);
|
|
2194
|
-
}
|
|
2195
|
-
|
|
2196
2191
|
function getMemoryTimestamp(item) {
|
|
2197
2192
|
return item.content?.updatedAt
|
|
2198
2193
|
?? item.content?.endedAt
|
|
@@ -2229,33 +2224,6 @@ function applyTaskSemantics(contract, semantic) {
|
|
|
2229
2224
|
];
|
|
2230
2225
|
}
|
|
2231
2226
|
|
|
2232
|
-
function scoreMemoryItem(item, queryTokens) {
|
|
2233
|
-
if (queryTokens.length === 0) {
|
|
2234
|
-
return 0;
|
|
2235
|
-
}
|
|
2236
|
-
|
|
2237
|
-
let score = 0;
|
|
2238
|
-
for (const segment of buildMemorySegments(item)) {
|
|
2239
|
-
const segmentTokens = new Set(tokenizeMemoryText(segment.text));
|
|
2240
|
-
for (const token of queryTokens) {
|
|
2241
|
-
if (segmentTokens.has(token)) {
|
|
2242
|
-
score += segment.weight;
|
|
2243
|
-
}
|
|
2244
|
-
}
|
|
2245
|
-
}
|
|
2246
|
-
|
|
2247
|
-
if (score === 0) {
|
|
2248
|
-
return 0;
|
|
2249
|
-
}
|
|
2250
|
-
|
|
2251
|
-
// TASK-027 CTX-01/CTX-04: the ranking must be a pure function of the logical memory
|
|
2252
|
-
// content. A recency bonus scaled by Date.now() made the score — and therefore the
|
|
2253
|
-
// injected previous-context block, its persisted order, and the PreCompact reinjection —
|
|
2254
|
-
// shift on every wall-clock tick. Eligibility is unchanged (still score > 0); only the
|
|
2255
|
-
// volatile ordering signal is dropped.
|
|
2256
|
-
return score;
|
|
2257
|
-
}
|
|
2258
|
-
|
|
2259
2227
|
function buildPreviousContextSnippet(item) {
|
|
2260
2228
|
const content = item.content ?? {};
|
|
2261
2229
|
if (item.type === 'project') {
|
|
@@ -2293,37 +2261,100 @@ function applyTaskSemantics(contract, semantic) {
|
|
|
2293
2261
|
return null;
|
|
2294
2262
|
}
|
|
2295
2263
|
|
|
2264
|
+
// 3.5.1: one recall engine. This lane no longer ranks privately; it feeds
|
|
2265
|
+
// the v1 items, the v2 records (eligibility-gated) and the markdown source
|
|
2266
|
+
// bullets to the shared BM25 mirror (runtime/memory-recall.mjs) and cuts
|
|
2267
|
+
// only after scoring. Any import/IO failure degrades to "no context".
|
|
2268
|
+
let engine;
|
|
2269
|
+
let policyMirror;
|
|
2270
|
+
let flags;
|
|
2271
|
+
const runtimeDir = path.join(projectRoot, '.claude', 'ukit', 'runtime');
|
|
2272
|
+
try {
|
|
2273
|
+
engine = await import(pathToFileURL(path.join(runtimeDir, 'memory-recall.mjs')).href);
|
|
2274
|
+
policyMirror = await import(pathToFileURL(path.join(runtimeDir, 'memory-policy.mjs')).href);
|
|
2275
|
+
flags = await import(pathToFileURL(path.join(runtimeDir, 'memory-flags.mjs')).href);
|
|
2276
|
+
} catch {
|
|
2277
|
+
return null;
|
|
2278
|
+
}
|
|
2279
|
+
|
|
2296
2280
|
const projectId = await detectProjectId(projectRoot);
|
|
2297
2281
|
const items = await listMemoryItems(projectRoot);
|
|
2298
|
-
const
|
|
2299
|
-
const
|
|
2282
|
+
const identity = await policyMirror.resolveProjectIdentityMirror(projectRoot).catch(() => null);
|
|
2283
|
+
const memoryConfig = {
|
|
2284
|
+
...config,
|
|
2285
|
+
memoryV2: {
|
|
2286
|
+
eligibility: { stage: 'default' },
|
|
2287
|
+
writer: { stage: 'default' },
|
|
2288
|
+
index: { stage: 'default' },
|
|
2289
|
+
decision: { stage: 'off' },
|
|
2290
|
+
canaryProjects: [],
|
|
2291
|
+
killSwitch: false,
|
|
2292
|
+
...(config?.memoryV2 && typeof config.memoryV2 === 'object' ? config.memoryV2 : {}),
|
|
2293
|
+
},
|
|
2294
|
+
};
|
|
2295
|
+
const eligibleItems = items
|
|
2300
2296
|
.filter((item) => item.type !== 'user')
|
|
2301
2297
|
.filter((item) => (
|
|
2302
2298
|
item.type === 'project'
|
|
2303
2299
|
? (item.content?.id === projectId)
|
|
2304
2300
|
: (item.type === 'session' ? item.content?.projectId === projectId : true)
|
|
2305
|
-
))
|
|
2306
|
-
|
|
2307
|
-
|
|
2308
|
-
|
|
2309
|
-
|
|
2310
|
-
|
|
2311
|
-
|
|
2312
|
-
|
|
2313
|
-
|
|
2314
|
-
.
|
|
2315
|
-
|
|
2316
|
-
|
|
2317
|
-
|
|
2318
|
-
|
|
2319
|
-
|
|
2301
|
+
));
|
|
2302
|
+
const docs = eligibleItems.map((item) => ({
|
|
2303
|
+
id: item.id,
|
|
2304
|
+
type: item.type,
|
|
2305
|
+
text: buildMemorySegments(item).map((segment) => String(segment.text ?? '')).join(' '),
|
|
2306
|
+
created_at: getMemoryTimestamp(item),
|
|
2307
|
+
}));
|
|
2308
|
+
const recordById = new Map();
|
|
2309
|
+
if (flags.resolveMemoryStage(memoryConfig, 'eligibility', { projectId: identity?.projectId ?? null }) !== 'off') {
|
|
2310
|
+
const doc = await readJson(path.join(buildRuntimePaths(projectRoot).memoryRoot, 'v2', 'records.json'), null);
|
|
2311
|
+
const now = Date.now();
|
|
2312
|
+
const eligibleCtx = {
|
|
2313
|
+
projectId: identity?.projectId ?? null,
|
|
2314
|
+
projectAliases: Array.isArray(identity?.aliases) ? identity.aliases : [],
|
|
2315
|
+
includeUser: false,
|
|
2316
|
+
now,
|
|
2317
|
+
};
|
|
2318
|
+
for (const record of Array.isArray(doc?.records) ? doc.records : []) {
|
|
2319
|
+
if (!record || typeof record !== 'object' || record.status !== 'active') continue;
|
|
2320
|
+
if (record.valid_until != null && record.valid_until <= now) continue;
|
|
2321
|
+
if (!policyMirror.eligible(record, eligibleCtx).ok) continue;
|
|
2322
|
+
recordById.set(`record:${record.id}`, record);
|
|
2323
|
+
docs.push({
|
|
2324
|
+
id: `record:${record.id}`,
|
|
2325
|
+
type: record.type,
|
|
2326
|
+
provenance: record.provenance,
|
|
2327
|
+
text: String(record.text ?? ''),
|
|
2328
|
+
created_at: record.created_at ?? 0,
|
|
2329
|
+
});
|
|
2330
|
+
}
|
|
2331
|
+
}
|
|
2332
|
+
const recalled = await engine.recallForHook({
|
|
2333
|
+
projectRoot, query: taskQuery, docs, config: memoryConfig, limit: 2,
|
|
2334
|
+
});
|
|
2335
|
+
const itemById = new Map(eligibleItems.map((item) => [item.id, item]));
|
|
2336
|
+
const rankedItems = recalled.ranked.map((entry) => {
|
|
2337
|
+
if (entry.doc.type === 'markdown') return { id: entry.doc.id, type: 'markdown', doc: entry.doc };
|
|
2338
|
+
const record = recordById.get(entry.doc.id);
|
|
2339
|
+
if (record) return { id: entry.doc.id, type: 'record', record };
|
|
2340
|
+
return itemById.get(entry.doc.id);
|
|
2341
|
+
}).filter(Boolean);
|
|
2320
2342
|
|
|
2321
2343
|
if (rankedItems.length === 0) {
|
|
2322
2344
|
return null;
|
|
2323
2345
|
}
|
|
2324
2346
|
|
|
2347
|
+
const renderItem = (item) => {
|
|
2348
|
+
if (item.type === 'markdown') return engine.renderMarkdownDoc(item.doc, 120);
|
|
2349
|
+
if (item.type === 'record') {
|
|
2350
|
+
const text = String(item.record.text ?? '').trim();
|
|
2351
|
+
return `[${item.record.type ?? 'record'}] ${text.length > 120 ? `${text.slice(0, 117)}...` : text}`;
|
|
2352
|
+
}
|
|
2353
|
+
return buildPreviousContextSnippet(item);
|
|
2354
|
+
};
|
|
2355
|
+
|
|
2325
2356
|
return {
|
|
2326
|
-
line: rankedItems.map(
|
|
2357
|
+
line: rankedItems.map(renderItem).join(' | '),
|
|
2327
2358
|
selectedIds: rankedItems.map((item) => item.id),
|
|
2328
2359
|
fingerprint: buildCompactMachineKey('route-memory-v1', {
|
|
2329
2360
|
taskQuery: normalizeMemoryText(taskQuery),
|