Document environment variable creation helpers

Andrew flagged the new helper introduced for the value-pool-leak fix
as missing documentation. akbasic_environment_create() and
akbasic_environment_create_empty() are already documented in the
header; the shared static helper they both call was the only
undocumented new function definition.

Co-authored-by: andrew <andrew@aklabs.net>

.gitea/workflows/mutation.yaml

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

.gitea/workflows/release.yaml

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

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

@@ -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

@@ -246,6 +246,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

@@ -118,12 +118,6 @@ 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];

src/environment.c

@@ -306,7 +306,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;
@@ -340,12 +356,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/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 int16_t *map, int64_t line)
+static int64_t mapped(const int64_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 int16_t *map = (const int16_t *)walk->self;
+    const int64_t *map = (const int64_t *)walk->self;
     int written = 0;
 
     PASS(errctx, aksl_snprintf(&written, dest, len, "%" PRId64, mapped(map, target)));
@@ -316,7 +316,8 @@ 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);
-    int16_t *map = obj == NULL ? NULL : obj->renumber_map;
+    static int64_t map[AKBASIC_MAX_SOURCE_LINES];
+    static akbasic_SourceLine rewritten[AKBASIC_MAX_SOURCE_LINES];
     akbasic_TargetWalk walk = { map, visit_renumber };
     int64_t next = newstart;
     int64_t i = 0;
@@ -355,8 +356,10 @@ akerr_ErrorContext *akbasic_renumber(akbasic_Runtime *obj, int64_t newstart, int
 	next += increment;
     }
 
-    PASS(errctx, aksl_memset(obj->renumber_visited, 0, sizeof(obj->renumber_visited)));
+    PASS(errctx, aksl_memset(rewritten, 0, sizeof(rewritten)));
     for ( i = 0; i < AKBASIC_MAX_SOURCE_LINES; i++ ) {
+	int64_t target = 0;
+
 	if ( obj->source[i].code[0] == '\0' ) {
 	    continue;
 	}
@@ -364,62 +367,20 @@ 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,
-				  obj->renumber_line.code, sizeof(obj->renumber_line.code)));
+				  rewritten[target].code, sizeof(rewritten[target].code)));
-	obj->renumber_line.lineno = i;
+	rewritten[target].lineno = target;
 	/*
 	 * 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.
 	 */
-	obj->renumber_line.numbered = true;
+	rewritten[target].numbered = true;
-	PASS(errctx, aksl_memcpy(&obj->source[i], &obj->renumber_line,
-				 sizeof(obj->source[i])));
     }
 
-    /* Move the already-rewritten lines in place. The map is a partial
+    PASS(errctx, aksl_memcpy(obj->source, rewritten, sizeof(obj->source)));
-     * 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_memcpy(&displaced, &obj->source[i], sizeof(displaced)));
-	for ( ;; ) {
-	    int64_t destination = map[current];
-
-	    obj->renumber_visited[current] = 1;
-	    if ( destination == i ) {
-		displaced.lineno = destination;
-		PASS(errctx, aksl_memcpy(&obj->source[destination], &displaced,
-					 sizeof(displaced)));
-		break;
-	    }
-	    if ( map[destination] < 0 ) {
-		displaced.lineno = destination;
-		PASS(errctx, aksl_memcpy(&obj->source[destination], &displaced,
-					 sizeof(displaced)));
-		PASS(errctx, aksl_memset(&obj->source[current], 0,
-					 sizeof(obj->source[current])));
-		break;
-	    }
-	    PASS(errctx, aksl_memcpy(&next_line, &obj->source[destination],
-				     sizeof(displaced)));
-	    displaced.lineno = destination;
-	    PASS(errctx, aksl_memcpy(&obj->source[destination], &displaced,
-				     sizeof(obj->renumber_line)));
-	    PASS(errctx, aksl_memset(&obj->source[current], 0,
-				     sizeof(obj->source[current])));
-	    PASS(errctx, aksl_memcpy(&displaced, &next_line,
-				     sizeof(displaced)));
-	    current = destination;
-	}
-    }
     SUCCEED_RETURN(errctx);
 }
 
@@ -474,6 +435,7 @@ 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;
@@ -501,8 +463,7 @@ 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,
+	PASS(errctx, rewrite_line(&walk, obj->source[i].code, discard, sizeof(discard)));
-				 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

@@ -989,12 +989,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]));

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/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();