/**
 * XmlError — structured error type for the xml-xsd-engine.
 *
 * Every error carries:
 *  • a machine-readable `code`      (e.g. "DUPLICATE_ATTRIBUTE")
 *  • a human-readable `message`
 *  • a `category`                   (G37: typed error classification)
 *  • optional source location       (line, col, path, source)
 *  • optional `stage`               (which pipeline stage produced the error)
 *
 * Error code stability guarantee (G37)
 * ──────────────────────────────────────
 * Error codes are stable across ALL minor and patch versions.
 * Removing or renaming a code requires a MAJOR version bump.
 * New codes may be added in minor versions.
 *
 * Error codes are grouped by phase:
 *  LEX_*    – lexer / tokenizer errors
 *  PARSE_*  – parser / well-formedness errors
 *  NS_*     – namespace errors
 *  SCHEMA_* – XSD parser / compiler errors
 *  VALID_*  – validation engine errors
 *  SEC_*    – security / limit errors
 *  IO_*     – file / stream I/O errors
 *  PIPE_*   – pipeline / orchestration errors  (v1.4)
 */
/**
 * High-level categories for structured error handling (G37).
 * Stable across all minor/patch versions.
 *
 *  'well-formedness'  – the XML document itself is malformed
 *  'namespace'        – namespace prefix / URI constraint violation
 *  'schema'           – the XSD schema itself has a problem
 *  'structure'        – document structure does not match schema
 *  'type'             – element/attribute value fails type constraint
 *  'identity'         – xs:key / xs:unique / xs:keyref violation
 *  'security'         – resource limits exceeded
 *  'io'               – file / stream read failure
 *  'pipeline'         – orchestration / internal pipeline error
 */
export type ValidationErrorCategory = 'well-formedness' | 'namespace' | 'schema' | 'structure' | 'type' | 'identity' | 'security' | 'io' | 'pipeline';
export type XmlErrorCode = 'LEX_UNEXPECTED_CHAR' | 'LEX_UNTERMINATED_STRING' | 'LEX_INVALID_ENTITY' | 'LEX_INVALID_CHAR_REF' | 'PARSE_MISMATCHED_TAG' | 'PARSE_UNCLOSED_TAG' | 'PARSE_DUPLICATE_ATTRIBUTE' | 'PARSE_MISSING_ROOT' | 'PARSE_MULTIPLE_ROOTS' | 'PARSE_EXPECTED_TOKEN' | 'PARSE_INVALID_PI_TARGET' | 'PARSE_INVALID_COMMENT' | 'PARSE_UNQUOTED_ATTRIBUTE' | 'NS_UNDECLARED_PREFIX' | 'NS_INVALID_QNAME' | 'NS_RESERVED_PREFIX' | 'SCHEMA_UNKNOWN_TYPE' | 'SCHEMA_CIRCULAR_TYPE' | 'SCHEMA_INVALID_FACET' | 'SCHEMA_MISSING_REQUIRED' | 'SCHEMA_PARSE_ERROR' | 'SCHEMA_UNDEFINED_REF' | 'SCHEMA_CONFLICTING_DECL' | 'SCHEMA_KEYREF_UNRESOLVED' | 'VALID_UNEXPECTED_ELEMENT' | 'VALID_MISSING_ELEMENT' | 'VALID_WRONG_TYPE' | 'VALID_MISSING_ATTRIBUTE' | 'VALID_BAD_ATTRIBUTE' | 'VALID_PATTERN_MISMATCH' | 'VALID_ENUM_MISMATCH' | 'VALID_OCCURRENCE' | 'VALID_ABSTRACT_ELEMENT' | 'VALID_IDENTITY_CONSTRAINT' | 'VALID_KEYREF_VIOLATION' | 'VALID_UNKNOWN_ELEMENT' | 'VALID_UNKNOWN_ATTRIBUTE' | 'VALID_DUPLICATE_XML_ID' | 'VALID_ASSERTION_FAILED' | 'SEC_MAX_DEPTH' | 'SEC_MAX_ATTRIBUTES' | 'SEC_MAX_TEXT_LENGTH' | 'SEC_ENTITY_EXPANSION' | 'SEC_EXTERNAL_ENTITY' | 'IO_FILE_NOT_FOUND' | 'IO_READ_ERROR' | 'PIPE_STAGE_FAILED' | 'PIPE_SCHEMA_COMPILE';
export interface SourceLocation {
    /** 1-based line number */
    line: number;
    /** 1-based column number */
    col: number;
    /** XPath-like path to the node in the document */
    path?: string;
    /** The source file/URL if known */
    source?: string;
    /**
     * G2: offset (0-based character position) in the original source string.
     * Populated when source-mapping is enabled on the parser.
     */
    offset?: number;
    /**
     * G2: end position of the offending token (for code-frame highlighting).
     */
    endLine?: number;
    endCol?: number;
}
/** Maps every error code to its high-level category. Stable across versions. */
export declare const ERROR_CATEGORY: Readonly<Record<XmlErrorCode, ValidationErrorCategory>>;
export declare class XmlError extends Error {
    readonly code: XmlErrorCode;
    readonly location: SourceLocation | null;
    /**
     * G37: Stable high-level category derived from the error code.
     * Use this for filtering/routing instead of parsing the code string.
     */
    readonly category: ValidationErrorCategory;
    /**
     * G34: Which pipeline stage produced this error.
     */
    readonly stage?: string;
    constructor(code: XmlErrorCode, message: string, location?: SourceLocation | null, stage?: string);
    /** Format as  "XmlError [CODE] at line N, col M: message" */
    toString(): string;
    /** True if this error is a security/limit violation */
    get isSecurity(): boolean;
    /** True if this error is a well-formedness violation */
    get isWellFormedness(): boolean;
    /** True if this error is a schema or validation error */
    get isValidation(): boolean;
    /** True if this is an identity-constraint violation */
    get isIdentityConstraint(): boolean;
}
export declare function xmlError(code: XmlErrorCode, message: string, location?: SourceLocation | null, stage?: string): XmlError;
export declare function secError(code: Extract<XmlErrorCode, `SEC_${string}`>, message: string, location?: SourceLocation | null): XmlError;
export declare function parseError(code: Extract<XmlErrorCode, `PARSE_${string}` | `LEX_${string}`>, message: string, location?: SourceLocation | null): XmlError;
export declare function nsError(code: Extract<XmlErrorCode, `NS_${string}`>, message: string, location?: SourceLocation | null): XmlError;
export declare function validError(code: Extract<XmlErrorCode, `VALID_${string}`>, message: string, location?: SourceLocation | null): XmlError;
export declare function schemaError(code: Extract<XmlErrorCode, `SCHEMA_${string}`>, message: string, location?: SourceLocation | null): XmlError;
//# sourceMappingURL=XmlError.d.ts.map