Add meta alloc docs, do code and doc cleanup.

1 files changed, 16 insertions, 11 deletions

diff --git a/doc/0/0-value.md b/doc/0/0-value.md
index b84a528..61d01d9 100644
--- a/doc/0/0-value.md
+++ b/doc/0/0-value.md
@@ -135,6 +135,13 @@ different unit sizes.  For instance, `istr` (interned string) pointers may use
 byte-addressing, meaning the 32-bit index limits the `istr` heap to 4 GiB only,
 while list pointers use 64-bit (8-byte) addressing, allowing for a 32 GiB heap.
 
+Note: The separation of heaps is a possibility, not a guarantee.  In practice,
+the various 32-bit indexes may share a single value domain, in which case list
+pointers, heap pointers, etc. would never have equal 32-bit index values; they
+may or may not, depending on current implementation details.  The unit size of
+each type of 32-bit index is also not guaranteed, but is at least 8 bytes for
+list pointers, since a list must contain at least one 64-bit Zisp Value.
+
 ### List pointers
 
 In Zisp, a list is a contiguous array of a fixed number of Values.  To improve
@@ -156,12 +163,12 @@ lists can't needlessly trigger the code branch that handles list pointers.
 Note that "list pointer" and "list heap" are slightly misleading terms, since
 arbitrary-length lists can be allocated on the main heap as Array objects with
 element type Value.  In this case, they are represented by a main heap pointer,
-and the generic list API hides the difference.
+and a generic list API may hide the difference.
 
 ### Heap pointers
 
 Regular heap objects are represented by this pointer type, which uses a 32-bit
-index into the main heap, in the lower portion of the 48-bit payload.
+heap index in the lower portion of the 48-bit payload.
 
 Of the 16 high bits of the payload, the upper 8 are used to immediately encode
 the type of the heap object, and the remaining 8 are used for internal metadata
@@ -171,8 +178,10 @@ This means our 64-bit Values can be checked against heap types by comparing the
 24 high bits to a combined constant: the 16 high bits that indicate it's a main
 heap index, plus 8 more bits encoding a specific heap type.
 
-Some heap types may actually reside in their own separate heap, meaning the
-32-bit index may refer to yet another memory region rather than the main heap.
+Different types may reside in different heaps, meaning the 32-bit index values
+of different heap types may or may not share value domains.  The index value of
+two heap pointers, of different types, being equal, is neither a guarantee that
+they share a memory location, nor is it ruled out.
 
 ### String pointers
 
@@ -180,13 +189,9 @@ An `istr` is a string of up to 255 arbitrary bytes, that is typically interned,
 fulfilling a similar purpose to symbols in Lisp and Scheme.  If uninterned, we
 could consider the 'i' to mean *intermediate* length string instead.
 
-Of the 48-bit payload value, the lower 32 bits are an offset into a dedicated
-virtual memory region for this type only, bounding total memory use to 4 GiB,
-which should be more than enough.
-
-The higher 16 bits of the payload are divided in two halves.  The upper 8 bits
-directly encode the length, which cannot be zero; the lower 8 bits are used for
-garbage collection metadata.
+Of the 48-bit payload value, the low 32 bits are a heap index, while the higher
+16 bits are divided into 8 high bits for a non-zero length, and 8 low bits for
+internal metadata such as for garbage collection.
 
 The empty string is represented as a *short string* instead; see below.