@ngockhoale/ukit 2.7.6 → 2.7.8

package/scripts/perf/audit-perf.mjs

@@ -17,7 +17,9 @@
  *      count per (event, matcher) pair.
  *   3. micro-benchmark — live spawn measurements: the `bash` and `node` boot
  *      floor, the advisory telemetry child, each settings row's script, and the
- *      index/router helpers invoked per prompt.
+ *      index/router helpers invoked per prompt — plus an in-process measurement
+ *      of `appendTelemetryRow` itself, so the observability layer's own I/O is
+ *      measured rather than assumed (O5).
  *   4. git-log — hot-path files added in the regression window (SPEC §2.3).
  *
  * Honesty contract: a number is emitted only when it was measured. An area with
@@ -33,9 +35,10 @@
  */
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { execFileSync, spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_ROOT = path.resolve(SCRIPT_DIR, '..', '..');
@@ -56,6 +59,8 @@ const PROCESSES_PER_HOOK_ROW = 3;
 
 const HOOKS_SUBPATH = ['templates', '.claude', 'hooks'];
 const CHAIN_RUNNER_LABEL = 'hook-chain-runner';
+// The ONE append API every hook writes through — the subject of the O5 benchmark.
+const TELEMETRY_MODULE_SUBPATH = ['templates', '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs'];
 
 // Index/router helpers a prompt or an edit pays a cold start for (SPEC §2.5).
 const ROUTER_HELPERS = [
@@ -316,6 +321,62 @@ function nestedScriptStats(rows) {
   return out;
 }
 
+/**
+ * O3 (SPEC §FR-009): the exec-vs-stage split. A hook's wall time is two
+ * different things added together — time it spent waiting for the producer to
+ * finish writing stdin, and time it spent working — and only the second is the
+ * hook's cost. Rows carry the stage half as `stdinStageMs` (chain rows) or
+ * `stageMs` (direct rows); the exec half is derived from the row's own
+ * `elapsedMs`, and both halves come from ONE row so they always sum to it.
+ *
+ * Null-safe by construction: a row carrying neither field is skipped entirely
+ * rather than counted as a zero stage, and a bucket with no usable numbers
+ * summarises to nulls (`summarise` filters non-finite values), so a tree whose
+ * dataset predates the fields renders as "not measured", never as 0ms.
+ */
+function stageSplit(rows) {
+  const buckets = new Map();
+  const allStage = [];
+  const allExec = [];
+  for (const row of rows) {
+    const chainStage = row.stdinStageMs;
+    const directStage = row.stageMs;
+    const hasChain = typeof chainStage === 'number' && Number.isFinite(chainStage);
+    const hasDirect = typeof directStage === 'number' && Number.isFinite(directStage);
+    if (!hasChain && !hasDirect) continue;
+    const stage = hasChain ? chainStage : directStage;
+    const key = row.hook || '(unattributed)';
+    if (!buckets.has(key)) {
+      buckets.set(key, { field: hasChain ? 'stdinStageMs' : 'stageMs', stage: [], exec: [] });
+    }
+    const bucket = buckets.get(key);
+    bucket.stage.push(stage);
+    allStage.push(stage);
+    if (typeof row.elapsedMs === 'number' && Number.isFinite(row.elapsedMs)) {
+      const exec = Math.max(0, row.elapsedMs - stage);
+      bucket.exec.push(exec);
+      allExec.push(exec);
+    }
+  }
+  const hooks = new Map();
+  for (const [hook, bucket] of buckets) {
+    hooks.set(hook, {
+      field: bucket.field,
+      stage: summarise(bucket.stage),
+      exec: summarise(bucket.exec),
+      // The rows belong to `hooks`, but `measured` counts the whole dataset so a
+      // reader can tell a fully-split snapshot from a partially-migrated one.
+      measured: bucket.stage.length,
+    });
+  }
+  return {
+    hooks,
+    measured: allStage.length,
+    stage: summarise(allStage),
+    exec: summarise(allExec),
+  };
+}
+
 // --- source 2: settings.json structure -------------------------------------
 
 function loadSettings(root, override) {
@@ -365,23 +426,83 @@ function benchSpawn(file, args, iterations, env) {
   return summarise(samples);
 }
 
+/**
+ * Every benchmark that exercises the telemetry writer is pointed at a throwaway
+ * project root: the audit must never add rows to the dataset it is measuring,
+ * or two snapshots of the same tree would differ by the act of auditing them
+ * (O2/O5).
+ */
+function scratchRoot(label) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `ukit-perf-${label}-`));
+}
+
 function benchmarkFloor(root, iterations) {
   const env = { ...process.env, CLAUDE_PROJECT_DIR: root };
   const telemetryTwin = path.join(root, 'templates', '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs');
-  return {
-    floor: {
-      bash: benchSpawn('bash', ['-c', 'true'], iterations, env),
-      node: benchSpawn('node', ['-e', '0'], iterations, env),
-    },
-    telemetryFinish: fs.existsSync(telemetryTwin)
-      ? benchSpawn('node', [telemetryTwin, '--finish'], iterations, {
-        ...env,
-        UKIT_TEL_HOOK: 'audit-bench.sh',
-        UKIT_TEL_RC: '0',
-        PROJECT_ROOT: root,
-      })
-      : null,
-  };
+  const scratch = scratchRoot('floor');
+  try {
+    return {
+      floor: {
+        bash: benchSpawn('bash', ['-c', 'true'], iterations, env),
+        node: benchSpawn('node', ['-e', '0'], iterations, env),
+      },
+      telemetryFinish: fs.existsSync(telemetryTwin)
+        ? benchSpawn('node', [telemetryTwin, '--finish'], iterations, {
+          ...env,
+          UKIT_TEL_HOOK: 'audit-bench.sh',
+          UKIT_TEL_RC: '0',
+          PROJECT_ROOT: scratch,
+          CLAUDE_PROJECT_DIR: scratch,
+        })
+        : null,
+    };
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/** The telemetry writer a tree ships, preferring the template (like hooksDir). */
+function telemetryModulePath(root) {
+  const candidates = [
+    path.join(root, 'templates', '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs'),
+    path.join(root, '.claude', 'ukit', 'runtime', 'hook-telemetry.mjs'),
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate)) || null;
+}
+
+/**
+ * O5: cost of one telemetry row as the writer actually pays it — the same
+ * `appendTelemetryRow` the hooks call, invoked in-process against a temp project
+ * root. The function is async only because the ESM writer must be imported
+ * dynamically; the measured region is synchronous I/O, not module loading.
+ */
+async function benchmarkAppend(root, iterations) {
+  const module = telemetryModulePath(root);
+  if (!module) return { stats: null, iterations, module: null, reason: 'telemetry writer not resolvable from this root' };
+  let dir = null;
+  try {
+    dir = scratchRoot('append');
+    const { appendTelemetryRow } = await import(pathToFileURL(module).href);
+    const row = {
+      v: 1,
+      ts: Date.now(),
+      hookEvent: 'PreToolUse',
+      hook: 'audit-append-bench.sh',
+      elapsedMs: 1,
+      outcome: 'ok',
+    };
+    const samples = [];
+    for (let i = 0; i < iterations; i += 1) {
+      const start = process.hrtime.bigint();
+      appendTelemetryRow(dir, 'audit-append-bench', row);
+      samples.push(Number(process.hrtime.bigint() - start) / 1e6);
+    }
+    return { stats: summarise(samples), iterations, module, reason: null };
+  } catch (error) {
+    return { stats: null, iterations, module, reason: `append measurement failed: ${error.message}` };
+  } finally {
+    if (dir) fs.rmSync(dir, { recursive: true, force: true });
+  }
 }
 
 /** Resolves the directory holding the shipped hooks, preferring the template. */
@@ -479,11 +600,11 @@ function finding(entry) {
 function slug(value) {
   return String(value).replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '').toLowerCase();
 }
-
 function buildFindings(context) {
   const {
     telemetry, telemetryDetail, groups, floor, telemetryFinish, hookBench,
     routerBench, perHook, records, events, multiplicity, nested, additions, spawns,
+    appendBench, root, split, telemetryRows,
   } = context;
 
   const findings = [];
@@ -691,7 +812,96 @@ function buildFindings(context) {
     status: 'not-a-bug',
   }));
 
