libakstdlib/TODO.md

# TODO

Working notes for `libakstdlib`. **Outstanding items only** — anything fixed comes
out of this file and goes into `UPGRADING.md`, the tests, or a comment beside the
code, whichever is the right place to be reminded of it.

Ordered by blast radius: what blocks other work first, what is merely wrong
second, what is missing last.

## Where the library stands

| | |
|---|---|
| Wrapped | 154 public functions across `src/stdlib.c`, `src/string.c`, `src/stream.c`, `src/collections.c` |
| Tests | 17 CTest binaries plus 2 negative-compile entries, green under the default and sanitizer builds |
| Line coverage | 99.5% (1708/1716) |
| Function coverage | 100% (154/154) |
| Doxygen | 100% of 154, gated — `cmake --build build --target docs` fails on an undocumented function, parameter or return |
| Mutation score | 72.3% (188/260 sampled from 1701), gated at 65 |

The six confirmed defects that used to head this file are fixed and
`AKSL_KNOWN_FAILING_TESTS` is empty. What they were, and what changed as a
result, is in `UPGRADING.md`.

---

## 1. Blocked on libakerror

These are not fixable from inside this repository. Each one currently costs
something here, and the cost is what makes them worth carrying.

### 1.1 The error pool is a process-global array with no locking

**This is what makes the library single-threaded**, and it is the largest open
item by some distance.

`AKERR_ARRAY_ERROR` is a fixed array in `deps/libakerror/src/error.c`, handed out
by `akerr_next_error()` with no synchronisation of any kind. Every entry point in
this library takes a slot from it on any failure path, so two threads raising
errors concurrently can be handed the same slot and will corrupt each other's
message, status and stack trace.

**Consequence.** `README.md` says plainly that the library is not thread-safe.
That is honest, and it is also a hard ceiling: §4's `pthread_*` and socket
wrappers cannot be written until this is resolved, because a threading API
nobody can call from a thread is not an API.

**What closing it would touch.** libakerror's pool — either a mutex around
`akerr_next_error`/`akerr_release_error`, or thread-local slot arrays, which
would suit the bounded-preallocation style better and cost nothing on the
single-threaded path. Then a TSan job in `.gitea/workflows/ci.yaml` and a
concurrent smoke test here, and the warning in `README.md` comes out.

### 1.2 `IGNORE()` logs a context and never releases it

`deps/libakerror/include/akerror.tmpl.h:308`. The macro assigns the context to
`__akerr_last_ignored`, logs it, and stops. The slot is never returned to the
pool, so every `IGNORE()` on a failing call leaks one — and after
`AKERR_MAX_ARRAY_ERROR` of them the pool is exhausted and `ENSURE_ERROR_READY`
calls `exit(1)`.

**Consequence here.** `aksl_tree_iterate`'s `CLEANUP` block (`src/stdlib.c`)
cannot use `IGNORE()` to drop a queue-drain failure and open-codes the
log-then-release by hand instead, with a comment saying why. It is four lines
that should be one.

**What closing it would touch.** One `RELEASE_ERROR` in the macro; then delete
the workaround here.

### 1.3 libakerror does not namespace its `coverage` target when embedded

`deps/libakerror/CMakeLists.txt:172` versus `:189` — it namespaces `mutation` and
not `coverage`.

**Consequence here.** A `-DAKSL_COVERAGE=ON` top-level build fails to configure
at all: *"another target with the same name already exists"*. `CMakeLists.txt`
shadows `add_custom_target` for the duration of the `add_subdirectory()` call and
renames the dependency's to `akerror_coverage`.

**What closing it would touch.** Apply the same
`CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR` test upstream that the
`mutation` target already has; then delete the shadow here, which sits directly
above the `add_test` shadow and shares its comment.

### 1.4 libakerror installs no `akerrorConfigVersion.cmake`

