Drive Sync Client

A folder's own directory

A folder record keeps its directory's identity the same way: the directory's id and birth, recorded when the record is minted, when it moves, and from the directory standing at its agreed path on each scan -- and from the one new directory an empty vault folder is read as renamed into, when it is gone from its place with exactly one new empty directory beside it, so the move that follows takes that directory as the vault's own.

• Proven: id and birth both match, on a strong volume. The folder follows its directory wherever it went, whatever is inside it, even when every file the folder had was moved out first, and onto a path the server is giving another folder in the same pass: the race over that name is naming's. A directory made where another was deleted can inherit its id (rm -rf A; mkdir B hands B A's inode on ext4) but never its birth, so a proven directory is never a stranger. The same pair says when the folder's directory is gone: its id standing on a directory with another birth is a later directory that took it, so the record forgets the id before the scan reads any directory, and learns the directory standing at its agreed path. A vault whose proven directory stands where the server is moving another folder waits for that move to claim it, and waiting is not leaving: the vault is present and its directory held, never taken up as a new plain folder that the vault's files would go up through in the clear.
• Id only (no birth reported, or a weak volume). The id corroborates what the folder's files propose and never claims on its own. A folder whose files point to one new directory while its id stands at another is held, present and unmoved: the issues panel names both places, and the hold lifts when the directory is back at the folder's own path or gone.
• No ids at all (FAT and exFAT, whose ids are positions). On a Mac a FAT or exFAT drive keeps each folder's own identity, its first cluster and its birth, which a rename, a move and a remount keep (Personality::fat_directories_hold), while its files' ids are positions as on any FAT drive. There a folder whose old name holds a new directory, one no folder record knows, while its own directory stands, by id and birth, at a directory no other folder holds, is that folder renamed: the user renamed it and then saved through its old name. Never a vault, never into or out of a vault's directory or a park, and only where the id and birth stand once (a freed cluster comes back after a remount, never with its birth). No other rule matches by those ids. Otherwise, and on Linux and Windows, a folder gone from its path is found by its files' bytes: the one new directory holding every file the folder has, at least two, each at its place inside the folder and with the bytes the engine last saw, is the folder renamed, so long as no other gone folder fits that directory and it holds no sealed file. A folder inside it goes with it under its own name, whatever it holds. Anything else (a folder of one file or none, one whose files were moved or changed in the same breath, two folders that fit one directory, a vault) is read as deleted, its copy on the server going to the trash.

One pass

The client is this loop, run over and over:

1. Read the change feed from the stored cursor (drive_changes), or walk the whole index (drive_index) when the server answers {reset: true} and on a store's first pass. The feed keeps only what changed within its retention window, and a cold start is answered from the window's first row rather than with a reset, so a store this client starts walks the index: a file untouched for longer has no feed row left to read. Every request asks for scope: mine: the client syncs the account's own Drive, never what another member shares with it. After any full walk the client asks drive_stat, by id, about every live record the walk did not return; one the server answers as missing (gone, or not the account's) reads as deleted. Nothing is decided by its absence from the walk alone. A store not yet marked as walked under this scope (OWN_DRIVE_ONLY) is walked this way once, which takes down anything of another member's it holds, each copy going to this computer's trash as a deletion would, an edit that never reached the server rescued into the folder it was made in. A store the client starts, at no feed position and holding nothing, is marked without a walk.
2. Absorb what the server reports into the remote side of entries. An observation, never an agreement.
3. Resolve names for this filesystem (below).
4. Walk the disk, hashing what the fingerprint cache says may have changed, and check the walk against the disk (below).
5. Pair what is on disk against what the engine believes it is called.
6. Decide, per entry, through the reconciliation matrix.
7. Order the decided actions into a safe sequence.
8. Journal every operation, with its idempotency key, before any runs.
9. Execute, with bounded concurrency and per-entry serialization.
10. Advance the cursor — last, and only now.

A look the disk was in

A walk is not one moment. It lists a folder's names, then looks at each file by its name, reading its identity and change time in that one look; and the directories are a second walk. A rename landing between two of those reads is seen half before and half after: a file moved from a folder not yet walked into one already walked stands nowhere, and read that way it was deleted; a swap landing between two looks shows one file at both names.

A file's bytes are hashed through one open handle that says which file it opened, and that neither follows a link nor waits on a pipe put at the name. A file that is not the one looked at is looked at again, up to three times. Where the volume shows file identities, a name that will not hold still that long is left out of the look. On FAT and exFAT, which show none, "the one looked at" means its size and time, and the last read is taken as it stands. A hash is cached only for the file it was read from, so a later look never reads back another file's bytes.

So once both walks are done, every folder is listed again and checked against what the walks handed on, by identity only: which file and which directory stands at which path. Size and time are not compared — a file being written to never holds still, and an edit is the next pass's to read. A file seen where it stands, gone since, or new since and nobody's is consistent; anything else — one file at two paths, a file the look saw elsewhere than it stands, a file a record owns standing where the look did not see it — tears the folders holding each of those paths and the folder its record last stood in. A check listing torn the same way differs from the walk too, so it errs towards another read, never towards a walk let stand.

Torn, the disk is read again, up to three times. A folder still torn after the third is held for the pass, with everything under it: no file in it is paired, judged edited, deleted, created or replaced, no folder in it is read as moved or deleted, and no local change the user made there is judged. A tear at the top of the sync folder holds the whole tree, since every path is under it. The rest of the disk is judged as read, and what the server changed still comes down: a download lands only on the file it was planned for, and a folder the server deleted still goes to this computer's trash, with any file in it that never reached the server rescued out first. A folder held three passes running raises folder_would_not_hold_still, naming it; the next pass that reads it whole syncs what changed there and withdraws the issue.

The trash of a folder the server deleted asks the disk the same checked way before it lets the folder's records go. Where the folder holds a sealed record, it waits for a look that holds still; a plain folder goes on with the look it has, since a plain child that look missed is met where it stands and sent as new.

On FAT and exFAT a file carries no identity, so only directories are compared, and only on macOS, where they keep one; elsewhere on those volumes the check stands aside.

When a pass runs

In the order the daemon checks: something on disk changed and has gone quiet (2 s); the watcher admitted it lost events; the poll interval elapsed (30 s); somebody asked for one. Anything that changes the server schedules an immediate next pass rather than waiting out the interval.

