Close the remaining cold-read gaps: bind, labels, menus and main's shape

Three more Haiku-class cold reads of the chapters, each against the
amended text. What each surfaced is now shown rather than described: the
akbasic_host_register_type()/akbasic_host_bind() boot calls, the
declare_play() label listing, the akgl_UiMenu static and its
handle_event signature, one control-handler pair, and main()'s
ATTEMPT/HANDLE_DEFAULT/FINISH_NORETURN shape with the CATCH-inside-
ATTEMPT rule stated. By the fourth read the generated player.c and
enemies.c compiled untouched and every remaining guess was a tuning
value the chapters deliberately leave open.

Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc

.gitea/workflows/ci.yaml

@@ -17,7 +17,7 @@ jobs:
           # Not recursive, deliberately. The top-level build needs
           # deps/libakerror and deps/libakstdlib, via add_subdirectory, and
           # nothing else: the golden corpus and the Commodore font now live in
-          # this repository (tests/language/ and assets/fonts/), so
+          # this repository (tests/reference/ and assets/fonts/), so
           # deps/basicinterpret is no longer a build dependency at all.
           # It does *not* need deps/libakgl, which is guarded behind
           # AKBASIC_WITH_AKGL and defaults OFF -- and recursing into it would
@@ -62,9 +62,11 @@ jobs:
         run: |
           cmake -S . -B build
           cmake --build build --parallel 2
-      # The suite is 112 cases: 65 language files with sibling expectations,
-      # 43 unit tests, 3 embedding examples, and docs_examples.
-      # Some unit tests assert the *correct* contract for known defects (TODO.md
+      # 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
+      # tests, 2 embedding examples, and 1 known-failing test that asserts the
+      # *correct* contract for defects carried over from the reference (TODO.md
       # section 6). A green run therefore does not mean defect-free -- see
       # AKBASIC_KNOWN_FAILING_TESTS.
       #

.gitea/workflows/mutation.yaml

@@ -1,48 +0,0 @@
-name: akbasic Mutation Testing
-run-name: ${{ gitea.actor }} akbasic mutation test
-
-# Mutation testing is intentionally isolated from push and merge checks. The
-# complete src/ tree takes hours and must not consume the shared CI capacity
-# during normal development.
-on:
-  # Gitea schedules use UTC. 07:00 UTC is 02:00 EST (the requested fixed
-  # Eastern Standard Time slot).
-  schedule:
-    - cron: '0 7 * * *'
-  workflow_dispatch:
-
-jobs:
-  full_mutation:
-    runs-on: ubuntu-latest
-    timeout-minutes: 720
-    steps:
-      - name: Check out repository code
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-      - name: dependencies
-        run: |
-          sudo apt-get update -y
-          sudo apt-get install -y cmake gcc python3 moreutils
-      - name: mutation testing (full tree)
-        run: |
-          python3 scripts/mutation_test.py \
-            --junit mutation-junit.xml \
-            --threshold 65
-      - name: publish mutation results
-        if: always()
-        uses: mikepenz/action-junit-report@v4
-        with:
-          report_paths: 'mutation-junit.xml'
-          annotate_only: true
-          detailed_summary: true
-          include_passed: true
-          fail_on_failure: 'false'
-      - name: upload mutation report
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: mutation-report
-          path: mutation-junit.xml
-          if-no-files-found: warn
-      - run: echo "🍏 This job's status is ${{ job.status }}."

.gitea/workflows/release.yaml

@@ -1,13 +1,24 @@
 name: akbasic Release Build
 run-name: ${{ gitea.actor }} akbasic release checks
-# Manual only. Nothing here runs on push: documentation is a release gate, not
-# a per-commit check. The expensive mutation suite has its own daily schedule.
+# Manual only. Nothing here runs on push: the full mutation set is thousands of
+# mutants and hours of runner time, which is a release-gate cost, not a
+# per-commit one. Trigger it from the Actions tab.
 on:
   workflow_dispatch:
+    inputs:
+      mutation_threshold:
+        description: "Fail if the mutation score falls below this percentage"
+        required: false
+        default: "65"
+      mutation_targets:
+        description: "Space-separated files to mutate; empty means the whole src/ tree"
+        required: false
+        default: ""
 
 jobs:
   # Moved here from ci.yaml. The docs are wanted for a release, not on every
-  # push.
+  # push, and building them beside the release mutation run keeps the two
+  # artefacts a release needs in one place.
   docs:
     runs-on: ubuntu-latest
     steps:
@@ -41,3 +52,89 @@ jobs:
           path: build/docs/html/
           if-no-files-found: error
       - run: echo "🍏 This job's status is ${{ job.status }}."
+
+  full_mutation:
+    runs-on: ubuntu-latest
+    # 3675 mutants across the whole src/ tree. Cost per mutant is one incremental
+    # rebuild plus one full ctest run, which measures at roughly 2s for a leaf
+    # file and 11s for src/value.c, where almost everything links against it.
+    # Budget most of a day and expect it to finish well inside that; the ceiling
+    # exists so a mutant that wedges the runner cannot hold it forever.
+    timeout-minutes: 720
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+        with:
+          # The harness copies the repo and configures a build inside the copy,
+          # so it needs the same submodules the main build does. The golden
+          # 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 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.
+      #
+      # Mutation testing is the only gate that sees the error-handling control
+      # flow at all: libakerror's ATTEMPT/CATCH/PASS macros expand at their call
+      # sites, so gcov attributes them to the caller and line coverage cannot
+      # measure them.
+      #
+      # The default threshold matches ci.yaml's rather than being stricter.
+      # Whole-tree coverage is uneven -- src/symtab.c is the only file measured
+      # on the push path, at 74.1%, and the rest is unmeasured, so a tighter
+      # number here would be a guess. Raise it with the workflow input once a
+      # full run has established a real baseline.
+      #
+      # The two inputs arrive through the environment rather than being
+      # interpolated straight into the script. ${{ }} substitution happens before
+      # the shell sees the line, so a value containing shell metacharacters would
+      # otherwise run as code. This workflow is manual and owner-triggered, but
+      # the safe form costs nothing.
+      - name: mutation testing (full tree)
+        env:
+          MUTATION_TARGETS: ${{ gitea.event.inputs.mutation_targets }}
+          MUTATION_THRESHOLD: ${{ gitea.event.inputs.mutation_threshold }}
+        run: |
+          set -eu
+          # Word-splitting is the point here: the input is a space-separated
+          # list. An empty input leaves $targets empty and the harness falls
+          # through to its own default, which is the whole src/ tree.
+          targets=""
+          for f in ${MUTATION_TARGETS:-}; do
+            targets="$targets --target $f"
+          done
+          # shellcheck disable=SC2086
+          python3 scripts/mutation_test.py \
+            $targets \
+            --junit mutation-junit.xml \
+            --threshold "${MUTATION_THRESHOLD:-65}"
+      # Publish even when the threshold gate fails, so survivors are visible --
+      # each one is a missing test. Display-only (fail_on_failure: false); the
+      # --threshold above is the gate. annotate_only avoids the Checks API 404
+      # on Gitea (mikepenz/action-junit-report#23).
+      - name: publish mutation results
+        if: always()
+        uses: mikepenz/action-junit-report@v4
+        with:
+          report_paths: 'mutation-junit.xml'
+          annotate_only: true
+          detailed_summary: true
+          include_passed: true
+          fail_on_failure: 'false'
+      # Keep the raw report as well as the annotations: a release wants the
+      # survivor list on file, and the job summary is not durable.
+      - name: upload mutation report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-report
+          path: mutation-junit.xml
+          if-no-files-found: warn
+      - run: echo "🍏 This job's status is ${{ job.status }}."

CLAUDE.md

@@ -57,9 +57,9 @@ repeating where you will see them:
   `include/akgl/SDL_GameControllerDB.h`. Change the template or the generator script.
 - **Do not reformat code you are not otherwise changing.** Several files mix tabs and spaces
   and there is no repo-wide formatter; style conversions get their own commit.
-- **Keep `tests/language/` editable.** Its `.bas` programs and sibling `.txt` expectations
-  are changed together when behavior changes. Record deliberate language decisions in
-  `TODO.md` or `docs/13-differences.md`.
+- **Do not edit `tests/reference/`.** Those expectations came from the Go implementation and
+  are never edited to suit this interpreter. A deliberate divergence goes in
+  `tests/reference/README.md`'s divergence table and `docs/13-differences.md`.
 - **Open an issue for outstanding work; do not add it to `TODO.md`.**
   <https://source.starfort.tech/andrew/akbasic/issues>, or `tea issues create --repo
   andrew/akbasic`. Name the file and line, the functional consequence, and what closing it would

CMakeLists.txt

@@ -51,14 +51,12 @@ option(AKBASIC_SANITIZE  "Build with ASan + UBSan"                           OFF
 # through: the dependencies set target and directory properties that their own
 # builds depend on.
 #
-# All three dependencies now namespace both their `coverage` and their
-# `mutation` targets when embedded, so there is no custom-target collision left
-# to work around. libakerror was the last holdout -- it namespaced `mutation`
-# but not `coverage`, and a coverage build collided on the bare name and failed
-# to configure at all. 2.0.2 applies the same CMAKE_SOURCE_DIR test to both
-# (deps/libakerror/CMakeLists.txt:429-434), closing libakerror issue #15, and
-# the add_custom_target() shadow that renamed it on the way past is gone with
-# this comment.
+# libakerror additionally namespaces its `mutation` target when embedded but not
+# its `coverage` target (deps/libakerror/CMakeLists.txt:194 vs :172), so a
+# coverage build collides on the `coverage` target and fails to configure at all.
+# Rename the dependency's on the way past. Remove this once libakerror applies
+# the same CMAKE_SOURCE_DIR test to `coverage` that it already applies to
+# `mutation` -- filed as libakerror issue #15.
 #
 # **Only one project in a tree may shadow add_test(), and this is that project.**
 # CMake exposes an overridden command as `_name` and chains exactly one level: a
@@ -88,6 +86,14 @@ function(set_property _scope)
   endif()
 endfunction()
 
+function(add_custom_target _name)
+  if(AKBASIC_SUPPRESS_ADD_TEST AND _name STREQUAL "coverage")
+    _add_custom_target(akerror_coverage ${ARGN})
+  else()
+    _add_custom_target(${ARGV})
+  endif()
+endfunction()
+
 add_subdirectory(deps/libakerror EXCLUDE_FROM_ALL)
 add_subdirectory(deps/libakstdlib EXCLUDE_FROM_ALL)
 if(AKBASIC_WITH_AKGL)
@@ -143,7 +149,6 @@ set(AKBASIC_SOURCES
   src/runtime_disk.c
   src/runtime_format.c
   src/runtime_functions.c
-  src/runtime_generator.c
   src/runtime_graphics.c
   src/runtime_housekeeping.c
   src/runtime_machine.c
@@ -353,7 +358,6 @@ set(AKBASIC_TESTS
   error_codes
   for_next
   format_verbs
-  generators
   grammar_leaves
   graphics_verbs
   hoststruct
@@ -507,7 +511,7 @@ if(AKBASIC_WITH_AKGL)
   # against.
   #
   # **A byte comparison of a rendered PNG is a deliberate bet**, the same bet
-  # the language corpus makes about golden output: that the dummy video
+  # tests/reference/ already makes about golden output: that the dummy video
   # driver and the software renderer are reproducible. They are, run to run and
   # build to build. What is untested is an SDL upgrade that shifts one pixel of
   # a diagonal, and the answer to that is to regenerate the figures in the same
@@ -590,20 +594,63 @@ if(AKBASIC_WILL_FAIL_TESTS OR AKBASIC_KNOWN_FAILING_TESTS)
   )
 endif()
 
-# The editable language corpus. One CTest case per .bas so a failure names the
-# file. Each program is paired with a sibling .txt expectation; see
-# tests/language/README.md for the editing rule.
+# The reference's own corpus, byte-compared against the sibling .txt. One CTest
+# case per .bas so a failure names the file.
 #
-# The corpus includes programs carried over from the deprecated Go implementation
-# and cases written for this interpreter. Their provenance is useful when
-# investigating a regression, but it does not make any case immutable.
+# It used to be driven in place out of deps/basicinterpret, on the reasoning that
+# copying a submodule's corpus guarantees drift. That reasoning was sound and it
+# has been overruled deliberately: the Go dependency is being deprecated, and a
+# build that cannot run its acceptance suite without cloning the implementation
+# it replaced is not finished. The copy is byte-identical to
+# basicinterpreter@d76162c and tests/reference/README.md records
+# where it came from and what the drift now costs.
+file(GLOB_RECURSE AKBASIC_GOLDEN_CASES
+  RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}/tests/reference"
+  "${CMAKE_CURRENT_SOURCE_DIR}/tests/reference/*.bas"
+)
+
+foreach(_case IN LISTS AKBASIC_GOLDEN_CASES)
+  string(REGEX REPLACE "^tests/" "" _name "${_case}")
+  string(REGEX REPLACE "\\.bas$" "" _name "${_name}")
+  string(REPLACE "/" "_" _name "${_name}")
+  _add_test(
+    NAME golden_${_name}
+    COMMAND ${CMAKE_COMMAND}
+            -DBASIC=$<TARGET_FILE:basic>
+            -DCASE=${CMAKE_CURRENT_SOURCE_DIR}/tests/reference/${_case}
+            -P ${CMAKE_CURRENT_SOURCE_DIR}/tests/golden.cmake
+  )
+endforeach()
+
+if(AKBASIC_GOLDEN_CASES)
+  set(AKBASIC_GOLDEN_NAMES)
+  foreach(_case IN LISTS AKBASIC_GOLDEN_CASES)
+    string(REGEX REPLACE "^tests/" "" _name "${_case}")
+    string(REGEX REPLACE "\\.bas$" "" _name "${_name}")
+    string(REPLACE "/" "_" _name "${_name}")
+    list(APPEND AKBASIC_GOLDEN_NAMES golden_${_name})
+  endforeach()
+  _set_tests_properties(${AKBASIC_GOLDEN_NAMES} PROPERTIES TIMEOUT 30)
+  # An AKGL build of `basic` opens a window, and forty-one of them is not what
+  # anybody running the suite wanted. The dummy driver produces the same stdout,
+  # which is the only thing a golden case compares.
+  if(AKBASIC_WITH_AKGL)
+    _set_tests_properties(${AKBASIC_GOLDEN_NAMES} PROPERTIES
+      ENVIRONMENT "SDL_VIDEODRIVER=dummy;SDL_AUDIODRIVER=dummy;SDL_RENDER_DRIVER=software")
+  endif()
+endif()
+
+# The local golden corpus, for verbs the reference never implemented.
 #
-# Programs carried over from the deprecated Go implementation and cases written
-# for this interpreter use the same editable `.bas`/`.txt` contract. Registered
-# under local_ so every failure identifies the program that produced it.
+# Still separate now that the reference's corpus lives in this repository too,
+# and the reason changed rather than went away: tests/reference/ is a *record* of
+# what the Go implementation did and nothing in it should ever be edited to suit
+# this one, while tests/language/ is ours to change. Registered under local_ so a
+# failure says at a glance which of the two it came from -- and so a diff that
+# touches tests/reference/ stands out as the thing it is.
 #
 # Note what this can and cannot cover. The graphics and sound verbs draw and play
-# rather than print, so what a golden file sees of them is their refusals and
+# rather than print, so what a golden file sees of them is their *refusals* and
 # whatever a program can PRINT about the state they changed. The behaviour that
 # reaches a device is asserted against tests/mockdevice.h instead.
 file(GLOB_RECURSE AKBASIC_LOCAL_CASES

Doxyfile

@@ -12,4 +12,3 @@ WARN_AS_ERROR          = FAIL_ON_WARNINGS
 GENERATE_HTML          = YES
 GENERATE_LATEX         = NO
 QUIET                  = YES
-DOT_GRAPH_MAX_NODES    = 100

MAINTENANCE.md

@@ -68,19 +68,12 @@ the `akgl_*` or `aksl_*` entry point should look like, and what tests would cove
 decision, which is true of *changing* it and not of *reporting* it. Follow the prose-paragraph style of the entries already
 there. Growing the dependency to serve the interpreter is a wanted outcome, not a detour.
 
-It works. **Five** gaps were filed this way and all five landed upstream: text measurement,
-immediate-mode drawing, audio and a non-blocking keystroke read became `akgl_text_measure`,
-the `akgl_draw_*` family, `akgl_audio_*` and `akgl_controller_poll_key`; and the
-directory-reading wrapper `DIRECTORY` was waiting on became `aksl_opendir`, `aksl_readdir`,
-`aksl_closedir` and `aksl_rewinddir` — `libakstdlib` issue #10, in the revision this tree
-pins.
-
-That leaves the two refusals in different positions, and the difference is worth keeping
-straight. **`FILTER` is the one verb still blocked on a gap** — there is no filter stage in
-`akgl_audio_*` to configure. **`DIRECTORY` is no longer blocked on anything**; it is simply
-unwritten, and its refusal says so rather than naming a wrapper that now exists. Both refuse
-at execution and say so, rather than being silently ignored: a program that asks for a
-low-pass filter and gets an unfiltered square wave has been lied to.
+It works. Four gaps were filed this way — text measurement, immediate-mode drawing, audio,
+and a non-blocking keystroke read — and all four landed upstream as `akgl_text_measure`, the
+`akgl_draw_*` family, `akgl_audio_*` and `akgl_controller_poll_key`. `FILTER` is the one verb
+still blocked on a gap, and `DIRECTORY` is refused pending an `opendir`/`readdir` wrapper in
+`libakstdlib`. Both refuse at execution and say so, rather than being silently ignored: a
+program that asks for a low-pass filter and gets an unfiltered square wave has been lied to.
 
 ### The Go reference
 
@@ -95,7 +88,7 @@ source stays readable as documentation of what the original did. Neither is bind
 
 **It is not a build or test dependency.** Both configurations have been configured, built and
 run from scratch with it moved out of the tree. Its acceptance corpus is checked in at
-`tests/language/` and its Commodore font at `assets/fonts/`.
+`tests/reference/` and its Commodore font at `assets/fonts/`.
 
 ```sh norun
 cd deps/basicinterpret
@@ -163,10 +156,10 @@ guards every dependency with `if(NOT TARGET ...)`, so a top-level build must def
 `akerror::akerror` and `akstdlib::akstdlib` from `deps/libakerror` and `deps/libakstdlib`
 **before** `add_subdirectory(deps/libakgl)`, or the targets are declared twice.
 
-That order is load-bearing for a second reason: `deps/libakerror` is at **2.0.3**, whose 2.0.0
+That order is load-bearing for a second reason: `deps/libakerror` is at **2.0.1**, whose 2.0.0
 was a source and ABI break carrying an soname (`libakerror.so.2`). `libakstdlib` and `libakgl`
 must be compiled against that header, not a 1.x one, and an installed `libakerror.so.1` must
-not be picked up. The break is quiet if you get it wrong: the context behind `IGNORE` became
+not be picked up. The break is quiet if you get it wrong: `__akerr_last_ignored` became
 thread-local and `akerr_next_error()` now returns a context that already holds a reference, so
 a mixed build leaks pool slots or frees one twice rather than failing to link.
 
@@ -174,23 +167,10 @@ a mixed build leaks pool slots or frees one twice rather than failing to link.
 
 | Submodule | Version | soname | ABI rule | Version API |
 |---|---|---|---|---|
-| `deps/libakerror` | 2.0.3 | `libakerror.so.2` | major only | **none** — no version macro; `include/akbasic/error.h` feature-tests `AKERR_THREAD_SAFE` and `AKERR_EXIT_STATUS_UNREPRESENTABLE` instead |
+| `deps/libakerror` | 2.0.1 | `libakerror.so.2` | major only | **none** — no version macro; `include/akbasic/error.h` feature-tests `AKERR_THREAD_SAFE` and `AKERR_EXIT_STATUS_UNREPRESENTABLE` instead |
 | `deps/libakstdlib` | 0.2.0 | `libakstdlib.so.0.2` | **`MAJOR.MINOR` while major is 0** | `AKSL_VERSION_*`, `aksl_version()`, `AKSL_VERSION_CHECK()` |
 | `deps/libakgl` | 0.9.0 | `libakgl.so.0.9` | **`MAJOR.MINOR` while major is 0** | `AKGL_VERSION*`, `akgl_version()`, `AKGL_VERSION_AT_LEAST()` |
 
-`project(akerror VERSION ...)` now stamps 2.0.3, matching that library's own "Release 2.0.3"
-release notes. It previously disagreed — the soname and `akerrorConfigVersion.cmake` still
-said 2.0.2 while the notes described 2.0.3 — but that was `libakerror` issue #38, which is
-closed; the table and the notes agree again.
-
-`IGNORE` still takes a *copy* of the ignored context so the pool slot can be released, which
-fixes a real leak, but the copy no longer costs TLS per translation unit. It was a file-scope
-`static` in the public header — one copy per TU, 37,296 bytes each, 1.35 MiB of thread-local
-storage in `build/basic` alone, plus 84 `-Wunused-variable` warnings for every TU that never
-called `IGNORE`. `libakerror` issue #37 moved it to an `extern` declaration in the header with
-a single definition in `src/error.c`, which restores one copy per thread and silences the
-warning. Issue #37 is closed and this subsection is gone accordingly.
-
 For both 0.x libraries the soname carries `MAJOR.MINOR` deliberately: 0.1 and 0.2 are
 *different* ABIs, and both become major-only at 1.0. Do not read `0.1 → 0.2` as a compatible
 bump — both libraries have actually made that jump, so anything built against the 0.1 headers
@@ -216,32 +196,16 @@ precedes the build tree on the include path and a stray copy there would shadow
 one and pin every consumer. It publishes `AKGL_VERSION_AT_LEAST(major, minor, patch)` — the
 compile-time test `libakstdlib` could not write against `libakerror` — and `akgl_version()`.
 
-**Version-pinning in `find_package` used to be asymmetric. It no longer is.**
+**Version-pinning in `find_package` is asymmetric, and that is deliberate.**
 `find_package(akstdlib 0.1)` and `find_package(akgl 0.1)` both work; each ships a
-`ConfigVersion.cmake` at `SameMinorVersion`, mirroring its soname. `libakerror` shipped
-`akerrorConfig.cmake` and `akerrorTargets.cmake` but no `akerrorConfigVersion.cmake`, so any
-versioned request failed against a correct install and the advice here was to ask for
-`akerror` unversioned. That was `libakerror` issue #16 — closed — and `libakstdlib` issue #5,
-which tracks the same fix from the other side and is still open only because nobody has shut
-it. It has landed: `libakerror` now writes `akerrorConfigVersion.cmake` at
-**`SameMajorVersion`**, matching the soname's major-only rule, rather than the
-`SameMinorVersion` the other two use to match theirs.
-
-Two things follow, and the second is the one that bites:
-
-- **A versioned request now works** — but the floor to ask for is **`2.0`**, not the `1.0`
-  this file used to say. `find_package(akerror 1.0)` fails *harder* than before: it is a
-  request for major 1 against a major-2 install, which `SameMajorVersion` correctly rejects.
-- **There is nothing in this repository to change.** `akbasic` reaches all three dependencies
-  by `add_subdirectory`, not `find_package`, and ships no CMake package config of its own —
-  so it has no `find_dependency` calls to add a floor to. The instruction that used to live
-  here was written for a consumer this project never became. It matters to anyone *installing*
-  these libraries and linking `akbasic` against the installed copies, which is why it is
-  recorded rather than deleted.
-
-The compile-time floor is unchanged and still the real guard: an `#error` feature-testing
-`AKERR_FIRST_CONSUMER_STATUS`, which `akstdlib.h`, `akgl/error.h` and our own
-`include/akbasic/error.h` all carry — include any of them and you inherit it.
+`ConfigVersion.cmake` at `SameMinorVersion`, mirroring its soname. `find_package(akerror 1.0)`
+**fails against a correct install**, because `libakerror` ships `akerrorConfig.cmake` and
+`akerrorTargets.cmake` but no `akerrorConfigVersion.cmake`. Ask for `akerror` unversioned. Its
+floor is enforced instead by an `#error` feature-testing `AKERR_FIRST_CONSUMER_STATUS`, which
+`akstdlib.h`, `akgl/error.h` and our own `include/akbasic/error.h` all carry — include any of
+them and you inherit the guard. The missing version file is filed in
+`libakstdlib` issue #5 and `libakerror` issue #16; when it lands, add the `1.0` floor to the `find_dependency`
+calls.
 
 ### Embedding all three dependencies collides four ways
 
@@ -286,19 +250,14 @@ CTest names. `libakstdlib` still uses bare `test_<name>` targets. **Name every t
 this repo `akbasic_test_<name>`** — it costs nothing and it is the collision that actually
 stopped a build.
 
-**3. Duplicate custom targets — fixed upstream, and the workaround is gone.** `libakerror`
-used to namespace its `mutation` target when embedded but **not** its `coverage` target, so
-any coverage-enabled top-level build failed with *"another target with the same name already
-exists"*. This project shadowed `add_custom_target` and renamed that one to
-`akerror_coverage` on the way past, and recorded the real fix as `libakerror` issue #15: the
-same `CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR` test it already applied to
-`mutation`.
-
-That landed in 2.0.2. `libakerror` now picks `akerror_coverage` itself when embedded, so the
-shadow was dead code that could only ever fire on a name the dependency had stopped using —
-and it is deleted. All three dependencies namespace both targets correctly now, so **there is
-no custom-target collision left**; only collisions 1, 2 and 4 below are live. The heading says
-four because four is what a reader coming from the issue tracker will be looking for.
+**3. Duplicate custom targets.** `libakerror` namespaces its `mutation` target when embedded
+but **not** its `coverage` target, so any coverage-enabled top-level build fails with *"another
+target with the same name already exists"*. We shadow `add_custom_target` and rename that one
+to `akerror_coverage` on the way past. `libakstdlib` (both targets) and `libakgl` (its
+`mutation` target) namespace themselves correctly. **The real fix is upstream in
+`libakerror`** — the same `CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR` test it already
+applies to `mutation` — and it is filed as `libakerror` issue #15. Delete the
+workaround when it lands.
 
 **4. Stale build trees poison the coverage report.** See below; it is the reason for
 `cmake -S . -B build`.
@@ -392,10 +351,15 @@ name. That is not cosmetic: `add_executable` creates a dependency's targets even
 
 ### The golden corpora
 
-`tests/language/` is the editable language corpus. It includes cases carried over from the
-deprecated Go implementation as well as cases written for this interpreter. Every `.bas` file
-has a sibling `.txt` expectation, and a new language feature needs that pair as well as unit
-tests. Change both deliberately in the same commit; provenance does not make a case immutable.
+`tests/reference/` is the Go implementation's own acceptance suite, byte-compared.
+**Nothing in it is ever edited to suit this interpreter.** If a case fails, either this
+interpreter is wrong or the divergence is deliberate — and a deliberate one goes in
+`tests/reference/README.md`'s divergence table and `docs/13-differences.md`, not into the
+expectation file. `tests/reference/README.md`
+says the same thing at more length.
+
+`tests/language/` is ours and may be changed freely. A new language feature needs a
+`.bas`/`.txt` pair there as well as unit tests.
 
 ### Mutation-check a fix before you believe it
 
@@ -698,26 +662,6 @@ as a commit co-author, and this repository follows the same rule.
 Each dependency carries its own `AGENTS.md` with authoritative per-repo rules. Read the
 relevant one before editing a submodule.
 