**Consequence here.** `cmake/akstdlib.cmake.in` has to call
`find_dependency(akerror)` with no version, because a request for one would be
refused for want of a version file no matter what is installed. The 1.0.0 floor
therefore rests on `akstdlib.pc`'s `Requires:` and the `#error` guard in
`akstdlib.h`, neither of which covers a `find_package` consumer.

**What closing it would touch.** One `write_basic_package_version_file()` call
upstream — libakstdlib already does this correctly and can be copied — then add
the `1.0.0` floor to the `find_dependency` here.

---

## 2. Known gaps in what is already wrapped

### 2.1 A short transfer with neither EOF nor a stream error is untested

`src/stdlib.c`, the `FAIL_RETURN(e, AKERR_IO, "short read: ...")` in `aksl_fread`
and its counterpart in `aksl_fwrite`. Two of the eight uncovered lines in the
whole library.

The standard permits a short transfer with neither indicator set, so the branch
is correct to have. Every way of actually producing one on Linux sets `feof` or
`ferror` first, so nothing in the suite reaches it.

**Consequence.** Low: the code is a handful of lines and reviewed, but it is the
only error path in the library that has never executed.

**What closing it would touch.** A `FILE *` over a custom stream — `fopencookie`
on glibc, `funopen` on the BSDs — whose read function returns a short count
without setting either flag. That is a platform-specific test helper in
`tests/aksl_capture.h` guarded on the platform, which is why it has not been
written yet rather than an oversight.

### 2.2 The string-buffer overflow guard is untestable

`src/collections.c`, the `capacity = needed` arm in `strbuf_reserve`. Reaching it
needs an `aksl_StrBuf` within a factor of two of `SIZE_MAX`, which is not a test,
it is a hang. The other two uncovered lines.

**Consequence.** None known. It is there because doubling a capacity is a
multiplication, and an unguarded one is how a growable buffer turns into a heap
overflow.

**What closing it would touch.** Nothing worth doing. Recorded so the coverage
listing does not read as an oversight.

### 2.3 `aksl_version_check()` ignores its `patch` argument

`src/stdlib.c`, the `(void)patch`. Correct for the current "same soname" rule —
patch level never breaks the ABI — but the parameter exists only so the error
message can name the caller's full version.

**Consequence.** None today. If a future compatibility rule needs the patch level
to participate, that is the line to change, and the `#if` in
`tests/test_version.c` is the test that encodes the rule.

### 2.4 Surviving mutants worth turning into assertions

The mutation harness samples 260 of 1701 mutants and kills 72.3% of them. Most of
the 72 survivors are equivalent mutants rather than missing tests — `README.md`
has the full breakdown — but three clusters are real work:

- **`FINISH(e, true)` → `FINISH(e, false)`, 3 survivors.** An error swallowed
  instead of propagated out of an `ATTEMPT` block, and nothing notices. Each one
  is a call whose failure path is exercised but whose *propagation* is not: the
  test asserts the status the callee raised without checking it came from the
  callee rather than being re-raised locally. `tests/test_pool.c`'s origin
  assertions are the shape of the fix.
- **`SUCCEED_RETURN` deleted, 7 survivors.** The function falls off the end and
  returns whatever is in the return register, which is NULL often enough to pass.
  These need an assertion on the *side effect* — the buffer that was filled, the
  node that was linked — rather than on the returned status.
- **`FAIL_*` guards deleted, ~6 of the 14 in that group.** Each is an argument
  check nothing drives. The other 8 in the group are constant shifts that no test
  can catch, because the test names the same constant symbolically and moves with
  it.

Two survivors in this class were real and are fixed: the right child's
`depth + 1` in the depth-first walk, and `aksl_tree_remove` on an empty tree.

**What closing them would touch.** Only `tests/`. Raise the `--threshold` in
`.gitea/workflows/ci.yaml` and `.githooks/pre-push` in step, as a ratchet.

