@loomwork/event-runtime 0.0.0-stage → 0.1.1

package/src/archiveSpi.ts

@@ -0,0 +1,308 @@
+import type { EventEnvelope } from "@loomwork/core";
+
+// ── ADR 0138 — the compaction archive SPI ────────────────────────────────────────────────────────
+//
+// `LogLifecycle.compact` removes the prefix of a log below its checkpoint. Under ADR 0138 it MOVES
+// that prefix: the removed envelopes are appended here first, then truncated. Nothing in loom
+// deletes a fact the log held, so an auditor can recover `archive ∪ surviving log == original log`.
+//
+// The archive is deliberately NOT an EventStore and NOT the content store: `readRange` of the log
+// never sees it (replay and resume cannot read it), no sweep enumerates it, and per-subject erasure
+// is a property of ONE store (a sealing wrapper over the same KeyStore as the event store).
+
+/**
+ * SPI version of {@link ArchiveStore} (ADR 0138). Pinned by `runArchiveStoreConformance`.
+ *
+ * 1.0.0: `append` / `headers` / `read` / `listExecutions` (paged) / optional `deleteExecution` /
+ * `close`; every segment header carries the log `incarnation` it belongs to and an optional `kind`.
+ *
+ * 1.1.0 (ADR 0139 N1/N7, additive): the optional `replaceSegments(key, expected, next)`, an ATOMIC
+ * compare-and-swap of a key's whole segment list (a concurrent `append` makes it fail with
+ * {@link ArchiveConflictError}; nothing is written), and the optional header field `senderDigest`
+ * (a digest of the senders of a PLAINTEXT reserved-stream segment, which the digest itself masks). A
+ * 1.0.0 store conforms; the erasure that needs `replaceSegments` refuses an archive without it.
+ */
+export const ARCHIVE_STORE_SPI_VERSION = "1.1.0";
+
+/**
+ * What a segment holds. Absent / `"events"`: the exact envelopes a compaction removed. `"legacy-checkpoint"`:
+ * ONE synthetic envelope carrying a checkpoint (snapshot) written before the archive existed, byte-exact:
+ * its folded state is the only copy of the settled steps' inputs the pre-0138 compactions removed.
+ */
+export type ArchiveSegmentKind = "events" | "legacy-checkpoint";
+
+/** The `eventType` of the synthetic envelope inside a `"legacy-checkpoint"` segment. */
+export const ARCHIVE_LEGACY_CHECKPOINT_EVENT = "ARCHIVE_LEGACY_CHECKPOINT";
+
+/** What a segment says about itself without its envelopes. */
+export interface ArchiveSegmentHeader {
+  /** The lowest sequence this segment covers (inclusive). */
+  readonly from: number;
+  /** The highest sequence it covers (inclusive): the compaction checkpoint's sequence. */
+  readonly through: number;
+  /** How many envelopes it holds (sequences inside `[from, through]` a compaction kept are absent). */
+  readonly count: number;
+  /** {@link segmentDigest} of the envelopes, in order. Stored and returned verbatim. */
+  readonly digest: string;
+  /**
+   * The incarnation of the log this segment came from: the {@link segmentDigest} of its bootstrap
+   * event (sequence 0, which survives every compaction; the id alone is `<executionId>-0` and says
+   * nothing). A segment of another incarnation under the same execution id (an id REUSED after a
+   * delete) is refused with {@link ArchiveIncarnationError}, never inherited. Two runs whose
+   * bootstrap envelopes are byte-identical (same input, same millisecond) are not told apart here;
+   * their later events then disagree, which the compaction and the audit read catch byte-for-byte.
+   */
+  readonly incarnation: string;
+  /** Absent means `"events"`. Stored and returned verbatim. */
+  readonly kind?: ArchiveSegmentKind;
+  /**
+   * SPI 1.1.0 (ADR 0139 N7), PLAINTEXT reserved-stream segments only: the sender digest of the
+   * envelopes' senders. The segment `digest` masks `payload.sender` (an erasure may redact it), so
+   * without this the sender field would have no bit-rot detection; a redaction recomputes it in the same
+   * atomic {@link ArchiveStore.replaceSegments}. Stored and returned verbatim; absent on every other segment
+   * (a sealing archive authenticates the sender with AEAD instead and never stores it).
+   */
+  readonly senderDigest?: string;
+}
+
+/** One contiguous range of removed envelopes. */
+export interface ArchiveSegment extends ArchiveSegmentHeader {
+  /** The exact envelopes the log held, ascending by sequence. */
+  readonly envelopes: readonly EventEnvelope[];
+  /**
+   * Opaque sealed form. A sealing decorator (`EncryptingArchiveStore`) stores its ciphertext here
+   * and an EMPTY `envelopes`; a plain backend persists it verbatim and never looks inside.
+   */
+  readonly sealed?: unknown;
+}
+
+/**
+ * Where compaction puts the events it removes (ADR 0138). Append-only: there is no per-segment
+ * delete, only {@link ArchiveStore.deleteExecution} for the existing whole-execution retention path.
+ *
+ * Contract (pinned by the conformance kit):
+ *  - `append` is IDEMPOTENT for an identical segment (same `from`, `through`, `digest`): a crash
+ *    between "archive" and "truncate" is retried by re-compaction, and the retry must not fail.
+ *  - Any other segment must start strictly after the last one's `through`; an overlap or a rewind
+ *    rejects with {@link ArchiveConflictError} and writes NOTHING.
+ *  - `headers` and `read` return segments in ascending `from`. `read` returns every segment that
+ *    overlaps the range, WHOLE (the caller trims), exactly what was appended.
+ *  - An unknown execution reads as `[]`.
+ */
+export interface ArchiveStore {
+  append(executionId: string, segment: ArchiveSegment): Promise<void>;
+  /** The segment headers, ascending. Cheap: no envelopes are read. */
+  headers(executionId: string): Promise<ArchiveSegmentHeader[]>;
+  /**
+   * One page of the execution ids that hold at least one segment, ascending in code point order,
+   * keyset-paged like `EventStore.listExecutionsPage`: pass the previous page's `nextCursor`
+   * (exclusive); no `nextCursor` means the end. Lets a sweep enumerate what the archive cites.
+   */
+  listExecutions(opts?: { cursor?: string; limit?: number }): Promise<ArchiveExecutionPage>;
+  read(
+    executionId: string,
+    range?: { readonly from?: number; readonly through?: number }
+  ): Promise<ArchiveSegment[]>;
+  /** OPTIONAL. The whole-execution delete of the retention path (`LogLifecycle.applyRetention`). */
+  deleteExecution?(executionId: string): Promise<void>;
+  /**
+   * OPTIONAL (SPI 1.1.0, ADR 0139 N1). Atomically replace ALL of `executionId`'s segments with `next`, IF
+   * its current headers are exactly `expected` (ascending, as {@link ArchiveStore.headers} returned
+   * them, `senderDigest` included): one compare-and-swap, so a concurrent writer (a trim on another node
+   * appending a segment after the caller read) makes it reject with {@link ArchiveConflictError} and
+   * write NOTHING, and the caller re-reads and retries. Used by erasure to redact a sender in place; the
+   * `next` segments must be ascending and non-overlapping, and of the incarnation `expected` holds.
+   */
+  replaceSegments?(
+    executionId: string,
+    expected: readonly ArchiveSegmentHeader[],
+    next: readonly ArchiveSegment[]
+  ): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** One page of {@link ArchiveStore.listExecutions}. */
+export interface ArchiveExecutionPage {
+  readonly executionIds: string[];
+  readonly nextCursor?: string;
+}
+
+/** The names of the OPTIONAL {@link ArchiveStore} methods, for the decorator plan. */
+export const OPTIONAL_ARCHIVE_STORE_METHODS = ["deleteExecution", "replaceSegments"] as const;
+
+/** A segment that overlaps or rewinds past what the archive already holds (nothing was written). */
+export class ArchiveConflictError extends Error {
+  readonly retryable = false;
+  constructor(
+    readonly executionId: string,
+    readonly attempted: ArchiveSegmentHeader,
+    readonly lastThrough: number,
+    /** Set by {@link ArchiveStore.replaceSegments}: why the compare-and-swap failed. */
+    readonly replaceReason?: string
+  ) {
+    super(
+      replaceReason !== undefined
+        ? `archive "${executionId}": replaceSegments refused - ${replaceReason}. Nothing was written; re-read the headers and retry.`
+        : `archive "${executionId}": segment [${attempted.from}..${attempted.through}] does not start after the archive's last sequence ${lastThrough}, and is not an exact repeat of an archived segment. Segments are append-only and contiguous; nothing was written.`
+    );
+    this.name = "ArchiveConflictError";
+    Object.setPrototypeOf(this, ArchiveConflictError.prototype);
+  }
+}
+
+/**
+ * The archive holds segments of another incarnation of this execution id (the id was deleted and
+ * REUSED): appending to or reading them as this run's history would mix two runs. Nothing was
+ * written. Never retryable.
+ */
+export class ArchiveIncarnationError extends Error {
+  readonly retryable = false;
+  constructor(
+    readonly executionId: string,
+    readonly archived: string,
+    readonly current: string
+  ) {
+    super(
+      `archive "${executionId}": the archive holds segments of a DIFFERENT run (incarnation ${archived}) than the log's (${current}) — the execution id was reused after its earlier run was deleted. The old run's archive was not removed with it, so it is not this run's history and is neither read as such nor extended. Remove the previous run's segments with the retention path (ArchiveStore.deleteExecution), or use a fresh execution id.`
+    );
+    this.name = "ArchiveIncarnationError";
+    Object.setPrototypeOf(this, ArchiveIncarnationError.prototype);
+  }
+}
+
+/** A segment's envelopes cannot be serialized to JSON (circular, BigInt, too deep): it cannot be archived or verified. */
+export class ArchiveUnserializableError extends Error {
+  readonly retryable = false;
+  constructor(cause: unknown) {
+    super(
+      `archive: the envelopes cannot be serialized to JSON (${cause instanceof Error ? cause.message : String(cause)}) — an archived event must be plain JSON data, byte-exact.`,
+      { cause }
+    );
+    this.name = "ArchiveUnserializableError";
+    Object.setPrototypeOf(this, ArchiveUnserializableError.prototype);
+  }
+}
+
+/** The envelopes of a segment do not hash to the digest it recorded: the archive was altered. */
+export class ArchiveDigestError extends Error {
+  readonly retryable = false;
+  constructor(
+    readonly executionId: string,
+    readonly from: number,
+    readonly through: number,
+    readonly expected: string,
+    readonly actual: string
+  ) {
+    super(
+      `archive "${executionId}": segment [${from}..${through}] does not match its recorded digest (expected ${expected}, computed ${actual}) — the archived events were altered or corrupted.`
+    );
+    this.name = "ArchiveDigestError";
+    Object.setPrototypeOf(this, ArchiveDigestError.prototype);
+  }
+}
+
+export const headerOf = (s: ArchiveSegmentHeader): ArchiveSegmentHeader => ({
+  from: s.from,
+  through: s.through,
+  count: s.count,
+  digest: s.digest,
+  incarnation: s.incarnation,
+  ...(s.kind !== undefined && { kind: s.kind }),
+  ...(s.senderDigest !== undefined && { senderDigest: s.senderDigest }),
+});
+
+const sameHeader = (a: ArchiveSegmentHeader, b: ArchiveSegmentHeader): boolean =>
+  a.from === b.from &&
+  a.through === b.through &&
+  a.count === b.count &&
+  a.digest === b.digest &&
+  a.incarnation === b.incarnation &&
+  (a.kind ?? "events") === (b.kind ?? "events") &&
+  (a.senderDigest ?? null) === (b.senderDigest ?? null);
+
+/**
+ * The shared `replaceSegments` rule for a backend, given the headers stored now: throws
+ * {@link ArchiveConflictError} unless they are exactly `expected`, and a `RangeError` for a `next` list
+ * that is not ascending, non-overlapping and well-formed. Nothing is written by this check.
+ */
+export function assertReplaceable(
+  executionId: string,
+  stored: readonly ArchiveSegmentHeader[],
+  expected: readonly ArchiveSegmentHeader[],
+  next: readonly ArchiveSegmentHeader[]
+): void {
+  const attempted =
+    next[0] ?? expected[0] ?? stored[0] ?? ({ from: 0, through: 0 } as ArchiveSegmentHeader);
+  const last = stored[stored.length - 1]?.through ?? -1;
+  if (stored.length !== expected.length) {
+    throw new ArchiveConflictError(
+      executionId,
+      attempted,
+      last,
+      `the key now holds ${stored.length} segment(s), the caller read ${expected.length}`
+    );
+  }
+  for (let i = 0; i < stored.length; i++) {
+    if (!sameHeader(stored[i]!, expected[i]!)) {
+      throw new ArchiveConflictError(
+        executionId,
+        attempted,
+        last,
+        `segment ${i} [${stored[i]!.from}..${stored[i]!.through}] changed since the caller read it`
+      );
+    }
+  }
+  let prev = Number.NEGATIVE_INFINITY;
+  for (const h of next) {
+    if (!Number.isSafeInteger(h.from) || !Number.isSafeInteger(h.through) || h.from > h.through) {
+      throw new RangeError(`archive segment [${h.from}..${h.through}] is malformed`);
+    }
+    if (h.from <= prev) {
+      throw new RangeError(
+        `replaceSegments: segments must be ascending and non-overlapping ([${h.from}..${h.through}] follows ${prev})`
+      );
+    }
+    prev = h.through;
+  }
+  const incarnation = expected[0]?.incarnation;
+  if (incarnation !== undefined) {
+    for (const h of next) {
+      if (h.incarnation !== incarnation) {
+        throw new ArchiveIncarnationError(executionId, incarnation, h.incarnation);
+      }
+    }
+  }
+}
+
+/**
+ * The shared `append` rule for a backend, given the headers already stored (ascending): `"noop"`
+ * for an exact repeat of a stored segment, `"append"` when the segment starts after the last one,
+ * else throws {@link ArchiveConflictError}.
+ */
+export function classifyAppend(
+  executionId: string,
+  stored: readonly ArchiveSegmentHeader[],
+  segment: ArchiveSegmentHeader
+): "append" | "noop" {
+  if (!Number.isSafeInteger(segment.from) || !Number.isSafeInteger(segment.through)) {
+    throw new RangeError("archive segment bounds must be safe integers");
+  }
+  if (segment.from > segment.through) {
+    throw new RangeError(`archive segment [${segment.from}..${segment.through}] is inverted`);
+  }
+  for (const h of stored) {
+    if (h.incarnation !== segment.incarnation) {
+      throw new ArchiveIncarnationError(executionId, h.incarnation, segment.incarnation);
+    }
+  }
+  for (const h of stored) {
+    if (h.from === segment.from && h.through === segment.through && h.digest === segment.digest) {
+      return "noop";
+    }
+  }
+  const last = stored[stored.length - 1];
+  if (last !== undefined && segment.from <= last.through) {
+    throw new ArchiveConflictError(executionId, segment, last.through);
+  }
+  return "append";
+}

package/src/creationMarker.ts

@@ -0,0 +1,15 @@
+import type { EventEnvelope } from "@loomwork/core";
+
+/**
+ * SPI 2.2.0 — the LEGACY (pre-ADR 0129) opaque creation marker `appendIfUnchanged` compares (see `TipObservation`):
+ * derived from an execution's sequence-0 envelope, so a log deleted and re-created under the same
+ * id reads as a different execution. Envelope ids are deterministic, hence the timestamp too.
+ * Every reference store derives it with this one function so they agree byte for byte.
+ *
+ * SPI 2.3.0 (ADR 0129): this is no longer the anchor of a log whose store assigned an
+ * incarnation (it cannot tell two byte-identical re-creations apart). It remains the anchor of a
+ * log created before the store gained that metadata, and of a store that cannot assign one.
+ */
+export function creationMarker(first: Pick<EventEnvelope, "id" | "timestamp">): string {
+  return `${first.timestamp}:${first.id}`;
+}

package/src/decoratorPlan.typecheck.ts

@@ -0,0 +1,52 @@
+import type { DecoratorPlan } from "./installOptional";
+import type { EventStore, OptionalEventStoreMethod } from "./types";
+
+// ── Compile-time proof that a DecoratorPlan cannot silently drop a method ────────
+//
+// This is a SOURCE file on purpose: `pnpm typecheck` (tsc --build) excludes `*.test.ts`, so a
+// type-level negative in a test file would never be checked. If `DecoratorPlan` ever lets a
+// plan omit an optional method again (a homomorphic mapped type over `EventStore` inherits the
+// methods' `?` and makes every key optional), the `@ts-expect-error` below becomes unused and
+// the build fails. Nothing here runs; it exports nothing.
+
+type Plan = DecoratorPlan<EventStore, OptionalEventStoreMethod>;
+
+const complete = {
+  appendBatch: "forward",
+  readRange: "forward",
+  head: "forward",
+  acquireFence: "forward",
+  acquireFenceIf: "forward",
+  appendIfUnchanged: "forward",
+  storeNow: "forward",
+  sealingCapability: "forward",
+  readAtRest: "forward",
+  copyPrefix: "forward",
+  deleteExecution: "forward",
+  deleteThrough: "forward",
+  truncatePrefix: "forward",
+  truncatePrefixKeeping: "forward",
+  listExecutions: "forward",
+  listExecutionsPage: { refuse: "a refusal is a decision, and still a key" },
+} satisfies Plan;
+void complete;
+
+// @ts-expect-error — listExecutionsPage is missing: a plan must decide every optional method.
+const missingOne: Plan = {
+  appendBatch: "forward",
+  readRange: "forward",
+  head: "forward",
+  acquireFence: "forward",
+  acquireFenceIf: "forward",
+  appendIfUnchanged: "forward",
+  storeNow: "forward",
+  sealingCapability: "forward",
+  readAtRest: "forward",
+  copyPrefix: "forward",
+  deleteExecution: "forward",
+  deleteThrough: "forward",
+  truncatePrefix: "forward",
+  truncatePrefixKeeping: "forward",
+  listExecutions: "forward",
+};
+void missingOne;

package/src/eventKindClass.ts

@@ -0,0 +1,127 @@
+import { type EventEnvelope, type EventKind, KERNEL_EVENT_KINDS } from "@loomwork/core";
+
+// ADR 0118 D1 — which kernel event kinds ANSWER a park.
+//
+// `acquireFenceIf(id, { fence, parkSeq })` (landing with R8k) refuses when an ANSWERING event
+// exists past the park it is answering: another resumer's `EXECUTION_RESUMED`, a later park, or a
+// terminal fact. Every other event is an audit append or an application event that follows a park without answering it
+// (an unfenced `EXECUTION_DENIED`, a late `OUTCOME_RECORDED`, a `STEP_FAILED` while parked, a
+// `MESSAGE_CONSUMED` written by the running owner, ...) and must NOT make the acquire stale, or a
+// legitimate resume would be refused for an audit row.
+//
+// The map is a REQUIRED `Record<EventKind, ...>` with no default: adding a kind to
+// `KERNEL_EVENT_KINDS` without deciding is a compile error here. The fitness test in
+// `@loomwork/workflow-runtime` pins its keys equal to the fold's handler table.
+
+/** Whether an event of this kind, appended after a park, answers it. */
+export type EventKindClass = "answering" | "ignorable";
+
+export const EVENT_KIND_CLASS: Readonly<Record<EventKind, EventKindClass>> = {
+  // ── answering: they move the execution out of the park (or supersede it) ──
+  EXECUTION_RESUMED: "answering", // any payload, incl. the `null` status-only re-open (ADR 0104)
+  EXECUTION_SUSPENDED: "answering", // a later park supersedes this one
+  EXECUTION_COMPLETED: "answering",
+  EXECUTION_FAILED: "answering",
+  EXECUTION_CANCELLED: "answering",
+  EXECUTION_CONTINUED: "answering", // ADR 0109: terminal, names the successor
+
+  // ── ignorable: audit / bookkeeping that never answers a park by itself ──
+  EXECUTION_STARTED: "ignorable", // sequence 0; precedes every park
+  EXECUTION_DENIED: "ignorable", // unfenced, appended after a park (`recordExecutionDenied`)
+  OUTCOME_RECORDED: "ignorable", // ADR 0116: terminal-only late attach, or a live emit
+  MESSAGE_CONSUMED: "ignorable", // ADR 0110: written by the running owner; the RESUMED answers
+  // ADR 0130 residuals D9 (EVENT_SCHEMA 1.25.0; written by quarantineInbox / releaseInbox / auto-release): both land under the park's
+  // conditional fence and leave the park unanswered, exactly like MESSAGE_CONSUMED.
+  INBOX_QUARANTINED: "ignorable", // the topic's head is held; the park is not answered
+  INBOX_RELEASED: "ignorable", // a held entry is released or dropped; the delivery's own facts answer
+  EXECUTION_MIGRATED: "ignorable",
+  STEP_STARTED: "ignorable",
+  STEP_COMPLETED: "ignorable",
+  STEP_FAILED: "ignorable", // ADR 0105: a sibling failing while parked
+  STEP_CANCELLED: "ignorable",
+  STEP_RETRYING: "ignorable",
+  PARALLEL_STARTED: "ignorable",
+  PARALLEL_COMPLETED: "ignorable", // ADR 0112: the scope outcome, written before a rethrow
+  DECISION_RECORDED: "ignorable",
+  EFFECT_DENIED: "ignorable",
+  EFFECT_INDOUBT: "ignorable",
+  EGRESS_DENIED: "ignorable",
+  SAFETY_BLOCKED: "ignorable",
+  QUOTA_EXCEEDED: "ignorable",
+  RESOURCE_METERED: "ignorable",
+  APPROVAL_GRANTED: "ignorable",
+  TIMER_FIRED: "ignorable",
+  PAYLOAD_SHREDDED: "ignorable",
+  ERASURE_PENDING: "ignorable",
+  EXECUTION_ARCHIVED: "ignorable",
+  EXECUTION_DELETED: "ignorable",
+  EVENTS_REHOMED: "ignorable",
+};
+
+/** The two envelope fields the classification reads. */
+export interface ClassifiableEvent {
+  readonly eventType: string;
+  readonly metadata?: Readonly<Record<string, unknown>> | undefined;
+}
+
+const KERNEL_KIND_SET: ReadonlySet<string> = new Set(KERNEL_EVENT_KINDS);
+
+/**
+ * Whether an appended event answers a park (what `acquireFenceIf` counts past `parkSeq`).
+ *
+ * - A kind in {@link KERNEL_EVENT_KINDS} is classified by its {@link EVENT_KIND_CLASS} entry.
+ * - A kind NOT in it is an APPLICATION event (`ctx.emit`, a `ctx.stream` delta, a parallel
+ *   sibling's output) and is IGNORABLE: counting it would let a sibling that keeps emitting after
+ *   the park make every `acquireFenceIf` stale, so the execution could never be resumed.
+ * - EXCEPT an unknown kind that carries `metadata.kernel === true`: a kernel kind written by a
+ *   NEWER node in a mixed fleet. This node cannot classify it, so it is ANSWERING (fail-closed:
+ *   the cost of a wrong "answering" is a `contended` retry, of a wrong "ignorable" a fenced-out
+ *   live body). This is why every kernel kind added after 1.23.0 MUST be stamped
+ *   `metadata.kernel: true` by its writer — an unstamped new kernel kind is indistinguishable
+ *   from an app event and would classify as ignorable on an older node.
+ *
+ * Own-property membership (a `Set`), so `"__proto__"` / `"constructor"` are unknown kinds, not
+ * `Object.prototype` members; the stamp must be literally `true`.
+ */
+export function isAnsweringKind(event: ClassifiableEvent): boolean {
+  if (KERNEL_KIND_SET.has(event.eventType)) {
+    return EVENT_KIND_CLASS[event.eventType as EventKind] === "answering";
+  }
+  return event.metadata?.kernel === true;
+}
+
+const QUIESCENT_TERMINAL_EVENTS = new Set([
+  "EXECUTION_COMPLETED",
+  "EXECUTION_FAILED",
+  "EXECUTION_CANCELLED",
+  "EXECUTION_CONTINUED",
+]);
+const QUIESCENT_TERMINAL_STATUS = new Set(["completed", "failed", "cancelled", "continued"]);
+
+/**
+ * Does the log show NO runner? The ONE rule `shredSubject` (before it takes a fence) and the
+ * erasure coordinator (in the destroy window, for a compacted log with a sealed checkpoint) share.
+ * Judged from data that sealing never hides: the LAST answering event of `tail`
+ * (`isAnsweringKind`, ignoring audit rows and the shredder's own events). A terminal kind or a park
+ * is quiescent; a resume (a terminal followed by a re-open included) or a start with no park is
+ * live. With no answering event in `tail`, the checkpoint's `snapshotStatus` decides when it is
+ * readable; if it is not (a retry after the key was destroyed), the erase intent already in the
+ * log is the proof, because it was only written to a quiescent log. Quiescent is NOT "terminal
+ * chain head": a parked (`suspended`) owner is quiescent.
+ */
+export function isQuiescent(
+  tail: readonly EventEnvelope[],
+  snapshotStatus: string | undefined,
+  hasIntent: boolean
+): boolean {
+  const last = [...tail].reverse().find((e) => isAnsweringKind(e));
+  if (last !== undefined) {
+    return (
+      QUIESCENT_TERMINAL_EVENTS.has(last.eventType) || last.eventType === "EXECUTION_SUSPENDED"
+    );
+  }
+  if (snapshotStatus !== undefined) {
+    return QUIESCENT_TERMINAL_STATUS.has(snapshotStatus) || snapshotStatus === "suspended";
+  }
+  return hasIntent;
+}

package/src/executionIdOrder.ts

@@ -0,0 +1,38 @@
+/**
+ * The ONE order of executionIds that `listExecutionsPage` promises (EventStore SPI 2.0.0, ADR 0108):
+ * Unicode code point order — the same as UTF-8 byte order, SQL `COLLATE "C"` and SQLite's
+ * BINARY collation, so a SQL backend can serve it from a plain b-tree.
+ *
+ * Not JavaScript's default string order: `<` and `Array.prototype.sort()` compare UTF-16
+ * code UNITS, which agree with code points everywhere except that an astral character (a
+ * surrogate pair, 0xD800–0xDFFF) sorts BELOW U+E000–U+FFFF by code unit and ABOVE them by
+ * code point. `ShardedEventStore` merges shard pages with this comparator and resumes every
+ * shard from the merged page's last id, so it and every store must agree exactly — a store
+ * paging in any other order (a Postgres database collation, say) silently skips ids.
+ *
+ * The parity with UTF-8 byte order holds for WELL-FORMED ids only. A lone surrogate has no
+ * UTF-8 encoding: node-postgres sends it as U+FFFD, so a Postgres store neither keeps nor
+ * orders such an id the way this function does. Execution ids should be well-formed Unicode
+ * (every id generator loom ships produces ASCII).
+ *
+ * O(length of the common prefix), no allocation.
+ */
+export function compareExecutionIds(a: string, b: string): number {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    const x = a.charCodeAt(i);
+    const y = b.charCodeAt(i);
+    if (x === y) continue;
+    // Below 0xD800 code-unit order is code-point order. When both units are at or above it,
+    // lift the surrogates above U+E000–U+FFFF (and lower those to make room), which is
+    // exactly where their code points sit. (A lone surrogate gets a consistent position here,
+    // but no store is obliged to agree: it cannot round-trip through UTF-8.)
+    if (x >= 0xd800 && y >= 0xd800) return surrogateLast(x) - surrogateLast(y);
+    return x - y;
+  }
+  return a.length - b.length;
+}
+
+function surrogateLast(unit: number): number {
+  return unit >= 0xe000 ? unit - 0x800 : unit + 0x2000;
+}

