akbasic/TODO.md

# Record

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

This file was the implementation plan for the Go → C port of `deps/basicinterpret`, written to be
executed by AI agents rather than read for inspiration. **The port is done**, so what it is now is
the record: the design decisions that are settled, the deviations from the reference and why each
was taken, the defects that were found and fixed, and the reasoning behind the measurements.

Each open item that moved leaves a line saying what it was and which issue carries it, because an
entry explaining *why* a defect matters is worth keeping beside the work it constrains — but the
tracking happens there, not here.

Issues are labelled by kind and blast radius, and milestoned by what they can land in: `0.1.x` for
anything that changes no public contract, `0.2.0` for new verbs and observable behaviour changes,
`1.0.0` for the design decisions. Everything filed carries `status::grooming`.

Two gaps this file recorded and deliberately did not file — the missing `HUD` anchors and a
dismissable dialog — are now `libakgl` #79 and #80. §7's rule is right that *changing* a dependency
is that repository's decision; it does not follow that reporting the gap is.

---

## 0. Agent protocol

### 0.1 The Go reference is deprecated. Stop matching it.

**`deps/basicinterpret` is a dead project. It will not be updated, and this interpreter is no
longer required to reproduce its behaviour.** Recorded here first because it silently reverses
the premise several sections of this file were written on, and because an agent that reads them
without this will park work that is no longer blocked.

What it changes:

- **§6 is now an ordinary defect list.** "Port the behaviour first so the port is provably
  faithful" is retired. Fix them because they are wrong, not when fidelity permits.
- **§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
  it is allowed and must be deliberate and recorded — see its README.

What it does **not** change:

- The corpus stays and stays green. Forty-one real BASIC programs with known-good output are
  worth having whatever their provenance, and an unexplained change there is still a red flag.
- The Go source stays readable as documentation. It remains the best answer to "what did the
  original actually do here", which is a question worth being able to answer even once the
  answer stops being binding.
- Nothing about the `ak*` house rules, which never came from the reference.

**Read these before touching anything**, in this order:

1. `MAINTENANCE.md` in this repository — project goals, the `libakerror` convention, the
   error-code range map, and the dependency versions.
2. `deps/libakerror/AGENTS.md` — the `ATTEMPT`/`CLEANUP`/`PROCESS`/`HANDLE`/`FINISH` protocol.
3. `deps/libakerror/UPGRADING.md` — 1.0.0's status registry. Required before writing an error
   code; the mechanism it replaced is gone.
4. `deps/libakstdlib`'s issue tracker — the defects and gaps in the library this port calls
   into. §1.9 below says which calls are cleared for use; that section is not optional
   reading, it bans a family of functions the port would otherwise reach for by reflex.
5. `deps/libakgl/AGENTS.md` — the no-`malloc` rule and the commit co-author requirement.
6. `deps/basicinterpret/README.md` — the language reference and the unimplemented list. Still
   worth reading for the verb set and the semantics; no longer binding, per §0.1.

**Rules for working this file:**

- **Do not** mark an item done until its acceptance command passes on a clean out-of-tree
  build. "It compiles" is not acceptance.
- **Do** update the tracker in the same commit as the work: close the issue, or replace it with
  the defect it uncovered. Outstanding items live there; this file holds the record.
- **Do** add the agent program name, model name and version as a commit co-author. That rule
  comes from `libakgl` and applies here.
- **Never** hand-edit generated output. `build/` trees and the generated `akerror.h` are
  off-limits; change the generator.
- **Never** reformat a file you are not otherwise changing.
- When a step is blocked because `libakgl` cannot supply a capability, **do not work around
  it here.** File it against `libakgl` in its issue tracker -- what the BASIC verb requires,
  what the `akgl_*` entry point should look like, and what tests would cover it -- and note the
  block in §7 below.

**Style**, restated so nobody has to go look: C99, 4-space indent, tabs at width 8
(`stroustrup`), function-body braces in column 0 on their own line, control braces on the same
line, **always brace**, spaces inside control-flow parens — `if ( x == y ) {`. Pointer star
binds to the identifier: `char *name`. Prefix is `akbasic_` for functions,
`akbasic_TypeName` for types, `AKBASIC_UPPER_SNAKE` for macros. `static` helpers drop the
prefix. Parameter names must match between header and source.

---

## 1. Design decisions already made

These are settled. Do not relitigate them mid-port; if evidence says one is wrong, say so in
a commit that changes it deliberately, and update this section.

### 1.1 Reflection becomes one aligned dispatch table

The Go runtime resolves verbs with `reflect.MethodByName("Command" + NAME)`
(`basicruntime.go:401`), functions with `"Function" + NAME`, and special parse paths with
`"ParseCommand" + NAME` (`basicparser.go:103`). C has no reflection and we are not adding
any. Replace all three with **one** static table in `src/verbs.c`, sorted by name, searched
with `bsearch(3)`:

```c
/* name        token type              parse handler          exec handler        */
{ "AUTO",      AKBASIC_TOK_CMDIMM,     NULL,                  cmd_auto      },
{ "DATA",      AKBASIC_TOK_COMMAND,    parse_data,            cmd_data      },
{ "DEF",       AKBASIC_TOK_COMMAND,    parse_def,             cmd_def       },
```

A `NULL` parse handler means "parse the rval as a plain expression", which is exactly what
`commandByReflection` returning `(nil, nil)` means today. Adding a verb is adding one row plus
two functions. **Keep the table column-aligned and one row per verb** — it is a table, so it
gets laid out as one.

This also kills the Go scanner's three separate maps (`reservedwords`, `commands`,
`functions`, `basicscanner.go:64-67`): the token type lives in the same row.

### 1.2 Strings are fixed-size and live inline

`libakstdlib` has no string type. `libakgl` has `akgl_String` but it is `PATH_MAX` bytes,
refcounted, and pool-allocated — wrong shape for a value that gets copied on every
assignment, and it would drag a `libakgl` dependency into the core interpreter.

Define in `include/akbasic/types.h`:

```c
#define AKBASIC_MAX_STRING_LENGTH    256    /* matches AKBASIC_MAX_LINE_LENGTH */
```

and give `akbasic_Value` a `char stringval[AKBASIC_MAX_STRING_LENGTH]` **inline**. `clone()`
becomes a struct assignment. No allocator, no refcount, no lifetime question.

**Tradeoff, stated:** every `akbasic_Value` is ~300 bytes, so one environment's
`values[AKBASIC_MAX_VALUES]` pool is ~19KB, and 32 environments is ~610KB of BSS. That is
fine on a PC and is the price of never calling `malloc`. If it ever isn't fine, the knob is
`AKBASIC_MAX_STRING_LENGTH`, not the allocator.

Truncation is an **error**, not a silent clamp: `FAIL_RETURN(e, AKBASIC_ERR_VALUE, ...)`.

### 1.3 Maps become fixed-capacity open-addressed tables

Five Go maps need replacing:

| Go site | Purpose | C replacement |
|---|---|---|
| `BasicScanner.reservedwords/commands/functions` | keyword → token type | the §1.1 static table + `bsearch` |
| `BasicEnvironment.variables` | name → `*BasicVariable` | `akbasic_SymbolTable`, capacity `AKBASIC_MAX_VARIABLES` |
| `BasicEnvironment.functions` | name → `*BasicFunctionDef` | `akbasic_SymbolTable`, capacity `AKBASIC_MAX_FUNCTIONS` |
| `BasicEnvironment.labels` | name → line number | `akbasic_SymbolTable`, capacity `AKBASIC_MAX_LABELS` |

One implementation, `src/symtab.c`, keyed by `aksl_strhash_djb2()` (already in
`libakstdlib`) with linear probing and a fixed slot array. **Use the existing hash; do not
write another one.** Table full is an error, not a resize.

Caveat, recorded upstream: the wrapper sign-extends `char`, so a
high-bit byte hashes wrong — `"\xff\xfe"` returns 5859874 where the `unsigned char` answer is
5868578. BASIC identifiers are 7-bit ASCII (the scanner only accepts `IsLetter`/`IsDigit` plus
a type suffix), so this cannot bite the symbol tables. It **would** bite if anyone later keys
a table on a string literal or a filename. Do not work around it here; it is already filed
upstream.

### 1.4 Environments come from a pool and are released

Go calls `new(BasicEnvironment)` at `basicruntime.go:121` and `basicparser_commands.go:124`
and never frees one. A long-running `GOSUB` or `FOR` in Go leaks; the GC eventually catches
some of it, and nothing in the tests notices.

C gets `HEAP_ENVIRONMENT[AKBASIC_MAX_ENVIRONMENTS]` with
`akbasic_env_acquire()` / `akbasic_env_release()`, in the shape of `akgl_heap_next_*`.
`akbasic_runtime_prev_environment()` **must** release the environment it pops. Pool
exhaustion is `AKBASIC_ERR_ENVIRONMENT`, reported with the current line number.

Watch the one place this is not a clean stack: `userFunction` (`basicruntime.go:348`) stores
a `BasicEnvironment` **by value** inside `BasicFunctionDef` and re-`init()`s it on every call.
In C the funcdef holds an `akbasic_Environment *` acquired at `DEF` time and reset per call —
it is owned by the funcdef, not the pool's free list, until the funcdef dies.

### 1.5 Output goes through a text sink backend

`Write()` and `Println()` (`basicruntime_graphics.go:140,148`) mirror every line to stdout
*and* to an SDL surface. That mirror is the only reason the golden-file suite works. Do not
reproduce it as a hardcoded pair of calls.

Define a record of function pointers, populated by an initializer — the house pattern:

```c
typedef struct akbasic_TextSink
{
    void *self;
    akerr_ErrorContext AKERR_NOIGNORE *(*write)(struct akbasic_TextSink *self, char *text);
    akerr_ErrorContext AKERR_NOIGNORE *(*writeln)(struct akbasic_TextSink *self, char *text);
    akerr_ErrorContext AKERR_NOIGNORE *(*readline)(struct akbasic_TextSink *self, char *dest, size_t len);
    akerr_ErrorContext AKERR_NOIGNORE *(*clear)(struct akbasic_TextSink *self);
} akbasic_TextSink;
```

`akbasic_sink_init_stdio()` is in the library and `akbasic_sink_init_akgl()` is in the
akgl-backed module. The driver is supposed to pick: a default build selects stdio, while an
`AKBASIC_WITH_AKGL` build selects the SDL text path and mirrors its output to stdout. It does
not do that yet; §3 records the missing standalone frontend. Cursor arithmetic, wrapping and
scrolling belong to the akgl sink, not to the interpreter.

### 1.6 The interpreter steps; it does not run

Go's `run()` (`basicruntime.go:682`) is a `for {}` that owns the process until `MODE_QUIT`.
Goal 3 forbids that: a host game must be able to bound execution.

The library exposes:

```c
akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_step(akbasic_Runtime *obj);
akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_run(akbasic_Runtime *obj, int maxsteps);
```

`_step()` does exactly what one iteration of Go's `for {}` body does and returns.
`_run(obj, maxsteps)` loops `_step()` until the mode is `AKBASIC_MODE_QUIT` or `maxsteps`
steps have elapsed; `maxsteps <= 0` means unbounded, which is what the standalone driver
passes. **This is a deliberate restructure, and it must not change a single byte of golden
output.**

`QUIT` sets `AKBASIC_MODE_QUIT` and returns. **Nothing in the library calls `exit()`,
`abort()`, or `FINISH_NORETURN`.** `FINISH_NORETURN` appears exactly once in the tree, in
`src/main.c`.

### 1.7 Error codes are absolute, reserved from the 1.0.0 registry

`deps/libakerror` is at **1.0.0**. Read `deps/libakerror/UPGRADING.md` before writing an error
code; `MAINTENANCE.md`'s error-code section is the condensed version. Three things this changes
from what you may have seen in an older draft or in `libakgl`:

- `AKERR_MAX_ERR_VALUE` **no longer exists**. The name registry is sparse and takes any `int`.
  There is nothing for a consumer to size, and no compile definition to set. Anywhere you find
  one, delete it.
- `__AKERR_ERROR_NAMES` **no longer exists**. The table is private.
- Codes are **absolute integer constants at 256 or above**, never `AKERR_LAST_ERRNO_VALUE + N`.
  The offset scheme is what produced the live `libakgl` collision documented in
  `MAINTENANCE.md`.

`akbasic` owns **512–767** per the range map in `MAINTENANCE.md`. Declare it as an `enum`, so the
values stay compile-time integer constants (`HANDLE` expands to `case` labels, which require
that) and adding a code does not mean renumbering an offset:

```c
#define AKBASIC_OWNER "akbasic"

enum {
    AKBASIC_ERR_BASE        = 512,   /** Start of akbasic's reserved status range */
    AKBASIC_ERR_SYNTAX      = AKBASIC_ERR_BASE,
                                     /** Parse-time grammar violation */
    AKBASIC_ERR_TYPE,                /** Incompatible types in an operation */
    AKBASIC_ERR_UNDEFINED,           /** Reference to an undefined verb, function or label */
    AKBASIC_ERR_BOUNDS,              /** Array subscript or pool index out of range */
    AKBASIC_ERR_ENVIRONMENT,         /** Environment pool exhausted or orphaned environment */
    AKBASIC_ERR_VALUE,               /** A value was malformed, truncated or unconvertible */
    AKBASIC_ERR_STATE,               /** A verb ran outside the block structure it requires */
    AKBASIC_ERR_LIMIT       = AKBASIC_ERR_BASE + 256
};
```

