@loomwork/event-runtime 0.0.0-stage → 0.1.0

package/src/leases.ts

@@ -0,0 +1,319 @@
+// ── Durable ownership of a running execution (#380) ───────────────────────────
+//
+// A `running` execution owned by a healthy node is byte-identical, in the log, to one
+// orphaned by a dead one: the difference is a fact about the cluster, not about the
+// execution, so no fold can see it. That is why `recoverAbandoned` demands a predicate — and
+// why a double dispatch today is merely SAFE rather than avoided. Fencing (K9.4) rejects the
+// loser's write; both runs still executed, and both still paid for their effects.
+//
+// A lease is the missing fact: ownership with an expiry, written where both nodes can see it.
+//
+// Deliberately shaped like `TimerStore`: a small store with a polling service above it, no
+// coordination protocol, and nothing required of a deployment that does not want it. Unwired,
+// every path behaves byte-identically (G2).
+
+/**
+ * SPI version for the {@link LeaseStore} contract. Pinned by `runLeaseStoreConformance`.
+ *
+ * 2.0.0 (L28): `expired`'s `now` became optional and MUST default to the store's stamping clock.
+ * MAJOR, not additive: a 1.x store written `expired(now: number)` still type-checks against the
+ * new signature but, handed `undefined`, returns `[]` — recovery silently recovers nothing.
+ *
+ * 2.1.0 (L29): optional `storeNow()` — the store's own clock. Additive: a store without it behaves
+ * exactly as before, and a caller with no `storeNow()` falls back to `Date.now()`.
+ *
+ * 2.2.0 (ADR 0130 D11, heartbeat leases): optional `scope` (who can see this store's leases:
+ * "process" | "host" | "cluster"; absent = unknown, treated as NOT cluster-visible), optional `acquireMany` / `renewMany` (returns the HELD
+ * set) / `releaseMany`, and the `steal` option on `acquire`. Additive: a store without them is
+ * driven through the single-id methods by the caller (correct, just slower). A store that claims
+ * 2.2.0 implements all three batch methods and the steal gate; one that claims 2.1.0 is not asked.
+ */
+export const LEASE_STORE_SPI_VERSION = "2.2.0";
+
+export interface Lease {
+  executionId: string;
+  /** Who holds it. A node id, a pod name, a process uuid — the deployment's vocabulary. */
+  owner: string;
+  /**
+   * Absolute expiry (epoch ms), on the store's clock (the one `expired()` defaults to), not
+   * necessarily the caller's. Past this, the lease is collectable by anyone.
+   */
+  expiresAt: number;
+}
+
+/**
+ * The proof a caller must hold to `steal` a lease: the fence it won with a CONDITIONAL fence
+ * acquisition (`acquireFenceIf`, i.e. proof the execution is parked). The store cannot verify it
+ * against the event log (the lease store is deliberately a separate, dumb SPI); it can only refuse
+ * a steal that does not even carry one, so a flag cannot be passed by accident.
+ *
+ * The proof is SHAPE-ONLY. Callers MUST pass a fence actually won via `acquireFenceIf` /
+ * `acquireFence` for THIS execution. A bogus steal is a liveness attack, never log corruption:
+ * the live owner's next `renew` fails (`LeaseLostError`), but the fence is the write guard
+ * (ADR 0130 D11 section 4), so the stale owner's appends are still rejected. An explicit `now`
+ * bypasses the expiry gate on every backend (pre-existing): production callers must never pass
+ * `now`, and on Postgres should omit it so the DATABASE clock rules.
+ */
+export interface StealProof {
+  /** The fence value the caller won: a positive safe integer (0 is the inert park token, ADR 0118). */
+  fence: number;
+}
+
+/** Options for {@link LeaseStore.acquire} / {@link LeaseStore.acquireMany} (SPI 2.2.0). */
+export interface AcquireOptions {
+  /**
+   * Take the lease even though ANOTHER owner holds it unexpired (a slow release left a stale row
+   * behind a driver that has already proved the execution is parked). Valid ONLY with a
+   * {@link StealProof}; anything else (`true`, `{}`, a negative or fractional fence) THROWS
+   * `TypeError` and changes nothing. After a release (no row), a steal is just an acquire. The
+   * displaced owner's next `renew`/`renewMany` reports it lost (`false` / absent).
+   *
+   * Single-id `acquire` ONLY: a fence belongs to one execution, so `acquireMany` REJECTS `steal`
+   * with `TypeError` (nothing changes).
+   */
+  steal?: StealProof;
+}
+
+export interface LeaseStore {
+  /**
+   * OPTIONAL (SPI 2.2.0): who can observe this store's leases. `"process"`: one process (in-memory);
+   * `"host"`: processes on one machine (a local file); `"cluster"`: every node (a shared server).
+   * Absent means unknown and is treated as NOT cluster-visible. Heartbeat evidence ("a lease
+   * expired, so the driver is gone") holds only if every node reads the same table.
+   */
+  readonly scope?: "process" | "host" | "cluster";
+  /**
+   * Take ownership, or report that someone else has it.
+   *
+   * Returns the lease on success and `null` when another owner holds an unexpired one — that
+   * single `null` is the mutual exclusion "only one node should run this execution" needs.
+   * Re-acquiring a lease you already hold is a renewal, not a conflict: a node that restarts
+   * its own work must not be locked out by its own previous claim.
+   *
+   * An EXPIRED lease is acquirable by anyone, which is the whole point — the previous owner
+   * stopped saying it was alive.
+   */
+  acquire(
+    executionId: string,
+    owner: string,
+    ttlMs: number,
+    now?: number,
+    options?: AcquireOptions
+  ): Promise<Lease | null>;
+  /**
+   * OPTIONAL (SPI 2.2.0): `acquire` for many executions in ONE round trip. Returns the leases
+   * granted; an id another owner holds unexpired is simply absent (the batch form of `null`).
+   * Duplicate ids count once. Per id the semantics are exactly {@link acquire}'s, and `now`
+   * applies to the whole batch. `options.steal` THROWS `TypeError` (steals go through `acquire`). Empty input returns `[]` without touching the store.
+   */
+  acquireMany?(
+    executionIds: readonly string[],
+    owner: string,
+    ttlMs: number,
+    now?: number,
+    options?: AcquireOptions
+  ): Promise<Lease[]>;
+  /**
+   * OPTIONAL (SPI 2.2.0): `renew` for many executions in one round trip. Returns the HELD set:
+   * the ids whose lease this `owner` still holds after the call (their expiry extended). Every
+   * other id, released, taken over, or never held, is absent, and nothing about it changes: a
+   * renew NEVER resurrects. The returned set is what a keeper diffs against its own to find the
+   * lost ids, so a store must not echo its input.
+   */
+  renewMany?(
+    executionIds: readonly string[],
+    owner: string,
+    ttlMs: number,
+    now?: number
+  ): Promise<string[]>;
+  /** OPTIONAL (SPI 2.2.0): `release` for many executions in one round trip; other owners' are untouched. */
+  releaseMany?(executionIds: readonly string[], owner: string): Promise<void>;
+  /**
+   * Extend a lease you hold. `false` means you no longer hold it — someone else took over
+   * after it expired — and a caller that keeps working on `false` is the split-brain this
+   * exists to surface. Never resurrects: renewing an expired lease that another owner has
+   * since taken fails rather than stealing it back.
+   */
+  renew(executionId: string, owner: string, ttlMs: number, now?: number): Promise<boolean>;
+  /**
+   * Leases past their expiry, soonest-expired first. The evidence an execution was orphaned.
+   *
+   * `now` is OPTIONAL (SPI 2.0.0) and an implementation MUST default it to the store's OWN
+   * clock — the same one `acquire`/`renew` stamp `expiresAt` with. Expiry is only meaningful
+   * judged on the clock that stamped it: a caller passing wall-clock `Date.now()` to a store
+   * running on an injected/simulated clock sees every live lease as expired (a
+   * double-execution hazard). Callers with no reason to override the clock
+   * (`recoverAbandoned`) pass `undefined`. An implementation that still declares
+   * `expired(now: number)` compiles, but given `undefined` its comparison is false (`<=
+   * undefined`, SQL `<= NULL`) and it returns `[]`: recovery silently recovers nothing.
+   *
+   * The SQL stores' "own clock" is one clock for every node: SQLite is single-host, so the
+   * process clock is its one clock; Postgres stamps and judges on DATABASE time (L29), so node
+   * skew cannot make a live lease look expired or let a fast node steal one.
+   */
+  expired(now?: number, limit?: number): Promise<Lease[]>;
+  /**
+   * OPTIONAL read: the lease on an execution, or `null` if nothing holds one.
+   *
+   * `expired()` answers "who stopped saying they were alive", which cannot distinguish an
+   * execution someone is actively renewing from one that never had a lease at all. That
+   * distinction is the whole question for `orphanCensus` (#408): a stuck execution with NO
+   * lease is a path nothing is watching, and counting those is how "should the runtime lease
+   * every run" stops being a guess.
+   */
+  get?(executionId: string): Promise<Lease | null>;
+  /**
+   * OPTIONAL (SPI 2.1.0): the store's OWN clock, in epoch ms, the one `expiresAt` is stamped and
+   * `expired()` judged on. A reader that must compare `expiresAt` to "now" outside the store
+   * (`orphanCensus`) asks this rather than assuming its host's `Date.now()`, which for a shared
+   * database (Postgres stamps on DB time) is a different clock. Absent means the store uses the
+   * caller-visible process clock.
+   */
+  storeNow?(): Promise<number>;
+  /** Give it up. Releasing a lease held by someone else is a no-op, never a steal. */
+  release(executionId: string, owner: string): Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface InMemoryLeaseStoreOptions {
+  /** Injectable clock, as everywhere else in the runtime. Default: `Date.now`. */
+  now?: () => number;
+}
+
+/**
+ * Map-backed {@link LeaseStore} — the browser-safe / test reference implementation beside the
+ * durable backends. Behaviour is pinned by `runLeaseStoreConformance`.
+ */
+export class InMemoryLeaseStore implements LeaseStore {
+  readonly scope = "process" as const;
+  private readonly leases = new Map<string, Lease>();
+  private readonly now: () => number;
+
+  constructor(options: InMemoryLeaseStoreOptions = {}) {
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  async acquire(
+    executionId: string,
+    owner: string,
+    ttlMs: number,
+    now = this.now(),
+    options?: AcquireOptions
+  ): Promise<Lease | null> {
+    assertTtl(ttlMs);
+    const steal = assertSteal(options);
+    const held = this.leases.get(executionId);
+    // Someone else's, and still alive (unless the caller proved it may take it).
+    if (held !== undefined && held.owner !== owner && held.expiresAt > now && !steal) return null;
+    const lease: Lease = { executionId, owner, expiresAt: now + ttlMs };
+    this.leases.set(executionId, lease);
+    return { ...lease };
+  }
+
+  async acquireMany(
+    executionIds: readonly string[],
+    owner: string,
+    ttlMs: number,
+    now = this.now(),
+    options?: AcquireOptions
+  ): Promise<Lease[]> {
+    assertTtl(ttlMs);
+    assertNoBatchSteal(options);
+    const out: Lease[] = [];
+    for (const id of new Set(executionIds)) {
+      const lease = await this.acquire(id, owner, ttlMs, now);
+      if (lease !== null) out.push(lease);
+    }
+    return out;
+  }
+
+  async renewMany(
+    executionIds: readonly string[],
+    owner: string,
+    ttlMs: number,
+    now = this.now()
+  ): Promise<string[]> {
+    assertTtl(ttlMs);
+    const held: string[] = [];
+    for (const id of new Set(executionIds))
+      if (await this.renew(id, owner, ttlMs, now)) held.push(id);
+    return held;
+  }
+
+  async releaseMany(executionIds: readonly string[], owner: string): Promise<void> {
+    for (const id of new Set(executionIds)) await this.release(id, owner);
+  }
+
+  async renew(
+    executionId: string,
+    owner: string,
+    ttlMs: number,
+    now = this.now()
+  ): Promise<boolean> {
+    assertTtl(ttlMs);
+    const held = this.leases.get(executionId);
+    if (held === undefined || held.owner !== owner) return false;
+    held.expiresAt = now + ttlMs;
+    return true;
+  }
+
+  async expired(now = this.now(), limit = 100): Promise<Lease[]> {
+    return [...this.leases.values()]
+      .filter((l) => l.expiresAt <= now)
+      .sort((a, b) => a.expiresAt - b.expiresAt)
+      .slice(0, limit)
+      .map((l) => ({ ...l }));
+  }
+
+  async get(executionId: string): Promise<Lease | null> {
+    const held = this.leases.get(executionId);
+    return held !== undefined ? { ...held } : null;
+  }
+
+  /** The store's own (injectable) clock: the one `expiresAt` is stamped and judged on (SPI 2.1.0). */
+  async storeNow(): Promise<number> {
+    return this.now();
+  }
+
+  async release(executionId: string, owner: string): Promise<void> {
+    const held = this.leases.get(executionId);
+    if (held?.owner === owner) this.leases.delete(executionId);
+  }
+
+  async close(): Promise<void> {
+    this.leases.clear();
+  }
+}
+
+/** A zero or negative TTL would make a lease expired on arrival — refuse it at every backend. */
+export function assertTtl(ttlMs: number): void {
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+    throw new RangeError(`lease ttlMs must be a positive number of milliseconds, got ${ttlMs}`);
+  }
+}
+
+/**
+ * The `steal` gate every backend applies BEFORE touching storage: `true` only for a real
+ * {@link StealProof}; `undefined` options or no `steal` is `false`; anything else THROWS
+ * `TypeError` (a flag is never a proof).
+ */
+export function assertSteal(options: AcquireOptions | undefined): boolean {
+  const steal = options?.steal as unknown;
+  if (steal === undefined) return false;
+  const fence = (steal as { fence?: unknown } | null)?.fence;
+  if (typeof fence !== "number" || !Number.isSafeInteger(fence) || fence < 1) {
+    throw new TypeError(
+      "lease steal requires a conditional-fence proof: { steal: { fence: <positive integer> } }"
+    );
+  }
+  return true;
+}
+
+/** `acquireMany` takes no `steal`: a fence belongs to one execution. THROWS `TypeError`, changing nothing. */
+export function assertNoBatchSteal(options: AcquireOptions | undefined): void {
+  if ((options?.steal as unknown) !== undefined) {
+    throw new TypeError(
+      "acquireMany does not accept `steal`: a fence belongs to one execution; steal through acquire()"
+    );
+  }
+}

package/src/payloadShredded.ts

@@ -0,0 +1,63 @@
+/**
+ * The realm-safe brand of the erasure outcome (ADR 0039, amendment 2026-10-17 (c)). A crypto-shredded
+ * payload is recognised by THIS symbol, never by the error's `name` alone: any store decorator, third
+ * party store or app code can throw an `Error` that merely NAMES itself `PayloadShreddedError`, and on
+ * the authorization path "proven erasure" means "unknown owner", which `unknownOwner: "allow"` admits.
+ *
+ * `Symbol.for` (the global registry) makes the brand survive duplicated package copies (dual CJS/ESM
+ * builds, two installs), where `instanceof` does not. A store that cannot extend the crypto plugin's
+ * class sets the brand on its own error with {@link brandPayloadShredded}.
+ */
+export const PAYLOAD_SHREDDED_BRAND: unique symbol = Symbol.for("loom.payloadShredded") as never;
+
+/**
+ * Mark `err` as the erasure outcome (non-enumerable, so serialization and logging are unchanged) and
+ * return it. Idempotent. The error's `name` and message are untouched.
+ *
+ * Brand BEFORE freezing: a frozen or otherwise non-extensible object cannot take the brand, and
+ * throwing here would replace the erasure with a TypeError. For such an object this returns a branded
+ * WRAPPER instead (a new `Error` with the same name, message, own fields and stack, `cause` = the
+ * original), so the erasure is still recognised.
+ */
+export function brandPayloadShredded<T extends object>(err: T): T {
+  if (!Object.isExtensible(err)) {
+    const src = err as unknown as Record<string, unknown>;
+    const wrapper = new Error(typeof src.message === "string" ? src.message : "", { cause: err });
+    for (const key of Object.getOwnPropertyNames(src)) {
+      if (key === "cause") continue;
+      const d = Object.getOwnPropertyDescriptor(src, key);
+      if (d !== undefined) Object.defineProperty(wrapper, key, { ...d, configurable: true });
+    }
+    if (!Object.prototype.hasOwnProperty.call(src, "name") && typeof src.name === "string") {
+      Object.defineProperty(wrapper, "name", {
+        value: src.name,
+        configurable: true,
+        writable: true,
+      });
+    }
+    return brandPayloadShredded(wrapper) as unknown as T;
+  }
+  Object.defineProperty(err, PAYLOAD_SHREDDED_BRAND, {
+    value: true,
+    enumerable: false,
+    configurable: true,
+    writable: false,
+  });
+  return err;
+}
+
+/**
+ * True when `err` carries the {@link PAYLOAD_SHREDDED_BRAND} as an OWN property (an inherited brand,
+ * e.g. from a shared prototype, does not count). The ONE definition every consumer uses.
+ * A plain object or `Error` that only has `name === "PayloadShreddedError"` is NOT shredded, and a
+ * value that crossed a process boundary (JSON) has lost the brand: such a boundary must re-establish
+ * trust explicitly (e.g. by checking the log's own `PAYLOAD_SHREDDED` tombstone).
+ */
+export function isPayloadShredded(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    Object.prototype.hasOwnProperty.call(err, PAYLOAD_SHREDDED_BRAND) &&
+    (err as Record<symbol, unknown>)[PAYLOAD_SHREDDED_BRAND] === true
+  );
+}

