@cloudbitmaps/roaring 0.25.0 → 0.27.0

package/PRIVACY.md

@@ -42,7 +42,7 @@ from constructing a cross-region topology. The points where personal data moves
 
 | Location | What's there | Residency note |
 |---|---|---|
-| **Storage** (object store) | immutable `.crbm` generations — every generation a segment has had, until a superseded one is collected. Every generation object a cloud driver writes (S3, GCS and Azure Blob) also carries a random write id in its metadata (`cbwid`; `x-amz-meta-cbwid` on S3): 128 random bits, no data from the bitmap or the source. A write that fails or is killed part way can leave the uploaded part of a generation behind (S3 multipart parts, Azure Blob uncommitted blocks, an unfinished GCS resumable session, a `LocalFsStorage` `.tmp` file); no listing shows it, so no erasure or drop reaches it. What each backend leaves, and when it is removed, is in [the backup checklist](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/disaster-recovery.md#backup-checklist) | the region of the bucket you wire |
+| **Storage** (object store) | immutable `.crbm` generations — every generation a segment has had, until a superseded one is collected. Every generation object a cloud driver writes (S3, GCS and Azure Blob) also carries a random write id in its metadata (`cbwid`; `x-amz-meta-cbwid` on S3): 128 random bits, no data from the bitmap or the source. A write that fails or is killed part way can leave the uploaded part of a generation behind (S3 multipart parts, Azure Blob uncommitted blocks, an unfinished GCS resumable session, a `LocalFsStorage` `.tmp` file); no listing shows it, so no erasure or drop reaches it. What each backend leaves, and how to remove it, is in [the backup checklist](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/disaster-recovery.md#backup-checklist). The library sweeps a `LocalFsStorage` `.tmp` leftover more than 24 hours old only when something writes in that directory again, and after a drop or an erasure nothing does: delete those yourself | the region of the bucket you wire |
 | **Registry** (S3 / GCS / Azure Blob / local) | one row per segment: its namespace and name, its status and timestamps, the current-generation pointer, wrapped keys and any key id, its `retention` and `residency` metadata, the current generation's id count, its object's size, footer checksum and tail size, and your metadata (those sealed when the segment is encrypted), a ledger of the generations the segment knows (each one's number and its object's footer checksum, in the clear even on an encrypted segment), any leases, and a token and `pointerId` — no IDs, unless you put one in the metadata or a name, which you must not. An Azure Blob row also carries the random write id in its metadata. On `LocalFsStorage`, a write killed part way leaves a `.tmp` copy of the row beside it, wrapped keys included, until a later write in that directory removes it once it is more than a day old, so a crypto-shred there can be outlived by that copy for that long | the region of the bucket you wire |
 | **cache** (process RAM) | decoded chunks, and the stored chunk bytes (ciphertext on an encrypted segment) a reader keeps of a small generation it read whole; bounded LRU | **wherever your process/Lambda runs** — an EU segment queried from a US function is processed in the US |
 | **Loads and rewrites** (`store.load()`, the `*Into` verbs, `store.materializeMany()`, `eraseSubject`) | read your source (or existing generations), write a new generation; a fed operand of `materializeMany` is read from your own process's memory | run wherever you run them — a loader in one region writing to a bucket in another is a transfer |
@@ -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, 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. A holder found only above the pointer likewise takes every generation below the pointer with it, clean ones included ([every holder goes](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/correctness.md#every-holder-goes)); above the pointer, a generation with no copy of the id stays, and so does the current one.) 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**. The scope is one `namespace` or `{ allNamespaces: true }`, never both (both throws `ValidationError`); a segment loaded with no `namespace` is reached only by `{ allNamespaces: true }`, and `'_default'` is an ordinary namespace name, not those segments. | "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 every object near the row's own numbers, so its `keep: 0` collection takes every older generation, above the pointer or below. A holder found only above the pointer likewise takes every generation below the pointer with it, clean ones included ([every holder goes](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/correctness.md#every-holder-goes)); above the pointer, a generation with no copy of the id stays, and so does the current one.) 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**. The scope is one `namespace` or `{ allNamespaces: true }`, never both (both throws `ValidationError`); a segment loaded with no `namespace` is reached only by `{ allNamespaces: true }`, and `'_default'` is an ordinary namespace name, not those segments. | "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) |
 
@@ -173,7 +173,7 @@ 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` + 1
-keys (33 by default) for a combine. That is the bound: the chunk or key a read is handing out and what it had already requested, which a `count` that reads chunks (on a source with no index of its own) reaches. A running `iterate` or combine on the library's own sources stops sooner: the verb invalidates the segment, so before the next key it takes the read lists its chunk keys again from the generation current then and drops what it had requested, and so yields the id only from the chunk or key it is handing out. 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. A pinned read in progress does not move to the rewritten generation: before its next chunk it opens its object again, and fails with `NotFoundError` once the erasure has deleted it, so it yields no more than that bound either. They are not immediate in any *other* store, in the same process or another, and this library ships nothing that could
+keys (33 by default) for a combine or a count of a combine. That is the bound: the chunk or key a read is handing out and what it had already requested, which a `count` that reads chunks (on a source with no index of its own) reaches. A running `iterate` or combine on the library's own sources stops sooner: the verb invalidates the segment, so before the next key it takes the read lists its chunk keys again from the generation current then and drops what it had requested, and so yields the id only from the chunk or key it is handing out. 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. A pinned read in progress does not move to the rewritten generation: before its next chunk it opens its object again, and fails with `NotFoundError` once the erasure has deleted it, so it yields no more than that bound either. In another store it stops at its next chunk once `cache.genTtlMs` has passed since the pin last looked at its segment's row and the segment has been destroyed or its generation erased. 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.
 
@@ -185,8 +185,7 @@ bucket.
 | another store with **no registry** (a bare `IStorageDriver`), with `cache: { genTtlMs: 0 }`, or on a `StorageChunkSource` of your own, which the store times no refresh on | **no bound** — only when its caches happen to let the segment go, or something tells it |
 | `seg.pinAt` of a generation the erasure rewrote, in any store | on return it fails with `NotFoundError`, since the object is deleted (and, with a registry, the row has moved on); during the erasure, between the rewrite's publish and its delete of the old generation, it can still open that generation, and a handle opened then is a pin, covered by the rows for the store whose verb made the call and for a pinned handle in another store |
 | a `materializeMany` call with a feed, and an erasure by any path but this store's `eraseSubject` | **no bound**: the call is refused only by this store's `eraseSubject` |
-| a pinned handle (`seg.pin()`) in another store | **no bound** — until that store's reader cache evicts the pin's reader (in a store with a timed pointer refresh, a small generation's reader holds all of its chunks, decoded or not) and its chunk cache evicts the chunks the pin decoded, or something tells it |
-| 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 |
+| a pinned handle (`seg.pin()`) in another store, leased or not | within `cache.genTtlMs` (default 2 s), while the registry can be read and storage answers the read of the pinned object's footer, whether or not its reader still holds the chunks; an outage of the registry, or a transient storage fault on that read, stretches it. A lease does not lengthen it: once a lease has lapsed, reads throw `LeaseExpiredError` first. A pin of a generation the erasure could not remove (its ledger entry has `erased: false`) reads it, the id included, until a re-run of the erasure removes it |
 
 **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 what the store resolved before the outage, for a segment
@@ -202,12 +201,13 @@ 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.
 
-The last two rows are the ones to design around. `cache: { genTtlMs: 0 }` turns the timed refresh off, and is a
+The no-timed-refresh row and the feed row are the ones to design around. `cache: { genTtlMs: 0 }` turns the timed refresh off, and is a
 legitimate setting for a read-only replica of immutable data — but a store set that way has no bound on when it
 observes a shred: until its reader cache lets the segment go, it keeps decrypting with the key it already unwrapped.
-A pinned handle is that case in any store, clock or none, and holds on longer: its reader keeps the key until the
-reader cache evicts it, and after that the pin still answers `has()` for the ids in chunks it decoded, until the
-chunk cache drops them. If a
+A pinned handle in such a store is that case too: its reader keeps the key until the reader cache evicts it, and after
+that the pin still answers `has()` for the ids in chunks it decoded, until the chunk cache drops them. A pinned handle
+in a store with a timed refresh is bounded like any other reader: it re-reads its segment's row every `cache.genTtlMs`,
+counted from the moment it was taken, and fails with `NotFoundError` once the segment is destroyed or its generation erased. If a
 compliance deadline depends on every reader converging, fan the reference out to your fleet and have each
 process call `store.invalidate(ref)`; that is the hook, and delivering it is yours because the transport is
 yours.
@@ -451,6 +451,12 @@ it (the request and response it kept, and a credential the service quotes back o
 in another form reaches you as the SDK wrote it; and `eraseSubject` copies each message into its ledger's `note`.
 Treat an error message, and the ledger, as carrying those names wherever you report or keep them.
 
+The names also reach your metrics sink: every `storage.get` event carries the segment and namespace of the read, as the
+audit events do (ids never appear in either). **The library does not redact a name.** If a name carries tenant or customer
+meaning, pass a name that does not: for example your own keyed hash of the tenant id (an HMAC under a key you hold) as the
+namespace or segment, with the mapping from a hash back to the tenant kept in your own system. Then every error, event and
+registry row names only the hash.
+
 
 ## Shared-responsibility matrix
 

package/README.md

@@ -105,8 +105,8 @@ name.
 
 ## What it costs
 
-A cold `intersect` of two 500,000-id segments sharing 100 of their 1,999 chunks made 6 GETs and took 104.88 ms at the median, **$2.40 per
-million** at list prices: measured on S3 in-region, in the run of 2026-10-13, whose client had 128 sockets. On a spread layout it reads more
+A cold `intersect` of two 500,000-id segments sharing 100 of their 1,999 chunks made 6 GETs and took 107.87 ms at the median, **$2.40 per
+million** at list prices: measured on S3 in-region, in the run of 2026-10-30, whose client had 128 sockets. On a spread layout it reads more
 bytes than it needs, which cross-region can cost more than the requests it saves. A segment's first single-part `store.load()` made
 2 PUT + 3 GET, **$11.20 per million** at the default prices, pointer included: the requests are measured on S3 in-region, in the same run. A steady single-part `store.load()` at `keep: 12` that deletes a generation by name costs **$12.00 per million**, for 2 PUT + 5 GET and a free delete, the requests measured on S3 in-region, in the same run. A cold `count()` is one
 pointer read: it reads no payload and no object.

package/dist/bin/export-segments.js

@@ -4,7 +4,7 @@
 import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { lstat, mkdir, open, readdir, rename, rm, rmdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { encodeNameForPath, namespacePathPart } from "@cloudbitmaps/core/driver-kit";
 
@@ -3172,8 +3172,8 @@ var SystemClock = class {
   }
   sleep(ms) {
     if (ms <= 0) return Promise.resolve();
-    return new Promise((resolve) => {
-      setTimeout(resolve, ms);
+    return new Promise((resolve2) => {
+      setTimeout(resolve2, ms);
     });
   }
   /**
@@ -3200,8 +3200,8 @@ var SystemClock = class {
    * "there is outstanding work" — and `setImmediate` cannot outlive the turn that scheduled it anyway.
    */
   yieldNow() {
-    return new Promise((resolve) => {
-      setImmediate(resolve);
+    return new Promise((resolve2) => {
+      setImmediate(resolve2);
     });
   }
 };
@@ -3572,6 +3572,29 @@ var CALL_KEYS = {
     "allowAbsentOperands",
     "exclude"
   ]),
+  intersectCount: keysOf()([
+    "after",
+    "through",
+    "concurrency",
+    "budget",
+    "allowAbsentOperands",
+    "exclude"
+  ]),
+  unionCount: keysOf()([
+    "after",
+    "through",
+    "concurrency",
+    "budget",
+    "allowAbsentOperands",
+    "exclude"
+  ]),
+  andNotCount: keysOf()([
+    "after",
+    "through",
+    "concurrency",
+    "budget",
+    "allowAbsentOperands"
+  ]),
   into: keysOf()([
     "after",
     "through",
@@ -3649,6 +3672,9 @@ var MISPLACED = {
   range: outside(CALL_KEYS.into, CALL_KEYS.range),
   andNot: outside(CALL_KEYS.into, CALL_KEYS.andNot),
   combine: outside(CALL_KEYS.into, CALL_KEYS.combine),
+  intersectCount: outside(CALL_KEYS.into, CALL_KEYS.intersectCount),
+  unionCount: outside(CALL_KEYS.into, CALL_KEYS.unionCount),
+  andNotCount: outside(CALL_KEYS.into, CALL_KEYS.andNotCount),
   andNotInto: outside(CALL_KEYS.into, CALL_KEYS.andNotInto),
   exportSegments: ["codec"]
 };
@@ -4473,7 +4499,7 @@ var CloudRoaring = class _CloudRoaring {
    * duration, or fix the source first and load after. A writer that lands *during* the rewrite is caught: the
    * rewrite's publish is refused **by the fence** — the publish lands its compare-and-swap only
    * while the pointer is still on the generation the rewrite streamed — and the entry says `note: 'superseded'`,
-   * so re-run. Forward-only alone would NOT refuse it: the rewrite's number goes above everything in the bucket,
+   * so re-run. Forward-only alone would NOT refuse it: the rewrite's number goes above everything listed near the row's own numbers,
    * so the rewrite would out-rank the newer generation and then collect it.
    *
    * A racing **erasure** is caught before that, and reported the same way. It collects with `keep: 0`, taking
@@ -4711,7 +4737,8 @@ var CloudRoaring = class _CloudRoaring {
    * It deletes nothing. The generations above the new pointer stay put — which is what makes this reversible —
    * and are then *above* `currentGen`, where collection never looks, and still known to the row, so rolling forward onto
    * one needs no flag. They remain until loads pass them (the first load whose
-   * number one of them holds numbers above them all, and collection then keeps `keep` of what is below its pointer, the
+   * number one of them holds numbers above them all, those within 1,024 of what the row names and any contiguous run
+   * touching them, and collection then keeps `keep` of what is below its pointer, the
    * generation that load superseded first), {@link CloudRoaring.dropSegment}
    * 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
@@ -5088,7 +5115,8 @@ var CloudRoaring = class _CloudRoaring {
    *   the unwrapped DEK, and decrypts with them, chunks it had never fetched before the shred included, until its
    *   snapshot re-resolves: within `cache.genTtlMs` when the store has a registry and a `genTtlMs` above 0, and
    *   otherwise only when its caches let the segment go or a read has to fetch from a generation a sweep collected.
-   *   A pin answers with no timed bound, until it is told or both caches let it go.
+   *   A pin on a store with a timed refresh fails within `cache.genTtlMs` once its segment is destroyed or its
+   *   generation erased; on a store with none it answers until it is told or both caches let it go.
    * - **Another process.** Erasing on one box invalidates nothing on the others; each store bounds its own
    *   staleness by `cache.genTtlMs`, and a store with no registry (a bare `IStorageDriver`), with
    *   `cache.genTtlMs: 0`, or on a `StorageChunkSource` of your own has no bound at all: it converges only when a read happens to miss its caches. If a compliance deadline depends on every
@@ -5170,6 +5198,7 @@ var CloudRoaring = class _CloudRoaring {
       throw err;
     }
     const pinnedAt = at === null ? { generation: null, version: null, fingerprint: null } : { generation: at.generation, version: at.version, fingerprint: at.fingerprint };
+    if (at !== null) crbm.startPinChecks(pinnedAt, at.checkedAtMs);
     const pins = /* @__PURE__ */ new Map([[segmentKey(ref), pinnedAt]]);
     return makeSegment({
       engine: this.engineWithPins(pins),
@@ -5415,7 +5444,7 @@ function operandsLabel(verb) {
 }
 function refuseNoOperands(verb) {
   throw new ValidationError5(
-    verb === "intersect" ? "intersect requires at least one segment to intersect with; to read every id of one segment, use iterate()" : "intersectInto requires at least one segment to intersect with; to copy this segment into dest, call materializeMany({ operands: { src: thisSegment }, outputs: [{ dest, expr: { or: ['src'] } }], keep })"
+    verb === "intersect" ? "intersect requires at least one segment to intersect with; to read every id of one segment, use iterate()" : verb === "intersectCount" ? "intersectCount requires at least one segment to intersect with; to count one segment, use count()" : "intersectInto requires at least one segment to intersect with; to copy this segment into dest, call materializeMany({ operands: { src: thisSegment }, outputs: [{ dest, expr: { or: ['src'] } }], keep })"
   );
 }
 var AS_IDS = {
@@ -5537,7 +5566,9 @@ var Segment = class _Segment {
    * `*Into` of one throws before it reads anything. Materialise one side first, with `materializeMany({ operands: { src: seg }, outputs: [{ dest, expr: { or: ['src'] } }], keep })`.
    *
    * **A pin knows its object, not only its number.** A name purged and loaded again starts again at generation
-   * 0, so a pin of the old segment never reads the new one: what it has already read still answers, as the
+   * 0, so a pin of the old segment never reads the new one. On a store with a timed refresh the pin fails with
+   * `NotFoundError` at its next check, within `cache.genTtlMs`, what it had already read included, and `invalidate`
+   * does not bring it back: take a new pin. On a store with none, what it has already read still answers, as the
    * instant it pinned, and anything it would have to fetch fails with `NotFoundError`, as a swept pin's does.
    *
    * **It is a hold, and `pin({ leaseUntil })` makes it a bounded one.** Without a lease nothing stops a collection
@@ -5559,7 +5590,11 @@ var Segment = class _Segment {
    * segment whose row is later dropped or destroyed fails once it must open its object again, rather than go empty
    * part-way through a call. **A pin
    * keeps the key its reader unwrapped for as long as that reader stays open, and answers from the chunks it
-   * decoded for as long as they stay cached.** This store invalidates a pin:
+   * decoded for as long as they stay cached, until its next check.** On a store with a timed refresh a pin checks its
+   * segment's row every `cache.genTtlMs` (from the moment it was taken, whether or not it was read) and fails with
+   * `NotFoundError` once the segment is destroyed, is another incarnation, or its generation is collected or recorded by its row as another object (an object lost or replaced out of band
+   * under a row that still names it is found only when the pin must fetch). This
+   * store invalidates a pin:
    *
    * - a `load`, a `rollback` or an `*Into` invalidates a pin of the segment it writes;
    * - `dropSegment` invalidates a pin of the segment it drops, and `retireExpired` a pin of each segment its ledger
@@ -5572,16 +5607,18 @@ var Segment = class _Segment {
    * where the object is still there, and fails with `NotFoundError` where it is gone. It caches nothing more of what it
    * began reading before the invalidation, so the pin's next read opens the object again too.
    * Anything else leaves the pin as it is: after a `destroySegment` beside this store, or an erasure, a drop or a
-   * retirement through another store, in this process or another, the pin answers from what it holds until this
+   * retirement through another store, in this process or another, the pin answers from what it holds for at most
+   * `cache.genTtlMs` on a store with a timed refresh, and then fails. On a store with none it answers until this
    * store's reader cache evicts the pin's reader and its chunk cache evicts the chunks the pin decoded, or
    * {@link CloudRoaring.invalidate} is called on this store. A combine on another store refuses the pin. Where the
    * object the pin reads has been deleted, by an erasure, a drop or a sweep, a chunk the pin has not cached fails at
-   * once. No timed refresh bounds any of that, as none bounds anything else a pin holds.
+   * once. With no timed refresh nothing bounds any of that, as nothing bounds anything else a pin holds.
    *
-   * A replacement a pin has found is remembered, so its later chunk reads fail with no request, until the store
+   * A replacement a read of the pin found is remembered, so its later chunk reads fail with no request, until the store
    * forgets it: an invalidation of the segment does, as does a later `pin()` of the same version that opens the object
-   * again, and the store remembers at most `cache.readerMax` of them. So once a restore puts the pinned object back,
-   * call {@link CloudRoaring.invalidate} on this store: the pin then reads the object again.
+   * again; a replacement the pin's own check found is forgotten only by an invalidation. The store remembers at most `cache.readerMax` of them. So once a restore puts the pinned object back
+   * into the same row, call {@link CloudRoaring.invalidate} on this store: the pin then reads the object again. A
+   * restore into a purged and re-created row does not revive a pin on a store with a timed refresh: take a new pin.
    *
    * `pin()` reads the registry row and opens the generation at once, so the pin knows its object before its first
    * read. With a registry, pins of one generation taken while its row is unchanged share one reader while the store
@@ -6125,6 +6162,111 @@ var Segment = class _Segment {
     );
     return this.combineInto("andNotInto", dest, excludes, options);
   }
+  /**
+   * How many ids `this ∩ others…` holds (minus `exclude`): the length of what {@link intersect} streams, without
+   * streaming it. Every key all the operands hold is decoded and counted as the stream reads it, and a key only some
+   * operands hold is not read, so the call makes the requests {@link intersect} makes and returns a number instead of
+   * the ids. It is exact: it never answers a key from an index, so it trusts nothing {@link count} trusts.
+   *
+   * The range, `concurrency`, `budget`, `allowAbsentOperands` and `exclude` are {@link intersect}'s; a write option fails
+   * the call with {@link ValidationError} before any request, and so does an empty `others` (to count one segment, use
+   * {@link count}).
+   *
+   * Like a stream, a count that runs while a segment is erased or reloaded can describe two instants, within the bound
+   * the streams state. A union or a difference, and an intersection with an `exclude`, looks at its operands'
+   * generations every `concurrency` keys; an intersection with no `exclude` makes no such look, since it decodes every
+   * key and so shows a move in the chunks it decodes, as its stream does. Either way it plans again above the last key
+   * it took when one moved. A pinned handle counts the generation it pinned, and each pinned operand's object is
+   * looked up once before the first key (one footer read each, which `budget` does not charge, and which the stream
+   * does not make), and again at each look where there is one, so an erasure of what it pinned fails the count with
+   * {@link NotFoundError}; a
+   * fault the look meets other than a transient one, which is retried, is raised as it is. A call that involves a
+   * handle whose lease has ended, or has ended by the next look, throws {@link LeaseExpiredError}.
+   */
+  async intersectCount(others, options) {
+    checkOptions(
+      options,
+      "intersectCount",
+      CALL_KEYS.intersectCount,
+      ["allowAbsentOperands"],
+      MISPLACED.intersectCount
+    );
+    return this.countCombine("intersect", others, options ?? void 0);
+  }
+  /**
+   * How many ids `this ∪ others…` holds (minus `exclude`): the length of what {@link union} streams, without streaming
+   * it. A chunk key only one operand holds, that no `exclude` holds and the range does not cut, is answered from that
+   * operand's index, so a union of segments that mostly do not overlap reads little of them; every other key is
+   * decoded and counted. On handles that are not pinned it makes no more requests than {@link union} does, and reads
+   * fewer bytes when the shared keys are few. An empty `others`, with no `exclude` and no range, is {@link count} of
+   * `this`, answered from the registry row when it can be; when that figure is 0 it adds one registry read, to refuse
+   * a segment that does not exist as the stream does.
+   *
+   * What it trusts: the index, for each key it answers without decoding, as {@link count} does, so a party who can write
+   * an object's index can make that key's figure wrong; a decoded key is exact. A source with no per-chunk counts
+   * decodes every key. It takes the options {@link intersectCount} takes; the erasure bound, the lease checks and the
+   * pinned handles are as for {@link intersectCount}, a pinned operand adding a footer read before the first key and at
+   * each look. An empty `others` on a pinned handle is {@link count} of the pin, with no look.
+   */
+  async unionCount(others, options) {
+    checkOptions(
+      options,
+      "unionCount",
+      CALL_KEYS.unionCount,
+      ["allowAbsentOperands"],
+      MISPLACED.unionCount
+    );
+    return this.countCombine("union", others, options ?? void 0);
+  }
+  /**
+   * How many ids `this \ (excludes…)` holds: the length of what {@link andNot} streams, without streaming it. A chunk
+   * key of `this` that no exclude holds and the range does not cut is answered from its index and not read; a key an
+   * exclude shares is decoded and counted. On handles that are not pinned it makes no more requests than {@link andNot}
+   * does, and reads fewer bytes when the excludes overlap little of `this`. An empty `excludes`, with no range, is
+   * {@link count} of `this` (the stream of it is the whole of `this`), answered from the registry row when it can be,
+   * with one registry read added when that figure is 0.
+   *
+   * It takes the options {@link andNot} takes (every one of {@link intersectCount}'s but `exclude`, which a count of a
+   * difference has no use for, since `excludes` is its subtraction) and trusts what {@link unionCount} trusts. The
+   * erasure bound, the lease checks and the pinned handles are as for {@link intersectCount}.
+   */
+  async andNotCount(excludes, options) {
+    checkOptions(
+      options,
+      "andNotCount",
+      CALL_KEYS.andNotCount,
+      ["allowAbsentOperands"],
+      MISPLACED.andNotCount
+    );
+    return this.countCombine("andNot", excludes, options ?? void 0);
+  }
+  /** The one body of the three count methods, after each has checked its own options. */
+  async countCombine(verb, operands, options) {
+    const name = `${verb}Count`;
+    const exclude = verb === "andNot" ? NO_SEGMENTS : this.excludesOf(options);
+    const others = segmentList(
+      operands,
+      verb === "andNot" ? `${name}: \`excludes\`` : `${name}: \`others\``
+    );
+    if (verb === "intersect" && others.length === 0) refuseNoOperands("intersectCount");
+    const handles = [this, ...others, ...exclude];
+    this.assertSegments(name, verb === "andNot" ? "an exclude" : "an operand", others);
+    this.assertSegments(name, "an exclude", exclude);
+    this.assertLeases(handles);
+    const engine = this.combineEngine(handles) ?? this.engine;
+    const read = options == null ? void 0 : readOptions(options);
+    const guard2 = handles.some((h) => h.leaseHold !== void 0) ? () => this.assertLeases(handles) : void 0;
+    const opts = guard2 === void 0 ? read : { ...read, guard: guard2 };
+    const refs = others.map((o) => o.ref);
+    if (verb === "andNot") return engine.combineCount([this.ref], refs, "all", verb, opts);
+    return engine.combineCount(
+      [this.ref, ...refs],
+      exclude.map((o) => o.ref),
+      verb === "union" ? "any" : "all",
+      verb,
+      opts
+    );
+  }
   /**
    * The one body of the three combines, read as ids or as chunks. `operands` is `others` for `intersect` and
    * `union`, and `excludes` for `andNot`, which takes no `exclude` option.
@@ -6196,7 +6338,7 @@ Exports every registered segment's current generation from a local-filesystem st
 Settings come from the environment:
 
   CR_EXPORT_ROOT       (required) the LocalFsStorage root, holding storage/ and registry/
-  CR_EXPORT_OUT        (required) the output directory for the dump
+  CR_EXPORT_OUT        (required) the output directory for the dump: new or existing (never a symlink)
   CR_EXPORT_FORMAT     roaring | ndjson (default: roaring)
   CR_EXPORT_NAMESPACE  (optional) scope the export to one namespace
 
@@ -6253,6 +6395,7 @@ function parseConfig(env) {
   return { root, out, format, namespace };
 }
 async function ensureOwnDirectory(out, dir) {
+  await checkOutDirectory(out);
   await mkdir(out, { recursive: true, mode: 448 });
   try {
     await mkdir(dir, { mode: 448 });
@@ -6271,6 +6414,20 @@ async function ensureOwnDirectory(out, dir) {
     if ((found.mode & 63) !== 0) refuse("a namespace directory is open to group or others");
   }
 }
+async function checkOutDirectory(out) {
+  let found;
+  try {
+    found = await lstat(resolve(out));
+  } catch (err) {
+    if (err.code === "ENOENT") return;
+    throw err;
+  }
+  const refuse = (why) => {
+    throw new ValidationError6(`the output directory is refused: ${why}`);
+  };
+  if (found.isSymbolicLink()) refuse("it is a symbolic link");
+  if (!found.isDirectory()) refuse("it is not a directory");
+}
 var MANIFEST_NAME = "manifest.json";
 function fsSink(out) {
   return {
@@ -6339,6 +6496,7 @@ async function main(env = process.env, now = () => Date.now()) {
   await requireStoreRoot(config.root);
   const storage = new LocalFsStorage(config.root);
   const store = new CloudRoaring({ storage });
+  await checkOutDirectory(config.out);
   const priorManifest = await lstat(join(config.out, MANIFEST_NAME)).catch(() => null);
   if (priorManifest?.isDirectory() === true) {
     throw new ValidationError6(