Use the library's own error idioms inside the library

Four things in src/error.c did by hand what the macros already do, or
skipped checks the library would have caught for a consumer.

akerr_copy_string() returned void and validated only its capacity, while
writing through a caller-supplied pointer for a caller-supplied length.
It is now __akerr_copy_string() and raises: AKERR_NULLPOINTER for a NULL
destination or source, AKERR_VALUE for a capacity with no room for a
terminator. Both call sites PASS it, and the owner copy in
akerr_reserve_status_range() now gates the commit, so a failed copy
cannot leave a range claimed under an empty owner. It is exported under
the internal prefix rather than static so tests/err_copy_string.c can
drive those guards; nothing else can reach them.

__akerr_name_library_status() and the band reservation in akerr_init()
hand-rolled the log/handler/release sequence. Both now use
ATTEMPT/CATCH/PROCESS/FINISH_NORETURN. PASS does not fit: both sites are
void and have no caller to propagate to, so the terminal form of the same
idiom is the right one -- an unhandled failure prints its stack trace and
goes to akerr_handler_unhandled_error, which terminates, exactly as
before but without the bespoke plumbing. The legacy set path in
akerr_name_for_status() had the same shape and now handles its refusal
with HANDLE_DEFAULT, converting it to the "Unknown Error" sentinel.

Every remaining `if (x) { FAIL_RETURN }` in the registry is now
FAIL_ZERO_RETURN or FAIL_NONZERO_RETURN, and akerr_register_status_name()
checks both owner and name before passing either down --
akerr_store_status_name() reads a NULL owner as "caller did not identify
itself" for the legacy path, so a NULL arriving through the owned entry
point would have skipped the ownership check entirely.

New tests: err_copy_string (the guards above), err_library_status_fatal
(WILL_FAIL -- proves a refused library-status registration terminates).

Tests: ctest 31/31, mutation 80.7% (was 77.5%), line coverage 98.9%.
Branch coverage on src/error.c drops 64.5% -> 50.4%, just over its gate:
each FAIL_* site carries ~6 branch outcomes of error-construction
machinery that only run when that failure fires, and each PASS around a
call that cannot fail carries ~25, so added validation lowers the ratio
by construction. Recorded in TODO.md item 7.

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

.gitea/workflows/ci.yaml

@@ -0,0 +1,99 @@
+name: libakerror CI Build
+run-name: ${{ gitea.actor }} libakerror test
+on: [push]
+
+jobs:
+  cmake_build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Triggered by ${{ gitea.event_name }} from ${{ gitea.repository }}@${{ gitea.ref }}. Building on ${{ runner.os }}."
+      - name: Check out repository code
+        uses: actions/checkout@v4
+      - name: dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y cmake gcc moreutils
+      - name: build and install
+        run: |
+          mkdir installdir
+          cmake -S . -B build -DCMAKE_INSTALL_PREFIX=installdir
+          cmake --build build
+          cmake --install build
+      # --output-junit resolves relative to the test dir, so give an absolute
+      # path to land the report in the workspace root for the reporter below.
+      - name: test (JUnit)
+        run: ctest --test-dir build --output-on-failure --output-junit "$(pwd)/ctest-junit.xml"
+      # annotate_only: true skips creating a check run via the Checks API, which
+      # Gitea does not support and 404s on (mikepenz/action-junit-report#23).
+      # Results surface via the job summary instead.
+      - name: publish test results
+        if: always()
+        uses: mikepenz/action-junit-report@v4
+        with:
+          report_paths: 'ctest-junit.xml'
+          annotate_only: true
+          detailed_summary: true
+          include_passed: true
+          fail_on_failure: 'true'
+      - run: echo "🍏 This job's status is ${{ job.status }}."
+
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+      - name: dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y cmake gcc moreutils python3
+      # Run the suite against a gcov-instrumented build and gate on coverage of
+      # the library sources. Thresholds keep headroom below the current numbers
+      # (src/error.c: ~94% line, ~60% branch) and apply per file as well as to
+      # the total, so the generated status-name table cannot mask a regression.
+      - name: coverage
+        run: |
+          python3 scripts/coverage.py --junit coverage-junit.xml --threshold 90 --branch-threshold 50
+      # Publish even when the threshold gate fails, so gaps are visible.
+      # Display-only (fail_on_failure: false); the --threshold above is the gate.
+      # annotate_only avoids the Checks API 404 on Gitea (see note above).
+      - name: publish coverage results
+        if: always()
+        uses: mikepenz/action-junit-report@v4
+        with:
+          report_paths: 'coverage-junit.xml'
+          annotate_only: true
+          detailed_summary: true
+          include_passed: true
+          fail_on_failure: 'false'
+      - run: echo "🍏 This job's status is ${{ job.status }}."
+
+  mutation_test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+      - name: dependencies
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y cmake gcc moreutils python3
+      # Verify the tests actually catch bugs: break the library many ways and
+      # confirm the suite fails. Gated on src/error.c (fast, deterministic).
+      # The threshold keeps headroom below the current score for equivalent
+      # mutants; see tests/MUTATION.md. Run the full default target locally for
+      # deeper (slower) coverage including the macro header.
+      - name: mutation testing
+        run: |
+          python3 scripts/mutation_test.py --target src/error.c --junit mutation-junit.xml --threshold 65
+      # Publish even when the threshold gate fails, so survivors are visible.
+      # Display-only (fail_on_failure: false); the --threshold above is the gate.
+      # annotate_only avoids the Checks API 404 on Gitea (see note above).
+      - name: publish mutation results
+        if: always()
+        uses: mikepenz/action-junit-report@v4
+        with:
+          report_paths: 'mutation-junit.xml'
+          annotate_only: true
+          detailed_summary: true
+          include_passed: true
+          fail_on_failure: 'false'
+      - run: echo "🍏 This job's status is ${{ job.status }}."

.gitignore

@@ -0,0 +1,3 @@
+include/akerror.h
+build/
+*-junit.xml

AGENTS.md

@@ -0,0 +1,81 @@
+# Repository Guidelines
+
+## 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`.
+
+## Build, Test, and Development Commands
+
+Use an out-of-tree build:
+
+```sh
+cmake -S . -B build
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+`cmake -S . -B build` configures the build and generates `akerror.h`.
+`cmake --build build` compiles `libakerror` and test executables. `ctest`
+runs the registered unit tests. To emit CI-style results, use:
+
+```sh
+ctest --test-dir build --output-on-failure --output-junit "$(pwd)/ctest-junit.xml"
+```
+
+Mutation testing is available through:
+
+```sh
+cmake --build build --target mutation
+scripts/mutation_test.py --target src/error.c --threshold 65
+```
+
+Code coverage is available through:
+
+```sh
+cmake --build build --target coverage
+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.
+
+## Coding Style & Naming Conventions
+
+Use C99-compatible C and follow the surrounding style. Functions and types use
+the `akerr_` prefix; macros and constants use `AKERR_` or all-caps macro names
+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.
+
+## Testing Guidelines
+
+Add tests as `tests/err_<behavior>.c`. Register each new test in the
+`AKERR_TESTS` list in `CMakeLists.txt`; tests that intentionally abort must
+also be listed in `AKERR_WILL_FAIL_TESTS`. Prefer focused executable tests that
+return zero on success and use existing helpers such as `AKERR_CHECK`. Run the
+CTest suite before submitting changes, and run mutation testing and coverage
+when changing core control-flow, reference counting, stack-trace, or handler
+behavior.
+
+## Commit & Pull Request Guidelines
+
+Recent commits use short, imperative, sentence-case subjects, for example
+`Fix refcount leak and stack-trace buffer overflow`. Keep commits focused and
+describe the observable behavior changed. Pull requests should include a brief
+summary, tests run, and any compatibility impact for public macros, generated
+headers, installation paths, or CMake/pkg-config consumers.
+
+## Agent-Specific Instructions
+
+Do not overwrite uncommitted user changes. Avoid editing generated files in
+`build/`; update `include/akerror.tmpl.h`, `src/error.c`, CMake files, tests,
+or scripts instead.

CLAUDE.md

@@ -0,0 +1 @@
+See @AGENTS.md

CMakeLists.txt

@@ -1,12 +1,64 @@
 cmake_minimum_required(VERSION 3.10)
-project(akerror LANGUAGES C)
+# The status-code registry replaced the consumer-sized __AKERR_ERROR_NAMES array
+# with private storage, which is a source and ABI break for anything built
+# against an earlier header -- hence 1.0.0 and a SOVERSION, so a stale installed
+# libakerror.so can no longer be silently paired with new headers.
+project(akerror VERSION 1.0.0 LANGUAGES C)
 
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)
+include(CTest)
 
 set(AKERR_USE_STDLIB 1 CACHE BOOL "Use the C standard library")
+set(AKERR_COVERAGE 0 CACHE BOOL "Instrument the build with gcov coverage counters")
+
+# Size of the private status-name hash table. Must be a power of two; usable
+# capacity is 75% of it (src/error.c asserts both). The host's errno list
+# consumes part of that at akerr_init() time, so the remainder is what all
+# consumer libraries in the process share. These are applied PRIVATE on purpose:
+# the table lives entirely in src/error.c, so raising them never changes
+# anything a consumer can see. That is what makes them safe to tune, unlike the
+# AKERR_MAX_ERR_VALUE they replaced.
+set(AKERR_STATUS_NAME_SLOTS 4096 CACHE STRING
+    "Slots in the status-name table (power of two; 75% usable)")
+set(AKERR_MAX_RESERVED_STATUS_RANGES 64 CACHE STRING
+    "Maximum number of status ranges that may be reserved")
 set(akerror_install_cmakedir "${CMAKE_INSTALL_LIBDIR}/cmake/akerror")
 
