@cloudbitmaps/roaring 0.8.1 → 0.9.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { bulkLoadCrbmGeneration as bulkLoadCrbmGeneration$1, compactSegment as compactSegment$1, runCompactionCycle as runCompactionCycle$1, runExport as runExport$1, CodecBitmap, CodecInterface, BudgetOption, IColdDriver, ColdChunkSource, IWarmDriver, IRegistryDriver, IKeystore, Clock, Rng, RetryPolicy, IMetricsSink, SegmentEngine, SegmentRef, PricingProfile, Workload, Topology, CostReport, IAuditSink, CompactionOptions, CompactionResult, DropResult, ConsistencyReport, ExportSink, ExportOptions, ExportManifest, EstimateInput } from '@cloudbitmaps/core';
+import { bulkLoadCrbmGeneration as bulkLoadCrbmGeneration$1, compactSegment as compactSegment$1, runCompactionCycle as runCompactionCycle$1, runExport as runExport$1, CodecBitmap, CodecInterface, BudgetOption, IColdDriver, ColdChunkSource, IWarmDriver, IRegistryDriver, IKeystore, Clock, Rng, RetryPolicy, IMetricsSink, SegmentEngine, SegmentRef, PricingProfile, Workload, Topology, CostReport, IAuditSink, CompactionOptions, CompactionResult, DropResult, RetentionPolicy, SetRetentionResult, RetireExpiredOptions, RetireExpiredResult, ConsistencyReport, ExportSink, ExportOptions, ExportManifest, EstimateInput } from '@cloudbitmaps/core';
 export * from '@cloudbitmaps/core';
 
 /**
@@ -422,7 +422,12 @@ declare class CloudRoaring {
      *
      * **Omitting the namespace addresses a different segment and is a silent no-op** — you get
      * `{ dropped: false, reason: 'absent' }`, not a throw, so a retention loop with that mistake deletes nothing
-     * forever and quietly. Check `reason` in an automated sweep.
+     * forever and quietly. Branch on `dropped`, and treat `reason: 'absent'` as the alert.
+     *
+     * **Works on an accumulator too.** A segment you created by writing to it — never bulk-loaded, never compacted,
+     * so it has no registry row and no Cold objects — is retired by deleting its Warm rows alone. That reports
+     * `{ dropped: true, reason: 'warm-only' }`: there is no tombstone to write, and deliberately none is written,
+     * because a `destroyed` row per retired daily bucket would be registry litter. The data really is gone.
      *
      * **Inspect `generationsRemaining`.** Empty is the normal outcome; non-empty means the storage was NOT fully
      * reclaimed and the drop should be re-run. A compaction that was already in flight when the tombstone landed
@@ -443,6 +448,98 @@ declare class CloudRoaring {
         dryRun?: boolean;
         audit?: IAuditSink;
     }): Promise<DropResult>;
+    /**
+     * **Record when this segment becomes eligible for retirement.** One registry write; nothing is deleted here,
+     * and nothing starts running. `retireExpired` is what acts on the policy, and **you** decide when that runs —
+     * an EventBridge rule, a CronJob, a queue consumer, whatever your deployment already has. This library starts
+     * no background thread (it has to work identically in a Lambda, an edge isolate and a long-lived server).
+     *
+     * `expiresAt` is an **absolute epoch-ms you compute**, not a duration the library derives. A relative TTL would
+     * have to be anchored to something the library knows — `updatedAt`, or the current generation — and compaction
+     * rewrites both, so "expire 30 days after the last write" would keep a busy daily bucket alive forever
+     * precisely because the daemon is working.
+     *
+     * ```ts
+     * const DAY = 86_400_000;
+     * const ref = { namespace: 'active-daily', segment: '2026-08-05' };
+     * await store.setRetention(ref, { expiresAt: Date.now() + 30 * DAY });
+     * ```
+     *
+     * **Works on an accumulator**, which is the whole point: a segment you created by writing to it has no
+     * registry row, so it is invisible to `registry.list()` and therefore to every fleet-wide operation, including
+     * the sweep. This call mints the row (`createdRow: true` in the result) with **no Cold generation**, so it
+     * becomes enumerable while every read still resolves exactly as before.
+     *
+     * A value in the past is legal and means "eligible on the next sweep" — backfilling a policy onto existing
+     * buckets is normal. A value below `MIN_EXPIRES_AT_MS` (2001-09-09) is rejected: it is almost certainly epoch
+     * **seconds**, which would read as long-expired and retire the segment on the next pass. Needs a `registry`
+     * in the store config (throws {@link UnsupportedError} otherwise), and refuses a crypto-shredded segment.
+     */
+    setRetention(ref: SegmentRef, policy: RetentionPolicy): Promise<SetRetentionResult>;
+    /**
+     * **The stored retention policy**, or `null` if the segment has none (or has no registry row, or is a
+     * tombstone). Returns the string `'invalid'` for a row whose `expiresAt` is present but unusable — a
+     * hand-edited row, or one from a restore — so a malformed policy is visible rather than silently reading as
+     * "never expires" on a segment someone believes is expiring.
+     */
+    getRetention(ref: SegmentRef): Promise<RetentionPolicy | null | 'invalid'>;
+    /**
+     * **Cancel a segment's expiry** so no sweep retires it. Returns whether a policy was actually removed (`false`
+     * when there was none). A separate verb from `setRetention` on purpose: "never expire" as a magic value passed
+     * to the setter is how a typo becomes a deletion.
+     */
+    clearRetention(ref: SegmentRef): Promise<boolean>;
+    /**
+     * **Run the retention sweep: retire every segment whose `expiresAt` has passed.** This is the call that acts on
+     * the policies `setRetention` records — and it is a **call, not a daemon**. Nothing schedules it; you run it from
+     * whatever heartbeat your deployment already has (an EventBridge rule, a Kubernetes CronJob, a queue consumer,
+     * your compaction worker's loop). A library that started a timer would behave differently in a Lambda, an edge
+     * isolate and a long-lived server, which is worse than not having one.
+     *
+     * Each retirement goes through `dropSegment`, so the Warm → registry → Cold ordering, the re-sweep for a
+     * generation staged by an in-flight compaction, and the `generationsRemaining` report all come from one
+     * implementation rather than two.
+     *
+     * ```ts
+     * // In your scheduled handler. Start with a preview in a new deployment.
+     * const preview = await store.retireExpired({ namespace: 'active-daily', dryRun: true });
+     * console.log(`would retire ${preview.retired} of ${preview.scanned} (limited: ${preview.limited})`);
+     *
+     * const swept = await store.retireExpired({ namespace: 'active-daily' });
+     * for (const e of swept.entries) {
+     *   if (e.action === 'skipped') console.warn(`${e.segment}: ${e.reason}`); // invalid-policy / limit / failed: …
+     *   if (e.action === 'retired' && e.result.generationsRemaining.length > 0) {
+     *     console.warn(`${e.segment}: storage not fully reclaimed — re-run`);
+     *   }
+     * }
+     * if (swept.limited) scheduleAnotherPassSoon(); // more are still eligible
+     * ```
+     *
+     * **Read the ledger.** A per-segment *fault* is an entry, not an exception — a throw from the middle of a fleet
+     * sweep would leave the caller unable to say which segments were retired, having already retired some. (A bad
+     * argument does throw, and so does a fleet larger than `maxScanSegments`.) `limited: true` means the per-cycle
+     * `limit` (default 100) cut the pass short and more are eligible. That cap is charged on **attempts**, not
+     * successes, which is what makes it a real bound: `dropSegment` deletes Warm and writes the tombstone before
+     * sweeping Cold, so a fault in the Cold phase is a segment that is already retired. Retirements are sequential
+     * (~8 round trips each), so `limit` is a wall-clock knob too, and `retired` counts deletions only — a dry run
+     * reports `wouldRetire` instead, so a dashboard summing `retired` can never show a phantom deletion.
+     *
+     * It also **deletes the tombstone rows its own past retirements left**, after `tombstoneGraceMs` (default 24 h)
+     * and only once that segment's Warm rows and Cold generations are provably gone — collecting a straggler
+     * generation itself first, since nothing else ever would for a tombstoned segment. Attribution is a **positive
+     * marker the sweep stamps on its own retirements**, not an inference from "destroyed + an expired policy": a
+     * crypto-shred leaves `retention` untouched, so setting a policy and then honouring a right-to-erasure request
+     * mid-window produces exactly that row, and deleting it would destroy the Art. 17 attestation and un-fence the
+     * name. Pass `purgeTombstones: false` to keep every tombstone.
+     *
+     * Needs the store built with a **raw cold driver + a registry** (throws {@link UnsupportedError} otherwise),
+     * because retiring a segment deletes its Cold objects. `now` defaults to the store's clock.
+     */
+    retireExpired(options?: Omit<RetireExpiredOptions, 'now'> & {
+        now?: number;
+    }): Promise<RetireExpiredResult>;
+    /** The store's registry, or a typed error naming the operation that needs one. */
+    private requireRegistry;
     /**
      * **Cross-tier DR consistency check (audit gap #11).** After a restore/failover, verify every registered
      * segment's `currentGen` actually has its `.crbm` present in Cold — catching a **torn restore** where the
@@ -632,6 +729,6 @@ declare class Segment {
 }
 
 /** Package version marker. Kept in sync with package.json at release. */
