@cloudbitmaps/core 0.1.0-rc.0

package/dist/s3/index.cjs

@@ -0,0 +1,891 @@
+'use strict';
+
+var crypto = require('crypto');
+var clientS3 = require('@aws-sdk/client-s3');
+
+// src/drivers/s3/cold.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 NotFoundError = 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 isWriteConflictError(err) {
+  return isCloudRoaringError(err) && err.name === "WriteConflictError";
+}
+function isNotFoundError(err) {
+  return isCloudRoaringError(err) && err.name === "NotFoundError";
+}
+function isValidationError(err) {
+  return isCloudRoaringError(err) && err.name === "ValidationError";
+}
+
+// src/core/validate.ts
+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");
+}
+
+// src/drivers/_shared/keys.ts
+var DEFAULT_NAMESPACE = "_default";
+function namespacePart(namespace) {
+  return namespace ?? DEFAULT_NAMESPACE;
+}
+
+// src/drivers/s3/keys.ts
+var SUFFIX = ".crbm";
+var REGISTRY_SUFFIX = ".reg";
+function prefixPart(prefix) {
+  if (prefix === void 0) return "";
+  const trimmed = prefix.replace(/^\/+|\/+$/g, "");
+  return trimmed === "" ? "" : `${trimmed}/`;
+}
+function normalizeS3Prefix(prefix) {
+  if (prefix === void 0) return void 0;
+  for (const ch of prefix) {
+    if (ch.charCodeAt(0) < 32) {
+      throw new ValidationError("prefix must not contain control characters");
+    }
+  }
+  for (const segment of prefix.split("/")) {
+    if (segment === "." || segment === "..") {
+      throw new ValidationError(
+        `prefix must not contain "." or ".." path segments: ${JSON.stringify(prefix)}`
+      );
+    }
+  }
+  return prefix;
+}
+function segmentObjectPrefix(prefix, ref) {
+  validateSegmentRef(ref);
+  return `${prefixPart(prefix)}${namespacePart(ref.namespace)}/segments/${ref.segment}.`;
+}
+function coldObjectKey(prefix, key) {
+  if (!Number.isInteger(key.generation) || key.generation < 0) {
+    throw new ValidationError(`generation must be a non-negative integer; got ${key.generation}`);
+  }
+  return `${segmentObjectPrefix(prefix, key)}${key.generation}${SUFFIX}`;
+}
+function registryPrefix(prefix) {
+  return `${prefixPart(prefix)}registry/`;
+}
+function registryObjectKey(prefix, ref) {
+  validateSegmentRef(ref);
+  return `${registryPrefix(prefix)}${namespacePart(ref.namespace)}/${ref.segment}${REGISTRY_SUFFIX}`;
+}
+function registryListPrefix(prefix, namespace) {
+  const base = registryPrefix(prefix);
+  return namespace === void 0 ? base : `${base}${namespacePart(namespace)}/`;
+}
+function parseRegistryKey(prefix, objectKey) {
+  const base = registryPrefix(prefix);
+  if (!objectKey.startsWith(base) || !objectKey.endsWith(REGISTRY_SUFFIX)) return null;
+  const rest = objectKey.slice(base.length, objectKey.length - REGISTRY_SUFFIX.length);
+  const slash = rest.indexOf("/");
+  if (slash < 0) return null;
+  const nsPart = rest.slice(0, slash);
+  const segment = rest.slice(slash + 1);
+  if (segment.length === 0 || segment.includes("/")) return null;
+  const namespace = nsPart === DEFAULT_NAMESPACE ? void 0 : nsPart;
+  const ref = { segment, namespace };
+  try {
+    validateSegmentRef(ref);
+  } catch {
+    return null;
+  }
+  return ref;
+}
+function parseGenerationFromKey(segmentPrefix, objectKey) {
+  if (!objectKey.startsWith(segmentPrefix) || !objectKey.endsWith(SUFFIX)) return null;
+  const middle = objectKey.slice(segmentPrefix.length, objectKey.length - SUFFIX.length);
+  if (!/^(0|[1-9]\d*)$/.test(middle)) return null;
+  const generation = Number(middle);
+  return Number.isSafeInteger(generation) ? generation : null;
+}
+
+// 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/s3/s3-errors.ts
+function isPreconditionFailed(err) {
+  return errorName(err) === "PreconditionFailed" || httpStatus(err) === 412;
+}
+function isConditionalConflict(err) {
+  return isPreconditionFailed(err) || errorName(err) === "ConditionalRequestConflict" || httpStatus(err) === 409;
+}
+function isNotFound(err) {
+  const name = errorName(err);
+  return name === "NoSuchKey" || name === "NotFound" || httpStatus(err) === 404;
+}
+function isInvalidRange(err) {
+  return errorName(err) === "InvalidRange" || httpStatus(err) === 416;
+}
+function isTransient(err) {
+  if (isConditionalConflict(err) || isNotFound(err) || isInvalidRange(err)) return false;
+  return errorName(err) === "SlowDown" || isServerSide(err) || isNetworkOrTimeout(err) || isSdkRetryable(err);
+}
+function totalFromContentRange(contentRange) {
+  if (contentRange === void 0) return void 0;
+  const match = /\/(\d+)\s*$/.exec(contentRange);
+  if (match === null) return void 0;
+  const total = Number(match[1]);
+  return Number.isSafeInteger(total) ? total : void 0;
+}
+
+// src/drivers/s3/cold.ts
+var S3_PART_BYTES = 8 * 1024 * 1024;
+var S3_MAX_PARTS = 1e4;
+var S3ColdDriver = class {
+  client;
+  bucket;
+  prefix;
+  maxObjectBytes;
+  partBytes;
+  constructor(options) {
+    this.client = options.client;
+    this.bucket = options.bucket;
+    this.prefix = normalizeS3Prefix(options.prefix);
+    const requestedPart = Math.max(options.partBytes ?? S3_PART_BYTES, 5 * 1024 * 1024);
+    this.maxObjectBytes = options.maxObjectBytes ?? requestedPart * S3_MAX_PARTS;
+    this.partBytes = Math.max(requestedPart, Math.ceil(this.maxObjectBytes / S3_MAX_PARTS));
+  }
+  capabilities() {
+    return { rangeRead: true, maxObjectBytes: this.maxObjectBytes, conditionalPut: true };
+  }
+  async putImmutable(key, write) {
+    const objectKey = coldObjectKey(this.prefix, key);
+    const sink = new S3MultipartSink(
+      this.client,
+      this.bucket,
+      objectKey,
+      this.partBytes,
+      this.maxObjectBytes
+    );
+    try {
+      await write(sink);
+      return await sink.finish();
+    } catch (err) {
+      await sink.abort();
+      if (isConditionalConflict(err)) {
+        throw new WriteConflictError(
+          `generation already exists (write-once): ${key.segment}.${key.generation}`
+        );
+      }
+      if (isValidationError(err) || isWriteConflictError(err) || isNotFoundError(err)) {
+        throw err;
+      }
+      throw this.mapError(err);
+    }
+  }
+  async getRange(key, offset, length) {
+    if (!Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0) {
+      throw new ValidationError(`invalid range offset=${offset} length=${length}`);
+    }
+    const objectKey = coldObjectKey(this.prefix, key);
+    if (length === 0) return new Uint8Array(0);
+    try {
+      const res = await this.client.send(
+        new clientS3.GetObjectCommand({
+          Bucket: this.bucket,
+          Key: objectKey,
+          Range: `bytes=${offset}-${offset + length - 1}`
+        })
+      );
+      const bytes = await collect(res.Body);
+      if (bytes.length !== length) {
+        throw new ValidationError(
+          `range [${offset}, ${offset + length}) out of bounds (got ${bytes.length}B)`
+        );
+      }
+      return bytes;
+    } catch (err) {
+      throw this.mapReadError(err, key);
+    }
+  }
+  async getTail(key, maxBytes) {
+    const objectKey = coldObjectKey(this.prefix, key);
+    if (maxBytes <= 0) {
+      try {
+        const head = await this.client.send(
+          new clientS3.HeadObjectCommand({ Bucket: this.bucket, Key: objectKey })
+        );
+        return { bytes: new Uint8Array(0), size: head.ContentLength ?? 0 };
+      } catch (err) {
+        throw this.mapReadError(err, key);
+      }
+    }
+    try {
+      const res = await this.client.send(
+        new clientS3.GetObjectCommand({ Bucket: this.bucket, Key: objectKey, Range: `bytes=-${maxBytes}` })
+      );
+      const bytes = await collect(res.Body);
+      let size = totalFromContentRange(res.ContentRange);
+      if (size === void 0) {
+        if (bytes.length === maxBytes) {
+          const head = await this.client.send(
+            new clientS3.HeadObjectCommand({ Bucket: this.bucket, Key: objectKey })
+          );
+          size = head.ContentLength ?? bytes.length;
+        } else {
+          size = bytes.length;
+        }
+      }
+      return { bytes, size };
+    } catch (err) {
+      throw this.mapReadError(err, key);
+    }
+  }
+  async delete(key) {
+    try {
+      await this.client.send(
+        new clientS3.DeleteObjectCommand({ Bucket: this.bucket, Key: coldObjectKey(this.prefix, key) })
+      );
+    } catch (err) {
+      throw this.mapError(err);
+    }
+  }
+  async *list(ref) {
+    const prefix = segmentObjectPrefix(this.prefix, ref);
+    let token;
+    do {
+      let res;
+      try {
+        res = await this.client.send(
+          new clientS3.ListObjectsV2Command({
+            Bucket: this.bucket,
+            Prefix: prefix,
+            ContinuationToken: token
+          })
+        );
+      } catch (err) {
+        throw this.mapError(err);
+      }
+      for (const obj of res.Contents ?? []) {
+        if (obj.Key === void 0) continue;
+        const generation = parseGenerationFromKey(prefix, obj.Key);
+        if (generation !== null) {
+          yield { namespace: ref.namespace, segment: ref.segment, generation };
+        }
+      }
+      token = res.IsTruncated === true ? res.NextContinuationToken : void 0;
+    } while (token !== void 0);
+  }
+  /** Map S3 read errors to the driver vocabulary; pass everything else through {@link mapError}. */
+  mapReadError(err, key) {
+    if (isValidationError(err)) return err;
+    if (isNotFound(err)) {
+      return new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);
+    }
+    if (isInvalidRange(err)) {
+      return new ValidationError(`range out of bounds for ${key.segment}.${key.generation}`);
+    }
+    return this.mapError(err);
+  }
+  /**
+   * Reclassify a transient S3 fault (throttle/5xx/dropped connection) as a retryable {@link TransientError}
+   * so the retry decorator can ride it out; everything else propagates unchanged. The final fallback at every
+   * `client.send` site, so callers and the decorator only ever see typed errors.
+   */
+  mapError(err) {
+    if (isTransient(err)) {
+      return new TransientError(
+        `transient S3 fault: ${err?.name ?? "unknown"}`,
+        { cause: err }
+      );
+    }
+    return err;
+  }
+};
+function concatBytes(parts, total) {
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const p of parts) {
+    out.set(p, offset);
+    offset += p.length;
+  }
+  return out;
+}
+var S3MultipartSink = class {
+  constructor(client, bucket, objectKey, partBytes, maxObjectBytes) {
+    this.client = client;
+    this.bucket = bucket;
+    this.objectKey = objectKey;
+    this.partBytes = partBytes;
+    this.maxObjectBytes = maxObjectBytes;
+  }
+  client;
+  bucket;
+  objectKey;
+  partBytes;
+  maxObjectBytes;
+  hash = crypto.createHash("sha256");
+  pending = [];
+  pendingLen = 0;
+  total = 0;
+  uploadId;
+  partNumber = 0;
+  parts = [];
+  async write(bytes) {
+    if (bytes.length === 0) return;
+    this.total += bytes.length;
+    if (this.total > this.maxObjectBytes) {
+      throw new ValidationError(`object exceeds maxObjectBytes ${this.maxObjectBytes}`);
+    }
+    this.hash.update(bytes);
+    this.pending.push(bytes);
+    this.pendingLen += bytes.length;
+    if (this.pendingLen >= this.partBytes) await this.flushPart();
+  }
+  /** Upload the buffered bytes (≥ one part) as a single part, freeing them. Starts the upload on first call. */
+  async flushPart() {
+    if (this.uploadId === void 0) {
+      const res2 = await this.client.send(
+        new clientS3.CreateMultipartUploadCommand({ Bucket: this.bucket, Key: this.objectKey })
+      );
+      if (res2.UploadId === void 0) {
+        throw new TransientError("S3 CreateMultipartUpload returned no UploadId");
+      }
+      this.uploadId = res2.UploadId;
+    }
+    const body = concatBytes(this.pending, this.pendingLen);
+    this.pending.length = 0;
+    this.pendingLen = 0;
+    this.partNumber += 1;
+    if (this.partNumber > S3_MAX_PARTS) {
+      throw new ValidationError(`multipart upload exceeded the S3 ${S3_MAX_PARTS}-part limit`);
+    }
+    const res = await this.client.send(
+      new clientS3.UploadPartCommand({
+        Bucket: this.bucket,
+        Key: this.objectKey,
+        UploadId: this.uploadId,
+        PartNumber: this.partNumber,
+        Body: body
+      })
+    );
+    this.parts.push({ ETag: res.ETag, PartNumber: this.partNumber });
+  }
+  /** Commit the object: a single conditional PUT if it fit in one part, else complete the multipart upload. */
+  async finish() {
+    const sha256 = this.hash.digest("hex");
+    if (this.uploadId === void 0) {
+      await this.client.send(
+        new clientS3.PutObjectCommand({
+          Bucket: this.bucket,
+          Key: this.objectKey,
+          Body: concatBytes(this.pending, this.pendingLen),
+          IfNoneMatch: "*"
+          // write-once
+        })
+      );
+      return { size: this.total, sha256 };
+    }
+    if (this.pendingLen > 0) await this.flushPart();
+    await this.client.send(
+      new clientS3.CompleteMultipartUploadCommand({
+        Bucket: this.bucket,
+        Key: this.objectKey,
+        UploadId: this.uploadId,
+        MultipartUpload: { Parts: this.parts },
+        IfNoneMatch: "*"
+        // write-once: fail if the object already exists
+      })
+    );
+    this.uploadId = void 0;
+    return { size: this.total, sha256 };
+  }
+  /** Best-effort cleanup of an in-flight multipart upload after an error (a leaked MPU is reaped by a bucket
+   * lifecycle rule; never a correctness issue). No-op if nothing was started or it already completed. */
+  async abort() {
+    if (this.uploadId === void 0) return;
+    const id = this.uploadId;
+    this.uploadId = void 0;
+    try {
+      await this.client.send(
+        new clientS3.AbortMultipartUploadCommand({ Bucket: this.bucket, Key: this.objectKey, UploadId: id })
+      );
+    } catch {
+    }
+  }
+};
+async function collect(body) {
+  if (body === void 0) {
+    throw new NotFoundError("S3 GetObject returned an empty body");
+  }
+  return body.transformToByteArray();
+}
+
+// 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 serializeRegistryEnvelope(env) {
+  return JSON.stringify({
+    schemaVersion: REGISTRY_SCHEMA_VERSION,
+    deleted: env.deleted,
+    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}`);
+  }
+  const n = Number(record.token);
+  if (!Number.isSafeInteger(n)) {
+    throw new IntegrityError(`registry row token is out of safe-integer range: ${record.token}`);
+  }
+  return n;
+}
+function parseRegistryEnvelope(text, ctx) {
+  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);
+  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}`);
+  }
+  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,
+    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/core/concurrency.ts
+async function mapWithConcurrency(items, limit, fn) {
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new ValidationError(`concurrency limit must be a positive integer; got ${limit}`);
+  }
+  const results = new Array(items.length);
+  let next = 0;
+  let failed = false;
+  let firstError;
+  const worker = async () => {
+    while (!failed) {
+      const i = next++;
+      if (i >= items.length) return;
+      try {
+        results[i] = await fn(items[i], i);
+      } catch (err) {
+        if (!failed) {
+          failed = true;
+          firstError = err;
+        }
+        return;
+      }
+    }
+  };
+  const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+  await Promise.all(workers);
+  if (failed) throw firstError;
+  return results;
+}
+
+// src/drivers/s3/registry.ts
+var MAX_ROW_BYTES = 1 * 1024 * 1024;
+var MAX_DELETE_ATTEMPTS = 8;
+var LIST_READ_CONCURRENCY = 16;
+var S3RegistryDriver = class {
+  client;
+  bucket;
+  prefix;
+  now;
+  constructor(options) {
+    this.client = options.client;
+    this.bucket = options.bucket;
+    this.prefix = normalizeS3Prefix(options.prefix);
+    this.now = options.now ?? (() => Date.now());
+  }
+  capabilities() {
+    return { strongRead: true };
+  }
+  async get(ref) {
+    const current = await this.readRow(registryObjectKey(this.prefix, ref));
+    return current && !current.env.deleted ? current.env.record : null;
+  }
+  async create(ref, record) {
+    validateNewRegistryRecord(record);
+    const key = registryObjectKey(this.prefix, ref);
+    const current = await this.readRow(key);
+    if (current !== null && !current.env.deleted) {
+      throw new WriteConflictError(`registry row already exists for segment ${ref.segment}`);
+    }
+    const token = String(current ? registryCounterOf(current.env.record) + 1 : 0);
+    const env = {
+      deleted: false,
+      record: recordFromNew(ref, record, this.now(), token)
+    };
+    await this.putRow(key, env, current ? { ifMatch: current.etag } : { ifNoneMatch: "*" });
+    return { token };
+  }
+  async compareAndSwap(ref, expected, patch) {
+    validateRegistryPatch(patch);
+    const key = registryObjectKey(this.prefix, ref);
+    const current = await this.readRow(key);
+    if (current === null || current.env.deleted || current.env.record.token !== expected) {
+      throw new WriteConflictError(`OCC token mismatch for registry row ${ref.segment}`);
+    }
+    const token = String(registryCounterOf(current.env.record) + 1);
+    const env = {
+      deleted: false,
+      record: applyRegistryPatch(current.env.record, patch, this.now(), token)
+    };
+    await this.putRow(key, env, { ifMatch: current.etag });
+    return { token };
+  }
+  async *list(namespace) {
+    const prefix = registryListPrefix(this.prefix, namespace);
+    let token;
+    do {
+      let res;
+      try {
+        res = await this.client.send(
+          new clientS3.ListObjectsV2Command({
+            Bucket: this.bucket,
+            Prefix: prefix,
+            ContinuationToken: token
+          })
+        );
+      } catch (err) {
+        throw this.mapError(err);
+      }
+      const keys = (res.Contents ?? []).map((obj) => obj.Key).filter((k) => k !== void 0 && parseRegistryKey(this.prefix, k) !== null);
+      const rows = await mapWithConcurrency(
+        keys,
+        LIST_READ_CONCURRENCY,
+        (key) => this.readRow(key)
+      );
+      for (const current of rows) {
+        if (current && !current.env.deleted) yield current.env.record;
+      }
+      token = res.IsTruncated === true ? res.NextContinuationToken : void 0;
+    } while (token !== void 0);
+  }
+  async delete(ref) {
+    const key = registryObjectKey(this.prefix, ref);
+    for (let attempt = 0; attempt < MAX_DELETE_ATTEMPTS; attempt++) {
+      const current = await this.readRow(key);
+      if (current === null || current.env.deleted) return;
+      const token = String(registryCounterOf(current.env.record) + 1);
+      const env = {
+        deleted: true,
+        record: { ...current.env.record, token, updatedAt: this.now() }
+      };
+      try {
+        await this.putRow(key, env, { ifMatch: current.etag });
+        return;
+      } catch (err) {
+        if (isWriteConflictError(err)) continue;
+        throw err;
+      }
+    }
+    throw new WriteConflictError(
+      `registry delete: contention tombstoning "${ref.segment}" \u2014 retry`
+    );
+  }
+  /** GET + parse a registry object, returning its envelope + ETag (for a later If-Match), or null if absent. */
+  async readRow(objectKey) {
+    let res;
+    try {
+      res = await this.client.send(new clientS3.GetObjectCommand({ Bucket: this.bucket, Key: objectKey }));
+    } catch (err) {
+      if (isNotFound(err)) return null;
+      throw this.mapError(err);
+    }
+    if ((res.ContentLength ?? 0) > MAX_ROW_BYTES) {
+      throw new IntegrityError(
+        `registry object ${res.ContentLength}B exceeds cap ${MAX_ROW_BYTES}B`
+      );
+    }
+    if (res.Body === void 0) {
+      throw new IntegrityError(`registry object has an empty body: ${objectKey}`);
+    }
+    const bytes = await res.Body.transformToByteArray();
+    if (bytes.length > MAX_ROW_BYTES) {
+      throw new IntegrityError(`registry object ${bytes.length}B exceeds cap ${MAX_ROW_BYTES}B`);
+    }
+    const env = parseRegistryEnvelope(Buffer.from(bytes).toString("utf8"), objectKey);
+    if (res.ETag === void 0 || res.ETag.length === 0) {
+      throw new IntegrityError(
+        `registry object has no ETag (needed for compare-and-swap): ${objectKey}`
+      );
+    }
+    return { env, etag: res.ETag };
+  }
+  /** Conditional PUT of an envelope; maps a `412` precondition failure to {@link WriteConflictError}. */
+  async putRow(objectKey, env, cond) {
+    const Body = Buffer.from(serializeRegistryEnvelope(env), "utf8");
+    if (Body.length > MAX_ROW_BYTES) {
+      throw new ValidationError(`registry object ${Body.length}B exceeds cap ${MAX_ROW_BYTES}B`);
+    }
+    try {
+      await this.client.send(
+        new clientS3.PutObjectCommand({
+          Bucket: this.bucket,
+          Key: objectKey,
+          Body,
+          ContentType: "application/json",
+          IfNoneMatch: "ifNoneMatch" in cond ? cond.ifNoneMatch : void 0,
+          IfMatch: "ifMatch" in cond ? cond.ifMatch : void 0
+        })
+      );
+    } catch (err) {
+      if (isConditionalConflict(err)) {
+        throw new WriteConflictError(`registry OCC conflict for ${objectKey}`);
+      }
+      throw this.mapError(err);
+    }
+  }
+  /** Reclassify a transient S3 fault as a retryable {@link TransientError}; pass everything else through. */
+  mapError(err) {
+    if (isTransient(err)) {
+      return new TransientError(
+        `transient S3 fault: ${err?.name ?? "unknown"}`,
+        { cause: err }
+      );
+    }
+    return err;
+  }
+};
+
+exports.S3ColdDriver = S3ColdDriver;
+exports.S3RegistryDriver = S3RegistryDriver;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map