revert 3a8478131a

revert Register line-limit fixtures as expected failures

This issue is not something this branch should solve

.gitea/workflows/ci.yaml

@@ -26,14 +26,42 @@ jobs:
           # skipped for the same reason: our CMakeLists declares akerror::akerror
           # first and libakstdlib guards on if(NOT TARGET ...).
           submodules: true
+      # moreutils is load-bearing, not incidental: it supplies errno(1), which
+      # deps/libakerror/scripts/generrno.sh shells out to at build time to
+      # generate its errno name table and to stamp AKERR_LAST_ERRNO_VALUE into
+      # the generated akerror.h.
+      #
+      # Its absence does not fail the build, which is what made this expensive to
+      # find. The script prints "errno: command not found" twice, emits an empty
+      # akerr_init_errno() so no errno ever gets a name, and substitutes an empty
+      # AKERR_LAST_ERRNO_VALUE -- so every code in libakerror's reserved band
+      # collapses from (134 + n) to ( + n), i.e. to n. AKERR_OUTOFBOUNDS is
+      # (AKERR_LAST_ERRNO_VALUE + 2), so it becomes literally 2, and ERR(2)
+      # answers "Out Of Bounds Error" where ENOENT's "No such file or directory"
+      # belongs. That is the docs_examples failure at docs/15-error-codes.md:105
+      # that this job carried on every run since #2.
       - name: dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y cmake gcc
+          sudo apt-get install -y cmake gcc moreutils
+      # --parallel 2 rather than a bare --parallel, and that bound is measured
+      # rather than cautious. All five jobs in this file say runs-on:
+      # ubuntu-latest and land on the same runner, so a bare --parallel asks for
+      # nproc compilers *per job* and the runner is handed five times that at
+      # once. Run #30 never showed it because akgl_build and coverage were still
+      # dying early; run #31 was the first push on which all five did real work
+      # simultaneously, and the sanitizers job went from a 55-second link phase
+      # to a 14-minute one -- individual `Linking C executable` steps taking two
+      # minutes each, starting at the exact second akgl_build began its SDL tree
+      # -- before the runner's Docker daemon fell over outright and took the job
+      # with it. That is memory exhaustion, and the only lever on it is the
+      # number of concurrent compiler and linker processes. Applied at all four
+      # build sites for the same reason; mutation_test drives its own builds
+      # through the harness and is not bounded here.
       - name: build
         run: |
           cmake -S . -B build
-          cmake --build build --parallel
+          cmake --build build --parallel 2
       # The suite is 78 cases: 41 golden files byte-compared against the Go
       # reference's own corpus (checked in at tests/reference/, see its README),
       # 9 local golden cases for verbs the reference never implemented, 25 unit
@@ -74,7 +102,7 @@ jobs:
       - name: dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y cmake gcc
+          sudo apt-get install -y cmake gcc moreutils
       # The whole suite under ASan and UBSan, golden files included. This is the
       # gate libakstdlib's TODO.md section 1 calls its highest-value missing item
       # -- worth having here from the start, because this library is all fixed
@@ -84,7 +112,7 @@ jobs:
           cmake -S . -B build-asan \
             -DAKBASIC_SANITIZE=ON \
             -DCMAKE_BUILD_TYPE=Debug
-          cmake --build build-asan --parallel
+          cmake --build build-asan --parallel 2
           ctest --test-dir build-asan --output-on-failure
       - run: echo "🍏 This job's status is ${{ job.status }}."
 
@@ -98,7 +126,7 @@ jobs:
       - name: dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y cmake gcc gcovr
+          sudo apt-get install -y cmake gcc gcovr moreutils
       # The gate is a ratchet, not a target: src/ sits at 94.6% of lines and
       # 98.6% of functions, so 90 fails on a real regression (a test deleted, or
       # new untested code added) without tripping over rounding.
@@ -124,7 +152,7 @@ jobs:
           cmake -S . -B build-coverage \
             -DAKBASIC_COVERAGE=ON \
             -DCMAKE_BUILD_TYPE=Debug
-          cmake --build build-coverage --parallel
+          cmake --build build-coverage --parallel 2
           ctest --test-dir build-coverage --output-on-failure
           mkdir -p build-coverage/coverage
           gcovr --root . --filter 'src/.*' \
@@ -134,9 +162,21 @@ jobs:
             --fail-under-line 90
       # Publish even when the threshold gate fails, so the uncovered lines are
       # visible -- each one is a missing test.
+      #
+      # @v3, not @v4, and that is Gitea rather than preference. @v4 bundles
+      # @actions/artifact v2, whose isGhes() treats any GITHUB_SERVER_URL that is
+      # not github.com as GitHub Enterprise Server and refuses outright:
+      # "GHESNotSupportedError: @actions/artifact v2.0.0+, upload-artifact@v4+
+      # and download-artifact@v4+ are not currently supported on GHES". @v3 uses
+      # the older artifact API, which this forge does implement.
+      #
+      # This never showed before because the step had nothing to upload: gcovr
+      # was never reached, so the step warned "No files were found" and passed.
+      # Fixing the suite is what first gave it a real file to refuse. Same class
+      # of accommodation as the annotate_only flag on the junit reporter above.
       - name: upload coverage reports
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with:
           name: code-coverage
           path: build-coverage/coverage/
@@ -161,22 +201,56 @@ jobs:
       # embedded it takes a find_package path instead, so our CMakeLists declares
       # those targets first and needs the submodules present. Six of them, none
       # recursive. Filed upstream as libakgl API-gap item 5.
+      #
+      # Eight, not six: deps/libccd and deps/clay were missing and are not
+      # optional. libakgl does not add_subdirectory either of them -- their own
+      # CMakeLists are unusable as subprojects -- it compiles them into itself,
+      # so nothing declares them and configuration dies late with "File
+      # deps/libccd/src/ccd/config.h.cmake.in does not exist" at
+      # deps/libakgl/CMakeLists.txt:282. clay is the same shape one step later:
+      # deps/clay/clay.h is on the include path and installed.
+      #
+      # deps/tg is a real submodule of libakgl and is deliberately not here --
+      # nothing in its CMakeLists references it. libakerror and libakstdlib are
+      # skipped for the reason the checkout note above gives.
       - name: libakgl dependencies
         run: |
           git -C deps/libakgl submodule update --init \
             deps/SDL deps/SDL_image deps/SDL_mixer deps/SDL_ttf \
-            deps/jansson deps/semver
+            deps/jansson deps/semver deps/libccd deps/clay
       # libfreetype-dev and libharfbuzz-dev are load-bearing, not incidental.
       # SDL_ttf prefers the system copies -- it reports "Using system freetype
       # library" and links libfreetype.so.6 -- and without them it would reach
       # for deps/SDL_ttf/external/freetype, which the checkout above
       # deliberately does not clone. Installing two dev packages is much cheaper
       # than cloning freetype and harfbuzz.
+      #
+      # The X11 dev packages are the other half, and they are what this job has
+      # been dying on since run #2 -- it has never once been green. SDL_X11 and
+      # its nine sub-options default ON on Linux, and CheckX11() in
+      # deps/SDL/cmake/sdlchecks.cmake calls SDL_missing_dependency() -- a hard
+      # CMake error, not a downgrade -- for any one of them whose header is
+      # absent. The runner image carries libx11-dev (X11/XKBlib.h resolved) but
+      # none of the extension packages, so configuration stopped at the first of
+      # the nine: "Couldn't find dependency package for XCURSOR".
+      #
+      # Turning the missing ones OFF would also configure, and is the wrong
+      # answer: the point of this job is that an AKGL build is a real SDL
+      # program, and a real SDL program on Linux builds the X11 backend. The
+      # tests still run headless under SDL_VIDEODRIVER=dummy -- see the env block
+      # below -- so this buys a faithful build, not a display.
+      #
+      # The list is SDL's own, from deps/SDL/docs/README-linux.md, reduced to the
+      # X11 entries: the audio, Wayland, KMSDRM and Vulkan backends all degrade
+      # to "not found" and skip themselves rather than erroring, so they cost
+      # nothing to leave out. Nine packages, all in noble.
       - name: dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y cmake gcc g++ pkg-config \
-            libfreetype-dev libharfbuzz-dev
+          sudo apt-get install -y cmake gcc g++ pkg-config moreutils \
+            libfreetype-dev libharfbuzz-dev \
+            libx11-dev libxext-dev libxcursor-dev libxi-dev libxfixes-dev \
+            libxrandr-dev libxss-dev libxtst-dev libxkbcommon-dev
       # The akgl-backed half: the text sink and the graphics, audio and input
       # backends, the standalone SDL frontend, and the two suites that drive
       # them against a real software renderer and read the pixels back.
@@ -194,7 +268,7 @@ jobs:
       - name: build with libakgl
         run: |
           cmake -S . -B build-akgl -DAKBASIC_WITH_AKGL=ON
-          cmake --build build-akgl --parallel
+          cmake --build build-akgl --parallel 2
       # Dummy video and audio drivers, set per test by CMakeLists rather than in
       # this job's environment, because an AKGL build of `basic` is now an SDL
       # program and the golden cases run *it*: forty-one real windows is not what
@@ -256,7 +330,7 @@ jobs:
       - name: dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y cmake gcc python3
+          sudo apt-get install -y cmake gcc python3 moreutils
       # Verify the tests actually catch bugs: break the library many ways and
       # confirm the suite fails. This matters more here than in an ordinary C
       # library, because the akerror control-flow macros expand at their call

.gitea/workflows/release.yaml

@@ -70,10 +70,14 @@ jobs:
           # corpus is part of what kills mutants and it is checked in now, so
           # that is libakerror and libakstdlib and nothing else.
           submodules: true
+      # moreutils for errno(1), which deps/libakerror's scripts/generrno.sh needs
+      # to generate its errno table. Without it the generated table is empty and
+      # every AKERR_* code collapses onto a low integer -- see the long note on
+      # ci.yaml's cmake_build job for what that breaks and how it presents.
       - name: dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y cmake gcc python3
+          sudo apt-get install -y cmake gcc python3 moreutils
       # The whole akbasic-owned src/ tree. ci.yaml runs a two-file subset on every
       # push; this is the one that actually covers the interpreter.
       #

CLAUDE.md

@@ -26,7 +26,7 @@ scripting engine for game authors.
 | [the issue tracker](https://source.starfort.tech/andrew/akbasic/issues) | **Outstanding defects and gaps.** Labelled by kind and blast radius; `status::grooming` means the scope is not settled yet |
 | [`TODO.md`](TODO.md) | The record: settled design decisions, the deviation register, defects already fixed, and the reasoning behind the measurements. §0.1 first — it retires the byte-for-byte fidelity constraint several later sections were written on |
 | [`README.md`](README.md) | What the project is and why, for somebody who has not seen it |
-| [`docs/`](docs/README.md) | The language itself: eighteen chapters, verb and function reference. [Chapter 14](docs/14-architecture.md) is the interpreter's architecture — the step loop, the pools, the two kinds of error, and how to debug it. [Chapter 15](docs/15-error-codes.md) is the error-code appendix. [Chapters 17](docs/17-tutorial-breakout.md) and [18](docs/18-tutorial-breakout-artwork.md) are tutorials that build the games in `examples/breakout/` |
+| [`docs/`](docs/README.md) | The language itself: twenty-one chapters, verb and function reference. [Chapter 14](docs/14-architecture.md) is the interpreter's architecture — the step loop, the pools, the two kinds of error, and how to debug it. [Chapter 15](docs/15-error-codes.md) is the error-code appendix. [Chapters 17](docs/17-tutorial-breakout.md) and [18](docs/18-tutorial-breakout-artwork.md) are tutorials that build the games in `examples/breakout/`; [Chapters 20](docs/20-tutorial-galaga.md) and [21](docs/21-tutorial-galaga-enemies.md) build the embedding host in `examples/galaga/` |
 | `deps/libakerror/AGENTS.md` | The `ATTEMPT`/`CLEANUP`/`PROCESS`/`HANDLE`/`FINISH` protocol, authoritatively |
 | `deps/libakerror/UPGRADING.md` | 1.0.0's status registry. Required before writing an error code |
 | `deps/<library>/AGENTS.md` | Per-repo rules. Read the relevant one **before editing a submodule** |

CMakeLists.txt

@@ -268,6 +268,69 @@ if(AKBASIC_BUILD_EXAMPLES)
   endforeach()
 endif()
 
+# The galaga example: a C game on libakgl with the interpreter embedded as its
+# enemy-behavior engine. Chapters 20 and 21 build it from an empty file, so it
+# is compiled and run by every AKGL build rather than rotting in a document.
+# The asset, script and font paths are baked in so the smoke test can launch
+# from any working directory; --assets and --script override them at runtime.
+if(AKBASIC_BUILD_EXAMPLES AND AKBASIC_WITH_AKGL)
+  add_executable(akbasic_example_galaga
+    examples/galaga/main.c
+    examples/galaga/script.c
+    examples/galaga/enemies.c
+    examples/galaga/player.c)
+  target_compile_options(akbasic_example_galaga PRIVATE -Wall -Wextra)
+  target_compile_definitions(akbasic_example_galaga PRIVATE
+    GALAGA_ASSET_DIR="${CMAKE_CURRENT_SOURCE_DIR}/examples/galaga/assets"
+    GALAGA_SCRIPT_PATH="${CMAKE_CURRENT_SOURCE_DIR}/examples/galaga/galaga.bas"
+    GALAGA_FONT_PATH="${CMAKE_CURRENT_SOURCE_DIR}/assets/fonts/C64_Pro_Mono-STYLE.ttf")
+  target_link_libraries(akbasic_example_galaga PRIVATE akbasic akgl
+    SDL3::SDL3 SDL3_ttf::SDL3_ttf SDL3_image::SDL3_image)
+  akbasic_instrument(akbasic_example_galaga)
+  # Ten seconds of scripted play under the headless drivers: the script boots,
+  # a wave enters and forms, the autoplay pilot shoots at it, and the program
+  # tears down and exits 0. A tutorial that stops working fails here rather
+  # than in front of a reader.
+  _add_test(NAME example_galaga COMMAND akbasic_example_galaga --frames 600 --autoplay)
+  _set_tests_properties(example_galaga PROPERTIES TIMEOUT 120
+    ENVIRONMENT "SDL_VIDEODRIVER=dummy;SDL_AUDIODRIVER=dummy;SDL_RENDER_DRIVER=software")
+
+  # The boundary's round-trip test: links the real script.c and the real
+  # galaga.bas, and fails the moment the two sides of the interop disagree.
+  add_executable(akbasic_example_galaga_interop
+    examples/galaga/interop_test.c
+    examples/galaga/script.c)
+  target_compile_options(akbasic_example_galaga_interop PRIVATE -Wall -Wextra)
+  target_compile_definitions(akbasic_example_galaga_interop PRIVATE
+    GALAGA_SCRIPT_PATH="${CMAKE_CURRENT_SOURCE_DIR}/examples/galaga/galaga.bas")
+  target_link_libraries(akbasic_example_galaga_interop PRIVATE akbasic akgl
+    SDL3::SDL3 m)
+  akbasic_instrument(akbasic_example_galaga_interop)
+  _add_test(NAME example_galaga_interop COMMAND akbasic_example_galaga_interop)
+  _set_tests_properties(example_galaga_interop PROPERTIES TIMEOUT 120)
+
+  # Regenerating the game figures in docs/ is a deliberate act, never part of
+  # a build, for the same reason docs_screenshots is: the PNGs are checked in.
+  # Wall-clock dt makes each regeneration differ by a few pixels of starfield,
+  # so expect a binary diff every time this runs; commit one only when the
+  # content changed on purpose. (docs_galaga_figures, not docs_game_figures:
+  # the libakgl submodule already owns that target name.)
+  add_custom_target(docs_galaga_figures
+    COMMAND ${CMAKE_COMMAND} -E env SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy
+            SDL_RENDER_DRIVER=software
+            $<TARGET_FILE:akbasic_example_galaga> --frames 40
+            --screenshot "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/galaga-title.png"
+            --screenshot-frame 30
+    COMMAND ${CMAKE_COMMAND} -E env SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy
+            SDL_RENDER_DRIVER=software
+            $<TARGET_FILE:akbasic_example_galaga> --autoplay --frames 370
+            --screenshot "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/galaga-wave.png"
+            --screenshot-frame 360
+    DEPENDS akbasic_example_galaga
+    COMMENT "Regenerating the galaga figures in docs/images"
+    VERBATIM)
+endif()
+
 # ---------------------------------------------------------------------------
 # Tests.
 #

README.md

@@ -126,7 +126,7 @@ version are catalogued in [`TODO.md`](TODO.md) and summarised for a BASIC progra
 
 | | |
 |---|---|
-| [`docs/`](docs/README.md) | The guide: eighteen chapters, the language then each hardware area then a reference section for every verb and function, [Chapter 14](docs/14-architecture.md) on the interpreter's own architecture, [Chapter 15](docs/15-error-codes.md) listing every error code, and [Chapters 17](docs/17-tutorial-breakout.md) and [18](docs/18-tutorial-breakout-artwork.md) building a whole game twice |
+| [`docs/`](docs/README.md) | The guide: twenty-one chapters, the language then each hardware area then a reference section for every verb and function, [Chapter 14](docs/14-architecture.md) on the interpreter's own architecture, [Chapter 15](docs/15-error-codes.md) listing every error code, [Chapters 17](docs/17-tutorial-breakout.md) and [18](docs/18-tutorial-breakout-artwork.md) building a whole game twice, and [Chapters 20](docs/20-tutorial-galaga.md) and [21](docs/21-tutorial-galaga-enemies.md) building a C game that embeds the interpreter |
 | [`MAINTENANCE.md`](MAINTENANCE.md) | For contributors and maintainers: the documentation-example harness, the three test lists, mutation testing, error-code allocation, style |
 | [`TODO.md`](TODO.md) | Outstanding defects, with file, line and consequence |
 | [`tests/reference/README.md`](tests/reference/README.md) | Where the golden corpus came from, and the rule for changing it |

docs/10-embedding.md

@@ -100,6 +100,50 @@ bounded run is usually inside a `FOR` or `GOSUB` body, and a variable created th
 dies when the body pops — silently, with the script reading it correctly right up until
 it stops.
 
+## Calling a function every frame
+
+`akbasic_runtime_call_function()` calls a `DEF` by name with values you already
+hold — the entry point a game loop wants. A host that calls it repeatedly signs
+up for three rules the one-shot examples never meet:
+
+```c wrap=hostcalls
+CATCH(errctx, akbasic_runtime_call_function(&SCRIPT, "THINK", argp, 1, &result));
+/* ...consume the result... */
+CATCH(errctx, akbasic_environment_zero(SCRIPT.environment));
+```
+
+1. **Reset the value scratch after every call, once the result is consumed.**
+   Each call parks its result in the caller environment's per-line scratch
+   (`AKBASIC_MAX_VALUES` slots), and a host calling in a loop never crosses the
+   line boundary that would reset it. Skip the `akbasic_environment_zero()` and
+   the pool drains — measured at under two frames of forty calls — after which
+   every call fails with `Maximum values per line reached`. The reset also
+   invalidates `result`, which is why it comes after the consumption.
+2. **Force RUN mode once after the boot run.** A multi-line `DEF` body only
+   runs while the runtime is in RUN mode, and by the time a host can call, the
+   program that filed the definitions has ended. One
+   `akbasic_runtime_set_mode(&SCRIPT, AKBASIC_MODE_RUN)` after
+   `akbasic_runtime_run()` makes the bodies run, and the mode stays put because
+   nothing steps the runtime between calls. Issue #8 tracks making this
+   unnecessary.
+3. **Revive after a script error, deliberately.** A BASIC-level error inside a
+   called body reports through the sink, answers a stale value, and latches:
+   the runtime leaves RUN mode and every later call does nothing. When your
+   policy is to absorb the error and keep calling — a game marking one actor
+   dumb rather than killing the frame — the revival is two calls:
+   `akbasic_runtime_clear_error()`, then `akbasic_runtime_set_mode(RUN)` again.
+   The latch is deliberate for *programs* — the first error ends a run, once,
+   with one line — so nothing clears it for you.
+
+Do not pass structures as per-frame arguments. A structure or pointer parameter
+spends a value-pool slot on every call and the pool never reclaims, so the
+interface dies after about a thousand calls — issue #36 has the measurements.
+Bind the instance once with `akbasic_host_bind()` and point it at each object
+with `akbasic_host_rebind()` ([Chapter 16](16-structures.md)), which spends
+nothing per call. The GALAGA tutorial ([Chapters 20](20-tutorial-galaga.md)
+and [21](21-tutorial-galaga-enemies.md)) is this whole recipe as a working
+game, forty calls a frame.
+
 ## Where the output goes
 
 `PRINT` writes through an `akbasic_TextSink`, which is a record of function pointers plus

docs/17-tutorial-breakout.md

@@ -685,9 +685,9 @@ seconds asks for fifty frames a second.
 ### Why `GOTO` rather than `DO ... LOOP`
 
 A `DO ... LOOP` around the frame would read better, and it is not usable here: **a `GOTO`
-that jumps out of a `FOR` or a `DO` does not release the loop's scope.** There are 32
+that jumps out of a `FOR` or a `DO` does not release the loop's scope.** There are 12
 scopes, so a game that leaves its main loop once per lost life stops on the
-thirty-second one:
+twelfth one:
 
 ```basic
 N# = 0
@@ -700,7 +700,7 @@ PRINT "SURVIVED " + N#
 ```
 
 ```output
-? 3 : PARSE ERROR Environment pool exhausted at line 3 (32 in use)
+? 3 : PARSE ERROR Environment pool exhausted at line 3 (12 in use)
 
 ```
 

docs/20-tutorial-galaga.md

@@ -0,0 +1,849 @@
+# 20. Tutorial: GALAGA — a C engine with a BASIC brain
+
+This chapter and [Chapter 21](21-tutorial-galaga-enemies.md) build a GALAGA-style
+fixed shooter from an empty file. The engine — window, starfield, bullets,
+collision, score, screens — is C on libakgl. The enemies think in BASIC: one
+script of `DEF` functions is called once per enemy per frame, and it reads and
+writes the engine's own structures with no marshalling in either direction.
+This chapter builds the engine and proves the boundary works; the next one
+fills in the data structures and the AI.
+
+The split is the point. Everything mechanical stays compiled, and everything an
+enemy *decides* is a text file you can edit and re-run without rebuilding. It is
+an academic exercise in *how* such an embed is done, not a claim that it is the
+best way to write a GALAGA.
+
+This is what the two chapters build:
+
+![A full wave: four green bosses, two rows of butterflies, bees still streaming into the grid, the player firing](images/galaga-wave.png)
+
+The finished program is [`examples/galaga/`](../examples/galaga/): four C files,
+one `galaga.bas`, and the assets. You do not need it to follow along, but it is
+the same program assembled.
+
+```sh norun
+$ cmake -S . -B build-akgl -DAKBASIC_WITH_AKGL=ON
+$ cmake --build build-akgl --target akbasic_example_galaga
+$ ./build-akgl/akbasic_example_galaga
+```
+
+| Key | Does |
+|---|---|
+| left / right | move the ship |
+| space | fire — two shots on screen at a time, the classic rule |
+| return | choose a menu entry |
+
+## What you will do
+
+- **[Step 1](#step-1-open-a-window)** — open a window, in the one startup order
+  that works
+- **[Step 2](#step-2-scatter-a-starfield)** — scatter a starfield and scroll it,
+  with no parallax machinery at all
+- **[Step 3](#step-3-put-a-ship-on-screen)** — put a ship on screen from a
+  sprite and a character file, and drive it from the keyboard
+- **[Step 4](#step-4-shots-and-collision)** — spawn shots from the actor heap
+  and collide them by hand
+- **[Step 5](#step-5-boot-the-interpreter)** — link the interpreter in, load a
+  script of definitions, and call one from C
+- **[Step 6](#step-6-the-update-hook)** — replace an actor's update hook so its
+  every frame is a BASIC call
+- **[Step 7](#step-7-first-light)** — watch one enemy move under BASIC control,
+  and read the same numbers from both sides
+- **[Step 8](#step-8-screens)** — add the title, game over and victory screens
+- **[Step 9](#step-9-run-it-headless)** — run the whole game headless, so CI can
+  play it every night
+
+Each step compiles and runs. The C fragments quote the finished example; the
+file layout there — `main.c` for the harness, `script.c` for the boundary,
+`enemies.c` and `player.c` for the actors — is a good one to copy.
+
+---
+
+## Step 1: Open a window
+
+**Goal: a black window with a title, from the canonical startup order.**
+
+libakgl has one startup sequence that works, documented at the top of its
+`include/akgl/game.h` and walked through in its own tutorial (libakgl
+docs/20-tutorial-sidescroller.md). The order matters twice: the screen
+properties are read by the renderer, so they must be set before it exists, and
+`akgl_game_init()` does **not** install a physics backend, so the application
+must.
+
+```c wrap=galagatypes requires=akgl
+static akerr_ErrorContext *startup(void)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, aksl_strncpy((char *)&akgl_game.name, sizeof(akgl_game.name),
+			      "akbasic galaga tutorial", sizeof(akgl_game.name) - 1));
+    PASS(errctx, aksl_strncpy((char *)&akgl_game.version, sizeof(akgl_game.version),
+			      "1.0.0", sizeof(akgl_game.version) - 1));
+    PASS(errctx, aksl_strncpy((char *)&akgl_game.uri, sizeof(akgl_game.uri),
+			      "net.aklabs.akbasic.galaga", sizeof(akgl_game.uri) - 1));
+
+    PASS(errctx, akgl_game_init());
+
+    PASS(errctx, akgl_set_property("game.screenwidth", "1280"));
+    PASS(errctx, akgl_set_property("game.screenheight", "960"));
+    PASS(errctx, akgl_render_2d_init(akgl_renderer));
+
+    FAIL_ZERO_RETURN(
+	errctx,
+	SDL_SetRenderLogicalPresentation(
+	    akgl_renderer->sdl_renderer,
+	    1280,
+	    960,
+	    SDL_LOGICAL_PRESENTATION_INTEGER_SCALE),
+	AKGL_ERR_SDL,
+	"%s",
+	SDL_GetError()
+	);
+    akgl_camera->x = 0.0f;
+    akgl_camera->y = 0.0f;
+    akgl_camera->w = 1280.0f;
+    akgl_camera->h = 960.0f;
+
+    PASS(errctx, akgl_physics_init_null(akgl_physics));
+    SUCCEED_RETURN(errctx);
+}
+```
+
+Three of those lines deserve their reasons.
+
+**The view is 1280x960 because the artwork is ~100 pixels wide.** libakgl draws
+a sprite at the sprite's own size — `akgl_Actor.scale` is overwritten every
+frame, so there is no way to draw one smaller (libakgl docs/12-actors.md) — and
+a ten-column formation of 100-pixel ships needs 1120 pixels plus margins. The
+view is sized to the art rather than the art resized to a view.
+
+**`akgl_physics_init_null()` is not optional.** Skip it and the first
+`akgl_game_update()` calls through a NULL `simulate` pointer. Null physics
+accepts every call and moves nothing, which is exactly right here: whatever
+writes `x` and `y` directly is the mover, and in this game that will be BASIC.
+
+**Error handling is the house protocol.** Every function returns
+`akerr_ErrorContext *`, `PASS` propagates, `ATTEMPT`/`CATCH`/`CLEANUP` brackets
+anything that must unwind. libakgl's docs/04-errors.md teaches it; this chapter
+just uses it, with two rules that keep the fragments compiling: **`CATCH` is
+only legal inside an `ATTEMPT` block, and `PASS` everywhere else** — swap them
+and the compiler objects about a stray `break` — and `main()` alone ends its
+block with `FINISH_NORETURN(errctx)` instead of `FINISH`, because `FINISH`
+expands a `return` of the context that an `int`-returning function cannot
+compile:
+
+```c wrap=galagatypes requires=akgl
+static int FAILED = 0;
+
+int main(int argc, char *argv[])
+{
+    PREPARE_ERROR(errctx);
+
+    (void)argc; (void)argv;
+    ATTEMPT {
+	/* CATCH each stage in order: startup, assets, the script boot,
+	 * the spawns, then the frame loop. */
+    } CLEANUP {
+	/* ...teardown, every call wrapped in IGNORE()... */
+    } PROCESS(errctx) {
+    } HANDLE_DEFAULT(errctx) {
+	LOG_ERROR_WITH_MESSAGE(errctx, "galaga could not run");
+	/* Set a flag rather than returning: leaving a HANDLE block early
+	 * skips FINISH's release and leaks the context's pool slot. */
+	FAILED = 1;
+    } FINISH_NORETURN(errctx);
+    return FAILED;
+}
+```
+
+The status codes this game raises are `AKERR_NULLPOINTER`,
+`AKERR_VALUE`, `AKERR_KEY`, `AKERR_IO`, `AKERR_OUTOFBOUNDS`, `AKGL_ERR_SDL`
+and `AKGL_ERR_HEAP` — there is no code this tutorial invents.
+
+The includes the engine files draw on, so nothing later has to be guessed —
+the SDL satellites use their own prefixes (`SDL3_ttf/SDL_ttf.h`, not
+`SDL3/SDL_ttf.h`):
+
+```c wrap=galagatypes requires=akgl
+#include <stdbool.h>
+#include <stdint.h>
+#include <string.h>
+
+#include <SDL3/SDL.h>
+#include <SDL3_image/SDL_image.h>
+#include <SDL3_ttf/SDL_ttf.h>
+
+#include <akerror.h>
+#include <akstdlib.h>
+
+#include <akgl/actor.h>
+#include <akgl/character.h>
+#include <akgl/controller.h>
+#include <akgl/draw.h>
+#include <akgl/error.h>
+#include <akgl/game.h>
+#include <akgl/heap.h>
+#include <akgl/physics.h>
+#include <akgl/registry.h>
+#include <akgl/renderer.h>
+#include <akgl/sprite.h>
+#include <akgl/text.h>
+#include <akgl/ui.h>
+#include <akgl/util.h>
+```
+
+The frame loop is the standard bracket, with one addition you will meet in
+Step 6 — for now, events in, world drawn, frame out:
+
+```c wrap=galagahost requires=akgl
+while ( SDL_PollEvent(&event) == true ) {
+    CATCH(errctx, akgl_controller_handle_event((void *)&akgl_game.state, &event));
+}
+CATCH(errctx, akgl_renderer->frame_start(akgl_renderer));
+CATCH(errctx, akgl_game_update(NULL));
+CATCH(errctx, akgl_renderer->frame_end(akgl_renderer));
+```
+
+`akgl_game_update(NULL)` is update-every-actor, step-the-physics,
+draw-the-world. It neither clears nor presents; the `frame_start` and
+`frame_end` calls own that.
+
+## Step 2: Scatter a starfield
+
+**Goal: a scrolling two-depth starfield, from an array and one draw call.**
+
+No parallax facility exists in libakgl and none is needed. A fixed array of
+stars, advanced per frame and drawn with `akgl_draw_point()` between
+`frame_start` and `akgl_game_update()`, is the whole feature. Two speed bands
+give the depth for free — the slow band reads as far away:
+
+```c wrap=galagatypes requires=akgl
+#define GALAGA_STARS 96
+
+static struct
+{
+    float x;
+    float y;
+    float speed;
+    Uint8 bright;
+} STARS[GALAGA_STARS];
+
+static akerr_ErrorContext *starfield_draw(float dt)
+{
+    SDL_Color color = { 255, 255, 255, 255 };
+    int i = 0;
+    PREPARE_ERROR(errctx);
+
+    for ( i = 0; i < GALAGA_STARS; i++ ) {
+	STARS[i].y += STARS[i].speed * dt;
+	if ( STARS[i].y > 960.0f ) {
+	    STARS[i].y -= 960.0f;
+	}
+	color.r = STARS[i].bright;
+	color.g = STARS[i].bright;
+	color.b = STARS[i].bright;
+	PASS(errctx, akgl_draw_point(akgl_renderer, STARS[i].x, STARS[i].y, color));
+    }
+    SUCCEED_RETURN(errctx);
+}
+```
+
+Seed the array once at startup — even indexes slow and dim (speed 40, bright
+110), odd indexes fast and bright (speed 110, bright 220) — and the effect is
+done. A point is exactly one pixel (libakgl docs/09-drawing.md).
+
+## Step 3: Put a ship on screen
+
+**Goal: a player actor, drawn from a character file, moving on key input.**
+
+The art is Kenney's Space Shooter pack, CC0, used byte for byte — see
+[`examples/galaga/assets/art/PROVENANCE.md`](../examples/galaga/assets/art/PROVENANCE.md)
+for what each file is. An actor gets its looks from a **character**, which maps
+actor state words to **sprites** (libakgl docs/10 and 12). Both are JSON; load
+sprites first, because a character names its sprites and a character loaded
+first fails on the first name it cannot find.
+
+These are the names, so the loading lists and every
+`akgl_actor_set_character()` call in both chapters agree — each `sprite_*.json`
+and `character_*.json` lives in `assets/`:
+
+| Character | Sprite(s) it maps | Worn by |
+|---|---|---|
+| `galaga_player` | `galaga_player` | the ship |
+| `galaga_bee` | `galaga_bee` | bees |
+| `galaga_butterfly` | `galaga_butterfly` | butterflies |
+| `galaga_boss` | `galaga_boss`, and `galaga_boss_hurt` on state bit 13 | bosses |
+| `galaga_playershot` | `galaga_playershot` | the ship's shots |
+| `galaga_enemyshot` | `galaga_enemyshot` | enemy shots |
+| `galaga_boom` | `galaga_boom` | explosions |
+
+The spawn is four decisions after the two boilerplate calls:
+
+```c wrap=galagagame requires=akgl
+static akerr_ErrorContext *galaga_player_spawn(void)
+{
+    akgl_Actor *player = NULL;
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, akgl_heap_next_actor(&player));
+    PASS(errctx, akgl_actor_initialize(player, "player"));
+    PASS(errctx, akgl_actor_set_character(player, "galaga_player"));
+    /* AFTER initialize: it resets all seven hooks. */
+    player->updatefunc = &player_update;
+    player->movement_controls_face = false;
+    player->state = AKGL_ACTOR_STATE_ALIVE;
+    player->visible = true;
+    player->x = 590.0f;
+    player->y = 860.0f;
+
+    galaga_game.player = player;
+    SUCCEED_RETURN(errctx);
+}
+```
+
+Each of the four lines under the comment closes a trap:
+
+- **`updatefunc` after `akgl_actor_initialize()`**, never before — initialize
+  installs all seven default hooks, and a hook set first is a hook reset.
+- **`movement_controls_face = false`.** The default facing logic edits the
+  state word, a character mapping matches the **whole** word, and an actor
+  whose state matches no mapping is *silently not drawn*. Nothing here moves by
+  state bits, so facing stays out of the word entirely.
+- **`state = AKGL_ACTOR_STATE_ALIVE`** — the word the character mapping names.
+- **`visible = true`.** `akgl_actor_initialize()` does not raise it. In a
+  tilemap game the map loader copies visibility from map data; there is no map
+  here, so an actor that skips this line exists, moves, fires and collides —
+  invisibly. This one line cost this example its first screenshot.
+
+Input goes through a control map: push a control per key with handlers that set
+flags, and let the actor's update hook read the flags. A handler receives the
+map's target actor and the event, and returns through the error protocol like
+everything else — this pair is the whole pattern, repeated per key:
+
+```c wrap=galagagame requires=akgl
+static bool MOVELEFT = false;
+
+akerr_ErrorContext *left_on(akgl_Actor *obj, SDL_Event *event)
+{
+    PREPARE_ERROR(errctx);
+    (void)obj; (void)event;
+    MOVELEFT = true;
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *left_off(akgl_Actor *obj, SDL_Event *event)
+{
+    PREPARE_ERROR(errctx);
+    (void)obj; (void)event;
+    MOVELEFT = false;
+    SUCCEED_RETURN(errctx);
+}
+```
+
+(The example keeps the flags in its `galaga_Game` struct rather than statics;
+either works.) The bindings themselves are pushes onto map 0:
+
+```c wrap=galagagame requires=akgl
+static akerr_ErrorContext *galaga_player_controls(void)
+{
+    akgl_Control control;
+    PREPARE_ERROR(errctx);
+
+    memset(&control, 0, sizeof(control));
+    control.event_on = SDL_EVENT_KEY_DOWN;
+    control.event_off = SDL_EVENT_KEY_UP;
+
+    control.key = SDLK_LEFT;
+    control.handler_on = &left_on;
+    control.handler_off = &left_off;
+    PASS(errctx, akgl_controller_pushmap(0, &control));
+
+    control.key = SDLK_RIGHT;
+    control.handler_on = &right_on;
+    control.handler_off = &right_off;
+    PASS(errctx, akgl_controller_pushmap(0, &control));
+
+    control.key = SDLK_SPACE;
+    control.handler_on = &fire_on;
+    control.handler_off = &fire_off;
+    PASS(errctx, akgl_controller_pushmap(0, &control));
+
+    akgl_controlmaps[0].target = galaga_game.player;
+    SUCCEED_RETURN(errctx);
+}
+```
+
+Hand **every** polled event to `akgl_controller_handle_event()` — one that no
+control binds is not an error, it is a call that did nothing.
+
+## Step 4: Shots and collision
+
+**Goal: bullets that fly, hit, and give their actor slot back.**
+
+Bullets and collision are C forever — they are engine, not behavior. A shot is
+an actor from the same 64-slot heap pool, with its own tiny update hook: move,
+test, release.
+
+```c wrap=galagagame requires=akgl
+static akerr_ErrorContext *player_shot_update(akgl_Actor *obj)
+{
+    SDL_FRect mine;
+    SDL_FRect theirs;
+    bool hit = false;
+    int i = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj");
+    obj->y -= 900.0f * galaga_game.dt;
+    if ( obj->y < -60.0f ) {
+	galaga_game.player_shots_live -= 1;
+	PASS(errctx, akgl_heap_release_actor(obj));
+	SUCCEED_RETURN(errctx);
+    }
+
+    shot_box(obj, &mine);
+    for ( i = 0; i < GALAGA_MAX_ENEMIES; i++ ) {
+	if ( galaga_enemy_actors[i] == NULL ) {
+	    continue;
+	}
+	enemy_box(galaga_enemy_actors[i], &theirs);
+	PASS(errctx, akgl_collide_rectangles(&mine, &theirs, &hit));
+	if ( !hit ) {
+	    continue;
+	}
+	galaga_enemies[i].hp -= 1;
+	if ( galaga_enemies[i].hp <= 0 ) {
+	    PASS(errctx, kill_enemy(i));
+	}
+	galaga_game.player_shots_live -= 1;
+	PASS(errctx, akgl_heap_release_actor(obj));
+	SUCCEED_RETURN(errctx);
+    }
+    SUCCEED_RETURN(errctx);
+}
+```
+
+Four conventions worth keeping:
+
+- **`akgl_collide_rectangles()` is the whole collision system.** At most 2
+  shots x 40 enemies of axis-aligned tests per frame is noise; the full
+  `akgl_CollisionWorld` machinery earns its keep on tilemaps, not here. The
+  `shot_box`/`enemy_box` helpers inset each box from the artwork's rectangle,
+  because the PNGs carry transparent margin that should not kill anybody.
+- **Releasing is despawning.** `akgl_heap_release_actor()` unregisters the
+  actor and stops it drawing; releasing mid-sweep is safe because
+  `akgl_game_update()` re-reads each slot's refcount as it goes.
+- **Names carry a serial** — `pshot17`, not `pshot1` reused — because the actor
+  registry is keyed by name, and two live actors with one name is a fight.
+- **Spawn caps are C-side refusals.** Two player shots, eight enemy shots; the
+  spawn functions simply decline past the cap.
+
+Give the enemy shots the same shape falling downward, and the ship a sweep over
+both — `examples/galaga/player.c` has all three loops.
+
+Explosions are the fourth actor kind, and they carry the one place this game
+*absorbs* an error instead of propagating it. `HANDLE` names the status it
+forgives; everything else still travels:
+
+```c wrap=galagagame requires=akgl
+static float BOOM_TTL[AKGL_MAX_HEAP_ACTOR];
+static uint32_t BOOM_SERIAL = 0;
+
+static akerr_ErrorContext *boom_update(akgl_Actor *obj)
+{
+    ptrdiff_t slot = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj");
+    slot = obj - akgl_heap_actors;
+    BOOM_TTL[slot] -= galaga_game.dt;
+    if ( BOOM_TTL[slot] <= 0.0f ) {
+	PASS(errctx, akgl_heap_release_actor(obj));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *galaga_boom_spawn(float x, float y)
+{
+    akgl_Actor *boom = NULL;
+    char name[32];
+    int count = 0;
+    PREPARE_ERROR(errctx);
+
+    ATTEMPT {
+	CATCH(errctx, akgl_heap_next_actor(&boom));
+	BOOM_SERIAL += 1;
+	CATCH(errctx, aksl_snprintf(&count, name, sizeof(name), "boom%u", BOOM_SERIAL));
+	CATCH(errctx, akgl_actor_initialize(boom, name));
+	CATCH(errctx, akgl_actor_set_character(boom, "galaga_boom"));
+	boom->updatefunc = &boom_update;
+	boom->movement_controls_face = false;
+	boom->state = AKGL_ACTOR_STATE_ALIVE;
+	boom->visible = true;
+	boom->x = x;
+	boom->y = y;
+	BOOM_TTL[boom - akgl_heap_actors] = 0.25f;
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } HANDLE(errctx, AKGL_ERR_HEAP) {
+	/* Explosions are decoration. When the heap is momentarily full the
+	 * right outcome is no explosion, not a dead frame. */
+    } FINISH(errctx, true);
+    SUCCEED_RETURN(errctx);
+}
+```
+
+## Step 5: Boot the interpreter
+
+**Goal: the engine calls a BASIC function and prints its answer.**
+
+Everything so far was libakgl. Now link the interpreter into the same
+executable. The whole CMake recipe, inside an akbasic checkout with
+`AKBASIC_WITH_AKGL=ON`:
+
+```cmake
+add_executable(mygalaga
+  main.c
+  script.c
+  enemies.c
+  player.c)
+target_compile_options(mygalaga PRIVATE -Wall -Wextra)
+target_compile_definitions(mygalaga PRIVATE
+  GALAGA_ASSET_DIR="${CMAKE_CURRENT_SOURCE_DIR}/assets"
+  GALAGA_SCRIPT_PATH="${CMAKE_CURRENT_SOURCE_DIR}/galaga.bas"
+  GALAGA_FONT_PATH="${CMAKE_CURRENT_SOURCE_DIR}/assets/fonts/C64_Pro_Mono-STYLE.ttf")
+target_link_libraries(mygalaga PRIVATE akbasic akgl
+  SDL3::SDL3 SDL3_ttf::SDL3_ttf SDL3_image::SDL3_image)
+```
+
+The three baked-in paths are what let the program launch from any working
+directory; `--assets` and `--script` flags can override them at runtime.
+
+Link `akbasic` — the interpreter only. Not `akbasic_akgl` (the device backends
+that let a script draw), and not `akbasic_frontend` (the standalone program's
+host). This game lends the script **no devices at all**: the scripts compute,
+the engine draws, and a script that tries `SPRITE` is refused by name. That
+refusal is enforced by the interpreter, not by convention —
+[Chapter 10](10-embedding.md) explains the device-lending model this game
+declines to use.
+
+The boot is the embedding host from Chapter 10, adapted to a script that only
+defines. Keep every line that touches the interpreter in one file — the
+example's `script.c` — so the boundary stays a place rather than a habit. That
+file's interpreter-facing includes and statics, exactly:
+
+```c wrap=galagatypes requires=akgl
+#include <akbasic/environment.h>
+#include <akbasic/error.h>
+#include <akbasic/host.h>
+#include <akbasic/runtime.h>
+#include <akbasic/sink.h>
+
+/* Static because an akbasic_Runtime is far too big for a stack frame --
+ * 2.40 MiB on this branch. */
+static akbasic_Runtime SCRIPT;
+static akbasic_TextSink SINK;
+static akbasic_StdioSink SINKSTATE;
+static char SOURCE[16384];
+```
+
+The boot itself:
+
+```c wrap=galagacalls requires=akgl
+CATCH(errctx, akbasic_error_register());
+CATCH(errctx, akbasic_sink_init_stdio(&SINK, &SINKSTATE, stdout, NULL));
+CATCH(errctx, akbasic_runtime_init(&SCRIPT, &SINK));
+
+CATCH(errctx, akbasic_runtime_load(&SCRIPT, SOURCE));
+CATCH(errctx, akbasic_runtime_start(&SCRIPT, AKBASIC_MODE_RUN));
+CATCH(errctx, akbasic_runtime_run(&SCRIPT, 4 * AKBASIC_MAX_SOURCE_LINES));
+CATCH(errctx, akbasic_runtime_set_mode(&SCRIPT, AKBASIC_MODE_RUN));
+```
+
+Two of those lines are the ones a first embedding gets wrong.
+
+**A "no top level code" script still has to run once.** The script is nothing
+but `DEF` blocks and a final `END`, and executing the `DEF` statements is what
+files the functions. The run is bounded — a script that is all definitions has
+no business taking more than a few steps per line, and an accidental loop at
+boot should be a diagnosis, not a hang.
+
+**The `set_mode` after the run is load-bearing.** The program has now ended and
+the runtime sits in QUIT mode, where a multi-line `DEF` called from the host
+returns a silent zero. Forcing the mode back to RUN makes the bodies run, and it
+stays put because nothing here ever steps the runtime again. Issue #8 tracks
+making this workaround unnecessary.
+
+`PRINT` inside the script goes through the stdio sink and lands on stdout —
+that is the script's debug channel for the rest of both chapters.
+
+Prove the wiring with one function. Put this in the script:
+
+```basic
+DEF ADDEM(A#, B#) = A# + B#
+END
+```
+
+And call it from C, with values you already have:
+
+```c wrap=galagacalls requires=akgl
+memset(&args[0], 0, sizeof(args[0]));
+memset(&args[1], 0, sizeof(args[1]));
+args[0].valuetype = AKBASIC_TYPE_INTEGER;
+args[0].intval = 17;
+args[1].valuetype = AKBASIC_TYPE_INTEGER;
+args[1].intval = 25;
+argp[0] = &args[0];
+argp[1] = &args[1];
+CATCH(errctx, akbasic_runtime_call_function(&SCRIPT, "ADDEM", argp, 2, &result));
+printf("ADDEM(17, 25) = %lld\n", (long long)result->intval);
+```
+
+```text
+ADDEM(17, 25) = 42
+```
+
+`akbasic_runtime_call_function()` is the host's entry point: a name and
+already-evaluated values in, the function's result out. The engine refuses to
+start when the script will not boot — a game whose enemies cannot think is not
+a game missing a feature, it is a game that does not run.
+
+## Step 6: The update hook
+
+**Goal: one actor whose every frame is a BASIC call.**
+
+`akgl_game_update()` calls each live actor's `updatefunc` exactly once per
+frame. Replacing that pointer is the whole integration: the actor's frame *is*
+a script call.
+
+```c wrap=galagagame requires=akgl
+static akerr_ErrorContext *enemy_update(akgl_Actor *obj)
+{
+    galaga_Enemy *enemy = NULL;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj");
+    enemy = (galaga_Enemy *)obj->actorData;
+    FAIL_ZERO_RETURN(errctx, enemy, AKERR_NULLPOINTER, "an enemy actor with no galaga_Enemy attached");
+
+    enemy->rnd = galaga_random();
+    PASS(errctx, galaga_script_update_enemy(enemy, obj, galaga_game.dt));
+    if ( enemy->fire != 0 ) {
+	PASS(errctx, enemy_fire(enemy, obj));
+    }
+    SUCCEED_RETURN(errctx);
+}
+```
+
+The hook's body is a protocol, and `galaga_script_update_enemy()` is its
+middle: **rebind, call, recover, reset.**
+
+```c wrap=galagacalls requires=akgl
+CATCH(errctx, akbasic_host_rebind(&SCRIPT, "SELF@", enemy));
+CATCH(errctx, akbasic_host_rebind(&SCRIPT, "ACTOR@", actor));
+
+memset(&dtval, 0, sizeof(dtval));
+dtval.valuetype = AKBASIC_TYPE_FLOAT;
+dtval.floatval = (double)dt;
+argp[0] = &dtval;
+CATCH(errctx, akbasic_runtime_call_function(&SCRIPT, "UPDATEBEE", argp, 1, &result));
+
+CATCH(errctx, akbasic_environment_zero(SCRIPT.environment));
+```
+
+`SELF@` and `ACTOR@` are **host bindings** — the enemy's record and the
+engine's live actor, shared with the script as structures it can read and
+write directly. [Chapter 21](21-tutorial-galaga-enemies.md) builds them; for
+this chapter, know that `akbasic_host_rebind()` points an existing binding at
+a different instance, which is how forty enemies share one script: one name,
+rebound per enemy, rather than forty names.
+
+**The `akbasic_environment_zero()` after every call is load-bearing.** Each
+call parks its result in the caller environment's per-line value scratch, and a
+host calling in a loop never crosses the line boundary that would reset it.
+Without this line the scratch drains in under two frames of a 40-enemy wave and
+every later call fails with `Maximum values per line reached`. Chapter 10's
+["Calling a function every frame"](10-embedding.md#calling-a-function-every-frame)
+section is the rule's home.
+
+## Step 7: First light
+
+**Goal: a C actor moving under BASIC control, and proof it is one memory.**
+
+Before any real AI, the smallest demonstration. One enemy, one function, a sine
+drift written entirely in BASIC through the actor binding:
+
+```basic
+DEF UPDATEBEE(DT%)
+  SELF@.T% = SELF@.T% + DT%
+  ACTOR@.X% = 590.0 + SIN(SELF@.T%) * 200
+  ACTOR@.Y% = 300.0
+  PRINT "BASIC SEES X = " + ACTOR@.X%
+  RETURN 0
+END
+```
+
+Spawn one enemy with the hook from Step 6, and have the engine print the same
+actor's position each frame from C:
+
+```c wrap=galagahost requires=akgl
+SDL_Log("C SEES X = %f", galaga_enemy_actors[0]->x);
+```
+
+```text
+BASIC SEES X = 593.191094
+INFO: C SEES X = 593.191094
+BASIC SEES X = 596.378593
+INFO: C SEES X = 596.378593
+```
+
+Same numbers, one memory. The script wrote `ACTOR@.X%`; the renderer read
+`akgl_Actor.x`; nothing copied anything anywhere. The ship swings in a slow
+arc, and the whole architecture is visible in that one motion: C owns the
+frame, BASIC owns the decision, and the actor is the same bytes to both.
+
+## Step 8: Screens
+
+**Goal: title, playing, game over, victory — a state machine around the loop.**
+
+The screens are libakgl's UI layer, in the three-state pattern of its uidemo
+example (libakgl docs/22-ui.md). A `galaga_Screen` enum, one `declare_*()`
+function per screen, and the UI bracket between `akgl_game_update()` and
+`frame_end` — exactly where the frame contract puts it:
+
+```c wrap=galagahost requires=akgl
+CATCH(errctx, akgl_ui_frame_begin());
+switch ( galaga_game.screen ) {
+case GALAGA_SCREEN_TITLE:
+    CATCH(errctx, declare_title());
+    break;
+case GALAGA_SCREEN_PLAY:
+    CATCH(errctx, declare_play());
+    break;
+case GALAGA_SCREEN_GAMEOVER:
+case GALAGA_SCREEN_VICTORY:
+    CATCH(errctx, declare_end());
+    break;
+}
+CATCH(errctx, akgl_ui_frame_end(akgl_renderer));
+```
+
+The playing screen is two `akgl_ui_label()` calls — a widget call per label,
+not a struct — formatted into `static` buffers, because the UI borrows label
+text until `frame_end` and a local buffer would be dangling by the time it
+draws:
+
+```c wrap=galagagame requires=akgl
+static char HUD_SCORE[64];
+static char HUD_LIVES[64];
+
+static akerr_ErrorContext *declare_play(void)
+{
+    int count = 0;
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, aksl_snprintf(&count, HUD_SCORE, sizeof(HUD_SCORE),
+			       "SCORE %06d", galaga_game.score));
+    PASS(errctx, aksl_snprintf(&count, HUD_LIVES, sizeof(HUD_LIVES),
+			       "LIVES %d   WAVE %d", galaga_game.lives, galaga_shared.wave));
+    PASS(errctx, akgl_ui_label("score", HUD_SCORE, AKGL_UI_ANCHOR_TOP_LEFT, NULL));
+    PASS(errctx, akgl_ui_label("lives", HUD_LIVES, AKGL_UI_ANCHOR_TOP_RIGHT, NULL));
+    SUCCEED_RETURN(errctx);
+}
+```
+
+The title and end screens are an `akgl_ui_menu()` at the center, fed an
+`akgl_UiMenu` that lives in a `static` for the same borrowing reason. The
+struct is an id, the item strings, a count, the selected index, the
+`activated` output flag, and a style (`NULL` for the default):
+
+```c wrap=galagatypes requires=akgl
+static akgl_UiMenu TITLE_MENU = {
+    "titlemenu", { "START", "QUIT" }, 2, 0, false, NULL
+};
+
+static akerr_ErrorContext *declare_title(void)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, akgl_ui_menu(&TITLE_MENU));
+    SUCCEED_RETURN(errctx);
+}
+```
+
+Route events to the menu with
+`akgl_ui_menu_handle_event(&TITLE_MENU, event, &consumed)` — the menu for
+whichever screen is up, a `bool` out-parameter reporting whether the event was
+taken. Up and down move `selected`, return sets `activated`.
+
+The big **GALAGA** headline is direct text rather than a label:
+
+```c wrap=galagagame requires=akgl
+static akerr_ErrorContext *draw_banner(char *text)
+{
+    SDL_Color ink = { 235, 235, 235, 255 };
+    TTF_Font *font = NULL;
+    int w = 0;
+    int h = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, text, AKERR_NULLPOINTER, "text");
+    font = SDL_GetPointerProperty(AKGL_REGISTRY_FONT, "banner", NULL);
+    FAIL_ZERO_RETURN(errctx, font, AKERR_KEY, "the banner font is not loaded");
+    PASS(errctx, akgl_text_measure(font, text, &w, &h));
+    PASS(errctx, akgl_text_rendertextat(font, text, ink, 0, (1280 - w) / 2, 280));
+    SUCCEED_RETURN(errctx);
+}
+```
+
+The menu owns `AKGL_UI_ANCHOR_CENTER`, a label anchored there disappears
+behind it, and there is no top-center anchor — so the headline measures itself
+and draws at a coordinate, before the UI bracket so the menu still paints over
+it if the two ever meet.
+
+![The title screen: the banner, the menu, the starfield](images/galaga-title.png)
+
+Screen transitions are three rules read after the world updates: lives spent is
+GAME OVER, an empty wave is VICTORY, and a menu activation either restarts or
+quits. The menu never clears its own `activated` flag — the state machine that
+acts on it does.
+
+## Step 9: Run it headless
+
+**Goal: the same game, playable by a script, in CI every night.**
+
+The example takes five flags, in the pattern of libakgl's sidescroller:
+
+```sh norun
+$ SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy SDL_RENDER_DRIVER=software \
+    ./build-akgl/akbasic_example_galaga --frames 600 --autoplay
+```
+
+`--frames N` bounds the run; `--autoplay` is a scripted pilot that starts the
+game, sweeps the floor and holds fire until the wave assembles; `--screenshot
+PATH --screenshot-frame N` write a PNG from the render target — the figures in
+this chapter are that flag's output, not pictures somebody took once. Synthetic
+input goes through `akgl_controller_handle_event()` with constructed
+`SDL_Event`s, never by calling the handlers directly — the point of autoplay is
+to exercise the same path a keyboard does.
+
+The last line of every run is the evidence:
+
+```text
+galaga: 600 frames, screen 1, score 1910, alive 9, kills bee 19 bfly 12 boss 0, shots bee 0 bfly 3 boss 0, script errors 0
+```
+
+Exiting 0 is not proof the wave flew. The readout is: kills and shots counted
+per kind say the enemies entered, thought and fired, and **`script errors 0`**
+says every one of the ~24,000 BASIC calls in those ten seconds came back clean.
+A wave of dumb enemies still exits 0, and that count is how you notice. The
+CTest entry `example_galaga` runs exactly this under the dummy SDL drivers,
+which is what keeps both chapters honest.
+
+---
+
+That is the engine: a window, a starfield, a ship, bullets, screens, and an
+interpreter that answers when called. Everything on screen so far is C. What
+turns it into a GALAGA is [Chapter 21](21-tutorial-galaga-enemies.md) — the
+three shared structures, the script that thinks through them, and a full wave
+entering, breathing, diving and firing without another line of engine code.

docs/21-tutorial-galaga-enemies.md

@@ -0,0 +1,585 @@
+# 21. Tutorial: GALAGA — the structures and the AI
+
+[Chapter 20](20-tutorial-galaga.md) built a C engine that boots the interpreter
+and hands one actor to BASIC. This chapter builds everything that crosses the
+boundary — the three shared structures — and then the script that thinks
+through them: a full wave that enters, forms up, breathes, dives, fires and
+dies, without another line of engine code.
+
+![The wave assembling: bosses, butterflies and bees under BASIC control](images/galaga-wave.png)
+
+The finished script is
+[`examples/galaga/galaga.bas`](../examples/galaga/galaga.bas) — six `DEF`
+functions and an `END`, nothing else. Editing it and re-running the game is the
+whole development loop; the engine never rebuilds.
+
+## What you will do
+
+- **[Step 1](#step-1-declare-the-enemy-once-in-c)** — declare the enemy record
+  once, in C, and register it as a BASIC type
+- **[Step 2](#step-2-bind-the-engines-own-actor)** — bind the engine's own
+  actor as the second type, which is the point of the whole exercise
+- **[Step 3](#step-3-share-the-frame-and-the-dice)** — share the frame state,
+  and give the script randomness it cannot make itself
+- **[Step 4](#step-4-why-bindings-and-not-arguments)** — see why the structures
+  are bindings rather than function arguments
+- **[Step 5](#step-5-the-shape-of-the-script)** — learn the three language
+  rules that shape every enemy function
+- **[Step 6](#step-6-the-shared-maneuvers)** — write the shared maneuvers:
+  glide home, dive, decide to fire
+- **[Step 7](#step-7-the-three-kinds)** — write the bee, the butterfly and the
+  boss
+- **[Step 8](#step-8-the-formation-c-or-basic)** — decide who owns the
+  formation, and lay it out
+- **[Step 9](#step-9-when-a-script-dies)** — decide what a script error does to
+  the game, and make it do that
+- **[Step 10](#step-10-prove-it)** — prove the boundary with a test that links
+  the real files
+- **[Step 11](#step-11-the-cost-measured)** — measure what thinking in BASIC
+  costs, against the same logic in C
+
+---
+
+## Step 1: Declare the enemy once, in C
+
+**Goal: one struct that both languages read and write, with one source of truth.**
+
+An enemy is what the state machine needs to remember between frames, plus one
+inbox and one outbox:
+
+```c wrap=galagatypes requires=akgl
+#define GALAGA_ENEMY_BEE	0
+#define GALAGA_ENEMY_BUTTERFLY	1
+#define GALAGA_ENEMY_BOSS	2
+
+/*
+ * galaga_Enemy.state bits. The script owns these transitions; the engine only
+ * writes the word at spawn.
+ *
+ * 8             0
+ * 0 0 0 0 0 1 1 1
+ *           | | `-- ENTERING: flying its entry path toward the formation slot
+ *           | `---- FORMATION: holding (and breathing around) homex/homey
+ *           `------ DIVING: attacking, off the grid until it leaves the screen
+ */
+#define GALAGA_ES_ENTERING	(1 << 0)
+#define GALAGA_ES_FORMATION	(1 << 1)
+#define GALAGA_ES_DIVING	(1 << 2)
+
+typedef struct galaga_Enemy
+{
+    int32_t  kind;	/* GALAGA_ENEMY_BEE / BUTTERFLY / BOSS		*/
+    int32_t  state;	/* GALAGA_ES_* bit flags			*/
+    float    homex;	/* formation slot, in map pixels		*/
+    float    homey;
+    float    t;		/* parametric clock for the current maneuver	*/
+    int32_t  hp;
+    int32_t  fire;	/* outbox: script sets 1, engine consumes	*/
+    float    rnd;	/* inbox: engine writes fresh 0..1 each call	*/
+} galaga_Enemy;
+```
+
+The C struct *is* the BASIC type. `akbasic_host_register_type()` takes a table
+of field descriptors — the BASIC name with its suffix, the C representation,
+and where the member sits — and after that the language's own machinery works
+across the boundary with no second set of rules
+([Chapter 16](16-structures.md)):
+
+```c wrap=galagatypes requires=akgl
+typedef struct galaga_Enemy
+{
+    int32_t  kind;
+    int32_t  state;
+    float    homex;
+    float    homey;
+    float    t;
+    int32_t  hp;
+    int32_t  fire;
+    float    rnd;
+} galaga_Enemy;
+
+static const akbasic_HostField ENEMY_FIELDS[] = {
+    /*                  struct        member  BASIC name  C representation          */
+    AKBASIC_HOST_FIELD( galaga_Enemy, kind,   "KIND#",    AKBASIC_HOSTFIELD_INT32 ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, state,  "STATE#",   AKBASIC_HOSTFIELD_INT32 ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, homex,  "HOMEX%",   AKBASIC_HOSTFIELD_FLOAT ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, homey,  "HOMEY%",   AKBASIC_HOSTFIELD_FLOAT ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, t,      "T%",       AKBASIC_HOSTFIELD_FLOAT ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, hp,     "HP#",      AKBASIC_HOSTFIELD_INT32 ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, fire,   "FIRE#",    AKBASIC_HOSTFIELD_INT32 ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, rnd,    "RND%",     AKBASIC_HOSTFIELD_FLOAT )
+};
+static const akbasic_HostType ENEMY_TYPE = {
+    "ENEMY", sizeof(galaga_Enemy), ENEMY_FIELDS, 8
+};
+```
+
+Three decisions are load-bearing here:
+
+- **`AKBASIC_HOST_FIELD` takes the offset and the width from the member
+  itself**, via `offsetof` — so the two sides cannot drift. Writing them out by
+  hand is two chances to name the wrong member and no way to notice.
+- **The script never declares a `TYPE`.** A host type and a script `TYPE` share
+  one namespace, and a script that tries to redeclare `ENEMY` is refused. The
+  "structure definitions" half of the boundary lives here, once.
+- **The suffixes are the dialect's**: `#` is integer, `%` is float
+  ([Chapter 3](03-the-language.md)). `HOMEX%` because a formation slot is a
+  pixel coordinate the glide arithmetic must not truncate.
+
+The limits that shape the struct: a type may carry 16 fields and the runtime 16
+types ([Chapter 16](16-structures.md)). `ENEMY` spends 8 fields; the game
+spends 3 types.
+
+## Step 2: Bind the engine's own actor
+
+**Goal: the script writes the same bytes the renderer reads.**
+
+The enemy record is the game's own invention. The second type is not — it is
+libakgl's `akgl_Actor`, registered field-for-field over the engine's real
+struct:
+
+```c wrap=galagatypes requires=akgl
+static const akbasic_HostField ACTOR_FIELDS[] = {
+    AKBASIC_HOST_FIELD( akgl_Actor, x,       "X%",       AKBASIC_HOSTFIELD_FLOAT ),
+    AKBASIC_HOST_FIELD( akgl_Actor, y,       "Y%",       AKBASIC_HOSTFIELD_FLOAT ),
+    AKBASIC_HOST_FIELD( akgl_Actor, state,   "STATE#",   AKBASIC_HOSTFIELD_INT32 ),
+    AKBASIC_HOST_FIELD( akgl_Actor, visible, "VISIBLE#", AKBASIC_HOSTFIELD_BOOL  )
+};
+static const akbasic_HostType ACTOR_TYPE = {
+    "ACTOR", sizeof(akgl_Actor), ACTOR_FIELDS, 4
+};
+```
+
+This is the demonstrative point of the whole exercise. When the script writes
+`ACTOR@.X%`, it writes `akgl_Actor.x` — the same memory the renderer reads on
+the same frame. There is no copy going in, no copy coming out, and no code
+between the script's decision and the engine's pixel. Null physics
+(Chapter 20, Step 1) is what makes that safe: nothing else is trying to move
+the actor.
+
+Registration and the first binding happen at boot, before the script loads —
+between `akbasic_runtime_init()` and `akbasic_runtime_load()` in Chapter 20's
+boot sequence. A binding is **borrowed, never copied**, so the placeholders it
+points at must be static storage:
+
+```c wrap=galagacalls requires=akgl
+CATCH(errctx, akbasic_host_register_type(&SCRIPT, &ENEMY_TYPE));
+CATCH(errctx, akbasic_host_register_type(&SCRIPT, &ACTOR_TYPE));
+CATCH(errctx, akbasic_host_register_type(&SCRIPT, &GAME_TYPE));
+
+CATCH(errctx, akbasic_host_bind(&SCRIPT, "SELF@", "ENEMY", &SCRATCH_ENEMY));
+CATCH(errctx, akbasic_host_bind(&SCRIPT, "ACTOR@", "ACTOR", &SCRATCH_ACTOR));
+CATCH(errctx, akbasic_host_bind(&SCRIPT, "GAME@", "GAME", &galaga_shared));
+```
+
+`akbasic_host_bind()` takes the script name, the registered type's name, and
+the instance; after that, `SELF@` and `ACTOR@` are only ever *re*bound.
+
+The per-frame call binds both names to *this* enemy before dispatching — one
+binding per name, pointed at forty enemies in turn, which is what
+`akbasic_host_rebind()` is for:
+
+```c wrap=galagacalls requires=akgl
+CATCH(errctx, akbasic_host_rebind(&SCRIPT, "SELF@", enemy));
+CATCH(errctx, akbasic_host_rebind(&SCRIPT, "ACTOR@", actor));
+```
+
+## Step 3: Share the frame, and the dice
+
+**Goal: everything a diving enemy needs to know about the world, in one record.**
+
+```c wrap=galagatypes requires=akgl
+typedef struct galaga_Shared
+{
+    float    playerx;	/* the player actor's position, this frame	*/
+    float    playery;
+    int32_t  wave;
+    float    rnd;	/* fresh 0..1 each frame; the issue #16 route	*/
+} galaga_Shared;
+```
+
+`GAME@` is bound once at boot to this one global instance and never rebound;
+the engine refreshes it at the top of every frame. The boss reads
+`GAME@.PLAYERX%` to lead its dive; the fire decision reads it to know whether
+anything is worth shooting at.
+
+The `rnd` fields — one here per frame, one on each enemy per call — exist
+because the engine's PRNG is the script's **only** source of randomness: write
+`SELF@.RND% < DT% * 1.5` and an enemy's trigger finger is a dice roll. There
+is no `RND` verb in this dialect; issue #16 tracks adding one, and Chapter
+17's breakout hand-rolls a linear congruential generator in BASIC as the other
+route. Here the engine fills the field, which also keeps a headless run the
+same game on every machine — the PRNG is the example's own, not libc's.
+
+## Step 4: Why bindings, and not arguments
+
+**Goal: know why `SELF@` is a bound global rather than a parameter.**
+
+The language can pass structures to functions — by value with `E@ AS ENEMY`,
+by reference with `E@ AS PTR TO ENEMY` ([Chapter 16](16-structures.md)) — and
+a host can construct those argument values, so the obvious alternative
+interface is honest functions:
+
+```basic norun
+DEF UPDATEBEE(E@ AS PTR TO ENEMY, A@ AS PTR TO ACTOR, G@ AS PTR TO GAME, DT%)
+```
+
+It was measured before this chapter chose. Pointer arguments work — writes
+through `E@->X%` land in the host struct, the type check refuses a wrong type,
+by-value copies exactly as documented. What rules them out is the pool math:
+
+| | bound globals | pointer arguments |
+|---|---|---|
+| value-pool slots per call | 0 | 1 per structure parameter, never returned |
+| calls before exhaustion | unbounded | 1,015 measured (2,048-slot pool, 2 pointer args) |
+| at 40 enemies per frame | unbounded | 25 frames |
+| per-call cost | 148 us | 251 us |
+
+A `@`-suffixed name always takes value-pool storage, and that pool never
+reclaims — a documented property of structures, because a pointer may outlive
+the scope that `DIM`med it. A *parameter* is a local that dies with the call,
+but it pays the storage price of a `DIM` that must survive one; the pool
+drains, and the wave stops thinking mid-flight. Issue #36 tracks it, with the
+reduction for whoever fixes it. Until then: **bind and rebind for per-frame
+host calls; pass structures only to functions called a bounded number of
+times.**
+
+## Step 5: The shape of the script
+
+**Goal: the three rules every enemy function is written under.**
+
+`galaga.bas` is definitions and an `END` — no top-level code, no line numbers,
+no `LABEL`s. Three rules of the dialect shape every body in it.
+
+**Rule 1: the left operand decides integer or float arithmetic**
+([Chapter 3](03-the-language.md)). This will bite every enemy script exactly
+once, so meet it now. The natural spelling of "move by speed times dt" moves
+nothing:
+
+```basic norun
+ACTOR@.Y% = ACTOR@.Y% + 260 * DT%
+```
+
+`260` is an integer, it is on the left of `*`, so `DT%` — a float around
+0.016 — is converted to integer **zero** before the multiply. Nothing fails;
+the enemy simply does not move. The working spelling puts the float first:
+
+```basic norun
+ACTOR@.Y% = ACTOR@.Y% + SPD% * DT%
+SPD% = SELF@.T% * 150 + 260
+```
+
+Every expression in the finished script is written float-first. When an enemy
+of yours will not move, this is the first thing to check.
+
+**Rule 2: only the last `RETURN` may start a line.** A multi-line `DEF` body
+runs until `RETURN` — and the *definition* is scanned the same way, ending at
+the first line that begins with one. An early return therefore always rides an
+`IF ... THEN RETURN 0` on one line, and exactly one line-leading `RETURN` ends
+each function. The stagger guard at the top of every update function is the
+idiom:
+
+```basic norun
+DEF UPDATEBEE(DT%)
+  SELF@.T% = SELF@.T% + DT%
+  IF SELF@.T% < 0 THEN RETURN 0
+```
+
+**Rule 3: the budgets are small and named.** Eight function slots exist
+(`AKBASIC_MAX_FUNCTIONS`), each a measured 36 KiB of the runtime's 2.40 MiB.
+This game defines six: three update functions, two shared maneuvers, one fire
+decision. Nesting draws from the twelve-slot environment pool exactly as
+`GOSUB` does; the deepest chain here is three (update → maneuver → nothing).
+If a design needs a ninth function, raising the limit is one `#define` and
++36 KiB per slot — weighed, not assumed.
+
+## Step 6: The shared maneuvers
+
+**Goal: three helpers that make the three kinds one page each.**
+
+Ease toward the formation slot, with a little entry swirl. Answers 1 once the
+slot is reached — the caller flips the state on that answer:
+
+```basic
+DEF GLIDEHOME(DT%)
+  DX% = SELF@.HOMEX% - ACTOR@.X%
+  DY% = SELF@.HOMEY% - ACTOR@.Y%
+  K% = DT% * 4.5
+  IF K% > 1 THEN K% = 1
+  ACTOR@.X% = ACTOR@.X% + DX% * K% + SIN(SELF@.T% * 6) * 90 * DT%
+  ACTOR@.Y% = ACTOR@.Y% + DY% * K%
+  IF ABS(DX%) < 3 AND ABS(DY%) < 3 THEN RETURN 1
+  RETURN 0
+END
+```
+
+One frame of a dive: accelerate downward, weave, lean toward the player's
+column, and glide back in from the top after falling out the bottom. The
+weave and the lean are parameters, which is what makes three kinds out of one
+maneuver:
+
+```basic
+DEF DIVESTEP(DT%, WEAVE%, LEAD%)
+  SPD% = SELF@.T% * 150 + 260
+  ACTOR@.Y% = ACTOR@.Y% + SPD% * DT%
+  ACTOR@.X% = ACTOR@.X% + SIN(SELF@.T% * 4) * WEAVE% * DT%
+  DX% = GAME@.PLAYERX% - ACTOR@.X%
+  IF DX% > 220 THEN DX% = 220
+  IF DX% < -220 THEN DX% = -220
+  ACTOR@.X% = ACTOR@.X% + DX% * LEAD% * DT%
+  IF ACTOR@.Y% > 1040 THEN BEGIN
+    ACTOR@.Y% = 0.0 - 90
+    SELF@.STATE# = 1
+    SELF@.T% = 0
+  BEND
+  RETURN 0
+END
+```
+
+Note the off-screen exit: state back to `1` (ENTERING), clock to zero, and the
+glide brings it home — a dive that misses rejoins the formation, which is the
+classic loop. `0.0 - 90` rather than `0 - 90` is Rule 1 again: the float goes
+first even to make a negative.
+
+The fire decision raises the flag when diving roughly above the player. The
+engine consumes `FIRE#` and does the spawning — the script only wishes,
+because spawning takes an actor from a bounded pool and pool exhaustion must
+be a C-side refusal with the house error context, not a script mystery:
+
+```basic
+DEF DECIDEFIRE(DT%)
+  DX% = GAME@.PLAYERX% - ACTOR@.X%
+  IF ABS(DX%) > 140 THEN RETURN 0
+  IF ACTOR@.Y% > GAME@.PLAYERY% THEN RETURN 0
+  IF SELF@.RND% < DT% * 1.5 THEN SELF@.FIRE# = 1
+  RETURN 0
+END
+```
+
+## Step 7: The three kinds
+
+**Goal: bee, butterfly, boss — one state machine, three characters.**
+
+Every kind is the same three-state machine, dispatched by the bits of
+`SELF@.STATE#`. The bee is the reference implementation:
+
+```basic
+DEF GLIDEHOME(DT%)
+  ACTOR@.X% = SELF@.HOMEX%
+  ACTOR@.Y% = SELF@.HOMEY%
+  RETURN 1
+
+DEF DIVESTEP(DT%, WEAVE%, LEAD%)
+  RETURN 0
+
+DEF DECIDEFIRE(DT%)
+  RETURN 0
+
+DEF UPDATEBEE(DT%)
+  SELF@.T% = SELF@.T% + DT%
+  IF SELF@.T% < 0 THEN RETURN 0
+  S# = SELF@.STATE#
+  IF (S# AND 1) > 0 THEN BEGIN
+    R# = GLIDEHOME(DT%)
+    IF R# = 1 THEN SELF@.STATE# = 2 : SELF@.T% = 0
+  BEND
+  IF (S# AND 2) > 0 THEN BEGIN
+    ACTOR@.X% = SELF@.HOMEX% + SIN(SELF@.T% * 1.7) * 16
+    ACTOR@.Y% = SELF@.HOMEY%
+    IF SELF@.RND% < DT% * 0.04 THEN SELF@.STATE# = 4 : SELF@.T% = 0
+  BEND
+  IF (S# AND 4) > 0 THEN BEGIN
+    R# = DIVESTEP(DT%, 130, 0.2)
+    R# = DECIDEFIRE(DT%)
+  BEND
+  RETURN 0
+END
+```
+
+(The three helpers above are stubs so this listing runs alone; the real ones
+are Step 6's. The listing in `galaga.bas` is this function verbatim.)
+
+The shape to notice: `S#` is read **once**, so a state flipped this frame does
+not also run its new state's block this frame — transitions are frame-atomic.
+Each block is one `IF ... BEGIN`/`BEND`, never nested. The formation block
+computes position *relative to home* every frame — `HOMEX% + SIN(...)` — so
+the grid's idle breathing belongs to the script even though C placed the grid.
+
+The butterfly is the bee with a wide lateral weave — `DIVESTEP(DT%, 260, 0.1)`
+— and a slightly itchier trigger. The boss differs three ways: two hit points
+(C fills `HP#` at spawn), a dive that leads the player —
+`DIVESTEP(DT%, 60, 0.9)` — and one line that crosses the boundary in the other
+direction:
+
+```basic norun
+IF SELF@.HP# = 1 THEN ACTOR@.STATE# = ACTOR@.STATE# OR 8192
+```
+
+8192 is `AKGL_ACTOR_STATE_UNDEFINED_13`, one of the actor state bits libakgl
+reserves for the game. The boss's character file maps the state word
+`ALIVE` to the green sprite and `ALIVE`+bit-13 to the drained one — so when
+the script raises the bit, the engine's own character machinery swaps the
+sprite. BASIC decides *that* the boss looks hurt; C never hears about it.
+
+## Step 8: The formation: C or BASIC?
+
+**Goal: decide who owns the grid, from the trade-offs rather than taste.**
+
+Both can lay out the formation. The choice is argued, not asserted:
+
+| | C lays out the grid | BASIC lays out the grid |
+|---|---|---|
+| actor pool safety | refusal at spawn, house error path | script can ask for more than 64 exist |
+| tuning without rebuild | no | yes |
+| call budget | zero calls | one call per spawn |
+| who knows the screen size | the engine owns it anyway | needs it exported through `GAME@` |
+
+**Decision: C owns the grid, the wave table and the spawn timing; BASIC owns
+everything an enemy does after it exists.** The slot arrives in
+`SELF@.HOMEX%`/`HOMEY%`, so the breathing stays the script's (Step 7), and the
+pool stays behind a C-side refusal. The wave is the aligned table house style
+already prescribes for tabular data — one row per formation row:
+
+```c wrap=galagagame requires=akgl
+static const struct
+{
+    int32_t kind;	/* GALAGA_ENEMY_*	*/
+    int     row;	/* formation row	*/
+    int     first;	/* first column filled	*/
+    int     count;	/* columns filled	*/
+    int32_t hp;
+}
+WAVE_ROWS[] = {
+    /*  kind                    row  first  count  hp  */
+    { GALAGA_ENEMY_BOSS,	 0,     3,     4,   2 },
+    { GALAGA_ENEMY_BUTTERFLY,	 1,     1,     8,   1 },
+    { GALAGA_ENEMY_BUTTERFLY,	 2,     1,     8,   1 },
+    { GALAGA_ENEMY_BEE,		 3,     0,    10,   1 },
+    { GALAGA_ENEMY_BEE,		 4,     0,    10,   1 }
+};
+```
+
+Forty enemies: 4 bosses, 16 butterflies, 20 bees. The actor heap holds 64:
+
+```text
+player            1
+player shots      2      /* the classic two-on-screen rule           */
+enemies          40      /* 20 bees, 16 butterflies, 4 bosses        */
+enemy shots       8
+explosions        8      /* short-lived actors, released on a timer  */
+                ---
+                 59 of 64
+```
+
+The spawn walks the table, fills each `galaga_Enemy`, and staggers the entry
+clocks — `t = -0.08 * index`, so each enemy holds still until its own clock
+crosses zero and the wave pours in as a stream rather than a wall. The full
+loop is `examples/galaga/enemies.c`.
+
+## Step 9: When a script dies
+
+**Goal: a script error costs one enemy's wits, never the frame.**
+
+A BASIC-level error in an enemy's function — a misspelled field, arithmetic on
+the wrong type — reports through the sink and stops the script. The engine's
+policy, implemented around the call in `script.c`:
+
+- **The enemy goes dumb**: state cleared to a formation hold it will never
+  leave, outbox cleared. The other thirty-nine keep thinking.
+- **The runtime is revived**: a run's first error latches, and while it stands
+  every later call answers a stale value after doing nothing. Revival is two
+  calls — `akbasic_runtime_clear_error()`, then the same
+  `akbasic_runtime_set_mode(RUN)` the boot needed (issue #8's mechanics).
+- **The first failure is logged, the rest are counted.** Sixty a second of the
+  same message is how a log stops being read; the count lands in the closing
+  readout as `script errors N`, where a headless run cannot miss it.
+
+The same detection runs at boot: every function in the dispatch table is
+called once against a zeroed scratch enemy, so a script that cannot run fails
+at startup with the function's name in the message — not on frame one of the
+first wave.
+
+## Step 10: Prove it
+
+**Goal: a test that fails the moment the two sides disagree.**
+
+`examples/galaga/interop_test.c` links the real `script.c` and loads the real
+`galaga.bas` — not copies — and pins the four claims this chapter made:
+
+```text
+ok: a formation bee's sway is written into akgl_Actor.x/y by the script
+ok: a diving bee above the player raises FIRE# for the engine to consume
+ok: a boss at one hit point raises actor state bit 13 from BASIC
+ok: 24000 calls survive the per-call akbasic_environment_zero() regime
+```
+
+That last claim is the per-frame contract from Chapter 20 Step 6 under a full
+game's load — forty enemies at sixty frames a second for ten seconds. CTest
+runs it as `example_galaga_interop` beside the headless game itself.
+
+And because the script is data, the proof extends to scripts nobody planned:
+run the game with `--script` pointing at a variant — enemies that never dive,
+enemies that always dive — and the engine neither knows nor cares. That
+swap-a-brain-without-rebuilding property is what the two chapters were about;
+the readout tells you how each brain did:
+
+```text
+galaga: 3000 frames, screen 2, score 2350, alive 0, kills bee 20 bfly 15 boss 1, shots bee 1 bfly 1 boss 1, script errors 0
+```
+
+## Step 11: The cost, measured
+
+**Goal: the real price of the boundary, in numbers, next to the same logic in C.**
+
+The interop test binary ends with a benchmark: 24,000 formation-hold updates —
+forty enemies at sixty frames a second for ten seconds — once through
+`galaga_script_update_enemy()` and once through a line-for-line C translation
+of `UPDATEBEE` with its helpers inlined. Same guard, same branches, same
+arithmetic; the difference is the interpreter. On this repository's build
+machine (a two-core VM, the interpreter built `-O2`):
+
+```text
+benchmark: 24000 formation-hold updates, dt 0.016
+  BASIC through the boundary:   21.147 s   881.11 us/call  35.245 ms per 40-enemy frame
+  the same logic in C:           0.000 s     0.01 us/call   0.001 ms per 40-enemy frame
+  ratio: 61022x
+```
+
+The facts, without decoration:
+
+- **A BASIC-driven update costs about four orders of magnitude more than the
+  same logic compiled.** The C translation of the whole state machine costs
+  tens of *nano*seconds; the scripted call costs high hundreds of
+  *micro*seconds.
+- **The cost is per line executed, not per call.** The interpreter scans and
+  parses each body line from source text on every call; a 3-line body measured
+  ~148 us on this class of machine, and this ~15-line body measures ~881 us.
+  Body length is the knob.
+- **At this cost, forty thinking enemies spend ~35 ms per frame on this
+  hardware** — more than two 60 Hz frames. The shipped example visibly runs
+  below 60 fps on this machine while the whole wave is alive, and exactly at
+  its frame pace once the wave thins. A faster machine moves the numbers, not
+  the shape.
+
+This is the measured version of decisions the chapters already made on
+architectural grounds. Bullets, collision and the starfield are C
+([Chapter 20](20-tutorial-galaga.md), Steps 2 and 4) — at two shots and forty
+tests a frame, scripting them would multiply the call count for things that
+decide nothing. The fire decision is one flag rather than a per-bullet
+callback (Step 6): the script's call budget is bounded by the enemy count and
+nothing else. C owns the formation and the spawn timing (Step 8), so zero
+calls happen for enemies that do not exist yet. And the 36 KiB function slots
+and 2.40 MiB runtime (Step 5) are the memory half of the same bill.
+
+What the cost buys is the previous ten steps: behavior as data, edited and
+swapped without a compiler. Whether ~900 us per thinking entity per frame is
+acceptable is a per-project decision — fewer thinkers, shorter bodies, or a
+lower think rate (every Nth frame) are the standard levers, and all three are
+host-side choices this architecture leaves open.
+
+---
+
+Where to go from here: more waves are rows in the table; a new enemy kind is
+one table row, one character file and one `DEF`; a smarter boss is edits to a
+text file while the game is closed — or a different file handed to
+`--script`. The engine is done. That is the point.

docs/README.md

@@ -16,7 +16,10 @@ embedding it, debugging it or changing it.
 **[Chapters 17](17-tutorial-breakout.md)** and **[18](18-tutorial-breakout-artwork.md)**
 are tutorials rather than reference: they build one complete game twice, two different
 ways, in numbered steps you can type in one at a time. Start with 17 — it needs nothing
-but the earlier chapters, and 18 assumes it.
+but the earlier chapters, and 18 assumes it. **[Chapters 20](20-tutorial-galaga.md)** and
+**[21](21-tutorial-galaga-enemies.md)** are the third tutorial, from the other side of
+the boundary: a C game on libakgl that embeds the interpreter as its enemy-behavior
+engine, for anyone whose question is "how do I put this in *my* game".
 
 ## Chapters
 
@@ -41,6 +44,8 @@ but the earlier chapters, and 18 assumes it.
 | **[17. Tutorial: Breakout](17-tutorial-breakout.md)** | Build a whole game out of the text grid and two `DATA` sprites, in sixteen steps |
 | **[18. Tutorial: Breakout with artwork](18-tutorial-breakout-artwork.md)** | Build it again out of loaded artwork, powerups and a drawn colour HUD, in thirteen |
 | **[19. Menus and dialogs](19-user-interface.md)** | `MENU`, `DIALOG`, `HUD` and `UISTYLE` — the widgets, and who owns the keyboard |
+| **[20. Tutorial: GALAGA](20-tutorial-galaga.md)** | Build a C engine on libakgl that embeds the interpreter, boots a script and hands it an actor |
+| **[21. Tutorial: GALAGA enemies](21-tutorial-galaga-enemies.md)** | Share three C structs with the script, then write the wave's whole brain in BASIC |
 
 ## The shortest possible start
 

examples/galaga/README.md

@@ -0,0 +1,63 @@
+# GALAGA — a C engine with akbasic embedded as its enemy brain
+
+A GALAGA-style fixed shooter whose core engine is C on libakgl, with akbasic
+linked in as the scripting engine that owns every enemy's behavior. One BASIC
+script — `galaga.bas`, nothing but `DEF` functions and an `END` — is called
+once per enemy per frame through a custom `akgl_Actor` update hook. Bullets,
+collision, scoring and screens are C forever; everything an enemy *decides* is
+BASIC.
+
+This is the checked-in example behind two tutorial chapters, and the chapters
+are the intended way in:
+
+* **[Chapter 20](../../docs/20-tutorial-galaga.md)** — the engine and the
+  boundary: from an empty file to a C game that boots a script and hands one
+  actor to BASIC.
+* **[Chapter 21](../../docs/21-tutorial-galaga-enemies.md)** — the data
+  structures and the AI: from `SELF@` to a full attacking wave.
+
+It is an academic exercise demonstrating *how* such an embed is done, not a
+claim that it is the best way to write a GALAGA.
+
+## Building and running
+
+The example builds when both example and graphics builds are on:
+
+```
+cmake -S . -B build-akgl -DAKBASIC_WITH_AKGL=ON
+cmake --build build-akgl --target akbasic_example_galaga
+build-akgl/akbasic_example_galaga
+```
+
+| Key | Does |
+|---|---|
+| Left / Right | move the ship |
+| Space | fire (two shots on screen, the classic rule) |
+| Return | choose a menu entry |
+
+## Flags
+
+```
+akbasic_example_galaga [--assets DIR] [--script PATH] [--frames N]
+                       [--autoplay] [--screenshot PATH] [--screenshot-frame N]
+```
+
+`--script` points at a different enemy script, which is the whole point of the
+architecture: edit `galaga.bas`, run again, no rebuild. `--frames N` with
+`--autoplay` is the headless smoke test CI runs under the dummy SDL drivers;
+the final log line reports frames, score, kills and shots per kind, and the
+script-error count — a wave of dumb enemies still exits 0, and that count is
+how you notice.
+
+## The files
+
+| File | Owns |
+|---|---|
+| `galaga.h` | the shared structs — the whole boundary in one header |
+| `main.c` | startup order, the frame loop, screens, the starfield |
+| `script.c` | everything that touches the interpreter |
+| `enemies.c` | wave table, formation grid, the enemy update hook |
+| `player.c` | the ship, both bullet kinds, every collision |
+| `galaga.bas` | every decision an enemy makes |
+| `interop_test.c` | round-trip proof the boundary works, run by CTest |
+| `assets/` | sprite/character JSON, and Kenney CC0 art under `assets/art/` |

examples/galaga/assets/art/License.txt

@@ -0,0 +1,14 @@
+
+###############################################################################
+
+	Space Shooter (Remastered, plus fonts and sounds) by Kenney Vleugels (www.kenney.nl)
+
+			------------------------------
+
+			        License (CC0)
+	       http://creativecommons.org/publicdomain/zero/1.0/
+
+	You may use these graphics in personal and commercial projects.
+	Credit (Kenney or www.kenney.nl) would be nice but is not mandatory.
+
+###############################################################################

examples/galaga/assets/art/PROVENANCE.md

@@ -0,0 +1,39 @@
+# Where this art came from
+
+Every PNG in this directory is from **Kenney's Space Shooter (Remastered)**, released
+into the public domain under
+[Creative Commons Zero](http://creativecommons.org/publicdomain/zero/1.0/).
+`License.txt` is the pack's own licence file, copied here unedited.
+
+* Source: <https://kenney.nl/assets/space-shooter-remastered>
+* Downloaded: 2026-08-04, `kenney_space-shooter-remastered.zip`
+* Author: Kenney (<https://www.kenney.nl>)
+* Licence: CC0 1.0. Crediting is not required; it is here because it should be.
+
+The files are the pack's `PNG/` versions, byte for byte — nothing is resized,
+recoloured or re-encoded, so the checksum of any of them still matches the
+distributed archive. `playerShip1_blue.png` sits at the top of `PNG/`; the enemies
+are from `PNG/Enemies/` and the lasers from `PNG/Lasers/`.
+
+| File | Size | Used for |
+|---|---|---|
+| `playerShip1_blue.png` | 99x75  | the player's ship |
+| `enemyBlue1.png`       | 93x84  | the bee |
+| `enemyRed2.png`        | 104x84 | the butterfly |
+| `enemyGreen3.png`      | 103x84 | the boss, at full health |
+| `enemyBlack3.png`      | 103x84 | the boss at one hit point — same silhouette, drained colour |
+| `laserBlue01.png`      | 9x54   | the player's shot |
+| `laserRed01.png`       | 9x54   | an enemy's shot |
+| `laserBlue08.png`      | 48x46  | the explosion burst |
+
+The sprites are used at their distributed size: libakgl draws a sprite at the
+sprite's own dimensions (`akgl_Actor.scale` is overwritten every frame — libakgl
+docs/12-actors.md), so there is no way to draw these smaller, and the game's
+1280x960 view is sized to fit a ten-column formation of them instead. The boss's
+damage state is the same shape in a different colour deliberately: the swap has to
+read at a glance from the top of the screen.
+
+Everything else on screen — the starfield and the HUD — is drawn by the program
+with `akgl_draw_point()` and the UI layer. See `../../README.md` for the run
+instructions and the two tutorial chapters (docs/20, docs/21) for why only the
+things that move are artwork.

examples/galaga/assets/character_galaga_bee.json

@@ -0,0 +1,16 @@
+{
+    "name": "galaga_bee",
+    "speedtime": 200,
+    "speed_x": 0.0,
+    "speed_y": 0.0,
+    "acceleration_x": 0.0,
+    "acceleration_y": 0.0,
+    "sprite_mappings": [
+        {
+            "state": [
+                "AKGL_ACTOR_STATE_ALIVE"
+            ],
+            "sprite": "galaga_bee"
+        }
+    ]
+}

examples/galaga/assets/character_galaga_boom.json

@@ -0,0 +1,16 @@
+{
+    "name": "galaga_boom",
+    "speedtime": 200,
+    "speed_x": 0.0,
+    "speed_y": 0.0,
+    "acceleration_x": 0.0,
+    "acceleration_y": 0.0,
+    "sprite_mappings": [
+        {
+            "state": [
+                "AKGL_ACTOR_STATE_ALIVE"
+            ],
+            "sprite": "galaga_boom"
+        }
+    ]
+}

examples/galaga/assets/character_galaga_boss.json

@@ -0,0 +1,23 @@
+{
+    "name": "galaga_boss",
+    "speedtime": 200,
+    "speed_x": 0.0,
+    "speed_y": 0.0,
+    "acceleration_x": 0.0,
+    "acceleration_y": 0.0,
+    "sprite_mappings": [
+        {
+            "state": [
+                "AKGL_ACTOR_STATE_ALIVE"
+            ],
+            "sprite": "galaga_boss"
+        },
+        {
+            "state": [
+                "AKGL_ACTOR_STATE_ALIVE",
+                "AKGL_ACTOR_STATE_UNDEFINED_13"
+            ],
+            "sprite": "galaga_boss_hurt"
+        }
+    ]
+}

examples/galaga/assets/character_galaga_butterfly.json

@@ -0,0 +1,16 @@
+{
+    "name": "galaga_butterfly",
+    "speedtime": 200,
+    "speed_x": 0.0,
+    "speed_y": 0.0,
+    "acceleration_x": 0.0,
+    "acceleration_y": 0.0,
+    "sprite_mappings": [
+        {
+            "state": [
+                "AKGL_ACTOR_STATE_ALIVE"
+            ],
+            "sprite": "galaga_butterfly"
+        }
+    ]
+}

examples/galaga/assets/character_galaga_enemyshot.json

@@ -0,0 +1,16 @@
+{
+    "name": "galaga_enemyshot",
+    "speedtime": 200,
+    "speed_x": 0.0,
+    "speed_y": 0.0,
+    "acceleration_x": 0.0,
+    "acceleration_y": 0.0,
+    "sprite_mappings": [
+        {
+            "state": [
+                "AKGL_ACTOR_STATE_ALIVE"
+            ],
+            "sprite": "galaga_enemyshot"
+        }
+    ]
+}

examples/galaga/assets/character_galaga_player.json

@@ -0,0 +1,16 @@
+{
+    "name": "galaga_player",
+    "speedtime": 200,
+    "speed_x": 0.0,
+    "speed_y": 0.0,
+    "acceleration_x": 0.0,
+    "acceleration_y": 0.0,
+    "sprite_mappings": [
+        {
+            "state": [
+                "AKGL_ACTOR_STATE_ALIVE"
+            ],
+            "sprite": "galaga_player"
+        }
+    ]
+}

examples/galaga/assets/character_galaga_playershot.json

@@ -0,0 +1,16 @@
+{
+    "name": "galaga_playershot",
+    "speedtime": 200,
+    "speed_x": 0.0,
+    "speed_y": 0.0,
+    "acceleration_x": 0.0,
+    "acceleration_y": 0.0,
+    "sprite_mappings": [
+        {
+            "state": [
+                "AKGL_ACTOR_STATE_ALIVE"
+            ],
+            "sprite": "galaga_playershot"
+        }
+    ]
+}

examples/galaga/assets/sprite_galaga_bee.json

@@ -0,0 +1,16 @@
+{
+    "spritesheet": {
+        "filename": "art/enemyBlue1.png",
+        "frame_width": 93,
+        "frame_height": 84
+    },
+    "name": "galaga_bee",
+    "width": 93,
+    "height": 84,
+    "speed": 200,
+    "loop": false,
+    "loopReverse": false,
+    "frames": [
+        0
+    ]
+}

examples/galaga/assets/sprite_galaga_boom.json

@@ -0,0 +1,16 @@
+{
+    "spritesheet": {
+        "filename": "art/laserBlue08.png",
+        "frame_width": 48,
+        "frame_height": 46
+    },
+    "name": "galaga_boom",
+    "width": 48,
+    "height": 46,
+    "speed": 200,
+    "loop": false,
+    "loopReverse": false,
+    "frames": [
+        0
+    ]
+}

examples/galaga/assets/sprite_galaga_boss.json

@@ -0,0 +1,16 @@
+{
+    "spritesheet": {
+        "filename": "art/enemyGreen3.png",
+        "frame_width": 103,
+        "frame_height": 84
+    },
+    "name": "galaga_boss",
+    "width": 103,
+    "height": 84,
+    "speed": 200,
+    "loop": false,
+    "loopReverse": false,
+    "frames": [
+        0
+    ]
+}

examples/galaga/assets/sprite_galaga_boss_hurt.json

@@ -0,0 +1,16 @@
+{
+    "spritesheet": {
+        "filename": "art/enemyBlack3.png",
+        "frame_width": 103,
+        "frame_height": 84
+    },
+    "name": "galaga_boss_hurt",
+    "width": 103,
+    "height": 84,
+    "speed": 200,
+    "loop": false,
+    "loopReverse": false,
+    "frames": [
+        0
+    ]
+}

examples/galaga/assets/sprite_galaga_butterfly.json

@@ -0,0 +1,16 @@
+{
+    "spritesheet": {
+        "filename": "art/enemyRed2.png",
+        "frame_width": 104,
+        "frame_height": 84
+    },
+    "name": "galaga_butterfly",
+    "width": 104,
+    "height": 84,
+    "speed": 200,
+    "loop": false,
+    "loopReverse": false,
+    "frames": [
+        0
+    ]
+}

examples/galaga/assets/sprite_galaga_enemyshot.json

@@ -0,0 +1,16 @@
+{
+    "spritesheet": {
+        "filename": "art/laserRed01.png",
+        "frame_width": 9,
+        "frame_height": 54
+    },
+    "name": "galaga_enemyshot",
+    "width": 9,
+    "height": 54,
+    "speed": 200,
+    "loop": false,
+    "loopReverse": false,
+    "frames": [
+        0
+    ]
+}

examples/galaga/assets/sprite_galaga_player.json

@@ -0,0 +1,16 @@
+{
+    "spritesheet": {
+        "filename": "art/playerShip1_blue.png",
+        "frame_width": 99,
+        "frame_height": 75
+    },
+    "name": "galaga_player",
+    "width": 99,
+    "height": 75,
+    "speed": 200,
+    "loop": false,
+    "loopReverse": false,
+    "frames": [
+        0
+    ]
+}

examples/galaga/assets/sprite_galaga_playershot.json

@@ -0,0 +1,16 @@
+{
+    "spritesheet": {
+        "filename": "art/laserBlue01.png",
+        "frame_width": 9,
+        "frame_height": 54
+    },
+    "name": "galaga_playershot",
+    "width": 9,
+    "height": 54,
+    "speed": 200,
+    "loop": false,
+    "loopReverse": false,
+    "frames": [
+        0
+    ]
+}

examples/galaga/enemies.c

@@ -0,0 +1,314 @@
+/**
+ * @file enemies.c
+ * @brief The formation, the wave, and the hook that hands each enemy to BASIC.
+ *
+ * C owns the grid, the wave table and the spawn timing; BASIC owns everything
+ * an enemy does after it exists. The formation slot arrives in SELF@.HOMEX% /
+ * HOMEY%, so even the idle breathing of the grid is the script's, computed
+ * relative to home.
+ */
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
+#include <SDL3/SDL.h>
+
+#include <akerror.h>
+#include <akstdlib.h>
+
+#include <akgl/actor.h>
+#include <akgl/error.h>
+#include <akgl/game.h>
+#include <akgl/heap.h>
+
+#include "galaga.h"
+
+galaga_Enemy galaga_enemies[GALAGA_MAX_ENEMIES];
+akgl_Actor *galaga_enemy_actors[GALAGA_MAX_ENEMIES];
+
+/* Explosion lifetimes, indexed by heap slot. An explosion is an actor with
+ * nothing to decide, so its whole state is one countdown. */
+static float BOOM_TTL[AKGL_MAX_HEAP_ACTOR];
+
+/* A spawn serial per shot so registry names never collide while two shots
+ * with the same slot number are briefly both alive. */
+static uint32_t SHOT_SERIAL = 0;
+static uint32_t BOOM_SERIAL = 0;
+
+/*
+ * The wave, one row per formation row. Columns are 0..9 at GALAGA_COL_PITCH;
+ * `first` and `count` say which columns the row fills. 40 enemies: 4 bosses,
+ * 16 butterflies, 20 bees -- 59 of the 64 actor heap slots at peak, counting
+ * the player, two player shots, eight enemy shots and eight explosions.
+ */
+static const struct
+{
+    int32_t kind;	/* GALAGA_ENEMY_*	*/
+    int     row;	/* formation row	*/
+    int     first;	/* first column filled	*/
+    int     count;	/* columns filled	*/
+    int32_t hp;
+}
+WAVE_ROWS[] = {
+    /*  kind                    row  first  count  hp  */
+    { GALAGA_ENEMY_BOSS,	 0,     3,     4,   2 },
+    { GALAGA_ENEMY_BUTTERFLY,	 1,     1,     8,   1 },
+    { GALAGA_ENEMY_BUTTERFLY,	 2,     1,     8,   1 },
+    { GALAGA_ENEMY_BEE,		 3,     0,    10,   1 },
+    { GALAGA_ENEMY_BEE,		 4,     0,    10,   1 }
+};
+#define WAVE_ROW_COUNT ((int)(sizeof(WAVE_ROWS) / sizeof(WAVE_ROWS[0])))
+
+/* Enemy kind -> character name, the render half of the dispatch table. */
+static char *ENEMY_CHARACTER[GALAGA_ENEMY_KINDS] = {
+    "galaga_bee",
+    "galaga_butterfly",
+    "galaga_boss"
+};
+
+/* --------------------------------------------------------------- random --- */
+
+/*
+ * No RND verb exists (issue #16), so the engine is the script's only source
+ * of randomness: it refreshes GAME@.RND% each frame and SELF@.RND% each call
+ * from this PRNG. A hand-rolled LCG rather than rand() so a headless run is
+ * the same game on every libc.
+ */
+static uint32_t PRNG_STATE = 0x12345678u;
+
+float galaga_random(void)
+{
+    PRNG_STATE = PRNG_STATE * 1664525u + 1013904223u;
+    return (float)(PRNG_STATE >> 8) / (float)0x01000000u;
+}
+
+/* -------------------------------------------------------------- helpers --- */
+
+static akerr_ErrorContext *release_actor(akgl_Actor *actor)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, actor, AKERR_NULLPOINTER, "actor");
+    PASS(errctx, akgl_heap_release_actor(actor));
+    SUCCEED_RETURN(errctx);
+}
+
+/* ---------------------------------------------------------------- shots --- */
+
+/**
+ * @brief Move an enemy shot; release it once it has left the screen.
+ */
+static akerr_ErrorContext *enemy_shot_update(akgl_Actor *obj)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj");
+    obj->y += 380.0f * galaga_game.dt;
+    if ( obj->y > (float)GALAGA_VIEW_HEIGHT + 60.0f ) {
+	galaga_game.enemy_shots_live -= 1;
+	PASS(errctx, release_actor(obj));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Consume an enemy's fire flag: take an actor and aim it downward.
+ *
+ * The script only raises a flag. Spawning takes a slot from the actor heap,
+ * and pool exhaustion must be a C-side refusal with the house error context --
+ * so C consumes the flag and does the spawn. The engine also enforces the
+ * eight-shot cap by simply not consuming the flag's wish.
+ */
+static akerr_ErrorContext *enemy_fire(galaga_Enemy *enemy, akgl_Actor *from)
+{
+    akgl_Actor *shot = NULL;
+    char name[32];
+    int count = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, enemy, AKERR_NULLPOINTER, "enemy");
+    FAIL_ZERO_RETURN(errctx, from, AKERR_NULLPOINTER, "from");
+
+    enemy->fire = 0;
+    if ( galaga_game.enemy_shots_live >= GALAGA_MAX_ENEMY_SHOTS ) {
+	SUCCEED_RETURN(errctx);
+    }
+
+    SHOT_SERIAL += 1;
+    PASS(errctx, aksl_snprintf(&count, name, sizeof(name), "eshot%u", SHOT_SERIAL));
+    PASS(errctx, akgl_heap_next_actor(&shot));
+    PASS(errctx, akgl_actor_initialize(shot, name));
+    PASS(errctx, akgl_actor_set_character(shot, "galaga_enemyshot"));
+    /* AFTER initialize: it resets all seven hooks. */
+    shot->updatefunc = &enemy_shot_update;
+    shot->movement_controls_face = false;
+    shot->state = AKGL_ACTOR_STATE_ALIVE;
+    /* akgl_actor_initialize() does not raise `visible`; a hand-spawned actor
+     * that skips this line exists, moves and collides -- invisibly. */
+    shot->visible = true;
+    /* Actor x/y is a sprite's top-left corner; the shot leaves the enemy's
+     * midline. Enemy sprites run 93..104 wide, the shot is 9. */
+    shot->x = from->x + 46.0f;
+    shot->y = from->y + 60.0f;
+
+    galaga_game.enemy_shots_live += 1;
+    galaga_game.shots[enemy->kind] += 1;
+    SUCCEED_RETURN(errctx);
+}
+
+/* ----------------------------------------------------------- explosions --- */
+
+static akerr_ErrorContext *boom_update(akgl_Actor *obj)
+{
+    ptrdiff_t slot = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj");
+    slot = obj - akgl_heap_actors;
+    BOOM_TTL[slot] -= galaga_game.dt;
+    if ( BOOM_TTL[slot] <= 0.0f ) {
+	PASS(errctx, release_actor(obj));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *galaga_boom_spawn(float x, float y)
+{
+    akgl_Actor *boom = NULL;
+    char name[32];
+    int count = 0;
+    PREPARE_ERROR(errctx);
+
+    ATTEMPT {
+	CATCH(errctx, akgl_heap_next_actor(&boom));
+	BOOM_SERIAL += 1;
+	CATCH(errctx, aksl_snprintf(&count, name, sizeof(name), "boom%u", BOOM_SERIAL));
+	CATCH(errctx, akgl_actor_initialize(boom, name));
+	CATCH(errctx, akgl_actor_set_character(boom, "galaga_boom"));
+	boom->updatefunc = &boom_update;
+	boom->movement_controls_face = false;
+	boom->state = AKGL_ACTOR_STATE_ALIVE;
+	boom->visible = true;
+	boom->x = x;
+	boom->y = y;
+	BOOM_TTL[boom - akgl_heap_actors] = 0.25f;
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } HANDLE(errctx, AKGL_ERR_HEAP) {
+	/* Explosions are decoration. When the heap is momentarily full the
+	 * right outcome is no explosion, not a dead frame -- this is the one
+	 * spawn that absorbs exhaustion. */
+    } FINISH(errctx, true);
+    SUCCEED_RETURN(errctx);
+}
+
+/* --------------------------------------------------------------- enemies --- */
+
+/**
+ * @brief The custom update hook: one enemy, once per frame, thought in BASIC.
+ *
+ * The whole body is the protocol from docs/20: refresh the inbox, hand the
+ * pair to the script, consume the outbox. akgl_game_update() calls this in
+ * place of akgl_actor_update() because spawn replaced the hook.
+ */
+static akerr_ErrorContext *enemy_update(akgl_Actor *obj)
+{
+    galaga_Enemy *enemy = NULL;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj");
+    enemy = (galaga_Enemy *)obj->actorData;
+    FAIL_ZERO_RETURN(errctx, enemy, AKERR_NULLPOINTER, "an enemy actor with no galaga_Enemy attached");
+
+    enemy->rnd = galaga_random();
+    PASS(errctx, galaga_script_update_enemy(enemy, obj, galaga_game.dt));
+    if ( enemy->fire != 0 ) {
+	PASS(errctx, enemy_fire(enemy, obj));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *galaga_wave_spawn(void)
+{
+    akgl_Actor *actor = NULL;
+    galaga_Enemy *enemy = NULL;
+    char name[32];
+    int row = 0;
+    int col = 0;
+    int index = 0;
+    int count = 0;
+    PREPARE_ERROR(errctx);
+
+    for ( row = 0; row < WAVE_ROW_COUNT; row++ ) {
+	for ( col = 0; col < WAVE_ROWS[row].count; col++ ) {
+	    FAIL_NONZERO_RETURN(errctx, (index >= GALAGA_MAX_ENEMIES), AKERR_OUTOFBOUNDS,
+				"The wave table places more than %d enemies", GALAGA_MAX_ENEMIES);
+	    enemy = &galaga_enemies[index];
+	    memset(enemy, 0, sizeof(*enemy));
+	    enemy->kind = WAVE_ROWS[row].kind;
+	    enemy->state = GALAGA_ES_ENTERING;
+	    enemy->homex = (float)(GALAGA_FORM_LEFT
+				   + (WAVE_ROWS[row].first + col) * GALAGA_COL_PITCH);
+	    enemy->homey = (float)(GALAGA_FORM_TOP + WAVE_ROWS[row].row * GALAGA_ROW_PITCH);
+	    enemy->hp = WAVE_ROWS[row].hp;
+	    /* Stagger the entries: each enemy's clock starts in the past, and
+	     * the script holds still until its own t crosses zero. */
+	    enemy->t = -0.08f * (float)index;
+
+	    PASS(errctx, aksl_snprintf(&count, name, sizeof(name), "enemy%02d", index));
+	    PASS(errctx, akgl_heap_next_actor(&actor));
+	    PASS(errctx, akgl_actor_initialize(actor, name));
+	    PASS(errctx, akgl_actor_set_character(actor, ENEMY_CHARACTER[enemy->kind]));
+	    /* AFTER initialize: it resets all seven hooks. */
+	    actor->updatefunc = &enemy_update;
+	    actor->actorData = enemy;
+	    /* Nothing here moves by state bits, and an actor whose state word
+	     * matches no character mapping is silently not drawn -- so facing
+	     * stays entirely out of the state word. */
+	    actor->movement_controls_face = false;
+	    actor->state = AKGL_ACTOR_STATE_ALIVE;
+	    /* akgl_actor_initialize() does not raise `visible` -- the map
+	     * loader copies it from map data, and there is no map here. Skip
+	     * this and the whole wave exists, moves, fires and dies without
+	     * ever being drawn. */
+	    actor->visible = true;
+	    /* Off screen above, pouring in from whichever side is closer. */
+	    actor->x = (enemy->homex < (float)GALAGA_VIEW_WIDTH / 2.0f)
+		? -80.0f : (float)GALAGA_VIEW_WIDTH + 80.0f;
+	    actor->y = -80.0f;
+
+	    galaga_enemy_actors[index] = actor;
+	    index += 1;
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *galaga_wave_release(void)
+{
+    int i = 0;
+    PREPARE_ERROR(errctx);
+
+    for ( i = 0; i < GALAGA_MAX_ENEMIES; i++ ) {
+	if ( galaga_enemy_actors[i] != NULL ) {
+	    PASS(errctx, release_actor(galaga_enemy_actors[i]));
+	    galaga_enemy_actors[i] = NULL;
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+int galaga_enemies_alive(void)
+{
+    int i = 0;
+    int alive = 0;
+
+    for ( i = 0; i < GALAGA_MAX_ENEMIES; i++ ) {
+	if ( galaga_enemy_actors[i] != NULL ) {
+	    alive += 1;
+	}
+    }
+    return alive;
+}

examples/galaga/galaga.bas

@@ -0,0 +1,119 @@
+REM GALAGA enemy behavior. The C engine loads this file, runs it once so the
+REM definitions exist, and then calls one UPDATE function per enemy per frame.
+REM There is no top-level code: definitions, then END.
+REM
+REM Names the engine binds before every call:
+REM   SELF@  - this enemy's record (ENEMY): the state machine's memory
+REM   ACTOR@ - the engine's live actor (ACTOR): position is the real thing
+REM   GAME@  - shared frame state (GAME): player position, wave, randomness
+REM
+REM SELF@.STATE# bits: 1 = entering  2 = in formation  4 = diving
+REM
+REM Two rules of this dialect that bite here, both from docs/03:
+REM   - the LEFT operand decides integer or float arithmetic, so a float
+REM     always goes first: SELF@.T% * 150 + 260, never 260 + 150 * SELF@.T%
+REM   - RETURN at the start of a line ends the DEF body, so every early
+REM     return rides an IF ... THEN, and only the last RETURN starts a line
+
+REM Ease toward the formation slot, with a little entry swirl.
+REM Answers 1 once the slot is reached, else 0.
+DEF GLIDEHOME(DT%)
+  DX% = SELF@.HOMEX% - ACTOR@.X%
+  DY% = SELF@.HOMEY% - ACTOR@.Y%
+  K% = DT% * 4.5
+  IF K% > 1 THEN K% = 1
+  ACTOR@.X% = ACTOR@.X% + DX% * K% + SIN(SELF@.T% * 6) * 90 * DT%
+  ACTOR@.Y% = ACTOR@.Y% + DY% * K%
+  IF ABS(DX%) < 3 AND ABS(DY%) < 3 THEN RETURN 1
+  RETURN 0
+
+REM One frame of a dive: accelerate downward, weave, lean toward the
+REM player's column, and glide back in from the top after falling out.
+DEF DIVESTEP(DT%, WEAVE%, LEAD%)
+  SPD% = SELF@.T% * 150 + 260
+  ACTOR@.Y% = ACTOR@.Y% + SPD% * DT%
+  ACTOR@.X% = ACTOR@.X% + SIN(SELF@.T% * 4) * WEAVE% * DT%
+  DX% = GAME@.PLAYERX% - ACTOR@.X%
+  IF DX% > 220 THEN DX% = 220
+  IF DX% < -220 THEN DX% = -220
+  ACTOR@.X% = ACTOR@.X% + DX% * LEAD% * DT%
+  IF ACTOR@.Y% > 1040 THEN BEGIN
+    ACTOR@.Y% = 0.0 - 90
+    SELF@.STATE# = 1
+    SELF@.T% = 0
+  BEND
+  RETURN 0
+
+REM Raise the fire flag when diving roughly above the player. The engine
+REM consumes FIRE# and does the spawning; the script only wishes.
+DEF DECIDEFIRE(DT%)
+  DX% = GAME@.PLAYERX% - ACTOR@.X%
+  IF ABS(DX%) > 140 THEN RETURN 0
+  IF ACTOR@.Y% > GAME@.PLAYERY% THEN RETURN 0
+  IF SELF@.RND% < DT% * 1.5 THEN SELF@.FIRE# = 1
+  RETURN 0
+
+REM Bee: enter, breathe in formation, occasionally dive nearly straight.
+DEF UPDATEBEE(DT%)
+  SELF@.T% = SELF@.T% + DT%
+  IF SELF@.T% < 0 THEN RETURN 0
+  S# = SELF@.STATE#
+  IF (S# AND 1) > 0 THEN BEGIN
+    R# = GLIDEHOME(DT%)
+    IF R# = 1 THEN SELF@.STATE# = 2 : SELF@.T% = 0
+  BEND
+  IF (S# AND 2) > 0 THEN BEGIN
+    ACTOR@.X% = SELF@.HOMEX% + SIN(SELF@.T% * 1.7) * 16
+    ACTOR@.Y% = SELF@.HOMEY%
+    IF SELF@.RND% < DT% * 0.04 THEN SELF@.STATE# = 4 : SELF@.T% = 0
+  BEND
+  IF (S# AND 4) > 0 THEN BEGIN
+    R# = DIVESTEP(DT%, 130, 0.2)
+    R# = DECIDEFIRE(DT%)
+  BEND
+  RETURN 0
+
+REM Butterfly: the same machine with a wide lateral weave on the dive.
+DEF UPDATEBFLY(DT%)
+  SELF@.T% = SELF@.T% + DT%
+  IF SELF@.T% < 0 THEN RETURN 0
+  S# = SELF@.STATE#
+  IF (S# AND 1) > 0 THEN BEGIN
+    R# = GLIDEHOME(DT%)
+    IF R# = 1 THEN SELF@.STATE# = 2 : SELF@.T% = 0
+  BEND
+  IF (S# AND 2) > 0 THEN BEGIN
+    ACTOR@.X% = SELF@.HOMEX% + SIN(SELF@.T% * 2.1) * 24
+    ACTOR@.Y% = SELF@.HOMEY%
+    IF SELF@.RND% < DT% * 0.05 THEN SELF@.STATE# = 4 : SELF@.T% = 0
+  BEND
+  IF (S# AND 4) > 0 THEN BEGIN
+    R# = DIVESTEP(DT%, 260, 0.1)
+    R# = DECIDEFIRE(DT%)
+  BEND
+  RETURN 0
+
+REM Boss: two hit points, a slow sway, and a dive that leads the player.
+REM At one hit point it raises actor state bit 13 (8192), and the engine's
+REM character mapping swaps the sprite - the boundary crossed the other way.
+DEF UPDATEBOSS(DT%)
+  SELF@.T% = SELF@.T% + DT%
+  IF SELF@.T% < 0 THEN RETURN 0
+  IF SELF@.HP# = 1 THEN ACTOR@.STATE# = ACTOR@.STATE# OR 8192
+  S# = SELF@.STATE#
+  IF (S# AND 1) > 0 THEN BEGIN
+    R# = GLIDEHOME(DT%)
+    IF R# = 1 THEN SELF@.STATE# = 2 : SELF@.T% = 0
+  BEND
+  IF (S# AND 2) > 0 THEN BEGIN
+    ACTOR@.X% = SELF@.HOMEX% + SIN(SELF@.T% * 1.1) * 10
+    ACTOR@.Y% = SELF@.HOMEY%
+    IF SELF@.RND% < DT% * 0.03 THEN SELF@.STATE# = 4 : SELF@.T% = 0
+  BEND
+  IF (S# AND 4) > 0 THEN BEGIN
+    R# = DIVESTEP(DT%, 60, 0.9)
+    R# = DECIDEFIRE(DT%)
+  BEND
+  RETURN 0
+
+END

examples/galaga/galaga.h

@@ -0,0 +1,155 @@
+/**
+ * @file galaga.h
+ * @brief Shared declarations for the GALAGA embedding example.
+ *
+ * The engine is C on libakgl; the enemies think in BASIC. Everything the two
+ * sides share crosses in exactly one place: the three structures below, which
+ * script.c registers as host types so a script reads and writes them directly.
+ * docs/20-tutorial-galaga.md and docs/21-tutorial-galaga-enemies.md build this
+ * program from an empty file; the split between files follows the split
+ * between chapters.
+ */
+
+#ifndef _GALAGA_H_
+#define _GALAGA_H_
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#include <akerror.h>
+
+#include <akgl/actor.h>
+
+/* ------------------------------------------------------------- geometry --- */
+
+/*
+ * The view is sized to the artwork rather than the other way round: the Kenney
+ * sprites are ~100 pixels wide, libakgl has no way to draw a sprite smaller
+ * than it is (akgl_Actor.scale is overwritten every frame -- libakgl
+ * docs/12-actors.md), and a ten-column formation of them needs 1120 pixels.
+ */
+#define GALAGA_VIEW_WIDTH	1280
+#define GALAGA_VIEW_HEIGHT	960
+
+#define GALAGA_FORM_COLUMNS	10	/* formation width, in slots	*/
+#define GALAGA_FORM_LEFT	136	/* x of column 0, map pixels	*/
+#define GALAGA_FORM_TOP		120	/* y of row 0, map pixels	*/
+#define GALAGA_COL_PITCH	112
+#define GALAGA_ROW_PITCH	100
+
+#define GALAGA_PLAYER_Y		860.0f
+#define GALAGA_PLAYER_SPEED	420.0f	/* map pixels per second	*/
+#define GALAGA_PLAYER_MARGIN	60.0f	/* how close to the edge it may go */
+
+/* ------------------------------------------------------------- entities --- */
+
+#define GALAGA_ENEMY_BEE	0
+#define GALAGA_ENEMY_BUTTERFLY	1
+#define GALAGA_ENEMY_BOSS	2
+#define GALAGA_ENEMY_KINDS	3
+
+#define GALAGA_MAX_ENEMIES	40
+#define GALAGA_MAX_PLAYER_SHOTS	2	/* the classic two-on-screen rule */
+#define GALAGA_MAX_ENEMY_SHOTS	8
+
+/*
+ * galaga_Enemy.state bits. The script owns these transitions; the engine only
+ * writes the word at spawn and when a script error forces an enemy dumb.
+ * galaga.bas spells the same three values as literals, with a REM naming them.
+ *
+ * 8             0
+ * 0 0 0 0 0 1 1 1
+ *           | | `-- ENTERING: flying its entry path toward the formation slot
+ *           | `---- FORMATION: holding (and breathing around) homex/homey
+ *           `------ DIVING: attacking, off the grid until it leaves the screen
+ */
+#define GALAGA_ES_ENTERING	(1 << 0)
+#define GALAGA_ES_FORMATION	(1 << 1)
+#define GALAGA_ES_DIVING	(1 << 2)
+
+/** @brief One enemy, as both sides see it. Hangs off akgl_Actor.actorData. */
+typedef struct galaga_Enemy
+{
+    int32_t  kind;	/* GALAGA_ENEMY_BEE / BUTTERFLY / BOSS		*/
+    int32_t  state;	/* GALAGA_ES_* bit flags			*/
+    float    homex;	/* formation slot, in map pixels		*/
+    float    homey;
+    float    t;		/* parametric clock for the current maneuver	*/
+    int32_t  hp;
+    int32_t  fire;	/* outbox: script sets 1, engine consumes	*/
+    float    rnd;	/* inbox: engine writes fresh 0..1 each call	*/
+} galaga_Enemy;
+
+/** @brief Frame state every enemy may read. Bound once as GAME@. */
+typedef struct galaga_Shared
+{
+    float    playerx;	/* the player actor's position, this frame	*/
+    float    playery;
+    int32_t  wave;
+    float    rnd;	/* fresh 0..1 each frame; the issue #16 route	*/
+} galaga_Shared;
+
+/* --------------------------------------------------------------- screens --- */
+
+typedef enum
+{
+    GALAGA_SCREEN_TITLE = 0,
+    GALAGA_SCREEN_PLAY,
+    GALAGA_SCREEN_GAMEOVER,
+    GALAGA_SCREEN_VICTORY
+} galaga_Screen;
+
+/* ------------------------------------------------------------ game state --- */
+
+typedef struct galaga_Game
+{
+    galaga_Screen screen;
+    int      frame;
+    float    dt;		/* seconds, clamped; see main.c		*/
+    bool     autoplay;
+
+    int      score;
+    int      lives;
+    int      kills[GALAGA_ENEMY_KINDS];
+    int      shots[GALAGA_ENEMY_KINDS];	/* shots each kind fired	*/
+    int      script_errors;
+
+    akgl_Actor *player;
+    float    fire_cooldown;
+    float    respawn_timer;	/* > 0 while the player is invulnerable	*/
+    bool     firing;
+    bool     moveleft;
+    bool     moveright;
+
+    int      player_shots_live;
+    int      enemy_shots_live;
+} galaga_Game;
+
+extern galaga_Game galaga_game;
+extern galaga_Shared galaga_shared;
+
+extern galaga_Enemy galaga_enemies[GALAGA_MAX_ENEMIES];
+extern akgl_Actor *galaga_enemy_actors[GALAGA_MAX_ENEMIES];
+
+/* ---------------------------------------------------------------- script --- */
+
+akerr_ErrorContext AKERR_NOIGNORE *galaga_script_boot(char *path);
+akerr_ErrorContext AKERR_NOIGNORE *galaga_script_update_enemy(galaga_Enemy *enemy, akgl_Actor *actor, float dt);
+
+/* --------------------------------------------------------------- enemies --- */
+
+akerr_ErrorContext AKERR_NOIGNORE *galaga_wave_spawn(void);
+akerr_ErrorContext AKERR_NOIGNORE *galaga_wave_release(void);
+int galaga_enemies_alive(void);
+akerr_ErrorContext AKERR_NOIGNORE *galaga_boom_spawn(float x, float y);
+
+/* ---------------------------------------------------------------- player --- */
+
+akerr_ErrorContext AKERR_NOIGNORE *galaga_player_spawn(void);
+akerr_ErrorContext AKERR_NOIGNORE *galaga_player_controls(void);
+akerr_ErrorContext AKERR_NOIGNORE *galaga_player_autoplay(int frame);
+
+/** @brief A 0..1 random draw from the engine's own PRNG (see enemies.c). */
+float galaga_random(void);
+
+#endif // _GALAGA_H_

examples/galaga/interop_test.c

@@ -0,0 +1,265 @@
+/**
+ * @file interop_test.c
+ * @brief Round-trip test for the galaga boundary, hoststruct.c-style.
+ *
+ * Links the real script.c and the real galaga.bas -- not copies -- so this
+ * fails the moment the boundary and the script disagree. The four claims it
+ * pins:
+ *
+ *  1. The script writes the engine's actor memory: a formation enemy's sway
+ *     lands in akgl_Actor.x with no marshalling step.
+ *  2. The outbox works: a diving enemy above the player raises FIRE# and the
+ *     C side reads it.
+ *  3. The boss flips actor state bit 13 at one hit point -- the boundary
+ *     crossed engine-ward.
+ *  4. Sustained calling holds: 24000 calls through the per-call
+ *     akbasic_environment_zero() regime, the load a 40-enemy wave puts on
+ *     the runtime in ten seconds.
+ *
+ * Exit status equals the number of failed claims.
+ */
+
+#include <math.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <string.h>
+#include <time.h>
+
+#include <akerror.h>
+
+#include <akgl/actor.h>
+
+#include "galaga.h"
+
+#ifndef GALAGA_SCRIPT_PATH
+#define GALAGA_SCRIPT_PATH "galaga.bas"
+#endif
+
+/* script.c reads these; main.c usually defines them. This test is the host. */
+galaga_Game galaga_game;
+galaga_Shared galaga_shared;
+
+static int FAILURES = 0;
+
+#define CLAIM(__cond, __text)						\
+    if ( !(__cond) ) {							\
+	fprintf(stderr, "FAILED: %s\n", __text);			\
+	FAILURES += 1;							\
+    } else {								\
+	printf("ok: %s\n", __text);					\
+    }
+
+static akerr_ErrorContext *run_claims(void)
+{
+    galaga_Enemy enemy;
+    akgl_Actor actor;
+    int i = 0;
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, galaga_script_boot((char *)GALAGA_SCRIPT_PATH));
+
+    /* --- 1: formation sway lands in the actor ---------------------------- */
+    memset(&enemy, 0, sizeof(enemy));
+    memset(&actor, 0, sizeof(actor));
+    enemy.kind = GALAGA_ENEMY_BEE;
+    enemy.state = GALAGA_ES_FORMATION;
+    enemy.homex = 400.0f;
+    enemy.homey = 300.0f;
+    enemy.hp = 1;
+    actor.x = 0.0f;
+    actor.y = 0.0f;
+    PASS(errctx, galaga_script_update_enemy(&enemy, &actor, 0.016f));
+    CLAIM((fabsf(actor.x - enemy.homex) <= 16.5f) && (actor.y == enemy.homey),
+	  "a formation bee's sway is written into akgl_Actor.x/y by the script");
+
+    /* --- 2: the fire outbox ---------------------------------------------- */
+    memset(&enemy, 0, sizeof(enemy));
+    memset(&actor, 0, sizeof(actor));
+    enemy.kind = GALAGA_ENEMY_BEE;
+    enemy.state = GALAGA_ES_DIVING;
+    enemy.rnd = 0.0f;			/* 0.0 < DT% * 1.5: always willing */
+    actor.x = 600.0f;
+    actor.y = 200.0f;
+    galaga_shared.playerx = 610.0f;	/* just off the shot's column      */
+    galaga_shared.playery = 860.0f;	/* well below                      */
+    PASS(errctx, galaga_script_update_enemy(&enemy, &actor, 0.016f));
+    CLAIM(enemy.fire == 1,
+	  "a diving bee above the player raises FIRE# for the engine to consume");
+
+    /* --- 3: the boss's hurt bit ------------------------------------------ */
+    memset(&enemy, 0, sizeof(enemy));
+    memset(&actor, 0, sizeof(actor));
+    enemy.kind = GALAGA_ENEMY_BOSS;
+    enemy.state = GALAGA_ES_FORMATION;
+    enemy.homex = 500.0f;
+    enemy.homey = 120.0f;
+    enemy.hp = 1;
+    actor.state = AKGL_ACTOR_STATE_ALIVE;
+    PASS(errctx, galaga_script_update_enemy(&enemy, &actor, 0.016f));
+    CLAIM((actor.state & AKGL_ACTOR_STATE_UNDEFINED_13) != 0,
+	  "a boss at one hit point raises actor state bit 13 from BASIC");
+
+    /* --- 4: sustained calling --------------------------------------------- */
+    memset(&enemy, 0, sizeof(enemy));
+    memset(&actor, 0, sizeof(actor));
+    enemy.kind = GALAGA_ENEMY_BEE;
+    enemy.state = GALAGA_ES_FORMATION;
+    enemy.homex = 400.0f;
+    enemy.homey = 300.0f;
+    for ( i = 0; i < 24000; i++ ) {
+	enemy.rnd = 0.9f;		/* never dive: keep the state put */
+	PASS(errctx, galaga_script_update_enemy(&enemy, &actor, 0.016f));
+    }
+    CLAIM(galaga_game.script_errors == 0,
+	  "24000 calls survive the per-call akbasic_environment_zero() regime");
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------ benchmark --- */
+
+/**
+ * @brief UPDATEBEE's state machine, translated line for line into C.
+ *
+ * The native comparator for the benchmark below: the same guard, the same
+ * three branches, the same arithmetic as galaga.bas's UPDATEBEE with its
+ * helpers inlined. Nothing is simplified, so the timing difference is the
+ * interpreter's, not the algorithm's.
+ */
+static void native_updatebee(galaga_Enemy *enemy, akgl_Actor *actor, float dt)
+{
+    float dx = 0.0f;
+    float dy = 0.0f;
+    float k = 0.0f;
+    int32_t s = 0;
+
+    enemy->t += dt;
+    if ( enemy->t < 0.0f ) {
+	return;
+    }
+    s = enemy->state;
+    if ( (s & GALAGA_ES_ENTERING) != 0 ) {
+	dx = enemy->homex - actor->x;
+	dy = enemy->homey - actor->y;
+	k = dt * 4.5f;
+	if ( k > 1.0f ) {
+	    k = 1.0f;
+	}
+	actor->x += dx * k + sinf(enemy->t * 6.0f) * 90.0f * dt;
+	actor->y += dy * k;
+	if ( fabsf(dx) < 3.0f && fabsf(dy) < 3.0f ) {
+	    enemy->state = GALAGA_ES_FORMATION;
+	    enemy->t = 0.0f;
+	}
+    }
+    if ( (s & GALAGA_ES_FORMATION) != 0 ) {
+	actor->x = enemy->homex + sinf(enemy->t * 1.7f) * 16.0f;
+	actor->y = enemy->homey;
+	if ( enemy->rnd < dt * 0.04f ) {
+	    enemy->state = GALAGA_ES_DIVING;
+	    enemy->t = 0.0f;
+	}
+    }
+    if ( (s & GALAGA_ES_DIVING) != 0 ) {
+	actor->y += (enemy->t * 150.0f + 260.0f) * dt;
+	actor->x += sinf(enemy->t * 4.0f) * 130.0f * dt;
+	dx = galaga_shared.playerx - actor->x;
+	if ( dx > 220.0f ) {
+	    dx = 220.0f;
+	}
+	if ( dx < -220.0f ) {
+	    dx = -220.0f;
+	}
+	actor->x += dx * 0.2f * dt;
+	if ( actor->y > 1040.0f ) {
+	    actor->y = -90.0f;
+	    enemy->state = GALAGA_ES_ENTERING;
+	    enemy->t = 0.0f;
+	}
+	dx = galaga_shared.playerx - actor->x;
+	if ( fabsf(dx) <= 140.0f && actor->y <= galaga_shared.playery
+	     && enemy->rnd < dt * 1.5f ) {
+	    enemy->fire = 1;
+	}
+    }
+}
+
+static double seconds_since(const struct timespec *t0)
+{
+    struct timespec t1;
+
+    clock_gettime(CLOCK_MONOTONIC, &t1);
+    return (double)(t1.tv_sec - t0->tv_sec) + (double)(t1.tv_nsec - t0->tv_nsec) / 1e9;
+}
+
+/**
+ * @brief The cost of thinking in BASIC, measured against the same logic in C.
+ *
+ * Both loops run the identical formation-hold workload, 24,000 calls -- forty
+ * enemies at sixty frames a second for ten seconds. Informational: nothing
+ * asserts on the timing, because CI machines vary; the numbers print so the
+ * tutorial can quote a real measurement.
+ */
+static akerr_ErrorContext *run_benchmark(void)
+{
+    galaga_Enemy enemy;
+    akgl_Actor actor;
+    struct timespec t0;
+    double basic_s = 0.0;
+    double native_s = 0.0;
+    int i = 0;
+    PREPARE_ERROR(errctx);
+
+    memset(&enemy, 0, sizeof(enemy));
+    memset(&actor, 0, sizeof(actor));
+    enemy.kind = GALAGA_ENEMY_BEE;
+    enemy.state = GALAGA_ES_FORMATION;
+    enemy.homex = 400.0f;
+    enemy.homey = 300.0f;
+    enemy.rnd = 0.9f;
+
+    clock_gettime(CLOCK_MONOTONIC, &t0);
+    for ( i = 0; i < 24000; i++ ) {
+	PASS(errctx, galaga_script_update_enemy(&enemy, &actor, 0.016f));
+    }
+    basic_s = seconds_since(&t0);
+
+    memset(&enemy, 0, sizeof(enemy));
+    memset(&actor, 0, sizeof(actor));
+    enemy.kind = GALAGA_ENEMY_BEE;
+    enemy.state = GALAGA_ES_FORMATION;
+    enemy.homex = 400.0f;
+    enemy.homey = 300.0f;
+    enemy.rnd = 0.9f;
+
+    clock_gettime(CLOCK_MONOTONIC, &t0);
+    for ( i = 0; i < 24000; i++ ) {
+	native_updatebee(&enemy, &actor, 0.016f);
+    }
+    native_s = seconds_since(&t0);
+
+    printf("benchmark: 24000 formation-hold updates, dt 0.016\n");
+    printf("  BASIC through the boundary: %8.3f s  %7.2f us/call  %6.3f ms per 40-enemy frame\n",
+	   basic_s, basic_s / 24000.0 * 1e6, basic_s / 24000.0 * 40.0 * 1e3);
+    printf("  the same logic in C:        %8.3f s  %7.2f us/call  %6.3f ms per 40-enemy frame\n",
+	   native_s, native_s / 24000.0 * 1e6, native_s / 24000.0 * 40.0 * 1e3);
+    printf("  ratio: %.0fx\n", basic_s / native_s);
+    SUCCEED_RETURN(errctx);
+}
+
+int main(void)
+{
+    PREPARE_ERROR(errctx);
+
+    ATTEMPT {
+	CATCH(errctx, run_claims());
+	CATCH(errctx, run_benchmark());
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } HANDLE_DEFAULT(errctx) {
+	LOG_ERROR_WITH_MESSAGE(errctx, "the interop test could not run");
+	FAILURES += 1;
+    } FINISH_NORETURN(errctx);
+
+    return FAILURES;
+}

examples/galaga/main.c

@@ -0,0 +1,698 @@
+/**
+ * @file main.c
+ * @brief Startup, the frame loop, the screens, and teardown.
+ *
+ * The startup order is libakgl's one sequence that works (deps/libakgl
+ * include/akgl/game.h): metadata, akgl_game_init(), screen properties,
+ * akgl_render_2d_init(), a physics backend -- and then, new in this example,
+ * the interpreter. The scripts compute, the engine draws; the interpreter is
+ * lent no devices at all, so a script that tries SPRITE is refused by name.
+ */
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <string.h>
+
+#include <SDL3/SDL.h>
+#include <SDL3_image/SDL_image.h>
+#include <SDL3_ttf/SDL_ttf.h>
+
+#include <akerror.h>
+#include <akstdlib.h>
+
+#include <akgl/actor.h>
+#include <akgl/character.h>
+#include <akgl/controller.h>
+#include <akgl/draw.h>
+#include <akgl/game.h>
+#include <akgl/heap.h>
+#include <akgl/physics.h>
+#include <akgl/registry.h>
+#include <akgl/renderer.h>
+#include <akgl/sprite.h>
+#include <akgl/text.h>
+#include <akgl/ui.h>
+
+#include "galaga.h"
+
+/** @brief Where the example's assets live. CMake defines it; `--assets` overrides. */
+#ifndef GALAGA_ASSET_DIR
+#define GALAGA_ASSET_DIR "."
+#endif
+
+/** @brief The enemy script. CMake defines it; `--script` overrides. */
+#ifndef GALAGA_SCRIPT_PATH
+#define GALAGA_SCRIPT_PATH "galaga.bas"
+#endif
+
+/** @brief The HUD font. CMake defines it; headless runs still need it for the UI. */
+#ifndef GALAGA_FONT_PATH
+#define GALAGA_FONT_PATH "font.ttf"
+#endif
+
+#define GALAGA_PATH_MAX 1024
+
+galaga_Game galaga_game;
+galaga_Shared galaga_shared;
+
+/** @brief Where `--screenshot` writes, and on which frame. NULL means never. */
+static char *SHOTPATH = NULL;
+static int SHOTFRAME = 0;
+
+/** @brief Set in HANDLE_DEFAULT and read after FINISH; see the note in main. */
+static int FAILED = 0;
+
+/* ------------------------------------------------------------- starfield --- */
+
+/*
+ * No parallax facility exists in libakgl and none is needed: a fixed array of
+ * stars advanced per frame and drawn with akgl_draw_point() between
+ * frame_start and akgl_game_update(). Two speed bands give the depth for
+ * free -- the slow band reads as far away.
+ */
+#define GALAGA_STARS 96
+
+static struct
+{
+    float x;
+    float y;
+    float speed;
+    Uint8 bright;
+} STARS[GALAGA_STARS];
+
+static void starfield_seed(void)
+{
+    int i = 0;
+
+    for ( i = 0; i < GALAGA_STARS; i++ ) {
+	STARS[i].x = galaga_random() * (float)GALAGA_VIEW_WIDTH;
+	STARS[i].y = galaga_random() * (float)GALAGA_VIEW_HEIGHT;
+	if ( (i % 2) == 0 ) {
+	    STARS[i].speed = 40.0f;		/* the far band  */
+	    STARS[i].bright = 110;
+	} else {
+	    STARS[i].speed = 110.0f;		/* the near band */
+	    STARS[i].bright = 220;
+	}
+    }
+}
+
+static akerr_ErrorContext *starfield_draw(void)
+{
+    SDL_Color color = { 255, 255, 255, 255 };
+    int i = 0;
+    PREPARE_ERROR(errctx);
+
+    for ( i = 0; i < GALAGA_STARS; i++ ) {
+	STARS[i].y += STARS[i].speed * galaga_game.dt;
+	if ( STARS[i].y > (float)GALAGA_VIEW_HEIGHT ) {
+	    STARS[i].y -= (float)GALAGA_VIEW_HEIGHT;
+	    STARS[i].x = galaga_random() * (float)GALAGA_VIEW_WIDTH;
+	}
+	color.r = STARS[i].bright;
+	color.g = STARS[i].bright;
+	color.b = STARS[i].bright;
+	PASS(errctx, akgl_draw_point(akgl_renderer, STARS[i].x, STARS[i].y, color));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------ screenshots --- */
+
+/**
+ * @brief Read the render target back and write it out as a PNG.
+ *
+ * Called after everything has drawn and before the frame is presented,
+ * because SDL_RenderPresent is where the target stops being readable. The
+ * figures in docs/20 and docs/21 are output from this program rather than
+ * pictures somebody took once, so they cannot show a game that no longer
+ * exists.
+ */
+static akerr_ErrorContext *save_screenshot(char *path)
+{
+    SDL_Surface *shot = NULL;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, path, AKERR_NULLPOINTER, "path");
+    shot = SDL_RenderReadPixels(akgl_renderer->sdl_renderer, NULL);
+    FAIL_ZERO_RETURN(errctx, shot, AKGL_ERR_SDL, "SDL_RenderReadPixels: %s", SDL_GetError());
+    ATTEMPT {
+	FAIL_ZERO_BREAK(errctx, IMG_SavePNG(shot, path), AKGL_ERR_SDL,
+			"IMG_SavePNG(%s): %s", path, SDL_GetError());
+    } CLEANUP {
+	SDL_DestroySurface(shot);
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    SDL_Log("Wrote %s", path);
+    SUCCEED_RETURN(errctx);
+}
+
+/* ---------------------------------------------------------------- assets --- */
+
+static char *SPRITE_FILES[] = {
+    "sprite_galaga_player.json",
+    "sprite_galaga_bee.json",
+    "sprite_galaga_butterfly.json",
+    "sprite_galaga_boss.json",
+    "sprite_galaga_boss_hurt.json",
+    "sprite_galaga_playershot.json",
+    "sprite_galaga_enemyshot.json",
+    "sprite_galaga_boom.json",
+    NULL
+};
+
+static char *CHARACTER_FILES[] = {
+    "character_galaga_player.json",
+    "character_galaga_bee.json",
+    "character_galaga_butterfly.json",
+    "character_galaga_boss.json",
+    "character_galaga_playershot.json",
+    "character_galaga_enemyshot.json",
+    "character_galaga_boom.json",
+    NULL
+};
+
+static akerr_ErrorContext *asset_path(char *dir, char *name, char *dest, size_t size)
+{
+    int count = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, dir, AKERR_NULLPOINTER, "dir");
+    FAIL_ZERO_RETURN(errctx, name, AKERR_NULLPOINTER, "name");
+    FAIL_ZERO_RETURN(errctx, dest, AKERR_NULLPOINTER, "dest");
+    PASS(errctx, aksl_snprintf(&count, dest, size, "%s/%s", dir, name));
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Sprites first, characters second. Not a preference: a character's
+ * JSON names its sprites by registry name, so a character loaded first fails
+ * on the first sprite it cannot find.
+ */
+static akerr_ErrorContext *load_assets(char *assetdir)
+{
+    char path[GALAGA_PATH_MAX];
+    int i = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, assetdir, AKERR_NULLPOINTER, "assetdir");
+    for ( i = 0; SPRITE_FILES[i] != NULL; i++ ) {
+	PASS(errctx, asset_path(assetdir, SPRITE_FILES[i], (char *)&path, sizeof(path)));
+	PASS(errctx, akgl_sprite_load_json((char *)&path));
+    }
+    for ( i = 0; CHARACTER_FILES[i] != NULL; i++ ) {
+	PASS(errctx, asset_path(assetdir, CHARACTER_FILES[i], (char *)&path, sizeof(path)));
+	PASS(errctx, akgl_character_load_json((char *)&path));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/* --------------------------------------------------------------- startup --- */
+
+/** @brief Replacement for akgl_game.lowfpsfunc, which logs a line per frame. */
+static void galaga_lowfps(void)
+{
+}
+
+static akerr_ErrorContext *startup(void)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, aksl_strncpy((char *)&akgl_game.name, sizeof(akgl_game.name),
+			      "akbasic galaga tutorial", sizeof(akgl_game.name) - 1));
+    PASS(errctx, aksl_strncpy((char *)&akgl_game.version, sizeof(akgl_game.version),
+			      "1.0.0", sizeof(akgl_game.version) - 1));
+    PASS(errctx, aksl_strncpy((char *)&akgl_game.uri, sizeof(akgl_game.uri),
+			      "net.aklabs.akbasic.galaga", sizeof(akgl_game.uri) - 1));
+
+    PASS(errctx, akgl_game_init());
+    akgl_game.lowfpsfunc = &galaga_lowfps;
+
+    /* Properties before the renderer: akgl_render_2d_init reads both, and an
+     * unset one defaults to the string "0" -- a zero-sized window. */
+    PASS(errctx, akgl_set_property("game.screenwidth", "1280"));
+    PASS(errctx, akgl_set_property("game.screenheight", "960"));
+    PASS(errctx, akgl_render_2d_init(akgl_renderer));
+
+    FAIL_ZERO_RETURN(
+	errctx,
+	SDL_SetRenderLogicalPresentation(
+	    akgl_renderer->sdl_renderer,
+	    GALAGA_VIEW_WIDTH,
+	    GALAGA_VIEW_HEIGHT,
+	    SDL_LOGICAL_PRESENTATION_INTEGER_SCALE),
+	AKGL_ERR_SDL,
+	"%s",
+	SDL_GetError()
+	);
+
+    /* The view is what the camera looks through, so it says the same thing. */
+    akgl_camera->x = 0.0f;
+    akgl_camera->y = 0.0f;
+    akgl_camera->w = (float)GALAGA_VIEW_WIDTH;
+    akgl_camera->h = (float)GALAGA_VIEW_HEIGHT;
+
+    /*
+     * akgl_game_init does NOT install a physics backend, whatever physics.h's
+     * file comment says (libakgl docs/14-physics.md). Null physics accepts
+     * every call and moves nothing: whatever writes x and y directly is the
+     * mover, and in this game that is BASIC writing through ACTOR@.
+     */
+    PASS(errctx, akgl_physics_init_null(akgl_physics));
+    SUCCEED_RETURN(errctx);
+}
+
+/* ---------------------------------------------------------------- the UI --- */
+
+static akgl_UiMenu TITLE_MENU = {
+    "titlemenu", { "START", "QUIT" }, 2, 0, false, NULL
+};
+static akgl_UiMenu AGAIN_MENU = {
+    "againmenu", { "PLAY AGAIN", "QUIT" }, 2, 0, false, NULL
+};
+
+/* Clay borrows label text until frame_end, so these cannot be locals. */
+static char HUD_SCORE[64];
+static char HUD_LIVES[64];
+
+/**
+ * @brief Draw a headline centred above the menu, in the banner font.
+ *
+ * Direct text rather than a ui label: the menu owns AKGL_UI_ANCHOR_CENTER,
+ * and a label anchored there disappears behind it -- there is no
+ * top-centre anchor to reach for. Drawn before the UI bracket, so the menu
+ * still paints over it if the two ever meet.
+ */
+static akerr_ErrorContext *draw_banner(char *text)
+{
+    SDL_Color ink = { 235, 235, 235, 255 };
+    TTF_Font *font = NULL;
+    int w = 0;
+    int h = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, text, AKERR_NULLPOINTER, "text");
+    font = SDL_GetPointerProperty(AKGL_REGISTRY_FONT, "banner", NULL);
+    FAIL_ZERO_RETURN(errctx, font, AKERR_KEY, "the banner font is not loaded");
+    PASS(errctx, akgl_text_measure(font, text, &w, &h));
+    PASS(errctx, akgl_text_rendertextat(font, text, ink, 0,
+					(GALAGA_VIEW_WIDTH - w) / 2, 280));
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *declare_title(void)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, akgl_ui_menu(&TITLE_MENU));
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *declare_play(void)
+{
+    int count = 0;
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, aksl_snprintf(&count, HUD_SCORE, sizeof(HUD_SCORE),
+			       "SCORE %06d", galaga_game.score));
+    PASS(errctx, aksl_snprintf(&count, HUD_LIVES, sizeof(HUD_LIVES),
+			       "LIVES %d   WAVE %d", galaga_game.lives, galaga_shared.wave));
+    PASS(errctx, akgl_ui_label("score", HUD_SCORE, AKGL_UI_ANCHOR_TOP_LEFT, NULL));
+    PASS(errctx, akgl_ui_label("lives", HUD_LIVES, AKGL_UI_ANCHOR_TOP_RIGHT, NULL));
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *declare_end(void)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, akgl_ui_menu(&AGAIN_MENU));
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------ transitions --- */
+
+static akerr_ErrorContext *start_game(void)
+{
+    PREPARE_ERROR(errctx);
+
+    galaga_game.score = 0;
+    galaga_game.lives = 3;
+    memset(galaga_game.kills, 0, sizeof(galaga_game.kills));
+    memset(galaga_game.shots, 0, sizeof(galaga_game.shots));
+    galaga_game.respawn_timer = 0.0f;
+    galaga_shared.wave = 1;
+
+    galaga_game.player->x = (float)GALAGA_VIEW_WIDTH / 2.0f - 50.0f;
+    PASS(errctx, galaga_wave_spawn());
+    galaga_game.screen = GALAGA_SCREEN_PLAY;
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief End-of-round bookkeeping: notice a cleared wave or a spent ship.
+ */
+static akerr_ErrorContext *check_transitions(bool *running)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, running, AKERR_NULLPOINTER, "running");
+    (void)running;
+    if ( galaga_game.screen != GALAGA_SCREEN_PLAY ) {
+	SUCCEED_RETURN(errctx);
+    }
+    if ( galaga_game.lives <= 0 ) {
+	PASS(errctx, galaga_wave_release());
+	galaga_game.screen = GALAGA_SCREEN_GAMEOVER;
+	SUCCEED_RETURN(errctx);
+    }
+    if ( galaga_enemies_alive() == 0 ) {
+	galaga_game.screen = GALAGA_SCREEN_VICTORY;
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Consume a menu activation. The menu never clears `activated`; the
+ * state machine that acts on it does.
+ */
+static akerr_ErrorContext *consume_menus(bool *running)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, running, AKERR_NULLPOINTER, "running");
+    if ( galaga_game.screen == GALAGA_SCREEN_TITLE && TITLE_MENU.activated ) {
+	TITLE_MENU.activated = false;
+	if ( TITLE_MENU.selected == 0 ) {
+	    PASS(errctx, start_game());
+	} else {
+	    *running = false;
+	}
+    }
+    if ( (galaga_game.screen == GALAGA_SCREEN_GAMEOVER
+	  || galaga_game.screen == GALAGA_SCREEN_VICTORY)
+	 && AGAIN_MENU.activated ) {
+	AGAIN_MENU.activated = false;
+	if ( AGAIN_MENU.selected == 0 ) {
+	    PASS(errctx, galaga_wave_release());
+	    PASS(errctx, start_game());
+	} else {
+	    *running = false;
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------- the frame --- */
+
+/**
+ * @brief Route one event: the UI gets first refusal, then the menus, then
+ * the controller. A consumed event goes no further.
+ */
+static akerr_ErrorContext *route_event(SDL_Event *event, bool *running)
+{
+    bool consumed = false;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, event, AKERR_NULLPOINTER, "event");
+    FAIL_ZERO_RETURN(errctx, running, AKERR_NULLPOINTER, "running");
+
+    if ( event->type == SDL_EVENT_QUIT ) {
+	*running = false;
+	SUCCEED_RETURN(errctx);
+    }
+    PASS(errctx, akgl_ui_handle_event((void *)&akgl_game.state, event, &consumed));
+    if ( consumed ) {
+	SUCCEED_RETURN(errctx);
+    }
+    if ( galaga_game.screen == GALAGA_SCREEN_TITLE ) {
+	PASS(errctx, akgl_ui_menu_handle_event(&TITLE_MENU, event, &consumed));
+    } else if ( galaga_game.screen == GALAGA_SCREEN_GAMEOVER
+		|| galaga_game.screen == GALAGA_SCREEN_VICTORY ) {
+	PASS(errctx, akgl_ui_menu_handle_event(&AGAIN_MENU, event, &consumed));
+    }
+    if ( consumed ) {
+	SUCCEED_RETURN(errctx);
+    }
+    /* Every event, unconditionally: one that no control map binds is not an
+     * error, it is a call that did nothing. */
+    PASS(errctx, akgl_controller_handle_event((void *)&akgl_game.state, event));
+    SUCCEED_RETURN(errctx);
+}
+
+/** @brief The previous frame's timestamp, for dt. Stamped once at loop start. */
+static uint64_t LAST_NS = 0;
+
+static akerr_ErrorContext *frame(bool *running)
+{
+    SDL_Event event;
+    uint64_t now = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, running, AKERR_NULLPOINTER, "running");
+
+    while ( SDL_PollEvent(&event) == true ) {
+	PASS(errctx, route_event(&event, running));
+    }
+
+    galaga_game.frame += 1;
+    if ( galaga_game.autoplay ) {
+	if ( galaga_game.screen == GALAGA_SCREEN_TITLE && galaga_game.frame >= 8 ) {
+	    PASS(errctx, start_game());
+	}
+	/*
+	 * On an end screen the pilot presses Return, which drives the real
+	 * menu path -- declare, handle, activate, restart -- so a headless
+	 * run that dies keeps exercising the game instead of idling.
+	 */
+	if ( galaga_game.screen == GALAGA_SCREEN_GAMEOVER
+	     || galaga_game.screen == GALAGA_SCREEN_VICTORY ) {
+	    if ( (galaga_game.frame % 30) == 0 ) {
+		SDL_Event press;
+		memset(&press, 0, sizeof(press));
+		press.type = SDL_EVENT_KEY_DOWN;
+		press.key.key = SDLK_RETURN;
+		PASS(errctx, route_event(&press, running));
+	    }
+	}
+	PASS(errctx, galaga_player_autoplay(galaga_game.frame));
+    }
+
+    /*
+     * dt from the wall clock, clamped: a debugger pause or a stalled runner
+     * must not become one frame of teleporting enemies. The clamp is a 30 Hz
+     * frame, the slowest game this is still worth playing at.
+     */
+    now = SDL_GetTicksNS();
+    galaga_game.dt = (float)(now - LAST_NS) / 1e9f;
+    LAST_NS = now;
+    if ( galaga_game.dt > (1.0f / 30.0f) ) {
+	galaga_game.dt = 1.0f / 30.0f;
+    }
+
+    /* The shared frame state, refreshed before any enemy thinks. The engine
+     * filling GAME@.RND% is the issue #16 route: no RND verb exists. */
+    galaga_shared.playerx = galaga_game.player->x + 50.0f;
+    galaga_shared.playery = galaga_game.player->y;
+    galaga_shared.rnd = galaga_random();
+
+    PASS(errctx, akgl_renderer->frame_start(akgl_renderer));
+    PASS(errctx, starfield_draw());
+
+    /*
+     * akgl_game_update is update-every-actor, step-the-physics, draw-the-
+     * world. Updating every actor is where the forty scripts run: each
+     * enemy's updatefunc is the hook in enemies.c, and that hook is a BASIC
+     * call. Held back on the menu screens so the world stands still there.
+     */
+    if ( galaga_game.screen == GALAGA_SCREEN_PLAY ) {
+	PASS(errctx, akgl_game_update(NULL));
+	PASS(errctx, check_transitions(running));
+    }
+
+    /* The banner is direct text, drawn before the UI bracket. */
+    if ( galaga_game.screen == GALAGA_SCREEN_TITLE ) {
+	PASS(errctx, draw_banner("GALAGA"));
+    } else if ( galaga_game.screen == GALAGA_SCREEN_GAMEOVER ) {
+	PASS(errctx, draw_banner("GAME OVER"));
+    } else if ( galaga_game.screen == GALAGA_SCREEN_VICTORY ) {
+	PASS(errctx, draw_banner("VICTORY"));
+    }
+
+    /* The UI bracket sits between akgl_game_update and frame_end, exactly as
+     * libakgl docs/22-ui.md draws it. */
+    PASS(errctx, akgl_ui_frame_begin());
+    switch ( galaga_game.screen ) {
+    case GALAGA_SCREEN_TITLE:
+	PASS(errctx, declare_title());
+	break;
+    case GALAGA_SCREEN_PLAY:
+	PASS(errctx, declare_play());
+	break;
+    case GALAGA_SCREEN_GAMEOVER:
+    case GALAGA_SCREEN_VICTORY:
+	PASS(errctx, declare_end());
+	break;
+    }
+    PASS(errctx, akgl_ui_frame_end(akgl_renderer));
+
+    PASS(errctx, consume_menus(running));
+
+    if ( (SHOTPATH != NULL) && (galaga_game.frame == SHOTFRAME) ) {
+	PASS(errctx, save_screenshot(SHOTPATH));
+    }
+    PASS(errctx, akgl_renderer->frame_end(akgl_renderer));
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *run(int frames)
+{
+    bool running = true;
+    PREPARE_ERROR(errctx);
+
+    LAST_NS = SDL_GetTicksNS();
+    while ( running == true ) {
+	PASS(errctx, frame(&running));
+	if ( (frames > 0) && (galaga_game.frame >= frames) ) {
+	    running = false;
+	}
+	/* A crude frame limiter. A game on a real display should ask SDL for
+	 * vsync; this one has to work under the dummy video driver, where
+	 * there is nothing to sync to. */
+	SDL_Delay(16);
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/* -------------------------------------------------------------- teardown --- */
+
+/**
+ * @brief Give back what the process is holding.
+ *
+ * There is no akgl_game_shutdown; teardown is the application's. Fonts have
+ * to unload before TTF_Quit destroys them underneath the registry. IGNORE()
+ * on every call: a teardown failure must not mask whatever error is already
+ * being reported.
+ */
+static void shutdown_game(void)
+{
+    int i = 0;
+
+    IGNORE(akgl_ui_shutdown());
+    IGNORE(akgl_text_unloadallfonts());
+    for ( i = 0; i < AKGL_MAX_HEAP_ACTOR; i++ ) {
+	if ( akgl_heap_actors[i].refcount > 0 ) {
+	    IGNORE(akgl_heap_release_actor(&akgl_heap_actors[i]));
+	}
+    }
+    TTF_Quit();
+    SDL_Quit();
+}
+
+/* ------------------------------------------------------------------ args --- */
+
+static akerr_ErrorContext *parse_args(int argc, char *argv[], char **assetdir,
+				      char **script, int *frames)
+{
+    int i = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, assetdir, AKERR_NULLPOINTER, "assetdir");
+    FAIL_ZERO_RETURN(errctx, script, AKERR_NULLPOINTER, "script");
+    FAIL_ZERO_RETURN(errctx, frames, AKERR_NULLPOINTER, "frames");
+
+    for ( i = 1; i < argc; i++ ) {
+	if ( strcmp(argv[i], "--autoplay") == 0 ) {
+	    galaga_game.autoplay = true;
+	} else if ( strcmp(argv[i], "--frames") == 0 ) {
+	    i += 1;
+	    FAIL_NONZERO_RETURN(errctx, (i >= argc), AKERR_VALUE, "--frames needs a count");
+	    PASS(errctx, aksl_atoi(argv[i], frames));
+	} else if ( strcmp(argv[i], "--assets") == 0 ) {
+	    i += 1;
+	    FAIL_NONZERO_RETURN(errctx, (i >= argc), AKERR_VALUE, "--assets needs a directory");
+	    *assetdir = argv[i];
+	} else if ( strcmp(argv[i], "--script") == 0 ) {
+	    i += 1;
+	    FAIL_NONZERO_RETURN(errctx, (i >= argc), AKERR_VALUE, "--script needs a path");
+	    *script = argv[i];
+	} else if ( strcmp(argv[i], "--screenshot") == 0 ) {
+	    i += 1;
+	    FAIL_NONZERO_RETURN(errctx, (i >= argc), AKERR_VALUE, "--screenshot needs a path");
+	    SHOTPATH = argv[i];
+	} else if ( strcmp(argv[i], "--screenshot-frame") == 0 ) {
+	    i += 1;
+	    FAIL_NONZERO_RETURN(errctx, (i >= argc), AKERR_VALUE,
+				"--screenshot-frame needs a number");
+	    PASS(errctx, aksl_atoi(argv[i], &SHOTFRAME));
+	} else {
+	    FAIL_RETURN(
+		errctx,
+		AKERR_VALUE,
+		"usage: galaga [--assets DIR] [--script PATH] [--frames N]"
+		" [--autoplay] [--screenshot PATH] [--screenshot-frame N]"
+		);
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+int main(int argc, char *argv[])
+{
+    char *assetdir = GALAGA_ASSET_DIR;
+    char *script = GALAGA_SCRIPT_PATH;
+    int frames = 0;
+    uint16_t fontid = 0;
+    PREPARE_ERROR(errctx);
+
+    ATTEMPT {
+	CATCH(errctx, parse_args(argc, argv, &assetdir, &script, &frames));
+	CATCH(errctx, startup());
+	CATCH(errctx, load_assets(assetdir));
+	/* The engine refuses to start when the script will not boot: a game
+	 * whose enemies cannot think is not a game missing a feature. */
+	CATCH(errctx, galaga_script_boot(script));
+	CATCH(errctx, akgl_ui_init(GALAGA_VIEW_WIDTH, GALAGA_VIEW_HEIGHT));
+	CATCH(errctx, akgl_text_loadfont("hud", GALAGA_FONT_PATH, 28));
+	CATCH(errctx, akgl_text_loadfont("banner", GALAGA_FONT_PATH, 84));
+	CATCH(errctx, akgl_ui_font_register("hud", &fontid));
+	CATCH(errctx, galaga_player_spawn());
+	CATCH(errctx, galaga_player_controls());
+	starfield_seed();
+	galaga_game.screen = GALAGA_SCREEN_TITLE;
+	galaga_game.lives = 3;
+	CATCH(errctx, run(frames));
+    } CLEANUP {
+	shutdown_game();
+    } PROCESS(errctx) {
+    } HANDLE_DEFAULT(errctx) {
+	LOG_ERROR_WITH_MESSAGE(errctx, "galaga could not run");
+	/* Set a flag rather than returning: leaving a HANDLE block early
+	 * skips FINISH's RELEASE_ERROR and leaks the context's pool slot. */
+	FAILED = 1;
+	/* FINISH_NORETURN rather than FINISH: FINISH expands a return that an
+	 * int-returning function cannot compile. */
+    } FINISH_NORETURN(errctx);
+
+    /*
+     * The readout is the evidence: exiting 0 is not proof the wave flew. A
+     * headless CI log gets the same line a reader's terminal does, and the
+     * script-error count is the line's whole reason to exist -- a wave of
+     * dumb enemies still exits 0.
+     */
+    SDL_Log(
+	"galaga: %d frames, screen %d, score %d, alive %d, kills bee %d bfly %d boss %d,"
+	" shots bee %d bfly %d boss %d, script errors %d",
+	galaga_game.frame,
+	(int)galaga_game.screen,
+	galaga_game.score,
+	galaga_enemies_alive(),
+	galaga_game.kills[GALAGA_ENEMY_BEE],
+	galaga_game.kills[GALAGA_ENEMY_BUTTERFLY],
+	galaga_game.kills[GALAGA_ENEMY_BOSS],
+	galaga_game.shots[GALAGA_ENEMY_BEE],
+	galaga_game.shots[GALAGA_ENEMY_BUTTERFLY],
+	galaga_game.shots[GALAGA_ENEMY_BOSS],
+	galaga_game.script_errors);
+    return FAILED;
+}

examples/galaga/player.c

@@ -0,0 +1,407 @@
+/**
+ * @file player.c
+ * @brief The player's ship, its shots, and every collision in the game.
+ *
+ * Bullets and collision are C forever -- they are engine, not behavior. The
+ * per-frame budget for the script is spent on the forty things that think;
+ * nothing here thinks, it just moves and intersects.
+ */
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <string.h>
+
+#include <SDL3/SDL.h>
+
+#include <akerror.h>
+#include <akstdlib.h>
+
+#include <akgl/actor.h>
+#include <akgl/controller.h>
+#include <akgl/game.h>
+#include <akgl/heap.h>
+#include <akgl/registry.h>
+#include <akgl/util.h>
+
+#include "galaga.h"
+
+/* Points per kill, indexed by enemy kind. */
+static const int KILL_SCORE[GALAGA_ENEMY_KINDS] = {
+    /* bee  butterfly  boss */
+       50,        80,   150
+};
+
+static uint32_t PSHOT_SERIAL = 0;
+
+/* -------------------------------------------------------------- hitboxes --- */
+
+/*
+ * Actor x/y is a sprite's top-left corner. Every box is inset from the
+ * artwork's rectangle, because the PNGs carry transparent margin and wing
+ * tips that should not kill anybody.
+ */
+static void player_box(akgl_Actor *actor, SDL_FRect *dest)
+{
+    dest->x = actor->x + 12.0f;
+    dest->y = actor->y + 8.0f;
+    dest->w = 75.0f;
+    dest->h = 60.0f;
+}
+
+static void enemy_box(akgl_Actor *actor, SDL_FRect *dest)
+{
+    dest->x = actor->x + 8.0f;
+    dest->y = actor->y + 8.0f;
+    dest->w = 78.0f;
+    dest->h = 68.0f;
+}
+
+static void shot_box(akgl_Actor *actor, SDL_FRect *dest)
+{
+    dest->x = actor->x;
+    dest->y = actor->y;
+    dest->w = 9.0f;
+    dest->h = 54.0f;
+}
+
+/* ---------------------------------------------------------- player shots --- */
+
+/**
+ * @brief Kill one enemy: score it, blow it up, free its slot.
+ */
+static akerr_ErrorContext *kill_enemy(int index)
+{
+    akgl_Actor *actor = NULL;
+    galaga_Enemy *enemy = NULL;
+    PREPARE_ERROR(errctx);
+
+    FAIL_NONZERO_RETURN(errctx, (index < 0 || index >= GALAGA_MAX_ENEMIES),
+			AKERR_OUTOFBOUNDS, "enemy index %d", index);
+    actor = galaga_enemy_actors[index];
+    FAIL_ZERO_RETURN(errctx, actor, AKERR_NULLPOINTER, "enemy %d is already gone", index);
+    enemy = &galaga_enemies[index];
+
+    galaga_game.score += KILL_SCORE[enemy->kind];
+    galaga_game.kills[enemy->kind] += 1;
+    PASS(errctx, galaga_boom_spawn(actor->x + 20.0f, actor->y + 20.0f));
+    PASS(errctx, akgl_heap_release_actor(actor));
+    galaga_enemy_actors[index] = NULL;
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Move a player shot and test it against every live enemy.
+ *
+ * The classic O(shots x enemies) sweep: at most 2 x 40 rectangle tests a
+ * frame, which is noise. A hit costs the enemy a point of hp; the boss's
+ * second point is the script's business to survive, not this file's.
+ */
+static akerr_ErrorContext *player_shot_update(akgl_Actor *obj)
+{
+    SDL_FRect mine;
+    SDL_FRect theirs;
+    bool hit = false;
+    int i = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj");
+    obj->y -= 900.0f * galaga_game.dt;
+    if ( obj->y < -60.0f ) {
+	galaga_game.player_shots_live -= 1;
+	PASS(errctx, akgl_heap_release_actor(obj));
+	SUCCEED_RETURN(errctx);
+    }
+
+    shot_box(obj, &mine);
+    for ( i = 0; i < GALAGA_MAX_ENEMIES; i++ ) {
+	if ( galaga_enemy_actors[i] == NULL ) {
+	    continue;
+	}
+	enemy_box(galaga_enemy_actors[i], &theirs);
+	PASS(errctx, akgl_collide_rectangles(&mine, &theirs, &hit));
+	if ( !hit ) {
+	    continue;
+	}
+	galaga_enemies[i].hp -= 1;
+	if ( galaga_enemies[i].hp <= 0 ) {
+	    PASS(errctx, kill_enemy(i));
+	}
+	galaga_game.player_shots_live -= 1;
+	PASS(errctx, akgl_heap_release_actor(obj));
+	SUCCEED_RETURN(errctx);
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *player_fire(akgl_Actor *player)
+{
+    akgl_Actor *shot = NULL;
+    char name[32];
+    int count = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, player, AKERR_NULLPOINTER, "player");
+
+    PSHOT_SERIAL += 1;
+    PASS(errctx, aksl_snprintf(&count, name, sizeof(name), "pshot%u", PSHOT_SERIAL));
+    PASS(errctx, akgl_heap_next_actor(&shot));
+    PASS(errctx, akgl_actor_initialize(shot, name));
+    PASS(errctx, akgl_actor_set_character(shot, "galaga_playershot"));
+    /* AFTER initialize: it resets all seven hooks. */
+    shot->updatefunc = &player_shot_update;
+    shot->movement_controls_face = false;
+    shot->state = AKGL_ACTOR_STATE_ALIVE;
+    shot->visible = true;
+    shot->x = player->x + 45.0f;
+    shot->y = player->y - 44.0f;
+
+    galaga_game.player_shots_live += 1;
+    galaga_game.fire_cooldown = 0.22f;
+    SUCCEED_RETURN(errctx);
+}
+
+/* ----------------------------------------------------------- player hit --- */
+
+static akerr_ErrorContext *player_hit(akgl_Actor *player)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, player, AKERR_NULLPOINTER, "player");
+    galaga_game.lives -= 1;
+    galaga_game.respawn_timer = 2.0f;
+    PASS(errctx, galaga_boom_spawn(player->x + 25.0f, player->y + 10.0f));
+    player->x = (float)GALAGA_VIEW_WIDTH / 2.0f - 50.0f;
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief The player's own update hook: motion, fire, and what can kill it.
+ */
+static akerr_ErrorContext *player_update(akgl_Actor *obj)
+{
+    SDL_FRect mine;
+    SDL_FRect theirs;
+    bool hit = false;
+    float dx = 0.0f;
+    int i = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj");
+
+    dx = 0.0f;
+    if ( galaga_game.moveleft ) {
+	dx -= GALAGA_PLAYER_SPEED;
+    }
+    if ( galaga_game.moveright ) {
+	dx += GALAGA_PLAYER_SPEED;
+    }
+    obj->x += dx * galaga_game.dt;
+    if ( obj->x < GALAGA_PLAYER_MARGIN ) {
+	obj->x = GALAGA_PLAYER_MARGIN;
+    }
+    if ( obj->x > (float)GALAGA_VIEW_WIDTH - GALAGA_PLAYER_MARGIN - 99.0f ) {
+	obj->x = (float)GALAGA_VIEW_WIDTH - GALAGA_PLAYER_MARGIN - 99.0f;
+    }
+
+    galaga_game.fire_cooldown -= galaga_game.dt;
+    if ( galaga_game.firing
+	 && galaga_game.fire_cooldown <= 0.0f
+	 && galaga_game.player_shots_live < GALAGA_MAX_PLAYER_SHOTS
+	 && galaga_game.screen == GALAGA_SCREEN_PLAY ) {
+	PASS(errctx, player_fire(obj));
+    }
+
+    /*
+     * Respawn grace: two seconds of blinking invulnerability. The blink is
+     * the `visible` flag, which is deliberate hiding -- the actor still
+     * updates, it just is not drawn on the off frames.
+     */
+    if ( galaga_game.respawn_timer > 0.0f ) {
+	galaga_game.respawn_timer -= galaga_game.dt;
+	obj->visible = ((galaga_game.frame / 6) % 2) == 0;
+	SUCCEED_RETURN(errctx);
+    }
+    obj->visible = true;
+
+    player_box(obj, &mine);
+
+    /* Enemy shots. */
+    for ( i = 0; i < AKGL_MAX_HEAP_ACTOR; i++ ) {
+	if ( akgl_heap_actors[i].refcount == 0 ) {
+	    continue;
+	}
+	if ( strncmp(akgl_heap_actors[i].name, "eshot", 5) != 0 ) {
+	    continue;
+	}
+	shot_box(&akgl_heap_actors[i], &theirs);
+	PASS(errctx, akgl_collide_rectangles(&mine, &theirs, &hit));
+	if ( hit ) {
+	    galaga_game.enemy_shots_live -= 1;
+	    PASS(errctx, akgl_heap_release_actor(&akgl_heap_actors[i]));
+	    PASS(errctx, player_hit(obj));
+	    SUCCEED_RETURN(errctx);
+	}
+    }
+
+    /* Diving enemies. The formation never reaches this low, so testing all
+     * forty is the same answer as testing the divers, without a state read. */
+    for ( i = 0; i < GALAGA_MAX_ENEMIES; i++ ) {
+	if ( galaga_enemy_actors[i] == NULL ) {
+	    continue;
+	}
+	enemy_box(galaga_enemy_actors[i], &theirs);
+	PASS(errctx, akgl_collide_rectangles(&mine, &theirs, &hit));
+	if ( hit ) {
+	    PASS(errctx, kill_enemy(i));
+	    PASS(errctx, player_hit(obj));
+	    SUCCEED_RETURN(errctx);
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/* -------------------------------------------------------------- controls --- */
+
+static akerr_ErrorContext *left_on(akgl_Actor *obj, SDL_Event *event)
+{
+    PREPARE_ERROR(errctx);
+    (void)obj; (void)event;
+    galaga_game.moveleft = true;
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *left_off(akgl_Actor *obj, SDL_Event *event)
+{
+    PREPARE_ERROR(errctx);
+    (void)obj; (void)event;
+    galaga_game.moveleft = false;
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *right_on(akgl_Actor *obj, SDL_Event *event)
+{
+    PREPARE_ERROR(errctx);
+    (void)obj; (void)event;
+    galaga_game.moveright = true;
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *right_off(akgl_Actor *obj, SDL_Event *event)
+{
+    PREPARE_ERROR(errctx);
+    (void)obj; (void)event;
+    galaga_game.moveright = false;
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *fire_on(akgl_Actor *obj, SDL_Event *event)
+{
+    PREPARE_ERROR(errctx);
+    (void)obj; (void)event;
+    galaga_game.firing = true;
+    SUCCEED_RETURN(errctx);
+}
+
+static akerr_ErrorContext *fire_off(akgl_Actor *obj, SDL_Event *event)
+{
+    PREPARE_ERROR(errctx);
+    (void)obj; (void)event;
+    galaga_game.firing = false;
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *galaga_player_controls(void)
+{
+    akgl_Control control;
+    PREPARE_ERROR(errctx);
+
+    memset(&control, 0, sizeof(control));
+    control.event_on = SDL_EVENT_KEY_DOWN;
+    control.event_off = SDL_EVENT_KEY_UP;
+
+    control.key = SDLK_LEFT;
+    control.handler_on = &left_on;
+    control.handler_off = &left_off;
+    PASS(errctx, akgl_controller_pushmap(0, &control));
+
+    control.key = SDLK_RIGHT;
+    control.handler_on = &right_on;
+    control.handler_off = &right_off;
+    PASS(errctx, akgl_controller_pushmap(0, &control));
+
+    control.key = SDLK_SPACE;
+    control.handler_on = &fire_on;
+    control.handler_off = &fire_off;
+    PASS(errctx, akgl_controller_pushmap(0, &control));
+
+    akgl_controlmaps[0].target = galaga_game.player;
+    SUCCEED_RETURN(errctx);
+}
+
+/* ----------------------------------------------------------------- spawn --- */
+
+akerr_ErrorContext *galaga_player_spawn(void)
+{
+    akgl_Actor *player = NULL;
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, akgl_heap_next_actor(&player));
+    PASS(errctx, akgl_actor_initialize(player, "player"));
+    PASS(errctx, akgl_actor_set_character(player, "galaga_player"));
+    /* AFTER initialize: it resets all seven hooks. */
+    player->updatefunc = &player_update;
+    player->movement_controls_face = false;
+    player->state = AKGL_ACTOR_STATE_ALIVE;
+    player->visible = true;
+    player->x = (float)GALAGA_VIEW_WIDTH / 2.0f - 50.0f;
+    player->y = GALAGA_PLAYER_Y;
+
+    galaga_game.player = player;
+    SUCCEED_RETURN(errctx);
+}
+
+/* -------------------------------------------------------------- autoplay --- */
+
+/**
+ * @brief Send one synthetic key event through the controller.
+ *
+ * Through akgl_controller_handle_event(), never the handlers directly: the
+ * point of autoplay is to exercise the same path a keyboard does.
+ */
+static akerr_ErrorContext *synth_key(SDL_Keycode key, bool down)
+{
+    SDL_Event event;
+    PREPARE_ERROR(errctx);
+
+    memset(&event, 0, sizeof(event));
+    event.type = (down ? SDL_EVENT_KEY_DOWN : SDL_EVENT_KEY_UP);
+    event.key.key = key;
+    PASS(errctx, akgl_controller_handle_event((void *)&akgl_game.state, &event));
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief The scripted pilot for headless runs: hold fire, sweep the floor.
+ */
+akerr_ErrorContext *galaga_player_autoplay(int frame)
+{
+    int phase = 0;
+    PREPARE_ERROR(errctx);
+
+    /* Hold fire until the wave has mostly assembled: shooting the entry
+     * stream point-blank empties the formation before it exists, which makes
+     * both the game and its figure worse. */
+    if ( frame == 300 ) {
+	PASS(errctx, synth_key(SDLK_SPACE, true));
+    }
+    phase = frame % 240;
+    if ( phase == 30 ) {
+	PASS(errctx, synth_key(SDLK_LEFT, true));
+    } else if ( phase == 90 ) {
+	PASS(errctx, synth_key(SDLK_LEFT, false));
+	PASS(errctx, synth_key(SDLK_RIGHT, true));
+    } else if ( phase == 210 ) {
+	PASS(errctx, synth_key(SDLK_RIGHT, false));
+    }
+    SUCCEED_RETURN(errctx);
+}

examples/galaga/script.c

@@ -0,0 +1,281 @@
+/**
+ * @file script.c
+ * @brief The boundary: everything that touches the interpreter lives here.
+ *
+ * One runtime, one script, three host types, three bindings. The engine calls
+ * exactly one thing per enemy per frame -- galaga_script_update_enemy() -- and
+ * that function is the whole protocol: rebind, call, recover, reset.
+ *
+ * The structure types are declared once, in C, right below. The script never
+ * declares a TYPE of its own; akbasic_host_register_type() makes these structs
+ * *be* the BASIC types, offsets taken from offsetof() so the two sides cannot
+ * drift (include/akbasic/host.h).
+ */
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <SDL3/SDL.h>
+
+#include <akerror.h>
+
+#include <akbasic/environment.h>
+#include <akbasic/error.h>
+#include <akbasic/host.h>
+#include <akbasic/runtime.h>
+#include <akbasic/sink.h>
+
+#include "galaga.h"
+
+/* The interpreter. Static because an akbasic_Runtime is far too big for a
+ * stack frame -- 2.40 MiB on this branch. */
+static akbasic_Runtime SCRIPT;
+static akbasic_TextSink SINK;
+static akbasic_StdioSink SINKSTATE;
+
+/** @brief Longest galaga.bas this loader will accept. */
+#define GALAGA_MAX_SCRIPT_BYTES 16384
+
+static char SOURCE[GALAGA_MAX_SCRIPT_BYTES];
+
+/*
+ * Enemy kind -> BASIC function name. Dispatch is a table, not a conditional:
+ * adding a kind is one row here and one DEF in galaga.bas.
+ */
+static const char *UPDATE_FUNCTION[GALAGA_ENEMY_KINDS] = {
+    "UPDATEBEE",	/* GALAGA_ENEMY_BEE       */
+    "UPDATEBFLY",	/* GALAGA_ENEMY_BUTTERFLY */
+    "UPDATEBOSS"	/* GALAGA_ENEMY_BOSS      */
+};
+
+/* ---------------------------------------------------------- host types --- */
+
+static const akbasic_HostField ENEMY_FIELDS[] = {
+    /*                  struct        member  BASIC name  C representation          */
+    AKBASIC_HOST_FIELD( galaga_Enemy, kind,   "KIND#",    AKBASIC_HOSTFIELD_INT32 ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, state,  "STATE#",   AKBASIC_HOSTFIELD_INT32 ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, homex,  "HOMEX%",   AKBASIC_HOSTFIELD_FLOAT ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, homey,  "HOMEY%",   AKBASIC_HOSTFIELD_FLOAT ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, t,      "T%",       AKBASIC_HOSTFIELD_FLOAT ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, hp,     "HP#",      AKBASIC_HOSTFIELD_INT32 ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, fire,   "FIRE#",    AKBASIC_HOSTFIELD_INT32 ),
+    AKBASIC_HOST_FIELD( galaga_Enemy, rnd,    "RND%",     AKBASIC_HOSTFIELD_FLOAT )
+};
+static const akbasic_HostType ENEMY_TYPE = {
+    "ENEMY", sizeof(galaga_Enemy), ENEMY_FIELDS, 8
+};
+
+/*
+ * The live actor itself. This is the demonstrative point of the whole
+ * example: the script writes the engine's *real* actor memory -- the same x
+ * the renderer reads -- with no copy in either direction.
+ */
+static const akbasic_HostField ACTOR_FIELDS[] = {
+    AKBASIC_HOST_FIELD( akgl_Actor, x,       "X%",       AKBASIC_HOSTFIELD_FLOAT ),
+    AKBASIC_HOST_FIELD( akgl_Actor, y,       "Y%",       AKBASIC_HOSTFIELD_FLOAT ),
+    AKBASIC_HOST_FIELD( akgl_Actor, state,   "STATE#",   AKBASIC_HOSTFIELD_INT32 ),
+    AKBASIC_HOST_FIELD( akgl_Actor, visible, "VISIBLE#", AKBASIC_HOSTFIELD_BOOL  )
+};
+static const akbasic_HostType ACTOR_TYPE = {
+    "ACTOR", sizeof(akgl_Actor), ACTOR_FIELDS, 4
+};
+
+static const akbasic_HostField GAME_FIELDS[] = {
+    AKBASIC_HOST_FIELD( galaga_Shared, playerx, "PLAYERX%", AKBASIC_HOSTFIELD_FLOAT ),
+    AKBASIC_HOST_FIELD( galaga_Shared, playery, "PLAYERY%", AKBASIC_HOSTFIELD_FLOAT ),
+    AKBASIC_HOST_FIELD( galaga_Shared, wave,    "WAVE#",    AKBASIC_HOSTFIELD_INT32 ),
+    AKBASIC_HOST_FIELD( galaga_Shared, rnd,     "RND%",     AKBASIC_HOSTFIELD_FLOAT )
+};
+static const akbasic_HostType GAME_TYPE = {
+    "GAME", sizeof(galaga_Shared), GAME_FIELDS, 4
+};
+
+/* Placeholders the boot bindings point at until the first real rebind. A
+ * binding is borrowed, never copied, so these must be static storage. */
+static galaga_Enemy SCRATCH_ENEMY;
+static akgl_Actor SCRATCH_ACTOR;
+
+/* ---------------------------------------------------------------- boot --- */
+
+static akerr_ErrorContext *read_script(char *path)
+{
+    FILE *fp = NULL;
+    size_t got = 0;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, path, AKERR_NULLPOINTER, "path");
+    fp = fopen(path, "rb");
+    FAIL_ZERO_RETURN(errctx, fp, AKERR_IO, "Cannot open the enemy script %s", path);
+    ATTEMPT {
+	got = fread(SOURCE, 1, sizeof(SOURCE) - 1, fp);
+	SOURCE[got] = '\0';
+	FAIL_NONZERO_BREAK(errctx, (got >= sizeof(SOURCE) - 1), AKERR_OUTOFBOUNDS,
+			   "%s does not fit in the %d byte script buffer",
+			   path, GALAGA_MAX_SCRIPT_BYTES);
+    } CLEANUP {
+	fclose(fp);
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief One dry call of every dispatch-table function, at boot.
+ *
+ * A missing or misspelled DEF fails here, at startup, with the function's name
+ * in the message -- not on frame one of the first wave. The scratch enemy's
+ * state word is zero, so no maneuver block runs and nothing moves.
+ */
+static akerr_ErrorContext *dry_run(void)
+{
+    akbasic_Value dt;
+    akbasic_Value *argp[1];
+    akbasic_Value *result = NULL;
+    int i = 0;
+    PREPARE_ERROR(errctx);
+
+    memset(&SCRATCH_ENEMY, 0, sizeof(SCRATCH_ENEMY));
+    memset(&dt, 0, sizeof(dt));
+    dt.valuetype = AKBASIC_TYPE_FLOAT;
+    dt.floatval = 0.0;
+    argp[0] = &dt;
+
+    for ( i = 0; i < GALAGA_ENEMY_KINDS; i++ ) {
+	PASS(errctx, akbasic_host_rebind(&SCRIPT, "SELF@", &SCRATCH_ENEMY));
+	PASS(errctx, akbasic_host_rebind(&SCRIPT, "ACTOR@", &SCRATCH_ACTOR));
+	PASS(errctx, akbasic_runtime_call_function(&SCRIPT, (char *)UPDATE_FUNCTION[i],
+						   argp, 1, &result));
+	/*
+	 * A body that died reports through the sink and answers zero; the
+	 * dropped mode is the only signal C gets. At boot that must be fatal
+	 * and must say which function -- not frame one of the first wave.
+	 */
+	FAIL_NONZERO_RETURN(errctx, (SCRIPT.mode != AKBASIC_MODE_RUN), AKERR_VALUE,
+			    "%s died during the boot dry run; the interpreter's report"
+			    " is above", UPDATE_FUNCTION[i]);
+	PASS(errctx, akbasic_environment_zero(SCRIPT.environment));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+akerr_ErrorContext *galaga_script_boot(char *path)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, path, AKERR_NULLPOINTER, "path");
+
+    PASS(errctx, akbasic_error_register());
+    PASS(errctx, akbasic_sink_init_stdio(&SINK, &SINKSTATE, stdout, NULL));
+    PASS(errctx, akbasic_runtime_init(&SCRIPT, &SINK));
+
+    PASS(errctx, akbasic_host_register_type(&SCRIPT, &ENEMY_TYPE));
+    PASS(errctx, akbasic_host_register_type(&SCRIPT, &ACTOR_TYPE));
+    PASS(errctx, akbasic_host_register_type(&SCRIPT, &GAME_TYPE));
+
+    PASS(errctx, akbasic_host_bind(&SCRIPT, "SELF@", "ENEMY", &SCRATCH_ENEMY));
+    PASS(errctx, akbasic_host_bind(&SCRIPT, "ACTOR@", "ACTOR", &SCRATCH_ACTOR));
+    PASS(errctx, akbasic_host_bind(&SCRIPT, "GAME@", "GAME", &galaga_shared));
+
+    PASS(errctx, read_script(path));
+    PASS(errctx, akbasic_runtime_load(&SCRIPT, SOURCE));
+
+    /*
+     * A "no top level code" script still has to run once: executing the DEF
+     * statements is what files the functions. The run is bounded because a
+     * script that is all definitions has no business taking more than a step
+     * per line, and an accidental loop at boot should be a diagnosis, not a
+     * hang.
+     */
+    PASS(errctx, akbasic_runtime_start(&SCRIPT, AKBASIC_MODE_RUN));
+    PASS(errctx, akbasic_runtime_run(&SCRIPT, 4 * AKBASIC_MAX_SOURCE_LINES));
+
+    /*
+     * The program has now ended and the runtime sits in QUIT mode, where a
+     * multi-line DEF called from the host returns a silent zero. Forcing the
+     * mode back makes the bodies run, and it stays put because nothing here
+     * ever steps the runtime again. Issue #8 tracks making this unnecessary.
+     */
+    PASS(errctx, akbasic_runtime_set_mode(&SCRIPT, AKBASIC_MODE_RUN));
+
+    PASS(errctx, dry_run());
+    SUCCEED_RETURN(errctx);
+}
+
+/* ------------------------------------------------------------ per frame --- */
+
+akerr_ErrorContext *galaga_script_update_enemy(galaga_Enemy *enemy, akgl_Actor *actor, float dt)
+{
+    akbasic_Value dtval;
+    akbasic_Value *argp[1];
+    akbasic_Value *result = NULL;
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, enemy, AKERR_NULLPOINTER, "enemy");
+    FAIL_ZERO_RETURN(errctx, actor, AKERR_NULLPOINTER, "actor");
+    FAIL_NONZERO_RETURN(errctx, (enemy->kind < 0 || enemy->kind >= GALAGA_ENEMY_KINDS),
+			AKERR_VALUE, "Enemy kind %d has no update function", enemy->kind);
+
+    PASS(errctx, akbasic_host_rebind(&SCRIPT, "SELF@", enemy));
+    PASS(errctx, akbasic_host_rebind(&SCRIPT, "ACTOR@", actor));
+
+    memset(&dtval, 0, sizeof(dtval));
+    dtval.valuetype = AKBASIC_TYPE_FLOAT;
+    dtval.floatval = (double)dt;
+    argp[0] = &dtval;
+
+    /*
+     * An error in an enemy's function is that script's problem, not the
+     * engine's: the enemy goes dumb -- cleared to a formation hold it will
+     * never leave -- and the frame lives. HANDLE_DEFAULT absorbs whatever the
+     * interpreter raised; the first failure is logged with the function's
+     * name, the rest are counted, because sixty a second of the same message
+     * is how a log stops being read.
+     */
+    ATTEMPT {
+	CATCH(errctx, akbasic_runtime_call_function(&SCRIPT, (char *)UPDATE_FUNCTION[enemy->kind],
+						    argp, 1, &result));
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } HANDLE_DEFAULT(errctx) {
+	if ( galaga_game.script_errors == 0 ) {
+	    LOG_ERROR_WITH_MESSAGE(errctx, "first script error; this enemy is now dumb");
+	}
+	galaga_game.script_errors += 1;
+	enemy->state = GALAGA_ES_FORMATION;
+	enemy->fire = 0;
+    } FINISH(errctx, true);
+
+    /*
+     * A BASIC-level error in the body is quieter than an interpreter error:
+     * it reports through the sink, the call answers a stale value, and the
+     * runtime falls out of RUN mode -- after which every later call is a
+     * silent no-op. The mode is the tell. Revival is two calls:
+     * clear_error(), because a run's first error latches and every line is
+     * skipped while it stands, and the same set_mode(RUN) the boot needed
+     * (issue #8's mechanics). The enemy is treated exactly like the
+     * interpreter-error case above.
+     */
+    if ( SCRIPT.mode != AKBASIC_MODE_RUN ) {
+	if ( galaga_game.script_errors == 0 ) {
+	    SDL_Log("first script error (reported by the interpreter above);"
+		    " enemy %s is now dumb", UPDATE_FUNCTION[enemy->kind]);
+	}
+	galaga_game.script_errors += 1;
+	enemy->state = GALAGA_ES_FORMATION;
+	enemy->fire = 0;
+	PASS(errctx, akbasic_runtime_clear_error(&SCRIPT));
+	PASS(errctx, akbasic_runtime_set_mode(&SCRIPT, AKBASIC_MODE_RUN));
+    }
+
+    /*
+     * Load-bearing: akbasic_runtime_call_function() parks every result in the
+     * caller environment's per-line value scratch, and a host calling in a
+     * loop never crosses the line boundary that would reset it. Without this
+     * the pool drains in under two frames of a 40-enemy wave.
+     */
+    PASS(errctx, akbasic_environment_zero(SCRIPT.environment));
+    SUCCEED_RETURN(errctx);
+}

include/akbasic/environment.h

@@ -156,18 +156,32 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_environment_new_leaf(akbasic_Environm
  */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_environment_wait_for_command(akbasic_Environment *obj, const char *command);
 /**
- * @brief True when this scope or any enclosing one is skipping forward.
+ * @brief Whether this scope or any enclosing one is skipping forward.
+ *
+ * The answer leaves through @p dest rather than the return value. Deciding it
+ * reads a recorded verb name, that read can fail, and a `bool` return has
+ * nowhere to report the failure -- so the signature changes rather than the
+ * error being swallowed. libakstdlib #38 is the ruling; `probe` in `symtab.c`
+ * and `loop_continues` in `runtime_structure.c` are the same shape.
+ *
  * @param obj Scope to inspect; NULL is not waiting.
- * @return `true` when execution is currently suppressed.
+ * @param[out] dest `true` when execution is currently suppressed. Required.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When dest is NULL.
  */
-bool akbasic_environment_is_waiting_for_any(akbasic_Environment *obj);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_environment_is_waiting_for_any(akbasic_Environment *obj, bool *dest);
 /**
- * @brief True when this scope or an enclosing one is waiting for a given verb.
+ * @brief Whether this scope or an enclosing one is waiting for a given verb.
+ *
+ * Reports through @p dest for the same reason its sibling above does.
+ *
  * @param obj Scope to inspect; NULL is not waiting.
- * @param command Verb to test for.
- * @return `true` when that verb is what execution is waiting on.
+ * @param command Verb to test for; NULL is not waiting.
+ * @param[out] dest `true` when that verb is what execution is waiting on. Required.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When dest is NULL.
  */
-bool akbasic_environment_is_waiting_for(akbasic_Environment *obj, const char *command);
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_environment_is_waiting_for(akbasic_Environment *obj, const char *command, bool *dest);
 /**
  * @brief Clear a pending wait, searching the parent chain for it.
  *

include/akbasic/runtime.h

@@ -211,8 +211,12 @@ typedef struct akbasic_Runtime
      * not exist relative to the working directory, which is what makes a `.bas`
      * beside its art work from anywhere. Group F's disk verbs will want the
      * same, which is why it is on the runtime rather than in the sprite state.
+     *
+     * Sized to AKBASIC_MAX_SOURCE_PATH_LENGTH, not AKBASIC_MAX_LINE_LENGTH: a
+     * directory is a filesystem path, not a line of BASIC, and the two do not
+     * belong to the same budget.
      */
-    char sourcepath[AKBASIC_MAX_LINE_LENGTH];
+    char sourcepath[AKBASIC_MAX_SOURCE_PATH_LENGTH];
 
     /*
      * The armed interrupts, and the environment the one currently running was
@@ -365,7 +369,7 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_set_ui(akbasic_Runtime *obj,
  * @param path Path to the program file, or NULL for none.
  * @return `NULL` on success, otherwise an error context owned by the caller.
  * @throws AKERR_NULLPOINTER When `obj` is NULL.
- * @throws AKBASIC_ERR_BOUNDS When the path is longer than AKBASIC_MAX_LINE_LENGTH.
+ * @throws AKBASIC_ERR_BOUNDS When the path is longer than AKBASIC_MAX_SOURCE_PATH_LENGTH.
  */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_set_source_path(akbasic_Runtime *obj, const char *path);
 
@@ -628,6 +632,27 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_println(akbasic_Runtime *obj,
  */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_set_mode(akbasic_Runtime *obj, int mode);
 
+/**
+ * @brief Forgive the last BASIC-level error, so a host may call again.
+ *
+ * A program run latches its first runtime error and ends -- deliberately, and
+ * a host cannot un-decide that with akbasic_runtime_set_mode() alone: the
+ * latch survives the mode change, every later line is skipped, and every
+ * later akbasic_runtime_call_function() answers a stale value after walking
+ * the whole source table doing nothing.
+ *
+ * A host that absorbed a script error -- reported through the sink, actor
+ * marked dumb, frame preserved -- calls this beside
+ * `akbasic_runtime_set_mode(obj, AKBASIC_MODE_RUN)` to put the runtime back
+ * in service. It is for hosts between calls, not for verbs during a run: a
+ * running program's first error still ends it, exactly once, with one line.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When `obj` is NULL.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_clear_error(akbasic_Runtime *obj);
+
 /**
  * @brief Evaluate one AST leaf, drawing scratch values from the environment.
  * @param obj Object to initialize, inspect, or modify.

include/akbasic/symtab.h

@@ -23,9 +23,17 @@
  * serves variables, functions and labels. Capacity is a member; the table is
  * kept below a 75% load factor by construction because `capacity` counts slots
  * and the caller's logical maximum is smaller.
+ *
+ * 172 rather than the old 256: no caller passes akbasic_symtab_init() anything
+ * larger than AKBASIC_MAX_VARIABLES (128), and 172 keeps that under the 75%
+ * load factor the comment above promises (128 / 0.75 = 170.7).
+ *
+ * AKBASIC_SYMTAB_MAX_KEY 24 rather than 64: the longest identifier across
+ * examples/breakout and examples/megademo -- variables, DIMmed arrays, labels
+ * and DEF FN names alike -- is 11 characters (TITLESCREEN, CLEARPOWERS).
  */
-#define AKBASIC_SYMTAB_MAX_SLOTS	256
-#define AKBASIC_SYMTAB_MAX_KEY		64
+#define AKBASIC_SYMTAB_MAX_SLOTS	172
+#define AKBASIC_SYMTAB_MAX_KEY		24
 
 typedef struct
 {

include/akbasic/types.h

@@ -6,6 +6,7 @@
 #ifndef _AKBASIC_TYPES_H_
 #define _AKBASIC_TYPES_H_
 
+#include <limits.h>
 #include <stdbool.h>
 #include <stdint.h>
 
@@ -27,15 +28,39 @@
 #define AKBASIC_MAX_VALUES		64
 #define AKBASIC_MAX_VARIABLES		128
 
-/* Whole-runtime pools */
-#define AKBASIC_MAX_SOURCE_LINES	9999
-#define AKBASIC_MAX_LINE_LENGTH		256
+/*
+ * Whole-runtime pools.
+ *
+ * AKBASIC_MAX_SOURCE_LINES, AKBASIC_MAX_LINE_LENGTH, AKBASIC_MAX_ARRAY_VALUES,
+ * AKBASIC_MAX_ENVIRONMENTS and AKBASIC_MAX_FUNCTIONS were cut from their
+ * original values against measurements taken off examples/breakout and
+ * examples/megademo, the two most demanding programs this interpreter runs --
+ * see the memory-footprint discussion this commit's PR body links. Each is
+ * sized at roughly 1.5-2x the peak the reference corpus actually reaches, not
+ * at the peak itself.
+ *
+ * AKBASIC_MAX_LINE_LENGTH in particular follows Commodore BASIC's own 80-column
+ * line limit rather than a measurement, which is why sink_stdio.c now refuses a
+ * line that fills the buffer with no terminator instead of silently truncating
+ * it: at 256 bytes that failure mode was theoretical, and at 80 it is not.
+ *
+ * AKBASIC_MAX_SOURCE_PATH_LENGTH is its own constant rather than a reuse of
+ * AKBASIC_MAX_LINE_LENGTH, which is where it used to come from. `sourcepath`
+ * (runtime.h) holds a directory, not a line of BASIC, and the two ideas do not
+ * scale together: shrinking the line limit to 80 broke every golden test in
+ * this checkout, because this repository's own working directory is deeper
+ * than that. PATH_MAX is the actual bound a filesystem path is subject to, so
+ * it is the one this borrows.
+ */
+#define AKBASIC_MAX_SOURCE_LINES	2048
+#define AKBASIC_MAX_LINE_LENGTH		80	/* Commodore BASIC's own line limit */
+#define AKBASIC_MAX_SOURCE_PATH_LENGTH	PATH_MAX
 #define AKBASIC_MAX_ARRAY_DEPTH		64	/* dimensions per array */
 #define AKBASIC_MAX_ARRAY_ELEMENTS	1024	/* elements in one array */
-#define AKBASIC_MAX_ARRAY_VALUES	4096	/* array elements across all variables */
+#define AKBASIC_MAX_ARRAY_VALUES	2048	/* array elements across all variables */
 #define AKBASIC_MAX_STRING_LENGTH	256	/* see TODO.md 1.2 */
-#define AKBASIC_MAX_ENVIRONMENTS	32	/* new: Go allocated these unbounded */
-#define AKBASIC_MAX_FUNCTIONS		64	/* new: Go used an unbounded map */
+#define AKBASIC_MAX_ENVIRONMENTS	12	/* new: Go allocated these unbounded */
+#define AKBASIC_MAX_FUNCTIONS		8	/* new: Go used an unbounded map */
 #define AKBASIC_MAX_LABELS		64	/* new: Go used an unbounded map */
 /*
  * Leaves a DO/LOOP condition may use. Its own small pool rather than a second

include/akbasic/variable.h

@@ -13,12 +13,22 @@
 
 #include <akerror.h>
 
+#include <akbasic/symtab.h>
 #include <akbasic/types.h>
 #include <akbasic/value.h>
 
 typedef struct
 {
-    char name[AKBASIC_MAX_STRING_LENGTH];
+    /*
+     * Sized to AKBASIC_SYMTAB_MAX_KEY, not AKBASIC_MAX_STRING_LENGTH: this name
+     * only ever gets here by surviving akbasic_symtab_set() first
+     * (akbasic_environment_create() calls it right after this field is
+     * populated), and that call refuses anything AKBASIC_SYMTAB_MAX_KEY
+     * characters or longer with AKBASIC_ERR_BOUNDS. A variable whose name did
+     * not fit could never exist, so the wider buffer was 232 bytes of headroom
+     * nothing could ever put a byte into.
+     */
+    char name[AKBASIC_SYMTAB_MAX_KEY];
     akbasic_Type valuetype;
     akbasic_Value *values;			/** The pool, or `inlinevalue` for a scalar */
     int valuecount;

src/data.c

@@ -8,7 +8,6 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
-#include <strings.h>
 
 #include <akerror.h>
 #include <akstdlib.h>
@@ -112,6 +111,7 @@ static akerr_ErrorContext *scan_line(akbasic_DataState *obj, const char *code, i
     const char *cursor = code;
     bool statementstart = true;
     bool instring = false;
+    int cmp = 0;
 
     while ( *cursor != '\0' ) {
 	if ( instring ) {
@@ -141,13 +141,15 @@ static akerr_ErrorContext *scan_line(akbasic_DataState *obj, const char *code, i
 	    }
 	    continue;
 	}
-	if ( statementstart && strncasecmp(cursor, "DATA", 4) == 0
-	     && !isalnum((unsigned char)cursor[4]) ) {
+	if ( statementstart ) {
+	    PASS(errctx, aksl_strncasecmp(cursor, "DATA", 4, &cmp));
+	    if ( cmp == 0 && !isalnum((unsigned char)cursor[4]) ) {
 		cursor += 4;
 		PASS(errctx, collect_items(obj, &cursor, lineno));
 		statementstart = false;
 		continue;
 	    }
+	}
 	statementstart = false;
 	cursor += 1;
     }
@@ -184,7 +186,7 @@ akerr_ErrorContext *akbasic_data_next(akbasic_Runtime *obj, akbasic_Type type, a
     PASS(errctx, akbasic_value_zero(dest));
     if ( type == AKBASIC_TYPE_STRING ) {
 	dest->valuetype = AKBASIC_TYPE_STRING;
-	snprintf(dest->stringval, sizeof(dest->stringval), "%s", item->text);
+	PASS(errctx, aksl_strcpy(dest->stringval, sizeof(dest->stringval), item->text));
 	SUCCEED_RETURN(errctx);
     }
 

src/environment.c

@@ -7,6 +7,7 @@
 #include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/environment.h>
 #include <akbasic/error.h>
@@ -39,7 +40,7 @@ akerr_ErrorContext *akbasic_environment_init(akbasic_Environment *obj, akbasic_R
     obj->readIdentifierIdx = 0;
     obj->waitingForCommand[0] = '\0';
     obj->errorToken = NULL;
-    memset(obj->readIdentifierLeaves, 0, sizeof(obj->readIdentifierLeaves));
+    PASS(errctx, aksl_memset(obj->readIdentifierLeaves, 0, sizeof(obj->readIdentifierLeaves)));
     obj->doLeafPool.next = 0;
     obj->doLeafPool.capacity = AKBASIC_MAX_CONDITION_LEAVES;
     obj->doLeafPool.leaves = obj->doLeafStorage;
@@ -123,6 +124,7 @@ akerr_ErrorContext *akbasic_environment_new_leaf(akbasic_Environment *obj, akbas
 akerr_ErrorContext *akbasic_environment_wait_for_command(akbasic_Environment *obj, const char *command)
 {
     PREPARE_ERROR(errctx);
+    size_t length = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL && command != NULL), AKERR_NULLPOINTER,
 		     "NULL argument in wait_for_command");
@@ -135,38 +137,56 @@ akerr_ErrorContext *akbasic_environment_wait_for_command(akbasic_Environment *ob
     FAIL_NONZERO_RETURN(errctx, (obj->waitingForCommand[0] != '\0'), AKBASIC_ERR_STATE,
 			"Can't wait on multiple commands in the same environment : %s",
 			obj->waitingForCommand);
-    FAIL_ZERO_RETURN(errctx, (strlen(command) < sizeof(obj->waitingForCommand)),
+    PASS(errctx, aksl_strlen(command, &length));
+    FAIL_ZERO_RETURN(errctx, (length < sizeof(obj->waitingForCommand)),
 		     AKBASIC_ERR_BOUNDS, "Command name '%s' is too long to wait on", command);
-    strncpy(obj->waitingForCommand, command, sizeof(obj->waitingForCommand) - 1);
-    obj->waitingForCommand[sizeof(obj->waitingForCommand) - 1] = '\0';
+    PASS(errctx, aksl_strcpy(obj->waitingForCommand, sizeof(obj->waitingForCommand), command));
     SUCCEED_RETURN(errctx);
 }
 
-bool akbasic_environment_is_waiting_for_any(akbasic_Environment *obj)
+akerr_ErrorContext *akbasic_environment_is_waiting_for_any(akbasic_Environment *obj, bool *dest)
 {
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (dest != NULL), AKERR_NULLPOINTER,
+		     "NULL destination in is_waiting_for_any");
+    *dest = false;
     if ( obj == NULL ) {
-	return false;
+	SUCCEED_RETURN(errctx);
     }
     if ( obj->waitingForCommand[0] != '\0' ) {
-	return true;
+	*dest = true;
+	SUCCEED_RETURN(errctx);
     }
-    return akbasic_environment_is_waiting_for_any(obj->parent);
+    /* The recursive tail becomes a PASS; dest carries the answer back up. */
+    PASS(errctx, akbasic_environment_is_waiting_for_any(obj->parent, dest));
+    SUCCEED_RETURN(errctx);
 }
 
-bool akbasic_environment_is_waiting_for(akbasic_Environment *obj, const char *command)
+akerr_ErrorContext *akbasic_environment_is_waiting_for(akbasic_Environment *obj, const char *command, bool *dest)
 {
+    PREPARE_ERROR(errctx);
+    int cmp = 0;
+
+    FAIL_ZERO_RETURN(errctx, (dest != NULL), AKERR_NULLPOINTER,
+		     "NULL destination in is_waiting_for");
+    *dest = false;
     if ( obj == NULL || command == NULL ) {
-	return false;
+	SUCCEED_RETURN(errctx);
     }
-    if ( strcmp(obj->waitingForCommand, command) == 0 ) {
-	return true;
+    PASS(errctx, aksl_strcmp(obj->waitingForCommand, command, &cmp));
+    if ( cmp == 0 ) {
+	*dest = true;
+	SUCCEED_RETURN(errctx);
     }
-    return akbasic_environment_is_waiting_for(obj->parent, command);
+    PASS(errctx, akbasic_environment_is_waiting_for(obj->parent, command, dest));
+    SUCCEED_RETURN(errctx);
 }
 
 akerr_ErrorContext *akbasic_environment_stop_waiting(akbasic_Environment *obj, const char *command)
 {
     PREPARE_ERROR(errctx);
+    int cmp = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL && command != NULL), AKERR_NULLPOINTER,
 		     "NULL argument in stop_waiting");
@@ -179,7 +199,8 @@ akerr_ErrorContext *akbasic_environment_stop_waiting(akbasic_Environment *obj, c
      * a miss is silently tolerated, exactly as today.
      */
     while ( obj != NULL ) {
-	if ( strcmp(obj->waitingForCommand, command) == 0 ) {
+	PASS(errctx, aksl_strcmp(obj->waitingForCommand, command, &cmp));
+	if ( cmp == 0 ) {
 	    obj->waitingForCommand[0] = '\0';
 	    SUCCEED_RETURN(errctx);
 	}
@@ -197,7 +218,7 @@ akerr_ErrorContext *akbasic_environment_get_function(akbasic_Environment *obj, c
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL && fname != NULL && dest != NULL), AKERR_NULLPOINTER,
 		     "NULL argument in get_function");
-    len = strlen(fname);
+    PASS(errctx, aksl_strlen(fname, &len));
     FAIL_ZERO_RETURN(errctx, (len < sizeof(upper)), AKERR_KEY, "Function '%s' is not defined", fname);
     for ( i = 0; i < len; i++ ) {
 	char c = fname[i];
@@ -291,6 +312,7 @@ akerr_ErrorContext *akbasic_environment_create(akbasic_Environment *obj, const c
     akbasic_Variable *variable = NULL;
     int64_t sizes[1] = { 1 };
     void *slot = NULL;
+    size_t namelen = 0;
     akerr_ErrorContext *found = NULL;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL && varname != NULL && dest != NULL), AKERR_NULLPOINTER,
@@ -312,10 +334,10 @@ akerr_ErrorContext *akbasic_environment_create(akbasic_Environment *obj, const c
     IGNORE(akerr_release_error(found));
 
     PASS(errctx, akbasic_runtime_new_variable(obj->runtime, &variable));
-    FAIL_ZERO_RETURN(errctx, (strlen(varname) < sizeof(variable->name)), AKBASIC_ERR_BOUNDS,
+    PASS(errctx, aksl_strlen(varname, &namelen));
+    FAIL_ZERO_RETURN(errctx, (namelen < sizeof(variable->name)), AKBASIC_ERR_BOUNDS,
 		     "Variable name '%s' is too long", varname);
-    strncpy(variable->name, varname, sizeof(variable->name) - 1);
-    variable->name[sizeof(variable->name) - 1] = '\0';
+    PASS(errctx, aksl_strcpy(variable->name, sizeof(variable->name), varname));
     variable->valuetype = AKBASIC_TYPE_UNDEFINED;
     variable->mutable_ = true;
     PASS(errctx, akbasic_variable_init(variable, &obj->runtime->valuepool, sizes, 1));

src/format.c

@@ -12,6 +12,7 @@
 #include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/error.h>
 #include <akbasic/format.h>
@@ -36,7 +37,7 @@ akerr_ErrorContext *akbasic_format_state_init(akbasic_FormatState *obj)
     PREPARE_ERROR(errctx);
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL format state in init");
-    memcpy(obj->chars, PUDEF_DEFAULTS, sizeof(obj->chars));
+    PASS(errctx, aksl_memcpy(obj->chars, PUDEF_DEFAULTS, sizeof(obj->chars)));
     SUCCEED_RETURN(errctx);
 }
 
@@ -161,11 +162,20 @@ static void measure_numeric(const char *field, size_t length, int *before, int *
     }
 }
 
-/** @brief Fill @p dest with @p width copies of `*`, the overflow marker. */
-static void overflow(char *dest, size_t width)
+/**
+ * @brief Fill @p dest with @p width copies of `*`, the overflow marker.
+ *
+ * Returns a context rather than `void` because the fill can fail and there was
+ * nowhere to say so. Both call sites are already inside `render_numeric`, which
+ * returns one. See libakstdlib #38.
+ */
+static akerr_ErrorContext *overflow(char *dest, size_t width)
 {
-    memset(dest, '*', width);
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, aksl_memset(dest, '*', width));
     dest[width] = '\0';
+    SUCCEED_RETURN(errctx);
 }
 
 /**
@@ -191,15 +201,21 @@ static akerr_ErrorContext *render_numeric(akbasic_FormatState *obj, const char *
     bool leadsign = false;
     bool trailsign = false;
     bool negative = (number < 0.0);
+    int written = 0;
 
     measure_numeric(field, length, &before, &after, &commas, &dollar, &leadsign, &trailsign);
     FAIL_ZERO_RETURN(errctx, (length + 1 <= len), AKBASIC_ERR_BOUNDS,
 		     "PRINT USING field of %zu characters does not fit", length);
 
-    snprintf(digits, sizeof(digits), "%.*f", after, (negative ? -number : number));
+    PASS(errctx, aksl_snprintf(&written, digits, sizeof(digits), "%.*f",
+			       after, (negative ? -number : number)));
 
-    point = strchr(digits, '.');
-    intlen = (point != NULL ? (size_t)(point - digits) : strlen(digits));
+    PASS(errctx, aksl_strchr(digits, '.', &point));
+    if ( point != NULL ) {
+	intlen = (size_t)(point - digits);
+    } else {
+	PASS(errctx, aksl_strlen(digits, &intlen));
+    }
 
     /* Group the integer part, if the field asked for separators. */
     used = 0;
@@ -213,7 +229,7 @@ static akerr_ErrorContext *render_numeric(akbasic_FormatState *obj, const char *
 	    used += 1;
 	}
     } else {
-	memcpy(grouped, digits, intlen);
+	PASS(errctx, aksl_memcpy(grouped, digits, intlen));
 	used = intlen;
     }
     grouped[used] = '\0';
@@ -226,7 +242,7 @@ static akerr_ErrorContext *render_numeric(akbasic_FormatState *obj, const char *
      * printing wider than asked, which would misalign every later column.
      */
     if ( (int)intlen > before ) {
-	overflow(dest, length);
+	PASS(errctx, overflow(dest, length));
 	SUCCEED_RETURN(errctx);
     }
 
@@ -252,13 +268,13 @@ static akerr_ErrorContext *render_numeric(akbasic_FormatState *obj, const char *
 	    used += 1;
 	}
     }
-    memcpy(dest + used, grouped, (size_t)group);
+    PASS(errctx, aksl_memcpy(dest + used, grouped, (size_t)group));
     used += (size_t)group;
 
     if ( after > 0 ) {
 	dest[used] = obj->chars[AKBASIC_PUDEF_POINT];
 	used += 1;
-	memcpy(dest + used, (point != NULL ? point + 1 : ""), (size_t)after);
+	PASS(errctx, aksl_memcpy(dest + used, (point != NULL ? point + 1 : ""), (size_t)after));
 	used += (size_t)after;
     }
     if ( trailsign ) {
@@ -271,7 +287,7 @@ static akerr_ErrorContext *render_numeric(akbasic_FormatState *obj, const char *
      * because a printed -5 that reads as 5 is worse than a row of stars.
      */
     if ( negative && !leadsign && !trailsign ) {
-	overflow(dest, length);
+	PASS(errctx, overflow(dest, length));
 	SUCCEED_RETURN(errctx);
     }
     dest[used] = '\0';
@@ -283,26 +299,27 @@ static akerr_ErrorContext *render_string(const char *field, size_t length, const
 					 char *dest, size_t len)
 {
     PREPARE_ERROR(errctx);
-    size_t textlen = strlen(text);
+    size_t textlen = 0;
     size_t pad = 0;
 
+    PASS(errctx, aksl_strlen(text, &textlen));
     FAIL_ZERO_RETURN(errctx, (length + 1 <= len), AKBASIC_ERR_BOUNDS,
 		     "PRINT USING field of %zu characters does not fit", length);
     if ( textlen > length ) {
 	/* Truncated, not starred: BASIC 7.0 cuts a string to its field. */
-	memcpy(dest, text, length);
+	PASS(errctx, aksl_memcpy(dest, text, length));
 	dest[length] = '\0';
 	SUCCEED_RETURN(errctx);
     }
 
-    memset(dest, ' ', length);
+    PASS(errctx, aksl_memset(dest, ' ', length));
     dest[length] = '\0';
     if ( field[0] == '=' ) {
 	pad = (length - textlen) / 2;
     } else {
 	pad = length - textlen;
     }
-    memcpy(dest + pad, text, textlen);
+    PASS(errctx, aksl_memcpy(dest + pad, text, textlen));
     SUCCEED_RETURN(errctx);
 }
 
@@ -313,6 +330,9 @@ akerr_ErrorContext *akbasic_format_using(akbasic_FormatState *obj, const char *f
     size_t start = 0;
     size_t length = 0;
     size_t used = 0;
+    size_t renderedlen = 0;
+    size_t formatlen = 0;
+    int written = 0;
     bool numeric = false;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL && format != NULL && value != NULL && dest != NULL),
@@ -343,12 +363,15 @@ akerr_ErrorContext *akbasic_format_using(akbasic_FormatState *obj, const char *f
     }
 
     /* Literal text before the field, the field, then literal text after it. */
-    used = strlen(rendered) + strlen(format) - length;
+    PASS(errctx, aksl_strlen(rendered, &renderedlen));
+    PASS(errctx, aksl_strlen(format, &formatlen));
+    used = renderedlen + formatlen - length;
     FAIL_ZERO_RETURN(errctx, (used + 1 <= len), AKBASIC_ERR_BOUNDS,
 		     "PRINT USING result of %zu characters does not fit", used);
-    memcpy(dest, format, start);
-    memcpy(dest + start, rendered, strlen(rendered));
-    snprintf(dest + start + strlen(rendered), len - start - strlen(rendered),
-	     "%s", format + start + length);
+    PASS(errctx, aksl_memcpy(dest, format, start));
+    PASS(errctx, aksl_memcpy(dest + start, rendered, renderedlen));
+    /* The check above already proved the tail fits, so this cannot truncate. */
+    PASS(errctx, aksl_snprintf(&written, dest + start + renderedlen,
+			       len - start - renderedlen, "%s", format + start + length));
     SUCCEED_RETURN(errctx);
 }

src/frontend_akgl.c

@@ -23,9 +23,9 @@
  */
 
 #include <stddef.h>
-#include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akgl/controller.h>
 #include <akgl/error.h>
@@ -55,7 +55,7 @@ akerr_ErrorContext *akbasic_frontend_akgl_init(akbasic_AkglFrontend *obj, const
     FAIL_ZERO_RETURN(errctx, (w > 0 && h > 0 && fontsize > 0), AKBASIC_ERR_VALUE,
 		     "A %dx%d window at %d points is not a window", w, h, fontsize);
 
-    memset(obj, 0, sizeof(*obj));
+    PASS(errctx, aksl_memset(obj, 0, sizeof(*obj)));
     obj->width = w;
     obj->height = h;
 

src/grammar.c

@@ -17,14 +17,19 @@
 static akerr_ErrorContext *copy_bounded(char *dest, const char *src, const char *what)
 {
     PREPARE_ERROR(errctx);
+    size_t srclen = 0;
 
     FAIL_ZERO_RETURN(errctx, (src != NULL), AKERR_NULLPOINTER, "NULL %s", what);
-    FAIL_ZERO_RETURN(errctx, (strlen(src) < AKBASIC_MAX_STRING_LENGTH),
+    PASS(errctx, aksl_strlen(src, &srclen));
+    FAIL_ZERO_RETURN(errctx, (srclen < AKBASIC_MAX_STRING_LENGTH),
 		     AKBASIC_ERR_VALUE,
 		     "%s of %zu characters exceeds the %d character limit",
-		     what, strlen(src), AKBASIC_MAX_STRING_LENGTH - 1);
-    strncpy(dest, src, AKBASIC_MAX_STRING_LENGTH - 1);
-    dest[AKBASIC_MAX_STRING_LENGTH - 1] = '\0';
+		     what, srclen, AKBASIC_MAX_STRING_LENGTH - 1);
+    /* aksl_strcpy always terminates and refuses rather than truncates, which is
+       the behaviour this site already wanted. The length check above stays
+       because it names the limit in the message. Every destination is one of the
+       leaf's AKBASIC_MAX_STRING_LENGTH buffers, which is what sizes the copy. */
+    PASS(errctx, aksl_strcpy(dest, AKBASIC_MAX_STRING_LENGTH, src));
     SUCCEED_RETURN(errctx);
 }
 
@@ -90,8 +95,8 @@ static akerr_ErrorContext *clone_into(akbasic_ASTLeaf *self, akbasic_LeafPool *p
     copy->parent = self->parent;
     copy->literal_int = self->literal_int;
     copy->literal_float = self->literal_float;
-    memcpy(copy->literal_string, self->literal_string, sizeof(copy->literal_string));
-    memcpy(copy->identifier, self->identifier, sizeof(copy->identifier));
+    PASS(errctx, aksl_memcpy(copy->literal_string, self->literal_string, sizeof(copy->literal_string)));
+    PASS(errctx, aksl_memcpy(copy->identifier, self->identifier, sizeof(copy->identifier)));
     copy->operator_ = self->operator_;
 
     PASS(errctx, clone_into(self->left, pool, &copy->left));
@@ -289,7 +294,9 @@ akerr_ErrorContext *akbasic_leaf_new_literal_int(akbasic_ASTLeaf *obj, const cha
 {
     PREPARE_ERROR(errctx);
     long long value = 0;
+    size_t lexlen = 0;
     int base = 10;
+    int cmp = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL leaf in new_literal_int");
     FAIL_ZERO_RETURN(errctx, (lexeme != NULL), AKERR_NULLPOINTER, "NULL lexeme in new_literal_int");
@@ -302,7 +309,9 @@ akerr_ErrorContext *akbasic_leaf_new_literal_int(akbasic_ASTLeaf *obj, const cha
      * Commodore BASIC has no octal literals, and a leading zero in a listing is
      * padding, not a radix.
      */
-    if ( strlen(lexeme) > 2 && strncmp(lexeme, "0x", 2) == 0 ) {
+    PASS(errctx, aksl_strlen(lexeme, &lexlen));
+    PASS(errctx, aksl_strncmp(lexeme, "0x", 2, &cmp));
+    if ( lexlen > 2 && cmp == 0 ) {
 	base = 16;
     }
     PASS(errctx, akbasic_leaf_init(obj, AKBASIC_LEAF_LITERAL_INT));
@@ -388,6 +397,7 @@ akerr_ErrorContext *akbasic_leaf_to_string(akbasic_ASTLeaf *self, char *dest, si
     PREPARE_ERROR(errctx);
     char sub1[AKBASIC_MAX_STRING_LENGTH];
     char sub2[AKBASIC_MAX_STRING_LENGTH];
+    int written = 0;
 
     FAIL_ZERO_RETURN(errctx, (self != NULL), AKERR_NULLPOINTER, "NULL leaf in to_string");
     FAIL_ZERO_RETURN(errctx, (dest != NULL), AKERR_NULLPOINTER, "NULL destination in to_string");
@@ -395,40 +405,42 @@ akerr_ErrorContext *akbasic_leaf_to_string(akbasic_ASTLeaf *self, char *dest, si
 
     switch ( self->leaftype ) {
     case AKBASIC_LEAF_LITERAL_INT:
-	snprintf(dest, len, "%" PRId64, self->literal_int);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "%" PRId64, self->literal_int));
 	break;
     case AKBASIC_LEAF_LITERAL_FLOAT:
-	snprintf(dest, len, "%f", self->literal_float);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "%f", self->literal_float));
 	break;
     case AKBASIC_LEAF_LITERAL_STRING:
-	snprintf(dest, len, "%s", self->literal_string);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "%s", self->literal_string));
 	break;
     case AKBASIC_LEAF_IDENTIFIER_INT:
     case AKBASIC_LEAF_IDENTIFIER_FLOAT:
     case AKBASIC_LEAF_IDENTIFIER_STRING:
     case AKBASIC_LEAF_IDENTIFIER:
-	snprintf(dest, len, "%s", self->identifier);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "%s", self->identifier));
 	break;
     case AKBASIC_LEAF_IDENTIFIER_STRUCT:
-	snprintf(dest, len, "%s", self->identifier);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "%s", self->identifier));
 	break;
     case AKBASIC_LEAF_FIELD:
 	PASS(errctx, akbasic_leaf_to_string(self->left, sub1, sizeof(sub1)));
-	snprintf(dest, len, "%s%s%s", sub1,
-		 (self->operator_ == AKBASIC_TOK_ARROW ? "->" : "."), self->identifier);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "%s%s%s", sub1,
+				   (self->operator_ == AKBASIC_TOK_ARROW ? "->" : "."), self->identifier));
 	break;
     case AKBASIC_LEAF_UNARY:
 	PASS(errctx, akbasic_leaf_to_string(self->left, sub1, sizeof(sub1)));
-	snprintf(dest, len, "(%s %s)", operator_to_str(self->operator_), sub1);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "(%s %s)",
+				   operator_to_str(self->operator_), sub1));
 	break;
     case AKBASIC_LEAF_BINARY:
 	PASS(errctx, akbasic_leaf_to_string(self->left, sub1, sizeof(sub1)));
 	PASS(errctx, akbasic_leaf_to_string(self->right, sub2, sizeof(sub2)));
-	snprintf(dest, len, "(%s %s %s)", operator_to_str(self->operator_), sub1, sub2);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "(%s %s %s)",
+				   operator_to_str(self->operator_), sub1, sub2));
 	break;
     case AKBASIC_LEAF_GROUPING:
 	PASS(errctx, akbasic_leaf_to_string(self->expr, sub1, sizeof(sub1)));
-	snprintf(dest, len, "(group %s)", sub1);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "(group %s)", sub1));
 	break;
     case AKBASIC_LEAF_COMMAND:
     case AKBASIC_LEAF_COMMAND_IMMEDIATE:
@@ -437,10 +449,10 @@ akerr_ErrorContext *akbasic_leaf_to_string(akbasic_ASTLeaf *self, char *dest, si
 	 * The reference falls through to Go's %+v struct dump here, which has no
 	 * useful C equivalent. Print something a test can assert on instead.
 	 */
-	snprintf(dest, len, "(%s)", self->identifier);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "(%s)", self->identifier));
 	break;
     default:
-	snprintf(dest, len, "(leaf %d)", (int)self->leaftype);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "(leaf %d)", (int)self->leaftype));
 	break;
     }
     SUCCEED_RETURN(errctx);

src/graphics_akgl.c

@@ -12,9 +12,8 @@
  * reaching for a global, which is exactly what goal 3 needs.
  */
 
-#include <string.h>
-
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akgl/draw.h>
 #include <akgl/error.h>
@@ -246,7 +245,7 @@ akerr_ErrorContext *akbasic_graphics_init_akgl(akbasic_GraphicsBackend *obj, akb
 		     "NULL renderer in graphics_init_akgl: the host creates it, not this");
     PASS(errctx, akgl_error_init());
 
-    memset(state, 0, sizeof(*state));
+    PASS(errctx, aksl_memset(state, 0, sizeof(*state)));
     state->renderer = renderer;
 
     obj->self		= state;

src/host.c

@@ -19,9 +19,9 @@
 
 #include <inttypes.h>
 #include <stdio.h>
-#include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/error.h>
 #include <akbasic/host.h>
@@ -89,8 +89,14 @@ akerr_ErrorContext *akbasic_host_read_field(akbasic_Runtime *obj, akbasic_Struct
 	 * left it full: a BASIC string is inline and fixed, so there is nothing
 	 * to alias and nothing that can outlive the read.
 	 */
+	/*
+	 * Raw snprintf: the host's bytes need not be terminated, and `%.*s`
+	 * bounded by hostwidth is what reads at most that many of them. A field
+	 * wider than the destination truncates, which is the documented contract
+	 * for reading a host string into a fixed BASIC one. libakstdlib #34.
+	 */
 	snprintf(text, sizeof(text), "%.*s", (int)field->hostwidth, at);
-	snprintf(dest->stringval, sizeof(dest->stringval), "%s", text);
+	PASS(errctx, aksl_strcpy(dest->stringval, sizeof(dest->stringval), text));
 	break;
     default:
 	FAIL_RETURN(errctx, AKBASIC_ERR_TYPE,
@@ -115,6 +121,7 @@ akerr_ErrorContext *akbasic_host_write_field(akbasic_Runtime *obj, akbasic_Struc
     char *at = (char *)hostbase + field->hostoffset;
     int64_t n = 0;
     double d = 0.0;
+    size_t len = 0;
 
     (void)obj;
     FAIL_ZERO_RETURN(errctx, (hostbase != NULL && src != NULL), AKERR_NULLPOINTER,
@@ -166,12 +173,13 @@ akerr_ErrorContext *akbasic_host_write_field(akbasic_Runtime *obj, akbasic_Struc
 	 * eight of them. BASIC strings have no width, so this is the one place
 	 * the two models genuinely disagree and the disagreement is reported.
 	 */
-	FAIL_ZERO_RETURN(errctx, (strlen(src->stringval) < field->hostwidth),
+	PASS(errctx, aksl_strlen(src->stringval, &len));
+	FAIL_ZERO_RETURN(errctx, (len < field->hostwidth),
 			 AKBASIC_ERR_VALUE,
 			 "A string of %zu characters does not fit in %s, which holds %zu",
-			 strlen(src->stringval), field->name, field->hostwidth - 1);
-	memset(at, 0, field->hostwidth);
-	memcpy(at, src->stringval, strlen(src->stringval));
+			 len, field->name, field->hostwidth - 1);
+	PASS(errctx, aksl_memset(at, 0, field->hostwidth));
+	PASS(errctx, aksl_memcpy(at, src->stringval, len));
 	break;
     default:
 	FAIL_RETURN(errctx, AKBASIC_ERR_TYPE,
@@ -226,7 +234,16 @@ akerr_ErrorContext *akbasic_host_register_type(akbasic_Runtime *obj, const akbas
 		     type->name, type->fieldcount, AKBASIC_MAX_STRUCT_FIELDS);
 
     dest = &obj->structtypes.types[obj->structtypes.count];
-    memset(dest, 0, sizeof(*dest));
+    PASS(errctx, aksl_memset(dest, 0, sizeof(*dest)));
+    /*
+     * Raw snprintf, and a latent defect rather than a settled decision: a host
+     * type name over 31 characters truncates silently here, and two that share a
+     * 31-character prefix then collide in akbasic_structtype_find. scan_names()
+     * in structtype.c already refuses the same case for a script-declared type
+     * with an explicit limit message, so the two paths disagree. Converting this
+     * to aksl_strcpy is the fix and it is a behaviour change on a public
+     * registration call, so it wants its own issue rather than this port.
+     */
     snprintf(dest->name, sizeof(dest->name), "%s", type->name);
     dest->used = true;
     dest->ishost = true;
@@ -241,7 +258,7 @@ akerr_ErrorContext *akbasic_host_register_type(akbasic_Runtime *obj, const akbas
 
 	FAIL_ZERO_RETURN(errctx, (src->name != NULL), AKERR_NULLPOINTER,
 			 "%s field %d has no name", type->name, i);
-	len = strlen(src->name);
+	PASS(errctx, aksl_strlen(src->name, &len));
 	/*
 	 * The suffix has to agree with the C type. A host that writes "HP%" over
 	 * an int32_t has said two different things about one field, and the
@@ -253,6 +270,7 @@ akerr_ErrorContext *akbasic_host_register_type(akbasic_Runtime *obj, const akbas
 			 "%s.%s must end in '%c' for the C type it describes",
 			 type->name, src->name, suffix_for(src->kind));
 
+	/* Same silent truncation as the type name above, and the same fix. */
 	snprintf(field->name, sizeof(field->name), "%s", src->name);
 	field->hostkind = src->kind;
 	field->hostoffset = src->offset;
@@ -296,7 +314,7 @@ akerr_ErrorContext *akbasic_host_bind(akbasic_Runtime *obj, const char *name,
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL && name != NULL && typename_ != NULL && instance != NULL),
 		     AKERR_NULLPOINTER, "NULL argument in host bind");
-    len = strlen(name);
+    PASS(errctx, aksl_strlen(name, &len));
     FAIL_ZERO_RETURN(errctx, (len >= 2 && name[len - 1] == '@'), AKBASIC_ERR_VALUE,
 		     "A structure variable's name ends in '@', so \"%s\" cannot be bound", name);
     PASS(errctx, akbasic_structtype_find(&obj->structtypes, typename_, &typeindex));

src/main.c

@@ -157,6 +157,7 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_akgl(FILE *program, const char *pa
     const char *fontpath = getenv("AKBASIC_FONT");
     FILE *input = program;
     int mode = AKBASIC_MODE_RUNSTREAM;
+    int fd = 0;
 
     if ( fontpath == NULL ) {
 	fontpath = AKBASIC_FONT_PATH;
@@ -169,7 +170,8 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_akgl(FILE *program, const char *pa
 	 * in an AKGL build, and the golden corpus can be driven through this
 	 * binary as well as through the stdio one.
 	 */
-	input = (isatty(fileno(stdin)) ? NULL : stdin);
+	PASS(errctx, aksl_fileno(stdin, &fd));
+	input = (isatty(fd) ? NULL : stdin);
 	mode = AKBASIC_MODE_REPL;
     }
 

src/parser.c

@@ -10,9 +10,9 @@
  */
 
 #include <inttypes.h>
-#include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/error.h>
 #include <akbasic/parser.h>
@@ -206,8 +206,7 @@ akerr_ErrorContext *akbasic_parser_command(akbasic_Parser *obj, akbasic_ASTLeaf
 
     PASS(errctx, akbasic_parser_previous(obj, &operator_));
     optype = operator_->tokentype;
-    strncpy(opname, operator_->lexeme, sizeof(opname) - 1);
-    opname[sizeof(opname) - 1] = '\0';
+    PASS(errctx, aksl_strcpy(opname, sizeof(opname), operator_->lexeme));
 
     /* Does this verb need its own parse path? */
     PASS(errctx, akbasic_verb_lookup(opname, &verb));
@@ -596,8 +595,7 @@ static akerr_ErrorContext *function_call(akbasic_Parser *obj, akbasic_ASTLeaf **
     }
 
     PASS(errctx, akbasic_parser_previous(obj, &operator_));
-    strncpy(fname, operator_->lexeme, sizeof(fname) - 1);
-    fname[sizeof(fname) - 1] = '\0';
+    PASS(errctx, aksl_strcpy(fname, sizeof(fname), operator_->lexeme));
 
     PASS(errctx, akbasic_verb_lookup(fname, &verb));
     if ( verb != NULL && verb->tokentype == AKBASIC_TOK_FUNCTION ) {

src/parser_commands.c

@@ -10,10 +10,9 @@
  */
 
 #include <inttypes.h>
-#include <string.h>
-#include <strings.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/error.h>
 #include <akbasic/parser.h>
@@ -78,10 +77,12 @@ akerr_ErrorContext *akbasic_parse_graphic(akbasic_Parser *parser, akbasic_ASTLea
     akbasic_ASTLeaf *arglist = NULL;
     akbasic_ASTLeaf *expr = NULL;
     akbasic_Token *peeked = NULL;
+    int cmp = 0;
 
     peeked = akbasic_parser_peek(parser);
-    if ( peeked != NULL && peeked->tokentype == AKBASIC_TOK_COMMAND &&
-	 strcmp(peeked->lexeme, "CLR") == 0 ) {
+    if ( peeked != NULL && peeked->tokentype == AKBASIC_TOK_COMMAND ) {
+	PASS(errctx, aksl_strcmp(peeked->lexeme, "CLR", &cmp));
+	if ( cmp == 0 ) {
 	    (void)akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND);
 	    PASS(errctx, akbasic_parser_new_leaf(parser, &arglist));
 	    arglist->leaftype = AKBASIC_LEAF_ARGUMENTLIST;
@@ -93,6 +94,7 @@ akerr_ErrorContext *akbasic_parse_graphic(akbasic_Parser *parser, akbasic_ASTLea
 	    *dest = expr;
 	    SUCCEED_RETURN(errctx);
 	}
+    }
     PASS(errctx, akbasic_parse_arglist(parser, dest));
     SUCCEED_RETURN(errctx);
 }
@@ -105,6 +107,7 @@ akerr_ErrorContext *akbasic_parse_draw(akbasic_Parser *parser, akbasic_ASTLeaf *
     akbasic_ASTLeaf *tail = NULL;
     akbasic_Token *peeked = NULL;
     akbasic_Token *operator_ = NULL;
+    int cmp = 0;
 
     /*
      * DRAW source, x1,y1 TO x2,y2 TO x3,y3 -- a polyline, with TO between pairs
@@ -125,9 +128,11 @@ akerr_ErrorContext *akbasic_parse_draw(akbasic_Parser *parser, akbasic_ASTLeaf *
 
     for ( ;; ) {
 	peeked = akbasic_parser_peek(parser);
-	if ( peeked == NULL ||
-	     peeked->tokentype != AKBASIC_TOK_COMMAND ||
-	     strcmp(peeked->lexeme, "TO") != 0 ) {
+	if ( peeked == NULL || peeked->tokentype != AKBASIC_TOK_COMMAND ) {
+	    break;
+	}
+	PASS(errctx, aksl_strcmp(peeked->lexeme, "TO", &cmp));
+	if ( cmp != 0 ) {
 	    break;
 	}
 	FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND),
@@ -259,6 +264,7 @@ static akerr_ErrorContext *parse_loop_condition(akbasic_Parser *parser, akbasic_
 {
     PREPARE_ERROR(errctx);
     akbasic_Token *peeked = NULL;
+    int cmp = 0;
 
     *condition = NULL;
     *kind = AKBASIC_LOOPCOND_NONE;
@@ -267,13 +273,16 @@ static akerr_ErrorContext *parse_loop_condition(akbasic_Parser *parser, akbasic_
     if ( peeked == NULL || peeked->tokentype != AKBASIC_TOK_COMMAND ) {
 	SUCCEED_RETURN(errctx);
     }
-    if ( strcmp(peeked->lexeme, "WHILE") == 0 ) {
+    PASS(errctx, aksl_strcmp(peeked->lexeme, "WHILE", &cmp));
+    if ( cmp == 0 ) {
 	*kind = AKBASIC_LOOPCOND_WHILE;
-    } else if ( strcmp(peeked->lexeme, "UNTIL") == 0 ) {
-	*kind = AKBASIC_LOOPCOND_UNTIL;
     } else {
+	PASS(errctx, aksl_strcmp(peeked->lexeme, "UNTIL", &cmp));
+	if ( cmp != 0 ) {
 	    SUCCEED_RETURN(errctx);
 	}
+	*kind = AKBASIC_LOOPCOND_UNTIL;
+    }
     (void)akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND);
 
     /* A loop condition is a condition, so a lone `=` in it is an equality test. */
@@ -372,6 +381,7 @@ akerr_ErrorContext *akbasic_parse_on(akbasic_Parser *parser, akbasic_ASTLeaf **d
     akbasic_ASTLeaf *expr = NULL;
     akbasic_ASTLeaf *tail = NULL;
     akbasic_Token *operator_ = NULL;
+    int cmp = 0;
     bool gosub = false;
 
     PASS(errctx, akbasic_parser_new_leaf(parser, &arglist));
@@ -389,10 +399,12 @@ akerr_ErrorContext *akbasic_parse_on(akbasic_Parser *parser, akbasic_ASTLeaf **d
     FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND),
 		     AKBASIC_ERR_SYNTAX, "Expected GOTO or GOSUB after ON (expression)");
     PASS(errctx, akbasic_parser_previous(parser, &operator_));
-    if ( strcmp(operator_->lexeme, "GOSUB") == 0 ) {
+    PASS(errctx, aksl_strcmp(operator_->lexeme, "GOSUB", &cmp));
+    if ( cmp == 0 ) {
 	gosub = true;
     } else {
-	FAIL_NONZERO_RETURN(errctx, strcmp(operator_->lexeme, "GOTO"), AKBASIC_ERR_SYNTAX,
+	PASS(errctx, aksl_strcmp(operator_->lexeme, "GOTO", &cmp));
+	FAIL_NONZERO_RETURN(errctx, cmp, AKBASIC_ERR_SYNTAX,
 			    "Expected GOTO or GOSUB after ON (expression)");
     }
     marker->literal_int = (gosub ? 1 : 0);
@@ -429,14 +441,20 @@ akerr_ErrorContext *akbasic_parse_resume(akbasic_Parser *parser, akbasic_ASTLeaf
     akbasic_ASTLeaf *expr = NULL;
     akbasic_ASTLeaf *target = NULL;
     akbasic_Token *peeked = NULL;
+    int cmp = 0;
 
     peeked = akbasic_parser_peek(parser);
-    if ( peeked != NULL && peeked->tokentype == AKBASIC_TOK_COMMAND &&
-	 strcmp(peeked->lexeme, "NEXT") == 0 ) {
+    if ( peeked != NULL && peeked->tokentype == AKBASIC_TOK_COMMAND ) {
+	PASS(errctx, aksl_strcmp(peeked->lexeme, "NEXT", &cmp));
+	if ( cmp == 0 ) {
 	    (void)akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND);
 	    PASS(errctx, akbasic_parser_new_leaf(parser, &target));
 	    PASS(errctx, akbasic_leaf_new_command(target, "NEXT", NULL));
-    } else if ( peeked != NULL && peeked->tokentype != AKBASIC_TOK_COLON ) {
+	}
+    }
+    /* The other two forms, taken only when the word was not NEXT -- which is
+       what a target already built says. */
+    if ( target == NULL && peeked != NULL && peeked->tokentype != AKBASIC_TOK_COLON ) {
 	PASS(errctx, akbasic_parser_expression(parser, &target));
     }
 
@@ -464,6 +482,8 @@ akerr_ErrorContext *akbasic_parse_print(akbasic_Parser *parser, akbasic_ASTLeaf
     akbasic_ASTLeaf *arglist = NULL;
     akbasic_ASTLeaf *right = NULL;
     akbasic_Token *peeked = NULL;
+    int cmp = 0;
+    bool matched = false;
 
     peeked = akbasic_parser_peek(parser);
 
@@ -499,8 +519,11 @@ akerr_ErrorContext *akbasic_parse_print(akbasic_Parser *parser, akbasic_ASTLeaf
 	SUCCEED_RETURN(errctx);
     }
 
-    if ( peeked == NULL || peeked->tokentype != AKBASIC_TOK_COMMAND ||
-	 strcmp(peeked->lexeme, "USING") != 0 ) {
+    if ( peeked != NULL && peeked->tokentype == AKBASIC_TOK_COMMAND ) {
+	PASS(errctx, aksl_strcmp(peeked->lexeme, "USING", &cmp));
+	matched = (cmp == 0);
+    }
+    if ( !matched ) {
 	/* The ordinary PRINT: one expression, or none at all. */
 	if ( peeked != NULL && peeked->tokentype != AKBASIC_TOK_COLON ) {
 	    PASS(errctx, akbasic_parser_expression(parser, &right));
@@ -627,12 +650,14 @@ akerr_ErrorContext *akbasic_parse_point(akbasic_Parser *parser, akbasic_ASTLeaf
     akbasic_ASTLeaf *arglist = NULL;
     akbasic_ASTLeaf *command = NULL;
     akbasic_Token *word = NULL;
+    int cmp = 0;
 
     PASS(errctx, akbasic_parser_expression(parser, &pointer));
     FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_IDENTIFIER),
 		     AKBASIC_ERR_SYNTAX, "Expected POINT <pointer> AT <structure>");
     PASS(errctx, akbasic_parser_previous(parser, &word));
-    FAIL_ZERO_RETURN(errctx, (strcasecmp(word->lexeme, "AT") == 0), AKBASIC_ERR_SYNTAX,
+    PASS(errctx, aksl_strcasecmp(word->lexeme, "AT", &cmp));
+    FAIL_ZERO_RETURN(errctx, (cmp == 0), AKBASIC_ERR_SYNTAX,
 		     "Expected AT after POINT <pointer>, not %s", word->lexeme);
     PASS(errctx, akbasic_parser_expression(parser, &target));
 
@@ -668,6 +693,7 @@ akerr_ErrorContext *akbasic_parse_dim(akbasic_Parser *parser, akbasic_ASTLeaf **
     PREPARE_ERROR(errctx);
     akbasic_ASTLeaf *command = NULL;
     akbasic_Token *word = NULL;
+    int cmp = 0;
 
     PASS(errctx, parse_verb_with_identifier(parser, "DIM", dest));
     command = *dest;
@@ -676,13 +702,15 @@ akerr_ErrorContext *akbasic_parse_dim(akbasic_Parser *parser, akbasic_ASTLeaf **
 	SUCCEED_RETURN(errctx);
     }
     PASS(errctx, akbasic_parser_previous(parser, &word));
-    FAIL_ZERO_RETURN(errctx, (strcasecmp(word->lexeme, "AS") == 0), AKBASIC_ERR_SYNTAX,
+    PASS(errctx, aksl_strcasecmp(word->lexeme, "AS", &cmp));
+    FAIL_ZERO_RETURN(errctx, (cmp == 0), AKBASIC_ERR_SYNTAX,
 		     "Expected AS after DIM %s, not %s", command->right->identifier, word->lexeme);
 
     FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_IDENTIFIER),
 		     AKBASIC_ERR_SYNTAX, "Expected a type name after AS");
     PASS(errctx, akbasic_parser_previous(parser, &word));
-    if ( strcasecmp(word->lexeme, "PTR") == 0 ) {
+    PASS(errctx, aksl_strcasecmp(word->lexeme, "PTR", &cmp));
+    if ( cmp == 0 ) {
 	command->literal_int = 1;
 	/*
 	 * `TO` is already a verb -- FOR ... TO owns it -- so it arrives as a
@@ -694,13 +722,14 @@ akerr_ErrorContext *akbasic_parse_dim(akbasic_Parser *parser, akbasic_ASTLeaf **
 	FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND),
 			 AKBASIC_ERR_SYNTAX, "Expected TO after PTR");
 	PASS(errctx, akbasic_parser_previous(parser, &word));
-	FAIL_ZERO_RETURN(errctx, (strcasecmp(word->lexeme, "TO") == 0), AKBASIC_ERR_SYNTAX,
+	PASS(errctx, aksl_strcasecmp(word->lexeme, "TO", &cmp));
+	FAIL_ZERO_RETURN(errctx, (cmp == 0), AKBASIC_ERR_SYNTAX,
 			 "Expected PTR TO TYPENAME, not PTR %s", word->lexeme);
 	FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_IDENTIFIER),
 			 AKBASIC_ERR_SYNTAX, "Expected a type name after PTR TO");
 	PASS(errctx, akbasic_parser_previous(parser, &word));
     }
-    snprintf(command->literal_string, sizeof(command->literal_string), "%s", word->lexeme);
+    PASS(errctx, aksl_strcpy(command->literal_string, sizeof(command->literal_string), word->lexeme));
     SUCCEED_RETURN(errctx);
 }
 
@@ -738,6 +767,7 @@ static akerr_ErrorContext *parse_def_parameters(akbasic_Parser *parser, akbasic_
     akbasic_ASTLeaf *param = NULL;
     akbasic_ASTLeaf *tail = NULL;
     akbasic_Token *word = NULL;
+    int cmp = 0;
 
     FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_LEFT_PAREN),
 		     AKBASIC_ERR_SYNTAX, "Expected an argument list after DEF <name>");
@@ -762,25 +792,28 @@ static akerr_ErrorContext *parse_def_parameters(akbasic_Parser *parser, akbasic_
 			     "%s must name its type: %s AS TYPENAME, or %s AS PTR TO TYPENAME",
 			     param->identifier, param->identifier, param->identifier);
 	    PASS(errctx, akbasic_parser_previous(parser, &word));
-	    FAIL_ZERO_RETURN(errctx, (strcasecmp(word->lexeme, "AS") == 0), AKBASIC_ERR_SYNTAX,
+	    PASS(errctx, aksl_strcasecmp(word->lexeme, "AS", &cmp));
+	    FAIL_ZERO_RETURN(errctx, (cmp == 0), AKBASIC_ERR_SYNTAX,
 			     "Expected AS after %s, not %s", param->identifier, word->lexeme);
 	    FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_IDENTIFIER),
 			     AKBASIC_ERR_SYNTAX, "Expected a type name after AS");
 	    PASS(errctx, akbasic_parser_previous(parser, &word));
-	    if ( strcasecmp(word->lexeme, "PTR") == 0 ) {
+	    PASS(errctx, aksl_strcasecmp(word->lexeme, "PTR", &cmp));
+	    if ( cmp == 0 ) {
 		param->literal_int = 1;
 		/* `TO` is already a verb -- FOR ... TO owns it -- so it arrives
 		   as a command token rather than an identifier. */
 		FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND),
 				 AKBASIC_ERR_SYNTAX, "Expected TO after PTR");
 		PASS(errctx, akbasic_parser_previous(parser, &word));
-		FAIL_ZERO_RETURN(errctx, (strcasecmp(word->lexeme, "TO") == 0), AKBASIC_ERR_SYNTAX,
+		PASS(errctx, aksl_strcasecmp(word->lexeme, "TO", &cmp));
+		FAIL_ZERO_RETURN(errctx, (cmp == 0), AKBASIC_ERR_SYNTAX,
 				 "Expected PTR TO TYPENAME, not PTR %s", word->lexeme);
 		FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_IDENTIFIER),
 				 AKBASIC_ERR_SYNTAX, "Expected a type name after PTR TO");
 		PASS(errctx, akbasic_parser_previous(parser, &word));
 	    }
-	    snprintf(param->literal_string, sizeof(param->literal_string), "%s", word->lexeme);
+	    PASS(errctx, aksl_strcpy(param->literal_string, sizeof(param->literal_string), word->lexeme));
 	}
 
 	if ( tail == NULL ) {
@@ -806,6 +839,7 @@ akerr_ErrorContext *akbasic_parse_def(akbasic_Parser *parser, akbasic_ASTLeaf **
     akbasic_ASTLeaf *expression = NULL;
     akbasic_ASTLeaf *command = NULL;
     akbasic_FunctionDef *fndef = NULL;
+    size_t namelen = 0;
     size_t i = 0;
 
     PASS(errctx, akbasic_parser_primary(parser, &identifier));
@@ -817,13 +851,14 @@ akerr_ErrorContext *akbasic_parse_def(akbasic_Parser *parser, akbasic_ASTLeaf **
     PASS(errctx, akbasic_runtime_new_function(runtime, &fndef));
 
     /* Uppercase the name: verbs and function names are case-insensitive. */
-    FAIL_ZERO_RETURN(errctx, (strlen(identifier->identifier) < sizeof(fndef->name)),
+    PASS(errctx, aksl_strlen(identifier->identifier, &namelen));
+    FAIL_ZERO_RETURN(errctx, (namelen < sizeof(fndef->name)),
 		     AKBASIC_ERR_BOUNDS, "Function name '%s' is too long", identifier->identifier);
-    for ( i = 0; i < strlen(identifier->identifier); i++ ) {
+    for ( i = 0; i < namelen; i++ ) {
 	char c = identifier->identifier[i];
 	fndef->name[i] = (char)((c >= 'a' && c <= 'z') ? (c - 'a' + 'A') : c);
     }
-    fndef->name[strlen(identifier->identifier)] = '\0';
+    fndef->name[namelen] = '\0';
 
     if ( akbasic_parser_match1(parser, AKBASIC_TOK_ASSIGNMENT) ) {
 	PASS(errctx, akbasic_parser_expression(parser, &expression));
@@ -866,13 +901,15 @@ akerr_ErrorContext *akbasic_parse_for(akbasic_Parser *parser, akbasic_ASTLeaf **
     akbasic_Environment *parent = runtime->environment;
     akbasic_Environment *newenv = NULL;
     int64_t firstline = 0;
+    int cmp = 0;
 
     PASS(errctx, akbasic_parser_assignment(parser, &assignment));
     FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND),
 		     AKBASIC_ERR_SYNTAX,
 		     "Expected FOR (assignment) TO (expression) [STEP (expression)]");
     PASS(errctx, akbasic_parser_previous(parser, &operator_));
-    FAIL_NONZERO_RETURN(errctx, strcmp(operator_->lexeme, "TO"), AKBASIC_ERR_SYNTAX,
+    PASS(errctx, aksl_strcmp(operator_->lexeme, "TO", &cmp));
+    FAIL_NONZERO_RETURN(errctx, cmp, AKBASIC_ERR_SYNTAX,
 			"Expected FOR (assignment) TO (expression) [STEP (expression)]");
     FAIL_ZERO_RETURN(errctx,
 		     (assignment != NULL && akbasic_leaf_is_identifier(assignment->left)),
@@ -894,7 +931,8 @@ akerr_ErrorContext *akbasic_parse_for(akbasic_Parser *parser, akbasic_ASTLeaf **
 
     if ( akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND) ) {
 	PASS(errctx, akbasic_parser_previous(parser, &operator_));
-	FAIL_NONZERO_RETURN(errctx, strcmp(operator_->lexeme, "STEP"), AKBASIC_ERR_SYNTAX,
+	PASS(errctx, aksl_strcmp(operator_->lexeme, "STEP", &cmp));
+	FAIL_NONZERO_RETURN(errctx, cmp, AKBASIC_ERR_SYNTAX,
 			    "Expected FOR (assignment) TO (expression) [STEP (expression)]");
 	PASS(errctx, akbasic_parser_expression(parser, &newenv->forStepLeaf));
     } else {
@@ -907,7 +945,8 @@ akerr_ErrorContext *akbasic_parse_for(akbasic_Parser *parser, akbasic_ASTLeaf **
     }
 
     /* A NEXT already being awaited means this is an inner loop over the same variable. */
-    if ( strcmp(parent->waitingForCommand, "NEXT") == 0 ) {
+    PASS(errctx, aksl_strcmp(parent->waitingForCommand, "NEXT", &cmp));
+    if ( cmp == 0 ) {
 	newenv->forNextVariable = parent->forNextVariable;
     }
     newenv->loopFirstLine = firstline;
@@ -1038,6 +1077,7 @@ akerr_ErrorContext *akbasic_parse_if(akbasic_Parser *parser, akbasic_ASTLeaf **d
     akbasic_ASTLeaf *else_command = NULL;
     akbasic_ASTLeaf *branch = NULL;
     akbasic_Token *operator_ = NULL;
+    int cmp = 0;
 
     /*
      * Everything from here to the THEN is a condition, so a lone `=` in it is an
@@ -1057,14 +1097,16 @@ akerr_ErrorContext *akbasic_parse_if(akbasic_Parser *parser, akbasic_ASTLeaf **d
     FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND),
 		     AKBASIC_ERR_SYNTAX, "Incomplete IF statement");
     PASS(errctx, akbasic_parser_previous(parser, &operator_));
-    FAIL_NONZERO_RETURN(errctx, strcmp(operator_->lexeme, "THEN"), AKBASIC_ERR_SYNTAX,
+    PASS(errctx, aksl_strcmp(operator_->lexeme, "THEN", &cmp));
+    FAIL_NONZERO_RETURN(errctx, cmp, AKBASIC_ERR_SYNTAX,
 			"Expected IF ... THEN");
 
     PASS(errctx, akbasic_parser_command(parser, &then_command));
 
     if ( akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND) ) {
 	PASS(errctx, akbasic_parser_previous(parser, &operator_));
-	FAIL_NONZERO_RETURN(errctx, strcmp(operator_->lexeme, "ELSE"), AKBASIC_ERR_SYNTAX,
+	PASS(errctx, aksl_strcmp(operator_->lexeme, "ELSE", &cmp));
+	FAIL_NONZERO_RETURN(errctx, cmp, AKBASIC_ERR_SYNTAX,
 			    "Expected IF ... THEN ... ELSE ...");
 	PASS(errctx, akbasic_parser_command(parser, &else_command));
     }

src/play.c

@@ -15,9 +15,9 @@
  */
 
 #include <ctype.h>
-#include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/audio.h>
 #include <akbasic/error.h>
@@ -96,7 +96,7 @@ akerr_ErrorContext *akbasic_play_parse(akbasic_Runtime *obj, const char *notes)
     FAIL_ZERO_RETURN(errctx, (obj != NULL && notes != NULL), AKERR_NULLPOINTER,
 		     "NULL argument in play_parse");
     audio = &obj->audio_state;
-    len = strlen(notes);
+    PASS(errctx, aksl_strlen(notes, &len));
 
     /*
      * A loop, so no CATCH and no _BREAK macros in here -- they expand to a C

src/renumber.c

@@ -27,10 +27,9 @@
 #include <inttypes.h>
 #include <stdio.h>
 #include <stdlib.h>
-#include <string.h>
-#include <strings.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/error.h>
 #include <akbasic/runtime.h>
@@ -103,7 +102,7 @@ static akerr_ErrorContext *rewrite_targets(akbasic_TargetWalk *walk, const char
     for ( ;; ) {
 	char replacement[32];
 	int64_t line = 0;
-	int written = 0;
+	size_t written = 0;
 
 	while ( *p == ' ' || *p == '\t' ) {
 	    FAIL_ZERO_RETURN(errctx, (out < limit), AKBASIC_ERR_BOUNDS,
@@ -126,9 +125,16 @@ static akerr_ErrorContext *rewrite_targets(akbasic_TargetWalk *walk, const char
 	    p += 1;
 	}
 	PASS(errctx, walk->visit(walk, line, replacement, sizeof(replacement)));
-	written = snprintf(out, (size_t)(limit - out), "%s", replacement);
+	/*
+	 * The fit is decided before the copy rather than read back out of a
+	 * return value afterwards: aksl_strcpy refuses rather than truncates,
+	 * so the bounds check has to come first to keep the diagnosis this
+	 * function already gives.
+	 */
+	PASS(errctx, aksl_strlen(replacement, &written));
 	FAIL_ZERO_RETURN(errctx, (written > 0 && out + written < limit), AKBASIC_ERR_BOUNDS,
 			 "RENUMBER: a rewritten line does not fit");
+	PASS(errctx, aksl_strcpy(out, (size_t)(limit - out), replacement));
 	out += written;
 
 	/*
@@ -176,6 +182,7 @@ static akerr_ErrorContext *rewrite_line(akbasic_TargetWalk *walk, const char *co
     const char *limit = dest + len - 1;
     bool statementstart = true;
     bool instring = false;
+    int cmp = 0;
     int i = 0;
 
     while ( *p != '\0' ) {
@@ -227,12 +234,12 @@ static akerr_ErrorContext *rewrite_line(akbasic_TargetWalk *walk, const char *co
 	 * name in the language to reach it.
 	 */
 	for ( i = 0; i < BRANCH_VERB_COUNT; i++ ) {
-	    verblen = strlen(BRANCH_VERBS[i]);
+	    PASS(errctx, aksl_strlen(BRANCH_VERBS[i], &verblen));
 	    if ( p > code && isalnum((unsigned char)p[-1]) ) {
 		break;
 	    }
-	    if ( strncasecmp(p, BRANCH_VERBS[i], verblen) == 0 &&
-		 !isalnum((unsigned char)p[verblen]) ) {
+	    PASS(errctx, aksl_strncasecmp(p, BRANCH_VERBS[i], verblen, &cmp));
+	    if ( cmp == 0 && !isalnum((unsigned char)p[verblen]) ) {
 		matched = true;
 		break;
 	    }
@@ -247,7 +254,7 @@ static akerr_ErrorContext *rewrite_line(akbasic_TargetWalk *walk, const char *co
 	if ( matched ) {
 	    FAIL_ZERO_RETURN(errctx, (out + verblen < (size_t)(limit - dest) + dest),
 			     AKBASIC_ERR_BOUNDS, "RENUMBER: a rewritten line does not fit");
-	    memcpy(out, p, verblen);
+	    PASS(errctx, aksl_memcpy(out, p, verblen));
 	    out += verblen;
 	    p += verblen;
 	    PASS(errctx, rewrite_targets(walk, &p, &out, limit));
@@ -260,9 +267,10 @@ static akerr_ErrorContext *rewrite_line(akbasic_TargetWalk *walk, const char *co
 	 * cannot be pointed at it directly. Copy the type and the comma, then
 	 * rewrite what follows.
 	 */
-	if ( strncasecmp(p, "COLLISION", 9) == 0 && !isalnum((unsigned char)p[9])
+	PASS(errctx, aksl_strncasecmp(p, "COLLISION", 9, &cmp));
+	if ( cmp == 0 && !isalnum((unsigned char)p[9])
 	     && !(p > code && isalnum((unsigned char)p[-1])) ) {
-	    memcpy(out, p, 9);
+	    PASS(errctx, aksl_memcpy(out, p, 9));
 	    out += 9;
 	    p += 9;
 	    while ( *p != '\0' && *p != ',' && *p != ':' ) {
@@ -299,8 +307,9 @@ static akerr_ErrorContext *visit_renumber(akbasic_TargetWalk *walk, int64_t targ
 {
     PREPARE_ERROR(errctx);
     const int64_t *map = (const int64_t *)walk->self;
+    int written = 0;
 
-    snprintf(dest, len, "%" PRId64, mapped(map, target));
+    PASS(errctx, aksl_snprintf(&written, dest, len, "%" PRId64, mapped(map, target)));
     SUCCEED_RETURN(errctx);
 }
 
@@ -347,7 +356,7 @@ akerr_ErrorContext *akbasic_renumber(akbasic_Runtime *obj, int64_t newstart, int
 	next += increment;
     }
 
-    memset(rewritten, 0, sizeof(rewritten));
+    PASS(errctx, aksl_memset(rewritten, 0, sizeof(rewritten)));
     for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
 	int64_t target = 0;
 
@@ -371,7 +380,7 @@ akerr_ErrorContext *akbasic_renumber(akbasic_Runtime *obj, int64_t newstart, int
 	rewritten[target].numbered = true;
     }
 
-    memcpy(obj->source, rewritten, sizeof(obj->source));
+    PASS(errctx, aksl_memcpy(obj->source, rewritten, sizeof(obj->source)));
     SUCCEED_RETURN(errctx);
 }
 
@@ -402,8 +411,9 @@ static akerr_ErrorContext *visit_check(akbasic_TargetWalk *walk, int64_t target,
 {
     PREPARE_ERROR(errctx);
     CheckState *state = (CheckState *)walk->self;
+    int written = 0;
 
-    snprintf(dest, len, "%" PRId64, target);
+    PASS(errctx, aksl_snprintf(&written, dest, len, "%" PRId64, target));
     if ( target >= 0 && target < AKBASIC_MAX_SOURCE_LINES ) {
 	FAIL_NONZERO_RETURN(errctx,
 			    (state->runtime->source[target].code[0] != '\0'

src/runtime.c

@@ -6,10 +6,9 @@
 #include <ctype.h>
 #include <inttypes.h>
 #include <stdio.h>
-#include <string.h>
-#include <strings.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/error.h>
 #include <akbasic/parser.h>
@@ -28,7 +27,7 @@ akerr_ErrorContext *akbasic_runtime_new_variable(akbasic_Runtime *obj, akbasic_V
 		     "NULL argument in new_variable");
     for ( i = 0; i < AKBASIC_MAX_VARIABLES; i++ ) {
 	if ( !obj->variables[i].used ) {
-	    memset(&obj->variables[i], 0, sizeof(obj->variables[i]));
+	    PASS(errctx, aksl_memset(&obj->variables[i], 0, sizeof(obj->variables[i])));
 	    obj->variables[i].used = true;
 	    /*
 	     * Not zero: zero is a valid structure type index, so a memset alone
@@ -102,7 +101,7 @@ akerr_ErrorContext *akbasic_runtime_new_function(akbasic_Runtime *obj, akbasic_F
 		     "NULL argument in new_function");
     for ( i = 0; i < AKBASIC_MAX_FUNCTIONS; i++ ) {
 	if ( !obj->functions[i].used ) {
-	    memset(&obj->functions[i], 0, sizeof(obj->functions[i]));
+	    PASS(errctx, aksl_memset(&obj->functions[i], 0, sizeof(obj->functions[i])));
 	    obj->functions[i].used = true;
 	    obj->functions[i].leafpool.next = 0;
 	    obj->functions[i].leafpool.capacity = AKBASIC_MAX_LEAVES * 2;
@@ -215,7 +214,7 @@ akerr_ErrorContext *akbasic_runtime_init(akbasic_Runtime *obj, akbasic_TextSink
      */
     PASS(errctx, akbasic_error_register());
 
-    memset(obj, 0, sizeof(*obj));
+    PASS(errctx, aksl_memset(obj, 0, sizeof(*obj)));
     obj->sink = sink;
     obj->environment = NULL;
     obj->autoLineNumber = 0;
@@ -279,7 +278,7 @@ akerr_ErrorContext *akbasic_runtime_set_ui(akbasic_Runtime *obj, akbasic_UiBacke
 akerr_ErrorContext *akbasic_runtime_set_source_path(akbasic_Runtime *obj, const char *path)
 {
     PREPARE_ERROR(errctx);
-    const char *slash = NULL;
+    char *slash = NULL;
     size_t length = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in set_source_path");
@@ -292,18 +291,18 @@ akerr_ErrorContext *akbasic_runtime_set_source_path(akbasic_Runtime *obj, const
      * would do it but it is allowed to modify its argument and two of the three
      * libcs this has to build on disagree about which one they implement.
      */
-    slash = strrchr(path, '/');
+    PASS(errctx, aksl_strrchr(path, '/', &slash));
     length = (slash == NULL ? 0 : (size_t)(slash - path));
     if ( length == 0 ) {
 	/* Either no directory at all, or the root. */
-	strncpy(obj->sourcepath, (slash == NULL ? "." : "/"), sizeof(obj->sourcepath) - 1);
-	obj->sourcepath[sizeof(obj->sourcepath) - 1] = '\0';
+	PASS(errctx, aksl_strcpy(obj->sourcepath, sizeof(obj->sourcepath),
+				 (slash == NULL ? "." : "/")));
 	SUCCEED_RETURN(errctx);
     }
     FAIL_ZERO_RETURN(errctx, (length < sizeof(obj->sourcepath)), AKBASIC_ERR_BOUNDS,
 		     "Program path of %zu characters exceeds the %d character limit",
-		     length, AKBASIC_MAX_LINE_LENGTH - 1);
-    memcpy(obj->sourcepath, path, length);
+		     length, AKBASIC_MAX_SOURCE_PATH_LENGTH - 1);
+    PASS(errctx, aksl_memcpy(obj->sourcepath, path, length));
     obj->sourcepath[length] = '\0';
     SUCCEED_RETURN(errctx);
 }
@@ -393,6 +392,16 @@ akerr_ErrorContext *akbasic_runtime_error(akbasic_Runtime *obj, akbasic_ErrorCla
      * The format, the trailing \n inside the string, and the second newline
      * writeln adds are all part of the acceptance contract --
      * tests/language/array_outofbounds.txt ends in 0a 0a. See TODO.md 1.8.
+     *
+     * **Raw snprintf on purpose, and this is the site where it matters most.**
+     * `line` is 512 bytes; `message` arrives from an akerr_ErrorContext, whose
+     * own buffer is AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH -- 12384. An ordinary
+     * long diagnostic therefore truncates, and truncating a report is correct
+     * here: this is the one function that tells the user *what went wrong*, and
+     * aksl_snprintf would turn a long message into a second, different failure
+     * that replaces the first. A report may be shortened; it may not be lost.
+     * libakstdlib #34 is the issue tracking the contract that would let a caller
+     * ask for the length instead.
      */
     snprintf(line, sizeof(line), "? %" PRId64 " : %s %s\n",
 	     obj->environment->lineno, errclass_to_string(errclass), message);
@@ -469,7 +478,15 @@ akerr_ErrorContext *akbasic_runtime_set_mode(akbasic_Runtime *obj, int mode)
 	} PROCESS(errctx) {
 	} HANDLE_DEFAULT(errctx) {
 	    char message[AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH];
-	    snprintf(message, sizeof(message), "%s", errctx->message);
+	    /*
+	     * Ignored rather than propagated: `errctx` is the error being
+	     * handled, so a PASS here would overwrite it with the copy's own
+	     * failure and the next line would read a released context. Same
+	     * reason the two calls below are ignored. aksl_strcpy empties the
+	     * destination before it copies, so a refusal leaves an empty
+	     * message rather than an uninitialised one.
+	     */
+	    IGNORE(aksl_strcpy(message, sizeof(message), errctx->message));
 	    obj->lasterrorstatus = errctx->status;
 	    IGNORE(akbasic_runtime_error(obj, AKBASIC_ERRCLASS_PARSE, message));
 	    IGNORE(akbasic_runtime_set_mode(obj, obj->run_finished_mode));
@@ -492,7 +509,14 @@ static akerr_ErrorContext *report_and_reraise(akbasic_Runtime *obj, akerr_ErrorC
     char message[AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH];
     int status = cause->status;
 
-    snprintf(message, sizeof(message), "%s", cause->message);
+    /*
+     * Ignored rather than passed: this function's whole contract is that the
+     * program's own error is the one that leaves, so a failure to copy the
+     * message must not become the error that gets raised. aksl_strcpy empties
+     * the destination first, so a refusal reports an empty message rather than
+     * an uninitialised one.
+     */
+    IGNORE(aksl_strcpy(message, sizeof(message), cause->message));
     /* What ER# reports, if a TRAP is armed. Recorded before the context goes. */
     obj->lasterrorstatus = status;
     cause->handled = true;
@@ -675,6 +699,7 @@ akerr_ErrorContext *akbasic_runtime_evaluate(akbasic_Runtime *obj, akbasic_ASTLe
     akbasic_Value *rval = NULL;
     akbasic_Value *scratch = NULL;
     const akbasic_Verb *verb = NULL;
+    int cmp = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
 		     "NULL argument in evaluate");
@@ -724,10 +749,12 @@ akerr_ErrorContext *akbasic_runtime_evaluate(akbasic_Runtime *obj, akbasic_ASTLe
 	     * reaches the end of this line. Arming the wait is what makes a
 	     * multi-line IF possible at all; BEND clears it.
 	     */
-	    if ( notaken != NULL && notaken->leaftype == AKBASIC_LEAF_COMMAND &&
-		 strcmp(notaken->identifier, "BEGIN") == 0 ) {
+	    if ( notaken != NULL && notaken->leaftype == AKBASIC_LEAF_COMMAND ) {
+		PASS(errctx, aksl_strcmp(notaken->identifier, "BEGIN", &cmp));
+		if ( cmp == 0 ) {
 		    PASS(errctx, akbasic_environment_wait_for_command(obj->environment, "BEND"));
 		}
+	    }
 	    if ( taken ) {
 		PASS(errctx, akbasic_runtime_evaluate(obj, expr->left, dest));
 		SUCCEED_RETURN(errctx);
@@ -765,7 +792,7 @@ akerr_ErrorContext *akbasic_runtime_evaluate(akbasic_Runtime *obj, akbasic_ASTLe
 
     case AKBASIC_LEAF_LITERAL_STRING:
 	lval->valuetype = AKBASIC_TYPE_STRING;
-	memcpy(lval->stringval, expr->literal_string, sizeof(lval->stringval));
+	PASS(errctx, aksl_memcpy(lval->stringval, expr->literal_string, sizeof(lval->stringval)));
 	SUCCEED_RETURN(errctx);
 
     case AKBASIC_LEAF_UNARY:
@@ -816,6 +843,10 @@ akerr_ErrorContext *akbasic_runtime_evaluate(akbasic_Runtime *obj, akbasic_ASTLe
 akerr_ErrorContext *akbasic_runtime_interpret(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    int cmp = 0;
+    bool waiting = false;
+    bool matchesverb = false;
+    bool waitingbend = false;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL && expr != NULL && dest != NULL), AKERR_NULLPOINTER,
 		     "NULL argument in interpret");
@@ -824,9 +855,21 @@ akerr_ErrorContext *akbasic_runtime_interpret(akbasic_Runtime *obj, akbasic_ASTL
      * verb. This is what keeps a zero-iteration FOR body from executing, given
      * that the loop condition is evaluated at the bottom of the structure.
      */
-    if ( akbasic_environment_is_waiting_for_any(obj->environment) ) {
-	if ( expr->leaftype != AKBASIC_LEAF_COMMAND ||
-	     !akbasic_environment_is_waiting_for(obj->environment, expr->identifier) ) {
+    PASS(errctx, akbasic_environment_is_waiting_for_any(obj->environment, &waiting));
+    if ( waiting ) {
+	/*
+	 * Hoisted out of the condition it used to be a term in: the test reads a
+	 * recorded verb name, that read can fail, and the old `bool` return had
+	 * nowhere to report it. `matchesverb` stays false unless the leaf really
+	 * is a command whose name is what the scope is waiting for, which is what
+	 * the `||` short-circuit used to say. See libakstdlib #38.
+	 */
+	matchesverb = false;
+	if ( expr->leaftype == AKBASIC_LEAF_COMMAND ) {
+	    PASS(errctx, akbasic_environment_is_waiting_for(obj->environment,
+							   expr->identifier, &matchesverb));
+	}
+	if ( !matchesverb ) {
 	    /*
 	     * **A skipped loop has already pushed its scope, and this is where it
 	     * comes back.**
@@ -860,12 +903,19 @@ akerr_ErrorContext *akbasic_runtime_interpret(akbasic_Runtime *obj, akbasic_ASTL
 	     */
 	    if ( expr->leaftype == AKBASIC_LEAF_COMMAND &&
 		 obj->environment->loopFirstLine != 0 &&
-		 obj->environment->waitingForCommand[0] == '\0' &&
-		 akbasic_environment_is_waiting_for(obj->environment, "BEND") &&
-		 (strcmp(expr->identifier, "FOR") == 0 ||
-		  strcmp(expr->identifier, "DO") == 0) ) {
+		 obj->environment->waitingForCommand[0] == '\0' ) {
+		PASS(errctx, akbasic_environment_is_waiting_for(obj->environment, "BEND",
+							       &waitingbend));
+		if ( waitingbend ) {
+		    PASS(errctx, aksl_strcmp(expr->identifier, "FOR", &cmp));
+		    if ( cmp != 0 ) {
+			PASS(errctx, aksl_strcmp(expr->identifier, "DO", &cmp));
+		    }
+		    if ( cmp == 0 ) {
 			PASS(errctx, akbasic_runtime_prev_environment(obj));
 		    }
+		}
+	    }
 	    *dest = &obj->staticTrueValue;
 	    SUCCEED_RETURN(errctx);
 	}
@@ -1064,9 +1114,33 @@ akerr_ErrorContext *akbasic_runtime_call_function(akbasic_Runtime *obj, const ch
      * answering wrongly -- which is worse. The fix wants the REPL's own line
      * cycle, and that is a larger change than a condition.
      */
+    ATTEMPT {
 	while ( obj->environment != targetenv && obj->mode == AKBASIC_MODE_RUN ) {
-	PASS(errctx, akbasic_runtime_process_line_run(obj));
+	    /*
+	     * The same per-line prologue akbasic_runtime_step() runs. Without
+	     * it the call environment's value scratch accumulates across the
+	     * whole body, and a body of ten real lines dies with "Maximum
+	     * values per line reached" -- a limit that is supposed to be per
+	     * line, not per call. step() cannot do this for us: this loop
+	     * drives process_line_run() directly.
+	     */
+	    CATCH(errctx, akbasic_runtime_zero(obj));
+	    CATCH(errctx, akbasic_scanner_zero(obj));
+	    CATCH(errctx, akbasic_runtime_process_line_run(obj));
 	}
+    } CLEANUP {
+	/*
+	 * A body that died mid-line -- a runtime error set run_finished_mode,
+	 * or a scanner error escaped (issue #4) -- left its scopes active.
+	 * Give them back, or a host absorbing script errors drains the
+	 * twelve-slot environment pool after twelve dead calls and every
+	 * call after that fails for a reason nobody can see in the script.
+	 */
+	while ( obj->environment != targetenv && obj->environment->parent != NULL ) {
+	    IGNORE(akbasic_runtime_prev_environment(obj));
+	}
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
     PASS(errctx, akbasic_environment_new_value(targetenv, &out));
     PASS(errctx, akbasic_value_clone(&targetenv->returnValue, out));
     *dest = out;
@@ -1125,15 +1199,18 @@ int64_t akbasic_runtime_find_previous_lineno(akbasic_Runtime *obj)
 akerr_ErrorContext *akbasic_runtime_store_line(akbasic_Runtime *obj, int64_t lineno, const char *code, bool numbered)
 {
     PREPARE_ERROR(errctx);
+    size_t length = 0;
 
     FAIL_ZERO_RETURN(errctx, (lineno >= 0 && lineno < AKBASIC_MAX_SOURCE_LINES),
 		     AKBASIC_ERR_BOUNDS,
 		     "Line number %" PRId64 " is outside 0..%d",
 		     lineno, AKBASIC_MAX_SOURCE_LINES - 1);
-    FAIL_ZERO_RETURN(errctx, (strlen(code) < AKBASIC_MAX_LINE_LENGTH), AKBASIC_ERR_BOUNDS,
+    PASS(errctx, aksl_strlen(code, &length));
+    FAIL_ZERO_RETURN(errctx, (length < AKBASIC_MAX_LINE_LENGTH), AKBASIC_ERR_BOUNDS,
 		     "Source line exceeds the %d character limit", AKBASIC_MAX_LINE_LENGTH - 1);
-    strncpy(obj->source[lineno].code, code, AKBASIC_MAX_LINE_LENGTH - 1);
-    obj->source[lineno].code[AKBASIC_MAX_LINE_LENGTH - 1] = '\0';
+    /* aksl_strcpy always terminates and refuses rather than truncates; the
+       length check above is what makes the refusal unreachable. */
+    PASS(errctx, aksl_strcpy(obj->source[lineno].code, sizeof(obj->source[lineno].code), code));
     obj->source[lineno].lineno = lineno;
     obj->source[lineno].numbered = numbered;
     SUCCEED_RETURN(errctx);
@@ -1242,11 +1319,12 @@ akerr_ErrorContext *akbasic_runtime_process_line_repl(akbasic_Runtime *obj)
     akbasic_ASTLeaf *leaf = NULL;
     akbasic_Value *value = NULL;
     akbasic_Parser parser;
+    int written = 0;
     bool eof = false;
 
     if ( obj->autoLineNumber > 0 ) {
-	snprintf(prompt, sizeof(prompt), "%" PRId64 " ",
-		 obj->environment->lineno + obj->autoLineNumber);
+	PASS(errctx, aksl_snprintf(&written, prompt, sizeof(prompt), "%" PRId64 " ",
+				   obj->environment->lineno + obj->autoLineNumber));
 	PASS(errctx, akbasic_runtime_write(obj, prompt));
     }
 
@@ -1272,7 +1350,8 @@ akerr_ErrorContext *akbasic_runtime_process_line_repl(akbasic_Runtime *obj)
 	} PROCESS(errctx) {
 	} HANDLE_DEFAULT(errctx) {
 	    char message[AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH];
-	    snprintf(message, sizeof(message), "%s", errctx->message);
+	    /* Ignored, not passed: `errctx` is the error being handled here. */
+	    IGNORE(aksl_strcpy(message, sizeof(message), errctx->message));
 	    obj->lasterrorstatus = errctx->status;
 	    IGNORE(akbasic_runtime_error(obj, AKBASIC_ERRCLASS_PARSE, message));
 	} FINISH(errctx, false);
@@ -1337,14 +1416,14 @@ akerr_ErrorContext *akbasic_runtime_process_line_run(akbasic_Runtime *obj)
     akbasic_ASTLeaf *leaf = NULL;
     akbasic_Value *value = NULL;
     akbasic_Parser parser;
+    int written = 0;
 
     if ( obj->environment->nextline >= AKBASIC_MAX_SOURCE_LINES ) {
 	PASS(errctx, akbasic_runtime_set_mode(obj, obj->run_finished_mode));
 	SUCCEED_RETURN(errctx);
     }
 
-    strncpy(line, obj->source[obj->environment->nextline].code, sizeof(line) - 1);
-    line[sizeof(line) - 1] = '\0';
+    PASS(errctx, aksl_strcpy(line, sizeof(line), obj->source[obj->environment->nextline].code));
     obj->environment->lineno = obj->environment->nextline;
     obj->environment->nextline += 1;
     if ( line[0] == '\0' ) {
@@ -1358,7 +1437,8 @@ akerr_ErrorContext *akbasic_runtime_process_line_run(akbasic_Runtime *obj)
      */
     if ( obj->trace ) {
 	char tracemark[32];
-	snprintf(tracemark, sizeof(tracemark), "[%" PRId64 "]", obj->environment->lineno);
+	PASS(errctx, aksl_snprintf(&written, tracemark, sizeof(tracemark), "[%" PRId64 "]",
+				   obj->environment->lineno));
 	PASS(errctx, akbasic_runtime_write(obj, tracemark));
     }
 
@@ -1373,7 +1453,8 @@ akerr_ErrorContext *akbasic_runtime_process_line_run(akbasic_Runtime *obj)
 	} PROCESS(errctx) {
 	} HANDLE_DEFAULT(errctx) {
 	    char message[AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH];
-	    snprintf(message, sizeof(message), "%s", errctx->message);
+	    /* Ignored, not passed: `errctx` is the error being handled here. */
+	    IGNORE(aksl_strcpy(message, sizeof(message), errctx->message));
 	    /*
 	     * What ER# reports, recorded before the context goes -- the same line
 	     * report_and_reraise() carries for a runtime error, and it was missing
@@ -1442,6 +1523,7 @@ static akerr_ErrorContext *scan_line_labels(akbasic_Environment *root, const cha
 {
     PREPARE_ERROR(errctx);
     const char *cursor = code;
+    int cmp = 0;
     bool statementstart = true;
     bool instring = false;
 
@@ -1479,8 +1561,9 @@ static akerr_ErrorContext *scan_line_labels(akbasic_Environment *root, const cha
 	    }
 	    continue;
 	}
-	if ( statementstart && strncasecmp(cursor, "LABEL", 5) == 0
-	     && !isalnum((unsigned char)cursor[5]) ) {
+	if ( statementstart ) {
+	    PASS(errctx, aksl_strncasecmp(cursor, "LABEL", 5, &cmp));
+	    if ( cmp == 0 && !isalnum((unsigned char)cursor[5]) ) {
 		char name[AKBASIC_SYMTAB_MAX_KEY];
 		size_t used = 0;
 
@@ -1505,6 +1588,7 @@ static akerr_ErrorContext *scan_line_labels(akbasic_Environment *root, const cha
 		statementstart = false;
 		continue;
 	    }
+	}
 	statementstart = false;
 	cursor += 1;
     }
@@ -1536,6 +1620,7 @@ akerr_ErrorContext *akbasic_runtime_arm_interrupt(akbasic_Runtime *obj, akbasic_
 {
     PREPARE_ERROR(errctx);
     akbasic_Interrupt *slot = NULL;
+    size_t length = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in arm_interrupt");
     FAIL_ZERO_RETURN(errctx, (source >= 0 && source < AKBASIC_MAX_INTERRUPTS),
@@ -1550,11 +1635,13 @@ akerr_ErrorContext *akbasic_runtime_arm_interrupt(akbasic_Runtime *obj, akbasic_
     slot->line = line;
     slot->label[0] = '\0';
     if ( label != NULL && label[0] != '\0' ) {
-	FAIL_ZERO_RETURN(errctx, (strlen(label) < sizeof(slot->label)), AKBASIC_ERR_BOUNDS,
+	PASS(errctx, aksl_strlen(label, &length));
+	FAIL_ZERO_RETURN(errctx, (length < sizeof(slot->label)), AKBASIC_ERR_BOUNDS,
 			 "Handler label \"%s\" exceeds the %zu character limit",
 			 label, sizeof(slot->label) - 1);
-	strncpy(slot->label, label, sizeof(slot->label) - 1);
-	slot->label[sizeof(slot->label) - 1] = '\0';
+	/* aksl_strcpy always terminates and refuses rather than truncates; the
+	   length check above is what makes the refusal unreachable. */
+	PASS(errctx, aksl_strcpy(slot->label, sizeof(slot->label), label));
     }
     SUCCEED_RETURN(errctx);
 }
@@ -1567,7 +1654,7 @@ akerr_ErrorContext *akbasic_runtime_disarm_interrupt(akbasic_Runtime *obj, akbas
     FAIL_ZERO_RETURN(errctx, (source >= 0 && source < AKBASIC_MAX_INTERRUPTS),
 		     AKBASIC_ERR_BOUNDS, "Interrupt source %d is outside 0..%d",
 		     (int)source, AKBASIC_MAX_INTERRUPTS - 1);
-    memset(&obj->interrupts[source], 0, sizeof(obj->interrupts[source]));
+    PASS(errctx, aksl_memset(&obj->interrupts[source], 0, sizeof(obj->interrupts[source])));
     SUCCEED_RETURN(errctx);
 }
 
@@ -1682,6 +1769,7 @@ akerr_ErrorContext *akbasic_runtime_load(akbasic_Runtime *obj, const char *sourc
     char scanned[AKBASIC_MAX_LINE_LENGTH];
     const char *cursor = NULL;
     const char *eol = NULL;
+    char *match = NULL;
     size_t length = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in load");
@@ -1696,9 +1784,11 @@ akerr_ErrorContext *akbasic_runtime_load(akbasic_Runtime *obj, const char *sourc
     obj->environment->lineno = 0;
 
     for ( cursor = source; *cursor != '\0'; cursor = (*eol == '\0' ? eol : eol + 1) ) {
-	eol = strchr(cursor, '\n');
+	PASS(errctx, aksl_strchr(cursor, '\n', &match));
+	eol = match;
 	if ( eol == NULL ) {
-	    eol = cursor + strlen(cursor);
+	    PASS(errctx, aksl_strlen(cursor, &length));
+	    eol = cursor + length;
 	}
 	length = (size_t)(eol - cursor);
 	if ( length > 0 && cursor[length - 1] == '\r' ) {
@@ -1707,7 +1797,7 @@ akerr_ErrorContext *akbasic_runtime_load(akbasic_Runtime *obj, const char *sourc
 	FAIL_ZERO_RETURN(errctx, (length < sizeof(line)), AKBASIC_ERR_BOUNDS,
 			 "Source line of %zu characters exceeds the %d character limit",
 			 length, AKBASIC_MAX_LINE_LENGTH - 1);
-	memcpy(line, cursor, length);
+	PASS(errctx, aksl_memcpy(line, cursor, length));
 	line[length] = '\0';
 	if ( line[0] == '\0' ) {
 	    continue;
@@ -1815,7 +1905,8 @@ akerr_ErrorContext *akbasic_runtime_step(akbasic_Runtime *obj)
 	} PROCESS(errctx) {
 	} HANDLE_DEFAULT(errctx) {
 	    char message[AKERR_MAX_ERROR_CONTEXT_STRING_LENGTH];
-	    snprintf(message, sizeof(message), "%s", errctx->message);
+	    /* Ignored, not passed: `errctx` is the error being handled here. */
+	    IGNORE(aksl_strcpy(message, sizeof(message), errctx->message));
 	    IGNORE(akbasic_runtime_error(obj, AKBASIC_ERRCLASS_RUNTIME, message));
 	} FINISH(errctx, false);
 	if ( obj->errclass != AKBASIC_ERRCLASS_NONE ) {
@@ -1851,6 +1942,15 @@ akerr_ErrorContext *akbasic_runtime_step(akbasic_Runtime *obj)
     SUCCEED_RETURN(errctx);
 }
 
+akerr_ErrorContext *akbasic_runtime_clear_error(akbasic_Runtime *obj)
+{
+    PREPARE_ERROR(errctx);
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in clear_error");
+    obj->errclass = AKBASIC_ERRCLASS_NONE;
+    SUCCEED_RETURN(errctx);
+}
+
 akerr_ErrorContext *akbasic_runtime_run(akbasic_Runtime *obj, int maxsteps)
 {
     PREPARE_ERROR(errctx);

src/runtime_commands.c

@@ -9,7 +9,6 @@
 #include <inttypes.h>
 #include <stdio.h>
 #include <stdlib.h>
-#include <string.h>
 
 #include <akerror.h>
 #include <akstdlib.h>
@@ -96,7 +95,7 @@ akerr_ErrorContext *akbasic_cmd_print(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
      */
     if ( (*dest)->valuetype == AKBASIC_TYPE_STRUCT || (*dest)->valuetype == AKBASIC_TYPE_POINTER ) {
 	if ( (*dest)->structbase == NULL ) {
-	    snprintf(rendered, sizeof(rendered), "NOTHING");
+	    PASS(errctx, aksl_strcpy(rendered, sizeof(rendered), "NOTHING"));
 	} else {
 	    PASS(errctx, akbasic_struct_to_string(obj, (*dest)->structtype, (*dest)->structbase,
 						  0, rendered, sizeof(rendered)));
@@ -149,13 +148,15 @@ akerr_ErrorContext *akbasic_cmd_return(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
 {
     PREPARE_ERROR(errctx);
     akbasic_Value *result = NULL;
+    bool waiting = false;
 
     (void)lval; (void)rval;
     /*
      * A RETURN reached while skipping forward to one is the end of a DEF body,
      * not a subroutine return. Stop waiting and carry on.
      */
-    if ( akbasic_environment_is_waiting_for(obj->environment, "RETURN") ) {
+    PASS(errctx, akbasic_environment_is_waiting_for(obj->environment, "RETURN", &waiting));
+    if ( waiting ) {
 	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "RETURN"));
 	SUCCEED_TRUE(obj, dest);
 	SUCCEED_RETURN(errctx);
@@ -445,6 +446,7 @@ akerr_ErrorContext *akbasic_cmd_input(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
     char rendered[AKBASIC_MAX_STRING_LENGTH];
     char buffer[AKBASIC_MAX_LINE_LENGTH];
     long long converted = 0;
+    size_t len = 0;
     bool eof = false;
 
     (void)lval; (void)rval;
@@ -479,10 +481,11 @@ akerr_ErrorContext *akbasic_cmd_input(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
 	break;
     default:
 	entered->valuetype = AKBASIC_TYPE_STRING;
-	FAIL_ZERO_RETURN(errctx, (strlen(buffer) < AKBASIC_MAX_STRING_LENGTH), AKBASIC_ERR_VALUE,
+	PASS(errctx, aksl_strlen(buffer, &len));
+	FAIL_ZERO_RETURN(errctx, (len < AKBASIC_MAX_STRING_LENGTH), AKBASIC_ERR_VALUE,
 			 "Input line exceeds the %d character limit", AKBASIC_MAX_STRING_LENGTH - 1);
-	strncpy(entered->stringval, buffer, AKBASIC_MAX_STRING_LENGTH - 1);
-	entered->stringval[AKBASIC_MAX_STRING_LENGTH - 1] = '\0';
+	/* aksl_strcpy always terminates, so the explicit terminator is gone. */
+	PASS(errctx, aksl_strcpy(entered->stringval, sizeof(entered->stringval), buffer));
 	break;
     }
     PASS(errctx, akbasic_environment_assign(obj->environment, identifier, entered, &unused));
@@ -539,6 +542,7 @@ akerr_ErrorContext *akbasic_cmd_list(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
     int64_t startidx = 0;
     int64_t endidx = 0;
     int64_t i = 0;
+    int written = 0;
 
     (void)lval; (void)rval;
     PASS(errctx, parse_line_range(obj, expr, &startidx, &endidx));
@@ -552,7 +556,8 @@ akerr_ErrorContext *akbasic_cmd_list(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
 	if ( obj->source[i].code[0] == '\0' ) {
 	    continue;
 	}
-	snprintf(line, sizeof(line), "%" PRId64 " %s", i, obj->source[i].code);
+	PASS(errctx, aksl_snprintf(&written, line, sizeof(line), "%" PRId64 " %s",
+				   i, obj->source[i].code));
 	PASS(errctx, akbasic_runtime_println(obj, line));
     }
     SUCCEED_TRUE(obj, dest);
@@ -588,6 +593,7 @@ static akerr_ErrorContext *filename_argument(akbasic_Runtime *obj, akbasic_ASTLe
 {
     PREPARE_ERROR(errctx);
     akbasic_Value *value = NULL;
+    size_t namelen = 0;
 
     FAIL_ZERO_RETURN(errctx, (expr != NULL && expr->right != NULL), AKBASIC_ERR_SYNTAX,
 		     "Expected a filename");
@@ -596,10 +602,107 @@ static akerr_ErrorContext *filename_argument(akbasic_Runtime *obj, akbasic_ASTLe
 			"Expected a filename string");
     FAIL_ZERO_RETURN(errctx, (value->stringval[0] != '\0'), AKBASIC_ERR_VALUE,
 		     "Filename must not be empty");
-    FAIL_ZERO_RETURN(errctx, (strlen(value->stringval) < len), AKBASIC_ERR_BOUNDS,
+    PASS(errctx, aksl_strlen(value->stringval, &namelen));
+    FAIL_ZERO_RETURN(errctx, (namelen < len), AKBASIC_ERR_BOUNDS,
 		     "Filename exceeds the %zu character limit", len - 1);
-    strncpy(dest, value->stringval, len - 1);
-    dest[len - 1] = '\0';
+    /* aksl_strcpy always terminates, so the explicit terminator is gone. */
+    PASS(errctx, aksl_strcpy(dest, len, value->stringval));
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Read one line, reporting end of stream rather than raising it.
+ *
+ * aksl_fgets raises AKERR_EOF where fgets(3) returned NULL, so the end of an
+ * ordinary file arrives as an error and has to be handled. It is handled here,
+ * in a function whose ATTEMPT block contains no loop at all, because a CATCH
+ * inside a loop expands to a break that leaves the loop rather than the
+ * ATTEMPT. The caller reads @p eof instead.
+ */
+static akerr_ErrorContext *dload_read_line(FILE *fp, char *buffer, size_t len, bool *eof)
+{
+    PREPARE_ERROR(errctx);
+    size_t used = 0;
+
+    *eof = false;
+    ATTEMPT {
+	CATCH(errctx, aksl_fgets(buffer, len, fp, &used));
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } HANDLE(errctx, AKERR_EOF) {
+	*eof = true;
+	used = 0;
+    } FINISH(errctx, true);
+
+    while ( used > 0 && (buffer[used - 1] == '\n' || buffer[used - 1] == '\r') ) {
+	buffer[used - 1] = '\0';
+	used -= 1;
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Read a whole program in, one line at a time.
+ *
+ * Hoisted out of akbasic_cmd_dload()'s ATTEMPT block because a loop inside one
+ * can use neither CATCH -- which breaks the loop -- nor PASS, which returns
+ * past CLEANUP and leaves the file open. Out here PASS is correct, and the
+ * caller CATCHes this one call.
+ */
+static akerr_ErrorContext *dload_read_program(akbasic_Runtime *obj, FILE *fp,
+					      char *buffer, size_t buflen,
+					      char *scanned, size_t scanlen)
+{
+    PREPARE_ERROR(errctx);
+    bool eof = false;
+
+    for ( ;; ) {
+	PASS(errctx, dload_read_line(fp, buffer, buflen, &eof));
+	if ( eof ) {
+	    break;
+	}
+	if ( buffer[0] == '\0' ) {
+	    continue;
+	}
+	PASS(errctx, akbasic_scanner_scan(obj, buffer, scanned, scanlen));
+	PASS(errctx, akbasic_runtime_file_line(obj, scanned));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Write every stored line out, numbered.
+ *
+ * Hoisted out of akbasic_cmd_dsave()'s ATTEMPT block for the same reason
+ * dload_read_program() is.
+ */
+static akerr_ErrorContext *dsave_write_program(akbasic_Runtime *obj, FILE *fp, char *line, size_t len)
+{
+    PREPARE_ERROR(errctx);
+    size_t written = 0;
+    int64_t i = 0;
+    int count = 0;
+
+    for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
+	if ( obj->source[i].code[0] == '\0' ) {
+	    continue;
+	}
+	/*
+	 * aksl_snprintf's count is the length it wrote, and it treats
+	 * truncation as an error rather than reporting a length it did not
+	 * write -- so it is what goes to fwrite, and the strlen that used to
+	 * recompute it is gone.
+	 */
+	PASS(errctx, aksl_snprintf(&count, line, len, "%" PRId64 " %s\n", i, obj->source[i].code));
+	/*
+	 * The written count is required by libakstdlib 0.2.0 and discarded
+	 * here on purpose: a short write is no longer something a caller has
+	 * to notice for itself, because that release made it an AKERR_IO
+	 * rather than a silent success. Before it, a DSAVE onto a full disk
+	 * reported nothing.
+	 */
+	PASS(errctx, aksl_fwrite(line, 1, (size_t)count, fp, &written));
+    }
     SUCCEED_RETURN(errctx);
 }
 
@@ -610,7 +713,6 @@ akerr_ErrorContext *akbasic_cmd_dload(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
     char buffer[AKBASIC_MAX_LINE_LENGTH];
     char scanned[AKBASIC_MAX_LINE_LENGTH];
     FILE *fp = NULL;
-    size_t used = 0;
     int64_t i = 0;
 
     (void)lval; (void)rval;
@@ -632,23 +734,14 @@ akerr_ErrorContext *akbasic_cmd_dload(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
 
     ATTEMPT {
 	CATCH(errctx, aksl_fopen(filename, "r", &fp));
-	while ( fgets(buffer, sizeof(buffer), fp) != NULL ) {
-	    used = strlen(buffer);
-	    while ( used > 0 && (buffer[used - 1] == '\n' || buffer[used - 1] == '\r') ) {
-		buffer[used - 1] = '\0';
-		used -= 1;
-	    }
-	    if ( buffer[0] == '\0' ) {
-		continue;
-	    }
 	/*
-	     * PASS inside the loop, never CATCH: CATCH expands to a break, which
-	     * would leave this loop rather than the ATTEMPT and let the rest of
-	     * the block run with an error pending.
+	 * The read is one CATCH of one call, because the loop it used to be
+	 * lives in dload_read_program() now: inside this block a loop can use
+	 * neither CATCH nor PASS without either escaping the loop or returning
+	 * past the fclose below.
 	 */
-	    PASS(errctx, akbasic_scanner_scan(obj, buffer, scanned, sizeof(scanned)));
-	    PASS(errctx, akbasic_runtime_file_line(obj, scanned));
-	}
+	CATCH(errctx, dload_read_program(obj, fp, buffer, sizeof(buffer),
+					 scanned, sizeof(scanned)));
     } CLEANUP {
 	if ( fp != NULL ) {
 	    IGNORE(aksl_fclose(fp));
@@ -676,30 +769,13 @@ akerr_ErrorContext *akbasic_cmd_dsave(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
     char filename[AKBASIC_MAX_STRING_LENGTH];
     char line[AKBASIC_MAX_LINE_LENGTH * 2];
     FILE *fp = NULL;
-    int64_t i = 0;
-    int count = 0;
-    size_t written = 0;
 
     (void)lval; (void)rval;
     PASS(errctx, filename_argument(obj, expr, filename, sizeof(filename)));
 
     ATTEMPT {
 	CATCH(errctx, aksl_fopen(filename, "w", &fp));
-	for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
-	    if ( obj->source[i].code[0] == '\0' ) {
-		continue;
-	    }
-	    snprintf(line, sizeof(line), "%" PRId64 " %s\n", i, obj->source[i].code);
-	    /*
-	     * The written count is required by libakstdlib 0.2.0 and discarded
-	     * here on purpose: a short write is no longer something a caller has
-	     * to notice for itself, because that release made it an AKERR_IO
-	     * rather than a silent success. Before it, a DSAVE onto a full disk
-	     * reported nothing.
-	     */
-	    PASS(errctx, aksl_fwrite(line, 1, strlen(line), fp, &written));
-	    count += 1;
-	}
+	CATCH(errctx, dsave_write_program(obj, fp, line, sizeof(line)));
     } CLEANUP {
 	if ( fp != NULL ) {
 	    IGNORE(aksl_fclose(fp));
@@ -807,6 +883,7 @@ akerr_ErrorContext *akbasic_cmd_next(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
     akbasic_Value *updated = NULL;
     akbasic_Value scratch;
     int64_t zerosubscript[1] = { 0 };
+    int cmp = 0;
     bool met = false;
 
     (void)lval; (void)rval;
@@ -842,7 +919,9 @@ akerr_ErrorContext *akbasic_cmd_next(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
      * A NEXT for someone else's loop variable: this environment is done, hand
      * the line back to the parent and pop. That is how nested loops unwind.
      */
-    if ( strcmp(expr->right->identifier, obj->environment->forNextVariable->name) != 0 ) {
+    PASS(errctx, aksl_strcmp(expr->right->identifier,
+			     obj->environment->forNextVariable->name, &cmp));
+    if ( cmp != 0 ) {
 	FAIL_ZERO_RETURN(errctx, (obj->environment->parent != NULL), AKBASIC_ERR_ENVIRONMENT,
 			 "NEXT in an orphaned environment");
 	obj->environment->parent->nextline = obj->environment->nextline;
@@ -951,7 +1030,8 @@ akerr_ErrorContext *akbasic_cmd_read(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
 	PASS(errctx, akbasic_leaf_init(&literal, AKBASIC_LEAF_LITERAL_INT));
 	if ( value.valuetype == AKBASIC_TYPE_STRING ) {
 	    literal.leaftype = AKBASIC_LEAF_LITERAL_STRING;
-	    snprintf(literal.literal_string, sizeof(literal.literal_string), "%s", value.stringval);
+	    PASS(errctx, aksl_strcpy(literal.literal_string, sizeof(literal.literal_string),
+				     value.stringval));
 	} else if ( value.valuetype == AKBASIC_TYPE_FLOAT ) {
 	    literal.leaftype = AKBASIC_LEAF_LITERAL_FLOAT;
 	    literal.literal_float = value.floatval;

src/runtime_console.c

@@ -15,6 +15,7 @@
 #include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/args.h>
 #include <akbasic/error.h>
@@ -114,6 +115,7 @@ akerr_ErrorContext *akbasic_cmd_key(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     /* Room for the longest macro plus `KEY n, ""` around it. */
     char line[AKBASIC_MAX_STRING_LENGTH + 32];
     int64_t number = 0;
+    int written = 0;
     int i = 0;
 
     (void)lval; (void)rval;
@@ -124,8 +126,8 @@ akerr_ErrorContext *akbasic_cmd_key(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     if ( arg == NULL ) {
 	/* Bare KEY lists the definitions, which is what a C128 does. */
 	for ( i = 0; i < AKBASIC_MAX_FUNCTION_KEYS; i++ ) {
-	    snprintf(line, sizeof(line), "KEY %d, \"%s\"",
-		     i + 1, obj->console_state.keys[i]);
+	    PASS(errctx, aksl_snprintf(&written, line, sizeof(line), "KEY %d, \"%s\"",
+				       i + 1, obj->console_state.keys[i]));
 	    PASS(errctx, akbasic_runtime_println(obj, line));
 	}
 	SUCCEED_TRUE(obj, dest);
@@ -146,8 +148,8 @@ akerr_ErrorContext *akbasic_cmd_key(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
     FAIL_NONZERO_RETURN(errctx, (value->valuetype != AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
 			"KEY expected a string");
-    snprintf(obj->console_state.keys[number - 1],
-	     sizeof(obj->console_state.keys[0]), "%s", value->stringval);
+    PASS(errctx, aksl_snprintf(&written, obj->console_state.keys[number - 1],
+			       sizeof(obj->console_state.keys[0]), "%s", value->stringval));
     SUCCEED_TRUE(obj, dest);
     SUCCEED_RETURN(errctx);
 }
@@ -253,7 +255,7 @@ akerr_ErrorContext *akbasic_console_state_init(akbasic_ConsoleState *obj)
     PREPARE_ERROR(errctx);
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL console state in init");
-    memset(obj, 0, sizeof(*obj));
+    PASS(errctx, aksl_memset(obj, 0, sizeof(*obj)));
     SUCCEED_RETURN(errctx);
 }
 
@@ -302,6 +304,7 @@ akerr_ErrorContext *akbasic_console_update_clock(akbasic_Runtime *obj)
     int64_t jiffies = 0;
     int64_t seconds = 0;
     char text[16];
+    int written = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in update_clock");
     if ( obj->environment == NULL ) {
@@ -324,8 +327,9 @@ akerr_ErrorContext *akbasic_console_update_clock(akbasic_Runtime *obj)
     PASS(errctx, akbasic_variable_set_integer(variable, jiffies, zerosubscript, 1));
 
     seconds = obj->timems / 1000;
-    snprintf(text, sizeof(text), "%02" PRId64 "%02" PRId64 "%02" PRId64,
-	     (seconds / 3600) % 24, (seconds / 60) % 60, seconds % 60);
+    PASS(errctx, aksl_snprintf(&written, text, sizeof(text),
+			       "%02" PRId64 "%02" PRId64 "%02" PRId64,
+			       (seconds / 3600) % 24, (seconds / 60) % 60, seconds % 60));
     PASS(errctx, akbasic_runtime_global(obj, "TI$", &variable));
     PASS(errctx, akbasic_variable_set_string(variable, text, zerosubscript, 1));
     SUCCEED_RETURN(errctx);

src/runtime_disk.c

@@ -22,7 +22,6 @@
 
 #include <inttypes.h>
 #include <stdio.h>
-#include <string.h>
 
 #include <akerror.h>
 #include <akstdlib.h>
@@ -44,7 +43,7 @@ akerr_ErrorContext *akbasic_disk_state_init(akbasic_DiskState *obj)
     PREPARE_ERROR(errctx);
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL disk state in init");
-    memset(obj, 0, sizeof(*obj));
+    PASS(errctx, aksl_memset(obj, 0, sizeof(*obj)));
     SUCCEED_RETURN(errctx);
 }
 
@@ -103,7 +102,12 @@ static akerr_ErrorContext *string_arg(akbasic_Runtime *obj, akbasic_ASTLeaf *arg
     PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
     FAIL_NONZERO_RETURN(errctx, (value->valuetype != AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
 			"%s expected a file name", verb);
-    snprintf(dest, len, "%s", value->stringval);
+    /*
+     * A plain copy, so aksl_strcpy rather than aksl_snprintf: it refuses rather
+     * than truncates, and every caller here hands in a buffer the size of a
+     * string value, so a name that did not fit could only ever be a bug.
+     */
+    PASS(errctx, aksl_strcpy(dest, len, value->stringval));
     SUCCEED_RETURN(errctx);
 }
 
@@ -157,7 +161,7 @@ static akerr_ErrorContext *open_file(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
     }
 
     PASS(errctx, aksl_fopen(name, mode, &channel->fp));
-    snprintf(channel->name, sizeof(channel->name), "%s", name);
+    PASS(errctx, aksl_strcpy(channel->name, sizeof(channel->name), name));
     channel->writing = writing;
     SUCCEED_RETURN(errctx);
 }
@@ -265,13 +269,24 @@ akerr_ErrorContext *akbasic_cmd_record(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
 akerr_ErrorContext *akbasic_cmd_scratch(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    akerr_ErrorContext *failure = NULL;
     char name[AKBASIC_MAX_STRING_LENGTH];
 
     (void)lval; (void)rval;
     FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER, "NULL argument in SCRATCH");
     PASS(errctx, string_arg(obj, akbasic_leaf_first_argument(expr), "SCRATCH", name, sizeof(name)));
-    FAIL_ZERO_RETURN(errctx, (remove(name) == 0), AKERR_IO,
-		     "SCRATCH could not delete \"%s\"", name);
+    /*
+     * Caught and restated rather than passed. aksl_remove raises the bare errno,
+     * and "No such file or directory" on its own does not say which file or
+     * which verb wanted it -- so the wrapper's error is retired here and the
+     * message the program sees keeps naming both.
+     */
+    failure = aksl_remove(name);
+    if ( failure != NULL ) {
+	failure->handled = true;
+	IGNORE(akerr_release_error(failure));
+	FAIL_RETURN(errctx, AKERR_IO, "SCRATCH could not delete \"%s\"", name);
+    }
     SUCCEED_TRUE(obj, dest);
     SUCCEED_RETURN(errctx);
 }
@@ -279,6 +294,7 @@ akerr_ErrorContext *akbasic_cmd_scratch(akbasic_Runtime *obj, akbasic_ASTLeaf *e
 akerr_ErrorContext *akbasic_cmd_rename(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    akerr_ErrorContext *failure = NULL;
     akbasic_ASTLeaf *arg = NULL;
     char from[AKBASIC_MAX_STRING_LENGTH];
     char to[AKBASIC_MAX_STRING_LENGTH];
@@ -288,8 +304,13 @@ akerr_ErrorContext *akbasic_cmd_rename(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
     arg = akbasic_leaf_first_argument(expr);
     PASS(errctx, string_arg(obj, arg, "RENAME", from, sizeof(from)));
     PASS(errctx, string_arg(obj, (arg != NULL ? arg->next : NULL), "RENAME", to, sizeof(to)));
-    FAIL_ZERO_RETURN(errctx, (rename(from, to) == 0), AKERR_IO,
-		     "RENAME could not rename \"%s\" to \"%s\"", from, to);
+    /* Caught and restated, for the reason SCRATCH gives: the message names both files. */
+    failure = aksl_rename(from, to);
+    if ( failure != NULL ) {
+	failure->handled = true;
+	IGNORE(akerr_release_error(failure));
+	FAIL_RETURN(errctx, AKERR_IO, "RENAME could not rename \"%s\" to \"%s\"", from, to);
+    }
     SUCCEED_TRUE(obj, dest);
     SUCCEED_RETURN(errctx);
 }
@@ -486,6 +507,7 @@ akerr_ErrorContext *akbasic_disk_write(akbasic_Runtime *obj, int64_t number, con
 {
     PREPARE_ERROR(errctx);
     akbasic_Channel *channel = NULL;
+    size_t length = 0;
     size_t put = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL && text != NULL), AKERR_NULLPOINTER,
@@ -493,7 +515,8 @@ akerr_ErrorContext *akbasic_disk_write(akbasic_Runtime *obj, int64_t number, con
     PASS(errctx, open_channel(obj, number, &channel));
     FAIL_ZERO_RETURN(errctx, channel->writing, AKBASIC_ERR_STATE,
 		     "Channel %" PRId64 " was opened for reading", number);
-    PASS(errctx, aksl_fwrite(text, 1, strlen(text), channel->fp, &put));
+    PASS(errctx, aksl_strlen(text, &length));
+    PASS(errctx, aksl_fwrite(text, 1, length, channel->fp, &put));
     PASS(errctx, aksl_fwrite("\n", 1, 1, channel->fp, &put));
     SUCCEED_RETURN(errctx);
 }
@@ -525,7 +548,7 @@ akerr_ErrorContext *akbasic_disk_readline(akbasic_Runtime *obj, int64_t number,
 	*eof = true;
 	SUCCEED_RETURN(errctx);
     }
-    newline = strchr(dest, '\n');
+    PASS(errctx, aksl_strchr(dest, '\n', &newline));
     if ( newline != NULL ) {
 	*newline = '\0';
     }
@@ -582,7 +605,7 @@ akerr_ErrorContext *akbasic_cmd_input_channel(akbasic_Runtime *obj, akbasic_ASTL
      * variable reading an empty line gets zero, the same as a C128.
      */
     PASS(errctx, akbasic_leaf_init(&literal, AKBASIC_LEAF_LITERAL_STRING));
-    snprintf(literal.literal_string, sizeof(literal.literal_string), "%s", text);
+    PASS(errctx, aksl_strcpy(literal.literal_string, sizeof(literal.literal_string), text));
     if ( akbasic_leaf_identifier_type(identifier) == AKBASIC_TYPE_INTEGER ) {
 	long long converted = 0;
 
@@ -610,13 +633,69 @@ akerr_ErrorContext *akbasic_cmd_input_channel(akbasic_Runtime *obj, akbasic_ASTL
 
 /* ---------------------------------------------------------------- VERIFY -- */
 
+/**
+ * @brief Count the lines of @p fp that differ from the program in memory.
+ *
+ * Its own function so that the comparison can be reached with a single CATCH.
+ * Written inline it would be a loop inside VERIFY's ATTEMPT, where neither form
+ * is available: CATCH expands to a break that would escape only the loop, and
+ * PASS returns past the CLEANUP that closes the file. One call is neither, so
+ * the wrappers below can PASS in the ordinary way.
+ */
+static akerr_ErrorContext *verify_lines(akbasic_Runtime *obj, FILE *fp, int64_t *dest)
+{
+    PREPARE_ERROR(errctx);
+    akerr_ErrorContext *got = NULL;
+    char line[AKBASIC_MAX_LINE_LENGTH];
+    const char *filetext = NULL;
+    char *newline = NULL;
+    int64_t lineno = 0;
+    size_t length = 0;
+    int cmp = 0;
+
+    *dest = 0;
+    for ( lineno = 0; lineno < AKBASIC_MAX_SOURCE_LINES; lineno++ ) {
+	if ( obj->source[lineno].code[0] == '\0' ) {
+	    continue;
+	}
+	got = aksl_fgets(line, sizeof(line), fp, &length);
+	if ( got != NULL ) {
+	    got->handled = true;
+	    IGNORE(akerr_release_error(got));
+	    *dest += 1;
+	    break;
+	}
+	PASS(errctx, aksl_strchr(line, '\n', &newline));
+	if ( newline != NULL ) {
+	    *newline = '\0';
+	}
+	/*
+	 * The stored line has had its number stripped, so the file's copy is
+	 * compared from past its own number.
+	 */
+	filetext = line;
+	while ( *filetext == ' ' ) {
+	    filetext += 1;
+	}
+	while ( *filetext >= '0' && *filetext <= '9' ) {
+	    filetext += 1;
+	}
+	while ( *filetext == ' ' ) {
+	    filetext += 1;
+	}
+	PASS(errctx, aksl_strcmp(filetext, obj->source[lineno].code, &cmp));
+	if ( cmp != 0 ) {
+	    *dest += 1;
+	}
+    }
+    SUCCEED_RETURN(errctx);
+}
+
 akerr_ErrorContext *akbasic_cmd_dverify(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
     FILE *fp = NULL;
     char name[AKBASIC_MAX_STRING_LENGTH];
-    char line[AKBASIC_MAX_LINE_LENGTH];
-    int64_t lineno = 0;
     int64_t mismatch = 0;
 
     (void)lval; (void)rval;
@@ -632,47 +711,7 @@ akerr_ErrorContext *akbasic_cmd_dverify(akbasic_Runtime *obj, akbasic_ASTLeaf *e
      */
     PASS(errctx, aksl_fopen(name, "r", &fp));
     ATTEMPT {
-	for ( lineno = 0; lineno < AKBASIC_MAX_SOURCE_LINES; lineno++ ) {
-	    size_t length = 0;
-	    akerr_ErrorContext *got = NULL;
-	    char *newline = NULL;
-
-	    if ( obj->source[lineno].code[0] == '\0' ) {
-		continue;
-	    }
-	    got = aksl_fgets(line, sizeof(line), fp, &length);
-	    if ( got != NULL ) {
-		got->handled = true;
-		IGNORE(akerr_release_error(got));
-		mismatch += 1;
-		break;
-	    }
-	    newline = strchr(line, '\n');
-	    if ( newline != NULL ) {
-		*newline = '\0';
-	    }
-	    /*
-	     * The stored line has had its number stripped, so the file's copy is
-	     * compared from past its own number. PASS rather than CATCH: this is
-	     * a loop.
-	     */
-	    {
-		const char *filetext = line;
-
-		while ( *filetext == ' ' ) {
-		    filetext += 1;
-		}
-		while ( *filetext >= '0' && *filetext <= '9' ) {
-		    filetext += 1;
-		}
-		while ( *filetext == ' ' ) {
-		    filetext += 1;
-		}
-		if ( strcmp(filetext, obj->source[lineno].code) != 0 ) {
-		    mismatch += 1;
-		}
-	    }
-	}
+	CATCH(errctx, verify_lines(obj, fp, &mismatch));
     } CLEANUP {
 	IGNORE(aksl_fclose(fp));
     } PROCESS(errctx) {

src/runtime_functions.c

@@ -14,7 +14,6 @@
 #include <inttypes.h>
 #include <math.h>
 #include <stdio.h>
-#include <string.h>
 
 #include <akerror.h>
 #include <akstdlib.h>
@@ -189,13 +188,19 @@ akerr_ErrorContext *akbasic_fn_hex(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     PREPARE_ERROR(errctx);
     akbasic_Value *arg = NULL;
     akbasic_Value *out = NULL;
+    int written = 0;
 
     (void)lval; (void)rval;
     PASS(errctx, first_arg(obj, expr, "HEX", NULL, &arg, &out));
     FAIL_NONZERO_RETURN(errctx, (arg->valuetype != AKBASIC_TYPE_INTEGER), AKBASIC_ERR_TYPE,
 			"HEX expected an integer");
     out->valuetype = AKBASIC_TYPE_STRING;
-    snprintf(out->stringval, sizeof(out->stringval), "%" PRIx64, arg->intval);
+    /*
+     * aksl_snprintf refuses to truncate, which costs nothing here: sixteen hex
+     * digits is the longest an int64_t can be and a string value holds far more.
+     */
+    PASS(errctx, aksl_snprintf(&written, out->stringval, sizeof(out->stringval),
+			       "%" PRIx64, arg->intval));
     *dest = out;
     SUCCEED_RETURN(errctx);
 }
@@ -270,6 +275,7 @@ akerr_ErrorContext *akbasic_fn_len(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     akbasic_Value *strval = NULL;
     akbasic_Value *out = NULL;
     akbasic_Variable *variable = NULL;
+    size_t length = 0;
 
     (void)lval; (void)rval;
     /*
@@ -291,7 +297,8 @@ akerr_ErrorContext *akbasic_fn_len(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     if ( argleaf->leaftype == AKBASIC_LEAF_LITERAL_STRING ||
 	 argleaf->leaftype == AKBASIC_LEAF_IDENTIFIER_STRING ) {
 	PASS(errctx, akbasic_runtime_evaluate(obj, argleaf, &strval));
-	out->intval = (int64_t)strlen(strval->stringval);
+	PASS(errctx, aksl_strlen(strval->stringval, &length));
+	out->intval = (int64_t)length;
     } else {
 	PASS(errctx, akbasic_environment_get(obj->environment, argleaf->identifier, &variable));
 	FAIL_ZERO_RETURN(errctx, (variable != NULL), AKBASIC_ERR_UNDEFINED,
@@ -338,7 +345,8 @@ akerr_ErrorContext *akbasic_fn_instr(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
     PASS(errctx, akbasic_environment_new_value(obj->environment, &out));
     PASS(errctx, akbasic_value_zero(out));
     out->valuetype = AKBASIC_TYPE_INTEGER;
-    hit = strstr(haystack->stringval, needle->stringval);
+    /* Not finding it is a successful NULL, which is exactly the -1 answer below. */
+    PASS(errctx, aksl_strstr(haystack->stringval, needle->stringval, &hit));
     out->intval = (hit == NULL ? -1 : (int64_t)(hit - haystack->stringval));
     *dest = out;
     SUCCEED_RETURN(errctx);
@@ -360,7 +368,7 @@ akerr_ErrorContext *akbasic_fn_left(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
 			"LEFT expected a string");
     FAIL_NONZERO_RETURN(errctx, (count->valuetype != AKBASIC_TYPE_INTEGER), AKBASIC_ERR_TYPE,
 			"LEFT expected an integer count");
-    sourcelen = strlen(source->stringval);
+    PASS(errctx, aksl_strlen(source->stringval, &sourcelen));
     take = count->intval;
     if ( take < 0 ) {
 	take = 0;
@@ -371,7 +379,7 @@ akerr_ErrorContext *akbasic_fn_left(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     PASS(errctx, akbasic_environment_new_value(obj->environment, &out));
     PASS(errctx, akbasic_value_zero(out));
     out->valuetype = AKBASIC_TYPE_STRING;
-    memcpy(out->stringval, source->stringval, (size_t)take);
+    PASS(errctx, aksl_memcpy(out->stringval, source->stringval, (size_t)take));
     out->stringval[take] = '\0';
     *dest = out;
     SUCCEED_RETURN(errctx);
@@ -393,7 +401,7 @@ akerr_ErrorContext *akbasic_fn_right(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
 			"RIGHT expected a string");
     FAIL_NONZERO_RETURN(errctx, (count->valuetype != AKBASIC_TYPE_INTEGER), AKBASIC_ERR_TYPE,
 			"RIGHT expected an integer count");
-    sourcelen = strlen(source->stringval);
+    PASS(errctx, aksl_strlen(source->stringval, &sourcelen));
     take = count->intval;
     if ( take < 0 ) {
 	take = 0;
@@ -404,7 +412,8 @@ akerr_ErrorContext *akbasic_fn_right(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
     PASS(errctx, akbasic_environment_new_value(obj->environment, &out));
     PASS(errctx, akbasic_value_zero(out));
     out->valuetype = AKBASIC_TYPE_STRING;
-    memcpy(out->stringval, source->stringval + (sourcelen - (size_t)take), (size_t)take);
+    PASS(errctx, aksl_memcpy(out->stringval, source->stringval + (sourcelen - (size_t)take),
+			     (size_t)take));
     out->stringval[take] = '\0';
     *dest = out;
     SUCCEED_RETURN(errctx);
@@ -432,7 +441,7 @@ akerr_ErrorContext *akbasic_fn_mid(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
 		      lengthval->valuetype == AKBASIC_TYPE_INTEGER),
 		     AKBASIC_ERR_TYPE, "MID expected integer start and length");
 
-    sourcelen = strlen(source->stringval);
+    PASS(errctx, aksl_strlen(source->stringval, &sourcelen));
     start = startval->intval;
     length = lengthval->intval;
     FAIL_ZERO_RETURN(errctx, (start >= 0 && (size_t)start <= sourcelen), AKBASIC_ERR_BOUNDS,
@@ -446,7 +455,7 @@ akerr_ErrorContext *akbasic_fn_mid(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     PASS(errctx, akbasic_environment_new_value(obj->environment, &out));
     PASS(errctx, akbasic_value_zero(out));
     out->valuetype = AKBASIC_TYPE_STRING;
-    memcpy(out->stringval, source->stringval + start, (size_t)length);
+    PASS(errctx, aksl_memcpy(out->stringval, source->stringval + start, (size_t)length));
     out->stringval[length] = '\0';
     *dest = out;
     SUCCEED_RETURN(errctx);

src/runtime_graphics.c

@@ -709,6 +709,7 @@ akerr_ErrorContext *akbasic_cmd_sshape(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
     char encoded[AKBASIC_MAX_STRING_LENGTH];
     int64_t subscripts[AKBASIC_MAX_ARRAY_DEPTH];
     int subscriptcount = 0;
+    int written = 0;
 
     (void)lval; (void)rval;
     PASS(errctx, require_graphics(obj, "SSHAPE"));
@@ -742,7 +743,7 @@ akerr_ErrorContext *akbasic_cmd_sshape(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
      * BASIC ever does with it; what it can no longer do is save it to disk or
      * take its LEN and get a size. TODO.md section 5.
      */
-    snprintf(encoded, sizeof(encoded), "%s%d", SHAPE_PREFIX, handle);
+    PASS(errctx, aksl_snprintf(&written, encoded, sizeof(encoded), "%s%d", SHAPE_PREFIX, handle));
     PASS(errctx, akbasic_variable_set_string(variable, encoded, subscripts, subscriptcount));
     SUCCEED_TRUE(obj, dest);
     SUCCEED_RETURN(errctx);
@@ -762,7 +763,9 @@ akerr_ErrorContext *akbasic_cmd_gshape(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
     double x = 0.0;
     double y = 0.0;
     int64_t subscripts[AKBASIC_MAX_ARRAY_DEPTH];
+    size_t prefixlen = 0;
     int subscriptcount = 0;
+    int cmp = 0;
 
     (void)lval; (void)rval;
     PASS(errctx, require_graphics(obj, "GSHAPE"));
@@ -782,11 +785,11 @@ akerr_ErrorContext *akbasic_cmd_gshape(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
     y = (count >= 2) ? coords[1] : obj->gfx.y;
 
     PASS(errctx, akbasic_variable_get_subscript(variable, subscripts, subscriptcount, &stored));
-    FAIL_ZERO_RETURN(errctx,
-		     (strncmp(stored->stringval, SHAPE_PREFIX, strlen(SHAPE_PREFIX)) == 0),
-		     AKBASIC_ERR_VALUE,
+    PASS(errctx, aksl_strlen(SHAPE_PREFIX, &prefixlen));
+    PASS(errctx, aksl_strncmp(stored->stringval, SHAPE_PREFIX, prefixlen, &cmp));
+    FAIL_ZERO_RETURN(errctx, (cmp == 0), AKBASIC_ERR_VALUE,
 		     "GSHAPE was given a string that did not come from SSHAPE");
-    PASS(errctx, aksl_atoll(stored->stringval + strlen(SHAPE_PREFIX), &converted));
+    PASS(errctx, aksl_atoll(stored->stringval + prefixlen, &converted));
     handle = (int64_t)converted;
 
     scale_point(&obj->gfx, &x, &y);

src/runtime_housekeeping.c

@@ -13,10 +13,9 @@
  */
 
 #include <inttypes.h>
-#include <stdio.h>
-#include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/args.h>
 #include <akbasic/error.h>
@@ -322,13 +321,13 @@ akerr_ErrorContext *akbasic_cmd_swap(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
      * exactly this reason. The names stay put: they are what the symbol table
      * points at.
      */
-    memcpy(namea, a->name, sizeof(namea));
-    memcpy(nameb, b->name, sizeof(nameb));
-    memcpy(&swap, a, sizeof(swap));
-    memcpy(a, b, sizeof(*a));
-    memcpy(b, &swap, sizeof(*b));
-    memcpy(a->name, namea, sizeof(a->name));
-    memcpy(b->name, nameb, sizeof(b->name));
+    PASS(errctx, aksl_memcpy(namea, a->name, sizeof(namea)));
+    PASS(errctx, aksl_memcpy(nameb, b->name, sizeof(nameb)));
+    PASS(errctx, aksl_memcpy(&swap, a, sizeof(swap)));
+    PASS(errctx, aksl_memcpy(a, b, sizeof(*a)));
+    PASS(errctx, aksl_memcpy(b, &swap, sizeof(*b)));
+    PASS(errctx, aksl_memcpy(a->name, namea, sizeof(a->name)));
+    PASS(errctx, aksl_memcpy(b->name, nameb, sizeof(b->name)));
     /*
      * A scalar's storage is *inside* the record, so the pointer that came over
      * with it names the other variable's inline slot -- which now holds this
@@ -352,6 +351,7 @@ akerr_ErrorContext *akbasic_cmd_help(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
 {
     PREPARE_ERROR(errctx);
     char line[AKBASIC_MAX_LINE_LENGTH * 2];
+    int written = 0;
 
     (void)expr; (void)lval; (void)rval;
     FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER, "NULL argument in HELP");
@@ -369,8 +369,14 @@ akerr_ErrorContext *akbasic_cmd_help(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
 	SUCCEED_TRUE(obj, dest);
 	SUCCEED_RETURN(errctx);
     }
-    snprintf(line, sizeof(line), "%" PRId64 " %s",
-	     obj->errorline, obj->source[obj->errorline].code);
+    /*
+     * aksl_snprintf treats truncation as an error, and this destination is twice
+     * AKBASIC_MAX_LINE_LENGTH against a stored line that is at most one of them
+     * plus a line number, so the fit is a property of the buffer rather than
+     * something to check for.
+     */
+    PASS(errctx, aksl_snprintf(&written, line, sizeof(line), "%" PRId64 " %s",
+			       obj->errorline, obj->source[obj->errorline].code));
     PASS(errctx, akbasic_runtime_println(obj, line));
     SUCCEED_TRUE(obj, dest);
     SUCCEED_RETURN(errctx);

src/runtime_input.c

@@ -14,9 +14,8 @@
  * as sitting on the keyboard. See TODO.md section 5.
  */
 
-#include <string.h>
-
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/error.h>
 #include <akbasic/input.h>
@@ -152,9 +151,8 @@ akerr_ErrorContext *akbasic_cmd_getkey(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
     }
     obj->input_state.waiting = true;
     obj->input_state.numeric = numeric;
-    strncpy(obj->input_state.variable, arg->identifier,
-	    sizeof(obj->input_state.variable) - 1);
-    obj->input_state.variable[sizeof(obj->input_state.variable) - 1] = '\0';
+    PASS(errctx, aksl_strcpy(obj->input_state.variable,
+			     sizeof(obj->input_state.variable), arg->identifier));
     SUCCEED_TRUE(obj, dest);
     SUCCEED_RETURN(errctx);
 }

src/runtime_machine.c

@@ -14,9 +14,9 @@
 
 #include <inttypes.h>
 #include <stdio.h>
-#include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/args.h>
 #include <akbasic/error.h>
@@ -69,7 +69,8 @@ static akerr_ErrorContext *copy_bytes(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
      * POKE and PEEK. A BASIC integer here is a real address, so a wrong one is a
      * segmentation fault rather than an error message. See TODO.md section 5.
      */
-    memmove((void *)(uintptr_t)args[2], (const void *)(uintptr_t)args[1], (size_t)length);
+    PASS(errctx, aksl_memmove((void *)(uintptr_t)args[2], (const void *)(uintptr_t)args[1],
+			      (size_t)length));
     SUCCEED_RETURN(errctx);
 }
 

src/runtime_sprite.c

@@ -31,6 +31,7 @@
 #include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/args.h>
 #include <akbasic/error.h>
@@ -403,6 +404,9 @@ static akerr_ErrorContext *define_from_leaf(akbasic_Runtime *obj, akbasic_ASTLea
     akbasic_Color fg;
     akbasic_Color bg;
     uint8_t pattern[AKBASIC_SPRITE_PATTERN_BYTES];
+    size_t prefixlen = 0;
+    int handle = 0;
+    int cmp = 0;
 
     if ( arg->leaftype == AKBASIC_LEAF_IDENTIFIER_INT &&
 	 akbasic_leaf_first_subscript(arg) == NULL ) {
@@ -428,11 +432,17 @@ static akerr_ErrorContext *define_from_leaf(akbasic_Runtime *obj, akbasic_ASTLea
     FAIL_ZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
 		     "SPRSAV expected a sprite number, an image path, a saved shape or an integer array");
 
-    if ( strncmp(value->stringval, SHAPE_PREFIX, strlen(SHAPE_PREFIX)) == 0 ) {
-	int handle = atoi(value->stringval + strlen(SHAPE_PREFIX));
-
+    PASS(errctx, aksl_strlen(SHAPE_PREFIX, &prefixlen));
+    PASS(errctx, aksl_strncmp(value->stringval, SHAPE_PREFIX, prefixlen, &cmp));
+    if ( cmp == 0 ) {
 	FAIL_ZERO_RETURN(errctx, (obj->sprites->define_shape != NULL), AKBASIC_ERR_DEVICE,
 			 "This sprite device cannot take a saved shape");
+	/*
+	 * aksl_atoi refuses a slot number that is not one, where atoi(3) answered
+	 * a silent 0 -- so `SPRSAV "SHAPE:", 1` is now told what is wrong with it
+	 * rather than being handed shape 0.
+	 */
+	PASS(errctx, aksl_atoi(value->stringval + prefixlen, &handle));
 	PASS(errctx, obj->sprites->define_shape(obj->sprites, index + 1, handle));
 	SUCCEED_RETURN(errctx);
     }
@@ -779,8 +789,9 @@ akerr_ErrorContext *akbasic_cmd_solid(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
 	    if ( !obj->sprite_state.solids[i].active ) {
 		continue;
 	    }
-	    memset(&obj->sprite_state.solids[i], 0, sizeof(obj->sprite_state.solids[i]));
 	    /* PASS rather than CATCH: this is a loop. */
+	    PASS(errctx, aksl_memset(&obj->sprite_state.solids[i], 0,
+				     sizeof(obj->sprite_state.solids[i])));
 	    PASS(errctx, obj->sprites->solid(obj->sprites, i + 1, false, 0.0, 0.0, 0.0, 0.0));
 	}
 	SUCCEED_RETURN(errctx);
@@ -792,7 +803,7 @@ akerr_ErrorContext *akbasic_cmd_solid(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
     solid = &obj->sprite_state.solids[id - 1];
 
     if ( count == 1 ) {
-	memset(solid, 0, sizeof(*solid));
+	PASS(errctx, aksl_memset(solid, 0, sizeof(*solid)));
 	PASS(errctx, obj->sprites->solid(obj->sprites, id, false, 0.0, 0.0, 0.0, 0.0));
 	SUCCEED_RETURN(errctx);
     }

src/runtime_struct.c

@@ -28,6 +28,7 @@
 #include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/error.h>
 #include <akbasic/runtime.h>
@@ -194,7 +195,11 @@ akerr_ErrorContext *akbasic_struct_to_string(akbasic_Runtime *obj, int typeindex
     PREPARE_ERROR(errctx);
     char rendered[AKBASIC_MAX_STRING_LENGTH];
     akbasic_StructType *type = NULL;
+    const char *separator = NULL;
     size_t used = 0;
+    size_t seplen = 0;
+    size_t namelen = 0;
+    size_t renderedlen = 0;
     int written = 0;
     int i = 0;
 
@@ -204,6 +209,20 @@ akerr_ErrorContext *akbasic_struct_to_string(akbasic_Runtime *obj, int typeindex
 		     AKBASIC_ERR_BOUNDS, "Structure type index %d is out of range", typeindex);
     type = &obj->structtypes.types[typeindex];
 
+    /*
+     * These two stay on raw snprintf on purpose, and are two of the six such
+     * sites left in src/. Both want truncation as an *answer*: `dest` and `len`
+     * come from the caller, this renders a value for display, and a name too long
+     * for the buffer should print short rather than fail the whole PRINT. The
+     * second one reads the return value to detect it -- on overflow `used` lands
+     * past `len`, which is exactly what makes the field loop below and the
+     * closing ")" both skip.
+     *
+     * aksl_snprintf treats truncation as AKERR_OUTOFBOUNDS and its `count` is 0
+     * on that path, so it can express neither the tolerance nor the detection.
+     * libakstdlib #34 is the issue that would give `count` the required length
+     * back; until it lands there is nothing to convert these to.
+     */
     if ( depth >= AKBASIC_MAX_STRUCT_DEPTH ) {
 	snprintf(dest, len, "%s(...)", type->name);
 	SUCCEED_RETURN(errctx);
@@ -222,7 +241,7 @@ akerr_ErrorContext *akbasic_struct_to_string(akbasic_Runtime *obj, int typeindex
 	    break;
 	case AKBASIC_FIELD_POINTER:
 	    if ( slot->structbase == NULL ) {
-		snprintf(rendered, sizeof(rendered), "NOTHING");
+		PASS(errctx, aksl_snprintf(&written, rendered, sizeof(rendered), "NOTHING"));
 	    } else {
 		PASS(errctx, akbasic_struct_to_string(obj, slot->structtype, slot->structbase,
 						      depth + 1, rendered, sizeof(rendered)));
@@ -232,15 +251,24 @@ akerr_ErrorContext *akbasic_struct_to_string(akbasic_Runtime *obj, int typeindex
 	    PASS(errctx, akbasic_value_to_string(slot, rendered, sizeof(rendered)));
 	    break;
 	}
-	written = snprintf(dest + used, len - used, "%s%s=%s",
-			   (i == 0 ? "" : ", "), field->name, rendered);
-	if ( written < 0 || (size_t)written >= len - used ) {
+	separator = (i == 0 ? "" : ", ");
+	PASS(errctx, aksl_strlen(separator, &seplen));
+	PASS(errctx, aksl_strlen(field->name, &namelen));
+	PASS(errctx, aksl_strlen(rendered, &renderedlen));
+	/*
+	 * A render that does not fit ends the list rather than failing it, so the
+	 * fit is decided here -- aksl_snprintf treats truncation as an error, and
+	 * the one byte counted beyond the three lengths is the `=`.
+	 */
+	if ( used + seplen + namelen + 1 + renderedlen >= len ) {
 	    break;
 	}
+	PASS(errctx, aksl_snprintf(&written, dest + used, len - used, "%s%s=%s",
+				   separator, field->name, rendered));
 	used += (size_t)written;
     }
     if ( used + 1 < len ) {
-	snprintf(dest + used, len - used, ")");
+	PASS(errctx, aksl_snprintf(&written, dest + used, len - used, ")"));
     }
     SUCCEED_RETURN(errctx);
 }

src/runtime_structure.c

@@ -173,6 +173,7 @@ akerr_ErrorContext *akbasic_cmd_begin(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
 akerr_ErrorContext *akbasic_cmd_bend(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    bool waiting = false;
 
     (void)expr; (void)lval; (void)rval;
     FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
@@ -182,7 +183,8 @@ akerr_ErrorContext *akbasic_cmd_bend(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
      * to do, or it is the BEND a skipped block was skipping to, in which case
      * stopping the skip is the whole job.
      */
-    if ( akbasic_environment_is_waiting_for(obj->environment, "BEND") ) {
+    PASS(errctx, akbasic_environment_is_waiting_for(obj->environment, "BEND", &waiting));
+    if ( waiting ) {
 	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "BEND"));
     }
     SUCCEED_TRUE(obj, dest);

src/runtime_trap.c

@@ -16,10 +16,9 @@
  */
 
 #include <inttypes.h>
-#include <stdio.h>
-#include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/args.h>
 #include <akbasic/error.h>
@@ -107,6 +106,8 @@ akerr_ErrorContext *akbasic_cmd_resume(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
     akbasic_Variable *variable = NULL;
     int64_t zerosubscript[1] = { 0 };
     int64_t resumeline = 0;
+    int cmp = 0;
+    bool isnext = false;
 
     (void)lval; (void)rval;
     FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
@@ -124,6 +125,10 @@ akerr_ErrorContext *akbasic_cmd_resume(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
     resumeline = value->intval;
 
     target = (expr != NULL ? expr->right : NULL);
+    if ( target != NULL && target->leaftype == AKBASIC_LEAF_COMMAND ) {
+	PASS(errctx, aksl_strcmp(target->identifier, "NEXT", &cmp));
+	isnext = (cmp == 0);
+    }
     if ( target == NULL ) {
 	/*
 	 * Bare RESUME retries the line that failed. That is a loop unless the
@@ -131,8 +136,7 @@ akerr_ErrorContext *akbasic_cmd_resume(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
 	 * is exactly what the verb is for.
 	 */
 	obj->environment->parent->nextline = resumeline;
-    } else if ( target->leaftype == AKBASIC_LEAF_COMMAND &&
-		strcmp(target->identifier, "NEXT") == 0 ) {
+    } else if ( isnext ) {
 	/* RESUME NEXT carries on at the line after the one that failed. */
 	obj->environment->parent->nextline = resumeline + 1;
     } else {
@@ -182,8 +186,8 @@ akerr_ErrorContext *akbasic_fn_err(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
      * that ever decides otherwise.
      */
     name = akerr_name_for_status((int)status, NULL);
-    snprintf(out->stringval, sizeof(out->stringval), "%s",
-	     (name != NULL ? name : "Unknown Error"));
+    PASS(errctx, aksl_strcpy(out->stringval, sizeof(out->stringval),
+			     (name != NULL ? name : "Unknown Error")));
     *dest = out;
     SUCCEED_RETURN(errctx);
 }

src/runtime_ui.c

@@ -19,9 +19,9 @@
  */
 
 #include <inttypes.h>
-#include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/args.h>
 #include <akbasic/error.h>
@@ -153,8 +153,7 @@ static akerr_ErrorContext *nth_string(akbasic_Runtime *obj, akbasic_ASTLeaf *exp
     PASS(errctx, akbasic_runtime_evaluate(obj, arg, &value));
     FAIL_ZERO_RETURN(errctx, (value->valuetype == AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
 		     "%s expected a string in argument %d", verb, n + 1);
-    strncpy(dest, value->stringval, len - 1);
-    dest[len - 1] = '\0';
+    PASS(errctx, aksl_strcpy(dest, len, value->stringval));
     SUCCEED_RETURN(errctx);
 }
 
@@ -259,8 +258,7 @@ static akerr_ErrorContext *target_variable(akbasic_Runtime *obj, akbasic_ASTLeaf
     PASS(errctx, akbasic_environment_get(obj->environment, arg->identifier, dest));
     FAIL_ZERO_RETURN(errctx, (*dest != NULL), AKBASIC_ERR_UNDEFINED,
 		     "GETMENU could not reach the variable %s", arg->identifier);
-    strncpy(name, arg->identifier, len - 1);
-    name[len - 1] = '\0';
+    PASS(errctx, aksl_strcpy(name, len, arg->identifier));
     SUCCEED_RETURN(errctx);
 }
 
@@ -309,8 +307,7 @@ akerr_ErrorContext *akbasic_cmd_getmenu(akbasic_Runtime *obj, akbasic_ASTLeaf *e
      */
     obj->ui_state.waiting = true;
     obj->ui_state.waitmenu = slot;
-    strncpy(obj->ui_state.variable, name, sizeof(obj->ui_state.variable) - 1);
-    obj->ui_state.variable[sizeof(obj->ui_state.variable) - 1] = '\0';
+    PASS(errctx, aksl_strcpy(obj->ui_state.variable, sizeof(obj->ui_state.variable), name));
     SUCCEED_TRUE(obj, dest);
     SUCCEED_RETURN(errctx);
 }
@@ -487,7 +484,7 @@ akerr_ErrorContext *akbasic_ui_state_init(akbasic_UiState *obj)
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER,
 		     "NULL argument in ui_state_init");
-    memset(obj, 0, sizeof(*obj));
+    PASS(errctx, aksl_memset(obj, 0, sizeof(*obj)));
     SUCCEED_RETURN(errctx);
 }
 

src/scanner.c

@@ -23,30 +23,71 @@ akerr_ErrorContext *akbasic_scanner_zero(akbasic_Runtime *obj)
     obj->current = 0;
     obj->start = 0;
     obj->hasError = false;
+    obj->tokentype = AKBASIC_TOK_UNDEFINED;
     SUCCEED_RETURN(errctx);
 }
 
-static bool is_at_end(akbasic_Runtime *obj)
+/**
+ * @brief Is the cursor past the end of the line?
+ *
+ * The answer leaves through @p dest rather than the return value because
+ * measuring the line can fail, and a `bool` has nowhere to put that. Same shape
+ * as symtab.c's `probe`, and for the same reason. See libakstdlib #38.
+ */
+static akerr_ErrorContext *is_at_end(akbasic_Runtime *obj, bool *dest)
 {
-    return (obj->current >= (int)strlen(obj->line));
+    PREPARE_ERROR(errctx);
+    size_t linelen = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in is_at_end");
+    PASS(errctx, aksl_strlen(obj->line, &linelen));
+    *dest = (obj->current >= (int)linelen);
+    SUCCEED_RETURN(errctx);
 }
 
-static bool peek(akbasic_Runtime *obj, char *dest)
+/**
+ * @brief The character under the cursor.
+ * @param[out] dest The character. Untouched when there is none.
+ * @param[out] got  Whether there was one. The old `bool` return.
+ */
+static akerr_ErrorContext *peek(akbasic_Runtime *obj, char *dest, bool *got)
 {
-    if ( is_at_end(obj) ) {
-	return false;
+    PREPARE_ERROR(errctx);
+    bool atend = false;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL && got != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in peek");
+    PASS(errctx, is_at_end(obj, &atend));
+    if ( atend ) {
+	*got = false;
+	SUCCEED_RETURN(errctx);
     }
     *dest = obj->line[obj->current];
-    return true;
+    *got = true;
+    SUCCEED_RETURN(errctx);
 }
 
-static bool peek_next(akbasic_Runtime *obj, char *dest)
+/**
+ * @brief The character one past the cursor.
+ * @param[out] dest The character. Untouched when there is none.
+ * @param[out] got  Whether there was one. The old `bool` return.
+ */
+static akerr_ErrorContext *peek_next(akbasic_Runtime *obj, char *dest, bool *got)
 {
-    if ( (obj->current + 1) >= (int)strlen(obj->line) ) {
-	return false;
+    PREPARE_ERROR(errctx);
+    size_t linelen = 0;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL && got != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in peek_next");
+    PASS(errctx, aksl_strlen(obj->line, &linelen));
+    if ( (obj->current + 1) >= (int)linelen ) {
+	*got = false;
+	SUCCEED_RETURN(errctx);
     }
     *dest = obj->line[obj->current + 1];
-    return true;
+    *got = true;
+    SUCCEED_RETURN(errctx);
 }
 
 /*
@@ -58,9 +99,12 @@ static bool peek_next(akbasic_Runtime *obj, char *dest)
 static akerr_ErrorContext *get_lexeme(akbasic_Runtime *obj, char *dest, size_t len)
 {
     PREPARE_ERROR(errctx);
-    int linelen = (int)strlen(obj->line);
+    size_t measured = 0;
+    int linelen = 0;
     int span = 0;
 
+    PASS(errctx, aksl_strlen(obj->line, &measured));
+    linelen = (int)measured;
     if ( obj->current == linelen ) {
 	span = linelen - obj->start;
     } else if ( obj->start == obj->current ) {
@@ -74,7 +118,7 @@ static akerr_ErrorContext *get_lexeme(akbasic_Runtime *obj, char *dest, size_t l
     }
     FAIL_ZERO_RETURN(errctx, (span >= 0 && (size_t)span < len), AKBASIC_ERR_BOUNDS,
 		     "Lexeme of %d characters exceeds the %zu character limit", span, len - 1);
-    memcpy(dest, obj->line + obj->start, (size_t)span);
+    PASS(errctx, aksl_memcpy(dest, obj->line + obj->start, (size_t)span));
     dest[span] = '\0';
     SUCCEED_RETURN(errctx);
 }
@@ -83,26 +127,39 @@ static akerr_ErrorContext *add_token(akbasic_Runtime *obj, akbasic_TokenType tok
 {
     PREPARE_ERROR(errctx);
     akbasic_Environment *env = obj->environment;
+    size_t lexemelen = 0;
 
     FAIL_ZERO_RETURN(errctx, (env->nexttoken < AKBASIC_MAX_TOKENS), AKBASIC_ERR_BOUNDS,
 		     "Line %" PRId64 " has more than %d tokens",
 		     env->lineno, AKBASIC_MAX_TOKENS);
-    FAIL_ZERO_RETURN(errctx, (strlen(lexeme) < AKBASIC_MAX_LINE_LENGTH), AKBASIC_ERR_BOUNDS,
+    PASS(errctx, aksl_strlen(lexeme, &lexemelen));
+    FAIL_ZERO_RETURN(errctx, (lexemelen < AKBASIC_MAX_LINE_LENGTH), AKBASIC_ERR_BOUNDS,
 		     "Token lexeme exceeds the %d character limit", AKBASIC_MAX_LINE_LENGTH - 1);
     env->tokens[env->nexttoken].tokentype = token;
     env->tokens[env->nexttoken].lineno = env->lineno;
-    strncpy(env->tokens[env->nexttoken].lexeme, lexeme, AKBASIC_MAX_LINE_LENGTH - 1);
-    env->tokens[env->nexttoken].lexeme[AKBASIC_MAX_LINE_LENGTH - 1] = '\0';
+    PASS(errctx, aksl_strcpy(env->tokens[env->nexttoken].lexeme,
+			     sizeof(env->tokens[env->nexttoken].lexeme), lexeme));
     env->nexttoken += 1;
     SUCCEED_RETURN(errctx);
 }
 
-/* Consume one more character when it matches, choosing between two token types. */
-static bool match_next_char(akbasic_Runtime *obj, char cm, akbasic_TokenType truetype, akbasic_TokenType falsetype)
+/**
+ * @brief Consume one more character when it matches, choosing between two token types.
+ * @param[out] matched Whether the character was consumed. The old `bool` return.
+ *
+ * On the chain below `peek`, so it reports the same way. See libakstdlib #38.
+ */
+static akerr_ErrorContext *match_next_char(akbasic_Runtime *obj, char cm, akbasic_TokenType truetype,
+					   akbasic_TokenType falsetype, bool *matched)
 {
+    PREPARE_ERROR(errctx);
     char nc = '\0';
+    bool got = false;
 
-    if ( !peek(obj, &nc) ) {
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && matched != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in match_next_char");
+    PASS(errctx, peek(obj, &nc, &got));
+    if ( !got ) {
 	/*
 	 * Nothing left to peek at, so the operator is whatever it is on its
 	 * own. The reference returns here *without* setting a type
@@ -112,24 +169,34 @@ static bool match_next_char(akbasic_Runtime *obj, char cm, akbasic_TokenType tru
 	 * TODO.md section 6 item 14.
 	 */
 	obj->tokentype = falsetype;
-	return false;
+	*matched = false;
+	SUCCEED_RETURN(errctx);
     }
     if ( nc == cm ) {
 	obj->current += 1;
 	obj->tokentype = truetype;
-	return true;
+	*matched = true;
+	SUCCEED_RETURN(errctx);
     }
     obj->tokentype = falsetype;
-    return false;
+    *matched = false;
+    SUCCEED_RETURN(errctx);
 }
 
 static akerr_ErrorContext *match_string(akbasic_Runtime *obj)
 {
     PREPARE_ERROR(errctx);
     char c = '\0';
+    bool atend = false;
+    bool got = false;
 
-    while ( !is_at_end(obj) ) {
-	if ( !peek(obj, &c) ) {
+    for ( ;; ) {
+	PASS(errctx, is_at_end(obj, &atend));
+	if ( atend ) {
+	    break;
+	}
+	PASS(errctx, peek(obj, &c, &got));
+	if ( !got ) {
 	    PASS(errctx, akbasic_runtime_error(obj, AKBASIC_ERRCLASS_PARSE,
 					       "UNTERMINATED STRING LITERAL\n"));
 	    obj->hasError = true;
@@ -154,12 +221,19 @@ static akerr_ErrorContext *match_number(akbasic_Runtime *obj)
     int64_t lineno = 0;
     long long converted = 0;
     bool hex = false;
+    bool atend = false;
+    bool got = false;
 
     obj->tokentype = AKBASIC_TOK_LITERAL_INT;
-    while ( !is_at_end(obj) ) {
-	(void)peek(obj, &c);
+    for ( ;; ) {
+	PASS(errctx, is_at_end(obj, &atend));
+	if ( atend ) {
+	    break;
+	}
+	PASS(errctx, peek(obj, &c, &got));
 	if ( c == '.' ) {
-	    if ( !peek_next(obj, &nc) || !isdigit((unsigned char)nc) ) {
+	    PASS(errctx, peek_next(obj, &nc, &got));
+	    if ( !got || !isdigit((unsigned char)nc) ) {
 		PASS(errctx, akbasic_runtime_error(obj, AKBASIC_ERRCLASS_PARSE,
 						   "INVALID FLOATING POINT LITERAL\n"));
 		obj->hasError = true;
@@ -200,13 +274,17 @@ static akerr_ErrorContext *match_number(akbasic_Runtime *obj)
 	} CLEANUP {
 	} PROCESS(errctx) {
 	} HANDLE_DEFAULT(errctx) {
-	    char message[AKBASIC_MAX_LINE_LENGTH + 32];
-	    snprintf(message, sizeof(message), "INTEGER CONVERSION ON '%s'", lexeme);
+	    char message[AKBASIC_MAX_LINE_LENGTH + 32] = "INTEGER CONVERSION";
+	    int written = 0;
 	    /*
-	     * Reporting can itself fail if the sink is broken. Nothing useful
-	     * remains to be done about that here, so record the flag and let the
-	     * next operation surface it.
+	     * Reporting can itself fail if the sink is broken, and so can
+	     * formatting the message. Neither leaves anything useful to do here --
+	     * this block is already handling an error -- so both are ignored, the
+	     * message keeps the initialiser above if the format fails, and the flag
+	     * lets the next operation surface it.
 	     */
+	    IGNORE(aksl_snprintf(&written, message, sizeof(message),
+				 "INTEGER CONVERSION ON '%s'", lexeme));
 	    IGNORE(akbasic_runtime_error(obj, AKBASIC_ERRCLASS_PARSE, message));
 	    obj->hasError = true;
 	} FINISH(errctx, false);
@@ -230,10 +308,16 @@ static akerr_ErrorContext *match_identifier(akbasic_Runtime *obj)
     bool userfunction = false;
     char c = '\0';
     size_t used = 0;
+    bool atend = false;
+    bool got = false;
 
     obj->tokentype = AKBASIC_TOK_IDENTIFIER;
-    while ( !is_at_end(obj) ) {
-	(void)peek(obj, &c);
+    for ( ;; ) {
+	PASS(errctx, is_at_end(obj, &atend));
+	if ( atend ) {
+	    break;
+	}
+	PASS(errctx, peek(obj, &c, &got));
 	if ( isdigit((unsigned char)c) || isalpha((unsigned char)c) ) {
 	    obj->current += 1;
 	    continue;
@@ -270,9 +354,8 @@ static akerr_ErrorContext *match_identifier(akbasic_Runtime *obj)
      * in variable name" branch below is dead code, and `PRINT$ = 1` is quietly
      * accepted as an ordinary string variable. TODO.md section 6 item 16.
      */
-    strncpy(basename, lexeme, sizeof(basename) - 1);
-    basename[sizeof(basename) - 1] = '\0';
-    used = strlen(basename);
+    PASS(errctx, aksl_strcpy(basename, sizeof(basename), lexeme));
+    PASS(errctx, aksl_strlen(basename, &used));
     if ( obj->tokentype != AKBASIC_TOK_IDENTIFIER && used > 0 ) {
 	basename[used - 1] = '\0';
     }
@@ -311,19 +394,32 @@ akerr_ErrorContext *akbasic_scanner_scan(akbasic_Runtime *obj, const char *line,
     char lexeme[AKBASIC_MAX_LINE_LENGTH];
     char c = '\0';
     bool done = false;
+    bool atend = false;
+    bool matched = false;
+    size_t linelen = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in scan");
     FAIL_ZERO_RETURN(errctx, (line != NULL), AKERR_NULLPOINTER, "NULL line in scan");
-    FAIL_ZERO_RETURN(errctx, (strlen(line) < AKBASIC_MAX_LINE_LENGTH), AKBASIC_ERR_BOUNDS,
+    PASS(errctx, aksl_strlen(line, &linelen));
+    FAIL_ZERO_RETURN(errctx, (linelen < AKBASIC_MAX_LINE_LENGTH), AKBASIC_ERR_BOUNDS,
 		     "Source line of %zu characters exceeds the %d character limit",
-		     strlen(line), AKBASIC_MAX_LINE_LENGTH - 1);
+		     linelen, AKBASIC_MAX_LINE_LENGTH - 1);
 
-    strncpy(obj->line, line, AKBASIC_MAX_LINE_LENGTH - 1);
-    obj->line[AKBASIC_MAX_LINE_LENGTH - 1] = '\0';
+    PASS(errctx, aksl_strcpy(obj->line, sizeof(obj->line), line));
     PASS(errctx, akbasic_environment_zero_parser(obj->environment));
     obj->current = 0;
     obj->start = 0;
     obj->hasError = false;
+    /*
+     * The `REM` early-exit below leaves `tokentype` holding AKBASIC_TOK_REM,
+     * and the loop's post-switch check reads it before the first character of
+     * the *next* line has assigned anything. A line whose first character
+     * carries no token of its own -- leading whitespace -- then re-triggered
+     * the REM break and scanned to nothing: every indented line after a REM
+     * was silently skipped. A numbered program never saw it, because the line
+     * number is the first token and overwrites the leftover.
+     */
+    obj->tokentype = AKBASIC_TOK_UNDEFINED;
     /*
      * Cleared here rather than by each caller, so the flag always describes the
      * line this call just scanned. It used to be cleared only in
@@ -333,7 +429,11 @@ akerr_ErrorContext *akbasic_scanner_scan(akbasic_Runtime *obj, const char *line,
      */
     obj->hadlinenumber = false;
 
-    while ( !is_at_end(obj) && !done ) {
+    for ( ;; ) {
+	PASS(errctx, is_at_end(obj, &atend));
+	if ( atend || done ) {
+	    break;
+	}
 	c = obj->line[obj->current];
 	obj->current += 1;
 
@@ -350,7 +450,7 @@ akerr_ErrorContext *akbasic_scanner_scan(akbasic_Runtime *obj, const char *line,
 	 * no spelling this makes ambiguous.
 	 */
 	case '-':
-	    (void)match_next_char(obj, '>', AKBASIC_TOK_ARROW, AKBASIC_TOK_MINUS);
+	    PASS(errctx, match_next_char(obj, '>', AKBASIC_TOK_ARROW, AKBASIC_TOK_MINUS, &matched));
 	    break;
 	case '/': obj->tokentype = AKBASIC_TOK_LEFT_SLASH;		break;
 	case '*': obj->tokentype = AKBASIC_TOK_STAR;			break;
@@ -373,15 +473,19 @@ akerr_ErrorContext *akbasic_scanner_scan(akbasic_Runtime *obj, const char *line,
 	case '[': obj->tokentype = AKBASIC_TOK_LEFT_SQUAREBRACKET;	break;
 	case ']': obj->tokentype = AKBASIC_TOK_RIGHT_SQUAREBRACKET;	break;
 	case '=':
-	    (void)match_next_char(obj, '=', AKBASIC_TOK_EQUAL, AKBASIC_TOK_ASSIGNMENT);
+	    PASS(errctx, match_next_char(obj, '=', AKBASIC_TOK_EQUAL, AKBASIC_TOK_ASSIGNMENT, &matched));
 	    break;
 	case '<':
-	    if ( !match_next_char(obj, '=', AKBASIC_TOK_LESS_THAN_EQUAL, AKBASIC_TOK_LESS_THAN) ) {
-		(void)match_next_char(obj, '>', AKBASIC_TOK_NOT_EQUAL, AKBASIC_TOK_LESS_THAN);
+	    PASS(errctx, match_next_char(obj, '=', AKBASIC_TOK_LESS_THAN_EQUAL,
+					 AKBASIC_TOK_LESS_THAN, &matched));
+	    if ( !matched ) {
+		PASS(errctx, match_next_char(obj, '>', AKBASIC_TOK_NOT_EQUAL,
+					     AKBASIC_TOK_LESS_THAN, &matched));
 	    }
 	    break;
 	case '>':
-	    (void)match_next_char(obj, '=', AKBASIC_TOK_GREATER_THAN_EQUAL, AKBASIC_TOK_GREATER_THAN);
+	    PASS(errctx, match_next_char(obj, '=', AKBASIC_TOK_GREATER_THAN_EQUAL,
+					 AKBASIC_TOK_GREATER_THAN, &matched));
 	    break;
 	case '"':
 	    obj->start = obj->current;
@@ -402,7 +506,10 @@ akerr_ErrorContext *akbasic_scanner_scan(akbasic_Runtime *obj, const char *line,
 		PASS(errctx, match_identifier(obj));
 	    } else {
 		char message[AKBASIC_MAX_LINE_LENGTH];
-		snprintf(message, sizeof(message), "UNKNOWN TOKEN %c\n", c);
+		int written = 0;
+
+		PASS(errctx, aksl_snprintf(&written, message, sizeof(message),
+					   "UNKNOWN TOKEN %c\n", c));
 		PASS(errctx, akbasic_runtime_error(obj, AKBASIC_ERRCLASS_PARSE, message));
 		obj->hasError = true;
 		obj->start = obj->current;
@@ -426,10 +533,13 @@ akerr_ErrorContext *akbasic_scanner_scan(akbasic_Runtime *obj, const char *line,
 		 * stores *that* as the program text.
 		 */
 		int skip = obj->current;
+		size_t tail = 0;
+
 		while ( obj->line[skip] == ' ' ) {
 		    skip += 1;
 		}
-		memmove(obj->line, obj->line + skip, strlen(obj->line + skip) + 1);
+		PASS(errctx, aksl_strlen(obj->line + skip, &tail));
+		PASS(errctx, aksl_memmove(obj->line, obj->line + skip, tail + 1));
 		obj->current = 0;
 	    } else {
 		PASS(errctx, get_lexeme(obj, lexeme, sizeof(lexeme)));
@@ -445,10 +555,10 @@ akerr_ErrorContext *akbasic_scanner_scan(akbasic_Runtime *obj, const char *line,
     }
 
     if ( dest != NULL ) {
-	FAIL_ZERO_RETURN(errctx, (strlen(obj->line) < len), AKBASIC_ERR_BOUNDS,
+	PASS(errctx, aksl_strlen(obj->line, &linelen));
+	FAIL_ZERO_RETURN(errctx, (linelen < len), AKBASIC_ERR_BOUNDS,
 			 "Scanned line does not fit the caller's buffer");
-	strncpy(dest, obj->line, len - 1);
-	dest[len - 1] = '\0';
+	PASS(errctx, aksl_strcpy(dest, len, obj->line));
     }
     SUCCEED_RETURN(errctx);
 }

src/sink_akgl.c

@@ -15,9 +15,8 @@
 
 #include <ctype.h>
 #include <stdio.h>
-#include <string.h>
-
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akgl/controller.h>
 #include <akgl/draw.h>
@@ -32,15 +31,24 @@
 /** @brief Bytes per row, including the terminator. */
 #define SINK_MAX_COLUMNS	256
 
-/** @brief Scroll the grid up by one row, dropping the top one. */
-static void scroll(akbasic_AkglSink *state)
+/**
+ * @brief Scroll the grid up by one row, dropping the top one.
+ *
+ * Returns a context rather than `void` because the row moves can fail and there
+ * was nowhere to say so. Everything on this chain -- scroll, newline,
+ * putchar_at, echo_line, edit_key -- returns one for the same reason, and the
+ * chain already ends at sink_write, sink_writeln and sink_readline, which
+ * returned one all along. See libakstdlib #38.
+ */
+static akerr_ErrorContext *scroll(akbasic_AkglSink *state)
 {
+    PREPARE_ERROR(errctx);
     int row = 0;
 
     for ( row = 0; row < SINK_MAX_ROWS - 1; row++ ) {
-	memcpy(state->text[row], state->text[row + 1], SINK_MAX_COLUMNS);
+	PASS(errctx, aksl_memcpy(state->text[row], state->text[row + 1], SINK_MAX_COLUMNS));
     }
-    memset(state->text[SINK_MAX_ROWS - 1], 0, SINK_MAX_COLUMNS);
+    PASS(errctx, aksl_memset(state->text[SINK_MAX_ROWS - 1], 0, SINK_MAX_COLUMNS));
     if ( state->cursorrow > 0 ) {
 	state->cursorrow -= 1;
     }
@@ -59,13 +67,16 @@ static void scroll(akbasic_AkglSink *state)
 }
 
 /** @brief Move to the start of the next row, scrolling if that runs off the end. */
-static void newline(akbasic_AkglSink *state)
+static akerr_ErrorContext *newline(akbasic_AkglSink *state)
 {
+    PREPARE_ERROR(errctx);
+
     state->cursorcol = 0;
     state->cursorrow += 1;
     if ( state->cursorrow >= state->rows || state->cursorrow >= SINK_MAX_ROWS ) {
-	scroll(state);
+	PASS(errctx, scroll(state));
     }
+    SUCCEED_RETURN(errctx);
 }
 
 /**
@@ -89,16 +100,17 @@ static void newline(akbasic_AkglSink *state)
  * cleared between rows, so the gap holds the tail of some longer row that used
  * to be here.
  */
-static void putchar_at(akbasic_AkglSink *state, char c)
+static akerr_ErrorContext *putchar_at(akbasic_AkglSink *state, char c)
 {
+    PREPARE_ERROR(errctx);
     int col = 0;
 
     if ( c == '\n' ) {
-	newline(state);
-	return;
+	PASS(errctx, newline(state));
+	SUCCEED_RETURN(errctx);
     }
     if ( state->cursorcol >= state->columns || state->cursorcol >= SINK_MAX_COLUMNS - 1 ) {
-	newline(state);
+	PASS(errctx, newline(state));
     }
     for ( col = 0; col < state->cursorcol; col++ ) {
 	if ( state->text[state->cursorrow][col] == '\0' ) {
@@ -111,6 +123,7 @@ static void putchar_at(akbasic_AkglSink *state, char c)
     state->text[state->cursorrow][state->cursorcol] = c;
     state->cursorcol += 1;
     state->text[state->cursorrow][state->cursorcol] = '\0';
+    SUCCEED_RETURN(errctx);
 }
 
 static akerr_ErrorContext *sink_write(akbasic_TextSink *self, const char *text)
@@ -125,7 +138,7 @@ static akerr_ErrorContext *sink_write(akbasic_TextSink *self, const char *text)
     FAIL_ZERO_RETURN(errctx, (state != NULL), AKERR_NULLPOINTER,
 		     "akgl sink has no state");
     for ( i = 0; text[i] != '\0'; i++ ) {
-	putchar_at(state, text[i]);
+	PASS(errctx, putchar_at(state, text[i]));
     }
     SUCCEED_RETURN(errctx);
 }
@@ -137,7 +150,7 @@ static akerr_ErrorContext *sink_writeln(akbasic_TextSink *self, const char *text
 
     PASS(errctx, sink_write(self, text));
     state = (akbasic_AkglSink *)self->self;
-    newline(state);
+    PASS(errctx, newline(state));
     SUCCEED_RETURN(errctx);
 }
 
@@ -151,8 +164,9 @@ static akerr_ErrorContext *sink_writeln(akbasic_TextSink *self, const char *text
  * memory, and the host draws it when it draws its frame -- so the cost is a
  * couple of memcpy-sized loops per keystroke.
  */
-static void echo_line(akbasic_AkglSink *state)
+static akerr_ErrorContext *echo_line(akbasic_AkglSink *state)
 {
+    PREPARE_ERROR(errctx);
     int i = 0;
     int erasedto = 0;
     int endedat = 0;
@@ -160,14 +174,14 @@ static void echo_line(akbasic_AkglSink *state)
     state->cursorrow = state->editrow;
     state->cursorcol = state->editcol;
     for ( i = 0; i < state->echolen; i++ ) {
-	putchar_at(state, ' ');
+	PASS(errctx, putchar_at(state, ' '));
     }
     erasedto = state->cursorrow;
 
     state->cursorrow = state->editrow;
     state->cursorcol = state->editcol;
     for ( i = 0; i < state->editlen; i++ ) {
-	putchar_at(state, state->editline[i]);
+	PASS(errctx, putchar_at(state, state->editline[i]));
     }
     endedat = state->cursorrow;
     state->echolen = state->editlen;
@@ -186,6 +200,7 @@ static void echo_line(akbasic_AkglSink *state)
     for ( i = endedat + 1; i <= erasedto && i < SINK_MAX_ROWS; i++ ) {
 	state->text[i][0] = '\0';
     }
+    SUCCEED_RETURN(errctx);
 }
 
 /** @brief Append one byte to the line being typed, if there is room for it. */
@@ -215,14 +230,15 @@ static void edit_append(akbasic_AkglSink *state, char c)
  * Backspace and Escape are keys rather than characters and several of them
  * compose to text SDL would otherwise hand straight through.
  */
-static void edit_key(akbasic_AkglSink *state, const akgl_Keystroke *key, bool *submitted)
+static akerr_ErrorContext *edit_key(akbasic_AkglSink *state, const akgl_Keystroke *key, bool *submitted)
 {
+    PREPARE_ERROR(errctx);
     size_t i = 0;
 
     if ( key->key == SDLK_RETURN || key->key == SDLK_KP_ENTER ||
 	 key->key == '\r' || key->key == '\n' ) {
 	*submitted = true;
-	return;
+	SUCCEED_RETURN(errctx);
     }
     if ( key->key == SDLK_BACKSPACE || key->key == '\b' || key->key == 0x7f ) {
 	if ( state->editlen > 0 ) {
@@ -235,15 +251,15 @@ static void edit_key(akbasic_AkglSink *state, const akgl_Keystroke *key, bool *s
 	     */
 	    state->editlen -= 1;
 	    state->editline[state->editlen] = '\0';
-	    echo_line(state);
+	    PASS(errctx, echo_line(state));
 	}
-	return;
+	SUCCEED_RETURN(errctx);
     }
     if ( key->key == SDLK_ESCAPE || key->key == 0x1b ) {
 	state->editlen = 0;
 	state->editline[0] = '\0';
-	echo_line(state);
-	return;
+	PASS(errctx, echo_line(state));
+	SUCCEED_RETURN(errctx);
     }
 
     if ( key->text[0] != '\0' ) {
@@ -257,8 +273,8 @@ static void edit_key(akbasic_AkglSink *state, const akgl_Keystroke *key, bool *s
 		edit_append(state, key->text[i]);
 	    }
 	}
-	echo_line(state);
-	return;
+	PASS(errctx, echo_line(state));
+	SUCCEED_RETURN(errctx);
     }
 
     /*
@@ -277,14 +293,15 @@ static void edit_key(akbasic_AkglSink *state, const akgl_Keystroke *key, bool *s
      */
     if ( key->key >= 0x20 && key->key < 0x7f ) {
 	edit_append(state, (char)toupper((unsigned char)key->key));
-	echo_line(state);
-	return;
+	PASS(errctx, echo_line(state));
+	SUCCEED_RETURN(errctx);
     }
 
     /*
      * Neither: a cursor key, a function key or a bare modifier. Not an editing
      * command here -- a script's own GET loop is what wants those.
      */
+    SUCCEED_RETURN(errctx);
 }
 
 /**
@@ -312,7 +329,7 @@ static akerr_ErrorContext AKERR_NOIGNORE *edit_loop(akbasic_AkglSink *state, boo
 	 */
 	PASS(errctx, akgl_controller_poll_keystroke(&key, &available));
 	if ( available ) {
-	    edit_key(state, &key, &submitted);
+	    PASS(errctx, edit_key(state, &key, &submitted));
 	    continue;
 	}
 	/*
@@ -375,9 +392,8 @@ static akerr_ErrorContext *sink_readline(akbasic_TextSink *self, char *dest, siz
     if ( *eof ) {
 	SUCCEED_RETURN(errctx);
     }
-    strncpy(dest, state->editline, len - 1);
-    dest[len - 1] = '\0';
-    newline(state);
+    PASS(errctx, aksl_strncpy(dest, len, state->editline, len - 1));
+    PASS(errctx, newline(state));
     SUCCEED_RETURN(errctx);
 }
 
@@ -391,7 +407,7 @@ static akerr_ErrorContext *sink_clear(akbasic_TextSink *self)
     state = (akbasic_AkglSink *)self->self;
     FAIL_ZERO_RETURN(errctx, (state != NULL), AKERR_NULLPOINTER,
 		     "akgl sink has no state");
-    memset(state->text, 0, sizeof(state->text));
+    PASS(errctx, aksl_memset(state->text, 0, sizeof(state->text)));
     state->cursorcol = 0;
     state->cursorrow = 0;
     SUCCEED_RETURN(errctx);
@@ -600,7 +616,7 @@ akerr_ErrorContext *akbasic_sink_init_akgl(akbasic_TextSink *obj, akbasic_AkglSi
 		     "A %dx%d text area has no room for a %dx%d character",
 		     w, h, cellw, cellh);
 
-    memset(state, 0, sizeof(*state));
+    PASS(errctx, aksl_memset(state, 0, sizeof(*state)));
     state->renderer = renderer;
     state->font = font;
     state->color.r = 0xff;

src/sink_stdio.c

@@ -10,7 +10,6 @@
  */
 
 #include <stdio.h>
-#include <string.h>
 
 #include <akerror.h>
 #include <akstdlib.h>
@@ -59,16 +58,40 @@ static akerr_ErrorContext *stdio_readline(akbasic_TextSink *self, char *dest, si
     *eof = false;
     dest[0] = '\0';
 
-    if ( fgets(dest, (int)len, state->in) == NULL ) {
+    /*
+     * The end of the stream is AKERR_EOF rather than a NULL return, so it is
+     * handled here and turned back into the *eof flag this sink promises. A
+     * genuine read error is left to propagate, which is what a NULL from
+     * fgets(3) could never be told apart from.
+     */
+    ATTEMPT {
+	CATCH(errctx, aksl_fgets(dest, len, state->in, &used));
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } HANDLE(errctx, AKERR_EOF) {
 	*eof = true;
+    } FINISH(errctx, true);
+    if ( *eof ) {
 	SUCCEED_RETURN(errctx);
     }
+    /*
+     * aksl_fgets(3)'s own contract: a full buffer with no trailing newline is
+     * how a caller spots a line longer than the buffer, because the rest of it
+     * is still sitting unread in the stream. Refusing here is what makes that
+     * true -- without it, the unread remainder is picked up by the *next*
+     * readline() as if it were its own statement, which does not fail, it just
+     * runs the wrong program. AKBASIC_MAX_LINE_LENGTH is small enough now that
+     * this is not a hypothetical: examples/breakout's own longest line used to
+     * clear the old 256-byte ceiling by more than half.
+     */
+    FAIL_NONZERO_RETURN(errctx, (used == len - 1 && dest[used - 1] != '\n' && dest[used - 1] != '\r'),
+			AKBASIC_ERR_BOUNDS,
+			"Source line exceeds the %zu character limit", len - 1);
     /*
      * Strip the line terminator. The scanner treats \r and \n as end-of-line
      * anyway, but leaving them on would make a stored source line differ from
      * the same line typed at the REPL.
      */
-    used = strlen(dest);
     while ( used > 0 && (dest[used - 1] == '\n' || dest[used - 1] == '\r') ) {
 	dest[used - 1] = '\0';
 	used -= 1;

src/sprite_akgl.c

@@ -34,11 +34,11 @@
  */
 
 #include <errno.h>
-#include <string.h>
 
 #include <SDL3_image/SDL_image.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akgl/error.h>
 #include <akgl/game.h>
@@ -195,9 +195,9 @@ static akerr_ErrorContext *build_slot(akbasic_AkglSprites *state, int i, int wid
 	oldvisible = state->actors[i]->visible;
     }
 
-    memset(spritename, 0, sizeof(spritename));
-    memset(charname, 0, sizeof(charname));
-    memset(actorname, 0, sizeof(actorname));
+    PASS(errctx, aksl_memset(spritename, 0, sizeof(spritename)));
+    PASS(errctx, aksl_memset(charname, 0, sizeof(charname)));
+    PASS(errctx, aksl_memset(actorname, 0, sizeof(actorname)));
     SDL_snprintf(spritename, sizeof(spritename), "akbasic:sprite:%d", i + 1);
     SDL_snprintf(charname, sizeof(charname), "akbasic:character:%d", i + 1);
     SDL_snprintf(actorname, sizeof(actorname), "akbasic:actor:%d", i + 1);
@@ -263,8 +263,8 @@ static akerr_ErrorContext *install_surface(akbasic_AkglSprites *state, int i, SD
      * which is what makes the texture's ownership one rule rather than two.
      */
     PASS(errctx, akgl_heap_next_spritesheet(&state->sheets[i]));
-    memset(state->sheets[i], 0, sizeof(*state->sheets[i]));
-    memset(sheetname, 0, sizeof(sheetname));
+    PASS(errctx, aksl_memset(state->sheets[i], 0, sizeof(*state->sheets[i])));
+    PASS(errctx, aksl_memset(sheetname, 0, sizeof(sheetname)));
     SDL_snprintf(sheetname, sizeof(sheetname), "akbasic:sheet:%d", i + 1);
     SDL_strlcpy(state->sheets[i]->name, sheetname, sizeof(state->sheets[i]->name));
     state->sheets[i]->texture = texture;
@@ -533,7 +533,7 @@ static akerr_ErrorContext *spr_shape(akbasic_SpriteBackend *self, int n, int kin
     state->shapex2[i] = (float32_t)x2;
     state->shapey2[i] = (float32_t)y2;
     state->shapeexplicit[i] = (x2 > x1 && y2 > y1);
-    memset(&state->syncedbox[i], 0, sizeof(state->syncedbox[i]));
+    PASS(errctx, aksl_memset(&state->syncedbox[i], 0, sizeof(state->syncedbox[i])));
     SUCCEED_RETURN(errctx);
 }
 
@@ -703,7 +703,8 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_scan(akbasic_AkglSprites *state)
     for ( i = 0; i < AKBASIC_MAX_SPRITES; i++ ) {
 	live[i] = slot_collidable(state, i);
 	synced[i] = false;
-	memset(&box[i], 0, sizeof(box[i]));
+	/* PASS rather than CATCH, as everywhere else in this loop-heavy function. */
+	PASS(errctx, aksl_memset(&box[i], 0, sizeof(box[i])));
 	if ( !live[i] ) {
 	    continue;
 	}
@@ -745,7 +746,7 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_scan(akbasic_AkglSprites *state)
     }
     state->lastmask = 0;
     state->lastsolidmask = 0;
-    memset(state->hascontact, 0, sizeof(state->hascontact));
+    PASS(errctx, aksl_memset(state->hascontact, 0, sizeof(state->hascontact)));
 
     /*
      * **Two phases, and the split is the whole performance story.**
@@ -970,7 +971,7 @@ akerr_ErrorContext *akbasic_sprite_init_akgl(akbasic_SpriteBackend *obj, akbasic
     /* Before anything else in libakgl, so every AKGL_ERR_* has a name to print. */
     PASS(errctx, akgl_error_init());
 
-    memset(state, 0, sizeof(*state));
+    PASS(errctx, aksl_memset(state, 0, sizeof(*state)));
     state->renderer = renderer;
     state->graphics = graphics;
 
@@ -1012,7 +1013,7 @@ akerr_ErrorContext *akbasic_sprite_init_akgl(akbasic_SpriteBackend *obj, akbasic
 						     &state->shapes[i], 0.0f, 0.0f, 0.0f));
     }
 
-    memset(obj, 0, sizeof(*obj));
+    PASS(errctx, aksl_memset(obj, 0, sizeof(*obj)));
     obj->self		= state;
     obj->define		= spr_define;
     obj->define_shape	= spr_define_shape;

src/sprite_tables.c

@@ -9,9 +9,8 @@
  * adaptor that has to turn a pattern into pixels.
  */
 
-#include <string.h>
-
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/error.h>
 #include <akbasic/sprite.h>
@@ -40,7 +39,7 @@ akerr_ErrorContext *akbasic_sprite_state_init(akbasic_SpriteState *obj)
     int i = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL sprite state in init");
-    memset(obj, 0, sizeof(*obj));
+    PASS(errctx, aksl_memset(obj, 0, sizeof(*obj)));
     for ( i = 0; i < AKBASIC_MAX_SPRITES; i++ ) {
 	obj->sprites[i].colorindex = SPRITE_COLOR_DEFAULT;
     }

src/structtype.c

@@ -23,6 +23,7 @@
 #include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/error.h>
 #include <akbasic/runtime.h>
@@ -88,10 +89,22 @@ static const char *next_word(const char *cursor, char *dest, size_t len)
     return cursor;
 }
 
-/** @brief Compare a word against a keyword. Verbs are case-insensitive here as everywhere. */
-static bool word_is(const char *word, const char *keyword)
+/**
+ * @brief Compare a word against a keyword. Verbs are case-insensitive here as everywhere.
+ *
+ * The answer leaves through @p dest rather than the return value because the
+ * comparison itself can fail, and a `bool` has nowhere to put that. See
+ * libakstdlib #38.
+ */
+static akerr_ErrorContext *word_is(const char *word, const char *keyword, bool *dest)
 {
-    return (strcmp(word, keyword) == 0);
+    PREPARE_ERROR(errctx);
+    int cmp = 0;
+
+    FAIL_ZERO_RETURN(errctx, (dest != NULL), AKERR_NULLPOINTER, "NULL dest in word_is");
+    PASS(errctx, aksl_strcmp(word, keyword, &cmp));
+    *dest = (cmp == 0);
+    SUCCEED_RETURN(errctx);
 }
 
 /**
@@ -103,8 +116,9 @@ static bool word_is(const char *word, const char *keyword)
 static akerr_ErrorContext *type_from_suffix(const char *name, akbasic_Type *dest)
 {
     PREPARE_ERROR(errctx);
-    size_t len = strlen(name);
+    size_t len = 0;
 
+    PASS(errctx, aksl_strlen(name, &len));
     FAIL_ZERO_RETURN(errctx, (len >= 2), AKBASIC_ERR_SYNTAX,
 		     "Field name \"%s\" carries no type suffix", name);
     switch ( name[len - 1] ) {
@@ -125,7 +139,7 @@ akerr_ErrorContext *akbasic_structtype_table_init(akbasic_StructTypeTable *obj)
     PREPARE_ERROR(errctx);
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL table in structtype init");
-    memset(obj, 0, sizeof(*obj));
+    PASS(errctx, aksl_memset(obj, 0, sizeof(*obj)));
     obj->count = 0;
     SUCCEED_RETURN(errctx);
 }
@@ -134,12 +148,17 @@ akerr_ErrorContext *akbasic_structtype_find(akbasic_StructTypeTable *obj, const
 {
     PREPARE_ERROR(errctx);
     int i = 0;
+    int cmp = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL && name != NULL && dest != NULL), AKERR_NULLPOINTER,
 		     "NULL argument in structtype find");
     *dest = -1;
     for ( i = 0; i < obj->count; i++ ) {
-	if ( obj->types[i].used && strcmp(obj->types[i].name, name) == 0 ) {
+	if ( !obj->types[i].used ) {
+	    continue;
+	}
+	PASS(errctx, aksl_strcmp(obj->types[i].name, name, &cmp));
+	if ( cmp == 0 ) {
 	    *dest = i;
 	    SUCCEED_RETURN(errctx);
 	}
@@ -151,9 +170,14 @@ akerr_ErrorContext *akbasic_structtype_field(akbasic_StructTypeTable *obj, int t
 {
     PREPARE_ERROR(errctx);
     char known[AKBASIC_MAX_STRING_LENGTH];
+    const char *separator = NULL;
     akbasic_StructType *type = NULL;
     size_t used = 0;
+    size_t namelen = 0;
+    size_t seplen = 0;
+    int written = 0;
     int i = 0;
+    int cmp = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL && name != NULL && dest != NULL), AKERR_NULLPOINTER,
 		     "NULL argument in structtype field");
@@ -162,7 +186,8 @@ akerr_ErrorContext *akbasic_structtype_field(akbasic_StructTypeTable *obj, int t
     type = &obj->types[typeindex];
 
     for ( i = 0; i < type->fieldcount; i++ ) {
-	if ( strcmp(type->fields[i].name, name) == 0 ) {
+	PASS(errctx, aksl_strcmp(type->fields[i].name, name, &cmp));
+	if ( cmp == 0 ) {
 	    *dest = &type->fields[i];
 	    SUCCEED_RETURN(errctx);
 	}
@@ -176,11 +201,20 @@ akerr_ErrorContext *akbasic_structtype_field(akbasic_StructTypeTable *obj, int t
      */
     known[0] = '\0';
     for ( i = 0; i < type->fieldcount; i++ ) {
-	int written = snprintf(known + used, sizeof(known) - used, "%s%s",
-			       (i == 0 ? "" : ", "), type->fields[i].name);
-	if ( written < 0 || (size_t)written >= sizeof(known) - used ) {
+	separator = (i == 0 ? "" : ", ");
+	PASS(errctx, aksl_strlen(separator, &seplen));
+	PASS(errctx, aksl_strlen(type->fields[i].name, &namelen));
+	/*
+	 * The list is advisory, so a full buffer ends it rather than failing the
+	 * lookup. aksl_snprintf treats truncation as an error, which is right
+	 * everywhere the output matters -- so the fit is decided here, before the
+	 * call, instead of being read back out of a return value afterwards.
+	 */
+	if ( used + seplen + namelen >= sizeof(known) ) {
 	    break;
 	}
+	PASS(errctx, aksl_snprintf(&written, known + used, sizeof(known) - used, "%s%s",
+				   separator, type->fields[i].name));
 	used += (size_t)written;
     }
     FAIL_RETURN(errctx, AKBASIC_ERR_UNDEFINED, "%s has no field %s (%s)",
@@ -223,6 +257,8 @@ static akerr_ErrorContext *scan_names(akbasic_Runtime *obj)
     int64_t i = 0;
     int open = -1;
     int existing = 0;
+    size_t namelen = 0;
+    bool matched = false;
     const akbasic_Verb *verb = NULL;
 
     for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
@@ -231,9 +267,11 @@ static akerr_ErrorContext *scan_names(akbasic_Runtime *obj)
 	}
 	cursor = next_word(skip_lineno(obj->source[i].code), word, sizeof(word));
 
-	if ( word_is(word, "END") ) {
+	PASS(errctx, word_is(word, "END", &matched));
+	if ( matched ) {
 	    (void)next_word(cursor, name, sizeof(name));
-	    if ( !word_is(name, "TYPE") ) {
+	    PASS(errctx, word_is(name, "TYPE", &matched));
+	    if ( !matched ) {
 		continue;		/* an ordinary END, not our terminator */
 	    }
 	    FAIL_ZERO_RETURN(errctx, (open >= 0), AKBASIC_ERR_SYNTAX,
@@ -242,7 +280,8 @@ static akerr_ErrorContext *scan_names(akbasic_Runtime *obj)
 	    open = -1;
 	    continue;
 	}
-	if ( !word_is(word, "TYPE") ) {
+	PASS(errctx, word_is(word, "TYPE", &matched));
+	if ( !matched ) {
 	    continue;
 	}
 
@@ -268,16 +307,17 @@ static akerr_ErrorContext *scan_names(akbasic_Runtime *obj)
 	FAIL_ZERO_RETURN(errctx, (table->count < AKBASIC_MAX_STRUCT_TYPES), AKBASIC_ERR_BOUNDS,
 			 "More than %d TYPE declarations", AKBASIC_MAX_STRUCT_TYPES);
 
-	FAIL_ZERO_RETURN(errctx, (strlen(name) < AKBASIC_MAX_STRUCT_NAME), AKBASIC_ERR_BOUNDS,
+	PASS(errctx, aksl_strlen(name, &namelen));
+	FAIL_ZERO_RETURN(errctx, (namelen < AKBASIC_MAX_STRUCT_NAME), AKBASIC_ERR_BOUNDS,
 			 "TYPE name \"%s\" exceeds the %d character limit",
 			 name, AKBASIC_MAX_STRUCT_NAME - 1);
 	open = table->count;
-	memset(&table->types[open], 0, sizeof(table->types[open]));
-	/* The memset is what terminates this: bounded at size - 1, the last byte
-	   is the zero it already wrote. Refused above rather than truncated,
-	   because two long names truncating to the same prefix would collide
-	   silently -- and truncation is an error everywhere else here. */
-	strncpy(table->types[open].name, name, sizeof(table->types[open].name) - 1);
+	PASS(errctx, aksl_memset(&table->types[open], 0, sizeof(table->types[open])));
+	/* aksl_strcpy always terminates and refuses rather than truncates, which
+	   is the behaviour this site already wanted -- two long names truncating
+	   to the same prefix would collide silently. The length check above stays
+	   because it names the limit in the message. */
+	PASS(errctx, aksl_strcpy(table->types[open].name, sizeof(table->types[open].name), name));
 	table->types[open].used = true;
 	table->types[open].firstline = i;
 	table->types[open].lastline = -1;
@@ -302,34 +342,38 @@ static akerr_ErrorContext *parse_field(akbasic_StructTypeTable *table, akbasic_S
     const char *cursor = NULL;
     akbasic_StructField *field = NULL;
     akbasic_Type valuetype = AKBASIC_TYPE_UNDEFINED;
+    size_t namelen = 0;
+    bool matched = false;
     int referenced = 0;
+    int cmp = 0;
     int i = 0;
 
     cursor = next_word(skip_lineno(line), fieldname, sizeof(fieldname));
     if ( fieldname[0] == '\0' || fieldname[0] == '\'' ) {
 	SUCCEED_RETURN(errctx);			/* a blank line inside the block */
     }
-    if ( word_is(fieldname, "REM") ) {
+    PASS(errctx, word_is(fieldname, "REM", &matched));
+    if ( matched ) {
 	SUCCEED_RETURN(errctx);
     }
 
     FAIL_ZERO_RETURN(errctx, (type->fieldcount < AKBASIC_MAX_STRUCT_FIELDS), AKBASIC_ERR_BOUNDS,
 		     "TYPE %s declares more than %d fields", type->name, AKBASIC_MAX_STRUCT_FIELDS);
     for ( i = 0; i < type->fieldcount; i++ ) {
-	FAIL_NONZERO_RETURN(errctx, (strcmp(type->fields[i].name, fieldname) == 0),
-			    AKBASIC_ERR_VALUE,
+	PASS(errctx, aksl_strcmp(type->fields[i].name, fieldname, &cmp));
+	FAIL_NONZERO_RETURN(errctx, (cmp == 0), AKBASIC_ERR_VALUE,
 			    "TYPE %s declares %s twice", type->name, fieldname);
     }
 
     PASS(errctx, type_from_suffix(fieldname, &valuetype));
-    FAIL_ZERO_RETURN(errctx, (strlen(fieldname) < AKBASIC_MAX_STRUCT_NAME), AKBASIC_ERR_BOUNDS,
+    PASS(errctx, aksl_strlen(fieldname, &namelen));
+    FAIL_ZERO_RETURN(errctx, (namelen < AKBASIC_MAX_STRUCT_NAME), AKBASIC_ERR_BOUNDS,
 		     "Field name \"%s\" exceeds the %d character limit",
 		     fieldname, AKBASIC_MAX_STRUCT_NAME - 1);
     field = &type->fields[type->fieldcount];
-    memset(field, 0, sizeof(*field));
-    /* Terminated by the memset above; refused rather than truncated, for the
-       same reason a type name is. */
-    strncpy(field->name, fieldname, sizeof(field->name) - 1);
+    PASS(errctx, aksl_memset(field, 0, sizeof(*field)));
+    /* Refused rather than truncated, for the same reason a type name is. */
+    PASS(errctx, aksl_strcpy(field->name, sizeof(field->name), fieldname));
     field->valuetype = valuetype;
     field->typeindex = -1;
     field->offset = -1;
@@ -354,13 +398,16 @@ static akerr_ErrorContext *parse_field(akbasic_StructTypeTable *table, akbasic_S
      * not fit in one. So the declaration has to name it.
      */
     cursor = next_word(cursor, word, sizeof(word));
-    FAIL_ZERO_RETURN(errctx, word_is(word, "AS"), AKBASIC_ERR_SYNTAX,
+    PASS(errctx, word_is(word, "AS", &matched));
+    FAIL_ZERO_RETURN(errctx, matched, AKBASIC_ERR_SYNTAX,
 		     "Line %" PRId64 ": %s must name its type -- %s AS TYPENAME, or %s AS PTR TO TYPENAME",
 		     lineno, fieldname, fieldname, fieldname);
     cursor = next_word(cursor, word, sizeof(word));
-    if ( word_is(word, "PTR") ) {
+    PASS(errctx, word_is(word, "PTR", &matched));
+    if ( matched ) {
 	cursor = next_word(cursor, word, sizeof(word));
-	FAIL_ZERO_RETURN(errctx, word_is(word, "TO"), AKBASIC_ERR_SYNTAX,
+	PASS(errctx, word_is(word, "TO", &matched));
+	FAIL_ZERO_RETURN(errctx, matched, AKBASIC_ERR_SYNTAX,
 			 "Line %" PRId64 ": expected PTR TO TYPENAME", lineno);
 	cursor = next_word(cursor, word, sizeof(word));
 	field->kind = AKBASIC_FIELD_POINTER;
@@ -466,7 +513,7 @@ akerr_ErrorContext *akbasic_structtype_scan(akbasic_Runtime *obj)
 	}
     }
     for ( i = t; i < table->count; i++ ) {
-	memset(&table->types[i], 0, sizeof(table->types[i]));
+	PASS(errctx, aksl_memset(&table->types[i], 0, sizeof(table->types[i])));
     }
     table->count = t;
 

src/symtab.c

@@ -3,8 +3,6 @@
  * @brief Implements the fixed-capacity open-addressed symbol table.
  */
 
-#include <string.h>
-
 #include <akerror.h>
 #include <akstdlib.h>
 
@@ -23,10 +21,13 @@ static akerr_ErrorContext *probe(akbasic_SymbolTable *obj, const char *key, int
 {
     PREPARE_ERROR(errctx);
     uint32_t hashval = 0;
+    size_t keylen = 0;
     int index = 0;
+    int cmp = 0;
     int i = 0;
 
-    PASS(errctx, aksl_strhash_djb2((char *)key, strlen(key), &hashval));
+    PASS(errctx, aksl_strlen(key, &keylen));
+    PASS(errctx, aksl_strhash_djb2((char *)key, keylen, &hashval));
 
     *found = false;
     index = (int)(hashval % (uint32_t)obj->capacity);
@@ -36,7 +37,8 @@ static akerr_ErrorContext *probe(akbasic_SymbolTable *obj, const char *key, int
 	    *slot = probeidx;
 	    SUCCEED_RETURN(errctx);
 	}
-	if ( strcmp(obj->slots[probeidx].key, key) == 0 ) {
+	PASS(errctx, aksl_strcmp(obj->slots[probeidx].key, key, &cmp));
+	if ( cmp == 0 ) {
 	    *slot = probeidx;
 	    *found = true;
 	    SUCCEED_RETURN(errctx);
@@ -58,7 +60,7 @@ akerr_ErrorContext *akbasic_symtab_init(akbasic_SymbolTable *obj, int capacity)
 		     "Symbol table capacity %d out of range 1..%d",
 		     capacity, AKBASIC_SYMTAB_MAX_SLOTS);
 
-    memset(obj, 0, sizeof(*obj));
+    PASS(errctx, aksl_memset(obj, 0, sizeof(*obj)));
     obj->capacity = capacity;
     obj->count = 0;
     SUCCEED_RETURN(errctx);
@@ -67,6 +69,7 @@ akerr_ErrorContext *akbasic_symtab_init(akbasic_SymbolTable *obj, int capacity)
 akerr_ErrorContext *akbasic_symtab_set(akbasic_SymbolTable *obj, const char *key, void *value, int64_t ivalue)
 {
     PREPARE_ERROR(errctx);
+    size_t keylen = 0;
     int slot = 0;
     bool found = false;
 
@@ -74,7 +77,8 @@ akerr_ErrorContext *akbasic_symtab_set(akbasic_SymbolTable *obj, const char *key
 		     "NULL symbol table in set");
     FAIL_ZERO_RETURN(errctx, (key != NULL), AKERR_NULLPOINTER,
 		     "NULL key in symbol table set");
-    FAIL_ZERO_RETURN(errctx, (strlen(key) < AKBASIC_SYMTAB_MAX_KEY),
+    PASS(errctx, aksl_strlen(key, &keylen));
+    FAIL_ZERO_RETURN(errctx, (keylen < AKBASIC_SYMTAB_MAX_KEY),
 		     AKBASIC_ERR_BOUNDS,
 		     "Symbol name '%s' exceeds %d characters",
 		     key, AKBASIC_SYMTAB_MAX_KEY - 1);
@@ -82,8 +86,10 @@ akerr_ErrorContext *akbasic_symtab_set(akbasic_SymbolTable *obj, const char *key
     PASS(errctx, probe(obj, key, &slot, &found));
 
     if ( !found ) {
-	strncpy(obj->slots[slot].key, key, AKBASIC_SYMTAB_MAX_KEY - 1);
-	obj->slots[slot].key[AKBASIC_SYMTAB_MAX_KEY - 1] = '\0';
+	/* aksl_strcpy always terminates, so the explicit terminator this
+	   replaced is no longer needed. The length check above has already
+	   refused anything that would not fit, so it cannot fail here. */
+	PASS(errctx, aksl_strcpy(obj->slots[slot].key, sizeof(obj->slots[slot].key), key));
 	obj->slots[slot].used = true;
 	obj->count += 1;
     }
@@ -95,6 +101,7 @@ akerr_ErrorContext *akbasic_symtab_set(akbasic_SymbolTable *obj, const char *key
 akerr_ErrorContext *akbasic_symtab_get(akbasic_SymbolTable *obj, const char *key, void **value, int64_t *ivalue)
 {
     PREPARE_ERROR(errctx);
+    size_t keylen = 0;
     int slot = 0;
     bool found = false;
 
@@ -102,7 +109,8 @@ akerr_ErrorContext *akbasic_symtab_get(akbasic_SymbolTable *obj, const char *key
 		     "NULL symbol table in get");
     FAIL_ZERO_RETURN(errctx, (key != NULL), AKERR_NULLPOINTER,
 		     "NULL key in symbol table get");
-    FAIL_ZERO_RETURN(errctx, (strlen(key) < AKBASIC_SYMTAB_MAX_KEY),
+    PASS(errctx, aksl_strlen(key, &keylen));
+    FAIL_ZERO_RETURN(errctx, (keylen < AKBASIC_SYMTAB_MAX_KEY),
 		     AKERR_KEY,
 		     "Symbol '%s' is not present", key);
 
@@ -127,7 +135,7 @@ akerr_ErrorContext *akbasic_symtab_clear(akbasic_SymbolTable *obj)
 		     "NULL symbol table in clear");
 
     capacity = obj->capacity;
-    memset(obj, 0, sizeof(*obj));
+    PASS(errctx, aksl_memset(obj, 0, sizeof(*obj)));
     obj->capacity = capacity;
     SUCCEED_RETURN(errctx);
 }

src/ui_akgl.c

@@ -16,10 +16,8 @@
  * string.
  */
 
-#include <stdio.h>
-#include <string.h>
-
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akgl/error.h>
 #include <akgl/registry.h>
@@ -94,8 +92,7 @@ static akerr_ErrorContext *ui_dialog(akbasic_UiBackend *self, const char *text)
 	state->dialogtext[0] = '\0';
 	SUCCEED_RETURN(errctx);
     }
-    strncpy(state->dialogtext, text, sizeof(state->dialogtext) - 1);
-    state->dialogtext[sizeof(state->dialogtext) - 1] = '\0';
+    PASS(errctx, aksl_strcpy(state->dialogtext, sizeof(state->dialogtext), text));
     state->dialogopen = true;
     SUCCEED_RETURN(errctx);
 }
@@ -113,8 +110,7 @@ static akerr_ErrorContext *ui_label(akbasic_UiBackend *self, int slot, int ancho
 	state->labeltext[slot][0] = '\0';
 	SUCCEED_RETURN(errctx);
     }
-    strncpy(state->labeltext[slot], text, sizeof(state->labeltext[slot]) - 1);
-    state->labeltext[slot][sizeof(state->labeltext[slot]) - 1] = '\0';
+    PASS(errctx, aksl_strcpy(state->labeltext[slot], sizeof(state->labeltext[slot]), text));
     state->labelanchor[slot] = anchor;
     state->labelset[slot] = true;
     SUCCEED_RETURN(errctx);
@@ -143,8 +139,8 @@ static akerr_ErrorContext *ui_menu(akbasic_UiBackend *self, int slot, const char
     for ( i = 0; i < count; i++ ) {
 	FAIL_ZERO_RETURN(errctx, (items[i] != NULL), AKERR_NULLPOINTER,
 			 "MENU entry %d is NULL", i + 1);
-	strncpy(state->menuitems[slot][i], items[i], sizeof(state->menuitems[slot][i]) - 1);
-	state->menuitems[slot][i][sizeof(state->menuitems[slot][i]) - 1] = '\0';
+	PASS(errctx, aksl_strcpy(state->menuitems[slot][i], sizeof(state->menuitems[slot][i]),
+				 items[i]));
 	state->menus[slot].items[i] = state->menuitems[slot][i];
     }
     for ( i = count; i < AKBASIC_UI_MAX_MENU_ITEMS; i++ ) {
@@ -348,9 +344,9 @@ akerr_ErrorContext *akbasic_ui_init_akgl(akbasic_UiBackend *obj, akbasic_AkglUi
 		     "A %dx%d UI at %d points is not a UI", width, height, fontsize);
     PASS(errctx, akgl_error_init());
 
-    memset(state, 0, sizeof(*state));
+    PASS(errctx, aksl_memset(state, 0, sizeof(*state)));
     state->renderer = renderer;
-    strncpy(state->fontname, UI_FONT_NAME, sizeof(state->fontname) - 1);
+    PASS(errctx, aksl_strcpy(state->fontname, sizeof(state->fontname), UI_FONT_NAME));
 
     /*
      * The element ids, once. clay identifies an element by its string and keeps
@@ -359,13 +355,14 @@ akerr_ErrorContext *akbasic_ui_init_akgl(akbasic_UiBackend *obj, akbasic_AkglUi
      * function that declares them.
      */
     for ( i = 0; i < AKBASIC_UI_MAX_LABELS; i++ ) {
-	snprintf(state->labelid[i], sizeof(state->labelid[i]), "hud%d", i + 1);
+	PASS(errctx, aksl_snprintf(&count, state->labelid[i], sizeof(state->labelid[i]),
+				   "hud%d", i + 1));
     }
     for ( i = 0; i < AKBASIC_UI_MAX_MENUS; i++ ) {
-	snprintf(state->menuid[i], sizeof(state->menuid[i]), "menu%d", i + 1);
+	PASS(errctx, aksl_snprintf(&count, state->menuid[i], sizeof(state->menuid[i]),
+				   "menu%d", i + 1));
 	state->menus[i].id = state->menuid[i];
     }
-    (void)count;
 
     /*
      * **akgl_registry_init() does not initialize the font registry** -- its own

src/value.c

@@ -13,6 +13,7 @@
 #include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/error.h>
 #include <akbasic/value.h>
@@ -119,13 +120,17 @@ static akerr_ErrorContext *require_numeric(akbasic_Value *self, akbasic_Value *r
 static akerr_ErrorContext *set_string(akbasic_Value *dest, const char *src)
 {
     PREPARE_ERROR(errctx);
+    size_t srclen = 0;
 
-    FAIL_ZERO_RETURN(errctx, (strlen(src) < AKBASIC_MAX_STRING_LENGTH),
+    PASS(errctx, aksl_strlen(src, &srclen));
+    FAIL_ZERO_RETURN(errctx, (srclen < AKBASIC_MAX_STRING_LENGTH),
 		     AKBASIC_ERR_VALUE,
 		     "String result of %zu characters exceeds the %d character limit",
-		     strlen(src), AKBASIC_MAX_STRING_LENGTH - 1);
-    strncpy(dest->stringval, src, AKBASIC_MAX_STRING_LENGTH - 1);
-    dest->stringval[AKBASIC_MAX_STRING_LENGTH - 1] = '\0';
+		     srclen, AKBASIC_MAX_STRING_LENGTH - 1);
+    /* aksl_strcpy always terminates and refuses rather than truncates, which is
+       the behaviour this site already wanted. The length check above stays
+       because it names the limit in the message. */
+    PASS(errctx, aksl_strcpy(dest->stringval, sizeof(dest->stringval), src));
     SUCCEED_RETURN(errctx);
 }
 
@@ -134,7 +139,7 @@ akerr_ErrorContext *akbasic_valuepool_init(akbasic_ValuePool *obj)
     PREPARE_ERROR(errctx);
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL pool in init");
-    memset(obj, 0, sizeof(*obj));
+    PASS(errctx, aksl_memset(obj, 0, sizeof(*obj)));
     obj->next = 0;
     SUCCEED_RETURN(errctx);
 }
@@ -201,7 +206,7 @@ akerr_ErrorContext *akbasic_value_clone(akbasic_Value *self, akbasic_Value *dest
 	SUCCEED_RETURN(errctx);
     }
     dest->valuetype = self->valuetype;
-    memcpy(dest->stringval, self->stringval, sizeof(dest->stringval));
+    PASS(errctx, aksl_memcpy(dest->stringval, self->stringval, sizeof(dest->stringval)));
     dest->intval = self->intval;
     dest->floatval = self->floatval;
     dest->boolvalue = self->boolvalue;
@@ -223,6 +228,7 @@ akerr_ErrorContext *akbasic_value_clone(akbasic_Value *self, akbasic_Value *dest
 akerr_ErrorContext *akbasic_value_to_string(akbasic_Value *self, char *dest, size_t len)
 {
     PREPARE_ERROR(errctx);
+    int written = 0;
 
     FAIL_ZERO_RETURN(errctx, (self != NULL), AKERR_NULLPOINTER, "NULL value in to_string");
     FAIL_ZERO_RETURN(errctx, (dest != NULL), AKERR_NULLPOINTER, "NULL destination in to_string");
@@ -230,20 +236,22 @@ akerr_ErrorContext *akbasic_value_to_string(akbasic_Value *self, char *dest, siz
 
     switch ( self->valuetype ) {
     case AKBASIC_TYPE_STRING:
-	snprintf(dest, len, "%s", self->stringval);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "%s", self->stringval));
 	break;
     case AKBASIC_TYPE_INTEGER:
-	snprintf(dest, len, "%" PRId64, self->intval);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "%" PRId64, self->intval));
 	break;
     case AKBASIC_TYPE_FLOAT:
-	snprintf(dest, len, "%f", self->floatval);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "%f", self->floatval));
 	break;
     case AKBASIC_TYPE_BOOLEAN:
 	/* Go's %t, which is "true"/"false" and not the numeric -1/0. */
-	snprintf(dest, len, "%s", (self->boolvalue == AKBASIC_TRUE ? "true" : "false"));
+	PASS(errctx, aksl_snprintf(&written, dest, len, "%s",
+				   (self->boolvalue == AKBASIC_TRUE ? "true" : "false")));
 	break;
     default:
-	snprintf(dest, len, "(UNDEFINED STRING REPRESENTATION FOR %d)", (int)self->valuetype);
+	PASS(errctx, aksl_snprintf(&written, dest, len, "(UNDEFINED STRING REPRESENTATION FOR %d)",
+				   (int)self->valuetype));
 	break;
     }
     SUCCEED_RETURN(errctx);
@@ -486,6 +494,7 @@ akerr_ErrorContext *akbasic_value_math_plus(akbasic_Value *self, akbasic_Value *
     PREPARE_ERROR(errctx);
     akbasic_Value *out = NULL;
     char buf[AKBASIC_MAX_STRING_LENGTH * 2];
+    int written = 0;
 
     FAIL_ZERO_RETURN(errctx, (self != NULL), AKERR_NULLPOINTER, "NULL value in math plus");
     FAIL_ZERO_RETURN(errctx, (rval != NULL), AKERR_NULLPOINTER, "nil rval");
@@ -511,13 +520,16 @@ akerr_ErrorContext *akbasic_value_math_plus(akbasic_Value *self, akbasic_Value *
     } else if ( self->valuetype == AKBASIC_TYPE_FLOAT ) {
 	out->floatval = self->floatval + rval_as_float(rval);
     } else if ( self->valuetype == AKBASIC_TYPE_STRING && rval->valuetype == AKBASIC_TYPE_STRING ) {
-	snprintf(buf, sizeof(buf), "%s%s", self->stringval, rval->stringval);
+	PASS(errctx, aksl_snprintf(&written, buf, sizeof(buf), "%s%s",
+				   self->stringval, rval->stringval));
 	PASS(errctx, set_string(out, buf));
     } else if ( self->valuetype == AKBASIC_TYPE_STRING && rval->valuetype == AKBASIC_TYPE_INTEGER ) {
-	snprintf(buf, sizeof(buf), "%s%" PRId64, self->stringval, rval->intval);
+	PASS(errctx, aksl_snprintf(&written, buf, sizeof(buf), "%s%" PRId64,
+				   self->stringval, rval->intval));
 	PASS(errctx, set_string(out, buf));
     } else if ( self->valuetype == AKBASIC_TYPE_STRING && rval->valuetype == AKBASIC_TYPE_FLOAT ) {
-	snprintf(buf, sizeof(buf), "%s%f", self->stringval, rval->floatval);
+	PASS(errctx, aksl_snprintf(&written, buf, sizeof(buf), "%s%f",
+				   self->stringval, rval->floatval));
 	PASS(errctx, set_string(out, buf));
     } else {
 	FAIL_RETURN(errctx, AKBASIC_ERR_TYPE, "Invalid arithmetic operation");
@@ -586,14 +598,14 @@ akerr_ErrorContext *akbasic_value_math_multiply(akbasic_Value *self, akbasic_Val
 	 */
 	FAIL_NONZERO_RETURN(errctx, (rval->intval < 0), AKBASIC_ERR_VALUE,
 			    "String multiplier %" PRId64 " must not be negative", rval->intval);
-	srclen = strlen((*dest)->stringval);
+	PASS(errctx, aksl_strlen((*dest)->stringval, &srclen));
 	FAIL_NONZERO_RETURN(errctx,
 			    (srclen != 0 && (uint64_t)rval->intval > (AKBASIC_MAX_STRING_LENGTH - 1) / srclen),
 			    AKBASIC_ERR_VALUE,
 			    "Repeated string of %zu x %" PRId64 " characters exceeds the %d character limit",
 			    srclen, rval->intval, AKBASIC_MAX_STRING_LENGTH - 1);
 	for ( i = 0; i < rval->intval; i++ ) {
-	    memcpy(buf + offset, (*dest)->stringval, srclen);
+	    PASS(errctx, aksl_memcpy(buf + offset, (*dest)->stringval, srclen));
 	    offset += srclen;
 	}
 	buf[offset] = '\0';
@@ -619,6 +631,7 @@ akerr_ErrorContext *akbasic_value_math_multiply(akbasic_Value *self, akbasic_Val
 akerr_ErrorContext *akbasic_value_less_than(akbasic_Value *self, akbasic_Value *rval, akbasic_Value *scratch, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    int cmp = 0;
 
     PASS(errctx, binary_prologue(self, rval, scratch, dest));
     if ( self->valuetype == AKBASIC_TYPE_INTEGER ) {
@@ -626,7 +639,8 @@ akerr_ErrorContext *akbasic_value_less_than(akbasic_Value *self, akbasic_Value *
     } else if ( self->valuetype == AKBASIC_TYPE_FLOAT ) {
 	PASS(errctx, akbasic_value_set_bool(*dest, self->floatval < rval_as_float(rval)));
     } else {
-	PASS(errctx, akbasic_value_set_bool(*dest, strcmp(self->stringval, rval->stringval) < 0));
+	PASS(errctx, aksl_strcmp(self->stringval, rval->stringval, &cmp));
+	PASS(errctx, akbasic_value_set_bool(*dest, cmp < 0));
     }
     SUCCEED_RETURN(errctx);
 }
@@ -634,6 +648,7 @@ akerr_ErrorContext *akbasic_value_less_than(akbasic_Value *self, akbasic_Value *
 akerr_ErrorContext *akbasic_value_less_than_equal(akbasic_Value *self, akbasic_Value *rval, akbasic_Value *scratch, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    int cmp = 0;
 
     PASS(errctx, binary_prologue(self, rval, scratch, dest));
     if ( self->valuetype == AKBASIC_TYPE_INTEGER ) {
@@ -641,7 +656,8 @@ akerr_ErrorContext *akbasic_value_less_than_equal(akbasic_Value *self, akbasic_V
     } else if ( self->valuetype == AKBASIC_TYPE_FLOAT ) {
 	PASS(errctx, akbasic_value_set_bool(*dest, self->floatval <= rval_as_float(rval)));
     } else {
-	PASS(errctx, akbasic_value_set_bool(*dest, strcmp(self->stringval, rval->stringval) <= 0));
+	PASS(errctx, aksl_strcmp(self->stringval, rval->stringval, &cmp));
+	PASS(errctx, akbasic_value_set_bool(*dest, cmp <= 0));
     }
     SUCCEED_RETURN(errctx);
 }
@@ -649,6 +665,7 @@ akerr_ErrorContext *akbasic_value_less_than_equal(akbasic_Value *self, akbasic_V
 akerr_ErrorContext *akbasic_value_greater_than(akbasic_Value *self, akbasic_Value *rval, akbasic_Value *scratch, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    int cmp = 0;
 
     PASS(errctx, binary_prologue(self, rval, scratch, dest));
     if ( self->valuetype == AKBASIC_TYPE_INTEGER ) {
@@ -656,7 +673,8 @@ akerr_ErrorContext *akbasic_value_greater_than(akbasic_Value *self, akbasic_Valu
     } else if ( self->valuetype == AKBASIC_TYPE_FLOAT ) {
 	PASS(errctx, akbasic_value_set_bool(*dest, self->floatval > rval_as_float(rval)));
     } else {
-	PASS(errctx, akbasic_value_set_bool(*dest, strcmp(self->stringval, rval->stringval) > 0));
+	PASS(errctx, aksl_strcmp(self->stringval, rval->stringval, &cmp));
+	PASS(errctx, akbasic_value_set_bool(*dest, cmp > 0));
     }
     SUCCEED_RETURN(errctx);
 }
@@ -664,6 +682,7 @@ akerr_ErrorContext *akbasic_value_greater_than(akbasic_Value *self, akbasic_Valu
 akerr_ErrorContext *akbasic_value_greater_than_equal(akbasic_Value *self, akbasic_Value *rval, akbasic_Value *scratch, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    int cmp = 0;
 
     PASS(errctx, binary_prologue(self, rval, scratch, dest));
     if ( self->valuetype == AKBASIC_TYPE_INTEGER ) {
@@ -671,7 +690,8 @@ akerr_ErrorContext *akbasic_value_greater_than_equal(akbasic_Value *self, akbasi
     } else if ( self->valuetype == AKBASIC_TYPE_FLOAT ) {
 	PASS(errctx, akbasic_value_set_bool(*dest, self->floatval >= rval_as_float(rval)));
     } else {
-	PASS(errctx, akbasic_value_set_bool(*dest, strcmp(self->stringval, rval->stringval) >= 0));
+	PASS(errctx, aksl_strcmp(self->stringval, rval->stringval, &cmp));
+	PASS(errctx, akbasic_value_set_bool(*dest, cmp >= 0));
     }
     SUCCEED_RETURN(errctx);
 }
@@ -679,6 +699,7 @@ akerr_ErrorContext *akbasic_value_greater_than_equal(akbasic_Value *self, akbasi
 akerr_ErrorContext *akbasic_value_is_equal(akbasic_Value *self, akbasic_Value *rval, akbasic_Value *scratch, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    int cmp = 0;
 
     PASS(errctx, binary_prologue(self, rval, scratch, dest));
     if ( self->valuetype == AKBASIC_TYPE_INTEGER ) {
@@ -686,7 +707,8 @@ akerr_ErrorContext *akbasic_value_is_equal(akbasic_Value *self, akbasic_Value *r
     } else if ( self->valuetype == AKBASIC_TYPE_FLOAT ) {
 	PASS(errctx, akbasic_value_set_bool(*dest, self->floatval == rval_as_float(rval)));
     } else {
-	PASS(errctx, akbasic_value_set_bool(*dest, strcmp(self->stringval, rval->stringval) == 0));
+	PASS(errctx, aksl_strcmp(self->stringval, rval->stringval, &cmp));
+	PASS(errctx, akbasic_value_set_bool(*dest, cmp == 0));
     }
     SUCCEED_RETURN(errctx);
 }
@@ -694,6 +716,7 @@ akerr_ErrorContext *akbasic_value_is_equal(akbasic_Value *self, akbasic_Value *r
 akerr_ErrorContext *akbasic_value_is_not_equal(akbasic_Value *self, akbasic_Value *rval, akbasic_Value *scratch, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);
+    int cmp = 0;
 
     PASS(errctx, binary_prologue(self, rval, scratch, dest));
     if ( self->valuetype == AKBASIC_TYPE_INTEGER ) {
@@ -701,7 +724,8 @@ akerr_ErrorContext *akbasic_value_is_not_equal(akbasic_Value *self, akbasic_Valu
     } else if ( self->valuetype == AKBASIC_TYPE_FLOAT ) {
 	PASS(errctx, akbasic_value_set_bool(*dest, self->floatval != rval_as_float(rval)));
     } else {
-	PASS(errctx, akbasic_value_set_bool(*dest, strcmp(self->stringval, rval->stringval) != 0));
+	PASS(errctx, aksl_strcmp(self->stringval, rval->stringval, &cmp));
+	PASS(errctx, akbasic_value_set_bool(*dest, cmp != 0));
     }
     SUCCEED_RETURN(errctx);
 }

src/variable.c

@@ -4,9 +4,9 @@
  */
 
 #include <inttypes.h>
-#include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/error.h>
 #include <akbasic/variable.h>
@@ -53,7 +53,7 @@ akerr_ErrorContext *akbasic_variable_init(akbasic_Variable *obj, akbasic_ValuePo
 		     "Array dimension count %d out of range 1..%d",
 		     sizecount, AKBASIC_MAX_ARRAY_DEPTH);
 
-    namelen = strlen(obj->name);
+    PASS(errctx, aksl_strlen(obj->name, &namelen));
     FAIL_ZERO_RETURN(errctx, (namelen > 0), AKBASIC_ERR_VALUE, "Invalid variable name");
 
     /* Type comes from the suffix. A bare name keeps whatever type it had. */
@@ -202,16 +202,17 @@ akerr_ErrorContext *akbasic_variable_set_string(akbasic_Variable *obj, const cha
 {
     PREPARE_ERROR(errctx);
     akbasic_Value tmp;
+    size_t valuelen = 0;
 
     FAIL_ZERO_RETURN(errctx, (value != NULL), AKERR_NULLPOINTER, "NULL string in set_string");
-    FAIL_ZERO_RETURN(errctx, (strlen(value) < AKBASIC_MAX_STRING_LENGTH),
+    PASS(errctx, aksl_strlen(value, &valuelen));
+    FAIL_ZERO_RETURN(errctx, (valuelen < AKBASIC_MAX_STRING_LENGTH),
 		     AKBASIC_ERR_VALUE,
 		     "String of %zu characters exceeds the %d character limit",
-		     strlen(value), AKBASIC_MAX_STRING_LENGTH - 1);
+		     valuelen, AKBASIC_MAX_STRING_LENGTH - 1);
     PASS(errctx, akbasic_value_zero(&tmp));
     tmp.valuetype = AKBASIC_TYPE_STRING;
-    strncpy(tmp.stringval, value, AKBASIC_MAX_STRING_LENGTH - 1);
-    tmp.stringval[AKBASIC_MAX_STRING_LENGTH - 1] = '\0';
+    PASS(errctx, aksl_strcpy(tmp.stringval, sizeof(tmp.stringval), value));
     PASS(errctx, akbasic_variable_set_subscript(obj, &tmp, subscripts, subscriptcount));
     SUCCEED_RETURN(errctx);
 }

src/verbs.c

@@ -8,6 +8,7 @@
 #include <string.h>
 
 #include <akerror.h>
+#include <akstdlib.h>
 
 #include <akbasic/error.h>
 #include <akbasic/verbs.h>
@@ -197,6 +198,28 @@ static const akbasic_Verb VERBS[] = {
 
 #define VERB_COUNT ((int)(sizeof(VERBS) / sizeof(VERBS[0])))
 
+/**
+ * @brief bsearch(3) comparator for the verb table.
+ *
+ * **This is the one call in `src/` that stays on raw `strcmp` on purpose.**
+ * Everything else that reaches past libakstdlib to a function that library wraps
+ * has been converted to the wrapper and propagates the error context; the ruling
+ * that required it is libakstdlib #38, and the rule is that a function which
+ * cannot report an error changes its own signature rather than swallowing one.
+ *
+ * That remedy is unavailable here, and only here. `bsearch(3)` fixes the
+ * comparator's signature at `int (*)(const void *, const void *)`, so there is
+ * no out-parameter to hand an `akerr_ErrorContext *` back through and no return
+ * value that is not already the ordering. Converting this one site means
+ * dropping `bsearch` for an in-house binary search that can propagate -- a
+ * separate change to a lookup that runs once per scanned identifier, and a
+ * decision that belongs in its own issue rather than riding along with a port.
+ *
+ * The bypass is safe as written: `key` is the caller's NUL-terminated `upper`
+ * buffer and `element->name` is a string literal in the static table above, so
+ * neither argument can be NULL and neither can be unterminated -- which is the
+ * whole of what `aksl_strcmp` would have checked.
+ */
 static int verb_compare(const void *key, const void *element)
 {
     const akbasic_Verb *verb = (const akbasic_Verb *)element;
@@ -223,7 +246,7 @@ akerr_ErrorContext *akbasic_verb_lookup(const char *name, const akbasic_Verb **d
     FAIL_ZERO_RETURN(errctx, (dest != NULL), AKERR_NULLPOINTER, "NULL destination in verb lookup");
 
     *dest = NULL;
-    len = strlen(name);
+    PASS(errctx, aksl_strlen(name, &len));
     if ( len == 0 || len >= sizeof(upper) ) {
 	/* Too long to be any verb we know. Not an error, just a miss. */
 	SUCCEED_RETURN(errctx);

tests/docs_preludes/galagacalls.post

@@ -0,0 +1,10 @@
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    (void)SCRIPT; (void)SINK; (void)SINKSTATE; (void)SOURCE;
+    (void)args; (void)argp; (void)dtval; (void)result;
+    (void)enemy; (void)actor; (void)dt;
+    (void)SCRATCH_ENEMY; (void)SCRATCH_ACTOR; (void)galaga_shared;
+    (void)ENEMY_TYPE; (void)ACTOR_TYPE; (void)GAME_TYPE;
+    SUCCEED_RETURN(errctx);
+}

tests/docs_preludes/galagacalls.pre

@@ -0,0 +1,84 @@
+/*
+ * Prelude for the interpreter-facing fragments in docs/20: the boot sequence,
+ * the ADDEM proof and the rebind-call-reset protocol, shown as runs of CATCH
+ * calls. The statics are the ones examples/galaga/script.c keeps; the locals
+ * are the superset every fragment draws from, void-cast in the postlude so an
+ * unused one is not a warning.
+ */
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <SDL3/SDL.h>
+
+#include <akerror.h>
+#include <akstdlib.h>
+
+#include <akgl/actor.h>
+
+#include <akbasic/environment.h>
+#include <akbasic/error.h>
+#include <akbasic/host.h>
+#include <akbasic/runtime.h>
+#include <akbasic/sink.h>
+
+typedef struct galaga_docs_Enemy
+{
+    int32_t  kind;
+    int32_t  state;
+    float    homex;
+    float    homey;
+    float    t;
+    int32_t  hp;
+    int32_t  fire;
+    float    rnd;
+} galaga_docs_Enemy;
+
+typedef struct galaga_docs_Shared
+{
+    float    playerx;
+    float    playery;
+    int32_t  wave;
+    float    rnd;
+} galaga_docs_Shared;
+
+static akbasic_Runtime SCRIPT;
+static akbasic_TextSink SINK;
+static akbasic_StdioSink SINKSTATE;
+static char SOURCE[16384];
+
+static galaga_docs_Enemy SCRATCH_ENEMY;
+static akgl_Actor SCRATCH_ACTOR;
+static galaga_docs_Shared galaga_shared;
+
+static const akbasic_HostField ENEMY_FIELDS[] = {
+    AKBASIC_HOST_FIELD( galaga_docs_Enemy, kind, "KIND#", AKBASIC_HOSTFIELD_INT32 )
+};
+static const akbasic_HostType ENEMY_TYPE = {
+    "ENEMY", sizeof(galaga_docs_Enemy), ENEMY_FIELDS, 1
+};
+static const akbasic_HostField ACTOR_FIELDS[] = {
+    AKBASIC_HOST_FIELD( akgl_Actor, x, "X%", AKBASIC_HOSTFIELD_FLOAT )
+};
+static const akbasic_HostType ACTOR_TYPE = {
+    "ACTOR", sizeof(akgl_Actor), ACTOR_FIELDS, 1
+};
+static const akbasic_HostField GAME_FIELDS[] = {
+    AKBASIC_HOST_FIELD( galaga_docs_Shared, wave, "WAVE#", AKBASIC_HOSTFIELD_INT32 )
+};
+static const akbasic_HostType GAME_TYPE = {
+    "GAME", sizeof(galaga_docs_Shared), GAME_FIELDS, 1
+};
+
+akerr_ErrorContext AKERR_NOIGNORE *galaga_docs_fragment(galaga_docs_Enemy *enemy, akgl_Actor *actor, float dt);
+akerr_ErrorContext AKERR_NOIGNORE *galaga_docs_fragment(galaga_docs_Enemy *enemy, akgl_Actor *actor, float dt)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Value args[2];
+    akbasic_Value *argp[2];
+    akbasic_Value dtval;
+    akbasic_Value *result = NULL;
+
+    ATTEMPT {

tests/docs_preludes/galagagame.pre

@@ -0,0 +1,121 @@
+/*
+ * Prelude for file-scope fragments in docs/20 and docs/21 that assume the
+ * galaga example's own declarations already exist -- the shared structures
+ * from examples/galaga/galaga.h and the helpers a fragment calls but does not
+ * define. The types are copied rather than included so a fragment compiles
+ * against exactly what the chapter has shown so far; the helper declarations
+ * are invented prototypes, per the prelude policy in MAINTENANCE.md.
+ */
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <SDL3/SDL.h>
+#include <SDL3_ttf/SDL_ttf.h>
+
+#include <akerror.h>
+#include <akstdlib.h>
+
+#include <akgl/actor.h>
+#include <akgl/character.h>
+#include <akgl/controller.h>
+#include <akgl/draw.h>
+#include <akgl/error.h>
+#include <akgl/game.h>
+#include <akgl/heap.h>
+#include <akgl/physics.h>
+#include <akgl/registry.h>
+#include <akgl/renderer.h>
+#include <akgl/sprite.h>
+#include <akgl/text.h>
+#include <akgl/ui.h>
+#include <akgl/util.h>
+
+#include <akbasic/environment.h>
+#include <akbasic/error.h>
+#include <akbasic/host.h>
+#include <akbasic/runtime.h>
+#include <akbasic/sink.h>
+
+#define GALAGA_ENEMY_BEE	0
+#define GALAGA_ENEMY_BUTTERFLY	1
+#define GALAGA_ENEMY_BOSS	2
+#define GALAGA_ENEMY_KINDS	3
+#define GALAGA_MAX_ENEMIES	40
+#define GALAGA_MAX_PLAYER_SHOTS	2
+#define GALAGA_MAX_ENEMY_SHOTS	8
+#define GALAGA_ES_ENTERING	(1 << 0)
+#define GALAGA_ES_FORMATION	(1 << 1)
+#define GALAGA_ES_DIVING	(1 << 2)
+
+typedef struct galaga_Enemy
+{
+    int32_t  kind;
+    int32_t  state;
+    float    homex;
+    float    homey;
+    float    t;
+    int32_t  hp;
+    int32_t  fire;
+    float    rnd;
+} galaga_Enemy;
+
+typedef struct galaga_Shared
+{
+    float    playerx;
+    float    playery;
+    int32_t  wave;
+    float    rnd;
+} galaga_Shared;
+
+typedef enum
+{
+    GALAGA_SCREEN_TITLE = 0,
+    GALAGA_SCREEN_PLAY,
+    GALAGA_SCREEN_GAMEOVER,
+    GALAGA_SCREEN_VICTORY
+} galaga_Screen;
+
+typedef struct galaga_Game
+{
+    galaga_Screen screen;
+    int      frame;
+    float    dt;
+    bool     autoplay;
+    int      score;
+    int      lives;
+    int      kills[GALAGA_ENEMY_KINDS];
+    int      shots[GALAGA_ENEMY_KINDS];
+    int      script_errors;
+    akgl_Actor *player;
+    float    fire_cooldown;
+    float    respawn_timer;
+    bool     firing;
+    bool     moveleft;
+    bool     moveright;
+    int      player_shots_live;
+    int      enemy_shots_live;
+} galaga_Game;
+
+extern galaga_Game galaga_game;
+extern galaga_Shared galaga_shared;
+extern galaga_Enemy galaga_enemies[GALAGA_MAX_ENEMIES];
+extern akgl_Actor *galaga_enemy_actors[GALAGA_MAX_ENEMIES];
+
+float galaga_random(void);
+akerr_ErrorContext AKERR_NOIGNORE *galaga_script_update_enemy(galaga_Enemy *enemy, akgl_Actor *actor, float dt);
+akerr_ErrorContext AKERR_NOIGNORE *galaga_boom_spawn(float x, float y);
+akerr_ErrorContext AKERR_NOIGNORE *enemy_fire(galaga_Enemy *enemy, akgl_Actor *from);
+akerr_ErrorContext AKERR_NOIGNORE *kill_enemy(int index);
+akerr_ErrorContext AKERR_NOIGNORE *player_update(akgl_Actor *obj);
+akerr_ErrorContext AKERR_NOIGNORE *left_on(akgl_Actor *obj, SDL_Event *event);
+akerr_ErrorContext AKERR_NOIGNORE *left_off(akgl_Actor *obj, SDL_Event *event);
+akerr_ErrorContext AKERR_NOIGNORE *right_on(akgl_Actor *obj, SDL_Event *event);
+akerr_ErrorContext AKERR_NOIGNORE *right_off(akgl_Actor *obj, SDL_Event *event);
+akerr_ErrorContext AKERR_NOIGNORE *fire_on(akgl_Actor *obj, SDL_Event *event);
+akerr_ErrorContext AKERR_NOIGNORE *fire_off(akgl_Actor *obj, SDL_Event *event);
+void shot_box(akgl_Actor *actor, SDL_FRect *dest);
+void enemy_box(akgl_Actor *actor, SDL_FRect *dest);
+void player_box(akgl_Actor *actor, SDL_FRect *dest);

tests/docs_preludes/galagahost.post

@@ -0,0 +1,6 @@
+    } CLEANUP {
+    } PROCESS(errctx) {
+    } FINISH(errctx, true);
+    (void)event;
+    SUCCEED_RETURN(errctx);
+}

tests/docs_preludes/galagahost.pre

@@ -0,0 +1,55 @@
+/*
+ * Prelude for statement-context fragments in docs/20: runs of CATCH calls
+ * from the galaga frame loop, shown without their scaffolding because the
+ * ATTEMPT protocol is the scaffolding. Same policy as hostcalls.pre.
+ */
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <SDL3/SDL.h>
+#include <SDL3_ttf/SDL_ttf.h>
+
+#include <akerror.h>
+#include <akstdlib.h>
+
+#include <akgl/actor.h>
+#include <akgl/controller.h>
+#include <akgl/draw.h>
+#include <akgl/game.h>
+#include <akgl/heap.h>
+#include <akgl/renderer.h>
+#include <akgl/ui.h>
+
+#include <akbasic/error.h>
+#include <akbasic/runtime.h>
+
+typedef enum
+{
+    GALAGA_SCREEN_TITLE = 0,
+    GALAGA_SCREEN_PLAY,
+    GALAGA_SCREEN_GAMEOVER,
+    GALAGA_SCREEN_VICTORY
+} galaga_Screen;
+
+struct galaga_docs_Game
+{
+    galaga_Screen screen;
+    float dt;
+    akgl_Actor *player;
+};
+extern struct galaga_docs_Game galaga_game;
+extern akgl_Actor *galaga_enemy_actors[40];
+
+akerr_ErrorContext AKERR_NOIGNORE *declare_title(void);
+akerr_ErrorContext AKERR_NOIGNORE *declare_play(void);
+akerr_ErrorContext AKERR_NOIGNORE *declare_end(void);
+akerr_ErrorContext AKERR_NOIGNORE *galaga_docs_fragment(void);
+akerr_ErrorContext AKERR_NOIGNORE *galaga_docs_fragment(void)
+{
+    PREPARE_ERROR(errctx);
+    SDL_Event event;
+
+    ATTEMPT {

tests/docs_preludes/galagatypes.pre

@@ -0,0 +1,37 @@
+/*
+ * Prelude for the self-contained file-scope fragments in docs/20 and docs/21:
+ * blocks that define a struct, a table or a whole function from scratch need
+ * only the includes. Only compiled in the AKBASIC_WITH_AKGL build.
+ */
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <SDL3/SDL.h>
+#include <SDL3_ttf/SDL_ttf.h>
+
+#include <akerror.h>
+#include <akstdlib.h>
+
+#include <akgl/actor.h>
+#include <akgl/character.h>
+#include <akgl/controller.h>
+#include <akgl/draw.h>
+#include <akgl/error.h>
+#include <akgl/game.h>
+#include <akgl/heap.h>
+#include <akgl/physics.h>
+#include <akgl/registry.h>
+#include <akgl/renderer.h>
+#include <akgl/sprite.h>
+#include <akgl/text.h>
+#include <akgl/ui.h>
+#include <akgl/util.h>
+
+#include <akbasic/environment.h>
+#include <akbasic/error.h>
+#include <akbasic/host.h>
+#include <akbasic/runtime.h>
+#include <akbasic/sink.h>

tests/docs_preludes/hostcalls.post

@@ -2,5 +2,7 @@
     } PROCESS(errctx) {
     } FINISH(errctx, true);
     (void)score;
+    (void)argp;
+    (void)result;
     SUCCEED_RETURN(errctx);
 }

tests/docs_preludes/hostcalls.pre

@@ -7,6 +7,7 @@
  * surrounding prose says exists but does not print.
  */
 #include <akerror.h>
+#include <akbasic/environment.h>
 #include <akbasic/error.h>
 #include <akbasic/runtime.h>
 #include <akbasic/variable.h>
@@ -23,5 +24,7 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_docs_fragment(void)
 {
     PREPARE_ERROR(errctx);
     int64_t score = 0;
+    akbasic_Value *argp[4];
+    akbasic_Value *result = NULL;
 
     ATTEMPT {

tests/environment_scope.c

@@ -13,6 +13,7 @@ int main(void)
     akbasic_Variable *again = NULL;
     akbasic_Value *value = NULL;
     int64_t lineno = 0;
+    bool waiting = false;
     int i = 0;
 
     TEST_REQUIRE_OK(harness_start(NULL));
@@ -57,24 +58,34 @@ int main(void)
     TEST_REQUIRE_STATUS(akbasic_runtime_prev_environment(&HARNESS_RUNTIME),
 			AKBASIC_ERR_ENVIRONMENT);
 
-    /* The wait mechanism, including the parent-chain search. */
-    TEST_REQUIRE(!akbasic_environment_is_waiting_for_any(root), "a fresh environment waits for nothing");
+    /*
+     * The wait mechanism, including the parent-chain search. Both predicates
+     * report through an out-parameter and return an error context, so each
+     * assertion is a TEST_REQUIRE_OK on the call and a TEST_REQUIRE on the
+     * answer. See libakstdlib #38.
+     */
+    TEST_REQUIRE_OK(akbasic_environment_is_waiting_for_any(root, &waiting));
+    TEST_REQUIRE(!waiting, "a fresh environment waits for nothing");
     TEST_REQUIRE_OK(akbasic_environment_wait_for_command(root, "NEXT"));
-    TEST_REQUIRE(akbasic_environment_is_waiting_for_any(root), "the wait must register");
-    TEST_REQUIRE(akbasic_environment_is_waiting_for(root, "NEXT"), "the wait must match by name");
-    TEST_REQUIRE(!akbasic_environment_is_waiting_for(root, "DATA"), "a different verb must not match");
+    TEST_REQUIRE_OK(akbasic_environment_is_waiting_for_any(root, &waiting));
+    TEST_REQUIRE(waiting, "the wait must register");
+    TEST_REQUIRE_OK(akbasic_environment_is_waiting_for(root, "NEXT", &waiting));
+    TEST_REQUIRE(waiting, "the wait must match by name");
+    TEST_REQUIRE_OK(akbasic_environment_is_waiting_for(root, "DATA", &waiting));
+    TEST_REQUIRE(!waiting, "a different verb must not match");
 
     /* Two pending waits in one environment is a hard error, not a panic. */
     TEST_REQUIRE_STATUS(akbasic_environment_wait_for_command(root, "DATA"), AKBASIC_ERR_STATE);
 
     TEST_REQUIRE_OK(akbasic_runtime_new_environment(&HARNESS_RUNTIME));
     child = HARNESS_RUNTIME.environment;
-    TEST_REQUIRE(akbasic_environment_is_waiting_for(child, "NEXT"),
-		 "a child must see its parent's wait");
+    TEST_REQUIRE_OK(akbasic_environment_is_waiting_for(child, "NEXT", &waiting));
+    TEST_REQUIRE(waiting, "a child must see its parent's wait");
     TEST_REQUIRE_OK(akbasic_runtime_prev_environment(&HARNESS_RUNTIME));
 
     TEST_REQUIRE_OK(akbasic_environment_stop_waiting(root, "NEXT"));
-    TEST_REQUIRE(!akbasic_environment_is_waiting_for_any(root), "stop_waiting must clear it");
+    TEST_REQUIRE_OK(akbasic_environment_is_waiting_for_any(root, &waiting));
+    TEST_REQUIRE(!waiting, "stop_waiting must clear it");
 
     /* The per-line value pool is bounded and says so. */
     for ( i = 0; i < AKBASIC_MAX_VALUES; i++ ) {

tests/language/statements/rem_indented_line.bas

@@ -0,0 +1,14 @@
+REM The line after this comment is indented, and it must still run: the
+REM scanner's REM early-exit used to leave TOK_REM armed, and the next
+REM line's leading whitespace re-triggered it -- every indented line
+REM after a REM was silently skipped. Unnumbered on purpose: a numbered
+REM line's first token overwrites the leftover and hides the defect.
+PRINT 1
+REM an indented statement follows
+  PRINT 2
+REM an indented multi-line DEF body, the shape that found it
+DEF F(N#)
+  REM a comment inside the body
+  RETURN N# + 5
+PRINT F(10)
+END

tests/language/statements/rem_indented_line.txt

@@ -0,0 +1,3 @@
+1
+2
+15

tests/user_functions.c

@@ -337,6 +337,113 @@ static void test_call_from_c(void)
     harness_stop();
 }
 
+/**
+ * @brief A long multi-line body called from C completes.
+ *
+ * The value scratch is a *per line* limit, and the call loop has to reset it
+ * per line the way akbasic_runtime_step() does. It did not: the scratch
+ * accumulated across the whole body, and any body past about ten real lines
+ * died with "Maximum values per line reached" -- silently, from the caller's
+ * point of view, because a BASIC-level error inside the loop reports through
+ * the sink and comes back as a zero (issue #7's shape). Found by the galaga
+ * example, whose enemy functions are all longer than ten lines.
+ *
+ * The set_mode(RUN) between the load and the call is the issue #8 workaround:
+ * the body only runs in RUN mode, and the program has already ended.
+ */
+static void test_long_body_called_from_c(void)
+{
+    akbasic_Value arg;
+    akbasic_Value *argp[1];
+    akbasic_Value *result = NULL;
+
+    TEST_REQUIRE_OK(run_program("10 DEF LONGB(N#)\n"
+				"20   A# = N# + 1\n"
+				"30   B# = A# + 1\n"
+				"40   C# = B# + 1\n"
+				"50   D# = C# + 1\n"
+				"60   E# = D# + 1\n"
+				"70   F# = E# + 1\n"
+				"80   G# = F# + 1\n"
+				"90   H# = G# + 1\n"
+				"100  I# = H# + 1\n"
+				"110  J# = I# + 1\n"
+				"120  K# = J# + 1\n"
+				"130  L# = K# + 1\n"
+				"140  M# = L# + 1\n"
+				"150  P# = M# + 1\n"
+				"160  Q# = P# + 1\n"
+				"170  R# = Q# + 1\n"
+				"180  RETURN R#\n"));
+    TEST_REQUIRE_OK(akbasic_runtime_set_mode(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+
+    memset(&arg, 0, sizeof(arg));
+    arg.valuetype = AKBASIC_TYPE_INTEGER;
+    arg.intval = 1;
+    argp[0] = &arg;
+    TEST_REQUIRE_OK(akbasic_runtime_call_function(&HARNESS_RUNTIME, "LONGB", argp, 1, &result));
+    TEST_REQUIRE(result != NULL, "a call should have produced a result");
+    TEST_REQUIRE_INT(result->intval, 17);
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "");
+    harness_stop();
+}
+
+/**
+ * @brief A body that dies leaves the environment stack balanced.
+ *
+ * A runtime error inside a called body reports through the sink and ends the
+ * run -- that part is unchanged, and the caller still gets the zeroed slot
+ * (issue #7 tracks whether it should). What must NOT happen is what did: the
+ * call's environment was never given back, so a host that absorbed script
+ * errors and kept calling drained the twelve-slot pool after twelve dead
+ * calls, and every later call failed with "Environment pool exhausted" -- an
+ * exhaustion nothing in the script explains.
+ *
+ * The revival dance after each death is two calls: clear_error(), because a
+ * run's first error latches and every later line is skipped while it stands,
+ * and set_mode(RUN), the issue #8 workaround the boot already needed --
+ * the error dropped the runtime out of RUN mode.
+ */
+static void test_dead_body_releases_environments(void)
+{
+    akbasic_Value arg;
+    akbasic_Value *argp[1];
+    akbasic_Value *result = NULL;
+    akbasic_Environment *root = NULL;
+    int i = 0;
+
+    TEST_REQUIRE_OK(run_program("10 DEF DIE(N#)\n"
+				"20   X# = NOSUCH(N#)\n"
+				"30   RETURN X#\n"
+				"40 DEF FINE(N#)\n"
+				"50   Y# = N# * 2\n"
+				"60   RETURN Y#\n"));
+    TEST_REQUIRE_OK(akbasic_runtime_set_mode(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    root = HARNESS_RUNTIME.environment;
+
+    memset(&arg, 0, sizeof(arg));
+    arg.valuetype = AKBASIC_TYPE_INTEGER;
+    arg.intval = 7;
+    argp[0] = &arg;
+
+    /* Fifteen deaths: more than the pool holds, so a single leaked scope
+     * fails this loop even if the first twelve limp through. */
+    for ( i = 0; i < 15; i++ ) {
+	TEST_REQUIRE_OK(akbasic_runtime_call_function(&HARNESS_RUNTIME, "DIE", argp, 1, &result));
+	TEST_REQUIRE(HARNESS_RUNTIME.environment == root,
+		     "a dead call must unwind back to the caller's environment");
+	TEST_REQUIRE_OK(akbasic_runtime_clear_error(&HARNESS_RUNTIME));
+	TEST_REQUIRE_OK(akbasic_runtime_set_mode(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    }
+
+    /* And the runtime is still whole: a healthy function runs to the right
+     * answer after every one of those deaths. */
+    TEST_REQUIRE_OK(akbasic_runtime_call_function(&HARNESS_RUNTIME, "FINE", argp, 1, &result));
+    TEST_REQUIRE(result != NULL, "a call should have produced a result");
+    TEST_REQUIRE_INT(result->intval, 14);
+    harness_stop();
+}
+
 int main(void)
 {
     TEST_REQUIRE_OK(akbasic_error_register());
@@ -351,6 +458,8 @@ int main(void)
     test_call_scopes_are_reclaimed();
     test_calls_do_not_leak_value_slots();
     test_call_from_c();
+    test_long_body_called_from_c();
+    test_dead_body_releases_environments();
 
     return akbasic_test_failures;
 }