@cloudbitmaps/core 0.8.2 → 0.10.0

package/dist/core/due-index.d.ts

@@ -0,0 +1,55 @@
+import { MAX_NAME_LENGTH } from './validate.js';
+import type { RegistryRecord, SegmentRef } from './ports.js';
+/** Namespace prefix for due-index rows. */
+export declare const DUE_NAMESPACE_PREFIX = "cbm.due.";
+/** Bucket width. One day: small enough that a cycle reads little, coarse enough that the index stays tiny. */
+export declare const DUE_BUCKET_MS = 86400000;
+/**
+ * The name-length cap, and an index row encodes **both** of the original ref's parts into one name — so a ref
+ * whose encoding would exceed it is simply not indexed (see {@link canIndex}).
+ *
+ * Re-exported from the validator rather than restated. The two were separate constants with the same value
+ * until the validator started measuring the **encoded** length; `canIndex` went on counting raw characters and
+ * began answering `true` for refs the registry then refused, turning a documented graceful degradation into a
+ * guaranteed throw on the retention fast path.
+ */
+export { MAX_NAME_LENGTH };
+/** Which bucket an expiry falls in. Total and reversible; no calendar, no timezone, no ambient time. */
+export declare function dueBucket(expiresAt: number): number;
+/** The namespace holding one bucket's pointers. */
+export declare function dueNamespace(bucket: number): string;
+/** Is this record a due-index pointer rather than a segment? */
+export declare function isDueIndexRow(record: Pick<RegistryRecord, 'namespace'>): boolean;
+/**
+ * Encode a ref into one index-row name, unambiguously.
+ *
+ * `${namespaceLength}.${namespace}${segment}` — a decimal length, a dot, then the two parts concatenated. The
+ * length prefix is what makes it reversible: every character the grammar allows (`.`, `-`, `_`, `:`, alphanumerics)
+ * is legal *inside* a name, so no separator character could ever be unambiguous on its own. Reading the digits
+ * up to the first dot tells the parser exactly where the namespace ends.
+ */
+export declare function encodeDueName(ref: SegmentRef): string;
+/**
+ * Can this ref be indexed at all? False when the encoded name would exceed the grammar's 256-character cap —
+ * possible only for a ref whose namespace and segment are together near the limit.
+ *
+ * **Not indexable is not "not retired".** The repair scan still sees the segment's own row, so the consequence
+ * is that it expires on the repair cadence instead of the fast one. Callers must not treat `false` as an error.
+ */
+export declare function canIndex(ref: SegmentRef): boolean;
+/** The registry ref of the pointer for `ref` in `bucket`. Throws if the ref cannot be encoded — check first. */
+export declare function dueIndexRef(bucket: number, ref: SegmentRef): SegmentRef;
+/**
+ * Recover the original ref from an index row's name. `null` for anything we did not write — a foreign row in
+ * the reserved namespace is ignored rather than acted upon.
+ */
+export declare function decodeDueName(name: string): SegmentRef | null;
+/**
+ * Which buckets a cycle must read at `now`: everything from `since` up to and including the current one.
+ *
+ * Past buckets are included because a sweep that did not run — a scaled-to-zero worker, a failed deploy, a
+ * paused schedule — must not leave its buckets stranded. `lookbackBuckets` bounds how far back a first run
+ * reaches, so a long outage costs a bounded number of list calls per cycle rather than one per day since the
+ * epoch; anything older is the repair scan's job.
+ */
+export declare function dueBucketsAt(now: number, lookbackBuckets: number): number[];

package/dist/core/engine.d.ts

