@cloudbitmaps/roaring 0.21.0 → 0.23.0

package/dist/roaring-codec.d.ts

@@ -1,16 +1,4 @@
-/**
- * SafeBitmap — the thin wrapper around the `roaring` (CRoaring) engine that owns the
- * untrusted-bytes boundary.
- *
- * All (de)serialization uses the **portable** format — the stable, bounds-checked one. The
- * `unsafe_frozen_*` formats are never used (they are explicitly documented as crash/attack
- * vectors). Every deserialize is preceded by a hard size cap and a structural check, because the native
- * portable deserializer bounds its reads and checks nothing else (see `portable/layout.ts`).
- */
-import roaring from 'roaring';
-import type { CodecBitmap, CodecInterface, EncodedChunk, LoadInput } from '@cloudbitmaps/core';
-declare const RoaringBitmap32: typeof roaring.RoaringBitmap32;
-type RoaringBitmap32 = InstanceType<typeof RoaringBitmap32>;
+import type { CodecBitmap, CodecInterface, EncodedChunk, LoadInput, PortableBitmap } from '@cloudbitmaps/core';
 export declare class SafeBitmap implements CodecBitmap {
     private readonly bitmap;
     private constructor();
@@ -31,8 +19,6 @@ export declare class SafeBitmap implements CodecBitmap {
     static safeDeserialize(bytes: Uint8Array, maxBytes: number, options?: {
         readonly whole?: boolean;
     }): SafeBitmap;
-    /** The `roaring` bitmap this wraps, for a caller that was handed it once and keeps no wrapper. */
-    unwrap(): RoaringBitmap32;
     serialize(): Uint8Array;
     /**
      * Convert containers to run-encoding where that is smaller. Representation only — membership is untouched, and
@@ -96,9 +82,10 @@ export declare class SafeBitmap implements CodecBitmap {
     toUint32Array(): Uint32Array;
 }
 /**
- * A bare `RoaringBitmap32` of this package's own `roaring`, passed where ids go, loads as `{ bitmap }`: from its
- * containers, through the same check as any bytes, never id by id. Any other input passes through unchanged, and a
- * bitmap from another copy of `roaring` is loaded as the ids it iterates, which is correct and slower.
+ * A bare `RoaringBitmap32` of this package's own `roaring`, or a bitmap {@link deserializePortable} returned, passed
+ * where ids go, loads as `{ bitmap }`: from its containers, through the same check as any bytes, never id by id. Any
+ * other input passes through unchanged, and a bitmap from another copy of `roaring` is loaded as the ids it
+ * iterates, which is correct and slower.
  */
 export declare function bitmapAsLoadInput(input: LoadInput): LoadInput;
 /**
@@ -108,11 +95,25 @@ export declare function bitmapAsLoadInput(input: LoadInput): LoadInput;
  */
 export declare const roaringCodec: CodecInterface;
 /**
- * Decode portable Roaring bytes you hold into a `RoaringBitmap32`, through the check a `{ serialized }` load makes
- * first: a size cap, a structural check, one whole bitmap, and only then the native decoder.
+ * A decoded bitmap that can only be read: what {@link deserializePortable} returns. Its ids come out ascending when
+ * it is iterated, which is a promise. It is a `PortableBitmap`, so a load takes it as `{ bitmap }`, and the library
+ * keeps no reference to it. What {@link deserializePortable} returns has these members only: a call to any other
+ * throws `TypeError`, it has no `getSerializationSizeInBytes`, and `serialize` takes exactly `'portable'`. Its class
+ * is not part of the contract: do not cast it and do not test it with `instanceof`. Passed to a method of the `roaring`
+ * package from npm in place of a `RoaringBitmap32`, it answers wrongly: decode its bytes first. `JSON.stringify` of one gives `"{}"`; write
+ * `JSON.stringify([...bitmap])`. For the rest of a Roaring library's API, decode its portable bytes with that library.
+ */
+export interface ReadonlyBitmap extends PortableBitmap, Iterable<number> {
+    /** How many ids it holds. */
+    readonly size: number;
+    /** Whether it holds `id`. */
+    has(id: number): boolean;
+}
+/**
+ * Decode portable Roaring bytes you hold into a {@link ReadonlyBitmap}, through the check a `{ serialized }` load
+ * makes first: a size cap, a structural check, one whole bitmap, and only then the native decoder.
  *
  * @param bytes a `Uint8Array`, which a Node `Buffer` is.
  * @throws {ValidationError} for bytes that are not exactly one well-formed portable bitmap, as a load refuses them.
  */
-export declare function deserializePortable(bytes: Uint8Array): RoaringBitmap32;
-export {};
+export declare function deserializePortable(bytes: Uint8Array): ReadonlyBitmap;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbitmaps/roaring",
-  "version": "0.21.0",
+  "version": "0.23.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",
@@ -48,7 +48,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -65,7 +66,7 @@
   },
   "dependencies": {
     "roaring": "2.7.0",
-    "@cloudbitmaps/core": "^0.21.0"
+    "@cloudbitmaps/core": "0.23.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/dist/bin/export-segments.d.ts

@@ -1,25 +0,0 @@
-#!/usr/bin/env node
-import type { ExportFormat, ExportManifest, ExportSink } from '../index.js';
-export interface ExportConfig {
-    readonly root: string;
-    readonly out: string;
-    readonly format: ExportFormat;
-    readonly namespace?: string;
-}
-/** Parse + validate config from an environment map. Throws a {@link ValidationError} on misconfiguration. */
-export declare function parseConfig(env: Record<string, string | undefined>): ExportConfig;
-/**
- * A filesystem {@link ExportSink}. Writes each segment to a **unique** `<segment><ext>.<uuid>.part` temp
- * (`O_EXCL` create, mode `0o600`) and atomically renames it into `<out>/<namespace>/<segment><ext>` on `close()`,
- * so a half-written file never masquerades as complete and concurrent exports to the same dir can't clobber one
- * another. Uses a `FileHandle` (not `createWriteStream`) so an I/O fault **rejects the write** rather than
- * emitting an unhandled `'error'` event that would crash the process, and loops on short writes so a partial
- * `write()` never truncates the output. Artifacts are **owner-only** (dir `0o700`, files `0o600`) — cleartext.
- *
- * A namespace named `manifest.json`, in any letter case, is refused with a `ValidationError`, so each of its segments
- * lands in `failed`: its directory would take the manifest's path. Aborting a segment also removes its namespace
- * directory when that leaves it empty.
- */
-export declare function fsSink(out: string): ExportSink;
-/** CLI entry: build a LocalFs store, export every enumerated segment, then write the manifest. */
-export declare function main(env?: Record<string, string | undefined>, now?: () => number): Promise<ExportManifest>;

package/dist/lease-guards.d.ts

@@ -1,46 +0,0 @@
-/**
- * The checks a stream makes of a lease: before its first pull, and each time it reads a chunk. Kept apart from the store
- * so each can be held on its own, and so a stream of another shape (a rank read, a plain iterable of ids) is wrapped by
- * the same function.
- *
- * ```
- *   caller ── next() ──> guarded stream ── next() ──> engine's stream
- *                         │  check before the first pull
- *                         │  check again at each chunk (or each item)
- *                         └─ a throwing check ends the engine's stream, then rejects
- *   return() / throw() ─────────────────────────────> engine's stream (ended / thrown into)
- * ```
- *
- * A guarded stream is its own iterator and single-use, as the engine's generator it wraps is: it answers `next`,
- * `return` and `throw`, and iterating it gives it back.
- */
-/** An async iterator that is also its own iterable, with `return` and `throw` always present, as a generator's are. */
-interface GuardedStream<T> extends AsyncIterableIterator<T> {
-    return(value?: unknown): Promise<IteratorResult<T, unknown>>;
-    throw(err: unknown): Promise<IteratorResult<T, unknown>>;
-}
-/** What an id stream is, as far as a guard is concerned: ids, and the same ids a chunk at a time. */
-interface IdStream extends AsyncIterable<number> {
-    batches(): AsyncIterable<Uint32Array>;
-}
-/** An id stream that is guarded: the per-id stream is an iterator of its own, and `batches()` is guarded too. */
-type GuardedIds = GuardedStream<number> & {
-    batches(): GuardedStream<Uint32Array>;
-};
-/**
- * A stream of ascending ids that checks a lease before it first pulls, and each time it reads a chunk after that: once
- * the engine has the next chunk and before an id of it is yielded, so nothing of a chunk fetched past the lease is
- * served. Ids ascend, so a chunk is entered when `id >>> 16` changes. The check before the first pull is what stops a
- * stream built while the lease was live, and pulled after it ended, ending empty without ever checking. A throw ends the
- * engine's reads. Used only when a handle in the call holds a lease: a call with none returns the engine's stream
- * untouched. It takes any async iterable of ids, so a stream with no `.batches()` (a rank read) is wrapped the same way.
- */
-export declare const guardIdIterable: (inner: AsyncIterable<number>, check: () => void) => GuardedStream<number>;
-/** {@link guardIdIterable} for an `IdStream`, whose `.batches()` is guarded too. */
-export declare const guardIds: (inner: IdStream, check: () => void) => GuardedIds;
-/**
- * A stream of chunks that checks a lease before the first pull and before each item is handed on: an item is one
- * chunk (a batch of ids, or a chunk an `*Into` writes).
- */
-export declare const guardItems: <T>(inner: AsyncIterable<T>, check: () => void) => GuardedStream<T>;
-export {};

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

@@ -1,37 +0,0 @@
-/**
- * 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. Most of an erasure's reads that can be refused come
- * before its deletes; two kinds come after one: the look for a holder left once the call has deleted, and the zero-byte
- * read of a generation the call deleted that the row then names. A refusal of either is thrown in place of the call's
- * answer, so the call reports the budget, not what it deleted.
- */
-import type { GenKey, IStorageDriver, SegmentRef, StorageDeleteOptions } 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']>;
-    /** Handed through whole: the erasure's delete of a holder is conditioned on the object it searched. */
-    delete(key: GenKey, options?: StorageDeleteOptions): Promise<void>;
-    list(ref: SegmentRef): AsyncIterable<GenKey>;
-}

package/dist/option-keys.d.ts

@@ -1,19 +0,0 @@
-/**
- * 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/options.d.ts

@@ -1,30 +0,0 @@
-/**
- * The shape checks every call that takes an options bag makes before it reads or writes anything: the bag is an
- * object, it names only keys the call takes, and each switch is a boolean. The per-call key tables stay with the
- * facade, because each is held to the options type it describes.
- */
-import { ValidationError } from '@cloudbitmaps/core';
-/** A key of `T` that `K` does not list: a key table missing one fails to compile. */
-type Unlisted<T, K extends readonly PropertyKey[]> = Exclude<keyof T, K[number]>;
-/** The keys of `T`, every one of them, as a table the options check below reads. */
-export declare const keysOf: <T>() => <const K extends readonly (keyof T & string)[]>(keys: K & ([Unlisted<T, K>] extends [never] ? unknown : never)) => readonly string[];
-/** How a value of the wrong kind is named in a message: by its kind, never by its content. */
-export declare const kindOf: (v: unknown) => string;
-/**
- * Why `options` cannot be a call's options, or `undefined` when it can. `undefined` and `null` read as none; anything
- * but an object is refused, and so is a key `known` does not list, unless its value is `undefined`, so a spread of
- * options keeps working; and each of `booleans` present must be a boolean, `null` included. A bag of the wrong shape, a misspelt key or
- * a switch given as a string would otherwise read as no option at all, and silently widen what the call does: a scope
- * passed as a string swept every namespace, and `dryRun: 'true'` deleted.
- */
-export declare function optionsError(options: unknown, op: string, known: readonly string[], booleans?: readonly string[]): ValidationError | undefined;
-/**
- * The keys of `options` a call takes, each read by name. A spread copies only own enumerable properties, so an option
- * held in a getter or inherited from a prototype, which TypeScript accepts and {@link optionsError} reads, would pass
- * the checks and then be dropped: a `dryRun` so held ran a real sweep, and a `namespace` exported every tenant. The
- * call then reads the copy only, so it runs with exactly what was checked.
- */
-export declare function picked<T extends object>(options: T | null | undefined, keys: readonly string[]): Partial<T>;
-/** {@link optionsError}, thrown: for a call that rejects, rather than one that returns a stream. */
-export declare function checkOptions(options: unknown, op: string, known: readonly string[], booleans?: readonly string[]): void;
-export {};

package/dist/portable/decode.d.ts

@@ -1,54 +0,0 @@
-/**
- * A decoded portable-roaring bitmap that can be queried but not modified.
- *
- * 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.
- */
-declare class PortableRoaringReader {
-    private readonly view;
-    private readonly containers;
-    private constructor();
-    /**
-     * Parse and check a portable-format bitmap.
-     *
-     * @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, 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? */
-    has(value: number): boolean;
-    /** Binary search the descriptive header for the container owning `key`. */
-    private findContainer;
-    /**
-     * 1,024 little-endian `u64` words. Read as `u32` at `(low >> 5) * 4`: a LE `u64` is two LE `u32`s with the
-     * low word first, so the 32-bit view lands on the right half without any 64-bit arithmetic.
-     */
-    private bitmapHas;
-    /**
-     * Sorted `u16` values — binary search.
-     *
-     * The `at === low` early return means the `at < low` below is only ever evaluated when `at !== low`, so
-     * writing it `at <= low` would behave identically. That is recorded because mutation testing surfaced it as
-     * a surviving mutant: it is an *equivalent* one, unkillable by any test rather than a coverage gap — three
-     * non-equivalent mutations of these same lines (inverting the branches, never reporting a hit, dropping the
-     * last element) are all caught. Do not "fix" the survivor, and do not add a test chasing it.
-     */
-    private arrayHas;
-    /**
-     * `u16` run count, then that many `(start, length)` `u16` pairs sorted by start.
-     *
-     * `length` is the number of values **after** `start`, so a run covers the inclusive range
-     * `[start, start + length]` and a single-value run is stored with length 0. Getting this off by one is the
-     * easiest mistake in the format and is why the differential test drives runs specifically.
-     */
-    private runHas;
-}
-/** Convenience wrapper over {@link PortableRoaringReader.decode}. */
-export declare function decodePortableRoaring(bytes: Uint8Array): PortableRoaringReader;
-export {};

package/dist/portable/layout.d.ts

@@ -1,52 +0,0 @@
-import type { EncodedChunk } from '@cloudbitmaps/core';
-/** 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. */
-declare const RUN = 2;
-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.
- *
- * @returns where the bitmap ends: the offset one past its last container's last byte (0 for an empty buffer). A
- * caller that needs the buffer to be exactly one bitmap compares it with the buffer's length.
- * @throws {IntegrityError} exactly where {@link parsePortableLayout} does.
- */
-export declare function checkPortableLayout(bytes: Uint8Array): number;
-/**
- * Each container of the portable bitmap in `bytes`, as the one-container portable bitmap a `.crbm` chunk stores:
- * its key moved to 0, its cardinality and kind kept, its body copied unchanged. These are exactly the bytes the
- * native serializer writes for a bitmap holding only that container's low 16 bits, so a chunk cut from a whole
- * bitmap is the chunk built from its ids, provided the whole bitmap was encoded canonically first.
- *
- * Lazy, one container per step, and each container checked as it is copied, by the same rules as
- * {@link checkPortableLayout} (keys in order, and each body holding what its header says), so a stored chunk is
- * never one a reader refuses. The bytes are the native serializer's, of a bitmap decoded from bytes that passed the
- * check, so on every honest input this finds nothing. It is what stands between a store and a bitmap decoded from a
- * buffer another thread was still writing during the load's call: the check saw the bytes as they were, the decode
- * as they became.
- *
- * @throws {IntegrityError} at the first container that runs past the buffer or does not hold what its header says.
- */
-export declare function containerPayloads(bytes: Uint8Array): Generator<EncodedChunk>;
-export {};

package/dist/reserved-namespace.d.ts

@@ -1,3 +0,0 @@
-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/system-clock.d.ts

@@ -1,39 +0,0 @@
-/**
- * The default real-time {@link Clock} — the production half of the determinism seam.
- *
- * 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` 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. */
-export declare class SystemClock implements Clock {
-    now(): number;
-    sleep(ms: number): Promise<void>;
-    /**
-     * `setImmediate`, and it has to be — this is the one place where the choice of primitive is the whole feature.
-     *
-     * 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 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
-     *   sleep(0)         555 ms wall   555.2 ms   ← a microtask. Yields NOTHING.
-     *   setImmediate     569 ms wall    13.8 ms   ← free, and 41x less starvation
-     *   setTimeout(1)    625 ms wall    15.0 ms   ← +10% wall for no extra relief
-     * ```
-     *
-     * `sleep(0)` resolving on a microtask is correct for its own contract and useless for this: microtasks drain
-     * before the loop ever advances a phase, so `await sleep(0)` in a tight loop never lets a single pending I/O
-     * callback run. `setImmediate` fires in the check phase *after* pending I/O, which is exactly the ordering a
-     * server wants — inbound requests are serviced before the loop resumes chewing.
-     *
-     * A timer is not ref'd here (unlike {@link sleep}): a yield expresses "someone else may go first", never
-     * "there is outstanding work" — and `setImmediate` cannot outlive the turn that scheduled it anyway.
-     */
-    yieldNow(): Promise<void>;
-}

package/dist/testing/conformance.d.ts

@@ -1,118 +0,0 @@
-import { SafeBitmap } from '../roaring-codec.js';
-import type { StorageChunkSource, IRegistryDriver, IStorageDriver, SegmentRef } 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
- * fails as an empty result rather than as the mismatch it actually is.
- */
-export declare const CONFORMANCE_SEGMENT = "s:v1";
-/**
- * Contract tests for a {@link StorageChunkSource}. `makeSource` MUST build a fresh source seeded with the
- * given chunks (each an immutable Storage bitmap) and nothing else.
- */
-export declare function storageChunkSourceConformance(label: string, makeSource: (chunks: Array<{
-    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' | 'delete of an absent key beside its neighbours' | 'list read-after-delete' | 'names and namespaces kept apart' | 'generations by number' | 'failed write' | 'missing location' | 'list across pages' | 'conditional 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` (of an absent key too, with neighbours present) after which a
- * read of the key is `NotFoundError` at once, a `list` that is read-after-delete, and a `delete` given `ifVersion` that does what `conditionalDelete` says. `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;
-    /**
-     * A driver over a bucket or container that does not exist, built fresh on each call. The `missing location` case
-     * holds it to failing a range read, a tail read, a delete and a listing with an error that is neither
-     * `NotFoundError` nor `TransientError`: read as an absence, a misnamed or deleted bucket answers every read of the
-     * store as an empty segment. Omitted, the case does not run.
-     */
-    readonly missingLocation?: () => IStorageDriver;
-    /**
-     * How many generations the `list across pages` case writes and lists back. Pass more than one listing page of the
-     * driver under test (S3 and GCS list 1,000 a page, Azure Blob 5,000, a test double what it is built with), so a
-     * driver that drops its continuation token fails. Omitted, the case does not run.
-     */
-    readonly pagedListSize?: number;
-    /**
-     * What the driver under test reports as `capabilities().conditionalDelete` once it has made a delete given
-     * `ifVersion`, which is when a driver that resolves it lazily has resolved it. Stated at the call site, so a driver
-     * that stops applying the condition fails here rather than being exempted by its own report. Omitted, the case
-     * holds the driver to whatever it reports.
-     */
-    readonly conditionalDelete?: boolean;
-}): 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
- * currentGen, status, clearable keyId, discovery).
- */
-export declare function registryConformance(label: string, makeDriver: () => IRegistryDriver, options?: {
-    /**
-     * A driver over a bucket or container that does not exist, built fresh on each call. The `missing location` case
-     * holds it to failing a read, a listing and a create with an error that is neither `NotFoundError` nor
-     * `TransientError`, and never answering a read with `null`: read as an absent row, a misnamed or deleted bucket
-     * answers every segment as one with no generation. Omitted, the case does not run.
-     */
-    readonly missingLocation?: () => IRegistryDriver;
-    /**
-     * How many rows the `list across pages` case creates and lists back. Pass more than one listing page of the driver
-     * under test (S3 and GCS list 1,000 a page, Azure Blob 5,000, a test double what it is built with), so a driver
-     * that drops its continuation token fails. Omitted, the case does not run.
-     */
-    readonly pagedListSize?: number;
-}): void;
-/**
- * Contract tests for an {@link IRegistryDriver} under **concurrent writers** — `makeDrivers` MUST return two
- * independent driver instances over the **same** backing store, as two processes would see it.
- *
- * This exists because {@link registryConformance} drives one driver sequentially, and `ObjectStoreRegistry`
- * checks the OCC token in memory before it ever issues a conditional write. That in-process check answers
- * every sequential case, so the store-level precondition — the only thing that fences writers *across*
- * processes, and the entire reason these drivers are built on conditional writes — is never load-bearing
- * there. A backend that accepted `If-Match` and ignored it passed the full suite; so did a GCS driver whose
- * writes were not fenced at all. These cases are what make the fence testable.
- */
-export declare function registryConcurrency(label: string, makeDrivers: () => readonly [IRegistryDriver, IRegistryDriver]): void;
-/**
- * What {@link registryDeleteConformance} needs to see past the port: the driver, and the backend behind it.
- *
- * `stored` says whether the backend still holds anything for a row, a tombstone included. Through the port a deleted
- * row and a tombstoned one look the same (`get` answers `null`, `list` skips both); what tells them apart is whether
- * a later full listing still has an object to read, which is the cost a hard delete exists to remove.
- */
-export interface RegistryDeleteHarness {
-    readonly driver: IRegistryDriver;
-    /** Whether the backend holds anything for `ref`: a live row, or the tombstone a delete left in its place. */
-    stored(ref: SegmentRef): Promise<boolean>;
-    /**
-     * Put `text` at `ref`'s row, as another writer left it: here, a row stamped with an earlier schema. Omitted by a
-     * registry that persists nothing a test can plant (the in-memory one).
-     */
-    plantRow?(ref: SegmentRef, text: string): Promise<void>;
-}
-/**
- * Contract tests for what `delete` leaves behind, which differs by driver and is declared by
- * `capabilities().conditionalDelete`:
- *
- * - **`true`**: a delete removes the row from the backend for good, and does so only while the row is still the
- *   version it read.
- * - **`false` or absent**: every delete leaves a tombstone, which a later full listing still reads.
- *
- * Either way `get` answers `null` afterwards, `list` skips the row, and a name created again is a new incarnation that
- * refuses every token an earlier one held.
- */
-export declare function registryDeleteConformance(label: string, make: () => RegistryDeleteHarness): void;

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

@@ -1,23 +0,0 @@
-/**
- * Internal surface for the coverage-guided fuzz harness, CODEC half.
- *
- * 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`, `DEFAULT_MAX_BITMAP_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.
- */
-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/dist/wire-store.d.ts

@@ -1,38 +0,0 @@
-import type { Clock, IMetricsSink, IKeystore, IRegistryDriver, IStorageDriver, RetryPolicy, RetryingOptions, Rng, StorageChunkSource } from '@cloudbitmaps/core';
-/** The slice of a store's options the wiring reads; `CloudRoaringOptions` satisfies it. */
-interface StoreWiring {
-    readonly storage: unknown;
-    readonly encryption?: {
-        readonly keystore?: IKeystore;
-        readonly required?: boolean;
-    };
-    readonly cache?: {
-        readonly genTtlMs?: number;
-        readonly readerMax?: number;
-        readonly readerMaxBytes?: number;
-    };
-    readonly retry?: (Partial<RetryPolicy> & {
-        readonly onRetry?: (info: {
-            attempt: number;
-            delayMs: number;
-            err: unknown;
-        }) => void;
-    }) | false;
-}
-/** What {@link wireStore} builds for the constructor. */
-interface WiredStore {
-    /** What the engine reads through: the source, wrapped in the read retry unless it is off. */
-    readonly storage: StorageChunkSource;
-    /** The resolved source before the retry wrapper. */
-    readonly source: StorageChunkSource;
-    readonly driver: IStorageDriver | undefined;
-    readonly registry: IRegistryDriver | undefined;
-    /** The read retry the store shares with its lifecycle reads; `undefined` when retry is off. */
-    readonly retryOptions: RetryingOptions | undefined;
-}
-/**
- * Resolve the storage seam, hand a backend the metrics sink, and wrap the source in the read retry. Refusals come in
- * that order: a bad `storage` first, then a bad `retry`.
- */
-export declare function wireStore(options: StoreWiring, clock: Clock, rng: Rng, metrics: IMetricsSink): WiredStore;
-export {};