package/src/scaleDecorators.bench.ts

@@ -0,0 +1,107 @@
+import type { EventEnvelope } from "@loomwork/core";
+import { bench, describe } from "vitest";
+import { CoalescingEventStore } from "./CoalescingEventStore";
+import { InMemoryAsyncEventStore } from "./InMemoryAsyncEventStore";
+import { ShardedEventStore } from "./ShardedEventStore";
+import type { EventStore } from "./types";
+
+// ── What the scale-out decorators cost and buy (ADR 0074) ────────────────────
+//
+// `scaleDecorators.test.ts` already proves round-trips are SAVED — it counts them. What a
+// count cannot say is what that is worth, because the answer depends entirely on what one
+// round-trip costs: over a free in-memory store, coalescing is pure overhead, and over a
+// network backend it is the difference between 18k and 78k events/sec (`docs/benchmarks.md`,
+// measured against real Postgres).
+//
+// So this bench prices a round-trip EXPLICITLY, spinning rather than sleeping — a timer
+// would put scheduler granularity into a measurement whose whole point is the number of
+// calls. `ROUND_TRIP_US` is the one assumption; every result below is a function of it, and
+// a reader who thinks their backend is cheaper or dearer can move it and re-run.
+//
+// The second half is the honest counterweight: what the decorators cost when there is
+// nothing to save. A decorator that is free on a free backend is a decorator that can be
+// left in place.
+
+const ROUND_TRIP_US = 20;
+
+const evt = (executionId: string, sequence: number): EventEnvelope => ({
+  id: `${executionId}-${sequence}`,
+  workflowId: "wf",
+  executionId,
+  eventType: "STEP_COMPLETED",
+  sequence,
+  timestamp: 1000 + sequence,
+  payload: { sequence },
+});
+
+/** Burn `us` microseconds of CPU. Deterministic; no timer, no scheduler. */
+function spin(us: number): void {
+  const until = performance.now() + us / 1000;
+  while (performance.now() < until) {
+    /* deliberately empty */
+  }
+}
+
+/**
+ * A backend that charges `ROUND_TRIP_US` per CALL, not per envelope — which is what a
+ * network backend does, and the entire reason batching exists. It keeps nothing: the
+ * measurement is the round-trips, not the storage.
+ */
+function pricedStore(): EventStore {
+  return {
+    append: async () => {
+      spin(ROUND_TRIP_US);
+    },
+    appendBatch: async () => {
+      spin(ROUND_TRIP_US);
+    },
+    read: async () => [],
+    readFrom: async () => [],
+    subscribe: async () => () => {},
+    close: async () => {},
+  };
+}
+
+/** One envelope from each of N distinct executions, appended concurrently — the real shape:
+ *  N journals, each holding a single pending envelope, all flushing into one turn. */
+const N = 512;
+const wave = Array.from({ length: N }, (_, i) => evt(`x${i}`, 0));
+
+async function appendAll(store: EventStore): Promise<void> {
+  await Promise.all(wave.map((e) => store.append(e)));
+}
+
+describe(`${N} cross-execution appends, one round-trip priced at ${ROUND_TRIP_US}µs`, () => {
+  bench("per-event append (no decorator)", async () => {
+    await appendAll(pricedStore());
+  });
+
+  bench("CoalescingEventStore (default maxBatch: 16)", async () => {
+    await appendAll(new CoalescingEventStore(pricedStore(), { maxBatch: 16 }));
+  });
+
+  bench("CoalescingEventStore (maxBatch: 64)", async () => {
+    await appendAll(new CoalescingEventStore(pricedStore(), { maxBatch: 64 }));
+  });
+});
+
+describe(`${N} cross-execution appends against a FREE backend (what the decorators cost)`, () => {
+  // The counterweight. Over an in-memory store there are no round-trips worth saving, so
+  // these numbers are the price of leaving a decorator wired where it buys nothing.
+  bench("InMemoryAsyncEventStore (no decorator)", async () => {
+    await appendAll(new InMemoryAsyncEventStore());
+  });
+
+  bench("CoalescingEventStore over in-memory", async () => {
+    await appendAll(new CoalescingEventStore(new InMemoryAsyncEventStore(), { maxBatch: 16 }));
+  });
+
+  bench("ShardedEventStore over 4 in-memory shards", async () => {
+    // Routing only — hash the id, pick a shard, delegate. What sharding actually buys is
+    // parallelism across backends, which a single-process bench cannot show and this
+    // deliberately does not claim.
+    await appendAll(
+      new ShardedEventStore(Array.from({ length: 4 }, () => new InMemoryAsyncEventStore()))
+    );
+  });
+});

