@loomwork/plugin-content 0.0.0-stage → 0.1.0

package/dist/gc.d.ts

@@ -0,0 +1,470 @@
+import type { ArchiveStore, EventStore, ExecutionEnumerable } from "@loomwork/event-runtime";
+import type { ContentStore } from "./ContentStore";
+/**
+ * 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 declare function pinByEventKinds(eventStore: Pick<EventStore, "read">, kinds: Iterable<string>): (executionId: string) => Promise<boolean>;
+/** 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;
+}
+/** `reclaimOrphans` was set without `{ completeScan: true }`. Nothing was read or erased. */
+export declare class ReclaimOrphansAckError extends TypeError {
+    constructor(received: unknown);
+}
+/**
+ * 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 declare class ReclaimOrphansSnapshotAckError extends TypeError {
+    constructor();
+}
+/**
+ * `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 declare class ReclaimOrphansTouchError extends TypeError {
+    constructor();
+}
+/**
+ * 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 declare const MIN_ORPHAN_ERASE_MARGIN_MS = 60000;
+/**
+ * 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 declare class ReclaimOrphansMarginError extends TypeError {
+    readonly marginMs: number;
+    constructor(marginMs: number);
+}
+/**
+ * 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 declare class ReclaimOrphansClockError extends TypeError {
+    constructor();
+}
+/** 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>;
+}
+/** Test-only: re-arm the once-per-process warning below. Not exported from the package index. */
+export declare function resetSnapshotUnwrappedWarning(): void;
+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 declare class ArchiveStoresRequiredError extends TypeError {
+    readonly executionIds: readonly string[];
+    /** `"none"`: no archiveStores given. `"uncovered"`: given, but they do not hold what was archived. */
+    readonly reason: "none" | "uncovered";
+    constructor(executionIds: readonly string[], 
+    /** `"none"`: no archiveStores given. `"uncovered"`: given, but they do not hold what was archived. */
+    reason?: "none" | "uncovered");
+}
+/**
+ * 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 declare class SealedArchiveScanError extends TypeError {
+    readonly executionIds: readonly string[];
+    constructor(executionIds: readonly string[]);
+}
+/**
+ * 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 declare class SealedSnapshotScanError extends TypeError {
+    readonly executionIds: readonly string[];
+    constructor(executionIds: readonly string[]);
+}
+/**
+ * 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 declare function sweepUnpinnedContent(given: ContentSweepOptions): Promise<ContentSweepReport>;
+//# sourceMappingURL=gc.d.ts.map

package/dist/gc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gc.d.ts","sourceRoot":"","sources":["../src/gc.ts"],"names":[],"mappings":"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"}