@elabs-ai/components-process 4.1.0

package/src/core/scale.ts

@@ -0,0 +1,100 @@
+/**
+ * Visual-scale helpers shared by every process view — RM-049.
+ *
+ * One implementation, so RM-051's edge width, RM-054's coverage bar and RM-050's
+ * abstraction threshold all agree on what "the 90th percentile" and "map this count to a
+ * stroke width" mean. Re-deriving a quantile per component is how two views end up
+ * disagreeing about the same log.
+ *
+ * All three are pure and total: they never throw, and they answer for the degenerate
+ * inputs (empty array, zero-width domain) rather than returning `NaN`.
+ */
+
+/** Ascending numeric comparator. Extracted so every sort in `/core` uses the same one. */
+export function ascending(a: number, b: number): number {
+  return a - b;
+}
+
+/** Only finite samples take part in a scale; `NaN`/`Infinity` are dropped, not propagated. */
+function finiteOnly(values: readonly number[]): number[] {
+  const out: number[] = [];
+  for (const v of values) if (Number.isFinite(v)) out.push(v);
+  return out;
+}
+
+/**
+ * The extent of `values`, ignoring non-finite entries.
+ *
+ * @returns `[min, max]`, or `[0, 0]` when there is nothing finite to measure.
+ */
+export function minMax(values: readonly number[]): [number, number] {
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  let seen = false;
+  for (const v of values) {
+    if (!Number.isFinite(v)) continue;
+    seen = true;
+    if (v < min) min = v;
+    if (v > max) max = v;
+  }
+  return seen ? [min, max] : [0, 0];
+}
+
+/**
+ * The `q`-quantile of an ALREADY ASCENDING-SORTED, all-finite array, by linear
+ * interpolation between order statistics (the R-7 / `d3.quantile` definition).
+ *
+ * Exported for callers that already hold a sorted array — {@link durationStats} sorts
+ * once and reads several quantiles off it. Use {@link quantile} when the input is not
+ * known to be sorted.
+ */
+export function quantileSorted(sorted: readonly number[], q: number): number {
+  const n = sorted.length;
+  if (n === 0) return 0;
+  if (n === 1) return sorted[0] as number;
+  const clamped = q < 0 ? 0 : q > 1 ? 1 : q;
+  const pos = clamped * (n - 1);
+  const lo = Math.floor(pos);
+  const hi = Math.ceil(pos);
+  const loValue = sorted[lo] as number;
+  if (lo === hi) return loValue;
+  const hiValue = sorted[hi] as number;
+  return loValue + (hiValue - loValue) * (pos - lo);
+}
+
+/**
+ * The `q`-quantile of `values` (0 ≤ `q` ≤ 1; out-of-range values are clamped).
+ *
+ * Sorts a COPY, so the caller's array is untouched. Non-finite entries are dropped;
+ * an empty (or all-non-finite) input answers `0`.
+ */
+export function quantile(values: readonly number[], q: number): number {
+  return quantileSorted(finiteOnly(values).sort(ascending), q);
+}
+
+/**
+ * Map `value` from `domain` onto `range`, clamped to the range's endpoints.
+ *
+ * The workhorse behind "frequency → stroke width" and "share → bar length". A
+ * DEGENERATE domain (`d0 === d1`, e.g. a graph whose every edge has the same count)
+ * answers `range[0]`: with a zero-width domain every input sits at the domain floor, so
+ * the range floor is the consistent answer — and it is what the clamped interpolation
+ * gives for any `value <= d0`. A caller that wants a different neutral (the widest
+ * stroke, say) special-cases it explicitly rather than relying on a surprise here.
+ *
+ * A descending domain (`d0 > d1`) is honoured — it simply inverts the mapping.
+ */
+export function clampWidth(
+  value: number,
+  domain: readonly [number, number],
+  range: readonly [number, number],
+): number {
+  const [d0, d1] = domain;
+  const [r0, r1] = range;
+  if (!Number.isFinite(value)) return r0;
+  const span = d1 - d0;
+  if (span === 0) return r0;
+  const t = (value - d0) / span;
+  const clamped = t < 0 ? 0 : t > 1 ? 1 : t;
+  return r0 + (r1 - r0) * clamped;
+}

