The Ledvar Manifesto

A protocol for remembering what changed.

Systems do not change all at once. They drift — a setting loosened here, a rule shadowed there, a value quietly raised and never lowered. Each change is small, reasonable, and forgotten by morning. You cannot understand a system you cannot compare against yesterday.

A ledger is a book of record kept by adding, never erasing — every entry preserved, in order, so the whole past stays legible. That is what a running system’s state should be: layer upon layer, each change recorded and kept, the past never lost. Ledvar — Ledger · Every · Diff · Versioned · Append-only · Recorded — is a protocol for writing those layers down in a way that can be compared, precisely and reproducibly, to reveal what changed.

It began as a way to watch security state drift. But what it standardizes never knew what “security” was — only how to describe a piece of state and hash it. So the protocol is deliberately broader than its first use: a node can describe a firewall rule, a virtual machine, a cloud permission, a repository’s access list, even a transaction. If it can be written as a tree, something built on Ledvar can remember it. Security is the first thing we built with it, not the limit of it.

A note on voice. Ledvar is a protocol — a small contract about what state is and how it is hashed. The pieces that actually watch a system, store its history, compare snapshots, and raise alerts are independent implementations built on it, each its own project. So where this manifesto says Ledvar “watches” or “remembers,” read it as what a system built on Ledvar does: the protocol is what makes that possible — and what keeps it honest.

None of what follows is settled doctrine. It’s what the project believes today, stated plainly so it can be argued with — and the most useful thing you can do is find where it’s wrong.

What we believe

1. Nouns, not verbs — and as few nouns as possible. The protocol says what a piece of state is and how to hash it. It does not say what to do with it: comparing, storing, alerting, displaying are all left to others. It has no clock, no memory, no opinions. The smaller the contract, the more places it survives unbroken and the easier it is to verify. Cleverness is where bugs and bias hide; there is almost nothing here to hide in.

2. One canonical hash, one truth. The same state, on any machine, in any language, on any day, produces byte-identical hashes. Identity is “same path”; equality is “same content hash.” That determinism is the whole foundation: it is what lets a fleet of machines, two implementations, and a year of history all be compared with a single =. Everything else is built on top of it.

3. What counts as a change is settled by mathematics, not opinion. Match two snapshots by node identity and each node is exactly one of: unchanged, modified, added, removed — plus the cold-start baseline. There is no sixth case, and none is left unclassified. It is not a design choice — it is what comparing two sets gives you. The protocol does not even prescribe how to compare; it only makes the answer inevitable. Whether a node changed is arithmetic; what the change means is for higher layers.

4. Context lives elsewhere — and stays honest because of it. Meaning — what is risky, what is allowed, what a value means, even whether "200" is a number — lives in higher layers, never in the protocol. A collector states what it sees; people decide what it means. A contract that mixes facts with opinions can be trusted with neither.

5. The past stays legible. The protocol can’t enforce this — it is stateless and holds no power over how anyone stores what they build from it. It’s a discipline: a store built for Ledvar keeps history append-only, overwriting and deleting nothing in normal operation. That immutable timeline is the point — a record where every entry in the ledger is still there to be read. History you can edit is not history.

6. A protocol, not a product. The contract is data and rules, not a binary you must run. Implement it in Go, Python, Rust, or anything that can hash. If your implementation produces the same hashes, it is Ledvar. No vendor, no lock-in, no blessed runtime — and no blessed serialization: carry it as JSON, YAML, protobuf, whatever fits. Only the bytes that get hashed are pinned. (“It is Ledvar” here means it speaks the protocol — same bytes, same hashes. It is a statement about technical conformance, not permission to use the name as your own product’s brand; see TRADEMARKS.md.)

7. No telemetry. Ever. The whole point is to watch your systems for you — never to watch you. The protocol defines no telemetry, carries none, and asks every implementation to add none: your state, your history, your metadata never leave your control. A monitoring tool that surveils its own user has failed its first duty.

8. Verifiable beats trusted. You should not have to take our word for anything. The hashes are reproducible; the comparison is forced by math; an honest store keeps every layer. Run it yourself, byte-compare the output, read the history. Trust that can be checked is the only kind worth having.

An invitation

This is an open protocol, and it is better with you in it.

• Write a collector. Anything with state worth watching — a server, a database, a cloud account, a repository, a config file — can feed it. If you can describe its state as a tree, something built on Ledvar can remember it.
• Implement it. Bring the protocol to your language — hash a node the same way, byte for byte. Prove it against the conformance vectors.
• Break it. Find the input that two implementations hash differently, the case the math missed, the snapshot that slips past well-formedness. Adversaries make protocols honest.
• Keep it small. The best contribution is often the rule we didn’t add. Guard the smallness like it’s the whole point — because it is.

Remember what changed. Make it provable. Tell no one but yourself.

— The Ledvar project