@cloudbitmaps/core 0.1.0-rc.0

package/dist/mysql/index.js

@@ -0,0 +1,211 @@
+import { NO_ROW } from '../chunk-AS6ODRLT.js';
+import { ValidationError, validateChunkRef, namespacePart, WriteConflictError, isWriteConflictError, validateSegmentRef, IntegrityError, TransientError } from '../chunk-NUIDEEFZ.js';
+import { randomUUID } from 'crypto';
+
+// 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 = 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;
+  }
+};
+
+export { MysqlWarmDriver, mysqlWarmTableDDL };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/mysql/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/drivers/mysql/keys.ts","../../src/drivers/mysql/mysql-errors.ts","../../src/drivers/mysql/warm.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Identifier + key validation for {@link MysqlWarmDriver} (Phase 7).\n *\n * Pure, SDK-free string logic — unit-testable without a live MySQL. Like the Postgres driver, the logical ref\n * is stored across **parameterized columns** (`namespace`, `segment`, `chunk_key`, `key_prefix`), so ref/prefix\n * values are never concatenated into SQL — `mysql2`'s `?` placeholders bind them as data (no injection surface).\n * The one value that CANNOT be a bind parameter is the **table name** (an identifier, not a value), so it is\n * validated against a strict grammar and **backtick-quoted** before interpolation — that is why this exists.\n */\nimport { ValidationError } from '@/core/errors';\n\n/** A SQL identifier segment: leading letter/underscore, then letters/digits/underscores (ASCII, ≤64 = MySQL max). */\nconst IDENT = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;\n\n/**\n * Validate a table name — optionally database-qualified (`db.table`) — and return it **safely quoted** for\n * interpolation (each part wrapped in backticks, MySQL's identifier quote). A table name is an identifier, so\n * it can't be a bind parameter; validating against {@link IDENT} (which excludes backticks, whitespace, `;`,\n * `-`, etc.) and quoting closes the only SQL-injection vector the driver has. Rejects anything else, fail-fast.\n */\nexport function validateAndQuoteTable(table: string): string {\n  const parts = table.split('.');\n  if (parts.length > 2 || parts.some((p) => !IDENT.test(p))) {\n    throw new ValidationError(\n      `invalid table name ${JSON.stringify(table)} — expected an identifier or \"db.table\" ` +\n        `(letters, digits, underscore; ≤64 chars; leading letter/underscore)`,\n    );\n  }\n  return parts.map((p) => `\\`${p}\\``).join('.');\n}\n\n/**\n * The `key_prefix` column is `VARCHAR(191)` (sized so the composite primary key fits InnoDB's 3072-byte index\n * limit under utf8mb4). A longer prefix must be rejected **fail-fast**: under a non-strict `sql_mode` MySQL\n * would otherwise *silently truncate* it, and two logical stores whose prefixes share the same first 191\n * characters would then collide on the same rows — defeating the isolation `keyPrefix` exists to provide.\n */\nconst MAX_KEY_PREFIX_CHARS = 191;\n\n/**\n * Validate a caller-supplied `keyPrefix` (lets several logical stores share one table). It's bound as a `?`\n * value, not concatenated, so the character check is a light sanity guard (no control characters), not an\n * anti-injection boundary; the length check, by contrast, is a real correctness guard (see\n * {@link MAX_KEY_PREFIX_CHARS}). Empty/undefined means no prefix (stored as the empty string).\n */\nexport function normalizeKeyPrefix(prefix: string | undefined): string {\n  if (prefix === undefined || prefix === '') return '';\n  let chars = 0;\n  for (const ch of prefix) {\n    chars++; // `for…of` iterates Unicode code points — matches MySQL's VARCHAR character count\n    if (ch.charCodeAt(0) < 0x20) {\n      throw new ValidationError('keyPrefix must not contain control characters');\n    }\n  }\n  if (chars > MAX_KEY_PREFIX_CHARS) {\n    throw new ValidationError(\n      `keyPrefix must be at most ${MAX_KEY_PREFIX_CHARS} characters (the key_prefix column width); got ${chars}`,\n    );\n  }\n  return prefix;\n}\n","/**\n * Pure helpers for classifying MySQL (`mysql2`) errors (Phase 7; transient class mirrors S3/GCS/Azure/Postgres).\n *\n * SDK-free + side-effect-free — they read only structural shapes off the thrown value (`err.errno`, a MySQL\n * error number; and `err.code`, a `mysql2`/Node string code), so the translation is unit-testable without a\n * live MySQL. Two classifiers: {@link isDuplicateKey} (the create-if-absent conflict signal, MySQL errno 1062)\n * and {@link isTransient} (retryable). Everything else propagates unchanged so a real bug is never blind-retried.\n */\n\n/** The MySQL error number off a thrown `mysql2` error, if present. */\nfunction errno(err: unknown): number | undefined {\n  const n = (err as { errno?: unknown } | null)?.errno;\n  return typeof n === 'number' ? n : undefined;\n}\n\n/** The string `code` off a thrown `mysql2`/Node error (e.g. `ER_DUP_ENTRY`, `PROTOCOL_CONNECTION_LOST`, `ECONNRESET`). */\nfunction code(err: unknown): string | undefined {\n  const c = (err as { code?: unknown } | null)?.code;\n  return typeof c === 'string' ? c : undefined;\n}\n\n/**\n * A duplicate-key violation (MySQL errno **1062** / `ER_DUP_ENTRY`). The driver's create-if-absent path is a\n * plain `INSERT`; a pre-existing row surfaces as this, which the driver maps to a `WriteConflictError`. Kept\n * separate from {@link isTransient} — a duplicate key is a **deterministic** conflict, never retried.\n */\nexport function isDuplicateKey(err: unknown): boolean {\n  return errno(err) === 1062 || code(err) === 'ER_DUP_ENTRY';\n}\n\n/**\n * A transient MySQL fault that is safe to retry: a lock-wait timeout / deadlock (1205 / 1213), too-many-\n * connections (1040 / 1203), a server shutdown / killed connection (1053 / 1927), the client's\n * server-gone / connection-lost codes (2006 / 2013, `PROTOCOL_CONNECTION_LOST`, `PROTOCOL_SEQUENCE_TIMEOUT`),\n * or a dropped/timed-out socket. Deterministic, caller-meaningful outcomes (duplicate key, unknown table,\n * syntax errors, etc.) are NOT transient — they must surface, never be blind-retried.\n */\nexport function isTransient(err: unknown): boolean {\n  const n = errno(err);\n  if (\n    n === 1205 || // ER_LOCK_WAIT_TIMEOUT\n    n === 1213 || // ER_LOCK_DEADLOCK\n    n === 1040 || // ER_CON_COUNT_ERROR (too many connections)\n    n === 1203 || // ER_TOO_MANY_USER_CONNECTIONS\n    n === 1053 || // ER_SERVER_SHUTDOWN\n    n === 1927 || // ER_CONNECTION_KILLED\n    n === 2006 || // CR_SERVER_GONE_ERROR\n    n === 2013 // CR_SERVER_LOST\n  ) {\n    return true;\n  }\n  const c = code(err);\n  return (\n    c === 'PROTOCOL_CONNECTION_LOST' ||\n    c === 'PROTOCOL_SEQUENCE_TIMEOUT' ||\n    c === 'CR_SERVER_GONE_ERROR' ||\n    c === 'CR_SERVER_LOST' ||\n    c === 'ECONNRESET' ||\n    c === 'ECONNABORTED' ||\n    c === 'ETIMEDOUT' ||\n    c === 'ESOCKETTIMEDOUT' ||\n    c === 'ECONNREFUSED' ||\n    c === 'EHOSTUNREACH' ||\n    c === 'ENETUNREACH' ||\n    c === 'EPIPE' ||\n    c === 'EAI_AGAIN' ||\n    c === 'ENOTFOUND'\n  );\n}\n","/**\n * `MysqlWarmDriver` — an {@link IWarmDriver} over MySQL / MariaDB (Phase 7).\n *\n * \"No DynamoDB — use the MySQL you already run.\" Uses the official `mysql2` (its promise API), an **optional\n * peer dependency** — only consumers of `cloud-roaring/mysql` install it. A `mysql2` `Pool` is **injected**\n * (dependency injection): the driver owns no connection/credential logic, so it's thin, reuses the caller's\n * pool, and is testable against a MySQL container.\n *\n * Each chunk is one row in a single table (`PRIMARY KEY (key_prefix, namespace, segment, chunk_key)`), with an\n * opaque OCC **token** (a random UUID minted per write) and the delta `payload` (LONGBLOB). Optimistic\n * concurrency is real, cross-process, and server-side:\n * - **create-if-absent** = a plain `INSERT`; a pre-existing row raises `ER_DUP_ENTRY` (errno 1062) ⇒\n *   {@link WriteConflictError}.\n * - **token-fenced update / delete** = `UPDATE … / DELETE … WHERE … AND token = ?`; `affectedRows !== 1` ⇒\n *   the stored token moved (or the row is gone) ⇒ {@link WriteConflictError}.\n *\n * **Why `affectedRows` is reliable here despite MySQL counting *changed* (not matched) rows by default:** the\n * new token is a fresh random UUID on every write, so a matched fenced `UPDATE` **always** changes the `token`\n * column ⇒ `affectedRows === 1` on a match and `0` on a miss, regardless of the connection's\n * `CLIENT_FOUND_ROWS` flag. (The driver never sets a value equal to what's stored, so the \"unchanged row ⇒ 0\n * affected\" MySQL quirk cannot mask a real match.)\n *\n * **Collation matters for correctness:** the table is `utf8mb4_bin`, so `key_prefix` / `namespace` / `segment`\n * / `token` compare **byte-exact and case-sensitive**. MySQL's *default* collation (`utf8mb4_0900_ai_ci`) is\n * case- and accent-**insensitive**, which would make `segment = 'A'` wrongly match a row keyed `'a'` — a\n * correctness hole. {@link mysqlWarmTableDDL} pins `utf8mb4_bin` to close it; a caller supplying their own\n * table must do the same.\n *\n * Tokens are not reused across delete→recreate (ABA-safe, D3): a delete removes the row and a recreate mints a\n * fresh random UUID, so a token from before the delete won't match. (Probabilistic — a random 122-bit UUIDv4,\n * collision odds negligible — vs the DynamoDB driver's structural monotonic counter; the hard-delete model\n * can't offer the latter, and conformance D3 pins the behavior. See DECISIONS #57.) Reads are strongly\n * consistent (single primary), so the optional `WarmReadOptions` consistency hint is a no-op, like the\n * in-memory / LocalFs / Postgres drivers. Drivers may use `node:crypto`; only `core/` is determinism-bound.\n */\nimport { randomUUID } from 'node:crypto';\nimport type { Pool, ResultSetHeader, RowDataPacket } from 'mysql2/promise';\nimport {\n  IntegrityError,\n  TransientError,\n  ValidationError,\n  WriteConflictError,\n  isWriteConflictError,\n} from '@/core/errors';\nimport { NO_ROW } from '@/core/ports';\nimport type { ChunkRef, IWarmDriver, NoRow, SegmentRef, Token, WarmRow } from '@/core/ports';\nimport { validateChunkRef, validateSegmentRef } from '@/core/validate';\nimport { namespacePart } from '../_shared/keys';\nimport { normalizeKeyPrefix, validateAndQuoteTable } from './keys';\nimport { isDuplicateKey, isTransient } from './mysql-errors';\n\nconst DEFAULT_TABLE = 'cloud_roaring_warm';\n/** Default listChunks keyset-pagination batch — bounds peak memory to ~this many rows regardless of width. */\nconst DEFAULT_LIST_BATCH = 1000;\n\nexport interface MysqlWarmDriverOptions {\n  /**\n   * A constructed `mysql2` promise `Pool` (or a pool-compatible client exposing `query`). The driver never\n   * opens/closes connections — the caller owns the pool's lifecycle. It **must target the primary**: reads are\n   * treated as strongly consistent (the OCC read-modify-write needs read-your-writes), so a pool pointed at a\n   * read replica could serve stale rows and silently break OCC.\n   */\n  readonly pool: Pool;\n  /** Warm table name — identifier or `db.table` (default `cloud_roaring_warm`). Must already exist. */\n  readonly table?: string;\n  /** Optional key-prefix column value so several logical stores can share one table (bound as data). */\n  readonly keyPrefix?: string;\n  /** Advanced: `listChunks` keyset-pagination page size (default 1000). Tunes peak memory on wide segments. */\n  readonly listPageSize?: number;\n}\n\n/** One raw warm row as selected. */\ninterface RawRow extends RowDataPacket {\n  chunk_key?: number;\n  token?: unknown;\n  payload?: unknown;\n}\n\n/**\n * The idempotent DDL for the warm table (identifier-validated + backtick-quoted). The driver does **not**\n * create schema (it stays thin + needs no DDL privileges at runtime); run this once at deploy time, e.g.\n * `await pool.query(mysqlWarmTableDDL())`. The `utf8mb4_bin` collation is **required for correctness** (see the\n * class doc): it makes the key columns compare byte-exact and case-sensitive, unlike MySQL's default ci\n * collation. Column lengths keep the composite primary key within InnoDB's 3072-byte index limit under utf8mb4.\n */\nexport function mysqlWarmTableDDL(table: string = DEFAULT_TABLE): string {\n  const t = validateAndQuoteTable(table);\n  return (\n    `CREATE TABLE IF NOT EXISTS ${t} (\\n` +\n    `  key_prefix VARCHAR(191) NOT NULL,\\n` +\n    `  namespace  VARCHAR(256) NOT NULL,\\n` +\n    `  segment    VARCHAR(256) NOT NULL,\\n` +\n    `  chunk_key  INT          NOT NULL,\\n` +\n    `  token      CHAR(36)     NOT NULL,\\n` +\n    `  payload    LONGBLOB     NOT NULL,\\n` +\n    `  PRIMARY KEY (key_prefix, namespace, segment, chunk_key)\\n` +\n    `) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;`\n  );\n}\n\nexport class MysqlWarmDriver implements IWarmDriver {\n  private readonly pool: Pool;\n  private readonly table: string; // validated + backtick-quoted for interpolation\n  private readonly keyPrefix: string;\n  private readonly listBatch: number;\n\n  constructor(options: MysqlWarmDriverOptions) {\n    this.pool = options.pool;\n    this.table = validateAndQuoteTable(options.table ?? DEFAULT_TABLE);\n    this.keyPrefix = normalizeKeyPrefix(options.keyPrefix);\n    const batch = options.listPageSize ?? DEFAULT_LIST_BATCH;\n    if (!Number.isSafeInteger(batch) || batch < 1) {\n      throw new ValidationError(`listPageSize must be a positive safe integer; got ${batch}`);\n    }\n    this.listBatch = batch;\n  }\n\n  // Reads are always strongly consistent (single primary), so the optional `WarmReadOptions` hint would be a\n  // no-op — the structurally-optional param is simply omitted (still satisfies IWarmDriver), as in LocalFs/pg.\n  async get(ref: ChunkRef): Promise<WarmRow | null> {\n    validateChunkRef(ref);\n    try {\n      const [rows] = await this.pool.query<RawRow[]>(\n        `SELECT token, payload FROM ${this.table} ` +\n          `WHERE key_prefix = ? AND namespace = ? AND segment = ? AND chunk_key = ?`,\n        [this.keyPrefix, namespacePart(ref.namespace), ref.segment, ref.chunkKey],\n      );\n      const row = rows[0];\n      return row === undefined ? null : this.rowFrom(row, ref.chunkKey);\n    } catch (err) {\n      throw this.mapError(err);\n    }\n  }\n\n  async putConditional(\n    ref: ChunkRef,\n    bytes: Uint8Array,\n    expected: Token | NoRow,\n  ): Promise<{ token: Token }> {\n    validateChunkRef(ref);\n    const token = randomUUID();\n    // Copy the payload into a Buffer for the LONGBLOB binding — severs any caller-owned/reused input buffer.\n    const payload = Buffer.from(bytes);\n    const ns = namespacePart(ref.namespace);\n    try {\n      if (expected === NO_ROW) {\n        // create-if-absent: a plain INSERT. A pre-existing PK raises ER_DUP_ENTRY (1062), caught below as a\n        // deterministic conflict — never an INSERT IGNORE (which would also swallow unrelated errors).\n        await this.pool.query<ResultSetHeader>(\n          `INSERT INTO ${this.table} (key_prefix, namespace, segment, chunk_key, token, payload) ` +\n            `VALUES (?, ?, ?, ?, ?, ?)`,\n          [this.keyPrefix, ns, ref.segment, ref.chunkKey, token, payload],\n        );\n      } else {\n        const [res] = await this.pool.query<ResultSetHeader>(\n          `UPDATE ${this.table} SET token = ?, payload = ? ` +\n            `WHERE key_prefix = ? AND namespace = ? AND segment = ? AND chunk_key = ? AND token = ?`,\n          [token, payload, this.keyPrefix, ns, ref.segment, ref.chunkKey, expected],\n        );\n        // The fresh token always changes the row, so affectedRows reflects the MATCH: 1 = fenced write applied,\n        // anything else = the stored token moved or the row is gone (a conflict), never a silent false-success.\n        if (res.affectedRows !== 1) {\n          throw new WriteConflictError(`OCC conflict on chunk ${ref.chunkKey}`);\n        }\n      }\n      return { token };\n    } catch (err) {\n      if (isWriteConflictError(err)) throw err; // our own deterministic conflict — never a transient\n      if (expected === NO_ROW && isDuplicateKey(err)) {\n        throw new WriteConflictError(`chunk ${ref.chunkKey} already exists (create-if-absent)`);\n      }\n      throw this.mapError(err);\n    }\n  }\n\n  async deleteConditional(ref: ChunkRef, expected: Token): Promise<void> {\n    validateChunkRef(ref);\n    try {\n      const [res] = await this.pool.query<ResultSetHeader>(\n        `DELETE FROM ${this.table} ` +\n          `WHERE key_prefix = ? AND namespace = ? AND segment = ? AND chunk_key = ? AND token = ?`,\n        [this.keyPrefix, namespacePart(ref.namespace), ref.segment, ref.chunkKey, expected],\n      );\n      if (res.affectedRows !== 1) {\n        throw new WriteConflictError(`fenced-delete conflict on chunk ${ref.chunkKey}`);\n      }\n    } catch (err) {\n      if (isWriteConflictError(err)) throw err;\n      throw this.mapError(err);\n    }\n  }\n\n  async *listChunks(ref: SegmentRef): AsyncIterable<{ chunkKey: number } & WarmRow> {\n    validateSegmentRef(ref);\n    const ns = namespacePart(ref.namespace);\n    // Keyset pagination on chunk_key (ascending) bounds peak memory to one page WITHIN a single enumeration,\n    // regardless of how wide the segment is. (It does NOT resume across a transient fault — the retry decorator\n    // re-enumerates a streaming method from the start and buffers, see drivers/retry/retrying-drivers.ts.)\n    let after = -1;\n    for (;;) {\n      let rows: RawRow[];\n      try {\n        const [res] = await this.pool.query<RawRow[]>(\n          `SELECT chunk_key, token, payload FROM ${this.table} ` +\n            `WHERE key_prefix = ? AND namespace = ? AND segment = ? AND chunk_key > ? ` +\n            `ORDER BY chunk_key ASC LIMIT ?`,\n          [this.keyPrefix, ns, ref.segment, after, this.listBatch],\n        );\n        rows = res;\n      } catch (err) {\n        throw this.mapError(err);\n      }\n      for (const row of rows) {\n        const chunkKey = row.chunk_key;\n        if (typeof chunkKey !== 'number') {\n          throw new IntegrityError('warm row is missing its chunk_key');\n        }\n        yield { chunkKey, ...this.rowFrom(row, chunkKey) };\n        after = chunkKey;\n      }\n      if (rows.length < this.listBatch) return;\n    }\n  }\n\n  /**\n   * Build a {@link WarmRow} from a raw row. `token` must be a non-empty string and `payload` a Buffer — a\n   * missing/typo'd column means a corrupt or foreign row, which we reject (untrusted-data posture) rather\n   * than paper over. The returned bytes are a fresh copy (driver-owned, read-only per the contract).\n   */\n  private rowFrom(row: RawRow, chunkKey: number): WarmRow {\n    if (typeof row.token !== 'string' || row.token === '') {\n      throw new IntegrityError(`warm row for chunk ${chunkKey} is missing its token`);\n    }\n    if (!(row.payload instanceof Uint8Array)) {\n      throw new IntegrityError(`warm row for chunk ${chunkKey} is missing its payload`);\n    }\n    return { token: row.token, bytes: new Uint8Array(row.payload) };\n  }\n\n  /**\n   * Reclassify a transient MySQL fault (lock-wait/deadlock, connection lost, too-many-connections, dropped\n   * socket) as a retryable {@link TransientError}; everything else propagates unchanged. Applied at every\n   * query site so callers + the retry decorator only ever see typed errors. A deterministic OCC/duplicate-key\n   * conflict is signalled by the driver itself — never reclassified here.\n   */\n  private mapError(err: unknown): unknown {\n    if (isTransient(err)) {\n      return new TransientError(\n        `transient MySQL fault: ${(err as { code?: unknown } | null)?.code ?? (err as { errno?: unknown } | null)?.errno ?? 'unknown'}`,\n        { cause: err },\n      );\n    }\n    return err;\n  }\n}\n"]}

package/dist/ports-D3BrJ6ax.d.cts

@@ -0,0 +1,357 @@
+/** Streaming append target for a single object being written. */
+interface BlobSink {
+    write(bytes: Uint8Array): Promise<void>;
+}
+/**
+ * Random/tail read access to a single finished object. The total size comes back from `getTail` (the
+ * codec's entry point), so there's no separate `size()` — keeping the seam minimal for driver authors.
+ */
+interface BlobReader {
+    /** Exactly `length` bytes starting at `offset`. Out-of-range is a `ValidationError`, never a short read. */
+    getRange(offset: number, length: number): Promise<Uint8Array>;
+    /** The last `min(maxBytes, size)` bytes plus the total size — the one-GET footer+index path. */
+    getTail(maxBytes: number): Promise<{
+        bytes: Uint8Array;
+        size: number;
+    }>;
+}
+/** In-memory `BlobSink` that accumulates written bytes; `bytes()` returns the concatenation. */
+declare class BufferSink implements BlobSink {
+    private readonly chunks;
+    private length;
+    write(bytes: Uint8Array): Promise<void>;
+    bytes(): Uint8Array;
+}
+/** In-memory `BlobReader` over a fixed byte buffer. */
+declare class BufferReader implements BlobReader {
+    private readonly buffer;
+    constructor(buffer: Uint8Array);
+    getRange(offset: number, length: number): Promise<Uint8Array>;
+    getTail(maxBytes: number): Promise<{
+        bytes: Uint8Array;
+        size: number;
+    }>;
+}
+
+/**
+ * Encryption seams — the **pure** interfaces `core/` depends on so the codec can encrypt/decrypt without
+ * importing `node:crypto` (lint-banned here, like `Clock`/`Rng`/drivers). Concrete AES-256-GCM lives outside
+ * `core/` (`src/drivers/crypto.ts`) and is injected. The envelope scheme: a per-segment DEK wrapped under an
+ * operator-held KEK, so discarding the DEK crypto-shreds the segment,
+ * [DECISIONS #19]. Per-chunk AEAD over the `.crbm` payloads + index; a per-segment **DEK** wrapped (envelope
+ * encryption) under one or more **KEK**s by an {@link IKeystore}; the wrapped DEK(s) live in the registry, so
+ * crypto-shred = delete them.
+ */
+/** One AEAD result: a fresh per-message nonce, the ciphertext, and the authentication tag. */
+interface AeadSealed {
+    readonly nonce: Uint8Array;
+    readonly ciphertext: Uint8Array;
+    readonly tag: Uint8Array;
+}
+/**
+ * Authenticated encryption bound to a single key (a segment's DEK). `aad` (associated data) is authenticated
+ * but not encrypted — the codec passes each chunk's `(namespace, segment, generation, chunkKey)` identity
+ * ({@link aadFor}), so a chunk's ciphertext can't be silently relocated to another segment/generation/chunk or
+ * the index, even by someone who can rewrite Cold objects. The seam is symmetric and self-framing-agnostic:
+ * the caller decides where the nonce/tag go (inline with a chunk, or in the footer for the index).
+ */
+interface Aead {
+    /** Encrypt `plaintext`, authenticating `aad`. Returns a fresh nonce + ciphertext + tag. */
+    seal(plaintext: Uint8Array, aad: Uint8Array): AeadSealed;
+    /**
+     * Decrypt + verify. Throws {@link IntegrityError} on **any** mismatch (wrong key, tampered ciphertext/tag,
+     * or `aad` that doesn't match what was sealed) — never returns wrong-but-plausible plaintext.
+     */
+    open(sealed: AeadSealed, aad: Uint8Array): Uint8Array;
+}
+/**
+ * A DEK wrapped under one KEK. A segment stores a **list** of these (one per KEK it was wrapped under — e.g.
+ * an active KEK plus an offline recovery KEK), so losing one KEK isn't fatal and KEK rotation needs no
+ * data re-encryption. `keyId` names which KEK; `wrapped` is the opaque wrapped-key blob (base64). Carries no
+ * plaintext key material — safe to store in the registry next to the (encrypted) data.
+ */
+interface WrappedDek {
+    readonly keyId: string;
+    readonly wrapped: string;
+}
+/**
+ * Envelope key management — the injected seam between the codec and however the operator holds key material
+ * (in-process BYOK by default; KMS/Vault as optional adapters later). Async so a remote keystore (KMS) fits
+ * the same interface. Never exposes raw key bytes to `core/`: it returns an {@link Aead} bound to the DEK.
+ */
+interface IKeystore {
+    /**
+     * Mint a fresh per-segment DEK, wrapped under the active KEK (and any recovery KEK). Returns the wrapping(s)
+     * to persist in the registry plus an {@link Aead} to encrypt this segment's chunks with.
+     */
+    createDek(): Promise<{
+        wrapped: WrappedDek[];
+        aead: Aead;
+    }>;
+    /**
+     * Reconstruct the {@link Aead} from a segment's stored wrappings by unwrapping with any KEK currently held.
+     * Throws {@link KeyUnavailableError} if it holds none of the referenced KEKs (lost key, or a shredded
+     * segment whose wrappings were deleted).
+     */
+    openDek(wrapped: readonly WrappedDek[]): Promise<Aead>;
+}
+/**
+ * What the encrypting codec needs: the {@link Aead} for this segment's DEK plus a way to build the AAD for a
+ * given scope (`'index'` or a chunkKey). Built per (segment, generation) by the cold-source bridge so the
+ * codec itself stays segment-agnostic.
+ */
+interface CrbmCrypto {
+    readonly aead: Aead;
+    aadFor(scope: number | 'index'): Uint8Array;
+}
+/**
+ * Build the AEAD associated-data binding a chunk (or the index) to its exact location:
+ * `v1 ‖ len(namespace) ‖ namespace ‖ len(segment) ‖ segment ‖ generation ‖ scope ‖ chunkKey`. Length-prefixed
+ * so distinct `(namespace, segment)` pairs can never collide. Pure (no crypto) — just the authenticated label.
+ */
+declare function aadFor(ref: {
+    readonly namespace?: string;
+    readonly segment: string;
+}, generation: number, scope: number | 'index'): Uint8Array;
+
+/**
+ * Storage-driver contracts the engine depends on.
+ *
+ * Phase 1 uses the subset needed by the in-memory engine: the per-chunk Warm store (under OCC) and a
+ * per-chunk read view of Cold. Drivers move opaque bytes + an OCC token; they never understand roaring,
+ * `adds`/`removes`, or the `.crbm` layout. The full `IColdDriver` (blob/range) + `IRegistryDriver` arrive
+ * with generations in Phase 2/3 — the `.crbm` reader will implement `ColdChunkSource`.
+ */
+
+/** Opaque optimistic-concurrency token — unique per write, compared by equality only. */
+type Token = string;
+/** Sentinel for `putConditional` meaning "the row must not exist yet" (create). */
+declare const NO_ROW: unique symbol;
+type NoRow = typeof NO_ROW;
+interface SegmentRef {
+    readonly namespace?: string;
+    readonly segment: string;
+}
+interface ChunkRef extends SegmentRef {
+    readonly chunkKey: number;
+}
+/** Identifies one immutable `.crbm` object — a single generation of a segment. */
+interface GenKey extends SegmentRef {
+    readonly generation: number;
+}
+interface WarmRow {
+    readonly token: Token;
+    /** Read-only: owned by the driver. Callers must NOT mutate the buffer (re-encode to write). */
+    readonly bytes: Uint8Array;
+}
+/**
+ * Read consistency for a Warm fetch (gap #9). `consistent: true` (the default — omitted ⇒ true) is a
+ * strong, read-your-writes read, as the OCC read-modify-write path requires. `consistent: false` requests an
+ * **eventually-consistent** read — on DynamoDB that is ~½ the RCU cost; a driver that is always strongly
+ * consistent (in-memory, LocalFs) ignores it. The engine uses it only on read paths (`has`/`count`/`iterate`/
+ * `intersect`) when the store opts into `warmReadConsistency: 'eventual'`, trading read-after-write for cost.
+ */
+interface WarmReadOptions {
+    readonly consistent?: boolean;
+}
+/** Per-chunk Warm store under optimistic concurrency. Returned byte buffers are read-only. */
+interface IWarmDriver {
+    get(ref: ChunkRef, opts?: WarmReadOptions): Promise<WarmRow | null>;
+    /** OCC write. `expected` = `NO_ROW` to create, else the token previously read. Throws `WriteConflictError` on mismatch. */
+    putConditional(ref: ChunkRef, bytes: Uint8Array, expected: Token | NoRow): Promise<{
+        token: Token;
+    }>;
+    /**
+     * Fenced delete — only if the stored token still equals `expected`; throws `WriteConflictError`
+     * otherwise. **Used by compaction (Phase 4); the Phase-1 engine never calls it** — drivers still
+     * implement it to satisfy the conformance suite.
+     */
+    deleteConditional(ref: ChunkRef, expected: Token): Promise<void>;
+    /** All dirty chunks of a segment, ascending `chunkKey`. Yielded `bytes` are read-only. */
+    listChunks(ref: SegmentRef, opts?: WarmReadOptions): AsyncIterable<{
+        chunkKey: number;
+    } & WarmRow>;
+}
+/**
+ * A segment's grounded on-disk footprint (Phase 5b) — the current generation's Cold object bytes, read
+ * cheaply from the `.crbm` footer/index (no payload reads). Powers the grounded `costReport()`.
+ */
+interface SegmentSize {
+    readonly sizeBytes: number;
+}
+/** Per-chunk read view of the immutable Cold tier (implemented by the `.crbm` reader from Phase 2). */
+interface ColdChunkSource {
+    /** Read-only bytes for the chunk, or `null` if absent. Callers must not mutate the buffer. */
+    getChunk(ref: ChunkRef): Promise<Uint8Array | null>;
+    listChunkKeys(ref: SegmentRef): Promise<number[]>;
+    /**
+     * Optional (Phase 5b): the current generation's grounded size, cheaply (from the already-parsed
+     * `.crbm` index — no payload reads), or `null` if the segment has no Cold generation. Powers the
+     * grounded `costReport()`.
+     */
+    sizeOf?(ref: SegmentRef): Promise<SegmentSize | null>;
+    /**
+     * Optional (Phase 5c): the current generation's **per-chunk cardinality** (`chunkKey → count`), read
+     * from the already-parsed `.crbm` index with **no payload reads**, or `null` if the segment has no Cold
+     * generation. Powers the cheap `count()` — a warm-delta-free chunk is counted straight from the index
+     * instead of fetching + deserializing it. A source with no index (e.g. the in-memory source) omits this,
+     * and `count()` falls back to fetching + merging every chunk.
+     */
+    cardinalities?(ref: SegmentRef): Promise<ReadonlyMap<number, number> | null>;
+    /**
+     * Optional (Phase B, gap #4): the segment's **current generation number** as this source resolves it right now
+     * (registry `currentGen`, or the highest cold generation), or `null` if the segment has no Cold generation. The
+     * engine keys its HOT chunk cache by this so a generation bump (a compaction commit) is observed — a new
+     * generation misses the cache instead of serving a stale decoded chunk, and an erased id can't resurrect from a
+     * cached pre-compaction chunk. Cheap: served from the source's own (short-TTL-refreshed) snapshot, **not** a
+     * fresh backend read per call. A source that pins one immutable generation for its whole lifetime and never
+     * refreshes may omit this — the engine then keys the cache without a generation, exactly as before.
+     */
+    currentGeneration?(ref: SegmentRef): Promise<number | null>;
+}
+/** Capabilities a Cold driver advertises; validated at wiring time, fail-fast. */
+interface ColdCaps {
+    /** REQUIRED — the format relies on byte-range reads. */
+    readonly rangeRead: true;
+    /** Largest single object the backend accepts (informs single-object-vs-shard, B7 — future). */
+    readonly maxObjectBytes: number;
+    /** Optional: enables the pure-object `LATEST`-pointer registry variant (S3 conditional put). */
+    readonly conditionalPut?: boolean;
+}
+/**
+ * Immutable object storage for `.crbm` generations. A "dumb byte mover": it
+ * understands neither roaring nor the `.crbm` layout, only opaque bytes addressed by a {@link GenKey}.
+ * The core never reuses a key, so puts are write-once.
+ */
+interface IColdDriver {
+    capabilities(): ColdCaps;
+    /**
+     * Stream a new immutable generation. The driver opens a destination, hands `write` a {@link BlobSink},
+     * then atomically commits (and computes the content hash). Throws if the key already exists (write-once).
+     */
+    putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
+        size: number;
+        sha256: string;
+    }>;
+    /** Range read; the caller bounds-checks. Out-of-range is rejected, never a short/adjacent read. */
+    getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
+    /** Speculative tail read: the last `min(maxBytes, size)` bytes + the total object size. */
+    getTail(key: GenKey, maxBytes: number): Promise<{
+        bytes: Uint8Array;
+        size: number;
+    }>;
+    delete(key: GenKey): Promise<void>;
+    /** Enumerate the generations present for a segment (orphan sweep / latest-gen resolution). */
+    list(ref: SegmentRef): AsyncIterable<GenKey>;
+}
+/**
+ * Lifecycle status of a segment. `active` is the steady state;
+ * `compacting`/`erasing` are transient flags a daemon sets while it works (Phase 4d/4e); `destroyed` is the
+ * post-crypto-shred tombstone (the row is kept for audit but the segment is logically gone). The 4c registry
+ * stores and round-trips the field; the *transitions* are driven by their owning features.
+ */
+type RegistryStatus = 'active' | 'compacting' | 'erasing' | 'destroyed';
+/** Free-form, JSON-serializable governance metadata (retention/residency policy); shape lands in Phase 6. */
+type GovernanceMeta = Record<string, unknown>;
+/**
+ * One registry row — the authoritative per-segment record. Exactly one per segment.
+ */
+interface RegistryRecord extends SegmentRef {
+    /** **The** authoritative LATEST pointer: which immutable Cold generation is current. */
+    readonly currentGen: number;
+    /**
+     * Per-segment data-key (DEK) wrappings for encryption-at-rest (Phase 4e): the DEK envelope-wrapped under one
+     * or more KEKs (active + optional recovery). Reading unwraps with any held KEK; **crypto-shred deletes this
+     * whole list**, making the segment's at-rest bytes permanently unrecoverable. Absent ⇒ the segment is
+     * cleartext. See [DECISIONS #19].
+     */
+    readonly wrappedDeks?: readonly WrappedDek[];
+    /**
+     * Optional **external** key reference (reserved) — e.g. a KMS key ARN for a future KMS keystore adapter that
+     * keeps wrapped material in the KMS rather than in-band {@link wrappedDeks}. Unused by the in-process BYOK
+     * keystore. Clearable on crypto-shred.
+     */
+    readonly keyId?: string;
+    /**
+     * Dirty-row hint written by `findCompactable`. Discovery still recomputes the live dirty count by scanning
+     * Warm each cycle (the count that decides candidacy), but it now **reads** this hint to gate a change-guarded
+     * CAS — the hint is only rewritten when the count actually moved, so an all-idle fleet issues no per-segment
+     * registry writes. It does not yet drive candidacy — turning the Warm scan itself into O(dirty) is a
+     * deferred cheap-enumeration fix.
+     */
+    readonly dirtyChunkCount: number;
+    readonly status: RegistryStatus;
+    /**
+     * Daemon health (Phase D, gap #2): epoch-ms of the last **successfully committed** compaction, and the
+     * count of **consecutive** compaction failures (reset to 0 by a successful commit). `lastCompactedAt`
+     * powers a dead-man's-switch / staleness alarm; `consecutiveFailures` drives **poison-segment quarantine** —
+     * discovery skips a segment past a failure threshold so one corrupt Warm row can't freeze the compaction of a
+     * segment **that has a committed generation** forever (with no alarm) while its Warm backlog grows unbounded.
+     * (A segment whose *very first* compaction keeps failing has no registry row to count against yet —
+     * bootstrap faults are surfaced as `error` results but not yet quarantined; gap #2.) Both
+     * **optional** (absent on rows written before Phase D, and on a segment never compacted) — read them as
+     * `lastCompactedAt ?? undefined`, `consecutiveFailures ?? 0`.
+     */
+    readonly lastCompactedAt?: number;
+    readonly consecutiveFailures?: number;
+    /**
+     * Compaction lease (Phase 4d): the opaque id of the worker currently compacting this segment, and the
+     * epoch-ms at which its lease expires. `status === 'compacting'` with `leaseExpiresAt` in the future means
+     * a live daemon owns it; once `leaseExpiresAt` is past, another worker may **steal** the lease (the prior
+     * holder crashed). Both absent in the steady (`active`) state. The lease is an efficiency guard only — the
+     * 2-phase commit is correct without it (OCC-fenced swap + write-once generations + version-fenced purge).
+     */
+    readonly leaseOwner?: string;
+    readonly leaseExpiresAt?: number;
+    /** Governance policy (Phase 6); stored + round-tripped now, semantics later. */
+    readonly retention?: GovernanceMeta;
+    readonly residency?: GovernanceMeta;
+    /** Epoch-ms of creation / last mutation (from the driver's injected clock). */
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    /** Opaque OCC token — compare-by-equality, never reused (ABA-safe), exactly like {@link WarmRow.token}. */
+    readonly token: Token;
+}
+/** The caller-settable fields at {@link IRegistryDriver.create} (audit + token are driver-managed). */
+interface NewRegistryRecord {
+    readonly currentGen: number;
+    readonly wrappedDeks?: readonly WrappedDek[];
+    readonly keyId?: string;
+    /** Defaults to 0. */
+    readonly dirtyChunkCount?: number;
+    /** Defaults to `'active'`. */
+    readonly status?: RegistryStatus;
+    readonly retention?: GovernanceMeta;
+    readonly residency?: GovernanceMeta;
+}
+/** Fields a {@link IRegistryDriver.compareAndSwap} may mutate (identity + audit + token are off-limits). */
+type RegistryPatch = Partial<Pick<RegistryRecord, 'currentGen' | 'wrappedDeks' | 'keyId' | 'dirtyChunkCount' | 'status' | 'leaseOwner' | 'leaseExpiresAt' | 'lastCompactedAt' | 'consecutiveFailures' | 'retention' | 'residency'>>;
+/** Capabilities a registry driver advertises; validated fail-fast at wiring time. */
+interface RegCaps {
+    /** REQUIRED — `currentGen` feeds read correctness + compaction CAS, so reads must be strongly consistent. */
+    readonly strongRead: true;
+}
+/**
+ * Per-segment registry — the authoritative source of `currentGen`, the discovery index, and (Phase 4e) the
+ * wrapped-DEK holder. One row per segment under OCC: a
+ * never-reused, equality-compared {@link Token} (ABA-safe across delete→recreate, like the Warm tier).
+ */
+interface IRegistryDriver {
+    capabilities(): RegCaps;
+    /** The segment's record, or `null` if it doesn't exist (or was deleted). */
+    get(ref: SegmentRef): Promise<RegistryRecord | null>;
+    /** Create the row; throws {@link WriteConflictError} if it already exists (use CAS to mutate). */
+    create(ref: SegmentRef, record: NewRegistryRecord): Promise<{
+        token: Token;
+    }>;
+    /** Server-side compare-and-set: apply `patch` iff the stored token equals `expected`, else `WriteConflictError`. */
+    compareAndSwap(ref: SegmentRef, expected: Token, patch: RegistryPatch): Promise<{
+        token: Token;
+    }>;
+    /** Discovery: every live record, optionally scoped to one namespace. Order is unspecified. */
+    list(namespace?: string): AsyncIterable<RegistryRecord>;
+    /** Remove the row (tombstoned for ABA-safety — a later `create` still gets a fresh, greater token). */
+    delete(ref: SegmentRef): Promise<void>;
+}
+
+export { type Aead as A, type BlobSink as B, type ColdCaps as C, type GenKey as G, type IColdDriver as I, type NoRow as N, type RegCaps as R, type SegmentRef as S, type Token as T, type WarmReadOptions as W, type IWarmDriver as a, type ChunkRef as b, type WarmRow as c, type IRegistryDriver as d, type RegistryRecord as e, type NewRegistryRecord as f, type RegistryPatch as g, type ColdChunkSource as h, type SegmentSize as i, type IKeystore as j, type CrbmCrypto as k, type BlobReader as l, type WrappedDek as m, type AeadSealed as n, BufferReader as o, BufferSink as p, type GovernanceMeta as q, NO_ROW as r, type RegistryStatus as s, aadFor as t };