package/src/sequenceRange.bench.ts

@@ -0,0 +1,51 @@
+import type { EventEnvelope } from "@loomwork/core";
+import { bench, describe } from "vitest";
+import { InMemoryAsyncEventStore } from "./InMemoryAsyncEventStore";
+import { sliceBySequence } from "./sequenceRange";
+
+// The fork/materialize hot path: extract a bounded [from..to] window from a long,
+// sequence-sorted log. The baselines are the previous O(n) shapes (a `.filter`, and
+// read()+sort()+filter) so the binary-search win is visible on a large history.
+
+function ev(sequence: number): EventEnvelope {
+  return {
+    id: `e-${sequence}`,
+    workflowId: "wf",
+    executionId: "x",
+    eventType: "STEP_STARTED",
+    sequence,
+    timestamp: sequence,
+    payload: {},
+  };
+}
+
+const N = 100_000;
+const events = Array.from({ length: N }, (_, i) => ev(i));
+// Fork early in the history — the pathological case for a full scan.
+const FROM = 100;
+const TO = 200;
+
+describe("bounded range over a 100k-event log", () => {
+  bench("filter baseline (previous shape)", () => {
+    events.filter((e) => e.sequence >= FROM && e.sequence <= TO);
+  });
+
+  bench("sliceBySequence (binary search)", () => {
+    sliceBySequence(events, FROM, TO);
+  });
+});
+
+describe("InMemoryAsyncEventStore range read (100k events)", () => {
+  const store = new InMemoryAsyncEventStore();
+  // Prime the store once outside the measured loop.
+  for (let i = 0; i < N; i++) void store.append(ev(i));
+
+  bench("read()+sort()+filter baseline (previous shape)", async () => {
+    const all = [...(await store.read("x"))].sort((a, b) => a.sequence - b.sequence);
+    all.filter((e) => e.sequence >= FROM && e.sequence <= TO);
+  });
+
+  bench("readRange (binary search, no sort)", async () => {
+    await store.readRange("x", FROM, TO);
+  });
+});

