@elabs-ai/components-process 4.1.0

package/src/core/extract-variants.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest";
+
+import { discoverGraph } from "./discover-graph";
+import { extractVariants, variantId, variantKey, VARIANT_KEY_SEPARATOR } from "./extract-variants";
+import { generateSyntheticLog } from "./fixtures/synthetic-log";
+import fixture from "./fixtures/order-to-cash-small.json";
+import type { EventLog } from "./types";
+
+const orderToCash = fixture as EventLog;
+
+describe("variantKey / variantId", () => {
+  it("joins on a C0 control character no activity name can contain", () => {
+    expect(VARIANT_KEY_SEPARATOR).toHaveLength(1);
+    expect(VARIANT_KEY_SEPARATOR.charCodeAt(0)).toBe(1);
+    expect(variantKey(["A", "B"]).split(VARIANT_KEY_SEPARATOR)).toEqual(["A", "B"]);
+  });
+
+  it("does not collide for sequences a printable separator would merge", () => {
+    // "A, B" as one activity vs "A" then "B" — a comma separator would key both "A, B".
+    expect(variantId(["A, B"])).not.toBe(variantId(["A", " B"]));
+  });
+
+  it("is stable across calls and sensitive to order", () => {
+    expect(variantId(["A", "B", "C"])).toBe(variantId(["A", "B", "C"]));
+    expect(variantId(["A", "B", "C"])).not.toBe(variantId(["C", "B", "A"]));
+  });
+});
+
+describe("extractVariants on the 5-case order-to-cash fixture", () => {
+  const variants = extractVariants(orderToCash);
+
+  it("groups the five cases into the four hand-counted variants", () => {
+    expect(variants.map((v) => [v.count, v.caseIds])).toEqual([
+      [2, ["case-1", "case-2"]],
+      [1, ["case-4"]],
+      [1, ["case-5"]],
+      [1, ["case-3"]],
+    ]);
+    expect(variants[0]?.sequence).toEqual([
+      "Create Order",
+      "Check Credit",
+      "Approve Order",
+      "Ship Order",
+      "Send Invoice",
+      "Receive Payment",
+    ]);
+  });
+
+  it("agrees with discoverGraph on the variant count", () => {
+    expect(variants).toHaveLength(discoverGraph(orderToCash).totals.variants);
+  });
+
+  it("sums share to 1", () => {
+    const total = variants.reduce((sum, variant) => sum + variant.share, 0);
+    expect(total).toBeCloseTo(1, 10);
+    expect(variants.map((v) => v.share)).toEqual([0.4, 0.2, 0.2, 0.2]);
+  });
+
+  it("keeps cumulativeShare monotonically non-decreasing, ending exactly at 1", () => {
+    let previous = 0;
+    for (const variant of variants) {
+      expect(variant.cumulativeShare).toBeGreaterThanOrEqual(previous);
+      previous = variant.cumulativeShare;
+    }
+    expect(variants.map((v) => v.cumulativeShare)).toEqual([0.4, 0.6, 0.8, 1]);
+    expect(variants[variants.length - 1]?.cumulativeShare).toBe(1);
+  });
+
+  it("summarizes END-TO-END case durations, not step durations", () => {
+    // case-1 and case-2 each run 09:00 to 14:00 — five hours.
+    expect(variants[0]?.duration).toEqual({
+      min: 18_000_000,
+      max: 18_000_000,
+      mean: 18_000_000,
+      median: 18_000_000,
+      p90: 18_000_000,
+      sum: 36_000_000,
+      trimmedMean: 18_000_000,
+    });
+    // case-3 is rejected after two hours; case-5 runs ten.
+    expect(variants[3]?.duration.sum).toBe(7_200_000);
+    expect(variants[2]?.duration.sum).toBe(36_000_000);
+  });
+
+  it("gives every variant a distinct, reproducible id", () => {
+    const ids = variants.map((v) => v.id);
+    expect(new Set(ids).size).toBe(ids.length);
+    expect(ids).toEqual(extractVariants(orderToCash).map((v) => v.id));
+    expect(variants[0]?.id).toBe(variantId(variants[0]?.sequence ?? []));
+  });
+});
+
+describe("extractVariants ordering and edge cases", () => {
+  it("ranks by count descending and breaks ties by key, so the order is total", () => {
+    const log: EventLog = {
+      events: [
+        { caseId: "c1", activity: "B", timestamp: 0 },
+        { caseId: "c2", activity: "A", timestamp: 0 },
+        { caseId: "c3", activity: "C", timestamp: 0 },
+        { caseId: "c4", activity: "C", timestamp: 1 },
+      ],
+    };
+    expect(extractVariants(log).map((v) => [v.sequence, v.count])).toEqual([
+      [["C"], 2],
+      [["A"], 1],
+      [["B"], 1],
+    ]);
+  });
+
+  it("answers an empty log with an empty array, not a zero-count variant", () => {
+    expect(extractVariants({ events: [] })).toEqual([]);
+  });
+
+  it("holds the two invariants on a large synthetic log too", () => {
+    const variants = extractVariants(generateSyntheticLog({ cases: 500, seed: 7 }));
+    expect(variants.length).toBeGreaterThan(1);
+    expect(variants.reduce((sum, v) => sum + v.share, 0)).toBeCloseTo(1, 10);
+    let previous = 0;
+    for (const variant of variants) {
+      expect(variant.cumulativeShare).toBeGreaterThanOrEqual(previous);
+      previous = variant.cumulativeShare;
+    }
+    expect(previous).toBe(1);
+    expect(variants.reduce((sum, v) => sum + v.count, 0)).toBe(500);
+  });
+});

