Durability and Write-Ahead Logging

Documentation status: architecture — see Maturity and evidence.

The persistent hypergraph uses a write-ahead journal to separate change production from durable application. The current engine contains a double-entry journal cache and a transaction-aware coordinator.

Commit batching

During a transaction, node and key changes are staged by transaction identifier. When the transaction commits, the journal writer emits the staged batch inside explicit pending/commit boundaries while holding a single writer section.

transaction changes
  -> stage latest node/key records
  -> commit requested
  -> begin journal batch
  -> write staged records
  -> end journal batch
  -> release transaction staging

Staging also allows a newer change for the same node/key inside one transaction to replace an older staged record before the committed batch is written.

Double-entry journal cache

The journal cache separates a write side from a reader/snapshot side. A swap rotates the current writer into the reader position and opens a new write target. Write/flush operations and swap are serialized so rotation cannot interleave with a partial producer operation.

This architecture supports asynchronous consumption of stable journal batches while new writes continue on the next writer.

Tags and logical records

Journal blocks can carry 64-bit tags. The engine uses tags and block types to distinguish transaction boundaries and persisted data categories. Those numeric values and binary layouts are private implementation details; public integrations should not parse them directly.

Operational caution

Write-ahead logging is a durability mechanism, but the presence of a WAL alone does not establish a complete public crash-recovery guarantee. Until recovery/replay behavior is certified as a public contract, operators should rely on the Runtime's supported backup, shutdown, restart and health procedures rather than external interpretation of journal files.