@ngockhoale/ukit 3.5.2 → 3.5.3
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 +17 -90
- package/README.md +1 -0
- package/package.json +8 -1
- package/src/cli/commands/doctor.js +14 -2
- package/src/cli/commands/memory.js +30 -2
- package/src/core/memory/memoryHit.js +2 -0
- package/src/core/memory/mutateMemory.js +9 -0
- package/src/core/memory/projectIdentity.js +9 -2
- package/src/core/memory/recallEngine.js +86 -4
- package/src/core/memory/registryPrune.js +230 -0
- package/src/core/memory/retrieval.js +12 -3
- package/src/core/runtimeConfig.js +1 -1
- package/src/index/queryIndex.js +151 -20
- package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
- package/template_project/.claude/ukit/index/lib/index-core.mjs +149 -19
- package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
- package/template_project/.claude/ukit/index/route-task.mjs +4 -1
- package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
- package/template_project/.claude/ukit/runtime/memory-recall.mjs +86 -4
- package/template_project/.claude/ukit/runtime/memory-validity.mjs +232 -0
- package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
- package/src/core/observability/evaluation/experimentPlan.js +0 -95
- package/src/core/observability/evaluation/perturbation.js +0 -273
- package/src/diagnostics/classifyHang.js +0 -246
- package/src/diagnostics/ompStallSnapshot.js +0 -199
- package/src/render/instructionRenderer.js +0 -290
- package/src/skill/auditSkill.js +0 -140
- package/template_project/instructions/overlays/repo.md +0 -9
|
@@ -1,273 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* perturbation.js (TASK-002, SPEC §2 G5-FR06/G5-FR07) — synthetic mutation harness.
|
|
3
|
-
*
|
|
4
|
-
* mutateSummaries(summaries, { seed, plan? }) → { summaries, manifest }
|
|
5
|
-
* detectPerturbations(mutatedSummaries, baselineSummaries, manifest)
|
|
6
|
-
* → { injected, detected, missed[], details[] }
|
|
7
|
-
*
|
|
8
|
-
* Pure module: no fs, no clock, no unseeded randomness (mulberry32, same
|
|
9
|
-
* construction as the bench corpus generator). Mutations edit TraceSummary
|
|
10
|
-
* structures so the downstream pipeline sees a genuinely different trace;
|
|
11
|
-
* detection is measured through the REAL computeFingerprint /
|
|
12
|
-
* detectOpportunities path — never from the manifest alone.
|
|
13
|
-
*
|
|
14
|
-
* Mutation kinds (MUTATION_KINDS):
|
|
15
|
-
* drop_record — removes a span and raises drops.dropped_count>0
|
|
16
|
-
* retry_inflation — adds an attempt_index>1 model span and raises retries
|
|
17
|
-
* cache_miss_spike — adds cache misses (cache.observed, hit_rate recomputed)
|
|
18
|
-
* orphan_span — rewrites parent_span_id to an absent id
|
|
19
|
-
* telemetry_incomplete — flips telemetry_complete=false
|
|
20
|
-
*
|
|
21
|
-
* Detection rule (per manifest entry): the mutated trace is detected when its
|
|
22
|
-
* fingerprint kind/count diverges from its own baseline, OR — once the trace
|
|
23
|
-
* is proven changed (hash divergence) — its opportunity cluster reports
|
|
24
|
-
* `inconclusive` (the honesty path telemetry_incomplete relies on) or a
|
|
25
|
-
* non-clean pattern. An unmutated trace claimed in the manifest cannot be
|
|
26
|
-
* detected: hash-identical traces have nothing to report.
|
|
27
|
-
*/
|
|
28
|
-
|
|
29
|
-
import { computeFingerprint } from '../analytics/fingerprints.js';
|
|
30
|
-
import { detectOpportunities } from '../analytics/opportunities.js';
|
|
31
|
-
|
|
32
|
-
export const MUTATION_KINDS = Object.freeze([
|
|
33
|
-
'drop_record',
|
|
34
|
-
'retry_inflation',
|
|
35
|
-
'cache_miss_spike',
|
|
36
|
-
'orphan_span',
|
|
37
|
-
'telemetry_incomplete',
|
|
38
|
-
]);
|
|
39
|
-
|
|
40
|
-
// Deterministic PRNG (mulberry32) — identical construction to the bench corpus.
|
|
41
|
-
function mulberry32(seed) {
|
|
42
|
-
let a = seed >>> 0;
|
|
43
|
-
return function next() {
|
|
44
|
-
a |= 0;
|
|
45
|
-
a = (a + 0x6d2b79f5) | 0;
|
|
46
|
-
let t = Math.imul(a ^ (a >>> 15), 1 | a);
|
|
47
|
-
t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
|
|
48
|
-
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
|
|
49
|
-
};
|
|
50
|
-
}
|
|
51
|
-
|
|
52
|
-
function isPlainObject(value) {
|
|
53
|
-
return value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
54
|
-
}
|
|
55
|
-
|
|
56
|
-
function num(value) {
|
|
57
|
-
return typeof value === 'number' && Number.isFinite(value) ? value : 0;
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
/**
|
|
61
|
-
* Candidate indices for a kind — a mutation must produce a genuinely
|
|
62
|
-
* different trace, so kinds with preconditions filter to eligible traces.
|
|
63
|
-
* Prefers traces not already mutated by this call.
|
|
64
|
-
*/
|
|
65
|
-
function candidateIndices(mutated, kind, used) {
|
|
66
|
-
const eligible = mutated
|
|
67
|
-
.map((s, idx) => ({ s, idx }))
|
|
68
|
-
.filter(({ s }) => {
|
|
69
|
-
if (!isPlainObject(s) || !Array.isArray(s.spans) || s.spans.length === 0) return false;
|
|
70
|
-
if (kind === 'telemetry_incomplete') return s.telemetry_complete === true;
|
|
71
|
-
return true;
|
|
72
|
-
})
|
|
73
|
-
.map(({ idx }) => idx);
|
|
74
|
-
const fresh = eligible.filter((idx) => !used.has(idx));
|
|
75
|
-
return fresh.length > 0 ? fresh : eligible;
|
|
76
|
-
}
|
|
77
|
-
|
|
78
|
-
function ensureCounters(summary) {
|
|
79
|
-
if (!isPlainObject(summary.retries)) summary.retries = {};
|
|
80
|
-
if (!isPlainObject(summary.drops)) summary.drops = {};
|
|
81
|
-
if (!isPlainObject(summary.drops.by_reason)) summary.drops.by_reason = {};
|
|
82
|
-
if (!isPlainObject(summary.cache)) summary.cache = {};
|
|
83
|
-
if (!isPlainObject(summary.coverage)) summary.coverage = {};
|
|
84
|
-
}
|
|
85
|
-
const MUTATORS = {
|
|
86
|
-
drop_record(summary) {
|
|
87
|
-
const idx = summary.spans.findIndex(
|
|
88
|
-
(s) => typeof s.parent_span_id === 'string' && s.parent_span_id.length > 0,
|
|
89
|
-
);
|
|
90
|
-
const i = idx >= 0 ? idx : 0;
|
|
91
|
-
const removed = summary.spans.splice(i, 1)[0] || null;
|
|
92
|
-
summary.drops.events = num(summary.drops.events) + 1;
|
|
93
|
-
summary.drops.dropped_count = num(summary.drops.dropped_count) + 1;
|
|
94
|
-
summary.drops.by_reason.synthetic_drop = num(summary.drops.by_reason.synthetic_drop) + 1;
|
|
95
|
-
summary.telemetry_complete = false;
|
|
96
|
-
summary.coverage.spans = summary.spans.length;
|
|
97
|
-
return { removed_span_id: removed ? removed.span_id : null };
|
|
98
|
-
},
|
|
99
|
-
|
|
100
|
-
retry_inflation(summary) {
|
|
101
|
-
const model =
|
|
102
|
-
summary.spans.find((s) => s.family === 'model') ||
|
|
103
|
-
summary.spans[summary.spans.length - 1] ||
|
|
104
|
-
null;
|
|
105
|
-
const maxAttempt = summary.spans.reduce(
|
|
106
|
-
(m, s) => (Number.isInteger(s.attempt_index) ? Math.max(m, s.attempt_index) : m),
|
|
107
|
-
0,
|
|
108
|
-
);
|
|
109
|
-
const attemptIndex = Math.max(2, maxAttempt + 1);
|
|
110
|
-
const clone = {
|
|
111
|
-
...(model || {
|
|
112
|
-
parent_span_id: null,
|
|
113
|
-
family: 'model',
|
|
114
|
-
operation: null,
|
|
115
|
-
status: 'completed',
|
|
116
|
-
duration_ms: 0,
|
|
117
|
-
}),
|
|
118
|
-
span_id: `${model ? model.span_id : 'span'}-retry${attemptIndex}`,
|
|
119
|
-
attempt_index: attemptIndex,
|
|
120
|
-
status: 'completed',
|
|
121
|
-
start_record_id: `rec-${summary.trace_id}-retry${attemptIndex}-start`,
|
|
122
|
-
end_record_id: `rec-${summary.trace_id}-retry${attemptIndex}-end`,
|
|
123
|
-
};
|
|
124
|
-
summary.spans.push(clone);
|
|
125
|
-
summary.retries.retries = num(summary.retries.retries) + 1;
|
|
126
|
-
summary.retries.model_attempts = num(summary.retries.model_attempts) + 1;
|
|
127
|
-
summary.coverage.spans = summary.spans.length;
|
|
128
|
-
return { added_attempt_span: clone.span_id, attempt_index: attemptIndex };
|
|
129
|
-
},
|
|
130
|
-
|
|
131
|
-
cache_miss_spike(summary, rand) {
|
|
132
|
-
const added = 2 + Math.floor(rand() * 3); // 2..4 misses
|
|
133
|
-
summary.cache.observed = true;
|
|
134
|
-
summary.cache.hits = num(summary.cache.hits);
|
|
135
|
-
summary.cache.misses = num(summary.cache.misses) + added;
|
|
136
|
-
const lookups = summary.cache.hits + summary.cache.misses;
|
|
137
|
-
summary.cache.hit_rate = lookups > 0 ? summary.cache.hits / lookups : null;
|
|
138
|
-
return { misses_added: added };
|
|
139
|
-
},
|
|
140
|
-
|
|
141
|
-
orphan_span(summary) {
|
|
142
|
-
const idx = summary.spans.findIndex(
|
|
143
|
-
(s) => typeof s.parent_span_id === 'string' && s.parent_span_id.length > 0,
|
|
144
|
-
);
|
|
145
|
-
const i = idx >= 0 ? idx : 0;
|
|
146
|
-
const target = summary.spans[i];
|
|
147
|
-
const previous = target.parent_span_id ?? null;
|
|
148
|
-
target.parent_span_id = `absent-${target.span_id}`;
|
|
149
|
-
summary.coverage.orphan_spans = num(summary.coverage.orphan_spans) + 1;
|
|
150
|
-
return { span_id: target.span_id, previous_parent: previous };
|
|
151
|
-
},
|
|
152
|
-
|
|
153
|
-
telemetry_incomplete(summary) {
|
|
154
|
-
const previous = summary.telemetry_complete;
|
|
155
|
-
summary.telemetry_complete = false;
|
|
156
|
-
return { previous_telemetry_complete: previous };
|
|
157
|
-
},
|
|
158
|
-
};
|
|
159
|
-
|
|
160
|
-
/**
|
|
161
|
-
* @param {Array<object>} summaries — baseline TraceSummary objects (not mutated).
|
|
162
|
-
* @param {{ seed?: number, plan?: Array<{kind:string}> }} [options]
|
|
163
|
-
* plan defaults to one mutation per MUTATION_KINDS entry.
|
|
164
|
-
* @returns {{ summaries: Array<object>, manifest: Array<object> }}
|
|
165
|
-
* manifest entries: { mutation_id, trace_id, kind, detail }.
|
|
166
|
-
*/
|
|
167
|
-
export function mutateSummaries(summaries, { seed = 42, plan } = {}) {
|
|
168
|
-
if (!Array.isArray(summaries)) {
|
|
169
|
-
throw new TypeError('mutateSummaries: summaries must be an array of TraceSummary');
|
|
170
|
-
}
|
|
171
|
-
const effectivePlan = Array.isArray(plan) ? plan : MUTATION_KINDS.map((kind) => ({ kind }));
|
|
172
|
-
for (const entry of effectivePlan) {
|
|
173
|
-
if (!isPlainObject(entry) || !MUTATION_KINDS.includes(entry.kind)) {
|
|
174
|
-
throw new TypeError(
|
|
175
|
-
`mutateSummaries: plan entries need kind ∈ {${MUTATION_KINDS.join(', ')}}`,
|
|
176
|
-
);
|
|
177
|
-
}
|
|
178
|
-
}
|
|
179
|
-
|
|
180
|
-
const rand = mulberry32(seed);
|
|
181
|
-
const mutated = summaries.map((s) => JSON.parse(JSON.stringify(s)));
|
|
182
|
-
const manifest = [];
|
|
183
|
-
const used = new Set();
|
|
184
|
-
|
|
185
|
-
effectivePlan.forEach((entry, i) => {
|
|
186
|
-
const pickFrom = candidateIndices(mutated, entry.kind, used);
|
|
187
|
-
if (pickFrom.length === 0) return;
|
|
188
|
-
const targetIdx = pickFrom[Math.floor(rand() * pickFrom.length)];
|
|
189
|
-
used.add(targetIdx);
|
|
190
|
-
const summary = mutated[targetIdx];
|
|
191
|
-
ensureCounters(summary);
|
|
192
|
-
const detail = MUTATORS[entry.kind](summary, rand);
|
|
193
|
-
manifest.push({
|
|
194
|
-
mutation_id: `mut-${String(i + 1).padStart(3, '0')}`,
|
|
195
|
-
trace_id: typeof summary.trace_id === 'string' ? summary.trace_id : `idx-${targetIdx}`,
|
|
196
|
-
kind: entry.kind,
|
|
197
|
-
detail,
|
|
198
|
-
});
|
|
199
|
-
});
|
|
200
|
-
|
|
201
|
-
return { summaries: mutated, manifest };
|
|
202
|
-
}
|
|
203
|
-
|
|
204
|
-
/**
|
|
205
|
-
* Measure detection through the real pipeline: computeFingerprint for
|
|
206
|
-
* per-trace divergence vs baseline and detectOpportunities for cluster
|
|
207
|
-
* status over the mutated set.
|
|
208
|
-
*
|
|
209
|
-
* @param {Array<object>} mutatedSummaries
|
|
210
|
-
* @param {Array<object>} baselineSummaries
|
|
211
|
-
* @param {Array<object>} manifest — entries from mutateSummaries.
|
|
212
|
-
* @returns {{ injected:number, detected:number, missed:Array<object>, details:Array<object> }}
|
|
213
|
-
*/
|
|
214
|
-
export function detectPerturbations(mutatedSummaries, baselineSummaries, manifest) {
|
|
215
|
-
if (!Array.isArray(mutatedSummaries) || !Array.isArray(baselineSummaries) || !Array.isArray(manifest)) {
|
|
216
|
-
throw new TypeError('detectPerturbations: summaries and manifest must be arrays');
|
|
217
|
-
}
|
|
218
|
-
|
|
219
|
-
const baselineByTrace = new Map();
|
|
220
|
-
for (const s of baselineSummaries) {
|
|
221
|
-
if (isPlainObject(s) && typeof s.trace_id === 'string') baselineByTrace.set(s.trace_id, s);
|
|
222
|
-
}
|
|
223
|
-
const mutatedByTrace = new Map();
|
|
224
|
-
for (const s of mutatedSummaries) {
|
|
225
|
-
if (isPlainObject(s) && typeof s.trace_id === 'string') mutatedByTrace.set(s.trace_id, s);
|
|
226
|
-
}
|
|
227
|
-
|
|
228
|
-
// Real pipeline — never read the manifest as evidence.
|
|
229
|
-
const opportunities = detectOpportunities(mutatedSummaries);
|
|
230
|
-
const oppByTrace = new Map();
|
|
231
|
-
for (const opp of opportunities) {
|
|
232
|
-
for (const ref of opp.trace_refs || []) {
|
|
233
|
-
if (!oppByTrace.has(ref)) oppByTrace.set(ref, opp);
|
|
234
|
-
}
|
|
235
|
-
}
|
|
236
|
-
|
|
237
|
-
const details = [];
|
|
238
|
-
for (const entry of manifest) {
|
|
239
|
-
const mutated = mutatedByTrace.get(entry.trace_id);
|
|
240
|
-
const baseline = baselineByTrace.get(entry.trace_id);
|
|
241
|
-
const via = [];
|
|
242
|
-
let opportunity = null;
|
|
243
|
-
if (mutated && baseline) {
|
|
244
|
-
const fm = computeFingerprint(mutated);
|
|
245
|
-
const fb = computeFingerprint(baseline);
|
|
246
|
-
const changed = fm.hash !== fb.hash;
|
|
247
|
-
if (fm.kind !== fb.kind || fm.count !== fb.count) via.push('fingerprint');
|
|
248
|
-
opportunity = oppByTrace.get(entry.trace_id) || null;
|
|
249
|
-
if (changed && opportunity) {
|
|
250
|
-
if (opportunity.status === 'inconclusive') via.push('inconclusive');
|
|
251
|
-
else if (opportunity.fingerprint && opportunity.fingerprint.kind !== 'clean') {
|
|
252
|
-
via.push('opportunity');
|
|
253
|
-
}
|
|
254
|
-
}
|
|
255
|
-
}
|
|
256
|
-
details.push({
|
|
257
|
-
mutation_id: entry.mutation_id,
|
|
258
|
-
trace_id: entry.trace_id,
|
|
259
|
-
kind: entry.kind,
|
|
260
|
-
detected: via.length > 0,
|
|
261
|
-
via,
|
|
262
|
-
opportunity,
|
|
263
|
-
});
|
|
264
|
-
}
|
|
265
|
-
|
|
266
|
-
const missed = details.filter((d) => !d.detected);
|
|
267
|
-
return {
|
|
268
|
-
injected: manifest.length,
|
|
269
|
-
detected: details.length - missed.length,
|
|
270
|
-
missed,
|
|
271
|
-
details,
|
|
272
|
-
};
|
|
273
|
-
}
|
|
@@ -1,246 +0,0 @@
|
|
|
1
|
-
// classifyHang.js — evidence-only hang classifier for the C19 liveness wave (TASK-032).
|
|
2
|
-
//
|
|
3
|
-
// What this is for: C19 removed a family of unbounded paths, and the remaining failure
|
|
4
|
-
// mode is telling ONE stall class apart from another. A prompt freeze used to be
|
|
5
|
-
// indistinguishable from an indexing freeze or a gateway stall, so operators had no
|
|
6
|
-
// evidence-based next step. This module turns an evidence bundle into exactly one
|
|
7
|
-
// declared lane, or `unknown` when the evidence cannot prove any of them.
|
|
8
|
-
//
|
|
9
|
-
// Contracts (asserted by tests/liveness/classifyHang.test.js):
|
|
10
|
-
// * PURE and CLOCK-FREE. Every rule is a function of the bundle only, so identical
|
|
11
|
-
// evidence always produces byte-identical output. No Date.now(), no randomness, no
|
|
12
|
-
// I/O — the caller supplies both the measurement and the clock.
|
|
13
|
-
// * NEVER GUESSES. A lane is only named when the evidence PROVES it:
|
|
14
|
-
// - `deadline` with zero survivors is a clean reap, not a process-tree leak;
|
|
15
|
-
// - survivors beside `failureKind: 'signal'` are NOT a leak: `signal` is documented
|
|
16
|
-
// by the runner as a signal IT DID NOT SEND, so there is no escalation to blame
|
|
17
|
-
// and the bundle is `unknown` (the runner's own `deadline` verdict is the only
|
|
18
|
-
// escalation proof);
|
|
19
|
-
// - a non-zero hook exit that finished inside its budget is a verdict, not a hang;
|
|
20
|
-
// - a non-typed index error is not a discovery deadline.
|
|
21
|
-
// Everything else is `unknown` with a concrete next check.
|
|
22
|
-
// * The UPSTREAM lane is never a hook. Stream idle with no hook active classifies
|
|
23
|
-
// `gateway-stream-idle`; the presence of hook evidence removes that lane entirely, so
|
|
24
|
-
// a gateway stall can no longer be reported as UKit's fault (or the reverse).
|
|
25
|
-
// * Exactly four fields, always: `{class, confidence, evidenceIds, recommendedNextCheck}`.
|
|
26
|
-
// `evidenceIds` names the fields the decision rests on, so a reviewer can re-derive it.
|
|
27
|
-
|
|
28
|
-
/**
|
|
29
|
-
* The six declared stall lanes. One bundle resolves to at most one of these.
|
|
30
|
-
* Ordered by decision precedence (see LANE_PRECEDENCE) — the first lane whose evidence
|
|
31
|
-
* is present AND conclusive owns the classification.
|
|
32
|
-
*/
|
|
33
|
-
export const HANG_CLASSES = Object.freeze([
|
|
34
|
-
'process-tree-leak',
|
|
35
|
-
'hook-overrun',
|
|
36
|
-
'index-deadline',
|
|
37
|
-
'lock-contention',
|
|
38
|
-
'context-capacity',
|
|
39
|
-
'gateway-stream-idle',
|
|
40
|
-
]);
|
|
41
|
-
|
|
42
|
-
/** The explicit "could not prove a lane" result. Never a member of HANG_CLASSES. */
|
|
43
|
-
export const UNKNOWN_CLASS = 'unknown';
|
|
44
|
-
|
|
45
|
-
/**
|
|
46
|
-
* Evidence kinds a bundle may carry. Exported so callers and diagnostics can enumerate
|
|
47
|
-
* what the classifier understands instead of guessing at field names.
|
|
48
|
-
*/
|
|
49
|
-
export const EVIDENCE_KINDS = Object.freeze([
|
|
50
|
-
'hook-telemetry',
|
|
51
|
-
'hook-active',
|
|
52
|
-
'process-result',
|
|
53
|
-
'index-error',
|
|
54
|
-
'lock-outcome',
|
|
55
|
-
'context-capacity',
|
|
56
|
-
'stream-idle',
|
|
57
|
-
]);
|
|
58
|
-
|
|
59
|
-
// Hook-runner outcomes that PROVE the runner ended the child (TASK-018 taxonomy). These
|
|
60
|
-
// are kill verdicts, so they name a lane; `ok` / `exit-code` are verdicts about the hook's
|
|
61
|
-
// own decision and prove nothing about liveness.
|
|
62
|
-
const KILL_OUTCOMES = new Set(['timeout', 'output-overflow', 'budget-exhausted']);
|
|
63
|
-
|
|
64
|
-
// A leak only exists AFTER the runner's OWN escalation attempt, and only if something is
|
|
65
|
-
// still alive. `failureKind: 'deadline'` is the runner's kill verdict — the deadline timer
|
|
66
|
-
// armed the TERM → KILL sequence, so survivors beside it really are an escapee (H03).
|
|
67
|
-
//
|
|
68
|
-
// `signal` is explicitly NOT escalation evidence: the runner documents it as "the child
|
|
69
|
-
// died from a signal this runner did not send" (hook-process.mjs), which is an unprompted
|
|
70
|
-
// EXTERNAL kill. Survivors beside an external signal may be unrelated processes, and naming
|
|
71
|
-
// a lane off it would fabricate a TERM → KILL diagnosis the evidence cannot support. Such a
|
|
72
|
-
// bundle is `unknown`, never `process-tree-leak`.
|
|
73
|
-
const RUNNER_ESCALATION_KINDS = new Set(['deadline']);
|
|
74
|
-
|
|
75
|
-
const UNKNOWN_CHECK = 'Collect hook telemetry, process-exit evidence, or an index/lock/context measurement for this stall — none of the current evidence proves a lane.';
|
|
76
|
-
|
|
77
|
-
const NEXT_CHECK = Object.freeze({
|
|
78
|
-
'process-tree-leak': 'Re-run the failing command with the process-tree runner and list the surviving PIDs: a process group survived its TERM→KILL escalation (check for a child that ignores or detaches from SIGTERM).',
|
|
79
|
-
'hook-overrun': 'Inspect the cited hook telemetry row: the hook was killed at its deadline or overflowed its output cap. Measure that hook alone and reduce its work below its budget.',
|
|
80
|
-
'index-deadline': 'Re-run discovery with a bounded deadline and inspect the recorded phase: git enumeration or the filesystem fallback consumed the whole budget.',
|
|
81
|
-
'lock-contention': 'Inspect the lock holder state for the named target: the acquisition budget expired or was aborted before the critical section ran (fail-closed, no mutation happened).',
|
|
82
|
-
'context-capacity': 'Re-check the negotiated context capacity against the estimate: the session reached its advisory cap, so compaction must run before more context is added.',
|
|
83
|
-
'gateway-stream-idle': 'Watch the stream idle window: no hook was active while the stream went silent, so treat this as an upstream/gateway stall and verify CLAUDE_STREAM_IDLE_TIMEOUT_MS and the non-streaming fallback.',
|
|
84
|
-
});
|
|
85
|
-
|
|
86
|
-
function isObject(value) {
|
|
87
|
-
return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
function isPositiveNumber(value) {
|
|
91
|
-
return typeof value === 'number' && Number.isFinite(value) && value > 0;
|
|
92
|
-
}
|
|
93
|
-
|
|
94
|
-
function resultFor(cls, confidence, evidenceIds, recommendedNextCheck) {
|
|
95
|
-
return { class: cls, confidence, evidenceIds, recommendedNextCheck };
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
function unknown(evidenceIds = []) {
|
|
99
|
-
return resultFor(UNKNOWN_CLASS, 'none', evidenceIds, UNKNOWN_CHECK);
|
|
100
|
-
}
|
|
101
|
-
|
|
102
|
-
// ─── per-lane evidence evaluators ────────────────────────────────────────────
|
|
103
|
-
// Each returns { evidenceIds, confidence } when the evidence PROVES the lane, else null.
|
|
104
|
-
|
|
105
|
-
function detectProcessTreeLeak(bundle) {
|
|
106
|
-
const processResult = bundle.processResult;
|
|
107
|
-
if (!isObject(processResult)) return null;
|
|
108
|
-
const survivors = processResult.survivors;
|
|
109
|
-
// `survivors` must be an explicit, non-empty array: a missing field is unknown
|
|
110
|
-
// evidence (the caller never probed), and an empty array is a clean reap.
|
|
111
|
-
if (!Array.isArray(survivors) || survivors.length === 0) return null;
|
|
112
|
-
// Survivors alone proves nothing — the runner must have escalated. `signal` is an
|
|
113
|
-
// external kill, so it stays `unknown` rather than claiming a leak.
|
|
114
|
-
if (!RUNNER_ESCALATION_KINDS.has(processResult.failureKind)) return null;
|
|
115
|
-
return { evidenceIds: ['process-result'], confidence: 'high' };
|
|
116
|
-
}
|
|
117
|
-
|
|
118
|
-
function detectHookOverrun(bundle) {
|
|
119
|
-
const rows = bundle.hookTelemetry;
|
|
120
|
-
if (!Array.isArray(rows)) return null;
|
|
121
|
-
for (let i = 0; i < rows.length; i += 1) {
|
|
122
|
-
const row = rows[i];
|
|
123
|
-
if (isObject(row) && KILL_OUTCOMES.has(row.outcome)) {
|
|
124
|
-
// Cite only the failing row — the row index is the evidence locator.
|
|
125
|
-
return { evidenceIds: [`hook-telemetry[${i}]`], confidence: 'high' };
|
|
126
|
-
}
|
|
127
|
-
}
|
|
128
|
-
return null;
|
|
129
|
-
}
|
|
130
|
-
|
|
131
|
-
function detectIndexDeadline(bundle) {
|
|
132
|
-
const indexError = bundle.indexError;
|
|
133
|
-
if (!isObject(indexError)) return null;
|
|
134
|
-
// Only the typed liveness failure is proof; a message alone could be anything.
|
|
135
|
-
const typed = indexError.name === 'IndexDiscoveryTimeoutError'
|
|
136
|
-
|| indexError.code === 'INDEX_DISCOVERY_TIMEOUT';
|
|
137
|
-
if (!typed) return null;
|
|
138
|
-
return { evidenceIds: ['index-error'], confidence: 'high' };
|
|
139
|
-
}
|
|
140
|
-
|
|
141
|
-
function detectLockContention(bundle) {
|
|
142
|
-
const lockOutcome = bundle.lockOutcome;
|
|
143
|
-
if (!isObject(lockOutcome) || lockOutcome.ok !== false) return null;
|
|
144
|
-
// TASK-028's typed envelope: the callback never ran, so no mutation was lost.
|
|
145
|
-
if (lockOutcome.reason !== 'busy' && lockOutcome.reason !== 'aborted') return null;
|
|
146
|
-
return { evidenceIds: ['lock-outcome'], confidence: 'high' };
|
|
147
|
-
}
|
|
148
|
-
|
|
149
|
-
function detectContextCapacity(bundle) {
|
|
150
|
-
const context = bundle.context;
|
|
151
|
-
if (!isObject(context)) return null;
|
|
152
|
-
const capTokens = context.capTokens;
|
|
153
|
-
const estimatedTokens = context.estimatedTokens;
|
|
154
|
-
if (!isPositiveNumber(capTokens) || !isPositiveNumber(estimatedTokens)) return null;
|
|
155
|
-
if (estimatedTokens < capTokens) return null;
|
|
156
|
-
return { evidenceIds: ['context-capacity'], confidence: 'high' };
|
|
157
|
-
}
|
|
158
|
-
|
|
159
|
-
function detectGatewayStreamIdle(bundle) {
|
|
160
|
-
const stream = bundle.stream;
|
|
161
|
-
if (!isObject(stream)) return null;
|
|
162
|
-
const idleMs = stream.idleMs;
|
|
163
|
-
const idleTimeoutMs = stream.idleTimeoutMs;
|
|
164
|
-
// Both numbers are required: without the negotiated timeout there is nothing to
|
|
165
|
-
// compare against, and an idle duration alone proves no stall.
|
|
166
|
-
if (!isPositiveNumber(idleMs) || !isPositiveNumber(idleTimeoutMs)) return null;
|
|
167
|
-
if (idleMs < idleTimeoutMs) return null;
|
|
168
|
-
// A hook was active while the stream was silent → the silence may be UKit's, so the
|
|
169
|
-
// upstream lane is removed entirely. Never blame the gateway over hook evidence.
|
|
170
|
-
// `null`/`undefined` both mean "no hook was active" — only a real value withholds it.
|
|
171
|
-
if (bundle.hookActive !== null && bundle.hookActive !== undefined) return null;
|
|
172
|
-
return { evidenceIds: ['stream-idle'], confidence: 'high' };
|
|
173
|
-
}
|
|
174
|
-
|
|
175
|
-
// Precedence: the most specific, evidence-backed lane wins. The upstream lane is LAST —
|
|
176
|
-
// it is the only lane whose proof is the ABSENCE of other evidence, so it may only be
|
|
177
|
-
// reached once every hook/index/lock/context claim had its chance.
|
|
178
|
-
const LANE_PRECEDENCE = Object.freeze([
|
|
179
|
-
['process-tree-leak', detectProcessTreeLeak],
|
|
180
|
-
['hook-overrun', detectHookOverrun],
|
|
181
|
-
['index-deadline', detectIndexDeadline],
|
|
182
|
-
['lock-contention', detectLockContention],
|
|
183
|
-
['context-capacity', detectContextCapacity],
|
|
184
|
-
['gateway-stream-idle', detectGatewayStreamIdle],
|
|
185
|
-
]);
|
|
186
|
-
|
|
187
|
-
// Evidence that was considered but is NOT sufficient to name a lane. Reported on the
|
|
188
|
-
// `unknown` result so a caller sees what was looked at, never just "nothing".
|
|
189
|
-
function inconclusiveEvidenceIds(bundle) {
|
|
190
|
-
const ids = [];
|
|
191
|
-
if (Array.isArray(bundle.hookTelemetry) && bundle.hookTelemetry.length > 0) {
|
|
192
|
-
ids.push('hook-telemetry');
|
|
193
|
-
}
|
|
194
|
-
if (isObject(bundle.hookActive)) ids.push('hook-active');
|
|
195
|
-
if (isObject(bundle.stream)) ids.push('stream-idle');
|
|
196
|
-
if (isObject(bundle.processResult)) ids.push('process-result');
|
|
197
|
-
if (isObject(bundle.indexError)) ids.push('index-error');
|
|
198
|
-
if (isObject(bundle.lockOutcome)) ids.push('lock-outcome');
|
|
199
|
-
if (isObject(bundle.context)) ids.push('context-capacity');
|
|
200
|
-
return ids;
|
|
201
|
-
}
|
|
202
|
-
|
|
203
|
-
/**
|
|
204
|
-
* Classify ONE stall from an evidence bundle.
|
|
205
|
-
*
|
|
206
|
-
* @param {object} [bundle] evidence collected by a scenario or a live diagnostic:
|
|
207
|
-
* `hookTelemetry` — redacted telemetry rows (TASK-019 schema; `outcome` is the
|
|
208
|
-
* runner's taxonomy, `hook` names the emitter).
|
|
209
|
-
* `hookActive` — `{hook, activeMs}` when a hook held the hot path. Presence alone
|
|
210
|
-
* removes the upstream lane.
|
|
211
|
-
* `processResult` — `{failureKind, signal, code, elapsedMs, survivors}` from the
|
|
212
|
-
* process-tree runner. `survivors` is the escalation probe.
|
|
213
|
-
* `indexError` — the thrown error (or its shape) from index discovery.
|
|
214
|
-
* `lockOutcome` — the typed `{ok:false, reason:'busy'|'aborted', waitedMs}` envelope.
|
|
215
|
-
* `context` — `{capTokens, estimatedTokens, ...}` from capacity negotiation.
|
|
216
|
-
* `stream` — `{idleMs, idleTimeoutMs, ...}` from stream timing.
|
|
217
|
-
* @returns {{ class: string, confidence: 'high'|'none', evidenceIds: string[],
|
|
218
|
-
* recommendedNextCheck: string }} exactly four fields; `class` is either a
|
|
219
|
-
* member of HANG_CLASSES or UNKNOWN_CLASS.
|
|
220
|
-
*/
|
|
221
|
-
export function classifyHang(bundle = {}) {
|
|
222
|
-
if (!isObject(bundle)) return unknown();
|
|
223
|
-
|
|
224
|
-
for (const [lane, detect] of LANE_PRECEDENCE) {
|
|
225
|
-
const evidence = detect(bundle);
|
|
226
|
-
if (evidence) return resultFor(lane, evidence.confidence, evidence.evidenceIds, NEXT_CHECK[lane]);
|
|
227
|
-
}
|
|
228
|
-
|
|
229
|
-
return unknown(inconclusiveEvidenceIds(bundle));
|
|
230
|
-
}
|
|
231
|
-
|
|
232
|
-
/**
|
|
233
|
-
* C19 finding → lane map. Every finding this cycle addressed has a lane whose evidence a
|
|
234
|
-
* scenario in `tests/liveness/hangScenarios.test.js` produces, so no finding is left
|
|
235
|
-
* without a classifier answer. Exposed as data (not prose) so the liveness suite can fail
|
|
236
|
-
* when coverage regresses.
|
|
237
|
-
*/
|
|
238
|
-
export const C19_LANE_MAP = Object.freeze([
|
|
239
|
-
Object.freeze({ findings: Object.freeze(['H01', 'H02', 'H05', 'H08', 'H21']), lane: 'hook-overrun' }),
|
|
240
|
-
Object.freeze({ findings: Object.freeze(['H03']), lane: 'process-tree-leak' }),
|
|
241
|
-
Object.freeze({ findings: Object.freeze(['H09', 'H10', 'H11', 'H12', 'H13', 'H14', 'H15']), lane: 'index-deadline' }),
|
|
242
|
-
Object.freeze({ findings: Object.freeze(['H16', 'H17', 'H18', 'H19', 'H20']), lane: 'lock-contention' }),
|
|
243
|
-
Object.freeze({ findings: Object.freeze(['H04', 'H22']), lane: 'context-capacity' }),
|
|
244
|
-
Object.freeze({ findings: Object.freeze(['H23', 'H24']), lane: 'hook-overrun' }),
|
|
245
|
-
Object.freeze({ findings: Object.freeze(['H25']), lane: 'gateway-stream-idle' }),
|
|
246
|
-
]);
|