@cloudbitmaps/roaring 0.10.0 → 0.11.0

package/dist/open-charging-storage.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A storage driver that charges every **generation open** to a per-op budget, for `eraseSubject`.
+ *
+ * The budget counts fan-out in units of one backend read. `eraseSubject`'s scan charges one unit per registered
+ * segment, but a segment whose current generation lacks the id is searched anyway: every other generation in its
+ * bucket is opened, one tail read each, and with the keep-everything default of the `*Into` verbs that is one per
+ * generation the segment ever had. Those opens are the work the scan's own count leaves out. They are counted here,
+ * at the storage port where they happen, so an open added to the erasure later is charged without anyone
+ * remembering to charge it, and no option of the public erasure call had to grow.
+ *
+ * Two opens are never charged, because the segment's unit already pays for them: the generation the row named when
+ * the scan listed it, which every erasure must read to decide membership, and an object this call wrote itself,
+ * which it reads back to verify. A refusal here comes from a read, and in an erasure the reads that can be refused
+ * come before the deletes.
+ */
+import type { GenKey, IStorageDriver, SegmentRef } from '@cloudbitmaps/core';
+export declare class OpenChargingStorage implements IStorageDriver {
+    private readonly inner;
+    private readonly charge;
+    private readonly free;
+    /**
+     * @param inner   the driver the erasure would otherwise use
+     * @param current the generation the segment's row named when it was listed, or `null` when it named none
+     * @param charge  called once per charged open; it throws to refuse
+     */
+    constructor(inner: IStorageDriver, current: number | null, charge: () => void);
+    capabilities(): ReturnType<IStorageDriver['capabilities']>;
+    putImmutable(key: GenKey, write: Parameters<IStorageDriver['putImmutable']>[1]): ReturnType<IStorageDriver['putImmutable']>;
+    getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
+    /** One `getTail` is one open: a reader takes the footer and the index from it, and reads chunks with `getRange`. */
+    getTail(key: GenKey, maxBytes: number): ReturnType<IStorageDriver['getTail']>;
+    delete(key: GenKey): Promise<void>;
+    list(ref: SegmentRef): AsyncIterable<GenKey>;
+}

package/dist/option-keys.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The keys `new CloudRoaring(options)` takes: at the top level, and inside each group whose value is an object. The
+ * constructor refuses any other key by name, because an option it ignored would do nothing and look as if it had,
+ * and the gates that read the docs' samples and the harnesses' option bags hold them to the same table. A test
+ * holds the table to the option interfaces, in both directions.
+ *
+ * NOT part of the public API. It is its own module, rather than an `export` from the barrel, so the constructor
+ * and those gates read one copy.
+ */
+export declare const OPTION_KEYS: {
+    readonly top: readonly ["storage", "cache", "encryption", "retry", "metrics", "budget", "seams"];
+    readonly cache: readonly ["maxChunks", "ttlMs", "genTtlMs", "readerMax", "readerMaxBytes"];
+    readonly encryption: readonly ["keystore", "required"];
+    readonly retry: readonly ["maxAttempts", "baseDelayMs", "maxDelayMs", "backoffFactor", "jitter", "onRetry"];
+    readonly budget: readonly ["maxRequests"];
+    readonly seams: readonly ["clock", "rng"];
+};
+/** The groups: the top-level keys whose value, when it is an object, has keys of its own. */
+export type OptionGroup = Exclude<keyof typeof OPTION_KEYS, 'top'>;

package/dist/portable/decode.d.ts