package/src/core/extract-variants.ts

@@ -0,0 +1,140 @@
+/**
+ * Variant extraction — RM-049.
+ *
+ * A "variant" is one distinct activity sequence, together with every case that follows
+ * it. Grouping traces by their sequence and ranking those groups by frequency is the
+ * standard second view onto a log (the first being the directly-follows graph), and the
+ * grouping shape below follows pm4js; see `ATTRIBUTION.md`. No pm4js code is copied.
+ *
+ * Deterministic: ids are hashes of the sequence, ordering is fully tie-broken, and the
+ * cumulative share is computed from counts rather than by summing floats, so it is exactly
+ * `1` on the last variant instead of `0.9999999999999998`.
+ */
+import { durationStats } from "./duration-stats";
+import { asNormalizedLog, type AnyLog, type NormalizedCase } from "./event-log";
+import type { Variant } from "./types";
+
+/**
+ * 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.
+ */
+export const VARIANT_KEY_SEPARATOR = "\u0001";
+
+/** Join an activity sequence into its canonical variant key. */
+export function variantKey(sequence: readonly string[]): string {
+  return sequence.join(VARIANT_KEY_SEPARATOR);
+}
+
+/** FNV-1a, 32-bit. Small, fast, dependency-free and identical in every engine. */
+function fnv1a32(text: string, basis: number): number {
+  let hash = basis >>> 0;
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+function hex8(value: number): string {
+  return (value >>> 0).toString(16).padStart(8, "0");
+}
+
+/**
+ * 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.
+ */
+export function variantId(sequence: readonly string[]): string {
+  const key = variantKey(sequence);
+  return `v${hex8(fnv1a32(key, 0x811c9dc5))}${hex8(fnv1a32(key, 0x84222325))}`;
+}
+
+interface VariantAccumulator {
+  key: string;
+  sequence: string[];
+  caseIds: string[];
+  durations: number[];
+}
+
+/**
+ * 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.
+ */
+export function extractVariants(log: AnyLog): Variant[] {
+  const normalized = asNormalizedLog(log);
+  const totalCases = normalized.cases.length;
+  if (totalCases === 0) return [];
+
+  const groups = new Map<string, VariantAccumulator>();
+  for (const kase of normalized.cases) {
+    const sequence = sequenceOf(kase);
+    const key = variantKey(sequence);
+    let group = groups.get(key);
+    if (group === undefined) {
+      group = { key, sequence, caseIds: [], durations: [] };
+      groups.set(key, group);
+    }
+    group.caseIds.push(kase.caseId);
+    group.durations.push(kase.duration);
+  }
+
+  const ranked = [...groups.values()].sort(
+    (a, b) => b.caseIds.length - a.caseIds.length || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0),
+  );
+
+  const taken = new Set<string>();
+  const variants: Variant[] = [];
+  let cumulativeCount = 0;
+
+  for (const group of ranked) {
+    const count = group.caseIds.length;
+    cumulativeCount += count;
+    // A 64-bit hash collision between two different sequences is vanishingly unlikely,
+    // but "vanishingly unlikely" is not "impossible" and a duplicate id would silently
+    // merge two rows in a table. Disambiguate deterministically: `ranked` is totally
+    // ordered, so the suffix an id receives is the same on every run.
+    let id = variantId(group.sequence);
+    if (taken.has(id)) {
+      let suffix = 1;
+      while (taken.has(`${id}-${suffix}`)) suffix += 1;
+      id = `${id}-${suffix}`;
+    }
+    taken.add(id);
+
+    variants.push({
+      id,
+      sequence: group.sequence,
+      count,
+      share: count / totalCases,
+      cumulativeShare: cumulativeCount / totalCases,
+      caseIds: group.caseIds,
+      duration: durationStats(group.durations),
+    });
+  }
+
+  return variants;
+}
+
+function sequenceOf(kase: NormalizedCase): string[] {
+  const sequence = new Array<string>(kase.events.length);
+  for (let i = 0; i < kase.events.length; i += 1) {
+    sequence[i] = (kase.events[i] as { activity: string }).activity;
+  }
+  return sequence;
+}

package/src/core/filter-log.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it } from "vitest";
+
+import { discoverGraph } from "./discover-graph";
+import { normalizeLog } from "./event-log";
+import { extractVariants, variantId } from "./extract-variants";
+import { caseMatchesFilters, filterLog, filterNormalizedLog, type FilterSpec } from "./filter-log";
+import fixture from "./fixtures/order-to-cash-small.json";
+import type { EventLog } from "./types";
+
+const orderToCash = fixture as EventLog;
+
+/**
+ * The five traces in `order-to-cash-small.json` (see `discover-graph.test.ts` for the
+ * full listing). What matters here:
+ *
+ *   case-1, case-2  the happy path, ending in Receive Payment
+ *   case-3          Create Order · Check Credit · Reject Order
+ *   case-4          the happy path with an Amend Order detour and a second Check Credit
+ *   case-5          the happy path with Send Invoice and Ship Order swapped
+ */
+const survivors = (log: EventLog, specs: FilterSpec[]): string[] => [
+  ...new Set(filterLog(log, specs).events.map((row) => row.caseId)),
+];
+
+describe("filterLog case predicates", () => {
+  it("keeps or drops on activity presence", () => {
+    expect(survivors(orderToCash, [{ kind: "with", activity: "Reject Order" }])).toEqual([
+      "case-3",
+    ]);
+    expect(survivors(orderToCash, [{ kind: "without", activity: "Reject Order" }])).toEqual([
+      "case-1",
+      "case-2",
+      "case-4",
+      "case-5",
+    ]);
+  });
+
+  it("matches on the first and last activity of a trace", () => {
+    expect(survivors(orderToCash, [{ kind: "startsWith", activity: "Create Order" }])).toHaveLength(
+      5,
+    );
+    expect(survivors(orderToCash, [{ kind: "endsWith", activity: "Reject Order" }])).toEqual([
+      "case-3",
+    ]);
+  });
+
+  it("separates a direct follower from an eventual one", () => {
+    // Ship Order is directly followed by Send Invoice in cases 1, 2 and 4; in case-5 the
+    // two are swapped, so Send Invoice still EVENTUALLY follows nothing of the sort —
+    // there Ship Order comes second and Receive Payment follows it.
+    expect(
+      survivors(orderToCash, [
+        { kind: "follower", a: "Ship Order", b: "Send Invoice", direct: true },
+      ]),
+    ).toEqual(["case-1", "case-2", "case-4"]);
+    expect(
+      survivors(orderToCash, [{ kind: "follower", a: "Create Order", b: "Receive Payment" }]),
+    ).toEqual(["case-1", "case-2", "case-4", "case-5"]);
+    // Eventually-follows is not symmetric, and does not fire on the same occurrence twice.
+    expect(
+      survivors(orderToCash, [{ kind: "follower", a: "Receive Payment", b: "Create Order" }]),
+    ).toEqual([]);
+  });
+
+  it("filters on the case's throughput time, inclusive at both bounds", () => {
+    const durations = normalizeLog(orderToCash).cases.map((kase) => kase.duration);
+    const shortest = Math.min(...durations);
+    expect(survivors(orderToCash, [{ kind: "duration", max: shortest }])).toEqual(["case-3"]);
+    expect(survivors(orderToCash, [{ kind: "duration", min: shortest }])).toHaveLength(5);
+    expect(survivors(orderToCash, [{ kind: "duration" }])).toHaveLength(5);
+  });
+
+  it("selects by variant id and by case id", () => {
+    const variants = extractVariants(orderToCash);
+    const busiest = variants[0] as { id: string; caseIds: string[] };
+    expect(survivors(orderToCash, [{ kind: "variant", ids: [busiest.id] }])).toEqual(
+      busiest.caseIds,
+    );
+    expect(variantId(["Create Order", "Check Credit", "Reject Order"])).toBe(
+      (variants.find((variant) => variant.sequence.includes("Reject Order")) as { id: string }).id,
+    );
+    expect(survivors(orderToCash, [{ kind: "cases", ids: ["case-2", "case-5"] }])).toEqual([
+      "case-2",
+      "case-5",
+    ]);
+  });
+
+  it("ANDs its specs, and keeps everything when given none", () => {
+    expect(
+      survivors(orderToCash, [
+        { kind: "with", activity: "Check Credit" },
+        { kind: "without", activity: "Amend Order" },
+        { kind: "endsWith", activity: "Receive Payment" },
+      ]),
+    ).toEqual(["case-1", "case-2", "case-5"]);
+    expect(filterLog(orderToCash, [])).toBe(orderToCash);
+  });
+});
+
+describe("filterLog attribute predicates", () => {
+  const withAttributes: EventLog = {
+    events: [
+      { caseId: "c1", activity: "A", timestamp: 0, resource: "Robot" },
+      { caseId: "c1", activity: "B", timestamp: 1000, resource: "Ada" },
+      { caseId: "c2", activity: "A", timestamp: 0, resource: "Ada" },
+      { caseId: "c3", activity: "A", timestamp: 0, attributes: { amount: 250 } },
+    ],
+    caseAttributes: {
+      c1: { region: "North", priority: 3 },
+      c2: { region: "South", priority: 1 },
+    },
+  };
+
+  const keep = (spec: FilterSpec): string[] => survivors(withAttributes, [spec]);
+
+  it("reads a case attribute", () => {
+    expect(keep({ kind: "attribute", key: "region", op: "eq", value: "North" })).toEqual(["c1"]);
+    expect(keep({ kind: "attribute", key: "priority", op: "gt", value: 2 })).toEqual(["c1"]);
+    expect(keep({ kind: "attribute", key: "priority", op: "lt", value: 2 })).toEqual(["c2"]);
+    expect(keep({ kind: "attribute", key: "region", op: "in", value: ["North", "South"] })).toEqual(
+      ["c1", "c2"],
+    );
+  });
+
+  it("falls back to the events — including `resource` — when the case has no such attribute", () => {
+    expect(keep({ kind: "attribute", key: "resource", op: "eq", value: "Robot" })).toEqual(["c1"]);
+    expect(keep({ kind: "attribute", key: "resource", op: "eq", value: "Ada" })).toEqual([
+      "c1",
+      "c2",
+    ]);
+    expect(keep({ kind: "attribute", key: "amount", op: "gt", value: 100 })).toEqual(["c3"]);
+  });
+
+  it("treats `ne` as the negation of `eq`, not as `some value differs`", () => {
+    // c1's events carry BOTH Robot and Ada, so an `eq`/`ne` pair on the same value must
+    // never both match it — otherwise a filter and its complement would overlap.
+    const matched = keep({ kind: "attribute", key: "resource", op: "eq", value: "Ada" });
+    const unmatched = keep({ kind: "attribute", key: "resource", op: "ne", value: "Ada" });
+    expect(matched).toEqual(["c1", "c2"]);
+    expect(unmatched).toEqual(["c3"]);
+    expect(matched.filter((id) => unmatched.includes(id))).toEqual([]);
+  });
+
+  it("does not compare across types, and needs an array for `in`", () => {
+    expect(keep({ kind: "attribute", key: "priority", op: "gt", value: "2" })).toEqual([]);
+    expect(keep({ kind: "attribute", key: "region", op: "in", value: "North" })).toEqual([]);
+  });
+
+  it("narrows caseAttributes to the survivors", () => {
+    const filtered = filterLog(withAttributes, [
+      { kind: "attribute", key: "region", op: "eq", value: "North" },
+    ]);
+    expect(filtered.caseAttributes).toEqual({ c1: { region: "North", priority: 3 } });
+  });
+});
+
+describe("filterLog composition", () => {
+  it("keeps every ROW of a surviving case, in input order", () => {
+    const filtered = filterLog(orderToCash, [{ kind: "with", activity: "Amend Order" }]);
+    expect(filtered.events).toEqual(orderToCash.events.filter((row) => row.caseId === "case-4"));
+  });
+
+  it("feeds discoverGraph and extractVariants unchanged", () => {
+    const filtered = filterLog(orderToCash, [{ kind: "without", activity: "Reject Order" }]);
+    const graph = discoverGraph(filtered);
+    expect(graph.totals.cases).toBe(4);
+    expect(graph.activities.map((activity) => activity.id)).not.toContain("Reject Order");
+    expect(extractVariants(filtered).map((variant) => variant.count)).toEqual([2, 1, 1]);
+  });
+
+  it("agrees with filterNormalizedLog, which normalizes at most once", () => {
+    const specs: FilterSpec[] = [{ kind: "endsWith", activity: "Receive Payment" }];
+    const normalized = normalizeLog(orderToCash);
+    const viaNormalized = filterNormalizedLog(normalized, specs);
+    expect(viaNormalized.cases.map((kase) => kase.caseId)).toEqual(survivors(orderToCash, specs));
+    expect(viaNormalized.totals).toEqual({ cases: 4, events: 26 });
+    // The surviving cases are the ORIGINAL objects — no re-derivation happened.
+    for (const kase of viaNormalized.cases) expect(normalized.cases).toContain(kase);
+  });
+
+  it("returns the input untouched when there is nothing to filter on", () => {
+    const normalized = normalizeLog(orderToCash);
+    expect(filterNormalizedLog(normalized, [])).toBe(normalized);
+  });
+
+  it("exposes the predicate on its own, for highlighting rather than removing", () => {
+    const normalized = normalizeLog(orderToCash);
+    const rejected = normalized.cases.filter((kase) =>
+      caseMatchesFilters(kase, [{ kind: "with", activity: "Reject Order" }]),
+    );
+    expect(rejected.map((kase) => kase.caseId)).toEqual(["case-3"]);
+  });
+});

