@ngockhoale/ukit 3.5.2 → 3.5.4

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 (75) hide show
  1. package/CHANGELOG.md +38 -90
  2. package/README.md +1 -0
  3. package/manifests/documentation.yaml +12 -1
  4. package/manifests/platform.full.yaml +12 -0
  5. package/package.json +34 -1
  6. package/src/cli/commands/doctor.js +55 -2
  7. package/src/cli/commands/indexTools.js +10 -4
  8. package/src/cli/commands/memory.js +107 -8
  9. package/src/core/memory/episodes.js +106 -7
  10. package/src/core/memory/memoryCheck.js +241 -0
  11. package/src/core/memory/memoryCheckRun.js +27 -0
  12. package/src/core/memory/memoryHit.js +2 -0
  13. package/src/core/memory/mutateMemory.js +46 -1
  14. package/src/core/memory/observations.js +192 -0
  15. package/src/core/memory/projectIdentity.js +9 -2
  16. package/src/core/memory/recallEngine.js +204 -9
  17. package/src/core/memory/records.js +23 -0
  18. package/src/core/memory/registryPrune.js +230 -0
  19. package/src/core/memory/retrieval.js +12 -3
  20. package/src/core/memory/writeGate.js +137 -0
  21. package/src/core/runtimeConfig.js +12 -2
  22. package/src/index/buildIndex.js +26 -0
  23. package/src/index/paths.js +3 -1
  24. package/src/index/queryIndex.js +372 -26
  25. package/src/index/resolveContext.js +1 -1
  26. package/template_project/.claude/hooks/edit-hint.mjs +64 -17
  27. package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
  28. package/template_project/.claude/hooks/session-episode.sh +9 -4
  29. package/template_project/.claude/settings.json +2 -2
  30. package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
  31. package/template_project/.claude/ukit/index/lib/index-core.mjs +400 -27
  32. package/template_project/.claude/ukit/index/query-index.mjs +14 -3
  33. package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
  34. package/template_project/.claude/ukit/index/route-task.mjs +8 -2
  35. package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
  36. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
  37. package/template_project/.claude/ukit/runtime/memory-recall.mjs +204 -9
  38. package/template_project/.claude/ukit/runtime/memory-validity.mjs +259 -0
  39. package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
  40. package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
  41. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  42. package/template_project/ukit/storage/config.json +4 -2
  43. package/src/core/agentRuntime/completionGate.js +0 -179
  44. package/src/core/agentRuntime/context.js +0 -571
  45. package/src/core/agentRuntime/qualityComparison.js +0 -112
  46. package/src/core/agentRuntime/resourcePolicy.js +0 -78
  47. package/src/core/agentRuntime/runtimeSupport.js +0 -255
  48. package/src/core/codeintel/manifest.js +0 -176
  49. package/src/core/experiments/deliberation.js +0 -327
  50. package/src/core/experiments/dynamicWorkflow.js +0 -507
  51. package/src/core/handoffDocValidator.js +0 -154
  52. package/src/core/memory/deltaOverlays.js +0 -493
  53. package/src/core/memory/learningCandidates.js +0 -347
  54. package/src/core/observability/emit/sessionBoot.js +0 -407
  55. package/src/core/observability/evaluation/experimentPlan.js +0 -95
  56. package/src/core/observability/evaluation/perturbation.js +0 -273
  57. package/src/core/observability/evaluation/replay.js +0 -149
  58. package/src/core/observability/evaluation/scorecard.js +0 -465
  59. package/src/core/observability/schema/compatibility.js +0 -180
  60. package/src/core/observability/support/renderer.js +0 -130
  61. package/src/core/reviewPanelAggregate.js +0 -204
  62. package/src/core/taskBudgetValidator.js +0 -251
  63. package/src/core/taskProgressGuard.js +0 -227
  64. package/src/decision/reviewVerdict.js +0 -339
  65. package/src/decision/runtimeFilter.js +0 -150
  66. package/src/decision/runtimeScheduler.js +0 -239
  67. package/src/diagnostics/classifyHang.js +0 -246
  68. package/src/diagnostics/ompStallSnapshot.js +0 -199
  69. package/src/index/contextPack.js +0 -285
  70. package/src/index/impactContext.js +0 -360
  71. package/src/index/reviewPolicy.js +0 -368
  72. package/src/index/sensitivePath.js +0 -21
  73. package/src/render/instructionRenderer.js +0 -290
  74. package/src/skill/auditSkill.js +0 -140
  75. package/template_project/instructions/overlays/repo.md +0 -9