`akbasic_init()` reserves the **whole** 256 in one call and then names each code. Both
registry calls return `akerr_ErrorContext *` and are `AKERR_NOIGNORE`, so a collision is an
ordinary error — `PASS` it and let it propagate out of init:

```c
akerr_ErrorContext AKERR_NOIGNORE *akbasic_init(void)
{
    PREPARE_ERROR(errctx);

    PASS(errctx, akerr_reserve_status_range(AKBASIC_ERR_BASE,
					    AKBASIC_ERR_LIMIT - AKBASIC_ERR_BASE,
					    AKBASIC_OWNER));
    PASS(errctx, akerr_register_status_name(AKBASIC_OWNER, AKBASIC_ERR_SYNTAX,
					    "Syntax Error"));
    /* ... one per code ... */
    SUCCEED_RETURN(errctx);
}
```

Reserve the whole range in **one** call — a subset or superset of your own range raises
`AKERR_STATUS_RANGE_OVERLAP`, not a no-op. Use `akerr_register_status_name()`, never the
two-argument `akerr_name_for_status(status, name)` set path: the owned form is the one that
catches a component writing into a range that is not its own, and the two-argument form is
what let `libakgl` silently clobber `libakerror`'s names.

There is no startup ceiling to assert any more — the BSS-overflow hazard the old draft
defended against was deleted along with `AKERR_MAX_ERR_VALUE`. What replaces it is the
reservation itself: if `akbasic_init()` returns an error, something else owns part of 512–767
and the process must not continue as though it does not.

Do not call `akerr_init()` first. Every registry entry point calls it, and since 1.0.0 it no
longer clears reservations made before it ran.

### 1.8 Error message text is a convention, no longer a contract

`tests/language/array_outofbounds.txt` is, verbatim:

```
? 20 : RUNTIME ERROR Variable index access out of bounds at dimension 0: 4 (max 2)\n\n
```

The trailing double newline is real: `basicError` builds a string ending in `\n` and hands it
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
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`
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**

`deps/libakstdlib` is at **0.2.0**, and that release *fixed all six* of the confirmed defects
this section was built around, plus seventeen contract gaps. The table of bans that used to
live here is gone because it is no longer true, and leaving it would send an agent around a
workaround for a function that now works.

What changed, in the four that mattered to this port:

| Was banned | Now |
|---|---|
| `aksl_atoi` / `_atol` / `_atoll` / `_atof` | Every one takes a `dest` pointer and raises `AKERR_VALUE` on no digits or trailing junk, `ERANGE` on overflow — exactly the contract this section demanded |
| `aksl_list_append` / `_iterate` | Append no longer truncates to two nodes; iterate no longer skips the first half |
| `aksl_tree_iterate` | `AKERR_ITERATOR_BREAK` stops the traversal |
| `aksl_realpath` | Rewritten; no longer reads uninitialised memory on its error path |

Two signature changes reach this repository. `aksl_fread` and `aksl_fwrite` now take a
required `size_t *nmemb_out` and report a short transfer as `AKERR_IO` instead of a silent
success — so a `DSAVE` onto a full disk is now an error a program sees, where before it
reported nothing. `src/runtime_commands.c` passes the count and discards it, which is correct:
the library does the noticing now.

**`src/convert.c` is gone.** It existed only because `aksl_ato*` could not report a conversion
failure, and its own note said what to do when that changed: *"When it grows it, delete
`src/convert.c` and switch the call sites over."* That is done. Six call sites now go straight
to the library — `newLiteralInt` and `newLiteralFloat` in `src/grammar.c`, the line number in
`src/scanner.c`, `FunctionVAL` in `src/runtime_functions.c`, `INPUT` in
`src/runtime_commands.c`, and `GSHAPE`'s handle in `src/runtime_graphics.c`.

Three things that fell out of it, recorded because each was checked rather than assumed:

- **`aksl_strtoll(str, NULL, base, &dest)` is the exact replacement**, not `aksl_atoll`, wherever
  a base is involved. The `ato*` forms are base 10; `src/grammar.c` picks base 8 or 16 from the
  lexeme's prefix. A `NULL` endptr is what makes trailing junk an error rather than a stopping
  point, and that is the whole contract this port needs.
- **The raised status changed** from `AKBASIC_ERR_VALUE` to `AKERR_VALUE`, and the message text
  with it — `VAL("garbage")` now says `no digits in "garbage"`. §1.8 makes message text part of
  the acceptance contract, so this was checked against the corpus first: **no golden file
  contained a conversion message**, which is also why §1.9 used to ask for one. Two now exist,
  `tests/language/numeric/val_refuses_garbage` and `octal_literal`, so the next change to that
  text has to move a golden file.
- **`tests/convert.c` became `tests/numeric_contract.c`.** The assertions did not become
  worthless when the wrapper went away — they became assertions about a contract this port
  depends on and no longer owns, which is worth pinning exactly because a regression in it would
  make `VAL("garbage")` return 0 silently. Same reasoning `libakstdlib`'s own
  `tests/test_status_registry.c` gives for pinning that it reserves no status range.

One caveat survives the upgrade unchanged: `aksl_strhash_djb2` still sign-extends `char`, so a
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.

---

## 2. What exists — **the core port is complete and green**

Phases 0 through 6 of the original plan are done. The interpreter builds clean under
`-Wall -Wextra`, passes the reference's entire corpus, and passes under ASan and UBSan.

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
longer a gate.

```sh
cmake -S . -B build && cmake --build build --parallel
ctest --test-dir build --output-on-failure          # 59/59
cmake -S . -B build-asan -DAKBASIC_SANITIZE=ON      # 59/59
cmake -S . -B build-cov  -DAKBASIC_COVERAGE=ON      # 92.3% line, 96.9% function
```

| Module | Source | Reference |
|---|---|---|
| Symbol table | `src/symtab.c` | the five Go maps |
| Value | `src/value.c` | `basicvalue.go` |
| Variable | `src/variable.c` | `basicvariable.go` |
| Tokens and AST leaves | `src/grammar.c` | `basicgrammar.go` + `basicparser.go` |
| Dispatch table | `src/verbs.c` | the three reflection lookups |
| Scanner | `src/scanner.c` | `basicscanner.go` |
| Parser | `src/parser.c`, `src/parser_commands.c` | `basicparser*.go` |
| Environment | `src/environment.c` | `basicenvironment.go` |
| Runtime | `src/runtime.c` | `basicruntime.go` minus SDL |
| Verbs and functions | `src/runtime_commands.c`, `src/runtime_functions.c` | `basicruntime_{commands,functions}.go` |
| Text sink | `src/sink_stdio.c` | `basicruntime_graphics.go`'s stdout mirror |
| Stdio driver | `src/main.c` | `main.go` minus its SDL frontend |
| Embedding examples | `examples/embed.c`, `examples/hostvars.c` | *(new)* |

`akbasic_runtime_load(rt, source)` was added while writing the README's embedding
section: a host usually holds its script as a string and wants the sink reserved for output,
and the only path that existed — `AKBASIC_MODE_RUNSTREAM` reading through the sink's
`readline` — forces a game to point its output device at its source text. `examples/embed.c`
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`
— 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.

