@elabs-ai/components-process 4.2.0 → 5.0.0

package/src/core/segments.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from "vitest";
+
+import { discoverGraph } from "./discover-graph";
+import { extractVariants } from "./extract-variants";
+import { generateSyntheticLog } from "./fixtures/synthetic-log";
+import {
+  durationQuartile,
+  durationQuartileThresholds,
+  quartileOf,
+  segmentKey,
+  segmentOrderByFrequency,
+  segmentOrderForVariant,
+  segmentsFor,
+  type SegmentDefinition,
+} from "./segments";
+import type { EventLog, EventRow } from "./types";
+
+const H = 3_600_000;
+
+/**
+ * Four cases through A → B → C → D. Waits (in hours) per segment:
+ *
+ * | case | A→B | B→C | C→D |
+ * | ---- | --- | --- | --- |
+ * | c1   | 1   | 8   | 2   |
+ * | c2   | 2   | 6   | 2   |
+ * | c3   | 3   | 4   | 2   |
+ * | c4   | 4   | 2   | 6   |
+ */
+function hourlyCase(caseId: string, offset: number, waits: [number, number, number]): EventRow[] {
+  const [ab, bc, cd] = waits;
+  const t0 = offset * H;
+  return [
+    { caseId, activity: "A", timestamp: t0 },
+    { caseId, activity: "B", timestamp: t0 + ab * H },
+    { caseId, activity: "C", timestamp: t0 + (ab + bc) * H },
+    { caseId, activity: "D", timestamp: t0 + (ab + bc + cd) * H },
+  ];
+}
+
+const LOG: EventLog = {
+  events: [
+    ...hourlyCase("c1", 0, [1, 8, 2]),
+    ...hourlyCase("c2", 1, [2, 6, 2]),
+    ...hourlyCase("c3", 2, [3, 4, 2]),
+    ...hourlyCase("c4", 3, [4, 2, 6]),
+  ],
+};
+
+const ORDER: SegmentDefinition[] = [
+  { from: "A", to: "B" },
+  { from: "B", to: "C" },
+  { from: "C", to: "D" },
+];
+
+describe("segmentsFor", () => {
+  const occurrences = segmentsFor(LOG, ORDER);
+
+  it("emits one occurrence per case per segment, in log then trace order", () => {
+    expect(occurrences).toHaveLength(12);
+    expect(occurrences.slice(0, 3).map((o) => [o.caseId, o.segment])).toEqual([
+      ["c1", segmentKey("A", "B")],
+      ["c1", segmentKey("B", "C")],
+      ["c1", segmentKey("C", "D")],
+    ]);
+    expect(occurrences[4]).toEqual({
+      segment: segmentKey("B", "C"),
+      caseId: "c2",
+      start: 3 * H,
+      end: 9 * H,
+      duration: 6 * H,
+    });
+  });
+
+  it("reproduces the hand-computed duration and quartile table", () => {
+    const table = ORDER.map((def) => {
+      const key = segmentKey(def.from, def.to);
+      const own = occurrences.filter((o) => o.segment === key);
+      const durations = own.map((o) => o.duration);
+      return own.map((o) => [o.caseId, o.duration / H, durationQuartile(o, durations)]);
+    });
+    expect(table).toEqual([
+      // A→B: 1,2,3,4 h → cuts 1.75 / 2.5 / 3.25
+      [
+        ["c1", 1, 1],
+        ["c2", 2, 2],
+        ["c3", 3, 3],
+        ["c4", 4, 4],
+      ],
+      // B→C: 8,6,4,2 h → cuts 3.5 / 5 / 6.5
+      [
+        ["c1", 8, 4],
+        ["c2", 6, 3],
+        ["c3", 4, 2],
+        ["c4", 2, 1],
+      ],
+      // C→D: 2,2,2,6 h → cuts 2 / 2 / 3 — ties land in the lowest quartile they reach
+      [
+        ["c1", 2, 1],
+        ["c2", 2, 1],
+        ["c3", 2, 1],
+        ["c4", 6, 4],
+      ],
+    ]);
+  });
+
+  it("skips pairs that are not in the order", () => {
+    const only = segmentsFor(LOG, [{ from: "B", to: "C" }]);
+    expect(only).toHaveLength(4);
+    expect(new Set(only.map((o) => o.segment))).toEqual(new Set([segmentKey("B", "C")]));
+    expect(segmentsFor(LOG, [{ from: "A", to: "C" }])).toEqual([]);
+    expect(segmentsFor(LOG, [])).toEqual([]);
+  });
+
+  it("ignores duplicate definitions and clamps an overlapping pair to zero duration", () => {
+    const overlapping: EventLog = {
+      events: [
+        { caseId: "x", activity: "A", startTimestamp: 0, timestamp: 10 },
+        { caseId: "x", activity: "B", startTimestamp: 5, timestamp: 20 },
+      ],
+    };
+    const out = segmentsFor(overlapping, [
+      { from: "A", to: "B" },
+      { from: "A", to: "B" },
+    ]);
+    expect(out).toEqual([
+      { segment: segmentKey("A", "B"), caseId: "x", start: 10, end: 10, duration: 0 },
+    ]);
+  });
+
+  it("is deterministic", () => {
+    const log = generateSyntheticLog({ cases: 50, seed: 3 });
+    const order = segmentOrderByFrequency(discoverGraph(log), 5);
+    expect(segmentsFor(log, order)).toEqual(segmentsFor(log, order));
+  });
+});
+
+describe("segmentOrderByFrequency", () => {
+  it("matches discoverGraph's own top-N transition ranking, order-stable", () => {
+    const log = generateSyntheticLog({ cases: 300, seed: 11 });
+    const graph = discoverGraph(log);
+    const top = segmentOrderByFrequency(graph, 6);
+    expect(top).toEqual(
+      graph.transitions.slice(0, 6).map((t) => ({ from: t.source, to: t.target })),
+    );
+    expect(segmentOrderByFrequency(discoverGraph(log), 6)).toEqual(top);
+  });
+
+  it("returns every transition without a limit, and none for a non-positive one", () => {
+    const graph = discoverGraph(LOG);
+    expect(segmentOrderByFrequency(graph)).toHaveLength(graph.transitions.length);
+    expect(segmentOrderByFrequency(graph, 0)).toEqual([]);
+  });
+});
+
+describe("segmentOrderForVariant", () => {
+  it("derives consecutive pairs from the variant sequence", () => {
+    const [variant] = extractVariants(LOG);
+    expect(segmentOrderForVariant(variant!)).toEqual(ORDER);
+  });
+
+  it("keeps a looped pair once, at its first position", () => {
+    const variant = { ...extractVariants(LOG)[0]!, sequence: ["A", "B", "A", "B", "C"] };
+    expect(segmentOrderForVariant(variant)).toEqual([
+      { from: "A", to: "B" },
+      { from: "B", to: "A" },
+      { from: "B", to: "C" },
+    ]);
+  });
+});
+
+describe("durationQuartileThresholds / quartileOf", () => {
+  it("answers zeros for an empty or all-non-finite sample", () => {
+    expect(durationQuartileThresholds([])).toEqual([0, 0, 0]);
+    expect(durationQuartileThresholds([Number.NaN])).toEqual([0, 0, 0]);
+  });
+
+  it("buckets with inclusive upper bounds", () => {
+    const cuts = durationQuartileThresholds([10, 20, 30, 40]);
+    expect(cuts).toEqual([17.5, 25, 32.5]);
+    expect([10, 17.5, 20, 25, 30, 32.5, 40].map((d) => quartileOf(d, cuts))).toEqual([
+      1, 1, 2, 2, 3, 3, 4,
+    ]);
+  });
+});

