zerobucket 0.0.0-stage → 0.4.0

package/dist/index.d.cts

@@ -0,0 +1,307 @@
+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 ContentValidator, V as ValidatedContent } from './client-WZ4VRCPi.cjs';
+export { B as BatchDeleteResult, f as BatchGetResult, g as BatchPutResult, h as BeforeGetHook, i as BeforePutHook, j as Connection, D as DEFAULT_MAX_BYTES, G as GetOptions, I as Image, k as ImageInput, l as ImageMetadata, m as ObjectStorage, n as ObjectStorageOptions, o as OptimizationResult, p as OptimizeOptions, q as PutManyOptions, r as PutOptions, Q as Queryable, s as SqliteDatabaseLike, t as StreamOptions, W as WritableLike, Z as ZeroBucket, u as ZeroBucketOptions, v as optimizeImage, w as readInput } from './client-WZ4VRCPi.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).
+ *
+ * Uses the EXACT schema the Python package creates (zerobucket_images, including
+ * the object-storage tiering columns and CHECK constraint), so a Node app and a
+ * Python app can share one database and read each other's rows.
+ *
+ * Lessons from the Python build, applied here from day one:
+ *  - Retry re-runs the WHOLE unit of work on a fresh connection after a full
+ *    ROLLBACK. It never replays a single statement of a multi-statement
+ *    transaction (the "half-applied put" hazard).
+ *  - Retry never applies when the caller passes `connection` (the caller owns
+ *    the transaction; restarting it is their decision).
+ *  - Pool acquire has an explicit timeout.
+ *  - Migration runs under an advisory lock so N concurrent first-callers do not
+ *    race on CREATE TABLE.
+ */
+
+interface PostgresBackendOptions {
+    /** postgresql:// connection string. Required unless `pool` is given. */
+    connectionString?: string;
+    /** Bring your own pg.Pool (not closed by `close()`). Pool sizing options are then ignored. */
+    pool?: Pool;
+    /** Create the schema on first use. Default true. */
+    autoMigrate?: boolean;
+    /** Retries for transient errors on pooled calls. Default 3; 0 disables. */
+    maxRetries?: number;
+    /** Base for exponential backoff with jitter (capped at 2s). Default 100. */
+    retryBaseDelayMs?: number;
+    poolMinSize?: number;
+    poolMaxSize?: number;
+    /** 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;
+    private pool;
+    private readonly ownsPool;
+    private readyPromise;
+    private closed;
+    private readonly maxRetries;
+    private readonly retryBaseDelayMs;
+    private readonly autoMigrate;
+    private readonly dedup;
+    private readonly sql;
+    constructor(opts: PostgresBackendOptions);
+    ready(): Promise<void>;
+    private init;
+    /** Create the schema if missing. Serialized across processes with an advisory lock. */
+    migrate(): Promise<void>;
+    close(): Promise<void>;
+    private emit;
+    /**
+     * 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.
+     */
+    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>;
+    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>;
+    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>;
+}
+
+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;
+}
+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>;
+    /**
+     * 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[];
+/** Reject images that would decode to more pixels than this, regardless of compressed size (~89 MP). */
+declare const DEFAULT_MAX_PIXELS = 89000000;
+interface ValidatedImage {
+    mimeType: string;
+    width: number;
+    height: number;
+    sizeBytes: number;
+}
+declare function validateImage(data: Buffer, opts: {
+    maxBytes: number;
+    maxPixels?: number;
+    allowedFormats?: readonly string[];
+}): Promise<ValidatedImage>;
+
+/**
+ * Validates that bytes look like a PDF: `%PDF-` magic bytes, non-empty, under a
+ * size ceiling. Deliberately minimal.
+ *
+ * Security note: this does NOT parse the PDF object structure and does not
+ * detect embedded JavaScript, forms or launch actions. Treat it as a sanity
+ * gate, not a security boundary, if you serve user-uploaded PDFs to other users.
+ */
+declare class PDFValidator implements ContentValidator {
+    private readonly opts;
+    constructor(opts?: {
+        maxBytes?: number;
+    });
+    validate(data: Buffer, { maxBytes }: {
+        maxBytes: number;
+    }): ValidatedContent;
+}
+
+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