+# Coverage instrumentation. Applied per target (not globally) so it never leaks
+# into the exported/installed target interface. Only the library is
+# instrumented: the tests are the thing doing the covering, and the public
+# header's macros cannot be measured this way at all -- GCC attributes an
+# expanded macro to its call site, so header logic shows up as test-file lines.
+# Coverage of those macros is what mutation testing (--target
+# include/akerror.tmpl.h) is for.
+if(AKERR_COVERAGE)
+    if(NOT CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
+        message(FATAL_ERROR
+            "AKERR_COVERAGE requires GCC or Clang, not ${CMAKE_C_COMPILER_ID}")
+    endif()
+    # -O0 keeps line counts attributable; no inlining or code motion.
+    set(AKERR_COVERAGE_FLAGS --coverage -O0 -g)
+    if(CMAKE_C_COMPILER_ID STREQUAL "GNU")
+        # Record absolute source paths so gcov resolves sources built from the
+        # generated directory (GCC 8+; harmless to check).
+        include(CheckCCompilerFlag)
+        check_c_compiler_flag(-fprofile-abs-path AKERR_HAVE_PROFILE_ABS_PATH)
+        if(AKERR_HAVE_PROFILE_ABS_PATH)
+            list(APPEND AKERR_COVERAGE_FLAGS -fprofile-abs-path)
+        endif()
+    endif()
+endif()
+
+# Add coverage compile/link flags to one target, if coverage is enabled.
+function(akerr_instrument_for_coverage _target)
+    if(AKERR_COVERAGE)
+        target_compile_options(${_target} PRIVATE ${AKERR_COVERAGE_FLAGS})
+        set_property(TARGET ${_target} APPEND_STRING
+                     PROPERTY LINK_FLAGS " --coverage")
+    endif()
+endfunction()
+
 set(SCRIPT ${CMAKE_CURRENT_SOURCE_DIR}/scripts/generrno.sh)
 set(INFILE ${CMAKE_CURRENT_SOURCE_DIR}/include/akerror.tmpl.h)
 
@@ -32,7 +84,7 @@ add_library(akerror SHARED
 )
 
 target_include_directories(akerror PUBLIC
-  $<BUILD_INTERFACE:${GENERATED_DIR}>/include
+  $<BUILD_INTERFACE:${GENERATED_DIR}/include>
   $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
 )
 
@@ -41,21 +93,113 @@ add_library(akerror::akerror ALIAS akerror)
 
 target_compile_definitions(akerror
     PUBLIC AKERR_USE_STDLIB=${AKERR_USE_STDLIB}
+    PRIVATE AKERR_STATUS_NAME_SLOTS=${AKERR_STATUS_NAME_SLOTS}
+    PRIVATE AKERR_MAX_RESERVED_STATUS_RANGES=${AKERR_MAX_RESERVED_STATUS_RANGES}
 )
 
-add_executable(test_err_catch tests/err_catch.c)
-add_executable(test_err_cleanup tests/err_cleanup.c)
-add_executable(test_err_trace tests/err_trace.c)
-add_executable(test_err_improper_closure tests/err_improper_closure.c)
-add_test(NAME err_catch COMMAND test_err_catch)
-add_test(NAME err_cleanup COMMAND test_err_cleanup)
-add_test(NAME err_trace COMMAND test_err_trace)
-add_test(NAME err_improper_closure COMMAND test_err_improper_closure)
+set_target_properties(akerror PROPERTIES
+    VERSION ${PROJECT_VERSION}
+    SOVERSION ${PROJECT_VERSION_MAJOR}
+)
 
-target_link_libraries(test_err_catch PRIVATE akerror)
-target_link_libraries(test_err_cleanup PRIVATE akerror)
-target_link_libraries(test_err_trace PRIVATE akerror)
-target_link_libraries(test_err_improper_closure PRIVATE akerror)
+akerr_instrument_for_coverage(akerror)
+
+# Each test is one source file in tests/ built into test_<name> and registered
+# as CTest <name>. Tests expected to abort (unhandled error / contract
+# violation) go in AKERR_WILL_FAIL_TESTS; all others must exit 0.
+set(AKERR_TESTS
+    err_catch
+    err_cleanup
+    err_trace
+    err_improper_closure
+    err_success
+    err_pool_refcount
+    err_handle_default
+    err_handle_group
+    err_handle_dispatch
+    err_pass
+    err_ignore
+    err_swallow
+    err_errno
+    err_break_variants
+    err_custom_handler
+    err_error_names
+    err_release_clears
+    err_pool_exhaust
+    err_maxval
+    err_name_ownership
+    err_registry_init_order
+    err_status_exception
+    err_copy_string
+    err_library_status_fatal
+    err_refcount_double_fail
+    err_stacktrace_bounds
+    err_name_bounds
+    err_format_string
+    err_unhandled_null
+    err_release_null
+    err_release_refcount
+)
+
+set(AKERR_WILL_FAIL_TESTS
+    err_trace
+    err_improper_closure
+    err_library_status_fatal
+)
+
+foreach(_test IN LISTS AKERR_TESTS)
+    add_executable(test_${_test} tests/${_test}.c)
+    target_include_directories(test_${_test} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/tests)
+    target_link_libraries(test_${_test} PRIVATE akerror)
+    add_test(NAME ${_test} COMMAND test_${_test})
+endforeach()
+
+set_tests_properties(
+    ${AKERR_WILL_FAIL_TESTS}
+    PROPERTIES WILL_FAIL TRUE
+)
+
+# Coverage and mutation testing are meta-checks on the test suite itself, and
+# both rebuild and re-run the whole suite, so they are manual targets rather
+# than CTest tests.
+find_package(Python3 COMPONENTS Interpreter)
+if(Python3_FOUND)
+    # Code coverage: which library lines/branches the CTest suite reaches.
+    #   cmake --build build --target coverage
+    # The script configures and drives its own instrumented build tree (under
+    # ${CMAKE_BINARY_DIR}/coverage) so this build's binaries and its coverage
+    # counters can never be stale or half-instrumented. Reports via gcov.
+    add_custom_target(coverage
+        COMMAND ${Python3_EXECUTABLE}
+                ${CMAKE_CURRENT_SOURCE_DIR}/scripts/coverage.py
+                --source-root ${CMAKE_CURRENT_SOURCE_DIR}
+                --build-dir ${CMAKE_CURRENT_BINARY_DIR}/coverage
+                --cmake ${CMAKE_COMMAND}
+                --ctest ${CMAKE_CTEST_COMMAND}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+        USES_TERMINAL
+        COMMENT "Running the test suite instrumented for coverage"
+    )
+
+    # Mutation testing: break the library in small ways and confirm the test
+    # suite notices.
+    #   cmake --build build --target mutation
+    # When embedded in another project, use a namespaced target to avoid
+    # collisions with mutation targets provided by sibling dependencies.
+    if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
+        set(AKERR_MUTATION_TARGET mutation)
+    else()
+        set(AKERR_MUTATION_TARGET akerror_mutation)
+    endif()
+    add_custom_target(${AKERR_MUTATION_TARGET}
+        COMMAND ${Python3_EXECUTABLE}
+                ${CMAKE_CURRENT_SOURCE_DIR}/scripts/mutation_test.py
+                --source-root ${CMAKE_CURRENT_SOURCE_DIR}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+        USES_TERMINAL
+        COMMENT "Running mutation tests (breaks the library, expects tests to fail)"
+    )
+endif()
 
 set(main_lib_dest "lib/my_library-${MY_LIBRARY_VERSION}")
 install(TARGETS akerror
@@ -66,11 +210,10 @@ install(TARGETS akerror
   INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
 )
 
-install(FILES "include/akerror.h" DESTINATION "include/")
+install(FILES ${GENERATED_AKERROR_H} DESTINATION "include/")
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/akerror.pc DESTINATION "lib/pkgconfig/")
 
-
-install(EXPORT akerror
+install(EXPORT akerrorTargets
     FILE akerrorTargets.cmake
     NAMESPACE akerror::
     DESTINATION ${akerror_install_cmakedir}

README.md

@@ -2,6 +2,16 @@
 
 This library provides a TRY/CATCH style exception handling mechanism for C. 
 
+![build badge](https://source.starfort.tech/andrew/libakerror/actions/workflows/ci.yaml/badge.svg?branch=main)
+
+## Upgrading from a pre-1.0.0 release
+
+1.0.0 replaced the consumer-sized status-name array with a private, ownership-
+enforced registry. That is a source and ABI break: see
+[UPGRADING.md](UPGRADING.md) for what was removed, how to migrate, the capacity
+limits and how to raise them, and the thread-safety rules.
+
+
 # Why?
 
 There is nothing wrong with C as it is. This library does not claim to fix some problem with C. 
@@ -62,14 +72,47 @@ Any function which uses the `PREPARE_ERROR` macro should have a return type of `
 
 The library uses integer values to specify error codes inside of its context. These integer return codes are defined in `akerror.h` in the form of `AKERR_xxxxx` where `xxxxx` is the name of the error code in question. See `akerror.h` for a list of defined errors and their descriptions. 
 
-You can define additional error types by defining additional `AKERR_xxxxx` values. Error values up to 255 are reserved by the library (`AKERR_xxxxx` begins where `errno` stops), so please begin your error values at 256. When you add additional error codes, you need to define `-DAKERR_MAX_ERR_VALUE=n` to the compiler, where `n` is the maximum error code you have defined. If you define custom error codes, `AKERR_MAX_ERR_VALUE` must be >= 256 or the compiler will throw an error.
+You can define additional error types as integer constants. Values 0 through 255
+are reserved by libakerror (the host's errno values plus the `AKERR_*` codes);
+consumers allocate codes starting at `AKERR_FIRST_CONSUMER_STATUS` (256). Status
+names are stored sparsely, so any `int` is a legal status and no compile
+definition is needed to use large values.
 
-Define a human-friendly name for the error with the `akerr_name_for_status` method somewhere in your code's initialization before the error may be used:
+Every library that may coexist in one process must reserve its range during
+initialization. `akerr_reserve_status_range()` and
+`akerr_register_status_name()` report failure the way everything else in this
+library does — they return `akerr_ErrorContext *`, and they are marked
+`AKERR_NOIGNORE` — so a collision is an exception you can `CATCH`, `HANDLE`, or
+`PASS` up out of your initialization:
 
 ```c
-akerr_name_for_status(129, "Some Error Code Description")
+#define MYLIB_OWNER "my-library"
+
+akerr_ErrorContext AKERR_NOIGNORE *mylib_init(void)
+{
+    PREPARE_ERROR(errctx);
+
+    /* Another component owning part of the range propagates to our caller. */
+    PASS(errctx, akerr_reserve_status_range(256, 16, MYLIB_OWNER));
+
+    /* Then name each code, quoting the owner you reserved with. */
+    PASS(errctx, akerr_register_status_name(MYLIB_OWNER, 256,
+                                            "Some Error Code Description"));
+    SUCCEED_RETURN(errctx);
+}
 ```
 
+Reservations are process-local, fixed-capacity, and idempotent when the same
+owner repeats the exact same range. They preserve compile-time integer constants
+so `HANDLE` still works, since `case` labels require them.
+
+Naming a status outside your reservation raises `AKERR_STATUS_NAME_FOREIGN`, and
+naming one nobody reserved raises `AKERR_STATUS_NAME_UNRESERVED`; a colliding
+reservation raises `AKERR_STATUS_RANGE_OVERLAP`, with a message naming the real
+owner. See [UPGRADING.md](UPGRADING.md) for the full list of statuses these two
+functions raise, the capacity limits and how to raise them, and thread-safety
+rules.
+
 
 # Installation
 
@@ -93,10 +136,14 @@ This library depends upon `stdlib`. If you don't want to link against stdlib, yo
 
 - `memset` function
 - `strncpy` function
+- `strlen` function
+- `strcmp` function
 - `sprintf` function
 - `exit` function
 - `bool` type
 - `NULL` type
+- `INT_MAX` constant
+- `PATH_MAX` constant
 
 ... then you can compile it thusly:
 
@@ -137,6 +184,14 @@ pkg_check_modules(akerror REQUIRED akerror)
 target_link_libraries(YOUR_TARGET PRIVATE akerror::akerror)
 ```
 
+Using this project as a submodule with cmake:
+
+```cmake
+add_subdirectory(deps/libakerror EXCLUDE_FROM_ALL)
+
+target_link_libraries(YOUR_PROJECT PRIVATE akerror::akerror)
+```
+
 
 ## (Optional) Configuring the logging function
 
@@ -200,6 +255,8 @@ ATTEMPT {
 
 This will assign the return value of the function in question to the akerr_ErrorContext previously prepared in the current scope. If the function returns an akerr_ErrorContext that indicates any type of error, the `ATTEMPT` block is immediately exited, and the `CLEANUP` block begins.
 
+(One caveat: because this exit is implemented with a C `break`, `CATCH` must not be used inside a loop within the `ATTEMPT` block — see the section "Important: do not use CATCH or FAIL_*_BREAK inside a loop" below.)
+
 ## Setting errors from functions or expressions returning integer
 
 For functions that return integer, such as logical comparisons or most standard library functions, use the `FAIL_ZERO_BREAK` and `FAIL_NONZERO_BREAK` macros. These macros allow you to capture an integer return code from an expression or function and set an error code in the current context based off that return.
@@ -222,6 +279,71 @@ ATTEMPT {
 
 When either of these two macros are used, the `ATTEMPT` block is immediately exited, and the `CLEANUP` block begins.
 
+## Important: do not use CATCH or FAIL_*_BREAK inside a loop
+
+`CATCH`, `FAIL_ZERO_BREAK`, `FAIL_NONZERO_BREAK`, and `FAIL_BREAK` leave the `ATTEMPT` block by executing a C `break` statement. In C, `break` only exits the *innermost* enclosing `for`, `while`, `do`, or `switch`. Therefore **these macros must not be used inside a loop (or a nested `switch`) that is itself inside an `ATTEMPT` block.** If you do, the `break` escapes only the loop — not the `ATTEMPT` — and the rest of the `ATTEMPT` body then runs with an error already pending:
+
+```c
+ATTEMPT {
+    for ( int i = 0; i < n; i++ ) {
+        CATCH(errctx, process(items[i]));   // WRONG: break exits the for loop, not the ATTEMPT
+    }
+    // ... this code still executes, with errctx already in an error state ...
+} CLEANUP {
+} PROCESS(errctx) {
+} FINISH(errctx, true);
+```
+
+Note that moving the loop into a helper function does **not** fix this on its own — if the helper still wraps the loop in an `ATTEMPT` and uses `CATCH`/`FAIL_*_BREAK` inside it, it has the exact same problem. The fix is to iterate with `return`-based macros, which are unaffected by loop nesting. Use one of the two patterns below.
+
+**Pattern 1 — use `PASS` (or a `FAIL_*_RETURN` macro) inside the loop.** These exit the *enclosing function* with a `return` rather than a `break`, so loop nesting is irrelevant. Use this when the loop should stop and propagate on the first error:
+
+```c
+akerr_ErrorContext AKERR_NOIGNORE *process_all(Item *items, int n)
+{
+    PREPARE_ERROR(errctx);
+    for ( int i = 0; i < n; i++ ) {
+        PASS(errctx, process(items[i]));   // returns from process_all on the first error
+    }
+    SUCCEED_RETURN(errctx);
+}
+```
+
+**Pattern 2 — move the loop into a helper and `CATCH` the single call.** When you need a `CLEANUP` block or want to `HANDLE` the error locally, put the loop in its own `akerr_ErrorContext *`-returning function (written per Pattern 1) and `CATCH` that one call. The `CATCH` is then not inside a loop, so its `break` scopes to the `ATTEMPT` correctly:
+
+```c
+ATTEMPT {
+    CATCH(errctx, process_all(items, n));   // a single CATCH, not looped
+} CLEANUP {
+    // ... always runs ...
+} PROCESS(errctx) {
+} HANDLE(errctx, AKERR_VALUE) {
+    // ... handle a failure from any iteration ...
+} FINISH(errctx, true);
+```
+
+# Passing errors
+
+Sometimes you can't actually do anything about the errors that come out of a given method, but you want that error to be propagated back up the call chain, and to be properly reported. If this is your goal, you can avoid using a `ATTEMPT ... FINISH` block, and simply use the `PASS` macro.
+
+```
+PREPARE_ERROR(e);
+PASS(e, some_method_that_may_fail());
+SUCCEED_RETURN(e);
+```
+
+This does the same thing as this, but with less code:
+
+```
+PREPARE_ERROR(e);
+ATTEMPT {
+    CATCH(e, some_method_that_may_fail());
+} CLEANUP {
+} PROCESS(e) {
+} FINISH(e, true);
+SUCCEED_RETURN(e);
+```
+
 # Handling errors
 
 Inside of the `PROCESS { ... }` block, you must handle any errors that occurred during the `ATTEMPT { ... }` block. You do this with `HANDLE`, `HANDLE_GROUP`, and `HANDLE_DEFAULT`.
@@ -310,20 +432,24 @@ FAIL_NONZERO_RETURN(errctx, strcmp("not", "equal"), AKERR_VALUE, "Strings are no
 
 # Uncaught errors
 
+## Misbehaving methods
+
+Any function which returns `akerr_ErrorContext *` and completes successfully MUST call `SUCCEED_RETURN(errctx)`. Failure to do this may result in an invalid `akerr_ErrorContext *` being returned, which will cause an `AKERR_BEHAVIOR` error to be triggered from your code. 
+
 ## Ensuring that all error codes are captured
 
-Any function which returns `akerr_ErrorContext *` should also be marked with `ERROR_NOIGNORE`.
+Any function which returns `akerr_ErrorContext *` should also be marked with `AKERROR_NOIGNORE`.
 
 ```c
-akerr_ErrorContext ERROR_NOIGNORE *f(...);
+akerr_ErrorContext AKERROR_NOIGNORE *f(...);
 ```
 
 This will cause a compile-time error if the return value of such a function is not used. "Used" here means assigned to a variable - it does not necessarily mean that the value is checked. However assuming that such functions are called inside of `ATTEMPT { ... }` blocks, it is safe to assume that such returns will be caught with `CATCH(...)`; therefore this error is a generally effective safeguard against careless coding where errors are not checked.
 
-Beware that `ERROR_NOIGNORE` is not a failsafe - it implements the `warn_unused_result` mechanic. By design users may explicitly ignore an error code from a function marked with `warn_unused_result` by explicitly casting the return to `void`.
+Beware that `AKERROR_NOIGNORE` is not a failsafe - it implements the `warn_unused_result` mechanic. By design users may explicitly ignore an error code from a function marked with `warn_unused_result` by explicitly casting the return to `void`.
 
 ```c
-#define ERROR_NOIGNORE __attribute__((warn_unused_result))
+#define AKERROR_NOIGNORE __attribute__((warn_unused_result))
 ```
 
 ## Stack Traces

TODO.md

@@ -0,0 +1,93 @@
+# TODO
+
+Working notes for `libakerror`. Outstanding items only.
+
+## 1. The test suite has no sanitizer run
+
+Mutation testing caught an out-of-bounds probe in the status-name hash table
+that the suite could not: the failure mode was a write into adjacent BSS, which
+does not crash, so every test still passed. Sharpening one test closed that
+instance, but ASan would have caught the whole class directly and independently
+of how sharp the assertions are.
+
+Add a `-fsanitize=address,undefined` build to `.gitea/workflows/ci.yaml`, or a
+CMake option alongside `AKERR_COVERAGE`. This is the highest-value item here: it
+covers the whole library, not just the registry, and the library's fixed pools
+and manual buffer arithmetic are exactly what it is good at.
+
+## 2. `HANDLE`-level status aliasing is still undetectable
+
+Two components can compile the same integer into a `case` label without ever
+reserving a range or registering a name, and nothing sees it. Ownership
+enforcement covers *naming*, which is the part the library mediates; the `case`
+label never reaches it.
+
+Closing this needs the `if`/`else if` handler ladder — rewriting
+`PROCESS`/`HANDLE`/`HANDLE_GROUP`/`HANDLE_DEFAULT`/`FINISH` so status matching
+is not restricted to integer constant expressions. That would also allow
+matching on ranges or predicates, and would let a handler resolve a code through
+its owner. It touches the most load-bearing code in the library and every
+consumer's error handling at once, so it wants its own change.
+
+Note it would *not* by itself fix the "don't use `CATCH` or `FAIL_*_BREAK`
+inside a loop" hazard: that comes from exiting via `break`, not from `switch`.
+
+## 3. No registry introspection
+
+There is no way to ask who owns a status, or to enumerate reservations. The
+"coordinate ranges at the dependency-stack level" advice in UPGRADING.md
+therefore has no tooling behind it.
+
+A read-only accessor plus a dump through `akerr_log_method` would let a startup
+self-check or a CI job print the whole map for a linked stack. Cheap, additive,
+and the natural next step for multi-component adoption.
+
+## 4. No way to release a reservation
+
+A plugin host that `dlopen`s many distinct plugins over a process lifetime
+accumulates ranges until the table fills. Reloading the *same* plugin is fine —
+an identical repeat by the same owner is idempotent.
+
+## 5. The registry is not thread safe
+
+Global mutable state, no locking, and `akerr_status_name_count++` is not atomic.
+Currently documented as an initialization-time-only API rather than enforced. If
+components start initializing on separate threads this needs either a lock or a
+documented once-per-process init barrier.
+
+## 6. Deprecate the two-argument name-registration path
+
+`akerr_name_for_status(status, name)` cannot identify its caller, so it can only
+check that *some* reservation covers the status, not that the caller owns it. It
+exists for migration. Once consumers have moved to
+`akerr_register_status_name()`, make the set path a no-op or remove it and leave
+`akerr_name_for_status()` as pure lookup.
+
+## 7. `akerr_init()`'s own reservation failure is untested
+
+`tests/err_library_status_fatal.c` covers the terminal path in
+`__akerr_name_library_status()` by naming a status the library does not own. The
+band reservation in `akerr_init()` has no such handle: it can only fail in a
+build whose tables are too small for the library's own entries, and both sizes
+are `PRIVATE` to the library target, so a test executable cannot set them.
+
+Closing it means a second library target built with tiny tables plus a
+`WILL_FAIL` test linked against it — worth doing when the CMake gains a
+sanitizer variant (item 1), since that adds the same machinery.
+
+Related: branch coverage on `src/error.c` now sits just above its 50% gate.
+Every `FAIL_*` site carries about six branch outcomes of error-construction
+machinery (`ENSURE_ERROR_READY`, `AKERR_STACKTRACE_APPEND`) that only run when
+that specific failure fires, and every `PASS` site around a call that cannot
+fail carries about twenty-five. Validating more inputs therefore lowers the
+ratio by construction. Before adding defensive checks, expect to add a test that
+drives them, as `tests/err_copy_string.c` does.
+
+## Unrelated pre-existing issues
+
+- The `AKERR_USE_STDLIB=OFF` build does not compile at all: `bool`, `PATH_MAX`
+  and `NULL` are used unconditionally but only included under the stdlib branch.
+  The README's dependency list states what a replacement must provide, but the
+  header still needs its includes untangled for that configuration to work.
+- `CMakeLists.txt` sets `main_lib_dest` from `MY_LIBRARY_VERSION`, which is never
+  defined and never read. Dead line.

UPGRADING.md

@@ -0,0 +1,208 @@
+# Upgrade notice: custom status codes (1.0.0)
+
+Version 1.0.0 replaces the consumer-sized status-name array with a private
+registry, and makes status-code ownership explicit and enforced. This is a
+source and ABI break. The library now carries a version and an soname
+(`libakerror.so.1`), so a stale installed library can no longer be silently
+paired with a newer header — but anything built against a pre-1.0.0 header must
+be rebuilt.
+
+What was removed:
+
+* `AKERR_MAX_ERR_VALUE` — the registry is sparse and accepts any `int`, so
+  consumers no longer size it. Delete every compile definition and source
+  reference. A stale `-DAKERR_MAX_ERR_VALUE=...` is now harmless but useless.
+* `__AKERR_ERROR_NAMES` — the name table is private to the library. Code that
+  touched this data symbol was using an undocumented interface; use
+  `akerr_name_for_status()`.
+* `AKERR_STATUS_RANGE_OK` and `AKERR_STATUS_NAME_OK` — the registry functions no
+  longer return an `int`. Success is a `NULL` `akerr_ErrorContext *`, like every
+  other function in the library. See "The registry raises errors" below.
+
+To migrate:
+
+1. Rebuild libakerror and every dependent library against the new header.
+2. Move custom status codes out of the reserved `0`–`255` band. Use fixed
+   integer constants beginning at `AKERR_FIRST_CONSUMER_STATUS` (256) rather
+   than offsets from `AKERR_LAST_ERRNO_VALUE`, so a libc that grows an errno
+   cannot move your codes.
+3. Assign a distinct range to every library that may coexist in one process, and
+   coordinate those ranges at the application or dependency-stack level.
+4. Reserve the complete range with `akerr_reserve_status_range()` during
+   initialization, and treat the error it returns like any other error: `CATCH`
+   it, `PASS` it, or let it propagate out of your init function.
+5. Register names with `akerr_register_status_name()`, passing the same owner
+   string you reserved with. **You can no longer name a status you have not
+   reserved** — see "Ownership is enforced" below.
+
+For example:
+
+```c
+enum {
+    MYLIB_ERR_BASE = AKERR_FIRST_CONSUMER_STATUS,   /* 256 */
+    MYLIB_ERR_PARSE = MYLIB_ERR_BASE,
+    MYLIB_ERR_STORAGE,
+    MYLIB_ERR_LIMIT
+};
+
+#define MYLIB_OWNER "mylib"
+
+akerr_ErrorContext AKERR_NOIGNORE *mylib_init(void)
+{
+    PREPARE_ERROR(errctx);
+
+    /* Any collision propagates out of mylib_init() to the caller. */
+    PASS(errctx, akerr_reserve_status_range(MYLIB_ERR_BASE,
+                                            MYLIB_ERR_LIMIT - MYLIB_ERR_BASE,
+                                            MYLIB_OWNER));
+    PASS(errctx, akerr_register_status_name(MYLIB_OWNER, MYLIB_ERR_PARSE,
+                                            "Parse Error"));
+    PASS(errctx, akerr_register_status_name(MYLIB_OWNER, MYLIB_ERR_STORAGE,
+                                            "Storage Error"));
+    SUCCEED_RETURN(errctx);
+}
+```
+
+If your `init` cannot return an `akerr_ErrorContext *` — a C API with an `int`
+return, say — catch the error and convert it. Close with `FINISH_NORETURN`
+rather than `FINISH`: nothing can propagate out of a function that does not
+return an error context, and `FINISH(errctx, false)` in an `int`-returning
+function compiles the (dead) propagation branch anyway, which warns.
+
+```c
+int mylib_init(void)
+{
+    PREPARE_ERROR(errctx);
+    int rc = MYLIB_INIT_OK;
+
+    ATTEMPT {
+        CATCH(errctx, akerr_reserve_status_range(MYLIB_ERR_BASE,
+                                                 MYLIB_ERR_LIMIT - MYLIB_ERR_BASE,
+                                                 MYLIB_OWNER));
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } HANDLE_DEFAULT(errctx) {
+        LOG_ERROR_WITH_MESSAGE(errctx, "mylib could not claim its status range");
+        rc = MYLIB_INIT_FAILED;   /* another component owns part of the range */
+    } FINISH_NORETURN(errctx);
+
+    return rc;
+}
+```
+
+You do not need to call `akerr_init()` first. Every registry entry point calls
+it for you, so a library that reserves its range before anything else in the
+process has touched libakerror keeps that reservation. (Before 1.0.0 this was
+silently destructive: `akerr_init()` cleared the tables, so a reservation made
+too early was discarded and the next component to claim the same range was told
+it was free.)
+
+## Ownership is enforced
+
+Reserving a range is no longer advisory bookkeeping. A status may only be named
+from inside a reservation:
+
+* `akerr_register_status_name(owner, status, name)` requires that `status` fall
+  in a range reserved by `owner`. Naming another component's status fails with
+  `AKERR_STATUS_NAME_FOREIGN`, and naming a status nobody reserved fails with
+  `AKERR_STATUS_NAME_UNRESERVED`.
+* The two-argument `akerr_name_for_status(status, name)` set path still works,
+  but it cannot identify its caller, so it can only require that *some*
+  reservation covers the status. Prefer the owned form: it is the one that
+  catches a component writing into a range that is not its own.
+
+Every refusal is reported, because a name that fails to register degrades that
+code to `"Unknown Error"` in every later stack trace.
+
+This detects *name* collisions. It cannot detect two components compiling the
+same integer into a `HANDLE` label without ever registering a name, so every
+co-resident library should still reserve its range.
+
+## The registry raises errors
+
+`akerr_reserve_status_range()` and `akerr_register_status_name()` return
+`akerr_ErrorContext *`, exactly like the rest of the library. They are marked
+`AKERR_NOIGNORE`, so discarding the result is a compile-time warning, and an
+error you catch but do not handle propagates out of your init function instead
+of leaving you with a range you do not actually own.
+
+```c
+ATTEMPT {
+    CATCH(errctx, akerr_reserve_status_range(256, 16, MYLIB_OWNER));
+} CLEANUP {
+} PROCESS(errctx) {
+} HANDLE(errctx, AKERR_STATUS_RANGE_OVERLAP) {
+    /* Another component owns part of it -- the message names which. */
+} FINISH(errctx, true);
+```
+
+`akerr_reserve_status_range()` raises:
+
+| Status | Meaning |
+| --- | --- |
+| — (returns `NULL`) | Range reserved, or an identical range was already reserved by the same owner |
+| `AKERR_STATUS_RANGE_OVERLAP` | Part of the range is owned by someone else (the message names the owner) |
+| `AKERR_STATUS_RANGE_FULL` | No reservation slots remain |
+| `AKERR_STATUS_RANGE_INVALID` | `count < 1`, NULL/empty/over-long owner, or the range overflows `int` |
+
+`akerr_register_status_name()` raises:
+
+| Status | Meaning |
+| --- | --- |
+| — (returns `NULL`) | Name registered |
+| `AKERR_STATUS_NAME_UNRESERVED` | No reservation contains this status |
+| `AKERR_STATUS_NAME_FOREIGN` | The status is in a range owned by someone else |
+| `AKERR_STATUS_NAME_FULL` | The name registry is full |
+| `AKERR_STATUS_NAME_INVALID` | NULL/empty/over-long owner, or a NULL name |
+
+These are ordinary status codes inside the library's reserved band, so they can
+be matched with `HANDLE`, grouped with `HANDLE_GROUP`, and they print with a
+name and a stack trace when they go unhandled.
+
+`akerr_name_for_status(status, name)` is the one exception: it returns a name
+rather than an error context, so it cannot raise. A refused registration through
+that path is reported through `akerr_log_method` and reads back as
+`"Unknown Error"`.
+
+Repeating an identical reservation for the same owner is a no-op. A *subset* or
+*superset* of your own range is not — it raises `AKERR_STATUS_RANGE_OVERLAP`.
+Reserve the whole range in one call.
+
+The library holds itself to the same rule at startup: if `akerr_init()` cannot
+reserve its own `0`–`255` band or name one of its own codes, it logs the failure
+and terminates the program. That can only happen in a misconfigured build (a
+name table too small for the library's own entries), and the alternative is a
+process whose stack traces silently read `"Unknown Error"` for built-in codes.
+
+## Capacity
+
+Both tables are fixed size, allocated in BSS, and never grow:
+
+| Limit | Default | Build-time override |
+| --- | --- | --- |
+| Status names | 3072 usable (4096 slots, 75% load) | `-DAKERR_STATUS_NAME_SLOTS=<power of two>` |
+| Reserved ranges | 64 | `-DAKERR_MAX_RESERVED_STATUS_RANGES=<n>` |
+
+`akerr_init()` consumes one name slot per host errno value plus one per
+`AKERR_*` code — around 150 on glibc, leaving roughly 2900 for all consumers in
+the process to share. That figure varies with the host libc, so treat it as
+approximate rather than a budget to fill.
+
+Both overrides are CMake cache variables and apply `PRIVATE` to the library
+target. The tables live entirely inside `src/error.c`, so raising them changes
+nothing a consumer can observe — unlike the `AKERR_MAX_ERR_VALUE` they replaced,
+where a mismatch between the library and its consumers corrupted memory. Set
+them when configuring libakerror itself:
+
+```sh
+cmake -S . -B build -DAKERR_STATUS_NAME_SLOTS=16384
+```
+
+Exhausting either table raises an error to the caller; it is never silent.
+
+## Thread safety
+
+The registry is process-global mutable state with no locking. Reserve ranges and
+register names during single-threaded initialization, before spawning threads.
+Lookups (`akerr_name_for_status(status, NULL)`) are safe to call concurrently
+once registration has finished.

include/akerror.tmpl.h

@@ -6,39 +6,76 @@
 #include <stdbool.h>
 #include <string.h>
 #include <stdio.h>
+#include <limits.h>
 #endif
 
-#define AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH              1024
+// FIXME: This is huge now. It used to be 1000 bytes, then I wanted to report errors
+// related to filesystem paths, which made it grow beyond PATH_MAX, then I started
+// reporting messages including 2 file paths (PATH_MAX * 2), so now to make the compiler warnings
+// shut up, it's enormous (PATH_MAX*3).
+#define AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH              12384
+
 #define AKERR_MAX_ERROR_NAME_LENGTH                        64
-#define AKERR_MAX_ERROR_FNAME_LENGTH                       256
+#define AKERR_MAX_ERROR_FNAME_LENGTH                       PATH_MAX
 #define AKERR_MAX_ERROR_FUNCTION_LENGTH                    128
-#define AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH              2048
+#define AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH              (AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH + AKERR_MAX_ERROR_NAME_LENGTH + AKERR_MAX_ERROR_FNAME_LENGTH + AKERR_MAX_ERROR_FUNCTION_LENGTH + 16)
 
 #define AKERR_LAST_ERRNO_VALUE      AKERR_LAST_ERRNO_VALUE_SED
 
-#define AKERR_NULLPOINTER           (AKERR_LAST_ERRNO_VALUE + 1)
-#define AKERR_OUTOFBOUNDS           (AKERR_LAST_ERRNO_VALUE + 2)
-#define AKERR_API                   (AKERR_LAST_ERRNO_VALUE + 3)
-#define AKERR_ATTRIBUTE             (AKERR_LAST_ERRNO_VALUE + 4)
-#define AKERR_TYPE                  (AKERR_LAST_ERRNO_VALUE + 5)
-#define AKERR_KEY                   (AKERR_LAST_ERRNO_VALUE + 6)                   
-#define AKERR_HEAP                  (AKERR_LAST_ERRNO_VALUE + 7)
-#define AKERR_INDEX                 (AKERR_LAST_ERRNO_VALUE + 8)
-#define AKERR_FORMAT                (AKERR_LAST_ERRNO_VALUE + 9)
-#define AKERR_IO                    (AKERR_LAST_ERRNO_VALUE + 10)
-#define AKERR_REGISTRY              (AKERR_LAST_ERRNO_VALUE + 11)
-#define AKERR_VALUE                 (AKERR_LAST_ERRNO_VALUE + 12)
-#define AKERR_BEHAVIOR              (AKERR_LAST_ERRNO_VALUE + 13)
-#define AKERR_RELATIONSHIP          (AKERR_LAST_ERRNO_VALUE + 14)
-#define AKERR_EOF                   (AKERR_LAST_ERRNO_VALUE + 15)
+#define AKERR_NULLPOINTER           (AKERR_LAST_ERRNO_VALUE + 1)   /** A pointer had a NULL value where such was not permissible */
+#define AKERR_OUTOFBOUNDS           (AKERR_LAST_ERRNO_VALUE + 2)   /** Attempt to access a datastructure outside of bounds */
+#define AKERR_API                   (AKERR_LAST_ERRNO_VALUE + 3)   /** An otherwise unspecified API contract has been violated */
+#define AKERR_ATTRIBUTE             (AKERR_LAST_ERRNO_VALUE + 4)   /** Relates to accessing of attributes on objects */
+#define AKERR_TYPE                  (AKERR_LAST_ERRNO_VALUE + 5)   /** An object had the incorrect type */
+#define AKERR_KEY                   (AKERR_LAST_ERRNO_VALUE + 6)   /** A key was either invalid for or not present in a map */
+#define AKERR_INDEX                 (AKERR_LAST_ERRNO_VALUE + 8)   /** An error occurred when attempting to index an indexable datastructure (other than out of bounds) */
+#define AKERR_FORMAT                (AKERR_LAST_ERRNO_VALUE + 9)   /** An error occurred in the formatting of an object (usually a string) */
+#define AKERR_IO                    (AKERR_LAST_ERRNO_VALUE + 10)  /** An unspecified IO error occurred. */
+#define AKERR_VALUE                 (AKERR_LAST_ERRNO_VALUE + 11)  /** A provided value was invalid */
+#define AKERR_RELATIONSHIP          (AKERR_LAST_ERRNO_VALUE + 12)  /** An error occurred in establishing, maintaining or severing a relationship between two objects */
+#define AKERR_EOF                   (AKERR_LAST_ERRNO_VALUE + 13)  /** The end of a stream or file has been encountered */
+#define AKERR_CIRCULAR_REFERENCE    (AKERR_LAST_ERRNO_VALUE + 14)  /** Indicates that a circular reference has been found in a linked list */
+#define AKERR_ITERATOR_BREAK        (AKERR_LAST_ERRNO_VALUE + 15)  /** Used to prematurely end an iteration cycle (such as when searching a graph and the desired node has been found) */
+#define AKERR_NOT_IMPLEMENTED       (AKERR_LAST_ERRNO_VALUE + 16)  /** A method was called that is defined but not currently implemented */
+#define AKERR_BADEXC                (AKERR_LAST_ERRNO_VALUE + 17)  /** The libakerr library was given an akerr_ErrorContext to parse that did not come from AKERR_ARRAY_ERROR (likely an uninitialized pointer) */
 
-#ifndef AKERR_MAX_ERR_VALUE
-#define AKERR_MAX_ERR_VALUE (AKERR_LAST_ERRNO_VALUE + 15)
-#elif AKERR_MAX_ERR_VALUE < 256
-#error user-defined AKERR_MAX_ERR_VALUE must be >= 256
-#endif
+/*
+ * Registry failures. These are ordinary status codes, not a private return
+ * enumeration: akerr_reserve_status_range() and akerr_register_status_name()
+ * return akerr_ErrorContext * like everything else in this library, so a refused
+ * reservation can be CATCH-ed, HANDLE-d, PASS-ed, or left unhandled to produce a
+ * stack trace and stop the program. Success returns NULL.
+ */
+#define AKERR_STATUS_RANGE_OVERLAP  (AKERR_LAST_ERRNO_VALUE + 18)  /** Some part of the range is already owned by someone else */
+#define AKERR_STATUS_RANGE_FULL     (AKERR_LAST_ERRNO_VALUE + 19)  /** No reservation slots remain (see AKERR_MAX_RESERVED_STATUS_RANGES) */
+#define AKERR_STATUS_RANGE_INVALID  (AKERR_LAST_ERRNO_VALUE + 20)  /** Bad count, bad owner string, or the range overflows int */
+#define AKERR_STATUS_NAME_UNRESERVED (AKERR_LAST_ERRNO_VALUE + 21) /** No owner has reserved a range containing this status */
+#define AKERR_STATUS_NAME_FOREIGN   (AKERR_LAST_ERRNO_VALUE + 22)  /** The status lies in a range reserved by a different owner */
+#define AKERR_STATUS_NAME_FULL      (AKERR_LAST_ERRNO_VALUE + 23)  /** The name registry is full (raise AKERR_STATUS_NAME_SLOTS) */
+#define AKERR_STATUS_NAME_INVALID   (AKERR_LAST_ERRNO_VALUE + 24)  /** NULL/empty/over-long owner, or a NULL name */
 
-extern char __AKERR_ERROR_NAMES[AKERR_MAX_ERR_VALUE+1][AKERR_MAX_ERROR_NAME_LENGTH];
+/* The last status the library defines for itself. Everything from
+ * AKERR_LAST_ERRNO_VALUE + 1 through here must have a registered name. */
+#define AKERR_LAST_LIBRARY_STATUS                AKERR_STATUS_NAME_INVALID
+
+/*
+ * Status values 0 through 255 are reserved by libakerror at akerr_init() time:
+ * the host's errno values plus the AKERR_* codes above. Consumers allocate from
+ * 256 upwards. Reserving any part of this band fails with
+ * AKERR_STATUS_RANGE_OVERLAP naming AKERR_LIBRARY_OWNER.
+ */
+#define AKERR_LIBRARY_OWNER                      "libakerror"
+#define AKERR_RESERVED_STATUS_COUNT              256
+#define AKERR_FIRST_CONSUMER_STATUS              AKERR_RESERVED_STATUS_COUNT
+
+/*
+ * The library reserves status values 0 through 255 for itself (see akerr_init),
+ * which must contain every AKERR_* code above. AKERR_LAST_ERRNO_VALUE is
+ * derived from the host's errno list at build time, so on a platform with an
+ * unusually large errno space these codes could escape the band and collide
+ * with consumer codes allocated at 256. Fail the build instead.
+ */
+typedef char akerr_assert_codes_within_reserved_band[(AKERR_LAST_LIBRARY_STATUS < 256) ? 1 : -1];
 
 #define AKERR_MAX_ARRAY_ERROR                    128
 
@@ -70,12 +107,56 @@ extern akerr_ErrorContext *__akerr_last_ignored;
 
 akerr_ErrorContext AKERR_NOIGNORE *akerr_release_error(akerr_ErrorContext *ptr);
 akerr_ErrorContext AKERR_NOIGNORE *akerr_next_error();
+/*
+ * Look up (name == NULL) or register (name != NULL) the display name for a
+ * status. Registration succeeds only if some owner has reserved a range
+ * containing `status`; prefer akerr_register_status_name(), which also checks
+ * that the range belongs to you and raises an error saying why a registration
+ * was refused. This entry point cannot return an error context, so a refusal
+ * here is reported through akerr_log_method and reads back as "Unknown Error".
+ * Never returns NULL -- an unregistered status reads back as "Unknown Error".
+ */
 char *akerr_name_for_status(int status, char *name);
+
+/*
+ * Register a display name for a status you own. `owner` must match the owner
+ * string passed to akerr_reserve_status_range() for the range containing
+ * `status`. Returns NULL on success, or an error context whose status is one of
+ * the AKERR_STATUS_NAME_* codes above -- CATCH it, HANDLE it, or let it
+ * propagate.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akerr_register_status_name(const char *owner, int status, const char *name);
+
+/*
+ * Claim `count` status values starting at `first_status` for `owner`. Repeating
+ * an identical reservation for the same owner is a no-op; any other collision is
+ * refused. Returns NULL on success, or an error context whose status is one of
+ * the AKERR_STATUS_RANGE_* codes above. Treat any error as an initialization
+ * failure: either handle it or let it propagate out of your init function.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akerr_reserve_status_range(int first_status, int count, const char *owner);
 void akerr_init();
 void akerr_default_handler_unhandled_error(akerr_ErrorContext *ptr);
 void akerr_default_logger(const char *f, ...);
+int akerr_valid_error_address(akerr_ErrorContext *ptr);
 /* defined in src/errno.c which is built dynamically at build time from system errno definitions */
 void akerr_init_errno(void);
+/*
+ * Internal. Names a status in the library's own reserved band on behalf of
+ * akerr_init() and the generated errno table, which have no caller to raise
+ * into: a failure here is logged and terminates the program. Not part of the
+ * consumer API -- use akerr_register_status_name(), which raises instead.
+ */
+void __akerr_name_library_status(int status, const char *name);
+
+/*
+ * Internal. Bounded string copy into a fixed buffer, always NUL-terminated.
+ * Raises AKERR_NULLPOINTER for a NULL destination or source and AKERR_VALUE for
+ * a capacity that leaves no room for a terminator. Exported so the library's
+ * own tests can drive those guards; not part of the consumer API.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *__akerr_copy_string(char *destination, int capacity,
+						       const char *source);
 
 #define LOG_ERROR_WITH_MESSAGE(__err_context, __err_message)		\
     akerr_log_method("%s%s:%s:%d: %s %d (%s): %s", (char *)&__err_context->stacktracebuf, (char *)__FILE__, (char *)__func__, __LINE__, __err_message, __err_context->status, akerr_name_for_status(__err_context->status, NULL), __err_context->message); \
@@ -99,10 +180,32 @@ void akerr_init_errno(void);
 	    akerr_log_method("%s:%s:%d: Unable to pull an error context from the array!", __FILE__, (char *)__func__, __LINE__); \
 	    exit(1);							\
 	}								\
-    }									\
-    __err_context->refcount += 1;
+	__err_context->refcount += 1;					\
+    }
 
-/* 
+/*
+ * Append a formatted line to the error's stack-trace buffer, bounded by the
+ * space that remains so a deep propagation chain cannot write past the end of
+ * stacktracebuf. snprintf reports the length it *would* have written, which on
+ * truncation exceeds what it actually wrote, so the cursor advance is clamped
+ * to the remaining space.
+ */
+#define AKERR_STACKTRACE_APPEND(__err_context, ...)			\
+    do {								\
+	char *__akerr_stb = (char *)__err_context->stacktracebuf;	\
+	size_t __akerr_used = (size_t)(__err_context->stacktracebufptr - __akerr_stb); \
+	if ( __akerr_used < AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH ) {	\
+	    size_t __akerr_rem = AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH - __akerr_used; \
+	    int __akerr_n = snprintf(__err_context->stacktracebufptr, __akerr_rem, __VA_ARGS__); \
+	    if ( __akerr_n < 0 ) {					\
+		__akerr_n = 0;						\
+	    }								\
+	    __err_context->stacktracebufptr += ((size_t)__akerr_n < __akerr_rem) \
+		? (size_t)__akerr_n : (__akerr_rem - 1);		\
+	}								\
+    } while ( 0 )
+
+/*
  * Failure and success methods for functions that return akerr_ErrorContext *
  */
 
@@ -157,11 +260,11 @@ void akerr_init_errno(void);
 #define FAIL(__err_context, __err, __message, ...)			\
     ENSURE_ERROR_READY(__err_context);					\
     __err_context->status = __err;					\
-    snprintf((char *)__err_context->fname, AKERR_MAX_ERROR_FNAME_LENGTH, __FILE__); \
-    snprintf((char *)__err_context->function, AKERR_MAX_ERROR_FUNCTION_LENGTH, __func__); \
+    snprintf((char *)__err_context->fname, AKERR_MAX_ERROR_FNAME_LENGTH, "%s", __FILE__); \
+    snprintf((char *)__err_context->function, AKERR_MAX_ERROR_FUNCTION_LENGTH, "%s", __func__); \
     __err_context->lineno = __LINE__;					\
     snprintf((char *)__err_context->message, AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH, __message, ## __VA_ARGS__); \
-    __err_context->stacktracebufptr += snprintf(__err_context->stacktracebufptr, AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH, "%s:%s:%d: %d (%s) : %s\n", (char *)__err_context->fname, (char *)__err_context->function, __err_context->lineno, __err_context->status, akerr_name_for_status(__err_context->status, NULL), (__err_context->message == NULL ? "" : __err_context->message));
+    AKERR_STACKTRACE_APPEND(__err_context, "%s:%s:%d: %d (%s) : %s\n", (char *)__err_context->fname, (char *)__err_context->function, __err_context->lineno, __err_context->status, akerr_name_for_status(__err_context->status, NULL), (__err_context->message == NULL ? "" : __err_context->message));
 
 
 #define SUCCEED(__err_context)			\
@@ -176,12 +279,18 @@ void akerr_init_errno(void);
     switch ( 0 ) {				\
     case 0:					\
 
+#define VALID(__err_context, __stmt)                       \
+    __stmt;                                                \
+    if ( akerr_valid_error_address(__err_context) == 0 ) { \
+	__err_context = NULL;                              \
+	FAIL(__err_context, AKERR_BADEXC, "Received (akerr_ErrorContext *) from an invalid memory region. (Did the method finish without calling SUCCEED_RETURN?)"); \
+    }
+
 #define DETECT(__err_context, __stmt)					\
-    __stmt;								\
+    VALID(__err_context, __stmt);					\
     if ( __err_context != NULL ) {					\
-	__err_context->stacktracebufptr += snprintf(__err_context->stacktracebufptr, AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH, "%s:%s:%d: Detected error %d from array (refcount %d)\n", (char *)__FILE__, (char *)__func__, __LINE__, __err_context->arrayid, __err_context->refcount); \
 	if ( __err_context->status != 0 ) {				\
-	    __err_context->stacktracebufptr += snprintf(__err_context->stacktracebufptr, AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH, "%s:%s:%d\n", (char *)__FILE__, (char *)__func__, __LINE__); \
+	    AKERR_STACKTRACE_APPEND(__err_context, "%s:%s:%d\n", (char *)__FILE__, (char *)__func__, __LINE__); \
 	    break;							\
 	}								\
     }
@@ -189,6 +298,13 @@ void akerr_init_errno(void);
 #define CATCH(__err_context, __stmt)			\
     DETECT(__err_context, __err_context = __stmt);
 
+#define PASS(__err_context, __stmt)               \
+    switch ( 0 ) {                                      \
+    case 0:                                             \
+	DETECT(__err_context, __err_context = __stmt);  \
+    }                                                   \
+    FINISH_LOGIC(__err_context, true);
+
 #define IGNORE(__stmt)							\
     __akerr_last_ignored = __stmt;					\
     if ( __akerr_last_ignored != NULL ) {				\
@@ -221,15 +337,17 @@ void akerr_init_errno(void);
     __err_context->stacktracebufptr = (char *)&__err_context->stacktracebuf; \
     __err_context->handled = true;
 
-#define FINISH(__err_context, __pass_up)				\
-    };									\
-    };									\
+#define FINISH_LOGIC(__err_context, __pass_up)                          \
     if ( __err_context != NULL ) {					\
 	if ( __err_context->handled == false && __pass_up == true ) {	\
-	    __err_context->stacktracebufptr += snprintf(__err_context->stacktracebufptr, AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH, "%s:%s:%d\n", (char *)__FILE__, (char *)__func__, __LINE__); \
 	    return __err_context;					\
 	}								\
     }									\
+
+#define FINISH(__err_context, __pass_up)				\
+    };									\
+    };									\
+    FINISH_LOGIC(__err_context, __pass_up)                              \
     RELEASE_ERROR(__err_context);
 
 #define FINISH_NORETURN(__err_context)					\
@@ -243,12 +361,4 @@ void akerr_init_errno(void);
     }									\
     RELEASE_ERROR(__err_context);
   
-#define CATCH_AND_RETURN(__err_context, __stmt) \
-    ATTEMPT {					\
-	CATCH(__err_context, __stmt);		\
-    } CLEANUP {					\
-      } PROCESS(__err_context) {		\
-	} FINISH(__err_context, true);		
-  
-
 #endif // _AKERR_H_

scripts/coverage.py

@@ -0,0 +1,407 @@
+#!/usr/bin/env python3
+"""
+Code coverage harness for libakerror.
+
+Coverage measures which parts of the library the CTest suite actually executes.
+It is the complement to mutation testing (scripts/mutation_test.py): coverage
+finds code the tests never reach, mutation testing finds code the tests reach
+but do not really check.
+
+What is measured is the library's own translation units: src/error.c and the
+generated src/errno.c. The macros in the public header are deliberately not
+measured -- GCC attributes an expanded macro to its call site, so header logic
+would be reported as lines of the test that used it. Use mutation testing
+(--target include/akerror.tmpl.h) to check how well those macros are tested.
+
+This harness has no third-party dependencies -- just gcov, which ships with the
+compiler, plus the project's normal cmake/ctest toolchain. By default it
+configures its own instrumented build directory so the ordinary build tree is
+left alone and coverage counters can never be stale.
+
+Usage:
+    scripts/coverage.py [options]
+
+    --source-root DIR     repo root (default: parent of this script's dir)
+    --build-dir DIR       instrumented build dir (default: <root>/build/coverage)
+    --no-configure        reuse the build dir as-is (do not cmake/build)
+    --no-run              report existing counters (do not reset and run ctest)
+    --threshold PCT       exit non-zero if line coverage < PCT (default: 0 = off)
+    --branch-threshold P  exit non-zero if branch coverage < P (default: 0 = off)
+    --junit PATH          write a JUnit XML report to this path
+    --max-uncovered N     uncovered lines to list per file (default: 40, 0 = all)
+    --exclude SUBSTR      skip reported paths containing SUBSTR; repeatable
+    --gcov PROG           gcov program (default: $GCOV or "gcov")
+"""
+
+import argparse
+import collections
+import json
+import os
+import subprocess
+import sys
+
+
+# --------------------------------------------------------------------------- #
+# Running the instrumented suite
+# --------------------------------------------------------------------------- #
+
+def configure_and_build(cmake, root, build, jobs):
+    """Configure an instrumented build dir and build everything in it."""
+    cmds = [
+        [cmake, "-S", root, "-B", build, "-DAKERR_COVERAGE=ON"],
+        [cmake, "--build", build] + (["--parallel", str(jobs)] if jobs else []),
+    ]
+    for cmd in cmds:
+        print("+ " + " ".join(cmd))
+        if subprocess.call(cmd) != 0:
+            return False
+    return True
+
+
+def reset_counters(build):
+    """Delete accumulated .gcda files so each run reports one suite run."""
+    removed = 0
+    for dirpath, _dirs, files in os.walk(build):
+        for name in files:
+            if name.endswith(".gcda"):
+                os.unlink(os.path.join(dirpath, name))
+                removed += 1
+    if removed:
+        print(f"Reset {removed} coverage data file(s).")
+
+
+def run_ctest(build, ctest):
+    """Run the suite. Returns True if every test passed.
+
+    Coverage counters are flushed at exit(), and the tests that are expected to
+    fail exit via the library's unhandled-error handler (exit(), not abort()),
+    so WILL_FAIL tests still contribute their counters.
+    """
+    cmd = [ctest, "--output-on-failure"]
+    print("+ " + " ".join(cmd) + f"   (in {build})")
+    return subprocess.call(cmd, cwd=build) == 0
+
+
+# --------------------------------------------------------------------------- #
+# Collecting gcov data
+# --------------------------------------------------------------------------- #
+
+class FileCov:
+    """Merged coverage for one source file, across every object that built it.
+
+    A file compiled into more than one object -- or a header included by several
+    translation units -- is reported once, with counts summed. Branches are
+    merged by (line, index within line), so differing expansions of the same
+    line contribute the union of their branches.
+    """
+
+    def __init__(self):
+        self.lines = collections.Counter()      # lineno -> execution count
+        self.branches = collections.Counter()   # (lineno, idx) -> taken count
+        self.funcs = collections.Counter()      # (name, start_line) -> count
+
+    def merge(self, entry):
+        for ln in entry.get("lines", []):
+            no = ln["line_number"]
+            self.lines[no] += ln.get("count", 0)
+            for idx, br in enumerate(ln.get("branches", [])):
+                if br.get("throw"):
+                    continue
+                self.branches[(no, idx)] += br.get("count", 0)
+        for fn in entry.get("functions", []):
+            key = (fn.get("name", "?"), fn.get("start_line", 0))
+            self.funcs[key] += fn.get("execution_count", 0)
+
+    @staticmethod
+    def _ratio(counter):
+        total = len(counter)
+        hit = sum(1 for v in counter.values() if v > 0)
+        return hit, total
+
+    def line_stats(self):
+        return self._ratio(self.lines)
+
+    def branch_stats(self):
+        return self._ratio(self.branches)
+
+    def func_stats(self):
+        return self._ratio(self.funcs)
+
+    def uncovered_lines(self):
+        return sorted(no for no, count in self.lines.items() if count == 0)
+
+
+def find_notes(build):
+    """Every .gcno in the build tree: one per instrumented translation unit."""
+    notes = []
+    for dirpath, _dirs, files in os.walk(build):
+        for name in files:
+            if name.endswith(".gcno"):
+                notes.append(os.path.join(dirpath, name))
+    return sorted(notes)
+
+
+def gcov_json(gcov, note, cwd):
+    """Run gcov on one .gcno and return its parsed JSON, or None on failure.
+
+    --stdout keeps gcov from littering .gcov files in the build tree. A .gcno
+    with no matching .gcda still reports, with all counts zero, which is the
+    correct answer for a translation unit no test executed.
+    """
+    cmd = [gcov, "--branch-probabilities", "--json-format", "--stdout", note]
+    proc = subprocess.Popen(cmd, cwd=cwd, stdout=subprocess.PIPE,
+                            stderr=subprocess.PIPE)
+    out, err = proc.communicate()
+    if proc.returncode != 0:
+        sys.stderr.write(f"warning: {' '.join(cmd)} failed:\n"
+                         f"{err.decode(errors='replace')}")
+        return None
+    try:
+        return json.loads(out.decode(errors="replace"))
+    except ValueError as exc:
+        sys.stderr.write(f"warning: unparseable gcov output for {note}: {exc}\n")
+        return None
+
+
+def display_path(path, build, root):
+    """Label a source: build-relative for generated files, else repo-relative.
+
+    Returns None for anything outside both trees (system headers, toolchain
+    internals). Generated sources are labelled relative to the build dir so the
+    report and its thresholds do not change with the build dir's location.
+    """
+    for base in (build, root):
+        if path.startswith(base + os.sep):
+            return os.path.relpath(path, base)
+    return None
+
+
+def collect(gcov, build, root, excludes):
+    """Merge gcov data for every instrumented unit into {display path: FileCov}."""
+    covs = {}
+    for note in find_notes(build):
+        data = gcov_json(gcov, note, build)
+        if data is None:
+            continue
+        # Paths in the report are relative to the directory the unit was
+        # compiled in, which gcov records in the notes file.
+        compile_dir = data.get("current_working_directory") or build
+        for entry in data.get("files", []):
+            path = entry.get("file", "")
+            if not os.path.isabs(path):
+                path = os.path.join(compile_dir, path)
+            display = display_path(os.path.realpath(path), build, root)
+            if display is None:
+                continue  # system headers, toolchain internals
+            if any(x in display for x in excludes):
+                continue
+            covs.setdefault(display, FileCov()).merge(entry)
+    return covs
+
+
+# --------------------------------------------------------------------------- #
+# Reporting
+# --------------------------------------------------------------------------- #
+
+def pct(hit, total):
+    return 100.0 * hit / total if total else 100.0
+
+
+def fmt_ratio(hit, total):
+    if not total:
+        return f"{'-':>9}      -"
+    return f"{hit:>4}/{total:<4} {pct(hit, total):5.1f}%"
+
+
+def compress(numbers):
+    """[1,2,3,7,9,10] -> '1-3, 7, 9-10' for readable uncovered-line lists."""
+    out, start, prev = [], None, None
+    for n in numbers:
+        if start is None:
+            start = prev = n
+        elif n == prev + 1:
+            prev = n
+        else:
+            out.append(f"{start}" if start == prev else f"{start}-{prev}")
+            start = prev = n
+    if start is not None:
+        out.append(f"{start}" if start == prev else f"{start}-{prev}")
+    return ", ".join(out)
+
+
+def report(covs, max_uncovered):
+    """Print the per-file table and uncovered detail; return overall percentages."""
+    width = max([len(p) for p in covs] + [len("TOTAL")])
+    print("\n" + "=" * 72)
+    print("CODE COVERAGE SUMMARY")
+    print("=" * 72)
+    print(f"  {'FILE':<{width}}  {'LINES':^15}  {'BRANCHES':^15}  FUNCS")
+
+    totals = [0, 0, 0, 0, 0, 0]  # lines hit/total, branches hit/total, funcs
+    for path in sorted(covs):
+        cov = covs[path]
+        lh, lt = cov.line_stats()
+        bh, bt = cov.branch_stats()
+        fh, ft = cov.func_stats()
+        for i, v in enumerate((lh, lt, bh, bt, fh, ft)):
+            totals[i] += v
+        print(f"  {path:<{width}}  {fmt_ratio(lh, lt)}  {fmt_ratio(bh, bt)}  "
+              f"{fh}/{ft}")
+
+    lh, lt, bh, bt, fh, ft = totals
+    print(f"  {'-' * width}  {'-' * 15}  {'-' * 15}  -----")
+    print(f"  {'TOTAL':<{width}}  {fmt_ratio(lh, lt)}  {fmt_ratio(bh, bt)}  "
+          f"{fh}/{ft}")
+
+    for path in sorted(covs):
+        missing = covs[path].uncovered_lines()
+        if not missing:
+            continue
+        shown = missing if not max_uncovered else missing[:max_uncovered]
+        more = "" if len(shown) == len(missing) else \
+            f" ... (+{len(missing) - len(shown)} more)"
+        print(f"\n  uncovered in {path} ({len(missing)} line(s)):")
+        print(f"    {compress(shown)}{more}")
+
+    return pct(lh, lt), pct(bh, bt)
+
+
+def _xml_escape(text):
+    return (str(text).replace("&", "&amp;").replace("<", "&lt;")
+            .replace(">", "&gt;").replace('"', "&quot;"))
+
+
+def write_junit(path, covs, line_threshold, branch_threshold):
+    """One <testcase> per file per metric; below-threshold is a <failure>."""
+    cases = []
+    for f in sorted(covs):
+        cov = covs[f]
+        cases.append((f, "lines", cov.line_stats(), line_threshold))
+        cases.append((f, "branches", cov.branch_stats(), branch_threshold))
+    for metric, thr, stats in (("lines", line_threshold,
+                                [c.line_stats() for c in covs.values()]),
+                               ("branches", branch_threshold,
+                                [c.branch_stats() for c in covs.values()])):
+        cases.append(("TOTAL", metric,
+                      (sum(h for h, _t in stats), sum(t for _h, t in stats)),
+                      thr))
+
+    fails = sum(1 for _f, _m, (h, t), thr in cases
+                if t and thr > 0 and pct(h, t) < thr)
+    out = ['<?xml version="1.0" encoding="UTF-8"?>',
+           f'<testsuites name="coverage" tests="{len(cases)}" '
+           f'failures="{fails}">',
+           f'  <testsuite name="coverage" tests="{len(cases)}" '
+           f'failures="{fails}">']
+    for f, metric, (hit, total), thr in cases:
+        name = _xml_escape(f"{f} {metric}")
+        detail = _xml_escape(f"{hit}/{total} ({pct(hit, total):.1f}%)"
+                             if total else "no data")
+        out.append(f'    <testcase name="{name}" '
+                   f'classname="coverage.{_xml_escape(metric)}" time="0">')
+        if total and thr > 0 and pct(hit, total) < thr:
+            out.append(f'      <failure message="{metric} coverage '
+                       f'{pct(hit, total):.1f}% &lt; threshold {thr:.1f}%">'
+                       f'{detail}</failure>')
+        else:
+            out.append(f'      <system-out>{detail}</system-out>')
+        out.append('    </testcase>')
+    out.append('  </testsuite>')
+    out.append('</testsuites>')
+    with open(path, "w") as fh:
+        fh.write("\n".join(out) + "\n")
+
+
+def main():
+    # Line-buffer stdout so progress is visible live under CI / the cmake target.
+    try:
+        sys.stdout.reconfigure(line_buffering=True)
+    except (AttributeError, ValueError):
+        pass
+    here = os.path.dirname(os.path.abspath(__file__))
+    default_root = os.path.dirname(here)
+
+    ap = argparse.ArgumentParser(description="Code coverage for libakerror")
+    ap.add_argument("--source-root", default=default_root)
+    ap.add_argument("--build-dir", default=None)
+    ap.add_argument("--configure", dest="configure", action="store_true",
+                    default=True)
+    ap.add_argument("--no-configure", dest="configure", action="store_false")
+    ap.add_argument("--run", dest="run", action="store_true", default=True)
+    ap.add_argument("--no-run", dest="run", action="store_false")
+    ap.add_argument("--threshold", type=float, default=0.0,
+                    help="fail if line coverage is below this percentage")
+    ap.add_argument("--branch-threshold", type=float, default=0.0,
+                    help="fail if branch coverage is below this percentage")
+    ap.add_argument("--junit", default=None,
+                    help="write a JUnit XML report to this path")
+    ap.add_argument("--max-uncovered", type=int, default=40)
+    ap.add_argument("--exclude", action="append", default=None,
+                    help="skip reported paths containing this substring")
+    ap.add_argument("--gcov", default=os.environ.get("GCOV", "gcov"))
+    ap.add_argument("--cmake", default=os.environ.get("CMAKE", "cmake"))
+    ap.add_argument("--ctest", default=os.environ.get("CTEST", "ctest"))
+    ap.add_argument("-j", "--jobs", type=int, default=0)
+    args = ap.parse_args()
+
+    root = os.path.realpath(args.source_root)
+    build = os.path.realpath(args.build_dir or os.path.join(root, "build",
+                                                            "coverage"))
+    # The tests exercise the library; their own source is not what we measure.
+    excludes = args.exclude if args.exclude is not None else ["tests/"]
+
+    if args.configure:
+        if not configure_and_build(args.cmake, root, build, args.jobs):
+            sys.stderr.write("\nInstrumented build FAILED; aborting.\n")
+            return 2
+    elif not os.path.isdir(build):
+        sys.stderr.write(f"No build dir at {build} (drop --no-configure).\n")
+        return 2
+
+    tests_ok = True
+    if args.run:
+        reset_counters(build)
+        tests_ok = run_ctest(build, args.ctest)
+        if not tests_ok:
+            sys.stderr.write("\nwarning: some tests FAILED; coverage below is "
+                             "still reported, but the run is not green.\n")
+
+    covs = collect(args.gcov, build, root, excludes)
+    if not covs:
+        sys.stderr.write("No coverage data found. Was the build instrumented "
+                         "(-DAKERR_COVERAGE=ON) and the suite run?\n")
+        return 2
+
+    line_pct, branch_pct = report(covs, args.max_uncovered)
+
+    if args.junit:
+        junit_path = os.path.abspath(args.junit)
+        write_junit(junit_path, covs, args.threshold, args.branch_threshold)
+        print(f"\nJUnit report written to: {junit_path}")
+
+    rc = 0
+    if not tests_ok:
+        print("\nFAIL: the CTest suite did not pass.")
+        rc = 1
+
+    # Thresholds gate every file as well as the total: a small, well-covered
+    # file (the generated status-name table) must not mask a regression in a
+    # bigger one. Files with no branches at all are not branch-gated.
+    checks = [("total", "line", line_pct, args.threshold),
+              ("total", "branch", branch_pct, args.branch_threshold)]
+    for path in sorted(covs):
+        lh, lt = covs[path].line_stats()
+        bh, bt = covs[path].branch_stats()
+        checks.append((path, "line", pct(lh, lt), args.threshold))
+        if bt:
+            checks.append((path, "branch", pct(bh, bt), args.branch_threshold))
+    for path, metric, value, threshold in checks:
+        if threshold > 0 and value < threshold:
+            print(f"\nFAIL: {path} {metric} coverage {value:.1f}% < threshold "
+                  f"{threshold:.1f}%")
+            rc = 1
+    return rc
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/generrno.sh

@@ -8,13 +8,24 @@ mkdir -p ${outdir}/include
 rm -f ${outdir}/src/errno.c
 echo "#include <akerror.h>" >> ${outdir}/src/errno.c
 echo "#include <errno.h>" >> ${outdir}/src/errno.c
+cat >> ${outdir}/src/errno.c <<'EOF'
+
+/*
+ * These names belong to the library's own reserved band, and this runs from
+ * akerr_init(), which has no caller to raise into -- so it goes through
+ * __akerr_name_library_status(), which reports a refusal and terminates rather
+ * than leaving every later stack trace to print "Unknown Error" for an errno.
+ * Keeping the branch in src/error.c also keeps this generated file free of
+ * control flow no test can reach.
+ */
+EOF
 echo "void akerr_init_errno(void) {" >> ${outdir}/src/errno.c
 maxval=$(errno --list | cut -d ' ' -f 2 | sort -g | tail -n 1)
 errno --list | while read LINE; do
     define=$(echo "$LINE" | cut -d ' ' -f 1);
     value=$(echo "$LINE" | cut -d ' ' -f 2);
     desc=$(echo "$LINE" | cut -d ' ' -f 3-);
-    echo "	akerr_name_for_status(${define}, \"${desc}\");" >> ${outdir}/src/errno.c ;
+    echo "	__akerr_name_library_status(${define}, \"${desc}\");" >> ${outdir}/src/errno.c ;
 done;
 echo "}" >> ${outdir}/src/errno.c
 sed "s/#define AKERR_LAST_ERRNO_VALUE .*/#define AKERR_LAST_ERRNO_VALUE      ${maxval}/" ${srcdir}/include/akerror.tmpl.h > ${outdir}/include/akerror.h

scripts/mutation_test.py

@@ -0,0 +1,436 @@
+#!/usr/bin/env python3
+"""
+Mutation testing harness for libakerror.
+
+Mutation testing measures how good the test suite is at catching bugs. It works
+by making many small, deliberate breakages ("mutants") to the library source --
+flipping a comparison, deleting a statement, swapping true/false -- and then
+running the whole CTest suite against each one. If the tests fail, the mutant is
+"killed" (good: the tests noticed the bug). If the tests still pass, the mutant
+"survived" (bad: a real bug of that shape would slip through unnoticed).
+
+The mutation score is killed / (killed + survived). Surviving mutants are printed
+with file:line and the exact change so they can be turned into new test cases.
+
+This harness has no third-party dependencies (Python stdlib + the project's
+normal cmake/ctest toolchain). It never mutates the real working tree: it copies
+the repo to a scratch directory and mutates there.
+
+Usage:
+    scripts/mutation_test.py [options]
+
+    --source-root DIR   repo root to copy (default: parent of this script's dir)
+    --target FILE       source file to mutate, relative to root; repeatable.
+                        Default: src/error.c and include/akerror.tmpl.h
+    --work DIR          scratch dir for the mutated copy (default: a temp dir)
+    --timeout SECONDS   per-suite ctest timeout (default: 120)
+    --threshold PCT     exit non-zero if mutation score < PCT (default: 0 = off)
+    --list              only list the mutants that would be run, then exit
+    --keep              keep the scratch working copy on exit (for debugging)
+    -j N                (reserved) currently runs sequentially
+"""
+
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+# --------------------------------------------------------------------------- #
+# Mutation operators
+#
+# Each operator yields zero or more (start, end, replacement) edits for a single
+# line of source. The driver applies exactly one edit per mutant so every mutant
+# differs from the original by one localized change.
+# --------------------------------------------------------------------------- #
+
+# Relational operator replacement: map each operator to the alternatives that
+# meaningfully change behaviour (not merely the strict negation).
+_REL = {
+    "==": ["!="],
+    "!=": ["=="],
+    "<=": ["<", "=="],
+    ">=": [">", "=="],
+    "<": ["<=", ">"],
+    ">": [">=", "<"],
+}
+# Match a relational operator that is NOT part of ->, <<, >>, =>, <=, >=, ==, !=
+# unless we intend it. We tokenize the two-char operators first, then single.
+_REL_TWO = re.compile(r"(==|!=|<=|>=)")
+_REL_ONE = re.compile(r"(?<![-<>=!+])([<>])(?![=<>])")
+
+_LOGICAL = {"&&": "||", "||": "&&"}
+_LOG_RE = re.compile(r"(&&|\|\|)")
+
+_BOOL = {"true": "false", "false": "true"}
+_BOOL_RE = re.compile(r"\b(true|false)\b")
+
+# Arithmetic / compound-assignment on whitespace-delimited operands only, to
+# avoid touching ++, --, ->, unary signs, or pointer/format punctuation.
+_ARITH_RE = re.compile(r"(?<=\s)([+\-])(?=\s)")
+_ARITH = {"+": "-", "-": "+"}
+_COMPOUND_RE = re.compile(r"(\+=|-=)")
+_COMPOUND = {"+=": "-=", "-=": "+="}
+
+# Integer literal replacement: 0 <-> 1 (word-bounded, not inside identifiers or
+# larger numbers, not a float).
+_INT_RE = re.compile(r"(?<![\w.])([01])(?![\w.])")
+_INT = {"0": "1", "1": "0"}
+
+
+def _op_edits(line):
+    """Yield (tag, start, end, replacement) for every candidate mutation."""
+    # Relational (two-char first so we don't split them with the one-char pass)
+    for m in _REL_TWO.finditer(line):
+        for alt in _REL[m.group(1)]:
+            yield ("ROR", m.start(1), m.end(1), alt)
+    for m in _REL_ONE.finditer(line):
+        for alt in _REL[m.group(1)]:
+            yield ("ROR", m.start(1), m.end(1), alt)
+    for m in _LOG_RE.finditer(line):
+        yield ("LCR", m.start(1), m.end(1), _LOGICAL[m.group(1)])
+    for m in _BOOL_RE.finditer(line):
+        yield ("BCR", m.start(1), m.end(1), _BOOL[m.group(1)])
+    for m in _COMPOUND_RE.finditer(line):
+        yield ("AOR", m.start(1), m.end(1), _COMPOUND[m.group(1)])
+    for m in _ARITH_RE.finditer(line):
+        yield ("AOR", m.start(1), m.end(1), _ARITH[m.group(1)])
+    for m in _INT_RE.finditer(line):
+        yield ("ICR", m.start(1), m.end(1), _INT[m.group(1)])
+
+
+# Statement-deletion: neutralize a whole statement. We only delete statements
+# that are safe to drop without guaranteeing a compile error, so a surviving
+# deletion is a genuine test gap rather than compiler noise.
+_STMT_DELETABLE = re.compile(
+    r"""^\s*(
+          break |
+          return\b[^;]* |
+          [A-Za-z_][-\w>().\[\]* ]*\s*=\s*[^;]* |   # assignments
+          [A-Za-z_][\w]*\s*\([^;]*\)                # bare function calls
+        )\s*;\s*(\\?)\s*$""",
+    re.VERBOSE,
+)
+
+
+# --------------------------------------------------------------------------- #
+# Deciding which lines are eligible to mutate
+# --------------------------------------------------------------------------- #
+
+# Skip preprocessor control and the block of constant/error-code #defines in the
+# template header: mutating buffer sizes or renumbering error codes produces
+# equivalent or uninteresting mutants that swamp the signal.
+_SKIP_LINE = re.compile(
+    r"""^\s*(
+          \#\s*(include|ifn?def|ifdef|if|elif|else|endif|error|pragma|undef) |
+          \#\s*define\s+AKERR_(MAX|LAST|NULLPOINTER|OUTOFBOUNDS|API|ATTRIBUTE|
+              TYPE|KEY|INDEX|FORMAT|IO|VALUE|RELATIONSHIP|EOF|CIRCULAR_REFERENCE|
+              ITERATOR_BREAK|NOT_IMPLEMENTED|BADEXC|NOIGNORE|USE_STDLIB)\b |
+          \*  | //                                   # comment bodies / line comments
+        )""",
+    re.VERBOSE,
+)
+
+
+def _is_comment_or_blank(line):
+    s = line.strip()
+    return (not s) or s.startswith("//") or s.startswith("/*") or s.startswith("*")
+
+
+def eligible(line):
+    if _is_comment_or_blank(line):
+        return False
+    if _SKIP_LINE.match(line):
+        return False
+    return True
+
+
+class Mutant:
+    __slots__ = ("path", "lineno", "op", "before", "after", "col")
+
+    def __init__(self, path, lineno, op, before, after, col):
+        self.path = path
+        self.lineno = lineno
+        self.op = op
+        self.before = before
+        self.after = after
+        self.col = col
+
+    def describe(self):
+        return (f"{self.path}:{self.lineno} [{self.op}] "
+                f"col{self.col}: {self.before.strip()}  ->  {self.after.strip()}")
+
+
+def generate_mutants(root, rel_target):
+    """Enumerate all mutants for one target file."""
+    abspath = os.path.join(root, rel_target)
+    with open(abspath, "r") as fh:
+        lines = fh.readlines()
+
+    mutants = []
+    for i, line in enumerate(lines, start=1):
+        if not eligible(line):
+            continue
+        # substitution operators
+        seen = set()
+        for tag, s, e, repl in _op_edits(line):
+            key = (s, e, repl)
+            if key in seen:
+                continue
+            seen.add(key)
+            mutated = line[:s] + repl + line[e:]
+            if mutated == line:
+                continue
+            mutants.append(Mutant(rel_target, i, tag, line, mutated, s))
+        # statement deletion
+        m = _STMT_DELETABLE.match(line)
+        if m:
+            indent = line[: len(line) - len(line.lstrip())]
+            cont = "\\" if line.rstrip().endswith("\\") else ""
+            deleted = f"{indent}/* mutant: deleted */ {cont}\n" if cont else f"{indent};\n"
+            mutants.append(Mutant(rel_target, i, "SDL", line, deleted, 0))
+    return mutants
+
+
+# --------------------------------------------------------------------------- #
+# Build / test orchestration against a scratch copy
+# --------------------------------------------------------------------------- #
+
+class Runner:
+    def __init__(self, work, timeout):
+        self.work = work
+        self.build = os.path.join(work, "build")
+        self.timeout = timeout
+
+    def _run(self, cmd, timeout=None):
+        return subprocess.run(
+            cmd, cwd=self.work, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+            timeout=timeout,
+        )
+
+    def configure(self):
+        r = self._run(["cmake", "-S", ".", "-B", "build"], timeout=self.timeout)
+        return r.returncode == 0, r.stdout
+
+    def build_and_test(self):
+        """Return ('killed-compile' | 'killed-test' | 'killed-timeout' | 'survived')."""
+        try:
+            b = self._run(["cmake", "--build", "build"], timeout=self.timeout)
+        except subprocess.TimeoutExpired:
+            return "killed-timeout"
+        if b.returncode != 0:
+            return "killed-compile"
+        try:
+            t = subprocess.run(
+                ["ctest", "--test-dir", "build", "--output-on-failure",
+                 "--stop-on-failure"],
+                cwd=self.work, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                timeout=self.timeout,
+            )
+        except subprocess.TimeoutExpired:
+            return "killed-timeout"
+        return "survived" if t.returncode == 0 else "killed-test"
+
+
+def _xml_escape(s):
+    return (s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+            .replace('"', "&quot;"))
+
+
+def write_junit(path, records, targets):
+    """Write a JUnit XML report. One <testcase> per mutant; a surviving mutant
+    is a <failure> (test-suite gap), a killed mutant is a passing case."""
+    by_file = {t: [] for t in targets}
+    for m, result in records:
+        by_file.setdefault(m.path, []).append((m, result))
+
+    total = len(records)
+    total_fail = sum(1 for _, r in records if r == "survived")
+    out = ['<?xml version="1.0" encoding="UTF-8"?>',
+           f'<testsuites name="mutation" tests="{total}" failures="{total_fail}">']
+    for f, items in by_file.items():
+        if not items:
+            continue
+        fails = sum(1 for _, r in items if r == "survived")
+        out.append(f'  <testsuite name="mutation:{_xml_escape(f)}" '
+                   f'tests="{len(items)}" failures="{fails}">')
+        for m, result in items:
+            name = _xml_escape(m.describe())
+            cls = "mutation." + _xml_escape(m.path)
+            if result == "survived":
+                detail = _xml_escape(f"{m.before.strip()}  ->  {m.after.strip()}")
+                out.append(f'    <testcase name="{name}" classname="{cls}" time="0">')
+                out.append(f'      <failure message="survived mutant '
+                           f'({_xml_escape(m.op)} at {_xml_escape(m.path)}:'
+                           f'{m.lineno})">{detail}</failure>')
+                out.append('    </testcase>')
+            else:
+                out.append(f'    <testcase name="{name}" classname="{cls}" '
+                           f'time="0"><system-out>{_xml_escape(result)}'
+                           '</system-out></testcase>')
+        out.append('  </testsuite>')
+    out.append('</testsuites>')
+    with open(path, "w") as fh:
+        fh.write("\n".join(out) + "\n")
+
+
+def copy_tree(src, dst):
+    ignore = shutil.ignore_patterns("build", ".git", "*.o", "*.so", "*~",
+                                    "#*#", "*.iso", "*.png")
+    shutil.copytree(src, dst, ignore=ignore, symlinks=True)
+
+
+def read_lines(path):
+    with open(path) as fh:
+        return fh.readlines()
+
+
+def write_lines(path, lines):
+    with open(path, "w") as fh:
+        fh.writelines(lines)
+
+
+def main():
+    # Line-buffer stdout so progress is visible live under CI / the cmake target.
+    try:
+        sys.stdout.reconfigure(line_buffering=True)
+    except (AttributeError, ValueError):
+        pass
+    here = os.path.dirname(os.path.abspath(__file__))
+    default_root = os.path.dirname(here)
+
+    ap = argparse.ArgumentParser(description="Mutation testing for libakerror")
+    ap.add_argument("--source-root", default=default_root)
+    ap.add_argument("--target", action="append", default=None)
+    ap.add_argument("--work", default=None)
+    ap.add_argument("--timeout", type=int, default=120)
+    ap.add_argument("--threshold", type=float, default=0.0)
+    ap.add_argument("--junit", default=None,
+                    help="write a JUnit XML report to this path")
+    ap.add_argument("--max-mutants", type=int, default=0,
+                    help="cap the run at N evenly-sampled mutants (0 = all)")
+    ap.add_argument("--list", action="store_true")
+    ap.add_argument("--keep", action="store_true")
+    ap.add_argument("-j", type=int, default=1)
+    args = ap.parse_args()
+
+    root = os.path.abspath(args.source_root)
+    targets = args.target or ["src/error.c", "include/akerror.tmpl.h"]
+
+    # Enumerate mutants from the pristine sources.
+    all_mutants = []
+    for t in targets:
+        all_mutants.extend(generate_mutants(root, t))
+
+    print(f"Generated {len(all_mutants)} mutants across {len(targets)} file(s):")
+    for t in targets:
+        n = sum(1 for m in all_mutants if m.path == t)
+        print(f"    {t}: {n}")
+
+    # Optional even-strided sampling to bound run time (CI / smoke tests).
+    if args.max_mutants and len(all_mutants) > args.max_mutants:
+        step = len(all_mutants) / args.max_mutants
+        sampled = [all_mutants[int(i * step)] for i in range(args.max_mutants)]
+        print(f"Sampling {len(sampled)} of {len(all_mutants)} mutants "
+              f"(--max-mutants {args.max_mutants}).")
+        all_mutants = sampled
+
+    if args.list:
+        for m in all_mutants:
+            print("  " + m.describe())
+        return 0
+
+    if not all_mutants:
+        print("No mutants generated; nothing to do.")
+        return 0
+
+    # Scratch working copy.
+    work_parent = args.work or tempfile.mkdtemp(prefix="akerr_mut_")
+    work = os.path.join(work_parent, "src") if args.work else work_parent
+    if os.path.exists(work):
+        shutil.rmtree(work)
+    print(f"\nCopying sources to scratch dir: {work}")
+    copy_tree(root, work)
+
+    runner = Runner(work, args.timeout)
+
+    print("Configuring baseline ...")
+    ok, out = runner.configure()
+    if not ok:
+        sys.stderr.write(out.decode(errors="replace"))
+        sys.stderr.write("\nBaseline configure FAILED; aborting.\n")
+        return 2
+
+    print("Verifying baseline is green (no mutation) ...")
+    baseline = runner.build_and_test()
+    if baseline != "survived":
+        sys.stderr.write(f"Baseline is not green ({baseline}); aborting. "
+                         "Fix the suite before mutation testing.\n")
+        return 2
+    print("Baseline OK.\n")
+
+    # Group mutants by file so we mutate one file at a time and restore it.
+    killed = {"killed-compile": 0, "killed-test": 0, "killed-timeout": 0}
+    survivors = []
+    records = []
+    total = len(all_mutants)
+
+    # Cache pristine contents per target.
+    pristine = {t: read_lines(os.path.join(work, t)) for t in targets}
+
+    for idx, m in enumerate(all_mutants, start=1):
+        tgt_abs = os.path.join(work, m.path)
+        lines = list(pristine[m.path])
+        lines[m.lineno - 1] = m.after
+        write_lines(tgt_abs, lines)
+        try:
+            result = runner.build_and_test()
+        finally:
+            write_lines(tgt_abs, pristine[m.path])  # always restore
+
+        records.append((m, result))
+        if result == "survived":
+            survivors.append(m)
+            mark = "SURVIVED"
+        else:
+            killed[result] += 1
+            mark = result.upper()
+        print(f"[{idx}/{total}] {mark:16} {m.describe()}")
+
+    total_killed = sum(killed.values())
+    score = 100.0 * total_killed / total if total else 100.0
+
+    print("\n" + "=" * 72)
+    print("MUTATION TESTING SUMMARY")
+    print("=" * 72)
+    print(f"  total mutants   : {total}")
+    print(f"  killed (test)   : {killed['killed-test']}")
+    print(f"  killed (compile): {killed['killed-compile']}")
+    print(f"  killed (timeout): {killed['killed-timeout']}")
+    print(f"  survived        : {len(survivors)}")
+    print(f"  mutation score  : {score:.1f}%")
+    if survivors:
+        print("\nSurviving mutants (test-suite gaps -- turn these into tests):")
+        for m in survivors:
+            print("  " + m.describe())
+
+    if args.junit:
+        junit_path = os.path.abspath(args.junit)
+        write_junit(junit_path, records, targets)
+        print(f"\nJUnit report written to: {junit_path}")
+
+    if not args.keep and not args.work:
+        shutil.rmtree(work_parent, ignore_errors=True)
+    else:
+        print(f"\nScratch working copy kept at: {work}")
+
+    if args.threshold > 0 and score < args.threshold:
+        print(f"\nFAIL: mutation score {score:.1f}% < threshold {args.threshold:.1f}%")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/error.c

@@ -10,14 +10,106 @@ akerr_ErrorContext *__akerr_last_ignored;
 akerr_ErrorUnhandledErrorHandler akerr_handler_unhandled_error;
 akerr_ErrorLogFunction akerr_log_method = NULL;
 
-char __AKERR_ERROR_NAMES[AKERR_MAX_ERR_VALUE+1][AKERR_MAX_ERROR_NAME_LENGTH];
+/*
+ * Status-name registry.
+ *
+ * Storage is an open-addressed hash table keyed by status value. Both sizes are
+ * private to this translation unit -- they are deliberately NOT in the public
+ * header, because a consumer-visible table bound is exactly the ABI hazard this
+ * registry replaced. Overriding them changes only this file, so a library and
+ * its consumers can never disagree about the layout.
+ *
+ * The table is never resized or rehashed, so a pointer handed out by
+ * akerr_name_for_status() stays valid for the life of the process. Entries are
+ * never removed, so probing needs no tombstones.
+ */
+#ifndef AKERR_STATUS_NAME_SLOTS
+#define AKERR_STATUS_NAME_SLOTS 4096
+#endif
+
+#ifndef AKERR_MAX_RESERVED_STATUS_RANGES
+#define AKERR_MAX_RESERVED_STATUS_RANGES 64
+#endif
+
+/* Probing masks with SLOTS-1, so the slot count must be a power of two. This is
+ * the C99-portable spelling of a static assertion (a negative array bound). */
+typedef char akerr_assert_name_slots_pow2[
+    (AKERR_STATUS_NAME_SLOTS > 0 &&
+     (AKERR_STATUS_NAME_SLOTS & (AKERR_STATUS_NAME_SLOTS - 1)) == 0) ? 1 : -1];
+
+/* Cap occupancy at 75% so linear probing always meets an empty slot. */
+#define AKERR_MAX_REGISTERED_STATUS_NAMES \
+    (AKERR_STATUS_NAME_SLOTS - (AKERR_STATUS_NAME_SLOTS / 4))
+
+#define AKERR_MAX_STATUS_RANGE_OWNER_LENGTH 64
+
+typedef struct
+{
+    int status;
+    int used;
+    char name[AKERR_MAX_ERROR_NAME_LENGTH];
+} akerr_StatusName;
+
+typedef struct
+{
+    int first;
+    int last;
+    char owner[AKERR_MAX_STATUS_RANGE_OWNER_LENGTH];
+} akerr_StatusRange;
+
+static akerr_StatusName akerr_status_names[AKERR_STATUS_NAME_SLOTS];
+static int akerr_status_name_count;
+static akerr_StatusRange akerr_status_ranges[AKERR_MAX_RESERVED_STATUS_RANGES];
+static int akerr_status_range_count;
 
 akerr_ErrorContext AKERR_ARRAY_ERROR[AKERR_MAX_ARRAY_ERROR];
 
+/*
+ * Bounded copy into a fixed buffer. Every argument is checked: this writes
+ * through a caller-supplied pointer for a caller-supplied length, so a NULL or
+ * a non-positive capacity here is a memory error waiting to happen, not
+ * something to absorb and return from quietly.
+ *
+ * Exported under the internal __akerr_ prefix rather than kept static so that
+ * tests/err_copy_string.c can reach these guards. Both in-library callers
+ * validate their arguments first, so nothing else can drive them.
+ */
+akerr_ErrorContext *__akerr_copy_string(char *destination, int capacity,
+					const char *source)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_NONZERO_RETURN(errctx, (destination == NULL || source == NULL),
+			AKERR_NULLPOINTER,
+			"__akerr_copy_string got a NULL %s",
+			destination == NULL ? "destination buffer" : "source string");
+    FAIL_NONZERO_RETURN(errctx, (capacity <= 0), AKERR_VALUE,
+			"__akerr_copy_string got a capacity of %d; a buffer must "
+			"have room for at least a terminator", capacity);
+
+    strncpy(destination, source, (size_t)capacity - 1);
+    destination[capacity - 1] = '\0';
+    SUCCEED_RETURN(errctx);
+}
+
+/*
+ * Compare against each element address rather than testing the address range.
+ * A range test also accepts pointers into the *interior* of an element, which
+ * would then be treated as the head of an akerr_ErrorContext and written
+ * through. Keep this an element-wise scan; it is not a missed optimization.
+ */
 int akerr_valid_error_address(akerr_ErrorContext *ptr)
 {
     // Is this within the memory region occupied by AKERR_ARRAY_ERROR?
-    return ((ptr >= &AKERR_ARRAY_ERROR[0]) && (ptr <= &AKERR_ARRAY_ERROR[AKERR_MAX_ARRAY_ERROR-1]));
+    if ( ptr == NULL ) {
+	return 1;
+    }
+    for ( int i = 0; i < AKERR_MAX_ARRAY_ERROR; i++ ) {
+	if ( ptr == &AKERR_ARRAY_ERROR[i] ) {
+	    return 1;
+	}
+    }
+    return 0;
 }
 
 void akerr_default_logger(const char *fmt, ...)
@@ -33,10 +125,48 @@ void akerr_default_logger(const char *fmt, ...)
 #endif
 }
 
+/*
+ * The library naming its own codes.
+ *
+ * akerr_init() returns void and runs before any consumer frame exists, so there
+ * is nothing to PASS an error to: this *is* the top of the stack. FINISH_NORETURN
+ * is the library's idiom for that position -- the same one main() uses -- so an
+ * unhandled failure prints its stack trace and goes to
+ * akerr_handler_unhandled_error, which terminates.
+ *
+ * That is fatal on purpose. The library can only fail to name its own status
+ * codes if the build is misconfigured -- a name table too small to hold even
+ * the library's own entries, or a reservation that did not take -- and the
+ * consequence of continuing is every later stack trace in the process printing
+ * "Unknown Error" for a code the library defines. That is a startup defect, and
+ * it is far cheaper to see it at init than to debug it from a degraded trace.
+ *
+ * The generated errno table calls this rather than registering names directly,
+ * so that all of this control flow lives here in one place.
+ */
+void __akerr_name_library_status(int status, const char *name)
+{
+    PREPARE_ERROR(errctx);
+
+    ATTEMPT {
+	CATCH(errctx, akerr_register_status_name(AKERR_LIBRARY_OWNER, status, name));
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } FINISH_NORETURN(errctx);
+}
+
+/*
+ * Idempotent. `inited` is set before any work so that the registry calls below
+ * -- and the public registry entry points, which all call akerr_init() so that
+ * a consumer reserving its range before anything else touches the library
+ * cannot have that reservation wiped by a later first-use of the pool -- see
+ * themselves as already initialized instead of recursing.
+ */
 void akerr_init()
 {
     static int inited = 0;
     if ( inited == 0 ) {
+	inited = 1;
 	for (int i = 0; i < AKERR_MAX_ARRAY_ERROR; i++ ) {
 	    memset((void *)&AKERR_ARRAY_ERROR[i], 0x00, sizeof(akerr_ErrorContext));
 	    AKERR_ARRAY_ERROR[i].arrayid = i;
@@ -49,26 +179,53 @@ void akerr_init()
 	    akerr_log_method = &akerr_default_logger;
 	}
 	akerr_handler_unhandled_error = &akerr_default_handler_unhandled_error;
-	memset((void *)&__AKERR_ERROR_NAMES[0], 0x00, ((AKERR_MAX_ERR_VALUE+1) * AKERR_MAX_ERROR_NAME_LENGTH));
+	memset((void *)&akerr_status_names[0], 0x00, sizeof(akerr_status_names));
+	memset((void *)&akerr_status_ranges[0], 0x00, sizeof(akerr_status_ranges));
+	akerr_status_name_count = 0;
+	akerr_status_range_count = 0;
 
-	akerr_name_for_status(AKERR_NULLPOINTER, "Null Pointer Error");
-	akerr_name_for_status(AKERR_OUTOFBOUNDS, "Out Of Bounds Error");
-	akerr_name_for_status(AKERR_API, "API Error");
-	akerr_name_for_status(AKERR_ATTRIBUTE, "Attribute Error");
-	akerr_name_for_status(AKERR_TYPE, "Type Error");
-	akerr_name_for_status(AKERR_KEY, "Key Error");
-	akerr_name_for_status(AKERR_HEAP, "Heap Error");
-	akerr_name_for_status(AKERR_INDEX, "Index Error");
-	akerr_name_for_status(AKERR_FORMAT, "Format Error");
-	akerr_name_for_status(AKERR_IO, "Input Output Error");
-	akerr_name_for_status(AKERR_REGISTRY, "Registry Error");
-	akerr_name_for_status(AKERR_VALUE, "Value Error");
-	akerr_name_for_status(AKERR_BEHAVIOR, "Behavior Error");
-	akerr_name_for_status(AKERR_RELATIONSHIP, "Relationship Error");
+	/* errno and AKERR_* values are the library-owned compatibility band.
+	 * This must precede every registration below: naming a status is only
+	 * permitted inside a reserved range. Terminal for the same reason as
+	 * __akerr_name_library_status(), and handled the same way: without this
+	 * band the library owns nothing, so none of the names below could
+	 * register either. */
+	PREPARE_ERROR(errctx);
+	ATTEMPT {
+	    CATCH(errctx, akerr_reserve_status_range(0, AKERR_RESERVED_STATUS_COUNT,
+						     AKERR_LIBRARY_OWNER));
+	} CLEANUP {
+	} PROCESS(errctx) {
+	} FINISH_NORETURN(errctx);
+
+	/* Every AKERR_* code gets a name; tests/err_error_names.c asserts the
+	 * list is exhaustive so a new code cannot be added without one. */
+	__akerr_name_library_status(AKERR_NULLPOINTER, "Null Pointer Error");
+	__akerr_name_library_status(AKERR_OUTOFBOUNDS, "Out Of Bounds Error");
+	__akerr_name_library_status(AKERR_API, "API Error");
+	__akerr_name_library_status(AKERR_ATTRIBUTE, "Attribute Error");
+	__akerr_name_library_status(AKERR_TYPE, "Type Error");
+	__akerr_name_library_status(AKERR_KEY, "Key Error");
+	__akerr_name_library_status(AKERR_INDEX, "Index Error");
+	__akerr_name_library_status(AKERR_FORMAT, "Format Error");
+	__akerr_name_library_status(AKERR_IO, "Input Output Error");
+	__akerr_name_library_status(AKERR_VALUE, "Value Error");
+	__akerr_name_library_status(AKERR_RELATIONSHIP, "Relationship Error");
+	__akerr_name_library_status(AKERR_EOF, "End Of File");
+	__akerr_name_library_status(AKERR_CIRCULAR_REFERENCE, "Circular Reference Error");
+	__akerr_name_library_status(AKERR_ITERATOR_BREAK, "Iterator Break");
+	__akerr_name_library_status(AKERR_NOT_IMPLEMENTED, "Not Implemented");
+	__akerr_name_library_status(AKERR_BADEXC, "Invalid akerr_ErrorContext");
+	__akerr_name_library_status(AKERR_STATUS_RANGE_OVERLAP, "Status Range Overlap");
+	__akerr_name_library_status(AKERR_STATUS_RANGE_FULL, "Status Range Table Full");
+	__akerr_name_library_status(AKERR_STATUS_RANGE_INVALID, "Invalid Status Range");
+	__akerr_name_library_status(AKERR_STATUS_NAME_UNRESERVED, "Unreserved Status Name");
+	__akerr_name_library_status(AKERR_STATUS_NAME_FOREIGN, "Foreign Status Name");
+	__akerr_name_library_status(AKERR_STATUS_NAME_FULL, "Status Name Registry Full");
+	__akerr_name_library_status(AKERR_STATUS_NAME_INVALID, "Invalid Status Name");
 #if (defined(AKERR_USE_STDLIB) && AKERR_USE_STDLIB == 1) || (!defined(AKERR_USE_STDLIB))
 	akerr_init_errno();
 #endif
-	inited = 1;
     }
 }
 
@@ -111,15 +268,245 @@ akerr_ErrorContext *akerr_release_error(akerr_ErrorContext *err)
 }
 
 
-// returns or sets the name for the given status.
-// Call with name = NULL to retrieve a status.
+/*
+ * Scatter the status across the table. Status values are typically dense runs
+ * (errno 1..N, then a library's block at its base), which linear probing on the
+ * raw value would pile into one cluster, so mix the bits first.
+ */
+static unsigned akerr_status_hash(int status)
+{
+    unsigned h = (unsigned)status;
+
+    h ^= h >> 16;
+    h *= 0x85ebca6bu;
+    h ^= h >> 13;
+    h *= 0xc2b2ae35u;
+    h ^= h >> 16;
+    return h & (unsigned)(AKERR_STATUS_NAME_SLOTS - 1);
+}
+
+/*
+ * Find the slot holding `status`. With create != 0, claim a free slot for it if
+ * it is not present yet. Returns NULL when the status is absent and either no
+ * slot was requested or the registry is full.
+ *
+ * The `& (AKERR_STATUS_NAME_SLOTS - 1)` below is load-bearing and fails
+ * silently: off by one in either direction and the probe indexes past
+ * akerr_status_names, writing into whatever BSS follows rather than crashing.
+ * A test that only counts how many names registered before the table filled
+ * cannot see that -- a probe sequence collapsed to two slots still registers
+ * "some" names. Any change to the probe sequence, the occupancy cap, or the
+ * power-of-two assumption needs a test that reads every entry back by its own
+ * distinct value; tests/err_maxval.c does.
+ */
+static akerr_StatusName *akerr_status_slot(int status, int create)
+{
+    unsigned slot = akerr_status_hash(status);
+
+    for ( int probe = 0; probe < AKERR_STATUS_NAME_SLOTS; probe++ ) {
+	akerr_StatusName *entry = &akerr_status_names[slot];
+
+	if ( entry->used == 0 ) {
+	    if ( create == 0 ||
+		 akerr_status_name_count >= AKERR_MAX_REGISTERED_STATUS_NAMES ) {
+		return NULL;
+	    }
+	    entry->used = 1;
+	    entry->status = status;
+	    entry->name[0] = '\0';
+	    akerr_status_name_count++;
+	    return entry;
+	}
+	if ( entry->status == status ) {
+	    return entry;
+	}
+	slot = (slot + 1u) & (unsigned)(AKERR_STATUS_NAME_SLOTS - 1);
+    }
+    /* Unreachable: occupancy is capped below the slot count, so the probe above
+     * always meets a free slot. Present so a future change to that cap cannot
+     * turn this into a runaway loop. */
+    return NULL;
+}
+
+/* The reservation covering `status`, or NULL if nobody has claimed it. */
+static akerr_StatusRange *akerr_range_for_status(int status)
+{
+    for ( int i = 0; i < akerr_status_range_count; i++ ) {
+	if ( status >= akerr_status_ranges[i].first &&
+	     status <= akerr_status_ranges[i].last ) {
+	    return &akerr_status_ranges[i];
+	}
+    }
+    return NULL;
+}
+
+/*
+ * Shared body of both registration entry points. A NULL owner means the caller
+ * did not identify itself (the legacy two-argument akerr_name_for_status path):
+ * the status must still lie inside *some* reservation, but we cannot check that
+ * it is the caller's. Every refusal raises an error -- a name that silently
+ * fails to register degrades into "Unknown Error" in stack traces, which is
+ * exactly the kind of quiet loss this registry exists to prevent -- so the
+ * message carries everything a caller needs to see in a stack trace.
+ */
+static akerr_ErrorContext AKERR_NOIGNORE *akerr_store_status_name(const char *owner,
+								  int status,
+								  const char *name)
+{
+    akerr_StatusRange *range;
+    akerr_StatusName *entry;
+    PREPARE_ERROR(errctx);
+
+    FAIL_NONZERO_RETURN(errctx, (name == NULL), AKERR_STATUS_NAME_INVALID,
+			"Refusing to name status %d for %s: the name is NULL",
+			status, owner == NULL ? "an unnamed caller" : owner);
+    FAIL_NONZERO_RETURN(errctx,
+			(owner != NULL && ( owner[0] == '\0' ||
+			 strlen(owner) >= AKERR_MAX_STATUS_RANGE_OWNER_LENGTH )),
+			AKERR_STATUS_NAME_INVALID,
+			"Refusing to name status %d (\"%s\"): the owner string "
+			"is empty or longer than %d characters",
+			status, name, AKERR_MAX_STATUS_RANGE_OWNER_LENGTH - 1);
+
+    range = akerr_range_for_status(status);
+    FAIL_ZERO_RETURN(errctx, range, AKERR_STATUS_NAME_UNRESERVED,
+		     "Refusing to name status %d (\"%s\") for %s: no reserved "
+		     "range contains it. Call akerr_reserve_status_range() first.",
+		     status, name, owner == NULL ? "an unnamed caller" : owner);
+    FAIL_NONZERO_RETURN(errctx,
+			(owner != NULL && strcmp(owner, range->owner) != 0),
+			AKERR_STATUS_NAME_FOREIGN,
+			"Refusing to name status %d (\"%s\") for %s: that status "
+			"is in range %d..%d owned by %s.",
+			status, name, owner,
+			range->first, range->last, range->owner);
+
+    entry = akerr_status_slot(status, 1);
+    FAIL_ZERO_RETURN(errctx, entry, AKERR_STATUS_NAME_FULL,
+		     "Status name registry is full (%d entries); dropping name "
+		     "\"%s\" for status %d. Rebuild libakerror with a larger "
+		     "AKERR_STATUS_NAME_SLOTS.",
+		     AKERR_MAX_REGISTERED_STATUS_NAMES, name, status);
+
+    PASS(errctx, __akerr_copy_string(entry->name, AKERR_MAX_ERROR_NAME_LENGTH, name));
+    SUCCEED_RETURN(errctx);
+}
+
+/*
+ * Register a name for a status inside a range the caller reserved. Both strings
+ * are checked here rather than only inside akerr_store_status_name(): the store
+ * accepts a NULL owner for the legacy akerr_name_for_status() path, so a NULL
+ * arriving through *this* entry point would be read as "caller did not identify
+ * itself" and skip the ownership check entirely.
+ */
+akerr_ErrorContext *akerr_register_status_name(const char *owner, int status, const char *name)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_NONZERO_RETURN(errctx, (owner == NULL), AKERR_STATUS_NAME_INVALID,
+			"Refusing to name status %d: the owner string is NULL. "
+			"Pass the same owner you reserved the range with.",
+			status);
+    FAIL_NONZERO_RETURN(errctx, (name == NULL), AKERR_STATUS_NAME_INVALID,
+			"Refusing to name status %d for %s: the name is NULL",
+			status, owner);
+    PASS(errctx, akerr_store_status_name(owner, status, name));
+    SUCCEED_RETURN(errctx);
+}
+
+/*
+ * Return or set a name. Status magnitude is unrelated to storage size.
+ *
+ * The set path is the legacy two-argument form. It returns a name, so it cannot
+ * hand an error back to its caller and cannot raise: it handles the refusal
+ * here, converting it to the "Unknown Error" sentinel the way any function that
+ * must return a value converts a caught error into one.
+ * akerr_register_status_name() is the form that raises.
+ *
+ * The lookup path (name == NULL) deliberately stays clear of all of this. FAIL
+ * calls it to render a status into a stack trace, so it must not itself need an
+ * error context.
+ */
 char *akerr_name_for_status(int status, char *name)
 {
-    if ( status > AKERR_MAX_ERR_VALUE ) {
+    akerr_StatusName *entry;
+
+    akerr_init();
+    if ( name != NULL ) {
+	PREPARE_ERROR(errctx);
+	int refused = 0;
+
+	ATTEMPT {
+	    CATCH(errctx, akerr_store_status_name(NULL, status, name));
+	} CLEANUP {
+	} PROCESS(errctx) {
+	} HANDLE_DEFAULT(errctx) {
+	    LOG_ERROR_WITH_MESSAGE(errctx, "** REFUSED STATUS NAME **");
+	    refused = 1;
+	} FINISH_NORETURN(errctx);
+
+	if ( refused != 0 ) {
+	    return "Unknown Error";
+	}
+    }
+    entry = akerr_status_slot(status, 0);
+    if ( entry == NULL ) {
 	return "Unknown Error";
     }
-    if ( name != NULL ) {
-	strncpy((char *)&__AKERR_ERROR_NAMES[status], name, AKERR_MAX_ERROR_NAME_LENGTH);	
-    }
-    return (char *)&__AKERR_ERROR_NAMES[status];
+    return entry->name;
+}
+
+/* Reserve an inclusive status interval and reject collisions. */
+akerr_ErrorContext *akerr_reserve_status_range(int first_status, int count, const char *owner)
+{
+    int last_status;
+    PREPARE_ERROR(errctx);
+
+    FAIL_NONZERO_RETURN(errctx,
+			(count <= 0 || owner == NULL || owner[0] == '\0' ||
+			 strlen(owner) >= AKERR_MAX_STATUS_RANGE_OWNER_LENGTH ||
+			 first_status > INT_MAX - (count - 1)),
+			AKERR_STATUS_RANGE_INVALID,
+			"Invalid status range reservation: %d status values from "
+			"%d for %s (count must be positive, the owner string "
+			"non-empty and shorter than %d characters, and the range "
+			"must not overflow int)",
+			count, first_status, owner == NULL ? "(null)" : owner,
+			AKERR_MAX_STATUS_RANGE_OWNER_LENGTH);
+    last_status = first_status + count - 1;
+
+    for ( int i = 0; i < akerr_status_range_count; i++ ) {
+	if ( first_status <= akerr_status_ranges[i].last &&
+	     last_status >= akerr_status_ranges[i].first ) {
+	    if ( first_status == akerr_status_ranges[i].first &&
+		 last_status == akerr_status_ranges[i].last &&
+		 strcmp(owner, akerr_status_ranges[i].owner) == 0 ) {
+		SUCCEED_RETURN(errctx);
+	    }
+	    FAIL_RETURN(errctx, AKERR_STATUS_RANGE_OVERLAP,
+			"Status range %d..%d requested by %s overlaps %d..%d "
+			"owned by %s",
+			first_status, last_status, owner,
+			akerr_status_ranges[i].first,
+			akerr_status_ranges[i].last,
+			akerr_status_ranges[i].owner);
+	}
+    }
+    FAIL_NONZERO_RETURN(errctx,
+			(akerr_status_range_count == AKERR_MAX_RESERVED_STATUS_RANGES),
+			AKERR_STATUS_RANGE_FULL,
+			"Status range table is full (%d ranges); refusing %d..%d "
+			"for %s.",
+			AKERR_MAX_RESERVED_STATUS_RANGES,
+			first_status, last_status, owner);
+
+    /* The owner copy is what commits the entry, so the count only advances
+     * once it has succeeded -- a half-written reservation would claim the
+     * range under an empty owner nobody could ever match. */
+    akerr_status_ranges[akerr_status_range_count].first = first_status;
+    akerr_status_ranges[akerr_status_range_count].last = last_status;
+    PASS(errctx, __akerr_copy_string(akerr_status_ranges[akerr_status_range_count].owner,
+				   AKERR_MAX_STATUS_RANGE_OWNER_LENGTH, owner));
+    akerr_status_range_count++;
+    SUCCEED_RETURN(errctx);
 }

test.sh

@@ -0,0 +1,5 @@
+ cmake -S . -B build
+ cmake --build build
+ ctest --test-dir build --output-on-failure --output-junit "$(pwd)/ctest-junit.xml"
+ python3 scripts/mutation_test.py --target src/error.c --junit mutation-junit.xml --threshold 65
+ python3 scripts/coverage.py --junit coverage-junit.xml --threshold 90 --branch-threshold 50

tests/MUTATION.md

@@ -0,0 +1,132 @@
+# Mutation testing
+
+The unit tests tell us the library works. **Mutation testing tells us the tests
+work** — that they would actually fail if the library were broken.
+
+`scripts/mutation_test.py` deliberately breaks the library in small ways
+("mutants"), one at a time, and runs the whole CTest suite against each broken
+copy:
+
+* if the tests **fail**, the mutant is **killed** — good, the suite caught it;
+* if the tests still **pass**, the mutant **survived** — a bug of that shape
+  would slip through, so it points at a missing test.
+
+The **mutation score** is `killed / (killed + survived)`. A surviving mutant is
+a to-do item: write a test that distinguishes the mutant from the original.
+
+## Running
+
+No third-party tools are required — just Python 3 and the normal
+cmake/ctest toolchain. The harness never touches your working tree; it copies
+the repo to a scratch directory and mutates the copy.
+
+```sh
+# Default: mutate src/error.c and include/akerror.tmpl.h
+scripts/mutation_test.py
+
+# Faster: just the C source
+scripts/mutation_test.py --target src/error.c
+
+# See what would run without building anything
+scripts/mutation_test.py --target src/error.c --list
+
+# Gate CI: exit non-zero if the score drops below 90%
+scripts/mutation_test.py --threshold 90
+```
+
+Via CMake (configures a build first if needed):
+
+```sh
+cmake --build build --target mutation
+```
+
+Useful flags: `--timeout SECONDS` (per-suite build+test cap; a mutant that
+hangs is counted as killed), `--keep` (retain the scratch copy for debugging),
+`--work DIR` (use a specific scratch directory), `--junit FILE` (write a JUnit
+XML report — surviving mutants appear as failing test cases).
+
+## CI reporting
+
+Both the unit tests and the mutation run emit JUnit XML that CI consumes:
+
+* `ctest --test-dir build --output-junit "$(pwd)/ctest-junit.xml"` — note the
+  absolute path; `--output-junit` otherwise resolves relative to the test dir.
+* `scripts/mutation_test.py --junit mutation-junit.xml`
+
+`.gitea/workflows/ci.yaml` runs both and feeds the XML to
+`mikepenz/action-junit-report` (with `if: always()`, so results publish even
+when a gate fails). The reporter runs with `annotate_only: true`: Gitea does not
+implement the Checks API the action uses to create a check run, so creating one
+404s (mikepenz/action-junit-report#23). `annotate_only` skips that call and the
+results surface via the job summary (`detailed_summary: true`) instead. The
+generated `*-junit.xml` files are git-ignored.
+
+## Mutation operators
+
+Each mutant changes exactly one location by one of:
+
+| Tag | Operator                       | Example                          |
+|-----|--------------------------------|----------------------------------|
+| ROR | relational operator            | `==` → `!=`, `<` → `<=`, `>=` → `>` |
+| LCR | logical connector              | `&&` → `\|\|`                     |
+| BCR | boolean constant               | `true` → `false`                 |
+| AOR | arithmetic / compound assign   | `+` → `-`, `+=` → `-=`           |
+| ICR | integer literal                | `0` → `1`, `1` → `0`             |
+| SDL | statement deletion             | `err->refcount += 1;` → *(removed)* |
+
+Preprocessor control lines, comments, and the block of error-code / buffer-size
+`#define`s are skipped: mutating those produces equivalent or uninteresting
+mutants that only add noise.
+
+## Interpreting survivors
+
+Not every survivor is a test gap — some mutants are **equivalent** (they don't
+change observable behaviour, e.g. resizing an internal scratch buffer). For each
+survivor, decide:
+
+1. **Real gap** → add or strengthen a test in `tests/` so the mutant is killed,
+   then re-run.
+2. **Equivalent mutant** → no test can catch it; leave a note. If a specific
+   line is a persistent source of equivalents, narrow the target with
+   `--target` or extend the skip rules in `scripts/mutation_test.py`.
+
+Re-run after adding tests and confirm the score went up.
+
+## Current status
+
+`src/error.c` scores ~77% (the CI gate is set to 65% for headroom). The
+remaining survivors are dominated by:
+
+* **Equivalent mutants** in `akerr_init`: deleting the `memset`/`NULL` setup of
+  file-scope statics (`AKERR_ARRAY_ERROR`, `__akerr_last_ditch`,
+  `__akerr_last_ignored`) changes nothing, because C already zero-initializes
+  objects with static storage duration. `int oldid = 0;` → `1` is likewise
+  dead: it is overwritten before use.
+* **Default logger / handler internals** (`vfprintf`, `va_end`, the
+  `errctx == NULL` branch, `exit(1)`): killing these needs a subprocess-based
+  test that captures a child's stderr and exit code, rather than the in-process
+  capturing logger the other tests use.
+* **Static assertions** (`akerr_assert_name_slots_pow2` and the occupancy cap
+  it guards): a mutated compile-time assertion that still compiles has no
+  runtime behavior to observe. Unkillable by construction — the assertion is
+  itself the test, and `tests/err_maxval.c` covers the runtime consequence.
+* **Hash and probe details** in `akerr_status_slot`: dropping one of the
+  multiply steps in `akerr_status_hash` leaves a worse but still correct hash,
+  and probing backwards (`slot - 1u`) is an equally valid sequence over a
+  power-of-two table. Both are behaviorally equivalent.
+* **The `capacity <= 0` guard** in `akerr_copy_string`, which is defensive: both
+  call sites pass a positive constant.
+
+Findings surfaced by mutation testing:
+
+* **Superseded:** status names now use a private sparse registry, so the old
+  public `AKERR_MAX_ERR_VALUE` ceiling and its consumer ABI mismatch no longer
+  exist. `tests/err_maxval.c` covers arbitrary `int` values and registry
+  exhaustion.
+* **Fixed:** the open-addressing probe mask (`& (AKERR_STATUS_NAME_SLOTS - 1)`)
+  could be mutated to `- 0` or `+ 1` — both of which index past the end of the
+  table — without any test noticing. `tests/err_maxval.c` only asserted that
+  *some* names registered before the table filled, which a collapsed probe
+  sequence still satisfies. It now requires a substantial number of entries and
+  reads every one of them back by its own distinct name, so a probe that
+  revisits slots fails on both counts.

tests/err_break_variants.c

@@ -0,0 +1,92 @@
+#include "akerror.h"
+#include "err_capture.h"
+
+/*
+ * Cover the conditional break/return failure macros:
+ *   FAIL_ZERO_BREAK / FAIL_NONZERO_BREAK / FAIL_BREAK   (inside ATTEMPT)
+ *   FAIL_ZERO_RETURN / FAIL_NONZERO_RETURN / FAIL_RETURN (direct return)
+ * Each is checked in both its failing and its non-failing (pass-through) state.
+ */
+
+akerr_ErrorContext *zero_break(int x)
+{
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	FAIL_ZERO_BREAK(e, x, AKERR_VALUE, "x was zero");
+    } CLEANUP {
+    } PROCESS(e) {
+    } FINISH(e, true);
+    SUCCEED_RETURN(e);
+}
+
+akerr_ErrorContext *nonzero_break(int x)
+{
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	FAIL_NONZERO_BREAK(e, x, AKERR_INDEX, "x was nonzero");
+    } CLEANUP {
+    } PROCESS(e) {
+    } FINISH(e, true);
+    SUCCEED_RETURN(e);
+}
+
+akerr_ErrorContext *always_break(void)
+{
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	FAIL_BREAK(e, AKERR_IO, "always");
+    } CLEANUP {
+    } PROCESS(e) {
+    } FINISH(e, true);
+    SUCCEED_RETURN(e);
+}
+
+akerr_ErrorContext *zero_return(int x)
+{
+    PREPARE_ERROR(e);
+    FAIL_ZERO_RETURN(e, x, AKERR_KEY, "x was zero");
+    SUCCEED_RETURN(e);
+}
+
+akerr_ErrorContext *nonzero_return(int x)
+{
+    PREPARE_ERROR(e);
+    FAIL_NONZERO_RETURN(e, x, AKERR_TYPE, "x was nonzero");
+    SUCCEED_RETURN(e);
+}
+
+int main(void)
+{
+    akerr_capture_install();
+    akerr_init();
+
+    akerr_ErrorContext *r;
+
+    r = zero_break(0);
+    AKERR_CHECK_STATUS(r, AKERR_VALUE);
+    r = akerr_release_error(r);
+    AKERR_CHECK(zero_break(7) == NULL);
+
+    r = nonzero_break(7);
+    AKERR_CHECK_STATUS(r, AKERR_INDEX);
+    r = akerr_release_error(r);
+    AKERR_CHECK(nonzero_break(0) == NULL);
+
+    r = always_break();
+    AKERR_CHECK_STATUS(r, AKERR_IO);
+    r = akerr_release_error(r);
+
+    r = zero_return(0);
+    AKERR_CHECK_STATUS(r, AKERR_KEY);
+    r = akerr_release_error(r);
+    AKERR_CHECK(zero_return(7) == NULL);
+
+    r = nonzero_return(7);
+    AKERR_CHECK_STATUS(r, AKERR_TYPE);
+    r = akerr_release_error(r);
+    AKERR_CHECK(nonzero_return(0) == NULL);
+
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+    fprintf(stderr, "err_break_variants ok\n");
+    return 0;
+}

tests/err_capture.h

@@ -0,0 +1,131 @@
+#ifndef AKERR_TEST_CAPTURE_H
+#define AKERR_TEST_CAPTURE_H
+
+/*
+ * Shared test helpers for libakerror.
+ *
+ * Installs a capturing implementation of akerr_log_method so tests can assert
+ * on the *content* of log/stacktrace output (messages, status codes, error
+ * names) instead of relying solely on process exit codes.
+ *
+ * Also provides AKERR_CHECK(), a NDEBUG-proof assertion that fails the test by
+ * returning non-zero from main() (unlike assert(), which is compiled out in
+ * release builds and would silently turn a test into a no-op).
+ */
+
+#include "akerror.h"
+#include <stdarg.h>
+#include <stdio.h>
+#include <string.h>
+
+#define AKERR_CAPTURE_BUFSZ 65536
+static char akerr_capture_buf[AKERR_CAPTURE_BUFSZ];
+static size_t akerr_capture_len = 0;
+
+static void __attribute__((unused)) akerr_capture_logger(const char *fmt, ...)
+{
+    va_list ap;
+    va_start(ap, fmt);
+    int n = vsnprintf(akerr_capture_buf + akerr_capture_len,
+		      AKERR_CAPTURE_BUFSZ - akerr_capture_len, fmt, ap);
+    va_end(ap);
+    if ( n > 0 ) {
+	akerr_capture_len += (size_t)n;
+	if ( akerr_capture_len >= AKERR_CAPTURE_BUFSZ ) {
+	    akerr_capture_len = AKERR_CAPTURE_BUFSZ - 1;
+	}
+    }
+}
+
+static void __attribute__((unused)) akerr_capture_reset(void)
+{
+    akerr_capture_len = 0;
+    akerr_capture_buf[0] = '\0';
+}
+
+/*
+ * Install the capturing logger. akerr_init() only assigns a default logger when
+ * akerr_log_method is NULL, and it is idempotent, so calling this either before
+ * or after the first PREPARE_ERROR keeps our logger in place.
+ */
+static void __attribute__((unused)) akerr_capture_install(void)
+{
+    akerr_capture_reset();
+    akerr_log_method = &akerr_capture_logger;
+}
+
+/* Count array slots currently checked out of the pool (refcount != 0). */
+static int __attribute__((unused)) akerr_slots_in_use(void)
+{
+    int n = 0;
+    for ( int i = 0; i < AKERR_MAX_ARRAY_ERROR; i++ ) {
+	if ( AKERR_ARRAY_ERROR[i].refcount != 0 ) {
+	    n++;
+	}
+    }
+    return n;
+}
+
+#define AKERR_CHECK(cond)					\
+    do {							\
+	if ( !(cond) ) {					\
+	    fprintf(stderr, "CHECK FAILED: %s at %s:%d\n",	\
+		    #cond, __FILE__, __LINE__);			\
+	    return 1;						\
+	}							\
+    } while ( 0 )
+
+#define AKERR_CHECK_STATUS(errctx, expected_status)			\
+    do {								\
+	AKERR_CHECK((errctx) != NULL);					\
+	AKERR_CHECK((errctx)->status == (expected_status));		\
+    } while ( 0 )
+
+/*
+ * Helpers for functions that report failure by returning akerr_ErrorContext *.
+ * Both release the context they consume, so a test that makes thousands of
+ * failing calls cannot exhaust the pool. AKERR_CHECK_RAISES keeps a copy of the
+ * message for AKERR_CHECK_MESSAGE_CONTAINS, since the context is gone by then.
+ */
+static char __attribute__((unused)) akerr_last_message[AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH];
+
+#define AKERR_CHECK_SUCCEEDS(expr)					\
+    do {								\
+	akerr_ErrorContext *__akerr_result = (expr);			\
+	if ( __akerr_result != NULL ) {					\
+	    fprintf(stderr, "UNEXPECTED ERROR from %s: %d (%s): %s"	\
+		    " at %s:%d\n", #expr, __akerr_result->status,	\
+		    akerr_name_for_status(__akerr_result->status, NULL),	\
+		    __akerr_result->message, __FILE__, __LINE__);	\
+	    RELEASE_ERROR(__akerr_result);				\
+	    return 1;							\
+	}								\
+    } while ( 0 )
+
+#define AKERR_CHECK_RAISES(expr, expected_status)			\
+    do {								\
+	akerr_ErrorContext *__akerr_result = (expr);			\
+	AKERR_CHECK(__akerr_result != NULL);				\
+	snprintf(akerr_last_message, sizeof(akerr_last_message), "%s",	\
+		 __akerr_result->message);				\
+	if ( __akerr_result->status != (expected_status) ) {		\
+	    fprintf(stderr, "WRONG STATUS from %s: got %d, want %s"	\
+		    " at %s:%d\n", #expr, __akerr_result->status,	\
+		    #expected_status, __FILE__, __LINE__);		\
+	    RELEASE_ERROR(__akerr_result);				\
+	    return 1;							\
+	}								\
+	RELEASE_ERROR(__akerr_result);					\
+	AKERR_CHECK(__akerr_result == NULL);				\
+    } while ( 0 )
+
+#define AKERR_CHECK_MESSAGE_CONTAINS(needle)			\
+    AKERR_CHECK(strstr(akerr_last_message, (needle)) != NULL)
+
+#define AKERR_CHECK_CONTAINS(needle)				\
+    AKERR_CHECK(strstr(akerr_capture_buf, (needle)) != NULL)
+
+#define AKERR_CHECK_NOT_CONTAINS(needle)			\
+    AKERR_CHECK(strstr(akerr_capture_buf, (needle)) == NULL)
+
+#endif // AKERR_TEST_CAPTURE_H

tests/err_catch.c

@@ -1,4 +1,5 @@
 #include "akerror.h"
+#include "err_capture.h"
 
 akerr_ErrorContext *func2(void)
 {
@@ -31,6 +32,11 @@ int main(void)
     } CLEANUP {
     } PROCESS(errctx) {
     } HANDLE(errctx, AKERR_NULLPOINTER) {
-      akerr_log_method("Caught exception");
+        AKERR_CHECK_STATUS(errctx, AKERR_NULLPOINTER);
+        akerr_log_method("Caught exception");
     } FINISH_NORETURN(errctx);
+
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+    fprintf(stderr, "err_catch ok\n");
+    return 0;
 }

tests/err_cleanup.c

@@ -1,4 +1,5 @@
 #include "akerror.h"
+#include "err_capture.h"
 
 int x;
 
@@ -34,10 +35,15 @@ int main(void)
     } CLEANUP {
     } PROCESS(errctx) {
     } HANDLE(errctx, AKERR_NULLPOINTER) {
+	AKERR_CHECK_STATUS(errctx, AKERR_NULLPOINTER);
 	if ( x == 0 ) {
-	    fprintf(stderr, "Cleanup works\n");
-	    return 0;
+	    akerr_log_method("Cleanup works\n");
+	} else {
+	    return 1;
 	}
-	return 1;
     } FINISH_NORETURN(errctx);
+
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+    fprintf(stderr, "err_cleanup ok\n");
+    return 0;
 }