package/src/core/segments.ts

@@ -0,0 +1,153 @@
+/**
+ * Segment occurrences — RM-060.
+ *
+ * A performance spectrum (ProM's PSM) draws one line per case through a FIXED, chosen
+ * sequence of segments, where a segment is one directly-follows pair `from → to`. That
+ * needs something `TransitionStats` does not carry: the individual, time-ordered
+ * OCCURRENCES of a pair (which case, when it entered, when it left), not one aggregate
+ * across the whole log. Batching, FIFO violations and queue build-up are visible only
+ * in the occurrences.
+ *
+ * ## What an occurrence measures
+ *
+ * `start` is the moment the `from` event COMPLETES and `end` the moment the `to` event
+ * STARTS — the same idle-time reading `discoverGraph` defaults to, so a spectrum row and
+ * the map's edge median agree about one pair. For atomic events (the common case) start
+ * and completion coincide, so this is simply the two event timestamps. Overlapping
+ * (parallel) events would give `end < start`; `end` is clamped to `start`, so `duration`
+ * is never negative and a line never runs backwards.
+ *
+ * Deterministic and framework-free: no React, no `@elabs-ai/components-*`.
+ */
+
+import { EDGE_KEY_SEPARATOR } from "./discover-graph";
+import { asNormalizedLog, type AnyLog, type NormalizedEvent } from "./event-log";
+import { ascending, quantileSorted } from "./scale";
+import type { ProcessGraph, Variant } from "./types";
+
+/** One row of a spectrum: the directly-follows pair `from → to`. */
+export interface SegmentDefinition {
+  from: string;
+  to: string;
+  /** Display label. Defaults to `"from → to"` in a view. */
+  label?: string;
+}
+
+/** One case passing through one segment. */
+export interface SegmentOccurrence {
+  /** The segment's key — {@link segmentKey}`(from, to)`. */
+  segment: string;
+  caseId: string;
+  /** When the `from` event completed, epoch ms. */
+  start: number;
+  /** When the `to` event started, epoch ms. Never before `start`. */
+  end: number;
+  /** `end - start`, in ms. */
+  duration: number;
+}
+
+/** A duration quartile, `1` = fastest quarter, `4` = slowest. */
+export type DurationQuartile = 1 | 2 | 3 | 4;
+
+/** The three cut points (25th, 50th, 75th percentile) a quartile is read against. */
+export type QuartileThresholds = readonly [number, number, number];
+
+/**
+ * The key of a segment — the same `source + separator + target` edge key `discoverGraph`
+ * and `ProcessMap` use, so a segment round-trips to a transition selection unchanged.
+ */
+export function segmentKey(from: string, to: string): string {
+  return `${from}${EDGE_KEY_SEPARATOR}${to}`;
+}
+
+/**
+ * Every occurrence of the segments in `order`, walking each case's normalised sequence
+ * once. Pairs not in `order` are skipped — a spectrum shows a chosen sequence, never the
+ * whole graph. Output is in log order: case by case, and within a case in trace order.
+ * Duplicate definitions in `order` are ignored.
+ */
+export function segmentsFor(log: AnyLog, order: readonly SegmentDefinition[]): SegmentOccurrence[] {
+  const wanted = new Set<string>();
+  for (const def of order) wanted.add(segmentKey(def.from, def.to));
+  const out: SegmentOccurrence[] = [];
+  if (wanted.size === 0) return out;
+
+  for (const kase of asNormalizedLog(log).cases) {
+    const trace = kase.events;
+    for (let i = 1; i < trace.length; i += 1) {
+      const previous = trace[i - 1] as NormalizedEvent;
+      const event = trace[i] as NormalizedEvent;
+      const key = segmentKey(previous.activity, event.activity);
+      if (!wanted.has(key)) continue;
+      const start = previous.end;
+      if (!Number.isFinite(start) || !Number.isFinite(event.start)) continue;
+      const end = Math.max(start, event.start);
+      out.push({ segment: key, caseId: kase.caseId, start, end, duration: end - start });
+    }
+  }
+  return out;
+}
+
+/**
+ * The `limit` most frequent directly-follows pairs of `graph`, busiest first. Reads
+ * `graph.transitions` in the order `discoverGraph` already ranks them (count descending,
+ * ties by source then target), so the two can never disagree about "the top N".
+ */
+export function segmentOrderByFrequency(
+  graph: ProcessGraph,
+  limit: number = Number.POSITIVE_INFINITY,
+): SegmentDefinition[] {
+  const n = Math.max(0, Math.floor(limit));
+  return graph.transitions.slice(0, n).map((t) => ({ from: t.source, to: t.target }));
+}
+
+/**
+ * The consecutive pairs of `variant.sequence`, in path order. A pair repeated by a loop
+ * (`A, B, A, B`) appears once, at its first position — a spectrum has one row per segment.
+ */
+export function segmentOrderForVariant(variant: Variant): SegmentDefinition[] {
+  const seen = new Set<string>();
+  const out: SegmentDefinition[] = [];
+  for (let i = 1; i < variant.sequence.length; i += 1) {
+    const from = variant.sequence[i - 1] as string;
+    const to = variant.sequence[i] as string;
+    const key = segmentKey(from, to);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ from, to });
+  }
+  return out;
+}
+
+/**
+ * The 25th/50th/75th percentile of `durations` (R-7 interpolation, the same `quantile`
+ * every process view uses). Non-finite samples are dropped; an empty input gives zeros.
+ * Compute this ONCE per segment and read many occurrences against it with
+ * {@link quartileOf} — {@link durationQuartile} sorts on every call.
+ */
+export function durationQuartileThresholds(durations: readonly number[]): QuartileThresholds {
+  const sorted: number[] = [];
+  for (const d of durations) if (Number.isFinite(d)) sorted.push(d);
+  sorted.sort(ascending);
+  if (sorted.length === 0) return [0, 0, 0];
+  return [quantileSorted(sorted, 0.25), quantileSorted(sorted, 0.5), quantileSorted(sorted, 0.75)];
+}
+
+/** Which quartile `duration` falls in, against precomputed thresholds (upper bounds inclusive). */
+export function quartileOf(duration: number, thresholds: QuartileThresholds): DurationQuartile {
+  if (duration <= thresholds[0]) return 1;
+  if (duration <= thresholds[1]) return 2;
+  if (duration <= thresholds[2]) return 3;
+  return 4;
+}
+
+/**
+ * Buckets `occurrence` against ITS OWN segment's duration distribution — not the whole
+ * log's — which is PSM's colour convention: a slow line is slow for that segment.
+ */
+export function durationQuartile(
+  occurrence: SegmentOccurrence,
+  allDurationsForSegment: readonly number[],
+): DurationQuartile {
+  return quartileOf(occurrence.duration, durationQuartileThresholds(allDurationsForSegment));
+}

