@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
package/bin/ukit
CHANGED
|
@@ -44,6 +44,15 @@ async function main() {
|
|
|
44
44
|
packageVersion,
|
|
45
45
|
});
|
|
46
46
|
} finally {
|
|
47
|
+
// emit() only queues in memory; a short-lived CLI never runs
|
|
48
|
+
// startLifecycle, so drain queued telemetry here. Bounded (2s) and
|
|
49
|
+
// never throws; the watchdog above is still armed while it runs.
|
|
50
|
+
try {
|
|
51
|
+
const { flushAllRecorders } = await import('../src/core/observability/emit/lifecycle.js');
|
|
52
|
+
await flushAllRecorders({ deadlineMs: 2000 });
|
|
53
|
+
} catch {
|
|
54
|
+
// telemetry must never change the CLI exit status
|
|
55
|
+
}
|
|
47
56
|
clearTimeout(watchdog);
|
|
48
57
|
}
|
|
49
58
|
}
|
|
@@ -1234,6 +1234,18 @@ entries:
|
|
|
1234
1234
|
archive_policy: never
|
|
1235
1235
|
notes: C100 native CI matrix design (macOS/Windows/Linux); maintainer-only, not shipped to user projects
|
|
1236
1236
|
|
|
1237
|
+
- id: docs-design-memory-io-inventory
|
|
1238
|
+
path: docs/design/memory-io-inventory.md
|
|
1239
|
+
class: canonical
|
|
1240
|
+
audience: [maintainer]
|
|
1241
|
+
owner: runtime
|
|
1242
|
+
source_of_truth: docs/design/memory-io-inventory.md
|
|
1243
|
+
merge_strategy: none
|
|
1244
|
+
load_policy: on-demand
|
|
1245
|
+
validation: [test:tests/docs/memoryInventory.test.js]
|
|
1246
|
+
archive_policy: never
|
|
1247
|
+
notes: live reader/writer inventory of src/core/memory modules (pinned by tests/docs/memoryInventory.test.js); maintainer-only, not shipped to user projects
|
|
1248
|
+
|
|
1237
1249
|
- id: docs-release-multi-engine-release-gate
|
|
1238
1250
|
path: docs/release/MULTI-ENGINE-RELEASE-GATE.md
|
|
1239
1251
|
class: canonical
|
|
@@ -1322,6 +1322,19 @@ items:
|
|
|
1322
1322
|
packs:
|
|
1323
1323
|
- core
|
|
1324
1324
|
|
|
1325
|
+
# 3.5.2 WP-C: advisory PostToolUse Edit|Write module step (edit-graph hint).
|
|
1326
|
+
- id: hook-edit-hint-module
|
|
1327
|
+
type: hook
|
|
1328
|
+
sourceTemplate: .claude/hooks/edit-hint.mjs
|
|
1329
|
+
targetPath: .claude/hooks/edit-hint.mjs
|
|
1330
|
+
requires:
|
|
1331
|
+
- ukit-runtime-scripts
|
|
1332
|
+
mergeStrategy: overwrite_with_backup
|
|
1333
|
+
variables: []
|
|
1334
|
+
enabledByDefault: true
|
|
1335
|
+
packs:
|
|
1336
|
+
- core
|
|
1337
|
+
|
|
1325
1338
|
- id: hook-completion-gate
|
|
1326
1339
|
type: hook
|
|
1327
1340
|
sourceTemplate: .claude/hooks/completion-gate.sh
|
|
@@ -1862,6 +1875,16 @@ items:
|
|
|
1862
1875
|
packs:
|
|
1863
1876
|
- core
|
|
1864
1877
|
|
|
1878
|
+
- id: ukit-index-edit-graph-script
|
|
1879
|
+
type: config
|
|
1880
|
+
sourceTemplate: .claude/ukit/index/edit-graph.mjs
|
|
1881
|
+
targetPath: .claude/ukit/index/edit-graph.mjs
|
|
1882
|
+
mergeStrategy: overwrite_with_backup
|
|
1883
|
+
variables: []
|
|
1884
|
+
enabledByDefault: true
|
|
1885
|
+
packs:
|
|
1886
|
+
- core
|
|
1887
|
+
|
|
1865
1888
|
- id: ukit-index-route-catalog-script
|
|
1866
1889
|
type: config
|
|
1867
1890
|
sourceTemplate: .claude/ukit/index/route-catalog.mjs
|
package/package.json
CHANGED
|
@@ -6,6 +6,7 @@ import { resolveDecisionApiKey, resolveDecisionBaseUrl } from '../../core/gatewa
|
|
|
6
6
|
import { buildCodeIndex, buildDerivedIndexArtifacts } from '../../index/buildIndex.js';
|
|
7
7
|
import { installIndexRefreshHooks } from '../../index/gitHooks.js';
|
|
8
8
|
import fs from 'node:fs/promises';
|
|
9
|
+
import { archiveLegacyEpisodes } from '../../core/memory/episodeArchive.js';
|
|
9
10
|
import { pathExists, removeFileOrLinkOnly } from '../../core/fileOps.js';
|
|
10
11
|
import { readInstallMetadata, removeTrackedPathsFromMetadata } from '../../core/metadata.js';
|
|
11
12
|
import { provisionSupportDir } from '../../core/observability/support/provision.js';
|
|
@@ -446,6 +447,17 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
|
|
|
446
447
|
);
|
|
447
448
|
}
|
|
448
449
|
|
|
450
|
+
// 3.5.1: archive pre-existing content-free episodes (backup first, never
|
|
451
|
+
// deleted, idempotent). Advisory — never fails install; not run from hooks.
|
|
452
|
+
try {
|
|
453
|
+
const archived = await archiveLegacyEpisodes(projectRoot);
|
|
454
|
+
if (archived.archived > 0) {
|
|
455
|
+
console.log(`[UKit] Memory: archived ${archived.archived} content-free episode(s) -> ${path.relative(projectRoot, archived.archivePath)} (backup: ${archived.backupDir})`);
|
|
456
|
+
}
|
|
457
|
+
} catch (error) {
|
|
458
|
+
console.log(`[UKit] Memory episode archive skipped: ${error?.message ?? String(error)}`);
|
|
459
|
+
}
|
|
460
|
+
|
|
449
461
|
console.log('[UKit] Install completed.');
|
|
450
462
|
console.log('[UKit] Team rule: remember only `ukit install`.');
|
|
451
463
|
console.log(
|
|
@@ -29,7 +29,8 @@ import { buildRuntimePaths } from '../../core/runtimePaths.js';
|
|
|
29
29
|
import { buildUserPaths } from '../../core/userPaths.js';
|
|
30
30
|
import { pathExists } from '../../core/fileOps.js';
|
|
31
31
|
import { detectProjectContext } from '../../context/detectProjectContext.js';
|
|
32
|
-
import { episodeText, resolveLedger, writeEpisode } from '../../core/memory/episodes.js';
|
|
32
|
+
import { episodeText, readRouteState, resolveLedger, writeEpisode } from '../../core/memory/episodes.js';
|
|
33
|
+
import { archiveLegacyEpisodes, purgeArchivedEpisode, restoreArchivedEpisodes } from '../../core/memory/episodeArchive.js';
|
|
33
34
|
import fs from 'node:fs/promises';
|
|
34
35
|
import os from 'node:os';
|
|
35
36
|
import path from 'node:path';
|
|
@@ -561,11 +562,17 @@ async function runMemoryEpisode(projectRoot, homeDir, args) {
|
|
|
561
562
|
|
|
562
563
|
if (dryRun) {
|
|
563
564
|
const sessionId = ledger.sessionId ?? ledger.sessionKey ?? ledgerKey.replace(/\.json$/, '');
|
|
564
|
-
|
|
565
|
+
const routeState = await readRouteState(projectRoot, ledger.sessionKey ?? sessionId);
|
|
566
|
+
const text = episodeText(ledger, sessionId, { routeState, projectRoot });
|
|
567
|
+
console.log(text ? `[UKit] episode (dry-run): ${text}` : '[UKit] episode (dry-run): no successful write — nothing to record');
|
|
565
568
|
return;
|
|
566
569
|
}
|
|
567
570
|
|
|
568
571
|
const res = await writeEpisode(projectRoot, { ledger, ledgerKey, config, homeDir });
|
|
572
|
+
if (res.status === 'empty') {
|
|
573
|
+
console.log('[UKit] episode: no successful write — nothing to record');
|
|
574
|
+
return;
|
|
575
|
+
}
|
|
569
576
|
if (res.status === 'duplicate') {
|
|
570
577
|
console.log('[UKit] episode: already recorded');
|
|
571
578
|
return;
|
|
@@ -929,6 +936,17 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
|
|
|
929
936
|
return;
|
|
930
937
|
}
|
|
931
938
|
|
|
939
|
+
if (subcommand === 'archive-episodes') {
|
|
940
|
+
if (rest.includes('--restore')) {
|
|
941
|
+
const r = await restoreArchivedEpisodes(projectRoot, { homeDir });
|
|
942
|
+
console.log(`[UKit] archive-episodes --restore: status=${r.status} restored=${r.restored} archived-file=${r.archived}`);
|
|
943
|
+
return;
|
|
944
|
+
}
|
|
945
|
+
const r = await archiveLegacyEpisodes(projectRoot, { dryRun: rest.includes('--dry-run'), homeDir });
|
|
946
|
+
console.log(`[UKit] archive-episodes: status=${r.status} archived=${r.archived} remaining=${r.remaining}${r.backupDir ? ` backup=${r.backupDir}` : ''}${r.reason ? ` reason=${r.reason}` : ''}`);
|
|
947
|
+
return;
|
|
948
|
+
}
|
|
949
|
+
|
|
932
950
|
if (subcommand === 'forget') {
|
|
933
951
|
const memoryId = rest.join(' ').trim();
|
|
934
952
|
if (!memoryId) {
|
|
@@ -955,6 +973,14 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
|
|
|
955
973
|
{ kind: 'project', projectRoot, homeDir },
|
|
956
974
|
{ op: 'purge', payload: { id: memoryId } },
|
|
957
975
|
);
|
|
976
|
+
// An archived episode is not in the live store; its copy must go too. A
|
|
977
|
+
// refused purge (disabled lane, corrupt store) leaves the archive alone.
|
|
978
|
+
const purgedFromArchive = (res.status === 'ok' || res.status === 'not-found')
|
|
979
|
+
&& await purgeArchivedEpisode(projectRoot, memoryId);
|
|
980
|
+
if (res.status === 'not-found' && purgedFromArchive) {
|
|
981
|
+
console.log(`[UKit] Purged ${memoryId} from the episode archive.`);
|
|
982
|
+
return;
|
|
983
|
+
}
|
|
958
984
|
const handled = handleMutationResult(res, {
|
|
959
985
|
notFoundMessage: `Memory record not found: ${memoryId}`,
|
|
960
986
|
});
|
|
@@ -981,7 +1007,7 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
|
|
|
981
1007
|
|
|
982
1008
|
export function printMemoryHelp() {
|
|
983
1009
|
console.log('UKit Memory Commands');
|
|
984
|
-
console.log('Usage: ukit memory <list|search|expand|recall|forget|purge|export|propose|approve|reject|learn|promote|episode|hygiene|backup|restore|doctor> [args]');
|
|
1010
|
+
console.log('Usage: ukit memory <list|search|expand|recall|forget|purge|export|propose|approve|reject|learn|promote|episode|archive-episodes|hygiene|backup|restore|doctor> [args]');
|
|
985
1011
|
console.log('');
|
|
986
1012
|
console.log('Subcommands:');
|
|
987
1013
|
console.log(' list List memory items in shared .ukit/storage/memory');
|
|
@@ -998,6 +1024,7 @@ export function printMemoryHelp() {
|
|
|
998
1024
|
console.log(' learn [--apply] [--min <n>] [--project <id>] Propose pending candidates from mined failure patterns (dry-run by default)');
|
|
999
1025
|
console.log(' promote [--dry-run] Render approved rules/procedures into the ## ukit-learned block in docs/MEMORY.md');
|
|
1000
1026
|
console.log(' episode [--dry-run] [--session <id>] Write a session episode record from the exec-ledger');
|
|
1027
|
+
console.log(' archive-episodes [--dry-run|--restore] Move content-free legacy episodes to episodes-archive.json (backup first; --restore re-adds them)');
|
|
1001
1028
|
console.log(' hygiene [--project <id>] Run decision-conflict resolution + session archiving now');
|
|
1002
1029
|
console.log(' backup [--out <dir>] [--user] Snapshot v2 store(s) + sha256 manifest into a backup dir');
|
|
1003
1030
|
console.log(' restore <dir> [--dry-run] [--user] Restore store(s) from a backup dir (plan only with --dry-run)');
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
// episodeArchive.js — move pre-3.5.1 content-free episodes out of the live
|
|
2
|
+
// store into <memoryV2Dir>/episodes-archive.json (never deleted).
|
|
3
|
+
//
|
|
4
|
+
// Detection is by the old template shape (LEGACY_EPISODE_TEXT_RE on
|
|
5
|
+
// type 'episode'), never by age. Run explicitly from `ukit install` and
|
|
6
|
+
// `ukit memory archive-episodes` — never from a hook.
|
|
7
|
+
//
|
|
8
|
+
// Invariants (blueprint ukit-memory PLAN §M02):
|
|
9
|
+
// - one backup (storeBackup.createBackup) before the first live-store write;
|
|
10
|
+
// - the removal goes through mutateMemory op 'relocate' (the single guarded
|
|
11
|
+
// write entry), under the store's file lock, so the generation bumps
|
|
12
|
+
// exactly once and tombstones are carried over untouched (no tombstone is
|
|
13
|
+
// added: an archived stub stays restorable);
|
|
14
|
+
// - the archive file is written (merged by id) BEFORE the live store drops
|
|
15
|
+
// the records, so a crash between the two leaves a superset, and a rerun
|
|
16
|
+
// simply finishes the removal;
|
|
17
|
+
// - second run finds no template-shaped episode left → no write, no backup.
|
|
18
|
+
// Restore goes through mutateMemory op 'restore': redaction, fingerprint
|
|
19
|
+
// dedupe and tombstone precedence apply, and purged ids never come back.
|
|
20
|
+
|
|
21
|
+
import fs from 'node:fs/promises';
|
|
22
|
+
import path from 'node:path';
|
|
23
|
+
|
|
24
|
+
import { readJsonIfExists, writeJson } from '../fileOps.js';
|
|
25
|
+
import { buildRuntimePaths } from '../runtimePaths.js';
|
|
26
|
+
import { readRecordStore } from './recordStore.js';
|
|
27
|
+
import { mutateMemory } from './mutateMemory.js';
|
|
28
|
+
import { createBackup } from './storeBackup.js';
|
|
29
|
+
import { LEGACY_EPISODE_TEXT_RE } from './episodes.js';
|
|
30
|
+
|
|
31
|
+
export const ARCHIVE_FILE = 'episodes-archive.json';
|
|
32
|
+
const ARCHIVE_VERSION = 1;
|
|
33
|
+
|
|
34
|
+
export function isLegacyEpisodeStub(record) {
|
|
35
|
+
return Boolean(record) && record.type === 'episode'
|
|
36
|
+
&& typeof record.text === 'string' && LEGACY_EPISODE_TEXT_RE.test(record.text);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
function archivePathFor(projectRoot) {
|
|
40
|
+
return path.join(buildRuntimePaths(projectRoot).memoryV2Dir, ARCHIVE_FILE);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
async function readArchive(archivePath) {
|
|
44
|
+
const doc = await readJsonIfExists(archivePath).catch(() => null);
|
|
45
|
+
return Array.isArray(doc?.records) ? doc.records : [];
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* archiveLegacyEpisodes(projectRoot, {dryRun}) →
|
|
50
|
+
* {status:'ok'|'noop'|'dry-run'|'skipped', archived, remaining, backupDir?, archivePath?, reason?}
|
|
51
|
+
*/
|
|
52
|
+
export async function archiveLegacyEpisodes(projectRoot, { dryRun = false, homeDir } = {}) {
|
|
53
|
+
const paths = buildRuntimePaths(projectRoot);
|
|
54
|
+
const recordsPath = paths.memoryV2RecordsPath;
|
|
55
|
+
const archivePath = archivePathFor(projectRoot);
|
|
56
|
+
|
|
57
|
+
const snapshot = await readRecordStore(recordsPath);
|
|
58
|
+
if (snapshot.state !== 'ok') {
|
|
59
|
+
return { status: 'skipped', archived: 0, remaining: snapshot.records.length, reason: `store-${snapshot.state}` };
|
|
60
|
+
}
|
|
61
|
+
const stubs = snapshot.records.filter(isLegacyEpisodeStub);
|
|
62
|
+
if (stubs.length === 0) {
|
|
63
|
+
return { status: 'noop', archived: 0, remaining: snapshot.records.length, archivePath };
|
|
64
|
+
}
|
|
65
|
+
if (dryRun) {
|
|
66
|
+
return { status: 'dry-run', archived: stubs.length, remaining: snapshot.records.length - stubs.length, archivePath };
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
// The backup is taken inside the sink: it only runs once the write lane has
|
|
70
|
+
// accepted the op and there are records to move, so a refused or empty run
|
|
71
|
+
// never creates one. The store file is not rewritten until the sink returns,
|
|
72
|
+
// so the backup still holds every record about to move; createBackup takes
|
|
73
|
+
// no store lock, so calling it under mutateMemory's lock cannot deadlock.
|
|
74
|
+
let backupDir;
|
|
75
|
+
const result = await mutateMemory(
|
|
76
|
+
{ kind: 'project', projectRoot, homeDir },
|
|
77
|
+
{ op: 'relocate', payload: { ids: stubs.map((r) => r.id) } },
|
|
78
|
+
{
|
|
79
|
+
sink: async (toArchive) => {
|
|
80
|
+
({ backupDir } = await createBackup({ projectRoot }));
|
|
81
|
+
const existing = await readArchive(archivePath);
|
|
82
|
+
const ids = new Set(existing.map((r) => r?.id));
|
|
83
|
+
const merged = [...existing, ...toArchive.filter((r) => !ids.has(r.id))];
|
|
84
|
+
await writeJson(archivePath, {
|
|
85
|
+
version: ARCHIVE_VERSION,
|
|
86
|
+
updatedAt: new Date().toISOString(),
|
|
87
|
+
records: merged,
|
|
88
|
+
}, { fsync: true });
|
|
89
|
+
await fs.chmod(archivePath, 0o600).catch(() => {});
|
|
90
|
+
},
|
|
91
|
+
},
|
|
92
|
+
);
|
|
93
|
+
if (result.status !== 'ok' || !(result.relocated > 0)) {
|
|
94
|
+
// Nothing left the live store (writer stage off, memoryV2 disabled, or a
|
|
95
|
+
// concurrent run got there first); the sink never ran, so no backup exists.
|
|
96
|
+
if (result.status !== 'ok') {
|
|
97
|
+
return {
|
|
98
|
+
status: 'skipped', archived: 0, remaining: snapshot.records.length, reason: result.reason ?? result.status,
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
return { status: 'noop', archived: 0, remaining: result.remaining, archivePath };
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
return {
|
|
105
|
+
status: 'ok',
|
|
106
|
+
archived: result.relocated,
|
|
107
|
+
remaining: result.remaining,
|
|
108
|
+
backupDir,
|
|
109
|
+
archivePath,
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* purgeArchivedEpisode(projectRoot, id) → boolean (true when a copy was removed)
|
|
115
|
+
* `ukit memory purge <id>` must also remove the archived copy: an archived stub
|
|
116
|
+
* is no longer in the live store, so the store purge alone would leave its text
|
|
117
|
+
* on disk.
|
|
118
|
+
*/
|
|
119
|
+
export async function purgeArchivedEpisode(projectRoot, id) {
|
|
120
|
+
const archivePath = archivePathFor(projectRoot);
|
|
121
|
+
const existing = await readArchive(archivePath);
|
|
122
|
+
const kept = existing.filter((r) => r?.id !== id);
|
|
123
|
+
if (kept.length === existing.length) return false;
|
|
124
|
+
await writeJson(archivePath, {
|
|
125
|
+
version: ARCHIVE_VERSION,
|
|
126
|
+
updatedAt: new Date().toISOString(),
|
|
127
|
+
records: kept,
|
|
128
|
+
}, { fsync: true });
|
|
129
|
+
await fs.chmod(archivePath, 0o600).catch(() => {});
|
|
130
|
+
return true;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* restoreArchivedEpisodes(projectRoot, {homeDir}) → {status, restored, archived}
|
|
135
|
+
* Re-adds archived stubs via op 'restore' (dedupe + tombstone precedence).
|
|
136
|
+
* The archive file is kept; running the archive again moves them back out.
|
|
137
|
+
*/
|
|
138
|
+
export async function restoreArchivedEpisodes(projectRoot, { homeDir } = {}) {
|
|
139
|
+
const archived = await readArchive(archivePathFor(projectRoot));
|
|
140
|
+
if (archived.length === 0) return { status: 'noop', restored: 0, archived: 0 };
|
|
141
|
+
const res = await mutateMemory(
|
|
142
|
+
{ kind: 'project', projectRoot, homeDir },
|
|
143
|
+
{ op: 'restore', payload: { records: archived } },
|
|
144
|
+
);
|
|
145
|
+
if (res.status !== 'ok') return { status: res.status, restored: 0, archived: archived.length, reason: res.reason };
|
|
146
|
+
return { status: 'ok', restored: res.added ?? 0, archived: archived.length };
|
|
147
|
+
}
|
|
@@ -14,6 +14,7 @@ import path from 'node:path';
|
|
|
14
14
|
|
|
15
15
|
import { loadRecords } from './storeV2.js';
|
|
16
16
|
import { mutateMemory } from './mutateMemory.js';
|
|
17
|
+
import { redactWritePayload } from './writeGuard.js';
|
|
17
18
|
import { detectProjectContext } from '../../context/detectProjectContext.js';
|
|
18
19
|
import { listLedgerFiles, LEDGER_DIR_REL } from '../../diagnostics/ledgerFiles.js';
|
|
19
20
|
|
|
@@ -49,19 +50,103 @@ export async function resolveLedger(projectRoot, sessionId) {
|
|
|
49
50
|
return { ledger: await readJsonIfExists(path.join(dir, name)), ledgerKey: name };
|
|
50
51
|
}
|
|
51
52
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
return
|
|
53
|
+
// Template shape of the pre-3.5.1 content-free episode text. The archive
|
|
54
|
+
// migration (episodeArchive.js) detects stubs by this shape, not by age.
|
|
55
|
+
export const LEGACY_EPISODE_TEXT_RE = /^Session .+: (?:writeOk|writeFail), verify=(?:ok|fail|not-run), \d+ receipts, last command /;
|
|
56
|
+
|
|
57
|
+
const PROMPT_MAX = 240;
|
|
58
|
+
const FILES_MAX = 6;
|
|
59
|
+
const LINE_MAX = 160;
|
|
60
|
+
|
|
61
|
+
const oneLine = (value, max) => String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
|
|
62
|
+
|
|
63
|
+
export async function readRouteState(projectRoot, sessionKey) {
|
|
64
|
+
if (!sessionKey) return null;
|
|
65
|
+
return readJsonIfExists(path.join(
|
|
66
|
+
projectRoot, '.ukit', 'storage', 'cache', 'route-state', `${safeSegment(sessionKey)}.json`,
|
|
67
|
+
));
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
// Project-relative path of a written file, or null when it falls outside the
|
|
71
|
+
// project (keeps home-directory paths out of the store).
|
|
72
|
+
function relativeWritten(projectRoot, file) {
|
|
73
|
+
if (typeof file !== 'string' || !file.trim()) return null;
|
|
74
|
+
const abs = path.isAbsolute(file) ? file : path.join(projectRoot, file);
|
|
75
|
+
const rel = path.relative(projectRoot, abs);
|
|
76
|
+
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
|
|
77
|
+
return rel.split(path.sep).join('/');
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
// Strips a leading `cd <root>;|&&` and rewrites remaining occurrences of the
|
|
81
|
+
// absolute project root to `.`, so no machine path lands in the record.
|
|
82
|
+
export function normalizeCommand(command, projectRoot) {
|
|
83
|
+
let text = String(command ?? '').trim();
|
|
84
|
+
const root = projectRoot ? String(projectRoot).replace(/[\\/]+$/, '') : '';
|
|
85
|
+
if (root) {
|
|
86
|
+
const esc = root.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
87
|
+
text = text.replace(new RegExp(`^cd\\s+(?:"${esc}"|'${esc}'|${esc})\\s*(?:;|&&)\\s*`), '');
|
|
88
|
+
text = text.split(root).join('.');
|
|
89
|
+
}
|
|
90
|
+
return text;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* buildEpisode(ledger, {routeState, projectRoot}) → {text, files, verify,
|
|
95
|
+
* command, unfinished, hasTask} | null. Null = no successful write → no
|
|
96
|
+
* episode. The task text is bounded data from the explicit user prompt,
|
|
97
|
+
* attached only when route-state and ledger agree on taskInstanceId.
|
|
98
|
+
* Transcript content is never read.
|
|
99
|
+
*/
|
|
100
|
+
export function buildEpisode(ledger, { routeState = null, projectRoot = '' } = {}) {
|
|
101
|
+
if (!ledger || typeof ledger !== 'object') return null;
|
|
102
|
+
const receipts = (Array.isArray(ledger.receipts) ? ledger.receipts : []).filter((r) => r && typeof r === 'object');
|
|
103
|
+
const writes = receipts.filter((r) => r.kind === 'write' && r.success === true);
|
|
104
|
+
if (ledger.writeSucceeded !== true && writes.length === 0) return null;
|
|
105
|
+
|
|
106
|
+
const files = [];
|
|
107
|
+
for (const r of writes) {
|
|
108
|
+
const rel = relativeWritten(projectRoot, r.file);
|
|
109
|
+
if (rel && !files.includes(rel)) files.push(rel);
|
|
110
|
+
}
|
|
111
|
+
const verifications = receipts.filter((r) => r.kind === 'verification');
|
|
112
|
+
const lastVerification = verifications.length > 0 ? verifications[verifications.length - 1] : null;
|
|
113
|
+
const command = oneLine(normalizeCommand(lastVerification?.command, projectRoot), LINE_MAX) || null;
|
|
114
|
+
let verify = 'not-run';
|
|
115
|
+
if (ledger.verificationAttempted === true || lastVerification) {
|
|
116
|
+
verify = ledger.verificationSucceeded === true ? 'ok' : 'fail';
|
|
117
|
+
}
|
|
118
|
+
const unfinished = [];
|
|
119
|
+
if (verify === 'not-run') unfinished.push('edits written but not verified');
|
|
120
|
+
if (verify === 'fail') unfinished.push('last verification failed');
|
|
121
|
+
if (ledger.blocker) {
|
|
122
|
+
const b = typeof ledger.blocker === 'string' ? ledger.blocker : (ledger.blocker.reason ?? ledger.blocker.code);
|
|
123
|
+
unfinished.push(`blocker: ${oneLine(b, 80) || 'recorded'}`);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
// A prompt captured on the task itself (ledger.taskPrompt, set when the task's ledger
|
|
127
|
+
// was created) is authoritative. Route-state only holds the LATEST prompt, so it is a
|
|
128
|
+
// fallback that must prove the same taskInstanceId on both sides.
|
|
129
|
+
const provenMatch = routeState && ledger.taskInstanceId && routeState.taskInstanceId
|
|
130
|
+
&& routeState.taskInstanceId === ledger.taskInstanceId;
|
|
131
|
+
const legacyMatch = routeState && !ledger.taskInstanceId && !routeState.taskInstanceId;
|
|
132
|
+
const task = oneLine(
|
|
133
|
+
ledger.taskPrompt
|
|
134
|
+
?? (provenMatch || legacyMatch ? routeState?.routingContext?.lastExplicitUserPromptText : ''),
|
|
135
|
+
PROMPT_MAX,
|
|
136
|
+
);
|
|
137
|
+
|
|
138
|
+
const parts = [];
|
|
139
|
+
if (task) parts.push(`Task: ${task}`);
|
|
140
|
+
const shown = files.slice(0, FILES_MAX);
|
|
141
|
+
parts.push(`Wrote: ${shown.length > 0 ? shown.join(', ') : `${writes.length} file(s)`}${files.length > FILES_MAX ? ` (+${files.length - FILES_MAX} more)` : ''}`);
|
|
142
|
+
parts.push(`Verify: ${verify}${command ? ` via ${command}` : ''}`);
|
|
143
|
+
if (unfinished.length > 0) parts.push(`Unfinished: ${unfinished.join('; ')}`);
|
|
144
|
+
return { text: parts.join('. ').slice(0, 900), files, verify, command, unfinished, hasTask: Boolean(task) };
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
export function episodeText(ledger, sessionId, opts = {}) {
|
|
148
|
+
void sessionId;
|
|
149
|
+
return buildEpisode(ledger, opts)?.text ?? null;
|
|
65
150
|
}
|
|
66
151
|
|
|
67
152
|
function ledgerSessionId(ledger, ledgerKey) {
|
|
@@ -69,12 +154,53 @@ function ledgerSessionId(ledger, ledgerKey) {
|
|
|
69
154
|
?? (ledgerKey ? ledgerKey.replace(/\.json$/, '') : 'unknown');
|
|
70
155
|
}
|
|
71
156
|
|
|
72
|
-
//
|
|
157
|
+
// Dedupe identity of one task's episode: session ledger key + taskInstanceId
|
|
158
|
+
// (the session key alone when the ledger has no task id).
|
|
159
|
+
export function taskKeyOf(ledgerKey, taskInstanceId) {
|
|
160
|
+
return taskInstanceId ? `${ledgerKey}#${taskInstanceId}` : ledgerKey;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
// Keys already recorded. Legacy records (ledgerKey only, no task id) keep the
|
|
164
|
+
// bare ledgerKey so they still dedupe a task-less ledger.
|
|
165
|
+
export function recordedEpisodeKeys(records) {
|
|
166
|
+
const keys = new Set();
|
|
167
|
+
for (const r of records) {
|
|
168
|
+
const m = r?.meta;
|
|
169
|
+
if (!m) continue;
|
|
170
|
+
if (m.taskKey) keys.add(m.taskKey);
|
|
171
|
+
else if (m.ledgerKey) keys.add(taskKeyOf(m.ledgerKey, m.taskInstanceId));
|
|
172
|
+
}
|
|
173
|
+
return keys;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
export const SPOOL_SUFFIX = '.episodes';
|
|
177
|
+
|
|
178
|
+
async function readSpool(projectRoot, ledgerKey) {
|
|
179
|
+
const list = await readJsonIfExists(path.join(projectRoot, LEDGER_DIR_REL, `${ledgerKey}${SPOOL_SUFFIX}`));
|
|
180
|
+
return Array.isArray(list) ? list.filter((e) => e && typeof e === 'object' && e.taskInstanceId) : [];
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
// Writes the episodes for one ledger file: one per spooled outgoing task, then the
|
|
184
|
+
// ledger's current task. Returns the status of the CURRENT task's episode
|
|
73
185
|
// { status: 'recorded', id, sessionId } | { status: 'duplicate' }
|
|
74
|
-
// | { status: '
|
|
75
|
-
//
|
|
76
|
-
//
|
|
77
|
-
|
|
186
|
+
// | { status: 'empty' } (no successful write → no episode)
|
|
187
|
+
// | { status: 'rejected', result } | { status: 'failed', reason }
|
|
188
|
+
// plus `spooled` = number of spooled tasks newly recorded.
|
|
189
|
+
// `existingKeys` (Set from recordedEpisodeKeys) skips the store read when batching.
|
|
190
|
+
export async function writeEpisode(projectRoot, opts = {}) {
|
|
191
|
+
const { ledger, ledgerKey, existingKeys } = opts;
|
|
192
|
+
const keys = existingKeys ?? recordedEpisodeKeys(await loadRecords(projectRoot, { homeDir: opts.homeDir }));
|
|
193
|
+
let spooled = 0;
|
|
194
|
+
for (const entry of await readSpool(projectRoot, ledgerKey)) {
|
|
195
|
+
if (entry.taskInstanceId === ledger?.taskInstanceId) continue;
|
|
196
|
+
const res = await writeTaskEpisode(projectRoot, { ...opts, ledger: entry, existingKeys: keys });
|
|
197
|
+
if (res.status === 'recorded') spooled += 1;
|
|
198
|
+
}
|
|
199
|
+
const res = await writeTaskEpisode(projectRoot, { ...opts, existingKeys: keys });
|
|
200
|
+
return { ...res, spooled };
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
async function writeTaskEpisode(projectRoot, {
|
|
78
204
|
ledger,
|
|
79
205
|
ledgerKey,
|
|
80
206
|
config,
|
|
@@ -83,11 +209,31 @@ export async function writeEpisode(projectRoot, {
|
|
|
83
209
|
existingKeys,
|
|
84
210
|
} = {}) {
|
|
85
211
|
const sessionId = ledgerSessionId(ledger, ledgerKey);
|
|
86
|
-
const
|
|
87
|
-
|
|
88
|
-
);
|
|
89
|
-
if (keys.has(ledgerKey)) return { status: 'duplicate' };
|
|
212
|
+
const taskKey = taskKeyOf(ledgerKey, ledger?.taskInstanceId);
|
|
213
|
+
const keys = existingKeys;
|
|
214
|
+
if (keys.has(taskKey)) return { status: 'duplicate' };
|
|
90
215
|
|
|
216
|
+
// A spool entry carries its own prompt; only the live ledger falls back to route-state.
|
|
217
|
+
const routeState = ledger?.taskPrompt !== undefined
|
|
218
|
+
? null
|
|
219
|
+
: await readRouteState(projectRoot, ledger?.sessionKey ?? ledger?.sessionId ?? sessionId);
|
|
220
|
+
const built = buildEpisode(ledger, { routeState, projectRoot });
|
|
221
|
+
if (!built) return { status: 'empty' };
|
|
222
|
+
const observedAt = Date.now();
|
|
223
|
+
const ev = (kind, locator) => ({
|
|
224
|
+
kind, locator: String(locator).slice(0, 512), observed_at: observedAt, fingerprint: null, trust_tier: 'verified',
|
|
225
|
+
});
|
|
226
|
+
// Prompt text can carry pasted secrets: redact with the shared write guard
|
|
227
|
+
// before the add (mutateMemory's reject-mode guard then sees clean text).
|
|
228
|
+
const { payload: guarded } = redactWritePayload({
|
|
229
|
+
text: built.text,
|
|
230
|
+
evidence: [
|
|
231
|
+
...built.files.slice(0, 6).map((f) => ev('file', f)),
|
|
232
|
+
...(built.command ? [ev('command', built.command)] : []),
|
|
233
|
+
ev('ledger', ledgerKey),
|
|
234
|
+
],
|
|
235
|
+
meta: { sessionId, ledgerKey, taskKey, taskInstanceId: ledger.taskInstanceId ?? null, verify: built.verify },
|
|
236
|
+
}, { config });
|
|
91
237
|
const ttlDays = Number(config?.memoryV2?.episodeTtlDays) || 90;
|
|
92
238
|
const resolvedProjectId = projectId
|
|
93
239
|
?? (await detectProjectContext(projectRoot, { homeDir })).project.name;
|
|
@@ -97,17 +243,18 @@ export async function writeEpisode(projectRoot, {
|
|
|
97
243
|
{ kind: 'project', projectRoot, homeDir },
|
|
98
244
|
{
|
|
99
245
|
op: 'add',
|
|
100
|
-
idempotencyKey:
|
|
246
|
+
idempotencyKey: taskKey,
|
|
101
247
|
payload: {
|
|
102
248
|
type: 'episode',
|
|
103
249
|
scope: 'session',
|
|
104
|
-
text:
|
|
250
|
+
text: guarded.text,
|
|
251
|
+
evidence: guarded.evidence,
|
|
105
252
|
provenance: 'exec-ledger',
|
|
106
253
|
confidence: 0.6,
|
|
107
254
|
createdBy: 'episode-hook',
|
|
108
255
|
projectId: resolvedProjectId,
|
|
109
256
|
validUntil: Date.now() + ttlDays * DAY_MS,
|
|
110
|
-
meta:
|
|
257
|
+
meta: guarded.meta,
|
|
111
258
|
},
|
|
112
259
|
},
|
|
113
260
|
);
|
|
@@ -116,7 +263,7 @@ export async function writeEpisode(projectRoot, {
|
|
|
116
263
|
if (res.status !== 'ok') {
|
|
117
264
|
return { status: 'failed', reason: `${res.status}${res.reason ? ` — ${res.reason}` : ''}` };
|
|
118
265
|
}
|
|
119
|
-
keys.add(
|
|
266
|
+
keys.add(taskKey);
|
|
120
267
|
return { status: 'recorded', id: res.record.id, sessionId };
|
|
121
268
|
}
|
|
122
269
|
|
|
@@ -137,30 +284,45 @@ export async function backfillEpisodes(projectRoot, {
|
|
|
137
284
|
}
|
|
138
285
|
const dir = path.join(projectRoot, LEDGER_DIR_REL);
|
|
139
286
|
const names = await listLedgerFiles(dir, limit);
|
|
140
|
-
|
|
141
|
-
const existingKeys = new Set(
|
|
142
|
-
(await loadRecords(projectRoot, { homeDir })).map((r) => r.meta?.ledgerKey).filter(Boolean),
|
|
143
|
-
);
|
|
287
|
+
const existingKeys = recordedEpisodeKeys(await loadRecords(projectRoot, { homeDir }));
|
|
144
288
|
const projectId = (await detectProjectContext(projectRoot, { homeDir })).project.name;
|
|
145
289
|
for (const name of names) {
|
|
146
290
|
summary.scanned += 1;
|
|
147
|
-
if (existingKeys.has(name)) { summary.skipped += 1; continue; }
|
|
148
291
|
let stat;
|
|
149
292
|
try { stat = await fs.stat(path.join(dir, name)); } catch { summary.skipped += 1; continue; }
|
|
150
293
|
if (now - stat.mtimeMs < idleMs) { summary.skipped += 1; continue; }
|
|
151
294
|
const ledger = await readJsonIfExists(path.join(dir, name));
|
|
152
|
-
|
|
153
|
-
if (!ledger || (receipts === 0 && ledger.writeSucceeded !== true)) {
|
|
154
|
-
summary.skipped += 1;
|
|
155
|
-
continue;
|
|
156
|
-
}
|
|
295
|
+
if (!ledger) { summary.skipped += 1; continue; }
|
|
157
296
|
const res = await writeEpisode(projectRoot, {
|
|
158
297
|
ledger, ledgerKey: name, config, homeDir, projectId, existingKeys,
|
|
159
298
|
});
|
|
299
|
+
summary.recorded += res.spooled ?? 0;
|
|
160
300
|
if (res.status === 'recorded') summary.recorded += 1;
|
|
161
|
-
else if (res.status === 'duplicate') summary.skipped += 1;
|
|
301
|
+
else if (res.status === 'duplicate' || res.status === 'empty') summary.skipped += 1;
|
|
162
302
|
else summary.failed += 1;
|
|
163
303
|
}
|
|
304
|
+
// Orphan spools: the ledger file was evicted by the dir sweep but its spool
|
|
305
|
+
// survived. Same dedupe keys, same idle rule (on the spool's mtime).
|
|
306
|
+
let dirNames = [];
|
|
307
|
+
try { dirNames = await fs.readdir(dir); } catch { /* none */ }
|
|
308
|
+
const present = new Set(dirNames);
|
|
309
|
+
for (const spoolName of dirNames) {
|
|
310
|
+
if (!spoolName.endsWith(`.json${SPOOL_SUFFIX}`)) continue;
|
|
311
|
+
const ledgerKey = spoolName.slice(0, -SPOOL_SUFFIX.length);
|
|
312
|
+
if (present.has(ledgerKey)) continue;
|
|
313
|
+
summary.scanned += 1;
|
|
314
|
+
let stat;
|
|
315
|
+
try { stat = await fs.stat(path.join(dir, spoolName)); } catch { summary.skipped += 1; continue; }
|
|
316
|
+
if (now - stat.mtimeMs < idleMs) { summary.skipped += 1; continue; }
|
|
317
|
+
for (const entry of await readSpool(projectRoot, ledgerKey)) {
|
|
318
|
+
const res = await writeTaskEpisode(projectRoot, {
|
|
319
|
+
ledger: entry, ledgerKey, config, homeDir, projectId, existingKeys,
|
|
320
|
+
});
|
|
321
|
+
if (res.status === 'recorded') summary.recorded += 1;
|
|
322
|
+
else if (res.status === 'duplicate' || res.status === 'empty') summary.skipped += 1;
|
|
323
|
+
else summary.failed += 1;
|
|
324
|
+
}
|
|
325
|
+
}
|
|
164
326
|
} catch (error) {
|
|
165
327
|
return { ...summary, reason: error?.message ?? String(error) };
|
|
166
328
|
}
|