Stop returning past CLEANUP, and validate the arguments every sibling validates

Closes internal-consistency items 16 and 17.

Ten *_RETURN macros sat inside ATTEMPT blocks, which return past CLEANUP and
skip every release in it. The one that mattered was the success path of
akgl_get_json_tilemap_property: it leaked two of the string pool's 256 entries
on every lookup that *found* what it was asked for, and a map load does that
several times per layer. tests/tilemap.c now runs each of its three paths --
found, absent, wrong type -- twice the pool size and asserts the pool is where
it started. Against the old code that test does not merely fail, it segfaults,
which is Defects item 30 seen from the outside: pool exhaustion arriving as a
NULL strncpy rather than as AKGL_ERR_HEAP.

Two of the conversions 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 are followed by `*collide = false;`, which would have overwritten
the hit that broke out; each corner test writes the flag itself, so that line
is gone rather than moved. The same function also released its scratch string
once per loop iteration while continuing to use it, so the slot was free while
still live -- one claim now covers the whole scan.

akgl_controller_default is the other behavioural one: its SUCCEED_RETURN was
the last statement in the ATTEMPT block, so the path that falls out of FINISH
reached the closing brace of a non-void function.

scripts/check_error_protocol.py keeps both rules enforced -- a *_RETURN inside
ATTEMPT, and a return out of a HANDLE block -- as the error_protocol test.
Neither produces a compiler diagnostic and neither fails a test run until the
pool it drains is empty, which is why both have already shipped once.

For item 17: the eight typed JSON accessors that validated their container and
then wrote through dest unconditionally now check key and dest as the two
string accessors always did; the null physics backend checks its actors like
the arcade one; and akgl_render_2d_frame_start, _frame_end and _shutdown check
self, which the first two read straight through. tests/renderer.c calls all
three with NULL, which segfaulted before.

25/25 pass, memcheck clean, reindent --check clean.

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

tests/json_helpers.c

@@ -48,6 +48,68 @@ static akerr_ErrorContext *load_fixture(void)
     SUCCEED_RETURN(e);
 }
 
+/**
+ * @brief Every accessor must refuse a NULL key or destination, not dereference it.
+ *
+ * Only the two string accessors did. The other eight validated the container
+ * and then wrote through @p dest unconditionally, so which arguments a caller
+ * could safely get wrong depended on which typed accessor they happened to
+ * call -- and the ones that crashed were the ones used most.
+ */
+akerr_ErrorContext *test_json_accessor_null_arguments(void)
+{
+    PREPARE_ERROR(e);
+    int intval = 0;
+    float floatval = 0;
+    double dblval = 0;
+    bool boolval = false;
+    json_t *jsonval = NULL;
+    akgl_String *strval = NULL;
+
+    ATTEMPT {
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_object_value(fixture, NULL, &jsonval),
+			   "object accessor with a NULL key");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_object_value(fixture, "nested", NULL),
+			   "object accessor with a NULL destination");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_boolean_value(fixture, NULL, &boolval),
+			   "boolean accessor with a NULL key");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_boolean_value(fixture, "enabled", NULL),
+			   "boolean accessor with a NULL destination");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_integer_value(fixture, NULL, &intval),
+			   "integer accessor with a NULL key");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_integer_value(fixture, "count", NULL),
+			   "integer accessor with a NULL destination");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_number_value(fixture, NULL, &floatval),
+			   "number accessor with a NULL key");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_number_value(fixture, "ratio", NULL),
+			   "number accessor with a NULL destination");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_double_value(fixture, NULL, &dblval),
+			   "double accessor with a NULL key");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_double_value(fixture, "ratio", NULL),
+			   "double accessor with a NULL destination");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_array_value(fixture, NULL, &jsonval),
+			   "array accessor with a NULL key");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_array_value(fixture, "integers", NULL),
+			   "array accessor with a NULL destination");
+
+	// The index accessors take no key, but they take a destination.
+	CATCH(e, akgl_get_json_array_value(fixture, "integers", &jsonval));
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_array_index_integer(jsonval, 0, NULL),
+			   "array index integer accessor with a NULL destination");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_array_index_object(jsonval, 0, NULL),
+			   "array index object accessor with a NULL destination");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_get_json_array_index_string(jsonval, 0, NULL),
+			   "array index string accessor with a NULL destination");
+
+	// Nothing above should have claimed a pool string on the way to
+	// refusing, which is the other half of "refuse rather than proceed".
+	TEST_ASSERT(e, strval == NULL, "a refused accessor wrote to its destination anyway");
+    } CLEANUP {
+    } PROCESS(e) {
+    } FINISH(e, true);
+    SUCCEED_RETURN(e);
+}
+
 akerr_ErrorContext *test_json_scalar_accessors(void)
 {
     PREPARE_ERROR(e);
@@ -353,6 +415,7 @@ int main(void)
 	CATCH(errctx, akgl_registry_init());
 	CATCH(errctx, load_fixture());
 
+	CATCH(errctx, test_json_accessor_null_arguments());
 	CATCH(errctx, test_json_scalar_accessors());
 	CATCH(errctx, test_json_double_value());
 	CATCH(errctx, test_json_string_accessor());

tests/physics.c

@@ -145,6 +145,18 @@ akerr_ErrorContext *test_physics_null_backend_is_inert(void)
 			   "null move with NULL self");
 	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_physics_null_collide(NULL, &actor, &reference),
 			   "null collide with NULL self");