tests/err_copy_string.c

@@ -0,0 +1,58 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <string.h>
+
+/*
+ * __akerr_copy_string() is the only place in the library that writes through a
+ * caller-supplied pointer for a caller-supplied length, so it validates every
+ * argument and raises rather than returning quietly. Both in-library callers
+ * check their arguments before calling it, so this test is what drives those
+ * guards -- without it they are unreachable code that no build ever exercises.
+ */
+
+int main(void)
+{
+    char buf[8];
+
+    akerr_capture_install();
+    akerr_init();
+
+    /* The happy path: bounded, and always terminated. */
+    memset(buf, 'x', sizeof(buf));
+    AKERR_CHECK_SUCCEEDS(__akerr_copy_string(buf, (int)sizeof(buf), "abc"));
+    AKERR_CHECK(strcmp(buf, "abc") == 0);
+
+    /* A source longer than the buffer is truncated, never overrun. */
+    memset(buf, 'x', sizeof(buf));
+    AKERR_CHECK_SUCCEEDS(__akerr_copy_string(buf, (int)sizeof(buf), "abcdefghijkl"));
+    AKERR_CHECK(strlen(buf) == sizeof(buf) - 1);
+    AKERR_CHECK(buf[sizeof(buf) - 1] == '\0');
+    AKERR_CHECK(strcmp(buf, "abcdefg") == 0);
+
+    /* A capacity of exactly one holds nothing but the terminator. */
+    memset(buf, 'x', sizeof(buf));
+    AKERR_CHECK_SUCCEEDS(__akerr_copy_string(buf, 1, "abc"));
+    AKERR_CHECK(buf[0] == '\0');
+    AKERR_CHECK(buf[1] == 'x');   /* and wrote nothing past its capacity */
+
+    /* NULL pointers raise instead of faulting, and the message says which. */
+    AKERR_CHECK_RAISES(__akerr_copy_string(NULL, (int)sizeof(buf), "abc"),
+		       AKERR_NULLPOINTER);
+    AKERR_CHECK_MESSAGE_CONTAINS("destination");
+    AKERR_CHECK_RAISES(__akerr_copy_string(buf, (int)sizeof(buf), NULL),
+		       AKERR_NULLPOINTER);
+    AKERR_CHECK_MESSAGE_CONTAINS("source");
+
+    /* A capacity with no room for a terminator is a value error, not a write. */
+    memset(buf, 'x', sizeof(buf));
+    AKERR_CHECK_RAISES(__akerr_copy_string(buf, 0, "abc"), AKERR_VALUE);
+    AKERR_CHECK_MESSAGE_CONTAINS("capacity of 0");
+    AKERR_CHECK_RAISES(__akerr_copy_string(buf, -1, "abc"), AKERR_VALUE);
+    AKERR_CHECK(buf[0] == 'x');   /* nothing was written */
+
+    /* Each refusal handed its context back to the pool. */
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    fprintf(stderr, "err_copy_string ok\n");
+    return 0;
+}

