@ngockhoale/ukit 3.5.3 → 3.5.5

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 (70) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/manifests/documentation.yaml +12 -1
  3. package/manifests/platform.full.yaml +12 -0
  4. package/package.json +29 -2
  5. package/src/cli/commands/doctor.js +41 -0
  6. package/src/cli/commands/indexTools.js +10 -4
  7. package/src/cli/commands/memory.js +88 -6
  8. package/src/core/memory/episodes.js +106 -7
  9. package/src/core/memory/memoryCheck.js +241 -0
  10. package/src/core/memory/memoryCheckRun.js +39 -0
  11. package/src/core/memory/memoryHit.js +31 -15
  12. package/src/core/memory/mutateMemory.js +37 -1
  13. package/src/core/memory/observations.js +192 -0
  14. package/src/core/memory/recallEngine.js +159 -10
  15. package/src/core/memory/recallLanes.js +182 -0
  16. package/src/core/memory/records.js +23 -0
  17. package/src/core/memory/retrieval.js +13 -1
  18. package/src/core/memory/topicCommand.js +75 -0
  19. package/src/core/memory/topicPages.js +545 -0
  20. package/src/core/memory/writeGate.js +137 -0
  21. package/src/core/runtimeConfig.js +56 -1
  22. package/src/decision/registry.js +17 -0
  23. package/src/index/buildIndex.js +312 -5
  24. package/src/index/languageTools.js +100 -0
  25. package/src/index/paths.js +4 -1
  26. package/src/index/queryIndex.js +356 -14
  27. package/src/index/resolveContext.js +1 -1
  28. package/template_project/.claude/hooks/edit-hint.mjs +64 -17
  29. package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
  30. package/template_project/.claude/hooks/session-episode.sh +9 -4
  31. package/template_project/.claude/settings.json +2 -2
  32. package/template_project/.claude/ukit/index/lib/index-core.mjs +769 -18
  33. package/template_project/.claude/ukit/index/query-index.mjs +14 -3
  34. package/template_project/.claude/ukit/index/refresh-index.mjs +11 -0
  35. package/template_project/.claude/ukit/index/route-task.mjs +4 -1
  36. package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
  37. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +9 -2
  38. package/template_project/.claude/ukit/runtime/memory-recall.mjs +159 -10
  39. package/template_project/.claude/ukit/runtime/memory-topics.mjs +545 -0
  40. package/template_project/.claude/ukit/runtime/memory-validity.mjs +28 -1
  41. package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
  42. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  43. package/template_project/ukit/storage/config.json +21 -2
  44. package/manifests/instructionRules.yaml +0 -442
  45. package/src/core/agentRuntime/completionGate.js +0 -179
  46. package/src/core/agentRuntime/context.js +0 -571
  47. package/src/core/agentRuntime/qualityComparison.js +0 -112
  48. package/src/core/agentRuntime/resourcePolicy.js +0 -78
  49. package/src/core/agentRuntime/runtimeSupport.js +0 -255
  50. package/src/core/codeintel/manifest.js +0 -176
  51. package/src/core/experiments/deliberation.js +0 -327
  52. package/src/core/experiments/dynamicWorkflow.js +0 -507
  53. package/src/core/handoffDocValidator.js +0 -154
  54. package/src/core/memory/deltaOverlays.js +0 -493
  55. package/src/core/memory/learningCandidates.js +0 -347
  56. package/src/core/observability/emit/sessionBoot.js +0 -407
  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/index/contextPack.js +0 -285
  68. package/src/index/impactContext.js +0 -360
  69. package/src/index/reviewPolicy.js +0 -368
  70. package/src/index/sensitivePath.js +0 -21
