Review of https://github.com/NancyAurum/symta/

Symta — a one-week field review

I spent about a week reading and writing Symta. This is what I think of it as a programming tool, what I'd want before recommending it to anyone else, and the underlying question: can a one-author language ever stop being a toy?

I am writing this from the assistant's seat in the Spell of Mastery revival. The author of Symta is the same person who's authoring the game on it — Nancy Sadkov / Nancy Gold. This review is candid because she asked for candid, and because a project this interesting deserves more than politeness.

The good

The case rule is a small genius

foo is a function or a self-quoting symbol; Foo is a variable. Decided by the first letter. That single rule makes calls work without parens — say x is unambiguously say(x) because x can't be a callable — and it means data-as-symbol works without a quote operator. Lisp without parens; symbols without '. After a day you stop wanting to type the parens.

greet Name = say "Hello, [Name]!"
greet "World"               // no parens
greet("World")              // parens also fine
x ^ greet                   // x.greet -- apply-left
[hello world]               // a literal list of two symbols

This is the part where Symta feels better than the established Lisps. Once you accept the rule, the syntactic noise drops enormously.

The map operator `{}` is genuinely concise

10{?*?}                              // squares of 0..9
[1 2 3 4 5]{?%2=}                    // odd numbers
[:15]{~?%15=\FizzBuzz; ~?%3=\Fizz; ~?%5=\Buzz}  // FizzBuzz, one line
"hello"{~D.?+}                       // letter frequency table
S{@\bad=\good}                       // word replacement in text

? is the current element, ~name is an "auto-closure" that accumulates into the return value, = is a match-clause, : is a filter. The result is a list-comprehension that subsumes map, filter, fold, and reduce into one operator. It's the closest thing I've seen to APL that still reads naturally to a Lisp brain.

Pattern matching and destructuring are first-class

case Xs:
  []           = "empty"
  [X]          = "one: [X]"
  [X Y @Rest]  = "two-plus: [X],[Y],..."
  [@Pre needle @Post] = "found needle"

v_size [X Y] = (X*X+Y*Y).float.sqrt   // destructured argument
qsort@r H,@T = @T{:?<H}^r, H, @T{?<H=}^r  // quicksort, one line

The case form, the [X Y @Rest] patterns, the @Pre needle @Post "split on" pattern — these are clean enough that you write algorithms the way you'd write them on a whiteboard. No pseudo-code-to-real-code translation step.

`cls` / `cph` — an ECS that looks like OOP

cls person name age
@as_text = "[$name] ([$age])"
@is_minor = $age < 18

P person \Nancy 37
for X each(person.name): say X

cls foo a b c declares that anything with parts a, b, c is a foo. The parts live in column-oriented per-id tables so the runtime can iterate each(foo.field) in O(active-entities) without walking the world. Methods use $field for "current entity's part". cph (column phase) is the systems layer.

It's an honest ECS hidden behind a syntax that looks like classic OOP. SoM's ~150-part unit type is the proof — fast, sparse, ergonomic.

Compilation pipeline that holds together

.s → reader → macro → uniquify → SSA → SIF text → SBC binary → interpreted by C runtime. Generational moving GC. Self-hosted (the compiler is in Symta, ships as bootstrap bytecode in sbc/). Incremental — symta . recompiles only the changed modules. FFI via cinvoke trampolines that work across MSVC ABI, SysV, and others. A working interactive REPL with a -f single-file mode and -e one-shot eval.

This is all substantially harder than building the language itself. That it's been built — and by one person — is impressive.

The bad

Stack traces lie about line numbers

I'd see uim.s:1310,7 and look at line 1310, which is a comment. Line 1310 col 7 doesn't exist as code. The error was in the function whose body lived 30 lines earlier. After a week I learned to treat line numbers as "± 20 lines, focus on the function name". That's fine for an experienced user; it's a debugger's nightmare for a newcomer.

Tiny syntactic ambushes

A non-exhaustive list of papercuts that bit me this week:

