@cloudbitmaps/core 0.24.0 → 0.26.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   boundedAll,
   mapWithConcurrency
-} from "./chunk-BUDAVGBI.js";
+} from "./chunk-7VNEBKC4.js";
 import {
   BufferReader,
   KeptSegmentKeys,
@@ -9,7 +9,7 @@ import {
   segmentKey,
   segmentPrefix,
   shardOf
-} from "./chunk-WPER7R2R.js";
+} from "./chunk-MNXTZJZ6.js";
 import {
   BudgetExceededError,
   CHUNK_COUNT,
@@ -116,7 +116,7 @@ import {
   validateUserRef,
   windowOf,
   withRetry
-} from "./chunk-2B2QF4FU.js";
+} from "./chunk-UFOMYONZ.js";
 
 // src/core/budget.ts
 var DEFAULT_BUDGET = { maxRequests: 1e6 };
@@ -183,7 +183,7 @@ async function refuseAbsent(op, candidates, limit, exists, nameOf) {
 // src/core/chunk-checks.ts
 function assertChunkKeyInRange(k) {
   if (!Number.isInteger(k) || k < 0 || k >= CHUNK_COUNT) {
-    throw new IntegrityError(`chunk key from a tier is out of range: ${k}`);
+    throw new IntegrityError("a chunk key from a tier is out of range");
   }
 }
 function assertChunkCardinalityInRange(c) {
@@ -206,22 +206,22 @@ function checkedChunkKeys(listed2) {
   keys.sort((a, b) => a - b);
   for (let i = 1; i < keys.length; i++) {
     if (keys[i] === keys[i - 1]) {
-      throw new IntegrityError(`chunk key from a tier is listed twice: ${keys[i]}`);
+      throw new IntegrityError("a chunk key from a tier is listed twice");
     }
   }
   return keys;
 }
-function assertChunkPayloadInRange(bitmap, chunkKey) {
+function assertChunkPayloadInRange(bitmap) {
   const max = bitmap.maximum?.();
   if (max !== void 0 && max > MAX_REMAINDER) {
     throw new IntegrityError(
-      `chunk ${chunkKey} payload holds value ${max}, outside the 16-bit remainder range [0, ${MAX_REMAINDER}] \u2014 the stored object is corrupt or was not written by this codec`
+      `a chunk payload holds a value outside the 16-bit remainder range [0, ${MAX_REMAINDER}] (a container key other than 0) \u2014 the stored object is corrupt or was not written by this codec`
     );
   }
 }
-function decodeChunkBytes(codec, bytes, chunkKey, maxBitmapBytes) {
+function decodeChunkBytes(codec, bytes, maxBitmapBytes) {
   const bitmap = codec.safeDeserialize(bytes, maxBitmapBytes);
-  assertChunkPayloadInRange(bitmap, chunkKey);
+  assertChunkPayloadInRange(bitmap);
   return bitmap;
 }
 
@@ -238,12 +238,10 @@ var ChunkStream = class {
     return this.iterator.next().then(
       (step) => {
         if (step.done === true) {
-          throw this.failure?.error ?? new IntegrityError(`chunk stream ended before chunk ${key}`);
+          throw this.failure?.error ?? new IntegrityError("chunk stream ended before a chunk it was opened over");
         }
         if (step.value.key !== key) {
-          throw new IntegrityError(
-            `chunk stream answered chunk ${step.value.key} where ${key} was due`
-          );
+          throw new IntegrityError("chunk stream answered a chunk other than the one due");
         }
         return step.value;
       },
@@ -676,6 +674,7 @@ var COMBINE_WINDOW_START = 8;
 var COMBINE_RANGE_START = 4;
 var OPERANDS_AT_ONCE = 16;
 var BATCH_QUIET_HOPS = 16;
+var COUNT_RELIST_ATTEMPTS = 4;
 var ZERO_CLOCK = { now: () => 0 };
 var CombineWindow = class {
   constructor(keys, limit, read) {
@@ -799,6 +798,19 @@ function combineReads(keys, operands, excludes, mode, through) {
   }
   return units;
 }
+function countSteps(operands, excludes, mode, w) {
+  const steps = [];
+  const decode = [];
+  for (const key of alignKeys(operands, mode)) {
+    const holders = mode === "all" ? operands : operands.filter((o) => o.keys.has(key));
+    const only = holders.length === 1 ? holders[0] : void 0;
+    const n = only?.cards?.get(key);
+    const viaIndex = n !== void 0 && !excludes.some((e) => e.keys.has(key)) && !(w !== null && isEdge(key, w));
+    steps.push({ key, n: viaIndex ? n : -1 });
+    if (!viaIndex) decode.push(key);
+  }
+  return { steps, decode };
+}
 var SegmentEngine = class _SegmentEngine {
   storage;
   cache;
@@ -1201,9 +1213,7 @@ var SegmentEngine = class _SegmentEngine {
     const expected = counts.get(chunkKey);
     if (chunk === null || chunk.size !== expected) {
       const got = chunk === null ? "no bytes" : `${chunk.size} ids`;
-      throw new IntegrityError(
-        `chunk ${chunkKey} holds ${got}, but the object's index says ${expected}`
-      );
+      throw new IntegrityError(`a chunk holds ${got}, but the object's index says ${expected}`);
     }
     return chunk.toUint32Array ? chunk.toUint32Array() : Uint32Array.from(chunk);
   }
@@ -1518,6 +1528,209 @@ var SegmentEngine = class _SegmentEngine {
       this.closeCombine(run.plan);
     }
   }
+  /**
+   * 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.
+   */
+  async combineCount(segs, excludeSegs, mode, op, options) {
+    const label = `${op}Count`;
+    if (segs.length === 0) throw new ValidationError(`${label} requires at least one segment`);
+    const limit = options?.concurrency === void 0 ? DEFAULT_INTERSECT_CONCURRENCY : options.concurrency;
+    requirePositiveInteger(limit, `${label}: concurrency`);
+    const budget = resolvePerOpBudget(options?.budget, this.budget);
+    const w = windowOf2(options, label);
+    options?.guard?.();
+    if (w === "empty") return 0;
+    if (op !== "intersect" && segs.length === 1 && excludeSegs.length === 0 && w === null) {
+      const n = await this.count(segs[0]);
+      if (n === 0) {
+        const none = {
+          seg: segs[0],
+          keys: /* @__PURE__ */ new Set(),
+          chunkless: true,
+          gen: void 0,
+          epoch: 0
+        };
+        await this.refuseAbsentOperands([none], options?.allowAbsentOperands, label);
+      }
+      return n;
+    }
+    const epoch = this.scope.epoch;
+    const [operands, excludes] = await this.countOperands(segs, excludeSegs, mode, w, -1);
+    await this.refuseAbsentOperands(
+      [...operands, ...excludes],
+      options?.allowAbsentOperands,
+      label
+    );
+    await this.verifyPinned([...operands, ...excludes]);
+    const { steps, decode } = countSteps(operands, excludes, mode, w);
+    checkBudget(budget, combineReads(decode, operands, excludes, mode, Infinity), label);
+    if (this.metricsOn) {
+      const distinct = /* @__PURE__ */ new Set();
+      for (const o of [...operands, ...excludes]) for (const k of o.keys) distinct.add(k);
+      this.metrics.onEvent({
+        kind: "intersect",
+        op,
+        operands: segs.length + excludes.length,
+        fetchedChunks: decode.length,
+        skippedChunks: distinct.size - decode.length
+      });
+    }
+    const everyKey = mode === "all" && segs.length > 1 && excludeSegs.length === 0;
+    const run = {
+      segs,
+      excludeSegs,
+      mode,
+      op,
+      limit,
+      budget,
+      w,
+      plan: this.openCombine(operands, excludes, mode, decode, limit),
+      looks: this.looks(everyKey ? Infinity : limit, epoch),
+      spent: 0,
+      steps,
+      at: 0,
+      guard: options?.guard,
+      ...everyKey && options?.guard !== void 0 ? { guardEvery: { since: 0 } } : {}
+    };
+    try {
+      return await this.runCount(run);
+    } finally {
+      this.closeCombine(run.plan);
+    }
+  }
+  /** Take every step of `run`: the index's figure for one, the size of the next decoded chunk for another. */
+  async runCount(run) {
+    let total = 0;
+    let last = -1;
+    while (run.at < run.steps.length) {
+      run.looks.left -= 1;
+      if (run.guardEvery !== void 0) this.guardAtCadence(run);
+      if (run.plan.moves.moved || this.lookDue(run.looks)) {
+        await this.countLook(run, last);
+        if (run.at >= run.steps.length) break;
+      }
+      const step = run.steps[run.at++];
+      last = step.key;
+      if (step.n >= 0) {
+        total += step.n;
+        continue;
+      }
+      const slot = await run.plan.window.next();
+      const chunk = slot?.result;
+      if (chunk === null || chunk === void 0 || chunk.isEmpty) continue;
+      total += run.w !== null && isEdge(step.key, run.w) ? cutToWindow(this.codec, chunk, step.key, run.w).size : chunk.size;
+    }
+    return total;
+  }
+  /** Run the guard every `limit` keys when the version looks are off (an AND of two or more includes). */
+  guardAtCadence(run) {
+    const cadence = run.guardEvery;
+    if (cadence.since >= run.limit) {
+      cadence.since = 0;
+      run.guard();
+    }
+    cadence.since += 1;
+  }
+  /**
+   * 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.
+   */
+  async verifyPinned(operands) {
+    const verify = this.storage.verifyPinned;
+    if (verify === void 0) return;
+    await boundedAll(operands, OPERANDS_AT_ONCE, (o) => verify.call(this.storage, o.seg));
+  }
+  /** Look at every operand's version, as {@link nextSlotAfterLook} does, and plan the keys above `last` again on a move. */
+  async countLook(run, last) {
+    const plan = run.plan;
+    plan.moves.moved = false;
+    this.looked(run.looks);
+    run.guard?.();
+    const all = [...plan.operands, ...plan.excludes];
+    await this.verifyPinned(all);
+    const now = await boundedAll(all, OPERANDS_AT_ONCE, (o) => this.cacheVersion(o.seg));
+    if (now.every((version, i) => version === all[i].gen)) return;
+    this.closeCombine(plan);
+    const spent = run.spent + combineReads(plan.keys, plan.operands, plan.excludes, run.mode, last);
+    const [operands, excludes] = await this.countOperands(
+      run.segs,
+      run.excludeSegs,
+      run.mode,
+      run.w,
+      last
+    );
+    const { steps, decode } = countSteps(operands, excludes, run.mode, run.w);
+    checkBudget(
+      run.budget,
+      spent + combineReads(decode, operands, excludes, run.mode, Infinity),
+      `${run.op}Count`
+    );
+    run.plan = this.openCombine(operands, excludes, run.mode, decode, run.limit);
+    run.spent = spent;
+    run.steps = steps;
+    run.at = 0;
+  }
+  /**
+   * {@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.
+   */
+  async countOperands(segs, excludeSegs, mode, w, after) {
+    const wantCounts = !(mode === "all" && segs.length > 1);
+    const extract = async (seg, withCounts) => {
+      for (let attempt = 0; attempt < COUNT_RELIST_ATTEMPTS; attempt++) {
+        const { listed: listed2, gen, epoch } = await this.listKeys(seg);
+        const cards = withCounts ? await this.chunkCounts(seg, listed2) : void 0;
+        if (cards === "moved") continue;
+        const keys = after < 0 && w === null ? listed2 : keysAbove(listed2, w, after);
+        return { seg, keys: new Set(keys), chunkless: listed2.length === 0, gen, epoch, cards };
+      }
+      throw new IntegrityError("a segment's index and its chunk keys name different chunks");
+    };
+    const all = await boundedAll(
+      [
+        ...segs.map((s) => [s, wantCounts]),
+        ...excludeSegs.map((s) => [s, false])
+      ],
+      OPERANDS_AT_ONCE,
+      ([seg, withCounts]) => extract(seg, withCounts)
+    );
+    return [all.slice(0, segs.length), all.slice(segs.length)];
+  }
+  /**
+   * 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.
+   */
+  async chunkCounts(seg, listed2) {
+    const counts = this.storage.cardinalities ? await this.storage.cardinalities(seg) : null;
+    if (counts === null) return void 0;
+    if (counts.size !== listed2.length) return "moved";
+    for (const key of listed2) {
+      const n = counts.get(key);
+      if (n === void 0) return "moved";
+      if (n !== 0) assertChunkCardinalityInRange(n);
+    }
+    return counts;
+  }
   /**
    * 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).
@@ -1871,7 +2084,7 @@ var SegmentEngine = class _SegmentEngine {
         streamed.moves.moved = true;
       }
       if (read.bytes === null) return null;
-      const bitmap = decodeChunkBytes(this.codec, read.bytes, chunkKey, this.maxBitmapBytes);
+      const bitmap = decodeChunkBytes(this.codec, read.bytes, this.maxBitmapBytes);
       if (this.cache && !streamed.invalidated && !this.scope.invalidatedSince(streamed.prefix, streamed.openedAt)) {
         const version = this.streamedVersion(streamed.gen, read.version);
         if (version !== null) {
@@ -2084,7 +2297,7 @@ var SegmentEngine = class _SegmentEngine {
       }
     }
     if (!bytes) return null;
-    const bitmap = decodeChunkBytes(this.codec, bytes, ref.chunkKey, this.maxBitmapBytes);
+    const bitmap = decodeChunkBytes(this.codec, bytes, this.maxBitmapBytes);
     if (key !== "" && this.scope.isOpen(cacheKey, token)) this.cache?.set(key, bitmap);
     return bitmap;
   }
@@ -2545,7 +2758,7 @@ function* planChunkReads(extents, region) {
   for (const extent of extents) {
     const extentEnd = extent.offset + extent.length;
     if (!(Number.isSafeInteger(extent.offset) && Number.isSafeInteger(extent.length) && extent.length >= 1 && extent.offset >= previousEnd && extentEnd <= region.end)) {
-      throw crbmIntegrity(`chunk ${extent.key} is not inside the chunk region, in order`);
+      throw crbmIntegrity("a chunk is not inside the chunk region, in order");
     }
     previousEnd = extentEnd;
     if (chunks.length > 0 && extent.offset - end <= MAX_COALESCE_GAP_BYTES && extentEnd - start <= MAX_COALESCED_READ_BYTES) {
@@ -2569,7 +2782,7 @@ function* planChunkReads(extents, region) {
 var U32_CEIL = U32_MAX + 1;
 function varintLength(value) {
   if (!Number.isInteger(value) || value < 0 || value >= U32_CEIL) {
-    throw new RangeError(`varint value must be a u32; got ${value}`);
+    throw new RangeError("varint value must be a u32");
   }
   if (value < 128) return 1;
   if (value < 16384) return 2;
@@ -3016,7 +3229,7 @@ var CrbmReader = class _CrbmReader {
     const offset = this.index.offsets[slot];
     const length = this.index.lengths[slot];
     if (offset < PAYLOAD_START || offset + length > this.objectSize - FOOTER_BYTES) {
-      throw crbmIntegrity(`chunk ${chunkKey} payload out of bounds`);
+      throw crbmIntegrity(`chunk at position ${slot} payload out of bounds`);
     }
     const held = this.keptRange(offset, length);
     return this.openChunk(slot, chunkKey, held ?? await this.blob.getRange(offset, length));
@@ -3043,11 +3256,11 @@ var CrbmReader = class _CrbmReader {
    */
   openChunk(slot, chunkKey, bytes) {
     if (crc32c(bytes) !== this.index.crcs[slot]) {
-      throw crbmIntegrity(`chunk ${chunkKey} payload CRC mismatch`);
+      throw crbmIntegrity(`chunk at position ${slot} payload CRC mismatch`);
     }
     if (this.crypto === void 0) return bytes;
     if (bytes.length < AEAD_NONCE_BYTES + AEAD_TAG_BYTES) {
-      throw crbmIntegrity(`chunk ${chunkKey} encrypted payload too short`);
+      throw crbmIntegrity(`chunk at position ${slot} encrypted payload too short`);
     }
     return this.crypto.aead.open(
       {
@@ -3293,19 +3506,20 @@ function parseIndex(indexBytes, payloadEnd, maxPayloadBytes, minPayloadBytes = 1
     const chunkKey = prevKey + keyDelta;
     const offset = prevEnd + offDelta;
     if (i > 0 && keyDelta === 0) {
-      throw crbmIntegrity(`.crbm index has a duplicate chunkKey ${chunkKey}`);
+      throw crbmIntegrity(`.crbm index entry ${i} repeats a chunk key`);
     }
-    if (chunkKey > 65535) throw crbmIntegrity(`.crbm chunkKey ${chunkKey} out of range`);
+    if (chunkKey > 65535)
+      throw crbmIntegrity(`.crbm index entry ${i} has a chunk key out of range`);
     if (len < minPayloadBytes || len > maxPayloadBytes) {
       throw crbmIntegrity(
-        `.crbm chunk ${chunkKey} length ${len} invalid (most is ${maxPayloadBytes})`
+        `.crbm index entry ${i} has a payload length ${len} invalid (most is ${maxPayloadBytes})`
       );
     }
     if (card < 1 || card > MAX_CHUNK_CARDINALITY) {
-      throw crbmIntegrity(`.crbm chunk ${chunkKey} cardinality ${card} invalid`);
+      throw crbmIntegrity(`.crbm index entry ${i} has a cardinality ${card} invalid`);
     }
     if (offset + len > payloadEnd) {
-      throw crbmIntegrity(`.crbm chunk ${chunkKey} payload out of bounds`);
+      throw crbmIntegrity(`.crbm index entry ${i} has a payload out of bounds`);
     }
     keys[count] = chunkKey;
     cardinalityMinusOne[count] = card - 1;
@@ -4464,9 +4678,9 @@ var CrbmStorageChunkSource = class {
    * ({@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.
    */
-  async throwIfReplaced(ref, generation, version, fingerprint) {
+  async throwIfReplaced(ref, generation, version, fingerprint, strict = false) {
     const held = this.heldKey(ref, version, fingerprint);
     if (this.replacedPins.get(held) !== void 0) throw notThePinned(ref, generation);
     let check = this.checking.get(held);
@@ -4494,11 +4708,20 @@ var CrbmStorageChunkSource = class {
     try {
       replaced = await check;
     } catch (err) {
-      if (isTransientError(err)) throw err;
+      if (strict || isTransientError(err)) throw err;
       return;
     }
     if (replaced) throw notThePinned(ref, generation);
   }
+  /**
+   * 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.
+   */
+  async verifyHeld(ref, generation, held) {
+    validateUserRef(ref, "read", PORT_KEYS);
+    await this.throwIfReplaced(ref, generation, held.version, held.fingerprint, true);
+  }
   /** Chunk keys of a specific generation — the pinned shape read. `held` as for {@link getChunkAt}. */
   async listChunkKeysAt(ref, generation, held) {
     validateUserRef(ref, "read", PORT_KEYS);
@@ -5070,11 +5293,11 @@ var PinnedStorageChunkSource = class {
   constructor(inner, pins) {
     this.inner = inner;
     this.pins = pins;
-    for (const [key, pin] of pins) {
+    for (const [pinKey, pin] of pins) {
       const held = pin;
       if (held.generation !== null && (typeof held.version !== "string" || typeof held.fingerprint !== "string"))
         throw new ValidationError(
-          `pin for "${key}" names generation ${held.generation} without its version and object fingerprint`
+          `pin for "${pinKey}" names generation ${held.generation} without its version and object fingerprint`
         );
     }
   }
@@ -5174,6 +5397,14 @@ var PinnedStorageChunkSource = class {
   exists(ref) {
     return this.inner.exists(ref);
   }
+  /** Whether the object this segment's pin holds is still there: see {@link HeldObjectLookup.verifyPinned}. */
+  verifyPinned(ref) {
+    const pin = this.pinFor(ref);
+    const held = pin === void 0 ? void 0 : heldBy(pin);
+    if (pin === void 0 || held === void 0 || pin.generation === null)
+      return Promise.resolve();
+    return this.inner.verifyHeld(ref, pin.generation, held);
+  }
   invalidate(ref) {
     this.inner.invalidate(ref);
   }
@@ -5275,14 +5506,15 @@ function plainView(bytes, what) {
   }
   return length === 0 ? new Uint8Array(0) : new Uint8Array(buffer, offset, length);
 }
-var sharedByteLength = typeof SharedArrayBuffer === "function" ? Object.getOwnPropertyDescriptor(SharedArrayBuffer.prototype, "byteLength")?.get : void 0;
+var plainByteLength = Object.getOwnPropertyDescriptor(ArrayBuffer.prototype, "byteLength")?.get;
+var hasSharedMemory = typeof SharedArrayBuffer === "function";
 function isShared(buffer) {
-  if (sharedByteLength === void 0) return false;
+  if (!hasSharedMemory) return false;
   try {
-    sharedByteLength.call(buffer);
-    return true;
-  } catch {
+    plainByteLength.call(buffer);
     return false;
+  } catch {
+    return true;
   }
 }
 function overCap(what, length) {
@@ -5323,11 +5555,22 @@ function prepareLoadInput(input, codec) {
     `a load takes ids (an iterable of integers), { serialized } or { bitmap }, as the only key; got an object with keys [${keys.join(", ")}]. Load options go in the next argument.`
   );
 }
-function decodeSerialized(bytes, codec, what = "the buffer") {
+function decodeSerialized(bytes, codec, what = "the buffer", options = {}) {
   if (typeof bytes !== "object" || bytes === null || tagOf(bytes) !== "Uint8Array") {
     throw new ValidationError(`${what} must be a Uint8Array of portable Roaring bytes`);
   }
   const view = plainView(bytes, what);
+  if (view.byteLength === 0 && options.refuseEmpty === true) {
+    throw new ValidationError(
+      `${what} is empty or detached: an empty buffer is not a bitmap, and an empty bitmap is built without bytes`
+    );
+  }
+  const { maxBytes } = options;
+  if (maxBytes !== void 0 && maxBytes < MAX_SERIALIZED_LOAD_BYTES && view.byteLength > maxBytes) {
+    throw new ValidationError(
+      `${what} is ${view.byteLength} bytes, more than the ${maxBytes} this call allows (maxBytes)`
+    );
+  }
   if (view.byteLength > MAX_SERIALIZED_LOAD_BYTES) throw overCap(what, view.byteLength);
   const own = isShared(view.buffer) ? new Uint8Array(view) : view;
   try {
@@ -5465,12 +5708,10 @@ var CrbmWriter = class {
   async addChunk(chunkKey, payload, cardinality) {
     if (this.finished) throw new ValidationError("CrbmWriter already finished");
     if (!Number.isInteger(chunkKey) || chunkKey < 0 || chunkKey > 65535) {
-      throw new ValidationError(`chunkKey must be a u16; got ${chunkKey}`);
+      throw new ValidationError("chunkKey must be a u16");
     }
     if (chunkKey <= this.lastKey) {
-      throw new ValidationError(
-        `chunkKey ${chunkKey} not strictly ascending (last ${this.lastKey})`
-      );
+      throw new ValidationError("chunkKey is not strictly ascending");
     }
     if (!Number.isInteger(cardinality) || cardinality < 1 || cardinality > MAX_CHUNK_CARDINALITY) {
       throw new ValidationError(
@@ -6280,7 +6521,7 @@ async function collectChunks(input, codec, clock) {
       throw new ValidationError("a chunk's key must be an integer in [0, 65535]");
     }
     if (chunkKey <= last) {
-      throw new ValidationError(`chunk ${chunkKey} does not ascend: the last was ${last}`);
+      throw new ValidationError("a chunk's key does not ascend past the previous chunk's");
     }
     last = chunkKey;
     const max = bitmap.maximum?.();
@@ -8671,7 +8912,7 @@ var Run = class {
                 failOperand(
                   c,
                   new IntegrityError(
-                    `operand "${c.op.spec.name}" lists chunk ${key} but its generation holds no bytes for it`
+                    `operand "${c.op.spec.name}" lists a chunk its generation holds no bytes for`
                   ),
                   victims ?? wanting(c)
                 );
@@ -8680,13 +8921,10 @@ var Run = class {
               try {
                 const resident = residentBytes(bytes.length);
                 if (!this.ledger.reserve(resident, makeRoom)) {
-                  throw this.refuse(resident, `operand "${c.op.spec.name}" at chunk ${key}`);
+                  throw this.refuse(resident, `operand "${c.op.spec.name}" at one of its chunks`);
                 }
                 held += resident;
-                decoded.set(
-                  c.op.index,
-                  decodeChunkBytes(this.codec, bytes, key, this.maxBitmapBytes)
-                );
+                decoded.set(c.op.index, decodeChunkBytes(this.codec, bytes, this.maxBitmapBytes));
               } catch (error) {
                 failOperand(c, error, victims ?? wanting(c));
               }
@@ -9593,7 +9831,7 @@ async function holds(c, generation) {
       }
       throw err;
     }
-    return bytes !== null && codec.safeDeserialize(bytes, maxBytes).has(remainder);
+    return bytes !== null && decodeChunkBytes(codec, bytes, maxBytes).has(remainder);
   } catch (err) {
     if (isNotFoundError(err)) return null;
     throw err;
@@ -10004,8 +10242,7 @@ async function stage(c) {
     c.fromFingerprint = reader.fingerprint;
     const bytes = await read(() => reader.getChunk(chunkKey));
     if (bytes === null) return await notInCurrent(c);
-    const target = codec.safeDeserialize(bytes, maxBytes);
-    assertRemaindersInRange(target, chunkKey);
+    const target = decodeChunkBytes(codec, bytes, maxBytes);
     if (!target.has(remainder)) return await notInCurrent(c);
     target.remove(remainder);
     assertRegistryCanWrite(deps.registry, "eraseIdFromSegment");
@@ -10291,26 +10528,17 @@ async function* rewrite(reader, chunkKey, replacement, codec, maxBytes, read) {
       }
       const item = await stream.next();
       if (item.done === true || item.value.key !== k) {
-        throw new IntegrityError(`the chunk stream ended before chunk ${k}`);
+        throw new IntegrityError("the chunk stream ended before a chunk the rewrite needs");
       }
       const bytes = item.value.bytes;
       if (bytes === null) continue;
-      const bitmap = codec.safeDeserialize(bytes, maxBytes);
-      assertRemaindersInRange(bitmap, k);
+      const bitmap = decodeChunkBytes(codec, bytes, maxBytes);
       yield { chunkKey: k, bitmap };
     }
   } finally {
     await stream.return(void 0);
   }
 }
-function assertRemaindersInRange(bitmap, chunkKey) {
-  const max = bitmap.maximum?.();
-  if (max !== void 0 && max > MAX_REMAINDER) {
-    throw new IntegrityError(
-      `chunk ${chunkKey} payload holds value ${max}, outside the 16-bit remainder range [0, ${MAX_REMAINDER}] \u2014 the stored object is corrupt or was not written by this codec; refusing to carry it into a new generation`
-    );
-  }
-}
 
 // src/core/cas-retry.ts
 async function casRetry(deps, ref, plan, step) {
@@ -12029,6 +12257,7 @@ var RetryingStorageChunkSource = class {
   invalidate;
   exists;
   currentVersion;
+  verifyPinned;
   constructor(inner, opts) {
     this.inner = inner;
     const r = toRetry(opts);
@@ -12074,6 +12303,10 @@ var RetryingStorageChunkSource = class {
     if (innerExists) {
       this.exists = (ref) => withRetry(() => innerExists.call(inner, ref), this.policy, this.deps);
     }
+    const innerVerify = inner.verifyPinned;
+    if (innerVerify) {
+      this.verifyPinned = (ref) => withRetry(() => innerVerify.call(inner, ref), this.policy, this.deps);
+    }
     const innerCurrentVersion = inner.currentVersion;
     if (innerCurrentVersion) {
       this.currentVersion = (ref) => withRetry(() => innerCurrentVersion.call(inner, ref), this.policy, this.deps);
@@ -12104,6 +12337,7 @@ export {
   LeaseLimitError,
   MAX_LEASES_PER_SEGMENT,
   MAX_LEASE_MS,
+  MAX_SERIALIZED_LOAD_BYTES,
   MIN_EXPIRES_AT_MS,
   NOOP_METRICS,
   NotFoundError,
@@ -12139,6 +12373,7 @@ export {
   mapWithConcurrency,
   readRetentionPolicy,
   rebindCombineMany,
+  refusalOfId,
   refuseUnknownRefKeys,
   releaseLease,
   resolveBudget,