@elabs-ai/components-process 4.1.0

package/src/core/discover-graph.test.ts

@@ -0,0 +1,378 @@
+import { describe, expect, it } from "vitest";
+
+import { discoverGraph } from "./discover-graph";
+import { DURATION_SAMPLE_CAP } from "./duration-stats";
+import { asNormalizedLog, normalizeLog } from "./event-log";
+import { generateSyntheticLog } from "./fixtures/synthetic-log";
+import fixture from "./fixtures/order-to-cash-small.json";
+import type { ActivityStats, EventLog, TransitionStats } from "./types";
+
+const orderToCash = fixture as EventLog;
+
+/**
+ * The five traces in `order-to-cash-small.json`, restated here so the expected table
+ * below can be read against them without opening the fixture:
+ *
+ *   case-1  Create Order · Check Credit · Approve Order · Ship Order · Send Invoice · Receive Payment
+ *   case-2  Create Order · Check Credit · Approve Order · Ship Order · Send Invoice · Receive Payment
+ *   case-3  Create Order · Check Credit · Reject Order
+ *   case-4  Create Order · Check Credit · Amend Order · Check Credit · Approve Order · Ship Order ·
+ *           Send Invoice · Receive Payment
+ *   case-5  Create Order · Check Credit · Approve Order · Send Invoice · Ship Order · Receive Payment
+ *
+ * 29 events, 5 cases, 4 distinct sequences. Every number below was counted from those
+ * five lines by hand, not read off the implementation.
+ */
+type ActivityRow = Omit<ActivityStats, "duration">;
+type TransitionRow = Omit<TransitionStats, "duration">;
+
+const stripDuration = (graph: { activities: ActivityStats[]; transitions: TransitionStats[] }) => ({
+  activities: graph.activities.map(({ duration: _duration, ...row }) => row) as ActivityRow[],
+  transitions: graph.transitions.map(({ duration: _duration, ...row }) => row) as TransitionRow[],
+});
+
+describe("discoverGraph on the 5-case order-to-cash fixture", () => {
+  it("reproduces the hand-computed activity table", () => {
+    // Ordered busiest-first, ties broken by name.
+    expect(stripDuration(discoverGraph(orderToCash)).activities).toEqual([
+      {
+        id: "Check Credit",
+        label: "Check Credit",
+        instances: 6,
+        cases: 5,
+        isStart: false,
+        isEnd: false,
+      },
+      {
+        id: "Create Order",
+        label: "Create Order",
+        instances: 5,
+        cases: 5,
+        isStart: true,
+        isEnd: false,
+      },
+      {
+        id: "Approve Order",
+        label: "Approve Order",
+        instances: 4,
+        cases: 4,
+        isStart: false,
+        isEnd: false,
+      },
+      {
+        id: "Receive Payment",
+        label: "Receive Payment",
+        instances: 4,
+        cases: 4,
+        isStart: false,
+        isEnd: true,
+      },
+      {
+        id: "Send Invoice",
+        label: "Send Invoice",
+        instances: 4,
+        cases: 4,
+        isStart: false,
+        isEnd: false,
+      },
+      {
+        id: "Ship Order",
+        label: "Ship Order",
+        instances: 4,
+        cases: 4,
+        isStart: false,
+        isEnd: false,
+      },
+      {
+        id: "Amend Order",
+        label: "Amend Order",
+        instances: 1,
+        cases: 1,
+        isStart: false,
+        isEnd: false,
+      },
+      {
+        id: "Reject Order",
+        label: "Reject Order",
+        instances: 1,
+        cases: 1,
+        isStart: false,
+        isEnd: true,
+      },
+    ]);
+  });
+
+  it("reproduces the hand-computed transition table", () => {
+    // Ordered by count descending, then source, then target.
+    expect(stripDuration(discoverGraph(orderToCash)).transitions).toEqual([
+      {
+        source: "Create Order",
+        target: "Check Credit",
+        count: 5,
+        caseCount: 5,
+        isSelfLoop: false,
+        isBackEdge: false,
+      },
+      {
+        source: "Check Credit",
+        target: "Approve Order",
+        count: 4,
+        caseCount: 4,
+        isSelfLoop: false,
+        isBackEdge: false,
+      },
+      {
+        source: "Approve Order",
+        target: "Ship Order",
+        count: 3,
+        caseCount: 3,
+        isSelfLoop: false,
+        isBackEdge: false,
+      },
+      {
+        source: "Send Invoice",
+        target: "Receive Payment",
+        count: 3,
+        caseCount: 3,
+        isSelfLoop: false,
+        isBackEdge: false,
+      },
+      {
+        source: "Ship Order",
+        target: "Send Invoice",
+        count: 3,
+        caseCount: 3,
+        isSelfLoop: false,
+        isBackEdge: false,
+      },
+      {
+        source: "Amend Order",
+        target: "Check Credit",
+        count: 1,
+        caseCount: 1,
+        isSelfLoop: false,
+        isBackEdge: false,
+      },
+      {
+        source: "Approve Order",
+        target: "Send Invoice",
+        count: 1,
+        caseCount: 1,
+        isSelfLoop: false,
+        isBackEdge: false,
+      },
+      {
+        source: "Check Credit",
+        target: "Amend Order",
+        count: 1,
+        caseCount: 1,
+        isSelfLoop: false,
+        isBackEdge: false,
+      },
+      {
+        source: "Check Credit",
+        target: "Reject Order",
+        count: 1,
+        caseCount: 1,
+        isSelfLoop: false,
+        isBackEdge: false,
+      },
+      {
+        source: "Send Invoice",
+        target: "Ship Order",
+        count: 1,
+        caseCount: 1,
+        isSelfLoop: false,
+        isBackEdge: false,
+      },
+      {
+        source: "Ship Order",
+        target: "Receive Payment",
+        count: 1,
+        caseCount: 1,
+        isSelfLoop: false,
+        isBackEdge: false,
+      },
+    ]);
+  });
+
+  it("reproduces the hand-computed start/end tallies and totals", () => {
+    const graph = discoverGraph(orderToCash);
+    expect(graph.startActivities).toEqual({ "Create Order": 5 });
+    expect(graph.endActivities).toEqual({ "Receive Payment": 4, "Reject Order": 1 });
+    expect(graph.totals).toEqual({ cases: 5, events: 29, variants: 4 });
+    // The two tallies must add up to the case count, once each.
+    const sum = (record: Record<string, number>): number =>
+      Object.values(record).reduce((total, value) => total + value, 0);
+    expect(sum(graph.startActivities)).toBe(5);
+    expect(sum(graph.endActivities)).toBe(5);
+  });
+
+  it("reproduces the hand-computed idle-time statistics of the busiest edge", () => {
+    // Create Order → Check Credit: 60 min in cases 1-4, 120 min in case 5.
+    // sorted [3.6e6, 3.6e6, 3.6e6, 3.6e6, 7.2e6] → sum 21.6e6, mean 4.32e6, median 3.6e6,
+    // p90 at pos 0.9 * 4 = 3.6 → 3.6e6 + 0.6 * 3.6e6 = 5.76e6, trim floor(0.5) = 0.
+    const edge = discoverGraph(orderToCash).transitions[0];
+    expect(edge?.duration).toEqual({
+      min: 3_600_000,
+      max: 7_200_000,
+      mean: 4_320_000,
+      median: 3_600_000,
+      p90: 5_760_000,
+      sum: 21_600_000,
+      trimmedMean: 4_320_000,
+    });
+  });
+
+  it("reports zero activity durations, because every fixture event is atomic", () => {
+    for (const activity of discoverGraph(orderToCash).activities) {
+      expect(activity.duration.sum).toBe(0);
+      expect(activity.duration.max).toBe(0);
+    }
+  });
+
+  it("accepts an already-normalized log and answers identically", () => {
+    expect(discoverGraph(normalizeLog(orderToCash))).toEqual(discoverGraph(orderToCash));
+  });
+
+  it("is deterministic — two runs over one log are deeply equal", () => {
+    expect(discoverGraph(orderToCash)).toEqual(discoverGraph(orderToCash));
+  });
+});
+
+describe("discoverGraph determinism past the duration-sample cap (RM-052 round 2, #227, F5)", () => {
+  // The determinism test above runs on the 5-case order-to-cash fixture (29 events), so no
+  // activity or edge ever offers more than a handful of duration samples — `DurationSampler`
+  // fills its reservoir and stops, and its seeded `mulberry32` PRNG is never consulted. That
+  // makes the assertion real but VACUOUS as a lock on the reservoir-REPLACEMENT branch (the
+  // one `add()` takes once `this.reservoir.length === this.capacity`, which is where a
+  // clock-seeded or otherwise non-deterministic RNG would actually show up as flaky output).
+  //
+  // "Create Order" opens every trace exactly once and unconditionally (see `buildTrace` in
+  // `./fixtures/synthetic-log.ts` — it is pushed before any of the random branches run), so
+  // at `cases: 5_000` its activity, and the "Create Order" → "Check Credit" edge that always
+  // follows it, each accumulate exactly 5,000 duration samples — comfortably past
+  // `DURATION_SAMPLE_CAP` (4,096) — forcing the replacement branch to run on every one of the
+  // 904 samples past the cap, not merely on the ones that fill it.
+  const bigLog = generateSyntheticLog({ cases: 5_000, seed: 11 });
+
+  it("proves the reservoir-replacement branch actually ran, by observed sample count — not log size", () => {
+    // Non-vacuity check, corrected (RM-052 round 3, #227, G3): `instances`/`count` below
+    // are the number of EVENTS/TRANSITIONS `discoverGraph` walked for that activity/edge —
+    // not a read of `DurationSampler`'s own state. They only stand in for "samples offered
+    // to the sampler" because every walked event/transition unconditionally calls
+    // `duration.add(...)` (see `discover-graph.ts`) with a FINITE duration. Assert that
+    // premise directly: every case in `bigLog`, once normalized the same way
+    // `discoverGraph` normalizes its input, has a finite `duration`/`start`/`end` on every
+    // event — so no event is silently dropped by `DurationSampler.add`'s
+    // `Number.isFinite` guard, and the instances/count tallies below really do equal the
+    // sampler's offered-sample count.
+    for (const normalizedCase of asNormalizedLog(bigLog).cases) {
+      for (const event of normalizedCase.events) {
+        expect(Number.isFinite(event.duration)).toBe(true);
+        expect(Number.isFinite(event.start)).toBe(true);
+        expect(Number.isFinite(event.end)).toBe(true);
+      }
+    }
+
+    const graph = discoverGraph(bigLog);
+    const createOrder = graph.activities.find((activity) => activity.id === "Create Order");
+    expect(createOrder?.instances).toBeGreaterThan(DURATION_SAMPLE_CAP);
+
+    const firstEdge = graph.transitions.find(
+      (edge) => edge.source === "Create Order" && edge.target === "Check Credit",
+    );
+    expect(firstEdge?.count).toBeGreaterThan(DURATION_SAMPLE_CAP);
+  });
+
+  it("is deterministic even once the PRNG reservoir-replacement branch is exercised", () => {
+    // Two independent `discoverGraph` calls over the same log, each building its own fresh
+    // `DurationSampler`s from scratch (seeded from a per-graph creation counter, never from
+    // a clock — see the `nextSeed` comment in `discover-graph.ts`). If that seeding, or the
+    // PRNG it feeds, ever became non-deterministic, this is where it would show up: past the
+    // cap, every kept/discarded decision depends on `this.random()`, so a diverging seed
+    // would diverge the retained reservoir, and with it `median`/`p90`/`trimmedMean`.
+    expect(discoverGraph(bigLog)).toEqual(discoverGraph(bigLog));
+  });
+});
+
+describe("discoverGraph edge semantics", () => {
+  it("marks a repeated activity as a self-loop", () => {
+    const log: EventLog = {
+      events: [
+        { caseId: "c1", activity: "Pick", timestamp: 0 },
+        { caseId: "c1", activity: "Pick", timestamp: 1000 },
+      ],
+    };
+    const [edge] = discoverGraph(log).transitions;
+    expect(edge).toMatchObject({ source: "Pick", target: "Pick", count: 1, isSelfLoop: true });
+  });
+
+  it("never sets isBackEdge — discovery does not lay out", () => {
+    const graph = discoverGraph(generateSyntheticLog({ cases: 200, seed: 3 }));
+    expect(graph.transitions.every((edge) => edge.isBackEdge === false)).toBe(true);
+  });
+
+  it("counts a repeated edge once per case in caseCount but every time in count", () => {
+    const log: EventLog = {
+      events: [
+        { caseId: "c1", activity: "A", timestamp: 0 },
+        { caseId: "c1", activity: "B", timestamp: 1 },
+        { caseId: "c1", activity: "A", timestamp: 2 },
+        { caseId: "c1", activity: "B", timestamp: 3 },
+      ],
+    };
+    const edge = discoverGraph(log).transitions.find((e) => e.source === "A" && e.target === "B");
+    expect(edge).toMatchObject({ count: 2, caseCount: 1 });
+    const activity = discoverGraph(log).activities.find((a) => a.id === "A");
+    expect(activity).toMatchObject({ instances: 2, cases: 1 });
+  });
+
+  it("measures idle time by default and inter-start time on request", () => {
+    const log: EventLog = {
+      events: [
+        { caseId: "c1", activity: "A", startTimestamp: 0, timestamp: 1000 },
+        { caseId: "c1", activity: "B", startTimestamp: 5000, timestamp: 6000 },
+      ],
+    };
+    expect(discoverGraph(log).transitions[0]?.duration.sum).toBe(4000); // 5000 - 1000
+    expect(discoverGraph(log, { flowTime: "inter_start_time" }).transitions[0]?.duration.sum).toBe(
+      5000, // 5000 - 0
+    );
+  });
+
+  it("answers an empty log with an empty graph", () => {
+    expect(discoverGraph({ events: [] })).toEqual({
+      activities: [],
+      transitions: [],
+      startActivities: {},
+      endActivities: {},
+      totals: { cases: 0, events: 0, variants: 0 },
+    });
+  });
+
+  it("gives a single-event case a start, an end and no transition", () => {
+    const graph = discoverGraph({ events: [{ caseId: "c1", activity: "Only", timestamp: 0 }] });
+    expect(graph.transitions).toEqual([]);
+    expect(graph.activities[0]).toMatchObject({ id: "Only", isStart: true, isEnd: true });
+  });
+});
+
+describe("discoverGraph performance", () => {
+  it("discovers a 13 000-case synthetic log well inside the budget", () => {
+    const log = generateSyntheticLog({ cases: 13_000, seed: 1 });
+    // Warm the JIT so the measurement is of steady-state work, not of first-call
+    // compilation — otherwise the number swings by an order of magnitude on CI.
+    discoverGraph(generateSyntheticLog({ cases: 200, seed: 1 }));
+
+    const started = performance.now();
+    const graph = discoverGraph(log);
+    const elapsed = performance.now() - started;
+
+    expect(graph.totals.cases).toBe(13_000);
+    expect(graph.totals.events).toBeGreaterThan(100_000);
+    // The design budget is 300 ms; the assertion carries 5x headroom so a loaded CI
+    // runner cannot turn a real regression gate into a flaky wall-clock test.
+    expect(elapsed).toBeLessThan(1500);
+  });
+});

