@cloudbitmaps/core 0.1.0-rc.0

package/dist/ports-D3BrJ6ax.d.ts

@@ -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 };

package/dist/postgres/index.cjs

@@ -0,0 +1,273 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/drivers/postgres/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/postgres/keys.ts
+var IDENT = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
+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 "schema.table" (letters, digits, underscore; \u226463 chars; leading letter/underscore)`
+    );
+  }
+  return parts.map((p) => `"${p}"`).join(".");
+}
+function normalizeKeyPrefix(prefix) {
+  if (prefix === void 0 || prefix === "") return "";
+  for (const ch of prefix) {
+    if (ch.charCodeAt(0) < 32) {
+      throw new ValidationError("keyPrefix must not contain control characters");
+    }
+  }
+  return prefix;
+}
+
+// src/drivers/postgres/postgres-errors.ts
+function networkCode(err) {
+  const code = err?.code;
+  return typeof code === "string" && /^E[A-Z_]+$/.test(code) ? code : void 0;
+}
+var CONNECTION_LOST = /connection terminated|not queryable|timeout exceeded when trying to connect/i;
+function isConnectionLostMessage(err) {
+  return err instanceof Error && CONNECTION_LOST.test(err.message);
+}
+function sqlState(err) {
+  if (networkCode(err) !== void 0) return void 0;
+  const code = err?.code;
+  return typeof code === "string" && /^[0-9A-Z]{5}$/.test(code) ? code : void 0;
+}
+function isTransient(err) {
+  const state = sqlState(err);
+  if (state !== void 0) {
+    const cls = state.slice(0, 2);
+    if (cls === "40" || cls === "08" || cls === "53") return true;
+    if (state === "57P03" || state === "57P01" || state === "57P02") return true;
+    return false;
+  }
+  const net = networkCode(err);
+  if (net === "ECONNRESET" || net === "ECONNABORTED" || net === "ETIMEDOUT" || net === "ESOCKETTIMEDOUT" || net === "ECONNREFUSED" || net === "EHOSTUNREACH" || net === "ENETUNREACH" || net === "EPIPE" || net === "EAI_AGAIN" || net === "ENOTFOUND") {
+    return true;
+  }
+  return isConnectionLostMessage(err);
+}
+
+// src/drivers/postgres/warm.ts
+var DEFAULT_TABLE = "cloud_roaring_warm";
+var DEFAULT_LIST_BATCH = 1e3;
+function postgresWarmTableDDL(table = DEFAULT_TABLE) {
+  const t = validateAndQuoteTable(table);
+  return `CREATE TABLE IF NOT EXISTS ${t} (
+  key_prefix text    NOT NULL,
+  namespace  text    NOT NULL,
+  segment    text    NOT NULL,
+  chunk_key  integer NOT NULL,
+  token      text    NOT NULL,
+  payload    bytea   NOT NULL,
+  PRIMARY KEY (key_prefix, namespace, segment, chunk_key)
+);`;
+}
+var PostgresWarmDriver = class {
+  pool;
+  table;
+  // validated + 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.
+  async get(ref) {
+    validateChunkRef(ref);
+    try {
+      const res = await this.pool.query(
+        `SELECT token, payload FROM ${this.table} WHERE key_prefix = $1 AND namespace = $2 AND segment = $3 AND chunk_key = $4`,
+        [this.keyPrefix, namespacePart(ref.namespace), ref.segment, ref.chunkKey]
+      );
+      const row = res.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) {
+        const res = await this.pool.query(
+          `INSERT INTO ${this.table} (key_prefix, namespace, segment, chunk_key, token, payload) VALUES ($1, $2, $3, $4, $5, $6) ON CONFLICT (key_prefix, namespace, segment, chunk_key) DO NOTHING`,
+          [this.keyPrefix, ns, ref.segment, ref.chunkKey, token, payload]
+        );
+        if (res.rowCount !== 1) {
+          throw new WriteConflictError(`chunk ${ref.chunkKey} already exists (create-if-absent)`);
+        }
+      } else {
+        const res = await this.pool.query(
+          `UPDATE ${this.table} SET token = $5, payload = $6 WHERE key_prefix = $1 AND namespace = $2 AND segment = $3 AND chunk_key = $4 AND token = $7`,
+          [this.keyPrefix, ns, ref.segment, ref.chunkKey, token, payload, expected]
+        );
+        if (res.rowCount !== 1)
+          throw new WriteConflictError(`OCC conflict on chunk ${ref.chunkKey}`);
+      }
+      return { token };
+    } catch (err) {
+      if (isWriteConflictError(err)) throw err;
+      throw this.mapError(err);
+    }
+  }
+  async deleteConditional(ref, expected) {
+    validateChunkRef(ref);
+    try {
+      const res = await this.pool.query(
+        `DELETE FROM ${this.table} WHERE key_prefix = $1 AND namespace = $2 AND segment = $3 AND chunk_key = $4 AND token = $5`,
+        [this.keyPrefix, namespacePart(ref.namespace), ref.segment, ref.chunkKey, expected]
+      );
+      if (res.rowCount !== 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 = $1 AND namespace = $2 AND segment = $3 AND chunk_key > $4 ORDER BY chunk_key ASC LIMIT $5`,
+          [this.keyPrefix, ns, ref.segment, after, this.listBatch]
+        );
+        rows = res.rows;
+      } 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 Postgres fault (serialization/deadlock, connection, resource, 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 conflict is signalled by
+   * the driver itself (0 rows affected) — never reclassified here.
+   */
+  mapError(err) {
+    if (isTransient(err)) {
+      return new TransientError(
+        `transient Postgres fault: ${err?.code ?? "unknown"}`,
+        { cause: err }
+      );
+    }
+    return err;
+  }
+};
+
+exports.PostgresWarmDriver = PostgresWarmDriver;
+exports.postgresWarmTableDDL = postgresWarmTableDDL;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map