import { chmod, type FileHandle } from 'node:fs/promises';
export interface FileIdentity {
    device: bigint;
    inode: bigint;
}
export interface RegularFileSnapshot {
    content: string;
    mode: number;
    identity: FileIdentity;
}
export interface FileExpectation {
    expected: RegularFileSnapshot | undefined;
    /** Paths whose absence is part of the same decision (for example an alternate config path). */
    mustRemainAbsent?: readonly string[];
    /** Reject every symbolic-link component below this already-resolved root. */
    containmentRoot?: string;
    /** When present, the parent must preexist and retain this exact directory identity. */
    expectedParentDirectory?: FileIdentity;
}
export declare class AtomicCleanupFailure extends Error {
    /** Exact pathname of the owned artifact, when its full binding was proven after the failure. */
    readonly artifactPath: string | undefined;
    constructor(
    /** Exact pathname of the owned artifact, when its full binding was proven after the failure. */
    artifactPath: string | undefined, options: {
        cause: unknown;
    });
}
export interface AtomicWriteResult {
    installed: RegularFileSnapshot;
    cleanupFailures: readonly AtomicCleanupFailure[];
}
export interface AtomicUnlinkResult {
    cleanupFailures: readonly AtomicCleanupFailure[];
}
export declare class AtomicCommittedMutationError extends AggregateError {
    readonly outcome: AtomicWriteResult;
    readonly operationError: unknown;
    constructor(outcome: AtomicWriteResult, operationError: unknown);
}
export declare class AtomicCommittedUnlinkError extends AggregateError {
    readonly outcome: AtomicUnlinkResult;
    readonly operationError: unknown;
    constructor(outcome: AtomicUnlinkResult, operationError: unknown);
}
export declare function assertAtomicCleanupComplete(result: Pick<AtomicWriteResult | AtomicUnlinkResult, 'cleanupFailures'>): void;
export interface AtomicWriteDependencies {
    chmod?: typeof chmod;
    beforeLink?: (source: string, destination: string) => void | Promise<void>;
    afterLink?: (source: string, destination: string) => void | Promise<void>;
    beforeRename?: (source: string, destination: string) => void | Promise<void>;
    afterRename?: (source: string, destination: string) => void | Promise<void>;
    beforeCleanup?: (artifactPath: string) => void | Promise<void>;
    beforeCommit?: (filePath: string) => void | Promise<void>;
    afterQuarantine?: (filePath: string) => void | Promise<void>;
    afterInstall?: (filePath: string) => void | Promise<void>;
}
export interface ReadRegularFileDependencies {
    /** Test seam for proving that reads remain bound to the opened descriptor. */
    afterOpen?: (filePath: string, handle: FileHandle) => void | Promise<void>;
    /** Test seam for preserving an operation failure when descriptor close also fails. */
    closeHandle?: (handle: FileHandle) => Promise<void>;
    /** Test seam for exercising the Windows no-O_NOFOLLOW strategy on any host. */
    platform?: NodeJS.Platform;
}
export interface ConditionalUnlinkDependencies {
    beforeRename?: (source: string, destination: string) => void | Promise<void>;
    afterRename?: (source: string, destination: string) => void | Promise<void>;
    beforeCleanup?: (artifactPath: string) => void | Promise<void>;
    beforeCommit?: (filePath: string) => void | Promise<void>;
}
export declare function readRegularFile(filePath: string, dependencies?: ReadRegularFileDependencies & {
    containmentRoot?: string;
}): Promise<RegularFileSnapshot | undefined>;
/** Read an exact directory identity without following its final path component. */
export declare function readDirectoryIdentity(directoryPath: string): Promise<FileIdentity | undefined>;
export interface PendingAtomicMutation {
    kind: 'deleted' | 'previous' | 'rollback';
    snapshot: RegularFileSnapshot;
}
/**
 * Bind a native atomic-write quarantine for this exact basename without
 * following path components. Its snapshot may constrain convergence, but it
 * never grants the caller ownership of the artifact.
 */
export declare function readPendingAtomicMutation(filePath: string, expectedParentDirectory: FileIdentity, containmentRoot?: string): Promise<PendingAtomicMutation | undefined>;
export declare function assertFileExpectation(filePath: string, expectation: FileExpectation): Promise<void>;
export declare function atomicWriteText(filePath: string, content: string, mode?: number, dependencyOverrides?: AtomicWriteDependencies): Promise<AtomicWriteResult>;
/** Write only when the target is still the exact file observed at planning time. */
export declare function atomicWriteTextIfUnchanged(filePath: string, content: string, expectation: FileExpectation, mode?: number, dependencyOverrides?: AtomicWriteDependencies): Promise<AtomicWriteResult>;
/** Delete only when the target is still the exact planned file identity and content. */
export declare function unlinkRegularFileIfUnchanged(filePath: string, expectation: FileExpectation, dependencyOverrides?: ConditionalUnlinkDependencies): Promise<AtomicUnlinkResult>;
//# sourceMappingURL=atomic-write.d.ts.map