@cloudbitmaps/core 0.22.0 → 0.23.0

package/README.md

@@ -7,6 +7,8 @@ when you install the two packages you want. Install those instead:
 pnpm add @cloudbitmaps/roaring @cloudbitmaps/s3   # the store, and the storage you have (or /gcs, or /azure-blob)
 ```
 
+Install the same version of every `@cloudbitmaps/*` package: they release together, and each pins the exact version of `core` it was built with.
+
 `roaring` needs its one install script to fetch its native binary, and newer clients run a dependency's script only if you allow it. Allow it before you install:
 
 - **npm 12:** add `{ "allowScripts": { "roaring": true } }` to your `package.json`. Without it the install exits 0 and the package throws at `import`. npm 11 runs the script but warns until you allow it the same way.
@@ -18,7 +20,7 @@ pnpm add @cloudbitmaps/roaring @cloudbitmaps/s3   # the store, and the storage y
 
 Depend on `@cloudbitmaps/core` directly only to write a driver, through `@cloudbitmaps/core/driver-kit`.
 
-> **The main entry of this package is internal.** It is the engine `@cloudbitmaps/roaring` and the driver packages are built on, and it is outside the stability promise: it can change in any minor release, and a change to it gets no CHANGELOG Breaking entry. Install `@cloudbitmaps/roaring` and a driver. The public entry here is `@cloudbitmaps/core/driver-kit`, the contract for writing a driver.
+> **The main entry of this package, and `@cloudbitmaps/core/node`, are internal.** The main entry is the engine `@cloudbitmaps/roaring` and the driver packages are built on, and `/node` holds the backends and keystore that need a Node builtin. Both are outside the stability promise: they can change in any minor release, and a change to either gets no CHANGELOG Breaking entry. Install `@cloudbitmaps/roaring` and a driver. The public entry here is `@cloudbitmaps/core/driver-kit`, the contract for writing a driver.
 
 > **ESM-only, Node ≥ 22.12.** Use `import`; for `require()`, Jest and TypeScript, see
 > [CommonJS, Jest and TypeScript](https://github.com/cloudbitmaps/cloudbitmaps/blob/main/docs/guide/getting-started.md#commonjs-jest-and-typescript).
@@ -29,7 +31,7 @@ Depend on `@cloudbitmaps/core` directly only to write a driver, through `@cloudb
 
 The codec-agnostic cloud engine: a bounded in-memory cache over immutable `.crbm` objects, chunk-skipping
 intersection, the segment registry, the write-once load-and-publish path, generation collection, encryption at rest
-and crypto-shred, erasure by rewrite, retention, and the in-memory and local-filesystem backends. It has **zero runtime
+and crypto-shred, erasure by rewrite, retention, and the in-memory and local-filesystem backends (exported from `@cloudbitmaps/core/node`, so the main entry imports no Node builtin). It has **zero runtime
 dependencies and no cloud SDK**. The cloud backends are their own packages, built against
 `@cloudbitmaps/core/driver-kit`, the declared contract a driver depends on. A third-party driver can use it too.
 
@@ -50,7 +52,8 @@ The `.crbm` storage path lives in `src/core/`, one module per concern. Arrows re
    publish.ts  crbm-write.ts  crbm-open.ts  <----  crbm-storage-source.ts     read path
 ```
 
-`publish.ts`, `crbm-write.ts` and `crbm-open.ts` import none of the others. Outside this group, `load.ts` imports
+`publish.ts`, `crbm-write.ts` and `crbm-open.ts` import none of the others. `bulk-load.ts` also imports
+`sorted-chunks.ts`, which cuts a sorted load's ids into chunks and imports none of them. Outside this group, `load.ts` imports
 `bulk-load.ts`, `publish.ts` and `crbm-open.ts`; `erase-id.ts` imports `publish.ts`, `crbm-write.ts` and
 `crbm-open.ts`; `rollback.ts` and `consistency.ts` import `crbm-open.ts`. `combine-many.ts`, `pinned-storage-source.ts`
 (types only) and the package entry import `crbm-storage-source.ts`.
@@ -58,8 +61,9 @@ The `.crbm` storage path lives in `src/core/`, one module per concern. Arrows re
 | File | Holds |
 |---|---|
 | `crbm-write.ts` | writing one immutable generation from in-memory bitmaps, from a stream or from already-encoded chunks |
+| `sorted-chunks.ts` | the chunks of a sorted load (`sorted: true`): ascending ids cut into one chunk at a time as they are read, each checked (a 32-bit id, not lower than the one before; a repeat skipped), the ids read once, and the first error they raise kept for the load to throw |
 | `publish.ts` | the forward-only pointer advance every write ends with, the lease patch, the refusal to point a keyed row at a cleartext generation, and the settling of a registry write that got no answer |
-| `bulk-load.ts` | the loader `load()` is built on, with its read-ahead: ids, a decoded bitmap or a combine's chunks in, made into chunks (ids bucketed, a bitmap split by its codec where the codec can, a combine's chunks checked), one generation written, and published when a registry is wired and the caller does not defer it; `load()` defers it and publishes through `publish.ts` after its guard |
+| `bulk-load.ts` | the loader `load()` is built on, with its read-ahead: ids, a decoded bitmap or a combine's chunks in, made into chunks (ids bucketed, a bitmap split by its codec where the codec can, a combine's chunks checked), one generation written, and published when a registry is wired and the caller does not defer it; `load()` defers it and publishes through `publish.ts` after its guard. Sorted ids are written through the streaming writer of `crbm-write.ts` while they are read, after the row, the number and the key are settled |
 | `known-generations.ts` | the row's ledger, `knownGens`: what a usable one is, the window a load collects by name, the cap, and the ledger a publish and a rollback write |
 | `ledger-seed.ts` | the first window of a ledger over a row that has none, read from the bucket |
 | `crbm-open.ts` | opening a stored generation without the cache: the blob reader over a driver object, the checked and noting opens, the identity checks that tie an open to the object it read, generation verification, and the rollback target open |

package/dist/chunk-7GT632UF.js

@@ -0,0 +1,641 @@
+import {
+  INCARNATION_TOKEN,
+  IntegrityError,
+  MAX_KNOWN_GENERATIONS,
+  MAX_LEASES_PER_SEGMENT,
+  MAX_METADATA_BYTES,
+  MAX_STORED_KNOWN_GENERATIONS,
+  MAX_STORED_LEASES,
+  MAX_SUMMARY_CARDINALITY,
+  UnsupportedError,
+  ValidationError,
+  canonicalMetadataJson,
+  encodeNameForKey,
+  encodeNameForPath,
+  fingerprintParts,
+  knownGensShapeFault,
+  refuseUnknownOptions,
+  renewsPointer,
+  requirePositiveInteger,
+  shown,
+  tailBytesFit
+} from "./chunk-MVUD4R72.js";
+
+// src/drivers/_shared/options.ts
+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);
+}
+var DELETE_OPTION_KEYS = ["ifVersion"];
+var WRITE_OPTION_KEYS = ["held", "onToken"];
+function checkDeleteOptions(options) {
+  if (options === void 0) return void 0;
+  refuseUnknownOptions("delete options", options, DELETE_OPTION_KEYS);
+  const { ifVersion } = options;
+  if (ifVersion !== void 0 && typeof ifVersion !== "string") {
+    throw new ValidationError(
+      `delete options: \`ifVersion\` must be a string; got ${shown(ifVersion)}`
+    );
+  }
+  return ifVersion;
+}
+function checkRegistryWriteOptions(options) {
+  if (options === void 0) return;
+  refuseUnknownOptions("write options", options, WRITE_OPTION_KEYS);
+  const { held, onToken } = options;
+  if (held !== void 0 && held !== null && typeof held !== "object") {
+    throw new ValidationError(
+      `write options: \`held\` must be a registry record or null; got ${shown(held)}`
+    );
+  }
+  if (onToken !== void 0 && typeof onToken !== "function") {
+    throw new ValidationError(
+      `write options: \`onToken\` must be a function; got ${shown(onToken)}`
+    );
+  }
+}
+
+// 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/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 BASE64 = /^(?:[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" || !BASE64.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 ${shown2(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 ${shown2(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, shown2);
+  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) {
+  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");
+  const list = value;
+  const max = MAX_STORED_LEASES;
+  if (list.length > max) fail(`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");
+    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)})`);
+      }
+    }
+    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 (${shown2(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 (${shown2(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 shown2(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 (${shown2(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 (${shown2(r.currentGen)}): ${ctx}`
+    );
+  }
+  if (!STATUSES.includes(r.status)) {
+    throw new IntegrityError(`registry record has an unknown status (${shown2(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 (${shown2(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}`);
+    }
+  }
+  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}`);
+    }
+  } 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"
+    );
+  }
+  return c.getRandomValues(new Uint8Array(length));
+};
+function entropyIsAvailable(entropy) {
+  return entropy !== webCryptoEntropy || webCrypto() !== void 0;
+}
+
+export {
+  checkNow,
+  requirePositiveInt,
+  checkDeleteOptions,
+  checkRegistryWriteOptions,
+  validateNewRegistryRecord,
+  validateRegistryPatch,
+  serializeRegistryEnvelope,
+  drawIncarnation,
+  drawWrite,
+  nextRegistryToken,
+  newIncarnationToken,
+  parseRegistryEnvelope,
+  recordFromNew,
+  applyRegistryPatch,
+  webCryptoEntropy,
+  entropyIsAvailable,
+  DEFAULT_NAMESPACE,
+  namespaceKeyPart,
+  namespacePathPart
+};
+//# sourceMappingURL=chunk-7GT632UF.js.map