package/src/core/token-replay.test.ts

@@ -0,0 +1,218 @@
+import { describe, expect, it } from "vitest";
+
+import { EDGE_KEY_SEPARATOR } from "./discover-graph";
+import { liftHappyPath, type HappyPath } from "./reference-model";
+import {
+  DEVIATION_TYPES,
+  replayActivities,
+  replayTrace,
+  tokenReplay,
+  type Deviation,
+} from "./token-replay";
+import type { EventLog, EventRow } from "./types";
+
+/** A → B (optional) → C (repeatable) → D → E. */
+const HAPPY: HappyPath = {
+  id: "o2c",
+  label: "Order to cash",
+  steps: [
+    { activity: "A" },
+    { activity: "B", optional: true },
+    { activity: "C", repeatable: true },
+    { activity: "D" },
+    { activity: "E" },
+  ],
+};
+const model = liftHappyPath(HAPPY);
+
+const T0 = Date.UTC(2026, 0, 5);
+
+function rows(caseId: string, trace: string[], start = T0): EventRow[] {
+  return trace.map((activity, i) => ({ caseId, activity, timestamp: start + i * 60_000 }));
+}
+
+/**
+ * Hand-computed. `produced` counts the initial token plus one per output of every fired
+ * transition (skip arcs included); `consumed` counts one per input of every fired
+ * transition plus the final token.
+ */
+const TABLE: {
+  name: string;
+  trace: string[];
+  counts: { produced: number; consumed: number; missing: number; remaining: number };
+  fitness: number;
+  deviations: Deviation[];
+}[] = [
+  {
+    name: "perfect match",
+    trace: ["A", "B", "C", "D", "E"],
+    counts: { produced: 6, consumed: 6, missing: 0, remaining: 0 },
+    fitness: 1,
+    deviations: [],
+  },
+  {
+    name: "skips the optional step",
+    trace: ["A", "C", "D", "E"],
+    // The silent skip arc fires: +1 produced, +1 consumed, no penalty.
+    counts: { produced: 6, consumed: 6, missing: 0, remaining: 0 },
+    fitness: 1,
+    deviations: [],
+  },
+  {
+    name: "repeats the repeatable step",
+    trace: ["A", "B", "C", "C", "D", "E"],
+    counts: { produced: 7, consumed: 7, missing: 0, remaining: 0 },
+    fitness: 1,
+    deviations: [],
+  },
+  {
+    name: "skips a required step",
+    trace: ["A", "B", "C", "E"],
+    // E forces a token into p4; the token left in p3 remains. ½(1−1/5) + ½(1−1/5).
+    counts: { produced: 5, consumed: 5, missing: 1, remaining: 1 },
+    fitness: 0.8,
+    deviations: [{ type: "skipped", activity: "D", expected: "D", at: 3 }],
+  },
+  {
+    name: "wrong order",
+    trace: ["A", "B", "D", "C", "E"],
+    // D forces p3 (C is observed later, so it is not "skipped"); C then leaves p3 over.
+    // ½(1−1/6) + ½(1−1/6).
+    counts: { produced: 6, consumed: 6, missing: 1, remaining: 1 },
+    fitness: 5 / 6,
+    deviations: [{ type: "wrongOrder", activity: "D", expected: "C", at: 2 }],
+  },
+  {
+    name: "undesired activity",
+    trace: ["A", "B", "X", "C", "D", "E"],
+    // X is a phantom firing consuming one forced token. ½(1−1/7) + ½(1−0/6).
+    counts: { produced: 6, consumed: 7, missing: 1, remaining: 0 },
+    fitness: 13 / 14,
+    deviations: [{ type: "undesired", activity: "X", expected: "C", at: 2 }],
+  },
+  {
+    name: "incomplete",
+    trace: ["A", "B", "C"],
+    // Final place p5 never marked; p3 left over. ½(1−1/4) + ½(1−1/4).
+    counts: { produced: 4, consumed: 4, missing: 1, remaining: 1 },
+    fitness: 0.75,
+    deviations: [{ type: "incomplete", activity: "C", expected: "D", at: 3 }],
+  },
+  {
+    name: "wrong start",
+    trace: ["B", "C", "D", "E"],
+    // B forces p1; the initial token in p0 remains. ½(1−1/5) + ½(1−1/5).
+    counts: { produced: 5, consumed: 5, missing: 1, remaining: 1 },
+    fitness: 0.8,
+    deviations: [{ type: "wrongStart", activity: "B", expected: "A", at: 0 }],
+  },
+];
+
+describe("replayTrace — hand-verified table", () => {
+  it.each(TABLE)("$name", ({ trace, counts, fitness, deviations }) => {
+    const result = replayTrace(rows("c", trace), model);
+    expect(result.caseId).toBe("c");
+    expect({
+      produced: result.produced,
+      consumed: result.consumed,
+      missing: result.missing,
+      remaining: result.remaining,
+    }).toEqual(counts);
+    expect(result.fitness).toBeCloseTo(fitness, 12);
+    expect(result.deviations).toEqual(deviations);
+  });
+});
+
+describe("replayTrace — input handling", () => {
+  it("orders rows in time and merges lifecycle pairs before replaying", () => {
+    const events: EventRow[] = [
+      { caseId: "c", activity: "E", timestamp: T0 + 9 },
+      { caseId: "c", activity: "B", timestamp: T0 + 3, lifecycle: "complete" },
+      { caseId: "c", activity: "A", timestamp: T0 + 1 },
+      { caseId: "c", activity: "B", timestamp: T0 + 2, lifecycle: "start" },
+      { caseId: "c", activity: "D", timestamp: T0 + 8 },
+      { caseId: "c", activity: "C", timestamp: T0 + 5 },
+    ];
+    const result = replayTrace(events, model);
+    expect(result.fitness).toBe(1);
+    expect(result.deviations).toEqual([]);
+  });
+
+  it("scores an empty trace as incomplete, never NaN", () => {
+    const result = replayActivities("empty", [], model);
+    expect(result.deviations).toEqual([{ type: "incomplete", expected: "A", at: 0 }]);
+    expect(result.fitness).toBe(0);
+  });
+
+  it("does not report an optional tail step as incomplete", () => {
+    const tail = liftHappyPath({
+      id: "t",
+      label: "Tail",
+      steps: [{ activity: "A" }, { activity: "Z", optional: true }],
+    });
+    const result = replayActivities("c", ["A"], tail);
+    expect(result.deviations).toEqual([]);
+    expect(result.fitness).toBe(1);
+  });
+});
+
+describe("tokenReplay", () => {
+  const log: EventLog = {
+    events: TABLE.flatMap(({ trace }, i) => rows(`case-${i}`, trace, T0 + i * 86_400_000)),
+  };
+  const result = tokenReplay(log, model);
+  const allDeviations = result.traces.flatMap((t) => t.deviations);
+
+  it("replays every case in log order", () => {
+    expect(result.traces.map((t) => t.caseId)).toEqual(TABLE.map((_, i) => `case-${i}`));
+    TABLE.forEach((row, i) => {
+      expect(result.traces[i]?.fitness).toBeCloseTo(row.fitness, 12);
+    });
+  });
+
+  it("reports overall fitness as the mean trace fitness", () => {
+    const mean = TABLE.reduce((sum, row) => sum + row.fitness, 0) / TABLE.length;
+    expect(result.overallFitness).toBeCloseTo(mean, 12);
+  });
+
+  it("keeps tallies non-negative and consistent with deviationCounts", () => {
+    expect(Object.keys(result.deviationCounts).sort()).toEqual([...DEVIATION_TYPES].sort());
+    expect(result.deviationCounts).toEqual({
+      undesired: 1,
+      skipped: 1,
+      wrongOrder: 1,
+      wrongStart: 1,
+      incomplete: 1,
+    });
+    const total = Object.values(result.deviationCounts).reduce((a, b) => a + b, 0);
+    expect(total).toBe(allDeviations.length);
+
+    const perActivity = Object.values(result.perActivity).map((v) => v.deviations);
+    const perEdge = Object.values(result.perEdge).map((v) => v.deviations);
+    for (const n of [...perActivity, ...perEdge]) expect(n).toBeGreaterThan(0);
+    expect(perActivity.reduce((a, b) => a + b, 0)).toBe(total);
+    expect(perEdge.reduce((a, b) => a + b, 0)).toBeLessThanOrEqual(total);
+  });
+
+  it("charges a deviation to the observed edge into the deviating event", () => {
+    const edge = (from: string, to: string) => `${from}${EDGE_KEY_SEPARATOR}${to}`;
+    expect({ ...result.perEdge }).toEqual({
+      [edge("C", "E")]: { deviations: 1 },
+      [edge("B", "D")]: { deviations: 1 },
+      [edge("B", "X")]: { deviations: 1 },
+    });
+    expect({ ...result.perActivity }).toEqual({
+      D: { deviations: 2 },
+      X: { deviations: 1 },
+      C: { deviations: 1 },
+      B: { deviations: 1 },
+    });
+  });
+
+  it("returns zero fitness and zeroed counts for an empty log", () => {
+    const empty = tokenReplay({ events: [] }, model);
+    expect(empty.overallFitness).toBe(0);
+    expect(empty.traces).toEqual([]);
+    expect(Object.values(empty.deviationCounts).every((n) => n === 0)).toBe(true);
+  });
+});