@cipherstash/migrate 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,740 @@
+import { ClientBase, PoolClient } from 'pg';
+import { z } from 'zod';
+
+/**
+ * DDL for `cipherstash.cs_migrations` — the append-only per-column event
+ * log that tracks encryption-migration runtime state (phase, backfill
+ * cursor, rows processed). Installed by `stash db install`.
+ *
+ * All statements are `CREATE … IF NOT EXISTS` so running the installer
+ * multiple times or alongside an existing deployment is safe.
+ *
+ * This table is intentionally kept separate from `eql_v2_configuration`:
+ * - That table's `data` JSONB has a strict CHECK constraint that forbids
+ *   custom metadata, so we cannot stuff backfill progress into it.
+ * - Its `state` enum is global (`pending`/`encrypting`/`active`/`inactive`
+ *   — only one of the first three at a time), which cannot represent
+ *   multiple columns in different phases simultaneously.
+ * - Checkpoint writes during backfill would collide with Proxy's 60s
+ *   config refresh cycle.
+ */
+declare const MIGRATIONS_SCHEMA_SQL = "\nCREATE SCHEMA IF NOT EXISTS cipherstash;\n\nCREATE TABLE IF NOT EXISTS cipherstash.cs_migrations (\n  id             bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,\n  table_name     text NOT NULL,\n  column_name    text NOT NULL,\n  event          text NOT NULL,\n  phase          text NOT NULL,\n  cursor_value   text,\n  rows_processed bigint,\n  rows_total     bigint,\n  details        jsonb,\n  created_at     timestamptz NOT NULL DEFAULT now()\n);\n\nCREATE INDEX IF NOT EXISTS cs_migrations_column_id_desc\n  ON cipherstash.cs_migrations (table_name, column_name, id DESC);\n";
+/**
+ * Create the `cipherstash` schema and `cs_migrations` table if they do not
+ * already exist. Safe to call on every `stash db install` invocation.
+ *
+ * Requires `CREATE SCHEMA` privileges on the database. If the caller lacks
+ * them, the query will fail and the error bubbles up — the CLI currently
+ * warns but does not abort, on the theory that a human DBA can install
+ * this schema out-of-band using `MIGRATIONS_SCHEMA_SQL` directly.
+ */
+declare function installMigrationsSchema(client: ClientBase): Promise<void>;
+
+/**
+ * Discrete event types written to the `cipherstash.cs_migrations` event log.
+ *
+ * Events are snake_case (for SQL readability); phases are kebab-case (for
+ * user-facing CLI output). Most events correspond 1:1 with a phase, except:
+ * - `backfill_started` and `backfill_checkpoint` both live inside phase
+ *   `backfilling`; the `_started` event records the initial intent (and
+ *   whether we resumed), while each `_checkpoint` records a committed chunk.
+ * - `error` records a failure at whatever phase was current; it does not
+ *   change the effective phase (so a retry resumes from where it failed).
+ */
+type MigrationEvent = 'schema_added' | 'dual_writing' | 'backfill_started' | 'backfill_checkpoint' | 'backfilled' | 'cut_over' | 'dropped' | 'error';
+/**
+ * The per-column lifecycle phase as surfaced in status/plan output and
+ * driven by the `stash encrypt {backfill,cutover,drop}` commands.
+ *
+ * ```
+ * schema-added  → the <col>_encrypted column exists and is registered with EQL
+ * dual-writing  → app writes both plaintext and encrypted on inserts/updates
+ * backfilling   → runBackfill is (or has been) encrypting historical rows
+ * backfilled    → all historical rows encrypted; safe to cut over reads
+ * cut-over      → columns renamed (via eql_v2.rename_encrypted_columns)
+ * dropped       → old plaintext column removed
+ * ```
+ */
+type MigrationPhase = 'schema-added' | 'dual-writing' | 'backfilling' | 'backfilled' | 'cut-over' | 'dropped';
+/**
+ * Composite key of `<table>.<column>`. Used as the map key by
+ * {@link latestByColumn}.
+ */
+type ColumnKey = `${string}.${string}`;
+/**
+ * A single row from `cipherstash.cs_migrations`, decoded with numeric bigints
+ * converted to `number` and column names camel-cased. `id` is a string to
+ * avoid JavaScript bigint precision loss for very large tables.
+ */
+interface MigrationStateRow {
+    /** Row id, stringified from the bigint column. Monotonically increasing. */
+    id: string;
+    tableName: string;
+    columnName: string;
+    event: MigrationEvent;
+    /** Effective phase *after* this event. */
+    phase: MigrationPhase;
+    /**
+     * Value of `pkColumn` for the last row processed in the most recent
+     * chunk. Set on `backfill_checkpoint` and `backfilled`; `null` on other
+     * event types. Stored as text so it works for any PK type.
+     */
+    cursorValue: string | null;
+    /** Cumulative rows encrypted. `null` on non-backfill events. */
+    rowsProcessed: number | null;
+    /** Target rows for this migration. `null` on non-backfill events. */
+    rowsTotal: number | null;
+    /**
+     * Free-form event-specific metadata. Examples: `{ chunkSize, resumed }`
+     * on `backfill_started`; `{ message, chunkIndex }` on `error`.
+     */
+    details: Record<string, unknown> | null;
+    createdAt: Date;
+}
+/**
+ * Input to {@link appendEvent}. All fields other than `tableName`,
+ * `columnName`, `event`, and `phase` are optional and stored as `NULL` when
+ * omitted.
+ */
+interface AppendEventInput {
+    tableName: string;
+    columnName: string;
+    event: MigrationEvent;
+    phase: MigrationPhase;
+    cursorValue?: string | null;
+    rowsProcessed?: number | null;
+    rowsTotal?: number | null;
+    details?: Record<string, unknown> | null;
+}
+/**
+ * Append a new event row to `cipherstash.cs_migrations`. The table is
+ * append-only — existing rows are never updated, so history is preserved
+ * and concurrent writers never clobber each other.
+ *
+ * The "current state" of a column is derived by selecting the row with the
+ * greatest `id` for that `(tableName, columnName)` pair.
+ */
+declare function appendEvent(client: ClientBase, input: AppendEventInput): Promise<MigrationStateRow>;
+/**
+ * Return the most recent event row for every column tracked in
+ * `cs_migrations`, keyed by `"<tableName>.<columnName>"`. Used by
+ * `stash encrypt status` and `plan` to render a table view.
+ *
+ * Columns with no recorded events are simply absent from the map — there
+ * is no synthetic "nothing happened yet" entry.
+ */
+declare function latestByColumn(client: ClientBase): Promise<Map<ColumnKey, MigrationStateRow>>;
+/**
+ * Latest event row for a single column, or `null` if the column has no
+ * recorded events. Used by the backfill runner to determine whether it is
+ * resuming a checkpoint or starting fresh.
+ */
+declare function progress(client: ClientBase, tableName: string, columnName: string): Promise<MigrationStateRow | null>;
+
+/**
+ * Thin, typed wrappers around the EQL (Encrypt Query Language) functions
+ * installed by `stash db install`. These mirror the canonical SQL API that
+ * CipherStash Proxy also drives, so every action we take here stays
+ * visible to Proxy using the same column-level config.
+ *
+ * Defined by the EQL project at
+ * https://github.com/cipherstash/encrypt-query-language — see
+ * `src/config/functions.sql` and `src/encryptindex/functions.sql` for the
+ * source of truth.
+ */
+/**
+ * A column that has been registered in the `pending` EQL configuration but
+ * is not yet part of the `active` config. Returned by
+ * {@link selectPendingColumns}.
+ */
+interface PendingColumn {
+    tableName: string;
+    columnName: string;
+}
+/**
+ * Return columns present in the `pending` EQL config but absent (or
+ * different) in the `active` one. Wraps `eql_v2.select_pending_columns()`.
+ * Useful for showing "what's about to change" before calling
+ * {@link readyForEncryption} + activating the pending config.
+ */
+declare function selectPendingColumns(client: ClientBase): Promise<PendingColumn[]>;
+/**
+ * Check EQL's precondition for activating a pending configuration: every
+ * pending column must have a matching `eql_v2_encrypted`-typed target
+ * column in the schema. Returns `true` if activation is safe.
+ * Wraps `eql_v2.ready_for_encryption()`.
+ */
+declare function readyForEncryption(client: ClientBase): Promise<boolean>;
+/**
+ * Atomically rename every `<col>` → `<col>_plaintext` and
+ * `<col>_encrypted` → `<col>` across tables in the **pending** EQL config.
+ * Wraps `eql_v2.rename_encrypted_columns()`.
+ *
+ * This is the **cut-over primitive**: after this returns, any SQL that
+ * reads `<col>` transparently receives the encrypted column (decrypted on
+ * read by Proxy or Protect). Call inside a transaction.
+ *
+ * **Requires a pending configuration.** The underlying EQL function calls
+ * `select_pending_columns()` and raises `'No pending configuration exists
+ * to encrypt'` if none is registered. Call `db push` to register a pending
+ * config first; if no rename targets are present in the diff, the loop
+ * inside `rename_encrypted_columns()` does nothing — but the function
+ * still requires pending to exist.
+ *
+ * Renames physical columns only — does not advance the EQL state machine.
+ * Pair with {@link migrateConfig} + {@link activateConfig} to finish the
+ * pending → encrypting → active transition.
+ */
+declare function renameEncryptedColumns(client: ClientBase): Promise<void>;
+/**
+ * Advance the EQL state machine: `pending → encrypting`. Wraps
+ * `eql_v2.migrate_config()`.
+ *
+ * Throws when:
+ * - There is no pending configuration to migrate.
+ * - There is already an encrypting configuration in flight.
+ * - Some pending column lacks its encrypted target column (`<col>_encrypted`
+ *   doesn't exist in the schema with `eql_v2_encrypted` UDT).
+ */
+declare function migrateConfig(client: ClientBase): Promise<void>;
+/**
+ * Advance the EQL state machine: `encrypting → active`. Wraps
+ * `eql_v2.activate_config()`. Marks any prior `active` row as `inactive`
+ * in the same call.
+ *
+ * Throws when there is no encrypting configuration to activate. Always
+ * call after {@link migrateConfig} has flipped the pending row to
+ * encrypting (typically inside the same transaction as
+ * {@link renameEncryptedColumns} for cutover; or alone for non-rename
+ * activations like adding a new column to an existing config).
+ */
+declare function activateConfig(client: ClientBase): Promise<void>;
+/**
+ * Discard the pending configuration without applying it. Wraps
+ * `eql_v2.discard()`. Used by `db push` to clean up any stale pending
+ * before writing a new one — the state machine only allows one pending
+ * row at a time, and a stale pending blocks new pushes.
+ *
+ * No-op when no pending exists.
+ */
+declare function discardPendingConfig(client: ClientBase): Promise<void>;
+/**
+ * Nudge Proxy to re-read its config immediately instead of waiting for its
+ * next 60-second refresh tick. Wraps `eql_v2.reload_config()`.
+ *
+ * **Must be executed through a CipherStash Proxy connection** — when
+ * connected directly to Postgres, `reload_config()` is a no-op (by design,
+ * per the EQL documentation). The CLI's `cutover` command accepts a
+ * `--proxy-url` flag and will connect to that separately to issue this.
+ */
+declare function reloadConfig(client: ClientBase): Promise<void>;
+/**
+ * Return EQL's count of rows in `<tableName>.<columnName>` whose encrypted
+ * payload's config version matches the currently active config. Useful as
+ * a cheap sanity check — 0 after a backfill generally means something's
+ * wrong (wrong config active, or the backfill wrote with a stale version).
+ *
+ * Wraps `eql_v2.count_encrypted_with_active_config(table, column)`.
+ *
+ * Returns `bigint` because the underlying Postgres function returns
+ * `BIGINT` and naively coercing to JS `number` loses precision past
+ * `Number.MAX_SAFE_INTEGER` — exactly the row counts large-table users
+ * are running this against. Callers that need a JS number can do their
+ * own range check.
+ */
+declare function countEncryptedWithActiveConfig(client: ClientBase, tableName: string, columnName: string): Promise<bigint>;
+
+/**
+ * Inputs to {@link fetchUnencryptedPage}.
+ */
+interface KeysetPageOptions {
+    /** Physical table name. Supports `schema.table`. */
+    tableName: string;
+    /**
+     * Primary-key column used for keyset pagination. Must be comparable with
+     * `>`. Cast to text by the query so any PK type works.
+     */
+    pkColumn: string;
+    /** Column to read the plaintext from, e.g. `email`. */
+    plaintextColumn: string;
+    /**
+     * Target encrypted column, e.g. `email_encrypted`. Rows where this is
+     * already non-null are skipped (idempotency guard).
+     */
+    encryptedColumn: string;
+    /**
+     * Exclusive lower bound on `pkColumn`. Set to `null` to start from the
+     * beginning; pass the `lastPk` of the previous page to continue.
+     */
+    after: string | null;
+    /** Maximum rows returned per call. */
+    limit: number;
+    /**
+     * When true, drop the `<encrypted_col> IS NULL` guard so rows that
+     * already have ciphertext are re-emitted. Used by `stash encrypt
+     * backfill --force` to recover from drift (e.g. dual-writes weren't
+     * actually deployed when an earlier backfill ran). Off by default — the
+     * guard makes normal re-runs idempotent.
+     */
+    force?: boolean;
+}
+/**
+ * One page of rows from {@link fetchUnencryptedPage}. `lastPk` is `null`
+ * only when the page is empty — the caller's completion signal.
+ */
+interface KeysetPage<Row = Record<string, unknown>> {
+    rows: Row[];
+    lastPk: string | null;
+}
+/**
+ * Fetch the next page of rows that still need encryption for a given column.
+ *
+ * Guards with `plaintext_col IS NOT NULL AND encrypted_col IS NULL` so a
+ * concurrent backfill or a re-run never re-processes the same row, even if
+ * the pagination cursor is lost. The ORDER BY + LIMIT form gives keyset
+ * (seek) pagination rather than OFFSET, which keeps the scan bounded as
+ * the cursor advances.
+ */
+declare function fetchUnencryptedPage(client: ClientBase, opts: KeysetPageOptions): Promise<KeysetPage<{
+    pk: string;
+    plaintext: unknown;
+}>>;
+/**
+ * Count rows that still need encryption: `plaintext IS NOT NULL AND
+ * encrypted IS NULL`. Called once at the start of a backfill to compute
+ * `rowsTotal` for progress reporting; does not hold a snapshot, so new
+ * rows inserted during the backfill are simply picked up on the next
+ * chunk's SELECT.
+ *
+ * When `force` is true, drops the `encrypted IS NULL` guard — used by
+ * `--force` to count every plaintext row, including ones that already
+ * have a (potentially stale) ciphertext.
+ */
+declare function countUnencrypted(client: ClientBase, tableName: string, plaintextColumn: string, encryptedColumn: string, force?: boolean): Promise<number>;
+/**
+ * Quote a possibly schema-qualified table name for use in a SQL statement.
+ * `"foo"` → `"foo"`; `"public.foo"` → `"public"."foo"`. Use for identifiers
+ * that cannot be parameterised.
+ */
+declare function qualifyTable(tableName: string): string;
+
+/**
+ * Quote a PostgreSQL identifier. Doubles any embedded `"` and wraps in `"`.
+ * Use for table/column names that cannot be parameterised.
+ */
+declare function quoteIdent(identifier: string): string;
+
+/**
+ * Shape returned by {@link EncryptionClientLike.bulkEncryptModels} on success.
+ * `data` is the array of models with the configured fields replaced by
+ * ciphertext payloads, preserving `__pk` and any other non-encrypted fields.
+ */
+interface BulkEncryptResultSuccess<T> {
+    failure?: undefined;
+    data: T[];
+}
+/**
+ * Shape returned by {@link EncryptionClientLike.bulkEncryptModels} on failure.
+ * Matches `@byteslice/result`'s `{ failure: { message } }` convention used
+ * by `@cipherstash/stack`. The backfill halts and writes an `error` event
+ * to `cs_migrations` when this is returned.
+ */
+interface BulkEncryptResultFailure {
+    failure: {
+        message: string;
+        type?: string;
+    };
+    data?: undefined;
+}
+/**
+ * Discriminated union returned by bulk-encrypt. Narrow with `if (r.failure)`
+ * vs `if (r.data)`. No exceptions are thrown by the underlying operation.
+ */
+type BulkEncryptResult<T> = BulkEncryptResultSuccess<T> | BulkEncryptResultFailure;
+/**
+ * A thenable wrapper around {@link BulkEncryptResult}. `@cipherstash/stack`'s
+ * `bulkEncryptModels` returns a fluent operation builder that resolves to a
+ * `Result` when awaited; this alias accepts anything `PromiseLike` so we
+ * don't bind to the full operation class in type-land.
+ */
+type BulkEncryptThenable<T> = PromiseLike<BulkEncryptResult<T>>;
+/**
+ * Minimal surface of `@cipherstash/stack`'s `EncryptionClient` used by
+ * {@link runBackfill}. Only `bulkEncryptModels` is required — the backfill
+ * encrypts in batches, it does not need the single-value `encrypt` API.
+ *
+ * Supplying an object that duck-types to this interface is enough; you do
+ * not have to import `EncryptionClient` itself.
+ *
+ * @example
+ * ```ts
+ * // Typical wiring: the user's `src/encryption/index.ts` exports an
+ * // already-initialised client, and you pass it through.
+ * import { encryptionClient } from './src/encryption/index.js'
+ * await runBackfill({ encryptionClient, ... })
+ * ```
+ */
+interface EncryptionClientLike {
+    /**
+     * Bulk-encrypt a batch of plaintext models against a table schema.
+     *
+     * @param input - Array of models. Each row is `{ [schemaColumnKey]: plaintext, ... }`.
+     *   The backfill also includes a `__pk` field per row so it can correlate
+     *   the encrypted result back to the database row on UPDATE.
+     * @param table - The `EncryptedTable` schema for the target table. Typed
+     *   as `any` here to keep this library decoupled from `@cipherstash/stack`.
+     */
+    bulkEncryptModels(input: Array<Record<string, unknown>>, table: any): BulkEncryptThenable<Record<string, unknown>>;
+}
+/**
+ * Snapshot of backfill progress, passed to {@link BackfillOptions.onProgress}
+ * after every successful chunk commit. Values represent the cumulative state
+ * *after* the most recent chunk — including any rows processed by a prior
+ * run that this invocation resumed from.
+ */
+interface BackfillProgress {
+    /** Total rows written to the encrypted column so far (includes a resumed prior run). */
+    rowsProcessed: number;
+    /** Total rows we expect to process over the life of this migration (incl. resumed). */
+    rowsTotal: number;
+    /** PK of the last row processed in the most recent chunk, cast to text. */
+    lastPk: string | null;
+    /** Chunk size used for this run (echoed from {@link BackfillOptions.chunkSize}). */
+    chunkSize: number;
+    /** Zero-based index of the chunk that just completed. */
+    chunkIndex: number;
+}
+/**
+ * Options for {@link runBackfill}.
+ *
+ * Distinguishes three separate name spaces that a reader has to keep straight:
+ * - **Physical names** ({@link tableName}, {@link plaintextColumn}, {@link encryptedColumn}, {@link pkColumn})
+ *   are Postgres identifiers used verbatim in SQL.
+ * - **Schema name** ({@link schemaColumnKey}) is the key on the `EncryptedTable`
+ *   schema object that corresponds to the column. In the common drizzle
+ *   convention — where the schema declares the encrypted column (not the
+ *   plaintext one) — this equals `encryptedColumn`. Pass explicitly only
+ *   when your schema's object keys diverge from the physical column names.
+ */
+interface BackfillOptions {
+    /**
+     * A pg pool client the runner owns for the duration of the call. The
+     * runner issues `BEGIN`/`COMMIT` on this connection for each chunk, so it
+     * must not be shared across concurrent work during the backfill.
+     *
+     * Acquire with `const db = await pool.connect()`, release with
+     * `db.release()` in your `finally`.
+     */
+    db: PoolClient;
+    /**
+     * Initialised encryption client. See {@link EncryptionClientLike} for the
+     * required surface (just `bulkEncryptModels`).
+     */
+    encryptionClient: EncryptionClientLike;
+    /**
+     * The `EncryptedTable` schema object for the target table, as exported
+     * from the user's `src/encryption/index.ts`. Passed through to
+     * `encryptionClient.bulkEncryptModels(models, tableSchema)`. Typed as
+     * `any` to avoid coupling this library to `@cipherstash/stack`.
+     */
+    tableSchema: any;
+    /**
+     * Physical Postgres table name. Supports `"schema.table"` for non-default
+     * schemas (identifiers are quoted automatically).
+     */
+    tableName: string;
+    /**
+     * The key in {@link tableSchema} that corresponds to this column. With
+     * the drizzle `extractEncryptionSchema` convention, where the schema is
+     * derived from a table like `{ email_encrypted: encryptedType(...) }`,
+     * this equals {@link encryptedColumn}. With a handwritten
+     * `encryptedTable('users', { email: … })` schema where there's only one
+     * column, this usually equals {@link plaintextColumn}.
+     */
+    schemaColumnKey: string;
+    /**
+     * Physical column that holds the plaintext being encrypted, e.g. `email`.
+     * The runner reads rows where this is `NOT NULL` and the target encrypted
+     * column is `NULL`.
+     */
+    plaintextColumn: string;
+    /**
+     * Physical column that receives the `eql_v2_encrypted` ciphertext JSON,
+     * e.g. `email_encrypted`. Must already exist (typically created by
+     * `drizzle-kit` / a prior migration) before backfill starts.
+     */
+    encryptedColumn: string;
+    /**
+     * Physical single-column primary key used for keyset pagination — the
+     * runner issues `WHERE pk > $after ORDER BY pk ASC LIMIT $n`. Must be
+     * comparable with `>` (bigint, integer, text, uuid all work). Composite
+     * primary keys are not yet supported.
+     */
+    pkColumn: string;
+    /**
+     * Rows per chunk / transaction. Default 1000. Tune down if you see lock
+     * contention, up for tables with small row payloads. A single chunk is
+     * one `BEGIN`/`UPDATE`/`INSERT checkpoint`/`COMMIT` cycle, so the value
+     * also bounds how much work is lost when you `Ctrl-C` mid-chunk.
+     */
+    chunkSize?: number;
+    /**
+     * Optional abort signal. Checked *between* chunks — the in-flight chunk
+     * always completes and checkpoints before the loop exits. Safe to wire
+     * to `SIGINT` / `SIGTERM`; the CLI does exactly this.
+     */
+    signal?: AbortSignal;
+    /**
+     * Invoked synchronously after each chunk has committed. Safe for logging
+     * and UI updates; throwing from this callback will kill the backfill.
+     */
+    onProgress?: (progress: BackfillProgress) => void;
+    /**
+     * Optional coercion applied to each row's plaintext value before it is
+     * passed to {@link EncryptionClientLike.bulkEncryptModels}. Needed when
+     * the pg driver's native JS type doesn't match the schema's declared
+     * dataType — e.g. pg returns `numeric` as a string, but a schema
+     * declaring `dataType('number')` expects a JS number. The CLI
+     * builds an appropriate coercer from the schema's `cast_as`; library
+     * callers can supply their own or leave undefined (identity).
+     */
+    transformPlaintext?: (value: unknown) => unknown;
+    /**
+     * When true, encrypt every row whose plaintext is non-null — including
+     * rows that already have a ciphertext in {@link encryptedColumn}.
+     *
+     * The default backfill skips already-encrypted rows for idempotency.
+     * `force` is the recovery path for *drift*: rows where the ciphertext
+     * is out of sync with the plaintext because the application was
+     * updating the plaintext column without dual-writing the encrypted
+     * twin. The drifted ciphertext is overwritten by re-encrypting the
+     * current plaintext.
+     *
+     * Not destructive (overwriting a correctly-encrypted value with a
+     * fresh encryption of the same plaintext is wasted work, not data
+     * loss), but expensive: every row is re-encrypted even if it didn't
+     * need to be. The CLI also appends `details: { force: true }` to the
+     * `backfill_started` event so audit queries can spot the recovery
+     * runs in `cs_migrations` history.
+     */
+    force?: boolean;
+}
+/**
+ * Return value from {@link runBackfill}.
+ */
+interface BackfillResult {
+    /**
+     * `true` if the run began from a previously-recorded checkpoint rather
+     * than starting fresh. Determined by the most recent event for this
+     * column being a `backfill_checkpoint`.
+     */
+    resumed: boolean;
+    /**
+     * Cumulative rows written to the encrypted column, including any from a
+     * prior run this invocation resumed from.
+     */
+    rowsProcessed: number;
+    /**
+     * Total rows the migration expects to process end-to-end (including
+     * resumed). Computed as `priorProcessed + currentRunTotal` at start.
+     */
+    rowsTotal: number;
+    /**
+     * `true` if this run drained all remaining rows. `false` means the run
+     * was aborted (via {@link BackfillOptions.signal}) or is otherwise
+     * paused and should be resumed by re-invoking with the same options.
+     */
+    completed: boolean;
+}
+/**
+ * Run a chunked, resumable, idempotent backfill of plaintext → encrypted.
+ *
+ * Per chunk, in a single transaction:
+ *   1. `SELECT` the next page of rows where the encrypted column is `NULL`
+ *      and the PK is greater than the cursor.
+ *   2. Encrypt the batch via {@link EncryptionClientLike.bulkEncryptModels}.
+ *   3. `UPDATE … FROM (VALUES …)` to write the ciphertext back.
+ *   4. `INSERT` a `backfill_checkpoint` event into `cipherstash.cs_migrations`.
+ *   5. `COMMIT`.
+ *
+ * **Idempotency** — the `encrypted IS NULL` guard in both the SELECT and the
+ * UPDATE's `WHERE` clause means re-runs never double-write a row, even if
+ * the cursor is lost.
+ *
+ * **Resumability** — restarting with the same arguments will pick up from
+ * the last committed checkpoint. Use {@link BackfillOptions.signal} to
+ * abort cleanly on `SIGINT`.
+ *
+ * **Failure handling** — if any chunk fails (encrypt error or DB error),
+ * the transaction is rolled back, an `error` event is appended to
+ * `cs_migrations` for diagnostics, and the error is re-thrown.
+ *
+ * @example
+ * ```ts
+ * const db = await pool.connect()
+ * try {
+ *   const result = await runBackfill({
+ *     db,
+ *     encryptionClient,
+ *     tableSchema: usersTable,
+ *     tableName: 'users',
+ *     schemaColumnKey: 'email',
+ *     plaintextColumn: 'email',
+ *     encryptedColumn: 'email_encrypted',
+ *     pkColumn: 'id',
+ *     chunkSize: 1000,
+ *     onProgress: (p) => console.log(`${p.rowsProcessed}/${p.rowsTotal}`),
+ *   })
+ *   console.log(result.completed ? 'done' : 'paused — re-run to resume')
+ * } finally {
+ *   db.release()
+ * }
+ * ```
+ */
+declare function runBackfill(options: BackfillOptions): Promise<BackfillResult>;
+
+/**
+ * Intent for a single column within the manifest. Expresses *what the user
+ * wants the state of this column to be*, not the observed reality — the
+ * `status` / `plan` commands diff this against `cs_migrations` and EQL to
+ * surface drift.
+ */
+declare const ManifestColumnSchema: z.ZodObject<{
+    /** Physical column name, e.g. `email`. */
+    column: z.ZodString;
+    /**
+     * EQL cast type. Text by default. See the EQL docs for the full list
+     * (`text | int | small_int | big_int | real | double | boolean | date |
+     * jsonb | json | float | decimal | timestamp`).
+     */
+    castAs: z.ZodDefault<z.ZodEnum<["text", "int", "small_int", "big_int", "real", "double", "boolean", "date", "jsonb", "json", "float", "decimal", "timestamp"]>>;
+    /** Desired EQL index set. Driver of the `indexes: {…}` block in EQL config. */
+    indexes: z.ZodDefault<z.ZodArray<z.ZodEnum<["unique", "match", "ore", "ste_vec"]>, "many">>;
+    /**
+     * The phase the user wants this column to reach. `cut-over` is the
+     * typical end state (reads transparently decrypted); advance to
+     * `dropped` only once you're confident the plaintext column is no
+     * longer needed.
+     */
+    targetPhase: z.ZodDefault<z.ZodEnum<["schema-added", "dual-writing", "backfilled", "cut-over", "dropped"]>>;
+    /**
+     * Override for primary-key detection during backfill. Omit to let the
+     * CLI auto-detect via `information_schema`.
+     */
+    pkColumn: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    column: string;
+    castAs: "boolean" | "text" | "int" | "small_int" | "big_int" | "real" | "double" | "date" | "jsonb" | "json" | "float" | "decimal" | "timestamp";
+    indexes: ("unique" | "match" | "ore" | "ste_vec")[];
+    targetPhase: "backfilled" | "dropped" | "schema-added" | "dual-writing" | "cut-over";
+    pkColumn?: string | undefined;
+}, {
+    column: string;
+    pkColumn?: string | undefined;
+    castAs?: "boolean" | "text" | "int" | "small_int" | "big_int" | "real" | "double" | "date" | "jsonb" | "json" | "float" | "decimal" | "timestamp" | undefined;
+    indexes?: ("unique" | "match" | "ore" | "ste_vec")[] | undefined;
+    targetPhase?: "backfilled" | "dropped" | "schema-added" | "dual-writing" | "cut-over" | undefined;
+}>;
+/**
+ * Root manifest shape. Stored at `.cipherstash/migrations.json`. Versioned
+ * (currently `1`) so we can evolve it without breaking existing manifests.
+ */
+declare const ManifestSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodLiteral<1>>;
+    /** Map of table name → array of column intents for that table. */
+    tables: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
+        /** Physical column name, e.g. `email`. */
+        column: z.ZodString;
+        /**
+         * EQL cast type. Text by default. See the EQL docs for the full list
+         * (`text | int | small_int | big_int | real | double | boolean | date |
+         * jsonb | json | float | decimal | timestamp`).
+         */
+        castAs: z.ZodDefault<z.ZodEnum<["text", "int", "small_int", "big_int", "real", "double", "boolean", "date", "jsonb", "json", "float", "decimal", "timestamp"]>>;
+        /** Desired EQL index set. Driver of the `indexes: {…}` block in EQL config. */
+        indexes: z.ZodDefault<z.ZodArray<z.ZodEnum<["unique", "match", "ore", "ste_vec"]>, "many">>;
+        /**
+         * The phase the user wants this column to reach. `cut-over` is the
+         * typical end state (reads transparently decrypted); advance to
+         * `dropped` only once you're confident the plaintext column is no
+         * longer needed.
+         */
+        targetPhase: z.ZodDefault<z.ZodEnum<["schema-added", "dual-writing", "backfilled", "cut-over", "dropped"]>>;
+        /**
+         * Override for primary-key detection during backfill. Omit to let the
+         * CLI auto-detect via `information_schema`.
+         */
+        pkColumn: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        column: string;
+        castAs: "boolean" | "text" | "int" | "small_int" | "big_int" | "real" | "double" | "date" | "jsonb" | "json" | "float" | "decimal" | "timestamp";
+        indexes: ("unique" | "match" | "ore" | "ste_vec")[];
+        targetPhase: "backfilled" | "dropped" | "schema-added" | "dual-writing" | "cut-over";
+        pkColumn?: string | undefined;
+    }, {
+        column: string;
+        pkColumn?: string | undefined;
+        castAs?: "boolean" | "text" | "int" | "small_int" | "big_int" | "real" | "double" | "date" | "jsonb" | "json" | "float" | "decimal" | "timestamp" | undefined;
+        indexes?: ("unique" | "match" | "ore" | "ste_vec")[] | undefined;
+        targetPhase?: "backfilled" | "dropped" | "schema-added" | "dual-writing" | "cut-over" | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    tables: Record<string, {
+        column: string;
+        castAs: "boolean" | "text" | "int" | "small_int" | "big_int" | "real" | "double" | "date" | "jsonb" | "json" | "float" | "decimal" | "timestamp";
+        indexes: ("unique" | "match" | "ore" | "ste_vec")[];
+        targetPhase: "backfilled" | "dropped" | "schema-added" | "dual-writing" | "cut-over";
+        pkColumn?: string | undefined;
+    }[]>;
+}, {
+    tables: Record<string, {
+        column: string;
+        pkColumn?: string | undefined;
+        castAs?: "boolean" | "text" | "int" | "small_int" | "big_int" | "real" | "double" | "date" | "jsonb" | "json" | "float" | "decimal" | "timestamp" | undefined;
+        indexes?: ("unique" | "match" | "ore" | "ste_vec")[] | undefined;
+        targetPhase?: "backfilled" | "dropped" | "schema-added" | "dual-writing" | "cut-over" | undefined;
+    }[]>;
+    version?: 1 | undefined;
+}>;
+type Manifest = z.infer<typeof ManifestSchema>;
+type ManifestColumn = z.infer<typeof ManifestColumnSchema>;
+/** Canonical on-disk location for the manifest. */
+declare function manifestPath(cwd?: string): string;
+/**
+ * Read and validate the manifest. Returns `null` when no manifest file
+ * exists (this is not an error — most commands still work without one;
+ * they just can't show intent-vs-observed drift).
+ *
+ * Throws on schema validation failures (zod errors).
+ */
+declare function readManifest(cwd?: string): Promise<Manifest | null>;
+/**
+ * Validate and write the manifest to `.cipherstash/migrations.json`,
+ * creating the directory if it doesn't exist. Rewrites the file
+ * atomically-enough for config purposes; not safe under concurrent writers.
+ */
+declare function writeManifest(manifest: Manifest, cwd?: string): Promise<void>;
+/**
+ * Read the manifest, upsert a single column entry under the named table,
+ * and write it back. If no manifest exists, creates one. If the column
+ * already exists for the table, the existing entry is replaced with the
+ * supplied values — useful for keeping the intent in lockstep with what
+ * the lifecycle commands actually committed.
+ *
+ * Called by `stash encrypt backfill` on first run for a column so the
+ * intent leg of the three-source state model exists in the repo. The
+ * agent (or the user) is free to hand-edit the file later — re-running
+ * `backfill` won't clobber a column the user has annotated, only the
+ * fields this function controls.
+ */
+declare function upsertManifestColumn(table: string, column: ManifestColumn, cwd?: string): Promise<void>;
+/**
+ * Update just the `targetPhase` of an existing column entry. No-op if
+ * the column isn't tracked yet — used by `stash encrypt drop` to bump
+ * the intent forward when the user commits to removing the plaintext
+ * column entirely.
+ */
+declare function setManifestTargetPhase(table: string, columnName: string, targetPhase: ManifestColumn['targetPhase'], cwd?: string): Promise<void>;
+
+export { type BackfillOptions, type BackfillProgress, type BackfillResult, type ColumnKey, type KeysetPage, type KeysetPageOptions, MIGRATIONS_SCHEMA_SQL, type Manifest, type ManifestColumn, type MigrationEvent, type MigrationPhase, type MigrationStateRow, activateConfig, appendEvent, countEncryptedWithActiveConfig, countUnencrypted, discardPendingConfig, fetchUnencryptedPage, installMigrationsSchema, latestByColumn, manifestPath, migrateConfig, progress, qualifyTable, quoteIdent, readManifest, readyForEncryption, reloadConfig, renameEncryptedColumns, runBackfill, selectPendingColumns, setManifestTargetPhase, upsertManifestColumn, writeManifest };