@cloudbitmaps/core 0.1.0-rc.0

package/dist/index.cjs

@@ -0,0 +1,4031 @@
+'use strict';
+
+var crypto = require('crypto');
+var fs = require('fs');
+var promises = require('fs/promises');
+var path = require('path');
+
+// src/core/errors.ts
+var ERROR_BRAND = /* @__PURE__ */ Symbol.for("cloud-roaring.error");
+var TRANSIENT_BRAND = /* @__PURE__ */ Symbol.for("cloud-roaring.error.transient");
+var CloudRoaringError = class extends Error {
+  /** Cross-bundle brand — see the predicates ({@link isCloudRoaringError}, …). Non-enumerable-ish (symbol key ⇒ not in JSON). */
+  [ERROR_BRAND] = true;
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var ValidationError = class extends CloudRoaringError {
+};
+var WriteConflictError = class extends CloudRoaringError {
+};
+var IntegrityError = class extends CloudRoaringError {
+};
+var NotFoundError = class extends CloudRoaringError {
+};
+var UnsupportedError = class extends CloudRoaringError {
+};
+var CapabilityError = class extends CloudRoaringError {
+};
+var BudgetExceededError = class extends CloudRoaringError {
+};
+var KeyUnavailableError = class extends CloudRoaringError {
+};
+var TransientError = class extends CloudRoaringError {
+  /** A second brand so the whole transient subtree (incl. {@link TimeoutError}) is classifiable cross-bundle. */
+  [TRANSIENT_BRAND] = true;
+  constructor(message, options) {
+    super(message);
+    if (options && "cause" in options) this.cause = options.cause;
+  }
+};
+var TimeoutError = class extends TransientError {
+};
+function hasBrand(err, brand) {
+  return typeof err === "object" && err !== null && err[brand] === true;
+}
+function isCloudRoaringError(err) {
+  return hasBrand(err, ERROR_BRAND);
+}
+function isWriteConflictError(err) {
+  return isCloudRoaringError(err) && err.name === "WriteConflictError";
+}
+function isTransientError(err) {
+  return hasBrand(err, TRANSIENT_BRAND);
+}
+function isNotFoundError(err) {
+  return isCloudRoaringError(err) && err.name === "NotFoundError";
+}
+function isIntegrityError(err) {
+  return isCloudRoaringError(err) && err.name === "IntegrityError";
+}
+function isValidationError(err) {
+  return isCloudRoaringError(err) && err.name === "ValidationError";
+}
+
+// src/core/bit-route.ts
+var U32_MAX = 4294967295;
+var CHUNK_COUNT = 65536;
+var LOW_16 = 65535;
+function splitId(id) {
+  if (!Number.isInteger(id) || id < 0 || id > U32_MAX) {
+    throw new ValidationError(`id must be an integer in 0..${U32_MAX}; got ${id}`);
+  }
+  return { chunkKey: id >>> 16, remainder: id & LOW_16 };
+}
+function joinId(chunkKey, remainder) {
+  return ((chunkKey & LOW_16) << 16 >>> 0) + (remainder & LOW_16);
+}
+
+// src/core/chunk.ts
+function emptyDelta(codec) {
+  return { adds: codec.empty(), removes: codec.empty() };
+}
+function applyAdd(delta, remainder) {
+  delta.adds.add(remainder);
+  delta.removes.remove(remainder);
+}
+function applyRemove(delta, remainder) {
+  delta.removes.add(remainder);
+  delta.adds.remove(remainder);
+}
+function effective(cold, delta) {
+  const out = cold.clone();
+  out.orInPlace(delta.adds);
+  out.andNotInPlace(delta.removes);
+  return out;
+}
+var WARM_DELTA_VERSION = 1;
+var VERSION_BYTES = 1;
+var HEADER_BYTES = 4;
+function encodeDelta(delta) {
+  const adds = delta.adds.serialize();
+  const removes = delta.removes.serialize();
+  const out = new Uint8Array(VERSION_BYTES + HEADER_BYTES + adds.length + removes.length);
+  out[0] = WARM_DELTA_VERSION;
+  new DataView(out.buffer).setUint32(VERSION_BYTES, adds.length, true);
+  out.set(adds, VERSION_BYTES + HEADER_BYTES);
+  out.set(removes, VERSION_BYTES + HEADER_BYTES + adds.length);
+  return out;
+}
+function decodeDelta(bytes, maxBitmapBytes, codec) {
+  if (bytes.length < VERSION_BYTES + HEADER_BYTES) {
+    throw new IntegrityError(`delta too short: ${bytes.length}B`);
+  }
+  const version = bytes[0];
+  if (version !== WARM_DELTA_VERSION) {
+    throw new UnsupportedError(
+      `Warm delta schema version ${version} is unsupported (this build reads v${WARM_DELTA_VERSION})`
+    );
+  }
+  const totalCap = 2 * maxBitmapBytes + VERSION_BYTES + HEADER_BYTES;
+  if (bytes.length > totalCap) {
+    throw new IntegrityError(`delta is ${bytes.length}B, exceeds cap ${totalCap}B`);
+  }
+  const addsStart = VERSION_BYTES + HEADER_BYTES;
+  const addsLen = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(
+    VERSION_BYTES,
+    true
+  );
+  const addsEnd = addsStart + addsLen;
+  if (addsLen > bytes.length - addsStart) {
+    throw new IntegrityError(
+      `delta addsLen ${addsLen} exceeds payload ${bytes.length - addsStart}`
+    );
+  }
+  const adds = codec.safeDeserialize(bytes.subarray(addsStart, addsEnd), maxBitmapBytes);
+  const removes = codec.safeDeserialize(bytes.subarray(addsEnd), maxBitmapBytes);
+  return { adds, removes };
+}
+
+// src/core/budget.ts
+var DEFAULT_BUDGET = { maxRequests: 1e6 };
+function resolveBudget(opt, fallback) {
+  if (opt === false) return null;
+  const maxRequests = opt?.maxRequests ?? fallback.maxRequests;
+  if (!Number.isInteger(maxRequests) || maxRequests < 1) {
+    throw new ValidationError(`budget.maxRequests must be a positive integer; got ${maxRequests}`);
+  }
+  return { maxRequests };
+}
+function resolvePerOpBudget(opt, storeBudget) {
+  if (opt === void 0) return storeBudget;
+  return resolveBudget(opt, storeBudget ?? DEFAULT_BUDGET);
+}
+function checkBudget(budget, projectedRequests, op) {
+  if (budget !== null && projectedRequests > budget.maxRequests) {
+    throw new BudgetExceededError(
+      `${op} would fan out to ${projectedRequests} units, over the per-op budget of ${budget.maxRequests} \u2014 raise \`budget.maxRequests\`, override it per-op, or set \`budget: false\``
+    );
+  }
+}
+
+// src/core/concurrency.ts
+async function mapWithConcurrency(items, limit, fn) {
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new ValidationError(`concurrency limit must be a positive integer; got ${limit}`);
+  }
+  const results = new Array(items.length);
+  let next = 0;
+  let failed = false;
+  let firstError;
+  const worker = async () => {
+    while (!failed) {
+      const i = next++;
+      if (i >= items.length) return;
+      try {
+        results[i] = await fn(items[i], i);
+      } catch (err) {
+        if (!failed) {
+          failed = true;
+          firstError = err;
+        }
+        return;
+      }
+    }
+  };
+  const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+  await Promise.all(workers);
+  if (failed) throw firstError;
+  return results;
+}
+
+// src/core/keys.ts
+var FIELD = " ";
+var NO_NAMESPACE = "/";
+function segmentKey(ref) {
+  return `${ref.namespace ?? NO_NAMESPACE}${FIELD}${ref.segment}`;
+}
+function segmentPrefix(ref) {
+  return `${segmentKey(ref)}${FIELD}`;
+}
+function chunkRefKey(ref) {
+  return `${segmentPrefix(ref)}${ref.chunkKey}`;
+}
+function chunkGenKey(ref, generation) {
+  return `${chunkRefKey(ref)}${FIELD}${generation}`;
+}
+
+// src/core/metrics.ts
+var NOOP_METRICS = {
+  onEvent() {
+  }
+};
+function safeMetrics(sink) {
+  if (sink === NOOP_METRICS) return sink;
+  return {
+    onEvent(event) {
+      try {
+        sink.onEvent(event);
+      } catch {
+      }
+    }
+  };
+}
+var OP_NAMES = [
+  "add",
+  "remove",
+  "addMany",
+  "removeMany",
+  "has",
+  "count",
+  "intersectInto"
+];
+var CountingMetricsSink = class _CountingMetricsSink {
+  cold = { gets: 0, bytes: 0, totalMs: 0 };
+  warm = { reads: 0, readBytes: 0, writes: 0, writeBytes: 0 };
+  cache = { hits: 0, misses: 0 };
+  retries = { occ: 0, transient: 0 };
+  intersect = { calls: 0, fetchedChunks: 0, skippedChunks: 0 };
+  compaction = { attempts: 0, committed: 0, dirtyChunks: 0, purged: 0, totalMs: 0 };
+  ops = _CountingMetricsSink.zeroOps();
+  static zeroOps() {
+    const ops = /* @__PURE__ */ Object.create(null);
+    for (const name of OP_NAMES) ops[name] = { count: 0, totalMs: 0 };
+    return ops;
+  }
+  onEvent(event) {
+    switch (event.kind) {
+      case "cold.get":
+        this.cold.gets += 1;
+        this.cold.bytes += event.bytes;
+        this.cold.totalMs += event.ms;
+        break;
+      case "cache":
+        if (event.hit) this.cache.hits += 1;
+        else this.cache.misses += 1;
+        break;
+      case "warm.read":
+        this.warm.reads += 1;
+        this.warm.readBytes += event.bytes;
+        break;
+      case "warm.write":
+        this.warm.writes += 1;
+        this.warm.writeBytes += event.bytes;
+        break;
+      case "retry":
+        if (event.reason === "occ") this.retries.occ += 1;
+        else this.retries.transient += 1;
+        break;
+      case "intersect":
+        this.intersect.calls += 1;
+        this.intersect.fetchedChunks += event.fetchedChunks;
+        this.intersect.skippedChunks += event.skippedChunks;
+        break;
+      case "compaction":
+        this.compaction.attempts += 1;
+        if (event.compacted) this.compaction.committed += 1;
+        this.compaction.dirtyChunks += event.dirtyChunks;
+        this.compaction.purged += event.purged;
+        this.compaction.totalMs += event.ms;
+        break;
+      case "op": {
+        const op = this.ops[event.name];
+        op.count += 1;
+        op.totalMs += event.ms;
+        break;
+      }
+      default: {
+        const exhaustive = event;
+        return exhaustive;
+      }
+    }
+  }
+  snapshot() {
+    const ops = /* @__PURE__ */ Object.create(null);
+    for (const name of OP_NAMES) ops[name] = { ...this.ops[name] };
+    return {
+      cold: { ...this.cold },
+      warm: { ...this.warm },
+      cache: { ...this.cache },
+      retries: { ...this.retries },
+      intersect: { ...this.intersect },
+      compaction: { ...this.compaction },
+      ops
+    };
+  }
+  reset() {
+    this.cold = { gets: 0, bytes: 0, totalMs: 0 };
+    this.warm = { reads: 0, readBytes: 0, writes: 0, writeBytes: 0 };
+    this.cache = { hits: 0, misses: 0 };
+    this.retries = { occ: 0, transient: 0 };
+    this.intersect = { calls: 0, fetchedChunks: 0, skippedChunks: 0 };
+    this.compaction = { attempts: 0, committed: 0, dirtyChunks: 0, purged: 0, totalMs: 0 };
+    this.ops = _CountingMetricsSink.zeroOps();
+  }
+};
+
+// src/core/ports.ts
+var NO_ROW = /* @__PURE__ */ Symbol.for("cloud-roaring.no-row");
+
+// src/core/retry.ts
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 4,
+  baseDelayMs: 50,
+  maxDelayMs: 2e3,
+  backoffFactor: 2,
+  jitter: "full"
+};
+var DEFAULT_OCC_BACKOFF = {
+  maxAttempts: 1,
+  // attempts are owned by the engine's loop; this policy only supplies the delay schedule
+  baseDelayMs: 5,
+  maxDelayMs: 200,
+  backoffFactor: 2,
+  jitter: "full"
+};
+function isTransient(err) {
+  return isTransientError(err);
+}
+function backoffDelayMs(policy, attempt) {
+  const raw = policy.baseDelayMs * policy.backoffFactor ** (attempt - 1);
+  return Math.min(policy.maxDelayMs, raw);
+}
+function applyJitter(policy, delayMs, rng) {
+  if (policy.jitter === "none") return delayMs;
+  return rng.next() * delayMs;
+}
+async function withRetry(op, policy, deps) {
+  const retryable = deps.isRetryable ?? isTransient;
+  const attempts = Math.max(1, policy.maxAttempts);
+  let lastErr;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      return await op();
+    } catch (err) {
+      lastErr = err;
+      if (attempt >= attempts || !retryable(err)) throw err;
+      const delayMs = applyJitter(policy, backoffDelayMs(policy, attempt), deps.rng);
+      deps.onRetry?.({ attempt, delayMs, err });
+      await deps.clock.sleep(delayMs);
+    }
+  }
+  throw lastErr;
+}
+
+// src/core/engine.ts
+var DEFAULT_MAX_BITMAP_BYTES = 1 << 20;
+var DEFAULT_MAX_RETRIES = 16;
+var DEFAULT_INTERSECT_CONCURRENCY = 8;
+var InstantClock = class {
+  now() {
+    return 0;
+  }
+  sleep() {
+    return Promise.resolve();
+  }
+};
+var ZeroRng = class {
+  next() {
+    return 0;
+  }
+};
+var SegmentEngine = class {
+  warm;
+  cold;
+  cache;
+  codec;
+  maxBitmapBytes;
+  maxRetries;
+  clock;
+  rng;
+  occBackoff;
+  metrics;
+  metricsOn;
+  /** Consistency for READ-path Warm fetches (precomputed; OCC RMW passes strong explicitly, see `warmGet`). */
+  readOpts;
+  writeConcurrency;
+  /** Resolved per-op budget (null = disabled); undefined deps ⇒ the generous default. See {@link checkBudget}. */
+  budget;
+  constructor(deps) {
+    this.warm = deps.warm;
+    this.cold = deps.cold;
+    this.cache = deps.cache;
+    this.codec = deps.codec;
+    this.maxBitmapBytes = deps.maxBitmapBytes ?? DEFAULT_MAX_BITMAP_BYTES;
+    this.maxRetries = deps.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.clock = deps.clock ?? new InstantClock();
+    this.rng = deps.rng ?? new ZeroRng();
+    this.occBackoff = deps.occBackoff ?? DEFAULT_OCC_BACKOFF;
+    this.readOpts = { consistent: (deps.warmReadConsistency ?? "strong") !== "eventual" };
+    this.writeConcurrency = deps.writeConcurrency ?? 1;
+    this.budget = deps.budget === void 0 ? DEFAULT_BUDGET : deps.budget;
+    this.metrics = safeMetrics(deps.metrics ?? NOOP_METRICS);
+    this.metricsOn = this.metrics !== NOOP_METRICS;
+  }
+  add(seg, id) {
+    const { chunkKey, remainder } = splitId(id);
+    return this.readModifyWrite(seg, chunkKey, (d) => applyAdd(d, remainder));
+  }
+  remove(seg, id) {
+    const { chunkKey, remainder } = splitId(id);
+    return this.readModifyWrite(seg, chunkKey, (d) => applyRemove(d, remainder));
+  }
+  addMany(seg, ids) {
+    return this.mutateMany(seg, ids, applyAdd);
+  }
+  removeMany(seg, ids) {
+    return this.mutateMany(seg, ids, applyRemove);
+  }
+  async has(seg, id, opts) {
+    const { chunkKey, remainder } = splitId(id);
+    const ref = { ...seg, chunkKey };
+    const row = await this.warmGet(ref, opts ?? this.readOpts);
+    if (row) {
+      const delta = decodeDelta(row.bytes, this.maxBitmapBytes, this.codec);
+      if (delta.removes.has(remainder)) return false;
+      if (delta.adds.has(remainder)) return true;
+    }
+    const cold = await this.coldChunk(ref, await this.currentGen(seg));
+    return cold ? cold.has(remainder) : false;
+  }
+  async count(seg) {
+    const warmRows = await this.collectWarm(seg);
+    const cardinalities = this.cold.cardinalities ? await this.cold.cardinalities(seg) : null;
+    if (!cardinalities) {
+      const chunkKeys = await this.chunkKeys(seg, warmRows);
+      checkBudget(this.budget, chunkKeys.length, "count");
+      const gen2 = await this.currentGen(seg);
+      let total2 = 0;
+      for (const chunkKey of chunkKeys) {
+        total2 += (await this.effectiveChunk(seg, chunkKey, warmRows, gen2)).size;
+      }
+      return total2;
+    }
+    checkBudget(this.budget, warmRows.size, "count");
+    const gen = await this.currentGen(seg);
+    const keys = new Set(warmRows.keys());
+    for (const k of cardinalities.keys()) keys.add(k);
+    let total = 0;
+    for (const k of keys) {
+      this.assertChunkKeyInRange(k);
+      total += warmRows.has(k) ? (await this.effectiveChunk(seg, k, warmRows, gen)).size : cardinalities.get(k) ?? 0;
+    }
+    return total;
+  }
+  /** Whether the Cold source can measure segment size (for grounded cost); false ⇒ storage isn't grounded. */
+  get supportsColdSize() {
+    return typeof this.cold.sizeOf === "function";
+  }
+  /** Grounded Cold size of a segment's current generation (cost reporting), or null if it has no generation. */
+  segmentSize(seg) {
+    return this.cold.sizeOf ? this.cold.sizeOf(seg) : Promise.resolve(null);
+  }
+  async *iterate(seg) {
+    const warmRows = await this.collectWarm(seg);
+    const chunkKeys = await this.chunkKeys(seg, warmRows);
+    checkBudget(this.budget, chunkKeys.length, "iterate");
+    const gen = await this.currentGen(seg);
+    for (const chunkKey of chunkKeys) {
+      const eff = await this.effectiveChunk(seg, chunkKey, warmRows, gen);
+      for (const remainder of eff) yield joinId(chunkKey, remainder);
+    }
+  }
+  /**
+   * Chunk-skipping intersection. Computes
+   * `seg[0] ∩ seg[1] ∩ …` and streams the result ids ascending. It aligns each segment's *effective*
+   * chunk-key set (Warm ∪ Cold), keeps only keys present in **all** operands (a key missing from any
+   * operand can't contribute → its **Cold chunks are never fetched** — the core saving), then for each
+   * surviving key merges tiers per operand (operand fetches run in parallel) and hands the buffers to the
+   * roaring engine for the AND, streaming results through a bounded in-flight window.
+   *
+   * **Memory:** the Cold payload footprint is bounded by the window (`concurrency × operands × chunk`), not
+   * by segment size — that's the Lambda-friendly property. The **Warm** side, however, is snapshotted up
+   * front (`collectWarm` per operand), so total memory also carries each operand's Warm size. Under
+   * Topology-A (read-mostly; compaction keeps Warm small) that's negligible; a streaming Warm/Cold
+   * merge-join for large Warm is Phase 4.
+   *
+   * Generation-consistent within the call (normal case): each operand's current generation is resolved **once**
+   * up front (before the fan-out) and threaded into every chunk read, so a concurrent compaction can't corrupt
+   * or tear the result — every chunk read is a whole, checksum-verified, immutable generation (finding C10).
+   * The edge a *long* call can hit: if it straddles a mid-call `coldGenTtlMs` boundary and a compaction has
+   * committed, an operand's not-yet-read chunks may re-resolve forward to the newer generation (a generation
+   * hop within one long call) — the call never crashes or returns a torn object, but may mix generations. That
+   * window is a single TTL (default 2 s), not the multi-cycle GC-sweep window it took pre-Phase-B. A shorter call
+   * is unaffected **unless the reader cache evicts an operand mid-call** (`maxOpenSegments`, gap #1): the re-read
+   * re-resolves fresh (bypassing the TTL), which can hop generations even sub-TTL — still whole/immutable per
+   * read, never torn. Full intra-op snapshot isolation is deferred (gap #4).
+   */
+  async *intersect(segs, options) {
+    if (segs.length === 0) {
+      throw new ValidationError("intersect requires at least one segment");
+    }
+    const limit = options?.concurrency ?? DEFAULT_INTERSECT_CONCURRENCY;
+    if (!Number.isInteger(limit) || limit < 1) {
+      throw new ValidationError(
+        `concurrency must be a positive integer; got ${options?.concurrency}`
+      );
+    }
+    const budget = resolvePerOpBudget(options?.budget, this.budget);
+    const operands = await Promise.all(
+      segs.map(async (seg) => {
+        const warmRows = await this.collectWarm(seg);
+        const keys = await this.chunkKeys(seg, warmRows);
+        const gen = await this.currentGen(seg);
+        return { seg, warmRows, keys: new Set(keys), gen };
+      })
+    );
+    const pivot = operands.reduce((a, b) => a.keys.size <= b.keys.size ? a : b);
+    const common = [];
+    for (const k of pivot.keys) {
+      if (operands.every((op) => op.keys.has(k))) common.push(k);
+    }
+    common.sort((a, b) => a - b);
+    checkBudget(budget, common.length * operands.length, "intersect");
+    if (this.metricsOn) {
+      const distinctKeys = /* @__PURE__ */ new Set();
+      for (const op of operands) {
+        for (const k of op.keys) distinctKeys.add(k);
+      }
+      this.metrics.onEvent({
+        kind: "intersect",
+        operands: segs.length,
+        fetchedChunks: common.length,
+        skippedChunks: distinctKeys.size - common.length
+      });
+    }
+    const startAt = (key) => this.intersectChunk(operands, key).then(
+      (result) => ({ key, result }),
+      (error) => ({ key, result: null, error })
+    );
+    const inFlight = [];
+    let next = 0;
+    while (next < common.length && inFlight.length < limit) inFlight.push(startAt(common[next++]));
+    while (inFlight.length > 0) {
+      const slot = await inFlight.shift();
+      if (next < common.length) inFlight.push(startAt(common[next++]));
+      if (slot.error !== void 0) throw slot.error;
+      if (slot.result && !slot.result.isEmpty) {
+        for (const remainder of slot.result) yield joinId(slot.key, remainder);
+      }
+    }
+  }
+  /**
+   * The AND of one chunk key across all operands (tier-merged per operand), or `null` if empty. Operand
+   * chunks are fetched **in parallel** (the spec's parallel byte-range reads). `acc` takes ownership of the
+   * first operand's effective chunk and mutates it in place — safe because `effectiveChunk` always returns
+   * a FRESH bitmap (never a cached/shared Cold instance), so this can't poison the HOT cache.
+   */
+  async intersectChunk(operands, chunkKey) {
+    const chunks = await Promise.all(
+      operands.map((op) => this.effectiveChunk(op.seg, chunkKey, op.warmRows, op.gen))
+    );
+    const acc = chunks[0];
+    for (let i = 1; i < chunks.length; i++) {
+      acc.andInPlace(chunks[i]);
+      if (acc.isEmpty) return null;
+    }
+    return acc.isEmpty ? null : acc;
+  }
+  /**
+   * Materialize `seg[0] ∩ seg[1] ∩ …` into `dest` via batched `addMany` (streaming, bounded memory).
+   * **Not atomic** — like `addMany`, ids land chunk-by-chunk; a failure mid-stream leaves a partial result.
+   * `dest` is added to, not replaced.
+   */
+  async intersectInto(dest, segs, options) {
+    const batchSize = Math.max(1, options?.batchSize ?? 4096);
+    let batch = [];
+    for await (const id of this.intersect(segs, options)) {
+      batch.push(id);
+      if (batch.length >= batchSize) {
+        await this.addMany(dest, batch);
+        batch = [];
+      }
+    }
+    if (batch.length > 0) await this.addMany(dest, batch);
+  }
+  async mutateMany(seg, ids, apply) {
+    const byChunk = /* @__PURE__ */ new Map();
+    for (const id of ids) {
+      const { chunkKey, remainder } = splitId(id);
+      const rems = byChunk.get(chunkKey) ?? [];
+      rems.push(remainder);
+      byChunk.set(chunkKey, rems);
+    }
+    await mapWithConcurrency(
+      [...byChunk],
+      this.writeConcurrency,
+      ([chunkKey, rems]) => this.readModifyWrite(seg, chunkKey, (d) => {
+        for (const r of rems) apply(d, r);
+      })
+    );
+  }
+  /** OCC read-modify-write on a chunk's Warm delta, retrying on conflict (bounded). */
+  async readModifyWrite(seg, chunkKey, mutate) {
+    const ref = { ...seg, chunkKey };
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const row = await this.warmGet(ref);
+      const delta = row ? decodeDelta(row.bytes, this.maxBitmapBytes, this.codec) : emptyDelta(this.codec);
+      mutate(delta);
+      const encoded = encodeDelta(delta);
+      try {
+        await this.warm.putConditional(ref, encoded, row ? row.token : NO_ROW);
+        if (this.metricsOn) {
+          this.metrics.onEvent({
+            kind: "warm.write",
+            namespace: ref.namespace,
+            segment: ref.segment,
+            bytes: encoded.length
+          });
+        }
+        return;
+      } catch (err) {
+        if (isWriteConflictError(err) && attempt < this.maxRetries) {
+          const delayMs = applyJitter(
+            this.occBackoff,
+            backoffDelayMs(this.occBackoff, attempt + 1),
+            this.rng
+          );
+          if (this.metricsOn) {
+            this.metrics.onEvent({ kind: "retry", reason: "occ", attempt: attempt + 1, delayMs });
+          }
+          await this.clock.sleep(delayMs);
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw new WriteConflictError(`OCC retries exhausted for chunk ${chunkKey}`);
+  }
+  /** `warm.get` + a `warm.read` metric (read bytes = the row size, 0 if absent). */
+  async warmGet(ref, opts) {
+    const row = await this.warm.get(ref, opts);
+    if (this.metricsOn) {
+      this.metrics.onEvent({
+        kind: "warm.read",
+        namespace: ref.namespace,
+        segment: ref.segment,
+        bytes: row ? row.bytes.length : 0
+      });
+    }
+    return row;
+  }
+  async collectWarm(seg) {
+    const rows = /* @__PURE__ */ new Map();
+    let bytes = 0;
+    for await (const row of this.warm.listChunks(seg, this.readOpts)) {
+      rows.set(row.chunkKey, row.bytes);
+      bytes += row.bytes.length;
+    }
+    if (this.metricsOn) {
+      this.metrics.onEvent({
+        kind: "warm.read",
+        namespace: seg.namespace,
+        segment: seg.segment,
+        bytes
+      });
+    }
+    return rows;
+  }
+  async chunkKeys(seg, warmRows) {
+    const keys = new Set(warmRows.keys());
+    for (const k of await this.cold.listChunkKeys(seg)) keys.add(k);
+    for (const k of keys) this.assertChunkKeyInRange(k);
+    return [...keys].sort((a, b) => a - b);
+  }
+  /**
+   * Tier-derived keys are untrusted (invariant 5) — fail fast on a corrupt/out-of-range key rather than
+   * letting it flow into `joinId` and produce a bogus id.
+   */
+  assertChunkKeyInRange(k) {
+    if (!Number.isInteger(k) || k < 0 || k >= CHUNK_COUNT) {
+      throw new IntegrityError(`chunk key from a tier is out of range: ${k}`);
+    }
+  }
+  async effectiveChunk(seg, chunkKey, warmRows, gen) {
+    const warmBytes = warmRows.get(chunkKey);
+    const delta = warmBytes ? decodeDelta(warmBytes, this.maxBitmapBytes, this.codec) : emptyDelta(this.codec);
+    const cold = await this.coldChunk({ ...seg, chunkKey }, gen) ?? this.codec.empty();
+    return effective(cold, delta);
+  }
+  /** The segment's current generation, resolved once per op (`undefined` ⇒ source can't report it). */
+  currentGen(seg) {
+    return this.cold.currentGeneration ? this.cold.currentGeneration(seg) : Promise.resolve(void 0);
+  }
+  /**
+   * Decode a Cold chunk. `gen` is the segment's current generation, resolved **once per op** by the caller (not
+   * per chunk — that would put a registry re-resolve on every chunk of a count/intersect). The HOT cache is
+   * keyed by it (gap #4), so a compaction that advances the generation misses the cache and re-reads the new
+   * bytes instead of serving a stale decoded chunk (an erased id can't resurrect from a cached pre-compaction
+   * chunk). `gen === null` ⇒ the source reports no current generation ⇒ no cold bytes for any chunk, so skip the
+   * fetch entirely (also avoids a redundant re-resolve on the warm-only path). `gen === undefined` ⇒ the source
+   * can't report a generation (pins one for its lifetime) ⇒ the key stays generation-free (unchanged behaviour).
+   * Superseded-generation entries age out under the LRU ceiling — no active purge.
+   */
+  async coldChunk(ref, gen) {
+    if (gen === null) return null;
+    const cacheKey = gen === void 0 ? chunkRefKey(ref) : chunkGenKey(ref, gen);
+    if (this.cache) {
+      const cached = this.cache.get(cacheKey);
+      if (cached) {
+        if (this.metricsOn) this.metrics.onEvent({ kind: "cache", hit: true });
+        return cached;
+      }
+      if (this.metricsOn) this.metrics.onEvent({ kind: "cache", hit: false });
+    }
+    const startedAt = this.metricsOn ? this.clock.now() : 0;
+    const bytes = await this.cold.getChunk(ref);
+    if (this.metricsOn) {
+      this.metrics.onEvent({
+        kind: "cold.get",
+        namespace: ref.namespace,
+        segment: ref.segment,
+        bytes: bytes ? bytes.length : 0,
+        ms: Math.max(0, this.clock.now() - startedAt)
+      });
+    }
+    if (!bytes) return null;
+    const bitmap = this.codec.safeDeserialize(bytes, this.maxBitmapBytes);
+    this.cache?.set(cacheKey, bitmap);
+    return bitmap;
+  }
+};
+
+// src/core/lru.ts
+var BoundedLru = class {
+  map = /* @__PURE__ */ new Map();
+  maxEntries;
+  maxBytes;
+  ttlMs;
+  clock;
+  totalBytes = 0;
+  constructor(options) {
+    if (!Number.isInteger(options.maxEntries) || options.maxEntries < 1) {
+      throw new ValidationError(`maxEntries must be a positive integer; got ${options.maxEntries}`);
+    }
+    if (options.maxBytes !== void 0 && (!(options.maxBytes > 0) || !Number.isFinite(options.maxBytes))) {
+      throw new ValidationError(
+        `maxBytes must be a positive finite number; got ${options.maxBytes}`
+      );
+    }
+    if (options.ttlMs !== void 0 && (!(options.ttlMs > 0) || !Number.isFinite(options.ttlMs))) {
+      throw new ValidationError(`ttlMs must be a positive finite number; got ${options.ttlMs}`);
+    }
+    this.maxEntries = options.maxEntries;
+    this.maxBytes = options.maxBytes;
+    this.ttlMs = options.ttlMs;
+    this.clock = options.clock;
+  }
+  get(key) {
+    const entry = this.map.get(key);
+    if (entry === void 0) return void 0;
+    if (entry.expiresAt <= this.clock.now()) {
+      this.drop(key, entry);
+      return void 0;
+    }
+    this.map.delete(key);
+    this.map.set(key, entry);
+    return entry.value;
+  }
+  /** Read a value **without** counting as an access (recency unchanged, no purge on expiry). */
+  peek(key) {
+    return this.map.get(key)?.value;
+  }
+  set(key, value) {
+    const prev = this.map.get(key);
+    if (prev !== void 0) this.totalBytes -= prev.bytes;
+    this.map.delete(key);
+    const expiresAt = this.ttlMs === void 0 ? Infinity : this.clock.now() + this.ttlMs;
+    this.map.set(key, { value, expiresAt, bytes: 0 });
+    while (this.map.size > this.maxEntries) {
+      const oldest = this.map.keys().next();
+      if (oldest.done === true) break;
+      this.dropKey(oldest.value);
+    }
+    this.evictToBudget(key);
+  }
+  /**
+   * Report an entry's byte weight (typically once a cached promise resolves and its size is known). Updates
+   * the running total and evicts the least-recently-used entries if the aggregate now exceeds `maxBytes`.
+   * Recency is **not** changed. The `key` being weighted is protected from this eviction pass (we just
+   * populated it) — so a single entry larger than the whole budget is kept rather than immediately dropped.
+   */
+  setWeight(key, bytes) {
+    if (!(bytes >= 0) || !Number.isFinite(bytes)) {
+      throw new ValidationError(`weight must be a non-negative finite number; got ${bytes}`);
+    }
+    const entry = this.map.get(key);
+    if (entry === void 0) return;
+    this.totalBytes += bytes - entry.bytes;
+    entry.bytes = bytes;
+    this.evictToBudget(key);
+  }
+  evictToBudget(protectKey) {
+    if (this.maxBytes === void 0) return;
+    while (this.totalBytes > this.maxBytes && this.map.size > 1) {
+      const oldest = this.oldestExcept(protectKey);
+      if (oldest === void 0) break;
+      this.dropKey(oldest);
+    }
+  }
+  /** The least-recently-used key that is not `protectKey`, or undefined if none other exists. */
+  oldestExcept(protectKey) {
+    for (const key of this.map.keys()) {
+      if (key !== protectKey) return key;
+    }
+    return void 0;
+  }
+  dropKey(key) {
+    const entry = this.map.get(key);
+    if (entry !== void 0) this.drop(key, entry);
+  }
+  drop(key, entry) {
+    this.totalBytes -= entry.bytes;
+    this.map.delete(key);
+  }
+  /** Membership test that does NOT count as an access (recency is unchanged). Purges if expired. */
+  has(key) {
+    const entry = this.map.get(key);
+    if (entry === void 0) return false;
+    if (entry.expiresAt <= this.clock.now()) {
+      this.drop(key, entry);
+      return false;
+    }
+    return true;
+  }
+  delete(key) {
+    const entry = this.map.get(key);
+    if (entry === void 0) return false;
+    this.drop(key, entry);
+    return true;
+  }
+  clear() {
+    this.map.clear();
+    this.totalBytes = 0;
+  }
+  /** Current entry count (may include not-yet-evicted expired entries). */
+  get size() {
+    return this.map.size;
+  }
+  /** Current aggregate reported weight (bytes) across all entries. */
+  get weightBytes() {
+    return this.totalBytes;
+  }
+};
+
+// src/core/cost.ts
+var AWS_US_EAST_1_ONDEMAND = {
+  name: "aws-us-east-1-ondemand",
+  cold: { getPerMillion: 0.4, putPerMillion: 5, storagePerGiBMonth: 0.023 },
+  warm: {
+    rruPerMillion: 0.125,
+    wruPerMillion: 0.625,
+    readUnitKiB: 4,
+    writeUnitKiB: 1,
+    storagePerGiBMonth: 0.25,
+    stronglyConsistent: true
+  },
+  redis: { monthlyUSD: 346 }
+  // ElastiCache HA: 1 primary + 2 replicas (cache.m7g.large); ~$115 single-node
+};
+var DEFAULT_PRICING = AWS_US_EAST_1_ONDEMAND;
+var SECONDS_PER_MONTH = 730 * 3600;
+var GIB = 1024 ** 3;
+function requireFiniteNonNeg(n, field) {
+  if (!Number.isFinite(n) || n < 0) {
+    throw new ValidationError(`${field} must be a finite number >= 0; got ${n}`);
+  }
+  return n;
+}
+function requireFinitePos(n, field) {
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new ValidationError(`${field} must be a finite number > 0; got ${n}`);
+  }
+  return n;
+}
+function clamp01(n) {
+  return n < 0 ? 0 : n > 1 ? 1 : n;
+}
+function sizingBytes(spec) {
+  if (spec.sizeBytes !== void 0) return requireFiniteNonNeg(spec.sizeBytes, "segment.sizeBytes");
+  if (spec.cardinality !== void 0) {
+    return requireFiniteNonNeg(spec.cardinality, "segment.cardinality") * 2;
+  }
+  return 0;
+}
+var BATCHABLE_WRITE_RATIO = 8;
+var BATCHABLE_MIN_SAVINGS_USD = 1;
+function deriveAdvisories(input) {
+  const { writes, writesUSD, maxWarmRows, warmWriteUSD } = input;
+  const out = [];
+  if (writes > 0 && writesUSD > 0 && maxWarmRows > 0) {
+    const ratio = writes / maxWarmRows;
+    const batchedFloorUSD = maxWarmRows * warmWriteUSD;
+    const savings = writesUSD - batchedFloorUSD;
+    if (ratio >= BATCHABLE_WRITE_RATIO && savings >= BATCHABLE_MIN_SAVINGS_USD) {
+      out.push({
+        code: "batchable-writes",
+        message: `${Math.round(writes).toLocaleString("en-US")} writes/mo against data occupying at most ${maxWarmRows.toLocaleString("en-US")} Warm rows \u2014 each row rewritten ~${Math.round(ratio).toLocaleString("en-US")}\xD7 ($${writesUSD.toFixed(2)}/mo). IF these ids ever arrive together, addMany() collapses them to one write per chunk and bulkLoadCrbmGeneration writes Cold directly, taking the write term toward $${batchedFloorUSD.toFixed(2)}/mo. If they genuinely arrive one at a time (real-time qualification), add() is the correct path and this is simply what it costs.`,
+        currentUSD: writesUSD,
+        batchedFloorUSD
+      });
+    }
+  }
+  return out;
+}
+function buildReport(input) {
+  const { topology, pricing, grounded } = input;
+  const { cold, warm, redis } = pricing;
+  const S = SECONDS_PER_MONTH;
+  requireFiniteNonNeg(cold.getPerMillion, "pricing.cold.getPerMillion");
+  requireFiniteNonNeg(cold.putPerMillion, "pricing.cold.putPerMillion");
+  requireFiniteNonNeg(cold.storagePerGiBMonth, "pricing.cold.storagePerGiBMonth");
+  requireFiniteNonNeg(warm.rruPerMillion, "pricing.warm.rruPerMillion");
+  requireFiniteNonNeg(warm.wruPerMillion, "pricing.warm.wruPerMillion");
+  requireFinitePos(warm.readUnitKiB, "pricing.warm.readUnitKiB");
+  requireFinitePos(warm.writeUnitKiB, "pricing.warm.writeUnitKiB");
+  requireFiniteNonNeg(redis.monthlyUSD, "pricing.redis.monthlyUSD");
+  const coldBytes = requireFiniteNonNeg(input.coldBytes, "coldBytes");
+  const cacheHitRate = clamp01(
+    requireFiniteNonNeg(input.workload.cacheHitRate ?? 0, "cacheHitRate")
+  );
+  const readsPerSec = requireFiniteNonNeg(input.workload.readsPerSec ?? 0, "readsPerSec");
+  const writesPerSec = requireFiniteNonNeg(input.workload.writesPerSec ?? 0, "writesPerSec");
+  const intersectsPerSec = requireFiniteNonNeg(
+    input.workload.intersectsPerSec ?? 0,
+    "intersectsPerSec"
+  );
+  const avgItemKiB = requireFiniteNonNeg(input.workload.avgItemKiB ?? 8, "avgItemKiB");
+  const chunksPerIntersect = requireFiniteNonNeg(
+    input.workload.chunksPerIntersect ?? 1,
+    "chunksPerIntersect"
+  );
+  const compactionsPerMonth = requireFiniteNonNeg(
+    input.workload.compactionsPerMonth ?? 0,
+    "compactionsPerMonth"
+  );
+  const avgItemBytes = avgItemKiB * 1024;
+  const derivedChunks = avgItemBytes > 0 ? Math.ceil(coldBytes / avgItemBytes) : 0;
+  const chunksPerCompaction = requireFiniteNonNeg(
+    input.workload.chunksPerCompaction ?? derivedChunks,
+    "chunksPerCompaction"
+  );
+  const dirtyChunksPerCompaction = requireFiniteNonNeg(
+    input.workload.dirtyChunksPerCompaction ?? 0,
+    "dirtyChunksPerCompaction"
+  );
+  const rruMult = warm.stronglyConsistent ? 1 : 0.5;
+  const warmReadUSD = Math.max(1, Math.ceil(avgItemKiB / warm.readUnitKiB)) * rruMult * (warm.rruPerMillion / 1e6);
+  const warmWriteUSD = Math.max(1, Math.ceil(avgItemKiB / warm.writeUnitKiB)) * (warm.wruPerMillion / 1e6);
+  const coldGetUSD = cold.getPerMillion / 1e6;
+  const missFraction = 1 - cacheHitRate;
+  const readMisses = readsPerSec * S * missFraction;
+  const writes = writesPerSec * S;
+  const intersects = intersectsPerSec * S;
+  const storageUSD = coldBytes / GIB * cold.storagePerGiBMonth;
+  const readsUSD = topology === "A" ? readMisses * coldGetUSD : readMisses * warmReadUSD;
+  const writesUSD = topology === "B" ? writes * warmWriteUSD : 0;
+  const intersectsUSD = intersects * chunksPerIntersect * coldGetUSD;
+  const putUSD = cold.putPerMillion / 1e6;
+  const compactionColdUSD = compactionsPerMonth * (chunksPerCompaction * coldGetUSD + putUSD);
+  const compactionWarmUSD = compactionsPerMonth * dirtyChunksPerCompaction * (warmReadUSD + warmWriteUSD);
+  const compactionUSD = compactionColdUSD + compactionWarmUSD;
+  const total = readsUSD + writesUSD + intersectsUSD + storageUSD + compactionUSD;
+  const warmTierUSD = (topology === "B" ? readsUSD + writesUSD : 0) + compactionWarmUSD;
+  const coldTierUSD = storageUSD + (topology === "A" ? readsUSD : 0) + intersectsUSD + compactionColdUSD;
+  const headroom = Math.max(0, redis.monthlyUSD - storageUSD);
+  const perReadUSD = topology === "A" ? coldGetUSD : warmReadUSD;
+  const writesCross = topology === "B" && warmWriteUSD > 0 ? headroom / (S * warmWriteUSD) : Infinity;
+  const readsCross = perReadUSD > 0 && missFraction > 0 ? headroom / (S * perReadUSD * missFraction) : Infinity;
+  const verdict = total <= redis.monthlyUSD * 0.1 ? "win-big" : total < redis.monthlyUSD ? "win" : "lose-zone";
+  const dominant = Math.max(readsUSD, writesUSD, intersectsUSD, storageUSD, compactionUSD);
+  let driver = "storage";
+  if (dominant === writesUSD && writesUSD > 0)
+    driver = "warm writes (the per-1KiB WRU cost driver)";
+  else if (dominant === readsUSD && readsUSD > 0)
+    driver = topology === "A" ? "cold reads (S3 GETs)" : "warm reads";
+  else if (dominant === intersectsUSD && intersectsUSD > 0) driver = "intersection cold fetches";
+  else if (dominant === compactionUSD && compactionUSD > 0)
+    driver = "compaction (whole-generation re-read)";
+  const rationale = verdict === "lose-zone" ? `pay-per-use total $${total.toFixed(2)}/mo exceeds the $${redis.monthlyUSD}/mo flat baseline; dominated by ${driver}` : verdict === "win-big" ? `$${total.toFixed(2)}/mo \u2014 \u226410% of the $${redis.monthlyUSD}/mo baseline; dominated by ${driver}` : `$${total.toFixed(2)}/mo, under the $${redis.monthlyUSD}/mo baseline; dominated by ${driver}`;
+  const notes = [
+    "S3\u2192same-region egress treated as free; internet egress is not modeled.",
+    "Warm delta storage treated as negligible (only dirty chunks).",
+    "Request cost is from the supplied workload rates (live-metrics-derived request cost is a later phase).",
+    compactionsPerMonth > 0 ? `Compaction modeled: ${compactionsPerMonth}/mo \xD7 (${chunksPerCompaction} Cold GET + 1 PUT${dirtyChunksPerCompaction > 0 ? ` + ${dirtyChunksPerCompaction}-row Warm purge` : ""}); the whole-generation re-read dominates. GC delete of the superseded generation is free (not modeled).` : "Compaction is NOT modeled \u2014 set workload.compactionsPerMonth (+ chunksPerCompaction) to include the whole-generation re-read that dominates operational cost.",
+    ...input.extraNotes ?? []
+  ];
+  return {
+    monthlyUSD: {
+      byTier: { hot: 0, warm: warmTierUSD, cold: coldTierUSD },
+      byOp: {
+        reads: readsUSD,
+        writes: writesUSD,
+        intersects: intersectsUSD,
+        storage: storageUSD,
+        compaction: compactionUSD
+      },
+      total
+    },
+    redisCrossover: { writesPerSec: writesCross, readsPerSec: readsCross },
+    verdict,
+    rationale,
+    // Topology-A has no per-op writes (they arrive via bulk-load), so `writesUSD` is 0 there and the advisory
+    // cannot fire — correctly, since bulk-load is already the batched path.
+    advisories: deriveAdvisories({
+      writes,
+      writesUSD,
+      maxWarmRows: requireFiniteNonNeg(input.maxWarmRows, "maxWarmRows"),
+      warmWriteUSD
+    }),
+    assumptions: { cacheHitRate, pricingName: pricing.name, grounded, topology, notes }
+  };
+}
+function estimateCost(input) {
+  const topology = input.topology ?? "A";
+  const pricing = input.pricing ?? DEFAULT_PRICING;
+  const workload = input.workload ?? {};
+  let coldBytes = 0;
+  let maxWarmRows = 0;
+  for (const spec of input.segments) {
+    const count = Math.floor(requireFiniteNonNeg(spec.count ?? 1, "segment.count"));
+    coldBytes += sizingBytes(spec) * count;
+    const perSegment = spec.cardinality !== void 0 ? Math.min(
+      Math.floor(requireFiniteNonNeg(spec.cardinality, "segment.cardinality")),
+      CHUNK_COUNT
+    ) : CHUNK_COUNT;
+    maxWarmRows += perSegment * count;
+  }
+  return buildReport({ coldBytes, workload, topology, pricing, grounded: false, maxWarmRows });
+}
+function groundedReport(input) {
+  return buildReport({
+    coldBytes: input.coldBytes,
+    workload: input.workload ?? {},
+    topology: input.topology ?? "A",
+    pricing: input.pricing ?? DEFAULT_PRICING,
+    grounded: input.grounded ?? true,
+    extraNotes: input.extraNotes,
+    maxWarmRows: input.maxWarmRows ?? CHUNK_COUNT
+  });
+}
+
+// src/core/audit.ts
+var NOOP_AUDIT = {
+  onEvent() {
+  }
+};
+function safeAudit(sink) {
+  if (sink === NOOP_AUDIT) return sink;
+  return {
+    onEvent(event) {
+      try {
+        sink.onEvent(event);
+      } catch {
+      }
+    }
+  };
+}
+var RecordingAuditSink = class {
+  recorded = [];
+  onEvent(event) {
+    this.recorded.push(event);
+  }
+  /** An independent copy of the recorded events, in emission order. */
+  snapshot() {
+    return this.recorded.map((e) => ({ ...e }));
+  }
+  reset() {
+    this.recorded.length = 0;
+  }
+};
+
+// src/core/codec.ts
+function requireCodec(codec, api) {
+  if (codec === void 0) {
+    throw new ValidationError(
+      `${api} needs a bitmap codec: pass \`codec\` (e.g. \`roaringCodec\` from @cloudbitmaps/roaring). @cloudbitmaps/core is codec-agnostic and has no default \u2014 install a flavor package, whose equivalents bind the codec for you.`
+    );
+  }
+  return codec;
+}
+
+// src/core/crypto.ts
+var AAD_VERSION = 1;
+var SCOPE_CHUNK = 0;
+var SCOPE_INDEX = 1;
+function aadFor(ref, generation, scope) {
+  const enc = new TextEncoder();
+  const ns = enc.encode(ref.namespace ?? "");
+  const seg = enc.encode(ref.segment);
+  const out = new Uint8Array(1 + 2 + ns.length + 2 + seg.length + 8 + 1 + 4);
+  const view = new DataView(out.buffer);
+  let o = 0;
+  out[o] = AAD_VERSION;
+  o += 1;
+  view.setUint16(o, ns.length, true);
+  o += 2;
+  out.set(ns, o);
+  o += ns.length;
+  view.setUint16(o, seg.length, true);
+  o += 2;
+  out.set(seg, o);
+  o += seg.length;
+  view.setBigUint64(o, BigInt(generation), true);
+  o += 8;
+  out[o] = scope === "index" ? SCOPE_INDEX : SCOPE_CHUNK;
+  o += 1;
+  view.setUint32(o, scope === "index" ? 0 : scope, true);
+  return out;
+}
+
+// src/core/validate.ts
+var CHUNK_KEY_MAX = 65535;
+var NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/;
+function validatePart(value, field) {
+  if (typeof value !== "string" || !NAME.test(value) || value.includes("..")) {
+    throw new ValidationError(
+      `${field} must match ${String(NAME)} and contain no "..": got ${JSON.stringify(value)}`
+    );
+  }
+}
+function validateSegmentRef(ref) {
+  validatePart(ref.segment, "segment");
+  if (ref.namespace !== void 0) validatePart(ref.namespace, "namespace");
+}
+function validateChunkRef(ref) {
+  validateSegmentRef(ref);
+  if (!Number.isInteger(ref.chunkKey) || ref.chunkKey < 0 || ref.chunkKey > CHUNK_KEY_MAX) {
+    throw new ValidationError(
+      `chunkKey must be an integer in [0, ${CHUNK_KEY_MAX}]; got ${ref.chunkKey}`
+    );
+  }
+}
+
+// src/core/crbm/crc32c.ts
+var TABLE = (() => {
+  const POLY = 2197175160;
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? POLY ^ c >>> 1 : c >>> 1;
+    }
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+function crc32c(bytes, seed = 0) {
+  let crc = (seed ^ 4294967295) >>> 0;
+  for (let i = 0; i < bytes.length; i++) {
+    crc = (TABLE[(crc ^ bytes[i]) & 255] ^ crc >>> 8) >>> 0;
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+
+// src/core/crbm/varint.ts
+var U32_CEIL = 4294967296;
+function writeVarint(out, value) {
+  if (!Number.isInteger(value) || value < 0 || value >= U32_CEIL) {
+    throw new RangeError(`varint value must be a u32; got ${value}`);
+  }
+  let v = value;
+  while (v > 127) {
+    out.push(v & 127 | 128);
+    v >>>= 7;
+  }
+  out.push(v);
+}
+function readVarint(bytes, offset) {
+  let result = 0;
+  let shift = 0;
+  let pos = offset;
+  for (let i = 0; i < 5; i++) {
+    if (pos >= bytes.length) {
+      throw new IntegrityError("varint truncated past end of buffer");
+    }
+    const byte = bytes[pos];
+    pos += 1;
+    if (i === 4 && byte > 15) {
+      throw new IntegrityError("varint exceeds u32 range");
+    }
+    result += (byte & 127) * 2 ** shift;
+    if ((byte & 128) === 0) {
+      return { value: result, next: pos };
+    }
+    shift += 7;
+  }
+  throw new IntegrityError("varint exceeds u32 range");
+}
+
+// src/core/crbm/format.ts
+var MAGIC = Uint8Array.of(67, 82, 66, 77);
+var VERSION_MAJOR = 1;
+var VERSION_MINOR = 0;
+var PREAMBLE_BYTES = 8;
+var PAYLOAD_START = PREAMBLE_BYTES;
+var FOOTER_BYTES = 104;
+var FOOTER = {
+  indexOffset: 0,
+  // u64
+  indexLength: 8,
+  // u64
+  indexCrc32c: 16,
+  // u32
+  flags: 20,
+  // u32
+  roaringSerializationId: 24,
+  // u16
+  elementWidth: 26,
+  // u8
+  containerCodec: 27,
+  // u8
+  versionMajor: 28,
+  // u8
+  versionMinor: 29,
+  // u16
+  generation: 32,
+  // u64
+  indexNonce: 40,
+  // 12 B
+  indexTag: 52,
+  // 16 B
+  chunkCount: 84,
+  // u32
+  totalCardinality: 88,
+  // u64
+  footerCrc32c: 96,
+  // u32 — covers footer bytes [0, 96)
+  endMagic: 100
+  // char[4]
+};
+var FOOTER_CRC_COVERAGE = FOOTER.footerCrc32c;
+var FLAG_ENCRYPTED = 1 << 0;
+var FLAG_LITTLE_ENDIAN = 1 << 2;
+var ELEMENT_WIDTH_32 = 32;
+var ROARING_PORTABLE_ID = 1;
+var CONTAINER_CODEC_NONE = 0;
+var DEFAULT_TAIL_BYTES = 256 * 1024;
+var DEFAULT_MAX_INDEX_BYTES = 8 * 1024 * 1024;
+var DEFAULT_MAX_PAYLOAD_BYTES = 16 * 1024 * 1024;
+var MAX_CHUNK_CARDINALITY = 65536;
+var CRC32C_BYTES = 4;
+var AEAD_NONCE_BYTES = 12;
+var AEAD_TAG_BYTES = 16;
+
+// src/core/crbm/reader.ts
+var RETAINED_BYTES_PER_INDEX_ENTRY = 160;
+function magicMatches(bytes, offset) {
+  return bytes[offset] === MAGIC[0] && bytes[offset + 1] === MAGIC[1] && bytes[offset + 2] === MAGIC[2] && bytes[offset + 3] === MAGIC[3];
+}
+function readU64(view, offset, field) {
+  const big = view.getBigUint64(offset, true);
+  if (big > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new IntegrityError(`.crbm ${field} ${big} exceeds safe-integer range`);
+  }
+  return Number(big);
+}
+var CrbmReader = class _CrbmReader {
+  constructor(blob, objectSize, generation, totalCardinality, entries, orderedKeys, servedFromTail, crypto) {
+    this.blob = blob;
+    this.objectSize = objectSize;
+    this.generation = generation;
+    this.totalCardinality = totalCardinality;
+    this.entries = entries;
+    this.orderedKeys = orderedKeys;
+    this.servedFromTail = servedFromTail;
+    this.crypto = crypto;
+  }
+  blob;
+  objectSize;
+  generation;
+  totalCardinality;
+  entries;
+  orderedKeys;
+  servedFromTail;
+  crypto;
+  /** Total object bytes (from the one-GET tail read) — for grounded storage cost (Phase 5b). */
+  get sizeBytes() {
+    return this.objectSize;
+  }
+  /**
+   * Estimated retained JS heap of this reader's parsed index — the weight the cold reader cache bounds on
+   * (gap #1: a wide segment's index dominates the reader's footprint). `entries.size` scales with the number
+   * of resident chunks (≤ 65536), so this is `entries.size × {@link RETAINED_BYTES_PER_INDEX_ENTRY}`.
+   */
+  get retainedIndexBytes() {
+    return this.entries.size * RETAINED_BYTES_PER_INDEX_ENTRY;
+  }
+  /** Per-chunk cardinality (`chunkKey → count`) from the parsed index — no payload reads (Phase 5c cheap count). */
+  cardinalities() {
+    const out = /* @__PURE__ */ new Map();
+    for (const [chunkKey, entry] of this.entries) out.set(chunkKey, entry.cardinality);
+    return out;
+  }
+  static async open(blob, options = {}) {
+    const tailBytes = Math.max(options.tailBytes ?? DEFAULT_TAIL_BYTES, FOOTER_BYTES);
+    const maxPayloadBytes = options.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES;
+    const maxIndexBytes = options.maxIndexBytes ?? DEFAULT_MAX_INDEX_BYTES;
+    const { bytes: tail, size } = await blob.getTail(tailBytes);
+    if (size < PREAMBLE_BYTES + FOOTER_BYTES || tail.length < FOOTER_BYTES) {
+      throw new IntegrityError(`.crbm too small: ${size}B`);
+    }
+    const footer = tail.subarray(tail.length - FOOTER_BYTES);
+    if (!magicMatches(footer, FOOTER.endMagic)) {
+      throw new IntegrityError(".crbm end magic mismatch");
+    }
+    const fview = new DataView(footer.buffer, footer.byteOffset, footer.byteLength);
+    const storedFooterCrc = fview.getUint32(FOOTER.footerCrc32c, true);
+    if (crc32c(footer.subarray(0, FOOTER_CRC_COVERAGE)) !== storedFooterCrc) {
+      throw new IntegrityError(".crbm footer CRC mismatch");
+    }
+    const versionMajor = footer[FOOTER.versionMajor];
+    if (versionMajor !== VERSION_MAJOR) {
+      throw new UnsupportedError(`.crbm major version ${versionMajor} not supported`);
+    }
+    const flags = fview.getUint32(FOOTER.flags, true);
+    const encrypted = (flags & FLAG_ENCRYPTED) !== 0;
+    if (encrypted && options.crypto === void 0) {
+      throw new ValidationError(".crbm is encrypted but no decryption key (crypto) was provided");
+    }
+    if ((flags & FLAG_LITTLE_ENDIAN) === 0) {
+      throw new UnsupportedError(".crbm big-endian layout not supported (v1 is little-endian)");
+    }
+    if ((flags & -6) !== 0) {
+      throw new UnsupportedError(`.crbm has unknown flag bits set: 0x${flags.toString(16)}`);
+    }
+    const elementWidth = footer[FOOTER.elementWidth];
+    if (elementWidth !== ELEMENT_WIDTH_32) {
+      throw new UnsupportedError(
+        `.crbm element_width ${elementWidth} not supported (v1 reads 32-bit ids; 64-bit is a future major version)`
+      );
+    }
+    const serializationId = fview.getUint16(FOOTER.roaringSerializationId, true);
+    if (serializationId !== ROARING_PORTABLE_ID) {
+      throw new UnsupportedError(
+        `.crbm roaring_serialization_id ${serializationId} not supported (v1 is portable=${ROARING_PORTABLE_ID})`
+      );
+    }
+    const containerCodec = footer[FOOTER.containerCodec];
+    if (containerCodec !== CONTAINER_CODEC_NONE) {
+      throw new UnsupportedError(
+        `.crbm container_codec ${containerCodec} not supported (v1 defines only ${CONTAINER_CODEC_NONE}=none)`
+      );
+    }
+    const indexOffset = readU64(fview, FOOTER.indexOffset, "index_offset");
+    const indexLength = readU64(fview, FOOTER.indexLength, "index_length");
+    const indexCrc = fview.getUint32(FOOTER.indexCrc32c, true);
+    const chunkCount = fview.getUint32(FOOTER.chunkCount, true);
+    const totalCardinality = readU64(fview, FOOTER.totalCardinality, "total_cardinality");
+    const generation = readU64(fview, FOOTER.generation, "generation");
+    if (indexOffset < PAYLOAD_START || indexOffset + indexLength > size - FOOTER_BYTES) {
+      throw new IntegrityError(
+        `.crbm index region [${indexOffset}, +${indexLength}) out of bounds`
+      );
+    }
+    if (indexLength > maxIndexBytes) {
+      throw new IntegrityError(`.crbm index ${indexLength}B exceeds cap ${maxIndexBytes}B`);
+    }
+    const tailCoversFrom = size - tail.length;
+    if (tailCoversFrom === 0) {
+      if (!magicMatches(tail, 0) || tail[4] !== versionMajor) {
+        throw new IntegrityError(".crbm preamble magic/version mismatch with footer");
+      }
+    }
+    let indexBytes;
+    let servedFromTail;
+    if (indexOffset >= tailCoversFrom) {
+      const start = indexOffset - tailCoversFrom;
+      indexBytes = tail.subarray(start, start + indexLength);
+      servedFromTail = true;
+    } else {
+      indexBytes = await blob.getRange(indexOffset, indexLength);
+      servedFromTail = false;
+    }
+    if (crc32c(indexBytes) !== indexCrc) {
+      throw new IntegrityError(".crbm index CRC mismatch");
+    }
+    const indexForParse = encrypted ? options.crypto.aead.open(
+      {
+        nonce: footer.subarray(FOOTER.indexNonce, FOOTER.indexNonce + AEAD_NONCE_BYTES),
+        ciphertext: indexBytes,
+        tag: footer.subarray(FOOTER.indexTag, FOOTER.indexTag + AEAD_TAG_BYTES)
+      },
+      options.crypto.aadFor("index")
+    ) : indexBytes;
+    const { entries, orderedKeys, cardinalitySum } = parseIndex(
+      indexForParse,
+      size,
+      maxPayloadBytes
+    );
+    if (encrypted) {
+      if (chunkCount !== 0 || totalCardinality !== 0) {
+        throw new IntegrityError(
+          ".crbm encrypted footer must zero chunk_count + total_cardinality"
+        );
+      }
+    } else {
+      if (entries.size !== chunkCount) {
+        throw new IntegrityError(
+          `.crbm chunk_count ${chunkCount} != ${entries.size} index entries`
+        );
+      }
+      if (cardinalitySum !== totalCardinality) {
+        throw new IntegrityError(
+          `.crbm total_cardinality ${totalCardinality} != \u03A3 index cardinality ${cardinalitySum}`
+        );
+      }
+    }
+    return new _CrbmReader(
+      blob,
+      size,
+      generation,
+      cardinalitySum,
+      entries,
+      orderedKeys,
+      servedFromTail,
+      options.crypto
+    );
+  }
+  /** Chunk keys present in this generation, ascending. */
+  chunkKeys() {
+    return this.orderedKeys.slice();
+  }
+  /** Segment cardinality from the footer (no payload reads) — the cheap `count()` path. */
+  count() {
+    return this.totalCardinality;
+  }
+  has(chunkKey) {
+    return this.entries.has(chunkKey);
+  }
+  /**
+   * Range-GET one chunk's payload, verifying its CRC32C before returning. Returns `null` if the chunk is
+   * absent. Throws `IntegrityError` on a CRC mismatch (the bytes must never reach the native
+   * deserializer). The returned buffer is a **read-only view** owned by the reader/driver — callers must
+   * not mutate it.
+   */
+  async getChunk(chunkKey) {
+    const e = this.entries.get(chunkKey);
+    if (e === void 0) return null;
+    if (e.offset < PAYLOAD_START || e.offset + e.length > this.objectSize - FOOTER_BYTES) {
+      throw new IntegrityError(`chunk ${chunkKey} payload out of bounds`);
+    }
+    const bytes = await this.blob.getRange(e.offset, e.length);
+    if (crc32c(bytes) !== e.crc32c) {
+      throw new IntegrityError(`chunk ${chunkKey} payload CRC mismatch`);
+    }
+    if (this.crypto === void 0) return bytes;
+    if (bytes.length < AEAD_NONCE_BYTES + AEAD_TAG_BYTES) {
+      throw new IntegrityError(`chunk ${chunkKey} encrypted payload too short`);
+    }
+    return this.crypto.aead.open(
+      {
+        nonce: bytes.subarray(0, AEAD_NONCE_BYTES),
+        ciphertext: bytes.subarray(AEAD_NONCE_BYTES, bytes.length - AEAD_TAG_BYTES),
+        tag: bytes.subarray(bytes.length - AEAD_TAG_BYTES)
+      },
+      this.crypto.aadFor(chunkKey)
+    );
+  }
+};
+function parseIndex(indexBytes, objectSize, maxPayloadBytes) {
+  const entries = /* @__PURE__ */ new Map();
+  const orderedKeys = [];
+  let pos = 0;
+  let prevKey = 0;
+  let prevEnd = PAYLOAD_START;
+  let cardinalitySum = 0;
+  for (let i = 0; pos < indexBytes.length; i++) {
+    const keyDelta = readVarint(indexBytes, pos);
+    const offDelta = readVarint(indexBytes, keyDelta.next);
+    const len = readVarint(indexBytes, offDelta.next);
+    const card = readVarint(indexBytes, len.next);
+    pos = card.next;
+    if (pos + CRC32C_BYTES > indexBytes.length) {
+      throw new IntegrityError(".crbm index truncated (missing payload CRC)");
+    }
+    const crc = (indexBytes[pos] | indexBytes[pos + 1] << 8 | indexBytes[pos + 2] << 16 | indexBytes[pos + 3] << 24) >>> 0;
+    pos += CRC32C_BYTES;
+    const chunkKey = prevKey + keyDelta.value;
+    const offset = prevEnd + offDelta.value;
+    if (i > 0 && keyDelta.value === 0) {
+      throw new IntegrityError(`.crbm index has a duplicate chunkKey ${chunkKey}`);
+    }
+    if (chunkKey > 65535) throw new IntegrityError(`.crbm chunkKey ${chunkKey} out of range`);
+    if (len.value === 0 || len.value > maxPayloadBytes) {
+      throw new IntegrityError(`.crbm chunk ${chunkKey} length ${len.value} invalid`);
+    }
+    if (card.value < 1 || card.value > MAX_CHUNK_CARDINALITY) {
+      throw new IntegrityError(`.crbm chunk ${chunkKey} cardinality ${card.value} invalid`);
+    }
+    if (offset < PAYLOAD_START || offset + len.value > objectSize - FOOTER_BYTES) {
+      throw new IntegrityError(`.crbm chunk ${chunkKey} payload out of bounds`);
+    }
+    entries.set(chunkKey, {
+      chunkKey,
+      offset,
+      length: len.value,
+      cardinality: card.value,
+      crc32c: crc
+    });
+    orderedKeys.push(chunkKey);
+    cardinalitySum += card.value;
+    prevKey = chunkKey;
+    prevEnd = offset + len.value;
+  }
+  return { entries, orderedKeys, cardinalitySum };
+}
+
+// src/core/crbm/writer.ts
+var CrbmWriter = class {
+  constructor(sink, options) {
+    this.sink = sink;
+    this.options = options;
+    if (!Number.isInteger(options.generation) || options.generation < 0) {
+      throw new ValidationError(
+        `generation must be a non-negative integer; got ${options.generation}`
+      );
+    }
+  }
+  sink;
+  options;
+  entries = [];
+  offset = PAYLOAD_START;
+  lastKey = -1;
+  totalCardinality = 0;
+  preambleWritten = false;
+  finished = false;
+  /**
+   * Append one chunk's payload (the roaring-serialized bytes) with its cardinality. `chunkKey` must be
+   * strictly greater than the previous one (ascending, no duplicates); `cardinality` is `[1, 65536]`.
+   */
+  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}`);
+    }
+    if (chunkKey <= this.lastKey) {
+      throw new ValidationError(
+        `chunkKey ${chunkKey} not strictly ascending (last ${this.lastKey})`
+      );
+    }
+    if (!Number.isInteger(cardinality) || cardinality < 1 || cardinality > MAX_CHUNK_CARDINALITY) {
+      throw new ValidationError(
+        `cardinality must be in [1, ${MAX_CHUNK_CARDINALITY}]; got ${cardinality}`
+      );
+    }
+    if (payload.length === 0) throw new ValidationError("chunk payload must be non-empty");
+    await this.ensurePreamble();
+    const stored = this.options.crypto ? this.sealChunk(chunkKey, payload) : payload;
+    await this.sink.write(stored);
+    this.entries.push({
+      chunkKey,
+      offset: this.offset,
+      length: stored.length,
+      cardinality,
+      crc32c: crc32c(stored)
+    });
+    this.offset += stored.length;
+    this.totalCardinality += cardinality;
+    this.lastKey = chunkKey;
+  }
+  /** Seal one chunk payload into the on-disk frame `nonce ‖ ciphertext ‖ tag`, bound to its chunkKey. */
+  sealChunk(chunkKey, payload) {
+    const crypto = this.options.crypto;
+    const sealed = crypto.aead.seal(payload, crypto.aadFor(chunkKey));
+    const out = new Uint8Array(sealed.nonce.length + sealed.ciphertext.length + sealed.tag.length);
+    out.set(sealed.nonce, 0);
+    out.set(sealed.ciphertext, sealed.nonce.length);
+    out.set(sealed.tag, sealed.nonce.length + sealed.ciphertext.length);
+    return out;
+  }
+  /** Write the index region + the fixed footer. After this the object is complete and immutable. */
+  async finish() {
+    if (this.finished) throw new ValidationError("CrbmWriter already finished");
+    await this.ensurePreamble();
+    const indexPlain = this.encodeIndex();
+    let indexRegion = indexPlain;
+    let indexNonce;
+    let indexTag;
+    if (this.options.crypto !== void 0) {
+      const sealed = this.options.crypto.aead.seal(indexPlain, this.options.crypto.aadFor("index"));
+      indexRegion = sealed.ciphertext;
+      indexNonce = sealed.nonce;
+      indexTag = sealed.tag;
+    }
+    const indexOffset = this.offset;
+    await this.sink.write(indexRegion);
+    this.offset += indexRegion.length;
+    const footer = this.buildFooter(indexOffset, indexRegion, indexNonce, indexTag);
+    await this.sink.write(footer);
+    this.finished = true;
+  }
+  async ensurePreamble() {
+    if (this.preambleWritten) return;
+    const preamble = new Uint8Array(PREAMBLE_BYTES);
+    preamble.set(MAGIC, 0);
+    preamble[4] = VERSION_MAJOR;
+    preamble[5] = VERSION_MINOR;
+    await this.sink.write(preamble);
+    this.preambleWritten = true;
+  }
+  encodeIndex() {
+    const out = [];
+    let prevKey = 0;
+    let prevEnd = PAYLOAD_START;
+    for (const e of this.entries) {
+      writeVarint(out, e.chunkKey - prevKey);
+      writeVarint(out, e.offset - prevEnd);
+      writeVarint(out, e.length);
+      writeVarint(out, e.cardinality);
+      out.push(
+        e.crc32c & 255,
+        e.crc32c >>> 8 & 255,
+        e.crc32c >>> 16 & 255,
+        e.crc32c >>> 24 & 255
+      );
+      prevKey = e.chunkKey;
+      prevEnd = e.offset + e.length;
+    }
+    return Uint8Array.from(out);
+  }
+  buildFooter(indexOffset, indexRegion, indexNonce, indexTag) {
+    const encrypted = this.options.crypto !== void 0;
+    const footer = new Uint8Array(FOOTER_BYTES);
+    const view = new DataView(footer.buffer);
+    view.setBigUint64(FOOTER.indexOffset, BigInt(indexOffset), true);
+    view.setBigUint64(FOOTER.indexLength, BigInt(indexRegion.length), true);
+    view.setUint32(FOOTER.indexCrc32c, crc32c(indexRegion), true);
+    view.setUint32(FOOTER.flags, FLAG_LITTLE_ENDIAN | (encrypted ? FLAG_ENCRYPTED : 0), true);
+    view.setUint16(
+      FOOTER.roaringSerializationId,
+      this.options.roaringSerializationId ?? ROARING_PORTABLE_ID,
+      true
+    );
+    footer[FOOTER.elementWidth] = this.options.elementWidth ?? ELEMENT_WIDTH_32;
+    footer[FOOTER.containerCodec] = CONTAINER_CODEC_NONE;
+    footer[FOOTER.versionMajor] = VERSION_MAJOR;
+    footer[FOOTER.versionMinor] = VERSION_MINOR;
+    if (indexNonce !== void 0) footer.set(indexNonce, FOOTER.indexNonce);
+    if (indexTag !== void 0) footer.set(indexTag, FOOTER.indexTag);
+    view.setBigUint64(FOOTER.generation, BigInt(this.options.generation), true);
+    view.setUint32(FOOTER.chunkCount, encrypted ? 0 : this.entries.length, true);
+    view.setBigUint64(FOOTER.totalCardinality, BigInt(encrypted ? 0 : this.totalCardinality), true);
+    view.setUint32(FOOTER.footerCrc32c, crc32c(footer.subarray(0, FOOTER_CRC_COVERAGE)), true);
+    footer.set(MAGIC, FOOTER.endMagic);
+    return footer;
+  }
+};
+
+// src/core/crbm-cold-source.ts
+function coldBlobReader(driver, key) {
+  return {
+    getRange(offset, length) {
+      return driver.getRange(key, offset, length);
+    },
+    getTail(maxBytes) {
+      return driver.getTail(key, maxBytes);
+    }
+  };
+}
+var DEFAULT_CURRENT_GEN_TTL_MS = 2e3;
+var DEFAULT_MAX_OPEN_SEGMENTS = 1024;
+var DEFAULT_MAX_OPEN_INDEX_BYTES = 64 * 1024 * 1024;
+var CrbmColdChunkSource = class {
+  constructor(driver, options = {}) {
+    this.driver = driver;
+    if (!driver.capabilities().rangeRead) {
+      throw new CapabilityError("Cold driver must support range reads (rangeRead)");
+    }
+    const {
+      registry,
+      keystore,
+      requireEncryption,
+      clock,
+      currentGenTtlMs,
+      maxOpenSegments,
+      maxOpenIndexBytes,
+      ...readerOptions
+    } = options;
+    if (keystore !== void 0 && registry === void 0) {
+      throw new CapabilityError(
+        "a keystore needs a registry (that is where wrapped DEKs are stored)"
+      );
+    }
+    if (requireEncryption === true && registry === void 0) {
+      throw new CapabilityError("requireEncryption needs a registry");
+    }
+    this.registry = registry;
+    this.keystore = keystore;
+    this.requireEncryption = requireEncryption ?? false;
+    this.readerOptions = readerOptions;
+    this.clock = clock;
+    this.currentGenTtlMs = currentGenTtlMs ?? DEFAULT_CURRENT_GEN_TTL_MS;
+    this.snapshots = new BoundedLru({
+      maxEntries: maxOpenSegments ?? DEFAULT_MAX_OPEN_SEGMENTS,
+      maxBytes: maxOpenIndexBytes ?? DEFAULT_MAX_OPEN_INDEX_BYTES,
+      clock: clock ?? { now: () => 0 }
+    });
+  }
+  driver;
+  /**
+   * One resolved reader per segment, re-resolved on a short TTL ({@link CrbmColdChunkSourceOptions.currentGenTtlMs},
+   * needs a clock). Within the TTL a segment's Cold bytes are treated as an immutable snapshot; when the TTL
+   * elapses the next read cheaply re-resolves `currentGen` and, only if it advanced (a compaction committed),
+   * opens the new generation — so a long-lived source observes new generations within the TTL rather than
+   * pinning one forever (gap #4). The engine pairs this with a **generation-keyed** HOT cache so a bump never
+   * serves a stale decoded chunk. Without a clock or a registry the source pins the first generation for its
+   * lifetime (pre-Phase-B behaviour). A segment with no generation yet is not memoized, so it's re-checked until
+   * one exists. **Bounded** by a {@link BoundedLru} ({@link CrbmColdChunkSourceOptions.maxOpenSegments}, default
+   * 1024): past the ceiling the least-recently-used segment's reader (and its parsed index) is evicted — the
+   * steady-state memory bound (gap #1); re-opening an evicted segment is one cheap tail GET.
+   */
+  snapshots;
+  registry;
+  keystore;
+  requireEncryption;
+  readerOptions;
+  clock;
+  currentGenTtlMs;
+  /** The current resolved reader for a segment, refreshing on the TTL (gap #4). Cheap within the TTL window. */
+  resolvedReader(ref) {
+    const key = segmentKey(ref);
+    const existing = this.snapshots.get(key);
+    if (existing === void 0) return this.install(key, this.resolveLatest(ref)).reader;
+    if (!this.expired(existing.installedAtMs)) return existing.reader;
+    return this.install(key, this.computeRefreshedReader(ref, existing)).reader;
+  }
+  /** TTL elapsed: cheaply re-resolve `currentGen`; reopen only if it actually changed, else reuse the prior reader. */
+  async computeRefreshedReader(ref, existing) {
+    const current = await existing.reader.catch(() => null);
+    let target;
+    try {
+      target = await this.resolveTarget(ref);
+    } catch {
+      target = void 0;
+    }
+    if (target === void 0) return current ?? this.resolveLatest(ref);
+    if (target === null) return null;
+    if (current !== null && target.generation === current.generation) return current;
+    return this.openForTarget(ref, target);
+  }
+  /**
+   * Memoize a reader-promise as the segment's snapshot at `now()`, forgetting it later if it resolves to
+   * null / throws (identity-guarded, so a stale cleanup never clobbers a fresher snapshot). Installing the
+   * (pending) promise **synchronously** is what lets concurrent callers coalesce onto one in-flight resolve.
+   */
+  install(key, reader) {
+    const snap = { reader, installedAtMs: this.now() };
+    this.snapshots.set(key, snap);
+    const forgetIfStale = () => {
+      if (this.snapshots.get(key) === snap) this.snapshots.delete(key);
+    };
+    reader.then((r) => {
+      if (r === null) {
+        forgetIfStale();
+        return;
+      }
+      if (this.snapshots.peek(key) === snap) this.snapshots.setWeight(key, r.retainedIndexBytes);
+    }, forgetIfStale);
+    return snap;
+  }
+  now() {
+    return this.clock ? this.clock.now() : 0;
+  }
+  expired(installedAtMs) {
+    return this.clock !== void 0 && this.registry !== void 0 && this.currentGenTtlMs > 0 && this.clock.now() - installedAtMs >= this.currentGenTtlMs;
+  }
+  /**
+   * The segment's current generation number (gap #4) — the engine keys its HOT chunk cache by this so a
+   * compaction bump is observed instead of serving a stale decoded chunk. Served from the (TTL-refreshed)
+   * snapshot, so no extra backend read within the TTL window. `null` if the segment has no committed generation.
+   */
+  async currentGeneration(ref) {
+    const reader = await this.resolvedReader(ref);
+    return reader?.generation ?? null;
+  }
+  async resolveLatest(ref) {
+    const target = await this.resolveTarget(ref);
+    if (target === null) return null;
+    return this.openForTarget(ref, target);
+  }
+  /** Open a {@link CrbmReader} for an already-resolved generation target (decrypting if the segment is encrypted). */
+  async openForTarget(ref, target) {
+    const genKey = {
+      namespace: ref.namespace,
+      segment: ref.segment,
+      generation: target.generation
+    };
+    const crypto = await this.cryptoForRead(ref, target.generation, target.wrappedDeks);
+    return CrbmReader.open(coldBlobReader(this.driver, genKey), { ...this.readerOptions, crypto });
+  }
+  /**
+   * The current generation + its DEK wrappings: the registry's authoritative record (one strong read), or a
+   * `list` scan for the max generation when there's no registry (a registry-less source can only read cleartext
+   * — there's nowhere a wrapped DEK could live).
+   */
+  async resolveTarget(ref) {
+    if (this.registry !== void 0) {
+      const record = await this.registry.get(ref);
+      if (record === null) return null;
+      if (record.status === "destroyed") return null;
+      return { generation: record.currentGen, wrappedDeks: record.wrappedDeks };
+    }
+    let maxGen = -1;
+    for await (const key of this.driver.list(ref)) {
+      if (key.generation > maxGen) maxGen = key.generation;
+    }
+    return maxGen < 0 ? null : { generation: maxGen };
+  }
+  /** Build the per-generation decryption context for an encrypted segment (undefined for cleartext). */
+  async cryptoForRead(ref, generation, wrappedDeks) {
+    if (wrappedDeks === void 0 || wrappedDeks.length === 0) {
+      if (this.requireEncryption) {
+        throw new KeyUnavailableError(
+          `requireEncryption: segment "${ref.segment}" is cleartext but encryption is required`
+        );
+      }
+      return void 0;
+    }
+    if (this.keystore === void 0) {
+      throw new KeyUnavailableError(
+        `segment "${ref.segment}" is encrypted but this CrbmColdChunkSource has no keystore`
+      );
+    }
+    const aead = await this.keystore.openDek(wrappedDeks);
+    return { aead, aadFor: (scope) => aadFor(ref, generation, scope) };
+  }
+  async getChunk(ref) {
+    validateChunkRef(ref);
+    return this.withFreshSnapshot(ref, (reader) => reader.getChunk(ref.chunkKey), null);
+  }
+  async listChunkKeys(ref) {
+    validateSegmentRef(ref);
+    return this.withFreshSnapshot(ref, (reader) => reader.chunkKeys(), []);
+  }
+  async sizeOf(ref) {
+    validateSegmentRef(ref);
+    return this.withFreshSnapshot(
+      ref,
+      (reader) => ({ sizeBytes: reader.sizeBytes }),
+      null
+    );
+  }
+  async cardinalities(ref) {
+    validateSegmentRef(ref);
+    return this.withFreshSnapshot(
+      ref,
+      (reader) => reader.cardinalities(),
+      null
+    );
+  }
+  /**
+   * Run `read` against the pinned snapshot, healing the one torn-read window compaction's GC can open: if the
+   * generation we pinned was superseded *and* swept (the grace window elapsed) mid-read, the Cold driver throws
+   * {@link NotFoundError}. Rather than surface that as a query failure (**I5**), we drop the stale snapshot,
+   * re-resolve `currentGen`, and retry once — the read then serves the newer (committed, immutable) generation,
+   * a monotonic move forward. A *second* NotFound is pathological (GC outrunning resolution) and propagates
+   * rather than fabricate an absent answer — never return a wrong result. `ifGone` is returned only when the
+   * segment legitimately has no committed generation at all (cold is empty). The single retry is bounded.
+   */
+  async withFreshSnapshot(ref, read, ifGone) {
+    const key = segmentKey(ref);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const pending = this.resolvedReader(ref);
+      const reader = await pending;
+      if (reader === null) return ifGone;
+      try {
+        return await read(reader);
+      } catch (err) {
+        if (!isNotFoundError(err) || attempt === 1) throw err;
+        const cur = this.snapshots.get(key);
+        if (cur !== void 0 && cur.reader === pending) this.snapshots.delete(key);
+      }
+    }
+    return ifGone;
+  }
+};
+function writeCrbmGeneration(driver, key, chunks, options = {}) {
+  const sorted = [...chunks].sort((a, b) => a.chunkKey - b.chunkKey);
+  return driver.putImmutable(key, async (sink) => {
+    const writer = new CrbmWriter(sink, { generation: key.generation, crypto: options.crypto });
+    for (const { chunkKey, bitmap } of sorted) {
+      if (bitmap.isEmpty) continue;
+      await writer.addChunk(chunkKey, bitmap.serialize(), bitmap.size);
+    }
+    await writer.finish();
+  });
+}
+async function writeCrbmGenerationStream(driver, key, chunks, options = {}) {
+  const chunkKeys = [];
+  let cardinality = 0;
+  const { size, sha256 } = await driver.putImmutable(key, async (sink) => {
+    const writer = new CrbmWriter(sink, { generation: key.generation, crypto: options.crypto });
+    for await (const { chunkKey, bitmap } of chunks) {
+      if (bitmap.isEmpty) continue;
+      await writer.addChunk(chunkKey, bitmap.serialize(), bitmap.size);
+      chunkKeys.push(chunkKey);
+      cardinality += bitmap.size;
+    }
+    await writer.finish();
+  });
+  return { size, sha256, chunkKeys, cardinality };
+}
+async function publishGeneration(registry, key, options = {}) {
+  for (let attempt = 0; attempt < 5; attempt++) {
+    const record = await registry.get(key);
+    try {
+      if (record === null) {
+        await registry.create(key, {
+          currentGen: key.generation,
+          wrappedDeks: options.wrappedDeks
+        });
+      } else if (record.currentGen > key.generation) {
+        return false;
+      } else if (record.currentGen === key.generation) {
+        return true;
+      } else {
+        await registry.compareAndSwap(key, record.token, { currentGen: key.generation });
+      }
+      return true;
+    } catch (err) {
+      if (isWriteConflictError(err)) continue;
+      throw err;
+    }
+  }
+  const final = await registry.get(key);
+  if (final !== null && final.currentGen >= key.generation)
+    return final.currentGen === key.generation;
+  throw new WriteConflictError(
+    `publishGeneration: contention setting currentGen for ${key.segment}`
+  );
+}
+async function bulkLoadCrbmGeneration(driver, key, ids, options = {}) {
+  if (options.keystore === void 0 && options.requireEncryption === true) {
+    throw new ValidationError("requireEncryption: bulk-load needs a keystore to write encrypted");
+  }
+  const codec = requireCodec(options.codec, "bulkLoadCrbmGeneration");
+  const byChunk = /* @__PURE__ */ new Map();
+  for await (const id of toAsyncIterable(ids)) {
+    const { chunkKey, remainder } = splitId(id);
+    let bitmap = byChunk.get(chunkKey);
+    if (bitmap === void 0) {
+      bitmap = codec.empty();
+      byChunk.set(chunkKey, bitmap);
+    }
+    bitmap.add(remainder);
+  }
+  let cardinality = 0;
+  const chunks = [];
+  for (const [chunkKey, bitmap] of byChunk) {
+    cardinality += bitmap.size;
+    chunks.push({ chunkKey, bitmap });
+  }
+  if (options.keystore !== void 0 && options.registry === void 0) {
+    throw new ValidationError("bulk-load encryption requires a registry to store the wrapped DEK");
+  }
+  const existing = options.registry !== void 0 ? await options.registry.get(key) : null;
+  if (existing?.status === "destroyed") {
+    throw new ValidationError(
+      `segment "${key.segment}" is destroyed (crypto-shredded) \u2014 refusing to write; use a new segment`
+    );
+  }
+  let crypto;
+  let newWrapped;
+  if (options.keystore !== void 0) {
+    if (existing?.wrappedDeks !== void 0 && existing.wrappedDeks.length > 0) {
+      const aead = await options.keystore.openDek(existing.wrappedDeks);
+      crypto = { aead, aadFor: (scope) => aadFor(key, key.generation, scope) };
+    } else {
+      const minted = await options.keystore.createDek();
+      newWrapped = minted.wrapped;
+      crypto = { aead: minted.aead, aadFor: (scope) => aadFor(key, key.generation, scope) };
+    }
+  }
+  const { size, sha256 } = await writeCrbmGeneration(driver, key, chunks, { crypto });
+  if (options.registry !== void 0) {
+    const becameCurrent = await publishGeneration(options.registry, key, {
+      wrappedDeks: newWrapped
+    });
+    if (becameCurrent) {
+      safeAudit(options.audit ?? NOOP_AUDIT).onEvent({
+        kind: "segment.publish",
+        namespace: key.namespace,
+        segment: key.segment,
+        generation: key.generation
+      });
+    }
+  }
+  return { size, sha256, chunkCount: chunks.length, cardinality };
+}
+async function* toAsyncIterable(src) {
+  if (Symbol.asyncIterator in src) {
+    yield* src;
+  } else {
+    yield* src;
+  }
+}
+
+// src/core/compaction.ts
+var DEFAULT_MAX_BITMAP_BYTES2 = 1 << 20;
+var DEFAULT_LEASE_MS = 6e4;
+var DEFAULT_QUARANTINE_THRESHOLD = 5;
+var DEFAULT_QUARANTINE_COOLDOWN_MS = 5 * 6e4;
+function validateCompactionOptions(options) {
+  if (typeof options.owner !== "string" || options.owner.length === 0) {
+    throw new ValidationError(
+      "compaction: options.owner must be a non-empty string (the lease owner id)"
+    );
+  }
+  if (options.leaseMs !== void 0 && (!Number.isFinite(options.leaseMs) || options.leaseMs <= 0)) {
+    throw new ValidationError(
+      `compaction: options.leaseMs must be a positive finite number; got ${options.leaseMs}`
+    );
+  }
+}
+async function compactSegment(ref, deps, options) {
+  validateCompactionOptions(options);
+  const startedAt = deps.clock.now();
+  const emit = (r) => {
+    if (deps.metrics === void 0) return;
+    try {
+      deps.metrics.onEvent({
+        kind: "compaction",
+        namespace: ref.namespace,
+        segment: ref.segment,
+        compacted: r.compacted,
+        reason: r.reason,
+        dirtyChunks: r.dirtyChunks,
+        purged: r.purged,
+        ms: Math.max(0, deps.clock.now() - startedAt)
+      });
+    } catch {
+    }
+  };
+  try {
+    const result = await compactSegmentInner(ref, deps, options);
+    emit(result);
+    return result;
+  } catch (err) {
+    emit({ compacted: false, reason: "error", dirtyChunks: 0, purged: 0 });
+    throw err;
+  }
+}
+async function compactSegmentInner(ref, deps, options) {
+  const now = () => deps.clock.now();
+  const maxBytes = deps.maxBitmapBytes ?? DEFAULT_MAX_BITMAP_BYTES2;
+  const leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;
+  const base = { segment: ref.segment, namespace: ref.namespace };
+  const audit = safeAudit(options.audit ?? NOOP_AUDIT);
+  const auditCompacted = (generation) => audit.onEvent({
+    kind: "segment.compact",
+    namespace: ref.namespace,
+    segment: ref.segment,
+    generation
+  });
+  const cryptoAt = (aead, generation) => aead === void 0 ? void 0 : { aead, aadFor: (scope) => aadFor(ref, generation, scope) };
+  const record = await deps.registry.get(ref);
+  if (record !== null && record.status === "destroyed") {
+    return {
+      ...base,
+      compacted: false,
+      reason: "destroyed",
+      fromGen: record.currentGen,
+      dirtyChunks: 0,
+      purged: 0,
+      survived: 0
+    };
+  }
+  if (record === null) {
+    const pinned = await collectDirty(
+      deps.warm,
+      ref,
+      maxBytes,
+      requireCodec(deps.codec, "compactSegment")
+    );
+    if (pinned.length === 0)
+      return {
+        ...base,
+        compacted: false,
+        reason: "clean",
+        fromGen: null,
+        dirtyChunks: 0,
+        purged: 0,
+        survived: 0
+      };
+    let aead;
+    let wrappedDeks;
+    if (deps.keystore !== void 0) {
+      const minted = await deps.keystore.createDek();
+      aead = minted.aead;
+      wrappedDeks = minted.wrapped;
+    } else if (deps.requireEncryption === true) {
+      throw new ValidationError(
+        `requireEncryption: segment "${ref.segment}" needs a keystore to bootstrap encrypted`
+      );
+    }
+    const gen0 = { namespace: ref.namespace, segment: ref.segment, generation: 0 };
+    const stream = mergeChunksStream(ref, null, pinned, deps, maxBytes, void 0);
+    let wrote = true;
+    let tally;
+    try {
+      tally = await writeCrbmGenerationStream(deps.cold, gen0, stream, {
+        crypto: cryptoAt(aead, 0)
+      });
+    } catch (err) {
+      if (!isWriteConflictError(err)) throw err;
+      wrote = false;
+    }
+    if (wrote && tally !== void 0) {
+      await verifyGeneration(deps.cold, gen0, tally, cryptoAt(aead, 0));
+    }
+    try {
+      await deps.registry.create(ref, {
+        currentGen: 0,
+        dirtyChunkCount: 0,
+        status: "active",
+        wrappedDeks
+      });
+    } catch (err) {
+      if (!isWriteConflictError(err)) throw err;
+    }
+    if (!wrote)
+      return {
+        ...base,
+        compacted: false,
+        reason: "bootstrap-raced",
+        fromGen: null,
+        dirtyChunks: pinned.length,
+        purged: 0,
+        survived: pinned.length
+      };
+    auditCompacted(0);
+    const { purged, survived } = await purgeAfterCommit(deps.warm, ref, pinned);
+    return {
+      ...base,
+      compacted: true,
+      fromGen: null,
+      toGen: 0,
+      dirtyChunks: pinned.length,
+      purged,
+      survived
+    };
+  }
+  const expired = record.leaseExpiresAt === void 0 || record.leaseExpiresAt <= now();
+  const ownedByOther = record.status === "compacting" && !expired && record.leaseOwner !== options.owner;
+  if (ownedByOther) {
+    return {
+      ...base,
+      compacted: false,
+      reason: "leased-by-other",
+      fromGen: record.currentGen,
+      dirtyChunks: 0,
+      purged: 0,
+      survived: 0
+    };
+  }
+  let leaseToken;
+  try {
+    const res = await deps.registry.compareAndSwap(ref, record.token, {
+      status: "compacting",
+      leaseOwner: options.owner,
+      leaseExpiresAt: now() + leaseMs
+    });
+    leaseToken = res.token;
+  } catch (err) {
+    if (isWriteConflictError(err)) {
+      return {
+        ...base,
+        compacted: false,
+        reason: "leased-by-other",
+        fromGen: record.currentGen,
+        dirtyChunks: 0,
+        purged: 0,
+        survived: 0
+      };
+    }
+    throw err;
+  }
+  const g = record.currentGen;
+  try {
+    let aead;
+    if (record.wrappedDeks !== void 0 && record.wrappedDeks.length > 0) {
+      if (deps.keystore === void 0) {
+        throw new KeyUnavailableError(
+          `segment "${ref.segment}" is encrypted but compaction has no keystore`
+        );
+      }
+      aead = await deps.keystore.openDek(record.wrappedDeks);
+    } else if (deps.requireEncryption === true) {
+      throw new ValidationError(`requireEncryption: segment "${ref.segment}" is cleartext`);
+    }
+    const live = await deps.registry.get(ref);
+    if (live === null || live.currentGen !== g) {
+      await releaseLease(deps, ref, leaseToken);
+      return {
+        ...base,
+        compacted: false,
+        reason: "superseded",
+        fromGen: g,
+        dirtyChunks: 0,
+        purged: 0,
+        survived: 0
+      };
+    }
+    await deleteGenerationsAbove(deps.cold, ref, g);
+    const pinned = await collectDirty(
+      deps.warm,
+      ref,
+      maxBytes,
+      requireCodec(deps.codec, "compactSegment")
+    );
+    if (pinned.length === 0) {
+      await releaseLease(deps, ref, leaseToken);
+      return {
+        ...base,
+        compacted: false,
+        reason: "clean",
+        fromGen: g,
+        dirtyChunks: 0,
+        purged: 0,
+        survived: 0
+      };
+    }
+    const newGen = g + 1;
+    const stream = mergeChunksStream(ref, g, pinned, deps, maxBytes, cryptoAt(aead, g));
+    await stageGeneration(
+      deps.cold,
+      { namespace: ref.namespace, segment: ref.segment, generation: newGen },
+      stream,
+      cryptoAt(aead, newGen)
+    );
+    try {
+      await deps.registry.compareAndSwap(ref, leaseToken, {
+        currentGen: newGen,
+        status: "active",
+        leaseOwner: void 0,
+        leaseExpiresAt: void 0,
+        dirtyChunkCount: 0,
+        lastCompactedAt: now(),
+        // dead-man's-switch (gap #2): a stale value = a stuck segment
+        consecutiveFailures: 0
+        // a successful commit clears any prior poison-quarantine streak
+      });
+    } catch (err) {
+      if (isWriteConflictError(err)) {
+        return {
+          ...base,
+          compacted: false,
+          reason: "lease-lost",
+          fromGen: g,
+          dirtyChunks: pinned.length,
+          purged: 0,
+          survived: 0
+        };
+      }
+      throw err;
+    }
+    auditCompacted(newGen);
+    const { purged, survived } = await purgeAfterCommit(deps.warm, ref, pinned);
+    return {
+      ...base,
+      compacted: true,
+      fromGen: g,
+      toGen: newGen,
+      dirtyChunks: pinned.length,
+      purged,
+      survived
+    };
+  } catch (err) {
+    await releaseLease(deps, ref, leaseToken).catch(() => void 0);
+    if (isWriteConflictError(err)) {
+      return {
+        ...base,
+        compacted: false,
+        reason: "stage-conflict",
+        fromGen: g,
+        dirtyChunks: 0,
+        purged: 0,
+        survived: 0
+      };
+    }
+    throw err;
+  }
+}
+async function gcOrphanGenerations(ref, deps, options = {}) {
+  const keep = Math.max(0, options.keep ?? 1);
+  const record = await deps.registry.get(ref);
+  if (record === null) return [];
+  const current = record.currentGen;
+  const gens = [];
+  for await (const key of deps.cold.list(ref)) gens.push(key.generation);
+  const below = gens.filter((g) => g < current).sort((a, b) => b - a);
+  const toDelete = below.slice(keep);
+  for (const generation of toDelete) {
+    await deps.cold.delete({ namespace: ref.namespace, segment: ref.segment, generation });
+  }
+  return toDelete;
+}
+async function collectDirty(warm, ref, maxBytes, codec) {
+  const out = [];
+  for await (const row of warm.listChunks(ref)) {
+    out.push({
+      chunkKey: row.chunkKey,
+      token: row.token,
+      delta: decodeDelta(row.bytes, maxBytes, codec)
+    });
+  }
+  return out;
+}
+async function* mergeChunksStream(ref, g, pinned, deps, maxBytes, readCrypto) {
+  const codec = requireCodec(deps.codec, "compactSegment");
+  const dirty = new Map(pinned.map((p) => [p.chunkKey, p.delta]));
+  const reader = g === null ? null : await openReader(
+    deps.cold,
+    { namespace: ref.namespace, segment: ref.segment, generation: g },
+    readCrypto
+  );
+  const keys = new Set(dirty.keys());
+  if (reader !== null) for (const k of reader.chunkKeys()) keys.add(k);
+  for (const chunkKey of [...keys].sort((a, b) => a - b)) {
+    const coldBytes = reader === null ? null : await reader.getChunk(chunkKey);
+    const cold = coldBytes === null ? codec.empty() : codec.safeDeserialize(coldBytes, maxBytes);
+    const merged = effective(cold, dirty.get(chunkKey) ?? emptyDelta(codec));
+    if (!merged.isEmpty) yield { chunkKey, bitmap: merged };
+  }
+}
+async function stageGeneration(cold, key, chunks, crypto) {
+  const tally = await writeCrbmGenerationStream(cold, key, chunks, { crypto });
+  await verifyGeneration(cold, key, tally, crypto);
+}
+async function verifyGeneration(cold, key, expected, crypto) {
+  const expectedCount = expected.cardinality;
+  const expectedKeys = [...expected.chunkKeys].sort((a, b) => a - b);
+  const reader = await openReader(cold, key, crypto);
+  const actualKeys = [...reader.chunkKeys()].sort((a, b) => a - b);
+  const keysMatch = actualKeys.length === expectedKeys.length && actualKeys.every((k, i) => k === expectedKeys[i]);
+  if (!keysMatch) {
+    throw new WriteConflictError(
+      `compaction verify failed for ${key.segment}.${key.generation}: chunk-key set mismatch (${actualKeys.length} vs ${expectedKeys.length})`
+    );
+  }
+  if (reader.count() !== expectedCount) {
+    throw new WriteConflictError(
+      `compaction verify failed for ${key.segment}.${key.generation}: cardinality ${reader.count()} != ${expectedCount}`
+    );
+  }
+}
+async function purge(warm, ref, pinned) {
+  let purged = 0;
+  let survived = 0;
+  for (const { chunkKey, token } of pinned) {
+    const chunkRef = { namespace: ref.namespace, segment: ref.segment, chunkKey };
+    try {
+      await warm.deleteConditional(chunkRef, token);
+      purged += 1;
+    } catch (err) {
+      if (!isWriteConflictError(err)) throw err;
+      survived += 1;
+    }
+  }
+  return { purged, survived };
+}
+async function purgeAfterCommit(warm, ref, pinned) {
+  return purge(warm, ref, pinned).catch(() => ({ purged: 0, survived: pinned.length }));
+}
+async function deleteGenerationsAbove(cold, ref, g) {
+  for await (const key of cold.list(ref)) {
+    if (key.generation > g) await cold.delete(key);
+  }
+}
+async function releaseLease(deps, ref, leaseToken) {
+  try {
+    await deps.registry.compareAndSwap(ref, leaseToken, {
+      status: "active",
+      leaseOwner: void 0,
+      leaseExpiresAt: void 0
+    });
+  } catch (err) {
+    if (!isWriteConflictError(err)) throw err;
+  }
+}
+function openReader(cold, key, crypto) {
+  const blob = {
+    getRange: (offset, length) => cold.getRange(key, offset, length),
+    getTail: (maxBytes) => cold.getTail(key, maxBytes)
+  };
+  return CrbmReader.open(blob, { crypto });
+}
+function validateShard(shard, totalShards) {
+  if (!Number.isInteger(totalShards) || totalShards < 1) {
+    throw new ValidationError(`totalShards must be a positive integer; got ${totalShards}`);
+  }
+  if (!Number.isInteger(shard) || shard < 0 || shard >= totalShards) {
+    throw new ValidationError(`shard must be an integer in [0, ${totalShards}); got ${shard}`);
+  }
+}
+function shardOf(key, totalShards) {
+  let h = 2166136261;
+  for (let i = 0; i < key.length; i++) {
+    h ^= key.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0) % totalShards;
+}
+async function findCompactable(deps, options = {}) {
+  const threshold = Math.max(1, options.threshold ?? 1);
+  const totalShards = options.totalShards ?? 1;
+  const shard = options.shard ?? 0;
+  validateShard(shard, totalShards);
+  const quarantineThreshold = options.quarantineThreshold ?? DEFAULT_QUARANTINE_THRESHOLD;
+  const cooldownMs = options.quarantineCooldownMs ?? DEFAULT_QUARANTINE_COOLDOWN_MS;
+  const now = deps.clock.now();
+  const known = /* @__PURE__ */ new Map();
+  for await (const rec of deps.registry.list(options.namespace)) {
+    known.set(segmentKey(rec), {
+      ref: { namespace: rec.namespace, segment: rec.segment },
+      currentGen: rec.currentGen,
+      token: rec.token,
+      dirtyHint: rec.dirtyChunkCount,
+      consecutiveFailures: rec.consecutiveFailures ?? 0,
+      updatedAt: rec.updatedAt,
+      lastCompactedAt: rec.lastCompactedAt
+    });
+  }
+  for (const ref of options.candidates ?? []) {
+    const k = segmentKey(ref);
+    if (!known.has(k)) {
+      known.set(k, { ref, currentGen: null, dirtyHint: 0, consecutiveFailures: 0, updatedAt: 0 });
+    }
+  }
+  const out = [];
+  for (const [key, seg] of known) {
+    if (totalShards > 1 && shardOf(key, totalShards) !== shard) continue;
+    if (seg.consecutiveFailures >= quarantineThreshold && now - seg.updatedAt < cooldownMs)
+      continue;
+    let dirty = 0;
+    for await (const row of deps.warm.listChunks(seg.ref)) {
+      dirty += 1;
+    }
+    if (seg.token !== void 0 && dirty !== seg.dirtyHint) {
+      try {
+        await deps.registry.compareAndSwap(seg.ref, seg.token, { dirtyChunkCount: dirty });
+      } catch (err) {
+        if (!isWriteConflictError(err)) throw err;
+      }
+    }
+    if (dirty >= threshold) {
+      out.push({
+        ref: seg.ref,
+        dirtyChunks: dirty,
+        currentGen: seg.currentGen,
+        lastCompactedAt: seg.lastCompactedAt
+      });
+    }
+  }
+  return out;
+}
+async function runCompactionCycle(deps, options) {
+  validateCompactionOptions(options);
+  if (options.maxSegments !== void 0 && (!Number.isInteger(options.maxSegments) || options.maxSegments < 1)) {
+    throw new ValidationError(`maxSegments must be a positive integer; got ${options.maxSegments}`);
+  }
+  const found = await findCompactable(deps, options);
+  found.sort(
+    (a, b) => b.dirtyChunks - a.dirtyChunks || (a.lastCompactedAt ?? 0) - (b.lastCompactedAt ?? 0)
+  );
+  const budget = options.maxSegments;
+  const picked = budget !== void 0 ? found.slice(0, budget) : found;
+  const results = [];
+  let compacted = 0;
+  for (const { ref } of picked) {
+    try {
+      const result = await compactSegment(ref, deps, options);
+      results.push(result);
+      if (result.compacted) {
+        compacted += 1;
+        await gcOrphanGenerations(ref, deps, { keep: options.keep }).catch(() => void 0);
+      }
+    } catch (err) {
+      await bumpFailure(deps, ref).catch(() => void 0);
+      results.push({
+        segment: ref.segment,
+        namespace: ref.namespace,
+        compacted: false,
+        reason: "error",
+        error: err instanceof Error ? err.message : String(err),
+        fromGen: null,
+        dirtyChunks: 0,
+        purged: 0,
+        survived: 0
+      });
+    }
+  }
+  return { candidates: found.length, compacted, deferred: found.length - picked.length, results };
+}
+async function bumpFailure(deps, ref) {
+  const rec = await deps.registry.get(ref);
+  if (rec === null) return;
+  try {
+    await deps.registry.compareAndSwap(ref, rec.token, {
+      consecutiveFailures: (rec.consecutiveFailures ?? 0) + 1
+    });
+  } catch (err) {
+    if (!isWriteConflictError(err)) throw err;
+  }
+}
+
+// src/export/index.ts
+var DEFAULT_NDJSON_BATCH_BYTES = 64 * 1024;
+var errMessage = (err) => err instanceof Error ? err.message : String(err);
+var refKey = (ref) => `${ref.namespace ?? ""} ${ref.segment}`;
+async function runExport(reader, registry, sink, options = {}) {
+  const format = options.format ?? "roaring";
+  const ext = format === "roaring" ? ".roaring" : ".ndjson";
+  const batchCap = options.ndjsonBatchBytes ?? DEFAULT_NDJSON_BATCH_BYTES;
+  const candidates = options.candidates ?? [];
+  const segments = [];
+  const failed = [];
+  let totalIds = 0;
+  const seen = candidates.length > 0 ? /* @__PURE__ */ new Set() : null;
+  const exportRef = async (ref) => {
+    let writer;
+    let count = 0;
+    let bytes = 0;
+    try {
+      validateSegmentRef(ref);
+      const ids = reader.segment(ref.segment, { namespace: ref.namespace }).iterate();
+      writer = await sink.open(ref, ext);
+      if (format === "roaring") {
+        const bm = requireCodec(options.codec, "runExport({ format: 'roaring' })").empty();
+        for await (const id of ids) {
+          bm.add(id);
+          count += 1;
+        }
+        const out = bm.serialize();
+        await writer.write(out);
+        bytes = out.length;
+      } else {
+        let buf = "";
+        for await (const id of ids) {
+          buf += `${id}
+`;
+          count += 1;
+          if (buf.length >= batchCap) {
+            const b = Buffer.from(buf, "utf8");
+            await writer.write(b);
+            bytes += b.length;
+            buf = "";
+          }
+        }
+        if (buf.length > 0) {
+          const b = Buffer.from(buf, "utf8");
+          await writer.write(b);
+          bytes += b.length;
+        }
+      }
+    } catch (err) {
+      if (writer !== void 0) {
+        try {
+          await writer.abort?.();
+        } catch {
+        }
+      }
+      failed.push({ segment: ref.segment, namespace: ref.namespace, error: errMessage(err) });
+      return;
+    }
+    try {
+      await writer.close();
+    } catch (err) {
+      failed.push({ segment: ref.segment, namespace: ref.namespace, error: errMessage(err) });
+      return;
+    }
+    segments.push({ segment: ref.segment, namespace: ref.namespace, count, bytes });
+    totalIds += count;
+  };
+  for await (const rec of registry.list(options.namespace)) {
+    if (rec.status === "destroyed") continue;
+    if (seen !== null) seen.add(refKey(rec));
+    await exportRef({ segment: rec.segment, namespace: rec.namespace });
+  }
+  for (const ref of candidates) {
+    if (options.namespace !== void 0 && ref.namespace !== options.namespace) continue;
+    const key = refKey(ref);
+    if (seen !== null && seen.has(key)) continue;
+    seen?.add(key);
+    await exportRef(ref);
+  }
+  return { version: 1, format, totalSegments: segments.length, totalIds, segments, failed };
+}
+
+// src/core/blob.ts
+var BufferSink = class {
+  chunks = [];
+  length = 0;
+  write(bytes) {
+    this.chunks.push(bytes.slice());
+    this.length += bytes.length;
+    return Promise.resolve();
+  }
+  bytes() {
+    const out = new Uint8Array(this.length);
+    let offset = 0;
+    for (const chunk of this.chunks) {
+      out.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return out;
+  }
+};
+var BufferReader = class {
+  constructor(buffer) {
+    this.buffer = buffer;
+  }
+  buffer;
+  getRange(offset, length) {
+    if (!Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0 || offset + length > this.buffer.length) {
+      throw new ValidationError(
+        `range [${offset}, ${offset + length}) out of bounds for ${this.buffer.length}-byte blob`
+      );
+    }
+    return Promise.resolve(this.buffer.subarray(offset, offset + length));
+  }
+  getTail(maxBytes) {
+    const size = this.buffer.length;
+    const take = Math.min(Math.max(maxBytes, 0), size);
+    return Promise.resolve({ bytes: this.buffer.subarray(size - take), size });
+  }
+};
+
+// src/drivers/_shared/registry.ts
+var STATUSES = ["active", "compacting", "erasing", "destroyed"];
+var MAX_GOVERNANCE_BYTES = 64 * 1024;
+var MAX_WRAPPED_DEKS = 8;
+var MAX_WRAPPED_DEK_BYTES = 4 * 1024;
+function validateGeneration(gen) {
+  if (!Number.isInteger(gen) || gen < 0) {
+    throw new ValidationError(`currentGen must be a non-negative integer; got ${gen}`);
+  }
+}
+function validateCount(count, field = "dirtyChunkCount") {
+  if (!Number.isInteger(count) || count < 0) {
+    throw new ValidationError(`${field} must be a non-negative integer; got ${count}`);
+  }
+}
+function validateTimestamp(ms, field) {
+  if (!Number.isFinite(ms) || ms < 0) {
+    throw new ValidationError(`${field} must be a non-negative finite number; got ${ms}`);
+  }
+}
+function validateStatus(status) {
+  if (!STATUSES.includes(status)) {
+    throw new ValidationError(`status must be one of ${STATUSES.join("/")}; got ${status}`);
+  }
+}
+function validateGovernance(meta, field) {
+  if (meta === void 0) return;
+  let json;
+  try {
+    json = JSON.stringify(meta);
+  } catch {
+    throw new ValidationError(`${field} must be JSON-serializable`);
+  }
+  if (json.length > MAX_GOVERNANCE_BYTES) {
+    throw new ValidationError(`${field} is ${json.length}B, exceeds cap ${MAX_GOVERNANCE_BYTES}B`);
+  }
+}
+function validateWrappedDeks(value, isStored) {
+  if (value === void 0) return;
+  const fail = (msg) => {
+    throw isStored ? new IntegrityError(msg) : new ValidationError(msg);
+  };
+  if (!Array.isArray(value)) fail("wrappedDeks must be an array");
+  const list = value;
+  if (list.length === 0) fail("wrappedDeks must be non-empty when present");
+  if (list.length > MAX_WRAPPED_DEKS)
+    fail(`wrappedDeks has ${list.length} entries, cap ${MAX_WRAPPED_DEKS}`);
+  for (const w of list) {
+    if (w === null || typeof w !== "object") fail("wrappedDeks entry must be an object");
+    const { keyId, wrapped } = w;
+    if (typeof keyId !== "string" || keyId.length === 0)
+      fail("wrappedDeks entry needs a non-empty keyId");
+    if (typeof wrapped !== "string" || wrapped.length === 0)
+      fail("wrappedDeks entry needs a non-empty wrapped blob");
+    if (wrapped.length > MAX_WRAPPED_DEK_BYTES)
+      fail(`wrappedDeks entry is ${wrapped.length}B, cap ${MAX_WRAPPED_DEK_BYTES}B`);
+  }
+}
+function validateNewRegistryRecord(rec) {
+  validateGeneration(rec.currentGen);
+  if (rec.dirtyChunkCount !== void 0) validateCount(rec.dirtyChunkCount);
+  if (rec.status !== void 0) validateStatus(rec.status);
+  validateWrappedDeks(rec.wrappedDeks, false);
+  validateGovernance(rec.retention, "retention");
+  validateGovernance(rec.residency, "residency");
+}
+function validateRegistryPatch(patch) {
+  if (patch.currentGen !== void 0) validateGeneration(patch.currentGen);
+  if (patch.dirtyChunkCount !== void 0) validateCount(patch.dirtyChunkCount);
+  if (patch.consecutiveFailures !== void 0)
+    validateCount(patch.consecutiveFailures, "consecutiveFailures");
+  if (patch.lastCompactedAt !== void 0)
+    validateTimestamp(patch.lastCompactedAt, "lastCompactedAt");
+  if (patch.status !== void 0) validateStatus(patch.status);
+  if ("wrappedDeks" in patch) validateWrappedDeks(patch.wrappedDeks, false);
+  if ("retention" in patch) validateGovernance(patch.retention, "retention");
+  if ("residency" in patch) validateGovernance(patch.residency, "residency");
+}
+var REGISTRY_SCHEMA_VERSION = 1;
+function assertRegistrySchemaVersion(raw, ctx) {
+  if (raw === void 0) return;
+  if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1) {
+    throw new IntegrityError(`registry row has a malformed schemaVersion (${String(raw)}): ${ctx}`);
+  }
+  if (raw > REGISTRY_SCHEMA_VERSION) {
+    throw new UnsupportedError(
+      `registry row schemaVersion ${raw} is newer than this build reads (v${REGISTRY_SCHEMA_VERSION}): ${ctx}`
+    );
+  }
+}
+function serializeRegistryEnvelope(env) {
+  return JSON.stringify({
+    schemaVersion: REGISTRY_SCHEMA_VERSION,
+    deleted: env.deleted,
+    record: env.record
+  });
+}
+function registryCounterOf(record) {
+  if (!/^(0|[1-9]\d*)$/.test(record.token)) {
+    throw new IntegrityError(`registry row token is not a canonical counter: ${record.token}`);
+  }
+  const n = Number(record.token);
+  if (!Number.isSafeInteger(n)) {
+    throw new IntegrityError(`registry row token is out of safe-integer range: ${record.token}`);
+  }
+  return n;
+}
+function parseRegistryEnvelope(text, ctx) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new IntegrityError(`registry row is not valid JSON: ${ctx}`);
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    throw new IntegrityError(`registry row has a malformed envelope: ${ctx}`);
+  }
+  const env = parsed;
+  assertRegistrySchemaVersion(env.schemaVersion, ctx);
+  if (typeof env.deleted !== "boolean" || env.record === null || typeof env.record !== "object") {
+    throw new IntegrityError(`registry row has a malformed envelope: ${ctx}`);
+  }
+  const r = env.record;
+  assertStoredRecordShape(r, ctx);
+  if (typeof r.token !== "string") {
+    throw new IntegrityError(`registry row is missing its token: ${ctx}`);
+  }
+  return { deleted: env.deleted, record: env.record };
+}
+function recordFromNew(ref, rec, now, token) {
+  return {
+    namespace: ref.namespace,
+    segment: ref.segment,
+    currentGen: rec.currentGen,
+    wrappedDeks: rec.wrappedDeks,
+    keyId: rec.keyId,
+    dirtyChunkCount: rec.dirtyChunkCount ?? 0,
+    status: rec.status ?? "active",
+    consecutiveFailures: 0,
+    // daemon health (Phase D); lastCompactedAt stays absent until first compaction
+    retention: rec.retention,
+    residency: rec.residency,
+    createdAt: now,
+    updatedAt: now,
+    token
+  };
+}
+function assertStoredRecordShape(r, ctx) {
+  if (typeof r.segment !== "string" || r.namespace !== void 0 && typeof r.namespace !== "string" || typeof r.currentGen !== "number" || typeof r.dirtyChunkCount !== "number" || typeof r.status !== "string" || typeof r.createdAt !== "number" || typeof r.updatedAt !== "number") {
+    throw new IntegrityError(`registry record is missing required fields: ${ctx}`);
+  }
+  if (!Number.isInteger(r.currentGen) || r.currentGen < 0) {
+    throw new IntegrityError(`registry record has an invalid currentGen (${r.currentGen}): ${ctx}`);
+  }
+  if (!Number.isInteger(r.dirtyChunkCount) || r.dirtyChunkCount < 0) {
+    throw new IntegrityError(`registry record has an invalid dirtyChunkCount: ${ctx}`);
+  }
+  if (!STATUSES.includes(r.status)) {
+    throw new IntegrityError(`registry record has an unknown status (${r.status}): ${ctx}`);
+  }
+  if (r.leaseOwner !== void 0 && typeof r.leaseOwner !== "string") {
+    throw new IntegrityError(`registry record has an invalid leaseOwner: ${ctx}`);
+  }
+  if (r.leaseExpiresAt !== void 0 && typeof r.leaseExpiresAt !== "number") {
+    throw new IntegrityError(`registry record has an invalid leaseExpiresAt: ${ctx}`);
+  }
+  if (r.consecutiveFailures !== void 0 && (!Number.isInteger(r.consecutiveFailures) || r.consecutiveFailures < 0)) {
+    throw new IntegrityError(`registry record has an invalid consecutiveFailures: ${ctx}`);
+  }
+  if (r.lastCompactedAt !== void 0 && (typeof r.lastCompactedAt !== "number" || !Number.isFinite(r.lastCompactedAt) || r.lastCompactedAt < 0)) {
+    throw new IntegrityError(`registry record has an invalid lastCompactedAt: ${ctx}`);
+  }
+  if (r.keyId !== void 0 && typeof r.keyId !== "string") {
+    throw new IntegrityError(`registry record has an invalid keyId: ${ctx}`);
+  }
+  validateWrappedDeks(r.wrappedDeks, true);
+}
+function applyRegistryPatch(prev, patch, now, token) {
+  return {
+    namespace: prev.namespace,
+    segment: prev.segment,
+    currentGen: patch.currentGen ?? prev.currentGen,
+    wrappedDeks: "wrappedDeks" in patch ? patch.wrappedDeks : prev.wrappedDeks,
+    keyId: "keyId" in patch ? patch.keyId : prev.keyId,
+    dirtyChunkCount: patch.dirtyChunkCount ?? prev.dirtyChunkCount,
+    status: patch.status ?? prev.status,
+    leaseOwner: "leaseOwner" in patch ? patch.leaseOwner : prev.leaseOwner,
+    leaseExpiresAt: "leaseExpiresAt" in patch ? patch.leaseExpiresAt : prev.leaseExpiresAt,
+    lastCompactedAt: "lastCompactedAt" in patch ? patch.lastCompactedAt : prev.lastCompactedAt,
+    consecutiveFailures: patch.consecutiveFailures ?? prev.consecutiveFailures ?? 0,
+    retention: "retention" in patch ? patch.retention : prev.retention,
+    residency: "residency" in patch ? patch.residency : prev.residency,
+    createdAt: prev.createdAt,
+    updatedAt: now,
+    token
+  };
+}
+
+// src/drivers/memory.ts
+var MemoryWarmDriver = class {
+  rows = /* @__PURE__ */ new Map();
+  seq = 0;
+  // Monotonic, unique-per-write token → equality-safe and ABA-free.
+  nextToken() {
+    this.seq += 1;
+    return String(this.seq);
+  }
+  // In-memory reads are always strongly consistent — the `WarmReadOptions` hint would be a no-op, so the
+  // structurally-optional param is simply omitted (still satisfies IWarmDriver).
+  async get(ref) {
+    validateChunkRef(ref);
+    const row = this.rows.get(chunkRefKey(ref));
+    return row ? { token: row.token, bytes: row.bytes } : null;
+  }
+  async putConditional(ref, bytes, expected) {
+    validateChunkRef(ref);
+    const key = chunkRefKey(ref);
+    const existing = this.rows.get(key);
+    if (expected === NO_ROW) {
+      if (existing) throw new WriteConflictError(`row already exists for chunk ${ref.chunkKey}`);
+    } else if (!existing || existing.token !== expected) {
+      throw new WriteConflictError(`OCC token mismatch for chunk ${ref.chunkKey}`);
+    }
+    const token = this.nextToken();
+    this.rows.set(key, { token, bytes, chunkKey: ref.chunkKey, prefix: segmentPrefix(ref) });
+    return { token };
+  }
+  async deleteConditional(ref, expected) {
+    validateChunkRef(ref);
+    const key = chunkRefKey(ref);
+    const existing = this.rows.get(key);
+    if (!existing || existing.token !== expected) {
+      throw new WriteConflictError(`OCC token mismatch for chunk ${ref.chunkKey}`);
+    }
+    this.rows.delete(key);
+  }
+  async *listChunks(ref) {
+    validateSegmentRef(ref);
+    const prefix = segmentPrefix(ref);
+    const rows = [...this.rows.values()].filter((r) => r.prefix === prefix);
+    rows.sort((a, b) => a.chunkKey - b.chunkKey);
+    for (const row of rows) {
+      yield { chunkKey: row.chunkKey, token: row.token, bytes: row.bytes };
+    }
+  }
+};
+var MemoryColdChunkSource = class {
+  chunks = /* @__PURE__ */ new Map();
+  async getChunk(ref) {
+    validateChunkRef(ref);
+    return this.chunks.get(chunkRefKey(ref)) ?? null;
+  }
+  async listChunkKeys(ref) {
+    validateSegmentRef(ref);
+    const prefix = segmentPrefix(ref);
+    const keys = [];
+    for (const key of this.chunks.keys()) {
+      if (key.startsWith(prefix)) keys.push(Number(key.slice(prefix.length)));
+    }
+    return keys;
+  }
+  async sizeOf(ref) {
+    validateSegmentRef(ref);
+    const prefix = segmentPrefix(ref);
+    let sizeBytes = 0;
+    let found = false;
+    for (const [key, bytes] of this.chunks) {
+      if (!key.startsWith(prefix)) continue;
+      found = true;
+      sizeBytes += bytes.length;
+    }
+    return found ? { sizeBytes } : null;
+  }
+  /** Test/seed helper — populate immutable Cold bytes for a chunk (no bulk-load path until Phase 3). */
+  seed(ref, bytes) {
+    validateChunkRef(ref);
+    this.chunks.set(chunkRefKey(ref), bytes);
+  }
+};
+var MemoryRegistryDriver = class {
+  rows = /* @__PURE__ */ new Map();
+  now;
+  seq = 0;
+  constructor(options = {}) {
+    this.now = options.now ?? (() => Date.now());
+  }
+  nextToken() {
+    this.seq += 1;
+    return String(this.seq);
+  }
+  capabilities() {
+    return { strongRead: true };
+  }
+  async get(ref) {
+    validateSegmentRef(ref);
+    const row = this.rows.get(segmentKey(ref));
+    return row ? structuredClone(row) : null;
+  }
+  async create(ref, record) {
+    validateSegmentRef(ref);
+    validateNewRegistryRecord(record);
+    const key = segmentKey(ref);
+    if (this.rows.has(key)) {
+      throw new WriteConflictError(`registry row already exists for segment ${ref.segment}`);
+    }
+    const token = this.nextToken();
+    this.rows.set(key, structuredClone(recordFromNew(ref, record, this.now(), token)));
+    return { token };
+  }
+  async compareAndSwap(ref, expected, patch) {
+    validateSegmentRef(ref);
+    validateRegistryPatch(patch);
+    const key = segmentKey(ref);
+    const existing = this.rows.get(key);
+    if (!existing || existing.token !== expected) {
+      throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
+    }
+    const token = this.nextToken();
+    this.rows.set(key, structuredClone(applyRegistryPatch(existing, patch, this.now(), token)));
+    return { token };
+  }
+  async *list(namespace) {
+    for (const row of this.rows.values()) {
+      if (namespace === void 0 || row.namespace === namespace) yield structuredClone(row);
+    }
+  }
+  async delete(ref) {
+    validateSegmentRef(ref);
+    this.rows.delete(segmentKey(ref));
+  }
+};
+var MemoryColdDriver = class {
+  objects = /* @__PURE__ */ new Map();
+  capabilities() {
+    return { rangeRead: true, maxObjectBytes: Number.MAX_SAFE_INTEGER, conditionalPut: true };
+  }
+  async putImmutable(key, write) {
+    const k = genObjectKey(key);
+    const sink = new BufferSink();
+    await write(sink);
+    const body = sink.bytes();
+    if (this.objects.has(k)) {
+      throw new WriteConflictError(
+        `generation already exists (write-once): ${key.segment}.${key.generation}`
+      );
+    }
+    this.objects.set(k, body);
+    return { size: body.length, sha256: crypto.createHash("sha256").update(body).digest("hex") };
+  }
+  async getRange(key, offset, length) {
+    if (!Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0) {
+      throw new ValidationError(`invalid range offset=${offset} length=${length}`);
+    }
+    const body = this.require(key);
+    if (offset + length > body.length) {
+      throw new ValidationError(
+        `range [${offset}, ${offset + length}) out of bounds for ${body.length}B`
+      );
+    }
+    return body.slice(offset, offset + length);
+  }
+  async getTail(key, maxBytes) {
+    const body = this.require(key);
+    const take = Math.min(Math.max(maxBytes, 0), body.length);
+    return { bytes: body.slice(body.length - take), size: body.length };
+  }
+  async delete(key) {
+    this.objects.delete(genObjectKey(key));
+  }
+  async *list(ref) {
+    validateSegmentRef(ref);
+    const prefix = `${segmentKey(ref)} `;
+    for (const k of this.objects.keys()) {
+      if (k.startsWith(prefix)) {
+        yield {
+          namespace: ref.namespace,
+          segment: ref.segment,
+          generation: Number(k.slice(prefix.length))
+        };
+      }
+    }
+  }
+  require(key) {
+    const body = this.objects.get(genObjectKey(key));
+    if (body === void 0) {
+      throw new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);
+    }
+    return body;
+  }
+};
+function genObjectKey(key) {
+  validateSegmentRef(key);
+  if (!Number.isInteger(key.generation) || key.generation < 0) {
+    throw new ValidationError(`generation must be a non-negative integer; got ${key.generation}`);
+  }
+  return `${segmentKey(key)} ${key.generation}`;
+}
+
+// src/drivers/_shared/keys.ts
+var DEFAULT_NAMESPACE = "_default";
+function namespacePart(namespace) {
+  return namespace ?? DEFAULT_NAMESPACE;
+}
+
+// src/drivers/localfs/paths.ts
+function segmentsDir(root, ref) {
+  validateSegmentRef(ref);
+  return path.join(root, namespacePart(ref.namespace), "segments");
+}
+function coldObjectPath(root, key) {
+  validateSegmentRef(key);
+  if (!Number.isInteger(key.generation) || key.generation < 0) {
+    throw new ValidationError(`generation must be a non-negative integer; got ${key.generation}`);
+  }
+  return path.join(segmentsDir(root, key), `${key.segment}.${key.generation}.crbm`);
+}
+function parseGeneration(segment, filename) {
+  const prefix = `${segment}.`;
+  const suffix = ".crbm";
+  if (!filename.startsWith(prefix) || !filename.endsWith(suffix)) return null;
+  const middle = filename.slice(prefix.length, filename.length - suffix.length);
+  if (!/^(0|[1-9]\d*)$/.test(middle)) return null;
+  const gen = Number(middle);
+  return Number.isSafeInteger(gen) ? gen : null;
+}
+var WARM_ROW_SUFFIX = ".row";
+var CHUNK_KEY_MAX2 = 65535;
+function warmSegmentDir(root, ref) {
+  validateSegmentRef(ref);
+  return path.join(root, namespacePart(ref.namespace), "warm", ref.segment);
+}
+function warmRowPath(root, ref) {
+  validateChunkRef(ref);
+  return path.join(warmSegmentDir(root, ref), `${ref.chunkKey}${WARM_ROW_SUFFIX}`);
+}
+var REGISTRY_SUFFIX = ".reg";
+function registryDir(root, namespace) {
+  return path.join(root, namespacePart(namespace), "registry");
+}
+function registryRowPath(root, ref) {
+  validateSegmentRef(ref);
+  return path.join(registryDir(root, ref.namespace), `${ref.segment}${REGISTRY_SUFFIX}`);
+}
+function parseRegistryRow(filename) {
+  if (!filename.endsWith(REGISTRY_SUFFIX)) return null;
+  const segment = filename.slice(0, filename.length - REGISTRY_SUFFIX.length);
+  try {
+    validateSegmentRef({ segment });
+  } catch {
+    return null;
+  }
+  return segment;
+}
+function parseChunkRow(filename) {
+  if (!filename.endsWith(WARM_ROW_SUFFIX)) return null;
+  const middle = filename.slice(0, filename.length - WARM_ROW_SUFFIX.length);
+  if (!/^(0|[1-9]\d*)$/.test(middle)) return null;
+  const chunkKey = Number(middle);
+  return chunkKey <= CHUNK_KEY_MAX2 ? chunkKey : null;
+}
+var isCode = (err, code) => err instanceof Error && err.code === code;
+var TRANSIENT_FS_CODES = /* @__PURE__ */ new Set(["EBUSY", "EAGAIN", "EMFILE", "ENFILE", "ETIMEDOUT"]);
+var isFsTransient = (err) => err instanceof Error && TRANSIENT_FS_CODES.has(err.code ?? "");
+var mapFsError = (err) => isFsTransient(err) ? new TransientError(`transient filesystem fault: ${err.code}`, { cause: err }) : err;
+var O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+async function fsyncDir(dir) {
+  try {
+    const handle = await promises.open(dir, "r");
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  } catch {
+  }
+}
+
+// src/drivers/localfs/cold.ts
+var LocalFsColdDriver = class {
+  constructor(root) {
+    this.root = root;
+  }
+  root;
+  capabilities() {
+    return { rangeRead: true, maxObjectBytes: Number.MAX_SAFE_INTEGER, conditionalPut: false };
+  }
+  async putImmutable(key, write) {
+    const finalPath = coldObjectPath(this.root, key);
+    await promises.mkdir(path.dirname(finalPath), { recursive: true });
+    const tmpPath = `${finalPath}.${crypto.randomUUID()}.tmp`;
+    const handle = await promises.open(tmpPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | O_NOFOLLOW);
+    const hash = crypto.createHash("sha256");
+    let size = 0;
+    const sink = {
+      async write(bytes) {
+        await handle.write(bytes);
+        hash.update(bytes);
+        size += bytes.length;
+      }
+    };
+    try {
+      await write(sink);
+      await handle.sync();
+    } catch (err) {
+      await handle.close().catch(() => {
+      });
+      await promises.unlink(tmpPath).catch(() => {
+      });
+      throw mapFsError(err);
+    }
+    await handle.close();
+    try {
+      await promises.link(tmpPath, finalPath);
+    } catch (err) {
+      await promises.unlink(tmpPath).catch(() => {
+      });
+      if (isCode(err, "EEXIST")) {
+        throw new WriteConflictError(
+          `generation already exists (write-once): ${key.segment}.${key.generation}`
+        );
+      }
+      throw mapFsError(err);
+    }
+    await promises.unlink(tmpPath).catch(() => {
+    });
+    await fsyncDir(path.dirname(finalPath));
+    return { size, sha256: hash.digest("hex") };
+  }
+  async getRange(key, offset, length) {
+    if (!Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0) {
+      throw new ValidationError(`invalid range offset=${offset} length=${length}`);
+    }
+    const handle = await this.openRead(key);
+    try {
+      const { size } = await handle.stat();
+      if (offset + length > size) {
+        throw new ValidationError(
+          `range [${offset}, ${offset + length}) out of bounds for ${size}B`
+        );
+      }
+      const buf = Buffer.alloc(length);
+      if (length > 0) await handle.read(buf, 0, length, offset);
+      return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    } finally {
+      await handle.close();
+    }
+  }
+  async getTail(key, maxBytes) {
+    const handle = await this.openRead(key);
+    try {
+      const { size } = await handle.stat();
+      const take = Math.min(Math.max(maxBytes, 0), size);
+      const buf = Buffer.alloc(take);
+      if (take > 0) await handle.read(buf, 0, take, size - take);
+      return { bytes: new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength), size };
+    } finally {
+      await handle.close();
+    }
+  }
+  async delete(key) {
+    await promises.unlink(coldObjectPath(this.root, key)).catch((err) => {
+      if (!isCode(err, "ENOENT")) throw mapFsError(err);
+    });
+  }
+  async *list(ref) {
+    const dir = segmentsDir(this.root, ref);
+    let names;
+    try {
+      names = await promises.readdir(dir);
+    } catch (err) {
+      if (isCode(err, "ENOENT")) return;
+      throw mapFsError(err);
+    }
+    for (const name of names) {
+      const generation = parseGeneration(ref.segment, name);
+      if (generation !== null) {
+        yield { namespace: ref.namespace, segment: ref.segment, generation };
+      }
+    }
+  }
+  async openRead(key) {
+    try {
+      return await promises.open(coldObjectPath(this.root, key), fs.constants.O_RDONLY | O_NOFOLLOW);
+    } catch (err) {
+      if (isCode(err, "ENOENT")) {
+        throw new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);
+      }
+      if (isCode(err, "ELOOP")) {
+        throw new NotFoundError(
+          `generation path is a symlink, refusing: ${key.segment}.${key.generation}`
+        );
+      }
+      throw mapFsError(err);
+    }
+  }
+};
+var HEADER_BYTES2 = 5;
+var COUNTER_MAX = 4294967295;
+var DEFAULT_MAX_ROW_BYTES = 64 * 1024 * 1024;
+var LocalFsWarmDriver = class {
+  constructor(root, maxRowBytes = DEFAULT_MAX_ROW_BYTES) {
+    this.root = root;
+    this.maxRowBytes = maxRowBytes;
+  }
+  root;
+  maxRowBytes;
+  /** Per-row promise chain — serializes read-modify-write so an in-process CAS never loses an update. */
+  chain = /* @__PURE__ */ new Map();
+  // Methods are `async` so boundary-validation throws (warmRowPath) surface as rejections, not sync throws.
+  // LocalFs reads are always strongly consistent (single filesystem) — the `WarmReadOptions` hint would be a
+  // no-op, so the structurally-optional param is simply omitted (still satisfies IWarmDriver).
+  async get(ref) {
+    const row = await this.readRow(warmRowPath(this.root, ref));
+    return row && !row.deleted ? { token: String(row.counter), bytes: row.bytes } : null;
+  }
+  async putConditional(ref, bytes, expected) {
+    const path = warmRowPath(this.root, ref);
+    return this.withRowLock(path, async () => {
+      const current = await this.readRow(path);
+      const live = current !== null && !current.deleted;
+      if (expected === NO_ROW) {
+        if (live) throw new WriteConflictError(`row already exists: chunk ${ref.chunkKey}`);
+        const counter = current ? current.counter + 1 : 0;
+        await this.writeRow(path, counter, false, bytes);
+        return { token: String(counter) };
+      }
+      if (!live || String(current.counter) !== expected) {
+        throw new WriteConflictError(`OCC conflict on chunk ${ref.chunkKey}`);
+      }
+      await this.writeRow(path, current.counter + 1, false, bytes);
+      return { token: String(current.counter + 1) };
+    });
+  }
+  async deleteConditional(ref, expected) {
+    const path = warmRowPath(this.root, ref);
+    return this.withRowLock(path, async () => {
+      const current = await this.readRow(path);
+      if (current === null || current.deleted || String(current.counter) !== expected) {
+        throw new WriteConflictError(`OCC conflict on delete of chunk ${ref.chunkKey}`);
+      }
+      await this.writeRow(path, current.counter + 1, true, new Uint8Array());
+    });
+  }
+  async *listChunks(ref) {
+    const dir = warmSegmentDir(this.root, ref);
+    let names;
+    try {
+      names = await promises.readdir(dir);
+    } catch (err) {
+      if (isCode(err, "ENOENT")) return;
+      throw mapFsError(err);
+    }
+    const keys = names.map((n) => parseChunkRow(n)).filter((k) => k !== null).sort((a, b) => a - b);
+    for (const chunkKey of keys) {
+      const row = await this.readRow(warmRowPath(this.root, { ...ref, chunkKey }));
+      if (row && !row.deleted) yield { chunkKey, token: String(row.counter), bytes: row.bytes };
+    }
+  }
+  async readRow(path) {
+    let handle;
+    try {
+      handle = await promises.open(path, fs.constants.O_RDONLY | O_NOFOLLOW);
+    } catch (err) {
+      if (isCode(err, "ENOENT") || isCode(err, "ELOOP")) return null;
+      throw mapFsError(err);
+    }
+    try {
+      const { size } = await handle.stat();
+      if (size > this.maxRowBytes) {
+        throw new IntegrityError(`warm row ${size}B exceeds cap ${this.maxRowBytes}B`);
+      }
+      if (size < HEADER_BYTES2) {
+        throw new IntegrityError(`warm row truncated: ${size}B < ${HEADER_BYTES2}B header`);
+      }
+      const buf = await handle.readFile();
+      const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+      return {
+        counter: view.getUint32(0, true),
+        deleted: buf[4] !== 0,
+        bytes: new Uint8Array(buf.subarray(HEADER_BYTES2))
+      };
+    } finally {
+      await handle.close();
+    }
+  }
+  async writeRow(path$1, counter, deleted, bytes) {
+    if (counter > COUNTER_MAX) {
+      throw new IntegrityError(`warm row counter overflow on ${path$1}`);
+    }
+    await promises.mkdir(path.dirname(path$1), { recursive: true });
+    const out = new Uint8Array(HEADER_BYTES2 + bytes.length);
+    new DataView(out.buffer).setUint32(0, counter, true);
+    out[4] = deleted ? 1 : 0;
+    out.set(bytes, HEADER_BYTES2);
+    const tmp = `${path$1}.${crypto.randomUUID()}.tmp`;
+    let handle;
+    try {
+      handle = await promises.open(tmp, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | O_NOFOLLOW);
+    } catch (err) {
+      throw mapFsError(err);
+    }
+    try {
+      await handle.write(out);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await promises.rename(tmp, path$1).catch(async (err) => {
+      await promises.unlink(tmp).catch(() => {
+      });
+      throw mapFsError(err);
+    });
+    await fsyncDir(path.dirname(path$1));
+  }
+  /**
+   * Serialize callbacks for a given row path so read-modify-write is atomic in-process. `prev.then(fn,
+   * fn)` runs `fn` regardless of whether the predecessor fulfilled or rejected — a conflict on one
+   * writer must not stall the row's chain.
+   */
+  withRowLock(key, fn) {
+    const prev = this.chain.get(key) ?? Promise.resolve();
+    const result = prev.then(fn, fn);
+    const tail = result.then(
+      () => void 0,
+      () => void 0
+    );
+    this.chain.set(key, tail);
+    void tail.then(() => {
+      if (this.chain.get(key) === tail) this.chain.delete(key);
+    });
+    return result;
+  }
+};
+var DEFAULT_MAX_ROW_BYTES2 = 1 * 1024 * 1024;
+var LocalFsRegistryDriver = class {
+  constructor(root, options = {}) {
+    this.root = root;
+    this.now = options.now ?? (() => Date.now());
+  }
+  root;
+  /** Per-row promise chain — serializes read-modify-write so an in-process CAS never loses an update. */
+  chain = /* @__PURE__ */ new Map();
+  now;
+  capabilities() {
+    return { strongRead: true };
+  }
+  async get(ref) {
+    const env = await this.readRow(registryRowPath(this.root, ref));
+    return env && !env.deleted ? env.record : null;
+  }
+  async create(ref, record) {
+    validateNewRegistryRecord(record);
+    const path = registryRowPath(this.root, ref);
+    return this.withRowLock(path, async () => {
+      const current = await this.readRow(path);
+      if (current !== null && !current.deleted) {
+        throw new WriteConflictError(`registry row already exists for segment ${ref.segment}`);
+      }
+      const counter = current ? registryCounterOf(current.record) + 1 : 0;
+      const token = String(counter);
+      await this.writeRow(path, false, recordFromNew(ref, record, this.now(), token));
+      return { token };
+    });
+  }
+  async compareAndSwap(ref, expected, patch) {
+    validateRegistryPatch(patch);
+    const path = registryRowPath(this.root, ref);
+    return this.withRowLock(path, async () => {
+      const current = await this.readRow(path);
+      if (current === null || current.deleted || current.record.token !== expected) {
+        throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
+      }
+      const token = String(registryCounterOf(current.record) + 1);
+      await this.writeRow(
+        path,
+        false,
+        applyRegistryPatch(current.record, patch, this.now(), token)
+      );
+      return { token };
+    });
+  }
+  async *list(namespace) {
+    for (const ns of await this.namespaceDirs(namespace)) {
+      const dir = registryDir(this.root, ns);
+      let names;
+      try {
+        names = await promises.readdir(dir);
+      } catch (err) {
+        if (isCode(err, "ENOENT")) continue;
+        throw mapFsError(err);
+      }
+      for (const name of names) {
+        const segment = parseRegistryRow(name);
+        if (segment === null) continue;
+        const env = await this.readRow(registryRowPath(this.root, { namespace: ns, segment }));
+        if (env && !env.deleted) yield env.record;
+      }
+    }
+  }
+  async delete(ref) {
+    const path = registryRowPath(this.root, ref);
+    return this.withRowLock(path, async () => {
+      const current = await this.readRow(path);
+      if (current === null || current.deleted) return;
+      const token = String(registryCounterOf(current.record) + 1);
+      await this.writeRow(path, true, { ...current.record, token, updatedAt: this.now() });
+    });
+  }
+  /** Namespaces to scan: just the one requested, or every namespace dir under the root. */
+  async namespaceDirs(namespace) {
+    if (namespace !== void 0) return [namespace];
+    let entries;
+    try {
+      entries = await promises.readdir(this.root);
+    } catch (err) {
+      if (isCode(err, "ENOENT")) return [];
+      throw mapFsError(err);
+    }
+    return entries.map((e) => e === "_default" ? void 0 : e);
+  }
+  async readRow(path) {
+    let handle;
+    try {
+      handle = await promises.open(path, fs.constants.O_RDONLY | O_NOFOLLOW);
+    } catch (err) {
+      if (isCode(err, "ENOENT") || isCode(err, "ELOOP")) return null;
+      throw mapFsError(err);
+    }
+    try {
+      const { size } = await handle.stat();
+      if (size > DEFAULT_MAX_ROW_BYTES2) {
+        throw new IntegrityError(`registry row ${size}B exceeds cap ${DEFAULT_MAX_ROW_BYTES2}B`);
+      }
+      const text = (await handle.readFile()).toString("utf8");
+      return parseRegistryEnvelope(text, path);
+    } finally {
+      await handle.close();
+    }
+  }
+  async writeRow(path$1, deleted, record) {
+    await promises.mkdir(path.dirname(path$1), { recursive: true });
+    const out = Buffer.from(serializeRegistryEnvelope({ deleted, record }), "utf8");
+    if (out.length > DEFAULT_MAX_ROW_BYTES2) {
+      throw new ValidationError(
+        `registry row ${out.length}B exceeds cap ${DEFAULT_MAX_ROW_BYTES2}B`
+      );
+    }
+    const tmp = `${path$1}.${crypto.randomUUID()}.tmp`;
+    let handle;
+    try {
+      handle = await promises.open(tmp, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | O_NOFOLLOW);
+    } catch (err) {
+      throw mapFsError(err);
+    }
+    try {
+      await handle.write(out);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await promises.rename(tmp, path$1).catch(async (err) => {
+      await promises.unlink(tmp).catch(() => {
+      });
+      throw mapFsError(err);
+    });
+    await fsyncDir(path.dirname(path$1));
+  }
+  /** Serialize callbacks for a row path so read-modify-write is atomic in-process (mirrors the Warm tier). */
+  withRowLock(key, fn) {
+    const prev = this.chain.get(key) ?? Promise.resolve();
+    const result = prev.then(fn, fn);
+    const tail = result.then(
+      () => void 0,
+      () => void 0
+    );
+    this.chain.set(key, tail);
+    void tail.then(() => {
+      if (this.chain.get(key) === tail) this.chain.delete(key);
+    });
+    return result;
+  }
+};
+var KEY_BYTES = 32;
+var NONCE_BYTES = 12;
+var TAG_BYTES = 16;
+var NodeAead = class {
+  key;
+  constructor(key) {
+    if (key.length !== KEY_BYTES)
+      throw new ValidationError(`AEAD key must be ${KEY_BYTES} bytes, got ${key.length}`);
+    this.key = Buffer.from(key);
+  }
+  seal(plaintext, aad) {
+    const nonce = crypto.randomBytes(NONCE_BYTES);
+    const cipher = crypto.createCipheriv("aes-256-gcm", this.key, nonce);
+    cipher.setAAD(aad);
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return { nonce, ciphertext, tag: cipher.getAuthTag() };
+  }
+  open(sealed, aad) {
+    if (sealed.nonce.length !== NONCE_BYTES || sealed.tag.length !== TAG_BYTES)
+      throw new IntegrityError("AEAD nonce/tag have the wrong length");
+    const decipher = crypto.createDecipheriv("aes-256-gcm", this.key, sealed.nonce);
+    decipher.setAAD(aad);
+    decipher.setAuthTag(Buffer.from(sealed.tag));
+    try {
+      return Buffer.concat([decipher.update(sealed.ciphertext), decipher.final()]);
+    } catch {
+      throw new IntegrityError(
+        "AEAD authentication failed (wrong key, tampered data, or wrong context)"
+      );
+    }
+  }
+};
+function wrapKey(dek, kek, keyId) {
+  const sealed = new NodeAead(kek).seal(dek, new TextEncoder().encode(keyId));
+  return Buffer.concat([sealed.nonce, sealed.ciphertext, sealed.tag]).toString("base64");
+}
+function unwrapKey(wrapped, kek, keyId) {
+  const blob = Buffer.from(wrapped, "base64");
+  if (blob.length < NONCE_BYTES + TAG_BYTES)
+    throw new IntegrityError("wrapped DEK is too short to be valid");
+  const nonce = blob.subarray(0, NONCE_BYTES);
+  const tag = blob.subarray(blob.length - TAG_BYTES);
+  const ciphertext = blob.subarray(NONCE_BYTES, blob.length - TAG_BYTES);
+  return new NodeAead(kek).open({ nonce, ciphertext, tag }, new TextEncoder().encode(keyId));
+}
+var InProcessKeystore = class {
+  keys;
+  activeKeyId;
+  recoveryKeyId;
+  constructor(options) {
+    const entries = Object.entries(options.keys);
+    if (entries.length === 0) throw new ValidationError("keystore needs at least one KEK");
+    for (const [id, k] of entries) {
+      if (k.length !== KEY_BYTES)
+        throw new ValidationError(`KEK "${id}" must be ${KEY_BYTES} bytes, got ${k.length}`);
+    }
+    if (!(options.activeKeyId in options.keys))
+      throw new ValidationError(`activeKeyId "${options.activeKeyId}" is not in keys`);
+    if (options.recoveryKeyId !== void 0 && !(options.recoveryKeyId in options.keys))
+      throw new ValidationError(`recoveryKeyId "${options.recoveryKeyId}" is not in keys`);
+    this.keys = new Map(entries.map(([id, k]) => [id, Buffer.from(k)]));
+    this.activeKeyId = options.activeKeyId;
+    this.recoveryKeyId = options.recoveryKeyId === options.activeKeyId ? void 0 : options.recoveryKeyId;
+  }
+  // async to satisfy the IKeystore seam (a KMS adapter awaits a network call here); the in-process path is
+  // synchronous, but staying async keeps unwrap failures as rejections, matching a remote keystore.
+  async createDek() {
+    const dek = crypto.randomBytes(KEY_BYTES);
+    const ids = this.recoveryKeyId ? [this.activeKeyId, this.recoveryKeyId] : [this.activeKeyId];
+    const wrapped = ids.map((keyId) => ({
+      keyId,
+      wrapped: wrapKey(dek, this.keys.get(keyId), keyId)
+    }));
+    return { wrapped, aead: new NodeAead(dek) };
+  }
+  // async for the same reason as createDek — a synchronous unwrap failure surfaces as a promise rejection.
+  async openDek(wrapped) {
+    let anyKekHeld = false;
+    let lastUnwrapError;
+    for (const w of wrapped) {
+      const kek = this.keys.get(w.keyId);
+      if (kek === void 0) continue;
+      anyKekHeld = true;
+      try {
+        return new NodeAead(unwrapKey(w.wrapped, kek, w.keyId));
+      } catch (err) {
+        lastUnwrapError = err;
+      }
+    }
+    if (anyKekHeld) throw lastUnwrapError;
+    const have = [...this.keys.keys()].join(", ") || "(none)";
+    const need = wrapped.map((w) => w.keyId).join(", ") || "(none)";
+    throw new KeyUnavailableError(
+      `no held KEK can unwrap this DEK \u2014 have [${have}], wrappings reference [${need}]. Restore the missing KEK (or its recovery KEK), or rebuild the segment from source.`
+    );
+  }
+};
+
+// src/core/erasure.ts
+var MAX_CAS_ATTEMPTS = 8;
+var MAX_WARM_PASSES = 4;
+async function destroySegment(ref, deps, options) {
+  if (options.confirmSegment !== ref.segment) {
+    throw new ValidationError(
+      `destroySegment: confirmSegment must equal the segment name "${ref.segment}" (guard against accidental crypto-shred)`
+    );
+  }
+  const result = await shredSegment(ref, deps, options.allowCleartext ?? false);
+  if (result.cryptoShredded) {
+    safeAudit(options.audit ?? NOOP_AUDIT).onEvent({
+      kind: "segment.erase",
+      namespace: ref.namespace,
+      segment: ref.segment
+    });
+  }
+  return result;
+}
+async function eraseNamespace(namespace, deps, options) {
+  if (typeof namespace !== "string" || namespace.length === 0) {
+    throw new ValidationError("eraseNamespace: namespace must be a non-empty string");
+  }
+  if (options.confirmNamespace !== namespace) {
+    throw new ValidationError(
+      `eraseNamespace: confirmNamespace must equal the namespace "${namespace}" (guard against accidental erasure)`
+    );
+  }
+  const refs = [];
+  for await (const rec of deps.registry.list(namespace)) {
+    refs.push({ namespace: rec.namespace, segment: rec.segment });
+  }
+  const audit = safeAudit(options.audit ?? NOOP_AUDIT);
+  const destroyed = [];
+  let segmentsShredded = 0;
+  for (const ref of refs) {
+    const result = await shredSegment(ref, deps, options.allowCleartext ?? false);
+    destroyed.push(result);
+    if (result.cryptoShredded) {
+      segmentsShredded += 1;
+      audit.onEvent({ kind: "segment.erase", namespace: ref.namespace, segment: ref.segment });
+    }
+  }
+  audit.onEvent({ kind: "namespace.erase", namespace, segmentsShredded });
+  return { destroyed };
+}
+async function shredSegment(ref, deps, allowCleartext) {
+  const base = { segment: ref.segment, namespace: ref.namespace };
+  for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
+    const record = await deps.registry.get(ref);
+    if (record === null) {
+      const warmRowsDeleted2 = await eraseWarm(deps.warm, ref);
+      return {
+        ...base,
+        destroyed: false,
+        cryptoShredded: false,
+        reason: "absent",
+        warmRowsDeleted: warmRowsDeleted2
+      };
+    }
+    if (record.status === "destroyed") {
+      const warmRowsDeleted2 = await eraseWarm(deps.warm, ref);
+      return {
+        ...base,
+        destroyed: true,
+        cryptoShredded: false,
+        reason: "already",
+        warmRowsDeleted: warmRowsDeleted2
+      };
+    }
+    const encrypted = record.wrappedDeks !== void 0 && record.wrappedDeks.length > 0;
+    if (!encrypted && !allowCleartext) {
+      return {
+        ...base,
+        destroyed: false,
+        cryptoShredded: false,
+        reason: "cleartext",
+        warmRowsDeleted: 0
+      };
+    }
+    const warmRowsDeleted = await eraseWarm(deps.warm, ref);
+    try {
+      await deps.registry.compareAndSwap(ref, record.token, {
+        status: "destroyed",
+        wrappedDeks: void 0,
+        // ← the crypto-shred: the only copy of the DEK wrappings is gone
+        keyId: void 0,
+        leaseOwner: void 0,
+        leaseExpiresAt: void 0
+      });
+      return { ...base, destroyed: true, cryptoShredded: encrypted, warmRowsDeleted };
+    } catch (err) {
+      if (!isWriteConflictError(err)) throw err;
+    }
+  }
+  throw new WriteConflictError(`destroySegment: contention shredding "${ref.segment}" \u2014 retry`);
+}
+async function eraseWarm(warm, ref) {
+  let deleted = 0;
+  for (let pass = 0; pass < MAX_WARM_PASSES; pass++) {
+    const rows = [];
+    for await (const row of warm.listChunks(ref))
+      rows.push({ chunkKey: row.chunkKey, token: row.token });
+    if (rows.length === 0) break;
+    let conflicts = 0;
+    for (const { chunkKey, token } of rows) {
+      const chunkRef = { namespace: ref.namespace, segment: ref.segment, chunkKey };
+      try {
+        await warm.deleteConditional(chunkRef, token);
+        deleted += 1;
+      } catch (err) {
+        if (!isWriteConflictError(err)) throw err;
+        conflicts += 1;
+      }
+    }
+    if (conflicts === 0) break;
+  }
+  return deleted;
+}
+
+// src/core/consistency.ts
+var DEFAULT_CHECK_CONCURRENCY = 8;
+async function listGenerations(cold, ref) {
+  const present = /* @__PURE__ */ new Set();
+  for await (const key of cold.list(ref)) present.add(key.generation);
+  return present;
+}
+async function runConsistencyCheck(deps, options = {}) {
+  const concurrency = options.concurrency ?? DEFAULT_CHECK_CONCURRENCY;
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw new ValidationError(`concurrency must be a positive integer; got ${concurrency}`);
+  }
+  const recs = [];
+  for await (const rec of deps.registry.list(options.namespace)) recs.push(rec);
+  const results = await mapWithConcurrency(recs, concurrency, async (rec) => {
+    if (rec.status === "destroyed") return { kind: "ok" };
+    const ref = { segment: rec.segment, namespace: rec.namespace };
+    try {
+      const live = await deps.registry.get(ref);
+      if (!live || live.status === "destroyed") return { kind: "ok" };
+      const present = await listGenerations(deps.cold, ref);
+      if (present.has(live.currentGen)) return { kind: "ok" };
+      return {
+        kind: "issue",
+        issue: {
+          segment: rec.segment,
+          namespace: rec.namespace,
+          currentGen: live.currentGen,
+          issue: "missing-cold-generation"
+        }
+      };
+    } catch (error) {
+      return {
+        kind: "error",
+        error: {
+          segment: rec.segment,
+          namespace: rec.namespace,
+          error: error instanceof Error ? error.message : String(error)
+        }
+      };
+    }
+  });
+  const inconsistent = [];
+  const errored = [];
+  for (const r of results) {
+    if (r.kind === "issue") inconsistent.push(r.issue);
+    else if (r.kind === "error") errored.push(r.error);
+  }
+  return { checked: recs.length, inconsistent, errored };
+}
+
+// src/drivers/retry/retrying-drivers.ts
+function toRetry(opts) {
+  return {
+    policy: opts.policy ?? DEFAULT_RETRY_POLICY,
+    deps: {
+      clock: opts.clock,
+      rng: opts.rng,
+      isRetryable: opts.isRetryable ?? isTransient,
+      onRetry: opts.onRetry
+    }
+  };
+}
+var RetryingWarmDriver = class {
+  inner;
+  policy;
+  deps;
+  constructor(inner, opts) {
+    this.inner = inner;
+    const r = toRetry(opts);
+    this.policy = r.policy;
+    this.deps = r.deps;
+  }
+  get(ref, opts) {
+    return withRetry(() => this.inner.get(ref, opts), this.policy, this.deps);
+  }
+  putConditional(ref, bytes, expected) {
+    return withRetry(() => this.inner.putConditional(ref, bytes, expected), this.policy, this.deps);
+  }
+  deleteConditional(ref, expected) {
+    return withRetry(() => this.inner.deleteConditional(ref, expected), this.policy, this.deps);
+  }
+  async *listChunks(ref, opts) {
+    const rows = await withRetry(
+      async () => {
+        const out = [];
+        for await (const row of this.inner.listChunks(ref, opts)) out.push(row);
+        return out;
+      },
+      this.policy,
+      this.deps
+    );
+    yield* rows;
+  }
+};
+var RetryingColdChunkSource = class {
+  inner;
+  policy;
+  deps;
+  /** Present only when the inner source supports it — so capability detection stays honest. */
+  sizeOf;
+  cardinalities;
+  currentGeneration;
+  constructor(inner, opts) {
+    this.inner = inner;
+    const r = toRetry(opts);
+    this.policy = r.policy;
+    this.deps = r.deps;
+    const innerSizeOf = inner.sizeOf;
+    if (innerSizeOf) {
+      this.sizeOf = (ref) => withRetry(() => innerSizeOf.call(inner, ref), this.policy, this.deps);
+    }
+    const innerCardinalities = inner.cardinalities;
+    if (innerCardinalities) {
+      this.cardinalities = (ref) => withRetry(() => innerCardinalities.call(inner, ref), this.policy, this.deps);
+    }
+    const innerCurrentGeneration = inner.currentGeneration;
+    if (innerCurrentGeneration) {
+      this.currentGeneration = (ref) => withRetry(() => innerCurrentGeneration.call(inner, ref), this.policy, this.deps);
+    }
+  }
+  getChunk(ref) {
+    return withRetry(() => this.inner.getChunk(ref), this.policy, this.deps);
+  }
+  listChunkKeys(ref) {
+    return withRetry(() => this.inner.listChunkKeys(ref), this.policy, this.deps);
+  }
+};
+var RetryingColdDriver = class {
+  inner;
+  policy;
+  deps;
+  constructor(inner, opts) {
+    this.inner = inner;
+    const r = toRetry(opts);
+    this.policy = r.policy;
+    this.deps = r.deps;
+  }
+  capabilities() {
+    return this.inner.capabilities();
+  }
+  putImmutable(key, write) {
+    return withRetry(() => this.inner.putImmutable(key, write), this.policy, this.deps);
+  }
+  getRange(key, offset, length) {
+    return withRetry(() => this.inner.getRange(key, offset, length), this.policy, this.deps);
+  }
+  getTail(key, maxBytes) {
+    return withRetry(() => this.inner.getTail(key, maxBytes), this.policy, this.deps);
+  }
+  delete(key) {
+    return withRetry(() => this.inner.delete(key), this.policy, this.deps);
+  }
+  async *list(ref) {
+    const keys = await withRetry(
+      async () => {
+        const out = [];
+        for await (const k of this.inner.list(ref)) out.push(k);
+        return out;
+      },
+      this.policy,
+      this.deps
+    );
+    yield* keys;
+  }
+};
+var RetryingRegistryDriver = class {
+  inner;
+  policy;
+  deps;
+  constructor(inner, opts) {
+    this.inner = inner;
+    const r = toRetry(opts);
+    this.policy = r.policy;
+    this.deps = r.deps;
+  }
+  capabilities() {
+    return this.inner.capabilities();
+  }
+  get(ref) {
+    return withRetry(() => this.inner.get(ref), this.policy, this.deps);
+  }
+  create(ref, record) {
+    return withRetry(() => this.inner.create(ref, record), this.policy, this.deps);
+  }
+  compareAndSwap(ref, expected, patch) {
+    return withRetry(() => this.inner.compareAndSwap(ref, expected, patch), this.policy, this.deps);
+  }
+  async *list(namespace) {
+    const records = await withRetry(
+      async () => {
+        const out = [];
+        for await (const r of this.inner.list(namespace)) out.push(r);
+        return out;
+      },
+      this.policy,
+      this.deps
+    );
+    yield* records;
+  }
+  delete(ref) {
+    return withRetry(() => this.inner.delete(ref), this.policy, this.deps);
+  }
+};
+
+exports.AWS_US_EAST_1_ONDEMAND = AWS_US_EAST_1_ONDEMAND;
+exports.BoundedLru = BoundedLru;
+exports.BudgetExceededError = BudgetExceededError;
+exports.BufferReader = BufferReader;
+exports.BufferSink = BufferSink;
+exports.CapabilityError = CapabilityError;
+exports.CloudRoaringError = CloudRoaringError;
+exports.CountingMetricsSink = CountingMetricsSink;
+exports.CrbmColdChunkSource = CrbmColdChunkSource;
+exports.CrbmReader = CrbmReader;
+exports.CrbmWriter = CrbmWriter;
+exports.DEFAULT_BUDGET = DEFAULT_BUDGET;
+exports.DEFAULT_OCC_BACKOFF = DEFAULT_OCC_BACKOFF;
+exports.DEFAULT_PRICING = DEFAULT_PRICING;
+exports.DEFAULT_RETRY_POLICY = DEFAULT_RETRY_POLICY;
+exports.InProcessKeystore = InProcessKeystore;
+exports.IntegrityError = IntegrityError;
+exports.KeyUnavailableError = KeyUnavailableError;
+exports.LocalFsColdDriver = LocalFsColdDriver;
+exports.LocalFsRegistryDriver = LocalFsRegistryDriver;
+exports.LocalFsWarmDriver = LocalFsWarmDriver;
+exports.MemoryColdChunkSource = MemoryColdChunkSource;
+exports.MemoryColdDriver = MemoryColdDriver;
+exports.MemoryRegistryDriver = MemoryRegistryDriver;
+exports.MemoryWarmDriver = MemoryWarmDriver;
+exports.NOOP_AUDIT = NOOP_AUDIT;
+exports.NOOP_METRICS = NOOP_METRICS;
+exports.NO_ROW = NO_ROW;
+exports.NodeAead = NodeAead;
+exports.NotFoundError = NotFoundError;
+exports.RecordingAuditSink = RecordingAuditSink;
+exports.RetryingColdChunkSource = RetryingColdChunkSource;
+exports.RetryingColdDriver = RetryingColdDriver;
+exports.RetryingRegistryDriver = RetryingRegistryDriver;
+exports.RetryingWarmDriver = RetryingWarmDriver;
+exports.SegmentEngine = SegmentEngine;
+exports.TimeoutError = TimeoutError;
+exports.TransientError = TransientError;
+exports.UnsupportedError = UnsupportedError;
+exports.ValidationError = ValidationError;
+exports.WriteConflictError = WriteConflictError;
+exports.aadFor = aadFor;
+exports.bulkLoadCrbmGeneration = bulkLoadCrbmGeneration;
+exports.checkBudget = checkBudget;
+exports.chunkRefKey = chunkRefKey;
+exports.compactSegment = compactSegment;
+exports.destroySegment = destroySegment;
+exports.eraseNamespace = eraseNamespace;
+exports.estimateCost = estimateCost;
+exports.findCompactable = findCompactable;
+exports.gcOrphanGenerations = gcOrphanGenerations;
+exports.groundedReport = groundedReport;
+exports.isCloudRoaringError = isCloudRoaringError;
+exports.isIntegrityError = isIntegrityError;
+exports.isNotFoundError = isNotFoundError;
+exports.isTransient = isTransient;
+exports.isTransientError = isTransientError;
+exports.isValidationError = isValidationError;
+exports.isWriteConflictError = isWriteConflictError;
+exports.joinId = joinId;
+exports.mapWithConcurrency = mapWithConcurrency;
+exports.publishGeneration = publishGeneration;
+exports.resolveBudget = resolveBudget;
+exports.resolvePerOpBudget = resolvePerOpBudget;
+exports.runCompactionCycle = runCompactionCycle;
+exports.runConsistencyCheck = runConsistencyCheck;
+exports.runExport = runExport;
+exports.safeMetrics = safeMetrics;
+exports.segmentKey = segmentKey;
+exports.splitId = splitId;
+exports.validateCompactionOptions = validateCompactionOptions;
+exports.validateSegmentRef = validateSegmentRef;
+exports.withRetry = withRetry;
+exports.writeCrbmGeneration = writeCrbmGeneration;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map