/**
 * Persistent per-(source, target) record of which upsert key each object
 * used, stored beside the project id-map at
 * `~/.sandbox-seed/id-maps/<source>__<target>.upsert-keys.json`.
 *
 * Why: the population-based auto-pick is deterministic for a given scope
 * (alphabetical tie-break), but two SESSIONS with different scopes — or
 * the same scope after source data drifts — can legitimately pick
 * different keys. A re-seed that matches on a different external-id than
 * the run that created the rows can stop matching them. Persisting the
 * pick makes re-seeds match on the SAME key until the user overrides it
 * (overrides always win and update the stored pick).
 *
 * Contents are object → field NAMES only — schema metadata, no values,
 * no record IDs. The store is consulted at dry-run (where the decision
 * is made and surfaced in the report) and written after a run completes.
 * Stored picks are re-validated against both describes on every read, so
 * schema drift degrades to a fresh auto-pick, never a broken upsert.
 */
export type UpsertKeyStoreOptions = {
    sourceAlias: string;
    targetAlias: string;
    /** Defaults to `~/.sandbox-seed`. Overridable for tests. */
    rootDir?: string;
};
export declare function upsertKeysPath(opts: UpsertKeyStoreOptions): string;
/** Load the stored picks. Missing or corrupt file ⇒ empty map, never throws. */
export declare function loadUpsertKeys(opts: UpsertKeyStoreOptions): Promise<Record<string, string>>;
/**
 * Merge `entries` over the stored picks (last write wins per object) and
 * persist. Best-effort by design — callers treat failures as non-fatal,
 * the same stance the project id-map merge-back takes.
 */
export declare function saveUpsertKeys(opts: UpsertKeyStoreOptions, entries: Record<string, string>): Promise<void>;