-declare const VERSION = "0.8.1";
+declare const VERSION = "0.9.0";
 
 export { type BaseCombineOptions, CloudRoaring, type CloudRoaringOptions, type CombineIntoOptions, type CombineOptions, type EraseSubjectResult, SafeBitmap, Segment, type SegmentOptions, type SubjectErasureEntry, type SubjectReport, type SubjectSegmentRef, VERSION, bulkLoadCrbmGeneration, compactSegment, roaringCodec, runCompactionCycle, runExport };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { IntegrityError, bulkLoadCrbmGeneration as bulkLoadCrbmGeneration$1, compactSegment as compactSegment$1, runCompactionCycle as runCompactionCycle$1, runExport as runExport$1, safeMetrics, NOOP_METRICS, BoundedLru, RetryingWarmDriver, RetryingColdChunkSource, ValidationError, resolveBudget, DEFAULT_BUDGET, SegmentEngine, UnsupportedError, validateSegmentRef, resolvePerOpBudget, splitId, collectWithinBudget, mapWithConcurrency, validateCompactionOptions, gcOrphanGenerations, dropSegment, runConsistencyCheck, estimateCost, groundedReport, CrbmColdChunkSource } from '@cloudbitmaps/core';
+import { IntegrityError, bulkLoadCrbmGeneration as bulkLoadCrbmGeneration$1, compactSegment as compactSegment$1, runCompactionCycle as runCompactionCycle$1, runExport as runExport$1, safeMetrics, NOOP_METRICS, BoundedLru, RetryingWarmDriver, RetryingColdChunkSource, ValidationError, resolveBudget, DEFAULT_BUDGET, SegmentEngine, UnsupportedError, validateSegmentRef, resolvePerOpBudget, splitId, collectWithinBudget, mapWithConcurrency, validateCompactionOptions, gcOrphanGenerations, dropSegment, setSegmentRetention, getSegmentRetention, clearSegmentRetention, retireExpired, runConsistencyCheck, estimateCost, groundedReport, CrbmColdChunkSource } from '@cloudbitmaps/core';
 export * from '@cloudbitmaps/core';
 import roaring from 'roaring';
 