package/src/fencing.ts

@@ -0,0 +1,31 @@
+import type { EventEnvelope } from "@loomwork/core";
+
+/**
+ * K9.4 — a fenced store rejected an append carrying a stale (or missing)
+ * fencing token: the execution was re-dispatched under a newer token, so the
+ * writer is a "zombie" — a network-partitioned or presumed-dead worker whose
+ * writes must not land after its execution moved elsewhere. Extends the D3
+ * single-writer invariant to the failure domain.
+ */
+export class StaleFenceError extends Error {
+  constructor(
+    readonly executionId: string,
+    readonly staleFence: number | undefined,
+    readonly currentFence: number,
+    /** The error this was re-raised from, when a decorator rewrote it (e.g. tenant unscoping). */
+    readonly cause?: unknown
+  ) {
+    super(
+      `stale fence for execution "${executionId}": append carried ` +
+        `${staleFence === undefined ? "no token" : `token ${staleFence}`}, current fence is ${currentFence}`
+    );
+    this.name = "StaleFenceError";
+    Object.setPrototypeOf(this, StaleFenceError.prototype);
+  }
+}
+
+/** The fencing token an envelope carries (in `metadata.fence`), if any. */
+export function fenceOf(envelope: EventEnvelope): number | undefined {
+  const fence = envelope.metadata?.fence;
+  return typeof fence === "number" ? fence : undefined;
+}