@@ -0,0 +1,27 @@
1
+ // memoryCheckRun.js — `ukit memory check [--json] [--file <rel>]...` runner (3.5.4).
2
+ // Binds the shared checker (memoryCheck.js) to the real engine, secret scanner and config.
3
+ import { loadRuntimeConfig } from '../runtimeConfig.js';
4
+ import { loadSensitiveAllowlist, scanText } from '../sensitiveValueScanner.js';
5
+ import { checkMemorySources } from './memoryCheck.js';
6
+ import { expandMemorySources, normalizeMemorySources, parseMarkdownBullets, tokenize } from './recallEngine.js';
7
+
8
+ export async function runMemoryCheck(projectRoot, args = []) {
9
+ const json = args.includes('--json');
10
+ const files = [];
11
+ for (let i = 0; i < args.length; i += 1) if (args[i] === '--file' && args[i + 1]) files.push(args[i + 1]);
12
+ const config = await loadRuntimeConfig(projectRoot).catch(() => ({}));
13
+ const allowlistHashes = loadSensitiveAllowlist(config);
14
+ const res = await checkMemorySources(projectRoot, {
15
+ sources: await expandMemorySources(projectRoot, normalizeMemorySources(config)),
16
+ engine: { tokenize, parseMarkdownBullets },
17
+ scan: (text) => scanText(text, { allowlistHashes }),
18
+ files: files.length > 0 ? files : null,
19
+ });
20
+ if (json) return { ok: res.ok, output: JSON.stringify(res, null, 2) };
21
+ const rows = [
22
+ `[UKit] memory check: ${res.ok ? 'OK' : 'VIOLATIONS'} — ${res.stats.files} file(s), ${res.stats.bullets} note(s), core ${res.stats.coreLines} lines / ${res.stats.coreBytes} bytes`,
23
+ ...res.violations.map((v) => ` violation ${v.file}:${v.line} ${v.code} — ${v.message}`),
24
+ ];
25
+ if (res.warnings.length > 0) rows.push(` ${res.warnings.length} warning(s) (notes naming no existing file); \`--json\` lists them`);
26
+ return { ok: res.ok, output: rows.join('\n') };
27
+ }
@@ -67,6 +67,7 @@ export function buildMemoryHit(record, { freshness = null, score = 0, reasons =
67
67
  summary: snippet,
68
68
  source: record?.type ?? null,
69
69
  timestamp: createdAt,
70
+ ...(record?.validity ? { validity: record.validity } : {}),
70
71
  };
71
72
  }
72
73
 
@@ -115,6 +116,7 @@ export function buildMarkdownHit(doc, { score = 0 } = {}) {
115
116
  source: 'markdown',
116
117
  timestamp: 0,
117
118
  provenance: doc.provenance,
119
+ ...(doc.validity ? { validity: doc.validity } : {}),
118
120
  };
119
121
  }
120
122
 
