@ngockhoale/ukit 2.6.9 → 2.6.11

package/src/diagnostics/ledgerFiles.js

@@ -0,0 +1,47 @@
+// ledgerFiles.js — shared exec-ledger directory helpers (SPEC C32 §3a).
+//
+// Extracted from failurePatterns.js so feedbackEvents (and any future
+// ledger-scanning diagnostics) share one glob/mtime discipline:
+//   * glob `*.json`, skip `gate-crash-counter.json`, `*.journal*`,
+//     `*.quarantine*`, bound results by mtime-desc order.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const LEDGER_DIR_REL = path.join('.ukit', 'storage', 'cache', 'exec-ledger');
+
+const NON_LEDGER_FILES = new Set(['gate-crash-counter.json']);
+
+export function isLedgerFilename(name) {
+  if (typeof name !== 'string' || !name.endsWith('.json')) return false;
+  if (NON_LEDGER_FILES.has(name)) return false;
+  if (name.includes('.journal')) return false;
+  if (name.includes('.quarantine')) return false;
+  return true;
+}
+
+// Returns up to `limit` ledger filenames sorted by mtime descending.
+// Missing/unreadable dir → [] (never throws).
+export async function listLedgerFiles(dir, limit) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !isLedgerFilename(entry.name)) continue;
+    files.push(entry.name);
+  }
+  const withMtime = await Promise.all(files.map(async (name) => {
+    try {
+      const stat = await fs.stat(path.join(dir, name));
+      return { name, mtimeMs: stat.mtimeMs };
+    } catch {
+      return { name, mtimeMs: 0 };
+    }
+  }));
+  withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return withMtime.slice(0, Math.max(0, limit)).map((f) => f.name);
+}

package/src/diagnostics/routeOutcomes.js

