@elabs-ai/components-process 4.1.0

package/src/core/fixtures/synthetic-log.ts

@@ -0,0 +1,167 @@
+/**
+ * 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.
+ */
+import type { EventLog, EventRow } from "../types";
+
+/** Epoch ms the first case starts at: 2026-01-05T08:00:00.000Z, a Monday morning. */
+export const SYNTHETIC_LOG_EPOCH = 1767600000000;
+
+const MINUTE = 60_000;
+
+/** Options for {@link generateSyntheticLog}. */
+export 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;
+}
+
+/**
+ * A deterministic 32-bit PRNG (mulberry32).
+ *
+ * Deliberately its own copy rather than one shared with the core's duration sampler: this
+ * generator's output is a FIXTURE that tests assert exact numbers against, so it must not
+ * shift because an unrelated internal in `duration-stats.ts` was retuned.
+ */
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const RESOURCES = [
+  "A. Novak",
+  "B. Ferreira",
+  "C. Okafor",
+  "D. Lindqvist",
+  "E. Haddad",
+  "Credit Service",
+  "Warehouse Robot",
+] as const;
+
+const REGIONS = ["North", "South", "East", "West"] as const;
+const SEGMENTS = ["Enterprise", "Mid-market", "SMB"] as const;
+
+/** Activity vocabulary. Exported so a story can label or colour by name without guessing. */
+export const SYNTHETIC_ACTIVITIES = [
+  "Create Order",
+  "Check Credit",
+  "Amend Order",
+  "Approve Order",
+  "Reject Order",
+  "Reserve Stock",
+  "Cancel Order",
+  "Pick Items",
+  "Ship Order",
+  "Send Invoice",
+  "Receive Payment",
+] as const;
+
+/** One activity name from {@link SYNTHETIC_ACTIVITIES}. */
+export type SyntheticActivity = (typeof SYNTHETIC_ACTIVITIES)[number];
+
+/** Build the activity sequence of a single case. Pure given `random`. */
+function buildTrace(random: () => number): SyntheticActivity[] {
+  const trace: SyntheticActivity[] = ["Create Order", "Check Credit"];
+
+  // Rework: an amendment sends the order back through the credit check, at most twice.
+  let reworks = 0;
+  while (reworks < 2 && random() < 0.14) {
+    trace.push("Amend Order", "Check Credit");
+    reworks += 1;
+  }
+
+  if (random() < 0.09) {
+    trace.push("Reject Order");
+    return trace;
+  }
+
+  trace.push("Approve Order", "Reserve Stock");
+
+  if (random() < 0.05) {
+    trace.push("Cancel Order");
+    return trace;
+  }
+
+  trace.push("Pick Items");
+  // A short-picked order is picked again — the log's only self-loop.
+  if (random() < 0.07) trace.push("Pick Items");
+
+  // Roughly a third of orders are invoiced before they ship.
+  if (random() < 0.32) trace.push("Send Invoice", "Ship Order");
+  else trace.push("Ship Order", "Send Invoice");
+
+  trace.push("Receive Payment");
+  return trace;
+}
+
+/**
+ * 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.
+ */
+export function generateSyntheticLog(options: SyntheticLogOptions): EventLog {
+  const total = Math.max(0, Math.floor(options.cases));
+  const random = mulberry32(options.seed ?? 1);
+  const epoch = options.startTime ?? SYNTHETIC_LOG_EPOCH;
+
+  const events: EventRow[] = [];
+  const caseAttributes: Record<string, Record<string, unknown>> = {};
+  const pad = String(total).length;
+
+  for (let index = 0; index < total; index += 1) {
+    const caseId = `case-${String(index + 1).padStart(Math.max(5, pad), "0")}`;
+    const trace = buildTrace(random);
+
+    caseAttributes[caseId] = {
+      region: REGIONS[Math.floor(random() * REGIONS.length)] as string,
+      segment: SEGMENTS[Math.floor(random() * SEGMENTS.length)] as string,
+      // Whole euros, so a table can render the value without a rounding decision.
+      orderValue: 250 + Math.floor(random() * 9750),
+    };
+
+    // Cases arrive about an hour apart, with a jitter that keeps them from lining up.
+    let cursor = epoch + index * 61 * MINUTE + Math.floor(random() * 40) * MINUTE;
+
+    for (const activity of trace) {
+      const idle = Math.floor(random() * 180) * MINUTE;
+      const work = (2 + Math.floor(random() * 44)) * MINUTE;
+      const start = cursor + idle;
+      const end = start + work;
+      events.push({
+        caseId,
+        activity,
+        timestamp: end,
+        startTimestamp: start,
+        resource: RESOURCES[Math.floor(random() * RESOURCES.length)] as string,
+      });
+      cursor = end;
+    }
+  }
+
+  return { events, caseAttributes };
+}

