@cloudbitmaps/core 0.11.2 → 0.12.0

package/dist/{chunk-5OMC5U7U.js → chunk-5W3XS2IU.js}

@@ -116,6 +116,9 @@ function decodeNameFromPath(encoded) {
 var CHUNK_KEY_MAX = 65535;
 var MAX_NAME_LENGTH = 256;
 var LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+function isWellFormedString(value) {
+  return !LONE_SURROGATE.test(value);
+}
 function encodedNameLength(value) {
   return Math.max(encodeNameForKey(value).length, encodeNameForPath(value).length);
 }
@@ -203,6 +206,13 @@ async function mapWithConcurrency(items, limit, fn) {
 }
 
 // src/core/ports.ts
+function assertRegistryCanWrite(registry, what) {
+  if (registry.capabilities().canWrite === false) {
+    throw new UnsupportedError(
+      `${what}: the registry reports it cannot write a row in this runtime (capabilities().canWrite is false), so nothing is written`
+    );
+  }
+}
 var STORAGE_BACKEND_BRAND = /* @__PURE__ */ Symbol.for("cloudbitmaps.storage-backend");
 var STORAGE_BACKEND = STORAGE_BACKEND_BRAND;
 function brandAsBackend(target) {
@@ -247,6 +257,96 @@ function namespacePathPart(namespace) {
   return namespace === void 0 ? DEFAULT_NAMESPACE : encodeNameForPath(namespace);
 }
 
+// src/core/metadata.ts
+var MAX_METADATA_BYTES = 1024;
+var MAX_METADATA_KEY_BYTES = 128;
+var utf8Length = (s) => new TextEncoder().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})`);
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (Object.prototype.toString.call(value) !== "[object Object]" || proto !== Object.prototype && proto !== null) {
+    fail("metadata must be a plain object, not an array, a Map, a boxed value or a class instance");
+  }
+  const entries = [];
+  const keys = Reflect.ownKeys(value);
+  for (const key of keys) {
+    if (typeof key !== "string") fail("metadata keys must be strings, not symbols");
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === void 0 || !("value" in descriptor) || descriptor.enumerable !== true) {
+      fail(`metadata key ${JSON.stringify(key)} must be an enumerable data property`);
+    }
+    if (key.length === 0) fail("metadata keys must be non-empty");
+    if (key === "__proto__") fail('metadata may not use the key "__proto__"');
+    if (!isWellFormedString(key)) fail("metadata keys must be well-formed UTF-16");
+    if (key.length * 3 > MAX_METADATA_KEY_BYTES) {
+      const keyBytes = utf8Length(key);
+      if (keyBytes > MAX_METADATA_KEY_BYTES) {
+        fail(`metadata key is ${keyBytes}B, over the ${MAX_METADATA_KEY_BYTES}B cap`);
+      }
+    }
+    const v = descriptor.value;
+    if (typeof v === "string") {
+      if (!isWellFormedString(v)) {
+        fail(`metadata value of ${JSON.stringify(key)} must be well-formed UTF-16`);
+      }
+    } else if (typeof v !== "number" || !Number.isFinite(v)) {
+      fail(`metadata value of ${JSON.stringify(key)} must be a string or a finite number`);
+    }
+    entries.push([key, v]);
+  }
+  entries.sort(([a], [b]) => a < b ? -1 : 1);
+  const json = `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${JSON.stringify(v)}`).join(",")}}`;
+  const bytes = utf8Length(json);
+  if (bytes > MAX_METADATA_BYTES) {
+    fail(`metadata is ${bytes}B as canonical JSON, over the ${MAX_METADATA_BYTES}B cap`);
+  }
+  return json;
+}
+function metadataBytes(value, fail) {
+  if (value === void 0) return void 0;
+  const json = canonicalMetadataJson(value, fail);
+  return json === "{}" ? void 0 : new TextEncoder().encode(json);
+}
+function copiedMetadata(value, fail) {
+  const bytes = metadataBytes(value, fail);
+  return bytes === void 0 ? void 0 : metadataFromBytes(bytes, fail);
+}
+function metadataFromBytes(bytes, fail) {
+  if (bytes.length > MAX_METADATA_BYTES) {
+    fail(`metadata is ${bytes.length}B, over the ${MAX_METADATA_BYTES}B cap`);
+  }
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    fail("metadata is not valid UTF-8");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    fail("metadata is not JSON");
+  }
+  const json = canonicalMetadataJson(parsed, fail);
+  if (json === "{}") fail("metadata is empty; a generation without metadata carries none");
+  if (json !== text) fail("metadata is not in canonical form");
+  return Object.freeze(parsed);
+}
+
+// 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 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/drivers/_shared/registry.ts
 var STATUSES = ["active", "destroyed"];
 var RECORD_FIELDS = [
@@ -258,14 +358,20 @@ var RECORD_FIELDS = [
   "status",
   "retention",
   "residency",
+  "summary",
   "createdAt",
   "updatedAt",
   "token"
 ];
+var SCHEMA_1_RECORD_FIELDS = RECORD_FIELDS.filter((f) => f !== "summary");
 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 + 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.isInteger(gen) || gen < 0) {
@@ -326,12 +432,93 @@ function validateWrappedDeks(value, isStored) {
       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, isStored, 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}`);
+  };
+  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", "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, 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)})`);
+  }
+  if (s.metadata === void 0) {
+    return Object.freeze({ generation, cardinality: n });
+  }
+  const canonical = canonicalMetadataJson(s.metadata, fail);
+  if (canonical === "{}") fail("metadata is empty; a generation without metadata carries none");
+  if (isStored) return s;
+  const metadata = Object.freeze(JSON.parse(canonical));
+  return Object.freeze({ generation, cardinality: n, 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 validateNewRegistryRecord(rec) {
   validateGeneration(rec.currentGen);
   if (rec.status !== void 0) validateStatus(rec.status);
   validateWrappedDeks(rec.wrappedDeks, false);
   validateGovernance(rec.retention, "retention");
   validateGovernance(rec.residency, "residency");
+  if (!("summary" in rec)) return rec;
+  const summary = validateSummary(rec.summary, false);
+  validateSummaryNames(summary, rec.currentGen);
+  validateSummaryKeys(summary, rec.wrappedDeks);
+  return { ...rec, summary };
 }
 function validateRegistryPatch(patch) {
   validatePatchGeneration(patch);
@@ -339,13 +526,16 @@ function validateRegistryPatch(patch) {
   if ("wrappedDeks" in patch) validateWrappedDeks(patch.wrappedDeks, false);
   if ("retention" in patch) validateGovernance(patch.retention, "retention");
   if ("residency" in patch) validateGovernance(patch.residency, "residency");
+  if (!("summary" in patch)) return patch;
+  return { ...patch, summary: validateSummary(patch.summary, false) };
 }
-var REGISTRY_SCHEMA_VERSION = 1;
+var REGISTRY_SCHEMA_VERSION = 2;
+var OLDEST_REGISTRY_SCHEMA_VERSION = 1;
 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) {
+  if (typeof raw !== "number" || !Number.isInteger(raw) || raw < OLDEST_REGISTRY_SCHEMA_VERSION) {
     throw new IntegrityError(`registry row has a malformed schemaVersion (${String(raw)}): ${ctx}`);
   }
   if (raw > REGISTRY_SCHEMA_VERSION) {
@@ -353,6 +543,7 @@ function assertRegistrySchemaVersion(raw, ctx) {
       `registry row schemaVersion ${raw} is newer than this build reads (v${REGISTRY_SCHEMA_VERSION}): ${ctx}`
     );
   }
+  return raw;
 }
 function serializeRegistryEnvelope(env) {
   return JSON.stringify({
@@ -361,15 +552,51 @@ function serializeRegistryEnvelope(env) {
     record: env.record
   });
 }
-function registryCounterOf(record) {
-  if (!/^(0|[1-9]\d*)$/.test(record.token)) {
-    throw new IntegrityError(`registry row token is not a canonical counter: ${record.token}`);
+var COUNTER_TOKEN = /^(0|[1-9]\d*)$/;
+var WRITTEN_COUNTER_TOKEN = /^(0|[1-9]\d*)\.([0-9a-f]{16})$/;
+var INCARNATION_BYTES = 16;
+var WRITE_BYTES = 8;
+function tokenParts(token, schemaVersion, ctx) {
+  const bare = schemaVersion === void 0 || schemaVersion === 1 ? COUNTER_TOKEN.exec(token) : null;
+  const written = schemaVersion === void 0 || schemaVersion >= 2 ? WRITTEN_COUNTER_TOKEN.exec(token) ?? INCARNATION_TOKEN.exec(token) : null;
+  const match = bare ?? written;
+  if (match === null) {
+    throw new IntegrityError(
+      `registry row token is not one a schema-${schemaVersion ?? REGISTRY_SCHEMA_VERSION} row holds (${JSON.stringify(token)}): ${ctx}`
+    );
   }
-  const n = Number(record.token);
-  if (!Number.isSafeInteger(n)) {
-    throw new IntegrityError(`registry row token is out of safe-integer range: ${record.token}`);
+  const born = match.length === 4;
+  const counter = Number(born ? match[2] : match[1]);
+  if (!Number.isSafeInteger(counter)) {
+    throw new IntegrityError(`registry row token's counter is out of safe-integer range: ${ctx}`);
   }
-  return n;
+  return { incarnation: born ? match[1] : void 0, counter };
+}
+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, void 0, record.segment);
+  const tail = `${counter + 1}.${drawWrite(entropy)}`;
+  return incarnation === void 0 ? tail : `${incarnation}.${tail}`;
+}
+function newIncarnationToken(entropy, tombstone) {
+  const counter = tombstone === void 0 ? 0 : tokenParts(tombstone.token, void 0, tombstone.segment).counter + 1;
+  return `${drawIncarnation(entropy)}.${counter}.${drawWrite(entropy)}`;
 }
 function parseRegistryEnvelope(text, ctx) {
   let parsed;
@@ -382,7 +609,7 @@ function parseRegistryEnvelope(text, ctx) {
     throw new IntegrityError(`registry row has a malformed envelope: ${ctx}`);
   }
   const env = parsed;
-  assertRegistrySchemaVersion(env.schemaVersion, ctx);
+  const schemaVersion = assertRegistrySchemaVersion(env.schemaVersion, ctx);
   const extra = Object.keys(env).filter((k) => !ENVELOPE_FIELDS.includes(k));
   if (extra.length > 0) {
     throw new IntegrityError(
@@ -393,10 +620,11 @@ function parseRegistryEnvelope(text, ctx) {
     throw new IntegrityError(`registry row has a malformed envelope: ${ctx}`);
   }
   const r = env.record;
-  assertStoredRecordShape(r, ctx);
+  assertStoredRecordShape(r, ctx, schemaVersion);
   if (typeof r.token !== "string") {
     throw new IntegrityError(`registry row is missing its token: ${ctx}`);
   }
+  tokenParts(r.token, schemaVersion, ctx);
   return { deleted: env.deleted, record: env.record };
 }
 function recordFromNew(ref, rec, now, token) {
@@ -409,12 +637,13 @@ function recordFromNew(ref, rec, now, token) {
     status: rec.status ?? "active",
     retention: rec.retention,
     residency: rec.residency,
+    summary: rec.summary,
     createdAt: now,
     updatedAt: now,
     token
   };
 }
-function assertStoredRecordShape(r, ctx) {
+function assertStoredRecordShape(r, ctx, schemaVersion = REGISTRY_SCHEMA_VERSION) {
   if (typeof r.segment !== "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}`);
   }
@@ -424,10 +653,11 @@ function assertStoredRecordShape(r, ctx) {
   if (!STATUSES.includes(r.status)) {
     throw new IntegrityError(`registry record has an unknown status (${r.status}): ${ctx}`);
   }
-  const extra = Object.keys(r).filter((k) => !RECORD_FIELDS.includes(k));
+  const declared = schemaVersion >= 2 ? RECORD_FIELDS : SCHEMA_1_RECORD_FIELDS;
+  const extra = Object.keys(r).filter((k) => !declared.includes(k));
   if (extra.length > 0) {
     throw new IntegrityError(
-      `registry record has fields it does not declare (${extra.join(", ")}): ${ctx}`
+      `registry record has fields a schema-${schemaVersion} row does not declare (${extra.join(", ")}): ${ctx}`
     );
   }
   if (r.keyId !== void 0 && typeof r.keyId !== "string") {
@@ -440,27 +670,54 @@ function assertStoredRecordShape(r, ctx) {
       throw new IntegrityError(`registry record has a non-object ${field}: ${ctx}`);
     }
   }
+  validateSummary(r.summary, true, 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;
+  }
   return {
     namespace: prev.namespace,
     segment: prev.segment,
-    // `'currentGen' in patch`, NOT `patch.currentGen ?? prev.currentGen`. `null` is a legal, meaningful value
-    // here (no Storage generation yet), and `??` treats it as absent — so the nullish form would silently ignore a
-    // patch that clears the pointer and leave the old generation in place. The same reason `wrappedDeks` and
-    // `keyId` below use presence: any field whose null is a *value* cannot be merged with `??`.
-    currentGen: "currentGen" in patch ? patch.currentGen ?? null : prev.currentGen,
-    wrappedDeks: "wrappedDeks" in patch ? patch.wrappedDeks : prev.wrappedDeks,
+    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,
     createdAt: prev.createdAt,
     updatedAt: now,
     token
   };
 }
 
+// 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 {
   CloudRoaringError,
   ValidationError,
@@ -491,18 +748,31 @@ export {
   validateUserRef,
   validateChunkRef,
   mapWithConcurrency,
+  assertRegistryCanWrite,
   STORAGE_BACKEND,
   brandAsBackend,
   isStorageBackend,
+  MAX_METADATA_BYTES,
+  canonicalMetadataJson,
+  metadataBytes,
+  copiedMetadata,
+  metadataFromBytes,
+  incarnationOf,
+  sameIncarnation,
   validateNewRegistryRecord,
   validateRegistryPatch,
   serializeRegistryEnvelope,
-  registryCounterOf,
+  drawIncarnation,
+  drawWrite,
+  nextRegistryToken,
+  newIncarnationToken,
   parseRegistryEnvelope,
   recordFromNew,
   applyRegistryPatch,
+  webCryptoEntropy,
+  entropyIsAvailable,
   DEFAULT_NAMESPACE,
   namespaceKeyPart,
   namespacePathPart
 };
-//# sourceMappingURL=chunk-5OMC5U7U.js.map
+//# sourceMappingURL=chunk-5W3XS2IU.js.map