package/src/core/types.ts

@@ -0,0 +1,151 @@
+/**
+ * The framework-free event-log and process-graph model — RM-049.
+ *
+ * Every downstream item in the process-mining track (RM-050 abstraction, RM-051 the
+ * process map, RM-052 the variant explorer, RM-053 the case table, RM-054 the coverage
+ * strip) reads these shapes, so they are the wave's frozen contract. Keep additions
+ * additive: a required field added here is a breaking change for five items at once.
+ *
+ * NOTHING in this module — or anywhere under `src/core/` — may import React, React Flow,
+ * visx, d3 or an `@elabs-ai/components-*` package. See `.claude/rules/process-components.md`
+ * and `pnpm process:reuse:check`.
+ */
+
+/**
+ * One raw row of an event log, before normalization.
+ *
+ * `timestamp` accepts the three shapes tabular sources actually produce — an ISO string,
+ * an epoch number, or a `Date` — because the adapters hand rows through unchanged and a
+ * consumer should not have to pre-convert. {@link normalizeLog} resolves all three to
+ * epoch milliseconds.
+ */
+export interface EventRow {
+  /** Case (process instance) this event belongs to. */
+  caseId: string;
+  /** Activity name. This is the node identity in the discovered graph. */
+  activity: string;
+  /** When the event completed (or, for a `lifecycle: "start"` row, when it started). */
+  timestamp: string | number | Date;
+  /**
+   * Optional explicit start of an interval event. Ignored when the row is one half of a
+   * `lifecycle` pair — the paired `"start"` row wins, because it is the observed value.
+   */
+  startTimestamp?: string | number | Date;
+  /** Who or what executed the event (a user, a queue, a system). */
+  resource?: string;
+  /** Lifecycle transition. Absent means the row is an atomic (already-complete) event. */
+  lifecycle?: "start" | "complete";
+  /** Free-form event-level attributes carried through normalization untouched. */
+  attributes?: Record<string, string | number | boolean | null>;
+}
+
+/** A raw event log: the rows, plus optional per-case attributes keyed by `caseId`. */
+export interface EventLog {
+  events: EventRow[];
+  caseAttributes?: Record<string, Record<string, unknown>>;
+}
+
+/**
+ * Summary statistics over a set of duration samples, in milliseconds.
+ *
+ * All seven members are always present; an empty sample set yields zeros rather than
+ * `null`, so a renderer never has to branch on absence.
+ */
+export interface DurationStats {
+  min: number;
+  max: number;
+  mean: number;
+  median: number;
+  p90: number;
+  sum: number;
+  /** Mean after discarding the lowest and highest 10% of samples. */
+  trimmedMean: number;
+}
+
+/** Per-activity aggregates in a discovered graph. */
+export interface ActivityStats {
+  /** Stable node identity — the activity name. */
+  id: string;
+  /** Human-readable label. Equal to `id` unless a caller relabels the graph. */
+  label: string;
+  /** Total occurrences across all cases. */
+  instances: number;
+  /** Number of distinct cases the activity occurs in at least once. */
+  cases: number;
+  /** True when the activity starts at least one case. */
+  isStart: boolean;
+  /** True when the activity ends at least one case. */
+  isEnd: boolean;
+  /** Distribution of the activity's own execution durations. */
+  duration: DurationStats;
+}
+
+/** Per-edge aggregates in a discovered graph (a directly-follows relation). */
+export interface TransitionStats {
+  source: string;
+  target: string;
+  /** Total occurrences of the directly-follows pair across all cases. */
+  count: number;
+  /** Number of distinct cases the pair occurs in at least once. */
+  caseCount: number;
+  /** Distribution of the flow time between the two activities. */
+  duration: DurationStats;
+  /** `source === target`. */
+  isSelfLoop: boolean;
+  /**
+   * Whether the edge points backwards in the laid-out graph. Discovery does not lay out,
+   * so this is always `false` here; a layout pass sets it (RM-044).
+   */
+  isBackEdge: boolean;
+}
+
+/** A directly-follows graph plus its totals. */
+export interface ProcessGraph {
+  activities: ActivityStats[];
+  transitions: TransitionStats[];
+  /** Activity name → number of cases that start with it. */
+  startActivities: Record<string, number>;
+  /** Activity name → number of cases that end with it. */
+  endActivities: Record<string, number>;
+  totals: { cases: number; events: number; variants: number };
+}
+
+/** One distinct activity sequence, with the cases that follow it. */
+export interface Variant {
+  /** Stable, reproducible id derived from the sequence — see `variantId`. */
+  id: string;
+  sequence: string[];
+  /** Number of cases following this sequence. */
+  count: number;
+  /** `count / totalCases`. */
+  share: number;
+  /** Running share across the descending-frequency order — monotonically non-decreasing. */
+  cumulativeShare: number;
+  /** Case ids following this sequence, in first-appearance order. */
+  caseIds: string[];
+  /** Distribution of the end-to-end case durations of `caseIds`. */
+  duration: DurationStats;
+}
+
+/** How an edge or node frequency is expressed to the reader. */
+export type FrequencyMode =
+  | "absolute"
+  | "absolute_case"
+  | "relative"
+  | "relative_case"
+  | "relative_antecedent"
+  | "relative_consequent"
+  | "max_repetitions";
+
+/** Which member of a {@link DurationStats} a performance view reads. */
+export type PerformanceAgg = "median" | "mean" | "min" | "max" | "sum" | "p90" | "trimmed_mean";
+
+/**
+ * Which elapsed time an edge measures.
+ *
+ * - `idle_time` — from the source's completion to the target's start (waiting time).
+ * - `inter_start_time` — from the source's start to the target's start (cycle time).
+ *
+ * For atomic events the two coincide, because start and completion are the same instant.
+ */
+export type FlowTime = "idle_time" | "inter_start_time";

