IncrementalGraph last node index
Purpose
last_node_index is the greatest local allocation index durably retired
from future use. It is a monotonic allocation watermark — not a count of
existing nodes and not a count of committed materialized nodes.
Storage location
rendered/r/global/last_node_index
In the LevelDB live database, this lives at the active replica's global
sublevel under the key "last_node_index".
Initial value
A fresh replica starts with last_node_index = 0. The first allocated
node identifier uses index 1.
Format
The value is a non-negative JSON integer.
Allocation behavior
When allocating new node identifiers, the next available index is
derived from the current last_node_index watermark:
const nextIndex = reserveNextNodeIndex(); // increments atomic volatile counter
const id = `${nextIndex.toString(36)}-${fingerprint}`;
The index prefix is base36 without padding or alignment:
1-abcdefghi
2-abcdefghi
z-abcdefghi
10-abcdefghi
Gaps
Gaps are acceptable and expected:
- If a transaction fails before durable commit, its uncommitted allocation does not leak into the persisted lookup or volatile committed state.
- Failed transactions consume an index value, creating a gap.
- Concurrent transactions that allocate indices and commit out of order can create gaps.
last_node_indexis the watermark of the largest index known to be retired; indices below it may not correspond to any materialized node.
Synchronization semantics
During normal synchronization, last_node_index is local allocation metadata
and is preserved from the receiver. A host's last_node_index belongs to
that host's fingerprint namespace and is not adopted.
Numeric indices are meaningful only together with their allocation fingerprint. Two hosts may safely allocate the same numeric index because the resulting node identifiers contain different fingerprints. Consequently, a host watermark must not advance or retire indices in the local fingerprint namespace.
When foreign Journal history is imported, the receiver's own
last_node_index is preserved. A higher host last_node_index does not
change that value. Differences in the host's last_node_index are
metadata-only and do not cause a projection change.
Concurrency
- Concurrent transactions must not allocate the same local index.
- JavaScript's single-threaded execution model makes atomic counter
increment possible without additional synchronization primitives:
the volatile
_nextNodeIndexcounter is incremented synchronously inside_allocateKeyIdentifier. - The persisted
last_node_indexis written in the same durable batch as the newidentifiers_keys_mapand node records.
Disk-before-memory invariant
- The commit watermark is captured once before disk write:
commitLastNodeIndex = rootDatabase.getCurrentAllocationWatermark(). - The disk batch writes
last_node_indexto thecommitLastNodeIndexvalue. - After the batch succeeds, in-memory
_computed.lastNodeIndexis set tomax(_computed.lastNodeIndex, commitLastNodeIndex). - This prevents
_computed.lastNodeIndexfrom advancing past what was actually written while another concurrent transaction allocates ahead.