/**
 * Copyright (c) 2025 Elara AI Pty Ltd
 * Licensed under BSL 1.1. See LICENSE for details.
 */
/**
 * Get the filesystem path for an object.
 *
 * @param repoPath - Path to e3 repository
 * @param hash - SHA256 hash of the object
 * @returns Filesystem path: objects/<hash[0..2]>/<hash[2..]>.beast2
 */
export declare function objectPath(repoPath: string, hash: string): string;
/**
 * Get the minimum unambiguous prefix length for an object hash.
 *
 * Scans the object store to find the shortest prefix of the given hash
 * that uniquely identifies it among all stored objects.
 *
 * @param repoPath - Path to e3 repository
 * @param hash - Full SHA256 hash of the object
 * @param minLength - Minimum prefix length to return (default: 4)
 * @returns Minimum unambiguous prefix length
 */
export declare function objectAbbrev(repoPath: string, hash: string, minLength?: number): Promise<number>;
/**
 * Errno codes Windows raises when an operation targets a path another handle has
 * open (a sharing violation), or when a just-deleted name briefly resists
 * re-creation. POSIX never raises these on rename-over-existing, so retrying is a
 * no-op there.
 *
 * The single source of truth for the transient-error policy, shared by every
 * local atomic write/rename ({@link renameWithRetry}), the dataset-ref
 * compare-and-swap, the lock service, and the dataflow state store — so the set
 * can never drift between copies (it historically had two divergent definitions).
 */
export declare const TRANSIENT_FS_ERROR_CODES: Set<string>;
/**
 * Whether a thrown error is a transient filesystem sharing-violation worth
 * retrying (or, where a retry budget is already spent, treating as a benign
 * conflict rather than a hard failure). See {@link TRANSIENT_FS_ERROR_CODES}.
 *
 * @param err - The value thrown by an `fs` operation.
 * @returns `true` if the error carries a transient errno code.
 */
export declare function isTransientFsError(err: unknown): boolean;
/**
 * Rename `from` over `to`, retrying on Windows sharing-violation errors.
 *
 * POSIX rename-over-existing is atomic even while another process holds the
 * destination open for read, so the first attempt always succeeds there.
 * Windows refuses the rename (EPERM/EACCES/EBUSY) while a reader holds the
 * destination open — Node/libuv never opens files with FILE_SHARE_DELETE and
 * exposes no way to set the share mode — so, like graceful-fs / npm, we retry
 * with a bounded exponential backoff. A realistic reader holds the handle only
 * for the brief duration of its read, so the lock clears almost immediately
 * (usually the first or second attempt); the attempt count is generous so that
 * even bursty concurrent reads on a loaded Windows host clear well before the
 * bound, while a genuine permission error still surfaces promptly. A no-op on
 * POSIX, where the first attempt always succeeds.
 *
 * @param from - Staging path to rename from
 * @param to - Destination path to atomically replace
 * @param maxAttempts - Upper bound on retries (≈1.9s total over the default 25)
 */
export declare function renameWithRetry(from: string, to: string, maxAttempts?: number): Promise<void>;
/**
 * Atomically (over)write a file: stage the bytes in a unique sibling
 * `.partial` file, then rename it over the destination.
 *
 * A bare `fs.writeFile` to an existing path opens it `O_TRUNC` — the file is
 * momentarily 0 bytes, so a concurrent reader can observe an empty/truncated
 * file and fail to decode it (e.g. "Data too short for Beast2 format: 0 bytes").
 * The stage-and-rename makes the replacement atomic: a reader sees either the
 * old complete file or the new complete file, never a partial one. Use this for
 * every mutable ref/state file a reader may read while a writer overwrites it
 * (execution status, dataflow runs, workspace state, dataset refs).
 *
 * Staging files use a `.partial` extension so the directory-listing helpers
 * (which filter `.partial`) never mistake them for real entries, and orphaned
 * stages from a crashed writer are swept by `gc` (see cleanupPartials).
 *
 * @param filePath - Destination path to atomically (over)write
 * @param data - Bytes (or string) to write
 */
export declare function atomicWriteFile(filePath: string, data: Uint8Array | string): Promise<void>;
//# sourceMappingURL=localHelpers.d.ts.map