### 2.5 Four uncovered `HANDLE(e, AKERR_ITERATOR_BREAK)` lines

Macro artifacts rather than gaps. In libakerror that macro begins with the
`break;` belonging to `PROCESS`'s `case 0:` arm, reachable only when a callback
returns a non-NULL context whose status is *zero* — which is the pathological case
the errno-fallback work removed. Left uncovered deliberately rather than pinned
by a test that would have to manufacture it.

---

## 3. Deliberate omissions

Recorded so nobody adds them thinking they were forgotten. Each is a decision,
and each can be revisited with an argument.

| Not wrapped | Why |
|---|---|
| `sprintf`, `vsprintf` | Cannot be bounded. An error-handling wrapper around an unbounded write is the sharp edge this library exists to remove. `aksl_snprintf` and `aksl_asprintf` cover both real uses. |
| `strtok` | Keeps its state in a hidden static, so two interleaved tokenisations corrupt each other silently and any use from a thread is a bug. `aksl_strtok_r` and `aksl_strsep` cover it. |
| `strcpy`, `strcat` as libc spells them | Cannot be called safely without the destination's size. The wrappers take it. |
| `setbuf` | Exactly `setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ)` and strictly less expressive. Wrapping it would add a second way to say one thing. |
| `perror` | Writes to stderr and consults a global. `aksl_strerror` is the akerror-native equivalent and knows this library's own statuses as well as errno's. |
| `strerror_r` | Two incompatible functions share that name and which one you get depends on feature-test macros a consumer cannot influence from inside this header. `aksl_strerror` is built on libakerror's registry instead. |

---

## 4. Not yet wrapped

Ordered by how much a caller of this library would miss them. §3.1 and §3.6 of
the old numbering are done; what follows is what is left.

### 4.1 POSIX file and process API

The most likely next surface. Nothing here is blocked; it is simply not written.

**`unistd.h` / `fcntl.h`**
- [ ] `open`, `close`, `read`, `write`, `pread`, `pwrite`, `lseek`
- [ ] `readv`, `writev`
- [ ] `dup`, `dup2`, `pipe`, `fcntl`
- [ ] `fsync`, `fdatasync`, `truncate`, `ftruncate`
- [ ] `unlink`, `link`, `symlink`, `readlink`, `rmdir`, `mkdir`
- [ ] `access`, `faccessat`, `chmod`, `fchmod`, `chown`, `fchown`, `umask`
- [ ] `chdir`, `fchdir`, `getcwd`
- [ ] `isatty`, `ttyname_r`
- [ ] `sysconf`, `pathconf`
- [ ] `sleep`, `usleep`, `nanosleep`

The short-read/short-write contract is the interesting part: `read(2)` returning
fewer bytes than asked for is *normal* on a pipe or a socket and a failure on a
regular file, so the wrapper needs the same transferred-count out-param
`aksl_fread` has, and callers need to be told which case they are in.

**`sys/stat.h`**
- [ ] `stat`, `fstat`, `lstat`, `fstatat`
- [ ] `statvfs`, `fstatvfs`

**`dirent.h`**
- [ ] `opendir`, `fdopendir`, `readdir`, `closedir`, `rewinddir`, `scandir`

`readdir(3)` returning NULL for both "end of directory" and "error, check errno"
is the same conflation `aksl_fgetc` and `aksl_fgets` already untangle, and should
be untangled the same way: AKERR_EOF for the end, the errno for the error.

**Process control**
- [ ] `fork`, the `exec*` family, `waitpid`, `wait`
- [ ] `posix_spawn`
- [ ] `system`, `popen`, `pclose`
- [ ] `getpid`, `getppid`, `getuid`, `geteuid`, `setuid`, `setgid`
- [ ] `atexit`, `exit`, `_exit`, `abort` — mostly to give akerror a shutdown hook
- [ ] `getenv`, `setenv`, `unsetenv`, `putenv`, `clearenv`

