@elabs-ai/components-process 4.2.0 → 5.1.0

package/dist/core/index.d.ts

@@ -7,8 +7,8 @@
  * 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`.
+ * visx, d3 or an `@elabs-ai/components-*` package. See `.claude/rules/data.md` ("Process
+ * mining" section) and `pnpm check --rule process-reuse`.
  */
 /**
  * One raw row of an event log, before normalization.
@@ -1026,4 +1026,802 @@ type ProcessWorkerResponse = {
  */
 declare function handleProcessRequest(request: ProcessWorkerRequest): ProcessWorkerResponse;
 
-export { type AbstractedGraph, type AbstractionOptions, type ActivityRework, type ActivityStats, type AnyLog, BPI_2012_ACTIVITIES, BPI_2012_SUBSET_EPOCH, type Bpi2012Activity, type Bpi2012SubsetOptions, type CreateProcessWorkerOptions, type CsvMapping, type CsvOptions, DEFAULT_LIFECYCLE_VALUES, DURATION_SAMPLE_CAP, DURATION_UNIT_MS, type DiscoverGraphOptions, DurationSampler, type DurationStats, type DurationUnit, EDGE_KEY_SEPARATOR, EMPTY_DURATION_STATS, type EventLog, type EventRow, type FilterSpec, type FlatRow, type FlatRowMapping, type FlowTime, type FrequencyMode, type LifecycleValues, type NormalizedCase, type NormalizedEvent, type NormalizedLog, type PerformanceAgg, type PerformanceGraph, type PerformanceLayer, type PerformanceOptions, type ProcessGraph, type ProcessWorkerHandle, type ProcessWorkerLike, type ProcessWorkerRequest, type ProcessWorkerResponse, type ReconciledGraph, type ReworkStats, SYNTHETIC_ACTIVITIES, SYNTHETIC_LOG_EPOCH, type SyntheticActivity, type SyntheticLogOptions, TRIM_FRACTION, type TransitionStats, VARIANT_KEY_SEPARATOR, type Variant, abstractGraph, aggregatePerformance, asNormalizedLog, caseMatchesFilters, clampWidth, createProcessWorker, detectRework, discoverGraph, durationStats, emptyDurationStats, extractVariants, filterLog, filterNormalizedLog, fromCsv, fromFlatRows, generateBpi2012Subset, generateSyntheticLog, handleProcessRequest, isNormalizedLog, minMax, normalizeLifecycle, normalizeLog, parseDelimited, performanceValue, quantile, quantileSorted, reconcileGraph, toEpochMs, variantId, variantKey };
+/**
+ * Activity colour scale — RM-054.
+ *
+ * One activity, one colour, across every process view. `ProcessMap` paints the colour as
+ * a small accent mark on the activity node; `VariantExplorer` paints it on the sequence
+ * chips. Both read the SAME scale instance built from one graph, so "Create Order" is the
+ * same swatch in the map and in the variant list.
+ *
+ * ## The colour budget
+ *
+ * The chart palette ships twelve series tokens (`--chart-1` … `--chart-12`). The eleven
+ * most frequent activities (ranked by the number of cases they occur in) take
+ * `--chart-1` … `--chart-11`; every remaining activity shares `--chart-12` and is flagged
+ * `pattern: "other"`, which the views render as a hatch so "other" never reads as a
+ * twelfth distinct activity. Colour is never the only channel: every view that paints a
+ * swatch also prints the activity label (or its two-letter {@link ActivityColorScale.codeFor}
+ * code) as text.
+ *
+ * Pure and framework-free: returns token NAMES, never resolved colours, so a theme switch
+ * re-inks every swatch with no recomputation.
+ */
+
+/** How many activities get a distinct palette slot before the rest share "other". */
+declare const ACTIVITY_COLOR_SLOTS = 11;
+/** The token every activity outside the top {@link ACTIVITY_COLOR_SLOTS} shares. */
+declare const ACTIVITY_OTHER_TOKEN = "--chart-12";
+/** The colour one activity is painted with. */
+interface ActivityColor {
+    /** A CSS custom-property NAME, e.g. `"--chart-3"`. Paint with `var(${token})`. */
+    token: string;
+    /** Present for the shared "other" bucket — render the hatch, not a flat swatch. */
+    pattern?: "other";
+}
+/** One legend entry, in rank order. */
+interface ActivityColorLegendEntry extends ActivityColor {
+    activityId: string;
+    label: string;
+    /** A two-character code unique within the scale, for abbreviated ("DNA strip") chips. */
+    code: string;
+}
+/** The shared activity→colour mapping. */
+interface ActivityColorScale {
+    /** The colour for an activity. An id the graph never contained is "other". */
+    colorFor(activityId: string): ActivityColor;
+    /** The two-character code for an activity; derived from the id when it is unknown. */
+    codeFor(activityId: string): string;
+    /** The activity's display label; the id itself when it is unknown. */
+    labelFor(activityId: string): string;
+    /** Every activity in the graph, ranked by case count descending, ties by id. */
+    legend: ActivityColorLegendEntry[];
+}
+/**
+ * Build the shared colour scale for a graph.
+ *
+ * Deterministic: the same graph always yields the same assignment, regardless of the
+ * order `graph.activities` arrives in. Build it from the FULL (unfiltered, unabstracted)
+ * graph so colours stay put while a reader filters or abstracts.
+ */
+declare function activityColorScale(graph: ProcessGraph): ActivityColorScale;
+
+/**
+ * One case's own summary — its extent, size and path identity, not its trace. The shape
+ * `CaseTable` (case-table/) renders one row per, and `CaseTimeline`'s own model reads a
+ * single case's raw `EventRow[]` separately (a summary row has no per-activity detail to
+ * build a Gantt row from).
+ */
+interface CaseRow {
+    caseId: string;
+    /** ISO 8601. Empty string when the case has no resolvable extent — see `normalizeLog`. */
+    start: string;
+    end: string;
+    durationMs: number;
+    eventCount: number;
+    /** Identical to the `id` {@link extractVariants} assigns the SAME case over the SAME log. */
+    variantId: string;
+    /**
+     * Never set here: no conformance model lives in `/core` (`ProcessKpiStrip`'s own
+     * `conformance` prop treats it the same way — a fitted value the HOST supplies, never a
+     * number this package invents). A caller with a conformance result attaches it per row.
+     */
+    conformance?: "conforming" | "nonConforming" | "unknown";
+    /** Carried over from `EventLog.caseAttributes`, untouched. */
+    attributes?: Record<string, string | number | boolean | null>;
+}
+/**
+ * One summary row per case in `log`, in the same first-appearance order `normalizeLog`
+ * produces. `variantId` is sourced from {@link extractVariants} over the identical log —
+ * see the module docblock for why that, and not a direct `variantId(sequence)` call, is
+ * what keeps a `CaseTable` and a variant explorer over the same log always agreeing on
+ * which cases share a path.
+ *
+ * An empty log answers an empty array.
+ */
+declare function casesFromLog(log: EventLog): CaseRow[];
+
+/**
+ * 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. */
+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. */
+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.
+ */
+type ReplayTransitionKind = "step" | "skip" | "repeat";
+/** One transition of a {@link ReplayModel}. */
+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. */
+interface ReplayModel {
+    places: string[];
+    initialMarking: string[];
+    finalMarking: string[];
+    transitions: ReplayTransition[];
+}
+/**
+ * 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.
+ */
+declare function liftHappyPath(path: HappyPath): ReplayModel;
+
+/**
+ * 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.
+ */
+
+/** Log-level conformance of an event log against a reference model. */
+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. */
+type ConformanceBucket = "day" | "week" | "month";
+/** One point of {@link conformanceRateSeries}. */
+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;
+}
+/**
+ * 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.
+ */
+declare function conformanceRateSeries(log: AnyLog, model: ReplayModel, bucket: ConformanceBucket): ConformanceRatePoint[];
+
+/**
+ * Token-based replay — RM-061.
+ *
+ * Replays each case of an event log against a {@link ReplayModel} (a lifted happy path)
+ * and scores it with the classic produced / consumed / missing / remaining token counts:
+ *
+ *     fitness = ½ · (1 − missing / consumed) + ½ · (1 − remaining / produced)
+ *
+ * The replay procedure — seed the initial marking, fire an enabled transition per event,
+ * enable a disabled one through silent transitions first, force-insert missing tokens
+ * only when that fails, then consume the final marking and count what is left over —
+ * follows the token-based replay algorithm published in pm4js (BSD-3-Clause, credited in
+ * `scripts/attributions.sources.json`). It is re-typed in TypeScript for the restricted
+ * nets `liftHappyPath` builds; no pm4js code is copied, and nothing here derives from the
+ * AGPL Python reference implementation.
+ *
+ * Deviation typing is this module's own layer on top of the counts: every forced token
+ * (and every unreachable final token) is explained by at least one
+ * {@link Deviation}, so a violation list can say WHY a case lost fitness.
+ *
+ * Scope boundary (analysis §9 risk 2): no alignment search. Replay is greedy and
+ * single-pass per trace.
+ *
+ * Framework-free, deterministic: no React, no `@elabs-ai/components-*` import.
+ */
+
+/**
+ * Why a case lost fitness.
+ *
+ * - `undesired` — the activity is not in the model at all.
+ * - `skipped` — a required modelled activity was jumped over and never observed in the case.
+ * - `wrongOrder` — the activity is modelled but its preceding place was unmarked, and the
+ *   gap is not explained by an unobserved step (it ran too early, too late, or again).
+ * - `wrongStart` — the first event of the case is not one the initial marking enables.
+ * - `incomplete` — the case ended before reaching the model's final marking.
+ */
+type DeviationType = "undesired" | "skipped" | "wrongOrder" | "wrongStart" | "incomplete";
+/** Every {@link DeviationType}, in a stable display order. */
+declare const DEVIATION_TYPES: readonly DeviationType[];
+/** One deviation found while replaying a case. */
+interface Deviation {
+    type: DeviationType;
+    /**
+     * The activity the deviation is about: the observed event for `undesired`/`wrongOrder`/
+     * `wrongStart`, the missing step for `skipped`, the last observed event for `incomplete`.
+     */
+    activity?: string;
+    /** The activity the model expected next at that point, when one is determinable. */
+    expected?: string;
+    /**
+     * Zero-based index into the case's ordered trace of the event where the deviation was
+     * detected. `incomplete` uses the trace length (the position after the last event).
+     */
+    at: number;
+}
+/** Replay result for one case. */
+interface TraceReplayResult {
+    caseId: string;
+    produced: number;
+    consumed: number;
+    missing: number;
+    remaining: number;
+    /** `½(1 − missing/consumed) + ½(1 − remaining/produced)`, in `[0, 1]`. */
+    fitness: number;
+    deviations: Deviation[];
+}
+/**
+ * Replay an already-ordered activity sequence. The shared engine behind
+ * {@link replayTrace}, {@link tokenReplay} and `conformanceRateSeries`.
+ */
+declare function replayActivities(caseId: string, trace: readonly string[], model: ReplayModel): TraceReplayResult;
+/**
+ * Replay ONE case's raw rows against `model`.
+ *
+ * Rows are normalized first (ordered in time, lifecycle pairs merged into one instance),
+ * exactly as every other `/core` derivation sees them. The rows are expected to share one
+ * `caseId`; if they do not, every instance is replayed as one trace in start order under
+ * the first row's `caseId`.
+ */
+declare function replayTrace(events: EventRow[], model: ReplayModel): TraceReplayResult;
+/** A {@link DeviationType}-keyed tally with every type present at zero. */
+declare function emptyDeviationCounts(): Record<DeviationType, number>;
+/**
+ * Replay every case of `log` against `model` and fold the results.
+ *
+ * - `deviationCounts[type]` — total deviations of that type across all cases.
+ * - `perActivity[activity].deviations` — every deviation carries an activity, so these sum
+ *   to the total deviation count.
+ * - `perEdge[source + EDGE_KEY_SEPARATOR + target].deviations` — a deviation detected at an
+ *   event with a predecessor is charged to the OBSERVED directly-follows edge into that
+ *   event (the key `discoverGraph` uses for the same edge). A deviation at the first event
+ *   or at the end of the case has no edge, so these sum to at most the total.
+ * - `overallFitness` — mean trace fitness; `0` for an empty log.
+ */
+declare function tokenReplay(log: AnyLog, model: ReplayModel): ConformanceResult;
+
+/**
+ * XES adapter — RM-063.
+ *
+ * IEEE 1849-2016's interchange format for event logs: a `<log>` of `<trace>`s of
+ * `<event>`s, each carrying `key`/`value` attributes typed by their own element name
+ * (`string`, `date`, `int`, `float`, `boolean`). It is the format most public benchmark
+ * logs — including the BPI Challenge series RM-049's synthetic fixture is modelled on —
+ * actually ship in.
+ *
+ * Parsing is hand-rolled here on purpose, and NOT behind a `DOMParser` fast path:
+ * `/core` must run identically in Node, in a worker and in a browser main thread, and a
+ * parser this narrow — six element names, attribute-only values, the five standard XML
+ * entities, self-closing tags — does not need a general XML engine. `DOMParser` is
+ * unavailable in Node/workers anyway, and branching on its presence would leave one of
+ * the two code paths permanently untested. Do not reach for an XML dependency or
+ * `DOMParser` here; extend the tokenizer below instead.
+ */
+
+/** Options for {@link fromXes}. */
+interface XesParseOptions {
+    /**
+     * Event attribute keys that jointly identify an activity, applied in order and joined
+     * with `"+"` when there is more than one — the same semantics as an XES `<classifier>`
+     * element's `keys` attribute. Defaults to the log's own first `<classifier>`, or
+     * `["concept:name"]` when the log declares none.
+     */
+    classifiers?: string[];
+    /**
+     * How `lifecycle:transition` maps onto {@link EventRow.lifecycle}. `"standard"`
+     * (default) maps the literal value `"start"` to `"start"` and every other XES
+     * lifecycle value (`"complete"`, `"schedule"`, `"suspend"`, …) to `"complete"`;
+     * `"none"` ignores the attribute entirely, so every event stays atomic.
+     */
+    lifecycleModel?: "standard" | "none";
+}
+/** One recoverable problem found while reading a XES document. */
+interface XesParseError {
+    type: "malformed_xml" | "missing_trace" | "missing_concept_name" | "missing_timestamp";
+    message: string;
+    traceIndex?: number;
+    eventIndex?: number;
+}
+/**
+ * `fromXes`'s result — mirrors the worker's `{ ok: true, … } | { ok: false, … }` result
+ * convention (`worker/process-worker.ts`), because unlike `fromCsv`/`fromFlatRows` (which
+ * silently skip an incomplete row) a XES document can be genuinely malformed XML, which
+ * has nothing sound left to skip to.
+ */
+type XesParseResult = {
+    ok: true;
+    log: EventLog;
+} | {
+    ok: false;
+    errors: XesParseError[];
+};
+/**
+ * Read a IEEE 1849 XES document into an {@link EventLog}.
+ *
+ * Collects every recoverable problem (a trace with no events, an event missing its
+ * activity classifier key(s) or `time:timestamp`) rather than stopping at the first one;
+ * only malformed XML itself — which leaves nothing sound to keep reading — short-circuits
+ * with a single `malformed_xml` error. Output feeds directly into `normalizeLog`, exactly
+ * like `fromCsv`/`fromFlatRows` — no XES-specific branching downstream.
+ */
+declare function fromXes(source: string, options?: XesParseOptions): XesParseResult;
+
+/**
+ * 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-*`.
+ */
+
+/** One row of a spectrum: the directly-follows pair `from → to`. */
+interface SegmentDefinition {
+    from: string;
+    to: string;
+    /** Display label. Defaults to `"from → to"` in a view. */
+    label?: string;
+}
+/** One case passing through one segment. */
+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. */
+type DurationQuartile = 1 | 2 | 3 | 4;
+/** The three cut points (25th, 50th, 75th percentile) a quartile is read against. */
+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.
+ */
+declare function segmentKey(from: string, to: string): string;
+/**
+ * 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.
+ */
+declare function segmentsFor(log: AnyLog, order: readonly SegmentDefinition[]): SegmentOccurrence[];
+/**
+ * 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".
+ */
+declare function segmentOrderByFrequency(graph: ProcessGraph, limit?: number): SegmentDefinition[];
+/**
+ * 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.
+ */
+declare function segmentOrderForVariant(variant: Variant): SegmentDefinition[];
+/**
+ * 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.
+ */
+declare function durationQuartileThresholds(durations: readonly number[]): QuartileThresholds;
+/** Which quartile `duration` falls in, against precomputed thresholds (upper bounds inclusive). */
+declare function quartileOf(duration: number, thresholds: QuartileThresholds): DurationQuartile;
+/**
+ * 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.
+ */
+declare function durationQuartile(occurrence: SegmentOccurrence, allDurationsForSegment: readonly number[]): DurationQuartile;
+
+/** Which side(s) of the diff an activity or transition survives in. */
+type DiffState = "common" | "aOnly" | "bOnly";
+/** One activity's or transition's diff — its identity, its state, and (when `"common"`) its delta. */
+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. */
+interface ProcessGraphDiff {
+    activities: DiffEntry<ActivityStats>[];
+    transitions: DiffEntry<TransitionStats>[];
+    totals: {
+        a: ProcessGraph["totals"];
+        b: ProcessGraph["totals"];
+    };
+}
+/**
+ * Diff two discovered graphs. Neither input is mutated; the entries reference the original
+ * `ActivityStats`/`TransitionStats` objects, never copies.
+ */
+declare function diffGraphs(a: ProcessGraph, b: ProcessGraph): ProcessGraphDiff;
+
+/** One case travelling one edge. Times are relative to {@link ReplayTimeline.origin}. */
+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. */
+interface ReplayFrameToken {
+    caseId: string;
+    edgeId: string;
+    /** 0 at the source end, 1 at the target end. */
+    progress: number;
+}
+/** The replay at one playhead. */
+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}. */
+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. */
+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. */
+declare const REPLAY_TARGET_FRAMES = 300;
+/** Upper bound on frames; a finer `bucketMs` is widened to respect it. */
+declare const REPLAY_MAX_FRAMES = 5000;
+/** The default bucket: the log span over {@link REPLAY_TARGET_FRAMES}, at least 1 ms. */
+declare function defaultReplayBucketMs(duration: number): number;
+/**
+ * Bucket a log into replay frames.
+ *
+ * @example
+ * ```ts
+ * const timeline = replayTimeline(log, { synchronizedStart: true });
+ * const frame = replayFrameAt(timeline, timeline.duration / 2);
+ * ```
+ */
+declare function replayTimeline(log: AnyLog, options?: ReplayTimelineOptions): ReplayTimeline;
+/**
+ * The replay at any playhead — tokens at exactly `t` (not snapped), congestion from the
+ * bucket containing `t`. `t` is clamped to `[0, duration]`.
+ */
+declare function replayFrameAt(timeline: ReplayTimeline, t: number): ReplayFrame;
+/** One transition in {@link rankReplayCongestion}'s list. */
+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. */
+declare function rankReplayCongestion(timeline: ReplayTimeline, limit?: number): ReplayCongestionEntry[];
+/** Smallest and largest token radius, in px. */
+declare const REPLAY_TOKEN_RADIUS_RANGE: readonly [3, 8];
+/**
+ * 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.
+ */
+declare function replayTokenRadius(congestion: number, peak: number): number;
+
+/**
+ * OCEL 2.0 adapter — RM-066.
+ *
+ * The Object-Centric Event Log standard (OCEL 2.0, ocel-standard.org) drops the single
+ * case notion: an event references any number of OBJECTS of any number of object TYPES
+ * (`order`, `item`, `package`, …). This adapter reads the standard's JSON serialization
+ * and FLATTENS it once per object type — the projection every object-centric
+ * directly-follows graph starts from: for object type `T`, every object of type `T` is a
+ * case, and every event that references that object is one row of that case.
+ *
+ * ## JSON only, on purpose
+ *
+ * OCEL 2.0 also ships as XML and SQLite. Only JSON is read here: it needs nothing beyond
+ * `JSON.parse`, which runs identically in Node, a worker and a browser main thread, and
+ * `/core` takes no parser dependency (the same format-choice precedent `fromXes` set in
+ * RM-063). SQLite would need a WASM engine; XML would need a second hand-rolled tokenizer
+ * for a format whose producers all also emit JSON. Convert an XML/SQLite log to JSON with
+ * the producing tool first.
+ *
+ * ## What survives the flattening
+ *
+ * Each emitted {@link EventRow} carries two reserved attributes so the object-centric
+ * discovery step can re-merge the projections:
+ *
+ * - `__ocelEventId` — the OCEL event's own id, so a shared activity is counted once per
+ *   EVENT rather than once per referenced object;
+ * - `__objectRefs` — the event's full object map (`{ order: ["o1"], item: ["i1", "i2"] }`),
+ *   JSON-encoded because `EventRow.attributes` values are scalars by contract (RM-049's
+ *   frozen types). Read it back with {@link readObjectRefs}.
+ */
+
+/** One `{ name, … }` type declaration (`objectTypes` / `eventTypes`). */
+interface OcelTypeDeclaration {
+    name: string;
+    attributes?: {
+        name: string;
+        type?: string;
+    }[];
+}
+/** An event or object attribute value. Object attributes carry a `time` (they can change). */
+interface OcelAttribute {
+    name: string;
+    value: string | number | boolean | null;
+    time?: string;
+}
+/** A qualified reference from an event (or object) to an object. */
+interface OcelRelationship {
+    objectId: string;
+    qualifier?: string;
+}
+/** One OCEL 2.0 event. `type` is the activity; `time` is an ISO-8601 timestamp. */
+interface OcelEvent {
+    id: string;
+    type: string;
+    time: string;
+    attributes?: OcelAttribute[];
+    relationships?: OcelRelationship[];
+}
+/** One OCEL 2.0 object. */
+interface OcelObject {
+    id: string;
+    type: string;
+    attributes?: OcelAttribute[];
+    relationships?: OcelRelationship[];
+}
+/** An OCEL 2.0 JSON document (OCEL 2.0 specification, JSON serialization). */
+interface OcelJson {
+    objectTypes: OcelTypeDeclaration[];
+    eventTypes?: OcelTypeDeclaration[];
+    objects: OcelObject[];
+    events: OcelEvent[];
+}
+/** Options for {@link fromOcel}. */
+interface OcelParseOptions {
+    /**
+     * Which object types to project a log for, in output order. Defaults to every declared
+     * object type, in declaration order. Naming an undeclared type is an error.
+     */
+    objectTypes?: string[];
+}
+/** One problem found while reading an OCEL 2.0 document. */
+interface OcelParseError {
+    type: "malformed_json" | "invalid_document" | "missing_event_id" | "missing_event_type" | "missing_timestamp" | "unknown_object" | "unknown_object_type";
+    message: string;
+    eventIndex?: number;
+    objectIndex?: number;
+}
+/**
+ * `fromOcel`'s result — the same `{ ok: true, … } | { ok: false, errors }` shape as
+ * `fromXes`. `logs` is keyed by object type; `activities` lists every event type that
+ * occurs, in first-appearance order; `objectTypes` is the projected types, in order.
+ */
+type OcelParseResult = {
+    ok: true;
+    logs: Record<string, EventLog>;
+    activities: string[];
+    objectTypes: string[];
+} | {
+    ok: false;
+    errors: OcelParseError[];
+};
+/** The reserved attribute holding an emitted row's OCEL event id. */
+declare const OCEL_EVENT_ID_ATTRIBUTE = "__ocelEventId";
+/** The reserved attribute holding an emitted row's JSON-encoded object map. */
+declare const OCEL_OBJECT_REFS_ATTRIBUTE = "__objectRefs";
+/**
+ * Read an OCEL 2.0 JSON document (a string, or an already-parsed object) into one
+ * {@link EventLog} per object type.
+ *
+ * Collects every per-event problem (a missing id, type or parsable `time`; a relationship
+ * to an object the document never declares) rather than stopping at the first; only a
+ * document that is not JSON, or not shaped like OCEL at all, short-circuits. Any error
+ * fails the whole read — a silently-dropped event would change every count downstream.
+ */
+declare function fromOcel(input: string | OcelJson, options?: OcelParseOptions): OcelParseResult;
+/**
+ * The object map an emitted row was flattened from (`{ order: ["o1"], item: ["i1"] }`), or
+ * `undefined` for a row that did not come from {@link fromOcel}.
+ */
+declare function readObjectRefs(row: EventRow): Record<string, string[]> | undefined;
+
+/**
+ * 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.
+ */
+
+/** One object type's share of a merged activity. */
+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. */
+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. */
+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. */
+interface AbstractedObjectCentricGraph extends ObjectCentricGraph {
+    hiddenByType: Record<string, {
+        activities: number;
+        paths: number;
+    }>;
+}
+/**
+ * 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.
+ */
+declare function mergeObjectCentricGraphs(graphsByType: Record<string, ProcessGraph>, objectTypes?: readonly string[], eventCounts?: ReadonlyMap<string, number>): ObjectCentricGraph;
+/**
+ * Discover an {@link ObjectCentricGraph} from per-object-type logs (typically
+ * `fromOcel(…).logs`). Runs `discoverGraph` once per type, then merges.
+ */
+declare function discoverObjectCentricGraph(logsByType: Record<string, EventLog>, options?: DiscoverGraphOptions & {
+    objectTypes?: string[];
+}): ObjectCentricGraph;
+/**
+ * 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.
+ */
+declare function abstractObjectCentricGraph(graph: ObjectCentricGraph, perType?: Readonly<Record<string, AbstractionOptions>>, fallback?: AbstractionOptions): AbstractedObjectCentricGraph;
+/**
+ * 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.
+ */
+declare function objectCentricProcessGraph(graph: ObjectCentricGraph): ProcessGraph;
+/**
+ * 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.
+ */
+declare function objectTypeColorScale(graph: ObjectCentricGraph): ActivityColorScale;
+
+export { ACTIVITY_COLOR_SLOTS, ACTIVITY_OTHER_TOKEN, type AbstractedGraph, type AbstractedObjectCentricGraph, type AbstractionOptions, type ActivityColor, type ActivityColorLegendEntry, type ActivityColorScale, type ActivityRework, type ActivityStats, type AnyLog, BPI_2012_ACTIVITIES, BPI_2012_SUBSET_EPOCH, type Bpi2012Activity, type Bpi2012SubsetOptions, type CaseRow, type ConformanceBucket, type ConformanceRatePoint, type ConformanceResult, type CreateProcessWorkerOptions, type CsvMapping, type CsvOptions, DEFAULT_LIFECYCLE_VALUES, DEVIATION_TYPES, DURATION_SAMPLE_CAP, DURATION_UNIT_MS, type Deviation, type DeviationType, type DiffEntry, type DiffState, type DiscoverGraphOptions, type DurationQuartile, DurationSampler, type DurationStats, type DurationUnit, EDGE_KEY_SEPARATOR, EMPTY_DURATION_STATS, type EventLog, type EventRow, type FilterSpec, type FlatRow, type FlatRowMapping, type FlowTime, type FrequencyMode, type HappyPath, type HappyPathStep, type LifecycleValues, type NormalizedCase, type NormalizedEvent, type NormalizedLog, OCEL_EVENT_ID_ATTRIBUTE, OCEL_OBJECT_REFS_ATTRIBUTE, type ObjectCentricActivityStats, type ObjectCentricGraph, type ObjectTypeActivityCounts, type OcelAttribute, type OcelEvent, type OcelJson, type OcelObject, type OcelParseError, type OcelParseOptions, type OcelParseResult, type OcelRelationship, type OcelTypeDeclaration, type PerformanceAgg, type PerformanceGraph, type PerformanceLayer, type PerformanceOptions, type ProcessGraph, type ProcessGraphDiff, type ProcessWorkerHandle, type ProcessWorkerLike, type ProcessWorkerRequest, type ProcessWorkerResponse, type QuartileThresholds, REPLAY_MAX_FRAMES, REPLAY_TARGET_FRAMES, REPLAY_TOKEN_RADIUS_RANGE, type ReconciledGraph, type ReplayCongestionEntry, type ReplayFrame, type ReplayFrameToken, type ReplayModel, type ReplaySegment, type ReplayTimeline, type ReplayTimelineOptions, type ReplayTransition, type ReplayTransitionKind, type ReworkStats, SYNTHETIC_ACTIVITIES, SYNTHETIC_LOG_EPOCH, type SegmentDefinition, type SegmentOccurrence, type SyntheticActivity, type SyntheticLogOptions, TRIM_FRACTION, type TraceReplayResult, type TransitionStats, VARIANT_KEY_SEPARATOR, type Variant, type XesParseError, type XesParseOptions, type XesParseResult, abstractGraph, abstractObjectCentricGraph, activityColorScale, aggregatePerformance, asNormalizedLog, caseMatchesFilters, casesFromLog, clampWidth, conformanceRateSeries, createProcessWorker, defaultReplayBucketMs, detectRework, diffGraphs, discoverGraph, discoverObjectCentricGraph, durationQuartile, durationQuartileThresholds, durationStats, emptyDeviationCounts, emptyDurationStats, extractVariants, filterLog, filterNormalizedLog, fromCsv, fromFlatRows, fromOcel, fromXes, generateBpi2012Subset, generateSyntheticLog, handleProcessRequest, isNormalizedLog, liftHappyPath, mergeObjectCentricGraphs, minMax, normalizeLifecycle, normalizeLog, objectCentricProcessGraph, objectTypeColorScale, parseDelimited, performanceValue, quantile, quantileSorted, quartileOf, rankReplayCongestion, readObjectRefs, reconcileGraph, replayActivities, replayFrameAt, replayTimeline, replayTokenRadius, replayTrace, segmentKey, segmentOrderByFrequency, segmentOrderForVariant, segmentsFor, toEpochMs, tokenReplay, variantId, variantKey };