@ngockhoale/ukit 2.6.9 → 2.6.11

package/src/core/codeintel/retriever.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 
 import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, normalizeRelative } from '../../index/paths.js';
 import { loadRuntimeConfig } from '../runtimeConfig.js';
@@ -260,6 +262,55 @@ function concatMerge(lanes) {
   return merged;
 }
 
+// FR-202b (TASK-228): fire-and-forget lane telemetry. One JSONL line per
+// retrieval at .ukit/storage/cache/retriever-lanes.jsonl; query persisted as
+// sha256 only (no raw prompts on disk). Failures are swallowed — telemetry
+// must never break retrieve(). Sync writes keep the fire-and-forget contract
+// deterministic for callers/tests.
+const RETRIEVER_LANES_MAX_BYTES = 256 * 1024;
+const RETRIEVER_LANES_KEEP_LINES = 2000;
+
+function emitRetrieverLaneTelemetry(rootDir, { query, mode, lanes, omitted, mergedPaths, merge, weights }) {
+  try {
+    const laneStats = {};
+    for (const laneName of LANE_ORDER) {
+      const lane = lanes.get(laneName);
+      const stat = {
+        hits: lane ? lane.length : 0,
+        weightUsed: weights?.[laneName] ?? 0,
+      };
+      const why = omitted?.find((o) => o?.what === `${laneName}-lane`)?.why;
+      if (!lane && why) stat.omitted = why;
+      if (lane) stat.paths = lane.map((entry) => entry.path).slice(0, 100);
+      laneStats[laneName] = stat;
+    }
+    const event = {
+      ts: Date.now(),
+      query: createHash('sha256').update(String(query ?? '')).digest('hex'),
+      mode,
+      lanes: laneStats,
+      mergedPaths,
+      merge,
+    };
+    const filePath = path.join(rootDir, '.ukit', 'storage', 'cache', 'retriever-lanes.jsonl');
+    fsSync.mkdirSync(path.dirname(filePath), { recursive: true });
+    // Best-effort cap: past 256 KiB keep only the newest ~2000 lines.
+    try {
+      const st = fsSync.statSync(filePath);
+      if (st.size > RETRIEVER_LANES_MAX_BYTES) {
+        const kept = fsSync.readFileSync(filePath, 'utf8').split('\n').filter(Boolean)
+          .slice(-RETRIEVER_LANES_KEEP_LINES);
+        fsSync.writeFileSync(filePath, kept.length ? `${kept.join('\n')}\n` : '');
+      }
+    } catch {
+      // Missing/unreadable file is fine — append below recreates it.
+    }
+    fsSync.appendFileSync(filePath, `${JSON.stringify(event)}\n`);
+  } catch {
+    // Telemetry is advisory; never propagate.
+  }
+}
+
 /**
  * retrieve(projectRoot, query, { mode, limit, snapshot, merge, weights }) →
  *   { anchors, evidence, relations, omitted }
@@ -384,6 +435,20 @@ export async function retrieve(projectRoot, query, { mode = 'search', limit, sna
     omitted.push({ what: 'anchors', why: 'no-match' });
   }
 
+  // FR-202b: emit lane telemetry only when a merge result exists — skipped
+  // entirely on the early no-index return and on empty merges.
+  if (merged.length > 0) {
+    emitRetrieverLaneTelemetry(rootDir, {
+      query: normalizedQuery,
+      mode,
+      lanes,
+      omitted,
+      mergedPaths: anchors.map((a) => a.path),
+      merge: effectiveMerge,
+      weights: effectiveWeights,
+    });
+  }
+
   const relations = [];
 
   // Impact mode — 1-hop reverse imports: who imports each anchor file.

package/src/core/memory/store.js

@@ -540,7 +540,8 @@ async function proposePatternCandidateV2(projectRoot, projectId, candidate) {
     .filter((record) => record.provenance === 'pattern-candidate'
       || String(record.provenance ?? '').includes('pattern-candidate'))
     .find((record) => record.meta?.legacyStatus === 'pending'
-      && normalizePatternText(record.text) === normalizedText);
+      && (normalizePatternText(record.text) === normalizedText
+        || (candidate?.signature && record.meta?.signature === candidate.signature)));
   if (existing) {
     return patternCandidateFromRecord(existing);
   }
@@ -553,6 +554,7 @@ async function proposePatternCandidateV2(projectRoot, projectId, candidate) {
     detectedAt: Date.now(),
     status: 'pending',
   };
+  if (candidate?.signature) entry.signature = candidate.signature;
 
   await v2.addRecord(projectRoot, {
     type: 'derived_fact',
@@ -626,7 +628,9 @@ export async function proposePatternCandidate(projectRoot, projectId, candidate)
 
   const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
   const existingPending = patternCandidates.find(
-    (entry) => entry.status === 'pending' && normalizePatternText(entry.text) === normalizedText,
+    (entry) => entry.status === 'pending'
+      && (normalizePatternText(entry.text) === normalizedText
+        || (candidate?.signature && entry.signature === candidate.signature)),
   );
   if (existingPending) {
     return existingPending;
@@ -640,6 +644,7 @@ export async function proposePatternCandidate(projectRoot, projectId, candidate)
     detectedAt: Date.now(),
     status: 'pending',
   };
+  if (candidate?.signature) entry.signature = candidate.signature;
 
   memory.patternCandidates = [...patternCandidates, entry];
   await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);

package/src/core/runtimeConfig.js

@@ -209,6 +209,14 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       maxRetries: 1,
       confidenceThreshold: 50,
     },
+    // Phase-4 learning loop (SPEC §8a). Advisory only — applyMode 'manual'
+    // means suggestions are computed + persisted, never auto-applied.
+    learning: {
+      feedback: { enabled: true, maxEvents: 200 },
+      proposals: { minCount: 3, minSessions: 2 },
+      episodes: { autoWrite: false },
+      tuning: { enabled: true, applyMode: 'manual' },
+    },
     safePatch: {
       enabled: true,
       strictSharedRisk: true,
@@ -564,6 +572,51 @@ export function validateRuntimeConfig(config) {
     pushPositiveNumberError(errors, config.safePatch.deltaMaxDiffCells, 'safePatch.deltaMaxDiffCells');
   }
 
+  // learning is optional-present: absent → valid (old configs); present but
+  // not an object → error. Per-key checks apply only when the sub-object
+  // exists, so partial learning blocks stay valid via defaults merge.
+  if (config.learning !== undefined) {
+    if (!isPlainObject(config.learning)) {
+      errors.push('learning must be an object.');
+    } else {
+      const learning = config.learning;
+      if (learning.feedback !== undefined) {
+        if (!isPlainObject(learning.feedback)) {
+          errors.push('learning.feedback must be an object.');
+        } else {
+          pushBooleanError(errors, learning.feedback.enabled, 'learning.feedback.enabled');
+          pushPositiveNumberError(errors, learning.feedback.maxEvents, 'learning.feedback.maxEvents');
+        }
+      }
+      if (learning.proposals !== undefined) {
+        if (!isPlainObject(learning.proposals)) {
+          errors.push('learning.proposals must be an object.');
+        } else {
+          pushPositiveNumberError(errors, learning.proposals.minCount, 'learning.proposals.minCount');
+          pushPositiveNumberError(errors, learning.proposals.minSessions, 'learning.proposals.minSessions');
+        }
+      }
+      if (learning.episodes !== undefined) {
+        if (!isPlainObject(learning.episodes)) {
+          errors.push('learning.episodes must be an object.');
+        } else {
+          pushBooleanError(errors, learning.episodes.autoWrite, 'learning.episodes.autoWrite');
+        }
+      }
+      if (learning.tuning !== undefined) {
+        if (!isPlainObject(learning.tuning)) {
+          errors.push('learning.tuning must be an object.');
+        } else {
+          pushBooleanError(errors, learning.tuning.enabled, 'learning.tuning.enabled');
+          const VALID_APPLY_MODES = new Set(['manual', 'off']);
+          if (!VALID_APPLY_MODES.has(learning.tuning.applyMode)) {
+            errors.push(`learning.tuning.applyMode must be one of: ${[...VALID_APPLY_MODES].join(', ')}.`);
+          }
+        }
+      }
+    }
+  }
+
   if (!isPlainObject(config.subagents)) {
     errors.push('subagents must be an object.');
   } else {

package/src/diagnostics/failurePatterns.js

@@ -0,0 +1,154 @@
+// failurePatterns.js — advisory failure-pattern mining over exec-ledger receipts (SI-103).
+//
+// What this is for: ledgers already record every verification receipt, but nothing
+// distilled "which commands keep failing". This module scans
+// `.ukit/storage/cache/exec-ledger/*.json`, extracts failed verification receipts,
+// normalizes each command into a deterministic two-token signature, and persists the
+// top patterns to `.ukit/storage/cache/failure-patterns.json` for `ukit metrics`.
+//
+// Contracts (asserted by tests/core/failurePatterns.test.js):
+//   * NEVER THROWS. Missing dir, malformed JSON, unreadable files → zeroed/partial
+//     result, no exception escapes. Artifact write failure is non-fatal: the computed
+//     object is still returned.
+//   * EVIDENCE-ONLY / ADVISORY. Zero writes to memory store, MEMORY.md, or routing
+//     inputs — the only side effect is the last-result cache artifact.
+//   * Deterministic normalization: first two whitespace tokens, lowercased;
+//     path-like and numeric tokens collapse to `<arg>`.
+//   * Same ledger-dir discipline as SPEC §4: glob `*.json`, skip
+//     `gate-crash-counter.json`, `*.journal*`, `*.quarantine*`, bound by mtime.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { listLedgerFiles, LEDGER_DIR_REL } from './ledgerFiles.js';
+
+const ARTIFACT_REL = path.join('.ukit', 'storage', 'cache', 'failure-patterns.json');
+const MAX_PATTERNS = 10;
+const MAX_EXAMPLES = 3;
+
+// Receipt kinds that count as verification-ish evidence.
+const VERIFY_KINDS = new Set(['verify', 'verification']);
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+// First two whitespace tokens, lowercased; path-like or numeric tokens become `<arg>`.
+function normalizeSignature(command) {
+  if (typeof command !== 'string') return null;
+  const tokens = command.trim().toLowerCase().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return null;
+  const head = tokens.slice(0, 2).map((token) => {
+    if (/^\d+(\.\d+)?$/.test(token)) return '<arg>';
+    if (token.includes('/') || token.includes('\\') || token.endsWith('.js')
+      || token.endsWith('.ts') || token.endsWith('.json')) {
+      return '<arg>';
+    }
+    return token;
+  });
+  return head.join(' ');
+}
+
+// Extract failure events from one parsed ledger. A failure event is a receipt with
+// `success === false` on a verification-ish kind carrying a `command`, OR (when the
+// ledger declares `verificationFailed === true`) any receipt carrying a `command`.
+function failureCommands(ledger) {
+  if (!isObject(ledger) || !Array.isArray(ledger.receipts)) return [];
+  const out = [];
+  for (const receipt of ledger.receipts) {
+    if (!isObject(receipt) || typeof receipt.command !== 'string') continue;
+    const verifyFail = receipt.success === false && VERIFY_KINDS.has(receipt.kind);
+    const ledgerFlagged = ledger.verificationFailed === true && receipt.success === false;
+    if (verifyFail || ledgerFlagged) {
+      out.push({ command: receipt.command, file: receipt.file });
+    }
+  }
+  return out;
+}
+
+async function writeArtifact(filePath, result) {
+  const dir = path.dirname(filePath);
+  const tmp = path.join(dir, `.failure-patterns-${process.pid}.tmp`);
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(tmp, JSON.stringify(result, null, 2));
+    await fs.rename(tmp, filePath);
+  } catch {
+    // Non-fatal: artifact is advisory; the computed result is still returned.
+    await fs.rm(tmp, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Mine verification-failure patterns from exec-ledger receipts.
+ *
+ * @param {string} projectRoot repository root containing `.ukit/storage/cache/exec-ledger/`.
+ * @param {{ limitLedgers?: number, minCount?: number }} [options]
+ * @returns {Promise<{generatedAt: string, ledgersScanned: number,
+ *   ledgersWithFailures: number,
+ *   patterns: Array<{signature: string, count: number, sessions: number,
+ *     commands: string[], files: string[]}>}>} never throws.
+ */
+export async function mineFailurePatterns(projectRoot, { limitLedgers = 500, minCount = 2 } = {}) {
+  const result = {
+    generatedAt: new Date().toISOString(),
+    ledgersScanned: 0,
+    ledgersWithFailures: 0,
+    patterns: [],
+  };
+
+  try {
+    const dir = path.join(projectRoot, LEDGER_DIR_REL);
+    const names = await listLedgerFiles(dir, limitLedgers);
+    const groups = new Map();
+
+    for (const name of names) {
+      let ledger;
+      try {
+        ledger = JSON.parse(await fs.readFile(path.join(dir, name), 'utf8'));
+      } catch {
+        continue; // malformed/unreadable ledger — skip, never throw
+      }
+      result.ledgersScanned += 1;
+
+      const failures = failureCommands(ledger);
+      if (failures.length === 0) continue;
+      result.ledgersWithFailures += 1;
+      const sessionId = typeof ledger.sessionId === 'string' ? ledger.sessionId : null;
+
+      for (const { command, file } of failures) {
+        const signature = normalizeSignature(command);
+        if (!signature) continue;
+        let group = groups.get(signature);
+        if (!group) {
+          group = { signature, count: 0, sessions: new Set(), commands: [], files: [] };
+          groups.set(signature, group);
+        }
+        group.count += 1;
+        if (sessionId) group.sessions.add(sessionId);
+        if (group.commands.length < MAX_EXAMPLES && !group.commands.includes(command)) {
+          group.commands.push(command);
+        }
+        if (typeof file === 'string' && group.files.length < MAX_EXAMPLES && !group.files.includes(file)) {
+          group.files.push(file);
+        }
+      }
+    }
+
+    result.patterns = [...groups.values()]
+      .filter((g) => g.count >= minCount)
+      .sort((a, b) => b.count - a.count || a.signature.localeCompare(b.signature))
+      .slice(0, MAX_PATTERNS)
+      .map((g) => ({
+        signature: g.signature,
+        count: g.count,
+        sessions: g.sessions.size,
+        commands: g.commands,
+        files: g.files,
+      }));
+  } catch {
+    // Any unexpected failure → return whatever was computed so far.
+  }
+
+  await writeArtifact(path.join(projectRoot, ARTIFACT_REL), result);
+  return result;
+}