The last two conditions are what make the client work when the first two fail. A watcher that dies degrades this into a thirty-second polling client, not into a client that has stopped.

Standing down

A stop, a pause or an unlink reaches the pass in progress the moment it is posted, not when the pass ends. The engine asks whether to carry on (ExecEnv::stand_down) before each operation and before each chunk of a transfer: an upload reads its file just before it sends each chunk, and a download asks as each piece of its bytes arrives. Asked to stand down, the pass stops there:

• Operations it has not started stay queued, untouched: no attempt is counted and nothing is sent.
• An operation stopped part-way through a transfer goes straight back on the queue under its own idempotency key, as it was before it ran: its attempt count, retry time and last error are untouched, and it runs again from its start. A stand-down only ever comes before a transfer's completion call, so the server holds nothing of the stopped attempt but, for an upload, a half-sent session that is abandoned as a crash abandons it; the next run opens a new one. A download's partial bytes go with its spool. Nothing is counted against it, so pausing one large upload over and over never makes it read as work that keeps failing, and never lengthens its backoff.
• The pass still finishes its bookkeeping and advances the cursor: everything the batch implied is already in the journal. Its outcome says it stood down (ExecReport::stood_down), and a pass that stood down is never a quiet one.

• reading the change feed, or walking the index;
• the scan, including hashing what changed on disk (the whole folder, on a first pass over one that already holds files);
• deciding and ordering what to do;
• the whole-file hash an upload takes before it starts;
• writing the encrypted copy of a file in an encrypted folder, before its upload starts.

The daemon's control thread says it (Shared::send), for the tray, the CLI, the settings page, and the update thread installing an update alike; the command still waits in the queue, and the loop acts on it once the pass is out. A resume lifts a pause and never a stop. The simulator never asks a pass to stand down: its devices are stopped by being killed, which is the harder case.

Deciding what happens

Per entry, each side's change is one of: none, edited, created, deleted, or moved. Content and location are separate axes, so a remote move and a local edit compose into "apply the move, then upload" rather than fighting.

Three rules run underneath the whole table:

An edit beats a delete, in both directions. They are not symmetric outcomes: a delete that loses is recoverable from a trash, an edit that loses is gone. So the edit survives, even where that resurrects a file somebody meant to remove. That holds inside a folder too. A folder deleted here that holds a file edited elsewhere since this device last agreed on it comes back, at the server's name and place, holding only the edited file; what nobody touched goes to the trash on its own, and the user is told the folder came back for the edit. So it does for a file this device agreed on that a peer edited, wherever this device's round puts it: moved into the folder by the peer while this device left it where it was, or edited here too, the peer's edit stands where the peer put it and an edit made here stands beside it. A file whose move here keeps it out of the folder goes where it was moved; where the server's move wins, or this device only renamed it, the folder comes back for it. A trash decided before the edit was heard of stands down when it runs. New content counts the same: a file another device saved into a folder deleted here, which this device never had, brings the folder back holding it, and the user is told the folder came back for a file another device was still sending. This device's own files that were never sent go with the folder its user deleted. The server trashes a folder with everything in it, so an edit that reaches the server after this device last read the change feed and before its trash lands goes to the server's trash with the folder. A file or folder this device holds outside a folder it deletes is not handed to that folder: where a peer's move would land it there, in a race with this device's own move of it or on its own, it stays where it stands here and is moved there on the server. Where the folder comes back for an edit, what the peer moved into it stays there.

Deletes only ever win against unchanged content. A remote move with a local delete resolves as a delete only when the last-agreed hash still matches the remote head.

Nothing is adopted on a fingerprint's word. Whenever the engine concludes "these two are the same, no transfer needed", that comes from comparing content hashes. Size and modification time only decide whether it is worth hashing.

Conflicts

The remote head keeps the path the user knows. The losing local content is preserved beside it and uploaded as a new file:

Report (conflicted copy 2026-07-31 from MacBook).xlsx

Both versions exist on both sides within one sync round, and the conflict always lands in the issues panel. The copy is named after what the file is called on the server, unless that is the scratch name a peer's swap holds it under for a moment (.jd-swap-...); then it is named after what the file is called here.

Two saves of one file in the same window meet this way too, whichever reached the server first. A new version names the head it was based on — the content this device last agreed, and for an encrypted file the metadata blob it was sealed from — and the server refuses one whose file has moved past that (head_moved, or moved_since for a rename, docs/drive.md). The engine does not send a version over a head it has already heard moved; refused, it stands the edit down, takes the head the refusal names, and the next round plans the conflict. An encrypted version is encrypted afresh on every attempt, so each attempt's ciphertext is noted before it is sent: a head the server names that is one of them is this device's own save, landed while its answer was lost, and becomes the agreement rather than a conflict with itself.

A file or folder moved on both sides is judged half by half against the placement both sides last agreed: its folder and its name. A half only one side changed takes that side's value, and a half both sides changed to the same value takes it, so a rename on one side and a move on the other both survive, and two devices making the same rename keep any move only one of them made. A half both sides changed to different values is settled by the server's value, and the issues panel says which half of the local move lost. Every device ends at the same placement. With no agreement to measure against, the server's placement settles the whole move.

The mass-delete guard

If one round would delete more than max(50, 25%) of the settled entries — in either direction — that class of operations is withheld and a person is asked. Ransomware, a volume that mounted empty, and a legitimate cleanup are byte-for-byte identical from here, and there is no clever test that separates them.

What a round would delete is counted in records, not in operations: a folder's delete counts every synced record under it on both sides as well, which is what it removes. A folder deleted here reaches the round as a delete of each record in it; a folder trashed on the server arrives as one change in the feed and one local trash, and counts the same. A record under it on only one side — moved out here, or by the server — is moved out before the trash runs, and is not counted. The records it would remove are held with it, and named with it.

Only deletes are withheld, and only in the blocked direction; ordinary transfers in the same round still run. An unavailable sync root is a separate case: it hard-pauses rather than reading as a mass local delete. Each device's guard answers for its own side, so a large delete approved on one device is asked about again on every other device that would remove it.

