@elabs-ai/components-process 4.2.0 → 5.1.0

package/src/core/conformance.ts

@@ -0,0 +1,91 @@
+/**
+ * Conformance model — RM-061.
+ *
+ * The log-level result of replaying an event log against a reference model
+ * ({@link ConformanceResult}, produced by `tokenReplay`) and the fitness-over-time series a
+ * KPI sparkline plots ({@link conformanceRateSeries}).
+ *
+ * Scope boundary (analysis §9 risk 2): token replay against a lifted happy path only — no
+ * alignments, no BPMN import. A host needing either brings a backend.
+ *
+ * Framework-free, deterministic: no React, no `Date.now()`, no `@elabs-ai/components-*`
+ * import.
+ */
+import { asNormalizedLog, type AnyLog } from "./event-log";
+import type { ReplayModel } from "./reference-model";
+import { replayActivities, type DeviationType, type TraceReplayResult } from "./token-replay";
+
+/** Log-level conformance of an event log against a reference model. */
+export interface ConformanceResult {
+  /** Mean trace fitness in `[0, 1]`; `0` for an empty log. */
+  overallFitness: number;
+  /** One result per case, in the log's case order. */
+  traces: TraceReplayResult[];
+  /** Total deviations per type across all cases; every type is present. */
+  deviationCounts: Record<DeviationType, number>;
+  /** Deviations charged to each activity. Sums to the total deviation count. */
+  perActivity: Record<string, { deviations: number }>;
+  /**
+   * Deviations charged to each OBSERVED directly-follows edge, keyed
+   * `source + EDGE_KEY_SEPARATOR + target` — the same key `discoverGraph` gives the edge.
+   * Sums to at most the total deviation count.
+   */
+  perEdge: Record<string, { deviations: number }>;
+}
+
+/** Calendar granularity of {@link conformanceRateSeries}. All buckets are UTC. */
+export type ConformanceBucket = "day" | "week" | "month";
+
+/** One point of {@link conformanceRateSeries}. */
+export interface ConformanceRatePoint {
+  /** `YYYY-MM-DD` (day; for week, the UTC Monday that starts it) or `YYYY-MM` (month). */
+  bucket: string;
+  /** Mean fitness of the cases that started in this bucket. */
+  fitness: number;
+  caseCount: number;
+}
+
+const DAY_MS = 86_400_000;
+
+function bucketOf(ms: number, bucket: ConformanceBucket): string {
+  const date = new Date(ms);
+  if (bucket === "week") {
+    // getUTCDay(): 0 = Sunday … 6 = Saturday; shift so Monday is day 0.
+    const offset = (date.getUTCDay() + 6) % 7;
+    const monday = new Date(
+      Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()) - offset * DAY_MS,
+    );
+    return monday.toISOString().slice(0, 10);
+  }
+  const iso = date.toISOString();
+  return bucket === "month" ? iso.slice(0, 7) : iso.slice(0, 10);
+}
+
+/**
+ * Mean replay fitness per calendar bucket, keyed by each case's START time, in ascending
+ * bucket order. Empty buckets are not emitted. A case with no resolvable start timestamp
+ * cannot be placed in time and is left out, so `caseCount`s sum to the number of cases
+ * with a valid start.
+ */
+export function conformanceRateSeries(
+  log: AnyLog,
+  model: ReplayModel,
+  bucket: ConformanceBucket,
+): ConformanceRatePoint[] {
+  const totals = new Map<string, { sum: number; count: number }>();
+  for (const kase of asNormalizedLog(log).cases) {
+    if (!Number.isFinite(kase.start)) continue;
+    const key = bucketOf(kase.start, bucket);
+    const trace = kase.events.map((event) => event.activity);
+    const { fitness } = replayActivities(kase.caseId, trace, model);
+    const entry = totals.get(key);
+    if (entry === undefined) totals.set(key, { sum: fitness, count: 1 });
+    else {
+      entry.sum += fitness;
+      entry.count += 1;
+    }
+  }
+  return [...totals.entries()]
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, { sum, count }]) => ({ bucket: key, fitness: sum / count, caseCount: count }));
+}

