Module kind 

Error-kind numbering for the un* family: the values that are already shared, and the bands that keep future ones from colliding.

What is here, and what deliberately is not

Each library owns its own ErrorKind enum, because the reasons a PDF fails to parse are not the reasons a spreadsheet does. What they share is the numbering those enums live in, since the discriminants cross the C ABI as plain integers.

This module therefore exports only values that are already identical across the family. It does not offer a broad set of “common kinds”, and that restraint is the whole design: a library adopting a constant whose value differs from what it currently ships would be renumbering its public ABI. Above UNKNOWN_FORMAT the family already disagrees — the low band was assigned independently before anyone thought to align it — so any value published here would be a renumbering request aimed at somebody.

For everything else, this module offers bands rather than values: a range each library allocates from, so that a kind added next year does not land on a number that already means something elsewhere.

Bands

Range	Meaning
0	Success. Never a valid kind — see NONE
1..=17	Assigned before the convention existed. Frozen where shipped; see below
COMMON_BAND	New reasons that genuinely apply to more than one library
BOUNDARY_BAND	Failures of the ABI call itself, with no library-side counterpart
200..	One band per library, LIBRARY_BAND_SIZE wide. See library_band

The 1..=17 range is history, not design. Numbers in it are frozen for any library that has shipped them, and a library that has not shipped a given number should not assume it is free to mean something new — a consumer reading two of these libraries sees one integer space. Add new reasons from COMMON_BAND or a library band.

Where a failure is attributed

Two libraries classified the same failure differently — serialising a rendered result to JSON — because nothing said where it belonged. A shared numbering is only useful if the same failure lands on the same number, so the rule is stated here rather than rediscovered:

Failing to serialise a rendered result is a rendering failure. Producing output is rendering, and it stays rendering when the last step of producing it is serialisation. It is not a generic failure, and it is not a boundary failure — nothing is wrong with how the call was made.

A library with no rendering reason of its own takes one from its own band rather than reaching for OTHER, which means “this failure carries no classification” and is worth keeping true.

The contract consumers are promised

Every library in the family documents the same four rules. They are restated here because a shared numbering is only worth having if the rules are shared too:

1. A new reason takes a new number. Existing numbers are never reused or renumbered.
2. An unrecognised value is not an error — treat it as a generic failure and keep the number. A newer library stays usable by an older caller precisely because of this.
3. 0 means success, never a reason.
4. Reasons are #[non_exhaustive]: match with a _ => arm.

Constants

BOUNDARY_BAND

Reasons that describe a failure of the ABI call itself.

COMMON_BAND

Reasons that apply to more than one library and were assigned after the convention.

FIRST_LIBRARY_BAND

First number available to library bands.

INVALID_ARGUMENT

An argument was null, or a string argument was not valid UTF-8.

INVALID_OUTPUT

The result could not cross the ABI: a string holding an interior NUL byte.

IO

An I/O failure: a missing file, an unreadable one, a short read.

LIBRARY_BAND_SIZE

Width of each library’s private band.

NONE

No error is recorded: the last call on this thread succeeded.

OTHER

A failure with no more specific classification.

PANIC

A panic was caught at the ABI boundary.

UNKNOWN_FORMAT

The input is not a document this library recognises at all.

Functions

is_boundary

Whether kind names a failure at the ABI boundary rather than in the document.

library_band

The band belonging to library index, counting from zero.