@@ -1,150 +0,0 @@
1
- // src/decision/runtimeFilter.js — pure (no I/O, no config, no gateway).
2
- // C65 G3-FR01 — deterministic pre-filter for G1/G2 SemanticEvents.
3
- // Known signals are decided locally and must NEVER produce a model call
4
- // downstream; only genuinely ambiguous items return action 'model_decision'
5
- // with a registered `runtime.*.v1` decisionKey.
6
- //
7
- // Interface (SPEC §4, frozen):
8
- // classifyRuntimeEvent(event, policy?) -> {
9
- // action: 'local_transition'|'local_observation'|'local_action'
10
- // |'model_decision'|'escalate'|'ignore',
11
- // priority: 'critical'|'decision'|'progress',
12
- // coalesceKey?: string, // only for coalescible progress
13
- // decisionKey?: string, // only when action='model_decision'
14
- // reason: string }
15
- //
16
- // Consumes: SemanticEvent { eventType, safePayload, operationId, seq, ... }
17
- // from src/core/agentRuntime/contract.js; liveness class vocabulary from
18
- // src/core/agentRuntime/liveness.js.
19
- // Consumed by: runtimeScheduler.submit (TASK-002), runtimeDecide (TASK-003).
20
-
21
- import { TERMINAL_STATES } from '../core/agentRuntime/contract.js';
22
- import { LIVENESS_CLASSES } from '../core/agentRuntime/liveness.js';
23
-
24
- const TERMINAL_SET = new Set(TERMINAL_STATES);
25
- const LIVENESS_SET = new Set(LIVENESS_CLASSES);
26
-
27
- // Observation classes that represent redundant progress — safe to coalesce
28
- // by key, latest wins (SPEC §5).
29
- const COALESCIBLE_CLASSES = new Set(['live_progressing', 'silent_live']);
30
-
31
- // Observation classes where a stall decision may be needed: with an explicit
32
- // spec/policy stallAction the action is deterministic; without one the item
33
- // is ambiguous and goes to the model via runtime.stall_action.v1.
34
- const STALL_CLASSES = new Set(['stalled', 'timeout']);
35
-
36
- // Ambiguous items that need a semantic decision: which decision key each
37
- // maps to. Keys must be registered in the decision registry (TASK-003).
38
- const DECISION_KEYS = Object.freeze({
39
- stall: 'runtime.stall_action.v1',
40
- ambiguous: 'runtime.wake_needed.v1',
41
- });
42
-
43
- // Signals that a human/authorization boundary must resolve — never dropped,
44
- // never coalesced, never auto-acted-on.
45
- const ESCALATION_EVENT_TYPE = /permission|input[_-]?required|authoriz/i;
46
- const ESCALATION_CLASS = /permission|input[_-]?required|authoriz|approval/i;
47
-
48
- function result(action, priority, reason, extra) {
49
- return { action, priority, reason, ...extra };
50
- }
51
-
52
- const ignore = (reason) => result('ignore', 'progress', reason);
53
-
54
- /**
55
- * Classify one runtime SemanticEvent into a local action, a model-decision
56
- * candidate, an escalation, or ignore. Pure: no I/O, no config import.
57
- *
58
- * @param {object} event G1 SemanticEvent envelope
59
- * @param {object} [policy] { stallAction?: string } — explicit spec policy
60
- * @returns {{action:string,priority:string,coalesceKey?:string,
61
- * decisionKey?:string,reason:string}}
62
- */
63
- export function classifyRuntimeEvent(event, policy) {
64
- if (event === null || typeof event !== 'object' || Array.isArray(event)) {
65
- return ignore('malformed_event');
66
- }
67
- const eventType = event.eventType;
68
- if (typeof eventType !== 'string' || eventType.length === 0) {
69
- return ignore('malformed_event');
70
- }
71
-
72
- // Permission / user-input / authorization signals escalate deterministically,
73
- // regardless of the channel they arrive on.
74
- if (ESCALATION_EVENT_TYPE.test(eventType)) {
75
- return result('escalate', 'critical', `escalation_signal:${eventType}`);
76
- }
77
-
78
- const safePayload = event.safePayload;
79
- const operationId =
80
- typeof event.operationId === 'string' && event.operationId.length > 0
81
- ? event.operationId
82
- : 'unknown';
83
-
84
- switch (eventType) {
85
- case 'operation.transition': {
86
- if (typeof safePayload !== 'object' || safePayload === null) {
87
- return result('model_decision', 'decision', 'unparseable_payload', {
88
- decisionKey: DECISION_KEYS.ambiguous,
89
- });
90
- }
91
- const to = safePayload.to;
92
- if (TERMINAL_SET.has(to)) {
93
- return result('local_transition', 'critical', `terminal_transition:${to}`);
94
- }
95
- // Non-terminal transition (queued→running, recovery_required, …):
96
- // known signal, decided locally; never reaches the model.
97
- return result('local_transition', 'progress', `transition:${to ?? 'unknown'}`);
98
- }
99
-
100
- case 'operation.observation': {
101
- if (typeof safePayload !== 'object' || safePayload === null) {
102
- return result('model_decision', 'decision', 'unparseable_payload', {
103
- decisionKey: DECISION_KEYS.ambiguous,
104
- });
105
- }
106
- const cls = safePayload.class;
107
-
108
- if (typeof cls === 'string' && ESCALATION_CLASS.test(cls)) {
109
- return result('escalate', 'critical', `escalation_signal:${cls}`);
110
- }
111
-
112
- if (COALESCIBLE_CLASSES.has(cls)) {
113
- return result('local_observation', 'progress', `observation:${cls}`, {
114
- coalesceKey: `obs:${operationId}:${cls}`,
115
- });
116
- }
117
-
118
- if (STALL_CLASSES.has(cls)) {
119
- const stallAction =
120
- policy && typeof policy === 'object' && typeof policy.stallAction === 'string'
121
- ? policy.stallAction
122
- : null;
123
- if (stallAction) {
124
- return result('local_action', 'critical', `policy_stall_action:${stallAction}:${cls}`);
125
- }
126
- return result('model_decision', 'decision', `ambiguous_stall:${cls}`, {
127
- decisionKey: DECISION_KEYS.stall,
128
- });
129
- }
130
-
131
- if (LIVENESS_SET.has(cls)) {
132
- // 'exited' — the only remaining liveness class. Terminal-adjacent
133
- // sample signal: critical so it is never dropped/starved by progress.
134
- return result('local_observation', 'critical', `observation:${cls}`);
135
- }
136
-
137
- // Unrecognized observation class — ambiguous.
138
- return result('model_decision', 'decision', `unknown_observation_class:${cls ?? 'none'}`, {
139
- decisionKey: DECISION_KEYS.ambiguous,
140
- });
141
- }
142
-
143
- default:
144
- // Valid envelope shape but a vocabulary the filter does not own —
145
- // ambiguous, candidate for a semantic decision.
146
- return result('model_decision', 'decision', `unknown_event_type:${eventType}`, {
147
- decisionKey: DECISION_KEYS.ambiguous,
148
- });
149
- }
150
- }
@@ -1,239 +0,0 @@
1
- /**
2
- * runtimeScheduler.js (G3-FR02)
3
- *
4
- * Bounded 3-tier queue for classified runtime items (SPEC §4):
5
- * - critical : terminal/failure/cancel/permission — emitted directly via
6
- * emitFn at flush; never dropped, never coalesced, never
7
- * counted against maxQueue, always drained first.
8
- * - decision : ambiguous items awaiting decideFn.
9
- * - progress : redundant progress — coalesced by coalesceKey while an
10
- * entry is pending (latest wins); eligible for drain after
11
- * coalesceWindowMs from first arrival.
12
- *
13
- * Serial drain (maxInFlight = 1 — the gateway is a single local model).
14
- * decideFn failures convert to typed Fallback objects emitted via emitFn;
15
- * a decideFn that never resolves yields { code:'timeout' }.
16
- *
17
- * Pure module: no I/O, no config. All dependencies injected via opts.
18
- */
19
-
20
- import { resolveConfigStage } from '../core/runtimeConfig.js';
21
- import { selectResourcePolicy } from '../core/agentRuntime/resourcePolicy.js';
22
-
23
- // G6 (DR-09): `decisionRuntime.resourcePolicy.stage` — absent/malformed →
24
- // 'off'; 'shadow' consults selectResourcePolicy on submit and records a
25
- // bounded receipt WITHOUT changing enqueue behavior. A policy throw or
26
- // malformed decision deterministically falls back to the prior path.
27
- const RESOURCE_FLAG = 'decisionRuntime.resourcePolicy.stage';
28
- const RESOURCE_RECEIPT_CAP = 128;
29
-
30
- // priority → eventClass for the resource consult. Scheduler-internal,
31
- // fail-open: unknown priorities consult as 'progress' (the only coalescible
32
- // class); malformed input still resolves emit downstream.
33
- const EVENT_CLASS_BY_PRIORITY = Object.freeze({
34
- critical: 'terminal',
35
- progress: 'progress',
36
- decision: 'progress',
37
- });
38
-
39
- const DEFAULT_COALESCE_WINDOW_MS = 250;
40
- const DEFAULT_MAX_QUEUE = 256;
41
- const DEFAULT_DECISION_TIMEOUT_MS = 5000;
42
-
43
- function fallback(code, item) {
44
- return { decidedBy: 'fallback', code, action: item?.action ?? 'ignore' };
45
- }
46
-
47
- export function createScheduler(opts = {}) {
48
- const decideFn = opts.decideFn ?? (async () => fallback('unavailable'));
49
- const emitFn = opts.emitFn ?? (() => {});
50
- const now = opts.now ?? (() => Date.now());
51
- const coalesceWindowMs = opts.coalesceWindowMs ?? DEFAULT_COALESCE_WINDOW_MS;
52
- const maxQueue = opts.maxQueue ?? DEFAULT_MAX_QUEUE;
53
- const decisionTimeoutMs = opts.decisionTimeoutMs ?? DEFAULT_DECISION_TIMEOUT_MS;
54
- // maxInFlight accepted for forward-compat; drain is serial regardless.
55
- void (opts.maxInFlight ?? 1);
56
-
57
- const resourceStage = () => resolveConfigStage(opts.config ?? null, RESOURCE_FLAG);
58
- const resourcePolicyFn = typeof opts.resourcePolicyFn === 'function'
59
- ? opts.resourcePolicyFn
60
- : selectResourcePolicy;
61
- const resourcesFn = typeof opts.resourcesFn === 'function'
62
- ? opts.resourcesFn
63
- : () => ({});
64
- const resourceReceipts = [];
65
-
66
- function recordResourceReceipt(entry) {
67
- if (resourceReceipts.length >= RESOURCE_RECEIPT_CAP) resourceReceipts.shift();
68
- resourceReceipts.push(Object.freeze(entry));
69
- }
70
-
71
- /**
72
- * Shadow consult: evaluate the resource policy for this submit and record
73
- * a bounded receipt. Never changes enqueue behavior; never throws.
74
- */
75
- function consultResourcePolicy(item) {
76
- let decision;
77
- let error;
78
- try {
79
- const resources = resourcesFn() ?? {};
80
- decision = resourcePolicyFn({
81
- cpuPressure: typeof resources.cpuPressure === 'string' ? resources.cpuPressure : 'normal',
82
- eventClass: EVENT_CLASS_BY_PRIORITY[item?.priority] ?? 'progress',
83
- queueDepth: boundedSize(),
84
- });
85
- } catch (err) {
86
- error = String(err?.message ?? err);
87
- }
88
- const valid = decision !== null && typeof decision === 'object'
89
- && (decision.action === 'emit' || decision.action === 'coalesce' || decision.action === 'defer');
90
- recordResourceReceipt({
91
- priority: item?.priority ?? null,
92
- stage: resourceStage(),
93
- decision: valid ? { action: decision.action, reason: decision.reason } : null,
94
- error: error ?? null,
95
- });
96
- }
97
-
98
- const critical = [];
99
- const decision = [];
100
- const progressPending = new Map(); // coalesceKey -> { item, firstArrival }
101
- const timers = new Set();
102
- let closed = false;
103
- let closedWith = 0;
104
- const counters = { submitted: 0, coalesced: 0, dropped: 0, deferred: 0, emitted: 0 };
105
-
106
- function boundedSize() {
107
- return decision.length + progressPending.size;
108
- }
109
-
110
- function submit(item) {
111
- if (closed || !item || typeof item !== 'object') {
112
- return { accepted: false, code: closed ? 'closed' : 'invalid' };
113
- }
114
- // G6 resource consult — shadow evaluates+records a bounded receipt;
115
- // enqueue below is always the prior path (throw/malformed → prior
116
- // behavior deterministically).
117
- if (resourceStage() !== 'off') {
118
- consultResourcePolicy(item);
119
- }
120
- if (item.priority === 'critical') {
121
- critical.push(item);
122
- counters.submitted++;
123
- return { accepted: true };
124
- }
125
- if (item.priority === 'progress' && item.coalesceKey) {
126
- const existing = progressPending.get(item.coalesceKey);
127
- if (existing) {
128
- existing.item = item; // latest wins
129
- counters.coalesced++;
130
- counters.submitted++;
131
- return { accepted: true };
132
- }
133
- if (boundedSize() >= maxQueue) {
134
- counters.dropped++;
135
- return { accepted: false, code: 'queue_full' };
136
- }
137
- progressPending.set(item.coalesceKey, { item, firstArrival: now() });
138
- counters.submitted++;
139
- return { accepted: true };
140
- }
141
- // decision tier (or progress without a key — cannot coalesce)
142
- if (boundedSize() >= maxQueue) {
143
- counters.dropped++;
144
- return { accepted: false, code: 'queue_full' };
145
- }
146
- decision.push(item);
147
- counters.submitted++;
148
- return { accepted: true };
149
- }
150
-
151
- function scheduleTimeout(ms) {
152
- let handle;
153
- const p = new Promise((resolve) => {
154
- handle = setTimeout(() => {
155
- timers.delete(handle);
156
- resolve('timeout');
157
- }, ms);
158
- if (typeof handle.unref === 'function') handle.unref();
159
- });
160
- timers.add(handle);
161
- return { promise: p, cancel: () => { clearTimeout(handle); timers.delete(handle); } };
162
- }
163
-
164
- async function decide(item) {
165
- const t = scheduleTimeout(decisionTimeoutMs);
166
- try {
167
- const result = await Promise.race([Promise.resolve().then(() => decideFn(item)), t.promise]);
168
- t.cancel();
169
- if (result === 'timeout') return fallback('timeout', item);
170
- if (result && result.decidedBy === 'fallback') return result;
171
- if (result === undefined || result === null) return fallback('invalid', item);
172
- return result;
173
- } catch {
174
- t.cancel();
175
- return fallback('invalid', item);
176
- }
177
- }
178
-
179
- async function flush() {
180
- const report = { processed: 0, emitted: 0, coalesced: 0, dropped: 0, deferred: 0 };
181
- if (closed) return report;
182
-
183
- while (critical.length) {
184
- const item = critical.shift();
185
- emitFn(item);
186
- counters.emitted++;
187
- report.processed++;
188
- report.emitted++;
189
- }
190
- while (decision.length) {
191
- const item = decision.shift();
192
- emitFn(await decide(item));
193
- counters.emitted++;
194
- report.processed++;
195
- report.emitted++;
196
- }
197
- const t = now();
198
- for (const [key, entry] of progressPending) {
199
- if (t - entry.firstArrival < coalesceWindowMs) {
200
- counters.deferred++;
201
- report.deferred++;
202
- continue;
203
- }
204
- progressPending.delete(key);
205
- emitFn(await decide(entry.item));
206
- counters.emitted++;
207
- report.processed++;
208
- report.emitted++;
209
- }
210
- return report;
211
- }
212
-
213
- function stats() {
214
- return {
215
- ...counters,
216
- pending: critical.length + decision.length + progressPending.size,
217
- closedWith,
218
- closed,
219
- };
220
- }
221
-
222
- async function close() {
223
- if (closed) return;
224
- closed = true;
225
- closedWith = critical.length + decision.length + progressPending.size;
226
- critical.length = 0;
227
- decision.length = 0;
228
- progressPending.clear();
229
- for (const h of timers) clearTimeout(h);
230
- timers.clear();
231
- }
232
-
233
- /** Bounded frozen receipts of shadow-stage resource-policy consults (G6). */
234
- function resourcePolicyReceipts() {
235
- return [...resourceReceipts];
236
- }
237
-
238
- return { submit, flush, stats, close, resourcePolicyReceipts };
239
- }
@@ -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
- }