The person is asked through one deletes_held issue for the device, so the tray shows Attention for as long as anything is held. It says how many items are held on each side (deleted here and not on the server, or deleted on the server or another device and not here), names up to three of them by the path both sides last agreed (a held folder stands for the held items inside it), says how to keep them — put them back on this computer, or restore them from the trash on the web — and names the held set: a fingerprint, sixteen hex digits of a SHA-256 over the sorted list of side and entity. The same items held the same way give the same fingerprint on every pass. The issue is a state, re-derived each pass and withdrawn the pass nothing is held; when the held set changes, its words and fingerprint change with it.

Going ahead is an approval of exactly the set the person was shown: the settings page's Approve these deletes button, or joinery-drive approve-deletes, which shows what is held and asks; given the fingerprint (joinery-drive approve-deletes <held-set>) it approves without asking, and only if that is still the set held. Either way the daemon is sent a control request, POST /approve-deletes with {"fingerprint": …}, which it refuses (409) when the fingerprint is not the one its last snapshot holds; the status answer carries the open question on its own as held_deletes (the issue's id, its words and held_set), outside the capped issue list. The approval is written to the store's meta table (deletes_approved), so a restart keeps it, and the next round reads it: if what that round would hold has exactly that fingerprint, its deletes go into the journal like any others; if anything was added, taken away or turned the other way since, nothing is let through, and the issue asks again under the new fingerprint. The approval is spent by the round that reads it, whether or not it matched.

A machine with no tray says so in the daemon's log, on stderr: one line when a new held set appears (its fingerprint, how many to remove here and how many to trash on the server), one when an approved set is carried out, and one when nothing is held any more.

A file's date

A file shows the date its content was last changed on every device it reaches, not the moment it arrived there.

An upload declares the date, read off the same open handle its bytes are sent from: the modified_time parameter for a plaintext file, and the mtime field inside the encrypted metadata for a vault file, whose date the server is never told (below). Both are written as a browser writes a date, 2026-07-20T12:34:56.789Z (jd-proto/src/mtime.rs). The server keeps a plaintext file's date to the second, so that is what the other devices get; a vault file's keeps milliseconds. A date more than forty years past this device's clock is not declared, because the server refuses one fifty years past its own and the upload would never land; the content still goes up.

A download puts the date on the file before anyone can see it. It goes on the spool after the last byte and before the rename (SpoolFile::set_modified), never on the path afterwards, where it would land on whatever the user had saved there in the meantime. The fingerprint the commit returns is read after the rename, so the agreement records the file with its date on it. Recorded before the date went on, it would describe a file that is no longer there, and the next scan would read every downloaded file as edited. The volume keeps what it can (two-second steps on FAT, whole seconds on HFS+) and the agreement records what it kept. A file put up with no date, as the browser's uploader puts one, lands with the time it arrived. A volume that will not take a date at all still takes the file.

Dates follow content and nothing else. An edit carries its new date. A rename or a move sends no content, so it keeps the date the content had, on the server and on every device. A date changed with the bytes left alone (touch) sends nothing, because the hash, not the date, decides whether anything changed. A fingerprint's time is nanoseconds since 1970 on every platform, Windows included, so the date a fingerprint holds is the date every other program on the computer reads.

Filesystem personalities

The engine is written against one clean tree: case-sensitive, NFC, legal names only. jd-vfs makes every real filesystem look like that, and reports what it could not.

A Personality records what a filesystem will do: case sensitivity, whether it decomposes Unicode, which characters and stems it refuses, whether it strips trailing dots, its name and path budgets, and its modification-time granularity.

This is not only about folded spellings. A file and a folder of the same name are one slot on every disk, whatever it folds, and the same rule settles it: whichever is already here claims it and the other parks.

A parked FOLDER takes what is inside it with it. Its children are held for exactly as long as it is: a parked folder has no directory of its own but still has a name, and a child left in the round would resolve onto whatever directory won the slot and land inside it -- one folder holding two folders' contents, with nothing on the disk saying so. The folder's own issue is the only thing the user is asked to act on, and the clash clearing releases the whole subtree at once. A parked folder that has a directory of its own is not held this way: what is inside it is genuinely there.

A folder given up here while its directory stands takes that directory to the OS trash, once nothing inside is owed elsewhere. Work the server does not have is carried out beside it first, and the give-up waits while something inside still has somewhere to go: a child the server has moved out, a file of another record's the user moved in, a file saved there and not yet sent. A sealed one waiting for a key holds it until there is one, and says so. A file carried out of its vault and held there -- sent before or not -- has nowhere on the server to go, so it does not hold the give-up: it is carried out beside the folder with the rest, its record following it, still held.

Which sibling wins: anything already on this disk claims first, then the lowest server id. A file held outside its vault claims before any of them: it stands where it is held, and a record that agrees on the same name cannot also have its file there. The consequence, stated honestly — two devices that downloaded a clashing pair in different orders keep different members of it. Both remain on the server and both devices report the clash. An entry recovers by itself, with no user action, as soon as the clash clears.

Three reasons, and they are told apart because the fixes differ:

Inside a vault it is ordinary, and the server cannot help. Uniqueness is enforced on the stored title, and an encrypted file's title is an opaque per-file identifier that is unique by construction — so two files in one vault folder whose real names are both notes.txt are a state the server cannot see, let alone refuse. The client is the only thing that can tell, and it resolves it by renaming: the lowest server id keeps the name, and every other holder becomes notes (2).txt, notes (3).txt and so on, applied by resealing that file's metadata.

The rule is the server id rather than anything a device can see for itself. Resolution order ranks materialized entries first, so a file already on disk here and not on the other computer would win here and lose there — each device renaming the other's file, neither ever holding still. An id is the same number everywhere, so every device arrives at the same answer without having to agree first. An entry the server has never seen loses to one it has: it has no id to compare and nobody has been told about it, so renaming it disturbs nothing.

A parked entry keeps recording the placement it is waiting for, and that record is not ownership of the path: it holds no bytes there and never did. Whatever asks "does this path belong to another entry" has to skip parked entries (Entry::holds_a_local_file), or the file that won the name can never upload again — its transfer is skipped over every candidate path as somebody else's, found nowhere, dropped as overtaken, and planned again on the next pass. Nothing fails, nothing queues, no issue is raised, and the device never goes quiet.

When the question is answered honestly and the path really does belong to another entry, the transfer still finds nothing — but for a different reason, and the difference decides what may be thrown away. A file found nowhere is gone, and an identity minted only because the scan saw an untracked file has nothing left to be about, so it is dropped. A file whose every candidate was refused on the name is still on the disk, and dropping its identity would say otherwise: the next scan finds the same untracked file, mints another identity, and arrives back at the same refusal. So a refusal on the name leaves the entry alone. Deciding who gets a contested name belongs to naming, and an identity minted after naming has already run for its pass can only be judged by surviving into the next one — where the loser is parked, visibly, under unsyncable. Nothing is raised from the transfer itself: the park carries the issue, and unsyncable is one of the kinds a pass withdraws again once the state ends.

Moves are ordered by what they wait on. A rename into a name another mover still holds waits for that mover; a folder moved into what is currently its own subtree (a parent swapped under its child) waits for the move that takes that folder out, and with nothing on that chain moving it is left out of the round until the chain changes. The local move refuses the same shape itself rather than asking the disk for a directory to move into itself. A folder being created on this disk takes a slot the same way a move does: it waits for the mover holding that slot, and a move into it waits for it to exist. When those two wait on each other (the server replaced a folder with a namesake and moved the old one inside it) the mover is parked under a scratch name in place, the folder is created, and the mover moves in. A local park is recorded as the spelling on disk, never as the agreement, and naming leaves a parked entry alone. The walk does not read inside a scratch directory, so while a park stands -- its finish refused, or a pass stopped between the two -- nothing under it is judged: it is all held, present and unmoved, until the finish lands. What stands in it is known by identity alone: a file the user carries out of the park is followed to where it went, and a file carried in from outside is held with the park until it ends. A park this device made that nothing is left to finish is finished: moved from where it stands to where the server has it, since the name it left belongs by then to the other half of the swap. That finish is judged as any arrival is: a name this disk cannot hold, or one a sibling here already holds, gives up the copy here as it would for any folder renamed to such a name, and a finish overtaken for any other reason is said until the park ends. A move into a name whose holder is still being parked out of it waits for the park, and a park's finish waits for its own park to land.

A rename the server refuses because the name is taken lands beside what holds it, under a conflict name, and the disk follows; what holds a name this device is renaming away is waited for instead. A server that refuses without saying why (one that does not say its refusals are reasoned, below) is read the same way for a folder whose name this device knows another live folder holds there, one it is not itself renaming away: that folder's arrival waits on this one's directory leaving the name, so neither would ever move. Any other folder rename refused without a reason is withdrawn, and the next pass derives it again from the disk until the name frees up.

A new file whose upload is refused because its name is taken goes up beside the holder under a conflict name. Refused without a reason by a server that does not say its refusals are reasoned, it does so only where the server lists something under that name in that folder; otherwise the upload is withdrawn and planned again from the disk, never sent as a conflicted copy of itself beside nothing. The file on this disk takes the conflict name where it still stands at the name refused; one the user moved or renamed after the upload was planned is sent from where it stands and left there, and its move goes up on the next pass. An upload whose bytes did not all arrive (upload_incomplete) is sent again whole.

Every refusal is read by its reason (Drive). A server that answers its feed and its index with refusals: reasoned gives every refusal one, and is taken at its word: not_found, parent_not_found and move_into_self plan the work again from what is there, a trash answered not_found is done, the server's own state (no_room, storage_failed, drive_disabled, signed_out, action_failed) is tried again on the backoff, vault_needed is held like a standing refusal (only an unlock window lifts it, a window belongs to a browser session, and this computer never holds one), and anything else keeps its status's reading, held where it stands. Each action refused is held on its own, so a file with two things refused (a Private file edited here and carried out: its move and its new contents) asks about neither again until something it was asked about moves. A refusal with no reason from such a server is withdrawn and planned again, never read as a name clash, and its issue says it came without a reason. The store keeps what the latest answer said, so a server that stops saying so is read the older way again.

A create claims a directory already standing at its path — a stand-in it was handed, or its own earlier attempt — and waits while that directory is one another live folder still holds, so the folder replacing a namesake never takes over the directory of the folder it replaces. A file in the way is moved aside instead, because nothing else is coming for it. The park, the create and the move that finishes them are three operations that fail one at a time, and the finisher counts its park from the moment it is queued rather than from the moment it lands: a park whose rename is refused keeps the finisher that is going to put it back.

A scratch name (.jd-swap-…) is a different kind of park: one step inside one operation, never a placement anyone agreed on. The planner mints one to break a rename cycle and a remote move mints one as its last resort when both orders of rename-and-reparent are refused; the operation that minted it knows its own park by its key and finishes from there, and the park is recorded as remote alone. The planner's park says where its finisher was decided against, as the finisher does, so a peer's rename that reached the server first refuses it with moved_since. An entry standing under another operation's scratch name in that folder is parked from that name, since nobody chose it; a peer that has since moved it on still refuses the park. A finisher whose park is still unanswered asks the server where the entry is before its first call: the park may have landed with its answer lost, and the finisher then starts from the scratch name. A move is two calls, rename and reparent, and an op retried between them recognises its own half-done work the same way: the new name in the old folder, or the old name in the new one, is its own and it finishes from there rather than standing down as somebody else's move. A first attempt claims nothing, and a move the server has already completed has nothing left to finish; both fall to the ordinary path. While an operation is open on an entry, or the entry wears a scratch name on the server and the pass's put-back owns it, naming leaves that entry's collisions alone: its agreement still names the slot it is leaving, and a duplicate or clash read against that slot would release the copy the operation is about to place. A verdict about the entry's own name still stands. An entry this device has never agreed on that wears another device's scratch name is not landed here at all, not even by a download planned before the park arrived: under the scratch name the walk cannot see it, and the next pass would read it as deleted here. It waits for the park to end and arrives under its real name. A park nobody is coming back for — its operation withdrawn, or dropped after a kill — is put back by the next pass under the name both sides last agreed, or the next free one there, and said as a reconcile issue. It stays in the folder the server has it in now, and which folder it ends in is settled on the next pass as a move made on both sides is, against the placement both sides last agreed. The put-back is a rename on the server of something the disk has not followed, so it too is recorded as remote alone, and the ordinary local move brings the directory along on the pass after.