**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
submodule moved out of the tree. The Commodore font moved too, to `assets/fonts/`, which was the
other thing tying the build to it; `assets/fonts/PROVENANCE.md` carries the licence question that
came with it.

Eighteen unit tests cover the modules the corpus cannot reach on its own.
`tests/known_reference_defects.c` is registered in `AKBASIC_KNOWN_FAILING_TESTS` and asserts
the **correct** contract for six of the defects in §6; when one is fixed CTest reports
"unexpectedly passed", which is the cue to split that assertion out and strike the item.

Two budget numbers moved during implementation and are worth knowing:
`AKBASIC_MAX_ARRAY_ELEMENTS` (1024) caps one array and `AKBASIC_MAX_ARRAY_VALUES` (4096) caps
all of them together, drawn from an `akbasic_ValuePool` the runtime owns. The reference had no
such ceiling because it called `make()`.

---


## 3. The akgl-backed sink, devices and standalone frontend — **done**

`-DAKBASIC_WITH_AKGL=ON` builds and its suite passes, and the build option now changes what
the executable *does*: an AKGL build of `basic` opens a window, draws BASIC output into it,
pumps SDL events, lets you type at it, and still puts every byte on stdout. Four adaptors in
the `akbasic_akgl` target, which is the only thing here that links SDL, are complete and
tested:

| File | Backs |
|---|---|
| `src/sink_akgl.c` | the §1.5 text sink, over `akgl_text_measure` and `akgl_text_rendertextat` |
| `src/graphics_akgl.c` | `akbasic_GraphicsBackend`, over `akgl_draw_*`, and the SSHAPE surface pool |
| `src/audio_akgl.c` | `akbasic_AudioBackend`, over `akgl_audio_*` |
| `src/input_akgl.c` | `akbasic_InputBackend`, over `akgl_controller_poll_key` |

The character grid comes from `akgl_text_measure(font, "A", &w, &h)` — the direct equivalent of
the `font.SizeUTF8("A")` at `basicruntime.go:96`, and the call this was blocked on until
42b60f7. Wrapping is done on the character grid rather than by handing SDL_ttf a `wraplength`,
because the cursor has to land somewhere definite: a program that `PRINT`s a long string and
then `PRINT`s again expects the second to start on the row after the first ended, and only the
code that placed the characters knows which row that is.

**The interpreter owns no window, renderer or event loop.** Every initializer takes something
the host already made. Each calls `akgl_error_init()` first: `akgl_game_init()` would have,
but we drive subsystems directly and never call it, and a code raised before that registration
carries no name into its stack trace. It is idempotent.

*Acceptance:* `tests/akgl_backends.c`, a 128x128 software renderer under the dummy video
driver read back with `SDL_RenderReadPixels` — the pattern `deps/libakgl/tests/draw.c`
established, which needs no display and no offscreen harness. Registered as the `akgl_backends`
CTest case, and only when `AKBASIC_WITH_AKGL` is on.

### The standalone frontend

The standalone executable is itself a host, and that half of the Go frontend is now ported —
`src/frontend_akgl.c`, in its own `akbasic_frontend` target. **The separation is in the build
graph and not only in a comment**: `akbasic` is the interpreter, `akbasic_akgl` is the four
adaptors that draw through somebody else's renderer, and `akbasic_frontend` is the one thing in
the repository that creates a window. A game embedding the interpreter links the first two and
not the third.

| Piece | Where |
|---|---|
| Window, renderer, font, the four adaptors | `akbasic_frontend_akgl_init()` |
| Sink and devices onto a runtime | `akbasic_frontend_akgl_attach()` |
| One frame: pump events, draw the text layer, present | `akbasic_frontend_akgl_pump()` |
| The bounded frame loop | `akbasic_frontend_akgl_drive()` |
| stdout mirror | `src/sink_tee.c`, in the *core* library |

Four things are worth knowing about how it came out.

1. **The stdout mirror is a sink, not a second write.** §1.5 made the sink boundary precisely
   so the interpreter would never carry the reference's hardcoded pair of calls, and §3 item 5
   said it again. `akbasic_sink_init_tee()` composes two sinks into one and takes `readline`
   from whichever of the two was named as the reader — which is the whole difference between
   the two modes: a program read from a file comes in through the stdio half, and typed lines
   come in through the akgl half's line editor. It lives in the core library and is tested
   there (`tests/sink_tee.c`), because composing two function-pointer records needs no SDL.

2. **The line editor borrows the host's loop a frame at a time.** `readline` has to wait for a
   typed line, and §1.6 forbids the library blocking — and a sink that sat on the keyboard with
   no way to pump events would deadlock the process on its first `INPUT`. So the host installs
   an `akbasic_AkglPump` with `akbasic_sink_akgl_set_pump()`, and the editor calls it between
   keystrokes. The loop is still the host's. `akbasic_frontend_akgl_pump()` has that exact
   signature and is installed as-is. Without a pump the sink reports EOF, which is what it did
   before and what a host that wants no editor still gets.

3. **The frame loop is bounded, and that is what makes the close button work.** 256 steps per
   frame (`AKBASIC_FRONTEND_STEPS_PER_FRAME`), then pump and present. `10 GOTO 10` under an
   unbounded `run()` would own the process forever; `tests/akgl_frontend.c` runs exactly that
   and asserts the window close ends it.

4. **The frame is not cleared.** The graphics verbs draw straight to the renderer rather than
   into a display list, so clearing would wipe every `DRAW` at the end of the frame it was
   issued in. The text layer is drawn over whatever is there, which is also how a C128 stacks
   its text plane on its bitmap plane.

*Acceptance:* two things, and the second one is the stronger.

