Add one-line comments to all defines in 5 spec files

parser.sx (3), render.sx (15), harness.sx (21), signals.sx (23),
canonical.sx (12) — 74 comments total. Each define now has a ;;
comment explaining its purpose.

Combined with the evaluator.sx commit, all 215 defines across 6 spec
files are now documented. primitives.sx and special-forms.sx already
had :doc fields.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

spec/signals.sx

@@ -1,17 +1,23 @@
+;; Create raw signal dict with value, subs, deps fields
 (define
   make-signal
   (fn
     (value)
     (dict "__signal" true "value" value "subscribers" (list) "deps" (list))))
 
+;; Type predicate for signals
 (define signal? (fn (x) (and (dict? x) (has-key? x "__signal"))))
 
+;; Read current value from signal
 (define signal-value (fn (s) (get s "value")))
 
+;; Write value to signal (no notification)
 (define signal-set-value! (fn (s v) (dict-set! s "value" v)))
 
+;; List of subscriber functions
 (define signal-subscribers (fn (s) (get s "subscribers")))
 
+;; Add a subscriber function
 (define
   signal-add-sub!
   (fn
@@ -20,6 +26,7 @@
       (not (contains? (get s "subscribers") f))
       (dict-set! s "subscribers" (append (get s "subscribers") (list f))))))
 
+;; Remove a subscriber function
 (define
   signal-remove-sub!
   (fn
@@ -29,15 +36,19 @@
       "subscribers"
       (filter (fn (sub) (not (identical? sub f))) (get s "subscribers")))))
 
+;; List of upstream signal dependencies
 (define signal-deps (fn (s) (get s "deps")))
 
+;; Set upstream dependencies
 (define signal-set-deps! (fn (s deps) (dict-set! s "deps" deps)))
 
+;; Create a reactive signal (user-facing constructor)
 (define
   signal
   :effects ()
   (fn ((initial-value :as any)) (make-signal initial-value)))
 
+;; Dereference a signal, returning its current value
 (define
   deref
   :effects ()
@@ -58,6 +69,7 @@
               (signal-add-sub! s notify-fn))))
         (signal-value s)))))
 
+;; Set signal to new value and notify subscribers
 (define
   reset!
   :effects (mutation)
@@ -72,6 +84,7 @@
           (signal-set-value! s value)
           (notify-subscribers s))))))
 
+;; Apply function to current value and reset
 (define
   swap!
   :effects (mutation)
@@ -87,6 +100,7 @@
           (signal-set-value! s new-val)
           (notify-subscribers s))))))
 
+;; Create a derived signal that auto-updates from dependencies
 (define
   computed
   :effects (mutation)
@@ -100,6 +114,7 @@
         (register-in-scope (fn () (dispose-computed s)))
         s))))
 
+;; Create a side-effect that runs when dependencies change
 (define
   effect
   :effects (mutation)
@@ -115,10 +130,13 @@
           (register-in-scope dispose-fn)
           dispose-fn)))))
 
+;; Nesting counter for batched updates
 (define *batch-depth* 0)
 
+;; Queued notifications during batch
 (define *batch-queue* (list))
 
+;; Batch multiple signal updates, notify once at end
 (define
   batch
   :effects (mutation)
@@ -148,6 +166,7 @@
             queue)
           (for-each (fn ((sub :as lambda)) (sub)) pending))))))
 
+;; Notify all subscribers of a signal change
 (define
   notify-subscribers
   :effects (mutation)
@@ -158,6 +177,7 @@
       (when (not (contains? *batch-queue* s)) (append! *batch-queue* s))
       (flush-subscribers s))))
 
+;; Process queued subscriber notifications
 (define
   flush-subscribers
   :effects (mutation)
@@ -165,6 +185,7 @@
     ((s :as dict))
     (for-each (fn (sub) (cek-call sub nil)) (signal-subscribers s))))
 
+;; Tear down a computed signal, remove from deps
 (define
   dispose-computed
   :effects (mutation)
@@ -177,6 +198,7 @@
         (signal-deps s))
       (signal-set-deps! s (list)))))
 
+;; Evaluate body in an island disposal scope
 (define
   with-island-scope
   :effects (mutation)
@@ -185,6 +207,7 @@
     (scope-push! "sx-island-scope" scope-fn)
     (let ((result (body-fn))) (scope-pop! "sx-island-scope") result)))
 
+;; Register a disposable in the current island scope
 (define
   register-in-scope
   :effects (mutation)