Crate sapphire_framework_sync

Expand description

Transport-agnostic replication core for sapphire-framework workspaces.

See docs/superpowers/specs/2026-09-15-p2p-sync-iroh-design.md, section 2.

Modules§

Conflict
ContentHash: SHA-256 of a file’s bytes.
DiskState: What is on disk for a path.
Dot: One event: the counter-th write recorded by replica.
Entry: One version of one path.
Hlc: Hybrid logical clock value, ordered by wall time and then the logical counter.
Meta: Replica-wide metadata.
ParseHashError: A string that is not 64 hex digits.
PathState: A path’s sibling versions, everything merged so far, and what is on disk.
PathUpdate: A path’s replicated state: its sibling versions and everything merged so far.
Replica: One workspace root and its replica store.
ReplicaConfig: How a replica is set up.
ReplicaId: Identity of one replica store, created once (UUIDv7). A reinstall gets a new one, so dots are never reused.
ReplicaStore: Persistent replica state.
Report: Effects of one scan, apply or fetch_missing call.
Skipped
SyncFilter: Declarative sync filter: the built-in rule for an app name plus .sapphireignore.
SystemClock: The system wall clock.
VersionVector: For each replica, the highest counter covered.

DEFAULT_MAX_FILE_SIZE: Files larger than this are not synced unless configured otherwise.
FORMAT_VERSION: On-disk format of the replica store. Bump for any change in stored data or in merge behaviour (spec §5.4).
IGNORE_FILE: Name of the per-workspace ignore file.
MAX_DRIFT_MS: How far ahead of the local wall clock a remote timestamp may pull the local clock.

Clock: Source of wall-clock time, injectable for tests.
ContentSource: Where a replica gets bytes it does not have: a peer, in practice.

conflict_path: <stem>.conflict-<grain-id>-<counter>.<ext>, or <name>.conflict-<grain-id>-<counter> when the name has no extension. A leading dot does not start an extension.
join: DVV-set join of a local state with an incoming one. Returns the joined (versions, seen), or None when the local state already contains everything.
needs_copy: Whether loser needs a conflict copy next to winner.
winner: The sibling whose content belongs on disk.