@ngockhoale/ukit 3.0.7 → 3.0.9

package/scripts/measure-decision-gateway.mjs

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+// TASK-004 — G3-FR06 decision-gateway cost/latency measurement probe.
+//
+// Probes the configured unic-decision gateway through the real client path
+// (createDecisionClient + resolveGatewayBaseUrl/ApiKey env indirection —
+// NO new credentials) and writes evidence to
+//   docs/AI_HANDOFF/inventory/g3-gateway-measurement.{json,md}
+//
+// Rules (PLAN §5 / TASK-004):
+//   - cost is provider-reported usage when present, else literal 'unknown';
+//     chars/4 estimates are forbidden.
+//   - unreachable gateway → availability:'unavailable' + errorClass + zero
+//     samples — a recorded outcome, NOT a probe failure.
+//   - partial samples → samples:<n> + partial:true; never padded.
+//
+// Usage: node scripts/measure-decision-gateway.mjs [--samples N] [--out dir]
+// Exit codes: 0 = artifact written (any availability), 2 = artifact write failed.
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { fileURLToPath } from 'node:url';
+
+import { createDecisionClient } from '../src/decision/client.js';
+import {
+  resolveGatewayApiKey,
+  resolveGatewayBaseUrl,
+} from '../src/core/gatewayProbe.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const DEFAULT_SAMPLES = 20;
+const DEFAULT_OUT_DIR = path.join(REPO_ROOT, 'docs/AI_HANDOFF/inventory');
+const PROBE_BATCH_ID = 'g3-gateway-measurement';
+const PROBE_QUESTIONS = [
+  {
+    decisionKey: 'probe.intent',
+    kind: 'choice',
+    instruction: 'Pick the intent kind.',
+    candidates: ['fix', 'feature', 'docs'],
+  },
+];
+
+// ---------- pure helpers (unit-tested) ----------
+
+/**
+ * Nearest-rank percentile over a numeric sample array.
+ * @param {number[]} samples latencies in ms (need not be sorted)
+ * @param {number} p percentile in (0, 100]
+ * @returns {number|null} null for empty input — never fabricated
+ */
+export function percentile(samples, p) {
+  const clean = (samples ?? []).filter((v) => Number.isFinite(v)).sort((a, b) => a - b);
+  if (clean.length === 0) return null;
+  const rank = Math.ceil((p / 100) * clean.length);
+  return clean[Math.min(Math.max(rank, 1), clean.length) - 1];
+}
+
+/**
+ * Extract provider-reported cost/usage from a raw chat-completions JSON body.
+ * Returns the provider's `usage` object verbatim when present, else 'unknown'.
+ * Never estimates.
+ */
+export function extractCost(parsedBody) {
+  const usage = parsedBody?.usage;
+  if (usage && typeof usage === 'object' && Object.keys(usage).length > 0) {
+    return usage;
+  }
+  return 'unknown';
+}
+
+/**
+ * Build the machine-readable measurement artifact.
+ * @param {{availability:'ok'|'unavailable', samples:number[], failures:number,
+ *          attempted:number, checkpoint:string|null, cost:object|'unknown',
+ *          errorClass?:string|null, endpointSource?:string|null}} probe
+ */
+export function buildMeasurementArtifact(probe, { gitSha, measuredAt } = {}) {
+  const latencies = probe?.samples ?? [];
+  const artifact = {
+    schema: 'g3-gateway-measurement/1',
+    availability: probe?.availability === 'ok' ? 'ok' : 'unavailable',
+    samples: latencies.length,
+    attempted: probe?.attempted ?? latencies.length,
+    failures: probe?.failures ?? 0,
+    p50Ms: percentile(latencies, 50),
+    p95Ms: percentile(latencies, 95),
+    minMs: latencies.length ? Math.min(...latencies) : null,
+    maxMs: latencies.length ? Math.max(...latencies) : null,
+    checkpoint: probe?.checkpoint ?? null,
+    cost: probe?.cost ?? 'unknown',
+    measuredAt: measuredAt ?? new Date().toISOString(),
+    gitSha: gitSha ?? null,
+  };
+  if (probe?.errorClass) artifact.errorClass = probe.errorClass;
+  if (probe?.endpointSource) artifact.endpointSource = probe.endpointSource;
+  // Honest sample count: anything below the attempted size is partial, never padded.
+  if (artifact.attempted > 0 && artifact.samples < artifact.attempted) {
+    artifact.partial = true;
+  }
+  return artifact;
+}
+
+/** Render the markdown evidence summary from an artifact object. */
+export function renderMeasurementMarkdown(artifact) {
+  const lines = [
+    '# G3 Gateway Measurement — unic-decision',
+    '',
+    `- Measured at: ${artifact.measuredAt}`,
+    `- Git SHA: ${artifact.gitSha ?? 'unknown'}`,
+    `- Availability: **${artifact.availability}**`,
+    `- Checkpoint: ${artifact.checkpoint ?? 'unresolved'}`,
+    `- Endpoint source: ${artifact.endpointSource ?? 'none'}`,
+    `- Samples: ${artifact.samples} ok / ${artifact.attempted} attempted` +
+      (artifact.partial ? ' (**partial**)' : ''),
+    `- p50 latency: ${artifact.p50Ms ?? 'n/a'} ms`,
+    `- p95 latency: ${artifact.p95Ms ?? 'n/a'} ms`,
+    `- min/max: ${artifact.minMs ?? 'n/a'} / ${artifact.maxMs ?? 'n/a'} ms`,
+    `- Cost (provider-reported): ${artifact.cost === 'unknown' ? 'unknown' : JSON.stringify(artifact.cost)}`,
+  ];
+  if (artifact.errorClass) lines.push(`- Error class: ${artifact.errorClass}`);
+  const interpretation =
+    artifact.availability === 'ok'
+      ? `Gateway reachable; ${artifact.samples} successful decision-batch ` +
+        `probes measured over the real client path (createDecisionClient → ` +
+        `resolveGatewayBaseUrl/ApiKey). Owner classification: local Lava/JEV ` +
+        `deployment, near-zero marginal cost [owner-cited context, not measured].`
+      : artifact.errorClass === 'endpoint-rejected'
+        ? 'Endpoint resolved and answered HTTP, but every decision-batch probe ' +
+          'was rejected (400/404/422 → `endpoint-rejected`) — the gateway is ' +
+          'reachable yet does not accept the C13 tools-encoded batch on this ' +
+          'checkpoint. No latency could be sampled; fallback path absorbs this.'
+        : 'Gateway was NOT reachable (or no endpoint configured) during this ' +
+          'probe. This is a recorded outcome — the scheduler fallback path ' +
+          'absorbs it; re-run the probe when the gateway is expected to be up.';
+  lines.push(
+    '',
+    '## Interpretation',
+    '',
+    interpretation,
+    '',
+    '## Explicit unknowns',
+    '',
+    artifact.cost === 'unknown'
+      ? '- `cost`: the provider response carried no `usage` block → recorded `unknown` (estimates forbidden).'
+      : '- `cost`: recorded verbatim from the provider `usage` block.',
+    artifact.checkpoint === null
+      ? '- `checkpoint`: unresolved (no successful request).'
+      : null,
+    '',
+  );
+  return lines.filter((l) => l !== null).join('\n');
+}
+
+export function writeMeasurementArtifacts(artifact, outDir) {
+  fs.mkdirSync(outDir, { recursive: true });
+  const jsonPath = path.join(outDir, 'g3-gateway-measurement.json');
+  const mdPath = path.join(outDir, 'g3-gateway-measurement.md');
+  fs.writeFileSync(jsonPath, `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+  fs.writeFileSync(mdPath, renderMeasurementMarkdown(artifact), 'utf8');
+  return { jsonPath, mdPath };
+}
+
+// ---------- live probe ----------
+
+function gitSha() {
+  try {
+    return execSync('git rev-parse HEAD', { cwd: REPO_ROOT, encoding: 'utf8' }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function parseArgs(argv) {
+  const opts = { samples: DEFAULT_SAMPLES, outDir: DEFAULT_OUT_DIR };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--samples') {
+      i += 1;
+      opts.samples = Number(argv[i]);
+    } else if (argv[i] === '--out') {
+      i += 1;
+      opts.outDir = path.resolve(argv[i]);
+    } else if (argv[i] === '--help' || argv[i] === '-h') {
+      return { help: true };
+    } else {
+      throw new Error(`Unknown argument: ${argv[i]}`);
+    }
+  }
+  return opts;
+}
+
+/** Wrap fetch to capture the last successful response's provider `usage`. */
+function captureCostTransport(baseTransport, sink) {
+  return async (url, init) => {
+    const res = await baseTransport(url, init);
+    if (res?.ok !== false && typeof res?.clone === 'function') {
+      try {
+        const body = await res.clone().json();
+        const cost = extractCost(body);
+        if (cost !== 'unknown') sink.cost = cost;
+      } catch {
+        // clone/parse failure must never break the probe
+      }
+    }
+    return res;
+  };
+}
+
+async function runProbe({ samples }) {
+  const projectRoot = REPO_ROOT;
+  const env = process.env;
+  const base = await resolveGatewayBaseUrl({ projectRoot, env });
+  const key = await resolveGatewayApiKey({ projectRoot, env });
+  const endpointSource = base?.source ?? null;
+
+  if (!base?.baseUrl) {
+    return {
+      availability: 'unavailable',
+      errorClass: 'endpoint-unconfigured',
+      endpointSource: null,
+      samples: [],
+      failures: 0,
+      attempted: 0,
+      checkpoint: null,
+      cost: 'unknown',
+    };
+  }
+
+  const sink = { cost: 'unknown' };
+  const client = createDecisionClient({
+    config: {},
+    transport: captureCostTransport(globalThis.fetch.bind(globalThis), sink),
+    projectRoot,
+    env,
+  });
+
+  const health = await client.healthProbe();
+  const latencies = [];
+  let failures = 0;
+  let lastErrorClass = null;
+  let checkpoint = health?.checkpoint ?? null;
+
+  if (health.status === 'ok' || health.status === 'unavailable' || health.status === 'timeout') {
+    for (let i = 0; i < samples; i += 1) {
+      const started = performance.now();
+      const result = await client.requestBatch({
+        batchId: `${PROBE_BATCH_ID}-${i}`,
+        boundary: 'measurement',
+        statePacket: { stateVersion: 1, taskClass: 'measurement', probeIndex: i },
+        questions: PROBE_QUESTIONS,
+        deadlineMs: 10_000,
+      });
+      const elapsed = performance.now() - started;
+      if (result.status === 'ok' || result.status === 'accepted' || result.answers?.length > 0) {
+        latencies.push(Math.round(elapsed * 100) / 100);
+        checkpoint = checkpoint ?? result.checkpoint ?? null;
+      } else {
+        failures += 1;
+        lastErrorClass = result.fallbackCode ?? result.status;
+        checkpoint = checkpoint ?? result.checkpoint ?? null;
+      }
+    }
+  }
+
+  const available = latencies.length > 0;
+  return {
+    availability: available ? 'ok' : 'unavailable',
+    errorClass: available
+      ? null
+      : (lastErrorClass ?? (health.status === 'ok' ? null : health.status)),
+    endpointSource: base.source ?? (key?.source ? `key:${key.source}` : null),
+    samples: latencies,
+    failures,
+    attempted: samples,
+    checkpoint,
+    cost: sink.cost,
+    healthStatus: health.status,
+  };
+}
+
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (isMain) {
+  try {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+      console.log('Usage: node scripts/measure-decision-gateway.mjs [--samples N] [--out dir]');
+      process.exit(0);
+    }
+    if (!Number.isInteger(opts.samples) || opts.samples < 1) {
+      throw new Error('--samples must be a positive integer');
+    }
+    const probe = await runProbe(opts);
+    const artifact = buildMeasurementArtifact(probe, {
+      gitSha: gitSha(),
+      measuredAt: new Date().toISOString(),
+    });
+    const { jsonPath, mdPath } = writeMeasurementArtifacts(artifact, opts.outDir);
+    console.log(`availability=${artifact.availability} samples=${artifact.samples} p50=${artifact.p50Ms} p95=${artifact.p95Ms} cost=${artifact.cost === 'unknown' ? 'unknown' : 'provider'}`);
+    console.log(`wrote ${jsonPath}`);
+    console.log(`wrote ${mdPath}`);
+    process.exit(0);
+  } catch (err) {
+    console.error(`measure-decision-gateway: ${err?.message ?? err}`);
+    process.exit(2);
+  }
+}

package/scripts/perf/audit-perf.mjs

@@ -85,16 +85,26 @@ function parseArgs(argv) {
     sinceDays: 14,
     benchIterations: 10,
   };
+  // A value-taking flag as the last argv entry (or followed by another flag)
+  // would reach path.resolve(undefined) → TypeError; fail with usage instead
+  // (same convention as scripts/audit/decision-coverage.mjs).
+  const valueFor = (flag, i) => {
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) {
+      console.error(`[audit-perf] missing value for ${flag} — expected: node scripts/perf/audit-perf.mjs ${flag} <value>`);
+      process.exit(1);
+    }
+    return next;
+  };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
-    const next = argv[i + 1];
     switch (arg) {
-      case '--root': options.root = path.resolve(next); i += 1; break;
-      case '--telemetry-dir': options.telemetryDir = path.resolve(next); i += 1; break;
-      case '--settings': options.settings = path.resolve(next); i += 1; break;
-      case '--out': options.out = path.resolve(next); i += 1; break;
-      case '--since': options.sinceDays = Number.parseInt(next, 10); i += 1; break;
-      case '--bench-iterations': options.benchIterations = Number.parseInt(next, 10); i += 1; break;
+      case '--root': options.root = path.resolve(valueFor(arg, i)); i += 1; break;
+      case '--telemetry-dir': options.telemetryDir = path.resolve(valueFor(arg, i)); i += 1; break;
+      case '--settings': options.settings = path.resolve(valueFor(arg, i)); i += 1; break;
+      case '--out': options.out = path.resolve(valueFor(arg, i)); i += 1; break;
+      case '--since': options.sinceDays = Number.parseInt(valueFor(arg, i), 10); i += 1; break;
+      case '--bench-iterations': options.benchIterations = Number.parseInt(valueFor(arg, i), 10); i += 1; break;
       default: break;
     }
   }
@@ -393,11 +403,16 @@ function loadSettings(root, override) {
       path.join(root, '.claude', 'settings.json'),
     ];
   for (const candidate of candidates) {
-    if (fs.existsSync(candidate)) {
-      return { file: candidate, settings: JSON.parse(fs.readFileSync(candidate, 'utf8')) };
+    if (!fs.existsSync(candidate)) continue;
+    try {
+      return { file: candidate, settings: JSON.parse(fs.readFileSync(candidate, 'utf8')), error: null };
+    } catch (error) {
+      // Corrupt settings.json (e.g. unresolved merge markers) must not crash
+      // the audit — report the failure and continue with no hook groups.
+      return { file: candidate, settings: null, error: `settings.json parse failed: ${error.message}` };
     }
   }
-  return { file: null, settings: null };
+  return { file: null, settings: null, error: null };
 }
 
 function describeGroups(settings) {
@@ -935,7 +950,7 @@ function renderMeasureDoc(context) {
   const {
     generatedAt, root, telemetry, telemetryDetail, perHook, records, events,
     multiplicity, nested, groups, floor, telemetryFinish, hookBench, routerBench,
-    additions, findings, settingsFile, iterations, hooksResolvedFrom,
+    additions, findings, settingsFile, settingsError, iterations, hooksResolvedFrom,
     telemetryRows, telemetryFiles, appendBench, split,
   } = context;
   const lines = [];
@@ -958,7 +973,7 @@ function renderMeasureDoc(context) {
   lines.push('node --test tests/handoff/c33/perfFindings.test.js');
   lines.push('');
   lines.push(`- root: \`${root}\``);
-  lines.push(`- settings.json: \`${settingsFile || 'NOT FOUND'}\``);
+  lines.push(`- settings.json: \`${settingsFile || 'NOT FOUND'}\`${settingsError ? ` — **PARSE FAILED** (${settingsError}); hook-group findings degrade to 'settings.json not readable'` : ''}`);
   lines.push(`- hooks resolved from: \`${hooksResolvedFrom || 'NOT FOUND'}\``);
   lines.push(`- telemetry: ${telemetry.available ? `\`${telemetry.dir}\` — ${telemetry.rows.length} rows in ${telemetry.files} files${telemetry.malformed ? ` (${telemetry.malformed} malformed lines skipped)` : ''}` : 'NOT PRESENT — every telemetry-sourced finding is `evidence: "unavailable"`'}`);
   lines.push(`- snapshot provenance: generatedAt \`${generatedAt}\`, telemetryRows: ${telemetryRows}, telemetryFiles: ${telemetryFiles} — hooks append continuously, so a report is a point-in-time view, not a stable dataset`);
