import type { KV } from "@nats-io/kv";
/** One journal entry the new source no longer reaches, as the record keeps it. */
export interface MigrationOrphanValue {
    readonly step: string;
    readonly kind: string;
    readonly verdict: "ignored" | "kept" | "rejected";
    readonly code?: string;
}
export interface RunMigrationSpecValue {
    readonly v: 1;
    readonly run: string;
    /**
     * The program hash the run was on, as the CALLER states it.
     *
     * Optional, and the reason is a gap rather than a preference: a program-hash pin on the run
     * record is declared and unbuilt, and `RunSpecValue` deliberately never invented one, so nothing
     * here can VERIFY this. Recorded as the caller's claim when supplied and absent when not — an
     * unverifiable field labelled as such beats one this file computes from a source it was never
     * given.
     */
    readonly fromHash?: string;
    /** The hash of the source the run is moving TO. Computed from that source, so not a claim. */
    readonly toHash: string;
    readonly at: number;
    /** How many recorded entries the walk accounted for. */
    readonly consumedThrough: number;
    readonly orphans: readonly MigrationOrphanValue[];
    /** What the caller overrode, verbatim, because an override is a person's decision. */
    readonly overrides: readonly string[];
    readonly actor: string;
}
export interface RunMigrationStatusValue {
    readonly v: 1;
    /** When the run actually advanced. */
    readonly appliedAt: number;
    /** WHICH driver advanced it, so an application can be traced to the holder that made it. */
    readonly by: string;
    readonly observedSpecRevision: number;
}
/**
 * The id one migration is filed under: a digest of the report itself.
 *
 * Everything the decision consists of goes in, so a re-run of the same check over the same journal
 * re-derives the same id and its create-only write lands on its own record. Change what was found
 * or what was overridden and it is a different migration, which is exactly right — it is.
 */
export declare function runMigrationId(value: Omit<RunMigrationSpecValue, "at">): string;
/**
 * File one migration's report, create-only.
 *
 * An identical retry is this attempt's own earlier write and is not a conflict. Differing content
 * under one id would mean two decisions claiming one identity, which is refused rather than
 * overwritten: a migration that could be rewritten would be a draft, and what it records is what a
 * person authorised to discard.
 */
export declare function writeRunMigration(kv: KV, endpoint: string, migrationId: string, value: RunMigrationSpecValue): Promise<{
    key: string;
    created: boolean;
}>;
export interface RunMigrationRead {
    readonly migrationId: string;
    readonly spec: RunMigrationSpecValue;
    readonly specRevision: number;
    readonly applied?: RunMigrationStatusValue;
}
/** Read one migration with its application, or `undefined` when nothing was filed under this id. */
export declare function readRunMigration(kv: KV, endpoint: string, runId: string, migrationId: string): Promise<RunMigrationRead | undefined>;
/**
 * Every migration filed on one run, oldest first.
 *
 * ORDER IS THE POINT of an append-only history: a run's second migration is only interpretable
 * beside its first. `at` decides, then the id, so two filed in the same millisecond still come back
 * in one fixed order rather than in whatever order the store enumerated its keys.
 */
export declare function listRunMigrations(kv: KV, endpoint: string, runId: string): Promise<RunMigrationRead[]>;
/**
 * Record that a driver applied this migration.
 *
 * **The create-only CAS is the arbiter and it is the only one.** Two drivers racing to apply one
 * migration both read no status and both write; the store decides, and the loser gets a loud
 * conflict rather than a second belief about a run that moved once. A "has it been applied?" read
 * before the write would be a fast path that lies under exactly the race it looks like it prevents.
 */
export declare function markRunMigrationApplied(kv: KV, endpoint: string, runId: string, migrationId: string, by: string, at: number): Promise<void>;
//# sourceMappingURL=run-migration.d.ts.map