akbasic/docs/14-architecture.md

# 14. Architecture

This chapter is for whoever has to understand the interpreter from the inside: to
embed it, to debug something it did, or to change it. Everything before this chapter
describes the language. This one describes the machine that runs it.

It is deliberately not a repeat of the API. **The headers under `include/akbasic/` are
the authority on every function's contract** — `doxygen Doxyfile` renders them, and each
one carries its parameters, its return, and the errors it raises. Where a rule is
subtle, the header comment states it at more length than a chapter should. What is here
instead is the shape: what talks to what, in what order, and why it was built that way.

| Question | Read |
|---|---|
| What does this function do? | the header, or the Doxygen it renders to |
| What does this verb do? | [Chapter 11](11-verb-reference.md), and `src/runtime_*.c` |
| Why is it built like this? | this chapter |
| What are the conventions for changing it? | [`MAINTENANCE.md`](../MAINTENANCE.md) |
| What is currently wrong with it? | [`TODO.md`](../TODO.md) |

## Three libraries and a driver

The build separates the interpreter from everything that could own a screen, and the
separation is in the build graph rather than in a comment.

```text
  +---------------------------+     +---------------------------+
  |  basic (src/main.c)       |     |  your game                |
  |  argv, QUIT,              |     |  window, renderer,        |
  |  FINISH_NORETURN          |     |  frame loop               |
  +-------------+-------------+     +-------------+-------------+
                |                                 |
  +-------------v-------------+                   |
  |  akbasic_frontend         |                   |  a host that already
  |  SDL window, font, event  |                   |  has a renderer skips
  |  pump, 256 steps a frame  |                   |  this target entirely
  +-------------+-------------+                   |
                |                                 |
  +-------------v---------------------------------v-------------+
  |  akbasic_akgl   sink | graphics | audio | input | sprites    |
  |                 function-pointer records that draw and play  |
  |                 through a renderer somebody else created     |
  +------------------------------+------------------------------+
                                 |
  +------------------------------v------------------------------+
  |  akbasic        scanner -> parser -> evaluator, the pools,   |
  |                 the verb table, values, environments         |
  |                 no SDL, no malloc, no exit(), no globals     |
  +------------------------------+------------------------------+
                                 |
  +------------------------------v------------------------------+
  |  libakstdlib   /   libakerror                                |
  +-------------------------------------------------------------+
```

| Target | What it is | A game links it? |
|---|---|---|
| `akbasic` | The interpreter. No SDL, nothing that terminates the process | Always |
| `akbasic_akgl` | The sink and the four device backends, drawing through *your* renderer | If you want them |
| `akbasic_frontend` | The standalone program's host: creates the window, owns the loop | **No.** You are the host |
| `basic` | The driver: argv, `QUIT`, and the one `FINISH_NORETURN` in the tree | — |

Where a thing lives:

| Area | Source |
|---|---|
| Tokens, AST leaves | `src/grammar.c`, `include/akbasic/grammar.h` |
| Scanner | `src/scanner.c` |
| Parser | `src/parser.c`, and the verbs with their own syntax in `src/parser_commands.c` |
| The step loop, evaluation, pools | `src/runtime.c` |
| Verb and function implementations | `src/runtime_*.c`, one file per verb group |
| The dispatch table | `src/verbs.c` |
| Scopes and block state | `src/environment.c` |
| Values, variables, symbol table | `src/value.c`, `src/variable.c`, `src/symtab.c` |
| Text sinks | `src/sink_stdio.c`, `src/sink_tee.c`, `src/sink_akgl.c` |
| Device backends | `src/graphics_akgl.c`, `src/audio_akgl.c`, `src/input_akgl.c`, `src/sprite_akgl.c` |

## One struct holds everything

There is no file-scope mutable state anywhere in the library. Every pool, every cursor
and every piece of subsystem state hangs off one `akbasic_Runtime`, which the caller
owns and passes by pointer. Two interpreters in one process do not interfere, which is
the whole reason for the rule.

It is several megabytes, because the pools are inline. Put it in static storage or in
your own state — never on a default stack. `src/main.c`, `tests/harness.h` and both
examples all do the same thing for the same reason.

`akbasic_Runtime` carries five kinds of thing, and it is worth knowing which is which
before you go reading it:

| Kind | Fields |
|---|---|
| The program | `source[]`, indexed **by line number**, and `sourcepath` |
| Pools | `environments[]`, `variables[]`, `functions[]`, `valuepool` |
| Execution state | `mode`, `run_finished_mode`, `environment`, `errclass`, `skiprestofline`, `trace`, `stopped` |
| Borrowed devices | `sink`, `graphics`, `audio`, `input`, `sprites` — any of the last four may be `NULL` |
| Per-subsystem BASIC state | `gfx`, `audio_state`, `input_state`, `sprite_state`, `format_state`, `console_state`, `data_state`, `disk_state` |

That last row is the one people ask about. `COLOR`, `TEMPO`, `SCALE`, the `PUDEF`
characters and the eight sprites' positions live on the *runtime*, not on the device
that renders them, because they are the program's state and not the hardware's. A host
that swaps one renderer for another does not expect the script's colours to go with it,
and `RSPPOS` answers correctly with no sprite device attached at all.

