@cloudbitmaps/core 0.15.0 → 0.16.0

package/dist/index.js

@@ -52,7 +52,7 @@ import {
   validateUserNamespace,
   validateUserRef,
   webCryptoEntropy
-} from "./chunk-B7IGS3W6.js";
+} from "./chunk-LFUNPMXZ.js";
 
 // src/core/bit-route.ts
 var U32_MAX = 4294967295;
@@ -494,6 +494,8 @@ var SegmentEngine = class {
    * they deliver, as a read whose entry an invalidation dropped does not (streams hold no `openReads` entry).
    */
   openStreams = /* @__PURE__ */ new Set();
+  /** How many times {@link invalidate} has been called: a read compares it with the count it began under. */
+  invalidations = 0;
   constructor(deps) {
     this.storage = deps.storage;
     this.cache = deps.cache;
@@ -578,8 +580,15 @@ var SegmentEngine = class {
    * coalesced ranges when the source has `getChunks`, opening 1, 2, 4 … ranges wide up to {@link DEFAULT_INTERSECT_CONCURRENCY},
    * else the chunk-by-chunk window of that many reads. `close` stops what is left of it.
    */
-  chunkSequence(seg, chunkKeys, gen) {
-    const streamed = this.openStreamed(seg, chunkKeys, gen, DEFAULT_INTERSECT_CONCURRENCY, 1);
+  chunkSequence(seg, chunkKeys, gen, epoch) {
+    const streamed = this.openStreamed(
+      seg,
+      chunkKeys,
+      gen,
+      epoch,
+      DEFAULT_INTERSECT_CONCURRENCY,
+      1
+    );
     if (streamed !== void 0) {
       return {
         take: (chunkKey) => this.streamedChunk(streamed, chunkKey),
@@ -604,10 +613,11 @@ var SegmentEngine = class {
     return range === void 0 ? this.iterateAll(seg) : this.iterateRange(seg, range);
   }
   async *iterateAll(seg) {
+    const epoch = this.invalidations;
     const chunkKeys = await this.chunkKeys(seg);
     checkBudget(this.budget, chunkKeys.length, "iterate");
     const gen = await this.cacheVersion(seg);
-    const chunks = this.chunkSequence(seg, chunkKeys, gen);
+    const chunks = this.chunkSequence(seg, chunkKeys, gen, epoch);
     try {
       for (const chunkKey of chunkKeys) {
         const chunk = await chunks.take(chunkKey);
@@ -619,12 +629,13 @@ var SegmentEngine = class {
     }
   }
   async *iterateRange(seg, range) {
+    const epoch = this.invalidations;
     const w = windowOf(range) ?? WHOLE_ID_SPACE;
     if (w === "empty") return;
     const chunkKeys = keysWithin(await this.chunkKeys(seg), w);
     checkBudget(this.budget, chunkKeys.length, "iterate");
     const gen = await this.cacheVersion(seg);
-    const chunks = this.chunkSequence(seg, chunkKeys, gen);
+    const chunks = this.chunkSequence(seg, chunkKeys, gen, epoch);
     try {
       for (const chunkKey of chunkKeys) {
         const chunk = await chunks.take(chunkKey);
@@ -646,12 +657,13 @@ var SegmentEngine = class {
    * the caller's to keep.
    */
   async *iterateBatches(seg, range) {
+    const epoch = this.invalidations;
     const w = windowOf(range);
     if (w === "empty") return;
     const chunkKeys = w === null ? await this.chunkKeys(seg) : keysWithin(await this.chunkKeys(seg), w);
     checkBudget(this.budget, chunkKeys.length, "iterate");
     const gen = await this.cacheVersion(seg);
-    const chunks = this.chunkSequence(seg, chunkKeys, gen);
+    const chunks = this.chunkSequence(seg, chunkKeys, gen, epoch);
     try {
       for (const chunkKey of chunkKeys) {
         const chunk = await chunks.take(chunkKey);
@@ -731,6 +743,26 @@ var SegmentEngine = class {
   andNotBatches(seg, excludes, options) {
     return this.combineBatches([seg], excludes, "all", "andNot", options);
   }
+  /**
+   * {@link intersect}, as the chunks the result is made of: `{ chunkKey, bitmap }` in ascending key order, each a
+   * non-empty bitmap of the chunk's 16-bit remainders, cut to the read's range. What a materialisation writes
+   * straight into its new generation, with no id built on the way.
+   *
+   * **Each bitmap belongs to the caller, who may change it:** it is the combine's own accumulator or a bitmap built
+   * for the range's edge, never a chunk the cache holds or another operand's. The reads, the budget, the metric and the
+   * errors are the id reads' own.
+   */
+  intersectChunks(segs, options) {
+    return this.combineChunks(segs, options?.exclude ?? [], "all", "intersect", options);
+  }
+  /** {@link union}, as chunks: see {@link intersectChunks}. */
+  unionChunks(segs, options) {
+    return this.combineChunks(segs, options?.exclude ?? [], "any", "union", options);
+  }
+  /** {@link andNot}, as chunks: see {@link intersectChunks}. */
+  andNotChunks(seg, excludes, options) {
+    return this.combineChunks([seg], excludes, "all", "andNot", options);
+  }
   /**
    * Everything a combine decides before it reads a chunk: validation, each operand's keys and generation, the
    * absent-operand refusal, key alignment, the budget and the metric. `null` when the range is empty. The per-id
@@ -753,10 +785,11 @@ var SegmentEngine = class {
     const w = windowOf(options);
     if (w === "empty") return null;
     const extract = async (seg) => {
+      const epoch = this.invalidations;
       const all = await this.chunkKeys(seg);
       const gen = await this.cacheVersion(seg);
       const keys = w === null ? all : keysWithin(all, w);
-      return { seg, keys: new Set(keys), chunkless: all.length === 0, gen };
+      return { seg, keys: new Set(keys), chunkless: all.length === 0, gen, epoch };
     };
     const [operands, excludes] = await Promise.all([
       Promise.all(segs.map(extract)),
@@ -801,14 +834,15 @@ var SegmentEngine = class {
     const open4 = (o, wanted) => {
       o.streamed = this.openStreamed(
         o.seg,
-        common.filter(wanted),
+        wanted === void 0 ? common : common.filter(wanted),
         o.gen,
+        o.epoch,
         limit,
         COMBINE_RANGE_START
       );
-      if (o.streamed?.stream) streams.push(o.streamed);
+      if (o.streamed) streams.push(o.streamed);
     };
-    for (const o of operands) open4(o, mode === "all" ? () => true : (k) => o.keys.has(k));
+    for (const o of operands) open4(o, mode === "all" ? void 0 : (k) => o.keys.has(k));
     if (streamExcludes) for (const e of excludes) open4(e, (k) => e.keys.has(k));
     return {
       w,
@@ -853,6 +887,28 @@ var SegmentEngine = class {
       for (const stream of plan.streams) this.closeStreamed(stream);
     }
   }
+  /** The chunk read: the plan every combine shares, then each key's result, cut to the range at its edges. */
+  async *combineChunks(segs, excludeSegs, mode, op, options) {
+    const plan = await this.combinePlan(segs, excludeSegs, mode, op, options);
+    if (plan === null) return;
+    const { w, window } = plan;
+    try {
+      for (let slot = await window.next(); slot !== void 0; slot = await window.next()) {
+        if (!slot.result || slot.result.isEmpty) continue;
+        const bitmap = w !== null && isEdge(slot.key, w) ? this.cutToWindow(slot.result, slot.key, w) : slot.result;
+        if (!bitmap.isEmpty) yield { chunkKey: slot.key, bitmap };
+      }
+    } finally {
+      for (const stream of plan.streams) this.closeStreamed(stream);
+    }
+  }
+  /** An edge chunk's bitmap cut to the window, as a new bitmap: the remainders `edgeIds` would yield. */
+  cutToWindow(chunk, chunkKey, w) {
+    const from = chunkKey === w.loKey ? w.loRem : 0;
+    const to = chunkKey === w.hiKey ? w.hiRem : MAX_REMAINDER;
+    const rem = chunk.toUint32Array ? chunk.toUint32Array() : Uint32Array.from(chunk);
+    return this.codec.fromValues(rem.subarray(firstAbove(rem, from - 1), firstAbove(rem, to)));
+  }
   /**
    * 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).
@@ -902,25 +958,43 @@ var SegmentEngine = class {
     return op.streamed === void 0 ? this.storageChunk({ ...op.seg, chunkKey }, op.gen) : this.streamedChunk(op.streamed, chunkKey);
   }
   /**
-   * Open `keys` of `seg` as a stream of coalesced ranges, or `undefined` when the read is per key: a source with no
-   * `getChunks`, a segment with no generation, or nothing to read. The chunks already decoded in the cache are taken out
-   * of the key list first and served from there, so a repeat read asks the source for nothing it holds. Nothing is
-   * requested until the first chunk is asked for.
+   * `keys` of `seg` as a stream of coalesced ranges, or `undefined` when the read is per key: a source with no
+   * `getChunks`, a segment with no generation, or nothing to read. Nothing is requested, and no cache lookup made, until
+   * the first chunk is asked for (see {@link StreamedChunks}).
+   */
+  openStreamed(seg, keys, gen, epoch, concurrency, rampStart) {
+    if (this.storage.getChunks === void 0 || gen === null || keys.length === 0) return void 0;
+    return {
+      seg,
+      gen,
+      epoch,
+      keys,
+      concurrency,
+      rampStart,
+      opened: false,
+      inStream: void 0,
+      stream: void 0,
+      invalidated: false
+    };
+  }
+  /**
+   * Open the stream of `streamed`, at its first uncached chunk `from`: over that chunk and the later keys the cache does
+   * not hold. Each later key is counted as a cache hit or miss here, so a key is counted once whichever way it is served.
    */
-  openStreamed(seg, keys, gen, concurrency, rampStart) {
+  startStream(streamed, from) {
+    const { seg, gen } = streamed;
     const getChunks = this.storage.getChunks;
-    if (getChunks === void 0 || gen === null || keys.length === 0) return void 0;
-    let wanted = keys;
-    let inStream;
+    let wanted = streamed.keys.slice(streamed.keys.indexOf(from));
     if (this.cache) {
-      const misses = [];
-      for (const chunkKey of keys) {
+      const misses = [from];
+      for (let i = 1; i < wanted.length; i++) {
+        const chunkKey = wanted[i];
         const hit = this.cache.get(this.chunkCacheKey({ ...seg, chunkKey }, gen));
         if (!hit) misses.push(chunkKey);
         if (this.metricsOn) this.metrics.onEvent({ kind: "cache", hit: hit !== void 0 });
       }
+      if (misses.length < wanted.length) streamed.inStream = new Set(misses);
       wanted = misses;
-      if (misses.length < keys.length) inStream = new Set(misses);
     }
     const onRequest = this.metricsOn ? (request) => {
       this.metrics.onEvent({
@@ -931,27 +1005,36 @@ var SegmentEngine = class {
         ms: request.ms
       });
     } : void 0;
-    const stream = wanted.length === 0 ? void 0 : new ChunkStream(
+    streamed.stream = new ChunkStream(
       getChunks.call(this.storage, seg, wanted, {
-        concurrency,
-        ramp: rampStart,
+        concurrency: streamed.concurrency,
+        ramp: streamed.rampStart,
         ...onRequest === void 0 ? {} : { onRequest }
       })
     );
-    const streamed = { seg, gen, inStream, stream, invalidated: false };
-    if (stream) this.openStreams.add(streamed);
-    return streamed;
+    streamed.opened = true;
+    streamed.invalidated = this.storage.currentVersion === void 0 && this.invalidations !== streamed.epoch;
+    this.openStreams.add(streamed);
   }
   closeStreamed(streamed) {
     streamed.stream?.close();
     this.openStreams.delete(streamed);
   }
   /**
-   * The decoded chunk at `chunkKey` of a streamed read: the next chunk of its stream, or, for a chunk the cache held
-   * when the read opened, the cached instance while it is still there, and a read of that chunk alone once it is not.
+   * The decoded chunk at `chunkKey` of a streamed read: from the cache while the stream is unopened and the cache holds
+   * it; else the next chunk of its stream, or, for a chunk the cache held when the stream opened, the cached instance
+   * while it is still there, and a read of that chunk alone once it is not.
    */
   streamedChunk(streamed, chunkKey) {
-    if (streamed.inStream !== void 0 && !streamed.inStream.has(chunkKey)) {
+    if (!streamed.opened) {
+      const cache = this.cache;
+      if (cache) {
+        const hit = cache.get(this.chunkCacheKey({ ...streamed.seg, chunkKey }, streamed.gen));
+        if (this.metricsOn) this.metrics.onEvent({ kind: "cache", hit: hit !== void 0 });
+        if (hit) return Promise.resolve(hit);
+      }
+      this.startStream(streamed, chunkKey);
+    } else if (streamed.inStream !== void 0 && !streamed.inStream.has(chunkKey)) {
       const ref = { ...streamed.seg, chunkKey };
       const hit = this.cache?.get(this.chunkCacheKey(ref, streamed.gen));
       return hit ? Promise.resolve(hit) : this.storageChunk(ref, streamed.gen);
@@ -1074,6 +1157,7 @@ var SegmentEngine = class {
    */
   invalidate(ref) {
     const prefix = segmentPrefix(ref);
+    this.invalidations += 1;
     for (const streamed of this.openStreams) {
       if (segmentPrefix(streamed.seg) === prefix) streamed.invalidated = true;
     }
@@ -1491,7 +1575,7 @@ var HOURS_PER_MONTH = 730;
 var SECONDS_PER_MONTH = HOURS_PER_MONTH * 3600;
 var GIB = 1024 ** 3;
 var STORE_LOAD_PUT_CLASS = 1 + 1 / LIST_COLLECTION_CADENCE;
-var STORE_LOAD_POINTER_READS = 3 + 2 / LIST_COLLECTION_CADENCE;
+var STORE_LOAD_POINTER_READS = 2 + 2 / LIST_COLLECTION_CADENCE;
 var STORE_LOAD_EXISTENCE_CHECKS = 2 - 1 / LIST_COLLECTION_CADENCE;
 var RETENTION_SWEEP_REQUESTS = deepFreeze({
   conditionalDelete: {
@@ -2108,6 +2192,10 @@ var MemoryRegistryDriver = class {
     this.rows.set(key, structuredClone(recordFromNew(ref, checked, this.now(), token)));
     return { token };
   }
+  /**
+   * A caller's `held` row (see `RegistryWriteOptions`) has no read to spare here: the token is compared with the stored row in the same step
+   * as the write, in memory, so a stale one fails exactly as a lost race does.
+   */
   async compareAndSwap(ref, expected, patch) {
     validateSegmentRef(ref);
     const checked = validateRegistryPatch(patch);
@@ -2463,6 +2551,10 @@ var LocalFsRegistryDriver = class {
       return { token };
     });
   }
+  /**
+   * A caller's `held` row (see `RegistryWriteOptions`) has no read to spare here: the row's file is read under its lock and its token compared
+   * there, a local read and no request, so a stale one fails exactly as a lost race does.
+   */
   async compareAndSwap(ref, expected, patch) {
     const checked = validateRegistryPatch(patch);
     const path = registryRowPath(this.root, ref);
@@ -3717,6 +3809,12 @@ var DecodedLoadInput = class {
   }
   bitmap;
 };
+var ChunkLoadInput = class {
+  constructor(chunks) {
+    this.chunks = chunks;
+  }
+  chunks;
+};
 function tagOf(value) {
   return Object.prototype.toString.call(value).slice(8, -1);
 }
@@ -5057,7 +5155,9 @@ async function publishGeneration(registry, key, options = {}) {
   let lastRecord;
   for (let attempt = 0; attempt < 5; attempt++) {
     const reused = attempt === 0 && options.row !== void 0;
+    const holdsRow = fresh === void 0;
     const record = fresh !== void 0 ? fresh : reused ? options.row ?? null : await registry.get(key);
+    const write = holdsRow ? { held: record } : void 0;
     fresh = void 0;
     unanswered = void 0;
     lastRecord = record;
@@ -5089,22 +5189,31 @@ async function publishGeneration(registry, key, options = {}) {
         return false;
       }
       if (record === null) {
-        await registry.create(key, {
-          currentGen: key.generation,
-          wrappedDeks: options.wrappedDeks,
-          ...options.summary === void 0 ? {} : { summary: options.summary }
-        });
+        await registry.create(
+          key,
+          {
+            currentGen: key.generation,
+            wrappedDeks: options.wrappedDeks,
+            ...options.summary === void 0 ? {} : { summary: options.summary }
+          },
+          write
+        );
       } else if (record.status === "destroyed") {
         throw new ValidationError(
           `segment "${key.segment}" was destroyed (crypto-shredded) while generation ${key.generation} was being written \u2014 refusing to publish it; the written object is unreadable. Use a new segment.`
         );
       } else if (record.currentGen === null) {
         refuseCleartextOntoKey(key, record, options.cleartext);
-        await registry.compareAndSwap(key, record.token, {
-          currentGen: key.generation,
-          ...options.wrappedDeks === void 0 ? {} : { wrappedDeks: options.wrappedDeks },
-          ...options.summary === void 0 ? {} : { summary: options.summary }
-        });
+        await registry.compareAndSwap(
+          key,
+          record.token,
+          {
+            currentGen: key.generation,
+            ...options.wrappedDeks === void 0 ? {} : { wrappedDeks: options.wrappedDeks },
+            ...options.summary === void 0 ? {} : { summary: options.summary }
+          },
+          write
+        );
       } else if (record.currentGen > key.generation) {
         return false;
       } else if (record.currentGen === key.generation) {
@@ -5117,10 +5226,15 @@ async function publishGeneration(registry, key, options = {}) {
           );
         }
         refuseCleartextOntoKey(key, record, options.cleartext);
-        await registry.compareAndSwap(key, record.token, {
-          currentGen: key.generation,
-          ...options.summary === void 0 ? {} : { summary: options.summary }
-        });
+        await registry.compareAndSwap(
+          key,
+          record.token,
+          {
+            currentGen: key.generation,
+            ...options.summary === void 0 ? {} : { summary: options.summary }
+          },
+          write
+        );
       }
       return true;
     } catch (err) {
@@ -5206,6 +5320,8 @@ async function bulkLoadAhead(driver, ref, ahead, ids, options = {}) {
     await pause();
     chunks = ids.bitmap.encodeChunks();
     await pause();
+  } else if (ids instanceof ChunkLoadInput) {
+    chunks = encodeEach(rangeCheckedAtWrite(await collectChunks(ids, codec, options.clock)));
   } else {
     chunks = encodeEach(
       await bucketIds(ids instanceof DecodedLoadInput ? ids.bitmap : ids, codec, options.clock)
@@ -5298,6 +5414,52 @@ async function bulkLoadAhead(driver, ref, ahead, ids, options = {}) {
     fingerprint
   };
 }
+function* rangeCheckedAtWrite(chunks) {
+  for (const chunk of chunks) {
+    const max = chunk.bitmap.maximum?.();
+    if (max !== void 0 && max > MAX_REMAINDER) {
+      throw new ValidationError(
+        `chunk ${chunk.chunkKey} holds ${max}, outside the 16-bit range [0, ${MAX_REMAINDER}]`
+      );
+    }
+    yield chunk;
+  }
+}
+async function collectChunks(input, codec, clock) {
+  const chunks = [];
+  const tick = yieldEvery(clock);
+  let last = -1;
+  for await (const chunk of input.chunks) {
+    if (typeof chunk !== "object" || chunk === null) {
+      throw new ValidationError(
+        `a chunk must be an object with a chunkKey and a bitmap; got ${String(chunk)}`
+      );
+    }
+    const { chunkKey, bitmap } = chunk;
+    if (codec.owns?.(bitmap) !== true) {
+      throw new ValidationError(
+        `chunk ${String(chunkKey)}: its bitmap is not one this load's codec made`
+      );
+    }
+    if (!Number.isInteger(chunkKey) || chunkKey < 0 || chunkKey > MAX_REMAINDER) {
+      throw new ValidationError(`a chunk's key must be an integer in [0, 65535]; got ${chunkKey}`);
+    }
+    if (chunkKey <= last) {
+      throw new ValidationError(`chunk ${chunkKey} does not ascend: the last was ${last}`);
+    }
+    last = chunkKey;
+    const max = bitmap.maximum?.();
+    if (max !== void 0 && max > MAX_REMAINDER) {
+      throw new ValidationError(
+        `chunk ${chunkKey} holds ${max}, outside the 16-bit range [0, ${MAX_REMAINDER}]`
+      );
+    }
+    chunks.push({ chunkKey, bitmap });
+    const pause = tick();
+    if (pause !== null) await pause;
+  }
+  return chunks;
+}
 async function bucketIds(ids, codec, clock) {
   const byChunk = /* @__PURE__ */ new Map();
   const pendingByChunk = /* @__PURE__ */ new Map();
@@ -5575,7 +5737,25 @@ async function currentCardinality(ref, deps, record, unwrapped) {
   for (const n of reader.cardinalities().values()) total += n;
   return { cardinality: total, fromSummary: false };
 }
-async function loadSegment(ref, input, deps, options = {}) {
+function loadSegment(ref, input, deps, options = {}) {
+  return runLoad(ref, (codec) => prepareLoadInput(input, codec), deps, options);
+}
+function loadSegmentChunks(ref, chunks, deps, options = {}) {
+  return runLoad(
+    ref,
+    () => {
+      if (typeof chunks !== "object" || chunks === null || !(Symbol.asyncIterator in chunks)) {
+        throw new ValidationError(
+          "loadSegmentChunks takes an async iterable of { chunkKey, bitmap }"
+        );
+      }
+      return new ChunkLoadInput(chunks);
+    },
+    deps,
+    options
+  );
+}
+async function runLoad(ref, prepare, deps, options) {
   validateUserRef(ref);
   const codec = requireCodec(deps.codec, "loadSegment");
   const keep = options.keep ?? 1;
@@ -5601,7 +5781,7 @@ async function loadSegment(ref, input, deps, options = {}) {
     throw new ValidationError(message);
   });
   const audit = safeAudit(options.audit ?? NOOP_AUDIT);
-  const ids = prepareLoadInput(input, codec);
+  const ids = prepare(codec);
   assertRegistryCanWrite(deps.registry, "load");
   const row = await deps.registry.get(ref);
   const fromToken = row?.token;
@@ -7195,6 +7375,7 @@ export {
   listGenerations,
   listSegments,
   loadSegment,
+  loadSegmentChunks,
   mapWithConcurrency,
   readRetentionPolicy,
   resolveBudget,