@elabs-ai/components-process 4.1.0

package/dist/core/index.d.ts

@@ -0,0 +1,1029 @@
+/**
+ * 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.
+ */
+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`. */
+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.
+ */
+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. */
+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). */
+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. */
+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. */
+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. */
+type FrequencyMode = "absolute" | "absolute_case" | "relative" | "relative_case" | "relative_antecedent" | "relative_consequent" | "max_repetitions";
+/** Which member of a {@link DurationStats} a performance view reads. */
+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.
+ */
+type FlowTime = "idle_time" | "inter_start_time";
+
+/**
+ * Event-log normalization — RM-049.
+ *
+ * Turns a flat `EventRow[]` into per-case traces of INSTANCES: one entry per real
+ * activity execution, carrying a resolved `start` and `end` in epoch milliseconds. Every
+ * other module in `/core` consumes the normalized form, so the messy parts of a raw log
+ * (three timestamp encodings, lifecycle rows split across two lines, rows arriving out of
+ * order) are handled exactly once, here.
+ *
+ * Deterministic: same rows in, same traces out. No `Date.now()`, no randomness.
+ */
+
+/** One activity execution, with both ends resolved to epoch milliseconds. */
+interface NormalizedEvent {
+    activity: string;
+    /**
+     * Start of the execution. Equals `end` for an atomic event — an event with no
+     * `lifecycle` pair and no `startTimestamp` has no observed duration, and inventing one
+     * would put fabricated numbers into every downstream statistic.
+     */
+    start: number;
+    /** Completion of the execution. */
+    end: number;
+    /** `end - start`, never negative (a clock-skewed pair is floored at 0). */
+    duration: number;
+    resource?: string;
+    attributes?: Record<string, string | number | boolean | null>;
+    /**
+     * True when this instance came from a `lifecycle: "start"` row that never got a
+     * matching `"complete"`. Its `end` is provisional (it equals `start`), so a performance
+     * view can choose to exclude it.
+     */
+    isOpen: boolean;
+}
+/** One case (process instance): its trace, plus the case's own extent. */
+interface NormalizedCase {
+    caseId: string;
+    /** Instances in ascending `start` order. Never empty. */
+    events: NormalizedEvent[];
+    /** Earliest `start` in the trace. */
+    start: number;
+    /** Latest `end` in the trace. */
+    end: number;
+    /** `end - start` — the case's throughput time. */
+    duration: number;
+    /** Per-case attributes carried over from `EventLog.caseAttributes`, when present. */
+    attributes?: Record<string, unknown>;
+}
+/** A normalized log: cases in first-appearance order, plus totals. */
+interface NormalizedLog {
+    cases: NormalizedCase[];
+    totals: {
+        cases: number;
+        events: number;
+    };
+}
+/** A log in either shape. Every derivation entry point accepts both. */
+type AnyLog = EventLog | NormalizedLog;
+/** Narrowing predicate — `true` when `log` has already been through {@link normalizeLog}. */
+declare function isNormalizedLog(log: AnyLog): log is NormalizedLog;
+/** Normalize `log` unless it already is normalized. The idempotent entry point. */
+declare function asNormalizedLog(log: AnyLog): NormalizedLog;
+/**
+ * Resolve the three accepted timestamp encodings to epoch milliseconds.
+ *
+ * Returns `NaN` for an unparseable value rather than throwing: one bad cell in a
+ * ten-thousand-row CSV must not abort the whole import. Downstream, a `NaN` sorts as
+ * equal (so the row keeps its input position) and is dropped from duration samples.
+ */
+declare function toEpochMs(value: string | number | Date | undefined | null): number;
+/**
+ * Group rows by case, order each case in time, and pair `lifecycle` rows into instances.
+ *
+ * The pairing rule, stated precisely because five downstream items depend on it:
+ *
+ * - Rows are grouped by `caseId` in ONE pass and each case is sorted independently. The
+ *   whole log is never sorted — sorting 200 000 rows to then split them is the shape that
+ *   makes a browser import feel broken.
+ * - A `lifecycle: "start"` row OPENS an instance at its position in the case's timeline.
+ * - A `lifecycle: "complete"` row CLOSES the oldest still-open instance of the SAME
+ *   activity, wherever that start sits in the trace. The two rows therefore do not have
+ *   to be adjacent: interleaved `A-start, B-start, A-complete, B-complete` pairs
+ *   correctly, and so does a log whose rows arrive in the wrong order entirely, because
+ *   the per-case sort runs first.
+ * - Repeated executions of one activity in a case pair oldest-start-to-earliest-complete
+ *   (FIFO), which is the only pairing that keeps intervals non-overlapping for a
+ *   sequential resource.
+ * - A `"complete"` with no open start becomes an instance in its own right, using an
+ *   explicit `startTimestamp` when the row carries one.
+ * - A `"start"` that is never completed stays OPEN: `end === start` and `isOpen` is true.
+ * - A row with no `lifecycle` is atomic: `start` comes from `startTimestamp` when given,
+ *   otherwise from `timestamp` itself.
+ *
+ * Rows with an empty `caseId` or `activity` are dropped — they cannot take part in a
+ * directly-follows relation, and keeping them would put an unnamed node in every graph.
+ */
+declare function normalizeLog(log: EventLog): NormalizedLog;
+
+/**
+ * Flat tabular adapter — RM-049.
+ *
+ * Pre-shaped tabular data is the lingua franca of event logs: whatever the source (a
+ * warehouse query, a spreadsheet export, an API page), it arrives as rows of columns. This
+ * adapter maps those columns onto `EventRow`, so every other importer — the CSV reader
+ * next door, and any future one — can be a thin front end over this single mapping step
+ * rather than a second, subtly different interpretation of the same log.
+ *
+ * Pure and deterministic: no clock, no I/O, no mutation of the caller's rows.
+ */
+
+/** One row of a flat source. Values are read defensively — a source may hand back anything. */
+type FlatRow = Record<string, unknown>;
+/** Which raw cell to read a lifecycle transition's `"start"` / `"complete"` from. */
+interface LifecycleValues {
+    start?: readonly string[];
+    complete?: readonly string[];
+}
+/** Column names that `fromFlatRows` reads. Only `caseId`, `activity` and `timestamp` are required. */
+interface FlatRowMapping {
+    /** Column holding the case (process instance) id. */
+    caseId: string;
+    /** Column holding the activity name. */
+    activity: string;
+    /** Column holding the event timestamp. */
+    timestamp: string;
+    /** Column holding an explicit interval start, when the source models one. */
+    startTimestamp?: string;
+    /** Column holding the executing resource. */
+    resource?: string;
+    /** Column holding a lifecycle transition. */
+    lifecycle?: string;
+    /** Extra columns copied verbatim into `EventRow.attributes`. */
+    attributes?: readonly string[];
+    /**
+     * Columns copied into `EventLog.caseAttributes`, taking the FIRST non-empty value seen
+     * per case. Case attributes are case-level by definition, so a later row disagreeing
+     * with an earlier one is a data problem, not something an adapter should silently
+     * resolve by overwriting.
+     */
+    caseAttributes?: readonly string[];
+    /**
+     * Raw cell values that mean `"start"` / `"complete"`, compared case-insensitively after
+     * trimming. Defaults to {@link DEFAULT_LIFECYCLE_VALUES}; supply your own for a source
+     * that spells them differently (`"S"` / `"C"`, `"begin"` / `"done"`).
+     */
+    lifecycleValues?: LifecycleValues;
+}
+/** The lifecycle spellings recognized when a mapping does not override them. */
+declare const DEFAULT_LIFECYCLE_VALUES: Required<LifecycleValues>;
+/** Map a raw lifecycle cell onto the canonical pair, or `undefined` when it matches neither. */
+declare function normalizeLifecycle(raw: string | undefined, values?: LifecycleValues): "start" | "complete" | undefined;
+/**
+ * Map flat rows onto an {@link EventLog}.
+ *
+ * Rows missing a case id, an activity or a timestamp are SKIPPED rather than throwing: a
+ * single blank trailing line or one incomplete record must not fail an entire import, and
+ * an event with no activity cannot take part in a directly-follows relation anyway. Count
+ * the difference between `rows.length` and `log.events.length` when you need to surface
+ * how many were dropped.
+ */
+declare function fromFlatRows(rows: readonly FlatRow[], mapping: FlatRowMapping): EventLog;
+
+/**
+ * CSV adapter — RM-049.
+ *
+ * A minimal RFC 4180 reader plus a thin front end onto {@link fromFlatRows}. It is written
+ * here rather than pulled from npm on purpose: `/core` is the framework-free,
+ * worker-safe leaf, and a parser this small (quoted fields, escaped quotes, embedded
+ * newlines, CRLF, a BOM) does not justify a runtime dependency in a package a consumer
+ * imports into a web worker.
+ *
+ * What it deliberately does NOT do: type inference, header de-duplication, streaming, or
+ * dialect sniffing. A source that needs any of those parses itself and calls
+ * {@link fromFlatRows} with the rows.
+ */
+
+/** Options for {@link parseDelimited} and {@link fromCsv}. */
+interface CsvOptions {
+    /** Field separator. Defaults to `","`; pass `"\t"` for TSV, `";"` for a European export. */
+    delimiter?: string;
+    /**
+     * Column names, when the text has NO header row. Omit for the usual case, where the
+     * first record is the header.
+     */
+    header?: readonly string[];
+}
+/** Everything `fromCsv` needs: the column mapping plus the dialect. */
+type CsvMapping = FlatRowMapping & CsvOptions;
+/**
+ * Parse RFC 4180 delimited text into records of raw string fields.
+ *
+ * Handles: quoted fields; a doubled `""` inside a quoted field as one literal quote;
+ * delimiters, `CR`, `LF` and `CRLF` inside a quoted field; `CRLF` or bare `LF` record
+ * separators; a leading UTF-8 BOM; and a trailing newline (which does NOT produce a
+ * phantom empty record).
+ *
+ * A field is returned exactly as written, without trimming — trimming is a MAPPING
+ * decision, and `fromFlatRows` makes it. Unterminated quotes are tolerated: the field runs
+ * to the end of the text rather than throwing, so a truncated download yields the rows it
+ * did contain.
+ */
+declare function parseDelimited(text: string, delimiter?: string): string[][];
+/**
+ * Read delimited text into an {@link EventLog}.
+ *
+ * The first record is the header unless `mapping.header` supplies one. Column names in
+ * the header are trimmed (a `", activity"` from a hand-edited export still matches
+ * `activity`); field VALUES are not, so `fromFlatRows` stays the only place that decides
+ * what an empty cell means.
+ *
+ * Empty text yields an empty log rather than throwing.
+ */
+declare function fromCsv(text: string, mapping: CsvMapping): EventLog;
+
+/**
+ * Separator used to key an edge. The same C0 control character the variant key uses, and
+ * for the same reason: no activity name can contain it, so `source + SEP + target` is an
+ * injective key.
+ */
+declare const EDGE_KEY_SEPARATOR = "\u0001";
+/** Options for {@link discoverGraph}. Every field has a default; `discoverGraph(log)` works. */
+interface DiscoverGraphOptions {
+    /**
+     * Which elapsed time an edge measures. Defaults to `"idle_time"` — the wait between the
+     * source completing and the target starting, which is the number a bottleneck view
+     * wants. For a log of atomic events the two choices coincide.
+     */
+    flowTime?: FlowTime;
+    /**
+     * Reservoir capacity per activity and per edge. Lower it for a very wide log; raise it
+     * for sharper tail statistics. `sum`/`mean`/`min`/`max` stay exact regardless.
+     */
+    maxDurationSamples?: number;
+}
+/**
+ * Derive a {@link ProcessGraph} from a raw or already-normalized log.
+ *
+ * One pass per trace: each case's activity sequence is walked once, incrementing
+ * per-activity and per-edge counters and feeding two duration samplers. Per-case
+ * uniqueness (the `cases` and `caseCount` fields) is tracked with two `Set`s that are
+ * cleared per case rather than a per-key `Set` of case ids, so memory stays proportional
+ * to the widest trace, not to the log.
+ *
+ * `totals.variants` is counted from the same walk (the joined activity sequence goes into
+ * a `Set`), so a caller that only needs the headline number does not also have to run
+ * `extractVariants`.
+ */
+declare function discoverGraph(log: AnyLog, options?: DiscoverGraphOptions): ProcessGraph;
+
+/**
+ * Separator joining a sequence into its variant key.
+ *
+ * U+0001 (START OF HEADING) is a C0 control character. No real activity name contains
+ * one, which is what makes joining on it lossless where a printable separator
+ * (`" -> "`, `","`) would collide with a name that happens to contain the separator.
+ */
+declare const VARIANT_KEY_SEPARATOR = "\u0001";
+/** Join an activity sequence into its canonical variant key. */
+declare function variantKey(sequence: readonly string[]): string;
+/**
+ * The stable id for an activity sequence: `v` followed by 64 bits of FNV-1a over the
+ * variant key, as hex.
+ *
+ * Exported because a selection is a wave-wide concern — RM-052's variant explorer and
+ * RM-053's case table both need to name the same variant without holding the object, and
+ * a hash of the sequence is the only identifier that survives a re-run, a worker boundary
+ * and a URL.
+ */
+declare function variantId(sequence: readonly string[]): string;
+/**
+ * Group `log`'s cases into variants, ranked by frequency.
+ *
+ * Ordering is `count` descending, ties broken by the variant key ascending — a total
+ * order, so the same log always produces the same array in the same positions.
+ *
+ * `share` is `count / cases`. `cumulativeShare` is the running `cumulativeCount / cases`,
+ * which is monotonically non-decreasing by construction and exactly `1` on the last
+ * entry. `duration` summarizes the END-TO-END case durations of the variant's cases, so
+ * it answers "how long does this path take", not "how long does one step take".
+ *
+ * An empty log yields an empty array — never a single zero-count variant.
+ */
+declare function extractVariants(log: AnyLog): Variant[];
+
+/** The fraction discarded from EACH tail by `trimmedMean`. */
+declare const TRIM_FRACTION = 0.1;
+/** All-zero statistics — the answer for an empty sample set. */
+declare const EMPTY_DURATION_STATS: Readonly<DurationStats>;
+/** A fresh mutable copy of {@link EMPTY_DURATION_STATS}. */
+declare function emptyDurationStats(): DurationStats;
+/**
+ * Summarize `samples` (milliseconds) as {@link DurationStats}.
+ *
+ * - Non-finite samples are DROPPED, not propagated — one unparseable timestamp upstream
+ *   must not turn an entire activity's statistics into `NaN`.
+ * - The input array is not mutated (a copy is sorted).
+ * - `p90` uses linear interpolation between order statistics (R-7 / `d3.quantile`).
+ * - `trimmedMean` discards the lowest and highest {@link TRIM_FRACTION} of samples. When
+ *   trimming would leave nothing (fewer than 5 samples, where `floor(n * 0.1)` is 0 or
+ *   the tails meet), it degrades to the plain mean rather than to `NaN`.
+ * - An empty (or all-non-finite) input answers all zeros.
+ */
+declare function durationStats(samples: readonly number[]): DurationStats;
+/** Default reservoir capacity for a single activity's or edge's duration samples. */
+declare const DURATION_SAMPLE_CAP = 4096;
+/**
+ * Bounded duration-sample collector.
+ *
+ * A log with a million events would otherwise hold a million numbers per hot edge just to
+ * compute seven statistics from them. The first {@link DURATION_SAMPLE_CAP} samples are
+ * kept outright; past the cap the collector switches to reservoir sampling (Algorithm R),
+ * so the retained set stays a uniform sample of everything seen while memory stays flat.
+ *
+ * `count` keeps the TRUE number of samples offered, and `sum` the true total, so a
+ * capped edge still reports an exact `sum` and an exact `mean`; only the order statistics
+ * (`median`, `p90`, `min`, `max`, `trimmedMean`) are estimated from the reservoir.
+ */
+declare class DurationSampler {
+    private readonly capacity;
+    private readonly random;
+    private readonly reservoir;
+    /** Number of finite samples offered, including those the reservoir discarded. */
+    private seen;
+    private total;
+    private lowest;
+    private highest;
+    constructor(seed?: number, capacity?: number);
+    /** Offer one sample. Non-finite values are ignored. */
+    add(sample: number): void;
+    /** True number of finite samples offered. */
+    get size(): number;
+    /**
+     * Summarize what was collected. `sum`, `mean`, `min` and `max` are EXACT even past the
+     * cap (they are accumulated, not read off the reservoir); the remaining three are
+     * computed from the retained sample.
+     */
+    stats(): DurationStats;
+}
+
+/**
+ * The extent of `values`, ignoring non-finite entries.
+ *
+ * @returns `[min, max]`, or `[0, 0]` when there is nothing finite to measure.
+ */
+declare function minMax(values: readonly number[]): [number, number];
+/**
+ * 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.
+ */
+declare function quantileSorted(sorted: readonly number[], q: number): number;
+/**
+ * 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`.
+ */
+declare function quantile(values: readonly number[], q: number): number;
+/**
+ * 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.
+ */
+declare function clampWidth(value: number, domain: readonly [number, number], range: readonly [number, number]): number;
+
+/**
+ * Seeded synthetic event-log generator — RM-049.
+ *
+ * Produces an order-to-cash shaped log — a happy path, two exception branches, a rework
+ * loop back to an earlier activity, an occasional repeat of one step, and a step-order
+ * swap — at any size, from a seed. That is what lets tests, stories and benchmarks work
+ * with a realistically messy log without this repo ever shipping a large binary fixture,
+ * and without any of them depending on a wall clock.
+ *
+ * Determinism is the whole contract: `generateSyntheticLog({ cases: n, seed: s })` returns
+ * a byte-identical log on every run, in every engine, forever. Downstream items snapshot
+ * against it.
+ */
+
+/** Epoch ms the first case starts at: 2026-01-05T08:00:00.000Z, a Monday morning. */
+declare const SYNTHETIC_LOG_EPOCH = 1767600000000;
+/** Options for {@link generateSyntheticLog}. */
+interface SyntheticLogOptions {
+    /** How many cases to generate. Values below 1 yield an empty log. */
+    cases: number;
+    /** PRNG seed. The same seed always produces the same log. */
+    seed?: number;
+    /** Epoch ms the first case starts at. Defaults to {@link SYNTHETIC_LOG_EPOCH}. */
+    startTime?: number;
+}
+/** Activity vocabulary. Exported so a story can label or colour by name without guessing. */
+declare const SYNTHETIC_ACTIVITIES: readonly ["Create Order", "Check Credit", "Amend Order", "Approve Order", "Reject Order", "Reserve Stock", "Cancel Order", "Pick Items", "Ship Order", "Send Invoice", "Receive Payment"];
+/** One activity name from {@link SYNTHETIC_ACTIVITIES}. */
+type SyntheticActivity = (typeof SYNTHETIC_ACTIVITIES)[number];
+/**
+ * Generate a synthetic order-to-cash log.
+ *
+ * Every event is an INTERVAL event: it carries both a `startTimestamp` and a `timestamp`,
+ * so activity durations and edge idle times are both non-zero and a performance view has
+ * something real to show. Timestamps are epoch numbers rather than ISO strings — a
+ * 13 000-case log is a quarter of a million rows, and making a benchmark of the discovery
+ * pass mostly measure `Date.parse` would be measuring the wrong thing.
+ *
+ * Cases are emitted in order, one per `caseId` of the form `case-00001`, zero-padded so
+ * lexical and numeric order agree.
+ */
+declare function generateSyntheticLog(options: SyntheticLogOptions): EventLog;
+
+/**
+ * Seeded BPI-2012-shaped event-log generator — RM-053.
+ *
+ * A SEPARATE generator from `synthetic-log.ts` (RM-049), not a second copy of it: RM-049's
+ * `generateSyntheticLog` produces an order-to-cash shaped log (Create Order, Check Credit,
+ * Ship Order, …); this one produces a log shaped like the public BPI Challenge 2012 event
+ * log (van Dongen, 2012) — a Dutch financial institution's loan-application process, whose
+ * activity vocabulary follows the dataset's own three-lifecycle-prefix convention
+ * (`A_` application state, `O_` offer state, `W_` work item). The BPI Challenge datasets are
+ * a public academic research corpus published for the annual Business Process Intelligence
+ * Challenge; naming one here names a published research artifact, not a commercial vendor.
+ *
+ * This is what analysis §4 R21 asks for: a ~13,000-case fixture large enough to exercise
+ * `discoverGraph`'s performance budget (already covered by RM-049's own
+ * `generateSyntheticLog({ cases: 13_000 })` in `discover-graph.test.ts`) and, from RM-051
+ * onward, a Storybook "LargeGraph" story that wants a visually denser, more tangled graph
+ * than the order-to-cash shape produces (more branching, more rework, a wider activity
+ * vocabulary).
+ *
+ * Determinism is the whole contract, exactly as in `synthetic-log.ts`:
+ * `generateBpi2012Subset({ cases: n, seed: s })` returns a byte-identical log on every run.
+ *
+ * ## This module is BROWSER-SAFE — no Node built-ins
+ *
+ * Deliberately: `discoverGraph`/`extractVariants` demos (the RM-053 placeholder Storybook
+ * story, and any future browser-rendered fixture preview) import this module directly, and
+ * Storybook's story tests run in a real browser (`@storybook/addon-vitest`'s Playwright
+ * provider) where `node:fs`/`node:path`/`node:url` are externalized and throw on access. So
+ * this file exports the PURE generator only — no filesystem write, no `import.meta.url`
+ * resolution, no `process.argv` read. The file that writes the on-disk fixture is the
+ * sibling `generate-bpi-2012-subset.write.ts` (see below), which is the only place those
+ * Node-only imports appear.
+ *
+ * ## Producing the on-disk fixture
+ *
+ * The 13k-case output is a ~250k-row JSON document — too large to commit as a binary (see
+ * the repo's "no committed large binary fixture" convention, already followed by
+ * `synthetic-log.ts`). It is a GENERATED artifact: run
+ *
+ * ```
+ * pnpm --filter @elabs-ai/components-process generate:fixtures
+ * ```
+ *
+ * which writes `bpi-2012-subset.json` next to this file (git-ignored — see the repo root
+ * `.gitignore`), via `generate-bpi-2012-subset.write.ts` (run through `vitest`, not `tsx` —
+ * see that file's docblock for why). A consumer of the generated JSON should treat it as a
+ * build artifact, not a checked-in fixture; import {@link generateBpi2012Subset} directly
+ * wherever possible instead of reading the file.
+ */
+
+/** Epoch ms the first case starts at: 2012-01-02T08:00:00.000Z, a Monday morning. */
+declare const BPI_2012_SUBSET_EPOCH = 1325487600000;
+/** Options for {@link generateBpi2012Subset}. */
+interface Bpi2012SubsetOptions {
+    /** How many cases to generate. Values below 1 yield an empty log. */
+    cases: number;
+    /** PRNG seed. The same seed always produces the same log. */
+    seed?: number;
+    /** Epoch ms the first case starts at. Defaults to {@link BPI_2012_SUBSET_EPOCH}. */
+    startTime?: number;
+}
+/**
+ * Activity vocabulary, following the public BPI Challenge 2012 log's own naming convention:
+ * `A_` (application), `O_` (offer) and `W_` (work item) lifecycle prefixes.
+ */
+declare const BPI_2012_ACTIVITIES: readonly ["A_SUBMITTED", "A_PARTLYSUBMITTED", "A_PREACCEPTED", "W_Completeren aanvraag", "A_ACCEPTED", "O_SELECTED", "A_FINALIZED", "O_CREATED", "O_SENT", "W_Nabellen offertes", "O_SENT_BACK", "A_REGISTERED", "A_APPROVED", "A_ACTIVATED", "O_ACCEPTED", "A_DECLINED", "O_DECLINED", "O_CANCELLED", "A_CANCELLED"];
+/** One activity name from {@link BPI_2012_ACTIVITIES}. */
+type Bpi2012Activity = (typeof BPI_2012_ACTIVITIES)[number];
+/**
+ * Generate a synthetic BPI-2012-shaped loan-application log.
+ *
+ * Every event is an INTERVAL event (`startTimestamp` + `timestamp`), and cases are emitted
+ * as `caseId`s of the form `bpi-000001`, zero-padded so lexical and numeric order agree —
+ * the same shape `generateSyntheticLog` uses, so downstream consumers do not need a second
+ * case-id convention.
+ */
+declare function generateBpi2012Subset(options: Bpi2012SubsetOptions): EventLog;
+
+/** Options for {@link abstractGraph}. Both fractions are `0..1` and both are required. */
+interface AbstractionOptions {
+    /** Fraction of activities to KEEP, `0..1`. At least one activity is always kept. */
+    activities: number;
+    /** Fraction of paths (transitions) to KEEP, `0..1`, over the kept-activity subgraph. */
+    paths: number;
+    /**
+     * Re-add whatever it takes to keep every kept activity reachable from a start activity
+     * and able to reach an end activity. Defaults to `true` — an island reads as a broken
+     * process, not a simplified one.
+     */
+    keepConnected?: boolean;
+    /** Hide the MOST frequent instead of the least — the "what is rare here" view. */
+    invert?: boolean;
+}
+/** What {@link abstractGraph} returns: a `ProcessGraph` plus what it left out. */
+interface AbstractedGraph extends ProcessGraph {
+    hidden: {
+        /** Activities present in the input graph and absent from this one. */
+        activities: number;
+        /** Transitions present in the input graph and absent from this one. */
+        paths: number;
+    };
+}
+/**
+ * Reduce `graph` to the fraction of activities and paths a reader asked to see.
+ *
+ * Activities rank by `cases` (how many process instances touch them), ties broken by
+ * `instances` then by name; paths rank by `count`, ties broken by `caseCount` then by
+ * endpoint names. Ranking on `cases` rather than `instances` is deliberate: an activity
+ * executed forty times inside one case is a loop, not a backbone step, and a frequency
+ * slider that promoted it would hide the shape of the process.
+ *
+ * The returned arrays hold the INPUT's own statistic objects, in the input's order.
+ * Treat the result as read-only: mutating a returned `ActivityStats` mutates the source
+ * graph's, by design — that shared identity is what proves no recomputation happened.
+ */
+declare function abstractGraph(graph: ProcessGraph, opts: AbstractionOptions): AbstractedGraph;
+
+/** The result of {@link reconcileGraph}. */
+interface ReconciledGraph<G extends ProcessGraph> {
+    /** `presented`'s exact element set, with `filtered`'s statistics where an element survived. */
+    graph: G;
+    /** Activity ids `presented` carries that `filtered` dropped — rendered as zeroed ghosts. */
+    excludedActivities: string[];
+    /** Transition keys (`source` + {@link EDGE_KEY_SEPARATOR} + `target`) `filtered` dropped. */
+    excludedTransitions: string[];
+}
+/**
+ * Reconcile a presented graph's element set against what a filter actually produced.
+ *
+ * `G` is generic over `ProcessGraph` so an already-abstracted graph (`AbstractedGraph`, which
+ * adds `hidden`) reconciles without losing its extra field — the return type is `G`, and the
+ * implementation spreads `presented` before overwriting only the fields this function owns.
+ */
+declare function reconcileGraph<G extends ProcessGraph>(presented: G, filtered: ProcessGraph): ReconciledGraph<G>;
+
+/** The units a duration can be spoken in. Everything upstream is milliseconds. */
+type DurationUnit = "ms" | "s" | "min" | "h" | "d";
+/** How many milliseconds each {@link DurationUnit} is worth. */
+declare const DURATION_UNIT_MS: Readonly<Record<DurationUnit, number>>;
+/** Options for {@link aggregatePerformance}. */
+interface PerformanceOptions {
+    /** Which member of a {@link DurationStats} the layer reads. */
+    agg: PerformanceAgg;
+    /**
+     * Which elapsed time an edge measures. Honoured only when `log` is supplied — a graph
+     * alone cannot be converted from waiting time to cycle time, because the two are not
+     * derivable from each other's summary statistics. Without `log` this field DECLARES
+     * what the graph already carries and nothing is re-derived.
+     */
+    flowTime: FlowTime;
+    /** The unit every returned duration is expressed in. */
+    unit: DurationUnit;
+    /**
+     * The log the graph came from. Supply it to re-derive edge durations at `flowTime`;
+     * pass an already-normalized log (see `asNormalizedLog`) to skip a second parse.
+     */
+    log?: AnyLog;
+    /**
+     * Reservoir capacity per activity and per edge when re-deriving. Order statistics
+     * (`median`, `p90`, `trimmedMean`) are ESTIMATES past this many samples per key; raise
+     * it when a threshold has to be exact. Only meaningful together with `log`.
+     */
+    maxDurationSamples?: number;
+}
+/** The per-element scalars a performance view paints with, plus the domains to scale them on. */
+interface PerformanceLayer {
+    agg: PerformanceAgg;
+    flowTime: FlowTime;
+    unit: DurationUnit;
+    /** Activity id → the selected aggregate of its execution time, in `unit`. */
+    activities: Record<string, number>;
+    /** `source␁target` (see `EDGE_KEY_SEPARATOR`) → the selected aggregate, in `unit`. */
+    transitions: Record<string, number>;
+    /** `[min, max]` over `activities` — `[0, 0]` when there are none. */
+    activityDomain: [number, number];
+    /** `[min, max]` over `transitions` — `[0, 0]` when there are none. */
+    transitionDomain: [number, number];
+}
+/** What {@link aggregatePerformance} returns: a `ProcessGraph` plus its metric layer. */
+interface PerformanceGraph extends ProcessGraph {
+    performance: PerformanceLayer;
+}
+/**
+ * Read the member of `stats` a {@link PerformanceAgg} names.
+ *
+ * The one place the mapping lives, so a control, a legend and a renderer cannot disagree
+ * about what "p90" is. `trimmed_mean` is the snake_case spelling of `trimmedMean` —
+ * the type is a wire/URL value, the field is a property name.
+ */
+declare function performanceValue(stats: DurationStats, agg: PerformanceAgg): number;
+/**
+ * Express `graph`'s durations as a performance layer.
+ *
+ * Every `DurationStats` in the returned graph is converted to `opts.unit`, and
+ * `performance` carries the single scalar per activity and per transition that
+ * `opts.agg` selects, together with the two domains a scale needs.
+ *
+ * With `opts.log`, edge and activity durations are RE-DERIVED at `opts.flowTime` from the
+ * FULL log — which is what keeps a performance layer honest on an abstracted graph: the
+ * numbers describe everything that happened, not only the part currently drawn. Elements
+ * the re-derivation does not know about keep the statistics they arrived with.
+ *
+ * Order statistics past the reservoir cap are estimates (see `maxDurationSamples`);
+ * `sum`, `mean`, `min` and `max` are exact at any log size.
+ */
+declare function aggregatePerformance(graph: ProcessGraph, opts: PerformanceOptions): PerformanceGraph;
+
+/**
+ * Rework detection — RM-050.
+ *
+ * "Rework" is the part of a process that happens more than once inside a single case: a
+ * step retried immediately (a SELF-LOOP), or a step the case comes back to after going
+ * somewhere else (a LOOP). Both are repeats, and separating them matters — a self-loop is
+ * usually a retry or a batch, a loop is usually a rejection sending work backwards, and
+ * the two lead to different conversations about the process.
+ *
+ * Counted per OCCURRENCE, over the normalized trace: the first execution of an activity in
+ * a case is never rework, and every later one is exactly one of the two kinds. So
+ * `selfLoops + loops` is precisely the number of repeated executions in the log.
+ *
+ * Deterministic and framework-free, like everything else in `/core`.
+ */
+
+/** Per-activity rework tallies. */
+interface ActivityRework {
+    /** Repeats of this activity immediately after itself. */
+    selfLoops: number;
+    /** Repeats of this activity later in the same case, with something else in between. */
+    loops: number;
+}
+/** What {@link detectRework} answers. */
+interface ReworkStats {
+    /** Adjacent repeats across the whole log. */
+    selfLoops: number;
+    /** Non-adjacent repeats across the whole log. */
+    loops: number;
+    /** Fraction of cases carrying at least one self-loop or loop. `0` for an empty log. */
+    caseReworkRate: number;
+    /**
+     * Every activity in the log, in ascending name order, with its own two tallies. An
+     * activity that never repeats is present with zeros — a renderer joining this against
+     * a graph's activities never has to distinguish "no rework" from "unknown activity".
+     */
+    perActivity: Record<string, ActivityRework>;
+}
+/**
+ * Count rework in `log`.
+ *
+ * Accepts a raw or an already-normalized log and normalizes at most once
+ * ({@link asNormalizedLog} is idempotent), so a caller that has already normalized for
+ * `discoverGraph` pays nothing here.
+ */
+declare function detectRework(log: AnyLog): ReworkStats;
+
+/**
+ * Case-level log filtering — RM-050.
+ *
+ * Every filter in a process-mining tool is a CASE predicate, not an event predicate:
+ * "cases that contain Reject Order", "cases that took longer than a day". Removing single
+ * events would rewrite traces and invent directly-follows relations that never happened,
+ * so a filter here only ever keeps or drops a case whole. That is what makes the result
+ * safe to hand straight back to `discoverGraph` / `extractVariants`.
+ *
+ * Specs AND together — an empty list keeps everything.
+ */
+
+/** One case-level predicate. {@link filterLog} ANDs a list of them. */
+type FilterSpec = 
+/** The case contains `activity` at least once. */
+{
+    kind: "with";
+    activity: string;
+}
+/** The case never contains `activity`. */
+ | {
+    kind: "without";
+    activity: string;
+}
+/** The case's FIRST activity is `activity`. */
+ | {
+    kind: "startsWith";
+    activity: string;
+}
+/** The case's LAST activity is `activity`. */
+ | {
+    kind: "endsWith";
+    activity: string;
+}
+/**
+ * `b` follows `a` in the case — directly (adjacent) when `direct`, otherwise eventually
+ * (anywhere later in the trace).
+ */
+ | {
+    kind: "follower";
+    a: string;
+    b: string;
+    direct?: boolean;
+}
+/** An attribute comparison — see {@link caseMatchesFilters} for how `key` is resolved. */
+ | {
+    kind: "attribute";
+    key: string;
+    op: "eq" | "ne" | "gt" | "lt" | "in";
+    value: unknown;
+}
+/** The case's throughput time, in milliseconds. Both bounds are INCLUSIVE. */
+ | {
+    kind: "duration";
+    min?: number;
+    max?: number;
+}
+/** The case follows one of these variants (see `variantId`). */
+ | {
+    kind: "variant";
+    ids: string[];
+}
+/** The case is one of these case ids. */
+ | {
+    kind: "cases";
+    ids: string[];
+};
+/**
+ * Does `kase` satisfy every spec?
+ *
+ * Exported because a case table and a variant list want to HIGHLIGHT what a filter
+ * selects as often as they want to remove what it does not.
+ */
+declare function caseMatchesFilters(kase: NormalizedCase, specs: readonly FilterSpec[]): boolean;
+/**
+ * Filter a NORMALIZED log — the composable form.
+ *
+ * This is the one to reach for in a pipeline: it accepts either shape, normalizes at most
+ * once, and returns the normalized result, so
+ * `discoverGraph(filterNormalizedLog(normalized, specs))` re-parses nothing. `totals` are
+ * recomputed over the surviving cases; case order is preserved.
+ */
+declare function filterNormalizedLog(log: AnyLog, specs: readonly FilterSpec[]): NormalizedLog;
+/**
+ * Filter a raw {@link EventLog}, answering a raw {@link EventLog}.
+ *
+ * Every ROW of a surviving case is kept, in input order, including rows normalization
+ * itself discards (an unpaired lifecycle half, say) — so the answer round-trips: it can be
+ * re-exported, handed to a different adapter, or re-normalized with different options.
+ * `caseAttributes` is narrowed to the surviving cases.
+ *
+ * Use {@link filterNormalizedLog} instead when the next step is another `/core` derivation;
+ * this form necessarily makes the caller normalize again.
+ */
+declare function filterLog(log: EventLog, specs: readonly FilterSpec[]): EventLog;
+
+/**
+ * Off-thread discovery — RM-050.
+ *
+ * Discovering a graph from a raw log is O(events) with a couple of hash lookups per event;
+ * on a 200 000-row import that is long enough to drop frames, and a dropped frame during a
+ * file import is exactly the moment an app reads as broken. So the derivation moves to a
+ * worker — but ONLY as an optimization: the caller never branches on the environment.
+ *
+ * **Degrade, never fail.** When there is no `Worker` (a server render, a Node test, an
+ * embedded webview), when constructing one throws, or when a live one errors, the same
+ * functions run inline on the calling thread and the promise still resolves with the same
+ * answer. `handleProcessRequest` is literally shared with the worker entry, so "the inline
+ * path agrees with the worker path" is a property of the code, not of a test.
+ *
+ * **Normalize once.** Every method takes an `AnyLog`; hand it an already-normalized log
+ * (`asNormalizedLog`) and neither side re-parses. A `NormalizedLog` is plain data and
+ * clones across `postMessage` unchanged.
+ */
+
+/**
+ * The slice of the `Worker` interface this module uses.
+ *
+ * Narrow on purpose: it is the seam a test (or a bundler with its own worker construction)
+ * substitutes, and demanding the full DOM `Worker` surface for that would be pointless
+ * ceremony. A real `Worker` satisfies it.
+ */
+interface ProcessWorkerLike {
+    postMessage(message: unknown): void;
+    terminate(): void;
+    addEventListener(type: "message" | "error" | "messageerror", listener: (event: unknown) => void): void;
+}
+/** Options for {@link createProcessWorker}. */
+interface CreateProcessWorkerOptions {
+    /** Skip the worker entirely and run inline. Useful for benchmarks and for tests. */
+    forceInline?: boolean;
+    /**
+     * Build the worker yourself.
+     *
+     * The default construction is
+     * `new Worker(new URL("./process-worker.ts", import.meta.url), { type: "module" })`.
+     * A bundler compiling THIS SOURCE (Vite, webpack) rewrites that literal itself; a
+     * consumer of the BUILT package gets `dist/core/process-worker.js`, which
+     * `tsup.config.ts` emits as its own pass and points the built bundle at — a bundler
+     * rewrites the source it compiles, never a `dist` it merely consumes, so that file has
+     * to be real. A host that needs its own URL supplies this instead. Throwing from it is
+     * safe: the handle falls back to the inline path.
+     */
+    createWorker?: () => ProcessWorkerLike;
+}
+/** What {@link createProcessWorker} hands back. */
+interface ProcessWorkerHandle {
+    /** Discover a directly-follows graph. */
+    discover(log: AnyLog, options?: DiscoverGraphOptions): Promise<ProcessGraph>;
+    /** Group the log's cases into variants. */
+    variants(log: AnyLog): Promise<Variant[]>;
+    /** Stop the worker. Pending promises reject, and so does every later call. */
+    terminate(): void;
+    /**
+     * `true` when work is currently running on the CALLING thread — either because the
+     * environment has no worker, or because one failed and the handle degraded.
+     */
+    readonly inline: boolean;
+}
+/**
+ * Create a handle that computes off-thread when it can and inline when it cannot.
+ *
+ * The worker is created LAZILY, on the first request, so constructing a handle costs
+ * nothing in an environment that never uses it.
+ */
+declare function createProcessWorker(options?: CreateProcessWorkerOptions): ProcessWorkerHandle;
+
+/**
+ * The worker entry point — RM-050.
+ *
+ * Two things live here, deliberately in one module: the PURE request handler, and the
+ * `message` bootstrap that runs it inside a real worker. `createProcessWorker` imports the
+ * handler for its inline path, so the code that answers on the main thread and the code
+ * that answers off it are the SAME function — parity is structural, not something a test
+ * has to keep true.
+ *
+ * The bootstrap is guarded by a real worker-scope check, so importing this module from the
+ * main thread registers nothing.
+ */
+
+/** What the main thread asks the worker to compute. Structured-cloneable, by construction. */
+type ProcessWorkerRequest = {
+    id: number;
+    kind: "discover";
+    log: AnyLog;
+    options?: DiscoverGraphOptions;
+} | {
+    id: number;
+    kind: "variants";
+    log: AnyLog;
+};
+/** What comes back. `ok: false` carries a message, never an `Error` (which clones poorly). */
+type ProcessWorkerResponse = {
+    id: number;
+    ok: true;
+    kind: "discover";
+    graph: ProcessGraph;
+} | {
+    id: number;
+    ok: true;
+    kind: "variants";
+    variants: Variant[];
+} | {
+    id: number;
+    ok: false;
+    error: string;
+};
+/**
+ * Answer one request.
+ *
+ * Pure and synchronous: the whole point of the worker is that this is the expensive part,
+ * and moving it off the main thread is the only thing the worker adds. Throwing is
+ * converted to an `ok: false` response so a bad log cannot silently kill the worker and
+ * leave every later request hanging.
+ */
+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 };