@loomwork/event-runtime 0.0.0-stage → 0.1.1

package/src/TenantScopedArchiveStore.ts

@@ -0,0 +1,114 @@
+import type {
+  ArchiveExecutionPage,
+  ArchiveSegment,
+  ArchiveSegmentHeader,
+  ArchiveStore,
+} from "./archiveSpi";
+import { compareExecutionIds } from "./executionIdOrder";
+
+const SEP = ":"; // the same tenant separator as TenantScopedEventStore / TenantScopedSnapshotStore
+
+/**
+ * ADR 0138 H3 - the archive half of tenant scoping (see `TenantScopedEventStore`). Key-prefixes the
+ * executionId so a `LogLifecycle` over a tenant-scoped event store, given a shared archive, can only
+ * address its own tenant's segments: another tenant's history cannot be read, extended, or (on the
+ * plain-delete retention path) deleted, by construction. `LogLifecycle.compact` REFUSES a tenant-scoped
+ * event store paired with an archive that is not scoped to the SAME tenant (`tenantScope` is the marker).
+ *
+ * The sealing markers of a wrapped `EncryptingArchiveStore` (`keys`, `sealsSegments`, `subjectOf`)
+ * are forwarded, so the erasure-boundary guard sees through this decorator.
+ */
+export class TenantScopedArchiveStore implements ArchiveStore {
+  readonly deleteExecution?: NonNullable<ArchiveStore["deleteExecution"]>;
+  readonly replaceSegments?: NonNullable<ArchiveStore["replaceSegments"]>;
+
+  constructor(
+    private readonly inner: ArchiveStore,
+    private readonly tenant: string
+  ) {
+    if (tenant === "" || tenant.includes(SEP)) {
+      throw new TypeError(
+        `TenantScopedArchiveStore: tenant must be non-empty and must not contain the separator "${SEP}" (got ${JSON.stringify(tenant)})`
+      );
+    }
+    const innerDelete = inner.deleteExecution;
+    if (innerDelete !== undefined) {
+      this.deleteExecution = (id) => innerDelete.call(inner, this.scope(id));
+    }
+    const innerReplace = inner.replaceSegments;
+    if (innerReplace !== undefined) {
+      this.replaceSegments = (id, expected, next) =>
+        innerReplace.call(inner, this.scope(id), expected, next);
+    }
+  }
+
+  /** Structural marker: the tenant this archive is scoped to (read by `LogLifecycle.compact`). */
+  get tenantScope(): string {
+    return this.tenant;
+  }
+  get keys(): unknown {
+    return (this.inner as { keys?: unknown }).keys;
+  }
+  get sealsSegments(): unknown {
+    return (this.inner as { sealsSegments?: unknown }).sealsSegments;
+  }
+  get subjectOf(): unknown {
+    return (this.inner as { subjectOf?: unknown }).subjectOf;
+  }
+
+  private scope(id: string): string {
+    return `${this.tenant}${SEP}${id}`;
+  }
+
+  append(executionId: string, segment: ArchiveSegment): Promise<void> {
+    return this.inner.append(this.scope(executionId), segment);
+  }
+
+  headers(executionId: string): Promise<ArchiveSegmentHeader[]> {
+    return this.inner.headers(this.scope(executionId));
+  }
+
+  read(
+    executionId: string,
+    range?: { readonly from?: number; readonly through?: number }
+  ): Promise<ArchiveSegment[]> {
+    return this.inner.read(this.scope(executionId), range);
+  }
+
+  async listExecutions(
+    opts: { cursor?: string; limit?: number } = {}
+  ): Promise<ArchiveExecutionPage> {
+    const prefix = `${this.tenant}${SEP}`;
+    // Seek to the tenant's contiguous id range, and stop at the first id past it.
+    let cursor =
+      opts.cursor === undefined ? `${this.tenant}9\u{10FFFF}` : `${prefix}${opts.cursor}`;
+    for (;;) {
+      const page = await this.inner.listExecutions({
+        cursor,
+        ...(opts.limit !== undefined && { limit: opts.limit }),
+      });
+      const executionIds: string[] = [];
+      let past = false;
+      for (const id of page.executionIds) {
+        if (id.startsWith(prefix)) executionIds.push(id.slice(prefix.length));
+        else if (compareExecutionIds(id, prefix) > 0) {
+          past = true;
+          break;
+        }
+      }
+      if (past || page.nextCursor === undefined) return { executionIds };
+      const last = executionIds[executionIds.length - 1];
+      if (last !== undefined) return { executionIds, nextCursor: last };
+      if (page.nextCursor === cursor) {
+        throw new TypeError(
+          "TenantScopedArchiveStore: listExecutions returned a non-advancing cursor"
+        );
+      }
+      cursor = page.nextCursor;
+    }
+  }
+
+  close(): Promise<void> {
+    return this.inner.close();
+  }
+}