tests/err_custom_handler.c

@@ -0,0 +1,45 @@
+#include "akerror.h"
+#include "err_capture.h"
+
+/*
+ * The unhandled-error hook (akerr_handler_unhandled_error) is overridable.
+ * Install a non-fatal handler so an unhandled error can be asserted directly
+ * (status, invocation) instead of relying on process death / WILL_FAIL.
+ */
+
+static int custom_fired = 0;
+static int custom_status = 0;
+
+static void my_handler(akerr_ErrorContext *e)
+{
+    custom_fired = 1;
+    custom_status = (e != NULL) ? e->status : -1;
+    /* deliberately does NOT exit() */
+}
+
+akerr_ErrorContext *boom(void)
+{
+    PREPARE_ERROR(e);
+    FAIL_RETURN(e, AKERR_TYPE, "unhandled on purpose");
+}
+
+int main(void)
+{
+    akerr_capture_install();
+    akerr_init(); /* sets the default handler... */
+    akerr_handler_unhandled_error = &my_handler; /* ...which we then override */
+
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	CATCH(e, boom());
+    } CLEANUP {
+    } PROCESS(e) {
+	/* no HANDLE for AKERR_TYPE -> stays unhandled */
+    } FINISH_NORETURN(e);
+
+    AKERR_CHECK(custom_fired == 1);
+    AKERR_CHECK(custom_status == AKERR_TYPE);
+    AKERR_CHECK_CONTAINS("Unhandled Error");
+    fprintf(stderr, "err_custom_handler ok\n");
+    return 0;
+}

