@cloudbitmaps/core 0.8.0 → 0.8.2

package/dist/index.d.cts

@@ -2146,7 +2146,16 @@ interface DropDeps extends EraseDeps {
 interface DropResult {
     readonly segment: string;
     readonly namespace?: string;
-    /** True iff the segment is now a `destroyed` tombstone (incl. the idempotent already-dropped case). */
+    /**
+     * **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.
+     *
+     * It is *not* simply "a tombstone exists", and that distinction is load-bearing. A **pure accumulator**
+     * segment — one created by writing to it and never compacted, so it has no registry row and no Cold objects —
+     * is retired by deleting its Warm rows alone, with no tombstone to write. That reports `dropped: true` with
+     * `reason: 'warm-only'`, because the data really is gone. Reporting it as `false` (which it did until
+     * `0.8.2`) made every successful retirement of an accumulator look like a failure.
+     */
     readonly dropped: boolean;
     /** Warm rows physically deleted. */
     readonly warmRowsDeleted: number;
@@ -2197,11 +2206,19 @@ interface DropResult {
      */
     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.
+     * How the segment got to its current state. Absent on a fresh, ordinary drop (tombstone written, Cold swept).
+     *
+     * - `'warm-only'` — **a successful retirement.** No registry row and no Cold objects, so this was an accumulator
+     *   segment: its Warm rows were deleted and it now reads empty. Pairs with `dropped: true`.
+     * - `'already'` — it was already a tombstone. Idempotent; pairs with `dropped: true`. Note a re-drop is **not**
+     *   a no-op — it also clears Warm rows that landed after the tombstone.
+     * - `'absent'` — **nothing existed.** No registry row, no Cold objects, and no Warm rows to delete. 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.
      *
-     * 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.
+     * Two things `'absent'` used to mean and no longer does: it was returned while the call deleted every Cold
+     * generation it found with no tombstone written (a data-integrity bug, fixed in `0.8.0`), and it was returned
+     * for a successfully retired accumulator segment (misleading, fixed in `0.8.2`).
      */
     readonly reason?: string;
 }

package/dist/index.d.ts

@@ -2146,7 +2146,16 @@ interface DropDeps extends EraseDeps {
 interface DropResult {
     readonly segment: string;
     readonly namespace?: string;
-    /** True iff the segment is now a `destroyed` tombstone (incl. the idempotent already-dropped case). */
+    /**
+     * **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.
+     *
+     * It is *not* simply "a tombstone exists", and that distinction is load-bearing. A **pure accumulator**
+     * segment — one created by writing to it and never compacted, so it has no registry row and no Cold objects —
+     * is retired by deleting its Warm rows alone, with no tombstone to write. That reports `dropped: true` with
+     * `reason: 'warm-only'`, because the data really is gone. Reporting it as `false` (which it did until
+     * `0.8.2`) made every successful retirement of an accumulator look like a failure.
+     */
     readonly dropped: boolean;
     /** Warm rows physically deleted. */
     readonly warmRowsDeleted: number;
@@ -2197,11 +2206,19 @@ interface DropResult {
      */
     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.
+     * How the segment got to its current state. Absent on a fresh, ordinary drop (tombstone written, Cold swept).
+     *
+     * - `'warm-only'` — **a successful retirement.** No registry row and no Cold objects, so this was an accumulator
+     *   segment: its Warm rows were deleted and it now reads empty. Pairs with `dropped: true`.
+     * - `'already'` — it was already a tombstone. Idempotent; pairs with `dropped: true`. Note a re-drop is **not**
+     *   a no-op — it also clears Warm rows that landed after the tombstone.
+     * - `'absent'` — **nothing existed.** No registry row, no Cold objects, and no Warm rows to delete. 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.
      *
-     * 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.
+     * Two things `'absent'` used to mean and no longer does: it was returned while the call deleted every Cold
+     * generation it found with no tombstone written (a data-integrity bug, fixed in `0.8.0`), and it was returned
+     * for a successfully retired accumulator segment (misleading, fixed in `0.8.2`).
      */
     readonly reason?: string;
 }

package/dist/index.js

@@ -3781,14 +3781,15 @@ async function dropSegment(ref, deps, options) {
   if (shred.reason === "absent") {
     const orphans = await listGenerations(deps.cold, ref);
     if (orphans.length === 0) {
+      const clearedWarmOnly = shred.warmRowsDeleted > 0;
       return {
         ...base,
-        dropped: false,
+        dropped: clearedWarmOnly,
         warmRowsDeleted: shred.warmRowsDeleted,
         generationsDeleted: [],
         generationsRemaining: [],
         cryptoShredded: false,
-        reason: "absent"
+        reason: clearedWarmOnly ? "warm-only" : "absent"
       };
     }
     try {