Execute every documented example as a test
docs/ and README.md carry 85 fenced blocks. Every one was checked by hand
exactly once, when it was written, which is not a standard that survives a
changing interpreter -- and four were already wrong: two transcripts showing a
leading space PRINT does not emit, akbasic_TextSink in README.md missing the
two members it had grown hours earlier, and FILTER's refusal quoted with
wording the code does not use.
tests/docs_examples.sh reads a fence-tag vocabulary and runs what it finds.
BASIC programs and transcripts run and are byte-compared against an `output`
block; C snippets compile with -fsyntax-only against the real include path,
which CMake writes out because it is transitive through akerror, akstdlib and
akgl; shell blocks run in a sandbox. Anything that would reconfigure the build
tree, hit the network or re-enter the suite is tagged norun with the reason in
MAINTENANCE.md, and the two cmake blocks stay hand-maintained by decision.
An untagged block is a failure rather than a default, and the pass line
reports what it executed by kind. Both exist because the way a harness like
this dies is by quietly matching nothing and passing -- which it duly did on
the first CTest run, where a generator expression evaluating to nothing still
contributed an empty argument that the script read as a filename. The count is
what caught it.
The excerpt check earns its own mention: a block tagged
`c excerpt=include/akbasic/sink.h` must still appear in that header, comments
and whitespace ignored. Compiling it would only redefine the type, so a
compile check could not have found the stale struct, and did not.
Registered as the CTest case docs_examples in both configurations. Fixing the
four wrong examples turned up two interpreter defects, fixed in the previous
commit and recorded in TODO.md section 8.
MAINTENANCE.md is new: the fence-tag reference, what to do when the case
fails, and the conventions that until now only existed inside source comments
-- the three test lists and how two of them invert "passed", the sorted verb
table, that a golden file is never edited to suit this interpreter, and that a
fix gets mutation-checked with a file copy rather than git checkout.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:41:36 -04:00
# Maintaining akbasic
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
`README.md` is for people evaluating the interpreter. `docs/` is for people writing BASIC in
it. This file is for whoever has to change the thing: what the project is trying to be, how
the build fits together, and the conventions — the ones enforced by a test, and the ones
enforced by nothing at all and therefore written down here.
`CLAUDE.md` is for agents, and it is deliberately thin: it points here. Everything an agent
is told about this project is in this file, so there is one copy to keep true.
Document the interpreter's architecture as chapter fourteen
Chapters 1 through 13 describe the language. Nothing described the machine
that runs it, and the answers were spread across header comments, TODO.md
sections written for a different purpose, and the source itself. Somebody
embedding the interpreter, debugging something it did, or adding a verb had
to reconstruct the shape from all three.
docs/14-architecture.md is that shape, and only that: the three targets and
the driver, the single akbasic_Runtime and why nothing is file-scope,
akbasic_runtime_step() unrolled with the reason each stage sits where it
does, the four modes and what set_mode() does beyond assigning, a line's
journey from text through tokens and leaves to a verb handler, the dispatch
table, the pool map with what each exhaustion actually says, environments
doubling as block state, the two kinds of error, devices, and interrupts.
It defers rather than restates. The headers are the authority on every
function's contract and the chapter says so up front; where a rule is subtle
the header comment already states it at more length than a chapter should.
MAINTENANCE.md keeps the conventions and now points here for the mechanism,
so there is still one copy of each.
Two sections are the reason it exists at all. Debugging: reading a TRON trace
as evidence about the loop rather than the lines, reading an akerror stack
trace and what it is not, four breakpoints and the expressions worth printing
at them, narrowing with ctest -R and the mock devices, and a symptom-to-cause
table. Changing it: the verb recipe end to end including the private
src/verbs.h prototype that is easy to miss, the rule that a missing
dependency capability gets filed upstream rather than worked around, and the
five constraints goal 3 puts on any change.
A `text` fence tag comes with it. Every fenced block in docs/ is executed and
an untagged one is a hard error, so six block diagrams had nowhere to live.
The tag means never executed, it is counted in the skip line like `cmake`,
and MAINTENANCE.md documents it -- the alternative was an indented block the
extractor never sees, and a picture nobody decided about is indistinguishable
from a test nobody ran.
tests/docs_examples.sh now makes --root and --basic absolute before it
starts. Both are used from inside a sandbox directory it cd's into, so the
invocation MAINTENANCE.md itself documents -- --root . --basic ./build/basic
-- failed every example with "exited 127" and every setup= with "setup
failed". CTest passes absolute paths and never saw it; running one document
by hand hits it immediately.
Writing the error section turned up a defect and TODO.md section 8 records
it. The ATTEMPT blocks that turn a script's mistake into an error line wrap
parsing and interpretation but not scanning, so a line with more than 32
tokens escapes as an interpreter error: stack trace, exit 1, and at a prompt
the REPL is gone. That is the same shape as section 8 item 2, on a path that
fix did not cover. Not fixed here -- it is a behaviour change and wants its
own tests -- but written down with the three call sites and what would cover
them.
Both configurations stay green: 95/95 and 94/94. docs_examples now runs 37
programs, 9 transcripts, 45 output comparisons, 3 C snippets, 2 excerpts and
2 shell blocks, and skips 9 text blocks.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 23:14:17 -04:00
One thing is deliberately * not * here. **How the interpreter actually works — the step loop,
the four modes, the pools, the scopes that double as block state, the two kinds of error,
and how to debug all of it — is [`docs/14-architecture.md` ](docs/14-architecture.md ).** This
file is the conventions for changing the thing; that chapter is the thing.
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
---
## What this project is
`akbasic` is a **C rewrite of the Go BASIC interpreter in `deps/basicinterpret` ** , written in
the idiom of the `ak*` C libraries it builds on.
| Submodule | Language | Role |
|---|---|---|
| `deps/basicinterpret` | Go | The implementation that was rewritten; the behavioural spec for questions about semantics |
| `deps/libakerror` | C | TRY/CATCH-style error contexts — the substrate every other `ak*` library is built on |
| `deps/libakstdlib` | C | libc and data-structure wrappers that report through `libakerror` |
| `deps/libakgl` | C | SDL3-based game/graphics library (sprites, text, tilemaps, actors, heap) — supplies all multimedia |
### The goals, in priority order
1. **Port Go → C. ** Reproduce the reference interpreter in C: `akerr_ErrorContext *` returns
everywhere, fixed-size pools instead of dynamic allocation, library-prefixed symbols,
one-file CTest executables. The Go code is already written against static pools and
explicit state structs, so it ports fairly directly — resist "improving" it into
`malloc` -based data structures. SDL2/SDL2_ttf calls in the Go version become `libakgl`
calls (`akgl_text_*` , the renderer, the registry), not raw SDL3 calls.
2. **Finish the language. ** The full Dartmouth BASIC and Commodore 128 BASIC 7.0 verb and
function set. `deps/basicinterpret/README.md` ends with the original's list of what was
Point the agent instructions at the issue tracker for outstanding work
This repository has no AGENTS.md; CLAUDE.md and MAINTENANCE.md carry the same
rules, so both are updated.
Outstanding work is an issue on the forge now, with the file and line, the
functional consequence, and what closing it would touch. TODO.md is the record
-- settled design decisions, the deviation register, defects already fixed, and
the reasoning behind the measurements -- and its row in CLAUDE.md's reading
table says so, with the tracker listed above it.
The dependency rule gains the correction this migration produced. 'Never work
around a missing dependency capability here' now says to open an issue in that
repository's tracker, and says plainly that recording it here instead is not
filing it: two akgl_ui gaps sat in TODO.md for a release on the reasoning that
changing a submodule is that repository's decision, which is true of changing it
and not of reporting it. Both are libakgl issues now.
Cross-repository citations of deps/*/TODO.md sections point at the trackers.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 19:25:05 -04:00
unimplemented, and that list was the work queue. Every group of it is done; what remains is
in the issue tracker and is summarised for a BASIC programmer in `docs/13-differences.md` . A few entries are
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
deliberately out of scope on a modern PC — `BANK` , `FAST` , `MONITOR` , and `SPRDEF` , which
is an interactive editor rather than a programmable verb. Keep that reasoning rather than
reviving them.
3. **Be embeddable. ** The end state is the interpreter linking * into * `libakgl` as a
scripting engine for game authors. That constrains the design from the start:
- The interpreter is a library target with a thin `src/main.c` driver on top. The REPL,
`QUIT` and argv handling belong to the driver, not the library.
- Interpreter state lives in explicit structs passed by pointer. No file-scope mutable
globals.
- **Nothing in the library may terminate the process.** Errors propagate out as
`akerr_ErrorContext *` for the host game to handle; `FINISH_NORETURN` belongs only in a
`main()` .
- The interpreter owns no window, renderer or game loop. It draws through whatever `akgl`
renderer the host already initialized, and a host must be able to bound execution rather
than surrender control to a `run()` that never returns.
### Missing capabilities get filed upstream, not worked around
**When `libakgl` — or `libakstdlib` — cannot supply something a verb needs, do not work
Point the agent instructions at the issue tracker for outstanding work
This repository has no AGENTS.md; CLAUDE.md and MAINTENANCE.md carry the same
rules, so both are updated.
Outstanding work is an issue on the forge now, with the file and line, the
functional consequence, and what closing it would touch. TODO.md is the record
-- settled design decisions, the deviation register, defects already fixed, and
the reasoning behind the measurements -- and its row in CLAUDE.md's reading
table says so, with the tracker listed above it.
The dependency rule gains the correction this migration produced. 'Never work
around a missing dependency capability here' now says to open an issue in that
repository's tracker, and says plainly that recording it here instead is not
filing it: two akgl_ui gaps sat in TODO.md for a release on the reasoning that
changing a submodule is that repository's decision, which is true of changing it
and not of reporting it. Both are libakgl issues now.
Cross-repository citations of deps/*/TODO.md sections point at the trackers.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 19:25:05 -04:00
around it here.** Open an issue in that repository's tracker on
<https://source.starfort.tech> describing the missing API: what the BASIC verb requires, what
the `akgl_*` or `aksl_*` entry point should look like, and what tests would cover it.
**Recording it in this repository instead is not filing it** — two `akgl_ui` gaps sat in
`TODO.md` for a release on the reasoning that changing a submodule is that repository's
decision, which is true of * changing * it and not of * reporting * it. Follow the prose-paragraph style of the entries already
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
there. Growing the dependency to serve the interpreter is a wanted outcome, not a detour.
It works. Four gaps were filed this way — text measurement, immediate-mode drawing, audio,
and a non-blocking keystroke read — and all four landed upstream as `akgl_text_measure` , the
`akgl_draw_*` family, `akgl_audio_*` and `akgl_controller_poll_key` . `FILTER` is the one verb
still blocked on a gap, and `DIRECTORY` is refused pending an `opendir` /`readdir` wrapper in
`libakstdlib` . Both refuse at execution and say so, rather than being silently ignored: a
program that asks for a low-pass filter and gets an unfiltered square wave has been lied to.
### The Go reference
`deps/basicinterpret` is a Commodore BASIC 7.0 / Dartmouth BASIC dialect in Go with SDL2 +
SDL2_ttf. It is the behavioural spec: when a question about semantics comes up — "what does
`READ` do when it runs off the end of `DATA` ?" — the answer lives in that code.
**That project is deprecated and this interpreter is no longer required to match it.**
`TODO.md` §0.1 retires the byte-for-byte fidelity constraint that several sections of that
file were originally written on. The corpus stays green as a * regression * suite; the Go
source stays readable as documentation of what the original did. Neither is binding.
**It is not a build or test dependency.** Both configurations have been configured, built and
run from scratch with it moved out of the tree. Its acceptance corpus is checked in at
2026-08-04 16:21:59 -04:00
`tests/language/` and its Commodore font at `assets/fonts/` .
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
```sh norun
cd deps/basicinterpret
make # builds ./basic (CGO_ENABLED=1, needs SDL2 + SDL2_ttf dev packages)
./basic # interactive REPL
./basic tests/language/functions.bas
make tests # or: bash ./test.sh
```
#### Its architecture, and the two decisions that shaped ours
Scanner → parser → tree-walking runtime, one source line at a time:
- `basicscanner.go` — tokenizes a line into `BasicToken` s. Verbs and function names are
case-insensitive; variable names are case-sensitive.
- `basicparser.go` / `basicparser_commands.go` — recursive-descent parser producing
`BasicASTLeaf` nodes; `basicgrammar.go` defines the leaf types. Commands get their own parse
paths.
- `basicruntime.go` — owns the source (`[MAX_SOURCE_LINES]BasicSourceLine` ), the variable
pool, the scanner/parser, the environment stack and the SDL window. `commandByReflection()`
dispatches a verb to a method by name, so adding a verb there was mostly a matter of adding
a correctly-named method. **We use a sorted dispatch table instead ** — see below.
- `basicenvironment.go` — a scope * and * the per-line working state: variables, functions,
labels, plus the in-flight state of `IF` /`FOR` /`GOSUB` /`READ` . Environments chain via
`parent` .
- `basicvalue.go` / `basicvariable.go` — the strongly-typed value and the named slot. Type is
carried by the identifier suffix: `#` integer, `%` float, `$` string.
- `basicruntime_graphics.go` — output goes through an SDL text surface with a cursor, wrapped
text, scrolling and a print buffer. `Write()` and `Println()` **mirror every line to
stdout**, and that mirror is the only reason a golden-file suite is possible at all. Our
`akbasic_TextSink` , and `akbasic_sink_init_tee()` in particular, is the equivalent.
1. **Everything is fixed-size and statically allocated. ** `main.go` set the budget:
`MAX_LEAVES` /`MAX_TOKENS` 32 per environment, `MAX_VALUES` 64, `MAX_VARIABLES` 128,
`MAX_SOURCE_LINES` 9999, `MAX_LINE_LENGTH` 256, `MAX_ARRAY_DEPTH` 64. The 32-leaf ceiling
is why a line is limited to roughly 16 operations. Ours are in `include/akbasic/types.h`
and are the same numbers plus three the Go version did not need because it called `make()` .
2. * * `waitingForCommand` drives block structure.** Rather than building nested blocks in the
AST, the environment records a verb it is skipping forward to (`NEXT` , `RETURN` , …) and
suppresses execution of intervening lines until it sees it. Loops and branches evaluate
their condition at the * bottom * of the structure. We reproduce this, and it is the reason a
whole `FOR ... NEXT` written on one line does not loop — block skipping walks source
* lines * .
Runtime modes are `MODE_REPL` , `MODE_RUN` , `MODE_RUNSTREAM` (piped input) and `MODE_QUIT` ;
`BASIC_TRUE` is `-1` and `BASIC_FALSE` is `0` , per Commodore convention. All of that carried
over.
---
## Building
```sh norun
git submodule update --init --recursive
cmake -S . -B build
cmake --build build --parallel
ctest --test-dir build --output-on-failure
```
### Build everything from the submodules, in one tree
`libakgl` vendors its * own * copies of `libakerror` and `libakstdlib` (plus SDL3, SDL3_image,
SDL3_mixer, SDL3_ttf, jansson and semver) under `deps/libakgl/deps/` . Its `CMakeLists.txt`
guards every dependency with `if(NOT TARGET ...)` , so a top-level build must define
`akerror::akerror` and `akstdlib::akstdlib` from `deps/libakerror` and `deps/libakstdlib`
**before** `add_subdirectory(deps/libakgl)` , or the targets are declared twice.
Take libakerror 2.0.1, and guard the exit status it fixes
2.0.0 makes the error pool and the status registry thread safe, and it is an ABI
break carrying the soname to libakerror.so.2. The break is a quiet one:
__akerr_last_ignored became thread-local and akerr_next_error() now returns a
context that already holds a reference, so objects compiled against a 1.x header
and linked against 2.x count every reference twice and never give a slot back.
Nothing about that fails to link, which is exactly what a guard is for --
include/akbasic/error.h feature-tests AKERR_THREAD_SAFE instead of
AKERR_FIRST_CONSUMER_STATUS, which 2.0.0 also still defines and which therefore
no longer distinguishes anything.
2.0.1 is the release this band needed most. The default unhandled-error handler
ended in exit(errctx->status), and a process exit status is one byte:
AKBASIC_ERR_BASE is 512, and 512 truncates to 0, so an unhandled
AKBASIC_ERR_SYNTAX reported success to anything watching $?. Every other code in
the band came out as some unrelated error's number. akerr_exit() substitutes 125
for anything a byte cannot carry, and a probe raising AKBASIC_ERR_DEVICE through
FINISH_NORETURN now exits 125 rather than 7.
It was latent here rather than live -- src/main.c handles the context and returns
EXIT_FAILURE, and every test with a top-level ATTEMPT carries a HANDLE_DEFAULT --
but "no caller relies on it today" is not a property a header can keep true.
tests/version_check.c asserts the mapping and fails if AKBASIC_ERR_BASE ever
stops truncating to zero, because that is the day this stops being about our base.
Chapter 10 gains a threading section: libakerror is safe from any thread now, and
this interpreter is not and has no lock anywhere in it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-01 08:00:24 -04:00
That order is load-bearing for a second reason: `deps/libakerror` is at **2.0.1 ** , whose 2.0.0
was a source and ABI break carrying an soname (`libakerror.so.2` ). `libakstdlib` and `libakgl`
must be compiled against that header, not a 1.x one, and an installed `libakerror.so.1` must
not be picked up. The break is quiet if you get it wrong: `__akerr_last_ignored` became
thread-local and `akerr_next_error()` now returns a context that already holds a reference, so
a mixed build leaks pool slots or frees one twice rather than failing to link.
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
### Dependency versions and what they promise
| Submodule | Version | soname | ABI rule | Version API |
|---|---|---|---|---|
Take libakerror 2.0.1, and guard the exit status it fixes
2.0.0 makes the error pool and the status registry thread safe, and it is an ABI
break carrying the soname to libakerror.so.2. The break is a quiet one:
__akerr_last_ignored became thread-local and akerr_next_error() now returns a
context that already holds a reference, so objects compiled against a 1.x header
and linked against 2.x count every reference twice and never give a slot back.
Nothing about that fails to link, which is exactly what a guard is for --
include/akbasic/error.h feature-tests AKERR_THREAD_SAFE instead of
AKERR_FIRST_CONSUMER_STATUS, which 2.0.0 also still defines and which therefore
no longer distinguishes anything.
2.0.1 is the release this band needed most. The default unhandled-error handler
ended in exit(errctx->status), and a process exit status is one byte:
AKBASIC_ERR_BASE is 512, and 512 truncates to 0, so an unhandled
AKBASIC_ERR_SYNTAX reported success to anything watching $?. Every other code in
the band came out as some unrelated error's number. akerr_exit() substitutes 125
for anything a byte cannot carry, and a probe raising AKBASIC_ERR_DEVICE through
FINISH_NORETURN now exits 125 rather than 7.
It was latent here rather than live -- src/main.c handles the context and returns
EXIT_FAILURE, and every test with a top-level ATTEMPT carries a HANDLE_DEFAULT --
but "no caller relies on it today" is not a property a header can keep true.
tests/version_check.c asserts the mapping and fails if AKBASIC_ERR_BASE ever
stops truncating to zero, because that is the day this stops being about our base.
Chapter 10 gains a threading section: libakerror is safe from any thread now, and
this interpreter is not and has no lock anywhere in it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-01 08:00:24 -04:00
| `deps/libakerror` | 2.0.1 | `libakerror.so.2` | major only | **none ** — no version macro; `include/akbasic/error.h` feature-tests `AKERR_THREAD_SAFE` and `AKERR_EXIT_STATUS_UNREPRESENTABLE` instead |
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
| `deps/libakstdlib` | 0.2.0 | `libakstdlib.so.0.2` | * * `MAJOR.MINOR` while major is 0** | `AKSL_VERSION_*` , `aksl_version()` , `AKSL_VERSION_CHECK()` |
Take libakgl 0.9.0, and shadow set_property(TEST) so it configures
0.9.0 is the akgl_ui subsystem: a vendored clay, an arena, menus, HUDs and
dialogs, reached through a new akgl/ui.h this project does not include. Every
header the akbasic_akgl target actually compiles against is byte-identical to
0.8.0, so unlike the 0.8.0 bump there is no sizeof to get wrong. The floor in
include/akbasic/akgl.h moves to 0.9.0 anyway, on the standing rule that the
soname carries MAJOR.MINOR while the major is 0.
It does not configure as it stands. 0.9.0 moved eight test property calls off
set_tests_properties -- correctly, because that command splits a
semicolon-separated value and had been silently reducing its LD_LIBRARY_PATH
prepend list to one directory -- onto set_property(TEST ...). This repository
suppresses add_test() while it pulls its dependencies in, so those test names do
not exist, and set_property errors on an unknown test name where
set_tests_properties was silent: eight hard configure failures. Shadow
set_property in its TEST form only; every other form has to pass through, since
the dependencies set target and directory properties their own builds need.
libakgl's status band grew to seven codes with AKGL_ERR_UI and it now owns 256
to 262, so the coordinated range map, docs/15-error-codes.md and both header
comments follow. TODO.md section 5's persistent-drawing-layer item still stands:
0.9.0's arena draws inside the frame like everything else, and there is still no
render-to-texture layer.
Both configurations build and both suites pass -- 110/110 without libakgl,
111/111 with it, akgl_typing included.
Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 16:56:52 -04:00
| `deps/libakgl` | 0.9.0 | `libakgl.so.0.9` | * * `MAJOR.MINOR` while major is 0** | `AKGL_VERSION*` , `akgl_version()` , `AKGL_VERSION_AT_LEAST()` |
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
For both 0.x libraries the soname carries `MAJOR.MINOR` deliberately: 0.1 and 0.2 are
*different* ABIs, and both become major-only at 1.0. Do not read `0.1 → 0.2` as a compatible
bump — both libraries have actually made that jump, so anything built against the 0.1 headers
must be rebuilt rather than relinked.
**`libakstdlib` and `libakgl` move together and have to.** `libakgl` 0.2.0 consumes the
`libakstdlib` 0.2.0 API, so a tree pinning `libakstdlib` at 0.1.0 while adding `libakgl` by
`add_subdirectory()` compiles 0.2.0-era code against 0.1.0 headers and fails on `aksl_fwrite` ,
`aksl_fread` and `aksl_realpath` . Bump them as a pair.
`akstdlib.h` pulls in `<akstdlib_version.h>` , which CMake **generates into the build tree ** and
installs beside `akstdlib.h` — so link `akstdlib::akstdlib` and let the target carry its
include directories. Hand-adding `deps/libakstdlib/include` to an include path gets you a
missing-header error. It records what the caller was * compiled * against, and `aksl_version()`
reports what actually * loaded * . `AKSL_VERSION_CHECK()` compares them and raises `AKERR_VALUE`
naming both. **Call it once during initialization ** : the soname normally catches a mismatch at
load time, but a 0.2.0 dropped in under the 0.1 filename loads happily and only the check
notices. It is a macro on purpose — it must expand at your call site to capture your numbers.
`libakgl` followed the same pattern. `project(akgl VERSION ...)` is the single source and
drives the generated `include/akgl/version.h` , which is `.gitignore` d because `include/`
precedes the build tree on the include path and a stray copy there would shadow the generated
one and pin every consumer. It publishes `AKGL_VERSION_AT_LEAST(major, minor, patch)` — the
compile-time test `libakstdlib` could not write against `libakerror` — and `akgl_version()` .
**Version-pinning in `find_package` is asymmetric, and that is deliberate.**
`find_package(akstdlib 0.1)` and `find_package(akgl 0.1)` both work; each ships a
`ConfigVersion.cmake` at `SameMinorVersion` , mirroring its soname. `find_package(akerror 1.0)`
**fails against a correct install**, because `libakerror` ships `akerrorConfig.cmake` and
`akerrorTargets.cmake` but no `akerrorConfigVersion.cmake` . Ask for `akerror` unversioned. Its
floor is enforced instead by an `#error` feature-testing `AKERR_FIRST_CONSUMER_STATUS` , which
`akstdlib.h` , `akgl/error.h` and our own `include/akbasic/error.h` all carry — include any of
them and you inherit the guard. The missing version file is filed in
Move outstanding work from TODO.md into the issue tracker
Twenty-six issues on source.starfort.tech/andrew/akbasic, labelled by kind and
blast radius and milestoned by what they can land in: 0.1.x for anything that
changes no public contract, 0.2.0 for new verbs and observable behaviour
changes, 1.0.0 for the design decisions. Everything carries status::grooming.
Block surgery rather than a rewrite. Every open item is replaced by a line
saying what it was and which issue carries it; everything else -- the settled
design decisions, the deviation register, the fixed defects and the reasoning
behind the measurements -- is byte-identical. 3338 lines to 2966.
Two corrections found while doing it. The "what remains, in priority order"
list named groups A, D, F, J and H as outstanding language work; SS4's own table
shows every one of them done, and what actually survives is one piece of
structural work that is not a verb -- block skipping by source line, which is
why a whole FOR/NEXT on one line never loops. And the two UI gaps SS7 recorded
and declined to file are now libakgl #79 and #80: that section's rule is right
that changing a dependency is that repository's decision, and it does not
follow that reporting the gap is.
Cross-repository references to deps/*/TODO.md sections are repointed at the
trackers that now hold them, here and in MAINTENANCE.md.
Verified: cmake --build build && ctest --test-dir build, 112/112.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 19:08:31 -04:00
`libakstdlib` issue #5 and `libakerror` issue #16 ; when it lands, add the `1.0` floor to the `find_dependency`
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
calls.
### Embedding all three dependencies collides four ways
All three libraries register their CTest tests unconditionally and add coverage and mutation
targets. A top-level build that `add_subdirectory` s them walks into four separate collisions.
The handling is at the top of `CMakeLists.txt` , and its comments carry the same detail.
**1. Duplicate CTest entries.** Every dependency's tests register into * our * suite. Under
`EXCLUDE_FROM_ALL` their binaries are never built, so each lands as "Not Run" and fails. CMake
offers no way to un-register a test, and `set_tests_properties` cannot reach across directory
scopes. We shadow `add_test()` and `set_tests_properties()` for the duration of the
`add_subdirectory()` calls. `libakstdlib` carries the same shadow but only arms it when * it *
is top-level, so it does nothing for us — ours has to wrap all three.
Take libakgl 0.9.0, and shadow set_property(TEST) so it configures
0.9.0 is the akgl_ui subsystem: a vendored clay, an arena, menus, HUDs and
dialogs, reached through a new akgl/ui.h this project does not include. Every
header the akbasic_akgl target actually compiles against is byte-identical to
0.8.0, so unlike the 0.8.0 bump there is no sizeof to get wrong. The floor in
include/akbasic/akgl.h moves to 0.9.0 anyway, on the standing rule that the
soname carries MAJOR.MINOR while the major is 0.
It does not configure as it stands. 0.9.0 moved eight test property calls off
set_tests_properties -- correctly, because that command splits a
semicolon-separated value and had been silently reducing its LD_LIBRARY_PATH
prepend list to one directory -- onto set_property(TEST ...). This repository
suppresses add_test() while it pulls its dependencies in, so those test names do
not exist, and set_property errors on an unknown test name where
set_tests_properties was silent: eight hard configure failures. Shadow
set_property in its TEST form only; every other form has to pass through, since
the dependencies set target and directory properties their own builds need.
libakgl's status band grew to seven codes with AKGL_ERR_UI and it now owns 256
to 262, so the coordinated range map, docs/15-error-codes.md and both header
comments follow. TODO.md section 5's persistent-drawing-layer item still stands:
0.9.0's arena draws inside the frame like everything else, and there is still no
render-to-texture layer.
Both configurations build and both suites pass -- 110/110 without libakgl,
111/111 with it, akgl_typing included.
Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 16:56:52 -04:00
`set_property(TEST ...)` has to be shadowed alongside them, and **only in its `TEST` form ** .
`libakgl` 0.9.0 moved eight of these calls off `set_tests_properties` , correctly: that command
parses its arguments as name/value pairs, so a semicolon-separated value is split and every
element after the first is consumed as a bogus property name — which silently reduced its
`LD_LIBRARY_PATH` prepend list to one directory. `set_property` does not split. But with
`add_test()` suppressed the tests those calls name do not exist, and `set_property` **errors **
on an unknown test name where `set_tests_properties` was silent, so pulling 0.9.0 in turned
eight quiet no-ops into eight hard configure failures. Every other form — `GLOBAL` ,
`DIRECTORY` , `TARGET` , `SOURCE` , `INSTALL` , `CACHE` — must pass straight through; the
dependencies set target and directory properties their own builds depend on.
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
**Only one project in a tree may shadow `add_test()` , and this is that project.** CMake
exposes an overridden command as `_name` and chains exactly one level: a second override
rebinds `_add_test` to the first override and the builtin becomes unreachable to everyone, so
our own registrations recurse until CMake stops at *"Maximum recursion depth of 1000
exceeded"*. `libakgl` 0.3.0 briefly shadowed it unconditionally and that is exactly what
happened.
**2. Duplicate test * target * names.** `add_subdirectory` creates a dependency's targets even
under `EXCLUDE_FROM_ALL` . When `libakstdlib` added `tests/test_version.c` it collided with
`libakgl` 's and stopped the configure dead:
add_executable cannot create target "test_version" because another target with the same
name already exists.
`libakgl` fixed its side by building programs as `akgl_test_<name>` while keeping the bare
CTest names. `libakstdlib` still uses bare `test_<name>` targets. **Name every test target in
this repo `akbasic_test_<name>` ** — it costs nothing and it is the collision that actually
stopped a build.
**3. Duplicate custom targets.** `libakerror` namespaces its `mutation` target when embedded
but **not ** its `coverage` target, so any coverage-enabled top-level build fails with *"another
target with the same name already exists"*. We shadow `add_custom_target` and rename that one
to `akerror_coverage` on the way past. `libakstdlib` (both targets) and `libakgl` (its
`mutation` target) namespace themselves correctly. **The real fix is upstream in
`libakerror` ** — the same `CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR` test it already
Move outstanding work from TODO.md into the issue tracker
Twenty-six issues on source.starfort.tech/andrew/akbasic, labelled by kind and
blast radius and milestoned by what they can land in: 0.1.x for anything that
changes no public contract, 0.2.0 for new verbs and observable behaviour
changes, 1.0.0 for the design decisions. Everything carries status::grooming.
Block surgery rather than a rewrite. Every open item is replaced by a line
saying what it was and which issue carries it; everything else -- the settled
design decisions, the deviation register, the fixed defects and the reasoning
behind the measurements -- is byte-identical. 3338 lines to 2966.
Two corrections found while doing it. The "what remains, in priority order"
list named groups A, D, F, J and H as outstanding language work; SS4's own table
shows every one of them done, and what actually survives is one piece of
structural work that is not a verb -- block skipping by source line, which is
why a whole FOR/NEXT on one line never loops. And the two UI gaps SS7 recorded
and declined to file are now libakgl #79 and #80: that section's rule is right
that changing a dependency is that repository's decision, and it does not
follow that reporting the gap is.
Cross-repository references to deps/*/TODO.md sections are repointed at the
trackers that now hold them, here and in MAINTENANCE.md.
Verified: cmake --build build && ctest --test-dir build, 112/112.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 19:08:31 -04:00
applies to `mutation` — and it is filed as `libakerror` issue #15 . Delete the
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
workaround when it lands.
**4. Stale build trees poison the coverage report.** See below; it is the reason for
`cmake -S . -B build` .
### Build trees stay out of the source directory
`gcovr` searches for `.gcda` /`.gcno` under its `--root` , and the dependencies set that to
their * source * directory — so a leftover instrumented build tree in the source dir is folded
into the report, and `--object-directory` does not narrow the search. A leftover
`build-coverage/` makes a freshly configured run fail in `coverage_reset` , before any test
executes, with `Got function ... on multiple lines` . Because `build*/` is `.gitignore` d, the
state is easy to reach and hard to see. Always `cmake -S . -B build` .
### Optional tooling, and what each one buys
Everything builds and tests with cmake and a C compiler. Three tools are optional, and each
buys a specific test rather than general convenience:
| Tool | Buys | Without it |
|---|---|---|
| `xdotool` + `script` (1) | `akgl_typing` — types at a real focused SDL window with a real keyboard | The test reports **Skipped ** . Nothing fails |
| `gcovr` | the `coverage` target and its 90%-of-lines gate | `-DAKBASIC_COVERAGE=ON` will not configure |
| `python3` | `scripts/mutation_test.py` and the `mutation` target | The target is not created |
**`akgl_typing` is worth installing `xdotool` for.** It is the only test that exercises the
path a person actually uses — X11 delivers a key press to a focused window, SDL composes it,
libakgl rings it, the editor echoes it, the interpreter runs it. Every other keyboard test
synthesises SDL events, which tests the code * downstream * of SDL and cannot test the code
upstream of it. That gap shipped a bug: the frontend never called `SDL_StartTextInput()` , so
SDL emitted no text-input events at all, the line editor dropped every keystroke, and the
whole suite stayed green because it was pushing those events itself.
It needs a real X server and **it steals keyboard focus for about fifteen seconds ** . Set
`AKBASIC_SKIP_INTERACTIVE=1` to skip it while you are using the machine. It skips itself when
there is no display, no `xdotool` , or no window manager answering — CTest reports `Skipped`
rather than a failure, because none of those means the answer is no.
### The two workflows
**`.gitea/workflows/ci.yaml` ** runs on every push: the suite, ASan+UBSan, coverage gated at
90% of lines, and mutation testing over two files. The coverage report is uploaded as a
`code-coverage` artifact.
**`.gitea/workflows/release.yaml` ** is manual (`workflow_dispatch` ) and is what a release
runs. It builds the API documentation and uploads it as `api-documentation` , and it mutates
the * whole * `src/` tree — 3675 mutants, hours of runner time, which is why it is not on the
push path. It takes two optional inputs: a mutation threshold, and a space-separated file
list to narrow the run.
### API documentation is a gate, not a convenience
```sh norun
doxygen Doxyfile
```
The `Doxyfile` is configured the way `libakgl` 's is, including
`WARN_AS_ERROR = FAIL_ON_WARNINGS` — a doc block that documents some of a function's
parameters but not all of them fails the run. Every public declaration under
`include/akbasic/` carries a `@brief` , a `@param` per parameter, a `@return` and its
`@throws` . Keep it that way when you add one.
---
## Tests
### Three lists, and two of them invert "passed"
`CMakeLists.txt` declares `AKBASIC_TESTS` , `AKBASIC_WILL_FAIL_TESTS` and
`AKBASIC_KNOWN_FAILING_TESTS` . The first must exit 0. The second aborts by design. The
Point the agent instructions at the issue tracker for outstanding work
This repository has no AGENTS.md; CLAUDE.md and MAINTENANCE.md carry the same
rules, so both are updated.
Outstanding work is an issue on the forge now, with the file and line, the
functional consequence, and what closing it would touch. TODO.md is the record
-- settled design decisions, the deviation register, defects already fixed, and
the reasoning behind the measurements -- and its row in CLAUDE.md's reading
table says so, with the tracker listed above it.
The dependency rule gains the correction this migration produced. 'Never work
around a missing dependency capability here' now says to open an issue in that
repository's tracker, and says plainly that recording it here instead is not
filing it: two akgl_ui gaps sat in TODO.md for a release on the reasoning that
changing a submodule is that repository's decision, which is true of changing it
and not of reporting it. Both are libakgl issues now.
Cross-repository citations of deps/*/TODO.md sections point at the trackers.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 19:25:05 -04:00
third **asserts the correct contract for a defect that has an open issue ** and is
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
expected to fail.
A green `ctest` therefore does not mean defect-free. When a known-failing test starts
passing, CTest reports "unexpectedly passed" — that is the cue to move it into
`AKBASIC_TESTS` along with the fix, not to delete it.
`AKBASIC_WILL_FAIL_TESTS` is currently empty and is kept declared anyway, so the shape is
there when it is next needed.
The dependencies use the same split under their own prefixes: `AKSL_TESTS` /
`AKSL_WILL_FAIL_TESTS` / `AKSL_KNOWN_FAILING_TESTS` , and `AKERR_TESTS` /
Point the agent instructions at the issue tracker for outstanding work
This repository has no AGENTS.md; CLAUDE.md and MAINTENANCE.md carry the same
rules, so both are updated.
Outstanding work is an issue on the forge now, with the file and line, the
functional consequence, and what closing it would touch. TODO.md is the record
-- settled design decisions, the deviation register, defects already fixed, and
the reasoning behind the measurements -- and its row in CLAUDE.md's reading
table says so, with the tracker listed above it.
The dependency rule gains the correction this migration produced. 'Never work
around a missing dependency capability here' now says to open an issue in that
repository's tracker, and says plainly that recording it here instead is not
filing it: two akgl_ui gaps sat in TODO.md for a release on the reasoning that
changing a submodule is that repository's decision, which is true of changing it
and not of reporting it. Both are libakgl issues now.
Cross-repository citations of deps/*/TODO.md sections point at the trackers.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-08-02 19:25:05 -04:00
`AKERR_WILL_FAIL_TESTS` . `libakstdlib` 0.2.0 fixed all six defects it had confirmed
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
and left `AKSL_KNOWN_FAILING_TESTS` empty.
### Test target names
Every test program builds as `akbasic_test_<name>` while registering under the bare CTest
name. That is not cosmetic: `add_executable` creates a dependency's targets even under
`EXCLUDE_FROM_ALL` , and when `libakstdlib` added a `test_version` it collided with
`libakgl` 's and stopped the configure dead.
### The golden corpora
2026-08-04 16:21:59 -04:00
`tests/language/` is the editable language corpus. It includes cases carried over from the
deprecated Go implementation as well as cases written for this interpreter. Every `.bas` file
has a sibling `.txt` expectation, and a new language feature needs that pair as well as unit
tests. Change both deliberately in the same commit; provenance does not make a case immutable.
Split the documentation by who reads it
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
2026-07-31 22:59:43 -04:00
### Mutation-check a fix before you believe it
Coverage says a line ran; it does not say anything would have noticed if it were wrong.
That matters more here than usual, because the `akerror` macros expand at their call sites
and `gcov` attributes them to the caller.
The discipline for any fix with a test: **revert the fix, confirm the test fails, restore
it.** Use a file copy, not `git checkout` — `git checkout -- src` in a loop like this has
already wiped a session's worth of unrelated edits.
```sh norun
cmake --build build --target mutation # whole tree; hours
python3 scripts/mutation_test.py --target src/value.c --threshold 70
