@elabs-ai/components-process 4.2.0 → 5.0.0

package/src/core/adapters/xes.ts

@@ -0,0 +1,384 @@
+/**
+ * XES adapter — RM-063.
+ *
+ * IEEE 1849-2016's interchange format for event logs: a `<log>` of `<trace>`s of
+ * `<event>`s, each carrying `key`/`value` attributes typed by their own element name
+ * (`string`, `date`, `int`, `float`, `boolean`). It is the format most public benchmark
+ * logs — including the BPI Challenge series RM-049's synthetic fixture is modelled on —
+ * actually ship in.
+ *
+ * Parsing is hand-rolled here on purpose, and NOT behind a `DOMParser` fast path:
+ * `/core` must run identically in Node, in a worker and in a browser main thread, and a
+ * parser this narrow — six element names, attribute-only values, the five standard XML
+ * entities, self-closing tags — does not need a general XML engine. `DOMParser` is
+ * unavailable in Node/workers anyway, and branching on its presence would leave one of
+ * the two code paths permanently untested. Do not reach for an XML dependency or
+ * `DOMParser` here; extend the tokenizer below instead.
+ */
+import type { EventLog, EventRow } from "../types";
+
+/** Options for {@link fromXes}. */
+export interface XesParseOptions {
+  /**
+   * Event attribute keys that jointly identify an activity, applied in order and joined
+   * with `"+"` when there is more than one — the same semantics as an XES `<classifier>`
+   * element's `keys` attribute. Defaults to the log's own first `<classifier>`, or
+   * `["concept:name"]` when the log declares none.
+   */
+  classifiers?: string[];
+  /**
+   * How `lifecycle:transition` maps onto {@link EventRow.lifecycle}. `"standard"`
+   * (default) maps the literal value `"start"` to `"start"` and every other XES
+   * lifecycle value (`"complete"`, `"schedule"`, `"suspend"`, …) to `"complete"`;
+   * `"none"` ignores the attribute entirely, so every event stays atomic.
+   */
+  lifecycleModel?: "standard" | "none";
+}
+
+/** One recoverable problem found while reading a XES document. */
+export interface XesParseError {
+  type: "malformed_xml" | "missing_trace" | "missing_concept_name" | "missing_timestamp";
+  message: string;
+  traceIndex?: number;
+  eventIndex?: number;
+}
+
+/**
+ * `fromXes`'s result — mirrors the worker's `{ ok: true, … } | { ok: false, … }` result
+ * convention (`worker/process-worker.ts`), because unlike `fromCsv`/`fromFlatRows` (which
+ * silently skip an incomplete row) a XES document can be genuinely malformed XML, which
+ * has nothing sound left to skip to.
+ */
+export type XesParseResult = { ok: true; log: EventLog } | { ok: false; errors: XesParseError[] };
+
+type XesAttributeValue = string | number | boolean | null;
+
+/** A parsed XML element, scoped to the tags XES actually uses (see the file header). */
+interface XmlElement {
+  tag: string;
+  attrs: Record<string, string>;
+  children: XmlElement[];
+}
+
+/** Thrown only inside {@link parseXmlDocument}; always caught and turned into `malformed_xml`. */
+class XmlSyntaxError extends Error {}
+
+const NAME_STOP = /[\s/>=]/;
+const ENTITY_NAMES: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+
+/** Resolve `&amp;`, `&#39;`, `&#x27;` and friends. Anything unrecognized is left as written. */
+function decodeXmlEntities(text: string): string {
+  return text.replace(/&(#x[0-9a-fA-F]+|#\d+|[a-zA-Z]+);/g, (match, body: string) => {
+    if (body[0] === "#") {
+      const isHex = body[1] === "x" || body[1] === "X";
+      const codePoint = Number.parseInt(body.slice(isHex ? 2 : 1), isHex ? 16 : 10);
+      return Number.isFinite(codePoint) ? String.fromCodePoint(codePoint) : match;
+    }
+    return ENTITY_NAMES[body] ?? match;
+  });
+}
+
+/**
+ * Parse well-formed XML into a tree of {@link XmlElement}, decoding entities as it goes.
+ * Deliberately narrow: no namespaces, no DTDs, no processing-instruction content, no
+ * nested-attribute (XES 2.0) support — the trace/event/string/date/int/float/boolean/
+ * classifier/global vocabulary this adapter reads needs none of that.
+ */
+function parseXmlDocument(text: string): XmlElement {
+  let i = 0;
+  const n = text.length;
+
+  const skipWhitespace = (): void => {
+    while (i < n && /\s/.test(text[i] as string)) i += 1;
+  };
+  const skipUntil = (marker: string, what: string): void => {
+    const at = text.indexOf(marker, i);
+    if (at === -1) throw new XmlSyntaxError(`unterminated ${what}`);
+    i = at + marker.length;
+  };
+  const readName = (): string => {
+    const start = i;
+    while (i < n && !NAME_STOP.test(text[i] as string)) i += 1;
+    if (i === start) throw new XmlSyntaxError(`expected a name at offset ${start}`);
+    return text.slice(start, i);
+  };
+  const readAttrs = (): Record<string, string> => {
+    const attrs: Record<string, string> = {};
+    for (;;) {
+      skipWhitespace();
+      const c = text[i];
+      if (c === undefined) throw new XmlSyntaxError("unexpected end of input in a start tag");
+      if (c === "/" || c === ">") return attrs;
+      const name = readName();
+      skipWhitespace();
+      if (text[i] !== "=") throw new XmlSyntaxError(`expected "=" after attribute "${name}"`);
+      i += 1;
+      skipWhitespace();
+      const quote = text[i];
+      if (quote !== '"' && quote !== "'") {
+        throw new XmlSyntaxError(`expected a quoted value for attribute "${name}"`);
+      }
+      i += 1;
+      const start = i;
+      while (i < n && text[i] !== quote) i += 1;
+      if (i >= n) throw new XmlSyntaxError(`unterminated value for attribute "${name}"`);
+      attrs[name] = decodeXmlEntities(text.slice(start, i));
+      i += 1;
+    }
+  };
+  const readElement = (): XmlElement => {
+    i += 1; // consume '<'
+    const tag = readName();
+    const attrs = readAttrs();
+    skipWhitespace();
+    if (text[i] === "/" && text[i + 1] === ">") {
+      i += 2;
+      return { tag, attrs, children: [] };
+    }
+    if (text[i] !== ">") throw new XmlSyntaxError(`expected ">" closing "<${tag}>"`);
+    i += 1;
+    const children: XmlElement[] = [];
+    for (;;) {
+      const lt = text.indexOf("<", i);
+      if (lt === -1) throw new XmlSyntaxError(`unterminated element "<${tag}>"`);
+      i = lt;
+      if (text.startsWith("<!--", i)) {
+        skipUntil("-->", "comment");
+        continue;
+      }
+      if (text.startsWith("<![CDATA[", i)) {
+        skipUntil("]]>", "CDATA section");
+        continue;
+      }
+      if (text.startsWith("</", i)) {
+        i += 2;
+        const closeName = readName();
+        skipWhitespace();
+        if (text[i] !== ">") throw new XmlSyntaxError(`expected ">" closing "</${closeName}>"`);
+        i += 1;
+        if (closeName !== tag) {
+          throw new XmlSyntaxError(
+            `mismatched closing tag: expected "</${tag}>", found "</${closeName}>"`,
+          );
+        }
+        return { tag, attrs, children };
+      }
+      children.push(readElement());
+    }
+  };
+
+  for (;;) {
+    skipWhitespace();
+    if (i >= n) throw new XmlSyntaxError("empty document");
+    if (text.startsWith("<?", i)) {
+      skipUntil("?>", "processing instruction");
+      continue;
+    }
+    if (text.startsWith("<!--", i)) {
+      skipUntil("-->", "comment");
+      continue;
+    }
+    if (text.startsWith("<!", i)) {
+      skipUntil(">", "declaration");
+      continue;
+    }
+    break;
+  }
+  if (text[i] !== "<") throw new XmlSyntaxError("expected a root element");
+  return readElement();
+}
+
+const XES_VALUE_TAGS = new Set(["string", "date", "int", "float", "boolean"]);
+
+/** Coerce one `<string|date|int|float|boolean key="…" value="…">` into a typed value. */
+function readXesValue(element: XmlElement): XesAttributeValue {
+  const raw = element.attrs.value;
+  if (raw === undefined) return null;
+  if (element.tag === "int") {
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) ? value : raw;
+  }
+  if (element.tag === "float") {
+    const value = Number.parseFloat(raw);
+    return Number.isFinite(value) ? value : raw;
+  }
+  if (element.tag === "boolean") return raw.trim().toLowerCase() === "true";
+  return raw;
+}
+
+/** Read every direct `key`/`value` attribute child (`string`/`date`/`int`/`float`/`boolean`). */
+function readAttributeChildren(children: readonly XmlElement[]): Record<string, XesAttributeValue> {
+  const result: Record<string, XesAttributeValue> = {};
+  for (const child of children) {
+    if (!XES_VALUE_TAGS.has(child.tag)) continue;
+    const key = child.attrs.key;
+    if (key === undefined) continue;
+    result[key] = readXesValue(child);
+  }
+  return result;
+}
+
+/** `own` values win; a `<global>` default only fills a key `own` never set. */
+function withDefaults(
+  own: Record<string, XesAttributeValue>,
+  defaults: Record<string, XesAttributeValue> | undefined,
+): Record<string, XesAttributeValue> {
+  return defaults === undefined ? own : { ...defaults, ...own };
+}
+
+/** Merge every `<global scope="…">` of the given scope, in document order. */
+function collectGlobalDefaults(
+  root: XmlElement,
+  scope: "event" | "trace",
+): Record<string, XesAttributeValue> | undefined {
+  let defaults: Record<string, XesAttributeValue> | undefined;
+  for (const child of root.children) {
+    if (child.tag !== "global" || child.attrs.scope !== scope) continue;
+    defaults = withDefaults(readAttributeChildren(child.children), defaults);
+  }
+  return defaults;
+}
+
+/**
+ * The keys that jointly name an activity: `options.classifiers` when given, else the
+ * log's own first `<classifier>`, else the XES default of `concept:name` alone.
+ */
+function resolveClassifierKeys(root: XmlElement, options: XesParseOptions | undefined): string[] {
+  if (options?.classifiers !== undefined && options.classifiers.length > 0) {
+    return options.classifiers;
+  }
+  const classifier = root.children.find((child) => child.tag === "classifier");
+  const keys = classifier?.attrs.keys?.trim();
+  if (keys !== undefined && keys !== "") return keys.split(/\s+/);
+  return ["concept:name"];
+}
+
+/** The literal value `"start"` maps to `"start"`; every other value collapses to `"complete"`. */
+function mapLifecycle(
+  raw: XesAttributeValue | undefined,
+  model: "standard" | "none",
+): "start" | "complete" | undefined {
+  if (typeof raw !== "string" || model === "none") return undefined;
+  const value = raw.trim().toLowerCase();
+  if (value === "") return undefined;
+  return value === "start" ? "start" : "complete";
+}
+
+/**
+ * Read a IEEE 1849 XES document into an {@link EventLog}.
+ *
+ * Collects every recoverable problem (a trace with no events, an event missing its
+ * activity classifier key(s) or `time:timestamp`) rather than stopping at the first one;
+ * only malformed XML itself — which leaves nothing sound to keep reading — short-circuits
+ * with a single `malformed_xml` error. Output feeds directly into `normalizeLog`, exactly
+ * like `fromCsv`/`fromFlatRows` — no XES-specific branching downstream.
+ */
+export function fromXes(source: string, options?: XesParseOptions): XesParseResult {
+  let root: XmlElement;
+  try {
+    root = parseXmlDocument(source);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, errors: [{ type: "malformed_xml", message }] };
+  }
+
+  const lifecycleModel = options?.lifecycleModel ?? "standard";
+  const classifierKeys = resolveClassifierKeys(root, options);
+  const consumedKeys = new Set([
+    ...classifierKeys,
+    "time:timestamp",
+    "org:resource",
+    "lifecycle:transition",
+  ]);
+  const eventDefaults = collectGlobalDefaults(root, "event");
+  const traceDefaults = collectGlobalDefaults(root, "trace");
+
+  const errors: XesParseError[] = [];
+  const events: EventRow[] = [];
+  let caseAttributes: Record<string, Record<string, unknown>> | undefined;
+
+  const traces = root.children.filter((child) => child.tag === "trace");
+  traces.forEach((trace, traceIndex) => {
+    const traceEvents = trace.children.filter((child) => child.tag === "event");
+    if (traceEvents.length === 0) {
+      errors.push({ type: "missing_trace", message: "trace has no events", traceIndex });
+      return;
+    }
+
+    const { "concept:name": rawCaseId, ...traceValues } = withDefaults(
+      readAttributeChildren(trace.children),
+      traceDefaults,
+    );
+    const caseId =
+      typeof rawCaseId === "string" && rawCaseId !== "" ? rawCaseId : `trace-${traceIndex}`;
+
+    if (Object.keys(traceValues).length > 0) {
+      caseAttributes ??= {};
+      caseAttributes[caseId] = traceValues;
+    }
+
+    traceEvents.forEach((eventElement, eventIndex) => {
+      const values = withDefaults(readAttributeChildren(eventElement.children), eventDefaults);
+
+      const activityParts: string[] = [];
+      let missingActivityKey = false;
+      for (const key of classifierKeys) {
+        const value = values[key];
+        if (value === undefined || value === null) {
+          missingActivityKey = true;
+          break;
+        }
+        activityParts.push(String(value));
+      }
+      if (missingActivityKey) {
+        errors.push({
+          type: "missing_concept_name",
+          message: "event is missing its classifier key(s)",
+          traceIndex,
+          eventIndex,
+        });
+        return;
+      }
+
+      const rawTimestamp = values["time:timestamp"];
+      if (rawTimestamp === undefined || rawTimestamp === null) {
+        errors.push({
+          type: "missing_timestamp",
+          message: "event is missing time:timestamp",
+          traceIndex,
+          eventIndex,
+        });
+        return;
+      }
+
+      const row: EventRow = {
+        caseId,
+        activity: activityParts.join("+"),
+        timestamp: String(rawTimestamp),
+      };
+
+      const resource = values["org:resource"];
+      if (typeof resource === "string" && resource !== "") row.resource = resource;
+
+      const lifecycle = mapLifecycle(values["lifecycle:transition"], lifecycleModel);
+      if (lifecycle !== undefined) row.lifecycle = lifecycle;
+
+      const attributes: Record<string, string | number | boolean | null> = {};
+      let anyAttribute = false;
+      for (const [key, value] of Object.entries(values)) {
+        if (consumedKeys.has(key)) continue;
+        attributes[key] = value;
+        anyAttribute = true;
+      }
+      if (anyAttribute) row.attributes = attributes;
+
+      events.push(row);
+    });
+  });
+
+  if (errors.length > 0) return { ok: false, errors };
+
+  const log: EventLog = { events };
+  if (caseAttributes !== undefined) log.caseAttributes = caseAttributes;
+  return { ok: true, log };
+}