@@ -0,0 +1,204 @@
+import type { CodecBitmap, CodecInterface } from './codec.js';
+import type { Budget, BudgetOption } from './budget.js';
+import type { Clock } from './determinism.js';
+import type { BoundedLru } from './lru.js';
+import type { IMetricsSink } from './metrics.js';
+import type { StorageChunkSource, SegmentRef, SegmentSize } from './ports.js';
+export interface EngineDeps {
+    readonly storage: StorageChunkSource;
+    /** Optional cache of decoded (immutable) Storage chunks. */
+    readonly cache?: BoundedLru<string, CodecBitmap>;
+    readonly maxBitmapBytes?: number;
+    /**
+     * The bitmap codec — **required**. `core/` is codec-agnostic: it can have no default, because the concrete codec
+     * lives in a *flavor* package that depends on core (a default here would invert that arrow). A flavor's facade
+     * injects it — `@cloudbitmaps/roaring` passes `roaringCodec` — so applications never see this.
+     */
+    readonly codec: CodecInterface;
+    /** Time source for the `storage.get` latency metric only; defaults to a clock that reads 0. */
+    readonly clock?: Pick<Clock, 'now'>;
+    /** Observability sink; defaults to a no-op. Assumed exception-safe (the facade wraps it). */
+    readonly metrics?: IMetricsSink;
+    /**
+     * Per-op denial-of-wallet budget, already resolved by the facade: a {@link Budget} to enforce, or `null` to
+     * disable. Undefined ⇒ {@link DEFAULT_BUDGET} (a direct engine construction still gets the generous default).
+     * Read ops refuse before fan-out if they'd exceed it.
+     */
+    readonly budget?: Budget | null;
+}
+/** Options common to the chunk-aligned combines. */
+export interface CombineOptions {
+    /** Max chunk keys resolved concurrently — bounds the Storage footprint. A positive integer. */
+    readonly concurrency?: number;
+    /** Override the store's per-op budget for this call (`false` lifts it). */
+    readonly budget?: BudgetOption;
+    /** Segments whose ids are subtracted from the result. */
+    readonly exclude?: readonly SegmentRef[];
+    /**
+     * Allow an operand that names a segment which does not exist. Default `false` — a combine refuses one,
+     * because a misspelled or mis-namespaced operand is indistinguishable from a correct one in the result.
+     * Set `true` when you genuinely intend to combine against a name that may not have been created yet.
+     */
+    readonly allowAbsentOperands?: boolean;
+}
+export declare class SegmentEngine {
+    private readonly storage;
+    private readonly cache;
+    private readonly codec;
+    private readonly maxBitmapBytes;
+    private readonly clock;
+    private readonly metrics;
+    private readonly metricsOn;
+    /** Resolved per-op budget (null = disabled); undefined deps ⇒ the generous default. */
+    private readonly budget;
+    constructor(deps: EngineDeps);
+    /** Membership: one chunk lookup — the cache, else one Storage fetch of that chunk. */
+    has(seg: SegmentRef, id: number): Promise<boolean>;
+    /**
+     * Cardinality. When the Storage source can serve per-chunk cardinality from its `.crbm` index (the `.crbm`
+     * source can), the count is summed from the index with **zero payload reads**. A source without that
+     * capability (the in-memory source) falls back to fetching every chunk.
+     */
+    count(seg: SegmentRef): Promise<number>;
+    /** Whether the Storage source can measure segment size (for grounded cost); false ⇒ storage isn't grounded. */
+    get supportsStorageSize(): boolean;
+    /** Grounded Storage size of a segment's current generation (cost reporting), or null if it has no generation. */
+    segmentSize(seg: SegmentRef): Promise<SegmentSize | null>;
+    /** Every id, ascending, one chunk at a time. */
+    iterate(seg: SegmentRef): AsyncGenerator<number>;
+    /**
+     * `segs[0] ∩ segs[1] ∩ …`, minus every id in `options.exclude` — streamed ascending.
+     *
+     * The `exclude` operands are what make suppression **compose without materialising**. Applying suppression
+     * afterwards (intersect into a temp segment, then subtract) writes an intermediate segment that nobody wants;
+     * applying it here folds it into the same chunk-aligned pass. It is also cheaper than it looks: an exclude
+     * operand is read **only at the keys that survived the intersection** — the cost is bounded by the
+     * audience's surviving key count and **never scales with the size of the suppression list**. Subtracting a
+     * 61,000-chunk global opt-out list costs at most one read per surviving key, not 61,000.
+     *
+     * ---
+     *
+     * Chunk-skipping intersection. Aligns each segment's chunk-key set (read from the `.crbm` index, no payload),
+     * keeps only keys present in **all** operands (a key missing from any operand can't contribute → its Storage
+     * chunks are never fetched — the core saving), then for each surviving key fetches the operands' chunks in
+     * parallel and hands them to the codec for the AND, streaming results through a bounded in-flight window.
+     *
+     * **Memory:** the Storage payload footprint is bounded by the window (`concurrency × operands × chunk`), not by
+     * segment size — that's the Lambda-friendly property.
+     *
+     * Generation-consistent within the call (normal case): each operand's current generation is resolved **once**
+     * up front (before the fan-out) and threaded into every chunk read, so a concurrent load can't corrupt or tear
+     * the result — every chunk read is a whole, checksum-verified, immutable generation. The edge a *long* call can
+     * hit: if it straddles a mid-call `cache.genTtlMs` boundary and a load has published, an operand's not-yet-read
+     * chunks may re-resolve forward to the newer generation (a generation hop within one long call) — the call
+     * never crashes or returns a torn object, but may mix generations. A shorter call is unaffected **unless the
+     * reader cache evicts an operand mid-call** (`maxOpenSegments`): the re-read re-resolves fresh (bypassing the
+     * TTL), which can hop generations even sub-TTL — still whole/immutable per read, never torn.
+     */
+    intersect(segs: readonly SegmentRef[], options?: CombineOptions): AsyncGenerator<number>;
+    /**
+     * `segs[0] ∪ segs[1] ∪ …`, minus every id in `options.exclude` — streamed ascending.
+     *
+     * **Union is the one composite read with no chunk-skipping**, and that is a property of the operation rather
+     * than of this implementation: an id in *any* operand belongs to the result, so every chunk of every operand
+     * has to be read. `intersect` can prune a key absent from any operand; union cannot prune anything. It is
+     * budgeted exactly like `intersect` so a wide union is refused rather than quietly billed.
+     */
+    union(segs: readonly SegmentRef[], options?: CombineOptions): AsyncGenerator<number>;
+    /**
+     * `seg \ (excludes[0] ∪ excludes[1] ∪ …)` — streamed ascending. Suppression on its own.
+     *
+     * Reads every chunk of `seg` (any of them may survive) but each exclude **only where it overlaps `seg`**, so
+     * the cost scales with the segment being filtered rather than with the size of the suppression list.
+     */
+    andNot(seg: SegmentRef, excludes: readonly SegmentRef[], options?: Omit<CombineOptions, 'exclude'>): AsyncGenerator<number>;
+    private combine;
+    /**
+     * The AND (or OR) of one chunk key across all operands, minus the excludes that hold it, or `null` if empty.
+     * Operand chunks are fetched **in parallel** (the spec's parallel byte-range reads).
+     *
+     * The accumulator is a **clone** of the first operand's chunk, and that clone is load-bearing: every other
+     * bitmap here is the cached, shared Storage instance and must never be mutated, or the cache is poisoned for
+     * every later reader. The remaining operands and the excludes are only *read* by the in-place ops, so they are
+     * used as-is — one clone per key, not one per operand.
+     */
+    private combineChunk;
+    /** The segment's chunk keys, ascending — a shape read off the index, no payload. Keys are untrusted (invariant 5). */
+    private chunkKeys;
+    /**
+     * Tier-derived keys are untrusted (invariant 5) — fail fast on a corrupt/out-of-range key rather than
+     * letting it flow into the id-routing step and produce a bogus id.
+     */
+    private assertChunkKeyInRange;
+    /**
+     * The other half of invariant 5: a chunk payload holds **remainders** — 16-bit offsets within one chunk — so
+     * every value must be `<= 0xffff`.
+     *
+     * Nothing upstream establishes that. The byte cap bounds *size*, and CRC/AEAD prove the bytes are the bytes
+     * that were written — which anyone able to write the bucket satisfies trivially. A value `>= 65536` would then
+     * reach the id-routing step, which masks it (`remainder & 0xffff`) and emits a **fabricated id belonging to a different
+     * chunk's id space**: indistinguishable from real data, inflating `count()` and creating spurious `intersect`
+     * matches.
+     *
+     * Costs one `maximum()` per chunk, not per id — `maximum` is optional on the codec seam precisely so a codec
+     * that cannot answer in O(1) opts out instead of making the read path walk every value.
+     */
+    private assertChunkPayloadInRange;
+    /**
+     * Refuse a combine whose operand names a segment that was never created.
+     *
+     * A segment that resolves to nothing is ambiguous in a way that matters only here. Read it directly and
+     * "empty" is the right answer either way. Pass it as an **operand** and the two states diverge: a
+     * suppression list with nobody on it correctly suppresses nothing, while one whose namespace you omitted
+     * *silently* suppresses nothing — and the result is not empty and obviously wrong, it is the full audience
+     * and plausibly right. That direction is the dangerous one: the failure mode is mailing the people who
+     * opted out.
+     *
+     * The asymmetry is why this is checked rather than left to the caller. A mistyped **include** collapses an
+     * intersect to nothing, which you notice; a mistyped **exclude** removes a safeguard, which you do not. Both
+     * are refused, because both are wiring errors and one rule is easier to trust than two.
+     *
+     * **Costs nothing on a normal combine.** `exists` is consulted only for an operand that resolved to zero
+     * chunks — a segment with data is self-evidently registered — so the check is a registry read exactly when
+     * a combine was about to do something suspicious, and no reads at all otherwise. A source that cannot answer
+     * `exists` (it has no notion of registration) skips the check rather than guessing.
+     */
+    private refuseAbsentOperands;
+    /**
+     * Drop every piece of state this engine derived from `ref`, and tell the Storage source to do the same.
+     *
+     * The decoded-chunk cache is keyed by generation, which handles a *publish* (the new generation misses) but
+     * not a *destruction*: a segment that was erased from, dropped, shredded or retired has no newer generation
+     * whose key would miss, so its decoded chunks stay resident and keep answering. That is why the erasing
+     * process itself could report `erased: true` and then still answer `true` for the same id, out of RAM, with
+     * no storage read to intercept.
+     *
+     * Called by the destructive verbs on the facade. Synchronous and best-effort — forgetting cannot fail.
+     */
+    invalidate(ref: SegmentRef): void;
+    /** The segment's current generation, resolved once per op (`undefined` ⇒ source can't report it). */
+    private currentGen;
+    /**
+     * The cache-key component identifying **which bytes** this op will read: the source's `currentVersion` when
+     * it has one, else the generation alone.
+     *
+     * The generation alone is not an identity. `nextGeneration` restarts at 0 once a row is purged and the
+     * bucket emptied, so a retired-and-re-created name serves different data at the same `currentGen` — and a
+     * decoded chunk cached under `(segment, chunk, 0)` is handed straight back to the new incarnation. That is an
+     * erased id reappearing with no read to intercept it, which is why this is keyed on the version rather than
+     * the number.
+     */
+    private cacheVersion;
+    /**
+     * Decode a Storage chunk. `gen` is the segment's current generation, resolved **once per op** by the caller (not
+     * per chunk — that would put a registry re-resolve on every chunk of a count/intersect). The cache is
+     * keyed by it, so a load that advances the generation misses the cache and re-reads the new bytes instead of
+     * serving a stale decoded chunk (an erased id can't resurrect from a cached superseded chunk). `gen === null`
+     * ⇒ the source reports no current generation ⇒ no storage bytes for any chunk, so skip the fetch entirely.
+     * `gen === undefined` ⇒ the source can't report a generation (pins one for its lifetime) ⇒ the key stays
+     * generation-free. Superseded-generation entries age out under the LRU ceiling — no active purge.
+     *
+     * The returned instance is **shared** (it may be the cached one): callers read it or clone it, never mutate it.
+     */
+    private storageChunk;
+}

