@ngockhoale/ukit 2.4.1 → 2.4.3

package/src/diagnostics/classifyHang.js

@@ -0,0 +1,246 @@
+// classifyHang.js — evidence-only hang classifier for the C19 liveness wave (TASK-032).
+//
+// What this is for: C19 removed a family of unbounded paths, and the remaining failure
+// mode is telling ONE stall class apart from another. A prompt freeze used to be
+// indistinguishable from an indexing freeze or a gateway stall, so operators had no
+// evidence-based next step. This module turns an evidence bundle into exactly one
+// declared lane, or `unknown` when the evidence cannot prove any of them.
+//
+// Contracts (asserted by tests/liveness/classifyHang.test.js):
+//   * PURE and CLOCK-FREE. Every rule is a function of the bundle only, so identical
+//     evidence always produces byte-identical output. No Date.now(), no randomness, no
+//     I/O — the caller supplies both the measurement and the clock.
+//   * NEVER GUESSES. A lane is only named when the evidence PROVES it:
+//       - `deadline` with zero survivors is a clean reap, not a process-tree leak;
+//       - survivors beside `failureKind: 'signal'` are NOT a leak: `signal` is documented
+//         by the runner as a signal IT DID NOT SEND, so there is no escalation to blame
+//         and the bundle is `unknown` (the runner's own `deadline` verdict is the only
+//         escalation proof);
+//       - a non-zero hook exit that finished inside its budget is a verdict, not a hang;
+//       - a non-typed index error is not a discovery deadline.
+//     Everything else is `unknown` with a concrete next check.
+//   * The UPSTREAM lane is never a hook. Stream idle with no hook active classifies
+//     `gateway-stream-idle`; the presence of hook evidence removes that lane entirely, so
+//     a gateway stall can no longer be reported as UKit's fault (or the reverse).
+//   * Exactly four fields, always: `{class, confidence, evidenceIds, recommendedNextCheck}`.
+//     `evidenceIds` names the fields the decision rests on, so a reviewer can re-derive it.
+
+/**
+ * The six declared stall lanes. One bundle resolves to at most one of these.
+ * Ordered by decision precedence (see LANE_PRECEDENCE) — the first lane whose evidence
+ * is present AND conclusive owns the classification.
+ */
+export const HANG_CLASSES = Object.freeze([
+  'process-tree-leak',
+  'hook-overrun',
+  'index-deadline',
+  'lock-contention',
+  'context-capacity',
+  'gateway-stream-idle',
+]);
+
+/** The explicit "could not prove a lane" result. Never a member of HANG_CLASSES. */
+export const UNKNOWN_CLASS = 'unknown';
+
+/**
+ * Evidence kinds a bundle may carry. Exported so callers and diagnostics can enumerate
+ * what the classifier understands instead of guessing at field names.
+ */
+export const EVIDENCE_KINDS = Object.freeze([
+  'hook-telemetry',
+  'hook-active',
+  'process-result',
+  'index-error',
+  'lock-outcome',
+  'context-capacity',
+  'stream-idle',
+]);
+
+// Hook-runner outcomes that PROVE the runner ended the child (TASK-018 taxonomy). These
+// are kill verdicts, so they name a lane; `ok` / `exit-code` are verdicts about the hook's
+// own decision and prove nothing about liveness.
+const KILL_OUTCOMES = new Set(['timeout', 'output-overflow', 'budget-exhausted']);
+
+// A leak only exists AFTER the runner's OWN escalation attempt, and only if something is
+// still alive. `failureKind: 'deadline'` is the runner's kill verdict — the deadline timer
+// armed the TERM → KILL sequence, so survivors beside it really are an escapee (H03).
+//
+// `signal` is explicitly NOT escalation evidence: the runner documents it as "the child
+// died from a signal this runner did not send" (hook-process.mjs), which is an unprompted
+// EXTERNAL kill. Survivors beside an external signal may be unrelated processes, and naming
+// a lane off it would fabricate a TERM → KILL diagnosis the evidence cannot support. Such a
+// bundle is `unknown`, never `process-tree-leak`.
+const RUNNER_ESCALATION_KINDS = new Set(['deadline']);
+
+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.';
+
+const NEXT_CHECK = Object.freeze({
+  '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).',
+  '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.',
+  'index-deadline': 'Re-run discovery with a bounded deadline and inspect the recorded phase: git enumeration or the filesystem fallback consumed the whole budget.',
+  '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).',
+  '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.',
+  '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.',
+});
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isPositiveNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+
+function resultFor(cls, confidence, evidenceIds, recommendedNextCheck) {
+  return { class: cls, confidence, evidenceIds, recommendedNextCheck };
+}
+
+function unknown(evidenceIds = []) {
+  return resultFor(UNKNOWN_CLASS, 'none', evidenceIds, UNKNOWN_CHECK);
+}
+
+// ─── per-lane evidence evaluators ────────────────────────────────────────────
+// Each returns { evidenceIds, confidence } when the evidence PROVES the lane, else null.
+
+function detectProcessTreeLeak(bundle) {
+  const processResult = bundle.processResult;
+  if (!isObject(processResult)) return null;
+  const survivors = processResult.survivors;
+  // `survivors` must be an explicit, non-empty array: a missing field is unknown
+  // evidence (the caller never probed), and an empty array is a clean reap.
+  if (!Array.isArray(survivors) || survivors.length === 0) return null;
+  // Survivors alone proves nothing — the runner must have escalated. `signal` is an
+  // external kill, so it stays `unknown` rather than claiming a leak.
+  if (!RUNNER_ESCALATION_KINDS.has(processResult.failureKind)) return null;
+  return { evidenceIds: ['process-result'], confidence: 'high' };
+}
+
+function detectHookOverrun(bundle) {
+  const rows = bundle.hookTelemetry;
+  if (!Array.isArray(rows)) return null;
+  for (let i = 0; i < rows.length; i += 1) {
+    const row = rows[i];
+    if (isObject(row) && KILL_OUTCOMES.has(row.outcome)) {
+      // Cite only the failing row — the row index is the evidence locator.
+      return { evidenceIds: [`hook-telemetry[${i}]`], confidence: 'high' };
+    }
+  }
+  return null;
+}
+
+function detectIndexDeadline(bundle) {
+  const indexError = bundle.indexError;
+  if (!isObject(indexError)) return null;
+  // Only the typed liveness failure is proof; a message alone could be anything.
+  const typed = indexError.name === 'IndexDiscoveryTimeoutError'
+    || indexError.code === 'INDEX_DISCOVERY_TIMEOUT';
+  if (!typed) return null;
+  return { evidenceIds: ['index-error'], confidence: 'high' };
+}
+
+function detectLockContention(bundle) {
+  const lockOutcome = bundle.lockOutcome;
+  if (!isObject(lockOutcome) || lockOutcome.ok !== false) return null;
+  // TASK-028's typed envelope: the callback never ran, so no mutation was lost.
+  if (lockOutcome.reason !== 'busy' && lockOutcome.reason !== 'aborted') return null;
+  return { evidenceIds: ['lock-outcome'], confidence: 'high' };
+}
+
+function detectContextCapacity(bundle) {
+  const context = bundle.context;
+  if (!isObject(context)) return null;
+  const capTokens = context.capTokens;
+  const estimatedTokens = context.estimatedTokens;
+  if (!isPositiveNumber(capTokens) || !isPositiveNumber(estimatedTokens)) return null;
+  if (estimatedTokens < capTokens) return null;
+  return { evidenceIds: ['context-capacity'], confidence: 'high' };
+}
+
+function detectGatewayStreamIdle(bundle) {
+  const stream = bundle.stream;
+  if (!isObject(stream)) return null;
+  const idleMs = stream.idleMs;
+  const idleTimeoutMs = stream.idleTimeoutMs;
+  // Both numbers are required: without the negotiated timeout there is nothing to
+  // compare against, and an idle duration alone proves no stall.
+  if (!isPositiveNumber(idleMs) || !isPositiveNumber(idleTimeoutMs)) return null;
+  if (idleMs < idleTimeoutMs) return null;
+  // A hook was active while the stream was silent → the silence may be UKit's, so the
+  // upstream lane is removed entirely. Never blame the gateway over hook evidence.
+  // `null`/`undefined` both mean "no hook was active" — only a real value withholds it.
+  if (bundle.hookActive !== null && bundle.hookActive !== undefined) return null;
+  return { evidenceIds: ['stream-idle'], confidence: 'high' };
+}
+
+// Precedence: the most specific, evidence-backed lane wins. The upstream lane is LAST —
+// it is the only lane whose proof is the ABSENCE of other evidence, so it may only be
+// reached once every hook/index/lock/context claim had its chance.
+const LANE_PRECEDENCE = Object.freeze([
+  ['process-tree-leak', detectProcessTreeLeak],
+  ['hook-overrun', detectHookOverrun],
+  ['index-deadline', detectIndexDeadline],
+  ['lock-contention', detectLockContention],
+  ['context-capacity', detectContextCapacity],
+  ['gateway-stream-idle', detectGatewayStreamIdle],
+]);
+
+// Evidence that was considered but is NOT sufficient to name a lane. Reported on the
+// `unknown` result so a caller sees what was looked at, never just "nothing".
+function inconclusiveEvidenceIds(bundle) {
+  const ids = [];
+  if (Array.isArray(bundle.hookTelemetry) && bundle.hookTelemetry.length > 0) {
+    ids.push('hook-telemetry');
+  }
+  if (isObject(bundle.hookActive)) ids.push('hook-active');
+  if (isObject(bundle.stream)) ids.push('stream-idle');
+  if (isObject(bundle.processResult)) ids.push('process-result');
+  if (isObject(bundle.indexError)) ids.push('index-error');
+  if (isObject(bundle.lockOutcome)) ids.push('lock-outcome');
+  if (isObject(bundle.context)) ids.push('context-capacity');
+  return ids;
+}
+
+/**
+ * Classify ONE stall from an evidence bundle.
+ *
+ * @param {object} [bundle] evidence collected by a scenario or a live diagnostic:
+ *   `hookTelemetry`  — redacted telemetry rows (TASK-019 schema; `outcome` is the
+ *                      runner's taxonomy, `hook` names the emitter).
+ *   `hookActive`     — `{hook, activeMs}` when a hook held the hot path. Presence alone
+ *                      removes the upstream lane.
+ *   `processResult`  — `{failureKind, signal, code, elapsedMs, survivors}` from the
+ *                      process-tree runner. `survivors` is the escalation probe.
+ *   `indexError`     — the thrown error (or its shape) from index discovery.
+ *   `lockOutcome`    — the typed `{ok:false, reason:'busy'|'aborted', waitedMs}` envelope.
+ *   `context`        — `{capTokens, estimatedTokens, ...}` from capacity negotiation.
+ *   `stream`         — `{idleMs, idleTimeoutMs, ...}` from stream timing.
+ * @returns {{ class: string, confidence: 'high'|'none', evidenceIds: string[],
+ *             recommendedNextCheck: string }} exactly four fields; `class` is either a
+ *   member of HANG_CLASSES or UNKNOWN_CLASS.
+ */
+export function classifyHang(bundle = {}) {
+  if (!isObject(bundle)) return unknown();
+
+  for (const [lane, detect] of LANE_PRECEDENCE) {
+    const evidence = detect(bundle);
+    if (evidence) return resultFor(lane, evidence.confidence, evidence.evidenceIds, NEXT_CHECK[lane]);
+  }
+
+  return unknown(inconclusiveEvidenceIds(bundle));
+}
+
+/**
+ * C19 finding → lane map. Every finding this cycle addressed has a lane whose evidence a
+ * scenario in `tests/liveness/hangScenarios.test.js` produces, so no finding is left
+ * without a classifier answer. Exposed as data (not prose) so the liveness suite can fail
+ * when coverage regresses.
+ */
+export const C19_LANE_MAP = Object.freeze([
+  Object.freeze({ findings: Object.freeze(['H01', 'H02', 'H05', 'H08', 'H21']), lane: 'hook-overrun' }),
+  Object.freeze({ findings: Object.freeze(['H03']), lane: 'process-tree-leak' }),
+  Object.freeze({ findings: Object.freeze(['H09', 'H10', 'H11', 'H12', 'H13', 'H14', 'H15']), lane: 'index-deadline' }),
+  Object.freeze({ findings: Object.freeze(['H16', 'H17', 'H18', 'H19', 'H20']), lane: 'lock-contention' }),
+  Object.freeze({ findings: Object.freeze(['H04', 'H22']), lane: 'context-capacity' }),
+  Object.freeze({ findings: Object.freeze(['H23', 'H24']), lane: 'hook-overrun' }),
+  Object.freeze({ findings: Object.freeze(['H25']), lane: 'gateway-stream-idle' }),
+]);