-  // 9. Registered hooks with no rows at all — evidenced absence, not a guess.
+  // 9. The observability layer's own cost (O5) — measured in-process, against a
+  // throwaway project root, so auditing a tree never writes into the dataset
+  // whose rows the audit is counting. Below the hotspot bar this is a documented
+  // non-issue; above it the append joins the same per-call cost reducible by
+  // TASK-234's consolidation.
+  const appendStats = appendBench.stats;
+  if (appendStats && appendStats.p50 !== null) {
+    const hotspot = appendStats.p50 > HOTSPOT_P50_MS;
+    findings.push(finding({
+      id: 'telemetry-append-overhead',
+      area: 'telemetry append overhead — appendTelemetryRow, in-process against a throwaway project root',
+      evidence: 'micro-benchmark',
+      evidenceDetail: `appendTelemetryRow over ${appendBench.iterations} iterations against a temp project root (the audited telemetry dir is never written): p50 ${appendStats.p50.toFixed(3)}ms, p95 ${appendStats.p95.toFixed(3)}ms, max ${appendStats.max.toFixed(3)}ms, total ${appendStats.total.toFixed(3)}ms; writer ${appendBench.module ? path.relative(root, appendBench.module) : 'n/a'}`,
+      p50ms: appendStats.p50,
+      p95ms: appendStats.p95,
+      totalMs: appendStats.total,
+      invocations: appendBench.iterations,
+      rootCause: hotspot
+        ? `one synchronous append costs p50 ${appendStats.p50.toFixed(3)}ms — above the ${HOTSPOT_P50_MS}ms hotspot bar — so the observability layer is paying a measurable per-hook term on the hot path`
+        : `one synchronous append costs p50 ${appendStats.p50.toFixed(3)}ms (under the ${HOTSPOT_P50_MS}ms hotspot bar): the observability layer's own I/O is bounded by a single append plus an amortized 1-in-16 sampled sweep, so it is not the hook chain's dominant term`,
+      fixTask: hotspot ? 'TASK-234' : null,
+      status: hotspot ? 'confirmed' : 'not-a-bug',
+    }));
+  } else {
+    findings.push(finding({
+      id: 'telemetry-append-overhead',
+      area: 'telemetry append overhead — appendTelemetryRow, in-process against a throwaway project root',
+      evidence: 'unavailable',
+      evidenceDetail: `${telemetryDetail}; the append benchmark needs the telemetry writer (${TELEMETRY_MODULE_SUBPATH.join('/')}) resolvable from this root — ${appendBench.reason || 'not resolvable'}, so the observability layer's own cost stays unset rather than estimated`,
+      p50ms: null,
+      p95ms: null,
+      totalMs: null,
+      invocations: 0,
+      rootCause: 'the observability layer cannot be measured on a tree that ships no telemetry writer; the absence is reported instead of a plausible-looking number',
+      fixTask: null,
+      status: 'deferred',
+    }));
+  }
+
+  // 10. O3: the exec-vs-stage split. The reported number here is the EXEC half
+  // — the hook's own cost — because the stage half is the producer's, and
+  // treating wait-on-stdin as a hook defect is exactly the misreading O3 names.
+  // Both halves are stated so the tail can be attributed rather than debated.
+  if (split.measured > 0) {
+    const stageText = split.stage.p50 === null
+      ? 'n/a'
+      : `${split.stage.p50}ms p50 / ${split.stage.p95}ms p95`;
+    const execText = split.exec.p50 === null
+      ? 'n/a'
+      : `${split.exec.p50}ms p50 / ${split.exec.p95}ms p95`;
+    const top = [...split.hooks.entries()]
+      .sort((a, b) => (b[1].stage.total || 0) - (a[1].stage.total || 0))
+      .slice(0, 5)
+      .map(([hook, entry]) => `${hook} (${entry.field}: stage ${entry.stage.p50}ms p50, exec ${entry.exec.p50}ms p50, n=${entry.measured})`)
+      .join(', ');
+    const execHotspot = split.exec.p50 !== null && split.exec.p50 > HOTSPOT_P50_MS;
+    findings.push(finding({
+      id: 'stdin-stage-vs-exec-split',
+      area: 'stdin stage vs execution split (O3 — the wall-time tail attributed)',
+      evidence: measuredEvidence,
+      evidenceDetail: `${telemetryDetail}; ${split.measured} of ${telemetryRows} rows carry the split (a row the producer's stdin held open carries the stage half; a row measured before this field existed carries neither and is excluded, not counted as 0ms). Across those rows, stage ${stageText} vs exec ${execText}; the exec half is the hook's own cost. Per hook: ${top}`,
+      p50ms: split.exec.p50,
+      p95ms: split.exec.p95,
+      totalMs: split.exec.total,
+      invocations: split.measured,
+      rootCause: execHotspot
+        ? `once the stdin stage is attributed to the producer, the remaining execution p50 of ${split.exec.p50}ms is still above the ${HOTSPOT_P50_MS}ms hotspot bar, so the tail is NOT fully explained by stdin staging and the hook's own work needs TASK-234's consolidation`
+        : `the tail artifact is a measurement artifact, not hook work: the wall time a hook reports is the stdin stage plus its execution, and only the execution half is the hook's cost. Attributing the stage half to the producer is what makes project-important.sh's reported p95 tail interpretable instead of looking like a slow script`,
+      fixTask: execHotspot ? 'TASK-234' : null,
+      status: execHotspot ? 'confirmed' : 'not-a-bug',
+    }));
+  } else {
+    // Rows predating the fields are the expected state on an unmigrated tree —
+    // reported as an evidenced absence, never as a 0ms stage.
+    findings.push(finding({
+      id: 'stdin-stage-vs-exec-split',
+      area: 'stdin stage vs execution split (O3 — the wall-time tail attributed)',
+      evidence: 'unavailable',
+      evidenceDetail: `${telemetryDetail}; no row carries \`stdinStageMs\` or \`stageMs\`, so the exec-vs-stage split is unmeasured on this tree. Old rows keep aggregating exactly as before — the fields are additive and optional, so their absence is reported rather than guessed at as 0ms.`,
+      p50ms: null,
+      p95ms: null,
+      totalMs: null,
+      invocations: 0,
+      rootCause: 'the split needs rows written after the fields shipped; a dataset predating them yields no numbers at all (null, not zero), which is the null-safe posture the audit reports here',
+      fixTask: null,
+      status: 'deferred',
+    }));
+  }
+
+  // 11. Registered hooks with no rows at all — evidenced absence, not a guess.
   const settingsScripts = [...new Set(groups.flatMap((group) => group.scripts.map((script) => script.script)))];
   for (const script of settingsScripts) {
     if (perHook.has(script)) continue;
@@ -720,6 +930,7 @@ function renderMeasureDoc(context) {
     generatedAt, root, telemetry, telemetryDetail, perHook, records, events,
     multiplicity, nested, groups, floor, telemetryFinish, hookBench, routerBench,
     additions, findings, settingsFile, iterations, hooksResolvedFrom,
+    telemetryRows, telemetryFiles, appendBench, split,
   } = context;
   const lines = [];
   lines.push('# perf-measure.md — raw measurement notes (TASK-233)');
@@ -728,7 +939,8 @@ function renderMeasureDoc(context) {
   lines.push('');
   lines.push('Appendix source for `docs/AI_REPORT/AI_REVIEW_BUGS_REPORT.md`. Every number in');
   lines.push('`perf-findings.json` comes from one of the four sources below. TASK-236 re-runs');
-  lines.push('the identical command for the before/after table (SPEC §5).');
+  lines.push('the identical command for the before/after table (SPEC §5). Two numbers from two');
+  lines.push('different snapshots are only comparable once their provenance line agrees.');
   lines.push('');
   lines.push('## 1. Reproduce');
   lines.push('');
@@ -736,13 +948,14 @@ function renderMeasureDoc(context) {
   lines.push('node scripts/perf/audit-perf.mjs \\');
   lines.push(`  --telemetry-dir "${telemetry.dir || path.join(root, '.ukit', 'storage', 'cache', 'hook-latency')}" \\`);
   lines.push(`  --out "${root}/scripts/perf/perf-findings.json"`);
+  lines.push('node scripts/perf/diff-perf-findings.mjs <earlier-snapshot>.json scripts/perf/perf-findings.json');
   lines.push('node --test tests/handoff/c33/perfFindings.test.js');
-  lines.push('```');
   lines.push('');
   lines.push(`- root: \`${root}\``);
   lines.push(`- settings.json: \`${settingsFile || 'NOT FOUND'}\``);
   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`);
   lines.push(`- benchmark iterations per subject: ${iterations}`);
   lines.push('');
   lines.push('## 2. Process floor (live spawnSync, ms)');
@@ -757,8 +970,19 @@ function renderMeasureDoc(context) {
   lines.push('');
   lines.push(`A hook row = wrapper bash + node runtime + advisory telemetry child = **${PROCESSES_PER_HOOK_ROW} processes**.`);
   lines.push('');
-  lines.push('## 3. Per-hook standalone re-run (`/bin/bash <script>` with `{}` on stdin, ms)');
+  lines.push('## 3. Telemetry append overhead (O5 — in-process `appendTelemetryRow`, ms)');
   lines.push('');
+  if (appendBench.stats) {
+    lines.push('| subject | iterations | p50 | p95 | max |');
+    lines.push('|---|---|---|---|---|');
+    lines.push(`| \`appendTelemetryRow\` → throwaway temp root | ${appendBench.iterations} | ${appendBench.stats.p50.toFixed(3)} | ${appendBench.stats.p95.toFixed(3)} | ${appendBench.stats.max.toFixed(3)} |`);
+    lines.push('');
+    lines.push(`Writer: \`${appendBench.module ? path.relative(root, appendBench.module) : 'n/a'}\`. Measured against a temp project root, so auditing a tree never adds rows to the dataset it is counting.`);
+  } else {
+    lines.push(`NOT MEASURED — ${appendBench.reason || 'the telemetry writer is not resolvable from this root'}. The observability layer's own cost stays unset rather than estimated.`);
+  }
+  lines.push('');
+  lines.push('## 4. Per-hook standalone re-run (`/bin/bash <script>` with `{}` on stdin, ms)');
   lines.push('| hook | p50 | p95 | max |');
   lines.push('|---|---|---|---|');
   for (const [name, stats] of [...hookBench.entries()].sort((a, b) => b[1].p50 - a[1].p50)) {
@@ -766,7 +990,7 @@ function renderMeasureDoc(context) {
   }
   if (!hookBench.size) lines.push('| _(no settings hook resolvable from this root)_ | | | |');
   lines.push('');
-  lines.push('## 4. Router/index helper cold start (ms)');
+  lines.push('## 5. Router/index helper cold start (ms)');
   lines.push('');
   lines.push('| helper | p50 | p95 | max |');
   lines.push('|---|---|---|---|');
@@ -775,7 +999,7 @@ function renderMeasureDoc(context) {
   }
   if (!routerBench.size) lines.push('| _(no helper resolvable from this root)_ | | | |');
   lines.push('');
-  lines.push('## 5. Per-hook telemetry (every hook with rows)');
+  lines.push('## 6. Per-hook telemetry (every hook with rows)');
   lines.push('');
   lines.push('| hook | n | p50 | p95 | max | total |');
   lines.push('|---|---|---|---|---|---|');
@@ -783,7 +1007,25 @@ function renderMeasureDoc(context) {
     lines.push(`| \`${hook}\` | ${stats.n} | ${stats.p50 ?? 'n/a'} | ${stats.p95 ?? 'n/a'} | ${stats.max ?? 'n/a'} | ${stats.total ?? 'n/a'} |`);
   }
   lines.push('');
-  lines.push('## 6. Per tool / per event cost (chain-runner total where present, else direct sum)');
+  lines.push('## 7. Stdin stage vs execution split (O3 — the wall-time tail attributed)');
+  lines.push('');
+  lines.push('A row\'s `elapsedMs` is the stdin stage plus the hook\'s own execution. `stageMs`');
+  lines.push('(direct rows) and `stdinStageMs` (chain rows) are the first half — the producer\'s');
+  lines.push('time, not the hook\'s — and `exec` below is the remainder, derived from the SAME');
+  lines.push('row so the two halves always sum to it. A row carrying neither field predates the');
+  lines.push('split or never staged stdin: it is excluded, never counted as a 0ms stage.');
+  lines.push('');
+  lines.push(`- rows with the split: ${split.measured} of ${telemetryRows}`);
+  lines.push(`- overall: stage ${split.stage.p50 ?? 'n/a'}ms p50 / ${split.stage.p95 ?? 'n/a'}ms p95, exec ${split.exec.p50 ?? 'n/a'}ms p50 / ${split.exec.p95 ?? 'n/a'}ms p95`);
+  lines.push('');
+  lines.push('| hook | field | n | stage p50 | stage p95 | exec p50 | exec p95 |');
+  lines.push('|---|---|---|---|---|---|---|');
+  for (const [hook, entry] of [...split.hooks.entries()].sort((a, b) => (b[1].stage.total || 0) - (a[1].stage.total || 0))) {
+    lines.push(`| \`${hook}\` | \`${entry.field}\` | ${entry.measured} | ${entry.stage.p50 ?? 'n/a'} | ${entry.stage.p95 ?? 'n/a'} | ${entry.exec.p50 ?? 'n/a'} | ${entry.exec.p95 ?? 'n/a'} |`);
+  }
+  if (!split.hooks.size) lines.push('| _(no row carries the split on this tree)_ | | | | | | |');
+  lines.push('');
+  lines.push('## 8. Per tool / per event cost (chain-runner total where present, else direct sum)');
   lines.push('');
   lines.push('| scope | calls | cost p50 | cost p95 | hook rows/call p50 | direct / chain-runner calls |');
   lines.push('|---|---|---|---|---|---|');
@@ -798,7 +1040,7 @@ function renderMeasureDoc(context) {
     lines.push(`| event ${event} (clustered, gap ≤ ${CLUSTER_GAP_MS}ms) | ${entry.calls} | ${entry.cost.p50 ?? 'n/a'} | ${entry.cost.p95 ?? 'n/a'} | ${entry.hookRows.p50 ?? 'n/a'} | ${entry.byPath.direct} / ${entry.byPath.chainRunner} |`);
   }
   lines.push('');
-  lines.push('## 7. Hook multiplicity proof (repeat-fire check)');
+  lines.push('## 9. Hook multiplicity proof (repeat-fire check)');
   lines.push('');
   lines.push('| hook | max fires in one tool call | calls observed | fire-count distribution |');
   lines.push('|---|---|---|---|');
@@ -806,7 +1048,7 @@ function renderMeasureDoc(context) {
     lines.push(`| \`${hook}\` | ${entry.maxPerCall} | ${entry.calls} | ${JSON.stringify(entry.distribution)} |`);
   }
   lines.push('');
-  lines.push('## 8. hook-chain-runner nested per-script (already-consolidated omp path)');
+  lines.push('## 10. hook-chain-runner nested per-script (already-consolidated omp path)');
   lines.push('');
   lines.push('| script | n | p50 | p95 | max |');
   lines.push('|---|---|---|---|---|');
@@ -814,7 +1056,7 @@ function renderMeasureDoc(context) {
     lines.push(`| \`${name}\` | ${stats.n} | ${stats.p50} | ${stats.p95} | ${stats.max} |`);
   }
   lines.push('');
-  lines.push('## 9. settings.json groups (spawn budget per call)');
+  lines.push('## 11. settings.json groups (spawn budget per call)');
   lines.push('');
   lines.push('| event | matcher | hooks | registered timeouts | spawns/call |');
   lines.push('|---|---|---|---|---|');
@@ -822,7 +1064,7 @@ function renderMeasureDoc(context) {
     lines.push(`| ${group.event} | ${group.matcher || '(all)'} | ${group.scripts.map((script) => script.script).join(', ')} | ${group.scripts.map((script) => `${script.timeout}s`).join(', ')} | ${group.scripts.length * PROCESSES_PER_HOOK_ROW} |`);
   }
   lines.push('');
-  lines.push('## 10. Recent hot-path additions (`git log --diff-filter=A`)');
+  lines.push('## 12. Recent hot-path additions (`git log --diff-filter=A`)');
   lines.push('');
   lines.push('| commit | date | subject | files added |');
   lines.push('|---|---|---|---|');
@@ -831,7 +1073,7 @@ function renderMeasureDoc(context) {
   }
   if (!additions.length) lines.push('| _(none in window)_ | | | |');
   lines.push('');
-  lines.push('## 11. Findings emitted');
+  lines.push('## 13. Findings emitted');
   lines.push('');
   lines.push('| id | evidence | p50 | p95 | status | fixTask |');
   lines.push('|---|---|---|---|---|---|');
@@ -844,7 +1086,7 @@ function renderMeasureDoc(context) {
 
 // --- main ------------------------------------------------------------------
 
-function main() {
+async function main() {
   const options = parseArgs(process.argv.slice(2));
   const root = options.root;
   const telemetryDir = options.telemetryDir || path.join(root, '.ukit', 'storage', 'cache', 'hook-latency');
@@ -860,10 +1102,12 @@ function main() {
   const events = eventAggregates(records);
   const multiplicity = hookMultiplicity(records);
   const nested = nestedScriptStats(telemetry.rows);
+  const split = stageSplit(telemetry.rows);
 
   const { floor, telemetryFinish } = benchmarkFloor(root, options.benchIterations);
   const { results: hookBench, dir: hooksResolvedFrom } = benchmarkHooks(root, groups, options.benchIterations);
   const routerBench = benchmarkRouterHelpers(root, options.benchIterations);
+  const appendBench = await benchmarkAppend(root, options.benchIterations);
   const additions = recentHotPathAdditions(root, options.sinceDays);
   const chainScripts = (() => {
     const lengths = new Map();
@@ -874,28 +1118,35 @@ function main() {
     return [...lengths.entries()].sort((a, b) => b[1] - a[1]).map(([length]) => length)[0] || 0;
   })();
 
+  // Snapshot provenance (O2): the dataset grows while it is being audited
+  // (30k → 34k rows in two hours in the finding), so a report that does not
+  // state how many rows and files it looked at cannot be compared with another.
+  const telemetryRows = telemetry.available ? telemetry.rows.length : 0;
+  const telemetryFiles = telemetry.available ? telemetry.files : 0;
   const telemetryDetail = telemetry.available
-    ? `.ukit/storage/cache/hook-latency — ${telemetry.rows.length} rows across ${telemetry.files} session files, span ${telemetry.span || 'n/a'}`
+    ? `.ukit/storage/cache/hook-latency — ${telemetryRows} rows across ${telemetryFiles} session files, span ${telemetry.span || 'n/a'}`
     : `telemetry directory not present (${telemetry.dir || 'n/a'})`;
 
   const generatedAt = new Date().toISOString();
   const context = {
     telemetry, telemetryDetail, groups, floor, telemetryFinish, hookBench, routerBench,
     root,
-    perHook, records, events, multiplicity, nested, additions, settingsFile,
+    perHook, records, events, multiplicity, nested, additions, settingsFile, split,
     iterations: options.benchIterations,
     sinceDays: options.sinceDays,
+    telemetryRows, telemetryFiles, appendBench,
     spawns: { chainScripts },
-    hooksResolvedFrom,
   };
   const findings = buildFindings({ ...context, generatedAt });
 
   const report = {
     generatedAt,
     schema: 'ukit-perf-findings/1',
+    telemetryRows,
+    telemetryFiles,
     sources: {
       telemetry: telemetry.available
-        ? { dir: telemetryDir, rows: telemetry.rows.length, files: telemetry.files }
+        ? { dir: telemetryDir, rows: telemetryRows, files: telemetryFiles }
         : { dir: telemetryDir, available: false },
       settings: settingsFile,
       hooksDir: hooksResolvedFrom,
@@ -911,10 +1162,10 @@ function main() {
 
   process.stdout.write(
     `${findings.length} findings → ${path.relative(root, outFile)}`
-    + ` (telemetry ${telemetry.available ? `${telemetry.rows.length} rows` : 'absent'},`
+    + ` (generatedAt ${generatedAt}, telemetry ${telemetry.available ? `${telemetryRows} rows / ${telemetryFiles} files` : 'absent'},`
     + ` settings ${settingsFile ? 'found' : 'missing'},`
     + ` ${groups.length} groups, ${hookBench.size} hooks benchmarked)\n`,
   );
 }
 
-main();
+await main();

package/scripts/perf/diff-perf-findings.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * diff-perf-findings.mjs — findings-level diff between two audit snapshots
+ * (TASK-006, SPEC §5 FR-008).
+ *
+ * Why a separate script and not a mode of `audit-perf.mjs`: the audit takes live
+ * measurements, so "compare two snapshots" is a read-only operation that must
+ * work against archived JSON long after the telemetry that produced it rotated
+ * away. This script never touches telemetry at all — it reads two reports and
+ * prints their deltas.
+ *
+ * Every snapshot is a point in time over a live dataset (see the O2 finding:
+ * 30k → 34k rows in two hours), so both snapshots' `generatedAt` /
+ * `telemetryRows` / `telemetryFiles` provenance is printed before any delta —
+ * two reports are only comparable once their provenance is known.
+ *
+ * Deltas reported, per finding id:
+ *   + <id> added    — present in b, absent from a
+ *   - <id> removed  — present in a, absent from b (never a crash)
+ *   ~ <id> changed  — same id, different status and/or different measured numbers
+ *
+ * Usage:
+ *   node scripts/perf/diff-perf-findings.mjs <a.json> <b.json>
+ *
+ * Exit: 0 = compared (with or without deltas, including a self-diff); 2 = usage,
+ * unreadable file, or a report that is not a findings snapshot.
+ */
+import fs from 'node:fs';
+
+const METRIC_KEYS = ['p50ms', 'p95ms', 'totalMs', 'invocations'];
+
+function usage() {
+  process.stderr.write('usage: node scripts/perf/diff-perf-findings.mjs <a.json> <b.json>\n');
+}
+
+function loadSnapshot(file) {
+  let report;
+  try {
+    report = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new Error(`cannot read findings snapshot ${file}: ${error.message}`);
+  }
+  if (!report || !Array.isArray(report.findings)) {
+    throw new Error(`${file} is not a findings snapshot (no findings[] array)`);
+  }
+  return report;
+}
+
+function formatNumber(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return 'n/a';
+  return Number.isInteger(value) ? String(value) : value.toFixed(1);
+}
+
+function provenanceLine(label, file, report) {
+  const rows = formatNumber(report.telemetryRows);
+  const files = formatNumber(report.telemetryFiles);
+  const generatedAt = typeof report.generatedAt === 'string' ? report.generatedAt : 'n/a';
+  return `${label}: ${file} — generatedAt ${generatedAt}, telemetryRows ${rows} / telemetryFiles ${files}`;
+}
+
+/** Metric drift for one finding pair, as `key a → b` fragments. */
+function metricDrift(before, after) {
+  return METRIC_KEYS
+    .filter((key) => before[key] !== after[key])
+    .map((key) => `${key} ${formatNumber(before[key])} → ${formatNumber(after[key])}`);
+}
+
+function diffFindings(a, b) {
+  const before = new Map(a.findings.map((item) => [item.id, item]));
+  const after = new Map(b.findings.map((item) => [item.id, item]));
+  const deltas = [];
+
+  for (const [id, item] of after) {
+    if (!before.has(id)) {
+      deltas.push({ kind: 'added', id, line: `+ ${id} added (status ${item.status})` });
+      continue;
+    }
+    const previous = before.get(id);
+    const drift = metricDrift(previous, item);
+    if (previous.status !== item.status) {
+      const suffix = drift.length ? ` (${drift.join(', ')})` : '';
+      deltas.push({
+        kind: 'changed',
+        id,
+        line: `~ ${id} status ${previous.status} → ${item.status}${suffix}`,
+      });
+    } else if (drift.length) {
+      deltas.push({ kind: 'changed', id, line: `~ ${id} ${drift.join(', ')}` });
+    }
+  }
+
+  for (const [id, item] of before) {
+    if (after.has(id)) continue;
+    deltas.push({ kind: 'removed', id, line: `- ${id} removed (was ${item.status})` });
+  }
+
+  return deltas;
+}
+
+function main(argv) {
+  const [fileA, fileB] = argv;
+  if (!fileA || !fileB || argv.length > 2) {
+    usage();
+    return 2;
+  }
+
+  let snapshotA;
+  let snapshotB;
+  try {
+    snapshotA = loadSnapshot(fileA);
+    snapshotB = loadSnapshot(fileB);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return 2;
+  }
+
+  const deltas = diffFindings(snapshotA, snapshotB);
+  const count = (kind) => deltas.filter((delta) => delta.kind === kind).length;
+  const lines = [
+    '# perf-findings diff',
+    provenanceLine('a', fileA, snapshotA),
+    provenanceLine('b', fileB, snapshotB),
+    '',
+  ];
+  if (deltas.length) {
+    lines.push(...deltas.map((delta) => delta.line), '');
+  }
+  lines.push(
+    `${deltas.length} delta${deltas.length === 1 ? '' : 's'}: `
+    + `${count('added')} added, ${count('removed')} removed, ${count('changed')} changed`,
+  );
+  process.stdout.write(`${lines.join('\n')}\n`);
+  return 0;
+}
+
+process.exitCode = main(process.argv.slice(2));