`fork` needs thinking about before it is wrapped: the error pool is inherited by
the child, and any context live at the moment of the fork exists twice
afterwards.

**`sys/mman.h`**
- [ ] `mmap`, `munmap`, `mprotect`, `msync`, `madvise`

### 4.2 Time

- [ ] `time`, `clock_gettime`, `clock_getres`, `gettimeofday`
- [ ] `localtime_r`, `gmtime_r`, `mktime`, `timegm`, `difftime`
- [ ] `strftime`, `strptime`
- [ ] `clock`, `times`

`strftime(3)` returns 0 for both "the output was empty" and "it did not fit",
which is the bounded-write ambiguity `aksl_snprintf` already resolves.

### 4.3 Sorting, searching and the rest of `stdlib.h`

- [ ] `qsort`, `qsort_r`, `bsearch` — a comparator that fails currently has
      nowhere to put the error. An akerror-aware comparator signature, shaped
      like the `aksl_TreeCompareFunc` the tree functions already take, would be a
      genuine improvement over libc rather than a wrapper around it.
- [ ] `abs`, `labs`, `llabs`, `div`, `ldiv`, `lldiv` — note that
      `abs(INT_MIN)` is undefined behaviour, which is exactly the kind of silent
      trap worth surfacing.
- [ ] `rand`, `srand`, `random`, `srandom`, `getrandom`/`arc4random`

### 4.4 Larger surfaces

- [ ] **Sockets**: `socket`, `bind`, `listen`, `accept`, `connect`, the
      `send`/`recv` families, `shutdown`, `setsockopt`/`getsockopt`,
      `getaddrinfo`/`freeaddrinfo`/`gai_strerror`, `inet_ntop`/`inet_pton`.
      `getaddrinfo` is the interesting one: it has its own error space, neither
      errno nor akerror, which needs mapping into a registered status range.
- [ ] **Multiplexing**: `select`, `poll`, `ppoll`, `epoll_*`
- [ ] **Signals**: `sigaction`, `sigprocmask`, `sigemptyset`/`sigaddset`, `kill`,
      `raise`, `signalfd`. A handler cannot raise an akerror context — the pool is
      not async-signal-safe — so the wrapper covers installation and masking only,
      and that limit should be documented rather than discovered.
- [ ] **Threads**: `pthread_create`/`join`/`detach`, `pthread_mutex_*`,
      `pthread_cond_*`, `pthread_rwlock_*`, `sem_*`. **Blocked on §1.1.**
- [ ] **Dynamic loading**: `dlopen`, `dlsym`, `dlclose`, `dlerror`. `dlerror(3)`
      is the same "returns a string and clears itself" trap as `strerror`.
- [ ] **Locale / wide chars**: `setlocale`, `mbstowcs`, `wcstombs`, `iconv_*`
- [ ] **Math**: the `math.h` functions that set `errno` or raise FP exceptions
      (`sqrt`, `log`, `pow`, `acos`, …). Probably a dedicated `libakmath` rather
      than more surface here — the failure model is `fetestexcept`, not errno, and
      it does not resemble anything else in this library.

### 4.5 Data structures

The list and tree API is complete against what §3.6 asked for. What a second
consumer might want next:

- [ ] A dynamic array / vector, on the same "caller owns the storage" terms as
      `aksl_HashMap`.
- [ ] A hash map keyed on something other than a string — the current one copies
      keys into fixed slots, which is right for identifiers and wrong for
      anything large or binary.
- [ ] Balanced insertion for the tree. It is a plain unbalanced BST and says so;
      sorted input gives a degenerate chain that `AKSL_TREE_MAX_DEPTH` then
      refuses. Bounded rather than dangerous, but a red-black or AVL variant is
      the honest fix if anyone inserts sorted data in earnest.

---

## 5. Evidence from the first full consumer