package/src/sequenceRange.ts

@@ -0,0 +1,35 @@
+import type { EventEnvelope } from "@loomwork/core";
+
+// Binary-search helpers over an event array that is sorted ascending by
+// `sequence` — the invariant every EventStore preserves (the per-execution
+// sequencer assigns strictly increasing sequences, and `copyPrefix` copies in
+// order). They turn range reads on an in-memory log from O(n) filters into
+// O(log n + k) slices, and back the workflow-runtime fork/materialize path.
+
+/** First index whose event.sequence >= `seq` (i.e. events.length if none). */
+export function lowerBoundBySequence(events: readonly EventEnvelope[], seq: number): number {
+  let lo = 0;
+  let hi = events.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if ((events[mid] as EventEnvelope).sequence < seq) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+/**
+ * Events with `fromSequence <= sequence <= toSequence`, assuming `events` is
+ * sorted ascending by sequence. O(log n) to locate the bounds + O(k) to copy the
+ * k in-range events — no full scan.
+ */
+export function sliceBySequence(
+  events: readonly EventEnvelope[],
+  fromSequence: number,
+  toSequence: number
+): EventEnvelope[] {
+  if (toSequence < fromSequence) return [];
+  const start = lowerBoundBySequence(events, fromSequence);
+  const end = lowerBoundBySequence(events, toSequence + 1);
+  return events.slice(start, end);
+}