@@ -26,8 +26,10 @@ import {
26
26
  import { createRecord, normalizeRecord } from './records.js';
27
27
  import { guardWritePayload, redactWritePayload } from './writeGuard.js';
28
28
  import { classifyWrite, mergeEvidence, REVIEW_QUEUE_MAX } from './writeClassification.js';
29
+ import { checkRecordWrite } from './writeGate.js';
29
30
  import { resolveMemoryStage, appendRolloutReceipt, latencyBandForMs } from './memoryFlags.js';
30
31
  import { resolveProjectIdentity } from './projectIdentity.js';
32
+ import { captureAnchors } from '../../../template_project/.claude/ukit/runtime/memory-validity.mjs';
31
33
 
32
34
  const JOURNAL_MAX = 256;
33
35
  const OPS = new Set(['add', 'update', 'archive', 'forget', 'purge', 'restore', 'relocate']);
@@ -100,7 +102,7 @@ export async function mutateMemory(target, envelope = {}, { classifyAdd, guard,
100
102
  const { recordsPath, paths } = resolveTarget(target);
101
103
  const journalPath = path.join(paths.memoryV2Dir, 'mutation-journal.json');
102
104
  const { op, payload, idempotencyKey, expectedRevision, expectedGeneration,
103
- confirmScope } = envelope;
105
+ confirmScope, actor } = envelope;
104
106
  if (!OPS.has(op)) {
105
107
  return { status: 'rejected', reason: `unknown-op:${String(op)}` };
106
108
  }
@@ -131,6 +133,18 @@ export async function mutateMemory(target, envelope = {}, { classifyAdd, guard,
131
133
  }
132
134
  receiptStage = writerStage === 'shadow' ? 'shadow' : null;
133
135
  }
136
+ // 3.5.4 write gate (writeGate.js), memory.writeGate: 'strict' (default) | 'off'
137
+ // (false is accepted as off). Strict = evidence + near-duplicate + size, applied
138
+ // to agent writes (envelope.actor 'agent', i.e. the CLI) and to EVERY write to
139
+ // the user store, with or without an actor (it is cross-project, so a duplicate
140
+ // there is the costliest). Other library callers (storeV2, tests, tools) get
141
+ // the size cap only. 'off' disables the whole gate. The user store has no
142
+ // project config, so the CLI passes the project's mode in envelope.writeGate.
143
+ const gateMode = envelope.writeGate !== undefined ? envelope.writeGate : config?.memory?.writeGate;
144
+ const gateOn = gateMode !== false && gateMode !== 'off';
145
+ // The user store has no project root, so file evidence is not required there
146
+ // (writeGate.js skips it); size, secrets and near-duplicates still apply.
147
+ const gateStrict = gateOn && (actor === 'agent' || target.kind === 'user');
134
148
  const guardFn = guard ?? ((p) => guardWritePayload(p, { config, projectId }));
135
149
 
136
150
  try {
@@ -227,6 +241,17 @@ export async function mutateMemory(target, envelope = {}, { classifyAdd, guard,
227
241
  appliedRecordId = record.id;
228
242
  return { result: { status: 'ok', record, reason: 'review' }, records: [...records, record], postWrite };
229
243
  }
244
+ if (gateOn && decision?.action !== 'ENRICH') {
245
+ const gate = await checkRecordWrite({
246
+ record,
247
+ records,
248
+ projectRoot: target.kind === 'project' ? target.projectRoot : null,
249
+ op: 'add',
250
+ strict: gateStrict,
251
+ replaces: decision?.targetIds ?? (decision?.targetId ? [decision.targetId] : []),
252
+ });
253
+ if (!gate.ok) return { result: { status: 'rejected', reason: gate.reason, code: gate.code } };
254
+ }
230
255
  if (decision?.action === 'ENRICH' && decision.targetId) {
231
256
  const targetRec = records.find((r) => r.id === decision.targetId);
232
257
  if (targetRec) {
@@ -268,6 +293,18 @@ export async function mutateMemory(target, envelope = {}, { classifyAdd, guard,
268
293
  if (guarded && guarded.ok === false) {
269
294
  return { result: { status: 'rejected', reason: guarded.reason ?? 'secret-detected', labels: guarded.labels } };
270
295
  }
296
+ if (gateOn && op === 'update') {
297
+ const gate = await checkRecordWrite({
298
+ record: { ...existing, ...patch },
299
+ records,
300
+ projectRoot: target.kind === 'project' ? target.projectRoot : null,
301
+ op: 'update',
302
+ strict: gateStrict,
303
+ patch,
304
+ replaces: [existing.id],
305
+ });
306
+ if (!gate.ok) return { result: { status: 'rejected', reason: gate.reason, code: gate.code } };
307
+ }
271
308
  const patched = applyRecordPatch(records, existing.id, {
272
309
  ...patch, revision: (existing.revision ?? 1) + 1,
273
310
  });
@@ -351,6 +388,14 @@ export async function mutateMemory(target, envelope = {}, { classifyAdd, guard,
351
388
  latencyBand: latencyBandForMs(Date.now() - startedAt),
352
389
  });
353
390
  }
391
+ // 3.5.3: anchor a freshly written note to the files it names (sidecar only,
392
+ // outside the store lock, never fails the write).
393
+ if (result?.status === 'ok' && op === 'add' && target.kind === 'project' && result.record && result.reason !== 'review') {
394
+ await captureAnchors(target.projectRoot, [{
395
+ id: `record:${result.record.id}`, type: result.record.type, provenance: result.record.provenance,
396
+ text: result.record.text, evidence: result.record.evidence,
397
+ }]).catch(() => 0);
398
+ }
354
399
  return result;
355
400
  } catch (error) {
356
401
  if (error instanceof StoreCorruptError || error?.name === 'StoreCorruptError') {
@@ -0,0 +1,192 @@
1
+ // observations.js (3.5.4) - observation records: consolidated notes backed by >= 2
2
+ // episodes. UKit's part is deterministic: validate evidence (validateObservation)
3
+ // and propose candidates from content-bearing episodes (proposeObservations,
4
+ // `ukit memory observe`). The running agent decides and writes through the
5
+ // mutateMemory gate; nothing here writes, and no hook calls the proposer.
6
+ import path from 'node:path';
7
+
8
+ import { readJsonIfExists } from '../fileOps.js';
9
+ import { buildRuntimePaths } from '../runtimePaths.js';
10
+ import { readRecordStore } from './recordStore.js';
11
+ import { observationEvidenceErrors } from './records.js';
12
+ import { ARCHIVE_FILE } from './episodeArchive.js';
13
+ import { stripPromptBoilerplate } from './episodes.js';
14
+
15
+ export const DEFAULT_MIN_SUPPORT = 3;
16
+ const MAX_CANDIDATES = 20;
17
+ const MAX_EPISODE_IDS = 8;
18
+ const FOLLOW_WINDOW = 3;
19
+
20
+ /** Ids of every episode in the live store and in the episodes archive. */
21
+ export async function loadEpisodeIdsFor(projectRoot) {
22
+ const paths = buildRuntimePaths(projectRoot);
23
+ const ids = new Set();
24
+ const store = await readRecordStore(paths.memoryV2RecordsPath);
25
+ for (const r of store.records) if (r.type === 'episode') ids.add(r.id);
26
+ const archive = await readJsonIfExists(path.join(paths.memoryV2Dir, ARCHIVE_FILE)).catch(() => null);
27
+ for (const r of Array.isArray(archive?.records) ? archive.records : []) if (r?.id) ids.add(r.id);
28
+ return ids;
29
+ }
30
+
31
+ /**
32
+ * validateObservation(record, { loadEpisodeIds }) -> { ok, errors }
33
+ * loadEpisodeIds: async () => Set|Array of existing episode ids (store + archive).
34
+ * Non-observation records pass. Fails closed when existence cannot be checked.
35
+ */
36
+ export async function validateObservation(record, { loadEpisodeIds } = {}) {
37
+ if (record?.type !== 'observation') return { ok: true, errors: [] };
38
+ const errors = observationEvidenceErrors(record);
39
+ if (errors.length > 0) return { ok: false, errors };
40
+ if (typeof loadEpisodeIds !== 'function') return { ok: false, errors: ['cannot verify evidence: loadEpisodeIds missing'] };
41
+ let known;
42
+ try { known = new Set(await loadEpisodeIds()); } catch { return { ok: false, errors: ['cannot verify evidence: episode lookup failed'] }; }
43
+ const missing = [...new Set(record.meta.evidence.episodes)].filter((id) => !known.has(id));
44
+ if (missing.length > 0) return { ok: false, errors: [`evidence episodes not found in store or archive: ${missing.join(', ')}`] };
45
+ return { ok: true, errors: [] };
46
+ }
47
+
48
+ /**
49
+ * validateObservationEvidence(record, { projectRoot }) -> { ok, reason? }
50
+ * Write-gate entry: validateObservation with the id lookup bound to the store + archive.
51
+ */
52
+ export async function validateObservationEvidence(record, { projectRoot } = {}) {
53
+ const res = await validateObservation(record, { loadEpisodeIds: () => loadEpisodeIdsFor(projectRoot) });
54
+ return res.ok ? { ok: true } : { ok: false, reason: res.errors[0] };
55
+ }
56
+
57
+ const isContent =(r) => r?.type === 'episode' && Array.isArray(r.evidence) && r.meta?.verify
58
+ && r.evidence.some((e) => e?.kind === 'file');
59
+ const filesOf = (r) => [...new Set(r.evidence.filter((e) => e?.kind === 'file').map((e) => e.locator))];
60
+ const stemOf = (p) => path.basename(p).replace(/\.(test|spec)\.[^.]+$/, '').replace(/\.[^.]+$/, '');
61
+ const isTest = (p) => /(^|\/)tests?\//.test(p) || /\.(test|spec)\./.test(p);
62
+ const stripMirror = (p) => p.replace(/^template_project\//, '');
63
+ const isMirror = (src, other) => src !== other && stripMirror(src) === stripMirror(other);
64
+ const isTestOf = (src, other) => !isTest(src) && isTest(other) && stemOf(src) === stemOf(other);
65
+
66
+ // Identity of the TASK behind an episode, so restarts count once. Priority: an explicit handoff
67
+ // task id (TASK-xxx) in the prompt or the written files; else the prompt after boilerplate strip.
68
+ // Older stored episodes may still carry the boilerplate, so the strip is applied here as well.
69
+ const TASK_ID_RE = /\bTASK-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*\b/;
70
+ export function taskIdentity(ep) {
71
+ const text = String(ep?.text ?? '');
72
+ const prompt = (text.match(/^Task: (.*?)(?:\. Wrote: |$)/s) ?? [])[1] ?? '';
73
+ const id = prompt.match(TASK_ID_RE)?.[0]
74
+ ?? filesOf(ep).map((f) => f.match(/(?:^|\/)(TASK-[^/]*)\.md$/)?.[1]).find(Boolean);
75
+ if (id) return `id:${id}`;
76
+ const norm = stripPromptBoilerplate(prompt).toLowerCase().slice(0, 120);
77
+ return norm ? `prompt:${norm}` : `ep:${ep?.id}`;
78
+ }
79
+
80
+ /** Content-bearing episodes, oldest first. */
81
+ export function contentEpisodes(records) {
82
+ return (Array.isArray(records) ? records : []).filter(isContent)
83
+ .sort((a, b) => (a.created_at ?? 0) - (b.created_at ?? 0));
84
+ }
85
+
86
+ const ids = (eps) => eps.slice(-MAX_EPISODE_IDS).map((e) => e.id);
87
+ const cand = (kind, key, files, text, eps) => {
88
+ const episodes = [...new Set(ids(eps))];
89
+ return { kind, key, files, text, support: eps.length, evidence: { episodes, count: episodes.length } };
90
+ };
91
+
92
+ // The ONE noise rule for co-write pairs: run bookkeeping (anything under docs/AI_HANDOFF/,
93
+ // or INDEX.md / RUN.md / TASK-*.md anywhere) is always written together by the handoff
94
+ // process itself, so a pair where BOTH files are bookkeeping says nothing about the code.
95
+ export const isBookkeeping = (f) => /^docs\/AI_HANDOFF\//.test(f) || /(^|\/)(INDEX\.md|RUN\.md|TASK-[^/]*\.md)$/.test(f);
96
+ // Living-status / log docs are touched by nearly every task; a pair with EITHER of them says
97
+ // nothing about the code. A hub file (in more than HUB_SHARE of all content episodes) co-occurs
98
+ // with everything for the same reason, so pairs involving it are dropped too.
99
+ export const isLivingStatusDoc = (f) => /^(docs\/(STATUS|WORKLOG|TASKS)\.md|CHANGELOG\.md)$/.test(f) || /^docs\/AI_HANDOFF\//.test(f);
100
+ export const HUB_SHARE = 0.3;
101
+ const HUB_MIN_EPISODES = 10; // below this the share is too noisy to call anything a hub
102
+
103
+ /**
104
+ * proposeObservations(records, { minSupport }) -> candidates (pure).
105
+ * kinds: co-write (file pair in >= N episodes), repeated-fail (file mostly in
106
+ * failed-verify episodes), follow-up (mirror/test written later than its source).
107
+ */
108
+ export function proposeObservations(records, { minSupport = DEFAULT_MIN_SUPPORT, existingKeys = new Set() } = {}) {
109
+ const eps = contentEpisodes(records);
110
+ const out = [];
111
+ const byFile = new Map();
112
+ const pairs = new Map();
113
+ for (const ep of eps) {
114
+ const files = filesOf(ep).sort();
115
+ for (const f of files) {
116
+ if (!byFile.has(f)) byFile.set(f, []);
117
+ byFile.get(f).push(ep);
118
+ }
119
+ for (let i = 0; i < files.length; i += 1) {
120
+ for (let j = i + 1; j < files.length; j += 1) {
121
+ const k = `${files[i]}\u0000${files[j]}`;
122
+ if (!pairs.has(k)) pairs.set(k, []);
123
+ pairs.get(k).push(ep);
124
+ }
125
+ }
126
+ }
127
+ for (const [k, list] of pairs) {
128
+ const [a, b] = k.split('\u0000');
129
+ if (isBookkeeping(a) && isBookkeeping(b)) continue;
130
+ if (isLivingStatusDoc(a) || isLivingStatusDoc(b)) continue;
131
+ if (eps.length >= HUB_MIN_EPISODES
132
+ && (byFile.get(a).length / eps.length > HUB_SHARE || byFile.get(b).length / eps.length > HUB_SHARE)) continue;
133
+ const base = Math.min(byFile.get(a).length, byFile.get(b).length);
134
+ if (list.length < minSupport || list.length / base < 0.5) continue;
135
+ out.push(cand('co-write', `co-write:${a}|${b}`, [a, b],
136
+ `Editing ${a} usually also touches ${b} (written together in ${list.length} episodes).`, list));
137
+ }
138
+ for (const [f, list] of byFile) {
139
+ if (isBookkeeping(f) || isLivingStatusDoc(f)) continue;
140
+ // Restarts of one task are ONE failure: count distinct tasks, keep one episode per task.
141
+ const byTask = new Map();
142
+ for (const e of list) {
143
+ const t = taskIdentity(e);
144
+ const slot = byTask.get(t) ?? { failed: null, any: e };
145
+ if (e.meta.verify === 'fail') slot.failed = e;
146
+ byTask.set(t, slot);
147
+ }
148
+ const failed = [...byTask.values()].filter((s) => s.failed).map((s) => s.failed);
149
+ if (failed.length < minSupport || failed.length / byTask.size < 0.5) continue;
150
+ out.push(cand('repeated-fail', `repeated-fail:${f}`, [f],
151
+ `Tasks editing ${f} often end with a failed verify (${failed.length} of ${byTask.size} tasks).`, failed));
152
+ }
153
+ for (const src of byFile.keys()) {
154
+ for (const other of byFile.keys()) {
155
+ const kind = isMirror(src, other) ? 'mirror' : (isTestOf(src, other) ? 'test' : null);
156
+ if (!kind) continue;
157
+ const srcOnly = byFile.get(src).filter((e) => !filesOf(e).includes(other));
158
+ const followed = srcOnly.filter((e) => {
159
+ const at = eps.indexOf(e);
160
+ return eps.slice(at + 1, at + 1 + FOLLOW_WINDOW).some((n) => filesOf(n).includes(other));
161
+ });
162
+ if (followed.length < minSupport) continue;
163
+ out.push(cand('follow-up', `follow-up:${src}|${other}`, [src, other],
164
+ `${other} (${kind} of ${src}) is usually edited in a later task after ${src} (${followed.length} times); update it in the same task.`, followed));
165
+ }
166
+ }
167
+ return out.filter((c) => !existingKeys.has(c.key))
168
+ .sort((x, y) => y.support - x.support || x.key.localeCompare(y.key)).slice(0, MAX_CANDIDATES);
169
+ }
170
+
171
+ /** `ukit memory observe [--json] [--min N]` - proposes only; never writes. */
172
+ export async function runObserve(projectRoot, rest = []) {
173
+ const json = rest.includes('--json');
174
+ const at = rest.indexOf('--min');
175
+ const minSupport = at >= 0 && Number(rest[at + 1]) >= 2 ? Number(rest[at + 1]) : DEFAULT_MIN_SUPPORT;
176
+ const store = await readRecordStore(buildRuntimePaths(projectRoot).memoryV2RecordsPath);
177
+ const existingKeys = new Set(store.records.filter((r) => r.type === 'observation' && r.meta?.key).map((r) => r.meta.key));
178
+ const content = contentEpisodes(store.records);
179
+ const candidates = proposeObservations(store.records, { minSupport, existingKeys });
180
+ if (json) {
181
+ console.log(JSON.stringify({ episodes: content.length, minSupport, candidates }, null, 2));
182
+ return { episodes: content.length, candidates };
183
+ }
184
+ console.log(`[UKit] observe: ${content.length} content-bearing episode(s), ${candidates.length} candidate(s) (min support ${minSupport})`);
185
+ for (const c of candidates) {
186
+ console.log(`- [${c.kind}] ${c.text}\n evidence: ${c.evidence.count} episodes ${c.evidence.episodes.join(' ')}`);
187
+ }
188
+ if (candidates.length > 0) {
189
+ console.log('Proposals only: write one through the memory write gate as type=observation with meta.evidence={episodes,count} and meta.key=<key>.');
190
+ }
191
+ return { episodes: content.length, candidates };
192
+ }
@@ -3,6 +3,7 @@ import path from 'node:path';
3
3
  import crypto from 'node:crypto';
4
4
  import { readJsonIfExists, writeJson, withFileLock } from '../fileOps.js';
5
5
  import { buildUserPaths } from '../userPaths.js';
6
+ import { maybeAutoPrune } from './registryPrune.js';
6
7
 
7
8
  /**
8
9
  * Host-owned stable project identity resolver (M01-01, SPEC §5 FR-001..003).
@@ -225,7 +226,7 @@ export async function resolveProjectIdentity(projectRoot, { homeDir, mint = true
225
226
  if (fresh === null) return null; // became corrupt between read and lock
226
227
  const existing = findByRoot(fresh, realRoot)
227
228
  ?? (commonDir ? findByGitCommonDir(fresh, commonDir) : null);
228
- if (existing) return existing;
229
+ if (existing) return { projectId: existing, entryCount: 0 };
229
230
 
230
231
  const now = new Date().toISOString();
231
232
  const projectId = mintProjectId(realRoot);
@@ -238,10 +239,16 @@ export async function resolveProjectIdentity(projectRoot, { homeDir, mint = true
238
239
  };
239
240
  indexAliases(fresh, projectId, aliases);
240
241
  await writeJson(regPath, fresh);
241
- return projectId;
242
+ return { projectId, entryCount: Object.keys(fresh.projects).length };
242
243
  });
243
244
 
244
245
  if (minted === undefined || minted === null) return unverified;
246
+ if (typeof minted === 'object') {
247
+ // Amortised stale-entry cleanup (never awaited by the caller's deadline path beyond its
248
+ // own bounded budget; failure-proof). Runs after the lock is released.
249
+ await maybeAutoPrune({ homeDir, entryCount: minted.entryCount, currentRoot: realRoot });
250
+ return { projectId: minted.projectId, source: 'registry', ambiguous: false, aliases };
251
+ }
245
252
  return { projectId: minted, source: 'registry', ambiguous: false, aliases };
246
253
  }
247
254