Initial draft text re annotations

preserves.md

@@ -25,7 +25,8 @@ programming languages.
 
 Preserves also supports the usual suite of atomic and compound data
 types, in particular including *binary* data as a distinct type from
-text strings.
+text strings. Its *annotations* allow separation of data from metadata
+such as comments, trace information, and provenance information.
 
 Finally, Preserves defines precisely how to *compare* two values.
 Comparison is based on the data model, not on syntax or on data
@@ -389,6 +390,34 @@ prefixing a `ByteString` containing the binary representation of the
     structure at all. It would be incoherent to expect to be able to
     access the representation of the text from within the text itself.
 
+### Annotations.
+
+When written down, a `Value` may have an associated sequence of
+*annotations* carrying “out-of-band” contextual metadata about the
+value. Each annotation is, in turn, a `Value`, and may itself have
+annotations.
+
+            Value =/ ws "@" Value Value
+
+Each annotation is preceded by `@`; the underlying annotated value
+follows its annotations.
+
+Annotations appear within syntax denoting a `Value`; however, the
+annotations are not part of the denoted value. They are only part of
+the syntax. Annotations do not play a part in equivalences and
+orderings of `Value`s.
+
+Reflective tools such as debuggers, user interfaces, and message
+routers and relays---tools which process `Value`s generically---may
+use annotated inputs to tailor their operation, or may insert
+annotations in their outputs. By contrast, in ordinary programs, as a
+rule of thumb, the presence, absence or specific value of an
+annotation should not change the control flow or output of the
+program. Annotations are data *describing* `Value`s, and are not in
+the domain of any specific application of `Value`s. That is, an
+annotation will almost never cause a non-reflective program to do
+anything observably different.
+
 ## Compact Binary Syntax
 
 A `Repr` is an encoding, or representation, of a specific `Value`.