package/src/core/filter-log.ts

@@ -0,0 +1,215 @@
+/**
+ * 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.
+ */
+import { asNormalizedLog, type AnyLog, type NormalizedCase, type NormalizedLog } from "./event-log";
+import { variantId } from "./extract-variants";
+import type { EventLog } from "./types";
+
+/** One case-level predicate. {@link filterLog} ANDs a list of them. */
+export 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[] };
+
+/** The activity sequence of a normalized case. */
+function sequenceOf(kase: NormalizedCase): string[] {
+  const sequence = new Array<string>(kase.events.length);
+  for (let i = 0; i < kase.events.length; i += 1) {
+    sequence[i] = (kase.events[i] as { activity: string }).activity;
+  }
+  return sequence;
+}
+
+/**
+ * Every value the case offers for `key`.
+ *
+ * Case attributes win: when `caseAttributes` defines the key, that single value IS the
+ * case's answer. Otherwise the key is looked for on the events — including `resource`,
+ * which is a first-class field rather than an entry in `attributes` — and the case offers
+ * every distinct value its events carry. So "cases handled by the credit service" is
+ * expressible without the caller pre-aggregating anything.
+ */
+function valuesFor(kase: NormalizedCase, key: string): unknown[] {
+  const attributes = kase.attributes;
+  if (attributes !== undefined && Object.hasOwn(attributes, key)) return [attributes[key]];
+
+  const values: unknown[] = [];
+  const seen = new Set<unknown>();
+  for (const event of kase.events) {
+    const value = key === "resource" ? event.resource : event.attributes?.[key];
+    if (value === undefined) continue;
+    if (seen.has(value)) continue;
+    seen.add(value);
+    values.push(value);
+  }
+  return values;
+}
+
+/** `>` / `<` over two numbers or two strings; anything else does not compare. */
+function ordered(left: unknown, right: unknown, wantGreater: boolean): boolean {
+  if (typeof left === "number" && typeof right === "number") {
+    return wantGreater ? left > right : left < right;
+  }
+  if (typeof left === "string" && typeof right === "string") {
+    return wantGreater ? left > right : left < right;
+  }
+  return false;
+}
+
+function matchesAttribute(
+  kase: NormalizedCase,
+  spec: Extract<FilterSpec, { kind: "attribute" }>,
+): boolean {
+  const values = valuesFor(kase, spec.key);
+  switch (spec.op) {
+    case "eq":
+      return values.some((value) => Object.is(value, spec.value));
+    // `ne` is the negation of `eq`, not "some value differs" — otherwise a case offering
+    // two resources would satisfy both `eq` and `ne` against the same value.
+    case "ne":
+      return !values.some((value) => Object.is(value, spec.value));
+    case "gt":
+      return values.some((value) => ordered(value, spec.value, true));
+    case "lt":
+      return values.some((value) => ordered(value, spec.value, false));
+    case "in": {
+      if (!Array.isArray(spec.value)) return false;
+      const allowed = spec.value as unknown[];
+      return values.some((value) => allowed.some((candidate) => Object.is(value, candidate)));
+    }
+    default:
+      return false;
+  }
+}
+
+function matchesOne(kase: NormalizedCase, sequence: readonly string[], spec: FilterSpec): boolean {
+  switch (spec.kind) {
+    case "with":
+      return sequence.includes(spec.activity);
+    case "without":
+      return !sequence.includes(spec.activity);
+    case "startsWith":
+      return sequence[0] === spec.activity;
+    case "endsWith":
+      return sequence[sequence.length - 1] === spec.activity;
+    case "follower": {
+      if (spec.direct === true) {
+        for (let i = 0; i + 1 < sequence.length; i += 1) {
+          if (sequence[i] === spec.a && sequence[i + 1] === spec.b) return true;
+        }
+        return false;
+      }
+      const first = sequence.indexOf(spec.a);
+      if (first < 0) return false;
+      return sequence.indexOf(spec.b, first + 1) >= 0;
+    }
+    case "attribute":
+      return matchesAttribute(kase, spec);
+    case "duration": {
+      if (spec.min === undefined && spec.max === undefined) return true;
+      // An unmeasurable case (every timestamp unparseable) cannot satisfy a bound.
+      if (!Number.isFinite(kase.duration)) return false;
+      if (spec.min !== undefined && kase.duration < spec.min) return false;
+      if (spec.max !== undefined && kase.duration > spec.max) return false;
+      return true;
+    }
+    case "variant":
+      return spec.ids.includes(variantId(sequence));
+    case "cases":
+      return spec.ids.includes(kase.caseId);
+    default:
+      return true;
+  }
+}
+
+/**
+ * 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.
+ */
+export function caseMatchesFilters(kase: NormalizedCase, specs: readonly FilterSpec[]): boolean {
+  if (specs.length === 0) return true;
+  const sequence = sequenceOf(kase);
+  for (const spec of specs) {
+    if (!matchesOne(kase, sequence, spec)) return false;
+  }
+  return true;
+}
+
+/**
+ * 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.
+ */
+export function filterNormalizedLog(log: AnyLog, specs: readonly FilterSpec[]): NormalizedLog {
+  const normalized = asNormalizedLog(log);
+  if (specs.length === 0) return normalized;
+
+  const cases: NormalizedCase[] = [];
+  let events = 0;
+  for (const kase of normalized.cases) {
+    if (!caseMatchesFilters(kase, specs)) continue;
+    cases.push(kase);
+    events += kase.events.length;
+  }
+  return { cases, totals: { cases: cases.length, events } };
+}
+
+/**
+ * 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.
+ */
+export function filterLog(log: EventLog, specs: readonly FilterSpec[]): EventLog {
+  if (specs.length === 0) return log;
+  const kept = new Set<string>();
+  for (const kase of filterNormalizedLog(log, specs).cases) kept.add(kase.caseId);
+
+  const filtered: EventLog = { events: log.events.filter((row) => kept.has(row?.caseId)) };
+  if (log.caseAttributes !== undefined) {
+    const caseAttributes: Record<string, Record<string, unknown>> = {};
+    for (const caseId of Object.keys(log.caseAttributes)) {
+      if (kept.has(caseId)) {
+        caseAttributes[caseId] = log.caseAttributes[caseId] as Record<string, unknown>;
+      }
+    }
+    filtered.caseAttributes = caseAttributes;
+  }
+  return filtered;
+}