tsunagiandClaude Opus 5
7cea9afa37
Working library with real iroh connections, not an interface sketch: - persistent device identity in state.sqlite, stable across restarts - deterministic network space derived from name + secret via HKDF-SHA256, with frozen labels and unambiguous length-prefixed encoding - replaceable discovery returning unverified candidates only; static bootstrap, in-memory test backend and a composite - real iroh connections plus an explicit mutual membership proof: HMAC-SHA256 over a role-separated transcript bound to the TLS exporter, the network id and both endpoint identities - small versioned control protocol: handshake, announcement, ping/pong - multiple networks per agent with enforced isolation - automatic reconnect with bounded backoff and jitter - mandatory state vs disposable cache, with a real directory ownership lock - status snapshots, event stream and honest diagnostics 47 integration and unit tests cover the required scenarios offline on loopback. Snapshots, revocations and WireGuard are designed for and documented, not implemented. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.7 KiB
Planned state synchronisation
Nothing in this document is implemented. The proof of concept exchanges hostname and capability announcements over live sessions and keeps no replicated history. This file records the intended direction so the module boundaries in architecture.md stay compatible with it, and so nobody mistakes the current announcements for synchronisation.
There is no fake "ready CRDT" here and no snapshots that are not actually verified.
The problem
The network may be unstable. A participant can come back after months. So:
- no dependence on the author of a change being online;
- no dependence on acknowledgements from every participant ever seen;
- any available replica holding the signed data must be able to hand it to a returning participant without the original author present.
The model
Signed self-contained state per author, merged between replicas.
A record contains: the network, the author, the author's own retained version, the full current content, and a signature. A change log may speed delivery up, but recovery must never require the entire chain from the first event.
A network snapshot is a set of verifiable authored records plus the revocations needed to interpret them. It is not a SQLite dump, and not a single document trusted merely because the neighbour who forwarded it signed it.
Merge rules
- A snapshot is merged into local state, never substituted for it wholesale.
- An older version never rolls back a newer known one.
- Absence from a snapshot does not mean deletion.
- Duplicates do not change the result.
- Two conflicting signed records at the same version from the same author need explicit handling; they are not resolved by luck.
- Neither arrival order nor system clocks decide a winner.
- Compaction must not drop what is needed to stop revoked records being resurrected.
Hostnames
A hostname is a mutable binding to a persistent author, not an identity. A rename must be a signed record that revokes the specific old binding and announces the new one, ideally atomically in one record.
Turning a computer off is not a revocation of its hostname and does not remove the participant. Revocations are not dropped merely because they are old, and no acknowledgement from offline peers is required to keep working.
Storage requirement this creates
When signed records land, writing the event and bumping the author's own
counter must happen in one SQLite transaction, committed before the change is
published to the network. SQLite gives atomic commit; use it instead of
separate, inconsistent writes. state.sqlite already has a schema version and
migrations for this.
Limits to state honestly
- Data that every copy has lost is not recoverable from the secret.
- A signature proves authorship, not global freshness: a replica can be behind, and you cannot tell from the signature alone.
- An isolated new client can end up with incomplete state and has no way to know what it is missing.
- Anyone who knows the secret can author records, so a majority of records is not evidence of anything.
Future tests
These are not implemented and must not be reported as passing:
- snapshot merge against the rules above, including conflicting same-version records;
- revocation propagation and resistance to resurrection after compaction;
- long network partitions and rejoin after an extended absence;
- hostname rename with atomic revoke-and-announce;
- recovery of a returning participant from a replica that is not the author;
- NAT traversal and hole punching between real hosts;
- relay fallback behaviour against a self-hosted relay;
- multi-process and multi-host deployment, as opposed to several library instances inside one test process.