README updates

chapter02/README.md

@@ -42,6 +42,18 @@ We extend the set of nodes by adding following additional node types.
 | Div       | Data | Divide a value by another     | Two data nodes, values are divided, order matters          | Result of the division      |
 | Minus     | Data | Negate a value                | One data node, value is negated                            | Result of the unary minus   |
 
+
+## *Value* equality vs *Reference* equality
+
+In much of Simple, Nodes are looked up (`find()` calls) via *reference*
+equality.  This is by far the most common case.  In [Chapter
+9](../chapter09/README.md) we introduce *value* equality for the first time.
+In both cases the choice of value-vs-reference equality is intentional: it is
+*never* correct to "just pick one or the other kind of equality".  When in
+doubt check the context: only *Global Value Numbering* uses value equality;
+everywhere we mean reference equality.
+
+
 ## Peephole Optimizations
 
 Nodes in the graph can be peephole-optimized.  The graph is viewed through a
@@ -141,6 +153,7 @@ starting in [Chapter 4](../chapter04/README.md) and [Chapter
 There are other important properties of the Lattice that we discuss in [Chapter
 4](../chapter04/README.md) and [Chapter 10](../chapter10/README.md), such as the "meet" and "join" operators and their rules.
 
+
 ## Nodes Pre Peephole Optimization
 
 The following visual shows how the graph looks like pre-peephole optimization:
@@ -152,10 +165,12 @@ The following visual shows how the graph looks like pre-peephole optimization:
 * The edges from Constants to Start are shown in dotted lines as these are not true control edges
 * We label each edge with its position in the node's list of inputs.
 
+
 ## Post-peephole
 
 ![Example Visual](./docs/02-post-peephole-ex1.svg)
 
+
 ## Demonstration
 To demonstrate how the optimisation works, let's consider the following code:
 ```

chapter09/README.md

@@ -48,6 +48,14 @@ get the same result - and can be shared.
   constant 17 is not the same as 99, but both are the same `ConstantNode` class
   and label.  The `eq` and `hash` calls check (or hash) these extra bits.
 
+Note the intentional *value* equality here.  In many places in Simple we use
+*reference* equality - e.g. node/edge maintenance is via reference equality, not
+value equality, so e.g. the `Utils.find()` call finds via reference.  Through
+out the Simple project whenever a Node lookup is happening, beware if its via
+*value* or *reference* equality; this is not always explicitly called out but
+should be obvious from context.
+
+
 Since we edit the graph a lot, Nodes can have their inputs change which changes
 their hash which means they can't be found in the GVN table.  E.g. we swap out
 the `Add` for a `Con` in: