spacedrive/docs/core/library-sync.mdx

---
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;
- locations 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.