@cloudbitmaps/roaring 0.25.0 → 0.27.0

package/dist/index.d.ts

@@ -163,7 +163,13 @@ export interface CacheOptions {
      * lapses, a read of it fails with the fault, as a cold read does. A refresh that fails with anything else, an access denial or a row that will not parse, is not
      * ridden out: the read that meets it throws that error, and the reader is dropped.
      *
-     * `0` turns this timed refresh off, and so does wiring a bare `IStorageDriver`, which has no registry. That is
+     * **A pinned handle is checked on the same interval.** It never moves to another generation, but at most every
+     * `genTtlMs` (counted on access) its segment's row is read, one read shared by every pin of the segment, and the
+     * pin fails with `NotFoundError` once the segment is destroyed, gone or re-created, or its generation erased or
+     * collected, or recorded by its row as another object, even when its reader and chunks are still cached. A transient
+     * fault of the registry, or of the footer read an erasure's check makes, keeps it serving.
+     *
+     * `0` turns this timed refresh off, and the pinned handles' check with it, and so does wiring a bare `IStorageDriver`, which has no registry. That is
      * all it does. The store still moves a segment on to whatever generation is current when its reader cache
      * evicts the segment, when a read has to fetch from a generation a sweep deleted, and when it is invalidated,
      * as its own `load`, `rollback`, `eraseSubject` and `*Into` writes do and {@link CloudRoaring.invalidate} does.
@@ -889,7 +895,7 @@ export declare 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
@@ -1057,7 +1063,8 @@ export declare 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
@@ -1366,7 +1373,8 @@ export declare 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
@@ -1777,7 +1785,9 @@ export declare 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
@@ -1799,7 +1809,11 @@ export declare 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
@@ -1812,16 +1826,18 @@ export declare 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
@@ -2128,6 +2144,59 @@ export declare class Segment {
      * {@link ValidationError} before any request.
      */
     andNotInto(dest: Segment, excludes: Segment[], options?: CombineOptions): Promise<MaterializeResult>;
+    /**
+     * 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}.
+     */
+    intersectCount(others: Segment[], options?: CombineOptions): Promise<number>;
+    /**
+     * 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.
+     */
+    unionCount(others: Segment[], options?: CombineOptions): Promise<number>;
+    /**
+     * 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}.
+     */
+    andNotCount(excludes: Segment[], options?: CombineOptions): Promise<number>;
+    /** The one body of the three count methods, after each has checked its own options. */
+    private countCombine;
     /**
      * 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.

package/dist/index.js

@@ -3973,6 +3973,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",
@@ -4050,6 +4073,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"]
 };
@@ -4874,7 +4900,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
@@ -5112,7 +5138,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
@@ -5489,7 +5516,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
@@ -5571,6 +5599,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),
@@ -5816,7 +5845,7 @@ function operandsLabel(verb) {
 }
 function refuseNoOperands(verb) {
   throw new ValidationError6(
-    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 = {
@@ -5938,7 +5967,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
@@ -5960,7 +5991,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
@@ -5973,16 +6008,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
@@ -6526,6 +6563,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.