package/src/core/diff-graphs.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from "vitest";
+import { diffGraphs } from "./diff-graphs";
+import type { ActivityStats, ProcessGraph, TransitionStats } from "./types";
+
+const DURATION = {
+  min: 1,
+  max: 10,
+  mean: 5,
+  median: 5,
+  p90: 9,
+  sum: 50,
+  trimmedMean: 5,
+};
+
+function activity(id: string, overrides: Partial<ActivityStats> = {}): ActivityStats {
+  return {
+    id,
+    label: id,
+    instances: 10,
+    cases: 5,
+    isStart: false,
+    isEnd: false,
+    duration: DURATION,
+    ...overrides,
+  };
+}
+
+function transition(
+  source: string,
+  target: string,
+  overrides: Partial<TransitionStats> = {},
+): TransitionStats {
+  return {
+    source,
+    target,
+    count: 10,
+    caseCount: 5,
+    duration: DURATION,
+    isSelfLoop: source === target,
+    isBackEdge: false,
+    ...overrides,
+  };
+}
+
+function graph(overrides: Partial<ProcessGraph> = {}): ProcessGraph {
+  return {
+    activities: [],
+    transitions: [],
+    startActivities: {},
+    endActivities: {},
+    totals: { cases: 0, events: 0, variants: 0 },
+    ...overrides,
+  };
+}
+
+describe("diffGraphs", () => {
+  it("marks every entry common with delta 0 on two identical graphs", () => {
+    const a = graph({
+      activities: [activity("Create", { isStart: true }), activity("Ship", { isEnd: true })],
+      transitions: [transition("Create", "Ship")],
+    });
+    const b = graph({
+      activities: [activity("Create", { isStart: true }), activity("Ship", { isEnd: true })],
+      transitions: [transition("Create", "Ship")],
+    });
+
+    const diff = diffGraphs(a, b);
+
+    expect(diff.activities).toHaveLength(2);
+    for (const entry of diff.activities) {
+      expect(entry.state).toBe("common");
+      expect(entry.delta).toBe(0);
+      expect(entry.ratio).toBe(1);
+    }
+    expect(diff.transitions).toHaveLength(1);
+    expect(diff.transitions[0]!.state).toBe("common");
+    expect(diff.transitions[0]!.delta).toBe(0);
+  });
+
+  it("marks every entry aOnly or bOnly on fully disjoint graphs", () => {
+    const a = graph({
+      activities: [activity("Create")],
+      transitions: [transition("Create", "Create")],
+    });
+    const b = graph({
+      activities: [activity("Cancel")],
+      transitions: [transition("Cancel", "Cancel")],
+    });
+
+    const diff = diffGraphs(a, b);
+
+    expect(diff.activities).toHaveLength(2);
+    // A one-sided entry never sets its ABSENT side's key at all (no `b: undefined` noise) —
+    // check presence/absence directly rather than via `toMatchObject`, which treats an
+    // expected `undefined` value inconsistently with a genuinely missing key.
+    const createEntry = diff.activities.find((e) => e.id === "Create");
+    expect(createEntry).toMatchObject({ state: "aOnly", a: expect.any(Object) });
+    expect(createEntry?.b).toBeUndefined();
+    expect(createEntry?.delta).toBeUndefined();
+    const cancelEntry = diff.activities.find((e) => e.id === "Cancel");
+    expect(cancelEntry).toMatchObject({ state: "bOnly", b: expect.any(Object) });
+    expect(cancelEntry?.a).toBeUndefined();
+    expect(cancelEntry?.delta).toBeUndefined();
+    expect(diff.transitions).toHaveLength(2);
+    for (const entry of diff.transitions) {
+      expect(["aOnly", "bOnly"]).toContain(entry.state);
+      expect(entry.delta).toBeUndefined();
+    }
+  });
+
+  it("computes delta and ratio for a common entry whose value changed", () => {
+    const a = graph({ activities: [activity("Create", { instances: 20 })] });
+    const b = graph({ activities: [activity("Create", { instances: 30 })] });
+
+    const diff = diffGraphs(a, b);
+
+    expect(diff.activities[0]).toMatchObject({ state: "common", delta: 10, ratio: 1.5 });
+  });
+
+  it("omits ratio (never Infinity) when a's reference value is zero", () => {
+    const a = graph({ activities: [activity("Create", { instances: 0 })] });
+    const b = graph({ activities: [activity("Create", { instances: 5 })] });
+
+    const diff = diffGraphs(a, b);
+
+    expect(diff.activities[0]!.delta).toBe(5);
+    expect(diff.activities[0]!.ratio).toBeUndefined();
+  });
+
+  it("carries each side's own totals through untouched", () => {
+    const a = graph({ totals: { cases: 3, events: 9, variants: 1 } });
+    const b = graph({ totals: { cases: 7, events: 21, variants: 2 } });
+
+    const diff = diffGraphs(a, b);
+
+    expect(diff.totals).toEqual({
+      a: { cases: 3, events: 9, variants: 1 },
+      b: { cases: 7, events: 21, variants: 2 },
+    });
+  });
+
+  it("keys a transition by source+target, not by object identity", () => {
+    const a = graph({ transitions: [transition("A", "B", { count: 4 })] });
+    const b = graph({ transitions: [transition("A", "B", { count: 9 })] });
+
+    const diff = diffGraphs(a, b);
+
+    expect(diff.transitions).toHaveLength(1);
+    expect(diff.transitions[0]).toMatchObject({ state: "common", delta: 5 });
+  });
+});