tests/err_errno.c

@@ -0,0 +1,48 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <errno.h>
+
+/*
+ * The library imports system errno codes and their descriptions at build time
+ * (scripts/generrno.sh -> akerr_init_errno). Verify:
+ *   - a system errno (EACCES) has a registered, non-empty name;
+ *   - an unregistered status returns the "Unknown Error" sentinel;
+ *   - a system errno can be raised, propagated and handled like any AKERR_* code.
+ */
+
+static int handled = 0;
+
+akerr_ErrorContext *boom(void)
+{
+    PREPARE_ERROR(e);
+    FAIL_RETURN(e, EACCES, "permission denied");
+}
+
+int main(void)
+{
+    akerr_capture_install();
+    akerr_init();
+
+    char *nm = akerr_name_for_status(EACCES, NULL);
+    AKERR_CHECK(nm != NULL);
+    AKERR_CHECK(nm[0] != '\0');
+    AKERR_CHECK(strcmp(nm, "Unknown Error") != 0);
+
+    AKERR_CHECK(strcmp(akerr_name_for_status(1000000, NULL),
+		       "Unknown Error") == 0);
+
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	CATCH(e, boom());
+    } CLEANUP {
+    } PROCESS(e) {
+    } HANDLE(e, EACCES) {
+	AKERR_CHECK_STATUS(e, EACCES);
+	handled = 1;
+    } FINISH_NORETURN(e);
+
+    AKERR_CHECK(handled == 1);
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+    fprintf(stderr, "err_errno ok (EACCES name: \"%s\")\n", nm);
+    return 0;
+}

