/**
 * SafeFsExecutor — the single funnel for destructive filesystem invocations.
 *
 * Parallel structure to SafeGitExecutor. Wraps `fs.rm`, `fs.rmSync`,
 * `fs.unlink`, `fs.unlinkSync`, `fs.rmdir`, `fs.rmdirSync` (and their
 * promises-API counterparts). Each wrapper:
 *
 *   1. Canonicalizes `target` via `realpathSync` (or nearest-existing-ancestor
 *      if the target itself doesn't exist — `assertNotInstarSourceTree`
 *      handles this internally).
 *   2. Calls `assertNotInstarSourceTree(target, operation)`. On failure,
 *      throws SourceTreeGuardError BEFORE touching disk.
 *   3. Performs the actual fs operation.
 *   4. Appends a JSON line to .instar/audit/destructive-ops.jsonl.
 *
 * See docs/specs/COMPREHENSIVE-DESTRUCTIVE-TOOL-CONTAINMENT-SPEC.md.
 */
import fs from 'node:fs';
import { SourceTreeGuardError } from './SourceTreeGuard.js';
export interface SafeFsOptions {
    /** Caller label for error messages and audit log. */
    operation: string;
}
export type SafeRmOptions = fs.RmOptions & SafeFsOptions;
export type SafeRmDirOptions = fs.RmDirOptions & SafeFsOptions;
export declare class SafeFsExecutor {
    /**
     * Recursive force-deletes default to fs.rm's native transient-error retry
     * (ENOTEMPTY/EBUSY/EPERM). A recursive tree delete racing a concurrent
     * writer (git finishing an object write, an mtime scanner walking the
     * tree) fails ENOTEMPTY exactly once and succeeds milliseconds later —
     * fs.rm retries this class natively, but only when maxRetries is set.
     * Live: CI shard failure 2026-06-05 in handoff-manager.test.ts cleanup
     * (`ENOTEMPTY: directory not empty, rmdir '/tmp/handoff-…/.git'`) on a
     * loaded runner — a whole-class flake every tmpdir-cleanup test inherits.
     * Explicit caller-set values always win; non-recursive deletes unchanged.
     */
    private static withRmRetryDefaults;
    /** Async fs.promises.rm wrapper. */
    static safeRm(target: string, opts: SafeRmOptions): Promise<void>;
    /** Sync fs.rmSync wrapper. */
    static safeRmSync(target: string, opts: SafeRmOptions): void;
    /** Async fs.promises.unlink wrapper. */
    static safeUnlink(target: string, opts: SafeFsOptions): Promise<void>;
    /** Sync fs.unlinkSync wrapper. */
    static safeUnlinkSync(target: string, opts: SafeFsOptions): void;
    /** Async fs.promises.rmdir wrapper. */
    static safeRmdir(target: string, opts: SafeRmDirOptions): Promise<void>;
    /** Sync fs.rmdirSync wrapper. */
    static safeRmdirSync(target: string, opts: SafeRmDirOptions): void;
    /**
     * Atomically write a string to `target`. Writes to a temp sibling, fsyncs,
     * then renames over the target. Creates parent directories if missing.
     */
    static atomicWriteFileSync(target: string, data: string | Uint8Array, opts?: {
        operation?: string;
        mode?: number;
    }): void;
    /**
     * Atomically write `value` as pretty-printed JSON to `target`.
     * Convenience wrapper around atomicWriteFileSync — the common case for
     * Instar's `.instar/state/*.json` files.
     */
    static atomicWriteJsonSync(target: string, value: unknown, opts?: {
        operation?: string;
        mode?: number;
        indent?: number;
    }): void;
}
export { SourceTreeGuardError };
//# sourceMappingURL=SafeFsExecutor.d.ts.map