- `tests/akgl_frontend.c`, registered as the `akgl_frontend` CTest case: a program run through
  the frontend under the dummy driver, asserting the mirrored stdout **byte for byte** and
  reading the renderer back to prove the same characters were drawn in the Commodore font;
  synthetic key events pushed into SDL's own queue and read back through the frontend's input
  backend, so every link the host owns is in the path; the line editor's fold to upper case,
  its backspace and its escape; a whole REPL session typed at the window and ended with a typed
  `QUIT`; and the window-close path.
- **The entire golden corpus is driven through the AKGL binary.** A `-DAKBASIC_WITH_AKGL=ON`
  build registers the same 41 upstream cases against the same executable, which now opens a
  window to run them, and all 41 still match byte for byte. That is a much broader statement
  than any hand-written frontend test: the SDL path changes no observable output anywhere in
  the corpus.

Three `no_device.bas` local cases are **deliberately not registered** in an AKGL build. Their
premise is a driver that was given no devices, which is true of the stdio driver and
deliberately false of this one. The refusal path they cover is asserted directly against the
backend records in `tests/devices.c`, which both configurations build.

**Manual check against a real display, 2026-07-31.** The dummy driver cannot prove presentation,
so `build-akgl/basic` was run against X display `:0` on a program that prints a line, draws a
`BOX` and then loops. `xwininfo` found a real 800x600 window titled `BASIC`; the window was
captured with `import` and measured: the first text row carries glyph pixels (mean 65/255), the
box's left edge at x=100 is a solid white line (mean 255), the box interior is black — it
outlines rather than fills — and an empty corner is black. stdout carried `HELLO WORLD` at the
same time. `QUIT` exits cleanly with status 0.

**The typing half is no longer manual, and it is no longer a gap.** It used to read "somebody
should type at it once", because no key-synthesis tool was installed. `xdotool` now is, and
`tests/akgl_typing.sh` is registered as the `akgl_typing` CTest case: it starts the driver under
a pty, waits for the window with `xdotool search --sync`, gives it keyboard focus, types a
program containing a **string literal** and a **lower-case** one, and polls the mirrored stdout
for what they print.

That case earns its keep twice over. It is the only test that covers the path *upstream* of SDL
— X11 → SDL composition → libakgl's ring → the editor — and everything else synthesises SDL
events, which is precisely how the missing `SDL_StartTextInput()` shipped with a green suite.
Confirmed by reverting both halves of that fix and watching it fail with the same symptom that
was reported: `READY`, and nothing after it.

It needs a real X server, a window manager and `xdotool`, and it steals keyboard focus for about
fifteen seconds. Absent any of those it reports CTest `Skipped` rather than failing, which is
what it does in CI. `AKBASIC_SKIP_INTERACTIVE=1` skips it deliberately.

### The five things that had to be worked around — **all gone**

Every one was filed against `libakgl` and every one is resolved in its 0.3.0. What is left here
is the note that they existed, because the pattern is the point: file it upstream, comment the
workaround at its site with the words "filed upstream", delete it when it lands.

| Was | Resolved by |
|---|---|
| An embedded `libakgl` required its vendored SDL, SDL_image, SDL_mixer, SDL_ttf and jansson to be *installed*, so our `CMakeLists.txt` declared all five by hand first | It adds them whether or not it is top-level |
| `akgl/controller.h` did not compile on its own — it used `akgl_Actor *` and included nothing that declared it | It includes `<akgl/actor.h>` |
| There was no way to bind a 2D backend to a renderer you already had, so the six vtable pointers were assigned by hand in two files | `akgl_render_bind2d()` |
| `akgl_text_rendertextat()` dereferenced an unset `draw_texture`, so the first `PRINT` through an unbound backend segfaulted | It checks, and reports `AKERR_NULLPOINTER` like the draw entry points |
| `SOUND`'s frequency sweep had no equivalent and was refused | `akgl_audio_sweep()` |

**0.3.0 also arrived with a regression that this repository is the one that found**, because it
is the only consumer that embeds `libakgl` alongside other projects: the commit that made the
vendored dependencies unconditional also made its `add_test()` shadow unconditional, and CMake
chains command overrides exactly one level deep. Two projects in one tree cannot both shadow
`add_test` — the second rebinds `_add_test` to the first and the builtin becomes unreachable to
everybody, so our own registrations recursed to CMake's depth limit. Fixed upstream by putting
the top-level guard back; filed as `libakgl` defect 27, with the two-line CMake program that
demonstrates the one-level limit.

### Still missing from the sink

Nothing that blocks a verb, and as of `libakgl` 0.3.0 nothing that blocks a *character* either.
The ring now carries the composed UTF-8 text SDL worked out from each keystroke, so the editor
takes that in preference to the keycode and shifted characters, keyboard layouts, compose keys
and dead keys all work. **A double quote can be typed, so a BASIC string literal can be typed**,
which was the sharp end of the old limitation — it used to mean a program with a string in it
had to be passed on the command line. Letters are no longer folded to upper case, because there
is no longer any reason to.

**The host has to turn text input on**, and forgetting to is how this broke once. SDL3 has it
off by default and per-window, so it is `akbasic_frontend_akgl_init()` that calls
`SDL_StartTextInput()` — `akgl/controller.h` says as much. Without it SDL emits no
`SDL_EVENT_TEXT_INPUT` at all, every keystroke reaches the ring with an empty `text`, and an
editor that reads that as "not a character" is silently dead: nothing echoes in the window, and
nothing reaches stdout either, because `RUN` can never be typed.

The editor therefore **falls back to the keycode** when a keystroke carries no composed text,
folded to upper case. A worse keyboard is a great deal better than no keyboard, and it means a
host that embeds these adaptors and forgets `SDL_StartTextInput()` gets a usable editor rather
than a dead one. Both halves are asserted in `tests/akgl_frontend.c`, and both were checked by
reverting each in turn and watching the test fail.

Worth knowing about the test suite that missed this: every other keyboard test pushes
`SDL_EVENT_TEXT_INPUT` into SDL's queue by hand, which is what a real keyboard produces — *once
text input has been started*. Synthesising the end of a chain cannot test the beginning of it.
The new test asserts `SDL_TextInputActive()` directly for that reason, and the whole frontend
suite has been run against a real X11 window as well as the dummy driver.

One limit remains, and it is a choice rather than a gap:

- **No cursor movement within a line.** Backspace and escape only. The arrow keys stay in the
  ring for a script's own `GET` loop, which is the more valuable use of them.

A non-ASCII character is accepted by the keyboard and then dropped rather than stored, which is
§1.2 rather than the editor: the grid is a byte per cell and a value's string is a fixed 256
bytes, so a multi-byte character has nowhere to go. Dropping it is honest where storing half of
it is not.

