@cloudbitmaps/core 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -293,7 +293,7 @@ declare class BoundedLru<K, V> {
  * "Observability" section.
  */
 /** The segment operations that emit an `op` latency event (timed with the injected clock, at the facade). */
-type MetricOpName = 'add' | 'remove' | 'addMany' | 'removeMany' | 'has' | 'count' | 'intersectInto' | 'unionInto' | 'andNotInto';
+type MetricOpName = 'add' | 'remove' | 'addMany' | 'removeMany' | 'claimMany' | 'has' | 'count' | 'intersectInto' | 'unionInto' | 'andNotInto';
 /**
  * One observability event. A discriminated union on `kind` — new variants can be added over time without
  * breaking consumers (they switch on the kinds they care about). `namespace` is the segment's namespace
@@ -634,6 +634,31 @@ declare class SegmentEngine {
     remove(seg: SegmentRef, id: number): Promise<void>;
     addMany(seg: SegmentRef, ids: Iterable<number> | AsyncIterable<number>): Promise<void>;
     removeMany(seg: SegmentRef, ids: Iterable<number> | AsyncIterable<number>): Promise<void>;
+    /**
+     * **Atomically claim ids: add them, and return only the ones that were not already there.**
+     *
+     * The durable analogue of Redis `SETBIT` returning the prior bit — the primitive an exactly-once "have I
+     * already processed / already sent to this id?" check needs. `has()` then `add()` cannot do this: two workers
+     * can both read absent and both proceed.
+     *
+     * **Bulk on purpose.** The per-id shape is the one this library is worst at, because a Warm write rewrites a
+     * whole 64K-id chunk bitmap: claiming 5,000 ids one at a time costs ~5,000 writes and ~23 MB, and claiming
+     * them in one call costs 1 write and ~8 KB. So this takes a batch and does one OCC read-modify-write per
+     * distinct chunk — Redis's semantics at this library's cost shape, rather than Redis's cost shape.
+     *
+     * **Atomicity is per id, which is the guarantee that matters here.** Each id lives in exactly one chunk, and a
+     * chunk is one OCC row, so for any id exactly one concurrent claimer sees it as new. It is NOT atomic across
+     * chunks (neither is `addMany`) — a mid-flight failure can leave some chunks claimed. Re-running is safe:
+     * already-claimed ids simply come back as not-new.
+     *
+     * **The presence test consults Cold, not just the Warm delta.** Checking `adds` alone would report an id as
+     * newly claimed when a compaction had already folded it into a Cold generation — silently breaking
+     * exactly-once on any segment that has ever been compacted. The check is the full effective set,
+     * `(cold ∪ adds) \ removes`.
+     *
+     * Returns the claimed ids grouped nowhere in particular — order is unspecified.
+     */
+    claimMany(seg: SegmentRef, ids: Iterable<number>): Promise<number[]>;
     has(seg: SegmentRef, id: number, opts?: WarmReadOptions): Promise<boolean>;
     count(seg: SegmentRef): Promise<number>;
     /** Whether the Cold source can measure segment size (for grounded cost); false ⇒ storage isn't grounded. */
@@ -1030,6 +1055,28 @@ type AuditEvent = {
     readonly kind: 'segment.erase';
     readonly namespace?: string;
     readonly segment: string;
+} | {
+    /**
+     * A segment was **disposed of** — tombstoned and its storage reclaimed (Warm rows + Cold generations
+     * deleted) by `dropSegment`, *without* a key shred.
+     *
+     * Deliberately a separate kind from {@link AuditEvent} `segment.erase`, and the distinction is the point.
+     * `segment.erase` attests that bytes are unreadable **everywhere, backups included** — the only claim that
+     * survives WORM. Deleting an object is strictly weaker: a noncurrent version, a cross-region replica or a
+     * PITR snapshot can still hold the cleartext. Emitting one kind for both would make a compliance dashboard
+     * over-attest, so a cleartext drop gets this instead.
+     *
+     * An **encrypted** segment dropped via `dropSegment` emits **both** — `segment.erase` for the key shred and
+     * this for the storage reclamation — because both things genuinely happened.
+     *
+     * `generationsDeleted` is how many Cold generations went. It can be 0 (a segment whose bytes were already
+     * gone), and it does not promise the storage is now fully reclaimed: check `DropResult.generationsRemaining`
+     * for that.
+     */
+    readonly kind: 'segment.dispose';
+    readonly namespace?: string;
+    readonly segment: string;
+    readonly generationsDeleted: number;
 } | {
     /** A namespace erasure was executed. `segmentsShredded` is the count actually crypto-shredded (may be 0). */
     readonly kind: 'namespace.erase';
@@ -1178,6 +1225,16 @@ declare function compactSegment(ref: SegmentRef, deps: CompactionDeps, options:
  * Garbage-collect superseded Cold generations for a segment: everything strictly below `currentGen`, keeping
  * the most recent `keep` of them as a grace window for in-flight readers pinned to a just-superseded
  * generation (**I5**). Generations ≥ `currentGen` are never touched. Returns the generations deleted.
+ *
+ * **Except on a `destroyed` segment, where EVERY generation is garbage** and the grace window is meaningless.
+ * A tombstoned segment resolves no generation at all, so no reader is or can become pinned to one; and nothing
+ * else in the library would ever collect them — the reconcile path that deletes generations above `currentGen`
+ * returns early on a destroyed row, so without this those objects are billed forever.
+ *
+ * That state is reachable in practice: a `dropSegment` whose Cold sweep threw part-way, or a compaction that was
+ * already staging when the tombstone landed and finished writing its object afterwards. `dropSegment` re-sweeps
+ * and reports whatever it could not reclaim in `generationsRemaining`, but a drop that was never re-run leaves a
+ * residual, and this is what eventually collects it under a running daemon.
  */
 declare function gcOrphanGenerations(ref: SegmentRef, deps: Pick<CompactionDeps, 'cold' | 'registry'>, options?: {
     keep?: number;
@@ -2080,6 +2137,140 @@ declare function eraseNamespace(namespace: string, deps: EraseDeps, options: {
 }): Promise<{
     destroyed: DestroyResult[];
 }>;
+/**
+ * Deps for {@link dropSegment}. Adds `cold`, because unlike a crypto-shred this one deletes the objects.
+ */
+interface DropDeps extends EraseDeps {
+    readonly cold: IColdDriver;
+}
+interface DropResult {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** True iff the segment is now a `destroyed` tombstone (incl. the idempotent already-dropped case). */
+    readonly dropped: boolean;
+    /** Warm rows physically deleted. */
+    readonly warmRowsDeleted: number;
+    /** Cold generations physically deleted, ascending. Empty on a dry run — see {@link DropResult.wouldDelete}. */
+    readonly generationsDeleted: readonly number[];
+    /**
+     * Generations still present in Cold 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. `dropped: true` with a populated `generationsDeleted`
+     * and no `reason` used to be returned even when a `.crbm` holding the **complete effective set** had just been
+     * left in the bucket by a compaction that was already mid-flight (it stages from data it read before the
+     * tombstone, so its commit fails on the voided lease but its object survives). For a cleartext segment those
+     * bytes are readable — and nothing in the library reclaimed them, because `gcOrphanGenerations` only considers
+     * generations *below* `currentGen` and `checkConsistency` skips destroyed segments. 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, how many Warm rows would be deleted. `undefined` on a real run.
+     *
+     * Previewing only the Cold generations was a gap: Warm rows hold **cleartext** deltas, so for the automated
+     * caller this preview exists for, "how much unencrypted data is about to go" is at least as load-bearing as
+     * the object count.
+     */
+    readonly wouldDeleteWarmRows?: 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;
+    /**
+     * `'absent'` (no registry row **and** no Cold objects — nothing existed to drop) or `'already'` (already a
+     * tombstone). Absent on a fresh drop.
+     *
+     * Note what `'absent'` no longer means: it used to be returned while the call deleted every Cold generation it
+     * found, with no tombstone written. See {@link dropSegment}'s "the absent case" note.
+     */
+    readonly reason?: string;
+}
+/**
+ * **Dispose of a segment: tombstone it, delete its Warm rows, and delete its Cold 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-cold-generation` state the DR runbook says not to serve traffic
+ * on, and it surfaces *intermittently*, because a read consults the hot cache before Cold: 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 — Warm, then registry, then Cold.** Each step is placed against a specific way
+ * the other orders break:
+ *
+ * 1. **Warm first.** A `destroyed` row makes Cold read as empty, but Warm is consulted *separately* and earlier
+ *    on the read path — so a tombstone with live Warm deltas still answers `true` for ids in those deltas.
+ *    (This is why {@link shredSegment} already orders it this way; the reasoning is inherited, not invented.)
+ *    **Necessary, but not sufficient** — see "writes must have stopped" below.
+ * 2. **Registry second.** After the tombstone nothing resolves a generation for this segment, so no reader can
+ *    reach for bytes that are about to disappear.
+ * 3. **Cold last, 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 3 sweeps more than once.** A compaction that was already mid-flight when the tombstone landed will
+ * still finish *staging* a fresh generation, built from data it read beforehand — its commit then fails on the
+ * lease the tombstone voided, but the object it wrote survives, and it holds the complete effective set including
+ * the Warm deltas step 1 just deleted. A single list-then-delete misses it entirely. The re-sweep converges
+ * because the tombstone *is* a hard fence on **starting** a new generation (compaction returns `destroyed`
+ * before it does anything), so only already-in-flight stagings can appear and they are finite.
+ *
+ * **Writes must have stopped.** Nothing here prevents a *new* Warm write after step 1 (the write path is
+ * deliberately uncoupled — see this module's header). For `destroySegment` that is a scope note; here it is
+ * sharper, because a Warm row that lands after the tombstone is **immortal**: compaction refuses to fold or purge
+ * a destroyed segment, so nothing ever reaps it, and a fresh reader will report the dropped segment as non-empty
+ * *forever*. Step 1 therefore runs a second time after the tombstone, which converges for anything in flight at
+ * drop time — but a writer that keeps writing will keep resurrecting the segment. Stop writes first, or re-run.
+ *
+ * **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 hot LRU, 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 `coldGenTtlMs` (default 2 s) **only for a reader whose cold source has both a clock
+ * and a registry and a positive TTL** — expiry needs all three. A source built without a clock, or with
+ * `coldGenTtlMs: 0` (documented as "pin forever"), holds its resolved snapshot for its own lifetime; because a
+ * hot-LRU hit never reaches Cold, 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.
+ */
+declare function dropSegment(ref: SegmentRef, deps: DropDeps, options: {
+    confirmSegment: string;
+    dryRun?: boolean;
+    audit?: IAuditSink;
+}): Promise<DropResult>;
 
 /**
  * Fail-safe cross-tier DR check (gap #11). The registry (`currentGen`, e.g. in
@@ -2324,4 +2515,4 @@ declare class CrbmWriter {
     private buildFooter;
 }
 
-export { AWS_US_EAST_1_ONDEMAND, Aead, AeadSealed, type AuditEvent, type AuditEventKind, BlobReader, BlobSink, BoundedLru, type Budget, BudgetExceededError, type BudgetOption, type BulkLoadResult, CapabilityError, ChunkRef, type Clock, CloudRoaringError, type CodecBitmap, type CodecInterface, ColdCaps, ColdChunkSource, type CompactionCandidate, type CompactionCycleResult, type CompactionDeps, type CompactionOptions, type CompactionResult, type ConsistencyErrorEntry, type ConsistencyIssue, type ConsistencyReport, type CostAdvisory, type CostReport, CountingMetricsSink, CrbmColdChunkSource, type CrbmColdChunkSourceOptions, CrbmCrypto, CrbmReader, type CrbmReaderOptions, CrbmWriter, type CrbmWriterOptions, DEFAULT_BUDGET, DEFAULT_MAX_SCAN_SEGMENTS, DEFAULT_MAX_WARM_SCAN_BYTES, DEFAULT_OCC_BACKOFF, DEFAULT_PRICING, DEFAULT_RETRY_POLICY, DEFAULT_WRITE_CONCURRENCY, type DestroyResult, type DiscoveryOptions, type EngineDeps, type EraseDeps, type EstimateInput, type ExportFailure, type ExportFormat, type ExportManifest, type ExportOptions, type ExportSink, type ExportWriter, type ExportedSegment, GenKey, type IAuditSink, IColdDriver, IKeystore, type IMetricsSink, IRegistryDriver, IWarmDriver, InProcessKeystore, type InProcessKeystoreOptions, IntegrityError, KeyUnavailableError, LocalFsColdDriver, LocalFsRegistryDriver, type LocalFsRegistryDriverOptions, LocalFsWarmDriver, MemoryColdChunkSource, MemoryColdDriver, MemoryRegistryDriver, type MemoryRegistryDriverOptions, MemoryWarmDriver, type MetricEvent, type MetricOpName, type MetricsSnapshot, NOOP_AUDIT, NOOP_METRICS, NewRegistryRecord, NoRow, NodeAead, NotFoundError, type PricingProfile, RecordingAuditSink, RegCaps, RegistryPatch, RegistryRecord, type RetryDeps, type RetryPolicy, RetryingColdChunkSource, RetryingColdDriver, type RetryingOptions, RetryingRegistryDriver, RetryingWarmDriver, type Rng, SegmentEngine, SegmentRef, SegmentSize, type SegmentSizing, TimeoutError, Token, type Topology, TransientError, UnsupportedError, ValidationError, WarmReadOptions, WarmRow, type Workload, WrappedDek, WriteConflictError, bulkLoadCrbmGeneration, checkBudget, chunkRefKey, collectWithinBudget, compactSegment, destroySegment, eraseNamespace, estimateCost, findCompactable, gcOrphanGenerations, groundedReport, isCloudRoaringError, isIntegrityError, isNotFoundError, isTransient, isTransientError, isValidationError, isWriteConflictError, joinId, mapWithConcurrency, publishGeneration, resolveBudget, resolvePerOpBudget, runCompactionCycle, runConsistencyCheck, runExport, safeMetrics, segmentKey, splitId, validateCompactionOptions, validateSegmentRef, withRetry, writeCrbmGeneration };
+export { AWS_US_EAST_1_ONDEMAND, Aead, AeadSealed, type AuditEvent, type AuditEventKind, BlobReader, BlobSink, BoundedLru, type Budget, BudgetExceededError, type BudgetOption, type BulkLoadResult, CapabilityError, ChunkRef, type Clock, CloudRoaringError, type CodecBitmap, type CodecInterface, ColdCaps, ColdChunkSource, type CompactionCandidate, type CompactionCycleResult, type CompactionDeps, type CompactionOptions, type CompactionResult, type ConsistencyErrorEntry, type ConsistencyIssue, type ConsistencyReport, type CostAdvisory, type CostReport, CountingMetricsSink, CrbmColdChunkSource, type CrbmColdChunkSourceOptions, CrbmCrypto, CrbmReader, type CrbmReaderOptions, CrbmWriter, type CrbmWriterOptions, DEFAULT_BUDGET, DEFAULT_MAX_SCAN_SEGMENTS, DEFAULT_MAX_WARM_SCAN_BYTES, DEFAULT_OCC_BACKOFF, DEFAULT_PRICING, DEFAULT_RETRY_POLICY, DEFAULT_WRITE_CONCURRENCY, type DestroyResult, type DiscoveryOptions, type DropDeps, type DropResult, type EngineDeps, type EraseDeps, type EstimateInput, type ExportFailure, type ExportFormat, type ExportManifest, type ExportOptions, type ExportSink, type ExportWriter, type ExportedSegment, GenKey, type IAuditSink, IColdDriver, IKeystore, type IMetricsSink, IRegistryDriver, IWarmDriver, InProcessKeystore, type InProcessKeystoreOptions, IntegrityError, KeyUnavailableError, LocalFsColdDriver, LocalFsRegistryDriver, type LocalFsRegistryDriverOptions, LocalFsWarmDriver, MemoryColdChunkSource, MemoryColdDriver, MemoryRegistryDriver, type MemoryRegistryDriverOptions, MemoryWarmDriver, type MetricEvent, type MetricOpName, type MetricsSnapshot, NOOP_AUDIT, NOOP_METRICS, NewRegistryRecord, NoRow, NodeAead, NotFoundError, type PricingProfile, RecordingAuditSink, RegCaps, RegistryPatch, RegistryRecord, type RetryDeps, type RetryPolicy, RetryingColdChunkSource, RetryingColdDriver, type RetryingOptions, RetryingRegistryDriver, RetryingWarmDriver, type Rng, SegmentEngine, SegmentRef, SegmentSize, type SegmentSizing, TimeoutError, Token, type Topology, TransientError, UnsupportedError, ValidationError, WarmReadOptions, WarmRow, type Workload, WrappedDek, WriteConflictError, bulkLoadCrbmGeneration, checkBudget, chunkRefKey, collectWithinBudget, compactSegment, destroySegment, dropSegment, eraseNamespace, estimateCost, findCompactable, gcOrphanGenerations, groundedReport, isCloudRoaringError, isIntegrityError, isNotFoundError, isTransient, isTransientError, isValidationError, isWriteConflictError, joinId, mapWithConcurrency, publishGeneration, resolveBudget, resolvePerOpBudget, runCompactionCycle, runConsistencyCheck, runExport, safeMetrics, segmentKey, splitId, validateCompactionOptions, validateSegmentRef, withRetry, writeCrbmGeneration };

package/dist/index.d.ts

@@ -293,7 +293,7 @@ declare class BoundedLru<K, V> {
  * "Observability" section.
  */
 /** The segment operations that emit an `op` latency event (timed with the injected clock, at the facade). */
-type MetricOpName = 'add' | 'remove' | 'addMany' | 'removeMany' | 'has' | 'count' | 'intersectInto' | 'unionInto' | 'andNotInto';
+type MetricOpName = 'add' | 'remove' | 'addMany' | 'removeMany' | 'claimMany' | 'has' | 'count' | 'intersectInto' | 'unionInto' | 'andNotInto';
 /**
  * One observability event. A discriminated union on `kind` — new variants can be added over time without
  * breaking consumers (they switch on the kinds they care about). `namespace` is the segment's namespace
@@ -634,6 +634,31 @@ declare class SegmentEngine {
     remove(seg: SegmentRef, id: number): Promise<void>;
     addMany(seg: SegmentRef, ids: Iterable<number> | AsyncIterable<number>): Promise<void>;
     removeMany(seg: SegmentRef, ids: Iterable<number> | AsyncIterable<number>): Promise<void>;
+    /**
+     * **Atomically claim ids: add them, and return only the ones that were not already there.**
+     *
+     * The durable analogue of Redis `SETBIT` returning the prior bit — the primitive an exactly-once "have I
+     * already processed / already sent to this id?" check needs. `has()` then `add()` cannot do this: two workers
+     * can both read absent and both proceed.
+     *
+     * **Bulk on purpose.** The per-id shape is the one this library is worst at, because a Warm write rewrites a
+     * whole 64K-id chunk bitmap: claiming 5,000 ids one at a time costs ~5,000 writes and ~23 MB, and claiming
+     * them in one call costs 1 write and ~8 KB. So this takes a batch and does one OCC read-modify-write per
+     * distinct chunk — Redis's semantics at this library's cost shape, rather than Redis's cost shape.
+     *
+     * **Atomicity is per id, which is the guarantee that matters here.** Each id lives in exactly one chunk, and a
+     * chunk is one OCC row, so for any id exactly one concurrent claimer sees it as new. It is NOT atomic across
+     * chunks (neither is `addMany`) — a mid-flight failure can leave some chunks claimed. Re-running is safe:
+     * already-claimed ids simply come back as not-new.
+     *
+     * **The presence test consults Cold, not just the Warm delta.** Checking `adds` alone would report an id as
+     * newly claimed when a compaction had already folded it into a Cold generation — silently breaking
+     * exactly-once on any segment that has ever been compacted. The check is the full effective set,
+     * `(cold ∪ adds) \ removes`.
+     *
+     * Returns the claimed ids grouped nowhere in particular — order is unspecified.
+     */
+    claimMany(seg: SegmentRef, ids: Iterable<number>): Promise<number[]>;
     has(seg: SegmentRef, id: number, opts?: WarmReadOptions): Promise<boolean>;
     count(seg: SegmentRef): Promise<number>;
     /** Whether the Cold source can measure segment size (for grounded cost); false ⇒ storage isn't grounded. */
@@ -1030,6 +1055,28 @@ type AuditEvent = {
     readonly kind: 'segment.erase';
     readonly namespace?: string;
     readonly segment: string;
+} | {
+    /**
+     * A segment was **disposed of** — tombstoned and its storage reclaimed (Warm rows + Cold generations
+     * deleted) by `dropSegment`, *without* a key shred.
+     *
+     * Deliberately a separate kind from {@link AuditEvent} `segment.erase`, and the distinction is the point.
+     * `segment.erase` attests that bytes are unreadable **everywhere, backups included** — the only claim that
+     * survives WORM. Deleting an object is strictly weaker: a noncurrent version, a cross-region replica or a
+     * PITR snapshot can still hold the cleartext. Emitting one kind for both would make a compliance dashboard
+     * over-attest, so a cleartext drop gets this instead.
+     *
+     * An **encrypted** segment dropped via `dropSegment` emits **both** — `segment.erase` for the key shred and
+     * this for the storage reclamation — because both things genuinely happened.
+     *
+     * `generationsDeleted` is how many Cold generations went. It can be 0 (a segment whose bytes were already
+     * gone), and it does not promise the storage is now fully reclaimed: check `DropResult.generationsRemaining`
+     * for that.
+     */
+    readonly kind: 'segment.dispose';
+    readonly namespace?: string;
+    readonly segment: string;
+    readonly generationsDeleted: number;
 } | {
     /** A namespace erasure was executed. `segmentsShredded` is the count actually crypto-shredded (may be 0). */
     readonly kind: 'namespace.erase';
@@ -1178,6 +1225,16 @@ declare function compactSegment(ref: SegmentRef, deps: CompactionDeps, options:
  * Garbage-collect superseded Cold generations for a segment: everything strictly below `currentGen`, keeping
  * the most recent `keep` of them as a grace window for in-flight readers pinned to a just-superseded
  * generation (**I5**). Generations ≥ `currentGen` are never touched. Returns the generations deleted.
+ *
+ * **Except on a `destroyed` segment, where EVERY generation is garbage** and the grace window is meaningless.
+ * A tombstoned segment resolves no generation at all, so no reader is or can become pinned to one; and nothing
+ * else in the library would ever collect them — the reconcile path that deletes generations above `currentGen`
+ * returns early on a destroyed row, so without this those objects are billed forever.
+ *
+ * That state is reachable in practice: a `dropSegment` whose Cold sweep threw part-way, or a compaction that was
+ * already staging when the tombstone landed and finished writing its object afterwards. `dropSegment` re-sweeps
+ * and reports whatever it could not reclaim in `generationsRemaining`, but a drop that was never re-run leaves a
+ * residual, and this is what eventually collects it under a running daemon.
  */
 declare function gcOrphanGenerations(ref: SegmentRef, deps: Pick<CompactionDeps, 'cold' | 'registry'>, options?: {
     keep?: number;
@@ -2080,6 +2137,140 @@ declare function eraseNamespace(namespace: string, deps: EraseDeps, options: {
 }): Promise<{
     destroyed: DestroyResult[];
 }>;
+/**
+ * Deps for {@link dropSegment}. Adds `cold`, because unlike a crypto-shred this one deletes the objects.
+ */
+interface DropDeps extends EraseDeps {
+    readonly cold: IColdDriver;
+}
+interface DropResult {
+    readonly segment: string;
+    readonly namespace?: string;
+    /** True iff the segment is now a `destroyed` tombstone (incl. the idempotent already-dropped case). */
+    readonly dropped: boolean;
+    /** Warm rows physically deleted. */
+    readonly warmRowsDeleted: number;
+    /** Cold generations physically deleted, ascending. Empty on a dry run — see {@link DropResult.wouldDelete}. */
+    readonly generationsDeleted: readonly number[];
+    /**
+     * Generations still present in Cold 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. `dropped: true` with a populated `generationsDeleted`
+     * and no `reason` used to be returned even when a `.crbm` holding the **complete effective set** had just been
+     * left in the bucket by a compaction that was already mid-flight (it stages from data it read before the
+     * tombstone, so its commit fails on the voided lease but its object survives). For a cleartext segment those
+     * bytes are readable — and nothing in the library reclaimed them, because `gcOrphanGenerations` only considers
+     * generations *below* `currentGen` and `checkConsistency` skips destroyed segments. 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, how many Warm rows would be deleted. `undefined` on a real run.
+     *
+     * Previewing only the Cold generations was a gap: Warm rows hold **cleartext** deltas, so for the automated
+     * caller this preview exists for, "how much unencrypted data is about to go" is at least as load-bearing as
+     * the object count.
+     */
+    readonly wouldDeleteWarmRows?: 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;
+    /**
+     * `'absent'` (no registry row **and** no Cold objects — nothing existed to drop) or `'already'` (already a
+     * tombstone). Absent on a fresh drop.
+     *
+     * Note what `'absent'` no longer means: it used to be returned while the call deleted every Cold generation it
+     * found, with no tombstone written. See {@link dropSegment}'s "the absent case" note.
+     */
+    readonly reason?: string;
+}
+/**
+ * **Dispose of a segment: tombstone it, delete its Warm rows, and delete its Cold 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-cold-generation` state the DR runbook says not to serve traffic
+ * on, and it surfaces *intermittently*, because a read consults the hot cache before Cold: 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 — Warm, then registry, then Cold.** Each step is placed against a specific way
+ * the other orders break:
+ *
+ * 1. **Warm first.** A `destroyed` row makes Cold read as empty, but Warm is consulted *separately* and earlier
+ *    on the read path — so a tombstone with live Warm deltas still answers `true` for ids in those deltas.
+ *    (This is why {@link shredSegment} already orders it this way; the reasoning is inherited, not invented.)
+ *    **Necessary, but not sufficient** — see "writes must have stopped" below.
+ * 2. **Registry second.** After the tombstone nothing resolves a generation for this segment, so no reader can
+ *    reach for bytes that are about to disappear.
+ * 3. **Cold last, 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 3 sweeps more than once.** A compaction that was already mid-flight when the tombstone landed will
+ * still finish *staging* a fresh generation, built from data it read beforehand — its commit then fails on the
+ * lease the tombstone voided, but the object it wrote survives, and it holds the complete effective set including
+ * the Warm deltas step 1 just deleted. A single list-then-delete misses it entirely. The re-sweep converges
+ * because the tombstone *is* a hard fence on **starting** a new generation (compaction returns `destroyed`
+ * before it does anything), so only already-in-flight stagings can appear and they are finite.
+ *
+ * **Writes must have stopped.** Nothing here prevents a *new* Warm write after step 1 (the write path is
+ * deliberately uncoupled — see this module's header). For `destroySegment` that is a scope note; here it is
+ * sharper, because a Warm row that lands after the tombstone is **immortal**: compaction refuses to fold or purge
+ * a destroyed segment, so nothing ever reaps it, and a fresh reader will report the dropped segment as non-empty
+ * *forever*. Step 1 therefore runs a second time after the tombstone, which converges for anything in flight at
+ * drop time — but a writer that keeps writing will keep resurrecting the segment. Stop writes first, or re-run.
+ *
+ * **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 hot LRU, 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 `coldGenTtlMs` (default 2 s) **only for a reader whose cold source has both a clock
+ * and a registry and a positive TTL** — expiry needs all three. A source built without a clock, or with
+ * `coldGenTtlMs: 0` (documented as "pin forever"), holds its resolved snapshot for its own lifetime; because a
+ * hot-LRU hit never reaches Cold, 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.
+ */
+declare function dropSegment(ref: SegmentRef, deps: DropDeps, options: {
+    confirmSegment: string;
+    dryRun?: boolean;
+    audit?: IAuditSink;
+}): Promise<DropResult>;
 
 /**
  * Fail-safe cross-tier DR check (gap #11). The registry (`currentGen`, e.g. in
@@ -2324,4 +2515,4 @@ declare class CrbmWriter {
     private buildFooter;
 }
 
-export { AWS_US_EAST_1_ONDEMAND, Aead, AeadSealed, type AuditEvent, type AuditEventKind, BlobReader, BlobSink, BoundedLru, type Budget, BudgetExceededError, type BudgetOption, type BulkLoadResult, CapabilityError, ChunkRef, type Clock, CloudRoaringError, type CodecBitmap, type CodecInterface, ColdCaps, ColdChunkSource, type CompactionCandidate, type CompactionCycleResult, type CompactionDeps, type CompactionOptions, type CompactionResult, type ConsistencyErrorEntry, type ConsistencyIssue, type ConsistencyReport, type CostAdvisory, type CostReport, CountingMetricsSink, CrbmColdChunkSource, type CrbmColdChunkSourceOptions, CrbmCrypto, CrbmReader, type CrbmReaderOptions, CrbmWriter, type CrbmWriterOptions, DEFAULT_BUDGET, DEFAULT_MAX_SCAN_SEGMENTS, DEFAULT_MAX_WARM_SCAN_BYTES, DEFAULT_OCC_BACKOFF, DEFAULT_PRICING, DEFAULT_RETRY_POLICY, DEFAULT_WRITE_CONCURRENCY, type DestroyResult, type DiscoveryOptions, type EngineDeps, type EraseDeps, type EstimateInput, type ExportFailure, type ExportFormat, type ExportManifest, type ExportOptions, type ExportSink, type ExportWriter, type ExportedSegment, GenKey, type IAuditSink, IColdDriver, IKeystore, type IMetricsSink, IRegistryDriver, IWarmDriver, InProcessKeystore, type InProcessKeystoreOptions, IntegrityError, KeyUnavailableError, LocalFsColdDriver, LocalFsRegistryDriver, type LocalFsRegistryDriverOptions, LocalFsWarmDriver, MemoryColdChunkSource, MemoryColdDriver, MemoryRegistryDriver, type MemoryRegistryDriverOptions, MemoryWarmDriver, type MetricEvent, type MetricOpName, type MetricsSnapshot, NOOP_AUDIT, NOOP_METRICS, NewRegistryRecord, NoRow, NodeAead, NotFoundError, type PricingProfile, RecordingAuditSink, RegCaps, RegistryPatch, RegistryRecord, type RetryDeps, type RetryPolicy, RetryingColdChunkSource, RetryingColdDriver, type RetryingOptions, RetryingRegistryDriver, RetryingWarmDriver, type Rng, SegmentEngine, SegmentRef, SegmentSize, type SegmentSizing, TimeoutError, Token, type Topology, TransientError, UnsupportedError, ValidationError, WarmReadOptions, WarmRow, type Workload, WrappedDek, WriteConflictError, bulkLoadCrbmGeneration, checkBudget, chunkRefKey, collectWithinBudget, compactSegment, destroySegment, eraseNamespace, estimateCost, findCompactable, gcOrphanGenerations, groundedReport, isCloudRoaringError, isIntegrityError, isNotFoundError, isTransient, isTransientError, isValidationError, isWriteConflictError, joinId, mapWithConcurrency, publishGeneration, resolveBudget, resolvePerOpBudget, runCompactionCycle, runConsistencyCheck, runExport, safeMetrics, segmentKey, splitId, validateCompactionOptions, validateSegmentRef, withRetry, writeCrbmGeneration };
+export { AWS_US_EAST_1_ONDEMAND, Aead, AeadSealed, type AuditEvent, type AuditEventKind, BlobReader, BlobSink, BoundedLru, type Budget, BudgetExceededError, type BudgetOption, type BulkLoadResult, CapabilityError, ChunkRef, type Clock, CloudRoaringError, type CodecBitmap, type CodecInterface, ColdCaps, ColdChunkSource, type CompactionCandidate, type CompactionCycleResult, type CompactionDeps, type CompactionOptions, type CompactionResult, type ConsistencyErrorEntry, type ConsistencyIssue, type ConsistencyReport, type CostAdvisory, type CostReport, CountingMetricsSink, CrbmColdChunkSource, type CrbmColdChunkSourceOptions, CrbmCrypto, CrbmReader, type CrbmReaderOptions, CrbmWriter, type CrbmWriterOptions, DEFAULT_BUDGET, DEFAULT_MAX_SCAN_SEGMENTS, DEFAULT_MAX_WARM_SCAN_BYTES, DEFAULT_OCC_BACKOFF, DEFAULT_PRICING, DEFAULT_RETRY_POLICY, DEFAULT_WRITE_CONCURRENCY, type DestroyResult, type DiscoveryOptions, type DropDeps, type DropResult, type EngineDeps, type EraseDeps, type EstimateInput, type ExportFailure, type ExportFormat, type ExportManifest, type ExportOptions, type ExportSink, type ExportWriter, type ExportedSegment, GenKey, type IAuditSink, IColdDriver, IKeystore, type IMetricsSink, IRegistryDriver, IWarmDriver, InProcessKeystore, type InProcessKeystoreOptions, IntegrityError, KeyUnavailableError, LocalFsColdDriver, LocalFsRegistryDriver, type LocalFsRegistryDriverOptions, LocalFsWarmDriver, MemoryColdChunkSource, MemoryColdDriver, MemoryRegistryDriver, type MemoryRegistryDriverOptions, MemoryWarmDriver, type MetricEvent, type MetricOpName, type MetricsSnapshot, NOOP_AUDIT, NOOP_METRICS, NewRegistryRecord, NoRow, NodeAead, NotFoundError, type PricingProfile, RecordingAuditSink, RegCaps, RegistryPatch, RegistryRecord, type RetryDeps, type RetryPolicy, RetryingColdChunkSource, RetryingColdDriver, type RetryingOptions, RetryingRegistryDriver, RetryingWarmDriver, type Rng, SegmentEngine, SegmentRef, SegmentSize, type SegmentSizing, TimeoutError, Token, type Topology, TransientError, UnsupportedError, ValidationError, WarmReadOptions, WarmRow, type Workload, WrappedDek, WriteConflictError, bulkLoadCrbmGeneration, checkBudget, chunkRefKey, collectWithinBudget, compactSegment, destroySegment, dropSegment, eraseNamespace, estimateCost, findCompactable, gcOrphanGenerations, groundedReport, isCloudRoaringError, isIntegrityError, isNotFoundError, isTransient, isTransientError, isValidationError, isWriteConflictError, joinId, mapWithConcurrency, publishGeneration, resolveBudget, resolvePerOpBudget, runCompactionCycle, runConsistencyCheck, runExport, safeMetrics, segmentKey, splitId, validateCompactionOptions, validateSegmentRef, withRetry, writeCrbmGeneration };