/**
 * Rill Error Classes and Factory
 * Structured error types with registry-based error codes
 */
import type { SourceLocation, SourceSpan } from './source-location.js';
/**
 * Call stack frame information for error reporting.
 * Represents a single frame in the call stack with location and context.
 */
export interface CallFrame {
    /** Source location of the call */
    readonly location: SourceSpan;
    /** Name of the function (closure or host function) */
    readonly functionName?: string | undefined;
    /** Additional context (e.g., "in each body") */
    readonly context?: string | undefined;
    /** Source identifier for cross-module call stacks (e.g. file path or "module:greetings") */
    readonly sourceId?: string | undefined;
}
/** Structured error data for host applications */
export interface RillErrorData {
    readonly errorId: string;
    readonly helpUrl?: string | undefined;
    readonly message: string;
    readonly location?: SourceLocation | undefined;
    readonly span?: SourceSpan | undefined;
    readonly context?: Record<string, unknown> | undefined;
    /** Identifies the source that produced this error (e.g. "module:greetings") */
    readonly sourceId?: string | undefined;
}
/**
 * Factory function for creating errors from registry.
 *
 * Looks up error definition from registry, renders message template with context,
 * and creates an instance of the class matching the error's category: a
 * `ParseError` for parse-category (and legacy syntax-parse) IDs, a
 * `RuntimeError` for runtime-category IDs, and a base `RillError` otherwise.
 *
 * @param errorId - Error identifier (format: RILL-{category}{3-digit})
 * @param context - Key-value pairs for template placeholder replacement
 * @param location - Source location where error occurred (optional)
 * @returns RillError instance (or a ParseError/RuntimeError subclass) with rendered message
 * @throws TypeError if errorId is not found in registry
 *
 * @example
 * createError("RILL-R005", { name: "foo" }, location)
 * // Creates RuntimeError: "Variable foo is not defined at 1:5"
 *
 * @example
 * createError("RILL-X999", {})
 * // Throws: TypeError("Unknown error ID: RILL-X999")
 */
export declare function createError(errorId: string, context: Record<string, unknown>, location?: SourceLocation | undefined): RillError;
/**
 * Base error class for all Rill errors.
 * Provides structured data for host applications to format as needed.
 */
export declare class RillError extends Error {
    readonly errorId: string;
    readonly helpUrl: string | undefined;
    readonly location?: SourceLocation | undefined;
    readonly span?: SourceSpan | undefined;
    readonly context?: Record<string, unknown> | undefined;
    readonly sourceId?: string | undefined;
    /** The message as constructed, before the " at {line}:{column}" location suffix is appended. */
    readonly rawMessage: string;
    constructor(data: RillErrorData);
    /** Get structured error data for custom formatting */
    toData(): RillErrorData;
    /** Format error for display (can be overridden by host) */
    format(formatter?: (data: RillErrorData) => string): string;
    /**
     * Return a new error instance of the same prototype with `patch` merged
     * into its context. Does not mutate `this`; the original context object
     * is not shared with the returned instance.
     */
    withContext(patch: Record<string, unknown>): RillError;
}
/** Parse-time errors */
export declare class ParseError extends RillError {
    constructor(errorId: string, message: string, location: SourceLocation, context?: Record<string, unknown>);
}
/** Runtime execution errors */
export declare class RuntimeError extends RillError {
    constructor(errorId: string, message: string, location?: SourceLocation, context?: Record<string, unknown>, span?: SourceSpan, sourceId?: string);
    /** Create from an AST node */
    static fromNode(errorId: string, message: string, node?: {
        span: SourceSpan;
    }, context?: Record<string, unknown>): RuntimeError;
}
/** Timeout errors */
export declare class TimeoutError extends RuntimeError {
    readonly functionName: string;
    readonly timeoutMs: number;
    constructor(functionName: string, timeoutMs: number, location?: SourceLocation);
}