@cloudbitmaps/core 0.24.0 → 0.26.0

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

package/dist/core/cooperative.d.ts

@@ -22,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-storage-source.d.ts

@@ -405,9 +405,15 @@ export declare class CrbmStorageChunkSource implements StorageChunkSource {
      * ({@link replacedPins}), and a check under way is shared by the reads that ask at once; neither "gone" nor "the
      * same" is kept, since either can change. A transient fault is rethrown, for the store's retries to see for what it
      * is. A footer that cannot be read otherwise says nothing about which object is there, so this returns, and the
-     * caller's own error stands.
+     * caller's own error stands; a caller with no error of its own passes `strict`, and that fault is raised.
      */
     private throwIfReplaced;
+    /**
+     * Throws the pin's `NotFoundError` when the object under `generation`'s key is no longer the one `held` names: one
+     * footer read, shared with a check already under way for the same pin. It fails closed: a footer that cannot be read,
+     * or an object that is not a generation object of this store, raises its own fault rather than passing.
+     */
+    verifyHeld(ref: SegmentRef, generation: number, held: PinnedObject): Promise<void>;
     /** Chunk keys of a specific generation — the pinned shape read. `held` as for {@link getChunkAt}. */
     listChunkKeysAt(ref: SegmentRef, generation: number, held?: PinnedObject): Promise<number[]>;
     /**

package/dist/core/engine.d.ts

@@ -101,6 +101,14 @@ export interface CombinedChunk {
     readonly chunkKey: number;
     readonly bitmap: CodecBitmap;
 }
+/** Options of {@link SegmentEngine.combineCount}: a combine's, and a check the count runs at its start and at each look. */
+export interface CountOptions extends CombineOptions {
+    /**
+     * Runs before the first key and at each look, and may throw to stop the count (a lease that has ended). A count
+     * answered from the index fetches no chunk, so this is where such a handle is held to its terms.
+     */
+    readonly guard?: () => void;
+}
 export declare class SegmentEngine {
     private readonly storage;
     private readonly cache;
@@ -397,6 +405,51 @@ export declare class SegmentEngine {
     private combineBatches;
     /** The chunk read: the plan every combine shares, then each key's result, cut to the range at its edges. */
     private combineChunks;
+    /**
+     * How many ids `segs[0] ∩ …` (`mode` 'all') or `segs[0] ∪ …` ('any') holds, minus `excludeSegs`, without streaming
+     * them: the size of what {@link combine} would stream. Each chunk key is taken one of two ways. A key exactly one
+     * include holds, that no exclude holds and the range does not cut, is answered from the index's count for it, with
+     * no chunk read. Every other key is decoded and counted as the combine reads it, with the same plan, the same ranges
+     * and the same window, over those keys alone. So an intersection reads what its stream reads, and a union or a
+     * difference reads no more than its stream.
+     *
+     * The keys answered from the index are trusted as {@link count} trusts the index, and checked no further than the
+     * reader checks it when it opens the object; a decoded key is exact. A source that reports no per-chunk counts has
+     * every key decoded. A union or a difference of one operand with no exclude and no range is {@link count}.
+     *
+     * A running union or difference, or an intersection with an `exclude`, looks at its operands' versions every
+     * `concurrency` keys, a key answered from the index being one taken, and any count looks before the first key after
+     * an invalidation, and runs `options.guard` at each look. On a move it plans again above the last key taken, as a
+     * combine does, so the bound on what it serves of an earlier generation is the combine's. A pinned operand's object
+     * is looked up before the first key and at each look there is (one footer read each, a fault other than a transient
+     * one raised as it is), so an erasure of what it pinned stops the count there with the pin's `NotFoundError`. An
+     * intersection of two or more operands with no exclude decodes every key and so shows a move without a version
+     * look; its guard still runs every `concurrency` keys.
+     */
+    combineCount(segs: readonly SegmentRef[], excludeSegs: readonly SegmentRef[], mode: 'all' | 'any', op: 'intersect' | 'union' | 'andNot', options?: Omit<CountOptions, 'exclude'>): Promise<number>;
+    /** Take every step of `run`: the index's figure for one, the size of the next decoded chunk for another. */
+    private runCount;
+    /** Run the guard every `limit` keys when the version looks are off (an AND of two or more includes). */
+    private guardAtCadence;
+    /**
+     * Look up each pinned operand's generation object, as a pinned read finds it: one footer read per pinned operand, and
+     * the pin's `NotFoundError` when the object is gone or is another. An operand that is not pinned costs nothing.
+     */
+    private verifyPinned;
+    /** Look at every operand's version, as {@link nextSlotAfterLook} does, and plan the keys above `last` again on a move. */
+    private countLook;
+    /**
+     * {@link combineOperands} for a count: each include also carries the per-chunk counts of the generation its keys were
+     * listed from. The counts are asked for after the keys, and the two must name the same keys, or the operand is listed
+     * again (a move between the two reads), and refused if a source keeps disagreeing with itself. A source with no
+     * per-chunk counts gives none, and every key of that operand is decoded.
+     */
+    private countOperands;
+    /**
+     * The per-chunk counts of `seg`, checked as untrusted tier data; `undefined` when the source reports none, and `'moved'`
+     * when they name other keys than `listed`, which the segment's generation changing between the two reads explains.
+     */
+    private chunkCounts;
     /**
      * 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).

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.
+ * @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/pinned-storage-source.d.ts

@@ -112,5 +112,7 @@ export declare class PinnedStorageChunkSource implements StorageChunkSource {
      */
     currentVersion(ref: SegmentRef): Promise<string | null>;
     exists(ref: SegmentRef): Promise<boolean>;
+    /** Whether the object this segment's pin holds is still there: see {@link HeldObjectLookup.verifyPinned}. */
+    verifyPinned(ref: SegmentRef): Promise<void>;
     invalidate(ref: SegmentRef): void;
 }

package/dist/core/ports.d.ts

@@ -147,7 +147,9 @@ export interface StorageChunkSource {
      * already-parsed `.crbm` index with **no payload reads**, or `null` if the segment has no Storage generation.
      * Powers the free `count()` of a source with no {@link StorageChunkSource.summary} — the engine sums the index
      * instead of fetching a single chunk. A source with no
-     * index (e.g. the in-memory source) omits this, and `count()` falls back to fetching every chunk.
+     * index (e.g. the in-memory source) omits this, and `count()` falls back to fetching every chunk. A count of a
+     * combine also asks for it, and takes its keys to be the ones `listChunkKeys` names for the same generation (an emptied
+     * chunk is named by both or by neither), listing again when they differ and refusing a source that keeps disagreeing.
      */
     cardinalities?(ref: SegmentRef): Promise<ReadonlyMap<number, number> | null>;
     /**
@@ -227,6 +229,19 @@ export interface StorageChunkSource {
      */
     currentVersion?(ref: SegmentRef): Promise<string | null>;
 }
+/**
+ * What a source that reads pinned generations also offers the engine, apart from {@link StorageChunkSource}: a lookup of
+ * the object a pin holds. Not part of the port a source implements; the engine asks for it when it is there.
+ */
+export interface HeldObjectLookup {
+    /**
+     * Resolves when the segment is not pinned here, or when the object its pin holds is still under its key; rejects with
+     * the pin's `NotFoundError` when it is gone or is another object, and with the fault itself when the footer cannot be
+     * read or is not a generation object's (a transient fault is for the caller's retries). One footer read for a pinned
+     * segment, none for any other.
+     */
+    verifyPinned(ref: SegmentRef): Promise<void>;
+}
 /** Capabilities a Storage driver advertises; validated at wiring time, fail-fast. */
 export interface StorageCaps {
     /** REQUIRED — the format relies on byte-range reads. */

package/dist/driver-kit.js

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

package/dist/drivers/retry/retrying-chunk-source.d.ts

@@ -51,6 +51,7 @@ export declare class RetryingStorageChunkSource implements StorageChunkSource {
     readonly invalidate?: (ref: SegmentRef) => void;
     readonly exists?: (ref: SegmentRef) => Promise<boolean>;
     readonly currentVersion?: (ref: SegmentRef) => Promise<string | null>;
+    readonly verifyPinned?: (ref: SegmentRef) => Promise<void>;
     constructor(inner: StorageChunkSource, opts: RetryingOptions);
     getChunk(ref: ChunkRef): Promise<Uint8Array | null>;
     listChunkKeys(ref: SegmentRef): Promise<number[]>;

package/dist/index.d.ts

@@ -19,12 +19,12 @@
  * publishable on its own and every codec reuses one driver set with zero duplication.
  */
 export { SegmentEngine } from './core/engine.js';
-export type { EngineDeps, CombineOptions as EngineCombineOptions, IdRange } from './core/engine.js';
+export type { EngineDeps, CombineOptions as EngineCombineOptions, CountOptions as EngineCountOptions, IdRange, } from './core/engine.js';
 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';