package/src/core/cases-from-log.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+
+import { casesFromLog } from "./cases-from-log";
+import { extractVariants } from "./extract-variants";
+import fixture from "./fixtures/order-to-cash-small.json";
+import type { EventLog } from "./types";
+
+const orderToCash = fixture as EventLog;
+
+describe("casesFromLog", () => {
+  it("answers an empty log with an empty array", () => {
+    expect(casesFromLog({ events: [] })).toEqual([]);
+  });
+
+  it("summarizes each case's own extent, size and duration", () => {
+    const rows = casesFromLog(orderToCash);
+    expect(rows.map((r) => r.caseId)).toEqual(["case-1", "case-2", "case-3", "case-4", "case-5"]);
+
+    const case1 = rows.find((r) => r.caseId === "case-1");
+    expect(case1).toMatchObject({
+      start: "2026-01-05T09:00:00.000Z",
+      end: "2026-01-05T14:00:00.000Z",
+      durationMs: 18_000_000,
+      eventCount: 6,
+    });
+  });
+
+  it("assigns the SAME variantId extractVariants assigns the same case", () => {
+    const rows = casesFromLog(orderToCash);
+    const variants = extractVariants(orderToCash);
+
+    for (const row of rows) {
+      const variant = variants.find((v) => v.caseIds.includes(row.caseId));
+      expect(row.variantId).toBe(variant?.id);
+    }
+
+    // case-1 and case-2 share the five-step happy path — same variant id.
+    const case1 = rows.find((r) => r.caseId === "case-1");
+    const case2 = rows.find((r) => r.caseId === "case-2");
+    expect(case1?.variantId).toBe(case2?.variantId);
+    expect(case1?.variantId).toBeTruthy();
+
+    // case-3 (rejected early) follows a different path.
+    const case3 = rows.find((r) => r.caseId === "case-3");
+    expect(case3?.variantId).not.toBe(case1?.variantId);
+  });
+
+  it("never invents a conformance value", () => {
+    const rows = casesFromLog(orderToCash);
+    expect(rows.every((r) => r.conformance === undefined)).toBe(true);
+  });
+
+  it("carries per-case attributes through untouched", () => {
+    const log: EventLog = {
+      events: [{ caseId: "c1", activity: "A", timestamp: 0 }],
+      caseAttributes: { c1: { region: "EU", priority: 2 } },
+    };
+    const rows = casesFromLog(log);
+    expect(rows[0]?.attributes).toEqual({ region: "EU", priority: 2 });
+  });
+
+  it("answers an empty ISO start/end for a case with no resolvable extent", () => {
+    // A "complete" row whose activity never opened and no explicit startTimestamp still
+    // resolves — the only way to get NaN is an unparseable timestamp on every row.
+    const log: EventLog = {
+      events: [{ caseId: "c1", activity: "A", timestamp: "not-a-date" }],
+    };
+    const rows = casesFromLog(log);
+    expect(rows[0]?.start).toBe("");
+    expect(rows[0]?.end).toBe("");
+  });
+});

