@loomwork/plugin-content 0.0.0-stage → 0.1.1

package/src/gc.ts

@@ -0,0 +1,1213 @@
+import type { EventEnvelope } from "@loomwork/core";
+import type { ArchiveStore, EventStore, ExecutionEnumerable } from "@loomwork/event-runtime";
+import {
+  INBOX_STREAM_PREFIX,
+  INBOX_TOPIC_SEQ_BASE,
+  isPayloadShredded,
+  isReservedStream,
+  iterateExecutionIds,
+} from "@loomwork/event-runtime";
+import type { ContentStore } from "./ContentStore";
+import { isContentTouchingSnapshotStore } from "./ContentTouchingSnapshotStore";
+import { retainRootsOf, visitCitedAddresses } from "./citations";
+import { terminalEndOf, wasReopened } from "./executionEnd";
+
+// ── K10.6 (ADR 0055) — pinned mark-and-sweep for claim-checked content ────────
+//
+// Blob reclamation was the ADR 0046 deferred gap: `deleteExecution`/
+// `truncatePrefix` reclaim events but never blobs. This sweep closes it for
+// claim-checked results (ADR 0054), with the retention rule the perpetual-agents
+// series fixed jointly: *findings and their evidence are permanent; runs are
+// archivable; raw telemetry is disposable.* Pins are DERIVED from the log on
+// every sweep (mark-and-sweep, not a persisted refcount): the log is the source
+// of truth, there is no mutable index to corrupt or resurrect, and archived
+// executions keep pinning simply by being scanned — pass the archive store
+// alongside the live one. Keyed by content address, so a blob cited by a
+// finding in an archived month-1 run survives any number of rotations.
+//
+// Only a claim-check envelope's own `ref` is TTL-reclaimable (ADR 0055 D4).
+// A bare ref is load-bearing: `ContentResolvingEventStore.read` resolves every
+// bare ref in a payload and throws `ContentMissingError` when its blob is gone,
+// so erasing one bricks the execution (resume, replay, fork, export). The raw
+// log cannot say which bare refs a resolving store will resolve, so every bare
+// ref is retained while any scanned event cites it.
+
+/**
+ * The highest sequence missing below the log's tip, or -1 when it is contiguous from 0. The
+ * same test `LogLifecycle` uses to find a compaction checkpoint (ADR 0106). One backward pass.
+ */
+function highestMissingSequence(events: readonly { sequence: number }[]): number {
+  for (let i = events.length - 1; i > 0; i--) {
+    const at = events[i]!.sequence;
+    if (at - events[i - 1]!.sequence > 1) return at - 1;
+  }
+  return events.length > 0 && events[0]!.sequence !== 0 ? events[0]!.sequence - 1 : -1;
+}
+
+/**
+ * A {@link PinPredicate} for `LogLifecycle` (K10.6): pin any execution whose log
+ * carries at least one event of the designated kinds — e.g. the app's finding
+ * events. Use when no archive is configured and reclaiming the run would destroy
+ * the only copy of its durable conclusions.
+ */
+export function pinByEventKinds(
+  eventStore: Pick<EventStore, "read">,
+  kinds: Iterable<string>
+): (executionId: string) => Promise<boolean> {
+  const pinnedKinds = new Set(kinds);
+  return async (executionId) =>
+    (await eventStore.read(executionId)).some((event) => pinnedKinds.has(event.eventType));
+}
+
+/** Everything but the `dryRun` / `reclaimOrphans` pair, which {@link ContentSweepOptions} ties together. */
+export interface ContentSweepBase {
+  /**
+   * Every log store whose events may cite content — the live store AND any
+   * archive stores. All must be enumerable (`listExecutionsPage()` preferred —
+   * SP-2, bounded memory — or `listExecutions()`): a store that cannot be
+   * enumerated cannot be swept safely (its pins would be invisible), so the
+   * sweep refuses rather than silently under-pinning.
+   *
+   * List the LIVE store BEFORE its archive. Retention copies an execution to the archive and
+   * then deletes it from the live store. Scanned live-first, an execution that moves during
+   * the sweep is seen in one store or the other. Scanned archive-first, it can be missed by
+   * both, and its blobs then look like orphans.
+   */
+  eventStores: readonly (Pick<EventStore, "read"> & ExecutionEnumerable)[];
+  /**
+   * ADR 0055 D6 — where compaction checkpoints live: the live snapshot store AND EACH
+   * ARCHIVE'S snapshot store. `LogLifecycle.compact` checkpoints the fold and truncates the
+   * prefix, so a ref the prefix cited survives only in snapshot state.
+   *
+   * Which logs were compacted (ADR 0106, superseding "no sequence-1 event"): compaction
+   * removes its checkpoint's slot and, when it keeps pinned-kind events, never the tip. So a
+   * gap-free log with more than the bootstrap was never compacted (no snapshot read); a
+   * gapped log's checkpoint sits at its highest missing sequence `gap`; a bootstrap-only log
+   * was compacted through its tip. For each compacted execution the sweep pins every ref in:
+   *  - the COMPACTION CHECKPOINT: the lowest snapshot in `[gap, tip]` — exactly `gap` for a
+   *    compaction's own, the fork seed (`metadata.forkSequence`, one `loadAt`) for a child
+   *    forked from a compacted parent — or, for a bootstrap-only log, its latest snapshot.
+   *    ANY snapshot at or above `gap` covers a lost checkpoint, matching `LogLifecycle.compact`,
+   *    which accepts a base at or above the gap; below `gap` nothing does. `fork()` from any point after it loads that
+   *    checkpoint, so its refs stay reachable even after a later snapshot overwrote them.
+   *  - the LATEST snapshot, which resume loads.
+   *
+   * Snapshots in between hold only checkpoint- or suffix-derived refs, and the suffix is
+   * scanned as log. Anything below the checkpoint is unreachable. The refs are PINNED because
+   * compaction folded away the event kinds, so the sweep cannot tell telemetry from evidence.
+   * They are released when retention deletes the execution, which deletes its snapshots too.
+   *
+   * `reclaimOrphans` REFUSES, before erasing anything:
+   *  - without this option, when any scanned store can `truncatePrefix`;
+   *  - when an execution looks compacted but no checkpoint is found. That covers a gap with no
+   *    snapshot in `[gap, tip]`, and a sequence-0-only log with no snapshot, which is either
+   *    compacted at its tip or a run that never got past its bootstrap. The two are
+   *    indistinguishable, so both refuse.
+   */
+  snapshotStores?: readonly SnapshotLookup[];
+  /**
+   * ADR 0138 - the compaction archives (`LogLifecycle.compactionArchive`). Compaction MOVES the events
+   * it removes into the archive, so a ref only an archived event cites (a step input the fold no
+   * longer keeps, an old finding) is cited THERE and nowhere else. Every ref cited by an archived
+   * envelope is PINNED for as long as the archive holds it: the sweep never reclaims a blob the
+   * recoverable history still names. Not scanning them is the hazard: an erasing orphan pass without
+   * the archive of a compacted log erases blobs its audit trail still cites. Read through the same
+   * sealing store the lifecycle uses (an `EncryptingArchiveStore` yields plaintext; a crypto-shredded
+   * subject's archive is unreadable and cites nothing). The archive itself is never swept or pruned.
+   *
+   * REQUIRED (fail closed) by an ERASING `reclaimOrphans` pass whenever any scanned log is compacted
+   * (a gap below its tip, or only its bootstrap left): {@link ArchiveStoresRequiredError} otherwise,
+   * before anything is erased. Coverage is CHECKED for EVERY compacted log, whatever its checkpoint
+   * is called (the `ckpt-0138-` id mark is only used to label reports - it can be lost to pruning, so
+   * it never gates an erase): the log's removed range must be covered by the given archives' headers
+   * (legacy-checkpoint segments included), else {@link ArchiveStoresRequiredError} (`reason:
+   * "uncovered"`). `[]` alone therefore no longer passes a gapped log. The only way past it, for logs
+   * compacted before ADR 0138 (no archive exists), is {@link acknowledgeUnarchivedLogs}.
+   * The archive is ENUMERATED (`listExecutions`), so segments whose log is gone are scanned
+   * too. A segment that is still sealed (count > 0 with no envelopes: the RAW inner store of an
+   * `EncryptingArchiveStore`) throws {@link SealedArchiveScanError} on an erasing pass.
+   */
+  archiveStores?: readonly Pick<ArchiveStore, "read" | "listExecutions" | "headers">[];
+  /**
+   * Explicit opt-in for an erasing `reclaimOrphans` pass over compacted logs the given
+   * `archiveStores` do not cover: "these logs' compacted history is already gone (compacted before
+   * ADR 0138 and never re-compacted, or a fork child whose parent's archive is not keyed to it);
+   * erasing their orphan blobs is accepted." The affected executions are reported in
+   * `unarchivedAcknowledged`. Never a substitute for passing the real archive.
+   */
+  acknowledgeUnarchivedLogs?: boolean;
+  /**
+   * The blob store. With `deleteIfUntouchedSince` (SPI 1.3.0) every erase is conditional on
+   * the blob's touch time, which closes the re-cite race for a re-cite THROUGH `put` (ADR 0055
+   * D5); without it the sweep falls back to `delete` and reports `raceSafe: false`. A citation
+   * copied WITHOUT a `put` (a fork's `copyPrefix`, a ref an `append` keeps) is protected by SPI
+   * 1.4.0 `touch`, which `reclaimOrphans` requires; see `reclaimOrphans`. `listPage` enables it.
+   */
+  contentStore: Pick<
+    ContentStore,
+    "delete" | "deleteIfUntouchedSince" | "listPage" | "touchClock" | "touch"
+  >;
+  /** Event kinds whose cited refs are pinned — retained as long as the citing fact exists. */
+  pinnedEventTypes: Iterable<string>;
+  /**
+   * Reclaim an unpinned ref only when its effective citation time is older than this (ADR 0146:
+   * its latest citation, or, for a ref cited by an execution that has ENDED, that execution's end
+   * if later). EXACTLY ONE of `olderThanMs` / `policy` must be given.
+   */
+  olderThanMs?: number;
+  /**
+   * ADR 0145 - an app-owned retention policy (`retentionPolicy()` from `@loomwork/workflow-runtime`;
+   * typed structurally here so this package takes no dependency on it). `content.unpinnedAfterMs`
+   * is used as `olderThanMs`. A policy without a `content` section is an error, not a silent no-op.
+   * Re-validated structurally (see `resolvePolicyTtl`): unknown keys are refused, and
+   * `unpinnedAfterMs >= terminalTtlMs` when the policy carries one (an advisory consistency rule,
+   * ADR 0145 D2).
+   */
+  policy?: {
+    terminalTtlMs?: number;
+    snapshots?: unknown;
+    content?: { unpinnedAfterMs: number };
+  };
+  /**
+   * LOG time, in epoch ms: the instant the TTL is measured back from, compared against event
+   * `timestamp`s (`now − effective citation time ≥ olderThanMs`, ADR 0146). It is NOT the store's clock. A
+   * simulated or replayed log may run far from the store's wall clock; the race guard uses
+   * `touchedBefore` for that reason.
+   */
+  now: number;
+  /**
+   * STORE time, in epoch ms, on the clock the content store stamps touch times with: the
+   * cutoff for the conditional delete and for orphan eligibility (ADR 0055 D5). Default: the
+   * store's `touchClock()` read ONCE at the sweep's start, minus `olderThanMs`. A store with
+   * `deleteIfUntouchedSince` but no `touchClock` requires it explicitly.
+   */
+  touchedBefore?: number;
+  /**
+   * DX-2 — report what WOULD be reclaimed without deleting anything (the
+   * `loom sweep content` operator default; `--apply` turns it off).
+   */
+  dryRun?: boolean;
+  /**
+   * ADR 0055 D7 — external root sets: content addresses held OUTSIDE the scanned logs (an app
+   * table such as a Postgres `experience_refs`). Every yielded address is pinned through both
+   * passes. Read once per sweep, after the mark phase. An app that records a new root for
+   * bytes the store already holds must `put` them (the put is the touch the conditional
+   * delete sees), exactly as a flow does.
+   */
+  roots?: () => AsyncIterable<string>;
+  /**
+   * ADR 0055 D6 — also reclaim ORPHANS: blobs no scanned event and no root cites (their
+   * execution was deleted with no archive, a crash between `put` and the append, a truncated
+   * prefix), once untouched for the TTL. Requires the store's `listPage` and
+   * `deleteIfUntouchedSince`; refuses otherwise.
+   *
+   * ACKNOWLEDGEMENT REQUIRED (ADR 0055 amendment, fail-closed): to ERASE, pass
+   * `{ completeScan: true }` (plus `snapshotsTouchContent: true` when `snapshotStores` is given, below). A bare `true` (or any other value) throws
+   * {@link ReclaimOrphansAckError} before anything is read or erased. A `dryRun` erases nothing
+   * and is how you check completeness, so under `dryRun: true` any truthy value (`true` included)
+   * is accepted; see {@link ContentSweepOptions} for the typing. The acknowledgement is your
+   * assertion that `eventStores`, `snapshotStores` and `roots` together cover EVERY place that
+   * cites content, scanned in the right ORDER: each live store BEFORE its archive (ADR 0055
+   * "Scan order"). `[archive, live]` can miss an execution that retention moves mid-sweep, and
+   * its blobs then look like orphans.
+   *
+   * HAZARD the sweep cannot detect, which is why the assertion exists: a citing store that was
+   * NOT passed in `eventStores` or `snapshotStores`. Every blob only that store cites is an
+   * orphan to this pass, and it is erased while still cited. Pass every archive
+   * (`retention.archive`) and each archive's snapshot store, and every app table through `roots`.
+   * Run with `dryRun: true` first and read the list.
+   *
+   * CONCURRENCY (ADR 0055 D6 amendment 2): D5's conditional delete only sees a touch. A `put`
+   * touches; a citation that enters a log WITHOUT one does not by itself:
+   * `ContentResolvingEventStore.copyPrefix` (a fork) copies refs verbatim, and an `append`
+   * keeps refs already inside its payload (recalled memory, `scriptRef`, refs passed between
+   * steps). SPI 1.4.0 `touch` closes that: those two paths touch the refs they carry, so a fork
+   * made mid-sweep makes `deleteIfUntouchedSince` refuse. To ERASE, the content store MUST
+   * implement `touch` or the sweep throws {@link ReclaimOrphansTouchError} (a `dryRun` need not).
+   * The log must be written through a `ContentResolvingEventStore` over that store: a writer
+   * that copies refs some other way is outside the guarantee.
+   *
+   * SNAPSHOTS (second path): a fork of a COMPACTED parent saves a seed snapshot whose state
+   * cites refs that exist nowhere else (the prefix was truncated). `ContentResolvingEventStore`
+   * cannot see it; only a snapshot store wrapped in `ContentTouchingSnapshotStore`
+   * (outside any `EncryptingSnapshotStore`, over the same content store) touches those refs.
+   * loom never builds either store for the host, so the wrapping is the host's and is not PROVEN
+   * from here (a sweep, and the CLI, read a RAW store over the tables a wrapped one wrote, so an
+   * unbranded store is no evidence the writer was unwrapped): an ERASING pass given `snapshotStores` must also pass
+   * `{ completeScan: true, snapshotsTouchContent: true }` or it throws
+   * {@link ReclaimOrphansSnapshotAckError}. Without `snapshotStores` it is not needed (such a
+   * pass already refuses a store that can `truncatePrefix`, and a fork of an uncompacted parent
+   * copies every event, so its seed cites nothing the copied events do not). A `dryRun` is exempt.
+   * The flag stays an assertion about the WRITER and is ALWAYS required, even when every store
+   * passed is a `ContentTouchingSnapshotStore` (it vouches for itself, not for the other stores the
+   * runtime saves to). Best-effort detection only WARNS: the report counts branded and unbranded
+   * stores (`snapshotStoresTouching` / `snapshotStoresUnbranded`), and a pass that is handed a MIX
+   * (some branded, some not: a host wrapped some writers and likely forgot others) emits one
+   * `LOOM_CONTENT_SNAPSHOT_UNWRAPPED` process warning. It never refuses, so the CLI's raw SQLite
+   * stores are not rejected; it never relaxes the flag either (fail-closed).
+   *
+   * THE GUARANTEE IS D5'S, NOT THE TOUCH'S. The cutoff is `touchClock() - olderThanMs`. The
+   * touch BEFORE a write is what makes a sweep whose cutoff is later refuse; so the race is
+   * closed while a write's touch-to-commit window is shorter than the margin
+   * `store-now - cutoff` (the TTL, or the distance of an explicit `touchedBefore` from the
+   * store's clock). The touch AFTER the write is a best-effort extension of that window (it
+   * is not retried and an error is reported through `onTouchError`, not raised); do not
+   * count on it. With a zero or tiny margin the window is unbounded: a fork whose before-touch
+   * is older than the cutoff and which commits after the scan has passed the child is erased
+   * under. So an ERASING orphan pass refuses `olderThanMs <= 0` and any cutoff closer to the
+   * store's clock than {@link MIN_ORPHAN_ERASE_MARGIN_MS} with {@link ReclaimOrphansMarginError},
+   * and a store with no `touchClock()` (the margin cannot be measured) with
+   * {@link ReclaimOrphansClockError}; a `dryRun` is unaffected. Pick a margin well above your longest write (a fork's copy of a
+   * long prefix included).
+   */
+  reclaimOrphans?: ReclaimOrphansAck | boolean;
+}
+
+/**
+ * Sweep options. `reclaimOrphans` and `dryRun` are tied by a union so the type says what the
+ * runtime enforces: a sweep that can ERASE (`dryRun` absent or `false`) accepts only the
+ * acknowledgement object (or `false`), so a bare `true` is a compile error there; a
+ * `dryRun: true` sweep also accepts a plain `true`, because it erases nothing and is how a host
+ * checks completeness. (A `dryRun` typed as a plain `boolean` falls in the first arm, which is
+ * the safe one.)
+ */
+export type ContentSweepOptions = Omit<ContentSweepBase, "dryRun" | "reclaimOrphans"> &
+  (
+    | { dryRun?: false; reclaimOrphans?: ReclaimOrphansAck | false }
+    | { dryRun: true; reclaimOrphans?: ReclaimOrphansAck | boolean }
+  );
+
+/**
+ * The caller's assertion that a `reclaimOrphans` sweep sees every citing store. The literal
+ * `true` type makes `{ completeScan: false }` a compile error; the runtime check also refuses
+ * untyped callers.
+ */
+export interface ReclaimOrphansAck {
+  completeScan: true;
+  /**
+   * Required (checked at runtime) whenever an ERASING pass is given `snapshotStores`: the
+   * caller's assertion that every snapshot store the runtime SAVES to is wrapped in
+   * `ContentTouchingSnapshotStore` (outside any `EncryptingSnapshotStore`). Without it a
+   * fork of a compacted parent saves a seed snapshot citing refs that live nowhere else, and
+   * a sweep can erase them under the live child. See {@link ReclaimOrphansSnapshotAckError}.
+   */
+  snapshotsTouchContent?: true;
+}
+
+/** A safe description of a rejected value: BigInt and circular values make `JSON.stringify` throw. */
+function describeReceived(received: unknown): string {
+  try {
+    return JSON.stringify(received) ?? String(received);
+  } catch {
+    try {
+      return `an unserializable ${typeof received} (${Object.prototype.toString.call(received)})`;
+    } catch {
+      return `an unserializable ${typeof received}`;
+    }
+  }
+}
+
+/** `reclaimOrphans` was set without `{ completeScan: true }`. Nothing was read or erased. */
+export class ReclaimOrphansAckError extends TypeError {
+  constructor(received: unknown) {
+    super(
+      `sweepUnpinnedContent: reclaimOrphans must be { completeScan: true } to erase (received ${describeReceived(received)}). Orphan reclamation erases every blob that no scanned log, snapshot or root cites, so a citing store you forgot to pass loses its blobs while they are still cited. Set { completeScan: true } only when eventStores, snapshotStores and roots cover ALL of them (every retention archive and its snapshot store included), AND scanned in order: each live store BEFORE its archive, or an execution retention moves mid-sweep can be missed by both. A dryRun does not need the acknowledgement. Migration: reclaimOrphans: true -> reclaimOrphans: { completeScan: true }.`
+    );
+    this.name = "ReclaimOrphansAckError";
+  }
+}
+
+/**
+ * An ERASING `reclaimOrphans` pass was given `snapshotStores` without
+ * `{ snapshotsTouchContent: true }`. Nothing was read or erased. A compacted parent's prefix refs
+ * live only in snapshot state, and a fork copies that state into its seed snapshot with no `put`
+ * and no event; only a snapshot store wrapped in `ContentTouchingSnapshotStore` touches them.
+ * The sweep cannot see how the writing runtime's snapshot store was built, so, like D6's
+ * archive assertion, the host states it. A `dryRun` is exempt. With no `snapshotStores` the
+ * acknowledgement is not needed: the pass then refuses any store that can `truncatePrefix`, and
+ * a fork of an UNcompacted parent copies every event (refs touched by `copyPrefix`), so its seed
+ * state cites nothing the copied events do not.
+ */
+export class ReclaimOrphansSnapshotAckError extends TypeError {
+  constructor() {
+    super(
+      "sweepUnpinnedContent: an erasing reclaimOrphans pass given snapshotStores needs { completeScan: true, snapshotsTouchContent: true }. A fork of a compacted parent saves a seed snapshot that cites refs found nowhere else; only a snapshot store wrapped in ContentTouchingSnapshotStore (outside any EncryptingSnapshotStore, over the same content store the log uses) touches them, so a sweep racing the fork erases blobs a live child cites (replay then throws ContentMissingError). Wrap every snapshot store the runtime saves to, then pass snapshotsTouchContent: true, or run with dryRun: true."
+    );
+    this.name = "ReclaimOrphansSnapshotAckError";
+  }
+}
+
+/**
+ * `reclaimOrphans` was asked to ERASE through a content store without SPI 1.4.0 `touch`.
+ * Nothing was read or erased. Without `touch`, a citation that enters a log with no `put` (a
+ * fork's `copyPrefix`, a ref an `append` carries) cannot make the conditional delete refuse, so
+ * an orphan sweep concurrent with a fork or a delete can erase a blob a live log still cites
+ * (replay then throws `ContentMissingError`). This is a deletion safety boundary: it refuses
+ * rather than documenting the hazard. A `dryRun` is unaffected.
+ */
+export class ReclaimOrphansTouchError extends TypeError {
+  constructor() {
+    super(
+      "sweepUnpinnedContent: reclaimOrphans needs a content store with touch() (ContentStore SPI 1.4.0) to ERASE. Without it a fork (copyPrefix) or an append that carries an existing ref cannot mark the blob re-cited, so an orphan sweep racing a fork or a delete can erase a blob a live log still cites. Add touch() to the store (SqliteContentStore and InMemoryContentStore have it; a CachingContentStore forwards it), or run with dryRun: true."
+    );
+    this.name = "ReclaimOrphansTouchError";
+  }
+}
+
+/**
+ * The smallest margin, in ms, between the content store's clock and the guard cutoff that an
+ * ERASING orphan pass accepts (ADR 0055 D6 amendment 2). A write's touch-to-commit window must
+ * be shorter than the margin for the touch to protect it; 60 s is far above an append and
+ * above a fork's prefix copy at any realistic size, and an operator who needs a bigger one
+ * simply passes a larger TTL.
+ */
+export const MIN_ORPHAN_ERASE_MARGIN_MS = 60_000;
+
+/**
+ * An ERASING `reclaimOrphans` pass was configured with a zero/negative `olderThanMs`, or a
+ * cutoff (`touchedBefore`) closer to the content store's clock than
+ * {@link MIN_ORPHAN_ERASE_MARGIN_MS}. Nothing was read or erased. With no margin the
+ * touch-before-write has no window to protect: a write can touch, the sweep read a later cutoff,
+ * and the write commit after the scan, so a blob a live log cites is erased.
+ */
+export class ReclaimOrphansMarginError extends TypeError {
+  constructor(readonly marginMs: number) {
+    super(
+      `sweepUnpinnedContent: an erasing reclaimOrphans pass needs a guard margin of at least ${MIN_ORPHAN_ERASE_MARGIN_MS}ms between the content store's clock and the cutoff (received ${marginMs}ms: olderThanMs, or touchedBefore's distance from the store's clock). The touch that protects a fork or an append only covers a write whose touch-to-commit window is shorter than that margin; with olderThanMs <= 0 the window is unbounded. Raise olderThanMs / lower touchedBefore, or run with dryRun: true.`
+    );
+    this.name = "ReclaimOrphansMarginError";
+  }
+}
+
+/**
+ * An ERASING `reclaimOrphans` pass over a content store with `deleteIfUntouchedSince` but no
+ * `touchClock()`. Nothing was read or erased. Without the store's clock the sweep cannot measure
+ * the margin between "now" and the cutoff (`touchedBefore` is an unchecked caller value, so
+ * `touchedBefore: Date.now()` would pass any `olderThanMs`), and the touch-to-commit window is
+ * then unbounded. A `dryRun` is exempt.
+ */
+export class ReclaimOrphansClockError extends TypeError {
+  constructor() {
+    super(
+      "sweepUnpinnedContent: an erasing reclaimOrphans pass needs a content store with touchClock() so the guard margin can be measured (a store with deleteIfUntouchedSince but no touchClock cannot prove touchedBefore is far enough behind its clock). Add touchClock() to the store, or run with dryRun: true."
+    );
+    this.name = "ReclaimOrphansClockError";
+  }
+}
+
+/** Structural view of a snapshot store: just `loadLatest` (no snapshot-runtime dependency). */
+export interface SnapshotLookup {
+  loadLatest(
+    executionId: string
+  ): Promise<{ id?: string; sequence: number; state: unknown } | null>;
+  /** Exact-sequence load; used for a forked child's seed (optional — falls back to a walk). */
+  loadAt?(
+    executionId: string,
+    sequence: number
+  ): Promise<{ id?: string; sequence: number; state: unknown } | null>;
+  loadLatestBefore(
+    executionId: string,
+    sequence: number
+  ): Promise<{ id?: string; sequence: number; state: unknown } | null>;
+}
+
+let warnedUnwrapped = false;
+/** Test-only: re-arm the once-per-process warning below. Not exported from the package index. */
+export function resetSnapshotUnwrappedWarning(): void {
+  warnedUnwrapped = false;
+}
+/**
+ * One process warning for a MIXED set of snapshot stores, ONCE per process (like
+ * `LOOM_CONTENT_TOUCH`): a scheduled sweep over the same mixed set would otherwise warn every run.
+ * Never throws (best effort, advisory).
+ */
+function emitUnwrappedWarning(touching: number, unbranded: number): void {
+  if (warnedUnwrapped) return;
+  warnedUnwrapped = true;
+  const proc = (globalThis as { process?: { emitWarning?: (m: string, o?: object) => void } })
+    .process;
+  try {
+    proc?.emitWarning?.(
+      `sweepUnpinnedContent: ${unbranded} of ${touching + unbranded} snapshot stores are not a ContentTouchingSnapshotStore while ${touching} are. If an unbranded one is a store the runtime SAVES to, a fork of a compacted parent can lose blobs to this erasing orphan pass; if it is only a raw reader over a wrapped writer's tables, ignore this.`,
+      { code: "LOOM_CONTENT_SNAPSHOT_UNWRAPPED" }
+    );
+  } catch {
+    // advisory only
+  }
+}
+
+/** Orphan-pass page size (ADR 0055 D6): bounded memory per page. */
+const ORPHAN_PAGE_LIMIT = 500;
+
+export interface ContentSweepReport {
+  executionsScanned: number;
+  refsSeen: number;
+  refsPinned: number;
+  /**
+   * ADR 0055 D4 - refs cited at least once anywhere but as a RECLAIMABLE claim-check envelope's
+   * `ref` (a digest counts as anywhere). Since ADR 0140 that includes a `retain: true` envelope
+   * whose ref sits at a trusted root (the top-level `output` of a STEP_COMPLETED, through a taint
+   * wrapper), and a R5 media source `{ kind: "ref", ref: { address } }`. Every address cited by an
+   * `archiveStores` segment is counted unconditionally. These are never reclaimed while any scanned
+   * event cites them. The set OVERLAPS `refsPinned` (a ref can be in both): the two are not disjoint
+   * partitions of `refsSeen`.
+   */
+  refsLoadBearing: number;
+  /**
+   * ADR 0146 - unpinned refs whose age clock came from a citing execution's END rather than from the
+   * citation: a ref cited by an execution that ended after the citation ages from the end. Counted
+   * on every sweep.
+   */
+  refsAgedByEnd: number;
+  /**
+   * ADR 0146 - DRY RUN ONLY (absent on an erasing sweep, which keeps no second map): refs the old
+   * citation clock would have reclaimed that the end clock keeps. Never reclaimed by the end clock
+   * that would not also have been by the old one, so this is the whole delta.
+   */
+  heldByEndClock?: string[];
+  /**
+   * Unpinned refs whose age clock stayed on the CITATION because the newest citing execution was
+   * RE-OPENED after a terminal event (`resumeAs` onto an ended run, ADR 0104 D1; ADR 0146's exception):
+   * they can be reclaimed while that execution's log is still live. Counted on every sweep. A plain
+   * running or parked execution that never ended is NOT counted. Decisions are unchanged: visibility only.
+   */
+  refsOfReopened: number;
+  /**
+   * DRY RUN ONLY (absent on an erasing sweep, which keeps no second list): of `reclaimed`, the addresses
+   * counted in `refsOfReopened`, so an operator sees them before `--apply`.
+   */
+  reclaimedWhileReopened?: string[];
+  /** Content addresses erased this sweep — or, under `dryRun`, that WOULD be. */
+  reclaimed: string[];
+  /**
+   * Eligible addresses (refs and orphans) whose conditional erase was REFUSED by the touch/race guard:
+   * `deleteIfUntouchedSince` returned false because the blob was touched after `touchCutoff` (a
+   * concurrent re-cite, or a content-store clock that is not the one the log's `now` runs on).
+   * ALWAYS 0 on a dry run, which never calls the store: a dry run can list N in `reclaimed` while the
+   * apply reports `reclaimed: []` and `keptByTouch: N`; when it does, compare `touchCutoff` with the
+   * store's touch stamps (see `touchedBefore`). Also 0 when the store is not `raceSafe` (plain delete).
+   */
+  keptByTouch: number;
+  /**
+   * The cutoff the guard compared touch stamps with, on the CONTENT STORE's clock (resolved from
+   * `touchedBefore`, else `touchClock() - olderThanMs`). Present on a dry run too (where it was not
+   * enforced); `undefined` when the store is not `raceSafe`.
+   */
+  touchCutoff?: number;
+  /**
+   * ADR 0055 D5 — every erase was conditional on the blob's touch time
+   * (`deleteIfUntouchedSince`), so a `put` that re-cited a blob during the sweep kept it.
+   * `false` = the store lacks it and the sweep used plain `delete`: such a re-cite is lost.
+   */
+  raceSafe: boolean;
+  /** ADR 0055 D6 — orphans erased (or, under `dryRun`, that WOULD be); `[]` unless `reclaimOrphans`. */
+  orphansReclaimed: string[];
+  /**
+   * Of `snapshotStores`, how many are a `ContentTouchingSnapshotStore` (branded). Informational:
+   * an unbranded store may be a raw reader over tables a wrapped writer filled.
+   */
+  snapshotStoresTouching: number;
+  /** Of `snapshotStores`, how many are NOT branded. See `snapshotStoresTouching`. */
+  snapshotStoresUnbranded: number;
+  /**
+   * Executions whose scanned snapshot `state` is a top-level `__loomEnc` envelope (an
+   * `EncryptingSnapshotStore({ sealState })` read RAW): the refs it cites are invisible to this
+   * scan. An erasing pass throws {@link SealedSnapshotScanError} instead; a `dryRun` lists them.
+   * The check looks at the TOP-LEVEL `__loomEnc` key of `state` only, not a nested envelope.
+   */
+  sealedSnapshots: string[];
+  /**
+   * Executions whose snapshot load threw `PayloadShreddedError` (their subject was crypto-shredded
+   * under a `sealState` store): the snapshot is erased, so it cites no readable refs and is skipped.
+   * Blobs another live owner cites stay pinned by it. Any OTHER load error still aborts the pass.
+   */
+  shreddedSnapshots: string[];
+  /**
+   * Executions whose compacted history is NOT (fully) in the given archives and whose orphan blobs
+   * this erasing pass erased anyway because `acknowledgeUnarchivedLogs: true` accepted it. Empty
+   * otherwise (and on a dry run).
+   */
+  unarchivedAcknowledged: string[];
+}
+
+/**
+ * An ERASING `reclaimOrphans` pass found compacted logs but was given no `archiveStores`: the events
+ * a compaction moved are cited only by the archive, so their blobs would look like orphans and be
+ * erased (ADR 0138). Nothing was erased.
+ */
+export class ArchiveStoresRequiredError extends TypeError {
+  constructor(
+    readonly executionIds: readonly string[],
+    /** `"none"`: no archiveStores given. `"uncovered"`: given, but they do not hold what was archived. */
+    readonly reason: "none" | "uncovered" = "none"
+  ) {
+    const shown = executionIds.slice(0, 5).join(", ");
+    const more = executionIds.length > 5 ? ` (+${executionIds.length - 5} more)` : "";
+    super(
+      reason === "none"
+        ? `sweepUnpinnedContent: ${executionIds.length} scanned log(s) are compacted (${shown}${more}) and no archiveStores were given. Compaction MOVES the removed events into the compaction archive, which is then the only place that cites their blobs; an erasing orphan pass without it deletes blobs the recoverable history still names. Pass archiveStores: [the compaction archive] (the sealing store when encrypted), or acknowledgeUnarchivedLogs: true if no archive exists (logs compacted before ADR 0138), or run with dryRun: true. Nothing was erased.`
+        : `sweepUnpinnedContent: ${executionIds.length} scanned log(s) are compacted but the given archiveStores do not cover the removed range (${shown}${more}): the archive passed is empty, the wrong one, or was wiped. An erasing orphan pass would delete blobs the lost history still names. Pass the real compaction archive (the sealing store when encrypted), restore it, run with dryRun: true, or pass acknowledgeUnarchivedLogs: true if that history is already gone (pre-ADR-0138 logs, fork children). Nothing was erased.`
+    );
+    this.name = "ArchiveStoresRequiredError";
+    Object.setPrototypeOf(this, ArchiveStoresRequiredError.prototype);
+  }
+}
+
+/**
+ * An erasing sweep read an archive segment that is still sealed (count > 0, no envelopes): the RAW
+ * inner store of an `EncryptingArchiveStore`. The refs inside are invisible, so live blobs would
+ * look unreferenced. Pass the sealing store itself. Nothing was erased.
+ */
+export class SealedArchiveScanError extends TypeError {
+  constructor(readonly executionIds: readonly string[]) {
+    const shown = executionIds.slice(0, 5).join(", ");
+    const more = executionIds.length > 5 ? ` (+${executionIds.length - 5} more)` : "";
+    super(
+      `sweepUnpinnedContent: ${executionIds.length} archived execution(s) hold sealed segments (${shown}${more}), so the refs they cite are invisible and an erasing pass would delete live blobs: pass the opening archive store (the EncryptingArchiveStore itself, not its inner store) in archiveStores, or run with dryRun: true. Nothing was erased.`
+    );
+    this.name = "SealedArchiveScanError";
+    Object.setPrototypeOf(this, SealedArchiveScanError.prototype);
+  }
+}
+
+/**
+ * An erasing sweep read a snapshot whose `state` is one sealed envelope (a `sealState`
+ * `EncryptingSnapshotStore` given as its RAW inner store). The scan cannot see the refs inside, so
+ * it would treat live blobs as unreferenced and erase them. Nothing was erased.
+ */
+export class SealedSnapshotScanError extends TypeError {
+  constructor(readonly executionIds: readonly string[]) {
+    const shown = executionIds.slice(0, 5).join(", ");
+    const more = executionIds.length > 5 ? ` (+${executionIds.length - 5} more)` : "";
+    super(
+      `sweepUnpinnedContent: ${executionIds.length} scanned snapshot(s) hold a sealed (whole-state encrypted) state (${shown}${more}), so the refs they cite are invisible and an erasing pass would delete live blobs: pass the decrypting snapshot store (the EncryptingSnapshotStore itself, not its inner store) in snapshotStores, or run with dryRun: true. Nothing was erased.`
+    );
+    this.name = "SealedSnapshotScanError";
+    Object.setPrototypeOf(this, SealedSnapshotScanError.prototype);
+  }
+}
+
+/**
+ * Mark: walk every event of every execution across the given stores, collecting
+ * each ref's latest citation timestamp, pinning refs cited from events of the
+ * designated kinds, and marking refs cited anywhere other than as a
+ * claim-check envelope's `ref` (a `digest` included) as load-bearing. Sweep:
+ * physically erase refs that are neither pinned nor load-bearing and whose
+ * effective citation time is older than the TTL — i.e. only refs cited solely as an
+ * envelope's `ref`. ADR 0146: a citing execution that has ENDED (newest kernel terminal event, not
+ * re-opened) ages its citations from `max(citation, end)`, so with a content TTL at least the log TTL a blob is
+ * never reclaimable before retention could delete the log citing it (exceptions: ADR 0146); a
+ * running execution (or a reserved stream) keeps the citation clock. Never earlier than the citation. Their erasure is invisible to replay by the claim-check
+ * contract (ADR 0054 — the fold never resolves); `resolveClaimCheck` readers get
+ * `null`. A bare ref is never reclaimed while cited (ADR 0055 D4): the resolving
+ * store would throw `ContentMissingError` on the next read. Idempotent:
+ * `ContentStore.delete` is idempotent and a reclaimed ref simply no longer
+ * resolves on the next sweep.
+ *
+ * Race-safe (ADR 0055 D5) when the store has `deleteIfUntouchedSince`: every erase is
+ * conditional on the blob being untouched since `now − olderThanMs`, so a `put` that re-cites
+ * old bytes between the scan and its own append keeps the blob. That holds while a flow's
+ * put→append window is shorter than the TTL. A citation copied without a `put` (a fork's
+ * `copyPrefix`, a ref kept inside an `append` payload) is covered by SPI 1.4.0 `touch`, which
+ * `reclaimOrphans` requires; see `reclaimOrphans`. `roots` (D7) pins addresses held outside the
+ * log; `reclaimOrphans` (D6) also erases stored blobs nothing scanned cites. Cost:
+ * O(events + blobs), all membership tests are Set/Map lookups.
+ */
+export async function sweepUnpinnedContent(
+  given: ContentSweepOptions
+): Promise<ContentSweepReport> {
+  const hasTtl = given.olderThanMs !== undefined;
+  const hasPolicy = given.policy !== undefined;
+  if (hasTtl === hasPolicy) {
+    throw new TypeError(
+      hasTtl
+        ? "sweepUnpinnedContent: pass olderThanMs OR policy, not both - they name the same TTL"
+        : "sweepUnpinnedContent: needs a TTL - pass olderThanMs, or policy (a retention policy with a content.unpinnedAfterMs section)"
+    );
+  }
+  let olderThanMs = given.olderThanMs as number;
+  if (hasPolicy) olderThanMs = resolvePolicyTtl(given.policy);
+  const { policy: _policy, ...rest } = given;
+  return sweepResolved({ ...rest, olderThanMs } as ContentSweepOptions & { olderThanMs: number });
+}
+
+/**
+ * ADR 0145 D3 - structural re-validation of a retention policy, WITHOUT a dependency on
+ * `@loomwork/workflow-runtime`. Each field is read ONCE into a plain snapshot, then the snapshot is
+ * checked, so a getter answering differently on a second read cannot pass a rule-breaking value.
+ * Checks what the sweep consumes: unknown keys (top level and `content`), `unpinnedAfterMs` a
+ * finite integer > 0, and, when `terminalTtlMs` is present, a finite integer >= 0 with
+ * `unpinnedAfterMs >= terminalTtlMs`. `snapshots` is allowed and not inspected (the sweep reads
+ * nothing from it; `LogLifecycle` validates it).
+ */
+function resolvePolicyTtl(policy: unknown): number {
+  const bad = (m: string): never => {
+    throw new TypeError(`sweepUnpinnedContent: policy ${m}`);
+  };
+  if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+    return bad("must be a retention policy object");
+  }
+  for (const k of Object.keys(policy)) {
+    if (k !== "terminalTtlMs" && k !== "snapshots" && k !== "content") {
+      bad(`has unknown key "${k}" (expected terminalTtlMs, snapshots, content)`);
+    }
+  }
+  const o = policy as Record<string, unknown>;
+  const ttl = o.terminalTtlMs;
+  const content = o.content;
+  if (ttl !== undefined && (typeof ttl !== "number" || !Number.isInteger(ttl) || ttl < 0)) {
+    bad(`terminalTtlMs must be a finite integer >= 0 (milliseconds); got ${String(ttl)}`);
+  }
+  if (content === undefined) {
+    return bad(
+      "has no content section - add content.unpinnedAfterMs to the retention policy, or pass olderThanMs"
+    );
+  }
+  if (typeof content !== "object" || content === null || Array.isArray(content)) {
+    return bad("content must be an object with unpinnedAfterMs");
+  }
+  for (const k of Object.keys(content)) {
+    if (k !== "unpinnedAfterMs") {
+      bad(`has unknown key "content.${k}" (expected unpinnedAfterMs)`);
+    }
+  }
+  const u = (content as Record<string, unknown>).unpinnedAfterMs;
+  if (typeof u !== "number" || !Number.isInteger(u) || u <= 0) {
+    return bad(
+      `content.unpinnedAfterMs must be a finite integer > 0 (milliseconds); got ${String(u)}`
+    );
+  }
+  if (typeof ttl === "number" && u < ttl) {
+    bad(`content.unpinnedAfterMs (${u}) must be >= terminalTtlMs (${ttl})`);
+  }
+  return u;
+}
+
+async function sweepResolved(
+  options: ContentSweepOptions & { olderThanMs: number }
+): Promise<ContentSweepReport> {
+  const store = options.contentStore;
+  const requested = options.reclaimOrphans as unknown;
+  if (requested !== undefined && requested !== false) {
+    // A dry run erases nothing, so it needs no acknowledgement (any truthy value turns the
+    // orphan pass on); the sweep that would ERASE must carry it.
+    if (
+      options.dryRun === true
+        ? !requested
+        : typeof requested !== "object" ||
+          requested === null ||
+          (requested as { completeScan?: unknown }).completeScan !== true
+    ) {
+      throw new ReclaimOrphansAckError(requested);
+    }
+  }
+  const orphans = requested !== undefined && requested !== false;
+  if (orphans && store.listPage === undefined) {
+    throw new TypeError(
+      "sweepUnpinnedContent: reclaimOrphans needs a content store with listPage() (ContentStore SPI 1.3.0) — orphans cannot be found without enumerating the store"
+    );
+  }
+  if (orphans && store.deleteIfUntouchedSince === undefined) {
+    throw new TypeError(
+      "sweepUnpinnedContent: reclaimOrphans needs a content store with deleteIfUntouchedSince() (ContentStore SPI 1.3.0) — a plain delete of a listed orphan loses a blob re-put since the listing"
+    );
+  }
+  if (orphans && options.dryRun !== true && store.touch === undefined) {
+    throw new ReclaimOrphansTouchError();
+  }
+  if (
+    orphans &&
+    options.dryRun !== true &&
+    options.snapshotStores !== undefined &&
+    (requested as { snapshotsTouchContent?: unknown }).snapshotsTouchContent !== true
+  ) {
+    throw new ReclaimOrphansSnapshotAckError();
+  }
+  if (orphans && options.dryRun !== true && store.touchClock === undefined) {
+    throw new ReclaimOrphansClockError();
+  }
+  if (
+    orphans &&
+    options.snapshotStores === undefined &&
+    options.eventStores.some(
+      (s) => typeof (s as { truncatePrefix?: unknown }).truncatePrefix === "function"
+    )
+  ) {
+    throw new TypeError(
+      "sweepUnpinnedContent: reclaimOrphans over an event store that can truncatePrefix needs snapshotStores — a compacted prefix's refs live only in its snapshot, and without it they look like orphans"
+    );
+  }
+  const snapshotList = options.snapshotStores ?? [];
+  const snapshotStoresTouching = snapshotList.filter(isContentTouchingSnapshotStore).length;
+  const snapshotStoresUnbranded = snapshotList.length - snapshotStoresTouching;
+  if (
+    orphans &&
+    options.dryRun !== true &&
+    snapshotStoresTouching > 0 &&
+    snapshotStoresUnbranded > 0
+  ) {
+    emitUnwrappedWarning(snapshotStoresTouching, snapshotStoresUnbranded);
+  }
+  // ADR 0055 D5 — the guard cutoff is on the STORE's clock, read once at the START: a blob
+  // touched after it (a re-citing put the scan could not see yet) is refused. The TTL on the
+  // log (`now`) is a different clock and never feeds it.
+  const raceSafe = store.deleteIfUntouchedSince !== undefined;
+  let cutoff = Number.NEGATIVE_INFINITY;
+  // The store's clock as read ONCE for this sweep: the cutoff AND the orphan margin below are
+  // measured against the same reading. A second read made the margin `olderThanMs` plus however
+  // many milliseconds elapsed between the reads, so a sub-minute TTL could pass the guard.
+  let storeNow: number | undefined;
+  if (raceSafe) {
+    if (options.touchedBefore !== undefined) {
+      cutoff = options.touchedBefore;
+    } else if (store.touchClock !== undefined) {
+      storeNow = await store.touchClock();
+      cutoff = storeNow - options.olderThanMs;
+    } else {
+      throw new TypeError(
+        "sweepUnpinnedContent: the content store has deleteIfUntouchedSince() but no touchClock() — pass touchedBefore (a cutoff on the store's clock) explicitly"
+      );
+    }
+  }
+  const dryRun = options.dryRun === true;
+  if (orphans && !dryRun) {
+    // The touch protects a write only while its touch-to-commit window is shorter than the
+    // margin between the store's clock and the cutoff (module note; ADR 0055 D6 amendment 2).
+    if (!(options.olderThanMs > 0)) throw new ReclaimOrphansMarginError(options.olderThanMs);
+    const margin = (storeNow ?? (await store.touchClock!())) - cutoff;
+    if (!(margin >= MIN_ORPHAN_ERASE_MARGIN_MS)) throw new ReclaimOrphansMarginError(margin);
+  }
+  /** Erase one address; `true` iff it is gone because of this sweep (or would be). */
+  let keptByTouch = 0;
+  const erase = async (address: string): Promise<boolean> => {
+    if (dryRun) return true;
+    const ref = { __loomContent: address };
+    if (store.deleteIfUntouchedSince !== undefined) {
+      const gone = await store.deleteIfUntouchedSince(ref, cutoff);
+      if (!gone) keptByTouch++;
+      return gone;
+    }
+    await store.delete(ref);
+    return true;
+  };
+
+  // Mark memory is O(distinct cited addresses): one Map entry per address plus the Sets.
+  const pinnedKinds = new Set(options.pinnedEventTypes);
+  // ADR 0146: the EFFECTIVE time per ref (end clock). Dry run alone also keeps the raw citation time.
+  const lastCited = new Map<string, number>();
+  const rawCited = options.dryRun === true ? new Map<string, number>() : undefined;
+  const viaEnd = new Set<string>();
+  // Refs whose newest citation came from a RE-OPENED execution (same tie rule as `viaEnd`).
+  const viaReopened = new Set<string>();
+  const pinned = new Set<string>();
+  const loadBearing = new Set<string>();
+  let executionsScanned = 0;
+  const uncovered: string[] = [];
+  const sealedSnapshots: string[] = [];
+  const shreddedSnapshots: string[] = [];
+  const compactedLogs = new Set<string>();
+  // EVERY compacted log's removed range (the `ckpt-0138-` mark is NOT consulted: it can be lost to
+  // pruning or a fork seed, and a heuristic must not gate an ERASE): each must be covered by the
+  // given archives' headers, else refused unless `acknowledgeUnarchivedLogs`.
+  const archivedRanges = new Map<string, Array<[number, number]>>();
+  const sealedArchives: string[] = [];
+
+  for (const eventStore of options.eventStores) {
+    if (eventStore.listExecutions === undefined && eventStore.listExecutionsPage === undefined) {
+      throw new TypeError(
+        "sweepUnpinnedContent: every event store must support listExecutionsPage() or listExecutions() — a store that cannot be enumerated cannot be swept safely"
+      );
+    }
+    for await (const executionId of iterateExecutionIds(eventStore)) {
+      executionsScanned++;
+      const events = await eventStore.read(executionId);
+      // ADR 0146: a terminal execution's citations age from its END (never earlier than the citation).
+      const endedAt = isReservedStream(executionId) ? undefined : terminalEndOf(events);
+      const reopened =
+        !isReservedStream(executionId) && endedAt === undefined && wasReopened(events);
+      for (const event of events) {
+        // Only a finite end strictly after the citation moves the clock; anything else is today's clock exactly.
+        const at = endedAt !== undefined && endedAt > event.timestamp ? endedAt : event.timestamp;
+        visitCitedAddresses(
+          event.payload,
+          (address, inEnvelope) => {
+            const prior = lastCited.get(address);
+            if (prior === undefined || at > prior) {
+              lastCited.set(address, at);
+              if (at > event.timestamp) viaEnd.add(address);
+              else viaEnd.delete(address);
+              if (reopened) viaReopened.add(address);
+              else viaReopened.delete(address);
+            }
+            if (rawCited !== undefined) {
+              const rawPrior = rawCited.get(address);
+              if (rawPrior === undefined || event.timestamp > rawPrior) {
+                rawCited.set(address, event.timestamp);
+              }
+            }
+            if (pinnedKinds.has(event.eventType)) pinned.add(address);
+            if (!inEnvelope) loadBearing.add(address);
+          },
+          retainRootsOf(event)
+        );
+      }
+      // Did compaction touch this log, and where is its checkpoint (ADR 0106)? Compaction
+      // removes its checkpoint's own slot and, whenever it keeps pinned-kind events, never
+      // the tip (the tip rule). So a gap-free log with more than the bootstrap was never
+      // compacted and costs no snapshot read; a gapped log's checkpoint sits at its highest
+      // missing sequence `gap`; and a bootstrap-only log was compacted through its tip (or
+      // never got past its bootstrap), its checkpoint above the tip.
+      if (events.length === 0) continue;
+      const tipSequence = events[events.length - 1]!.sequence;
+      // ADR 0139 - a RESERVED stream (the inbox, its topic streams, the quarantine copies) is never
+      // checkpointed: a trim MOVES its consumed prefix to the archive instead. Its removed range is
+      // what its sequences skip from its first possible one (a topic stream starts at
+      // INBOX_TOPIC_SEQ_BASE, not 0, so a bare "gap" test would call every topic stream compacted), and
+      // an erasing pass needs the archive to cover it, exactly as for a compacted log (D24).
+      if (isReservedStream(executionId)) {
+        const runs = missingRunsFrom(
+          events,
+          isInboxTopicStream(executionId) ? INBOX_TOPIC_SEQ_BASE : 1,
+          tipSequence
+        );
+        if (runs.length > 0) {
+          compactedLogs.add(executionId);
+          archivedRanges.set(executionId, runs);
+        }
+        continue;
+      }
+      const gap = highestMissingSequence(events);
+      const bootstrapOnly = events.length === 1;
+      if (gap < 0 && !bootstrapOnly) continue;
+      // ADR 0138 - a gapped log is compacted: an erasing orphan pass needs its archive, else the
+      // moved events' blobs look unreferenced. (A bootstrap-only log counts once a checkpoint shows.)
+      if (gap >= 0) {
+        compactedLogs.add(executionId);
+        archivedRanges.set(executionId, missingRunsWithin(events, gap));
+      }
+      if (options.snapshotStores === undefined) {
+        if (gap >= 0) uncovered.push(executionId); // a gap is log evidence
+        continue;
+      }
+      const pin = (snapshot: { state: unknown }): void => {
+        const st = snapshot.state;
+        if (typeof st === "object" && st !== null && "__loomEnc" in st) {
+          if (!sealedSnapshots.includes(executionId)) sealedSnapshots.push(executionId);
+        }
+        visitCitedAddresses(snapshot.state, (address) => {
+          if (!lastCited.has(address)) lastCited.set(address, Number.POSITIVE_INFINITY);
+          pinned.add(address);
+        });
+      };
+      let covered = false;
+      for (const snapshots of options.snapshotStores) {
+        try {
+          const latest = await snapshots.loadLatest(executionId);
+          if (latest !== null && latest.sequence >= 1) pin(latest);
+          if (bootstrapOnly) {
+            // Compacted at the tip: the checkpoint IS the latest snapshot.
+            if (latest !== null && latest.sequence >= 1) {
+              covered = true;
+              compactedLogs.add(executionId);
+              archivedRanges.set(executionId, [[1, latest.sequence]]);
+            }
+            continue;
+          }
+          // The checkpoint: the LOWEST snapshot in [gap, tip] — any snapshot at or above the gap
+          // covers a lost checkpoint, exactly as `compact` accepts a base at or above it. A
+          // compaction's own sits exactly at `gap` (one read). A child forked from a compacted
+          // parent copies the gap, and its lowest snapshot is its fork seed, whose sequence the
+          // copied envelopes record (`metadata.forkSequence`): one exact read. Only a log with
+          // neither walks the snapshots down from the tip.
+          let checkpoint = await snapshots.loadLatestBefore(executionId, gap);
+          const forkSequence = (events[0]!.metadata as { forkSequence?: unknown } | undefined)
+            ?.forkSequence;
+          if (
+            (checkpoint === null || checkpoint.sequence !== gap) &&
+            typeof forkSequence === "number" &&
+            forkSequence >= gap
+          ) {
+            const seed =
+              snapshots.loadAt !== undefined
+                ? await snapshots.loadAt(executionId, forkSequence)
+                : await snapshots.loadLatestBefore(executionId, forkSequence);
+            checkpoint = seed !== null && seed.sequence === forkSequence ? seed : checkpoint;
+          }
+          if (checkpoint === null || checkpoint.sequence < gap) {
+            checkpoint = null;
+            let s = await snapshots.loadLatestBefore(executionId, tipSequence);
+            while (s !== null && s.sequence >= gap) {
+              checkpoint = s;
+              s =
+                s.sequence > gap
+                  ? await snapshots.loadLatestBefore(executionId, s.sequence - 1)
+                  : null;
+            }
+          }
+          if (checkpoint !== null) {
+            pin(checkpoint);
+            covered = true;
+          }
+        } catch (err) {
+          // Only a CONFIRMED crypto-shred means the snapshot is erased: the store's error (recognised by the realm-safe
+          // brand, never by name) AND the execution's own `PAYLOAD_SHREDDED`
+          // tombstone. A node that merely lacks the key can report the same error, so without the
+          // tombstone it propagates like anything else (undecryptable, I/O, a key unavailable with no
+          // tombstone): dropping refs for data that still exists would delete live blobs. A
+          // snapshot store without the raw log reports a shredded subject's PRE-shred snapshot as
+          // `KeyUnavailableError` (it cannot see the tombstone above it), so that name is accepted
+          // too, but ONLY beside the tombstone.
+          const tombstoned = events.some((e) => e.eventType === "PAYLOAD_SHREDDED");
+          if (
+            !(err instanceof Error) ||
+            (!isPayloadShredded(err) && err.name !== "KeyUnavailableError") ||
+            !tombstoned
+          )
+            throw err;
+          if (!shreddedSnapshots.includes(executionId)) shreddedSnapshots.push(executionId);
+          covered = true;
+        }
+      }
+      if (!covered) uncovered.push(executionId);
+    }
+  }
+  // ADR 0138 - what compaction MOVED out of the logs still cites content: pin it permanently. The
+  // archive is enumerated (not walked per log), so segments of an execution whose log is gone count.
+  const anyLog = async (executionId: string): Promise<EventEnvelope[]> => {
+    const all: EventEnvelope[] = [];
+    for (const es of options.eventStores) all.push(...(await es.read(executionId)));
+    return all;
+  };
+  for (const archive of options.archiveStores ?? []) {
+    let cursor: string | undefined;
+    do {
+      const page = await archive.listExecutions({ ...(cursor !== undefined && { cursor }) });
+      for (const executionId of page.executionIds) {
+        // ADR 0139 - a reserved stream that is DELETED (nothing live to derive a gap from) is judged by
+        // the archive's own extent: a hole between its first possible sequence and its last archived one
+        // (a trim before the archive existed) is history nothing holds, exactly like a live stream's gap.
+        if (isReservedStream(executionId) && !executionId.startsWith("__loom_late__:")) {
+          if (!archivedRanges.has(executionId)) {
+            const headers = await archive.headers(executionId);
+            const first = isInboxTopicStream(executionId) ? INBOX_TOPIC_SEQ_BASE : 1;
+            const extent = headers.length > 0 ? headers[headers.length - 1]!.through : -1;
+            const holes = missingRunsFrom(
+              headers.flatMap((h) =>
+                Array.from(new Set([h.from, h.through])).map((sequence) => ({ sequence }))
+              ),
+              first,
+              extent
+            ).filter(
+              ([x, y]) =>
+                !rangeCovered(
+                  x,
+                  y,
+                  headers.map((h) => [h.from, h.through] as const)
+                )
+            );
+            if (holes.length > 0) {
+              compactedLogs.add(executionId);
+              archivedRanges.set(executionId, holes);
+            }
+          }
+        }
+        let segments: Awaited<ReturnType<ArchiveStore["read"]>>;
+        try {
+          segments = await archive.read(executionId);
+        } catch (err) {
+          // Only a CONFIRMED shred (the realm-safe brand AND the execution's own tombstone) means the
+          // archived copy is erased; anything else (a missing key on this node, I/O) propagates.
+          if (
+            isPayloadShredded(err) &&
+            (await anyLog(executionId)).some((e) => e.eventType === "PAYLOAD_SHREDDED")
+          ) {
+            continue;
+          }
+          throw err;
+        }
+        for (const seg of segments) {
+          if (seg.count > 0 && seg.envelopes.length === 0) {
+            if (!sealedArchives.includes(executionId)) sealedArchives.push(executionId);
+            continue;
+          }
+          for (const event of seg.envelopes) {
+            visitCitedAddresses(event.payload, (address) => {
+              const prior = lastCited.get(address);
+              if (prior === undefined || event.timestamp > prior) {
+                lastCited.set(address, event.timestamp);
+                viaEnd.delete(address);
+                viaReopened.delete(address);
+              }
+              if (rawCited !== undefined) {
+                const rawPrior = rawCited.get(address);
+                if (rawPrior === undefined || event.timestamp > rawPrior) {
+                  rawCited.set(address, event.timestamp);
+                }
+              }
+              pinned.add(address);
+              loadBearing.add(address);
+            });
+          }
+        }
+      }
+      cursor = page.nextCursor;
+    } while (cursor !== undefined);
+  }
+  if (!dryRun && sealedArchives.length > 0) throw new SealedArchiveScanError(sealedArchives);
+  const unarchivedAcknowledged: string[] = [];
+  if (orphans && !dryRun && options.archiveStores === undefined && compactedLogs.size > 0) {
+    if (options.acknowledgeUnarchivedLogs !== true) {
+      throw new ArchiveStoresRequiredError([...compactedLogs]);
+    }
+  }
+  // Coverage is CHECKED for every compacted log, whatever its checkpoint is called: `[]` or a
+  // partial archive never suffices for a gapped log; only the headers (or the explicit
+  // acknowledgment, for logs whose history is already gone) get past it.
+  if (orphans && !dryRun && archivedRanges.size > 0) {
+    const lost: string[] = [];
+    for (const [executionId, runs] of archivedRanges) {
+      const held: Array<[number, number]> = [];
+      for (const archive of options.archiveStores ?? []) {
+        for (const h of await archive.headers(executionId)) held.push([h.from, h.through]);
+      }
+      if (!runs.every(([a, b]) => rangeCovered(a, b, held))) lost.push(executionId);
+    }
+    if (lost.length > 0) {
+      if (options.acknowledgeUnarchivedLogs !== true) {
+        throw new ArchiveStoresRequiredError(lost, "uncovered");
+      }
+      unarchivedAcknowledged.push(...lost);
+    }
+  }
+  if (!dryRun && sealedSnapshots.length > 0) throw new SealedSnapshotScanError(sealedSnapshots);
+  if (orphans && uncovered.length > 0) {
+    const shown = uncovered.slice(0, 5).join(", ");
+    const more = uncovered.length > 5 ? ` (+${uncovered.length - 5} more)` : "";
+    throw new TypeError(
+      `sweepUnpinnedContent: ${uncovered.length} execution(s) look compacted but no checkpoint in snapshotStores covers them (${shown}${more}) — their prefix refs cannot be seen, so reclaimOrphans refuses before erasing anything. A run that never got past its bootstrap looks the same: let it progress, or pass the snapshot store its checkpoint went to (each archive's too)`
+    );
+  }
+
+  // ADR 0055 D7 — external root sets pin like a pinned event kind does.
+  const roots = new Set<string>();
+  if (options.roots !== undefined) {
+    for await (const address of options.roots()) roots.add(address);
+  }
+
+  const reclaimed: string[] = [];
+  const heldByEndClock: string[] = [];
+  const reclaimedWhileReopened: string[] = [];
+  let refsAgedByEnd = 0;
+  let refsOfReopened = 0;
+  for (const [address, citedAt] of lastCited) {
+    if (pinned.has(address) || loadBearing.has(address) || roots.has(address)) continue;
+    if (viaEnd.has(address)) refsAgedByEnd++;
+    const ofReopened = viaReopened.has(address);
+    if (ofReopened) refsOfReopened++;
+    if (options.now - citedAt < options.olderThanMs) {
+      const raw = rawCited?.get(address);
+      if (raw !== undefined && options.now - raw >= options.olderThanMs) {
+        heldByEndClock.push(address);
+      }
+      continue;
+    }
+    if (await erase(address)) {
+      reclaimed.push(address);
+      if (ofReopened && dryRun) reclaimedWhileReopened.push(address);
+    }
+  }
+
+  // ADR 0055 D6 — orphans: stored, untouched since the cutoff, and cited by nothing scanned.
+  // `pinned` and `loadBearing` are subsets of `lastCited`, so two Set lookups decide.
+  // Keyset paging on address: erasing entries of a page never skips a later one.
+  const orphansReclaimed: string[] = [];
+  if (orphans) {
+    let cursor: string | undefined;
+    do {
+      const page = await store.listPage!({
+        ...(cursor !== undefined && { cursor }),
+        limit: ORPHAN_PAGE_LIMIT,
+        touchedBefore: cutoff,
+      });
+      for (const { address, touchedAt } of page.entries) {
+        // 0 = UNKNOWN: the column default a pre-1.3.0 writer leaves during a mixed rollout.
+        if (!(touchedAt > 0)) continue;
+        if (lastCited.has(address) || roots.has(address)) continue;
+        if (await erase(address)) orphansReclaimed.push(address);
+      }
+      cursor = page.nextCursor;
+    } while (cursor !== undefined);
+  }
+
+  return {
+    executionsScanned,
+    refsSeen: lastCited.size,
+    refsPinned: pinned.size,
+    refsLoadBearing: loadBearing.size,
+    refsAgedByEnd,
+    ...(dryRun && { heldByEndClock }),
+    refsOfReopened,
+    ...(dryRun && { reclaimedWhileReopened }),
+    reclaimed,
+    keptByTouch,
+    ...(raceSafe && { touchCutoff: cutoff }),
+    raceSafe,
+    orphansReclaimed,
+    snapshotStoresTouching,
+    snapshotStoresUnbranded,
+    sealedSnapshots,
+    shreddedSnapshots,
+    unarchivedAcknowledged,
+  };
+}
+
+/** The runs of sequences in `[1..extent]` that `events` does not hold. */
+function missingRunsWithin(
+  events: readonly { sequence: number }[],
+  extent: number
+): Array<[number, number]> {
+  const runs: Array<[number, number]> = [];
+  let prev = 0;
+  for (const e of events) {
+    if (e.sequence === 0) continue;
+    if (e.sequence > extent + 1) break;
+    if (e.sequence - prev > 1) runs.push([prev + 1, e.sequence - 1]);
+    prev = e.sequence;
+  }
+  if (prev < extent) runs.push([prev + 1, extent]);
+  return runs;
+}
+
+/** The runs of sequences in `[first..extent]` that `events` does not hold. */
+function missingRunsFrom(
+  events: readonly { sequence: number }[],
+  first: number,
+  extent: number
+): Array<[number, number]> {
+  const runs: Array<[number, number]> = [];
+  let prev = first - 1;
+  for (const e of events) {
+    if (e.sequence < first) continue;
+    if (e.sequence > extent) break;
+    if (e.sequence - prev > 1) runs.push([prev + 1, e.sequence - 1]);
+    prev = e.sequence;
+  }
+  if (prev < extent) runs.push([prev + 1, extent]);
+  return runs;
+}
+
+/** A per-topic inbox stream (`__loom_inbox__:<chain>#<16 hex>`): its sequences start at INBOX_TOPIC_SEQ_BASE. */
+function isInboxTopicStream(executionId: string): boolean {
+  return executionId.startsWith(INBOX_STREAM_PREFIX) && /#[0-9a-f]{16}$/.test(executionId);
+}
+
+/** Whether the union of `held` ranges (inclusive) covers every sequence of `[a..b]`. */
+function rangeCovered(a: number, b: number, held: readonly (readonly [number, number])[]): boolean {
+  let next = a;
+  for (const [from, through] of [...held].sort((x, y) => x[0] - y[0])) {
+    if (from > next) break;
+    if (through >= next) next = through + 1;
+    if (next > b) return true;
+  }
+  return next > b;
+}