-### Abandoned generators
-
-The one invariant generators (`GEN`/`EMIT`, `FOR EACH`/`DO EACH`) add to the environment
-pool: **a suspended generator hangs off its loop scope's `forGeneratorEnv` as a *child*,
-off the parent chain, so no walk up `->parent` ever finds it.** Any path that discards a
-loop scope — `EXIT`, a mismatched `NEXT`, a `LOOP` condition saying stop, an error unwind
-through `akbasic_runtime_pump_generator()` or `akbasic_runtime_call_function()` — must
-release that generator too, or its pool slot is stranded until the next `RUN`; with
-twelve slots, a loop that abandons a dozen of them kills the program with "Environment
-pool exhausted" far from the cause.
-
-Two functions own the invariant, and every discard path goes through one of them:
-`akbasic_runtime_release_generator()` (walks a detached generator chain up through its
-call frame, recursing into any `forGeneratorEnv` it passes) and
-`akbasic_runtime_unwind_to_environment()` (pops the *active* chain down to a target,
-releasing each popped scope's suspended generator on the way). If you add a new path
-that pops or discards environments, use one of these — a bare
-`akbasic_runtime_prev_environment()` loop reintroduces the leak, and
-`tests/generators.c` holds the pool-exhaustion tests that will say so.
-
 ---
 
 ## Editing the documentation

README.md

@@ -10,7 +10,7 @@ implementation that started from the Java Lox instructions in
 [craftinginterpreters.com](https://craftinginterpreters.com) and then struck off on its own. That
 project is deprecated. It is vendored here as the behavioural spec to read when a question about
 semantics comes up, and its acceptance corpus is checked in at
-[`tests/language/`](tests/language/README.md) and runs on every build — so nothing about
+[`tests/reference/`](tests/reference/README.md) and runs on every build — so nothing about
 building or testing this project needs it.
 
 ## Quickstart
@@ -24,7 +24,7 @@ ctest --test-dir build --output-on-failure
 
 ```sh norun
 ./build/basic                                          # the REPL
-./build/basic tests/language/functions.bas             # run a program
+./build/basic tests/reference/language/functions.bas   # run a program
 ```
 
 ```basic
@@ -129,7 +129,7 @@ version are catalogued in [`TODO.md`](TODO.md) and summarised for a BASIC progra
 | [`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/language/README.md`](tests/language/README.md) | The editable language corpus and the rule for changing it |
+| [`tests/reference/README.md`](tests/reference/README.md) | Where the golden corpus came from, and the rule for changing it |
 
 API documentation builds with `doxygen Doxyfile`, into `build/docs/html`.
 
@@ -138,13 +138,12 @@ API documentation builds with `doxygen Doxyfile`, into `build/docs/html`.
 Everything is a submodule; `git submodule update --init --recursive` gets all of it. There is
 nothing to install first.
 
-* [libakerror](https://source.starfort.tech/andrew/libakerror) 2.0.2 — TRY/CATCH-style error
+* [libakerror](https://source.starfort.tech/andrew/libakerror) 2.0.1 — TRY/CATCH-style error
   contexts. Every function that can fail returns one. 2.0.0 made it thread safe and broke the
   ABI; anything built against a 1.x header must be rebuilt rather than relinked.
 * [libakstdlib](https://source.starfort.tech/andrew/libakstdlib) 0.2.0 — libc wrappers that
   report through `libakerror`. String-to-number conversion goes straight to it, which is why
-  `VAL("garbage")` is an error rather than a silent `0`. Its public header now also pulls in
-  `<dirent.h>` and `<sys/stat.h>` for the directory and file-metadata wrappers.
+  `VAL("garbage")` is an error rather than a silent `0`.
 * [libakgl](https://source.starfort.tech/andrew/libakgl) 0.9.0 — **optional**, only for
   `-DAKBASIC_WITH_AKGL=ON`. Pulls in SDL3. Its soname carries `MAJOR.MINOR` while the major is 0,
   so rebuild rather than relink.

TODO.md

@@ -38,7 +38,7 @@ What it changes:
 - **§1.8's message-text contract is now a convention.** Improving a message is allowed; it costs
   a golden file, which is a cost rather than a veto.
 - **§5's bar drops** from "defensible against the golden suite" to defensible on its own merits.
-- **`tests/language/` is the editable language corpus rather than a protected specification.** Diverging from
+- **`tests/reference/` becomes a regression suite rather than a specification.** Diverging from
   it is allowed and must be deliberate and recorded — see its README.
 
 What it does **not** change:
@@ -306,13 +306,13 @@ to `Println`, which adds another.
 **This used to be a hard contract and is now a default.** The Go implementation is deprecated
 and will not be updated, so the two projects are no longer required to match — see §0.1. What
 survives is the practical half: these strings and this newline behaviour are what every
-expectation in `tests/language/` was written against, so changing one means changing the paired
+expectation in `tests/reference/` was written against, so changing one means changing golden
 files, and that is worth doing on purpose rather than by accident. A message that reads
 awkwardly *may* now be improved; do it deliberately, move the expectations in the same commit,
 and add a line to §5.
 
 Numeric formatting still matches the reference: integers via `%" PRId64 "`, floats via `%f`
-(Go's `%f` and C's `%f` both give six decimals — `tests/language/arithmetic/float.txt`
+(Go's `%f` and C's `%f` both give six decimals — `tests/reference/language/arithmetic/float.txt`
 confirms). No reason to change it, which is different from not being allowed to.
 
 ### 1.9 Which `libakstdlib` calls are cleared for use — **the bans are lifted**
@@ -366,36 +366,6 @@ One caveat survives the upgrade unchanged: `aksl_strhash_djb2` still sign-extend
 high-bit byte hashes differently from the `unsigned char` answer. BASIC identifiers are 7-bit
 ASCII so the symbol tables cannot reach it — see §1.3, which is still accurate.
 
-### 1.10 Generators share the `DEF` namespace, and the rest of their v1 semantics
-
-Decided with issue #57 and its review. `GEN` and `DEF` live in the same functions table —
-one lookup, one "unknown function" error path, a name cannot be both. What follows from
-that and from the review of PR #61, all settled:
-
-- A `GEN` called like a function (`X# = COUNTUP(3)`) is refused at the call, before
-  anything is pushed — `akbasic_FunctionDef.isGenerator` exists for exactly this check.
-- Bare `RETURN` standing in a `GEN`'s own frame ends the generator exactly as `END GEN`
-  does; `RETURN expr` there is an error, because values leave a `GEN` only through `EMIT`.
-  Both inherit the interpreter-wide restriction that `RETURN` does not unwind nested
-  `FOR`/`DO` scopes — lifting that everywhere (the C64 reference *does* unwind) is filed
-  separately.
-- `DO EACH ... LOOP WHILE c | UNTIL c` composes: the condition is checked after each trip,
-  with the loop variable still holding that trip's value, and stopping abandons the
-  generator exactly as `EXIT` does. A condition on the `DO EACH` line itself is a parse
-  error.
-- Self-recursion — a `GEN` reached again down its own parent chain — is refused; sibling
-  and nested invocations of the same `GEN` are each a fresh pool environment and are fine.
-- Every path that discards a `FOR EACH`/`DO EACH` scope must release the generator
-  suspended off it; see MAINTENANCE.md's "Abandoned generators" note for the invariant
-  and `akbasic_runtime_unwind_to_environment()` for the one primitive that enforces it.
-
-One known limitation, pre-existing and shared with `DEF`: `parse_def_parameters()` does
-not accept an empty parameter list, so `GEN NAME()` cannot be written — every generator
-takes at least one parameter whether it wants one or not. Location:
-`src/parser_commands.c`, `parse_def_parameters()`. Consequence: pointless parameters in
-programs. Blast radius: cosmetic, both `DEF` and `GEN` headers. Closure: teach the shared
-helper to accept `()`, one test each for `DEF` and `GEN`; filed as its own issue.
-
 ---
 
 ## 2. What exists — **the core port is complete and green**
@@ -405,7 +375,7 @@ Phases 0 through 6 of the original plan are done. The interpreter builds clean u
 
 It *did* reproduce the reference byte for byte, and that claim is retired rather than broken:
 §0.1 released it, and one case has since diverged deliberately (§6 item 16, listed in
-`tests/language/README.md`). Everything else still matches, which is worth knowing but is no
+`tests/reference/README.md`). Everything else still matches, which is worth knowing but is no
 longer a gate.
 
 ```sh
@@ -438,16 +408,17 @@ and the only path that existed — `AKBASIC_MODE_RUNSTREAM` reading through the
 is the code the README quotes, built by every build and registered as a CTest case so a
 signature change breaks the build rather than rotting the document.
 
-**The acceptance suite is the editable language corpus, checked in at `tests/language/`.** All
-65 `.bas` files are registered as individual CTest cases and compared against their `.txt`
+**The acceptance suite is the reference's own corpus, checked in at `tests/reference/`.** All
+41 `.bas` files are registered as individual CTest cases and byte-compared against their `.txt`
 — including the trailing double newline on an error line (§1.8).
 
 It was driven *in place* out of `deps/basicinterpret` until 2026-07-31, on the reasoning that
 copying a submodule's corpus guarantees drift. That reasoning was sound and was overruled
 deliberately: the Go dependency is being deprecated, and a build that cannot run its own
 acceptance suite without cloning the implementation it replaced is not finished. The copy is
-originally byte-identical to `basicinterpreter@d76162c`, and `tests/language/README.md` records the
-provenance and the rule that programs and expectations are edited together deliberately.
+byte-identical to `basicinterpreter@d76162c`, and `tests/reference/README.md` records the
+provenance, the cost of the drift nobody is watching for now, and the rule that those
+expectations are never edited to suit this interpreter.
 
 **Nothing in the build or the suite needs `deps/basicinterpret` any more**, and that is checked
 rather than assumed — both configurations were configured, built and run from scratch with the
@@ -1055,7 +1026,7 @@ deviations from the reference's *program*: `main.go` and the SDL half of
 
     **What it costs a program:** a listing that used `INPUT$`, `LEN#` or `GOTO%` as a variable
     stops parsing, and the fix is to rename the variable. One case in the reference's own corpus
-    did exactly that; see `tests/language/examples/strreverse.bas`.
+    did exactly that; see `tests/reference/README.md`.
 
 ### Deviations in statement separation
 
@@ -1420,10 +1391,10 @@ deviations from the reference's *program*: `main.go` and the SDL half of
     **This one moved a golden file.** A line with no number used to be filed under the loader's
     cursor unchanged — that is, on top of the line before it — so two unnumbered lines in a row
     silently lost the first, and a *blank* line erased whatever preceded it. The reference does
-    the same, and `tests/language/arithmetic/integer.bas` is the proof: four `PRINT`
+    the same, and `tests/reference/language/arithmetic/integer.bas` is the proof: four `PRINT`
     statements, an expectation with three values, and a trailing blank line that erased
     `40 PRINT 4 - 2` before the program ran. The expectation is now `4 4 2 2` and
-    `tests/language/README.md` records it.
+    `tests/reference/README.md` records it.
 
     In its place: `akbasic_runtime_file_line()` (`src/runtime.c`) is the one implementation of
     the rule, shared by `akbasic_runtime_load()`, RUNSTREAM and `DLOAD`. A numbered line is
@@ -1615,9 +1586,9 @@ be reproduced before it can be fixed.
 
     **It cost one golden case, exactly as predicted, and the cost turned out to be nothing.**
     The reference's `examples/strreverse.bas` names a variable `INPUT$`; the variable is renamed
-    to `SOURCE$` in `tests/language/examples/strreverse.bas`, the expectation is byte-for-byte unchanged — the program
+    to `SOURCE$` in `tests/reference/`, the expectation is byte-for-byte unchanged — the program
     still prints `REVERSED: OLLEH` — and the case keeps every bit of its coverage. Recorded in
-    `tests/language/README.md` records the corpus editing rule.
+    `tests/reference/README.md`'s divergence table, which this is the first entry in.
 
     This item sat parked because the corpus was the acceptance contract and lived in a submodule
     this repository could not edit. Both premises are gone: the corpus is checked in, and
@@ -2261,10 +2232,10 @@ update --init --recursive` gets them.
 
 ## 8. Status
 
-**The port is done.** The C interpreter passes the language corpus and passes clean
+**The port is done.** The C interpreter passes the Go reference's entire corpus and passes clean
 under ASan and UBSan. It reproduced that corpus byte for byte until §0.1 retired the
 requirement; two cases have diverged on purpose since, and
-`tests/language/README.md` lists them.
+`tests/reference/README.md` lists them.
 
 | Gate | Result |
 |---|---|
@@ -2272,7 +2243,7 @@ requirement; two cases have diverged on purpose since, and
 | `ctest` with `-DAKBASIC_WITH_AKGL=ON` | 112/112 headless, with `akgl_typing` skipping itself. The same set minus the four `no_device` cases the SDL driver contradicts, plus `akgl_backends`, `akgl_frontend`, `docs_screenshots` and `akgl_typing` — the last of which is the skip, and the `akgl_build` CI job is where it skips |
 | `docs_examples` | Every fenced block in `README.md`, `MAINTENANCE.md` and `docs/` executed and byte-compared: 71 programs, 9 transcripts, 79 output comparisons, 4 C snippets, 2 excerpts, 2 shell blocks and 19 figures in the default build. The C-snippet count reads 0 when the harness is run by hand without `--cflags-file`; CTest passes it. `MAINTENANCE.md` documents the fence-tag convention |
 | `docs_screenshots` | 19/19 figures re-rendered and byte-identical to the checked-in PNGs. AKGL build only — rendering a picture needs the SDL half |
-| Language corpus | 65/65 paired expectations — **and 65/65 again through the SDL binary**, which is most of what proves the frontend changes no output |
+| Golden corpus | 41/41 byte-exact from `tests/reference/` — **and 41/41 again through the SDL binary**, which is most of what proves the frontend changes no output |
 | ASan + UBSan | 112/112 |
 | Line coverage | 94.1% (7227/7681) — above the 90% gate |
 | Function coverage | 97.9% (474/484) |
@@ -2369,9 +2340,9 @@ Dependency baseline:
 
 | Submodule | Version | Notes |
 |---|---|---|
-| `deps/libakerror` | 2.0.2 | Private ownership-enforced status registry. akbasic reserves 512–767 in `akbasic_error_register()`. **2.0.0 is thread safe and an ABI break** (`libakerror.so.2`): the `IGNORE` context is thread-local and `akerr_next_error()` returns an owned reference, neither of which fails to link when mismatched. **2.0.1 fixes an exit status that mattered more to this band than to any other** — see below. **2.0.2** namespaces its embedded `coverage` target (issue #15 — our `add_custom_target` shadow is deleted), installs `akerrorConfigVersion.cmake` at `SameMajorVersion` (issue #16), fixes the `AKERR_USE_STDLIB=OFF` build, retires `PATH_MAX` for `AKERR_MAX_ERROR_FNAME_LENGTH`, and turns the `IGNORE` slot into a released copy — `__akerr_last_ignored` was an `extern` pointer and is now a per-TU `static akerr_last_ignored`. **That last one costs us 1.35 MiB of thread-local storage**: 38 translation units x 37,296 bytes, measured as the whole TLS segment of `build/basic`, where 2.0.1 produced no TLS segment at all. Filed upstream as libakerror issue #37, along with the 84 `-Wunused-variable` warnings it emits. Its `UPGRADING.md` describes a 2.0.3 that `project()` never stamped — libakerror issue #38, which is why the version above reads 2.0.2. |
-| `deps/libakstdlib` | 0.2.0 | soname `libakstdlib.so.0.2`. `AKSL_VERSION_CHECK()` asserted in `tests/version_check.c`. This release fixed all six confirmed defects the port was working around — see §1.9, where the bans are now lifted. Since then, and with no version bump: **directory wrappers landed** (`aksl_opendir`/`readdir`/`closedir`/`rewinddir`, issue #10) — the gap `DIRECTORY` was refused for, so that refusal now says only that the verb is unwritten; file-metadata wrappers landed; and `aksl_snprintf` keeps its `int *count` but now reports the *required* length on truncation rather than 0. Only read on success here, so nothing moved. |
-| `deps/libakgl` | 0.9.0 | soname `libakgl.so.0.9`. Owns status codes 256–262. Linked and tested under `-DAKBASIC_WITH_AKGL=ON`, which still defaults OFF so the core library and its whole suite build on a machine with no SDL. **0.3.0 closed every API gap this port had filed** — see §7 — so the four workarounds §3 used to list are gone. 0.4.0 was a leak-and-overread release that changed no public struct. **0.5.0 is the first that broke our source as well as our ABI**: it namespaced every exported symbol, so `akgl_render_bind2d` is `akgl_render_2d_bind`, `akgl_sprite_sheet_coords_for_frame` is `akgl_spritesheet_coords_for_frame`, the `renderer`/`camera`/`window` globals carry the prefix, and `_akgl_renderer`/`_akgl_camera` are `akgl_default_renderer`/`akgl_default_camera`. `include/akbasic/akgl.h` asserts the floor. **0.6.0 and 0.7.0 broke nothing here** — 0.6.0 is three arcade-physics fixes and a `physics.max_timestep` property this port does not use, and 0.7.0 reports failures `libakstdlib`'s wrappers were already catching and takes `libakerror` 2.0.1. **0.8.0 and 0.9.0 broke nothing here either** — 0.8.0 is the collision subsystem (`AKGL_ERR_COLLISION`, code 261, and the vendored `libccd` and `tg` submodules that come with it), and 0.9.0 is the `akgl_ui` subsystem (`AKGL_ERR_UI`, code 262, and vendored `clay`), which is what `src/ui_akgl.c` draws through. Both widen libakgl's reserved band from five codes to seven; the range map in `MAINTENANCE.md` carries it. The floor moved anyway, because deciding for ourselves which of libakgl's minor releases were really compatible is the judgement the soname exists to take away. **Note `deps/libakgl/deps/` pins its own `libakerror` and `libakstdlib` older than ours**; the top-level build declares both targets first and libakgl's `if(NOT TARGET ...)` guards mean its copies are never configured, so what libakgl actually compiles against is what this tree pins. |
+| `deps/libakerror` | 2.0.1 | Private ownership-enforced status registry. akbasic reserves 512–767 in `akbasic_error_register()`. Does not namespace its `coverage` target when embedded — worked around in our `CMakeLists.txt`. **2.0.0 is thread safe and an ABI break** (`libakerror.so.2`): `__akerr_last_ignored` is thread-local and `akerr_next_error()` returns an owned reference, neither of which fails to link when mismatched. **2.0.1 fixes an exit status that mattered more to this band than to any other** — see below. |
+| `deps/libakstdlib` | 0.2.0 | soname `libakstdlib.so.0.2`. `AKSL_VERSION_CHECK()` asserted in `tests/version_check.c`. This release fixed all six confirmed defects the port was working around — see §1.9, where the bans are now lifted. |
+| `deps/libakgl` | 0.7.0 | soname `libakgl.so.0.7`. Owns status codes 256–260. Linked and tested under `-DAKBASIC_WITH_AKGL=ON`, which still defaults OFF so the core library and its whole suite build on a machine with no SDL. **0.3.0 closed every API gap this port had filed** — see §7 — so the four workarounds §3 used to list are gone. 0.4.0 was a leak-and-overread release that changed no public struct. **0.5.0 is the first that broke our source as well as our ABI**: it namespaced every exported symbol, so `akgl_render_bind2d` is `akgl_render_2d_bind`, `akgl_sprite_sheet_coords_for_frame` is `akgl_spritesheet_coords_for_frame`, the `renderer`/`camera`/`window` globals carry the prefix, and `_akgl_renderer`/`_akgl_camera` are `akgl_default_renderer`/`akgl_default_camera`. `include/akbasic/akgl.h` asserts the floor. **0.6.0 and 0.7.0 broke nothing here** — 0.6.0 is three arcade-physics fixes and a `physics.max_timestep` property this port does not use, and 0.7.0 reports failures `libakstdlib`'s wrappers were already catching and takes `libakerror` 2.0.1. The floor moved anyway, because deciding for ourselves which of libakgl's minor releases were really compatible is the judgement the soname exists to take away. |
 
 **An unhandled error in this band used to exit zero, and 512 is the worst possible base for
 that.** `libakerror`'s default unhandled-error handler ended in `exit(errctx->status)`, and a
@@ -2582,7 +2553,7 @@ What remains, in priority order:
       this whole arrangement exists against.
 
     The byte comparison is a deliberate bet that the dummy driver and the software renderer
-    are reproducible, which is the same bet `tests/language/` makes about golden
+    are reproducible, which is the same bet `tests/reference/` already makes about golden
     output. Verified run-to-run and build-to-build here; what is untested is an SDL upgrade
     that moves one pixel of a diagonal. **If that happens, regenerate the figures in the same
     commit as the bump** — do not weaken the test to a size check, which would pass for every
@@ -2665,7 +2636,7 @@ reduced against `build/basic`, the stdio build, unless it says otherwise.
 
    **It is narrower than it looks, and the golden corpus is why.** The first attempt
    released the scope on *any* skip, which broke
-   `tests/language/flowcontrol/nestedforloopwaitingforcommand.bas`: a zero-
+   `tests/reference/language/flowcontrol/nestedforloopwaitingforcommand.bas`: a zero-
    iteration `FOR` skips its body by the same mechanism, and there the orphan is
    load-bearing -- it is what absorbs the inner `NEXT` so the outer one still finds its
    `FOR`. Releasing it turns that case into "NEXT outside the context of FOR". So the

docs/04-control-flow.md

@@ -146,143 +146,6 @@ condition at all loops forever until an `EXIT` or a `GOTO` leaves it.
 
 `EXIT` works here too.
 
-## GEN ... EMIT and FOR EACH / DO EACH
-
-A `GEN` is a subroutine that hands back more than one value, one at a time, instead of
-returning once. It looks like a multi-line `DEF`, except its body runs `EMIT` where a
-function would `RETURN`, and it ends in `END GEN` rather than `RETURN`:
-
-```basic
-10 GEN COUNTUP(N#)
-20     FOR I# = 1 TO N#
-30         EMIT I#
-40     NEXT I#
-50 END GEN
-60 FOR EACH V# IN COUNTUP(3)
-70     PRINT V#
-80 NEXT V#
-```
-
-```output
-1
-2
-3
-```
-
-`FOR EACH` is what runs a `GEN`: it calls `COUNTUP(3)` the way `FOR EACH V# IN` says,
-and each `EMIT` inside the generator's body becomes one trip through the loop, with `V#`
-holding whatever was emitted. When the generator's body reaches `END GEN` with nothing
-left to emit, the loop ends -- there is no separate "no more values" check to write.
-
-`DO EACH ... LOOP` does the same thing:
-
-```basic
-10 GEN COUNTUP(N#)
-20     FOR I# = 1 TO N#
-30         EMIT I#
-40     NEXT I#
-50 END GEN
-60 DO EACH V# IN COUNTUP(3)
-70     PRINT V#
-80 LOOP
-```
-
-```output
-1
-2
-3
-```
-
-A `GEN`'s body is ordinary BASIC: it may hold its own `FOR`, `DO`, `IF` or `GOSUB`
-around the `EMIT`s, and even invoke another `GEN` with its own `FOR EACH`/`DO EACH` --
-the same generator invoked with different arguments, nested or side by side, is not
-recursion. A `GEN` invoking *itself* from within its own currently-running body is
-refused: unlike a function call, which runs to completion and returns, the outer
-invocation is suspended mid-body waiting on the same loop, and there is no answer to
-"which EMIT feeds which loop" that is not a surprise.
-
-`EXIT` leaves a `FOR EACH`/`DO EACH` loop early, exactly as it does a plain `FOR` or
-`DO`, and the generator it was consuming stops there -- nothing forces the rest of it to
-run just because the loop started it:
-
-```basic
-10 GEN COUNTUP(N#)
-20     FOR I# = 1 TO N#
-30         EMIT I#
-40     NEXT I#
-50 END GEN
-60 FOR EACH V# IN COUNTUP(100)
-70     PRINT V#
-80     IF V# = 3 THEN EXIT
-90 NEXT V#
-100 PRINT "STOPPED"
-```
-
-```output
-1
-2
-3
-STOPPED
-```
-
-`RETURN` ends a `GEN` from the inside, exactly as it ends a multi-line `DEF` or a
-`GOSUB`: the generator is done, the loop consuming it ends, and the program carries on
-after the loop. What a generator's `RETURN` cannot do is carry a value -- values leave
-a `GEN` one at a time, through `EMIT`, and `RETURN 99` inside one is an error. Like a
-`GOSUB`'s or a `DEF`'s, the `RETURN` must stand in the `GEN`'s own scope: from inside
-a `FOR` or `DO` the body opened, it is an error, though `IF ... THEN RETURN` is fine
-because `IF` opens no scope of its own.
-
-```basic
-10 GEN FIRSTFEW(N#)
-20     EMIT 1
-30     IF N# < 2 THEN RETURN
-40     EMIT 2
-50     IF N# < 3 THEN RETURN
-60     EMIT 3
-70 END GEN
-80 FOR EACH V# IN FIRSTFEW(2)
-90     PRINT V#
-100 NEXT V#
-110 PRINT "DONE"
-```
-
-```output
-1
-2
-DONE
-```
-
-A `DO EACH`'s `LOOP` may carry a `WHILE` or `UNTIL`, and the two compose: the condition
-is checked after each trip through the body, with the loop variable still holding that
-trip's value, and a condition that says stop abandons the rest of the generator exactly
-as `EXIT` does. The condition belongs on the `LOOP` -- putting it on the `DO` line is
-an error, since the `DO` line already says what the loop consumes.
-
-```basic
-10 GEN COUNTUP(N#)
-20     FOR I# = 1 TO N#
-30         EMIT I#
-40     NEXT I#
-50 END GEN
-60 DO EACH V# IN COUNTUP(10)
-70     PRINT V#
-80 LOOP UNTIL V# = 3
-90 PRINT "STOPPED"
-```
-
-```output
-1
-2
-3
-STOPPED
-```
-
-A `GEN` shares its namespace with `DEF` -- the same name cannot be both -- but it is not
-a function and cannot be called like one: `X# = COUNTUP(3)` is refused, because nothing
-about an ordinary call means "resume where the last `EMIT` left off." `FOR EACH`/`DO
-EACH` is the only thing that consumes a `GEN`.
-
 ## GOTO and GOSUB
 
 ```basic

docs/09-files-and-disk.md

@@ -126,7 +126,7 @@ exists, and reading into one you never sized writes over something else.
 | `COLLECT` | validates a disk's block allocation map. There is no map |
 | `BACKUP` | duplicates one disk onto another. There are no disks |
 | `BOOT` | loads and runs a boot sector. There is no boot sector |
-| `DIRECTORY` / `CATALOG` | not written yet. It was blocked on a directory-reading wrapper in the standard library; that landed, so only the verb is outstanding |
+| `DIRECTORY` / `CATALOG` | needs a directory-reading wrapper the standard library does not have yet. Filed upstream |
 
 `DCLEAR` is the exception among the drive verbs: resetting a drive also closes its
 channels, and closing the channels is real, so that is what it does.

docs/11-verb-reference.md

@@ -35,22 +35,19 @@ for the reasoning in each case.
 | `DIALOG` | `DIALOG ["text"]` | Show a text panel across the bottom of the screen. No argument takes it down. See Chapter 19. |
 | `DIM` | `DIM A#(n [,...])` | Make an array. Subscripts start at zero; `n` is the count. |
 | `DIM` … `AS` | `DIM S@ AS T`, `DIM P@ AS PTR TO T` | Make a structure, or a strict pointer to one. See Chapter 16. |
-| `DIRECTORY` | `DIRECTORY` | **Refused.** Not written yet; the standard-library wrapper it waited on has landed. |
+| `DIRECTORY` | `DIRECTORY` | **Refused.** Needs a directory-reading wrapper that does not exist yet. |
 | `DLOAD` | `DLOAD "name"` | Load a program from a file. |
-| `DO` | `DO [WHILE c | UNTIL c]`, `DO EACH V IN gen(args)` | Start a loop. The condition may be here, on the `LOOP`, or neither. `EACH` consumes a `GEN` instead, and takes its condition only on the `LOOP`; see Chapter 4. |
+| `DO` | `DO [WHILE c | UNTIL c]` | Start a loop. The condition may be here, on the `LOOP`, or neither. |
 | `DOPEN` | `DOPEN n, "name" [,W]` | Open a file on channel `n`. `W` opens it for writing. |
 | `DRAW` | `DRAW src, x, y [TO x, y ...]` | Plot a point or draw a polyline. |
 | `DSAVE` | `DSAVE "name"` | Save the program to a file. |
 | `DVERIFY` | `DVERIFY "name"` | The other name for `VERIFY`. |
-| `EMIT` | `EMIT expr` | Yield one value from a `GEN` body. Only valid inside one; see Chapter 4. |
 | `END` | `END` | Stop the program. Does not arm `CONT`. |
-| `END GEN` | `END GEN` | Close a `GEN` body, the way `RETURN` closes a multi-line `DEF`. |
 | `ENVELOPE` | `ENVELOPE n, a, d, s, r` | Define one of `PLAY`'s ten envelope presets. |
-| `EXIT` | `EXIT` | Leave the innermost `FOR`, `FOR EACH`, `DO` or `DO EACH` loop. |
+| `EXIT` | `EXIT` | Leave the innermost `FOR` or `DO` loop. |
 | `FETCH` | `FETCH count, from, to` | Copy bytes. The same as `STASH`; there is no expansion RAM. |
 | `FILTER` | `FILTER ...` | **Refused.** There is no filter stage in the audio backend. |
-| `FOR` | `FOR V = a TO b [STEP c]`, `FOR EACH V IN gen(args)` | Start a counted loop, ended by `NEXT`. `EACH` consumes a `GEN` instead; see Chapter 4. |
-| `GEN` | `GEN NAME(args) ... END GEN` | Define a generator: a subroutine that yields more than once via `EMIT`, consumed by `FOR EACH`/`DO EACH`. See Chapter 4. |
+| `FOR` | `FOR V = a TO b [STEP c]` | Start a counted loop, ended by `NEXT`. |
 | `GET` | `GET V` | Take a keystroke if one is waiting, without stopping. |
 | `GETKEY` | `GETKEY V` | Wait for a keystroke, holding the program but not the host. |
 | `GETMENU` | `GETMENU n, V%` | Wait for a menu choice, holding the program but not the host. Assigns the entry number. See Chapter 19. |
@@ -70,11 +67,11 @@ for the reasoning in each case.
 | `LIST` | `LIST [n][-n]` | List the program, or part of it. |
 | `LOAD` | `LOAD "name"` | The other name for `DLOAD`. |
 | `LOCATE` | `LOCATE x, y` | Move the pixel cursor. |
-| `LOOP` | `LOOP [WHILE c | UNTIL c]` | End a `DO` loop, including a `DO EACH`. |
+| `LOOP` | `LOOP [WHILE c | UNTIL c]` | End a `DO` loop. |
 | `MENU` | `MENU [n [,"item", ...]]` | Show a menu the player picks from. No entries retires it; no arguments retire them all. See Chapter 19. |
 | `MOVSPR` | `MOVSPR n, ...` | Move a sprite. Four forms; see Chapter 8. |
 | `NEW` | `NEW` | Erase the program and every variable. |
-| `NEXT` | `NEXT V` | End a `FOR` loop and advance its counter, or resume a `FOR EACH` for its next value. |
+| `NEXT` | `NEXT V` | End a `FOR` loop and advance its counter. |
 | `ON` | `ON e GOTO|GOSUB t [,...]` | Branch to the `e`th target, counting from one. |
 | `PAINT` | `PAINT src, x, y` | Flood-fill the region containing a point. |
 | `PLAY` | `PLAY "notes"` | Queue notes. Does not block. |
@@ -90,7 +87,7 @@ for the reasoning in each case.
 | `RENUMBER` | `RENUMBER [start [,step [,from]]]` | Renumber lines, rewriting every branch to match. |
 | `RESTORE` | `RESTORE [line]` | Reset the `READ` cursor, optionally to a line. |
 | `RESUME` | `RESUME [NEXT | line]` | Return from a `TRAP` handler. |
-| `RETURN` | `RETURN [expr]` | Return from a `GOSUB` or a multi-line `DEF`. Inside a `GEN`, a bare `RETURN` ends the generator early; `RETURN expr` there is an error. |
+| `RETURN` | `RETURN [expr]` | Return from a `GOSUB` or a multi-line `DEF`. |
 | `RUN` | `RUN [line]` | Run the program, optionally from a line. |
 | `SAVE` | `SAVE "name"` | The other name for `DSAVE`. |
 | `SCALE` | `SCALE on [,xmax, ymax]` | Turn user coordinates on or off. |

docs/12-function-reference.md

@@ -9,7 +9,6 @@ so a call with the wrong number is a syntax error rather than a surprise.
 | Function | Args | Form | What it gives |
 |---|---|---|---|
 | `ABS` | 1 | `ABS(n)` | The absolute value of an integer or float. |
-| `ASC` | 1 | `ASC(A$)` | The Unicode code point of a string's first character. |
 | `ATN` | 1 | `ATN(n)` | Arctangent, in radians. |
 | `BUMP` | 1 | `BUMP(1)` | Which sprites have collided, as a bitmask. **Reading clears it.** |
 | `CHR` | 1 | `CHR(n)` | The character for a Unicode code point, as a string. |
@@ -30,7 +29,6 @@ so a call with the wrong number is a syntax error rather than a surprise.
 | `RGR` | 1 | `RGR(f)` | The `GRAPHIC` mode (0), the drawing surface's width (1) or height (2) in pixels, or a character cell's width (3) or height (4). |
 | `RIGHT` | 2 | `RIGHT(A$, n)` | The rightmost `n` characters. Clamped. |
 | `RMENU` | 2 | `RMENU(n, f)` | A menu's state: field 0 the highlighted entry, field 1 whether it has been confirmed. **Reading field 1 clears it.** |
-| `RND` | 1 | `RND(n)` | A random integer from 0 up to but not including `n`. |
 | `RWINDOW` | 1 | `RWINDOW(f)` | The current text window's rows (0) or columns (1). Field 2 is a C128 screen mode and is refused. |
 | `RSPCOLOR` | 1 | `RSPCOLOR(n)` | One of `SPRCOLOR`'s two shared registers, 1 or 2. |
 | `RSPHIT` | 2 | `RSPHIT(n, f)` | One of `SPRHIT`'s settings for sprite `n`, in `SPRHIT`'s own argument order: 0 the kind, 1 to 4 the two corners. |

docs/13-differences.md

@@ -199,8 +199,7 @@ interpreter's error code, which bears no relation to a Commodore error number. P
 - **`BLOAD` requires a length.**
 - **`HEADER`, `COLLECT`, `BACKUP` and `BOOT` are refused.** They operate on a physical
   disk.
-- **`DIRECTORY` is refused** because it is not written yet. The standard-library
-  wrapper it was waiting on has landed, so the remaining work is the verb.
+- **`DIRECTORY` is refused** pending a wrapper in the standard library.
 
 ## Machine
 

docs/14-architecture.md

@@ -407,8 +407,6 @@ block structure is executing: the `FOR` bounds and step, the `DO`/`LOOP` conditi
 | `GOSUB` | `RETURN` |
 | A call to a multi-line user function | that function's `RETURN` |
 | An interrupt firing | the handler's `RETURN` |
-| `FOR EACH`/`DO EACH` — the loop's own scope, during parsing | the `NEXT`/`LOOP` that finds the generator exhausted, or an `EXIT` |
-| A `FOR EACH`/`DO EACH` invoking a `GEN` | `END GEN` reached for real, or the loop's own abandonment |
 
 That `FOR` entry is not a typo. `akbasic_parse_for()` pushes the new environment while
 parsing the line, parks `TO` and `STEP` in it as unevaluated leaves, and makes it active
@@ -456,59 +454,6 @@ Three consequences follow, and all three are things people report as bugs:
   the value correctly inside the loop and gets `0` immediately after it, with nothing
   raised anywhere.
 
-### Generators: a scope that outlives the verb that pushed it
-
-Everything above pops a scope by *releasing* it — `akbasic_runtime_prev_environment()`
-gives its variables and its own pool slot back in the same motion that hands control to
-its parent. A `GEN` needed a third option, because `EMIT` has to survive being
-"returned" from: the next value comes from resuming exactly where the last `EMIT` left
-off, not from starting over.
-
-`akbasic_runtime_prev_environment()` is now built from two smaller pieces:
-
-- `akbasic_runtime_detach_environment()` — moves `obj->environment` to the parent,
-  *without* releasing anything.
-- `akbasic_runtime_release_environment()` — gives a scope's variables and pool slot
-  back, callable on a scope that is not necessarily the active one.
-
-A `FOR EACH`/`DO EACH` invocation therefore holds **two** environments at once, for as
-long as the loop is running:
-
-```text
-loop environment (isEachLoop)          <- pushed like a plain FOR/DO's, at parse time
-    forGeneratorEnv -----------> generator environment (isGenerator)
-                                      <- pushed once, by akbasic_runtime_generator_invoke(),
-                                         and never released until the generator is
-                                         exhausted or abandoned
-```
-
-`EMIT` finds its generator environment by walking *up* from wherever it is actually
-standing — a `GEN` body is ordinary BASIC and may nest its own `FOR`, `DO` or `GOSUB`
-around an `EMIT`, each pushing scopes of its own — to the nearest ancestor with
-`isGenerator` set. It assigns the emitted value into the loop's `forNextVariable`,
-records *exactly* where it is standing (which may be several environments below the
-generator's own call frame) as `forGeneratorEnv`, and moves `obj->environment` straight
-to the loop environment — detaching, not popping, so every environment between the two
-survives untouched.
-
-`NEXT`/`LOOP` reactivate a suspended generator by setting `obj->environment` back to
-`forGeneratorEnv` and driving the step loop (`akbasic_runtime_pump_generator()`) until
-either another `EMIT` detaches it again or `END GEN` is reached for real — meaning
-`isGenerator` is set and nothing is skipping forward to it, exactly the same test
-`RETURN` makes for a multi-line `DEF`. Real exhaustion releases the generator
-environment (`akbasic_runtime_prev_environment()`, same as anything else that pops) and
-clears `forGeneratorEnv`, which is what tells the loop apart from one still waiting to
-resume.
-
-**Abandoning a live generator has to release it explicitly.** `EXIT` out of a `FOR
-EACH`/`DO EACH` pops the loop environment the same way it always has, but a generator
-paused mid-run is not on that direct parent chain from the loop back to the root — it
-hangs off `forGeneratorEnv` instead, possibly several environments deep if `EMIT` last
-ran inside a nested `FOR`/`DO` in the `GEN`'s own body. `akbasic_runtime_release_generator()`
-is what walks that chain and releases all of it; every place that pops a `FOR EACH`/`DO
-EACH` loop out from under a live generator calls it first, or the pool leaks one
-generator at a time.
-
 ## Values
 
 `akbasic_Value` carries its string **inline**, not behind a pointer, so a copy is a struct
@@ -798,8 +743,8 @@ way to see that something pushed a scope and never popped it.
 
 ```sh norun
 ctest --test-dir build --output-on-failure -R for_next     # one unit test
-ctest --test-dir build --output-on-failure -R local_       # the language corpus
-./build/basic tests/language/functions.bas | diff - tests/language/functions.txt
+ctest --test-dir build --output-on-failure -R golden_      # the reference corpus
+./build/basic tests/reference/language/functions.bas | diff - tests/reference/language/functions.txt
 ./tests/docs_examples.sh --root . --basic ./build/basic \
     --cflags-file build/docs_cflags.txt docs/14-architecture.md
 ```

docs/17-tutorial-breakout.md

@@ -1005,26 +1005,57 @@ IF NUDGE# = 1 THEN GOSUB UNSTICK
 LABEL UNSTICK
 NUDGE# = 0
 STALL# = 0
-BVX# = (RND(4) * 3) - 6
+RMAX# = 4
+GOSUB RANDOM
+BVX# = (RND# * 3) - 6
 IF BVX# = 0 THEN BVX# = 3
 RETURN
 ```
 
-### Random numbers are built in
+### You have to write your own random numbers
 
-There is no `INT`, `SQR` or `TIMER` in this dialect, but
-`RND(n)` returns an integer from zero through `n - 1`. It seeds itself
-from the host clock the first time it is called, so a program only needs the bound:
+**There is no `RND` in this dialect**, and no `INT`, `SQR`, `ASC` or `TIMER` either. A
+linear congruential generator is nine tokens and does the job. Put the number of possible
+answers in `RMAX#` and read the result from `RND#`:
 
 ```basic
+SEED# = 12345
+RMAX# = 6
+RND# = 0
 I# = 0
 FOR I# = 1 TO 5
-  PRINT "ROLL " + (RND(6) + 1)
+  GOSUB RANDOM
+  PRINT "ROLL " + (RND# + 1)
 NEXT I#
 END
+
+LABEL RANDOM
+SEED# = MOD(((SEED# * 1103515245) + 12345), 2147483648)
+RND# = MOD((SEED# / 65536), RMAX#)
+RETURN
 ```
 
-Use `RND` for the serve, too, so the ball does not always leave in the same direction:
+```output
+ROLL 1
+ROLL 5
+ROLL 2
+ROLL 1
+ROLL 2
+```
+
+The multiplication stays inside a 64-bit integer for any seed below 2147483648, which is
+why the modulus is that number. The answer is taken from the middle bits — `SEED# / 65536`
+— because the low bits of a power-of-two modulus barely change from one call to the next.
+Integer division truncating for free is the `INT` you do not have.
+
+Seed it from the clock at startup. `TI#` is the host's uptime in sixtieths of a second,
+which is different every time the game is run:
+
+```basic norun
+SEED# = TI#
+```
+
+Use `RANDOM` for the serve, too, so the ball does not always leave in the same direction:
 
 ```basic norun
 LABEL SERVE
@@ -1032,43 +1063,16 @@ PX# = (SCW# - PW#) / 2
 HELD# = 1
 BX# = PX# + ((PW# / 2) - 4)
 BY# = PY# - 10
+RMAX# = 2
+GOSUB RANDOM
 BVX# = BSPD#
-IF RND(2) = 0 THEN BVX# = 0 - BSPD#
+IF RND# = 0 THEN BVX# = 0 - BSPD#
 BVY# = 0 - BSPD#
 PDEC# = 0
 GOSUB SHOWSPR
 RETURN
 ```
 
-<details>
-<summary>Historical aside: the LCG this chapter used to teach</summary>
-
-Before `RND` existed, this nine-token linear congruential generator was copied into
-every program. It remains a useful from-scratch PRNG example:
-
-```basic norun
-SEED# = 12345
-RMAX# = 6
-ROLL# = 0
-I# = 0
-FOR I# = 1 TO 5
-  GOSUB RANDOM
-  PRINT "ROLL " + (ROLL# + 1)
-NEXT I#
-END
-
-LABEL RANDOM
-SEED# = MOD(((SEED# * 1103515245) + 12345), 2147483648)
-ROLL# = MOD((SEED# / 65536), RMAX#)
-RETURN
-```
-
-The multiplication stays inside a 64-bit integer for any seed below 2147483648. The
-answer is taken from the middle bits because the low bits of a power-of-two modulus
-barely change from one call to the next. This used to be required; it is now built in.
-
-</details>
-
 `HELD#` is the flag Step 6's loop tests: while it is 1 the ball sits on the paddle, and
 `HOLDBAL` keeps it there:
 
@@ -1418,7 +1422,9 @@ PX# = PX# + D#
 RETURN
 
 LABEL DEMOAIM
-DOFF# = RND(81) - 40
+RMAX# = 81
+GOSUB RANDOM
+DOFF# = RND# - 40
 RETURN
 ```
 
@@ -1495,7 +1501,7 @@ This is the shape of the whole file:
 LABEL SETUP           the geometry from Step 2
                       the declaration block from Step 3
                       the brick faces from Step 5
-                      RND(n) seeds itself from the host clock
+                      SEED# = TI#
                       the ceiling from Step 9
                       GOSUB MKSPR       Step 4
                       GOSUB SNDPROBE    Step 14
@@ -1570,7 +1576,10 @@ BB# = 0
 RX# = 0
 N# = 0
 MROW# = 0
+RMAX# = 2
+RND# = 0
 SND# = 0
+SEED# = 0
 P$ = ""
 H$ = ""
 S$ = ""

docs/18-tutorial-breakout-artwork.md

@@ -1423,8 +1423,7 @@ IF STATE# = 2 THEN GOSUB UNSTICK
 RETURN
 
 LABEL PRESSPAUSE
-IF STATE# = 2 THEN STATE# = 6 : GMTYP# = 0 : BAN$ = "PAUSED"
-IF STATE# = 2 THEN BAN$ = "PAUSED" : GOSUB SETBANNER : RETURN
+IF STATE# = 2 THEN STATE# = 6 : GMTYP# = 0 : BAN$ = "PAUSED" : GOSUB SETBANNER : RETURN
 IF STATE# = 6 THEN STATE# = 2 : BAN$ = "" : GOSUB SETBANNER
 RETURN
 ```

docs/21-tutorial-galaga-enemies.md

@@ -20,7 +20,7 @@ whole development loop; the engine never rebuilds.
 - **[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 hand the script dice the engine controls
+  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
@@ -75,7 +75,7 @@ typedef struct galaga_Enemy
     float    t;		/* parametric clock for the current maneuver	*/
     int32_t  hp;
     int32_t  fire;	/* outbox: script sets 1, engine consumes	*/
-    float    rnd;	/* inbox: fresh 0..1 each call; ROLL% in BASIC	*/
+    float    rnd;	/* inbox: engine writes fresh 0..1 each call	*/
 } galaga_Enemy;
 ```
 
@@ -107,7 +107,7 @@ static const akbasic_HostField ENEMY_FIELDS[] = {
     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,    "ROLL%",    AKBASIC_HOSTFIELD_FLOAT )
+    AKBASIC_HOST_FIELD( galaga_Enemy, rnd,    "RND%",     AKBASIC_HOSTFIELD_FLOAT )
 };
 static const akbasic_HostType ENEMY_TYPE = {
     "ENEMY", sizeof(galaga_Enemy), ENEMY_FIELDS, 8
@@ -194,7 +194,7 @@ 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; ROLL% to the script	*/
+    float    rnd;	/* fresh 0..1 each frame; the issue #16 route	*/
 } galaga_Shared;
 ```
 
@@ -203,24 +203,13 @@ 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 — carry the
-engine's PRNG into the script: write `SELF@.ROLL% < DT% * 1.5` and an enemy's
-trigger finger is a dice roll.
-
-The dialect does now have a native `RND` function — issue #16 closed, and
-[Chapter 12](12-function-reference.md) documents it — so this is no longer the
-*only* route; Chapter 17's breakout hand-rolls a linear congruential generator
-in BASIC as a third. The engine keeps filling the field here on purpose,
-because it buys something `RND` cannot: the numbers come from the example's own
-PRNG rather than libc's, so a headless run is the same game on every machine,
-which is what makes `example_galaga` a test and not just a demo.
-
-**The BASIC name is `ROLL%`, not `RND%`.** A host field is a bare word and
-shares a namespace with every verb and function, so once `RND` became a
-function name a field could no longer be called that — the scanner refuses it
-with *"Reserved word in variable name"*. The C member stays `rnd`; only the
-name the script sees had to move. [Chapter 16](16-structures.md) has the same
-rule for `TYPE` declarations.
+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
 
@@ -362,7 +351,7 @@ 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@.ROLL% < DT% * 1.5 THEN SELF@.FIRE# = 1
+  IF SELF@.RND% < DT% * 1.5 THEN SELF@.FIRE# = 1
   RETURN 0
 END
 ```
@@ -397,7 +386,7 @@ DEF UPDATEBEE(DT%)
   IF (S# AND 2) > 0 THEN BEGIN
     ACTOR@.X% = SELF@.HOMEX% + SIN(SELF@.T% * 1.7) * 16
     ACTOR@.Y% = SELF@.HOMEY%
-    IF SELF@.ROLL% < DT% * 0.04 THEN SELF@.STATE# = 4 : SELF@.T% = 0
+    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)

examples/breakout/characters/breakout.bas

@@ -145,7 +145,7 @@ RX# = 0
 N# = 0
 MROW# = 0
 RMAX# = 2
-ROLL# = 0
+RND# = 0
 SND# = 0
 P$ = ""
 H$ = ""
@@ -172,8 +172,7 @@ BSG$(4) = "[--]"
 BSG$(5) = "[--]"
 
 REM --- the seed -------------------------------------------------------
-REM RND exists now, but this program keeps its own LCG so a headless run
-REM is the same game every time. TI# is jiffies off the host's clock
+REM There is no RND in this dialect. TI# is jiffies off the host's clock
 REM and is host uptime rather than zero-based, which makes it a fine seed.
 SEED# = TI#
 
@@ -390,18 +389,17 @@ BY# = PY# - 10
 RMAX# = 2
 GOSUB RANDOM
 BVX# = BSPD#
-IF ROLL# = 0 THEN BVX# = 0 - BSPD#
+IF RND# = 0 THEN BVX# = 0 - BSPD#
 BVY# = 0 - BSPD#
 PDEC# = 0
 GOSUB SHOWSPR
 RETURN
 
-REM A linear congruential generator. RND(n) would do this in one token
-REM now; the LCG stays because its sequence is reproducible.
+REM A linear congruential generator, because this dialect has no RND.
 REM The multiply stays inside int64 for any seed under 2^31.
 LABEL RANDOM
 SEED# = MOD(((SEED# * 1103515245) + 12345), 2147483648)
-ROLL# = MOD((SEED# / 65536), RMAX#)
+RND# = MOD((SEED# / 65536), RMAX#)
 RETURN
 
 REM ####################################################################
@@ -634,7 +632,7 @@ NUDGE# = 0
 STALL# = 0
 RMAX# = 4
 GOSUB RANDOM
-BVX# = (ROLL# * 3) - 6
+BVX# = (RND# * 3) - 6
 IF BVX# = 0 THEN BVX# = 3
 RETURN
 
@@ -643,7 +641,7 @@ REM like something with a hand on the paddle rather than a mirror.
 LABEL DEMOAIM
 RMAX# = 81
 GOSUB RANDOM
-DOFF# = ROLL# - 40
+DOFF# = RND# - 40
 RETURN
 
 REM ####################################################################

examples/breakout/sprites/breakout.bas

@@ -241,8 +241,7 @@ SLX# = 0
 SLY# = 0
 SLI# = 0
 REM The two eraser stamps. Declared here for exactly the same reason -- built
-REM inside DRAWPROTOS and left undeclared, they were SHAPE:6 and SHAPE:7
-REM inside
+REM inside DRAWPROTOS and left undeclared, they were SHAPE:6 and SHAPE:7 inside
 REM it and empty everywhere else.
 BL$ = ""
 HBL$ = ""
@@ -255,13 +254,10 @@ REM cursor through every DATA item in the program in the order they appear
 REM in the file, so whichever loader runs first gets the DATA that is
 REM written first. The tables are written first.
 REM The text layer repaints every row it owns, opaque, so it has to be moved
-REM out of the way before anything drawn can be seen. Two rows at the bottom
-REM is
+REM out of the way before anything drawn can be seen. Two rows at the bottom is
 REM enough for the final score, and hands the other thirty-five to the drawing
-REM verbs. Everything this game draws then simply stays there -- a drawing
-REM goes
-REM into a layer the frame composites, so nothing here is captured into a
-REM sprite
+REM verbs. Everything this game draws then simply stays there -- a drawing goes
+REM into a layer the frame composites, so nothing here is captured into a sprite
 REM and nothing is redrawn every frame.
 WINDOW 0, 35, 49, 36
 
@@ -297,8 +293,7 @@ ENVELOPE 0, 0, 6, 0, 4
 TEMPO 12
 
 COLLISION 2, BRICKHIT
-REM The stamps, once. They used to be rebuilt whenever the SSHAPE pool ran
-REM dry,
+REM The stamps, once. They used to be rebuilt whenever the SSHAPE pool ran dry,
 REM because every frame's capture spent another slot; nothing captures now, so
 REM eight slots are spent here and never again.
 GOSUB DRAWPROTOS
@@ -379,8 +374,7 @@ COLOR 1, 1
 FOR K# = 0 TO 15
   DRAW 1, 0, 130 + K# TO 67, 130 + K#
 NEXT K#
-REM And an eighth the width of the HUD strip, for the same reason: the strip
-REM is
+REM And an eighth the width of the HUD strip, for the same reason: the strip is
 REM rewritten whenever a number in it changes, and the old digits have to go
 REM somewhere first.
 FOR K# = 0 TO 59
@@ -399,8 +393,7 @@ DPLAY# = 1
 DHUD# = 1
 RETURN
 
-REM Take one brick off the screen: stamp the blank over it. Called when a
-REM brick
+REM Take one brick off the screen: stamp the blank over it. Called when a brick
 REM breaks, so the field is never redrawn as a whole during play -- which is
 REM what lets the whole live-list machinery go.
 LABEL ERASEBRICK
@@ -451,8 +444,7 @@ WIDTH 1
 COLOR 0, 1 : COLOR 1, 4 : COLOR 2, 8 : COLOR 3, 5
 COLOR 4, 11 : COLOR 5, 16 : COLOR 6, 6
 REM The old strip goes first. Nothing here clears the screen -- a drawing
-REM stays, which is the whole point -- so the digits that were there have to
-REM be
+REM stays, which is the whole point -- so the digits that were there have to be
 REM stamped over before the new ones are drawn.
 Z$ = HBL$
 GSHAPE Z$, 0, 0
@@ -503,10 +495,7 @@ IF SNDON# = 0 THEN VOL 0
 RETURN
 
 LABEL PRESSPAUSE
-IF STATE# <> 2 THEN GOTO PRESSPAUSE2
-STATE# = 6 : GMTYP# = 0 : BAN$ = "PAUSED" : GOSUB SETBANNER
-RETURN
-LABEL PRESSPAUSE2
+IF STATE# = 2 THEN STATE# = 6 : GMTYP# = 0 : BAN$ = "PAUSED" : GOSUB SETBANNER : RETURN
 IF STATE# = 6 THEN STATE# = 2 : BAN$ = "" : GOSUB SETBANNER
 RETURN
 

examples/galaga/enemies.c

@@ -71,15 +71,10 @@ static char *ENEMY_CHARACTER[GALAGA_ENEMY_KINDS] = {
 /* --------------------------------------------------------------- random --- */
 
 /*
- * The engine is this script's source of randomness: it refreshes GAME@.ROLL%
- * each frame and SELF@.ROLL% each call from this PRNG. A hand-rolled LCG
- * rather than rand() so a headless run is the same game on every libc, which
- * is what lets interop_test.c assert exact counts. The dialect gained a native
- * RND (issue #16) after this example was written; the field stays because RND
- * would reintroduce exactly the per-machine variation this avoids.
- *
- * The BASIC-visible name is ROLL%, not RND%: host field names share a
- * namespace with verbs and functions, so RND stopped being available as one.
+ * 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;
 

examples/galaga/galaga.bas

@@ -50,7 +50,7 @@ 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@.ROLL% < DT% * 1.5 THEN SELF@.FIRE# = 1
+  IF SELF@.RND% < DT% * 1.5 THEN SELF@.FIRE# = 1
   RETURN 0
 
 REM Bee: enter, breathe in formation, occasionally dive nearly straight.
@@ -65,7 +65,7 @@ DEF UPDATEBEE(DT%)
   IF (S# AND 2) > 0 THEN BEGIN
     ACTOR@.X% = SELF@.HOMEX% + SIN(SELF@.T% * 1.7) * 16
     ACTOR@.Y% = SELF@.HOMEY%
-    IF SELF@.ROLL% < DT% * 0.04 THEN SELF@.STATE# = 4 : SELF@.T% = 0
+    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)
@@ -85,7 +85,7 @@ DEF UPDATEBFLY(DT%)
   IF (S# AND 2) > 0 THEN BEGIN
     ACTOR@.X% = SELF@.HOMEX% + SIN(SELF@.T% * 2.1) * 24
     ACTOR@.Y% = SELF@.HOMEY%
-    IF SELF@.ROLL% < DT% * 0.05 THEN SELF@.STATE# = 4 : SELF@.T% = 0
+    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)
@@ -108,7 +108,7 @@ DEF UPDATEBOSS(DT%)
   IF (S# AND 2) > 0 THEN BEGIN
     ACTOR@.X% = SELF@.HOMEX% + SIN(SELF@.T% * 1.1) * 10
     ACTOR@.Y% = SELF@.HOMEY%
-    IF SELF@.ROLL% < DT% * 0.03 THEN SELF@.STATE# = 4 : SELF@.T% = 0
+    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)

examples/galaga/galaga.h

@@ -77,7 +77,7 @@ typedef struct galaga_Enemy
     float    t;		/* parametric clock for the current maneuver	*/
     int32_t  hp;
     int32_t  fire;	/* outbox: script sets 1, engine consumes	*/
-    float    rnd;	/* inbox: fresh 0..1 each call; ROLL% in BASIC	*/
+    float    rnd;	/* inbox: engine writes fresh 0..1 each call	*/
 } galaga_Enemy;
 
 /** @brief Frame state every enemy may read. Bound once as GAME@. */
@@ -86,7 +86,7 @@ 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; ROLL% to the script	*/
+    float    rnd;	/* fresh 0..1 each frame; the issue #16 route	*/
 } galaga_Shared;
 
 /* --------------------------------------------------------------- screens --- */

examples/galaga/main.c

@@ -491,8 +491,7 @@ static akerr_ErrorContext *frame(bool *running)
     }
 
     /* The shared frame state, refreshed before any enemy thinks. The engine
-     * fills GAME@.ROLL% from its own PRNG rather than letting the script call
-     * the native RND, so a headless run is the same game on every machine. */
+     * 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();

examples/galaga/script.c

@@ -62,7 +62,7 @@ static const akbasic_HostField ENEMY_FIELDS[] = {
     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,    "ROLL%",    AKBASIC_HOSTFIELD_FLOAT )
+    AKBASIC_HOST_FIELD( galaga_Enemy, rnd,    "RND%",     AKBASIC_HOSTFIELD_FLOAT )
 };
 static const akbasic_HostType ENEMY_TYPE = {
     "ENEMY", sizeof(galaga_Enemy), ENEMY_FIELDS, 8
@@ -87,7 +87,7 @@ 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,     "ROLL%",    AKBASIC_HOSTFIELD_FLOAT )
+    AKBASIC_HOST_FIELD( galaga_Shared, rnd,     "RND%",     AKBASIC_HOSTFIELD_FLOAT )
 };
 static const akbasic_HostType GAME_TYPE = {
     "GAME", sizeof(galaga_Shared), GAME_FIELDS, 4

examples/megademo/README.md

@@ -56,10 +56,7 @@ This is a tour of the interpreter's edges, on purpose:
   counterpoint: a genuine 24x21 `SPRSAV` type-in sprite, 63 bytes, which is
   everything `DATA` has room to say. The paint is the reveal, and the exit is a
   stride-63 column dissolve — 63 is coprime to 160, so the walk hits every
-  column once and looks random while carrying no state. The strings come in
-  64-character chunks because a source line is 80 columns, like the machines
-  this pretends to be — the decoder carries its cursor from one `IM$` entry to
-  the next, and the generator refuses to cut inside a run.
+  column once and looks random while carrying no state.
 - **And then the picture is video.** Six delta frames loop the floor grid toward
   you and crawl the sun's slice pattern — full motion video, 1.3 KB total, about
   220 bytes a frame. A delta re-encodes only the rows that changed: an `R`
@@ -85,10 +82,6 @@ This is a tour of the interpreter's edges, on purpose:
   batch a bar of noise drums. Noise is real: `ENVELOPE`'s sixth argument is a
   waveform, 0 to 3, which Chapter 7 forgot to mention. Voice 1 carries the tune so
   the collision blips (voice 2) and scene sweeps (voice 3) never steal its channel.
-  A batch is four `PLAY` statements, one bar each — the 80-column line limit will
-  not hold four bars in one string, and it does not need to: the parser's voice,
-  envelope and duration state persists across statements and every `PLAY` appends
-  to the same queue, so four bars queue exactly as one line would.
 
 It also probes for its hardware like a proper boot loader, with one `TRAP` per
 device: no graphics refuses by name and exits, no audio mutes the soundtrack, no

examples/megademo/megademo.bas

@@ -10,7 +10,7 @@ REM  A demoscene production for the akbasic interpreter, written as if
 REM  it were 1985 and this dialect were the machine under the tree.
 REM  It leans on every corner of the interpreter on purpose:
 REM
-REM    - it carries chapter 17's LCG rather than the native RND, and seeds it
+REM    - there is no RND, so it carries chapter 17's LCG and seeds it
 REM      from the jiffy clock
 REM    - the palette cannot be rewritten, so every "colour cycle" is an
 REM      honest redraw of the same strokes in the next colour
@@ -81,7 +81,7 @@ REM  machine and a predeclared scratch variable occupies one forever,
 REM  where a scoped one gives its slot back. The first cut of this
 REM  program predeclared everything and ran the pool dry.
 RMAX# = 0
-ROLL# = 0
+RND# = 0
 TX% = 0
 TB# = 0
 
@@ -461,78 +461,38 @@ BS% = W# / 160
 IF BS% < 1 THEN BS% = 1
 REM  ---- PICTURE-BEGIN (generated by vaporwave.py; do not
 REM  ---- hand-edit -- rerun the script to change the picture)
-DIM IM$(56)
+DIM IM$(16)
 DIM VA#(6)
 DIM VB#(6)
-NS# = 32
-VA#(0) = 32
-VB#(0) = 35
-VA#(1) = 36
-VB#(1) = 39
-VA#(2) = 40
-VB#(2) = 43
-VA#(3) = 44
-VB#(3) = 47
-VA#(4) = 48
-VB#(4) = 51
-VA#(5) = 52
-VB#(5) = 55
-IM$(0) = "G9G9G9G9GPGHEHG9GTEHG9GTEHGPGPEHG9GTEHG9GTEHGHGXEHGTBAG8EHG9GTEH"
-IM$(1) = "G5EHGPEHG5EHGPEHG5EHGAPAG3EHGPEHG5EHGPEHGXGHEHG5EHGPEHG5EHGFBAGI"
-IM$(2) = "EHGPGPEHGPEHGHEHGPEHGPEHGHEHGPEHGHEHGPEHGPEHGHEHGBPAGMEHGPEHGHEH"
-IM$(3) = "GPEHGHEHGPEHGPEHGHEHGPEHGPEHGHEHGPEHGHEPGHEHGPEHGHEPGHEHGPEHGHEP"
-IM$(4) = "GHEHGHEGBAEHGHEHGPEHGHEPGHEHGPEHGHEHGPEHGHEPGHEHGPEHGHEPGHEHGPEC"
-IM$(5) = "PAEDGHEPGHEHGHEPGHEPGHEHGHEPGHEPGHEHGHEPGHEHGHEPGHEPGHECBAEDGHEP"
-IM$(6) = "GHEPGHEHGHEPGHEHGHEPGHEPGHEHGHEPGHEPEPGHEPGHE5GHEPGHE5GHEHEXGHEP"
-IM$(7) = "GHEEPAEZGHEPGHE5GHE5GHEPGHE5GHEPGHE5GHE9ETGHE9ETGHEXEHGHE9ETGHHA"
-IM$(8) = "E9ESGHEPEPGBBAGEE9EMHOE9ETGHEHE9E7HUE9E6E9E4H0E9E3E9E3H2E9EHBAET"
-IM$(9) = "EHKHE9ELH6E9ECKHEPEPKHE9EBH9HAE9EIKHEHEXKHE2H9HCE9EPKHE5KHEPKDH9"
-IM$(10) = "HEKCEPKHE5KHE5KHEKH9HGEBKHEPKHEXEHKHE5KHEBH9HIEIKHEPKHEPEPKHEPKH"
-IM$(11) = "EHKAH9HKKHEHKHEPKHEHKHEPKHEPKHH9HMEGKHEHKHEPKHEHKHEPKHEPH9HMEOKH"
-IM$(12) = "EHKHEPKHEHKPEHKHEGH9HOKFEPKHEHKPEHKHEHKPEHKGH9HOEFKHEPKHEHKHEPKH"
-IM$(13) = "EHKPEFH9HQKEEHKHEPKHEHKHEPKHEHKMH9HSKLEHKHEPKHEHKPEHKHEHKEH9HSED"
-IM$(14) = "KPEHKPEHKHEHKPEHKHEEH9HSKDEHKPEHKPKPEHKPEHKDH9HUECKHEHKPEHKHKXEH"
-IM$(15) = "KPEDH9HUKCEHK5EHK5EHKLH9HUKKEHK5EHK5EHKCH9HWEBKPEHKXKHEHK8I9IWKZ"
-IM$(16) = "EHKPKPEHK0I9IWK7EHKHKXEHKSI9IWK9KFEHK9KOI9IWK9KNK9KOI9IWK9KNK9KO"
-IM$(17) = "I9IWK9KNKPIHKZI9IYK6IHKHKXIHKSI9IWK9KFIHK5IHKKI9IWK9KNIHK5IHKCI9"
-IM$(18) = "IYKPIHKXKHIHK5IHKPIHK5IHKPIHKPKPIHK0I9IWKJIHKPIHKHIHKPIHKPI9IZKB"
-IM$(19) = "IHKHIHKPIHKHIHKPIHKKI9IWKJIHKHIHKPIHKHIHKPIHKDI9IXKPIHKHIHKHKHIH"
-IM$(20) = "KHIPKHI9IYKCIHKPIHKHIHKPIHKHIPKHIHKPIHKHIPKHIHKPIHKHIHKPIHKHI9I9"
-IM$(21) = "IHKHIHKPIHKHIPKHIHKHIEC9CSKDIPKHIPKHIHKHIPKHIHKEC9CSIDKHIPKHIPIP"
-IM$(22) = "KHIPKHIFC9CQKEIHKHIPKHIHIXKHIPKGC9COIFKHI5KHI5KHIPKHI5KHIPKHI5KH"
-IM$(23) = "I5KHIPKHI5KHIPKHIXIHKHI9IDC9CMI4KHIPIPKHI6C9CKI9IDKHIHIXKHIZC9CI"
-IM$(24) = "I9IMKHI9IWC9CGI9IVI9I9I9I9IPI9I9I9I9IPQ9Q9Q9Q9QPE9E9E9E9EPE9E9E9"
-IM$(25) = "E9EPQ9Q9Q9Q9QPE9E9E9E9EPQ9Q9Q9Q9QPE9E9E9E9EPQ9Q9Q9Q9QPQ9Q9Q9Q9QP"
-IM$(26) = "Q9Q9Q9Q9QPQ9Q9Q9Q9QPE9E9E9E9EPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9"
-IM$(27) = "Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPE9E9E9E9EPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9"
-IM$(28) = "QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9"
-IM$(29) = "Q9Q9Q9QPE9E9E9E9EPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9"
-IM$(30) = "Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QP"
-IM$(31) = "Q9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QP"
-IM$(32) = "RBRQ9QOKMQHK5RBSQ9QTI9IRRBXQ9QTKPQHKHQPKERBYQ9QPI9IHRB3Q9QSKAI5"
-IM$(33) = "KHIJRB5Q9QTC9CMRB9Q9QWI9IGRCBQ9QYC9CCRCIA9A9A9A9APRCJE9E9E9E9EP"
-IM$(34) = "RCNA9A9A9A9APRCOE9E9E9E9EPRCUA9A9A9A9APRCVE9E9E9E9EPRC5A9A9A9A9"
-IM$(35) = "APRC7E9E9E9E9EP"
-IM$(36) = "RBQQ9QOK9KIQHKFRBRQ9QOI9IQRBWQ9QPKLQHKHQHKPRBXQ9QTI9QLIERB2Q9QR"
-IM$(37) = "IBKHIPKHIPKCRB4Q9QSC9CORB8Q9QVI3KHIGRCAQ9QXC9CERCJA9A9A9A9APRCK"
-IM$(38) = "E9E9E9E9EPRCOA9A9A9A9APRCPE9E9E9E9EPRCVA9A9A9A9APRCXE9E9E9E9EP"
-IM$(39) = "RC7A9A9A9A9APRDAE9E9E9E9EP"
-IM$(40) = "RBPQ9QOK9KAQHKNRBQQ9QOI9IWRBVQ9QOKEQHKHQHKPQHKFRBWQ9QPI9IPRB1Q9"
-IM$(41) = "QQKCIPKHIPKHIDRB3Q9QSC9CORB7Q9QUIWKHIPRB9Q9QWC9CGRCEA9A9A9A9AP"
-IM$(42) = "RCFE9E9E9E9EPRCGA9A9A9A9APRCHE9E9E9E9EPRCPA9A9A9A9APRCQE9E9E9E9"
-IM$(43) = "EPRCXA9A9A9A9APRCZE9E9E9E9EPRDAA9A9A9A9APRDCE9E9E9E9EP"
-IM$(44) = "RBOQ9QNK3QHKWRBPQ9QOI9IWRBUQ9QTKHQHKPQHKNRBVQ9QOI9IWRB0Q9QQIKKH"
-IM$(45) = "IPKHIHKDRB1Q9QQC9CSRB2Q9QRC9CQRB6Q9QTIPKHIYRB8Q9QVC9CIRCKA9A9A9"
-IM$(46) = "A9APRCLE9E9E9E9EPRCQA9A9A9A9APRCRE9E9E9E9EPRCZA9A9A9A9APRC1E9E9"
-IM$(47) = "E9E9EPRDCA9A9A9A9APRDFE9E9E9E9EP"
-IM$(48) = "RBOQ9QNI9IYRBTQ9QOKEQHKPQHKVRBUQ9QTI9IRRBZQ9QTKHQHKPQHKHRB0Q9QQ"
-IM$(49) = "C9CSRB5Q9QTIHKHI5KARB7Q9QUC9CKRCBQ9QYI9ICRCHA9A9A9A9APRCIE9E9E9"
-IM$(50) = "E9EPRCLA9A9A9A9APRCME9E9E9E9EPRCRA9A9A9A9APRCTE9E9E9E9EPRC1A9A9"
-IM$(51) = "A9A9APRC3E9E9E9E9EPRDFA9A9A9A9APRDIE9E9E9E9EP"
-IM$(52) = "RBSQ9QTKPQHK3RBTQ9QOI9IWRBYQ9QPKDQHKPQHKHRBZQ9QTI9ILRB4Q9QSIAKH"
-IM$(53) = "I5KHIBRB6Q9QTC9CMRCAQ9QXI9IERCEE9E9E9E9EPRCFA9A9A9A9APRCGE9E9E9"
-IM$(54) = "E9EPRCMA9A9A9A9APRCNE9E9E9E9EPRCTA9A9A9A9APRCUE9E9E9E9EPRC3A9A9"
-IM$(55) = "A9A9APRC5E9E9E9E9EPRDIA9A9A9A9AP"
+NS# = 9
+VA#(0) = 9
+VB#(0) = 9
+VA#(1) = 10
+VB#(1) = 10
+VA#(2) = 11
+VB#(2) = 12
+VA#(3) = 13
+VB#(3) = 13
+VA#(4) = 14
+VB#(4) = 14
+VA#(5) = 15
+VB#(5) = 15
+IM$(0) = "G9G9G9G9GPGHEHG9GTEHG9GTEHGPGPEHG9GTEHG9GTEHGHGXEHGTBAG8EHG9GTEHG5EHGPEHG5EHGPEHG5EHGAPAG3EHGPEHG5EHGPEHGXGHEHG5EHGPEHG5EHGFBAGIEHGPGPEHGPEHGHEHGPEHGPEHGHEHGPEHGHEHGPEHGPEHGHEHGBPAGMEHGPEHGHEHGPEHGHEHGPEHGPEHGHEHGPEHGPEHGHEHGPEHGHEPGHEHGPEH"
+IM$(1) = "GHEPGHEHGPEHGHEPGHEHGHEGBAEHGHEHGPEHGHEPGHEHGPEHGHEHGPEHGHEPGHEHGPEHGHEPGHEHGPECPAEDGHEPGHEHGHEPGHEPGHEHGHEPGHEPGHEHGHEPGHEHGHEPGHEPGHECBAEDGHEPGHEPGHEHGHEPGHEHGHEPGHEPGHEHGHEPGHEPEPGHEPGHE5GHEPGHE5GHEHEXGHEPGHEEPAEZGHEPGHE5GHE5GHEPGHE5GHEP"
+IM$(2) = "GHE5GHE9ETGHE9ETGHEXEHGHE9ETGHHAE9ESGHEPEPGBBAGEE9EMHOE9ETGHEHE9E7HUE9E6E9E4H0E9E3E9E3H2E9EHBAETEHKHE9ELH6E9ECKHEPEPKHE9EBH9HAE9EIKHEHEXKHE2H9HCE9EPKHE5KHEPKDH9HEKCEPKHE5KHE5KHEKH9HGEBKHEPKHEXEHKHE5KHEBH9HIEIKHEPKHEPEPKHEPKHEHKAH9HKKHEHKHEP"
+IM$(3) = "KHEHKHEPKHEPKHH9HMEGKHEHKHEPKHEHKHEPKHEPH9HMEOKHEHKHEPKHEHKPEHKHEGH9HOKFEPKHEHKPEHKHEHKPEHKGH9HOEFKHEPKHEHKHEPKHEHKPEFH9HQKEEHKHEPKHEHKHEPKHEHKMH9HSKLEHKHEPKHEHKPEHKHEHKEH9HSEDKPEHKPEHKHEHKPEHKHEEH9HSKDEHKPEHKPKPEHKPEHKDH9HUECKHEHKPEHKHKXEH"
+IM$(4) = "KPEDH9HUKCEHK5EHK5EHKLH9HUKKEHK5EHK5EHKCH9HWEBKPEHKXKHEHK8I9IWKZEHKPKPEHK0I9IWK7EHKHKXEHKSI9IWK9KFEHK9KOI9IWK9KNK9KOI9IWK9KNK9KOI9IWK9KNKPIHKZI9IYK6IHKHKXIHKSI9IWK9KFIHK5IHKKI9IWK9KNIHK5IHKCI9IYKPIHKXKHIHK5IHKPIHK5IHKPIHKPKPIHK0I9IWKJIHKPIH"
+IM$(5) = "KHIHKPIHKPI9IZKBIHKHIHKPIHKHIHKPIHKKI9IWKJIHKHIHKPIHKHIHKPIHKDI9IXKPIHKHIHKHKHIHKHIPKHI9IYKCIHKPIHKHIHKPIHKHIPKHIHKPIHKHIPKHIHKPIHKHIHKPIHKHI9I9IHKHIHKPIHKHIPKHIHKHIEC9CSKDIPKHIPKHIHKHIPKHIHKEC9CSIDKHIPKHIPIPKHIPKHIFC9CQKEIHKHIPKHIHIXKHIPKG"
+IM$(6) = "C9COIFKHI5KHI5KHIPKHI5KHIPKHI5KHI5KHIPKHI5KHIPKHIXIHKHI9IDC9CMI4KHIPIPKHI6C9CKI9IDKHIHIXKHIZC9CII9IMKHI9IWC9CGI9IVI9I9I9I9IPI9I9I9I9IPQ9Q9Q9Q9QPE9E9E9E9EPE9E9E9E9EPQ9Q9Q9Q9QPE9E9E9E9EPQ9Q9Q9Q9QPE9E9E9E9EPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9"
+IM$(7) = "Q9QPE9E9E9E9EPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPE9E9E9E9EPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPE9E9E9E9EPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9"
+IM$(8) = "Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QPQ9Q9Q9Q9QP"
+IM$(9) = "RBRQ9QOKMQHK5RBSQ9QTI9IRRBXQ9QTKPQHKHQPKERBYQ9QPI9IHRB3Q9QSKAI5KHIJRB5Q9QTC9CMRB9Q9QWI9IGRCBQ9QYC9CCRCIA9A9A9A9APRCJE9E9E9E9EPRCNA9A9A9A9APRCOE9E9E9E9EPRCUA9A9A9A9APRCVE9E9E9E9EPRC5A9A9A9A9APRC7E9E9E9E9EP"
+IM$(10) = "RBQQ9QOK9KIQHKFRBRQ9QOI9IQRBWQ9QPKLQHKHQHKPRBXQ9QTI9QLIERB2Q9QRIBKHIPKHIPKCRB4Q9QSC9CORB8Q9QVI3KHIGRCAQ9QXC9CERCJA9A9A9A9APRCKE9E9E9E9EPRCOA9A9A9A9APRCPE9E9E9E9EPRCVA9A9A9A9APRCXE9E9E9E9EPRC7A9A9A9A9APRDAE9E9E9E9EP"
+IM$(11) = "RBPQ9QOK9KAQHKNRBQQ9QOI9IWRBVQ9QOKEQHKHQHKPQHKFRBWQ9QPI9IPRB1Q9QQKCIPKHIPKHIDRB3Q9QSC9CORB7Q9QUIWKHIPRB9Q9QWC9CGRCEA9A9A9A9APRCFE9E9E9E9EPRCGA9A9A9A9APRCHE9E9E9E9EPRCPA9A9A9A9APRCQE9E9E9E9EPRCXA9A9A9A9APRCZE9E9E9E9EPRDAA9A9A9A9APRDCE9E9E9E9"
+IM$(12) = "EP"
+IM$(13) = "RBOQ9QNK3QHKWRBPQ9QOI9IWRBUQ9QTKHQHKPQHKNRBVQ9QOI9IWRB0Q9QQIKKHIPKHIHKDRB1Q9QQC9CSRB2Q9QRC9CQRB6Q9QTIPKHIYRB8Q9QVC9CIRCKA9A9A9A9APRCLE9E9E9E9EPRCQA9A9A9A9APRCRE9E9E9E9EPRCZA9A9A9A9APRC1E9E9E9E9EPRDCA9A9A9A9APRDFE9E9E9E9EP"
+IM$(14) = "RBOQ9QNI9IYRBTQ9QOKEQHKPQHKVRBUQ9QTI9IRRBZQ9QTKHQHKPQHKHRB0Q9QQC9CSRB5Q9QTIHKHI5KARB7Q9QUC9CKRCBQ9QYI9ICRCHA9A9A9A9APRCIE9E9E9E9EPRCLA9A9A9A9APRCME9E9E9E9EPRCRA9A9A9A9APRCTE9E9E9E9EPRC1A9A9A9A9APRC3E9E9E9E9EPRDFA9A9A9A9APRDIE9E9E9E9EP"
+IM$(15) = "RBSQ9QTKPQHK3RBTQ9QOI9IWRBYQ9QPKDQHKPQHKHRBZQ9QTI9ILRB4Q9QSIAKHI5KHIBRB6Q9QTC9CMRCAQ9QXI9IERCEE9E9E9E9EPRCFA9A9A9A9APRCGE9E9E9E9EPRCMA9A9A9A9APRCNE9E9E9E9EPRCTA9A9A9A9APRCUE9E9E9E9EPRC3A9A9A9A9APRC5E9E9E9E9EPRDIA9A9A9A9AP"
 REM  ---- PICTURE-END
 SS# = 0
 SE# = NS# - 1
@@ -816,12 +776,11 @@ REM =====================================================================
 REM  Subroutines.
 REM =====================================================================
 
-REM  Chapter 17's historical generator, verbatim. RND(n) is built in now;
-REM  this stays so the demo runs identically on every machine.
-REM  Answers 0 to RMAX#-1 in ROLL#, from the middle bits of the seed.
+REM  Chapter 17's generator, verbatim: there is no RND in this dialect.
+REM  Answers 0 to RMAX#-1 in RND#, from the middle bits of the seed.
 LABEL RANDOM
 SEED# = MOD(((SEED# * 1103515245) + 12345), 2147483648)
-ROLL# = MOD((SEED# / 65536), RMAX#)
+RND# = MOD((SEED# / 65536), RMAX#)
 RETURN
 
 REM  NS# stars in four brightnesses. Two LCG pulls a star, and the
@@ -831,10 +790,10 @@ SI# = 0
 DO WHILE SI# < NS#
   RMAX# = W#
   GOSUB RANDOM
-  X# = ROLL#
+  X# = RND#
   RMAX# = H#
   GOSUB RANDOM
-  Y# = ROLL#
+  Y# = RND#
   B# = MOD(SEED#, 4)
   COLOR 1, STC#(B#)
   DRAW 1, X#, Y#
@@ -1292,7 +1251,7 @@ LABEL REHOME
 MOVSPR L2#, 0.5 * W#, 0.5 * H#
 RMAX# = 360
 GOSUB RANDOM
-SBG#(L2#) = ROLL#
+SBG#(L2#) = RND#
 MOVSPR L2#, SBG#(L2#) # 5
 RETURN
 
@@ -1358,25 +1317,13 @@ TB# = TB# + 1
 IF TB# > 2 THEN TB# = 0
 RETURN
 
-REM  A batch is four PLAY statements, one bar each: the parser's V, T,
-REM  U and duration state persists across statements and every PLAY
-REM  appends to the same queue, so four bars queue exactly as one long
-REM  string would -- which the 80-column line limit no longer allows.
-REM  Each bar restates the prefix anyway, so a bar dropped by QFULL
-REM  never leaves the next one playing with drum-kit state.
 LABEL TUNEA
-PLAY "V1T3U9S O1AO2AO3AO2AO3AO4CEAO1AO2AO4CEAO5CO4AE"
-PLAY "V1T3U9S O1FO2FO3FO2FO3FAO4CFO1FO2FO3AO4CFAO5CO4A"
-PLAY "V1T3U9S O1CO2CO3CO2CO3CEGO4CO1CO2CO3EGO4CEGO5C"
-PLAY "V1T3U9S O1GO2GO3GO2GO3GBO4DGO1GO2GO3BO4DGBO5DO4B"
+PLAY "V1T3U9S O1AO2AO3AO2AO3AO4CEAO1AO2AO4CEAO5CO4AE O1FO2FO3FO2FO3FAO4CFO1FO2FO3AO4CFAO5CO4A O1CO2CO3CO2CO3CEGO4CO1CO2CO3EGO4CEGO5C O1GO2GO3GO2GO3GBO4DGO1GO2GO3BO4DGBO5DO4B"
 MT# = TI# + 270
 RETURN
 
 LABEL TUNEB
-PLAY "V1T3U9S O1AO2AO3AO2AO3AO4CEAO1AO2AO4CEAO5CEO4A"
-PLAY "V1T3U9S O1FO2FO3FO2FO3FAO4CFO1FO2FO3AO4CFAO5CO4A"
-PLAY "V1T3U9S O1DO2DO3DO2DO3DFAO4DO1DO2DO3FAO4DFAO5D"
-PLAY "V1T3U9S O1EO2EO3EO2EO3E#GBO4EO1EO2EO3#GBO4E#GBO5E"
+PLAY "V1T3U9S O1AO2AO3AO2AO3AO4CEAO1AO2AO4CEAO5CEO4A O1FO2FO3FO2FO3FAO4CFO1FO2FO3AO4CFAO5CO4A O1DO2DO3DO2DO3DFAO4DO1DO2DO3FAO4DFAO5D O1EO2EO3EO2EO3E#GBO4EO1EO2EO3#GBO4E#GBO5E"
 MT# = TI# + 270
 RETURN
 

examples/megademo/vaporwave.py

@@ -58,14 +58,7 @@ SKIP = "Q"
 ROWREC = "R"
 LENCH = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
 MAXRUN = len(LENCH)
-
-# The interpreter reads source through an 80-byte line buffer and refuses
-# any line that fills it (AKBASIC_MAX_LINE_LENGTH, sink_stdio.c), so a
-# stored line is at most 78 characters plus its newline. 'IM$(NN) = "' and
-# the closing quote spend 12 of those; 64 keeps the emitted lines under
-# the ceiling with margin to spare while the index stays two digits.
-PAYLOAD = 64
-MAXLINE = 78
+PAYLOAD = 240
 
 SUN_CX, SUN_CY, SUN_R = 80, 50, 30
 HORIZON = 74
@@ -213,32 +206,13 @@ def encode_delta(prev, cur):
 
 
 def chop(blob):
-    """Split a stream into strings of at most PAYLOAD characters, cutting
-    only between records. The decoder reads a record's tail characters
-    with MID on the string it is walking, so a run (two characters) or a
-    row record (three) that straddled two IM$ entries would decode as
-    garbage; DRAWSTREAM only carries the cursor, never a partial record."""
-    out, cur = [], ""
-    p = 0
-    while p < len(blob):
-        n = 3 if blob[p] == ROWREC else 2
-        if len(cur) + n > PAYLOAD:
-            out.append(cur)
-            cur = ""
-        cur += blob[p:p + n]
-        p += n
-    if cur:
-        out.append(cur)
-    return out
+    return [blob[i:i + PAYLOAD] for i in range(0, len(blob), PAYLOAD)]
 
 
-def simulate(raster, blob, x=0, y=0):
+def simulate(raster, blob):
     """Apply one encoded stream to a raster exactly the way the BASIC
-    decoder does, skips-draw-nothing and all. The cursor comes in and
-    goes back out because DRAWSTREAM carries it from one IM$ entry to
-    the next -- decoding the chopped strings one at a time with the
-    cursor threaded through is exactly what the demo will execute."""
-    p = 0
+    decoder does, skips-draw-nothing and all."""
+    x = y = p = 0
     while p < len(blob):
         c = blob[p]
         if c == ROWREC:
@@ -256,31 +230,20 @@ def simulate(raster, blob, x=0, y=0):
             x = 0
             y += 1
         p += 2
-    return raster, x, y
-
-
-def simulate_lines(raster, lines):
-    """One stream as its chopped strings, cursor carried across the
-    boundaries the way DRAWSTREAM carries X# and Y#."""
-    x = y = 0
-    for line in lines:
-        raster, x, y = simulate(raster, line, x, y)
     return raster
 
 
-def verify(frames, base_lines, delta_line_groups):
+def verify(frames, base_blob, delta_blobs):
     """The base must reproduce frame 0 exactly, and each delta must
     carry the raster exactly to the next frame. A skip leaves the cell
     the encoder promised was already right, so equality is total and
-    any difference at all is an encoder bug. This decodes the CHOPPED
-    strings, not the blobs, so a chop that split a record would fail
-    here instead of corrupting the screen."""
+    any difference at all is an encoder bug."""
     raster = [[1] * W for _ in range(H)]
-    raster = simulate_lines(raster, base_lines)
+    raster = simulate(raster, base_blob)
     assert raster == frames[0], "base stream does not reproduce frame 0"
-    for i, lines in enumerate(delta_line_groups):
+    for i, blob in enumerate(delta_blobs):
         want = frames[(i + 1) % PHASES]
-        raster = simulate_lines(raster, lines)
+        raster = simulate(raster, blob)
         assert raster == want, "delta %d does not reproduce its frame" % i
 
 
@@ -298,9 +261,6 @@ def emit_block(base_lines, delta_ranges, all_lines):
     for i, s in enumerate(all_lines):
         out.append('IM$(%d) = "%s"' % (i, s))
     out.append("REM  ---- PICTURE-END")
-    for line in out:
-        assert len(line) <= MAXLINE, "emitted line over %d chars: %r" % (
-            MAXLINE, line)
     return out
 
 
@@ -343,15 +303,15 @@ def main():
     base_lines = chop(base_blob)
     all_lines = list(base_lines)
     delta_ranges = []
-    delta_line_groups = []
+    delta_blobs = []
     for i in range(PHASES):
         blob = encode_delta(frames[i], frames[(i + 1) % PHASES])
+        delta_blobs.append(blob)
         lines = chop(blob)
-        delta_line_groups.append(lines)
         delta_ranges.append((len(all_lines), len(all_lines) + len(lines) - 1))
         all_lines.extend(lines)
-    verify(frames, base_lines, delta_line_groups)
-    dbytes = sum(len(l) for g in delta_line_groups for l in g)
+    verify(frames, base_blob, delta_blobs)
+    dbytes = sum(len(b) for b in delta_blobs)
     print("base %d bytes in %d strings; video %d bytes in %d strings; "
           "%d strings total" %
           (sum(len(s) for s in base_lines), len(base_lines), dbytes,

include/akbasic/akgl.h

@@ -296,7 +296,7 @@ typedef struct
      *
      * Claimed up front rather than per scan for two reasons. The pool is shared
      * with whatever host this interpreter is embedded in -- a game with its own
-     * shaped actors draws from the same `AKGL_MAX_HEAP_COLLISION_PROXY` -- so
+     * shaped actors draws from the same #AKGL_MAX_HEAP_COLLISION_PROXY -- so
      * running out is a real possibility, and it should be an init-time failure
      * naming the pool rather than a collision scan that starts refusing halfway
      * through a game. And a proxy carries a *copy* of its shape, so there is

include/akbasic/environment.h

@@ -72,37 +72,6 @@ typedef struct akbasic_Environment
      */
     bool exiting;
 
-    /*
-     * Generator state (GEN / EMIT / FOR EACH / DO EACH).
-     *
-     * `isGenerator` is set on the environment a GEN call pushes -- the one
-     * whose body is actually running the GEN's lines, as opposed to the loop's
-     * own environment. `generatorFn` records *which* GEN it is running, so a
-     * FOR EACH/DO EACH that would invoke a GEN currently running higher up the
-     * parent chain (self-recursion) can be told apart from one invoking it
-     * fresh, or invoking a sibling instance of the same GEN sitting detached in
-     * someone else's `forGeneratorEnv`. It carries an akbasic_FunctionDef *, kept
-     * as void * for the same reason akbasic_environment_get_function() does:
-     * runtime.h includes this header, not the other way around.
-     */
-    bool isGenerator;
-    void *generatorFn;
-    /**
-     * Set on a FOR EACH or DO EACH loop's own environment, distinguishing it
-     * from a plain FOR/DO for verbs that need to know which kind of loop this
-     * is -- EXIT, NEXT and LOOP all read it.
-     */
-    bool isEachLoop;
-    /**
-     * The generator environment a FOR EACH/DO EACH loop is suspended on
-     * between iterations -- alive, detached from the step loop, but not
-     * released, so its own `nextline` still says where to resume. NULL means
-     * either "not an EACH loop" or "the generator is exhausted": both leave
-     * nothing to resume, and by the time either becomes true the loop
-     * environment itself is on its way out too.
-     */
-    struct akbasic_Environment *forGeneratorEnv;
-
     int64_t gosubReturnLine;
 
     /* READ state. The identifier leaves are deep copies, so they need storage. */

include/akbasic/error.h

@@ -12,12 +12,9 @@
  * libakerror 2.0.0 is the floor, raised from 1.0.0 because 2.0.0 is an ABI break
  * that a compile against the wrong header cannot survive quietly:
  *
- *   - The context behind `IGNORE` became thread-local. `IGNORE` expands at *our*
- *     call site, so our objects reference that storage under whichever model the
- *     header on the include path declared. 2.0.2 went further and made it a
- *     per-translation-unit `static` snapshot named `akerr_last_ignored`, copied
- *     from the pool slot so the slot can be released; the old spelling
- *     `__akerr_last_ignored` was an `extern` pointer and no longer exists.
+ *   - `__akerr_last_ignored` became thread-local. `IGNORE` expands at *our* call
+ *     site, so our objects reference that symbol under whichever storage model
+ *     the header on the include path declared.
  *   - `akerr_next_error()` now returns a context that already holds a reference,
  *     and `ENSURE_ERROR_READY` no longer increments. Objects compiled against a
  *     1.x header count every reference twice and never give a slot back.

include/akbasic/runtime.h

@@ -102,15 +102,6 @@ typedef struct
     akbasic_ASTLeaf *arglist;
     akbasic_ASTLeaf *expression;
     int64_t lineno;
-    /*
-     * Set by akbasic_parse_gen(), left false by akbasic_parse_def(). GEN and
-     * DEF share this table (TODO.md's namespace decision for generators), so
-     * this is what lets akbasic_runtime_call_function() refuse to run a GEN
-     * called like an ordinary function -- cleanly, before anything is pushed,
-     * rather than relying on EMIT to fail deep inside a call whose BASIC-level
-     * error a caller driving its own step loop would not see raised.
-     */
-    bool isGenerator;
     /*
      * There is deliberately no environment here. It used to be owned by the
      * funcdef and reset on every call, which made a function not re-entrant --
@@ -261,11 +252,6 @@ typedef struct akbasic_Runtime
      */
     int64_t timems;
 
-    /* RND's lazy seed state. The flag distinguishes an unseeded run from a
-     * legitimate LCG state of zero. */
-    int64_t rndseed;
-    bool rndseeded;
-
     /*
      * Set by a branch that has decided the remaining statements on its line
      * belong to the arm it did not take, and cleared at the top of every line.
@@ -604,115 +590,6 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_new_environment(akbasic_Runti
  */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_prev_environment(akbasic_Runtime *obj);
 
-/**
- * @brief Return control to the active scope's parent, without releasing it.
- *
- * The half of akbasic_runtime_prev_environment() that pops; the other half,
- * akbasic_runtime_release_environment(), gives the scope's variables and its
- * pool slot back. Split for EMIT: a generator suspended between iterations
- * has to keep existing -- its own `nextline` is where NEXT resumes it -- so
- * detaching without releasing is what lets `obj->environment` move on to the
- * loop while the generator's scope stays alive, reachable through
- * `forGeneratorEnv`.
- *
- * @param obj Object to initialize, inspect, or modify.
- * @return `NULL` on success, otherwise an error context owned by the caller.
- * @throws AKBASIC_ERR_ENVIRONMENT When the active scope is the root.
- */
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_detach_environment(akbasic_Runtime *obj);
-/**
- * @brief Give a scope's variables and its pool slot back.
- *
- * The other half of akbasic_runtime_prev_environment(): unlike that function,
- * @p env need not be `obj->environment` -- a generator environment sitting
- * detached in some loop's `forGeneratorEnv` is released this way once it is
- * exhausted or abandoned, without disturbing whatever scope is active now.
- *
- * @param obj Object to initialize, inspect, or modify.
- * @param env The scope to release; must not be NULL and must not be the root.
- * @return `NULL` on success, otherwise an error context owned by the caller.
- * @throws AKERR_NULLPOINTER When `env` is NULL.
- */
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_release_environment(akbasic_Runtime *obj, akbasic_Environment *env);
-
-/**
- * @brief Pop and release every scope from the active one up to @p target.
- *
- * The shared teardown for every path that abandons part of the environment
- * chain at once instead of popping it a verb at a time: the error unwinds in
- * akbasic_runtime_pump_generator() and akbasic_runtime_call_function(). Each
- * popped scope's suspended generator (`forGeneratorEnv`), if it still holds
- * one, is released through akbasic_runtime_release_generator() -- a suspended
- * generator is a *child* of its loop scope, so no walk up the parent chain
- * would ever reach it.
- *
- * Stops without error at the root if @p target is not on the chain: callers
- * are already cleaning up after a failure, and releasing everything is the
- * least-wrong answer to a target that has gone missing.
- *
- * @param obj Object to initialize, inspect, or modify.
- * @param target The scope to stop at; it is left active and untouched.
- * @return `NULL` on success, otherwise an error context owned by the caller.
- * @throws AKERR_NULLPOINTER When @p target is NULL.
- */
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_unwind_to_environment(akbasic_Runtime *obj, akbasic_Environment *target);
-
-/**
- * @brief Push a GEN's environment, bind its parameters and run it to its first EMIT.
- *
- * Shared by the EACH branches of `FOR` and `DO`: both look up the same kind of
- * call expression (an `AKBASIC_LEAF_FUNCTION` leaf naming a GEN), guard
- * against invoking a GEN that is already running higher up this same parent
- * chain, evaluate the call's arguments in the caller's scope, bind them into a
- * fresh environment the way a function call does, and run that environment
- * until EMIT detaches it or END GEN ends it with nothing emitted.
- *
- * @p loopenv is left in the state a caller checks afterwards:
- * `loopenv->forGeneratorEnv` is the live generator environment when
- * something was emitted, or NULL when the GEN produced nothing at all.
- *
- * @param obj Object to initialize, inspect, or modify.
- * @param loopenv The FOR EACH/DO EACH loop's own environment; becomes the new
- *        generator environment's parent.
- * @param callexpr The generator call, e.g. `ROOMOBJECTS(CURROOM%)`.
- * @return `NULL` on success, otherwise an error context owned by the caller.
- * @throws AKBASIC_ERR_STATE When the named GEN is already running higher up
- *         this same parent chain.
- */
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_generator_invoke(akbasic_Runtime *obj, akbasic_Environment *loopenv, akbasic_ASTLeaf *callexpr);
-/**
- * @brief Run a suspended generator until it next detaches.
- *
- * Shared by the EACH branches of `NEXT` and `LOOP`: `obj->environment` is
- * expected to already be the generator environment to resume (a caller sets
- * that from `loopenv->forGeneratorEnv` before calling), and this drives the
- * step loop until either EMIT detaches it back to @p loopenv with another
- * value, or END GEN really ends it -- in which case it releases the
- * generator environment itself and clears `loopenv->forGeneratorEnv`.
- *
- * @param obj Object to initialize, inspect, or modify.
- * @param loopenv The FOR EACH/DO EACH loop's own environment, and the pump's
- *        stopping point.
- * @return `NULL` on success, otherwise an error context owned by the caller.
- */
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_pump_generator(akbasic_Runtime *obj, akbasic_Environment *loopenv);
-
-/**
- * @brief Release a live, abandoned generator, wherever EMIT left it suspended.
- *
- * `env` is expected to be a loop's `forGeneratorEnv` -- the resume point, not
- * necessarily the GEN's own call frame, since EMIT may have run several
- * levels below it inside a FOR/DO/GOSUB the body wrote. Walks up from there,
- * releasing every environment through the call frame itself inclusive, so
- * nothing above the resume point is left behind.
- *
- * @param obj Object to initialize, inspect, or modify.
- * @param env The suspended resume point to release.
- * @return `NULL` on success, otherwise an error context owned by the caller.
- * @throws AKERR_NULLPOINTER When `env` is NULL.
- */
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_release_generator(akbasic_Runtime *obj, akbasic_Environment *env);
-
 /**
  * @brief Report a BASIC error on the current line, in the reference's format.
  *
@@ -950,6 +827,13 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_reserve_globals(akbasic_Runti
  * @throws AKBASIC_ERR_BOUNDS When every variable slot is in use.
  */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_new_variable(akbasic_Runtime *obj, akbasic_Variable **dest);
+/**
+ * @brief Take an unused function definition from the runtime's pool.
+ * @param obj Object to initialize, inspect, or modify.
+ * @param dest Output destination populated by the function.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKBASIC_ERR_BOUNDS When every function slot is in use.
+ */
 /**
  * @brief Call a user-defined function with values a caller already has.
  *
@@ -976,13 +860,6 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_new_variable(akbasic_Runtime
  */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_call_function(struct akbasic_Runtime *obj, const char *name, akbasic_Value **args, int nargs, akbasic_Value **dest);
 
-/**
- * @brief Take an unused function definition from the runtime's pool.
- * @param obj Object to initialize, inspect, or modify.
- * @param dest Output destination populated by the function.
- * @return `NULL` on success, otherwise an error context owned by the caller.
- * @throws AKBASIC_ERR_BOUNDS When every function slot is in use.
- */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_new_function(akbasic_Runtime *obj, akbasic_FunctionDef **dest);
 /**
  * @brief File one already-scanned source line under its line number.

include/akbasic/sprite.h

@@ -59,7 +59,7 @@
  * with headroom. The ceiling matters because these come out of libakgl's
  * collision proxy pool, which is shared with whatever host this interpreter is
  * embedded in: eight sprites plus sixty-four solids is seventy-two of
- * `AKGL_MAX_HEAP_COLLISION_PROXY`, and the rest is the host's.
+ * #AKGL_MAX_HEAP_COLLISION_PROXY, and the rest is the host's.
  */
 #ifndef AKBASIC_MAX_SOLIDS
 #define AKBASIC_MAX_SOLIDS		64
@@ -117,7 +117,7 @@ typedef struct
     int speed;			/*   clockwise from vertical, and 0-15		*/
 
     /**
-     * SPRHIT's collision shape: one of the `AKBASIC_SHAPE_*` kinds, and a
+     * SPRHIT's collision shape: one of the #AKBASIC_SHAPE_* kinds, and a
      * rectangle measured from the sprite's top-left corner.
      *
      * `shapeexplicit` is what separates "the program asked for the whole frame"

scripts/mutation_test.py

@@ -282,8 +282,9 @@ def copy_tree(src, dst):
     # and a coverage tree drags along every .gcno/.gcda as well.
     #
     # deps/ is copied wholesale and has to be: the build pulls libakerror and
-    # libakstdlib in with add_subdirectory. The language corpus is the other
-    # reason it comes along with the rest of the tree.
+    # libakstdlib in with add_subdirectory. The golden corpus used to be the
+    # other reason -- it was driven in place out of deps/basicinterpret -- and
+    # now lives in tests/reference/, which comes along with the rest of the tree.
     # Only vendored Windows DLLs are dead weight, hence "*.dll".
     #
     # **PNGs are ours or theirs, and the difference matters.** This used to drop

src/environment.c

@@ -35,10 +35,6 @@ akerr_ErrorContext *akbasic_environment_init(akbasic_Environment *obj, akbasic_R
     obj->doConditionLeaf = NULL;
     obj->doConditionKind = AKBASIC_LOOPCOND_NONE;
     obj->isDoLoop = false;
-    obj->isGenerator = false;
-    obj->generatorFn = NULL;
-    obj->isEachLoop = false;
-    obj->forGeneratorEnv = NULL;
     obj->gosubReturnLine = 0;
     obj->readReturnLine = 0;
     obj->readIdentifierIdx = 0;

src/parser_commands.c

@@ -20,9 +20,6 @@
 
 #include "verbs.h"
 
-/* Shared by akbasic_parse_for() and akbasic_parse_do(); defined after akbasic_parse_def(). */
-static akerr_ErrorContext *parse_each_clause(akbasic_Parser *parser, akbasic_ASTLeaf **var, akbasic_ASTLeaf **callexpr);
-
 akerr_ErrorContext *akbasic_parse_arglist(akbasic_Parser *parser, akbasic_ASTLeaf **dest)
 {
     PREPARE_ERROR(errctx);
@@ -312,58 +309,8 @@ akerr_ErrorContext *akbasic_parse_do(akbasic_Parser *parser, akbasic_ASTLeaf **d
     akbasic_Environment *newenv = NULL;
     akbasic_ASTLeaf *expr = NULL;
     akbasic_ASTLeaf *condition = NULL;
-    akbasic_Token *peeked = NULL;
     int kind = AKBASIC_LOOPCOND_NONE;
     int64_t firstline = parent->lineno + 1;
-    int cmp = 0;
-
-    /*
-     * DO EACH <variable> IN <generator call> ... LOOP. Mutually exclusive with
-     * DO WHILE/UNTIL on the same DO, so this is checked first and returns
-     * before any of the WHILE/UNTIL machinery runs.
-     */
-    peeked = akbasic_parser_peek(parser);
-    if ( peeked != NULL && peeked->tokentype == AKBASIC_TOK_COMMAND ) {
-	PASS(errctx, aksl_strcmp(peeked->lexeme, "EACH", &cmp));
-	if ( cmp == 0 ) {
-	    akbasic_ASTLeaf *var = NULL;
-	    akbasic_ASTLeaf *callexpr = NULL;
-
-	    (void)akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND);
-
-	    PASS(errctx, akbasic_runtime_new_environment(runtime));
-	    newenv = runtime->environment;
-	    runtime->environment = parent;
-
-	    PASS(errctx, parse_each_clause(parser, &var, &callexpr));
-
-	    /*
-	     * Same guard as akbasic_parse_for()'s EACH branch, with the likely
-	     * mistake named: a condition belongs on the LOOP, where it is
-	     * checked against each emitted value, not here on the DO.
-	     */
-	    peeked = akbasic_parser_peek(parser);
-	    FAIL_NONZERO_RETURN(errctx,
-				(peeked != NULL &&
-				 peeked->tokentype != AKBASIC_TOK_UNDEFINED &&
-				 peeked->tokentype != AKBASIC_TOK_COLON),
-				AKBASIC_ERR_SYNTAX,
-				"DO EACH takes its WHILE/UNTIL on the LOOP, and nothing else here");
-
-	    newenv->isDoLoop = true;
-	    newenv->isEachLoop = true;
-	    newenv->loopFirstLine = firstline;
-	    /* See akbasic_parse_for()'s EACH branch for why this is not cloned. */
-	    newenv->forToLeaf = callexpr;
-
-	    PASS(errctx, akbasic_parser_new_leaf(parser, &expr));
-	    PASS(errctx, akbasic_leaf_new_command(expr, "DO", var));
-
-	    runtime->environment = newenv;
-	    *dest = expr;
-	    SUCCEED_RETURN(errctx);
-	}
-    }
 
     PASS(errctx, akbasic_runtime_new_environment(runtime));
     newenv = runtime->environment;
@@ -936,134 +883,6 @@ akerr_ErrorContext *akbasic_parse_def(akbasic_Parser *parser, akbasic_ASTLeaf **
     SUCCEED_RETURN(errctx);
 }
 
-/*
- * GEN NAME(parameters) ... END GEN
- *
- * A DEF that yields more than once, in the same shape a multi-line DEF is:
- * the header is parsed, the parameter list is read with parse_def_parameters()
- * (GEN and DEF share the functions table -- TODO.md's namespace decision for
- * this feature -- so a name cannot be both), and the body is skipped on this,
- * the definitional pass, by arming akbasic_environment_wait_for_command() for
- * "END GEN" instead of "RETURN". It only really executes when a FOR EACH/DO
- * EACH invokes it through akbasic_runtime_generator_invoke(), which sets
- * `nextline` to `fndef->lineno` directly and never runs this line again.
- *
- * There is no single-expression form: a GEN with nothing to loop over is just
- * a DEF, and EMIT already needs a body to sit in.
- */
-akerr_ErrorContext *akbasic_parse_gen(akbasic_Parser *parser, akbasic_ASTLeaf **dest)
-{
-    PREPARE_ERROR(errctx);
-    akbasic_Runtime *runtime = parser->runtime;
-    akbasic_ASTLeaf *identifier = NULL;
-    akbasic_ASTLeaf *arglist = NULL;
-    akbasic_ASTLeaf *command = NULL;
-    akbasic_FunctionDef *fndef = NULL;
-    size_t namelen = 0;
-    size_t i = 0;
-
-    PASS(errctx, akbasic_parser_primary(parser, &identifier));
-    FAIL_ZERO_RETURN(errctx, (identifier->leaftype == AKBASIC_LEAF_IDENTIFIER),
-		     AKBASIC_ERR_SYNTAX, "Expected identifier");
-
-    PASS(errctx, parse_def_parameters(parser, &arglist));
-
-    PASS(errctx, akbasic_runtime_new_function(runtime, &fndef));
-
-    /* Uppercase the name: verbs, functions and generators are all case-insensitive. */
-    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 < namelen; i++ ) {
-	char c = identifier->identifier[i];
-	fndef->name[i] = (char)((c >= 'a' && c <= 'z') ? (c - 'a' + 'A') : c);
-    }
-    fndef->name[namelen] = '\0';
-
-    fndef->expression = NULL;
-    fndef->isGenerator = true;
-    PASS(errctx, akbasic_environment_wait_for_command(runtime->environment, "END GEN"));
-    PASS(errctx, akbasic_leaf_clone(arglist, &fndef->leafpool, &fndef->arglist));
-    fndef->lineno = runtime->environment->lineno + 1;
-
-    PASS(errctx, akbasic_symtab_set(&runtime->environment->functions, fndef->name, fndef, 0));
-
-    PASS(errctx, akbasic_parser_new_leaf(parser, &command));
-    PASS(errctx, akbasic_leaf_new_command(command, "GEN", NULL));
-    *dest = command;
-    SUCCEED_RETURN(errctx);
-}
-
-/*
- * END [GEN]
- *
- * Bare END finishes the program, the default command path's job before this
- * handler existed. `END GEN` is a GEN body's own closing verb, and it is
- * never scanned as one token -- GEN follows END as an ordinary COMMAND token
- * on the same line -- so this is what tells the two apart and builds the
- * compound leaf akbasic_cmd_end_gen dispatches on, the same trick
- * akbasic_parse_print() uses for `PRINT #`.
- */
-akerr_ErrorContext *akbasic_parse_end(akbasic_Parser *parser, akbasic_ASTLeaf **dest)
-{
-    PREPARE_ERROR(errctx);
-    akbasic_ASTLeaf *expr = NULL;
-    akbasic_ASTLeaf *right = NULL;
-    akbasic_Token *peeked = NULL;
-    int cmp = 0;
-
-    peeked = akbasic_parser_peek(parser);
-    if ( peeked != NULL && peeked->tokentype == AKBASIC_TOK_COMMAND ) {
-	PASS(errctx, aksl_strcmp(peeked->lexeme, "GEN", &cmp));
-	if ( cmp == 0 ) {
-	    (void)akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND);
-	    PASS(errctx, akbasic_parser_new_leaf(parser, &expr));
-	    PASS(errctx, akbasic_leaf_new_command(expr, "END GEN", NULL));
-	    *dest = expr;
-	    SUCCEED_RETURN(errctx);
-	}
-    }
-
-    /* A plain END, matching what the default command path used to do. */
-    if ( peeked != NULL && peeked->tokentype != AKBASIC_TOK_UNDEFINED &&
-	 peeked->tokentype != AKBASIC_TOK_COLON ) {
-	PASS(errctx, akbasic_parser_expression(parser, &right));
-    }
-    PASS(errctx, akbasic_parser_new_leaf(parser, &expr));
-    PASS(errctx, akbasic_leaf_new_command(expr, "END", right));
-    *dest = expr;
-    SUCCEED_RETURN(errctx);
-}
-
-/*
- * EACH <variable> IN <generator call>
- *
- * Shared by akbasic_parse_for() and akbasic_parse_do(), both of which consume
- * the leading EACH themselves (it is what tells them this is an EACH loop
- * rather than their ordinary form) before calling this for the rest.
- */
-static akerr_ErrorContext *parse_each_clause(akbasic_Parser *parser, akbasic_ASTLeaf **var, akbasic_ASTLeaf **callexpr)
-{
-    PREPARE_ERROR(errctx);
-    akbasic_Token *word = NULL;
-    int cmp = 0;
-
-    PASS(errctx, akbasic_parser_expression(parser, var));
-    FAIL_ZERO_RETURN(errctx, (*var != NULL && akbasic_leaf_is_identifier(*var)), AKBASIC_ERR_SYNTAX,
-		     "Expected EACH (variable) IN (generator call)");
-
-    FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND), AKBASIC_ERR_SYNTAX,
-		     "Expected IN after EACH (variable)");
-    PASS(errctx, akbasic_parser_previous(parser, &word));
-    PASS(errctx, aksl_strcmp(word->lexeme, "IN", &cmp));
-    FAIL_NONZERO_RETURN(errctx, cmp, AKBASIC_ERR_SYNTAX, "Expected IN after EACH (variable)");
-
-    PASS(errctx, akbasic_parser_expression(parser, callexpr));
-    FAIL_ZERO_RETURN(errctx, (*callexpr != NULL && (*callexpr)->leaftype == AKBASIC_LEAF_FUNCTION),
-		     AKBASIC_ERR_SYNTAX, "Expected a generator call after IN");
-    SUCCEED_RETURN(errctx);
-}
-
 /*
  * FOR     ...        TO ....        [STEP    ...]
  * COMMAND ASSIGNMENT    EXPRESSION  [COMMAND EXPRESSION]
@@ -1079,72 +898,11 @@ akerr_ErrorContext *akbasic_parse_for(akbasic_Parser *parser, akbasic_ASTLeaf **
     akbasic_ASTLeaf *assignment = NULL;
     akbasic_ASTLeaf *expr = NULL;
     akbasic_Token *operator_ = NULL;
-    akbasic_Token *peeked = NULL;
     akbasic_Environment *parent = runtime->environment;
     akbasic_Environment *newenv = NULL;
     int64_t firstline = 0;
     int cmp = 0;
 
-    /*
-     * FOR EACH <variable> IN <generator call>. Checked before the leaf right of
-     * FOR is required to be an assignment, because EACH is the one other thing
-     * that leaf is allowed to be.
-     */
-    peeked = akbasic_parser_peek(parser);
-    if ( peeked != NULL && peeked->tokentype == AKBASIC_TOK_COMMAND ) {
-	PASS(errctx, aksl_strcmp(peeked->lexeme, "EACH", &cmp));
-	if ( cmp == 0 ) {
-	    akbasic_ASTLeaf *var = NULL;
-	    akbasic_ASTLeaf *callexpr = NULL;
-
-	    (void)akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND);
-	    firstline = parent->lineno + 1;
-
-	    /*
-	     * Pushed the same way a plain FOR's environment is: while the
-	     * parent is still active, so the call expression's identifiers
-	     * resolve in the caller's scope rather than the loop's own.
-	     */
-	    PASS(errctx, akbasic_runtime_new_environment(runtime));
-	    newenv = runtime->environment;
-	    runtime->environment = parent;
-
-	    PASS(errctx, parse_each_clause(parser, &var, &callexpr));
-
-	    /*
-	     * Nothing may follow the generator call but another statement.
-	     * Without this, a stray clause sits unparsed on the line and only
-	     * blows up after the whole loop has run, when the parent scope
-	     * resumes the line mid-statement -- an error at the loop's end
-	     * pointing at its beginning.
-	     */
-	    peeked = akbasic_parser_peek(parser);
-	    FAIL_NONZERO_RETURN(errctx,
-				(peeked != NULL &&
-				 peeked->tokentype != AKBASIC_TOK_UNDEFINED &&
-				 peeked->tokentype != AKBASIC_TOK_COLON),
-				AKBASIC_ERR_SYNTAX,
-				"FOR EACH takes nothing after the generator call");
-
-	    newenv->isEachLoop = true;
-	    newenv->loopFirstLine = firstline;
-	    /*
-	     * Stashed on forToLeaf rather than cloned into a leaf pool: unlike
-	     * DO's condition, this expression is evaluated exactly once, by
-	     * akbasic_cmd_for() on this same pass before the per-line leaf
-	     * storage it lives in is reused -- see akbasic_runtime_generator_invoke().
-	     */
-	    newenv->forToLeaf = callexpr;
-
-	    PASS(errctx, akbasic_parser_new_leaf(parser, &expr));
-	    PASS(errctx, akbasic_leaf_new_command(expr, "FOR", var));
-
-	    runtime->environment = newenv;
-	    *dest = expr;
-	    SUCCEED_RETURN(errctx);
-	}
-    }
-
     PASS(errctx, akbasic_parser_assignment(parser, &assignment));
     FAIL_ZERO_RETURN(errctx, akbasic_parser_match1(parser, AKBASIC_TOK_COMMAND),
 		     AKBASIC_ERR_SYNTAX,

src/runtime.c

@@ -143,24 +143,17 @@ akerr_ErrorContext *akbasic_runtime_new_environment(akbasic_Runtime *obj)
     SUCCEED_RETURN(errctx);
 }
 