`source[]` being indexed by line number is worth pausing on. A line's number *is* its
array slot, so `GOTO 500` is one assignment — `environment->nextline = 500` — and no
search. Blank slots are skipped by the step loop. That is why line numbers are capped at
9998 and why a nine-line program still costs a 9999-entry array.

It is also why **a loaded line does not have to arrive with a number**. Execution needs a
slot, not a number somebody typed, so a line that comes without one is simply given the
slot after the last line filed. `akbasic_runtime_file_line()` is the one place that rule
lives, shared by `akbasic_runtime_load()`, `RUNSTREAM` and `DLOAD`; the step loop, the
branch verbs, the four prescans and `RENUMBER` never learn that anything changed, because
all of them already worked in slots. `akbasic_SourceLine::numbered` records which kind a
line was, and exactly one thing reads it — `akbasic_runtime_check_targets()`, which
refuses `GOTO 100` when line 100 is a number nobody wrote.

The prompt is deliberately outside all of this: `process_line_repl()` files a line only
when it *had* a number, because there the number is what separates program text from a
statement to run now.

## One step

`akbasic_runtime_step()` is the whole loop, unrolled to a single iteration. The
reference's `run()` did not return until the program quit; here the caller owns the loop
and the library owns exactly one turn of it.

```text
  akbasic_runtime_step(rt)
    |
    +-- akbasic_play_service()        release the next queued note if its time is up
    +-- akbasic_sprite_service()      advance continuous MOVSPR motion
    +-- akbasic_collision_service()   look for collisions where the sprites now are
    |
    +-- mode == QUIT ? ------------------------------------> return
    |
    +-- akbasic_input_service()       GETKEY waiting?  ----->  return  (no line runs)
    +-- akbasic_console_update_clock()
    +-- akbasic_console_service()     SLEEP or WAIT holding? -> return
    |
    +-- akbasic_runtime_zero()        reset the per-line value pool
    +-- akbasic_scanner_zero()        reset the scanner cursor
    |
    +-- switch ( mode )
    |     RUNSTREAM -> process_line_runstream()   read a line, file it
    |     REPL      -> process_line_repl()        read a line, run it or file it
    |     RUN       -> service_interrupts()       enter a handler if one is due
    |                  process_line_run()         run source[nextline]
    |
    +-- errclass set ?  -> set_mode(run_finished_mode)
```

Three things in that order are deliberate.

**The service calls run before the `QUIT` check.** A program's last notes still come out
while a host keeps calling `step()` after the script has ended.

**They run before the blocking checks, too.** A program sitting in `GETKEY` still has its
music paced and its sprites moved. `GETKEY` holding the program means *this step
executes no source line* — it does not mean the step does not return. It always returns.

**Interrupts are serviced between lines and nowhere else.** A handler entered mid-statement
would have to return into the middle of a line, and the parser keeps no state that could
resume there.

`akbasic_runtime_run(rt, n)` is `step()` in a `while` with a budget: at most `n` steps,
then return regardless. That bound is the only thing standing between a script containing
`10 GOTO 10` and your frame rate. `n <= 0` means unbounded, which is right for a test and
wrong for a game. The SDL frontend uses 256 (`AKBASIC_FRONTEND_STEPS_PER_FRAME`); the
stdio driver uses 1, because it wants to refresh the clock between steps.

**That budget is visible to a script, and drawing is where it shows.** The frontend
presents the frame when `run()` comes back, and presenting discards the drawing buffer —
so a sequence of drawing verbs longer than one budget is cut in half by the present in
the middle of it, and an `SSHAPE` afterwards captures only what was issued since. Not a
transient artefact: a torn capture, over whatever the frame before left behind.

