@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.
- package/CHANGELOG.md +17 -90
- package/README.md +1 -0
- package/package.json +8 -1
- package/src/cli/commands/doctor.js +14 -2
- package/src/cli/commands/memory.js +30 -2
- package/src/core/memory/memoryHit.js +2 -0
- package/src/core/memory/mutateMemory.js +9 -0
- package/src/core/memory/projectIdentity.js +9 -2
- package/src/core/memory/recallEngine.js +86 -4
- package/src/core/memory/registryPrune.js +230 -0
- package/src/core/memory/retrieval.js +12 -3
- package/src/core/runtimeConfig.js +1 -1
- package/src/index/queryIndex.js +151 -20
- package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
- package/template_project/.claude/ukit/index/lib/index-core.mjs +149 -19
- package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
- package/template_project/.claude/ukit/index/route-task.mjs +4 -1
- package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
- package/template_project/.claude/ukit/runtime/memory-recall.mjs +86 -4
- package/template_project/.claude/ukit/runtime/memory-validity.mjs +232 -0
- package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
- package/src/core/observability/evaluation/experimentPlan.js +0 -95
- package/src/core/observability/evaluation/perturbation.js +0 -273
- package/src/diagnostics/classifyHang.js +0 -246
- package/src/diagnostics/ompStallSnapshot.js +0 -199
- package/src/render/instructionRenderer.js +0 -290
- package/src/skill/auditSkill.js +0 -140
- package/template_project/instructions/overlays/repo.md +0 -9
|
@@ -161,6 +161,69 @@ export function docTokens(doc) {
|
|
|
161
161
|
return tokenize(text.replace(EPISODE_LABEL_RE, ' '));
|
|
162
162
|
}
|
|
163
163
|
|
|
164
|
+
// Source-validity marker shown next to an item whose anchored file changed or
|
|
165
|
+
// vanished (set on docs as `validity` by memory-validity.mjs).
|
|
166
|
+
export const STALE_MARKER = '[source changed since noted — verify]';
|
|
167
|
+
export const RRF_K = 60;
|
|
168
|
+
export const validityRank = (doc) => (doc?.validity === 'missing' ? 2 : doc?.validity === 'changed' ? 1 : 0);
|
|
169
|
+
const bareId = (id) => String(id ?? '').replace(/^record:/, '');
|
|
170
|
+
|
|
171
|
+
// A doc is superseded when it says so (`superseded_by`) or another candidate
|
|
172
|
+
// lists it in `supersedes`: the superseding doc wins even if the old text
|
|
173
|
+
// scores higher, so the old one never reaches the ranking.
|
|
174
|
+
export function dropSuperseded(docs) {
|
|
175
|
+
const replaced = new Set();
|
|
176
|
+
for (const doc of docs) {
|
|
177
|
+
if (!doc || !Array.isArray(doc.supersedes)) continue;
|
|
178
|
+
for (const id of doc.supersedes) replaced.add(bareId(id));
|
|
179
|
+
}
|
|
180
|
+
return docs.filter((doc) => doc != null && !doc.superseded_by && !replaced.has(bareId(doc.id)));
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
// Reciprocal rank fusion over ordered id lists (best first); lists are lanes.
|
|
184
|
+
// Score = sum weight/(k + rank). Ties break on id, never on a timestamp.
|
|
185
|
+
export function fuseRanked(lanes, { k = RRF_K, weights = [] } = {}) {
|
|
186
|
+
const scores = new Map();
|
|
187
|
+
(Array.isArray(lanes) ? lanes : []).forEach((lane, idx) => {
|
|
188
|
+
const weight = Number.isFinite(weights[idx]) ? weights[idx] : 1;
|
|
189
|
+
const seen = new Set();
|
|
190
|
+
let rank = 0;
|
|
191
|
+
for (const id of lane ?? []) {
|
|
192
|
+
if (seen.has(id)) continue;
|
|
193
|
+
seen.add(id);
|
|
194
|
+
rank += 1;
|
|
195
|
+
scores.set(id, (scores.get(id) ?? 0) + weight / (k + rank));
|
|
196
|
+
}
|
|
197
|
+
});
|
|
198
|
+
return [...scores].map(([id, score]) => ({ id, score }))
|
|
199
|
+
.sort((a, b) => b.score - a.score || String(a.id).localeCompare(String(b.id)));
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
// Validity as one more fusion lane (3.5.3). `changed` (an anchored source was
|
|
203
|
+
// edited) is always labelled but only mildly demoted: lane 1 is the incoming
|
|
204
|
+
// relevance order, lane 2 the same items valid-first, fused with a small weight,
|
|
205
|
+
// so a clearly more relevant changed note still beats a weakly relevant valid
|
|
206
|
+
// one. `missing` (file gone) is labelled and ranked last. Nothing is dropped.
|
|
207
|
+
// Measurement knob UKIT_MEMORY_VALIDITY_RANK: `hard` (every changed below every
|
|
208
|
+
// valid), `label` (marker only, no rank change), `mild[:<weight>]` (default).
|
|
209
|
+
export const VALIDITY_WEIGHT = 0.35;
|
|
210
|
+
const pad = (i) => String(i).padStart(6, '0');
|
|
211
|
+
export function demoteByValidity(items, docOf = (item) => item?.doc ?? item) {
|
|
212
|
+
const list = Array.isArray(items) ? [...items] : [];
|
|
213
|
+
if (!list.some((item) => validityRank(docOf(item)) > 0)) return list;
|
|
214
|
+
const [mode, raw] = String(process.env.UKIT_MEMORY_VALIDITY_RANK ?? 'mild').split(':');
|
|
215
|
+
if (mode === 'label') return list;
|
|
216
|
+
const rank = (item) => validityRank(docOf(item));
|
|
217
|
+
if (mode === 'hard') return list.sort((a, b) => rank(a) - rank(b));
|
|
218
|
+
const weight = Number.isFinite(Number(raw)) && raw !== undefined && raw !== '' ? Number(raw) : VALIDITY_WEIGHT;
|
|
219
|
+
const byIndex = list.map((item, i) => ({ item, i }));
|
|
220
|
+
const lane1 = byIndex.map((e) => pad(e.i));
|
|
221
|
+
const lane2 = [...byIndex].sort((a, b) => rank(a.item) - rank(b.item)).map((e) => pad(e.i));
|
|
222
|
+
return fuseRanked([lane1, lane2], { weights: [1, weight] })
|
|
223
|
+
.map((e) => list[Number(e.id)])
|
|
224
|
+
.sort((a, b) => Number(rank(a) === 2) - Number(rank(b) === 2));
|
|
225
|
+
}
|
|
226
|
+
|
|
164
227
|
function idf(totalDocs, docFreq) {
|
|
165
228
|
return Math.log(1 + (totalDocs - docFreq + 0.5) / (docFreq + 0.5));
|
|
166
229
|
}
|
|
@@ -176,6 +239,8 @@ export function rankDocs(docs, query, { limit = 10 } = {}) {
|
|
|
176
239
|
ranked: [], candidateCount: 0, queryTokenCount: queryTokens.length, topScore: 0, abstained: true,
|
|
177
240
|
};
|
|
178
241
|
if (!Array.isArray(docs) || docs.length === 0 || queryTokens.length === 0) return empty;
|
|
242
|
+
docs = dropSuperseded(docs);
|
|
243
|
+
if (docs.length === 0) return empty;
|
|
179
244
|
|
|
180
245
|
const stats = [];
|
|
181
246
|
const docFreq = new Map();
|
|
@@ -222,7 +287,10 @@ export function rankDocs(docs, query, { limit = 10 } = {}) {
|
|
|
222
287
|
scored.sort((a, b) => b.score - a.score
|
|
223
288
|
|| String(a.doc.id ?? '').localeCompare(String(b.doc.id ?? '')));
|
|
224
289
|
const top = scored.length > 0 ? scored[0].score : 0;
|
|
225
|
-
|
|
290
|
+
// Temporal lane (3.5.3): validity is one more fusion lane over the docs that
|
|
291
|
+
// cleared the floor and cutoff (see demoteByValidity); nothing is dropped.
|
|
292
|
+
const ranked = demoteByValidity(scored.filter((entry) => entry.score >= RELATIVE_CUTOFF * top), (entry) => entry.doc)
|
|
293
|
+
.slice(0, limit);
|
|
226
294
|
return {
|
|
227
295
|
ranked,
|
|
228
296
|
candidateCount,
|
|
@@ -359,16 +427,30 @@ const SNIPPET_CHARS = 160;
|
|
|
359
427
|
|
|
360
428
|
// Shared hook lane: score ALL eligible docs (no newest-N pre-filter) together
|
|
361
429
|
// with the markdown source bullets, then cut. Async I/O only; never throws.
|
|
362
|
-
|
|
430
|
+
// `annotate(docs) -> Promise<docs>` is an optional caller-injected async step
|
|
431
|
+
// (source validity, 3.5.3); this file stays free of non-node imports. A failing
|
|
432
|
+
// or slow-to-throw annotate never affects recall.
|
|
433
|
+
export async function recallForHook({
|
|
434
|
+
projectRoot, query, docs = [], config = null, limit = 2, annotate = null,
|
|
435
|
+
} = {}) {
|
|
363
436
|
let markdown = [];
|
|
364
437
|
try {
|
|
365
438
|
markdown = await loadMarkdownDocs(projectRoot, normalizeMemorySources(config));
|
|
366
439
|
} catch {
|
|
367
440
|
markdown = [];
|
|
368
441
|
}
|
|
442
|
+
let pool = [...docs, ...markdown];
|
|
443
|
+
if (typeof annotate === 'function') {
|
|
444
|
+
try {
|
|
445
|
+
const annotated = await annotate(pool);
|
|
446
|
+
if (Array.isArray(annotated) && annotated.length === pool.length) pool = annotated;
|
|
447
|
+
} catch {
|
|
448
|
+
// keep the unannotated pool
|
|
449
|
+
}
|
|
450
|
+
}
|
|
369
451
|
let result;
|
|
370
452
|
try {
|
|
371
|
-
result = rankDocs(
|
|
453
|
+
result = rankDocs(pool, query, { limit });
|
|
372
454
|
} catch {
|
|
373
455
|
result = rankDocs([], '', { limit });
|
|
374
456
|
}
|
|
@@ -419,5 +501,5 @@ async function emitRecallTelemetry(projectRoot, config, result) {
|
|
|
419
501
|
export function renderMarkdownDoc(doc, maxChars = SNIPPET_CHARS) {
|
|
420
502
|
const text = String(doc?.text ?? '');
|
|
421
503
|
const body = text.length > maxChars ? `${text.slice(0, maxChars - 3)}...` : text;
|
|
422
|
-
return `[${doc?.provenance ?? 'markdown'}] ${body}`;
|
|
504
|
+
return `[${doc?.provenance ?? 'markdown'}] ${body}${doc?.validity ? ` ${STALE_MARKER}` : ''}`;
|
|
423
505
|
}
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
// memory-validity.mjs (3.5.3) - source anchors for memory items. A note that names
|
|
2
|
+
// an existing file is anchored to that file's state (sha1 + size + mtime, plus the
|
|
3
|
+
// git commit when known) in the sidecar .ukit/storage/memory/v2/anchors.json, so
|
|
4
|
+
// docs/MEMORY.md and records are never rewritten. Standalone ESM, async fs only.
|
|
5
|
+
// Reads (withValidity) are hook-safe; capture is CLI/write-time only.
|
|
6
|
+
// Env switches (read per call; unset = on):
|
|
7
|
+
// UKIT_MEMORY_VALIDITY=0 kill switch: no anchors, no marker, no rank change.
|
|
8
|
+
// UKIT_MEMORY_VALIDITY_RANK=<mode> measurement knob read by demoteByValidity in
|
|
9
|
+
// memory-recall.mjs: `mild[:<weight>]` (default), `label` (marker only), `hard`
|
|
10
|
+
// (changed below valid; measured worse, 36/38 vs 37/38). Unknown values mean mild.
|
|
11
|
+
// Not a user setting: used by scripts/bench/memory-gold-validity.mjs and tests.
|
|
12
|
+
import crypto from 'node:crypto';
|
|
13
|
+
import { execFile } from 'node:child_process';
|
|
14
|
+
import fsp from 'node:fs/promises';
|
|
15
|
+
import path from 'node:path';
|
|
16
|
+
|
|
17
|
+
import { STALE_MARKER, validityRank } from './memory-recall.mjs';
|
|
18
|
+
|
|
19
|
+
export { STALE_MARKER, validityRank };
|
|
20
|
+
const MAX_FILES = 6;
|
|
21
|
+
const MAX_HASH_BYTES = 2 * 1024 * 1024;
|
|
22
|
+
const MAX_STORE_BYTES = 1024 * 1024;
|
|
23
|
+
const MAX_ENTRIES = 2000;
|
|
24
|
+
const KNOWN_ROOTS = new Set(['src', 'tests', 'test', 'docs', 'scripts', 'lib', 'app', 'template_project', 'packages', 'bin']);
|
|
25
|
+
const EXT_RE = /\.[A-Za-z][A-Za-z0-9]{0,7}$/;
|
|
26
|
+
|
|
27
|
+
export function normalizePath(raw, { needSlash = true } = {}) {
|
|
28
|
+
let t = String(raw ?? '').trim().replace(/`/g, '').replace(/\\/g, '/');
|
|
29
|
+
t = t.replace(/^(\.\/)+/, '').replace(/:\d+(?::\d+)?$/, '').replace(/[.,;:!?)\]}>"'*]+$/, '').replace(/^[("'[{<]+/, '');
|
|
30
|
+
t = t.replace(/:\d+(?::\d+)?$/, '');
|
|
31
|
+
if (!t || t.includes('://') || t.startsWith('/') || /^[A-Za-z]:/.test(t) || t.startsWith('~')) return null;
|
|
32
|
+
const segs = t.split('/');
|
|
33
|
+
if (segs.some((s) => s === '..' || s === '')) {
|
|
34
|
+
if (!(t.endsWith('/') && segs.slice(0, -1).every((s) => s && s !== '..'))) return null;
|
|
35
|
+
segs.pop();
|
|
36
|
+
}
|
|
37
|
+
const clean = segs.join('/');
|
|
38
|
+
const last = segs[segs.length - 1];
|
|
39
|
+
if (EXT_RE.test(last) && last.length > 2) return needSlash && segs.length < 2 ? null : clean;
|
|
40
|
+
if (segs.length >= 2 && (t.endsWith('/') || KNOWN_ROOTS.has(segs[0]))) return clean;
|
|
41
|
+
return null;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
export const isFilePath = (p) => EXT_RE.test(String(p).split('/').pop());
|
|
45
|
+
|
|
46
|
+
export function extractAnchors(doc) {
|
|
47
|
+
const out = new Set();
|
|
48
|
+
for (const tok of String(doc?.text ?? '').split(/\s+/)) {
|
|
49
|
+
const hit = /[/\\]/.test(tok) ? normalizePath(tok) : null;
|
|
50
|
+
if (hit) out.add(hit);
|
|
51
|
+
}
|
|
52
|
+
for (const ev of Array.isArray(doc?.evidence) ? doc.evidence : []) {
|
|
53
|
+
if (typeof ev === 'string') { const p = normalizePath(ev, { needSlash: false }); if (p) out.add(p); continue; }
|
|
54
|
+
if (ev?.kind && ev.kind !== 'file') continue;
|
|
55
|
+
const p = normalizePath(ev?.locator, { needSlash: false });
|
|
56
|
+
if (p) out.add(p);
|
|
57
|
+
}
|
|
58
|
+
return [...out].sort();
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
// Episodes and exec-ledger stubs describe a session, not a claim about a file.
|
|
62
|
+
const anchorable = (doc) => doc && doc.type !== 'episode' && doc.provenance !== 'exec-ledger';
|
|
63
|
+
|
|
64
|
+
// Stable identity: records by id, markdown bullets by path + text hash (a line
|
|
65
|
+
// shift keeps the anchor; an edited bullet is a new, unanchored item).
|
|
66
|
+
export function anchorKey(doc) {
|
|
67
|
+
if (doc?.type === 'markdown') {
|
|
68
|
+
const rel = String(doc.provenance ?? '').replace(/:\d+$/, '');
|
|
69
|
+
return `md:${rel}:${crypto.createHash('sha1').update(String(doc.text ?? '')).digest('hex').slice(0, 12)}`;
|
|
70
|
+
}
|
|
71
|
+
return `rec:${String(doc?.id ?? '').replace(/^record:/, '')}`;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
const storePath = (root) => path.join(root, '.ukit', 'storage', 'memory', 'v2', 'anchors.json');
|
|
75
|
+
|
|
76
|
+
export async function loadAnchors(root) {
|
|
77
|
+
try {
|
|
78
|
+
const file = storePath(root);
|
|
79
|
+
const st = await fsp.stat(file);
|
|
80
|
+
if (!st.isFile() || st.size > MAX_STORE_BYTES) return { version: 1, anchors: {} };
|
|
81
|
+
const doc = JSON.parse(await fsp.readFile(file, 'utf8'));
|
|
82
|
+
return { version: 1, anchors: doc && typeof doc.anchors === 'object' && doc.anchors ? doc.anchors : {} };
|
|
83
|
+
} catch {
|
|
84
|
+
return { version: 1, anchors: {} };
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
async function saveAnchors(root, store) {
|
|
89
|
+
const keys = Object.keys(store.anchors);
|
|
90
|
+
if (keys.length > MAX_ENTRIES) {
|
|
91
|
+
keys.sort((a, b) => (store.anchors[a].at ?? 0) - (store.anchors[b].at ?? 0));
|
|
92
|
+
for (const k of keys.slice(0, keys.length - MAX_ENTRIES)) delete store.anchors[k];
|
|
93
|
+
}
|
|
94
|
+
const file = storePath(root);
|
|
95
|
+
await fsp.mkdir(path.dirname(file), { recursive: true });
|
|
96
|
+
const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
|
|
97
|
+
await fsp.writeFile(tmp, `${JSON.stringify(store)}\n`, 'utf8');
|
|
98
|
+
await fsp.rename(tmp, file);
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
async function fileState(root, rel) {
|
|
102
|
+
const st = await fsp.stat(path.resolve(root, rel));
|
|
103
|
+
if (!st.isFile()) throw Object.assign(new Error('not a file'), { code: 'ENOENT' });
|
|
104
|
+
const sha1 = st.size <= MAX_HASH_BYTES
|
|
105
|
+
? crypto.createHash('sha1').update(await fsp.readFile(path.resolve(root, rel))).digest('hex') : null;
|
|
106
|
+
return { sha1, size: st.size, mtimeMs: st.mtimeMs };
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
function headCommit(root) {
|
|
110
|
+
return new Promise((resolve) => {
|
|
111
|
+
try {
|
|
112
|
+
execFile('git', ['rev-parse', 'HEAD'], { cwd: root, timeout: 1500 }, (err, out) => {
|
|
113
|
+
const sha = String(out ?? '').trim();
|
|
114
|
+
resolve(!err && /^[0-9a-f]{40}$/i.test(sha) ? sha.toLowerCase() : null);
|
|
115
|
+
});
|
|
116
|
+
} catch { resolve(null); }
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
async function buildEntry(root, doc, commit) {
|
|
121
|
+
const files = {};
|
|
122
|
+
for (const rel of extractAnchors(doc).filter(isFilePath).slice(0, MAX_FILES)) {
|
|
123
|
+
try { files[rel] = await fileState(root, rel); } catch { /* names a path that does not exist: not anchored */ }
|
|
124
|
+
}
|
|
125
|
+
return Object.keys(files).length ? { at: Date.now(), commit: commit ?? null, files } : null;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
// 'valid' | 'changed' | 'missing'. A deleted file outranks a changed one.
|
|
129
|
+
// `memo` is per withValidity call: each distinct file is stat-ed / hashed once
|
|
130
|
+
// however many notes name it.
|
|
131
|
+
const memoStat = (root, rel, memo) => {
|
|
132
|
+
if (!memo.stat.has(rel)) {
|
|
133
|
+
memo.stat.set(rel, fsp.stat(path.resolve(root, rel)).then((st) => ({ st }), (err) => ({ err })));
|
|
134
|
+
}
|
|
135
|
+
return memo.stat.get(rel);
|
|
136
|
+
};
|
|
137
|
+
const memoSha1 = (root, rel, memo) => {
|
|
138
|
+
// The caller already stat-ed (and size-matched) the file: only read it here.
|
|
139
|
+
if (!memo.sha1.has(rel)) {
|
|
140
|
+
memo.sha1.set(rel, fsp.readFile(path.resolve(root, rel))
|
|
141
|
+
.then((buf) => crypto.createHash('sha1').update(buf).digest('hex'), () => undefined));
|
|
142
|
+
}
|
|
143
|
+
return memo.sha1.get(rel);
|
|
144
|
+
};
|
|
145
|
+
|
|
146
|
+
async function evaluateEntry(root, entry, memo = { stat: new Map(), sha1: new Map() }) {
|
|
147
|
+
let changed = false;
|
|
148
|
+
for (const [rel, was] of Object.entries(entry?.files ?? {}).slice(0, MAX_FILES)) {
|
|
149
|
+
const { st, err } = await memoStat(root, rel, memo);
|
|
150
|
+
if (err) {
|
|
151
|
+
if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return 'missing';
|
|
152
|
+
continue;
|
|
153
|
+
}
|
|
154
|
+
if (!st.isFile()) return 'missing';
|
|
155
|
+
if (st.size === was.size && st.mtimeMs === was.mtimeMs) continue;
|
|
156
|
+
// A different size already proves a different content: no read, no hash.
|
|
157
|
+
if (!was.sha1 || st.size !== was.size) { changed = true; continue; }
|
|
158
|
+
const sha1 = await memoSha1(root, rel, memo);
|
|
159
|
+
if (sha1 !== undefined && sha1 !== was.sha1) changed = true; // unreadable (undefined): do not claim a change
|
|
160
|
+
}
|
|
161
|
+
return changed ? 'changed' : 'valid';
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
const FILE_WORK_CONCURRENCY = 4;
|
|
165
|
+
|
|
166
|
+
async function mapLimited(items, limit, fn) {
|
|
167
|
+
const out = new Array(items.length);
|
|
168
|
+
let next = 0;
|
|
169
|
+
const worker = async () => {
|
|
170
|
+
while (next < items.length) { const i = next++; out[i] = await fn(items[i]); }
|
|
171
|
+
};
|
|
172
|
+
await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
|
|
173
|
+
return out;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
// Adds `validity: 'changed'|'missing'` to docs whose anchored source moved on;
|
|
177
|
+
// every other doc is returned untouched (same object). `capture` also anchors
|
|
178
|
+
// docs that have no anchor yet (CLI/write time only, never inside a hook).
|
|
179
|
+
export async function withValidity(root, docs, { capture = false } = {}) {
|
|
180
|
+
const list = Array.isArray(docs) ? docs : [];
|
|
181
|
+
if (!root || process.env.UKIT_MEMORY_VALIDITY === '0') return list;
|
|
182
|
+
try {
|
|
183
|
+
const store = await loadAnchors(root);
|
|
184
|
+
let dirty = false;
|
|
185
|
+
let commit;
|
|
186
|
+
const memo = { stat: new Map(), sha1: new Map() };
|
|
187
|
+
const out = await mapLimited(list, FILE_WORK_CONCURRENCY, async (doc) => {
|
|
188
|
+
if (!anchorable(doc)) return doc;
|
|
189
|
+
const key = anchorKey(doc);
|
|
190
|
+
const entry = store.anchors[key];
|
|
191
|
+
if (entry) {
|
|
192
|
+
const verdict = await evaluateEntry(root, entry, memo);
|
|
193
|
+
return verdict === 'valid' ? doc : { ...doc, validity: verdict };
|
|
194
|
+
}
|
|
195
|
+
if (capture && extractAnchors(doc).some(isFilePath)) {
|
|
196
|
+
commit ??= headCommit(root);
|
|
197
|
+
const built = await buildEntry(root, doc, await commit);
|
|
198
|
+
if (built) { store.anchors[key] = built; dirty = true; }
|
|
199
|
+
}
|
|
200
|
+
return doc;
|
|
201
|
+
});
|
|
202
|
+
if (dirty) await saveAnchors(root, store);
|
|
203
|
+
return out;
|
|
204
|
+
} catch {
|
|
205
|
+
return list;
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
// Write-time / `ukit memory v2 confirm`: (re)anchor docs to the files' state now.
|
|
210
|
+
export async function captureAnchors(root, docs) {
|
|
211
|
+
try {
|
|
212
|
+
if (!root || process.env.UKIT_MEMORY_VALIDITY === '0') return 0;
|
|
213
|
+
// No git spawn / store read unless a doc actually names a file.
|
|
214
|
+
const todo = (Array.isArray(docs) ? docs : []).filter((d) => anchorable(d) && extractAnchors(d).some(isFilePath));
|
|
215
|
+
if (todo.length === 0) return 0;
|
|
216
|
+
const store = await loadAnchors(root);
|
|
217
|
+
const commit = await headCommit(root);
|
|
218
|
+
let n = 0;
|
|
219
|
+
for (const doc of todo) {
|
|
220
|
+
const built = await buildEntry(root, doc, commit);
|
|
221
|
+
if (!built) continue;
|
|
222
|
+
store.anchors[anchorKey(doc)] = built;
|
|
223
|
+
n += 1;
|
|
224
|
+
}
|
|
225
|
+
if (n) await saveAnchors(root, store);
|
|
226
|
+
return n;
|
|
227
|
+
} catch {
|
|
228
|
+
return 0;
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
export const staleSuffix = (doc) => (doc?.validity ? ` ${STALE_MARKER}` : '');
|
|
@@ -31,7 +31,7 @@ import {
|
|
|
31
31
|
import { resolveRecordFreshness } from './memory-freshness.mjs';
|
|
32
32
|
import { resolveMemoryStage } from './memory-flags.mjs';
|
|
33
33
|
import { recallForHook, renderMarkdownDoc } from './memory-recall.mjs';
|
|
34
|
-
|
|
34
|
+
import { withValidity, staleSuffix } from './memory-validity.mjs';
|
|
35
35
|
// Hook-context self-deadline (2.4.1 orphan-leak class): the reinject-context hook passes
|
|
36
36
|
// UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the hook
|
|
37
37
|
// budget. Non-hook usage never sets it and is never self-killed.
|
|
@@ -1253,7 +1253,9 @@ async function buildPreviousContextLines(projectRoot, state, config) {
|
|
|
1253
1253
|
});
|
|
1254
1254
|
const recalled = await recallForHook({
|
|
1255
1255
|
projectRoot, query: taskQuery, docs, config, limit: 2,
|
|
1256
|
+
annotate: (pool) => withValidity(projectRoot, pool),
|
|
1256
1257
|
});
|
|
1258
|
+
const validityById = new Map(recalled.ranked.map((entry) => [entry.doc.id, entry.doc]));
|
|
1257
1259
|
const rankedItems = recalled.ranked.map((entry) => (entry.doc.type === 'markdown'
|
|
1258
1260
|
? { id: entry.doc.id, type: 'markdown', doc: entry.doc }
|
|
1259
1261
|
: itemById.get(entry.doc.id))).filter(Boolean);
|
|
@@ -1273,7 +1275,7 @@ async function buildPreviousContextLines(projectRoot, state, config) {
|
|
|
1273
1275
|
|
|
1274
1276
|
return [`- Previous context: ${rankedItems.map((item) => (item.type === 'markdown'
|
|
1275
1277
|
? renderMarkdownDoc(item.doc, 120)
|
|
1276
|
-
: buildPreviousContextSnippet(item, freshnessById.get(item.id)))).join(' | ')}`];
|
|
1278
|
+
: `${buildPreviousContextSnippet(item, freshnessById.get(item.id))}${staleSuffix(validityById.get(item.id))}`)).join(' | ')}`];
|
|
1277
1279
|
}
|
|
1278
1280
|
|
|
1279
1281
|
// BUG-C23-13: only run main() on direct CLI invocation — an unguarded bottom
|
|
@@ -1,95 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* experimentPlan — pure staged controlled-experiment planner (GAP-c).
|
|
3
|
-
*
|
|
4
|
-
* Maps a KB optimization entry + a `computeGateComparison` GateComparison to
|
|
5
|
-
* staged rollout ACTIONS over the seam ladder. The planner EMITS intent only:
|
|
6
|
-
* it never mutates config, never calls killSwitch/resolveSeamConfig, and never
|
|
7
|
-
* touches fs. Execution (if any) is a separate operator-owned act.
|
|
8
|
-
*
|
|
9
|
-
* Rules:
|
|
10
|
-
* - gate must be a real GateComparison (verdict in pass|non-inferior|unknown);
|
|
11
|
-
* anything else → TypeError (a fabricated gate can never plan a promotion).
|
|
12
|
-
* - abort flag (operator rollback_criterion met) → kill 'abort-requested'.
|
|
13
|
-
* - gate.forbiddenFailures > 0 → kill 'forbidden-failures' prepended.
|
|
14
|
-
* - verdict !== 'pass' → hold (reason = verdict). 'non-inferior' means the
|
|
15
|
-
* variant FAILED the pre-registered gate.
|
|
16
|
-
* - verdict 'pass' + non-empty controlled_rollout.evidence_refs → one promote
|
|
17
|
-
* action per seam in stage-rank order (shadow → canary → default), each
|
|
18
|
-
* carrying requires_evidence_refs:true. Missing refs → hold
|
|
19
|
-
* 'missing-controlled-rollout-evidence': promotion never fires on the
|
|
20
|
-
* quality signal alone.
|
|
21
|
-
*/
|
|
22
|
-
|
|
23
|
-
import { SEAM_MIN_STAGE } from '../rollout.js';
|
|
24
|
-
|
|
25
|
-
export const ROLLOUT_ACTIONS = Object.freeze(['promote', 'hold', 'kill']);
|
|
26
|
-
|
|
27
|
-
const GATE_VERDICTS = new Set(['pass', 'non-inferior', 'unknown']);
|
|
28
|
-
|
|
29
|
-
const STAGE_RANK = { shadow: 1, canary: 2, default: 3 };
|
|
30
|
-
|
|
31
|
-
function isPlainObject(value) {
|
|
32
|
-
return value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
function isNonEmptyStringList(value) {
|
|
36
|
-
return (
|
|
37
|
-
Array.isArray(value) &&
|
|
38
|
-
value.length > 0 &&
|
|
39
|
-
value.every((v) => typeof v === 'string' && v.length > 0)
|
|
40
|
-
);
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
/**
|
|
44
|
-
* @param {{optimization?: object, gate?: object, abort?: boolean}} input
|
|
45
|
-
* @returns {{actions: object[]}} frozen action list
|
|
46
|
-
*/
|
|
47
|
-
export function planControlledRollout(input = {}) {
|
|
48
|
-
const { optimization, gate, abort } = isPlainObject(input) ? input : {};
|
|
49
|
-
|
|
50
|
-
if (!isPlainObject(gate) || !GATE_VERDICTS.has(gate.verdict)) {
|
|
51
|
-
throw new TypeError(
|
|
52
|
-
'experimentPlan: gate must be a GateComparison with verdict in pass|non-inferior|unknown',
|
|
53
|
-
);
|
|
54
|
-
}
|
|
55
|
-
|
|
56
|
-
const actions = [];
|
|
57
|
-
|
|
58
|
-
if (abort === true) {
|
|
59
|
-
actions.push({ type: 'kill', reason: 'abort-requested' });
|
|
60
|
-
}
|
|
61
|
-
if (gate.forbiddenFailures > 0) {
|
|
62
|
-
actions.push({ type: 'kill', reason: 'forbidden-failures' });
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
if (gate.verdict !== 'pass') {
|
|
66
|
-
actions.push({ type: 'hold', reason: gate.verdict });
|
|
67
|
-
return { actions: Object.freeze(actions) };
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
if (actions.length > 0) {
|
|
71
|
-
// pass + forbiddenFailures is unreachable from real computeGateComparison
|
|
72
|
-
// output (forbidden → non-inferior hard gate); defend the shape anyway.
|
|
73
|
-
return { actions: Object.freeze(actions) };
|
|
74
|
-
}
|
|
75
|
-
|
|
76
|
-
const rollout = isPlainObject(optimization) ? optimization.controlled_rollout : undefined;
|
|
77
|
-
const evidenceRefs = isPlainObject(rollout) ? rollout.evidence_refs : undefined;
|
|
78
|
-
if (!isNonEmptyStringList(evidenceRefs)) {
|
|
79
|
-
return {
|
|
80
|
-
actions: Object.freeze([{ type: 'hold', reason: 'missing-controlled-rollout-evidence' }]),
|
|
81
|
-
};
|
|
82
|
-
}
|
|
83
|
-
|
|
84
|
-
// Order from the shared seam contract (read-only): each seam promotes at the
|
|
85
|
-
// stage it unlocks, lowest stage rank first.
|
|
86
|
-
const seams = Object.entries(SEAM_MIN_STAGE)
|
|
87
|
-
.map(([seam, stage]) => ({ seam, stage }))
|
|
88
|
-
.sort((a, b) => STAGE_RANK[a.stage] - STAGE_RANK[b.stage] || a.seam.localeCompare(b.seam));
|
|
89
|
-
|
|
90
|
-
for (const { seam, stage } of seams) {
|
|
91
|
-
actions.push({ type: 'promote', seam, stage, requires_evidence_refs: true });
|
|
92
|
-
}
|
|
93
|
-
|
|
94
|
-
return { actions: Object.freeze(actions) };
|
|
95
|
-
}
|