ruby: Phase 1 parser (+83 tests, 190 total)

lib/ruby/tokenizer.sx — rb-tokenize: keywords, identifiers (@/@~/$/const),
numbers (dec/hex/oct/bin/float), strings (dq with raw interpolation, sq),
symbols, %w/%i, operators (all compound forms), punctuation, comments,
line/col tracking. Plus test runner test.sh and 107 passing tests.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

lib/ruby/parser.sx

@@ -0,0 +1,831 @@
+;; Ruby parser: token list → AST.
+;; Entry: (rb-parse tokens)  or  (rb-parse-str src)
+;; AST nodes: dicts with :type plus type-specific fields.
+
+(define rb-parse
+  (fn (tokens)
+    (let ((pos 0) (tok-count (len tokens)))
+
+      (define rb-p-cur
+        (fn () (nth tokens pos)))
+      (define rb-p-peek
+        (fn (n)
+          (if (< (+ pos n) tok-count)
+            (nth tokens (+ pos n))
+            {:type "eof" :value nil :line 0 :col 0})))
+      (define rb-p-advance!
+        (fn () (set! pos (+ pos 1))))
+      (define rb-p-type
+        (fn () (get (rb-p-cur) :type)))
+      (define rb-p-val
+        (fn () (get (rb-p-cur) :value)))
+      (define rb-p-sep?
+        (fn () (or (= (rb-p-type) "newline") (= (rb-p-type) "semi"))))
+      (define rb-p-skip-seps!
+        (fn ()
+          (when (rb-p-sep?)
+            (do (rb-p-advance!) (rb-p-skip-seps!)))))
+      (define rb-p-skip-newlines!
+        (fn ()
+          (when (= (rb-p-type) "newline")
+            (do (rb-p-advance!) (rb-p-skip-newlines!)))))
+      (define rb-p-expect!
+        (fn (type)
+          (if (= (rb-p-type) type)
+            (let ((tok (rb-p-cur)))
+              (rb-p-advance!)
+              tok)
+            {:type "error"
+             :msg (join "" (list "expected " type " got " (rb-p-type)))})))
+      (define rb-p-expect-kw!
+        (fn (kw)
+          (when (and (= (rb-p-type) "keyword") (= (rb-p-val) kw))
+            (rb-p-advance!))))
+
+      ;; Block: do |params| body end  or  { |params| body }
+      (define rb-p-parse-block-params
+        (fn ()
+          (if (= (rb-p-type) "pipe")
+            (do
+              (rb-p-advance!)
+              (let ((params (list)))
+                (define rb-p-bp-loop
+                  (fn ()
+                    (when (not (or (= (rb-p-type) "pipe") (= (rb-p-type) "eof")))
+                      (do
+                        (cond
+                          ((and (= (rb-p-type) "op") (= (rb-p-val) "**"))
+                            (do
+                              (rb-p-advance!)
+                              (append! params {:type "param-kwrest" :name (rb-p-val)})
+                              (rb-p-advance!)))
+                          ((and (= (rb-p-type) "op") (= (rb-p-val) "*"))
+                            (do
+                              (rb-p-advance!)
+                              (if (= (rb-p-type) "ident")
+                                (do
+                                  (append! params {:type "param-rest" :name (rb-p-val)})
+                                  (rb-p-advance!))
+                                (append! params {:type "param-rest" :name nil}))))
+                          (:else
+                            (do
+                              (append! params {:type "param-req" :name (rb-p-val)})
+                              (rb-p-advance!))))
+                        (when (= (rb-p-type) "comma") (rb-p-advance!))
+                        (rb-p-bp-loop)))))
+                (rb-p-bp-loop)
+                (rb-p-expect! "pipe")
+                params))
+            (list))))
+
+      (define rb-p-parse-block
+        (fn ()
+          (cond
+            ((and (= (rb-p-type) "keyword") (= (rb-p-val) "do"))
+              (do
+                (rb-p-advance!)
+                (let ((params (rb-p-parse-block-params)))
+                  (rb-p-skip-seps!)
+                  (let ((body (rb-p-parse-stmts (list "end"))))
+                    (rb-p-expect-kw! "end")
+                    {:type "block" :params params :body body}))))
+            ((= (rb-p-type) "lbrace")
+              (do
+                (rb-p-advance!)
+                (let ((params (rb-p-parse-block-params)))
+                  (rb-p-skip-seps!)
+                  (let ((body (rb-p-parse-stmts (list "rbrace"))))
+                    (rb-p-expect! "rbrace")
+                    {:type "block" :params params :body body}))))
+            (:else nil))))
+
+      ;; Method def params
+      (define rb-p-parse-def-params
+        (fn ()
+          (let ((params (list)))
+            (define rb-p-dp-one
+              (fn ()
+                (cond
+                  ((and (= (rb-p-type) "op") (= (rb-p-val) "&"))
+                    (do
+                      (rb-p-advance!)
+                      (append! params {:type "param-block" :name (rb-p-val)})
+                      (rb-p-advance!)))
+                  ((and (= (rb-p-type) "op") (= (rb-p-val) "**"))
+                    (do
+                      (rb-p-advance!)
+                      (append! params {:type "param-kwrest" :name (rb-p-val)})
+                      (rb-p-advance!)))
+                  ((and (= (rb-p-type) "op") (= (rb-p-val) "*"))
+                    (do
+                      (rb-p-advance!)
+                      (if (= (rb-p-type) "ident")
+                        (do
+                          (append! params {:type "param-rest" :name (rb-p-val)})
+                          (rb-p-advance!))
+                        (append! params {:type "param-rest" :name nil}))))
+                  ((and (= (rb-p-type) "ident")
+                        (= (get (rb-p-peek 1) :type) "colon"))
+                    (do
+                      (let ((name (rb-p-val)))
+                        (rb-p-advance!)
+                        (rb-p-advance!)
+                        (if (or (rb-p-sep?) (= (rb-p-type) "comma")
+                                (= (rb-p-type) "rparen") (= (rb-p-type) "eof"))
+                          (append! params {:type "param-kw" :name name :default nil})
+                          (append! params {:type "param-kw" :name name
+                                          :default (rb-p-parse-assign)})))))
+                  (:else
+                    (let ((name (rb-p-val)))
+                      (rb-p-advance!)
+                      (if (and (= (rb-p-type) "op") (= (rb-p-val) "="))
+                        (do
+                          (rb-p-advance!)
+                          (append! params {:type "param-opt" :name name
+                                          :default (rb-p-parse-assign)}))
+                        (append! params {:type "param-req" :name name})))))))
+            (define rb-p-dp-loop
+              (fn ()
+                (when (not (or (= (rb-p-type) "rparen") (rb-p-sep?)
+                               (= (rb-p-type) "eof")))
+                  (do
+                    (rb-p-dp-one)
+                    (when (= (rb-p-type) "comma")
+                      (do (rb-p-advance!) (rb-p-skip-newlines!)))
+                    (rb-p-dp-loop)))))
+            (rb-p-dp-loop)
+            params)))
+
+      ;; def [recv.] name [(params)] body end
+      (define rb-p-parse-def
+        (fn ()
+          (rb-p-advance!)
+          (let ((recv nil) (name nil))
+            (cond
+              ((and (= (rb-p-type) "keyword") (= (rb-p-val) "self")
+                    (= (get (rb-p-peek 1) :type) "dot"))
+                (do
+                  (set! recv {:type "self"})
+                  (rb-p-advance!)
+                  (rb-p-advance!)
+                  (set! name (rb-p-val))
+                  (rb-p-advance!)))
+              ((and (= (rb-p-type) "ident")
+                    (= (get (rb-p-peek 1) :type) "dot"))
+                (do
+                  (set! recv {:type "lvar" :name (rb-p-val)})
+                  (rb-p-advance!)
+                  (rb-p-advance!)
+                  (set! name (rb-p-val))
+                  (rb-p-advance!)))
+              (:else
+                (do
+                  (set! name (rb-p-val))
+                  (rb-p-advance!))))
+            (let ((params (list)))
+              (cond
+                ((= (rb-p-type) "lparen")
+                  (do
+                    (rb-p-advance!)
+                    (rb-p-skip-newlines!)
+                    (set! params (rb-p-parse-def-params))
+                    (rb-p-expect! "rparen")))
+                ((not (or (rb-p-sep?) (= (rb-p-type) "eof")))
+                  (set! params (rb-p-parse-def-params)))
+                (:else nil))
+              (rb-p-skip-seps!)
+              (let ((body (rb-p-parse-stmts (list "end"))))
+                (rb-p-expect-kw! "end")
+                {:type "method-def" :recv recv :name name
+                 :params params :body body})))))
+
+      ;; class [<<obj | Name [<Super]] body end
+      (define rb-p-parse-class
+        (fn ()
+          (rb-p-advance!)
+          (if (and (= (rb-p-type) "op") (= (rb-p-val) "<<"))
+            (do
+              (rb-p-advance!)
+              (let ((obj (rb-p-parse-primary)))
+                (rb-p-skip-seps!)
+                (let ((body (rb-p-parse-stmts (list "end"))))
+                  (rb-p-expect-kw! "end")
+                  {:type "sclass" :obj obj :body body})))
+            (let ((name (rb-p-parse-const-path)))
+              (let ((super nil))
+                (when (and (= (rb-p-type) "op") (= (rb-p-val) "<"))
+                  (do
+                    (rb-p-advance!)
+                    (set! super (rb-p-parse-const-path))))
+                (rb-p-skip-seps!)
+                (let ((body (rb-p-parse-stmts (list "end"))))
+                  (rb-p-expect-kw! "end")
+                  {:type "class-def" :name name :super super :body body}))))))
+
+      ;; module Name body end
+      (define rb-p-parse-module
+        (fn ()
+          (rb-p-advance!)
+          (let ((name (rb-p-parse-const-path)))
+            (rb-p-skip-seps!)
+            (let ((body (rb-p-parse-stmts (list "end"))))
+              (rb-p-expect-kw! "end")
+              {:type "module-def" :name name :body body}))))
+
+      ;; Const or Const::Const::...
+      (define rb-p-parse-const-path
+        (fn ()
+          (let ((node {:type "const" :name (rb-p-val)}))
+            (rb-p-advance!)
+            (define rb-p-cp-loop
+              (fn ()
+                (when (= (rb-p-type) "dcolon")
+                  (do
+                    (rb-p-advance!)
+                    (let ((name (rb-p-val)))
+                      (rb-p-advance!)
+                      (set! node {:type "const-path" :left node :name name})
+                      (rb-p-cp-loop))))))
+            (rb-p-cp-loop)
+            node)))
+
+      ;; [e, *e, ...]
+      (define rb-p-parse-array
+        (fn ()
+          (rb-p-advance!)
+          (rb-p-skip-newlines!)
+          (let ((elems (list)))
+            (define rb-p-arr-loop
+              (fn ()
+                (when (not (or (= (rb-p-type) "rbracket") (= (rb-p-type) "eof")))
+                  (do
+                    (if (and (= (rb-p-type) "op") (= (rb-p-val) "*"))
+                      (do
+                        (rb-p-advance!)
+                        (append! elems {:type "splat" :value (rb-p-parse-assign)}))
+                      (append! elems (rb-p-parse-assign)))
+                    (rb-p-skip-newlines!)
+                    (when (= (rb-p-type) "comma")
+                      (do (rb-p-advance!) (rb-p-skip-newlines!)))
+                    (rb-p-arr-loop)))))
+            (rb-p-arr-loop)
+            (rb-p-expect! "rbracket")
+            {:type "array" :elems elems})))
+
+      ;; {k: v, k => v, ...}
+      (define rb-p-parse-hash
+        (fn ()
+          (rb-p-advance!)
+          (rb-p-skip-newlines!)
+          (let ((pairs (list)))
+            (define rb-p-hash-loop
+              (fn ()
+                (when (not (or (= (rb-p-type) "rbrace") (= (rb-p-type) "eof")))
+                  (do
+                    (let ((key nil) (val nil) (style nil))
+                      (cond
+                        ((and (or (= (rb-p-type) "ident") (= (rb-p-type) "const"))
+                              (= (get (rb-p-peek 1) :type) "colon"))
+                          (do
+                            (set! key {:type "lit-sym" :value (rb-p-val)})
+                            (set! style "colon")
+                            (rb-p-advance!)
+                            (rb-p-advance!)))
+                        (:else
+                          (do
+                            (set! key (rb-p-parse-assign))
+                            (set! style "rocket")
+                            (when (and (= (rb-p-type) "op") (= (rb-p-val) "=>"))
+                              (rb-p-advance!)))))
+                      (rb-p-skip-newlines!)
+                      (set! val (rb-p-parse-assign))
+                      (append! pairs {:key key :val val :style style}))
+                    (rb-p-skip-newlines!)
+                    (when (= (rb-p-type) "comma")
+                      (do (rb-p-advance!) (rb-p-skip-newlines!)))
+                    (rb-p-hash-loop)))))
+            (rb-p-hash-loop)
+            (rb-p-expect! "rbrace")
+            {:type "hash" :pairs pairs})))
+
+      ;; (a, *b, **c, &d)
+      (define rb-p-parse-args-parens
+        (fn ()
+          (rb-p-advance!)
+          (rb-p-skip-newlines!)
+          (let ((args (list)))
+            (define rb-p-ap-loop
+              (fn ()
+                (when (not (or (= (rb-p-type) "rparen") (= (rb-p-type) "eof")))
+                  (do
+                    (cond
+                      ((and (= (rb-p-type) "op") (= (rb-p-val) "**"))
+                        (do (rb-p-advance!)
+                            (append! args {:type "dsplat" :value (rb-p-parse-assign)})))
+                      ((and (= (rb-p-type) "op") (= (rb-p-val) "*"))
+                        (do (rb-p-advance!)
+                            (append! args {:type "splat" :value (rb-p-parse-assign)})))
+                      ((and (= (rb-p-type) "op") (= (rb-p-val) "&"))
+                        (do (rb-p-advance!)
+                            (append! args {:type "block-pass" :value (rb-p-parse-assign)})))
+                      (:else (append! args (rb-p-parse-assign))))
+                    (rb-p-skip-newlines!)
+                    (when (= (rb-p-type) "comma")
+                      (do (rb-p-advance!) (rb-p-skip-newlines!)))
+                    (rb-p-ap-loop)))))
+            (rb-p-ap-loop)
+            (rb-p-expect! "rparen")
+            args)))
+
+      ;; No-paren arg list up to sep/end-keyword
+      (define rb-p-parse-args-bare
+        (fn ()
+          (let ((args (list)) (going true))
+            (define rb-p-ab-loop
+              (fn ()
+                (when (and going
+                           (not (rb-p-sep?))
+                           (not (= (rb-p-type) "eof"))
+                           (not (= (rb-p-type) "rparen"))
+                           (not (= (rb-p-type) "rbracket"))
+                           (not (= (rb-p-type) "rbrace"))
+                           (not (and (= (rb-p-type) "keyword")
+                                     (contains? (list "end" "else" "elsif" "when"
+                                                      "rescue" "ensure" "then" "do")
+                                                (rb-p-val)))))
+                  (do
+                    (cond
+                      ((and (= (rb-p-type) "op") (= (rb-p-val) "*"))
+                        (do (rb-p-advance!)
+                            (append! args {:type "splat" :value (rb-p-parse-assign)})))
+                      ((and (= (rb-p-type) "op") (= (rb-p-val) "**"))
+                        (do (rb-p-advance!)
+                            (append! args {:type "dsplat" :value (rb-p-parse-assign)})))
+                      ((and (= (rb-p-type) "op") (= (rb-p-val) "&"))
+                        (do (rb-p-advance!)
+                            (append! args {:type "block-pass" :value (rb-p-parse-assign)})))
+                      (:else (append! args (rb-p-parse-assign))))
+                    (if (= (rb-p-type) "comma")
+                      (do (rb-p-advance!) (rb-p-skip-newlines!) (rb-p-ab-loop))
+                      (set! going false))))))
+            (rb-p-ab-loop)
+            args)))
+
+      ;; Primary expression
+      (define rb-p-parse-primary
+        (fn ()
+          (cond
+            ((= (rb-p-type) "int")
+              (let ((v (rb-p-val))) (rb-p-advance!) {:type "lit-int" :value v}))
+            ((= (rb-p-type) "float")
+              (let ((v (rb-p-val))) (rb-p-advance!) {:type "lit-float" :value v}))
+            ((= (rb-p-type) "string")
+              (let ((v (rb-p-val))) (rb-p-advance!) {:type "lit-str" :value v}))
+            ((= (rb-p-type) "symbol")
+              (let ((v (rb-p-val))) (rb-p-advance!) {:type "lit-sym" :value v}))
+            ((= (rb-p-type) "words")
+              (let ((v (rb-p-val))) (rb-p-advance!) {:type "lit-words" :elems v}))
+            ((= (rb-p-type) "isymbols")
+              (let ((v (rb-p-val))) (rb-p-advance!) {:type "lit-isyms" :elems v}))
+            ((= (rb-p-type) "ivar")
+              (let ((v (rb-p-val))) (rb-p-advance!) {:type "ivar" :name v}))
+            ((= (rb-p-type) "cvar")
+              (let ((v (rb-p-val))) (rb-p-advance!) {:type "cvar" :name v}))
+            ((= (rb-p-type) "gvar")
+              (let ((v (rb-p-val))) (rb-p-advance!) {:type "gvar" :name v}))
+            ((= (rb-p-type) "const")
+              (rb-p-parse-const-path))
+            ((= (rb-p-type) "ident")
+              (let ((name (rb-p-val)))
+                (rb-p-advance!)
+                (if (= (rb-p-type) "lparen")
+                  (let ((args (rb-p-parse-args-parens))
+                        (blk (rb-p-parse-block)))
+                    {:type "send" :name name :args args :block blk})
+                  {:type "send" :name name :args (list) :block nil})))
+            ((= (rb-p-type) "keyword")
+              (cond
+                ((= (rb-p-val) "nil")
+                  (do (rb-p-advance!) {:type "lit-nil"}))
+                ((= (rb-p-val) "true")
+                  (do (rb-p-advance!) {:type "lit-bool" :value true}))
+                ((= (rb-p-val) "false")
+                  (do (rb-p-advance!) {:type "lit-bool" :value false}))
+                ((= (rb-p-val) "self")
+                  (do (rb-p-advance!) {:type "self"}))
+                ((= (rb-p-val) "super")
+                  (do
+                    (rb-p-advance!)
+                    (let ((args (if (= (rb-p-type) "lparen")
+                                   (rb-p-parse-args-parens) (list)))
+                          (blk (rb-p-parse-block)))
+                      {:type "send" :name "super" :args args :block blk})))
+                (:else
+                  {:type "error"
+                   :msg (join "" (list "unexpected kw " (rb-p-val)))})))
+            ((= (rb-p-type) "lbracket")
+              (rb-p-parse-array))
+            ((= (rb-p-type) "lbrace")
+              (rb-p-parse-hash))
+            ((= (rb-p-type) "lparen")
+              (do
+                (rb-p-advance!)
+                (rb-p-skip-seps!)
+                (let ((node (rb-p-parse-expr)))
+                  (rb-p-skip-seps!)
+                  (rb-p-expect! "rparen")
+                  node)))
+            (:else
+              (do
+                (rb-p-advance!)
+                {:type "error"
+                 :msg (join "" (list "unexpected " (rb-p-type)
+                                     " '" (or (rb-p-val) "") "'"))})))))
+
+      ;; .method  ::Const  [index]  chains
+      (define rb-p-parse-postfix
+        (fn ()
+          (let ((node (rb-p-parse-primary)))
+            (define rb-p-pf-loop
+              (fn ()
+                (cond
+                  ((= (rb-p-type) "dot")
+                    (do
+                      (rb-p-advance!)
+                      (let ((method (rb-p-val)))
+                        (rb-p-advance!)
+                        (let ((args (if (= (rb-p-type) "lparen")
+                                       (rb-p-parse-args-parens) (list)))
+                              (blk (rb-p-parse-block)))
+                          (set! node {:type "call" :recv node :method method
+                                      :args args :block blk})
+                          (rb-p-pf-loop)))))
+                  ((= (rb-p-type) "dcolon")
+                    (do
+                      (rb-p-advance!)
+                      (let ((name (rb-p-val)))
+                        (rb-p-advance!)
+                        (if (= (rb-p-type) "lparen")
+                          (let ((args (rb-p-parse-args-parens))
+                                (blk (rb-p-parse-block)))
+                            (set! node {:type "call" :recv node :method name
+                                        :args args :block blk}))
+                          (set! node {:type "const-path" :left node :name name}))
+                        (rb-p-pf-loop))))
+                  ((= (rb-p-type) "lbracket")
+                    (do
+                      (rb-p-advance!)
+                      (rb-p-skip-newlines!)
+                      (let ((idxargs (list)))
+                        (define rb-p-idx-loop
+                          (fn ()
+                            (when (not (or (= (rb-p-type) "rbracket") (= (rb-p-type) "eof")))
+                              (do
+                                (append! idxargs (rb-p-parse-assign))
+                                (when (= (rb-p-type) "comma")
+                                  (do (rb-p-advance!) (rb-p-skip-newlines!)))
+                                (rb-p-idx-loop)))))
+                        (rb-p-idx-loop)
+                        (rb-p-expect! "rbracket")
+                        (set! node {:type "index" :recv node :args idxargs})
+                        (rb-p-pf-loop))))
+                  (:else nil))))
+            (rb-p-pf-loop)
+            node)))
+
+      (define rb-p-parse-unary
+        (fn ()
+          (cond
+            ((and (= (rb-p-type) "op") (= (rb-p-val) "!"))
+              (do (rb-p-advance!)
+                  {:type "unop" :op "!" :value (rb-p-parse-unary)}))
+            ((and (= (rb-p-type) "op") (= (rb-p-val) "~"))
+              (do (rb-p-advance!)
+                  {:type "unop" :op "~" :value (rb-p-parse-unary)}))
+            ((and (= (rb-p-type) "op") (= (rb-p-val) "-"))
+              (do (rb-p-advance!)
+                  {:type "unop" :op "-" :value (rb-p-parse-unary)}))
+            ((and (= (rb-p-type) "op") (= (rb-p-val) "+"))
+              (do (rb-p-advance!) (rb-p-parse-unary)))
+            (:else (rb-p-parse-postfix)))))
+
+      (define rb-p-parse-power
+        (fn ()
+          (let ((node (rb-p-parse-unary)))
+            (if (and (= (rb-p-type) "op") (= (rb-p-val) "**"))
+              (do (rb-p-advance!)
+                  {:type "binop" :op "**" :left node :right (rb-p-parse-power)})
+              node))))
+
+      (define rb-p-parse-mul
+        (fn ()
+          (let ((node (rb-p-parse-power)))
+            (define rb-p-mul-loop
+              (fn ()
+                (if (and (= (rb-p-type) "op")
+                         (or (= (rb-p-val) "*") (= (rb-p-val) "/") (= (rb-p-val) "%")))
+                  (let ((op (rb-p-val)))
+                    (rb-p-advance!)
+                    (set! node {:type "binop" :op op :left node :right (rb-p-parse-power)})
+                    (rb-p-mul-loop))
+                  node)))
+            (rb-p-mul-loop))))
+
+      (define rb-p-parse-add
+        (fn ()
+          (let ((node (rb-p-parse-mul)))
+            (define rb-p-add-loop
+              (fn ()
+                (if (and (= (rb-p-type) "op")
+                         (or (= (rb-p-val) "+") (= (rb-p-val) "-")))
+                  (let ((op (rb-p-val)))
+                    (rb-p-advance!)
+                    (set! node {:type "binop" :op op :left node :right (rb-p-parse-mul)})
+                    (rb-p-add-loop))
+                  node)))
+            (rb-p-add-loop))))
+
+      (define rb-p-parse-shift
+        (fn ()
+          (let ((node (rb-p-parse-add)))
+            (define rb-p-sh-loop
+              (fn ()
+                (if (and (= (rb-p-type) "op")
+                         (or (= (rb-p-val) "<<") (= (rb-p-val) ">>")))
+                  (let ((op (rb-p-val)))
+                    (rb-p-advance!)
+                    (set! node {:type "binop" :op op :left node :right (rb-p-parse-add)})
+                    (rb-p-sh-loop))
+                  node)))
+            (rb-p-sh-loop))))
+
+      (define rb-p-parse-bitand
+        (fn ()
+          (let ((node (rb-p-parse-shift)))
+            (define rb-p-ba-loop
+              (fn ()
+                (if (and (= (rb-p-type) "op") (= (rb-p-val) "&"))
+                  (do
+                    (rb-p-advance!)
+                    (set! node {:type "binop" :op "&" :left node :right (rb-p-parse-shift)})
+                    (rb-p-ba-loop))
+                  node)))
+            (rb-p-ba-loop))))
+
+      ;; | is "pipe" token (not "op")
+      (define rb-p-parse-bitor
+        (fn ()
+          (let ((node (rb-p-parse-bitand)))
+            (define rb-p-bo-loop
+              (fn ()
+                (cond
+                  ((= (rb-p-type) "pipe")
+                    (do
+                      (rb-p-advance!)
+                      (set! node {:type "binop" :op "|" :left node :right (rb-p-parse-bitand)})
+                      (rb-p-bo-loop)))
+                  ((and (= (rb-p-type) "op") (= (rb-p-val) "^"))
+                    (do
+                      (rb-p-advance!)
+                      (set! node {:type "binop" :op "^" :left node :right (rb-p-parse-bitand)})
+                      (rb-p-bo-loop)))
+                  (:else node))))
+            (rb-p-bo-loop))))
+
+      (define rb-p-parse-comparison
+        (fn ()
+          (let ((node (rb-p-parse-bitor)))
+            (if (and (= (rb-p-type) "op")
+                     (contains? (list "==" "!=" "<" ">" "<=" ">="
+                                      "<=>" "===" "=~" "!~") (rb-p-val)))
+              (let ((op (rb-p-val)))
+                (rb-p-advance!)
+                {:type "binop" :op op :left node :right (rb-p-parse-bitor)})
+              node))))
+
+      (define rb-p-parse-not
+        (fn ()
+          (if (and (= (rb-p-type) "keyword") (= (rb-p-val) "not"))
+            (do (rb-p-advance!)
+                {:type "not" :value (rb-p-parse-not)})
+            (rb-p-parse-comparison))))
+
+      (define rb-p-parse-and
+        (fn ()
+          (let ((node (rb-p-parse-not)))
+            (define rb-p-and-loop
+              (fn ()
+                (cond
+                  ((and (= (rb-p-type) "op") (= (rb-p-val) "&&"))
+                    (do
+                      (rb-p-advance!)
+                      (set! node {:type "binop" :op "&&" :left node :right (rb-p-parse-not)})
+                      (rb-p-and-loop)))
+                  ((and (= (rb-p-type) "keyword") (= (rb-p-val) "and"))
+                    (do
+                      (rb-p-advance!)
+                      (set! node {:type "binop" :op "and" :left node :right (rb-p-parse-not)})
+                      (rb-p-and-loop)))
+                  (:else node))))
+            (rb-p-and-loop))))
+
+      (define rb-p-parse-or
+        (fn ()
+          (let ((node (rb-p-parse-and)))
+            (define rb-p-or-loop
+              (fn ()
+                (cond
+                  ((and (= (rb-p-type) "op") (= (rb-p-val) "||"))
+                    (do
+                      (rb-p-advance!)
+                      (set! node {:type "binop" :op "||" :left node :right (rb-p-parse-and)})
+                      (rb-p-or-loop)))
+                  ((and (= (rb-p-type) "keyword") (= (rb-p-val) "or"))
+                    (do
+                      (rb-p-advance!)
+                      (set! node {:type "binop" :op "or" :left node :right (rb-p-parse-and)})
+                      (rb-p-or-loop)))
+                  (:else node))))
+            (rb-p-or-loop))))
+
+      (define rb-p-parse-range
+        (fn ()
+          (let ((node (rb-p-parse-or)))
+            (cond
+              ((= (rb-p-type) "dotdot")
+                (do (rb-p-advance!)
+                    {:type "range" :from node :to (rb-p-parse-or) :exclusive false}))
+              ((= (rb-p-type) "dotdotdot")
+                (do (rb-p-advance!)
+                    {:type "range" :from node :to (rb-p-parse-or) :exclusive true}))
+              (:else node)))))
+
+      (define rb-p-parse-assign
+        (fn ()
+          (let ((node (rb-p-parse-range)))
+            (cond
+              ((and (= (rb-p-type) "op") (= (rb-p-val) "="))
+                (do (rb-p-advance!)
+                    {:type "assign" :target node :value (rb-p-parse-assign)}))
+              ((and (= (rb-p-type) "op")
+                    (contains? (list "+=" "-=" "*=" "/=" "%=" "**="
+                                     "<<=" ">>=" "&=" "|=" "^=" "&&=" "||=")
+                               (rb-p-val)))
+                (let ((op (substring (rb-p-val) 0 (- (len (rb-p-val)) 1))))
+                  (rb-p-advance!)
+                  {:type "op-assign" :target node :op op :value (rb-p-parse-assign)}))
+              (:else node)))))
+
+      (define rb-p-parse-expr
+        (fn () (rb-p-parse-assign)))
+
+      ;; e, e, ... → single node or array
+      (define rb-p-parse-multi-val
+        (fn ()
+          (let ((vals (list)))
+            (define rb-p-mv-loop
+              (fn ()
+                (append! vals (rb-p-parse-assign))
+                (when (= (rb-p-type) "comma")
+                  (do (rb-p-advance!) (rb-p-skip-newlines!) (rb-p-mv-loop)))))
+            (rb-p-mv-loop)
+            (if (= (len vals) 1)
+              (nth vals 0)
+              {:type "array" :elems vals}))))
+
+      ;; a, b, *c = rhs
+      (define rb-p-parse-massign
+        (fn ()
+          (let ((targets (list)))
+            (define rb-p-ma-loop
+              (fn ()
+                (cond
+                  ((and (= (rb-p-type) "op") (= (rb-p-val) "*"))
+                    (do
+                      (rb-p-advance!)
+                      (if (= (rb-p-type) "ident")
+                        (do
+                          (append! targets {:type "splat-target" :name (rb-p-val)})
+                          (rb-p-advance!))
+                        (append! targets {:type "splat-target" :name nil}))))
+                  ((= (rb-p-type) "ident")
+                    (do (append! targets {:type "lvar" :name (rb-p-val)}) (rb-p-advance!)))
+                  ((= (rb-p-type) "ivar")
+                    (do (append! targets {:type "ivar" :name (rb-p-val)}) (rb-p-advance!)))
+                  ((= (rb-p-type) "cvar")
+                    (do (append! targets {:type "cvar" :name (rb-p-val)}) (rb-p-advance!)))
+                  ((= (rb-p-type) "gvar")
+                    (do (append! targets {:type "gvar" :name (rb-p-val)}) (rb-p-advance!)))
+                  ((= (rb-p-type) "const")
+                    (do (append! targets {:type "const" :name (rb-p-val)}) (rb-p-advance!)))
+                  (:else nil))
+                (when (= (rb-p-type) "comma")
+                  (do (rb-p-advance!) (rb-p-skip-newlines!) (rb-p-ma-loop)))))
+            (rb-p-ma-loop)
+            (rb-p-advance!)
+            {:type "massign" :targets targets :value (rb-p-parse-multi-val)})))
+
+      (define rb-p-parse-stmt
+        (fn ()
+          (cond
+            ((and (= (rb-p-type) "keyword") (= (rb-p-val) "def"))
+              (rb-p-parse-def))
+            ((and (= (rb-p-type) "keyword") (= (rb-p-val) "class"))
+              (rb-p-parse-class))
+            ((and (= (rb-p-type) "keyword") (= (rb-p-val) "module"))
+              (rb-p-parse-module))
+            ((and (= (rb-p-type) "keyword") (= (rb-p-val) "return"))
+              (do (rb-p-advance!)
+                  {:type "return"
+                   :value (if (or (rb-p-sep?) (= (rb-p-type) "eof"))
+                             nil (rb-p-parse-multi-val))}))
+            ((and (= (rb-p-type) "keyword") (= (rb-p-val) "yield"))
+              (do (rb-p-advance!)
+                  {:type "yield"
+                   :args (cond
+                           ((= (rb-p-type) "lparen") (rb-p-parse-args-parens))
+                           ((or (rb-p-sep?) (= (rb-p-type) "eof")) (list))
+                           (:else (rb-p-parse-args-bare)))}))
+            ((and (= (rb-p-type) "keyword") (= (rb-p-val) "break"))
+              (do (rb-p-advance!)
+                  {:type "break"
+                   :value (if (or (rb-p-sep?) (= (rb-p-type) "eof"))
+                             nil (rb-p-parse-expr))}))
+            ((and (= (rb-p-type) "keyword") (= (rb-p-val) "next"))
+              (do (rb-p-advance!)
+                  {:type "next"
+                   :value (if (or (rb-p-sep?) (= (rb-p-type) "eof"))
+                             nil (rb-p-parse-expr))}))
+            ((and (= (rb-p-type) "keyword") (= (rb-p-val) "redo"))
+              (do (rb-p-advance!) {:type "redo"}))
+            ((and (= (rb-p-type) "keyword") (= (rb-p-val) "raise"))
+              (do (rb-p-advance!)
+                  {:type "raise"
+                   :value (if (or (rb-p-sep?) (= (rb-p-type) "eof"))
+                             nil (rb-p-parse-expr))}))
+            ;; Massign: token followed by comma
+            ((and (or (= (rb-p-type) "ident") (= (rb-p-type) "ivar")
+                      (= (rb-p-type) "cvar") (= (rb-p-type) "gvar")
+                      (= (rb-p-type) "const"))
+                  (= (get (rb-p-peek 1) :type) "comma"))
+              (rb-p-parse-massign))
+            (:else
+              (let ((node (rb-p-parse-assign)))
+                (if (and (= (get node :type) "send")
+                         (= (len (get node :args)) 0)
+                         (nil? (get node :block)))
+                  ;; Bare send: check for block or no-paren args
+                  (cond
+                    ;; Block immediately follows (do or {)
+                    ((or (and (= (rb-p-type) "keyword") (= (rb-p-val) "do"))
+                         (= (rb-p-type) "lbrace"))
+                      (let ((blk (rb-p-parse-block)))
+                        {:type "send" :name (get node :name) :args (list) :block blk}))
+                    ;; No-paren args (stop before block/sep/end keywords)
+                    ((and (not (rb-p-sep?))
+                          (not (= (rb-p-type) "eof"))
+                          (not (= (rb-p-type) "op"))
+                          (not (= (rb-p-type) "dot"))
+                          (not (= (rb-p-type) "dcolon"))
+                          (not (= (rb-p-type) "rparen"))
+                          (not (= (rb-p-type) "rbracket"))
+                          (not (= (rb-p-type) "rbrace"))
+                          (not (= (rb-p-type) "lbrace"))
+                          (not (and (= (rb-p-type) "keyword")
+                                    (contains? (list "end" "else" "elsif" "when"
+                                                     "rescue" "ensure" "then" "do"
+                                                     "and" "or" "not")
+                                               (rb-p-val)))))
+                      (let ((args (rb-p-parse-args-bare))
+                            (blk (rb-p-parse-block)))
+                        (if (> (len args) 0)
+                          {:type "send" :name (get node :name) :args args :block blk}
+                          node)))
+                    (:else node))
+                  node))))))
+
+      (define rb-p-parse-stmts
+        (fn (terminators)
+          (let ((stmts (list)))
+            (define rb-p-at-term?
+              (fn ()
+                (or (= (rb-p-type) "eof")
+                    (and (= (rb-p-type) "keyword")
+                         (contains? terminators (rb-p-val)))
+                    (and (= (rb-p-type) "rbrace")
+                         (contains? terminators "rbrace")))))
+            (define rb-p-ps-loop
+              (fn ()
+                (rb-p-skip-seps!)
+                (when (not (rb-p-at-term?))
+                  (do
+                    (append! stmts (rb-p-parse-stmt))
+                    (rb-p-skip-seps!)
+                    (rb-p-ps-loop)))))
+            (rb-p-ps-loop)
+            stmts)))
+
+      {:type "program" :stmts (rb-p-parse-stmts (list))})))
+
+(define rb-parse-str
+  (fn (src) (rb-parse (rb-tokenize src))))

lib/ruby/test.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Ruby-on-SX test runner.
+# Usage:
+#   bash lib/ruby/test.sh              # run all tests
+#   bash lib/ruby/test.sh -v           # verbose
+#   bash lib/ruby/test.sh tests/parse.sx   # single file
+
+set -euo pipefail
+cd "$(git rev-parse --show-toplevel)"
+
+SX_SERVER="hosts/ocaml/_build/default/bin/sx_server.exe"
+if [ ! -x "$SX_SERVER" ]; then
+  MAIN_ROOT=$(git worktree list | head -1 | awk '{print $1}')
+  if [ -x "$MAIN_ROOT/$SX_SERVER" ]; then
+    SX_SERVER="$MAIN_ROOT/$SX_SERVER"
+  else
+    echo "ERROR: sx_server.exe not found."
+    exit 1
+  fi
+fi
+
+VERBOSE=""
+FILES=()
+for arg in "$@"; do
+  case "$arg" in
+    -v|--verbose) VERBOSE=1 ;;
+    *) FILES+=("$arg") ;;
+  esac
+done
+
+if [ ${#FILES[@]} -eq 0 ]; then
+  mapfile -t FILES < <(find lib/ruby/tests -maxdepth 2 -name '*.sx' | sort)
+fi
+
+TOTAL_PASS=0
+TOTAL_FAIL=0
+FAILED_FILES=()
+
+for FILE in "${FILES[@]}"; do
+  [ -f "$FILE" ] || { echo "skip $FILE (not found)"; continue; }
+  TMPFILE=$(mktemp)
+  # Build epoch sequence: load runtime files, then test file, then eval summary.
+  {
+    echo "(epoch 1)"
+    echo "(load \"lib/ruby/tokenizer.sx\")"
+    if [ -f "lib/ruby/parser.sx" ]; then
+      echo "(epoch 2)"
+      echo "(load \"lib/ruby/parser.sx\")"
+    fi
+    echo "(epoch 3)"
+    echo "(load \"$FILE\")"
+    echo "(epoch 4)"
+    echo "(eval \"(list rb-test-pass rb-test-fail)\")"
+  } > "$TMPFILE"
+
+  OUTPUT=$(timeout 60 "$SX_SERVER" < "$TMPFILE" 2>&1 || true)
+  rm -f "$TMPFILE"
+
+  # Extract epoch 4 result: (ok-len 4 N)\n<val>  or  (ok 4 <val>)
+  LINE=$(printf '%s\n' "$OUTPUT" | awk '/^\(ok-len 4 / {getline; print; exit}')
+  if [ -z "$LINE" ]; then
+    LINE=$(printf '%s\n' "$OUTPUT" \
+           | grep -E '^\(ok 4 \([0-9]+ [0-9]+\)\)' | tail -1 \
+           | sed -E 's/^\(ok 4 //; s/\)$//')
+  fi
+  if [ -z "$LINE" ]; then
+    echo "✗ $FILE: could not extract summary"
+    printf '%s\n' "$OUTPUT" | grep -v '^(ok ' | tail -10
+    TOTAL_FAIL=$((TOTAL_FAIL + 1))
+    FAILED_FILES+=("$FILE")
+    continue
+  fi
+  P=$(printf '%s\n' "$LINE" | sed -E 's/^\(([0-9]+) ([0-9]+)\).*/\1/')
+  F=$(printf '%s\n' "$LINE" | sed -E 's/^\(([0-9]+) ([0-9]+)\).*/\2/')
+  TOTAL_PASS=$((TOTAL_PASS + P))
+  TOTAL_FAIL=$((TOTAL_FAIL + F))
+  if [ "$F" -gt 0 ]; then
+    FAILED_FILES+=("$FILE")
+    printf '✗ %-40s %d/%d\n' "$FILE" "$P" "$((P+F))"
+  elif [ "$VERBOSE" = "1" ]; then
+    printf '✓ %-40s %d passed\n' "$FILE" "$P"
+  fi
+done
+
+TOTAL=$((TOTAL_PASS + TOTAL_FAIL))
+if [ $TOTAL_FAIL -eq 0 ]; then
+  echo "✓ $TOTAL_PASS/$TOTAL ruby-on-sx tests passed"
+else
+  echo "✗ $TOTAL_PASS/$TOTAL passed, $TOTAL_FAIL failed in: ${FAILED_FILES[*]}"
+fi
+
+[ $TOTAL_FAIL -eq 0 ]

lib/ruby/tests/parse.sx

@@ -0,0 +1,439 @@
+;; Parser tests for Ruby 2.7 subset.
+
+(define rb-deep=?
+  (fn (a b)
+    (cond
+      ((= a b) true)
+      ((and (dict? a) (dict? b))
+        (let ((ak (keys a)) (bk (keys b)))
+          (if (not (= (len ak) (len bk)))
+            false
+            (every?
+              (fn (k)
+                (and (has-key? b k) (rb-deep=? (get a k) (get b k))))
+              ak))))
+      ((and (list? a) (list? b))
+        (if (not (= (len a) (len b)))
+          false
+          (let ((i 0) (ok true))
+            (define rb-de-loop
+              (fn ()
+                (when (and ok (< i (len a)))
+                  (do
+                    (when (not (rb-deep=? (nth a i) (nth b i)))
+                      (set! ok false))
+                    (set! i (+ i 1))
+                    (rb-de-loop)))))
+            (rb-de-loop)
+            ok)))
+      (:else false))))
+
+(define rb-test-pass 0)
+(define rb-test-fail 0)
+(define rb-test-fails (list))
+
+(define rb-test
+  (fn (name actual expected)
+    (if (rb-deep=? actual expected)
+      (set! rb-test-pass (+ rb-test-pass 1))
+      (do
+        (set! rb-test-fail (+ rb-test-fail 1))
+        (append! rb-test-fails {:name name :actual actual :expected expected})))))
+
+;; Shorthand: parse src and extract :stmts list
+(define rb-p-stmts
+  (fn (src)
+    (get (rb-parse-str src) :stmts)))
+
+;; Shorthand: parse and get first statement
+(define rb-p-first
+  (fn (src)
+    (nth (rb-p-stmts src) 0)))
+
+;; ── Literals ─────────────────────────────────────────────────────────────────
+
+(rb-test "int literal"
+  (rb-p-first "42")
+  {:type "lit-int" :value 42})
+
+(rb-test "negative int"
+  (rb-p-first "-7")
+  {:type "unop" :op "-" :value {:type "lit-int" :value 7}})
+
+(rb-test "float literal"
+  (rb-p-first "3.14")
+  {:type "lit-float" :value "3.14"})
+
+(rb-test "string literal"
+  (rb-p-first "\"hello\"")
+  {:type "lit-str" :value "hello"})
+
+(rb-test "symbol literal"
+  (rb-p-first ":foo")
+  {:type "lit-sym" :value "foo"})
+
+(rb-test "nil literal"
+  (rb-p-first "nil")
+  {:type "lit-nil"})
+
+(rb-test "true literal"
+  (rb-p-first "true")
+  {:type "lit-bool" :value true})
+
+(rb-test "false literal"
+  (rb-p-first "false")
+  {:type "lit-bool" :value false})
+
+(rb-test "self"
+  (rb-p-first "self")
+  {:type "self"})
+
+(rb-test "%w[] words"
+  (rb-p-first "%w[a b c]")
+  {:type "lit-words" :elems (list "a" "b" "c")})
+
+(rb-test "%i[] isymbols"
+  (rb-p-first "%i[x y]")
+  {:type "lit-isyms" :elems (list "x" "y")})
+
+;; ── Variables ─────────────────────────────────────────────────────────────────
+
+(rb-test "local var / send"
+  (rb-p-first "x")
+  {:type "send" :name "x" :args (list) :block nil})
+
+(rb-test "ivar"
+  (rb-p-first "@foo")
+  {:type "ivar" :name "@foo"})
+
+(rb-test "cvar"
+  (rb-p-first "@@count")
+  {:type "cvar" :name "@@count"})
+
+(rb-test "gvar"
+  (rb-p-first "$stdout")
+  {:type "gvar" :name "$stdout"})
+
+(rb-test "constant"
+  (rb-p-first "Foo")
+  {:type "const" :name "Foo"})
+
+(rb-test "const path"
+  (rb-p-first "Foo::Bar")
+  {:type "const-path"
+   :left {:type "const" :name "Foo"}
+   :name "Bar"})
+
+(rb-test "triple const path"
+  (rb-p-first "A::B::C")
+  {:type "const-path"
+   :left {:type "const-path"
+          :left {:type "const" :name "A"}
+          :name "B"}
+   :name "C"})
+
+;; ── Arrays and Hashes ─────────────────────────────────────────────────────────
+
+(rb-test "empty array"
+  (rb-p-first "[]")
+  {:type "array" :elems (list)})
+
+(rb-test "array literal"
+  (rb-p-first "[1, 2, 3]")
+  {:type "array" :elems (list {:type "lit-int" :value 1}
+                               {:type "lit-int" :value 2}
+                               {:type "lit-int" :value 3})})
+
+(rb-test "hash colon style"
+  (get (rb-p-first "{a: 1}") :type)
+  "hash")
+
+(rb-test "hash pair style"
+  (get (nth (get (rb-p-first "{a: 1}") :pairs) 0) :style)
+  "colon")
+
+(rb-test "hash symbol key"
+  (get (get (nth (get (rb-p-first "{a: 1}") :pairs) 0) :key) :value)
+  "a")
+
+;; ── Binary operators ──────────────────────────────────────────────────────────
+
+(rb-test "addition"
+  (rb-p-first "1 + 2")
+  {:type "binop" :op "+"
+   :left {:type "lit-int" :value 1}
+   :right {:type "lit-int" :value 2}})
+
+(rb-test "subtraction"
+  (get (rb-p-first "a - b") :op)
+  "-")
+
+(rb-test "multiplication"
+  (get (rb-p-first "x * y") :op)
+  "*")
+
+(rb-test "precedence: * before +"
+  (rb-p-first "1 + 2 * 3")
+  {:type "binop" :op "+"
+   :left {:type "lit-int" :value 1}
+   :right {:type "binop" :op "*"
+           :left {:type "lit-int" :value 2}
+           :right {:type "lit-int" :value 3}}})
+
+(rb-test "power right-assoc"
+  (rb-p-first "2 ** 3 ** 4")
+  {:type "binop" :op "**"
+   :left {:type "lit-int" :value 2}
+   :right {:type "binop" :op "**"
+           :left {:type "lit-int" :value 3}
+           :right {:type "lit-int" :value 4}}})
+
+(rb-test "equality"
+  (get (rb-p-first "a == b") :op)
+  "==")
+
+(rb-test "logical and"
+  (get (rb-p-first "a && b") :op)
+  "&&")
+
+(rb-test "logical or"
+  (get (rb-p-first "a || b") :op)
+  "||")
+
+(rb-test "range inclusive"
+  (rb-p-first "1..5")
+  {:type "range"
+   :from {:type "lit-int" :value 1}
+   :to {:type "lit-int" :value 5}
+   :exclusive false})
+
+(rb-test "range exclusive"
+  (get (rb-p-first "1...5") :exclusive)
+  true)
+
+;; ── Assignment ────────────────────────────────────────────────────────────────
+
+(rb-test "assign"
+  (rb-p-first "x = 1")
+  {:type "assign"
+   :target {:type "send" :name "x" :args (list) :block nil}
+   :value {:type "lit-int" :value 1}})
+
+(rb-test "op-assign +="
+  (get (rb-p-first "x += 1") :type)
+  "op-assign")
+
+(rb-test "op-assign op"
+  (get (rb-p-first "x += 1") :op)
+  "+")
+
+(rb-test "massign"
+  (get (rb-p-first "a, b = 1, 2") :type)
+  "massign")
+
+(rb-test "massign targets"
+  (len (get (rb-p-first "a, b = 1, 2") :targets))
+  2)
+
+(rb-test "massign value array"
+  (get (get (rb-p-first "a, b = 1, 2") :value) :type)
+  "array")
+
+;; ── Method calls ──────────────────────────────────────────────────────────────
+
+(rb-test "call with parens"
+  (rb-p-first "foo(1, 2)")
+  {:type "send" :name "foo"
+   :args (list {:type "lit-int" :value 1}
+               {:type "lit-int" :value 2})
+   :block nil})
+
+(rb-test "chained call"
+  (get (rb-p-first "obj.foo") :type)
+  "call")
+
+(rb-test "chained call method"
+  (get (rb-p-first "obj.foo") :method)
+  "foo")
+
+(rb-test "chained call with args"
+  (len (get (rb-p-first "obj.foo(1, 2)") :args))
+  2)
+
+(rb-test "no-paren call"
+  (get (rb-p-first "puts \"hello\"") :type)
+  "send")
+
+(rb-test "no-paren call name"
+  (get (rb-p-first "puts \"hello\"") :name)
+  "puts")
+
+(rb-test "no-paren call args"
+  (len (get (rb-p-first "puts \"hello\"") :args))
+  1)
+
+(rb-test "indexing"
+  (get (rb-p-first "a[0]") :type)
+  "index")
+
+;; ── Unary operators ───────────────────────────────────────────────────────────
+
+(rb-test "unary not"
+  (rb-p-first "!x")
+  {:type "unop" :op "!"
+   :value {:type "send" :name "x" :args (list) :block nil}})
+
+(rb-test "unary minus"
+  (get (rb-p-first "-x") :op)
+  "-")
+
+;; ── Method def ────────────────────────────────────────────────────────────────
+
+(rb-test "empty method def"
+  (get (rb-p-first "def foo; end") :type)
+  "method-def")
+
+(rb-test "method def name"
+  (get (rb-p-first "def foo; end") :name)
+  "foo")
+
+(rb-test "method def no params"
+  (len (get (rb-p-first "def foo; end") :params))
+  0)
+
+(rb-test "method def with params"
+  (len (get (rb-p-first "def foo(a, b); end") :params))
+  2)
+
+(rb-test "method def param-req"
+  (get (nth (get (rb-p-first "def foo(a); end") :params) 0) :type)
+  "param-req")
+
+(rb-test "method def param name"
+  (get (nth (get (rb-p-first "def foo(a); end") :params) 0) :name)
+  "a")
+
+(rb-test "method def optional param"
+  (get (nth (get (rb-p-first "def foo(a, b=1); end") :params) 1) :type)
+  "param-opt")
+
+(rb-test "method def splat"
+  (get (nth (get (rb-p-first "def foo(*args); end") :params) 0) :type)
+  "param-rest")
+
+(rb-test "method def double splat"
+  (get (nth (get (rb-p-first "def foo(**opts); end") :params) 0) :type)
+  "param-kwrest")
+
+(rb-test "method def block param"
+  (get (nth (get (rb-p-first "def foo(&blk); end") :params) 0) :type)
+  "param-block")
+
+(rb-test "method def all param types"
+  (len (get (rb-p-first "def foo(a, b=1, *c, **d, &e); end") :params))
+  5)
+
+(rb-test "method def singleton recv"
+  (get (get (rb-p-first "def self.bar; end") :recv) :type)
+  "self")
+
+(rb-test "method def body"
+  (len (get (rb-p-first "def foo; 1; 2; end") :body))
+  2)
+
+;; ── Class def ────────────────────────────────────────────────────────────────
+
+(rb-test "class def type"
+  (get (rb-p-first "class Foo; end") :type)
+  "class-def")
+
+(rb-test "class def name"
+  (get (get (rb-p-first "class Foo; end") :name) :name)
+  "Foo")
+
+(rb-test "class def no super"
+  (nil? (get (rb-p-first "class Foo; end") :super))
+  true)
+
+(rb-test "class def with super"
+  (get (get (rb-p-first "class Foo < Bar; end") :super) :name)
+  "Bar")
+
+(rb-test "singleton class"
+  (get (rb-p-first "class << self; end") :type)
+  "sclass")
+
+;; ── Module def ────────────────────────────────────────────────────────────────
+
+(rb-test "module def type"
+  (get (rb-p-first "module M; end") :type)
+  "module-def")
+
+(rb-test "module def name"
+  (get (get (rb-p-first "module M; end") :name) :name)
+  "M")
+
+;; ── Blocks ────────────────────────────────────────────────────────────────────
+
+(rb-test "block do...end"
+  (get (get (rb-p-first "foo do |x| x end") :block) :type)
+  "block")
+
+(rb-test "block brace"
+  (get (get (rb-p-first "foo { |x| x }") :block) :type)
+  "block")
+
+(rb-test "block params"
+  (len (get (get (rb-p-first "foo { |a, b| a }") :block) :params))
+  2)
+
+(rb-test "block no params"
+  (len (get (get (rb-p-first "foo { 42 }") :block) :params))
+  0)
+
+;; ── Control flow ──────────────────────────────────────────────────────────────
+
+(rb-test "return type"
+  (get (rb-p-first "return 1") :type)
+  "return")
+
+(rb-test "return value"
+  (get (get (rb-p-first "return 1") :value) :value)
+  1)
+
+(rb-test "return nil"
+  (nil? (get (rb-p-first "return") :value))
+  true)
+
+(rb-test "yield type"
+  (get (rb-p-first "yield 1") :type)
+  "yield")
+
+(rb-test "break type"
+  (get (rb-p-first "break") :type)
+  "break")
+
+(rb-test "next type"
+  (get (rb-p-first "next") :type)
+  "next")
+
+(rb-test "redo type"
+  (get (rb-p-first "redo") :type)
+  "redo")
+
+;; ── Multi-statement program ───────────────────────────────────────────────────
+
+(rb-test "two statements"
+  (len (rb-p-stmts "1\n2"))
+  2)
+
+(rb-test "semi-separated"
+  (len (rb-p-stmts "1; 2; 3"))
+  3)
+
+(rb-test "class with method"
+  (let ((cls (rb-p-first "class Foo\n  def bar\n    1\n  end\nend")))
+    (len (get cls :body)))
+  1)
+
+(list rb-test-pass rb-test-fail)

lib/ruby/tests/tokenizer.sx

@@ -0,0 +1,210 @@
+;; Ruby tokenizer tests.
+;; Final value: {:pass N :fail N :fails (list)}
+
+(define rb-deep=?
+  (fn (a b)
+    (cond
+      ((= a b) true)
+      ((and (dict? a) (dict? b))
+        (let ((ak (keys a)) (bk (keys b)))
+          (if (not (= (len ak) (len bk)))
+            false
+            (every?
+              (fn (k) (and (has-key? b k) (rb-deep=? (get a k) (get b k))))
+              ak))))
+      ((and (list? a) (list? b))
+        (if (not (= (len a) (len b)))
+          false
+          (let ((i 0) (ok true))
+            (define rb-de-loop
+              (fn ()
+                (when (and ok (< i (len a)))
+                  (do
+                    (when (not (rb-deep=? (nth a i) (nth b i)))
+                      (set! ok false))
+                    (set! i (+ i 1))
+                    (rb-de-loop)))))
+            (rb-de-loop)
+            ok)))
+      (:else false))))
+
+(define rb-test-pass 0)
+(define rb-test-fail 0)
+(define rb-test-fails (list))
+
+(define rb-test
+  (fn (name actual expected)
+    (if (rb-deep=? actual expected)
+      (set! rb-test-pass (+ rb-test-pass 1))
+      (do
+        (set! rb-test-fail (+ rb-test-fail 1))
+        (append! rb-test-fails {:name name :actual actual :expected expected})))))
+
+;; Helper: tokenize, drop newline+eof, return {:type :value} pairs
+(define rb-toks
+  (fn (src)
+    (map
+      (fn (tok) {:value (get tok "value") :type (get tok "type")})
+      (filter
+        (fn (tok)
+          (let ((ty (get tok "type")))
+            (not (or (= ty "newline") (= ty "eof")))))
+        (rb-tokenize src)))))
+
+;; Helper: get just types
+(define rb-types
+  (fn (src) (map (fn (t) (get t "type")) (rb-toks src))))
+
+;; Helper: get first token type
+(define rb-first-type
+  (fn (src) (get (get (rb-tokenize src) 0) "type")))
+
+(define rb-first-value
+  (fn (src) (get (get (rb-tokenize src) 0) "value")))
+
+;; ── 1. Keywords ────────────────────────<E29480><E29480><EFBFBD>─────────────────────────
+(rb-test "keyword def" (rb-toks "def") (list {:value "def" :type "keyword"}))
+(rb-test "keyword end" (rb-toks "end") (list {:value "end" :type "keyword"}))
+(rb-test "keyword class" (rb-toks "class") (list {:value "class" :type "keyword"}))
+(rb-test "keyword if" (rb-toks "if") (list {:value "if" :type "keyword"}))
+(rb-test "keyword while" (rb-toks "while") (list {:value "while" :type "keyword"}))
+(rb-test "keyword nil" (rb-toks "nil") (list {:value "nil" :type "keyword"}))
+(rb-test "keyword true" (rb-toks "true") (list {:value "true" :type "keyword"}))
+(rb-test "keyword false" (rb-toks "false") (list {:value "false" :type "keyword"}))
+(rb-test "keyword return" (rb-toks "return") (list {:value "return" :type "keyword"}))
+(rb-test "keyword yield" (rb-toks "yield") (list {:value "yield" :type "keyword"}))
+(rb-test "keyword begin" (rb-toks "begin") (list {:value "begin" :type "keyword"}))
+(rb-test "keyword rescue" (rb-toks "rescue") (list {:value "rescue" :type "keyword"}))
+(rb-test "keyword self" (rb-toks "self") (list {:value "self" :type "keyword"}))
+(rb-test "keyword super" (rb-toks "super") (list {:value "super" :type "keyword"}))
+
+;; ── 2. Identifiers ────────────────────────────────────────────────
+(rb-test "ident simple" (rb-toks "foo") (list {:value "foo" :type "ident"}))
+(rb-test "ident underscore" (rb-toks "_foo") (list {:value "_foo" :type "ident"}))
+(rb-test "ident with digit" (rb-toks "foo2") (list {:value "foo2" :type "ident"}))
+(rb-test "ident predicate" (rb-toks "empty?") (list {:value "empty?" :type "ident"}))
+(rb-test "ident bang" (rb-toks "save!") (list {:value "save!" :type "ident"}))
+(rb-test "defined?" (rb-toks "defined?") (list {:value "defined?" :type "keyword"}))
+
+;; ── 3. Constants ──────────────────────────────────────────────────
+(rb-test "const simple" (rb-toks "Foo") (list {:value "Foo" :type "const"}))
+(rb-test "const upcase" (rb-toks "MY_CONST") (list {:value "MY_CONST" :type "const"}))
+(rb-test "const class" (rb-toks "String") (list {:value "String" :type "const"}))
+
+;; ── 4. Sigil variables ───────────────────────────────────────────
+(rb-test "ivar" (rb-toks "@name") (list {:value "@name" :type "ivar"}))
+(rb-test "cvar" (rb-toks "@@count") (list {:value "@@count" :type "cvar"}))
+(rb-test "gvar" (rb-toks "$global") (list {:value "$global" :type "gvar"}))
+
+;; ── 5. Integers ───────────────────────────────────────────────────
+(rb-test "int decimal" (rb-first-value "42") 42)
+(rb-test "int zero" (rb-first-value "0") 0)
+(rb-test "int underscore" (rb-first-value "1_000") 1000)
+(rb-test "int hex" (rb-first-value "0xFF") 255)
+(rb-test "int hex lower" (rb-first-value "0xff") 255)
+(rb-test "int octal" (rb-first-value "0o17") 15)
+(rb-test "int binary" (rb-first-value "0b1010") 10)
+(rb-test "int type" (rb-first-type "42") "int")
+
+;; ── 6. Floats ─────────────────────────────────────────────────────
+(rb-test "float simple" (rb-first-type "3.14") "float")
+(rb-test "float value" (rb-first-value "3.14") "3.14")
+(rb-test "float exp" (rb-first-type "1.5e10") "float")
+(rb-test "float exp value" (rb-first-value "1.5e10") "1.5e10")
+
+;; ── 7. Strings ────────────────────────────────────────────────────
+(rb-test "dq string" (rb-first-value "\"hello\"") "hello")
+(rb-test "dq string type" (rb-first-type "\"hello\"") "string")
+(rb-test "sq string" (rb-first-value "'world'") "world")
+(rb-test "dq escape nl" (rb-first-value "\"a\\nb\"") "a\nb")
+(rb-test "dq escape tab" (rb-first-value "\"a\\tb\"") "a\tb")
+(rb-test "dq escape quote" (rb-first-value "\"a\\\"b\"") "a\"b")
+(rb-test "sq no escape" (rb-first-value "'a\\nb'") "a\\nb")
+(rb-test "sq escape backslash" (rb-first-value "'a\\\\'") "a\\")
+(rb-test "dq interp kept" (rb-first-value "\"#{x}\"") "#{x}")
+
+;; ── 8. Symbols ────────────────────────────────────────────────────
+(rb-test "symbol simple" (rb-first-type ":foo") "symbol")
+(rb-test "symbol value" (rb-first-value ":foo") "foo")
+(rb-test "symbol predicate" (rb-first-value ":empty?") "empty?")
+(rb-test "symbol dq" (rb-first-value ":\"hello world\"") "hello world")
+(rb-test "symbol sq" (rb-first-value ":'hello'") "hello")
+
+;; ── 9. %w and %i literals ────────────────────────────────────────
+(rb-test "%w bracket" (rb-first-type "%w[a b c]") "words")
+(rb-test "%w value" (rb-first-value "%w[a b c]") (list "a" "b" "c"))
+(rb-test "%w paren" (rb-first-value "%w(x y)") (list "x" "y"))
+(rb-test "%i bracket" (rb-first-type "%i[a b]") "isymbols")
+(rb-test "%i value" (rb-first-value "%i[foo bar]") (list "foo" "bar"))
+
+;; ── 10. Punctuation ───────────────────────────────────────────────
+(rb-test "dot" (rb-first-type ".") "dot")
+(rb-test "dotdot" (rb-first-type "..") "dotdot")
+(rb-test "dotdotdot" (rb-first-type "...") "dotdotdot")
+(rb-test "dcolon" (rb-first-type "::") "dcolon")
+(rb-test "comma" (rb-first-type ",") "comma")
+(rb-test "semi" (rb-first-type ";") "semi")
+(rb-test "lparen" (rb-first-type "(") "lparen")
+(rb-test "rparen" (rb-first-type ")") "rparen")
+(rb-test "lbracket" (rb-first-type "[") "lbracket")
+(rb-test "rbracket" (rb-first-type "]") "rbracket")
+(rb-test "lbrace" (rb-first-type "{") "lbrace")
+(rb-test "rbrace" (rb-first-type "}") "rbrace")
+(rb-test "pipe" (rb-first-type "|") "pipe")
+
+;; ── 11. Operators ─────────────────────────────────────────────────
+(rb-test "op plus" (rb-first-value "+") "+")
+(rb-test "op minus" (rb-first-value "-") "-")
+(rb-test "op star" (rb-first-value "*") "*")
+(rb-test "op slash" (rb-first-value "/") "/")
+(rb-test "op eq" (rb-first-value "=") "=")
+(rb-test "op eqeq" (rb-first-value "==") "==")
+(rb-test "op neq" (rb-first-value "!=") "!=")
+(rb-test "op lt" (rb-first-value "<") "<")
+(rb-test "op gt" (rb-first-value ">") ">")
+(rb-test "op lte" (rb-first-value "<=") "<=")
+(rb-test "op gte" (rb-first-value ">=") ">=")
+(rb-test "op spaceship" (rb-first-value "<=>") "<=>")
+(rb-test "op tripleq" (rb-first-value "===") "===")
+(rb-test "op match" (rb-first-value "=~") "=~")
+(rb-test "op nomatch" (rb-first-value "!~") "!~")
+(rb-test "op lshift" (rb-first-value "<<") "<<")
+(rb-test "op rshift" (rb-first-value ">>") ">>")
+(rb-test "op and" (rb-first-value "&&") "&&")
+(rb-test "op or" (rb-first-value "||") "||")
+(rb-test "op power" (rb-first-value "**") "**")
+(rb-test "op plus-eq" (rb-first-value "+=") "+=")
+(rb-test "op minus-eq" (rb-first-value "-=") "-=")
+(rb-test "op arrow" (rb-first-value "->") "->")
+(rb-test "op hash-rocket" (rb-first-value "=>") "=>")
+
+;; ── 12. Comments ──────────────────────────────────────────────────
+(rb-test "comment skipped" (len (rb-toks "# this is a comment")) 0)
+(rb-test "comment mid-line" (rb-types "x = 1 # comment") (list "ident" "op" "int"))
+
+;; ── 13. Multi-token sequences ─────────────────────────────────────
+(rb-test "method call" (rb-types "foo.bar")
+  (list "ident" "dot" "ident"))
+(rb-test "class def" (rb-types "class Foo")
+  (list "keyword" "const"))
+(rb-test "method def" (rb-types "def greet(name)")
+  (list "keyword" "ident" "lparen" "ident" "rparen"))
+(rb-test "assignment" (rb-types "x = 42")
+  (list "ident" "op" "int"))
+(rb-test "block params" (rb-types "|x, y|")
+  (list "pipe" "ident" "comma" "ident" "pipe"))
+(rb-test "scope resolution" (rb-types "Foo::Bar")
+  (list "const" "dcolon" "const"))
+(rb-test "range" (rb-types "1..10")
+  (list "int" "dotdot" "int"))
+(rb-test "exclusive range" (rb-types "1...10")
+  (list "int" "dotdotdot" "int"))
+
+;; ── 14. Line/col tracking ────────────────────────────────────────
+(define rb-tok1 (get (rb-tokenize "hello\nworld") 0))
+(define rb-tok2 (get (rb-tokenize "hello\nworld") 2))
+(rb-test "line track start" (get rb-tok1 "line") 1)
+(rb-test "line track second" (get rb-tok2 "line") 2)
+(rb-test "col track start" (get rb-tok1 "col") 1)
+
+(list rb-test-pass rb-test-fail)

lib/ruby/tokenizer.sx

@@ -0,0 +1,549 @@
+;; Ruby tokenizer for Ruby 2.7 subset.
+;; Token: {:type T :value V :line L :col C}
+;;
+;; Types: keyword ident ivar cvar gvar const
+;;        int float string symbol
+;;        op dot dotdot dotdotdot dcolon colon
+;;        lparen rparen lbracket rbracket lbrace rbrace
+;;        comma semi pipe newline words isymbols eof
+
+;; ── Character code table ──────────────────────────────────────────
+(define rb-ord-table
+  (let ((t (dict)) (i 0))
+    (define rb-build-table
+      (fn ()
+        (when (< i 128)
+          (do
+            (dict-set! t (char-from-code i) i)
+            (set! i (+ i 1))
+            (rb-build-table)))))
+    (rb-build-table)
+    t))
+
+(define rb-ord (fn (c) (or (get rb-ord-table c) 0)))
+
+;; ── Character predicates ──────────────────────────────────────────
+(define rb-digit?
+  (fn (c) (and (string? c) (>= (rb-ord c) 48) (<= (rb-ord c) 57))))
+
+(define rb-hex-digit?
+  (fn (c)
+    (and (string? c)
+         (or (and (>= (rb-ord c) 48) (<= (rb-ord c) 57))
+             (and (>= (rb-ord c) 97) (<= (rb-ord c) 102))
+             (and (>= (rb-ord c) 65) (<= (rb-ord c) 70))))))
+
+(define rb-octal-digit?
+  (fn (c) (and (string? c) (>= (rb-ord c) 48) (<= (rb-ord c) 55))))
+
+(define rb-binary-digit? (fn (c) (or (= c "0") (= c "1"))))
+
+(define rb-lower?
+  (fn (c) (and (string? c) (>= (rb-ord c) 97) (<= (rb-ord c) 122))))
+
+(define rb-upper?
+  (fn (c) (and (string? c) (>= (rb-ord c) 65) (<= (rb-ord c) 90))))
+
+(define rb-ident-start?
+  (fn (c) (or (rb-lower? c) (rb-upper? c) (= c "_"))))
+
+(define rb-ident-cont?
+  (fn (c) (or (rb-lower? c) (rb-upper? c) (rb-digit? c) (= c "_"))))
+
+(define rb-space? (fn (c) (or (= c " ") (= c "\t") (= c "\r"))))
+
+;; ── Reserved words ────────────────────────────────────────────────
+(define rb-keywords
+  (list "__ENCODING__" "__LINE__" "__FILE__"
+        "BEGIN" "END"
+        "alias" "and"
+        "begin" "break"
+        "case" "class"
+        "def" "defined?" "do"
+        "else" "elsif" "end" "ensure"
+        "false" "for"
+        "if" "in"
+        "module"
+        "next" "nil" "not"
+        "or"
+        "redo" "rescue" "retry" "return"
+        "self" "super"
+        "then" "true"
+        "undef" "unless" "until"
+        "when" "while"
+        "yield"))
+
+(define rb-keyword? (fn (w) (contains? rb-keywords w)))
+
+;; ── Token constructor ─────────────────────────────────────────────
+(define rb-make-token
+  (fn (type value line col) {:type type :value value :line line :col col}))
+
+;; ── Radix number parser ───────────────────────────────────────────
+(define rb-parse-radix
+  (fn (s radix)
+    (let ((n (len s)) (i 0) (acc 0))
+      (define rb-rad-loop
+        (fn ()
+          (when (< i n)
+            (do
+              (let ((c (substring s i (+ i 1))))
+                (cond
+                  ((and (>= (rb-ord c) 48) (<= (rb-ord c) 57))
+                    (set! acc (+ (* acc radix) (- (rb-ord c) 48))))
+                  ((and (>= (rb-ord c) 97) (<= (rb-ord c) 102))
+                    (set! acc (+ (* acc radix) (+ 10 (- (rb-ord c) 97)))))
+                  ((and (>= (rb-ord c) 65) (<= (rb-ord c) 70))
+                    (set! acc (+ (* acc radix) (+ 10 (- (rb-ord c) 65)))))))
+              (set! i (+ i 1))
+              (rb-rad-loop)))))
+      (rb-rad-loop)
+      acc)))
+
+;; ── Strip underscores from numeric literals ───────────────────────
+(define rb-strip-underscores
+  (fn (s)
+    (let ((n (len s)) (i 0) (parts (list)))
+      (define rb-su-loop
+        (fn ()
+          (when (< i n)
+            (do
+              (let ((c (substring s i (+ i 1))))
+                (when (not (= c "_"))
+                  (append! parts c)))
+              (set! i (+ i 1))
+              (rb-su-loop)))))
+      (rb-su-loop)
+      (join "" parts))))
+
+;; ── Main tokenizer ────────────────────────────────────────────────
+(define rb-tokenize
+  (fn (src)
+    (let ((tokens (list))
+          (pos 0)
+          (line 1)
+          (col 1)
+          (src-len (len src)))
+      (define rb-peek
+        (fn (offset)
+          (if (< (+ pos offset) src-len)
+            (substring src (+ pos offset) (+ pos offset 1))
+            nil)))
+      (define rb-cur (fn () (rb-peek 0)))
+      (define rb-advance!
+        (fn ()
+          (let ((c (rb-cur)))
+            (set! pos (+ pos 1))
+            (if (= c "\n")
+              (do (set! line (+ line 1)) (set! col 1))
+              (set! col (+ col 1))))))
+      (define rb-advance-n!
+        (fn (n)
+          (when (> n 0)
+            (do (rb-advance!) (rb-advance-n! (- n 1))))))
+      (define rb-push!
+        (fn (type value tok-line tok-col)
+          (append! tokens (rb-make-token type value tok-line tok-col))))
+      (define rb-read-while
+        (fn (pred)
+          (let ((start pos))
+            (define rb-rw-loop
+              (fn ()
+                (when (and (< pos src-len) (pred (rb-cur)))
+                  (do (rb-advance!) (rb-rw-loop)))))
+            (rb-rw-loop)
+            (substring src start pos))))
+      (define rb-skip-line-comment!
+        (fn ()
+          (define rb-slc-loop
+            (fn ()
+              (when (and (< pos src-len) (not (= (rb-cur) "\n")))
+                (do (rb-advance!) (rb-slc-loop)))))
+          (rb-slc-loop)))
+      (define rb-read-escape
+        (fn ()
+          (rb-advance!)
+          (let ((c (rb-cur)))
+            (cond
+              ((= c "n") (do (rb-advance!) "\n"))
+              ((= c "t") (do (rb-advance!) "\t"))
+              ((= c "r") (do (rb-advance!) "\r"))
+              ((= c "\\") (do (rb-advance!) "\\"))
+              ((= c "'") (do (rb-advance!) "'"))
+              ((= c "\"") (do (rb-advance!) "\""))
+              ((= c "a") (do (rb-advance!) (char-from-code 7)))
+              ((= c "b") (do (rb-advance!) (char-from-code 8)))
+              ((= c "f") (do (rb-advance!) (char-from-code 12)))
+              ((= c "v") (do (rb-advance!) (char-from-code 11)))
+              ((= c "e") (do (rb-advance!) (char-from-code 27)))
+              ((= c "s") (do (rb-advance!) " "))
+              ((= c "0") (do (rb-advance!) (char-from-code 0)))
+              (:else (do (rb-advance!) (str "\\" c)))))))
+      (define rb-read-sq-string
+        (fn ()
+          (let ((parts (list)))
+            (rb-advance!)
+            (define rb-sq-loop
+              (fn ()
+                (cond
+                  ((>= pos src-len) nil)
+                  ((= (rb-cur) "'") (rb-advance!))
+                  ((and (= (rb-cur) "\\")
+                        (let ((n (rb-peek 1)))
+                          (or (= n "\\") (= n "'"))))
+                    (do
+                      (rb-advance!)
+                      (append! parts (rb-cur))
+                      (rb-advance!)
+                      (rb-sq-loop)))
+                  (:else
+                    (do
+                      (append! parts (rb-cur))
+                      (rb-advance!)
+                      (rb-sq-loop))))))
+            (rb-sq-loop)
+            (join "" parts))))
+      (define rb-read-dq-string
+        (fn ()
+          (let ((parts (list)))
+            (rb-advance!)
+            (define rb-dq-loop
+              (fn ()
+                (cond
+                  ((>= pos src-len) nil)
+                  ((= (rb-cur) "\"") (rb-advance!))
+                  ((= (rb-cur) "\\")
+                    (do
+                      (append! parts (rb-read-escape))
+                      (rb-dq-loop)))
+                  ((and (= (rb-cur) "#") (= (rb-peek 1) "{"))
+                    (do
+                      (append! parts "#{")
+                      (rb-advance-n! 2)
+                      (let ((depth 1))
+                        (define rb-interp-inner
+                          (fn ()
+                            (when (and (< pos src-len) (> depth 0))
+                              (do
+                                (let ((c (rb-cur)))
+                                  (cond
+                                    ((= c "{")
+                                      (do
+                                        (set! depth (+ depth 1))
+                                        (append! parts c)
+                                        (rb-advance!)))
+                                    ((= c "}")
+                                      (do
+                                        (set! depth (- depth 1))
+                                        (when (> depth 0)
+                                          (do (append! parts c) (rb-advance!)))))
+                                    (:else
+                                      (do (append! parts c) (rb-advance!)))))
+                                (rb-interp-inner)))))
+                        (rb-interp-inner))
+                      (when (= (rb-cur) "}")
+                        (do (append! parts "}") (rb-advance!)))
+                      (rb-dq-loop)))
+                  (:else
+                    (do
+                      (append! parts (rb-cur))
+                      (rb-advance!)
+                      (rb-dq-loop))))))
+            (rb-dq-loop)
+            (join "" parts))))
+      (define rb-read-percent-words
+        (fn ()
+          (rb-advance-n! 2)
+          (let ((open-ch (rb-cur)))
+            (let ((close-ch
+                    (cond
+                      ((= open-ch "[") "]")
+                      ((= open-ch "(") ")")
+                      ((= open-ch "{") "}")
+                      ((= open-ch "<") ">")
+                      (:else open-ch))))
+              (rb-advance!)
+              (let ((items (list)))
+                (define rb-pw-skip
+                  (fn ()
+                    (when (and (< pos src-len) (or (rb-space? (rb-cur)) (= (rb-cur) "\n")))
+                      (do (rb-advance!) (rb-pw-skip)))))
+                (define rb-pw-word
+                  (fn (wparts)
+                    (if (or (>= pos src-len)
+                             (rb-space? (rb-cur))
+                             (= (rb-cur) "\n")
+                             (= (rb-cur) close-ch))
+                      (append! items (join "" wparts))
+                      (do
+                        (append! wparts (rb-cur))
+                        (rb-advance!)
+                        (rb-pw-word wparts)))))
+                (define rb-pw-loop
+                  (fn ()
+                    (rb-pw-skip)
+                    (when (and (< pos src-len) (not (= (rb-cur) close-ch)))
+                      (do
+                        (rb-pw-word (list))
+                        (rb-pw-loop)))))
+                (rb-pw-loop)
+                (when (= (rb-cur) close-ch) (rb-advance!))
+                items)))))
+      (define rb-read-ident-word
+        (fn ()
+          (let ((start pos))
+            (rb-read-while rb-ident-cont?)
+            (when (and (= (rb-cur) "?") (not (= (rb-peek 1) "=")))
+              (rb-advance!))
+            (when (and (= (rb-cur) "!") (not (or (= (rb-peek 1) "=") (= (rb-peek 1) "~"))))
+              (rb-advance!))
+            (substring src start pos))))
+      (define rb-read-number!
+        (fn (tok-line tok-col)
+          (let ((start pos))
+            (cond
+              ((and (= (rb-cur) "0") (let ((p (rb-peek 1))) (or (= p "b") (= p "B"))))
+                (do
+                  (rb-advance-n! 2)
+                  (let ((bin-str (rb-read-while rb-binary-digit?)))
+                    (rb-push! "int" (rb-parse-radix bin-str 2) tok-line tok-col))))
+              ((and (= (rb-cur) "0") (let ((p (rb-peek 1))) (or (= p "o") (= p "O"))))
+                (do
+                  (rb-advance-n! 2)
+                  (let ((oct-str (rb-read-while rb-octal-digit?)))
+                    (rb-push! "int" (rb-parse-radix oct-str 8) tok-line tok-col))))
+              ((and (= (rb-cur) "0") (let ((p (rb-peek 1))) (or (= p "x") (= p "X"))))
+                (do
+                  (rb-advance-n! 2)
+                  (let ((hex-str (rb-read-while rb-hex-digit?)))
+                    (rb-push! "int" (rb-parse-radix hex-str 16) tok-line tok-col))))
+              (:else
+                (do
+                  (rb-read-while (fn (c) (or (rb-digit? c) (= c "_"))))
+                  (let ((is-float false))
+                    (when (and (= (rb-cur) ".") (rb-digit? (rb-peek 1)))
+                      (do
+                        (set! is-float true)
+                        (rb-advance!)
+                        (rb-read-while (fn (c) (or (rb-digit? c) (= c "_"))))))
+                    (when (or (= (rb-cur) "e") (= (rb-cur) "E"))
+                      (do
+                        (set! is-float true)
+                        (rb-advance!)
+                        (when (or (= (rb-cur) "+") (= (rb-cur) "-"))
+                          (rb-advance!))
+                        (rb-read-while rb-digit?)))
+                    (let ((num-str (rb-strip-underscores (substring src start pos))))
+                      (if is-float
+                        (rb-push! "float" num-str tok-line tok-col)
+                        (rb-push! "int" (parse-int num-str) tok-line tok-col))))))))))
+      (define rb-read-op!
+        (fn (tok-line tok-col)
+          (let ((c0 (rb-cur)) (c1 (rb-peek 1)) (c2 (rb-peek 2)))
+            (cond
+              ((and (= c0 "<") (= c1 "=") (= c2 ">"))
+                (do (rb-advance-n! 3) (rb-push! "op" "<=>" tok-line tok-col)))
+              ((and (= c0 "=") (= c1 "=") (= c2 "="))
+                (do (rb-advance-n! 3) (rb-push! "op" "===" tok-line tok-col)))
+              ((and (= c0 "*") (= c1 "*") (= c2 "="))
+                (do (rb-advance-n! 3) (rb-push! "op" "**=" tok-line tok-col)))
+              ((and (= c0 "<") (= c1 "<") (= c2 "="))
+                (do (rb-advance-n! 3) (rb-push! "op" "<<=" tok-line tok-col)))
+              ((and (= c0 ">") (= c1 ">") (= c2 "="))
+                (do (rb-advance-n! 3) (rb-push! "op" ">>=" tok-line tok-col)))
+              ((and (= c0 "&") (= c1 "&") (= c2 "="))
+                (do (rb-advance-n! 3) (rb-push! "op" "&&=" tok-line tok-col)))
+              ((and (= c0 "|") (= c1 "|") (= c2 "="))
+                (do (rb-advance-n! 3) (rb-push! "op" "||=" tok-line tok-col)))
+              ((and (= c0 "*") (= c1 "*"))
+                (do (rb-advance-n! 2) (rb-push! "op" "**" tok-line tok-col)))
+              ((and (= c0 "=") (= c1 "="))
+                (do (rb-advance-n! 2) (rb-push! "op" "==" tok-line tok-col)))
+              ((and (= c0 "!") (= c1 "="))
+                (do (rb-advance-n! 2) (rb-push! "op" "!=" tok-line tok-col)))
+              ((and (= c0 "<") (= c1 "="))
+                (do (rb-advance-n! 2) (rb-push! "op" "<=" tok-line tok-col)))
+              ((and (= c0 ">") (= c1 "="))
+                (do (rb-advance-n! 2) (rb-push! "op" ">=" tok-line tok-col)))
+              ((and (= c0 "=") (= c1 "~"))
+                (do (rb-advance-n! 2) (rb-push! "op" "=~" tok-line tok-col)))
+              ((and (= c0 "!") (= c1 "~"))
+                (do (rb-advance-n! 2) (rb-push! "op" "!~" tok-line tok-col)))
+              ((and (= c0 "<") (= c1 "<"))
+                (do (rb-advance-n! 2) (rb-push! "op" "<<" tok-line tok-col)))
+              ((and (= c0 ">") (= c1 ">"))
+                (do (rb-advance-n! 2) (rb-push! "op" ">>" tok-line tok-col)))
+              ((and (= c0 "&") (= c1 "&"))
+                (do (rb-advance-n! 2) (rb-push! "op" "&&" tok-line tok-col)))
+              ((and (= c0 "|") (= c1 "|"))
+                (do (rb-advance-n! 2) (rb-push! "op" "||" tok-line tok-col)))
+              ((and (= c0 "+") (= c1 "="))
+                (do (rb-advance-n! 2) (rb-push! "op" "+=" tok-line tok-col)))
+              ((and (= c0 "-") (= c1 "="))
+                (do (rb-advance-n! 2) (rb-push! "op" "-=" tok-line tok-col)))
+              ((and (= c0 "*") (= c1 "="))
+                (do (rb-advance-n! 2) (rb-push! "op" "*=" tok-line tok-col)))
+              ((and (= c0 "/") (= c1 "="))
+                (do (rb-advance-n! 2) (rb-push! "op" "/=" tok-line tok-col)))
+              ((and (= c0 "%") (= c1 "="))
+                (do (rb-advance-n! 2) (rb-push! "op" "%=" tok-line tok-col)))
+              ((and (= c0 "&") (= c1 "="))
+                (do (rb-advance-n! 2) (rb-push! "op" "&=" tok-line tok-col)))
+              ((and (= c0 "|") (= c1 "="))
+                (do (rb-advance-n! 2) (rb-push! "op" "|=" tok-line tok-col)))
+              ((and (= c0 "^") (= c1 "="))
+                (do (rb-advance-n! 2) (rb-push! "op" "^=" tok-line tok-col)))
+              ((and (= c0 "-") (= c1 ">"))
+                (do (rb-advance-n! 2) (rb-push! "op" "->" tok-line tok-col)))
+              ((and (= c0 "=") (= c1 ">"))
+                (do (rb-advance-n! 2) (rb-push! "op" "=>" tok-line tok-col)))
+              ((and (= c0 "|") (nil? c1))
+                (do (rb-advance!) (rb-push! "pipe" "|" tok-line tok-col)))
+              ((= c0 "|")
+                (do (rb-advance!) (rb-push! "pipe" "|" tok-line tok-col)))
+              (:else
+                (do (rb-advance!) (rb-push! "op" c0 tok-line tok-col)))))))
+      (define rb-scan!
+        (fn ()
+          (cond
+            ((>= pos src-len) nil)
+            ((rb-space? (rb-cur)) (do (rb-advance!) (rb-scan!)))
+            ((= (rb-cur) "#") (do (rb-skip-line-comment!) (rb-scan!)))
+            ((= (rb-cur) "\n")
+              (do
+                (let ((l line) (c col))
+                  (rb-advance!)
+                  (rb-push! "newline" nil l c))
+                (rb-scan!)))
+            ((rb-digit? (rb-cur))
+              (do
+                (let ((l line) (c col))
+                  (rb-read-number! l c))
+                (rb-scan!)))
+            ((rb-ident-start? (rb-cur))
+              (do
+                (let ((l line) (c col))
+                  (let ((w (rb-read-ident-word)))
+                    (if (rb-keyword? w)
+                      (rb-push! "keyword" w l c)
+                      (if (rb-upper? (substring w 0 1))
+                        (rb-push! "const" w l c)
+                        (rb-push! "ident" w l c)))))
+                (rb-scan!)))
+            ((= (rb-cur) "@")
+              (do
+                (let ((l line) (c col))
+                  (if (= (rb-peek 1) "@")
+                    (do
+                      (rb-advance-n! 2)
+                      (let ((name (rb-read-while rb-ident-cont?)))
+                        (rb-push! "cvar" (str "@@" name) l c)))
+                    (do
+                      (rb-advance!)
+                      (let ((name (rb-read-while rb-ident-cont?)))
+                        (rb-push! "ivar" (str "@" name) l c)))))
+                (rb-scan!)))
+            ((= (rb-cur) "$")
+              (do
+                (let ((l line) (c col))
+                  (rb-advance!)
+                  (let ((name (rb-read-while rb-ident-cont?)))
+                    (rb-push! "gvar" (str "$" name) l c)))
+                (rb-scan!)))
+            ((= (rb-cur) "\"")
+              (do
+                (let ((l line) (c col))
+                  (rb-push! "string" (rb-read-dq-string) l c))
+                (rb-scan!)))
+            ((= (rb-cur) "'")
+              (do
+                (let ((l line) (c col))
+                  (rb-push! "string" (rb-read-sq-string) l c))
+                (rb-scan!)))
+            ((and (= (rb-cur) ":") (= (rb-peek 1) ":"))
+              (do
+                (let ((l line) (c col))
+                  (rb-advance-n! 2)
+                  (rb-push! "dcolon" "::" l c))
+                (rb-scan!)))
+            ((= (rb-cur) ":")
+              (do
+                (let ((l line) (c col))
+                  (rb-advance!)
+                  (cond
+                    ((= (rb-cur) "\"")
+                      (rb-push! "symbol" (rb-read-dq-string) l c))
+                    ((= (rb-cur) "'")
+                      (rb-push! "symbol" (rb-read-sq-string) l c))
+                    ((rb-ident-start? (rb-cur))
+                      (let ((name (rb-read-ident-word)))
+                        (rb-push! "symbol" name l c)))
+                    (:else
+                      (rb-push! "colon" ":" l c))))
+                (rb-scan!)))
+            ((and (= (rb-cur) "%")
+                  (let ((p (rb-peek 1)))
+                    (or (= p "w") (= p "W") (= p "i") (= p "I"))))
+              (do
+                (let ((l line) (c col))
+                  (let ((kind (rb-peek 1)))
+                    (let ((items (rb-read-percent-words)))
+                      (if (or (= kind "i") (= kind "I"))
+                        (rb-push! "isymbols" items l c)
+                        (rb-push! "words" items l c)))))
+                (rb-scan!)))
+            ((= (rb-cur) ".")
+              (do
+                (let ((l line) (c col))
+                  (cond
+                    ((and (= (rb-peek 1) ".") (= (rb-peek 2) "."))
+                      (do (rb-advance-n! 3) (rb-push! "dotdotdot" "..." l c)))
+                    ((= (rb-peek 1) ".")
+                      (do (rb-advance-n! 2) (rb-push! "dotdot" ".." l c)))
+                    (:else
+                      (do (rb-advance!) (rb-push! "dot" "." l c)))))
+                (rb-scan!)))
+            ((= (rb-cur) ",")
+              (do
+                (let ((l line) (c col)) (rb-push! "comma" "," l c) (rb-advance!))
+                (rb-scan!)))
+            ((= (rb-cur) ";")
+              (do
+                (let ((l line) (c col)) (rb-push! "semi" ";" l c) (rb-advance!))
+                (rb-scan!)))
+            ((= (rb-cur) "(")
+              (do
+                (let ((l line) (c col)) (rb-push! "lparen" "(" l c) (rb-advance!))
+                (rb-scan!)))
+            ((= (rb-cur) ")")
+              (do
+                (let ((l line) (c col)) (rb-push! "rparen" ")" l c) (rb-advance!))
+                (rb-scan!)))
+            ((= (rb-cur) "[")
+              (do
+                (let ((l line) (c col)) (rb-push! "lbracket" "[" l c) (rb-advance!))
+                (rb-scan!)))
+            ((= (rb-cur) "]")
+              (do
+                (let ((l line) (c col)) (rb-push! "rbracket" "]" l c) (rb-advance!))
+                (rb-scan!)))
+            ((= (rb-cur) "{")
+              (do
+                (let ((l line) (c col)) (rb-push! "lbrace" "{" l c) (rb-advance!))
+                (rb-scan!)))
+            ((= (rb-cur) "}")
+              (do
+                (let ((l line) (c col)) (rb-push! "rbrace" "}" l c) (rb-advance!))
+                (rb-scan!)))
+            ((or (= (rb-cur) "+") (= (rb-cur) "-") (= (rb-cur) "*")
+                 (= (rb-cur) "/") (= (rb-cur) "%") (= (rb-cur) "=")
+                 (= (rb-cur) "!") (= (rb-cur) "<") (= (rb-cur) ">")
+                 (= (rb-cur) "&") (= (rb-cur) "^") (= (rb-cur) "~")
+                 (= (rb-cur) "|"))
+              (do
+                (let ((l line) (c col)) (rb-read-op! l c))
+                (rb-scan!)))
+            (:else (do (rb-advance!) (rb-scan!))))))
+      (rb-scan!)
+      (rb-push! "eof" nil line col)
+      tokens)))

plans/agent-briefings/apl-loop.md

@@ -0,0 +1,81 @@
+# apl-on-sx loop agent (single agent, queue-driven)
+
+Role: iterates `plans/apl-on-sx.md` forever. Rank-polymorphic primitives + 6 operators on the JIT is the headline showcase — APL is the densest combinator algebra you can put on top of a primitive table. Every program is `array → array` pure pipelines, exactly what the JIT was built for.
+
+```
+description: apl-on-sx queue loop
+subagent_type: general-purpose
+run_in_background: true
+isolation: worktree
+```
+
+## Prompt
+
+You are the sole background agent working `/root/rose-ash/plans/apl-on-sx.md`. Isolated worktree, forever, one commit per feature. Never push.
+
+## Restart baseline — check before iterating
+
+1. Read `plans/apl-on-sx.md` — roadmap + Progress log.
+2. `ls lib/apl/` — pick up from the most advanced file.
+3. If `lib/apl/tests/*.sx` exist, run them. Green before new work.
+4. If `lib/apl/scoreboard.md` exists, that's your baseline.
+
+## The queue
+
+Phase order per `plans/apl-on-sx.md`:
+
+- **Phase 1** — tokenizer + parser. Unicode glyphs, `¯` for negative, strands (juxtaposition), right-to-left, valence resolution by syntactic position
+- **Phase 2** — array model + scalar primitives. `make-array {shape, ravel}`, scalar promotion, broadcast for `+ - × ÷ ⌈ ⌊ * ⍟ | ! ○`, comparison, logical, `⍳`, `⎕IO`
+- **Phase 3** — structural primitives + indexing. `⍴ , ⍉ ↑ ↓ ⌽ ⊖ ⌷ ⍋ ⍒ ⊂ ⊃ ∊`
+- **Phase 4** — **THE SHOWCASE**: operators. `f/` (reduce), `f¨` (each), `∘.f` (outer), `f.g` (inner), `f⍨` (commute), `f∘g` (compose), `f⍣n` (power), `f⍤k` (rank), `@` (at)
+- **Phase 5** — dfns + tradfns + control flow. `{⍺+⍵}`, `∇` recurse, `⍺←default`, tradfn header, `:If/:While/:For/:Select`
+- **Phase 6** — classic programs (life, mandelbrot, primes, n-queens, quicksort) + idiom corpus + drive to 100+
+
+Within a phase, pick the checkbox that unlocks the most tests per effort.
+
+Every iteration: implement → test → commit → tick `[ ]` → Progress log → next.
+
+## Ground rules (hard)
+
+- **Scope:** only `lib/apl/**` and `plans/apl-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, other `lib/<lang>/` dirs, `lib/stdlib.sx`, or `lib/` root. APL primitives go in `lib/apl/runtime.sx`.
+- **NEVER call `sx_build`.** 600s watchdog. If sx_server binary broken → Blockers entry, stop.
+- **Shared-file issues** → plan's Blockers with minimal repro.
+- **SX files:** `sx-tree` MCP tools ONLY. `sx_validate` after edits.
+- **Unicode in `.sx`:** raw UTF-8 only, never `\uXXXX` escapes. Glyphs land directly in source.
+- **Worktree:** commit locally. Never push. Never touch `main`.
+- **Commit granularity:** one feature per commit.
+- **Plan file:** update Progress log + tick boxes every commit.
+
+## APL-specific gotchas
+
+- **Right-to-left, no precedence among functions.** `2 × 3 + 4` is `2 × (3 + 4)` = 14, not 10. Operators bind tighter than functions: `+/ ⍳5` is `+/(⍳5)`, and `2 +.× 3 4` is `2 (+.×) 3 4`.
+- **Valence by position.** `-3` is monadic negate (`-` with no left arg). `5-3` is dyadic subtract. The parser must look left to decide. Same glyph; different fn.
+- **`¯` is part of a number literal**, not a prefix function. `¯3` is the literal negative three; `-3` is the function call. Tokenizer eats `¯` into the numeric token.
+- **Strands.** `1 2 3` is a 3-element vector, not three separate calls. Adjacent literals fuse into a strand at parse time. Adjacent names do *not* fuse — `a b c` is three separate references.
+- **Scalar promotion.** `1 + 2 3 4` ↦ `3 4 5`. Any scalar broadcasts against any-rank conformable shape.
+- **Conformability** = exactly matching shapes, OR one side scalar, OR (in some dialects) one side rank-1 cycling against rank-N. Keep strict in v1: matching shape or scalar only.
+- **`⍳` is overloaded.** Monadic `⍳N` = vector 1..N (or 0..N-1 if `⎕IO=0`). Dyadic `V ⍳ W` = first-index lookup, returns `≢V+1` for not-found.
+- **Reduce with `+/⍳0`** = `0` (identity for `+`). Each scalar primitive has a defined identity used by reduce-on-empty. Don't crash; return identity.
+- **Reduce direction.** `f/` reduces the *last* axis. `f⌿` reduces the *first*. Matters for matrices.
+- **Indexing is 1-based** by default (`⎕IO=1`). Do not silently translate to 0-based; respect `⎕IO`.
+- **Bracket indexing** `A[I]` is sugar for `I⌷A` (squad-quad). Multi-axis: `A[I;J]` is `I J⌷A` with semicolon-separated axes; `A[;J]` selects all of axis 0.
+- **Dfn `{...}`** — `⍺` = left arg (may be unbound for monadic call → check with `⍺←default`), `⍵` = right arg, `∇` = recurse. Default left arg syntax: `⍺←0`.
+- **Tradfn vs dfn** — tradfns use line-numbered `→linenum` for goto; dfns use guards `cond:expr`. Pick the right one for the user's syntax.
+- **Empty array** = rank-N array where some dim is 0. `0⍴⍳0` is empty rank-1. Scalar prototype matters for empty-array operations; ignore in v1, return 0/space.
+- **Test corpus:** custom + idioms. Place programs in `lib/apl/tests/programs/` with `.apl` extension.
+
+## General gotchas (all loops)
+
+- SX `do` = R7RS iteration. Use `begin` for multi-expr sequences.
+- `cond`/`when`/`let` clauses evaluate only the last expr.
+- `type-of` on user fn returns `"lambda"`.
+- Shell heredoc `||` gets eaten — escape or use `case`.
+
+## Style
+
+- No comments in `.sx` unless non-obvious.
+- No new planning docs — update `plans/apl-on-sx.md` inline.
+- Short, factual commit messages (`apl: outer product ∘. (+9)`).
+- One feature per iteration. Commit. Log. Next.
+
+Go. Read the plan; find first `[ ]`; implement.

plans/agent-briefings/common-lisp-loop.md

@@ -0,0 +1,80 @@
+# common-lisp-on-sx loop agent (single agent, queue-driven)
+
+Role: iterates `plans/common-lisp-on-sx.md` forever. Conditions + restarts on delimited continuations is the headline showcase — every other Lisp reinvents resumable exceptions on the host stack. On SX `signal`/`invoke-restart` is just a captured continuation. Plus CLOS, the LOOP macro, packages.
+
+```
+description: common-lisp-on-sx queue loop
+subagent_type: general-purpose
+run_in_background: true
+isolation: worktree
+```
+
+## Prompt
+
+You are the sole background agent working `/root/rose-ash/plans/common-lisp-on-sx.md`. Isolated worktree, forever, one commit per feature. Never push.
+
+## Restart baseline — check before iterating
+
+1. Read `plans/common-lisp-on-sx.md` — roadmap + Progress log.
+2. `ls lib/common-lisp/` — pick up from the most advanced file.
+3. If `lib/common-lisp/tests/*.sx` exist, run them. Green before new work.
+4. If `lib/common-lisp/scoreboard.md` exists, that's your baseline.
+
+## The queue
+
+Phase order per `plans/common-lisp-on-sx.md`:
+
+- **Phase 1** — reader + parser (read macros `#'` `'` `` ` `` `,` `,@` `#( … )` `#:` `#\char` `#xFF` `#b1010`, ratios, dispatch chars, lambda lists with `&optional`/`&rest`/`&key`/`&aux`)
+- **Phase 2** — sequential eval + special forms (`let`/`let*`/`flet`/`labels`, `block`/`return-from`, `tagbody`/`go`, `unwind-protect`, multiple values, `setf` subset, dynamic variables)
+- **Phase 3** — **THE SHOWCASE**: condition system + restarts. `define-condition`, `signal`/`error`/`cerror`/`warn`, `handler-bind` (non-unwinding), `handler-case` (unwinding), `restart-case`, `restart-bind`, `find-restart`/`invoke-restart`/`compute-restarts`, `with-condition-restarts`. Classic programs (restart-demo, parse-recover, interactive-debugger) green.
+- **Phase 4** — CLOS: `defclass`, `defgeneric`, `defmethod` with `:before`/`:after`/`:around`, `call-next-method`, multiple dispatch
+- **Phase 5** — macros + LOOP macro + reader macros
+- **Phase 6** — packages + stdlib (sequence functions, FORMAT directives, drive corpus to 200+)
+
+Within a phase, pick the checkbox that unlocks the most tests per effort.
+
+Every iteration: implement → test → commit → tick `[ ]` → Progress log → next.
+
+## Ground rules (hard)
+
+- **Scope:** only `lib/common-lisp/**` and `plans/common-lisp-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, other `lib/<lang>/` dirs, `lib/stdlib.sx`, or `lib/` root. CL primitives go in `lib/common-lisp/runtime.sx`.
+- **NEVER call `sx_build`.** 600s watchdog. If sx_server binary broken → Blockers entry, stop.
+- **Shared-file issues** → plan's Blockers with minimal repro.
+- **Delimited continuations** are in `lib/callcc.sx` + `spec/evaluator.sx` Step 5. `sx_summarise` spec/evaluator.sx first — 2300+ lines.
+- **SX files:** `sx-tree` MCP tools ONLY. `sx_validate` after edits.
+- **Worktree:** commit locally. Never push. Never touch `main`.
+- **Commit granularity:** one feature per commit.
+- **Plan file:** update Progress log + tick boxes every commit.
+
+## Common-Lisp-specific gotchas
+
+- **`handler-bind` is non-unwinding** — handlers can decline by returning normally, in which case `signal` keeps walking the chain. **`handler-case` is unwinding** — picking a handler aborts the protected form via a captured continuation. Don't conflate them.
+- **Restarts are not handlers.** `restart-case` establishes named *resumption points*; `signal` runs handler code with restarts visible; the handler chooses a restart by calling `invoke-restart`, which abandons handler stack and resumes at the restart point. Two stacks: handlers walk down, restarts wait to be invoked.
+- **`block` / `return-from`** is lexical. `block name … (return-from name v) …` captures `^k` once at entry; `return-from` invokes it. `return-from` to a name not in scope is an error (don't fall back to outer block).
+- **`tagbody` / `go`** — each tag in tagbody is a continuation; `go tag` invokes it. Tags are lexical, can only target tagbodies in scope.
+- **`unwind-protect`** runs cleanup on *any* non-local exit (return-from, throw, condition unwind). Implement as a scope frame fired by the cleanup machinery.
+- **Multiple values**: primary-value-only contexts (function args, `if` test, etc.) drop extras silently. `values` produces multiple. `multiple-value-bind` / `multiple-value-call` consume them. Don't auto-list.
+- **CLOS dispatch:** sort applicable methods by argument-list specificity (`subclassp` per arg, left-to-right); standard method combination calls primary methods most-specific-first via `call-next-method` chain. `:before` runs all before primaries; `:after` runs all after, in reverse-specificity. `:around` wraps everything.
+- **`call-next-method`** is a *continuation* available only inside a method body. Implement as a thunk stored in a dynamic-extent variable.
+- **Generalised reference (`setf`)**: `(setf (foo x) v)` ↦ `(setf-foo v x)`. Look up the setf-expander, not just a writer fn. `define-setf-expander` is mandatory for non-trivial places. Start with the symbolic / list / aref / slot-value cases.
+- **Dynamic variables (specials):** `defvar`/`defparameter` mark a symbol as special. `let` over a special name *rebinds* in dynamic extent (use parameterize-style scope), not lexical.
+- **Symbols are package-qualified.** Reader resolves `cl:car`, `mypkg::internal`, bare `foo` (current package). Internal vs external matters for `:` (one colon) reads.
+- **`nil` is also `()` is also the empty list.** Same object. `nil` is also false. CL has no distinct unit value.
+- **LOOP macro is huge.** Build incrementally — start with `for/in`, `for/from`, `collect`, `sum`, `count`, `repeat`. Add conditional clauses (`when`, `if`, `else`) once iteration drivers stable. `named` blocks + `return-from named` last.
+- **Test corpus:** custom + curated `ansi-test` slice. Place programs in `lib/common-lisp/tests/programs/` with `.lisp` extension.
+
+## General gotchas (all loops)
+
+- SX `do` = R7RS iteration. Use `begin` for multi-expr sequences.
+- `cond`/`when`/`let` clauses evaluate only the last expr.
+- `type-of` on user fn returns `"lambda"`.
+- Shell heredoc `||` gets eaten — escape or use `case`.
+
+## Style
+
+- No comments in `.sx` unless non-obvious.
+- No new planning docs — update `plans/common-lisp-on-sx.md` inline.
+- Short, factual commit messages (`common-lisp: handler-bind + 12 tests`).
+- One feature per iteration. Commit. Log. Next.
+
+Go. Read the plan; find first `[ ]`; implement.

plans/agent-briefings/ruby-loop.md

@@ -0,0 +1,83 @@
+# ruby-on-sx loop agent (single agent, queue-driven)
+
+Role: iterates `plans/ruby-on-sx.md` forever. Fibers via delcc is the headline showcase — `Fiber.new`/`Fiber.yield`/`Fiber.resume` are textbook delimited continuations with sugar, where MRI does it via C-stack swapping. Plus blocks/yield (lexical escape continuations, same shape as Smalltalk's non-local return), method_missing, and singleton classes.
+
+```
+description: ruby-on-sx queue loop
+subagent_type: general-purpose
+run_in_background: true
+isolation: worktree
+```
+
+## Prompt
+
+You are the sole background agent working `/root/rose-ash/plans/ruby-on-sx.md`. Isolated worktree, forever, one commit per feature. Never push.
+
+## Restart baseline — check before iterating
+
+1. Read `plans/ruby-on-sx.md` — roadmap + Progress log.
+2. `ls lib/ruby/` — pick up from the most advanced file.
+3. If `lib/ruby/tests/*.sx` exist, run them. Green before new work.
+4. If `lib/ruby/scoreboard.md` exists, that's your baseline.
+
+## The queue
+
+Phase order per `plans/ruby-on-sx.md`:
+
+- **Phase 1** — tokenizer + parser. Keywords, identifier sigils (`@` ivar, `@@` cvar, `$` global), strings with interpolation, `%w[]`/`%i[]`, symbols, blocks `{|x| …}` and `do |x| … end`, splats, default args, method def
+- **Phase 2** — object model + sequential eval. Class table, ancestor-chain dispatch, `super`, singleton classes, `method_missing` fallback, dynamic constant lookup
+- **Phase 3** — blocks + procs + lambdas. Method captures escape continuation `^k`; `yield` / `return` / `break` / `next` / `redo` semantics; lambda strict arity vs proc lax
+- **Phase 4** — **THE SHOWCASE**: fibers via delcc. `Fiber.new`/`Fiber.resume`/`Fiber.yield`/`Fiber.transfer`. Classic programs (generator, producer-consumer, tree-walk) green
+- **Phase 5** — modules + mixins + metaprogramming. `include`/`prepend`/`extend`, `define_method`, `class_eval`/`instance_eval`, `respond_to?`/`respond_to_missing?`, hooks
+- **Phase 6** — stdlib drive. `Enumerable` mixin, `Comparable`, Array/Hash/Range/String/Integer methods, drive corpus to 200+
+
+Within a phase, pick the checkbox that unlocks the most tests per effort.
+
+Every iteration: implement → test → commit → tick `[ ]` → Progress log → next.
+
+## Ground rules (hard)
+
+- **Scope:** only `lib/ruby/**` and `plans/ruby-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, other `lib/<lang>/` dirs, `lib/stdlib.sx`, or `lib/` root. Ruby primitives go in `lib/ruby/runtime.sx`.
+- **NEVER call `sx_build`.** 600s watchdog. If sx_server binary broken → Blockers entry, stop.
+- **Shared-file issues** → plan's Blockers with minimal repro.
+- **Delimited continuations** are in `lib/callcc.sx` + `spec/evaluator.sx` Step 5. `sx_summarise` spec/evaluator.sx first — 2300+ lines.
+- **SX files:** `sx-tree` MCP tools ONLY. `sx_validate` after edits.
+- **Worktree:** commit locally. Never push. Never touch `main`.
+- **Commit granularity:** one feature per commit.
+- **Plan file:** update Progress log + tick boxes every commit.
+
+## Ruby-specific gotchas
+
+- **Block `return` vs lambda `return`.** Inside a block `{ ... return v }`, `return` invokes the *enclosing method's* escape continuation (non-local return). Inside a lambda `->(){ ... return v }`, `return` returns from the *lambda*. Don't conflate. Implement: blocks bind their `^method-k`; lambdas bind their own `^lambda-k`.
+- **`break` from inside a block** invokes a different escape — the *iteration loop's* escape — and the loop returns the break-value. `next` is escape from current iteration, returns iteration value. `redo` re-enters current iteration without advancing.
+- **Proc arity is lax.** `proc { |a, b, c| … }.call(1, 2)` ↦ `c = nil`. Lambda is strict — same call raises ArgumentError. Check arity at call site for lambdas only.
+- **Block argument unpacking.** `[[1,2],[3,4]].each { |a, b| … }` — single Array arg auto-unpacks for blocks (not lambdas). One arg, one Array → unpack. Frequent footgun.
+- **Method dispatch chain order:** prepended modules → class methods → included modules → superclass → BasicObject → method_missing. `super` walks from the *defining* class's position, not the receiver class's.
+- **Singleton classes** are lazily allocated. Looking up the chain for an object passes through its singleton class first, then its actual class. `class << obj; …; end` opens the singleton.
+- **`method_missing`** — fallback when ancestor walk misses. Receives `(name_symbol, *args, &blk)`. Pair with `respond_to_missing?` for `respond_to?` to also report true. Do **not** swallow NoMethodError silently.
+- **Ivars are per-object dicts.** Reading an unset ivar yields `nil` and a warning (`-W`). Don't error.
+- **Constant lookup** is first lexical (Module.nesting), then inheritance (Module.ancestors of the innermost class). Different from method lookup.
+- **`Object#send`** invokes private and public methods alike; `Object#public_send` skips privates.
+- **Class reopening.** `class Foo; def bar; …; end; end` plus a later `class Foo; def baz; …; end; end` adds methods to the same class. Class table lookups must be by-name, mutable; methods dict is mutable.
+- **Fiber semantics.** `Fiber.new { |arg| … }` creates a fiber suspended at entry. First `Fiber.resume(v)` enters with `arg = v`. Inside, `Fiber.yield(w)` returns `w` to the resumer; the next `Fiber.resume(v')` returns `v'` to the yield site. End of block returns final value to last resumer; subsequent `Fiber.resume` raises FiberError.
+- **`Fiber.transfer`** is symmetric — either side can transfer to the other; no resume/yield asymmetry. Implement on top of the same continuation pair, just don't enforce direction.
+- **Symbols are interned.** `:foo == :foo` is identity. Use SX symbols.
+- **Strings are mutable.** `s = "abc"; s << "d"; s == "abcd"`. Hash keys can be strings; hash dups string keys at insertion to be safe (or freeze them).
+- **Truthiness:** only `false` and `nil` are falsy. `0`, `""`, `[]` are truthy.
+- **Test corpus:** custom + curated RubySpec slice. Place programs in `lib/ruby/tests/programs/` with `.rb` extension.
+
+## General gotchas (all loops)
+
+- SX `do` = R7RS iteration. Use `begin` for multi-expr sequences.
+- `cond`/`when`/`let` clauses evaluate only the last expr.
+- `type-of` on user fn returns `"lambda"`.
+- Shell heredoc `||` gets eaten — escape or use `case`.
+
+## Style
+
+- No comments in `.sx` unless non-obvious.
+- No new planning docs — update `plans/ruby-on-sx.md` inline.
+- Short, factual commit messages (`ruby: Fiber.yield + Fiber.resume (+8)`).
+- One feature per iteration. Commit. Log. Next.
+
+Go. Read the plan; find first `[ ]`; implement.

plans/agent-briefings/smalltalk-loop.md

@@ -0,0 +1,77 @@
+# smalltalk-on-sx loop agent (single agent, queue-driven)
+
+Role: iterates `plans/smalltalk-on-sx.md` forever. Message-passing OO + **blocks with non-local return** on delimited continuations. Non-local return is the headline showcase — every other Smalltalk reinvents it on the host stack; on SX it falls out of the captured method-return continuation.
+
+```
+description: smalltalk-on-sx queue loop
+subagent_type: general-purpose
+run_in_background: true
+isolation: worktree
+```
+
+## Prompt
+
+You are the sole background agent working `/root/rose-ash/plans/smalltalk-on-sx.md`. Isolated worktree, forever, one commit per feature. Never push.
+
+## Restart baseline — check before iterating
+
+1. Read `plans/smalltalk-on-sx.md` — roadmap + Progress log.
+2. `ls lib/smalltalk/` — pick up from the most advanced file.
+3. If `lib/smalltalk/tests/*.sx` exist, run them. Green before new work.
+4. If `lib/smalltalk/scoreboard.md` exists, that's your baseline.
+
+## The queue
+
+Phase order per `plans/smalltalk-on-sx.md`:
+
+- **Phase 1** — tokenizer + parser (chunk format, identifiers, keywords `foo:`, binary selectors, `#sym`, `#(…)`, `$c`, blocks `[:a | …]`, cascades, message precedence)
+- **Phase 2** — object model + sequential eval (class table bootstrap, message dispatch, `super`, `doesNotUnderstand:`, instance variables)
+- **Phase 3** — **THE SHOWCASE**: blocks with non-local return via captured method-return continuation. `whileTrue:` / `ifTrue:ifFalse:` as block sends. 5 classic programs (eight-queens, quicksort, mandelbrot, life, fibonacci) green.
+- **Phase 4** — reflection + MOP: `perform:`, `respondsTo:`, runtime method addition, `becomeForward:`, `Exception` / `on:do:` / `ensure:` on top of `handler-bind`/`raise`
+- **Phase 5** — collections + numeric tower + streams
+- **Phase 6** — port SUnit, vendor Pharo Kernel-Tests slice, drive corpus to 200+
+- **Phase 7** — speed (optional): inline caching, block intrinsification
+
+Within a phase, pick the checkbox that unlocks the most tests per effort.
+
+Every iteration: implement → test → commit → tick `[ ]` → Progress log → next.
+
+## Ground rules (hard)
+
+- **Scope:** only `lib/smalltalk/**` and `plans/smalltalk-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, other `lib/<lang>/` dirs, `lib/stdlib.sx`, or `lib/` root. Smalltalk primitives go in `lib/smalltalk/runtime.sx`.
+- **NEVER call `sx_build`.** 600s watchdog. If sx_server binary broken → Blockers entry, stop.
+- **Shared-file issues** → plan's Blockers with minimal repro.
+- **Delimited continuations** are in `lib/callcc.sx` + `spec/evaluator.sx` Step 5. `sx_summarise` spec/evaluator.sx first — 2300+ lines.
+- **SX files:** `sx-tree` MCP tools ONLY. `sx_validate` after edits.
+- **Worktree:** commit locally. Never push. Never touch `main`.
+- **Commit granularity:** one feature per commit.
+- **Plan file:** update Progress log + tick boxes every commit.
+
+## Smalltalk-specific gotchas
+
+- **Method invocation captures `^k`** — the return continuation. Bind it as the block's escape token. `^expr` from inside any nested block invokes that captured `^k`. Escape past method return raises `BlockContext>>cannotReturn:`.
+- **Blocks are lambdas + escape token**, not bare lambdas. `value`/`value:`/… invoke the lambda; `^` invokes the escape.
+- **`ifTrue:` / `ifFalse:` / `whileTrue:` are ordinary block sends** — no special form. The runtime intrinsifies them in the JIT path (Tier 1 of bytecode expansion already covers this pattern).
+- **Cascade** `r m1; m2; m3` desugars to `(let ((tmp r)) (st-send tmp 'm1 ()) (st-send tmp 'm2 ()) (st-send tmp 'm3 ()))`. Result is the cascade's last send (or first, depending on parser variant — pick one and document).
+- **`super` send** looks up starting from the *defining* class's superclass, not the receiver class. Stash the defining class on the method record.
+- **Selectors are interned symbols.** Use SX symbols.
+- **Receiver dispatch:** tagged ints / floats / strings / symbols / `nil` / `true` / `false` aren't boxed. Their classes (`SmallInteger`, `Float`, `String`, `Symbol`, `UndefinedObject`, `True`, `False`) are looked up by SX type-of, not by an `:class` field.
+- **Method precedence:** unary > binary > keyword. `3 + 4 factorial` is `3 + (4 factorial)`. `a foo: b bar` is `a foo: (b bar)` (keyword absorbs trailing unary).
+- **Image / fileIn / become: between sessions** = out of scope. One-way `becomeForward:` only.
+- **Test corpus:** ~200 hand-written + a slice of Pharo Kernel-Tests. Place programs in `lib/smalltalk/tests/programs/`.
+
+## General gotchas (all loops)
+
+- SX `do` = R7RS iteration. Use `begin` for multi-expr sequences.
+- `cond`/`when`/`let` clauses evaluate only the last expr.
+- `type-of` on user fn returns `"lambda"`.
+- Shell heredoc `||` gets eaten — escape or use `case`.
+
+## Style
+
+- No comments in `.sx` unless non-obvious.
+- No new planning docs — update `plans/smalltalk-on-sx.md` inline.
+- Short, factual commit messages (`smalltalk: tokenizer + 56 tests`).
+- One feature per iteration. Commit. Log. Next.
+
+Go. Read the plan; find first `[ ]`; implement.

plans/agent-briefings/tcl-loop.md

@@ -0,0 +1,83 @@
+# tcl-on-sx loop agent (single agent, queue-driven)
+
+Role: iterates `plans/tcl-on-sx.md` forever. `uplevel`/`upvar` is the headline showcase — Tcl's superpower for defining your own control structures, requiring deep VM cooperation in any normal host but falling out of SX's first-class env-chain. Plus the Dodekalogue (12 rules), command-substitution everywhere, and "everything is a string" homoiconicity.
+
+```
+description: tcl-on-sx queue loop
+subagent_type: general-purpose
+run_in_background: true
+isolation: worktree
+```
+
+## Prompt
+
+You are the sole background agent working `/root/rose-ash/plans/tcl-on-sx.md`. Isolated worktree, forever, one commit per feature. Never push.
+
+## Restart baseline — check before iterating
+
+1. Read `plans/tcl-on-sx.md` — roadmap + Progress log.
+2. `ls lib/tcl/` — pick up from the most advanced file.
+3. If `lib/tcl/tests/*.sx` exist, run them. Green before new work.
+4. If `lib/tcl/scoreboard.md` exists, that's your baseline.
+
+## The queue
+
+Phase order per `plans/tcl-on-sx.md`:
+
+- **Phase 1** — tokenizer + parser. The Dodekalogue (12 rules): word-splitting, command sub `[…]`, var sub `$name`/`${name}`/`$arr(idx)`, double-quote vs brace word, backslash, `;`, `#` comments only at command start, single-pass left-to-right substitution
+- **Phase 2** — sequential eval + core commands. `set`/`unset`/`incr`/`append`/`lappend`, `puts`/`gets`, `expr` (own mini-language), `if`/`while`/`for`/`foreach`/`switch`, string commands, list commands, dict commands
+- **Phase 3** — **THE SHOWCASE**: `proc` + `uplevel` + `upvar`. Frame stack with proc-call push/pop; `uplevel #N script` evaluates in caller's frame; `upvar` aliases names across frames. Classic programs (for-each-line, assert macro, with-temp-var) green
+- **Phase 4** — `return -code N`, `catch`, `try`/`trap`/`finally`, `throw`. Control flow as integer codes
+- **Phase 5** — namespaces + ensembles. `namespace eval`, qualified names `::ns::cmd`, ensembles, `namespace path`
+- **Phase 6** — coroutines (built on fibers, same delcc as Ruby fibers) + system commands + drive corpus to 150+
+
+Within a phase, pick the checkbox that unlocks the most tests per effort.
+
+Every iteration: implement → test → commit → tick `[ ]` → Progress log → next.
+
+## Ground rules (hard)
+
+- **Scope:** only `lib/tcl/**` and `plans/tcl-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, other `lib/<lang>/` dirs, `lib/stdlib.sx`, or `lib/` root. Tcl primitives go in `lib/tcl/runtime.sx`.
+- **NEVER call `sx_build`.** 600s watchdog. If sx_server binary broken → Blockers entry, stop.
+- **Shared-file issues** → plan's Blockers with minimal repro.
+- **Delimited continuations** are in `lib/callcc.sx` + `spec/evaluator.sx` Step 5. `sx_summarise` spec/evaluator.sx first — 2300+ lines.
+- **SX files:** `sx-tree` MCP tools ONLY. `sx_validate` after edits.
+- **Worktree:** commit locally. Never push. Never touch `main`.
+- **Commit granularity:** one feature per commit.
+- **Plan file:** update Progress log + tick boxes every commit.
+
+## Tcl-specific gotchas
+
+- **Everything is a string.** Internally cache shimmer reps (list, dict, int, double) for performance, but every value must be re-stringifiable. Mutating one rep dirties the cached string and vice versa.
+- **The Dodekalogue is strict.** Substitution is **one-pass**, **left-to-right**. The result of a substitution is a value, not a script — it does NOT get re-parsed for further substitutions. This is what makes Tcl safe-by-default. Don't accidentally re-parse.
+- **Brace word `{…}`** is the only way to defer evaluation. No substitution inside, just balanced braces. Used for `if {expr}` body, `proc body`, `expr` arguments.
+- **Double-quote word `"…"`** is identical to a bare word for substitution purposes — it just allows whitespace in a single word. `\` escapes still apply.
+- **Comments are only at command position.** `# this is a comment` after a `;` or newline; *not* inside a command. `set x 1 # not a comment` is a 4-arg `set`.
+- **`expr` has its own grammar** — operator precedence, function calls — and does its own substitution. Brace `expr {$x + 1}` to avoid double-substitution and to enable bytecode caching.
+- **`if` and `while` re-parse** the condition only if not braced. Always use `if {…}`/`while {…}` form. The unbraced form re-substitutes per iteration.
+- **`return` from a `proc`** uses control code 2. `break` is 3, `continue` is 4. `error` is 1. `catch` traps any non-zero code; user can return non-zero with `return -code error -errorcode FOO message`.
+- **`uplevel #0 script`** is global frame. `uplevel 1 script` (or just `uplevel script`) is caller's frame. `uplevel #N` is absolute level N (0=global, 1=top-level proc, 2=proc-called-from-top, …). Negative levels are errors.
+- **`upvar #N otherVar localVar`** binds `localVar` in the current frame as an *alias* — both names refer to the same storage. Reads and writes go through the alias.
+- **`info level`** with no arg returns current level number. `info level N` (positive) returns the command list that invoked level N. `info level -N` returns the command list of the level N relative-up.
+- **Variable names with `(…)`** are array elements: `set arr(foo) 1`. Arrays are not first-class values — you can't `set x $arr`. `array get arr` gives a flat list `{key1 val1 key2 val2 …}`.
+- **List vs string.** `set l "a b c"` and `set l [list a b c]` look the same when printed but the second has a cached list rep. `lindex` works on both via shimmering. Most user code can't tell the difference.
+- **`incr x`** errors if x doesn't exist; pre-set with `set x 0` or use `incr x 0` first if you mean "create-or-increment". Or use `dict incr` for dicts.
+- **Coroutines are fibers.** `coroutine name body` starts a coroutine; calling `name` resumes it; `yield value` from inside suspends and returns `value` to the resumer. Same primitive as Ruby fibers — share the implementation under the hood.
+- **`switch`** matches first clause whose pattern matches. Default is `default`. Variant matches: glob (default), `-exact`, `-glob`, `-regexp`. Body `-` means "fall through to next clause's body".
+- **Test corpus:** custom + slice of Tcl's own tests. Place programs in `lib/tcl/tests/programs/` with `.tcl` extension.
+
+## General gotchas (all loops)
+
+- SX `do` = R7RS iteration. Use `begin` for multi-expr sequences.
+- `cond`/`when`/`let` clauses evaluate only the last expr.
+- `type-of` on user fn returns `"lambda"`.
+- Shell heredoc `||` gets eaten — escape or use `case`.
+
+## Style
+
+- No comments in `.sx` unless non-obvious.
+- No new planning docs — update `plans/tcl-on-sx.md` inline.
+- Short, factual commit messages (`tcl: uplevel + upvar (+11)`).
+- One feature per iteration. Commit. Log. Next.
+
+Go. Read the plan; find first `[ ]`; implement.

plans/apl-on-sx.md

@@ -0,0 +1,115 @@
+# APL-on-SX: rank-polymorphic primitives + glyph parser
+
+The headline showcase is **rank polymorphism** — a single primitive (`+`, `⌈`, `⊂`, `⍳`) works uniformly on scalars, vectors, matrices, and higher-rank arrays. ~80 glyph primitives + 6 operators bind together with right-to-left evaluation; the entire language is a high-density combinator algebra. The JIT compiler + primitive table pay off massively here because almost every program is `array → array` pure pipelines.
+
+End-state goal: Dyalog-flavoured APL subset, dfns + tradfns, classic programs (game-of-life, mandelbrot, prime-sieve, n-queens, conway), 100+ green tests.
+
+## Scope decisions (defaults — override by editing before we spawn)
+
+- **Syntax:** Dyalog APL surface, Unicode glyphs. `⎕`-quad system functions for I/O. `∇` tradfn header.
+- **Conformance:** "Reads like APL, runs like APL." Not byte-compat with Dyalog; we care about right-to-left semantics and rank polymorphism.
+- **Test corpus:** custom — APL idioms (Roger Hui style), classic programs, plus ~50 pattern tests for primitives.
+- **Out of scope:** ⎕-namespaces beyond a handful, complex numbers, full TAO ordering, `⎕FX` runtime function definition (use static `∇` only), nested-array-of-functions higher orders, the editor.
+- **Glyphs:** input via plain Unicode in `.apl` source files. Backtick-prefix shortcuts handled by the user's editor — we don't ship one.
+
+## Ground rules
+
+- **Scope:** only touch `lib/apl/**` and `plans/apl-on-sx.md`. Don't edit `spec/`, `hosts/`, `shared/`, or any other `lib/<lang>/**`. APL primitives go in `lib/apl/runtime.sx`.
+- **SX files:** use `sx-tree` MCP tools only.
+- **Commits:** one feature per commit. Keep `## Progress log` updated and tick roadmap boxes.
+
+## Architecture sketch
+
+```
+APL source (Unicode glyphs)
+    │
+    ▼
+lib/apl/tokenizer.sx   — glyphs, identifiers, numbers (¯ for negative), strings, strands
+    │
+    ▼
+lib/apl/parser.sx      — right-to-left with valence resolution (mon vs dyadic by position)
+    │
+    ▼
+lib/apl/transpile.sx   — AST → SX AST (entry: apl-eval-ast)
+    │
+    ▼
+lib/apl/runtime.sx     — array model, ~80 primitives, 6 operators, dfns/tradfns
+```
+
+Core mapping:
+- **Array** = SX dict `{:shape (d1 d2 …) :ravel #(v1 v2 …)}`. Scalar is rank-0 (empty shape), vector is rank-1, matrix rank-2, etc. Type uniformity not required (heterogeneous nested arrays via "boxed" elements `⊂x`).
+- **Rank polymorphism** — every scalar primitive is broadcast: `1 2 3 + 4 5 6` ↦ `5 7 9`; `(2 3⍴⍳6) + 1` ↦ broadcast scalar to matrix.
+- **Conformability** = matching shapes, or one-side scalar, or rank-1 cycling (deferred — keep strict in v1).
+- **Valence** = each glyph has a monadic and a dyadic meaning; resolution is purely positional (left-arg present → dyadic).
+- **Operator** = takes one or two function operands, returns a derived function (`f¨` = `each f`, `f/` = `reduce f`, `f∘g` = `compose`, `f⍨` = `commute`).
+- **Tradfn** `∇R←L F R; locals` = named function with explicit header.
+- **Dfn** `{⍺+⍵}` = anonymous, `⍺` = left arg, `⍵` = right arg, `∇` = recurse.
+
+## Roadmap
+
+### Phase 1 — tokenizer + parser
+- [ ] Tokenizer: Unicode glyphs (the full APL set: `+ - × ÷ * ⍟ ⌈ ⌊ | ! ? ○ ~ < ≤ = ≥ > ≠ ∊ ∧ ∨ ⍱ ⍲ , ⍪ ⍴ ⌽ ⊖ ⍉ ↑ ↓ ⊂ ⊃ ⊆ ∪ ∩ ⍳ ⍸ ⌷ ⍋ ⍒ ⊥ ⊤ ⊣ ⊢ ⍎ ⍕ ⍝`), operators (`/ \ ¨ ⍨ ∘ . ⍣ ⍤ ⍥ @`), numbers (`¯` for negative, `1E2`, `1J2` complex deferred), characters (`'a'`, `''` escape), strands (juxtaposition of literals: `1 2 3`), names, comments `⍝ …`
+- [ ] Parser: right-to-left; classify each token as function, operator, value, or name; resolve valence positionally; dfn `{…}` body, tradfn `∇` header, guards `:`, control words `:If :While :For …` (Dyalog-style)
+- [ ] Unit tests in `lib/apl/tests/parse.sx`
+
+### Phase 2 — array model + scalar primitives
+- [ ] Array constructor: `make-array shape ravel`, `scalar v`, `vector v…`, `enclose`/`disclose`
+- [ ] Shape arithmetic: `⍴` (shape), `,` (ravel), `≢` (tally / first-axis-length), `≡` (depth)
+- [ ] Scalar arithmetic primitives broadcast: `+ - × ÷ ⌈ ⌊ * ⍟ | ! ○`
+- [ ] Scalar comparison primitives: `< ≤ = ≥ > ≠`
+- [ ] Scalar logical: `~ ∧ ∨ ⍱ ⍲`
+- [ ] Index generator: `⍳n` (vector 1..n or 0..n-1 depending on `⎕IO`)
+- [ ] `⎕IO` = 1 default (Dyalog convention)
+- [ ] 40+ tests in `lib/apl/tests/scalar.sx`
+
+### Phase 3 — structural primitives + indexing
+- [ ] Reshape `⍴`, ravel `,`, transpose `⍉` (full + dyadic axis spec)
+- [ ] Take `↑`, drop `↓`, rotate `⌽` (last axis), `⊖` (first axis)
+- [ ] Catenate `,` (last axis) and `⍪` (first axis)
+- [ ] Index `⌷` (squad), bracket-indexing `A[I]` (sugar for `⌷`)
+- [ ] Grade-up `⍋`, grade-down `⍒`
+- [ ] Enclose `⊂`, disclose `⊃`, partition (subset deferred)
+- [ ] Membership `∊`, find `⍳` (dyadic), without `~` (dyadic), unique `∪` (deferred to phase 6)
+- [ ] 40+ tests in `lib/apl/tests/structural.sx`
+
+### Phase 4 — operators (THE SHOWCASE)
+- [ ] Reduce `f/` (last axis), `f⌿` (first axis) — including `∧/`, `∨/`, `+/`, `×/`, `⌈/`, `⌊/`
+- [ ] Scan `f\`, `f⍀`
+- [ ] Each `f¨` — applies `f` to each scalar/element
+- [ ] Outer product `∘.f` — `1 2 3 ∘.× 1 2 3` ↦ multiplication table
+- [ ] Inner product `f.g` — `+.×` is matrix multiply
+- [ ] Commute `f⍨` — `f⍨ x` ↔ `x f x`, `x f⍨ y` ↔ `y f x`
+- [ ] Compose `f∘g` — applies `g` first then `f`
+- [ ] Power `f⍣n` — apply f n times; `f⍣≡` until fixed point
+- [ ] Rank `f⍤k` — apply f at sub-rank k
+- [ ] At `@` — selective replace
+- [ ] 40+ tests in `lib/apl/tests/operators.sx`
+
+### Phase 5 — dfns + tradfns + control flow
+- [ ] Dfn `{…}` with `⍺` (left arg, may be absent → niladic/monadic), `⍵` (right arg), `∇` (recurse), guards `cond:expr`, default left arg `⍺←default`
+- [ ] Local assignment via `←` (lexical inside dfn)
+- [ ] Tradfn `∇` header: `R←L F R;l1;l2`, statement-by-statement, branch via `→linenum`
+- [ ] Dyalog control words: `:If/:Else/:EndIf`, `:While/:EndWhile`, `:For X :In V :EndFor`, `:Select/:Case/:EndSelect`, `:Trap`/`:EndTrap`
+- [ ] Niladic / monadic / dyadic dispatch (function valence at definition time)
+- [ ] `lib/apl/conformance.sh` + runner, `scoreboard.json` + `scoreboard.md`
+
+### Phase 6 — classic programs + drive corpus
+- [ ] Classic programs in `lib/apl/tests/programs/`:
+  - [ ] `life.apl` — Conway's Game of Life as a one-liner using `⊂` `⊖` `⌽` `+/`
+  - [ ] `mandelbrot.apl` — complex iteration with rank-polymorphic `+ × ⌊` (or real-axis subset)
+  - [ ] `primes.apl` — `(2=+⌿0=A∘.|A)/A←⍳N` sieve
+  - [ ] `n-queens.apl` — backtracking via reduce
+  - [ ] `quicksort.apl` — the classic Roger Hui one-liner
+- [ ] System functions: `⎕FMT`, `⎕FR` (float repr), `⎕TS` (timestamp), `⎕IO`, `⎕ML` (migration level — fixed at 1), `⎕←` (print)
+- [ ] Drive corpus to 100+ green
+- [ ] Idiom corpus — `lib/apl/tests/idioms.sx` covering classic Roger Hui / Phil Last idioms
+
+## Progress log
+
+_Newest first._
+
+- _(none yet)_
+
+## Blockers
+
+- _(none yet)_

plans/common-lisp-on-sx.md

@@ -0,0 +1,121 @@
+# Common-Lisp-on-SX: conditions + restarts on delimited continuations
+
+The headline showcase is the **condition system**. Restarts are *resumable* exceptions — every other Lisp implementation reinvents this on host-stack unwind tricks. On SX restarts are textbook delimited continuations: `signal` walks the handler chain; `invoke-restart` resumes the captured continuation at the restart point. Same delcc primitive that powers Erlang actors, expressed as a different surface.
+
+End-state goal: ANSI Common Lisp subset with a working condition/restart system, CLOS multimethods (with `:before`/`:after`/`:around`), the LOOP macro, packages, and ~150 hand-written + classic programs.
+
+## Scope decisions (defaults — override by editing before we spawn)
+
+- **Syntax:** ANSI Common Lisp surface. Read tables, dispatch macros (`#'`, `#(`, `#\`, `#:`, `#x`, `#b`, `#o`, ratios `1/3`).
+- **Conformance:** ANSI X3.226 *as a target*, not bug-for-bug SBCL/CCL. "Reads like CL, runs like CL."
+- **Test corpus:** custom + a curated slice of `ansi-test`. Plus classic programs: condition-system demo, restart-driven debugger, multiple-dispatch geometry, LOOP corpus.
+- **Out of scope:** compilation to native, FFI, sockets, threads, MOP class redefinition, full pathname/logical-pathname machinery, structures with `:include` deep customization.
+- **Packages:** simple — `defpackage`/`in-package`/`export`/`use-package`/`:cl`/`:cl-user`. No nicknames, no shadowing-import edge cases.
+
+## Ground rules
+
+- **Scope:** only touch `lib/common-lisp/**` and `plans/common-lisp-on-sx.md`. Don't edit `spec/`, `hosts/`, `shared/`, or any other `lib/<lang>/**`. CL primitives go in `lib/common-lisp/runtime.sx`.
+- **SX files:** use `sx-tree` MCP tools only.
+- **Commits:** one feature per commit. Keep `## Progress log` updated and tick roadmap boxes.
+
+## Architecture sketch
+
+```
+Common Lisp source
+    │
+    ▼
+lib/common-lisp/reader.sx     — tokenizer + reader (read macros, dispatch chars)
+    │
+    ▼
+lib/common-lisp/parser.sx     — AST: forms, declarations, lambda lists
+    │
+    ▼
+lib/common-lisp/transpile.sx  — AST → SX AST (entry: cl-eval-ast)
+    │
+    ▼
+lib/common-lisp/runtime.sx    — special forms, condition system, CLOS, packages, BIFs
+```
+
+Core mapping:
+- **Symbol** = SX symbol with package prefix; package table is a flat dict.
+- **Cons cell** = SX pair via `cons`/`car`/`cdr`; lists native.
+- **Multiple values** = thread through `values`/`multiple-value-bind`; primary-value default for one-context callers.
+- **Block / return-from** = captured continuation; `return-from name v` invokes the block-named `^k`.
+- **Tagbody / go** = each tag is a continuation; `go tag` invokes it.
+- **Unwind-protect** = scope frame with a cleanup thunk fired on any non-local exit.
+- **Conditions / restarts** = layered handler chain on top of `handler-bind` + delcc. `signal` walks handlers; `invoke-restart` resumes a captured continuation.
+- **CLOS** = generic functions are dispatch tables on argument-class lists; method combination computed lazily; `call-next-method` is a continuation.
+- **Macros** = SX macros (sentinel-body) — defmacro lowers directly.
+
+## Roadmap
+
+### Phase 1 — reader + parser
+- [ ] Tokenizer: symbols (with package qualification `pkg:sym` / `pkg::sym`), numbers (int, float, ratio `1/3`, `#xFF`, `#b1010`, `#o17`), strings `"…"` with `\` escapes, characters `#\Space` `#\Newline` `#\a`, comments `;`, block comments `#| … |#`
+- [ ] Reader: list, dotted pair, quote `'`, function `#'`, quasiquote `` ` ``, unquote `,`, splice `,@`, vector `#(…)`, uninterned `#:foo`, nil/t literals
+- [ ] Parser: lambda lists with `&optional` `&rest` `&key` `&aux` `&allow-other-keys`, defaults, supplied-p variables
+- [ ] Unit tests in `lib/common-lisp/tests/read.sx`
+
+### Phase 2 — sequential eval + special forms
+- [ ] `cl-eval-ast`: `quote`, `if`, `progn`, `let`, `let*`, `flet`, `labels`, `setq`, `setf` (subset), `function`, `lambda`, `the`, `locally`, `eval-when`
+- [ ] `block` + `return-from` via captured continuation
+- [ ] `tagbody` + `go` via per-tag continuations
+- [ ] `unwind-protect` cleanup frame
+- [ ] `multiple-value-bind`, `multiple-value-call`, `multiple-value-prog1`, `values`, `nth-value`
+- [ ] `defun`, `defparameter`, `defvar`, `defconstant`, `declaim`, `proclaim` (no-op)
+- [ ] Dynamic variables — `defvar`/`defparameter` produce specials; `let` rebinds via parameterize-style scope
+- [ ] 60+ tests in `lib/common-lisp/tests/eval.sx`
+
+### Phase 3 — conditions + restarts (THE SHOWCASE)
+- [ ] `define-condition` — class hierarchy rooted at `condition`/`error`/`warning`/`simple-error`/`simple-warning`/`type-error`/`arithmetic-error`/`division-by-zero`
+- [ ] `signal`, `error`, `cerror`, `warn` — all walk the handler chain
+- [ ] `handler-bind` — non-unwinding handlers, may decline by returning normally
+- [ ] `handler-case` — unwinding handlers (delcc abort)
+- [ ] `restart-case`, `with-simple-restart`, `restart-bind`
+- [ ] `find-restart`, `invoke-restart`, `invoke-restart-interactively`, `compute-restarts`
+- [ ] `with-condition-restarts` — associate restarts with a specific condition
+- [ ] `*break-on-signals*`, `*debugger-hook*` (basic)
+- [ ] Classic programs in `lib/common-lisp/tests/programs/`:
+  - [ ] `restart-demo.lisp` — division with `:use-zero` and `:retry` restarts
+  - [ ] `parse-recover.lisp` — parser with skipped-token restart
+  - [ ] `interactive-debugger.lisp` — ASCII REPL using `:debugger-hook`
+- [ ] `lib/common-lisp/conformance.sh` + runner, `scoreboard.json` + `scoreboard.md`
+
+### Phase 4 — CLOS
+- [ ] `defclass` with `:initarg`/`:initform`/`:accessor`/`:reader`/`:writer`/`:allocation`
+- [ ] `make-instance`, `slot-value`, `(setf slot-value)`, `with-slots`, `with-accessors`
+- [ ] `defgeneric` with `:method-combination` (standard, plus `+`, `and`, `or`)
+- [ ] `defmethod` with `:before` / `:after` / `:around` qualifiers
+- [ ] `call-next-method` (continuation), `next-method-p`
+- [ ] `class-of`, `find-class`, `slot-boundp`, `change-class` (basic)
+- [ ] Multiple dispatch — method specificity by argument-class precedence list
+- [ ] Built-in classes registered for tagged values (`integer`, `float`, `string`, `symbol`, `cons`, `null`, `t`)
+- [ ] Classic programs:
+  - [ ] `geometry.lisp` — `intersect` generic dispatching on (point line), (line line), (line plane)…
+  - [ ] `mop-trace.lisp` — `:before` + `:after` printing call trace
+
+### Phase 5 — macros + LOOP + reader macros
+- [ ] `defmacro`, `macrolet`, `symbol-macrolet`, `macroexpand-1`, `macroexpand`
+- [ ] `gensym`, `gentemp`
+- [ ] `set-macro-character`, `set-dispatch-macro-character`, `get-macro-character`
+- [ ] **The LOOP macro** — iteration drivers (`for … in/across/from/upto/downto/by`, `while`, `until`, `repeat`), accumulators (`collect`, `append`, `nconc`, `count`, `sum`, `maximize`, `minimize`), conditional clauses (`if`/`when`/`unless`/`else`), termination (`finally`/`thereis`/`always`/`never`), `named` blocks
+- [ ] LOOP test corpus: 30+ tests covering all clause types
+
+### Phase 6 — packages + stdlib drive
+- [ ] `defpackage`, `in-package`, `export`, `use-package`, `import`, `find-package`
+- [ ] Package qualification at the reader level — `cl:car`, `mypkg::internal`
+- [ ] `:common-lisp` (`:cl`) and `:common-lisp-user` (`:cl-user`) packages
+- [ ] Sequence functions — `mapcar`, `mapc`, `mapcan`, `reduce`, `find`, `find-if`, `position`, `count`, `every`, `some`, `notany`, `notevery`, `remove`, `remove-if`, `subst`
+- [ ] List ops — `assoc`, `getf`, `nth`, `last`, `butlast`, `nthcdr`, `tailp`, `ldiff`
+- [ ] String ops — `string=`, `string-upcase`, `string-downcase`, `subseq`, `concatenate`
+- [ ] FORMAT — basic directives `~A`, `~S`, `~D`, `~F`, `~%`, `~&`, `~T`, `~{...~}` (iteration), `~[...~]` (conditional), `~^` (escape), `~P` (plural)
+- [ ] Drive corpus to 200+ green
+
+## Progress log
+
+_Newest first._
+
+- _(none yet)_
+
+## Blockers
+
+- _(none yet)_

plans/hs-blockers-drain.md

@@ -0,0 +1,96 @@
+# HS conformance — blockers drain
+
+Goal: take hyperscript conformance from **1277/1496 (85.4%)** to **1496/1496 (100%)** by clearing the blocked clusters and the design-done Bucket E subsystems.
+
+This plan exists because the per-iteration `loops/hs` agent can't fit these into its 30-min budget — they need dedicated multi-commit sit-downs. Track progress here; refer to `plans/hs-conformance-to-100.md` for the canonical cluster ledger.
+
+## Current state (2026-04-25)
+
+- Loop running in `/root/rose-ash-loops/hs` (branch `loops/hs`)
+- sx-tree MCP **fixed** (was a session-stale binary issue — restart of claude in the tmux window picked it up). Loop hinted to retry **#32**, **#29** first.
+- Recent loop progress: ~1 commit/6h — easy wins drained, what's left needs focused attention.
+
+## Remaining work
+
+### Bucket-A/B/C blockers (small, in-place fixes)
+
+| # | Cluster | Tests | Effort | Blocker | Fix sketch |
+|---|---------|------:|--------|---------|------------|
+| **17** | `tell` semantics | +3 | ~1h | Implicit-default-target ambiguity. `bare add .bar` inside `tell X` should target `X` but explicit `to me` must reach the original element. | Add `beingTold` symbol distinct from `me`; bare commands compile to `beingTold-or-me`; explicit `me` always the original. |
+| **22** | window global fn fallback | +2-4 | ~1h | `foo()` where `foo` isn't SX-defined needs to fall back to `(host-global "foo")`. Three attempts failed: guard (host-level error not catchable), `env-has?` (not in HS kernel), `hs-win-call` (NativeFn not callable from CALL). | Add `symbol-bound?` predicate to HS kernel **OR** a host-call-fn primitive with arity-agnostic dispatch. |
+| **29** | `hyperscript:before:init` / `:after:init` / `:parse-error` events | +4-6 | ~30m (post sx-tree fix) | Was sx-tree MCP outage. Now unblocked — loop should retry. 4 of 6 tests need stricter parser error-rejection (out of scope; mark partial). | Edit `integration.sx` to fire DOM events at activation boundaries. |
+
+### Bucket D — medium features
+
+| # | Cluster | Tests | Effort | Status |
+|---|---------|------:|--------|--------|
+| **31** | runtime null-safety error reporting | **+15-18** | **2-4h** | **THIS SESSION'S TARGET.** Plan node fully spec'd: 5 pieces of work. |
+| **32** | MutationObserver mock + `on mutation` | +10-15 | ~2h | Was sx-tree-blocked. Now unblocked — loop hinted to retry. Multi-file: parser, compiler, runtime, runner mock, generator skip-list. |
+| **33** | cookie API | +2 (remaining) | ~30m | Partial done (+3). Remaining 2 need `hs-method-call` runtime fallback for unknown methods + `hs-for-each` recognising host-array/proxy collections. |
+| 34 | event modifier DSL | +6-8 | ~1-2h | `elsewhere`, `every`, count filters (`once`/`twice`/`3 times`/ranges), `from elsewhere`. Pending. |
+| 35 | namespaced `def` | +3 | ~30m | Pending. |
+
+### Bucket E — subsystems (design docs landed, multi-commit each)
+
+Each has a design doc with a step-by-step checklist. These are 1-2 days of focused work each, not loop-fits.
+
+| # | Subsystem | Tests | Design doc | Branch |
+|---|-----------|------:|------------|--------|
+| 36 | WebSocket + `socket` + RPC Proxy | +12-16 | `plans/designs/e36-websocket.md` | `worktree-agent-a9daf73703f520257` |
+| 37 | Tokenizer-as-API | +16-17 | `plans/designs/e37-tokenizer-api.md` | `worktree-agent-a6bb61d59cc0be8b4` |
+| 38 | SourceInfo API | +4 | `plans/designs/e38-sourceinfo.md` | `agent-e38-sourceinfo` |
+| 39 | WebWorker plugin (parser-only stub) | +1 | `plans/designs/e39-webworker.md` | `hs-design-e39-webworker` |
+| 40 | Real Fetch / non-2xx / before-fetch | +7 | `plans/designs/e40-real-fetch.md` | `worktree-agent-a94612a4283eaa5e0` |
+
+### Bucket F — generator translation gaps
+
+~25 tests SKIP'd because `tests/playwright/generate-sx-tests.py` bails with `return None`. Single dedicated generator-repair sit-down once Bucket D is drained. ~half-day.
+
+## Order of attack
+
+In approximate cost-per-test order:
+
+1. **Loop self-heal** (no human work) — wait for #29, #32 to land via the running loop ⏱️ ~next 1-2 hours
+2. **#31 null-safety** — biggest scoped single win, dedicated worktree agent (this session)
+3. **#33 cookie API remainder** — quick partial completion
+4. **#17 / #22 / #34 / #35** — small fiddly fixes, one sit-down each
+5. **Bucket E** — pick one subsystem at a time. **#39 (WebWorker stub) first** — single commit, smallest. Then **#38 (SourceInfo)** — 4 commits. Then the bigger three (#36, #37, #40).
+6. **Bucket F** — generator repair sweep at the end.
+
+Estimated total to 100%: ~10-15 days of focused work, parallelisable across branches.
+
+## Cluster #31 spec (full detail)
+
+The plan note from `hs-conformance-to-100.md`:
+
+> 18 tests in `runtimeErrors`. When accessing `.foo` on nil, emit a structured error with position info. One coordinated fix in the compiler emit paths for property access, function calls, set/put.
+
+**Required pieces:**
+
+1. **Generator-side `eval-hs-error` helper + recognizer** for `expect(await error("HS")).toBe("MSG")` blocks. In `tests/playwright/generate-sx-tests.py`.
+2. **Runtime helpers** in `lib/hyperscript/runtime.sx`:
+   - `hs-null-error!` raising `'<sel>' is null`
+   - `hs-named-target` — wraps a query result with the original selector source
+   - `hs-named-target-list` — same for list results
+3. **Compiler patches at every target-position `(query SEL)` emit** — wrap in named-target carrying the original selector source. ~17 command emit paths in `lib/hyperscript/compiler.sx`:
+   add, remove, hide, show, measure, settle, trigger, send, set, default, increment, decrement, put, toggle, transition, append, take.
+4. **Function-call null-check** at bare `(name)`, `hs-method-call`, and `host-get` chains, deriving the leftmost-uncalled-name (`'x'` / `'x.y'`) from the parse tree.
+5. **Possessive-base null-check** (`set x's y to true` → `'x' is null`).
+
+**Files in scope:**
+- `lib/hyperscript/runtime.sx` (new helpers)
+- `lib/hyperscript/compiler.sx` (~17 emit-path edits)
+- `tests/playwright/generate-sx-tests.py` (test recognizer)
+- `tests/hs-run-filtered.js` (if mock helpers needed)
+- `shared/static/wasm/sx/hs-runtime.sx` + `hs-compiler.sx` (WASM staging copies)
+
+**Approach:** target-named pieces incrementally — runtime helpers first (no compiler change), then compiler emit paths in batches (group similar commands), then function-call/possessive at the end. Each batch is one commit if it lands +N tests; mark partial if it only unlocks part.
+
+**Watch for:** smoke-range regressions (tests flipping pass→fail). Each commit: rerun smoke 0-195 and the `runtimeErrors` suite.
+
+## Notes for future sessions
+
+- `plans/hs-conformance-to-100.md` is the canonical cluster ledger — update it on every commit.
+- `plans/hs-conformance-scoreboard.md` is the live tally — bump `Merged:` and the bucket roll-up.
+- Loop has scope rule "never edit `spec/evaluator.sx` or broader SX kernel" — most fixes here stay in `lib/hyperscript/**`, `tests/`, generator. If a fix needs kernel work, surface to the user; don't merge silently.
+- Cluster #22's `symbol-bound?` predicate would be a kernel addition — that's a real cross-boundary scope expansion.

plans/ruby-on-sx.md

@@ -0,0 +1,125 @@
+# Ruby-on-SX: fibers + blocks + open classes on delimited continuations
+
+The headline showcase is **fibers** — Ruby's `Fiber.new { … Fiber.yield v … }` / `Fiber.resume` are textbook delimited continuations with sugar. MRI implements them by swapping C stacks; on SX they fall out of the existing `perform`/`cek-resume` machinery for free. Plus blocks/yield (lexical escape continuations, same shape as Smalltalk's non-local return), method_missing, and singleton classes.
+
+End-state goal: Ruby 2.7-flavoured subset, Enumerable mixin, fibers + threads-via-fibers (no real OS threads), method_missing-driven DSLs, ~150 hand-written + classic programs.
+
+## Scope decisions (defaults — override by editing before we spawn)
+
+- **Syntax:** Ruby 2.7. No 3.x pattern matching, no rightward assignment, no endless methods. We pick 2.7 because it's the biggest semantic surface that still parses cleanly.
+- **Conformance:** "Reads like Ruby, runs like Ruby." Slice of RubySpec (Core + Library subset), not full RubySpec.
+- **Test corpus:** custom + curated RubySpec slice. Plus classic programs: fiber-based generator, internal DSL with method_missing, mixin-based Enumerable on a custom class.
+- **Out of scope:** real threads, GIL, refinements, `binding_of_caller` from non-Ruby contexts, Encoding object beyond UTF-8/ASCII-8BIT, RubyVM::* introspection beyond bytecode-disassembly placeholder, IO subsystem beyond `puts`/`gets`/`File.read`.
+- **Symbols:** SX symbols. Strings are mutable copies; symbols are interned.
+
+## Ground rules
+
+- **Scope:** only touch `lib/ruby/**` and `plans/ruby-on-sx.md`. Don't edit `spec/`, `hosts/`, `shared/`, or any other `lib/<lang>/**`. Ruby primitives go in `lib/ruby/runtime.sx`.
+- **SX files:** use `sx-tree` MCP tools only.
+- **Commits:** one feature per commit. Keep `## Progress log` updated and tick roadmap boxes.
+
+## Architecture sketch
+
+```
+Ruby source
+    │
+    ▼
+lib/ruby/tokenizer.sx   — keywords, ops, %w[], %i[], heredocs (deferred), regex (deferred)
+    │
+    ▼
+lib/ruby/parser.sx      — AST: classes, modules, methods, blocks, calls
+    │
+    ▼
+lib/ruby/transpile.sx   — AST → SX AST (entry: rb-eval-ast)
+    │
+    ▼
+lib/ruby/runtime.sx     — class table, MOP, dispatch, fibers, primitives
+```
+
+Core mapping:
+- **Object** = SX dict `{:class :ivars :singleton-class?}`. Instance variables live in `ivars` keyed by symbol.
+- **Class** = SX dict `{:name :superclass :methods :class-methods :metaclass :includes :prepends}`. Class table is flat.
+- **Method dispatch** = lookup walks ancestor chain (prepended → class → included modules → superclass → …). Falls back to `method_missing` with a `Symbol`+args.
+- **Block** = lambda + escape continuation. `yield` invokes the block in current context. `return` from within a block invokes the enclosing-method's escape continuation.
+- **Proc** = lambda without strict arity. `Proc.new` + `proc {}`.
+- **Lambda** = lambda with strict arity + `return`-returns-from-lambda semantics.
+- **Fiber** = pair of continuations (resume-k, yield-k) wrapped in a record. `Fiber.new { … }` builds it; `Fiber.resume` invokes the resume-k; `Fiber.yield` invokes the yield-k. Built directly on `perform`/`cek-resume`.
+- **Module** = class without instance allocation. `include` puts it in the chain; `prepend` puts it earlier; `extend` puts it on the singleton.
+- **Singleton class** = lazily allocated per-object class for `def obj.foo` definitions.
+- **Symbol** = interned SX symbol. `:foo` reads as `(quote foo)` flavour.
+
+## Roadmap
+
+### Phase 1 — tokenizer + parser
+- [x] Tokenizer: keywords (`def end class module if unless while until do return yield begin rescue ensure case when then else elsif`), identifiers (lowercase = local/method, `@` = ivar, `@@` = cvar, `$` = global, uppercase = constant), numbers (int, float, `0x` `0o` `0b`, `_` separators), strings (`"…"` interpolation, `'…'` literal, `%w[a b c]`, `%i[a b c]`), symbols `:foo` `:"…"`, operators (`+ - * / % ** == != < > <= >= <=> === =~ !~ << >> & | ^ ~ ! && || and or not`), `:: . , ; ( ) [ ] { } -> => |`, comments `#`
+- [x] Parser: program is sequence of statements separated by newlines or `;`; method def `def name(args) … end`; class `class Foo < Bar … end`; module `module M … end`; block `do |a, b| … end` and `{ |a, b| … }`; call sugar (no parens), `obj.method`, `Mod::Const`; arg shapes (positional, default, splat `*args`, double-splat `**opts`, block `&blk`)
+- [ ] If/while/case expressions (return values), `unless`/`until`, postfix modifiers
+- [ ] Begin/rescue/ensure/retry, raise, raise with class+message
+- [x] Unit tests in `lib/ruby/tests/parse.sx`
+
+### Phase 2 — object model + sequential eval
+- [ ] Class table bootstrap: `BasicObject`, `Object`, `Kernel`, `Module`, `Class`, `Numeric`, `Integer`, `Float`, `String`, `Symbol`, `Array`, `Hash`, `Range`, `NilClass`, `TrueClass`, `FalseClass`, `Proc`, `Method`
+- [ ] `rb-eval-ast`: literals, variables (local, ivar, cvar, gvar, constant), assignment (single and parallel `a, b = 1, 2`, splat receive), method call, message dispatch
+- [ ] Method lookup walks ancestor chain; cache hit-class per `(class, selector)`
+- [ ] `method_missing` fallback constructing args list
+- [ ] `super` and `super(args)` — lookup in defining class's superclass
+- [ ] Singleton class allocation on first `def obj.foo` or `class << obj`
+- [ ] `nil`, `true`, `false` are singletons of their classes; tagged values aren't boxed
+- [ ] Constant lookup (lexical-then-inheritance) with `Module.nesting`
+- [ ] 60+ tests in `lib/ruby/tests/eval.sx`
+
+### Phase 3 — blocks + procs + lambdas
+- [ ] Method invocation captures escape continuation `^k` for `return`; binds it as block's escape
+- [ ] `yield` invokes implicit block
+- [ ] `block_given?`, `&blk` parameter, `&proc` arg unpacking
+- [ ] `Proc.new`, `proc { }`, `lambda { }` (or `->(x) { x }`)
+- [ ] Lambda strict arity + lambda-local `return` semantics
+- [ ] Proc lax arity (`a, b, c` unpacks Array; missing args nil)
+- [ ] `break`, `next`, `redo` — `break` is escape-from-loop-or-block; `next` is escape-from-block-iteration; `redo` re-runs current iteration
+- [ ] 30+ tests in `lib/ruby/tests/blocks.sx`
+
+### Phase 4 — fibers (THE SHOWCASE)
+- [ ] `Fiber.new { |arg| … Fiber.yield v … }` allocates a fiber record with paired continuations
+- [ ] `Fiber.resume(args…)` resumes the fiber, returning the value passed to `Fiber.yield`
+- [ ] `Fiber.yield(v)` from inside the fiber suspends and returns control to the resumer
+- [ ] `Fiber.current` from inside the fiber
+- [ ] `Fiber#alive?`, `Fiber#raise` (deferred)
+- [ ] `Fiber.transfer` — symmetric coroutines (resume from any side)
+- [ ] Classic programs in `lib/ruby/tests/programs/`:
+  - [ ] `generator.rb` — pull-style infinite enumerator built on fibers
+  - [ ] `producer-consumer.rb` — bounded buffer with `Fiber.transfer`
+  - [ ] `tree-walk.rb` — recursive tree walker that yields each node, driven by `Fiber.resume`
+- [ ] `lib/ruby/conformance.sh` + runner, `scoreboard.json` + `scoreboard.md`
+
+### Phase 5 — modules + mixins + metaprogramming
+- [ ] `include M` — appends M's methods after class methods in chain
+- [ ] `prepend M` — prepends M before class methods
+- [ ] `extend M` — adds M to singleton class
+- [ ] `Module#ancestors`, `Module#included_modules`
+- [ ] `define_method`, `class_eval`, `instance_eval`, `module_eval`
+- [ ] `respond_to?`, `respond_to_missing?`, `method_missing`
+- [ ] `Object#send`, `Object#public_send`, `Object#__send__`
+- [ ] `Module#method_added`, `singleton_method_added` hooks
+- [ ] Hooks: `included`, `extended`, `inherited`, `prepended`
+- [ ] Internal-DSL classic program: `lib/ruby/tests/programs/dsl.rb`
+
+### Phase 6 — stdlib drive
+- [ ] `Enumerable` mixin: `each` (abstract), `map`, `select`/`filter`, `reject`, `reduce`/`inject`, `each_with_index`, `each_with_object`, `take`, `drop`, `take_while`, `drop_while`, `find`/`detect`, `find_index`, `any?`, `all?`, `none?`, `one?`, `count`, `min`, `max`, `min_by`, `max_by`, `sort`, `sort_by`, `group_by`, `partition`, `chunk`, `each_cons`, `each_slice`, `flat_map`, `lazy`
+- [ ] `Comparable` mixin: `<=>`, `<`, `<=`, `>`, `>=`, `==`, `between?`, `clamp`
+- [ ] `Array`: indexing, slicing, `push`/`pop`/`shift`/`unshift`, `concat`, `flatten`, `compact`, `uniq`, `sort`, `reverse`, `zip`, `dig`, `pack`/`unpack` (deferred)
+- [ ] `Hash`: `[]`, `[]=`, `delete`, `merge`, `each_pair`, `keys`, `values`, `to_a`, `dig`, `fetch`, default values, default proc
+- [ ] `Range`: `each`, `step`, `cover?`, `include?`, `size`, `min`, `max`
+- [ ] `String`: indexing, slicing, `split`, `gsub` (string-arg version, regex deferred), `sub`, `upcase`, `downcase`, `strip`, `chomp`, `chars`, `bytes`, `to_i`, `to_f`, `to_sym`, `*`, `+`, `<<`, format with `%`
+- [ ] `Integer`: `times`, `upto`, `downto`, `step`, `digits`, `gcd`, `lcm`
+- [ ] Drive corpus to 200+ green
+
+## Progress log
+
+_Newest first._
+
+- 2026-04-25: Phase 1 parser complete — `lib/ruby/parser.sx` (rb-parse/rb-parse-str) + `lib/ruby/tests/parse.sx` (83/83 tests). Program, method-def (all param shapes), class/module/sclass, blocks (do/brace), method calls (parens + no-parens + chains), const-path, assignment (=, op=, massign), binary/unary ops with precedence, array/hash literals, return/yield/break/next/redo/raise, indexing.
+- 2026-04-25: Phase 1 tokenizer complete — `lib/ruby/tokenizer.sx` + `lib/ruby/tests/tokenizer.sx` (107/107 tests). Keywords, identifiers (@ivar @@cvar $gvar), numbers (dec/hex/octal/binary/float), strings (dq with interpolation kept raw, sq), symbols, %w/%i literals, operators (all compound forms), punctuation, comments, line/col tracking.
+
+## Blockers
+
+- _(none yet)_

plans/smalltalk-on-sx.md

@@ -0,0 +1,116 @@
+# Smalltalk-on-SX: blocks with non-local return on delimited continuations
+
+The headline showcase is **blocks** — Smalltalk's closures with non-local return (`^expr` aborts the enclosing *method*, not the block). Every other Smalltalk on top of a host VM (RSqueak on PyPy, GemStone on C, Maxine on Java) reinvents non-local return on whatever stack discipline the host gives them. On SX it's a one-liner: a block holds a captured continuation; `^` just invokes it. Message-passing OO falls out cheaply on top of the existing component / dispatch machinery.
+
+End-state goal: ANSI-ish Smalltalk-80 subset, SUnit working, ~200 hand-written tests + a vendored slice of the Pharo kernel tests, classic corpus (eight queens, quicksort, mandelbrot, Conway's Life).
+
+## Scope decisions (defaults — override by editing before we spawn)
+
+- **Syntax:** Pharo / Squeak chunk format (`!` separators, `Object subclass: #Foo …`). No fileIn/fileOut images — text source only.
+- **Conformance:** ANSI X3J20 *as a target*, not bug-for-bug Squeak. "Reads like Smalltalk, runs like Smalltalk."
+- **Test corpus:** SUnit ported to SX-Smalltalk + custom programs + a curated slice of Pharo `Kernel-Tests` / `Collections-Tests`.
+- **Image:** out of scope. Source-only. No `become:` between sessions, no snapshotting.
+- **Reflection:** `class`, `respondsTo:`, `perform:`, `doesNotUnderstand:` in. `become:` (object-identity swap) **in** — it's a good CEK exercise. Method modification at runtime in.
+- **GUI / Morphic / threads:** out entirely.
+
+## Ground rules
+
+- **Scope:** only touch `lib/smalltalk/**` and `plans/smalltalk-on-sx.md`. Don't edit `spec/`, `hosts/`, `shared/`, or any other `lib/<lang>/**`. Smalltalk primitives go in `lib/smalltalk/runtime.sx`.
+- **SX files:** use `sx-tree` MCP tools only.
+- **Commits:** one feature per commit. Keep `## Progress log` updated and tick roadmap boxes.
+
+## Architecture sketch
+
+```
+Smalltalk source
+    │
+    ▼
+lib/smalltalk/tokenizer.sx  — selectors, keywords, literals, $c, #sym, #(…), $'…'
+    │
+    ▼
+lib/smalltalk/parser.sx     — AST: classes, methods, blocks, cascades, sends
+    │
+    ▼
+lib/smalltalk/transpile.sx  — AST → SX AST (entry: smalltalk-eval-ast)
+    │
+    ▼
+lib/smalltalk/runtime.sx    — class table, MOP, dispatch, primitives
+```
+
+Core mapping:
+- **Class** = SX dict `{:name :superclass :ivars :methods :class-methods :metaclass}`. Class table is a flat dict keyed by class name.
+- **Object** = SX dict `{:class :ivars}` — `ivars` keyed by symbol. Tagged ints / floats / strings / symbols are not boxed; their class is looked up by SX type.
+- **Method** = SX lambda closing over a `self` binding + temps. Body wrapped in a delimited continuation so `^` can escape.
+- **Message send** = `(st-send receiver selector args)` — does class-table lookup, walks superclass chain, falls back to `doesNotUnderstand:` with a `Message` object.
+- **Block** `[:x | … ^v … ]` = lambda + captured `^k` (the method-return continuation). Invoking `^` calls `k`; outer block invocation past method return raises `BlockContext>>cannotReturn:`.
+- **Cascade** `r m1; m2; m3` = `(let ((tmp r)) (st-send tmp 'm1 ()) (st-send tmp 'm2 ()) (st-send tmp 'm3 ()))`.
+- **`ifTrue:ifFalse:` / `whileTrue:`** = ordinary block sends; the runtime intrinsifies them in the JIT path so they compile to native branches (Tier 1 of bytecode expansion already covers this pattern).
+- **`become:`** = swap two object identities everywhere — in SX this is a heap walk, but we restrict to `oneWayBecome:` (cheap: rewrite class field) by default.
+
+## Roadmap
+
+### Phase 1 — tokenizer + parser
+- [ ] Tokenizer: identifiers, keywords (`foo:`), binary selectors (`+`, `==`, `,`, `->`, `~=` etc.), numbers (radix `16r1F`, scaled `1.5s2`), strings `'…''…'`, characters `$c`, symbols `#foo` `#'foo bar'` `#+`, byte arrays `#[1 2 3]`, literal arrays `#(1 #foo 'x')`, comments `"…"`
+- [ ] Parser: chunk format (`! !` separators), class definitions (`Object subclass: #X instanceVariableNames: '…' classVariableNames: '…' …`), method definitions (`extend: #Foo with: 'bar ^self'`), pragmas `<primitive: 1>`, blocks `[:a :b | | t1 t2 | …]`, cascades, message precedence (unary > binary > keyword)
+- [ ] Unit tests in `lib/smalltalk/tests/parse.sx`
+
+### Phase 2 — object model + sequential eval
+- [ ] Class table + bootstrap: `Object`, `Behavior`, `Class`, `Metaclass`, `UndefinedObject`, `Boolean`/`True`/`False`, `Number`/`Integer`/`Float`, `String`, `Symbol`, `Array`, `Block`
+- [ ] `smalltalk-eval-ast`: literals, variable reference, assignment, message send, cascade, sequence, return
+- [ ] Method lookup: walk class → superclass; cache hit-class on `(class, selector)`
+- [ ] `doesNotUnderstand:` fallback constructing `Message` object
+- [ ] `super` send (lookup starts at superclass of *defining* class, not receiver class)
+- [ ] 30+ tests in `lib/smalltalk/tests/eval.sx`
+
+### Phase 3 — blocks + non-local return (THE SHOWCASE)
+- [ ] Method invocation captures a `^k` (the return continuation) and binds it as the block's escape
+- [ ] `^expr` from inside a block invokes that captured `^k`
+- [ ] `BlockContext>>value`, `value:`, `value:value:`, …, `valueWithArguments:`
+- [ ] `whileTrue:` / `whileTrue` / `whileFalse:` / `whileFalse` as ordinary block sends — runtime intrinsifies the loop in the bytecode JIT
+- [ ] `ifTrue:` / `ifFalse:` / `ifTrue:ifFalse:` as block sends, similarly intrinsified
+- [ ] Escape past returned-from method raises `BlockContext>>cannotReturn:`
+- [ ] Classic programs in `lib/smalltalk/tests/programs/`:
+  - [ ] `eight-queens.st`
+  - [ ] `quicksort.st`
+  - [ ] `mandelbrot.st`
+  - [ ] `life.st` (Conway's Life, glider gun)
+  - [ ] `fibonacci.st` (recursive + memoised)
+- [ ] `lib/smalltalk/conformance.sh` + runner, `scoreboard.json` + `scoreboard.md`
+
+### Phase 4 — reflection + MOP
+- [ ] `Object>>class`, `class>>name`, `class>>superclass`, `class>>methodDict`, `class>>selectors`
+- [ ] `Object>>perform:` / `perform:with:` / `perform:withArguments:`
+- [ ] `Object>>respondsTo:`, `Object>>isKindOf:`, `Object>>isMemberOf:`
+- [ ] `Behavior>>compile:` — runtime method addition
+- [ ] `Object>>becomeForward:` (one-way become; rewrites the class field of `aReceiver`)
+- [ ] Exceptions: `Exception`, `Error`, `signal`, `signal:`, `on:do:`, `ensure:`, `ifCurtailed:` — built on top of SX `handler-bind`/`raise`
+
+### Phase 5 — collections + numeric tower
+- [ ] `SequenceableCollection`/`OrderedCollection`/`Array`/`String`/`Symbol`
+- [ ] `HashedCollection`/`Set`/`Dictionary`/`IdentityDictionary`
+- [ ] `Stream` hierarchy: `ReadStream`/`WriteStream`/`ReadWriteStream`
+- [ ] `Number` tower: `SmallInteger`/`LargePositiveInteger`/`Float`/`Fraction`
+- [ ] `String>>format:`, `printOn:` for everything
+
+### Phase 6 — SUnit + corpus to 200+
+- [ ] Port SUnit (TestCase, TestSuite, TestResult) — written in SX-Smalltalk, runs in itself
+- [ ] Vendor a slice of Pharo `Kernel-Tests` and `Collections-Tests`
+- [ ] Drive the scoreboard up: aim for 200+ green tests
+- [ ] Stretch: ANSI Smalltalk validator subset
+
+### Phase 7 — speed (optional)
+- [ ] Method-dictionary inline caching (already in CEK as a primitive; just wire selector cache)
+- [ ] Block intrinsification beyond `whileTrue:` / `ifTrue:`
+- [ ] Compare against GNU Smalltalk on the corpus
+
+## Progress log
+
+_Newest first. Agent appends on every commit._
+
+- _(none yet)_
+
+## Blockers
+
+_Shared-file issues that need someone else to fix. Minimal repro only._
+
+- _(none yet)_

plans/tcl-on-sx.md

@@ -0,0 +1,127 @@
+# Tcl-on-SX: uplevel/upvar = stack-walking delcc, everything-is-a-string
+
+The headline showcase is **uplevel/upvar** — Tcl's superpower for defining your own control structures. `uplevel` evaluates a script in the *caller's* stack frame; `upvar` aliases a variable in the caller. On a normal language host this requires deep VM cooperation; on SX it falls out of the env-chain made first-class via captured continuations. Plus the *Dodekalogue* (12 rules), command-substitution everywhere, and "everything is a string" homoiconicity.
+
+End-state goal: Tcl 8.6-flavoured subset, the Dodekalogue parser, namespaces, `try`/`catch`/`return -code`, `coroutine` (built on fibers), classic programs that show off uplevel-driven DSLs, ~150 hand-written tests.
+
+## Scope decisions (defaults — override by editing before we spawn)
+
+- **Syntax:** Tcl 8.6 surface. The 12-rule Dodekalogue. Brace-quoted scripts deferred-evaluate; double-quoted ones substitute.
+- **Conformance:** "Reads like Tcl, runs like Tcl." Slice of Tcl's own test suite, not full TCT.
+- **Test corpus:** custom + curated `tcl-tests/` slice. Plus classic programs: define-your-own `for-each-line`, expression-language compiler-in-Tcl, fiber-based event loop.
+- **Out of scope:** Tk, sockets beyond a stub, threads (mapped to `coroutine` only), `package require` of binary loadables, `dde`/`registry` Windows shims, full `clock format` locale support.
+- **Channels:** `puts` and `gets` on `stdout`/`stdin`/`stderr`; `open` on regular files; no async I/O beyond what `coroutine` gives.
+
+## Ground rules
+
+- **Scope:** only touch `lib/tcl/**` and `plans/tcl-on-sx.md`. Don't edit `spec/`, `hosts/`, `shared/`, or any other `lib/<lang>/**`. Tcl primitives go in `lib/tcl/runtime.sx`.
+- **SX files:** use `sx-tree` MCP tools only.
+- **Commits:** one feature per commit. Keep `## Progress log` updated and tick roadmap boxes.
+
+## Architecture sketch
+
+```
+Tcl source
+    │
+    ▼
+lib/tcl/tokenizer.sx   — the Dodekalogue: words, [..], ${..}, "..", {..}, ;, \n, \, #
+    │
+    ▼
+lib/tcl/parser.sx      — list-of-words AST (script = list of commands; command = list of words)
+    │
+    ▼
+lib/tcl/transpile.sx   — AST → SX AST (entry: tcl-eval-script)
+    │
+    ▼
+lib/tcl/runtime.sx     — env stack, command table, uplevel/upvar, coroutines, BIFs
+```
+
+Core mapping:
+- **Value** = string. Internally we cache a "shimmer" representation (list, dict, integer, double) for performance, but every value can be re-stringified.
+- **Variable** = entry in current frame's env. Frames form a stack; level-0 is the global frame.
+- **Command** = entry in command table; first word of any list dispatches into it. User-defined via `proc`. Built-ins are SX functions registered in the table.
+- **Frame** = `{:locals (dict) :level n :parent frame}`. Each `proc` call pushes a frame; commands run in current frame.
+- **`uplevel #N script`** = walk frame chain to absolute level N (or relative if no `#`); evaluate script in that frame's env.
+- **`upvar [#N] varname localname`** = bind `localname` in the current frame as an alias to `varname` in the level-N frame (env-chain delegate).
+- **`return -code N`** = control flow as integers: 0=ok, 1=error, 2=return, 3=break, 4=continue. `catch` traps any non-zero; `try` adds named handlers.
+- **`coroutine`** = fiber on top of `perform`/`cek-resume`. `yield`/`yieldto` suspend; calling the coroutine command resumes.
+- **List / dict** = list-shaped string ("element1 element2 …") with a cached parsed form. Modifications dirty the string cache.
+
+## Roadmap
+
+### Phase 1 — tokenizer + parser (the Dodekalogue)
+- [ ] Tokenizer applying the 12 rules:
+  1. Commands separated by `;` or newlines
+  2. Words separated by whitespace within a command
+  3. Double-quoted words: `\` escapes + `[…]` + `${…}` + `$var` substitution
+  4. Brace-quoted words: literal, no substitution; brace count must balance
+  5. Argument expansion: `{*}list`
+  6. Command substitution: `[script]` evaluates script, takes its return value
+  7. Variable substitution: `$name`, `${name}`, `$arr(idx)`, `$arr($i)`
+  8. Backslash substitution: `\n`, `\t`, `\\`, `\xNN`, `\uNNNN`, `\<newline>` continues
+  9. Comments: `#` only at the start of a command
+  10. Order of substitution is left-to-right, single-pass
+  11. Substitutions don't recurse — substituted text is not re-parsed
+  12. The result of any substitution is the value, not a new script
+- [ ] Parser: script = list of commands; command = list of words; word = literal string + list of substitutions
+- [ ] Unit tests in `lib/tcl/tests/parse.sx`
+
+### Phase 2 — sequential eval + core commands
+- [ ] `tcl-eval-script`: walk command list, dispatch each first-word into command table
+- [ ] Core commands: `set`, `unset`, `incr`, `append`, `lappend`, `puts`, `gets`, `expr`, `if`, `while`, `for`, `foreach`, `switch`, `break`, `continue`, `return`, `error`, `eval`, `subst`, `format`, `scan`
+- [ ] `expr` is its own mini-language — operator precedence, function calls (`sin`, `sqrt`, `pow`, `abs`, `int`, `double`), variable substitution, command substitution
+- [ ] String commands: `string length`, `string index`, `string range`, `string compare`, `string match`, `string toupper`, `string tolower`, `string trim`, `string map`, `string repeat`, `string first`, `string last`, `string is`, `string cat`
+- [ ] List commands: `list`, `lindex`, `lrange`, `llength`, `lreverse`, `lsearch`, `lsort`, `lsort -integer/-real/-dictionary`, `lreplace`, `linsert`, `concat`, `split`, `join`
+- [ ] Dict commands: `dict create`, `dict get`, `dict set`, `dict unset`, `dict exists`, `dict keys`, `dict values`, `dict size`, `dict for`, `dict update`, `dict merge`
+- [ ] 60+ tests in `lib/tcl/tests/eval.sx`
+
+### Phase 3 — proc + uplevel + upvar (THE SHOWCASE)
+- [ ] `proc name args body` — register user-defined command; args supports defaults `{name default}` and rest `args`
+- [ ] Frame stack: each proc call pushes a frame with locals dict; pop on return
+- [ ] `uplevel ?level? script` — evaluate `script` in level-N frame's env; default level is 1 (caller). `#0` is global, `#1` is relative-1
+- [ ] `upvar ?level? otherVar localVar ?…?` — alias localVar to a variable in level-N frame; reads/writes go through the alias
+- [ ] `info level`, `info level N`, `info frame`, `info vars`, `info locals`, `info globals`, `info commands`, `info procs`, `info args`, `info body`
+- [ ] `global var ?…?` — alias to global frame (sugar for `upvar #0 var var`)
+- [ ] `variable name ?value?` — namespace-scoped global
+- [ ] Classic programs in `lib/tcl/tests/programs/`:
+  - [ ] `for-each-line.tcl` — define your own loop construct using `uplevel`
+  - [ ] `assert.tcl` — assertion macro that reports caller's line
+  - [ ] `with-temp-var.tcl` — scoped variable rebind via `upvar`
+- [ ] `lib/tcl/conformance.sh` + runner, `scoreboard.json` + `scoreboard.md`
+
+### Phase 4 — control flow + error handling
+- [ ] `return -code (ok|error|return|break|continue|N) -errorinfo … -errorcode … -level N value`
+- [ ] `catch script ?resultVar? ?optionsVar?` — runs script, returns code; sets resultVar to return value/message; optionsVar to the dict
+- [ ] `try script ?on code var body ...? ?trap pattern var body...? ?finally body?`
+- [ ] `throw type message`
+- [ ] `error message ?info? ?code?`
+- [ ] Stack-trace with `errorInfo` / `errorCode`
+- [ ] 30+ tests in `lib/tcl/tests/error.sx`
+
+### Phase 5 — namespaces + ensembles
+- [ ] `namespace eval ns body`, `namespace current`, `namespace which`, `namespace import`, `namespace export`, `namespace forget`, `namespace delete`
+- [ ] Qualified names: `::ns::cmd`, `::ns::var`
+- [ ] Ensembles: `namespace ensemble create -map { sub1 cmd1 sub2 cmd2 }`
+- [ ] `namespace path` for resolution chain
+- [ ] `proc` and `variable` work inside namespaces
+
+### Phase 6 — coroutines + drive corpus
+- [ ] `coroutine name cmd ?args…?` — start a coroutine; future calls to `name` resume it
+- [ ] `yield ?value?` — suspend, return value to resumer
+- [ ] `yieldto cmd ?args…?` — symmetric transfer
+- [ ] `coroutine` semantics built on fibers (same delcc primitive as Ruby fibers)
+- [ ] Classic programs: `event-loop.tcl` — cooperative scheduler with multiple coroutines
+- [ ] System: `clock seconds`, `clock format`, `clock scan` (subset)
+- [ ] File I/O: `open`, `close`, `read`, `gets`, `puts -nonewline`, `flush`, `eof`, `seek`, `tell`
+- [ ] Drive corpus to 150+ green
+- [ ] Idiom corpus — `lib/tcl/tests/idioms.sx` covering classic Welch/Jones idioms
+
+## Progress log
+
+_Newest first._
+
+- _(none yet)_
+
+## Blockers
+
+- _(none yet)_

scripts/sx-loops-down.sh

@@ -30,7 +30,7 @@ fi
 
 if [ "$CLEAN" = "1" ]; then
   cd "$(dirname "$0")/.."
-  for lang in lua prolog forth erlang haskell js hs; do
+  for lang in lua prolog forth erlang haskell js hs smalltalk common-lisp apl ruby tcl; do
     wt="$WORKTREE_BASE/$lang"
     if [ -d "$wt" ]; then
       git worktree remove --force "$wt" 2>/dev/null || rm -rf "$wt"
@@ -39,5 +39,5 @@ if [ "$CLEAN" = "1" ]; then
   done
   git worktree prune
   echo "Worktree branches (loops/<lang>) are preserved. Delete manually if desired:"
-  echo "  git branch -D loops/lua loops/prolog loops/forth loops/erlang loops/haskell loops/js loops/hs"
+  echo "  git branch -D loops/lua loops/prolog loops/forth loops/erlang loops/haskell loops/js loops/hs loops/smalltalk loops/common-lisp loops/apl loops/ruby loops/tcl"
 fi

scripts/sx-loops-up.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Spawn 7 claude sessions in tmux, one per language loop.
+# Spawn 12 claude sessions in tmux, one per language loop.
 # Each runs in its own git worktree rooted at /root/rose-ash-loops/<lang>,
 # on branch loops/<lang>. No two loops share a working tree, so there's
 # zero risk of file collisions between languages.
@@ -9,7 +9,7 @@
 #
 # After the script prints done:
 #   tmux a -t sx-loops
-#   Ctrl-B + <window-number> to switch (0=lua ... 6=hs)
+#   Ctrl-B + <window-number> to switch (0=lua ... 11=tcl)
 #   Ctrl-B + d to detach (loops keep running, SSH-safe)
 #
 # Stop: ./scripts/sx-loops-down.sh
@@ -38,8 +38,13 @@ declare -A BRIEFING=(
   [haskell]=haskell-loop.md
   [js]=loop.md
   [hs]=hs-loop.md
+  [smalltalk]=smalltalk-loop.md
+  [common-lisp]=common-lisp-loop.md
+  [apl]=apl-loop.md
+  [ruby]=ruby-loop.md
+  [tcl]=tcl-loop.md
 )
-ORDER=(lua prolog forth erlang haskell js hs)
+ORDER=(lua prolog forth erlang haskell js hs smalltalk common-lisp apl ruby tcl)
 
 mkdir -p "$WORKTREE_BASE"
 
@@ -60,13 +65,13 @@ for lang in "${ORDER[@]}"; do
   fi
 done
 
-# Create tmux session with 7 windows, each cwd in its worktree
+# Create tmux session with one window per language, each cwd in its worktree
 tmux new-session -d -s "$SESSION" -n "${ORDER[0]}" -c "$WORKTREE_BASE/${ORDER[0]}"
 for lang in "${ORDER[@]:1}"; do
   tmux new-window -t "$SESSION" -n "$lang" -c "$WORKTREE_BASE/$lang"
 done
 
-echo "Starting 7 claude sessions..."
+echo "Starting ${#ORDER[@]} claude sessions..."
 for lang in "${ORDER[@]}"; do
   tmux send-keys -t "$SESSION:$lang" "claude" C-m
 done
@@ -89,10 +94,10 @@ for lang in "${ORDER[@]}"; do
 done
 
 echo ""
-echo "Done. 7 loops started in tmux session '$SESSION', each in its own worktree."
+echo "Done. ${#ORDER[@]} loops started in tmux session '$SESSION', each in its own worktree."
 echo ""
 echo "  Attach:    tmux a -t $SESSION"
-echo "  Switch:    Ctrl-B <0..6>  (0=lua 1=prolog 2=forth 3=erlang 4=haskell 5=js 6=hs)"
+echo "  Switch:    Ctrl-B <0..11>  (0=lua 1=prolog 2=forth 3=erlang 4=haskell 5=js 6=hs 7=smalltalk 8=common-lisp 9=apl 10=ruby 11=tcl)"
 echo "  List:      Ctrl-B w"
 echo "  Detach:    Ctrl-B d"
 echo "  Stop:      ./scripts/sx-loops-down.sh"

spec/tests/test-hyperscript-behavioral.sx

@@ -88,6 +88,27 @@
                 (raise _e))))
           (handler me-val))))))
 
+;; Evaluate a hyperscript expression, catch the first error raised, and
+;; return its message string. Used by runtimeErrors tests.
+;; Returns nil if no error is raised (test would then fail equality).
+(define eval-hs-error
+  (fn (src)
+    (let ((sx (hs-to-sx (hs-compile src))))
+      (let ((handler (eval-expr-cek
+              (list (quote fn) (list (quote me))
+                (list (quote let) (list (list (quote it) nil) (list (quote event) nil)) sx)))))
+        (guard
+          (_e
+            (true
+              (if
+                (string? _e)
+                _e
+                (if
+                  (and (list? _e) (= (first _e) "hs-return"))
+                  nil
+                  (str _e)))))
+          (begin (handler nil) nil))))))
+
 ;; ── add (19 tests) ──
 (defsuite "hs-upstream-add"
   (deftest "can add a value to a set"
@@ -2153,41 +2174,75 @@
 ;; ── core/runtimeErrors (18 tests) ──
 (defsuite "hs-upstream-core/runtimeErrors"
   (deftest "reports basic function invocation null errors properly"
-    (error "SKIP (untranslated): reports basic function invocation null errors properly"))
+    (assert= (eval-hs-error "x()") "'x' is null")
+    (assert= (eval-hs-error "x.y()") "'x' is null")
+    (assert= (eval-hs-error "x.y.z()") "'x.y' is null")
+  )
   (deftest "reports basic function invocation null errors properly w/ of"
-    (error "SKIP (untranslated): reports basic function invocation null errors properly w/ of"))
+    (assert= (eval-hs-error "z() of y of x") "'z' is null")
+  )
   (deftest "reports basic function invocation null errors properly w/ possessives"
-    (error "SKIP (untranslated): reports basic function invocation null errors properly w/ possessives"))
+    (assert= (eval-hs-error "x's y()") "'x' is null")
+    (assert= (eval-hs-error "x's y's z()") "'x's y' is null")
+  )
   (deftest "reports null errors on add command properly"
-    (error "SKIP (untranslated): reports null errors on add command properly"))
+    (assert= (eval-hs-error "add .foo to #doesntExist") "'#doesntExist' is null")
+    (assert= (eval-hs-error "add @foo to #doesntExist") "'#doesntExist' is null")
+    (assert= (eval-hs-error "add {display:none} to #doesntExist") "'#doesntExist' is null")
+  )
   (deftest "reports null errors on decrement command properly"
-    (error "SKIP (untranslated): reports null errors on decrement command properly"))
+    (assert= (eval-hs-error "decrement #doesntExist's innerHTML") "'#doesntExist' is null")
+  )
   (deftest "reports null errors on default command properly"
-    (error "SKIP (untranslated): reports null errors on default command properly"))
+    (assert= (eval-hs-error "default #doesntExist's innerHTML to 'foo'") "'#doesntExist' is null")
+  )
   (deftest "reports null errors on hide command properly"
-    (error "SKIP (untranslated): reports null errors on hide command properly"))
+    (assert= (eval-hs-error "hide #doesntExist") "'#doesntExist' is null")
+  )
   (deftest "reports null errors on increment command properly"
-    (error "SKIP (untranslated): reports null errors on increment command properly"))
+    (assert= (eval-hs-error "increment #doesntExist's innerHTML") "'#doesntExist' is null")
+  )
   (deftest "reports null errors on measure command properly"
-    (error "SKIP (untranslated): reports null errors on measure command properly"))
+    (assert= (eval-hs-error "measure #doesntExist") "'#doesntExist' is null")
+  )
   (deftest "reports null errors on put command properly"
-    (error "SKIP (untranslated): reports null errors on put command properly"))
+    (assert= (eval-hs-error "put 'foo' into #doesntExist") "'#doesntExist' is null")
+    (assert= (eval-hs-error "put 'foo' into #doesntExist's innerHTML") "'#doesntExist' is null")
+    (assert= (eval-hs-error "put 'foo' into #doesntExist.innerHTML") "'#doesntExist' is null")
+    (assert= (eval-hs-error "put 'foo' before #doesntExist") "'#doesntExist' is null")
+    (assert= (eval-hs-error "put 'foo' after #doesntExist") "'#doesntExist' is null")
+    (assert= (eval-hs-error "put 'foo' at the start of #doesntExist") "'#doesntExist' is null")
+    (assert= (eval-hs-error "put 'foo' at the end of #doesntExist") "'#doesntExist' is null")
+  )
   (deftest "reports null errors on remove command properly"
-    (error "SKIP (untranslated): reports null errors on remove command properly"))
+    (assert= (eval-hs-error "remove .foo from #doesntExist") "'#doesntExist' is null")
+    (assert= (eval-hs-error "remove @foo from #doesntExist") "'#doesntExist' is null")
+    (assert= (eval-hs-error "remove #doesntExist from #doesntExist") "'#doesntExist' is null")
+  )
   (deftest "reports null errors on send command properly"
-    (error "SKIP (untranslated): reports null errors on send command properly"))
+    (assert= (eval-hs-error "send 'foo' to #doesntExist") "'#doesntExist' is null")
+  )
   (deftest "reports null errors on sets properly"
-    (error "SKIP (untranslated): reports null errors on sets properly"))
+    (assert= (eval-hs-error "set x's y to true") "'x' is null")
+    (assert= (eval-hs-error "set x's @y to true") "'x' is null")
+  )
   (deftest "reports null errors on settle command properly"
-    (error "SKIP (untranslated): reports null errors on settle command properly"))
+    (assert= (eval-hs-error "settle #doesntExist") "'#doesntExist' is null")
+  )
   (deftest "reports null errors on show command properly"
-    (error "SKIP (untranslated): reports null errors on show command properly"))
+    (assert= (eval-hs-error "show #doesntExist") "'#doesntExist' is null")
+  )
   (deftest "reports null errors on toggle command properly"
-    (error "SKIP (untranslated): reports null errors on toggle command properly"))
+    (assert= (eval-hs-error "toggle .foo on #doesntExist") "'#doesntExist' is null")
+    (assert= (eval-hs-error "toggle between .foo and .bar on #doesntExist") "'#doesntExist' is null")
+    (assert= (eval-hs-error "toggle @foo on #doesntExist") "'#doesntExist' is null")
+  )
   (deftest "reports null errors on transition command properly"
-    (error "SKIP (untranslated): reports null errors on transition command properly"))
+    (assert= (eval-hs-error "transition #doesntExist's *visibility to 0") "'#doesntExist' is null")
+  )
   (deftest "reports null errors on trigger command properly"
-    (error "SKIP (untranslated): reports null errors on trigger command properly"))
+    (assert= (eval-hs-error "trigger 'foo' on #doesntExist") "'#doesntExist' is null")
+  )
 )
 
 ;; ── core/scoping (20 tests) ──

tests/playwright/generate-sx-tests.py

@@ -2333,6 +2333,25 @@ def generate_eval_only_test(test, idx):
         hs_expr = extract_hs_expr(m.group(2))
         assertions.append(f'    (assert-throws (eval-hs "{hs_expr}"))')
 
+    # Pattern 4: eval-hs-error — expect(await error("expr")).toBe("msg")
+    # These test that running HS raises an error with a specific message string.
+    for m in re.finditer(
+        r'(?:const\s+\w+\s*=\s*)?(?:await\s+)?error\((["\x27`])(.+?)\1\)'
+        r'(?:[^;]|\n)*?(?:expect\([^)]*\)\.toBe\(([^)]+)\)|\.toBe\(([^)]+)\))',
+        body, re.DOTALL
+    ):
+        hs_expr = extract_hs_expr(m.group(2))
+        expected_raw = (m.group(3) or m.group(4) or '').strip()
+        # Strip only the outermost JS string delimiter (double or single quote)
+        # without touching inner quotes inside the string value.
+        if len(expected_raw) >= 2 and expected_raw[0] == expected_raw[-1] and expected_raw[0] in ('"', "'"):
+            inner = expected_raw[1:-1]
+            expected_sx = '"' + inner.replace('\\', '\\\\').replace('"', '\\"') + '"'
+        else:
+            expected_sx = js_val_to_sx(expected_raw)
+        hs_escaped = hs_expr.replace('\\', '\\\\').replace('"', '\\"')
+        assertions.append(f'    (assert= (eval-hs-error "{hs_escaped}") {expected_sx})')
+
     if not assertions:
         return None  # Can't convert this body pattern
 
@@ -2692,6 +2711,27 @@ output.append('                (nth _e 1)')
 output.append('                (raise _e))))')
 output.append('          (handler me-val))))))')
 output.append('')
+output.append(';; Evaluate a hyperscript expression, catch the first error raised, and')
+output.append(';; return its message string. Used by runtimeErrors tests.')
+output.append(';; Returns nil if no error is raised (test would then fail equality).')
+output.append('(define eval-hs-error')
+output.append('  (fn (src)')
+output.append('    (let ((sx (hs-to-sx (hs-compile src))))')
+output.append('      (let ((handler (eval-expr-cek')
+output.append('              (list (quote fn) (list (quote me))')
+output.append('                (list (quote let) (list (list (quote it) nil) (list (quote event) nil)) sx)))))')
+output.append('        (guard')
+output.append('          (_e')
+output.append('            (true')
+output.append('              (if')
+output.append('                (string? _e)')
+output.append('                _e')
+output.append('                (if')
+output.append('                  (and (list? _e) (= (first _e) "hs-return"))')
+output.append('                  nil')
+output.append('                  (str _e)))))')
+output.append('          (begin (handler nil) nil))))))')
+output.append('')
 
 # Group by category
 categories = OrderedDict()