+
+	// The actor arguments too. The arcade backend has always checked these;
+	// the null one checked only `self`, so which pointers a caller could get
+	// away with passing depended on which backend it happened to have.
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_physics_null_gravity(&backend, NULL, 1.0f),
+			   "null gravity with a NULL actor");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_physics_null_move(&backend, NULL, 1.0f),
+			   "null move with a NULL actor");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_physics_null_collide(&backend, NULL, &reference),
+			   "null collide with a NULL first actor");
+	TEST_EXPECT_STATUS(e, AKERR_NULLPOINTER, akgl_physics_null_collide(&backend, &actor, NULL),
+			   "null collide with a NULL second actor");
     } CLEANUP {
     } PROCESS(e) {
     } FINISH(e, true);

tests/renderer.c

@@ -92,6 +92,16 @@ akerr_ErrorContext *test_render_backend_without_a_renderer(void)
 	TEST_EXPECT_STATUS(errctx, AKERR_NULLPOINTER, empty.frame_end(&empty),
 			   "ending a frame on a backend with no renderer");
 
+	// And a NULL backend outright. frame_start and frame_end used to read
+	// self->sdl_renderer with no check on self at all, which is a segfault
+	// rather than an error, while draw_texture beside them checked it.
+	TEST_EXPECT_STATUS(errctx, AKERR_NULLPOINTER, akgl_render_2d_frame_start(NULL),
+			   "starting a frame on a NULL backend");
+	TEST_EXPECT_STATUS(errctx, AKERR_NULLPOINTER, akgl_render_2d_frame_end(NULL),
+			   "ending a frame on a NULL backend");
+	TEST_EXPECT_STATUS(errctx, AKERR_NULLPOINTER, akgl_render_2d_shutdown(NULL),
+			   "shutting down a NULL backend");
+
 	// Shutdown is the one that has nothing to release yet, so it succeeds.
 	TEST_EXPECT_OK(errctx, empty.shutdown(&empty), "shutting down an unused backend");
     } CLEANUP {

tests/testutil.h

@@ -20,6 +20,28 @@
 #include <SDL3/SDL.h>
 #include <akerror.h>
 #include <akgl/error.h>
+#include <akgl/heap.h>
+
+/**
+ * @brief How many pool string slots are currently claimed.
+ *
+ * The string pool is 256 entries and every loader borrows scratch strings from
+ * it, so "does this function give back what it took" is a question a test can
+ * answer directly by counting either side of a call. A leak that would take
+ * fifty map loads to show up in production shows up here on the first one.
+ */
+static inline int test_string_pool_used(void)
+{
+    int used = 0;
+    int i = 0;
+
+    for ( i = 0; i < AKGL_MAX_HEAP_STRING; i++ ) {
+	if ( akgl_heap_strings[i].refcount != 0 ) {
+	    used += 1;
+	}
+    }
+    return used;
+}
 
 /**
  * @brief Exit with a status the shell can actually see.

tests/tilemap.c

@@ -13,6 +13,100 @@
 
 #include "testutil.h"
 
+/**
+ * @brief akgl_get_json_tilemap_property must give back its scratch strings on every path.
+ *
+ * It claims two pool strings per call -- one for the property name it is
+ * comparing, one for the declared type -- and used to leave the block through a
+ * `SUCCEED_RETURN` from inside `ATTEMPT` on the path where it *found* what it
+ * was asked for. That returns past `CLEANUP`, so the ordinary, successful
+ * lookup was the leaking one, at two of the pool's 256 entries a time. A map
+ * load does this several times per layer.
+ *
+ * Three paths, run more times than the pool has entries: found, absent, and
+ * present-but-wrong-type. Against the old code the found loop exhausts the pool
+ * and comes back AKGL_ERR_HEAP long before it finishes.
+ */
+akerr_ErrorContext *test_tilemap_property_lookup_releases_strings(void)
+{
+    PREPARE_ERROR(errctx);
+    json_t *jsondoc = NULL;
+    json_error_t jsonerr;
+    akgl_String *pathstr = NULL;
+    int baseline = 0;
+    int propnum = 0;
+    int i = 0;
+
+    ATTEMPT {
+	CATCH(errctx, akgl_heap_next_string(&pathstr));
+	snprintf(
+	    (char *)&pathstr->data,
+	    AKGL_MAX_STRING_LENGTH,
+	    "%s%s",
+	    SDL_GetBasePath(),
+	    "assets/snippets/test_tilemap_get_json_tilemap_property.json"
+	    );
+	jsondoc = json_load_file((char *)&pathstr->data, 0, (json_error_t *)&jsonerr);
+	FAIL_ZERO_BREAK(errctx, jsondoc, AKERR_NULLPOINTER, "Failure loading json fixture: %s", (char *)jsonerr.text);
+
+	baseline = test_string_pool_used();
+
+	// The success path. Twice the pool size, so a leak of even one entry
+	// per call cannot finish.
+	for ( i = 0; i < (AKGL_MAX_HEAP_STRING * 2); i++ ) {
+	    CATCH(errctx, akgl_get_json_properties_integer(jsondoc, "state", &propnum));
+	}
+	TEST_ASSERT(
+	    errctx,
+	    test_string_pool_used() == baseline,
+	    "%d successful property lookups left %d pool strings claimed, expected %d",
+	    (AKGL_MAX_HEAP_STRING * 2),
+	    test_string_pool_used(),
+	    baseline);
+
+	// The absent path, which reports AKERR_KEY from after FINISH.
+	for ( i = 0; i < (AKGL_MAX_HEAP_STRING * 2); i++ ) {
+	    TEST_EXPECT_STATUS(
+		errctx,
+		AKERR_KEY,
+		akgl_get_json_properties_integer(jsondoc, "no_such_property", &propnum),
+		"looking up a property the object does not have");
+	}
+	TEST_ASSERT(
+	    errctx,
+	    test_string_pool_used() == baseline,
+	    "absent-property lookups left %d pool strings claimed, expected %d",
+	    test_string_pool_used(),
+	    baseline);
+
+	// The wrong-type path, which fails from inside the ATTEMPT block with
+	// both scratch strings already claimed.
+	for ( i = 0; i < (AKGL_MAX_HEAP_STRING * 2); i++ ) {
+	    TEST_EXPECT_STATUS(
+		errctx,
+		AKERR_TYPE,
+		akgl_get_json_properties_integer(jsondoc, "character", &propnum),
+		"reading a string property as an int");
+	}
+	TEST_ASSERT(
+	    errctx,
+	    test_string_pool_used() == baseline,
+	    "wrong-type lookups left %d pool strings claimed, expected %d",
+	    test_string_pool_used(),
+	    baseline);
+    } CLEANUP {
+	if ( jsondoc != NULL ) {
+	    json_decref(jsondoc);
+	    jsondoc = NULL;
+	}
+	if ( pathstr != NULL ) {
+	    IGNORE(akgl_heap_release_string(pathstr));
+	}
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    SUCCEED_RETURN(errctx);
+}
+
 akerr_ErrorContext *test_tilemap_akgl_get_json_tilemap_property(void)
 {
     PREPARE_ERROR(errctx);
@@ -438,6 +532,7 @@ int main(void)
 	CATCH(errctx, akgl_character_load_json("assets/testcharacter.json"));
 
 	CATCH(errctx, test_tilemap_akgl_get_json_tilemap_property());
+	CATCH(errctx, test_tilemap_property_lookup_releases_strings());
 	CATCH(errctx, test_akgl_tilemap_compute_tileset_offsets());
 	CATCH(errctx, test_akgl_tilemap_load_layer_objects());
 	CATCH(errctx, test_akgl_tilemap_load_layer_tile());