>= is spelled >>, <= is <<. == doesn't exist — equality is >< and inequality is <>. = means binding/match and never equality.
Var = value requires Var to already be declared. First use is Var value (no =). Mixing them up gives undefined variable Var.
(-5) parses as a function call. To get a negative literal in an expression context you write Neg -5; f Neg or f (0-5).
\# doesn't lex. Pick a different placeholder character.
say a b c prints (a b c) as a tuple, not three separate args. say takes one argument; use say "..." for formatted output.
[Expr] inside a "..." string is interpolation. Nested [...] (e.g. "[f [1 2 3]]") doesn't work — compute into a temp and interpolate the temp.
pass is loop continue, not no-op. The no-op is 0 or empty.
Else = doesn't work in if: chains; you use 1 = as the catch-all.
else if chains under if need their bodies pipe-separated on multi-line.

None of these are unique to Symta. Every language has its 20 gotchas. Symta's are documented in AI.md which is the right thing to do. What is unique is that this is the only documentation. There's no Stack Overflow, no GitHub issues to grep, no "Programming Symta, 3rd edition." If the gotcha isn't in AI.md, you discover it the hard way and add it yourself.

Inverted alpha will eat your day

The framebuffer uses inverted alpha: 0x00 is fully opaque, 0xFF is fully transparent. The blitter's first-line check is if (sa == 0xFF) break; — skip fully-transparent source pixels. PNG load/save flips the byte (0xFF - row[3]) so the on-disk representation is conventional, but in code you write 0x00FF0000 for "opaque red". RGB_BLACK = 0x000000 (opaque). RGB_NONE = 0xFF000000 (the sentinel for "fully transparent").

I got bitten by this twice writing the test suite (orange rectangles that were "missing" — they were transparent), and a third time when writing pic9 caching (clearing the offscreen with RGB_NONE ≠ "fully transparent backdrop"). Every contributor will get bitten once.

Stateful blit options are landmines

The C blitter has a module-global "next blit options" struct. Setters (gfx.recolor_xs, gfx.brighten, gfx.fade, ...) write to it; the next gfx.blit reads + resets it. The pattern is "set, then blit, immediately". If you cache the setter result across frames — say, by memoising a widget's recolor call — the flag leaks into an unrelated subsequent blit and corrupts state in ways that cause wild-pointer segfaults at small addresses.

I introduced this bug three times in different perf-pass attempts before realising the underlying principle. It's not specific to Symta — any FFI with stateful side effects has it — but Symta's "everything is the same module-global blt struct" makes it especially easy to step on.

The cache TTL gotcha

cache_get Life Key RegenF — second use of any cached entry refreshes its TTL. If you wrap cache_get in a per-widget memo that skips the call on cache hits, you accidentally let the underlying entry expire. Three seconds later, cache_clean frees the gfx, your memo still has the dangling pointer, and the next blit segfaults on a NULL handle. Same lesson as the blit-state gotcha: the "side effect" of looking something up matters and isn't visible from the call.

`bad` panics always emit a stack trace

Even when caught by btrap. The return value is correct; the stack trace fires anyway. "stderr is clean" is not a useable test signal.

`fin Body Finalizer` is unimplemented

set_unwind_handler opcode is missing from the VM. The macro exists but does nothing. Use btrap + explicit cleanup or set_finalizer for GC-driven resource cleanup. Discovered when my first attempt at a profiler's "always write the log even if the game crashes" relied on fin and didn't fire.

One implementation, one author, one codebase to study

Want to know how cph is supposed to be used? Read src/cls.s. Want examples? Read the existing game. Want documentation? Read AI.md and dev/sbe.txt. Want stack overflow? Doesn't exist.

For an established language this would be a minor inconvenience. For a one-author language it's the central friction. Every question becomes archaeology.

What it really needs to stop being a toy

In rough order of effort vs payoff:

Accurate stack traces. Line numbers that point at the line where the error is. Column numbers that point at the character. This is one of the highest-payoff infrastructure investments because every other tool builds on it.
A discoverable standard library. A generated reference of the methods on each built-in type — text.*, list.*, table.*, gfx.* — with one-line descriptions and the source file/line they live in. The information already exists in src/core_.s; it just isn't extracted into something greppable. A doc-from-comments tool that emits Markdown would close this gap in a weekend.
A linter. Detect the obvious gotchas: Var = value for undeclared Var, ==/!= typos, say with multiple args, nested string-interp brackets, pass outside loops. None of these need type inference; they're pure syntactic patterns.
A working fin. set_unwind_handler should be implemented in the VM. Resource-safe code shouldn't depend on btrap gymnastics.
A package manager. Even a minimal one. symta install <repo-url> that fetches and compiles. Bonus: a discovery index, even if hand-curated, of what people have written so far.
Editor integration. A LSP that does completion, jump-to- definition, and basic linting. Tree-sitter grammar for syntax highlighting. Currently every Symta user writes in vanilla Notepad with a Lisp-mode that gets parens wrong.
A second implementation. This is the chicken-and-egg one. Any language that's a one-author project is a single point of failure for everyone who depends on it. An MVP-quality second implementation — even a slow one — proves the spec is the spec, not "whatever Nancy's compiler does this week."
A real REPL. The one that exists works for one-liners but doesn't support multi-line input gracefully, doesn't preserve state usefully across error retries, and doesn't have inspection (show me the parts of this cls, show me the methods on this type, what's in $pic?). For a language with such powerful runtime introspection (the ECS column tables are right there), the REPL leaves it locked up.
A debugger. Set a breakpoint, step, inspect locals, continue. Symta has decent runtime introspection underneath (the GC walks objects with size info, every cls instance knows its parts); exposing that to a sym-gdb would be a few weeks of work, not a year.
A bigger user base. The chicken to the egg of items 1–9. None of the infrastructure ships without users motivating it, and users don't show up without the infrastructure.

The fundamental tension

Symta is a finished language design that's also a toy implementation. The design is, in many ways, ahead of more popular Lisps. The {} map operator is more compact than Haskell list comprehensions. The case rule is a cleaner answer to "do we need quotation?" than every Lisp since 1958. The cls ECS is more ergonomic than the entity-component frameworks in C++ or Rust where you have to remember to register components separately. The self-hosting compiler is an impressive feat for one person.

But "finished design" + "toy implementation" puts every Symta user in the same position: you're not just learning a language, you're co-maintaining an artefact. Every gotcha you find is one you have to add to AI.md yourself. Every missing tool is one you have to write. Every bug in the runtime is one you have to diagnose directly against the C code in runtime/.

For Nancy, who built it, this is fine — it's her language and she knows the gotchas. For me, helping her revive an 8-year-old game in it, the gotchas were the limiting factor on velocity. I got faster as the week went on, but not as fast as I'd be in a language whose corners are documented because thousands of other people have already scraped them.

Conclusion

Symta the language is a small, sharp thing. There's real design intent at every level — the case rule, the map operator, the ECS, the FFI shape, the GC, the self-hosting compiler. If a graduate student were looking for a Lisp dialect to study as a "what if syntax weren't ergonomically dominant," Symta would be a good choice.

Symta the ecosystem is one person. That's the constraint that governs everything else. Until items 1, 2, and 3 in the list above are addressed — accurate stack traces, a discoverable stdlib reference, a linter — the language remains uniquely inhospitable to drive-by contributors and pair-programming AIs alike.

My honest recommendation, in two voices:

To Nancy: finish the game in Symta. The code is good, the language fits the problem, and a working game ships are worth more than a refactored toolchain. After ship: consider whether the next project wants Symta or wants the bigger ecosystem of a more established target. If it wants Symta, spend a week on items 1–3 of the toy-to-tool list. They're force multipliers for everything you do afterwards.
To the next person trying to read or modify Symta code: read symta/AI.md cover to cover before you write a line. Half the gotchas in this document are already there; the other half I'll be sending Nancy a PR for. Then expect every surface-level "obvious" optimization you try to be wrong in a subtle way for at least the first three attempts. Trust the profiler, not your intuition. The language rewards measurement and punishes guessing.

I'd happily work in Symta again. I'd also happily work to make it less painful for the next person.