@@ -1100,7 +1115,7 @@ async function main() {
   const measureFile = path.join(path.dirname(outFile), 'perf-measure.md');
 
   const telemetry = loadTelemetry(telemetryDir);
-  const { file: settingsFile, settings } = loadSettings(root, options.settings);
+  const { file: settingsFile, settings, error: settingsError } = loadSettings(root, options.settings);
   const groups = describeGroups(settings);
 
   const perHook = perHookStats(telemetry.rows);
@@ -1137,7 +1152,7 @@ async function main() {
   const context = {
     telemetry, telemetryDetail, groups, floor, telemetryFinish, hookBench, routerBench,
     root,
-    perHook, records, events, multiplicity, nested, additions, settingsFile, split,
+    perHook, records, events, multiplicity, nested, additions, settingsFile, settingsError, split,
     iterations: options.benchIterations,
     sinceDays: options.sinceDays,
     telemetryRows, telemetryFiles, appendBench,
@@ -1154,7 +1169,7 @@ async function main() {
       telemetry: telemetry.available
         ? { dir: telemetryDir, rows: telemetryRows, files: telemetryFiles }
         : { dir: telemetryDir, available: false },
-      settings: settingsFile,
+      settings: settingsFile ? { file: settingsFile, error: settingsError } : null,
       hooksDir: hooksResolvedFrom,
       benchmarkIterations: options.benchIterations,
       gitLogWindowDays: options.sinceDays,
@@ -1169,9 +1184,12 @@ async function main() {
   process.stdout.write(
     `${findings.length} findings → ${path.relative(root, outFile)}`
     + ` (generatedAt ${generatedAt}, telemetry ${telemetry.available ? `${telemetryRows} rows / ${telemetryFiles} files` : 'absent'},`
-    + ` settings ${settingsFile ? 'found' : 'missing'},`
+    + ` settings ${settingsError ? 'unparseable' : settingsFile ? 'found' : 'missing'},`
     + ` ${groups.length} groups, ${hookBench.size} hooks benchmarked)\n`,
   );
 }
 
-await main();
+main().catch((error) => {
+  console.error(`[audit-perf] ${error && error.message ? error.message : error}`);
+  process.exit(1);
+});

package/src/bug/triageBug.js

@@ -49,9 +49,10 @@ export async function triageBug({ rootDir = process.cwd(), signature } = {}) {
 
   const recommendedTest = await buildTestCommand(rootDir, recommendedTestFile);
 
-  const analogFiles = topResult
-    ? (relatedArtifacts?.analogsMap.get(topResult.filePath) ?? []).slice(0, 2)
-    : [];
+  const topAnalogs = topResult ? relatedArtifacts?.analogsMap.get(topResult.filePath) : null;
+  const analogFiles = (Array.isArray(topAnalogs) ? topAnalogs : [])
+    .filter((analog) => analog && typeof analog.filePath === 'string')
+    .slice(0, 2);
 
   return {
     signature,