package/src/core/index.ts

@@ -0,0 +1,118 @@
+/**
+ * `@elabs-ai/components-process/core` — the FRAMEWORK-FREE half of the process package.
+ *
+ * A gated subpath export (ADR 0006 / ADR 0034): the event-log model, directly-follows
+ * derivation, variant grouping and conformance math, with a materially lighter
+ * dependency tree than the trunk — no React, no React Flow, no visx. That is what lets
+ * a server route, a worker or a unit test import the domain model without pulling a
+ * rendering engine.
+ *
+ * NOTHING in this module may import React or any `@elabs-ai/components-*` package.
+ *
+ * Wave-1 items APPEND their exports at the end of the block below, each under a
+ * `// <Name> — RM-NNN` comment, so concurrent branches merge as appends.
+ */
+
+// ── Model & derivation (framework-free) ──────────────────────────────────────
+
+// Model types — RM-049
+export type {
+  ActivityStats,
+  DurationStats,
+  EventLog,
+  EventRow,
+  FlowTime,
+  FrequencyMode,
+  PerformanceAgg,
+  ProcessGraph,
+  TransitionStats,
+  Variant,
+} from "./types";
+
+// normalizeLog — RM-049
+export { asNormalizedLog, isNormalizedLog, normalizeLog, toEpochMs } from "./event-log";
+export type { AnyLog, NormalizedCase, NormalizedEvent, NormalizedLog } from "./event-log";
+
+// fromFlatRows — RM-049
+export { DEFAULT_LIFECYCLE_VALUES, fromFlatRows, normalizeLifecycle } from "./adapters/flat";
+export type { FlatRow, FlatRowMapping, LifecycleValues } from "./adapters/flat";
+
+// fromCsv — RM-049
+export { fromCsv, parseDelimited } from "./adapters/csv";
+export type { CsvMapping, CsvOptions } from "./adapters/csv";
+
+// discoverGraph — RM-049
+export { discoverGraph } from "./discover-graph";
+export type { DiscoverGraphOptions } from "./discover-graph";
+
+// extractVariants — RM-049
+export { extractVariants, variantId, variantKey, VARIANT_KEY_SEPARATOR } from "./extract-variants";
+
+// durationStats — RM-049
+export {
+  DURATION_SAMPLE_CAP,
+  DurationSampler,
+  durationStats,
+  EMPTY_DURATION_STATS,
+  emptyDurationStats,
+  TRIM_FRACTION,
+} from "./duration-stats";
+
+// minMax / quantile / clampWidth — RM-049
+export { clampWidth, minMax, quantile, quantileSorted } from "./scale";
+
+// generateSyntheticLog — RM-049
+export {
+  generateSyntheticLog,
+  SYNTHETIC_ACTIVITIES,
+  SYNTHETIC_LOG_EPOCH,
+} from "./fixtures/synthetic-log";
+export type { SyntheticActivity, SyntheticLogOptions } from "./fixtures/synthetic-log";
+
+// generateBpi2012Subset — RM-053 (#228 F2 — restores the same reachability
+// generateSyntheticLog already has; see generate-bpi-2012-subset.ts's own docblock)
+export {
+  BPI_2012_ACTIVITIES,
+  BPI_2012_SUBSET_EPOCH,
+  generateBpi2012Subset,
+} from "./fixtures/generate-bpi-2012-subset";
+export type { Bpi2012Activity, Bpi2012SubsetOptions } from "./fixtures/generate-bpi-2012-subset";
+
+// abstractGraph — RM-050
+export { abstractGraph } from "./abstract-graph";
+export type { AbstractedGraph, AbstractionOptions } from "./abstract-graph";
+
+// reconcileGraph — RM-052 round 2 (#227, Invariant F)
+export { reconcileGraph } from "./reconcile-graph";
+export type { ReconciledGraph } from "./reconcile-graph";
+
+// aggregatePerformance — RM-050
+export { aggregatePerformance, DURATION_UNIT_MS, performanceValue } from "./aggregate-performance";
+export type {
+  DurationUnit,
+  PerformanceGraph,
+  PerformanceLayer,
+  PerformanceOptions,
+} from "./aggregate-performance";
+
+// detectRework — RM-050
+export { detectRework } from "./detect-rework";
+export type { ActivityRework, ReworkStats } from "./detect-rework";
+
+// filterLog — RM-050
+export { caseMatchesFilters, filterLog, filterNormalizedLog } from "./filter-log";
+export type { FilterSpec } from "./filter-log";
+
+// createProcessWorker — RM-050
+export { createProcessWorker } from "./worker/create-process-worker";
+export type {
+  CreateProcessWorkerOptions,
+  ProcessWorkerHandle,
+  ProcessWorkerLike,
+} from "./worker/create-process-worker";
+export { handleProcessRequest } from "./worker/process-worker";
+export type { ProcessWorkerRequest, ProcessWorkerResponse } from "./worker/process-worker";
+
+// EDGE_KEY_SEPARATOR — RM-050 (the edge-key convention abstraction and the
+// performance layer both index on; discovery has always used it internally)
+export { EDGE_KEY_SEPARATOR } from "./discover-graph";