package/src/core/cases-from-log.ts

@@ -0,0 +1,85 @@
+/**
+ * casesFromLog — RM-055.
+ *
+ * A pure per-case summary over an event log: one {@link CaseRow} per case, shaped for
+ * `CaseTable`'s default columns and CSV export (`toCsv`). `variantId` is read off
+ * {@link extractVariants} rather than recomputed independently — `extractVariants` is the
+ * one place that disambiguates a 64-bit hash collision between two different sequences
+ * with a `-1`/`-2` suffix, so recomputing `variantId(sequence)` here directly would
+ * silently diverge from a variant explorer over the SAME log on the rare log where that
+ * disambiguation fires. Reading it off `extractVariants`'s own `caseIds` keeps the two
+ * views byte-identical always, not just usually.
+ *
+ * Framework-free, deterministic: no React, no `Date.now()`, no randomness. See
+ * `.claude/rules/data.md` — nothing under `src/core/` may import React or an
+ * `@elabs-ai/components-*` package.
+ */
+import { asNormalizedLog, type NormalizedCase } from "./event-log";
+import { extractVariants } from "./extract-variants";
+import type { EventLog } from "./types";
+
+/**
+ * One case's own summary — its extent, size and path identity, not its trace. The shape
+ * `CaseTable` (case-table/) renders one row per, and `CaseTimeline`'s own model reads a
+ * single case's raw `EventRow[]` separately (a summary row has no per-activity detail to
+ * build a Gantt row from).
+ */
+export interface CaseRow {
+  caseId: string;
+  /** ISO 8601. Empty string when the case has no resolvable extent — see `normalizeLog`. */
+  start: string;
+  end: string;
+  durationMs: number;
+  eventCount: number;
+  /** Identical to the `id` {@link extractVariants} assigns the SAME case over the SAME log. */
+  variantId: string;
+  /**
+   * Never set here: no conformance model lives in `/core` (`ProcessKpiStrip`'s own
+   * `conformance` prop treats it the same way — a fitted value the HOST supplies, never a
+   * number this package invents). A caller with a conformance result attaches it per row.
+   */
+  conformance?: "conforming" | "nonConforming" | "unknown";
+  /** Carried over from `EventLog.caseAttributes`, untouched. */
+  attributes?: Record<string, string | number | boolean | null>;
+}
+
+/** `NaN` (no resolvable extent) becomes `""`, never a thrown `RangeError` or `"Invalid Date"`. */
+function toIso(ms: number): string {
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : "";
+}
+
+function toCaseRow(kase: NormalizedCase, variantId: string): CaseRow {
+  const row: CaseRow = {
+    caseId: kase.caseId,
+    start: toIso(kase.start),
+    end: toIso(kase.end),
+    durationMs: Number.isFinite(kase.duration) ? kase.duration : 0,
+    eventCount: kase.events.length,
+    variantId,
+  };
+  if (kase.attributes !== undefined) {
+    row.attributes = kase.attributes as Record<string, string | number | boolean | null>;
+  }
+  return row;
+}
+
+/**
+ * One summary row per case in `log`, in the same first-appearance order `normalizeLog`
+ * produces. `variantId` is sourced from {@link extractVariants} over the identical log —
+ * see the module docblock for why that, and not a direct `variantId(sequence)` call, is
+ * what keeps a `CaseTable` and a variant explorer over the same log always agreeing on
+ * which cases share a path.
+ *
+ * An empty log answers an empty array.
+ */
+export function casesFromLog(log: EventLog): CaseRow[] {
+  const normalized = asNormalizedLog(log);
+  if (normalized.cases.length === 0) return [];
+
+  const variantIdByCase = new Map<string, string>();
+  for (const variant of extractVariants(normalized)) {
+    for (const caseId of variant.caseIds) variantIdByCase.set(caseId, variant.id);
+  }
+
+  return normalized.cases.map((kase) => toCaseRow(kase, variantIdByCase.get(kase.caseId) ?? ""));
+}

