about summary refs log tree commit diff stats
path: root/apps
diff options
context:
space:
mode:
authorKartik Agaram <vc@akkartik.com>2019-12-08 13:56:46 -0800
committerKartik Agaram <vc@akkartik.com>2019-12-08 23:31:05 -0800
commit2a2a5b1e43b6aa650a41ab1ec68d9778c14cb649 (patch)
tree734619639755cf5b95490bdc4362bbef0a504881 /apps
parenta93cd189c95fc82a8f1db4e42e5f278bc642bb0c (diff)
downloadmu-2a2a5b1e43b6aa650a41ab1ec68d9778c14cb649.tar.gz
5804
Try to make the comments consistent with the type system we'll eventually
have.
Diffstat (limited to 'apps')
-rwxr-xr-xapps/assortbin42810 -> 42800 bytes
-rw-r--r--apps/assort.subx44
-rwxr-xr-xapps/bracesbin42826 -> 42816 bytes
-rw-r--r--apps/braces.subx20
-rwxr-xr-xapps/callsbin47536 -> 47526 bytes
-rw-r--r--apps/calls.subx56
-rwxr-xr-xapps/crenshaw2-1bin42218 -> 42208 bytes
-rw-r--r--apps/crenshaw2-1.subx32
-rwxr-xr-xapps/crenshaw2-1bbin42765 -> 42755 bytes
-rw-r--r--apps/crenshaw2-1b.subx30
-rwxr-xr-xapps/dquotesbin46460 -> 46450 bytes
-rw-r--r--apps/dquotes.subx74
-rwxr-xr-xapps/factorialbin41237 -> 41227 bytes
-rw-r--r--apps/factorial.subx8
-rwxr-xr-xapps/handlebin42135 -> 42125 bytes
-rw-r--r--apps/handle.subx22
-rwxr-xr-xapps/hexbin45057 -> 45047 bytes
-rw-r--r--apps/hex.subx28
-rwxr-xr-xapps/mubin63193 -> 63183 bytes
-rw-r--r--apps/mu.subx451
-rw-r--r--apps/mulisp.subx18
-rwxr-xr-xapps/packbin55202 -> 55192 bytes
-rw-r--r--apps/pack.subx260
-rwxr-xr-xapps/sigilsbin55211 -> 55201 bytes
-rw-r--r--apps/sigils.subx47
-rwxr-xr-xapps/surveybin52051 -> 52041 bytes
-rw-r--r--apps/survey.subx142
-rwxr-xr-xapps/testsbin41608 -> 41598 bytes
-rw-r--r--apps/tests.subx18
29 files changed, 631 insertions, 619 deletions
diff --git a/apps/assort b/apps/assort
index 05e615a7..b8cba438 100755
--- a/apps/assort
+++ b/apps/assort
Binary files differdiff --git a/apps/assort.subx b/apps/assort.subx
index 123ad64e..0aa18555 100644
--- a/apps/assort.subx
+++ b/apps/assort.subx
@@ -50,8 +50,8 @@ Entry:  # run tests if necessary, convert stdin if not
     e8/call  kernel-string-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto interactive
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto interactive
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $subx-assort-main:interactive/disp8
     # run-tests()
     e8/call  run-tests/disp32
@@ -60,7 +60,7 @@ Entry:  # run tests if necessary, convert stdin if not
     eb/jump  $subx-assort-main:end/disp8
 $subx-assort-main:interactive:
     # - otherwise convert stdin
-    # var ed/eax : exit-descriptor
+    # var ed/eax : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
     # configure ed to really exit()
@@ -97,7 +97,7 @@ subx-assort:  # in : (address buffered-file), out : (address buffered-file)
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
     # . save registers
     51/push-ecx
-    # var table/ecx : (address stream byte 10*8)
+    # var table/ecx : (ref stream {string, (address stream byte)} 80)  # 10 rows * 8 bytes/row
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0x50/imm32        # subtract from esp
     68/push  0x50/imm32/length
     68/push  0/imm32/read
@@ -450,8 +450,10 @@ test-subx-assort:
     5d/pop-to-ebp
     c3/return
 
+# type string_key = (address array byte)
+
 # beware: leaks memory (one name per segment read)
-read-segments:  # in : (address buffered-file), table : (address stream {string, (address stream byte)})
+read-segments:  # in : (address buffered-file), table : (address stream {string_key, (handle stream byte)})
     # pseudocode:
     #   var curr-segment : (handle stream byte) = 0
     #   var line : (stream byte 512)
@@ -494,13 +496,13 @@ read-segments:  # in : (address buffered-file), table : (address stream {string,
     52/push-edx
     53/push-ebx
     56/push-esi
-    # var line/ecx : (stream byte 512)
+    # var line/ecx : (ref stream byte 512)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0x200/imm32       # subtract from esp
     68/push  0x200/imm32/length
     68/push  0/imm32/read
     68/push  0/imm32/write
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # var word-slice/edx = {0, 0}
+    # var word-slice/edx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    2/rm32/edx    .           .             .           4/r32/esp   .               .                 # copy esp to edx
@@ -583,8 +585,8 @@ $read-segments:check1:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) continue
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) continue
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $read-segments:loop/disp32
 $read-segments:check-for-comment:
 #?     # print("check for comment\n") {{{
@@ -597,12 +599,12 @@ $read-segments:check-for-comment:
 #?     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
 #?     # }}}
     # if (slice-starts-with?(word-slice, "#")) continue
-    # . start/esi = word-slice->start
+    # . var start/esi : (address byte) = word-slice->start
     8b/copy                         0/mod/indirect  2/rm32/edx    .           .             .           6/r32/esi   .               .                 # copy *ecx to esi
-    # . c/eax = *start
+    # . var c/eax : byte = *start
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
     8a/copy-byte                    0/mod/indirect  6/rm32/esi    .           .             .           0/r32/AL    .               .                 # copy byte at *esi to AL
-    # . if (eax == '#') continue
+    # . if (c == '#') continue
     3d/compare-eax-and  0x23/imm32/hash
     0f 84/jump-if-equal  $read-segments:loop/disp32
 $read-segments:check-for-segment-header:
@@ -664,8 +666,8 @@ $read-segments:check-for-segment-header:
     e8/call  slice-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto check3
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto check3
+    3d/compare-eax-and  0/imm32/false
     0f 84/jump-if-equal  $read-segments:regular-line/disp32
     # segment-name = next-word-or-string(line)
     # . . push args
@@ -715,7 +717,7 @@ $read-segments:check-for-segment-header:
 #?     # . . discard args
 #?     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
 #?     # }}}
-    # segment-slot/eax = leaky-get-or-insert-slice(table, segment-name, row-size=8)
+    # var segment-slot/eax : (address handle stream byte) = leaky-get-or-insert-slice(table, segment-name, row-size=8)
     # . . push args
     68/push  8/imm32/row-size
     52/push-edx
@@ -841,10 +843,10 @@ $read-segments:end:
     5d/pop-to-ebp
     c3/return
 
-write-segments:  # out : (address buffered-file), table : (address stream {string, (address stream byte)})
+write-segments:  # out : (address buffered-file), table : (address stream {string_key, (handle stream byte)})
     # pseudocode:
     #   var curr = table->data
-    #   var max = table->data + table->write
+    #   var max = &table->data[table->write]
     #   while curr < max
     #     stream = table[i].stream
     #     write-stream-data(out, stream)
@@ -860,17 +862,17 @@ write-segments:  # out : (address buffered-file), table : (address stream {strin
     56/push-esi
     # esi = table
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           6/r32/esi   0xc/disp8       .                 # copy *(ebp+12) to esi
-    # write/edx = table->write
+    # var write/edx : int = table->write
     8b/copy                         0/mod/indirect  6/rm32/esi    .           .             .           2/r32/edx   .               .                 # copy *esi to edx
-    # curr/esi = table->data
+    # var curr/esi : (address byte) = table->data
     81          0/subop/add         3/mod/direct    6/rm32/esi    .           .             .           .           .               0xc/imm32         # add to eax
-    # max/edx = curr + write
+    # var max/edx : (address byte) = curr + write
     01/add                          3/mod/direct    2/rm32/edx    .           .             .           6/r32/esi   .               .                 # add esi to edx
 $write-segments:loop:
     # if (curr >= max) break
     39/compare                      3/mod/direct    6/rm32/esi    .           .             .           2/r32/edx   .               .                 # compare esi with edx
     73/jump-if-greater-or-equal-unsigned  $write-segments:break/disp8
