/**
 * Idempotent startup upgrades for the shell application.
 *
 * On boot the shell may need to perform one-time housekeeping: create a missing
 * directory, move a file to a new location, rewrite a stale config shape. Each
 * such chore is an {@link Upgrade} — a small object with a stable, human-chosen
 * `id` and an `apply` step. The set is *keyed by id rather than by a sequential
 * version number*: an upgrade runs at most once across the lifetime of an
 * install, and adding, reordering, or removing entries never disturbs which
 * other upgrades are considered "done".
 *
 * {@link applyUpgrades} reads a tiny marker file listing the ids that have
 * already run, applies only the rest in declaration order, records each success,
 * and returns the ids it applied this pass. Re-running it is a no-op once every
 * upgrade is recorded, which is what makes startup cheap and safe to repeat.
 *
 * Failures are contained: if one upgrade throws, the ids that already succeeded
 * this pass are still persisted, and the error propagates so the boot layer can
 * decide how loud to be. The marker file itself is read forgivingly — a missing
 * or corrupt marker is treated as "nothing has run yet".
 */
import type { Locator } from "../config/locator";
/**
 * One idempotent boot-time chore.
 *
 * `id` is the identity used to remember whether this upgrade has run; it must be
 * stable forever once shipped (renaming an id re-runs the upgrade). `description`
 * is for logs and humans only. `apply` performs the work and must itself be safe
 * to run on an already-upgraded install, since the marker file could be lost.
 */
export interface Upgrade {
    /** Stable, unique identity used to record completion. Never renamed. */
    readonly id: string;
    /** Human-readable summary of what the upgrade does. */
    readonly description: string;
    /** Perform the upgrade. Should tolerate already-applied state. */
    apply(locator: Locator): Promise<void>;
}
/**
 * The ordered set of upgrades this build knows about.
 *
 * Order matters only for upgrades within a single boot that have not yet run;
 * completion is tracked per-id, so inserting a new upgrade anywhere is safe.
 *
 * Seeded with two trivial, self-evidently-idempotent examples:
 *   - `ensure-profile-dir`  — guarantee the per-user profile directory exists.
 *   - `ensure-sessions-dir` — guarantee the sessions subdirectory exists.
 */
export declare const UPGRADES: readonly Upgrade[];
/**
 * Run every upgrade that has not yet been applied, in declaration order.
 *
 * Reads the marker, applies each {@link UPGRADES} entry whose id is absent,
 * records each success immediately into the in-memory set, and flushes the
 * marker once at the end. Returns the ids applied during *this* call (empty when
 * the install is already fully upgraded).
 *
 * If an upgrade throws, the marker is still flushed with whatever succeeded
 * before the failure, then the error is re-thrown — so a retry will skip the
 * work already done.
 */
export declare function applyUpgrades(locator: Locator): Promise<string[]>;