package/src/core/conformance.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+
+import { conformanceRateSeries } from "./conformance";
+import * as core from "./index";
+import { liftHappyPath } from "./reference-model";
+import type { EventLog, EventRow } from "./types";
+
+const model = liftHappyPath({
+  id: "p",
+  label: "Path",
+  steps: [{ activity: "A" }, { activity: "B" }, { activity: "C" }],
+});
+
+function caseRows(caseId: string, start: number, trace: string[]): EventRow[] {
+  return trace.map((activity, i) => ({ caseId, activity, timestamp: start + i * 3_600_000 }));
+}
+
+// Three months: January all conforming, February one of two, March one incomplete case.
+const log: EventLog = {
+  events: [
+    ...caseRows("jan-1", Date.UTC(2026, 0, 3), ["A", "B", "C"]),
+    ...caseRows("jan-2", Date.UTC(2026, 0, 20), ["A", "B", "C"]),
+    ...caseRows("feb-1", Date.UTC(2026, 1, 2), ["A", "B", "C"]),
+    ...caseRows("feb-2", Date.UTC(2026, 1, 14), ["A", "B"]),
+    ...caseRows("mar-1", Date.UTC(2026, 2, 30), ["A", "B"]),
+  ],
+};
+
+describe("conformanceRateSeries", () => {
+  it("returns one bucket per month whose case counts sum to the log total", () => {
+    const series = conformanceRateSeries(log, model, "month");
+    expect(series.map((p) => p.bucket)).toEqual(["2026-01", "2026-02", "2026-03"]);
+    expect(series.map((p) => p.caseCount)).toEqual([2, 2, 1]);
+    expect(series.reduce((sum, p) => sum + p.caseCount, 0)).toBe(5);
+    // A, B then stop: p=3, c=3, m=1, r=1 → ½(1−1/3) + ½(1−1/3) = 2/3.
+    expect(series[0]?.fitness).toBe(1);
+    expect(series[1]?.fitness).toBeCloseTo((1 + 2 / 3) / 2, 12);
+    expect(series[2]?.fitness).toBeCloseTo(2 / 3, 12);
+  });
+
+  it("buckets by UTC day and by the UTC Monday of the week", () => {
+    expect(conformanceRateSeries(log, model, "day").map((p) => p.bucket)).toEqual([
+      "2026-01-03",
+      "2026-01-20",
+      "2026-02-02",
+      "2026-02-14",
+      "2026-03-30",
+    ]);
+    // 2026-01-03 is a Saturday → week of Monday 2025-12-29; 2026-03-30 is itself a Monday.
+    expect(conformanceRateSeries(log, model, "week").map((p) => p.bucket)).toEqual([
+      "2025-12-29",
+      "2026-01-19",
+      "2026-02-02",
+      "2026-02-09",
+      "2026-03-30",
+    ]);
+  });
+
+  it("leaves out a case with no resolvable start instead of inventing a bucket", () => {
+    const withBad: EventLog = {
+      events: [...log.events, { caseId: "bad", activity: "A", timestamp: "garbage" }],
+    };
+    const total = conformanceRateSeries(withBad, model, "month").reduce(
+      (sum, p) => sum + p.caseCount,
+      0,
+    );
+    expect(total).toBe(5);
+  });
+});
+
+describe("core scope boundary (analysis §9 risk 2)", () => {
+  it("exports the replay API and no alignment search or BPMN import", () => {
+    expect(typeof core.liftHappyPath).toBe("function");
+    expect(typeof core.replayTrace).toBe("function");
+    expect(typeof core.tokenReplay).toBe("function");
+    expect(typeof core.conformanceRateSeries).toBe("function");
+    const forbidden = Object.keys(core).filter((name) => /align|bpmn|petri/i.test(name));
+    expect(forbidden).toEqual([]);
+  });
+});