@@ -0,0 +1,146 @@
+// Route-outcome join (SPEC §4, SI-102): joins route-audit.json entries to
+// per-request exec-ledger ledgers on requestKey and aggregates outcome stats
+// per executionMode / taskType. Read-only; never throws.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const UNCLASSIFIED = '(unclassified)';
+const LEDGER_EXCLUDE = new Set(['gate-crash-counter.json']);
+
+function zeroedResult(extra = {}) {
+  return {
+    generatedAt: new Date().toISOString(),
+    ledgersScanned: 0,
+    auditRowsScanned: 0,
+    joined: 0,
+    unmatchedAudit: 0,
+    unmatchedLedger: 0,
+    byMode: {},
+    byTaskType: {},
+    joinCoverage: 0,
+    ...extra,
+  };
+}
+
+function emptyBucket() {
+  return {
+    routes: 0,
+    joined: 0,
+    writeOk: 0,
+    writeFail: 0,
+    verifyAttempted: 0,
+    verifyOk: 0,
+    verifyFail: 0,
+    rescue: 0,
+    stalled: 0,
+  };
+}
+
+async function listLedgerFiles(ledgerDir, limitLedgers) {
+  let dirents;
+  try {
+    dirents = await fs.readdir(ledgerDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const candidates = [];
+  for (const dirent of dirents) {
+    if (!dirent.isFile()) continue;
+    const name = dirent.name;
+    if (!name.endsWith('.json')) continue;
+    if (LEDGER_EXCLUDE.has(name)) continue;
+    if (name.includes('.journal') || name.includes('.quarantine')) continue;
+    candidates.push(name);
+  }
+  const withMtime = await Promise.all(candidates.map(async (name) => {
+    try {
+      const stat = await fs.stat(path.join(ledgerDir, name));
+      return { name, mtimeMs: stat.mtimeMs };
+    } catch {
+      return { name, mtimeMs: 0 };
+    }
+  }));
+  withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return withMtime.slice(0, Math.max(0, limitLedgers)).map((entry) => entry.name);
+}
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function bump(bucket, ledger, auditEntry) {
+  bucket.joined += 1;
+  if (ledger.writeSucceeded === true) bucket.writeOk += 1;
+  else if (ledger.writeAttempted === true) bucket.writeFail += 1;
+  if (ledger.verificationAttempted === true) bucket.verifyAttempted += 1;
+  if (ledger.verificationSucceeded === true) bucket.verifyOk += 1;
+  if (ledger.verificationFailed === true) bucket.verifyFail += 1;
+  if (auditEntry.rescueMode != null) bucket.rescue += 1;
+  if ((auditEntry.repeatCount ?? 0) >= 2 && ledger.writeSucceeded !== true) {
+    bucket.stalled += 1;
+  }
+}
+
+export async function collectRouteOutcomes(projectRoot, { limitLedgers = 500 } = {}) {
+  try {
+    const cacheDir = path.join(projectRoot, '.ukit', 'storage', 'cache');
+    const auditDoc = await readJson(path.join(cacheDir, 'route-audit.json'));
+    const auditEntries = Array.isArray(auditDoc?.entries) ? auditDoc.entries : [];
+
+    const ledgerDir = path.join(cacheDir, 'exec-ledger');
+    const ledgerFiles = await listLedgerFiles(ledgerDir, limitLedgers);
+    const ledgers = [];
+    for (const name of ledgerFiles) {
+      const doc = await readJson(path.join(ledgerDir, name));
+      if (doc && typeof doc === 'object') ledgers.push(doc);
+    }
+
+    const result = zeroedResult();
+    result.ledgersScanned = ledgers.length;
+    result.auditRowsScanned = auditEntries.length;
+
+    const auditByKey = new Map();
+    for (const entry of auditEntries) {
+      if (entry && typeof entry.requestKey === 'string' && entry.requestKey) {
+        auditByKey.set(entry.requestKey, entry);
+      }
+    }
+    const ledgerKeys = new Set();
+    for (const ledger of ledgers) {
+      if (ledger && typeof ledger.requestKey === 'string' && ledger.requestKey) {
+        ledgerKeys.add(ledger.requestKey);
+      }
+    }
+
+    for (const entry of auditByKey.values()) {
+      const modeKey = entry.executionMode ?? UNCLASSIFIED;
+      const taskKey = entry.taskType ?? UNCLASSIFIED;
+      const modeBucket = result.byMode[modeKey] ??= emptyBucket();
+      const taskBucket = result.byTaskType[taskKey] ??= emptyBucket();
+      modeBucket.routes += 1;
+      taskBucket.routes += 1;
+      const ledger = ledgers.find((candidate) => candidate.requestKey === entry.requestKey);
+      if (!ledger) continue;
+      result.joined += 1;
+      bump(modeBucket, ledger, entry);
+      bump(taskBucket, ledger, entry);
+    }
+
+    result.unmatchedAudit = auditByKey.size - result.joined;
+    const matchedLedgerKeys = new Set(
+      ledgers
+        .filter((ledger) => auditByKey.has(ledger?.requestKey))
+        .map((ledger) => ledger.requestKey),
+    );
+    result.unmatchedLedger = ledgerKeys.size - matchedLedgerKeys.size;
+    result.joinCoverage = result.joined / Math.max(1, auditByKey.size);
+    return result;
+  } catch (error) {
+    return zeroedResult({ error: error?.message ?? String(error) });
+  }
+}

package/src/diagnostics/skillAccuracy.js

@@ -0,0 +1,158 @@
+// skillAccuracy.js — per-skill trigger accuracy collector (SPEC C32 §5a).
+//
+// Joins route-audit entries carrying `skillIds` (FR-202) to exec-ledger
+// ledgers via `requestKey` (same join discipline as routeOutcomes.js) and
+// aggregates per-skill counters:
+//   triggers  = audit rows listing the skill
+//   joined    = those matched to a ledger
+//   accuracy  = joined === 0 ? null : writeOk / joined
+//   verifyOk/verifyFail/rescue reported separately for nuance.
+// Skills with triggers >= 2 && accuracy !== null && accuracy < 0.5 are also
+// copied into `lowAccuracy` for quick scanning.
+//
+// Contracts: NEVER THROWS — missing/malformed telemetry → zeroed result with
+// `error` field. Only side effect is the advisory artifact
+// `.ukit/storage/learning/skill-accuracy.json` (tmp+rename, non-fatal).
+// Gated by config `learning?.feedback?.enabled !== false` (default true).
+
+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 ARTIFACT_REL = path.join('.ukit', 'storage', 'learning', 'skill-accuracy.json');
+const CONFIG_REL = path.join('.ukit', 'storage', 'config.json');
+const MAX_SKILL_IDS = 8;
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function zeroedResult(extra = {}) {
+  return {
+    generatedAt: new Date().toISOString(),
+    auditRowsScanned: 0,
+    ledgersScanned: 0,
+    joined: 0,
+    skills: {},
+    lowAccuracy: [],
+    ...extra,
+  };
+}
+
+function emptySkillBucket() {
+  return {
+    triggers: 0,
+    joined: 0,
+    writeOk: 0,
+    writeFail: 0,
+    verifyOk: 0,
+    verifyFail: 0,
+    rescue: 0,
+    accuracy: null,
+  };
+}
+
+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;
+}
+
+function skillIdsOf(entry) {
+  if (!Array.isArray(entry?.skillIds)) return [];
+  return entry.skillIds
+    .filter((id) => typeof id === 'string' && id)
+    .slice(0, MAX_SKILL_IDS);
+}
+
+async function writeArtifact(filePath, result) {
+  const dir = path.dirname(filePath);
+  const tmp = path.join(dir, `.skill-accuracy-${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 per-skill trigger accuracy by joining route-audit `skillIds` to
+ * exec-ledger ledgers on `requestKey`.
+ *
+ * @param {string} projectRoot repository root containing `.ukit/storage/`.
+ * @param {{ limitLedgers?: number }} [options]
+ * @returns {Promise<object>} never throws.
+ */
+export async function collectSkillAccuracy(projectRoot, { limitLedgers = 500 } = {}) {
+  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 ledgerByKey = new Map();
+    for (const name of ledgerNames) {
+      const ledger = await readJson(path.join(ledgerDir, name));
+      if (!isObject(ledger)) continue;
+      result.ledgersScanned += 1;
+      if (typeof ledger.requestKey === 'string' && ledger.requestKey) {
+        ledgerByKey.set(ledger.requestKey, ledger);
+      }
+    }
+
+    for (const entry of auditEntries) {
+      const ids = skillIdsOf(entry);
+      if (ids.length === 0) continue;
+      const ledger = typeof entry.requestKey === 'string'
+        ? ledgerByKey.get(entry.requestKey)
+        : undefined;
+      for (const id of ids) {
+        const bucket = result.skills[id] ??= emptySkillBucket();
+        bucket.triggers += 1;
+        if (!ledger) continue;
+        bucket.joined += 1;
+        if (ledger.writeSucceeded === true) bucket.writeOk += 1;
+        else if (ledger.writeAttempted === true || ledger.writeSucceeded === false) {
+          bucket.writeFail += 1;
+        }
+        if (ledger.verificationSucceeded === true) bucket.verifyOk += 1;
+        if (ledger.verificationFailed === true) bucket.verifyFail += 1;
+        if (entry.rescueMode != null) bucket.rescue += 1;
+      }
+      if (ledger) result.joined += 1;
+    }
+
+    for (const [id, bucket] of Object.entries(result.skills)) {
+      bucket.accuracy = bucket.joined === 0 ? null : bucket.writeOk / bucket.joined;
+      if (bucket.triggers >= 2 && bucket.accuracy !== null && bucket.accuracy < 0.5) {
+        result.lowAccuracy.push({ id, accuracy: bucket.accuracy });
+      }
+    }
+    result.lowAccuracy.sort((a, b) => a.accuracy - b.accuracy);
+  } catch (error) {
+    result.error = error?.message ?? String(error);
+  }
+
+  await writeArtifact(path.join(projectRoot, ARTIFACT_REL), result);
+  return result;
+}

package/src/learning/patternProposals.js

@@ -0,0 +1,151 @@
+// patternProposals.js — promotion lane step 1 (FR-204 / TASK-230).
+//
+// Turns mined failure patterns (`.ukit/storage/cache/failure-patterns.json`,
+// C31 artifact) into pending pattern-candidate records for human
+// `ukit memory approve`. Dry-run by default; `dryRun: false` writes via
+// `proposePatternCandidate` from `src/core/memory/store.js`.
+//
+// Contracts:
+//   * NEVER THROWS — missing artifact, unreadable ledgers, store failures →
+//     partial result with `error` field, no exception escapes.
+//   * Nothing auto-promotes: candidates stay `pending`.
+//   * Eligible: count >= minCount AND sessions >= 2.
+//   * Dedupe: normalized-text OR meta.signature match against existing pending
+//     candidates and active v2 records → status 'duplicate', no write.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  listPendingPatternCandidates,
+  proposePatternCandidate,
+} from '../core/memory/store.js';
+
+const ARTIFACT_REL = path.join('.ukit', 'storage', 'cache', 'failure-patterns.json');
+const MIN_SESSIONS = 2;
+
+function normalizeText(text) {
+  return String(text ?? '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function candidateText(pattern) {
+  const firstFile = Array.isArray(pattern.files) && pattern.files.length > 0
+    ? pattern.files[0]
+    : 'the affected files';
+  return `Verification pattern "${pattern.signature}" failed ${pattern.count}× across ${pattern.sessions} sessions — check ${firstFile} before retrying.`;
+}
+
+async function loadPatterns(projectRoot) {
+  try {
+    const raw = await fs.readFile(path.join(projectRoot, ARTIFACT_REL), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && Array.isArray(parsed.patterns)) return parsed.patterns;
+  } catch {
+    // Artifact absent/corrupt → lazy re-mine below.
+  }
+  try {
+    const mod = await import('../diagnostics/failurePatterns.js');
+    if (typeof mod?.mineFailurePatterns !== 'function') return [];
+    const mined = await mod.mineFailurePatterns(projectRoot, { minCount: 1 });
+    return Array.isArray(mined?.patterns) ? mined.patterns : [];
+  } catch {
+    return [];
+  }
+}
+
+async function knownSignaturesAndTexts(projectRoot, projectId) {
+  const signatures = new Set();
+  const texts = new Set();
+  try {
+    const pending = await listPendingPatternCandidates(projectRoot, projectId);
+    for (const entry of pending) {
+      texts.add(normalizeText(entry.text));
+    }
+  } catch {
+    // listing failed → degrade, store dedupe is last line of defense
+  }
+  try {
+    const { queryRecords } = await import('../core/memory/storeV2.js');
+    const records = await queryRecords(projectRoot, { projectId });
+    for (const record of records) {
+      if (typeof record?.meta?.signature === 'string') {
+        signatures.add(record.meta.signature);
+      }
+      if (record?.status === 'active' || record?.meta?.legacyStatus === 'pending') {
+        texts.add(normalizeText(record.text));
+      }
+    }
+  } catch {
+    // v2 store unavailable → degrade
+  }
+  return { signatures, texts };
+}
+
+/**
+ * Propose pending pattern-candidates from mined failure patterns.
+ *
+ * @param {string} projectRoot
+ * @param {string} projectId
+ * @param {{ minCount?: number, dryRun?: boolean }} [options]
+ * @returns {Promise<{generatedAt: string, patternsScanned: number, eligible: number,
+ *   proposed: Array<{signature: string, text: string,
+ *     status: 'proposed'|'duplicate'|'skipped'}>, dryRun: boolean, error?: string}>}
+ */
+export async function proposeFromPatterns(projectRoot, projectId, { minCount = 3, dryRun = true } = {}) {
+  const result = {
+    generatedAt: new Date().toISOString(),
+    patternsScanned: 0,
+    eligible: 0,
+    proposed: [],
+    dryRun,
+  };
+
+  try {
+    const patterns = await loadPatterns(projectRoot);
+    result.patternsScanned = patterns.length;
+    const known = await knownSignaturesAndTexts(projectRoot, projectId);
+
+    for (const pattern of patterns) {
+      const signature = typeof pattern?.signature === 'string' ? pattern.signature : null;
+      const count = Number(pattern?.count) || 0;
+      const sessions = Number(pattern?.sessions) || 0;
+      if (!signature) continue;
+
+      const text = candidateText({ signature, count, sessions, files: pattern.files });
+      const eligible = count >= minCount && sessions >= MIN_SESSIONS;
+      if (!eligible) {
+        result.proposed.push({ signature, text, status: 'skipped' });
+        continue;
+      }
+      result.eligible += 1;
+
+      if (known.signatures.has(signature) || known.texts.has(normalizeText(text))) {
+        result.proposed.push({ signature, text, status: 'duplicate' });
+        continue;
+      }
+
+      if (dryRun) {
+        result.proposed.push({ signature, text, status: 'proposed' });
+        continue;
+      }
+
+      try {
+        await proposePatternCandidate(projectRoot, projectId, {
+          text,
+          category: 'failure-pattern',
+          signature,
+          detectedFrom: 'memory-learn',
+        });
+        known.signatures.add(signature);
+        known.texts.add(normalizeText(text));
+        result.proposed.push({ signature, text, status: 'proposed' });
+      } catch (err) {
+        result.proposed.push({ signature, text, status: 'skipped' });
+        result.error = err?.message ?? String(err);
+      }
+    }
+  } catch (err) {
+    result.error = err?.message ?? String(err);
+  }
+
+  return result;
+}