libakgl/TODO.md

Record

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

This file used to carry both halves of the record -- what had been done and what was left -- and the second half is what a tracker is for. Every open item moved there. What stays here is the part a tracker has no place for: why a decision went the way it did, what the measurement was, and which arguments turned out to be wrong.

The rule that produced this split is the one this file kept breaking: an entry describing work still to do goes stale the moment somebody does it, and stale entries are where the next defect hides. AGENTS.md records the last round of that -- eleven entries here described code that had already changed -- and this file admitted to three more when it was migrated. A record of finished work cannot go stale in that way.

Issues are labelled by kind (defect, performance, test-coverage, api-gap, packaging, docs, design-decision, abi-break, hygiene) and by blast radius, and milestoned by what they can land in: 0.9.x for anything that breaks no ABI, 0.10.0 for new or changed public symbols, 1.0.0 for the design work, Unscheduled for constraints waiting on a trigger.

Four issues are epics with the rest hanging off them: the performance plan (#60), coverage (#61), actor rotation (#62), and the false header comments (#63).

---

Test suites that could not fail

Found while renaming the exported globals. Both are fixed, and this is the entry that argues hardest for not trusting a green suite.

Every suite reported success on any status whose low byte is zero. libakerror's default unhandled-error handler ends in exit(errctx->status). exit keeps only the low byte of what it is given, and libakgl's status band starts at AKERR_FIRST_CONSUMER_STATUS, which is 256. AKGL_ERR_SDL is therefore exactly 256, exit(256) is a wait status of 0, and CTest recorded a pass. The most common failure status in a library built on SDL was the one status that could not fail a test.

tests/character.c was green while running one of its four tests. It aborted in test_character_sprite_mgmt with Failed loading asset .../spritesheet.png : Parameter 'renderer' is invalid -- the symbol collision described under "Public naming" below -- and exited 0 because that status was AKGL_ERR_SDL. Two independent defects had to line up, and they did, for long enough that this file recorded the suite as passing and wondered which change had fixed it. Nothing had; it had stopped running.

Fixed twice. 0.5.0 worked around it here, with a TEST_TRAP_UNHANDLED_ERRORS() in tests/testutil.h that installed a handler collapsing any status a byte cannot carry onto 1. Once installed, no other suite changed colour, so this was not masking anything beyond character -- but it could have been at any time, and nothing would have said so.

That entry ended "any consumer's test suites have this problem; that is worth raising upstream", and it was. libakerror 2.0.1 fixes it at the source: akerr_exit() owns the status-to-exit-code mapping and the default handler calls it, so 0 exits 0, 1 through 255 exit themselves, and anything else exits AKERR_EXIT_STATUS_UNREPRESENTABLE (125) rather than a low byte that is either a lie or a claim of success. There is no wider exit() to reach for -- _exit(), _Exit(), quick_exit() and the raw exit_group syscall all truncate the same way, and even waitid() reports the truncated value.

The workaround is gone as of 0.6.0, along with its 21 call sites. Verified by putting the original failure back: a FAIL_BREAK(AKGL_ERR_SDL) in tests/character.c's main now exits 125 and CTest records a failure, where it exited 0 and passed before.

Internal consistency

A sweep of src/ and include/ found 41 consistency and convention problems. All are resolved except the two now filed as #4 and #5. What follows is the part worth keeping: what changed, and which of them were not cosmetic after all.

Public naming, resolved in 0.5.0

An ABI break, carrying the soname to libakgl.so.0.5. What a consumer had to rename:

Was	Is
_ASSETS_H_, _CONTROLLER_H_, _DRAW_H_, _ERROR_H_, _JSON_HELPERS_H_, _PHYSICS_H_, _REGISTRY_H_, _RENDERER_H_, _TEXT_H_, _TILEMAP_H_, _UTIL_H_, _STRING_H_	_AKGL_<FILE>_H_
akgl_Actor_cmhf_* (8 functions)	akgl_actor_cmhf_*
akgl_game_updateFPS	akgl_game_update_fps
akgl_render_init2d, akgl_render_bind2d	akgl_render_2d_init, akgl_render_2d_bind
akgl_sprite_sheet_coords_for_frame	akgl_spritesheet_coords_for_frame
point, RectanglePoints	akgl_Point, akgl_RectanglePoints
window, bgm, game, gamemap, renderer, physics, camera	the same, akgl_-prefixed
_akgl_renderer, _akgl_physics, _akgl_camera, _akgl_gamemap	akgl_default_renderer, akgl_default_physics, akgl_default_camera, akgl_default_gamemap
HEAP_ACTOR, HEAP_SPRITE, HEAP_SPRITESHEET, HEAP_CHARACTER, HEAP_STRING	akgl_heap_actors, akgl_heap_sprites, akgl_heap_spritesheets, akgl_heap_characters, akgl_heap_strings
GAME_ControlMaps	akgl_controlmaps
AKGL_SPRITE_MAX_CHARACTER_NAME_LENGTH	AKGL_CHARACTER_MAX_NAME_LENGTH
AKGL_TIME_ONESEC_MS	AKGL_TIME_ONEMS_NS

include/akgl/staticstring.h also stopped guarding with _STRING_H_ -- a name several libc implementations use for their own <string.h> -- and its #include "string.h" is now #include <string.h>.

The renames were done by renaming each declaration and letting the compiler find every use, rather than by pattern substitution. That distinction matters for renderer, physics and camera, which are also parameter and struct-member names: a sed would have rewritten map->physics and every akgl_RenderBackend *renderer parameter, and nothing would have complained.

One rename had a live bug behind it. akgl_game_state_lock counted its retry loop against a constant named "one second in milliseconds" that held 1000000, so it retried 10,000 times at 100 ms and blocked for roughly sixteen minutes before reporting failure. The budget is now AKGL_GAME_STATE_LOCK_BUDGET_MS (1000), with the cadence named separately as AKGL_GAME_STATE_LOCK_RETRY_MS. tests/game.c carries test_game_state_lock_budget, which holds the mutex from a second thread and asserts the call gives up between half a second and five. The old code fails it by timing the suite out; a build that gave up without waiting at all fails the lower bound. Nothing exercised the contended path before -- the existing lock test only ever took an uncontended mutex, which never reaches the retry loop.

Renaming the exported globals was not cosmetic, and the proof was sitting in the test suite. renderer was exported from the shared library, and tests/character.c defined an SDL_Renderer *renderer of its own. Both had external linkage and the same spelling, so the executable's definition preempted the library's: akgl_sprite_load_json read an SDL_Renderer * through an akgl_RenderBackend *, every texture load in that suite failed with Parameter 'renderer' is invalid, and the suite still reported success. A consuming game with a variable called renderer would have hit the same thing with no test to notice.

Header/implementation surface drift, resolved in 0.5.0

Nineteen non-static functions were defined in src/ but declared in no header. Each is now declared or static. The controller handlers were the interesting case: they were defined as gamepad_handle_* while controller.h declared the akgl_controller_handle_* names it never defined -- four symbols mentioned in prose, which is not the same as being declared.

This is enforced now. scripts/check_api_surface.sh reads the built library's dynamic symbol table, strips comments out of every public header, and fails when an exported akgl_* symbol is declared nowhere. It runs as the api_surface CTest test. Stripping comments is the point, and is exactly how those four went unnoticed.

Headers relied on their includers for types. iterator.h used uint32_t without <stdint.h>; json_helpers.h used json_t without <jansson.h>; util.h used SDL_FRect and bool without any SDL include. Each compiled only because of .c-file include ordering.

Resolved, and enforced rather than merely fixed: AKGL_PUBLIC_HEADERS in CMakeLists.txt is the single list behind both install() and a generated translation unit per header -- each including exactly that header and nothing before it -- linked into the headers suite. A header that ships is a header that is checked. Writing that check found a case the hand-written list had missed: registry.h uses SDL_PropertiesID in eight declarations and included no SDL header at all. That is the argument for generating the check off the install list rather than hand-listing the headers somebody thought were at risk.

Object-pool size macros were defined twice and the override hook was dead. They live once, in heap.h, inside the #ifndef guards that were always supposed to make them overridable. tests/header_pool_override.c is the regression test: it defines its own ceilings, includes heap.h, and #errors if the guard did not fire. The assertion is the compile.

Empty parameter lists. akgl_game_init, akgl_game_update_fps, akgl_heap_init, akgl_heap_init_actor and the eight akgl_registry_init* functions declare and define (void). Before C23 () means "unspecified arguments" and suppresses argument checking, so these were the entry points a caller could pass anything to.

Also resolved: akgl_game_init_screen declared and never defined; static helpers using three naming styles; six parameter-name disagreements between declaration and definition (akgl_get_json_with_default was the interesting one -- it took the incoming context as err and named its own context e, and renaming it was what surfaced that the two had been swapped rather than merely misspelled); and AKERR_NOIGNORE applied inconsistently at definition sites.

Error-handling pattern, resolved in 0.5.0

*_RETURN macros were used inside ATTEMPT blocks, which skips CLEANUP. Ten sites, found by scanning rather than from the list -- which named six and missed the four in akgl_collide_rectangles.

The one that mattered was the success path of akgl_get_json_tilemap_property, which leaked two of the string pool's 256 entries on every lookup that found what it was asked for. A map load does that several times per layer.

Two needed more than swapping the macro. In akgl_get_json_tilemap_property a plain break would have fallen through to the "property not found" FAIL_RETURN after FINISH, reporting a miss for something found, so the success path sets a flag. In akgl_collide_rectangles the eight early exits were followed by *collide = false;, which would have overwritten the hit that broke out of the block; each corner test writes the flag itself, so that line is gone rather than moved.

scripts/check_error_protocol.py keeps this closed, as the error_protocol test. It also enforces the other rule with a silent failure mode -- no return out of a HANDLE block.

Also resolved: NULL-check discipline varying by function (the eight typed JSON accessors that validated their container and then wrote through dest unconditionally; the null physics backend; akgl_render_2d_frame_start, _frame_end and _shutdown, which tests/renderer.c now calls with NULL and which segfaulted before), and the errctx/e split -- all 45 remaining sites are errctx, in its own commit because it is a rename and nothing else, with e keeping its meaning as an incoming context being inspected.

Types and macros, resolved in 0.5.0

AKGL_COLLIDE_RECTANGLES had unbalanced parentheses. Three opens against two closes meant any expansion was a syntax error. It had no callers and duplicated akgl_collide_rectangles, so it was deleted.

Bitmask macros were unparenthesized. All five are fully parenthesized, and AKGL_BITMASK_CLEAR no longer carries a semicolon inside its body. tests/bitmasks.c covers the composition cases, and writing them turned up something worth recording: the obvious test does not catch this. For a bit that is set, !AKGL_BITMASK_HAS(mask, bit) misparses to !(mask & bit) == bit, which is 0 == bit -- false, the same answer the correct parse gives. It only diverges for a bit that is not set and whose value is not 1: !(0) is 1, and 1 == 64 is false where the answer should be true. The suite uses that shape, and fails against the old macros.

Also resolved: float/double spelled raw where types.h defines float32_t and float64_t; the state and iterator bit macros mixing forms; and akgl_Frame, defined and never used, deleted.

The bit-pattern comments in actor.h were not wrong so much as unlabelled: each shows the pattern within its own 16-bit half, which is why bit 16 looks like it restarts at bit 0. The section headings say so now. Rendering the full 32-bit value instead would push those lines past the 100-column fill.

AKGL_ACTOR_STATE_STRING_NAMES, resolved in 0.5.0

The array bound differed between declaration and definition. The header declared [AKGL_ACTOR_MAX_STATES+1] (33) and the definition was a literal [32], so a consumer trusting the declared bound read past the object.

Two entries named the wrong bit. Indices 11 and 12 said AKGL_ACTOR_STATE_UNDEFINED_11 and _12 where actor.h has MOVING_IN and MOVING_OUT, so no character JSON could ever bind a sprite to either state -- the name it would have to write was not in the registry.

tests/registry.c now walks the whole table: every entry non-NULL, every entry resolving to its own bit, no two entries sharing a name (a duplicate silently overwrites and makes one bit unreachable), and MOVING_IN/MOVING_OUT named explicitly so a regression reads as what it is.

The generation comment was stale -- there is no generator, no Makefile and no lib_src/. The file's own header says it is maintained by hand and states the two invariants that keep breaking.

Formatting and hygiene, resolved in 0.5.0

Leftover debug code. Four SDL_Log lines in src/controller.c guarded by event->type == 768 && event->key.which == 11 && event->key.key == 13 -- decimal literals for one keyboard on one developer's machine, inside the per-event inner loop.

akgl_game_update's default flags OR-ed the same bit twice. It reads AKGL_ITERATOR_OP_UPDATE | AKGL_ITERATOR_OP_LAYERMASK now. This was a statement of intent rather than a behaviour change, and the reason is worth knowing: nothing in that loop read either bit, which was the per-layer update sweep defect fixed later.

akgl_draw_background was the only public function outside the error protocol. It takes an akgl_RenderBackend * like every other entry point in draw.h, returns an error context, checks the backend and its sdl_renderer, and restores the draw colour it found. It was recorded as needing the offscreen renderer harness. It did not, and never did -- what it needed was to stop reading the global.

akgl_registry_init_actor was the only initializer that destroyed the registry it was replacing. All eight go through one registry_create() helper now, so the other seven stop leaking an SDL_PropertiesID per call after the first -- which a game that resets between levels makes on every level. Fixed alongside it, because it is the same function: akgl_registry_init() never called akgl_registry_init_properties(), so AKGL_REGISTRY_PROPERTIES stayed 0 for any caller that did not also go through akgl_game_init, making akgl_set_property a silent no-op and akgl_get_property always return the caller's default -- so akgl_physics_init_arcade and akgl_render_2d_init quietly ignored their configuration.

Also resolved: five abandoned SDL_GetBasePath() blocks; a dozen unused locals; struct-qualified parameters in two physics definitions; text.c validating the wrong argument; and dst vs dest for output parameters.

Coverage

Line coverage 83.9%, function coverage 91.2% (2433/2901 lines, 176/193 functions), up from 79.6% / 87.2% before the 0.5.0 defect work and from a 39.6% / 44.3% baseline. Snapshot at 0.9.0; the gaps behind it are #61.

Generated with:

cmake -S . -B build-coverage -DAKGL_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build-coverage --parallel
ctest --test-dir build-coverage --output-on-failure

Reports land in build-coverage/coverage/ (index.html, coverage.xml). A coverage tree rebuilt after a source edit fails coverage_reset with GCOV returncode was 5; find build-coverage -name '*.gcda' -delete clears it.

File	Lines	Functions
src/actor.c	205/258 (80%)	16/18
src/assets.c	0/21 (0%)	0/1
src/audio.c	229/248 (92%)	22/23
src/character.c	122/126 (97%)	7/7
src/controller.c	314/349 (90%)	17/17
src/draw.c	281/286 (98%)	12/12
src/error.c	9/9 (100%)	1/1
src/game.c	142/243 (58%)	13/18
src/heap.c	116/116 (100%)	12/12
src/json_helpers.c	123/123 (100%)	11/11
src/physics.c	144/144 (100%)	10/10
src/registry.c	83/111 (75%)	12/13
src/renderer.c	61/83 (74%)	8/8
src/sprite.c	102/110 (93%)	5/5
src/staticstring.c	17/18 (94%)	2/2
src/text.c	79/80 (99%)	7/7
src/tilemap.c	276/444 (62%)	13/20
src/util.c	128/130 (98%)	7/7
src/version.c	2/2 (100%)	1/1

src/tilemap.c moved the most, 47% to 62%, because the bounds and leak work needed the loaders driven rather than merely called.

Branch coverage reads 24.7% and should not be used as a target. The akerror control-flow macros expand into large branch trees per call site, most of them unreachable in normal operation -- src/game.c reports over 1700 branches across 230 lines. Track line and function coverage; treat branch coverage as a relative signal within a file.

Suites

Every suite is registered through the AKGL_TEST_SUITES list in CMakeLists.txt, which drives target creation, CTest registration, the WORKING_DIRECTORY/TIMEOUT properties, the link line, and the FIXTURES_REQUIRED akgl_coverage list together. Adding tests/<name>.c and the name to that list is all a new suite needs; it can no longer be accidentally left out of the coverage fixture.

Shared assertion helpers are in tests/testutil.h: TEST_ASSERT, TEST_ASSERT_FEQ, TEST_EXPECT_STATUS, TEST_EXPECT_OK, TEST_EXPECT_ANY_ERROR and TEST_ASSERT_FLAG. All except the last expand to a break on failure, so they belong directly inside an ATTEMPT block, not inside a loop nested in one.

Mutation testing

Macros expand at call sites, so mutation testing is the only thing that checks them. scripts/mutation_test.py, run when touching control flow, refcounting, stack traces or handlers.

Sampled runs (--max-mutants 8 to 10 each, so these are samples rather than exhaustive scores):

File	Score	Surviving mutants
src/draw.c	90%	Deleting the FAIL_ZERO_BREAK on SDL_CreateTextureFromSurface in akgl_draw_flood_fill
src/audio.c	75%	Deleting SUCCEED_RETURN from the static check_voice; deleting spec.freq before opening a device
src/text.c	50%	Three in akgl_text_rendertextat, which had no test yet, plus one SUCCEED_RETURN deletion
src/controller.c	40%	Three SDL_Log deletions; keybuffer_head's initialiser; count > 0 in keybuffer_attach_text; the mod a text-only entry is given

What the runs found, and what they did not. src/audio.c scored 50% first and named two real gaps, both now tested: nothing asserted that an unconfigured voice is audible (the whole reason the table defaults to a square wave at full level rather than a zeroed struct), and no envelope test used a non-zero attack and decay together, so the decay measuring from the wrong origin survived. src/draw.c scored 70% first and named one: the circle was only checked at its four axis points, which a mis-signed octant reflection survives, so it now checks that every plotted pixel has a mirror in the other three quadrants. In src/controller.c, one real gap -- nothing checked that a text-only ring entry reports no modifiers.

The rest are equivalent mutants rather than misses, and knowing which is which is the point: a ring buffer whose head starts at 1 behaves identically, count > 0 cannot be false where it is checked, deleting the break on a switch's last case changes nothing, and the mixer's v <= bound reads one voice past a zeroed table, which is undefined rather than observable. SDL_Log deletions are unobservable by construction. Deleting a SUCCEED_RETURN leaves a non-void function falling off its end, which is undefined rather than observably wrong.

The three src/text.c survivors are gone: it is tested against a software renderer, and deleting any of its three backend checks fails the suite. That was not free -- the first draft of the test used a made-up SDL_Renderer pointer, which SDL refuses on its own, so the deleted-check mutant survived it. A live renderer was what made the check observable.

Defects

Fixed while building the suites

Each was found by a test written to assert correct behaviour.

1. akgl_physics_simulate dereferenced self before its NULL check. src/physics.c:132 read self->gravity_time at declaration time, three lines above the FAIL_ZERO_RETURN. A NULL backend segfaulted.
2. akgl_game_save never flushed or closed its stream. CLEANUP and PROCESS were transposed, which put the fclose inside the PROCESS switch, where it only ran if an error context existed and reported success. An ordinary save produced an empty file.
3. akgl_game_save_actors wrote name-table terminators from a single char. aksl_fwrite((void *)&nullval, 1, AKGL_ACTOR_MAX_NAME_LENGTH, fp) emitted 127 bytes of adjacent stack memory into the save file and produced a sentinel the loader could not recognize.
4. akgl_game_load_objectnamemap swallowed read failures. CATCH used directly inside while (1) breaks the loop, not the function, so a truncated or corrupt name table loaded as a successful game.
5. akgl_Actor_cmhf_up_on and _down_on dereferenced basechar unguarded, unlike their left and right counterparts.
6. akgl_actor_logic_movement checked actor twice instead of checking actor->basechar before dereferencing it.
7. The gamepad handlers checked appstate three times each, so a NULL event or a missing player actor was never caught.

Fixed in 0.5.0 and later

• akgl_render_and_compare compared a texture against itself. Both passes drew t1, so it always reported a match and every image assertion built on it asserted nothing.

• akgl_tilemap_release double-freed tileset textures. The layers loop tested layers[i].texture and destroyed tilesets[i].texture, so every tileset texture was freed twice on a single release and no image layer's texture was freed at all. Each pointer is cleared as it goes now, which also makes a second release safe rather than a use-after-free.

• akgl_path_relative_from was a stub that leaked. It claimed a heap string, never wrote its output, and never released it, so 256 calls exhausted the string pool. Declared in no header, called from nowhere, duplicating what akgl_path_relative already does. Fixing an unfinished function nobody can reach is worse than deleting it.

• akgl_compare_sdl_surfaces memcmp'd without checking geometry. tests/util.c compares a 32x32 surface against an 8x8 one in both directions, which used to read 4 KiB past the end of the smaller.

• akgl_string_initialize overflowed by four bytes when init is NULL. The four bytes it ran past the end of the object landed on the next pool slot's refcount, which is the field the allocator reads to decide whether a slot is free -- so the overrun could hand a live string out twice. Fixed alongside, same class: akgl_string_copy accepted a count above AKGL_MAX_STRING_LENGTH, which read past the end of one pool slot and wrote past the end of another. The header documented that as behaviour.

• Savegame name lengths disagreed between writer and reader. The reader used AKGL_ACTOR_MAX_NAME_LENGTH for all four tables; only the spritesheet table was wrong, and that was enough. The failure was worse than "cannot be read back", which is what made the test interesting: the tables carry no length prefix and end at a zeroed sentinel, so a reader stepping the wrong width does not run off anything -- it finds a run of zeros somewhere inside an entry, stops early, and reports success with silently wrong maps. A test that only asserted the load succeeded passed against the broken reader. So akgl_game_load checks the stream is at EOF once the four tables are read, which is what turns a width disagreement into AKERR_IO instead of a corruption. That EOF check has to move when the objects themselves start being written; there is a comment at the site saying so.

  A first pass introduced four AKGL_GAME_SAVE_*_NAME_WIDTH aliases, on the reasoning that the on-disk format's widths are a separate concern from the object model's. They were removed: each expanded to exactly one existing constant and had exactly one use per side, so they were indirection with no second consumer -- and the divergence they anticipated cannot happen quietly anyway, since raising one of those lengths is an ABI change and akgl_game_load refuses a save whose libversion does not match before it reads a single table.

• akgl_controller_pushmap and akgl_controller_default accepted negative map ids. Both check the lower bound now.

• A failed controller-DB fetch silently destroyed the tracked fallback. mkcontrollermappings.sh runs under set -euo pipefail, fetches into a temporary directory, and moves the result into place only after checking curl's exit status (with --fail, so an HTTP error is a status rather than an error page in the body), a plausible minimum mapping count, and that no mapping carries a quote or backslash that would break the C string literal it becomes.

  Verified against all five failure modes: an unresolvable host, a 404, a truncated response, an empty-but-successful response -- the original failure exactly -- and a response containing a quote. Each refuses, and the header's checksum is unchanged after every one.

  The build no longer runs it. The add_custom_command declared OUTPUT include/akgl/SDL_GameControllerDB.h as a relative path, which CMake resolves against the binary directory while the script writes to the source directory, so the declared output never appeared, the command was permanently out of date, and every build re-ran it -- needing network access and leaving the tree dirty.

  Regenerating against the real upstream produced byte-identical mappings -- 2255 entries, no content change -- so the rewrite is faithful.

• A stale build tree in the source directory broke the coverage run. gcovr searches for .gcda/.gcno under its search paths, and with none given it searches --root -- the source directory, which is where developers keep their build trees. --object-directory does not narrow that; per gcovr's own help it only identifies "the path between gcda files and the directory where the compiler was originally run". Verified by reproducing it: two instrumented trees built inside the source directory with a source edit between them fail the old invocation with Got function write_exact on multiple lines: 46, 48 and exit 64; the new one exits 0.

• 22 public symbols shipped without a version or soname bump, contradicting this repository's own rule that for 0.x libraries the soname carries MAJOR.MINOR deliberately. Two consequences, and the first is the one that bites: a binary compiled against the new headers links happily against a libakgl.so.0.1 built from the old tree, because the soname says they are the same ABI, and fails at symbol resolution rather than at configure time. And AKGL_VERSION_AT_LEAST(0, 1, 0) was true for both trees, so a consumer could not feature-test for the new API at all -- akbasic pinned the requirement by submodule commit instead, and said so in its README, which is not a thing a released library should make anybody do. Worth remembering the next time a handful of symbols looks too small to bump for.

Found while rewriting the Doxygen comments

Each came out of reading an implementation against the contract its header claimed. They are recorded inline as @note or @warning on the function concerned.

• akgl_sprite_load_json did not bound the frames array. The count is bounded against AKGL_SPRITE_MAX_FRAMES before anything is written, and each element is read into an int and narrowed deliberately rather than written through a uint32_t * cast of a uint8_t *. A frame number that does not fit a uint8_t is refused rather than truncated into an index that names a different tile. tests/sprite.c covers exactly the maximum, one past it, and the wide frame number; against the old code the middle case loads happily.
• Two more unbounded array loads in the tilemap loader, both fixed with the bound at the top of the loop body. The object one is the reachable half -- 128 objects is not a large object layer and akgl_TilemapObject is not small.
• akgl_get_json_with_default defaulted on a status the array accessors never raise. Worth knowing for the next test written against this function: it returns the context it was given when it does not handle the status, so TEST_EXPECT_OK -- which releases whatever the statement returns -- will double-release it against a CLEANUP block that also releases it, and a double-released context corrupts the failure instead of reporting it. The first draft of that test did exactly that and passed against the unfixed library.
• akgl_character_sprite_add leaked a sprite reference when a state is remapped. The new reference is taken before the write and given back if the write fails, so there is no window where a sprite is bound with nothing behind it.
• akgl_heap_release_character abandoned the whole state-to-sprite map. src/heap.c:150 zeroed the character without walking state_sprites, so every sprite reference the character took was lost and the SDL_PropertiesID holding the map was never destroyed. The test was already written: tests/character.c had asserted this contract all along -- "character did not reduce reference count of its child sprites when released" -- and had never once run, for the two reasons under "Test suites that could not fail".
• akgl_actor_render computed a sprite's drawn height from its width. Every actor was drawn square, so a non-square sprite was stretched or squashed -- invisible in the fixtures because they are all square. tests/actor.c renders a 48x24 sprite through a backend whose draw_texture records the rectangle it is handed rather than drawing it. That recording backend is also the first coverage akgl_actor_render has had at all.
• akgl_text_rendertextat refused the empty string while akgl_text_measure accepted it. The check sits after the font, text and backend guards rather than before them, so drawing nothing still refuses the things drawing something refuses -- a caller does not get a different contract for an empty string.
• character_load_json_state_int_from_strings checked the same argument twice. Not asserted, deliberately. The function is static and has one call site, which passes &stateval, so a NULL dest is unreachable from the public API and the guard cannot fire. Testing it would mean giving the function external linkage purely to reach a defensive check.

Performance

The first measured baseline is in PERFORMANCE.md, produced by tests/perf.c and tests/perf_render.c (ctest --test-dir build -L perf). Both suites hold every measurement to a budget set at roughly ten times the recorded baseline, so an algorithmic regression fails the suite rather than being discovered by a player. Read PERFORMANCE.md before arguing with anything below -- every claim has a number behind it, and several of the things expected to be slow are not.

The plan for the missed targets is #60.

Defects the perf suites found

• akgl_path_relative leaked an error context on every root-fallback resolution. It took its ENOENT branch by returning from inside the HANDLE block, which skips the RELEASE_ERROR that FINISH ends with. One entry of AKERR_ARRAY_ERROR was lost per call, and the 129th call hit "Unable to pull an error context from the array!" and exited the process. Every tilemap load resolves several paths this way, so a game that loaded fifty levels died in the loader. tests/util.c resolves AKERR_MAX_ARRAY_ERROR * 2 paths through that branch; against the old code that test does not fail, it terminates the suite.

  This is the only return from inside a HANDLE block in src/ -- the other candidates use SUCCEED_RETURN, which releases correctly. Worth a grep before anyone writes a new one, and it is now in AGENTS.md's error-handling protocol, which warned about *_RETURN inside ATTEMPT but not about returning out of HANDLE.

• akgl_tilemap_load leaked five pooled strings per load, in two parts. Three were akgl_get_json_tilemap_property leaking two scratch strings on every successful property lookup. The remaining two were each a claim with no matching release. Finding the last two meant dumping the contents of every still-claimed slot after a cycle rather than reading the code again; 'tilelayer' and an assets directory named themselves immediately. Fixed alongside, same class: akgl_tilemap_load_layer_objects released its scratch string after reading each object's name and then kept using the slot -- and akgl_get_json_string_value reuses a non-NULL destination without taking another reference, so the slot was free while still live.

• Two JSON accessors turned string-pool exhaustion into a segfault. tests/json_helpers.c claims every slot in the pool and asserts AKGL_ERR_HEAP comes back out of both accessors. Against the old code that test segfaults rather than failing -- and so did the new tilemap property-lookup test, which is how this was confirmed rather than merely believed.

• akgl_game_update segfaulted if akgl_game_init did not run. game.fps is 0 for the first second of the process, which is under the threshold, so the unguarded akgl_game_lowfps call fired on frame one. Only akgl_game_init installed the default -- and include/akgl/renderer.h documents the other path on purpose: a host that owns its own window calls akgl_render_2d_bind instead of akgl_render_2d_init. An embedder following that documentation crashed on its first frame, and akbasic is exactly that embedder.

• akgl_game_update ran the actor update sweep once per tilemap layer. The sweep is hoisted out of the layer loop -- updating an actor is not a per-layer operation. tests/game.c counts calls into a stub updatefunc; against the old code it reports 16. Counting is the assertion on purpose: the defect was invisible in the frame total because the tilemap blits are three orders of magnitude larger, so a timing test would have measured the rasterizer.

Targets

What a library like this should hit. The frame budget throughout is 16.67 ms (60 fps); where a target is stated per-operation it is because that is the number that survives a change of renderer.

The one that governs the rest: libakgl's own bookkeeping should never be the reason a frame is late. Everything the library decides -- pool scans, registry lookups, state-to-sprite mapping, physics, visibility, error contexts -- should fit in 5% of a frame, leaving 95% for the pixels and the game's own logic. At 64 actors and a screenful of tiles that is a ceiling of about 800 us.

#	Target	Today	Verdict
1	Library bookkeeping under 5% of a 60 fps frame at 64 actors + 1200 tiles	~0.3% (excluding pixel work)	met
2	One actor's logic update under 200 ns	68.4 ns	met
3	One actor's render bookkeeping, excluding the blit, under 500 ns	~250 ns, by subtraction	met, weakly measured
4	Physics sweep under 25 ns per live actor, proportional to live actors rather than pool size	19 ns per live actor, but 63.9 ns for an empty pool	partly
5	Tilemap draw bookkeeping under 100 ns per tile, excluding the blit	~25 ns	met
6	Pool acquire under 100 ns regardless of how full the pool is	3.9 ns empty, 250.9 ns on the last free string slot	missed (#21)
7	Pool release proportional to the bytes actually used	47.2 ns, a fixed 4 KiB wipe	missed (#21)
8	Re-drawing an unchanged line of text under 1 us	12.6 us, every frame, no cache	missed (#22)
9	Zero texture creation or destruction per frame in steady state	one create + one destroy per line of text per frame	missed (#22)
10	A handled, routine condition costs no more than twice the path that succeeds	616.5 ns vs 68.4 ns -- 9x	missed (#23)
11	256 actors simulated, updated and made ready to draw in under 1 ms	~22 us at 64 actors; linear, so ~90 us extrapolated	met, untested at that size
12	Collision for 256 actors under 2 ms without the caller writing a broad phase	54.1 us at -DAKGL_MAX_HEAP_ACTOR=256	met
13	Level load under 100 ms for a map with 8 tilesets, 4 layers and 64 actors	11.9 ms for a 2x2 map with one tileset	unknown at that size (#27)
14	Fixed per-load overhead under 1% of a level load	11.5% -- zeroing 26 MB of akgl_Tilemap	missed (#28)
15	Static footprint under 4 MB in the default configuration	28 MB, 94% of it one tilemap	missed (#28)
16	No pool leaks across a load/release cycle of any asset type	tilemap is clean, asserted over 64 cycles; sprite, spritesheet and character cycles are not asserted	met where tested (#13)
17	Pool exhaustion reports AKGL_ERR_HEAP and never crashes	all five pools report it	met
18	Every benchmark held to 10x its recorded baseline, enforced in CI	done, ctest -L perf	met

Notes on the ones worth arguing about:

• 6 and 7 are the same fix, and 8 and 9 are one cache, and 14 and 15 are the same refactor. Each pair is one issue for that reason.

• 10 is a design target, not a speed target. The answer is not a faster error context; it is that "this character has no sprite for this state" is a question with a boolean answer.

• 12 is a scope decision, not a defect, and it is done. The structure is the incremental uniform grid, not the tree -- cells keyed on tile size, static arrays, insert/remove as actors move, wired into the collide slot of akgl_PhysicsBackend. Construct measured that design at a 96% check reduction over brute force and rejected quadtrees as costlier to maintain; Phaser's rebuild-the-RTree-every-frame approach carries a documented ~5,000-body ceiling and is the counterexample.

  Measured here rather than cited: the grid beats the BSP by 2.6x on the same 64-proxy population (44.3 ns against 116.1 ns per query), before counting that the tree rebuilds whenever a proxy moves and the grid's move is 11.9 ns when the cell rectangle has not changed. Over a 4x range in actor count the step grew 3.5x and the all-pairs control grew 15.6x, which is the n2 the index exists to avoid.

  The BSP ships anyway. A vtable with one implementation behind it has never been asked to be a vtable; tests/partition.c runs its whole contract against a table of both, so the seam is proven rather than asserted. It would earn its place in a world with wildly non-uniform object sizes or one larger than the grid's 128x128 cell array covers.

Memory checking

cmake --build build --target memcheck runs the suites that already exist under valgrind -- ctest -T memcheck with the headless drivers forced, wrapped by scripts/memcheck.sh so that a finding is an exit status rather than a line in a log nobody reads. There are no memory-check test programs, and there should never be any: tests/benchutil.h notices that it is running under valgrind and divides every benchmark's iteration count by two thousand, which turns the perf suites into the broadest path coverage in the tree at a cost valgrind can survive. The whole run is about thirty seconds.

The two halves fit together on purpose. A benchmark is a program that walks one path a hundred thousand times; a leak check wants every path walked once. Same binaries, same registration, one flag apart.

Third-party findings are suppressed in scripts/valgrind.supp, and the run forces SDL_VIDEO_DRIVER=dummy / SDL_RENDER_DRIVER=software / SDL_AUDIO_DRIVER=dummy so the vendor GPU stack is never loaded -- that removes thousands of unfixable findings inside amdgpu_dri.so without suppressing anything at all. Only definite losses and invalid accesses are counted.

Defects the memory checker found

All six are fixed, and the CI job that runs memcheck gates: the next one of these fails the build on the push that introduces it. Every size below is measured.

1. Every JSON loader leaked its parsed document. Four json_load_file calls in src/ and not one json_decref anywhere in the library:

   Loader	Site	Leaked per call
   akgl_sprite_load_json	src/sprite.c:140	~1,500 bytes
   akgl_character_load_json	src/character.c:232	~2,150 bytes
   akgl_tilemap_load	src/tilemap.c:693	~9,000 bytes (2x2 fixture map)
   akgl_registry_load_properties	src/registry.c:134	not exercised by any test

   Blast radius: every asset load, forever. A 128x128 map leaks on the order of a megabyte per load, and this is the one item in this list that grew without bound. akgl_registry_load_properties needed its loop moved inside the ATTEMPT block first: props is a borrowed reference into the document and was read after the block ended. The test is the memcheck run -- nothing in the public API can observe a jansson refcount, and inventing a hook to prove it would be testing the test.

2. akgl_get_property read up to 4 KiB past the end of the property value. It copied a fixed AKGL_MAX_STRING_LENGTH bytes out of whatever SDL_GetStringProperty returns, and what it returns is an SDL_strdup of the value -- four bytes for "0.0". Valgrind reported an invalid read on every call. This had been in registry.h as a @note about the copy being "a fixed #AKGL_MAX_STRING_LENGTH bytes rather than the length" -- filed as waste. It was not waste, it was an out-of-bounds read, and on a value that lands at the end of a page it is a segfault in a getter.

3. The savegame name tables read past the end of every registry key, and wrote what they found into the file. Two consequences, and the second is the interesting one: the read can fault if the key sits at the end of a page, and whatever it reads goes into the save file, so a savegame contained up to 500 bytes of this process's heap per registered object. That is a file a player might send someone. All four iterators write through write_name_field now, and a negative-array-size typedef fails the build if any of the four widths ever outgrows the staging buffer.

4. akgl_controller_list_keyboards leaked the array SDL gives it. One SDL_free, in a CLEANUP block so a failure inside the loop cannot take the array with it. The same question was asked of every other SDL enumeration in src/controller.c; SDL_GetGamepads and SDL_GetGamepadMapping are freed too.

5. A font, once loaded, was never freed and could not be. 10,523 bytes per font. It was a gap in the API rather than only a leak: a game that switches fonts between scenes, or a tool like charviewer that reloads one while the user picks a size, had no way to give the old one back. akgl_text_unloadfont is a new public symbol; akgl_text_loadfont calls it when it replaces a live name, but only after the new font has opened, so a failed reload leaves the caller with the font they already had. What is still missing is a teardown that calls it -- #15.

6. Vendored deps/semver's own unit test leaks 188 bytes. Not libakgl's code and not libakgl's to fix. Suppressed, which is what this list said the answer would be if it ever became noise, and gating the job made it noise. The two entries in scripts/valgrind.supp name the functions rather than the file, so a rewrite of those cases stops being suppressed and comes back as a finding. They are the only entries there that hide a real leak in a program this build runs; the alternative was a fork of a vendored dependency.

Not defects, and why

• tests/util.c fixtures were reading uninitialised stack floats. Three null-pointer tests declared SDL_FRect and point fixtures without initializing them, which is sixteen "conditional jump depends on uninitialised value" findings for a test that is not about coordinates. The library was never at fault; a memory checker that reports noise gets ignored, which is the only reason this was worth touching.
• "Still reachable" at exit is not counted. SDL's global state, the hint table, the property registry and FreeType's library instance are one per process and are reclaimed by SDL_Quit / TTF_Quit. Counting them would bury the six findings above under a hundred that mean nothing.
• The GPU driver's findings are avoided rather than suppressed. Running the suite against the real driver produces thousands of findings inside amdgpu_dri.so; running it headless produces none, and headless is what the suites are written for.

Found while embedding libakgl in a consumer

Shadowing add_test() unconditionally broke every embedding consumer. Fixed in the same release it was introduced in, and kept because the CMake behaviour behind it is not obvious and will catch the next person.

CMake chains command overrides exactly one level deep. Overriding add_test makes the builtin available as _add_test; overriding it a second time rebinds _add_test to the first override and the builtin becomes unreachable to everybody, permanently -- there is no __add_test. Verified directly rather than inferred from the documentation:

function(add_test) _add_test(${ARGV}) endfunction()   # _add_test  -> builtin
function(add_test) _add_test(${ARGV}) endfunction()   # _add_test  -> the first override
if(COMMAND __add_test) ... endif()                    # absent

So two projects in one tree cannot both shadow it. akbasic shadows it first -- it has to, for libakerror and libakstdlib, which register their tests unconditionally -- and its own registrations then recursed until CMake stopped at "Maximum recursion depth of 1000 exceeded". A consumer had no way to work around it: once the builtin is gone it is gone for that project too.

The override is guarded on being top-level again. An embedded libakgl leaves add_test alone and lets its consumer suppress what it does not want -- machinery the consumer has to have anyway.

Build notes

The vendored SDL satellite libraries are built into per-project subdirectories that are not on the loader's default search path, and LD_LIBRARY_PATH is searched ahead of RPATH -- so a developer who had previously run rebuild.sh had their installed libakgl.so shadow the one under test, and a developer who had not saw every test abort before main() with "cannot open shared object file". CMakeLists.txt sets BUILD_RPATH on the library, the utility and every test target, and prepends the build tree to LD_LIBRARY_PATH for the CTest run.

API gaps that blocked akbasic

akbasic (the C port of the BASIC interpreter, source.starfort.tech/andrew/akbasic) links libakgl as a scripting engine for game authors. All ten items are resolved, and its libakgl-backed text sink, graphics backend, sound backend and input backend are written and tested.

Decisions worth keeping, because each was a fork in the road rather than an implementation detail:

• Text measurement. akgl_text_measure and _measure_wrapped sit over TTF_GetStringSize/TTF_GetStringSizeWrapped. A negative wraplength is refused with AKERR_OUTOFBOUNDS rather than passed through, because SDL_ttf reads it as a very large unsigned width and silently stops wrapping. The test font is monospaced on purpose: it lets the suite assert width("AAAA") == 4 * width("A") instead of hardcoding glyph metrics that FreeType is free to round differently.
• Drawing: colour is an argument, not state. There is no current-colour global to get out of step with the caller's own. Each call saves and restores the renderer's draw colour, so drawing a line does not change what the host's next SDL_RenderClear paints. The flood fill reads the target back, fills on the CPU, and blits only the bounding box of what changed, keeping a fixed AKGL_DRAW_MAX_FLOOD_SPANS (4096) stack of horizontal runs at file scope rather than recursing per pixel. It is therefore not reentrant -- neither is anything else that draws to a single SDL_Renderer.
• Audio: the voice table works with no device open. That is not only for embedding -- it is what makes the suite deterministic. A device pulls samples on SDL's audio thread whenever it likes, so a test that opened one and then asserted on voice state would be racing the callback. Phase is derived from the frame counter rather than accumulated, because a float increment of hz / 44100 is not exact and adding it 44100 times a second walks a held note off pitch. A voice that was never configured is audible: a zeroed voice has a sustain of 0.0, which is silence with no error to explain it, so the table defaults to a square wave at full level. Three voices summing past full scale are clamped, not scaled, so one voice plays at the level it was asked for rather than a third of it.
• The sweep steps once every 1/60 second (AKGL_AUDIO_SWEEP_TICK_HZ), because that is the rate the machine this vocabulary comes from advanced its sweep at. It divides 44100 exactly, so a step boundary always lands on a whole frame -- which is what lets the suite assert the exact frame the pitch moves on rather than a tolerance. Direction comes from the two frequencies, not from the sign of the step. A swept voice accumulates its phase instead of deriving it: deriving assumes a constant frequency, and under a sweep it jumps the waveform at every step, which is an audible click.
• Keystrokes: the ring records every SDL_EVENT_KEY_DOWN before the control-map scan, so a key bound to an actor still reaches a polling caller -- the scan returns as soon as a binding claims the event, and doing it afterwards would have lost exactly the keys a game also acts on. A full buffer drops the newest key rather than overwriting the oldest, matching the Commodore keyboard buffer. The composed text is attached to the press that is still waiting for it, tracked by a flag rather than by "whatever entry is newest": without the flag, a press dropped by a full buffer hands its text to some older key sitting at the end of the ring -- wrong in exactly the case where things are already going badly.
• akgl_render_2d_bind deliberately does not touch self->sdl_renderer, which is the whole point -- a host that already owns one keeps it, and a host that does not gets a backend whose entry points all report AKERR_NULLPOINTER instead of crashing.
• Vendored dependencies are added on both paths now, guarded by if(NOT TARGET ...), through an akgl_add_vendored_dependency(<target> <dir>) macro -- a macro rather than a function because add_subdirectory() inside a function runs in that function's variable scope. Verified by configuring and building a scratch consumer with CMAKE_DISABLE_FIND_PACKAGE_* set for all seven dependencies, so any reliance on an installed copy would have failed the configure.
• tests/headers.c is a whole suite for one #include on purpose: a second #include after the first proves nothing about the second, because by then the first has dragged its dependencies in.

Still missing for a complete BASIC vocabulary, and filed: the oscillating SOUND direction and FILTER (#58). TEMPO and the PLAY note-string parser belong in the interpreter rather than here.

akgl_collide_rectangles stays; the corner helpers did not

The collision plan's last step was to delete akgl_rectangle_points, akgl_collide_point_rectangle and akgl_collide_rectangles once the shape API landed. Two of the three went, in 0.8.0, along with akgl_Point and akgl_RectanglePoints. The third stays, and this is the reasoning rather than an oversight.

Why the two went. They were the intermediate form of an implementation that changed. akgl_collide_rectangles was eight corner-containment tests built on them; it is four span comparisons now and does not go through either. Nothing outside tests/ called them, and a point-in-rectangle test is four comparisons a caller can write without a struct conversion in front of it.

Why the third stays.

• It has callers that are correct. examples/sidescroller/player.c uses it twice, for coins and for hazards. Those are overlap questions asked from an updatefunc -- "am I touching this" -- and the right answer is a bool. Routing them through a collision shape would mean a proxy, a broad-phase insert and a narrowphase call to compute a normal and a depth that nothing reads.
• It was fixed in this same series, not left broken. It missed the cross case and truncated through akgl_Point's int members; it is exact in float32_t now. Deleting it two commits after fixing it is a strange thing to do to a caller.
• A game-level overlap question is not always a physics question. A minimap marker, a UI hit test, "is the cursor over this". None of those wants to be pushed, and none of them belongs in a collision world.

Why libakstdlib's collections are not used

aksl_HashMap, aksl_List and aksl_TreeNode exist and libakgl uses SDL property sets for every registry instead. That is not an oversight -- the registries hand SDL_PropertiesID values to callers and SDL owns the lifetime. Recorded so nobody re-derives it.

The wrappers that were adopted, and why each was worth it: aksl_fclose (an unchecked close in akgl_game_save lost buffered data silently), aksl_fgetc (fgetc(3) spells EOF and a read error the same way), aksl_snprintf at two sites that were truncating under a silenced -Wformat-truncation, and aksl_strncpy at the two src/game.c sites the fixed-width copy sweep missed. Whether to adopt the pure-arithmetic wrappers is #19.

Why deps/tg is still in the tree

deps/tg is pinned at v0.7.9 and nothing uses it. It was evaluated alongside deps/libccd for the collision work and lost, for two reasons that are properties of the library rather than preferences: it is 2D permanently (its own documentation says the z coordinate serves no purpose but export, and no predicate reads it), and its predicates return bool -- resolving a collision needs a minimum translation vector, which tg_geom_intersects cannot supply.

It is kept rather than dropped because there is one job it does that libccd structurally cannot: indexed point-in-polygon against concave polygons with holes. GJK and MPR are convex-only, always.

That is a deadline, not a permanent exemption -- #55, with #75 as the consumer that would justify it.

The ccd arena

src/collision_arena.c is one static arena of AKGL_CCD_ARENA_BYTES (64 KB) with a bump pointer, reset at the top of every akgl_collision_test. The size is a measurement, not a guess: one GJK/EPA box pair measures 7,264 bytes. Exhaustion is reported, not crashed -- ccdGJKPenetration returns -2 and akgl_collision_test raises AKGL_ERR_COLLISION with the high-water mark in the message, so the failure names its own fix. MPR, the default on the frame path, allocates nothing at all.

akgl_ccd_arena_highwater() is public so a game can assert its own ceiling. The threading constraint that follows from a single arena is #57.