@elabs-ai/components-process 4.2.0 → 5.0.0

package/dist/test/index.d.ts

@@ -11,10 +11,19 @@ type ProcessSelection = null | {
 };
 /** What {@link assertProcessContract} checks for one double. */
 interface ProcessContractSpec {
-    /** Name of the prop carrying the double's primary data payload. */
-    dataProp: "graph" | "variants";
+    /**
+     * Name of the prop carrying the double's primary data payload. `conformance` is a
+     * `ConformanceResult` and `value` a `HappyPath` (RM-062).
+     */
+    dataProp: "graph" | "variants" | "log" | "conformance" | "value";
     /** Other props the real component requires; the double must not silently accept `undefined`. */
     requiredProps?: string[];
+    /**
+     * PerformanceSpectrum — RM-060: the `order` prop (default `"frequency"`) must resolve to
+     * at least one segment that actually occurs in `log`, or the real view renders only its
+     * empty panel — almost always a test wired to the wrong activity names.
+     */
+    segmentOrder?: boolean;
 }
 /** Thrown by {@link assertProcessContract} when a double is used with an invalid prop shape. */
 declare class ProcessContractError extends Error {
@@ -47,8 +56,8 @@ declare function readProcessDoubleProps(el: Element): ProcessDoublePayload | nul
  * 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.
@@ -164,6 +173,137 @@ interface Variant {
     duration: DurationStats;
 }
 
+/**
+ * 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[];
+}
+
+/**
+ * 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";
+/** 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[];
+}
+
+/**
+ * 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;
+    }>;
+}
+
 interface DoubleOwnProps extends HTMLAttributes<HTMLDivElement> {
     selection?: ProcessSelection;
     onSelectionChange?: (selection: ProcessSelection) => void;
@@ -183,6 +323,84 @@ declare const ProcessMapDouble: react.ForwardRefExoticComponent<ProcessMapDouble
 declare const VariantExplorerDouble: react.ForwardRefExoticComponent<VariantExplorerDoubleProps & react.RefAttributes<HTMLDivElement>>;
 /** Stand-in for the future `ProcessKpiStrip` (RM-054). */
 declare const ProcessKpiStripDouble: react.ForwardRefExoticComponent<ProcessKpiStripDoubleProps & react.RefAttributes<HTMLDivElement>>;
+interface DottedChartDoubleProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+    log: EventLog;
+    selectedCaseIds?: readonly string[];
+    onSelect?: (caseIds: string[]) => void;
+}
+/** Stand-in for `DottedChart` (RM-059). Asserts a non-empty `log.events` with parsable timestamps. */
+declare const DottedChartDouble: react.ForwardRefExoticComponent<DottedChartDoubleProps & react.RefAttributes<HTMLDivElement>>;
+interface PerformanceSpectrumDoubleProps extends HTMLAttributes<HTMLDivElement> {
+    log: EventLog;
+    /** Explicit segments, `"frequency"` (the default) or `{ variantId }` — as the real prop. */
+    order?: Array<{
+        from: string;
+        to: string;
+        label?: string;
+    }> | "frequency" | {
+        variantId: string;
+    };
+    segmentLimit?: number;
+    mode?: "lines" | "aggregated";
+    binSize?: number;
+    onFilterIntent?: (intent: {
+        kind: "cases";
+        ids: string[];
+    }) => void;
+    height?: number;
+    tableView?: boolean;
+    loading?: boolean;
+}
+/** Stand-in for `PerformanceSpectrum` (RM-060); asserts `order` resolves to a segment present in `log`. */
+declare const PerformanceSpectrumDouble: react.ForwardRefExoticComponent<PerformanceSpectrumDoubleProps & react.RefAttributes<HTMLDivElement>>;
+interface ConformanceOverlayDoubleProps extends DoubleOwnProps {
+    graph: ProcessGraph;
+    conformance: ConformanceResult;
+}
+interface ViolationListDoubleProps extends HTMLAttributes<HTMLDivElement> {
+    conformance: ConformanceResult;
+}
+interface HappyPathEditorDoubleProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    value: HappyPath;
+    onChange: (path: HappyPath) => void;
+}
+/** Stand-in for `ConformanceOverlay` (RM-062): requires a graph AND a replay result. */
+declare const ConformanceOverlayDouble: react.ForwardRefExoticComponent<ConformanceOverlayDoubleProps & react.RefAttributes<HTMLDivElement>>;
+/** Stand-in for `ViolationList` (RM-062). */
+declare const ViolationListDouble: react.ForwardRefExoticComponent<ViolationListDoubleProps & react.RefAttributes<HTMLDivElement>>;
+/** Stand-in for `HappyPathEditor` (RM-062): a controlled editor, so `onChange` is required. */
+declare const HappyPathEditorDouble: react.ForwardRefExoticComponent<HappyPathEditorDoubleProps & react.RefAttributes<HTMLDivElement>>;
+interface ProcessReplayDoubleProps extends HTMLAttributes<HTMLDivElement> {
+    graph: ProcessGraph;
+    log: EventLog;
+    synchronizedStart?: boolean;
+    bucketMs?: number;
+    playing?: boolean;
+    defaultPlaying?: boolean;
+    onPlayingChange?: (playing: boolean) => void;
+    time?: number;
+    defaultTime?: number;
+    onTimeChange?: (time: number) => void;
+    speed?: number;
+    defaultSpeed?: number;
+    onSpeedChange?: (speed: number) => void;
+    congestionLimit?: number;
+    loading?: boolean;
+}
+/** Stand-in for `ProcessReplay` (RM-065): requires the log (per-case timing) AND the graph. */
+declare const ProcessReplayDouble: react.ForwardRefExoticComponent<ProcessReplayDoubleProps & react.RefAttributes<HTMLDivElement>>;
+
+interface ProcessCompareSideDoubleProps {
+    label: string;
+    graph?: ProcessGraph;
+}
+interface ProcessCompareDoubleProps extends HTMLAttributes<HTMLDivElement> {
+    a: ProcessCompareSideDoubleProps;
+    b: ProcessCompareSideDoubleProps;
+    mode?: "side-by-side" | "superimposed";
+}
+/** Stand-in for `ProcessCompare` (RM-064) — cheap enough to mount without a real canvas. */
+declare const ProcessCompareDouble: react.ForwardRefExoticComponent<ProcessCompareDoubleProps & react.RefAttributes<HTMLDivElement>>;
 
 /** The derived triple most process stories/tests want from one raw log. */
 interface ProcessFixture {
@@ -193,4 +411,4 @@ interface ProcessFixture {
 /** Derive {@link ProcessFixture} from a raw event log. Pure — no caching, no I/O. */
 declare function withProcessFixture(log: EventLog): ProcessFixture;
 
-export { ProcessContractError, type ProcessContractSpec, type ProcessDoublePayload, type ProcessFixture, ProcessKpiStripDouble, type ProcessKpiStripDoubleProps, ProcessMapDouble, type ProcessMapDoubleProps, type ProcessSelection, VariantExplorerDouble, type VariantExplorerDoubleProps, assertProcessContract, buildProcessDoublePayload, readProcessDoubleProps, withProcessFixture };
+export { ConformanceOverlayDouble, type ConformanceOverlayDoubleProps, DottedChartDouble, type DottedChartDoubleProps, HappyPathEditorDouble, type HappyPathEditorDoubleProps, PerformanceSpectrumDouble, type PerformanceSpectrumDoubleProps, ProcessCompareDouble, type ProcessCompareDoubleProps, ProcessContractError, type ProcessContractSpec, type ProcessDoublePayload, type ProcessFixture, ProcessKpiStripDouble, type ProcessKpiStripDoubleProps, ProcessMapDouble, type ProcessMapDoubleProps, ProcessReplayDouble, type ProcessReplayDoubleProps, type ProcessSelection, VariantExplorerDouble, type VariantExplorerDoubleProps, ViolationListDouble, type ViolationListDoubleProps, assertProcessContract, buildProcessDoublePayload, readProcessDoubleProps, withProcessFixture };