@loomwork/plugin-content 0.0.0-stage → 0.1.1

package/dist/gc.js

@@ -0,0 +1,819 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SealedSnapshotScanError = exports.SealedArchiveScanError = exports.ArchiveStoresRequiredError = exports.ReclaimOrphansClockError = exports.ReclaimOrphansMarginError = exports.MIN_ORPHAN_ERASE_MARGIN_MS = exports.ReclaimOrphansTouchError = exports.ReclaimOrphansSnapshotAckError = exports.ReclaimOrphansAckError = void 0;
+exports.pinByEventKinds = pinByEventKinds;
+exports.resetSnapshotUnwrappedWarning = resetSnapshotUnwrappedWarning;
+exports.sweepUnpinnedContent = sweepUnpinnedContent;
+const event_runtime_1 = require("@loomwork/event-runtime");
+const ContentTouchingSnapshotStore_1 = require("./ContentTouchingSnapshotStore");
+const citations_1 = require("./citations");
+const executionEnd_1 = require("./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) {
+    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.
+ */
+function pinByEventKinds(eventStore, kinds) {
+    const pinnedKinds = new Set(kinds);
+    return async (executionId) => (await eventStore.read(executionId)).some((event) => pinnedKinds.has(event.eventType));
+}
+/** A safe description of a rejected value: BigInt and circular values make `JSON.stringify` throw. */
+function describeReceived(received) {
+    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. */
+class ReclaimOrphansAckError extends TypeError {
+    constructor(received) {
+        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";
+    }
+}
+exports.ReclaimOrphansAckError = 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.
+ */
+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";
+    }
+}
+exports.ReclaimOrphansSnapshotAckError = 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.
+ */
+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";
+    }
+}
+exports.ReclaimOrphansTouchError = 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.
+ */
+exports.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.
+ */
+class ReclaimOrphansMarginError extends TypeError {
+    marginMs;
+    constructor(marginMs) {
+        super(`sweepUnpinnedContent: an erasing reclaimOrphans pass needs a guard margin of at least ${exports.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.marginMs = marginMs;
+        this.name = "ReclaimOrphansMarginError";
+    }
+}
+exports.ReclaimOrphansMarginError = 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.
+ */
+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";
+    }
+}
+exports.ReclaimOrphansClockError = ReclaimOrphansClockError;
+let warnedUnwrapped = false;
+/** Test-only: re-arm the once-per-process warning below. Not exported from the package index. */
+function resetSnapshotUnwrappedWarning() {
+    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, unbranded) {
+    if (warnedUnwrapped)
+        return;
+    warnedUnwrapped = true;
+    const proc = globalThis
+        .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;
+/**
+ * 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.
+ */
+class ArchiveStoresRequiredError extends TypeError {
+    executionIds;
+    reason;
+    constructor(executionIds, 
+    /** `"none"`: no archiveStores given. `"uncovered"`: given, but they do not hold what was archived. */
+    reason = "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.executionIds = executionIds;
+        this.reason = reason;
+        this.name = "ArchiveStoresRequiredError";
+        Object.setPrototypeOf(this, ArchiveStoresRequiredError.prototype);
+    }
+}
+exports.ArchiveStoresRequiredError = ArchiveStoresRequiredError;
+/**
+ * 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.
+ */
+class SealedArchiveScanError extends TypeError {
+    executionIds;
+    constructor(executionIds) {
+        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.executionIds = executionIds;
+        this.name = "SealedArchiveScanError";
+        Object.setPrototypeOf(this, SealedArchiveScanError.prototype);
+    }
+}
+exports.SealedArchiveScanError = SealedArchiveScanError;
+/**
+ * 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.
+ */
+class SealedSnapshotScanError extends TypeError {
+    executionIds;
+    constructor(executionIds) {
+        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.executionIds = executionIds;
+        this.name = "SealedSnapshotScanError";
+        Object.setPrototypeOf(this, SealedSnapshotScanError.prototype);
+    }
+}
+exports.SealedSnapshotScanError = SealedSnapshotScanError;
+/**
+ * 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.
+ */
+async function sweepUnpinnedContent(given) {
+    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;
+    if (hasPolicy)
+        olderThanMs = resolvePolicyTtl(given.policy);
+    const { policy: _policy, ...rest } = given;
+    return sweepResolved({ ...rest, olderThanMs });
+}
+/**
+ * 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) {
+    const bad = (m) => {
+        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;
+    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.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) {
+    const store = options.contentStore;
+    const requested = options.reclaimOrphans;
+    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.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.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.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(ContentTouchingSnapshotStore_1.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;
+    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 >= exports.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) => {
+        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();
+    const rawCited = options.dryRun === true ? new Map() : undefined;
+    const viaEnd = new Set();
+    // Refs whose newest citation came from a RE-OPENED execution (same tie rule as `viaEnd`).
+    const viaReopened = new Set();
+    const pinned = new Set();
+    const loadBearing = new Set();
+    let executionsScanned = 0;
+    const uncovered = [];
+    const sealedSnapshots = [];
+    const shreddedSnapshots = [];
+    const compactedLogs = new Set();
+    // 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();
+    const sealedArchives = [];
+    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 (0, event_runtime_1.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 = (0, event_runtime_1.isReservedStream)(executionId) ? undefined : (0, executionEnd_1.terminalEndOf)(events);
+            const reopened = !(0, event_runtime_1.isReservedStream)(executionId) && endedAt === undefined && (0, executionEnd_1.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;
+                (0, citations_1.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);
+                }, (0, citations_1.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 ((0, event_runtime_1.isReservedStream)(executionId)) {
+                const runs = missingRunsFrom(events, isInboxTopicStream(executionId) ? event_runtime_1.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) => {
+                const st = snapshot.state;
+                if (typeof st === "object" && st !== null && "__loomEnc" in st) {
+                    if (!sealedSnapshots.includes(executionId))
+                        sealedSnapshots.push(executionId);
+                }
+                (0, citations_1.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
+                        ?.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) ||
+                        (!(0, event_runtime_1.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) => {
+        const all = [];
+        for (const es of options.eventStores)
+            all.push(...(await es.read(executionId)));
+        return all;
+    };
+    for (const archive of options.archiveStores ?? []) {
+        let cursor;
+        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 ((0, event_runtime_1.isReservedStream)(executionId) && !executionId.startsWith("__loom_late__:")) {
+                    if (!archivedRanges.has(executionId)) {
+                        const headers = await archive.headers(executionId);
+                        const first = isInboxTopicStream(executionId) ? event_runtime_1.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])));
+                        if (holes.length > 0) {
+                            compactedLogs.add(executionId);
+                            archivedRanges.set(executionId, holes);
+                        }
+                    }
+                }
+                let segments;
+                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 ((0, event_runtime_1.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) {
+                        (0, citations_1.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 = [];
+    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 = [];
+        for (const [executionId, runs] of archivedRanges) {
+            const held = [];
+            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();
+    if (options.roots !== undefined) {
+        for await (const address of options.roots())
+            roots.add(address);
+    }
+    const reclaimed = [];
+    const heldByEndClock = [];
+    const reclaimedWhileReopened = [];
+    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 = [];
+    if (orphans) {
+        let cursor;
+        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, extent) {
+    const runs = [];
+    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, first, extent) {
+    const runs = [];
+    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) {
+    return executionId.startsWith(event_runtime_1.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, b, held) {
+    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;
+}
+//# sourceMappingURL=gc.js.map