@ngockhoale/ukit 3.5.3 → 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.
- package/CHANGELOG.md +21 -0
- package/manifests/documentation.yaml +12 -1
- package/manifests/platform.full.yaml +12 -0
- package/package.json +27 -1
- package/src/cli/commands/doctor.js +41 -0
- package/src/cli/commands/indexTools.js +10 -4
- package/src/cli/commands/memory.js +77 -6
- package/src/core/memory/episodes.js +106 -7
- package/src/core/memory/memoryCheck.js +241 -0
- package/src/core/memory/memoryCheckRun.js +27 -0
- package/src/core/memory/mutateMemory.js +37 -1
- package/src/core/memory/observations.js +192 -0
- package/src/core/memory/recallEngine.js +120 -7
- package/src/core/memory/records.js +23 -0
- package/src/core/memory/writeGate.js +137 -0
- package/src/core/runtimeConfig.js +11 -1
- package/src/index/buildIndex.js +26 -0
- package/src/index/paths.js +3 -1
- package/src/index/queryIndex.js +225 -10
- package/src/index/resolveContext.js +1 -1
- package/template_project/.claude/hooks/edit-hint.mjs +64 -17
- package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
- package/template_project/.claude/hooks/session-episode.sh +9 -4
- package/template_project/.claude/settings.json +2 -2
- package/template_project/.claude/ukit/index/lib/index-core.mjs +255 -12
- package/template_project/.claude/ukit/index/query-index.mjs +14 -3
- package/template_project/.claude/ukit/index/route-task.mjs +4 -1
- package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
- package/template_project/.claude/ukit/runtime/memory-recall.mjs +120 -7
- package/template_project/.claude/ukit/runtime/memory-validity.mjs +28 -1
- package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
- package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
- package/template_project/ukit/storage/config.json +4 -2
- package/src/core/agentRuntime/completionGate.js +0 -179
- package/src/core/agentRuntime/context.js +0 -571
- package/src/core/agentRuntime/qualityComparison.js +0 -112
- package/src/core/agentRuntime/resourcePolicy.js +0 -78
- package/src/core/agentRuntime/runtimeSupport.js +0 -255
- package/src/core/codeintel/manifest.js +0 -176
- package/src/core/experiments/deliberation.js +0 -327
- package/src/core/experiments/dynamicWorkflow.js +0 -507
- package/src/core/handoffDocValidator.js +0 -154
- package/src/core/memory/deltaOverlays.js +0 -493
- package/src/core/memory/learningCandidates.js +0 -347
- package/src/core/observability/emit/sessionBoot.js +0 -407
- package/src/core/observability/evaluation/replay.js +0 -149
- package/src/core/observability/evaluation/scorecard.js +0 -465
- package/src/core/observability/schema/compatibility.js +0 -180
- package/src/core/observability/support/renderer.js +0 -130
- package/src/core/reviewPanelAggregate.js +0 -204
- package/src/core/taskBudgetValidator.js +0 -251
- package/src/core/taskProgressGuard.js +0 -227
- package/src/decision/reviewVerdict.js +0 -339
- package/src/decision/runtimeFilter.js +0 -150
- package/src/decision/runtimeScheduler.js +0 -239
- package/src/index/contextPack.js +0 -285
- package/src/index/impactContext.js +0 -360
- package/src/index/reviewPolicy.js +0 -368
- 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
|
-
}
|
package/src/index/contextPack.js
DELETED
|
@@ -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
|
-
}
|