@ngockhoale/ukit 3.5.1 → 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.
Files changed (39) hide show
  1. package/CHANGELOG.md +35 -297
  2. package/README.md +1 -0
  3. package/manifests/platform.full.yaml +23 -0
  4. package/package.json +8 -1
  5. package/src/cli/commands/doctor.js +14 -2
  6. package/src/cli/commands/memory.js +30 -2
  7. package/src/core/memory/memoryHit.js +2 -0
  8. package/src/core/memory/mutateMemory.js +9 -0
  9. package/src/core/memory/projectIdentity.js +9 -2
  10. package/src/core/memory/recallEngine.js +86 -4
  11. package/src/core/memory/registryPrune.js +230 -0
  12. package/src/core/memory/retrieval.js +12 -3
  13. package/src/core/runtimeConfig.js +1 -0
  14. package/src/index/buildIndex.js +22 -0
  15. package/src/index/impactContext.js +11 -1
  16. package/src/index/queryIndex.js +151 -20
  17. package/template_project/.claude/hooks/edit-hint.mjs +119 -0
  18. package/template_project/.claude/settings.json +2 -2
  19. package/template_project/.claude/ukit/index/edit-graph.mjs +404 -0
  20. package/template_project/.claude/ukit/index/lib/index-core.mjs +185 -20
  21. package/template_project/.claude/ukit/index/post-edit-verify.mjs +8 -5
  22. package/template_project/.claude/ukit/index/resolve-context.mjs +17 -0
  23. package/template_project/.claude/ukit/index/route-task.mjs +4 -1
  24. package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs +62 -5
  25. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +259 -0
  26. package/template_project/.claude/ukit/runtime/memory-recall.mjs +86 -4
  27. package/template_project/.claude/ukit/runtime/memory-validity.mjs +232 -0
  28. package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
  29. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  30. package/template_project/AGENTS.md +1 -1
  31. package/template_project/CLAUDE.md +1 -1
  32. package/template_project/instructions/core.md +1 -1
  33. package/src/core/observability/evaluation/experimentPlan.js +0 -95
  34. package/src/core/observability/evaluation/perturbation.js +0 -273
  35. package/src/diagnostics/classifyHang.js +0 -246
  36. package/src/diagnostics/ompStallSnapshot.js +0 -199
  37. package/src/render/instructionRenderer.js +0 -290
  38. package/src/skill/auditSkill.js +0 -140
  39. package/template_project/instructions/overlays/repo.md +0 -9
@@ -45,7 +45,7 @@
45
45
  <!-- RULE: IDX-02 -->
46
46
  2. Open only the **top 1-3 suspect files first**, then widen — `outline:` jumps to `Read(file, offset=<line>)`.
47
47
  <!-- RULE: IDX-03 -->
48
- The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip.
48
+ The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip. No edit hooks (Codex)? `resolve-context --target <file>` before editing lists its mirror, tests, attached memory.
49
49
 
50
50
  ## Automatic Skill Activation (mandatory)
51
51
  <!-- RULE: SKILL-01 -->
@@ -45,7 +45,7 @@
45
45
  <!-- RULE: IDX-02 -->
46
46
  2. Open only the **top 1-3 suspect files first**, then widen — `outline:` jumps to `Read(file, offset=<line>)`.
47
47
  <!-- RULE: IDX-03 -->
48
- The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip.
48
+ The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip. No edit hooks (Codex)? `resolve-context --target <file>` before editing lists its mirror, tests, attached memory.
49
49
 
50
50
  ## Automatic Skill Activation (mandatory)
51
51
  <!-- RULE: SKILL-01 -->
@@ -42,7 +42,7 @@
42
42
  <!-- RULE: IDX-02 -->
43
43
  2. Open only the **top 1-3 suspect files first**, then widen — `outline:` jumps to `Read(file, offset=<line>)`.
44
44
  <!-- RULE: IDX-03 -->
45
- The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip.
45
+ The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip. No edit hooks (Codex)? `resolve-context --target <file>` before editing lists its mirror, tests, attached memory.
46
46
 
47
47
  ## Automatic Skill Activation (mandatory)
48
48
  <!-- RULE: SKILL-01 -->