`WINDOW` and `KEY` in group E want a text-window rectangle and a function-key table on top of
this, which is ordinary work here rather than anything blocked.

---

## 4. Remaining work: language completion (goal 2)

The work queue is the "What Isn't Implemented" list in `deps/basicinterpret/README.md`.
Each verb is: table row (§1.1) → parse handler if it needs one → exec handler → unit test →
a new `.bas`/`.txt` pair. **Both** kinds of test; they answer different questions.

Order by what unblocks the most, and by what does not need `libakgl` to grow first:

| Group | Verbs | Blocked on |
|---|---|---|
| ~~A. Structure~~ | ~~`DO`, `LOOP`, `WHILE`, `UNTIL`, `ON`, `BEGIN`, `BEND`, `END`~~ | **done** — `src/runtime_structure.c`, `tests/structure_verbs.c` |
| ~~B. Housekeeping~~ | ~~`NEW`, `CLR`, `CONT`, `SWAP`, `TRON`, `TROFF`, `HELP`~~ | **done** — `src/runtime_housekeeping.c`, `tests/housekeeping_verbs.c` |
| ~~B′. Housekeeping, deferred~~ | ~~`RESTORE`, `RENUMBER`~~ | **done** — `src/data.c` and `src/renumber.c`, `tests/read_data.c` and `tests/renumber.c` |
| ~~C. Errors~~ | ~~`TRAP`, `RESUME`, `ER`, `ERR`~~ | **done** — `src/runtime_trap.c`, `tests/trap_verbs.c`. `ER`/`EL` are `ER#`/`EL#`; see §5 |
| ~~D. Strings/format~~ | ~~`USING`, `PUDEF`, `WIDTH`, `CHAR`~~ | **done** — `src/format.c`, `src/runtime_format.c`, `tests/format_verbs.c` |
| ~~E. Console~~ | ~~`WINDOW`, `KEY`, `SLEEP`, `WAIT`, `TI`~~ | **done** — `src/runtime_console.c`, `tests/console_verbs.c` |
| ~~F. Disk~~ | ~~all 21~~ | **done** — `src/runtime_disk.c`, `tests/disk_verbs.c`. Five refuse for want of a drive and `DIRECTORY` for want of an upstream wrapper; see §5 |
| ~~G. Graphics~~ | ~~`GRAPHIC`, `DRAW`, `BOX`, `CIRCLE`, `PAINT`, `COLOR`, `SCALE`, `SSHAPE`, `GSHAPE`, `LOCATE`~~ | **done** — `src/runtime_graphics.c`, `tests/graphics_verbs.c` |
| ~~H. Sprites~~ | ~~`SPRITE`, `MOVSPR`, `SPRCOLOR`, `SPRSAV`, `COLLISION`~~ | **done** — `src/runtime_sprite.c`, `src/sprite_akgl.c`, `tests/sprite_verbs.c`. `SPRDEF` is out of scope; see below |
| ~~I. Audio~~ | ~~`PLAY`, `SOUND`, `ENVELOPE`, `VOL`, `TEMPO`~~ | **done** — `src/runtime_audio.c`, `src/play.c`, `tests/audio_verbs.c` |
| I′. Audio, still gapped | `FILTER` | `libakgl` has no filter stage and SDL3 supplies no primitive; refused with `AKBASIC_ERR_DEVICE`. `SOUND`'s sweep arguments used to be here and landed with `akgl_audio_sweep` in libakgl 0.3.0 |
| ~~E′. Console input~~ | ~~`GET`, `GETKEY`, `SCNCLR`~~ | **done** — `src/runtime_input.c`, `tests/input_verbs.c` |
| ~~J. Machine~~ | ~~`SYS`, `FETCH`, `STASH`~~ | **done** — `src/runtime_machine.c`, `tests/machine_verbs.c`. `SYS` is refused by name; see §5 |

**`RESTORE` and `RENUMBER` are deferred, and neither is a small job.**

- ~~**`RESTORE` needs a DATA pointer, and there isn't one.**~~ **Done.** Every `DATA` statement
  is pre-scanned into one flat list before the program runs -- `src/data.c`, called from
  `akbasic_runtime_set_mode()` beside the label prescan -- and `READ` walks a cursor along it.
  `RESTORE` resets the cursor; `RESTORE (line)` moves it to the first item on or after that
  line.

  It fixed two defects on the way, both of which were consequences of `READ` not reading.
  **A `DATA` line above its `READ` is now found**, where skipping forward from the `READ` used
  to run off the end of the program in silence. And **the lines between a `READ` and its `DATA`
  now execute**, where the skip used to swallow them -- a C128 runs them, because `READ` takes
  the next item and execution carries on. The one corpus case has its `DATA` immediately after
  its `READ`, so neither was observable there. `tests/read_data.c`.

  `DATA` at run time is now a no-op: it is a declaration, and reaching the statement means
  walking past it.

- ~~**`RENUMBER` has to rewrite references or it is worse than useless.**~~ **Done.**
  `src/renumber.c` builds the whole old-to-new map first, then rewrites every line -- including
  lines *before* the renumbered region, which can branch into it -- and only then moves them.

  The rewrite is textual and understands exactly one thing about the rest of the language:
  where a string literal starts and stops, so `PRINT "GOTO 10"` survives. `GOTO`, `GOSUB`,
  `RUN`, `RESTORE` and `TRAP` targets are rewritten, and so is the comma-separated list after
  `ON X GOTO` -- for free, since the targets follow the `GOTO`. `COLLISION` is special-cased
  because its handler is its *second* argument.

  Two deliberate non-rewrites. **A target naming a line that does not exist is left alone**:
  `GOTO 9999` in a program with no line 9999 is already broken, and inventing a destination
  would hide that. And **`THEN`/`ELSE` do not take bare line numbers in this dialect** -- the
  corpus writes `THEN GOTO 100` -- so a number after `THEN` is an expression, not a target.

  A renumbering that would land a moved line on a kept one is refused before anything is
  written, because losing a line to a renumbering is not recoverable.

  **A program written with labels needs none of this.** `GOTO DONE` is unaffected by any
  renumbering, which is the strongest argument for `LABEL` there is.

`LOCATE` used to appear in both E and G. It belongs to G alone: in BASIC 7.0 `LOCATE` moves the
*graphics* pixel cursor that `DRAW` starts from, and the text cursor verb is `CHAR`, which is
already in group D.

**Out of scope, and staying that way** — the reference marks these as incompatible with a
modern PC and that reasoning stands: `BANK` (no bank switching), `FAST` (irrelevant CPU speed
control), `MONITOR` (no machine-language monitor). **`SPRDEF` joins them** on the same
reasoning: it is not a programmable verb but an interactive full-screen sprite editor, driven
by single keystrokes and its own cursor. A program cannot call it usefully and this interpreter
does not own the screen it would take over. The three `SPRSAV` source forms are what replace it.

