mirror of
https://github.com/spacedriveapp/spacedrive.git
synced 2026-11-03 22:05:11 -05:00
Jamie Pine
bbaf0b5d54
AGENTS.md and CLAUDE.md flip their current direction from tearing down the entries world to it being gone, and drop the ephemeral note T6.7 retired. The locations page is deleted; the overview page that explained pins as location rows becomes Add Sources and Pins, and the data model, library, architecture, sync, and CLI pages describe pins as Space items. The React explorer and normalized cache guides use sources and spaces for their examples, the snapshot format doc points at the moved module, and CONTRIBUTING tracks a source instead of adding a location. The final-drop plan records FD5 with what still fails and why, the convergence plan notes the old world is gone, and the registers move FD5 to done with FDA ready.
152 lines
5.7 KiB
Plaintext
152 lines
5.7 KiB
Plaintext
---
|
|
title: Library Sync
|
|
description: How devices share library state without central custody
|
|
sidebarTitle: Library Sync
|
|
---
|
|
|
|
Library sync keeps a person's Spacedrive environment coherent across paired
|
|
devices. It synchronizes small durable state, source availability, and user
|
|
assertions. It does not place every filesystem record into one replicated
|
|
library database.
|
|
|
|
That boundary lets a library grow across large NAS datasets, removable drives,
|
|
and cloud sources without making each client copy the full index.
|
|
|
|
## What library sync carries
|
|
|
|
Library sync carries state that defines the shared environment:
|
|
|
|
- paired device membership and revocation;
|
|
- source descriptors and availability;
|
|
- spaces, pins, and library presentation;
|
|
- tags, notes, policies, permissions, and review decisions;
|
|
- source subscriptions and cache intent;
|
|
- logical clocks and acknowledgements.
|
|
|
|
Large source generations follow the source replication protocol or remain
|
|
served by their owning device. File bytes move only through remote reads,
|
|
caching, file operations, or explicit file sync.
|
|
|
|
## Three planes
|
|
|
|
| Plane | Data | Direction |
|
|
| --- | --- | --- |
|
|
| Library | Devices, registry, policy, and small shared state | Merge between authorized peers |
|
|
| Source | Records, facets, content evidence, and search projection | From the ingest authority to subscribers |
|
|
| Bytes | File content and ranges | On demand or through explicit policy |
|
|
|
|
Separating these planes prevents a metadata edit from becoming a file transfer.
|
|
It also prevents one unavailable source from blocking unrelated library work.
|
|
|
|
## Pairing and trust
|
|
|
|
Pairing creates a direct trust relationship. One device generates a short
|
|
pairing secret. The joining device proves possession, the two nodes exchange
|
|
identities, and both record the relationship.
|
|
|
|
Traffic is encrypted between peers. Local discovery handles nearby devices.
|
|
The internet path attempts a direct connection and uses a relay when necessary.
|
|
Relays help packets travel. They do not become the authority for the library or
|
|
receive permission to browse it.
|
|
|
|
Device revocation is shared library state. A revoked device loses future access
|
|
to remote queries and bytes. Revocation cannot erase data that the device was
|
|
previously allowed to cache, so access policy should expose the smallest useful
|
|
scope.
|
|
|
|
## Source generations
|
|
|
|
Each source generation has one ingest authority. For a local filesystem source,
|
|
that authority is the node with access to the origin. For an adapter, it is the
|
|
node assigned to ingest that provider.
|
|
|
|
Subscribers can receive:
|
|
|
|
- a live query served by the authority;
|
|
- an on-disk source-store replica;
|
|
- a bounded metadata cache;
|
|
- dated frozen generations.
|
|
|
|
Generation updates are ordered by source watermarks. A subscriber applies them
|
|
in authority order. It does not merge two competing filesystem observations
|
|
with last-write-wins.
|
|
|
|
If an origin moves to another device, authority transfer is an explicit action
|
|
with a recorded handoff. Source identity survives the move.
|
|
|
|
## Assertions
|
|
|
|
Assertions represent knowledge that does not come from the origin, such as a
|
|
tag, note, permission, or review decision. Authorized devices can create
|
|
assertions independently while offline.
|
|
|
|
Every assertion carries provenance and logical time. Replicas merge changes by
|
|
the rule for that assertion type. A scalar preference may use last accepted
|
|
logical write. A tag attachment can preserve independent add and remove intent.
|
|
Security-sensitive policy can require explicit confirmation instead of silent
|
|
conflict resolution.
|
|
|
|
Filesystem modification time is never used to order assertion changes.
|
|
|
|
## Availability
|
|
|
|
Library sync keeps source presence separate from source availability.
|
|
|
|
| State | Meaning |
|
|
| --- | --- |
|
|
| Live | The origin and its serving node answer now |
|
|
| Degraded | Stored records remain available, but some queries or bytes cannot be served |
|
|
| Lost | The origin no longer answers; retained stores and snapshots are the evidence |
|
|
|
|
The interface can therefore show an offline drive, search its retained index,
|
|
and explain why opening a file is unavailable.
|
|
|
|
## Offline work
|
|
|
|
A device can browse attached stores and edit permitted assertions while peers
|
|
are offline. On reconnect:
|
|
|
|
1. Devices authenticate the existing pairing.
|
|
2. Each side exchanges library and assertion watermarks.
|
|
3. Missing changes are streamed and verified.
|
|
4. Source subscriptions resume from their own watermarks.
|
|
5. Availability is recalculated from current evidence.
|
|
|
|
No global leader is required for ordinary assertion sync. Source generation
|
|
still has an explicit authority.
|
|
|
|
## Remote queries
|
|
|
|
A paired device can serve source queries without copying the whole store first.
|
|
Queries are scoped by library membership, source grants, and subtree
|
|
permissions. Results identify their source and generation so a client can
|
|
detect stale cached data.
|
|
|
|
Search may combine local stores, cached catalogs, and live remote results. The
|
|
interface must distinguish a complete answer from a partial answer caused by
|
|
offline sources.
|
|
|
|
## Security boundary
|
|
|
|
Pairing grants a device identity, not unrestricted filesystem access.
|
|
Authorization is checked at operation time for:
|
|
|
|
- library membership;
|
|
- source and subtree scope;
|
|
- metadata visibility;
|
|
- byte reads;
|
|
- mutations;
|
|
- shares and mounts.
|
|
|
|
The same checks apply to graphical clients, CLI calls, extensions, and agents.
|
|
|
|
## Library sync is not file sync
|
|
|
|
Library sync can tell another device that a source contains a file. Remote
|
|
serving can open that file while the source is online. Neither action creates a
|
|
new durable copy.
|
|
|
|
[File Sync](/core/file-sync) is the explicit system that changes the placement
|
|
of bytes. Keeping it separate makes storage cost, deletion, conflicts, and
|
|
failure domains visible to the user.
|