package/dist/core/erase-id.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Subject erasure on a loaded segment (GDPR Art. 17): remove **one id** from a segment by rewriting its current
+ * generation without that id.
+ *
+ * There is no per-id delete on an immutable object, and there is no mutable tier to hold a tombstone, so erasure
+ * is what every other write in this library is: a new generation. The current generation is streamed chunk by
+ * chunk through the ascending writer — every chunk copied through, the one chunk holding the id re-encoded with
+ * that bit cleared — then published fenced on the generation it streamed, and that generation is collected immediately
+ * (`keep: 0`), so the bit is **physically gone from the bucket when this returns**. Constant memory: one chunk in
+ * flight, never the whole segment.
+ *
+ * What it does NOT reach: backups, replicas and noncurrent object versions hold the old object until their own
+ * lifecycle removes it. For an at-rest guarantee that survives those, use encryption plus crypto-shred
+ * (`destroySegment`), which is per segment — a per-id shred is infeasible because one DEK covers the whole segment.
+ *
+ * Concurrency. This is a **read-modify-write**, not a plain forward-only publish, and that distinction is where
+ * its correctness lives: the new generation is `from` minus one bit, so it is a valid successor to `from` and to
+ * nothing else. The publish is therefore fenced on `from` **and on the row it was read from**
+ * (`publishGeneration`'s `expectFrom` + `expectToken`) and lands only while the pointer is still exactly there,
+ * on that same row. Both halves are needed: a generation number identifies a generation only within one
+ * incarnation of a name, and a name that is retired and re-created restarts at `0`, so the number alone matched
+ * a different segment entirely. Anything else — a load that published in the meantime, or another
+ * erasure that got there first — is reported as `reason: 'superseded'`, `erased: false`, and the caller re-runs
+ * against the new generation. A writer that claims the same generation *number* first surfaces as a
+ * `WriteConflictError` (write-once).
+ *
+ * The same answer covers the read half, and for the same reason. An erasure collects with `keep: 0`, which takes
+ * every generation below its new pointer — so a racing erasure can delete the generation this call is streaming,
+ * and (once it is below the winner's pointer) the object this call just wrote. All three exposed round trips (the
+ * reader open, any chunk of the whole-segment rewrite, the verify) therefore report a *reason* rather than a bare
+ * `NotFoundError`, which was the same event wearing an unactionable face: through `eraseSubject` it became a note
+ * the facade documents as ambiguous about which side of the publish it landed on, telling an operator to triage
+ * where the truth was to re-run.
+ *
+ * Which reason comes from **re-reading the row**, not from assuming a supersession: a moved pointer is
+ * `'superseded'`, a tombstoned row `'destroyed'`, a purged row `'absent'`, a row with no pointer
+ * `'no-generation'`. A pointer still on `from` means the object it names is genuinely gone — the forbidden
+ * `missing-storage-generation` state — and that throws, because no re-run fixes it. That `NotFoundError` is the only
+ * signal of that state, so a faulting re-read rethrows it rather than replacing it with a transient-looking
+ * registry error.
+ *
+ * **No orphan is left behind by a refused rewrite**, and it is worth saying why, because nothing else collects
+ * above the pointer: `putImmutable` commits atomically, so a rewrite whose stream throws leaves no object at all;
+ * and if the write did complete, the winner's generation is necessarily higher, which puts ours below its pointer
+ * where its `keep: 0` takes it. The two orderings are mutually exclusive.
+ *
+ * Without that fence the failure was silent and severe, and both halves were reproduced: `nextGeneration` picks a
+ * number above everything in the bucket, so a forward-only publish here always won — discarding a concurrent
+ * load's whole set, and letting two concurrent erasures each return `erased: true` while the second one's
+ * generation put the first one's id back and collected the generation that had evidenced its removal. A false
+ * Art. 17 receipt is the worst output this module can produce.
+ *
+ * Readers pinned to the collected generation re-resolve on their next read; that is the documented cost of
+ * physical deletion on return. **Do not re-load the id while erasing it**: a load that lands after this rewrite
+ * carries whatever its source held, and the library cannot know that source was meant to exclude the id.
+ */
+import { type IAuditSink } from './audit.js';
+import type { CodecInterface } from './codec.js';
+import type { Yielder } from './cooperative.js';
+import type { IKeystore } from './crypto.js';
+import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
+/** What {@link eraseIdFromSegment} needs: the objects, the pointer, the codec, and the key material if encrypted. */
+export interface EraseIdDeps {
+    readonly storage: IStorageDriver;
+    readonly registry: IRegistryDriver;
+    /**
+     * Bitmap codec — the rewrite decodes and re-encodes every chunk through it. Optional in the type so this stays
+     * call-compatible public API; a **flavor** package binds it (see {@link requireCodec}).
+     */
+    readonly codec?: CodecInterface;
+    /**
+     * Keystore for an **encrypted** segment: its registry record carries wrapped DEK(s), and the rewrite reuses
+     * that DEK — unwrapping it to decrypt the old generation and encrypt the new one under a `(segment, generation)`
+     * -bound AAD. Rewriting an encrypted segment without a keystore throws {@link KeyUnavailableError}.
+     */
+    readonly keystore?: IKeystore;
+    /** When true, refuse to rewrite a **cleartext** segment (the same guard the read path and bulk-load offer). */
+    readonly requireEncryption?: boolean;
+    /** Supplying a clock that can yield makes the rewrite cooperative — see `bulkLoadCrbmGeneration`. */
+    readonly clock?: Yielder;
+    /** Per-chunk decode ceiling (invariant 5); defaults to 1 MiB. */
+    readonly maxBitmapBytes?: number;
+}
+export interface EraseIdResult {
+    readonly segment: string;
+    readonly namespace?: string;
+    /**
+     * True iff the id **was** a member and a generation without it is now the segment's current generation — and
+     * the generation that held it has been deleted (see `collected`). This is the field an erasure ledger records.
+     */
+    readonly erased: boolean;
+    /**
+     * Why nothing was rewritten, when `erased` is false. `'absent'` (no registry row), `'destroyed'` (a crypto-shred
+     * tombstone — already unreadable), `'no-generation'` (a row with no Storage data yet), `'not-member'` (the id is not
+     * in the current generation — the common case across a fleet scan), or `'superseded'`.
+     *
+     * **`'superseded'` means this call did not erase the id, not that the id is still there.** Another writer — a
+     * load, or another erasure — moved the pointer off the generation this rewrite was derived from, so the
+     * rewrite is not a valid successor to what is now current. Re-run against the new generation: if the id is
+     * still present it is erased then; if the racing writer was another erasure of the *same* id, the re-run
+     * reports `'not-member'` because it is already gone. Either way the re-run settles it, which is why it is the
+     * documented action for this reason and for no other.
+     *
+     * The first four reasons are also returned when the row changes *underneath* a rewrite already in flight,
+     * not only when it is read up front — a concurrent `dropSegment` gives `'destroyed'`, a retention sweep that
+     * purges the row gives `'absent'`. A caller branching on `reason` never has to care which it was.
+     */
+    readonly reason?: 'absent' | 'destroyed' | 'no-generation' | 'not-member' | 'superseded';
+    /** The generation the id was found in (present whenever it was read). */
+    readonly fromGeneration?: number;
+    /** The generation written without the id (present whenever one was written, even if `superseded`). */
+    readonly generation?: number;
+    /**
+     * Generations deleted after the publish — normally `[fromGeneration]`, plus any older orphans. Empty when nothing
+     * was rewritten. **It is what THIS call deleted, not the proof that the id is gone** — those differ: a
+     * concurrent collector can take the generation holding the id first, and then `erased: true` is returned with
+     * `collected` empty, because the claim is about the bucket rather than about who emptied it. Treat a
+     * non-empty `collected` as evidence and an empty one as "someone else got there", never as a failure.
+     *
+     * A call that cannot establish the claim **throws** rather than report `erased: true` over bytes that are
+     * still there. Three ways that happens: a Storage `delete` fault, a collection pass that could not prove the
+     * segment was still the same one (`WriteConflictError`, which an ordinary retirement landing mid-call is
+     * enough to cause), and the same refusal on the collect-only path below, where nothing was published at all.
+     *
+     * **Re-run it**, and read what the re-run says rather than assuming it finished the job. The pointer has
+     * moved, so the re-run looks for the id in the *superseded* generations as well as the current one, and there
+     * are three outcomes:
+     *
+     *  - `erased: true` naming the superseded generation it found the id in and collected — the ordinary case,
+     *    and the one that gives you the receipt the failed call could not;
+     *  - `'not-member'` — a racing collector took that generation first. The bit is gone, but **no run reports a
+     *    receipt for it**, so keep the failed call's error alongside your ledger if you need the audit trail;
+     *  - `'absent'` — the segment's registry row is gone, so it is no longer a segment at all and
+     *    `store.eraseSubject` will not even scan it. Anything left in the bucket is an **orphan**: find it with
+     *    `checkConsistency()` and collect it with `gcOrphanGenerations`.
+     */
+    readonly collected: readonly number[];
+}
+export declare function eraseIdFromSegment(ref: SegmentRef, id: number, deps: EraseIdDeps, options?: {
+    audit?: IAuditSink;
+}): Promise<EraseIdResult>;

package/dist/core/erasure.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Whole-segment erasure: crypto-shred (`destroySegment`, `eraseNamespace`) and disposal (`dropSegment`).
+ *
+ * GDPR "right to erasure" on immutable, backed-up storage: you can't delete a `.crbm` object from every
+ * backup, but you can **delete its key**. `destroySegment` drops the segment's wrapped DEK(s) from the registry
+ * (a CAS to a `destroyed` tombstone) — the encrypted Storage bytes are then permanently unreadable, everywhere,
+ * forever. **Immediate + irreversible**, so it's gated behind an explicit confirmation (name the exact
+ * segment/namespace). A `destroyed` segment reads as empty (its DEK is gone). Only works on an **encrypted**
+ * segment; a cleartext segment has no key to shred.
+ *
+ * The tombstone is also the fence every writer respects: `publishGeneration` and `bulkLoadCrbmGeneration` refuse
+ * a `destroyed` row, so a load racing an erasure cannot resurrect the segment. A single id's erasure is a different
+ * operation — `eraseIdFromSegment` rewrites the generation without it.
+ */
+import { type IAuditSink } from './audit.js';
+import type { IStorageDriver, IRegistryDriver, SegmentRef } from './ports.js';
+export interface EraseDeps {
+    readonly registry: IRegistryDriver;
+}
+export interface DestroyResult {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** True iff the segment is now a `destroyed` tombstone (incl. the idempotent already-destroyed case). */
+    readonly destroyed: boolean;
+    /**
+     * True iff **this call** performed a genuine crypto-shred — an encrypted segment whose wrapped DEK(s) were
+     * dropped, so its Storage bytes are now permanently unreadable. False for a cleartext tombstone (bytes remain
+     * readable), for the idempotent already-destroyed case, and for an absent segment. This is what the
+     * `segment.erase` audit event keys off — a cleartext "erase" is not an irreversible destruction.
+     */
+    readonly cryptoShredded: boolean;
+    /**
+     * Why this segment was not a fresh crypto-shred. `'absent'` (no registry row), `'already'` (already
+     * destroyed), `'cleartext'` (no DEK to shred) — and from `eraseNamespace` only, where per-segment faults are
+     * isolated so one failure cannot discard the ledger: `'contended'` (the row was rewritten during every CAS
+     * attempt) or `` `failed: <message>` `` (any other fault).
+     *
+     * The last two come with `destroyed: false` and mean **the segment still holds data**. A namespace erase
+     * returns them rather than throwing, so its entries have to be inspected — see {@link eraseNamespace}.
+     */
+    readonly reason?: string;
+}
+/**
+ * Crypto-shred one segment. **Irreversible.** `confirmSegment` must equal `ref.segment` (a guard against an
+ * accidental destroy — you must name the exact segment). A non-encrypted segment is rejected unless you opt in
+ * via `allowCleartext` (there's no key to shred; its Storage bytes stay readable — the tombstone only stops the
+ * segment resolving).
+ */
+export declare function destroySegment(ref: SegmentRef, deps: EraseDeps, options: {
+    confirmSegment: string;
+    allowCleartext?: boolean;
+    audit?: IAuditSink;
+}): Promise<DestroyResult>;
+/**
+ * Crypto-shred every segment in a namespace. **Irreversible.** `confirmNamespace` must equal `namespace`.
+ * Returns a per-segment result (skips cleartext segments unless `allowCleartext`).
+ */
+export declare function eraseNamespace(namespace: string, deps: EraseDeps, options: {
+    confirmNamespace: string;
+    allowCleartext?: boolean;
+    audit?: IAuditSink;
+}): Promise<{
+    destroyed: DestroyResult[];
+}>;
+/**
+ * Deps for {@link dropSegment}. Adds `storage`, because unlike a crypto-shred this one deletes the objects.
+ */
+export interface DropDeps extends EraseDeps {
+    readonly storage: IStorageDriver;
+}
+export interface DropResult {
+    readonly segment: string;
+    readonly namespace?: string;
+    /**
+     * **True iff this segment is now empty as a result of this call — or already was.** This is the field a
+     * retention job should branch on: `false` means the call found nothing to do and your ref is probably wrong.
+     */
+    readonly dropped: boolean;
+    /** Storage generations physically deleted, ascending. Empty on a dry run — see {@link DropResult.wouldDelete}. */
+    readonly generationsDeleted: readonly number[];
+    /**
+     * Generations still present in Storage when the sweep gave up, ascending. **Empty is the normal outcome** — a
+     * non-empty value means the storage was NOT fully reclaimed and the drop should be re-run.
+     *
+     * This field exists because its absence was a defect. A drop used to return `dropped: true` with a populated
+     * `generationsDeleted` and no `reason` even when an object holding the **complete set** had just been left in
+     * the bucket by a writer that was already mid-write when the tombstone landed (its publish is refused, but the
+     * object survives). For a cleartext segment those bytes are readable — and `gcOrphanGenerations` only collects
+     * a destroyed segment's generations when something runs it. The result was indistinguishable from a clean
+     * drop, so an operator got no signal to re-run. Now they do.
+     */
+    readonly generationsRemaining: readonly number[];
+    /**
+     * On a dry run, the generations that **would** be deleted. `undefined` on a real run.
+     *
+     * This exists because the confirmation guard the erasure calls use — naming the segment twice — protects a
+     * hand-typed literal and nothing else. In the loop this operation is actually *for*
+     * (`for (const day of expired) drop({segment: day}, {confirmSegment: day})`) the same variable appears twice
+     * and the guard is pure ceremony. A dry run is the guard that still works when a machine is calling.
+     *
+     * It is a **snapshot**: a later real run can see a different set.
+     */
+    readonly wouldDelete?: readonly number[];
+    /**
+     * On a dry run, whether the real drop would **also** crypto-shred (i.e. the segment is encrypted).
+     * `undefined` on a real run. This is the one fact in the preview that is irreversible *everywhere*, backups
+     * included — a dry run that did not surface it was previewing the recoverable half only.
+     */
+    readonly wouldCryptoShred?: boolean;
+    /**
+     * True iff the segment was encrypted and its wrapped DEK(s) were dropped as part of this call — so its bytes
+     * are unreadable *everywhere*, backups included, not merely deleted from the bucket. Deleting an object does
+     * not reach a noncurrent version, a replica, or a PITR snapshot; discarding the key does.
+     */
+    readonly cryptoShredded: boolean;
+    /**
+     * How the segment got to its current state. Absent on a fresh, ordinary drop (tombstone written, Storage swept).
+     *
+     * - `'already'` — it was already a tombstone. Idempotent; pairs with `dropped: true`. A re-drop is **not** a
+     *   no-op — it re-sweeps Storage, so it is how a residual in `generationsRemaining` is collected.
+     * - `'absent'` — **nothing existed.** No registry row and no Storage objects. Pairs with `dropped: false`, and it
+     *   is the one value worth alerting on: the usual cause is a mistyped name or an omitted `namespace`, both of
+     *   which address a *different* segment than you meant.
+     */
+    readonly reason?: string;
+}
+/**
+ * **Dispose of a segment: tombstone it, then delete its Storage objects.** Irreversible.
+ *
+ * WHY THIS EXISTS, given {@link destroySegment} already erases. Because `destroySegment` answers a *compliance*
+ * question and this one answers an *operational* question, and they are not the same:
+ *
+ * - `destroySegment` **crypto-shreds** — it discards the key so the bytes are unreadable everywhere including
+ *   immutable backups, which is the only erasure that survives WORM. But it **leaves the objects in the
+ *   bucket**, still billed, and it *requires* encryption because a cleartext segment has no key to discard.
+ * - `dropSegment` **removes the storage**. It works on a cleartext segment, and on an encrypted one it *also*
+ *   drops the DEKs, so it is a strict superset there.
+ *
+ * Before this existed there was no supported way to delete a segment and stop paying for it, and the obvious
+ * workaround — an object-store lifecycle rule on the key prefix — deletes the bytes while the registry still
+ * points at them. That is exactly the `missing-storage-generation` state the DR runbook says not to serve traffic
+ * on, and it surfaces *intermittently*, because a read consults the cache before Storage: cached chunks answer
+ * correctly and evicted ones throw. The whole value of this function is that the ordering below cannot be got
+ * wrong by a caller.
+ *
+ * **THE ORDER IS THE CONTRACT — registry first, then Storage.**
+ *
+ * 1. **Registry first.** After the tombstone nothing resolves a generation for this segment, so no reader can
+ *    reach for bytes that are about to disappear, and no writer can publish onto it (`publishGeneration` and
+ *    `bulkLoadCrbmGeneration` refuse a `destroyed` row).
+ * 2. **Storage second, best-effort, and re-swept.** Once the pointer is a tombstone the segment resolves as empty,
+ *    so a failure part-way through leaves **orphaned bytes, not a wrong answer.** Orphans cost money and are
+ *    cleaned up by re-running; a torn pointer costs correctness and is not self-healing. Given the choice, leak
+ *    bytes — but say so: whatever survives the sweep is reported in {@link DropResult.generationsRemaining}.
+ *
+ * **Why step 2 sweeps more than once.** A load that was already writing its object when the tombstone landed
+ * still finishes the write — its publish is then refused, but the object survives, and it holds the complete
+ * set. A single list-then-delete misses it entirely. The re-sweep converges because the tombstone *is* a hard
+ * fence on **publishing**, so only already-in-flight writes can appear and they are finite.
+ *
+ * **When "reads as empty" starts being true.** Not instantly, for a store that has already read this segment: a
+ * resolved generation is cached and decoded chunks sit in the cache, so an in-flight reader can answer from
+ * cache for a window. A fresh store, or any reader that had not touched the segment, sees empty at once.
+ *
+ * That window is bounded by `cache.genTtlMs` (default 2 s) **only for a reader whose storage source has both a clock
+ * and a registry and a positive TTL** — expiry needs all three. A source built without a clock, or with
+ * `cache.genTtlMs: 0` (documented as "pin forever"), holds its resolved snapshot for its own lifetime; because a
+ * cache-LRU hit never reaches Storage, such a reader can answer `true` for a dropped segment **indefinitely** and must
+ * be restarted. This is the *same* caching that makes the delete-bytes-first ordering fail intermittently rather
+ * than loudly — it cuts both ways.
+ *
+ * `confirmSegment` must equal `ref.segment`, matching `destroySegment`/`eraseNamespace`. For an automated
+ * caller that guard is ceremony — use `dryRun` first, which reports what would go without touching anything.
+ */
+export declare function dropSegment(ref: SegmentRef, deps: DropDeps, options: {
+    confirmSegment: string;
+    dryRun?: boolean;
+    audit?: IAuditSink;
+}): Promise<DropResult>;