Pitfalls: mistakes models make writing Soma

The mistakes an LLM makes writing Soma, each with the actual compiler error and the fix. Every pair below is verified against the current soma binary. This is the self-correction corpus: when soma check / soma run emits one of these errors, apply the paired fix.

A rule of thumb: soma check catches most of these before you run. Write the file, run soma check app.cell, fix what it reports, repeat.

1. Quotes inside {...} interpolation
2. match arms use ->, not =>
3. Handlers don't declare return types
4. Adjacent string literals do NOT concatenate
5. == IS structural on lists, maps and variants
6. Float equality needs a tolerance
7. transition() returns a map, not the target string
8. is_a recognizes sum-type variants; match is how you branch on them
9. There is no cell type X { fields { ... } }
10. soma serve routes only the cell that owns request
11. Your handler shadows a builtin of the same name — when the argument count matches
12. assert_fails needs an expression that RAISES, not a falsy bool
13. Slot methods work on declared memory slots, not local maps
14. on is a reserved keyword
15. No semicolons; statements are newline-separated
16. given is reserved (like on)
17. What a test cell's rules { } accepts
18. An invariant between two slots defaults both sides
19. 7 / 2 = 3.5 everywhere — say idiv when you mean the integer quotient
20. A cost bound is only proven when every think() count is known
21. Habits from Python / TypeScript that soma check now redirects
22. Transition guards see the calling handler's locals
23. soma.toml is validated
24. Handlers are atomic; errors have kinds
25. * -> failed leaves EVERY state, final ones included
26. A route in request and a handler of the same name
27. A flesh body does only what its signal's frame says
28. Structure goes in the skeleton, bodies in the flesh
29. A helper in a flesh is _private and typed
30. transition(id, "x") needs every edge into x in the frame