erlang: Phase 9d — OP_RECEIVE_SCAN stub (+10 vm tests)

lib/erlang/vm/dispatcher.sx

@@ -118,6 +118,49 @@
         (not (= (nth rethrow 0) nil)) (raise (nth rethrow 0))
         :else (nth result 0)))))
 
+;; ── Phase 9d — receive scan opcode ────────────────────────────
+;; Selective receive primitive. Scans a mailbox value-list in arrival
+;; order; for each value, tries each clause's pattern (binding into
+;; env on success); on match returns `{:matched true :index N :body B}`
+;; — the caller decides what to do with the index (queue-delete) and
+;; the body (eval in the now-mutated env). On miss returns
+;; `{:matched false}`, the caller arranges suspension (via OP_PERFORM).
+;;
+;; Operands: (clauses mbox-list env)
+;;   clauses    — list of {:pattern :guards :body} dicts
+;;   mbox-list  — SX list of message values
+;;   env        — env dict (mutated on match)
+
+(define er-vm-receive-try-clauses
+  (fn (clauses msg env i)
+    (cond
+      (>= i (len clauses)) {:matched false}
+      :else
+        (let ((c (nth clauses i)) (snap (er-env-copy env)))
+          (cond
+            (and
+              (er-match! (get c :pattern) msg env)
+              (er-eval-guards (get c :guards) env))
+              {:matched true :body (get c :body)}
+            :else
+              (do (er-env-restore! env snap)
+                  (er-vm-receive-try-clauses clauses msg env (+ i 1))))))))
+
+(define er-vm-receive-scan-loop
+  (fn (clauses mbox env i)
+    (cond
+      (>= i (len mbox)) {:matched false}
+      :else
+        (let ((msg (nth mbox i))
+              (cr (er-vm-receive-try-clauses clauses msg env 0)))
+          (cond
+            (get cr :matched) {:matched true :index i :body (get cr :body)}
+            :else (er-vm-receive-scan-loop clauses mbox env (+ i 1)))))))
+
+(define er-vm-op-receive-scan
+  (fn (operands)
+    (er-vm-receive-scan-loop (nth operands 0) (nth operands 1) (nth operands 2) 0)))
+
 ;; ── Phase 9b — pattern-match opcodes ────────────────────────────
 ;; Each handler takes a list (pattern-ast value env) and returns
 ;; true/false, mutating env on success (same contract as the
@@ -158,6 +201,7 @@
           (nth operands 2))))
     (er-vm-register-opcode! 131 "OP_PERFORM" er-vm-op-perform)
     (er-vm-register-opcode! 132 "OP_HANDLE" er-vm-op-handle)
+    (er-vm-register-opcode! 133 "OP_RECEIVE_SCAN" er-vm-op-receive-scan)
     (er-mk-atom "ok")))
 
 (er-vm-register-erlang-opcodes!)