@cloudbitmaps/core 0.23.0 → 0.24.0

package/dist/{chunk-7GT632UF.js → chunk-45ML6YU4.js}

@@ -19,7 +19,7 @@ import {
   requirePositiveInteger,
   shown,
   tailBytesFit
-} from "./chunk-MVUD4R72.js";
+} from "./chunk-2B2QF4FU.js";
 
 // src/drivers/_shared/options.ts
 function checkNow(name, now) {
@@ -638,4 +638,4 @@ export {
   namespaceKeyPart,
   namespacePathPart
 };
-//# sourceMappingURL=chunk-7GT632UF.js.map
+//# sourceMappingURL=chunk-45ML6YU4.js.map

package/dist/{chunk-CGILDXGP.js → chunk-BUDAVGBI.js}

@@ -1,6 +1,6 @@
 import {
   requirePositiveInteger
-} from "./chunk-MVUD4R72.js";
+} from "./chunk-2B2QF4FU.js";
 
 // src/core/concurrency.ts
 async function mapWithConcurrency(items, limit, fn) {
@@ -70,4 +70,4 @@ export {
   mapWithConcurrency,
   boundedAll
 };
-//# sourceMappingURL=chunk-CGILDXGP.js.map
+//# sourceMappingURL=chunk-BUDAVGBI.js.map

package/dist/{chunk-GKHERVVQ.js → chunk-WPER7R2R.js}

@@ -1,7 +1,7 @@
 import {
   ValidationError,
   encodeNameForKey
-} from "./chunk-MVUD4R72.js";
+} from "./chunk-2B2QF4FU.js";
 
 // src/core/keys.ts
 var FIELD = " ";
@@ -118,4 +118,4 @@ export {
   BufferSink,
   BufferReader
 };
-//# sourceMappingURL=chunk-GKHERVVQ.js.map
+//# sourceMappingURL=chunk-WPER7R2R.js.map

package/dist/core/check.d.ts

