Journal and framing
The local journal's ownership, sequence and integrity rules, with clear format boundaries.
Status: Foundation. The byte-frame codec and local journal are implemented. They establish storage boundaries; they do not by themselves implement a document database or certify physical power-loss behavior.
A bounded frame
Each frame has a fixed 64-byte header followed by a bounded opaque payload. The header contains magic, format version, record kind, reserved bytes, sequence, length and a SHA-256 digest.
Integers use explicit little-endian encoding. The digest covers the protected header fields and payload. Decoding validates a complete first frame without allocating and returns a payload borrowed from the supplied input.
Malformed fields, unsupported versions, excessive lengths, incomplete input and checksum mismatches have distinct outcomes. The caller must bound its receive buffer and inspect any remaining bytes.
Frame format version 1 and journal file version 2 describe different layers. They are separate from the repository's product version shown in the live version badge.
A local owner
The journal owns a dedicated directory with a persistent lock file and a log file. An exclusive OS advisory lock prevents a second cooperating owner from opening the same store. Closing releases the lock but does not remove the lock inode.
The version 2 journal header contains an immutable 128-bit store identity obtained from OS cryptographic entropy at creation. Reopening preserves that identity. Unsupported older or future file formats are rejected rather than silently upgraded.
The caller supplies a trusted parent directory. This model does not defend against another principal that can replace the live files or directory, and it is not a network-filesystem coordination protocol.
Ordered append and replay
The journal checks expected sequence, payload size and capacity before writing. A successful append returns only after file synchronization. Replay validates the full bounded image and requires contiguous sequence numbers.
Unknown append outcomes block further normal use. Malformed reopened suffixes are preserved for recovery; they are not silently truncated. A valid prefix is diagnostic evidence, not permission to serve a partly reconstructed database.
Current open/replay uses a bounded whole-log buffer. There is no automatic checkpoint rotation, compaction or larger-than-memory replay in this module.
Evidence and limits
Tests cover real temporary directories, ownership conflicts, incomplete initialization, sequence errors, corrupt frames, reopen behavior and injected write/sync failures. The journal version 2 module passed 27 standalone tests at the recorded module checkpoint on 19 September 2026.
These tests do not turn a local copy into replication or establish a complete backup workflow. See durability and recovery for the acknowledgment contract and project status for current whole-project readiness.