package/src/core/discover-graph.ts

@@ -0,0 +1,202 @@
+/**
+ * Directly-follows graph discovery — RM-049.
+ *
+ * The directly-follows abstraction (one node per activity, one edge per adjacent pair in
+ * a trace, with frequency and performance aggregates on both) is the standard starting
+ * point of every process-mining view. The shape of what a discovered graph carries —
+ * per-activity instance and case counts, per-edge count and case count, start/end
+ * activity tallies — follows pm4js; see `ATTRIBUTION.md`. No pm4js code is copied, and
+ * nothing here derives from the AGPL Python reference implementation.
+ *
+ * Deterministic and layout-free: `isBackEdge` is always `false` here, because whether an
+ * edge points backwards is a property of a LAYOUT, not of a log. A layout pass sets it.
+ */
+import { DURATION_SAMPLE_CAP, DurationSampler } from "./duration-stats";
+import { asNormalizedLog, type AnyLog, type NormalizedEvent } from "./event-log";
+import { VARIANT_KEY_SEPARATOR } from "./extract-variants";
+import type { ActivityStats, FlowTime, ProcessGraph, TransitionStats } from "./types";
+
+/**
+ * Separator used to key an edge. The same C0 control character the variant key uses, and
+ * for the same reason: no activity name can contain it, so `source + SEP + target` is an
+ * injective key.
+ */
+export const EDGE_KEY_SEPARATOR = VARIANT_KEY_SEPARATOR;
+
+/** Options for {@link discoverGraph}. Every field has a default; `discoverGraph(log)` works. */
+export interface DiscoverGraphOptions {
+  /**
+   * Which elapsed time an edge measures. Defaults to `"idle_time"` — the wait between the
+   * source completing and the target starting, which is the number a bottleneck view
+   * wants. For a log of atomic events the two choices coincide.
+   */
+  flowTime?: FlowTime;
+  /**
+   * Reservoir capacity per activity and per edge. Lower it for a very wide log; raise it
+   * for sharper tail statistics. `sum`/`mean`/`min`/`max` stay exact regardless.
+   */
+  maxDurationSamples?: number;
+}
+
+interface ActivityAccumulator {
+  instances: number;
+  cases: number;
+  duration: DurationSampler;
+}
+
+interface TransitionAccumulator {
+  source: string;
+  target: string;
+  count: number;
+  caseCount: number;
+  duration: DurationSampler;
+}
+
+/**
+ * Derive a {@link ProcessGraph} from a raw or already-normalized log.
+ *
+ * One pass per trace: each case's activity sequence is walked once, incrementing
+ * per-activity and per-edge counters and feeding two duration samplers. Per-case
+ * uniqueness (the `cases` and `caseCount` fields) is tracked with two `Set`s that are
+ * cleared per case rather than a per-key `Set` of case ids, so memory stays proportional
+ * to the widest trace, not to the log.
+ *
+ * `totals.variants` is counted from the same walk (the joined activity sequence goes into
+ * a `Set`), so a caller that only needs the headline number does not also have to run
+ * `extractVariants`.
+ */
+export function discoverGraph(log: AnyLog, options: DiscoverGraphOptions = {}): ProcessGraph {
+  const flowTime: FlowTime = options.flowTime ?? "idle_time";
+  const capacity = options.maxDurationSamples ?? DURATION_SAMPLE_CAP;
+  const normalized = asNormalizedLog(log);
+
+  const activities = new Map<string, ActivityAccumulator>();
+  const transitions = new Map<string, TransitionAccumulator>();
+  const startActivities = new Map<string, number>();
+  const endActivities = new Map<string, number>();
+  const variantKeys = new Set<string>();
+
+  // Sampler seeds come from a creation counter, never from a clock or from entropy: the
+  // iteration order over a given log is fixed, so the same log always seeds the same
+  // samplers and the reservoir retains the same rows.
+  let samplerIndex = 0;
+  const nextSeed = (): number => {
+    samplerIndex += 1;
+    return (0x9e3779b9 ^ Math.imul(samplerIndex, 0x9e3779b1)) >>> 0;
+  };
+
+  let events = 0;
+  const seenActivities = new Set<string>();
+  const seenEdges = new Set<string>();
+
+  for (const kase of normalized.cases) {
+    const trace = kase.events;
+    if (trace.length === 0) continue;
+    events += trace.length;
+    seenActivities.clear();
+    seenEdges.clear();
+
+    const sequence = new Array<string>(trace.length);
+
+    for (let i = 0; i < trace.length; i += 1) {
+      const event = trace[i] as NormalizedEvent;
+      const name = event.activity;
+      sequence[i] = name;
+
+      let activity = activities.get(name);
+      if (activity === undefined) {
+        activity = { instances: 0, cases: 0, duration: new DurationSampler(nextSeed(), capacity) };
+        activities.set(name, activity);
+      }
+      activity.instances += 1;
+      activity.duration.add(event.duration);
+      if (!seenActivities.has(name)) {
+        seenActivities.add(name);
+        activity.cases += 1;
+      }
+
+      if (i === 0) continue;
+      const previous = trace[i - 1] as NormalizedEvent;
+      const source = previous.activity;
+      const key = `${source}${EDGE_KEY_SEPARATOR}${name}`;
+      let edge = transitions.get(key);
+      if (edge === undefined) {
+        edge = {
+          source,
+          target: name,
+          count: 0,
+          caseCount: 0,
+          duration: new DurationSampler(nextSeed(), capacity),
+        };
+        transitions.set(key, edge);
+      }
+      edge.count += 1;
+      edge.duration.add(
+        flowTime === "inter_start_time" ? event.start - previous.start : event.start - previous.end,
+      );
+      if (!seenEdges.has(key)) {
+        seenEdges.add(key);
+        edge.caseCount += 1;
+      }
+    }
+
+    const first = trace[0] as NormalizedEvent;
+    const last = trace[trace.length - 1] as NormalizedEvent;
+    startActivities.set(first.activity, (startActivities.get(first.activity) ?? 0) + 1);
+    endActivities.set(last.activity, (endActivities.get(last.activity) ?? 0) + 1);
+    variantKeys.add(sequence.join(VARIANT_KEY_SEPARATOR));
+  }
+
+  const activityList: ActivityStats[] = [];
+  for (const [id, accumulator] of activities) {
+    activityList.push({
+      id,
+      label: id,
+      instances: accumulator.instances,
+      cases: accumulator.cases,
+      isStart: startActivities.has(id),
+      isEnd: endActivities.has(id),
+      duration: accumulator.duration.stats(),
+    });
+  }
+  // Deterministic, reader-friendly order: busiest first, ties broken by name, so the same
+  // log always yields the same array in the same positions (downstream items snapshot it).
+  activityList.sort((a, b) => b.instances - a.instances || compareStrings(a.id, b.id));
+
+  const transitionList: TransitionStats[] = [];
+  for (const accumulator of transitions.values()) {
+    transitionList.push({
+      source: accumulator.source,
+      target: accumulator.target,
+      count: accumulator.count,
+      caseCount: accumulator.caseCount,
+      duration: accumulator.duration.stats(),
+      isSelfLoop: accumulator.source === accumulator.target,
+      isBackEdge: false,
+    });
+  }
+  transitionList.sort(
+    (a, b) =>
+      b.count - a.count || compareStrings(a.source, b.source) || compareStrings(a.target, b.target),
+  );
+
+  return {
+    activities: activityList,
+    transitions: transitionList,
+    startActivities: toSortedRecord(startActivities),
+    endActivities: toSortedRecord(endActivities),
+    totals: { cases: normalized.cases.length, events, variants: variantKeys.size },
+  };
+}
+
+/** Code-unit comparison — locale-independent, so the order is the same on every machine. */
+function compareStrings(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** Key order is part of the output, so it is sorted rather than left to insertion order. */
+function toSortedRecord(counts: Map<string, number>): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const key of [...counts.keys()].sort()) out[key] = counts.get(key) as number;
+  return out;
+}

