@ngockhoale/ukit 3.3.2 → 3.4.0

package/src/index/fixLoopEscalation.js

@@ -0,0 +1,453 @@
+// fixLoopEscalation.js — fix-loop escalation to a deeper lane (C85 TASK-018,
+// BL-018 / SPEC FR-006 / ARCH §State Machine fix-loop transition).
+//
+// "Fast becomes sloppy" loops exit into rigor instead of a third blind retry:
+// when `historySignals.fixLoopCount` — the fingerprint-joined counter of failed
+// attempts on the SAME `routeFingerprint`/`requestKey` (never a session-wide
+// counter, GAP M12) — reaches `orchestration.escalation.debugLoopThreshold`,
+// the route deepens its lane:
+//
+//   escalate → bounded unic-decision `laneDeepening`/`verificationDepth`
+//     questions (BL-017 family machinery) → deeper debug + verification lane.
+//   live-symptom loops hand off toward the `runtime-forensics` playbookId row;
+//     while the file is absent the route stamps `playbookLoad: 'missing'` and
+//     the lane still deepens (SPEC §14 degrade contract).
+//   decision endpoint down/malformed → deterministic deeper-lane fallback;
+//     the existing deterministic tier-bump path (`applyEscalationToRouteSummary`)
+//     stays in force as the escalation fallback — recorded as `fallback:tier-bump`.
+//   deeper lane already escalated and the same fingerprint still fails →
+//     BLOCKED with a named blocker + attempts evidence; never another
+//     same-lane retry (ARCH §Failure Modes "fix-loop escalation exhausted").
+//
+// This module is deterministic and performs NO I/O itself: the decision-plane
+// call, the registry presence check, and the receipt append are injected by
+// each router surface (taskRouting.js supplies the in-process decision client;
+// route-task.mjs supplies the unic-decision.mjs CLI spawn + ledger receipts).
+//
+// Mirror parity: template_project/.claude/ukit/index/fix-loop-escalation.mjs
+// carries the identical logic (the mirror cannot import src/). Both twins are
+// locked by tests/index/fixLoopEscalation.test.js parity cases.
+
+import {
+  resolveRouteStage,
+  resolveDecisionPlaneStage,
+} from './routeResolver.js';
+import { resolveCrossCheckDepth } from './crossCheckMatrix.js';
+
+// Deepening vocabulary = the contract lane ladder (EXECUTION_MODE_ORDER); the
+// non-contract 'informational' lane is never an escalation destination.
+export const FIX_LOOP_LANE_CANDIDATES = Object.freeze([
+  'tiny-fix',
+  'local-fix',
+  'local-build',
+  'find-cause',
+  'shared-edit',
+  'map-impact',
+  'review-release',
+]);
+
+// Deterministic deeper-lane map — the fallback the endpoint-down path records
+// as `fallback:tier-bump` AND the deterministic endpoint the escalated lane
+// still deepens to. Architecture ladder (ARCH §State Machine): shallow fix
+// lanes deepen to find-cause (systematic-debugging depth); find-cause widens
+// to map-impact; already-deep lanes stay put — the loop on them is the
+// exhaustion signal, handled by the BLOCKED transition.
+export const FIX_LOOP_LANE_DEEPENING = Object.freeze({
+  'tiny-fix': 'find-cause',
+  'local-fix': 'find-cause',
+  'local-build': 'find-cause',
+  'find-cause': 'map-impact',
+  'shared-edit': 'find-cause',
+  'map-impact': 'map-impact',
+  'review-release': 'map-impact',
+  informational: 'find-cause',
+});
+
+// BL-018 escalation questions — the BL-017 ROUTE_SHADOW_QUESTIONS entries the
+// escalation fires. Candidates are protocol-local labels; identical rows live
+// in route-resolver.mjs and are parity-locked by the family table test.
+export const FIX_LOOP_ESCALATION_QUESTIONS = Object.freeze([
+  {
+    decisionKey: 'lane.deepening.v1',
+    kind: 'choice',
+    instruction: 'Execution lane after fix-loop escalation deepening.',
+    candidates: [...FIX_LOOP_LANE_CANDIDATES],
+  },
+  {
+    decisionKey: 'verification.depth.v1',
+    kind: 'choice',
+    instruction: 'Verification depth for this route.',
+    candidates: ['none', 'runnable', 'review-round', 'escalate'],
+  },
+]);
+
+const DEFAULT_FIX_LOOP_DEBUG_THRESHOLD = 2;
+
+// Live-symptom vocabulary — a non-deterministic repro (hang/leak/intermittent)
+// is the runtime-forensics hand-off, while a named test-harness failure IS a
+// deterministic repro and stays in the standard deeper lane. Mirrors the
+// playbook-registry signal (its regexes are registry-private).
+const LIVE_SYMPTOM_RE = /\b(hangs?|leaks?|sometimes|intermittent|flaky|occasionally|random|sporadic|one in \d+|about \d+ in \d+|cpuprofile|heap\s*(?:dump|snapshot|profile)|memory profile|dropped (?:a )?(?:cpu|heap|profile) artifact)\b/i;
+const TEST_HARNESS_RE = /\b(spec|test|tests|assertion)\b/i;
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function clampThreshold(value, fallback = DEFAULT_FIX_LOOP_DEBUG_THRESHOLD) {
+  return Number.isFinite(value) && value > 0
+    ? Math.max(1, Math.floor(value))
+    : fallback;
+}
+
+// Escalation settings consumed from `orchestration.escalation` — the SAME block
+// the tier-bump ladder reads (runtimeConfig.js ships debugLoopThreshold: 2).
+// `laneDeepening` is the additive BL-018 switch; absent defaults to enabled.
+export function resolveFixLoopEscalationConfig(config = null) {
+  const raw = config?.orchestration?.escalation;
+  return {
+    enabled: typeof raw?.enabled === 'boolean' ? raw.enabled : true,
+    debugLoopThreshold: clampThreshold(raw?.debugLoopThreshold),
+    laneDeepening: raw?.laneDeepening !== false,
+  };
+}
+
+// Same-symptom detection joins on the fingerprint-joined history counter —
+// fixLoopCount only counts markers matching the current routeFingerprint/
+// requestKey (sessionHistoryExtractor), so a session full of UNRELATED failures
+// can never trip this gate (SPEC §10). Same-symptom semantics live in the
+// caller-supplied counter; this gate is a pure threshold comparison.
+export function isFixLoopEscalationDue({
+  historySignals = null,
+  config = null,
+} = {}) {
+  const settings = resolveFixLoopEscalationConfig(config);
+  if (!settings.enabled || !settings.laneDeepening) {
+    return false;
+  }
+  const fixLoopCount = Number.isFinite(historySignals?.fixLoopCount)
+    ? Math.max(0, Math.floor(historySignals.fixLoopCount))
+    : 0;
+  return fixLoopCount >= settings.debugLoopThreshold;
+}
+
+// Deterministic deeper lane for a fix-loop escalation — the fallback the
+// endpoint-down path rides (recorded as `fallback:tier-bump` since the
+// tier-escalation ladder stays the escalation's deterministic fallback).
+export function deterministicEscalatedLane(currentLane = null) {
+  return FIX_LOOP_LANE_DEEPENING[currentLane] ?? 'find-cause';
+}
+
+// Live-symptom detection for the runtime-forensics hand-off. Only a
+// non-deterministic repro qualifies — an explicit spec/test failure is a
+// deterministic repro, which deepens to find-cause instead.
+export function isLiveSymptomRoute({
+  routeSummary = null,
+  routingContext = {},
+} = {}) {
+  if (routeSummary?.workGroup === 'runtime-forensics') return true;
+  const signalText = [routingContext.promptText, routingContext.commandText]
+    .map((value) => String(value ?? '').trim().toLowerCase())
+    .filter(Boolean)
+    .join('\n');
+  if (signalText === '') return false;
+  return LIVE_SYMPTOM_RE.test(signalText) && !TEST_HARNESS_RE.test(signalText);
+}
+
+// Deterministic deeper verification depth — the cross-check matrix (BL-016)
+// resolved over the route's own risk/evidence inputs. 'none' cannot be the
+// answer to a fix loop: the floor is 'runnable' so the deeper lane always
+// carries a runnable check.
+export function resolveEscalationVerificationDepth({
+  routeSummary = null,
+  config = null,
+} = {}) {
+  try {
+    const resolved = resolveCrossCheckDepth({
+      riskFloor: routeSummary?.riskFloor ?? null,
+      rigor: routeSummary?.execution?.rigor ?? null,
+      evidenceQuality: routeSummary?.verificationRecipe?.evidenceRequired ?? null,
+      overrides: config?.crossCheck ?? null,
+    });
+    const depth = typeof resolved?.depth === 'string' ? resolved.depth : null;
+    return depth && depth !== 'none' ? depth : 'runnable';
+  } catch {
+    return 'runnable';
+  }
+}
+
+function validAnswerValue(result, decisionKey, candidates) {
+  const answers = Array.isArray(result?.answers) ? result.answers : [];
+  for (const answer of answers) {
+    if (answer?.decisionKey !== decisionKey) continue;
+    if (answer?.validationStatus !== 'valid') continue;
+    const value = typeof answer?.value === 'string' ? answer.value.trim() : null;
+    if (value && candidates.includes(value)) return value;
+  }
+  return null;
+}
+
+// Build the bounded statePacket the laneDeepening/verificationDepth batch
+// carries — identical vocabulary to the shadow batch (bounded counters and
+// enums only; never prompt text, transcript text, or raw state blobs).
+export function buildFixLoopStatePacket({
+  routeSummary = null,
+  routingContext = {},
+} = {}) {
+  const hist = routeSummary?.historySignals ?? null;
+  return {
+    stateVersion: 1,
+    taskClass: routingContext.taskClass ?? routingContext.taskType ?? 'unknown',
+    intentSignals: routingContext.intentMode ? [routingContext.intentMode] : [],
+    targetClass: routingContext.targetFile ? 'file-target' : 'no-target',
+    execution: routeSummary?.executionMode ? { mode: routeSummary.executionMode } : {},
+    riskSignals: routeSummary?.riskFloor?.codes ?? [],
+    history: hist
+      ? {
+          priorAttemptCount: Math.max(0, Math.trunc(hist.priorAttemptCount ?? 0) || 0),
+          fixLoopCount: Math.max(0, Math.trunc(hist.fixLoopCount ?? 0) || 0),
+          sameSymptomReask: hist.sameSymptomReask === true,
+          correctionEvents: Math.max(0, Math.trunc(hist.correctionEvents ?? hist.correctionCount ?? 0) || 0),
+          degraded: hist.degraded === true,
+        }
+      : null,
+  };
+}
+
+/**
+ * Apply the fix-loop escalation transition to a built routeSummary.
+ *
+ * Additive route fields produced:
+ *   escalatedLane                deeper lane, or 'blocked' on exhaustion
+ *   escalateReason               bounded machine-readable reason
+ *   escalatedVerificationDepth   deeper verification depth (escalate only)
+ *   escalatedRouteFingerprint    the routeFingerprint this escalation record
+ *                                belongs to — the same-loop join key: a prior
+ *                                escalatedLane/blocked is only honored when
+ *                                its carried fingerprint equals the current
+ *                                routeFingerprint (SPEC §10; a different
+ *                                fingerprint's record is a different loop and
+ *                                can never fabricate a blocked verdict or
+ *                                leak a lane onto an unrelated route).
+ *
+ * Returns `{action:'escalate'|'blocked'|'preserve'|'clear'}`; 'preserve'/'clear'
+ * leave the summary so threshold-1 attempts and non-loop routes stay exactly
+ * as before (a previously escalated lane persists across emissions — it is the
+ * same fingerprint's recorded escalation, not a fresh one). 'blocked' is
+ * terminal: a same-fingerprint re-ask stays blocked with no decision-plane
+ * round and no re-escalation.
+ *
+ * Injected seams (each surface wires its own):
+ *   ask({batch}) → DecisionBatchResult     decision-plane call; null = stage off
+ *   appendReceipt(receipt)                 decisions.tsv writer; may be async
+ *   runtimeForensicsPresent                boolean — runtime-forensics.md
+ *                                          resolved through the playbook
+ *                                          registry (absent → 'missing')
+ *   previousRouteSummary                   prior emission for the same route
+ *                                          (drives the exhaustion BLOCKED path)
+ *   routeFingerprint                       current route's fingerprint — the
+ *                                          same-loop join key stamped onto
+ *                                          the escalation record
+ */
+export async function applyFixLoopEscalation({
+  routeSummary = null,
+  routingContext = {},
+  previousRouteSummary = null,
+  routeFingerprint = null,
+  config = null,
+  ask = null,
+  appendReceipt = null,
+  runtimeForensicsPresent = null,
+  now = () => Date.now(),
+} = {}) {
+  if (!isPlainObject(routeSummary)) {
+    return { action: 'clear', routeSummary };
+  }
+
+  const settings = resolveFixLoopEscalationConfig(config);
+  const stage = resolveRouteStage(config, 'escalation');
+  const fixLoopCount = Number.isFinite(routeSummary?.historySignals?.fixLoopCount)
+    ? Math.max(0, Math.floor(routeSummary.historySignals.fixLoopCount))
+    : 0;
+  const thresholdMet = fixLoopCount >= settings.debugLoopThreshold;
+  // Same-loop join (SPEC §10): a prior escalation record only binds when the
+  // fingerprint it was stamped under equals THIS route's fingerprint — a
+  // different fingerprint's escalatedLane is a different loop, never this
+  // route's spent escalation, and a fingerprint-less record can never be
+  // verified as same-loop (escalate fresh, never fabricate 'blocked').
+  const priorLane = previousRouteSummary?.escalatedLane ?? null;
+  const priorLoopFingerprint = previousRouteSummary?.escalatedRouteFingerprint ?? null;
+  const sameLoop = Boolean(priorLane)
+    && Boolean(priorLoopFingerprint)
+    && priorLoopFingerprint === routeFingerprint;
+
+  // ── not due: preserve a same-fingerprint escalation, else stay clean ──
+  if (stage === 'off' || !settings.enabled || !settings.laneDeepening || !thresholdMet) {
+    if (sameLoop) {
+      routeSummary.escalatedLane = priorLane;
+      routeSummary.escalateReason = previousRouteSummary.escalateReason ?? null;
+      routeSummary.escalatedRouteFingerprint = priorLoopFingerprint;
+      if (previousRouteSummary.escalatedVerificationDepth != null) {
+        routeSummary.escalatedVerificationDepth = previousRouteSummary.escalatedVerificationDepth;
+      } else {
+        delete routeSummary.escalatedVerificationDepth;
+      }
+      return { action: 'preserve', routeSummary };
+    }
+    delete routeSummary.escalatedLane;
+    delete routeSummary.escalateReason;
+    delete routeSummary.escalatedVerificationDepth;
+    delete routeSummary.escalatedRouteFingerprint;
+    return { action: 'clear', routeSummary };
+  }
+
+  const currentLane = typeof routeSummary.executionMode === 'string'
+    ? routeSummary.executionMode
+    : null;
+  const deterministicLane = deterministicEscalatedLane(currentLane);
+  const liveSymptom = isLiveSymptomRoute({ routeSummary, routingContext });
+  const emit = (receipt) => {
+    if (typeof appendReceipt !== 'function') return;
+    try {
+      const pending = appendReceipt(receipt);
+      if (pending?.catch) pending.catch(() => {});
+    } catch {
+      // Receipt loss is advisory — the escalation stands regardless.
+    }
+  };
+
+  // ── blocked is terminal: the same fingerprint already exhausted its
+  // escalation → stay blocked with the prior blocker, no decision-plane
+  // round, no re-escalation (a different fingerprint's 'blocked' record can
+  // never reach here — sameLoop already gates the join).
+  if (sameLoop && priorLane === 'blocked') {
+    routeSummary.escalatedLane = 'blocked';
+    routeSummary.escalateReason = previousRouteSummary.escalateReason ?? null;
+    routeSummary.escalatedRouteFingerprint = priorLoopFingerprint;
+    delete routeSummary.escalatedVerificationDepth;
+    return { action: 'blocked', routeSummary };
+  }
+
+  // ── exhausted: the deeper lane already escalated for this fingerprint and
+  // the same fingerprint still fails → BLOCKED with the blocker named; never
+  // another same-lane retry. escalatedLane is recorded, never promoted to
+  // executionMode, so priorLane === currentLane IS the spent-escalation case.
+  if (sameLoop) {
+    const reason = [
+      `blocked: fix-loop-exhausted lane=${priorLane} fixLoopCount=${fixLoopCount}`,
+      'blocker=deeper-lane-still-failing (no further same-lane retries — escalate to the human or new evidence)',
+    ].join(' ');
+    routeSummary.escalatedLane = 'blocked';
+    routeSummary.escalateReason = reason;
+    routeSummary.escalatedRouteFingerprint = priorLoopFingerprint;
+    delete routeSummary.escalatedVerificationDepth;
+    emit({
+      kind: 'applied',
+      boundary: 'route',
+      stage: 'deterministic',
+      outcomeClass: 'blocked',
+      checkpoint: `fix-loop escalation exhausted lane=${priorLane} attempts=${fixLoopCount}`,
+      latencyClass: 'unknown',
+      decisionKeys: ['lane.deepening.v1'],
+      agreement: 'n/a',
+      fallbackCode: 'fix-loop-exhausted',
+      now: typeof now === 'function' ? now() : undefined,
+    });
+    return { action: 'blocked', routeSummary };
+  }
+
+  // ── escalate: laneDeepening/verificationDepth question → deeper lane ──
+  const planeStage = resolveDecisionPlaneStage(config);
+  let batchResult = null;
+  if (planeStage !== 'off' && typeof ask === 'function') {
+    const batch = {
+      batchId: `fix-loop-escalation-${now().toString(36)}`,
+      boundary: 'route',
+      deadlineMs: Math.max(
+        500,
+        Number.isFinite(config?.decisionPlane?.timeoutMs)
+          ? config.decisionPlane.timeoutMs
+          : 2000,
+      ),
+      statePacket: buildFixLoopStatePacket({ routeSummary, routingContext }),
+      questions: [...FIX_LOOP_ESCALATION_QUESTIONS],
+    };
+    try {
+      batchResult = await ask({ batch });
+    } catch {
+      batchResult = null;
+    }
+  }
+
+  const modelLane = batchResult
+    ? validAnswerValue(batchResult, 'lane.deepening.v1', FIX_LOOP_LANE_CANDIDATES)
+    : null;
+  const modelDepth = batchResult
+    ? validAnswerValue(
+        batchResult,
+        'verification.depth.v1',
+        FIX_LOOP_ESCALATION_QUESTIONS[1].candidates,
+      )
+    : null;
+  // A model lane that refuses to deepen is not an escalation answer — the
+  // deterministic deeper lane wins so the loop actually exits its lane.
+  const usableModelLane = modelLane && modelLane !== currentLane ? modelLane : null;
+  const lane = usableModelLane ?? deterministicLane;
+  const endpointDown = batchResult !== null
+    && batchResult.status !== 'accepted'
+    && batchResult.status !== 'partial'
+    && !usableModelLane;
+  const depth = (modelDepth && modelDepth !== 'none' ? modelDepth : null)
+    ?? resolveEscalationVerificationDepth({ routeSummary, config });
+
+  const reason = [
+    `fix-loop: fixLoopCount=${fixLoopCount} threshold=${settings.debugLoopThreshold} fingerprint-joined`,
+    lane === usableModelLane
+      ? `laneDeepening=${lane}`
+      : `laneDeepening=${lane} (${endpointDown ? 'fallback:tier-bump' : 'deterministic'})`,
+    `verificationDepth=${depth}`,
+    liveSymptom ? 'live-symptom→runtime-forensics' : null,
+  ].filter(Boolean).join(' ');
+
+  routeSummary.escalatedLane = lane;
+  routeSummary.escalateReason = reason;
+  routeSummary.escalatedVerificationDepth = depth;
+  // The escalation record carries THIS route's fingerprint — the next
+  // emission's same-loop join (exhaustion/blocked-terminal/preserve) only
+  // binds a record whose stamped fingerprint still matches.
+  routeSummary.escalatedRouteFingerprint = routeFingerprint;
+
+  // Live-symptom hand-off: the escalation destination row is runtime-forensics.
+  // While the file is absent the registry degrade applies — playbookLoad:
+  // 'missing' is stamped honestly and the lane deepens anyway (SPEC §14).
+  if (liveSymptom && routeSummary.workGroup !== 'runtime-forensics') {
+    routeSummary.playbookId = 'runtime-forensics';
+    routeSummary.workGroup = 'runtime-forensics';
+    if (runtimeForensicsPresent === true) {
+      routeSummary.playbookReason = 'fix-loop-escalation';
+      routeSummary.playbookLoad = null;
+    } else {
+      routeSummary.playbookReason = 'fix-loop-escalation:playbook-missing';
+      routeSummary.playbookLoad = 'missing';
+    }
+  } else if (liveSymptom) {
+    // Natural resolution already claimed the row — surface the destination id
+    // (the registry returned playbookId: null on the missing-file degrade).
+    routeSummary.playbookId = 'runtime-forensics';
+    routeSummary.playbookLoad = runtimeForensicsPresent === true ? null : 'missing';
+  }
+
+  emit({
+    kind: endpointDown ? 'fallback' : 'applied',
+    boundary: 'route',
+    stage: planeStage === 'off' ? 'deterministic' : planeStage,
+    outcomeClass: batchResult?.status ?? 'deterministic',
+    checkpoint: `fix-loop escalate lane=${lane} depth=${depth} loop=${fixLoopCount}`,
+    latencyClass: batchResult?.latencyClass ?? 'unknown',
+    decisionKeys: FIX_LOOP_ESCALATION_QUESTIONS.map((q) => q.decisionKey),
+    agreement: usableModelLane ? 'model' : 'deterministic',
+    fallbackCode: batchResult?.fallbackCode ?? null,
+    now: typeof now === 'function' ? now() : undefined,
+  });
+  return { action: 'escalate', routeSummary };
+}