-    # stream/eax = table[i].stream
+    # var stream/eax : (address stream byte) = table[i].stream
     8b/copy                         1/mod/*+disp8   6/rm32/esi    .           .             .           0/r32/eax   4/disp8         .                 # copy *(esi+4) to eax
     # write-stream-data(out, stream)
     # . . push args
diff --git a/apps/braces b/apps/braces
index 7307be11..ef7eb54a 100755
--- a/apps/braces
+++ b/apps/braces
Binary files differdiff --git a/apps/braces.subx b/apps/braces.subx
index 27810a86..95b6a7ea 100644
--- a/apps/braces.subx
+++ b/apps/braces.subx
@@ -77,8 +77,8 @@ $subx-braces-main:end:
 
 subx-braces:  # in : (address buffered-file), out : (address buffered-file)
     # pseudocode:
-    #   var line : (stream byte 512)
-    #   var label-stack : (stack address 32)  # at most 32 levels of nesting
+    #   var line : (ref stream byte 512)
+    #   var label-stack : (stack int 32)  # at most 32 levels of nesting
     #   var next-label-id : int = 1
     #   while true
     #     clear-stream(line)
@@ -123,20 +123,20 @@ subx-braces:  # in : (address buffered-file), out : (address buffered-file)
     57/push-edi
     # esi = in
     8b/-> *(ebp+8) 6/r32/esi
-    # var line/ecx : (stream byte 512)
+    # var line/ecx : (ref stream byte 512)
     81 5/subop/subtract %esp 0x200/imm32
     68/push 0x200/imm32/length
     68/push 0/imm32/read
     68/push 0/imm32/write
     89/<- %ecx 4/r32/esp
-    # var label-stack/edx : (stack int 32)
+    # var label-stack/edx : (ref stack int 32)
     81 5/subop/subtract %esp 0x80/imm32
     68/push 0x80/imm32/length
     68/push 0/imm32/top
     89/<- %edx 4/r32/esp
-    # next-label-id/ebx = 1
+    # var next-label-id/ebx : int = 1
     c7 0/subop/copy %ebx 1/imm32
-    # var word-slice/edi = {0, 0}
+    # var word-slice/edi : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %edi 4/r32/esp
@@ -201,8 +201,8 @@ $subx-braces:check-for-break:
     # if (!slice-starts-with?(word-slice, "break/")) goto next check
     # . eax = slice-starts-with?(word-slice, "break/")
     (slice-starts-with? %edi "break/")
-    # . if (eax == 0) goto next check
-    3d/compare-eax-and 0/imm32
+    # . if (eax == false) goto next check
+    3d/compare-eax-and 0/imm32/false
     74/jump-if-equal $subx-braces:check-for-loop/disp8
 $subx-braces:emit-break:
     (top %edx)
@@ -217,8 +217,8 @@ $subx-braces:check-for-loop:
     # if (!slice-starts-with?(word-slice, "loop/")) emit word
     # . eax = slice-starts-with?(word-slice, "loop/")
     (slice-starts-with? %edi "loop/")
-    # . if (eax == 0) goto next check
-    3d/compare-eax-and 0/imm32
+    # . if (eax == false) goto next check
+    3d/compare-eax-and 0/imm32/false
     74/jump-if-equal $subx-braces:emit-word-slice/disp8
 $subx-braces:emit-loop:
     (top %edx)
diff --git a/apps/calls b/apps/calls
index 418d230e..15bbc5db 100755
--- a/apps/calls
+++ b/apps/calls
Binary files differdiff --git a/apps/calls.subx b/apps/calls.subx
index 28e2ff63..030509ed 100644
--- a/apps/calls.subx
+++ b/apps/calls.subx
@@ -51,8 +51,8 @@ Entry:  # run tests if necessary, convert stdin if not
     e8/call kernel-string-equal?/disp32
     # . . discard args
     81 0/subop/add %esp 8/imm32
-    # . if (eax == 0) goto run-main
-    3d/compare-eax-and 0/imm32
+    # . if (eax == false) goto run-main
+    3d/compare-eax-and 0/imm32/false
     74/jump-if-equal $subx-calls-main:interactive/disp8
     # run-tests()
     e8/call run-tests/disp32
@@ -77,8 +77,8 @@ $subx-calls-main:end:
 
 subx-calls:  # in : (address buffered-file), out : (address buffered-file)
     # pseudocode:
-    #   var line : (stream byte 512)
-    #   var words : (stream slice 16)  # at most function name and 15 args
+    #   var line : (ref stream byte 512)
+    #   var words : (ref stream slice 16)  # at most function name and 15 args
     #   while true
     #     clear-stream(line)
     #     read-line-buffered(in, line)
@@ -105,13 +105,13 @@ subx-calls:  # in : (address buffered-file), out : (address buffered-file)
     51/push-ecx
     52/push-edx
     56/push-esi
-    # var line/esi : (address stream byte) = stream(512)
+    # var line/esi : (ref stream byte 512)
     81 5/subop/subtract %esp 0x200/imm32
     68/push 0x200/imm32/length
     68/push 0/imm32/read
     68/push 0/imm32/write
     89/<- %esi 4/r32/esp
-    # var words/edx : (address stream slice) = stream(16, 8)
+    # var words/edx : (ref stream slice 128)  # 16 rows * 8 bytes/row
     81 5/subop/subtract %esp 0x80/imm32
     68/push 0x80/imm32/length
     68/push 0/imm32/read
@@ -233,7 +233,7 @@ $subx-calls:end:
 
 parse-line:  # line : (address stream byte), words : (address stream slice)
     # pseudocode:
-    #   var word-slice : (address slice)
+    #   var word-slice : (ref slice)
     #   while true
     #     word-slice = next-word-string-or-expression-without-metadata(line)
     #     if slice-empty?(word-slice)
@@ -246,7 +246,7 @@ parse-line:  # line : (address stream byte), words : (address stream slice)
     89/<- %ebp 4/r32/esp
     # . save registers
     51/push-ecx
-    # var word-slice/ecx : (address slice) = {0, 0}
+    # var word-slice/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -268,8 +268,8 @@ $parse-line:check1:
     e8/call slice-empty?/disp32
     # . . discard args
     81 0/subop/add %esp 4/imm32
-    # . if (eax != 0) break
-    3d/compare-eax-and 0/imm32
+    # . if (eax != false) break
+    3d/compare-eax-and 0/imm32/false
     0f 85/jump-if-not-equal $parse-line:end/disp32
 #?     # dump word-slice {{{
 #?     # . write(2/stderr, "w: ")
@@ -381,9 +381,9 @@ emit-call:  # out : (address buffered-file), words : (address stream slice)
     8b/-> *esi 1/r32/ecx
     81 5/subop/subtract %ecx 8/imm32
     0f 8c/jump-if-lesser $emit-call:error1/disp32
-    # curr/ecx = &words->data[words->write-8]
+    # var curr/ecx : (address slice) = &words->data[words->write-8]
     8d/copy-address *(esi+ecx+0xc) 1/r32/ecx
-    # min/edx = words->data
+    # var min/edx : (address byte) = words->data
     8d/copy-address *(esi+0xc) 2/r32/edx
     # - emit pushes
 $emit-call:push-loop:
@@ -391,15 +391,15 @@ $emit-call:push-loop:
     39/compare %ecx 2/r32/edx
     0f 8e/jump-if-lesser-or-equal $emit-call:call-instruction/disp32
     # if (*curr->start in '%' '*') goto push-rm32
-    # . eax = curr->start
+    # . var start/eax : (address byte) = curr->start
     8b/-> *ecx 0/r32/eax
-    # . eax = (byte)*eax
+    # . var c/eax : byte = *eax
     8b/-> *eax 0/r32/eax
     81 4/subop/and %eax 0xff/imm32
-    # . if (eax == '%') goto push-rm32
+    # . if (c == '%') goto push-rm32
     3d/compare-eax-and 0x25/imm32/percent
     74/jump-if-equal $emit-call:push-rm32/disp8
-    # . if (eax == '*') goto push-rm32
+    # . if (c == '*') goto push-rm32
     3d/compare-eax-and 0x2a/imm32/asterisk
     74/jump-if-equal $emit-call:push-rm32/disp8
 $emit-call:push-imm32:
@@ -741,7 +741,7 @@ test-subx-calls-processes-calls:
     5d/pop-to-ebp
     c3/return
 
-next-word-string-or-expression-without-metadata:  # line : (address stream), out : (address slice)
+next-word-string-or-expression-without-metadata:  # line : (address stream byte), out : (address slice)
     # pseudocode:
     #   skip-chars-matching(line, ' ')
     #   if line->read >= line->write              # end of line
@@ -830,7 +830,7 @@ $next-word-string-or-expression-without-metadata:check-for-comment:
     8d/copy-address *(esi+ecx+0xc) 0/r32/eax
     89/<- *edi 0/r32/eax
     # if (line->data[line->read] != '#') goto next check
-    # . eax = line->data[line->read]
+    # . var eax : byte = line->data[line->read]
     31/xor %eax 0/r32/eax
     8a/copy-byte *(esi+ecx+0xc) 0/r32/AL
     # . if (eax != '#') goto next check
@@ -1191,7 +1191,7 @@ test-next-word-string-or-expression-without-metadata:
     e8/call clear-stream/disp32
     # . . discard args
     81 0/subop/add %esp 4/imm32
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -1264,7 +1264,7 @@ test-next-word-string-or-expression-without-metadata-returns-whole-comment:
     e8/call clear-stream/disp32
     # . . discard args
     81 0/subop/add %esp 4/imm32
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -1337,7 +1337,7 @@ test-next-word-string-or-expression-without-metadata-returns-empty-slice-on-eof:
     e8/call clear-stream/disp32
     # . . discard args
     81 0/subop/add %esp 4/imm32
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -1379,7 +1379,7 @@ test-next-word-string-or-expression-without-metadata-returns-string-literal:
     e8/call clear-stream/disp32
     # . . discard args
     81 0/subop/add %esp 4/imm32
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -1442,7 +1442,7 @@ test-next-word-string-or-expression-without-metadata-returns-string-with-escapes
     e8/call clear-stream/disp32
     # . . discard args
     81 0/subop/add %esp 4/imm32
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -1505,7 +1505,7 @@ test-next-word-string-or-expression-without-metadata-returns-whole-expression:
     e8/call clear-stream/disp32
     # . . discard args
     81 0/subop/add %esp 4/imm32
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -1568,7 +1568,7 @@ test-next-word-string-or-expression-without-metadata-returns-eol-on-trailing-clo
     e8/call clear-stream/disp32
     # . . discard args
     81 0/subop/add %esp 4/imm32
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -1623,7 +1623,7 @@ test-next-word-string-or-expression-without-metadata-handles-comment-after-trail
     e8/call clear-stream/disp32
     # . . discard args
     81 0/subop/add %esp 4/imm32
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -1678,7 +1678,7 @@ test-next-word-string-or-expression-without-metadata-handles-newline-after-trail
     e8/call clear-stream/disp32
     # . . discard args
     81 0/subop/add %esp 4/imm32
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -1733,7 +1733,7 @@ test-next-word-string-or-expression-without-metadata-stops-at-close-paren:
     e8/call clear-stream/disp32
     # . . discard args
     81 0/subop/add %esp 4/imm32
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
diff --git a/apps/crenshaw2-1 b/apps/crenshaw2-1
index 7103908f..a579ee45 100755
--- a/apps/crenshaw2-1
+++ b/apps/crenshaw2-1
Binary files differdiff --git a/apps/crenshaw2-1.subx b/apps/crenshaw2-1.subx
index 2217e430..228f4696 100644
--- a/apps/crenshaw2-1.subx
+++ b/apps/crenshaw2-1.subx
@@ -57,8 +57,8 @@ Entry:  # run tests if necessary, call 'compile' if not
     e8/call  kernel-string-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto run-main
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto run-main
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $run-main/disp8
     # run-tests()
     e8/call  run-tests/disp32
@@ -67,7 +67,7 @@ Entry:  # run tests if necessary, call 'compile' if not
     eb/jump  $main:end/disp8
 $run-main:
     # - otherwise read a program from stdin and emit its translation to stdout
-    # var ed/eax : exit-descriptor
+    # var ed/eax : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
     # configure ed to really exit()
@@ -90,7 +90,7 @@ $main:end:
     cd/syscall  0x80/imm8
 
 # the main entry point
-compile:  # in : (address buffered-file), out : fd or (address stream), err : fd or (address stream), ed : (address exit-descriptor)
+compile:  # in : (address buffered-file), out : fd or (address stream byte), err : fd or (address stream byte), ed : (address exit-descriptor)
     # . prologue
     55/push-ebp
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
@@ -105,7 +105,7 @@ compile:  # in : (address buffered-file), out : fd or (address stream), err : fd
     e8/call  get-char/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # var num/ecx : (address stream) on the stack
+    # var num/ecx : (ref stream byte 7)
     # Numbers can be 32 bits or 8 hex bytes long. One of them will be in 'Look', so we need space for 7 bytes.
     # Sizing the stream just right buys us overflow-handling for free inside 'get-num'.
     # Add 12 bytes for 'read', 'write' and 'length' fields, for a total of 19 bytes, or 0x13 in hex.
@@ -187,10 +187,11 @@ $compile:end:
     5d/pop-to-ebp
     c3/return
 
-# Read a single digit into 'out'. Abort if there are none, or if there is no space in 'out'.
-# Input comes from the global variable 'Look', and we leave the next byte from
-# 'in' into it on exit.
-get-num:  # in : (address buffered-file), out : (address stream), err : fd or (address stream), ed : (address exit-descriptor)
+# Read a single digit into 'out'. Abort if there are none, or if there is no
+# space in 'out'.
+# Input comes from the global variable 'Look' (first byte) and the argument
+# 'in' (rest). We leave the next byte from 'in' into 'Look' on exit.
+get-num:  # in : (address buffered-file), out : (address stream byte), err : fd or (address stream byte), ed : (address exit-descriptor)
     # pseudocode:
     #   if (!is-digit?(Look)) expected(ed, err, "integer")
     #   if out->write >= out->length
@@ -221,8 +222,8 @@ get-num:  # in : (address buffered-file), out : (address stream), err : fd or (a
     e8/call  is-digit?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax == 0)
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false)
+    3d/compare-eax-and  0/imm32/false
     75/jump-if-not-equal  $get-num:main/disp8
     # . expected(ed, err, "integer")
     # . . push args
@@ -251,6 +252,7 @@ $get-num:main:
     8b/copy                         0/mod/indirect  7/rm32/edi    .           .             .           1/r32/ecx   .               .                 # copy *edi to ecx
     # edx = out->length
     8b/copy                         1/mod/*+disp8   7/rm32/edi    .           .             .           2/r32/edx   8/disp8         .                 # copy *(edi+8) to edx
+$get-num:loop:
     # if (out->write >= out->length) error
     39/compare                      3/mod/direct    2/rm32/edx    .           .             .           1/r32/ecx   .               .                 # compare edx with ecx
     7d/jump-if-lesser  $get-num:stage2/disp8
@@ -337,7 +339,7 @@ test-get-num-reads-single-digit:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'get-num' below
-    # . var ed/eax : exit-descriptor
+    # . var ed/eax : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
     # . tailor-exit-descriptor(ed, 16)
@@ -426,7 +428,7 @@ test-get-num-aborts-on-non-digit-in-Look:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'get-num' below
-    # . var ed/eax : (address exit-descriptor)
+    # . var ed/eax : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
     # . tailor-exit-descriptor(ed, 16)
@@ -468,7 +470,7 @@ test-get-num-aborts-on-non-digit-in-Look:
 ## helpers
 
 # write(f, "Error: "+s+" expected\n") then stop(ed, 1)
-expected:  # ed : (address exit-descriptor), f : fd or (address stream), s : (address array byte)
+expected:  # ed : (address exit-descriptor), f : fd or (address stream byte), s : (address array byte)
     # . prologue
     55/push-ebp
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
@@ -488,7 +490,7 @@ expected:  # ed : (address exit-descriptor), f : fd or (address stream), s : (ad
     e8/call  write/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # write(f, " expected")
+    # write(f, " expected\n")
     # . . push args
     68/push  " expected\n"/imm32
     ff          6/subop/push        1/mod/*+disp8   5/rm32/ebp    .           .             .           .           0xc/disp8       .                 # push *(ebp+12)
diff --git a/apps/crenshaw2-1b b/apps/crenshaw2-1b
index 31b9cac1..a398a0bc 100755
--- a/apps/crenshaw2-1b
+++ b/apps/crenshaw2-1b
Binary files differdiff --git a/apps/crenshaw2-1b.subx b/apps/crenshaw2-1b.subx
index 58467aa9..374625e9 100644
--- a/apps/crenshaw2-1b.subx
+++ b/apps/crenshaw2-1b.subx
@@ -57,8 +57,8 @@ Entry:  # run tests if necessary, call 'compile' if not
     e8/call  kernel-string-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto run-main
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto run-main
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $run-main/disp8
     # run-tests()
     e8/call  run-tests/disp32
@@ -67,7 +67,7 @@ Entry:  # run tests if necessary, call 'compile' if not
     eb/jump  $main:end/disp8
 $run-main:
     # - otherwise read a program from stdin and emit its translation to stdout
-    # var ed/eax : exit-descriptor
+    # var ed/eax : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
     # configure ed to really exit()
@@ -90,7 +90,7 @@ $main:end:
     cd/syscall  0x80/imm8
 
 # the main entry point
-compile:  # in : (address buffered-file), out : fd or (address stream), err : fd or (address stream), ed : (address exit-descriptor)
+compile:  # in : (address buffered-file), out : fd or (address stream byte), err : fd or (address stream byte), ed : (address exit-descriptor)
     # . prologue
     55/push-ebp
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
@@ -105,7 +105,7 @@ compile:  # in : (address buffered-file), out : fd or (address stream), err : fd
     e8/call  get-char/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # var num/ecx : (address stream) on the stack
+    # var num/ecx : (ref stream byte 7)
     # Numbers can be 32 bits or 8 hex bytes long. One of them will be in 'Look', so we need space for 7 bytes.
     # Sizing the stream just right buys us overflow-handling for free inside 'get-num'.
     # Add 12 bytes for 'read', 'write' and 'length' fields, for a total of 19 bytes, or 0x13 in hex.
@@ -191,7 +191,7 @@ $compile:end:
 # no space in 'out'.
 # Input comes from the global variable 'Look' (first byte) and the argument
 # 'in' (rest). We leave the next byte from 'in' into 'Look' on exit.
-get-num:  # in : (address buffered-file), out : (address stream), err : fd or (address stream), ed : (address exit-descriptor)
+get-num:  # in : (address buffered-file), out : (address stream byte), err : fd or (address stream byte), ed : (address exit-descriptor)
     # pseudocode:
     #   if (!is-digit?(Look)) expected(ed, err, "integer")
     #   do
@@ -227,8 +227,8 @@ get-num:  # in : (address buffered-file), out : (address stream), err : fd or (a
     e8/call  is-digit?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax == 0)
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false)
+    3d/compare-eax-and  0/imm32/false
     75/jump-if-not-equal  $get-num:main/disp8
     # . expected(ed, err, "integer")
     # . . push args
@@ -292,8 +292,8 @@ $get-num:loop-stage2:
     e8/call  is-digit?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) loop
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) loop
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $get-num:loop/disp32
 $get-num:loop-end:
     # persist necessary variables from registers
@@ -355,7 +355,7 @@ test-get-num-reads-single-digit:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'get-num' below
-    # . var ed/eax : exit-descriptor
+    # . var ed/eax : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
     # . tailor-exit-descriptor(ed, 16)
@@ -444,7 +444,7 @@ test-get-num-aborts-on-non-digit-in-Look:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'get-num' below
-    # . var ed/eax : (address exit-descriptor)
+    # . var ed/eax : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
     # . tailor-exit-descriptor(ed, 16)
@@ -527,7 +527,7 @@ test-get-num-reads-multiple-digits:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'get-num' below
-    # . var ed/eax : (address exit-descriptor)
+    # . var ed/eax : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
     # . tailor-exit-descriptor(ed, 16)
@@ -616,7 +616,7 @@ test-get-num-reads-multiple-digits-followed-by-nondigit:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'get-num' below
-    # . var ed/eax : (address exit-descriptor)
+    # . var ed/eax : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
     # . tailor-exit-descriptor(ed, 16)
@@ -664,7 +664,7 @@ test-get-num-reads-multiple-digits-followed-by-nondigit:
 ## helpers
 
 # write(f, "Error: "+s+" expected\n") then stop(ed, 1)
-expected:  # ed : (address exit-descriptor), f : fd or (address stream), s : (address array byte)
+expected:  # ed : (address exit-descriptor), f : fd or (address stream byte), s : (address array byte)
     # . prologue
     55/push-ebp
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
diff --git a/apps/dquotes b/apps/dquotes
index ec6808ec..ae526a6c 100755
--- a/apps/dquotes
+++ b/apps/dquotes
Binary files differdiff --git a/apps/dquotes.subx b/apps/dquotes.subx
index 5186eda6..4b985fbb 100644
--- a/apps/dquotes.subx
+++ b/apps/dquotes.subx
@@ -46,8 +46,8 @@ Entry:  # run tests if necessary, convert stdin if not
     e8/call  kernel-string-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto interactive
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto interactive
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $subx-dquotes-main:interactive/disp8
     # run-tests()
     e8/call  run-tests/disp32
@@ -56,7 +56,7 @@ Entry:  # run tests if necessary, convert stdin if not
     eb/jump  $subx-dquotes-main:end/disp8
 $subx-dquotes-main:interactive:
     # - otherwise convert stdin
-    # var ed/eax : exit-descriptor
+    # var ed/eax : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
     # configure ed to really exit()
@@ -84,7 +84,7 @@ $subx-dquotes-main:end:
 
 subx-dquotes:  # in : (address buffered-file), out : (address buffered-file)
     # pseudocode:
-    #   var line : (stream byte 512)
+    #   var line : (ref stream byte 512)
     #   var new-data-segment : (handle stream byte) = new-stream(Heap, Segment-size, 1)
     #
     #   write(new-data-segment, "== data\n")
@@ -125,13 +125,13 @@ subx-dquotes:  # in : (address buffered-file), out : (address buffered-file)
     53/push-ebx
     56/push-esi
     57/push-edi
-    # var line/ecx : (address stream byte) = stream(512)
+    # var line/ecx : (ref stream byte 512)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0x200/imm32       # subtract from esp
     68/push  0x200/imm32/length
     68/push  0/imm32/read
     68/push  0/imm32/write
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # var word-slice/edx = {0, 0}
+    # var word-slice/edx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    2/rm32/edx    .           .             .           4/r32/esp   .               .                 # copy esp to edx
@@ -193,17 +193,17 @@ $subx-dquotes:check1:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) break
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) break
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $subx-dquotes:next-line/disp32
 $subx-dquotes:check-for-comment:
     # if (slice-starts-with?(word-slice, "#")) continue
-    # . start/esi = word-slice->start
+    # . var start/esi : (address byte) = word-slice->start
     8b/copy                         0/mod/indirect  2/rm32/edx    .           .             .           6/r32/esi   .               .                 # copy *edx to esi
-    # . c/eax = *start
+    # . var c/eax : byte = *start
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
     8a/copy-byte                    0/mod/indirect  6/rm32/esi    .           .             .           0/r32/AL    .               .                 # copy byte at *esi to AL
-    # . if (eax == '#') continue
+    # . if (c == '#') continue
     3d/compare-eax-and  0x23/imm32/hash
     74/jump-if-equal  $subx-dquotes:word-loop/disp8
 $subx-dquotes:check-for-string-literal:
@@ -287,7 +287,7 @@ $subx-dquotes:end:
 
 # Write out 'string-literal' in a new format to 'out-segment', assign it a new
 # label, and write the new label out to 'out'.
-process-string-literal:  # string-literal : (address slice), out : (address buffered-file), out-segment : (address stream)
+process-string-literal:  # string-literal : (address slice), out : (address buffered-file), out-segment : (address stream byte)
     # pseudocode:
     #   print(out-segment, "_string#{Next-string-literal}:\n")
     #   emit-string-literal-data(out-segment, string-literal)
@@ -300,7 +300,7 @@ process-string-literal:  # string-literal : (address slice), out : (address buff
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
     # . save registers
     51/push-ecx
-    # var int32-stream/ecx = stream(10)  # number of decimal digits a 32-bit number can have
+    # var int32-stream/ecx : (ref stream byte 10)  # number of decimal digits a 32-bit number can have
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0xa/imm32         # subtract from esp
     68/push  0xa/imm32/decimal-digits-in-32bit-number
     68/push  0/imm32/read
@@ -846,7 +846,7 @@ test-subx-dquotes-processes-string-literals:
     c3/return
 
 # generate the data segment contents byte by byte for a given slice
-emit-string-literal-data:  # out : (address stream), word : (address slice)
+emit-string-literal-data:  # out : (address stream byte), word : (address slice)
     # pseudocode
     #   len = string-length-at-start-of-slice(word->start, word->end)
     #   print(out, "#{len}/imm32 ")
@@ -885,14 +885,14 @@ emit-string-literal-data:  # out : (address stream), word : (address slice)
     56/push-esi
     # esi = word
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           6/r32/esi   0xc/disp8       .                 # copy *(ebp+12) to esi
-    # idx/ebx = 0
+    # var idx/ebx : int = 0
     31/xor                          3/mod/direct    3/rm32/ebx    .           .             .           3/r32/ebx   .               .                 # clear ebx
-    # curr/edx = word->start
+    # var curr/edx : (address byte) = word->start
     8b/copy                         0/mod/indirect  6/rm32/esi    .           .             .           2/r32/edx   .               .                 # copy *esi to edx
-    # max/esi = word->end
+    # var max/esi : (address byte) = word->end
     8b/copy                         1/mod/*+disp8   6/rm32/esi    .           .             .           6/r32/esi   4/disp8         .                 # copy *(esi+4) to esi
 $emit-string-literal-data:emit-length:
-    # len/eax = string-length-at-start-of-slice(word->start, word->end)
+    # var len/eax : int = string-length-at-start-of-slice(word->start, word->end)
     # . . push args
     56/push-esi
     52/push-edx
@@ -920,7 +920,7 @@ $emit-string-literal-data:emit-length:
 $emit-string-literal-data:loop-init:
     # ++curr  # skip initial '"'
     42/increment-edx
-    # c/ecx = 0
+    # var c/ecx : byte = 0
     31/xor                          3/mod/direct    1/rm32/ecx    .           .             .           1/r32/ecx   .               .                 # clear ecx
 $emit-string-literal-data:loop:
     # if (curr >= max) break
@@ -955,15 +955,15 @@ $emit-string-literal-data:emit:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # if (is-alphanumeric?(*curr)) print(out, "/#{*curr}")
-    # . eax = is-alphanumeric?(CL)
+    # . var eax : boolean = is-alphanumeric?(CL)
     # . . push args
     51/push-ecx
     # . . call
     e8/call  is-alphanumeric?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax == 0) goto char-done
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto char-done
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $emit-string-literal-data:char-done/disp8
     # . write(out, "/")
     # . . push args
@@ -1027,22 +1027,22 @@ is-alphanumeric?:  # c : int -> eax : boolean
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
     # eax = c
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           0/r32/eax   8/disp8         .                 # copy *(ebp+8) to eax
-    # if (eax < '0') return false
+    # if (c < '0') return false
     3d/compare-eax-with  0x30/imm32/0
     7c/jump-if-lesser  $is-alphanumeric?:false/disp8
-    # if (eax <= '9') return true
+    # if (c <= '9') return true
     3d/compare-eax-with  0x39/imm32/9
     7e/jump-if-lesser-or-equal  $is-alphanumeric?:true/disp8
-    # if (eax < 'A') return false
+    # if (c < 'A') return false
     3d/compare-eax-with  0x41/imm32/A
     7c/jump-if-lesser  $is-alphanumeric?:false/disp8
-    # if (eax <= 'Z') return true
+    # if (c <= 'Z') return true
     3d/compare-eax-with  0x5a/imm32/Z
     7e/jump-if-lesser-or-equal  $is-alphanumeric?:true/disp8
-    # if (eax < 'a') return false
+    # if (c < 'a') return false
     3d/compare-eax-with  0x61/imm32/a
     7c/jump-if-lesser  $is-alphanumeric?:false/disp8
-    # if (eax <= 'z') return true
+    # if (c <= 'z') return true
     3d/compare-eax-with  0x7a/imm32/z
     7e/jump-if-lesser-or-equal  $is-alphanumeric?:true/disp8
     # return false
@@ -1381,7 +1381,7 @@ test-emit-string-literal-data-handles-newline-escape:
 # emit everything from a word except the initial datum
 emit-metadata:  # out : (address buffered-file), word : (address slice)
     # pseudocode
-    #   var slice = {0, word->end}
+    #   var slice : (ref slice) = {0, word->end}
     #   curr = word->start
     #   if *curr == '"'
     #     curr = skip-string-in-slice(curr, word->end)
@@ -1406,11 +1406,11 @@ emit-metadata:  # out : (address buffered-file), word : (address slice)
     56/push-esi
     # esi = word
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           6/r32/esi   0xc/disp8       .                 # copy *(ebp+12) to esi
-    # curr/ecx = word->start
+    # var curr/ecx : (address byte) = word->start
     8b/copy                         0/mod/indirect  6/rm32/esi    .           .             .           1/r32/ecx   .               .                 # copy *esi to ecx
-    # end/edx = word->end
+    # var end/edx : (address byte) = word->end
     8b/copy                         1/mod/*+disp8   6/rm32/esi    .           .             .           2/r32/edx   4/disp8         .                 # copy *(esi+4) to edx
-    # var slice/ebx = {0, end}
+    # var slice/ebx : (ref slice) = {0, end}
     52/push-edx
     68/push  0/imm32
     89/copy                         3/mod/direct    3/rm32/ebx    .           .             .           4/r32/esp   .               .                 # copy esp to ebx
@@ -1790,9 +1790,9 @@ string-length-at-start-of-slice:  # curr : (address byte), end : (address byte)
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .                         1/r32/ecx   8/disp8         .                 # copy *(ebp+8) to ecx
     # edx = end
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .                         2/r32/edx   0xc/disp8         .               # copy *(ebp+12) to edx
-    # length/eax = 0
+    # var length/eax : int = 0
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
-    # ebx = 0
+    # var c/ebx : byte = 0
     31/xor                          3/mod/direct    3/rm32/ebx    .           .             .           3/r32/ebx   .               .                 # clear ebx
     # skip initial dquote
     41/increment-ecx
@@ -1800,14 +1800,14 @@ $string-length-at-start-of-slice:loop:
     # if (curr >= end) return length
     39/compare                      3/mod/direct    1/rm32/ecx    .           .             .           2/r32/edx   .               .                 # compare ecx with edx
     73/jump-if-greater-unsigned-or-equal  $string-length-at-start-of-slice:end/disp8
-    # BL = *curr
+    # c = *curr
     8a/copy-byte                    0/mod/indirect  1/rm32/ecx    .           .             .           3/r32/BL    .               .                 # copy byte at *ecx to BL
 $string-length-at-start-of-slice:dquote:
-    # if (ebx == '"') break
+    # if (c == '"') break
     81          7/subop/compare     3/mod/direct    3/rm32/ebx    .           .             .           .           .               0x22/imm32/dquote # compare ebx
     74/jump-if-equal  $string-length-at-start-of-slice:end/disp8
 $string-length-at-start-of-slice:check-for-escape:
-    # if (ebx == '\') escape next char
+    # if (c == '\') escape next char
     81          7/subop/compare     3/mod/direct    3/rm32/ebx    .           .             .           .           .               0x5c/imm32/backslash # compare ebx
     75/jump-if-not-equal  $string-length-at-start-of-slice:continue/disp8
 $string-length-at-start-of-slice:escape:
diff --git a/apps/factorial b/apps/factorial
index d3cee9da..dd981d0d 100755
--- a/apps/factorial
+++ b/apps/factorial
Binary files differdiff --git a/apps/factorial.subx b/apps/factorial.subx
index 26cf3f9d..019329e3 100644
--- a/apps/factorial.subx
+++ b/apps/factorial.subx
@@ -45,8 +45,8 @@ Entry:  # run tests if necessary, compute `factorial(5)` if not
     e8/call  kernel-string-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto run-main
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto run-main
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $run-main/disp8
     # run-tests()
     e8/call  run-tests/disp32
@@ -77,10 +77,10 @@ factorial:  # n : int -> int/eax
     b8/copy-to-eax  1/imm32
     81          7/subop/compare     1/mod/*+disp8   5/rm32/ebp    .           .             .           .           8/disp8         1/imm32           # compare *(ebp+8)
     7e/jump-if-<=  $factorial:end/disp8
-    # ebx = n-1
+    # var ebx : int = n-1
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .                         3/r32/ebx   8/disp8         .                 # copy *(ebp+8) to ebx
     4b/decrement-ebx
-    # eax = factorial(n-1)
+    # var eax : int = factorial(n-1)
     # . . push args
     53/push-ebx
     # . . call
diff --git a/apps/handle b/apps/handle
index fdc96dcf..23993ca6 100755
--- a/apps/handle
+++ b/apps/handle
Binary files differdiff --git a/apps/handle.subx b/apps/handle.subx
index 7c4657ec..07611596 100644
--- a/apps/handle.subx
+++ b/apps/handle.subx
@@ -44,7 +44,7 @@ $handle-main:end:
     b8/copy-to-eax  1/imm32/exit
     cd/syscall  0x80/imm8
 
-new:  # ad : (address allocation-descriptor), n : int, out : (address handle)
+new:  # ad : (address allocation-descriptor), n : int, out : (handle _)
     # . prologue
     55/push-ebp
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
@@ -55,7 +55,7 @@ new:  # ad : (address allocation-descriptor), n : int, out : (address handle)
     # ecx = n+4
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           1/r32/ecx   0xc/disp8       .                 # copy *(ebp+12) to ecx
     81          0/subop/add         3/mod/direct    1/rm32/ecx    .           .             .           .           .               4/imm32           # add to ecx
-    # eax = allocate(ad, ecx)
+    # var eax : (handle _) = allocate(ad, ecx)
     # . . push args
     51/push-ecx
     ff          6/subop/push        1/mod/*+disp8   5/rm32/ebp    .           .             .           .           8/disp8         .                 # push *(ebp+8)
@@ -96,7 +96,7 @@ test-new:
     # . prologue
     55/push-ebp
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
-    # var heap/edx : (address allocation-descriptor) = {0, 0}
+    # var heap/edx : (ref allocation-descriptor)
     68/push  0/imm32/limit
     68/push  0/imm32/curr
     89/copy                         3/mod/direct    2/rm32/edx    .           .             .           4/r32/esp   .               .                 # copy esp to edx
@@ -110,7 +110,7 @@ test-new:
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # *Next-alloc-id = 0x34
     c7          0/subop/copy        0/mod/indirect  5/rm32/.disp32            .             .           .     Next-alloc-id/disp32  0x34/imm32        # copy to *Next-alloc-id
-    # var handle/ecx = {0, 0}
+    # var handle/ecx : (ref handle)
     68/push  0/imm32/address
     68/push  0/imm32/alloc-id
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -166,7 +166,7 @@ _pending-test-new-failure:
     # . *Next-alloc-id = 0x34
     c7          0/subop/copy        0/mod/indirect  5/rm32/.disp32            .             .           .           Next-alloc-id/disp32  0x34/imm32  # copy to *Next-alloc-id
     # define an allocation-descriptor with no space left
-    # . var ad/eax : (address allocation-descriptor) = {0x10, 0x10}
+    # . var ad/eax : (ref allocation-descriptor) = {0x10, 0x10}
     68/push  0x10/imm32/limit
     68/push  0x10/imm32/curr
     89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
@@ -282,7 +282,7 @@ test-lookup-success:
     55/push-ebp
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
     # . save registers
-    # var heap/ebx : (address allocation-descriptor) = {0, 0}
+    # var heap/ebx : (ref allocation-descriptor)
     68/push  0/imm32/limit
     68/push  0/imm32/curr
     89/copy                         3/mod/direct    3/rm32/ebx    .           .             .           4/r32/esp   .               .                 # copy esp to ebx
@@ -294,7 +294,7 @@ test-lookup-success:
     e8/call  new-segment/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # var handle/ecx = {0, 0}
+    # var handle/ecx : (ref handle)
     68/push  0/imm32/address
     68/push  0/imm32/alloc-id
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -350,7 +350,7 @@ test-lookup-failure:
     # . prologue
     55/push-ebp
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
-    # var heap/esi : (address allocation-descriptor) = {0, 0}
+    # var heap/esi : (ref allocation-descriptor)
     68/push  0/imm32/limit
     68/push  0/imm32/curr
     89/copy                         3/mod/direct    6/rm32/esi    .           .             .           4/r32/esp   .               .                 # copy esp to esi
@@ -362,7 +362,7 @@ test-lookup-failure:
     e8/call  new-segment/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # var h1/ecx = {0, 0}
+    # var h1/ecx : (ref handle)
     68/push  0/imm32/address
     68/push  0/imm32/alloc-id
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -381,7 +381,7 @@ test-lookup-failure:
     # reset heap->curr to mimic reclamation
     89/copy                         0/mod/indirect  6/rm32/esi    .           .             .           3/r32/ebx   .               .                 # copy ebx to *esi
     # second allocation that returns the same address as the first
-    # var h2/edx = {0, 0}
+    # var h2/edx : (ref handle)
     68/push  0/imm32/address
     68/push  0/imm32/alloc-id
     89/copy                         3/mod/direct    2/rm32/edx    .           .             .           4/r32/esp   .               .                 # copy esp to edx
@@ -422,7 +422,7 @@ test-lookup-failure:
 == data
 
 # Monotonically increasing counter for calls to 'new'
-Next-alloc-id:
+Next-alloc-id:  # int
     1/imm32
 
 # . . vim:nowrap:textwidth=0
diff --git a/apps/hex b/apps/hex
index 785d81f8..d349dea8 100755
--- a/apps/hex
+++ b/apps/hex
Binary files differdiff --git a/apps/hex.subx b/apps/hex.subx
index 80469961..09e394bd 100644
--- a/apps/hex.subx
+++ b/apps/hex.subx
@@ -44,8 +44,8 @@ Entry:  # run tests if necessary, convert stdin if not
     e8/call  kernel-string-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto interactive
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto interactive
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $subx-hex-main:interactive/disp8
     # run-tests()
     e8/call  run-tests/disp32
@@ -54,7 +54,7 @@ Entry:  # run tests if necessary, convert stdin if not
     eb/jump  $subx-hex-main:end/disp8
 $subx-hex-main:interactive:
     # - otherwise convert stdin
-    # var ed/eax : exit-descriptor
+    # var ed/eax : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
     # configure ed to really exit()
@@ -247,7 +247,7 @@ test-convert-next-octet:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'convert-next-octet' below
-    # . var ed/ecx : exit-descriptor
+    # . var ed/ecx : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
     # . tailor-exit-descriptor(ed, 12)
@@ -337,7 +337,7 @@ test-convert-next-octet-handles-Eof:
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
     # don't initialize '_test-stream'
     # initialize exit-descriptor 'ed' for the call to 'convert-next-octet' below
-    # . var ed/ecx : exit-descriptor
+    # . var ed/ecx : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
     # . tailor-exit-descriptor(ed, 12)
@@ -435,7 +435,7 @@ test-convert-next-octet-aborts-on-single-hex-byte:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'convert-next-octet' below
-    # . var ed/ecx : exit-descriptor
+    # . var ed/ecx : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
     # . tailor-exit-descriptor(ed, 12)
@@ -604,7 +604,7 @@ test-scan-next-byte:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'scan-next-byte' below
-    # . var ed/ecx : exit-descriptor
+    # . var ed/ecx : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
     # . tailor-exit-descriptor(ed, 12)
@@ -702,7 +702,7 @@ test-scan-next-byte-skips-whitespace:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'scan-next-byte' below
-    # . var ed/ecx : exit-descriptor
+    # . var ed/ecx : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
     # . tailor-exit-descriptor(ed, 12)
@@ -808,7 +808,7 @@ test-scan-next-byte-skips-comment:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'scan-next-byte' below
-    # . var ed/ecx : exit-descriptor
+    # . var ed/ecx : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
     # . tailor-exit-descriptor(ed, 12)
@@ -914,7 +914,7 @@ test-scan-next-byte-skips-comment-and-whitespace:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'scan-next-byte' below
-    # . var ed/ecx : exit-descriptor
+    # . var ed/ecx : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
     # . tailor-exit-descriptor(ed, 12)
@@ -1022,7 +1022,7 @@ test-scan-next-byte-skips-whitespace-and-comment:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'scan-next-byte' below
-    # . var ed/ecx : exit-descriptor
+    # . var ed/ecx : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
     # . tailor-exit-descriptor(ed, 12)
@@ -1120,7 +1120,7 @@ test-scan-next-byte-reads-final-byte:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'scan-next-byte' below
-    # . var ed/ecx : exit-descriptor
+    # . var ed/ecx : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
     # . tailor-exit-descriptor(ed, 12)
@@ -1210,7 +1210,7 @@ test-scan-next-byte-handles-Eof:
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
     # leave '_test-stream' empty
     # initialize exit-descriptor 'ed' for the call to 'scan-next-byte' below
-    # . var ed/ecx : exit-descriptor
+    # . var ed/ecx : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
     # . tailor-exit-descriptor(ed, 12)
@@ -1308,7 +1308,7 @@ test-scan-next-byte-aborts-on-invalid-byte:
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
     # initialize exit-descriptor 'ed' for the call to 'scan-next-byte' below
-    # . var ed/ecx : exit-descriptor
+    # . var ed/ecx : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
     # . tailor-exit-descriptor(ed, 12)
diff --git a/apps/mu b/apps/mu
index e95a43f1..0e2717c7 100755
--- a/apps/mu
+++ b/apps/mu
Binary files differdiff --git a/apps/mu.subx b/apps/mu.subx
index b0cf03c1..e4b8604b 100644
--- a/apps/mu.subx
+++ b/apps/mu.subx
@@ -7,7 +7,8 @@
 # == Goals
 # 1. Be memory safe. It should be impossible to corrupt the heap, or to create
 # a bad pointer. (Requires strong type safety.)
-# 2. Do as little as possible to achieve goal 1.
+# 2. Do as little as possible to achieve goal 1. The translator should be
+# implementable in machine code.
 #   - minimize impedance mismatch between source language and SubX target
 #     (e.g. programmer manages registers manually)
 #   - checks over syntax
@@ -63,9 +64,10 @@
 #         }
 #
 #   - variable definitions on the stack. E.g.:
-#       - var foo: int
-#       - var bar: (array int 3)
+#       - var foo: (ref int)
+#       - var bar: (ref array int 3)
 #     There's no initializer; variables are automatically initialized.
+#     The type of a local variable is either word-length (4 bytes) or starts with 'ref'.
 #
 #   - variables definitions in a register. E.g.:
 #       - var foo/eax : int <- add bar 1
@@ -81,20 +83,24 @@
 #   user-defined types: 'type' for structs, 'choice' for unions
 #   short-lived 'address' type for efficiently writing inside nested structs
 #
+# We don't have 'handle' types yet, but we try to distinguish 'ref', 'handle'
+# and 'address' in comments. Their definitions are in layer 50, but really you
+# can ignore the distinctions on a first reading of this program.
+#
 # Formal types:
 #   A program is a linked list of functions
 #   A function contains:
-#     name: string
+#     name: (handle array byte)
 #     inouts: linked list of vars  <-- 'inouts' is more precise than 'inputs'
-#       data: (address var)
-#       next: (address list)
+#       data: (handle var)
+#       next: (handle list)
 #     outputs: linked list of vars
-#       data: (address var)
-#       next: (address list)
-#     body: block
+#       data: (handle var)
+#       next: (handle list)
+#     body: (handle block)
 #   A var-type contains:
-#     name: string
-#     type: s-expression of type ids
+#     name: (handle array byte)
+#     type: (handle s-expression type-id)
 #
 #   A statement can be:
 #     tag 0: a block
@@ -105,29 +111,29 @@
 #
 #   A block contains:
 #     tag: 0
-#     statements: (address list statement)
+#     statements: (handle list statement)
 #
 #   A regular statement contains:
 #     tag: 1
-#     operation: string
-#     inouts: (address list operand)
-#     outputs: (address list var)
+#     operation: (handle array byte)
+#     inouts: (handle list operand)
+#     outputs: (handle list var)
 #
 #   A variable defined on the stack contains:
 #     tag: 2
-#     name: string
-#     type: type-tree
+#     name: (handle array byte)
+#     type: (handle s-expression type-id)
 #
 #   A variable defined in a register contains:
 #     tag: 3
-#     name: string
-#     type: type-tree
-#     reg: string
+#     name: (handle array byte)
+#     type: (handle s-expression type-id)
+#     reg: (handle array byte)
 #
 #   A named block contains:
 #     tag: 4
-#     name: string
-#     statements: (address list statement)
+#     name: (handle array byte)
+#     statements: (handle list statement)
 
 # == Translation: managing the stack
 # Now that we know what the language looks like in the large, let's think
@@ -151,11 +157,11 @@
 # Formal types:
 #   live-vars: stack of vars
 #   var:
-#     name: string
+#     name: (handle array byte)
 #     type: s-expression? Just a type id for now.
 #     block: int
 #     stack-offset: int  (added to ebp)
-#     register: string
+#     register: (handle array byte)
 #       either usual register names
 #       or '*' to indicate any register
 #   At most one of stack-offset or register-index must be non-zero.
@@ -172,11 +178,11 @@
 #
 # Formal types:
 #   functions: linked list of info
-#     name: string
+#     name: (handle array byte)
 #     inouts: linked list of vars
 #     outputs: linked list of vars
 #     body: block (singleton linked list)
-#     subx-name: string
+#     subx-name: (handle array byte)
 
 # == Translating a single primitive instruction
 # A second crucial piece of the puzzle is how Mu converts fairly regular
@@ -208,10 +214,10 @@
 #
 # Accordingly, the formal data structure for a primitive looks like this:
 #   primitives: linked list of info
-#     name: string
+#     name: (handle array byte)
 #     mu-inouts: linked list of vars to check
 #     mu-outputs: linked list of vars to check
-#     subx-name: string
+#     subx-name: (handle array byte)
 #     subx-rm32: enum arg-location
 #     subx-r32: enum arg-location
 #     subx-imm32: enum arg-location
@@ -239,31 +245,31 @@
 
 == data
 
-Program:  # (address function)
+Program:  # (handle function)
   0/imm32
 
 Function-name:
   0/imm32
 Function-subx-name:
   4/imm32
-Function-inouts:  # (address list var)
+Function-inouts:  # (handle list var)
   8/imm32
-Function-outputs:  # (address list var)
+Function-outputs:  # (handle list var)
   0xc/imm32
-Function-body:  # (address block)
+Function-body:  # (handle block)
   0x10/imm32
-Function-next:  # (address function)
+Function-next:  # (handle function)
   0x14/imm32
 Function-size:
   0x18/imm32/24
 
 Primitive-name:
   0/imm32
-Primitive-inouts:  # (address list var)
+Primitive-inouts:  # (handle list var)
   4/imm32
-Primitive-outputs:  # (address list var)
+Primitive-outputs:  # (handle list var)
   8/imm32
-Primitive-subx-name:  # (address string)
+Primitive-subx-name:  # (handle array byte)
   0xc/imm32
 Primitive-subx-rm32:  # enum arg-location
   0x10/imm32
@@ -271,7 +277,7 @@ Primitive-subx-r32:  # enum arg-location
   0x14/imm32
 Primitive-subx-imm32:  # enum arg-location
   0x18/imm32
-Primitive-next:  # (address function)
+Primitive-next:  # (handle function)
   0x1c/imm32
 Primitive-size:
   0x20/imm32/24
@@ -279,31 +285,31 @@ Primitive-size:
 Stmt-tag:
   0/imm32
 
-Block-statements:  # (address list statement)
+Block-statements:  # (handle list statement)
   4/imm32
 
-Stmt1-operation:  # string
+Stmt1-operation:  # (handle array byte)
   4/imm32
-Stmt1-inouts:  # (address list var)
+Stmt1-inouts:  # (handle list var)
   8/imm32
-Stmt1-outputs:  # (address list var)
+Stmt1-outputs:  # (handle list var)
   0xc/imm32
 
-Vardef-name:  # string
+Vardef-name:  # (handle array byte)
   4/imm32
-Vardef-type:  # (address tree type-id)
+Vardef-type:  # (handle tree type-id)
   8/imm32
 
-Regvardef-name:  # string
+Regvardef-name:  # (handle array byte)
   4/imm32
-Regvardef-type:  # (address tree type-id)
+Regvardef-type:  # (handle tree type-id)
   8/imm32
-Regvardef-register:  # string
+Regvardef-register:  # (handle array byte)
   0xc/imm32
 
 Named-block-name:
   4/imm32
-Named-block-statements:  # (address list statement)
+Named-block-statements:  # (handle list statement)
   8/imm32
 
 Stmt-size:
@@ -621,9 +627,9 @@ test-convert-function-with-arg-and-body:
 
 parse-mu:  # in : (address buffered-file)
     # pseudocode
-    #   var curr-function = Program
-    #   var line : (stream byte 512)
-    #   var word-slice : slice
+    #   var curr-function : (handle function) = Program
+    #   var line : (ref stream byte 512)
+    #   var word-slice : (ref slice)
     #   while true                                  # line loop
     #     clear-stream(line)
     #     read-line-buffered(in, line)
@@ -634,7 +640,7 @@ parse-mu:  # in : (address buffered-file)
     #     else if slice-starts-with?(word-slice, "#")  # comment
     #       continue                                # end of line
     #     else if slice-equal(word-slice, "fn")
-    #       var new-function : (address function) = new function
+    #       var new-function : (handle function) = new function
     #       populate-mu-function-header(in, new-function)
     #       populate-mu-function-body(in, new-function)
     #       *curr-function = new-function
@@ -650,17 +656,17 @@ parse-mu:  # in : (address buffered-file)
     51/push-ecx
     52/push-edx
     57/push-edi
-    # var line/ecx : (stream byte 512)
+    # var line/ecx : (ref stream byte 512)
     81 5/subop/subtract %esp 0x200/imm32
     68/push 0x200/imm32/length
     68/push 0/imm32/read
     68/push 0/imm32/write
     89/<- %ecx 4/r32/esp
-    # var word-slice/edx : slice
+    # var word-slice/edx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %edx 4/r32/esp
-    # var curr-function/edi : (address function) = Program
+    # var curr-function/edi : (handle function) = Program
     bf/copy-to-edi Program/imm32
     {
 $parse-mu:line-loop:
@@ -694,7 +700,7 @@ $parse-mu:fn:
         (slice-equal? %edx "fn")
         3d/compare-eax-and 0/imm32
         0f 84/jump-if-equal break/disp32
-        # var new-function/eax : (address function) = populate-mu-function()
+        # var new-function/eax : (handle function) = populate-mu-function()
         (allocate Heap *Function-size)  # => eax
         (populate-mu-function-header %ecx %eax)
         (populate-mu-function-body *(ebp+8) %eax)
@@ -743,9 +749,10 @@ $parse-mu:abort:
 # ✓ fn foo x : int {
 # ✓ fn foo x: int {
 # ✓ fn foo x: int -> y/eax: int {
-populate-mu-function-header:  # first-line : (address stream byte), out : (address function)
+populate-mu-function-header:  # first-line : (address stream byte), out : (handle function)
     # pseudocode:
-    #   var name : slice = next-word(first-line)
+    #   var name : (ref slice)
+    #   next-word(first-line, name)
     #   assert(name not in '{' '}' '->')
     #   out->name = slice-to-string(name)
     #   ## inouts
@@ -755,14 +762,14 @@ populate-mu-function-header:  # first-line : (address stream byte), out : (addre
     #     if (name == '{') goto done
     #     if (name == '->') break
     #     assert(name != '}')
-    #     var v : (address var) = parse-var-with-type(name, first-line)
+    #     var v : (handle var) = parse-var-with-type(name, first-line)
     #     out->inouts = append(out->inouts, v)
     #   ## outputs
     #   while true
     #     ## name
     #     name = next-word(first-line)
     #     assert(name not in '{' '}' '->')
-    #     var v : (address var) = parse-var-with-type(name, first-line)
+    #     var v : (handle var) = parse-var-with-type(name, first-line)
     #     out->outputs = append(out->outputs, v)
     #   done:
     #
@@ -775,7 +782,7 @@ populate-mu-function-header:  # first-line : (address stream byte), out : (addre
     57/push-edi
     # edi = out
     8b/-> *(ebp+0xc) 7/r32/edi
-    # var word-slice/ecx : slice
+    # var word-slice/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -875,7 +882,7 @@ test-function-header-with-arg:
     # setup
     (clear-stream _test-input-stream)
     (write _test-input-stream "foo n : int {\n")
-    # result/ecx : (address function)
+    # result/ecx : (ref function)
     2b/subtract-> *Function-size 4/r32/esp
     89/<- %ecx 4/r32/esp
     (zero-out %ecx *Function-size)
@@ -883,9 +890,9 @@ test-function-header-with-arg:
     (populate-mu-function-header _test-input-stream %ecx)
     # check result
     (check-strings-equal *ecx "foo" "F - test-function-header-with-arg/name")  # Function-name
-    # edx : (address list var) = result->inouts
+    # edx : (handle list var) = result->inouts
     8b/-> *(ecx+8) 2/r32/edx  # Function-inouts
-    # ebx : (address var) = result->inouts->value
+    # ebx : (handle var) = result->inouts->value
     8b/-> *edx 3/r32/ebx  # List-value
     (check-strings-equal *ebx "n" "F - test-function-header-with-arg/inout:0")  # Var-name
     (check-ints-equal *(ebx+4) 1 "F - test-function-header-with-arg/inout:0/type")  # Var-type
@@ -902,7 +909,7 @@ test-function-header-with-multiple-args:
     # setup
     (clear-stream _test-input-stream)
     (write _test-input-stream "foo a: int, b: int c: int {\n")
-    # result/ecx : (address function)
+    # result/ecx : (handle function)
     2b/subtract-> *Function-size 4/r32/esp
     89/<- %ecx 4/r32/esp
     (zero-out %ecx *Function-size)
@@ -910,9 +917,9 @@ test-function-header-with-multiple-args:
     (populate-mu-function-header _test-input-stream %ecx)
     # check result
     (check-strings-equal *ecx "foo")  # Function-name
-    # edx : (address list var) = result->inouts
+    # edx : (handle list var) = result->inouts
     8b/-> *(ecx+8) 2/r32/edx  # Function-inouts
-    # ebx : (address var) = result->inouts->value
+    # ebx : (handle var) = result->inouts->value
     8b/-> *edx 3/r32/ebx  # List-value
     (check-strings-equal *ebx "a" "F - test-function-header-with-multiple-args/inout:0")  # Var-name
     (check-ints-equal *(ebx+4) 1 "F - test-function-header-with-arg/inout:0/type")  # Var-type
@@ -941,7 +948,7 @@ test-function-with-multiple-args-and-outputs:
     # setup
     (clear-stream _test-input-stream)
     (write _test-input-stream "foo a: int, b: int, c: int -> x/ecx: int y/edx : int {\n")
-    # result/ecx : (address function)
+    # result/ecx : (handle function)
     2b/subtract-> *Function-size 4/r32/esp
     89/<- %ecx 4/r32/esp
     (zero-out %ecx *Function-size)
@@ -949,9 +956,9 @@ test-function-with-multiple-args-and-outputs:
     (populate-mu-function-header _test-input-stream %ecx)
     # check result
     (check-strings-equal *ecx "foo")  # Function-name
-    # edx : (address list var) = result->inouts
+    # edx : (handle list var) = result->inouts
     8b/-> *(ecx+8) 2/r32/edx  # Function-inouts
-    # ebx : (address var) = result->inouts->value
+    # ebx : (handle var) = result->inouts->value
     8b/-> *edx 3/r32/ebx  # List-value
     (check-strings-equal *ebx "a" "F - test-function-header-with-multiple-args/inout:0")  # Var-name
     (check-ints-equal *(ebx+4) 1 "F - test-function-header-with-arg/inout:0/type")  # Var-type
@@ -967,9 +974,9 @@ test-function-with-multiple-args-and-outputs:
     8b/-> *edx 3/r32/ebx  # List-value
     (check-strings-equal *ebx "c" "F - test-function-header-with-multiple-args/inout:2")  # Var-name
     (check-ints-equal *(ebx+4) 1 "F - test-function-header-with-arg/inout:2/type")  # Var-type
-    # edx : (address list var) = result->outputs
+    # edx : (handle list var) = result->outputs
     8b/-> *(ecx+0xc) 2/r32/edx  # Function-outputs
-    # ebx : (address var) = result->outputs->value
+    # ebx : (handle var) = result->outputs->value
     8b/-> *edx 3/r32/ebx  # List-value
     (check-strings-equal *ebx "x" "F - test-function-header-with-multiple-args/output:0")  # Var-name
     (check-ints-equal *(ebx+4) 1 "F - test-function-header-with-arg/output:0/type")  # Var-type
@@ -991,12 +998,12 @@ test-function-with-multiple-args-and-outputs:
 #   x: int
 #   x: int,
 # ignores at most one trailing colon or comma
-parse-var-with-type:  # name: slice, first-line: (address stream) -> result/eax: (address var)
+parse-var-with-type:  # name: (address slice), first-line: (address stream byte) -> result/eax: (handle var)
     # pseudocode:
-    #   var v : (address var) = allocate(Heap, Var-size)
-    #   var s : slice
+    #   var v : (handle var) = allocate(Heap, Var-size)
+    #   var s : (ref slice)
     #   next-token-from-slice(name->start, name->end, '/', s)
-    #   var end : address = s->end
+    #   var end : (address byte) = s->end
     #   if (slice-ends-with(s, ":"))
     #     decrement s->end
     #   if (slice-ends-with(s, ","))
@@ -1030,12 +1037,12 @@ parse-var-with-type:  # name: slice, first-line: (address stream) -> result/eax:
     53/push-ebx
     56/push-esi
     57/push-edi
-    # var result/edi : (address var) = allocate(Heap, Var-size)
+    # var result/edi : (handle var) = allocate(Heap, Var-size)
     (allocate Heap *Var-size)
     89/<- %edi 0/r32/eax
     # esi = name
     8b/-> *(ebp+8) 6/r32/esi
-    # var s/ecx : slice
+    # var s/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -1160,7 +1167,7 @@ $parse-var-with-type:abort:
     cd/syscall  0x80/imm8
     # never gets here
 
-next-mu-token:  # in: (address stream), out: (address slice)
+next-mu-token:  # in: (address stream byte), out: (address slice)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -1201,7 +1208,7 @@ $next-mu-token:end:
     5d/pop-to-ebp
     c3/return
 
-type-for:  # name: (address slice) -> result/eax: type-tree
+type-for:  # name: (address slice) -> result/eax: (handle s-expression type-id)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -1227,7 +1234,7 @@ test-parse-var-with-type:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1254,7 +1261,7 @@ test-parse-var-with-type-and-register:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1283,7 +1290,7 @@ test-parse-var-with-trailing-characters:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1314,7 +1321,7 @@ is-identifier?:  # in : (address slice) -> result/eax : boolean
     (slice-empty? *(ebp+8))  # => eax
     3d/compare-eax-and 0/imm32
     75/jump-if-not-equal $is-identifier?:false/disp8
-    # var c/eax : char = *in->start
+    # var c/eax : byte = *in->start
     8b/-> *(ebp+8) 0/r32/eax
     8b/-> *eax 0/r32/eax
     8a/copy-byte *eax 0/r32/AL
@@ -1354,7 +1361,7 @@ test-is-identifier-dollar:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1375,7 +1382,7 @@ test-is-identifier-underscore:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1396,7 +1403,7 @@ test-is-identifier-a:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1417,7 +1424,7 @@ test-is-identifier-z:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1438,7 +1445,7 @@ test-is-identifier-A:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1459,7 +1466,7 @@ test-is-identifier-Z:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1481,7 +1488,7 @@ test-is-identifier-@:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1503,7 +1510,7 @@ test-is-identifier-square-bracket:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1525,7 +1532,7 @@ test-is-identifier-backtick:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1547,7 +1554,7 @@ test-is-identifier-curly-brace-open:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1568,7 +1575,7 @@ test-is-identifier-curly-brace-close:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1590,7 +1597,7 @@ test-is-identifier-hyphen:
     8b/-> *eax 1/r32/ecx
     8d/copy-address *(eax+ecx+4) 1/r32/ecx
     05/add-to-eax 4/imm32
-    # var slice/ecx = {eax, ecx}
+    # var slice/ecx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/<- %ecx 4/r32/esp
@@ -1602,7 +1609,7 @@ test-is-identifier-hyphen:
     5d/pop-to-ebp
     c3/return
 
-populate-mu-function-body:  # in : (address buffered-file), out : (address function)
+populate-mu-function-body:  # in : (address buffered-file), out : (handle function)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -1614,7 +1621,7 @@ populate-mu-function-body:  # in : (address buffered-file), out : (address funct
     8b/-> *(ebp+8) 6/r32/esi
     # edi = out
     8b/-> *(ebp+0xc) 7/r32/edi
-    # var eax : (address block) = parse-mu-block(in)
+    # var eax : (handle block) = parse-mu-block(in)
     (parse-mu-block %esi)  # => eax
     # out->body = eax
     89/<- *(edi+0x10) 0/r32/eax  # Function-body
@@ -1629,10 +1636,10 @@ $populate-mu-function-body:end:
     c3/return
 
 # parses a block, assuming that the leading '{' has already been read by the caller
-parse-mu-block:  # in : (address buffered-file) -> result/eax : (address block)
+parse-mu-block:  # in : (address buffered-file) -> result/eax : (handle block)
     # pseudocode:
-    #   var line : (stream byte 512)
-    #   var word-slice : slice
+    #   var line : (ref stream byte 512)
+    #   var word-slice : (ref slice)
     #   result/eax = allocate(Heap, Stmt-size)
     #   result->tag = 0/Block
     #   while true                                  # line loop
@@ -1670,13 +1677,13 @@ parse-mu-block:  # in : (address buffered-file) -> result/eax : (address block)
     53/push-ebx
     56/push-esi
     57/push-edi
-    # var line/ecx : (stream byte 512)
+    # var line/ecx : (ref stream byte 512)
     81 5/subop/subtract %esp 0x200/imm32
     68/push 0x200/imm32/length
     68/push 0/imm32/read
     68/push 0/imm32/write
     89/<- %ecx 4/r32/esp
-    # var word-slice/edx : slice
+    # var word-slice/edx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %edx 4/r32/esp
@@ -1791,14 +1798,14 @@ $parse-mu-block:abort:
     cd/syscall  0x80/imm8
     # never gets here
 
-check-no-tokens-left:  # line : (address stream)
+check-no-tokens-left:  # line : (address stream byte)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
     # . save registers
     50/push-eax
     51/push-ecx
-    # var s/ecx : slice = next-word(line)
+    # var s/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -1838,10 +1845,10 @@ $check-no-tokens-left:end:
     5d/pop-to-ebp
     c3/return
 
-parse-mu-named-block:  # name : (address slice), first-line : (address stream), in : (address buffered-file) -> result/eax : (address stmt)
+parse-mu-named-block:  # name : (address slice), first-line : (address stream byte), in : (address buffered-file) -> result/eax : (handle stmt)
     # pseudocode:
-    #   var line : (stream byte 512)
-    #   var word-slice : slice
+    #   var line : (ref stream byte 512)
+    #   var word-slice : (ref slice)
     #   result/eax = allocate(Heap, Stmt-size)
     #   result->tag = 4/Named-block
     #   result->name = name
@@ -1882,7 +1889,7 @@ $parse-mu-named-block:end:
     5d/pop-to-ebp
     c3/return
 
-parse-mu-var-def:  # line : (address stream) -> result/eax : (address stmt)
+parse-mu-var-def:  # line : (address stream byte) -> result/eax : (handle stmt)
     # pseudocode:
     #
     # . prologue
@@ -1897,10 +1904,10 @@ $parse-mu-var-def:end:
     5d/pop-to-ebp
     c3/return
 
-parse-mu-stmt:  # line : (address stream) -> result/eax : (address stmt)
+parse-mu-stmt:  # line : (address stream byte) -> result/eax : (handle stmt)
     # pseudocode:
-    #   var name : slice
-    #   var v : (address var)
+    #   var name : (ref slice)
+    #   var v : (ref var)
     #   result = allocate(Heap, Stmt-size)
     #   if stmt-has-outputs?(line)
     #     while true
@@ -1921,11 +1928,11 @@ parse-mu-stmt:  # line : (address stream) -> result/eax : (address stmt)
     # . save registers
     51/push-ecx
     57/push-edi
-    # var name/ecx : (address slice)
+    # var name/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
-    # var result/edi : (address stmt)
+    # result/edi : (handle stmt)
     (allocate Heap *Stmt-size)
     89/<- %edi 0/r32/eax
     # result->tag = 1/stmt
@@ -2017,13 +2024,13 @@ $parse-mu-stmt:abort2:
     cd/syscall  0x80/imm8
     # never gets here
 
-stmt-has-outputs?:  # line : (address stream) -> result/eax : boolean
+stmt-has-outputs?:  # line : (address stream byte) -> result/eax : boolean
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
     # . save registers
     51/push-ecx
-    # var word-slice/ecx : slice
+    # var word-slice/ecx : (ref slice)
     68/push 0/imm32/end
     68/push 0/imm32/start
     89/<- %ecx 4/r32/esp
@@ -2063,7 +2070,7 @@ $stmt-has-outputs:end:
     5d/pop-to-ebp
     c3/return
 
-parse-var:  # ad: allocation-descriptor, name: (address slice) -> result/eax: (address var)
+parse-var:  # ad: allocation-descriptor, name: (address slice) -> result/eax: (handle var)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2099,9 +2106,9 @@ test-parse-mu-stmt:
     (parse-mu-stmt _test-input-stream)
     # check result
     (check-strings-equal *(eax+4) "increment" "F - test-parse-mu-stmt/name")  # Stmt1-operation
-    # edx : (address list var) = result->inouts
+    # edx : (handle list var) = result->inouts
     8b/-> *(eax+8) 2/r32/edx  # Stmt1-inouts
-    # ebx : (address var) = result->inouts->value
+    # ebx : (handle var) = result->inouts->value
     8b/-> *edx 3/r32/ebx  # List-value
     (check-strings-equal *ebx "n" "F - test-parse-mu-stmt/inout:0")  # Var-name
     # . epilogue
@@ -2109,7 +2116,7 @@ test-parse-mu-stmt:
     5d/pop-to-ebp
     c3/return
 
-new-function:  # ad: allocation-descriptor, name: string, subx-name: string, inouts: (address list var), outputs: (address list var), body: (address block), next: (address function) -> result/eax: (address function)
+new-function:  # ad: allocation-descriptor, name: string, subx-name: string, inouts: (handle list var), outputs: (handle list var), body: (handle block), next: (handle function) -> result/eax: (handle function)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2137,7 +2144,7 @@ $new-function:end:
     5d/pop-to-ebp
     c3/return
 
-new-var:  # ad: allocation-descriptor, name: string, type: int, block: int, stack-offset: int, register: string -> result/eax: (address var)
+new-var:  # ad: allocation-descriptor, name: string, type: int, block: int, stack-offset: int, register: string -> result/eax: (handle var)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2163,7 +2170,7 @@ $new-var:end:
     5d/pop-to-ebp
     c3/return
 
-new-block:  # ad: allocation-descriptor, data: (address list statement) -> result/eax: (address statement)
+new-block:  # ad: allocation-descriptor, data: (handle list statement) -> result/eax: (handle statement)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2182,7 +2189,7 @@ $new-block:end:
     5d/pop-to-ebp
     c3/return
 
-new-stmt:  # ad: allocation-descriptor, operation: string, inouts: (address list var), outputs: (address list var) -> result/eax: (address statement)
+new-stmt:  # ad: allocation-descriptor, operation: string, inouts: (handle list var), outputs: (handle list var) -> result/eax: (handle statement)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2205,7 +2212,7 @@ $new-stmt:end:
     5d/pop-to-ebp
     c3/return
 
-new-vardef:  # ad: allocation-descriptor, name: string, type: int -> result/eax: (address statement)
+new-vardef:  # ad: allocation-descriptor, name: string, type: int -> result/eax: (handle statement)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2226,7 +2233,7 @@ $new-vardef:end:
     5d/pop-to-ebp
     c3/return
 
-new-regvardef:  # ad: allocation-descriptor, name: string, type: int, register: string -> result/eax: (address statement)
+new-regvardef:  # ad: allocation-descriptor, name: string, type: int, register: string -> result/eax: (handle statement)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2249,7 +2256,7 @@ $new-regvardef:end:
     5d/pop-to-ebp
     c3/return
 
-new-named-block:  # ad: allocation-descriptor, name: string, data: (address list statement) -> result/eax: (address statement)
+new-named-block:  # ad: allocation-descriptor, name: string, data: (handle list statement) -> result/eax: (handle statement)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2270,7 +2277,7 @@ $new-named-block:end:
     5d/pop-to-ebp
     c3/return
 
-new-list:  # ad: allocation-descriptor, value: _type, next: (address list _type) -> result/eax : (address list _type)
+new-list:  # ad: allocation-descriptor, value: _type, next: (handle list _type) -> result/eax : (handle list _type)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2290,7 +2297,7 @@ $new-list:end:
     5d/pop-to-ebp
     c3/return
 
-append-list:  # ad: allocation-descriptor, value: _type, list: (address list _type) -> result/eax : (address list _type)
+append-list:  # ad: allocation-descriptor, value: _type, list: (handle list _type) -> result/eax : (handle list _type)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2326,7 +2333,7 @@ $append-list:end:
     5d/pop-to-ebp
     c3/return
 
-append-to-block:  # ad: allocation-descriptor, block: (address block), x: (address stmt)
+append-to-block:  # ad: allocation-descriptor, block: (handle block), x: (handle stmt)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2373,10 +2380,10 @@ emit-subx:  # out : (address buffered-file)
     57/push-edi
     # edi = out
     8b/-> *(ebp+8) 7/r32/edi
-    # var curr/ecx : (address function) = Program
+    # var curr/ecx : (handle function) = Program
     8b/-> *Program 1/r32/ecx
     {
-      # if (curr == NULL) break
+      # if (curr == null) break
       81 7/subop/compare %ecx 0/imm32
       0f 84/jump-if-equal break/disp32
       (emit-subx-function %edi %ecx)
@@ -2394,7 +2401,7 @@ $emit-subx:end:
     5d/pop-to-ebp
     c3/return
 
-emit-subx-function:  # out : (address buffered-file), f : (address function)
+emit-subx-function:  # out : (address buffered-file), f : (handle function)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2422,11 +2429,11 @@ $emit-subx-function:end:
     5d/pop-to-ebp
     c3/return
 
-emit-subx-block:  # out : (address buffered-file), block : (address block)
+emit-subx-block:  # out : (address buffered-file), block : (handle block)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
-    # curr/esi : (address list statement) = block->statements
+    # curr/esi : (handle list statement) = block->statements
     8b/-> *(ebp+0xc) 6/r32/esi
     8b/-> *(esi+4) 6/r32/esi  # Block-statements
     #
@@ -2451,7 +2458,7 @@ $emit-subx-block:end:
     5d/pop-to-ebp
     c3/return
 
-emit-subx-statement:  # out : (address buffered-file), stmt : (address statement), vars : (stack var), primitives : (address primitive), functions : (address function)
+emit-subx-statement:  # out : (address buffered-file), stmt : (handle statement), vars : (handle stack var), primitives : (handle primitive), functions : (handle function)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2614,7 +2621,7 @@ Lit-var:
     0/imm32/no-register
 
 == code
-emit-subx-primitive:  # out : (address buffered-file), stmt : (address statement), vars : (address variable), primitive : (address function)
+emit-subx-primitive:  # out : (address buffered-file), stmt : (handle statement), vars : (handle variable), primitive : (handle function)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2640,7 +2647,7 @@ $emit-subx-primitive:end:
     5d/pop-to-ebp
     c3/return
 
-emit-subx-rm32:  # out : (address buffered-file), l : arg-location, stmt : (address statement)
+emit-subx-rm32:  # out : (address buffered-file), l : arg-location, stmt : (handle statement)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2660,7 +2667,7 @@ $emit-subx-rm32:end:
     5d/pop-to-ebp
     c3/return
 
-get-stmt-operand-from-arg-location:  # stmt : (address statement), l : arg-location -> var/eax : (address variable)
+get-stmt-operand-from-arg-location:  # stmt : (handle statement), l : arg-location -> var/eax : (handle variable)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2720,7 +2727,7 @@ $get-stmt-operand-from-arg-location:abort:
     cd/syscall  0x80/imm8
     # never gets here
 
-emit-subx-r32:  # out : (address buffered-file), l : arg-location, stmt : (address statement)
+emit-subx-r32:  # out : (address buffered-file), l : arg-location, stmt : (handle statement)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2745,7 +2752,7 @@ $emit-subx-r32:end:
     5d/pop-to-ebp
     c3/return
 
-emit-subx-imm32:  # out : (address buffered-file), l : arg-location, stmt : (address statement)
+emit-subx-imm32:  # out : (address buffered-file), l : arg-location, stmt : (handle statement)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2769,7 +2776,7 @@ $emit-subx-imm32:end:
     5d/pop-to-ebp
     c3/return
 
-emit-subx-call:  # out : (address buffered-file), stmt : (address statement), vars : (address variable), callee : (address function)
+emit-subx-call:  # out : (address buffered-file), stmt : (handle statement), vars : (handle variable), callee : (handle function)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2782,7 +2789,7 @@ emit-subx-call:  # out : (address buffered-file), stmt : (address statement), va
     8b/-> *(ebp+0x14) 1/r32/ecx
     (write-buffered *(ebp+8) *(ecx+4))  # Function-subx-name
     # - emit arguments
-    # var curr/ecx : (list var) = stmt->inouts
+    # var curr/ecx : (handle list var) = stmt->inouts
     8b/-> *(ebp+0xc) 1/r32/ecx
     8b/-> *(ecx+8) 1/r32/ecx  # Stmt1-inouts
     {
@@ -2805,7 +2812,7 @@ $emit-subx-call:end:
     5d/pop-to-ebp
     c3/return
 
-emit-subx-call-operand:  # out : (address buffered-file), operand : (address variable)
+emit-subx-call-operand:  # out : (address buffered-file), operand : (handle variable)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2831,7 +2838,7 @@ $emit-subx-call-operand:end:
     5d/pop-to-ebp
     c3/return
 
-emit-subx-var-as-rm32:  # out : (address buffered-file), operand : (address variable)
+emit-subx-var-as-rm32:  # out : (address buffered-file), operand : (handle variable)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2866,19 +2873,19 @@ $emit-subx-var-as-rm32:end:
     5d/pop-to-ebp
     c3/return
 
-find-matching-function:  # functions : (address function), stmt : (address statement) -> result/eax : (address function)
+find-matching-function:  # functions : (address function), stmt : (handle statement) -> result/eax : (handle function)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
     # . save registers
     51/push-ecx
-    # var curr/ecx : (address function) = functions
+    # var curr/ecx : (handle function) = functions
     8b/-> *(ebp+8) 1/r32/ecx
     {
       # if (curr == null) break
       81 7/subop/compare %ecx 0/imm32
       74/jump-if-equal break/disp8
-      # if match(curr, stmt) return curr
+      # if match(stmt, curr) return curr
       {
         (mu-stmt-matches-function? *(ebp+0xc) %ecx)  # => eax
         3d/compare-eax-and 0/imm32
@@ -2900,13 +2907,13 @@ $find-matching-function:end:
     5d/pop-to-ebp
     c3/return
 
-find-matching-primitive:  # primitives : (address primitive), stmt : (address statement) -> result/eax : (address primitive)
+find-matching-primitive:  # primitives : (handle primitive), stmt : (handle statement) -> result/eax : (handle primitive)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
     # . save registers
     51/push-ecx
-    # var curr/ecx : (address primitive) = primitives
+    # var curr/ecx : (handle primitive) = primitives
     8b/-> *(ebp+8) 1/r32/ecx
     {
 $find-matching-primitive:loop:
@@ -2936,7 +2943,7 @@ $find-matching-primitive:end:
     5d/pop-to-ebp
     c3/return
 
-mu-stmt-matches-function?:  # stmt : (address statement), function : (address opcode-info) => result/eax : boolean
+mu-stmt-matches-function?:  # stmt : (handle statement), function : (handle function) => result/eax : boolean
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -2954,7 +2961,7 @@ $mu-stmt-matches-function?:end:
     5d/pop-to-ebp
     c3/return
 
-mu-stmt-matches-primitive?:  # stmt : (address statement), primitive : (address primitive) => result/eax : boolean
+mu-stmt-matches-primitive?:  # stmt : (handle statement), primitive : (handle primitive) => result/eax : boolean
     # A mu stmt matches a primitive if the name matches, all the inout vars
     # match, and all the output vars match.
     # Vars match if types match and registers match.
@@ -3080,7 +3087,7 @@ $mu-stmt-matches-primitive?:end:
     5d/pop-to-ebp
     c3/return
 
-operand-matches-primitive?:  # var : (address var), primout-var : (address var) => result/eax : boolean
+operand-matches-primitive?:  # var : (handle var), primout-var : (handle var) => result/eax : boolean
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
@@ -3153,30 +3160,30 @@ test-emit-subx-statement-primitive:
     # setup
     (clear-stream _test-output-stream)
     (clear-stream $_test-output-buffered-file->buffer)
-    # var-foo/ecx : var
+    # var var-foo/ecx : (ref var)
     68/push 0/imm32/no-register
     68/push -8/imm32/stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "foo"/imm32
     89/<- %ecx 4/r32/esp
-    # vars/edx : (stack 1)
+    # var vars/edx : (ref stack 1)
     51/push-ecx/var-foo
     68/push 1/imm32/data-length
     68/push 1/imm32/top
     89/<- %edx 4/r32/esp
-    # operand/ebx : (list var)
+    # var operand/ebx : (ref list var)
     68/push 0/imm32/next
     51/push-ecx/var-foo
     89/<- %ebx 4/r32/esp
-    # stmt/esi : statement
+    # var stmt/esi : (ref statement)
     68/push 0/imm32/next
     68/push 0/imm32/outputs
     53/push-ebx/operands
     68/push "increment"/imm32/operation
     68/push 1/imm32
     89/<- %esi 4/r32/esp
-    # primitives/ebx : primitive
+    # var primitives/ebx : (ref primitive)
     68/push 0/imm32/next
     68/push 0/imm32/no-imm32
     68/push 0/imm32/no-r32
@@ -3226,41 +3233,41 @@ test-emit-subx-statement-primitive-register:
     # setup
     (clear-stream _test-output-stream)
     (clear-stream $_test-output-buffered-file->buffer)
-    # var-foo/ecx : var in eax
+    # var var-foo/ecx : (ref var) in eax
     68/push "eax"/imm32/register
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "foo"/imm32
     89/<- %ecx 4/r32/esp
-    # vars/edx : (stack 1)
+    # var vars/edx : (ref stack 1)
     51/push-ecx/var-foo
     68/push 1/imm32/data-length
     68/push 1/imm32/top
     89/<- %edx 4/r32/esp
-    # operand/ebx : (list var)
+    # var operand/ebx : (ref list var)
     68/push 0/imm32/next
     51/push-ecx/var-foo
     89/<- %ebx 4/r32/esp
-    # stmt/esi : statement
+    # var stmt/esi : (ref statement)
     68/push 0/imm32/next
     53/push-ebx/outputs
     68/push 0/imm32/inouts
     68/push "increment"/imm32/operation
     68/push 1/imm32
     89/<- %esi 4/r32/esp
-    # formal-var/ebx : var in any register
+    # var formal-var/ebx : (ref var) in any register
     68/push Any-register/imm32
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "dummy"/imm32
     89/<- %ebx 4/r32/esp
-    # operand/ebx : (list var)
+    # var operand/ebx : (ref list var)
     68/push 0/imm32/next
     53/push-ebx/formal-var
     89/<- %ebx 4/r32/esp
-    # primitives/ebx : primitive
+    # var primitives/ebx : (ref primitive)
     68/push 0/imm32/next
     68/push 0/imm32/no-imm32
     68/push 0/imm32/no-r32
@@ -3313,41 +3320,41 @@ test-emit-subx-statement-select-primitive:
     # setup
     (clear-stream _test-output-stream)
     (clear-stream $_test-output-buffered-file->buffer)
-    # var-foo/ecx : var in eax
+    # var var-foo/ecx : (ref var) in eax
     68/push "eax"/imm32/register
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "foo"/imm32
     89/<- %ecx 4/r32/esp
-    # vars/edx : (stack 1)
+    # var vars/edx : (ref stack 1)
     51/push-ecx/var-foo
     68/push 1/imm32/data-length
     68/push 1/imm32/top
     89/<- %edx 4/r32/esp
-    # real-outputs/edi : (list var)
+    # var real-outputs/edi : (ref list var)
     68/push 0/imm32/next
     51/push-ecx/var-foo
     89/<- %edi 4/r32/esp
-    # stmt/esi : statement
+    # var stmt/esi : (ref statement)
     68/push 0/imm32/next
     57/push-edi/outputs
     68/push 0/imm32/inouts
     68/push "increment"/imm32/operation
     68/push 1/imm32
     89/<- %esi 4/r32/esp
-    # formal-var/ebx : var in any register
+    # var formal-var/ebx : (ref var) in any register
     68/push Any-register/imm32
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "dummy"/imm32
     89/<- %ebx 4/r32/esp
-    # formal-outputs/ebx : (list var)
+    # var formal-outputs/ebx : (ref list var) = {formal-var, 0}
     68/push 0/imm32/next
     53/push-ebx/formal-var
     89/<- %ebx 4/r32/esp
-    # primitive1/ebx : primitive
+    # var primitive1/ebx : (ref primitive)
     68/push 0/imm32/next
     68/push 0/imm32/no-imm32
     68/push 0/imm32/no-r32
@@ -3357,7 +3364,7 @@ test-emit-subx-statement-select-primitive:
     68/push 0/imm32/inouts
     68/push "increment"/imm32/name
     89/<- %ebx 4/r32/esp
-    # primitives/ebx : primitive
+    # var primitives/ebx : (ref primitive)
     53/push-ebx/next
     68/push 0/imm32/no-imm32
     68/push 0/imm32/no-r32
@@ -3410,41 +3417,41 @@ test-emit-subx-statement-select-primitive-2:
     # setup
     (clear-stream _test-output-stream)
     (clear-stream $_test-output-buffered-file->buffer)
-    # var-foo/ecx : var in eax
+    # var var-foo/ecx : (ref var) in eax
     68/push "eax"/imm32/register
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "foo"/imm32
     89/<- %ecx 4/r32/esp
-    # vars/edx : (stack 1)
+    # var vars/edx : (ref stack 1)
     51/push-ecx/var-foo
     68/push 1/imm32/data-length
     68/push 1/imm32/top
     89/<- %edx 4/r32/esp
-    # inouts/edi : (list var)
+    # var inouts/edi : (ref list var)
     68/push 0/imm32/next
     51/push-ecx/var-foo
     89/<- %edi 4/r32/esp
-    # stmt/esi : statement
+    # var stmt/esi : (ref statement)
     68/push 0/imm32/next
     68/push 0/imm32/outputs
     57/push-edi/inouts
     68/push "increment"/imm32/operation
     68/push 1/imm32
     89/<- %esi 4/r32/esp
-    # formal-var/ebx : var in any register
+    # var formal-var/ebx : (ref var) in any register
     68/push Any-register/imm32
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "dummy"/imm32
     89/<- %ebx 4/r32/esp
-    # operand/ebx : (list var)
+    # var operand/ebx : (ref list var)
     68/push 0/imm32/next
     53/push-ebx/formal-var
     89/<- %ebx 4/r32/esp
-    # primitive1/ebx : primitive
+    # var primitive1/ebx : primitive
     68/push 0/imm32/next
     68/push 0/imm32/no-imm32
     68/push 0/imm32/no-r32
@@ -3454,7 +3461,7 @@ test-emit-subx-statement-select-primitive-2:
     68/push 0/imm32/inouts
     68/push "increment"/imm32/name
     89/<- %ebx 4/r32/esp
-    # primitives/ebx : primitive
+    # var primitives/ebx : (ref primitive)
     53/push-ebx/next
     68/push 0/imm32/no-imm32
     68/push 0/imm32/no-r32
@@ -3501,23 +3508,23 @@ test-increment-register:
     # setup
     (clear-stream _test-output-stream)
     (clear-stream $_test-output-buffered-file->buffer)
-    # var-foo/ecx : var in eax
+    # var var-foo/ecx : (ref var) in eax
     68/push "eax"/imm32/register
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "foo"/imm32
     89/<- %ecx 4/r32/esp
-    # vars/edx : (stack 1)
+    # var vars/edx : (ref stack 1)
     51/push-ecx/var-foo
     68/push 1/imm32/data-length
     68/push 1/imm32/top
     89/<- %edx 4/r32/esp
-    # real-outputs/edi : (list var)
+    # var real-outputs/edi : (ref list var)
     68/push 0/imm32/next
     51/push-ecx/var-foo
     89/<- %edi 4/r32/esp
-    # stmt/esi : statement
+    # var stmt/esi : (ref statement)
     68/push 0/imm32/next
     57/push-edi/outputs
     68/push 0/imm32/inouts
@@ -3561,23 +3568,23 @@ test-increment-var:
     # setup
     (clear-stream _test-output-stream)
     (clear-stream $_test-output-buffered-file->buffer)
-    # var-foo/ecx : var in eax
+    # var var-foo/ecx : (ref var) in eax
     68/push "eax"/imm32/register
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "foo"/imm32
     89/<- %ecx 4/r32/esp
-    # vars/edx : (stack 1)
+    # var vars/edx : (ref stack 1)
     51/push-ecx/var-foo
     68/push 1/imm32/data-length
     68/push 1/imm32/top
     89/<- %edx 4/r32/esp
-    # inouts/edi : (list var)
+    # var inouts/edi : (ref list var)
     68/push 0/imm32/next
     51/push-ecx/var-foo
     89/<- %edi 4/r32/esp
-    # stmt/esi : statement
+    # var stmt/esi : (ref statement)
     68/push 0/imm32/next
     68/push 0/imm32/outputs
     57/push-edi/inouts
@@ -3611,29 +3618,29 @@ test-add-reg-to-reg:
     # setup
     (clear-stream _test-output-stream)
     (clear-stream $_test-output-buffered-file->buffer)
-    # var-var1/ecx : var in eax
+    # var var-var1/ecx : (ref var) in eax
     68/push "eax"/imm32/register
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "var1"/imm32
     89/<- %ecx 4/r32/esp
-    # var-var2/edx : var in ecx
+    # var var-var2/edx : (ref var) in ecx
     68/push "ecx"/imm32/register
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "var2"/imm32
     89/<- %edx 4/r32/esp
-    # inouts/esi : (list var2)
+    # var inouts/esi : (ref list var2)
     68/push 0/imm32/next
     52/push-edx/var-var2
     89/<- %esi 4/r32/esp
-    # outputs/edi : (list var1)
+    # var outputs/edi : (ref list var1)
     68/push 0/imm32/next
     51/push-ecx/var-var1
     89/<- %edi 4/r32/esp
-    # stmt/esi : statement
+    # var stmt/esi : (ref statement)
     68/push 0/imm32/next
     57/push-edi/outputs
     56/push-esi/inouts
@@ -3667,29 +3674,29 @@ test-add-reg-to-mem:
     # setup
     (clear-stream _test-output-stream)
     (clear-stream $_test-output-buffered-file->buffer)
-    # var-var1/ecx : var
+    # var var-var1/ecx : (ref var)
     68/push 0/imm32/no-register
     68/push 8/imm32/stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "var1"/imm32
     89/<- %ecx 4/r32/esp
-    # var-var2/edx : var in ecx
+    # var var-var2/edx : (ref var) in ecx
     68/push "ecx"/imm32/register
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "var2"/imm32
     89/<- %edx 4/r32/esp
-    # inouts/esi : (list var2)
+    # var inouts/esi : (ref list var2)
     68/push 0/imm32/next
     52/push-edx/var-var2
     89/<- %esi 4/r32/esp
-    # inouts = (list var1 var2)
+    # var inouts = (ref list var1 var2)
     56/push-esi/next
     51/push-ecx/var-var1
     89/<- %esi 4/r32/esp
-    # stmt/esi : statement
+    # var stmt/esi : (ref statement)
     68/push 0/imm32/next
     68/push 0/imm32/outputs
     56/push-esi/inouts
@@ -3723,29 +3730,29 @@ test-add-mem-to-reg:
     # setup
     (clear-stream _test-output-stream)
     (clear-stream $_test-output-buffered-file->buffer)
-    # var-var1/ecx : var in eax
+    # var var-var1/ecx : (ref var) in eax
     68/push "eax"/imm32/register
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "var1"/imm32
     89/<- %ecx 4/r32/esp
-    # var-var2/edx : var
+    # var var-var2/edx : (ref var)
     68/push 0/imm32/no-register
     68/push 8/imm32/stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "var2"/imm32
     89/<- %edx 4/r32/esp
-    # inouts/esi : (list var2)
+    # var inouts/esi : (ref list var2)
     68/push 0/imm32/next
     52/push-edx/var-var2
     89/<- %esi 4/r32/esp
-    # outputs/edi : (list var1)
+    # var outputs/edi : (ref list var1)
     68/push 0/imm32/next
     51/push-ecx/var-var1
     89/<- %edi 4/r32/esp
-    # stmt/esi : statement
+    # var stmt/esi : (ref statement)
     68/push 0/imm32/next
     57/push-edi/outputs
     56/push-esi/inouts
@@ -3779,29 +3786,29 @@ test-add-literal-to-reg:
     # setup
     (clear-stream _test-output-stream)
     (clear-stream $_test-output-buffered-file->buffer)
-    # var-var1/ecx : var in eax
+    # var var-var1/ecx : (ref var) in eax
     68/push "eax"/imm32/register
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "var1"/imm32
     89/<- %ecx 4/r32/esp
-    # var-var2/edx : var literal
+    # var var-var2/edx : (ref var) literal
     68/push 0/imm32/no-register
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 0/imm32/type-literal
     68/push "0x34"/imm32
     89/<- %edx 4/r32/esp
-    # inouts/esi : (list var2)
+    # var inouts/esi : (ref list var2)
     68/push 0/imm32/next
     52/push-edx/var-var2
     89/<- %esi 4/r32/esp
-    # outputs/edi : (list var1)
+    # var outputs/edi : (ref list var1)
     68/push 0/imm32/next
     51/push-ecx/var-var1
     89/<- %edi 4/r32/esp
-    # stmt/esi : statement
+    # var stmt/esi : (ref statement)
     68/push 0/imm32/next
     57/push-edi/outputs
     56/push-esi/inouts
@@ -3835,29 +3842,29 @@ test-add-literal-to-mem:
     # setup
     (clear-stream _test-output-stream)
     (clear-stream $_test-output-buffered-file->buffer)
-    # var-var1/ecx : var
+    # var var-var1/ecx : (ref var)
     68/push 0/imm32/no-register
     68/push 8/imm32/stack-offset
     68/push 1/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "var1"/imm32
     89/<- %ecx 4/r32/esp
-    # var-var2/edx : var literal
+    # var var-var2/edx : (ref var) literal
     68/push 0/imm32/no-register
     68/push 0/imm32/no-stack-offset
     68/push 1/imm32/block-depth
     68/push 0/imm32/type-literal
     68/push "0x34"/imm32
     89/<- %edx 4/r32/esp
-    # inouts/esi : (list var2)
+    # var inouts/esi : (ref list var2)
     68/push 0/imm32/next
     52/push-edx/var-var2
     89/<- %esi 4/r32/esp
-    # inouts = (list var1 inouts)
+    # var inouts = (ref list var1 inouts)
     56/push-esi/next
     51/push-ecx/var-var1
     89/<- %esi 4/r32/esp
-    # stmt/esi : statement
+    # var stmt/esi : (ref statement)
     68/push 0/imm32/next
     68/push 0/imm32/outputs
     56/push-esi/inouts
@@ -3906,30 +3913,30 @@ test-emit-subx-statement-function-call:
     # setup
     (clear-stream _test-output-stream)
     (clear-stream $_test-output-buffered-file->buffer)
-    # var-foo/ecx : var
+    # var var-foo/ecx : (ref var)
     68/push 0/imm32/no-register
     68/push -8/imm32/stack-offset
     68/push 0/imm32/block-depth
     68/push 1/imm32/type-int
     68/push "foo"/imm32
     89/<- %ecx 4/r32/esp
-    # vars/edx = (stack 1)
+    # var vars/edx = (ref stack 1)
     51/push-ecx/var-foo
     68/push 1/imm32/data-length
     68/push 1/imm32/top
     89/<- %edx 4/r32/esp
-    # operands/esi : (list var)
+    # var operands/esi : (ref list var)
     68/push 0/imm32/next
     51/push-ecx/var-foo
     89/<- %esi 4/r32/esp
-    # stmt/esi : statement
+    # var stmt/esi : (ref statement)
     68/push 0/imm32/next
     68/push 0/imm32/outputs
     56/push-esi/inouts
     68/push "f"/imm32/operation
     68/push 1/imm32
     89/<- %esi 4/r32/esp
-    # functions/ebx : function
+    # var functions/ebx : (ref function)
     68/push 0/imm32/next
     68/push 0/imm32/body
     68/push 0/imm32/outputs
@@ -3965,30 +3972,30 @@ test-emit-subx-statement-function-call-with-literal-arg:
     # setup
     (clear-stream _test-output-stream)
     (clear-stream $_test-output-buffered-file->buffer)
-    # var-foo/ecx : literal
+    # var var-foo/ecx : (ref var) literal
     68/push 0/imm32/no-register
     68/push 0/imm32/no-stack-offset
     68/push 0/imm32/block-depth
     68/push 0/imm32/type-literal
     68/push "34"/imm32
     89/<- %ecx 4/r32/esp
-    # vars/edx = (stack 1)
+    # var vars/edx = (ref stack 1)
     51/push-ecx/var-foo
     68/push 1/imm32/data-length
     68/push 1/imm32/top
     89/<- %edx 4/r32/esp
-    # operands/esi : (list var)
+    # var operands/esi : (ref list var)
     68/push 0/imm32/next
     51/push-ecx/var-foo
     89/<- %esi 4/r32/esp
-    # stmt/esi : statement
+    # var stmt/esi : (ref statement)
     68/push 0/imm32/next
     68/push 0/imm32/outputs
     56/push-esi/inouts
     68/push "f"/imm32/operation
     68/push 1/imm32
     89/<- %esi 4/r32/esp
-    # functions/ebx : function
+    # var functions/ebx : (ref function)
     68/push 0/imm32/next
     68/push 0/imm32/body
     68/push 0/imm32/outputs
diff --git a/apps/mulisp.subx b/apps/mulisp.subx
index 71ad170c..1cfdeb03 100644
--- a/apps/mulisp.subx
+++ b/apps/mulisp.subx
@@ -81,12 +81,12 @@ repl:  # in : (address buffered-file), out : (address buffered-file)
     # . save registers
     50/push-eax
     {
-      (lisp-read Stdin)  # => eax : (address cell)
+      (lisp-read Stdin)  # => eax : (handle cell)
       # if (eax == 0) break
       3d/compare-eax-and 0/imm32
       74/jump-if-equal break/disp8
       #
-      (lisp-eval %eax)  # => eax : (address cell)
+      (lisp-eval %eax)  # => eax : (handle cell)
       (lisp-print Stdout %eax)
       eb/jump loop/disp8
     }
@@ -104,13 +104,13 @@ $repl:end:
 # arrays start with '['
 # symbols start with anything else but quote, backquote, unquote or splice
 # only one s-expression per line
-lisp-read:  # in : (address buffered-file) -> eax : (address cell)
+lisp-read:  # in : (address buffered-file) -> eax : (handle cell)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
     # . save registers
     51/push-ecx
-    # var s/ecx : (stream byte 512)
+    # var s/ecx : (ref stream byte 512)
     81 5/subop/subtract %esp 0x200/imm32
     68/push 0x200/imm32/size
     68/push 0/imm32/read
@@ -142,14 +142,14 @@ $lisp-read:end:
     5d/pop-to-ebp
     c3/return
 
-# lisp-read:  in : (address buffered-file) -> (address cell)
+# lisp-read:  in : (address buffered-file) -> (handle cell)
 #   token tmp = next-mulisp-token(in)
 #   if is-int(tmp) return cell(tmp)
 #   if is-string(tmp) return cell(tmp)
 #   if is-pair(tmp) ...
 #   if is-array(tmp) ...
 
-next-mulisp-token:  # in : (address buffered-file), line : (address stream), result : (address slice)
+next-mulisp-token:  # in : (address buffered-file), line : (address stream byte), result : (address slice)
     # pseudocode:
     #   if (line->read >= line->write)
     #     read-line-buffered(in, line)
@@ -194,11 +194,11 @@ $next-mulisp-token:end:
     5d/pop-to-ebp
     c3/return
 
-new-int-cell:  # in : (address slice) -> eax : (address cell)
+new-int-cell:  # in : (address slice) -> eax : (handle cell)
 
-new-string-cell:  # in : (address slice) -> eax : (address cell)
+new-string-cell:  # in : (address slice) -> eax : (handle cell)
 
-lisp-eval:  # in : (address cell) -> eax : (address cell)
+lisp-eval:  # in : (address cell) -> eax : (handle cell)
     # . prologue
     55/push-ebp
     89/<- %ebp 4/r32/esp
diff --git a/apps/pack b/apps/pack
index 74d4ed32..005c42f8 100755
--- a/apps/pack
+++ b/apps/pack
Binary files differdiff --git a/apps/pack.subx b/apps/pack.subx
index 6079a896..df683f84 100644
--- a/apps/pack.subx
+++ b/apps/pack.subx
@@ -45,8 +45,8 @@ Entry:  # run tests if necessary, convert stdin if not
     e8/call  kernel-string-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto interactive
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto interactive
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $subx-pack-main:interactive/disp8
     # run-tests()
     e8/call  run-tests/disp32
@@ -55,7 +55,7 @@ Entry:  # run tests if necessary, convert stdin if not
     eb/jump  $subx-pack-main:end/disp8
 $subx-pack-main:interactive:
     # - otherwise convert stdin
-    # var ed/eax : exit-descriptor
+    # var ed/eax : (ref exit-descriptor)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # subtract from esp
     89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
     # configure ed to really exit()
@@ -99,7 +99,7 @@ $subx-pack-main:end:
 
 subx-pack:  # in : (address buffered-file), out : (address buffered-file)
     # pseudocode:
-    #   var line : (stream byte 512)
+    #   var line : (ref stream byte 512)
     #   var in-code? = false
     #   while true
     #     clear-stream(line)
@@ -128,17 +128,17 @@ subx-pack:  # in : (address buffered-file), out : (address buffered-file)
     51/push-ecx
     52/push-edx
     53/push-ebx
-    # var line/ecx : (address stream byte) = stream(512)
+    # var line/ecx : (ref stream byte 512)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0x200/imm32       # subtract from esp
     68/push  0x200/imm32/length
     68/push  0/imm32/read
     68/push  0/imm32/write
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # var word-slice/edx = {0, 0}
+    # var word-slice/edx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    2/rm32/edx    .           .             .           4/r32/esp   .               .                 # copy esp to edx
-    # var in-code?/ebx = false
+    # var in-code?/ebx : boolean = false
     31/xor                          3/mod/direct    3/rm32/ebx    .           .             .           3/r32/ebx   .               .                 # clear ebx
 $subx-pack:loop:
     # clear-stream(line)
@@ -203,8 +203,8 @@ $subx-pack:check1:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) write-stream-data(out, line)
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) write-stream-data(out, line)
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $subx-pack:pass-through/disp32
 $subx-pack:check2:
 #?     # dump word-slice {{{
@@ -256,8 +256,8 @@ $subx-pack:check2:
     e8/call  slice-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto check3
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto check3
+    3d/compare-eax-and  0/imm32/false
     0f 84/jump-if-equal  $subx-pack:check3/disp32
     # word-slice = next-word(line)
     # . . push args
@@ -328,8 +328,8 @@ $subx-pack:check3:
     e8/call  rewind-stream/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # if (in-code? != 0) convert-instruction(line, out)
-    81          7/subop/compare     3/mod/direct    3/rm32/ebx    .           .             .           .           .               0/imm32           # compare ebx
+    # if (in-code? != false) convert-instruction(line, out)
+    81          7/subop/compare     3/mod/direct    3/rm32/ebx    .           .             .           .           .               0/imm32/false     # compare ebx
     74/jump-if-equal  $subx-pack:data/disp8
 $subx-pack:code:
     # . convert-instruction(line, out)
@@ -911,7 +911,7 @@ test-subx-pack-code-and-data-segments:
 
 convert-data:  # line : (address stream byte), out : (address buffered-file)
     # pseudocode:
-    #   var word-slice = {0, 0}
+    #   var word-slice : (ref slice)
     #   while true
     #     word-slice = next-word(line)
     #     if slice-empty?(word-slice)                 # end of file (maybe including trailing whitespace)
@@ -936,7 +936,7 @@ convert-data:  # line : (address stream byte), out : (address buffered-file)
     50/push-eax
     51/push-ecx
     52/push-edx
-    # var word-slice/ecx = {0, 0}
+    # var word-slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -1024,17 +1024,17 @@ $convert-data:check0:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) break
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) break
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $convert-data:break/disp32
 $convert-data:check-for-comment:
     # if (slice-starts-with?(word-slice, "#"))
-    # . start/edx = word-slice->start
+    # . var start/edx : (address byte) = word-slice->start
     8b/copy                         0/mod/indirect  1/rm32/ecx    .           .             .           2/r32/edx   .               .                 # copy *ecx to edx
-    # . c/eax = *start
+    # . var c/eax : byte = *start
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
     8a/copy-byte                    0/mod/indirect  2/rm32/edx    .           .             .           0/r32/AL    .               .                 # copy byte at *edx to AL
-    # . if (eax != '#') goto next check
+    # . if (c != '#') goto next check
     3d/compare-eax-and  0x23/imm32/hash
     75/jump-if-not-equal  $convert-data:check-for-label/disp8
 $convert-data:comment:
@@ -1050,12 +1050,12 @@ $convert-data:comment:
     0f 85/jump-if-not-equal  $convert-data:end/disp32
 $convert-data:check-for-label:
     # if (slice-ends-with?(word-slice, ":"))
-    # . end/edx = word-slice->end
+    # . var end/edx : (address byte) = word-slice->end
     8b/copy                         1/mod/*+disp8   1/rm32/ecx    .           .             .           2/r32/edx   4/disp8         .                 # copy *(ecx+4) to edx
-    # . c/eax = *(end-1)
+    # . var c/eax : byte = *(end-1)
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
     8a/copy-byte                    1/mod/*+disp8   2/rm32/edx    .           .             .           0/r32/AL    -1/disp8        .                 # copy byte at *ecx to AL
-    # . if (eax != ':') goto next check
+    # . if (c != ':') goto next check
     3d/compare-eax-and  0x3a/imm32/colon
     75/jump-if-not-equal  $convert-data:check-for-imm32/disp8
 $convert-data:label:
@@ -1079,8 +1079,8 @@ $convert-data:check-for-imm32:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) process as a single byte
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) process as a single byte
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $convert-data:single-byte/disp8
 $convert-data:imm32:
     # emit(out, word-slice, 4)
@@ -1837,7 +1837,7 @@ convert-instruction:  # line : (address stream byte), out : (address buffered-fi
     50/push-eax
     51/push-ecx
     52/push-edx
-    # var word-slice/ecx = {0, 0}
+    # var word-slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -1858,27 +1858,27 @@ $convert-instruction:check0:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) pass through
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) pass through
+    3d/compare-eax-and  0/imm32/false
     75/jump-if-not-equal  $convert-instruction:pass-through/disp8
 $convert-instruction:check1:
     # if (slice-starts-with?(word-slice, "#")) write-stream-data(out, line)
-    # . start/edx = word-slice->start
+    # . var start/edx : (address byte) = word-slice->start
     8b/copy                         0/mod/indirect  1/rm32/ecx    .           .             .           2/r32/edx   .               .                 # copy *ecx to edx
-    # . c/eax = *start
+    # . var c/eax : byte = *start
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
     8a/copy-byte                    0/mod/indirect  2/rm32/edx    .           .             .           0/r32/AL    .               .                 # copy byte at *edx to AL
-    # . if (eax == '#') pass through
+    # . if (c == '#') pass through
     3d/compare-eax-and  0x23/imm32/hash
     74/jump-if-equal  $convert-instruction:pass-through/disp8
 $convert-instruction:check2:
     # if (slice-ends-with?(word-slice, ":")) write-stream-data(out, line)
-    # . end/edx = word-slice->end
+    # . var end/edx : (address byte) = word-slice->end
     8b/copy                         1/mod/*+disp8   1/rm32/ecx    .           .             .           2/r32/edx   4/disp8         .                 # copy *(ecx+4) to edx
-    # . c/eax = *(end-1)
+    # . var c/eax : byte = *(end-1)
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
     8a/copy-byte                    1/mod/*+disp8   2/rm32/edx    .           .             .           0/r32/AL    -1/disp8        .                 # copy byte at *ecx to AL
-    # . if (eax == ':') pass through
+    # . if (c == ':') pass through
     3d/compare-eax-and  0x3a/imm32/colon
     75/jump-if-not-equal  $convert-instruction:really-convert/disp8
 $convert-instruction:pass-through:
@@ -1994,11 +1994,11 @@ emit-opcodes:  # line : (address stream byte), out : (address buffered-file)
     51/push-ecx
     52/push-edx
     53/push-ebx
-    # var op1/ecx = {0, 0}
+    # var op1/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # var op2/edx = {0, 0}
+    # var op2/edx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    2/rm32/edx    .           .             .           4/r32/esp   .               .                 # copy esp to edx
@@ -2026,16 +2026,16 @@ $emit-opcodes:op1:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) return
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) return
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-opcodes:end/disp32
     # if (slice-starts-with?(op1, "#")) return
-    # . start/ebx = op1->start
+    # . var start/ebx : (address byte) = op1->start
     8b/copy                         0/mod/indirect  1/rm32/ecx    .           .             .           3/r32/ebx   .               .                 # copy *ecx to ebx
-    # . c/eax = *start
+    # . var c/eax : byte = *start
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
     8a/copy-byte                    0/mod/indirect  3/rm32/ebx    .           .             .           0/r32/AL    .               .                 # copy byte at *ebx to AL
-    # . if (eax == '#') return
+    # . if (c == '#') return
     3d/compare-eax-and  0x23/imm32/hash
     0f 84/jump-if-equal  $emit-opcodes:end/disp32
     # op1 = next-token-from-slice(op1->start, op1->end, '/')
@@ -2073,8 +2073,8 @@ $emit-opcodes:op1:
     e8/call  slice-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax != 0) goto op2
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) goto op2
+    3d/compare-eax-and  0/imm32/false
     75/jump-if-not-equal  $emit-opcodes:op2/disp8
     # if (slice-equal?(op1, "f2")) goto op2
     # . eax = slice-equal?(op1, "f2")
@@ -2085,8 +2085,8 @@ $emit-opcodes:op1:
     e8/call  slice-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax != 0) goto op2
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) goto op2
+    3d/compare-eax-and  0/imm32/false
     75/jump-if-not-equal  $emit-opcodes:op2/disp8
     # if (slice-equal?(op1, "f3")) goto op2
     # . eax = slice-equal?(op1, "f3")
@@ -2097,8 +2097,8 @@ $emit-opcodes:op1:
     e8/call  slice-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax != 0) goto op2
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) goto op2
+    3d/compare-eax-and  0/imm32/false
     75/jump-if-not-equal  $emit-opcodes:op2/disp8
     # otherwise return
     e9/jump  $emit-opcodes:end/disp32
@@ -2119,16 +2119,16 @@ $emit-opcodes:op2:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) return
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) return
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-opcodes:end/disp32
     # if (slice-starts-with?(op2, "#")) return
-    # . start/ebx = op2->start
+    # . var start/ebx : (address byte) = op2->start
     8b/copy                         0/mod/indirect  2/rm32/edx    .           .             .           3/r32/ebx   .               .                 # copy *edx to ebx
-    # . c/eax = *start
+    # . var c/eax : byte = *start
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
     8a/copy-byte                    0/mod/indirect  3/rm32/ebx    .           .             .           0/r32/AL    .               .                 # copy byte at *ebx to AL
-    # . if (eax == '#') return
+    # . if (c == '#') return
     3d/compare-eax-and  0x23/imm32/hash
     0f 84/jump-if-equal  $emit-opcodes:end/disp32
     # op2 = next-token-from-slice(op2->start, op2->end, '/')
@@ -2166,8 +2166,8 @@ $emit-opcodes:op2:
     e8/call  slice-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax != 0) return
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) return
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-opcodes:end/disp32
     # if (!slice-equal?(op2, "0f")) return
     # . eax = slice-equal?(op2, "0f")
@@ -2178,8 +2178,8 @@ $emit-opcodes:op2:
     e8/call  slice-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) return
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) return
+    3d/compare-eax-and  0/imm32/false
     0f 84/jump-if-equal  $emit-opcodes:end/disp32
 $emit-opcodes:op3:
     # next-word(line, op3)  # reuse op2/edx
@@ -2198,16 +2198,16 @@ $emit-opcodes:op3:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) return
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) return
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-opcodes:end/disp32
     # if (slice-starts-with?(op3, "#")) return
-    # . start/ebx = op2->start
+    # . var start/ebx : (address byte) = op2->start
     8b/copy                         0/mod/indirect  2/rm32/edx    .           .             .           3/r32/ebx   .               .                 # copy *edx to ebx
-    # . c/eax = *start
+    # . var c/eax : byte = *start
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
     8a/copy-byte                    0/mod/indirect  3/rm32/ebx    .           .             .           0/r32/AL    .               .                 # copy byte at *ebx to AL
-    # . if (eax == '#') return
+    # . if (c == '#') return
     3d/compare-eax-and  0x23/imm32/hash
     0f 84/jump-if-equal  $emit-opcodes:end/disp32
     # op3 = next-token-from-slice(op3->start, op3->end, '/')
@@ -2253,7 +2253,7 @@ emit-modrm:  # line : (address stream byte), out : (address buffered-file)
     # pseudocode:
     #   rewind-stream(line)
     #   var has-modrm? = false, mod = 0, rm32 = 0, r32 = 0
-    #   var word-slice = {0, 0}
+    #   var word-slice : (ref slice)
     #   while true
     #     word-slice = next-word(line)
     #     if (slice-empty?(word-slice)) break
@@ -2285,17 +2285,17 @@ emit-modrm:  # line : (address stream byte), out : (address buffered-file)
     53/push-ebx
     56/push-esi
     57/push-edi
-    # var word-slice/ecx = {0, 0}
+    # var word-slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # var has-modrm?/edx = false
+    # var has-modrm?/edx : boolean = false
     31/xor                          3/mod/direct    2/rm32/edx    .           .             .           2/r32/edx   .               .                 # clear edx
-    # var mod/ebx = 0
+    # var mod/ebx : byte = 0
     31/xor                          3/mod/direct    3/rm32/ebx    .           .             .           3/r32/ebx   .               .                 # clear ebx
-    # var rm32/esi = 0
+    # var rm32/esi : byte = 0
     31/xor                          3/mod/direct    6/rm32/esi    .           .             .           6/r32/esi   .               .                 # clear esi
-    # var r32/edi = 0
+    # var r32/edi : byte = 0
     31/xor                          3/mod/direct    7/rm32/edi    .           .             .           7/r32/edi   .               .                 # clear edi
     # rewind-stream(line)
     # . . push args
@@ -2395,21 +2395,21 @@ $emit-modrm:check0:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) pass through
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) pass through
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-modrm:break/disp32
 $emit-modrm:check1:
     # if (slice-starts-with?(word-slice, "#")) break
     # . spill edx
     52/push-edx
-    # . start/edx = word-slice->start
+    # . var start/edx : (address byte) = word-slice->start
     8b/copy                         0/mod/indirect  1/rm32/ecx    .           .             .           2/r32/edx   .               .                 # copy *ecx to edx
-    # . c/eax = *start
+    # . var c/eax : byte = *start
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
     8a/copy-byte                    0/mod/indirect  2/rm32/edx    .           .             .           0/r32/AL    .               .                 # copy byte at *edx to AL
     # . restore edx
     5a/pop-to-edx
-    # . if (eax == '#') pass through
+    # . if (c == '#') pass through
     3d/compare-eax-and  0x23/imm32/hash
     0f 84/jump-if-equal  $emit-modrm:break/disp32
 $emit-modrm:check-for-mod:
@@ -2422,8 +2422,8 @@ $emit-modrm:check-for-mod:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto next check
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto next check
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $emit-modrm:check-for-rm32/disp8
 $emit-modrm:mod:
     # mod = parse-hex-int(next-token-from-slice(word-slice->start, word-slice->end, '/'))
@@ -2450,8 +2450,8 @@ $emit-modrm:check-for-rm32:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto next check
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto next check
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $emit-modrm:check-for-r32/disp8
 $emit-modrm:rm32:
     # rm32 = parse-hex-int(next-token-from-slice(word-slice->start, word-slice->end, '/'))
@@ -2478,8 +2478,8 @@ $emit-modrm:check-for-r32:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto next check
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto next check
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $emit-modrm:check-for-subop/disp8
 $emit-modrm:r32:
     # r32 = parse-hex-int(next-token-from-slice(word-slice->start, word-slice->end, '/'))
@@ -2506,8 +2506,8 @@ $emit-modrm:check-for-subop:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) loop
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) loop
+    3d/compare-eax-and  0/imm32/false
     0f 84/jump-if-equal  $emit-modrm:loop/disp32
 $emit-modrm:subop:
     # r32 = parse-hex-int(next-token-from-slice(word-slice->start, word-slice->end, '/'))
@@ -2526,10 +2526,10 @@ $emit-modrm:subop:
     e9/jump  $emit-modrm:loop/disp32
 $emit-modrm:break:
     # if (!has-modrm?) return
-    81          7/subop/compare     3/mod/direct    2/rm32/edx    .           .             .           .           .               0/imm32           # compare edx
+    81          7/subop/compare     3/mod/direct    2/rm32/edx    .           .             .           .           .               0/imm32/false     # compare edx
     74/jump-if-equal  $emit-modrm:end/disp8
 $emit-modrm:calculate:
-    # modrm/ebx = mod & 0b11
+    # var modrm/ebx : byte = mod & 0b11
     81          4/subop/and         3/mod/direct    3/rm32/ebx    .           .             .           .           .               3/imm32/0b11      # bitwise and of ebx
     # modrm <<= 3
     c1/shift    4/subop/left        3/mod/direct    3/rm32/ebx    .           .             .           .           .               3/imm8            # shift ebx left by 3 bits
@@ -2569,7 +2569,7 @@ $emit-modrm:end:
 emit-sib:  # line : (address stream byte), out : (address buffered-file)
     # pseudocode:
     #   var has-sib? = false, base = 0, index = 0, scale = 0
-    #   var word-slice = {0, 0}
+    #   var word-slice : (ref slice)
     #   while true
     #     word-slice = next-word(line)
     #     if (slice-empty?(word-slice)) break
@@ -2601,17 +2601,17 @@ emit-sib:  # line : (address stream byte), out : (address buffered-file)
     53/push-ebx
     56/push-esi
     57/push-edi
-    # var word-slice/ecx = {0, 0}
+    # var word-slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # var has-sib?/edx = false
+    # var has-sib?/edx : boolean = false
     31/xor                          3/mod/direct    2/rm32/edx    .           .             .           2/r32/edx   .               .                 # clear edx
-    # var scale/ebx = 0
+    # var scale/ebx : byte = 0
     31/xor                          3/mod/direct    3/rm32/ebx    .           .             .           3/r32/ebx   .               .                 # clear ebx
-    # var base/esi = 0
+    # var base/esi : byte = 0
     31/xor                          3/mod/direct    6/rm32/esi    .           .             .           6/r32/esi   .               .                 # clear esi
-    # var index/edi = 0
+    # var index/edi : byte = 0
     31/xor                          3/mod/direct    7/rm32/edi    .           .             .           7/r32/edi   .               .                 # clear edi
     # rewind-stream(line)
     # . . push args
@@ -2704,21 +2704,21 @@ $emit-sib:check0:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) pass through
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) pass through
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-sib:break/disp32
 $emit-sib:check1:
     # if (slice-starts-with?(word-slice, "#")) break
     # . spill edx
     52/push-edx
-    # . start/edx = word-slice->start
+    # . var start/edx : (address byte) = word-slice->start
     8b/copy                         0/mod/indirect  1/rm32/ecx    .           .             .           2/r32/edx   .               .                 # copy *ecx to edx
-    # . c/eax = *start
+    # . var c/eax : byte = *start
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
     8a/copy-byte                    0/mod/indirect  2/rm32/edx    .           .             .           0/r32/AL    .               .                 # copy byte at *edx to AL
     # . restore edx
     5a/pop-to-edx
-    # . if (eax == '#') pass through
+    # . if (c == '#') pass through
     3d/compare-eax-and  0x23/imm32/hash
     0f 84/jump-if-equal  $emit-sib:break/disp32
 $emit-sib:check-for-scale:
@@ -2731,8 +2731,8 @@ $emit-sib:check-for-scale:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto next check
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto next check
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $emit-sib:check-for-base/disp8
 $emit-sib:scale:
     # scale = parse-hex-int(next-token-from-slice(word-slice->start, word-slice->end, '/'))
@@ -2759,8 +2759,8 @@ $emit-sib:check-for-base:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto next check
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto next check
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $emit-sib:check-for-index/disp8
 $emit-sib:base:
     # base = parse-hex-int(next-token-from-slice(word-slice->start, word-slice->end, '/'))
@@ -2787,8 +2787,8 @@ $emit-sib:check-for-index:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) loop
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) loop
+    3d/compare-eax-and  0/imm32/false
     0f 84/jump-if-equal  $emit-sib:loop/disp32
 $emit-sib:index:
     # index = parse-hex-int(next-token-from-slice(word-slice->start, word-slice->end, '/'))
@@ -2807,10 +2807,10 @@ $emit-sib:index:
     e9/jump  $emit-sib:loop/disp32
 $emit-sib:break:
     # if (!has-sib?) return
-    81          7/subop/compare     3/mod/direct    2/rm32/edx    .           .             .           .           .               0/imm32           # compare edx
+    81          7/subop/compare     3/mod/direct    2/rm32/edx    .           .             .           .           .               0/imm32/false     # compare edx
     74/jump-if-equal  $emit-sib:end/disp8
 $emit-sib:calculate:
-    # sib/ebx = scale & 0b11
+    # var sib/ebx : byte = scale & 0b11
     81          4/subop/and         3/mod/direct    3/rm32/ebx    .           .             .           .           .               3/imm32/0b11      # bitwise and of ebx
     # sib <<= 2
     c1/shift    4/subop/left        3/mod/direct    3/rm32/ebx    .           .             .           .           .               2/imm8            # shift ebx left by 2 bits
@@ -2850,7 +2850,7 @@ $emit-sib:end:
 emit-disp:  # line : (address stream byte), out : (address buffered-file)
     # pseudocode:
     #   rewind-stream(line)
-    #   var word-slice = {0, 0}
+    #   var word-slice : (ref slice)
     #   while true
     #     word-slice = next-word(line)
     #     if (slice-empty?(word-slice)) break
@@ -2872,7 +2872,7 @@ emit-disp:  # line : (address stream byte), out : (address buffered-file)
     50/push-eax
     51/push-ecx
     52/push-edx
-    # var word-slice/ecx = {0, 0}
+    # var word-slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -2967,17 +2967,17 @@ $emit-disp:check0:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) pass through
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) pass through
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-disp:break/disp32
 $emit-disp:check1:
     # if (slice-starts-with?(word-slice, "#")) break
-    # . start/edx = word-slice->start
+    # . var start/edx : (address byte) = word-slice->start
     8b/copy                         0/mod/indirect  1/rm32/ecx    .           .             .           2/r32/edx   .               .                 # copy *ecx to edx
-    # . c/eax = *start
+    # . var c/eax : byte = *start
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
     8a/copy-byte                    0/mod/indirect  2/rm32/edx    .           .             .           0/r32/AL    .               .                 # copy byte at *edx to AL
-    # . if (eax == '#') break
+    # . if (c == '#') break
     3d/compare-eax-and  0x23/imm32/hash
     0f 84/jump-if-equal  $emit-disp:break/disp32
 $emit-disp:check-for-disp32:
@@ -2990,8 +2990,8 @@ $emit-disp:check-for-disp32:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto next check
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto next check
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $emit-disp:check-for-disp16/disp8
 $emit-disp:disp32:
     # emit(out, word-slice, 4)
@@ -3015,8 +3015,8 @@ $emit-disp:check-for-disp16:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto next check
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto next check
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $emit-disp:check-for-disp8/disp8
 $emit-disp:disp16:
     # emit(out, word-slice, 2)
@@ -3040,8 +3040,8 @@ $emit-disp:check-for-disp8:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) loop
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) loop
+    3d/compare-eax-and  0/imm32/false
     0f 84/jump-if-equal  $emit-disp:loop/disp32
 $emit-disp:disp8:
     # emit(out, word-slice, 1)
@@ -3069,7 +3069,7 @@ $emit-disp:break:
 emit-imm:  # line : (address stream byte), out : (address buffered-file)
     # pseudocode:
     #   rewind-stream(line)
-    #   var word-slice = {0, 0}
+    #   var word-slice : (ref slice)
     #   while true
     #     word-slice = next-word(line)
     #     if (slice-empty?(word-slice)) break
@@ -3091,7 +3091,7 @@ emit-imm:  # line : (address stream byte), out : (address buffered-file)
     50/push-eax
     51/push-ecx
     52/push-edx
-    # var word-slice/ecx = {0, 0}
+    # var word-slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -3186,17 +3186,17 @@ $emit-imm:check0:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) pass through
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) pass through
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-imm:break/disp32
 $emit-imm:check1:
     # if (slice-starts-with?(word-slice, "#")) break
-    # . start/edx = slice->start
+    # . var start/edx : (address byte) = slice->start
     8b/copy                         0/mod/indirect  1/rm32/ecx    .           .             .           2/r32/edx   .               .                 # copy *ecx to edx
-    # . c/eax = *start
+    # . var c/eax : byte = *start
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
     8a/copy-byte                    0/mod/indirect  2/rm32/edx    .           .             .           0/r32/AL    .               .                 # copy byte at *edx to AL
-    # . if (eax == '#') break
+    # . if (c == '#') break
     3d/compare-eax-and  0x23/imm32/hash
     0f 84/jump-if-equal  $emit-imm:break/disp32
 $emit-imm:check-for-imm32:
@@ -3209,8 +3209,8 @@ $emit-imm:check-for-imm32:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto next check
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto next check
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $emit-imm:check-for-imm16/disp8
 $emit-imm:imm32:
     # emit(out, word-slice, 4)
@@ -3234,8 +3234,8 @@ $emit-imm:check-for-imm16:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto next check
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto next check
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $emit-imm:check-for-imm8/disp8
 $emit-imm:imm16:
     # emit(out, word-slice, 2)
@@ -3259,8 +3259,8 @@ $emit-imm:check-for-imm8:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) loop
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) loop
+    3d/compare-eax-and  0/imm32/false
     0f 84/jump-if-equal  $emit-imm:loop/disp32
 $emit-imm:imm8:
     # emit(out, word-slice, 1)
@@ -5837,7 +5837,7 @@ test-convert-instruction-handles-imm8-operand:
     c3/return
 
 # shortcut for parse-hex-int(next-token-from-slice(word->start, word->end, '/'))
-parse-datum-of-word:  # word : (address slice) -> value/eax
+parse-datum-of-word:  # word : (address slice) -> value/eax : int
     # . prologue
     55/push-ebp
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
@@ -5846,7 +5846,7 @@ parse-datum-of-word:  # word : (address slice) -> value/eax
     56/push-esi
     # esi = word
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           6/r32/esi   8/disp8         .                 # copy *(ebp+8) to esi
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -5860,7 +5860,7 @@ parse-datum-of-word:  # word : (address slice) -> value/eax
     e8/call  next-token-from-slice/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               0x10/imm32        # add to esp
-    # value/eax = parse-hex-int(slice)
+    # return parse-hex-int(slice)
     # . . push args
     51/push-ecx
     # . . call
diff --git a/apps/sigils b/apps/sigils
index a792c7e0..a1f33ada 100755
--- a/apps/sigils
+++ b/apps/sigils
Binary files differdiff --git a/apps/sigils.subx b/apps/sigils.subx
index e6aba87a..a22aee44 100644
--- a/apps/sigils.subx
+++ b/apps/sigils.subx
@@ -78,8 +78,8 @@ Entry:  # run tests if necessary, convert stdin if not
     e8/call  kernel-string-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto interactive
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto interactive
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $subx-sigils-main:interactive/disp8
     # run-tests()
     e8/call  run-tests/disp32
@@ -147,7 +147,7 @@ subx-sigils:  # in : (address buffered-file), out : (address buffered-file)
     68/push  0/imm32/read
     68/push  0/imm32/write
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # var word-slice/edx = {0, 0}
+    # var word-slice/edx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    2/rm32/edx    .           .             .           4/r32/esp   .               .                 # copy esp to edx
@@ -189,8 +189,8 @@ $subx-sigils:check1:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) break
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) break
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $subx-sigils:next-line/disp32
 $subx-sigils:check-for-comment:
     # if (slice-starts-with?(word-slice, "#")) continue
@@ -269,8 +269,8 @@ $subx-sigils:check-for-indirect-mode:
     e8/call  disp32-mode?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax == 0) goto indirect mode
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto indirect mode
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $subx-sigils:indirect-mode/disp8
 $subx-sigils:disp32-mode:
     # emit-indirect-mode(out, word-slice)
@@ -1365,7 +1365,7 @@ emit-direct-mode:  # out : (address buffered-file), word-slice : (address slice)
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
     # . save registers
     50/push-eax
-    # var local-slice/eax : (address slice) = {word-slice->start, word-slice->end}
+    # var local-slice/eax : (ref slice) = {word-slice->start, word-slice->end}
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           0/r32/eax   0xc/disp8       .                 # copy *(ebp+12) to eax
     ff          6/subop/push        1/mod/*+disp8   0/rm32/eax    .           .             .           .           4/disp8         .                 # push *(eax+4)
     ff          6/subop/push        0/mod/indirect  0/rm32/eax    .           .             .           .           .               .                 # push *eax
@@ -1834,7 +1834,7 @@ test-next-word-or-expression:
     e8/call  clear-stream/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -1907,7 +1907,7 @@ test-next-word-or-expression-returns-whole-comment:
     e8/call  clear-stream/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -1980,7 +1980,7 @@ test-next-word-or-expression-returns-empty-slice-on-eof:
     e8/call  clear-stream/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -2022,7 +2022,7 @@ test-next-word-or-expression-returns-string-literal:
     e8/call  clear-stream/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -2085,7 +2085,7 @@ test-next-word-or-expression-returns-string-with-escapes:
     e8/call  clear-stream/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -2148,7 +2148,7 @@ test-next-word-or-expression-returns-whole-expression:
     e8/call  clear-stream/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # var slice/ecx = {0, 0}
+    # var slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -2250,7 +2250,7 @@ parse-effective-address:  # word-slice : (address slice) -> base/eax, index/ecx,
     # . save registers
     56/push-esi
     57/push-edi
-    # var local-slice/esi : (address slice) = {word-slice->start, word-slice->end}
+    # var local-slice/esi : (ref slice) = {word-slice->start, word-slice->end}
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           6/r32/esi   8/disp8         .                 # copy *(ebp+8) to esi
     ff          6/subop/push        1/mod/*+disp8   6/rm32/esi    .           .             .           .           4/disp8         .                 # push *(esi+4)
     ff          6/subop/push        0/mod/indirect  6/rm32/esi    .           .             .           .           .               .                 # push *esi
@@ -2679,7 +2679,7 @@ next-register:  # in : (address slice) -> reg/eax : int
     56/push-esi
     # esi = in
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           6/r32/esi   8/disp8         .                 # copy *(ebp+8) to esi
-    # var reg-slice/ecx : (address slice) = {in->start, in->start + 3}
+    # var reg-slice/ecx : (ref slice) = {in->start, in->start + 3}
     8b/copy                         0/mod/indirect  6/rm32/esi    .           .             .           0/r32/eax   .               .                 # copy *esi to eax
     05/add-to-eax  3/imm32
     50/push-eax
@@ -3865,7 +3865,7 @@ disp32-mode?:  # in : (address slice) -> reg/eax : boolean
     # . save registers
     56/push-esi
     57/push-edi
-    # var local-slice/esi : (address slice) = {in->start, in->end}
+    # var local-slice/esi : (ref slice) = {in->start, in->end}
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           6/r32/esi   8/disp8         .                 # copy *(ebp+8) to esi
     ff          6/subop/push        1/mod/*+disp8   6/rm32/esi    .           .             .           .           4/disp8         .                 # push *(esi+4)
     ff          6/subop/push        0/mod/indirect  6/rm32/esi    .           .             .           .           .               .                 # push *esi
@@ -3923,7 +3923,7 @@ emit-indirect-disp32:  # out : (address buffered-file), word-slice : (address sl
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
     # . save registers
     56/push-esi
-    # var local-slice/esi : (address slice) = {in->start, in->end}
+    # var local-slice/esi : (ref slice) = {in->start, in->end}
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           6/r32/esi   0xc/disp8       .                 # copy *(ebp+12) to esi
     ff          6/subop/push        1/mod/*+disp8   6/rm32/esi    .           .             .           .           4/disp8         .                 # push *(esi+4)
     ff          6/subop/push        0/mod/indirect  6/rm32/esi    .           .             .           .           .               .                 # push *esi
@@ -4055,8 +4055,8 @@ $next-hex-int:loop:
     e8/call  is-hex-digit?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax == 0) break
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) break
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $next-hex-int:break/disp8
     # eax = from-hex-char(*curr)
     # . . copy arg to eax
@@ -4071,7 +4071,8 @@ $next-hex-int:loop:
     # loop
     eb/jump  $next-hex-int:loop/disp8
 $next-hex-int:break:
-    81          7/subop/compare     3/mod/direct    3/rm32/ebx    .           .             .           .           .               0/imm32           # compare ebx
+    # if (negate?) result = -result
+    81          7/subop/compare     3/mod/direct    3/rm32/ebx    .           .             .           .           .               0/imm32/false     # compare ebx
     74/jump-if-equal  $next-hex-int:end/disp8
 $next-hex-int:negate:
     f7          3/subop/negate      3/mod/direct    7/rm32/edi    .           .             .           .           .               .                 # negate edi
@@ -4437,8 +4438,8 @@ $next-positive-hex-int:loop:
     e8/call  is-hex-digit?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax == 0) break
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) break
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $next-positive-hex-int:end/disp8
     # eax = from-hex-char(*curr)
     # . . copy arg to eax
diff --git a/apps/survey b/apps/survey
index 23eb9e3b..2ec38e5d 100755
--- a/apps/survey
+++ b/apps/survey
Binary files differdiff --git a/apps/survey.subx b/apps/survey.subx
index 8563116f..e365ac1b 100644
--- a/apps/survey.subx
+++ b/apps/survey.subx
@@ -74,8 +74,8 @@ Entry:  # run tests if necessary, convert stdin if not
     e8/call  kernel-string-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto interactive
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto interactive
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $subx-survey-main:interactive/disp8
     # run-tests()
     e8/call  run-tests/disp32
@@ -115,9 +115,9 @@ $subx-survey-main:end:
 
 subx-survey:  # infile : (address buffered-file), out : (address buffered-file)
     # pseudocode
-    #   var in : (address stream byte) = stream(4096)
+    #   var in : (ref stream byte 4096)
     #   slurp(infile, in)
-    #   var segments : (stream segment-info 10)
+    #   var segments : (stream segment-info)
     #   var labels : (stream label-info Max-labels)
     #   compute-offsets(in, segments, labels)
     #   compute-addresses(segments, labels)
@@ -131,13 +131,13 @@ subx-survey:  # infile : (address buffered-file), out : (address buffered-file)
     51/push-ecx
     52/push-edx
     56/push-esi
-    # var segments/ecx = stream(10 * 16)
+    # var segments/ecx : (ref stream {string, segment-info} 160)   # 10 rows * 16 bytes/row
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0xa0/imm32        # subtract from esp
     68/push  0xa0/imm32/length
     68/push  0/imm32/read
     68/push  0/imm32/write
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # var labels/edx = stream(Max-labels * 16)
+    # var labels/edx : (ref stream label-info Max-labels*16)
     # . data
     2b/subtract                     0/mod/indirect  5/rm32/.disp32            .             .           4/r32/esp   Max-labels/disp32                 # subtract *Max-labels from esp
     # . length
@@ -147,7 +147,7 @@ subx-survey:  # infile : (address buffered-file), out : (address buffered-file)
     # . write
     68/push  0/imm32/write
     89/copy                         3/mod/direct    2/rm32/edx    .           .             .           4/r32/esp   .               .                 # copy esp to edx
-    # var in/esi = stream(Input-size * 1)
+    # var in/esi : (ref stream byte Input-size)
     # . data
     2b/subtract                     0/mod/indirect  5/rm32/.disp32            .             .           4/r32/esp   Input-size/disp32                 # subtract *Input-size from esp
     # . length
@@ -618,7 +618,7 @@ compute-offsets:segment-tmp:  # slice
 
 == code
 
-compute-offsets:  # in : (address stream), segments : (address stream {string, segment-info}), labels : (address stream {string, label-info})
+compute-offsets:  # in : (address stream byte), segments : (address stream {string, segment-info}), labels : (address stream {string, label-info})
     # skeleton:
     #   for lines in 'in'
     #     for words in line
@@ -833,8 +833,8 @@ $compute-offsets:case-empty:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) break
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) break
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $compute-offsets:line-loop/disp32
 $compute-offsets:case-comment:
     # if slice-starts-with?(word-slice, "#") continue
@@ -843,8 +843,8 @@ $compute-offsets:case-comment:
     e8/call  slice-starts-with?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax != 0) break
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) break
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $compute-offsets:line-loop/disp32
 $compute-offsets:case-segment-header:
     # if (!slice-equal?(word-slice/edx, "==")) goto next case
@@ -854,8 +854,8 @@ $compute-offsets:case-segment-header:
     e8/call  slice-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto next case
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto next case
+    3d/compare-eax-and  0/imm32/false
     0f 84/jump-if-equal  $compute-offsets:case-label/disp32
     # if (curr-segment-name == 0) goto construct-next-segment
     81          7/subop/compare     3/mod/direct    6/rm32/esi    .           .             .           .           .               0/imm32           # compare esi
@@ -973,8 +973,8 @@ $compute-offsets:update-curr-segment-name:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) abort
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) abort
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $compute-offsets:abort/disp32
     # seg/ebx = get-or-insert(segments, curr-segment-name, row-size=16)
     # . . push args
@@ -1022,8 +1022,8 @@ $compute-offsets:case-label:
     e8/call  is-label?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax == 0) goto next case
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto next case
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $compute-offsets:case-default/disp8
     # strip trailing ':' from word-slice
     ff          1/subop/decrement   1/mod/*+disp8   2/rm32/edx    .           .             .           .           4/disp8         .                 # decrement *(edx+4)
@@ -1219,13 +1219,13 @@ test-compute-offsets:
     e8/call  clear-stream/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # var segments/ecx = stream(2 * 16)
+    # var segments/ecx : (ref stream byte 2*16)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0x20/imm32        # subtract from esp
     68/push  0x20/imm32/length
     68/push  0/imm32/read
     68/push  0/imm32/write
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # var labels/edx = stream(2 * 16)
+    # var labels/edx : (ref stream byte 2*16)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0x20/imm32        # subtract from esp
     68/push  0x20/imm32/length
     68/push  0/imm32/read
@@ -1381,7 +1381,7 @@ test-compute-offsets:
 compute-addresses:  # segments : (address stream {string, segment-info}), labels : (address stream {string, label-info})
     # pseudocode:
     #   srow : (address segment-info) = segments->data
-    #   max = segments->data + segments->write
+    #   max = &segments->data[segments->write]
     #   num-segments = segments->write / 16
     #   starting-offset = 0x34 + (num-segments * 0x20)
     #   while true
@@ -1392,7 +1392,7 @@ compute-addresses:  # segments : (address stream {string, segment-info}), labels
     #     trace-sssns("segment " s->key " starts at address " s->address)
     #     srow += 16  # row-size
     #   lrow : (address label-info) = labels->data
-    #   max = labels->data + labels->write
+    #   max = &labels->data[labels->write]
     #   while true
     #     if (lrow >= max) break
     #     seg-name : (address string) = lrow->segment-name
@@ -1422,7 +1422,7 @@ compute-addresses:  # segments : (address stream {string, segment-info}), labels
     81          0/subop/add         3/mod/direct    7/rm32/edi    .           .             .           .           .               0x34/imm32        # add to edi
     # srow/eax = segments->data
     8d/copy-address                 1/mod/*+disp8   6/rm32/esi    .           .             .           0/r32/eax   0xc/disp8       .                 # copy esi+12 to eax
-    # max/ecx = segments->data + segments->write
+    # max/ecx = &segments->data[segments->write]
     8b/copy                         0/mod/indirect  6/rm32/esi    .           .             .           1/r32/ecx   .               .                 # copy *esi to ecx
     01/add                          3/mod/direct    1/rm32/ecx    .           .             .           6/r32/esi   .               .                 # add esi to ecx
 $compute-addresses:segment-loop:
@@ -1489,7 +1489,7 @@ $compute-addresses:segment-break:
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           6/r32/esi   0xc/disp8       .                 # copy *(ebp+12) to esi
     # lrow/eax = labels->data
     8d/copy-address                 1/mod/*+disp8   6/rm32/esi    .           .             .           0/r32/eax   0xc/disp8       .                 # copy esi+12 to eax
-    # max/ecx = labels->data + labels->write
+    # max/ecx = &labels->data[labels->write]
     8b/copy                         0/mod/indirect  6/rm32/esi    .           .             .           1/r32/ecx   .               .                 # copy *esi to ecx
     01/add                          3/mod/direct    1/rm32/ecx    .           .             .           6/r32/esi   .               .                 # add esi to ecx
 $compute-addresses:label-loop:
@@ -1621,13 +1621,13 @@ test-compute-addresses:
     55/push-ebp
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
     # setup
-    # . var segments/ecx = stream(10 * 16)
+    # . var segments/ecx : (ref stream byte 10*16)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0xa0/imm32        # subtract from esp
     68/push  0xa0/imm32/length
     68/push  0/imm32/read
     68/push  0/imm32/write
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # . var labels/edx = stream(512 * 16)
+    # . var labels/edx : (ref stream byte 512*16)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0x2000/imm32      # subtract from esp
     68/push  0x2000/imm32/length
     68/push  0/imm32/read
@@ -1790,13 +1790,13 @@ test-compute-addresses-large-segments:
     55/push-ebp
     89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
     # setup
-    # . var segments/ecx = stream(10 * 16)
+    # . var segments/ecx : (ref stream byte 10*16)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0xa0/imm32        # subtract from esp
     68/push  0xa0/imm32/length
     68/push  0/imm32/read
     68/push  0/imm32/write
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # . var labels/edx = stream(512 * 16)
+    # . var labels/edx : (ref stream byte 512*16)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0x2000/imm32      # subtract from esp
     68/push  0x2000/imm32/length
     68/push  0/imm32/read
@@ -1871,7 +1871,7 @@ test-compute-addresses-large-segments:
     5d/pop-to-ebp
     c3/return
 
-emit-output:  # in : (address stream), out : (address buffered-file), segments : (address stream {string, segment-info}), labels : (address stream {string, label-info})
+emit-output:  # in : (address stream byte), out : (address buffered-file), segments : (address stream {string, segment-info}), labels : (address stream {string, label-info})
     # pseudocode:
     #   emit-headers(out, segments, labels)
     #   emit-segments(in, out, segments, labels)
@@ -1922,7 +1922,7 @@ $emit-output:end:
     5d/pop-to-ebp
     c3/return
 
-emit-segments:  # in : (address stream), out : (address buffered-file), segments : (address stream {string, segment-info}), labels : (address stream {string, label-info})
+emit-segments:  # in : (address stream byte), out : (address buffered-file), segments : (address stream {string, segment-info}), labels : (address stream {string, label-info})
     # pseudocode:
     #   var offset-of-next-instruction = 0
     #   var line : (stream byte 512)
@@ -1993,11 +1993,11 @@ emit-segments:  # in : (address stream), out : (address buffered-file), segments
     68/push  0/imm32/read
     68/push  0/imm32/write
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # var word-slice/edx = {0, 0}
+    # var word-slice/edx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    2/rm32/edx    .           .             .           4/r32/esp   .               .                 # copy esp to edx
-    # var datum/edi = {0, 0}
+    # var datum/edi : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    7/rm32/edi    .           .             .           4/r32/esp   .               .                 # copy esp to edi
@@ -2139,8 +2139,8 @@ $emit-segments:check-for-label:
     e8/call  is-label?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) break
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) break
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-segments:line-loop/disp32
 $emit-segments:check-for-segment-header:
     # if (slice-equal?(word-slice, "==")) break
@@ -2152,8 +2152,8 @@ $emit-segments:check-for-segment-header:
     e8/call  slice-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax != 0) break
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) break
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-segments:line-loop/disp32
 $emit-segments:2-character:
     # if (length(word-slice) != 2) goto next check
@@ -2275,8 +2275,8 @@ $emit-segments:check-global-variable:
     e8/call  string-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax != 0) goto code label checks
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) goto code label checks
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-segments:check-code-label-for-imm8/disp32
 $emit-segments:check-global-variable-for-disp8:
     # if has-metadata?(word-slice, "disp8") abort
@@ -2288,8 +2288,8 @@ $emit-segments:check-global-variable-for-disp8:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax != 0) abort
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) abort
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-segments:global-variable-abort/disp32
 $emit-segments:check-global-variable-for-imm8:
     # if has-metadata?(word-slice, "imm8") abort
@@ -2301,8 +2301,8 @@ $emit-segments:check-global-variable-for-imm8:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax != 0) abort
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) abort
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-segments:global-variable-abort/disp32
 $emit-segments:emit-global-variable:
     # emit-hex(out, info->address, 4)
@@ -2326,8 +2326,8 @@ $emit-segments:check-code-label-for-imm8:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax != 0) abort
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) abort
+    3d/compare-eax-and  0/imm32/false
     0f 85/jump-if-not-equal  $emit-segments:imm8-abort/disp32
 $emit-segments:check-code-label-for-imm32:
     # if (!has-metadata?(word-slice, "imm32")) goto next check
@@ -2339,7 +2339,7 @@ $emit-segments:check-code-label-for-imm32:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto next check
+    # . if (eax == false) goto next check
     3d/compare-eax-and  0/imm32
     74/jump-if-equal  $emit-segments:check-code-label-for-disp8/disp8
 #?     # dump info->address {{{
@@ -2397,8 +2397,8 @@ $emit-segments:check-code-label-for-disp8:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto next check
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto next check
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $emit-segments:check-code-label-for-disp32/disp8
 $emit-segments:emit-code-label-disp8:
     # emit-hex(out, info->offset - offset-of-next-instruction, 1)
@@ -2424,8 +2424,8 @@ $emit-segments:check-code-label-for-disp32:
     e8/call  has-metadata?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) abort
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) abort
+    3d/compare-eax-and  0/imm32/false
     0f 84/jump-if-equal  $emit-segments:abort/disp32
 $emit-segments:emit-code-label-disp32:
     # emit-hex(out, info->offset - offset-of-next-instruction, 4)
@@ -2577,13 +2577,13 @@ test-emit-segments-global-variable:
     e8/call  clear-stream/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . var segments/ecx = stream(10 * 16)
+    # . var segments/ecx : (ref stream byte 10*16)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0xa0/imm32        # subtract from esp
     68/push  0xa0/imm32/length
     68/push  0/imm32/read
     68/push  0/imm32/write
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # . var labels/edx = stream(512 * 16)
+    # . var labels/edx : (ref stream byte 512*16)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0x2000/imm32      # subtract from esp
     68/push  0x2000/imm32/length
     68/push  0/imm32/read
@@ -2814,13 +2814,13 @@ test-emit-segments-code-label:
     e8/call  clear-stream/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . var segments/ecx = stream(10 * 16)
+    # . var segments/ecx : (ref stream byte 10*16)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0xa0/imm32        # subtract from esp
     68/push  0xa0/imm32/length
     68/push  0/imm32/read
     68/push  0/imm32/write
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # . var labels/edx = stream(512 * 16)
+    # . var labels/edx : (ref stream byte 512*16)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0x2000/imm32      # subtract from esp
     68/push  0x2000/imm32/length
     68/push  0/imm32/read
@@ -3016,13 +3016,13 @@ test-emit-segments-code-label-absolute:
     e8/call  clear-stream/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . var segments/ecx = stream(10 * 16)
+    # . var segments/ecx : (ref stream byte 10*16)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0xa0/imm32        # subtract from esp
     68/push  0xa0/imm32/length
     68/push  0/imm32/read
     68/push  0/imm32/write
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # . var labels/edx = stream(512 * 16)
+    # . var labels/edx : (ref stream byte 512*16)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0x2000/imm32      # subtract from esp
     68/push  0x2000/imm32/length
     68/push  0/imm32/read
@@ -3177,7 +3177,7 @@ emit-headers:  # out : (address buffered-file), segments : (address stream {stri
     # pseudocode:
     #   emit-elf-header(out, segments, labels)
     #   curr-segment = segments->data
-    #   max = segments->data + segments->write
+    #   max = &segments->data[segments->write]
     #   while true
     #     if (curr-segment >= max) break
     #     emit-elf-program-header-entry(out, curr-segment)
@@ -3213,7 +3213,7 @@ emit-headers:  # out : (address buffered-file), segments : (address stream {stri
     8b/copy                         0/mod/indirect  0/rm32/eax    .           .             .           1/r32/ecx   .               .                 # copy *eax to ecx
     # curr-segment/eax = segments->data
     8d/copy-address                 1/mod/*+disp8   0/rm32/eax    .           .             .           0/r32/eax   0xc/disp8       .                 # copy eax+12 to eax
-    # max/ecx = segments->data + segments->write
+    # max/ecx = &segments->data[segments->write]
     01/add                          3/mod/direct    1/rm32/ecx    .           .             .           0/r32/eax   .               .                 # add eax to ecx
 $emit-headers:loop:
     # if (curr-segment >= max) break
@@ -3431,8 +3431,8 @@ emit-elf-program-header-entry:  # out : (address buffered-file), curr-segment :
     e8/call  string-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto next check
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto next check
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $emit-elf-program-header-entry:data/disp8
     # *$Elf_p_flags = r-x
     c7          0/subop/copy        0/mod/indirect  5/rm32/.disp32            .             .           .           $Elf_p_flags/disp32  5/imm32      # copy to *$Elf_p_flags
@@ -3479,12 +3479,12 @@ stream-add4:  # in : (address stream byte), key : address, val1 : address, val2
     56/push-esi
     # esi = in
     8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           6/r32/esi   8/disp8         .                 # copy *(ebp+8) to esi
-    # curr/eax = in->data + in->write
+    # curr/eax = &in->data[in->write]
     # . eax = in->write
     8b/copy                         0/mod/indirect  6/rm32/esi    .           .             .           0/r32/eax   .               .                 # copy *esi to eax
     # . eax = esi+eax+12
     8d/copy-address                 1/mod/*+disp8   4/rm32/sib    6/base/esi  0/index/eax   .           0/r32/eax   0xc/disp8       .                 # copy esi+eax+12 to eax
-    # max/edx = in->data + in->length
+    # max/edx = &in->data[in->length]
     # . edx = in->length
     8b/copy                         1/mod/*+disp8   6/rm32/esi    .           .             .           2/r32/edx   8/disp8         .                 # copy *(esi+8) to edx
     # . edx = esi+edx+12
@@ -3830,7 +3830,7 @@ test-trace-slsls:
     8b/copy                         0/mod/indirect  0/rm32/eax    .           .             .           1/r32/ecx   .               .                 # copy *eax to ecx
     8d/copy-address                 1/mod/*+disp8   4/rm32/sib    0/base/eax  1/index/ecx   .           1/r32/ecx   4/disp8         .                 # copy eax+ecx+4 to ecx
     05/add-to-eax  4/imm32
-    # var b/ebx : (address slice) = {eax, ecx}
+    # var b/ebx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/copy                         3/mod/direct    3/rm32/ebx    .           .             .           4/r32/esp   .               .                 # copy esp to ebx
@@ -3839,7 +3839,7 @@ test-trace-slsls:
     8b/copy                         0/mod/indirect  0/rm32/eax    .           .             .           1/r32/ecx   .               .                 # copy *eax to ecx
     8d/copy-address                 1/mod/*+disp8   4/rm32/sib    0/base/eax  1/index/ecx   .           1/r32/ecx   4/disp8         .                 # copy eax+ecx+4 to ecx
     05/add-to-eax  4/imm32
-    # var d/edx : (address slice) = {eax, ecx}
+    # var d/edx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/copy                         3/mod/direct    2/rm32/edx    .           .             .           4/r32/esp   .               .                 # copy esp to edx
@@ -3955,7 +3955,7 @@ test-trace-slsns:
     8b/copy                         0/mod/indirect  0/rm32/eax    .           .             .           1/r32/ecx   .               .                 # copy *eax to ecx
     8d/copy-address                 1/mod/*+disp8   4/rm32/sib    0/base/eax  1/index/ecx   .           1/r32/ecx   4/disp8         .                 # copy eax+ecx+4 to ecx
     05/add-to-eax  4/imm32
-    # var b/ebx : (address slice) = {eax, ecx}
+    # var b/ebx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/copy                         3/mod/direct    3/rm32/ebx    .           .             .           4/r32/esp   .               .                 # copy esp to ebx
@@ -4071,7 +4071,7 @@ test-trace-slsss:
     8b/copy                         0/mod/indirect  0/rm32/eax    .           .             .           1/r32/ecx   .               .                 # copy *eax to ecx
     8d/copy-address                 1/mod/*+disp8   4/rm32/sib    0/base/eax  1/index/ecx   .           1/r32/ecx   4/disp8         .                 # copy eax+ecx+4 to ecx
     05/add-to-eax  4/imm32
-    # var b/ebx : (address slice) = {eax, ecx}
+    # var b/ebx : (ref slice) = {eax, ecx}
     51/push-ecx
     50/push-eax
     89/copy                         3/mod/direct    3/rm32/ebx    .           .             .           4/r32/esp   .               .                 # copy esp to ebx
@@ -4125,7 +4125,7 @@ test-trace-slsss:
     5d/pop-to-ebp
     c3/return
 
-num-bytes:  # line : (address stream) -> eax : int
+num-bytes:  # line : (address stream byte) -> eax : int
     # pseudocode:
     #   result = 0
     #   while true
@@ -4150,7 +4150,7 @@ num-bytes:  # line : (address stream) -> eax : int
     53/push-ebx
     # var result/eax = 0
     31/xor                          3/mod/direct    0/rm32/eax    .           .             .           0/r32/eax   .               .                 # clear eax
-    # var word-slice/ecx = {0, 0}
+    # var word-slice/ecx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
@@ -4247,8 +4247,8 @@ $num-bytes:check0:
     e8/call  slice-empty?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax != 0) break
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) break
+    3d/compare-eax-and  0/imm32/false
     # . restore result now that ZF is set
     58/pop-to-eax
     75/jump-if-not-equal  $num-bytes:end/disp8
@@ -4284,8 +4284,8 @@ $num-bytes:check-for-segment-header:
     e8/call  slice-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax != 0) break
-    3d/compare-eax-and  0/imm32
+    # . if (eax != false) break
+    3d/compare-eax-and  0/imm32/false
     # . restore result now that ZF is set
     58/pop-to-eax
     75/jump-if-not-equal  $num-bytes:end/disp8
diff --git a/apps/tests b/apps/tests
index dd75aac1..b292f93b 100755
--- a/apps/tests
+++ b/apps/tests
Binary files differdiff --git a/apps/tests.subx b/apps/tests.subx
index f31f4d16..1d00cf30 100644
--- a/apps/tests.subx
+++ b/apps/tests.subx
@@ -43,8 +43,8 @@ Entry:  # run tests if necessary, convert stdin if not
     e8/call  kernel-string-equal?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) goto run-main
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) goto run-main
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $subx-tests-main:interactive/disp8
     # run-tests()
     e8/call  run-tests/disp32
@@ -101,13 +101,13 @@ subx-gen-run-tests:  # in : (address buffered-file), out : (address buffered-fil
     52/push-edx
     53/push-ebx
     57/push-edi
-    # var line/ecx : (address stream byte) = stream(512)
+    # var line/ecx : (ref stream byte 512)
     81          5/subop/subtract    3/mod/direct    4/rm32/esp    .           .             .           .           .               0x200/imm32       # subtract from esp
     68/push  0x200/imm32/length
     68/push  0/imm32/read
     68/push  0/imm32/write
     89/copy                         3/mod/direct    1/rm32/ecx    .           .             .           4/r32/esp   .               .                 # copy esp to ecx
-    # var word-slice/edx = {0, 0}
+    # var word-slice/edx : (ref slice)
     68/push  0/imm32/end
     68/push  0/imm32/start
     89/copy                         3/mod/direct    2/rm32/edx    .           .             .           4/r32/esp   .               .                 # copy esp to edx
@@ -178,8 +178,8 @@ $subx-gen-run-tests:check-for-label:
     e8/call  is-label?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
-    # . if (eax == 0) continue
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) continue
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $subx-gen-run-tests:continue/disp8
 $subx-gen-run-tests:check-label-prefix:
     # strip trailing ':' from word-slice
@@ -192,8 +192,8 @@ $subx-gen-run-tests:check-label-prefix:
     e8/call  slice-starts-with?/disp32
     # . . discard args
     81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
-    # . if (eax == 0) break
-    3d/compare-eax-and  0/imm32
+    # . if (eax == false) break
+    3d/compare-eax-and  0/imm32/false
     74/jump-if-equal  $subx-gen-run-tests:continue/disp8
 $subx-gen-run-tests:call-test-function:
     # tests-found? = true
@@ -242,7 +242,7 @@ $subx-gen-run-tests:continue:
     e9/jump  $subx-gen-run-tests:loop/disp32
 $subx-gen-run-tests:break:
     # if (!tests-found?) goto end
-    81          7/subop/compare     3/mod/direct    3/rm32/ebx    .           .             .           .           .               0/imm32           # compare ebx
+    81          7/subop/compare     3/mod/direct    3/rm32/ebx    .           .             .           .           .               0/imm32/false     # compare ebx
     74/jump-if-equal  $subx-gen-run-tests:end/disp8
     # write(new-code-segment, "  c3/return\n")
     # . . push args