@cloudbitmaps/roaring 0.19.1 → 0.20.0

package/dist/index.js

@@ -23,8 +23,6 @@ import {
   excludingReservedRows,
   dropSegment,
   eraseIdFromSegment,
-  estimateCost,
-  groundedReport,
   judgeLoad,
   loadSegment,
   loadSegmentChunks,
@@ -45,7 +43,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 {
@@ -78,8 +76,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);
@@ -648,10 +647,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. */
@@ -773,23 +769,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 = []) {
@@ -1141,22 +1121,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) {
@@ -1190,13 +1172,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
@@ -1561,7 +1550,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) {
@@ -1606,7 +1595,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;
@@ -1626,10 +1615,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
@@ -1651,13 +1644,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
@@ -1852,8 +1853,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.
    *
@@ -1922,10 +1924,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
@@ -2138,8 +2142,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),
@@ -2363,7 +2367,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.
    *
@@ -2399,15 +2404,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) => {
@@ -2804,8 +2800,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
@@ -2824,17 +2820,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() {
@@ -3124,38 +3133,8 @@ 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."]
-    });
-  }
 };
 export {
-  AWS_US_EAST_1_ONDEMAND,
   BudgetExceededError,
   BufferReader,
   CapabilityError,
@@ -3165,7 +3144,6 @@ export {
   CrbmReader,
   CrbmStorageChunkSource2 as CrbmStorageChunkSource,
   DEFAULT_RETRY_POLICY2 as DEFAULT_RETRY_POLICY,
-  ELASTICACHE_REDIS_US_EAST_1_ONDEMAND,
   InProcessKeystore,
   IntegrityError3 as IntegrityError,
   KeyUnavailableError,
@@ -3179,7 +3157,6 @@ export {
   MemoryStorage,
   NodeAead,
   NotFoundError2 as NotFoundError,
-  ONE_REDIS_HA_CLUSTER,
   RecordingAuditSink,
   Segment,
   StaleOperandError,