@@ -0,0 +1,307 @@
+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 ContentValidator, V as ValidatedContent } from './client-WZ4VRCPi.js';
+export { B as BatchDeleteResult, f as BatchGetResult, g as BatchPutResult, h as BeforeGetHook, i as BeforePutHook, j as Connection, D as DEFAULT_MAX_BYTES, G as GetOptions, I as Image, k as ImageInput, l as ImageMetadata, m as ObjectStorage, n as ObjectStorageOptions, o as OptimizationResult, p as OptimizeOptions, q as PutManyOptions, r as PutOptions, Q as Queryable, s as SqliteDatabaseLike, t as StreamOptions, W as WritableLike, Z as ZeroBucket, u as ZeroBucketOptions, v as optimizeImage, w as readInput } from './client-WZ4VRCPi.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).
+ *
+ * Uses the EXACT schema the Python package creates (zerobucket_images, including
+ * the object-storage tiering columns and CHECK constraint), so a Node app and a
+ * Python app can share one database and read each other's rows.
+ *
+ * Lessons from the Python build, applied here from day one:
+ *  - Retry re-runs the WHOLE unit of work on a fresh connection after a full
+ *    ROLLBACK. It never replays a single statement of a multi-statement
+ *    transaction (the "half-applied put" hazard).
+ *  - Retry never applies when the caller passes `connection` (the caller owns
+ *    the transaction; restarting it is their decision).
+ *  - Pool acquire has an explicit timeout.
+ *  - Migration runs under an advisory lock so N concurrent first-callers do not
+ *    race on CREATE TABLE.
+ */
+
+interface PostgresBackendOptions {
+    /** postgresql:// connection string. Required unless `pool` is given. */
+    connectionString?: string;
+    /** Bring your own pg.Pool (not closed by `close()`). Pool sizing options are then ignored. */
+    pool?: Pool;
+    /** Create the schema on first use. Default true. */
+    autoMigrate?: boolean;
+    /** Retries for transient errors on pooled calls. Default 3; 0 disables. */
+    maxRetries?: number;
+    /** Base for exponential backoff with jitter (capped at 2s). Default 100. */
+    retryBaseDelayMs?: number;
+    poolMinSize?: number;
+    poolMaxSize?: number;
+    /** 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;
+    private pool;
+    private readonly ownsPool;
+    private readyPromise;
+    private closed;
+    private readonly maxRetries;
+    private readonly retryBaseDelayMs;
+    private readonly autoMigrate;
+    private readonly dedup;
+    private readonly sql;
+    constructor(opts: PostgresBackendOptions);
+    ready(): Promise<void>;
+    private init;
+    /** Create the schema if missing. Serialized across processes with an advisory lock. */
+    migrate(): Promise<void>;
+    close(): Promise<void>;
+    private emit;
+    /**
+     * 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.
+     */
+    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>;
+    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>;
+    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>;
+}
+
+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;
+}
+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>;
+    /**
+     * 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[];
+/** Reject images that would decode to more pixels than this, regardless of compressed size (~89 MP). */
+declare const DEFAULT_MAX_PIXELS = 89000000;
+interface ValidatedImage {
+    mimeType: string;
+    width: number;
+    height: number;
+    sizeBytes: number;
+}
+declare function validateImage(data: Buffer, opts: {
+    maxBytes: number;
+    maxPixels?: number;
+    allowedFormats?: readonly string[];
+}): Promise<ValidatedImage>;
+
+/**
+ * Validates that bytes look like a PDF: `%PDF-` magic bytes, non-empty, under a
+ * size ceiling. Deliberately minimal.
+ *
+ * Security note: this does NOT parse the PDF object structure and does not
+ * detect embedded JavaScript, forms or launch actions. Treat it as a sanity
+ * gate, not a security boundary, if you serve user-uploaded PDFs to other users.
+ */
+declare class PDFValidator implements ContentValidator {
+    private readonly opts;
+    constructor(opts?: {
+        maxBytes?: number;
+    });
+    validate(data: Buffer, { maxBytes }: {
+        maxBytes: number;
+    }): ValidatedContent;
+}
+
+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 };