@@ -305,12 +305,12 @@ var CloudRoaring = class {
   compactionDeps() {
     if (this.coldDriver === void 0) {
       throw new UnsupportedError(
-        "compact/dropSegment/eraseSubject/checkConsistency need the store built with a raw cold driver (IColdDriver), not a pre-built ColdChunkSource \u2014 or call the compactSegment/runConsistencyCheck free functions with explicit deps"
+        "compact/dropSegment/retireExpired/eraseSubject/checkConsistency need the store built with a raw cold driver (IColdDriver), not a pre-built ColdChunkSource \u2014 or call the compactSegment/runConsistencyCheck free functions with explicit deps"
       );
     }
     if (this.registry === void 0) {
       throw new UnsupportedError(
-        "compact/eraseSubject/checkConsistency need a `registry` in the store config"
+        "compact/dropSegment/retireExpired/eraseSubject/checkConsistency need a `registry` in the store config"
       );
     }
     return {
@@ -343,10 +343,7 @@ var CloudRoaring = class {
    * (throws {@link UnsupportedError} otherwise).
    */
   async subjectReport(id, options = {}) {
-    if (this.registry === void 0) {
-      throw new UnsupportedError("subjectReport needs a `registry` in the store config");
-    }
-    const registry = this.registry;
+    const registry = this.requireRegistry("subjectReport");
     requireScope(options, "subjectReport");
     validateConcurrency(options.concurrency);
     const budget = resolvePerOpBudget(options.budget, this.budget);
@@ -496,7 +493,12 @@ var CloudRoaring = class {
    *
    * **Omitting the namespace addresses a different segment and is a silent no-op** — you get
    * `{ dropped: false, reason: 'absent' }`, not a throw, so a retention loop with that mistake deletes nothing
-   * forever and quietly. Check `reason` in an automated sweep.
+   * forever and quietly. Branch on `dropped`, and treat `reason: 'absent'` as the alert.
+   *
+   * **Works on an accumulator too.** A segment you created by writing to it — never bulk-loaded, never compacted,
+   * so it has no registry row and no Cold objects — is retired by deleting its Warm rows alone. That reports
+   * `{ dropped: true, reason: 'warm-only' }`: there is no tombstone to write, and deliberately none is written,
+   * because a `destroyed` row per retired daily bucket would be registry litter. The data really is gone.
    *
    * **Inspect `generationsRemaining`.** Empty is the normal outcome; non-empty means the storage was NOT fully
    * reclaimed and the drop should be re-run. A compaction that was already in flight when the tombstone landed
@@ -517,6 +519,116 @@ var CloudRoaring = class {
     const deps = this.compactionDeps();
     return dropSegment(ref, { registry: deps.registry, warm: deps.warm, cold: deps.cold }, options);
   }
+  /**
+   * **Record when this segment becomes eligible for retirement.** One registry write; nothing is deleted here,
+   * and nothing starts running. `retireExpired` is what acts on the policy, and **you** decide when that runs —
+   * an EventBridge rule, a CronJob, a queue consumer, whatever your deployment already has. This library starts
+   * no background thread (it has to work identically in a Lambda, an edge isolate and a long-lived server).
+   *
+   * `expiresAt` is an **absolute epoch-ms you compute**, not a duration the library derives. A relative TTL would
+   * have to be anchored to something the library knows — `updatedAt`, or the current generation — and compaction
+   * rewrites both, so "expire 30 days after the last write" would keep a busy daily bucket alive forever
+   * precisely because the daemon is working.
+   *
+   * ```ts
+   * const DAY = 86_400_000;
+   * const ref = { namespace: 'active-daily', segment: '2026-08-05' };
+   * await store.setRetention(ref, { expiresAt: Date.now() + 30 * DAY });
+   * ```
+   *
+   * **Works on an accumulator**, which is the whole point: a segment you created by writing to it has no
+   * registry row, so it is invisible to `registry.list()` and therefore to every fleet-wide operation, including
+   * the sweep. This call mints the row (`createdRow: true` in the result) with **no Cold generation**, so it
+   * becomes enumerable while every read still resolves exactly as before.
+   *
+   * A value in the past is legal and means "eligible on the next sweep" — backfilling a policy onto existing
+   * buckets is normal. A value below `MIN_EXPIRES_AT_MS` (2001-09-09) is rejected: it is almost certainly epoch
+   * **seconds**, which would read as long-expired and retire the segment on the next pass. Needs a `registry`
+   * in the store config (throws {@link UnsupportedError} otherwise), and refuses a crypto-shredded segment.
+   */
+  async setRetention(ref, policy) {
+    validateSegmentRef(ref);
+    return setSegmentRetention(ref, { registry: this.requireRegistry("setRetention") }, policy);
+  }
+  /**
+   * **The stored retention policy**, or `null` if the segment has none (or has no registry row, or is a
+   * tombstone). Returns the string `'invalid'` for a row whose `expiresAt` is present but unusable — a
+   * hand-edited row, or one from a restore — so a malformed policy is visible rather than silently reading as
+   * "never expires" on a segment someone believes is expiring.
+   */
+  async getRetention(ref) {
+    validateSegmentRef(ref);
+    return getSegmentRetention(ref, { registry: this.requireRegistry("getRetention") });
+  }
+  /**
+   * **Cancel a segment's expiry** so no sweep retires it. Returns whether a policy was actually removed (`false`
+   * when there was none). A separate verb from `setRetention` on purpose: "never expire" as a magic value passed
+   * to the setter is how a typo becomes a deletion.
+   */
+  async clearRetention(ref) {
+    validateSegmentRef(ref);
+    return clearSegmentRetention(ref, { registry: this.requireRegistry("clearRetention") });
+  }
+  /**
+   * **Run the retention sweep: retire every segment whose `expiresAt` has passed.** This is the call that acts on
+   * the policies `setRetention` records — and it is a **call, not a daemon**. Nothing schedules it; you run it from
+   * whatever heartbeat your deployment already has (an EventBridge rule, a Kubernetes CronJob, a queue consumer,
+   * your compaction worker's loop). A library that started a timer would behave differently in a Lambda, an edge
+   * isolate and a long-lived server, which is worse than not having one.
+   *
+   * Each retirement goes through `dropSegment`, so the Warm → registry → Cold ordering, the re-sweep for a
+   * generation staged by an in-flight compaction, and the `generationsRemaining` report all come from one
+   * implementation rather than two.
+   *
+   * ```ts
+   * // In your scheduled handler. Start with a preview in a new deployment.
+   * const preview = await store.retireExpired({ namespace: 'active-daily', dryRun: true });
+   * console.log(`would retire ${preview.retired} of ${preview.scanned} (limited: ${preview.limited})`);
+   *
+   * const swept = await store.retireExpired({ namespace: 'active-daily' });
+   * for (const e of swept.entries) {
+   *   if (e.action === 'skipped') console.warn(`${e.segment}: ${e.reason}`); // invalid-policy / limit / failed: …
+   *   if (e.action === 'retired' && e.result.generationsRemaining.length > 0) {
+   *     console.warn(`${e.segment}: storage not fully reclaimed — re-run`);
+   *   }
+   * }
+   * if (swept.limited) scheduleAnotherPassSoon(); // more are still eligible
+   * ```
+   *
+   * **Read the ledger.** A per-segment *fault* is an entry, not an exception — a throw from the middle of a fleet
+   * sweep would leave the caller unable to say which segments were retired, having already retired some. (A bad
+   * argument does throw, and so does a fleet larger than `maxScanSegments`.) `limited: true` means the per-cycle
+   * `limit` (default 100) cut the pass short and more are eligible. That cap is charged on **attempts**, not
+   * successes, which is what makes it a real bound: `dropSegment` deletes Warm and writes the tombstone before
+   * sweeping Cold, so a fault in the Cold phase is a segment that is already retired. Retirements are sequential
+   * (~8 round trips each), so `limit` is a wall-clock knob too, and `retired` counts deletions only — a dry run
+   * reports `wouldRetire` instead, so a dashboard summing `retired` can never show a phantom deletion.
+   *
+   * It also **deletes the tombstone rows its own past retirements left**, after `tombstoneGraceMs` (default 24 h)
+   * and only once that segment's Warm rows and Cold generations are provably gone — collecting a straggler
+   * generation itself first, since nothing else ever would for a tombstoned segment. Attribution is a **positive
+   * marker the sweep stamps on its own retirements**, not an inference from "destroyed + an expired policy": a
+   * crypto-shred leaves `retention` untouched, so setting a policy and then honouring a right-to-erasure request
+   * mid-window produces exactly that row, and deleting it would destroy the Art. 17 attestation and un-fence the
+   * name. Pass `purgeTombstones: false` to keep every tombstone.
+   *
+   * Needs the store built with a **raw cold driver + a registry** (throws {@link UnsupportedError} otherwise),
+   * because retiring a segment deletes its Cold objects. `now` defaults to the store's clock.
+   */
+  async retireExpired(options = {}) {
+    const deps = this.compactionDeps();
+    return retireExpired(
+      { registry: deps.registry, warm: deps.warm, cold: deps.cold },
+      { ...options, now: options.now ?? this.clock.now() }
+    );
+  }
+  /** The store's registry, or a typed error naming the operation that needs one. */
+  requireRegistry(op) {
+    if (this.registry === void 0) {
+      throw new UnsupportedError(`${op} needs a \`registry\` in the store config`);
+    }
+    return this.registry;
+  }
   /**
    * **Cross-tier DR consistency check (audit gap #11).** After a restore/failover, verify every registered
    * segment's `currentGen` actually has its `.crbm` present in Cold — catching a **torn restore** where the
@@ -544,10 +656,8 @@ var CloudRoaring = class {
    * exists" means the run finished — check `failed`. The `export-segments` CLI wraps this with a filesystem sink.
    */
   async exportSegments(sink, options = {}) {
-    if (this.registry === void 0) {
-      throw new UnsupportedError("exportSegments needs a `registry` in the store config");
-    }
-    return runExport$1(this, this.registry, sink, {
+    const registry = this.requireRegistry("exportSegments");
+    return runExport$1(this, registry, sink, {
       ...options,
       codec: options.codec ?? roaringCodec
     });
@@ -758,7 +868,7 @@ var Segment = class {
     });
   }
 };
-var VERSION = "0.8.1";
+var VERSION = "0.9.0";
 
 export { CloudRoaring, SafeBitmap, Segment, VERSION, bulkLoadCrbmGeneration, compactSegment, roaringCodec, runCompactionCycle, runExport };
 //# sourceMappingURL=index.js.map