Epiq Architecture

The event log is a CRDT

No server, no shared clock. Each actor appends to its own JSONL log on the state branch, git merges them, and every machine derives the same board from the same set. Everything below keeps that derivation a pure function of the event set.

The model

• Every event names its causal parent — the last event its writer had seen. Concurrent writers may share a parent.
• Order is derived, never stored. It is rebuilt from the parent links, with concurrent siblings tie-broken by id. File line order means nothing.
• Ids are a hybrid logical clock (ULIDs): a new id always sorts after its parent, whatever the wall clock says. The wall clock is only a lower bound.
• An event identifies its actor by id and carries nothing else about them. The id comes from the log file name; the display name from the contributor registry, which is itself built from events.
• Same event set ⇒ same order ⇒ same board.

Invariants

• Order comes from parent links plus the id tiebreak. Nothing else.
• Ids are permanent; tombstone instead. A tombstoned node takes its descendants with it; a tombstoned contributor keeps its record so assignments still resolve.
• Replay is total. An event that lost a race, or names state this replay never applied, is skipped, not fatal. The same precondition on a live write is a real failure — there it is the answer the caller asked for.
• Unreadable stays ordered. The envelope parses even when the payload doesn't, so a newer build's event keeps its place.
• Append only. One id is one byte sequence — what makes git's union merge of the logs safe.
• Time travel cuts causally. An event whose parent is past the cut is past it too, whatever its timestamp.

Never

• Break a client already out there. The format grows by adding (a new event type, a field nothing older must read), never by changing or repurposing what an older build reads. Most rules below follow from this one. A version marker can't help retroactively: an older build can't check for something it shipped without.
• Change the log file name's grammar without a release between reader and writer. It has no additive form — every client reads every other client's logs — and an old build misreads a name rather than failing. A test pins every form still out there.
• Order or resolve conflicts by wall clock. No latest-timestamp-wins; time is a display value and an id lower bound.
• Mint an id that could sort before its parent — it corrupts the order. A damaged parent id (undecodable, or absurdly far ahead) falls back to the wall clock; order still comes from the parent link.
• Hard-delete a node, contributor, tag or event, or reuse or rewrite an id — replay would reach a reference that no longer exists.
• Rewrite, reorder or de-duplicate log lines — union merge depends on their identity.
• Abort replay on an event that merely lost — one concurrent edit would leave a board that never opens again for whoever's build understands the most.
• Assume a single writer. Any log can gain lines between two reads, even mid-sync.
• Put actor identity, or anything derivable, in the payload. Beware spreading a user object into an event: TypeScript doesn't excess-check a spread.
• Read a display name off an event or a log file name. Resolve it by id from the registry. Old log file names still carry a sanitized name, kept only as a fallback for authors the registry lacks.
• Store a name beside an id — the copy freezes at the old name and never sees a rename.
• Add a payload field older clients must interpret without a schema-version story.

Adding an event type

It is applied on every machine, in causal order, possibly after events it didn't expect: make it idempotent, treat unmet preconditions as a skip rather than an error, and reference targets by id only. All of it lives in lib/board/ — the event map and action list, the payload schema, the handler, and which nodes it affects for replay. The generic log in lib/event/ doesn't change.

Proving a change is safe

• source/test/replay-equivalence.test.ts — batched replay equals per-event replay.
• source/test/event-core-generic.test.ts — the log still works for a product that isn't the board.
• npm run test:collab — several actors on one remote end with the same events and order.
• Touching ordering, merge, replay or materialization means running all three.
• The pre-push hook runs lint, typecheck, unit, e2e, collaboration and GUI tests. Do not bypass it.
• Git-driving suites run containerised over a read-only checkout; a test that aims git at the checkout instead of a temp dir fails.