One shape of it is the client's own bookkeeping rather than anything the user can act on, and is repaired without being shown. A device that creates a file or folder gives it a provisional identity before the server has named it; if the name is taken in the meantime the create is refused, and the real item then arrives from the change feed as a second record of the same path. Left alone the two are rivals — the provisional holds the name, the real one is refused against a name identical to its own, and neither can ever supersede the other. The pass folds a provisional into the real item at the same placement before naming runs, so the pair resolves itself. What survives is the real identity, with whatever was last agreed about it left intact, so an ordinary edit stays an edit instead of becoming a conflicted copy.

Encrypted files and folders

This section is about Fortress folders — the client-custody level, where the device holds the keys. Private folders are not synced to computers: their bytes are opened by the server inside the owner's unlock window, the window belongs to a browser session, and a sync client never holds one. Both exports carry protection_level and a syncable flag (an export without the flag reads as syncable). The client parks a Private tree's top folder out of scope, as it parks a vault on a FAT drive, and everything under it waits with it: nothing is downloaded or created there, nothing saved there is uploaded, and nothing already there is moved or removed. A folder that synced before it was made Private keeps its copy on the computer, no longer synced, and one issue (private_not_synced) says so; the Drive UI says so on the folder. A file carried out of the folder on the computer is sent as a move, which the server refuses until the owner's window is open (vault_needed, held like a standing refusal), and a file never sent goes up from where it now stands. Made Standard again, the folder syncs again, and what was done to it on the computer meanwhile goes up.

Fortress content syncs like anything else, with one difference that runs through everything: the engine works in the plaintext domain and the server only ever sees the ciphertext one. For an encrypted file the server holds a placeholder name (enc-<content id>), the hash and size of the ciphertext, and no modification time at all — a plaintext timestamp would tell it when somebody last worked on the file. The real name, mime, size and mtime live inside the encrypted metadata blob, under the file's own key.

The old copy goes to the trash rather than away, which is what trashing the source means; emptying it stays the user's decision.

Not yet built: encrypted thumbnails.

The vault key

The key that opens encrypted content is the Drive vault's X25519 secret key. It reaches the device once, during the browser link ceremony, sealed to a keypair the device generated for that purpose, and goes straight into the operating system's credential store — or, on a computer with no store the client can use (Linux in the default build), a mode-0600 file in the state directory. A session that cannot open a credential store the computer has is not given it at all (Credentials). The daemon reads it back once at startup and holds it for the life of the process — reading it per file would mean a keychain prompt per file on macOS.

Only the secret half is stored. The public half — which is what file-key grants are sealed to, because the sealing scheme mixes it into its key derivation — is recomputed from the secret on every start. A pair carried as two stored fields can be got out of step by one bad write, and the symptom is every unwrap failing with an error that names nothing.

A device with no vault key is an ordinary, supported state, not a degraded one: an account with no encrypted folders never needs one. So none of its failure modes are fatal. A key that is missing, unreadable, or not a vault key at all produces a warning naming which of the three it is, and the daemon starts and syncs everything else.

A vault key comes only from the computer's own link. A link that hands no vault key over — the box not ticked, a session that cannot keep one, a key that would not open — removes any vault key the computer held from an earlier link, so a key of another account, or of another installation, is never carried into this one. At start the daemon uses a stored key only when its config says the link handed one over (vault_enabled), and asks the server once (vault_client_probe) whether the key can be the account's:

• the account has no vault: the key is not its, and is not used;
• the device row says this computer holds the account's key, and the one here has another public half: it is not the key this computer was handed, and is not used;
• the account's key is another one and this computer is no longer listed: that is a rotation, the retired key still opens what it opened before, and it is used (A rotated vault key is noticed, above);
• the server cannot be asked or will not say: the key is used, and the log says so.

Unicode normalization

Names are composed at one boundary — Vfs::read_dir returns NFC, always — because a volume that hands a name back in a different normal form than it was written reads as a rename on the very next scan, and two devices then rename the file at each other forever.

Crash consistency

The client may stop at any instruction.

Downloads stream to a spool file, are verified, then fsynced and renamed onto the target. A partial download is never something a user can open. The rename is guarded by the fingerprint the engine decided against, so a file edited while the download was in flight is not overwritten — the download is withdrawn and the local edit wins. A file the user saves at a download's name before that download has ever landed here is a new file of the user's, never the download's edit: a rename this device sends for a file not yet downloaded moves it on the server alone. A download's byte count comes from the bytes that reached the spool, never from a header. It lands in the directory that stood at its folder's path when the spool was opened, and only where that directory is its folder's own: on a volume whose identities hold, a directory at the folder's name with another id and birth (the folder renamed away and a new one made at its old name) is another folder, and the download is refused there. A folder the user moved or replaced while the bytes were in flight is never made again at its old name (VfsError::FolderMoved), and a spool whose folder is not on the disk when it opens is refused (VfsError::NoFolder). No engine write makes a directory it was not asked to make: a move refuses a destination folder that is not there, and a folder create makes one level, never a missing parent. The download or move stands down and the next pass places it where the folder now is.

The spool lives with the state store, so a sync root on another volume (an external disk, a second partition, a mount point inside the root) cannot take the rename. The commit then copies the bytes beside the target under .jd-land-<op>-<token> (never over a file already standing there), makes them durable, asks every gate again, because the copy is the widest window the commit has, and renames them into place on the target's own volume. A landing name that outlives its commit is trashed by the next walk unless its op is still open in the journal; the server still holds the bytes, so the download is simply planned again.

Uploads commit their hash at init, read from the same open handle the bytes are sent from. A file whose bytes change mid-upload fails verification at completion and re-queues. After the transfer the fingerprint is re-checked: unchanged means record the agreement, changed means leave the entry pending so the newer content is still sent.

The indicator is computed from the store on every request, not accumulated as passes run. An incremented counter drifts, and one missed decrement means a tray that spins forever, which teaches the user to ignore it.

What decides unsyncable is the entry's own LocalStatus, not the naming pass's report of what it just did: an entry already settled as unsyncable is not re-reported each pass, so reading that report as the full set withdraws a complaint that is still true.