A script cannot read the budget, but it can *see* it: `akbasic_runtime_settime()` is
called once per frame by the host, so `TI#` changes on the first step of a batch and
nowhere else. Spinning until it changes is the only frame synchronisation this dialect
has, and it is what
[Chapter 18](18-tutorial-breakout-artwork.md#step-4-find-the-frame-boundary) is built on.
A host that gives the interpreter a larger budget makes more drawing fit; one that never
calls `settime()` takes the synchronisation away entirely.

Time comes in from outside. `akbasic_runtime_settime(rt, ms)` is how the interpreter
learns what time it is; it reads no clock, because it owns no loop and must not block. A
host that never calls it leaves time frozen at zero, and every duration then expires on
the step after it starts — audible, but never a hang. That is the intended way for it to
fail.

## Four modes

```text
                    akbasic_runtime_start(rt, mode)
                                |
            +-------------------+-------------------+
            |                                       |
            v                                       v
       RUNSTREAM                                  REPL <---------------+
    read a line, file it,                 read a line: file it if it   |
    execute nothing                       has a number, run it if not  |
            |                                       |                  |
            | end of input                RUN, CONT |                  |
            +--------------->  RUN  <---------------+                  |
                                |                                      |
                                | END, STOP, a BASIC error, or         |
                                | running off the end of the source    |
                                v                                      |
                        run_finished_mode ---------- == REPL ----------+
                                |
                                | == QUIT, or the QUIT verb, or
                                v end of input at the prompt
                               QUIT
```

| Mode | What one step does | How it leaves |
|---|---|---|
| `AKBASIC_MODE_REPL` | Read one line from the sink. With a line number, file it; without one, **run it now** | `QUIT` verb, or end of input |
| `AKBASIC_MODE_RUN` | Execute `source[nextline]` | Running off the end, `END`, `STOP`, or a BASIC error |
| `AKBASIC_MODE_RUNSTREAM` | Read one line from the sink and file it. Executes nothing | End of input, which switches to `RUN` |
| `AKBASIC_MODE_QUIT` | Nothing | — |

`run_finished_mode` decides where a finished program lands. `akbasic_runtime_start(rt,
AKBASIC_MODE_REPL)` sets it to `REPL`, so a program that ends drops back to a prompt;
anything else sets it to `QUIT`, so `basic program.bas` exits. It is one field, and it is
the whole difference between an interactive session and a script runner.

**`akbasic_runtime_set_mode()` is not just an assignment.** Entering `REPL` prints
`READY`. Entering `RUN` does four prescans of the whole program first:

- **Labels.** Every `LABEL` in the source is filed before anything executes, textually
  rather than by parsing. Without it a label would exist only from the moment its `LABEL`
  statement ran, so `GOTO` could reach backwards and never forwards — and an interrupt
  handler, which by definition sits where normal flow does not fall, could not be named
  by label at all.
- **`DATA` items.** `READ` walks a cursor along a list built before the program runs, so a
  `DATA` line above its `READ` is found.
- **`TYPE` declarations.** A declaration has to be in effect wherever control goes, so
  `DIM P@ AS RECT` cannot run before `RECT` exists even if a branch skipped the lines that
  declared it.
- **Branch targets.** The only one that reads nothing in and merely refuses: a numeric
  `GOTO`, `GOSUB`, `RUN`, `RESTORE`, `TRAP` or `COLLISION` target naming a line the program
  did not number. It shares `RENUMBER`'s walk in `src/renumber.c` rather than repeating it.

Every path into a run — `akbasic_runtime_start()`, the `RUN` verb, `CONT`, and the end of
a `RUNSTREAM` load — goes through that one function, which is why the prescans live there
and not in any of the four callers.

All four run inside one `ATTEMPT`, because **a prescan failure is the program's mistake
and not the host's** and has to leave as a BASIC error line rather than a raised context.
Three of them report against whichever line the loader stopped on and put the real one in
the message text; the branch-target scan points `environment->lineno` at the line it is
walking so the `? N :` prefix is right. `TODO.md` §5 item 64 records the difference.

The REPL's split between *file it* and *run it now* is one boolean: the scanner sets
`hadlinenumber` when the line it just read began with a number. A line typed with a
number is program text; a line typed without one is direct mode and runs immediately.

## From a line of text to an effect

Nothing is compiled and nothing is cached. Every time a line executes it is scanned and
parsed again, from the source text, into per-line pools that are reset on the way in.

```text
   source[42]  "IF A# = 5 THEN PRINT \"FIVE\""
        |
        |  akbasic_scanner_scan()          verb names via the dispatch table;
        v                                  no keyword maps of its own
   environment->tokens[32]   COMMAND(IF) IDENT_INT(A#) ASSIGNMENT LITERAL_INT(5)
        |                    COMMAND(THEN) COMMAND(PRINT) LITERAL_STRING(FIVE)
        |
        |  akbasic_parser_parse()          one statement per call; the caller
        v                                  loops until the tokens are spent
   environment->leaves[32]        BRANCH
        |                        /      \
        |                  (= A# 5)   COMMAND PRINT
        |                                    |
        |                             LITERAL_STRING "FIVE"
        |
        |  akbasic_runtime_interpret()      suppressed while this scope is
        v                                   skipping forward to a verb
   akbasic_runtime_evaluate()   switch on leaf type; a COMMAND leaf looks its
        |                       handler up in the table and calls it
        v
   verb->exec()  ->  the sink, a device backend, or a variable
```

The statement loop lives in `process_line_run()` and `process_line_repl()`, not in the
parser: a line can hold several statements separated by colons, so the caller loops on
`akbasic_parser_is_at_end()`. **`akbasic_parser_parse()` may return `NULL` on success** —
that is a line that was nothing but separators — and a caller that does not skip it will
hand `NULL` to the interpreter.

`skiprestofline` is how a branch tells that loop to stop. BASIC 7.0 scopes everything
after `THEN` to the condition, but the parser takes only *one* statement per arm and the
rest arrive at the statement loop as ordinary top-level statements. So the branch raises a
flag and the loop obeys it. The rule is not "skip when false": the remainder belongs to
whichever arm was written last, so it is skipped exactly when *that* arm is the one not
taken. [Chapter 4](04-control-flow.md) has the truth table; the `AKBASIC_LEAF_BRANCH` case
in `akbasic_runtime_evaluate()` has the code.

Two details in that diagram catch people out:

**A lone `=` is scanned as `ASSIGNMENT`, not as equality.** The scanner cannot know
whether it is looking at a statement or a condition. The parser can: `akbasic_Parser`
carries a `comparing` flag, set around a condition and cleared afterwards, and while it is
set the relation rule accepts `ASSIGNMENT` as a seventh operator and rewrites it to
`EQUAL`. Outside a condition `=` has to stay an assignment or `FOR I# = 1 TO 5` never
initialises its counter.

**The token and leaf numbering is the Go reference's, on purpose.** `grammar.h` keeps the
original values so a debugging session against either implementation reads the same.

`akbasic_leaf_to_string()` renders a tree in prefix form — `(+ A# 42)`, `(group (+ A# 42))`
— which is the fastest way to see what the parser actually built. It is a plain function,
so you can call it from a debugger against any leaf pointer you have.

## The dispatch table

The Go reference resolved a verb by reflection: `MethodByName("Command" + NAME)`. C has
no reflection and none is being added. All three of its lookups — verbs, functions, and
verbs with their own parse path — collapse into one sorted table in `src/verbs.c`.

```c excerpt=include/akbasic/verbs.h
typedef struct
{
    const char *name;
    akbasic_TokenType tokentype;
    int arity;
    akbasic_ParseHandler parse;
    akbasic_ExecHandler exec;
} akbasic_Verb;
```

One row per name, and both handlers are optional:

| Field | Meaning |
|---|---|
| `tokentype` | What the **scanner** gives this name. It has no keyword maps of its own |
| `arity` | Argument count for a function; `-1` where it does not apply |
| `parse == NULL` | The verb's rval parses as a plain expression |
| `parse != NULL` | The verb has its own syntax — `src/parser_commands.c` |
| `exec == NULL` | The token is consumed by another verb's parser and never evaluated alone: `THEN`, `ELSE`, `TO`, `STEP` |

`AKBASIC_TOK_COMMAND_IMMEDIATE` marks a verb the REPL may run against a line that *does*
carry a number — `RUN`, `LIST`, `NEW`, `DLOAD`. Everything else typed with a number is
filed as program text.

**The table is searched with `bsearch`, so it must stay sorted.** A mis-sorted row does
not fail to compile; it silently becomes an unfindable verb, and the symptom is
`Unknown command PRINT` a long way from the cause. `tests/verbs_table.c` asserts the
ordering, which is the only reason that is a safe thing to say.

## Nothing is allocated

Every object comes from a fixed pool inside the runtime. Exhausting one is a diagnosable
error naming the pool, not a crash and not a slow leak.

| Pool | Size | Lives on | Exhaustion says |
|---|---|---|---|
| `AKBASIC_MAX_SOURCE_LINES` | 9999 | runtime | `Line number N is outside 0..9998` |
| `AKBASIC_MAX_ENVIRONMENTS` | 32 | runtime | `Environment pool exhausted at line N (32 in use)` |
| `AKBASIC_MAX_VARIABLES` | 128 | runtime | `Maximum runtime variables reached` |
| `AKBASIC_MAX_FUNCTIONS` | 64 | runtime | `Maximum function definitions reached` |
| `AKBASIC_MAX_ARRAY_VALUES` | 4096 | runtime (`valuepool`) | `Array of N elements does not fit in the M remaining value slots` |
| `AKBASIC_MAX_TOKENS` | 32 | **environment** | `Line N has more than 32 tokens` |
| `AKBASIC_MAX_LEAVES` | 32 | **environment** | `No more leaves available` |
| `AKBASIC_MAX_VALUES` | 64 | **environment** | `Maximum values per line reached` |

The numbers are in `include/akbasic/types.h`, transcribed from the reference's `main.go`
plus three the Go version did not need because it called `make()`.
[Chapter 13](13-differences.md) states the same budget from a BASIC programmer's side.

The per-environment three are reset at the top of every line, which is what makes
"roughly 16 operations per line" a real limit and not a leak: a line that uses 30 leaves
is fine, and a line that needs 33 tokens is refused. Because they are per environment
rather than per runtime, a `FOR` body running inside a pushed scope gets its own 32.

`valuepool` is a bump allocator for array storage and it does not release. Nothing in
BASIC destroys a variable, so there is nothing to release *to* — but re-`DIM`ming an array
larger takes fresh slots and abandons the old ones, so a program that does that in a loop
will exhaust the pool. Bounded and diagnosable, which is the point.

## A scope is also the block state

`akbasic_Environment` does two jobs at once, and the second one is the surprising one. It
is a variable scope, chained to its parent — and it is the in-flight state of whatever
block structure is executing: the `FOR` bounds and step, the `DO`/`LOOP` condition, the
`GOSUB` return line, the `READ` cursor, and the line counters.

| What pushes a scope | What pops it |
|---|---|
| `FOR` — **during parsing**, not execution | the `NEXT` whose condition is met, or an `EXIT` |
| `GOSUB` | `RETURN` |
| A call to a multi-line user function | that function's `RETURN` |
| An interrupt firing | the handler's `RETURN` |

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
only after parsing is finished — because the loop body is scanned against the *parent's*
token stream. If you are chasing a scope that appeared earlier than you expected, that is
why.

### `waitingForCommand`, and why loops work at all

A loop's condition is evaluated at the *bottom* of the structure, which leaves an obvious
problem: how does a zero-iteration `FOR` avoid running its body once? The answer is a
string on the environment.

```text
   10 FOR I# = 5 TO 1          FOR pushes a scope, evaluates the condition,
   20   PRINT "NEVER"          finds it already met, and calls
   30 NEXT I#                  wait_for_command(env, "NEXT")

   step: line 20   interpret() sees the scope is waiting, and the leaf is not
                   COMMAND "NEXT" -> evaluates nothing, returns static true
   step: line 30   the leaf *is* COMMAND "NEXT" -> runs. NEXT stops the wait,
                   pops the scope, and hands nextline back to the parent
```

`akbasic_runtime_interpret()` is where that is enforced, and it is the first thing it
does. Five places arm a wait, and between them they are the whole of block structure:

| Verb | Waits for | Because |
|---|---|---|
| `FOR` | `NEXT` | the condition was already met — zero iterations |
| `DO WHILE` / `DO UNTIL` | `LOOP` | the same, at the top of a `DO` |
| `EXIT` | `NEXT` or `LOOP` | where the loop *ends* is not known until a `NEXT` has run once |
| `IF ... THEN BEGIN` | `BEND` | the arm not taken has to skip *lines*, and `skiprestofline` only reaches the end of this one |
| a multi-line `DEF` | `RETURN` | the definition must not execute its own body |

Three consequences follow, and all three are things people report as bugs:

- **Block skipping walks source *lines*.** A whole `FOR ... NEXT` written on one line does
  not loop, because there is no next line for the wait to skip to.
- **A `FOR` counter does not survive its loop.** It lives in the loop's own scope. On a
  C128 it keeps its final value.
- **A host must use `akbasic_runtime_global()`.** `akbasic_environment_get()` creates in
  whatever scope is active, and a script suspended part-way through a bounded
  `akbasic_runtime_run()` is usually inside a `FOR` or `GOSUB` body — so the script reads
  the value correctly inside the loop and gets `0` immediately after it, with nothing
  raised anywhere.

## Values

`akbasic_Value` carries its string **inline**, not behind a pointer, so a copy is a struct
assignment with no allocator, no refcount and no lifetime question. It costs 256 bytes per
value; that is the trade, and it is recorded in `TODO.md`.

Type comes from the identifier's suffix and nothing else: `A#` integer, `A%` float, `A$`
string, and a bare name with no suffix is a *label*. That is `akbasic_leaf_identifier_type()`,
and it is why `ER` and `EL` are spelled `ER#` and `EL#` here.

One field on the runtime changes how identifiers evaluate. `eval_clone_identifiers` is
normally true, and evaluating `A#` then yields a clone drawn from the per-line value pool.
`POKE` and `POINTER` need the address of the real storage, so they clear it around their
own evaluation. If you are debugging an assignment that wrote to the wrong place, that
flag is the first thing to check.

## Structures are laid out exactly as arrays are

The whole storage model falls out of one decision: **a `TYPE` is declared**, so an
instance has a known slot count before the program runs.

That means a structure needs no pool of its own. `DIM R@ AS RECT` calls the same
`akbasic_valuepool_take()` that `DIM A#(10)` calls, and the variable's `values` run *is*
the instance. A field access is offset arithmetic against an offset the type descriptor
already knows. A nested value field **flattens into its container's run** — a `SEGMENT`
holding two `COORD`s and a string is five slots, not three — which is why the nesting is
free rather than a second indirection.

```text
    DIM S@ AS SHAPE            SHAPE: NAME$, ORIGIN@ AS COORD, AREA%
                               COORD: X#, Y#

    variable S@
      structtype ──► type table entry SHAPE (slotcount 4)
      values ──────► ┌────────┬────────┬────────┬────────┐
                     │ NAME$  │  X#    │  Y#    │ AREA%  │
                     └────────┴────────┴────────┴────────┘
                       off 0    off 1    off 2    off 3
                                └── ORIGIN@ is offset 1, two slots ──┘
```

`src/structtype.c` fills the table, and it does so **in three passes**, each for a case
the pass before cannot handle. Names first, so a field can refer to a type declared
further down. Then field lists, now able to resolve every reference. Then sizes, by
repeated resolution — a type whose fields are all sized can be sized, and repeating that
settles any legal ordering. **Whatever never resolves is a cycle of by-value containment**,
which is how "a `TYPE` cannot contain itself by value" is a diagnosis rather than an
assumption.

It is a *prescan*, run from `akbasic_runtime_set_mode()` beside the label and `DATA`
scans, for the reason all three are: a declaration has to be in effect wherever control
goes, including when a branch skips the lines that made it. The `TYPE` verb's whole job at
run time is to **jump past its own `END TYPE`**, because the field lines are declarations
and executing `W#` would evaluate a bare identifier and quietly create a global.

### Copy, and where it has to happen

A `STRUCT` value and a `POINTER` value carry the same thing: a type index and a base. What
differs is what *assignment* does with it.

**The copy cannot live in `akbasic_value_clone()`**, and this is the trap to know about.
Clone copies one slot, and one slot holds a *reference* to an instance rather than the
instance — so a structure going through clone would alias, which is precisely the
semantics the language does not have. `akbasic_environment_assign()` intercepts a
structure before that path and calls `akbasic_struct_copy()`, which walks the descriptor
and copies slot by slot. Deliberately not one `memcpy` of the run: a pointer field must
copy its reference where a value field must copy its slots, and only the descriptor knows
which is which.

Copy is therefore **deep through values and stops at pointers**, as it is for a C struct
holding a pointer. Since a `TYPE` cannot contain itself by value, copy depth is fixed by
the type graph before the program starts and no copy can recurse away. Only *rendering*
needs a runtime bound, because a pointer can make the graph cyclic — that is
`AKBASIC_MAX_STRUCT_DEPTH`, four, chosen so the bound bites before the 256-byte render
buffer does.

### A host structure is the same thing with its bytes somewhere else

`akbasic_host_register_type()` puts a host's C struct in the *same* table, so `PTR TO`,
copy-on-assign, `.` and `->` all work across the boundary with no second set of rules. The
only difference is where a field's bytes live, and that is carried by three members on the
field descriptor — `hostkind`, `hostoffset`, `hostwidth`.

A binding takes a **shadow run** of slots from the ordinary pool. A field read refreshes
its slot from host memory first; a field write converts back and stores. So the script
always sees current values and its writes always land, while everything else in the
interpreter goes on seeing one storage model. If you are debugging a host binding that
reads stale data, `akbasic_host_refresh()` is where to look.

**This is the one pointer the interpreter holds that it did not allocate.** Everything
else is pool-bounded; a binding whose instance has been freed is the only way to get a
wild pointer in here, which is what `akbasic_host_unbind()` is for.

## Errors come in two kinds, and the distinction is the point

```text
   a script's mistake                        the interpreter's mistake
   -----------------                         -------------------------
   PRINT 1/0, GOTO nowhere,                  pool exhausted, NULL argument,
   type mismatch, a refused verb             a sink that failed to write
        |                                          |
        v                                          v
   report_and_reraise()                       propagates out through
   writes "? 20 : RUNTIME ..." to the sink    akbasic_runtime_step()
        |                                          |
        v                                          v
   swallowed by process_line_run()            handed to the host, which
   or process_line_repl(); the run stops,     decides what to do. The
   the host is never told                     driver prints a stack trace
                                              and exits 1
```

A script's mistakes are the script's problem and your program keeps running. That is goal
3, and it is easier to get wrong than it looks: the direct-mode branch of
`process_line_repl()` once used a bare `PASS`, so a `VERIFY` against a file that did not
match — an ordinary user answer — tore down the driver with a stack trace.

The BASIC-visible line is `? <line> : <CLASS> <message>`, where the class is one of `IO`,
`PARSE`, `SYNTAX` or `RUNTIME`. The message is expected to end in a newline and the sink
adds another, **so an error line is followed by a blank one**. That is the contract, not an
accident, and the golden corpus depends on it.

`errclass` being set is what ends a run: `step()` sees it and switches to
`run_finished_mode`. Returning to a prompt clears it; quitting does not.

**`akbasic_runtime_error()` is the single choke point** — the one place a BASIC-visible
error is reported *and* the one place a run is stopped. That is not an accident of
factoring, it is what makes `TRAP` implementable: an armed trap turns both off in one
place. Nothing is printed, `errclass` stays clear so the step loop carries on, and the
handler is entered at the next line boundary by the same machinery `COLLISION` uses. If
you ever need to intercept an error class, that function is where to stand.

Interpreter errors carry a status from the `akbasic` band, 512–767, declared as an `enum`
in `include/akbasic/error.h` and named in `akbasic_error_register()`. `MAINTENANCE.md`
carries the coordinated range map across the whole dependency stack, and it is required
reading before adding a code.

**One gap worth knowing before it surprises you.** The `ATTEMPT` blocks that convert a
script's mistake into an error line are wrapped around *parsing* and *interpretation*,
not around *scanning*. A line with more than 32 tokens therefore escapes as an
interpreter error — the driver prints a stack trace and exits 1, and an embedding host is
handed a context for what is really a script's mistake. It is the same shape as the
`VERIFY` defect above, on a path that fix did not cover. Filed in `TODO.md`; until it is
closed, a host that cannot tolerate that should refuse over-long lines itself.

## Devices, and how a capability is withheld

The sink and the four device backends are records of function pointers plus whatever
state you hang off `self`. That is the house pattern for anything that varies, and it is
what keeps SDL out of the core: the whole test suite runs on a machine with no SDL
installed at all.

```text
   akbasic_runtime_set_devices(rt, graphics, audio, input, sprites)
                                  |        |      |      |
                          any of them may be NULL, and NULL is not
                          "do nothing" -- it is "refuse by name":

                          SOUND with no audio backend ->
                          "? 10 : RUNTIME ERROR SOUND needs an audio
                           device and this runtime has none"
```

A backend record with a `NULL` *entry point* behaves the same way, one verb at a time —
`CHAR` against a stdio sink that cannot move a cursor refuses rather than printing in the
wrong place. Nothing is ever silently ignored; that is the rule the whole device layer is
built to keep.

`akbasic_sink_init_tee()` composes two sinks into one, which is how the SDL build puts
`PRINT` in a window *and* on stdout. The second write belongs out here rather than inside
the interpreter — the reference hardcoded it, and that is exactly what made its output
untestable without a display.

[Chapter 10](10-embedding.md) is the practical side of all of this, with a complete host
loop.

## Interrupts

`COLLISION` and `TRAP` arm a slot; a device backend, the collision service, or
`akbasic_runtime_error()` calls `akbasic_runtime_raise_interrupt()`, which only records
that it fired. The handler is entered later, by `step()`, between two source lines.

Raising is cheap and safe to call every frame whether or not anything is armed — an
unarmed source records nothing — so a host does not have to ask what the script has
subscribed to before reporting a collision.

Entering one is a `GOSUB` the program did not write: a scope is pushed, its return line is
the line that was about to run, and the handler's `RETURN` pops back to it — so a handler
must end in `RETURN`, exactly as on a C128.

`handlerenv` does two jobs. It is the "a handler is running" flag, which is what stops a
collision that persists across the handler from recursing until the environment pool is
gone. And it is the identity `RETURN` compares against, so the flag clears on the `RETURN`
that leaves *this* handler rather than on the first `RETURN` of any `GOSUB` the handler
itself makes. A depth counter would have got that wrong.

## Debugging it

### What the language gives you

`TRON` prints each line's number in brackets, inline and with no newline, which is what a
C128 does:

```basic
10 TRON
20 FOR I# = 1 TO 3
30   PRINT I#
40 NEXT I#
50 TROFF
60 PRINT "DONE"
```

```output
[20][30]1
[40][30]2
[40][30]3
[40][50]DONE
```

Read that trace as evidence about the *loop*, not just about the lines: `[40][30]` says
`NEXT` sent control back to 30, and the missing `[20]` on later passes says the `FOR` line
is not re-entered. A trace that shows a line you expected to be skipped is a
`waitingForCommand` question; a trace that shows the right lines with the wrong output is
an evaluation question.

`HELP` re-displays the last error line, and that is the whole of what it does.

### Reading a stack trace

An interpreter-level error that nothing handled reaches the driver, which prints the
`akerror` trace on **stderr** and exits 1. Every frame is `file:function:line`:

```text
src/scanner.c:add_token:87: 515 (Out Of Bounds) : Line 10 has more than 32 tokens
src/scanner.c:akbasic_scanner_scan:414
src/runtime.c:akbasic_runtime_process_line_runstream:788
src/runtime.c:akbasic_runtime_step:1302
src/runtime.c:akbasic_runtime_run:1367
src/main.c:drive:94
src/main.c:run_stdio:130
src/main.c:main:203
src/main.c:main:214: akbasic terminated on an unhandled error 515 (Out Of Bounds)
```

The paths are `__FILE__` as your build spells it, so an out-of-tree build prints them
absolute. The top frame is where it was raised and the bottom is where it was reported.
The number is the status code — 512 and up is ours, and `include/akbasic/error.h` names
them. A code printing as `Unknown Error` means somebody added it to the `enum` and forgot
to name it in `akbasic_error_register()`.

Note what this trace is *not*: it is not on stdout, so a golden comparison never sees it,
and `? 10 : RUNTIME ERROR ...` is a different thing entirely — that one is the script's
error, on stdout, and the process exits 0.

### Under a debugger

Four breakpoints answer most questions:

| Break on | Answers |
|---|---|
| `akbasic_runtime_step` | Which mode, and what the step decided to do |
| `akbasic_parser_parse` | What the parser built — then render it |
| `akbasic_runtime_evaluate` | Every leaf, in evaluation order. Noisy; condition it on `expr->leaftype` |
| the verb's own `akbasic_cmd_*` | What arguments a verb actually received |

Useful expressions once you are stopped. `rt` is whatever your host calls the runtime; in
the standalone driver it is the file-static `RUNTIME`, so it is `p RUNTIME.mode` there:

```text
  p rt->mode                              1 REPL, 2 RUN, 3 RUNSTREAM, 4 QUIT
  p rt->environment->lineno               the line executing
  p rt->environment->nextline             the line that will execute next
  p rt->environment->waitingForCommand    "" or the verb being skipped forward to
  p rt->environment->parent               NULL means this is the root scope
  p rt->source[42].code                   the stored text of line 42
  p rt->errclass                          non-zero means the run is ending
  p *rt->environment->forNextVariable     the FOR counter, when there is one

  call akbasic_leaf_to_string(leaf, buf, sizeof buf)   render a subtree: (+ A# 42)
```

Walking `parent` from `rt->environment` gives you the scope stack, and it is the fastest
way to see that something pushed a scope and never popped it.

### Narrowing it with the suite

```sh norun
ctest --test-dir build --output-on-failure -R for_next     # one unit test
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
```

The unit tests build a runtime against memory buffers (`tests/harness.h`), so they can
assert on exact output without a terminal. `tests/mockdevice.h` gives the graphics, audio
and input verbs recording backends that log every call — which is how the device verbs are
tested at all, since they produce no stdout for a golden file to compare.

Two more builds, when the answer is not in the logic:

```sh norun
cmake -S . -B build-asan -DAKBASIC_SANITIZE=ON     # ASan + UBSan
cmake -S . -B build-cov  -DAKBASIC_COVERAGE=ON     # gcovr, and the 90% gate
```

`MAINTENANCE.md` covers the mutation harness and the discipline that goes with a fix:
revert it, confirm the test fails, restore it.

### Symptom to cause

| Symptom | Look at |
|---|---|
| `Unknown command PRINT` | The verb table's sort order. `tests/verbs_table.c` |
| `peek() returned nil token!` | The line ended before the parser expected it to — a missing operand or an unbalanced paren |
| A line ran that should have been skipped | `waitingForCommand` on the active scope, and `skiprestofline` |
| A line was skipped that should have run | The same two, in the other direction |
| A variable reads `0` right after a loop | It lived in the loop's scope. Use `akbasic_runtime_global()` from a host |
| `Environment pool exhausted` | A scope pushed and never popped — usually a `GOSUB` with no `RETURN`, or recursion |
| `Line N has more than 32 tokens` | The per-environment token pool. Split the line |
| Every duration expires instantly | The host never called `akbasic_runtime_settime()` |
| A verb refuses with "needs a ... device" | That backend is `NULL`, or the entry point it wanted is |
| The driver exits 1 with a stack trace | An *interpreter* error, not a script error. Read the top frame |

## Changing it

### Adding a verb

1. **One row in `src/verbs.c`**, in sort order. Pick `AKBASIC_TOK_COMMAND`, or
   `AKBASIC_TOK_COMMAND_IMMEDIATE` if the REPL should run it against a numbered line.
2. **A parse handler**, only if the syntax is not "the verb and one expression". Put it in
   `src/parser_commands.c` and leave the table cell `NULL` otherwise.
3. **An exec handler** in the `src/runtime_*.c` file for its verb group, with the
   signature from `include/akbasic/verbs.h` — `(runtime, expr, lval, rval, dest)` — and a
   prototype in the *private* `src/verbs.h`, where the table gets its declarations.
4. **A unit test** in `tests/`, registered in `AKBASIC_TESTS` in `CMakeLists.txt`, built as
   `akbasic_test_<name>`.
5. **A `.bas`/`.txt` pair** in `tests/language/`. Both kinds of test, because they answer
   different questions: one pins the C contract, the other pins what a user sees.
6. **A row in [Chapter 11](11-verb-reference.md)**, and an example somewhere — every fenced
   block in `docs/` is executed by `ctest`.

Adding a *function* is the same, with `AKBASIC_TOK_FUNCTION`, a real `arity`, and
[Chapter 12](12-function-reference.md).

### Adding a device capability

Add the entry point to the backend record in the relevant `include/akbasic/*.h`, implement
it in `src/*_akgl.c`, and — this is the part that is easy to skip — **make the verb refuse
by name when the pointer is `NULL`**, so an older host or a different backend gets an
error rather than silence.

If `libakgl` cannot supply what the verb needs, **do not work around it here**. File it in
`deps/libakgl/TODO.md`: what the BASIC verb requires, what the `akgl_*` entry point should
look like, and what tests would cover it. Four gaps have gone upstream that way and all
four landed.

### The rules a change has to keep

These are not style preferences. Each one is load-bearing for goal 3, and each one has a
test or a build failure behind it:

- **Nothing in the library terminates the process.** `FINISH_NORETURN` belongs only in a
  `main()`.
- **Nothing calls `malloc`.** Add a pool, or a layer to one.
- **No file-scope mutable state.** It goes on `akbasic_Runtime`.
- **Nothing blocks.** A verb that waits sets state and returns; `step()` checks it next
  time round. `SLEEP`, `WAIT`, `GETKEY` and `PLAY` are all built that way.
- **The interpreter owns no window, renderer or loop.**

## Where to read next

`MAINTENANCE.md` is the conventions: the three test lists and why two of them invert
"passed", the documentation-example harness, the error-code map, the build collisions, the
style rules. `TODO.md` is the defect list, with file, line and consequence — including the
ones inherited from the Go reference and the ones found writing these chapters. The
headers under `include/akbasic/` are the API, and `doxygen Doxyfile` renders them into
`build/docs/html`.

And `examples/embed.c` and `examples/hostvars.c` are two complete hosts, built and run by
every build, so neither can rot.