How the project works

The entity system is not one program. It is a specification, several independent programs that implement it, and the machinery that checks they agree. Those are separate efforts with separate lifecycles, and the separation is deliberate: a protocol that only one codebase can speak has not been shown to be a protocol at all.

This page describes how that work is divided and how it converges.

The governing rule

Implement Entity Core Protrocol and you interoperate at the substrate. The protocol is a small mandatory core; every capability above it is opt-in. Two peers that implement the core can exchange entities whether or not they share anything else — the same language, the same libraries, the same extensions, the same opinions about what to build.

Divergence is allowed above core protocol. Convergence is offered, not mandated. That rule is why the work splits the way it does below.

The specification

Two repositories, and the boundary between them carries most of the weight.

• entity-core-protocol — the mandatory layer. The wire encoding, the entity-native type system, identity, capabilities, dispatch, and the core tree operations. This is the part that must not move casually: every peer interoperates by agreeing on it, so the wire core is held stable on purpose and changes here are expensive by design.
• entity-system-architecture — everything optional above the core. The extension family, the SDK conventions, the application-layer conventions, and the implementer guides. This is the design space, and it moves continuously.

The split matters to a reader deciding where to look: if you want to know what a peer must do, the first repository answers it. If you want to know what a peer may do, the second one does. What is settled and what is still moving is tracked on the roadmap.

A third repository, entity-system-arch-tools, holds the tooling that keeps the specification corpus coherent — a linter that checks style, internal consistency, and whether a specification cites something that does not exist.

The implementations

• entity-core-go — the Go implementation. It also hosts validate-peer, the harness the other implementations are checked against.
• entity-core-py — the Python implementation.
• entity-core-rust — the Rust implementation.

These are independent codebases, written separately against the same specification. They are not ports of one another, and that is the point: where two of them disagree, the specification was ambiguous, and the disagreement is the signal.

How a change actually moves

The loop runs in both directions, and the upward half does more work than people expect.

Downward — specification to implementations. A change to normative text is proposed before it is written, so the reasoning has somewhere to live other than the specification itself. Once ratified it lands in the specification, then the implementations pick it up.

Upward — implementations to specification. An implementer who hits an ambiguity does not resolve it locally. They file it, and it routes back to the specification as a question with a named answer. This is where most corrections originate. An implementation that quietly works around an unclear sentence leaves the sentence unclear for the next reader; one that reports it gets the sentence fixed.

The rule underneath both halves is that implementations implement and do not define. A gap gets logged and routed upstream rather than papered over — which only works if reporting is genuinely cheaper than working around, so it is made cheap on purpose.

What governs a decision

Not every design question is the same kind of question, and treating them alike is how arguments about complexity go in circles. The specification sorts a decision into one of three constraint regimes — not by how important it is, but by what governs it, and therefore whose complexity it is.

Substrate. Mathematics and computer science govern. A competent designer starting anywhere arrives at the same answer, or is wrong. Content addressing, cryptographic hashing, verifying a signature at the destination rather than in transit, canonical encoding. There are essentially no degrees of freedom in the structure, the complexity belongs to nobody, and "simplify this" means be wrong — a simpler Merkle proof is not a Merkle proof.

Design space. Coherence governs, and we choose. Several internally consistent answers exist and the system stays whole under any of them; we pick one for economy, not because the alternatives are broken. This is the only regime where complexity is genuinely ours to remove, and therefore the only one where "this is too complicated" is a complete argument rather than the start of one. It fails in two directions: building a mechanism where composing existing ones would do, and — the more expensive mistake — deleting a point from a design space because it looked over-broad.

Accumulated technology. The world governs and we adapt. Complexity imposed by decades of deployed technology nobody here chose and nobody here can change: address exhaustion and the workarounds that outlived it, the traversal machinery those workarounds require, the fact that a browser will not hand out a socket or listen on one. There are no degrees of freedom here either — but not for the first regime's reason. Not because the mathematics forbids another answer; because the installed base does. The constraint is contingent and historical and it binds exactly as hard as if it were necessary. This complexity is real, it is not ours, and it cannot be designed away — only placed. Arguing that it is inelegant is arguing with history.

Two things make this useful rather than decorative. A regime applies to a decision, not to a component — a single extension routinely has its structure in one regime and its motivation in another, which is why "is this part of the core or part of the network layer" was never one question with one answer. And a substrate-regime structure almost always contains a design-space parameter inside it: that a hash must be collision-resistant is forced, but which hash is a choice, and the discipline is to expose it as one rather than let the arbitrary part fuse to the necessary part.

The standing rule that falls out: keep the third regime's complexity from leaking into the first two. Interoperating with the world as it is should not deform the structure underneath.

Full treatment in System Architecture, which also carries a second axis — how many defensible designs an area actually has — and pairs each band with the review method that fits it. The two axes exist because applying a correctness argument to a genuine design space is how rulings get published and then retracted.

How agreement is shown

Four kinds of evidence, and they are not interchangeable.

The three reference implementations. Independent codebases in different languages, checked against a shared conformance harness. Three rather than two for a specific reason: two implementations can rationalise a difference between them and pick one. Three cannot — when they diverge, at least one is unambiguously wrong, and the question goes back to the specification instead of being settled by negotiation.

The Keystone project. A generator that emits a complete core peer for a target language from the specification, run as a cohort across many languages at once. It answers a different question from the reference implementations: not "can careful people write this twice" but "is the specification precise enough to be mechanically realisable across substrates that share nothing" — managed runtimes, manual memory, stack machines, array languages, live images. Its conformance matrix is the per-peer record, including known gaps.

The honest framing is part of the result and is stated plainly in the project's own documentation: generated peers share a generation lineage, so what the cohort demonstrates is specification-forced convergence, not independent convergence. Those are different claims and the weaker one is the true one.

Cross-implementation test vectors. Byte-pinned cases that a peer either reproduces or does not. Where the harness cannot construct the state a rule requires, that is declared rather than approximated — a test that reports coverage over a case it never reached is worse than an honest gap, because it reads as evidence.

Machine-checked models. Formal specifications of the protocol's concurrency and security properties, checked by model checkers and protocol verifiers rather than by testing. A fourth kind of evidence, and one that has caught things the other three did not.

What counts as done

Conformance is the contract, not the version number. A green test suite is not a release; agreement on the conformance surface is. A published conformance result is reported against the specific oracle it was measured with, along with what passed, what warned, what failed and what was skipped — and a skipped case counts as a failure, not as a pass with an asterisk.

This is the discipline that keeps the rest honest. It is easy to describe a system as converged; it is harder, and more useful, to be able to say exactly which peers were measured, against what, and where they fell short.

The applications

Built on the substrate rather than part of it, and useful mainly as demonstrations that the substrate carries real weight.

• entity-browser-rust — a browser for entity-native content, as a native application and in the browser.
• entity-workbench-go — a desktop workbench for working with peers and trees directly.

Together they are ECDEOS, the distributed entity operating system — and it is the same argument as the core, one layer up. Three independent implementations show the protocol is real; these two show the operating-system layer is, in different languages on different cores, aligned by the application-layer conventions rather than by shared code. It hosts applications, browses and publishes content sites, transfers files and carries a chat, and it runs in a browser tab. Early-stage research prototype, and worth trying.

Where to look next

The roadmap tracks what is moving and how far along it is. Entity System Architecture carries the extension and SDK corpus in full. The core specification and the conformance evidence live at entitycoreprotocol.org.

Each project keeps its own documentation, and on any question about a project that documentation is the authority — this page orients, it does not restate.