tests/err_error_names.c

@@ -0,0 +1,83 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <string.h>
+
+/*
+ * akerr_init() registers a human-readable name for each library error code.
+ * Verify the names are actually installed (mutation testing showed the
+ * registration calls could be deleted without any test noticing).
+ *
+ * This list must stay exhaustive. AKERR_EOF, AKERR_ITERATOR_BREAK and
+ * AKERR_NOT_IMPLEMENTED were previously valid codes with no registered name, so
+ * they rendered as "Unknown Error" in every stack trace that carried them --
+ * the same class of silent gap that a too-small AKERR_MAX_ERR_VALUE used to
+ * cause. The sweep below walks the whole AKERR_* offset span so a newly added
+ * code without a name fails here rather than showing up in production traces.
+ */
+
+static const struct {
+    int code;
+    const char *name;
+} expected[] = {
+    { AKERR_NULLPOINTER,        "Null Pointer Error" },
+    { AKERR_OUTOFBOUNDS,        "Out Of Bounds Error" },
+    { AKERR_API,                "API Error" },
+    { AKERR_ATTRIBUTE,          "Attribute Error" },
+    { AKERR_TYPE,               "Type Error" },
+    { AKERR_KEY,                "Key Error" },
+    { AKERR_INDEX,              "Index Error" },
+    { AKERR_FORMAT,             "Format Error" },
+    { AKERR_IO,                 "Input Output Error" },
+    { AKERR_VALUE,              "Value Error" },
+    { AKERR_RELATIONSHIP,       "Relationship Error" },
+    { AKERR_EOF,                "End Of File" },
+    { AKERR_CIRCULAR_REFERENCE, "Circular Reference Error" },
+    { AKERR_ITERATOR_BREAK,     "Iterator Break" },
+    { AKERR_NOT_IMPLEMENTED,    "Not Implemented" },
+    { AKERR_BADEXC,             "Invalid akerr_ErrorContext" },
+    { AKERR_STATUS_RANGE_OVERLAP,   "Status Range Overlap" },
+    { AKERR_STATUS_RANGE_FULL,      "Status Range Table Full" },
+    { AKERR_STATUS_RANGE_INVALID,   "Invalid Status Range" },
+    { AKERR_STATUS_NAME_UNRESERVED, "Unreserved Status Name" },
+    { AKERR_STATUS_NAME_FOREIGN,    "Foreign Status Name" },
+    { AKERR_STATUS_NAME_FULL,       "Status Name Registry Full" },
+    { AKERR_STATUS_NAME_INVALID,    "Invalid Status Name" },
+};
+
+int main(void)
+{
+    akerr_init();
+
+    for ( unsigned i = 0; i < sizeof(expected) / sizeof(expected[0]); i++ ) {
+        char *nm = akerr_name_for_status(expected[i].code, NULL);
+        AKERR_CHECK(nm != NULL);
+        AKERR_CHECK(strcmp(nm, expected[i].name) == 0);
+    }
+
+    /*
+     * Every value in the library's own offset span must resolve to a real name.
+     * AKERR_LAST_ERRNO_VALUE + 7 is the one deliberate hole (a removed code);
+     * anything else nameless is a code someone added without registering it.
+     */
+    for ( int offset = 1;
+	  offset <= AKERR_LAST_LIBRARY_STATUS - AKERR_LAST_ERRNO_VALUE;
+	  offset++ ) {
+        int code = AKERR_LAST_ERRNO_VALUE + offset;
+        char *nm = akerr_name_for_status(code, NULL);
+        if ( offset == 7 ) {
+            AKERR_CHECK(strcmp(nm, "Unknown Error") == 0);
+            continue;
+        }
+        if ( strcmp(nm, "Unknown Error") == 0 || nm[0] == '\0' ) {
+            fprintf(stderr, "AKERR_LAST_ERRNO_VALUE + %d (%d) has no name\n",
+                    offset, code);
+            return 1;
+        }
+    }
+
+    /* Every AKERR_* code must sit inside the band the library reserves. */
+    AKERR_CHECK(AKERR_LAST_LIBRARY_STATUS < AKERR_FIRST_CONSUMER_STATUS);
+
+    fprintf(stderr, "err_error_names ok\n");
+    return 0;
+}

tests/err_format_string.c

@@ -0,0 +1,34 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <string.h>
+
+/*
+ * FAIL records the source file and function names with snprintf. Those names
+ * must be passed as %s ARGUMENTS, not used as the format string -- otherwise a
+ * path containing a printf conversion (say a build directory with a '%') is
+ * interpreted as a format and reads nonexistent varargs (undefined behavior).
+ *
+ * #line lets us make __FILE__ contain a conversion specifier; the stored name
+ * must come back verbatim.
+ */
+
+#line 1 "pct%dname.c"
+akerr_ErrorContext *raise_with_percent_in_filename(void)
+{
+    PREPARE_ERROR(e);
+    FAIL_RETURN(e, AKERR_VALUE, "boom");
+}
+#line 22 "tests/err_format_string.c"
+
+int main(void)
+{
+    akerr_init();
+
+    akerr_ErrorContext *e = raise_with_percent_in_filename();
+    AKERR_CHECK(e != NULL);
+    AKERR_CHECK(strcmp(e->fname, "pct%dname.c") == 0);
+
+    e = akerr_release_error(e);
+    fprintf(stderr, "err_format_string ok\n");
+    return 0;
+}

tests/err_handle_default.c