@@ -1,95 +0,0 @@
1
- /**
2
- * experimentPlan — pure staged controlled-experiment planner (GAP-c).
3
- *
4
- * Maps a KB optimization entry + a `computeGateComparison` GateComparison to
5
- * staged rollout ACTIONS over the seam ladder. The planner EMITS intent only:
6
- * it never mutates config, never calls killSwitch/resolveSeamConfig, and never
7
- * touches fs. Execution (if any) is a separate operator-owned act.
8
- *
9
- * Rules:
10
- * - gate must be a real GateComparison (verdict in pass|non-inferior|unknown);
11
- * anything else → TypeError (a fabricated gate can never plan a promotion).
12
- * - abort flag (operator rollback_criterion met) → kill 'abort-requested'.
13
- * - gate.forbiddenFailures > 0 → kill 'forbidden-failures' prepended.
14
- * - verdict !== 'pass' → hold (reason = verdict). 'non-inferior' means the
15
- * variant FAILED the pre-registered gate.
16
- * - verdict 'pass' + non-empty controlled_rollout.evidence_refs → one promote
17
- * action per seam in stage-rank order (shadow → canary → default), each
18
- * carrying requires_evidence_refs:true. Missing refs → hold
19
- * 'missing-controlled-rollout-evidence': promotion never fires on the
20
- * quality signal alone.
21
- */
22
-
23
- import { SEAM_MIN_STAGE } from '../rollout.js';
24
-
25
- export const ROLLOUT_ACTIONS = Object.freeze(['promote', 'hold', 'kill']);
26
-
27
- const GATE_VERDICTS = new Set(['pass', 'non-inferior', 'unknown']);
28
-
29
- const STAGE_RANK = { shadow: 1, canary: 2, default: 3 };
30
-
31
- function isPlainObject(value) {
32
- return value !== null && typeof value === 'object' && !Array.isArray(value);
33
- }
34
-
35
- function isNonEmptyStringList(value) {
36
- return (
37
- Array.isArray(value) &&
38
- value.length > 0 &&
39
- value.every((v) => typeof v === 'string' && v.length > 0)
40
- );
41
- }
42
-
43
- /**
44
- * @param {{optimization?: object, gate?: object, abort?: boolean}} input
45
- * @returns {{actions: object[]}} frozen action list
46
- */
47
- export function planControlledRollout(input = {}) {
48
- const { optimization, gate, abort } = isPlainObject(input) ? input : {};
49
-
50
- if (!isPlainObject(gate) || !GATE_VERDICTS.has(gate.verdict)) {
51
- throw new TypeError(
52
- 'experimentPlan: gate must be a GateComparison with verdict in pass|non-inferior|unknown',
53
- );
54
- }
55
-
56
- const actions = [];
57
-
58
- if (abort === true) {
59
- actions.push({ type: 'kill', reason: 'abort-requested' });
60
- }
61
- if (gate.forbiddenFailures > 0) {
62
- actions.push({ type: 'kill', reason: 'forbidden-failures' });
63
- }
64
-
65
- if (gate.verdict !== 'pass') {
66
- actions.push({ type: 'hold', reason: gate.verdict });
67
- return { actions: Object.freeze(actions) };
68
- }
69
-
70
- if (actions.length > 0) {
71
- // pass + forbiddenFailures is unreachable from real computeGateComparison
72
- // output (forbidden → non-inferior hard gate); defend the shape anyway.
73
- return { actions: Object.freeze(actions) };
74
- }
75
-
76
- const rollout = isPlainObject(optimization) ? optimization.controlled_rollout : undefined;
77
- const evidenceRefs = isPlainObject(rollout) ? rollout.evidence_refs : undefined;
78
- if (!isNonEmptyStringList(evidenceRefs)) {
79
- return {
80
- actions: Object.freeze([{ type: 'hold', reason: 'missing-controlled-rollout-evidence' }]),
81
- };
82
- }
83
-
84
- // Order from the shared seam contract (read-only): each seam promotes at the
85
- // stage it unlocks, lowest stage rank first.
86
- const seams = Object.entries(SEAM_MIN_STAGE)
87
- .map(([seam, stage]) => ({ seam, stage }))
88
- .sort((a, b) => STAGE_RANK[a.stage] - STAGE_RANK[b.stage] || a.seam.localeCompare(b.seam));
89
-
90
- for (const { seam, stage } of seams) {
91
- actions.push({ type: 'promote', seam, stage, requires_evidence_refs: true });
92
- }
93
-
94
- return { actions: Object.freeze(actions) };
95
- }
@@ -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
- ]);