The evidentiary spine
Every significant operation emits a canonical event
LockChain Core is what makes the sixty-eight modules a platform rather than sixty separate audit logs. A module does not invent its own record format, its own hashing, or its own idea of what an accountable action looks like. It emits a canonical event, and the spine does the rest.
The canonical event
These are the fields the blueprint lists. The ones marked hashed are
covered by canonical_event_hash and therefore bound by the signature. The three that are
not are excluded for reasons that are load-bearing, not convenient — see below.
event_idevent_typeschema_versionaggregate_typeaggregate_idtenant_idjurisdiction_idelection_idlocation_idactor_idactor_role_snapshotdevice_idoccurred_atrecorded_atreceived_atpayload_hashattachment_manifest_hashprevious_event_hashsignature_key_idcheckpoint_referencesource_referencecorrects_event_idsync_stateserver_acknowledgement
Why three fields sit outside the hash
server_acknowledgement- Written by the server after the device hashed the event. Including it would make the device's own hash unverifiable the moment the acknowledgement arrived.
sync_state- Advances over the life of the same event — queued, attempted, received. A field that legitimately changes cannot sit inside a hash whose whole job is to prove nothing changed.
checkpoint_reference- Circular. A checkpoint's Merkle root is computed over these event hashes, so an event cannot bind the checkpoint that contains it. This one was found by the engine gate failing on a clean ledger — the record looked tampered with because writing the reference back after committing silently invalidated every hash in the batch.
None of the three is a weakening: checkpoint_reference is
recoverable from the checkpoint's own signed event_ids, and the other two are transport
state carrying no evidentiary claim.
The critical design rule
Never edit the historical event to “fix” it. A correction becomes a new event.
Corrections append. They never overwrite.
The blueprint states this as an imperative and it is implemented as one. The ledger
class exposes no update, no edit and no delete — the gate in
test/engine.mjs asserts that those methods do not exist. A correction is an append that
points at the original with corrects_event_id, and the original stays exactly where it
was: still hashed, still linked, still verifiable.
That preserves the original record while giving the system a legally and operationally understandable correction history. The correction history is the record.
Watch a correction leave the original untouched
This runs in your browser. It appends a custody event, records its hash, then corrects it — and re-reads the original's hash afterwards.
What a module attaches an event to
An event must name the thing it is about. These are the aggregate types the spine recognises across the sixty-eight modules — the same nouns, so a custody question and an equipment question are answered by one query rather than by sixty schemas.
ballot_containerpolling_locationequipment_assetsealincidentevidence_itemsupply_kitworker_assignmentcustody_transferchecklist_runrecords_requestpolicy_documentSigned checkpoints
A checkpoint commits a range of the chain: a Merkle root over the event hashes in that range, plus the range metadata, signed with Ed25519 by a registered key. It is what lets a third party check one event without being handed the whole log.
The root alone is not enough. A Merkle root over an odd number of leaves, where the last leaf
is duplicated to pad the level, is ambiguous — a tree over three events can share a root with a tree
over four. Signing only the root therefore accepts a weaker claim than it appears to. This engine signs
the root together with event_count and the sequence range, so the count is bound by the
signature. The collision, and its closure, run live on the verify page.
Where the guarantee ends
A privileged attacker who possesses every database, signing key, checkpoint and backup could potentially fabricate a replacement history. Separation of signing keys from application databases, key rotation and audit, protected checkpoints, retained independent verification material and separate backup/retention controls are what make that expensive — not the hash chain by itself.
- The word
- Tamper-evident. Not "immutable", and not tamper-proof.