@@ -1,25 +1,24 @@
 /**
  * A decoded portable-roaring bitmap that can be queried but not modified.
  *
- * Construction parses only the headers — container payloads are read on demand, so a membership test against a
- * large bitmap touches one container rather than materializing the set.
+ * Construction checks every container once, in {@link parsePortableLayout}, which is the same check the native
+ * path runs; after that a membership test reads one container rather than materializing the set.
  */
 export declare class PortableRoaringReader {
-    private readonly bytes;
     private readonly view;
     private readonly containers;
     private constructor();
     /**
-     * Parse the headers of a portable-format bitmap.
+     * Parse and check a portable-format bitmap.
      *
-     * @throws {IntegrityError} if the cookie is unrecognized, or any header field runs past the buffer.
+     * @throws {IntegrityError} if the bytes are not a well-formed portable bitmap: see {@link parsePortableLayout}.
      */
     static decode(bytes: Uint8Array): PortableRoaringReader;
     /**
      * Total cardinality.
      *
-     * Served entirely from the descriptive header — no container payload is read, so this is O(containers) and
-     * independent of how many values the bitmap holds.
+     * Served entirely from the descriptive header, which {@link parsePortableLayout} has checked against every
+     * container's payload, so this is O(containers) and independent of how many values the bitmap holds.
      */
     count(): number;
     /** Is `value` (a `u32`) in the set? */

package/dist/portable/layout.d.ts

@@ -0,0 +1,32 @@
+/** A container of sorted `u16` values. */
+export declare const ARRAY = 0;
+/** A container of 65,536 bits. */
+export declare const BITMAP = 1;
+/** A container of `(start, length)` runs. */
+export declare const RUN = 2;
+export type ContainerKind = typeof ARRAY | typeof BITMAP | typeof RUN;
+export interface PortableContainer {
+    /** High 16 bits of every value in this container. */
+    readonly key: number;
+    /** Number of values. Stored as `cardinality - 1` on the wire, normalized here. */
+    readonly cardinality: number;
+    readonly kind: ContainerKind;
+    /** Absolute byte offset of this container's payload within the source buffer; a run container's run count. */
+    readonly offset: number;
+}
+/**
+ * Parse the portable-format bitmap in `bytes`, and check its structure.
+ *
+ * An empty buffer is the empty bitmap, as it is to the native addon, which returns one without reading a byte.
+ *
+ * @throws {IntegrityError} if the cookie is unrecognized, any field runs past the buffer, or the structure is not
+ * one a writer produces (see the module header for the list).
+ */
+export declare function parsePortableLayout(bytes: Uint8Array): PortableContainer[];
+/**
+ * {@link parsePortableLayout}'s check alone, for a caller that hands the bytes to another decoder afterwards and
+ * so has no use for the layout: it allocates nothing per container.
+ *
+ * @throws {IntegrityError} exactly where {@link parsePortableLayout} does.
+ */
+export declare function checkPortableLayout(bytes: Uint8Array): void;

package/dist/reserved-namespace.d.ts

@@ -0,0 +1,3 @@
+export declare const RESERVED_NAMESPACE_PREFIX = "cbm.due.";
+/** Throw `ValidationError` for a namespace in the reserved prefix; `undefined` and every look-alike pass. */
+export declare function refuseReservedNamespace(namespace: string | undefined): void;

package/dist/roaring-codec.d.ts

@@ -5,9 +5,14 @@ export declare class SafeBitmap implements CodecBitmap {
     static empty(): SafeBitmap;
     static fromValues(values: Iterable<number>): SafeBitmap;
     /**
-     * Validate size, then deserialize with the **portable** (validated) format.
-     * Throws `IntegrityError` if the input exceeds `maxBytes` or fails to decode — the
-     * native addon is never handed unbounded or unsafe-format input.
+     * Cap the size, check the structure, then deserialize with the **portable** format.
+     * Throws `IntegrityError` if the input exceeds `maxBytes`, is not a well-formed portable bitmap, or fails to
+     * decode — the native addon is never handed unbounded, malformed or unsafe-format input.
+     *
+     * The structural check is what makes the decoded bitmap's answers mean anything. The native deserializer
+     * bounds its reads and checks nothing else, so bytes of the right length and the wrong shape (containers or
+     * values out of order, overlapping runs, a cardinality that disagrees with the bits) decode into a bitmap
+     * whose `maximum()`, `has()` and `size` are wrong, and some of those shapes crash the process when used.
      */
     static safeDeserialize(bytes: Uint8Array, maxBytes: number): SafeBitmap;
     serialize(): Uint8Array;
@@ -31,8 +36,10 @@ export declare class SafeBitmap implements CodecBitmap {
      */
     optimize(): void;
     /**
-     * Largest value, or `undefined` when empty. O(1) — roaring reads it off the container index, so the engine's
-     * per-chunk range assertion costs one call per chunk rather than a walk per id.
+     * Largest value, or `undefined` when empty. O(1) — roaring reads it off the last container, so the engine's
+     * per-chunk range assertion costs one call per chunk rather than a walk per id. The last container holds the
+     * largest value only because {@link SafeBitmap.safeDeserialize} refuses bytes whose containers or values are
+     * out of order.
      */
     maximum(): number | undefined;
     add(value: number): void;
@@ -56,6 +63,6 @@ export declare class SafeBitmap implements CodecBitmap {
 /**
  * The roaring {@link CodecInterface} — the flagship codec, delegating to {@link SafeBitmap}'s statics. This is
  * the default the `CloudRoaring` facade injects into the engine; `core/` itself never hard-references it once a
- * caller supplies a codec. Moves to `@cloudbitmaps/roaring` when the package split lands.
+ * caller supplies a codec.
  */
 export declare const roaringCodec: CodecInterface;

package/dist/system-clock.d.ts

@@ -4,9 +4,8 @@
  * It lives outside `core/`, so `Date.now()`, `setTimeout` and `setImmediate` are allowed here; that separation is
  * the whole point of the seam, and it is lint-enforced on the other side.
  *
- * It sits in its own module rather than in `index.ts` because two places need it — the facade, and
- * `codec-bound.ts`, which pre-binds it into `bulkLoadCrbmGeneration`. Importing it from `index.ts` would put a
- * cycle between the barrel and a module the barrel re-exports.
+ * It sits in its own module rather than in `index.ts` so the facade, the tests and anything else that needs a real
+ * clock can import it without importing the whole barrel.
  */
 import type { Clock } from '@cloudbitmaps/core';
 /** Default real-time clock — lives outside `core/`, so `Date.now()` + timers are allowed here. */
@@ -19,7 +18,7 @@ export declare class SystemClock implements Clock {
      * A long CPU-bound loop in `core/` (bulk-load is the one that matters) periodically hands the loop back so a
      * co-resident HTTP server keeps answering. Measured on the **synthetic yield-primitive benchmark** — a
      * 61,035-iteration loop yielding every 1,024, isolating the primitive rather than timing a real load (the
-     * end-to-end figures are 450 ms → 19 ms; see `cooperative.ts`, which lists all three experiments):
+     * end-to-end figures are 519 ms → 24 ms; see `cooperative.ts`, which lists all three experiments):
      *
      * ```text
      *   no yield         568 ms wall   568.0 ms worst event-loop gap

package/dist/testing/conformance.d.ts

@@ -1,5 +1,5 @@
 import { SafeBitmap } from '../roaring-codec.js';
-import type { StorageChunkSource, IRegistryDriver } from '@cloudbitmaps/core';
+import type { StorageChunkSource, IRegistryDriver, IStorageDriver } from '@cloudbitmaps/core';
 /**
  * The segment every conformance seeder must write. Exported so a driver's own test file derives the name
  * instead of restating it — a second copy that drifts makes the suite query a segment nobody seeded, which
@@ -14,6 +14,26 @@ export declare function storageChunkSourceConformance(label: string, makeSource:
     chunkKey: number;
     bitmap: SafeBitmap;
 }>) => Promise<StorageChunkSource>): void;
+/** The storage-driver cases {@link storageDriverConformance} runs; an emulator that cannot model one skips it by name. */
+export type StorageDriverCase = 'write-once round trip' | 'collision' | 'collision on a large upload' | 'missing object' | 'out-of-range read' | 'tail size' | 'idempotent delete' | 'list read-after-delete';
+/**
+ * Contract tests for an {@link IStorageDriver} — the contract its doc comment lists: write-once with
+ * `WriteConflictError` on a collision, `NotFoundError` for a missing object, `ValidationError` for an out-of-range
+ * read, `getTail`'s true total size, idempotent `delete`, and a `list` that is read-after-delete. `makeDriver` MUST
+ * return a driver over an empty, isolated keyspace on each call.
+ *
+ * `skip` names the cases a backend cannot exercise (a local emulator that does not model a contract), so each
+ * skip is visible at the call site, with the reason beside it, rather than hidden in a weakened assertion.
+ */
+export declare function storageDriverConformance(label: string, makeDriver: () => IStorageDriver, options?: {
+    readonly skip?: readonly StorageDriverCase[];
+    /**
+     * Size of the object the `collision on a large upload` case writes. Pass one above the driver's single-request
+     * upload threshold to exercise its multipart or resumable path, where the write-once precondition is
+     * sent on a different request than a small object's. Omitted, the case does not run.
+     */
+    readonly largeBytes?: number;
+}): void;
 /**
  * Contract tests for an {@link IRegistryDriver}. `makeDriver` MUST return a fresh, empty, isolated driver on
  * each call. The OCC contract (create / token-fenced CAS / ABA) plus the registry's record semantics (forward

package/dist/testing/fuzz-codec.d.ts

@@ -1,9 +1,23 @@
 /**
  * Internal surface for the coverage-guided fuzz harness, CODEC half.
  *
- * Only the concrete bitmap codec lives here — the core half (`CrbmReader`, the non-public `parseIndex`,
- * `BufferReader`, `CloudRoaringError`, `DEFAULT_MAX_PAYLOAD_BYTES`) is built from `@cloudbitmaps/core`'s own
- * `src/testing/fuzz-core.ts` to `fuzz/build/fuzz-core.js`. Splitting it this way keeps the published entries
- * of both packages free of test-only exports: neither widened its public API to feed the fuzzer.
+ * The concrete bitmap codec, and the one property the harness holds every decode it accepts to. The core half
+ * (`CrbmReader`, the non-public `parseIndex`, `BufferReader`, `CloudRoaringError`, `DEFAULT_MAX_PAYLOAD_BYTES`) is
+ * built from `@cloudbitmaps/core`'s own `src/testing/fuzz-core.ts` to `fuzz/build/fuzz-core.js`. Splitting it this
+ * way keeps the published entries of both packages free of test-only exports: neither widened its public API to
+ * feed the fuzzer.
  */
-export { SafeBitmap } from '../roaring-codec.js';
+import { SafeBitmap } from '../roaring-codec.js';
+export { SafeBitmap };
+/**
+ * What an accepted decode must be: it iterates strictly ascending, `size` is the number of values it iterates, and
+ * `has` confirms what it iterates. Throws a plain `Error` otherwise, which the fuzz targets and the corpus replay
+ * report as a finding.
+ *
+ * Memory safety alone does not see a structurally broken bitmap. Bytes with containers or values out of order, or
+ * a cardinality that disagrees with the bits, decode into memory that behaves until an operation trusts one of the
+ * broken invariants, so a contract of "no crash" passes them. This fails them. It is bounded like the
+ * materialization it replaces, because a valid run-heavy bitmap is tiny on disk and can hold billions of ids, and it
+ * asks `has` of the first 4,096 values only, which is enough to reach every container a small input can hold.
+ */
+export declare function assertConsistentDecode(bm: SafeBitmap): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbitmaps/roaring",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Distributed, cloud-native Roaring Bitmaps — query and intersect billion-scale integer sets straight out of object storage, from a bounded RAM cache over immutable objects in your own bucket, at a fraction of an always-on cache.",
   "keywords": [
     "roaring",
@@ -24,7 +24,6 @@
     "segmentation",
     "audience",
     "cloud",
-    "cloud-roaring",
     "cloudbitmaps"
   ],
   "license": "Apache-2.0",
@@ -66,7 +65,7 @@
   },
   "dependencies": {
     "roaring": "2.7.0",
-    "@cloudbitmaps/core": "^0.10.0"
+    "@cloudbitmaps/core": "^0.11.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/dist/codec-bound.d.ts

@@ -1,38 +0,0 @@
-/**
- * Codec-bound wrappers over the public `@cloudbitmaps/core` entry points that need a bitmap codec.
- *
- * `core` is codec-agnostic and therefore cannot default the codec (the concrete codec lives *here*, in a package
- * that depends on core — a default over there would invert the dependency arrow). But an application using
- * `@cloudbitmaps/roaring` should never have to pass one. So this module re-binds each such entry point with
- * {@link roaringCodec} and the facade re-exports these **explicitly**, which shadows the same names coming from
- * `export * from '@cloudbitmaps/core'` (an explicit export always wins over a star export). Net effect: every
- * call signature is unchanged from before the family split — you can still call
- * `bulkLoadCrbmGeneration(driver, key, ids)` with no options at all.
- *
- * A caller who *wants* a different codec passes it explicitly; the binding only fills an absent one — via
- * `?? roaringCodec` rather than spread order, so an explicit `codec: undefined` still gets the binding
- * (`exactOptionalPropertyTypes` is off, so that call typechecks and must not fall through to the throw).
- */
-import { bulkLoadCrbmGeneration as coreBulkLoad, eraseIdFromSegment as coreEraseIdFromSegment, loadSegment as coreLoadSegment, runExport as coreRunExport } from '@cloudbitmaps/core';
-type BulkLoad = typeof coreBulkLoad;
-type LoadSegment = typeof coreLoadSegment;
-type EraseIdFromSegment = typeof coreEraseIdFromSegment;
-type RunExport = typeof coreRunExport;
-/**
- * {@link coreBulkLoad} with the roaring codec **and a real clock** pre-bound.
- *
- * The clock is what makes a large load **cooperative**: bulk-load yields the event loop periodically instead of
- * stalling the process for its whole duration (measured end-to-end at 450 ms of unbroken blocking for a 1M-id
- * load, now ~19 ms worst case). `core/` cannot
- * default it — it is timer-free by lint, which is precisely why waiting goes through the `Clock` seam — so the
- * flavor package supplies it, exactly as it supplies the codec. A caller who passes their own clock (a virtual
- * one in a simulation, say) keeps it.
- */
-export declare const bulkLoadCrbmGeneration: BulkLoad;
-/** {@link coreEraseIdFromSegment} with the roaring codec and a real (cooperative) clock pre-bound. */
-export declare const eraseIdFromSegment: EraseIdFromSegment;
-/** {@link coreRunExport} with the roaring codec pre-bound (only the `'roaring'` format needs it). */
-export declare const runExport: RunExport;
-/** {@link coreLoadSegment} with the roaring codec and a real clock pre-bound, for the same reasons as above. */
-export declare const loadSegment: LoadSegment;
-export {};

package/dist/moved-options.d.ts

@@ -1,14 +0,0 @@
-/**
- * The 0.9.x option spellings this release no longer accepts, and what to tell someone who passes one.
- *
- * NOT part of the public API. It lives in its own module — rather than as an `export` from the barrel — so
- * that the gates which must agree with it (the doc-fence scan, the harness scan, and the test that diffs this
- * table against `CloudRoaringOptions` at the previous tag) can all read ONE copy, without the migration
- * table becoming a permanent public export in the same release whose point was to shrink that surface.
- *
- * Retyping it was tried and is what this replaces: the hand-maintained copies had drifted to naming three
- * spellings no release ever shipped while omitting the five that actually went away with the live tier.
- */
-export type MovedOptionKind = 'group' | 'renamed' | 'gone';
-/** `[the 0.9.x key, what to do instead, which kind of answer that is]`. */
-export declare const MOVED_OPTIONS: ReadonlyArray<readonly [string, string, MovedOptionKind]>;