- * as much as makes sense. Note that I took some liberty in matching
- * the reserved prefix values to notmuch concepts, (for example, 'G'
- * is documented as "newsGroup (or similar entity - e.g. a web forum
- * name)", for which I think the thread is the closest analogue in
- * notmuch. This in spite of the fact that we will eventually be
- * storing mailing-list messages where 'G' for "mailing list name"
- * might be even a closer analogue. I'm treating the single-character
- * prefixes preferentially for core notmuch concepts (which will be
- * nearly universal to all mail messages).
+ * Database metadata
+ * -----------------
+ * Xapian allows us to store arbitrary name-value pairs as
+ * "metadata". We currently use the following metadata names with the
+ * given meanings:
+ *
+ * version The database schema version, (which is distinct
+ * from both the notmuch package version (see
+ * notmuch --version) and the libnotmuch library
+ * version. The version is stored as an base-10
+ * ASCII integer. The initial database version
+ * was 1, (though a schema existed before that
+ * were no "version" database value existed at
+ * all). Successive versions are allocated as
+ * changes are made to the database (such as by
+ * indexing new fields).
+ *
+ * features The set of features supported by this
+ * database. This consists of a set of
+ * '\n'-separated lines, where each is a feature
+ * name, a '\t', and compatibility flags. If the
+ * compatibility flags contain 'w', then the
+ * opener must support this feature to safely
+ * write this database. If the compatibility
+ * flags contain 'r', then the opener must
+ * support this feature to read this database.
+ * Introduced in database version 3.
+ *
+ * last_thread_id The last thread ID generated. This is stored
+ * as a 16-byte hexadecimal ASCII representation
+ * of a 64-bit unsigned integer. The first ID
+ * generated is 1 and the value will be
+ * incremented for each thread ID.
+ *
+ * C* metadata keys starting with C indicate
+ * configuration data. It can be managed with the
+ * n_database_*config* API. There is a convention
+ * of hierarchical keys separated by '.' (e.g.
+ * query.notmuch stores the value for the named
+ * query 'notmuch'), but it is not enforced by the
+ * API.
+ *
+ * Obsolete metadata
+ * -----------------
+ *
+ * If ! NOTMUCH_FEATURE_GHOSTS, there are no ghost mail documents.
+ * Instead, the database has the following additional database
+ * metadata:
+ *
+ * thread_id_* A pre-allocated thread ID for a particular
+ * message. This is actually an arbitrarily large
+ * family of metadata name. Any particular name is
+ * formed by concatenating "thread_id_" with a message
+ * ID (or the SHA1 sum of a message ID if it is very
+ * long---see description of 'id' in the mail
+ * document). The value stored is a thread ID.
+ *
+ * These thread ID metadata values are stored
+ * whenever a message references a parent message
+ * that does not yet exist in the database. A
+ * thread ID will be allocated and stored, and if
+ * the message is later added, the stored thread
+ * ID will be used (and the metadata value will
+ * be cleared).
+ *
+ * Even before a message is added, it's
+ * pre-allocated thread ID is useful so that all
+ * descendant messages that reference this common
+ * parent can be recognized as belonging to the
+ * same thread.