-akerr_ErrorContext *akbasic_runtime_detach_environment(akbasic_Runtime *obj)
-{
-    PREPARE_ERROR(errctx);
-
-    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in detach_environment");
-    FAIL_ZERO_RETURN(errctx, (obj->environment->parent != NULL), AKBASIC_ERR_ENVIRONMENT,
-		     "No previous environment to return to");
-    obj->environment = obj->environment->parent;
-    SUCCEED_RETURN(errctx);
-}
-
-akerr_ErrorContext *akbasic_runtime_release_environment(akbasic_Runtime *obj, akbasic_Environment *env)
+akerr_ErrorContext *akbasic_runtime_prev_environment(akbasic_Runtime *obj)
 {
     PREPARE_ERROR(errctx);
+    akbasic_Environment *popped = NULL;
     int i = 0;
 
-    FAIL_ZERO_RETURN(errctx, (obj != NULL && env != NULL), AKERR_NULLPOINTER,
-		     "NULL argument in release_environment");
+    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in prev_environment");
+    FAIL_ZERO_RETURN(errctx, (obj->environment->parent != NULL), AKBASIC_ERR_ENVIRONMENT,
+		     "No previous environment to return to");
+    popped = obj->environment;
+    obj->environment = popped->parent;
 
     /*
      * Give back the variables this scope created, as well as the scope.
@@ -180,9 +173,9 @@ akerr_ErrorContext *akbasic_runtime_release_environment(akbasic_Runtime *obj, ak
      * times exhausted the 128-slot pool and reported "Maximum runtime variables
      * reached" on a four-line program.
      */
-    for ( i = 0; i < env->variables.capacity; i++ ) {
-	akbasic_Variable *variable = (akbasic_Variable *)env->variables.slots[i].value;
-	if ( env->variables.slots[i].used && variable != NULL ) {
+    for ( i = 0; i < popped->variables.capacity; i++ ) {
+	akbasic_Variable *variable = (akbasic_Variable *)popped->variables.slots[i].value;
+	if ( popped->variables.slots[i].used && variable != NULL ) {
 	    variable->used = false;
 	}
     }
@@ -192,51 +185,7 @@ akerr_ErrorContext *akbasic_runtime_release_environment(akbasic_Runtime *obj, ak
      * here the pool is finite, so an unreleased environment is a bug that shows
      * up as exhaustion a few thousand GOSUBs later.
      */
-    env->used = false;
-    SUCCEED_RETURN(errctx);
-}
-
-akerr_ErrorContext *akbasic_runtime_prev_environment(akbasic_Runtime *obj)
-{
-    PREPARE_ERROR(errctx);
-    akbasic_Environment *popped = NULL;
-
-    FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in prev_environment");
-    popped = obj->environment;
-    PASS(errctx, akbasic_runtime_detach_environment(obj));
-    PASS(errctx, akbasic_runtime_release_environment(obj, popped));
-    SUCCEED_RETURN(errctx);
-}
-
-akerr_ErrorContext *akbasic_runtime_unwind_to_environment(akbasic_Runtime *obj, akbasic_Environment *target)
-{
-    PREPARE_ERROR(errctx);
-    akbasic_Environment *popped = NULL;
-
-    FAIL_ZERO_RETURN(errctx, (obj != NULL && target != NULL), AKERR_NULLPOINTER,
-		     "NULL argument in unwind_to_environment");
-    /*
-     * Stops early at the root rather than failing on it: every caller is an
-     * error-unwind path, where "release whatever there is" beats raising a
-     * second failure on top of the one being cleaned up after.
-     */
-    while ( obj->environment != target && obj->environment->parent != NULL ) {
-	popped = obj->environment;
-	obj->environment = popped->parent;
-	/*
-	 * An EACH loop scope on its way out takes its suspended generator with
-	 * it -- the generator is a *child* of the scope, off the parent chain,
-	 * and this walk is the only thing that will ever see it again. Guarded
-	 * on `used` because a generator that was being pumped when the failure
-	 * hit is *on* the chain being unwound, already released by the time
-	 * the walk reaches the loop scope that references it.
-	 */
-	if ( popped->forGeneratorEnv != NULL && popped->forGeneratorEnv->used ) {
-	    PASS(errctx, akbasic_runtime_release_generator(obj, popped->forGeneratorEnv));
-	}
-	popped->forGeneratorEnv = NULL;
-	PASS(errctx, akbasic_runtime_release_environment(obj, popped));
-    }
+    popped->used = false;
     SUCCEED_RETURN(errctx);
 }
 
@@ -944,7 +893,7 @@ akerr_ErrorContext *akbasic_runtime_interpret(akbasic_Runtime *obj, akbasic_ASTL
 	     *
 	     * **Only a block skip**, which is what the `BEND` test is for. A
 	     * zero-iteration `FOR` skips its body the same way, and there the
-	     * orphan is load-bearing: `tests/language/.../nestedforloopwaiting
+	     * orphan is load-bearing: `tests/reference/.../nestedforloopwaiting
 	     * forcommand.bas` nests a loop inside one that runs zero times, and
 	     * the inner scope is what absorbs the inner `NEXT` so the outer `NEXT`
 	     * still finds its `FOR`. Popping it there turns that case into "NEXT
@@ -1079,18 +1028,6 @@ akerr_ErrorContext *akbasic_runtime_call_function(akbasic_Runtime *obj, const ch
 
     PASS(errctx, akbasic_environment_get_function(obj->environment, name, &fnptr));
     fndef = (akbasic_FunctionDef *)fnptr;
-    /*
-     * A GEN is not a function: it yields more than once, through EMIT, and
-     * nothing about an ordinary call ever resumes it for a second value.
-     * Refused here, before anything is pushed, rather than left to fail
-     * inside the call -- a BASIC-level error down in EMIT is swallowed by
-     * process_line_run() the same way any statement's is, so a caller
-     * driving its own step loop would see this "succeed" with whatever
-     * garbage was left in the return slot instead of failing at all.
-     */
-    FAIL_NONZERO_RETURN(errctx, fndef->isGenerator, AKBASIC_ERR_STATE,
-			"%s is a GEN; call it with FOR EACH or DO EACH, not as a function",
-			fndef->name);
 
     /*
      * **One environment per call, from the pool -- exactly as GOSUB does.**
@@ -1198,11 +1135,10 @@ akerr_ErrorContext *akbasic_runtime_call_function(akbasic_Runtime *obj, const ch
 	 * 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.
-	 * The unwind, not a bare prev_environment() loop, because a body that
-	 * died inside a FOR EACH leaves a suspended generator hanging off the
-	 * loop scope, and only the unwind knows to take it down too.
 	 */
-	IGNORE(akbasic_runtime_unwind_to_environment(obj, targetenv));
+	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));
@@ -1350,7 +1286,7 @@ akerr_ErrorContext *akbasic_runtime_process_line_runstream(akbasic_Runtime *obj)
      * This mode used to file it like any other, under the cursor -- which for a
      * blank line is the number of the line *before* it. A file ending in a blank
      * line therefore had its last line erased before it ever ran, silently. The
-     * reference did the same, and `tests/language/arithmetic/integer.bas`
+     * reference did the same, and `tests/reference/language/arithmetic/integer.bas`
      * has an expectation with three values for four PRINT statements to prove it.
      */
     if ( buffer[0] == '\0' ) {

src/runtime_commands.c

@@ -161,22 +161,8 @@ akerr_ErrorContext *akbasic_cmd_return(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
 	SUCCEED_TRUE(obj, dest);
 	SUCCEED_RETURN(errctx);
     }
-    /*
-     * A GEN is a function at heart, and RETURN ends it the way it ends a DEF
-     * or a GOSUB: early, cleanly, from its own frame. What a generator's
-     * RETURN cannot do is carry a value -- values leave a GEN one at a time,
-     * through EMIT, and there is no caller waiting on a return slot.
-     */
-    if ( obj->environment->isGenerator ) {
-	FAIL_NONZERO_RETURN(errctx, (expr != NULL && expr->right != NULL), AKBASIC_ERR_STATE,
-			    "A GEN yields values through EMIT; RETURN here takes none");
-	PASS(errctx, akbasic_runtime_prev_environment(obj));
-	obj->environment->forGeneratorEnv = NULL;
-	SUCCEED_TRUE(obj, dest);
-	SUCCEED_RETURN(errctx);
-    }
     FAIL_ZERO_RETURN(errctx, (obj->environment->gosubReturnLine != 0), AKBASIC_ERR_STATE,
-		     "RETURN outside the context of GOSUB, DEF, or GEN");
+		     "RETURN outside the context of GOSUB");
 
     if ( expr != NULL && expr->right != NULL ) {
 	PASS(errctx, akbasic_runtime_evaluate(obj, expr->right, &result));
@@ -854,31 +840,6 @@ akerr_ErrorContext *akbasic_cmd_for(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     bool met = false;
 
     (void)lval; (void)rval;
-    if ( obj->environment->isEachLoop ) {
-	akbasic_Environment *loopenv = obj->environment;
-
-	FAIL_ZERO_RETURN(errctx, (expr != NULL && akbasic_leaf_is_identifier(expr->right)),
-			 AKBASIC_ERR_SYNTAX, "Expected FOR EACH (variable) IN (generator call)");
-	FAIL_ZERO_RETURN(errctx, (loopenv->forToLeaf != NULL), AKBASIC_ERR_STATE,
-			 "Expected FOR EACH (variable) IN (generator call)");
-
-	PASS(errctx, akbasic_environment_get(loopenv, expr->right->identifier,
-					     &loopenv->forNextVariable));
-	FAIL_ZERO_RETURN(errctx, (loopenv->forNextVariable != NULL), AKBASIC_ERR_UNDEFINED,
-			 "Unable to get loop variable %s", expr->right->identifier);
-
-	PASS(errctx, akbasic_runtime_generator_invoke(obj, loopenv, loopenv->forToLeaf));
-	loopenv->forToLeaf = NULL;
-
-	if ( loopenv->forGeneratorEnv == NULL ) {
-	    /* The generator produced nothing: skip the body by waiting for NEXT,
-	       exactly as a zero-iteration plain FOR does. */
-	    PASS(errctx, akbasic_environment_wait_for_command(loopenv, "NEXT"));
-	}
-	SUCCEED_TRUE(obj, dest);
-	SUCCEED_RETURN(errctx);
-    }
-
     FAIL_ZERO_RETURN(errctx, (obj->environment->forToLeaf != NULL && expr != NULL && expr->right != NULL),
 		     AKBASIC_ERR_STATE, "Expected FOR ... TO [STEP ...]");
     FAIL_ZERO_RETURN(errctx,
@@ -930,16 +891,10 @@ akerr_ErrorContext *akbasic_cmd_next(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
 		     "NEXT outside the context of FOR");
     FAIL_ZERO_RETURN(errctx, (expr != NULL && expr->right != NULL), AKBASIC_ERR_SYNTAX,
 		     "Expected NEXT IDENTIFIER");
-    if ( obj->environment->isEachLoop ) {
-	/* EACH accepts any emitted type; the numeric-only check is for plain FOR. */
-	FAIL_ZERO_RETURN(errctx, akbasic_leaf_is_identifier(expr->right), AKBASIC_ERR_SYNTAX,
-			 "Expected NEXT IDENTIFIER");
-    } else {
-	FAIL_ZERO_RETURN(errctx,
-			 (expr->right->leaftype == AKBASIC_LEAF_IDENTIFIER_INT ||
-			  expr->right->leaftype == AKBASIC_LEAF_IDENTIFIER_FLOAT),
-			 AKBASIC_ERR_TYPE, "FOR ... NEXT only valid over INT and FLOAT types");
-    }
+    FAIL_ZERO_RETURN(errctx,
+		     (expr->right->leaftype == AKBASIC_LEAF_IDENTIFIER_INT ||
+		      expr->right->leaftype == AKBASIC_LEAF_IDENTIFIER_FLOAT),
+		     AKBASIC_ERR_TYPE, "FOR ... NEXT only valid over INT and FLOAT types");
 
     obj->environment->loopExitLine = obj->environment->lineno + 1;
 
@@ -954,14 +909,6 @@ akerr_ErrorContext *akbasic_cmd_next(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
 	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "NEXT"));
 	FAIL_ZERO_RETURN(errctx, (obj->environment->parent != NULL), AKBASIC_ERR_ENVIRONMENT,
 			 "NEXT in an orphaned environment");
-	/*
-	 * A live generator abandoned mid-run: release it too, or it never comes
-	 * back to the pool. See MAINTENANCE.md's note on abandoned generators.
-	 */
-	if ( obj->environment->forGeneratorEnv != NULL ) {
-	    PASS(errctx, akbasic_runtime_release_generator(obj, obj->environment->forGeneratorEnv));
-	    obj->environment->forGeneratorEnv = NULL;
-	}
 	obj->environment->parent->nextline = obj->environment->loopExitLine;
 	PASS(errctx, akbasic_runtime_prev_environment(obj));
 	*dest = &obj->staticFalseValue;
@@ -977,37 +924,12 @@ akerr_ErrorContext *akbasic_cmd_next(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
     if ( cmp != 0 ) {
 	FAIL_ZERO_RETURN(errctx, (obj->environment->parent != NULL), AKBASIC_ERR_ENVIRONMENT,
 			 "NEXT in an orphaned environment");
-	if ( obj->environment->forGeneratorEnv != NULL ) {
-	    PASS(errctx, akbasic_runtime_release_generator(obj, obj->environment->forGeneratorEnv));
-	    obj->environment->forGeneratorEnv = NULL;
-	}
 	obj->environment->parent->nextline = obj->environment->nextline;
 	PASS(errctx, akbasic_runtime_prev_environment(obj));
 	*dest = &obj->staticFalseValue;
 	SUCCEED_RETURN(errctx);
     }
 
-    if ( obj->environment->isEachLoop ) {
-	akbasic_Environment *loopenv = obj->environment;
-
-	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "NEXT"));
-	if ( loopenv->forGeneratorEnv != NULL ) {
-	    obj->environment = loopenv->forGeneratorEnv;
-	    PASS(errctx, akbasic_runtime_pump_generator(obj, loopenv));
-	}
-	if ( loopenv->forGeneratorEnv == NULL ) {
-	    /* Exhausted: pop the loop, same landing NEXT always uses when done. */
-	    FAIL_ZERO_RETURN(errctx, (loopenv->parent != NULL), AKBASIC_ERR_ENVIRONMENT,
-			     "NEXT in an orphaned environment");
-	    loopenv->parent->nextline = loopenv->loopExitLine;
-	    PASS(errctx, akbasic_runtime_prev_environment(obj));
-	    *dest = &obj->staticFalseValue;
-	    SUCCEED_RETURN(errctx);
-	}
-	SUCCEED_TRUE(obj, dest);
-	SUCCEED_RETURN(errctx);
-    }
-
     PASS(errctx, akbasic_environment_get(obj->environment, expr->right->identifier, &nextvar));
     FAIL_ZERO_RETURN(errctx, (nextvar != NULL), AKBASIC_ERR_UNDEFINED,
 		     "Unable to get loop variable %s", expr->right->identifier);
@@ -1050,7 +972,7 @@ akerr_ErrorContext *akbasic_cmd_exit(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
      */
     FAIL_NONZERO_RETURN(errctx,
 			(obj->environment->forToValue.valuetype == AKBASIC_TYPE_UNDEFINED &&
-			 !obj->environment->isDoLoop && !obj->environment->isEachLoop),
+			 !obj->environment->isDoLoop),
 			AKBASIC_ERR_STATE, "EXIT outside the context of FOR or DO");
     FAIL_ZERO_RETURN(errctx, (obj->environment->parent != NULL), AKBASIC_ERR_ENVIRONMENT,
 		     "EXIT in an orphaned environment");

src/runtime_disk.c

@@ -407,22 +407,17 @@ akerr_ErrorContext *akbasic_cmd_directory(akbasic_Runtime *obj, akbasic_ASTLeaf
     FAIL_ZERO_RETURN(errctx, (obj != NULL && dest != NULL), AKERR_NULLPOINTER,
 		     "NULL argument in DIRECTORY");
     /*
-     * Refused rather than half-built. This was blocked upstream: listing a
-     * directory needs opendir/readdir, `libakstdlib` did not wrap them, and
-     * this project's rule is that a missing capability gets filed upstream
-     * rather than worked around here (MAINTENANCE.md). That was libakstdlib
-     * issue #10, and it landed -- aksl_opendir, aksl_readdir, aksl_closedir
-     * and aksl_rewinddir all exist as of the revision this tree pins.
+     * Refused rather than half-built. Listing a directory needs opendir/readdir,
+     * which `libakstdlib` does not wrap -- and this project's rule is that a
+     * missing capability gets filed upstream rather than worked around here
+     * (MAINTENANCE.md). Filed as libakstdlib issue #10.
      *
-     * So the blocker is gone and only the work is left. Writing the verb needs
-     * decisions this commit is not the place for: what a listing looks like on
-     * a filesystem with no disk-image block counts, which of the Commodore
-     * wildcard forms to honour, and where the entries go. Tracked as akbasic
-     * issue #55; the refusal stays honest until then rather than growing a
-     * half-listing nobody specified.
+     * The alternative was shelling out to `ls`, which a library has no business
+     * doing, or calling readdir directly and stepping outside the error
+     * convention every other call in this file follows.
      */
     FAIL_RETURN(errctx, AKBASIC_ERR_DEVICE,
-		"DIRECTORY is not implemented yet");
+		"DIRECTORY is not implemented: libakstdlib has no directory-reading wrapper yet");
 }
 
 /* ------------------------------------------------------------ BSAVE/BLOAD -- */

src/runtime_functions.c

@@ -183,69 +183,6 @@ akerr_ErrorContext *akbasic_fn_chr(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     SUCCEED_RETURN(errctx);
 }
 
-akerr_ErrorContext *akbasic_fn_asc(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
-{
-    PREPARE_ERROR(errctx);
-    akbasic_Value *arg = NULL;
-    akbasic_Value *out = NULL;
-    const unsigned char *text = NULL;
-    int64_t codepoint = 0;
-
-    (void)lval; (void)rval;
-    PASS(errctx, first_arg(obj, expr, "ASC", NULL, &arg, &out));
-    FAIL_NONZERO_RETURN(errctx, (arg->valuetype != AKBASIC_TYPE_STRING), AKBASIC_ERR_TYPE,
-			"ASC expected a string");
-    FAIL_ZERO_RETURN(errctx, (arg->stringval[0] != '\0'), AKBASIC_ERR_BOUNDS,
-		     "ASC expected a non-empty string");
-
-    /* Decode the first UTF-8 code point, the inverse of CHR's encoder. */
-    text = (const unsigned char *)arg->stringval;
-    if ( text[0] < 0x80 ) {
-	codepoint = text[0];
-    } else if ( (text[0] & 0xE0) == 0xC0 ) {
-	codepoint = ((int64_t)(text[0] & 0x1F) << 6) |
-		    (text[1] & 0x3F);
-    } else if ( (text[0] & 0xF0) == 0xE0 ) {
-	codepoint = ((int64_t)(text[0] & 0x0F) << 12) |
-		    ((int64_t)(text[1] & 0x3F) << 6) |
-		    (text[2] & 0x3F);
-    } else {
-	codepoint = ((int64_t)(text[0] & 0x07) << 18) |
-		    ((int64_t)(text[1] & 0x3F) << 12) |
-		    ((int64_t)(text[2] & 0x3F) << 6) |
-		    (text[3] & 0x3F);
-    }
-    out->valuetype = AKBASIC_TYPE_INTEGER;
-    out->intval = codepoint;
-    *dest = out;
-    SUCCEED_RETURN(errctx);
-}
-
-akerr_ErrorContext *akbasic_fn_rnd(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
-{
-    PREPARE_ERROR(errctx);
-    akbasic_Value *arg = NULL;
-    akbasic_Value *out = NULL;
-    const int64_t modulus = 2147483648;
-
-    (void)lval; (void)rval;
-    PASS(errctx, first_arg(obj, expr, "RND", NULL, &arg, &out));
-    FAIL_NONZERO_RETURN(errctx, (arg->valuetype != AKBASIC_TYPE_INTEGER), AKBASIC_ERR_TYPE,
-			"RND expected an integer");
-    FAIL_ZERO_RETURN(errctx, (arg->intval > 0), AKBASIC_ERR_VALUE,
-		     "RND count %" PRId64 " must be positive", arg->intval);
-
-    if ( !obj->rndseeded ) {
-	obj->rndseed = obj->timems % modulus;
-	obj->rndseeded = true;
-    }
-    obj->rndseed = (obj->rndseed * 1103515245 + 12345) % modulus;
-    out->valuetype = AKBASIC_TYPE_INTEGER;
-    out->intval = (obj->rndseed / 65536) % arg->intval;
-    *dest = out;
-    SUCCEED_RETURN(errctx);
-}
-
 akerr_ErrorContext *akbasic_fn_hex(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
 {
     PREPARE_ERROR(errctx);

src/runtime_generator.c

@@ -1,307 +0,0 @@
-/**
- * @file runtime_generator.c
- * @brief GEN, EMIT and END GEN, plus the machinery FOR EACH/DO EACH share.
- *
- * A GEN is a DEF that yields more than once. Its body is skipped on the
- * definitional pass exactly as a multi-line DEF's is -- `akbasic_parse_gen()`
- * arms `akbasic_environment_wait_for_command(env, "END GEN")` the same way
- * `akbasic_parse_def()` arms one for `RETURN` -- and it only ever really runs
- * when a `FOR EACH`/`DO EACH` invokes it.
- *
- * That invocation pushes one environment for the whole lifetime of the loop,
- * exactly as a GOSUB or a function call does, except that `EMIT` does not pop
- * it: it hands control back to the loop without releasing anything, so the
- * environment EMIT actually ran in -- which may be nested several levels
- * below the GEN's own call frame, inside a FOR/DO/GOSUB the body wrote --
- * still says exactly where to resume when `NEXT`/`LOOP` calls back into
- * akbasic_runtime_pump_generator(). Only `END GEN` reached for real --
- * meaning `obj->environment->isGenerator` is true and nothing is skipping
- * forward to it -- actually releases the call frame, the way `RETURN`
- * releases a DEF's call environment.
- */
-
-#include <akerror.h>
-#include <akstdlib.h>
-
-#include <akbasic/error.h>
-#include <akbasic/runtime.h>
-#include <akbasic/scanner.h>
-
-#include "verbs.h"
-
-/* Most verbs answer "did something happen"; this is that answer. */
-#define SUCCEED_TRUE(__obj, __dest)			\
-    do {						\
-	*(__dest) = &(__obj)->staticTrueValue;		\
-    } while ( 0 )
-
-akerr_ErrorContext *akbasic_runtime_pump_generator(akbasic_Runtime *obj, akbasic_Environment *loopenv)
-{
-    PREPARE_ERROR(errctx);
-
-    FAIL_ZERO_RETURN(errctx, (obj != NULL && loopenv != NULL), AKERR_NULLPOINTER,
-		     "NULL argument in pump_generator");
-    /*
-     * The same per-line prologue akbasic_runtime_step() and
-     * akbasic_runtime_call_function() run, driving process_line_run() directly
-     * rather than through the ordinary step loop: a generator body is not the
-     * top-level program and nothing else is going to advance it.
-     */
-    ATTEMPT {
-	while ( obj->environment != loopenv && obj->mode == AKBASIC_MODE_RUN ) {
-	    CATCH(errctx, akbasic_runtime_zero(obj));
-	    CATCH(errctx, akbasic_scanner_zero(obj));
-	    CATCH(errctx, akbasic_runtime_process_line_run(obj));
-	}
-    } CLEANUP {
-	/*
-	 * CLEANUP runs unconditionally -- it is not a `catch` -- so it is
-	 * guarded on the one thing that tells success and failure apart here:
-	 * whether `obj->environment` is still `loopenv`. On the ordinary
-	 * success path it already is (that is the ATTEMPT loop's own exit
-	 * condition), so this is a no-op there, exactly as it is meant to be.
-	 * Only a genuine C-level failure -- the scanner or parser raised, or a
-	 * runtime error escaped the swallow process_line_run() ordinarily does
-	 * for a BASIC-level one -- leaves scopes active between here and
-	 * loopenv, and only then does this force them back, taking
-	 * `forGeneratorEnv` down with them since whatever it pointed at is
-	 * among the scopes just released.
-	 */
-	if ( obj->environment != loopenv ) {
-	    IGNORE(akbasic_runtime_unwind_to_environment(obj, loopenv));
-	    loopenv->forGeneratorEnv = NULL;
-	}
-    } PROCESS(errctx) {
-    } FINISH(errctx, true);
-    SUCCEED_RETURN(errctx);
-}
-
-/**
- * @brief Release a live generator, however deep EMIT left it suspended.
- *
- * `loopenv->forGeneratorEnv` is the *resume point*, not necessarily the GEN's
- * own call frame -- EMIT may have run several levels down, inside a FOR/DO/
- * GOSUB the body wrote around it. Abandoning it (EXIT) has to give back every
- * environment from there up through the call frame itself, or everything
- * above the resume point leaks.
- *
- * @param obj Object to initialize, inspect, or modify.
- * @param env The suspended resume point; walks up through its own parents.
- * @return `NULL` on success, otherwise an error context owned by the caller.
- */
-akerr_ErrorContext *akbasic_runtime_release_generator(akbasic_Runtime *obj, akbasic_Environment *env)
-{
-    PREPARE_ERROR(errctx);
-    akbasic_Environment *walk = env;
-    akbasic_Environment *next = NULL;
-    bool isgen = false;
-
-    FAIL_ZERO_RETURN(errctx, (obj != NULL && env != NULL), AKERR_NULLPOINTER,
-		     "NULL argument in release_generator");
-    while ( walk != NULL ) {
-	isgen = walk->isGenerator;
-	next = walk->parent;
-	/*
-	 * A scope between the resume point and the call frame may be an EACH
-	 * loop with its *own* generator suspended off to the side. Releasing
-	 * the loop scope without releasing that generator strands it in the
-	 * pool -- the walk goes through parents and a suspended generator is a
-	 * child. Guarded on `used` so a generator already released as part of
-	 * some enclosing teardown is not released twice.
-	 */
-	if ( walk->forGeneratorEnv != NULL && walk->forGeneratorEnv->used ) {
-	    PASS(errctx, akbasic_runtime_release_generator(obj, walk->forGeneratorEnv));
-	}
-	walk->forGeneratorEnv = NULL;
-	PASS(errctx, akbasic_runtime_release_environment(obj, walk));
-	if ( isgen ) {
-	    break;
-	}
-	walk = next;
-    }
-    SUCCEED_RETURN(errctx);
-}
-
-akerr_ErrorContext *akbasic_runtime_generator_invoke(akbasic_Runtime *obj, akbasic_Environment *loopenv, akbasic_ASTLeaf *callexpr)
-{
-    PREPARE_ERROR(errctx);
-    akbasic_Environment *callenv = NULL;
-    akbasic_Environment *walk = NULL;
-    akbasic_FunctionDef *fndef = NULL;
-    akbasic_ASTLeaf *fnarg = NULL;
-    akbasic_ASTLeaf *paramleaf = NULL;
-    akbasic_Value *argvals[AKBASIC_MAX_CALL_ARGUMENTS];
-    akbasic_Value *unused = NULL;
-    void *fnptr = NULL;
-    int nargs = 0;
-    int i = 0;
-
-    FAIL_ZERO_RETURN(errctx, (obj != NULL && loopenv != NULL && callexpr != NULL), AKERR_NULLPOINTER,
-		     "NULL argument in generator_invoke");
-    FAIL_ZERO_RETURN(errctx, (callexpr->leaftype == AKBASIC_LEAF_FUNCTION), AKBASIC_ERR_SYNTAX,
-		     "Expected a generator call after IN");
-
-    /*
-     * GEN and DEF share the functions table (TODO.md's namespace decision for
-     * this feature), so this is the same lookup akbasic_runtime_call_function()
-     * does. The parser already proved the name resolves and the arity matches
-     * when it parsed `callexpr` -- akbasic_parser_expression() would not have
-     * produced an AKBASIC_LEAF_FUNCTION leaf otherwise -- so a miss here would
-     * mean the function table changed out from under a leaf built against it,
-     * which is not a case this needs its own message for.
-     */
-    PASS(errctx, akbasic_environment_get_function(loopenv, callexpr->identifier, &fnptr));
-    fndef = (akbasic_FunctionDef *)fnptr;
-    FAIL_ZERO_RETURN(errctx, fndef->isGenerator, AKBASIC_ERR_STATE,
-		     "%s is a DEF, not a GEN -- FOR EACH/DO EACH needs a generator",
-		     fndef->name);
-
-    /*
-     * Self-recursion: walk the *parent* chain, not the pool. An environment
-     * reachable only through some other loop's `forGeneratorEnv` is a sibling
-     * invocation sitting detached between its own iterations, not an ancestor
-     * of this call -- nothing points from here to it via `parent`, so it never
-     * matches and independent or nested FOR EACH/DO EACH over the same GEN
-     * (even the same GEN with different arguments) is unaffected.
-     */
-    for ( walk = loopenv; walk != NULL; walk = walk->parent ) {
-	if ( walk->isGenerator && walk->generatorFn == (void *)fndef ) {
-	    FAIL_RETURN(errctx, AKBASIC_ERR_STATE,
-			"GEN %s cannot FOR EACH/DO EACH over itself from its own body",
-			fndef->name);
-	}
-    }
-
-    /*
-     * Evaluated in the caller's own scope, before anything is pushed -- the
-     * same reason akbasic_runtime_user_function() evaluates every argument
-     * before binding the first one: a later argument must not see an earlier
-     * one already sitting in the callee's scope.
-     */
-    fnarg = akbasic_leaf_first_argument(callexpr);
-    for ( ; fnarg != NULL; fnarg = fnarg->next ) {
-	FAIL_ZERO_RETURN(errctx, (nargs < AKBASIC_MAX_CALL_ARGUMENTS), AKBASIC_ERR_BOUNDS,
-			 "%s was called with more than %d arguments",
-			 callexpr->identifier, AKBASIC_MAX_CALL_ARGUMENTS);
-	PASS(errctx, akbasic_runtime_evaluate(obj, fnarg, &argvals[nargs]));
-	nargs += 1;
-    }
-
-    /*
-     * One environment for the whole lifetime of the loop, exactly as GOSUB and
-     * a function call take one from the pool -- and unlike either, this one
-     * survives past the verb that pushed it, held alive by `loopenv`'s own
-     * reference until NEXT/LOOP exhausts or EXIT abandons it.
-     */
-    PASS(errctx, akbasic_runtime_new_environment(obj));
-    callenv = obj->environment;
-    callenv->isGenerator = true;
-    callenv->generatorFn = (void *)fndef;
-    callenv->nextline = fndef->lineno;
-    loopenv->forGeneratorEnv = callenv;
-
-    paramleaf = (fndef->arglist != NULL ? fndef->arglist->right : NULL);
-    for ( i = 0; i < nargs && paramleaf != NULL; i++ ) {
-	PASS(errctx, akbasic_environment_assign(callenv, paramleaf, argvals[i], &unused));
-	paramleaf = paramleaf->next;
-    }
-
-    PASS(errctx, akbasic_runtime_pump_generator(obj, loopenv));
-    SUCCEED_RETURN(errctx);
-}
-
-akerr_ErrorContext *akbasic_cmd_gen(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
-{
-    PREPARE_ERROR(errctx);
-
-    (void)expr; (void)lval; (void)rval;
-    /* The parse handler already installed the generator, exactly as DEF's does. */
-    SUCCEED_TRUE(obj, dest);
-    SUCCEED_RETURN(errctx);
-}
-
-akerr_ErrorContext *akbasic_cmd_emit(akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest)
-{
-    PREPARE_ERROR(errctx);
-    akbasic_Environment *genenv = NULL;
-    akbasic_Environment *loopenv = NULL;
-    akbasic_Value *value = NULL;
-    int64_t zerosubscript[1] = { 0 };
-
-    (void)lval; (void)rval;
-    FAIL_ZERO_RETURN(errctx, (expr != NULL && expr->right != NULL), AKBASIC_ERR_SYNTAX,
-		     "Expected EMIT (expression)");
-    /*
-     * EMIT is not necessarily standing directly in the environment
-     * akbasic_runtime_generator_invoke() pushed: a GEN body is ordinary BASIC
-     * and may nest its own FOR, DO or GOSUB around an EMIT, each of which
-     * pushes an environment of its own -- exactly what the issue's own
-     * ROOMOBJECTS example does. Walk up to the nearest one that really is a
-     * GEN's own call frame.
-     */
-    for ( genenv = obj->environment; genenv != NULL && !genenv->isGenerator; genenv = genenv->parent ) {
-    }
-    FAIL_ZERO_RETURN(errctx, (genenv != NULL), AKBASIC_ERR_STATE,
-		     "EMIT outside the context of a GEN body");
-    loopenv = genenv->parent;
-    FAIL_ZERO_RETURN(errctx, (loopenv != NULL), AKBASIC_ERR_ENVIRONMENT,
-		     "EMIT from an orphaned environment");
-
-    PASS(errctx, akbasic_runtime_evaluate(obj, expr->right, &value));
-    /*
-     * Straight into the loop variable's storage, bypassing the arithmetic
-     * akbasic_environment_assign() and evaluate_for_condition() carry for a
-     * plain FOR: an EACH variable takes whatever type the GEN emits, string or
-     * structure element included, and there is no TO/STEP to compare it
-     * against.
-     */
-    PASS(errctx, akbasic_variable_set_subscript(loopenv->forNextVariable, value, zerosubscript, 1));
-    loopenv->nextline = loopenv->loopFirstLine;
-    /*
-     * The resume point, which may be several levels below `genenv` -- whatever
-     * nested FOR/DO/GOSUB environment this EMIT actually ran in. NEXT/LOOP
-     * reactivates exactly this one, so the nested structure picks up exactly
-     * where it left off rather than restarting at the top of the GEN body.
-     */
-    loopenv->forGeneratorEnv = obj->environment;
-    /*
-     * Not a pop, and not a single-level detach either: everything between here
-     * and `loopenv` -- `genenv` and any of its own descendants -- has to
-     * survive untouched to be resumed, so control moves to `loopenv` directly
-     * rather than walking the chain one release at a time.
-     */
-    obj->environment = loopenv;
-    SUCCEED_TRUE(obj, dest);
-    SUCCEED_RETURN(errctx);
-}
-
-akerr_ErrorContext *akbasic_cmd_end_gen(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;
-    /*
-     * A END GEN reached while skipping forward to one is the end of a GEN
-     * body's *definition*, not the end of a call -- the same distinction
-     * RETURN draws for DEF.
-     */
-    PASS(errctx, akbasic_environment_is_waiting_for(obj->environment, "END GEN", &waiting));
-    if ( waiting ) {
-	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "END GEN"));
-	SUCCEED_TRUE(obj, dest);
-	SUCCEED_RETURN(errctx);
-    }
-    FAIL_ZERO_RETURN(errctx, (obj->environment->isGenerator), AKBASIC_ERR_STATE,
-		     "END GEN outside the context of a generator invocation");
-    /*
-     * Real exhaustion: release this environment and detach in the same
-     * motion prev_environment() always does, then clear the parent's
-     * reference to it so a caller pumping this loop can tell "still alive"
-     * apart from "nothing left to resume".
-     */
-    PASS(errctx, akbasic_runtime_prev_environment(obj));
-    obj->environment->forGeneratorEnv = NULL;
-    SUCCEED_TRUE(obj, dest);
-    SUCCEED_RETURN(errctx);
-}

src/runtime_structure.c

@@ -80,31 +80,6 @@ akerr_ErrorContext *akbasic_cmd_do(akbasic_Runtime *obj, akbasic_ASTLeaf *expr,
     FAIL_ZERO_RETURN(errctx, obj->environment->isDoLoop, AKBASIC_ERR_STATE,
 		     "DO did not establish its own scope");
 
-    if ( obj->environment->isEachLoop ) {
-	akbasic_Environment *loopenv = obj->environment;
-	akbasic_ASTLeaf *var = (expr != NULL ? expr->right : NULL);
-
-	FAIL_ZERO_RETURN(errctx, (var != NULL && akbasic_leaf_is_identifier(var)),
-			 AKBASIC_ERR_SYNTAX, "Expected DO EACH (variable) IN (generator call)");
-	FAIL_ZERO_RETURN(errctx, (loopenv->forToLeaf != NULL), AKBASIC_ERR_STATE,
-			 "Expected DO EACH (variable) IN (generator call)");
-
-	PASS(errctx, akbasic_environment_get(loopenv, var->identifier, &loopenv->forNextVariable));
-	FAIL_ZERO_RETURN(errctx, (loopenv->forNextVariable != NULL), AKBASIC_ERR_UNDEFINED,
-			 "Unable to get loop variable %s", var->identifier);
-
-	PASS(errctx, akbasic_runtime_generator_invoke(obj, loopenv, loopenv->forToLeaf));
-	loopenv->forToLeaf = NULL;
-
-	if ( loopenv->forGeneratorEnv == NULL ) {
-	    /* The generator produced nothing: skip the body, same as DO WHILE
-	       false does. */
-	    PASS(errctx, akbasic_environment_wait_for_command(loopenv, "LOOP"));
-	}
-	SUCCEED_TRUE(obj, dest);
-	SUCCEED_RETURN(errctx);
-    }
-
     PASS(errctx, loop_continues(obj, obj->environment->doConditionLeaf,
 				obj->environment->doConditionKind, &enter));
     if ( !enter ) {
@@ -139,37 +114,7 @@ akerr_ErrorContext *akbasic_cmd_loop(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
     if ( obj->environment->exiting ) {
 	obj->environment->exiting = false;
 	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "LOOP"));
-	/* A live generator abandoned mid-run: release it too. */
-	if ( obj->environment->forGeneratorEnv != NULL ) {
-	    PASS(errctx, akbasic_runtime_release_generator(obj, obj->environment->forGeneratorEnv));
-	    obj->environment->forGeneratorEnv = NULL;
-	}
 	again = false;
-    } else if ( obj->environment->isEachLoop ) {
-	akbasic_Environment *loopenv = obj->environment;
-
-	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "LOOP"));
-	/*
-	 * A condition on the LOOP composes with EACH: it is checked after each
-	 * trip through the body, with the loop variable still holding that
-	 * trip's value, before the generator is pumped for the next one. A
-	 * condition that says stop abandons the generator exactly as EXIT does.
-	 */
-	again = true;
-	arg = (expr != NULL ? expr->right : NULL);
-	if ( arg != NULL ) {
-	    kind = (int)arg->literal_int;
-	    PASS(errctx, loop_continues(obj, arg->left, kind, &again));
-	}
-	if ( !again && loopenv->forGeneratorEnv != NULL ) {
-	    PASS(errctx, akbasic_runtime_release_generator(obj, loopenv->forGeneratorEnv));
-	    loopenv->forGeneratorEnv = NULL;
-	}
-	if ( again && loopenv->forGeneratorEnv != NULL ) {
-	    obj->environment = loopenv->forGeneratorEnv;
-	    PASS(errctx, akbasic_runtime_pump_generator(obj, loopenv));
-	}
-	again = (again && loopenv->forGeneratorEnv != NULL);
     } else {
 	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "LOOP"));
 	/*

src/scanner.c

@@ -48,7 +48,6 @@ static akerr_ErrorContext *is_at_end(akbasic_Runtime *obj, bool *dest)
 
 /**
  * @brief The character under the cursor.
- * @param obj The runtime whose scan cursor is being read.
  * @param[out] dest The character. Untouched when there is none.
  * @param[out] got  Whether there was one. The old `bool` return.
  */
@@ -71,7 +70,6 @@ static akerr_ErrorContext *peek(akbasic_Runtime *obj, char *dest, bool *got)
 
 /**
  * @brief The character one past the cursor.
- * @param obj The runtime whose scan cursor is being read.
  * @param[out] dest The character. Untouched when there is none.
  * @param[out] got  Whether there was one. The old `bool` return.
  */
@@ -147,10 +145,6 @@ static akerr_ErrorContext *add_token(akbasic_Runtime *obj, akbasic_TokenType tok
 
 /**
  * @brief Consume one more character when it matches, choosing between two token types.
- * @param obj The runtime whose scan cursor is being advanced.
- * @param cm The character that must be next for the match to succeed.
- * @param truetype The token type to report when @p cm matches.
- * @param falsetype The token type to report when it does not.
  * @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.

src/sprite_akgl.c

@@ -875,7 +875,7 @@ static akerr_ErrorContext AKERR_NOIGNORE *run_scan(akbasic_AkglSprites *state)
  * proxy carries the owner only so a resolver can push something. Nothing here
  * resolves anything, so the field stays empty and the shape is what matters.
  *
- * Layers are the other half. A wall sits on `AKGL_COLLISION_LAYER_STATIC` and
+ * Layers are the other half. A wall sits on #AKGL_COLLISION_LAYER_STATIC and
  * responds to nothing, which is the asymmetry libakgl's masks exist for: the
  * sprite's own `collidemask` includes STATIC, so a sprite finds a wall and two
  * walls never test against each other. Sixty-four motionless rectangles

src/verbs.c

@@ -37,7 +37,6 @@ static const akbasic_Verb VERBS[] = {
     { "ABS",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_abs },
     { "AND",          AKBASIC_TOK_AND,                  -1, NULL,                  NULL },
     { "APPEND",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_append },
-    { "ASC",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_asc },
     { "ATN",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_atn },
     { "AUTO",         AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_auto },
     { "BACKUP",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_optional_arglist, akbasic_cmd_backup },
@@ -74,32 +73,14 @@ static const akbasic_Verb VERBS[] = {
     { "DRAW",         AKBASIC_TOK_COMMAND,              -1, akbasic_parse_draw,    akbasic_cmd_draw },
     { "DSAVE",        AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, NULL,                  akbasic_cmd_dsave },
     { "DVERIFY",      AKBASIC_TOK_COMMAND_IMMEDIATE,    -1, akbasic_parse_arglist, akbasic_cmd_dverify },
-    /*
-     * EACH is never dispatched on its own -- akbasic_parse_for() and
-     * akbasic_parse_do() consume it directly, the same way TO, STEP, WHILE and
-     * UNTIL are. It exists here only so the scanner gives it a COMMAND token
-     * rather than letting it scan as a plain identifier.
-     */
-    { "EACH",         AKBASIC_TOK_COMMAND,              -1, NULL,                  NULL },
     { "ELSE",         AKBASIC_TOK_COMMAND,              -1, NULL,                  NULL },
-    { "EMIT",         AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_emit },
-    { "END",          AKBASIC_TOK_COMMAND,              -1, akbasic_parse_end,     akbasic_cmd_end },
-    /*
-     * `END GEN` is never scanned as one token -- END and GEN are ordinary
-     * COMMAND tokens on the same line -- so this row is reached only from
-     * akbasic_parse_end(), which builds a leaf carrying this exact name after
-     * it sees GEN follow END. It still has to be here, and in order, because
-     * dispatch is a bsearch on the leaf's name; the same reason INPUT# and
-     * PRINT# are.
-     */
-    { "END GEN",      AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_end_gen },
+    { "END",          AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_end },
     { "ENVELOPE",     AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_envelope },
     { "ERR",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_err },
     { "EXIT",         AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_exit },
     { "FETCH",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_fetch },
     { "FILTER",       AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_filter },
     { "FOR",          AKBASIC_TOK_COMMAND,              -1, akbasic_parse_for,     akbasic_cmd_for },
-    { "GEN",          AKBASIC_TOK_COMMAND,              -1, akbasic_parse_gen,     akbasic_cmd_gen },
     { "GET",          AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_get },
     { "GETKEY",       AKBASIC_TOK_COMMAND,              -1, NULL,                  akbasic_cmd_getkey },
     { "GETMENU",      AKBASIC_TOK_COMMAND,              -1, akbasic_parse_arglist, akbasic_cmd_getmenu },
@@ -112,9 +93,6 @@ static const akbasic_Verb VERBS[] = {
     { "HEX",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_hex },
     { "HUD",          AKBASIC_TOK_COMMAND,              -1, akbasic_parse_optional_arglist, akbasic_cmd_hud },
     { "IF",           AKBASIC_TOK_COMMAND,              -1, akbasic_parse_if,      akbasic_cmd_if },
-    /* IN is consumed directly by akbasic_parse_for()/akbasic_parse_do()'s EACH
-       clause, the same way EACH itself is. */
-    { "IN",           AKBASIC_TOK_COMMAND,              -1, NULL,                  NULL },
     { "INPUT",        AKBASIC_TOK_COMMAND,              -1, akbasic_parse_input,   akbasic_cmd_input },
     /*
      * `INPUT#` and `PRINT#` are never scanned as verb names -- the scanner reads
@@ -168,7 +146,6 @@ static const akbasic_Verb VERBS[] = {
     { "RGR",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_rgr },
     { "RIGHT",        AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_right },
     { "RMENU",        AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_rmenu },
-    { "RND",          AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_rnd },
     { "RSPCOLOR",     AKBASIC_TOK_FUNCTION,              1, NULL,                  akbasic_fn_rspcolor },
     { "RSPHIT",       AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_rsphit },
     { "RSPPOS",       AKBASIC_TOK_FUNCTION,              2, NULL,                  akbasic_fn_rsppos },

src/verbs.h

@@ -20,8 +20,6 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_data(struct akbasic_Parser *par
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_graphic(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_draw(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_def(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_gen(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_end(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_dim(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_for(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_parse_if(struct akbasic_Parser *parser, akbasic_ASTLeaf **dest);
@@ -113,11 +111,6 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_swap(struct akbasic_Runtime *obj,
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_troff(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_tron(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 
-/* Group L generator verbs -- src/runtime_generator.c */
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_gen(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_emit(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_end_gen(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
-
 /* Verb handlers -- src/runtime_commands.c */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_auto(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_data(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
@@ -147,7 +140,6 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_cmd_stop(struct akbasic_Runtime *obj,
 
 /* Function handlers -- src/runtime_functions.c */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_abs(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_asc(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_atn(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_chr(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_cos(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
@@ -162,7 +154,6 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_peek(struct akbasic_Runtime *obj,
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_pointer(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_pointervar(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_rad(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
-akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_rnd(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_right(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_sgn(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_fn_shl(struct akbasic_Runtime *obj, akbasic_ASTLeaf *expr, akbasic_Value *lval, akbasic_Value *rval, akbasic_Value **dest);

tests/disk_verbs.c

@@ -244,16 +244,10 @@ static void test_no_drive_verbs(void)
 	harness_stop();
     }
 
-    /*
-     * DIRECTORY is refused for a different reason than the five above: not for
-     * want of a drive, but because it is unwritten. It used to name the missing
-     * libakstdlib wrapper; that wrapper landed, so naming it would be a lie.
-     */
+    /* DIRECTORY is refused for a different reason, and says which. */
     TEST_REQUIRE_OK(run_program("10 DIRECTORY\n"));
-    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "not implemented") != NULL,
-		 "DIRECTORY should say it is unwritten, got \"%s\"", HARNESS_OUTPUT);
-    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "libakstdlib") == NULL,
-		 "DIRECTORY must not still blame libakstdlib, got \"%s\"", HARNESS_OUTPUT);
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "libakstdlib") != NULL,
+		 "DIRECTORY should name the missing wrapper, got \"%s\"", HARNESS_OUTPUT);
     harness_stop();
 }
 

tests/for_semantics.c

@@ -81,7 +81,7 @@ static void test_counter_survives_the_loop(void)
  * `FOR I = 1 TO 1` executes the body one time on every BASIC there has ever
  * been. Here the entry test treats "the counter has reached the limit" as
  * "do not enter", so the body is skipped entirely -- and
- * tests/language/flowcontrol/forloopwaitingforcommand.bas pins that,
+ * tests/reference/language/flowcontrol/forloopwaitingforcommand.bas pins that,
  * which is why this cannot simply be corrected.
  */
 static void test_single_iteration_loop(void)

tests/generators.c

@@ -1,360 +0,0 @@
-/**
- * @file generators.c
- * @brief Generators: GEN/EMIT/END GEN and the FOR EACH/DO EACH loops over them.
- *
- * The golden corpus (tests/language/flowcontrol/generators_*.bas) covers the
- * ordinary shapes: the issue's own ROOMOBJECTS example in both loop forms, an
- * empty generator, a non-numeric EMIT and nested/interleaved invocations. This
- * file covers what a byte-compared program cannot: that abandoning a
- * generator with EXIT gives its environment back to the pool rather than
- * leaking it, and that misusing a GEN fails cleanly rather than corrupting the
- * environment stack.
- */
-
-#include <string.h>
-
-#include <akbasic/error.h>
-#include <akbasic/runtime.h>
-
-#include "harness.h"
-#include "testutil.h"
-
-/** @brief Run a program to completion under an explicit step budget. */
-static akerr_ErrorContext AKERR_NOIGNORE *run_program_bounded(const char *source, int64_t steps)
-{
-    PREPARE_ERROR(errctx);
-
-    PASS(errctx, harness_start(NULL));
-    PASS(errctx, akbasic_runtime_load(&HARNESS_RUNTIME, source));
-    PASS(errctx, akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
-    PASS(errctx, akbasic_runtime_run(&HARNESS_RUNTIME, steps));
-    SUCCEED_RETURN(errctx);
-}
-
-/** @brief Run a program to completion, bounded so a hang fails rather than waits. */
-static akerr_ErrorContext AKERR_NOIGNORE *run_program(const char *source)
-{
-    PREPARE_ERROR(errctx);
-
-    PASS(errctx, run_program_bounded(source, 20000));
-    SUCCEED_RETURN(errctx);
-}
-
-/** @brief The issue's own example, as a sanity check independent of the golden corpus. */
-static void test_room_objects_smoke(void)
-{
-    TEST_REQUIRE_OK(run_program("10 DIM OBJ#(3)\n"
-				"20 OBJ#(0) = 100\n"
-				"30 OBJ#(1) = 200\n"
-				"40 OBJ#(2) = 300\n"
-				"50 GEN ROOMOBJECTS(R#)\n"
-				"60   FOR I# = 0 TO 2\n"
-				"70     IF I# <> 1 THEN EMIT OBJ#(I#)\n"
-				"80   NEXT I#\n"
-				"90 END GEN\n"
-				"100 FOR EACH O# IN ROOMOBJECTS(0)\n"
-				"110   PRINT O#\n"
-				"120 NEXT O#\n"));
-    TEST_REQUIRE_STR(HARNESS_OUTPUT, "100\n300\n");
-    harness_stop();
-}
-
-/**
- * @brief EXIT out of a FOR EACH loop releases its generator, not just the loop.
- *
- * Run more FOR EACH/EXIT constructs than AKBASIC_MAX_ENVIRONMENTS -- each one
- * takes two environments (the loop's own and the generator's) -- in a single
- * program. If EXIT abandoned the generator environment instead of releasing
- * it, this exhausts the pool partway through and the run reports "Environment
- * pool exhausted" instead of finishing.
- */
-static void test_exit_releases_generator_for_each(void)
-{
-    TEST_REQUIRE_OK(run_program("10 GEN ONE(X#)\n"
-				"20   EMIT 1\n"
-				"30 END GEN\n"
-				"40 FOR K# = 1 TO 13\n"
-				"50   FOR EACH V# IN ONE(0)\n"
-				"60     EXIT\n"
-				"70   NEXT V#\n"
-				"80 NEXT K#\n"
-				"90 PRINT \"DONE\"\n"));
-    TEST_REQUIRE_STR(HARNESS_OUTPUT, "DONE\n");
-    harness_stop();
-}
-
-/** @brief The same leak check for DO EACH/EXIT. */
-static void test_exit_releases_generator_do_each(void)
-{
-    TEST_REQUIRE_OK(run_program("10 GEN ONE(X#)\n"
-				"20   EMIT 1\n"
-				"30 END GEN\n"
-				"40 FOR K# = 1 TO 13\n"
-				"50   DO EACH V# IN ONE(0)\n"
-				"60     EXIT\n"
-				"70   LOOP\n"
-				"80 NEXT K#\n"
-				"90 PRINT \"DONE\"\n"));
-    TEST_REQUIRE_STR(HARNESS_OUTPUT, "DONE\n");
-    harness_stop();
-}
-
-/**
- * @brief EXIT partway through, with more of the generator left to run, still
- * frees the environment for the next construct that needs one.
- */
-static void test_exit_partway_through(void)
-{
-    TEST_REQUIRE_OK(run_program("10 GEN COUNTUP(N#)\n"
-				"20   FOR I# = 1 TO N#\n"
-				"30     EMIT I#\n"
-				"40   NEXT I#\n"
-				"50 END GEN\n"
-				"60 FOR EACH V# IN COUNTUP(10)\n"
-				"70   PRINT V#\n"
-				"80   IF V# = 2 THEN EXIT\n"
-				"90 NEXT V#\n"
-				"100 PRINT \"AFTER\"\n"));
-    TEST_REQUIRE_STR(HARNESS_OUTPUT, "1\n2\nAFTER\n");
-    harness_stop();
-}
-
-/**
- * @brief Abandoning a generator that is itself suspended inside a FOR EACH
- * over another generator releases the inner generator too.
- *
- * The inner generator's environment hangs off the *loop* scope inside OUTER's
- * body as a child, off the parent chain -- the one place a bare parent walk
- * never looks. Before akbasic_runtime_release_generator() recursed into
- * `forGeneratorEnv`, every trip through this loop stranded one pool slot and
- * the 13th trip died with "Environment pool exhausted".
- */
-static void test_exit_releases_nested_generators(void)
-{
-    TEST_REQUIRE_OK(run_program("10 GEN INNER(N#)\n"
-				"20   EMIT 1\n"
-				"30   EMIT 2\n"
-				"40 END GEN\n"
-				"50 GEN OUTER(N#)\n"
-				"60   FOR EACH I# IN INNER(0)\n"
-				"70     EMIT I#\n"
-				"80   NEXT I#\n"
-				"90 END GEN\n"
-				"100 FOR K# = 1 TO 40\n"
-				"110   FOR EACH V# IN OUTER(0)\n"
-				"120     EXIT\n"
-				"130   NEXT V#\n"
-				"140 NEXT K#\n"
-				"150 PRINT \"DONE\"\n"));
-    TEST_REQUIRE_STR(HARNESS_OUTPUT, "DONE\n");
-    harness_stop();
-}
-
-/**
- * @brief A LOOP UNTIL that stops a DO EACH early releases the generator it
- * abandons, every time.
- */
-static void test_loop_condition_releases_generator(void)
-{
-    TEST_REQUIRE_OK(run_program("10 GEN COUNTUP(N#)\n"
-				"20   FOR I# = 1 TO N#\n"
-				"30     EMIT I#\n"
-				"40   NEXT I#\n"
-				"50 END GEN\n"
-				"60 FOR K# = 1 TO 40\n"
-				"70   DO EACH V# IN COUNTUP(10)\n"
-				"80   LOOP UNTIL V# = 2\n"
-				"90 NEXT K#\n"
-				"100 PRINT \"DONE\"\n"));
-    TEST_REQUIRE_STR(HARNESS_OUTPUT, "DONE\n");
-    harness_stop();
-}
-
-/**
- * @brief RETURN standing in a GEN's own frame ends the generator early,
- * exactly as END GEN would -- a GEN is a function at heart.
- */
-static void test_return_ends_generator(void)
-{
-    TEST_REQUIRE_OK(run_program("10 GEN G(N#)\n"
-				"20   EMIT 1\n"
-				"30   RETURN\n"
-				"40   EMIT 2\n"
-				"50 END GEN\n"
-				"60 FOR EACH V# IN G(0)\n"
-				"70   PRINT V#\n"
-				"80 NEXT V#\n"
-				"90 PRINT \"DONE\"\n"));
-    TEST_REQUIRE_STR(HARNESS_OUTPUT, "1\nDONE\n");
-    harness_stop();
-}
-
-/**
- * @brief RETURN with a value inside a GEN is refused: values leave a GEN one
- * at a time, through EMIT, and there is no return slot waiting.
- */
-static void test_return_value_in_generator_refused(void)
-{
-    TEST_REQUIRE_OK(run_program_bounded("10 GEN G(N#)\n"
-					"20   EMIT 1\n"
-					"30   RETURN 99\n"
-					"40 END GEN\n"
-					"50 FOR EACH V# IN G(0)\n"
-					"60   PRINT V#\n"
-					"70 NEXT V#\n"
-					"80 PRINT \"UNREACHABLE\"\n", 2000));
-    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "1\n") != NULL,
-		 "expected the first EMIT in \"%s\"", HARNESS_OUTPUT);
-    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "UNREACHABLE") == NULL,
-		 "RETURN with a value must stop the run, got \"%s\"", HARNESS_OUTPUT);
-    harness_stop();
-}
-
-/**
- * @brief The unwind primitive releases a popped scope's suspended generator.
- *
- * Built by hand rather than through BASIC because the paths that need this --
- * the error unwinds in pump_generator() and call_function() -- only trigger
- * on C-level failures a program cannot politely ask for. The shape is the
- * one EMIT leaves behind: a loop scope holding a detached generator child,
- * with a further scope active above it.
- */
-static void test_unwind_releases_suspended_generators(void)
-{
-    akbasic_Environment *root = NULL;
-    akbasic_Environment *loopenv = NULL;
-    akbasic_Environment *genenv = NULL;
-    akbasic_Environment *forenv = NULL;
-
-    TEST_REQUIRE_OK(harness_start(NULL));
-    root = HARNESS_RUNTIME.environment;
-
-    TEST_REQUIRE_OK(akbasic_runtime_new_environment(&HARNESS_RUNTIME));
-    loopenv = HARNESS_RUNTIME.environment;
-    loopenv->isEachLoop = true;
-
-    TEST_REQUIRE_OK(akbasic_runtime_new_environment(&HARNESS_RUNTIME));
-    genenv = HARNESS_RUNTIME.environment;
-    genenv->isGenerator = true;
-    TEST_REQUIRE_OK(akbasic_runtime_detach_environment(&HARNESS_RUNTIME));
-    loopenv->forGeneratorEnv = genenv;
-
-    TEST_REQUIRE_OK(akbasic_runtime_new_environment(&HARNESS_RUNTIME));
-    forenv = HARNESS_RUNTIME.environment;
-
-    TEST_REQUIRE_OK(akbasic_runtime_unwind_to_environment(&HARNESS_RUNTIME, root));
-    TEST_REQUIRE(HARNESS_RUNTIME.environment == root,
-		 "unwind must land on the target scope");
-    TEST_REQUIRE(!forenv->used && !loopenv->used && !genenv->used,
-		 "unwind must release the chain and the suspended generator");
-    harness_stop();
-}
-
-/**
- * @brief A GEN invoked like an ordinary function, rather than through FOR
- * EACH/DO EACH, fails cleanly.
- *
- * EMIT requires `isGenerator`, which only a FOR EACH/DO EACH invocation sets
- * -- an ordinary call pushes a plain environment, exactly as a DEF's does --
- * so the first EMIT the call reaches is where this is refused.
- */
-static void test_called_like_a_function(void)
-{
-    akbasic_Value *args[1];
-    akbasic_Value argvalue;
-    akbasic_Value *out = NULL;
-
-    TEST_REQUIRE_OK(harness_start(NULL));
-    TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME,
-					 "10 GEN ONE(N#)\n"
-					 "20   EMIT N#\n"
-					 "30 END GEN\n"));
-    TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
-    TEST_REQUIRE_OK(akbasic_runtime_run(&HARNESS_RUNTIME, 100));
-
-    TEST_REQUIRE_OK(akbasic_value_zero(&argvalue));
-    argvalue.valuetype = AKBASIC_TYPE_INTEGER;
-    argvalue.intval = 5;
-    args[0] = &argvalue;
-    TEST_REQUIRE_ANY_ERROR(akbasic_runtime_call_function(&HARNESS_RUNTIME, "ONE", args, 1, &out));
-    harness_stop();
-}
-
-/** @brief EMIT reached with no enclosing GEN invocation is refused. */
-static void test_emit_outside_gen(void)
-{
-    akbasic_ASTLeaf *leaf = NULL;
-    akbasic_Value *out = NULL;
-
-    TEST_REQUIRE_OK(harness_start(NULL));
-    TEST_REQUIRE_OK(akbasic_environment_zero(HARNESS_RUNTIME.environment));
-    TEST_REQUIRE_OK(harness_parse("EMIT 5", &leaf));
-    TEST_REQUIRE_ANY_ERROR(akbasic_runtime_evaluate(&HARNESS_RUNTIME, leaf, &out));
-    harness_stop();
-}
-
-/**
- * @brief A GEN invoking itself, directly, is refused rather than recursing.
- *
- * Bounded tightly: a program that recursed forever would hang the whole
- * suite, and this is exactly the case that must not.
- */
-static void test_self_recursion_refused(void)
-{
-    TEST_REQUIRE_OK(run_program_bounded("10 GEN RECURSIVE(N#)\n"
-					"20   FOR EACH X# IN RECURSIVE(N# + 1)\n"
-					"30     EMIT X#\n"
-					"40   NEXT X#\n"
-					"50 END GEN\n"
-					"60 PRINT \"BEFORE\"\n"
-					"70 FOR EACH R# IN RECURSIVE(1)\n"
-					"80   PRINT R#\n"
-					"90 NEXT R#\n"
-					"100 PRINT \"UNREACHABLE\"\n", 2000));
-    /* Whatever else happened, the line before the recursive call ran and the
-       one two lines after invoking it -- which would only print after the
-       loop completed successfully -- did not. */
-    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "BEFORE\n") != NULL,
-		 "expected \"BEFORE\" in \"%s\"", HARNESS_OUTPUT);
-    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "UNREACHABLE") == NULL,
-		 "self-recursion must not reach \"UNREACHABLE\", got \"%s\"", HARNESS_OUTPUT);
-    harness_stop();
-}
-
-/**
- * @brief Independent (sibling) FOR EACH invocations of the same GEN are not
- * self-recursion, even nested.
- */
-static void test_sibling_invocations_allowed(void)
-{
-    TEST_REQUIRE_OK(run_program("10 GEN COUNTUP(N#)\n"
-				"20   FOR I# = 1 TO N#\n"
-				"30     EMIT I#\n"
-				"40   NEXT I#\n"
-				"50 END GEN\n"
-				"60 FOR EACH A# IN COUNTUP(2)\n"
-				"70   FOR EACH B# IN COUNTUP(2)\n"
-				"80     PRINT A# * 10 + B#\n"
-				"90   NEXT B#\n"
-				"100 NEXT A#\n"));
-    TEST_REQUIRE_STR(HARNESS_OUTPUT, "11\n12\n21\n22\n");
-    harness_stop();
-}
-
-int main(void)
-{
-    test_room_objects_smoke();
-    test_exit_releases_generator_for_each();
-    test_exit_releases_generator_do_each();
-    test_exit_partway_through();
-    test_exit_releases_nested_generators();
-    test_loop_condition_releases_generator();
-    test_return_ends_generator();
-    test_return_value_in_generator_refused();
-    test_unwind_releases_suspended_generators();
-    test_called_like_a_function();
-    test_emit_outside_gen();
-    test_self_recursion_refused();
-    test_sibling_invocations_allowed();
-    return akbasic_test_failures;
-}

tests/language/README.md

@@ -1,16 +0,0 @@
-# The language test corpus
-
-The `.bas` files in this directory and their sibling `.txt` files are the editable language
-corpus. CMake registers every program as an individual `local_*` CTest case and compares its
-output with the sibling expectation.
-
-The corpus includes cases carried over from the deprecated Go implementation as well as cases
-written for this interpreter. Their provenance is useful when investigating a regression, but it
-does not make any case immutable or turn the old implementation into a specification.
-
-**Change a program and its expectation deliberately and in the same commit.** If the changed
-output represents an intentional language decision, record the reason in `TODO.md` or the
-relevant documentation. If it is an accidental change, fix the interpreter instead.
-
-The `examples/` subdirectory contains complete BASIC programs used as worked examples. It is
-part of the same corpus and follows the same `.bas`/`.txt` pairing rule.

tests/language/arrays_in_parameter_lists.bas

@@ -1,6 +1,6 @@
 10 REM An array reference used as a function argument, and as one of several.
 20 REM An identifier's subscript list used to hang off .right, which is also
-30 REM where arguments chain their arguments -- so the arity counter walked
+30 REM where an argument list chains its arguments -- so the arity counter walked
 40 REM straight into the subscripts and refused the call. TODO.md section 4.
 50 DIM C#(4)
 60 C#(1) = -9

tests/language/audio/filter_refused.bas

@@ -1,6 +1,6 @@
-10 REM FILTER has no device capability -- audio synthesises and mixes but
-20 REM has no filter stage; SDL3 supplies no primitive to build one from. It
-30 REM is refused rather than silently ignored, so a program that asked
+10 REM FILTER has no device capability behind it -- akgl_audio_* synthesises and
+20 REM mixes but has no filter stage, and SDL3 supplies no primitive to build one
+30 REM from. It is refused rather than silently ignored, so a program that asked
 40 REM for a low-pass finds out it did not get one.
 50 PRINT "BEFORE"
 60 FILTER 1000, 1, 0, 0, 5

tests/language/audio/no_device.bas

@@ -1,4 +1,4 @@
-10 REM The standalone driver has no audio device. ENVELOPE, VOL and
+10 REM The standalone driver lends the script no audio device. ENVELOPE, VOL and
 20 REM TEMPO only change interpreter state, so they work regardless; SOUND and
 30 REM PLAY need the device and must name themselves when there is none.
 40 ENVELOPE 1, 5, 9, 12, 2

tests/language/flowcontrol/generators_call_as_function.bas

@@ -1,6 +0,0 @@
-10 REM A GEN invoked like an ordinary function is refused, not silently run.
-20 GEN ONE(N#)
-30     EMIT N#
-40 END GEN
-50 X# = ONE(5)
-60 PRINT "UNREACHABLE"

tests/language/flowcontrol/generators_call_as_function.txt

@@ -1,2 +0,0 @@
-? 50 : RUNTIME ERROR ONE is a GEN; call it with FOR EACH or DO EACH, not as a function
-

tests/language/flowcontrol/generators_do_condition_misplaced.bas

@@ -1,8 +0,0 @@
-10 REM A DO EACH takes its condition on the LOOP, not on the DO line.
-20 GEN ONE(N#)
-30     EMIT N#
-40 END GEN
-50 DO EACH V# IN ONE(1) WHILE V# < 9
-60     PRINT V#
-70 LOOP
-80 PRINT "UNREACHABLE"

tests/language/flowcontrol/generators_do_condition_misplaced.txt

@@ -1,2 +0,0 @@
-? 50 : PARSE ERROR DO EACH takes its WHILE/UNTIL on the LOOP, and nothing else here
-

tests/language/flowcontrol/generators_doeach.bas

@@ -1,14 +0,0 @@
-10 REM Same generator as generators_foreach.bas, via DO EACH ... LOOP.
-20 DIM OBJ#(3)
-30 OBJ#(0) = 100
-40 OBJ#(1) = 200
-50 OBJ#(2) = 300
-60 GEN ROOMOBJECTS(R#)
-70     FOR I# = 0 TO 2
-80         IF I# <> 1 THEN EMIT OBJ#(I#)
-90     NEXT I#
-100 END GEN
-110 DO EACH O# IN ROOMOBJECTS(0)
-120     PRINT O#
-130 LOOP
-140 PRINT "DONE"

tests/language/flowcontrol/generators_doeach.txt

@@ -1,3 +0,0 @@
-100
-300
-DONE

tests/language/flowcontrol/generators_emit_outside.bas

@@ -1,3 +0,0 @@
-10 REM EMIT outside any GEN invocation is refused cleanly.
-20 EMIT 5
-30 PRINT "UNREACHABLE"

tests/language/flowcontrol/generators_emit_outside.txt

@@ -1,2 +0,0 @@
-? 20 : RUNTIME ERROR EMIT outside the context of a GEN body
-

tests/language/flowcontrol/generators_empty.bas

@@ -1,11 +0,0 @@
-10 REM A GEN with no EMIT at all runs its FOR EACH/DO EACH body zero times.
-20 GEN NOTHING(N#)
-30 END GEN
-40 FOR EACH X# IN NOTHING(0)
-50     PRINT "NEVER FOR"
-60 NEXT X#
-70 PRINT "AFTER FOR"
-80 DO EACH Y# IN NOTHING(0)
-90     PRINT "NEVER DO"
-100 LOOP
-110 PRINT "AFTER DO"

tests/language/flowcontrol/generators_empty.txt

@@ -1,2 +0,0 @@
-AFTER FOR
-AFTER DO

tests/language/flowcontrol/generators_foreach.bas

@@ -1,15 +0,0 @@
-10 REM The GEN/FOR EACH example from issue #57, with real arrays standing in
-20 REM for OBJCOUNT%/VISIBLE/OBJ%.
-30 DIM OBJ#(3)
-40 OBJ#(0) = 100
-50 OBJ#(1) = 200
-60 OBJ#(2) = 300
-70 GEN ROOMOBJECTS(R#)
-80     FOR I# = 0 TO 2
-90         IF I# <> 1 THEN EMIT OBJ#(I#)
-100     NEXT I#
-110 END GEN
-120 FOR EACH O# IN ROOMOBJECTS(0)
-130     PRINT O#
-140 NEXT O#
-150 PRINT "DONE"

tests/language/flowcontrol/generators_foreach.txt

@@ -1,3 +0,0 @@
-100
-300
-DONE

tests/language/flowcontrol/generators_loop_condition.bas

@@ -1,15 +0,0 @@
-10 REM A WHILE or UNTIL on the LOOP composes with DO EACH: it is checked
-20 REM after each trip through the body, with the loop variable still
-30 REM holding that trip's value. Stopping abandons the generator cleanly.
-40 GEN COUNTUP(N#)
-50     FOR I# = 1 TO N#
-60         EMIT I#
-70     NEXT I#
-80 END GEN
-90 DO EACH V# IN COUNTUP(10)
-100     PRINT V#
-110 LOOP UNTIL V# = 3
-120 DO EACH W# IN COUNTUP(4)
-130     PRINT W# * 10
-140 LOOP WHILE W# < 3
-150 PRINT "DONE"

tests/language/flowcontrol/generators_loop_condition.txt

@@ -1,7 +0,0 @@
-1
-2
-3
-10
-20
-30
-DONE

tests/language/flowcontrol/generators_mismatched_next.bas

@@ -1,10 +0,0 @@
-10 REM A stray NEXT with nothing open behaves like the plain-FOR case: the
-20 REM FOR EACH's own NEXT closes it cleanly, and a second one errors.
-30 GEN ONE(N#)
-40     EMIT N#
-50 END GEN
-60 FOR EACH O# IN ONE(1)
-70     PRINT O#
-80 NEXT O#
-90 NEXT O#
-100 PRINT "UNREACHABLE"

tests/language/flowcontrol/generators_mismatched_next.txt

@@ -1,3 +0,0 @@
-1
-? 90 : RUNTIME ERROR NEXT outside the context of FOR
-

tests/language/flowcontrol/generators_nested.bas

@@ -1,22 +0,0 @@
-10 REM Nested FOR EACH/DO EACH over the same GEN with different arguments,
-20 REM in every combination of the two loop shapes.
-30 GEN COUNTUP(N#)
-40     FOR I# = 1 TO N#
-50         EMIT I#
-60     NEXT I#
-70 END GEN
-80 FOR EACH A# IN COUNTUP(2)
-90     FOR EACH B# IN COUNTUP(3)
-100         PRINT A# * 10 + B#
-110     NEXT B#
-120 NEXT A#
-130 DO EACH C# IN COUNTUP(2)
-140     DO EACH D# IN COUNTUP(2)
-150         PRINT C# * 100 + D#
-160     LOOP
-170 LOOP
-180 FOR EACH E# IN COUNTUP(2)
-190     DO EACH F# IN COUNTUP(2)
-200         PRINT E# * 1000 + F#
-210     LOOP
-220 NEXT E#

tests/language/flowcontrol/generators_nested.txt

@@ -1,14 +0,0 @@
-11
-12
-13
-21
-22
-23
-101
-102
-201
-202
-1001
-1002
-2001
-2002

tests/language/flowcontrol/generators_return.bas

@@ -1,15 +0,0 @@
-10 REM RETURN ends a GEN early, exactly as END GEN would: a GEN is a
-20 REM function at heart, and only EMIT is different about it. Like a
-30 REM GOSUB's or DEF's RETURN, it must stand in the GEN's own scope,
-40 REM not inside a FOR or DO the body opened.
-50 GEN FIRSTFEW(N#)
-60     EMIT 1
-70     IF N# < 2 THEN RETURN
-80     EMIT 2
-90     IF N# < 3 THEN RETURN
-100     EMIT 3
-110 END GEN
-120 FOR EACH V# IN FIRSTFEW(2)
-130     PRINT V#
-140 NEXT V#
-150 PRINT "DONE"

tests/language/flowcontrol/generators_return.txt

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

tests/language/flowcontrol/generators_string.bas

@@ -1,11 +0,0 @@
-10 REM FOR EACH/DO EACH accept any emitted type, not just numeric.
-20 GEN WORDS(N#)
-30     EMIT "HELLO"
-40     EMIT "WORLD"
-50 END GEN
-60 FOR EACH W$ IN WORDS(0)
-70     PRINT W$
-80 NEXT W$
-90 DO EACH V$ IN WORDS(0)
-100     PRINT V$
-110 LOOP

tests/language/flowcontrol/generators_string.txt

@@ -1,4 +0,0 @@
-HELLO
-WORLD
-HELLO
-WORLD

tests/language/functions/asc.bas

@@ -1,3 +0,0 @@
-10 PRINT "97 : " + ASC("a")
-20 PRINT "65 : " + ASC("A")
-30 PRINT "64 : " + ASC("@")

tests/language/functions/asc.txt

@@ -1,3 +0,0 @@
-97 : 97
-65 : 65
-64 : 64

tests/language/functions/recursion.bas

@@ -1,6 +1,6 @@
-10 REM A DEF call takes an environment from the pool, one per call, exactly as
+10 REM A DEF call takes its environment from the pool, one per call, exactly as
 20 REM GOSUB does. It used to be owned by the funcdef and reset on every call,
-30 REM which cost two silent defects: two calls shared a slot,
+30 REM which cost two silent defects: two calls in one expression shared a slot,
 40 REM and recursion never came back at all.
 50 DEF FACT(N#)
 60 IF N# <= 1 THEN RETURN 1
@@ -15,9 +15,9 @@
 150 DEF DBL(N#) = N# * 2
 160 PRINT DBL(10) + DBL(1)
 170 PRINT DBL(1) + DBL(10) + DBL(100)
-180 REM Depth answers to the pool, so runaway recursion reports
-190 REM "Environment pool exhausted" rather than hanging. It is not exercised
-200 REM here because a failed call's statement still prints a junk value
-210 REM afterwards -- a TODO.md defect this file would pin
-220 REM if it went in. tests/user_functions.c asserts
+180 REM Depth answers to the environment pool now, so runaway recursion reports
+190 REM "Environment pool exhausted" rather than hanging. It is not exercised here
+200 REM because the statement containing a failed call still prints a junk value
+210 REM afterwards -- a separate, pre-existing defect recorded in TODO.md, and one
+220 REM this golden file would pin if it went in. tests/user_functions.c asserts
 230 REM the message instead.

tests/language/graphics/argument_errors.bas

@@ -1,4 +1,4 @@
-10 REM A range check reported through the driver. The program stops
+10 REM A range check reported through the driver, end to end. The program stops
 20 REM at the first error, so this file covers one; the rest of the checks are
 30 REM asserted in tests/graphics_verbs.c against the recording backend.
 40 PRINT "BEFORE"

tests/language/graphics/no_device.bas

@@ -1,5 +1,5 @@
 10 REM The standalone driver lends the script no graphics device.
-20 REM COLOR, LOCATE and SCALE touch interpreter state and must still work.
+20 REM COLOR, LOCATE and SCALE only touch interpreter state and must still work.
 30 COLOR 1, 3
 40 LOCATE 40, 50
 50 SCALE 1, 640, 400

tests/language/housekeeping/verbs.bas

@@ -1,5 +1,5 @@
-10 REM Group B: housekeeping verbs. None is in the Go reference --
-20 REM they are on its unimplemented list -- so what each one means here is
+10 REM Group B: the housekeeping verbs. None of these is in the Go reference --
+20 REM they are on its own unimplemented list -- so what each one means here is
 30 REM a decision, recorded in src/runtime_housekeeping.c beside the verb.
 40 A# = 1 : B# = 2
 50 PRINT A# : PRINT B#
@@ -11,7 +11,7 @@
 110 P#(2) = 7 : Q#(2) = 9
 120 SWAP P#, Q#
 130 PRINT P#(2) : PRINT Q#(2)
-140 REM TRON prints each line number inline, as a C128 does.
+140 REM TRON prints each line number inline before the line runs, as a C128 does.
 150 TRON
 160 PRINT "TRACED"
 170 TROFF

tests/language/numeric/octal_literal.bas

@@ -1,7 +1,7 @@
-10 REM A leading zero is padding, not a radix. The reference selects base 8;
-20 REM 010 printed 8 and 08 was a parse error -- TODO.md section 6 item 10.
-30 REM Commodore BASIC has no octal literals.
-40 REM 0x is the one prefix that changes the base and reaches the scanner
+10 REM A leading zero is padding, not a radix. The reference selects base 8 for
+20 REM any lexeme starting with 0, so 010 printed 8 and 08 was a parse error --
+30 REM TODO.md section 6 item 10, fixed. Commodore BASIC has no octal literals.
+40 REM 0x is the one prefix that changes the base, and it now reaches the scanner
 50 REM whole: that was section 6 item 15.
 60 PRINT 010
 70 PRINT 08

tests/language/numeric/truth_value_arithmetic.bas

@@ -1,12 +1,12 @@
 10 REM A truth value carries its payload in boolvalue, not floatval. The three
 20 REM numeric operators were `if ( INTEGER ) ... else <treat as float>`, and
-30 REM that else was a catch-all, not a float branch -- so a truth value
+30 REM that else was a catch-all rather than a float branch -- so a truth value
 40 REM on the LEFT computed 0 - 1 into a field nothing reads, kept its BOOLEAN
 50 REM type, and printed `true` instead of -2. Silent, and wrong twice over.
 60 A# = 1
 70 PRINT (A# == 1)
-80 REM On the RIGHT it stays legal and stays -1, the same property that
-90 REM lets AND and OR double as logical operators. Refusing it would have
+80 REM On the RIGHT it stays legal and stays -1, which is the same property that
+90 REM lets AND and OR double as logical operators. Refusing it here would have
 100 REM broken every condition in the language.
 110 PRINT 5 - (A# == 1)
 120 PRINT 5 * (A# == 1)

tests/language/statements/multiple_per_line.bas

@@ -1,11 +1,11 @@
-10 REM Statements separated by colons. The COLON token existed from the start,
-20 REM but nothing consumed it, so a line could hold only one statement.
+10 REM Statements separated by colons. The COLON token existed from the start of
+20 REM the port and nothing consumed it, so a line could hold only one statement.
 30 PRINT "A" : PRINT "B"
 40 A# = 1 : B# = 2 : PRINT A# + B#
-50 REM An empty statement is no error: a trailing separator or run of them.
+50 REM An empty statement is not an error: a trailing separator, or a run of them.
 60 PRINT "C" :
 70 PRINT "D" :: PRINT "E"
-80 REM Everything after THEN belongs to the condition, as in BASIC 7.0, and is
+80 REM Everything after THEN belongs to the condition, which is BASIC 7.0 and is
 90 REM not something the reference had an opinion about -- it never got here.
 100 IF 1 == 1 THEN PRINT "TRUE-1" : PRINT "TRUE-2"
 110 IF 1 == 0 THEN PRINT "NEVER-1" : PRINT "NEVER-2"

tests/language/structures/missing_field.bas

@@ -1,5 +1,5 @@
-10 REM A field name is checked against the type's closed set, which
-20 REM is the one thing here whose valid spellings are written down.
+10 REM A field name is checked against a closed set the program declared, which
+20 REM is the one thing in this language whose valid spellings are written down.
 30 REM A misspelled *variable* is still silent -- see the last two lines.
 40 TYPE RECT
 50   W#

tests/language/structures/parameters.bas

@@ -17,7 +17,7 @@
 170 RETURN B@.W#
 180 PRINT WIDEN(A@)
 190 PRINT A@.W#
-200 REM To change one, pass a pointer. Assignment copies the pointer.
+200 REM To change one on purpose, pass a pointer. Assignment copies a pointer's
 210 REM reference, so the callee is looking at the caller's own record.
 220 DIM Q@ AS PTR TO CRATE
 230 POINT Q@ AT A@
@@ -37,7 +37,7 @@
 370 N2@.COUNT# = 20
 380 POINT N1@.TAIL@ AT N2@
 390 DEF TOTAL(P@ AS PTR TO NODE)
-395 REM A pointer is true when it points at something, so a walk knows
+395 REM A pointer is true when it points at something, which is how a walk knows
 396 REM where the list ends. NOT is the bitwise operator here, so the test is
 397 REM written the positive way round.
 400 IF P@->TAIL@ THEN RETURN P@->COUNT# + TOTAL(P@->TAIL@)

tests/language/structures/records.bas

@@ -1,4 +1,4 @@
-10 REM A TYPE declares fields; each takes its type from its own suffix,
+10 REM A TYPE declares its fields; each takes its own type from its own suffix,
 20 REM which is the same rule every other name in this language follows.
 30 TYPE COORD
 40   X#

tests/language/structures/reserved_names.bas

@@ -1,6 +1,6 @@
 10 REM A type name and a field name are bare words, and so is every verb, so
 20 REM they share a namespace whether we like it or not. Both are refused with
-30 REM the same rule the scanner applies to variable names -- and a type
+30 REM the same rule the scanner already applies to variable names -- and a type
 40 REM name is refused by the prescan, which can say so plainly rather than
 50 REM leaving the parser to report "Expected expression or literal".
 60 TYPE POINT

tests/reference/README.md

@@ -0,0 +1,63 @@
+# The reference interpreter's own test corpus
+
+These 41 `.bas` files and their 41 `.txt` expectations are **not this project's tests.** They
+are a byte-for-byte copy of the acceptance corpus belonging to the Go implementation this
+interpreter was ported from:
+
+| | |
+|---|---|
+| Source | `https://source.starfort.tech/andrew/basicinterpreter`, `tests/` |
+| Copied at | commit `d76162cb37eeaccddae2cf6cab7af7bc8175d6d2` ("Update README.md") |
+| Copied on | 2026-07-31 |
+| Verified | every file `cmp`-identical to the submodule at the time of the copy |
+
+They are registered as the `golden_*` CTest cases and run against `basic` on every build, in
+both the default and the `-DAKBASIC_WITH_AKGL=ON` configurations.
+
+## Why they are a copy, when they deliberately were not
+
+Until 2026-07-31 these were driven *in place* out of `deps/basicinterpret`, and the reasoning
+was written down in `CMakeLists.txt`: the corpus is a submodule, and copying a submodule's
+corpus guarantees drift.
+
+That reasoning was sound and it stopped applying. The Go project is deprecated and will not be
+updated, so there is nothing left to drift *from* — and a build that cannot run its own
+acceptance suite without cloning the implementation it replaced is not finished.
+
+## What these are for now
+
+**A regression suite, not a specification.** That distinction is the whole of how to treat
+them, and it changed on 2026-07-31 (`TODO.md` §0.1): matching the Go implementation is no
+longer a goal, so a difference between it and this interpreter is not automatically a bug in
+this one.
+
+What they are still good for is unchanged and is worth a lot: forty-one real BASIC programs
+with known-good output, covering arithmetic, arrays, flow control, every builtin function,
+`READ`/`DATA`, labels and three worked examples. That catches regressions whatever its
+provenance.
+
+## The rule for editing these
+
+**Diverge deliberately, never by accident.**
+
+A failure here means this interpreter's behaviour changed. Nine times in ten that is a bug you
+just introduced and the answer is to fix the code. The tenth time it is an improvement on the
+reference, and then the answer is:
+
+1. Change the expectation in the same commit as the code.
+2. Say why in the commit message.
+3. Add a line to `TODO.md` §5, which is the list of deliberate deviations.
+
+What is not acceptable is editing a `.txt` to make a red suite green without deciding which of
+the two you are doing.
+
+New cases for this project's own behaviour go in `tests/language/`, registered under `local_*`.
+The prefix says which corpus a failure came from, and a diff touching `tests/reference/` stands
+out as the thing it is.
+
+## Divergences so far
+
+| Case | Change | Why |
+|---|---|---|
+| `language/arithmetic/integer.txt` | Expectation grew from `4 4 2` to `4 4 2 2` | The program has **four** `PRINT` statements and the expectation had three values. The file ends in a blank line, and both interpreters filed a blank line under the loader's cursor — which for a line with no number of its own is the number of the line before it. So `40 PRINT 4 - 2` was erased before the program ran. The reference lost it the same way, which is why the expectation was written short. Fixed by skipping blank lines in RUNSTREAM, as `akbasic_runtime_load()` and `DLOAD` already did. `TODO.md` §5. |
+| `examples/strreverse.bas` | Variable `INPUT$` renamed to `SOURCE$` | `INPUT$` is a reserved word with a type suffix, which a real C128 refuses and which this interpreter now refuses too (`TODO.md` §6 item 16). The reference accepted it only because its own reserved-word check never fired. The expectation is byte-for-byte unchanged — the program still prints `REVERSED: OLLEH` — so the case keeps all of its value. |