package/src/TenantScopedEventStore.ts

@@ -0,0 +1,266 @@
+import type { EventEnvelope } from "@loomwork/core";
+import { compareExecutionIds } from "./executionIdOrder";
+import { StaleFenceError } from "./fencing";
+import { type DecoratorPlan, installOptional } from "./installOptional";
+import type { EventStore, ExecutionPage, OptionalEventStoreMethod } from "./types";
+import { DuplicateEnvelopeIdError, DuplicateSequenceError } from "./writeConflicts";
+
+// The tenant/execution key separator — a control char that can't appear in a
+// normal executionId, so prefixing is unambiguous and un-stripping is exact.
+const SEP = ":"; // ":" is not in the ULID alphabet — an unambiguous, collision-free tenant separator
+
+/**
+ * One tenant's page of a shared store's keyset-paged enumeration.
+ *
+ * The cursor is an OUTER id — this tenant's unprefixed executionId — because that is what a
+ * caller holds: `ShardedEventStore` (the ADR 0074 composition, sharding outermost) resumes
+ * every shard from the last id of its MERGED page, which it only ever sees unprefixed. Before
+ * L10 this passed the inner, prefixed cursor out, and got the unprefixed one back in, so
+ * `Sharded(TenantScoped(…))` compared `e-04` against `acme:e-…` and re-served its first page
+ * forever.
+ *
+ * Since EventStore SPI 2.0.0 every store pages in code point order, where the ids under
+ * `prefix` are CONTIGUOUS. So a page seeks to the tenant (the empty id `prefix` included —
+ * a blank stream is still this tenant's, and repair must be able to find it) and stops at
+ * the first id past the prefix, instead of walking the whole shared store. The cursor is
+ * exclusive, so a fresh scan cannot start AT `prefix`; it starts at {@link seekBelow}, the
+ * largest practical string below `prefix` (`acme9\u{10FFFF}` for `acme:`): every other
+ * tenant whose name extends this one with a character below `:` (`acme-eu`, `acme.io`,
+ * `acme0`…`acme9`) sorts before it and is never read.
+ *
+ * It does not stop early with an empty page and a cursor: a non-final page with no ids is not
+ * something consumers are written for (`ShardedEventStore` reads an empty merged page as the
+ * end). Memory stays one inner page.
+ */
+/**
+ * The exclusive cursor a fresh tenant scan starts from: `SEP` is `:` (U+003A), so the string
+ * just below `tenant + ":"` is `tenant + "9"` (U+0039) followed by the highest code point.
+ * Only an id that continues past `tenant + "9\u{10FFFF}"` (never produced by an id
+ * generator) could sit between it and the tenant's range, and would be walked and dropped.
+ * The tenant's blank stream (`tenant + ":"`) sorts after it, so repair still finds it.
+ */
+function seekBelow(tenant: string): string {
+  return `${tenant}9\u{10FFFF}`;
+}
+
+async function pageWithinPrefix(
+  inner: EventStore,
+  tenant: string,
+  prefix: string,
+  opts: { cursor?: string; limit?: number } | undefined
+): Promise<ExecutionPage> {
+  let cursor = opts?.cursor === undefined ? seekBelow(tenant) : `${prefix}${opts.cursor}`;
+  for (;;) {
+    const page = await inner.listExecutionsPage!({
+      cursor,
+      ...(opts?.limit !== undefined && { limit: opts.limit }),
+    });
+    const executionIds: string[] = [];
+    let pastPrefix = false;
+    for (const id of page.executionIds) {
+      if (id.startsWith(prefix)) executionIds.push(id.slice(prefix.length));
+      // Every id after the tenant's range sorts after `prefix` without starting with it.
+      else if (compareExecutionIds(id, prefix) > 0) {
+        pastPrefix = true;
+        break;
+      }
+    }
+    const last = executionIds[executionIds.length - 1];
+    if (pastPrefix || page.nextCursor === undefined) return { executionIds };
+    if (last !== undefined) return { executionIds, nextCursor: last };
+    if (page.nextCursor === cursor) {
+      // The same guard `iterateExecutionIds` applies — except this loop is internal, so
+      // without it a store bug would spin here where no caller could see it.
+      throw new TypeError(
+        "TenantScopedEventStore: listExecutionsPage returned a non-advancing cursor (store bug)"
+      );
+    }
+    cursor = page.nextCursor;
+  }
+}
+
+/**
+ * K12.5 — a tenant-scoped view of a shared {@link EventStore}. Every execution
+ * id is key-prefixed with the tenant on the way in and un-prefixed on the way
+ * out, so a store scoped to tenant A can only ever ADDRESS keys under A —
+ * reading or subscribing to tenant B's executions is impossible **by
+ * construction**, not by a filter that could be bypassed. The app sees its own
+ * unprefixed ids throughout (append/read/subscribe/fork all round-trip).
+ *
+ * Default scoping mechanism per the amendment (A7): key-prefixing. Postgres
+ * row-level security is an optional hardening layer on top, not a replacement.
+ */
+export class TenantScopedEventStore implements EventStore {
+  readonly appendBatch?: NonNullable<EventStore["appendBatch"]>;
+  readonly head?: NonNullable<EventStore["head"]>;
+  readonly readRange?: NonNullable<EventStore["readRange"]>;
+  readonly acquireFence?: NonNullable<EventStore["acquireFence"]>;
+  readonly acquireFenceIf?: NonNullable<EventStore["acquireFenceIf"]>;
+  readonly appendIfUnchanged?: NonNullable<EventStore["appendIfUnchanged"]>;
+  readonly storeNow?: NonNullable<EventStore["storeNow"]>;
+  readonly sealingCapability?: NonNullable<EventStore["sealingCapability"]>;
+  readonly readAtRest?: NonNullable<EventStore["readAtRest"]>;
+  readonly copyPrefix?: NonNullable<EventStore["copyPrefix"]>;
+  readonly deleteExecution?: NonNullable<EventStore["deleteExecution"]>;
+  readonly deleteThrough?: NonNullable<EventStore["deleteThrough"]>;
+  readonly truncatePrefix?: NonNullable<EventStore["truncatePrefix"]>;
+  readonly truncatePrefixKeeping?: NonNullable<EventStore["truncatePrefixKeeping"]>;
+  readonly listExecutions?: NonNullable<EventStore["listExecutions"]>;
+  readonly listExecutionsPage?: NonNullable<EventStore["listExecutionsPage"]>;
+
+  constructor(
+    private readonly inner: EventStore,
+    private readonly tenant: string
+  ) {
+    if (tenant === "" || tenant.includes(SEP)) {
+      // Prefix scoping is only isolation if no tenant's prefix is a prefix of another's:
+      // tenant "a" scopes "b:x" to "a:b:x", which is tenant "a:b"'s "x".
+      throw new TypeError(
+        `TenantScopedEventStore: tenant must be non-empty and must not contain the separator "${SEP}" (got ${JSON.stringify(tenant)})`
+      );
+    }
+    const scope = (id: string): string => `${this.tenant}${SEP}${id}`;
+    const prefix = `${this.tenant}${SEP}`;
+    // Every optional method decided here, over the whole union (ADR 0074 Amendment): a new
+    // SPI method is a compile error until this decorator forwards, overrides or refuses it.
+    const plan = {
+      // Order preserved: the SPI's per-execution order is array order.
+      appendBatch: (envs) =>
+        inner.appendBatch!(envs.map((e) => this.scopeEnvelope(e))).catch(this.rethrowUnscoped),
+      head: (id) => inner.head!(scope(id)),
+      readRange: (id, from, to) =>
+        inner.readRange!(scope(id), from, to).then((evs) => evs.map((e) => this.unscope(e))),
+      acquireFence: (id) => inner.acquireFence!(scope(id)),
+      acquireFenceIf: (id, expect) => inner.acquireFenceIf!(scope(id), expect),
+      appendIfUnchanged: (id, event, expect) =>
+        inner.appendIfUnchanged!(
+          scope(id),
+          event === null ? null : this.scopeEnvelope(event),
+          expect
+        ).catch(this.rethrowUnscoped),
+      storeNow: "forward", // the store clock is not tenant data
+      sealingCapability: "forward", // what the store seals is not tenant data
+      // The at-rest view is tenant-scoped like `read`: ids scoped on the way in, unscoped on the way out.
+      readAtRest: () => {
+        const raw = inner.readAtRest!();
+        const back = async (p: Promise<EventEnvelope[]>) => (await p).map((e) => this.unscope(e));
+        return {
+          read: (id) => back(raw.read(scope(id))),
+          readFrom: (id, from) => back(raw.readFrom(scope(id), from)),
+          ...(raw.readRange !== undefined && {
+            readRange: (id: string, a: number, b: number) => back(raw.readRange!(scope(id), a, b)),
+          }),
+          ...(raw.head !== undefined && { head: (id: string) => raw.head!(scope(id)) }),
+        };
+      },
+      // Fork stays IN-TENANT: both ids are scoped, so a fork can never cross the
+      // tenant boundary (a cross-tenant copy is unaddressable here).
+      copyPrefix: (from, to, through, metadata) =>
+        inner.copyPrefix!(scope(from), scope(to), through, metadata).catch(this.rethrowUnscoped),
+      deleteExecution: (id) => inner.deleteExecution!(scope(id)),
+      deleteThrough: (id, through) => inner.deleteThrough!(scope(id), through),
+      truncatePrefix: (id, through) => inner.truncatePrefix!(scope(id), through),
+      truncatePrefixKeeping: (id, through, keep) =>
+        inner.truncatePrefixKeeping!(scope(id), through, keep),
+      // Enumerate only THIS tenant's executions: keep the ones under our prefix, strip it.
+      // Cross-tenant ids are invisible (isolation by construction, K12.5).
+      listExecutions: async () =>
+        (await inner.listExecutions!())
+          .filter((id) => id.startsWith(prefix))
+          .map((id) => id.slice(prefix.length)),
+      listExecutionsPage: (opts) => pageWithinPrefix(inner, this.tenant, prefix, opts),
+    } satisfies DecoratorPlan<EventStore, OptionalEventStoreMethod>;
+    installOptional<EventStore, OptionalEventStoreMethod>(this, inner, plan);
+  }
+
+  /** Structural marker: the tenant this view is scoped to (`LogLifecycle.compact` pairs it with the archive's). */
+  get tenantScope(): string {
+    return this.tenant;
+  }
+
+  private scope(id: string): string {
+    return `${this.tenant}${SEP}${id}`;
+  }
+
+  /** Rewrite a stored envelope's scoped executionId/id back to the app's view. */
+  private unscope(e: EventEnvelope): EventEnvelope {
+    const prefix = `${this.tenant}${SEP}`;
+    if (!e.executionId.startsWith(prefix)) return e;
+    const executionId = e.executionId.slice(prefix.length);
+    return { ...e, executionId, id: e.id.startsWith(prefix) ? e.id.slice(prefix.length) : e.id };
+  }
+
+  /** Prefix an envelope for storage under the tenant scope. */
+  private scopeEnvelope(e: EventEnvelope): EventEnvelope {
+    return { ...e, executionId: this.scope(e.executionId), id: this.scope(e.id) };
+  }
+
+  async append(envelope: EventEnvelope): Promise<void> {
+    return this.inner.append(this.scopeEnvelope(envelope)).catch(this.rethrowUnscoped);
+  }
+
+  /**
+   * L20 — the store's write refusals name the id it WROTE, which is the scoped one (`acme:x`).
+   * The app never sees scoped ids anywhere else, and callers key on the refusal's id: a
+   * dispatcher decides "another holder owns THIS execution" by comparing it with its own
+   * (`isSupersededRefusal`), so a prefixed id made every fenced-out attempt read as a genuine
+   * failure and the ping-pong came back under tenancy. The three normalized refusals are
+   * re-raised as the same class and name with the ids unscoped and the original as `cause`.
+   * Anything else — and a refusal naming another tenant's key, which cannot be unscoped — passes
+   * through untouched.
+   */
+  private readonly rethrowUnscoped = (err: unknown): never => {
+    throw this.unscopeError(err);
+  };
+
+  private unscopeError(err: unknown): unknown {
+    if (err === null || typeof err !== "object") return err;
+    const prefix = `${this.tenant}${SEP}`;
+    const e = err as Record<string, unknown>;
+    const executionId = e.executionId;
+    if (typeof executionId !== "string" || !executionId.startsWith(prefix)) return err;
+    const id = executionId.slice(prefix.length);
+    switch (e.name) {
+      case "StaleFenceError":
+        return new StaleFenceError(
+          id,
+          e.staleFence as number | undefined,
+          e.currentFence as number,
+          err
+        );
+      case "DuplicateSequenceError":
+        return new DuplicateSequenceError(id, e.sequence as number, err);
+      case "DuplicateEnvelopeIdError": {
+        const envelopeId = String(e.envelopeId);
+        return new DuplicateEnvelopeIdError(
+          envelopeId.startsWith(prefix) ? envelopeId.slice(prefix.length) : envelopeId,
+          id,
+          err
+        );
+      }
+      default:
+        return err;
+    }
+  }
+
+  async read(executionId: string): Promise<EventEnvelope[]> {
+    return (await this.inner.read(this.scope(executionId))).map((e) => this.unscope(e));
+  }
+
+  async readFrom(executionId: string, fromSequence: number): Promise<EventEnvelope[]> {
+    return (await this.inner.readFrom(this.scope(executionId), fromSequence)).map((e) =>
+      this.unscope(e)
+    );
+  }
+
+  async subscribe(
+    executionId: string,
+    handler: (event: EventEnvelope) => void
+  ): Promise<() => void> {
+    return this.inner.subscribe(this.scope(executionId), (e) => handler(this.unscope(e)));
+  }
+
+  async close(): Promise<void> {
+    return this.inner.close();
+  }
+}