package/src/core/diff-graphs.ts

@@ -0,0 +1,118 @@
+/**
+ * diffGraphs — RM-064's pure diff between two discovered `ProcessGraph`s, the model
+ * `ProcessCompare` renders (side-by-side or superimposed).
+ *
+ * Activities are matched by `id` (the activity name — the same identity `/core` uses
+ * everywhere else); transitions are matched by `source`+{@link EDGE_KEY_SEPARATOR}+`target`,
+ * exactly the key `reconcileGraph`'s own `transitionKey` builds, so a transition that moved
+ * between the two graphs is never mistaken for two unrelated ones. An element present on
+ * both sides is `"common"`; present only in `a` is `"aOnly"`; present only in `b` is
+ * `"bOnly"` — every element in the union appears in exactly one of the three states.
+ *
+ * `delta`/`ratio` are computed once BOTH sides have the element (a `"common"` entry) —
+ * comparing a real reading against nothing would be a fabricated number, not a diff. The
+ * reference metric is each element's plain occurrence count — `instances` for an activity,
+ * `count` for a transition — because those are the only two fields every `ActivityStats`/
+ * `TransitionStats` always carries (never derived, never optional), so a delta is always
+ * well-defined for a `"common"` entry, whatever metric a downstream view happens to paint
+ * with. `ratio` is omitted rather than `Infinity` when `a`'s value is `0`.
+ *
+ * Pure, deterministic, framework-free — see the module-level rule in `types.ts`.
+ */
+import { EDGE_KEY_SEPARATOR } from "./discover-graph";
+import type { ActivityStats, ProcessGraph, TransitionStats } from "./types";
+
+/** Which side(s) of the diff an activity or transition survives in. */
+export type DiffState = "common" | "aOnly" | "bOnly";
+
+/** One activity's or transition's diff — its identity, its state, and (when `"common"`) its delta. */
+export interface DiffEntry<Stats> {
+  id: string;
+  state: DiffState;
+  /** Present unless the element is `"bOnly"`. */
+  a?: Stats;
+  /** Present unless the element is `"aOnly"`. */
+  b?: Stats;
+  /** `b`'s reference value minus `a`'s. Only set for a `"common"` entry. */
+  delta?: number;
+  /** `b`'s reference value divided by `a`'s. Only set for a `"common"` entry with `a > 0`. */
+  ratio?: number;
+}
+
+/** The full diff between two graphs. */
+export interface ProcessGraphDiff {
+  activities: DiffEntry<ActivityStats>[];
+  transitions: DiffEntry<TransitionStats>[];
+  totals: { a: ProcessGraph["totals"]; b: ProcessGraph["totals"] };
+}
+
+/** `source`+{@link EDGE_KEY_SEPARATOR}+`target` — the same key `reconcileGraph` builds. */
+function transitionKey(transition: Pick<TransitionStats, "source" | "target">): string {
+  return `${transition.source}${EDGE_KEY_SEPARATOR}${transition.target}`;
+}
+
+/** Every id in `first`, in order, then every id `second` adds that `first` did not have. */
+function unionIds(first: string[], second: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const id of first) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  for (const id of second) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+
+function diffEntries<Stats>(
+  aById: ReadonlyMap<string, Stats>,
+  bById: ReadonlyMap<string, Stats>,
+  ids: string[],
+  referenceValue: (stats: Stats) => number,
+): DiffEntry<Stats>[] {
+  return ids.map((id) => {
+    const a = aById.get(id);
+    const b = bById.get(id);
+    const state: DiffState = a !== undefined && b !== undefined ? "common" : a ? "aOnly" : "bOnly";
+    const entry: DiffEntry<Stats> = { id, state };
+    if (a !== undefined) entry.a = a;
+    if (b !== undefined) entry.b = b;
+    if (a !== undefined && b !== undefined) {
+      const aValue = referenceValue(a);
+      const bValue = referenceValue(b);
+      entry.delta = bValue - aValue;
+      if (aValue > 0) entry.ratio = bValue / aValue;
+    }
+    return entry;
+  });
+}
+
+/**
+ * Diff two discovered graphs. Neither input is mutated; the entries reference the original
+ * `ActivityStats`/`TransitionStats` objects, never copies.
+ */
+export function diffGraphs(a: ProcessGraph, b: ProcessGraph): ProcessGraphDiff {
+  const aActivities = new Map(a.activities.map((activity) => [activity.id, activity]));
+  const bActivities = new Map(b.activities.map((activity) => [activity.id, activity]));
+  const activityIds = unionIds(
+    a.activities.map((activity) => activity.id),
+    b.activities.map((activity) => activity.id),
+  );
+
+  const aTransitions = new Map(a.transitions.map((t) => [transitionKey(t), t]));
+  const bTransitions = new Map(b.transitions.map((t) => [transitionKey(t), t]));
+  const transitionIds = unionIds(
+    a.transitions.map((t) => transitionKey(t)),
+    b.transitions.map((t) => transitionKey(t)),
+  );
+
+  return {
+    activities: diffEntries(aActivities, bActivities, activityIds, (stats) => stats.instances),
+    transitions: diffEntries(aTransitions, bTransitions, transitionIds, (stats) => stats.count),
+    totals: { a: a.totals, b: b.totals },
+  };
+}

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

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+
+import { fromOcel } from "./adapters/ocel";
+import {
+  abstractObjectCentricGraph,
+  discoverObjectCentricGraph,
+  objectCentricProcessGraph,
+  objectTypeColorScale,
+} from "./discover-object-centric-graph";
+import { OCEL_SAMPLE } from "./fixtures/ocel-sample";
+
+function sampleGraph() {
+  const result = fromOcel(OCEL_SAMPLE);
+  if (!result.ok) throw new Error("fixture must parse");
+  return discoverObjectCentricGraph(result.logs, { objectTypes: result.objectTypes });
+}
+
+describe("discoverObjectCentricGraph", () => {
+  it("merges an activity shared by all three types into one node with three perType entries", () => {
+    const graph = sampleGraph();
+    const pack = graph.activities.find((activity) => activity.id === "Pack")!;
+    expect(pack.perType).toEqual({
+      order: { instances: 1, cases: 1 },
+      item: { instances: 2, cases: 2 },
+      package: { instances: 1, cases: 1 },
+    });
+    // One OCEL event, however many objects it touched.
+    expect(pack.events).toBe(1);
+  });
+
+  it("keeps an activity present in only one type single-type", () => {
+    const graph = sampleGraph();
+    const pick = graph.activities.find((activity) => activity.id === "Pick Item")!;
+    expect(Object.keys(pick.perType)).toEqual(["item"]);
+    expect(pick.perType.item).toEqual({ instances: 1, cases: 1 });
+  });
+
+  it("keeps edges per type — never merged across types", () => {
+    const graph = sampleGraph();
+    expect(graph.objectTypes).toEqual(["order", "item", "package"]);
+    const pairs = (type: string) =>
+      graph.transitionsByType[type]!.map((t) => `${t.source}>${t.target}:${t.count}`).sort();
+    expect(pairs("order")).toEqual(["Pack>Ship:1", "Place Order>Pack:1"]);
+    expect(pairs("item")).toEqual([
+      "Pick Item>Pack:1",
+      "Place Order>Pack:1",
+      "Place Order>Pick Item:1",
+    ]);
+    expect(pairs("package")).toEqual(["Pack>Ship:1"]);
+  });
+
+  it("flattens to a ProcessGraph that sums shared transitions for layout", () => {
+    const flat = objectCentricProcessGraph(sampleGraph());
+    expect(flat.activities.map((a) => a.id).sort()).toEqual([
+      "Pack",
+      "Pick Item",
+      "Place Order",
+      "Ship",
+    ]);
+    const placeToPack = flat.transitions.find(
+      (t) => t.source === "Place Order" && t.target === "Pack",
+    )!;
+    expect(placeToPack.count).toBe(2);
+    expect(flat.totals).toEqual({ cases: 4, events: 4, variants: 4 });
+    expect(flat.activities.find((a) => a.id === "Pack")).toMatchObject({ instances: 1, cases: 4 });
+  });
+
+  it("abstracts one type without touching another", () => {
+    const graph = sampleGraph();
+    const abstracted = abstractObjectCentricGraph(graph, {
+      item: { activities: 0.34, paths: 1, keepConnected: false },
+    });
+    expect(abstracted.transitionsByType.order).toBe(graph.transitionsByType.order);
+    expect(abstracted.transitionsByType.item!.length).toBeLessThan(
+      graph.transitionsByType.item!.length,
+    );
+    expect(abstracted.hiddenByType.order).toEqual({ activities: 0, paths: 0 });
+    expect(abstracted.hiddenByType.item!.activities).toBeGreaterThan(0);
+    // Event counts are carried over, never restated.
+    expect(abstracted.activities.find((a) => a.id === "Pack")!.events).toBe(1);
+  });
+
+  it("colours object types with the shared RM-054 scale and a text code per type", () => {
+    const scale = objectTypeColorScale(sampleGraph());
+    // Ranked by object count: item (2) first, then order and package (1 each) by name.
+    expect(scale.legend.map((entry) => [entry.activityId, entry.token])).toEqual([
+      ["item", "--chart-1"],
+      ["order", "--chart-2"],
+      ["package", "--chart-3"],
+    ]);
+    const codes = scale.legend.map((entry) => entry.code);
+    expect(new Set(codes).size).toBe(3);
+  });
+});