package/src/core/reconcile-graph.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from "vitest";
+import { EMPTY_DURATION_STATS } from "./duration-stats";
+import { reconcileGraph } from "./reconcile-graph";
+import type { AbstractedGraph } from "./abstract-graph";
+import type { ActivityStats, ProcessGraph, TransitionStats } from "./types";
+
+const DURATION = {
+  min: 1,
+  max: 10,
+  mean: 5,
+  median: 5,
+  p90: 9,
+  sum: 50,
+  trimmedMean: 5,
+};
+
+function activity(id: string, overrides: Partial<ActivityStats> = {}): ActivityStats {
+  return {
+    id,
+    label: id,
+    instances: 10,
+    cases: 5,
+    isStart: false,
+    isEnd: false,
+    duration: DURATION,
+    ...overrides,
+  };
+}
+
+function transition(
+  source: string,
+  target: string,
+  overrides: Partial<TransitionStats> = {},
+): TransitionStats {
+  return {
+    source,
+    target,
+    count: 10,
+    caseCount: 5,
+    duration: DURATION,
+    isSelfLoop: source === target,
+    isBackEdge: false,
+    ...overrides,
+  };
+}
+
+function graph(overrides: Partial<ProcessGraph> = {}): ProcessGraph {
+  return {
+    activities: [],
+    transitions: [],
+    startActivities: {},
+    endActivities: {},
+    totals: { cases: 0, events: 0, variants: 0 },
+    ...overrides,
+  };
+}
+
+describe("reconcileGraph", () => {
+  it("is the identity when filtered is deep-equal to presented (no filter applied)", () => {
+    const presented = graph({
+      activities: [activity("A", { isStart: true }), activity("B", { isEnd: true })],
+      transitions: [transition("A", "B")],
+      startActivities: { A: 5 },
+      endActivities: { B: 5 },
+      totals: { cases: 5, events: 10, variants: 1 },
+    });
+    // A structurally distinct but deep-equal graph, as a fresh discoverGraph(log) call with
+    // no active filter would actually produce.
+    const filtered = graph({
+      activities: [activity("A", { isStart: true }), activity("B", { isEnd: true })],
+      transitions: [transition("A", "B")],
+      startActivities: { A: 5 },
+      endActivities: { B: 5 },
+      totals: { cases: 5, events: 10, variants: 1 },
+    });
+
+    const result = reconcileGraph(presented, filtered);
+
+    expect(result.graph).toEqual(presented);
+    expect(result.excludedActivities).toEqual([]);
+    expect(result.excludedTransitions).toEqual([]);
+  });
+
+  it("ghosts an activity the filter dropped: same id, every count zeroed", () => {
+    const presented = graph({
+      activities: [
+        activity("A", { isStart: true, instances: 10, cases: 5 }),
+        activity("B", { instances: 3, cases: 2 }),
+      ],
+      transitions: [transition("A", "B", { count: 3, caseCount: 2 })],
+      totals: { cases: 5, events: 13, variants: 2 },
+    });
+    // The filter kept only "A" — "B" (and its edge) did not survive.
+    const filtered = graph({
+      activities: [activity("A", { isStart: true, instances: 10, cases: 5 })],
+      transitions: [],
+      startActivities: { A: 5 },
+      totals: { cases: 5, events: 10, variants: 1 },
+    });
+
+    const {
+      graph: reconciled,
+      excludedActivities,
+      excludedTransitions,
+    } = reconcileGraph(presented, filtered);
+
+    // Invariant F: the element set is unchanged — "B" is still on the map.
+    expect(reconciled.activities.map((a) => a.id)).toEqual(["A", "B"]);
+    expect(reconciled.transitions).toHaveLength(1);
+
+    const ghost = reconciled.activities.find((a) => a.id === "B")!;
+    expect(ghost.instances).toBe(0);
+    expect(ghost.cases).toBe(0);
+    expect(ghost.isStart).toBe(false);
+    expect(ghost.isEnd).toBe(false);
+    expect(ghost.duration).toEqual(EMPTY_DURATION_STATS);
+
+    const ghostEdge = reconciled.transitions[0]!;
+    expect(ghostEdge.source).toBe("A");
+    expect(ghostEdge.target).toBe("B");
+    expect(ghostEdge.count).toBe(0);
+    expect(ghostEdge.caseCount).toBe(0);
+    expect(ghostEdge.duration).toEqual(EMPTY_DURATION_STATS);
+
+    expect(excludedActivities).toEqual(["B"]);
+    expect(excludedTransitions).toEqual([`A
B`]);
+  });
+
+  it("takes startActivities, endActivities and totals from the FILTERED graph", () => {
+    const presented = graph({
+      activities: [activity("A"), activity("B")],
+      startActivities: { A: 5, B: 1 },
+      endActivities: { B: 5, A: 1 },
+      totals: { cases: 5, events: 20, variants: 3 },
+    });
+    const filtered = graph({
+      activities: [activity("A")],
+      startActivities: { A: 2 },
+      endActivities: { A: 2 },
+      totals: { cases: 2, events: 4, variants: 1 },
+    });
+
+    const { graph: reconciled } = reconcileGraph(presented, filtered);
+
+    expect(reconciled.startActivities).toEqual({ A: 2 });
+    expect(reconciled.endActivities).toEqual({ A: 2 });
+    expect(reconciled.totals).toEqual({ cases: 2, events: 4, variants: 1 });
+  });
+
+  it("preserves a surviving element's structural fields (isSelfLoop / isBackEdge) even when zeroed", () => {
+    // A ghosted transition still carries its structural shape — only its statistics zero.
+    const presented = graph({
+      activities: [activity("A")],
+      transitions: [transition("A", "A", { isBackEdge: true, count: 4, caseCount: 4 })],
+    });
+    const filtered = graph({ activities: [activity("A")], transitions: [] });
+
+    const { graph: reconciled } = reconcileGraph(presented, filtered);
+    const ghostEdge = reconciled.transitions[0]!;
+    expect(ghostEdge.isSelfLoop).toBe(true);
+    expect(ghostEdge.isBackEdge).toBe(true);
+    expect(ghostEdge.count).toBe(0);
+  });
+
+  it("passes an extra field on G (AbstractedGraph.hidden) through untouched", () => {
+    const presented: AbstractedGraph = {
+      ...graph({ activities: [activity("A"), activity("B")] }),
+      hidden: { activities: 3, paths: 1 },
+    };
+    const filtered = graph({ activities: [activity("A")] });
+
+    const { graph: reconciled } = reconcileGraph(presented, filtered);
+    expect(reconciled.hidden).toEqual({ activities: 3, paths: 1 });
+  });
+});