package/src/archive.ts

@@ -0,0 +1,248 @@
+import { createHash } from "node:crypto";
+import { type EventEnvelope, canonicalJson } from "@loomwork/core";
+import {
+  ArchiveDigestError,
+  type ArchiveExecutionPage,
+  type ArchiveSegment,
+  type ArchiveSegmentKind,
+  type ArchiveStore,
+  ArchiveUnserializableError,
+} from "./archiveSpi";
+import { compareExecutionIds } from "./executionIdOrder";
+import {
+  INBOX_STREAM_PREFIX,
+  QUARANTINE_STREAM_PREFIX,
+  RESERVED_LATE_PREFIX,
+  archiveChainOf,
+  isReservedStream,
+} from "./types";
+
+/**
+ * The JSON form of the envelopes, which is what every backend stores and returns (a `Date` becomes
+ * its ISO string, `toJSON` runs, `undefined` members drop). Digesting the round-tripped value makes
+ * the digest the same on the write side and on a read that came back through any JSON store, and a
+ * value that cannot be JSON (circular, BigInt, a nesting JSON cannot hold) a typed refusal at
+ * archive time instead of a `TypeError` mid-compaction or a false digest mismatch on audit.
+ */
+function jsonForm(envelopes: readonly EventEnvelope[]): unknown {
+  try {
+    return JSON.parse(JSON.stringify(envelopes));
+  } catch (err) {
+    throw new ArchiveUnserializableError(err);
+  }
+}
+
+/**
+ * The digest of a run of envelopes: SHA-256 (hex) over their canonical JSON (sorted keys, so a
+ * backend that reorders object keys on a JSON round trip, such as Postgres `jsonb`, still agrees).
+ */
+export function segmentDigest(envelopes: readonly EventEnvelope[]): string {
+  const form = jsonForm(envelopes);
+  try {
+    return createHash("sha256").update(canonicalJson(form)).digest("hex");
+  } catch (err) {
+    throw new ArchiveUnserializableError(err);
+  }
+}
+
+/** Build a segment from the envelopes a compaction removes. `envelopes` must be non-empty and ascending. */
+export function buildSegment(
+  envelopes: readonly EventEnvelope[],
+  incarnation: string,
+  from: number = envelopes[0]!.sequence,
+  through: number = envelopes[envelopes.length - 1]!.sequence,
+  kind?: ArchiveSegmentKind
+): ArchiveSegment {
+  return {
+    from,
+    through,
+    count: envelopes.length,
+    digest: segmentDigest(envelopes),
+    incarnation,
+    ...(kind !== undefined && kind !== "events" && { kind }),
+    envelopes,
+  };
+}
+
+// ── ADR 0139 D12 - the sender field of an archived inbox envelope is the one erasable part ──────────
+
+/** `payload.sender` after the sender was erased (sealed under their subject and shredded, or redacted). */
+export const SENDER_ERASED = Object.freeze({ erased: true as const });
+
+/**
+ * The erased-sender marker carrying a STABLE, NON-IDENTIFYING per-sender reference (ADR 0139 N3): the sealed
+ * sender's opaque handle, or a random one a plaintext redaction minted per erased subject. Two messages
+ * from one erased sender still share it and two different erased senders do not, so the owner's dedupe
+ * (which keyed on the identity before the erasure) keeps telling them apart; it names nobody.
+ */
+export function senderErasedMarker(ref?: string): { erased: true; ref?: string } {
+  return ref === undefined ? { erased: true } : { erased: true, ref };
+}
+
+/** Whether a stored `sender` value is the {@link SENDER_ERASED} marker. */
+export function isSenderErased(v: unknown): boolean {
+  return typeof v === "object" && v !== null && (v as { erased?: unknown }).erased === true;
+}
+
+/**
+ * The envelope with an inbox message's `payload.sender` masked (`null`). The digest of a RESERVED
+ * stream's segment is taken over this form, so the one thing an erasure may change afterwards - the
+ * sender's identity, sealed under THEIR subject and shredded with it, or redacted in a plaintext archive
+ * (a recorded redaction, ADR 0139 D12) - does not turn into a digest mismatch on the audit read. Every
+ * other byte stays covered, and a live envelope is compared with its archived copy by
+ * {@link sameReservedEnvelope}, which still tells two DIFFERENT live senders apart.
+ */
+export function maskSender(e: EventEnvelope): EventEnvelope {
+  if (e.eventType !== "INBOX_MESSAGE") return e;
+  const p = e.payload as { sender?: unknown } | null | undefined;
+  if (p === null || typeof p !== "object" || p.sender === undefined) return e;
+  return { ...e, payload: { ...p, sender: null } };
+}
+
+/** {@link segmentDigest} over {@link maskSender}-masked envelopes (the digest of a reserved-stream segment). */
+export function reservedSegmentDigest(envelopes: readonly EventEnvelope[]): string {
+  return segmentDigest(envelopes.map(maskSender));
+}
+
+/**
+ * ADR 0139 N7 - the digest of the SENDERS of a run of reserved-stream envelopes (SHA-256 over the canonical
+ * JSON of each envelope's `payload.sender`, `null` for one without). A plaintext reserved segment carries it
+ * beside its (sender-masked) `digest`, so the one field an erasure may redact still has bit-rot detection;
+ * a redaction recomputes it in the same atomic replace.
+ */
+export function senderDigestOf(envelopes: readonly EventEnvelope[]): string {
+  const senders = envelopes.map((e) =>
+    e.eventType === "INBOX_MESSAGE"
+      ? ((e.payload as { sender?: unknown } | null)?.sender ?? null)
+      : null
+  );
+  try {
+    return createHash("sha256")
+      .update(canonicalJson(JSON.parse(JSON.stringify(senders))))
+      .digest("hex");
+  } catch (err) {
+    throw new ArchiveUnserializableError(err);
+  }
+}
+
+/** {@link buildSegment} with the reserved-stream digest. */
+export function buildReservedSegment(
+  envelopes: readonly EventEnvelope[],
+  incarnation: string,
+  from: number = envelopes[0]!.sequence,
+  through: number = envelopes[envelopes.length - 1]!.sequence
+): ArchiveSegment {
+  return {
+    ...buildSegment(envelopes, incarnation, from, through),
+    digest: reservedSegmentDigest(envelopes),
+    senderDigest: senderDigestOf(envelopes),
+  };
+}
+
+/** {@link assertSegmentDigest} for a reserved-stream segment. */
+export function assertReservedSegmentDigest(executionId: string, segment: ArchiveSegment): void {
+  // The sender digest is verified ONLY WHEN PRESENT: a segment written before ARCHIVE_STORE_SPI 1.1.0 (or by
+  // an archive that does not persist the field) has none, and still reads - its sender field simply has no
+  // bit-rot detection of its own (ADR 0139 D19; pre-1.1.0 compatibility path, not a downgrade to exploit:
+  // a writer of the archive could equally rewrite the segment).
+  const actual = reservedSegmentDigest(segment.envelopes);
+  if (
+    segment.senderDigest !== undefined &&
+    senderDigestOf(segment.envelopes) !== segment.senderDigest
+  ) {
+    throw new ArchiveDigestError(
+      executionId,
+      segment.from,
+      segment.through,
+      `sender:${segment.senderDigest}`,
+      `sender:${senderDigestOf(segment.envelopes)}`
+    );
+  }
+  if (actual !== segment.digest || segment.envelopes.length !== segment.count) {
+    throw new ArchiveDigestError(
+      executionId,
+      segment.from,
+      segment.through,
+      segment.digest,
+      actual
+    );
+  }
+}
+
+/**
+ * Are `live` and `archived` the same inbox envelope? Equal masked digests, and the senders either equal
+ * or at least one of them erased (an erased sender is the same fact with its identity removed).
+ */
+export function sameReservedEnvelope(live: EventEnvelope, archived: EventEnvelope): boolean {
+  if (segmentDigest([maskSender(live)]) !== segmentDigest([maskSender(archived)])) return false;
+  const a = (live.payload as { sender?: unknown } | null)?.sender;
+  const b = (archived.payload as { sender?: unknown } | null)?.sender;
+  if (isSenderErased(a) || isSenderErased(b)) return true;
+  return segmentDigest([{ ...live, payload: a }]) === segmentDigest([{ ...archived, payload: b }]);
+}
+
+/** One page of ids from an ascending list, keyset by exclusive cursor (shared by the backends' tests and memory store). */
+export function pageIds(
+  sorted: readonly string[],
+  opts: { cursor?: string; limit?: number } = {}
+): ArchiveExecutionPage {
+  const limit = opts.limit ?? 500;
+  const start =
+    opts.cursor === undefined
+      ? 0
+      : sorted.findIndex((id) => compareExecutionIds(id, opts.cursor!) > 0);
+  if (start === -1) return { executionIds: [] };
+  const page = sorted.slice(start, start + limit);
+  const more = start + limit < sorted.length;
+  return more ? { executionIds: page, nextCursor: page[page.length - 1]! } : { executionIds: page };
+}
+
+/** Throws {@link ArchiveDigestError} when `segment`'s envelopes do not hash to its digest. */
+export function assertSegmentDigest(executionId: string, segment: ArchiveSegment): void {
+  const actual = segmentDigest(segment.envelopes);
+  if (actual !== segment.digest || segment.envelopes.length !== segment.count) {
+    throw new ArchiveDigestError(
+      executionId,
+      segment.from,
+      segment.through,
+      segment.digest,
+      actual
+    );
+  }
+}
+
+/**
+ * The ids of the reserved streams of `chainId` the archive holds segments for (keyset prefix scans, ADR
+ * 0139): the chain's inbox (legacy, per-topic, registry) and quarantine streams, and the late runs split
+ * from them. The late keys all sit under one prefix, so their scan walks every late run of every chain
+ * (they exist only after a raced send or a node without an archive floor: a handful at most); the listing
+ * is paged by 200.
+ */
+export async function archivedReservedStreams(
+  archive: Pick<ArchiveStore, "listExecutions">,
+  chainId: string
+): Promise<string[]> {
+  const found: string[] = [];
+  const own = [`${INBOX_STREAM_PREFIX}${chainId}`, `${QUARANTINE_STREAM_PREFIX}${chainId}`];
+  const prefixes = [...own, ...own.map((p) => `${RESERVED_LATE_PREFIX}${p}`)];
+  for (const prefix of prefixes) {
+    // The cursor is EXCLUSIVE and the stream whose id IS the prefix must be listed, so start one
+    // character short of it and skip what sorts before the prefix.
+    let cursor: string | undefined = prefix.slice(0, -1);
+    for (;;) {
+      const page: ArchiveExecutionPage = await archive.listExecutions({ cursor, limit: 200 });
+      let past = false;
+      for (const id of page.executionIds) {
+        if (!id.startsWith(prefix)) {
+          if (compareExecutionIds(id, prefix) < 0) continue;
+          past = true;
+          break;
+        }
+        if (isReservedStream(id) && archiveChainOf(id) === chainId) found.push(id);
+      }
+      if (past || page.nextCursor === undefined || page.nextCursor === cursor) break;
+      cursor = page.nextCursor;
+    }
+  }
+  return found;
+}