/**
 * @packageDocumentation
 * Structured error handling for best-effort typed AST operations.
 */
/**
 * Counter contract used by test-time debug instrumentation.
 */
export type SafeTypeOperationCounter<Reason extends string> = Readonly<{
    getSnapshot: () => ReadonlyMap<Reason, number>;
    onFailure: (failure: Readonly<{
        error: unknown;
        reason: Reason;
    }>) => void;
}>;
/**
 * Failure payload emitted when a safe typed operation throws.
 */
export type SafeTypeOperationFailure<Reason extends string> = Readonly<{
    error: unknown;
    reason: Reason;
}>;
/**
 * Optional observer called whenever an operation fails.
 */
export type SafeTypeOperationFailureObserver<Reason extends string> = (failure: Readonly<SafeTypeOperationFailure<Reason>>) => void;
/**
 * Failure payload emitted when an observer itself throws.
 */
export type SafeTypeOperationObserverFailure<Reason extends string> = Readonly<{
    failure: Readonly<SafeTypeOperationFailure<Reason>>;
    observerError: unknown;
    observerKind: "global" | "local";
}>;
/**
 * Optional observer called when an operation failure observer throws.
 */
export type SafeTypeOperationObserverFailureObserver<Reason extends string> = (failure: Readonly<SafeTypeOperationObserverFailure<Reason>>) => void;
/**
 * Register a process-local observer for observer failures.
 *
 * @param observer - Callback invoked when a local/global failure observer
 *   throws.
 *
 * @returns Unsubscribe callback to remove the observer.
 */
export declare const registerSafeTypeOperationObserverFailureObserver: (observer: SafeTypeOperationObserverFailureObserver<string>) => (() => void);
/**
 * Register a process-local failure observer for typed operations.
 *
 * @param observer - Callback invoked for each operation failure.
 *
 * @returns Unsubscribe callback to remove the observer.
 */
export declare const registerSafeTypeOperationFailureObserver: (observer: SafeTypeOperationFailureObserver<string>) => (() => void);
/**
 * Run one operation with a scoped failure observer that is always cleaned up.
 *
 * @param observer - Observer registered for the operation scope.
 * @param operation - Synchronous operation to execute while observing failures.
 *
 * @returns Return value produced by `operation`.
 */
export declare const withSafeTypeOperationFailureObserver: <Result>(observer: SafeTypeOperationFailureObserver<string>, operation: () => Result) => Result;
/**
 * Result shape for safe typed operations.
 */
export type SafeTypeOperationResult<Result, Reason extends string> = Readonly<{
    failure: SafeTypeOperationFailure<Reason>;
    ok: false;
}> | Readonly<{
    ok: true;
    value: Result;
}>;
/**
 * Execute a typed operation with structured failure output instead of throws.
 */
export declare const safeTypeOperation: <Result, Reason extends string>({ onFailure, operation, reason, }: Readonly<{
    onFailure?: SafeTypeOperationFailureObserver<Reason>;
    operation: () => Result;
    reason: Reason;
}>) => SafeTypeOperationResult<Result, Reason>;
/**
 * Build a lightweight reason counter for debugging operation failures in tests.
 *
 * @param reasonsForTypeInference - Optional typed reason literals used to infer
 *   the `Reason` generic without requiring explicit type parameters.
 */
export declare const createSafeTypeOperationCounter: <Reason extends string = never>(reasonsForTypeInference?: readonly Reason[]) => SafeTypeOperationCounter<Reason>;
//# sourceMappingURL=safe-type-operation.d.ts.map