**The `libakgl` JSON layer turned out not to be in the way at all.** Group H was parked on
"check the sprite/actor API before filing", and the concern was that libakgl's sprites are
described by JSON documents that would be cumbersome to reach through BASIC.
`akgl_sprite_load_json()` is a thin wrapper over `akgl_spritesheet_initialize` +
`akgl_sprite_initialize` + writes to public struct fields, and every field it fills from a
document — frame list, animation speed, loop flags, state-to-sprite map — is something a
Commodore sprite does not have. So `src/sprite_akgl.c` builds the same four objects directly.
The one field that *did* survive into the verb syntax is the spritesheet's filename:
`SPRSAV "ship.png", 1` goes through `akgl_path_relative()` and `akgl_spritesheet_initialize()`,
which is the same pair of calls the JSON loader makes.

Also on the queue, from the reference's own defect list:

- ~~**Multiple statements per line**~~ **Done.** `akbasic_parser_parse()` consumes a run of
  `COLON` tokens before each statement and hands the caller a NULL leaf when nothing followed
  them, which is how an empty statement — a trailing separator, or `::` — stays legal rather
  than becoming an error. `tests/parser_commands.c` counts statements per line;
  `tests/language/statements/multiple_per_line.bas` asserts what actually runs.

  **One thing about it needed a decision rather than a transcription**, and it is recorded as
  deviation 31 in §5: BASIC 7.0 scopes everything after `THEN` to the condition, so
  `IF C THEN A : B` must run neither `A` nor `B` when `C` is false. The parser takes exactly one
  statement per arm, so the rest of the line reaches the statement loop as ordinary statements
  and the branch has to tell the loop whether to run them.

  **A known limitation, not a defect:** a whole `FOR`/`NEXT` on one line
  (`FOR I# = 1 TO 3 : PRINT I# : NEXT I#`) does not loop. The block structure is the
  reference's `waitingForCommand` model (§1.6), which skips forward *by source line* to the verb
  it is waiting for, so a `NEXT` on the same line as its `FOR` is never reached. Fixing it means
  restructuring control flow to work on statements rather than lines, which is a deliberate
  piece of work and wants its own commit. Group A's `DO`/`LOOP` will meet the same wall.
- ~~**Array references in parameter lists**~~ **Done**, and it turned out to be §6 item 13 a
  third time rather than a separate defect. An identifier's subscript list moved to `.expr`, and
  `akbasic_ASTLeaf` grew a `next` field so an argument list chains through a link of its own.
  That last part is the real fix: the reference chains arguments through each argument's own
  `.right`, and *every* leaf type that can be an argument already uses `.right` for something,
  so moving one operand out of the way only shifted the collision along. Covered by
  `tests/language/arrays_in_parameter_lists.bas` and `tests/runtime_evaluate.c`.

### What a demoscene program wanted and could not have

`examples/megademo/megademo.bas` was written to push the interpreter to its edges, and these are
the edges it hit. **None of them blocked the demo** — every one has a workaround and the program
carries all six — but each workaround is a routine every future game will carry too, and that is
the argument for the verb.