Work that keeps failing is a state too. Once an operation's backoff reaches its fifteen-minute cap it is tried every quarter of an hour for as long as it fails, and one keeps_failing issue says how many operations are stuck and why the first of them fails; it is withdrawn on the first pass that leaves nothing at the cap. It is one issue for the device, not one per operation: an outage on the server fails every queued operation at once, and a thousand identical issues would hide the one that matters.

A record of something the server has deleted is never a fault. An entry with no way back to the root normally means this device has lost its record of a folder that still exists, which is a hole in the store's picture: the engine re-derives from the index, and says so as store_inconsistent if the index cannot account for the parent either. Entries carrying remote_deleted are excluded from that count. There is no path to resolve for them and no work to plan against them, and counting them starts a loop rather than a repair — drive_index returns trashed entities on purpose, so the walk re-absorbs the tombstone that provoked it and the next pass finds it stranded again, walking every entity on every pass for the life of the client and standing on a claim that items need attention when all of them are already deleted.

The records themselves are kept. Discarding them was tried once and the soak run that followed lost seven files where the run before it lost none — they are what ties a local file to what the server already holds. They stop being counted, not stored.

The ceremony is started one of two ways, and both store the approval through the same code. joinery-drive login <url> runs it in a terminal. A daemon started before the computer is linked runs it from the settings page instead: the site's address, the approval in a signed-in browser (the page shows the code and opens the approval page), then the folder to sync, then syncing starts in the same process — see The settings page.

Where things live

Updates keep their own two things: update.json in the config directory (which channel this computer follows; see Updates) and an updates folder in the state directory (downloads, the start marker, what the updater remembers).

JOINERY_DRIVE_HOME overrides all three at once. One variable rather than three, because three would allow a config pointing at one account and a state store holding another — which reads as mass corruption on the very next pass.

Credentials

Three secrets: the API secret, the device X25519 key, and (when enabled) the Drive vault key.

• macOS — the login Keychain. Windows — the Credential Manager.
• Linux — a mode-0600 file in the state directory, by default. The Secret Service needs a desktop session and a build-time system package, and the daemon explicitly supports headless servers. Build with the secret-service feature on a desktop to use the keyring instead.

The shared name com.joinery.drive holds the items of an installation linked under it. An installation with a config or a state store of its own and no API secret under its own name or in its file looks there when a secret is not found, and moves all three items it finds to its own name, deleting them from the shared name, so nothing is left there for a second installation to read as its own. A new installation (no config, no state store) and one with a secret of its own both leave the shared name alone: what is there belongs to another installation. The shared name holds one installation's items; of several that look there, the first started takes them, and the others are linked again.

A keychain is only available in a session somebody has logged in to. Over SSH, or at boot before a graphical login, the login keychain is locked and no prompt can be shown to unlock it — macOS answers "user interaction is not allowed". In such a session:

• The API secret and the device key go to a mode-0600 file, as on a machine with no store, so plain folders link and sync.
• The vault key is not kept at all. On a computer that has a credential store, the key to encrypted folders lives in it or nowhere. login (and the settings page's first run) offers no public key for the vault to be sealed to, so the approval page does not offer encrypted folders, and says to run joinery-drive login from the desktop session to enable them. A computer with no credential store at all keeps the vault key in a file like the rest: there is nowhere else for it to be.

Installers

sync/packaging/ builds them, one script per operating system; its README holds the prerequisites, commands and signing settings.

The Windows installer waits for the programs it replaces or removes to exit — the daemon's stop lands at the pass's next safe point (Standing down), usually at once, though hashing or encrypting a large file holds it until that step ends — and never skips a file it cannot write. If one is still running after a minute it stops without changing any file; the daemon still stops at that safe point (the request cannot be withdrawn), and the installer says so and that it can be started again from the icon's menu.

Beside each installer the script writes the update payload the installed client applies (joinery-drive-release pack; see Updates), packed from the same files the installer carries.

Every artifact carries the workspace version from sync/Cargo.toml — the version --version prints and the daemon sends as client-version — and the daemon names its platform as client-app (joinery-sync-macos, joinery-sync-windows, joinery-sync-linux), so the API's minimum-version gate can hold back one platform's release on its own. Signing is configured by environment variables and skipped without them: ad hoc on macOS, unsigned on Windows and Linux.

The program

joinery-drive login <instance-url> [--device NAME] [--root PATH]
joinery-drive daemon
joinery-drive settings
joinery-drive status | issues | dismiss <id>
joinery-drive approve-deletes [held-set]
joinery-drive pause | resume | sync-now | stop
joinery-drive autostart on|off
joinery-drive check-update
joinery-drive unlink
joinery-drive --version

Everything except login and daemon is a request to the running daemon, so every answer is what the daemon actually believes rather than a second opinion. status exits non-zero when the client is stopped or not linked, so a monitoring script does not have to parse prose. stop comes back once the daemon is gone, so a script that stops it and then touches its folder or its state does not race a pass still finishing. A pass hears a stop between two operations or two chunks of a transfer; one still going a little over a minute later (past a stalled download's silence limit) makes stop exit non-zero, naming the process, and it stops on its own at its next safe point.

login takes the same addresses the settings page does, checked by the same code before anything is sent: a missing scheme is read as https://, and plain http:// is refused except to this machine itself (localhost, 127.0.0.1, [::1]), saying why — the credential the link hands over would cross the network unencrypted. While it waits, it prints the approval address and the code either way, and says "opened in your browser" only where there is a desktop and a browser was asked to open it; otherwise it tells the person to open the address themselves, on this computer or any other. settings opens the settings page in the browser, and prints its address when there is no desktop to open it on.

daemon runs whether or not the computer is linked. With no config it serves the settings page's first-run setup instead of syncing, and starts syncing as soon as the setup finishes — or as soon as login, run in a terminal, writes a config. A config that exists but cannot be read is still refused at startup: falling back to defaults would point a client that had been syncing one folder at another, and the first pass would read that as everything having been deleted.

One daemon runs per home. It takes an exclusive lock on daemon.lock in its state folder before anything else, and writes its process id beside it in daemon.pid (a Windows lock keeps other handles from reading the locked file). A second daemon on the same home — one started by hand beside autostart's, a user's own restart loop, a copy that relaunched itself when its program file was replaced — waits up to ten seconds for the holder to exit, then prints that joinery-drive is already running (with the holder's process id) and exits with success, so neither launchd nor systemd starts it again. Two daemons on one home would drive one folder from two stores, each reading the other's work as a change, and turn files into conflicted copies of themselves. The lock is the operating system's, so it goes with the process, a crash included. Where the state folder cannot be locked at all, the daemon says so and runs unguarded. A daemon relaunching itself (an update, a replaced program file) lets go of the lock only after its control endpoint is gone, and the copy watching an update come up does not read a new copy that stood down for a running daemon as a failed update. Because the lock goes last, after the state store and the endpoint, it is what stop, unlink and login wait on to know the daemon is gone; where the state folder cannot be locked, they wait for its control channel to stop answering instead.

A supervisor that restarts the daemon after every exit, success included (s6, runit, a container's restart policy), restarts a copy that stood down every ten seconds or so for as long as the other one runs; launchd and systemd as installed here do not. The other side of that: when autostart's copy is the one that stood down (a daemon was already running by hand), quitting the hand-run one leaves nothing syncing until autostart runs again, at the next login.

• The page's three files (/settings, /settings/app.css, /settings/app.js) are the only thing served without a credential. They are compiled into the binary and hold no data; everything the page shows it asks for.
• Every request without the token must carry exactly one Host naming 127.0.0.1 or localhost on this port. That defeats DNS rebinding — a site pointing its own hostname at 127.0.0.1 still makes the browser send its own name.
• A request carrying a ticket or a session must come from the page's own origin: an Origin header, when present, must be http://127.0.0.1:<port> or http://localhost:<port>, and Sec-Fetch-Site, when present, same-origin or none. Another site's page, or another local web server's on a different port, is refused.
• No answer ever carries an Access-Control-Allow-* header, so no other site can read one or get a preflight approved. Every answer carries a content security policy (scripts, styles and fetches from the page's own origin only, no framing), X-Frame-Options: DENY, nosniff, and no-store.
• A query string is never a credential: a token or session in a URL is simply absent.

The tray

1. Your site — the address (a missing scheme is taken as https://; plain http:// is refused except to this machine itself) and a name for the computer, which ends up in conflict-copy names and so keeps to characters every disk accepts.
2. Approve — the link code, the approval page opened in the browser (and a link to it), and polling every 3 s. A network failure while waiting is said and retried; a denial or expiry returns to step 1 saying which.
3. Folder — prefilled with the default sync root. Refused: the whole home folder, a disk's root, and anywhere that holds or sits inside the client's own config, state or logs — checked both as typed and as the path resolves through symlinks, so a link to the home folder is the home folder. A folder that already has things in it asks for confirmation first, because they will be uploaded. "Start Joinery Drive when I log in" is on by default.

Updates

The client keeps itself current from one signed feed that every installation reads, whatever instance it is linked to (spec D19): instances stay zero-config, and only one place has to sign anything. The code is jd-daemon/src/update/ and, for everything that differs by operating system, jd-platform/src/install.rs.

The feed

One JSON manifest per channel, at https://getjoinery.com/drive/updates/<channel>.json, with a detached signature beside it at the same address plus .sig:

{
  "format": "joinery-drive-update/1",
  "channel": "beta",
  "version": "0.3.0",
  "minimum_supported_version": "0.2.0",
  "release_notes_url": "https://getjoinery.com/drive/releases/0.3.0",
  "artifacts": [
    { "os": "macos", "arch": "universal", "kind": "update",
      "url": "https://…/joinery-drive-0.3.0-macos-universal.update.tar.gz",
      "size": 9123456, "sha256": "…" },
    { "os": "linux", "arch": "x86_64", "kind": "deb", "url": "…", "size": …, "sha256": "…" }
  ]
}

The .sig file is base64 Ed25519 signatures over the manifest's exact bytes, one per line. Exact bytes, because a signature checked against a re-serialization is a signature over something else; more than one line, because that is how a key is rotated (below).

Only kind: "update" is ever installed: the payload this client knows how to put in place, which is the app bundle on a Mac and the program's files elsewhere. The other kinds (dmg, installer, deb, rpm, tarball) are there for the download page and are never fetched by the client. A Mac matches its own architecture or universal; everywhere else the architecture must match exactly, so a native ARM install is never replaced by an emulated x86 one.

update.json in the config directory chooses the channel (default beta), can name another feed address (feed_url), and can turn off automatic installing (automatic: false still checks and reports). Off means off, a required update included — one the feed's minimum_supported_version says this copy is below: the status leads with "A required update is waiting", and it installs when somebody asks (check-update, or the settings page's button). It is apart from config.json because it belongs to the installed program, not to the link: unlinking forgets the account, not the channel. It is read when the daemon starts. A damaged file is reported in the status and the defaults are used.

When it looks: 30 seconds to 5 minutes after the daemon starts, then every six hours, each time at a random point an hour either side, so a fleet waking at the same moment does not arrive at the feed together. After a failed check, again in 30 to 60 minutes. joinery-drive check-update (control `POST /check-update`) checks at once.

What it believes, in order:

1. The signature, against the keys compiled into the build. Nothing in an unsigned document is read, not even its version.
2. The channel inside the document must be the configured one. Every channel is signed by the same key, so without this a stable client served the beta document would accept it.
3. The version must be higher than the running one. It never installs a lower or equal version, so an old manifest replayed by anybody is inert. Versions are MAJOR.MINOR.PATCH with an optional -alpha.N, -beta.N or -rc.N, ordered as the server's upgrade gate orders them: a pre-release before its release, alpha before beta before rc.
4. The download's size and SHA-256 against the manifest, while it downloads, into a .part file renamed only once both match.
5. The payload's format (below), unpacked beside what it replaces.
6. The new program itself: the staged daemon is run once with --version and must print the version the manifest promised, before anything is swapped. The first line of --version is therefore a contract: its last word is the version (joinery-drive 0.3.0), and the wording changes only together with the check that reads it (update::preflight). This is what catches a program that cannot run here at all — the wrong architecture, a signature the system refuses, a missing library — which never reaches the code that would count a failed start.

Keys

jd-daemon/src/update/trusted_keys.txt lists the Ed25519 public keys the client accepts a feed from, one base64 key per line. It is in the repository so that adding or retiring a key is a commit anybody can read, and so that nothing a local process writes can teach the client to trust somebody new. A feed signed by any listed key is accepted. A build whose list is empty checks no feed, says so in its status, and installs nothing.

A rotation: add the new key to the list and ship a release; sign every feed with both keys (joinery-drive-release sign --append) while clients move; then remove the old line and stop signing with it.

What each kind of install does

Installing is a restart

The update thread is a third thread beside the sync and control threads. It holds no database handle. To install, it hands the staged update to main and posts Stop; the pass in progress stands down at its next safe point, and main swaps the files once the store is closed.

Then the daemon starts again from its live path:

• Under the LaunchAgent or a systemd unit, it exits with status 75, which both bring back (KeepAlive on an unsuccessful exit, Restart=on-failure). Supervision is judged precisely, because a daemon started by hand that exited expecting a restart would simply be gone: the LaunchAgent sets XPC_SERVICE_NAME to the bundle id, and a systemd unit's own process is the one SYSTEMD_EXEC_PID names (on systemd older than 248, a process in the joinery-drive.service control group). Any unit's own process exits to be restarted, even in a unit an administrator wrote: systemd stops everything in a unit when its own process exits, so a replacement it started itself would be stopped with it.
• Otherwise (Windows, whose Run value only runs at login, or a daemon started by hand) it starts <exe> daemon — the command autostart runs — detached, and stays to watch it come up.

The tray watches its own executable and, once the file at its path is a different file and has looked the same twice in a row, starts the new copy and exits. The daemon does the same when its file is replaced underneath it — by a package manager, or a new app dragged over the old one — once the new file has answered --version. The second look keeps a half-written file from being started.

When the new copy does not start

Before the first file moves, the old daemon writes updates/pending.json: the two versions, every swap, and whether syncing was paused. The new daemon reads it before anything else it does and counts the start. It clears the marker, and the old copy is deleted, once its sync loop has run the startup recovery and published its first status — or, on a computer not linked yet, once the first-run setup is answering.

• Under a supervisor, every start is an attempt. Past three, the new copy puts the old one back itself and exits to be restarted as the old one.
• Watched by the old process, a new copy that exits, or is not up within two minutes, is put back by the old process, which then starts itself again.
• A marker found mid-swap (the installing process died) is put back on the next start, from wherever the swap stopped; each platform's swap can be undone from any point. Windows has one gap: between renaming the old .exe aside and the new one into place, two system calls apart, there is no program at the live path.

In the status answer

GET /status carries an update object once the computer is linked, which joinery-drive status prints as one line and the settings page shows in its Updates section, beside a Check for updates button (POST /check-update; a check that cannot run, in a build with no key, answers 409 with the reason):

Publishing a release

joinery-drive-release (in jd-daemon, never shipped) does the publisher's half:

joinery-drive-release keygen --out PATH                      # once per key
joinery-drive-release pack --out macos.update.tar.gz "Joinery Drive.app"
joinery-drive-release pack --out linux-x86_64.update.tar.gz joinery-drive joinery-drive-tray
joinery-drive-release manifest --channel beta --version 0.3.0 \
    --base-url https://getjoinery.com/drive/updates/files \
    --artifact macos:universal:update:macos.update.tar.gz \
    --artifact linux:x86_64:update:linux-x86_64.update.tar.gz \
    --artifact linux:x86_64:deb:joinery-drive_0.3.0_amd64.deb --out beta.json
joinery-drive-release sign --manifest beta.json --key PATH    # or JOINERY_DRIVE_UPDATE_KEY=PATH
joinery-drive-release verify --manifest beta.json --trust <public key>

The signing key comes only from --key or the file JOINERY_DRIVE_UPDATE_KEY names; there is no default location. A key file other accounts can read is refused, and so is one inside a git working tree that git would track. The file is base64 of the 64-byte libsodium form (seed, then public key), the same form as the platform's release key, so one file works here and with PHP's sodium_crypto_sign_detached. sign checks its signature against the public half before writing it, and refuses a manifest no client would accept; manifest refuses to write one.

The payload is a gzipped tar in a subset this tool writes and the client reads: plain ustar headers, folders, regular files, and Unix symlinks, with sorted entries, zero times and owners, normalised modes, and a gzip header with no name or time — so one build always packs to the same bytes. The client refuses anything else by name, any path that leaves the folder it is unpacked into, anything written through a link the archive made, and more than 2 GiB unpacked.

Tests

The update modules carry unit tests in cargo test -p jd-daemon and -p jd-platform (and so in sync_engine_gate.sh): manifest parsing; good, bad, stranger's and tampered signatures; rotation with either key; the channel check; downgrades; an unknown platform; the decision for each kind of install, including a required update waiting while automatic updates are off; a folder update that leaves out the tray; the built-in key list parsing; the payload round trip, determinism, and every escape; each platform's swap undone from every point; the start marker's count, rollback and confirmation. jd-daemon/tests/update_e2e.rs serves a feed from 127.0.0.1 signed with a key made for the test, carrying the real joinery-drive the build produced, and checks that it is found, downloaded, run once, and swapped in over a stand-in install (a program folder, or an app bundle on a Mac); that the real new binary, started the way autostart starts it and unable to finish starting, puts the stand-in back after three attempts; and that a tampered payload, a stranger's signature, an older version, a package-managed install, and a binary that is not the promised version all leave the install untouched.

Testing

The edge-case space is combinatorial, so the client is built around a deterministic simulator rather than a list of hand-written cases.

jd-sim provides a virtual filesystem with a per-OS personality (case-folding, NFD, coarse mtimes, inode reuse, scheduled failures), a mock server implementing the documented contract (cursor feed with resets, chunk resync, dedup, quota, idempotency replay, declared modification times, key grants that arrive and are withdrawn on the feed, a vault key rotation), a controlled clock, and a network that loses, delays, reorders, and duplicates. Every run is reproducible from a seed, and seeds that found bugs are frozen in the repository.

Two invariants are asserted around every pass, not at the end of a run:

1. Convergence — each device's disk and the server agree.
2. Nothing committed is lost — anything that was on a disk before a pass and is gone after it must still be reachable: the server's live tree, its version history, another device, a trash, or a conflict copy. The mock server keeps every version it has ever been given, which is what makes this a question with a checkable answer rather than a hope.

The soak environment