formalize file system objects

convention: describe every data type in prose, and illustrate with
a class diagram, and a textual representation of an abstract
data type.

right now we save ourselves the trouble of doing class diagrams, we can
add them later. but they are important.

1 files changed, 18 insertions, 7 deletions

diff --git a/doc/manual/src/architecture/store/objects.md b/doc/manual/src/architecture/store/objects.md
index d7a27b528..7f341c87c 100644
--- a/doc/manual/src/architecture/store/objects.md
+++ b/doc/manual/src/architecture/store/objects.md
@@ -6,31 +6,42 @@ A store object is the pair of
   - a [file system object](#file-system-object)
   - a set of [references](#reference) to store objects.
 
+We call a store object's outermost file system object the *root*.
+
+```haskell
+data StoreOject = StoreObject {
+  root       :: FileSystemObject
+, references :: Set StoreObject
+}
+```
+
 ## File system object {#file-system-object}
 
 The Nix store uses a simple file system model.
 
-    data FileSystemObject
-      = File Executable Contents
-      | Directory (Map FileName FileSystemObject)
-      | SymLink Path
-
 Every file system object is one of the following:
  - File: an executable flag, and arbitrary data for contents
  - Directory: mapping of names to child file system objects
  - [Symbolic link](https://en.m.wikipedia.org/wiki/Symbolic_link): may point anywhere.
 
-   In particular, symlinks pointing outside of their own root file system object, or to a store object without a matching reference, are allowed, but might not function as intended.
+```haskell
+data FileSystemObject
+  = File { isExecutable :: Bool, contents :: Bytes }
+  | Directory { entries ::  Map FileName FileSystemObject }
+  | SymLink { target :: Path }
+```
 
 A bare file or symlink can be a root file system object.
 
+Symlinks pointing outside of their own root, or to a store object without a matching reference, are allowed, but might not function as intended.
+
 ## Reference {#reference}
 
 A store object can refer to other store objects or itself.
 
 Nix collects these references by scanning file contents for [store paths](./paths.md) when a new store object is created.
 
-While references could be arbitrary paths, Nix requires them to be store paths to ensure correctness:
+While references could be arbitrary paths, Nix requires them to be store paths to ensure correctness.
 Anything outside a given store is not under control of Nix, and therefore cannot be guaranteed to be present when needed.
 
 However, having references match store paths in files is not enforced by the data model: