--- /dev/null
+# heap
+
+a heap is allocated at the start, and the address to the next free
+space on it is stored in `heap_start`. it needs to be
+updated/decremented whenever you put anything on the heap
+
+# closures
+
+* lambda: actual function containing the code
+* closure: reference to the lambda containing captives
+
+closures are stored on the heap. They contain the address to the
+lambda along with any "captives", i.e. captured variables. They have
+the following layout:
+
+```
+0 8 16 24 32
+lambda code 1st 2nd 3rd
+address captive captive captive ...
+```
+
+# lambdas
+
+lambdas use the system v amd64 calling convention.
+
+* param 0: the start address of the **1st** captive
+* param 1...n: the remaining, regular args.
+
+e.g.
+```
+(let [(x 42)] (lambda (y) (+ x y)))
+```
+
+* param 0: pointer to the value of `x`
+* param 1: the value of`y`