Add section about uniqueness and UUIDs to units design doc

design/units.md

@@ -29,7 +29,40 @@ there is an additional directory in the search path, such as
 `/usr/local/include/fspl`, then the unit will be searched for in each one (in
 order) until it is found.
 
-Module UUIDs are not used in addressing.
+## Uniqueness
+
+Each unit is uniqued by a UUID. Most users will never directly use UUIDs, but
+they are essential in order to prevent name collisions within the compiler or
+linker. For modules, the UUID is specified in the metadata file. For other
+units, the UUID is a UUIDv3 (md5) generated using the zero-UUID as a namespace
+and the basename of the file (with the extension) as the data.
+
+When creating a module, a UUID should be randomly generated for it. Keep in mind
+that altering the UUID of a library will cause programs that used to dynamically
+load it to no longer function until they are re-compiled. Therefore, UUIDs
+should only be altered if you are introducing breaking ABI changes to your
+library. If you are forking an existing module and making changes to it, a
+similar rule applies: only keep the same UUID if you intend on keeping an
+entirely backwards compatible ABI.
+
+Built-in entities that can be accessed globally from any module (such as the
+`String` type) are given a zero-UUID, which represents the "global" unit.
+Anything that is a part of this unit is accesisble from any other unit, without
+having to use a nickname to refer to it.
+
+When generating code, top-level entities must be named like this if their link
+name was not specified manually:
+
+`<hash>::<name>`
+
+Where `<hash>` is the base64 encoding of the UUID with no padding. For example,
+the built-in String type would be assigned the following link name:
+
+`AAAAAAAAAAAAAAAAAAAAAA==::String`
+
+And a type `Bird` in a lone source file with the name `bird.fspl` would be:
+
+`eT/CnSopFDlFwpDCnSEAThjDsBw=::Bird`
 
 ## Module Structure