@elabs-ai/components-process 4.1.0 → 5.0.0

package/src/core/reference-model.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+
+import { liftHappyPath } from "./reference-model";
+
+describe("liftHappyPath", () => {
+  it("lifts a plain sequence to one place between consecutive steps", () => {
+    const model = liftHappyPath({
+      id: "p",
+      label: "Plain",
+      steps: [{ activity: "A" }, { activity: "B" }],
+    });
+    expect(model.places).toEqual(["p0", "p1", "p2"]);
+    expect(model.initialMarking).toEqual(["p0"]);
+    expect(model.finalMarking).toEqual(["p2"]);
+    expect(model.transitions).toEqual([
+      { id: "t0", activity: "A", kind: "step", consumes: ["p0"], produces: ["p1"] },
+      { id: "t1", activity: "B", kind: "step", consumes: ["p1"], produces: ["p2"] },
+    ]);
+  });
+
+  it("adds a silent skip arc for an optional step and a self-loop for a repeatable one", () => {
+    const model = liftHappyPath({
+      id: "p",
+      label: "Flags",
+      steps: [{ activity: "A", optional: true, repeatable: true }],
+    });
+    expect(model.transitions).toEqual([
+      { id: "t0", activity: "A", kind: "step", consumes: ["p0"], produces: ["p1"] },
+      { id: "skip0", activity: "A", kind: "skip", consumes: ["p0"], produces: ["p1"] },
+      { id: "repeat0", activity: "A", kind: "repeat", consumes: ["p1"], produces: ["p1"] },
+    ]);
+  });
+
+  it("lifts an empty path to a single place that is both initial and final", () => {
+    const model = liftHappyPath({ id: "e", label: "Empty", steps: [] });
+    expect(model).toEqual({
+      places: ["p0"],
+      initialMarking: ["p0"],
+      finalMarking: ["p0"],
+      transitions: [],
+    });
+  });
+});

package/src/core/reference-model.ts

@@ -0,0 +1,116 @@
+/**
+ * Reference model — RM-061.
+ *
+ * A HAPPY PATH (the prescribed sequence of activities an owner or auditor expects) lifted
+ * to the smallest workflow-net-like structure token replay can run against: one place
+ * between consecutive steps, one visible transition per step, a silent SKIP transition
+ * beside every optional step and a SELF-LOOP transition after every repeatable one.
+ *
+ * Scope boundary (analysis §9 risk 2): this is deliberately NOT a general Petri-net
+ * importer. No BPMN, no parallel gateways, no alignments beyond skip/repeat. A host that
+ * needs full alignment-based conformance brings a backend; this module never grows one.
+ *
+ * Framework-free, deterministic: no React, no `@elabs-ai/components-*` import.
+ */
+
+/** One prescribed step of a happy path. */
+export interface HappyPathStep {
+  /** Activity name, matched exactly against `EventRow.activity`. */
+  activity: string;
+  /** The step may be left out without a deviation (a silent skip arc is added). */
+  optional?: boolean;
+  /** The step may run several times in a row without a deviation (a self-loop is added). */
+  repeatable?: boolean;
+}
+
+/** A prescribed process: an ordered list of steps. */
+export interface HappyPath {
+  id: string;
+  label: string;
+  steps: HappyPathStep[];
+}
+
+/**
+ * What a transition stands for. `"step"` fires a step's activity for the first time,
+ * `"repeat"` fires it again from the place after it, `"skip"` is SILENT (no activity is
+ * observed) and moves the token past an optional step.
+ */
+export type ReplayTransitionKind = "step" | "skip" | "repeat";
+
+/** One transition of a {@link ReplayModel}. */
+export interface ReplayTransition {
+  id: string;
+  /** The activity this transition fires on. The skipped step's activity for a `"skip"`. */
+  activity: string;
+  kind: ReplayTransitionKind;
+  /** Input places — one token each is consumed when the transition fires. */
+  consumes: string[];
+  /** Output places — one token each is produced when the transition fires. */
+  produces: string[];
+}
+
+/** A workflow-net-like replay structure. Places are listed in path order. */
+export interface ReplayModel {
+  places: string[];
+  initialMarking: string[];
+  finalMarking: string[];
+  transitions: ReplayTransition[];
+}
+
+/** Name of the place before step `index` (and after step `index - 1`). */
+function placeName(index: number): string {
+  return `p${index}`;
+}
+
+/**
+ * Lift a happy path to a {@link ReplayModel}.
+ *
+ * For `n` steps the model has places `p0 … pn`, starts with one token in `p0` and ends
+ * with one token in `pn`. Step `i` gets transition `t<i>` (`p<i>` → `p<i+1>`); an optional
+ * step also gets a silent `skip<i>` over the same places; a repeatable step also gets
+ * `repeat<i>` consuming and producing `p<i+1>`. An empty path lifts to a single place
+ * that is both initial and final.
+ */
+export function liftHappyPath(path: HappyPath): ReplayModel {
+  const steps = path.steps;
+  const places: string[] = [];
+  for (let i = 0; i <= steps.length; i += 1) places.push(placeName(i));
+
+  const transitions: ReplayTransition[] = [];
+  steps.forEach((step, i) => {
+    const before = placeName(i);
+    const after = placeName(i + 1);
+    transitions.push({
+      id: `t${i}`,
+      activity: step.activity,
+      kind: "step",
+      consumes: [before],
+      produces: [after],
+    });
+    if (step.optional) {
+      transitions.push({
+        id: `skip${i}`,
+        activity: step.activity,
+        kind: "skip",
+        consumes: [before],
+        produces: [after],
+      });
+    }
+    if (step.repeatable) {
+      transitions.push({
+        id: `repeat${i}`,
+        activity: step.activity,
+        kind: "repeat",
+        consumes: [after],
+        produces: [after],
+      });
+    }
+  });
+
+  return {
+    places,
+    initialMarking: [placeName(0)],
+    finalMarking: [placeName(steps.length)],
+    transitions,
+  };
+}

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

@@ -0,0 +1,161 @@
+import { describe, expect, it } from "vitest";
+
+import { EDGE_KEY_SEPARATOR } from "./discover-graph";
+import fixture from "./fixtures/order-to-cash-small.json";
+import {
+  REPLAY_MAX_FRAMES,
+  REPLAY_TOKEN_RADIUS_RANGE,
+  rankReplayCongestion,
+  replayFrameAt,
+  replayTimeline,
+  replayTokenRadius,
+} from "./replay-timeline";
+import type { EventLog } from "./types";
+
+const log = fixture as EventLog;
+const HOUR = 3_600_000;
+const edge = (source: string, target: string) => `${source}${EDGE_KEY_SEPARATOR}${target}`;
+
+/**
+ * The five traces of `order-to-cash-small.json`, as hours after each case's own start
+ * (every event is atomic, so an edge runs from one event to the next):
+ *
+ *   case-1  CO 0 · CC 1 · AO 2 · SO 3 · SI 4 · RP 5
+ *   case-2  CO 0 · CC 1 · AO 2 · SO 3 · SI 4 · RP 5
+ *   case-3  CO 0 · CC 1 · RO 2
+ *   case-4  CO 0 · CC 1 · AmO 2 · CC 3 · AO 4 · SO 5 · SI 6 · RP 7
+ *   case-5  CO 0 · CC 2 · AO 4 · SI 6 · SO 8 · RP 10
+ *
+ * A case is in flight at hour h when one of its edges spans [enter, exit) and contains h.
+ * Counted by hand from the five lines above:
+ *
+ *   h        0  1  2  3  4  5  6  7  8  9  10
+ *   c1       1  1  1  1  1  -  -  -  -  -  -
+ *   c2       1  1  1  1  1  -  -  -  -  -  -
+ *   c3       1  1  -  -  -  -  -  -  -  -  -
+ *   c4       1  1  1  1  1  1  1  -  -  -  -
+ *   c5       1  1  1  1  1  1  1  1  1  1  -
+ *   tokens   5  5  4  4  4  2  2  1  1  1  0
+ */
+const SYNCHRONIZED_TOKENS_PER_HOUR = [5, 5, 4, 4, 4, 2, 2, 1, 1, 1, 0];
+
+describe("replayTimeline — synchronized start", () => {
+  const timeline = replayTimeline(log, { bucketMs: HOUR, synchronizedStart: true });
+
+  it("aligns all five cases' first activity to t = 0", () => {
+    expect(timeline.origin).toBe(0);
+    const firstMoves = new Map<string, number>();
+    for (const s of timeline.segments) {
+      if (!firstMoves.has(s.caseId)) firstMoves.set(s.caseId, s.enterAt);
+    }
+    expect([...firstMoves.keys()].sort()).toEqual([
+      "case-1",
+      "case-2",
+      "case-3",
+      "case-4",
+      "case-5",
+    ]);
+    expect([...firstMoves.values()]).toEqual([0, 0, 0, 0, 0]);
+    expect(timeline.frames[0]!.tokens.map((token) => token.edgeId)).toEqual(
+      Array(5).fill(edge("Create Order", "Check Credit")),
+    );
+  });
+
+  it("matches the hand-computed token count per bucket", () => {
+    expect(timeline.duration).toBe(10 * HOUR);
+    expect(timeline.frames.map((frame) => frame.t)).toEqual(
+      SYNCHRONIZED_TOKENS_PER_HOUR.map((_, h) => h * HOUR),
+    );
+    expect(timeline.frames.map((frame) => frame.tokens.length)).toEqual(
+      SYNCHRONIZED_TOKENS_PER_HOUR,
+    );
+  });
+
+  it("counts distinct cases per edge per bucket as congestion", () => {
+    expect(timeline.frames[0]!.congestion).toEqual({ [edge("Create Order", "Check Credit")]: 5 });
+    // Hour 1: case-5 is still on its first edge; the rest have moved on.
+    expect(timeline.frames[1]!.congestion).toEqual({
+      [edge("Create Order", "Check Credit")]: 1,
+      [edge("Check Credit", "Approve Order")]: 2,
+      [edge("Check Credit", "Reject Order")]: 1,
+      [edge("Check Credit", "Amend Order")]: 1,
+    });
+    expect(timeline.peakCongestion).toBe(5);
+  });
+
+  it("ranks the busiest transition first", () => {
+    const ranked = rankReplayCongestion(timeline, 3);
+    expect(ranked).toHaveLength(3);
+    expect(ranked[0]).toMatchObject({
+      edgeId: edge("Create Order", "Check Credit"),
+      source: "Create Order",
+      target: "Check Credit",
+      peak: 5,
+      peakAt: 0,
+    });
+  });
+});
+
+describe("replayTimeline — wall clock", () => {
+  const timeline = replayTimeline(log, { bucketMs: HOUR });
+
+  it("starts at the earliest event and runs to the latest", () => {
+    expect(timeline.origin).toBe(Date.parse("2026-01-05T09:00:00.000Z"));
+    // 2026-01-05T09:00 to 2026-01-09T19:00.
+    expect(timeline.duration).toBe(106 * HOUR);
+    expect(timeline.frames).toHaveLength(107);
+  });
+
+  it("never has more than one case in flight — each starts on its own day", () => {
+    expect(Math.max(...timeline.frames.map((frame) => frame.tokens.length))).toBe(1);
+    expect(timeline.frames[24]!.tokens).toEqual([
+      { caseId: "case-2", edgeId: edge("Create Order", "Check Credit"), progress: 0 },
+    ]);
+  });
+});
+
+describe("replayFrameAt", () => {
+  const timeline = replayTimeline(log, { bucketMs: HOUR, synchronizedStart: true });
+
+  it("interpolates progress between buckets and reads the containing bucket's congestion", () => {
+    const frame = replayFrameAt(timeline, 1.5 * HOUR);
+    expect(frame.tokens.find((token) => token.caseId === "case-5")).toEqual({
+      caseId: "case-5",
+      edgeId: edge("Create Order", "Check Credit"),
+      progress: 0.75,
+    });
+    expect(frame.congestion).toEqual(timeline.frames[1]!.congestion);
+  });
+
+  it("clamps the playhead", () => {
+    expect(replayFrameAt(timeline, -5).t).toBe(0);
+    expect(replayFrameAt(timeline, 99 * HOUR).t).toBe(10 * HOUR);
+    expect(replayFrameAt(timeline, Number.NaN).t).toBe(0);
+  });
+});
+
+describe("edge cases", () => {
+  it("answers one empty frame for an empty log", () => {
+    const timeline = replayTimeline({ events: [] });
+    expect(timeline.duration).toBe(0);
+    expect(timeline.frames).toEqual([{ t: 0, tokens: [], congestion: {} }]);
+    expect(rankReplayCongestion(timeline)).toEqual([]);
+  });
+
+  it("widens a bucket that would exceed the frame cap", () => {
+    const timeline = replayTimeline(log, { bucketMs: 1 });
+    expect(timeline.frames.length).toBeLessThanOrEqual(REPLAY_MAX_FRAMES);
+  });
+
+  it("defaults to about 300 frames", () => {
+    expect(replayTimeline(log).frames.length).toBe(301);
+  });
+
+  it("scales token radius by area within the range", () => {
+    const [min, max] = REPLAY_TOKEN_RADIUS_RANGE;
+    expect(replayTokenRadius(0, 5)).toBe(min);
+    expect(replayTokenRadius(5, 5)).toBe(max);
+    expect(replayTokenRadius(1, 4)).toBeCloseTo(min + (max - min) * 0.5);
+    expect(replayTokenRadius(3, 0)).toBe(min);
+  });
+});

package/src/core/replay-timeline.ts

@@ -0,0 +1,260 @@
+/**
+ * replayTimeline — the timing model behind `ProcessReplay` (RM-065).
+ *
+ * Pure, deterministic, framework-free: no DOM, no clock, no randomness. It turns a log into
+ * the moves each case makes along the directly-follows edges of its trace, then answers two
+ * questions for any playhead `t`:
+ *
+ * - **Where is every in-flight case?** A token per case on the edge it is travelling, with
+ *   `progress` 0..1 from the source activity's completion to the target activity's start
+ *   (the idle time the edge measures). {@link replayFrameAt}.
+ * - **How congested is each edge?** The number of distinct cases on it at any moment of the
+ *   current bucket (`bucketMs` wide). {@link ReplayFrame.congestion}.
+ *
+ * Edge ids are `/core`'s `source + EDGE_KEY_SEPARATOR + target` — the same string
+ * `discoverGraph`'s transitions and the process map's React Flow edges use.
+ *
+ * Time is RELATIVE to the timeline's `origin`: `t = 0` is the earliest event in wall-clock
+ * mode, or each case's own first activity in `synchronizedStart` mode (Disco's
+ * "synchronized start"), where `origin` is `0` and absolute timestamps are meaningless.
+ */
+import { EDGE_KEY_SEPARATOR } from "./discover-graph";
+import { asNormalizedLog, type AnyLog } from "./event-log";
+
+/** One case travelling one edge. Times are relative to {@link ReplayTimeline.origin}. */
+export interface ReplaySegment {
+  caseId: string;
+  /** `source + EDGE_KEY_SEPARATOR + target`. */
+  edgeId: string;
+  source: string;
+  target: string;
+  /** The source activity's completion. */
+  enterAt: number;
+  /** The target activity's start — never before {@link enterAt}. */
+  exitAt: number;
+}
+
+/** One case's token on one edge at a playhead. */
+export interface ReplayFrameToken {
+  caseId: string;
+  edgeId: string;
+  /** 0 at the source end, 1 at the target end. */
+  progress: number;
+}
+
+/** The replay at one playhead. */
+export interface ReplayFrame {
+  /** Playhead, relative to the timeline origin. */
+  t: number;
+  /** One token per in-flight case, in segment order. */
+  tokens: ReplayFrameToken[];
+  /** Edge id → distinct cases on that edge during the bucket starting at `t`. Zero edges are omitted. */
+  congestion: Record<string, number>;
+}
+
+/** Options for {@link replayTimeline}. */
+export interface ReplayTimelineOptions {
+  /** Bucket width in ms. Defaults to {@link defaultReplayBucketMs}. Raised when it would exceed {@link REPLAY_MAX_FRAMES}. */
+  bucketMs?: number;
+  /** Align every case's first activity to `t = 0`. @default false */
+  synchronizedStart?: boolean;
+}
+
+/** A replay-ready timeline. */
+export interface ReplayTimeline {
+  /** Epoch ms of `t = 0` in wall-clock mode; `0` in synchronized-start mode. */
+  origin: number;
+  /** Last relative instant any case reaches. `0` for an empty log. */
+  duration: number;
+  /** The bucket width actually used. */
+  bucketMs: number;
+  synchronizedStart: boolean;
+  /** Every edge move of every case, ordered by `enterAt` then case order. */
+  segments: ReplaySegment[];
+  /** One frame per bucket, `frames[i].t === i * bucketMs`, covering `[0, duration]`. */
+  frames: ReplayFrame[];
+  /** Highest congestion any edge reaches in any bucket. `0` when nothing moves. */
+  peakCongestion: number;
+}
+
+/** How many frames {@link defaultReplayBucketMs} aims for. */
+export const REPLAY_TARGET_FRAMES = 300;
+/** Upper bound on frames; a finer `bucketMs` is widened to respect it. */
+export const REPLAY_MAX_FRAMES = 5000;
+
+/** The default bucket: the log span over {@link REPLAY_TARGET_FRAMES}, at least 1 ms. */
+export function defaultReplayBucketMs(duration: number): number {
+  if (!Number.isFinite(duration) || duration <= 0) return 1;
+  return Math.max(1, duration / REPLAY_TARGET_FRAMES);
+}
+
+/** Every case's edge moves, relative to the chosen origin. */
+function buildSegments(
+  log: AnyLog,
+  synchronizedStart: boolean,
+): { origin: number; duration: number; segments: ReplaySegment[] } {
+  const { cases } = asNormalizedLog(log);
+  if (cases.length === 0) return { origin: 0, duration: 0, segments: [] };
+  const origin = synchronizedStart ? 0 : Math.min(...cases.map((c) => c.start));
+  const segments: ReplaySegment[] = [];
+  let duration = 0;
+  for (const trace of cases) {
+    const base = synchronizedStart ? trace.start : origin;
+    duration = Math.max(duration, trace.end - base);
+    for (let i = 1; i < trace.events.length; i++) {
+      const from = trace.events[i - 1]!;
+      const to = trace.events[i]!;
+      const enterAt = from.end - base;
+      segments.push({
+        caseId: trace.caseId,
+        edgeId: `${from.activity}${EDGE_KEY_SEPARATOR}${to.activity}`,
+        source: from.activity,
+        target: to.activity,
+        enterAt,
+        exitAt: Math.max(enterAt, to.start - base),
+      });
+    }
+  }
+  // Stable: equal `enterAt` keeps case order.
+  segments.sort((a, b) => a.enterAt - b.enterAt);
+  return { origin, duration, segments };
+}
+
+/** Tokens at `t`: a segment is in flight over `[enterAt, exitAt)`. */
+function tokensAt(segments: readonly ReplaySegment[], t: number): ReplayFrameToken[] {
+  const tokens: ReplayFrameToken[] = [];
+  for (const segment of segments) {
+    if (segment.enterAt > t) break;
+    if (t >= segment.exitAt) continue;
+    tokens.push({
+      caseId: segment.caseId,
+      edgeId: segment.edgeId,
+      progress: (t - segment.enterAt) / (segment.exitAt - segment.enterAt),
+    });
+  }
+  return tokens;
+}
+
+/** Distinct cases per edge overlapping `[start, end)`. A zero-length move counts where it happens. */
+function congestionIn(
+  segments: readonly ReplaySegment[],
+  start: number,
+  end: number,
+): Record<string, number> {
+  const casesByEdge = new Map<string, Set<string>>();
+  for (const segment of segments) {
+    if (segment.enterAt >= end) break;
+    const overlaps = segment.exitAt > start || segment.enterAt >= start;
+    if (!overlaps) continue;
+    let cases = casesByEdge.get(segment.edgeId);
+    if (!cases) casesByEdge.set(segment.edgeId, (cases = new Set()));
+    cases.add(segment.caseId);
+  }
+  const congestion: Record<string, number> = {};
+  for (const [edgeId, cases] of casesByEdge) congestion[edgeId] = cases.size;
+  return congestion;
+}
+
+/**
+ * Bucket a log into replay frames.
+ *
+ * @example
+ * ```ts
+ * const timeline = replayTimeline(log, { synchronizedStart: true });
+ * const frame = replayFrameAt(timeline, timeline.duration / 2);
+ * ```
+ */
+export function replayTimeline(log: AnyLog, options: ReplayTimelineOptions = {}): ReplayTimeline {
+  const synchronizedStart = options.synchronizedStart ?? false;
+  const { origin, duration, segments } = buildSegments(log, synchronizedStart);
+  const requested =
+    options.bucketMs !== undefined && Number.isFinite(options.bucketMs) && options.bucketMs > 0
+      ? options.bucketMs
+      : defaultReplayBucketMs(duration);
+  const bucketMs = Math.max(requested, duration / (REPLAY_MAX_FRAMES - 1));
+  const frameCount = Math.floor(duration / bucketMs) + 1;
+  const frames: ReplayFrame[] = [];
+  let peakCongestion = 0;
+  for (let i = 0; i < frameCount; i++) {
+    const t = i * bucketMs;
+    const congestion = congestionIn(segments, t, t + bucketMs);
+    for (const count of Object.values(congestion)) peakCongestion = Math.max(peakCongestion, count);
+    frames.push({ t, tokens: tokensAt(segments, t), congestion });
+  }
+  return { origin, duration, bucketMs, synchronizedStart, segments, frames, peakCongestion };
+}
+
+/**
+ * The replay at any playhead — tokens at exactly `t` (not snapped), congestion from the
+ * bucket containing `t`. `t` is clamped to `[0, duration]`.
+ */
+export function replayFrameAt(timeline: ReplayTimeline, t: number): ReplayFrame {
+  const clamped = Math.min(Math.max(Number.isFinite(t) ? t : 0, 0), timeline.duration);
+  const bucket = Math.min(Math.floor(clamped / timeline.bucketMs), timeline.frames.length - 1);
+  return {
+    t: clamped,
+    tokens: tokensAt(timeline.segments, clamped),
+    congestion: timeline.frames[Math.max(bucket, 0)]?.congestion ?? {},
+  };
+}
+
+/** One transition in {@link rankReplayCongestion}'s list. */
+export interface ReplayCongestionEntry {
+  edgeId: string;
+  source: string;
+  target: string;
+  /** Most distinct cases on the edge in one bucket. */
+  peak: number;
+  /** Relative start of the first bucket reaching {@link peak}. */
+  peakAt: number;
+  /** Mean congestion over every bucket of the timeline. */
+  mean: number;
+}
+
+/** Transitions ranked by peak congestion, then mean, then edge id. Edges that never carry a case are omitted. */
+export function rankReplayCongestion(
+  timeline: ReplayTimeline,
+  limit = Number.POSITIVE_INFINITY,
+): ReplayCongestionEntry[] {
+  const ends = new Map<string, { source: string; target: string }>();
+  for (const s of timeline.segments) ends.set(s.edgeId, { source: s.source, target: s.target });
+  const byEdge = new Map<string, ReplayCongestionEntry>();
+  for (const frame of timeline.frames) {
+    for (const [edgeId, count] of Object.entries(frame.congestion)) {
+      let entry = byEdge.get(edgeId);
+      if (!entry) {
+        const { source, target } = ends.get(edgeId)!;
+        byEdge.set(edgeId, (entry = { edgeId, source, target, peak: 0, peakAt: 0, mean: 0 }));
+      }
+      if (count > entry.peak) {
+        entry.peak = count;
+        entry.peakAt = frame.t;
+      }
+      entry.mean += count;
+    }
+  }
+  const frameCount = Math.max(timeline.frames.length, 1);
+  return [...byEdge.values()]
+    .map((entry) => ({ ...entry, mean: entry.mean / frameCount }))
+    .sort(
+      (a, b) =>
+        b.peak - a.peak ||
+        b.mean - a.mean ||
+        (a.edgeId < b.edgeId ? -1 : a.edgeId > b.edgeId ? 1 : 0),
+    )
+    .slice(0, limit);
+}
+
+/** Smallest and largest token radius, in px. */
+export const REPLAY_TOKEN_RADIUS_RANGE = Object.freeze([3, 8] as const);
+
+/**
+ * Token radius for an edge's congestion: the radius above the minimum grows with
+ * √(count / peak), so a busier edge's blob grows by area rather than by diameter.
+ */
+export function replayTokenRadius(congestion: number, peak: number): number {
+  const [min, max] = REPLAY_TOKEN_RADIUS_RANGE;
+  if (!(peak > 0) || !(congestion > 0)) return min;
+  const share = Math.min(congestion / peak, 1);
+  return min + (max - min) * Math.sqrt(share);
+}