@@ -0,0 +1,41 @@
+#include "akerror.h"
+#include "err_capture.h"
+
+/*
+ * An error whose status has no matching HANDLE block must fall through to
+ * HANDLE_DEFAULT, and the non-matching HANDLE body must not run.
+ */
+
+static int specific_fired = 0;
+static int default_fired = 0;
+static int default_status = 0;
+
+akerr_ErrorContext *boom(void)
+{
+    PREPARE_ERROR(e);
+    FAIL_RETURN(e, AKERR_TYPE, "wrong type");
+}
+
+int main(void)
+{
+    akerr_capture_install();
+
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	CATCH(e, boom());
+    } CLEANUP {
+    } PROCESS(e) {
+    } HANDLE(e, AKERR_KEY) {
+	specific_fired = 1; /* must NOT run: error is AKERR_TYPE */
+    } HANDLE_DEFAULT(e) {
+	default_fired = 1;
+	default_status = e->status;
+    } FINISH_NORETURN(e);
+
+    AKERR_CHECK(specific_fired == 0);
+    AKERR_CHECK(default_fired == 1);
+    AKERR_CHECK(default_status == AKERR_TYPE);
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+    fprintf(stderr, "err_handle_default ok\n");
+    return 0;
+}

tests/err_handle_dispatch.c

@@ -0,0 +1,45 @@
+#include "akerror.h"
+#include "err_capture.h"
+
+/*
+ * With several distinct HANDLE blocks, only the one matching the raised status
+ * may run. Raise the middle code and confirm exact dispatch.
+ */
+
+static int a_fired = 0;
+static int b_fired = 0;
+static int c_fired = 0;
+static int b_status = 0;
+
+akerr_ErrorContext *boom(void)
+{
+    PREPARE_ERROR(e);
+    FAIL_RETURN(e, AKERR_TYPE, "the middle one");
+}
+
+int main(void)
+{
+    akerr_capture_install();
+
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	CATCH(e, boom());
+    } CLEANUP {
+    } PROCESS(e) {
+    } HANDLE(e, AKERR_KEY) {
+	a_fired = 1;
+    } HANDLE(e, AKERR_TYPE) {
+	b_fired = 1;
+	b_status = e->status;
+    } HANDLE(e, AKERR_IO) {
+	c_fired = 1;
+    } FINISH_NORETURN(e);
+
+    AKERR_CHECK(a_fired == 0);
+    AKERR_CHECK(b_fired == 1);
+    AKERR_CHECK(b_status == AKERR_TYPE);
+    AKERR_CHECK(c_fired == 0);
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+    fprintf(stderr, "err_handle_dispatch ok\n");
+    return 0;
+}

tests/err_handle_group.c

@@ -0,0 +1,63 @@
+#include "akerror.h"
+#include "err_capture.h"
+
+/*
+ * HANDLE_GROUP lets several status codes share one handler body via
+ * case-fallthrough. The first member of the group uses HANDLE (which emits the
+ * leading break that terminates the previous case); each additional member
+ * uses HANDLE_GROUP; the shared body follows the last member. Verify that two
+ * different status codes both reach the shared body.
+ */
+
+static int group_fired = 0;
+static int other_fired = 0;
+static int group_status = 0;
+static int other_status = 0;
+
+akerr_ErrorContext *boom(int status)
+{
+    PREPARE_ERROR(e);
+    FAIL_RETURN(e, status, "boom %d", status);
+}
+
+akerr_ErrorContext *run(int status)
+{
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	CATCH(e, boom(status));
+    } CLEANUP {
+    } PROCESS(e) {
+    } HANDLE(e, AKERR_KEY)
+	  HANDLE_GROUP(e, AKERR_INDEX) {
+	group_fired++;
+	group_status = e->status;
+    } HANDLE(e, AKERR_IO) {
+	other_fired++;
+	other_status = e->status;
+    } FINISH(e, false);
+    return e;
+}
+
+int main(void)
+{
+    akerr_capture_install();
+
+    run(AKERR_KEY);
+    AKERR_CHECK(group_fired == 1);
+    AKERR_CHECK(group_status == AKERR_KEY);
+    AKERR_CHECK(other_fired == 0);
+
+    run(AKERR_INDEX);
+    AKERR_CHECK(group_fired == 2);
+    AKERR_CHECK(group_status == AKERR_INDEX);
+    AKERR_CHECK(other_fired == 0);
+
+    run(AKERR_IO);
+    AKERR_CHECK(group_fired == 2);
+    AKERR_CHECK(other_fired == 1);
+    AKERR_CHECK(other_status == AKERR_IO);
+
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+    fprintf(stderr, "err_handle_group ok\n");
+    return 0;
+}

tests/err_ignore.c

@@ -0,0 +1,34 @@
+#include "akerror.h"
+#include "err_capture.h"
+
+/*
+ * IGNORE deliberately swallows an error: it records the context in
+ * __akerr_last_ignored, logs it with an "IGNORED ERROR" marker, and lets
+ * execution continue.
+ */
+
+akerr_ErrorContext *boom(void)
+{
+    PREPARE_ERROR(e);
+    FAIL_RETURN(e, AKERR_VALUE, "this error is ignored on purpose");
+}
+
+int main(void)
+{
+    akerr_capture_install();
+
+    int reached_after_ignore = 0;
+    PREPARE_ERROR(e);
+    (void)e;
+
+    IGNORE(boom());
+    reached_after_ignore = 1;
+
+    AKERR_CHECK(__akerr_last_ignored != NULL);
+    AKERR_CHECK(__akerr_last_ignored->status == AKERR_VALUE);
+    AKERR_CHECK(reached_after_ignore == 1);
+    AKERR_CHECK_CONTAINS("IGNORED ERROR");
+    AKERR_CHECK_CONTAINS("this error is ignored on purpose");
+    fprintf(stderr, "err_ignore ok\n");
+    return 0;
+}

tests/err_library_status_fatal.c

@@ -0,0 +1,31 @@
+#include "akerror.h"
+#include "err_capture.h"
+
+/*
+ * The library naming one of its own codes is not allowed to fail quietly.
+ * __akerr_name_library_status() runs from akerr_init() and from the generated
+ * errno table, neither of which has a caller to raise into, so a refusal there
+ * goes through FINISH_NORETURN: stack trace, then akerr_handler_unhandled_error,
+ * which terminates the process.
+ *
+ * In a correct build that can only happen with a name table too small to hold
+ * the library's own entries, which no test can configure (the slot count is
+ * PRIVATE to the library target). Calling the helper for a status the library
+ * does not own reaches the same refusal, so this test covers the terminal path
+ * itself.
+ *
+ * Registered in AKERR_WILL_FAIL_TESTS: reaching the end of main() means the
+ * failure was swallowed, and that is the bug this test exists to catch.
+ */
+
+int main(void)
+{
+    akerr_init();
+
+    /* Nobody has reserved 9999, so this registration is refused. */
+    __akerr_name_library_status(9999, "Not The Library's To Name");
+
+    fprintf(stderr, "err_library_status_fatal: a refused library-status "
+		    "registration did NOT terminate\n");
+    return 0;
+}

tests/err_maxval.c

@@ -0,0 +1,165 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <limits.h>
+#include <string.h>
+
+/*
+ * Status magnitude is no longer coupled to a public array bound: any int is a
+ * legal status, and storage is a private sparse registry. What bounds the
+ * registry now is its *capacity*, not the value of the largest code.
+ *
+ * Covers: arbitrary int status values, name truncation, range reservation
+ * semantics (overlap, idempotency, endpoints, validation, overflow), and both
+ * capacity limits -- the range table and the name table -- each of which must
+ * raise rather than dropping the registration quietly.
+ *
+ * Every refusal is an error context the caller owns, so each check below also
+ * asserts the context returns to the pool; a leak here would exhaust the
+ * 128-slot pool long before these loops finish.
+ */
+
+int main(void)
+{
+    akerr_capture_install();
+    akerr_init();
+
+    /* Any int is a legal status, at either extreme of the range. */
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(INT_MIN, 1, "min-owner"));
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(INT_MAX, 1, "max-owner"));
+    AKERR_CHECK_SUCCEEDS(akerr_register_status_name("max-owner", INT_MAX, "Maximum Status"));
+    AKERR_CHECK_SUCCEEDS(akerr_register_status_name("min-owner", INT_MIN, "Minimum Status"));
+    AKERR_CHECK(strcmp(akerr_name_for_status(INT_MAX, NULL), "Maximum Status") == 0);
+    AKERR_CHECK(strcmp(akerr_name_for_status(INT_MIN, NULL), "Minimum Status") == 0);
+
+    /* A name longer than the buffer is truncated and always terminated. */
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(1000000, 1, "trunc"));
+    const char *long_name =
+	"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-extra";
+    AKERR_CHECK_SUCCEEDS(akerr_register_status_name("trunc", 1000000, long_name));
+    char *stored = akerr_name_for_status(1000000, NULL);
+    AKERR_CHECK(strlen(stored) == AKERR_MAX_ERROR_NAME_LENGTH - 1);
+    AKERR_CHECK(stored[AKERR_MAX_ERROR_NAME_LENGTH - 1] == '\0');
+
+    /* Reservation: overlap detection, and idempotency for an exact repeat. */
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(256, 16, "component-a"));
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(256, 16, "component-a"));
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(260, 2, "component-b"),
+		       AKERR_STATUS_RANGE_OVERLAP);
+    AKERR_CHECK_MESSAGE_CONTAINS("component-a");
+
+    /* The library's own 0..255 band is reserved and cannot be encroached on. */
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(255, 1, "component-b"),
+		       AKERR_STATUS_RANGE_OVERLAP);
+    AKERR_CHECK_MESSAGE_CONTAINS(AKERR_LIBRARY_OWNER);
+    /* An exact repeat by the owner is still a no-op. */
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(0, AKERR_RESERVED_STATUS_COUNT,
+						    AKERR_LIBRARY_OWNER));
+
+    /* Argument validation. */
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(INT_MAX, 2, "overflow"),
+		       AKERR_STATUS_RANGE_INVALID);
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(300, 0, "empty"),
+		       AKERR_STATUS_RANGE_INVALID);
+    AKERR_CHECK_MESSAGE_CONTAINS("empty");   /* the message names the caller */
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(300, -1, "negative"),
+		       AKERR_STATUS_RANGE_INVALID);
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(300, 1, NULL),
+		       AKERR_STATUS_RANGE_INVALID);
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(300, 1, ""),
+		       AKERR_STATUS_RANGE_INVALID);
+
+    /* Owner strings: 63 chars fit, 64 do not, and neither does anything past. */
+    char owner63[AKERR_MAX_ERROR_NAME_LENGTH];
+    char owner64[AKERR_MAX_ERROR_NAME_LENGTH + 1];
+    char owner70[AKERR_MAX_ERROR_NAME_LENGTH + 7];
+    memset(owner63, 'a', sizeof(owner63) - 1);
+    owner63[sizeof(owner63) - 1] = '\0';
+    memset(owner64, 'b', sizeof(owner64) - 1);
+    owner64[sizeof(owner64) - 1] = '\0';
+    memset(owner70, 'c', sizeof(owner70) - 1);
+    owner70[sizeof(owner70) - 1] = '\0';
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(400, 1, owner63));
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(401, 1, owner64),
+		       AKERR_STATUS_RANGE_INVALID);
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(402, 1, owner70),
+		       AKERR_STATUS_RANGE_INVALID);
+
+    /* Partial overlaps at either endpoint, and a same-range different owner. */
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(500, 2, "endpoint"));
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(499, 2, "left"),
+		       AKERR_STATUS_RANGE_OVERLAP);
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(500, 1, "endpoint"),
+		       AKERR_STATUS_RANGE_OVERLAP);   /* subset, not an exact repeat */
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(501, 1, "endpoint"),
+		       AKERR_STATUS_RANGE_OVERLAP);
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(500, 2, "other"),
+		       AKERR_STATUS_RANGE_OVERLAP);   /* same range, wrong owner */
+
+    /* Claim room for the name-exhaustion sweep before filling the range table. */
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(2000000, 100000, "fill"));
+
+    /*
+     * Range table capacity. The limit is private to src/error.c on purpose, so
+     * discover it by filling rather than by hardcoding it here.
+     */
+    int ranges_added = 0;
+    akerr_ErrorContext *range_err = NULL;
+    for ( int i = 0; i < 100000; i++ ) {
+	range_err = akerr_reserve_status_range(1000 + (i * 2), 1, "pad");
+	if ( range_err != NULL ) {
+	    break;
+	}
+	ranges_added++;
+    }
+    AKERR_CHECK(ranges_added > 0);
+    AKERR_CHECK_STATUS(range_err, AKERR_STATUS_RANGE_FULL);
+    AKERR_CHECK(strstr(range_err->message, "range table is full") != NULL);
+    RELEASE_ERROR(range_err);
+    AKERR_CHECK(range_err == NULL);
+
+    /*
+     * Name table capacity. Exhaustion must be reported, not silent: a dropped
+     * name degrades every future stack trace for that code to "Unknown Error".
+     */
+    int full_at = -1;
+    for ( int i = 0; i < 100000; i++ ) {
+	char name[32];
+	snprintf(name, sizeof(name), "Filled %d", i);
+	akerr_ErrorContext *name_err =
+	    akerr_register_status_name("fill", 2000000 + i, name);
+	if ( name_err != NULL ) {
+	    AKERR_CHECK_STATUS(name_err, AKERR_STATUS_NAME_FULL);
+	    AKERR_CHECK(strstr(name_err->message, "registry is full") != NULL);
+	    AKERR_CHECK(strstr(name_err->message, "AKERR_STATUS_NAME_SLOTS") != NULL);
+	    RELEASE_ERROR(name_err);
+	    AKERR_CHECK(name_err == NULL);
+	    full_at = i;
+	    break;
+	}
+    }
+
+    /*
+     * The table must actually hold everything it accepted. A probe sequence
+     * that revisits slots instead of walking the table -- e.g. masking with
+     * SLOTS rather than SLOTS-1 -- both collapses the usable capacity and
+     * loses earlier entries, and each check below catches it independently.
+     * The floor assumes at least the default table size (4096 slots).
+     */
+    AKERR_CHECK(full_at > 256);
+    for ( int i = 0; i < full_at; i++ ) {
+	char expected[32];
+	snprintf(expected, sizeof(expected), "Filled %d", i);
+	AKERR_CHECK(strcmp(akerr_name_for_status(2000000 + i, NULL), expected) == 0);
+    }
+
+    /* A dropped name reads back as the sentinel, and earlier ones survive. */
+    AKERR_CHECK(strcmp(akerr_name_for_status(2000000 + full_at, NULL),
+		       "Unknown Error") == 0);
+    AKERR_CHECK(strcmp(akerr_name_for_status(INT_MIN, NULL), "Minimum Status") == 0);
+
+    /* Thousands of refusals later, every context went back to the pool. */
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    fprintf(stderr, "err_maxval ok (%d consumer names before full)\n", full_at);
+    return 0;
+}

tests/err_name_bounds.c

@@ -0,0 +1,24 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <string.h>
+
+/* Unregistered status values return the sentinel regardless of magnitude. */
+
+int main(void)
+{
+    akerr_init();
+
+    /* Below range. */
+    AKERR_CHECK(strcmp(akerr_name_for_status(-1, NULL), "Unknown Error") == 0);
+    AKERR_CHECK(strcmp(akerr_name_for_status(-9999, NULL), "Unknown Error") == 0);
+
+    AKERR_CHECK(strcmp(akerr_name_for_status(1000000, NULL),
+		       "Unknown Error") == 0);
+
+    /* A valid code must still resolve to its real name. */
+    AKERR_CHECK(strcmp(akerr_name_for_status(AKERR_NULLPOINTER, NULL),
+		       "Null Pointer Error") == 0);
+
+    fprintf(stderr, "err_name_bounds ok\n");
+    return 0;
+}

tests/err_name_ownership.c

@@ -0,0 +1,126 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <string.h>
+
+/*
+ * Reserving a range used to be pure bookkeeping: akerr_name_for_status() would
+ * name any status for any caller, so two components could still register names
+ * for the same code -- and HANDLE the same code -- with nothing detecting it.
+ * Reservation only caught components that both opted in AND declared ranges
+ * that happened to overlap.
+ *
+ * Naming a status is now permitted only inside a reservation:
+ *   - akerr_register_status_name() requires the range to belong to the caller,
+ *     and raises AKERR_STATUS_NAME_* when it does not;
+ *   - the legacy two-argument akerr_name_for_status() set path cannot identify
+ *     its caller, so it can only require that *some* reservation covers the
+ *     status -- still enough to stop a code nobody claimed. It returns a name
+ *     rather than an error context, so its refusals are logged instead.
+ * Either way the refusal is visible, because a name that fails to register
+ * degrades the status to "Unknown Error" in every later stack trace.
+ */
+
+int main(void)
+{
+    akerr_capture_install();
+    akerr_init();
+
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(256, 16, "lib-a"));
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(512, 16, "lib-b"));
+
+    /* The owner of a range may name statuses inside it. */
+    AKERR_CHECK_SUCCEEDS(akerr_register_status_name("lib-a", 256, "A Parse Error"));
+    AKERR_CHECK_SUCCEEDS(akerr_register_status_name("lib-a", 271, "A Last Error"));
+    AKERR_CHECK(strcmp(akerr_name_for_status(256, NULL), "A Parse Error") == 0);
+
+    /* Naming another owner's status is refused and names the real owner. */
+    AKERR_CHECK_RAISES(akerr_register_status_name("lib-b", 256, "B Hijack"),
+		       AKERR_STATUS_NAME_FOREIGN);
+    AKERR_CHECK_MESSAGE_CONTAINS("lib-a");
+    AKERR_CHECK_MESSAGE_CONTAINS("lib-b");
+    AKERR_CHECK(strcmp(akerr_name_for_status(256, NULL), "A Parse Error") == 0);
+
+    /* Including the library's own reserved band. */
+    AKERR_CHECK_RAISES(akerr_register_status_name("lib-b", AKERR_VALUE, "B Value"),
+		       AKERR_STATUS_NAME_FOREIGN);
+    AKERR_CHECK_MESSAGE_CONTAINS(AKERR_LIBRARY_OWNER);
+    AKERR_CHECK(strcmp(akerr_name_for_status(AKERR_VALUE, NULL), "Value Error") == 0);
+
+    /* A status nobody reserved cannot be named through either entry point. */
+    AKERR_CHECK_RAISES(akerr_register_status_name("lib-a", 9999, "Unclaimed"),
+		       AKERR_STATUS_NAME_UNRESERVED);
+    AKERR_CHECK_MESSAGE_CONTAINS("no reserved range");
+    AKERR_CHECK(strcmp(akerr_name_for_status(9999, NULL), "Unknown Error") == 0);
+
+    /* The legacy path has no caller to raise into, so it logs the refusal.
+     * It also cannot name the caller, and must say so rather than printing a
+     * stray owner. */
+    akerr_capture_reset();
+    AKERR_CHECK(strcmp(akerr_name_for_status(9999, "Unclaimed Legacy"),
+		       "Unknown Error") == 0);
+    AKERR_CHECK_CONTAINS("no reserved range");
+    AKERR_CHECK_CONTAINS("an unnamed caller");
+    AKERR_CHECK_CONTAINS("REFUSED STATUS NAME");
+    AKERR_CHECK(strcmp(akerr_name_for_status(9999, NULL), "Unknown Error") == 0);
+    /* ... and hands the context it raised back to the pool. */
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    /* Boundaries: just outside lib-a's range is not lib-a's to name. */
+    AKERR_CHECK_RAISES(akerr_register_status_name("lib-a", 255, "Below"),
+		       AKERR_STATUS_NAME_FOREIGN);
+    AKERR_CHECK_RAISES(akerr_register_status_name("lib-a", 272, "Above"),
+		       AKERR_STATUS_NAME_UNRESERVED);
+
+    /* The legacy set path still works inside any reservation. */
+    AKERR_CHECK(strcmp(akerr_name_for_status(513, "B Legacy"), "B Legacy") == 0);
+    AKERR_CHECK(strcmp(akerr_name_for_status(513, NULL), "B Legacy") == 0);
+
+    /* Re-registering your own status overwrites the name. */
+    AKERR_CHECK_SUCCEEDS(akerr_register_status_name("lib-a", 256, "A Renamed"));
+    AKERR_CHECK(strcmp(akerr_name_for_status(256, NULL), "A Renamed") == 0);
+
+    /*
+     * Argument validation. Each message must identify the caller it refused,
+     * since that message is the whole report a consumer gets.
+     */
+    AKERR_CHECK_RAISES(akerr_register_status_name(NULL, 257, "No Owner"),
+		       AKERR_STATUS_NAME_INVALID);
+    AKERR_CHECK_MESSAGE_CONTAINS("257");
+    AKERR_CHECK_RAISES(akerr_register_status_name("", 257, "Empty Owner"),
+		       AKERR_STATUS_NAME_INVALID);
+    AKERR_CHECK_MESSAGE_CONTAINS("Empty Owner");
+    AKERR_CHECK_RAISES(akerr_register_status_name("lib-a", 257, NULL),
+		       AKERR_STATUS_NAME_INVALID);
+    AKERR_CHECK_MESSAGE_CONTAINS("lib-a");
+
+    /* Over-long owner strings: 63 characters fit, 64 and beyond do not. */
+    char owner63[64];
+    char owner64[65];
+    char owner70[71];
+    memset(owner63, 'a', sizeof(owner63) - 1);
+    owner63[sizeof(owner63) - 1] = '\0';
+    memset(owner64, 'b', sizeof(owner64) - 1);
+    owner64[sizeof(owner64) - 1] = '\0';
+    memset(owner70, 'c', sizeof(owner70) - 1);
+    owner70[sizeof(owner70) - 1] = '\0';
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(600, 1, owner63));
+    AKERR_CHECK_SUCCEEDS(akerr_register_status_name(owner63, 600, "Long Owner"));
+    AKERR_CHECK_RAISES(akerr_register_status_name(owner64, 600, "Too Long"),
+		       AKERR_STATUS_NAME_INVALID);
+    AKERR_CHECK_MESSAGE_CONTAINS("63");
+    AKERR_CHECK_RAISES(akerr_register_status_name(owner70, 600, "Far Too Long"),
+		       AKERR_STATUS_NAME_INVALID);
+    AKERR_CHECK(strcmp(akerr_name_for_status(600, NULL), "Long Owner") == 0);
+
+    /* A refused registration must not consume a slot or leave a partial entry. */
+    AKERR_CHECK(strcmp(akerr_name_for_status(257, NULL), "Unknown Error") == 0);
+
+    /* Lookup is unaffected by ownership -- anyone may read any name. */
+    AKERR_CHECK(strcmp(akerr_name_for_status(271, NULL), "A Last Error") == 0);
+
+    /* Every refusal above released its context. */
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    fprintf(stderr, "err_name_ownership ok\n");
+    return 0;
+}

tests/err_pass.c

@@ -0,0 +1,47 @@
+#include "akerror.h"
+#include "err_capture.h"
+
+/*
+ * PASS bubbles an error up to the caller without a local ATTEMPT/PROCESS block:
+ * if the wrapped call fails, PASS returns the context from the current function.
+ * Verify the error reaches main and that the code after PASS is skipped on
+ * failure.
+ */
+
+static int reached_after_pass = 0;
+
+akerr_ErrorContext *inner(void)
+{
+    PREPARE_ERROR(e);
+    FAIL_RETURN(e, AKERR_IO, "inner failed");
+}
+
+akerr_ErrorContext *outer(void)
+{
+    PREPARE_ERROR(e);
+    PASS(e, inner());
+    reached_after_pass = 1; /* must NOT run: PASS returned already */
+    SUCCEED_RETURN(e);
+}
+
+int main(void)
+{
+    akerr_capture_install();
+
+    int handled = 0;
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	CATCH(e, outer());
+    } CLEANUP {
+    } PROCESS(e) {
+    } HANDLE(e, AKERR_IO) {
+	AKERR_CHECK_STATUS(e, AKERR_IO);
+	handled = 1;
+    } FINISH_NORETURN(e);
+
+    AKERR_CHECK(handled == 1);
+    AKERR_CHECK(reached_after_pass == 0);
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+    fprintf(stderr, "err_pass ok\n");
+    return 0;
+}

tests/err_pool_exhaust.c