package/src/diagnostics/feedbackEvents.js

@@ -0,0 +1,196 @@
+// feedbackEvents.js — labeled wrong-route feedback events collector (SPEC C32 §3b).
+//
+// Derives labeled events from telemetry already on disk:
+//   * rescue          — route-audit entry with `rescueMode != null` → detail = rescueMode
+//   * re-route        — consecutive same-fingerprint audit entries where the later
+//                       entry changed executionMode (detail "<prev>→<new>")
+//   * repeat-stall    — audit `repeatCount >= minRepeat` with no matching
+//                       ledger `writeSucceeded` (join on requestKey)
+//   * user-correction — manual labels appended by `ukit feedback "<text>"` to
+//                       `.ukit/storage/cache/feedback-manual.jsonl`
+//
+// Contracts:
+//   * NEVER THROWS. Missing/malformed telemetry → zeroed result, `error` field
+//     on failure. Artifact write failure is non-fatal.
+//   * EVIDENCE-ONLY. The only side effect is the advisory artifact
+//     `.ukit/storage/learning/feedback-events.json` (tmp+rename).
+//   * Gated by config `learning?.feedback?.enabled !== false` (default true;
+//     the `learning` namespace lands in TASK-232 so the read is defensive).
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { listLedgerFiles, LEDGER_DIR_REL } from './ledgerFiles.js';
+
+const CACHE_DIR_REL = path.join('.ukit', 'storage', 'cache');
+const AUDIT_REL = path.join(CACHE_DIR_REL, 'route-audit.json');
+const MANUAL_REL = path.join(CACHE_DIR_REL, 'feedback-manual.jsonl');
+const ARTIFACT_REL = path.join('.ukit', 'storage', 'learning', 'feedback-events.json');
+const CONFIG_REL = path.join('.ukit', 'storage', 'config.json');
+const MAX_EVENTS = 200;
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function zeroedResult(extra = {}) {
+  return {
+    generatedAt: new Date().toISOString(),
+    auditRowsScanned: 0,
+    ledgersScanned: 0,
+    byKind: { rescue: 0, 're-route': 0, 'repeat-stall': 0, 'user-correction': 0 },
+    events: [],
+    ...extra,
+  };
+}
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Default true when `learning`/`feedback` is absent (namespace lands in TASK-232).
+async function feedbackEnabled(projectRoot) {
+  const config = await readJson(path.join(projectRoot, CONFIG_REL));
+  return config?.learning?.feedback?.enabled !== false;
+}
+
+// Manual jsonl is field-tolerant: unknown keys ignored, a legacy `context`
+// key is treated as an optional extra. Bad lines are skipped, not fatal.
+async function readManualEvents(projectRoot, byKind) {
+  const events = [];
+  let raw;
+  try {
+    raw = await fs.readFile(path.join(projectRoot, MANUAL_REL), 'utf8');
+  } catch {
+    return events;
+  }
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let record;
+    try {
+      record = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (!isObject(record) || typeof record.text !== 'string') continue;
+    const event = {
+      ts: typeof record.ts === 'number' ? record.ts : 0,
+      kind: 'user-correction',
+      detail: record.text,
+      source: 'manual',
+    };
+    if (typeof record.targetFile === 'string') event.targetFile = record.targetFile;
+    events.push(event);
+    byKind['user-correction'] += 1;
+  }
+  return events;
+}
+
+async function writeArtifact(filePath, result) {
+  const dir = path.dirname(filePath);
+  const tmp = path.join(dir, `.feedback-events-${process.pid}.tmp`);
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(tmp, JSON.stringify(result, null, 2));
+    await fs.rename(tmp, filePath);
+  } catch {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Collect labeled wrong-route feedback events.
+ *
+ * @param {string} projectRoot repository root containing `.ukit/storage/`.
+ * @param {{ limitLedgers?: number, minRepeat?: number }} [options]
+ * @returns {Promise<{generatedAt: string, auditRowsScanned: number,
+ *   ledgersScanned: number, byKind: Record<string, number>,
+ *   events: Array<object>, error?: string}>} never throws.
+ */
+export async function collectFeedbackEvents(projectRoot, { limitLedgers = 500, minRepeat = 2 } = {}) {
+  const result = zeroedResult();
+  try {
+    if (!(await feedbackEnabled(projectRoot))) {
+      return result;
+    }
+
+    const auditDoc = await readJson(path.join(projectRoot, AUDIT_REL));
+    const auditEntries = Array.isArray(auditDoc?.entries)
+      ? auditDoc.entries.filter(isObject)
+      : [];
+    result.auditRowsScanned = auditEntries.length;
+
+    const ledgerDir = path.join(projectRoot, LEDGER_DIR_REL);
+    const ledgerNames = await listLedgerFiles(ledgerDir, limitLedgers);
+    const writeOkKeys = new Set();
+    for (const name of ledgerNames) {
+      const ledger = await readJson(path.join(ledgerDir, name));
+      if (!isObject(ledger)) continue;
+      result.ledgersScanned += 1;
+      if (ledger.writeSucceeded === true && typeof ledger.requestKey === 'string') {
+        writeOkKeys.add(ledger.requestKey);
+      }
+    }
+
+    const events = [];
+    for (const entry of auditEntries) {
+      const base = {
+        ts: typeof entry.ts === 'number' ? entry.ts : 0,
+        requestKey: typeof entry.requestKey === 'string' ? entry.requestKey : undefined,
+        targetFile: typeof entry.targetFile === 'string' ? entry.targetFile : undefined,
+        taskType: typeof entry.taskType === 'string' ? entry.taskType : undefined,
+        executionMode: typeof entry.executionMode === 'string' ? entry.executionMode : undefined,
+        source: 'derived',
+      };
+
+      if (entry.rescueMode != null) {
+        events.push({ ...base, kind: 'rescue', detail: String(entry.rescueMode) });
+        result.byKind.rescue += 1;
+      }
+
+      if ((entry.repeatCount ?? 0) >= minRepeat && !writeOkKeys.has(entry.requestKey)) {
+        events.push({ ...base, kind: 'repeat-stall', detail: `repeatCount=${entry.repeatCount}` });
+        result.byKind['repeat-stall'] += 1;
+      }
+    }
+
+    // re-route: audit is newest-first — entry i is the later entry, i+1 the
+    // previous one for the same promptFingerprint + targetFile.
+    for (let i = 0; i < auditEntries.length - 1; i += 1) {
+      const later = auditEntries[i];
+      const prev = auditEntries[i + 1];
+      if (typeof later.promptFingerprint !== 'string' || !later.promptFingerprint) continue;
+      if (later.promptFingerprint !== prev.promptFingerprint) continue;
+      if (later.targetFile !== prev.targetFile) continue;
+      if (later.wideningBlocked === true) continue;
+      const prevMode = prev.executionMode;
+      const newMode = later.executionMode;
+      if (prevMode == null || newMode == null || prevMode === newMode) continue;
+      events.push({
+        ts: typeof later.ts === 'number' ? later.ts : 0,
+        kind: 're-route',
+        requestKey: typeof later.requestKey === 'string' ? later.requestKey : undefined,
+        targetFile: typeof later.targetFile === 'string' ? later.targetFile : undefined,
+        taskType: typeof later.taskType === 'string' ? later.taskType : undefined,
+        executionMode: typeof later.executionMode === 'string' ? later.executionMode : undefined,
+        detail: `${prevMode}→${newMode}`,
+        source: 'derived',
+      });
+      result.byKind['re-route'] += 1;
+    }
+
+    events.push(...await readManualEvents(projectRoot, result.byKind));
+
+    events.sort((a, b) => b.ts - a.ts);
+    result.events = events.slice(0, MAX_EVENTS);
+  } catch (error) {
+    result.error = error?.message ?? String(error);
+  }
+
+  await writeArtifact(path.join(projectRoot, ARTIFACT_REL), result);
+  return result;
+}

package/src/diagnostics/laneStats.js

@@ -0,0 +1,111 @@
+// laneStats.js — retriever lane contribution stats (SPEC C32 §5b).
+//
+// Reads `.ukit/storage/cache/retriever-lanes.jsonl` emitted by the retriever
+// (FR-202b) and rolls up per-lane counters:
+//   retrievals   = events where the lane had hits > 0
+//   totalHits    = sum of lane hits
+//   exclusive    = events where this lane was the SOLE lane with hits > 0
+//                  (emitters record per-lane hit counts only, so exclusivity
+//                  is approximated rather than per-path recomputed)
+//   avgWeight    = mean weightUsed over events that recorded one
+//   contribution = retrievals / max(1, events)
+//
+// Contracts: NEVER THROWS — missing/empty file → `empty: true` + zeroed lanes.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const LANES_REL = path.join('.ukit', 'storage', 'cache', 'retriever-lanes.jsonl');
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function zeroedResult(extra = {}) {
+  return {
+    generatedAt: new Date().toISOString(),
+    events: 0,
+    lanes: {},
+    empty: false,
+    ...extra,
+  };
+}
+
+function emptyLaneBucket() {
+  return {
+    retrievals: 0,
+    totalHits: 0,
+    exclusive: 0,
+    avgWeight: 0,
+    contribution: 0,
+    _weightSum: 0,
+    _weightCount: 0,
+  };
+}
+
+/**
+ * Collect retriever lane contribution stats.
+ *
+ * @param {string} projectRoot repository root containing `.ukit/storage/`.
+ * @param {{ maxEvents?: number }} [options]
+ * @returns {Promise<object>} never throws.
+ */
+export async function collectLaneStats(projectRoot, { maxEvents = 2000 } = {}) {
+  const result = zeroedResult();
+  try {
+    let raw;
+    try {
+      raw = await fs.readFile(path.join(projectRoot, LANES_REL), 'utf8');
+    } catch {
+      return { ...result, empty: true };
+    }
+    const lines = raw.split('\n');
+    const events = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const record = JSON.parse(trimmed);
+        if (isObject(record) && isObject(record.lanes)) events.push(record);
+      } catch {
+        // skip malformed line
+      }
+      if (events.length >= maxEvents) break;
+    }
+    if (events.length === 0) {
+      return { ...result, empty: true };
+    }
+    result.events = events.length;
+
+    for (const event of events) {
+      const positive = [];
+      for (const [lane, stats] of Object.entries(event.lanes)) {
+        if (!isObject(stats)) continue;
+        const bucket = result.lanes[lane] ??= emptyLaneBucket();
+        const hits = typeof stats.hits === 'number' ? stats.hits : 0;
+        if (hits > 0) {
+          bucket.retrievals += 1;
+          bucket.totalHits += hits;
+          positive.push(lane);
+        }
+        if (typeof stats.weightUsed === 'number') {
+          bucket._weightSum += stats.weightUsed;
+          bucket._weightCount += 1;
+        }
+      }
+      if (positive.length === 1) {
+        result.lanes[positive[0]].exclusive += 1;
+      }
+    }
+
+    for (const bucket of Object.values(result.lanes)) {
+      bucket.avgWeight = bucket._weightCount === 0 ? 0 : bucket._weightSum / bucket._weightCount;
+      bucket.contribution = bucket.retrievals / Math.max(1, result.events);
+      delete bucket._weightSum;
+      delete bucket._weightCount;
+    }
+  } catch (error) {
+    result.error = error?.message ?? String(error);
+  }
+  return result;
+}