Merge pull request 'Report prescan errors on their source lines' (#44) from 10 into main

Reviewed-on: #44
Reviewed-by: andrew <andrew@aklabs.net>

MAINTENANCE.md

@@ -698,6 +698,26 @@ as a commit co-author, and this repository follows the same rule.
 Each dependency carries its own `AGENTS.md` with authoritative per-repo rules. Read the
 relevant one before editing a submodule.
 
+### Abandoned generators
+
+The one invariant generators (`GEN`/`EMIT`, `FOR EACH`/`DO EACH`) add to the environment
+pool: **a suspended generator hangs off its loop scope's `forGeneratorEnv` as a *child*,
+off the parent chain, so no walk up `->parent` ever finds it.** Any path that discards a
+loop scope — `EXIT`, a mismatched `NEXT`, a `LOOP` condition saying stop, an error unwind
+through `akbasic_runtime_pump_generator()` or `akbasic_runtime_call_function()` — must
+release that generator too, or its pool slot is stranded until the next `RUN`; with
+twelve slots, a loop that abandons a dozen of them kills the program with "Environment
+pool exhausted" far from the cause.
+
+Two functions own the invariant, and every discard path goes through one of them:
+`akbasic_runtime_release_generator()` (walks a detached generator chain up through its
+call frame, recursing into any `forGeneratorEnv` it passes) and
+`akbasic_runtime_unwind_to_environment()` (pops the *active* chain down to a target,
+releasing each popped scope's suspended generator on the way). If you add a new path
+that pops or discards environments, use one of these — a bare
+`akbasic_runtime_prev_environment()` loop reintroduces the leak, and
+`tests/generators.c` holds the pool-exhaustion tests that will say so.
+
 ---
 
 ## Editing the documentation

TODO.md

@@ -366,6 +366,36 @@ One caveat survives the upgrade unchanged: `aksl_strhash_djb2` still sign-extend
 high-bit byte hashes differently from the `unsigned char` answer. BASIC identifiers are 7-bit
 ASCII so the symbol tables cannot reach it — see §1.3, which is still accurate.
 
+### 1.10 Generators share the `DEF` namespace, and the rest of their v1 semantics
+
+Decided with issue #57 and its review. `GEN` and `DEF` live in the same functions table —
+one lookup, one "unknown function" error path, a name cannot be both. What follows from
+that and from the review of PR #61, all settled:
+
+- A `GEN` called like a function (`X# = COUNTUP(3)`) is refused at the call, before
+  anything is pushed — `akbasic_FunctionDef.isGenerator` exists for exactly this check.
+- Bare `RETURN` standing in a `GEN`'s own frame ends the generator exactly as `END GEN`
+  does; `RETURN expr` there is an error, because values leave a `GEN` only through `EMIT`.
+  Both inherit the interpreter-wide restriction that `RETURN` does not unwind nested
+  `FOR`/`DO` scopes — lifting that everywhere (the C64 reference *does* unwind) is filed
+  separately.
+- `DO EACH ... LOOP WHILE c | UNTIL c` composes: the condition is checked after each trip,
+  with the loop variable still holding that trip's value, and stopping abandons the
+  generator exactly as `EXIT` does. A condition on the `DO EACH` line itself is a parse
+  error.
+- Self-recursion — a `GEN` reached again down its own parent chain — is refused; sibling
+  and nested invocations of the same `GEN` are each a fresh pool environment and are fine.
+- Every path that discards a `FOR EACH`/`DO EACH` scope must release the generator
+  suspended off it; see MAINTENANCE.md's "Abandoned generators" note for the invariant
+  and `akbasic_runtime_unwind_to_environment()` for the one primitive that enforces it.
+
+One known limitation, pre-existing and shared with `DEF`: `parse_def_parameters()` does
+not accept an empty parameter list, so `GEN NAME()` cannot be written — every generator
+takes at least one parameter whether it wants one or not. Location:
+`src/parser_commands.c`, `parse_def_parameters()`. Consequence: pointless parameters in
+programs. Blast radius: cosmetic, both `DEF` and `GEN` headers. Closure: teach the shared
+helper to accept `()`, one test each for `DEF` and `GEN`; filed as its own issue.
+
 ---
 
 ## 2. What exists — **the core port is complete and green**

docs/04-control-flow.md

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

docs/11-verb-reference.md

@@ -37,7 +37,7 @@ for the reasoning in each case.
 | `DIM` … `AS` | `DIM S@ AS T`, `DIM P@ AS PTR TO T` | Make a structure, or a strict pointer to one. See Chapter 16. |
 | `DIRECTORY` | `DIRECTORY` | **Refused.** Not written yet; the standard-library wrapper it waited on has landed. |
 | `DLOAD` | `DLOAD "name"` | Load a program from a file. |
-| `DO` | `DO [WHILE c | UNTIL c]`, `DO EACH V IN gen(args)` | Start a loop. The condition may be here, on the `LOOP`, or neither. `EACH` consumes a `GEN` instead; see Chapter 4. |
+| `DO` | `DO [WHILE c | UNTIL c]`, `DO EACH V IN gen(args)` | Start a loop. The condition may be here, on the `LOOP`, or neither. `EACH` consumes a `GEN` instead, and takes its condition only on the `LOOP`; see Chapter 4. |
 | `DOPEN` | `DOPEN n, "name" [,W]` | Open a file on channel `n`. `W` opens it for writing. |
 | `DRAW` | `DRAW src, x, y [TO x, y ...]` | Plot a point or draw a polyline. |
 | `DSAVE` | `DSAVE "name"` | Save the program to a file. |
@@ -90,7 +90,7 @@ for the reasoning in each case.
 | `RENUMBER` | `RENUMBER [start [,step [,from]]]` | Renumber lines, rewriting every branch to match. |
 | `RESTORE` | `RESTORE [line]` | Reset the `READ` cursor, optionally to a line. |
 | `RESUME` | `RESUME [NEXT | line]` | Return from a `TRAP` handler. |
-| `RETURN` | `RETURN [expr]` | Return from a `GOSUB` or a multi-line `DEF`. |
+| `RETURN` | `RETURN [expr]` | Return from a `GOSUB` or a multi-line `DEF`. Inside a `GEN`, a bare `RETURN` ends the generator early; `RETURN expr` there is an error. |
 | `RUN` | `RUN [line]` | Run the program, optionally from a line. |
 | `SAVE` | `SAVE "name"` | The other name for `DSAVE`. |
 | `SCALE` | `SCALE on [,xmax, ymax]` | Turn user coordinates on or off. |

docs/14-architecture.md

@@ -380,8 +380,10 @@ no free, so anything drawn from it is spent for the life of the run — and scop
 returns a variable's *slot* without returning its storage. A scalar therefore does not
 draw from it at all: `akbasic_variable_init()` points a one-element non-`@` variable at
 its own `inlinevalue`, which is what makes a local, a `FOR` counter and a `DEF` parameter
-free. Arrays and structures still spend, deliberately, because a pointer into a record is
+free. A pointer parameter is also free: it owns only its one-slot reference, so its
-allowed to outlive the scope that DIMmed it.
+`inlinevalue` dies with the call while the target remains in the caller's storage. Arrays,
+structures and by-value structure parameters still spend, deliberately, because a pointer
+into a record is allowed to outlive the scope that DIMmed it.
 [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

docs/16-structures.md

@@ -50,7 +50,7 @@ nothing would say which type it is.
 ```
 
 ```output
-? 40 : PARSE ERROR TYPE POINT: POINT is a reserved word and cannot name a type
+? 10 : PARSE ERROR TYPE POINT: POINT is a reserved word and cannot name a type
 
 ```
 
@@ -266,6 +266,13 @@ The function saw 99; the caller still has 5. To change a caller's record on purp
 a pointer — `DEF POKEIT(P@ AS PTR TO CRATE)` — and reach through it with `->`. Neither is
 a special rule: both fall out of the parameter being assigned like any other variable.
 
+A pointer parameter's own reference is kept in the call variable's inline slot, so repeated
+calls do not spend the value pool. Its target remains the caller's structure. A by-value
+structure parameter is different: its copied slots remain in the value pool because
+`POINT Q@ AT B@` may retain a pointer to that copy after the function returns. Until escape
+analysis can distinguish that case, **do not call a by-value structure-parameter function in
+a loop**; bind a host global and rebind it per instance instead.
+
 ## What is checked, and what is not
 
 A field name is checked against the set the type declared, and the refusal lists the

include/akbasic/environment.h

@@ -277,6 +277,16 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_environment_collect_subscripts(akbasi
  */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_environment_create(akbasic_Environment *obj, const char *varname, akbasic_Variable **dest);
 
+/**
+ * @brief Create a variable slot without allocating value storage.
+ *
+ * Used when the caller knows the variable's representation before its first
+ * initialization, such as a structure parameter. The caller must initialize
+ * the variable before evaluating it.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_environment_create_empty(akbasic_Environment *obj, const char *varname,
+										akbasic_Variable **dest);
+
 /**
  * @brief Resolve a label to the line number it marks.
  * @param obj Scope to search; the parent chain is walked.

include/akbasic/runtime.h

@@ -127,6 +127,12 @@ typedef struct akbasic_Runtime
 {
     akbasic_SourceLine source[AKBASIC_MAX_SOURCE_LINES];
 
+    /* Scratch owned by this runtime for RENUMBER and its target prescan. */
+    int16_t renumber_map[AKBASIC_MAX_SOURCE_LINES];
+    uint8_t renumber_visited[AKBASIC_MAX_SOURCE_LINES];
+    akbasic_SourceLine renumber_line;
+    char renumber_discard[AKBASIC_MAX_LINE_LENGTH * 2];
+
     /* Pools. Nothing here is malloc'd; everything is drawn from and returned. */
     akbasic_Environment environments[AKBASIC_MAX_ENVIRONMENTS];
     akbasic_Variable variables[AKBASIC_MAX_VARIABLES];
@@ -635,6 +641,28 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_detach_environment(akbasic_Ru
  */
 akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_release_environment(akbasic_Runtime *obj, akbasic_Environment *env);
 
+/**
+ * @brief Pop and release every scope from the active one up to @p target.
+ *
+ * The shared teardown for every path that abandons part of the environment
+ * chain at once instead of popping it a verb at a time: the error unwinds in
+ * akbasic_runtime_pump_generator() and akbasic_runtime_call_function(). Each
+ * popped scope's suspended generator (`forGeneratorEnv`), if it still holds
+ * one, is released through akbasic_runtime_release_generator() -- a suspended
+ * generator is a *child* of its loop scope, so no walk up the parent chain
+ * would ever reach it.
+ *
+ * Stops without error at the root if @p target is not on the chain: callers
+ * are already cleaning up after a failure, and releasing everything is the
+ * least-wrong answer to a target that has gone missing.
+ *
+ * @param obj Object to initialize, inspect, or modify.
+ * @param target The scope to stop at; it is left active and untouched.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ * @throws AKERR_NULLPOINTER When @p target is NULL.
+ */
+akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_unwind_to_environment(akbasic_Runtime *obj, akbasic_Environment *target);
+
 /**
  * @brief Push a GEN's environment, bind its parameters and run it to its first EMIT.
  *

src/data.c

@@ -160,14 +160,21 @@ akerr_ErrorContext *akbasic_data_scan(akbasic_Runtime *obj)
 {
     PREPARE_ERROR(errctx);
     int64_t i = 0;
+    int64_t entry = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in data_scan");
+    FAIL_ZERO_RETURN(errctx, (obj->environment != NULL), AKERR_NULLPOINTER,
+		     "Runtime has no environment; call akbasic_runtime_init() first");
+    entry = obj->environment->lineno;
     PASS(errctx, akbasic_data_state_init(&obj->data_state));
     for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
 	if ( obj->source[i].code[0] != '\0' ) {
+	    /* Keep BASIC's error prefix on the source line being prescanned. */
+	    obj->environment->lineno = i;
 	    PASS(errctx, scan_line(&obj->data_state, obj->source[i].code, i));
 	}
     }
+    obj->environment->lineno = entry;
     SUCCEED_RETURN(errctx);
 }
 

src/environment.c

@@ -310,7 +310,23 @@ akerr_ErrorContext *akbasic_environment_get(akbasic_Environment *obj, const char
     SUCCEED_RETURN(errctx);
 }
 
-akerr_ErrorContext *akbasic_environment_create(akbasic_Environment *obj, const char *varname, akbasic_Variable **dest)
+/**
+ * @brief Create a variable slot in the given scope, optionally allocating its storage.
+ *
+ * Shared by akbasic_environment_create() and akbasic_environment_create_empty(),
+ * which differ only in whether the new variable's value storage is initialized
+ * immediately or left for the caller to set up.
+ *
+ * @param obj Scope the variable is created in; only this scope is searched or
+ *        written to, unlike akbasic_environment_get()'s walk up the parent chain.
+ * @param varname Name of the variable to create.
+ * @param dest Set to the created (or already-existing) variable.
+ * @param initialize When true, the variable's value storage is allocated from
+ *        the runtime's value pool; when false, the caller must initialize it
+ *        before the variable is evaluated.
+ */
+static akerr_ErrorContext *environment_create_named(akbasic_Environment *obj, const char *varname,
+							akbasic_Variable **dest, bool initialize)
 {
     PREPARE_ERROR(errctx);
     akbasic_Variable *variable = NULL;
@@ -344,12 +360,49 @@ akerr_ErrorContext *akbasic_environment_create(akbasic_Environment *obj, const c
     PASS(errctx, aksl_strcpy(variable->name, sizeof(variable->name), varname));
     variable->valuetype = AKBASIC_TYPE_UNDEFINED;
     variable->mutable_ = true;
+    if ( initialize ) {
 	PASS(errctx, akbasic_variable_init(variable, &obj->runtime->valuepool, sizes, 1));
+    }
     PASS(errctx, akbasic_symtab_set(&obj->variables, varname, variable, 0));
     *dest = variable;
     SUCCEED_RETURN(errctx);
 }
 
+/**
+ * @brief Find a variable in this scope, creating and initializing it if absent.
+ *
+ * @param obj The scope to search and, on a miss, to create in.
+ * @param varname Name including its type suffix.
+ * @param dest Output destination populated with the variable.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ */
+akerr_ErrorContext *akbasic_environment_create(akbasic_Environment *obj, const char *varname, akbasic_Variable **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, environment_create_named(obj, varname, dest, true));
+    SUCCEED_RETURN(errctx);
+}
+
+/**
+ * @brief Find a variable in this scope, creating it without value storage if absent.
+ *
+ * The caller must initialize the variable before evaluating it.
+ *
+ * @param obj The scope to search and, on a miss, to create in.
+ * @param varname Name including its type suffix.
+ * @param dest Output destination populated with the variable.
+ * @return `NULL` on success, otherwise an error context owned by the caller.
+ */
+akerr_ErrorContext *akbasic_environment_create_empty(akbasic_Environment *obj, const char *varname,
+							akbasic_Variable **dest)
+{
+    PREPARE_ERROR(errctx);
+
+    PASS(errctx, environment_create_named(obj, varname, dest, false));
+    SUCCEED_RETURN(errctx);
+}
+
 /*
  * Evaluate an lvalue's subscript list, if it has one, into `subscripts`. A bare
  * identifier yields the single subscript {0}, which is how a scalar is addressed

src/parser_commands.c

@@ -337,6 +337,19 @@ akerr_ErrorContext *akbasic_parse_do(akbasic_Parser *parser, akbasic_ASTLeaf **d
 
 	    PASS(errctx, parse_each_clause(parser, &var, &callexpr));
 
+	    /*
+	     * Same guard as akbasic_parse_for()'s EACH branch, with the likely
+	     * mistake named: a condition belongs on the LOOP, where it is
+	     * checked against each emitted value, not here on the DO.
+	     */
+	    peeked = akbasic_parser_peek(parser);
+	    FAIL_NONZERO_RETURN(errctx,
+				(peeked != NULL &&
+				 peeked->tokentype != AKBASIC_TOK_UNDEFINED &&
+				 peeked->tokentype != AKBASIC_TOK_COLON),
+				AKBASIC_ERR_SYNTAX,
+				"DO EACH takes its WHILE/UNTIL on the LOOP, and nothing else here");
+
 	    newenv->isDoLoop = true;
 	    newenv->isEachLoop = true;
 	    newenv->loopFirstLine = firstline;
@@ -1098,6 +1111,21 @@ akerr_ErrorContext *akbasic_parse_for(akbasic_Parser *parser, akbasic_ASTLeaf **
 
 	    PASS(errctx, parse_each_clause(parser, &var, &callexpr));
 
+	    /*
+	     * Nothing may follow the generator call but another statement.
+	     * Without this, a stray clause sits unparsed on the line and only
+	     * blows up after the whole loop has run, when the parent scope
+	     * resumes the line mid-statement -- an error at the loop's end
+	     * pointing at its beginning.
+	     */
+	    peeked = akbasic_parser_peek(parser);
+	    FAIL_NONZERO_RETURN(errctx,
+				(peeked != NULL &&
+				 peeked->tokentype != AKBASIC_TOK_UNDEFINED &&
+				 peeked->tokentype != AKBASIC_TOK_COLON),
+				AKBASIC_ERR_SYNTAX,
+				"FOR EACH takes nothing after the generator call");
+
 	    newenv->isEachLoop = true;
 	    newenv->loopFirstLine = firstline;
 	    /*

src/renumber.c

@@ -72,7 +72,7 @@ struct akbasic_TargetWalk
  * rewritten: `GOTO 9999` in a program with no line 9999 is already broken, and
  * inventing a destination for it would hide that.
  */
-static int64_t mapped(const int64_t *map, int64_t line)
+static int64_t mapped(const int16_t *map, int64_t line)
 {
     if ( line < 0 || line >= AKBASIC_MAX_SOURCE_LINES ) {
 	return line;
@@ -306,7 +306,7 @@ static akerr_ErrorContext *rewrite_line(akbasic_TargetWalk *walk, const char *co
 static akerr_ErrorContext *visit_renumber(akbasic_TargetWalk *walk, int64_t target, char *dest, size_t len)
 {
     PREPARE_ERROR(errctx);
-    const int64_t *map = (const int64_t *)walk->self;
+    const int16_t *map = (const int16_t *)walk->self;
     int written = 0;
 
     PASS(errctx, aksl_snprintf(&written, dest, len, "%" PRId64, mapped(map, target)));
@@ -316,8 +316,7 @@ static akerr_ErrorContext *visit_renumber(akbasic_TargetWalk *walk, int64_t targ
 akerr_ErrorContext *akbasic_renumber(akbasic_Runtime *obj, int64_t newstart, int64_t increment, int64_t oldstart)
 {
     PREPARE_ERROR(errctx);
-    static int64_t map[AKBASIC_MAX_SOURCE_LINES];
+    int16_t *map = obj == NULL ? NULL : obj->renumber_map;
-    static akbasic_SourceLine rewritten[AKBASIC_MAX_SOURCE_LINES];
     akbasic_TargetWalk walk = { map, visit_renumber };
     int64_t next = newstart;
     int64_t i = 0;
@@ -356,10 +355,8 @@ akerr_ErrorContext *akbasic_renumber(akbasic_Runtime *obj, int64_t newstart, int
 	next += increment;
     }
 
-    PASS(errctx, aksl_memset(rewritten, 0, sizeof(rewritten)));
+    PASS(errctx, aksl_memset(obj->renumber_visited, 0, sizeof(obj->renumber_visited)));
     for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
-	int64_t target = 0;
-
 	if ( obj->source[i].code[0] == '\0' ) {
 	    continue;
 	}
@@ -367,20 +364,77 @@ akerr_ErrorContext *akbasic_renumber(akbasic_Runtime *obj, int64_t newstart, int
 	 * Every line is rewritten, not just the moved ones: a line before
 	 * `oldstart` can branch into the region that moved.
 	 */
-	target = mapped(map, i);
 	PASS(errctx, rewrite_line(&walk, obj->source[i].code,
-				  rewritten[target].code, sizeof(rewritten[target].code)));
+				  obj->renumber_line.code, sizeof(obj->renumber_line.code)));
-	rewritten[target].lineno = target;
+	obj->renumber_line.lineno = i;
 	/*
 	 * Every line comes out numbered, whether or not it went in that way.
 	 * Asking for numbers is what RENUMBER is, and a program that has been
 	 * through it can be branched into by number -- which is the whole point
 	 * of running it over source that arrived without any.
 	 */
-	rewritten[target].numbered = true;
+	obj->renumber_line.numbered = true;
+	PASS(errctx, aksl_strncpy(obj->source[i].code, AKBASIC_MAX_LINE_LENGTH,
+				 obj->renumber_line.code, AKBASIC_MAX_LINE_LENGTH));
+	obj->source[i].lineno = obj->renumber_line.lineno;
+	obj->source[i].numbered = obj->renumber_line.numbered;
     }
 
-    PASS(errctx, aksl_memcpy(obj->source, rewritten, sizeof(obj->source)));
+    /* Move the already-rewritten lines in place. The map is a partial
+     * permutation: a chain ends at an empty slot, while a cycle closes back
+     * on its starting line. A single displaced line is sufficient for both. */
+    for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
+	int64_t current = i;
+	akbasic_SourceLine displaced;
+	akbasic_SourceLine next_line;
+
+	if ( map[i] < 0 || obj->renumber_visited[i] ) {
+	    continue;
+	}
+	PASS(errctx, aksl_strncpy(displaced.code, AKBASIC_MAX_LINE_LENGTH,
+				 obj->source[i].code, AKBASIC_MAX_LINE_LENGTH));
+	displaced.lineno = obj->source[i].lineno;
+	displaced.numbered = obj->source[i].numbered;
+	for ( ;; ) {
+	    int64_t destination = map[current];
+
+	    obj->renumber_visited[current] = 1;
+	    if ( destination == i ) {
+		displaced.lineno = destination;
+		PASS(errctx, aksl_strncpy(obj->source[destination].code, AKBASIC_MAX_LINE_LENGTH,
+					 displaced.code, AKBASIC_MAX_LINE_LENGTH));
+		obj->source[destination].lineno = displaced.lineno;
+		obj->source[destination].numbered = displaced.numbered;
+		break;
+	    }
+	    if ( map[destination] < 0 ) {
+		displaced.lineno = destination;
+		PASS(errctx, aksl_strncpy(obj->source[destination].code, AKBASIC_MAX_LINE_LENGTH,
+					 displaced.code, AKBASIC_MAX_LINE_LENGTH));
+		obj->source[destination].lineno = displaced.lineno;
+		obj->source[destination].numbered = displaced.numbered;
+		PASS(errctx, aksl_memset(&obj->source[current], 0,
+					 sizeof(obj->source[current])));
+		break;
+	    }
+	    PASS(errctx, aksl_strncpy(next_line.code, AKBASIC_MAX_LINE_LENGTH,
+				     obj->source[destination].code, AKBASIC_MAX_LINE_LENGTH));
+	    next_line.lineno = obj->source[destination].lineno;
+	    next_line.numbered = obj->source[destination].numbered;
+	    displaced.lineno = destination;
+	    PASS(errctx, aksl_strncpy(obj->source[destination].code, AKBASIC_MAX_LINE_LENGTH,
+				     displaced.code, AKBASIC_MAX_LINE_LENGTH));
+	    obj->source[destination].lineno = displaced.lineno;
+	    obj->source[destination].numbered = displaced.numbered;
+	    PASS(errctx, aksl_memset(&obj->source[current], 0,
+				     sizeof(obj->source[current])));
+	    PASS(errctx, aksl_strncpy(displaced.code, AKBASIC_MAX_LINE_LENGTH,
+				     next_line.code, AKBASIC_MAX_LINE_LENGTH));
+	    displaced.lineno = next_line.lineno;
+	    displaced.numbered = next_line.numbered;
+	    current = destination;
+	}
+    }
     SUCCEED_RETURN(errctx);
 }
 
@@ -435,7 +489,6 @@ akerr_ErrorContext *akbasic_runtime_check_targets(akbasic_Runtime *obj)
      * step(). Nothing is read back out of it -- the walk needs somewhere to put
      * the text it would have written, and this is it.
      */
-    static char discard[AKBASIC_MAX_LINE_LENGTH * 2];
     CheckState state = { NULL, 0 };
     akbasic_TargetWalk walk = { &state, visit_check };
     int64_t entry = 0;
@@ -463,7 +516,8 @@ akerr_ErrorContext *akbasic_runtime_check_targets(akbasic_Runtime *obj)
 	 * the whole point of setting it.
 	 */
 	obj->environment->lineno = i;
-	PASS(errctx, rewrite_line(&walk, obj->source[i].code, discard, sizeof(discard)));
+	PASS(errctx, rewrite_line(&walk, obj->source[i].code,
+				 obj->renumber_discard, sizeof(obj->renumber_discard)));
     }
     /* Nothing was refused, so leave the cursor as the caller had it. */
     obj->environment->lineno = entry;

src/runtime.c

@@ -208,6 +208,38 @@ akerr_ErrorContext *akbasic_runtime_prev_environment(akbasic_Runtime *obj)
     SUCCEED_RETURN(errctx);
 }
 
+akerr_ErrorContext *akbasic_runtime_unwind_to_environment(akbasic_Runtime *obj, akbasic_Environment *target)
+{
+    PREPARE_ERROR(errctx);
+    akbasic_Environment *popped = NULL;
+
+    FAIL_ZERO_RETURN(errctx, (obj != NULL && target != NULL), AKERR_NULLPOINTER,
+		     "NULL argument in unwind_to_environment");
+    /*
+     * Stops early at the root rather than failing on it: every caller is an
+     * error-unwind path, where "release whatever there is" beats raising a
+     * second failure on top of the one being cleaned up after.
+     */
+    while ( obj->environment != target && obj->environment->parent != NULL ) {
+	popped = obj->environment;
+	obj->environment = popped->parent;
+	/*
+	 * An EACH loop scope on its way out takes its suspended generator with
+	 * it -- the generator is a *child* of the scope, off the parent chain,
+	 * and this walk is the only thing that will ever see it again. Guarded
+	 * on `used` because a generator that was being pumped when the failure
+	 * hit is *on* the chain being unwound, already released by the time
+	 * the walk reaches the loop scope that references it.
+	 */
+	if ( popped->forGeneratorEnv != NULL && popped->forGeneratorEnv->used ) {
+	    PASS(errctx, akbasic_runtime_release_generator(obj, popped->forGeneratorEnv));
+	}
+	popped->forGeneratorEnv = NULL;
+	PASS(errctx, akbasic_runtime_release_environment(obj, popped));
+    }
+    SUCCEED_RETURN(errctx);
+}
+
 /* ------------------------------------------------------------- lifecycle -- */
 
 akerr_ErrorContext *akbasic_runtime_zero(akbasic_Runtime *obj)
@@ -1008,12 +1040,13 @@ static akerr_ErrorContext *bind_structure_parameter(akbasic_Runtime *obj, akbasi
 		     obj->structtypes.types[typeindex].name,
 		     obj->structtypes.types[argvalue->structtype].name);
 
-    PASS(errctx, akbasic_environment_create(callenv, param->identifier, &variable));
+    PASS(errctx, akbasic_environment_create_empty(callenv, param->identifier, &variable));
     sizes[0] = (ispointer ? 1 : obj->structtypes.types[typeindex].slotcount);
+    /* A pointer parameter's own reference cannot escape its call scope. */
+    variable->ispointer = ispointer;
     PASS(errctx, akbasic_variable_init(variable, &obj->valuepool, sizes, 1));
     variable->valuetype = AKBASIC_TYPE_STRUCT;
     variable->structtype = typeindex;
-    variable->ispointer = ispointer;
 
     if ( ispointer ) {
 	PASS(errctx, akbasic_value_clone(argvalue, &variable->values[0]));
@@ -1166,10 +1199,11 @@ akerr_ErrorContext *akbasic_runtime_call_function(akbasic_Runtime *obj, const ch
 	 * Give them back, or a host absorbing script errors drains the
 	 * twelve-slot environment pool after twelve dead calls and every
 	 * call after that fails for a reason nobody can see in the script.
+	 * The unwind, not a bare prev_environment() loop, because a body that
+	 * died inside a FOR EACH leaves a suspended generator hanging off the
+	 * loop scope, and only the unwind knows to take it down too.
 	 */
-	while ( obj->environment != targetenv && obj->environment->parent != NULL ) {
+	IGNORE(akbasic_runtime_unwind_to_environment(obj, targetenv));
-	    IGNORE(akbasic_runtime_prev_environment(obj));
-	}
     } PROCESS(errctx) {
     } FINISH(errctx, true);
     PASS(errctx, akbasic_environment_new_value(targetenv, &out));
@@ -1631,17 +1665,22 @@ akerr_ErrorContext *akbasic_runtime_scan_labels(akbasic_Runtime *obj)
     PREPARE_ERROR(errctx);
     akbasic_Environment *root = NULL;
     int64_t i = 0;
+    int64_t entry = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in scan_labels");
     FAIL_ZERO_RETURN(errctx, (obj->environment != NULL), AKERR_NULLPOINTER,
 		     "Runtime has no environment; call akbasic_runtime_init() first");
     for ( root = obj->environment; root->parent != NULL; root = root->parent ) {
     }
+    entry = obj->environment->lineno;
     for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
 	if ( obj->source[i].code[0] != '\0' ) {
+	    /* Keep BASIC's error prefix on the source line being prescanned. */
+	    obj->environment->lineno = i;
 	    PASS(errctx, scan_line_labels(root, obj->source[i].code, i));
 	}
     }
+    obj->environment->lineno = entry;
     SUCCEED_RETURN(errctx);
 }
 

src/runtime_commands.c

@@ -161,8 +161,22 @@ akerr_ErrorContext *akbasic_cmd_return(akbasic_Runtime *obj, akbasic_ASTLeaf *ex
 	SUCCEED_TRUE(obj, dest);
 	SUCCEED_RETURN(errctx);
     }
+    /*
+     * A GEN is a function at heart, and RETURN ends it the way it ends a DEF
+     * or a GOSUB: early, cleanly, from its own frame. What a generator's
+     * RETURN cannot do is carry a value -- values leave a GEN one at a time,
+     * through EMIT, and there is no caller waiting on a return slot.
+     */
+    if ( obj->environment->isGenerator ) {
+	FAIL_NONZERO_RETURN(errctx, (expr != NULL && expr->right != NULL), AKBASIC_ERR_STATE,
+			    "A GEN yields values through EMIT; RETURN here takes none");
+	PASS(errctx, akbasic_runtime_prev_environment(obj));
+	obj->environment->forGeneratorEnv = NULL;
+	SUCCEED_TRUE(obj, dest);
+	SUCCEED_RETURN(errctx);
+    }
     FAIL_ZERO_RETURN(errctx, (obj->environment->gosubReturnLine != 0), AKBASIC_ERR_STATE,
-		     "RETURN outside the context of GOSUB");
+		     "RETURN outside the context of GOSUB, DEF, or GEN");
 
     if ( expr != NULL && expr->right != NULL ) {
 	PASS(errctx, akbasic_runtime_evaluate(obj, expr->right, &result));

src/runtime_generator.c

@@ -68,9 +68,7 @@ akerr_ErrorContext *akbasic_runtime_pump_generator(akbasic_Runtime *obj, akbasic
 	 * among the scopes just released.
 	 */
 	if ( obj->environment != loopenv ) {
-	    while ( obj->environment != loopenv && obj->environment->parent != NULL ) {
+	    IGNORE(akbasic_runtime_unwind_to_environment(obj, loopenv));
-		IGNORE(akbasic_runtime_prev_environment(obj));
-	    }
 	    loopenv->forGeneratorEnv = NULL;
 	}
     } PROCESS(errctx) {
@@ -103,6 +101,18 @@ akerr_ErrorContext *akbasic_runtime_release_generator(akbasic_Runtime *obj, akba
     while ( walk != NULL ) {
 	isgen = walk->isGenerator;
 	next = walk->parent;
+	/*
+	 * A scope between the resume point and the call frame may be an EACH
+	 * loop with its *own* generator suspended off to the side. Releasing
+	 * the loop scope without releasing that generator strands it in the
+	 * pool -- the walk goes through parents and a suspended generator is a
+	 * child. Guarded on `used` so a generator already released as part of
+	 * some enclosing teardown is not released twice.
+	 */
+	if ( walk->forGeneratorEnv != NULL && walk->forGeneratorEnv->used ) {
+	    PASS(errctx, akbasic_runtime_release_generator(obj, walk->forGeneratorEnv));
+	}
+	walk->forGeneratorEnv = NULL;
 	PASS(errctx, akbasic_runtime_release_environment(obj, walk));
 	if ( isgen ) {
 	    break;

src/runtime_structure.c

@@ -149,11 +149,27 @@ akerr_ErrorContext *akbasic_cmd_loop(akbasic_Runtime *obj, akbasic_ASTLeaf *expr
 	akbasic_Environment *loopenv = obj->environment;
 
 	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "LOOP"));
-	if ( loopenv->forGeneratorEnv != NULL ) {
+	/*
+	 * A condition on the LOOP composes with EACH: it is checked after each
+	 * trip through the body, with the loop variable still holding that
+	 * trip's value, before the generator is pumped for the next one. A
+	 * condition that says stop abandons the generator exactly as EXIT does.
+	 */
+	again = true;
+	arg = (expr != NULL ? expr->right : NULL);
+	if ( arg != NULL ) {
+	    kind = (int)arg->literal_int;
+	    PASS(errctx, loop_continues(obj, arg->left, kind, &again));
+	}
+	if ( !again && loopenv->forGeneratorEnv != NULL ) {
+	    PASS(errctx, akbasic_runtime_release_generator(obj, loopenv->forGeneratorEnv));
+	    loopenv->forGeneratorEnv = NULL;
+	}
+	if ( again && loopenv->forGeneratorEnv != NULL ) {
 	    obj->environment = loopenv->forGeneratorEnv;
 	    PASS(errctx, akbasic_runtime_pump_generator(obj, loopenv));
 	}
-	again = (loopenv->forGeneratorEnv != NULL);
+	again = (again && loopenv->forGeneratorEnv != NULL);
     } else {
 	PASS(errctx, akbasic_environment_stop_waiting(obj->environment, "LOOP"));
 	/*

src/structtype.c

@@ -260,11 +260,13 @@ static akerr_ErrorContext *scan_names(akbasic_Runtime *obj)
     size_t namelen = 0;
     bool matched = false;
     const akbasic_Verb *verb = NULL;
+    int64_t entry = obj->environment->lineno;
 
     for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
 	if ( obj->source[i].code[0] == '\0' ) {
 	    continue;
 	}
+	obj->environment->lineno = i;
 	cursor = next_word(skip_lineno(obj->source[i].code), word, sizeof(word));
 
 	PASS(errctx, word_is(word, "END", &matched));
@@ -327,6 +329,7 @@ static akerr_ErrorContext *scan_names(akbasic_Runtime *obj)
 
     FAIL_NONZERO_RETURN(errctx, (open >= 0), AKBASIC_ERR_SYNTAX,
 			"TYPE %s is never closed with END TYPE", table->types[open >= 0 ? open : 0].name);
+    obj->environment->lineno = entry;
     SUCCEED_RETURN(errctx);
 }
 
@@ -440,7 +443,7 @@ static akerr_ErrorContext *parse_field(akbasic_StructTypeTable *table, akbasic_S
  * each other by value, which has no finite size. That is the diagnosis rather
  * than a stack overflow later.
  */
-static akerr_ErrorContext *resolve_sizes(akbasic_StructTypeTable *table)
+static akerr_ErrorContext *resolve_sizes(akbasic_Runtime *runtime, akbasic_StructTypeTable *table)
 {
     PREPARE_ERROR(errctx);
     bool progress = true;
@@ -477,6 +480,7 @@ static akerr_ErrorContext *resolve_sizes(akbasic_StructTypeTable *table)
     }
 
     for ( i = 0; i < table->count; i++ ) {
+	runtime->environment->lineno = table->types[i].firstline;
 	FAIL_NONZERO_RETURN(errctx, (table->types[i].slotcount < 0), AKBASIC_ERR_VALUE,
 			    "TYPE %s contains itself by value, so it has no size. "
 			    "A type may only refer to itself through PTR TO",
@@ -493,9 +497,13 @@ akerr_ErrorContext *akbasic_structtype_scan(akbasic_Runtime *obj)
     akbasic_StructTypeTable *table = NULL;
     int64_t i = 0;
     int t = 0;
+    int64_t entry = 0;
 
     FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in structtype scan");
+    FAIL_ZERO_RETURN(errctx, (obj->environment != NULL), AKERR_NULLPOINTER,
+		     "Runtime has no environment; call akbasic_runtime_init() first");
     table = &obj->structtypes;
+    entry = obj->environment->lineno;
 
     /*
      * Drop what the *script* declared and keep what the *host* registered.
@@ -525,10 +533,12 @@ akerr_ErrorContext *akbasic_structtype_scan(akbasic_Runtime *obj)
 	    if ( obj->source[i].code[0] == '\0' ) {
 		continue;
 	    }
+	    obj->environment->lineno = i;
 	    PASS(errctx, parse_field(table, type, obj->source[i].code, i));
 	}
     }
 
-    PASS(errctx, resolve_sizes(table));
+    PASS(errctx, resolve_sizes(obj, table));
+    obj->environment->lineno = entry;
     SUCCEED_RETURN(errctx);
 }

src/variable.c

@@ -99,18 +99,21 @@ akerr_ErrorContext *akbasic_variable_init(akbasic_Variable *obj, akbasic_ValuePo
      * the run was over, which a game loop reaches in half a minute. TODO.md
      * section 6 item 30 has the whole reduction.
      *
-     * **A `@` name is the one exclusion**, and it is the whole of it. A
+     * **A `@` name is the one exclusion**, except for a one-slot pointer
-     * structure or a pointer to one keeps pool storage because a pointer may
+     * parameter. A structure or a pointer variable keeps pool storage because
-     * outlive the scope that DIMmed it -- docs/16-structures.md says nothing is
+     * a pointer may outlive the scope that DIMmed it -- docs/16-structures.md
-     * reclaimed and akbasic_runtime_prev_environment() relies on it. The suffix
+     * says nothing is reclaimed and akbasic_runtime_prev_environment() relies
-     * is the right test rather than `structtype`, which the DIM path sets
+     * on it. A pointer parameter owns only its reference slot; the target is
+     * owned by the caller, so bind_structure_parameter() marks it before this
+     * call and lets that slot use inline storage. The suffix is the right test
+     * for every other case rather than `structtype`, which the DIM path sets
      * *after* calling this.
      *
      * Otherwise: reuse the existing slice when it is already big enough, which
      * makes a re-DIM to the same or a smaller size free; growing takes fresh
      * slots and abandons the old ones, as documented on akbasic_ValuePool.
      */
-    if ( totalsize == 1 && lastchar != '@' ) {
+    if ( totalsize == 1 && (lastchar != '@' || obj->ispointer) ) {
 	obj->values = &obj->inlinevalue;
     } else if ( obj->values == NULL || obj->valuecount < (int)totalsize ) {
 	PASS(errctx, akbasic_valuepool_take(pool, (int)totalsize, &obj->values));

tests/generators.c

@@ -119,6 +119,137 @@ static void test_exit_partway_through(void)
     harness_stop();
 }
 
+/**
+ * @brief Abandoning a generator that is itself suspended inside a FOR EACH
+ * over another generator releases the inner generator too.
+ *
+ * The inner generator's environment hangs off the *loop* scope inside OUTER's
+ * body as a child, off the parent chain -- the one place a bare parent walk
+ * never looks. Before akbasic_runtime_release_generator() recursed into
+ * `forGeneratorEnv`, every trip through this loop stranded one pool slot and
+ * the 13th trip died with "Environment pool exhausted".
+ */
+static void test_exit_releases_nested_generators(void)
+{
+    TEST_REQUIRE_OK(run_program("10 GEN INNER(N#)\n"
+				"20   EMIT 1\n"
+				"30   EMIT 2\n"
+				"40 END GEN\n"
+				"50 GEN OUTER(N#)\n"
+				"60   FOR EACH I# IN INNER(0)\n"
+				"70     EMIT I#\n"
+				"80   NEXT I#\n"
+				"90 END GEN\n"
+				"100 FOR K# = 1 TO 40\n"
+				"110   FOR EACH V# IN OUTER(0)\n"
+				"120     EXIT\n"
+				"130   NEXT V#\n"
+				"140 NEXT K#\n"
+				"150 PRINT \"DONE\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "DONE\n");
+    harness_stop();
+}
+
+/**
+ * @brief A LOOP UNTIL that stops a DO EACH early releases the generator it
+ * abandons, every time.
+ */
+static void test_loop_condition_releases_generator(void)
+{
+    TEST_REQUIRE_OK(run_program("10 GEN COUNTUP(N#)\n"
+				"20   FOR I# = 1 TO N#\n"
+				"30     EMIT I#\n"
+				"40   NEXT I#\n"
+				"50 END GEN\n"
+				"60 FOR K# = 1 TO 40\n"
+				"70   DO EACH V# IN COUNTUP(10)\n"
+				"80   LOOP UNTIL V# = 2\n"
+				"90 NEXT K#\n"
+				"100 PRINT \"DONE\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "DONE\n");
+    harness_stop();
+}
+
+/**
+ * @brief RETURN standing in a GEN's own frame ends the generator early,
+ * exactly as END GEN would -- a GEN is a function at heart.
+ */
+static void test_return_ends_generator(void)
+{
+    TEST_REQUIRE_OK(run_program("10 GEN G(N#)\n"
+				"20   EMIT 1\n"
+				"30   RETURN\n"
+				"40   EMIT 2\n"
+				"50 END GEN\n"
+				"60 FOR EACH V# IN G(0)\n"
+				"70   PRINT V#\n"
+				"80 NEXT V#\n"
+				"90 PRINT \"DONE\"\n"));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "1\nDONE\n");
+    harness_stop();
+}
+
+/**
+ * @brief RETURN with a value inside a GEN is refused: values leave a GEN one
+ * at a time, through EMIT, and there is no return slot waiting.
+ */
+static void test_return_value_in_generator_refused(void)
+{
+    TEST_REQUIRE_OK(run_program_bounded("10 GEN G(N#)\n"
+					"20   EMIT 1\n"
+					"30   RETURN 99\n"
+					"40 END GEN\n"
+					"50 FOR EACH V# IN G(0)\n"
+					"60   PRINT V#\n"
+					"70 NEXT V#\n"
+					"80 PRINT \"UNREACHABLE\"\n", 2000));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "1\n") != NULL,
+		 "expected the first EMIT in \"%s\"", HARNESS_OUTPUT);
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "UNREACHABLE") == NULL,
+		 "RETURN with a value must stop the run, got \"%s\"", HARNESS_OUTPUT);
+    harness_stop();
+}
+
+/**
+ * @brief The unwind primitive releases a popped scope's suspended generator.
+ *
+ * Built by hand rather than through BASIC because the paths that need this --
+ * the error unwinds in pump_generator() and call_function() -- only trigger
+ * on C-level failures a program cannot politely ask for. The shape is the
+ * one EMIT leaves behind: a loop scope holding a detached generator child,
+ * with a further scope active above it.
+ */
+static void test_unwind_releases_suspended_generators(void)
+{
+    akbasic_Environment *root = NULL;
+    akbasic_Environment *loopenv = NULL;
+    akbasic_Environment *genenv = NULL;
+    akbasic_Environment *forenv = NULL;
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+    root = HARNESS_RUNTIME.environment;
+
+    TEST_REQUIRE_OK(akbasic_runtime_new_environment(&HARNESS_RUNTIME));
+    loopenv = HARNESS_RUNTIME.environment;
+    loopenv->isEachLoop = true;
+
+    TEST_REQUIRE_OK(akbasic_runtime_new_environment(&HARNESS_RUNTIME));
+    genenv = HARNESS_RUNTIME.environment;
+    genenv->isGenerator = true;
+    TEST_REQUIRE_OK(akbasic_runtime_detach_environment(&HARNESS_RUNTIME));
+    loopenv->forGeneratorEnv = genenv;
+
+    TEST_REQUIRE_OK(akbasic_runtime_new_environment(&HARNESS_RUNTIME));
+    forenv = HARNESS_RUNTIME.environment;
+
+    TEST_REQUIRE_OK(akbasic_runtime_unwind_to_environment(&HARNESS_RUNTIME, root));
+    TEST_REQUIRE(HARNESS_RUNTIME.environment == root,
+		 "unwind must land on the target scope");
+    TEST_REQUIRE(!forenv->used && !loopenv->used && !genenv->used,
+		 "unwind must release the chain and the suspended generator");
+    harness_stop();
+}
+
 /**
  * @brief A GEN invoked like an ordinary function, rather than through FOR
  * EACH/DO EACH, fails cleanly.
@@ -216,6 +347,11 @@ int main(void)
     test_exit_releases_generator_for_each();
     test_exit_releases_generator_do_each();
     test_exit_partway_through();
+    test_exit_releases_nested_generators();
+    test_loop_condition_releases_generator();
+    test_return_ends_generator();
+    test_return_value_in_generator_refused();
+    test_unwind_releases_suspended_generators();
     test_called_like_a_function();
     test_emit_outside_gen();
     test_self_recursion_refused();

tests/interrupts.c

@@ -16,6 +16,8 @@
  * below.
  */
 
+#include <stdio.h>
+
 #include "harness.h"
 
 /**
@@ -341,6 +343,28 @@ static akerr_ErrorContext AKERR_NOIGNORE *test_prescan_boundaries(void)
     SUCCEED_RETURN(errctx);
 }
 
+/** @brief A full label table reports the line whose label could not be filed. */
+static void test_label_prescan_error_line(void)
+{
+    char source[4096] = "";
+    size_t used = 0;
+    int i = 0;
+
+    for ( i = 1; i <= AKBASIC_MAX_LABELS + 1; i++ ) {
+	used += (size_t)snprintf(source + used, sizeof(source) - used,
+				"%d LABEL L%d\n", i, i);
+    }
+    (void)snprintf(source + used, sizeof(source) - used, "100 PRINT 1\n");
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+    TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "? 65 : PARSE ERROR") != NULL,
+		 "a full label table should report its source line, got \"%s\"",
+		 HARNESS_OUTPUT);
+    harness_stop();
+}
+
 int main(void)
 {
     PREPARE_ERROR(errctx);
@@ -355,6 +379,7 @@ int main(void)
 	CATCH(errctx, test_undefined_label_is_reported());
 	CATCH(errctx, test_arm_refusals());
 	CATCH(errctx, test_prescan_boundaries());
+	test_label_prescan_error_line();
     } CLEANUP {
     } PROCESS(errctx) {
     } HANDLE_DEFAULT(errctx) {

tests/language/flowcontrol/generators_do_condition_misplaced.bas

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

tests/language/flowcontrol/generators_do_condition_misplaced.txt

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

tests/language/flowcontrol/generators_loop_condition.bas

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

tests/language/flowcontrol/generators_loop_condition.txt

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

tests/language/flowcontrol/generators_return.bas

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

tests/language/flowcontrol/generators_return.txt

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

tests/language/structures/reserved_names.txt

@@ -1,2 +1,2 @@
-? 90 : PARSE ERROR TYPE POINT: POINT is a reserved word and cannot name a type
+? 60 : PARSE ERROR TYPE POINT: POINT is a reserved word and cannot name a type
 

tests/read_data.c

@@ -8,6 +8,7 @@
  * TODO.md section 6.
  */
 
+#include <stdio.h>
 #include <string.h>
 
 #include <akbasic/error.h>
@@ -174,6 +175,34 @@ static void test_colon_ends_data(void)
     harness_stop();
 }
 
+/** @brief DATA overflow reports the line where the item limit was crossed. */
+static void test_data_prescan_error_line(void)
+{
+    char source[4096] = "";
+    size_t used = 0;
+    int line = 0;
+    int item = 0;
+
+    for ( line = 1; line <= 34; line++ ) {
+	used += (size_t)snprintf(source + used, sizeof(source) - used, "%d DATA ", line);
+	for ( item = 0; item < 15; item++ ) {
+	    used += (size_t)snprintf(source + used, sizeof(source) - used,
+				      "%s1", (item == 0 ? "" : ","));
+	}
+	used += (size_t)snprintf(source + used, sizeof(source) - used, "\n");
+    }
+	used += (size_t)snprintf(source + used, sizeof(source) - used, "100 DATA 1,1\n");
+	(void)snprintf(source + used, sizeof(source) - used, "101 DATA 1\n200 PRINT 1\n");
+
+    TEST_REQUIRE_OK(harness_start(NULL));
+    TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME, source));
+    TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+	TEST_REQUIRE(strstr(HARNESS_OUTPUT, "? 101 : PARSE ERROR") != NULL,
+		 "DATA overflow should report its source line, got \"%s\"",
+		 HARNESS_OUTPUT);
+    harness_stop();
+}
+
 /** @brief A float item fills a float variable with its fractional part intact. */
 static void test_float_items(void)
 {
@@ -227,6 +256,7 @@ int main(void)
     test_type_mismatch();
     test_quoted_items();
     test_colon_ends_data();
+	test_data_prescan_error_line();
     test_float_items();
     test_negative_items();
     return akbasic_test_failures;

tests/struct_types.c

@@ -218,6 +218,22 @@ static void test_declaration_errors_are_basic_errors(void)
     }
 }
 
+/** @brief A field declaration error reports the field's source line. */
+static void test_type_prescan_error_line(void)
+{
+    TEST_REQUIRE_OK(harness_start(NULL));
+    TEST_REQUIRE_OK(akbasic_runtime_load(&HARNESS_RUNTIME,
+					 "10 TYPE RECT\n"
+					 "20 W# EXTRA\n"
+					 "30 END TYPE\n"
+					 "40 PRINT 1\n"));
+    TEST_REQUIRE_OK(akbasic_runtime_start(&HARNESS_RUNTIME, AKBASIC_MODE_RUN));
+    TEST_REQUIRE(strstr(HARNESS_OUTPUT, "? 20 : PARSE ERROR") != NULL,
+		 "TYPE prescan should report its source line, got \"%s\"",
+		 HARNESS_OUTPUT);
+    harness_stop();
+}
+
 /**
  * @brief An over-long type or field name is refused, not silently trimmed.
  *
@@ -270,6 +286,7 @@ int main(void)
     test_missing_field_lists_the_others();
     test_self_by_value_refused();
     test_declaration_errors_are_basic_errors();
+    test_type_prescan_error_line();
     test_long_names_are_refused();
 
     return akbasic_test_failures;

tests/user_functions.c

@@ -183,6 +183,33 @@ static void test_structure_parameters(void)
     harness_stop();
 }
 
+/**
+ * @brief Pointer parameters do not consume value-pool slots per call.
+ *
+ * The pointer's parameter variable owns only one reference to the caller's
+ * record, so that reference can live in the variable's inline slot. The target
+ * remains in the caller's storage. One pointer parameter and 8,000 calls make
+ * one leaked slot per call fail against the 4,096-slot value pool.
+ */
+static void test_pointer_parameters_do_not_leak_value_slots(void)
+{
+    TEST_REQUIRE_OK(run_program_bounded("10 TYPE CRATE\n"
+					"20   W#\n"
+					"30 END TYPE\n"
+					"40 DIM A@ AS CRATE\n"
+					"50 DIM P@ AS PTR TO CRATE\n"
+					"60 POINT P@ AT A@\n"
+					"70 DEF POKEIT(P@ AS PTR TO CRATE)\n"
+					"80 P@->W# = P@->W# + 1\n"
+					"90 RETURN P@->W#\n"
+					"100 FOR I# = 1 TO 8000\n"
+					"110 R# = POKEIT(P@)\n"
+					"120 NEXT I#\n"
+					"130 PRINT A@.W#\n", 1000000));
+    TEST_REQUIRE_STR(HARNESS_OUTPUT, "8000\n");
+    harness_stop();
+}
+
 /**
  * @brief A structure parameter must name its type, and the type is checked.
  *
@@ -454,6 +481,7 @@ int main(void)
     test_runaway_recursion_is_diagnosed();
     test_single_expression_form();
     test_structure_parameters();
+    test_pointer_parameters_do_not_leak_value_slots();
     test_structure_parameter_types_are_checked();
     test_call_scopes_are_reclaimed();
     test_calls_do_not_leak_value_slots();