@@ -0,0 +1,39 @@
+#include "akerror.h"
+#include "err_capture.h"
+
+/*
+ * The error pool is a fixed array of AKERR_MAX_ARRAY_ERROR slots. When every
+ * slot is checked out, akerr_next_error() must return NULL rather than run off
+ * the end of the array; and it must always hand back the lowest free slot.
+ * Mutation testing showed both the terminating "return NULL" and the scan
+ * bounds could be broken without any test noticing.
+ */
+
+int main(void)
+{
+    akerr_init();
+
+    akerr_ErrorContext *slots[AKERR_MAX_ARRAY_ERROR];
+
+    /* Check out every slot. */
+    for ( int i = 0; i < AKERR_MAX_ARRAY_ERROR; i++ ) {
+        slots[i] = akerr_next_error();
+        AKERR_CHECK(slots[i] != NULL);
+        slots[i]->refcount = 1;
+    }
+
+    /* Pool is fully exhausted: the next request must fail cleanly. */
+    AKERR_CHECK(akerr_next_error() == NULL);
+
+    /* Free exactly the first slot; the scan must find and return it. */
+    slots[0]->refcount = 0;
+    AKERR_CHECK(akerr_next_error() == slots[0]);
+
+    /* Tidy up. */
+    for ( int i = 0; i < AKERR_MAX_ARRAY_ERROR; i++ ) {
+        slots[i]->refcount = 0;
+    }
+
+    fprintf(stderr, "err_pool_exhaust ok\n");
+    return 0;
+}

tests/err_pool_refcount.c

@@ -0,0 +1,60 @@
+#include "akerror.h"
+#include "err_capture.h"
+
+/*
+ * Pool-hygiene regression test. The error pool is a fixed 128-slot static
+ * array; a single leaked reference per error would silently exhaust it. Run a
+ * large number of full raise -> catch -> handle cycles and confirm every slot
+ * is returned to the pool (refcount 0) and the pool can still hand out
+ * contexts afterwards.
+ */
+
+#define ITERATIONS 100000
+
+static int handled_status = 0;
+
+akerr_ErrorContext *boom(void)
+{
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	FAIL(e, AKERR_VALUE, "boom %d", 1);
+    } CLEANUP {
+    } PROCESS(e) {
+    } FINISH(e, true);
+    SUCCEED_RETURN(e);
+}
+
+/* One full raise -> catch -> handle cycle. Returns NULL (context released). */
+akerr_ErrorContext *one_cycle(void)
+{
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	CATCH(e, boom());
+    } CLEANUP {
+    } PROCESS(e) {
+    } HANDLE(e, AKERR_VALUE) {
+	handled_status = e->status;
+    } FINISH(e, false);
+    return e;
+}
+
+int main(void)
+{
+    akerr_capture_install();
+    akerr_init();
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    for ( int iter = 0; iter < ITERATIONS; iter++ ) {
+	handled_status = 0;
+	(void)one_cycle();
+	AKERR_CHECK(handled_status == AKERR_VALUE);
+    }
+
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    akerr_ErrorContext *probe = akerr_next_error();
+    AKERR_CHECK(probe != NULL);
+
+    fprintf(stderr, "err_pool_refcount ok (%d cycles, 0 leaked)\n", ITERATIONS);
+    return 0;
+}

tests/err_refcount_double_fail.c

@@ -0,0 +1,56 @@
+#include "akerror.h"
+#include "err_capture.h"
+
+/*
+ * Regression test for the refcount leak: ENSURE_ERROR_READY must increment
+ * refcount only when it *acquires* a fresh context, not on every FAIL/SUCCEED.
+ * A function that calls FAIL more than once on the same context and then
+ * propagates used to arrive at the caller with refcount 2; the caller released
+ * once, leaking the slot. After enough leaks the pool is exhausted and the
+ * library exit(1)s.
+ */
+
+static int handled_status = 0;
+
+akerr_ErrorContext *validate(void)
+{
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	FAIL(e, AKERR_VALUE, "condition 1 failed");   /* acquires the context   */
+	FAIL(e, AKERR_KEY, "condition 2 failed");     /* must NOT re-acquire it  */
+    } CLEANUP {
+    } PROCESS(e) {
+    } FINISH(e, true);                                /* unhandled -> propagate  */
+    SUCCEED_RETURN(e);
+}
+
+/* One raise -> catch -> handle cycle; returns NULL (context released). */
+akerr_ErrorContext *one_cycle(void)
+{
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	CATCH(e, validate());
+    } CLEANUP {
+    } PROCESS(e) {
+    } HANDLE(e, AKERR_KEY) {
+	handled_status = e->status;
+    } HANDLE(e, AKERR_VALUE) {
+    } FINISH(e, false);
+    return e;
+}
+
+int main(void)
+{
+    akerr_init();
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    for ( int i = 0; i < 32; i++ ) {
+	handled_status = 0;
+	(void)one_cycle();
+	AKERR_CHECK(handled_status == AKERR_KEY);
+    }
+
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+    fprintf(stderr, "err_refcount_double_fail ok\n");
+    return 0;
+}

tests/err_registry_init_order.c

@@ -0,0 +1,55 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <string.h>
+
+/*
+ * A library may reserve its status range from its own init() before anything in
+ * the process has raised an error, i.e. before akerr_init() has run. That used
+ * to be silently destructive: akerr_init() clears the range and name tables, so
+ * whichever component first triggered it (via PREPARE_ERROR) wiped the earlier
+ * reservation, and the *next* component to claim the same range was told OK --
+ * producing exactly the undetected aliasing the registry exists to prevent.
+ *
+ * Every public registry entry point now calls akerr_init() itself, so the
+ * tables are only ever cleared before the first reservation, never after one.
+ *
+ * Note this test must not call akerr_init() or PREPARE_ERROR first -- the
+ * uninitialized entry is the whole point.
+ */
+
+int main(void)
+{
+    akerr_capture_install();
+
+    /* Cold call: no akerr_init(), no PREPARE_ERROR anywhere yet. */
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(256, 16, "early-lib"));
+    AKERR_CHECK_SUCCEEDS(akerr_register_status_name("early-lib", 256, "Early Error"));
+
+    /* Something else now uses the library for the first time. */
+    akerr_init();
+    PREPARE_ERROR(e);
+    (void)e;
+
+    /* The early reservation and its name must both have survived. */
+    AKERR_CHECK(strcmp(akerr_name_for_status(256, NULL), "Early Error") == 0);
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(256, 16, "late-lib"),
+		       AKERR_STATUS_RANGE_OVERLAP);
+    AKERR_CHECK_MESSAGE_CONTAINS("early-lib");
+    AKERR_CHECK_RAISES(akerr_reserve_status_range(260, 2, "late-lib"),
+		       AKERR_STATUS_RANGE_OVERLAP);
+
+    /* The library's own initialization still happened exactly once. */
+    AKERR_CHECK(strcmp(akerr_name_for_status(AKERR_NULLPOINTER, NULL),
+		       "Null Pointer Error") == 0);
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(0, AKERR_RESERVED_STATUS_COUNT,
+						    AKERR_LIBRARY_OWNER));
+
+    /* An identical repeat by the original owner is still idempotent. */
+    AKERR_CHECK_SUCCEEDS(akerr_reserve_status_range(256, 16, "early-lib"));
+
+    /* Raising from a cold registry must not strand a pool slot either. */
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    fprintf(stderr, "err_registry_init_order ok\n");
+    return 0;
+}

tests/err_release_clears.c

@@ -0,0 +1,45 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <string.h>
+
+/*
+ * Releasing an error context back to the pool must wipe it, so the next caller
+ * that checks it out never sees stale status/message/stacktrace from a previous
+ * error. Mutation testing showed the clearing memset in akerr_release_error
+ * could be deleted without any test noticing.
+ */
+
+akerr_ErrorContext *boom(void)
+{
+    PREPARE_ERROR(e);
+    FAIL_RETURN(e, AKERR_VALUE, "stale dirty message that must not survive");
+}
+
+int main(void)
+{
+    akerr_capture_install();
+    akerr_init();
+
+    /* Raise and fully handle an error; FINISH_NORETURN releases it to the pool. */
+    PREPARE_ERROR(e);
+    ATTEMPT {
+        CATCH(e, boom());
+    } CLEANUP {
+    } PROCESS(e) {
+    } HANDLE(e, AKERR_VALUE) {
+	AKERR_CHECK_STATUS(e, AKERR_VALUE);
+    } FINISH_NORETURN(e);
+
+    AKERR_CHECK(e == NULL);
+
+    /* The next context handed out is the slot we just released: it must be clean. */
+    akerr_ErrorContext *slot = akerr_next_error();
+    AKERR_CHECK(slot != NULL);
+    AKERR_CHECK(slot->status == 0);
+    AKERR_CHECK(slot->message[0] == '\0');
+    AKERR_CHECK(slot->stacktracebuf[0] == '\0');
+    AKERR_CHECK(strstr(slot->message, "stale dirty message") == NULL);
+
+    fprintf(stderr, "err_release_clears ok\n");
+    return 0;
+}

tests/err_release_null.c

@@ -0,0 +1,43 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <string.h>
+
+/*
+ * akerr_release_error(NULL) is an API contract violation the library reports
+ * rather than crashes on: it raises AKERR_NULLPOINTER against the internal
+ * last-ditch context and hands that back, so the caller gets a describable
+ * error instead of a dereferenced NULL. Nothing exercised that path.
+ *
+ * The last-ditch context deliberately lives outside AKERR_ARRAY_ERROR so
+ * reporting this failure cannot consume a pool slot -- which is exactly what
+ * akerr_valid_error_address() reports on, and what this test checks.
+ */
+
+int main(void)
+{
+    akerr_capture_install();
+    /* akerr_init() sets up the last-ditch context's stacktrace cursor. */
+    akerr_init();
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    akerr_ErrorContext *ret = akerr_release_error(NULL);
+
+    AKERR_CHECK(ret != NULL);
+    AKERR_CHECK(ret->status == AKERR_NULLPOINTER);
+    AKERR_CHECK(strstr(ret->message, "NULL context pointer") != NULL);
+
+    /* Reported through FAIL, so the stack trace names the error too. */
+    AKERR_CHECK(strstr(ret->stacktracebuf, "Null Pointer Error") != NULL);
+
+    /* Not a pool slot, and no slot was checked out to report the failure. */
+    AKERR_CHECK(akerr_valid_error_address(ret) == 0);
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    /* The last-ditch context is a singleton: the same one comes back. */
+    akerr_ErrorContext *again = akerr_release_error(NULL);
+    AKERR_CHECK(again == ret);
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    fprintf(stderr, "err_release_null ok\n");
+    return 0;
+}

tests/err_release_refcount.c

@@ -0,0 +1,71 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <string.h>
+
+/*
+ * akerr_release_error() drops one reference and only recycles the slot when the
+ * last one goes away. Two of its refcount edges had no test:
+ *
+ *   - refcount > 1: the release must decrement and return the context intact,
+ *     not wipe it out from under the reference that is still held.
+ *   - refcount == 0: releasing a context nobody holds must not underflow the
+ *     count; it wipes and returns NULL like any other fully-released slot.
+ *
+ * The macro API never produces a refcount above 1 (ENSURE_ERROR_READY only
+ * increments when it acquires a fresh slot), so this test sets the count
+ * directly to model a caller that took an extra reference.
+ */
+
+int main(void)
+{
+    akerr_capture_install();
+    akerr_init();
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    /* Check out a slot and give it two holders. */
+    akerr_ErrorContext *held = akerr_next_error();
+    AKERR_CHECK(held != NULL);
+    int slotid = held->arrayid;
+    held->refcount = 2;
+    held->status = AKERR_VALUE;
+    snprintf((char *)held->message, AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH,
+	     "still referenced");
+
+    /* First release: one holder left, so the context survives untouched. */
+    akerr_ErrorContext *ret = akerr_release_error(held);
+    AKERR_CHECK(ret == held);
+    AKERR_CHECK(held->refcount == 1);
+    AKERR_CHECK(held->status == AKERR_VALUE);
+    AKERR_CHECK(strcmp(held->message, "still referenced") == 0);
+    AKERR_CHECK(akerr_slots_in_use() == 1);
+
+    /* Second release: last holder gone, so the slot is wiped and recycled. */
+    ret = akerr_release_error(held);
+    AKERR_CHECK(ret == NULL);
+    AKERR_CHECK(held->refcount == 0);
+    AKERR_CHECK(held->status == 0);
+    AKERR_CHECK(held->message[0] == '\0');
+    /* The wipe must preserve the slot's identity and stacktrace cursor. */
+    AKERR_CHECK(held->arrayid == slotid);
+    AKERR_CHECK(held->stacktracebufptr == (char *)&held->stacktracebuf);
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    /*
+     * Releasing an unheld slot: refcount is already 0, so there is nothing to
+     * decrement and the count must not go negative.
+     */
+    akerr_ErrorContext *unheld = akerr_next_error();
+    AKERR_CHECK(unheld != NULL);
+    AKERR_CHECK(unheld->refcount == 0);
+    ret = akerr_release_error(unheld);
+    AKERR_CHECK(ret == NULL);
+    AKERR_CHECK(unheld->refcount == 0);
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    /* The pool is still healthy afterwards. */
+    akerr_ErrorContext *probe = akerr_next_error();
+    AKERR_CHECK(probe != NULL);
+
+    fprintf(stderr, "err_release_refcount ok\n");
+    return 0;
+}

tests/err_stacktrace_bounds.c

@@ -0,0 +1,54 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <string.h>
+
+/*
+ * Regression test for the stack-trace buffer overflow. Each frame appended a
+ * line with snprintf, but passed the *full* buffer length as the size rather
+ * than the space remaining, and advanced the cursor by snprintf's would-be
+ * return value. A trace that filled the buffer therefore wrote past the end of
+ * stacktracebuf and ran the cursor out of bounds.
+ *
+ * We place a context in a struct with a guard region right after it, position
+ * the trace cursor near the end of the buffer, append one more frame, and
+ * require that nothing was written past the buffer and the cursor stayed in
+ * bounds.
+ */
+
+static struct {
+    akerr_ErrorContext ctx;
+    unsigned char guard[512];
+} probe;
+
+akerr_ErrorContext *append_frame(akerr_ErrorContext *e)
+{
+    FAIL_RETURN(e, AKERR_VALUE,
+		"an error message long enough to overflow a nearly full stack trace buffer");
+}
+
+int main(void)
+{
+    akerr_init();
+
+    memset(&probe, 0x00, sizeof(probe));
+    memset(probe.guard, 0xAA, sizeof(probe.guard));
+
+    akerr_ErrorContext *e = &probe.ctx;
+    e->refcount = 1;
+    /* Two bytes short of full: any real frame would overflow the old code. */
+    e->stacktracebufptr = probe.ctx.stacktracebuf
+	+ AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH - 2;
+
+    (void)append_frame(e);
+
+    /* Nothing may have been written past the end of stacktracebuf. */
+    for ( unsigned i = 0; i < sizeof(probe.guard); i++ ) {
+	AKERR_CHECK(probe.guard[i] == 0xAA);
+    }
+    /* The cursor must remain within the buffer. */
+    AKERR_CHECK(e->stacktracebufptr
+		<= probe.ctx.stacktracebuf + AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH);
+
+    fprintf(stderr, "err_stacktrace_bounds ok\n");
+    return 0;
+}

tests/err_status_exception.c

@@ -0,0 +1,100 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <string.h>
+
+/*
+ * The registry entry points report failure the same way every other function in
+ * this library does: they return akerr_ErrorContext *. A refused reservation is
+ * therefore an ordinary error, and everything that works on an ordinary error
+ * must work on it -- CATCH, HANDLE, PASS, propagation to the caller, and the
+ * stack trace an unhandled one prints.
+ *
+ * This is what distinguishes the current design from the integer return codes
+ * it replaced: a consumer that ignores the result gets a compiler warning
+ * (AKERR_NOIGNORE), and a consumer that catches it but does not handle it gets
+ * the error propagated out of its init function rather than a silently
+ * unreserved range.
+ */
+
+#define TEST_OWNER "exception-test"
+
+/* A consumer init function in the shape the documentation recommends. */
+static akerr_ErrorContext AKERR_NOIGNORE *component_init(int base, const char *owner)
+{
+    PREPARE_ERROR(errctx);
+
+    ATTEMPT {
+	CATCH(errctx, akerr_reserve_status_range(base, 4, owner));
+	CATCH(errctx, akerr_register_status_name(owner, base, "Component Error"));
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    SUCCEED_RETURN(errctx);
+}
+
+int main(void)
+{
+    akerr_capture_install();
+    akerr_init();
+
+    PREPARE_ERROR(errctx);
+
+    /* A successful reservation raises nothing at all. */
+    AKERR_CHECK_SUCCEEDS(component_init(256, TEST_OWNER));
+    AKERR_CHECK(strcmp(akerr_name_for_status(256, NULL), "Component Error") == 0);
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    /*
+     * A collision propagates out of the component's init and is caught here.
+     * HANDLE proves the status is a real, distinct exception a consumer can
+     * dispatch on -- not an opaque nonzero int.
+     */
+    int handled_overlap = 0;
+    ATTEMPT {
+	CATCH(errctx, component_init(258, "other-component"));
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } HANDLE(errctx, AKERR_STATUS_RANGE_OVERLAP) {
+	handled_overlap = 1;
+    } HANDLE_DEFAULT(errctx) {
+	handled_overlap = -1;
+    } FINISH_NORETURN(errctx);
+    AKERR_CHECK(handled_overlap == 1);
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    /* The name-side refusals dispatch the same way. */
+    int handled_foreign = 0;
+    ATTEMPT {
+	CATCH(errctx, akerr_register_status_name("interloper", 256, "Hijack"));
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } HANDLE(errctx, AKERR_STATUS_NAME_FOREIGN) {
+	handled_foreign = 1;
+    } FINISH_NORETURN(errctx);
+    AKERR_CHECK(handled_foreign == 1);
+    AKERR_CHECK(strcmp(akerr_name_for_status(256, NULL), "Component Error") == 0);
+
+    /*
+     * An unhandled refusal carries a stack trace naming the real owner, so the
+     * report a consumer gets is the library's normal one.
+     */
+    akerr_capture_reset();
+    ATTEMPT {
+	CATCH(errctx, akerr_reserve_status_range(AKERR_VALUE, 1, "encroacher"));
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } HANDLE_DEFAULT(errctx) {
+	LOG_ERROR_WITH_MESSAGE(errctx, "Reservation refused");
+    } FINISH_NORETURN(errctx);
+    AKERR_CHECK_CONTAINS("Reservation refused");
+    AKERR_CHECK_CONTAINS("Status Range Overlap");
+    AKERR_CHECK_CONTAINS(AKERR_LIBRARY_OWNER);
+    AKERR_CHECK_CONTAINS("encroacher");
+    AKERR_CHECK_CONTAINS("error.c");
+
+    /* Nothing above stranded a pool slot. */
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    fprintf(stderr, "err_status_exception ok\n");
+    return 0;
+}

tests/err_success.c

@@ -0,0 +1,44 @@
+#include "akerror.h"
+#include "err_capture.h"
+
+/*
+ * The success path: a nested call that returns cleanly (NULL) must not break
+ * out of the caller's ATTEMPT block, must not enter any handler, and must not
+ * consume a slot from the error pool.
+ */
+
+static int default_fired = 0;
+
+akerr_ErrorContext *ok_func(void)
+{
+    PREPARE_ERROR(e);
+    ATTEMPT {
+    } CLEANUP {
+    } PROCESS(e) {
+    } FINISH(e, true);
+    SUCCEED_RETURN(e);
+}
+
+int main(void)
+{
+    akerr_capture_install();
+    akerr_init();
+
+    int reached_after_catch = 0;
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	CATCH(e, ok_func());
+	reached_after_catch = 1; /* must run: no break on success */
+    } CLEANUP {
+    } PROCESS(e) {
+    } HANDLE_DEFAULT(e) {
+	default_fired = 1; /* must NOT run */
+    } FINISH_NORETURN(e);
+
+    AKERR_CHECK(reached_after_catch == 1);
+    AKERR_CHECK(default_fired == 0);
+    AKERR_CHECK(e == NULL);
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+    fprintf(stderr, "err_success ok\n");
+    return 0;
+}

tests/err_swallow.c

@@ -0,0 +1,48 @@
+#include "akerror.h"
+#include "err_capture.h"
+
+/*
+ * FINISH(ctx, false) closes an ATTEMPT block without propagating: an unhandled
+ * error is dropped (not returned, not passed to the unhandled handler) and the
+ * context is released back to the pool. Because we use FINISH (not
+ * FINISH_NORETURN) the process must continue normally and exit 0.
+ */
+
+static int wrong_handler_fired = 0;
+static int swallowed_status = 0;
+
+akerr_ErrorContext *boom(void)
+{
+    PREPARE_ERROR(e);
+    FAIL_RETURN(e, AKERR_VALUE, "unhandled but swallowed");
+}
+
+/* FINISH(e, false) belongs in a context-returning function. On the swallow
+ * path e is released to NULL, so this returns NULL to its caller. */
+akerr_ErrorContext *swallow_it(void)
+{
+    PREPARE_ERROR(e);
+    ATTEMPT {
+	CATCH(e, boom());
+    } CLEANUP {
+	swallowed_status = (e != NULL) ? e->status : 0;
+    } PROCESS(e) {
+    } HANDLE(e, AKERR_KEY) {
+	wrong_handler_fired = 1; /* does not match AKERR_VALUE */
+    } FINISH(e, false);
+    return e; /* NULL: released even though unhandled */
+}
+
+int main(void)
+{
+    akerr_capture_install();
+
+    akerr_ErrorContext *res = swallow_it();
+
+    AKERR_CHECK(wrong_handler_fired == 0);
+    AKERR_CHECK(swallowed_status == AKERR_VALUE);
+    AKERR_CHECK(res == NULL); /* released even though unhandled */
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+    fprintf(stderr, "err_swallow ok\n");
+    return 0;
+}

tests/err_trace.c

@@ -1,4 +1,10 @@
 #include "akerror.h"
+#include <stdlib.h>
+
+static void expect_unhandled_nullpointer(akerr_ErrorContext *errctx)
+{
+    exit((errctx != NULL && errctx->status == AKERR_NULLPOINTER) ? 1 : 0);
+}
 
 akerr_ErrorContext *func2(void)
 {
@@ -25,6 +31,9 @@ akerr_ErrorContext *func1(void)
 
 int main(void)
 {
+    akerr_init();
+    akerr_handler_unhandled_error = &expect_unhandled_nullpointer;
+
     PREPARE_ERROR(errctx);
     ATTEMPT {
 	CATCH(errctx, func1());

tests/err_unhandled_null.c

@@ -0,0 +1,61 @@
+#include "akerror.h"
+#include "err_capture.h"
+#include <unistd.h>
+#include <sys/wait.h>
+
+/*
+ * The default unhandled-error handler is the library's last stop: it exits the
+ * process. Both of its exits were untested -- exit(1) for a NULL context (a
+ * handler invoked with no error at all) and exit(errctx->status) for a real one.
+ *
+ * The handler never returns, so each case runs in a forked child and the test
+ * asserts the exact exit status. That is stricter than a WILL_FAIL test, which
+ * would pass on any non-zero exit, including one caused by an unrelated bug.
+ */
+
+/*
+ * Run the default handler on ctx in a child process and return the child's exit
+ * status, or -1 if it did not exit normally. The _exit() sentinel catches a
+ * handler that returns instead of terminating.
+ */
+static int handler_exit_status(akerr_ErrorContext *ctx)
+{
+    pid_t pid = fork();
+    if ( pid == 0 ) {
+	akerr_default_handler_unhandled_error(ctx);
+	_exit(99);
+    }
+    int status = 0;
+    if ( pid < 0 || waitpid(pid, &status, 0) != pid || !WIFEXITED(status) ) {
+	return -1;
+    }
+    return WEXITSTATUS(status);
+}
+
+int main(void)
+{
+    akerr_capture_install();
+    akerr_init();
+
+    /* No context to report: the handler has nothing to exit with but failure. */
+    AKERR_CHECK(handler_exit_status(NULL) == 1);
+
+    /*
+     * With a context, the status becomes the exit code. waitpid only reports
+     * its low 8 bits, which is where AKERR_VALUE (144) lands, and it is neither
+     * 0 nor the 1 used for the NULL case, so the two exits stay distinguishable.
+     */
+    akerr_ErrorContext *slot = akerr_next_error();
+    AKERR_CHECK(slot != NULL);
+    slot->refcount = 1;
+    slot->status = AKERR_VALUE;
+    AKERR_CHECK((AKERR_VALUE & 0xff) != 0 && (AKERR_VALUE & 0xff) != 1);
+    AKERR_CHECK(handler_exit_status(slot) == (AKERR_VALUE & 0xff));
+
+    slot = akerr_release_error(slot);
+    AKERR_CHECK(slot == NULL);
+    AKERR_CHECK(akerr_slots_in_use() == 0);
+
+    fprintf(stderr, "err_unhandled_null ok\n");
+    return 0;
+}