zerobucket 0.1.0 → 0.5.0

package/dist/index.d.cts

@@ -1,7 +1,64 @@
-import { S as StorageBackend, O as OperationEvent, P as PreparedRow, C as CallOptions, a as StoredRecord, b as StoredRecordMetadata, c as StreamOptions, d as ContentValidator, V as ValidatedContent } from './client-C_W0t8My.cjs';
-export { B as BatchDeleteResult, e as BatchGetResult, f as BatchPutResult, g as BeforeGetHook, h as BeforePutHook, D as DEFAULT_MAX_BYTES, G as GetOptions, I as Image, i as ImageInput, j as ImageMetadata, k as OptimizationResult, l as OptimizeOptions, m as PutManyOptions, n as PutOptions, Q as Queryable, o as StreamOptions, W as WritableLike, Z as ZeroBucket, p as ZeroBucketOptions, q as optimizeImage, r as readInput } from './client-C_W0t8My.cjs';
+import { S as StorageBackend, O as OperationEvent, a as ObjectStorageLike, P as PreparedRow, C as CallOptions, b as StoredRecord, c as StoredRecordMetadata, d as StreamOptions, e as StorageInfo, I as ImageListOptions, f as ImageListEntry, g as ContentValidator, V as ValidatedContent } from './client-C7xs1dlr.cjs';
+export { B as BatchDeleteResult, h as BatchGetResult, i as BatchPutResult, j as BeforeGetHook, k as BeforePutHook, l as Connection, D as DEFAULT_MAX_BYTES, G as GetOptions, m as Image, n as ImageInput, o as ImageMetadata, p as ObjectStorage, q as ObjectStorageOptions, r as OptimizationResult, s as OptimizeOptions, t as PutManyOptions, u as PutOptions, Q as Queryable, v as SqliteDatabaseLike, w as StreamOptions, W as WritableLike, Z as ZeroBucket, x as ZeroBucketOptions, y as optimizeImage, z as readInput } from './client-C7xs1dlr.cjs';
 import { Pool } from 'pg';
 
+/**
+ * Error hierarchy for ZeroBucket. Mirrors the Python package's exceptions
+ * one-to-one so behaviour is portable across languages.
+ *
+ * Catch broadly with `instanceof ZeroBucketError`, or narrowly with a
+ * subclass such as `ImageNotFoundError`.
+ */
+declare class ZeroBucketError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Any content (image or custom-validated) failed validation. */
+declare class ContentValidationError extends ZeroBucketError {
+}
+/** An image failed validation (bad format, too large, corrupted, ...). */
+declare class ImageValidationError extends ContentValidationError {
+}
+declare class ImageTooLargeError extends ImageValidationError {
+    readonly sizeBytes: number;
+    readonly maxBytes: number;
+    constructor(sizeBytes: number, maxBytes: number);
+}
+declare class UnsupportedFormatError extends ImageValidationError {
+    readonly detectedFormat: string | null;
+    readonly allowed: readonly string[];
+    constructor(detectedFormat: string | null, allowed: readonly string[]);
+}
+/** Image bytes could not be decoded despite a recognizable header. */
+declare class CorruptedImageError extends ImageValidationError {
+}
+/** `get()`, `getStream()` or `metadata()` was called with an id that does not exist. */
+declare class ImageNotFoundError extends ZeroBucketError {
+    readonly imageId: string;
+    constructor(imageId: string);
+}
+/** Underlying storage / database failure not covered above. */
+declare class StorageError extends ZeroBucketError {
+}
+/**
+ * A `beforeGet` / `beforePut` hook denied the operation by returning false.
+ *
+ * If the hook itself throws, that exception propagates unchanged: it is NOT
+ * wrapped in AccessDeniedError and NOT treated as an implicit allow. A broken
+ * authorization check must fail closed, never open.
+ */
+declare class AccessDeniedError extends ZeroBucketError {
+    readonly operation: string;
+    readonly imageId?: string | undefined;
+    constructor(operation: string, imageId?: string | undefined);
+}
+
+/** Helpers shared by every storage adapter (kept here so Postgres and SQLite cannot drift apart). */
+
+/** 1 MiB. Default chunk size for getStream(). */
+declare const DEFAULT_STREAM_CHUNK_SIZE: number;
+
 /**
  * PostgreSQL storage adapter (classic mode).
  *
@@ -20,8 +77,6 @@ import { Pool } from 'pg';
  *    race on CREATE TABLE.
  */
 
