docs: mesh multiplayer protocol with dot diagrams

Adds docs/mesh.md and five graphviz diagrams covering the federation
layer: identity stack, epoch state machine, per-member secret envelope,
gossip wire contract, and operator decision tree. Pins the protocol
contract for the upcoming HTTP wire (mesh sync, mesh serve).

Makefile gets a 'docs' target with pattern rule so PNG renders are
incremental from .dot sources.
This commit is contained in:
russell@unturf.com 2026-04-28 12:54:36 -04:00
parent 1f5bf7318d
commit c7275b5618
No known key found for this signature in database
12 changed files with 510 additions and 1 deletions

View file

@ -30,7 +30,7 @@ SEARCH_Q ?= computer
ingest-xml-attached ingest-abstract \
ingest-grok ingest-grok-media \
ingest-self ingest-git ingest-hg \
verify search stats test clean clean-db clean-data help
verify search stats test docs clean clean-db clean-data help
all: bootstrap fetch-cur ingest-cur verify stats ## bootstrap → fetch cur → ingest cur → verify → stats
@ -282,6 +282,14 @@ stats: bootstrap ## counts: documents, chunks, edges, audit chain
test: bootstrap ## run pytest suite
$(VENV)/bin/pytest -q
DOT_SRCS := $(wildcard docs/diagrams/*.dot)
DOT_PNGS := $(DOT_SRCS:.dot=.png)
docs/diagrams/%.png: docs/diagrams/%.dot
dot -Tpng $< -o $@
docs: $(DOT_PNGS) ## render docs/diagrams/*.dot -> .png via graphviz
# Reproducible micro-benchmark over a fixed slice of cur. Lets you compare
# ETL throughput across configs and catches regressions on optimization
# work. Override BENCH_DOCS=N (default 5000).