@cloudbitmaps/roaring 0.19.1 → 0.20.0

package/PRIVACY.md

@@ -60,7 +60,7 @@ CloudBitmaps gives you three levers with different guarantees. Use them delibera
 
 | Lever | API | Guarantee | Use for |
 |---|---|---|---|
-| **Subject erasure** | `store.eraseSubject(id, { namespace })` | *Physical on return* — the segment's current generation is rewritten without the id (every chunk streamed through, one bit cleared), published **fenced on the generation it streamed**, and **the generation that held the bit is deleted before the call returns**. So is every other generation still holding the id: a retained *superseded* one (an ex-member dropped by a re-seed), and each one above the pointer after a `rollback` — generations a rollback can move the pointer onto again — while, when the current generation does not hold the id, the ones there that never held it stay as rollback targets (a rewrite is numbered above everything, so its `keep: 0` collection takes every older generation, above the pointer or below). Before it says `erased: true` the call lists the bucket and reads what is left, so **`erased: true` means no generation of the segment holds the id**, above the pointer or below it. `eraseSubject` reports a per-segment fault as an `error: …` ledger entry rather than throwing it, and a call that a racing writer overtook (a load, another erasure, or a rollback) as `erased: false, note: 'superseded'`, so "on return" is a claim about every segment whose entry says **`erased: true`** (a fault is an `error: …` entry, never `erased: true`). The store that performs the call stops serving the id immediately; **other processes converge on their own read TTL** — see [One process, and the rest of your fleet](#one-process-and-the-rest-of-your-fleet). Does **not** reach backups, replicas or noncurrent object versions — those hold the old generation until their own lifecycle removes it. It carries a generation's metadata over unchanged and does **not** scan it, so **never put a subject's id in metadata**. | "forget this person" — GDPR Art. 17 |
+| **Subject erasure** | `store.eraseSubject(id, { namespace })` | *Physical on return* — the segment's current generation is rewritten without the id (every chunk streamed through, one bit cleared), published **fenced on the generation it streamed**, and **the generation that held the bit is deleted before the call returns**. So is every other generation still holding the id: a retained *superseded* one (an ex-member dropped by a re-seed), and each one above the pointer after a `rollback` — generations a rollback can move the pointer onto again — while, when the current generation does not hold the id, the ones there that never held it stay as rollback targets, but for any object no read of the segment can open, which goes whatever the id. (When the current generation holds the id, the rewrite is numbered above everything, so its `keep: 0` collection takes every older generation, above the pointer or below.) Before it says `erased: true` the call lists the bucket and reads what is left, so **`erased: true` means no generation of the segment holds the id**, above the pointer or below it. `eraseSubject` reports a per-segment fault as an `error: …` ledger entry rather than throwing it, and a call that a racing writer overtook (a load, another erasure, or a rollback) as `erased: false, note: 'superseded'`, so "on return" is a claim about every segment whose entry says **`erased: true`** (a fault is an `error: …` entry, never `erased: true`). The store that performs the call stops serving the id immediately; **other processes converge on their own read TTL** — see [One process, and the rest of your fleet](#one-process-and-the-rest-of-your-fleet). Does **not** reach backups, replicas or noncurrent object versions — those hold the old generation until their own lifecycle removes it. It carries a generation's metadata over unchanged and does **not** scan it, so **never put a subject's id in metadata**. | "forget this person" — GDPR Art. 17 |
 | **Dispose** | `store.dropSegment(ref, { confirmSegment })` | *Immediate* — the segment is tombstoned and its Storage generations deleted, reclaiming the space. **Check `generationsRemaining`:** if it is non-empty the space was *not* fully reclaimed and the drop should be re-run (a load that had read the segment before the tombstone landed, even one still consuming its ids, or an `eraseSubject` rewrite already under way, can write its object after the drop's sweep; it deletes that object itself once its publish is refused, and only one whose process stops in between, or whose publish fails without a definite answer (a lost response, a timeout), leaves it, for a re-run of the drop). Works on cleartext; on an encrypted segment it *also* crypto-shreds, on the terms in the next row. Does **not** reach noncurrent versions / replicas / PITR snapshots — deleting an object is weaker than removing a key. | retiring a dated bucket; rolling-window retention |
 | **Crypto-shred** | `destroySegment` / `eraseNamespace` | *At rest, complete once no copy of the wrapped key survives* — removes the segment's wrapped DEK(s) from its registry row in one compare-and-swap, without touching the bytes or any KEK. **Every** copy of the objects (current, prior generations, backups, WORM-locked objects) is then unreadable once no retained copy of that row still holds the wrapped key — noncurrent object versions, backups and PITR copies of the row included — or once every KEK that wrapped it is destroyed. Until then, a retained copy of the row and a KEK that wrapped it decrypt the segment, and a registry restore to a point before the shred makes it readable again; see *Erasure vs. backups / WORM* below, and [an optional registry expiry rule](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/disaster-recovery.md#optional-make-a-shred-durable-with-a-registry-expiry-rule) that makes a shred durable after a set number of days. Requires the segment to be encrypted. A process that had already opened the segment holds the **unwrapped** key in memory and keeps reading until it is told — call `store.invalidate(ref)` there; see [One process, and the rest of your fleet](#one-process-and-the-rest-of-your-fleet). | whole-segment / tenant offboarding; erasure under immutable backups (see below) |
 
@@ -76,9 +76,16 @@ It reuses the store's own drivers (so build the store with a backend). It return
 **erasure ledger** — one entry per segment the id was found in, `{ segment, namespace?, erased, fromGeneration,
 generation, note? }` — as your proof of deletion; persist it or route it to your audit sink, which also receives
 one `segment.rewrite { fromGeneration, generation }` event per rewrite when you pass `audit` — an id found only
-outside the current generation (a retained *superseded* one, or one above the pointer after a rollback) is
-collected rather than rewritten, so it emits no event and its ledger entry carries no `generation`. Segments the id is
-not in are not listed. `store.subjectReport(id, { namespace })` answers the read side (Art. 15 — which segments
+outside the current generation (a retained *superseded* one, one above the pointer after a rollback, an object left
+under a tombstone, or a first load's object on a segment with no generation yet) is collected rather than rewritten,
+so it emits `segment.collect { fromGeneration, collected }`
+instead and its ledger entry carries no `generation`. Each `segment.*` event also names the segment's `incarnation`
+when its registry token carries one, so a segment created again under the same name is told apart from the one
+erased. Segments the id is
+not in are not listed. A segment where the erasure found the id in nothing it could search, and deleted only objects
+no read of it can open, is not listed either: the audit sink gets `segment.collect { collected }` for it, with no
+`fromGeneration`, and that event is the only record of the deletion. `store.subjectReport(id, { namespace })` answers
+the read side (Art. 15 — which segments
 an id is in).
 
 Two rules. **Do not load a segment while erasing from it**: a load that lands after the rewrite carries whatever
@@ -117,11 +124,22 @@ sweep run (it collects nothing without a row) reaches. List those objects with `
 `store.dropSegment(ref, { confirmSegment: ref.segment })`, which leaves a tombstone row fencing the name. An empty
 ledger is not by itself proof the id is gone. A tombstoned segment is searched too: a
 cleartext object left under it that holds the id is deleted with everything under the tombstone, and the entry reads
-`erased: true`. A segment whose row names no generation yet (a retention policy set before its first load) is
-searched too: an object a first load wrote and never published that holds the id, or on an encrypted store cannot
-be searched until its load publishes the key, is reported as an `error: …` note and not deleted: the erasure writes
-nothing to such a row, so the load that wrote the object may still publish it. Load the segment, which makes the
-object collectable, or drop it, and re-run.
+`erased: true`. A segment whose row names no generation yet (a retention policy set before its first load) is searched
+too: an object a first load wrote and never published that holds the id is deleted, and the entry reads `erased:
+true`. Before it deletes anything the erasure renews the row's `pointerId`, so a load still running that wrote such an
+object is refused at its publish and never names an object that is gone. Each delete names the object the erasure
+read: on a storage driver that reports `conditionalDelete`, another erasure of the id that deletes it first, followed
+by a load that takes the number freed and publishes, does not lose that load's generation to this erasure's delete; on
+one that does not, it can, and the row then names a missing object, which `store.checkConsistency()` reports
+([a number taken again](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/erasure.md#how-it-stays-correct)). On an encrypted store such an object cannot
+be searched until its load publishes the key, so it is deleted whatever id is erased: an erasure of any id refuses an
+encrypted first load in flight that has written its object onto a segment whose row was made ahead of its data, and
+that load is re-run ([the erasure guide](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/erasure.md#two-rules-while-you-erase)). On an encrypted segment,
+an object sealed under a key its row does not hold, and on a cleartext segment with a generation, an encrypted object,
+open for no read of the segment (the object of a first load that lost the race to the one that published, or
+crashed): each is deleted the same way, whatever id is erased, wherever an erasure meets it, except as the current
+generation, which is never deleted for this, and under a tombstone, where it is no holder and goes only with
+everything there, when another object under the tombstone holds the id.
 
 **Do not roll a segment back while erasing from it.** A rollback that lands mid-erasure can move the pointer onto a
 generation the erasure did not rewrite, so the id can be current again. Roll back before the erasure starts or
@@ -137,8 +155,8 @@ A call with a feed reads operands the library never stores, which no erasure can
 
 Erasure and crypto-shred are **immediate in storage and immediate in the store whose verb performed them**, for
 every read that starts after the verb returns. A read already in progress in that store can still yield an erased id
-from a chunk it had requested before the verb ran: up to 32 chunks for `iterate` and `count`, and up to `concurrency`
-keys (32 by default) for a combine. A combine or `iterate` reads ranges of the object, and resolves the segment again before it serves each chunk, one held in its cache included, as a read of that chunk alone does, so the ranges it had already requested are dropped, not served. They are not immediate in any *other* store, in the same process or another, and this library ships nothing that could
+from a chunk it had requested before the verb ran: up to 32 chunks for `iterate` and `count`, and up to `concurrency` + 1
+keys (33 by default) for a combine, the key it is handing out and the `concurrency` keys it had already requested. A combine or `iterate` reads ranges of the object, and resolves the segment again before it serves each chunk, one held in its cache included, as a read of that chunk alone does, so the ranges it had already requested are dropped, not served. They are not immediate in any *other* store, in the same process or another, and this library ships nothing that could
 make them so — there is no daemon, no bus, and no connection between two stores that happen to point at the same
 bucket.
 
@@ -154,11 +172,15 @@ bucket.
 | a leased pinned handle (`seg.pin({ leaseUntil })`) in another store | until its lease ends, at most 14 days after it was taken: its reads then throw `LeaseExpiredError`, whether or not its reader still holds the chunks. Until then, as for any pinned handle in the row above |
 
 **An outage of the registry extends that bound.** A refresh that cannot read the row because of a transient fault
-(throttling, a 5xx, a dropped connection) keeps serving the generation the reader already holds, and the key it
-unwrapped, and asks again 500 ms later, or after `cache.genTtlMs` if that is shorter. So while the registry cannot
-be read, a shred or a drop is not seen, and the store converges within one retry of the registry answering. Any
-other failure of the refresh (an access denial, a row that will not parse) is not ridden out: the read that finds it
-fails with that error, and the reader is dropped with the key it held.
+(throttling, a 5xx, a dropped connection) keeps serving what the store resolved before the outage, for a segment
+still in its reader cache: its open reader and the key that reader unwrapped, or, where no reader is open (a
+`count()` answered from the row opens none), the row it resolved. A read during the outage that needs the key,
+where none was unwrapped before it, unwraps it from that row's wrapped keys. The refresh asks again 500 ms later, or
+after `cache.genTtlMs` if that is shorter. So while the registry cannot be read, a shred or a drop is not seen, and
+the store converges within one retry of the registry answering. A segment the reader cache has let go is served only
+until its resolution lapses: after that its next read fails with the fault, as a cold read does. Any other failure
+of the refresh (an access denial, a row that will not parse) is not ridden out: the read that finds it fails with
+that error, and the reader is dropped with the key it held.
 
 `destroySegment` and `eraseNamespace` are free functions over raw drivers, not verbs of a store, so for them every
 store is another store, one in the same process included.
@@ -261,10 +283,10 @@ to run, and the deletion is ours to perform correctly.** Practical patterns:
   The registry row's `retention` is untouched by a load, an `*Into` materialization or an erasure rewrite, so the
   `expiresAt` you set stays put across all of them.
 - Surface segment age and size so unbounded growth is visible, not silent. The **metrics sink** carries neither (its `storage.get` events count the bytes of each read, not a segment's size).
-  `seg.count()` gives a segment's cardinality; `seg.costReport()` prices its current generation's measured size
-  (`monthlyUSD.byOp.storage`, $0 when the storage source cannot measure it), and does not count superseded
-  generations still in the bucket, which `store.generations(ref)` lists; and its registry row carries `createdAt`
-  and `updatedAt`, which the backend's `registry.list()` returns for every row.
+  `seg.count()` gives a segment's cardinality; `seg.stat()` gives its current generation's size in bytes (`sizeBytes`,
+  `null` when the storage source cannot measure it), and does not count superseded generations still in the bucket,
+  which `store.generations(ref)` lists; and its registry row carries `createdAt` and `updatedAt`, which the
+  backend's `registry.list()` returns for every row.
 
 **Be precise about what "drop the oldest" involves**, because the three levers differ in what they guarantee:
 
@@ -276,10 +298,10 @@ to run, and the deletion is ours to perform correctly.** Practical patterns:
 - **A deleted row keeps its record only where the registry cannot remove it.** Where the registry reports
   `conditionalDelete` (the default for S3 when its client sends to an AWS S3 host, for
   Azure Blob, the local filesystem and memory), `registry.delete` and the retention sweep's purge of a tombstone remove
-  a row created by 0.12 from the bucket, and its token's random incarnation id keeps a re-create apart from it. Where it
-  does not (an S3 client that sends to an S3-compatible store or an emulator, or a GCS client, by default, or
-  `conditionalDelete: false`), and for a row written by a release before 0.12 on any backend, a delete writes a deleted marker that holds
-  the record, so the row's token counter survives a re-create. A tombstone left by `dropSegment` or `destroySegment`
+  the row from the bucket, and a re-create's random incarnation id keeps it apart from the removed row. Where it does not
+  (an S3 client that sends to an S3-compatible store or an emulator, or a GCS client, by default, or
+  `conditionalDelete: false`), a delete writes a deleted marker that holds the record, so the row's token counter
+  survives a re-create. A tombstone left by `dropSegment` or `destroySegment`
   holds no wrapped key and no summary, since both clear them, so a purge that leaves a tombstone keeps the name, the
   pointer, the retention policy and the timestamps. A **live** row deleted directly with `registry.delete` keeps its
   summary, the current generation's id count and your metadata, in a marker where one is written.
@@ -308,12 +330,11 @@ So the two are complements, not alternatives: **`dropSegment` for "stop paying f
 > ⚠️ **Never let a lifecycle rule expire a registry row's current version, a tombstone, or a due-index pointer** —
 > a separate trap, and a worse one. A rule cannot tell a live row from a tombstone, and an expired live row is a
 > segment whose pointer is gone: its generations look unreferenced, and nothing reads or collects them. The library
-> removes a row only by a delete the store applies to the exact version it judged, and only a row whose token
-> carries a random incarnation id, so a name re-created later is told apart from it with overwhelming probability.
-> A tombstone of a row written by a release before 0.12 carries the row's token counter on instead, and that counter
-> is what keeps the name's tokens unique against a process still on that release. That token is the segment's
-> **identity**: it is what a cached reader, a fenced publish and a generation-collection pass each compare to decide
-> whether two observations describe the same segment. Re-issue one and they can all answer "yes" about a segment that
+> removes a row only by a delete the store applies to the exact version it judged, and every row's token carries a
+> random incarnation id, so a name re-created later is told apart from it with overwhelming probability. That token is
+> the segment's **identity**: a fenced publish and a generation-collection pass compare it, and a cached reader
+> compares the row's `pointerId`, itself one of the row's tokens, to decide whether two observations describe the same
+> segment. Re-issue one and they can all answer "yes" about a segment that
 > no longer exists — serving a deleted incarnation's data, or collecting a live one's objects. A rule on
 > *noncurrent* versions of the registry prefix touches neither the current row nor its tombstone; what it shortens is
 > the history a registry restore picks from, and the time a crypto-shred takes to complete (above).
@@ -332,8 +353,7 @@ response, a removal the registry refused (`purgeFaults` counts it), or a pointer
 it reads, and an unscoped fleet scan, one given no `namespace`, from every day. A deployment that scopes every sweep to a
 namespace, or runs only index scans, keeps such a pointer until an unscoped fleet scan runs. Where the registry does not
 report `conditionalDelete` (an S3 client that sends to an S3-compatible store or an emulator, or a GCS client, by default, or
-`conditionalDelete: false`), and for a row written by a release before 0.12 on any backend, the purge leaves a tombstone
-instead: every one of those fields, in the bucket, indefinitely, read by every full listing. A registry that does not
+`conditionalDelete: false`), the purge leaves a tombstone instead: every one of those fields, in the bucket, indefinitely, read by every full listing. A registry that does not
 report it files no pointer to begin with. A removed
 row stays recoverable wherever the storage keeps a copy of it: with object versioning on, its earlier versions stay until
 a noncurrent-version rule expires them, as an overwritten row's do; with soft delete on, it stays for the retention
@@ -382,8 +402,13 @@ Wire the **audit sink** (`IAuditSink`) to get an append-only, vendor-neutral rec
 state changes — `segment.publish` (a loaded generation became current), `segment.load-refused` (a load that did
 not publish, because its guard refused it or another writer got there first), `segment.rollback` (an operator moved
 the pointer to a generation it named), `segment.rewrite` (a subject-erasure
-rewrite: `fromGeneration` → `generation`), `segment.erase` (a genuine crypto-shred), `segment.dispose` (a
-`dropSegment`, including every retirement the sweep performs) and `namespace.erase` — for your audit log / SIEM.
+rewrite: `fromGeneration` → `generation`), `segment.collect` (a subject erasure that rewrote nothing and deleted what
+no reader resolves: the generations holding the id, when it found the id only outside the current generation, or, with
+no `fromGeneration`, only objects no read of the segment can open, which it deletes whatever the id), `segment.erase`
+(a genuine
+crypto-shred), `segment.dispose` (a `dropSegment`, including every retirement the sweep performs) and
+`namespace.erase` — for your audit log / SIEM. Each `segment.*` event names the segment's `incarnation` when its
+registry token carries one, so a segment created again under the same name is told apart from the one before.
 It is off by default and exception-safe. See the [dashboards guide](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/dashboards.md), which also says
 which event is the receipt for which claim. An erasure *ledger* — per-subject-request proof of physical deletion
 — is returned by **`eraseSubject`**. `subjectReport` is the read side and returns only which segments an id is

package/README.md

@@ -14,6 +14,7 @@ file, then ask `has`, `count`, `iterate`, `intersect`, `union` and `andNot`, wit
 ```bash
 pnpm add @cloudbitmaps/roaring              # the store, with in-memory and local-disk backends
 pnpm add @cloudbitmaps/s3                   # the storage you have: or @cloudbitmaps/gcs, or @cloudbitmaps/azure-blob
+pnpm add @cloudbitmaps/tools                # optional: price a store, offline
 ```
 
 On npm 12 and pnpm 10 and later, allow `roaring`'s one install script first, or the install exits 0 and the package throws at `import`. Put this in your `package.json`: `{ "allowScripts": { "roaring": true }, "pnpm": { "onlyBuiltDependencies": ["roaring"] } }`. npm 11 runs the script but warns until you allow it the same way; pnpm 9 needs nothing extra. [Details](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#cannot-find-module-buildreleaseroaringnode-after-a-successful-install).
@@ -83,7 +84,8 @@ pointer read: it reads no payload and no object.
 The trade is stated plainly. A membership check that misses the cache costs a ranged GET against object storage,
 where an in-process store costs a memory read. If you need sub-millisecond answers on a working set that fits a
 bounded cache, use Redis. [The benchmarks](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/benchmarks.md)
-give the method and what the numbers do not establish.
+give the method and what the numbers do not establish. To price your own store, from the sizes `seg.stat()` reports, use
+`@cloudbitmaps/tools` ([the cost guide](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/cost.md)).
 
 ## Before production
 

package/dist/bin/export-segments.js

@@ -33,8 +33,6 @@ import {
   excludingReservedRows,
   dropSegment,
   eraseIdFromSegment,
-  estimateCost,
-  groundedReport,
   judgeLoad,
   loadSegment,
   loadSegmentChunks,
@@ -55,7 +53,7 @@ import {
   splitId,
   takeLease
 } from "@cloudbitmaps/core";
-import { validateSegmentRef } from "@cloudbitmaps/core/driver-kit";
+import { pointerIdOf, validateSegmentRef } from "@cloudbitmaps/core/driver-kit";
 
 // src/open-charging-storage.ts
 var OpenChargingStorage = class {
@@ -88,8 +86,9 @@ var OpenChargingStorage = class {
     if (!this.free.has(key.generation)) this.charge();
     return this.inner.getTail(key, maxBytes);
   }
-  delete(key) {
-    return this.inner.delete(key);
+  /** Handed through whole: the erasure's delete of a holder is conditioned on the object it searched. */
+  delete(key, options) {
+    return this.inner.delete(key, options);
   }
   list(ref) {
     return this.inner.list(ref);
@@ -655,10 +654,7 @@ import {
   BufferReader,
   CountingMetricsSink,
   RecordingAuditSink,
-  DEFAULT_RETRY_POLICY as DEFAULT_RETRY_POLICY2,
-  AWS_US_EAST_1_ONDEMAND,
-  ELASTICACHE_REDIS_US_EAST_1_ONDEMAND,
-  ONE_REDIS_HA_CLUSTER
+  DEFAULT_RETRY_POLICY as DEFAULT_RETRY_POLICY2
 } from "@cloudbitmaps/core";
 var SystemRng = class {
   /** A float in `[0, 1)`. Jitter only — never key material, never anything a caller can observe. */
@@ -780,23 +776,7 @@ var CALL_KEYS = {
     "concurrency",
     "summaries"
   ]),
-  exportSegments: keysOf()(["format", "codec", "namespace", "ndjsonBatchBytes"]),
-  costReport: keysOf()(["pricing", "workload"]),
-  workload: keysOf()([
-    "readsPerSec",
-    "intersectsPerSec",
-    "cacheHitRate",
-    "chunksPerIntersect",
-    "operandsPerIntersect",
-    "loadsPerMonth",
-    "requestsPerLoad",
-    "hotSegments",
-    "readerProcesses",
-    "genTtlMs",
-    "retirementsPerMonth",
-    "purgesPerMonth",
-    "conditionalDelete"
-  ])
+  exportSegments: keysOf()(["format", "codec", "namespace", "ndjsonBatchBytes"])
 };
 var kindOf = (v) => v === null ? "null" : Array.isArray(v) ? "an array" : `a ${typeof v}`;
 function optionsError(options, op, known, booleans = []) {
@@ -1148,22 +1128,24 @@ var CloudRoaring = class _CloudRoaring {
   }
   /**
    * Get a handle to a segment. Validates the name (non-empty, well-formed, within the encoded-length cap). The options
-   * are `{ namespace }` and nothing else: anything else is refused with {@link ValidationError}, by name, since a
-   * misspelt `namespace` would otherwise address the default namespace. An `expiresAt` among them is refused with its own
-   * message: a handle carries no deadline, and one left unread would serve the data past it. A key whose value is
-   * `undefined` is read as absent, so a spread of options keeps working.
+   * are a plain object holding `{ namespace }` and nothing else: any other own key, enumerable or not, is refused with
+   * {@link ValidationError}, by name, since a misspelt `namespace` would otherwise address the default namespace, and a
+   * deadline such as `expiresAt` would be left unread. A class instance, or an object built on another, is refused too,
+   * since it can carry an option no scan of its own keys sees. A key whose value is `undefined` is read as absent, so a
+   * spread of options keeps working.
    */
   segment(name, options) {
     if (options !== void 0 && options !== null) {
       if (typeof options !== "object" || Array.isArray(options)) {
         throw new ValidationError2("segment: options must be an object such as { namespace }");
       }
-      if (options.expiresAt !== void 0) {
+      const proto = Object.getPrototypeOf(options);
+      if (proto !== null && Object.getPrototypeOf(proto) !== null) {
         throw new ValidationError2(
-          "segment: `expiresAt` is not an option of a handle; check a deadline where you read, or record it with `store.setRetention(ref, { expiresAt })` and run `store.retireExpired()`"
+          "segment: options must be a plain object such as { namespace }, not a class instance or an object built on another"
         );
       }
-      const unknown = Object.keys(options).filter(
+      const unknown = Object.getOwnPropertyNames(options).filter(
         (k) => k !== "namespace" && options[k] !== void 0
       );
       if (unknown.length > 0) {
@@ -1197,13 +1179,20 @@ var CloudRoaring = class _CloudRoaring {
    * of it. A materialisation is a load whose ids happen to come from a combine instead of from upstream, so
    * everything `load()` learned the hard way applies unchanged: the generation is written UNPUBLISHED, the
    * guard runs while the old generation is still authoritative, the publish is fenced as above, and a refused
-   * object is reclaimed only when a re-read finds the row unchanged (the same token) or gone (hard invariant 1:
-   * deleting it after a purge-and-recreate would put a live row over a missing generation).
-   *
-   * That last check narrows the window rather than closing it: the row read and the delete are two round
-   * trips, and `IStorageDriver` has no conditional delete to make them one. the collection a load runs carries
-   * the same residual. The failure it leaves is an orphan object, which costs storage until
-   * something collects it — deliberately the cheaper side of the trade.
+   * object is reclaimed only when a re-read finds the row unchanged (the same token, or one that differs only in
+   * its leases), `destroyed`, or gone, or finds key material on it when the load wrote cleartext; under any other
+   * row it is kept (hard invariant 1: deleting it after a purge-and-recreate would put a live row over a missing
+   * generation).
+   *
+   * Where the row is gone, or keyed over a cleartext write, the object is proved the load's own by its footer, and
+   * the delete passes the version that read reported, so on a storage driver that reports `conditionalDelete` an
+   * object put under the number since is kept. Where the row is unchanged or `destroyed`, the check narrows the
+   * window rather than closing it: the row read and the delete are two round trips, and the delete is by number,
+   * since the write reports no version of the object it made. The other deletes a load leads to are by number too: its
+   * collection deletes what a listing, or the row's list of kept generations, names below the pointer, and a drop's
+   * sweep and a tombstoned segment's collection delete what a listing names under a `destroyed` row. The failure the
+   * checks leave when they refuse is an orphan object, which costs storage until something collects it —
+   * deliberately the cheaper side of the trade.
    *
    * Written and published in one step, with no guard, an empty combine — a typo'd operand, an `exclude` that
    * swallowed everything, an operand that had not loaded yet — would silently replace `dest` with an empty
@@ -1568,7 +1557,7 @@ var CloudRoaring = class _CloudRoaring {
       }
     }
     const row = await this.withRetries(() => registry.get(ref));
-    return row === null ? null : { generation: row.currentGen, token: row.token };
+    return row === null ? null : { generation: row.currentGen, token: pointerIdOf(row) };
   }
   /** Throw what a read of, or a publish to, `handle` must throw now: its lease error, if it has one. */
   assertLease(handle) {
@@ -1613,7 +1602,7 @@ var CloudRoaring = class _CloudRoaring {
         const ref = { segment: rec.segment, namespace: rec.namespace };
         if (this.crbmSource !== void 0) {
           const held = await this.crbmSource.currentVersion(ref);
-          const listed = rec.currentGen === null ? null : `${rec.currentGen}:${String(rec.token)}`;
+          const listed = rec.currentGen === null ? null : `${rec.currentGen}:${pointerIdOf(rec)}`;
           if (rowVersionOfLive(held) !== listed) this.engine.invalidate(ref);
         }
         return await this.engine.has(ref, id) ? { segment: rec.segment, namespace: rec.namespace } : null;
@@ -1633,10 +1622,14 @@ var CloudRoaring = class _CloudRoaring {
    * can still hold it, and so can one above the pointer after a {@link CloudRoaring.rollback}, which the rollback
    * could make current again. Each holder is deleted — below the pointer by a `keep: 0` collection, above it one
    * by one, re-proved against the row first — and the generations above the pointer that never held the id stay
-   * as rollback targets. An entry says `erased: true` only once the call has listed the bucket and read what is
-   * left: **no generation of the segment holds the id**. The returned per-segment record is your **erasure ledger** —
-   * persist it / route it to your audit sink as the proof of deletion (a `segment.rewrite` audit event is also
-   * emitted per rewrite when you pass `audit`).
+   * as rollback targets, but for any object no read of the segment can open, which goes whatever the id. An entry
+   * says `erased: true` only once the call has listed the bucket and read what is left: **no generation of the
+   * segment holds the id**. The returned per-segment record is your **erasure ledger** —
+   * persist it / route it to your audit sink as the proof of deletion (when you pass `audit`, an audit event is also
+   * emitted per segment erased: `segment.rewrite` for a rewrite, `segment.collect` where only other generations held
+   * the id and nothing was rewritten). A segment where the erasure deleted only objects no read of it can open (a first
+   * load's sealed under a key no row holds) found the id in none, so the ledger does not list it; the audit sink gets
+   * `segment.collect` for it with no `fromGeneration`, which is the only record of that deletion.
    *
    * Uses the backend's **own** two halves, so the membership check and the rewrite provably run
    * over the same generation. Requires the store built with a **backend** (throws
@@ -1658,13 +1651,21 @@ var CloudRoaring = class _CloudRoaring {
    * an error, read off the row: a moved pointer is a `'superseded'` entry, which a re-run settles, and a segment
    * that a concurrent `dropSegment` tombstoned or a retention sweep purged is left out of the ledger. A tombstoned
    * segment is still searched: a cleartext object left under it that holds the id is deleted, with everything under
-   * the tombstone, and the entry reads `erased: true`.
+   * the tombstone, and the entry reads `erased: true`. So is a segment whose row names no generation yet (a retention
+   * policy set before its first load): a first load's object that holds the id is deleted, once the row's `pointerId`
+   * is renewed so that the load, if still running, is refused at its publish, and the entry reads `erased: true`. An
+   * encrypted first load's object there cannot be searched, so it is deleted whatever the id: on an encrypted store,
+   * an erasure of any id refuses an encrypted first load in flight that has written its object onto a segment made
+   * ahead of its data. Each such delete, and each of a holder above the pointer, names the object the erasure read:
+   * on a storage driver that reports `conditionalDelete`, another erasure of the id that deletes it first, followed by
+   * a load that takes the number freed and publishes, does not lose that load's generation to this erasure's delete,
+   * which is refused, and the entry says what the row says; on one that does not, it can.
    *
    * **Read `note` on any `erased: false` entry — the two reasons mean different things.** `'superseded'` means
-   * another writer (a load, another erasure, or a rollback) moved the pointer mid-call, so **this call** did not
-   * erase the id. Re-run: it erases the id if it is still there, and lists nothing for the segment if a racing
-   * erasure of the same id already removed it. Do not read `'superseded'` as "the id is still present" —
-   * read it as "not done by this call, and the re-run settles it".
+   * another writer (a load, another erasure, or a rollback) moved the pointer, or replaced an object the call meant to
+   * delete, mid-call, so **this call** did not erase the id. Re-run: it erases the id if it is still there, and lists
+   * nothing for the segment if a racing erasure of the same id already removed it. Do not read `'superseded'` as
+   * "the id is still present" — read it as "not done by this call, and the re-run settles it".
    * `` `error: …` `` is a per-segment fault (caught so one segment can't discard the whole ledger) and it can land
    * on either side of the publish: if the rewrite had not published, the id is still there and a re-run erases
    * it; if the publish succeeded and only the **collection** of the old generation failed, the id is already
@@ -1859,8 +1860,9 @@ var CloudRoaring = class _CloudRoaring {
    * and are then *above* `currentGen`, where collection never looks. They remain until loads pass them (the first
    * load whose number one of them holds numbers above them all, and collection then keeps the newest `keep` of what is
    * below its pointer), {@link CloudRoaring.dropSegment}
-   * deletes them, or {@link CloudRoaring.eraseSubject} does: all of those present when it rewrites, and only those holding
-   * the id when the current generation does not. An operator who has just undone a bad load should not have the
+   * deletes them, or {@link CloudRoaring.eraseSubject} does: all of those present when it rewrites, and, when the
+   * current generation does not hold the id, only those holding it and any no read of the segment can open, whatever
+   * the id. An operator who has just undone a bad load should not have the
    * evidence collected out from under them, while a rollback target that still holds erased data would make the
    * erasure undoable.
    *
@@ -1929,10 +1931,12 @@ var CloudRoaring = class _CloudRoaring {
    * published, a retention change, a rollback or an erasure wrote the row, or the row was deleted.
    *
    * A refused load deletes the object it wrote before returning — it sits above `currentGen`, where generation
-   * collection deliberately never looks — but only while the segment's registry row is unchanged or gone. Once
-   * another write has changed the row, the generation number it holds may name another incarnation's live object,
-   * so it leaves the orphan rather than risk deleting live data. No row's list names it, so it takes no place in a
-   * window, and a listing deletes it once a later generation is current above it.
+   * collection deliberately never looks — but only while the segment's registry row is unchanged (or differs only
+   * in its leases), `destroyed` or gone, or has key material when the load wrote cleartext, which has no place in an
+   * encrypted segment's bucket. Under a row that is gone or keyed, a read of the object's footer must prove it the
+   * load's own first. Once another write has otherwise changed the row, the generation number it holds may name
+   * another incarnation's live object, so it leaves the orphan rather than risk deleting live data. No row's list
+   * names it, so it takes no place in a window, and a listing deletes it once a later generation is current above it.
    *
    * **Collection is by name at any `keep` up to 64.** The segment's row records the generations a load keeps, so a load
    * that found nothing above the pointer deletes the generations its publish pushed out of the window and lists
@@ -2145,8 +2149,8 @@ var CloudRoaring = class _CloudRoaring {
    * Pass `purgeTombstones: false` to keep every tombstone, that row included. On a backend whose registry reports
    * `conditionalDelete` (AWS S3, Azure Blob, the local filesystem and memory, by default; GCS when you set `conditionalDelete: true`)
    * the purge removes the row from the bucket for good, by a delete the store applies only to the version it judged,
-   * so a full sweep reads what is live or inside its grace rather than every name a namespace ever held; elsewhere,
-   * and for a row a release before 0.12 wrote, it leaves a tombstone. Each retirement files a pointer in the due index
+   * so a full sweep reads what is live or inside its grace rather than every name a namespace ever held; elsewhere it
+   * leaves a tombstone. Each retirement files a pointer in the due index
    * under the day its tombstone's grace ends, so `scan: 'index'` purges as well as retires.
    *
    * Needs the store built with a **backend** (throws {@link UnsupportedError} otherwise),
@@ -2370,7 +2374,8 @@ var CloudRoaring = class _CloudRoaring {
    * A segment whose pointer names a missing object is the torn restore this reports; a cold `count()` of it still
    * answers the number its row records, while a read of the object throws, so the count alone never shows it. With
    * `summaries: true` it also opens each segment's current object (one tail read each) and reports a segment whose
-   * row's summary says another id count or metadata than the object holds as `summary-mismatch`, which is what a
+   * row's summary names another object by its fingerprint, or says another id count or metadata than the object holds,
+   * as `summary-mismatch`, which is what a
    * restore of the registry from another point than the bucket leaves a count to answer. A sealed summary is held
    * against its object when this store has the key, and counted in `summariesUnchecked` when it does not.
    *
@@ -2406,15 +2411,6 @@ var CloudRoaring = class _CloudRoaring {
     const registry = this.requireRegistry("exportSegments");
     return runExport(this, registry, sink, { ...opts, codec: opts.codec ?? roaringCodec });
   }
-  /**
-   * Planning cost estimate — pure, no instance/data needed: sizing, sales, what-if. For a real, grounded report
-   * from live segment sizes, use `store.segment(name).costReport()`. See {@link CostReport}.
-   * @deprecated Moves to `@cloudbitmaps/tools`, a package of its own, with a `size` on `stat()` so a grounded report
-   * needs nothing internal. It is a planning tool, and its price list is as old as the release that ships it.
-   */
-  static estimateCost(input) {
-    return estimateCost(input);
-  }
 };
 var withBatches = (gen, batches) => Object.assign(gen, { batches });
 var failing = (err) => {
@@ -2811,8 +2807,8 @@ var Segment = class _Segment {
    * Cardinality of the generation this handle reads: **one registry read when cold, none when warm, and no read of the
    * object**, with **zero payload reads**. The registry row records the id count of the generation it names, written
    * by the write that made it current, and a count answers from that. A row with no summary it can use (one written
-   * before rows carried it, one that names another generation, a sealed one that does not open) sends the count to the
-   * `.crbm` index, summed with a tail read of the object. A segment whose pointer names a missing object (a torn
+   * without it, as a registry of your own may, one that names another generation, a sealed one that does not open)
+   * sends the count to the `.crbm` index, summed with a tail read of the object. A segment whose pointer names a missing object (a torn
    * restore) still counts the row's number, while a read of the object throws; `checkConsistency` is what finds it.
    *
    * What this trusts: the row's summary, or the index's sum, and no payload is decoded to confirm it. The summary is
@@ -2831,17 +2827,30 @@ var Segment = class _Segment {
     return this.timed("count", () => this.engine.count(this.ref));
   }
   /**
-   * What the generation this handle reads is, from one resolution: its number, its id count and the metadata it
-   * was loaded with (absent when it has none). It is what answers {@link Segment.count}, so the three describe one
-   * generation and cannot straddle a publish. One registry read when cold, none while warm, and none on a pinned
-   * handle, which answers for the generation it pinned. A segment with no generation answers
-   * `{ generation: null, cardinality: 0 }`.
-   *
-   * Trust is as for `count()`: the registry row's word, not confirmed against the object until the object is
-   * opened, when a disagreement makes this process stop using that row's summary.
+   * What the generation this handle reads is, from one resolution: its number, its id count, the metadata it was
+   * loaded with (absent when it has none), and `sizeBytes`, its object's bytes in storage. All four come from the
+   * registry row when it has a summary this store can use, as `count()`'s do: the summary records the object's
+   * fingerprint, its size with its checksum. That is **one registry read when cold, none when warm, and no read of the
+   * object**. With no summary it can use, they come from the generation's object, opened once: its footer and index,
+   * with no payload read, which is a tail read of the object more when cold (and a range read for an index longer than
+   * the tail) and keeps the generation in the reader cache as a read does. On a pinned handle it answers for the
+   * generation it pinned, from the pinned object. A segment with no generation answers
+   * `{ generation: null, cardinality: 0, sizeBytes: null }`, and a store whose source cannot report a size answers
+   * `sizeBytes: null`. A pointer that names a missing object (a torn restore) still answers from the row's summary, as
+   * `count()` does, while a read of the object throws `NotFoundError`; with no summary to use, `stat()` throws it too.
+   * `checkConsistency` is what finds such a row.
+   *
+   * Trust is as for `count()`: what the row's summary says is believed until the object is next opened. Every open of
+   * the generation holds the object to the fingerprint the summary records, so another object under the number is
+   * refused when it is opened, and holds its count against the summary's; a disagreement in count makes this process
+   * stop using that summary, so `stat()` then answers from the object, whose index is checked for internal consistency
+   * and whose count is the index's sum. A reader already open is not checked again until the row changes, it is
+   * evicted or it is invalidated.
+   *
+   * `sizeBytes` is what `groundedReport` in `@cloudbitmaps/tools` prices storage from.
    *
    * ```ts
-   * const { generation, cardinality, metadata } = await store.segment('active-30d').stat();
+   * const { generation, cardinality, metadata, sizeBytes } = await store.segment('active-30d').stat();
    * ```
    */
   async stat() {
@@ -3131,35 +3140,6 @@ var Segment = class _Segment {
       )
     );
   }
-  /**
-   * Grounded cost report for this segment: storage cost from its **real** `.crbm` size (exact, no payload
-   * reads); request cost from the supplied `workload` rates. A segment with no Storage generation reports zero
-   * storage. The pointer refresh is priced at the store's own `cache.genTtlMs`, or at none when the store never
-   * refreshes, unless the workload sets `genTtlMs`. See {@link CostReport} — it always includes a verdict (incl.
-   * the lose-zone).
-   * @deprecated Moves to `@cloudbitmaps/tools`, a package of its own, with a `size` on `stat()` so a grounded report
-   * needs nothing internal. It is a planning tool, and its price list is as old as the release that ships it.
-   */
-  async costReport(options) {
-    checkOptions(options, "costReport", CALL_KEYS.costReport);
-    const shape = options?.workload;
-    if (shape !== void 0 && shape !== null && (typeof shape !== "object" || Array.isArray(shape))) {
-      throw new ValidationError2("costReport: workload must be an object");
-    }
-    this.assertLeases([this]);
-    const canMeasure = this.engine.supportsStorageSize;
-    const size = canMeasure ? await this.engine.segmentSize(this.ref) : null;
-    const refreshMs = this.engine.pointerRefreshMs;
-    const given = options?.workload === void 0 || options.workload === null ? void 0 : picked(options.workload, CALL_KEYS.workload);
-    const workload = refreshMs === void 0 || given?.genTtlMs !== void 0 ? given : { ...given, genTtlMs: refreshMs };
-    return groundedReport({
-      storageBytes: size?.sizeBytes ?? 0,
-      grounded: canMeasure,
-      workload,
-      pricing: options?.pricing,
-      extraNotes: canMeasure ? void 0 : ["storage source has no sizeOf() \u2014 storage not measured, reported as $0."]
-    });
-  }
 };
 
 // src/bin/export-segments.ts
@@ -3282,7 +3262,8 @@ async function main(env = process.env, now = () => Date.now()) {
     format: manifest.format,
     totalSegments: manifest.totalSegments,
     totalIds: manifest.totalIds,
-    failed: manifest.failed.length
+    failed: manifest.failed.length,
+    skipped: manifest.skipped.length
   });
   return manifest;
 }