libakerror/TODO.md

Record

Outstanding work is in the issue tracker, not in this file: https://source.starfort.tech/andrew/libakerror/issues

Issues are labelled by kind and blast radius, and milestoned by what they can land in: 2.0.x for anything that breaks no ABI, 2.1.0 for additive surface, 3.0.0 for the handler-ladder rewrite and the contract changes that go with it. Everything filed carries status::grooming until it has been through grooming.

What stays here is the reasoning a tracker has no place for.

Three defects were recorded only downstream

Found while moving this file and libakstdlib's into their trackers. Each is a defect in this library, each was written down in a consumer's TODO file, and none had an entry here:

Issue	What it is	What it costs downstream
#14	IGNORE() logs a context and never releases it	libakstdlib's aksl_tree_iterate open-codes log-then-release by hand; every IGNORE() in libakgl's CLEANUP blocks is a leaked slot
#15	The coverage target is not namespaced when embedded, though mutation is	libakstdlib shadows add_custom_target to embed this library at all
#16	No akerrorConfigVersion.cmake is installed	No consumer can ask find_dependency(akerror) for a version floor

That is the finding worth keeping, more than the three defects. A library whose consumers record its defects in their own files has no way to see them: each consumer knows one, nobody sees the pattern, and the workaround gets written three times. The tracker is now the place, and a consumer filing upstream costs them one issue instead of one workaround.

Why the handler ladder is a 3.0.0 change and not a patch

PROCESS/HANDLE/HANDLE_GROUP/HANDLE_DEFAULT/FINISH compile to a switch, which restricts status matching to integer constant expressions. That is what makes HANDLE-level aliasing undetectable (#4): two components can compile the same integer into a case label without reserving a range or registering a name, and ownership enforcement never sees it, because it covers naming and the case label never reaches the library.

Rewriting it as an if/else if ladder would allow matching on ranges or predicates and let a handler resolve a code through its owner. It also touches the most load-bearing code in the library and every consumer's error handling at once.

One thing it would not fix, recorded so nobody expects it to: the "don't use CATCH or FAIL_*_BREAK inside a loop" hazard comes from exiting via break, not from switch.

Why a copied akerr_ErrorContext is a trap

Recorded because the struct looks copyable and is not, and #11 exists only if a consumer ever needs it.

• stacktracebufptr is self-referential. akerr_ErrorContext c = *src; leaves the copy's cursor pointing into the source's buffer, so the copy logs correctly and then corrupts a slot it does not own the first time anything appends.
• arrayid is restored after the wipe in akerr_release_error() (src/error.c:395-398), so a copied id makes the destination impersonate the source's slot for the life of the process.

If it is ever built, the shape takes the destination as a parameter rather than allocating it: an allocating copy could fail on pool exhaustion, and reporting that failure needs a pool slot, so it would have to abort — a third exit() site in a library that deliberately has two.

Why validating more inputs lowers branch coverage

Branch coverage on src/error.c sits just above its 50% gate, and the gate is set where it is on purpose.

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. Every PASS site around a call that cannot fail carries about twenty-five.

So adding a defensive check lowers the ratio by construction. Before adding one, expect to add a test that drives it, as tests/err_copy_string.c does.

Why the mutation score is a floor

scripts/mutation_test.py configures each mutant with the default CMake options, so a mutant that only breaks under concurrency is judged by a suite running without ThreadSanitizer.

Measured: deleting the pool's akerr_mutex_lock() call survives the run, even though it is a real race. Rebuilt and run directly, that mutant fails tests/err_threads_pool.c in 4 of 10 runs, and fails under scripts/thread_test.sh in 5 of 5.

81.2% is therefore a floor for that category, not a verdict. #10 is the passthrough that would fix the measurement, and it belongs behind a flag: a TSan-instrumented suite per mutant costs roughly 6s instead of 0.4s.

Why a registered name is returned by pointer

akerr_name_for_status(status, NULL) returns a pointer into the registry rather than a copy, which is what makes it usable from inside FAIL — it needs no buffer and no error context of its own.

The cost is that renaming a status is not safe against a concurrent lookup (#7): every other registry operation is serialized, and this one cannot be, because the reader is outside the lock by the time it reads the characters. Documented in docs/thread-safety.md and UPGRADING.md as "register names during initialization".