@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
@@ -1,199 +0,0 @@
1
- // Development-only incident capture: bounded metadata, no session control or payload persistence.
2
- import fs from 'node:fs/promises';
3
- import { constants } from 'node:fs';
4
- import { spawn } from 'node:child_process';
5
-
6
- const ID_PATTERN = /^[\w.:/-]{1,120}$/;
7
- const id = (value) => typeof value === 'string' && ID_PATTERN.test(value) ? value : null;
8
- const time = (value) => Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : null;
9
-
10
-
11
- export async function runBoundedProcess(command, args = [], { timeoutMs = 650, maxBuffer = 65536 } = {}) {
12
- return new Promise((resolve) => {
13
- let settled = false;
14
- let timedOut = false;
15
- let oversized = false;
16
- let stdoutBytes = 0;
17
- let stderrBytes = 0;
18
- const stdout = [];
19
- const stderr = [];
20
- let timer;
21
- const finish = (result) => { if (!settled) { settled = true; clearTimeout(timer); resolve(result); } };
22
- let child;
23
- try { child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true }); }
24
- catch (error) { resolve({ ok: false, errorCode: error.code || 'UNKNOWN', stdout: '', stderr: '' }); return; }
25
- timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, Math.max(1, timeoutMs));
26
- const collect = (chunks, field) => (chunk) => {
27
- const next = field === 'stdout' ? stdoutBytes + chunk.length : stderrBytes + chunk.length;
28
- if (next + (field === 'stdout' ? stderrBytes : stdoutBytes) > maxBuffer) { oversized = true; child.kill('SIGKILL'); return; }
29
- chunks.push(chunk);
30
- if (field === 'stdout') stdoutBytes = next; else stderrBytes = next;
31
- };
32
- child.stdout.on('data', collect(stdout, 'stdout'));
33
- child.stderr.on('data', collect(stderr, 'stderr'));
34
- child.on('error', (error) => finish({ ok: false, errorCode: error.code || 'UNKNOWN', stdout: '', stderr: '' }));
35
- child.on('close', (code) => finish({ ok: !timedOut && !oversized && code === 0,
36
- errorCode: timedOut ? 'ETIMEDOUT' : oversized ? 'MAXBUFFER' : code === 0 ? null : 'EXIT_NONZERO',
37
- exitCode: code, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') }));
38
- });
39
- }
40
-
41
- export async function readBoundedTail(file, { maxBytes = 262144 } = {}) {
42
- const cap = Math.max(1, Math.min(1048576, maxBytes));
43
- const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NONBLOCK || 0) | (constants.O_NOFOLLOW || 0));
44
- try {
45
- const stat = await handle.stat();
46
- if (!stat.isFile()) throw new Error('capture requires a regular file');
47
- const size = Math.min(cap, stat.size);
48
- const buffer = Buffer.alloc(size);
49
- const { bytesRead } = await handle.read(buffer, 0, size, Math.max(0, stat.size - size));
50
- let text = buffer.subarray(0, bytesRead).toString('utf8');
51
- const truncated = stat.size > size;
52
- if (truncated) text = text.includes('\n') ? text.slice(text.indexOf('\n') + 1) : '';
53
- return { text, bytesRead, truncated, size: stat.size, modifiedAt: stat.mtimeMs };
54
- } finally { await handle.close(); }
55
- }
56
-
57
- const operationKinds = ['model', 'tool', 'hook', 'subagent'];
58
- const activeStates = new Set(['started', 'running', 'pending', 'waiting']);
59
- const terminalStates = new Set(['completed', 'finished', 'failed', 'stopped', 'cancelled']);
60
- export function processInventoryCommand(platform) {
61
- return platform === 'win32' ? ['tasklist', ['/FO', 'CSV', '/NH']]
62
- : ['ps', ['-A', '-o', 'pid=,ppid=,stat=,etime=,comm=']];
63
- }
64
-
65
- export function parseProcessInventory(platform, text) {
66
- if (platform === 'win32') return text.split(/\r?\n/).flatMap((line) => {
67
- const fields = line.match(/"(?:[^"]|"")*"|[^,]+/g) || [];
68
- const name = fields[0]?.replace(/^"|"$/g, '').replace(/""/g, '"');
69
- const pid = Number(fields[1]?.replaceAll('"', ''));
70
- return Number.isSafeInteger(pid) && pid > 0 ? [{ pid, name: (name || '').split(/[\\/]/).at(-1) }] : [];
71
- });
72
- return text.split('\n').flatMap((line) => {
73
- const match = line.match(/^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(.+)$/);
74
- return match ? [{ pid: Number(match[1]), name: match[5].trim().split(/[\\/]/).at(-1) }] : [];
75
- });
76
- }
77
-
78
- export function parseOwnerPids(command, text) {
79
- const values = command === 'fuser' ? (text.match(/:\s*([^\r\n]+)/g) || []).flatMap((line) => line.slice(line.indexOf(':') + 1).trim().split(/\s+/).map((token) => token.match(/^(\d+)[A-Za-z]*$/)?.[1]).filter(Boolean))
80
- : (text.match(/\b\d+\b/g) || []);
81
- return [...new Set(values.map(Number).filter((pid) => Number.isSafeInteger(pid) && pid > 0))];
82
- }
83
-
84
- export function classifySessionActivity({ association = 'NOT_OBSERVABLE', summary = null, now = Date.now(), idleMs = 120000 } = {}) {
85
- if (summary?.operatorBlock === 'OBSERVED_BLOCK') return 'OPERATOR_BLOCK';
86
- if (summary?.sessionState === 'STOPPED') return 'STOPPED';
87
- if (association !== 'ACTIVE_OWNER' || !summary) return 'NOT_OBSERVABLE';
88
- const progressAge = Number.isFinite(summary.lastProgressAt) ? Math.max(0, now - summary.lastProgressAt) : null;
89
- const outputAge = Number.isFinite(summary.lastOutputAt) ? Math.max(0, now - summary.lastOutputAt) : null;
90
- const pending = summary.pendingOperations || {};
91
- if (progressAge === null) return 'NOT_OBSERVABLE';
92
- if (progressAge >= idleMs) return 'SUSPECTED_STALL';
93
- if (Object.values(pending).some((items) => Array.isArray(items) && items.length > 0)
94
- && Object.entries(pending).some(([kind, items]) => items.length > 0 && summary.operationObservability?.[kind] === 'OBSERVED')) return 'WAITING';
95
- if (outputAge !== null && outputAge >= idleMs) return 'NO_OUTPUT';
96
- return 'ACTIVE_PROGRESS';
97
- }
98
-
99
-
100
- export function summarizeSessionTail(text) {
101
- const result = { sessionId: null, modelAlias: 'NOT_OBSERVABLE', resolvedRoute: 'NOT_OBSERVABLE', currentTurn: 'NOT_OBSERVABLE', lastCompletedTurn: 'NOT_OBSERVABLE',
102
- pendingModelRequest: 'NOT_OBSERVABLE', lastChunk: 'NOT_OBSERVABLE', terminalEvent: 'NOT_OBSERVABLE', pendingTools: [], unmatchedToolCallCandidates: [], pendingSubagent: 'NOT_OBSERVABLE',
103
- pendingOperations: { model: [], tool: [], hook: [], subagent: [] }, operationObservability: { model: 'NOT_OBSERVABLE', tool: 'NOT_OBSERVABLE', hook: 'NOT_OBSERVABLE', subagent: 'NOT_OBSERVABLE' },
104
- operatorBlock: 'NOT_OBSERVABLE', turnState: 'NOT_OBSERVABLE', sessionState: 'NOT_OBSERVABLE', compaction: 'NOT_OBSERVABLE', stopContinuation: 'NOT_OBSERVABLE',
105
- lastProgressAt: 'NOT_OBSERVABLE', lastOutputAt: 'NOT_OBSERVABLE', outputState: 'NOT_OBSERVABLE' };
106
- const operations = Object.fromEntries(operationKinds.map((kind) => [kind, new Map()]));
107
- const tools = new Map();
108
- const observedOperations = new Set();
109
- const operatorBlocks = new Map();
110
- for (const line of text.split('\n')) {
111
- let row;
112
- try { row = JSON.parse(line); } catch { continue; }
113
- const ts = time(row.timestamp);
114
- if (ts) result.lastProgressAt = Date.parse(ts);
115
- if (row.type === 'session' && id(row.id)) { result.sessionId = id(row.id); result.sessionIdentityObserved = true; }
116
- if (row.type === 'compaction') result.compaction = { timestamp: ts, id: id(row.id), tokensBefore: Number.isFinite(row.tokensBefore) ? row.tokensBefore : null };
117
- if (row.type === 'session_end' || row.type === 'session_stopped') result.sessionState = 'STOPPED';
118
-
119
- if (row.type === 'operation' && operationKinds.includes(row.operation) && id(row.id)) {
120
- observedOperations.add(row.operation);
121
- const state = typeof row.state === 'string' ? row.state.toLowerCase() : '';
122
- if (activeStates.has(state)) operations[row.operation].set(row.id, { id: row.id, ...(id(row.name) ? { name: id(row.name) } : {}) });
123
- if (terminalStates.has(state)) operations[row.operation].delete(row.id);
124
- }
125
- const eventState = String(row.state || '').toLowerCase();
126
- if (row.type === 'operator_block' || row.operation === 'operator') {
127
- const key = id(row.id) || `block-${operatorBlocks.size}`;
128
- if (['pending', 'blocked', 'waiting'].includes(eventState)) operatorBlocks.set(key, { id: id(row.id), state: 'BLOCKED' });
129
- if (terminalStates.has(eventState) || ['unblocked', 'cleared'].includes(eventState)) operatorBlocks.delete(key);
130
- }
131
-
132
- const message = row.message;
133
- if (!message) continue;
134
- if (message.role === 'toolResult' && id(message.toolCallId)) tools.delete(message.toolCallId);
135
- if (message.role !== 'assistant') continue;
136
- result.modelAlias = { provider: id(message.provider), model: id(message.model) };
137
- if (message.stopReason) {
138
- const stopReason = ['stop', 'toolUse', 'error', 'aborted', 'length'].includes(message.stopReason) ? message.stopReason : 'other';
139
- result.lastCompletedTurn = { id: id(row.id), timestamp: ts, stopReason };
140
- result.terminalEvent = stopReason;
141
- result.turnState = message.stopReason === 'aborted' ? 'TURN_ABORTED' : message.stopReason === 'error' ? 'TURN_ERROR' : 'TURN_COMPLETED';
142
- }
143
- if (Array.isArray(message.content)) {
144
- for (const part of message.content) {
145
- if (part.type === 'toolCall' && id(part.id)) tools.set(part.id, { id: id(part.id), name: id(part.name) });
146
- if (part.type === 'text' && ts) {
147
- result.lastOutputAt = Date.parse(ts);
148
- result.outputState = 'OBSERVED_OUTPUT';
149
- }
150
- }
151
- }
152
- }
153
- result.unmatchedToolCallCandidates = [...tools.values()].slice(-32);
154
- result.pendingOperations = Object.fromEntries(operationKinds.map((kind) => [kind, [...operations[kind].values()].slice(-32)]));
155
- result.pendingTools = result.pendingOperations.tool;
156
- result.operationObservability = Object.fromEntries(operationKinds.map((kind) => [kind, observedOperations.has(kind) || (kind === 'tool' && tools.size > 0) ? 'OBSERVED' : 'NOT_OBSERVABLE']));
157
- result.pendingModelRequest = result.operationObservability.model === 'OBSERVED' ? (result.pendingOperations.model.length ? 'OBSERVED_PENDING_EVENT' : 'NO_PENDING_EVENT_OBSERVED') : 'NOT_OBSERVABLE';
158
- result.pendingSubagent = result.operationObservability.subagent === 'OBSERVED' ? (result.pendingOperations.subagent.length ? 'OBSERVED_PENDING_EVENT' : 'NO_PENDING_EVENT_OBSERVED') : 'NOT_OBSERVABLE';
159
- result.operatorBlock = operatorBlocks.size ? 'OBSERVED_BLOCK' : 'NOT_OBSERVABLE';
160
- return result;
161
- }
162
-
163
- export function associateSessionEvidence({ sessions = [], ownerLocks = {}, processInventory = { state: 'NOT_OBSERVABLE', processes: [] }, logs = [] } = {}) {
164
- const sessionCounts = new Map();
165
- for (const session of sessions) if (id(session.sessionId)) sessionCounts.set(session.sessionId, (sessionCounts.get(session.sessionId) || 0) + 1);
166
- return sessions.map((session) => {
167
- const sessionId = id(session.sessionId);
168
- const lock = sessionId ? ownerLocks[sessionId] : null;
169
- const lockState = lock?.state || 'NOT_OBSERVABLE';
170
- const pids = lockState === 'OBSERVED' && Array.isArray(lock.pids) ? [...new Set(lock.pids.filter((pid) => Number.isSafeInteger(pid) && pid > 0))] : [];
171
- const uniqueOwnerPid = pids.length === 1 ? pids[0] : null;
172
- const duplicateSession = sessionId !== null && sessionCounts.get(sessionId) > 1;
173
- const process = uniqueOwnerPid !== null && processInventory.state === 'OBSERVED'
174
- ? processInventory.processes.find((entry) => entry.pid === uniqueOwnerPid && /^omp(?:\.exe)?$/i.test(entry.name)) || null : null;
175
- const processAssociation = duplicateSession ? 'AMBIGUOUS_TRANSCRIPT' : pids.length > 1 ? 'AMBIGUOUS_OWNER_LOCK'
176
- : uniqueOwnerPid === null ? (lockState === 'NOT_OBSERVABLE' ? 'NOT_OBSERVABLE' : 'UNHELD')
177
- : processInventory.state !== 'OBSERVED' ? 'NOT_OBSERVABLE' : process ? 'VERIFIED' : 'PID_NOT_FOUND';
178
- const ownerPid = duplicateSession ? null : uniqueOwnerPid;
179
- const identityVerified = session?.sessionIdentityObserved === true || session?.sourceCoverage?.sessionIdentityObserved === true;
180
- const ompLog = ownerPid === null ? null : logs.find((entry) => entry.pid === ownerPid) || null;
181
- const logAssociation = ownerPid === null ? 'NOT_OBSERVABLE' : ompLog ? 'VERIFIED' : 'NOT_OBSERVABLE';
182
- return { sessionId, transcript: typeof session.transcriptPath === 'string' ? session.transcriptPath.split(/[\\/]/).at(-1) : null,
183
- sessionAssociation: identityVerified && processAssociation === 'VERIFIED' && logAssociation === 'VERIFIED' ? 'ACTIVE_OWNER' : 'NOT_OBSERVABLE',
184
- ownerLockState: duplicateSession ? 'AMBIGUOUS_TRANSCRIPT' : lockState, ownerPid, processAssociation, logAssociation, identityVerified,
185
- process: process ? { pid: process.pid, name: id(process.name) } : null, ompLog };
186
- });
187
- }
188
-
189
- export function buildStallSnapshot({ now = Date.now(), lastProgressAt = null, lastOutputAt = null, idleMs = 120000, executionState = 'NOT_OBSERVABLE', ...evidence } = {}) {
190
- const age = (ts) => Number.isFinite(ts) ? Math.max(0, now - ts) : null;
191
- const progressAgeMs = age(lastProgressAt);
192
- const outputAgeMs = age(lastOutputAt);
193
- const activity = evidence.activity || (executionState === 'NO_EXECUTION' ? 'NO_EXECUTION'
194
- : executionState !== 'EXECUTING' ? 'NOT_OBSERVABLE'
195
- : progressAgeMs === null ? 'NOT_OBSERVABLE' : progressAgeMs >= idleMs ? 'NO_OBSERVED_PROGRESS'
196
- : outputAgeMs !== null && outputAgeMs >= idleMs ? 'NO_OUTPUT' : 'RECENT_PROGRESS');
197
- return { schemaVersion: 1, capturedAt: new Date(now).toISOString(), verdict: 'INSUFFICIENT_EVIDENCE', activity,
198
- executionState, progressAgeMs, outputAgeMs, ...evidence };
199
- }
@@ -1,285 +0,0 @@
1
- import fs from 'node:fs/promises';
2
- import path from 'node:path';
3
-
4
- import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, normalizeRelative } from './paths.js';
5
- import { getFileOutline, queryCodeIndex } from './queryIndex.js';
6
- import { inferRelatedTests } from './relatedTests.js';
7
- import { discoverProjectFiles } from './buildIndex.js';
8
- import { isSensitivePath } from './sensitivePath.js';
9
-
10
- // TASK-B2 (PLAN-ENDUR-B §B2): deterministic, bounded context pack built from the
11
- // existing index artifacts. No LLM, no network, no clock/random — the same
12
- // inputs + the same index always serialize to byte-identical JSON.
13
- //
14
- // Contract notes (recorded in TASK-B2 Discussion):
15
- // - `overBudget` (global constraint "flags overBudget instead of dropping a
16
- // required item"): required entries (targets) are always admitted; if the
17
- // admitted set alone violates maxBytes/maxFiles the pack says so honestly
18
- // instead of silently dropping a target. `truncated` marks extras
19
- // (related tests) dropped for budget — the pack then never exceeds the bounds.
20
- // - `fallback: 'path-only'` is set when the index artifacts are missing/corrupt
21
- // (whole pack is raw target paths) OR when any individual target could not be
22
- // resolved through the index (that target is listed as a raw path).
23
- // - `index` accepts preloaded `{ meta, files }` artifacts to override the disk
24
- // reads used for targeting/fingerprint; symbol outlines still come from the
25
- // on-disk symbols artifact via getFileOutline.
26
-
27
- export const DEFAULT_MAX_BYTES = 12000;
28
- export const DEFAULT_MAX_FILES = 8;
29
-
30
- const TARGET_SCORE = 1000;
31
- const RELATED_TEST_SCORE = 12;
32
- const SYMBOL_QUERY_LIMIT = 3;
33
- const RELATED_TEST_LIMIT = 6;
34
-
35
- const REQUIRED_REASONS = new Set(['target', 'target-symbol', 'unresolved-target', 'path-only']);
36
-
37
- /**
38
- * Build a deterministic, bounded context pack from the existing index.
39
- *
40
- * @param {object} [options]
41
- * @param {string} [options.rootDir] Project root (default: cwd).
42
- * @param {string[]} [options.targets] Target paths or symbol names.
43
- * @param {number} [options.maxBytes] Byte budget for the files payload (default 12000).
44
- * @param {number} [options.maxFiles] File-count budget (default 8).
45
- * @param {{meta?: object, files?: object}} [options.index] Preloaded meta/files artifacts.
46
- * @returns {Promise<{ok: boolean, files: Array<{path: string, reason: string, outline: Array, bytes: number}>,
47
- * truncated: boolean, overBudget: boolean, stale: boolean, fallback: 'path-only'|null,
48
- * bytes: number, fingerprint: {fileCount: number, newestMtimeMs: number, digest: string|null}|null}>}
49
- * Never throws: every failure mode degrades to `ok: true` with a degraded pack.
50
- */
51
- export async function buildContextPack({
52
- rootDir = process.cwd(),
53
- targets = [],
54
- maxBytes = DEFAULT_MAX_BYTES,
55
- maxFiles = DEFAULT_MAX_FILES,
56
- index = null,
57
- } = {}) {
58
- const absoluteRoot = path.resolve(rootDir);
59
- const byteBudget = normalizeBudget(maxBytes, DEFAULT_MAX_BYTES);
60
- const fileBudget = normalizeBudget(maxFiles, DEFAULT_MAX_FILES);
61
- const requestedTargets = normalizeTargets(targets);
62
-
63
- const [filesArtifact, metaArtifact] = await Promise.all([
64
- index?.files ?? readJsonArtifact(absoluteRoot, INDEX_ARTIFACTS.files),
65
- index?.meta ?? readJsonArtifact(absoluteRoot, INDEX_ARTIFACTS.meta),
66
- ]);
67
-
68
- const indexUsable = isValidItemArtifact(filesArtifact) && isValidSchemaArtifact(metaArtifact);
69
- const recordedFingerprint = normalizeRecordedFingerprint(metaArtifact?.sourceFingerprint);
70
-
71
- // Staleness: compare meta.sourceFingerprint's file count / newest mtime to a
72
- // fresh discovery enumeration. No auto refresh, no clock — pure comparison.
73
- let stale = false;
74
- if (indexUsable) {
75
- if (!recordedFingerprint) {
76
- stale = true;
77
- } else {
78
- const discovered = await discoverProjectFiles(absoluteRoot).catch(() => null);
79
- stale = discovered
80
- ? isFingerprintStale(recordedFingerprint, fingerprintMetaFromEntries(absoluteRoot, discovered))
81
- : true;
82
- }
83
- }
84
-
85
- const candidates = [];
86
- let anyUnresolved = false;
87
-
88
- if (indexUsable) {
89
- const indexedFileSet = new Set(
90
- filesArtifact.items
91
- .filter((item) => item && typeof item === 'object' && typeof item.filePath === 'string')
92
- .map((item) => item.filePath),
93
- );
94
-
95
- let rank = 0;
96
- const resolvedTargetPaths = [];
97
- for (const target of requestedTargets) {
98
- if (isSensitivePath(target)) {
99
- rank += 1;
100
- continue;
101
- }
102
- const score = Math.max(1, TARGET_SCORE - rank);
103
- rank += 1;
104
-
105
- const directPath = normalizeTargetPath(target);
106
- if (indexedFileSet.has(directPath)) {
107
- candidates.push({ path: directPath, reason: 'target', score });
108
- resolvedTargetPaths.push(directPath);
109
- continue;
110
- }
111
-
112
- const queryHits = await queryCodeIndex({ rootDir: absoluteRoot, query: target, limit: SYMBOL_QUERY_LIMIT })
113
- .catch(() => []);
114
- const bestHit = queryHits.find((hit) => hit?.filePath && !isSensitivePath(hit.filePath));
115
- if (bestHit) {
116
- candidates.push({ path: bestHit.filePath, reason: 'target-symbol', score });
117
- resolvedTargetPaths.push(bestHit.filePath);
118
- } else {
119
- anyUnresolved = true;
120
- candidates.push({ path: directPath, reason: 'unresolved-target', score });
121
- }
122
- }
123
-
124
- const relatedTests = resolvedTargetPaths.length > 0
125
- ? await inferRelatedTests({ rootDir: absoluteRoot, candidateFiles: resolvedTargetPaths, limit: RELATED_TEST_LIMIT })
126
- .catch(() => [])
127
- : [];
128
- for (const related of relatedTests) {
129
- if (!related?.filePath || isSensitivePath(related.filePath)) {
130
- continue;
131
- }
132
- candidates.push({ path: related.filePath, reason: 'related-test', score: RELATED_TEST_SCORE });
133
- }
134
- } else {
135
- // Missing/corrupt index: path-only fallback listing the raw target paths.
136
- anyUnresolved = requestedTargets.length > 0;
137
- let rank = 0;
138
- for (const target of requestedTargets) {
139
- if (isSensitivePath(target)) {
140
- rank += 1;
141
- continue;
142
- }
143
- candidates.push({
144
- path: normalizeTargetPath(target),
145
- reason: 'path-only',
146
- score: Math.max(1, TARGET_SCORE - rank),
147
- });
148
- rank += 1;
149
- }
150
- }
151
-
152
- // Stable order: score desc, then path asc (plan §B2 acceptance).
153
- candidates.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
154
-
155
- const seenPaths = new Set();
156
- const deduped = candidates.filter((candidate) => {
157
- if (seenPaths.has(candidate.path)) {
158
- return false;
159
- }
160
- seenPaths.add(candidate.path);
161
- return true;
162
- });
163
-
164
- const withOutline = indexUsable;
165
- const selected = [];
166
- let usedBytes = 0;
167
- for (const candidate of deduped.filter((entry) => REQUIRED_REASONS.has(entry.reason))) {
168
- const entry = await materializeEntry(absoluteRoot, candidate, withOutline);
169
- selected.push(entry);
170
- usedBytes += entry.bytes;
171
- }
172
-
173
- let truncated = false;
174
- for (const candidate of deduped.filter((entry) => !REQUIRED_REASONS.has(entry.reason))) {
175
- const entry = await materializeEntry(absoluteRoot, candidate, withOutline);
176
- if (selected.length >= fileBudget || usedBytes + entry.bytes > byteBudget) {
177
- truncated = true;
178
- continue;
179
- }
180
- selected.push(entry);
181
- usedBytes += entry.bytes;
182
- }
183
-
184
- const overBudget = selected.length > fileBudget || usedBytes > byteBudget;
185
-
186
- return {
187
- ok: true,
188
- files: selected,
189
- truncated,
190
- overBudget,
191
- stale,
192
- fallback: !indexUsable || anyUnresolved ? 'path-only' : null,
193
- bytes: usedBytes,
194
- fingerprint: recordedFingerprint,
195
- };
196
- }
197
-
198
- function normalizeBudget(value, defaultValue) {
199
- const parsed = Number(value);
200
- return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultValue;
201
- }
202
-
203
- function normalizeTargets(targets) {
204
- const list = Array.isArray(targets) ? targets : [targets];
205
- const seen = new Set();
206
- const normalized = [];
207
- for (const raw of list) {
208
- const value = String(raw ?? '').trim();
209
- if (!value || seen.has(value)) {
210
- continue;
211
- }
212
- seen.add(value);
213
- normalized.push(value);
214
- }
215
- return normalized;
216
- }
217
-
218
- function normalizeTargetPath(target) {
219
- return String(target ?? '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
220
- }
221
-
222
- async function materializeEntry(absoluteRoot, candidate, withOutline) {
223
- const outline = withOutline
224
- ? await getFileOutline({ rootDir: absoluteRoot, filePath: candidate.path }).catch(() => [])
225
- : [];
226
- const row = { path: candidate.path, reason: candidate.reason, outline, bytes: 0 };
227
- row.bytes = Buffer.byteLength(JSON.stringify({ path: row.path, reason: row.reason, outline }));
228
- return row;
229
- }
230
-
231
- async function readJsonArtifact(rootDir, artifactName) {
232
- try {
233
- const content = await fs.readFile(getArtifactPath(rootDir, artifactName), 'utf8');
234
- return JSON.parse(content);
235
- } catch {
236
- return null;
237
- }
238
- }
239
-
240
- // Same gate queryIndex applies (C92-B-03): artifacts written under a different
241
- // INDEX_SCHEMA_VERSION are treated as absent. Item artifacts (files.json) must
242
- // carry an `items` array; meta.json has none, so schema currency is its only gate.
243
- function isValidItemArtifact(artifact) {
244
- return Boolean(
245
- artifact
246
- && typeof artifact === 'object'
247
- && Array.isArray(artifact.items)
248
- && artifact.schemaVersion === INDEX_SCHEMA_VERSION,
249
- );
250
- }
251
-
252
- function isValidSchemaArtifact(artifact) {
253
- return Boolean(artifact && typeof artifact === 'object' && artifact.schemaVersion === INDEX_SCHEMA_VERSION);
254
- }
255
-
256
- function normalizeRecordedFingerprint(raw) {
257
- if (!raw || typeof raw !== 'object') {
258
- return null;
259
- }
260
- return {
261
- fileCount: Number(raw.fileCount),
262
- newestMtimeMs: Number(raw.newestMtimeMs),
263
- digest: typeof raw.digest === 'string' ? raw.digest : null,
264
- };
265
- }
266
-
267
- function isFingerprintStale(recorded, current) {
268
- return recorded.fileCount !== current.fileCount || recorded.newestMtimeMs !== current.newestMtimeMs;
269
- }
270
-
271
- // Mirrors createSourceFingerprint's normalization (buildIndex.js) for the two
272
- // fields the plan's staleness contract compares: fileCount and newestMtimeMs.
273
- function fingerprintMetaFromEntries(rootDir, entries) {
274
- let fileCount = 0;
275
- let newestMtimeMs = 0;
276
- for (const entry of Array.isArray(entries) ? entries : []) {
277
- const filePath = normalizeRelative(rootDir, entry?.absolutePath ?? '');
278
- if (!filePath || filePath === '.' || filePath.startsWith('../') || path.isAbsolute(filePath)) {
279
- continue;
280
- }
281
- fileCount += 1;
282
- newestMtimeMs = Math.max(newestMtimeMs, Number(entry.mtimeMs ?? -1));
283
- }
284
- return { fileCount, newestMtimeMs };
285
- }