import { type ResultFailure } from "./result.js";
import type { FuncParam } from "./agencyFunction.js";
/** Runtime mode for the failure-propagation feature. "on": skip/throw.
 *  "warn": warnings only, legacy behavior otherwise. "off": no checks. */
export type FailurePropagationMode = "off" | "warn" | "on";
/** Resolve the active mode. Two defaults exist ON PURPOSE and only the
 *  other one flips at Stage 2: real compiled programs read the mode off
 *  their ExecutionContext (whose constructor default is the staged
 *  rollout value — "warn" in Stage 1); the `?? "on"` here applies only
 *  OUTSIDE an execution frame, i.e. bare unit tests and direct runtime
 *  callers, which have no config to honor and no corpus at risk, so they
 *  always get the strict rule. Do not change this fallback when flipping
 *  the rollout default. */
export declare function getFailurePropagationMode(): FailurePropagationMode;
/** Tag a plain TypeScript function as legitimately receiving failure
 *  values, exempting it from the dispatcher's failure-argument check. */
export declare function acceptsFailures<T extends (...args: any[]) => any>(fn: T): T;
export declare function isFailureTolerant(fn: unknown): boolean;
/**
 * SINGLE SOURCE OF TRUTH for runtime-layer builtins that legitimately
 * receive failure values. Add new entries HERE, never as scattered
 * acceptsFailures() calls.
 *
 * Every entry must be on the compiler's DIRECT_CALL_FUNCTIONS list
 * (lib/backends/typescriptBuilder/nameClassifier.ts) — by-name calls to
 * those bypass the dispatcher entirely, so this list only matters for
 * ALIASED use (`const f = isFailure; f(x)`). A tripwire test in
 * failurePropagation.test.ts enforces that membership, so the two lists
 * cannot drift silently.
 *
 * Two deliberate non-members:
 * - stdlib TS helpers (`_print`, `_printJSON`) have their own list in
 *   lib/stdlib/builtins.ts, because the runtime hot path must not import
 *   the stdlib graph.
 * - JSON.stringify is tolerated by IDENTITY inside isFailureTolerant; it
 *   is a native, not an Agency builtin.
 */
export declare const FAILURE_TOLERANT_BUILTINS: ReadonlyArray<(...args: any[]) => any>;
/**
 * Scan resolved call arguments for failures landing on params that do not
 * accept Results. `args` is aligned index-for-index with `params` (invoke
 * passes the merged, resolved list; the variadic slot holds the gathered
 * array). Returns the failure to propagate, or null to proceed with the
 * call. Only `acceptsResult === false` rejects — absent means a legacy or
 * handcrafted param, which fails open.
 */
export declare function checkFailureArgs(fnName: string, params: FuncParam[], args: unknown[]): ResultFailure | null;
/**
 * A failure passed to a plain TypeScript function is always a mistake
 * unless the function is tagged. Throws a plain Error (NEVER AgencyAbort —
 * the enclosing auto-try must convert it into a catchable failure).
 */
export declare function checkTsFunctionArgs(target: (...args: unknown[]) => unknown, fnName: string, args: unknown[]): void;
/**
 * A method call on a Result throws, unless the property is an own field
 * holding a callable (`r.value()` when the success wraps a function or
 * AgencyFunction). Prototype methods like .toString() throw too. Plain
 * Error only — see checkTsFunctionArgs.
 */
export declare function checkResultMethodCall(obj: unknown, prop: string | number): void;
/** Message for `__call` when the call TARGET itself is a failure value.
 *  Deliberately NOT mode-gated: this path already threw ("Cannot call
 *  non-function value") before this feature, so enriching the message is
 *  not a behavior change and warn mode's legacy-behavior promise holds. */
export declare function describeFailureCallTarget(f: ResultFailure): string;