zerobucket 0.4.0 → 0.5.0

package/dist/bin.js

@@ -0,0 +1,2506 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { parseArgs } from "util";
+
+// src/errors.ts
+var ZeroBucketError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+};
+var StorageError = class extends ZeroBucketError {
+};
+
+// src/adapters/shared.ts
+var DEFAULT_STREAM_CHUNK_SIZE = 1024 * 1024;
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isValidId(id) {
+  return typeof id === "string" && UUID_RE.test(id);
+}
+function msg(exc) {
+  return exc instanceof Error ? exc.message : String(exc);
+}
+function wrap(prefix, exc) {
+  return exc instanceof StorageError ? exc : new StorageError(`${prefix}: ${msg(exc)}`, { cause: exc });
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(limit, items.length) }, async () => {
+      while (next < items.length) {
+        const i = next++;
+        out[i] = await fn(items[i]);
+      }
+    })
+  );
+  return out;
+}
+function tieredWithoutStorage(id, key) {
+  return new StorageError(
+    `Image ${JSON.stringify(id)} is stored in object storage (key=${JSON.stringify(key)}) but this ZeroBucket was constructed without \`objectStorage\`. Configure it with the same bucket and credentials that were used to tier this image.`
+  );
+}
+async function hydrateRow(row, id, os) {
+  let data;
+  if (row.storage_backend === "object_storage") {
+    if (!os) throw tieredWithoutStorage(id, row.object_storage_key);
+    data = await os.download(row.object_storage_key);
+    if (data.length !== row.size_bytes) {
+      throw new StorageError(
+        `Object ${JSON.stringify(row.object_storage_key)} for image ${JSON.stringify(id)} has ${data.length} bytes but the database records ${row.size_bytes}. The stored object is corrupted or was replaced.`
+      );
+    }
+  } else {
+    data = row.data;
+  }
+  return {
+    id: String(row.id),
+    data,
+    mimeType: row.mime_type,
+    originalFilename: row.original_filename,
+    sizeBytes: row.size_bytes,
+    width: row.width,
+    height: row.height,
+    checksumSha256: row.checksum_sha256
+  };
+}
+async function* streamFromObjectStorage(os, id, key, start, end, chunkSize) {
+  let offset = start;
+  while (offset <= end) {
+    const last = Math.min(offset + chunkSize - 1, end);
+    const expected = last - offset + 1;
+    const chunk = await os.downloadRange(key, offset, last);
+    if (chunk.length !== expected) {
+      throw new StorageError(
+        `Object ${JSON.stringify(key)} for image ${JSON.stringify(id)} returned ${chunk.length} bytes for a ${expected}-byte range; the stored object is shorter than the database records.`
+      );
+    }
+    yield chunk;
+    offset = last + 1;
+  }
+}
+function prettySize(bytes) {
+  if (bytes < 1024) return `${bytes} bytes`;
+  const units = ["kB", "MB", "GB", "TB"];
+  let v = bytes / 1024;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i += 1;
+  }
+  return `${v.toFixed(1)} ${units[i]}`;
+}
+
+// src/adapters/postgres.ts
+var SCHEMA = `
+CREATE TABLE IF NOT EXISTS zerobucket_images (
+    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    data                BYTEA NOT NULL,
+    mime_type           TEXT NOT NULL,
+    original_filename   TEXT,
+    size_bytes          INTEGER NOT NULL,
+    width               INTEGER,
+    height              INTEGER,
+    checksum_sha256     CHAR(64) NOT NULL,
+    created_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_checksum ON zerobucket_images (checksum_sha256);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_created_at ON zerobucket_images (created_at);
+
+-- Object-storage tiering columns (additive; identical to the Python package).
+ALTER TABLE zerobucket_images ALTER COLUMN data DROP NOT NULL;
+ALTER TABLE zerobucket_images
+    ADD COLUMN IF NOT EXISTS storage_backend TEXT NOT NULL DEFAULT 'postgres';
+ALTER TABLE zerobucket_images ADD COLUMN IF NOT EXISTS object_storage_bucket TEXT;
+ALTER TABLE zerobucket_images ADD COLUMN IF NOT EXISTS object_storage_key TEXT;
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'zerobucket_storage_location_check'
+    ) THEN
+        ALTER TABLE zerobucket_images ADD CONSTRAINT zerobucket_storage_location_check
+        CHECK (
+            (storage_backend = 'postgres'
+                AND data IS NOT NULL
+                AND object_storage_key IS NULL
+                AND object_storage_bucket IS NULL)
+            OR
+            (storage_backend = 'object_storage'
+                AND data IS NULL
+                AND object_storage_key IS NOT NULL
+                AND object_storage_bucket IS NOT NULL)
+        );
+    END IF;
+END $$;
+CREATE INDEX IF NOT EXISTS idx_zerobucket_storage_backend
+    ON zerobucket_images (storage_backend) WHERE storage_backend != 'postgres';
+`;
+var INSERT = `
+INSERT INTO zerobucket_images
+    (data, mime_type, original_filename, size_bytes, width, height, checksum_sha256)
+VALUES ($1, $2, $3, $4, $5, $6, $7)
+RETURNING id;`;
+var SELECT_FULL = `
+SELECT id, data, mime_type, original_filename, size_bytes, width, height,
+       checksum_sha256, storage_backend, object_storage_bucket, object_storage_key
+FROM zerobucket_images WHERE id = $1;`;
+var SELECT_MANY = `
+SELECT id, data, mime_type, original_filename, size_bytes, width, height,
+       checksum_sha256, storage_backend, object_storage_bucket, object_storage_key
+FROM zerobucket_images WHERE id = ANY($1::uuid[]);`;
+var SELECT_METADATA = `
+SELECT id, mime_type, original_filename, size_bytes, width, height, checksum_sha256
+FROM zerobucket_images WHERE id = $1;`;
+var SELECT_CHUNK = `SELECT substring(data FROM $1::int FOR $2::int) AS chunk FROM zerobucket_images WHERE id = $3;`;
+var SELECT_STREAM_INFO = `SELECT size_bytes, storage_backend, object_storage_key FROM zerobucket_images WHERE id = $1;`;
+var DELETE_RETURNING = `DELETE FROM zerobucket_images WHERE id = $1 RETURNING storage_backend, object_storage_key;`;
+var DELETE_MANY = `DELETE FROM zerobucket_images WHERE id = ANY($1::uuid[]) RETURNING id, storage_backend, object_storage_key;`;
+var EXISTS = `SELECT 1 FROM zerobucket_images WHERE id = $1;`;
+var SELECT_FOR_TIERING = `SELECT data, mime_type, size_bytes, storage_backend FROM zerobucket_images WHERE id = $1 FOR UPDATE;`;
+var UPDATE_AFTER_TIERING = `UPDATE zerobucket_images SET data = NULL, storage_backend = 'object_storage', object_storage_bucket = $1, object_storage_key = $2, updated_at = now() WHERE id = $3;`;
+var DEDUP_SCHEMA = `
+CREATE TABLE IF NOT EXISTS zerobucket_blobs (
+    checksum_sha256     CHAR(64) PRIMARY KEY,
+    data                BYTEA NOT NULL,
+    mime_type           TEXT NOT NULL,
+    size_bytes          INTEGER NOT NULL,
+    width               INTEGER,
+    height              INTEGER,
+    ref_count           INTEGER NOT NULL DEFAULT 0,
+    created_at          TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS zerobucket_image_refs (
+    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    checksum_sha256     CHAR(64) NOT NULL REFERENCES zerobucket_blobs(checksum_sha256),
+    original_filename   TEXT,
+    created_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_image_refs_checksum ON zerobucket_image_refs (checksum_sha256);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_image_refs_created_at ON zerobucket_image_refs (created_at);
+`;
+var D_UPSERT_BLOB = `
+INSERT INTO zerobucket_blobs (checksum_sha256, data, mime_type, size_bytes, width, height, ref_count)
+VALUES ($1, $2, $3, $4, $5, $6, $7)
+ON CONFLICT (checksum_sha256) DO UPDATE SET ref_count = zerobucket_blobs.ref_count + EXCLUDED.ref_count;`;
+var D_INSERT_REF = `INSERT INTO zerobucket_image_refs (checksum_sha256, original_filename) VALUES ($1, $2) RETURNING id;`;
+var D_COLS = `r.id, b.data, b.mime_type, r.original_filename, b.size_bytes, b.width, b.height, r.checksum_sha256,
+       'postgres'::text AS storage_backend, NULL::text AS object_storage_bucket, NULL::text AS object_storage_key`;
+var D_FROM = `FROM zerobucket_image_refs r JOIN zerobucket_blobs b ON r.checksum_sha256 = b.checksum_sha256`;
+var D_DELETE_REF = `DELETE FROM zerobucket_image_refs WHERE id = $1 RETURNING checksum_sha256;`;
+var D_DELETE_REFS = `DELETE FROM zerobucket_image_refs WHERE id = ANY($1::uuid[]) RETURNING id, checksum_sha256;`;
+var D_DECREMENT = `UPDATE zerobucket_blobs SET ref_count = ref_count - $1 WHERE checksum_sha256 = $2 RETURNING ref_count;`;
+var D_DELETE_EMPTY = `DELETE FROM zerobucket_blobs WHERE checksum_sha256 = ANY($1::text[]) AND ref_count <= 0;`;
+var CLASSIC_SQL = {
+  schema: SCHEMA,
+  selectFull: SELECT_FULL,
+  selectMany: SELECT_MANY,
+  selectMetadata: SELECT_METADATA,
+  selectStreamInfo: SELECT_STREAM_INFO,
+  selectChunk: SELECT_CHUNK,
+  exists: EXISTS
+};
+var DEDUP_SQL = {
+  schema: DEDUP_SCHEMA,
+  selectFull: `SELECT ${D_COLS} ${D_FROM} WHERE r.id = $1;`,
+  selectMany: `SELECT ${D_COLS} ${D_FROM} WHERE r.id = ANY($1::uuid[]);`,
+  selectMetadata: `SELECT r.id, b.mime_type, r.original_filename, b.size_bytes, b.width, b.height, r.checksum_sha256 ${D_FROM} WHERE r.id = $1;`,
+  selectStreamInfo: `SELECT b.size_bytes, 'postgres'::text AS storage_backend, NULL::text AS object_storage_key ${D_FROM} WHERE r.id = $1;`,
+  selectChunk: `SELECT substring(b.data FROM $1::int FOR $2::int) AS chunk ${D_FROM} WHERE r.id = $3;`,
+  exists: `SELECT 1 FROM zerobucket_image_refs WHERE id = $1;`
+};
+var RETRYABLE_SQLSTATES = /* @__PURE__ */ new Set([
+  "40001",
+  // serialization_failure
+  "40P01",
+  // deadlock_detected
+  "08000",
+  // connection_exception
+  "08003",
+  // connection_does_not_exist
+  "08006",
+  // connection_failure
+  "08001",
+  // sqlclient_unable_to_establish_sqlconnection
+  "08004",
+  // sqlserver_rejected_establishment_of_sqlconnection
+  "57P01",
+  // admin_shutdown
+  "57P02",
+  // crash_shutdown
+  "57P03",
+  // cannot_connect_now
+  "53000",
+  // insufficient_resources
+  "53300"
+  // too_many_connections
+]);
+var RETRYABLE_NODE_CODES = /* @__PURE__ */ new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "EPIPE",
+  "ECONNABORTED"
+]);
+var CONNECTION_MESSAGE_RE = /connection terminated|connection timeout|timeout exceeded when trying to connect|client has encountered a connection error/i;
+function isRetryable(exc) {
+  if (!(exc instanceof Error)) return false;
+  const code = exc.code;
+  if (typeof code === "string") {
+    if (RETRYABLE_SQLSTATES.has(code) || RETRYABLE_NODE_CODES.has(code))
+      return true;
+  }
+  return CONNECTION_MESSAGE_RE.test(exc.message);
+}
+function isConnectionLevel(exc) {
+  if (!(exc instanceof Error)) return false;
+  const code = exc.code;
+  if (typeof code === "string" && (RETRYABLE_NODE_CODES.has(code) || code.startsWith("08") || code.startsWith("57"))) {
+    return true;
+  }
+  return CONNECTION_MESSAGE_RE.test(exc.message);
+}
+var MAX_BACKOFF_MS = 2e3;
+function backoffDelayMs(attempt, baseDelayMs) {
+  const exponential = baseDelayMs * 2 ** (attempt - 1);
+  const jitter = Math.random() * baseDelayMs;
+  return Math.min(exponential + jitter, MAX_BACKOFF_MS);
+}
+var PostgresBackend = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (!opts.connectionString && !opts.pool) {
+      throw new TypeError(
+        "PostgresBackend requires either `connectionString` or `pool`"
+      );
+    }
+    this.ownsPool = !opts.pool;
+    this.pool = opts.pool;
+    this.maxRetries = opts.maxRetries ?? 3;
+    this.retryBaseDelayMs = opts.retryBaseDelayMs ?? 100;
+    this.autoMigrate = opts.autoMigrate ?? true;
+    this.dedup = opts.dedup ?? false;
+    if (this.dedup && opts.objectStorage) {
+      throw new TypeError(
+        "objectStorage is not supported together with dedup: true (same restriction as the Python package). Tiering moves one image's bytes, but a deduplicated blob can be shared by many images."
+      );
+    }
+    this.sql = this.dedup ? DEDUP_SQL : CLASSIC_SQL;
+  }
+  opts;
+  pool;
+  ownsPool;
+  readyPromise;
+  closed = false;
+  maxRetries;
+  retryBaseDelayMs;
+  autoMigrate;
+  dedup;
+  sql;
+  // ---- lifecycle -------------------------------------------------------
+  ready() {
+    if (this.closed)
+      return Promise.reject(
+        new StorageError("This ZeroBucket instance has been closed")
+      );
+    this.readyPromise ??= this.init().catch((exc) => {
+      this.readyPromise = void 0;
+      throw exc;
+    });
+    return this.readyPromise;
+  }
+  async init() {
+    if (!this.pool) {
+      let pg;
+      try {
+        const mod = await import("pg");
+        pg = mod.default ?? mod;
+      } catch (cause) {
+        throw new StorageError(
+          "PostgresBackend requires the 'pg' package. Install it with: npm install pg",
+          { cause }
+        );
+      }
+      const config = {
+        connectionString: this.opts.connectionString,
+        min: this.opts.poolMinSize ?? 1,
+        max: this.opts.poolMaxSize ?? 5,
+        connectionTimeoutMillis: this.opts.poolTimeoutMs ?? 1e4
+      };
+      this.pool = new pg.Pool(config);
+      this.pool.on("error", () => {
+      });
+    }
+    try {
+      if (this.autoMigrate) await this.migrate();
+      else await this.pool.query("SELECT 1");
+    } catch (exc) {
+      if (this.ownsPool) {
+        await this.pool.end().catch(() => {
+        });
+        this.pool = void 0;
+      }
+      throw exc instanceof StorageError ? exc : new StorageError(`Could not connect to PostgreSQL: ${msg(exc)}`, {
+        cause: exc
+      });
+    }
+  }
+  /** Create the schema if missing. Serialized across processes with an advisory lock. */
+  async migrate() {
+    const pool = this.pool;
+    let client;
+    try {
+      client = await pool.connect();
+    } catch (exc) {
+      throw new StorageError(`Could not connect to PostgreSQL: ${msg(exc)}`, {
+        cause: exc
+      });
+    }
+    try {
+      await client.query("BEGIN");
+      await client.query(
+        "SELECT pg_advisory_xact_lock(hashtext('zerobucket_migrate'))"
+      );
+      await client.query(this.sql.schema);
+      await client.query("COMMIT");
+      client.release();
+    } catch (exc) {
+      await client.query("ROLLBACK").catch(() => {
+      });
+      client.release(true);
+      throw new StorageError(`Migration failed: ${msg(exc)}`, { cause: exc });
+    }
+  }
+  async close() {
+    this.closed = true;
+    const pool = this.pool;
+    this.pool = void 0;
+    this.readyPromise = void 0;
+    if (pool && this.ownsPool) await pool.end();
+  }
+  // ---- execution core --------------------------------------------------
+  emit(operation, start, success, error, retryCount) {
+    const cb = this.opts.onOperation;
+    if (!cb) return;
+    try {
+      cb({
+        operation,
+        durationMs: performance.now() - start,
+        success,
+        error,
+        retryCount
+      });
+    } catch {
+    }
+  }
+  /**
+   * Run `work` and return its result, emitting exactly one OperationEvent.
+   *
+   * connection given  -> run once on it, no BEGIN/COMMIT, no retry.
+   * connection absent -> pooled; `tx` wraps the work in BEGIN/COMMIT; transient
+   *                      failures retry the WHOLE closure on a fresh connection.
+   */
+  async run(operation, connection, work, { tx = false } = {}) {
+    if (connection) {
+      if (!isQueryable(connection)) {
+        throw new TypeError(
+          "PostgresBackend expects a pg client/pool client as `connection` (an object with query()), not a SQLite Database."
+        );
+      }
+      const start2 = performance.now();
+      try {
+        const result = tx ? await this.atomic(connection, work) : await work(connection);
+        this.emit(operation, start2, true, null, 0);
+        return result;
+      } catch (exc) {
+        this.emit(operation, start2, false, msg(exc), 0);
+        throw exc;
+      }
+    }
+    await this.ready();
+    const start = performance.now();
+    let attempt = 0;
+    for (; ; ) {
+      let client;
+      let destroy = false;
+      try {
+        client = await this.pool.connect();
+        if (tx) await client.query("BEGIN");
+        const result = await work(client);
+        if (tx) await client.query("COMMIT");
+        this.emit(operation, start, true, null, attempt);
+        return result;
+      } catch (exc) {
+        if (client && tx) {
+          try {
+            await client.query("ROLLBACK");
+          } catch {
+            destroy = true;
+          }
+        }
+        if (isConnectionLevel(exc)) destroy = true;
+        attempt += 1;
+        if (attempt > this.maxRetries || !isRetryable(exc)) {
+          this.emit(operation, start, false, msg(exc), attempt - 1);
+          throw exc;
+        }
+      } finally {
+        client?.release(destroy);
+      }
+      await sleep(backoffDelayMs(attempt, this.retryBaseDelayMs));
+    }
+  }
+  /**
+   * Make multi-statement work all-or-nothing on a CALLER-supplied connection.
+   *  - Caller has an open transaction -> SAVEPOINT: a failure rolls back only our work and the
+   *    caller's transaction stays usable; success joins their transaction.
+   *  - No open transaction (an autocommit pg.Client) -> open and commit our own, so a failure
+   *    can never leave half-applied state (e.g. an inflated dedup ref_count).
+   */
+  async atomic(conn, work) {
+    let ownTx = false;
+    try {
+      await conn.query("SAVEPOINT zerobucket_atomic");
+    } catch (exc) {
+      if (exc.code !== "25P01") throw exc;
+      ownTx = true;
+      await conn.query("BEGIN");
+    }
+    try {
+      const result = await work(conn);
+      await conn.query(
+        ownTx ? "COMMIT" : "RELEASE SAVEPOINT zerobucket_atomic"
+      );
+      return result;
+    } catch (exc) {
+      try {
+        await conn.query(
+          ownTx ? "ROLLBACK" : "ROLLBACK TO SAVEPOINT zerobucket_atomic"
+        );
+      } catch {
+      }
+      throw exc;
+    }
+  }
+  // ---- StorageBackend --------------------------------------------------
+  async put(row, { connection } = {}) {
+    try {
+      if (this.dedup) {
+        return await this.run(
+          "put",
+          connection,
+          async (q) => {
+            await q.query(D_UPSERT_BLOB, blobParams(row, 1));
+            return String(
+              (await q.query(D_INSERT_REF, [
+                row.checksumSha256,
+                row.originalFilename
+              ])).rows[0].id
+            );
+          },
+          { tx: true }
+        );
+      }
+      return await this.run("put", connection, async (q) => {
+        const res = await q.query(INSERT, rowParams(row));
+        return String(res.rows[0].id);
+      });
+    } catch (exc) {
+      throw wrap("Failed to store image", exc);
+    }
+  }
+  async putMany(rows, { connection } = {}) {
+    if (rows.length === 0) return [];
+    try {
+      if (this.dedup) {
+        return await this.run(
+          "put_many",
+          connection,
+          async (q) => {
+            const groups = /* @__PURE__ */ new Map();
+            for (const r of rows) {
+              const g = groups.get(r.checksumSha256);
+              if (g) g.n += 1;
+              else groups.set(r.checksumSha256, { row: r, n: 1 });
+            }
+            for (const checksum of [...groups.keys()].sort()) {
+              const g = groups.get(checksum);
+              await q.query(D_UPSERT_BLOB, blobParams(g.row, g.n));
+            }
+            const ids = [];
+            for (const r of rows) {
+              ids.push(
+                String(
+                  (await q.query(D_INSERT_REF, [
+                    r.checksumSha256,
+                    r.originalFilename
+                  ])).rows[0].id
+                )
+              );
+            }
+            return ids;
+          },
+          { tx: true }
+        );
+      }
+      return await this.run(
+        "put_many",
+        connection,
+        async (q) => {
+          const ids = [];
+          for (const r of rows)
+            ids.push(String((await q.query(INSERT, rowParams(r))).rows[0].id));
+          return ids;
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to store image batch", exc);
+    }
+  }
+  async get(id, { connection } = {}) {
+    if (!isValidId(id)) return null;
+    let row;
+    try {
+      row = await this.run(
+        "get",
+        connection,
+        async (q) => (await q.query(this.sql.selectFull, [id])).rows[0]
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image", exc);
+    }
+    return row ? this.hydrate(row, id) : null;
+  }
+  async getMany(ids, { connection } = {}) {
+    const valid = ids.filter(isValidId);
+    if (valid.length === 0) return [];
+    let rows;
+    try {
+      rows = await this.run(
+        "get_many",
+        connection,
+        async (q) => (await q.query(this.sql.selectMany, [valid])).rows
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image batch", exc);
+    }
+    return mapLimit(rows, 4, (r) => this.hydrate(r, String(r.id)));
+  }
+  async getMetadata(id, { connection } = {}) {
+    if (!isValidId(id)) return null;
+    let row;
+    try {
+      row = await this.run(
+        "get_metadata",
+        connection,
+        async (q) => (await q.query(this.sql.selectMetadata, [id])).rows[0]
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image metadata", exc);
+    }
+    if (!row) return null;
+    return {
+      id: String(row.id),
+      mimeType: row.mime_type,
+      originalFilename: row.original_filename,
+      sizeBytes: row.size_bytes,
+      width: row.width,
+      height: row.height,
+      checksumSha256: row.checksum_sha256
+    };
+  }
+  async getStream(id, opts) {
+    if (!isValidId(id)) return null;
+    const { connection, chunkSize } = opts;
+    if (!Number.isInteger(chunkSize) || chunkSize <= 0)
+      throw new RangeError("chunkSize must be a positive integer");
+    let info;
+    try {
+      info = await this.run(
+        "get_metadata",
+        connection,
+        async (q) => (await q.query(this.sql.selectStreamInfo, [id])).rows[0]
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image metadata", exc);
+    }
+    if (!info) return null;
+    const totalSize = info.size_bytes;
+    const start = opts.range?.start ?? 0;
+    const end = Math.min(opts.range?.end ?? totalSize - 1, totalSize - 1);
+    if (info.storage_backend === "object_storage") {
+      const os = this.opts.objectStorage;
+      if (!os) throw tieredWithoutStorage(id, info.object_storage_key);
+      return streamFromObjectStorage(
+        os,
+        id,
+        info.object_storage_key,
+        start,
+        end,
+        chunkSize
+      );
+    }
+    const self = this;
+    async function* generate() {
+      let offset = start;
+      let delivered = 0;
+      const wanted = Math.max(0, end - start + 1);
+      while (delivered < wanted) {
+        const length = Math.min(chunkSize, wanted - delivered);
+        let row;
+        try {
+          row = await self.run(
+            "get_stream",
+            connection,
+            async (q) => (await q.query(self.sql.selectChunk, [offset + 1, length, id])).rows[0]
+          );
+        } catch (exc) {
+          throw wrap("Failed to stream image", exc);
+        }
+        if (!row) {
+          throw new StorageError(
+            `Image ${JSON.stringify(id)} was deleted while streaming (delivered ${delivered} of ${wanted} bytes). Pass connection with your own open transaction if you need a consistent read across concurrent writers.`
+          );
+        }
+        const chunk = row.chunk;
+        if (!chunk || chunk.length === 0) {
+          throw new StorageError(
+            `Image ${JSON.stringify(id)} ended early while streaming (delivered ${delivered} of ${wanted} bytes).`
+          );
+        }
+        yield chunk;
+        offset += chunk.length;
+        delivered += chunk.length;
+      }
+    }
+    return generate();
+  }
+  async delete(id, { connection } = {}) {
+    if (!isValidId(id)) return false;
+    if (this.dedup) return this.deleteDedup(id, connection);
+    try {
+      const row = await this.run(
+        "delete",
+        connection,
+        async (q) => (await q.query(DELETE_RETURNING, [id])).rows[0]
+      );
+      if (row?.storage_backend === "object_storage")
+        await this.cleanupObject([row.object_storage_key], connection);
+      return row !== void 0;
+    } catch (exc) {
+      throw wrap("Failed to delete image", exc);
+    }
+  }
+  async deleteMany(ids, { connection } = {}) {
+    const valid = ids.filter(isValidId);
+    if (valid.length === 0) return [];
+    if (this.dedup) return this.deleteManyDedup(valid, connection);
+    try {
+      const rows = await this.run(
+        "delete_many",
+        connection,
+        async (q) => (await q.query(DELETE_MANY, [valid])).rows
+      );
+      await this.cleanupObject(
+        rows.filter((r) => r.storage_backend === "object_storage").map((r) => r.object_storage_key),
+        connection
+      );
+      return rows.map((r) => String(r.id));
+    } catch (exc) {
+      throw wrap("Failed to delete image batch", exc);
+    }
+  }
+  async exists(id, { connection } = {}) {
+    if (!isValidId(id)) return false;
+    try {
+      return await this.run(
+        "exists",
+        connection,
+        async (q) => ((await q.query(this.sql.exists, [id])).rowCount ?? 0) > 0
+      );
+    } catch (exc) {
+      throw wrap("Failed to check image existence", exc);
+    }
+  }
+  // ---- maintenance (CLI) -----------------------------------------------
+  async getInfo() {
+    try {
+      return await this.run("info", void 0, async (q) => {
+        const imgTable = this.dedup ? "zerobucket_image_refs" : "zerobucket_images";
+        const present = await q.query(
+          "SELECT to_regclass($1) AS a, to_regclass('zerobucket_blobs') AS b",
+          [imgTable]
+        );
+        if (!present.rows[0].a || this.dedup && !present.rows[0].b)
+          return null;
+        const j = this.dedup ? "FROM zerobucket_image_refs r JOIN zerobucket_blobs b ON r.checksum_sha256 = b.checksum_sha256" : "FROM zerobucket_images";
+        const size = this.dedup ? "b.size_bytes" : "size_bytes";
+        const created = this.dedup ? "r.created_at" : "created_at";
+        const mime = this.dedup ? "b.mime_type" : "mime_type";
+        const tot = (await q.query(
+          `SELECT count(*)::int AS n, coalesce(sum(${size}), 0)::text AS bytes, min(${created})::text AS oldest, max(${created})::text AS newest ${j}`
+        )).rows[0];
+        const disk = (await q.query(
+          this.dedup ? "SELECT pg_size_pretty(pg_total_relation_size('zerobucket_blobs') + pg_total_relation_size('zerobucket_image_refs')) AS s" : "SELECT pg_size_pretty(pg_total_relation_size('zerobucket_images')) AS s"
+        )).rows[0].s;
+        const fmt = (await q.query(
+          `SELECT ${mime} AS m, count(*)::int AS n, coalesce(sum(${size}), 0)::text AS bytes ${j} GROUP BY ${mime} ORDER BY count(*) DESC, ${mime}`
+        )).rows;
+        const info = {
+          mode: this.dedup ? "dedup" : "classic",
+          count: tot.n,
+          totalBytes: Number(tot.bytes),
+          // Postgres prints the offset as "+00"; Python's CLI (and ISO-8601) print "+00:00". Normalise so output is identical.
+          oldest: tot.oldest && tot.oldest.replace(/([+-]\d\d)$/, "$1:00"),
+          newest: tot.newest && tot.newest.replace(/([+-]\d\d)$/, "$1:00"),
+          onDisk: disk,
+          byFormat: fmt.map((r) => ({
+            mimeType: r.m,
+            count: r.n,
+            bytes: Number(r.bytes)
+          }))
+        };
+        if (this.dedup) {
+          const b = (await q.query(
+            "SELECT count(*)::int AS n, coalesce(sum(size_bytes), 0)::text AS bytes FROM zerobucket_blobs"
+          )).rows[0];
+          info.dedup = { blobs: b.n, storedBytes: Number(b.bytes) };
+        } else {
+          const t = (await q.query(
+            "SELECT count(*)::int AS n, coalesce(sum(size_bytes), 0)::text AS bytes FROM zerobucket_images WHERE storage_backend = 'object_storage'"
+          )).rows[0];
+          info.tiered = { count: t.n, bytes: Number(t.bytes) };
+        }
+        return info;
+      });
+    } catch (exc) {
+      throw wrap("Failed to read storage info", exc);
+    }
+  }
+  async listImages(o = {}) {
+    const where = [];
+    const params = [];
+    const add = (sql2, v) => (params.push(v), where.push(sql2.replace("$?", `$${params.length}`)));
+    if (o.minSize !== void 0)
+      add(`${this.dedup ? "b.size_bytes" : "size_bytes"} >= $?`, o.minSize);
+    if (o.olderThanDays !== void 0)
+      add(
+        `${this.dedup ? "r.created_at" : "created_at"} <= now() - make_interval(days => $?::int)`,
+        o.olderThanDays
+      );
+    if (o.onlyUntiered && !this.dedup)
+      where.push("storage_backend = 'postgres'");
+    const from = this.dedup ? "FROM zerobucket_image_refs r JOIN zerobucket_blobs b ON r.checksum_sha256 = b.checksum_sha256" : "FROM zerobucket_images";
+    const idCol = this.dedup ? "r.id" : "id";
+    const tierCol = this.dedup ? "false AS tiered" : "(storage_backend = 'object_storage') AS tiered";
+    const order = o.sample !== void 0 ? "ORDER BY random()" : `ORDER BY ${this.dedup ? "r.created_at" : "created_at"}, ${idCol}`;
+    const lim = o.sample ?? o.limit;
+    let sql = `SELECT ${idCol} AS id, ${tierCol} ${from}${where.length ? " WHERE " + where.join(" AND ") : ""} ${order}`;
+    if (lim !== void 0) {
+      params.push(lim);
+      sql += ` LIMIT $${params.length}`;
+    }
+    try {
+      const rows = await this.run(
+        "list_images",
+        void 0,
+        async (q) => (await q.query(sql, params)).rows
+      );
+      return rows.map((r) => ({ id: String(r.id), tiered: Boolean(r.tiered) }));
+    } catch (exc) {
+      throw wrap("Failed to list images", exc);
+    }
+  }
+  // ---- dedup deletes / migration ---------------------------------------
+  async deleteDedup(id, connection) {
+    try {
+      return await this.run(
+        "delete",
+        connection,
+        async (q) => {
+          const ref = (await q.query(D_DELETE_REF, [id])).rows[0];
+          if (!ref) return false;
+          const checksum = ref.checksum_sha256;
+          const dec = (await q.query(D_DECREMENT, [1, checksum])).rows[0];
+          if (dec && dec.ref_count <= 0)
+            await q.query(D_DELETE_EMPTY, [[checksum]]);
+          return true;
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to delete image", exc);
+    }
+  }
+  async deleteManyDedup(ids, connection) {
+    try {
+      return await this.run(
+        "delete_many",
+        connection,
+        async (q) => {
+          const deleted = (await q.query(D_DELETE_REFS, [ids])).rows;
+          if (deleted.length === 0) return [];
+          const counts = /* @__PURE__ */ new Map();
+          for (const r of deleted)
+            counts.set(
+              r.checksum_sha256,
+              (counts.get(r.checksum_sha256) ?? 0) + 1
+            );
+          const emptied = [];
+          for (const checksum of [...counts.keys()].sort()) {
+            const dec = (await q.query(D_DECREMENT, [counts.get(checksum), checksum])).rows[0];
+            if (dec && dec.ref_count <= 0) emptied.push(checksum);
+          }
+          if (emptied.length > 0) await q.query(D_DELETE_EMPTY, [emptied]);
+          return deleted.map((r) => String(r.id));
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to delete image batch", exc);
+    }
+  }
+  /**
+   * One-time, NON-DESTRUCTIVE copy of every row in the classic `zerobucket_images` table into this
+   * dedup instance's tables, preserving every id (external references keep working) and
+   * deduplicating identical content on the way. The classic table is never modified.
+   *
+   * Differences from the Python version, all deliberate: rows are copied in small batches (bounded
+   * memory instead of loading the whole table); re-running is safe (already-migrated ids are
+   * skipped and reported, not an error); and classic rows already tiered to object storage are
+   * refused up front with a clear message (their bytes are not in the database to copy).
+   * Still all-or-nothing: one transaction.
+   */
+  async migrateClassicToDedup() {
+    if (!this.dedup) {
+      throw new StorageError(
+        "migrateClassicToDedup() must be called on an instance created with dedup: true."
+      );
+    }
+    await this.ready();
+    const client = await this.pool.connect();
+    let destroy = false;
+    try {
+      await client.query("BEGIN");
+      await client.query(
+        "SELECT pg_advisory_xact_lock(hashtext('zerobucket_migrate_dedup'))"
+      );
+      if (!(await client.query("SELECT to_regclass('zerobucket_images') AS t")).rows[0].t) {
+        throw new StorageError(
+          "No classic zerobucket_images table found in this database -- nothing to migrate."
+        );
+      }
+      const hasTierCol = (await client.query(
+        "SELECT 1 FROM information_schema.columns WHERE table_name = 'zerobucket_images' AND column_name = 'storage_backend'"
+      )).rowCount;
+      if (hasTierCol) {
+        const tiered = (await client.query(
+          "SELECT count(*)::int AS n FROM zerobucket_images WHERE storage_backend <> 'postgres'"
+        )).rows[0].n;
+        if (tiered > 0) {
+          throw new StorageError(
+            `${tiered} classic image(s) are tiered to object storage, so their bytes are not in the database to migrate. Dedup mode does not support tiering. Migrate only an un-tiered table, or bring those images back first.`
+          );
+        }
+      }
+      const seen = /* @__PURE__ */ new Set();
+      let migrated = 0;
+      let already = 0;
+      let cursor = null;
+      const BATCH = 20;
+      for (; ; ) {
+        const page = cursor ? await client.query(
+          `SELECT id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, created_at::text AS created_at_txt
+               FROM zerobucket_images WHERE (created_at, id) > ($1::timestamptz, $2::uuid) ORDER BY created_at, id LIMIT ${BATCH}`,
+          [cursor.createdAt, cursor.id]
+        ) : await client.query(
+          `SELECT id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, created_at::text AS created_at_txt
+               FROM zerobucket_images ORDER BY created_at, id LIMIT ${BATCH}`
+        );
+        if (page.rows.length === 0) break;
+        const last = page.rows[page.rows.length - 1];
+        if (cursor && cursor.createdAt === last.created_at_txt && cursor.id === last.id) {
+          throw new StorageError(
+            "Migration made no progress (keyset cursor did not advance); aborting instead of looping."
+          );
+        }
+        cursor = { createdAt: last.created_at_txt, id: last.id };
+        const have = new Set(
+          (await client.query(
+            "SELECT id FROM zerobucket_image_refs WHERE id = ANY($1::uuid[])",
+            [page.rows.map((r) => r.id)]
+          )).rows.map((r) => String(r.id))
+        );
+        const fresh = page.rows.filter((r) => !have.has(String(r.id)));
+        already += page.rows.length - fresh.length;
+        const groups = /* @__PURE__ */ new Map();
+        for (const r of fresh) {
+          const g = groups.get(r.checksum_sha256);
+          if (g) g.n += 1;
+          else groups.set(r.checksum_sha256, { row: r, n: 1 });
+        }
+        for (const checksum of [...groups.keys()].sort()) {
+          const { row, n } = groups.get(checksum);
+          await client.query(D_UPSERT_BLOB, [
+            checksum,
+            row.data,
+            row.mime_type,
+            row.size_bytes,
+            row.width,
+            row.height,
+            n
+          ]);
+        }
+        for (const r of fresh) {
+          await client.query(
+            "INSERT INTO zerobucket_image_refs (id, checksum_sha256, original_filename, created_at) VALUES ($1, $2, $3, $4::timestamptz)",
+            [r.id, r.checksum_sha256, r.original_filename, r.created_at_txt]
+          );
+          seen.add(r.checksum_sha256);
+          migrated += 1;
+        }
+      }
+      await client.query("COMMIT");
+      return {
+        imagesMigrated: migrated,
+        distinctBlobsCreated: seen.size,
+        duplicateReferencesFound: migrated - seen.size,
+        alreadyMigrated: already
+      };
+    } catch (exc) {
+      try {
+        await client.query("ROLLBACK");
+      } catch {
+        destroy = true;
+      }
+      throw exc instanceof StorageError ? exc : new StorageError(`Migration to dedup failed: ${msg(exc)}`, {
+        cause: exc
+      });
+    } finally {
+      client.release(destroy);
+    }
+  }
+  // ---- helpers ---------------------------------------------------------
+  hydrate(row, id) {
+    return hydrateRow(row, id, this.opts.objectStorage);
+  }
+  /**
+   * Remove tiered objects AFTER their rows are gone. Ordering is deliberate:
+   * once the row is deleted the image is correctly "not found" to everyone, so
+   * a failed object delete only leaves a harmless orphan, whereas deleting the
+   * object first and then failing the row delete would leave a row pointing at nothing.
+   *
+   * Never runs inside a caller-owned transaction (`connection`): we cannot know
+   * whether it will commit, and destroying data before the commit outcome is known
+   * could leave a rolled-back row pointing at a deleted object. In that case the
+   * object stays until you remove it yourself after committing (objectStorage.delete(id)).
+   * Failures are reported through onOperation and never fail the delete itself.
+   */
+  async cleanupObject(keys, connection) {
+    const os = this.opts.objectStorage;
+    if (!os || connection || keys.length === 0) return;
+    await Promise.all(
+      keys.map(async (key) => {
+        const start = performance.now();
+        try {
+          await os.delete(key);
+          this.emit("object_storage_delete", start, true, null, 0);
+        } catch (exc) {
+          this.emit("object_storage_delete", start, false, msg(exc), 0);
+        }
+      })
+    );
+  }
+  /**
+   * Move an image's bytes out of Postgres into object storage, replacing the
+   * row's `data` with a pointer. Returns:
+   *   null  - no such image
+   *   false - already tiered (a safe no-op, so backfills can be re-run)
+   *   true  - tiered just now
+   *
+   * SAFETY: the upload happens INSIDE the same transaction as the row lock
+   * (SELECT ... FOR UPDATE) and the UPDATE that flips the row. If the upload
+   * fails, the transaction rolls back and the row is untouched: there is no
+   * moment when the bytes exist nowhere, or when a row claims to be tiered
+   * without a completed upload.
+   *
+   * TRADEOFF: the row lock is held for the whole upload. Concurrent writes
+   * to THIS image (delete, tier) wait; every other row is unaffected, and plain
+   * reads are never blocked (Postgres MVCC). Meant for explicit maintenance, not hot paths.
+   *
+   * Retry is safe: a transient error replays the whole closure, and the
+   * deterministic key (the image id) makes the re-upload an idempotent overwrite.
+   */
+  async tierToObjectStorage(id, { connection } = {}) {
+    if (this.dedup) {
+      throw new StorageError(
+        "tierToObjectStorage() is not supported in dedup mode (a blob may be shared by many images)."
+      );
+    }
+    const os = this.opts.objectStorage;
+    if (!os) {
+      throw new StorageError(
+        "tierToObjectStorage() requires objectStorage to be configured (new ZeroBucket({ objectStorage: new ObjectStorage({ bucket }) }))."
+      );
+    }
+    if (!isValidId(id)) return null;
+    const key = id.toLowerCase();
+    try {
+      return await this.run(
+        "tier_to_object_storage",
+        connection,
+        async (q) => {
+          const row = (await q.query(SELECT_FOR_TIERING, [id])).rows[0];
+          if (!row) return null;
+          if (row.storage_backend !== "postgres") return false;
+          await os.upload(key, row.data, { mimeType: row.mime_type });
+          await q.query(UPDATE_AFTER_TIERING, [os.bucket, key, id]);
+          return true;
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to tier image to object storage", exc);
+    }
+  }
+};
+function blobParams(r, refs) {
+  return [
+    r.checksumSha256,
+    r.data,
+    r.mimeType,
+    r.sizeBytes,
+    r.width,
+    r.height,
+    refs
+  ];
+}
+function rowParams(r) {
+  return [
+    r.data,
+    r.mimeType,
+    r.originalFilename,
+    r.sizeBytes,
+    r.width,
+    r.height,
+    r.checksumSha256
+  ];
+}
+function isQueryable(c) {
+  return typeof c.query === "function";
+}
+
+// src/adapters/sqlite.ts
+import { randomUUID } from "crypto";
+import { existsSync, statSync } from "fs";
+var SCHEMA2 = `
+CREATE TABLE IF NOT EXISTS zerobucket_images (
+    id                  TEXT PRIMARY KEY,
+    data                BLOB,
+    mime_type           TEXT NOT NULL,
+    original_filename   TEXT,
+    size_bytes          INTEGER NOT NULL,
+    width               INTEGER,
+    height              INTEGER,
+    checksum_sha256     TEXT NOT NULL,
+    created_at          TEXT NOT NULL,
+    updated_at          TEXT NOT NULL,
+    storage_backend     TEXT NOT NULL DEFAULT 'sqlite',
+    object_storage_bucket TEXT,
+    object_storage_key  TEXT,
+    CHECK (
+        (storage_backend = 'sqlite'
+            AND data IS NOT NULL
+            AND object_storage_key IS NULL
+            AND object_storage_bucket IS NULL)
+        OR
+        (storage_backend = 'object_storage'
+            AND data IS NULL
+            AND object_storage_key IS NOT NULL
+            AND object_storage_bucket IS NOT NULL)
+    )
+);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_checksum ON zerobucket_images (checksum_sha256);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_created_at ON zerobucket_images (created_at);
+`;
+var DEDUP_SCHEMA2 = `
+CREATE TABLE IF NOT EXISTS zerobucket_blobs (
+    checksum_sha256     TEXT PRIMARY KEY,
+    data                BLOB NOT NULL,
+    mime_type           TEXT NOT NULL,
+    size_bytes          INTEGER NOT NULL,
+    width               INTEGER,
+    height              INTEGER,
+    ref_count           INTEGER NOT NULL DEFAULT 0,
+    created_at          TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS zerobucket_image_refs (
+    id                  TEXT PRIMARY KEY,
+    checksum_sha256     TEXT NOT NULL REFERENCES zerobucket_blobs(checksum_sha256),
+    original_filename   TEXT,
+    created_at          TEXT NOT NULL,
+    updated_at          TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_image_refs_checksum ON zerobucket_image_refs (checksum_sha256);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_image_refs_created_at ON zerobucket_image_refs (created_at);
+`;
+var COLS = `id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, storage_backend, object_storage_bucket, object_storage_key`;
+var INSERT2 = `INSERT INTO zerobucket_images (id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+var SELECT_FULL2 = `SELECT ${COLS} FROM zerobucket_images WHERE id = ?`;
+var selectMany = (n) => `SELECT ${COLS} FROM zerobucket_images WHERE id IN (${placeholders(n)})`;
+var SELECT_METADATA2 = `SELECT id, mime_type, original_filename, size_bytes, width, height, checksum_sha256 FROM zerobucket_images WHERE id = ?`;
+var STREAM_INFO = `SELECT size_bytes, storage_backend, object_storage_key FROM zerobucket_images WHERE id = ?`;
+var CHUNK = `SELECT substr(data, ?, ?) AS chunk FROM zerobucket_images WHERE id = ?`;
+var EXISTS2 = `SELECT 1 FROM zerobucket_images WHERE id = ?`;
+var DELETE_ONE = `DELETE FROM zerobucket_images WHERE id = ? RETURNING storage_backend, object_storage_key`;
+var deleteMany = (n) => `DELETE FROM zerobucket_images WHERE id IN (${placeholders(n)}) RETURNING id, storage_backend, object_storage_key`;
+var SELECT_FOR_TIERING2 = `SELECT data, mime_type, size_bytes, storage_backend FROM zerobucket_images WHERE id = ?`;
+var UPDATE_AFTER_TIERING2 = `UPDATE zerobucket_images SET data = NULL, storage_backend = 'object_storage', object_storage_bucket = ?, object_storage_key = ?, updated_at = ? WHERE id = ?`;
+var D_FROM2 = `FROM zerobucket_image_refs r JOIN zerobucket_blobs b ON r.checksum_sha256 = b.checksum_sha256`;
+var D_COLS2 = `r.id AS id, b.data AS data, b.mime_type AS mime_type, r.original_filename AS original_filename, b.size_bytes AS size_bytes, b.width AS width, b.height AS height, r.checksum_sha256 AS checksum_sha256, 'sqlite' AS storage_backend, NULL AS object_storage_bucket, NULL AS object_storage_key`;
+var D_UPSERT = `INSERT INTO zerobucket_blobs (checksum_sha256, data, mime_type, size_bytes, width, height, ref_count, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT (checksum_sha256) DO UPDATE SET ref_count = ref_count + excluded.ref_count`;
+var D_INSERT_REF2 = `INSERT INTO zerobucket_image_refs (id, checksum_sha256, original_filename, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`;
+var D_SELECT_FULL = `SELECT ${D_COLS2} ${D_FROM2} WHERE r.id = ?`;
+var dSelectMany = (n) => `SELECT ${D_COLS2} ${D_FROM2} WHERE r.id IN (${placeholders(n)})`;
+var D_SELECT_METADATA = `SELECT r.id AS id, b.mime_type AS mime_type, r.original_filename AS original_filename, b.size_bytes AS size_bytes, b.width AS width, b.height AS height, r.checksum_sha256 AS checksum_sha256 ${D_FROM2} WHERE r.id = ?`;
+var D_STREAM_INFO = `SELECT b.size_bytes AS size_bytes, 'sqlite' AS storage_backend, NULL AS object_storage_key ${D_FROM2} WHERE r.id = ?`;
+var D_CHUNK = `SELECT substr(b.data, ?, ?) AS chunk ${D_FROM2} WHERE r.id = ?`;
+var D_EXISTS = `SELECT 1 FROM zerobucket_image_refs WHERE id = ?`;
+var D_DELETE_REF2 = `DELETE FROM zerobucket_image_refs WHERE id = ? RETURNING checksum_sha256`;
+var dDeleteRefs = (n) => `DELETE FROM zerobucket_image_refs WHERE id IN (${placeholders(n)}) RETURNING id, checksum_sha256`;
+var D_DECREMENT2 = `UPDATE zerobucket_blobs SET ref_count = ref_count - ? WHERE checksum_sha256 = ? RETURNING ref_count`;
+var D_DELETE_EMPTY2 = `DELETE FROM zerobucket_blobs WHERE checksum_sha256 = ? AND ref_count <= 0`;
+var IN_CHUNK = 500;
+var ATTEMPT_BUSY_MS = 25;
+var DEFAULT_BUSY_TIMEOUT_MS = 1e4;
+function placeholders(n) {
+  return Array.from({ length: n }, () => "?").join(", ");
+}
+function isoNow() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace("Z", "000+00:00");
+}
+function isBusy(exc) {
+  const code = exc?.code;
+  return typeof code === "string" && (code.startsWith("SQLITE_BUSY") || code.startsWith("SQLITE_LOCKED"));
+}
+var Mutex = class {
+  tail = Promise.resolve();
+  run(fn) {
+    const prev = this.tail;
+    let release;
+    this.tail = new Promise((r) => release = r);
+    return prev.then(fn).finally(release);
+  }
+};
+var SQLiteBackend = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (!opts.path)
+      throw new TypeError(
+        'SQLiteBackend requires a `path` (a file path or ":memory:")'
+      );
+    this.dedup = opts.dedup ?? false;
+    this.busyTimeoutMs = opts.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
+    if (this.dedup && opts.objectStorage) {
+      throw new TypeError(
+        "objectStorage is not supported together with dedup: true (same restriction as the Python package). Tiering moves one image's bytes, but a deduplicated blob can be shared by many images."
+      );
+    }
+  }
+  opts;
+  db;
+  Database;
+  readyPromise;
+  closed = false;
+  dedup;
+  busyTimeoutMs;
+  writeLock = new Mutex();
+  // ---- lifecycle -------------------------------------------------------
+  ready() {
+    if (this.closed)
+      return Promise.reject(
+        new StorageError("This ZeroBucket instance has been closed")
+      );
+    this.readyPromise ??= this.init().catch((exc) => {
+      this.readyPromise = void 0;
+      throw exc;
+    });
+    return this.readyPromise;
+  }
+  async init() {
+    try {
+      const mod = await import("better-sqlite3");
+      this.Database = mod.default ?? mod;
+    } catch (cause) {
+      throw new StorageError(
+        "SQLiteBackend requires the 'better-sqlite3' package. Install it with: npm install better-sqlite3",
+        { cause }
+      );
+    }
+    const db = new this.Database(this.opts.path, { timeout: ATTEMPT_BUSY_MS });
+    try {
+      await this.retrying(() => {
+        if (this.opts.path !== ":memory:" && db.pragma("journal_mode", { simple: true }) !== "wal") {
+          db.pragma("journal_mode = WAL");
+        }
+        db.pragma("foreign_keys = ON");
+        if (this.opts.autoMigrate ?? true)
+          db.exec(this.dedup ? DEDUP_SCHEMA2 : SCHEMA2);
+      });
+    } catch (exc) {
+      try {
+        db.close();
+      } catch {
+      }
+      throw new StorageError(
+        `Could not open SQLite database ${JSON.stringify(this.opts.path)}: ${msg(exc)}`,
+        { cause: exc }
+      );
+    }
+    this.db = db;
+  }
+  async close() {
+    this.closed = true;
+    const db = this.db;
+    this.db = void 0;
+    this.readyPromise = void 0;
+    await this.writeLock.run(async () => {
+      db?.close();
+    });
+  }
+  // ---- execution core --------------------------------------------------
+  emit(operation, start, success, error, retryCount) {
+    const cb = this.opts.onOperation;
+    if (!cb) return;
+    try {
+      cb({
+        operation,
+        durationMs: performance.now() - start,
+        success,
+        error,
+        retryCount
+      });
+    } catch {
+    }
+  }
+  /** Re-run `fn` while another connection holds a lock, sleeping asynchronously between attempts. `fn` must be atomic. */
+  async retrying(fn, onRetry) {
+    const deadline = performance.now() + this.busyTimeoutMs;
+    let attempt = 0;
+    for (; ; ) {
+      try {
+        return fn();
+      } catch (exc) {
+        if (!isBusy(exc) || performance.now() >= deadline) throw exc;
+        attempt += 1;
+        onRetry?.(attempt);
+        await sleep(
+          Math.min(5 * 2 ** Math.min(attempt, 5), 100) + Math.random() * 5
+        );
+      }
+    }
+  }
+  /** BEGIN IMMEDIATE takes the write lock up front, so a BUSY comes before any work and the whole unit is safely re-runnable. */
+  tx(db, work) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+      const result = work(db);
+      db.exec("COMMIT");
+      return result;
+    } catch (exc) {
+      try {
+        db.exec("ROLLBACK");
+      } catch {
+      }
+      throw exc;
+    }
+  }
+  /**
+   * All-or-nothing work on a CALLER-supplied handle. SAVEPOINT works whether or not the caller has an open
+   * transaction: inside one it nests (a failure rolls back only our work); outside one it begins and, on
+   * RELEASE, commits.
+   */
+  atomic(db, work) {
+    db.exec("SAVEPOINT zerobucket_atomic");
+    try {
+      const result = work(db);
+      db.exec("RELEASE SAVEPOINT zerobucket_atomic");
+      return result;
+    } catch (exc) {
+      try {
+        db.exec("ROLLBACK TO SAVEPOINT zerobucket_atomic");
+        db.exec("RELEASE SAVEPOINT zerobucket_atomic");
+      } catch {
+      }
+      throw exc;
+    }
+  }
+  async execute(operation, connection, mode, work) {
+    const start = performance.now();
+    let retries = 0;
+    try {
+      let result;
+      if (connection) {
+        if (typeof connection.prepare !== "function") {
+          throw new TypeError(
+            "SQLiteBackend expects a better-sqlite3 Database as `connection` (an object with prepare()), not a pg client."
+          );
+        }
+        const db = connection;
+        result = mode === "write" ? this.atomic(db, work) : work(db);
+      } else {
+        await this.ready();
+        const db = this.db;
+        const onRetry = (n) => retries = n;
+        result = mode === "write" ? await this.writeLock.run(
+          () => this.retrying(() => this.tx(db, work), onRetry)
+        ) : await this.retrying(() => work(db), onRetry);
+      }
+      this.emit(operation, start, true, null, retries);
+      return result;
+    } catch (exc) {
+      this.emit(operation, start, false, msg(exc), retries);
+      throw exc;
+    }
+  }
+  // ---- StorageBackend --------------------------------------------------
+  async put(row, { connection } = {}) {
+    try {
+      return await this.execute(
+        "put",
+        connection,
+        "write",
+        (db) => this.insertOne(db, row)
+      );
+    } catch (exc) {
+      throw wrap("Failed to store image", exc);
+    }
+  }
+  insertOne(db, r) {
+    const id = randomUUID();
+    const now = isoNow();
+    if (this.dedup) {
+      db.prepare(D_UPSERT).run(
+        r.checksumSha256,
+        r.data,
+        r.mimeType,
+        r.sizeBytes,
+        r.width,
+        r.height,
+        1,
+        now
+      );
+      db.prepare(D_INSERT_REF2).run(
+        id,
+        r.checksumSha256,
+        r.originalFilename,
+        now,
+        now
+      );
+    } else {
+      db.prepare(INSERT2).run(
+        id,
+        r.data,
+        r.mimeType,
+        r.originalFilename,
+        r.sizeBytes,
+        r.width,
+        r.height,
+        r.checksumSha256,
+        now,
+        now
+      );
+    }
+    return id;
+  }
+  async putMany(rows, { connection } = {}) {
+    if (rows.length === 0) return [];
+    try {
+      return await this.execute("put_many", connection, "write", (db) => {
+        if (!this.dedup) return rows.map((r) => this.insertOne(db, r));
+        const now = isoNow();
+        const groups = /* @__PURE__ */ new Map();
+        for (const r of rows) {
+          const g = groups.get(r.checksumSha256);
+          if (g) g.n += 1;
+          else groups.set(r.checksumSha256, { row: r, n: 1 });
+        }
+        for (const [checksum, { row, n }] of groups) {
+          db.prepare(D_UPSERT).run(
+            checksum,
+            row.data,
+            row.mimeType,
+            row.sizeBytes,
+            row.width,
+            row.height,
+            n,
+            now
+          );
+        }
+        return rows.map((r) => {
+          const id = randomUUID();
+          db.prepare(D_INSERT_REF2).run(
+            id,
+            r.checksumSha256,
+            r.originalFilename,
+            now,
+            now
+          );
+          return id;
+        });
+      });
+    } catch (exc) {
+      throw wrap("Failed to store image batch", exc);
+    }
+  }
+  async get(id, { connection } = {}) {
+    if (!isValidId(id)) return null;
+    const norm = id.toLowerCase();
+    let row;
+    try {
+      row = await this.execute(
+        "get",
+        connection,
+        "read",
+        (db) => db.prepare(this.dedup ? D_SELECT_FULL : SELECT_FULL2).get(norm)
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image", exc);
+    }
+    return row ? hydrateRow(row, norm, this.opts.objectStorage) : null;
+  }
+  async getMany(ids, { connection } = {}) {
+    const valid = [
+      ...new Set(ids.filter(isValidId).map((i) => i.toLowerCase()))
+    ];
+    if (valid.length === 0) return [];
+    let rows;
+    try {
+      rows = await this.execute("get_many", connection, "read", (db) => {
+        const out = [];
+        for (let i = 0; i < valid.length; i += IN_CHUNK) {
+          const part = valid.slice(i, i + IN_CHUNK);
+          out.push(
+            ...db.prepare(
+              this.dedup ? dSelectMany(part.length) : selectMany(part.length)
+            ).all(...part)
+          );
+        }
+        return out;
+      });
+    } catch (exc) {
+      throw wrap("Failed to retrieve image batch", exc);
+    }
+    return mapLimit(
+      rows,
+      4,
+      (r) => hydrateRow(r, String(r.id), this.opts.objectStorage)
+    );
+  }
+  async getMetadata(id, { connection } = {}) {
+    if (!isValidId(id)) return null;
+    let row;
+    try {
+      row = await this.execute(
+        "get_metadata",
+        connection,
+        "read",
+        (db) => db.prepare(this.dedup ? D_SELECT_METADATA : SELECT_METADATA2).get(id.toLowerCase())
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image metadata", exc);
+    }
+    if (!row) return null;
+    return {
+      id: String(row.id),
+      mimeType: row.mime_type,
+      originalFilename: row.original_filename,
+      sizeBytes: row.size_bytes,
+      width: row.width,
+      height: row.height,
+      checksumSha256: row.checksum_sha256
+    };
+  }
+  async getStream(id, opts) {
+    if (!isValidId(id)) return null;
+    const norm = id.toLowerCase();
+    const { connection, chunkSize } = opts;
+    if (!Number.isInteger(chunkSize) || chunkSize <= 0)
+      throw new RangeError("chunkSize must be a positive integer");
+    let info;
+    try {
+      info = await this.execute(
+        "get_metadata",
+        connection,
+        "read",
+        (db) => db.prepare(this.dedup ? D_STREAM_INFO : STREAM_INFO).get(norm)
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image metadata", exc);
+    }
+    if (!info) return null;
+    const totalSize = info.size_bytes;
+    const start = opts.range?.start ?? 0;
+    const end = Math.min(opts.range?.end ?? totalSize - 1, totalSize - 1);
+    if (info.storage_backend === "object_storage") {
+      const os = this.opts.objectStorage;
+      if (!os) throw tieredWithoutStorage(norm, info.object_storage_key);
+      return streamFromObjectStorage(
+        os,
+        norm,
+        info.object_storage_key,
+        start,
+        end,
+        chunkSize
+      );
+    }
+    const self = this;
+    async function* generate() {
+      let offset = start;
+      let delivered = 0;
+      const wanted = Math.max(0, end - start + 1);
+      while (delivered < wanted) {
+        const length = Math.min(chunkSize, wanted - delivered);
+        let row;
+        try {
+          row = await self.execute(
+            "get_stream",
+            connection,
+            "read",
+            (db) => db.prepare(self.dedup ? D_CHUNK : CHUNK).get(offset + 1, length, norm)
+          );
+        } catch (exc) {
+          throw wrap("Failed to stream image", exc);
+        }
+        if (!row) {
+          throw new StorageError(
+            `Image ${JSON.stringify(norm)} was deleted while streaming (delivered ${delivered} of ${wanted} bytes). Pass connection with your own open transaction if you need a consistent read across concurrent writers.`
+          );
+        }
+        const chunk = row.chunk;
+        if (!chunk || chunk.length === 0) {
+          throw new StorageError(
+            `Image ${JSON.stringify(norm)} ended early while streaming (delivered ${delivered} of ${wanted} bytes).`
+          );
+        }
+        yield chunk;
+        offset += chunk.length;
+        delivered += chunk.length;
+      }
+    }
+    return generate();
+  }
+  async delete(id, { connection } = {}) {
+    if (!isValidId(id)) return false;
+    const norm = id.toLowerCase();
+    try {
+      if (this.dedup) {
+        return await this.execute("delete", connection, "write", (db) => {
+          const ref = db.prepare(D_DELETE_REF2).get(norm);
+          if (!ref) return false;
+          const dec = db.prepare(D_DECREMENT2).get(1, ref.checksum_sha256);
+          if (dec && dec.ref_count <= 0)
+            db.prepare(D_DELETE_EMPTY2).run(ref.checksum_sha256);
+          return true;
+        });
+      }
+      const row = await this.execute(
+        "delete",
+        connection,
+        "write",
+        (db) => db.prepare(DELETE_ONE).get(norm)
+      );
+      if (row?.storage_backend === "object_storage")
+        await this.cleanupObjects([row.object_storage_key], connection);
+      return row !== void 0;
+    } catch (exc) {
+      throw wrap("Failed to delete image", exc);
+    }
+  }
+  async deleteMany(ids, { connection } = {}) {
+    const valid = [
+      ...new Set(ids.filter(isValidId).map((i) => i.toLowerCase()))
+    ];
+    if (valid.length === 0) return [];
+    try {
+      if (this.dedup) {
+        return await this.execute("delete_many", connection, "write", (db) => {
+          const deleted = [];
+          for (let i = 0; i < valid.length; i += IN_CHUNK) {
+            const part = valid.slice(i, i + IN_CHUNK);
+            deleted.push(...db.prepare(dDeleteRefs(part.length)).all(...part));
+          }
+          const counts = /* @__PURE__ */ new Map();
+          for (const r of deleted)
+            counts.set(
+              r.checksum_sha256,
+              (counts.get(r.checksum_sha256) ?? 0) + 1
+            );
+          for (const [checksum, n] of counts) {
+            const dec = db.prepare(D_DECREMENT2).get(n, checksum);
+            if (dec && dec.ref_count <= 0)
+              db.prepare(D_DELETE_EMPTY2).run(checksum);
+          }
+          return deleted.map((r) => String(r.id));
+        });
+      }
+      const rows = await this.execute(
+        "delete_many",
+        connection,
+        "write",
+        (db) => {
+          const out = [];
+          for (let i = 0; i < valid.length; i += IN_CHUNK) {
+            const part = valid.slice(i, i + IN_CHUNK);
+            out.push(...db.prepare(deleteMany(part.length)).all(...part));
+          }
+          return out;
+        }
+      );
+      await this.cleanupObjects(
+        rows.filter((r) => r.storage_backend === "object_storage").map((r) => r.object_storage_key),
+        connection
+      );
+      return rows.map((r) => String(r.id));
+    } catch (exc) {
+      throw wrap("Failed to delete image batch", exc);
+    }
+  }
+  async exists(id, { connection } = {}) {
+    if (!isValidId(id)) return false;
+    try {
+      return await this.execute(
+        "exists",
+        connection,
+        "read",
+        (db) => db.prepare(this.dedup ? D_EXISTS : EXISTS2).get(id.toLowerCase()) !== void 0
+      );
+    } catch (exc) {
+      throw wrap("Failed to check image existence", exc);
+    }
+  }
+  // ---- maintenance (CLI) -----------------------------------------------
+  async getInfo() {
+    try {
+      return await this.execute("info", void 0, "read", (db) => {
+        const has = (t) => db.prepare(
+          "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?"
+        ).get(t) !== void 0;
+        if (!has(this.dedup ? "zerobucket_image_refs" : "zerobucket_images") || this.dedup && !has("zerobucket_blobs"))
+          return null;
+        const j = this.dedup ? D_FROM2 : "FROM zerobucket_images";
+        const size = this.dedup ? "b.size_bytes" : "size_bytes";
+        const created = this.dedup ? "r.created_at" : "created_at";
+        const mime = this.dedup ? "b.mime_type" : "mime_type";
+        const tot = db.prepare(
+          `SELECT count(*) AS n, coalesce(sum(${size}), 0) AS bytes, min(${created}) AS oldest, max(${created}) AS newest ${j}`
+        ).get();
+        const fmt = db.prepare(
+          `SELECT ${mime} AS m, count(*) AS n, coalesce(sum(${size}), 0) AS bytes ${j} GROUP BY ${mime} ORDER BY count(*) DESC, ${mime}`
+        ).all();
+        let onDisk = null;
+        if (this.opts.path !== ":memory:") {
+          let total = statSync(this.opts.path).size;
+          for (const suffix of ["-wal", "-shm"])
+            if (existsSync(this.opts.path + suffix))
+              total += statSync(this.opts.path + suffix).size;
+          onDisk = prettySize(total);
+        }
+        const info = {
+          mode: this.dedup ? "dedup" : "classic",
+          count: tot.n,
+          totalBytes: Number(tot.bytes),
+          oldest: tot.oldest,
+          newest: tot.newest,
+          onDisk,
+          byFormat: fmt.map((r) => ({
+            mimeType: r.m,
+            count: r.n,
+            bytes: Number(r.bytes)
+          }))
+        };
+        if (this.dedup) {
+          const b = db.prepare(
+            "SELECT count(*) AS n, coalesce(sum(size_bytes), 0) AS bytes FROM zerobucket_blobs"
+          ).get();
+          info.dedup = { blobs: b.n, storedBytes: Number(b.bytes) };
+        } else {
+          const t = db.prepare(
+            "SELECT count(*) AS n, coalesce(sum(size_bytes), 0) AS bytes FROM zerobucket_images WHERE storage_backend = 'object_storage'"
+          ).get();
+          info.tiered = { count: t.n, bytes: Number(t.bytes) };
+        }
+        return info;
+      });
+    } catch (exc) {
+      throw wrap("Failed to read storage info", exc);
+    }
+  }
+  async listImages(o = {}) {
+    const where = [];
+    const params = [];
+    if (o.minSize !== void 0)
+      where.push(`${this.dedup ? "b.size_bytes" : "size_bytes"} >= ?`), params.push(o.minSize);
+    if (o.olderThanDays !== void 0) {
+      const cutoff = new Date(Date.now() - o.olderThanDays * 864e5).toISOString().replace("Z", "000+00:00");
+      where.push(`${this.dedup ? "r.created_at" : "created_at"} <= ?`);
+      params.push(cutoff);
+    }
+    if (o.onlyUntiered && !this.dedup) where.push("storage_backend = 'sqlite'");
+    const from = this.dedup ? D_FROM2 : "FROM zerobucket_images";
+    const idCol = this.dedup ? "r.id" : "id";
+    const tierCol = this.dedup ? "0 AS tiered" : "(storage_backend = 'object_storage') AS tiered";
+    const order = o.sample !== void 0 ? "ORDER BY random()" : `ORDER BY ${this.dedup ? "r.created_at" : "created_at"}, ${idCol}`;
+    const lim = o.sample ?? o.limit;
+    let sql = `SELECT ${idCol} AS id, ${tierCol} ${from}${where.length ? " WHERE " + where.join(" AND ") : ""} ${order}`;
+    if (lim !== void 0) sql += " LIMIT ?", params.push(lim);
+    try {
+      const rows = await this.execute(
+        "list_images",
+        void 0,
+        "read",
+        (db) => db.prepare(sql).all(...params)
+      );
+      return rows.map((r) => ({
+        id: String(r.id),
+        tiered: Boolean(r.tiered)
+      }));
+    } catch (exc) {
+      throw wrap("Failed to list images", exc);
+    }
+  }
+  /**
+   * Remove tiered objects AFTER their rows are gone (a failed object delete leaves a harmless orphan; the
+   * reverse order could leave a row pointing at nothing). Skipped inside a caller-owned transaction, since the
+   * commit outcome is unknown. Failures never fail the delete; they are reported through onOperation.
+   */
+  async cleanupObjects(keys, connection) {
+    const os = this.opts.objectStorage;
+    if (!os || connection || keys.length === 0) return;
+    await Promise.all(
+      keys.map(async (key) => {
+        const start = performance.now();
+        try {
+          await os.delete(key);
+          this.emit("object_storage_delete", start, true, null, 0);
+        } catch (exc) {
+          this.emit("object_storage_delete", start, false, msg(exc), 0);
+        }
+      })
+    );
+  }
+  /**
+   * Move an image's bytes into object storage. null = no such image, false = already tiered, true = tiered now.
+   *
+   * SAFETY (same guarantee as Postgres): the upload happens INSIDE a BEGIN IMMEDIATE transaction; if it fails the
+   * transaction rolls back and the row is untouched.
+   *
+   * TRADEOFF (coarser than Postgres): SQLite has no row locks, so BEGIN IMMEDIATE locks the WHOLE DATABASE for the
+   * upload. Other processes' writes wait; this process's writes queue behind an async lock; reads are not blocked.
+   */
+  async tierToObjectStorage(id, { connection } = {}) {
+    if (this.dedup)
+      throw new StorageError(
+        "tierToObjectStorage() is not supported in dedup mode (a blob may be shared by many images)."
+      );
+    const os = this.opts.objectStorage;
+    if (!os) {
+      throw new StorageError(
+        "tierToObjectStorage() requires objectStorage to be configured (new ZeroBucket({ sqlite, objectStorage: new ObjectStorage({ bucket }) }))."
+      );
+    }
+    if (connection) {
+      throw new StorageError(
+        "tierToObjectStorage() does not accept `connection` on SQLite: it needs its own dedicated connection for the BEGIN IMMEDIATE transaction."
+      );
+    }
+    if (this.opts.path === ":memory:") {
+      throw new StorageError(
+        "tierToObjectStorage() needs a database file: an in-memory SQLite database cannot be shared with its dedicated tiering connection."
+      );
+    }
+    if (!isValidId(id)) return null;
+    const norm = id.toLowerCase();
+    const start = performance.now();
+    let retries = 0;
+    try {
+      await this.ready();
+      const result = await this.writeLock.run(async () => {
+        const tdb = new this.Database(this.opts.path, {
+          timeout: ATTEMPT_BUSY_MS
+        });
+        try {
+          await this.retrying(
+            () => tdb.exec("BEGIN IMMEDIATE"),
+            (n) => retries = n
+          );
+          try {
+            const row = tdb.prepare(SELECT_FOR_TIERING2).get(norm);
+            if (!row) {
+              tdb.exec("ROLLBACK");
+              return null;
+            }
+            if (row.storage_backend !== "sqlite") {
+              tdb.exec("ROLLBACK");
+              return false;
+            }
+            await os.upload(norm, row.data, {
+              mimeType: row.mime_type
+            });
+            tdb.prepare(UPDATE_AFTER_TIERING2).run(os.bucket, norm, isoNow(), norm);
+            tdb.exec("COMMIT");
+            return true;
+          } catch (exc) {
+            try {
+              tdb.exec("ROLLBACK");
+            } catch {
+            }
+            throw exc;
+          }
+        } finally {
+          tdb.close();
+        }
+      });
+      this.emit("tier_to_object_storage", start, true, null, retries);
+      return result;
+    } catch (exc) {
+      this.emit("tier_to_object_storage", start, false, msg(exc), retries);
+      throw wrap("Failed to tier image to object storage", exc);
+    }
+  }
+};
+
+// src/object-storage.ts
+var ObjectStorage = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (!opts.bucket)
+      throw new TypeError("ObjectStorage requires a bucket name");
+    this.bucket = opts.bucket;
+  }
+  opts;
+  bucket;
+  clientPromise;
+  connection() {
+    this.clientPromise ??= (async () => {
+      let sdk;
+      try {
+        sdk = await import("@aws-sdk/client-s3");
+      } catch (cause) {
+        throw new StorageError(
+          "Object-storage tiering requires the optional dependency '@aws-sdk/client-s3'. Install it with: npm install @aws-sdk/client-s3",
+          { cause }
+        );
+      }
+      const o = this.opts;
+      const client = o.client ?? new sdk.S3Client({
+        endpoint: o.endpoint,
+        region: o.region ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? "us-east-1",
+        credentials: o.credentials,
+        forcePathStyle: o.forcePathStyle ?? o.endpoint !== void 0
+      });
+      return { sdk, client };
+    })().catch((exc) => {
+      this.clientPromise = void 0;
+      throw exc;
+    });
+    return this.clientPromise;
+  }
+  async upload(key, data, { mimeType }) {
+    const { sdk, client } = await this.connection();
+    try {
+      await client.send(
+        new sdk.PutObjectCommand({
+          Bucket: this.bucket,
+          Key: key,
+          Body: data,
+          ContentType: mimeType
+        })
+      );
+    } catch (exc) {
+      throw new StorageError(
+        `Failed to upload ${JSON.stringify(key)} to bucket ${JSON.stringify(this.bucket)}: ${msg2(exc)}`,
+        { cause: exc }
+      );
+    }
+  }
+  async download(key) {
+    return this.get(key, void 0);
+  }
+  async downloadRange(key, start, endInclusive) {
+    return this.get(key, `bytes=${start}-${endInclusive}`);
+  }
+  async get(key, range) {
+    const { sdk, client } = await this.connection();
+    try {
+      const res = await client.send(
+        new sdk.GetObjectCommand({
+          Bucket: this.bucket,
+          Key: key,
+          Range: range
+        })
+      );
+      return Buffer.from(await res.Body.transformToByteArray());
+    } catch (exc) {
+      throw new StorageError(
+        `Failed to download ${JSON.stringify(key)} from bucket ${JSON.stringify(this.bucket)}: ${msg2(exc)}`,
+        { cause: exc }
+      );
+    }
+  }
+  async delete(key) {
+    const { sdk, client } = await this.connection();
+    try {
+      await client.send(
+        new sdk.DeleteObjectCommand({ Bucket: this.bucket, Key: key })
+      );
+    } catch (exc) {
+      throw new StorageError(
+        `Failed to delete ${JSON.stringify(key)} from bucket ${JSON.stringify(this.bucket)}: ${msg2(exc)}`,
+        { cause: exc }
+      );
+    }
+  }
+  async exists(key) {
+    const { sdk, client } = await this.connection();
+    try {
+      await client.send(
+        new sdk.HeadObjectCommand({ Bucket: this.bucket, Key: key })
+      );
+      return true;
+    } catch (exc) {
+      const e = exc;
+      if (e.name === "NotFound" || e.name === "NoSuchKey" || e.$metadata?.httpStatusCode === 404)
+        return false;
+      throw new StorageError(
+        `Failed to check ${JSON.stringify(key)} in bucket ${JSON.stringify(this.bucket)}: ${msg2(exc)}`,
+        { cause: exc }
+      );
+    }
+  }
+};
+function msg2(exc) {
+  return exc instanceof Error ? exc.message : String(exc);
+}
+
+// src/cli.ts
+var defaultIO = () => ({
+  out: (l) => console.log(l),
+  err: (l) => console.error(l),
+  env: process.env
+});
+var CliExit = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+  code;
+};
+var usageError = (m) => new CliExit(2, m);
+function cliVersion() {
+  try {
+    return JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf8")
+    ).version;
+  } catch {
+    return "unknown";
+  }
+}
+var HELP = `zerobucket - database-native image storage.
+
+Usage: zerobucket <command> [options]
+
+Commands:
+  init       Create the schema (tables and indexes) if missing.
+  migrate    Apply schema migrations (currently: same as init).
+             --to-dedup  copy every classic image into the dedup tables (PostgreSQL only; non-destructive)
+  info       Show storage stats: count, size, breakdown by format.
+  verify     Re-checksum stored images to detect corruption.
+               --sample N        check a random sample of N images instead of every image
+               --bucket ...      also verify images tiered to object storage (same options as 'tier')
+  tier       Move image(s) from the database into S3-compatible object storage.
+               IMAGE_ID                          tier a single image, OR bulk:
+               --all | --min-size BYTES | --older-than DAYS   (combinable), --limit N, --dry-run
+               --bucket NAME (required)          bucket must already exist
+               --endpoint-url URL                for non-AWS stores (R2, MinIO, B2, Spaces)
+               --region NAME  --aws-access-key-id ID  --aws-secret-access-key KEY
+
+Database (choose one; flags beat environment variables):
+  --database-url URL    PostgreSQL connection string   (env: ZEROBUCKET_DATABASE_URL)
+  --sqlite PATH         SQLite database file            (env: ZEROBUCKET_SQLITE_PATH)
+  --dedup               operate on the dedup-mode tables instead of the classic table
+
+Other:
+  --version, -v         print the version
+  --help, -h            show this help
+
+Exit codes: 0 success, 1 problems found or an operation failed, 2 usage or connection error.`;
+var OPTIONS = {
+  "database-url": { type: "string" },
+  sqlite: { type: "string" },
+  dedup: { type: "boolean" },
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "v" },
+  "to-dedup": { type: "boolean" },
+  sample: { type: "string" },
+  bucket: { type: "string" },
+  "endpoint-url": { type: "string" },
+  region: { type: "string" },
+  "aws-access-key-id": { type: "string" },
+  "aws-secret-access-key": { type: "string" },
+  "min-size": { type: "string" },
+  "older-than": { type: "string" },
+  all: { type: "boolean" },
+  limit: { type: "string" },
+  "dry-run": { type: "boolean" }
+};
+var COMMAND_OPTIONS = {
+  init: [],
+  migrate: ["to-dedup"],
+  info: [],
+  verify: [
+    "sample",
+    "bucket",
+    "endpoint-url",
+    "region",
+    "aws-access-key-id",
+    "aws-secret-access-key"
+  ],
+  tier: [
+    "bucket",
+    "endpoint-url",
+    "region",
+    "aws-access-key-id",
+    "aws-secret-access-key",
+    "min-size",
+    "older-than",
+    "all",
+    "limit",
+    "dry-run"
+  ]
+};
+var COMMON = /* @__PURE__ */ new Set(["database-url", "sqlite", "dedup", "help", "version"]);
+function resolveTarget(v, env) {
+  if (v.sqlite && v["database-url"])
+    throw usageError(
+      "Error: choose one database: --sqlite OR --database-url, not both."
+    );
+  if (v.sqlite) return { kind: "sqlite", path: v.sqlite };
+  if (v["database-url"]) return { kind: "postgres", url: v["database-url"] };
+  const url = env.ZEROBUCKET_DATABASE_URL;
+  const path = env.ZEROBUCKET_SQLITE_PATH;
+  if (url && path) {
+    throw usageError(
+      "Error: both ZEROBUCKET_DATABASE_URL and ZEROBUCKET_SQLITE_PATH are set. Pass --database-url or --sqlite to choose."
+    );
+  }
+  if (url) return { kind: "postgres", url };
+  if (path) return { kind: "sqlite", path };
+  throw usageError(
+    "Error: no database provided. Pass --database-url (PostgreSQL) or --sqlite PATH, or set the ZEROBUCKET_DATABASE_URL / ZEROBUCKET_SQLITE_PATH environment variable."
+  );
+}
+function openBackend(t, o) {
+  return t.kind === "sqlite" ? new SQLiteBackend({
+    path: t.path,
+    dedup: o.dedup,
+    autoMigrate: o.autoMigrate,
+    objectStorage: o.objectStorage
+  }) : new PostgresBackend({
+    connectionString: t.url,
+    dedup: o.dedup,
+    autoMigrate: o.autoMigrate,
+    objectStorage: o.objectStorage,
+    maxRetries: 0
+  });
+}
+async function connect(backend, what) {
+  try {
+    await backend.ready();
+  } catch (exc) {
+    await backend.close().catch(() => {
+    });
+    throw usageError(`Error: could not ${what}: ${msg(exc)}`);
+  }
+}
+function positiveInt(name, raw, min) {
+  if (raw === void 0) return void 0;
+  if (!/^\d+$/.test(raw) || Number(raw) < min)
+    throw usageError(`Error: --${name} must be an integer >= ${min}.`);
+  return Number(raw);
+}
+var num = (n) => n.toLocaleString("en-US");
+function buildObjectStorage(v) {
+  if (!v.bucket) throw usageError("Error: --bucket is required.");
+  const id = v["aws-access-key-id"];
+  const secret = v["aws-secret-access-key"];
+  if (Boolean(id) !== Boolean(secret))
+    throw usageError(
+      "Error: pass both --aws-access-key-id and --aws-secret-access-key, or neither."
+    );
+  return new ObjectStorage({
+    bucket: v.bucket,
+    endpoint: v["endpoint-url"],
+    region: v.region,
+    credentials: id && secret ? { accessKeyId: id, secretAccessKey: secret } : void 0
+  });
+}
+function requireSqliteFile(t, hint) {
+  if (t.kind === "sqlite" && t.path !== ":memory:" && !existsSync2(t.path)) {
+    throw new CliExit(
+      1,
+      `SQLite database file ${JSON.stringify(t.path)} does not exist yet. ${hint}`
+    );
+  }
+}
+async function cmdInit(v, env, io) {
+  const backend = openBackend(resolveTarget(v, env), {
+    dedup: Boolean(v.dedup),
+    autoMigrate: true
+  });
+  await connect(backend, "initialize schema");
+  io.out(
+    v.dedup ? "zerobucket_blobs and zerobucket_image_refs tables and indexes are ready." : "zerobucket_images table and indexes are ready."
+  );
+  await backend.close();
+  return 0;
+}
+async function cmdMigrate(v, env, io) {
+  if (v["to-dedup"]) {
+    const target = resolveTarget(v, env);
+    if (target.kind !== "postgres")
+      throw usageError("Error: --to-dedup is only supported for PostgreSQL.");
+    const backend = openBackend(target, { dedup: true, autoMigrate: true });
+    await connect(backend, "connect");
+    try {
+      const r = await backend.migrateClassicToDedup();
+      io.out(
+        `Migrated ${num(r.imagesMigrated)} image(s) into ${num(r.distinctBlobsCreated)} distinct blob(s).`
+      );
+      io.out(
+        `  Duplicate references found: ${num(r.duplicateReferencesFound)}`
+      );
+      io.out(`  Already migrated (skipped): ${num(r.alreadyMigrated)}`);
+      io.out("The classic table was not modified.");
+      return 0;
+    } catch (exc) {
+      throw new CliExit(1, `Error: ${msg(exc)}`);
+    } finally {
+      await backend.close();
+    }
+  }
+  io.out(
+    "Note: zerobucket does not have versioned migrations yet -- this currently just ensures the base schema exists, same as 'init'."
+  );
+  return cmdInit(v, env, io);
+}
+async function cmdInfo(v, env, io) {
+  const target = resolveTarget(v, env);
+  requireSqliteFile(target, "Run 'zerobucket init --sqlite PATH' first.");
+  const backend = openBackend(target, {
+    dedup: Boolean(v.dedup),
+    autoMigrate: false
+  });
+  await connect(backend, "connect");
+  try {
+    const info = await backend.getInfo();
+    if (!info) {
+      io.out(
+        v.dedup ? "zerobucket_blobs / zerobucket_image_refs tables do not exist yet. Run 'zerobucket init --dedup' first." : "zerobucket_images table does not exist yet. Run 'zerobucket init' first."
+      );
+      return 1;
+    }
+    if (info.mode === "dedup") {
+      io.out(
+        `zerobucket_image_refs: ${num(info.count)} image(s) sharing ${num(info.dedup.blobs)} distinct blob(s)`
+      );
+    } else {
+      io.out(`zerobucket_images: ${num(info.count)} image(s)`);
+    }
+    io.out(
+      `  Total stored bytes (application-recorded): ${num(info.totalBytes)} bytes`
+    );
+    if (info.dedup) {
+      const saved = info.totalBytes - info.dedup.storedBytes;
+      const pct = info.totalBytes > 0 ? (saved / info.totalBytes * 100).toFixed(1) : "0.0";
+      io.out(
+        `  Physical bytes after dedup:                ${num(info.dedup.storedBytes)} bytes (saved ${num(saved)} bytes, ${pct}%)`
+      );
+    }
+    if (info.onDisk) {
+      io.out(
+        target.kind === "postgres" ? `  On-disk size (table + TOAST + indexes):    ${info.onDisk}` : `  On-disk size (database file + WAL):        ${info.onDisk}`
+      );
+    }
+    if (info.tiered && info.tiered.count > 0) {
+      io.out(
+        `  Tiered to object storage:                  ${num(info.tiered.count)} image(s), ${num(info.tiered.bytes)} bytes (not in the database)`
+      );
+    }
+    if (info.oldest !== null) {
+      io.out(`  Oldest: ${info.oldest}`);
+      io.out(`  Newest: ${info.newest}`);
+    }
+    if (info.byFormat.length > 0) {
+      io.out("  By format:");
+      for (const f of info.byFormat) {
+        io.out(
+          `    ${f.mimeType.padEnd(12)} ${String(f.count).padStart(8)} image(s)  ${num(f.bytes).padStart(14)} bytes`
+        );
+      }
+    }
+    return 0;
+  } finally {
+    await backend.close();
+  }
+}
+async function cmdVerify(v, env, io) {
+  const sample = positiveInt("sample", v.sample, 1);
+  const os = v.bucket ? buildObjectStorage(v) : void 0;
+  const target = resolveTarget(v, env);
+  requireSqliteFile(target, "Nothing to verify.");
+  const backend = openBackend(target, {
+    dedup: Boolean(v.dedup),
+    autoMigrate: false,
+    objectStorage: os
+  });
+  await connect(backend, "connect");
+  const mismatches = [];
+  const errors = [];
+  let checked = 0;
+  let skippedTiered = 0;
+  try {
+    let entries;
+    try {
+      entries = await backend.listImages({ sample });
+    } catch (exc) {
+      throw new CliExit(
+        1,
+        `Error: ${msg(exc)} (has 'zerobucket init' been run?)`
+      );
+    }
+    const total = entries.length;
+    if (total === 0) {
+      io.out("No images to verify.");
+      return 0;
+    }
+    io.out(`Verifying ${num(total)} image(s)...`);
+    for (let i = 1; i <= total; i++) {
+      const e = entries[i - 1];
+      if (e.tiered && !os) {
+        skippedTiered += 1;
+      } else {
+        try {
+          const rec = await backend.get(e.id);
+          if (rec) {
+            checked += 1;
+            if (createHash("sha256").update(rec.data).digest("hex") !== rec.checksumSha256.trim())
+              mismatches.push(e.id);
+          }
+        } catch (exc) {
+          errors.push(`${e.id}: ${msg(exc)}`);
+        }
+      }
+      if (i % 100 === 0 || i === total) io.out(`  ${i}/${total} checked...`);
+    }
+  } finally {
+    await backend.close();
+  }
+  io.out("");
+  if (mismatches.length > 0) {
+    io.out(
+      `FAILED: ${mismatches.length} of ${checked} image(s) have a checksum mismatch (possible corruption):`
+    );
+    for (const id of mismatches) io.out(`  ${id}`);
+  }
+  if (errors.length > 0) {
+    io.out(`ERROR: could not read ${errors.length} image(s):`);
+    for (const e of errors) io.out(`  ${e}`);
+  }
+  if (skippedTiered > 0) {
+    io.out(
+      `Note: ${skippedTiered} image(s) tiered to object storage were skipped. Pass --bucket (and credentials) to verify them too.`
+    );
+  }
+  if (mismatches.length > 0 || errors.length > 0) return 1;
+  io.out(`OK: all ${checked} image(s) verified, no checksum mismatches.`);
+  return 0;
+}
+async function cmdTier(v, positional, env, io) {
+  const bulk = Boolean(v.all) || v["min-size"] !== void 0 || v["older-than"] !== void 0;
+  if (positional && bulk)
+    throw usageError(
+      "Error: can't combine a single IMAGE_ID with --all/--min-size/--older-than."
+    );
+  if (!positional && !bulk) {
+    throw usageError(
+      "Error: specify either a single IMAGE_ID to tier, or a bulk selection filter (--all, --min-size, and/or --older-than)."
+    );
+  }
+  if (v.dedup)
+    throw usageError(
+      "Error: tier is not supported with --dedup (a deduplicated blob can be shared by many images)."
+    );
+  const minSize = positiveInt("min-size", v["min-size"], 0);
+  const olderThanDays = positiveInt("older-than", v["older-than"], 0);
+  const limit = positiveInt("limit", v.limit, 1);
+  const os = buildObjectStorage(v);
+  const target = resolveTarget(v, env);
+  requireSqliteFile(target, "Nothing to tier.");
+  const backend = openBackend(target, {
+    dedup: false,
+    autoMigrate: false,
+    objectStorage: os
+  });
+  await connect(backend, "connect");
+  try {
+    let candidates;
+    if (positional) {
+      candidates = [positional];
+    } else {
+      candidates = (await backend.listImages({
+        minSize,
+        olderThanDays,
+        limit,
+        onlyUntiered: true
+      })).map((e) => e.id);
+      if (candidates.length === 0) {
+        io.out("No matching images to tier (or all already tiered).");
+        return 0;
+      }
+    }
+    if (v["dry-run"]) {
+      io.out(`Would tier ${candidates.length} image(s):`);
+      for (const id of candidates) io.out(`  ${id}`);
+      return 0;
+    }
+    let tiered = 0;
+    let skipped = 0;
+    let failed = 0;
+    let notAttempted = 0;
+    const total = candidates.length;
+    for (let i = 1; i <= total; i++) {
+      const id = candidates[i - 1];
+      try {
+        const r = await backend.tierToObjectStorage(id);
+        if (r === null) {
+          io.err(`  NOT FOUND ${id}`);
+          failed += 1;
+        } else if (r === false) skipped += 1;
+        else tiered += 1;
+      } catch (exc) {
+        io.err(`  FAILED ${id}: ${msg(exc)}`);
+        failed += 1;
+        if (/optional dependency '@aws-sdk\/client-s3'/.test(msg(exc))) {
+          notAttempted = total - i;
+          if (notAttempted > 0)
+            io.err(
+              `  Stopping: the remaining ${notAttempted} image(s) would fail the same way.`
+            );
+          break;
+        }
+      }
+      if (total > 1 && (i % 50 === 0 || i === total))
+        io.out(`  ${i}/${total} processed...`);
+    }
+    io.out("");
+    io.out(
+      `Tiered: ${tiered}, already tiered (skipped): ${skipped}, failed: ${failed}${notAttempted > 0 ? `, not attempted: ${notAttempted}` : ""}`
+    );
+    return failed > 0 ? 1 : 0;
+  } finally {
+    await backend.close();
+  }
+}
+async function main(argv, io = defaultIO()) {
+  try {
+    let parsed;
+    try {
+      parsed = parseArgs({
+        args: argv,
+        options: OPTIONS,
+        allowPositionals: true,
+        strict: true
+      });
+    } catch (exc) {
+      throw usageError(
+        `Error: ${msg(exc)}
+Run 'zerobucket --help' for usage.`
+      );
+    }
+    const { values: v, positionals } = parsed;
+    if (v.version) {
+      io.out(`zerobucket ${cliVersion()}`);
+      return 0;
+    }
+    if (v.help) {
+      io.out(HELP);
+      return 0;
+    }
+    const command = positionals[0];
+    if (!command) {
+      io.err(HELP);
+      return 2;
+    }
+    const allowed = COMMAND_OPTIONS[command];
+    if (!allowed)
+      throw usageError(
+        `Error: unknown command ${JSON.stringify(command)}.
+Run 'zerobucket --help' for usage.`
+      );
+    for (const name of Object.keys(v)) {
+      if (!COMMON.has(name) && !allowed.includes(name))
+        throw usageError(`Error: --${name} is not valid for '${command}'.`);
+    }
+    if (positionals.length > (command === "tier" ? 2 : 1))
+      throw usageError(
+        `Error: unexpected argument ${JSON.stringify(positionals[command === "tier" ? 2 : 1])}.`
+      );
+    if (command !== "tier" && positionals.length > 1)
+      throw usageError(
+        `Error: unexpected argument ${JSON.stringify(positionals[1])}.`
+      );
+    switch (command) {
+      case "init":
+        return await cmdInit(v, io.env, io);
+      case "migrate":
+        return await cmdMigrate(v, io.env, io);
+      case "info":
+        return await cmdInfo(v, io.env, io);
+      case "verify":
+        return await cmdVerify(v, io.env, io);
+      default:
+        return await cmdTier(v, positionals[1], io.env, io);
+    }
+  } catch (exc) {
+    if (exc instanceof CliExit) {
+      (exc.code === 1 && !exc.message.startsWith("Error") ? io.out : io.err)(
+        exc.message
+      );
+      return exc.code;
+    }
+    io.err(`Error: ${msg(exc)}`);
+    return 1;
+  }
+}
+
+// src/bin.ts
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (exc) => {
+    console.error(`Error: ${exc instanceof Error ? exc.message : String(exc)}`);
+    process.exitCode = 1;
+  }
+);