package/src/core/duration-stats.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  DURATION_SAMPLE_CAP,
+  DurationSampler,
+  durationStats,
+  emptyDurationStats,
+} from "./duration-stats";
+
+describe("durationStats", () => {
+  it("computes every member from a hand-checkable sample set", () => {
+    // 10 samples, 1000 apart: sum 55 000, mean 5500, median (5000 + 6000) / 2 = 5500,
+    // p90 at pos 0.9 * 9 = 8.1 → 9000 + 0.1 * 1000 = 9100, trim floor(10 * 0.1) = 1 each
+    // tail → mean of 2000…9000 = 5500.
+    const samples = [1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10_000];
+    expect(durationStats(samples)).toEqual({
+      min: 1000,
+      max: 10_000,
+      mean: 5500,
+      median: 5500,
+      p90: 9100,
+      sum: 55_000,
+      trimmedMean: 5500,
+    });
+  });
+
+  it("lets the trimmed mean diverge from the mean when the tails are extreme", () => {
+    const samples = [0, 10, 10, 10, 10, 10, 10, 10, 10, 1000];
+    const stats = durationStats(samples);
+    expect(stats.mean).toBe(108);
+    // One sample trimmed from each tail removes the 0 and the 1000.
+    expect(stats.trimmedMean).toBe(10);
+  });
+
+  it("degrades the trimmed mean to the plain mean when trimming would leave nothing", () => {
+    // n = 4 → floor(0.4) = 0 trimmed, so the two agree.
+    const stats = durationStats([1, 2, 3, 10]);
+    expect(stats.trimmedMean).toBe(stats.mean);
+    expect(stats.trimmedMean).toBe(4);
+  });
+
+  it("drops non-finite samples instead of poisoning every statistic", () => {
+    expect(durationStats([Number.NaN, 10, Number.POSITIVE_INFINITY, 30])).toMatchObject({
+      min: 10,
+      max: 30,
+      mean: 20,
+      sum: 40,
+    });
+  });
+
+  it("answers all zeros for an empty sample set", () => {
+    expect(durationStats([])).toEqual(emptyDurationStats());
+    expect(durationStats([Number.NaN])).toEqual(emptyDurationStats());
+  });
+
+  it("does not mutate the caller's array", () => {
+    const samples = [30, 10, 20];
+    durationStats(samples);
+    expect(samples).toEqual([30, 10, 20]);
+  });
+});
+
+describe("DurationSampler", () => {
+  it("keeps every sample below the cap", () => {
+    const sampler = new DurationSampler(1, 8);
+    for (const value of [4, 8, 15, 16, 23, 42]) sampler.add(value);
+    expect(sampler.size).toBe(6);
+    expect(sampler.stats()).toEqual(durationStats([4, 8, 15, 16, 23, 42]));
+  });
+
+  it("keeps sum, mean, min and max EXACT past the cap", () => {
+    const sampler = new DurationSampler(7, 16);
+    let expectedSum = 0;
+    for (let i = 1; i <= 5000; i += 1) {
+      sampler.add(i);
+      expectedSum += i;
+    }
+    const stats = sampler.stats();
+    expect(sampler.size).toBe(5000);
+    expect(stats.sum).toBe(expectedSum);
+    expect(stats.mean).toBe(expectedSum / 5000);
+    expect(stats.min).toBe(1);
+    expect(stats.max).toBe(5000);
+  });
+
+  it("is deterministic — the same seed and inputs give the same order statistics", () => {
+    const build = (): ReturnType<DurationSampler["stats"]> => {
+      const sampler = new DurationSampler(0x1234, 32);
+      for (let i = 0; i < 2000; i += 1) sampler.add((i * 37) % 991);
+      return sampler.stats();
+    };
+    expect(build()).toEqual(build());
+  });
+
+  it("estimates the median from the reservoir within a few percent of the truth", () => {
+    const sampler = new DurationSampler(99, 512);
+    const all: number[] = [];
+    for (let i = 0; i < 20_000; i += 1) {
+      sampler.add(i);
+      all.push(i);
+    }
+    const truth = durationStats(all).median;
+    expect(Math.abs(sampler.stats().median - truth) / truth).toBeLessThan(0.05);
+  });
+
+  it("ignores non-finite samples and reports zeros when nothing was collected", () => {
+    const sampler = new DurationSampler();
+    sampler.add(Number.NaN);
+    expect(sampler.size).toBe(0);
+    expect(sampler.stats()).toEqual(emptyDurationStats());
+  });
+
+  it("defaults to the documented cap", () => {
+    expect(DURATION_SAMPLE_CAP).toBe(4096);
+  });
+});