Ordered by how much BASIC each one would delete: `RND` and `ASC` (#16), the unwritable palette
(#17), `GSHAPE`'s missing blend modes (#18), no way to ask whether `PLAY` has drained (#19),
`PLAY` being monophonic (#20), `DATA` being too small a pipe for assets (#21), and the `TI#` spin
that starves the audio queue (#22).

**The last of those is the one worth reading before writing a game loop.** Polling `TI#` does not
merely waste CPU: the host calls `settime()` once per `runtime_run()` batch, so a batch of spin
statements drops the note release rate below what a sixteenth-note tune needs, the queue never
reclaims slots until it drains completely, and the backlog compounds until `PLAY queue is full`.
Reproduced both ways in isolation. Sleep a frame instead.

---

## 5. Deliberate deviations from the reference

Keep this list current. Most of these change structure without changing observable output;
the ones that *do* change output say so and carry the golden file they moved.

The bar has dropped since this list was started. It used to be "defensible against the golden
suite", because matching the Go implementation byte for byte was goal 1's headline claim. That
implementation is now deprecated (§0.1), so the bar is the ordinary one: defensible on its own
merits, recorded here, and tested.

1. Reflection → static dispatch table (§1.1).
2. Go maps → fixed open-addressed tables (§1.3).
3. Unbounded `new(BasicEnvironment)` → pool with release (§1.4).
4. Hardcoded stdout+SDL mirror → text sink backend (§1.5).
5. `run()` owns the process → `step()` / bounded `run()` (§1.6).
6. `panic()` → `FAIL_RETURN`; no library call terminates the process (§1.6).
7. `debug.PrintStack()` on parse error → the `akerr` stack trace only (§3.1 of the original plan).
8. `BasicEnvironment.eval_clone_identifiers` deleted as dead state (§4.2 of the original plan).
9. `BasicValue.name` and `BasicEnvironment.update()` deleted as dead: nothing ever writes the
   field a non-empty string, and `update()` — its only reader — has no callers.
10. The `DEF`-statement bootstrap is gone. The reference declares every builtin by *running a
    BASIC program of `DEF` lines through the interpreter* at startup and then nulling out the
    expressions (`basicruntime_functions.go:14`); here a builtin's name, arity and handler are
    a row in the dispatch table, and `MOD`, `SPC` and `STR` are ordinary native handlers. This
    removes the need to run the interpreter before the interpreter is ready.
11. Undefined behaviour the reference reaches by a defined route is refused rather than
    inherited: a shift count outside 0..63, a negative string multiplier, and integer division
    by zero all raise. Go defines all three (or panics); C does not. No golden case exercises
    any of them, so observable behaviour is unchanged.
12. `CommandEXIT` clears the pending `NEXT` wait before popping. The reference does not, which
    leaves the parent waiting for a `NEXT` that never arrives (§6 item 8) — in C that is a hang
    rather than a misbehaviour, and no golden case depends on it.

### Deviations in the verbs the reference never implemented

Items 1–12 above are deviations *from ported code*. These are deviations from **Commodore
BASIC 7.0**, in verbs the reference lists as unimplemented and which therefore had no Go
behaviour to port. They matter to somebody typing in a listing out of a C128 manual.

13. **Hardware verbs reach a device through a backend record, and refuse when there is none.**
    `akbasic_GraphicsBackend`, `_AudioBackend` and `_InputBackend` are records of function
    pointers on the runtime; all three may be `NULL`, which is what the current stdio-only
    standalone driver gives them. That is correct for a default build and unfinished for an
    `AKBASIC_WITH_AKGL` build; see §3. A verb that needs a device it was not given raises
    `AKBASIC_ERR_DEVICE` naming itself. `COLOR`, `LOCATE`, `SCALE`, `ENVELOPE`, `TEMPO` and
    `VOL` deliberately do *not* require one — they change interpreter state, so a program can
    configure itself before the host lends it a renderer.

14. **`CIRCLE` is a polygon, always.** BASIC 7.0's `CIRCLE` takes two radii, a start and end
    angle, a rotation and a degree increment, which makes it an inc-degree polygon by
    definition. `akgl_draw_circle` exists and is deliberately **not** used: it draws one
    radius, full sweep, unrotated, so it could serve only the case where every optional
    argument is defaulted — and a shape that changed character depending on whether the two
    radii happened to be equal is worse than one that is uniformly a polygon.

15. **`SSHAPE` stores a handle in the string, not the pixels.** A real C128 packs the
    region's bitmap into the string variable. Here a value's string is a fixed 256 bytes
    (§1.2) and a saved region is a device surface, so the variable gets `SHAPE:<n>` and the
    surface stays in a fixed pool on the backend. `GSHAPE` accepts only a string carrying that
    prefix, so a hand-written one is refused rather than pasting an unrelated slot. **What
    this costs:** a shape cannot be written to disk, cannot be concatenated, and `LEN` of it
    is not its size. Nothing in BASIC does any of those to a shape string except a program
    deliberately poking at it.

16. **`BOX` cannot fill at all, and the plan for it is to spell fill as a negative angle.**
    7.0's last argument selects outline or fill and sits *after* the rotation, which would
    make a filled box a seven-argument call — one more than `akbasic_cmd_box()` collects.
    Spelling it as a negative rotation instead is the intended answer and **is not
    implemented**: today a rotation of zero outlines through the renderer's rectangle and any
    other rotation, negative included, draws four lines.

    **This entry used to claim in bold that it fills**, with the body then saying it was
    filed rather than implemented — a headline that contradicted its own paragraph, which is
    exactly how a reader ends up believing a feature exists. Found by writing a
    documentation figure for `BOX` and getting an outline back. `PAINT` is the fill a
    program has today.

    **`akbasic_GraphicsBackend::filled_rect` is dead from the language's side** as a direct
    consequence: `src/graphics_akgl.c` implements it and `tests/mockdevice.h` records it, but
    no BASIC verb reaches it. It is the entry point this fix would call, so it is waiting
    rather than unused — worth knowing before somebody tidies it away.

17. **`GRAPHIC` records its mode but honours only one consequence of it.** 7.0's five modes
    differ in bitmap resolution and in whether the bottom of the screen stays text. Neither
    means anything against a host's renderer, whose size the interpreter does not own. The
    mode is stored, an out-of-range one is refused because that is a typo worth catching, and
    the one observable rule is that mode 0 is text. The mode is readable as `RGR(0)`, which
    is 7.0's whole `RGR` and the one field of ours that is.

18. **A coordinate reaching a backend is a device pixel, and the whole of the host's window
    is reachable from BASIC.** This used to read "coordinates are BASIC's 320x200 space and
    scaling to the window is the host's job", on the reasoning that the interpreter cannot
    ask the renderer how big it is without owning it. **That reasoning was wrong twice over**,
    which is what §8 item 9 came to say.

    It was wrong about the mechanism: not owning a thing is no bar to *asking* it, and the
    backend record is how everything else here asks. `akbasic_GraphicsBackend` grew a `size`
    entry point, `require_graphics()` calls it before every verb that draws -- so a resized
    window is honoured between two statements rather than at attach -- and 320x200 became
    the fallback for a backend that leaves `size` NULL. It is the record's one optional
    entry point, so a host written against the old header keeps working and gets exactly the
    behaviour it used to get.

    And it was wrong about the description: nothing ever stretched anything. With `SCALE`
    off a coordinate was passed straight to `akgl_draw_*` as a pixel address, so an 800x600
    window drew a C128 listing into its top-left 320x200 corner and left the rest unused.
    The documentation described a coordinate transform that did not exist.

    **What changed observably** is `SCALE`, which now maps user coordinates onto the device
    rather than onto the constants, and `RGR(1)` / `RGR(2)`, which report the drawing
    surface's width and height so a program can use a window whose size it did not choose.
    A C128 listing draws in the corner as it always did; `SCALE 1, 319, 199` gives it the
    whole window.

    **One fix rode along, in the same line of code and too small to defer.** `SCALE` mapped
    `xmax` onto the *width*, which put the user space's far corner one pixel past the
    surface: `SCALE 1, 319, 199` then `DRAW 1, 319, 199` drew nothing at all. It maps onto
    the last pixel now, which is what makes that sentence above true rather than nearly
    true. `tests/graphics_verbs.c` and `tests/akgl_backends.c`, the latter against a
    128x128 target chosen because it is *smaller* than the old constants -- a `SCALE` still
    dividing by them misses it entirely rather than landing somewhere plausible.

19. **`PLAY` does not block.** On a C128 `PLAY` holds the program until the last note ends.
    §1.6 forbids that outright, so `PLAY` parses the string into a fixed queue and returns;
    `akbasic_runtime_step()` releases one note at a time against whatever time the host last
    passed to `akbasic_runtime_settime()`. **What this changes for a program:** the statement
    after a `PLAY` runs immediately rather than a bar later, so a listing that relied on `PLAY`
    for timing will race ahead. A program that wants to wait should test the queue rather than
    assume the verb waits for it.

20. **The host owns the clock, and an unset clock rushes the music.** The library reads no
    clock — it owns no loop and must not block. A host calls `akbasic_runtime_settime()` once a
    frame; the standalone driver calls it every step off `CLOCK_MONOTONIC`. Left unset it reads
    zero forever, so every duration has already expired and the queue drains as fast as
    `step()` is called. Audible, deterministic, and never a hang, which is the right way for
    that to fail.

21. **`PLAY`'s `M` (measure) is a no-op, and `SOUND`'s sweep runs once rather than
    oscillating.** `M` synchronises the three voices on a C128; with one sequential queue there
    is nothing to synchronise, and a listing full of them should still play, so it is accepted
    and ignored.

    The sweep *used* to be refused outright — there was no `akgl_audio_*` equivalent and faking
    one would have tied audible pitch to how often the host calls us. `libakgl` 0.3.0 added
    `akgl_audio_sweep()` and `SOUND voice, freq, dur, dir, min, step` now reaches it. What does