What a hash chain cannot see
Every entry in the ledger commits to its predecessor:
const base = { ts: new Date().toISOString(), seq: this.seq, prevHash: this.prevHash, ...safe };
const hash = sha256(this.prevHash + JSON.stringify(base));
const ev = { ...base, hash };
JSONL, one event per line, fsync per event. The chain seeds from the literal string 'GENESIS' rather than a hash, so event zero's preimage contains it twice — once as the raw prefix, once inside the serialized body. Verification recomputes both assertions per event: that the recorded prevHash matches the running head, and that re-hashing the event without its hash field reproduces the hash.
That catches edits, reordering, insertions, and deletion of anything that isn't a contiguous suffix. It is the part every tamper-evident log gets right.
The blind spot is structural, not an oversight
A hash chain is an assertion about what came before each record. It contains no statement whatsoever about what came after.
Lop off the last five lines and every surviving event still links correctly to its predecessor and still re-hashes correctly. The file is a valid chain. It is just a shorter one. There is nothing inside the artifact that can distinguish "this log has two events" from "this log had seven and someone deleted five."
Detecting it requires an out-of-band claim about the expected length. So alongside the log sits one small file containing exactly that: {seq, headHash}, rewritten and fsynced after every append. At construction, the ledger reads it and compares.
const anchor = this.readAnchor();
if (anchor && this.seq - 1 < anchor.seq) { /* truncated or deleted */ }
Strictly less-than, so an anchor lagging behind the log is tolerated — it can legitimately be one write stale if its last write failed. Only an anchor ahead of the recovered head trips.
Note what this is not. It is one number and one hash in a separate file on the same disk. It is a tripwire, not a witness. Against carelessness, a crash, or a partial edit it works. Against someone who deletes both files it reports clean — and the test that proves the guard works survives precisely because the attacker in it deletes only the log.
Five states, and why "fresh install" is one of the dangerous ones
Recovery runs unconditionally at construction. That word is the whole story, and the comment explaining it is the strongest line in the file:
Recovery used to be gated on the log or the segment index existing. So deleting the log outright skipped recovery entirely — the anchor, the one artifact proving events had existed, was never read. Integrity reported clean. Verification returned true. The sequence restarted at zero.
The ledger now distinguishes five states, and the difference between the last two is deliberate:
| clean | a genuinely fresh install — and a test asserts this produces no false positive |
| torn | one unparseable final line: a crash artifact. Tolerated, flagged, and physically healed so the next append starts on a clean line |
| corrupt | an unparseable earlier line: nothing a crash produces. Flagged, and deliberately not repaired |
| truncated | anchor ahead of the log, log still present |
| deleted | anchor present, no log and no segments at all |
The torn-versus-corrupt split is nine lines of parsing that carry a physical argument: a partial write at the end of a file is what a power failure looks like. A broken line in the middle is not. So one is healed and one is quarantined, and corruption outranks a torn tail — a corrupt file is never rewritten.
The last two get separate messages on purpose, because an operator needs to read total absence as destruction rather than as a first run. Any of the four unhealthy states boots the governor into safe mode, where the decision point denies everything until an operator re-attests.
The failure of the thing that detects failure
The anchor's own write can fail. A read-only directory, a full disk. And it must not fail the append, because the chain still works perfectly without it.
So the write swallows its exception — but records that it did:
catch (e) {
this.anchorDegraded = `anchor unwritable (${e.message}) — tail truncation is no longer detectable`;
}
Boot then surfaces that as an audit event at high severity. The reasoning is the second-order version of the first problem: "best effort" was hiding the difference between "anchoring is off" (a choice) and "anchoring is broken" (a failure). A silently unwritable anchor is a silently degraded guarantee — the chain keeps verifying, so nothing looks wrong, while truncation quietly stops being detectable.
That is the same question asked twice, one level apart. First: what would it look like if the log vanished rather than reported an error? Then: what would it look like if the mechanism that answers that question vanished?
Rotation, and the joint that has to be a real hash link
Size-based, checked after each append, disabled by default. Rotation seals the live file into a segment by atomic rename and records a root: first and last sequence, the incoming prevHash, the outgoing lastHash, a hash of the segment, and the filename.
Two details make it safe. It never rotates an unhealthy tail — a torn or corrupt file is not sealed, which is why segments are always clean. And it touches neither the sequence counter nor the running head, both of which live in memory, so the next append continues as though nothing happened and the live file's first event points into the sealed segment.
Across a restart the joint is restored from the index rather than memory, with a branch that exists for exactly one moment: immediately after rotation the live file does not exist, so the head comes from the last segment's recorded hash.
Verification then threads the running head through each segment in order and hands it to the live tail. The joints are real hash links, not bookkeeping.
Two honest observations for anyone reading the source. The per-segment content hash is recorded but never recomputed — the real segment check is that the recomputed head matches the recorded one, which makes that field decorative for integrity purposes. And the segment index itself is plain, unchained, unsigned JSON; an unparseable index degrades to an empty list, which does not silently pass, because the live tail's first event then fails to link to 'GENESIS'. Controlled degradation rather than a hole, but worth knowing.
Also worth saying plainly: rotation bounds the live file, not verification. A full verify re-reads every segment and re-hashes every event, every time.
Redaction has to happen before hashing, which forecloses something
Secrets are stripped from the reason and target fields, and recursively from the free-form detail object, to a bounded depth of six. The patterns are the usual suspects — PEM private key blocks, AWS access keys, provider API keys, GitHub and Slack tokens, JWTs, and a line-anchored assignment form that keeps the key name and redacts only the value.
Detail needed covering separately for a reason that generalises: reason and target are flat strings, one call each and you are done. Detail is an arbitrary-shaped record populated by dozens of call sites. Guarding only the two fields you were thinking about left the one field with unbounded shape completely open.
The architectural consequence is the interesting part. Redaction happens before the event is hashed, so the chain commits to the redacted text — and a test asserts the log still verifies afterwards. Which means you cannot scrub a secret from a past event without invalidating every hash from that point forward.
Append-only and "please remove that from the log" are mutually exclusive. This design picks append-only and pushes redaction to the write boundary, permanently. There is no retroactive fix available, by construction.
Two gaps I would rather state than leave for a reader to find: the free-form action field is not redacted, and a string nested deeper than six levels inside detail escapes redaction — an explicit trade of a bounded leak at pathological depth against a hard recursion bound.
Notarization is a different thing from the head anchor
Two unrelated mechanisms share a word, and conflating them makes the design incoherent.
The head anchor is local, on by default, and answers "was this log truncated." Notarization is external, off by default, and answers a different question: is the record tamper-evident against the operator who holds the keys — the designated-third-party gap that regulated retention rules care about.
It commits a Merkle root plus a head pointer. Both, deliberately, because a root alone has the same blind spot a chain does: it fingerprints the set without pinning its length. The file backend chains anchors to each other, giving a chain of roots over a chain of events. Only roots ever leave the machine — never audit content.
The whole thing is best-effort: a failed commit is recorded as an audit event and execution continues. Notarization can never block a decision, because fail-closed is a property of the decision point, not of the notary. And the adapter factory fails soft to a no-op rather than erroring, for the same reason.
Two cryptographic notes a careful reader will spot. The Merkle construction duplicates the last leaf on odd levels and uses unprefixed concatenation with no leaf/internal domain separation — the shape behind a known malleability class elsewhere. Here the leaves are themselves chain hashes over distinct events, so practical exposure is small, but the root is not a second-preimage-resistant commitment in the strict sense. And a single-leaf root returns that leaf unchanged rather than a hash of it.
The ledger is a gate, not a log
The append function throws on write failure. Deliberately, and the ordering around it is the design:
appendFileSync(fd, ...); fsyncSync(fd);
this.seq++; this.prevHash = hash; // only AFTER the write succeeded
A failed append leaves the in-memory chain state untouched, so the next attempt reuses the same sequence number and the same head. No gap, no fork, no phantom event the chain believes exists but the file does not contain.
And the caller fails closed. The decision point computes its verdict, attempts the record, and returns the verdict only if the record was written. An allow that cannot be recorded becomes a denial.
That is what "no silent execution" has to mean to be worth anything: the record is a precondition of the act, not a side effect of it. A log you cannot write is an inconvenience. A gate you cannot write is a closed gate.
It also has an availability cost that should be stated as a property rather than discovered: a wedged audit log is a total denial of service. That is the right trade for a governance system, and it is a trade.
The sharpest finding in this whole area came from noticing the two enforcement rings disagreed about it. The decision point failed closed on an unwritable audit. The layer that actually performs effects swallowed the failure and carried on — so an unwritable audit denied every future decision while still executing work already authorized, with no record of either. Both rings now audit before acting, and abort if the record cannot be written.
What this does not defend against
The chain is plain SHA-256. No HMAC, no signature. Anyone with write access to the log can rewrite history from 'GENESIS' forward, recompute every hash, and produce a self-consistent chain that verifies.
The chain proves internal consistency, not authenticity. Chain plus head anchor is tamper-evident against carelessness and partial edits — not against a competent attacker with filesystem write access.
What actually raises that bar is the operator-signed integrity manifest, whose expected public key is supplied out-of-band precisely so an attacker cannot re-sign with their own, and external notarization where only roots leave the machine. Both are opt-in. That is the honest ceiling: local integrity artifacts sit inside the operator's own write reach, which is exactly why the third-party gap exists as a named concept rather than being papered over.
Two smaller ones. Timestamps come from the local clock — hashed, so they cannot be edited afterwards, but never attested and never checked for monotonicity against the sequence, so a rolled-back clock produces a log that verifies perfectly with non-monotonic times. And the design assumes a single writer: each instance keeps its head in memory and appends without locking, so two instances on one path would fork the chain.
None of that makes the ledger less useful for what it is for. It makes the difference between "tamper-evident" and "tamper-proof" a real distinction rather than a marketing one — and a governance product that blurs those two is not one to trust with the other claims either.