@cloudbitmaps/core 0.23.0 → 0.25.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

@@ -16,9 +16,9 @@
  * different codecs, or a cached bitmap from codec A could reach codec B's in-place op. The `CloudRoaring` facade
  * mints the cache per store, so this cannot arise in normal use.)
  *
- * **Interface surface = exactly what the engine needs**, kept general enough for the known fast-follow codecs
- * (positional/rank-select access + raw-bitset interop that `@cloudbitmaps/bitset` will add live on that
- * package's own extended value type, not here — the engine never calls them). The one codec-linked concern
+ * **Interface surface = exactly what the engine needs**, and nothing a codec might one day offer: an operation the
+ * engine never calls (positional or rank/select access, say) is not on {@link CodecBitmap}, and a second codec that
+ * has such operations would carry them on its own value type. The one codec-linked concern
  * this seam intentionally leaves in the format layer is the `.crbm` **payload codec id**
  * (`PAYLOAD_CODEC_ROARING_PORTABLE` / `KNOWN_PAYLOAD_CODEC_IDS` in `crbm/format.ts`): it is stamped in the footer
  * and validated on read, as membership of a registry rather than equality with one constant, so a codec-specific
@@ -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.
  *
@@ -19,7 +22,7 @@
  *    the microtask queue drains to empty before the event loop advances a single phase. A loop awaiting them
  *    yields to other *microtasks* and to nothing else; no pending I/O callback runs. Measured: 555 ms of
  *    starvation against a 568 ms unyielded baseline **on the synthetic yield-primitive benchmark below** —
- *    a different, smaller workload than the 442 ms end-to-end load above, which is why the two baselines
+ *    a different, smaller workload than the 518 ms end-to-end load above, which is why the two baselines
  *    differ. The yield must be a **macrotask** — hence
  *    `Clock.yieldNow`, backed by `setImmediate` in production wiring.
  * 2. **Yielding per unit of work costs more than the work.** The yield has to be periodic, and `everyN` has to be

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

@@ -115,10 +115,16 @@ export declare function prepareLoadInput(input: LoadInput, codec: CodecInterface
  * input of a load goes through, and what a flavor offers its users to decode bytes they hold themselves.
  *
  * The bytes must be a `Uint8Array` (a Node `Buffer` is one), at most {@link MAX_SERIALIZED_LOAD_BYTES}, one whole
- * bitmap and structurally sound. A view is read over the bytes it really holds, and bytes in a `SharedArrayBuffer`
- * are copied first. An empty or detached buffer is the empty bitmap.
+ * bitmap and structurally sound. A view is read over the bytes it really holds, once, and the size checks, the
+ * copy and the decode all use that one view. Bytes in a `SharedArrayBuffer` are copied first. An empty or detached
+ * buffer is the empty bitmap, unless `refuseEmpty` is set.
  *
  * @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.
+ * @param options `maxBytes` lowers the size cap for this call (it cannot raise it); `refuseEmpty` refuses an empty or
+ * detached buffer, which is not a bitmap.
+ * @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;
+export declare function decodeSerialized(bytes: unknown, codec: CodecInterface, what?: string, options?: {
+    readonly maxBytes?: number;
+    readonly refuseEmpty?: boolean;
+}): 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.d.ts

@@ -24,7 +24,7 @@ export { BoundedLru } from './core/lru.js';
 export { safeMetrics } from './core/metrics.js';
 export { runExport } from './export/index.js';
 export type { SegmentReader } from './export/index.js';
-export { splitId } from './core/bit-route.js';
+export { splitId, refusalOfId } from './core/bit-route.js';
 export { mapWithConcurrency } from './core/concurrency.js';
 export { resolveBudget, resolvePerOpBudget, checkBudget, collectWithinBudget } from './core/budget.js';
 export { segmentExists, listSegments } from './core/discover.js';
@@ -43,7 +43,7 @@ export { compileCombineMany, rebindCombineMany, runCombineMany } from './core/co
 export type { CombineManyDeps, CombineManyFeed, CombineManyOperand, CombineManyOutcome, CombineManyOutput, CombineManyRequest, CombineManyRun, CombineManyWrite, CompiledCombineMany, Expr, MaterializeManyFeedRecord, MaterializeManyOperandStats, MaterializeManyOutputStats, MaterializeManyStats, } from './core/combine-many.js';
 export type { LoadDeps, LoadOptions, LoadGuard, GuardRefusal, LoadJudgement, LoadResult, LoadRefusal, } from './core/load.js';
 export type { LoadInput, PortableBitmap } from './core/load-input.js';
-export { decodeSerialized } from './core/load-input.js';
+export { decodeSerialized, MAX_SERIALIZED_LOAD_BYTES } from './core/load-input.js';
 export { listGenerations, rollbackSegment } from './core/rollback.js';
 export type { GenerationListDeps, GenerationEntry, RollbackResult } from './core/rollback.js';
 export { eraseIdFromSegment, findIdUnderTombstone } from './core/erase-id.js';