-/** 1 MiB. Default chunk size for getStream(). */
-declare const DEFAULT_STREAM_CHUNK_SIZE: number;
 interface PostgresBackendOptions {
     /** postgresql:// connection string. Required unless `pool` is given. */
     connectionString?: string;
@@ -38,6 +93,18 @@ interface PostgresBackendOptions {
     /** Max wait for a pooled connection. Default 10000. */
     poolTimeoutMs?: number;
     onOperation?: (event: OperationEvent) => void;
+    /**
+     * Enables transparent reads of tiered rows and `tierToObjectStorage()`.
+     * Configure it with the same bucket/credentials used to tier the images.
+     */
+    objectStorage?: ObjectStorageLike;
+    /**
+     * Content-addressed mode: identical bytes are stored once (zerobucket_blobs) and each
+     * put() adds a lightweight reference (zerobucket_image_refs) with its own id and filename.
+     * Separate tables from classic mode, so the two can never be confused. Cannot be combined
+     * with `objectStorage`. Same schema as the Python package's dedup mode.
+     */
+    dedup?: boolean;
 }
 declare class PostgresBackend implements StorageBackend {
     private readonly opts;
@@ -48,6 +115,8 @@ declare class PostgresBackend implements StorageBackend {
     private readonly maxRetries;
     private readonly retryBaseDelayMs;
     private readonly autoMigrate;
+    private readonly dedup;
+    private readonly sql;
     constructor(opts: PostgresBackendOptions);
     ready(): Promise<void>;
     private init;
@@ -63,6 +132,14 @@ declare class PostgresBackend implements StorageBackend {
      *                      failures retry the WHOLE closure on a fresh connection.
      */
     private run;
+    /**
+     * 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).
+     */
+    private atomic;
     put(row: PreparedRow, { connection }?: CallOptions): Promise<string>;
     putMany(rows: PreparedRow[], { connection }?: CallOptions): Promise<string[]>;
     get(id: string, { connection }?: CallOptions): Promise<StoredRecord | null>;
@@ -72,60 +149,130 @@ declare class PostgresBackend implements StorageBackend {
     delete(id: string, { connection }?: CallOptions): Promise<boolean>;
     deleteMany(ids: string[], { connection }?: CallOptions): Promise<string[]>;
     exists(id: string, { connection }?: CallOptions): Promise<boolean>;
-    private toRecord;
-    private tieredWithoutStorage;
+    getInfo(): Promise<StorageInfo | null>;
+    listImages(o?: ImageListOptions): Promise<ImageListEntry[]>;
+    private deleteDedup;
+    private deleteManyDedup;
+    /**
+     * 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.
+     */
+    migrateClassicToDedup(): Promise<{
+        imagesMigrated: number;
+        distinctBlobsCreated: number;
+        duplicateReferencesFound: number;
+        alreadyMigrated: number;
+    }>;
+    private hydrate;
+    /**
+     * 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.
+     */
+    private cleanupObject;
+    /**
+     * 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.
+     */
+    tierToObjectStorage(id: string, { connection }?: CallOptions): Promise<boolean | null>;
 }
 
-/**
- * Error hierarchy for ZeroBucket. Mirrors the Python package's exceptions
- * one-to-one so behaviour is portable across languages.
- *
- * Catch broadly with `instanceof ZeroBucketError`, or narrowly with a
- * subclass such as `ImageNotFoundError`.
- */
-declare class ZeroBucketError extends Error {
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
-}
-/** Any content (image or custom-validated) failed validation. */
-declare class ContentValidationError extends ZeroBucketError {
-}
-/** An image failed validation (bad format, too large, corrupted, ...). */
-declare class ImageValidationError extends ContentValidationError {
-}
-declare class ImageTooLargeError extends ImageValidationError {
-    readonly sizeBytes: number;
-    readonly maxBytes: number;
-    constructor(sizeBytes: number, maxBytes: number);
-}
-declare class UnsupportedFormatError extends ImageValidationError {
-    readonly detectedFormat: string | null;
-    readonly allowed: readonly string[];
-    constructor(detectedFormat: string | null, allowed: readonly string[]);
-}
-/** Image bytes could not be decoded despite a recognizable header. */
-declare class CorruptedImageError extends ImageValidationError {
-}
-/** `get()`, `getStream()` or `metadata()` was called with an id that does not exist. */
-declare class ImageNotFoundError extends ZeroBucketError {
-    readonly imageId: string;
-    constructor(imageId: string);
-}
-/** Underlying storage / database failure not covered above. */
-declare class StorageError extends ZeroBucketError {
+interface SQLiteBackendOptions {
+    /** Database file path, or ":memory:" for a throwaway in-process database (tiering is unavailable for ":memory:"). */
+    path: string;
+    /** Create the schema on first use. Default true. */
+    autoMigrate?: boolean;
+    /** Content-addressed mode (separate tables; same schema as the Python package). Cannot be combined with objectStorage. */
+    dedup?: boolean;
+    /** Enables tiering and transparent reads of tiered rows. */
+    objectStorage?: ObjectStorageLike;
+    /** Total time to keep retrying when another connection/process holds the write lock. Default 10000. */
+    busyTimeoutMs?: number;
+    onOperation?: (event: OperationEvent) => void;
 }
-/**
- * A `beforeGet` / `beforePut` hook denied the operation by returning false.
- *
- * If the hook itself throws, that exception propagates unchanged: it is NOT
- * wrapped in AccessDeniedError and NOT treated as an implicit allow. A broken
- * authorization check must fail closed, never open.
- */
-declare class AccessDeniedError extends ZeroBucketError {
-    readonly operation: string;
-    readonly imageId?: string | undefined;
-    constructor(operation: string, imageId?: string | undefined);
+declare class SQLiteBackend implements StorageBackend {
+    private readonly opts;
+    private db;
+    private Database;
+    private readyPromise;
+    private closed;
+    private readonly dedup;
+    private readonly busyTimeoutMs;
+    private readonly writeLock;
+    constructor(opts: SQLiteBackendOptions);
+    ready(): Promise<void>;
+    private init;
+    close(): Promise<void>;
+    private emit;
+    /** Re-run `fn` while another connection holds a lock, sleeping asynchronously between attempts. `fn` must be atomic. */
+    private retrying;
+    /** BEGIN IMMEDIATE takes the write lock up front, so a BUSY comes before any work and the whole unit is safely re-runnable. */
+    private tx;
+    /**
+     * 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.
+     */
+    private atomic;
+    private execute;
+    put(row: PreparedRow, { connection }?: CallOptions): Promise<string>;
+    private insertOne;
+    putMany(rows: PreparedRow[], { connection }?: CallOptions): Promise<string[]>;
+    get(id: string, { connection }?: CallOptions): Promise<StoredRecord | null>;
+    getMany(ids: string[], { connection }?: CallOptions): Promise<StoredRecord[]>;
+    getMetadata(id: string, { connection }?: CallOptions): Promise<StoredRecordMetadata | null>;
+    getStream(id: string, opts: StreamOptions): Promise<AsyncIterable<Buffer> | null>;
+    delete(id: string, { connection }?: CallOptions): Promise<boolean>;
+    deleteMany(ids: string[], { connection }?: CallOptions): Promise<string[]>;
+    exists(id: string, { connection }?: CallOptions): Promise<boolean>;
+    getInfo(): Promise<StorageInfo | null>;
+    listImages(o?: ImageListOptions): Promise<ImageListEntry[]>;
+    /**
+     * 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.
+     */
+    private cleanupObjects;
+    /**
+     * 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.
+     */
+    tierToObjectStorage(id: string, { connection }?: CallOptions): Promise<boolean | null>;
 }
 
 declare const SUPPORTED_FORMATS: readonly string[];
@@ -161,4 +308,4 @@ declare class PDFValidator implements ContentValidator {
     }): ValidatedContent;
 }
 
-export { AccessDeniedError, CallOptions, ContentValidationError, ContentValidator, CorruptedImageError, DEFAULT_MAX_PIXELS, DEFAULT_STREAM_CHUNK_SIZE, ImageNotFoundError, ImageTooLargeError, ImageValidationError, OperationEvent, PDFValidator, PostgresBackend, type PostgresBackendOptions, PreparedRow, SUPPORTED_FORMATS, StorageBackend, StorageError, StoredRecord, StoredRecordMetadata, UnsupportedFormatError, ValidatedContent, type ValidatedImage, ZeroBucketError, validateImage };
+export { AccessDeniedError, CallOptions, ContentValidationError, ContentValidator, CorruptedImageError, DEFAULT_MAX_PIXELS, DEFAULT_STREAM_CHUNK_SIZE, ImageNotFoundError, ImageTooLargeError, ImageValidationError, ObjectStorageLike, OperationEvent, PDFValidator, PostgresBackend, type PostgresBackendOptions, PreparedRow, SQLiteBackend, type SQLiteBackendOptions, SUPPORTED_FORMATS, StorageBackend, StorageError, StoredRecord, StoredRecordMetadata, UnsupportedFormatError, ValidatedContent, type ValidatedImage, ZeroBucketError, validateImage };

package/dist/index.d.ts

@@ -1,7 +1,64 @@
-import { S as StorageBackend, O as OperationEvent, P as PreparedRow, C as CallOptions, a as StoredRecord, b as StoredRecordMetadata, c as StreamOptions, d as ContentValidator, V as ValidatedContent } from './client-C_W0t8My.js';
-export { B as BatchDeleteResult, e as BatchGetResult, f as BatchPutResult, g as BeforeGetHook, h as BeforePutHook, D as DEFAULT_MAX_BYTES, G as GetOptions, I as Image, i as ImageInput, j as ImageMetadata, k as OptimizationResult, l as OptimizeOptions, m as PutManyOptions, n as PutOptions, Q as Queryable, o as StreamOptions, W as WritableLike, Z as ZeroBucket, p as ZeroBucketOptions, q as optimizeImage, r as readInput } from './client-C_W0t8My.js';
+import { S as StorageBackend, O as OperationEvent, a as ObjectStorageLike, P as PreparedRow, C as CallOptions, b as StoredRecord, c as StoredRecordMetadata, d as StreamOptions, e as StorageInfo, I as ImageListOptions, f as ImageListEntry, g as ContentValidator, V as ValidatedContent } from './client-C7xs1dlr.js';
+export { B as BatchDeleteResult, h as BatchGetResult, i as BatchPutResult, j as BeforeGetHook, k as BeforePutHook, l as Connection, D as DEFAULT_MAX_BYTES, G as GetOptions, m as Image, n as ImageInput, o as ImageMetadata, p as ObjectStorage, q as ObjectStorageOptions, r as OptimizationResult, s as OptimizeOptions, t as PutManyOptions, u as PutOptions, Q as Queryable, v as SqliteDatabaseLike, w as StreamOptions, W as WritableLike, Z as ZeroBucket, x as ZeroBucketOptions, y as optimizeImage, z as readInput } from './client-C7xs1dlr.js';
 import { Pool } from 'pg';
 
+/**
+ * Error hierarchy for ZeroBucket. Mirrors the Python package's exceptions
+ * one-to-one so behaviour is portable across languages.
+ *
+ * Catch broadly with `instanceof ZeroBucketError`, or narrowly with a
+ * subclass such as `ImageNotFoundError`.
+ */
+declare class ZeroBucketError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Any content (image or custom-validated) failed validation. */
+declare class ContentValidationError extends ZeroBucketError {
+}
+/** An image failed validation (bad format, too large, corrupted, ...). */
+declare class ImageValidationError extends ContentValidationError {
+}
+declare class ImageTooLargeError extends ImageValidationError {
+    readonly sizeBytes: number;
+    readonly maxBytes: number;
+    constructor(sizeBytes: number, maxBytes: number);
+}
+declare class UnsupportedFormatError extends ImageValidationError {
+    readonly detectedFormat: string | null;
+    readonly allowed: readonly string[];
+    constructor(detectedFormat: string | null, allowed: readonly string[]);
+}
+/** Image bytes could not be decoded despite a recognizable header. */
+declare class CorruptedImageError extends ImageValidationError {
+}
+/** `get()`, `getStream()` or `metadata()` was called with an id that does not exist. */
+declare class ImageNotFoundError extends ZeroBucketError {
+    readonly imageId: string;
+    constructor(imageId: string);
+}
+/** Underlying storage / database failure not covered above. */
+declare class StorageError extends ZeroBucketError {
+}
+/**
+ * A `beforeGet` / `beforePut` hook denied the operation by returning false.
+ *
+ * If the hook itself throws, that exception propagates unchanged: it is NOT
+ * wrapped in AccessDeniedError and NOT treated as an implicit allow. A broken
+ * authorization check must fail closed, never open.
+ */
+declare class AccessDeniedError extends ZeroBucketError {
+    readonly operation: string;
+    readonly imageId?: string | undefined;
+    constructor(operation: string, imageId?: string | undefined);
+}
+
+/** Helpers shared by every storage adapter (kept here so Postgres and SQLite cannot drift apart). */
+
+/** 1 MiB. Default chunk size for getStream(). */
+declare const DEFAULT_STREAM_CHUNK_SIZE: number;
+
 /**
  * PostgreSQL storage adapter (classic mode).
  *
@@ -20,8 +77,6 @@ import { Pool } from 'pg';
  *    race on CREATE TABLE.
  */
 
-/** 1 MiB. Default chunk size for getStream(). */
-declare const DEFAULT_STREAM_CHUNK_SIZE: number;
 interface PostgresBackendOptions {
     /** postgresql:// connection string. Required unless `pool` is given. */
     connectionString?: string;
@@ -38,6 +93,18 @@ interface PostgresBackendOptions {
     /** Max wait for a pooled connection. Default 10000. */
     poolTimeoutMs?: number;
     onOperation?: (event: OperationEvent) => void;
+    /**
+     * Enables transparent reads of tiered rows and `tierToObjectStorage()`.
+     * Configure it with the same bucket/credentials used to tier the images.
+     */
+    objectStorage?: ObjectStorageLike;
+    /**
+     * Content-addressed mode: identical bytes are stored once (zerobucket_blobs) and each
+     * put() adds a lightweight reference (zerobucket_image_refs) with its own id and filename.
+     * Separate tables from classic mode, so the two can never be confused. Cannot be combined
+     * with `objectStorage`. Same schema as the Python package's dedup mode.
+     */
+    dedup?: boolean;
 }
 declare class PostgresBackend implements StorageBackend {
     private readonly opts;
@@ -48,6 +115,8 @@ declare class PostgresBackend implements StorageBackend {
     private readonly maxRetries;
     private readonly retryBaseDelayMs;
     private readonly autoMigrate;
+    private readonly dedup;
+    private readonly sql;
     constructor(opts: PostgresBackendOptions);
     ready(): Promise<void>;
     private init;
@@ -63,6 +132,14 @@ declare class PostgresBackend implements StorageBackend {
      *                      failures retry the WHOLE closure on a fresh connection.
      */
     private run;
+    /**
+     * 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).
+     */
+    private atomic;
     put(row: PreparedRow, { connection }?: CallOptions): Promise<string>;
     putMany(rows: PreparedRow[], { connection }?: CallOptions): Promise<string[]>;
     get(id: string, { connection }?: CallOptions): Promise<StoredRecord | null>;
@@ -72,60 +149,130 @@ declare class PostgresBackend implements StorageBackend {
     delete(id: string, { connection }?: CallOptions): Promise<boolean>;
     deleteMany(ids: string[], { connection }?: CallOptions): Promise<string[]>;
     exists(id: string, { connection }?: CallOptions): Promise<boolean>;
-    private toRecord;
-    private tieredWithoutStorage;
+    getInfo(): Promise<StorageInfo | null>;
+    listImages(o?: ImageListOptions): Promise<ImageListEntry[]>;
+    private deleteDedup;
+    private deleteManyDedup;
+    /**
+     * 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.
+     */
+    migrateClassicToDedup(): Promise<{
+        imagesMigrated: number;
+        distinctBlobsCreated: number;
+        duplicateReferencesFound: number;
+        alreadyMigrated: number;
+    }>;
+    private hydrate;
+    /**
+     * 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.
+     */
+    private cleanupObject;
+    /**
+     * 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.
+     */
+    tierToObjectStorage(id: string, { connection }?: CallOptions): Promise<boolean | null>;
 }
 
-/**
- * Error hierarchy for ZeroBucket. Mirrors the Python package's exceptions
- * one-to-one so behaviour is portable across languages.
- *
- * Catch broadly with `instanceof ZeroBucketError`, or narrowly with a
- * subclass such as `ImageNotFoundError`.
- */
-declare class ZeroBucketError extends Error {
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
-}
-/** Any content (image or custom-validated) failed validation. */
-declare class ContentValidationError extends ZeroBucketError {
-}
-/** An image failed validation (bad format, too large, corrupted, ...). */
-declare class ImageValidationError extends ContentValidationError {
-}
-declare class ImageTooLargeError extends ImageValidationError {
-    readonly sizeBytes: number;
-    readonly maxBytes: number;
-    constructor(sizeBytes: number, maxBytes: number);
-}
-declare class UnsupportedFormatError extends ImageValidationError {
-    readonly detectedFormat: string | null;
-    readonly allowed: readonly string[];
-    constructor(detectedFormat: string | null, allowed: readonly string[]);
-}
-/** Image bytes could not be decoded despite a recognizable header. */
-declare class CorruptedImageError extends ImageValidationError {
-}
-/** `get()`, `getStream()` or `metadata()` was called with an id that does not exist. */
-declare class ImageNotFoundError extends ZeroBucketError {
-    readonly imageId: string;
-    constructor(imageId: string);
-}
-/** Underlying storage / database failure not covered above. */
-declare class StorageError extends ZeroBucketError {
+interface SQLiteBackendOptions {
+    /** Database file path, or ":memory:" for a throwaway in-process database (tiering is unavailable for ":memory:"). */
+    path: string;
+    /** Create the schema on first use. Default true. */
+    autoMigrate?: boolean;
+    /** Content-addressed mode (separate tables; same schema as the Python package). Cannot be combined with objectStorage. */
+    dedup?: boolean;
+    /** Enables tiering and transparent reads of tiered rows. */
+    objectStorage?: ObjectStorageLike;
+    /** Total time to keep retrying when another connection/process holds the write lock. Default 10000. */
+    busyTimeoutMs?: number;
+    onOperation?: (event: OperationEvent) => void;
 }
-/**
- * A `beforeGet` / `beforePut` hook denied the operation by returning false.
- *
- * If the hook itself throws, that exception propagates unchanged: it is NOT
- * wrapped in AccessDeniedError and NOT treated as an implicit allow. A broken
- * authorization check must fail closed, never open.
- */
-declare class AccessDeniedError extends ZeroBucketError {
-    readonly operation: string;
-    readonly imageId?: string | undefined;
-    constructor(operation: string, imageId?: string | undefined);
+declare class SQLiteBackend implements StorageBackend {
+    private readonly opts;
+    private db;
+    private Database;
+    private readyPromise;
+    private closed;
+    private readonly dedup;
+    private readonly busyTimeoutMs;
+    private readonly writeLock;
+    constructor(opts: SQLiteBackendOptions);
+    ready(): Promise<void>;
+    private init;
+    close(): Promise<void>;
+    private emit;
+    /** Re-run `fn` while another connection holds a lock, sleeping asynchronously between attempts. `fn` must be atomic. */
+    private retrying;
+    /** BEGIN IMMEDIATE takes the write lock up front, so a BUSY comes before any work and the whole unit is safely re-runnable. */
+    private tx;
+    /**
+     * 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.
+     */
+    private atomic;
+    private execute;
+    put(row: PreparedRow, { connection }?: CallOptions): Promise<string>;
+    private insertOne;
+    putMany(rows: PreparedRow[], { connection }?: CallOptions): Promise<string[]>;
+    get(id: string, { connection }?: CallOptions): Promise<StoredRecord | null>;
+    getMany(ids: string[], { connection }?: CallOptions): Promise<StoredRecord[]>;
+    getMetadata(id: string, { connection }?: CallOptions): Promise<StoredRecordMetadata | null>;
+    getStream(id: string, opts: StreamOptions): Promise<AsyncIterable<Buffer> | null>;
+    delete(id: string, { connection }?: CallOptions): Promise<boolean>;
+    deleteMany(ids: string[], { connection }?: CallOptions): Promise<string[]>;
+    exists(id: string, { connection }?: CallOptions): Promise<boolean>;
+    getInfo(): Promise<StorageInfo | null>;
+    listImages(o?: ImageListOptions): Promise<ImageListEntry[]>;
+    /**
+     * 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.
+     */
+    private cleanupObjects;
+    /**
+     * 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.
+     */
+    tierToObjectStorage(id: string, { connection }?: CallOptions): Promise<boolean | null>;
 }
 
 declare const SUPPORTED_FORMATS: readonly string[];
@@ -161,4 +308,4 @@ declare class PDFValidator implements ContentValidator {
     }): ValidatedContent;
 }
 
-export { AccessDeniedError, CallOptions, ContentValidationError, ContentValidator, CorruptedImageError, DEFAULT_MAX_PIXELS, DEFAULT_STREAM_CHUNK_SIZE, ImageNotFoundError, ImageTooLargeError, ImageValidationError, OperationEvent, PDFValidator, PostgresBackend, type PostgresBackendOptions, PreparedRow, SUPPORTED_FORMATS, StorageBackend, StorageError, StoredRecord, StoredRecordMetadata, UnsupportedFormatError, ValidatedContent, type ValidatedImage, ZeroBucketError, validateImage };
+export { AccessDeniedError, CallOptions, ContentValidationError, ContentValidator, CorruptedImageError, DEFAULT_MAX_PIXELS, DEFAULT_STREAM_CHUNK_SIZE, ImageNotFoundError, ImageTooLargeError, ImageValidationError, ObjectStorageLike, OperationEvent, PDFValidator, PostgresBackend, type PostgresBackendOptions, PreparedRow, SQLiteBackend, type SQLiteBackendOptions, SUPPORTED_FORMATS, StorageBackend, StorageError, StoredRecord, StoredRecordMetadata, UnsupportedFormatError, ValidatedContent, type ValidatedImage, ZeroBucketError, validateImage };