@cloudbitmaps/core 0.1.0-rc.0

package/dist/dynamodb/index.cjs

@@ -0,0 +1,731 @@
+'use strict';
+
+var clientDynamodb = require('@aws-sdk/client-dynamodb');
+
+// src/drivers/dynamodb/warm.ts
+
+// src/core/errors.ts
+var ERROR_BRAND = /* @__PURE__ */ Symbol.for("cloud-roaring.error");
+var TRANSIENT_BRAND = /* @__PURE__ */ Symbol.for("cloud-roaring.error.transient");
+var CloudRoaringError = class extends Error {
+  /** Cross-bundle brand — see the predicates ({@link isCloudRoaringError}, …). Non-enumerable-ish (symbol key ⇒ not in JSON). */
+  [ERROR_BRAND] = true;
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var ValidationError = class extends CloudRoaringError {
+};
+var WriteConflictError = class extends CloudRoaringError {
+};
+var IntegrityError = class extends CloudRoaringError {
+};
+var UnsupportedError = class extends CloudRoaringError {
+};
+var TransientError = class extends CloudRoaringError {
+  /** A second brand so the whole transient subtree (incl. {@link TimeoutError}) is classifiable cross-bundle. */
+  [TRANSIENT_BRAND] = true;
+  constructor(message, options) {
+    super(message);
+    if (options && "cause" in options) this.cause = options.cause;
+  }
+};
+function hasBrand(err, brand) {
+  return typeof err === "object" && err !== null && err[brand] === true;
+}
+function isCloudRoaringError(err) {
+  return hasBrand(err, ERROR_BRAND);
+}
+function isIntegrityError(err) {
+  return isCloudRoaringError(err) && err.name === "IntegrityError";
+}
+
+// src/core/ports.ts
+var NO_ROW = /* @__PURE__ */ Symbol.for("cloud-roaring.no-row");
+
+// src/drivers/_shared/aws-errors.ts
+function httpStatus(err) {
+  return err?.$metadata?.httpStatusCode;
+}
+function errorName(err) {
+  return err?.name;
+}
+function errorCode(err) {
+  return err?.code;
+}
+function isSdkRetryable(err) {
+  return err?.$retryable != null;
+}
+function isServerSide(err) {
+  const status = httpStatus(err);
+  return status !== void 0 && status >= 500 && status <= 599;
+}
+var NETWORK_NAMES = /* @__PURE__ */ new Set([
+  "TimeoutError",
+  "RequestTimeout",
+  "RequestTimeoutException",
+  "NetworkingError",
+  "AbortError"
+]);
+var NETWORK_CODES = /* @__PURE__ */ new Set([
+  "ETIMEDOUT",
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "EPIPE",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ECONNABORTED"
+]);
+var NETWORK_MESSAGE = /socket hang up|network (error|failure)|(connection|request|socket|operation|read|write)\s+tim(e|ed)\s?out|connection (reset|refused|aborted|closed)/i;
+function isNetworkOrTimeout(err) {
+  if (NETWORK_NAMES.has(errorName(err) ?? "")) return true;
+  if (NETWORK_CODES.has(errorCode(err) ?? "")) return true;
+  return NETWORK_MESSAGE.test(err?.message ?? "");
+}
+
+// src/drivers/dynamodb/dynamodb-errors.ts
+function isConditionalCheckFailed(err) {
+  return errorName(err) === "ConditionalCheckFailedException";
+}
+var TRANSIENT_NAMES = /* @__PURE__ */ new Set([
+  "ThrottlingException",
+  "ProvisionedThroughputExceededException",
+  "RequestLimitExceeded",
+  "InternalServerError",
+  "ServiceUnavailable",
+  "LimitExceededException"
+]);
+function isTransient(err) {
+  if (isConditionalCheckFailed(err)) return false;
+  return TRANSIENT_NAMES.has(errorName(err) ?? "") || isServerSide(err) || isNetworkOrTimeout(err) || isSdkRetryable(err);
+}
+
+// src/core/validate.ts
+var CHUNK_KEY_MAX = 65535;
+var NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/;
+function validatePart(value, field) {
+  if (typeof value !== "string" || !NAME.test(value) || value.includes("..")) {
+    throw new ValidationError(
+      `${field} must match ${String(NAME)} and contain no "..": got ${JSON.stringify(value)}`
+    );
+  }
+}
+function validateSegmentRef(ref) {
+  validatePart(ref.segment, "segment");
+  if (ref.namespace !== void 0) validatePart(ref.namespace, "namespace");
+}
+function validateChunkRef(ref) {
+  validateSegmentRef(ref);
+  if (!Number.isInteger(ref.chunkKey) || ref.chunkKey < 0 || ref.chunkKey > CHUNK_KEY_MAX) {
+    throw new ValidationError(
+      `chunkKey must be an integer in [0, ${CHUNK_KEY_MAX}]; got ${ref.chunkKey}`
+    );
+  }
+}
+
+// src/drivers/_shared/keys.ts
+var DEFAULT_NAMESPACE = "_default";
+function namespacePart(namespace) {
+  return namespace ?? DEFAULT_NAMESPACE;
+}
+
+// src/drivers/dynamodb/keys.ts
+var CHUNK_SK_PREFIX = "chunk#";
+var CHUNK_KEY_DIGITS = 5;
+function assertValidKeyPrefix(prefix) {
+  if (prefix === void 0 || prefix === "") return;
+  for (const ch of prefix) {
+    const code = ch.charCodeAt(0);
+    if (ch === "|" || ch === "#" || code < 32) {
+      throw new ValidationError(`keyPrefix must not contain "|", "#", or control characters`);
+    }
+  }
+}
+function partitionKey(ref, prefix) {
+  validateSegmentRef(ref);
+  const base = `ns#${namespacePart(ref.namespace)}|seg#${ref.segment}`;
+  return prefix === void 0 || prefix === "" ? base : `${prefix}|${base}`;
+}
+function chunkSortKey(chunkKey) {
+  return `${CHUNK_SK_PREFIX}${String(chunkKey).padStart(CHUNK_KEY_DIGITS, "0")}`;
+}
+function chunkKeyPair(ref, prefix) {
+  validateChunkRef(ref);
+  return { pk: partitionKey(ref, prefix), sk: chunkSortKey(ref.chunkKey) };
+}
+function chunkSortKeyPrefix() {
+  return CHUNK_SK_PREFIX;
+}
+var REGISTRY_SK = "reg#";
+function registrySortKey() {
+  return REGISTRY_SK;
+}
+function registryKeyPair(ref, prefix) {
+  validateSegmentRef(ref);
+  return { pk: partitionKey(ref, prefix), sk: REGISTRY_SK };
+}
+function parseChunkSortKey(sk) {
+  if (!sk.startsWith(CHUNK_SK_PREFIX)) return null;
+  const middle = sk.slice(CHUNK_SK_PREFIX.length);
+  if (!new RegExp(`^\\d{${CHUNK_KEY_DIGITS}}$`).test(middle)) return null;
+  const chunkKey = Number(middle);
+  return chunkKey <= 65535 ? chunkKey : null;
+}
+
+// src/drivers/dynamodb/warm.ts
+var MUTATE_NAMES = { "#v": "v", "#b": "b", "#del": "del" };
+var QUERY_NAMES = { "#pk": "PK", "#sk": "SK", "#del": "del" };
+var ONE = { N: "1" };
+var TRUE = { BOOL: true };
+var FALSE = { BOOL: false };
+var DynamoDbWarmDriver = class {
+  client;
+  table;
+  keyPrefix;
+  constructor(options) {
+    assertValidKeyPrefix(options.keyPrefix);
+    this.client = options.client;
+    this.table = options.tableName;
+    this.keyPrefix = options.keyPrefix;
+  }
+  async get(ref, opts) {
+    const { pk, sk } = chunkKeyPair(ref, this.keyPrefix);
+    let res;
+    try {
+      res = await this.client.send(
+        new clientDynamodb.GetItemCommand({
+          TableName: this.table,
+          Key: { PK: { S: pk }, SK: { S: sk } },
+          // Strong by default (the OCC read-modify-write must see the latest committed value); a read path
+          // may opt into an eventually-consistent read (~½ RCU) via `warmReadConsistency: 'eventual'` (gap #9).
+          ConsistentRead: opts?.consistent ?? true
+        })
+      );
+    } catch (err) {
+      throw this.mapError(err, ref.chunkKey);
+    }
+    if (res.Item === void 0 || res.Item.del?.BOOL === true) return null;
+    return this.rowFrom(res.Item, ref.chunkKey);
+  }
+  async putConditional(ref, bytes, expected) {
+    const { pk, sk } = chunkKeyPair(ref, this.keyPrefix);
+    const command = expected === NO_ROW ? new clientDynamodb.UpdateItemCommand({
+      TableName: this.table,
+      Key: { PK: { S: pk }, SK: { S: sk } },
+      ConditionExpression: "attribute_not_exists(#v) OR #del = :true",
+      UpdateExpression: "ADD #v :one SET #b = :b, #del = :false",
+      ExpressionAttributeNames: MUTATE_NAMES,
+      ExpressionAttributeValues: {
+        ":one": ONE,
+        ":b": { B: bytes },
+        ":true": TRUE,
+        ":false": FALSE
+      },
+      ReturnValues: "UPDATED_NEW"
+    }) : new clientDynamodb.UpdateItemCommand({
+      TableName: this.table,
+      Key: { PK: { S: pk }, SK: { S: sk } },
+      ConditionExpression: "#v = :expected AND #del = :false",
+      UpdateExpression: "ADD #v :one SET #b = :b",
+      ExpressionAttributeNames: MUTATE_NAMES,
+      ExpressionAttributeValues: {
+        ":expected": { N: expected },
+        ":one": ONE,
+        ":b": { B: bytes },
+        ":false": FALSE
+      },
+      ReturnValues: "UPDATED_NEW"
+    });
+    try {
+      const res = await this.client.send(command);
+      const token = res.Attributes?.v?.N;
+      if (token === void 0) throw new IntegrityError("DynamoDB UpdateItem returned no token");
+      return { token };
+    } catch (err) {
+      throw this.mapError(err, ref.chunkKey);
+    }
+  }
+  async deleteConditional(ref, expected) {
+    const { pk, sk } = chunkKeyPair(ref, this.keyPrefix);
+    try {
+      await this.client.send(
+        new clientDynamodb.UpdateItemCommand({
+          TableName: this.table,
+          Key: { PK: { S: pk }, SK: { S: sk } },
+          // Tombstone (advance the counter, drop the payload) — keeps the token monotonic for ABA-safety.
+          ConditionExpression: "#v = :expected AND #del = :false",
+          UpdateExpression: "ADD #v :one SET #del = :true REMOVE #b",
+          ExpressionAttributeNames: MUTATE_NAMES,
+          ExpressionAttributeValues: {
+            ":expected": { N: expected },
+            ":one": ONE,
+            ":true": TRUE,
+            ":false": FALSE
+          }
+        })
+      );
+    } catch (err) {
+      throw this.mapError(err, ref.chunkKey);
+    }
+  }
+  async *listChunks(ref, opts) {
+    const pk = partitionKey(ref, this.keyPrefix);
+    let startKey;
+    do {
+      let res;
+      try {
+        res = await this.client.send(
+          new clientDynamodb.QueryCommand({
+            TableName: this.table,
+            KeyConditionExpression: "#pk = :pk AND begins_with(#sk, :prefix)",
+            FilterExpression: "#del = :false",
+            // exclude tombstones (server-side)
+            ExpressionAttributeNames: QUERY_NAMES,
+            ExpressionAttributeValues: {
+              ":pk": { S: pk },
+              ":prefix": { S: chunkSortKeyPrefix() },
+              ":false": FALSE
+            },
+            ConsistentRead: opts?.consistent ?? true,
+            // strong by default; eventual when a read path opts in (gap #9)
+            ExclusiveStartKey: startKey
+          })
+        );
+      } catch (err) {
+        throw this.mapError(err, -1);
+      }
+      for (const item of res.Items ?? []) {
+        const chunkKey = parseChunkSortKey(item.SK?.S ?? "");
+        if (chunkKey === null) continue;
+        yield { chunkKey, ...this.rowFrom(item, chunkKey) };
+      }
+      startKey = res.LastEvaluatedKey;
+    } while (startKey !== void 0);
+  }
+  /**
+   * Build a {@link WarmRow} from a raw item. Only ever called for a **live** row (callers filter
+   * tombstones first), so both `v` and `b` MUST be present — a missing attribute means a corrupt or
+   * foreign item, which we reject (untrusted-bytes posture, invariant 5) rather than paper over.
+   */
+  rowFrom(item, chunkKey) {
+    const token = item.v?.N;
+    if (token === void 0) {
+      throw new IntegrityError(`warm row for chunk ${chunkKey} is missing its token`);
+    }
+    const bytes = item.b?.B;
+    if (bytes === void 0) {
+      throw new IntegrityError(`live warm row for chunk ${chunkKey} is missing its payload`);
+    }
+    return { token, bytes };
+  }
+  /**
+   * Translate a raw SDK/driver error to our typed vocabulary: a failed condition is an OCC conflict; a
+   * throttle/5xx/dropped-connection is a (retryable) {@link TransientError}; everything else propagates
+   * unchanged. Applied at every `client.send` site so callers (and the retry decorator) only ever see typed
+   * errors. Order matters: a conflict is **never** transient (it's deterministic — the engine's OCC loop
+   * owns that retry), so it's classified first.
+   */
+  mapError(err, chunkKey) {
+    if (isIntegrityError(err)) return err;
+    if (err instanceof clientDynamodb.ConditionalCheckFailedException || err?.name === "ConditionalCheckFailedException") {
+      return new WriteConflictError(`OCC conflict on chunk ${chunkKey}`);
+    }
+    if (isTransient(err)) {
+      return new TransientError(
+        `transient DynamoDB fault on chunk ${chunkKey}: ${err?.name ?? "unknown"}`,
+        { cause: err }
+      );
+    }
+    return err;
+  }
+};
+
+// src/drivers/_shared/registry.ts
+var STATUSES = ["active", "compacting", "erasing", "destroyed"];
+var MAX_GOVERNANCE_BYTES = 64 * 1024;
+var MAX_WRAPPED_DEKS = 8;
+var MAX_WRAPPED_DEK_BYTES = 4 * 1024;
+function validateGeneration(gen) {
+  if (!Number.isInteger(gen) || gen < 0) {
+    throw new ValidationError(`currentGen must be a non-negative integer; got ${gen}`);
+  }
+}
+function validateCount(count, field = "dirtyChunkCount") {
+  if (!Number.isInteger(count) || count < 0) {
+    throw new ValidationError(`${field} must be a non-negative integer; got ${count}`);
+  }
+}
+function validateTimestamp(ms, field) {
+  if (!Number.isFinite(ms) || ms < 0) {
+    throw new ValidationError(`${field} must be a non-negative finite number; got ${ms}`);
+  }
+}
+function validateStatus(status) {
+  if (!STATUSES.includes(status)) {
+    throw new ValidationError(`status must be one of ${STATUSES.join("/")}; got ${status}`);
+  }
+}
+function validateGovernance(meta, field) {
+  if (meta === void 0) return;
+  let json;
+  try {
+    json = JSON.stringify(meta);
+  } catch {
+    throw new ValidationError(`${field} must be JSON-serializable`);
+  }
+  if (json.length > MAX_GOVERNANCE_BYTES) {
+    throw new ValidationError(`${field} is ${json.length}B, exceeds cap ${MAX_GOVERNANCE_BYTES}B`);
+  }
+}
+function validateWrappedDeks(value, isStored) {
+  if (value === void 0) return;
+  const fail = (msg) => {
+    throw isStored ? new IntegrityError(msg) : new ValidationError(msg);
+  };
+  if (!Array.isArray(value)) fail("wrappedDeks must be an array");
+  const list = value;
+  if (list.length === 0) fail("wrappedDeks must be non-empty when present");
+  if (list.length > MAX_WRAPPED_DEKS)
+    fail(`wrappedDeks has ${list.length} entries, cap ${MAX_WRAPPED_DEKS}`);
+  for (const w of list) {
+    if (w === null || typeof w !== "object") fail("wrappedDeks entry must be an object");
+    const { keyId, wrapped } = w;
+    if (typeof keyId !== "string" || keyId.length === 0)
+      fail("wrappedDeks entry needs a non-empty keyId");
+    if (typeof wrapped !== "string" || wrapped.length === 0)
+      fail("wrappedDeks entry needs a non-empty wrapped blob");
+    if (wrapped.length > MAX_WRAPPED_DEK_BYTES)
+      fail(`wrappedDeks entry is ${wrapped.length}B, cap ${MAX_WRAPPED_DEK_BYTES}B`);
+  }
+}
+function validateNewRegistryRecord(rec) {
+  validateGeneration(rec.currentGen);
+  if (rec.dirtyChunkCount !== void 0) validateCount(rec.dirtyChunkCount);
+  if (rec.status !== void 0) validateStatus(rec.status);
+  validateWrappedDeks(rec.wrappedDeks, false);
+  validateGovernance(rec.retention, "retention");
+  validateGovernance(rec.residency, "residency");
+}
+function validateRegistryPatch(patch) {
+  if (patch.currentGen !== void 0) validateGeneration(patch.currentGen);
+  if (patch.dirtyChunkCount !== void 0) validateCount(patch.dirtyChunkCount);
+  if (patch.consecutiveFailures !== void 0)
+    validateCount(patch.consecutiveFailures, "consecutiveFailures");
+  if (patch.lastCompactedAt !== void 0)
+    validateTimestamp(patch.lastCompactedAt, "lastCompactedAt");
+  if (patch.status !== void 0) validateStatus(patch.status);
+  if ("wrappedDeks" in patch) validateWrappedDeks(patch.wrappedDeks, false);
+  if ("retention" in patch) validateGovernance(patch.retention, "retention");
+  if ("residency" in patch) validateGovernance(patch.residency, "residency");
+}
+var REGISTRY_SCHEMA_VERSION = 1;
+function assertRegistrySchemaVersion(raw, ctx) {
+  if (raw === void 0) return;
+  if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1) {
+    throw new IntegrityError(`registry row has a malformed schemaVersion (${String(raw)}): ${ctx}`);
+  }
+  if (raw > REGISTRY_SCHEMA_VERSION) {
+    throw new UnsupportedError(
+      `registry row schemaVersion ${raw} is newer than this build reads (v${REGISTRY_SCHEMA_VERSION}): ${ctx}`
+    );
+  }
+}
+function recordFromNew(ref, rec, now, token) {
+  return {
+    namespace: ref.namespace,
+    segment: ref.segment,
+    currentGen: rec.currentGen,
+    wrappedDeks: rec.wrappedDeks,
+    keyId: rec.keyId,
+    dirtyChunkCount: rec.dirtyChunkCount ?? 0,
+    status: rec.status ?? "active",
+    consecutiveFailures: 0,
+    // daemon health (Phase D); lastCompactedAt stays absent until first compaction
+    retention: rec.retention,
+    residency: rec.residency,
+    createdAt: now,
+    updatedAt: now,
+    token
+  };
+}
+function assertStoredRecordShape(r, ctx) {
+  if (typeof r.segment !== "string" || r.namespace !== void 0 && typeof r.namespace !== "string" || typeof r.currentGen !== "number" || typeof r.dirtyChunkCount !== "number" || typeof r.status !== "string" || typeof r.createdAt !== "number" || typeof r.updatedAt !== "number") {
+    throw new IntegrityError(`registry record is missing required fields: ${ctx}`);
+  }
+  if (!Number.isInteger(r.currentGen) || r.currentGen < 0) {
+    throw new IntegrityError(`registry record has an invalid currentGen (${r.currentGen}): ${ctx}`);
+  }
+  if (!Number.isInteger(r.dirtyChunkCount) || r.dirtyChunkCount < 0) {
+    throw new IntegrityError(`registry record has an invalid dirtyChunkCount: ${ctx}`);
+  }
+  if (!STATUSES.includes(r.status)) {
+    throw new IntegrityError(`registry record has an unknown status (${r.status}): ${ctx}`);
+  }
+  if (r.leaseOwner !== void 0 && typeof r.leaseOwner !== "string") {
+    throw new IntegrityError(`registry record has an invalid leaseOwner: ${ctx}`);
+  }
+  if (r.leaseExpiresAt !== void 0 && typeof r.leaseExpiresAt !== "number") {
+    throw new IntegrityError(`registry record has an invalid leaseExpiresAt: ${ctx}`);
+  }
+  if (r.consecutiveFailures !== void 0 && (!Number.isInteger(r.consecutiveFailures) || r.consecutiveFailures < 0)) {
+    throw new IntegrityError(`registry record has an invalid consecutiveFailures: ${ctx}`);
+  }
+  if (r.lastCompactedAt !== void 0 && (typeof r.lastCompactedAt !== "number" || !Number.isFinite(r.lastCompactedAt) || r.lastCompactedAt < 0)) {
+    throw new IntegrityError(`registry record has an invalid lastCompactedAt: ${ctx}`);
+  }
+  if (r.keyId !== void 0 && typeof r.keyId !== "string") {
+    throw new IntegrityError(`registry record has an invalid keyId: ${ctx}`);
+  }
+  validateWrappedDeks(r.wrappedDeks, true);
+}
+function applyRegistryPatch(prev, patch, now, token) {
+  return {
+    namespace: prev.namespace,
+    segment: prev.segment,
+    currentGen: patch.currentGen ?? prev.currentGen,
+    wrappedDeks: "wrappedDeks" in patch ? patch.wrappedDeks : prev.wrappedDeks,
+    keyId: "keyId" in patch ? patch.keyId : prev.keyId,
+    dirtyChunkCount: patch.dirtyChunkCount ?? prev.dirtyChunkCount,
+    status: patch.status ?? prev.status,
+    leaseOwner: "leaseOwner" in patch ? patch.leaseOwner : prev.leaseOwner,
+    leaseExpiresAt: "leaseExpiresAt" in patch ? patch.leaseExpiresAt : prev.leaseExpiresAt,
+    lastCompactedAt: "lastCompactedAt" in patch ? patch.lastCompactedAt : prev.lastCompactedAt,
+    consecutiveFailures: patch.consecutiveFailures ?? prev.consecutiveFailures ?? 0,
+    retention: "retention" in patch ? patch.retention : prev.retention,
+    residency: "residency" in patch ? patch.residency : prev.residency,
+    createdAt: prev.createdAt,
+    updatedAt: now,
+    token
+  };
+}
+
+// src/drivers/dynamodb/registry.ts
+var MUTATE_NAMES2 = { "#v": "v", "#r": "r", "#del": "del" };
+var SCAN_NAMES = { "#sk": "SK", "#del": "del", "#pk": "PK" };
+var ONE2 = { N: "1" };
+var TRUE2 = { BOOL: true };
+var FALSE2 = { BOOL: false };
+var DynamoDbRegistryDriver = class {
+  client;
+  table;
+  keyPrefix;
+  now;
+  constructor(options) {
+    assertValidKeyPrefix(options.keyPrefix);
+    this.client = options.client;
+    this.table = options.tableName;
+    this.keyPrefix = options.keyPrefix;
+    this.now = options.now ?? (() => Date.now());
+  }
+  capabilities() {
+    return { strongRead: true };
+  }
+  async get(ref) {
+    const { pk, sk } = registryKeyPair(ref, this.keyPrefix);
+    let res;
+    try {
+      res = await this.client.send(
+        new clientDynamodb.GetItemCommand({
+          TableName: this.table,
+          Key: { PK: { S: pk }, SK: { S: sk } },
+          ConsistentRead: true
+          // currentGen feeds correctness — must be the latest committed value
+        })
+      );
+    } catch (err) {
+      throw this.mapError(err, ref);
+    }
+    if (res.Item === void 0 || res.Item.del?.BOOL === true) return null;
+    return rowToRecord(res.Item, ref);
+  }
+  async create(ref, record) {
+    validateNewRegistryRecord(record);
+    const { pk, sk } = registryKeyPair(ref, this.keyPrefix);
+    const now = this.now();
+    const body = serializeBody(recordFromNew(ref, record, now, ""));
+    try {
+      const res = await this.client.send(
+        new clientDynamodb.UpdateItemCommand({
+          TableName: this.table,
+          Key: { PK: { S: pk }, SK: { S: sk } },
+          ConditionExpression: "attribute_not_exists(#v) OR #del = :true",
+          UpdateExpression: "ADD #v :one SET #r = :r, #del = :false",
+          ExpressionAttributeNames: MUTATE_NAMES2,
+          ExpressionAttributeValues: {
+            ":one": ONE2,
+            ":r": { S: body },
+            ":true": TRUE2,
+            ":false": FALSE2
+          },
+          ReturnValues: "UPDATED_NEW"
+        })
+      );
+      return { token: tokenOf(res.Attributes) };
+    } catch (err) {
+      throw this.mapError(err, ref, "already exists");
+    }
+  }
+  async compareAndSwap(ref, expected, patch) {
+    validateRegistryPatch(patch);
+    const current = await this.get(ref);
+    if (current === null || current.token !== expected) {
+      throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
+    }
+    const { pk, sk } = registryKeyPair(ref, this.keyPrefix);
+    const body = serializeBody(applyRegistryPatch(current, patch, this.now(), ""));
+    try {
+      const res = await this.client.send(
+        new clientDynamodb.UpdateItemCommand({
+          TableName: this.table,
+          Key: { PK: { S: pk }, SK: { S: sk } },
+          ConditionExpression: "#v = :expected AND #del = :false",
+          UpdateExpression: "ADD #v :one SET #r = :r",
+          ExpressionAttributeNames: MUTATE_NAMES2,
+          ExpressionAttributeValues: {
+            ":expected": { N: expected },
+            ":one": ONE2,
+            ":r": { S: body },
+            ":false": FALSE2
+          },
+          ReturnValues: "UPDATED_NEW"
+        })
+      );
+      return { token: tokenOf(res.Attributes) };
+    } catch (err) {
+      throw this.mapError(err, ref);
+    }
+  }
+  async *list(namespace) {
+    const filter = ["#sk = :reg", "#del = :false"];
+    const values = {
+      ":reg": { S: registrySortKey() },
+      ":false": FALSE2
+    };
+    const pkPrefix = this.scanPkPrefix(namespace);
+    if (pkPrefix !== void 0) {
+      filter.push("begins_with(#pk, :pk)");
+      values[":pk"] = { S: pkPrefix };
+    }
+    let startKey;
+    do {
+      let res;
+      try {
+        res = await this.client.send(
+          new clientDynamodb.ScanCommand({
+            TableName: this.table,
+            FilterExpression: filter.join(" AND "),
+            ExpressionAttributeNames: pkPrefix !== void 0 ? SCAN_NAMES : { "#sk": "SK", "#del": "del" },
+            ExpressionAttributeValues: values,
+            ExclusiveStartKey: startKey
+          })
+        );
+      } catch (err) {
+        throw this.mapError(err);
+      }
+      for (const item of res.Items ?? []) {
+        yield rowToRecord(item, namespaceOf(item));
+      }
+      startKey = res.LastEvaluatedKey;
+    } while (startKey !== void 0);
+  }
+  async delete(ref) {
+    const { pk, sk } = registryKeyPair(ref, this.keyPrefix);
+    try {
+      await this.client.send(
+        new clientDynamodb.UpdateItemCommand({
+          TableName: this.table,
+          Key: { PK: { S: pk }, SK: { S: sk } },
+          UpdateExpression: "ADD #v :one SET #del = :true REMOVE #r",
+          ExpressionAttributeNames: MUTATE_NAMES2,
+          ExpressionAttributeValues: { ":one": ONE2, ":true": TRUE2 }
+        })
+      );
+    } catch (err) {
+      throw this.mapError(err, ref);
+    }
+  }
+  /** The PK prefix to scope a `list` scan, or `undefined` for an unscoped scan (no namespace, no keyPrefix). */
+  scanPkPrefix(namespace) {
+    if (namespace !== void 0) {
+      const full = partitionKey({ namespace, segment: "x" }, this.keyPrefix);
+      return full.slice(0, full.length - "x".length);
+    }
+    return this.keyPrefix !== void 0 ? `${this.keyPrefix}|` : void 0;
+  }
+  /** Map a raw SDK error to the typed vocabulary (conflict / transient / passthrough). */
+  mapError(err, ref, conflictHint = "OCC token mismatch") {
+    if (isIntegrityError(err)) return err;
+    if (err instanceof clientDynamodb.ConditionalCheckFailedException || err?.name === "ConditionalCheckFailedException") {
+      return new WriteConflictError(
+        `registry ${conflictHint}${ref ? ` for segment ${ref.segment}` : ""}`
+      );
+    }
+    if (isTransient(err)) {
+      return new TransientError(
+        `transient DynamoDB fault on registry${ref ? ` ${ref.segment}` : ""}: ${err?.name ?? "unknown"}`,
+        { cause: err }
+      );
+    }
+    return err;
+  }
+};
+function tokenOf(attrs) {
+  const token = attrs?.v?.N;
+  if (token === void 0)
+    throw new IntegrityError("DynamoDB registry UpdateItem returned no token");
+  return token;
+}
+function serializeBody(record) {
+  const body = {
+    namespace: record.namespace,
+    segment: record.segment,
+    currentGen: record.currentGen,
+    wrappedDeks: record.wrappedDeks,
+    keyId: record.keyId,
+    dirtyChunkCount: record.dirtyChunkCount,
+    status: record.status,
+    leaseOwner: record.leaseOwner,
+    leaseExpiresAt: record.leaseExpiresAt,
+    lastCompactedAt: record.lastCompactedAt,
+    consecutiveFailures: record.consecutiveFailures,
+    retention: record.retention,
+    residency: record.residency,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt
+  };
+  return JSON.stringify({ schemaVersion: REGISTRY_SCHEMA_VERSION, ...body });
+}
+function namespaceOf(item) {
+  const body = parseBody(item.r?.S, "scan");
+  return { namespace: body.namespace, segment: body.segment };
+}
+function rowToRecord(item, ref) {
+  const token = item.v?.N;
+  if (token === void 0) {
+    throw new IntegrityError(`registry row for segment ${ref.segment} is missing its token`);
+  }
+  const body = parseBody(item.r?.S, ref.segment);
+  return { ...body, token };
+}
+function parseBody(json, ctx) {
+  if (json === void 0) throw new IntegrityError(`registry row ${ctx} is missing its body`);
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    throw new IntegrityError(`registry row ${ctx} body is not valid JSON`);
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    throw new IntegrityError(`registry row ${ctx} body is malformed`);
+  }
+  const { schemaVersion, ...body } = parsed;
+  assertRegistrySchemaVersion(schemaVersion, ctx);
+  assertStoredRecordShape(body, ctx);
+  return body;
+}
+
+exports.DynamoDbRegistryDriver = DynamoDbRegistryDriver;
+exports.DynamoDbWarmDriver = DynamoDbWarmDriver;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map