@cloudbitmaps/core 0.22.0 → 0.23.0

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

@@ -5,6 +5,7 @@ var NAMES = /* @__PURE__ */ new WeakMap();
 var CloudRoaringError = class extends Error {
   /** Cross-bundle brand — see {@link errorKind}. Non-enumerable-ish (symbol key ⇒ not in JSON). */
   [ERROR_BRAND] = true;
+  /** Builds the error from `message`, and sets `name` to the class's name as written. */
   constructor(message) {
     super(message);
     this.name = NAMES.get(new.target) ?? new.target.name;
@@ -24,6 +25,7 @@ var LeaseExpiredError = class extends CloudRoaringError {
   until;
   /** `'expired'` when the clock reached `until`, `'released'` after `release()`. */
   reason;
+  /** Builds the error from its `message`, the epoch-ms the lease ran until, and why it ended. */
   constructor(message, until, reason) {
     super(message);
     this.until = until;
@@ -33,11 +35,13 @@ var LeaseExpiredError = class extends CloudRoaringError {
 var LeaseLimitError = class extends CloudRoaringError {
 };
 var StaleOperandError = class extends CloudRoaringError {
+  /** The stable code `'stale-operand'`, to match on. */
   code = "stale-operand";
   /** The operand's name in the call that found it stale. */
   operand;
   /** Why it is stale. */
   reason;
+  /** Builds the error from its `message`, the operand's name and why it is stale. */
   constructor(message, operand, reason) {
     super(message);
     this.operand = operand;
@@ -58,6 +62,7 @@ var BudgetExceededError = class extends CloudRoaringError {
    * lower bound on the resident bytes it needs (`'maxBufferedBytes'`), or `limit + 1` (`'maxScanSegments'`).
    */
   spent;
+  /** Builds the error from its `message` and the `option`, `limit` and `spent` it reports. */
   constructor(message, details) {
     super(message);
     this.option = details.option;
@@ -70,6 +75,7 @@ var KeyUnavailableError = class extends CloudRoaringError {
 var TransientError = class extends CloudRoaringError {
   /** A second brand so a transient fault is classifiable cross-bundle. */
   [TRANSIENT_BRAND] = true;
+  /** Builds the error from `message`; `options.cause`, when given, is kept as `cause`. */
   constructor(message, options) {
     super(message);
     if (options && "cause" in options) this.cause = options.cause;
@@ -97,6 +103,15 @@ function isCloudRoaringError(err) {
 function isWriteConflictError(err) {
   return isCloudRoaringError(err) && err.name === "WriteConflictError";
 }
+var UNSETTLED_BRAND = /* @__PURE__ */ Symbol.for("cloudbitmaps.error.unsettled-conflict");
+function unsettledConflict(message) {
+  const err = new WriteConflictError(message);
+  Object.defineProperty(err, UNSETTLED_BRAND, { value: true });
+  return err;
+}
+function isUnsettledConflict(err) {
+  return isWriteConflictError(err) && hasBrand(err, UNSETTLED_BRAND);
+}
 function isTransientError(err) {
   return hasBrand(err, TRANSIENT_BRAND);
 }
@@ -134,39 +149,6 @@ function errorKind(err) {
   return typeof name === "string" && Object.hasOwn(KIND_NAMES, name) ? name : "CloudRoaringError";
 }
 
-// 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);
-}
-
 // src/core/check.ts
 function shown(value) {
   if (typeof value === "string") return JSON.stringify(value);
@@ -190,6 +172,11 @@ function requireInteger(value, bounds) {
   }
   return value;
 }
+function checkRequireEncryption(value) {
+  if (value !== void 0 && typeof value !== "boolean") {
+    throw new ValidationError(`requireEncryption must be a boolean; got ${shown(value)}`);
+  }
+}
 function requirePositiveInteger(value, what) {
   return requireInteger(value, { min: 1, what });
 }
@@ -202,69 +189,71 @@ function requireFiniteNumber(value, bounds) {
   }
   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 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 boundedAll(items, limit, fn) {
-  try {
-    requirePositiveInteger(limit, "concurrency limit");
-  } catch (err) {
-    return Promise.reject(err);
+function requireBool(name, value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "boolean") {
+    throw new ValidationError(`${name} must be a boolean; got ${shown(value)}`);
   }
-  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 value;
+}
+function requireNonEmptyString(name, value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new ValidationError(
+      `${name} must be a non-empty string; got ${typeof value === "string" ? "an empty string" : shown(value)}`
+    );
   }
-  return Promise.all(calls);
+  return value;
 }
-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/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 refusalOfId(id) {
+  return badId(id);
+}
+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);
 }
 
 // src/core/name-codec.ts
@@ -359,6 +348,7 @@ function validatePart(value, field) {
     );
   }
 }
+var REF_KEYS = ["segment", "namespace", "currentGen", "status"];
 function requireRefObject(ref, hint = "") {
   if (typeof ref !== "object" || ref === null) {
     throw new ValidationError(`a segment ref is an object such as { segment: 'name' }${hint}`);
@@ -366,6 +356,7 @@ function requireRefObject(ref, hint = "") {
 }
 function validateSegmentRef(ref) {
   requireRefObject(ref);
+  refuseUnknownKeys(ref);
   validatePart(ref.segment, "segment");
   if (ref.namespace !== void 0) validatePart(ref.namespace, "namespace");
 }
@@ -381,8 +372,56 @@ function validateUserNamespace(namespace) {
     );
   }
 }
-function validateUserRef(ref) {
+var PORT_KEYS = [
+  "generation",
+  "chunkKey",
+  "wrappedDeks",
+  "keyId",
+  "retention",
+  "residency",
+  "summary",
+  "knownGens",
+  "leases",
+  "createdAt",
+  "updatedAt",
+  "token",
+  "pointerId"
+];
+var SEGMENT_HANDLE_MARK = /* @__PURE__ */ Symbol.for("cloudbitmaps.roaring.segment/1");
+function unknownKeysOf(ref, extraKeys) {
+  return Object.keys(ref).filter(
+    (k) => !REF_KEYS.includes(k) && !extraKeys.includes(k)
+  );
+}
+function refuseUnknownKeys(ref) {
+  const unknown = unknownKeysOf(ref, PORT_KEYS);
+  if (unknown.length === 0) return;
+  const list = unknown.map((k) => `"${k}"`).join(", ");
+  throw new ValidationError(
+    `a driver port: unknown ${unknown.length === 1 ? "key" : "keys"} ${list} in the segment ref; it takes { segment, namespace } and a generation key's \`generation\`, a chunk ref's \`chunkKey\`, a \`segments()\` row's \`currentGen\` and \`status\`, or a registry row's own fields (a segment addressed without its namespace is a different segment)`
+  );
+}
+function refuseUnknownRefKeys(ref, verb, extraKeys = []) {
+  if (ref[SEGMENT_HANDLE_MARK] === true) {
+    throw new ValidationError(
+      `${verb}: a segment handle is not a ref; pass { segment, namespace }`
+    );
+  }
+  if (Array.isArray(ref)) {
+    throw new ValidationError(
+      `${verb}: a segment ref is an object such as { segment: 'name' }, not an array`
+    );
+  }
+  const unknown = unknownKeysOf(ref, extraKeys);
+  if (unknown.length === 0) return;
+  const list = unknown.map((k) => `"${k}"`).join(", ");
+  throw new ValidationError(
+    `${verb}: unknown ${unknown.length === 1 ? "key" : "keys"} ${list} in the segment ref; a ref takes { segment, namespace } (and a \`segments()\` row's \`currentGen\` and \`status\`, which are read for nothing); a segment addressed without its namespace is a different segment`
+  );
+}
+function validateUserRef(ref, verb, extraKeys = []) {
   requireRefObject(ref, "; store.segment() takes the bare name");
+  if (verb !== void 0) refuseUnknownRefKeys(ref, verb, extraKeys);
   validatePart(ref.segment, "segment");
   if (ref.namespace !== void 0) validateUserNamespace(ref.namespace);
 }
@@ -445,6 +484,22 @@ function isStorageBackend(value) {
   return typeof value === "object" && value !== null && value[STORAGE_BACKEND_BRAND] === true;
 }
 
+// src/core/token.ts
+var INCARNATION_TOKEN = /^([0-9a-f]{32})\.(0|[1-9]\d*)\.([0-9a-f]{16})$/;
+function incarnationOf(token) {
+  return INCARNATION_TOKEN.exec(token)?.[1];
+}
+function incarnationField(token) {
+  const incarnation = token === void 0 ? void 0 : incarnationOf(token);
+  return incarnation === void 0 ? {} : { incarnation };
+}
+function sameIncarnation(a, b) {
+  const ia = incarnationOf(a.token);
+  const ib = incarnationOf(b.token);
+  if (ia !== void 0 || ib !== void 0) return ia === ib;
+  return a.createdAt === b.createdAt;
+}
+
 // src/core/pointer-id.ts
 var RESOLVED_FIELDS = [
   "currentGen",
@@ -468,6 +523,11 @@ function pointerIdOf(row) {
   }
   return pointerId;
 }
+function pointerSetBy(now, before, generation, sent) {
+  if (now === null || now.status === "destroyed" || now.currentGen !== generation) return false;
+  if (before !== null && !sameIncarnation(before, now)) return false;
+  return sent.has(now.pointerId);
+}
 
 // src/core/crypto.ts
 var UTF82 = new TextEncoder();
@@ -560,22 +620,6 @@ async function withRetry(op, policy, deps) {
   throw lastErr;
 }
 
-// src/core/token.ts
-var INCARNATION_TOKEN = /^([0-9a-f]{32})\.(0|[1-9]\d*)\.([0-9a-f]{16})$/;
-function incarnationOf(token) {
-  return INCARNATION_TOKEN.exec(token)?.[1];
-}
-function incarnationField(token) {
-  const incarnation = token === void 0 ? void 0 : incarnationOf(token);
-  return incarnation === void 0 ? {} : { incarnation };
-}
-function sameIncarnation(a, b) {
-  const ia = incarnationOf(a.token);
-  const ib = incarnationOf(b.token);
-  if (ia !== void 0 || ib !== void 0) return ia === ib;
-  return a.createdAt === b.createdAt;
-}
-
 // src/core/leases.ts
 var MAX_LEASE_MS = 14 * 864e5;
 var LEASE_SKEW_MS = 6e4;
@@ -742,53 +786,6 @@ async function releaseLease(ref, deps, holder) {
   );
 }
 
-// src/drivers/_shared/keys.ts
-var DEFAULT_NAMESPACE = "_default";
-function namespaceKeyPart(namespace) {
-  return namespace === void 0 ? DEFAULT_NAMESPACE : encodeNameForKey(namespace);
-}
-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;
@@ -1067,35 +1064,6 @@ function ownSummary(ref, generation, description, aead) {
   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;
 
@@ -1248,553 +1216,33 @@ function leasedByRow(record) {
   return new Set((record.leases ?? []).map((e) => e.generation));
 }
 
-// src/drivers/_shared/registry.ts
-var STATUSES = ["active", "destroyed"];
-var RECORD_FIELDS = [
-  "namespace",
-  "segment",
-  "currentGen",
-  "wrappedDeks",
-  "keyId",
-  "status",
-  "retention",
-  "residency",
-  "summary",
-  "createdAt",
-  "updatedAt",
-  "token",
-  "knownGens",
-  "leases",
-  "pointerId"
-];
-var DRIVER_MANAGED = ["token", "pointerId"];
-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 SEALED_SUMMARY_MIN_BYTES = 12 + 8 + 8 + 4 + 4 + 16;
-var SEALED_SUMMARY_MAX_BYTES = SEALED_SUMMARY_MIN_BYTES + MAX_METADATA_BYTES;
-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) {
-    throw new ValidationError(
-      `currentGen must be a non-negative safe integer or null (no Storage generation yet); got ${gen}`
-    );
-  }
-}
-function validatePatchGeneration(patch) {
-  if (!("currentGen" in patch)) return;
-  if (patch.currentGen === void 0) {
-    throw new ValidationError(
-      `currentGen was present in the patch but undefined. Pass \`null\` to clear the pointer (the segment has no Storage generation), or omit the key to leave it unchanged \u2014 an undefined value is refused because it would un-publish the segment's Storage data.`
-    );
-  }
-  validateGeneration(patch.currentGen);
-}
-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;
-  if (meta === null || typeof meta !== "object" || Array.isArray(meta)) {
-    throw new ValidationError(
-      `${field} must be a plain object (got ${meta === null ? "null" : typeof meta})`
-    );
-  }
-  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, origin) {
-  if (value === void 0) return;
-  const fail = (msg) => {
-    throw origin === "stored" ? 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`);
-  }
-}
-var BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-function base64PadBitsAreZero(text) {
-  const pad = text.endsWith("==") ? 2 : text.endsWith("=") ? 1 : 0;
-  if (pad === 0) return true;
-  const last = BASE64_ALPHABET.indexOf(text[text.length - pad - 1]);
-  return pad === 2 ? (last & 15) === 0 : (last & 3) === 0;
-}
-function validateSummary(value, origin, ctx) {
-  if (value === void 0) return void 0;
-  const fail = (msg) => {
-    const where = ctx === void 0 ? "" : `: ${ctx}`;
-    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(
-      `must be an object (got ${value === null ? "null" : Array.isArray(value) ? "an array" : typeof value})`
-    );
-  }
-  const s = value;
-  const keys = Object.keys(s);
-  const isSealed = keys.includes("sealed");
-  const allowed = isSealed ? ["generation", "sealed"] : ["generation", "cardinality", "fingerprint", "tailBytes", "metadata"];
-  const extra = keys.filter((k) => !allowed.includes(k));
-  if (extra.length > 0) {
-    fail(
-      `has fields its ${isSealed ? "sealed" : "clear"} shape does not declare (${extra.join(", ")})`
-    );
-  }
-  const generation = s.generation;
-  if (!Number.isSafeInteger(generation) || generation < 0) {
-    fail(`generation must be a non-negative safe integer (got ${String(generation)})`);
-  }
-  if (isSealed) {
-    const sealed = s.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, fingerprint and tail size, a tag, and metadata up to its cap)`
-      );
-    }
-    return Object.freeze({ generation, sealed: text });
-  }
-  const n = s.cardinality;
-  if (!Number.isInteger(n) || n < 0 || n > MAX_SUMMARY_CARDINALITY) {
-    fail(`cardinality must be an integer from 0 to 2^32 (got ${String(n)})`);
-  }
-  const fingerprint = s.fingerprint;
-  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(
-      `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,
-      tailBytes
-    });
-  }
-  const canonical = canonicalMetadataJson(s.metadata, fail);
-  if (canonical === "{}") fail("metadata is empty; a generation without metadata carries none");
-  if (origin === "stored") return s;
-  const metadata = Object.freeze(JSON.parse(canonical));
-  return Object.freeze({
-    generation,
-    cardinality: n,
-    fingerprint,
-    tailBytes,
-    metadata
-  });
-}
-function validateSummaryNames(summary, currentGen) {
-  if (summary !== void 0 && summary.generation !== currentGen) {
-    throw new ValidationError(
-      `summary describes generation ${summary.generation}, but the row points at ${String(currentGen)}`
-    );
-  }
-}
-function summaryAgreesWithKeys(summary, wrappedDeks) {
-  return "sealed" in summary === (wrappedDeks !== void 0);
-}
-function validateSummaryKeys(summary, wrappedDeks) {
-  if (summary !== void 0 && !summaryAgreesWithKeys(summary, wrappedDeks)) {
-    throw new ValidationError(
-      wrappedDeks === void 0 ? "summary is sealed, but the row has no wrapped keys to open it with" : "summary is in the clear, but the row is encrypted: an encrypted segment's summary must be sealed"
-    );
-  }
-}
-function validateKnownGens(value, origin, ctx) {
-  if (value === void 0) return void 0;
-  const fail = (msg) => {
-    const where = ctx === void 0 ? "" : `: ${ctx}`;
-    throw origin === "stored" ? new IntegrityError(`registry record knownGens: ${msg}${where}`) : new ValidationError(`knownGens: ${msg}`);
-  };
-  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 origin === "stored" ? out : Object.freeze(out);
-}
-var HOLDER = /^[0-9a-f]{16}$/;
-var LEASE_ENTRY_KEYS = ["holder", "generation", "until"];
-function validateLeases(value, origin, ctx) {
+// src/core/known-generations-shape.ts
+var ENTRY_KEYS = ["generation", "footerCrc"];
+function knownGensShapeFault(value, max, show = String) {
   if (value === void 0) return void 0;
-  const fail = (msg) => {
-    const where = ctx === void 0 ? "" : `: ${ctx}`;
-    throw origin === "stored" ? new IntegrityError(`registry record leases: ${msg}${where}`) : new ValidationError(`leases: ${msg}`);
-  };
-  if (!Array.isArray(value)) fail("must be an array");
+  if (!Array.isArray(value)) return "must be an array";
   const list = value;
-  const max = MAX_STORED_LEASES;
-  if (list.length > max) fail(`has ${list.length} entries, cap ${max}`);
+  if (list.length > max) return `has ${list.length} entries, cap ${max}`;
   const seen = /* @__PURE__ */ new Set();
-  const out = [];
   for (const e of list) {
-    if (typeof e !== "object" || e === null || Array.isArray(e)) fail("an entry must be an object");
+    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) => !LEASE_ENTRY_KEYS.includes(k));
-    if (extra.length > 0) fail(`an entry carries an undeclared field (${extra.join(", ")})`);
-    const { holder, generation, until } = entry;
-    if (typeof holder !== "string" || !HOLDER.test(holder)) {
-      fail("a holder must be 16 lowercase hex digits");
-    }
-    if (seen.has(holder)) fail("holders must be unique");
-    seen.add(holder);
-    for (const [name, n] of [
-      ["generation", generation],
-      ["until", until]
-    ]) {
-      if (!Number.isSafeInteger(n) || n < 0) {
-        fail(`${name} must be a non-negative safe integer (got ${String(n)})`);
-      }
+    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(", "))})`;
     }
-    out.push(
-      origin === "stored" ? entry : Object.freeze({
-        holder,
-        generation,
-        until
-      })
-    );
-  }
-  if (origin === "stored") return out;
-  return out.length === 0 ? void 0 : Object.freeze(out);
-}
-function validateLeasesPointer(leases, currentGen) {
-  if (leases !== void 0 && leases.length > 0 && currentGen === null) {
-    throw new ValidationError("leases: a row with no pointer has no generation to lease");
-  }
-}
-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(
-      `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})`
-    );
-  }
-  if (summary !== void 0 && summary.generation === currentGen && "fingerprint" in summary && fingerprintParts(summary.fingerprint)?.footerCrc !== last.footerCrc) {
-    throw new ValidationError(
-      `knownGens records footerCrc ${last.footerCrc} for generation ${currentGen}, but the summary's fingerprint ${summary.fingerprint} carries another: both describe the one current object`
-    );
-  }
-}
-function refuseDriverManaged(write, what) {
-  const named = DRIVER_MANAGED.filter((field) => field in write);
-  if (named.length > 0) {
-    throw new ValidationError(
-      `${what} names ${named.join(" and ")}, which the registry sets on every write and a caller never does`
-    );
-  }
-}
-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, "caller");
-  validateGovernance(rec.retention, "retention");
-  validateGovernance(rec.residency, "residency");
-  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 { ...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, "caller");
-  if ("retention" in patch) validateGovernance(patch.retention, "retention");
-  if ("residency" in patch) validateGovernance(patch.residency, "residency");
-  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, "caller") };
-}
-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 (${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 (steps: https://github.com/cloudbitmaps/cloudbitmaps/blob/main/CHANGELOG.md, the Breaking entry on registry schema 5): ${ctx}`
-    );
-  }
-  if (raw > REGISTRY_SCHEMA_VERSION) {
-    throw new UnsupportedError(
-      `registry row schemaVersion ${raw} is newer than this build reads (v${REGISTRY_SCHEMA_VERSION}): ${ctx}`
-    );
-  }
-  return raw;
-}
-function serializeRegistryEnvelope(env) {
-  return JSON.stringify({
-    schemaVersion: REGISTRY_SCHEMA_VERSION,
-    deleted: env.deleted,
-    record: env.record
-  });
-}
-var INCARNATION_BYTES = 16;
-var WRITE_BYTES = 8;
-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 (${shown3(JSON.stringify(token))}): ${ctx}`
-    );
-  }
-  const counter = Number(match[2]);
-  if (!Number.isSafeInteger(counter)) {
-    throw new IntegrityError(`registry row ${what}'s counter is out of safe-integer range: ${ctx}`);
-  }
-  return { incarnation: match[1], counter };
-}
-function checkPointerId(pointerId, token, ctx) {
-  const parts = tokenParts(pointerId, ctx, "pointerId");
-  if (parts.incarnation !== token.incarnation) {
-    throw new IntegrityError(
-      `registry row pointerId names another incarnation than its token: ${ctx}`
-    );
-  }
-  if (parts.counter > token.counter) {
-    throw new IntegrityError(`registry row pointerId is a write after its token: ${ctx}`);
-  }
-}
-function drawHex(entropy, bytes) {
-  const drawn = entropy(bytes);
-  if (!(drawn instanceof Uint8Array) || drawn.length !== bytes) {
-    throw new ValidationError(
-      `the registry's entropy source must return ${bytes} bytes as a Uint8Array`
-    );
-  }
-  let hex = "";
-  for (const b of drawn) hex += b.toString(16).padStart(2, "0");
-  return hex;
-}
-function drawIncarnation(entropy) {
-  return drawHex(entropy, INCARNATION_BYTES);
-}
-function drawWrite(entropy) {
-  return drawHex(entropy, WRITE_BYTES);
-}
-function nextRegistryToken(record, entropy) {
-  const { incarnation, counter } = tokenParts(record.token, record.segment);
-  return `${incarnation}.${counter + 1}.${drawWrite(entropy)}`;
-}
-function newIncarnationToken(entropy, tombstone) {
-  const counter = tombstone === void 0 ? 0 : tokenParts(tombstone.token, tombstone.segment).counter + 1;
-  return `${drawIncarnation(entropy)}.${counter}.${drawWrite(entropy)}`;
-}
-function shown3(v) {
-  const text = String(v);
-  return text.length > 64 ? `${text.slice(0, 64)}\u2026` : text;
-}
-function parseRegistryEnvelope(text, ctx, expected) {
-  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);
-  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 (${shown3(extra.join(", "))}): ${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}`);
-  }
-  checkPointerId(r.pointerId, tokenParts(r.token, ctx), ctx);
-  if (expected !== void 0 && (r.segment !== expected.segment || (r.namespace ?? void 0) !== (expected.namespace ?? void 0))) {
-    throw new IntegrityError(
-      `registry row names another segment than the one it is stored for: ${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,
-    status: rec.status ?? "active",
-    retention: rec.retention,
-    residency: rec.residency,
-    summary: rec.summary,
-    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,
-    updatedAt: now,
-    token,
-    pointerId: token
-  };
-}
-function assertStoredRecordShape(r, ctx) {
-  if (typeof r.segment !== "string" || typeof r.pointerId !== "string" || r.namespace !== void 0 && typeof r.namespace !== "string" || r.currentGen !== null && typeof r.currentGen !== "number" || typeof r.status !== "string" || typeof r.createdAt !== "number" || typeof r.updatedAt !== "number") {
-    throw new IntegrityError(`registry record is missing required fields: ${ctx}`);
-  }
-  if (r.currentGen !== null && (!Number.isSafeInteger(r.currentGen) || r.currentGen < 0)) {
-    throw new IntegrityError(
-      `registry record has an invalid currentGen (${shown3(r.currentGen)}): ${ctx}`
-    );
-  }
-  if (!STATUSES.includes(r.status)) {
-    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 (${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, "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}`);
+    const { generation, footerCrc } = entry;
+    if (!Number.isSafeInteger(generation) || generation < 0) {
+      return `a generation must be a non-negative safe integer (got ${show(generation)})`;
     }
-  }
-  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;
-  const wrappedDeks = "wrappedDeks" in patch ? patch.wrappedDeks : prev.wrappedDeks;
-  let summary;
-  if ("summary" in patch) {
-    validateSummaryNames(patch.summary, currentGen);
-    validateSummaryKeys(patch.summary, wrappedDeks);
-    summary = patch.summary;
-  } else {
-    const kept = currentGen === prev.currentGen ? prev.summary : void 0;
-    summary = kept !== void 0 && summaryAgreesWithKeys(kept, wrappedDeks) ? kept : void 0;
-  }
-  let knownGens;
-  if ("knownGens" in patch) {
-    validateKnownGensFit(patch.knownGens, currentGen, summary);
-    knownGens = patch.knownGens;
-  } else {
-    knownGens = currentGen === prev.currentGen ? prev.knownGens : void 0;
-  }
-  let leases;
-  if ("leases" in patch) {
-    leases = patch.leases;
-    validateLeasesPointer(leases, currentGen);
-    const most = Math.max(MAX_LEASES_PER_SEGMENT, prev.leases?.length ?? 0);
-    if (leases !== void 0 && leases.length > most) {
-      throw new ValidationError(`leases: has ${leases.length} entries, cap ${most}`);
+    if (!Number.isInteger(footerCrc) || footerCrc < 0 || footerCrc > 4294967295) {
+      return `a footerCrc must be an integer from 0 to 2^32 - 1 (got ${show(footerCrc)})`;
     }
-  } else {
-    leases = prev.leases;
-  }
-  return {
-    namespace: prev.namespace,
-    segment: prev.segment,
-    currentGen,
-    wrappedDeks,
-    keyId: "keyId" in patch ? patch.keyId : prev.keyId,
-    status: patch.status ?? prev.status,
-    retention: "retention" in patch ? patch.retention : prev.retention,
-    residency: "residency" in patch ? patch.residency : prev.residency,
-    summary,
-    knownGens,
-    leases,
-    createdAt: prev.createdAt,
-    updatedAt: now,
-    token,
-    pointerId: renewsPointer(patch) ? token : prev.pointerId
-  };
-}
-
-// src/drivers/_shared/entropy.ts
-function webCrypto() {
-  const c = globalThis.crypto;
-  return c !== void 0 && typeof c.getRandomValues === "function" ? c : void 0;
-}
-var webCryptoEntropy = (length) => {
-  const c = webCrypto();
-  if (c === void 0) {
-    throw new UnsupportedError(
-      "this runtime has no Web Crypto (crypto.getRandomValues), which a registry needs for the token of every row it writes: run on a runtime that has it"
-    );
+    if (seen.has(generation)) return `generation ${String(generation)} is repeated`;
+    seen.add(generation);
   }
-  return c.getRandomValues(new Uint8Array(length));
-};
-function entropyIsAvailable(entropy) {
-  return entropy !== webCryptoEntropy || webCrypto() !== void 0;
+  return void 0;
 }
 
 export {
@@ -1813,23 +1261,29 @@ export {
   KeyUnavailableError,
   TransientError,
   isWriteConflictError,
+  unsettledConflict,
+  isUnsettledConflict,
   isTransientError,
   isNotFoundError,
   isIntegrityError,
   isValidationError,
   isKeyUnavailableError,
   errorKind,
+  shown,
   requireInteger,
+  checkRequireEncryption,
   requirePositiveInteger,
   requireFiniteNumber,
+  refuseUnknownOptions,
+  requireBool,
+  requireNonEmptyString,
   U32_MAX,
   CHUNK_COUNT,
   isBadIdError,
+  refusalOfId,
   splitId,
   MAX_REMAINDER,
   joinId,
-  mapWithConcurrency,
-  boundedAll,
   PREAMBLE_BYTES,
   FOOTER_BYTES,
   encodeNameForKey,
@@ -1842,6 +1296,8 @@ export {
   RESERVED_NAMESPACE_PREFIX,
   isReservedNamespace,
   validateUserNamespace,
+  PORT_KEYS,
+  refuseUnknownRefKeys,
   validateUserRef,
   validateChunkKeyOrder,
   validateChunkRef,
@@ -1850,15 +1306,7 @@ export {
   STORAGE_BACKEND,
   brandAsBackend,
   isStorageBackend,
-  MAX_METADATA_BYTES,
-  metadataBytes,
-  copiedMetadata,
-  metadataFromBytes,
-  sizePart,
-  fingerprintFor,
-  fingerprintParts,
-  footerCrcOf,
-  compactFingerprint,
+  INCARNATION_TOKEN,
   incarnationOf,
   incarnationField,
   sameIncarnation,
@@ -1866,14 +1314,28 @@ export {
   renewsPointer,
   renewPointer,
   pointerIdOf,
+  pointerSetBy,
   aadFor,
   sameKeys,
+  MAX_METADATA_BYTES,
+  canonicalMetadataJson,
+  metadataBytes,
+  copiedMetadata,
+  metadataFromBytes,
+  sizePart,
+  fingerprintFor,
+  fingerprintParts,
+  footerCrcOf,
+  compactFingerprint,
+  MAX_SUMMARY_CARDINALITY,
+  tailBytesFit,
   sizeOfFingerprint,
   usableSummary,
   summaryAgrees,
   metadataToCarry,
   summaryOf,
   ownSummary,
+  ascending,
   DEFAULT_RETRY_POLICY,
   jitteredWait,
   retryRead,
@@ -1882,6 +1344,7 @@ export {
   MAX_LEASE_MS,
   LEASE_SKEW_MS,
   MAX_LEASES_PER_SEGMENT,
+  MAX_STORED_LEASES,
   UNANSWERED_RESENDS,
   UNANSWERED_BASE_MS,
   isLive,
@@ -1890,8 +1353,7 @@ export {
   leaseChurn,
   takeLease,
   releaseLease,
-  knownGensShapeFault,
-  ascending,
+  MAX_KNOWN_GENERATIONS,
   MAX_STORED_KNOWN_GENERATIONS,
   usableKnownGens,
   windowOf,
@@ -1903,24 +1365,6 @@ export {
   describingKnown,
   isFullLedger,
   fallbackBound,
-  validateNewRegistryRecord,
-  validateRegistryPatch,
-  serializeRegistryEnvelope,
-  drawIncarnation,
-  drawWrite,
-  nextRegistryToken,
-  newIncarnationToken,
-  parseRegistryEnvelope,
-  recordFromNew,
-  applyRegistryPatch,
-  webCryptoEntropy,
-  entropyIsAvailable,
-  DEFAULT_NAMESPACE,
-  namespaceKeyPart,
-  namespacePathPart,
-  refuseUnknownOptions,
-  checkNow,
-  requirePositiveInt,
-  requireBool
+  knownGensShapeFault
 };
-//# sourceMappingURL=chunk-OSU7W2Y3.js.map
+//# sourceMappingURL=chunk-MVUD4R72.js.map