@elabs-ai/components-process 4.2.0 → 5.1.0

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

@@ -0,0 +1,296 @@
+/**
+ * Object-centric directly-follows graph (OC-DFG) discovery — RM-066.
+ *
+ * An OC-DFG is one directly-follows graph PER OBJECT TYPE, drawn on one canvas: activities
+ * shared between types merge into a single node that keeps a per-type breakdown, while
+ * edges stay per type — an `order` following and an `item` following are different
+ * relations, so they are never summed into one arrow. The merge semantics (per-type
+ * projection, shared-activity join, per-type edges) follow pm4js's documented OC-DFG
+ * construction; see `ATTRIBUTION.md`. No pm4js code is copied, and nothing here derives
+ * from the AGPL Python reference implementation.
+ *
+ * Built entirely on `discoverGraph` and `abstractGraph`: every per-type number is exactly
+ * what the single-case pipeline would print for that type's projection.
+ */
+import { abstractGraph, type AbstractionOptions } from "./abstract-graph";
+import { activityColorScale, type ActivityColorScale } from "./activity-color-scale";
+import { OCEL_EVENT_ID_ATTRIBUTE } from "./adapters/ocel";
+import { discoverGraph, EDGE_KEY_SEPARATOR, type DiscoverGraphOptions } from "./discover-graph";
+import type { ActivityStats, EventLog, ProcessGraph, TransitionStats } from "./types";
+
+/** One object type's share of a merged activity. */
+export interface ObjectTypeActivityCounts {
+  /** Occurrences in that type's projection (one per event × referenced object). */
+  instances: number;
+  /** Distinct objects of that type the activity touches. */
+  cases: number;
+}
+
+/** A merged activity: shared across object types, with a per-type breakdown. */
+export interface ObjectCentricActivityStats extends Omit<ActivityStats, "instances" | "cases"> {
+  /**
+   * Distinct OCEL events of this activity across every type — an event that references an
+   * order and two items counts once. Falls back to the largest per-type `instances` when
+   * the logs carry no `__ocelEventId` (hand-built logs).
+   */
+  events: number;
+  /** Object type → counts, only for the types this activity occurs in. */
+  perType: Record<string, ObjectTypeActivityCounts>;
+}
+
+/** An object-centric directly-follows graph. */
+export interface ObjectCentricGraph {
+  /** Merged activities, busiest (by `events`) first, ties by id. */
+  activities: ObjectCentricActivityStats[];
+  /** Object type → that type's own directly-follows edges. Never merged across types. */
+  transitionsByType: Record<string, TransitionStats[]>;
+  /** The object types, in the caller's order. */
+  objectTypes: string[];
+  /** Object type → the full per-type graph the merge was built from. */
+  graphsByType: Record<string, ProcessGraph>;
+}
+
+/** {@link abstractObjectCentricGraph}'s result — what each type's abstraction hid. */
+export interface AbstractedObjectCentricGraph extends ObjectCentricGraph {
+  hiddenByType: Record<string, { activities: number; paths: number }>;
+}
+
+function compareStrings(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** Distinct `__ocelEventId`s per activity across every log, or `undefined` if none carry one. */
+function countDistinctEvents(logs: readonly EventLog[]): Map<string, number> | undefined {
+  const ids = new Map<string, Set<string>>();
+  let any = false;
+  for (const log of logs) {
+    for (const row of log.events) {
+      const id = row.attributes?.[OCEL_EVENT_ID_ATTRIBUTE];
+      if (typeof id !== "string") continue;
+      any = true;
+      let set = ids.get(row.activity);
+      if (set === undefined) {
+        set = new Set();
+        ids.set(row.activity, set);
+      }
+      set.add(id);
+    }
+  }
+  if (!any) return undefined;
+  const out = new Map<string, number>();
+  for (const [activity, set] of ids) out.set(activity, set.size);
+  return out;
+}
+
+/**
+ * Merge per-type graphs into one {@link ObjectCentricGraph}.
+ *
+ * `eventCounts` supplies each activity's distinct-event count; an activity it does not
+ * name falls back to its largest per-type `instances`. A merged activity's `duration` is
+ * the duration of the type with the most instances of it (ties: earlier type), because
+ * durations of the same events seen through two projections are not additive.
+ */
+export function mergeObjectCentricGraphs(
+  graphsByType: Record<string, ProcessGraph>,
+  objectTypes: readonly string[] = Object.keys(graphsByType),
+  eventCounts?: ReadonlyMap<string, number>,
+): ObjectCentricGraph {
+  const merged = new Map<string, ObjectCentricActivityStats>();
+  const bestInstances = new Map<string, number>();
+  const transitionsByType: Record<string, TransitionStats[]> = {};
+  const types = objectTypes.filter((type) => graphsByType[type] !== undefined);
+
+  for (const type of types) {
+    const graph = graphsByType[type] as ProcessGraph;
+    transitionsByType[type] = graph.transitions;
+    for (const activity of graph.activities) {
+      let entry = merged.get(activity.id);
+      if (entry === undefined) {
+        entry = {
+          id: activity.id,
+          label: activity.label,
+          isStart: false,
+          isEnd: false,
+          duration: activity.duration,
+          events: 0,
+          perType: {},
+        };
+        merged.set(activity.id, entry);
+      }
+      entry.perType[type] = { instances: activity.instances, cases: activity.cases };
+      entry.isStart ||= activity.isStart;
+      entry.isEnd ||= activity.isEnd;
+      if (activity.instances > (bestInstances.get(activity.id) ?? -1)) {
+        bestInstances.set(activity.id, activity.instances);
+        entry.duration = activity.duration;
+      }
+    }
+  }
+
+  const activities = [...merged.values()];
+  for (const activity of activities) {
+    activity.events = eventCounts?.get(activity.id) ?? bestInstances.get(activity.id) ?? 0;
+  }
+  activities.sort((a, b) => b.events - a.events || compareStrings(a.id, b.id));
+
+  const graphs: Record<string, ProcessGraph> = {};
+  for (const type of types) graphs[type] = graphsByType[type] as ProcessGraph;
+
+  return { activities, transitionsByType, objectTypes: types, graphsByType: graphs };
+}
+
+/**
+ * Discover an {@link ObjectCentricGraph} from per-object-type logs (typically
+ * `fromOcel(…).logs`). Runs `discoverGraph` once per type, then merges.
+ */
+export function discoverObjectCentricGraph(
+  logsByType: Record<string, EventLog>,
+  options: DiscoverGraphOptions & { objectTypes?: string[] } = {},
+): ObjectCentricGraph {
+  const { objectTypes = Object.keys(logsByType), ...discoverOptions } = options;
+  const types = objectTypes.filter((type) => logsByType[type] !== undefined);
+  const graphsByType: Record<string, ProcessGraph> = {};
+  for (const type of types) {
+    graphsByType[type] = discoverGraph(logsByType[type] as EventLog, discoverOptions);
+  }
+  const eventCounts = countDistinctEvents(types.map((type) => logsByType[type] as EventLog));
+  return mergeObjectCentricGraphs(graphsByType, types, eventCounts);
+}
+
+/**
+ * Abstract each object type independently, then re-merge.
+ *
+ * `perType[type]` wins for a type it names; `fallback` applies to every other type; a type
+ * with neither is kept whole. Activity `events` counts are carried over from the input,
+ * so abstraction hides nodes and edges without restating a statistic.
+ */
+export function abstractObjectCentricGraph(
+  graph: ObjectCentricGraph,
+  perType: Readonly<Record<string, AbstractionOptions>> = {},
+  fallback?: AbstractionOptions,
+): AbstractedObjectCentricGraph {
+  const graphsByType: Record<string, ProcessGraph> = {};
+  const hiddenByType: Record<string, { activities: number; paths: number }> = {};
+  for (const type of graph.objectTypes) {
+    const source = graph.graphsByType[type] as ProcessGraph;
+    const options = perType[type] ?? fallback;
+    if (options === undefined) {
+      graphsByType[type] = source;
+      hiddenByType[type] = { activities: 0, paths: 0 };
+      continue;
+    }
+    const { hidden, ...abstracted } = abstractGraph(source, options);
+    graphsByType[type] = abstracted;
+    hiddenByType[type] = hidden;
+  }
+  const eventCounts = new Map(graph.activities.map((activity) => [activity.id, activity.events]));
+  return {
+    ...mergeObjectCentricGraphs(graphsByType, graph.objectTypes, eventCounts),
+    hiddenByType,
+  };
+}
+
+/**
+ * Flatten an {@link ObjectCentricGraph} into one {@link ProcessGraph} — the shape the
+ * process map lays out and reads its node metrics from.
+ *
+ * - an activity's `instances` is its distinct-event count and its `cases` is the number of
+ *   objects (of any type) it touches;
+ * - a pair of activities joined in several types becomes ONE transition whose `count` and
+ *   `caseCount` sum the types' — used for layout and selection only; the map still draws
+ *   the per-type edges from `transitionsByType`;
+ * - `totals.cases` counts objects, `totals.events` distinct events.
+ */
+export function objectCentricProcessGraph(graph: ObjectCentricGraph): ProcessGraph {
+  const activities: ActivityStats[] = graph.activities.map((activity) => {
+    let cases = 0;
+    for (const counts of Object.values(activity.perType)) cases += counts.cases;
+    return {
+      id: activity.id,
+      label: activity.label,
+      instances: activity.events,
+      cases,
+      isStart: activity.isStart,
+      isEnd: activity.isEnd,
+      duration: activity.duration,
+    };
+  });
+
+  const transitions = new Map<string, TransitionStats>();
+  const startActivities: Record<string, number> = {};
+  const endActivities: Record<string, number> = {};
+  const totals = { cases: 0, events: 0, variants: 0 };
+  for (const activity of graph.activities) totals.events += activity.events;
+
+  for (const type of graph.objectTypes) {
+    const typeGraph = graph.graphsByType[type] as ProcessGraph;
+    totals.cases += typeGraph.totals.cases;
+    totals.variants += typeGraph.totals.variants;
+    for (const [id, count] of Object.entries(typeGraph.startActivities)) {
+      startActivities[id] = (startActivities[id] ?? 0) + count;
+    }
+    for (const [id, count] of Object.entries(typeGraph.endActivities)) {
+      endActivities[id] = (endActivities[id] ?? 0) + count;
+    }
+    for (const transition of graph.transitionsByType[type] ?? []) {
+      const key = `${transition.source}${EDGE_KEY_SEPARATOR}${transition.target}`;
+      const existing = transitions.get(key);
+      if (existing === undefined) {
+        transitions.set(key, { ...transition });
+        continue;
+      }
+      if (transition.count > existing.count) existing.duration = transition.duration;
+      existing.count += transition.count;
+      existing.caseCount += transition.caseCount;
+    }
+  }
+
+  const transitionList = [...transitions.values()].sort(
+    (a, b) =>
+      b.count - a.count || compareStrings(a.source, b.source) || compareStrings(a.target, b.target),
+  );
+
+  const sorted = (record: Record<string, number>): Record<string, number> => {
+    const out: Record<string, number> = {};
+    for (const key of Object.keys(record).sort()) out[key] = record[key] as number;
+    return out;
+  };
+
+  return {
+    activities,
+    transitions: transitionList,
+    startActivities: sorted(startActivities),
+    endActivities: sorted(endActivities),
+    totals,
+  };
+}
+
+/**
+ * The object-type colour scale — RM-054's `activityColorScale`, reused rather than
+ * reimplemented: object types are ranked by how many objects each has (ties by name) and
+ * take `--chart-1` … `--chart-11` in that order, beyond which they share the hatched
+ * "other" slot. `codeFor(type)` is the two-character text code painted beside every
+ * swatch, so a type is never identified by colour alone.
+ */
+export function objectTypeColorScale(graph: ObjectCentricGraph): ActivityColorScale {
+  const zero = { min: 0, max: 0, mean: 0, median: 0, p90: 0, sum: 0, trimmedMean: 0 };
+  const activities: ActivityStats[] = graph.objectTypes.map((type) => {
+    const typeGraph = graph.graphsByType[type] as ProcessGraph;
+    return {
+      id: type,
+      label: type,
+      instances: typeGraph.totals.events,
+      cases: typeGraph.totals.cases,
+      isStart: false,
+      isEnd: false,
+      duration: zero,
+    };
+  });
+  return activityColorScale({
+    activities,
+    transitions: [],
+    startActivities: {},
+    endActivities: {},
+    totals: { cases: 0, events: 0, variants: 0 },
+  });
+}

package/src/core/fixtures/ocel-sample.ts

@@ -0,0 +1,82 @@
+/**
+ * A 3-object-type, 4-event OCEL 2.0 JSON log (RM-066) — small enough to verify by hand.
+ *
+ * | event | activity    | time  | order | item   | package |
+ * | ----- | ----------- | ----- | ----- | ------ | ------- |
+ * | e1    | Place Order | 09:00 | o1    | i1, i2 |         |
+ * | e2    | Pick Item   | 10:00 |       | i1     |         |
+ * | e3    | Pack        | 11:00 | o1    | i1, i2 | p1      |
+ * | e4    | Ship        | 12:00 | o1    |        | p1      |
+ *
+ * Projections: `order` has 3 rows (o1: Place Order → Pack → Ship), `item` has 5 (i1: Place
+ * Order → Pick Item → Pack; i2: Place Order → Pack), `package` has 2 (p1: Pack → Ship).
+ * `Pack` occurs in all three types; `Pick Item` only in `item`.
+ */
+import type { OcelJson } from "../adapters/ocel";
+
+export const OCEL_SAMPLE: OcelJson = {
+  objectTypes: [
+    { name: "order", attributes: [{ name: "value", type: "float" }] },
+    { name: "item", attributes: [] },
+    { name: "package", attributes: [] },
+  ],
+  eventTypes: [
+    { name: "Place Order", attributes: [{ name: "channel", type: "string" }] },
+    { name: "Pick Item", attributes: [] },
+    { name: "Pack", attributes: [] },
+    { name: "Ship", attributes: [] },
+  ],
+  objects: [
+    {
+      id: "o1",
+      type: "order",
+      attributes: [
+        { name: "value", time: "2026-01-05T08:00:00.000Z", value: 120 },
+        { name: "value", time: "2026-01-05T11:30:00.000Z", value: 95 },
+      ],
+    },
+    { id: "i1", type: "item" },
+    { id: "i2", type: "item" },
+    { id: "p1", type: "package" },
+  ],
+  events: [
+    {
+      id: "e1",
+      type: "Place Order",
+      time: "2026-01-05T09:00:00.000Z",
+      attributes: [{ name: "channel", value: "web" }],
+      relationships: [
+        { objectId: "o1", qualifier: "placed" },
+        { objectId: "i1", qualifier: "contains" },
+        { objectId: "i2", qualifier: "contains" },
+      ],
+    },
+    {
+      id: "e2",
+      type: "Pick Item",
+      time: "2026-01-05T10:00:00.000Z",
+      relationships: [{ objectId: "i1", qualifier: "picked" }],
+    },
+    {
+      id: "e3",
+      type: "Pack",
+      time: "2026-01-05T11:00:00.000Z",
+      relationships: [
+        { objectId: "o1", qualifier: "for" },
+        { objectId: "i1", qualifier: "packed" },
+        { objectId: "i2", qualifier: "packed" },
+        { objectId: "i2", qualifier: "checked" },
+        { objectId: "p1", qualifier: "into" },
+      ],
+    },
+    {
+      id: "e4",
+      type: "Ship",
+      time: "2026-01-05T12:00:00.000Z",
+      relationships: [
+        { objectId: "o1", qualifier: "for" },
+        { objectId: "p1", qualifier: "shipped" },
+      ],
+    },
+  ],
+};

package/src/core/fixtures/sample.xes

@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  RM-063 fixture — a 3-trace IEEE 1849 XES log exercising: a complete-only (atomic) trace,
+  a trace using lifecycle:transition start/complete pairs, and a trace relying on a
+  <global scope="event"> default for org:resource. Hand-computed and asserted in xes.test.ts.
+-->
+<log xes.version="1.0" xes.features="nested-attributes">
+  <global scope="event">
+    <string key="org:resource" value="Unassigned"/>
+  </global>
+  <classifier name="Activity classifier" keys="concept:name"/>
+  <trace>
+    <string key="concept:name" value="case-1"/>
+    <string key="channel" value="web"/>
+    <event>
+      <string key="concept:name" value="Create Order"/>
+      <date key="time:timestamp" value="2026-01-05T09:00:00.000Z"/>
+      <string key="org:resource" value="A. Novak"/>
+    </event>
+    <event>
+      <string key="concept:name" value="Check Credit"/>
+      <date key="time:timestamp" value="2026-01-05T09:15:00.000Z"/>
+      <string key="org:resource" value="Credit Service"/>
+      <float key="cost:total" value="120.5"/>
+    </event>
+  </trace>
+  <trace>
+    <string key="concept:name" value="case-2"/>
+    <string key="channel" value="mobile"/>
+    <event>
+      <string key="concept:name" value="Register"/>
+      <date key="time:timestamp" value="2026-01-06T09:00:00.000Z"/>
+      <string key="org:resource" value="System"/>
+      <string key="lifecycle:transition" value="start"/>
+    </event>
+    <event>
+      <string key="concept:name" value="Register"/>
+      <date key="time:timestamp" value="2026-01-06T09:10:00.000Z"/>
+      <string key="org:resource" value="System"/>
+      <string key="lifecycle:transition" value="complete"/>
+    </event>
+    <event>
+      <string key="concept:name" value="Approve"/>
+      <date key="time:timestamp" value="2026-01-06T09:10:00.000Z"/>
+      <string key="org:resource" value="B. Kowalski"/>
+      <string key="lifecycle:transition" value="start"/>
+    </event>
+    <event>
+      <string key="concept:name" value="Approve"/>
+      <date key="time:timestamp" value="2026-01-06T09:30:00.000Z"/>
+      <string key="org:resource" value="B. Kowalski"/>
+      <string key="lifecycle:transition" value="complete"/>
+    </event>
+  </trace>
+  <trace>
+    <string key="concept:name" value="case-3"/>
+    <string key="channel" value="phone"/>
+    <event>
+      <string key="concept:name" value="Create Order"/>
+      <date key="time:timestamp" value="2026-01-07T09:00:00.000Z"/>
+    </event>
+    <event>
+      <string key="concept:name" value="Ship Order"/>
+      <date key="time:timestamp" value="2026-01-07T09:20:00.000Z"/>
+      <string key="org:resource" value="Courier"/>
+    </event>
+  </trace>
+</log>

package/src/core/index.ts

@@ -116,3 +116,116 @@ export type { ProcessWorkerRequest, ProcessWorkerResponse } from "./worker/proce
 // EDGE_KEY_SEPARATOR — RM-050 (the edge-key convention abstraction and the
 // performance layer both index on; discovery has always used it internally)
 export { EDGE_KEY_SEPARATOR } from "./discover-graph";
+
+// activityColorScale — RM-054
+export {
+  ACTIVITY_COLOR_SLOTS,
+  ACTIVITY_OTHER_TOKEN,
+  activityColorScale,
+} from "./activity-color-scale";
+export type {
+  ActivityColor,
+  ActivityColorLegendEntry,
+  ActivityColorScale,
+} from "./activity-color-scale";
+
+// casesFromLog — RM-055
+export { casesFromLog } from "./cases-from-log";
+export type { CaseRow } from "./cases-from-log";
+
+// tokenReplay / conformance — RM-061
+export { liftHappyPath } from "./reference-model";
+export type {
+  HappyPath,
+  HappyPathStep,
+  ReplayModel,
+  ReplayTransition,
+  ReplayTransitionKind,
+} from "./reference-model";
+export {
+  DEVIATION_TYPES,
+  emptyDeviationCounts,
+  replayActivities,
+  replayTrace,
+  tokenReplay,
+} from "./token-replay";
+export type { Deviation, DeviationType, TraceReplayResult } from "./token-replay";
+export { conformanceRateSeries } from "./conformance";
+export type { ConformanceBucket, ConformanceRatePoint, ConformanceResult } from "./conformance";
+
+// fromXes — RM-063
+export { fromXes } from "./adapters/xes";
+export type { XesParseError, XesParseOptions, XesParseResult } from "./adapters/xes";
+
+// segments — RM-060
+export {
+  durationQuartile,
+  durationQuartileThresholds,
+  quartileOf,
+  segmentKey,
+  segmentOrderByFrequency,
+  segmentOrderForVariant,
+  segmentsFor,
+} from "./segments";
+export type {
+  DurationQuartile,
+  QuartileThresholds,
+  SegmentDefinition,
+  SegmentOccurrence,
+} from "./segments";
+
+// diffGraphs — RM-064
+export { diffGraphs } from "./diff-graphs";
+export type { DiffEntry, DiffState, ProcessGraphDiff } from "./diff-graphs";
+
+// replayTimeline — RM-065
+export {
+  defaultReplayBucketMs,
+  rankReplayCongestion,
+  REPLAY_MAX_FRAMES,
+  REPLAY_TARGET_FRAMES,
+  REPLAY_TOKEN_RADIUS_RANGE,
+  replayFrameAt,
+  replayTimeline,
+  replayTokenRadius,
+} from "./replay-timeline";
+export type {
+  ReplayCongestionEntry,
+  ReplayFrame,
+  ReplayFrameToken,
+  ReplaySegment,
+  ReplayTimeline,
+  ReplayTimelineOptions,
+} from "./replay-timeline";
+
+// Object-centric — RM-066
+export {
+  fromOcel,
+  OCEL_EVENT_ID_ATTRIBUTE,
+  OCEL_OBJECT_REFS_ATTRIBUTE,
+  readObjectRefs,
+} from "./adapters/ocel";
+export type {
+  OcelAttribute,
+  OcelEvent,
+  OcelJson,
+  OcelObject,
+  OcelParseError,
+  OcelParseOptions,
+  OcelParseResult,
+  OcelRelationship,
+  OcelTypeDeclaration,
+} from "./adapters/ocel";
+export {
+  abstractObjectCentricGraph,
+  discoverObjectCentricGraph,
+  mergeObjectCentricGraphs,
+  objectCentricProcessGraph,
+  objectTypeColorScale,
+} from "./discover-object-centric-graph";
+export type {
+  AbstractedObjectCentricGraph,
+  ObjectCentricActivityStats,
+  ObjectCentricGraph,
+  ObjectTypeActivityCounts,
+} from "./discover-object-centric-graph";

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: [],
+    });
+  });
+});