package/src/core/reconcile-graph.ts

@@ -0,0 +1,107 @@
+/**
+ * reconcileGraph — merge a FILTERED graph's statistics onto a PRESENTED graph's element set
+ * (RM-052 round 2, issue #227, Invariant F).
+ *
+ * The maintainer's ruling on filtering: keep every process-map step visible, dim the ones a
+ * filter excludes — never remove them. Invariant F makes that ruling mechanical: the set of
+ * activities and transitions a process map renders is a function of the log and the
+ * abstraction alone, never of the active filter intents. Applying or clearing a filter can
+ * only change an element's STATE and the statistics it carries; it can never add or remove a
+ * node or an edge.
+ *
+ * `reconcileGraph` is the pure operation that keeps that promise: given the graph a map is
+ * about to PRESENT (`presented` — the full, abstracted graph, computed with no filter
+ * applied) and the graph the ACTIVE filter actually produced (`filtered`), it returns a graph
+ * with `presented`'s exact element set, where every element also present in `filtered` reads
+ * `filtered`'s statistics, and every element `filtered` dropped becomes a "ghost" — the same
+ * id, at zero. A ghost's statistics are the FILTERED ones (zero), not the full-log ones —
+ * painting full-log numbers on an excluded element would make filtering cosmetic.
+ *
+ * `startActivities`, `endActivities` and `totals` come from `filtered` outright (they are
+ * graph-level facts about what actually survived the filter, not per-element stats to
+ * reconcile). Extra fields the presented graph carries beyond `ProcessGraph` itself (e.g.
+ * `AbstractedGraph.hidden`) pass through untouched — `reconcileGraph` never removes what it
+ * did not add.
+ *
+ * Pipeline ordering is load-bearing: abstraction runs on the FULL graph, BEFORE
+ * reconciliation with the filtered graph. Reconciling first (running abstraction on an
+ * already-filtered graph) would let the zeroed ghosts get treated as least-frequent and
+ * deleted by abstraction's own ranking — reinstating the "filtering removes elements"
+ * behaviour the maintainer ruled against, by a second route.
+ */
+import { emptyDurationStats } from "./duration-stats";
+import { EDGE_KEY_SEPARATOR } from "./discover-graph";
+import type { ProcessGraph, TransitionStats } from "./types";
+
+/** The result of {@link reconcileGraph}. */
+export 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[];
+}
+
+function transitionKey(transition: Pick<TransitionStats, "source" | "target">): string {
+  return `${transition.source}${EDGE_KEY_SEPARATOR}${transition.target}`;
+}
+
+/**
+ * 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.
+ */
+export function reconcileGraph<G extends ProcessGraph>(
+  presented: G,
+  filtered: ProcessGraph,
+): ReconciledGraph<G> {
+  const filteredActivities = new Map(
+    filtered.activities.map((activity) => [activity.id, activity]),
+  );
+  const filteredTransitions = new Map(
+    filtered.transitions.map((transition) => [transitionKey(transition), transition]),
+  );
+
+  const excludedActivities: string[] = [];
+  const activities = presented.activities.map((activity) => {
+    const survivor = filteredActivities.get(activity.id);
+    if (survivor) return survivor;
+    excludedActivities.push(activity.id);
+    return {
+      ...activity,
+      instances: 0,
+      cases: 0,
+      isStart: false,
+      isEnd: false,
+      duration: emptyDurationStats(),
+    };
+  });
+
+  const excludedTransitions: string[] = [];
+  const transitions = presented.transitions.map((transition) => {
+    const key = transitionKey(transition);
+    const survivor = filteredTransitions.get(key);
+    if (survivor) return survivor;
+    excludedTransitions.push(key);
+    return {
+      ...transition,
+      count: 0,
+      caseCount: 0,
+      duration: emptyDurationStats(),
+    };
+  });
+
+  const graph: G = {
+    ...presented,
+    activities,
+    transitions,
+    startActivities: filtered.startActivities,
+    endActivities: filtered.endActivities,
+    totals: filtered.totals,
+  };
+
+  return { graph, excludedActivities, excludedTransitions };
+}

