@cloudbitmaps/core 0.9.0 → 0.10.0

package/dist/mongodb/index.js

@@ -1,199 +0,0 @@
-import { NO_ROW } from '../chunk-OZ6LAFV4.js';
-import { ValidationError, WriteConflictError, IntegrityError, TransientError, validateChunkRef, namespacePart, validateSegmentRef } from '../chunk-NUIDEEFZ.js';
-import { randomUUID } from 'crypto';
-
-// src/drivers/mongodb/keys.ts
-function normalizeKeyPrefix(prefix) {
-  if (prefix === void 0 || prefix === "") return "";
-  for (const ch of prefix) {
-    if (ch.charCodeAt(0) < 32 || ch === "|") {
-      throw new ValidationError('keyPrefix must not contain "|" or control characters');
-    }
-  }
-  return prefix;
-}
-function segmentScope(prefix, ref) {
-  validateSegmentRef(ref);
-  return { kp: prefix, ns: namespacePart(ref.namespace), seg: ref.segment };
-}
-function chunkDocId(prefix, ref) {
-  validateChunkRef(ref);
-  return `${prefix}|${namespacePart(ref.namespace)}|${ref.segment}|${ref.chunkKey}`;
-}
-
-// src/drivers/mongodb/mongodb-errors.ts
-function serverCode(err) {
-  const code = err?.code;
-  return typeof code === "number" ? code : void 0;
-}
-function networkCode(err) {
-  const code = err?.code;
-  return typeof code === "string" && /^E[A-Z_]+$/.test(code) ? code : void 0;
-}
-function isDuplicateKey(err) {
-  const code = serverCode(err);
-  return code === 11e3 || code === 11001;
-}
-var RETRYABLE_CODES = /* @__PURE__ */ new Set([
-  6,
-  // HostUnreachable
-  7,
-  // HostNotFound
-  89,
-  // NetworkTimeout
-  91,
-  // ShutdownInProgress
-  189,
-  // PrimarySteppedDown
-  262,
-  // ExceededTimeLimit
-  9001,
-  // SocketException
-  10107,
-  // NotWritablePrimary
-  11600,
-  // InterruptedAtShutdown
-  11602,
-  // InterruptedDueToReplStateChange
-  13435,
-  // NotPrimaryNoSecondaryOk
-  13436,
-  // NotPrimaryOrSecondary
-  63,
-  // StaleShardVersion
-  150
-  // StaleEpoch
-]);
-function isTransient(err) {
-  if (isDuplicateKey(err)) return false;
-  const name = err?.name;
-  if (name === "MongoNetworkError" || name === "MongoServerSelectionError") return true;
-  const hasLabel = err?.hasErrorLabel;
-  if (typeof hasLabel === "function") {
-    if (hasLabel.call(err, "RetryableWriteError") || hasLabel.call(err, "TransientTransactionError")) {
-      return true;
-    }
-  }
-  const code = serverCode(err);
-  if (code !== void 0 && RETRYABLE_CODES.has(code)) return true;
-  const net = networkCode(err);
-  return net === "ECONNRESET" || net === "ECONNABORTED" || net === "ETIMEDOUT" || net === "ESOCKETTIMEDOUT" || net === "ECONNREFUSED" || net === "EHOSTUNREACH" || net === "ENETUNREACH" || net === "EPIPE" || net === "EAI_AGAIN" || net === "ENOTFOUND";
-}
-
-// src/drivers/mongodb/warm.ts
-var DEFAULT_COLLECTION = "cloud_roaring_warm";
-var INDEX_NAME = "cr_warm_scope_ck";
-var DEFAULT_BATCH = 500;
-var SIMPLE_COLLATION = { locale: "simple" };
-async function ensureMongoWarmIndexes(db, collection = DEFAULT_COLLECTION) {
-  await db.collection(collection).createIndex(
-    { kp: 1, ns: 1, seg: 1, ck: 1 },
-    { name: INDEX_NAME, collation: SIMPLE_COLLATION }
-  );
-}
-var MongoWarmDriver = class {
-  col;
-  keyPrefix;
-  batch;
-  constructor(options) {
-    this.keyPrefix = normalizeKeyPrefix(options.keyPrefix);
-    const batch = options.listPageSize ?? DEFAULT_BATCH;
-    if (!Number.isSafeInteger(batch) || batch < 1) {
-      throw new ValidationError(`listPageSize must be a positive safe integer; got ${batch}`);
-    }
-    this.batch = batch;
-    this.col = options.db.collection(options.collection ?? DEFAULT_COLLECTION);
-  }
-  // Reads are strongly consistent when the Db targets the primary (see the `db` option), so the optional
-  // `WarmReadOptions` hint would be a no-op — the structurally-optional param is simply omitted, as in the
-  // LocalFs / Postgres / Redis drivers.
-  async get(ref) {
-    const _id = chunkDocId(this.keyPrefix, ref);
-    let doc;
-    try {
-      doc = await this.col.findOne({ _id }, { collation: SIMPLE_COLLATION });
-    } catch (err) {
-      throw this.mapError(err);
-    }
-    return doc === null ? null : this.rowFrom(doc, ref.chunkKey);
-  }
-  async putConditional(ref, bytes, expected) {
-    const _id = chunkDocId(this.keyPrefix, ref);
-    const token = randomUUID();
-    const payload = Buffer.from(bytes);
-    try {
-      if (expected === NO_ROW) {
-        const { kp, ns, seg } = segmentScope(this.keyPrefix, ref);
-        await this.col.insertOne({ _id, kp, ns, seg, ck: ref.chunkKey, token, payload });
-      } else {
-        const res = await this.col.updateOne(
-          { _id, token: expected },
-          { $set: { token, payload } },
-          { collation: SIMPLE_COLLATION }
-        );
-        if (res.matchedCount !== 1) {
-          throw new WriteConflictError(`OCC conflict on chunk ${ref.chunkKey}`);
-        }
-      }
-      return { token };
-    } catch (err) {
-      if (isDuplicateKey(err)) {
-        throw new WriteConflictError(`chunk ${ref.chunkKey} already exists (create-if-absent)`);
-      }
-      throw this.mapError(err);
-    }
-  }
-  async deleteConditional(ref, expected) {
-    const _id = chunkDocId(this.keyPrefix, ref);
-    let deletedCount;
-    try {
-      deletedCount = (await this.col.deleteOne({ _id, token: expected }, { collation: SIMPLE_COLLATION })).deletedCount;
-    } catch (err) {
-      throw this.mapError(err);
-    }
-    if (deletedCount !== 1) {
-      throw new WriteConflictError(`fenced-delete conflict on chunk ${ref.chunkKey}`);
-    }
-  }
-  async *listChunks(ref) {
-    const scope = segmentScope(this.keyPrefix, ref);
-    const cursor = this.col.find(scope, { collation: SIMPLE_COLLATION }).sort({ ck: 1 }).batchSize(this.batch);
-    try {
-      for await (const doc of cursor) {
-        if (typeof doc.ck !== "number") {
-          throw new IntegrityError("warm doc is missing its numeric chunk key (ck)");
-        }
-        yield { chunkKey: doc.ck, ...this.rowFrom(doc, doc.ck) };
-      }
-    } catch (err) {
-      throw this.mapError(err);
-    }
-  }
-  /** Build a {@link WarmRow} from a doc; reject one missing/!typed fields (corrupt/foreign). */
-  rowFrom(doc, chunkKey) {
-    if (typeof doc.token !== "string" || doc.token === "") {
-      throw new IntegrityError(`warm doc for chunk ${chunkKey} is missing its token`);
-    }
-    return { token: doc.token, bytes: decodePayload(doc.payload, chunkKey) };
-  }
-  /** Reclassify a transient Mongo fault as a retryable {@link TransientError}; else propagate unchanged. */
-  mapError(err) {
-    if (isTransient(err)) {
-      return new TransientError(
-        `transient MongoDB fault: ${err?.message ?? "unknown"}`,
-        { cause: err }
-      );
-    }
-    return err;
-  }
-};
-function decodePayload(p, chunkKey) {
-  if (p instanceof Uint8Array) return new Uint8Array(p);
-  const inner = p?.buffer;
-  if (inner instanceof Uint8Array) return new Uint8Array(inner);
-  throw new IntegrityError(`warm doc for chunk ${chunkKey} has no readable payload`);
-}
-
-export { MongoWarmDriver, ensureMongoWarmIndexes };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/mongodb/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/drivers/mongodb/keys.ts","../../src/drivers/mongodb/mongodb-errors.ts","../../src/drivers/mongodb/warm.ts"],"names":[],"mappings":";;;;;AA2BO,SAAS,mBAAmB,MAAA,EAAoC;AACrE,EAAA,IAAI,MAAA,KAAW,MAAA,IAAa,MAAA,KAAW,EAAA,EAAI,OAAO,EAAA;AAClD,EAAA,KAAA,MAAW,MAAM,MAAA,EAAQ;AACvB,IAAA,IAAI,GAAG,UAAA,CAAW,CAAC,CAAA,GAAI,EAAA,IAAQ,OAAO,GAAA,EAAK;AACzC,MAAA,MAAM,IAAI,gBAAgB,sDAAsD,CAAA;AAAA,IAClF;AAAA,EACF;AACA,EAAA,OAAO,MAAA;AACT;AAGO,SAAS,YAAA,CAAa,QAAgB,GAAA,EAA+B;AAC1E,EAAA,kBAAA,CAAmB,GAAG,CAAA;AACtB,EAAA,OAAO,EAAE,EAAA,EAAI,MAAA,EAAQ,EAAA,EAAI,aAAA,CAAc,IAAI,SAAS,CAAA,EAAG,GAAA,EAAK,GAAA,CAAI,OAAA,EAAQ;AAC1E;AAGO,SAAS,UAAA,CAAW,QAAgB,GAAA,EAAuB;AAChE,EAAA,gBAAA,CAAiB,GAAG,CAAA;AACpB,EAAA,OAAO,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,aAAA,CAAc,GAAA,CAAI,SAAS,CAAC,CAAA,CAAA,EAAI,GAAA,CAAI,OAAO,CAAA,CAAA,EAAI,GAAA,CAAI,QAAQ,CAAA,CAAA;AACjF;;;ACrCA,SAAS,WAAW,GAAA,EAAkC;AACpD,EAAA,MAAM,OAAQ,GAAA,EAAmC,IAAA;AACjD,EAAA,OAAO,OAAO,IAAA,KAAS,QAAA,GAAW,IAAA,GAAO,MAAA;AAC3C;AAGA,SAAS,YAAY,GAAA,EAAkC;AACrD,EAAA,MAAM,OAAQ,GAAA,EAAmC,IAAA;AACjD,EAAA,OAAO,OAAO,IAAA,KAAS,QAAA,IAAY,aAAa,IAAA,CAAK,IAAI,IAAI,IAAA,GAAO,MAAA;AACtE;AAGO,SAAS,eAAe,GAAA,EAAuB;AACpD,EAAA,MAAM,IAAA,GAAO,WAAW,GAAG,CAAA;AAC3B,EAAA,OAAO,IAAA,KAAS,QAAS,IAAA,KAAS,KAAA;AACpC;AAOA,IAAM,eAAA,uBAAsB,GAAA,CAAY;AAAA,EACtC,CAAA;AAAA;AAAA,EACA,CAAA;AAAA;AAAA,EACA,EAAA;AAAA;AAAA,EACA,EAAA;AAAA;AAAA,EACA,GAAA;AAAA;AAAA,EACA,GAAA;AAAA;AAAA,EACA,IAAA;AAAA;AAAA,EACA,KAAA;AAAA;AAAA,EACA,KAAA;AAAA;AAAA,EACA,KAAA;AAAA;AAAA,EACA,KAAA;AAAA;AAAA,EACA,KAAA;AAAA;AAAA,EACA,EAAA;AAAA;AAAA,EACA;AAAA;AACF,CAAC,CAAA;AAOM,SAAS,YAAY,GAAA,EAAuB;AACjD,EAAA,IAAI,cAAA,CAAe,GAAG,CAAA,EAAG,OAAO,KAAA;AAChC,EAAA,MAAM,OAAQ,GAAA,EAAmC,IAAA;AACjD,EAAA,IAAI,IAAA,KAAS,mBAAA,IAAuB,IAAA,KAAS,2BAAA,EAA6B,OAAO,IAAA;AACjF,EAAA,MAAM,WAAY,GAAA,EAA2D,aAAA;AAC7E,EAAA,IAAI,OAAO,aAAa,UAAA,EAAY;AAClC,IAAA,IACE,QAAA,CAAS,KAAK,GAAA,EAAK,qBAAqB,KACxC,QAAA,CAAS,IAAA,CAAK,GAAA,EAAK,2BAA2B,CAAA,EAC9C;AACA,MAAA,OAAO,IAAA;AAAA,IACT;AAAA,EACF;AACA,EAAA,MAAM,IAAA,GAAO,WAAW,GAAG,CAAA;AAC3B,EAAA,IAAI,SAAS,MAAA,IAAa,eAAA,CAAgB,GAAA,CAAI,IAAI,GAAG,OAAO,IAAA;AAC5D,EAAA,MAAM,GAAA,GAAM,YAAY,GAAG,CAAA;AAC3B,EAAA,OACE,QAAQ,YAAA,IACR,GAAA,KAAQ,kBACR,GAAA,KAAQ,WAAA,IACR,QAAQ,iBAAA,IACR,GAAA,KAAQ,cAAA,IACR,GAAA,KAAQ,kBACR,GAAA,KAAQ,aAAA,IACR,QAAQ,OAAA,IACR,GAAA,KAAQ,eACR,GAAA,KAAQ,WAAA;AAEZ;;;ACvDA,IAAM,kBAAA,GAAqB,oBAAA;AAC3B,IAAM,UAAA,GAAa,kBAAA;AAEnB,IAAM,aAAA,GAAgB,GAAA;AAatB,IAAM,gBAAA,GAAmB,EAAE,MAAA,EAAQ,QAAA,EAAS;AAmC5C,eAAsB,sBAAA,CACpB,EAAA,EACA,UAAA,GAAqB,kBAAA,EACN;AACf,EAAA,MAAM,EAAA,CACH,UAAA,CAAW,UAAU,CAAA,CACrB,WAAA;AAAA,IACC,EAAE,IAAI,CAAA,EAAG,EAAA,EAAI,GAAG,GAAA,EAAK,CAAA,EAAG,IAAI,CAAA,EAAE;AAAA,IAC9B,EAAE,IAAA,EAAM,UAAA,EAAY,SAAA,EAAW,gBAAA;AAAiB,GAClD;AACJ;AAEO,IAAM,kBAAN,MAA6C;AAAA,EACjC,GAAA;AAAA,EACA,SAAA;AAAA,EACA,KAAA;AAAA,EAEjB,YAAY,OAAA,EAAiC;AAC3C,IAAA,IAAA,CAAK,SAAA,GAAY,kBAAA,CAAmB,OAAA,CAAQ,SAAS,CAAA;AACrD,IAAA,MAAM,KAAA,GAAQ,QAAQ,YAAA,IAAgB,aAAA;AACtC,IAAA,IAAI,CAAC,MAAA,CAAO,aAAA,CAAc,KAAK,CAAA,IAAK,QAAQ,CAAA,EAAG;AAC7C,MAAA,MAAM,IAAI,eAAA,CAAgB,CAAA,kDAAA,EAAqD,KAAK,CAAA,CAAE,CAAA;AAAA,IACxF;AACA,IAAA,IAAA,CAAK,KAAA,GAAQ,KAAA;AACb,IAAA,IAAA,CAAK,MAAM,OAAA,CAAQ,EAAA,CAAG,UAAA,CAAoB,OAAA,CAAQ,cAAc,kBAAkB,CAAA;AAAA,EACpF;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,IAAI,GAAA,EAAwC;AAChD,IAAA,MAAM,GAAA,GAAM,UAAA,CAAW,IAAA,CAAK,SAAA,EAAW,GAAG,CAAA;AAC1C,IAAA,IAAI,GAAA;AACJ,IAAA,IAAI;AACF,MAAA,GAAA,GAAM,MAAM,IAAA,CAAK,GAAA,CAAI,OAAA,CAAQ,EAAE,KAAI,EAAG,EAAE,SAAA,EAAW,gBAAA,EAAkB,CAAA;AAAA,IACvE,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,IAAA,CAAK,SAAS,GAAG,CAAA;AAAA,IACzB;AACA,IAAA,OAAO,QAAQ,IAAA,GAAO,IAAA,GAAO,KAAK,OAAA,CAAQ,GAAA,EAAK,IAAI,QAAQ,CAAA;AAAA,EAC7D;AAAA,EAEA,MAAM,cAAA,CACJ,GAAA,EACA,KAAA,EACA,QAAA,EAC2B;AAC3B,IAAA,MAAM,GAAA,GAAM,UAAA,CAAW,IAAA,CAAK,SAAA,EAAW,GAAG,CAAA;AAC1C,IAAA,MAAM,QAAQ,UAAA,EAAW;AACzB,IAAA,MAAM,OAAA,GAAU,MAAA,CAAO,IAAA,CAAK,KAAK,CAAA;AACjC,IAAA,IAAI;AACF,MAAA,IAAI,aAAa,MAAA,EAAQ;AACvB,QAAA,MAAM,EAAE,IAAI,EAAA,EAAI,GAAA,KAAQ,YAAA,CAAa,IAAA,CAAK,WAAW,GAAG,CAAA;AACxD,QAAA,MAAM,IAAA,CAAK,GAAA,CAAI,SAAA,CAAU,EAAE,GAAA,EAAK,EAAA,EAAI,EAAA,EAAI,GAAA,EAAK,EAAA,EAAI,GAAA,CAAI,QAAA,EAAU,KAAA,EAAO,SAAS,CAAA;AAAA,MACjF,CAAA,MAAO;AACL,QAAA,MAAM,GAAA,GAAM,MAAM,IAAA,CAAK,GAAA,CAAI,SAAA;AAAA,UACzB,EAAE,GAAA,EAAK,KAAA,EAAO,QAAA,EAAS;AAAA,UACvB,EAAE,IAAA,EAAM,EAAE,KAAA,EAAO,SAAQ,EAAE;AAAA,UAC3B,EAAE,WAAW,gBAAA;AAAiB,SAChC;AACA,QAAA,IAAI,GAAA,CAAI,iBAAiB,CAAA,EAAG;AAC1B,UAAA,MAAM,IAAI,kBAAA,CAAmB,CAAA,sBAAA,EAAyB,GAAA,CAAI,QAAQ,CAAA,CAAE,CAAA;AAAA,QACtE;AAAA,MACF;AACA,MAAA,OAAO,EAAE,KAAA,EAAM;AAAA,IACjB,SAAS,GAAA,EAAK;AAEZ,MAAA,IAAI,cAAA,CAAe,GAAG,CAAA,EAAG;AACvB,QAAA,MAAM,IAAI,kBAAA,CAAmB,CAAA,MAAA,EAAS,GAAA,CAAI,QAAQ,CAAA,kCAAA,CAAoC,CAAA;AAAA,MACxF;AACA,MAAA,MAAM,IAAA,CAAK,SAAS,GAAG,CAAA;AAAA,IACzB;AAAA,EACF;AAAA,EAEA,MAAM,iBAAA,CAAkB,GAAA,EAAe,QAAA,EAAgC;AACrE,IAAA,MAAM,GAAA,GAAM,UAAA,CAAW,IAAA,CAAK,SAAA,EAAW,GAAG,CAAA;AAC1C,IAAA,IAAI,YAAA;AACJ,IAAA,IAAI;AACF,MAAA,YAAA,GAAA,CACE,MAAM,IAAA,CAAK,GAAA,CAAI,SAAA,CAAU,EAAE,GAAA,EAAK,KAAA,EAAO,QAAA,EAAS,EAAG,EAAE,SAAA,EAAW,gBAAA,EAAkB,CAAA,EAClF,YAAA;AAAA,IACJ,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,IAAA,CAAK,SAAS,GAAG,CAAA;AAAA,IACzB;AACA,IAAA,IAAI,iBAAiB,CAAA,EAAG;AACtB,MAAA,MAAM,IAAI,kBAAA,CAAmB,CAAA,gCAAA,EAAmC,GAAA,CAAI,QAAQ,CAAA,CAAE,CAAA;AAAA,IAChF;AAAA,EACF;AAAA,EAEA,OAAO,WAAW,GAAA,EAAgE;AAChF,IAAA,MAAM,KAAA,GAAQ,YAAA,CAAa,IAAA,CAAK,SAAA,EAAW,GAAG,CAAA;AAK9C,IAAA,MAAM,SAAS,IAAA,CAAK,GAAA,CACjB,KAAK,KAAA,EAAO,EAAE,WAAW,gBAAA,EAAkB,CAAA,CAC3C,IAAA,CAAK,EAAE,EAAA,EAAI,CAAA,EAAG,CAAA,CACd,SAAA,CAAU,KAAK,KAAK,CAAA;AACvB,IAAA,IAAI;AACF,MAAA,WAAA,MAAiB,OAAO,MAAA,EAAQ;AAG9B,QAAA,IAAI,OAAO,GAAA,CAAI,EAAA,KAAO,QAAA,EAAU;AAC9B,UAAA,MAAM,IAAI,eAAe,gDAAgD,CAAA;AAAA,QAC3E;AACA,QAAA,MAAM,EAAE,QAAA,EAAU,GAAA,CAAI,EAAA,EAAI,GAAG,KAAK,OAAA,CAAQ,GAAA,EAAK,GAAA,CAAI,EAAE,CAAA,EAAE;AAAA,MACzD;AAAA,IACF,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,IAAA,CAAK,SAAS,GAAG,CAAA;AAAA,IACzB;AAAA,EACF;AAAA;AAAA,EAGQ,OAAA,CAAQ,KAAc,QAAA,EAA2B;AACvD,IAAA,IAAI,OAAO,GAAA,CAAI,KAAA,KAAU,QAAA,IAAY,GAAA,CAAI,UAAU,EAAA,EAAI;AACrD,MAAA,MAAM,IAAI,cAAA,CAAe,CAAA,mBAAA,EAAsB,QAAQ,CAAA,qBAAA,CAAuB,CAAA;AAAA,IAChF;AACA,IAAA,OAAO,EAAE,OAAO,GAAA,CAAI,KAAA,EAAO,OAAO,aAAA,CAAc,GAAA,CAAI,OAAA,EAAS,QAAQ,CAAA,EAAE;AAAA,EACzE;AAAA;AAAA,EAGQ,SAAS,GAAA,EAAuB;AACtC,IAAA,IAAI,WAAA,CAAY,GAAG,CAAA,EAAG;AACpB,MAAA,OAAO,IAAI,cAAA;AAAA,QACT,CAAA,yBAAA,EAA6B,GAAA,EAAsC,OAAA,IAAW,SAAS,CAAA,CAAA;AAAA,QACvF,EAAE,OAAO,GAAA;AAAI,OACf;AAAA,IACF;AACA,IAAA,OAAO,GAAA;AAAA,EACT;AACF;AAOA,SAAS,aAAA,CAAc,GAAY,QAAA,EAA8B;AAC/D,EAAA,IAAI,CAAA,YAAa,UAAA,EAAY,OAAO,IAAI,WAAW,CAAC,CAAA;AACpD,EAAA,MAAM,QAAS,CAAA,EAAmC,MAAA;AAClD,EAAA,IAAI,KAAA,YAAiB,UAAA,EAAY,OAAO,IAAI,WAAW,KAAK,CAAA;AAC5D,EAAA,MAAM,IAAI,cAAA,CAAe,CAAA,mBAAA,EAAsB,QAAQ,CAAA,wBAAA,CAA0B,CAAA;AACnF","file":"index.js","sourcesContent":["/**\n * Logical-ref → MongoDB document-id mapping for {@link MongoWarmDriver} (Phase 7).\n *\n * Pure, SDK-free string logic — unit-testable without a live MongoDB. Each chunk is one document with a\n * **deterministic composite `_id`** `<prefix>|<ns>|<seg>|<chunkKey>`, so create-if-absent is a plain\n * `insertOne` (a duplicate `_id` → the unique-index conflict, no extra index needed) and `get` is a direct\n * `_id` lookup. The ref fields are ALSO stored as separate typed fields (`kp`/`ns`/`seg`/`ck`) so `listChunks`\n * can query + **numerically** sort by `ck` (an `_id`-string sort would order `10` before `9`). The name grammar\n * (validateSegmentRef) forbids `|` in ns/seg and {@link normalizeKeyPrefix} forbids it in the prefix, so the\n * `|`-joined id is unambiguous.\n */\nimport { ValidationError } from '@/core/errors';\nimport { validateChunkRef, validateSegmentRef } from '@/core/validate';\nimport type { ChunkRef, SegmentRef } from '@/core/ports';\nimport { namespacePart } from '../_shared/keys';\n\n/** The scope fields shared by every doc of a segment — the `listChunks` filter. */\nexport interface SegmentScope {\n  kp: string;\n  ns: string;\n  seg: string;\n}\n\n/**\n * Validate a caller-supplied key prefix: no control characters and no `|` (the composite-`_id` delimiter), so\n * it can neither corrupt an id nor alias another prefix. Empty/undefined ⇒ no prefix (stored as `''`).\n */\nexport function normalizeKeyPrefix(prefix: string | undefined): string {\n  if (prefix === undefined || prefix === '') return '';\n  for (const ch of prefix) {\n    if (ch.charCodeAt(0) < 0x20 || ch === '|') {\n      throw new ValidationError('keyPrefix must not contain \"|\" or control characters');\n    }\n  }\n  return prefix;\n}\n\n/** The scope filter for all of a segment's chunk docs. Validates the ref. */\nexport function segmentScope(prefix: string, ref: SegmentRef): SegmentScope {\n  validateSegmentRef(ref);\n  return { kp: prefix, ns: namespacePart(ref.namespace), seg: ref.segment };\n}\n\n/** The deterministic `_id` of one chunk's doc: `<prefix>|<ns>|<seg>|<chunkKey>`. Validates the full ref. */\nexport function chunkDocId(prefix: string, ref: ChunkRef): string {\n  validateChunkRef(ref);\n  return `${prefix}|${namespacePart(ref.namespace)}|${ref.segment}|${ref.chunkKey}`;\n}\n","/**\n * Pure helpers for classifying MongoDB (`mongodb`) errors (Phase 7; transient class mirrors the other drivers).\n *\n * SDK-free + side-effect-free — they read only structural shapes off the thrown value (`err.code`, `err.name`,\n * the driver's `hasErrorLabel`, or a Node socket code). The driver signals a create-if-absent conflict itself\n * (a duplicate-key error, {@link isDuplicateKey}) and a token-fenced conflict via a 0 matched/deleted count,\n * so there's no general OCC classifier here — only duplicate-key + transient-vs-not.\n */\n\n/** A MongoDB numeric server error code, if present (`err.code`). */\nfunction serverCode(err: unknown): number | undefined {\n  const code = (err as { code?: unknown } | null)?.code;\n  return typeof code === 'number' ? code : undefined;\n}\n\n/** A Node system/socket error `code` string (starts with `E`, uppercase letters + underscore, no digits). */\nfunction networkCode(err: unknown): string | undefined {\n  const code = (err as { code?: unknown } | null)?.code;\n  return typeof code === 'string' && /^E[A-Z_]+$/.test(code) ? code : undefined;\n}\n\n/** A create-if-absent lost the race — the `_id` already existed (duplicate key: 11000 / 11001). */\nexport function isDuplicateKey(err: unknown): boolean {\n  const code = serverCode(err);\n  return code === 11000 || code === 11001;\n}\n\n/**\n * Retryable MongoDB server error codes: failover / primary-stepdown / node-unreachable / shutdown / network\n * timeouts. (Names from the server error catalogue.) These are safe to retry; deterministic errors\n * (BadValue, duplicate key, etc.) are not listed, so they surface.\n */\nconst RETRYABLE_CODES = new Set<number>([\n  6, // HostUnreachable\n  7, // HostNotFound\n  89, // NetworkTimeout\n  91, // ShutdownInProgress\n  189, // PrimarySteppedDown\n  262, // ExceededTimeLimit\n  9001, // SocketException\n  10107, // NotWritablePrimary\n  11600, // InterruptedAtShutdown\n  11602, // InterruptedDueToReplStateChange\n  13435, // NotPrimaryNoSecondaryOk\n  13436, // NotPrimaryOrSecondary\n  63, // StaleShardVersion\n  150, // StaleEpoch\n]);\n\n/**\n * A transient MongoDB fault safe to retry: a network error, a server-selection timeout, a driver retryable\n * label (`RetryableWriteError` / `TransientTransactionError`), a retryable server code, or a dropped socket.\n * A duplicate-key error is NOT transient (it's the deterministic create-if-absent conflict).\n */\nexport function isTransient(err: unknown): boolean {\n  if (isDuplicateKey(err)) return false;\n  const name = (err as { name?: unknown } | null)?.name;\n  if (name === 'MongoNetworkError' || name === 'MongoServerSelectionError') return true;\n  const hasLabel = (err as { hasErrorLabel?: (l: string) => boolean } | null)?.hasErrorLabel;\n  if (typeof hasLabel === 'function') {\n    if (\n      hasLabel.call(err, 'RetryableWriteError') ||\n      hasLabel.call(err, 'TransientTransactionError')\n    ) {\n      return true;\n    }\n  }\n  const code = serverCode(err);\n  if (code !== undefined && RETRYABLE_CODES.has(code)) return true;\n  const net = networkCode(err);\n  return (\n    net === 'ECONNRESET' ||\n    net === 'ECONNABORTED' ||\n    net === 'ETIMEDOUT' ||\n    net === 'ESOCKETTIMEDOUT' ||\n    net === 'ECONNREFUSED' ||\n    net === 'EHOSTUNREACH' ||\n    net === 'ENETUNREACH' ||\n    net === 'EPIPE' ||\n    net === 'EAI_AGAIN' ||\n    net === 'ENOTFOUND'\n  );\n}\n","/**\n * `MongoWarmDriver` — an {@link IWarmDriver} over MongoDB / DocumentDB (Phase 7).\n *\n * Uses the official `mongodb` driver, an **optional peer dependency** — only consumers of\n * `cloud-roaring/mongodb` install it. A `Db` is **injected** (dependency injection): the driver owns no\n * connection/credential logic, so it's thin and reuses the caller's client.\n *\n * Each chunk is one document keyed by a deterministic composite `_id` (`<prefix>|<ns>|<seg>|<chunkKey>`) with\n * an opaque OCC **token** (a random UUID per write) and the delta `payload` (BSON binary). Optimistic\n * concurrency is per-document and server-side:\n * - **create-if-absent** = `insertOne` with that `_id`; a duplicate-key error ⇒ {@link WriteConflictError}.\n * - **token-fenced update / delete** = `updateOne` / `deleteOne` filtered on `{ _id, token: expected }`; a 0\n *   matched/deleted count ⇒ {@link WriteConflictError}.\n *\n * Each op is a single-document atomic operation, so no transaction is needed. Tokens are not reused across\n * delete→recreate (ABA-safe, D3 — probabilistic random UUID, like the Postgres/Redis drivers). Reads are\n * strongly consistent when the `Db` targets the primary (majority/primary read preference), which the OCC\n * read-modify-write requires — see the `db` option note. Drivers may use `node:crypto`.\n */\nimport { randomUUID } from 'node:crypto';\nimport type { Collection, Db } from 'mongodb';\nimport { IntegrityError, TransientError, ValidationError, WriteConflictError } from '@/core/errors';\nimport { NO_ROW } from '@/core/ports';\nimport type { ChunkRef, IWarmDriver, NoRow, SegmentRef, Token, WarmRow } from '@/core/ports';\nimport { chunkDocId, normalizeKeyPrefix, segmentScope } from './keys';\nimport { isDuplicateKey, isTransient } from './mongodb-errors';\n\nconst DEFAULT_COLLECTION = 'cloud_roaring_warm';\nconst INDEX_NAME = 'cr_warm_scope_ck';\n/** find() cursor batch — bounds resident docs on a very wide segment. */\nconst DEFAULT_BATCH = 500;\n/**\n * Force **binary (byte-exact) comparison** on every op + the index, overriding any case-/diacritic-insensitive\n * *default* collation the collection may have been created with. Grammar-legal segment/namespace names differ\n * only by case (`\"A\"` vs `\"a\"`) are distinct stores; under a case-insensitive default collation an unpinned\n * `findOne({_id})` / `updateOne` / `deleteOne` would match the *wrong* document → cross-segment read/leak and\n * wrong-doc OCC updates. This is the Mongo analogue of the MySQL `utf8mb4_bin` requirement. Operation-level\n * collation is binary in the common (no-default-collation) case, so this is a no-op there and a fix otherwise.\n * NOTE: `insertOne` uniqueness is governed by the `_id` index's collation, which cannot be overridden per-op —\n * so a collection created with a case-insensitive **default** collation can still collapse `\"a\"`/`\"A\"` on\n * *insert* (a spurious create-if-absent conflict, not a data leak). The operator guide states the warm\n * collection must use the simple default collation; this pin closes the get/update/delete/list matching hole.\n */\nconst SIMPLE_COLLATION = { locale: 'simple' } as const;\n\n/** One warm chunk document. */\ninterface WarmDoc {\n  _id: string;\n  kp: string;\n  ns: string;\n  seg: string;\n  ck: number;\n  token: string;\n  payload: unknown; // written as a Node Buffer; read back as a BSON Binary (or Buffer if promoteBuffers)\n}\n\nexport interface MongoWarmDriverOptions {\n  /**\n   * A `mongodb` `Db` (the driver calls `db.collection(...)`). The driver never connects/closes the client —\n   * the caller owns its lifecycle. Reads must be strongly consistent for OCC (read-your-writes): use a\n   * primary read preference (the default), not `secondary`/`secondaryPreferred`.\n   */\n  readonly db: Db;\n  /** Warm collection name (default `cloud_roaring_warm`). */\n  readonly collection?: string;\n  /** Optional key-prefix component of the composite `_id` so several logical stores can share one collection. */\n  readonly keyPrefix?: string;\n  /** Advanced: `listChunks` cursor batch size (default 500). Tunes peak memory on wide segments. */\n  readonly listPageSize?: number;\n}\n\n/**\n * Create the index `listChunks` needs — `{ kp, ns, seg, ck }` (scope filter + numeric ascending sort) —\n * idempotently. **Run this once at deploy time — it is effectively required, not merely an optimization:**\n * without it a `listChunks` over a segment whose dirty backlog exceeds MongoDB's 32 MB in-memory-sort ceiling\n * fails (server error 292, `QueryExceededMemoryLimitNoDiskUseAllowedException`) rather than merely running\n * slow. (create-if-absent needs no extra index — the composite `_id` is inherently unique.)\n */\nexport async function ensureMongoWarmIndexes(\n  db: Db,\n  collection: string = DEFAULT_COLLECTION,\n): Promise<void> {\n  await db\n    .collection(collection)\n    .createIndex(\n      { kp: 1, ns: 1, seg: 1, ck: 1 },\n      { name: INDEX_NAME, collation: SIMPLE_COLLATION },\n    );\n}\n\nexport class MongoWarmDriver implements IWarmDriver {\n  private readonly col: Collection<WarmDoc>;\n  private readonly keyPrefix: string;\n  private readonly batch: number;\n\n  constructor(options: MongoWarmDriverOptions) {\n    this.keyPrefix = normalizeKeyPrefix(options.keyPrefix);\n    const batch = options.listPageSize ?? DEFAULT_BATCH;\n    if (!Number.isSafeInteger(batch) || batch < 1) {\n      throw new ValidationError(`listPageSize must be a positive safe integer; got ${batch}`);\n    }\n    this.batch = batch;\n    this.col = options.db.collection<WarmDoc>(options.collection ?? DEFAULT_COLLECTION);\n  }\n\n  // Reads are strongly consistent when the Db targets the primary (see the `db` option), so the optional\n  // `WarmReadOptions` hint would be a no-op — the structurally-optional param is simply omitted, as in the\n  // LocalFs / Postgres / Redis drivers.\n  async get(ref: ChunkRef): Promise<WarmRow | null> {\n    const _id = chunkDocId(this.keyPrefix, ref); // validates ref\n    let doc: WarmDoc | null;\n    try {\n      doc = await this.col.findOne({ _id }, { collation: SIMPLE_COLLATION });\n    } catch (err) {\n      throw this.mapError(err);\n    }\n    return doc === null ? null : this.rowFrom(doc, ref.chunkKey);\n  }\n\n  async putConditional(\n    ref: ChunkRef,\n    bytes: Uint8Array,\n    expected: Token | NoRow,\n  ): Promise<{ token: Token }> {\n    const _id = chunkDocId(this.keyPrefix, ref); // validates ref\n    const token = randomUUID();\n    const payload = Buffer.from(bytes); // copy: severs any caller-owned/reused input buffer; stored as Binary\n    try {\n      if (expected === NO_ROW) {\n        const { kp, ns, seg } = segmentScope(this.keyPrefix, ref);\n        await this.col.insertOne({ _id, kp, ns, seg, ck: ref.chunkKey, token, payload });\n      } else {\n        const res = await this.col.updateOne(\n          { _id, token: expected },\n          { $set: { token, payload } },\n          { collation: SIMPLE_COLLATION },\n        );\n        if (res.matchedCount !== 1) {\n          throw new WriteConflictError(`OCC conflict on chunk ${ref.chunkKey}`);\n        }\n      }\n      return { token };\n    } catch (err) {\n      // A duplicate `_id` is the deterministic create-if-absent conflict — never a transient.\n      if (isDuplicateKey(err)) {\n        throw new WriteConflictError(`chunk ${ref.chunkKey} already exists (create-if-absent)`);\n      }\n      throw this.mapError(err); // WriteConflictError (from the update branch) passes straight through\n    }\n  }\n\n  async deleteConditional(ref: ChunkRef, expected: Token): Promise<void> {\n    const _id = chunkDocId(this.keyPrefix, ref); // validates ref\n    let deletedCount: number;\n    try {\n      deletedCount = (\n        await this.col.deleteOne({ _id, token: expected }, { collation: SIMPLE_COLLATION })\n      ).deletedCount;\n    } catch (err) {\n      throw this.mapError(err);\n    }\n    if (deletedCount !== 1) {\n      throw new WriteConflictError(`fenced-delete conflict on chunk ${ref.chunkKey}`);\n    }\n  }\n\n  async *listChunks(ref: SegmentRef): AsyncIterable<{ chunkKey: number } & WarmRow> {\n    const scope = segmentScope(this.keyPrefix, ref); // validates ref\n    // The driver's cursor streams in `batchSize` batches, so peak memory is bounded on a wide segment; the\n    // `{ kp, ns, seg, ck }` index (ensureMongoWarmIndexes) serves the filter + numeric ascending sort — and is\n    // effectively required: without it a wide segment's sort spills past MongoDB's 32 MB in-memory-sort limit\n    // and errors (292), not just runs slow.\n    const cursor = this.col\n      .find(scope, { collation: SIMPLE_COLLATION })\n      .sort({ ck: 1 })\n      .batchSize(this.batch);\n    try {\n      for await (const doc of cursor) {\n        // Validate the yielded chunkKey (untrusted-data posture, like the sibling drivers) — a foreign/corrupt\n        // doc matching the scope but lacking a numeric `ck` must not surface as `{ chunkKey: undefined }`.\n        if (typeof doc.ck !== 'number') {\n          throw new IntegrityError('warm doc is missing its numeric chunk key (ck)');\n        }\n        yield { chunkKey: doc.ck, ...this.rowFrom(doc, doc.ck) };\n      }\n    } catch (err) {\n      throw this.mapError(err);\n    }\n  }\n\n  /** Build a {@link WarmRow} from a doc; reject one missing/!typed fields (corrupt/foreign). */\n  private rowFrom(doc: WarmDoc, chunkKey: number): WarmRow {\n    if (typeof doc.token !== 'string' || doc.token === '') {\n      throw new IntegrityError(`warm doc for chunk ${chunkKey} is missing its token`);\n    }\n    return { token: doc.token, bytes: decodePayload(doc.payload, chunkKey) };\n  }\n\n  /** Reclassify a transient Mongo fault as a retryable {@link TransientError}; else propagate unchanged. */\n  private mapError(err: unknown): unknown {\n    if (isTransient(err)) {\n      return new TransientError(\n        `transient MongoDB fault: ${(err as { message?: unknown } | null)?.message ?? 'unknown'}`,\n        { cause: err },\n      );\n    }\n    return err;\n  }\n}\n\n/**\n * Decode a stored payload to owned bytes, duck-typed so the driver needs no runtime `mongodb`/`bson` import\n * (kept `import type`, so `cloud-roaring/mongodb`'s built bundle has no runtime SDK dependency). A Node\n * `Buffer` is a `Uint8Array` (the `promoteBuffers` case); a BSON `Binary` exposes its bytes on `.buffer`.\n */\nfunction decodePayload(p: unknown, chunkKey: number): Uint8Array {\n  if (p instanceof Uint8Array) return new Uint8Array(p); // Buffer / Uint8Array — copy\n  const inner = (p as { buffer?: unknown } | null)?.buffer; // BSON Binary → .buffer is a Buffer\n  if (inner instanceof Uint8Array) return new Uint8Array(inner);\n  throw new IntegrityError(`warm doc for chunk ${chunkKey} has no readable payload`);\n}\n"]}

package/dist/mysql/index.cjs

@@ -1,281 +0,0 @@
-'use strict';
-
-var crypto = require('crypto');
-
-// src/drivers/mysql/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 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";
-}
-
-// src/core/ports.ts
-var NO_ROW = /* @__PURE__ */ Symbol.for("cloud-roaring.no-row");
-
-// 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/mysql/keys.ts
-var IDENT = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
-function validateAndQuoteTable(table) {
-  const parts = table.split(".");
-  if (parts.length > 2 || parts.some((p) => !IDENT.test(p))) {
-    throw new ValidationError(
-      `invalid table name ${JSON.stringify(table)} \u2014 expected an identifier or "db.table" (letters, digits, underscore; \u226464 chars; leading letter/underscore)`
-    );
-  }
-  return parts.map((p) => `\`${p}\``).join(".");
-}
-var MAX_KEY_PREFIX_CHARS = 191;
-function normalizeKeyPrefix(prefix) {
-  if (prefix === void 0 || prefix === "") return "";
-  let chars = 0;
-  for (const ch of prefix) {
-    chars++;
-    if (ch.charCodeAt(0) < 32) {
-      throw new ValidationError("keyPrefix must not contain control characters");
-    }
-  }
-  if (chars > MAX_KEY_PREFIX_CHARS) {
-    throw new ValidationError(
-      `keyPrefix must be at most ${MAX_KEY_PREFIX_CHARS} characters (the key_prefix column width); got ${chars}`
-    );
-  }
-  return prefix;
-}
-
-// src/drivers/mysql/mysql-errors.ts
-function errno(err) {
-  const n = err?.errno;
-  return typeof n === "number" ? n : void 0;
-}
-function code(err) {
-  const c = err?.code;
-  return typeof c === "string" ? c : void 0;
-}
-function isDuplicateKey(err) {
-  return errno(err) === 1062 || code(err) === "ER_DUP_ENTRY";
-}
-function isTransient(err) {
-  const n = errno(err);
-  if (n === 1205 || // ER_LOCK_WAIT_TIMEOUT
-  n === 1213 || // ER_LOCK_DEADLOCK
-  n === 1040 || // ER_CON_COUNT_ERROR (too many connections)
-  n === 1203 || // ER_TOO_MANY_USER_CONNECTIONS
-  n === 1053 || // ER_SERVER_SHUTDOWN
-  n === 1927 || // ER_CONNECTION_KILLED
-  n === 2006 || // CR_SERVER_GONE_ERROR
-  n === 2013) {
-    return true;
-  }
-  const c = code(err);
-  return c === "PROTOCOL_CONNECTION_LOST" || c === "PROTOCOL_SEQUENCE_TIMEOUT" || c === "CR_SERVER_GONE_ERROR" || c === "CR_SERVER_LOST" || c === "ECONNRESET" || c === "ECONNABORTED" || c === "ETIMEDOUT" || c === "ESOCKETTIMEDOUT" || c === "ECONNREFUSED" || c === "EHOSTUNREACH" || c === "ENETUNREACH" || c === "EPIPE" || c === "EAI_AGAIN" || c === "ENOTFOUND";
-}
-
-// src/drivers/mysql/warm.ts
-var DEFAULT_TABLE = "cloud_roaring_warm";
-var DEFAULT_LIST_BATCH = 1e3;
-function mysqlWarmTableDDL(table = DEFAULT_TABLE) {
-  const t = validateAndQuoteTable(table);
-  return `CREATE TABLE IF NOT EXISTS ${t} (
-  key_prefix VARCHAR(191) NOT NULL,
-  namespace  VARCHAR(256) NOT NULL,
-  segment    VARCHAR(256) NOT NULL,
-  chunk_key  INT          NOT NULL,
-  token      CHAR(36)     NOT NULL,
-  payload    LONGBLOB     NOT NULL,
-  PRIMARY KEY (key_prefix, namespace, segment, chunk_key)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;`;
-}
-var MysqlWarmDriver = class {
-  pool;
-  table;
-  // validated + backtick-quoted for interpolation
-  keyPrefix;
-  listBatch;
-  constructor(options) {
-    this.pool = options.pool;
-    this.table = validateAndQuoteTable(options.table ?? DEFAULT_TABLE);
-    this.keyPrefix = normalizeKeyPrefix(options.keyPrefix);
-    const batch = options.listPageSize ?? DEFAULT_LIST_BATCH;
-    if (!Number.isSafeInteger(batch) || batch < 1) {
-      throw new ValidationError(`listPageSize must be a positive safe integer; got ${batch}`);
-    }
-    this.listBatch = batch;
-  }
-  // Reads are always strongly consistent (single primary), so the optional `WarmReadOptions` hint would be a
-  // no-op — the structurally-optional param is simply omitted (still satisfies IWarmDriver), as in LocalFs/pg.
-  async get(ref) {
-    validateChunkRef(ref);
-    try {
-      const [rows] = await this.pool.query(
-        `SELECT token, payload FROM ${this.table} WHERE key_prefix = ? AND namespace = ? AND segment = ? AND chunk_key = ?`,
-        [this.keyPrefix, namespacePart(ref.namespace), ref.segment, ref.chunkKey]
-      );
-      const row = rows[0];
-      return row === void 0 ? null : this.rowFrom(row, ref.chunkKey);
-    } catch (err) {
-      throw this.mapError(err);
-    }
-  }
-  async putConditional(ref, bytes, expected) {
-    validateChunkRef(ref);
-    const token = crypto.randomUUID();
-    const payload = Buffer.from(bytes);
-    const ns = namespacePart(ref.namespace);
-    try {
-      if (expected === NO_ROW) {
-        await this.pool.query(
-          `INSERT INTO ${this.table} (key_prefix, namespace, segment, chunk_key, token, payload) VALUES (?, ?, ?, ?, ?, ?)`,
-          [this.keyPrefix, ns, ref.segment, ref.chunkKey, token, payload]
-        );
-      } else {
-        const [res] = await this.pool.query(
-          `UPDATE ${this.table} SET token = ?, payload = ? WHERE key_prefix = ? AND namespace = ? AND segment = ? AND chunk_key = ? AND token = ?`,
-          [token, payload, this.keyPrefix, ns, ref.segment, ref.chunkKey, expected]
-        );
-        if (res.affectedRows !== 1) {
-          throw new WriteConflictError(`OCC conflict on chunk ${ref.chunkKey}`);
-        }
-      }
-      return { token };
-    } catch (err) {
-      if (isWriteConflictError(err)) throw err;
-      if (expected === NO_ROW && isDuplicateKey(err)) {
-        throw new WriteConflictError(`chunk ${ref.chunkKey} already exists (create-if-absent)`);
-      }
-      throw this.mapError(err);
-    }
-  }
-  async deleteConditional(ref, expected) {
-    validateChunkRef(ref);
-    try {
-      const [res] = await this.pool.query(
-        `DELETE FROM ${this.table} WHERE key_prefix = ? AND namespace = ? AND segment = ? AND chunk_key = ? AND token = ?`,
-        [this.keyPrefix, namespacePart(ref.namespace), ref.segment, ref.chunkKey, expected]
-      );
-      if (res.affectedRows !== 1) {
-        throw new WriteConflictError(`fenced-delete conflict on chunk ${ref.chunkKey}`);
-      }
-    } catch (err) {
-      if (isWriteConflictError(err)) throw err;
-      throw this.mapError(err);
-    }
-  }
-  async *listChunks(ref) {
-    validateSegmentRef(ref);
-    const ns = namespacePart(ref.namespace);
-    let after = -1;
-    for (; ; ) {
-      let rows;
-      try {
-        const [res] = await this.pool.query(
-          `SELECT chunk_key, token, payload FROM ${this.table} WHERE key_prefix = ? AND namespace = ? AND segment = ? AND chunk_key > ? ORDER BY chunk_key ASC LIMIT ?`,
-          [this.keyPrefix, ns, ref.segment, after, this.listBatch]
-        );
-        rows = res;
-      } catch (err) {
-        throw this.mapError(err);
-      }
-      for (const row of rows) {
-        const chunkKey = row.chunk_key;
-        if (typeof chunkKey !== "number") {
-          throw new IntegrityError("warm row is missing its chunk_key");
-        }
-        yield { chunkKey, ...this.rowFrom(row, chunkKey) };
-        after = chunkKey;
-      }
-      if (rows.length < this.listBatch) return;
-    }
-  }
-  /**
-   * Build a {@link WarmRow} from a raw row. `token` must be a non-empty string and `payload` a Buffer — a
-   * missing/typo'd column means a corrupt or foreign row, which we reject (untrusted-data posture) rather
-   * than paper over. The returned bytes are a fresh copy (driver-owned, read-only per the contract).
-   */
-  rowFrom(row, chunkKey) {
-    if (typeof row.token !== "string" || row.token === "") {
-      throw new IntegrityError(`warm row for chunk ${chunkKey} is missing its token`);
-    }
-    if (!(row.payload instanceof Uint8Array)) {
-      throw new IntegrityError(`warm row for chunk ${chunkKey} is missing its payload`);
-    }
-    return { token: row.token, bytes: new Uint8Array(row.payload) };
-  }
-  /**
-   * Reclassify a transient MySQL fault (lock-wait/deadlock, connection lost, too-many-connections, dropped
-   * socket) as a retryable {@link TransientError}; everything else propagates unchanged. Applied at every
-   * query site so callers + the retry decorator only ever see typed errors. A deterministic OCC/duplicate-key
-   * conflict is signalled by the driver itself — never reclassified here.
-   */
-  mapError(err) {
-    if (isTransient(err)) {
-      return new TransientError(
-        `transient MySQL fault: ${err?.code ?? err?.errno ?? "unknown"}`,
-        { cause: err }
-      );
-    }
-    return err;
-  }
-};
-
-exports.MysqlWarmDriver = MysqlWarmDriver;
-exports.mysqlWarmTableDDL = mysqlWarmTableDDL;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map