Initial commit

spec/04-identity.md

@@ -0,0 +1,73 @@
+# 4. Identity
+
+A node's ID is a name, not a position.
+It carries no meaning, and once a document is established it is never recomputed, reassigned or reused.
+
+## 4.1 Letter-first base32
+
+To encode a SHA-256 digest *d* (32 bytes) as a letter-first ID of *n* characters:
+
+1. The first character is the letter at index `d[0] mod 22` of `abcdefghjkmnpqrstvwxyz`.
+2. Read the bytes `d[1]` to `d[31]` as one big-endian bit string.
+3. Each further character is the Crockford character for the next five bits, from the most significant end.
+
+Node IDs have seven characters, about 34.5 bits; derived record IDs have 13.
+`ids.jsonl` in the vectors gives digests and their encodings.
+
+## 4.2 Minting node IDs
+
+A node's ID is minted from SHA-256 of the canonical JSON of the array `["scienting-id/1", doc_key, kind, text_hash, occurrence]`, encoded with seven characters.
+`text_hash` is the plain, never keyed, text hash of the node ([5.1](05-hashes.md#51-the-five-values)).
+
+When a document is established, nodes are minted in document order.
+A node's occurrence starts at the number of earlier nodes with the same kind and text hash; while the resulting ID is already taken, the occurrence increases by one.
+So a fresh conversion of the same input mints the same IDs.
+
+A node added later, by an `insert` or a `split`, starts at occurrence 0 and increases while the ID is taken by any live, retired or alias ID of the document.
+
+Columns and figure-text items are not nodes, but they take IDs from the same rule and the same document-wide set, after the nodes:
+a column with kind `column` and the text hash of its header cells' plain projections joined with U+0020;
+a figure-text item with kind `figure-text` and the text hash of its text.
+
+## 4.3 Permanence, retirement and aliases
+
+| Rule | Detail |
+| --- | --- |
+| Permanence | Once established, an ID never changes, and no other node ever takes it. |
+| Retirement | A `merge` or a `delete` retires IDs ([11](11-corrections.md)). A merge records the surviving node as the successor; a delete records none. |
+| Aliases | Legacy IDs, such as the `b-p03-text-004` block IDs Lode's extracts use today, are recorded as aliases of the node that now holds that text. |
+| Labels | What people say, such as "Eq. 3" or "Table S1", is a `label`, never an ID. |
+| Display paths | Tools may show a path such as `§2.3 ¶4 s2`; it is never stored or cited. |
+
+## 4.4 `ids.jsonl`
+
+Each line is one entry.
+
+| Property | Holds |
+| --- | --- |
+| `id` | The retired node ID, or the alias. |
+| `kind` | `retired` or `alias`. |
+| `successor` | For a retirement, the successor's ID, or null for a deletion; for an alias, the live node it names. |
+| `node_kind` | For a retirement, the kind the node had. |
+| `rev` | For a retirement, the index of the correction that retired it. |
+
+Aliases come first, sorted by ID; retirements follow, sorted by `rev` and then ID.
+No ID is both live and in the table, every successor is live or itself in the table, and every alias names a live node.
+
+## 4.5 Store-qualified names
+
+A document key qualified by its store, `smithlab/cornell1995second`, names a document anywhere, and an address with a store names a node anywhere ([6.1](06-anchors.md#61-addresses)).
+
+## 4.6 Record IDs
+
+A record that is never edited takes its ID from its own content, as 13 letter-first characters of a hash:
+
+| Record | Hash |
+| --- | --- |
+| Receipt, revocation, policy | The record hash: SHA-256 of the record without `id` and `signature` ([8.4](08-fidelity.md#84-record-hashes-and-signatures)). |
+| Correction | SHA-256 of the record without `id`. |
+| Annotation | SHA-256 of the annotation without `id`, `status`, `receipt` and `modified`, as created. |
+| Submission, digitization | SHA-256 of the record without `id`. |
+
+A witness ID is the seven-character letter-first encoding of the witness's SHA-256 itself.
+Other records, such as layers and qa reports, MAY use any record ID unique in their store.