mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/observability/perf-aggregator.js

@@ -1,813 +0,0 @@
-/**
- * Performance signal aggregator (Epic #1030 / Story #1123; rewrite under
- * Epic #1181 / Story #1438 / Task #1460).
- *
- * Pure functions that turn the per-Story `signals.ndjson` stream into the
- * structured payloads posted by `analyze-execution.js`:
- *
- *   - `computeStoryPerfSummary(events, opts)` → `<!-- structured:story-perf-summary -->`
- *   - `computeEpicPerfReport(perStorySummaries, opts)` → `<!-- structured:epic-perf-report -->`
- *
- * Both take a materialised event iterable; the caller (`analyze-execution.js`)
- * owns NDJSON ingestion via `lib/signals/read.js`. (The former
- * streaming store-reading variants were retired in the Epic #4406
- * signal-contract cutover — they had no callers.)
- *
- * Schemas:
- *   - `.agents/schemas/story-perf-summary.schema.json`
- *   - `.agents/schemas/epic-perf-report.schema.json`
- *
- * Robustness contract:
- *   - Both helpers tolerate empty / partial input. Empty streams produce a
- *     well-formed payload with zeroed counters and empty arrays so the
- *     analyzer can still upsert a comment without throwing.
- *   - Malformed events (missing `kind`, non-object payload) are silently
- *     skipped; the caller is responsible for reading them off the wire and
- *     deciding whether to log. The aggregator never throws on bad data.
- *   - Numeric fields are floored to non-negative integers so the schemas
- *     (`integer`, `minimum: 0`) hold by construction.
- *
- * NDJSON ingestion discipline (Epic #1181):
- *   - Field-name literals for event `kind` come from
- *     `lib/signals/schema.js` so writer ↔ reader names stay in lockstep.
- *   - All file I/O for `signals.ndjson` goes through `lib/signals/read.js`
- *     (no direct `readFileSync` / `createReadStream` on signals.ndjson in
- *     this module). A grep gate in `tests/lib/checks/` enforces this on
- *     CI.
- */
-
-import { isObject } from '../json-utils.js';
-import { EVENT_KINDS } from '../signals/schema.js';
-
-const FRICTION_KIND = EVENT_KINDS.FRICTION;
-const HOTSPOT_KIND = EVENT_KINDS.HOTSPOT;
-const REWORK_KIND = EVENT_KINDS.REWORK;
-const RETRY_KIND = EVENT_KINDS.RETRY;
-const SIGNAL_COUNT_KINDS = Object.freeze([
-  EVENT_KINDS.FRICTION,
-  EVENT_KINDS.HOTSPOT,
-  EVENT_KINDS.REWORK,
-  EVENT_KINDS.CHURN,
-  EVENT_KINDS.IDLE,
-  EVENT_KINDS.RETRY,
-]);
-
-function nonNegativeInt(v) {
-  const n = Number(v);
-  if (!Number.isFinite(n) || n < 0) return 0;
-  return Math.floor(n);
-}
-
-function nonNegativeNumber(v) {
-  const n = Number(v);
-  if (!Number.isFinite(n) || n < 0) return 0;
-  return n;
-}
-
-/**
- * Pull friction-by-category counts off a list of NDJSON events. Keys are
- * the **top-level** `category` strings (Epic #4406 canonical shape); a
- * record with no top-level category buckets under `Unknown`. Reading the
- * top-level key (not `details.category`) is what un-zeroes the report —
- * every writer emits `category` at the envelope top level.
- *
- * @param {Iterable<object>} events
- * @returns {Object<string, number>}
- */
-function frictionByCategory(events) {
-  const out = {};
-  for (const evt of events) {
-    if (!isObject(evt) || evt.kind !== FRICTION_KIND) continue;
-    const category =
-      typeof evt.category === 'string' && evt.category.length > 0
-        ? evt.category
-        : 'Unknown';
-    out[category] = (out[category] ?? 0) + 1;
-  }
-  return out;
-}
-
-/**
- * Build the `topSlowPhasesVsBaseline` array. We accept hotspot signals
- * carrying `{ phase, elapsedMs, baselineP95Ms, ratio }` in `details` and
- * surface them sorted by ratio descending. The hotspot detector is a
- * future Epic-#1030 Story; until it lands the input list is empty and
- * this returns `[]`.
- *
- * @param {Iterable<object>} events
- * @param {{ limit?: number }} [opts]
- * @returns {Array<{phase: string, elapsedMs: number, baselineP95Ms: number, ratio: number}>}
- */
-function topSlowPhasesVsBaseline(events, opts = {}) {
-  const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 5;
-  const rows = [];
-  for (const evt of events) {
-    if (!isObject(evt) || evt.kind !== HOTSPOT_KIND) continue;
-    const d = isObject(evt.details) ? evt.details : {};
-    const phase =
-      typeof evt.phase === 'string' && evt.phase.length > 0
-        ? evt.phase
-        : typeof d.phase === 'string' && d.phase.length > 0
-          ? d.phase
-          : null;
-    if (!phase) continue;
-    rows.push({
-      phase,
-      elapsedMs: nonNegativeInt(d.elapsedMs),
-      baselineP95Ms: nonNegativeInt(d.baselineP95Ms),
-      ratio: nonNegativeNumber(d.ratio),
-    });
-  }
-  rows.sort((a, b) => b.ratio - a.ratio);
-  return rows.slice(0, limit);
-}
-
-/**
- * Build the `reworkScore` object: `{ filesEditedBeyondThreshold, topPath?,
- * topPathEdits? }`. We aggregate `kind: 'rework'` signals whose details
- * carry a `targetHash` and an `editCount` — the exact keys
- * `detectors/rework.js` emits (Epic #4406 canonical shape). `topPath` is
- * the offending `targetHash` (a sha256; the raw path never reaches the
- * aggregator by the privacy contract). When the input has no rework
- * signals we return the zero-shape: `{ filesEditedBeyondThreshold: 0 }`.
- *
- * @param {Iterable<object>} events
- * @returns {{ filesEditedBeyondThreshold: number, topPath?: string|null, topPathEdits?: number|null }}
- */
-function reworkScore(events) {
-  const editsByPath = new Map();
-  for (const evt of events) {
-    if (!isObject(evt) || evt.kind !== REWORK_KIND) continue;
-    const d = isObject(evt.details) ? evt.details : {};
-    const p =
-      typeof d.targetHash === 'string' && d.targetHash.length > 0
-        ? d.targetHash
-        : null;
-    if (!p) continue;
-    const edits = nonNegativeInt(d.editCount);
-    editsByPath.set(p, Math.max(editsByPath.get(p) ?? 0, edits));
-  }
-  if (editsByPath.size === 0) {
-    return { filesEditedBeyondThreshold: 0 };
-  }
-  let topPath = null;
-  let topPathEdits = 0;
-  for (const [p, n] of editsByPath) {
-    if (n > topPathEdits) {
-      topPath = p;
-      topPathEdits = n;
-    }
-  }
-  return {
-    filesEditedBeyondThreshold: editsByPath.size,
-    topPath,
-    topPathEdits,
-  };
-}
-
-/**
- * Build the `retryDensity` object: `{ retries, uniqueCommands }`. Sums
- * `kind: 'retry'` signals; `uniqueCommands` is the hash-cardinality of the
- * distinct `details.commandHash` values observed — the exact key
- * `detectors/retry.js` emits (Epic #4406 canonical shape). The raw command
- * never reaches the aggregator by the privacy contract, so we count
- * distinct hashes. Zero-shape on empty input.
- *
- * @param {Iterable<object>} events
- * @returns {{ retries: number, uniqueCommands: number }}
- */
-function retryDensity(events) {
-  let retries = 0;
-  const commandHashes = new Set();
-  for (const evt of events) {
-    if (!isObject(evt) || evt.kind !== RETRY_KIND) continue;
-    const d = isObject(evt.details) ? evt.details : {};
-    retries += 1;
-    if (typeof d.commandHash === 'string' && d.commandHash.length > 0) {
-      commandHashes.add(d.commandHash);
-    }
-  }
-  return { retries, uniqueCommands: commandHashes.size };
-}
-
-/**
- * Convert a phase-timer summary `{ phases: [{ name, elapsedMs }, ...] }`
- * into the flat `{ <name>: <ms> }` map the schema wants. Last entry wins
- * if a phase appears twice (mark/finish boundaries).
- *
- * @param {{ phases?: Array<{ name: string, elapsedMs: number }> } | null | undefined} timing
- * @returns {Object<string, number>}
- */
-function phaseTimingsMs(timing) {
-  if (!isObject(timing) || !Array.isArray(timing.phases)) return {};
-  const out = {};
-  for (const p of timing.phases) {
-    if (!isObject(p)) continue;
-    if (typeof p.name !== 'string' || p.name.length === 0) continue;
-    out[p.name] = nonNegativeInt(p.elapsedMs);
-  }
-  return out;
-}
-
-/**
- * Compute the StoryPerfSummary payload from a list of NDJSON events
- * sampled out of `temp/epic-<eid>/stories/story-<sid>/signals.ndjson` plus an
- * optional phase-timer summary.
- *
- * @param {Iterable<object>} events
- * @param {{ storyId: number, epicId: number, closedAt?: string, phaseTiming?: object|null }} opts
- * @returns {object} StoryPerfSummary payload (schema: story-perf-summary)
- */
-export function computeStoryPerfSummary(events, opts) {
-  if (!isObject(opts)) {
-    throw new TypeError('computeStoryPerfSummary: opts is required');
-  }
-  const storyId = Number(opts.storyId);
-  const epicId = Number(opts.epicId);
-  if (!Number.isInteger(storyId) || storyId < 1) {
-    throw new RangeError(
-      `computeStoryPerfSummary: storyId must be a positive integer (got ${opts.storyId})`,
-    );
-  }
-  if (!Number.isInteger(epicId) || epicId < 1) {
-    throw new RangeError(
-      `computeStoryPerfSummary: epicId must be a positive integer (got ${opts.epicId})`,
-    );
-  }
-  const closedAt =
-    typeof opts.closedAt === 'string' && opts.closedAt.length > 0
-      ? opts.closedAt
-      : new Date().toISOString();
-
-  // Materialise the iterable so each helper can scan independently.
-  const evtArr = [];
-  for (const e of events ?? []) {
-    if (isObject(e) && typeof e.kind === 'string') evtArr.push(e);
-  }
-
-  return {
-    kind: 'story-perf-summary',
-    storyId,
-    epicId,
-    closedAt,
-    frictionByCategory: frictionByCategory(evtArr),
-    phaseTimingsMs: phaseTimingsMs(opts.phaseTiming),
-    topSlowPhasesVsBaseline: topSlowPhasesVsBaseline(evtArr),
-    reworkScore: reworkScore(evtArr),
-    retryDensity: retryDensity(evtArr),
-  };
-}
-
-/**
- * Compute the EpicPerfReport payload from a list of per-Story summaries
- * (each shaped like `computeStoryPerfSummary`'s return value) plus an
- * optional list of raw events for signal-count rollup.
- *
- * `signalCounts` rolls up across **events**, not summaries — a Story's
- * `frictionByCategory` only carries friction (the named slice the schema
- * surfaces), but the Epic-level rollup wants every kind. When `opts.events`
- * is absent we fall back to summing each summary's friction count and
- * leave the other kinds at 0.
- *
- * @param {Iterable<object>} perStorySummaries
- * @param {{ epicId: number, generatedAt?: string, events?: Iterable<object>, waveParallelism?: Array<object>, topHotspots?: Array<object> }} opts
- * @returns {object} EpicPerfReport payload (schema: epic-perf-report)
- */
-/**
- * Predicate / collector: walk a `perStorySummaries` iterable and emit
- * only the entries whose `kind === 'story-perf-summary'`. Extracted from
- * `computeEpicPerfReport` so the input-validation cascade is independently
- * testable and the parent stays straight-line. Returns `[]` for nullish
- * inputs, which matches the parent's prior behaviour.
- *
- * @param {Iterable<object>|null|undefined} perStorySummaries
- * @returns {object[]}
- */
-export function collectValidStorySamples(perStorySummaries) {
-  const out = [];
-  if (!perStorySummaries) return out;
-  for (const s of perStorySummaries) {
-    if (isObject(s) && s.kind === 'story-perf-summary') out.push(s);
-  }
-  return out;
-}
-
-/**
- * Build the `signalCounts` block. When `events` is supplied we roll up
- * across every kind in `SIGNAL_COUNT_KINDS`; otherwise we sum the
- * per-Story friction counts so the legacy summary-only path keeps the
- * same friction total.
- *
- * @param {Iterable<object>|null|undefined} events
- * @param {object[]} summaries
- * @returns {{friction: number, hotspot: number, rework: number, churn: number, idle: number, retry: number}}
- */
-function buildSignalCounts(events, summaries) {
-  const counts = {
-    friction: 0,
-    hotspot: 0,
-    rework: 0,
-    churn: 0,
-    idle: 0,
-    retry: 0,
-  };
-  if (events) {
-    for (const evt of events) {
-      if (!isObject(evt) || typeof evt.kind !== 'string') continue;
-      if (SIGNAL_COUNT_KINDS.includes(evt.kind)) {
-        counts[evt.kind] += 1;
-      }
-    }
-    return counts;
-  }
-  for (const s of summaries) {
-    if (!isObject(s.frictionByCategory)) continue;
-    for (const v of Object.values(s.frictionByCategory)) {
-      counts.friction += nonNegativeInt(v);
-    }
-  }
-  return counts;
-}
-
-/**
- * Aggregate the `topHotspots` block from per-Story samples: group each
- * story's `topSlowPhasesVsBaseline` rows by phase, count occurrences,
- * average the ratio, then sort by `occurrences desc, avgRatio desc` and
- * cap at 5. Extracted from `computeEpicPerfReport` so the parent stays
- * straight-line; callers that pass `opts.topHotspots` skip this helper
- * entirely.
- *
- * @param {object[]} summaries
- * @returns {Array<{phase: string, occurrences: number, avgRatio: number}>}
- */
-function aggregateTopHotspots(summaries) {
-  const acc = new Map();
-  for (const s of summaries) {
-    const arr = Array.isArray(s.topSlowPhasesVsBaseline)
-      ? s.topSlowPhasesVsBaseline
-      : [];
-    for (const row of arr) {
-      if (!isObject(row) || typeof row.phase !== 'string') continue;
-      const rec = acc.get(row.phase) ?? {
-        phase: row.phase,
-        occurrences: 0,
-        ratioSum: 0,
-      };
-      rec.occurrences += 1;
-      rec.ratioSum += nonNegativeNumber(row.ratio);
-      acc.set(row.phase, rec);
-    }
-  }
-  return [...acc.values()]
-    .map((r) => ({
-      phase: r.phase,
-      occurrences: r.occurrences,
-      avgRatio: r.occurrences > 0 ? r.ratioSum / r.occurrences : 0,
-    }))
-    .sort((a, b) => b.occurrences - a.occurrences || b.avgRatio - a.avgRatio)
-    .slice(0, 5);
-}
-
-/**
- * Default verify-concurrency cap when the caller does not override it.
- * Mirrors the default for `delivery.deliverRunner.verifyConcurrencyCap`
- * in `.agentrc.json` (Epic #3019 Tech Spec §1.4).
- */
-const DEFAULT_VERIFY_CONCURRENCY_CAP = 4;
-
-/**
- * Default wave-execution concurrency cap used when the caller does not
- * supply `concurrencyCap` to {@link computeWaveParallelismRows}. The
- * project default (`delivery.deliverRunner.concurrencyCap`) is 2 today;
- * the value here is the safe fallback for offline / test contexts.
- */
-const DEFAULT_WAVE_CONCURRENCY_CAP = 2;
-
-function tsOf(evt) {
-  return evt?.ts ?? null;
-}
-
-function tsToMs(ts) {
-  if (typeof ts !== 'string') return null;
-  const n = Date.parse(ts);
-  return Number.isFinite(n) ? n : null;
-}
-
-function storyIdOf(evt) {
-  const n = Number(evt?.storyId);
-  return Number.isInteger(n) && n > 0 ? n : null;
-}
-
-/**
- * Materialise an event iterable into an array of `{ evt, ms }` records,
- * parsing each event's timestamp **exactly once** (Story #3343). Events
- * with a non-string `kind` are dropped (matching the prior inline guard);
- * the `ms` field is `null` when the timestamp is missing or unparseable so
- * downstream passes can skip it without re-parsing.
- *
- * @param {Iterable<object>} events
- * @returns {Array<{ evt: object, ms: number|null }>}
- */
-function materialiseTimedEvents(events) {
-  const out = [];
-  for (const evt of events ?? []) {
-    if (isObject(evt) && typeof evt.kind === 'string') {
-      out.push({ evt, ms: tsToMs(tsOf(evt)) });
-    }
-  }
-  return out;
-}
-
-/**
- * Index Story state-transition windows from pre-timed events: first
- * `agent::executing` → last terminal (`agent::done` | `agent::blocked` |
- * `agent::failed`). Reuses the per-event `ms` parsed by
- * {@link materialiseTimedEvents}. Extracted from
- * {@link computeWaveParallelismRows} (Story #3343).
- *
- * @param {Array<{ evt: object, ms: number|null }>} timedEvents
- * @returns {Map<number, { startMs: number|null, endMs: number|null }>}
- */
-function indexStoryWindows(timedEvents) {
-  const storyWindows = new Map();
-  for (const { evt, ms } of timedEvents) {
-    if (evt.kind !== 'state-transition') continue;
-    const sid = storyIdOf(evt);
-    if (sid == null) continue;
-    if (ms == null) continue;
-    const to =
-      (isObject(evt.details) && evt.details.to) ?? evt.to ?? evt.toState;
-    const rec = storyWindows.get(sid) ?? { startMs: null, endMs: null };
-    if (to === 'agent::executing') {
-      if (rec.startMs == null || ms < rec.startMs) rec.startMs = ms;
-    } else if (
-      to === 'agent::done' ||
-      to === 'agent::blocked' ||
-      to === 'agent::failed'
-    ) {
-      if (rec.endMs == null || ms > rec.endMs) rec.endMs = ms;
-    }
-    storyWindows.set(sid, rec);
-  }
-  return storyWindows;
-}
-
-/**
- * Bucket `wave-start` / `wave-complete` events by index from pre-timed
- * events. Reuses the per-event `ms` parsed by
- * {@link materialiseTimedEvents}. Extracted from
- * {@link computeWaveParallelismRows} (Story #3343).
- *
- * @param {Array<{ evt: object, ms: number|null }>} timedEvents
- * @returns {Map<number, { startMs: number|null, endMs: number|null, stories: number[] }>}
- */
-function bucketWaves(timedEvents) {
-  const waves = new Map();
-  for (const { evt, ms } of timedEvents) {
-    if (ms == null) continue;
-    if (evt.kind === 'wave-start') {
-      const idx = Number(evt.index);
-      if (!Number.isInteger(idx) || idx < 0) continue;
-      const storiesField = Array.isArray(evt.stories) ? evt.stories : [];
-      const storyIds = storiesField
-        .map((s) => {
-          const n = Number(isObject(s) ? (s.id ?? s.storyId) : s);
-          return Number.isInteger(n) && n > 0 ? n : null;
-        })
-        .filter((n) => n != null);
-      const rec = waves.get(idx) ?? {
-        startMs: null,
-        endMs: null,
-        stories: [],
-      };
-      if (rec.startMs == null || ms < rec.startMs) rec.startMs = ms;
-      rec.stories = storyIds;
-      waves.set(idx, rec);
-    } else if (evt.kind === 'wave-complete') {
-      const idx = Number(evt.index);
-      if (!Number.isInteger(idx) || idx < 0) continue;
-      const rec = waves.get(idx) ?? {
-        startMs: null,
-        endMs: null,
-        stories: [],
-      };
-      if (rec.endMs == null || ms > rec.endMs) rec.endMs = ms;
-      waves.set(idx, rec);
-    }
-  }
-  return waves;
-}
-
-/**
- * Largest value `< hi` that is `>= lo` in a sorted ascending array, or
- * `null` when the half-open window `[lo, hi)` contains no element. Pure
- * binary search — used by {@link fillMissingWaveEnds} to find a wave's
- * fallback terminator without re-scanning the whole event array per wave.
- *
- * @param {number[]} sortedMs ascending
- * @param {number} lo inclusive lower bound
- * @param {number} hi exclusive upper bound (may be Infinity)
- * @returns {number|null}
- */
-function maxInWindow(sortedMs, lo, hi) {
-  // Find the first index with value >= hi (upper bound), then step back to
-  // the last element strictly below hi.
-  let left = 0;
-  let right = sortedMs.length;
-  while (left < right) {
-    const mid = (left + right) >> 1;
-    if (sortedMs[mid] < hi) left = mid + 1;
-    else right = mid;
-  }
-  const candidate = left - 1; // last index with value < hi
-  if (candidate < 0) return null;
-  const val = sortedMs[candidate];
-  return val >= lo ? val : null;
-}
-
-/**
- * Fill the `endMs` of any wave that never observed a `wave-complete`:
- * each such wave's terminator is the max event timestamp in the half-open
- * window `[startMs, nextStartMs)`, where `nextStartMs` is the start of the
- * next wave by ascending index (or `Infinity` for the last wave).
- *
- * Replaces the prior O(waves × events) nested scan with a single sort of
- * the already-parsed timestamps plus one binary search per gap-wave
- * (Story #3343). Output is byte-identical to the prior implementation.
- *
- * @param {Array<[number, { startMs: number|null, endMs: number|null, stories: number[] }]>} orderedWaves sorted by index asc
- * @param {Array<{ evt: object, ms: number|null }>} timedEvents
- * @returns {void} mutates the wave records in `orderedWaves` in place
- */
-function fillMissingWaveEnds(orderedWaves, timedEvents) {
-  const needsFill = orderedWaves.some(
-    ([, rec]) => rec.endMs == null && rec.startMs != null,
-  );
-  if (!needsFill) return;
-  const sortedMs = [];
-  for (const { ms } of timedEvents) {
-    if (ms != null) sortedMs.push(ms);
-  }
-  sortedMs.sort((a, b) => a - b);
-  for (let i = 0; i < orderedWaves.length; i += 1) {
-    const [, rec] = orderedWaves[i];
-    if (rec.endMs != null) continue;
-    const startMs = rec.startMs;
-    if (startMs == null) continue;
-    const nextStartMs =
-      i + 1 < orderedWaves.length ? orderedWaves[i + 1][1].startMs : Infinity;
-    const maxMs = maxInWindow(sortedMs, startMs, nextStartMs);
-    rec.endMs = maxMs == null ? startMs : Math.max(startMs, maxMs);
-  }
-}
-
-/**
- * Compute per-wave parallelism rows from a chronological iterable of
- * lifecycle events (Task #3028, Epic #3019 / Story #3025).
- *
- * Wave windows are bracketed by `wave-start` (carrying `index` +
- * `stories[]`) and the matching `wave-complete` (same `index`). When no
- * `wave-complete` is observed for a wave, the wave's wallClockMs falls
- * back to the timestamp of the last in-wave event observed (so partial
- * runs still emit a row). When `wave-start` is missing entirely we emit
- * no row for that wave.
- *
- * Per-Story durations within a wave come from `state-transition` events
- * (`agent::executing` → `agent::done`) for the Story IDs the
- * `wave-start` payload enumerated. We bracket the **first**
- * `executing` transition and the **last** terminal transition (`done`,
- * `blocked`, or `failed`) per Story; if a Story is missing one boundary
- * its contribution to `summedStoryMs` is 0.
- *
- * Field contract (per the extended `epic-perf-report.schema.json`):
- *   - `waveIndex`: integer ≥ 0, from `wave-start.index`
- *   - `storyCount`: integer ≥ 0, number of Stories in the wave (from
- *     `wave-start.stories`). Added under Story #3850.
- *   - `wallClockMs`: integer ≥ 0, `(waveEnd - waveStart)` in ms
- *   - `summedStoryMs`: integer ≥ 0, Σ per-Story `(end - start)`
- *   - `utilisation`: `summedStoryMs / (wallClockMs * effectiveCap)`,
- *     where `effectiveCap = min(storyCount, concurrencyCap)`, clamped
- *     to `[0, 1]`. Zero when `wallClockMs === 0` or effectiveCap is 0.
- *     Using the effective (not raw) cap means a fully-busy 1-Story wave
- *     scores 1.0 rather than `1/cap`, eliminating false-positive
- *     `low-utilisation` signals on serialized/narrow waves (Story #3850).
- *   - `capBinding`: true when `summedStoryMs / wallClockMs >=
- *     concurrencyCap`, false otherwise (and false when wallClockMs
- *     is 0). Still uses the raw cap so the signal fires when the
- *     configured parallelism ceiling is actually saturated.
- *   - `verifyConcurrencyCap`: forwarded from `opts.verifyConcurrencyCap`
- *     (or the project default 4) so the post-merge close comment can
- *     attribute saturation back to the cap value in force at the time.
- *
- * @param {Iterable<object>} events
- * @param {{
- *   concurrencyCap?: number,
- *   verifyConcurrencyCap?: number,
- * }} [opts]
- * @returns {Array<{
- *   waveIndex: number,
- *   storyCount: number,
- *   wallClockMs: number,
- *   summedStoryMs: number,
- *   utilisation: number,
- *   capBinding: boolean,
- *   verifyConcurrencyCap: number,
- * }>}
- */
-export function computeWaveParallelismRows(events, opts = {}) {
-  const concurrencyCap =
-    Number.isInteger(opts.concurrencyCap) && opts.concurrencyCap >= 1
-      ? opts.concurrencyCap
-      : DEFAULT_WAVE_CONCURRENCY_CAP;
-  const verifyConcurrencyCap =
-    Number.isInteger(opts.verifyConcurrencyCap) &&
-    opts.verifyConcurrencyCap >= 1
-      ? opts.verifyConcurrencyCap
-      : DEFAULT_VERIFY_CONCURRENCY_CAP;
-
-  // Materialise the iterable once, parsing each event's timestamp a
-  // single time so every downstream pass reuses the same `ms` value
-  // (Story #3343). Events are typically a few thousand per Epic at most.
-  const timedEvents = materialiseTimedEvents(events);
-
-  // Index Story state-transition windows: first `agent::executing` →
-  // last terminal (`agent::done` | `agent::blocked` | `agent::failed`).
-  const storyWindows = indexStoryWindows(timedEvents);
-
-  // Bucket wave-start / wave-complete events by index, then fill any wave
-  // that never saw `wave-complete` via a single sorted-timestamp sweep
-  // (replacing the prior O(waves × events) nested scan).
-  const waves = bucketWaves(timedEvents);
-  const orderedWaves = [...waves.entries()].sort((a, b) => a[0] - b[0]);
-  fillMissingWaveEnds(orderedWaves, timedEvents);
-
-  // Build rows.
-  const rows = [];
-  for (const [idx, rec] of orderedWaves) {
-    if (rec.startMs == null) continue;
-    const wallClockMs = Math.max(
-      0,
-      Math.floor((rec.endMs ?? rec.startMs) - rec.startMs),
-    );
-    const storyCount = rec.stories.length;
-    let summedStoryMs = 0;
-    for (const sid of rec.stories) {
-      const w = storyWindows.get(sid);
-      if (!w || w.startMs == null || w.endMs == null) continue;
-      const dur = w.endMs - w.startMs;
-      if (Number.isFinite(dur) && dur > 0) summedStoryMs += Math.floor(dur);
-    }
-    // Use the effective cap — min(storyCount, concurrencyCap) — as the
-    // utilisation denominator so a fully-busy 1-Story wave scores 1.0
-    // instead of 1/cap. This eliminates false-positive `low-utilisation`
-    // signals on serialized / narrow-wave Epics (Story #3850).
-    // capBinding still uses the raw concurrencyCap because it signals that
-    // the configured parallelism ceiling is genuinely saturated.
-    const effectiveCap = Math.min(storyCount, concurrencyCap);
-    let utilisation = 0;
-    let capBinding = false;
-    if (wallClockMs > 0 && effectiveCap > 0) {
-      utilisation = clamp(summedStoryMs / (wallClockMs * effectiveCap), 0, 1);
-    }
-    if (wallClockMs > 0 && concurrencyCap > 0) {
-      capBinding = summedStoryMs / wallClockMs >= concurrencyCap;
-    }
-    rows.push({
-      waveIndex: idx,
-      storyCount,
-      wallClockMs,
-      summedStoryMs,
-      utilisation,
-      capBinding,
-      verifyConcurrencyCap,
-    });
-  }
-
-  return rows;
-}
-
-/**
- * Clamp `n` to the inclusive range [lo, hi]. Returns `lo` for NaN /
- * non-finite inputs so the coercer stays well-behaved on garbage.
- *
- * @param {number} n
- * @param {number} lo
- * @param {number} hi
- * @returns {number}
- */
-function clamp(n, lo, hi) {
-  if (!Number.isFinite(n)) return lo;
-  if (n < lo) return lo;
-  if (n > hi) return hi;
-  return n;
-}
-
-/**
- * Coerce a single waveParallelism input row into the schema-canonical
- * shape `{ waveIndex, storyCount, wallClockMs, summedStoryMs, utilisation,
- * capBinding, verifyConcurrencyCap }` (Story #3025; storyCount added
- * Story #3850).
- *
- * - Numeric fields are floored to non-negative integers (or clamped
- *   numbers for utilisation) so the JSON-schema `integer` / `minimum: 0`
- *   constraints hold by construction.
- * - `utilisation` is clamped to `[0, 1]` per the Tech Spec
- *   contract (§1.1).
- * - `capBinding` is coerced to boolean.
- * - `verifyConcurrencyCap` falls back to the project default (4) when the
- *   caller omits it or supplies a non-positive integer; the schema
- *   requires `minimum: 1` so 0 is not a valid carrier value.
- * - `storyCount` falls back to 0 when absent (older payloads predating
- *   Story #3850 do not carry the field).
- *
- * Exported for unit-testing the coercer in isolation.
- *
- * @param {object | null | undefined} row
- * @returns {{ waveIndex: number, storyCount: number, wallClockMs: number, summedStoryMs: number, utilisation: number, capBinding: boolean, verifyConcurrencyCap: number }}
- */
-export function coerceWaveParallelismRow(row) {
-  const src = isObject(row) ? row : {};
-  const cap = Number(src.verifyConcurrencyCap);
-  const verifyConcurrencyCap =
-    Number.isInteger(cap) && cap >= 1 ? cap : DEFAULT_VERIFY_CONCURRENCY_CAP;
-  return {
-    waveIndex: nonNegativeInt(src.waveIndex),
-    storyCount: nonNegativeInt(src.storyCount),
-    wallClockMs: nonNegativeInt(src.wallClockMs),
-    summedStoryMs: nonNegativeInt(src.summedStoryMs),
-    utilisation: clamp(nonNegativeNumber(src.utilisation), 0, 1),
-    capBinding: Boolean(src.capBinding),
-    verifyConcurrencyCap,
-  };
-}
-
-export function computeEpicPerfReport(perStorySummaries, opts) {
-  if (!isObject(opts)) {
-    throw new TypeError('computeEpicPerfReport: opts is required');
-  }
-  const epicId = Number(opts.epicId);
-  if (!Number.isInteger(epicId) || epicId < 1) {
-    throw new RangeError(
-      `computeEpicPerfReport: epicId must be a positive integer (got ${opts.epicId})`,
-    );
-  }
-  const generatedAt =
-    typeof opts.generatedAt === 'string' && opts.generatedAt.length > 0
-      ? opts.generatedAt
-      : new Date().toISOString();
-
-  const summaries = collectValidStorySamples(perStorySummaries);
-
-  // signalCounts: prefer the raw-event roll-up; fall back to friction-only
-  // when the caller did not pass events.
-  const signalCounts = buildSignalCounts(opts.events, summaries);
-
-  const topHotspots = Array.isArray(opts.topHotspots)
-    ? opts.topHotspots
-    : aggregateTopHotspots(summaries);
-
-  // mostFrictionStories: per-Story friction count, sorted desc, capped.
-  const mostFrictionStories = summaries
-    .map((s) => {
-      const counts = isObject(s.frictionByCategory)
-        ? Object.values(s.frictionByCategory).reduce(
-            (acc, v) => acc + nonNegativeInt(v),
-            0,
-          )
-        : 0;
-      return {
-        storyId: nonNegativeInt(s.storyId),
-        frictionCount: counts,
-      };
-    })
-    .filter((row) => row.storyId > 0)
-    .sort((a, b) => b.frictionCount - a.frictionCount)
-    .slice(0, 5);
-
-  let waveParallelism;
-  if (Array.isArray(opts.waveParallelism)) {
-    waveParallelism = opts.waveParallelism.map((row) =>
-      coerceWaveParallelismRow(row),
-    );
-  } else if (opts.events) {
-    // Derive rows from the raw lifecycle event stream when the caller
-    // hands us the events but no pre-computed array (Story #3025 /
-    // Task #3028).
-    waveParallelism = computeWaveParallelismRows(opts.events, {
-      concurrencyCap: opts.concurrencyCap,
-      verifyConcurrencyCap: opts.verifyConcurrencyCap,
-    });
-  } else {
-    waveParallelism = [];
-  }
-
-  return {
-    kind: 'epic-perf-report',
-    epicId,
-    generatedAt,
-    signalCounts,
-    waveParallelism,
-    topHotspots,
-    mostFrictionStories,
-  };
-}