`akbasic` (`source.starfort.tech/andrew/akbasic`) is a ~6,300-line C interpreter
built on this library and `libakerror`. It was the first consumer to exercise the
whole surface rather than a corner of it, and what it *could not* use is what
prioritised the work above.

**The number that started it.** Across `src/`, akbasic made **10 calls into this
library and 116 to raw libc** — a library whose value proposition is "turn silent
libc failures into error contexts", bypassed 92% of the time by the consumer most
committed to it.

| Raw libc it had to use | Count | Now available as |
|---|---|---|
| `strlen` | 37 | `aksl_strlen` |
| `snprintf` | 28 | `aksl_snprintf` |
| `strcmp` | 16 | `aksl_strcmp` |
| `memcpy` / `memset` | 16 | `aksl_memcpy` / `aksl_memset` |
| `strncpy` | 15 | `aksl_strncpy` |
| `strtoll` / `strtod` | 2 | `aksl_strtoll` / `aksl_strtod` |
| `fgets` | 2 | `aksl_fgets` |
| `strstr` | 1 | `aksl_strstr` |

**All four things the port had to write for itself now exist here.**

1. **A strict `strtoll`/`strtod` wrapper** (`akbasic/src/convert.c`, ~60 lines).
   The `aksl_strto*` family is that, with the endptr/`errno`/range contract.
   akbasic's own `TODO.md` §1.9 formally bans the `aksl_ato*` family because
   routing four diagnosable errors through it would have turned them into wrong
   answers — `VAL("garbage")` silently returning `0.0`. That ban can be lifted:
   the `ato*` forms report failures now. **`src/convert.c` can be deleted.**
2. **A fixed-capacity string-keyed hash table** (`akbasic/src/symtab.c`, ~130
   lines, needed three times over). `aksl_hashmap_*` is that table generalised,
   with tombstones on delete, which the original did not have.
3. **The bounded-copy-with-truncation-as-error idiom, at ten sites.**
   `aksl_strcpy` and `aksl_strncpy` are exactly that idiom.
4. **Uppercase folding for case-insensitive lookup, three times.**
   `aksl_strcasecmp` and `aksl_strncasecmp`.

**And the four confirmed-with-impact items are closed.** §2.2.4's unbounded
`aksl_sprintf` is gone; §2.2.2's unchecked `aksl_fopen` arguments are checked, so
`akbasic_cmd_dload`'s hand-rolled validation and its comment pointing here can go;
§2.2.6's sign-extended djb2 reads bytes unsigned; and §2.1.4's missing `va_end` —
which akbasic's stdio text sink ran on every line of program output — is fixed.

**Still true, and still shaping the wishlist.** akbasic uses no allocator, no
lists and no trees, drawing everything from fixed pools by design. A consumer that
does allocate would weight §4.1's `open`/`read`/`write` far higher than this one
does. The next thing worth doing is porting akbasic onto this release and
counting the calls again.

## Requested by consumers

1. **No directory-reading wrapper.** There is no `aksl_opendir` / `aksl_readdir` /
   `aksl_closedir`, so a consumer that wants to list a directory has to call
   `opendir(3)` itself and step outside the error convention every other call in
   its file follows — reporting through `errno` where everything around it
   reports through an `akerr_ErrorContext *`.

   `akbasic` hit this implementing Commodore BASIC's `DIRECTORY` verb, and
   refuses the verb rather than working around it: `src/runtime_disk.c` reports
   "DIRECTORY is not implemented: libakstdlib has no directory-reading wrapper
   yet". The shape it wants is the one the `aksl_f*` family already has — a
   handle out through a pointer parameter, `NULL` on success, `ENOENT` and
   `EACCES` propagated as themselves.

   A wrapper would want tests for: a directory that does not exist, one that
   cannot be searched, an empty one, and one whose entries outlast a single
   read — plus whatever the `d_type` portability story turns out to be, since
   not every filesystem fills it in.