@cloudbitmaps/core 0.20.0 → 0.22.0

package/dist/{chunk-YSC7NJWV.js → chunk-OSU7W2Y3.js}

@@ -3,7 +3,7 @@ var ERROR_BRAND = /* @__PURE__ */ Symbol.for("cloudbitmaps.error");
 var TRANSIENT_BRAND = /* @__PURE__ */ Symbol.for("cloudbitmaps.error.transient");
 var NAMES = /* @__PURE__ */ new WeakMap();
 var CloudRoaringError = class extends Error {
-  /** Cross-bundle brand — see the predicates ({@link isCloudRoaringError}, …). Non-enumerable-ish (symbol key ⇒ not in JSON). */
+  /** Cross-bundle brand — see {@link errorKind}. Non-enumerable-ish (symbol key ⇒ not in JSON). */
   [ERROR_BRAND] = true;
   constructor(message) {
     super(message);
@@ -12,6 +12,7 @@ var CloudRoaringError = class extends Error {
 };
 var ValidationError = class extends CloudRoaringError {
 };
+var CONTENTION_NEXT_STEP = "; another writer changed the segment's row while this call ran. Re-run the call: it reads the row afresh";
 var WriteConflictError = class extends CloudRoaringError {
 };
 var IntegrityError = class extends CloudRoaringError {
@@ -48,6 +49,21 @@ var UnsupportedError = class extends CloudRoaringError {
 var CapabilityError = class extends CloudRoaringError {
 };
 var BudgetExceededError = class extends CloudRoaringError {
+  /** The option to raise to let the call through. */
+  option;
+  /** The bound in force: requests, bytes or rows, by `option`. */
+  limit;
+  /**
+   * What the call had reached when refused. By `option`: the requests the call needs (`'budget.maxRequests'`), a
+   * lower bound on the resident bytes it needs (`'maxBufferedBytes'`), or `limit + 1` (`'maxScanSegments'`).
+   */
+  spent;
+  constructor(message, details) {
+    super(message);
+    this.option = details.option;
+    this.limit = details.limit;
+    this.spent = details.spent;
+  }
 };
 var KeyUnavailableError = class extends CloudRoaringError {
 };
@@ -84,15 +100,6 @@ function isWriteConflictError(err) {
 function isTransientError(err) {
   return hasBrand(err, TRANSIENT_BRAND);
 }
-function isLeaseExpiredError(err) {
-  return isCloudRoaringError(err) && err.name === "LeaseExpiredError";
-}
-function isStaleOperandError(err) {
-  return isCloudRoaringError(err) && err.name === "StaleOperandError";
-}
-function isLeaseLimitError(err) {
-  return isCloudRoaringError(err) && err.name === "LeaseLimitError";
-}
 function isNotFoundError(err) {
   return isCloudRoaringError(err) && err.name === "NotFoundError";
 }
@@ -102,23 +109,169 @@ function isIntegrityError(err) {
 function isValidationError(err) {
   return isCloudRoaringError(err) && err.name === "ValidationError";
 }
-function isUnsupportedError(err) {
-  return isCloudRoaringError(err) && err.name === "UnsupportedError";
+function isKeyUnavailableError(err) {
+  return isCloudRoaringError(err) && err.name === "KeyUnavailableError";
 }
-function isCapabilityError(err) {
-  return isCloudRoaringError(err) && err.name === "CapabilityError";
+var KIND_NAMES = {
+  CloudRoaringError: true,
+  ValidationError: true,
+  WriteConflictError: true,
+  IntegrityError: true,
+  NotFoundError: true,
+  UnsupportedError: true,
+  CapabilityError: true,
+  TransientError: true,
+  KeyUnavailableError: true,
+  BudgetExceededError: true,
+  LeaseExpiredError: true,
+  LeaseLimitError: true,
+  StaleOperandError: true
+};
+function errorKind(err) {
+  if (hasBrand(err, TRANSIENT_BRAND)) return "TransientError";
+  if (!hasBrand(err, ERROR_BRAND)) return void 0;
+  const name = err.name;
+  return typeof name === "string" && Object.hasOwn(KIND_NAMES, name) ? name : "CloudRoaringError";
 }
-function isBudgetExceededError(err) {
-  return isCloudRoaringError(err) && err.name === "BudgetExceededError";
+
+// src/core/bit-route.ts
+var U32_MAX = 4294967295;
+var CHUNK_COUNT = 65536;
+var LOW_16 = 65535;
+var idErrors = /* @__PURE__ */ new WeakSet();
+function isBadIdError(err) {
+  return err instanceof ValidationError && idErrors.has(err);
+}
+function badId(id) {
+  let got;
+  if (id === null) got = "null";
+  else if (id === void 0) got = "undefined";
+  else if (typeof id === "object") got = "an object";
+  else if (typeof id !== "number") got = `${/^[aeiou]/.test(typeof id) ? "an" : "a"} ${typeof id}`;
+  else if (!Number.isFinite(id)) got = "NaN or an infinity";
+  else if (id < 0) got = "a negative number";
+  else if (!Number.isInteger(id)) got = "a number with a fraction";
+  else got = `a number above ${U32_MAX} (ids are 32-bit)`;
+  const err = new ValidationError(`an id must be an integer from 0 to ${U32_MAX}; got ${got}`);
+  idErrors.add(err);
+  return err;
+}
+function splitId(id) {
+  if (!Number.isInteger(id) || id < 0 || id > U32_MAX) {
+    throw badId(id);
+  }
+  return { chunkKey: id >>> 16, remainder: id & LOW_16 };
+}
+var MAX_REMAINDER = CHUNK_COUNT - 1;
+function joinId(chunkKey, remainder) {
+  return ((chunkKey & LOW_16) << 16 >>> 0) + (remainder & LOW_16);
 }
-function isKeyUnavailableError(err) {
-  return isCloudRoaringError(err) && err.name === "KeyUnavailableError";
+
+// src/core/check.ts
+function shown(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "bigint") return `${value}n`;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return value === null ? "null" : typeof value;
+}
+function rangeOf(min, max, note) {
+  let range = "";
+  if (min !== void 0 && max !== void 0) range = ` from ${min} to ${max}`;
+  else if (min !== void 0) range = ` of at least ${min}`;
+  else if (max !== void 0) range = ` of at most ${max}`;
+  return note === void 0 ? range : `${range} (${note})`;
+}
+function requireInteger(value, bounds) {
+  const { min, max, what, note } = bounds;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || max !== void 0 && value > max) {
+    throw new ValidationError(
+      `${what} must be an integer${rangeOf(min, max, note)}; got ${shown(value)}`
+    );
+  }
+  return value;
+}
+function requirePositiveInteger(value, what) {
+  return requireInteger(value, { min: 1, what });
+}
+function requireFiniteNumber(value, bounds) {
+  const { min, max, what, note } = bounds;
+  if (typeof value !== "number" || !Number.isFinite(value) || min !== void 0 && value < min || max !== void 0 && value > max) {
+    throw new ValidationError(
+      `${what} must be a finite number${rangeOf(min, max, note)}; got ${shown(value)}`
+    );
+  }
+  return value;
+}
+
+// src/core/concurrency.ts
+async function mapWithConcurrency(items, limit, fn) {
+  requirePositiveInteger(limit, "concurrency 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;
+}
+function boundedAll(items, limit, fn) {
+  try {
+    requirePositiveInteger(limit, "concurrency limit");
+  } catch (err) {
+    return Promise.reject(err);
+  }
+  if (items.length > limit) return inWaves(items, limit, fn);
+  const calls = [];
+  for (const item of items) {
+    try {
+      calls.push(fn(item));
+    } catch (err) {
+      void Promise.allSettled(calls);
+      return Promise.reject(err);
+    }
+  }
+  return Promise.all(calls);
+}
+async function inWaves(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  let failed = false;
+  const worker = async () => {
+    while (!failed && next < items.length) {
+      const i = next++;
+      try {
+        results[i] = await fn(items[i]);
+      } catch (err) {
+        failed = true;
+        throw err;
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: limit }, () => worker()));
+  return results;
 }
 
 // src/core/name-codec.ts
 var KEY_SAFE = /[A-Za-z0-9._:-]/;
 var PATH_SAFE = /[A-Za-z0-9._-]/;
 var UTF8 = new TextEncoder();
+var UTF8_LENIENT = new TextDecoder("utf-8", { fatal: false, ignoreBOM: true });
 function escapeChar(ch) {
   let out = "";
   for (const byte of UTF8.encode(ch)) {
@@ -136,17 +289,17 @@ function encodeWith(name, safe) {
 function decodePercent(encoded) {
   const bytes = [];
   for (let i = 0; i < encoded.length; ) {
-    if (encoded[i] === "%" && i + 2 < encoded.length + 1) {
+    if (encoded[i] === "%" && i + 2 <= encoded.length) {
       const hex = encoded.slice(i + 1, i + 3);
       if (!/^[0-9A-Fa-f]{2}$/.test(hex)) return encoded;
       bytes.push(parseInt(hex, 16));
       i += 3;
     } else {
-      for (const b of new TextEncoder().encode(encoded[i])) bytes.push(b);
+      for (const b of UTF8.encode(encoded[i])) bytes.push(b);
       i += 1;
     }
   }
-  return new TextDecoder("utf-8", { fatal: false, ignoreBOM: true }).decode(new Uint8Array(bytes));
+  return UTF8_LENIENT.decode(new Uint8Array(bytes));
 }
 function encodeNameForKey(name) {
   return defuseDotComponent(encodeWith(name, KEY_SAFE));
@@ -206,7 +359,13 @@ function validatePart(value, field) {
     );
   }
 }
+function requireRefObject(ref, hint = "") {
+  if (typeof ref !== "object" || ref === null) {
+    throw new ValidationError(`a segment ref is an object such as { segment: 'name' }${hint}`);
+  }
+}
 function validateSegmentRef(ref) {
+  requireRefObject(ref);
   validatePart(ref.segment, "segment");
   if (ref.namespace !== void 0) validatePart(ref.namespace, "namespace");
 }
@@ -223,6 +382,7 @@ function validateUserNamespace(namespace) {
   }
 }
 function validateUserRef(ref) {
+  requireRefObject(ref, "; store.segment() takes the bare name");
   validatePart(ref.segment, "segment");
   if (ref.namespace !== void 0) validateUserNamespace(ref.namespace);
 }
@@ -234,39 +394,12 @@ function validateChunkKeyOrder(keys) {
 }
 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}]`);
-  }
+  validateChunkKey(ref.chunkKey);
 }
-
-// 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}`);
+function validateChunkKey(chunkKey) {
+  if (!(typeof chunkKey === "number" && chunkKey >= 0 && chunkKey <= CHUNK_KEY_MAX && (chunkKey | 0) === chunkKey)) {
+    throw new ValidationError(`chunkKey must be an integer in [0, ${CHUNK_KEY_MAX}]`);
   }
-  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/ports.ts
@@ -336,6 +469,97 @@ function pointerIdOf(row) {
   return pointerId;
 }
 
+// src/core/crypto.ts
+var UTF82 = new TextEncoder();
+var AAD_VERSION = 1;
+var SCOPE_CHUNK = 0;
+var SCOPE_INDEX = 1;
+var SCOPE_METADATA = 2;
+var SCOPE_SUMMARY = 3;
+function aadFor(ref, generation, scope) {
+  const ns = UTF82.encode(ref.namespace ?? "");
+  const seg = UTF82.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 === "metadata" ? SCOPE_METADATA : scope === "summary" ? SCOPE_SUMMARY : SCOPE_CHUNK;
+  o += 1;
+  view.setUint32(o, typeof scope === "number" ? scope : 0, true);
+  return out;
+}
+var sameKeys = (a, b) => a !== void 0 && JSON.stringify(a) === JSON.stringify(b);
+
+// src/core/retry.ts
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 4,
+  baseDelayMs: 50,
+  maxDelayMs: 2e3,
+  backoffFactor: 2,
+  jitter: "full"
+};
+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;
+}
+function jitteredWait(clock, rng, boundMs) {
+  const sleep = clock?.sleep;
+  return sleep === void 0 ? Promise.resolve() : sleep.call(clock, Math.floor((rng?.next() ?? 1) * boundMs));
+}
+function retryRead(op, retry) {
+  return retry === void 0 ? op() : withRetry(op, retry.policy ?? DEFAULT_RETRY_POLICY, retry);
+}
+function checkedRetryPolicy(policy) {
+  const { maxAttempts, baseDelayMs, maxDelayMs, backoffFactor, jitter } = policy;
+  requireInteger(maxAttempts, { min: 1, what: "retry.maxAttempts" });
+  requireFiniteNumber(baseDelayMs, { min: 0, what: "retry.baseDelayMs" });
+  requireFiniteNumber(maxDelayMs, {
+    min: baseDelayMs,
+    what: "retry.maxDelayMs",
+    note: "retry.baseDelayMs"
+  });
+  requireFiniteNumber(backoffFactor, { min: 1, what: "retry.backoffFactor" });
+  if (jitter !== "full" && jitter !== "none") {
+    throw new ValidationError(`retry.jitter must be 'full' or 'none'`);
+  }
+  return policy;
+}
+async function withRetry(op, policy, deps) {
+  const retryable = deps.isRetryable ?? isTransientError;
+  const attempts = requireInteger(policy.maxAttempts, { min: 1, what: "retry.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);
+      try {
+        deps.onRetry?.({ attempt, delayMs, err });
+      } catch {
+      }
+      await deps.clock.sleep(delayMs);
+    }
+  }
+  throw lastErr;
+}
+
 // src/core/token.ts
 var INCARNATION_TOKEN = /^([0-9a-f]{32})\.(0|[1-9]\d*)\.([0-9a-f]{16})$/;
 function incarnationOf(token) {
@@ -403,10 +627,7 @@ function leaseChurn(deps) {
       if (used >= LEASE_ONLY_RETRIES || !onlyLeasesDiffer(held, now, alsoIgnore)) return void 0;
       const bound = Math.min(CONFLICT_BASE_MS * 2 ** Math.min(used, 4), CONFLICT_CAP_MS);
       used += 1;
-      const sleep = deps.clock?.sleep;
-      if (sleep !== void 0) {
-        await sleep.call(deps.clock, Math.floor((deps.rng?.next() ?? 1) * bound));
-      }
+      await jitteredWait(deps.clock, deps.rng, bound);
       return { row: await reread() };
     }
   };
@@ -417,7 +638,7 @@ function listOf(entries) {
     (a, b) => a.generation !== b.generation ? a.generation - b.generation : a.holder < b.holder ? -1 : a.holder > b.holder ? 1 : 0
   );
 }
-var wait = (deps, bound) => deps.clock.sleep(Math.floor((deps.rng?.next() ?? 1) * bound));
+var wait = (deps, bound) => jitteredWait(deps.clock, deps.rng, bound);
 var heldBy = (row, take) => (row?.leases ?? []).some(
   (e) => e.holder === take.holder && e.generation === take.generation && e.until === take.until
 );
@@ -480,7 +701,9 @@ async function takeLease(ref, deps, take) {
     }
   }
   if (unanswered !== void 0) throw unanswered;
-  throw new WriteConflictError(`lease: contention taking a lease on segment "${ref.segment}"`);
+  throw new WriteConflictError(
+    `lease: contention taking a lease on segment "${ref.segment}"${CONTENTION_NEXT_STEP}`
+  );
 }
 async function releaseLease(ref, deps, holder) {
   let resends = 0;
@@ -514,7 +737,9 @@ async function releaseLease(ref, deps, holder) {
     }
   }
   if (unanswered !== void 0) throw unanswered;
-  throw new WriteConflictError(`lease: contention releasing a lease on segment "${ref.segment}"`);
+  throw new WriteConflictError(
+    `lease: contention releasing a lease on segment "${ref.segment}"${CONTENTION_NEXT_STEP}`
+  );
 }
 
 // src/drivers/_shared/keys.ts
@@ -526,6 +751,44 @@ function namespacePathPart(namespace) {
   return namespace === void 0 ? DEFAULT_NAMESPACE : encodeNameForPath(namespace);
 }
 
+// src/drivers/_shared/options.ts
+function refuseUnknownOptions(name, options, keys, hint) {
+  if (options === null || typeof options !== "object") {
+    throw new ValidationError(
+      `${name} needs an options object \u2014 got ${options === null ? "null" : typeof options}`
+    );
+  }
+  const unknown = Object.keys(options).filter((k) => !keys.includes(k));
+  if (unknown.length > 0) {
+    const list = (ks) => ks.map((k) => `\`${k}\``).join(", ");
+    throw new ValidationError(
+      `${name} does not take ${list(unknown)}. It takes ${list(keys)}${hint === void 0 ? "" : `; ${hint}`}.`
+    );
+  }
+}
+function checkNow(name, now) {
+  if (now !== void 0 && typeof now !== "function") {
+    throw new ValidationError(`${name}: \`now\` must be a function returning epoch milliseconds`);
+  }
+}
+function requirePositiveInt(name, value) {
+  return value === void 0 ? void 0 : requirePositiveInteger(value, name);
+}
+function requireBool(name, value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "boolean") {
+    throw new ValidationError(`${name} must be a boolean; got ${shown2(value)}`);
+  }
+  return value;
+}
+function shown2(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return value === null ? "null" : typeof value;
+}
+
 // src/core/crbm/frame.ts
 var PREAMBLE_BYTES = 8;
 var FOOTER_BYTES = 104;
@@ -533,7 +796,9 @@ var FOOTER_BYTES = 104;
 // src/core/metadata.ts
 var MAX_METADATA_BYTES = 1024;
 var MAX_METADATA_KEY_BYTES = 128;
-var utf8Length = (s) => new TextEncoder().encode(s).length;
+var UTF83 = new TextEncoder();
+var UTF8_STRICT = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+var utf8Length = (s) => UTF83.encode(s).length;
 function canonicalMetadataJson(value, fail) {
   if (value === null || typeof value !== "object") {
     fail(`metadata must be a plain object (got ${value === null ? "null" : typeof value})`);
@@ -580,7 +845,7 @@ function canonicalMetadataJson(value, fail) {
 function metadataBytes(value, fail) {
   if (value === void 0) return void 0;
   const json = canonicalMetadataJson(value, fail);
-  return json === "{}" ? void 0 : new TextEncoder().encode(json);
+  return json === "{}" ? void 0 : UTF83.encode(json);
 }
 function copiedMetadata(value, fail) {
   const bytes = metadataBytes(value, fail);
@@ -592,7 +857,7 @@ function metadataFromBytes(bytes, fail) {
   }
   let text;
   try {
-    text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    text = UTF8_STRICT.decode(bytes);
   } catch {
     fail("metadata is not valid UTF-8");
   }
@@ -621,6 +886,13 @@ function fingerprintParts(fingerprint) {
   if (footerCrc > 4294967295) return void 0;
   return { size, footerCrc };
 }
+function footerCrcOf(fingerprint) {
+  const parts = fingerprintParts(fingerprint);
+  if (parts === void 0) {
+    throw new IntegrityError(`not an object's fingerprint: ${String(fingerprint).slice(0, 64)}`);
+  }
+  return parts.footerCrc;
+}
 function compactFingerprint(fingerprint) {
   const colon = fingerprint.indexOf(":");
   const size = Number(fingerprint.slice(0, colon));
@@ -628,25 +900,352 @@ function compactFingerprint(fingerprint) {
   return `${size.toString(36)}.${crc.toString(36)}`;
 }
 
-// src/core/kept-generations.ts
+// src/core/summary.ts
+var NONCE_BYTES = 12;
+var TAG_BYTES = 16;
+var COUNT_BYTES = 8;
+var SIZE_BYTES = 8;
+var CRC_BYTES = 4;
+var TAIL_BYTES = 4;
+var FIXED_BYTES = COUNT_BYTES + SIZE_BYTES + CRC_BYTES + TAIL_BYTES;
+var MAX_SUMMARY_CARDINALITY = U32_MAX + 1;
+var MAX_TAIL_BYTES = 8392820;
+function tailBytesFit(tailBytes, size) {
+  return typeof tailBytes === "number" && Number.isInteger(tailBytes) && tailBytes >= FOOTER_BYTES && tailBytes <= size - PREAMBLE_BYTES && tailBytes <= MAX_TAIL_BYTES;
+}
+function sizeOfFingerprint(fingerprint) {
+  const parts = fingerprintParts(fingerprint);
+  if (parts === void 0)
+    throw new IntegrityError("registry record summary: a malformed fingerprint");
+  return parts.size;
+}
+var BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function toBase64(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i];
+    const b = bytes[i + 1];
+    const c = bytes[i + 2];
+    out += BASE64[a >> 2] + BASE64[(a & 3) << 4 | (b ?? 0) >> 4];
+    out += b === void 0 ? "=" : BASE64[(b & 15) << 2 | (c ?? 0) >> 6];
+    out += c === void 0 ? "=" : BASE64[c & 63];
+  }
+  return out;
+}
+function fromBase64(text) {
+  if (text.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(text)) return void 0;
+  const pad = text.endsWith("==") ? 2 : text.endsWith("=") ? 1 : 0;
+  const out = new Uint8Array(text.length / 4 * 3 - pad);
+  let o = 0;
+  for (let i = 0; i < text.length; i += 4) {
+    const n = BASE64.indexOf(text[i]) << 18 | BASE64.indexOf(text[i + 1]) << 12 | Math.max(BASE64.indexOf(text[i + 2]), 0) << 6 | Math.max(BASE64.indexOf(text[i + 3]), 0);
+    if (o < out.length) out[o++] = n >> 16 & 255;
+    if (o < out.length) out[o++] = n >> 8 & 255;
+    if (o < out.length) out[o++] = n & 255;
+  }
+  return out;
+}
+function clearSummary(generation, cardinality, fingerprint, tailBytes, metadata) {
+  return metadata === void 0 || Object.keys(metadata).length === 0 ? { generation, cardinality, fingerprint, tailBytes } : { generation, cardinality, fingerprint, tailBytes, metadata };
+}
+function sealSummary(aead, ref, generation, cardinality, fingerprint, tailBytes, metadata) {
+  const meta = metadataBytes(metadata, (message) => {
+    throw new IntegrityError(`summary metadata: ${message}`);
+  });
+  const parts = fingerprintParts(fingerprint);
+  if (parts === void 0) throw new IntegrityError("summary: a malformed fingerprint");
+  const plain = new Uint8Array(FIXED_BYTES + (meta?.length ?? 0));
+  const view = new DataView(plain.buffer);
+  view.setBigUint64(0, BigInt(cardinality), true);
+  view.setBigUint64(COUNT_BYTES, BigInt(parts.size), true);
+  view.setUint32(COUNT_BYTES + SIZE_BYTES, parts.footerCrc, true);
+  view.setUint32(COUNT_BYTES + SIZE_BYTES + CRC_BYTES, tailBytes, true);
+  if (meta !== void 0) plain.set(meta, FIXED_BYTES);
+  const { nonce, ciphertext, tag } = aead.seal(plain, aadFor(ref, generation, "summary"));
+  const framed = new Uint8Array(nonce.length + ciphertext.length + tag.length);
+  framed.set(nonce, 0);
+  framed.set(ciphertext, nonce.length);
+  framed.set(tag, nonce.length + ciphertext.length);
+  return { generation, sealed: toBase64(framed) };
+}
+function openSummary(aead, ref, summary) {
+  const fail = (message) => {
+    throw new IntegrityError(`registry record summary: ${message}`);
+  };
+  const framed = fromBase64(summary.sealed);
+  const framing = NONCE_BYTES + TAG_BYTES;
+  if (framed === void 0 || framed.length < framing + FIXED_BYTES || framed.length > framing + FIXED_BYTES + MAX_METADATA_BYTES) {
+    fail(
+      "the sealed summary is not a nonce, a count, a fingerprint, a tail size, up to 1 KiB of metadata and a tag"
+    );
+  }
+  const bytes = framed;
+  let plain;
+  try {
+    plain = aead.open(
+      {
+        nonce: bytes.subarray(0, NONCE_BYTES),
+        ciphertext: bytes.subarray(NONCE_BYTES, bytes.length - TAG_BYTES),
+        tag: bytes.subarray(bytes.length - TAG_BYTES)
+      },
+      aadFor(ref, summary.generation, "summary")
+    );
+  } catch (err) {
+    if (!isIntegrityError(err)) throw err;
+    return fail(
+      "the sealed summary does not open: tampered bytes, or a summary moved from another generation"
+    );
+  }
+  if (plain.length < FIXED_BYTES)
+    fail("the sealed summary is shorter than its count, fingerprint and tail size");
+  const view = new DataView(plain.buffer, plain.byteOffset, plain.byteLength);
+  const count = view.getBigUint64(0, true);
+  if (count > BigInt(MAX_SUMMARY_CARDINALITY)) fail(`cardinality ${count} is outside 0 to 2^32`);
+  const size = view.getBigUint64(COUNT_BYTES, true);
+  const fingerprint = fingerprintFor(Number(size), view.getUint32(COUNT_BYTES + SIZE_BYTES, true));
+  if (size > BigInt(Number.MAX_SAFE_INTEGER) || fingerprintParts(fingerprint) === void 0) {
+    fail(`the object size ${size} is not one a .crbm object can have`);
+  }
+  const tailBytes = view.getUint32(COUNT_BYTES + SIZE_BYTES + CRC_BYTES, true);
+  if (!tailBytesFit(tailBytes, Number(size))) {
+    fail(`the tail size ${tailBytes} is not one a .crbm object of ${size} bytes can have`);
+  }
+  const metadata = plain.length === FIXED_BYTES ? void 0 : metadataFromBytes(plain.subarray(FIXED_BYTES), fail);
+  return { cardinality: Number(count), metadata, fingerprint, tailBytes };
+}
+function usableSummary(ref, row, aead) {
+  const summary = row.summary;
+  if (summary === void 0 || row.status !== "active" || summary.generation !== row.currentGen) {
+    return void 0;
+  }
+  const keyed = row.wrappedDeks !== void 0 && row.wrappedDeks.length > 0;
+  if ("sealed" in summary) {
+    if (!keyed || aead === void 0) return void 0;
+    try {
+      return openSummary(aead, ref, summary);
+    } catch (err) {
+      if (isIntegrityError(err)) return void 0;
+      throw err;
+    }
+  }
+  if (keyed) return void 0;
+  const parts = fingerprintParts(summary.fingerprint);
+  if (parts === void 0 || !tailBytesFit(summary.tailBytes, parts.size)) return void 0;
+  return {
+    cardinality: summary.cardinality,
+    metadata: summary.metadata,
+    fingerprint: summary.fingerprint,
+    tailBytes: summary.tailBytes
+  };
+}
+function canonicalOrNone(metadata) {
+  if (metadata === void 0) return void 0;
+  const json = canonicalMetadataJson(metadata, (message) => {
+    throw new IntegrityError(`metadata: ${message}`);
+  });
+  return json === "{}" ? void 0 : json;
+}
+function summaryAgrees(summary, object) {
+  return summary.cardinality === object.cardinality && canonicalOrNone(summary.metadata) === canonicalOrNone(object.metadata) && (summary.tailBytes === void 0 || object.tailBytes === void 0 || summary.tailBytes === object.tailBytes);
+}
+function metadataToCarry(object, authenticated) {
+  const empty = (metadata) => metadata === void 0 || Object.keys(metadata).length === 0;
+  return empty(object) && authenticated !== void 0 && !empty(authenticated.metadata) ? authenticated.metadata : object;
+}
+function summaryOf(ref, generation, description, aead) {
+  const { cardinality, fingerprint, tailBytes, metadata } = description;
+  if (tailBytes > MAX_TAIL_BYTES) return void 0;
+  return aead === void 0 ? clearSummary(generation, cardinality, fingerprint, tailBytes, metadata) : sealSummary(aead, ref, generation, cardinality, fingerprint, tailBytes, metadata);
+}
+function ownSummary(ref, generation, description, aead) {
+  const summary = summaryOf(ref, generation, description, aead);
+  if (summary === void 0) {
+    throw new IntegrityError(
+      `the object written for generation ${generation} of "${ref.segment}" has a tail of ${description.tailBytes} bytes, above the ${MAX_TAIL_BYTES} a summary records`
+    );
+  }
+  return summary;
+}
+
+// src/core/known-generations-shape.ts
+var ENTRY_KEYS = ["generation", "footerCrc"];
+function knownGensShapeFault(value, max, show = String) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value)) return "must be an array";
+  const list = value;
+  if (list.length > max) return `has ${list.length} entries, cap ${max}`;
+  const seen = /* @__PURE__ */ new Set();
+  for (const e of list) {
+    if (typeof e !== "object" || e === null || Array.isArray(e))
+      return "an entry must be an object";
+    const entry = e;
+    const extra = Object.keys(entry).filter((k) => !ENTRY_KEYS.includes(k));
+    if (extra.length > 0) {
+      return `an entry carries an undeclared field (${show(extra.join(", "))})`;
+    }
+    const { generation, footerCrc } = entry;
+    if (!Number.isSafeInteger(generation) || generation < 0) {
+      return `a generation must be a non-negative safe integer (got ${show(generation)})`;
+    }
+    if (!Number.isInteger(footerCrc) || footerCrc < 0 || footerCrc > 4294967295) {
+      return `a footerCrc must be an integer from 0 to 2^32 - 1 (got ${show(footerCrc)})`;
+    }
+    if (seen.has(generation)) return `generation ${String(generation)} is repeated`;
+    seen.add(generation);
+  }
+  return void 0;
+}
+
+// src/core/order.ts
+var ascending = (a, b) => a - b;
+
+// src/core/known-generations.ts
 var MAX_KEPT_GENERATIONS = 64;
-var MAX_STORED_KEPT_GENERATIONS = 256;
-function usableKeptGens(record) {
-  const list = record?.keptGens;
-  if (record === null || list === void 0 || record.currentGen === null) return void 0;
-  for (const g of list) if (g >= record.currentGen) return void 0;
-  return list;
-}
-function nextKept(prev, generation, keep) {
-  const none = { list: void 0, evict: [] };
-  if (keep === void 0 || keep > MAX_KEPT_GENERATIONS) return none;
-  if (generation === 0) return { list: [], evict: [] };
-  const previous = prev?.currentGen ?? null;
-  const known = usableKeptGens(prev);
-  if (previous === null || known === void 0) return none;
-  const all = [...known, previous];
-  const cut = Math.max(0, all.length - keep);
-  return { list: all.slice(cut), evict: all.slice(0, cut) };
+var KNOWN_FILL = 128;
+var MAX_KNOWN_GENERATIONS = 192;
+var MAX_STORED_KNOWN_GENERATIONS = 384;
+function usableKnownGens(record) {
+  const known = record?.knownGens;
+  if (record === null || known === void 0 || known.length === 0 || record.status !== "active" || record.currentGen === null) {
+    return void 0;
+  }
+  const last = known[known.length - 1];
+  if (last.generation !== record.currentGen) return void 0;
+  const summary = record.summary;
+  if (summary !== void 0 && summary.generation === record.currentGen && "fingerprint" in summary && fingerprintParts(summary.fingerprint)?.footerCrc !== last.footerCrc) {
+    return void 0;
+  }
+  return known;
+}
+function windowOf(record) {
+  const known = usableKnownGens(record);
+  if (known === void 0) return void 0;
+  const pointer = record.currentGen;
+  return known.filter((e) => e.generation < pointer).map((e) => e.generation);
+}
+function carriesWindow(record, leased) {
+  const below = windowOf(record);
+  return below !== void 0 && below.filter((g) => !leased.has(g)).length <= MAX_KEPT_GENERATIONS;
+}
+var KNOWN_SPAN = 127;
+function keptWindow(below, superseded, keep) {
+  const oldestFirst = [...below].sort(ascending);
+  const first = keep > 0 && superseded !== void 0 && oldestFirst.includes(superseded) ? superseded : void 0;
+  const held = new Set(first === void 0 ? [] : [first]);
+  for (let i = oldestFirst.length - 1, room = keep - held.size; i >= 0 && room > 0; i--) {
+    if (oldestFirst[i] === first) continue;
+    held.add(oldestFirst[i]);
+    room -= 1;
+  }
+  return {
+    kept: oldestFirst.filter((g) => held.has(g)),
+    evict: oldestFirst.filter((g) => !held.has(g))
+  };
+}
+function capKnown(known, protect, leased = /* @__PURE__ */ new Set()) {
+  const keep = /* @__PURE__ */ new Set();
+  for (const e of known) if (protect.has(e.generation)) keep.add(e.generation);
+  for (let i = known.length - 1; i >= 0 && keep.size < MAX_KNOWN_GENERATIONS; i--) {
+    if (leased.has(known[i].generation)) keep.add(known[i].generation);
+  }
+  for (let i = known.length - 1; i >= 0 && keep.size < KNOWN_FILL; i--)
+    keep.add(known[i].generation);
+  return known.filter((e) => keep.has(e.generation));
+}
+function capInsert(known, protect, leased) {
+  const keep = /* @__PURE__ */ new Set();
+  let unleased = 0;
+  for (const e of known) {
+    if (!protect.has(e.generation)) continue;
+    keep.add(e.generation);
+    if (!leased.has(e.generation)) unleased += 1;
+  }
+  for (let i = known.length - 1; i >= 0 && unleased < KNOWN_FILL; i--) {
+    const g = known[i].generation;
+    if (keep.has(g) || leased.has(g)) continue;
+    keep.add(g);
+    unleased += 1;
+  }
+  for (let i = known.length - 1; i >= 0 && keep.size < MAX_KNOWN_GENERATIONS; i--) {
+    if (leased.has(known[i].generation)) keep.add(known[i].generation);
+  }
+  return known.filter((e) => keep.has(e.generation));
+}
+function makeCurrent(known, entry) {
+  return [...known.filter((e) => e.generation !== entry.generation), entry];
+}
+function nextKnown(prev, generation, footerCrc, keep, options = {}) {
+  const self = { generation, footerCrc };
+  const clears = options.clearsLeases === true;
+  const byName = keep !== void 0 && keep <= MAX_KEPT_GENERATIONS;
+  if (options.seed !== void 0 && !clears) {
+    const seed = options.seed.filter((e) => e.generation !== generation);
+    const protect = /* @__PURE__ */ new Set([...seed.map((e) => e.generation), generation]);
+    return {
+      known: capKnown([...seed, self], protect, options.leased ?? /* @__PURE__ */ new Set()),
+      list: void 0,
+      evict: []
+    };
+  }
+  const found = usableKnownGens(prev);
+  if (found === void 0 && prev !== null && prev.currentGen !== null) {
+    return { known: [self], list: void 0, evict: [] };
+  }
+  const all = found ?? [];
+  const below = all.filter((e) => e.generation < generation);
+  const above = clears ? [] : all.filter((e) => e.generation > generation);
+  const span = clears ? 0 : Math.min(keep ?? Number.MAX_SAFE_INTEGER, KNOWN_SPAN);
+  const vouch = new Set((span === 0 ? [] : below.slice(-span)).map((e) => e.generation));
+  const leased = clears ? /* @__PURE__ */ new Set() : options.leased ?? /* @__PURE__ */ new Set();
+  const held = below.filter((e) => !vouch.has(e.generation) && leased.has(e.generation));
+  const chosen = /* @__PURE__ */ new Set([
+    ...vouch,
+    ...held.map((e) => e.generation),
+    ...above.map((e) => e.generation)
+  ]);
+  const known = capKnown(
+    [...all.filter((e) => chosen.has(e.generation)), self],
+    /* @__PURE__ */ new Set([...vouch, generation]),
+    leased
+  );
+  const wide = !clears && found !== void 0 && !carriesWindow(prev, leased);
+  if (!byName || wide) return { known, list: void 0, evict: [] };
+  const named = new Set(known.map((e) => e.generation));
+  return {
+    known,
+    list: known.filter((e) => e.generation < generation).map((e) => e.generation).sort(ascending),
+    evict: below.filter((e) => !named.has(e.generation)).map((e) => e.generation).sort(ascending)
+  };
+}
+function rollbackKnown(prev, target) {
+  const found = usableKnownGens(prev);
+  if (found === void 0) return void 0;
+  const moved = makeCurrent(found, target);
+  const inserted = !found.some((e) => e.generation === target.generation);
+  if (!inserted && moved.length <= MAX_KNOWN_GENERATIONS) return moved;
+  return capInsert(moved, /* @__PURE__ */ new Set([target.generation, prev.currentGen]), leasedByRow(prev));
+}
+function pruneKnown(record, doomed) {
+  const found = usableKnownGens(record);
+  if (found === void 0) return void 0;
+  const rest = found.filter((e) => e.generation === record.currentGen || !doomed.has(e.generation));
+  if (rest.length <= MAX_KNOWN_GENERATIONS) return rest;
+  return capKnown(rest, /* @__PURE__ */ new Set([record.currentGen]), leasedByRow(record));
+}
+function describingKnown(record, movedTo) {
+  const found = usableKnownGens(record);
+  if (found === void 0 || found.length <= MAX_KNOWN_GENERATIONS) return found;
+  return capKnown(found, /* @__PURE__ */ new Set([record.currentGen, movedTo]), leasedByRow(record));
+}
+function isFullLedger(known) {
+  return known.length >= KNOWN_FILL;
+}
+function fallbackBound(record, known) {
+  const leased = leasedByRow(record);
+  return (known.find((e) => !leased.has(e.generation)) ?? known[0]).generation;
+}
+function leasedByRow(record) {
+  return new Set((record.leases ?? []).map((e) => e.generation));
 }
 
 // src/drivers/_shared/registry.ts
@@ -664,7 +1263,7 @@ var RECORD_FIELDS = [
   "createdAt",
   "updatedAt",
   "token",
-  "keptGens",
+  "knownGens",
   "leases",
   "pointerId"
 ];
@@ -673,10 +1272,9 @@ var ENVELOPE_FIELDS = ["schemaVersion", "deleted", "record"];
 var MAX_GOVERNANCE_BYTES = 64 * 1024;
 var MAX_WRAPPED_DEKS = 8;
 var MAX_WRAPPED_DEK_BYTES = 4 * 1024;
-var MAX_SUMMARY_CARDINALITY = 2 ** 32;
-var SEALED_SUMMARY_MIN_BYTES = 12 + 8 + 8 + 4 + 16;
+var SEALED_SUMMARY_MIN_BYTES = 12 + 8 + 8 + 4 + 4 + 16;
 var SEALED_SUMMARY_MAX_BYTES = SEALED_SUMMARY_MIN_BYTES + MAX_METADATA_BYTES;
-var BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+var BASE642 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
 function validateGeneration(gen) {
   if (gen === null) return;
   if (!Number.isSafeInteger(gen) || gen < 0) {
@@ -716,10 +1314,10 @@ function validateGovernance(meta, field) {
     throw new ValidationError(`${field} is ${json.length}B, exceeds cap ${MAX_GOVERNANCE_BYTES}B`);
   }
 }
-function validateWrappedDeks(value, isStored) {
+function validateWrappedDeks(value, origin) {
   if (value === void 0) return;
   const fail = (msg) => {
-    throw isStored ? new IntegrityError(msg) : new ValidationError(msg);
+    throw origin === "stored" ? new IntegrityError(msg) : new ValidationError(msg);
   };
   if (!Array.isArray(value)) fail("wrappedDeks must be an array");
   const list = value;
@@ -744,11 +1342,11 @@ function base64PadBitsAreZero(text) {
   const last = BASE64_ALPHABET.indexOf(text[text.length - pad - 1]);
   return pad === 2 ? (last & 15) === 0 : (last & 3) === 0;
 }
-function validateSummary(value, isStored, ctx) {
+function validateSummary(value, origin, ctx) {
   if (value === void 0) return void 0;
   const fail = (msg) => {
     const where = ctx === void 0 ? "" : `: ${ctx}`;
-    throw isStored ? new IntegrityError(`registry record summary: ${msg}${where}`) : new ValidationError(`summary: ${msg}${where}`);
+    throw origin === "stored" ? new IntegrityError(`registry record summary: ${msg}${where}`) : new ValidationError(`summary: ${msg}${where}`);
   };
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     fail(
@@ -758,7 +1356,7 @@ function validateSummary(value, isStored, ctx) {
   const s = value;
   const keys = Object.keys(s);
   const isSealed = keys.includes("sealed");
-  const allowed = isSealed ? ["generation", "sealed"] : ["generation", "cardinality", "fingerprint", "metadata"];
+  const allowed = isSealed ? ["generation", "sealed"] : ["generation", "cardinality", "fingerprint", "tailBytes", "metadata"];
   const extra = keys.filter((k) => !allowed.includes(k));
   if (extra.length > 0) {
     fail(
@@ -771,14 +1369,14 @@ function validateSummary(value, isStored, ctx) {
   }
   if (isSealed) {
     const sealed = s.sealed;
-    if (typeof sealed !== "string" || !BASE64.test(sealed) || !base64PadBitsAreZero(sealed)) {
+    if (typeof sealed !== "string" || !BASE642.test(sealed) || !base64PadBitsAreZero(sealed)) {
       fail("sealed must be canonical, padded standard base64");
     }
     const text = sealed;
     const bytes = text.length / 4 * 3 - (text.endsWith("==") ? 2 : text.endsWith("=") ? 1 : 0);
     if (bytes < SEALED_SUMMARY_MIN_BYTES || bytes > SEALED_SUMMARY_MAX_BYTES) {
       fail(
-        `sealed is ${bytes}B, outside ${SEALED_SUMMARY_MIN_BYTES}..${SEALED_SUMMARY_MAX_BYTES}B (a nonce, a fixed-width count and fingerprint, a tag, and metadata up to its cap)`
+        `sealed is ${bytes}B, outside ${SEALED_SUMMARY_MIN_BYTES}..${SEALED_SUMMARY_MAX_BYTES}B (a nonce, a fixed-width count, fingerprint and tail size, a tag, and metadata up to its cap)`
       );
     }
     return Object.freeze({ generation, sealed: text });
@@ -788,26 +1386,35 @@ function validateSummary(value, isStored, ctx) {
     fail(`cardinality must be an integer from 0 to 2^32 (got ${String(n)})`);
   }
   const fingerprint = s.fingerprint;
-  if (fingerprintParts(fingerprint) === void 0) {
+  const parts = fingerprintParts(fingerprint);
+  if (parts === void 0) {
+    fail(
+      `fingerprint must be an object's, <size>:<footer checksum> in decimal (got ${shown3(JSON.stringify(fingerprint))})`
+    );
+  }
+  const tailBytes = s.tailBytes;
+  if (!tailBytesFit(tailBytes, parts.size)) {
     fail(
-      `fingerprint must be an object's, <size>:<footer checksum> in decimal (got ${shown(JSON.stringify(fingerprint))})`
+      `tailBytes must be an integer from the footer's size to the object's size less its preamble, and at most the cap of one open's tail read (got ${shown3(JSON.stringify(tailBytes))} for an object of ${parts.size} bytes)`
     );
   }
   if (s.metadata === void 0) {
     return Object.freeze({
       generation,
       cardinality: n,
-      fingerprint
+      fingerprint,
+      tailBytes
     });
   }
   const canonical = canonicalMetadataJson(s.metadata, fail);
   if (canonical === "{}") fail("metadata is empty; a generation without metadata carries none");
-  if (isStored) return s;
+  if (origin === "stored") return s;
   const metadata = Object.freeze(JSON.parse(canonical));
   return Object.freeze({
     generation,
     cardinality: n,
     fingerprint,
+    tailBytes,
     metadata
   });
 }
@@ -828,33 +1435,30 @@ function validateSummaryKeys(summary, wrappedDeks) {
     );
   }
 }
-function validateKeptGens(value, isStored, ctx) {
+function validateKnownGens(value, origin, ctx) {
   if (value === void 0) return void 0;
   const fail = (msg) => {
     const where = ctx === void 0 ? "" : `: ${ctx}`;
-    throw isStored ? new IntegrityError(`registry record keptGens: ${msg}${where}`) : new ValidationError(`keptGens: ${msg}`);
+    throw origin === "stored" ? new IntegrityError(`registry record knownGens: ${msg}${where}`) : new ValidationError(`knownGens: ${msg}`);
   };
-  if (!Array.isArray(value)) fail("must be an array");
-  const list = value;
-  const max = isStored ? MAX_STORED_KEPT_GENERATIONS : MAX_KEPT_GENERATIONS;
-  if (list.length > max) fail(`has ${list.length} entries, cap ${max}`);
-  let last = -1;
-  for (const g of list) {
-    if (!Number.isSafeInteger(g) || g < 0) {
-      fail(`entries must be non-negative safe integers (got ${String(g)})`);
-    }
-    if (g <= last) fail("entries must be strictly ascending");
-    last = g;
+  const max = origin === "stored" ? MAX_STORED_KNOWN_GENERATIONS : MAX_KNOWN_GENERATIONS;
+  const fault = knownGensShapeFault(value, max, shown3);
+  if (fault !== void 0) fail(fault);
+  const out = [];
+  for (const entry of value) {
+    out.push(
+      origin === "stored" ? entry : Object.freeze({ generation: entry.generation, footerCrc: entry.footerCrc })
+    );
   }
-  return isStored ? list : Object.freeze([...list]);
+  return origin === "stored" ? out : Object.freeze(out);
 }
 var HOLDER = /^[0-9a-f]{16}$/;
 var LEASE_ENTRY_KEYS = ["holder", "generation", "until"];
-function validateLeases(value, isStored, ctx) {
+function validateLeases(value, origin, ctx) {
   if (value === void 0) return void 0;
   const fail = (msg) => {
     const where = ctx === void 0 ? "" : `: ${ctx}`;
-    throw isStored ? new IntegrityError(`registry record leases: ${msg}${where}`) : new ValidationError(`leases: ${msg}`);
+    throw origin === "stored" ? new IntegrityError(`registry record leases: ${msg}${where}`) : new ValidationError(`leases: ${msg}`);
   };
   if (!Array.isArray(value)) fail("must be an array");
   const list = value;
@@ -882,14 +1486,14 @@ function validateLeases(value, isStored, ctx) {
       }
     }
     out.push(
-      isStored ? entry : Object.freeze({
+      origin === "stored" ? entry : Object.freeze({
         holder,
         generation,
         until
       })
     );
   }
-  if (isStored) return out;
+  if (origin === "stored") return out;
   return out.length === 0 ? void 0 : Object.freeze(out);
 }
 function validateLeasesPointer(leases, currentGen) {
@@ -897,17 +1501,20 @@ function validateLeasesPointer(leases, currentGen) {
     throw new ValidationError("leases: a row with no pointer has no generation to lease");
   }
 }
-function validateKeptGensBelow(keptGens, currentGen) {
-  if (keptGens === void 0) return;
+function validateKnownGensFit(knownGens, currentGen, summary) {
+  if (knownGens === void 0) return;
   if (currentGen === null) {
+    throw new ValidationError("knownGens: a row with no pointer has no generation to know");
+  }
+  const last = knownGens[knownGens.length - 1];
+  if (last === void 0 || last.generation !== currentGen) {
     throw new ValidationError(
-      "keptGens: a row with no pointer has no generations below it to keep"
+      `knownGens must end with the row's pointer ${currentGen}, in the order the generations were made current (its last entry is ${last === void 0 ? "missing" : last.generation})`
     );
   }
-  const top = keptGens[keptGens.length - 1];
-  if (top !== void 0 && top >= currentGen) {
+  if (summary !== void 0 && summary.generation === currentGen && "fingerprint" in summary && fingerprintParts(summary.fingerprint)?.footerCrc !== last.footerCrc) {
     throw new ValidationError(
-      `keptGens names generation ${top}, which is not below the row's pointer ${currentGen}`
+      `knownGens records footerCrc ${last.footerCrc} for generation ${currentGen}, but the summary's fingerprint ${summary.fingerprint} carries another: both describe the one current object`
     );
   }
 }
@@ -919,45 +1526,52 @@ function refuseDriverManaged(write, what) {
     );
   }
 }
+function validateKeyId(keyId) {
+  if (keyId !== void 0 && (typeof keyId !== "string" || keyId.length === 0)) {
+    throw new ValidationError("keyId must be a non-empty string, or absent");
+  }
+}
 function validateNewRegistryRecord(rec) {
   refuseDriverManaged(rec, "a new record");
+  validateKeyId(rec.keyId);
   validateGeneration(rec.currentGen);
   if (rec.status !== void 0) validateStatus(rec.status);
-  validateWrappedDeks(rec.wrappedDeks, false);
+  validateWrappedDeks(rec.wrappedDeks, "caller");
   validateGovernance(rec.retention, "retention");
   validateGovernance(rec.residency, "residency");
-  const keptGens = validateKeptGens(rec.keptGens, false);
-  validateKeptGensBelow(keptGens, rec.currentGen);
-  const withKept = keptGens === void 0 ? rec : { ...rec, keptGens };
-  if (!("summary" in rec)) return withKept;
-  const summary = validateSummary(rec.summary, false);
+  const knownGens = validateKnownGens(rec.knownGens, "caller");
+  const withKnown = knownGens === void 0 ? rec : { ...rec, knownGens };
+  const summary = "summary" in rec ? validateSummary(rec.summary, "caller") : void 0;
+  validateKnownGensFit(knownGens, rec.currentGen, summary);
+  if (!("summary" in rec)) return withKnown;
   validateSummaryNames(summary, rec.currentGen);
   validateSummaryKeys(summary, rec.wrappedDeks);
-  return { ...withKept, summary };
+  return { ...withKnown, summary };
 }
 function validateRegistryPatch(patch) {
   refuseDriverManaged(patch, "a patch");
+  if ("keyId" in patch) validateKeyId(patch.keyId);
   validatePatchGeneration(patch);
   if (patch.status !== void 0) validateStatus(patch.status);
-  if ("wrappedDeks" in patch) validateWrappedDeks(patch.wrappedDeks, false);
+  if ("wrappedDeks" in patch) validateWrappedDeks(patch.wrappedDeks, "caller");
   if ("retention" in patch) validateGovernance(patch.retention, "retention");
   if ("residency" in patch) validateGovernance(patch.residency, "residency");
-  const withKept = patch.keptGens === void 0 ? patch : { ...patch, keptGens: validateKeptGens(patch.keptGens, false) };
-  const withLeases = "leases" in withKept ? { ...withKept, leases: validateLeases(withKept.leases, false) } : withKept;
+  const withKnown = patch.knownGens === void 0 ? patch : { ...patch, knownGens: validateKnownGens(patch.knownGens, "caller") };
+  const withLeases = "leases" in withKnown ? { ...withKnown, leases: validateLeases(withKnown.leases, "caller") } : withKnown;
   if (!("summary" in patch)) return withLeases;
-  return { ...withLeases, summary: validateSummary(patch.summary, false) };
+  return { ...withLeases, summary: validateSummary(patch.summary, "caller") };
 }
-var REGISTRY_SCHEMA_VERSION = 4;
+var REGISTRY_SCHEMA_VERSION = 5;
 function assertRegistrySchemaVersion(raw, ctx) {
   if (raw === void 0) {
     throw new IntegrityError(`registry row has no schemaVersion: ${ctx}`);
   }
   if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1) {
-    throw new IntegrityError(`registry row has a malformed schemaVersion (${shown(raw)}): ${ctx}`);
+    throw new IntegrityError(`registry row has a malformed schemaVersion (${shown3(raw)}): ${ctx}`);
   }
   if (raw < REGISTRY_SCHEMA_VERSION) {
     throw new UnsupportedError(
-      `registry row schemaVersion ${raw} is one this build does not read: it reads schema ${REGISTRY_SCHEMA_VERSION} only. Export the segments with the release that wrote the row and load them with this one into a new prefix (the CHANGELOG gives the steps): ${ctx}`
+      `registry row schemaVersion ${raw} is one this build does not read: it reads schema ${REGISTRY_SCHEMA_VERSION} only. Export the segments with the release that wrote the row and load them with this one into a new prefix (steps: https://github.com/cloudbitmaps/cloudbitmaps/blob/main/CHANGELOG.md, the Breaking entry on registry schema 5): ${ctx}`
     );
   }
   if (raw > REGISTRY_SCHEMA_VERSION) {
@@ -980,7 +1594,7 @@ function tokenParts(token, ctx, what = "token") {
   const match = typeof token === "string" ? INCARNATION_TOKEN.exec(token) : null;
   if (match === null) {
     throw new IntegrityError(
-      `registry row ${what} is not one a shipped registry writes (${shown(JSON.stringify(token))}): ${ctx}`
+      `registry row ${what} is not one a shipped registry writes (${shown3(JSON.stringify(token))}): ${ctx}`
     );
   }
   const counter = Number(match[2]);
@@ -1025,7 +1639,7 @@ function newIncarnationToken(entropy, tombstone) {
   const counter = tombstone === void 0 ? 0 : tokenParts(tombstone.token, tombstone.segment).counter + 1;
   return `${drawIncarnation(entropy)}.${counter}.${drawWrite(entropy)}`;
 }
-function shown(v) {
+function shown3(v) {
   const text = String(v);
   return text.length > 64 ? `${text.slice(0, 64)}\u2026` : text;
 }
@@ -1044,7 +1658,7 @@ function parseRegistryEnvelope(text, ctx, expected) {
   const extra = Object.keys(env).filter((k) => !ENVELOPE_FIELDS.includes(k));
   if (extra.length > 0) {
     throw new IntegrityError(
-      `registry row has fields its envelope does not declare (${shown(extra.join(", "))}): ${ctx}`
+      `registry row has fields its envelope does not declare (${shown3(extra.join(", "))}): ${ctx}`
     );
   }
   if (typeof env.deleted !== "boolean" || env.record === null || typeof env.record !== "object") {
@@ -1074,7 +1688,7 @@ function recordFromNew(ref, rec, now, token) {
     retention: rec.retention,
     residency: rec.residency,
     summary: rec.summary,
-    keptGens: rec.keptGens,
+    knownGens: rec.knownGens,
     // A new row has no holder: a lease is written only against a row that already exists.
     leases: void 0,
     createdAt: now,
@@ -1089,32 +1703,32 @@ function assertStoredRecordShape(r, ctx) {
   }
   if (r.currentGen !== null && (!Number.isSafeInteger(r.currentGen) || r.currentGen < 0)) {
     throw new IntegrityError(
-      `registry record has an invalid currentGen (${shown(r.currentGen)}): ${ctx}`
+      `registry record has an invalid currentGen (${shown3(r.currentGen)}): ${ctx}`
     );
   }
   if (!STATUSES.includes(r.status)) {
-    throw new IntegrityError(`registry record has an unknown status (${shown(r.status)}): ${ctx}`);
+    throw new IntegrityError(`registry record has an unknown status (${shown3(r.status)}): ${ctx}`);
   }
   const declared = RECORD_FIELDS;
   const extra = Object.keys(r).filter((k) => !declared.includes(k));
   if (extra.length > 0) {
     throw new IntegrityError(
-      `registry record has fields a schema-${REGISTRY_SCHEMA_VERSION} row does not declare (${shown(extra.join(", "))}): ${ctx}`
+      `registry record has fields a schema-${REGISTRY_SCHEMA_VERSION} row does not declare (${shown3(extra.join(", "))}): ${ctx}`
     );
   }
   if (r.keyId !== void 0 && typeof r.keyId !== "string") {
     throw new IntegrityError(`registry record has an invalid keyId: ${ctx}`);
   }
-  validateWrappedDeks(r.wrappedDeks, true);
+  validateWrappedDeks(r.wrappedDeks, "stored");
   for (const field of ["retention", "residency"]) {
     const meta = r[field];
     if (meta !== void 0 && (meta === null || typeof meta !== "object" || Array.isArray(meta))) {
       throw new IntegrityError(`registry record has a non-object ${field}: ${ctx}`);
     }
   }
-  validateSummary(r.summary, true, ctx);
-  validateKeptGens(r.keptGens, true, ctx);
-  validateLeases(r.leases, true, ctx);
+  validateSummary(r.summary, "stored", ctx);
+  validateKnownGens(r.knownGens, "stored", ctx);
+  validateLeases(r.leases, "stored", ctx);
 }
 function applyRegistryPatch(prev, patch, now, token) {
   const currentGen = "currentGen" in patch ? patch.currentGen ?? null : prev.currentGen;
@@ -1128,12 +1742,12 @@ function applyRegistryPatch(prev, patch, now, token) {
     const kept = currentGen === prev.currentGen ? prev.summary : void 0;
     summary = kept !== void 0 && summaryAgreesWithKeys(kept, wrappedDeks) ? kept : void 0;
   }
-  let keptGens;
-  if ("keptGens" in patch) {
-    validateKeptGensBelow(patch.keptGens, currentGen);
-    keptGens = patch.keptGens;
+  let knownGens;
+  if ("knownGens" in patch) {
+    validateKnownGensFit(patch.knownGens, currentGen, summary);
+    knownGens = patch.knownGens;
   } else {
-    keptGens = currentGen === prev.currentGen ? prev.keptGens : void 0;
+    knownGens = currentGen === prev.currentGen ? prev.knownGens : void 0;
   }
   let leases;
   if ("leases" in patch) {
@@ -1156,7 +1770,7 @@ function applyRegistryPatch(prev, patch, now, token) {
     retention: "retention" in patch ? patch.retention : prev.retention,
     residency: "residency" in patch ? patch.residency : prev.residency,
     summary,
-    keptGens,
+    knownGens,
     leases,
     createdAt: prev.createdAt,
     updatedAt: now,
@@ -1186,6 +1800,7 @@ function entropyIsAvailable(entropy) {
 export {
   CloudRoaringError,
   ValidationError,
+  CONTENTION_NEXT_STEP,
   WriteConflictError,
   IntegrityError,
   NotFoundError,
@@ -1197,19 +1812,24 @@ export {
   BudgetExceededError,
   KeyUnavailableError,
   TransientError,
-  isCloudRoaringError,
   isWriteConflictError,
   isTransientError,
-  isLeaseExpiredError,
-  isStaleOperandError,
-  isLeaseLimitError,
   isNotFoundError,
   isIntegrityError,
   isValidationError,
-  isUnsupportedError,
-  isCapabilityError,
-  isBudgetExceededError,
   isKeyUnavailableError,
+  errorKind,
+  requireInteger,
+  requirePositiveInteger,
+  requireFiniteNumber,
+  U32_MAX,
+  CHUNK_COUNT,
+  isBadIdError,
+  splitId,
+  MAX_REMAINDER,
+  joinId,
+  mapWithConcurrency,
+  boundedAll,
   PREAMBLE_BYTES,
   FOOTER_BYTES,
   encodeNameForKey,
@@ -1225,19 +1845,19 @@ export {
   validateUserRef,
   validateChunkKeyOrder,
   validateChunkRef,
-  mapWithConcurrency,
+  validateChunkKey,
   assertRegistryCanWrite,
   STORAGE_BACKEND,
   brandAsBackend,
   isStorageBackend,
   MAX_METADATA_BYTES,
-  canonicalMetadataJson,
   metadataBytes,
   copiedMetadata,
   metadataFromBytes,
   sizePart,
   fingerprintFor,
   fingerprintParts,
+  footerCrcOf,
   compactFingerprint,
   incarnationOf,
   incarnationField,
@@ -1246,6 +1866,19 @@ export {
   renewsPointer,
   renewPointer,
   pointerIdOf,
+  aadFor,
+  sameKeys,
+  sizeOfFingerprint,
+  usableSummary,
+  summaryAgrees,
+  metadataToCarry,
+  summaryOf,
+  ownSummary,
+  DEFAULT_RETRY_POLICY,
+  jitteredWait,
+  retryRead,
+  checkedRetryPolicy,
+  withRetry,
   MAX_LEASE_MS,
   LEASE_SKEW_MS,
   MAX_LEASES_PER_SEGMENT,
@@ -1257,9 +1890,19 @@ export {
   leaseChurn,
   takeLease,
   releaseLease,
-  MAX_KEPT_GENERATIONS,
-  usableKeptGens,
-  nextKept,
+  knownGensShapeFault,
+  ascending,
+  MAX_STORED_KNOWN_GENERATIONS,
+  usableKnownGens,
+  windowOf,
+  KNOWN_SPAN,
+  keptWindow,
+  nextKnown,
+  rollbackKnown,
+  pruneKnown,
+  describingKnown,
+  isFullLedger,
+  fallbackBound,
   validateNewRegistryRecord,
   validateRegistryPatch,
   serializeRegistryEnvelope,
@@ -1274,6 +1917,10 @@ export {
   entropyIsAvailable,
   DEFAULT_NAMESPACE,
   namespaceKeyPart,
-  namespacePathPart
+  namespacePathPart,
+  refuseUnknownOptions,
+  checkNow,
+  requirePositiveInt,
+  requireBool
 };
-//# sourceMappingURL=chunk-YSC7NJWV.js.map
+//# sourceMappingURL=chunk-OSU7W2Y3.js.map