Module errors 

XSLT error handling (§33, §85 Phase 8).

Defines error domains, error levels, error handler types, and the public API for reporting and retrieving XSLT errors.

Upstream contract

Parity target: upstream libxslt xsltutils.c + xsltInternals.h (1.1.45; SRC-LIBXSLT-1.1.42-XSLTUTILS-C under oracle/historical/src). The observable surface is xsltTransformError (with its xsltPrintErrorContext context line), xsltSetTransformErrorFunc, xsltSetGenericDebugFunc/xsltGenericDebug, xsltGetLastError, and the XSLT_ERR_* domain/level constants from xslt.h 1.1.45.

Conceptual behavior

Error reporting follows upstream routing: xsltTransformError moves the transform context out of the OK state (error or stopped), prints the xsltPrintErrorContext context line (one of error, compilation error, runtime error, each optionally with file/line/ element), and emits the message verbatim — messages carry their own trailing newline and the function is variadic upstream, so callers format before calling (the candidate never expands %s/%d placeholders). With a registered per-context handler the message is routed there; otherwise it goes to stderr.

Ownership & safety invariants

• LAST_XSLT_ERROR is a mutex-guarded thread-safe copy of the last raw message; xsltGetLastError returns a heap copy the caller frees with libc::free (matching the documented caller frees contract for xsltGetLastError).
• Handler slots (error/errctx) are borrowed user-data, never dereferenced by the library — per atlas/OWNERSHIP_ATLAS.md section 6, the caller keeps the context alive.
• The exported xsltGenericDebug / xsltGenericDebugContext data globals (crate::abi::data_globals) are process-global, exactly like the upstream xsltGenericDebug globals; callers must not race them (R-000171 slot-race lesson applied to the debug pair). 11.1-Z.1: xsltGenericDebug is exported as DATA (function pointer, oracle D) with the upstream default handler, not as a function (R-000174).

Historical quirks & epochs

E-008 (atlas/SEMANTIC_EPOCHS.md): error output participates in the byte-identical xsltproc epoch (1.1.26, 2009, through 1.1.45), so the context-line wording is frozen. R-000161 fixed error routing parity for the generic/structured handler chain (xmlFormatError fragment streaming, 6 calls per raise) and the default variadic stderr printers xmlGenericError/xsltGenericError; the candidate xsltGenericDebug default handler writes through the xsltGenericDebugContext FILE* with the upstream NULL-context suppression (11.1-Z.1, R-000174). R-000140 covered the _xslt* ABI mirrors.

Deliberate oddities

• The variadic upstream signature is reduced to a pre-formatted message (an intentional, documented divergence — see the xsltTransformError docs); the emitted bytes match the oracle.
• xsltSetGenericDebugFunc keeps the upstream NULL-context suppression quirk: a NULL handler with a NULL context suppresses debug output.

Proving courts

ERROR-001 (error-family differential probe; R-000161), CLI-XSLTPROC (stderr byte-compare on failing stylesheets), XSLT-001, and the in-crate cargo test suites.

Tempting simplifications that would break parity

• Replacing the context line with a plain error: prefix breaks stderr byte-parity for compilation and runtime errors (the xsltPrintErrorContext forms are oracle-verified).
• Buffering the last-error message with the error state would drop the frozen state transition (OK → ERROR/STOPPED) that the transform loop checks to stop execution.
• Writing debug output unconditionally would break the upstream NULL-context suppression contract exercised by the CLI corpus.

Constants

XSLT_ERR_CYCLIC_REFERENCE

Cyclic reference detected.

XSLT_ERR_INTERNAL

Internal XSLT error.

XSLT_ERR_INVALID_ATTRIBUTE

Invalid attribute value.

XSLT_ERR_INVALID_ELEMENT

Invalid element.

XSLT_ERR_INVALID_MATCH

Invalid match pattern.

XSLT_ERR_INVALID_NAMESPACE

Invalid namespace.

XSLT_ERR_INVALID_SELECT

Invalid select expression.

XSLT_ERR_INVALID_TEST

Invalid test expression.

XSLT_ERR_INVALID_USE

Invalid use expression.

XSLT_ERR_LEVEL_ERROR

Error — processing may continue but results may be incomplete.

XSLT_ERR_LEVEL_FATAL

Fatal error — processing cannot continue.

XSLT_ERR_LEVEL_NONE

No error level (unset).

XSLT_ERR_LEVEL_WARNING

Warning — non-fatal issue.

XSLT_ERR_MISSING_ATTRIBUTE

Missing required attribute.

XSLT_ERR_MISSING_ELEMENT

Missing required element.

XSLT_ERR_MISSING_MATCH

Missing match attribute.

XSLT_ERR_MISSING_NAME

Missing name attribute.

XSLT_ERR_MISSING_NAMESPACE

Missing required namespace.

XSLT_ERR_MISSING_NS

Missing namespace.

XSLT_ERR_MISSING_SELECT

Missing select attribute.

XSLT_ERR_MISSING_TEST

Missing test attribute.

XSLT_ERR_MISSING_USE

Missing use attribute.

XSLT_ERR_NONE

No error.

XSLT_ERR_RECURSION

Recursion limit exceeded.

XSLT_ERR_UNKNOWN

Unknown error.

Functions

xsltEmitMessage

Emit an xsl:message payload through the transform error handler (or the global xsltGenericError channel), WITHOUT moving the transform context out of the OK state.

xsltGetLastError

Get the last XSLT error message as a NUL-terminated heap string.

xsltSetGenericDebugFunc^⚠

Global debug handler: the exported xsltGenericDebug data global in crate::abi::data_globals (upstream xsltGenericDebug, a function pointer variable defaulting to xsltGenericDebugDefaultFunc — R-000174).

xsltSetTransformErrorFunc

Set the transform error handler for a context.

xsltTransformError

Report an XSLT error.

Type Aliases

xsltTransformErrorFunc

Global XSLT error handler function type.