/**
 * CLI-facing wrapper around the generic {@link recoverMalformedDb} pipeline
 * (T10318 SG-BRAIN-DB-RESILIENCE E3-BACKUP-RECOVERY).
 *
 * Exposes the recovery pipeline to the `cleo backup recover <role>` verb
 * with three additions that don't belong in the chokepoint module:
 *
 *  1. **Dry-run planning** — enumerates snapshot candidates, validates the
 *     freshest one via `PRAGMA quick_check`, and returns the envelope WITHOUT
 *     quarantining or copying anything. Operators use this to preview the
 *     freshness window before pulling the trigger.
 *  2. **Per-table row counts** — probes user tables post-restore via
 *     `sqlite_master` enumeration so the runbook surfaces the recovered
 *     scope for any role (not just brain's three tables).
 *  3. **Snapshot pinning** — accepts `fromSnapshot` (absolute path or ISO
 *     prefix) so operators can roll back to a specific snapshot when the
 *     freshest is also poisoned.
 *
 * The pipeline itself is NEVER re-implemented here — every code path
 * delegates to {@link recoverMalformedDb} or to the shared candidate-
 * enumeration / probe helpers re-exported from
 * {@link ./recover-malformed-db.js}.
 *
 * @task T10318
 * @epic T10284
 * @saga T10281
 */
import type { BackupRecoverResult, DbRole } from '@cleocode/contracts';
import { type RecoveryLogger } from './recover-malformed-db.js';
/**
 * Options accepted by {@link runBackupRecover}.
 *
 * @task T10318
 * @public
 */
export interface BackupRecoverOptions {
    /** Canonical role to recover. Must exist in `DB_INVENTORY`. */
    role: DbRole;
    /**
     * Absolute path to the corrupt DB file. When omitted, derived from the
     * inventory entry with `<projectRoot>` substitution.
     */
    corruptPath?: string;
    /**
     * Absolute path to the project root. Used to resolve inventory templates
     * for `project`-tier roles. Required when `corruptPath` is not supplied
     * for a project-tier role.
     */
    projectRoot?: string;
    /** Absolute path to `.cleo/backups/snapshot/` — overrides inventory-derived default. */
    snapshotDir?: string;
    /** Absolute path to `.cleo/backups/sqlite/` (VACUUM INTO snapshots) — overrides default. */
    vacuumSnapshotDir?: string;
    /** Absolute path to `.cleo/` for legacy `<role>.db.PRE-DUP-FIX-*` fallback — overrides default. */
    legacyArtifactDir?: string;
    /**
     * Absolute path to the quarantine root. Defaults to
     * `<dirname(corruptPath)>/quarantine` to match the chokepoint helper.
     */
    quarantineRoot?: string;
    /** Pino-shaped logger for the recovery announcement. */
    logger: RecoveryLogger;
    /**
     * When `true`, enumerate candidates + validate the freshest one and
     * return the planned envelope WITHOUT quarantining or copying.
     */
    dryRun?: boolean;
    /**
     * Optional snapshot pin — either an absolute path to a specific
     * snapshot file OR an ISO timestamp prefix (e.g. `2026-05-23`) that
     * resolves to the freshest validated snapshot whose timestamp begins
     * with that prefix. When unset, the freshest validated candidate wins.
     */
    fromSnapshot?: string;
    /**
     * When `true`, skip the future `sqlite3 .recover` delta-merge step.
     * Reserved for future extension — the current pipeline does not
     * perform delta-merge.
     */
    noDelta?: boolean;
}
/**
 * Error thrown when the recovery pre-conditions cannot be satisfied.
 *
 * @remarks
 * Distinct from runtime recovery failures (which are reported via the
 * envelope's `integrityOK: false` field) — these errors signal that the
 * CLI cannot even attempt recovery (no snapshots present at all,
 * `fromSnapshot` does not resolve, etc.).
 *
 * @task T10318
 * @public
 */
export declare class BackupRecoverError extends Error {
    /** Stable numeric exit code. */
    readonly code: number;
    /** Stable string error code for envelope `codeName`. */
    readonly codeName: string;
    /** Optional remediation hint surfaced to the operator. */
    readonly fix?: string;
    /**
     * @param message  - Human-readable error message.
     * @param code     - Numeric exit code for the CLI surface.
     * @param codeName - Stable error code (e.g. `'E_NO_SNAPSHOT'`).
     * @param fix      - Optional remediation hint.
     */
    constructor(message: string, code: number, codeName: string, fix?: string);
}
/**
 * Run the database recovery pipeline as an operator-facing one-shot.
 *
 * @remarks
 * In `dryRun` mode this returns the plan envelope (which snapshot would be
 * picked, where the corrupt DB would be quarantined) without mutating any
 * files on disk.
 *
 * In execute mode this delegates to {@link recoverMalformedDb} for the
 * actual quarantine + copy + integrity-check pipeline, then probes the
 * restored DB for per-table row counts to enrich the envelope.
 *
 * @param opts - Recovery inputs (role, corrupt path, snapshot dirs, mode flags).
 * @returns The recovery envelope (plan or post-mutation).
 * @throws {BackupRecoverError} When pre-conditions fail (no snapshots
 *         at all, `fromSnapshot` cannot be resolved, etc.).
 *
 * @example
 * ```typescript
 * import { runBackupRecover } from '@cleocode/core/store/backup-recover';
 * import { getLogger } from '@cleocode/core/logger';
 *
 * const result = runBackupRecover({
 *   role: 'brain',
 *   projectRoot: '/repo',
 *   logger: getLogger('backup-recover'),
 *   dryRun: true,
 * });
 * if (!result.integrityOK) {
 *   process.exitCode = 1;
 * }
 * ```
 *
 * @task T10318
 * @epic T10284
 * @saga T10281
 * @public
 */
export declare function runBackupRecover(opts: BackupRecoverOptions): BackupRecoverResult;
//# sourceMappingURL=backup-recover.d.ts.map