@elabs-ai/components-process 4.1.0

package/src/core/duration-stats.ts

@@ -0,0 +1,162 @@
+/**
+ * Duration summary statistics — RM-049.
+ *
+ * The single implementation every part of the core reads: per-activity execution time,
+ * per-edge flow time and per-variant case time all pass through here, which is what makes
+ * "the variant's median agrees with the edge's median on the same fixture" true by
+ * construction rather than by coincidence.
+ *
+ * Algorithm shape (which statistics a discovered graph carries per activity and per edge)
+ * follows pm4js — see `ATTRIBUTION.md`. No pm4js code is copied; the arithmetic below is
+ * the ordinary textbook definition.
+ */
+import { ascending, quantileSorted } from "./scale";
+import type { DurationStats } from "./types";
+
+/** The fraction discarded from EACH tail by `trimmedMean`. */
+export const TRIM_FRACTION = 0.1;
+
+/** All-zero statistics — the answer for an empty sample set. */
+export const EMPTY_DURATION_STATS: Readonly<DurationStats> = Object.freeze({
+  min: 0,
+  max: 0,
+  mean: 0,
+  median: 0,
+  p90: 0,
+  sum: 0,
+  trimmedMean: 0,
+});
+
+/** A fresh mutable copy of {@link EMPTY_DURATION_STATS}. */
+export function emptyDurationStats(): DurationStats {
+  return { ...EMPTY_DURATION_STATS };
+}
+
+/**
+ * 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.
+ */
+export function durationStats(samples: readonly number[]): DurationStats {
+  const sorted: number[] = [];
+  for (const s of samples) if (Number.isFinite(s)) sorted.push(s);
+  const n = sorted.length;
+  if (n === 0) return emptyDurationStats();
+  sorted.sort(ascending);
+
+  let sum = 0;
+  for (const s of sorted) sum += s;
+
+  const trim = Math.floor(n * TRIM_FRACTION);
+  const lo = trim;
+  const hi = n - trim;
+  let trimmedMean: number;
+  if (hi - lo <= 0) {
+    trimmedMean = sum / n;
+  } else {
+    let trimmedSum = 0;
+    for (let i = lo; i < hi; i += 1) trimmedSum += sorted[i] as number;
+    trimmedMean = trimmedSum / (hi - lo);
+  }
+
+  return {
+    min: sorted[0] as number,
+    max: sorted[n - 1] as number,
+    mean: sum / n,
+    median: quantileSorted(sorted, 0.5),
+    p90: quantileSorted(sorted, 0.9),
+    sum,
+    trimmedMean,
+  };
+}
+
+/** Default reservoir capacity for a single activity's or edge's duration samples. */
+export const DURATION_SAMPLE_CAP = 4096;
+
+/**
+ * A deterministic 32-bit PRNG (mulberry32). Same seed, same stream — which is the whole
+ * point: the reservoir below must make identical keep/discard decisions on every run, in
+ * every engine, or two runs over one log would produce different `p90`s.
+ */
+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;
+  };
+}
+
+/**
+ * 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.
+ */
+export class DurationSampler {
+  private readonly capacity: number;
+  private readonly random: () => number;
+  private readonly reservoir: number[] = [];
+  /** Number of finite samples offered, including those the reservoir discarded. */
+  private seen = 0;
+  private total = 0;
+  private lowest = Number.POSITIVE_INFINITY;
+  private highest = Number.NEGATIVE_INFINITY;
+
+  constructor(seed = 0x9e3779b9, capacity: number = DURATION_SAMPLE_CAP) {
+    this.capacity = capacity > 0 ? capacity : 1;
+    this.random = mulberry32(seed);
+  }
+
+  /** Offer one sample. Non-finite values are ignored. */
+  add(sample: number): void {
+    if (!Number.isFinite(sample)) return;
+    this.total += sample;
+    if (sample < this.lowest) this.lowest = sample;
+    if (sample > this.highest) this.highest = sample;
+    if (this.reservoir.length < this.capacity) {
+      this.reservoir.push(sample);
+    } else {
+      const j = Math.floor(this.random() * (this.seen + 1));
+      if (j < this.capacity) this.reservoir[j] = sample;
+    }
+    this.seen += 1;
+  }
+
+  /** True number of finite samples offered. */
+  get size(): number {
+    return this.seen;
+  }
+
+  /**
+   * 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 {
+    if (this.seen === 0) return emptyDurationStats();
+    const fromReservoir = durationStats(this.reservoir);
+    return {
+      ...fromReservoir,
+      min: this.lowest,
+      max: this.highest,
+      sum: this.total,
+      mean: this.total / this.seen,
+    };
+  }
+}

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

@@ -0,0 +1,224 @@
+import { describe, expect, it } from "vitest";
+
+import { asNormalizedLog, isNormalizedLog, normalizeLog, toEpochMs } from "./event-log";
+import type { EventLog } from "./types";
+
+const T = (iso: string): number => Date.parse(iso);
+
+describe("toEpochMs", () => {
+  it("resolves all three accepted timestamp encodings", () => {
+    expect(toEpochMs("2026-01-05T09:00:00.000Z")).toBe(T("2026-01-05T09:00:00.000Z"));
+    expect(toEpochMs(1_767_600_000_000)).toBe(1_767_600_000_000);
+    expect(toEpochMs(new Date("2026-01-05T09:00:00.000Z"))).toBe(T("2026-01-05T09:00:00.000Z"));
+  });
+
+  it("reads a bare numeric string as epoch milliseconds", () => {
+    expect(toEpochMs("1767600000000")).toBe(1_767_600_000_000);
+  });
+
+  it("answers NaN for an unparseable or absent value instead of throwing", () => {
+    expect(toEpochMs("not a date")).toBeNaN();
+    expect(toEpochMs(undefined)).toBeNaN();
+    expect(toEpochMs(null)).toBeNaN();
+  });
+});
+
+describe("normalizeLog", () => {
+  it("groups by case and orders each case in time without sorting the whole log", () => {
+    const log: EventLog = {
+      events: [
+        { caseId: "b", activity: "B2", timestamp: "2026-01-05T11:00:00Z" },
+        { caseId: "a", activity: "A2", timestamp: "2026-01-05T10:00:00Z" },
+        { caseId: "b", activity: "B1", timestamp: "2026-01-05T09:00:00Z" },
+        { caseId: "a", activity: "A1", timestamp: "2026-01-05T09:30:00Z" },
+      ],
+    };
+    const normalized = normalizeLog(log);
+    // Cases keep FIRST-APPEARANCE order; events inside each case are sorted.
+    expect(normalized.cases.map((c) => c.caseId)).toEqual(["b", "a"]);
+    expect(normalized.cases[0]?.events.map((e) => e.activity)).toEqual(["B1", "B2"]);
+    expect(normalized.cases[1]?.events.map((e) => e.activity)).toEqual(["A1", "A2"]);
+    expect(normalized.totals).toEqual({ cases: 2, events: 4 });
+  });
+
+  it("pairs start/complete rows that are NOT adjacent in the input", () => {
+    // Interleaved lifecycle rows, and the rows themselves arrive out of time order.
+    const log: EventLog = {
+      events: [
+        {
+          caseId: "c1",
+          activity: "Pack",
+          lifecycle: "complete",
+          timestamp: "2026-01-05T12:00:00Z",
+        },
+        { caseId: "c1", activity: "Pick", lifecycle: "start", timestamp: "2026-01-05T09:00:00Z" },
+        { caseId: "c1", activity: "Pack", lifecycle: "start", timestamp: "2026-01-05T10:00:00Z" },
+        {
+          caseId: "c1",
+          activity: "Pick",
+          lifecycle: "complete",
+          timestamp: "2026-01-05T11:00:00Z",
+        },
+      ],
+    };
+    const [kase] = normalizeLog(log).cases;
+    expect(kase?.events).toEqual([
+      {
+        activity: "Pick",
+        start: T("2026-01-05T09:00:00Z"),
+        end: T("2026-01-05T11:00:00Z"),
+        duration: 7_200_000,
+        isOpen: false,
+      },
+      {
+        activity: "Pack",
+        start: T("2026-01-05T10:00:00Z"),
+        end: T("2026-01-05T12:00:00Z"),
+        duration: 7_200_000,
+        isOpen: false,
+      },
+    ]);
+    expect(kase?.duration).toBe(10_800_000);
+  });
+
+  it("pairs repeated executions of one activity oldest-start to earliest-complete", () => {
+    const log: EventLog = {
+      events: [
+        { caseId: "c1", activity: "Pick", lifecycle: "start", timestamp: "2026-01-05T09:00:00Z" },
+        { caseId: "c1", activity: "Pick", lifecycle: "start", timestamp: "2026-01-05T09:30:00Z" },
+        {
+          caseId: "c1",
+          activity: "Pick",
+          lifecycle: "complete",
+          timestamp: "2026-01-05T10:00:00Z",
+        },
+        {
+          caseId: "c1",
+          activity: "Pick",
+          lifecycle: "complete",
+          timestamp: "2026-01-05T11:00:00Z",
+        },
+      ],
+    };
+    const events = normalizeLog(log).cases[0]?.events ?? [];
+    expect(events.map((e) => [e.start, e.end])).toEqual([
+      [T("2026-01-05T09:00:00Z"), T("2026-01-05T10:00:00Z")],
+      [T("2026-01-05T09:30:00Z"), T("2026-01-05T11:00:00Z")],
+    ]);
+  });
+
+  it("leaves an unmatched start OPEN rather than inventing a completion", () => {
+    const log: EventLog = {
+      events: [
+        { caseId: "c1", activity: "Pick", lifecycle: "start", timestamp: "2026-01-05T09:00:00Z" },
+      ],
+    };
+    const event = normalizeLog(log).cases[0]?.events[0];
+    expect(event?.isOpen).toBe(true);
+    expect(event?.start).toBe(event?.end);
+    expect(event?.duration).toBe(0);
+  });
+
+  it("uses an explicit startTimestamp when a complete row has no matching start", () => {
+    const log: EventLog = {
+      events: [
+        {
+          caseId: "c1",
+          activity: "Ship",
+          lifecycle: "complete",
+          startTimestamp: "2026-01-05T09:00:00Z",
+          timestamp: "2026-01-05T10:00:00Z",
+        },
+      ],
+    };
+    expect(normalizeLog(log).cases[0]?.events[0]).toMatchObject({
+      start: T("2026-01-05T09:00:00Z"),
+      duration: 3_600_000,
+      isOpen: false,
+    });
+  });
+
+  it("treats a row with no lifecycle as atomic", () => {
+    const log: EventLog = {
+      events: [{ caseId: "c1", activity: "Ship", timestamp: "2026-01-05T10:00:00Z" }],
+    };
+    const event = normalizeLog(log).cases[0]?.events[0];
+    expect(event?.start).toBe(event?.end);
+    expect(event?.duration).toBe(0);
+    expect(event?.isOpen).toBe(false);
+  });
+
+  it("floors a clock-skewed pair at zero instead of reporting a negative duration", () => {
+    const log: EventLog = {
+      events: [
+        {
+          caseId: "c1",
+          activity: "Ship",
+          startTimestamp: "2026-01-05T11:00:00Z",
+          timestamp: "2026-01-05T10:00:00Z",
+        },
+      ],
+    };
+    expect(normalizeLog(log).cases[0]?.events[0]?.duration).toBe(0);
+  });
+
+  it("carries resources, event attributes and case attributes through", () => {
+    const log: EventLog = {
+      events: [
+        {
+          caseId: "c1",
+          activity: "Ship",
+          timestamp: "2026-01-05T10:00:00Z",
+          resource: "Warehouse Robot",
+          attributes: { carrier: "DPD", cost: 12.5 },
+        },
+      ],
+      caseAttributes: { c1: { region: "North" } },
+    };
+    const [kase] = normalizeLog(log).cases;
+    expect(kase?.attributes).toEqual({ region: "North" });
+    expect(kase?.events[0]).toMatchObject({
+      resource: "Warehouse Robot",
+      attributes: { carrier: "DPD", cost: 12.5 },
+    });
+  });
+
+  it("drops rows with no case id or no activity", () => {
+    const log: EventLog = {
+      events: [
+        { caseId: "", activity: "Ship", timestamp: 1 },
+        { caseId: "c1", activity: "", timestamp: 2 },
+        { caseId: "c1", activity: "Ship", timestamp: 3 },
+      ],
+    };
+    expect(normalizeLog(log).totals).toEqual({ cases: 1, events: 1 });
+  });
+
+  it("keeps rows with an unparseable timestamp in their input order", () => {
+    const log: EventLog = {
+      events: [
+        { caseId: "c1", activity: "First", timestamp: "nonsense" },
+        { caseId: "c1", activity: "Second", timestamp: "also nonsense" },
+      ],
+    };
+    expect(normalizeLog(log).cases[0]?.events.map((e) => e.activity)).toEqual(["First", "Second"]);
+  });
+
+  it("answers an empty log with an empty result", () => {
+    expect(normalizeLog({ events: [] })).toEqual({ cases: [], totals: { cases: 0, events: 0 } });
+  });
+});
+
+describe("asNormalizedLog", () => {
+  it("is idempotent — a normalized log passes through untouched", () => {
+    const once = normalizeLog({
+      events: [{ caseId: "c1", activity: "Ship", timestamp: 10 }],
+    });
+    expect(isNormalizedLog(once)).toBe(true);
+    expect(asNormalizedLog(once)).toBe(once);
+  });
+
+  it("recognizes a raw log", () => {
+    expect(isNormalizedLog({ events: [] })).toBe(false);
+  });
+});

package/src/core/event-log.ts

@@ -0,0 +1,244 @@
+/**
+ * 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.
+ */
+import type { EventLog, EventRow } from "./types";
+
+/** One activity execution, with both ends resolved to epoch milliseconds. */
+export 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. */
+export 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. */
+export interface NormalizedLog {
+  cases: NormalizedCase[];
+  totals: { cases: number; events: number };
+}
+
+/** A log in either shape. Every derivation entry point accepts both. */
+export type AnyLog = EventLog | NormalizedLog;
+
+/** Narrowing predicate — `true` when `log` has already been through {@link normalizeLog}. */
+export function isNormalizedLog(log: AnyLog): log is NormalizedLog {
+  return Array.isArray((log as NormalizedLog).cases);
+}
+
+/** Normalize `log` unless it already is normalized. The idempotent entry point. */
+export function asNormalizedLog(log: AnyLog): NormalizedLog {
+  return isNormalizedLog(log) ? log : normalizeLog(log);
+}
+
+/**
+ * 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.
+ */
+export function toEpochMs(value: string | number | Date | undefined | null): number {
+  if (value === undefined || value === null) return Number.NaN;
+  if (typeof value === "number") return Number.isFinite(value) ? value : Number.NaN;
+  if (value instanceof Date) return value.getTime();
+  const parsed = Date.parse(value);
+  if (!Number.isNaN(parsed)) return parsed;
+  // A bare numeric string ("1735725600000") is a legitimate epoch encoding that
+  // `Date.parse` reads as a year in some engines; treat it as epoch ms explicitly.
+  const asNumber = Number(value);
+  return Number.isFinite(asNumber) && value.trim() !== "" ? asNumber : Number.NaN;
+}
+
+/** Stable comparator that leaves `NaN`-timestamped rows in their input order. */
+function byTimestamp(a: { at: number }, b: { at: number }): number {
+  if (Number.isNaN(a.at) || Number.isNaN(b.at)) return 0;
+  return a.at - b.at;
+}
+
+interface StagedRow {
+  at: number;
+  row: EventRow;
+}
+
+/**
+ * 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.
+ */
+export function normalizeLog(log: EventLog): NormalizedLog {
+  const staged = new Map<string, StagedRow[]>();
+  const order: string[] = [];
+
+  for (const row of log.events) {
+    if (!row || typeof row.caseId !== "string" || row.caseId === "") continue;
+    if (typeof row.activity !== "string" || row.activity === "") continue;
+    let bucket = staged.get(row.caseId);
+    if (bucket === undefined) {
+      bucket = [];
+      staged.set(row.caseId, bucket);
+      order.push(row.caseId);
+    }
+    bucket.push({ at: toEpochMs(row.timestamp), row });
+  }
+
+  const cases: NormalizedCase[] = [];
+  let events = 0;
+
+  for (const caseId of order) {
+    const bucket = staged.get(caseId) as StagedRow[];
+    // `Array.prototype.sort` is stable (ES2019), so equal timestamps keep input order.
+    bucket.sort(byTimestamp);
+
+    const instances: NormalizedEvent[] = [];
+    /** activity → FIFO queue of indices into `instances` awaiting a `"complete"`. */
+    const open = new Map<string, number[]>();
+
+    for (const { at, row } of bucket) {
+      if (row.lifecycle === "start") {
+        const index = instances.length;
+        instances.push(makeInstance(row, at, at, true));
+        const queue = open.get(row.activity);
+        if (queue === undefined) open.set(row.activity, [index]);
+        else queue.push(index);
+        continue;
+      }
+
+      if (row.lifecycle === "complete") {
+        const queue = open.get(row.activity);
+        const index = queue?.shift();
+        if (index !== undefined) {
+          const instance = instances[index] as NormalizedEvent;
+          instance.end = at;
+          instance.duration = durationOf(instance.start, at);
+          instance.isOpen = false;
+          if (instance.resource === undefined && row.resource !== undefined) {
+            instance.resource = row.resource;
+          }
+          if (instance.attributes === undefined && row.attributes !== undefined) {
+            instance.attributes = row.attributes;
+          }
+          continue;
+        }
+      }
+
+      const end = at;
+      const explicitStart = toEpochMs(row.startTimestamp);
+      const start = Number.isNaN(explicitStart) ? end : explicitStart;
+      instances.push(makeInstance(row, start, end, false));
+    }
+
+    if (instances.length === 0) continue;
+
+    // Pairing can move an instance's start earlier than the row that created it, so the
+    // trace is re-ordered by resolved start. It is already almost sorted, which is the
+    // best case for the engine's TimSort — this is not a second full sort in practice.
+    instances.sort(byStart);
+
+    let caseStart = Number.POSITIVE_INFINITY;
+    let caseEnd = Number.NEGATIVE_INFINITY;
+    for (const instance of instances) {
+      if (Number.isFinite(instance.start) && instance.start < caseStart) caseStart = instance.start;
+      if (Number.isFinite(instance.end) && instance.end > caseEnd) caseEnd = instance.end;
+    }
+    const hasExtent =
+      caseStart !== Number.POSITIVE_INFINITY && caseEnd !== Number.NEGATIVE_INFINITY;
+
+    const normalizedCase: NormalizedCase = {
+      caseId,
+      events: instances,
+      start: hasExtent ? caseStart : Number.NaN,
+      end: hasExtent ? caseEnd : Number.NaN,
+      duration: hasExtent ? durationOf(caseStart, caseEnd) : Number.NaN,
+    };
+    const caseAttributes = log.caseAttributes?.[caseId];
+    if (caseAttributes !== undefined) normalizedCase.attributes = caseAttributes;
+
+    cases.push(normalizedCase);
+    events += instances.length;
+  }
+
+  return { cases, totals: { cases: cases.length, events } };
+}
+
+function byStart(a: NormalizedEvent, b: NormalizedEvent): number {
+  if (Number.isNaN(a.start) || Number.isNaN(b.start)) return 0;
+  return a.start - b.start;
+}
+
+function durationOf(start: number, end: number): number {
+  const delta = end - start;
+  if (!Number.isFinite(delta)) return Number.NaN;
+  return delta < 0 ? 0 : delta;
+}
+
+function makeInstance(row: EventRow, start: number, end: number, isOpen: boolean): NormalizedEvent {
+  const instance: NormalizedEvent = {
+    activity: row.activity,
+    start,
+    end,
+    duration: durationOf(start, end),
+    isOpen,
+  };
+  if (row.resource !== undefined) instance.resource = row.resource;
+  if (row.attributes !== undefined) instance.attributes = row.attributes;
+  return instance;
+}