Expand description
The team mind without a server: the members of a collective sync its lessons peer to peer.
- Identity (identity.rs): one ed25519 key per node and collective, kept in the collective’s store (mode 0600). The same key is the node’s iroh id, so the transport authenticates it.
- Membership (membership.rs): a JSON document listing member keys, roles and revocations, signed by an admin. A newer version is adopted only if it is the next one, names the held one as its parent and an admin of the held version signed it; concurrent admins’ forks resolve the same way on every node, keeping every revocation. A node talks only to peers its verified membership lists.
- Data (lines.rs, origin.rs): the append-only
lessons.jsonl, addressed per line by blake3, each line with a signed origin (who stamped it, when). Merge is a union; the latest version of a lesson wins, asconscience::loadexpects. Raw episodes stay on the node that captured them, so each is learned exactly once. Reasoning excerpts (git notes,borg notes) go from their author to two member replicas, and any holder answers a member asking for a commit’s. - Sync (sync.rs, recon.rs): iroh QUIC between two nodes, trust first (membership and revocations before any data), then range-based set reconciliation, cost ∝ difference.
- Live (live.rs): presence of the members’ drones, ephemeral, carried in every session after the logs; never reconciled into a log.
- Steering (steer.rs): a pause, resume or veto is a message line, authenticated by its origin;
another node’s counts only under its member role
adminorsteer, admitted when stored. - Daemon (daemon.rs, peers.rs):
serveaccepts members and dials the known ones every interval and on local change, with backoff, until Ctrl-C / SIGTERM. - Reach (addr.rs): peers are dialled by key; across NAT through iroh’s hole punching with relay fallback (n0’s public relays and address lookup by default, a self-hosted relay, or direct addresses only), set per collective.
- Onboarding (invite.rs): an admin’s signed, expiring, use-limited invite in a ticket string
or QR code;
join <ticket>dials the admin, which adds the key to the signed membership.
The gate: borg::collective::may_sync is asked before any byte of a collective leaves, on both
sides, on the config as it is at that moment. A local collective or an off repo is refused before
a connection is even opened, and so is a store a local collective also maps to.
Internal API, no semver. The product is the borg-mesh binary; this library exists for borg’s own
crates, which pin it = to the same version. Any release may change or remove any item.
Modules§
- addr
- How a node is reached: by its key, with optional hints, through the relay its collective uses.
- daemon
borg mesh serve: one node, running until it is told to stop.- identity
- A node’s identity in one collective: an ed25519 key in
<store>/mesh/node.key(hex seed, 0600). - invite
- Onboarding by ticket:
borg mesh inviteprints one string (and a QR code of it),borg mesh join <ticket>on the new machine does the rest. - lines
- A collective’s append-only logs as sets of content-addressed lines.
- live
- Presence over the mesh: which drones run on the other members’ machines, for
borg top. - membership
- Who belongs to a collective:
<store>/mesh/membership.json, signed by the collective’s admin. - origin
- Where each synced line came from:
<store>/mesh/origins.jsonl, one signed record per line hash. - peers
- Where members can be reached:
<store>/mesh/peers.json,{"<key>": "<hints>"}. - recon
- Range-based set reconciliation of two hash sets: the cost grows with the difference, not with the history (the Negentropy / iroh-docs idea, in its simplest lock-step form).
- steer
- Steering over the mesh: which pause, resume and veto messages of another node count here (the hook side, the admissions file and delivery are borg steer.rs).
- sync
- Two members of one collective reconcile its logs over iroh (QUIC, TLS with raw ed25519 keys).