paperspec/spec/04-identity.md

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).

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). 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).

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).
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.