Make the error pool and status registry thread safe

Every entry point may now be called from any thread. akerr_init() runs
exactly once however many threads race into it, the pool hands each slot
to exactly one thread, and reservations, registrations and lookups are
serialized against each other.

One recursive lock covers both tables (src/lock.h, private). Recursive
because raising an error re-enters the library -- FAIL needs a pool slot
and a status name -- and single because two locks would mean an ordering
to get wrong. Registry bodies that use the early-returning FAIL_*_RETURN
macros are split into *_locked functions behind wrappers that take and
release the lock on one path; consumer callbacks are never called under
it.

This is an ABI break, hence 2.0.0 and SOVERSION 2:

- akerr_next_error() now returns a context that already holds its
  reference. Finding a free slot and claiming it has to be one operation,
  or two threads scanning at once are handed the same slot.
  ENSURE_ERROR_READY no longer increments.
- __akerr_last_ignored is thread-local, as is the last-ditch context used
  to report akerr_release_error(NULL).

The threading backend is chosen at configure time by AKERR_THREADS
(auto, pthread, none). auto fails the configure when it cannot find
POSIX threads rather than quietly building a library that reports itself
thread safe and is not. generrno.sh stamps the decision into the
generated header as AKERR_THREAD_SAFE, so a consumer cannot disagree
with the library about it.

Tests: err_threads_init, err_threads_pool and err_threads_registry
assert exclusive slot ownership, exactly one winner for a contested
range, and every registered name readable back under contention.
AKERR_SANITIZE builds the library and the tests with any sanitizer;
scripts/thread_test.sh runs the suite under ThreadSanitizer and CI runs
it. Removing the pool lock makes both the sanitizer and the plain
assertions fail, so the tests are not vacuous.

Documented in README.md and UPGRADING.md, including what this does not
cover: renaming a status while another thread looks it up, and which of
two simultaneous unhandled errors sets the exit status.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -3,11 +3,13 @@
 ## Project Structure & Module Organization
 
 This is a small C library built with CMake. Core implementation lives in
-`src/error.c`. The public header is generated at build time from
-`include/akerror.tmpl.h` by `scripts/generrno.sh`, which also generates
-`src/errno.c` under the build directory. CMake package and pkg-config templates
-are in `cmake/` and `akerror.pc.in`. Tests are one-file C programs in `tests/`;
-shared test helpers live beside them, such as `tests/err_capture.h`.
+`src/error.c`. `src/lock.h` is private: it selects the threading backend
+(pthread or none) and is not installed. The public header is generated at build
+time from `include/akerror.tmpl.h` by `scripts/generrno.sh`, which also
+generates `src/errno.c` under the build directory and stamps in whether the
+build is thread safe. CMake package and pkg-config templates are in `cmake/` and
+`akerror.pc.in`. Tests are one-file C programs in `tests/`; shared test helpers
+live beside them, such as `tests/err_capture.h` and `tests/err_threads.h`.
 
 ## Build, Test, and Development Commands
 
@@ -27,6 +29,20 @@ runs the registered unit tests. To emit CI-style results, use:
 ctest --test-dir build --output-on-failure --output-junit "$(pwd)/ctest-junit.xml"
 ```
 
+The suite includes thread tests. The run that proves there is no data race under
+them is ThreadSanitizer:
+
+```sh
+scripts/thread_test.sh
+```
+
+which configures `build/tsan` with `-DAKERR_SANITIZE=thread`, builds the library
+*and* the tests with it, and runs CTest with ASLR disabled (TSan aborts with an
+"unexpected memory mapping" on kernels with `vm.mmap_rnd_bits` above 28).
+`AKERR_SANITIZE` takes any sanitizer list, so `-DAKERR_SANITIZE=address,undefined`
+works the same way. Under a sanitized build a report fails the test rather than
+being printed and passed over.
+
 Mutation testing is available through:
 
 ```sh
@@ -44,9 +60,13 @@ scripts/coverage.py --threshold 90 --branch-threshold 50
 `scripts/coverage.py` configures its own instrumented build tree (default
 `build/coverage`, `-DAKERR_COVERAGE=ON`), runs the CTest suite there, and
 reports gcov line/branch coverage per library source. Thresholds gate each
-file as well as the total. Coverage measures `src/error.c` and the generated
-`src/errno.c` only; the public header's macros expand at their call sites, so
-mutation testing is what checks those.
+file as well as the total. Coverage measures the library's own sources only --
+`src/error.c`, `src/lock.h` and the generated `src/errno.c`; the public header's
+macros expand at their call sites, so mutation testing is what checks those.
+
+To build without threads (no locking, no thread-local storage, thread tests not
+registered), configure with `-DAKERR_THREADS=none`. `auto` is the default and
+fails the configure rather than falling back.
 
 ## Coding Style & Naming Conventions
 
@@ -56,6 +76,15 @@ such as `PREPARE_ERROR`. Keep generated-code changes in templates or generator
 scripts, not in build outputs. Preserve concise comments for invariants,
 macro constraints, and non-obvious error lifecycle behavior.
 
+**Locking.** One recursive lock (`akerr_state_lock`, see `src/lock.h`) covers
+both the error pool and the status registry. A function named `*_locked` is
+called with that lock already held; a function without the suffix takes it.
+Never take it in a body written with the `FAIL_*_RETURN` macros — those return
+from the middle of the function and would skip the unlock. Split it instead: the
+locked body does the work, and a thin wrapper takes the lock, calls it, and
+releases it on the single return path. Do not call consumer code
+(`akerr_log_method`, `akerr_handler_unhandled_error`) while holding it.
+
 ## Testing Guidelines
 
 Add tests as `tests/err_<behavior>.c`. Register each new test in the
@@ -66,6 +95,19 @@ CTest suite before submitting changes, and run mutation testing and coverage
 when changing core control-flow, reference counting, stack-trace, or handler
 behavior.
 
+Tests that drive the library from several threads go in the `AKERR_THREAD_SAFE`
+branch of the `AKERR_TESTS` list — an `-DAKERR_THREADS=none` build has no
+threading to test — and use `tests/err_threads.h`, which runs a body on
+`AKERR_TEST_THREADS` threads that meet at a barrier first.
+Count failures per thread with `AKERR_TCHECK` rather than returning early: a
+thread that abandons its work leaves the others holding pool slots and turns one
+failure into a cascade. Anything the test shares between its own threads must go
+through `__atomic` builtins — a race in the test is still a race, and
+ThreadSanitizer cannot tell you whose it is. The capturing logger in
+`err_capture.h` is single-threaded (shared buffer, shared length); use
+`akerr_thread_logger` instead. Run `scripts/thread_test.sh` when changing
+anything that touches the pool, the registry, initialization, or the lock.
+
 ## Commit & Pull Request Guidelines
 
 Recent commits use short, imperative, sentence-case subjects, for example