package/src/core/scale.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+
+import { clampWidth, minMax, quantile, quantileSorted } from "./scale";
+
+describe("minMax", () => {
+  it("returns the extent of the finite values", () => {
+    expect(minMax([3, 1, 4, 1, 5])).toEqual([1, 5]);
+  });
+
+  it("ignores non-finite entries rather than propagating them", () => {
+    expect(minMax([Number.NaN, 2, Number.POSITIVE_INFINITY, 8])).toEqual([2, 8]);
+  });
+
+  it("answers [0, 0] when there is nothing finite to measure", () => {
+    expect(minMax([])).toEqual([0, 0]);
+    expect(minMax([Number.NaN])).toEqual([0, 0]);
+  });
+
+  it("handles a single value and negative values", () => {
+    expect(minMax([7])).toEqual([7, 7]);
+    expect(minMax([-5, -1, -9])).toEqual([-9, -1]);
+  });
+});
+
+describe("quantile", () => {
+  it("interpolates linearly between order statistics (R-7)", () => {
+    // pos = 0.9 * (5 - 1) = 3.6 → 40 + 0.6 * (50 - 40) = 46
+    expect(quantile([10, 20, 30, 40, 50], 0.9)).toBe(46);
+  });
+
+  it("returns the median at q = 0.5 for odd and even lengths", () => {
+    expect(quantile([1, 2, 3], 0.5)).toBe(2);
+    expect(quantile([1, 2, 3, 4], 0.5)).toBe(2.5);
+  });
+
+  it("sorts a copy, leaving the caller's array untouched", () => {
+    const values = [5, 1, 3];
+    expect(quantile(values, 0)).toBe(1);
+    expect(values).toEqual([5, 1, 3]);
+  });
+
+  it("clamps q to [0, 1] and answers 0 for an empty input", () => {
+    expect(quantile([1, 2, 3], -1)).toBe(1);
+    expect(quantile([1, 2, 3], 4)).toBe(3);
+    expect(quantile([], 0.5)).toBe(0);
+  });
+
+  it("quantileSorted trusts the caller's ordering", () => {
+    expect(quantileSorted([1, 2, 3, 4, 5], 0.25)).toBe(2);
+    expect(quantileSorted([42], 0.9)).toBe(42);
+  });
+});
+
+describe("clampWidth", () => {
+  it("maps the domain onto the range linearly", () => {
+    expect(clampWidth(0, [0, 10], [1, 5])).toBe(1);
+    expect(clampWidth(5, [0, 10], [1, 5])).toBe(3);
+    expect(clampWidth(10, [0, 10], [1, 5])).toBe(5);
+  });
+
+  it("clamps values outside the domain to the range endpoints", () => {
+    expect(clampWidth(-100, [0, 10], [1, 5])).toBe(1);
+    expect(clampWidth(100, [0, 10], [1, 5])).toBe(5);
+  });
+
+  it("answers the range floor for a degenerate domain", () => {
+    // Every edge in a graph carrying the same count: the domain has zero width, so
+    // there is no information to map and the floor is the documented answer.
+    expect(clampWidth(7, [7, 7], [1, 5])).toBe(1);
+  });
+
+  it("honours a descending domain by inverting the mapping", () => {
+    expect(clampWidth(0, [10, 0], [1, 5])).toBe(5);
+    expect(clampWidth(10, [10, 0], [1, 5])).toBe(1);
+  });
+
+  it("answers the range floor for a non-finite value", () => {
+    expect(clampWidth(Number.NaN, [0, 10], [2, 6])).toBe(2);
+  });
+});