package/src/core/worker/create-process-worker.test.ts

@@ -0,0 +1,255 @@
+import { describe, expect, it } from "vitest";
+
+import { discoverGraph } from "../discover-graph";
+import { normalizeLog } from "../event-log";
+import { extractVariants } from "../extract-variants";
+import fixture from "../fixtures/order-to-cash-small.json";
+import type { AnyLog } from "../event-log";
+import type { EventLog } from "../types";
+import { createProcessWorker, type ProcessWorkerLike } from "./create-process-worker";
+import { handleProcessRequest, type ProcessWorkerResponse } from "./process-worker";
+
+const orderToCash = fixture as EventLog;
+
+/**
+ * A stand-in for `Worker` that speaks the REAL protocol: it receives the same request
+ * object `postMessage` would clone, answers it asynchronously, and delivers the answer as
+ * a `{ data }` message event to the listeners the handle registered.
+ *
+ * This is deliberately not a spy. It exercises the message plumbing — id correlation,
+ * listener registration, the `{ data }` unwrap — which is the only part of the worker path
+ * that does not also run inline.
+ */
+class FakeWorker implements ProcessWorkerLike {
+  readonly received: unknown[] = [];
+  terminated = false;
+  private readonly listeners = new Map<string, ((event: unknown) => void)[]>();
+
+  constructor(private readonly options: { garbleFirst?: boolean } = {}) {}
+
+  postMessage(message: unknown): void {
+    this.received.push(message);
+    const response = handleProcessRequest(message as Parameters<typeof handleProcessRequest>[0]);
+    // A real worker answers on a later task; resolving synchronously here would hide an
+    // ordering bug the moment one appeared.
+    void Promise.resolve().then(() => {
+      if (this.terminated) return;
+      if (this.options.garbleFirst === true && this.received.length === 1) {
+        // Something that is not a response at all — the handle must ignore it and stay
+        // waiting rather than settling the promise with rubbish.
+        this.emit("message", { data: { nonsense: true } });
+      }
+      this.emit("message", { data: response });
+    });
+  }
+
+  terminate(): void {
+    this.terminated = true;
+  }
+
+  addEventListener(type: "message" | "error" | "messageerror", listener: (e: unknown) => void) {
+    const bucket = this.listeners.get(type);
+    if (bucket === undefined) this.listeners.set(type, [listener]);
+    else bucket.push(listener);
+  }
+
+  emit(type: string, event: unknown): void {
+    for (const listener of this.listeners.get(type) ?? []) listener(event);
+  }
+}
+
+describe("createProcessWorker degrades to the calling thread", () => {
+  it("runs inline in an environment with no Worker, and still answers correctly", async () => {
+    // The fallback here is ENVIRONMENT-DRIVEN, not simulated: jsdom implements no `Worker`
+    // constructor, so this is the same code path a server render or an embedded webview
+    // takes. Asserted rather than assumed, because the whole test is vacuous otherwise.
+    expect(typeof Worker).toBe("undefined");
+
+    const handle = createProcessWorker();
+    expect(handle.inline).toBe(true);
+    expect(await handle.discover(orderToCash)).toEqual(discoverGraph(orderToCash));
+    expect(await handle.variants(orderToCash)).toEqual(extractVariants(orderToCash));
+    handle.terminate();
+  });
+
+  it("falls back when constructing the worker throws", async () => {
+    let attempts = 0;
+    const handle = createProcessWorker({
+      createWorker: () => {
+        attempts += 1;
+        throw new Error("no worker here");
+      },
+    });
+    expect(handle.inline).toBe(false); // optimistic until the first request proves otherwise
+    expect(await handle.discover(orderToCash)).toEqual(discoverGraph(orderToCash));
+    expect(handle.inline).toBe(true);
+    expect(attempts).toBe(1);
+    // Degraded for good — it does not retry the broken constructor on every call.
+    expect(await handle.variants(orderToCash)).toEqual(extractVariants(orderToCash));
+    expect(attempts).toBe(1);
+  });
+
+  it("falls back when postMessage throws, without losing the in-flight request", async () => {
+    const handle = createProcessWorker({
+      createWorker: () => ({
+        postMessage() {
+          throw new Error("detached");
+        },
+        terminate() {},
+        addEventListener() {},
+      }),
+    });
+    expect(await handle.discover(orderToCash)).toEqual(discoverGraph(orderToCash));
+    expect(handle.inline).toBe(true);
+  });
+
+  it("answers a request already in flight when the worker errors", async () => {
+    const silent: ProcessWorkerLike & { fail?: () => void } = {
+      postMessage() {
+        // Never answers — the error event is what settles this request.
+      },
+      terminate() {},
+      addEventListener(type, listener) {
+        if (type === "error") silent.fail = () => listener(new Error("worker died"));
+      },
+    };
+    const handle = createProcessWorker({ createWorker: () => silent });
+    const pending = handle.discover(orderToCash);
+    silent.fail?.();
+    expect(await pending).toEqual(discoverGraph(orderToCash));
+    expect(handle.inline).toBe(true);
+  });
+
+  it("runs inline on request when asked to, without ever constructing a worker", async () => {
+    let constructed = 0;
+    const handle = createProcessWorker({
+      forceInline: true,
+      createWorker: () => {
+        constructed += 1;
+        return new FakeWorker();
+      },
+    });
+    expect(handle.inline).toBe(true);
+    await handle.discover(orderToCash);
+    expect(constructed).toBe(0);
+  });
+});
+
+describe("createProcessWorker over the message protocol", () => {
+  it("sends the request across and resolves with the worker's answer", async () => {
+    const fake = new FakeWorker();
+    const handle = createProcessWorker({ createWorker: () => fake });
+    const graph = await handle.discover(orderToCash);
+    expect(handle.inline).toBe(false);
+    expect(graph).toEqual(discoverGraph(orderToCash));
+    expect(fake.received).toEqual([{ id: 1, kind: "discover", log: orderToCash }]);
+  });
+
+  it("agrees with the inline path, request for request", async () => {
+    const viaWorker = createProcessWorker({ createWorker: () => new FakeWorker() });
+    const viaInline = createProcessWorker({ forceInline: true });
+    const options = { flowTime: "inter_start_time" } as const;
+
+    expect(await viaWorker.discover(orderToCash, options)).toEqual(
+      await viaInline.discover(orderToCash, options),
+    );
+    expect(await viaWorker.variants(orderToCash)).toEqual(await viaInline.variants(orderToCash));
+    viaWorker.terminate();
+    viaInline.terminate();
+  });
+
+  it("keeps concurrent requests apart by id", async () => {
+    const fake = new FakeWorker();
+    const handle = createProcessWorker({ createWorker: () => fake });
+    const [graph, variants] = await Promise.all([
+      handle.discover(orderToCash),
+      handle.variants(orderToCash),
+    ]);
+    expect(graph).toEqual(discoverGraph(orderToCash));
+    expect(variants).toEqual(extractVariants(orderToCash));
+    expect(fake.received.map((message) => (message as { id: number }).id)).toEqual([1, 2]);
+  });
+
+  it("ignores a message that is not a response", async () => {
+    const handle = createProcessWorker({
+      createWorker: () => new FakeWorker({ garbleFirst: true }),
+    });
+    expect(await handle.discover(orderToCash)).toEqual(discoverGraph(orderToCash));
+  });
+
+  it("passes an already-normalized log through untouched", async () => {
+    const normalized = normalizeLog(orderToCash);
+    const fake = new FakeWorker();
+    const handle = createProcessWorker({ createWorker: () => fake });
+    expect(await handle.discover(normalized)).toEqual(discoverGraph(normalized));
+    // The handle does not normalize, copy or reshape on the way out — `asNormalizedLog` is
+    // idempotent and the log crosses `postMessage` as the caller handed it over.
+    expect((fake.received[0] as { log: unknown }).log).toBe(normalized);
+  });
+
+  it("rejects when the worker reports a failure", async () => {
+    const handle = createProcessWorker({ createWorker: () => new FakeWorker() });
+    await expect(handle.discover({ nope: true } as unknown as AnyLog)).rejects.toThrow();
+  });
+
+  it("rejects pending and later work once terminated", async () => {
+    const silent: ProcessWorkerLike = {
+      postMessage() {},
+      terminate() {},
+      addEventListener() {},
+    };
+    const handle = createProcessWorker({ createWorker: () => silent });
+    const pending = handle.discover(orderToCash);
+    handle.terminate();
+    await expect(pending).rejects.toThrow("process worker terminated");
+    await expect(handle.variants(orderToCash)).rejects.toThrow("process worker terminated");
+  });
+});
+
+describe("handleProcessRequest", () => {
+  it("is the one function both paths run", () => {
+    const response = handleProcessRequest({ id: 7, kind: "discover", log: orderToCash });
+    expect(response).toEqual({
+      id: 7,
+      ok: true,
+      kind: "discover",
+      graph: discoverGraph(orderToCash),
+    });
+  });
+
+  it("honours discover options", () => {
+    const response = handleProcessRequest({
+      id: 1,
+      kind: "discover",
+      log: orderToCash,
+      options: { flowTime: "inter_start_time" },
+    });
+    expect(response).toEqual({
+      id: 1,
+      ok: true,
+      kind: "discover",
+      graph: discoverGraph(orderToCash, { flowTime: "inter_start_time" }),
+    });
+  });
+
+  it("answers variants", () => {
+    expect(handleProcessRequest({ id: 2, kind: "variants", log: orderToCash })).toEqual({
+      id: 2,
+      ok: true,
+      kind: "variants",
+      variants: extractVariants(orderToCash),
+    });
+  });
+
+  it("turns a throw into an ok:false response rather than killing the worker", () => {
+    const response = handleProcessRequest({
+      id: 3,
+      kind: "discover",
+      log: { nope: true } as unknown as AnyLog,
+    });
+    expect(response.ok).toBe(false);
+    expect((response as Extract<ProcessWorkerResponse, { ok: false }>).error).toBeTruthy();
+    // Still answerable afterwards — the failure is per-request, not per-worker.
+    expect(handleProcessRequest({ id: 4, kind: "variants", log: orderToCash }).ok).toBe(true);
+  });
+});