@@ -33,7 +33,8 @@ export declare function requireFiniteNumber(value: unknown, bounds: {
 /**
  * Refuse an options bag that is not an object, or that holds a key not in `keys`, naming each such key and the keys it
  * takes. `hint`, when given, ends the message, to point at where a likely mistake belongs (`an S3 client goes in
- * \`client\``). Only the bag's own enumerable string keys are read.
+ * \`client\``). Only the bag's own enumerable string keys are read, so a key inherited through a prototype is not
+ * checked.
  */
 export declare function refuseUnknownOptions(name: string, options: unknown, keys: readonly string[], hint?: string): void;
 /**

package/dist/core/codec.d.ts

@@ -54,7 +54,7 @@ export interface CodecBitmap {
     toArray(): number[];
     /**
      * The set's values as one ascending `Uint32Array` the caller owns: what a batch read converts a chunk with, in one
-     * native step instead of one iterator step per value.
+     * step instead of one iterator step per value.
      *
      * **Optional.** A codec without it is read through its iterator, which is correct and slower.
      *
@@ -125,7 +125,7 @@ export interface EncodedChunk {
 }
 /**
  * A pluggable bitmap codec — the factory the codec-agnostic engine constructs {@link CodecBitmap}s through.
- * Implementations **must** size-cap before handing untrusted bytes to any native decoder and use a safe
+ * Implementations **must** size-cap before handing untrusted bytes to a decoder and use a safe
  * (never a trusting/frozen) deserializer — hard invariant 5.
  */
 export interface CodecInterface {
@@ -135,7 +135,7 @@ export interface CodecInterface {
     fromValues(values: Iterable<number>): CodecBitmap;
     /**
      * Size-cap (`bytes.length <= maxBytes`) then portable-deserialize. Throws `IntegrityError` when the input
-     * exceeds the cap or fails to decode — the native decoder is never handed unbounded or unsafe-format input.
+     * exceeds the cap or fails to decode — the decoder is never handed unbounded or unsafe-format input.
      *
      * "Fails to decode" includes bytes that are the right length and the wrong shape. A bitmap this returns must
      * satisfy every invariant its own operations assume (for roaring: containers and values in order, runs
@@ -161,6 +161,16 @@ export interface CodecInterface {
      * The answer is the whole check: an `owns` that answers `true` for anything lets any object through as a bitmap.
      */
     owns?(bitmap: unknown): boolean;
+    /**
+     * Whether an intersect of three or more operands should meet each chunk's operands smallest-first (by `size`).
+     *
+     * **Optional, and off by default.** A codec whose combine cost depends on the order, because an early operand that is
+     * large and of one container kind makes the running result expensive, sets it; the engine then pays one `size` read per
+     * operand per chunk to put the sparsest first. A codec whose combines cost about the same in any order, or whose
+     * `size` is expensive to read, leaves it out and keeps the operand order it was given. The answer is the
+     * same either way.
+     */
+    readonly intersectSmallestFirst?: boolean;
 }
 /**
  * Resolve a codec that a **public core entry point** was given, failing fast when it is missing.

package/dist/core/cooperative.d.ts

@@ -3,13 +3,16 @@
  *
  * Everything this library does on the hot read path is small. Bulk-load is the exception: it is the one place
  * where a single call legitimately occupies the CPU for hundreds of milliseconds, and Node has exactly one thread
- * to occupy. Measured on a 1M-id load of 65,536 chunks onto in-memory storage, on a loaded Apple M3 Pro: **518 ms
- * wall, and 519 ms during which the event loop did not turn at all** (medians of 20 fresh-process runs). Wire that to a request handler and every other in-flight request on the instance — health
+ * to occupy. Measured on the native codec of 0.23.0 (every figure in this header is the native codec's, to be
+ * re-measured on the TypeScript codec), on a 1M-id load of 65,536 chunks onto in-memory storage, on a loaded Apple M3
+ * Pro: **518 ms wall, and 519 ms during which the event loop did not turn at all** (medians of 20 fresh-process
+ * runs). Wire that to a request handler and every other in-flight request on the instance — health
  * checks included — waits out the whole load.
  *
- * The fix is not to make the work asynchronous. That was measured too, and it is a 7x *regression*: handing each
- * chunk's insert to the threadpool costs ~9 µs of dispatch against ~1.5 µs of actual work once ids are spread
- * across ~62,000 chunks (636 ms versus 92 ms). The work is genuinely CPU-bound and genuinely small per chunk;
+ * The fix is not to make the work asynchronous. That was measured too, on the native codec's threadpool insert, and
+ * it was a 7x *regression*: handing each chunk's insert to the threadpool cost ~9 µs of dispatch against ~1.5 µs of
+ * actual work once ids are spread across ~62,000 chunks (636 ms versus 92 ms). The TypeScript codec has no
+ * threadpool path. The work is genuinely CPU-bound and genuinely small per chunk;
  * the only thing wrong with it is that it never stops to let anyone else go. So the fix is to keep the work
  * synchronous and periodically hand the loop back.
  *

package/dist/core/crbm/reader.d.ts

@@ -179,7 +179,7 @@ export declare class CrbmReader {
     has(chunkKey: number): boolean;
     /**
      * Range-GET one chunk's payload, verifying its CRC32C before returning. Returns `null` if the chunk is
-     * absent. Throws `IntegrityError` on a CRC mismatch (the bytes must never reach the native
+     * absent. Throws `IntegrityError` on a CRC mismatch (the bytes must never reach the codec's
      * deserializer). The returned bytes may be shared (a small generation's chunks are kept by the reader and handed out
      * again), so callers must not change them.
      */

package/dist/core/engine.d.ts

@@ -401,7 +401,7 @@ export declare class SegmentEngine {
      * The AND (or OR) of one chunk key across all operands, minus the excludes that hold it, or `null` if empty.
      * Operand chunks are fetched **in parallel** (the spec's parallel byte-range reads).
      *
-     * The accumulator is a **clone** of the first operand's chunk, and that clone is load-bearing: every other
+     * The accumulator is a **clone** of one operand's chunk (the first, or for a codec that asks the one with the fewest values), and that clone is load-bearing: every other
      * bitmap here is the cached, shared Storage instance and must never be mutated, or the cache is poisoned for
      * every later reader. The remaining operands and the excludes are only *read* by the in-place ops, so they are
      * used as-is — one clone per key, not one per operand.

package/dist/core/erase-id.d.ts

@@ -66,7 +66,7 @@
  * its number after the winner's object was already in the bucket. Up there nothing collects it, and it was derived
  * from a generation the winner has replaced, so when the winner was another erasure it still holds the id that
  * erasure has just reported gone. That object is deleted before this call returns, once its footer matches the
- * rewrite's and a renewal of the row has refused every publish fenced on a row read before it, under the version the
+ * rewrite's (a read of it that faults is thrown instead, and the object stays) and a renewal of the row has refused every publish fenced on a row read before it, under the version the
  * footer read reported, unless {@link DISCARD_ATTEMPTS} renewals lose to other writes (a load, a rollback, a
  * retention write): then it is kept, and can hold the winner's id, until a later call takes it: any erasure that
  * rewrites the segment (this one's re-run among them, while its id is still in the current generation) numbers above it

package/dist/core/load-input.d.ts

@@ -119,6 +119,6 @@ export declare function prepareLoadInput(input: LoadInput, codec: CodecInterface
  * are copied first. An empty or detached buffer is the empty bitmap.
  *
  * @param what names the input in a refusal's message.
- * @throws {ValidationError} for anything that is not such bytes; nothing reaches the codec's native decoder then.
+ * @throws {ValidationError} for anything that is not such bytes; nothing reaches the codec's decoder then.
  */
 export declare function decodeSerialized(bytes: unknown, codec: CodecInterface, what?: string): CodecBitmap;

package/dist/core/load.d.ts

@@ -148,8 +148,8 @@ export interface LoadOptions {
      * `ValidationError`, naming its position and never the id. The object is the same, byte for byte, as an unsorted load
      * of the same ids writes under the same write identity.
      *
-     * For ids only (an iterable or an async iterable): with `{ serialized }`, `{ bitmap }` or a `RoaringBitmap32` of the
-     * flavor's own `roaring` (one from another copy loads as its ids, and takes `sorted`), and on core's
+     * For ids only (an iterable or an async iterable): with `{ serialized }`, `{ bitmap }` or a bitmap itself (an
+     * iterable with a `serialize` method, which a flavor loads as `{ bitmap }`), and on core's
      * `loadSegmentChunks`, it throws `ValidationError`, as does a value that is not a boolean, before any request.
      *
      * The ids are read after the segment's row is read and judged, and after its number and key are settled, so a load

package/dist/driver-kit.js

@@ -1,6 +1,6 @@
 import {
   mapWithConcurrency
-} from "./chunk-CGILDXGP.js";
+} from "./chunk-BUDAVGBI.js";
 import {
   DEFAULT_NAMESPACE,
   applyRegistryPatch,
@@ -18,7 +18,7 @@ import {
   validateNewRegistryRecord,
   validateRegistryPatch,
   webCryptoEntropy
-} from "./chunk-7GT632UF.js";
+} from "./chunk-45ML6YU4.js";
 import {
   CloudRoaringError,
   IntegrityError,
@@ -45,7 +45,7 @@ import {
   requireNonEmptyString,
   unsettledConflict,
   validateSegmentRef
-} from "./chunk-MVUD4R72.js";
+} from "./chunk-2B2QF4FU.js";
 
 // src/drivers/_shared/object-registry-keys.ts
 var REGISTRY_SUFFIX = ".reg";

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   boundedAll,
   mapWithConcurrency
-} from "./chunk-CGILDXGP.js";
+} from "./chunk-BUDAVGBI.js";
 import {
   BufferReader,
   KeptSegmentKeys,
@@ -9,7 +9,7 @@ import {
   segmentKey,
   segmentPrefix,
   shardOf
-} from "./chunk-GKHERVVQ.js";
+} from "./chunk-WPER7R2R.js";
 import {
   BudgetExceededError,
   CHUNK_COUNT,
@@ -99,6 +99,7 @@ import {
   rollbackKnown,
   sameIncarnation,
   sameKeys,
+  sameKnownGens,
   sizeOfFingerprint,
   sizePart,
   splitId,
@@ -115,7 +116,7 @@ import {
   validateUserRef,
   windowOf,
   withRetry
-} from "./chunk-MVUD4R72.js";
+} from "./chunk-2B2QF4FU.js";
 
 // src/core/budget.ts
 var DEFAULT_BUDGET = { maxRequests: 1e6 };
@@ -758,6 +759,23 @@ function chunkIds(chunk, chunkKey, w) {
   for (let i = 0; i < rem.length; i++) rem[i] = base + (rem[i] & MAX_REMAINDER);
   return rem;
 }
+function smallestFirst(chunks) {
+  const out = chunks.slice();
+  const sizes = out.map((c) => c.size);
+  for (let i = 1; i < out.length; i++) {
+    const c = out[i];
+    const size = sizes[i];
+    let j = i - 1;
+    while (j >= 0 && sizes[j] > size) {
+      out[j + 1] = out[j];
+      sizes[j + 1] = sizes[j];
+      j--;
+    }
+    out[j + 1] = c;
+    sizes[j + 1] = size;
+  }
+  return out;
+}
 function alignKeys(operands, mode) {
   const candidates = [];
   if (mode === "all") {
@@ -1504,7 +1522,7 @@ var SegmentEngine = class _SegmentEngine {
    * The AND (or OR) of one chunk key across all operands, minus the excludes that hold it, or `null` if empty.
    * Operand chunks are fetched **in parallel** (the spec's parallel byte-range reads).
    *
-   * The accumulator is a **clone** of the first operand's chunk, and that clone is load-bearing: every other
+   * The accumulator is a **clone** of one operand's chunk (the first, or for a codec that asks the one with the fewest values), and that clone is load-bearing: every other
    * bitmap here is the cached, shared Storage instance and must never be mutated, or the cache is poisoned for
    * every later reader. The remaining operands and the excludes are only *read* by the in-place ops, so they are
    * used as-is — one clone per key, not one per operand.
@@ -1518,10 +1536,11 @@ var SegmentEngine = class _SegmentEngine {
     const fetched = await Promise.all(reads.map((op) => this.operandChunk(op, chunkKey, moves)));
     const chunks = together ? fetched.slice(0, present.length) : fetched;
     if (mode === "all" && chunks.some((c) => c === null)) return null;
-    const first = chunks[0];
+    const ordered = mode === "all" && chunks.length > 2 && this.codec.intersectSmallestFirst === true ? smallestFirst(chunks) : chunks;
+    const first = ordered[0];
     const acc = first ? first.clone() : this.codec.empty();
-    for (let i = 1; i < chunks.length; i++) {
-      const other = chunks[i];
+    for (let i = 1; i < ordered.length; i++) {
+      const other = ordered[i];
       if (other === null || other === void 0) continue;
       if (mode === "all") {
         acc.andInPlace(other);
@@ -2301,6 +2320,22 @@ function requireCodec(codec, api) {
 // src/export/index.ts
 var UTF8 = new TextEncoder();
 var DEFAULT_NDJSON_BATCH_BYTES = 64 * 1024;
+var EXPORT_BATCH = 1 << 16;
+async function addAll(bitmap, ids) {
+  const batch = new Uint32Array(EXPORT_BATCH);
+  let held = 0;
+  let count = 0;
+  for await (const id of ids) {
+    batch[held++] = id;
+    count += 1;
+    if (held === EXPORT_BATCH) {
+      bitmap.addMany(batch);
+      held = 0;
+    }
+  }
+  if (held > 0) bitmap.addMany(batch.subarray(0, held));
+  return count;
+}
 var errMessage = (err) => err instanceof Error ? err.message : String(err);
 async function runExport(reader, registry, sink, options = {}) {
   if (sink === null || typeof sink !== "object" || typeof sink.open !== "function") {
@@ -2360,10 +2395,7 @@ async function runExport(reader, registry, sink, options = {}) {
       writer = await sink.open(ref, ext);
       if (format === "roaring") {
         const bm = requireCodec(options.codec, "runExport({ format: 'roaring' })").empty();
-        for await (const id of ids) {
-          bm.add(id);
-          count += 1;
-        }
+        count = await addAll(bm, ids);
         if (count === 0 && await rowIsGone(ref)) return await skipGone(ref, writer);
         const out = bm.serialize();
         await writer.write(out);
@@ -2974,7 +3006,7 @@ var CrbmReader = class _CrbmReader {
   }
   /**
    * Range-GET one chunk's payload, verifying its CRC32C before returning. Returns `null` if the chunk is
-   * absent. Throws `IntegrityError` on a CRC mismatch (the bytes must never reach the native
+   * absent. Throws `IntegrityError` on a CRC mismatch (the bytes must never reach the codec's
    * deserializer). The returned bytes may be shared (a small generation's chunks are kept by the reader and handed out
    * again), so callers must not change them.
    */
@@ -3357,8 +3389,9 @@ async function provenObject(storage, key, fingerprint) {
       version ??= tail.version;
     });
     return await CrbmReader.sameObject(blob, fingerprint) ? { version } : null;
-  } catch {
-    return null;
+  } catch (err) {
+    if (isNotFoundError(err)) return null;
+    throw err;
   }
 }
 function sameObjectUnder(storage, key, fingerprint) {
@@ -3409,12 +3442,7 @@ async function footerCrcUnder(storage, key) {
   return (await readFooter(storageBlobReader(storage, key))).footerCrc;
 }
 async function provesOwnObject(storage, key, fingerprint) {
-  try {
-    return await CrbmReader.sameObject(storageBlobReader(storage, key), fingerprint);
-  } catch (err) {
-    if (isNotFoundError(err)) return false;
-    throw err;
-  }
+  return await provenObject(storage, key, fingerprint) !== null;
 }
 var openedVersions = /* @__PURE__ */ new WeakMap();
 function openGenerationReader(storage, key, crypto, options = {}, named) {
@@ -7271,7 +7299,7 @@ var KeyBits = class {
 };
 
 // src/core/combine-ledger.ts
-var RESIDENT_BITMAP_OVERHEAD = 512;
+var RESIDENT_BITMAP_OVERHEAD = 832;
 var MAX_CHUNK_SERIALIZED = 8208;
 function serializedBound(cardinality) {
   return Math.min(2 * cardinality + 16, MAX_CHUNK_SERIALIZED);
@@ -7279,7 +7307,7 @@ function serializedBound(cardinality) {
 var MAX_RESIDENT_DATA = 8800;
 function residentBytes(serialized) {
   return Math.ceil(
-    RESIDENT_BITMAP_OVERHEAD + Math.min(1.6 * serialized, serialized + 2e3, MAX_RESIDENT_DATA)
+    RESIDENT_BITMAP_OVERHEAD + Math.min(1.6 * serialized, serialized + 2200, MAX_RESIDENT_DATA)
   );
 }
 function residentBound(cardinality) {
@@ -9681,7 +9709,8 @@ async function fence(c, plan) {
     const ledger = usableKnownGens(row);
     const doomed = doomedGenerations(c, plan, byName, ledger, pointer);
     const named = ledger !== void 0 && ledger.some((e) => doomed.has(e.generation));
-    const renew = byName.length > 0;
+    const sweepOwes = plan.sweeps && !named && row.pointerId === record.pointerId && sameKnownGens(row.knownGens, record.knownGens);
+    const renew = byName.length > 0 || sweepOwes;
     const renewedAfter = held && row.pointerId !== first.pointerId;
     if (!named && (!renew || renewedAfter)) {
       c.premise = row;
@@ -10039,6 +10068,34 @@ async function stage(c) {
     throw err;
   }
 }
+async function provenOwn(c, key, fingerprint) {
+  const { deps } = c;
+  const retry = deps.readRetry;
+  const base = retry?.isRetryable ?? isTransientError;
+  let fault;
+  try {
+    return await retryRead(
+      async () => {
+        try {
+          return await provenObject(deps.storage, key, fingerprint);
+        } catch (err) {
+          if (!isIntegrityError(err)) fault = err;
+          throw err;
+        }
+      },
+      retry === void 0 ? void 0 : {
+        ...retry,
+        isRetryable: (err) => isIntegrityError(err) || base(err),
+        onRetry: (info) => {
+          if (!isIntegrityError(info.err)) retry.onRetry?.(info);
+        }
+      }
+    );
+  } catch (err) {
+    if (isIntegrityError(err) && fault === void 0) return null;
+    throw fault ?? err;
+  }
+}
 async function discardRefused(c, own) {
   const { ref, deps, base, from } = c;
   const key = { ...base, generation: own.generation };
@@ -10055,7 +10112,7 @@ async function discardRefused(c, own) {
     }
     if (row === null || row.status !== "active" || row.currentGen === null) return row;
     if (row.currentGen <= from || row.currentGen >= own.generation) return row;
-    const proven = await provenObject(deps.storage, key, own.fingerprint);
+    const proven = await provenOwn(c, key, own.fingerprint);
     if (proven === null) return row;
     const renewed = await renewal.renew(row);
     if ("row" in renewed) {