Skip to content
C.W.K.
← C.W.K. Quests
🔺

Delta Quest

New: 2026-11-13Updated: 2026-11-12

The data channel we own — how a family of Macs stopped pushing files through SSH and built a service it can read, fix and measure

A drawing app asked another Mac for 384 thumbnails, one SSH command each, and 152 of them never came back. The cause was a sshd setting that throttles bursts of new connections, on a daemon the family did not write and could not fix. Delta is the answer: one small service per Mac, written on Python's standard library, that serves its Mac's files to the others, reads theirs through a cache that follows its source, and moves files and folders resumably and verified. This quest walks it from the code: why macOS lets Apple's own python reach the house network when a conda python cannot, how a share is a root class and an app's data is a child, how the route to a peer is chosen from verified facts instead of a machine name, how a caller is identified with no copied password, why a stale copy must say it is stale, why a transfer is never done on silence, and why a write to another Mac's app is sent at most once.

8 tracks · 43 lessons · ~10h · difficulty: intermediate-to-advanced

Level 0Loose File
0 XP0/43 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete
Delta is the CWK family's own data channel between Macs, born on 2026-11-09 after SSH failed one burst too many. Every family Mac but the household's runs one Delta, under launchd, on Apple's /usr/bin/python3 and nothing but the standard library. It serves that Mac's shares to the others, reads theirs for the apps on its own Mac, and moves files and folders between Macs with live progress. You start with the incident and the doctrine that came out of it: SSH carries commands, data rides a service the family owns, and the one process that dials the house network is a platform binary that macOS's Local Network privacy lets through. Then the shape of what is served: a DataShare root class with a small vocabulary, a plain tree and the home folder as children, refusals that are rules about places (credential stores and the folders macOS guards with a prompt), and app children that ship in the app's own repository and fail alone. Then the wire: same house means an address on-link with one of this Mac's live interfaces, and the route prefers the fastest wire first: a Thunderbolt cable, then Ethernet, then Wi-Fi, then the tailnet; identity is the tailnet's own roster, tickets are minted only where identity was proven, the shared LAN pins each Mac's certificate, and loopback carries a local token because loopback is not an identity. Then the receiving side: a content-addressed cache whose every entry is revalidated by the owner's validator, a stale answer that is labeled stale, and a commit made before the last byte goes out. Then the bytes: jobs that outlive a terminal, 16 MiB chunks over parallel workers and bundles of small files, a stall timeout instead of a deadline, partials that resume chunk by chunk, links, patterns and folders that will not open, and the honest table against rsync and scp, including where rsync still wins. Then the two-way cases: a named pair that tells a deletion from a new file by an archive both sides agreed on, and a write call that an app's owner carries out itself, sent at most once, with three outcomes told apart by whether the request left. It ends with operating it (one service per Mac, everything that accumulates bounded, one test per failure mode) and with a small channel of your own. Conceptual open-sourcing: the architecture is the deliverable, never a repository to clone.

Tracks

  1. 01🔧Why Our Own Channel

    0/5 lessons

    152 blank thumbnails, a daemon that was not ours, and a gate that reads the binary

    Delta began with a grid of 384 thumbnails, 152 of them blank, because every tile opened fresh SSH sessions and the burst crossed a limit in a daemon nobody in the family owned. This track is the reasoning that followed: why the fix was a service of our own rather than a better-tuned sshd, what that service does and what it must never become, why it runs on Apple's Python 3.9 with nothing but the standard library (macOS lets a platform binary through its local network gate, and a launchd agent cannot answer the prompt), and how one process per Mac splits into two doors: an engine on loopback for the apps here, and a gateway that sorts every arriving connection by the path it came in on.

    Lesson list (5)Quiz · 5 questions→

  2. 02🌳Root Class, Child Shares

    0/6 lessons

    One class the server speaks to, children that each serve one kind of data, and refusals that hold however a path is spelled

    Delta serves a home folder, an Eagle image library and a soul vault's store through the same server code, because the server only ever talks to one class. This track takes that root class apart: the vocabulary every share speaks and the refusing defaults that make a forgotten method a closed door; the plain tree that serves a home the way scp sees it, with paths cleaned before anything touches the disk and links that never lead out; the credential stores and macOS-guarded folders that are refused as places, before a single stat; the delta.json declaration through which an app ships its own child, loaded by file path and isolated so that one broken child disables only its own share; the policies that name Macs by role, group and app instead of by machine; and the read APIs and derived outputs that answer "nothing changed" as cheaply as the data allows.

    Lesson list (6)Quiz · 5 questions→

  3. 03🏠Same House or Away

    0/5 lessons

    How Delta decides, per request and from verified facts, which wire to put the bytes on

    Two Macs on one desk can talk over a Thunderbolt cable at 28 Gbit/s, over the house's 10GbE at 9, or over the tailnet at a third of one. Choosing among them is Delta's most consequential decision, made per request from facts, never from a machine name. This track follows that decision: the on-link test built from the peer's own advertised addresses, this Mac's live interfaces and the routing table; the fixed order of Thunderbolt, Ethernet, Wi-Fi and tailnet, and why each road gets its own kind of protection; the route book that keeps a choice for a minute while a LAN route re-proves itself every ten seconds; the one retry on a fresh road when a fast road dies, with a hold-down so that once a sleeping Mac has cost one caller its timeout, the callers after it are told at once; and the pooled connections whose every failure names its phase, including the short read Python's standard library returns without a word.

    Lesson list (5)Quiz · 5 questions→

  4. 04🪪Identity Without Copied Secrets

    0/5 lessons

    Every caller named, every credential minted where identity is already proven, and nothing copied from Mac to Mac

    Before Delta serves a byte it has to know which Mac is asking, and it refuses to learn that from a secret somebody copied. This track walks the four answers it gives, one per route. On the tailnet, WireGuard has already bound the source address to a key, so Delta only translates: address to node through Tailscale's roster, node to fleet label through the registry, and it tells "I cannot tell" apart from "you are a stranger". On Thunderbolt and the shared LAN, the caller presents a ticket that the serving Mac minted for it over the tailnet and keeps only as a hash; on the LAN the ticket rides inside TLS pinned to a certificate fingerprint published over the same tailnet. On loopback, a 0600 token file proves the caller runs in Delta's own account. And a family Mac outside the fleet is named like any other, then admitted only by the one share whose policy names its group.

    Lesson list (5)Quiz · 5 questions→

  5. 05🗄️A Cache That Follows the Source

    0/5 lessons

    Keeping another Mac's files close without ever guessing whether they changed

    Every read an app makes through Delta passes a cache, and this track is how that cache stays honest. Bytes that crossed once are kept as blobs named by their SHA-256, under Delta's own state and never inside the data, with an index row that remembers the owner's validator. A read then has four possible answers, and the response always says which: a hit when the caller named the version it expects (no network, not even a route), a revalidation when the owner answers 304, a miss when new bytes arrive, and a stale copy, labeled with its reason, when the owner cannot be reached. You will see where validators come from (a file's size, nanosecond time and inode, or an app's own cheap tag), the one edit a stat cannot see, why the disk floor is read the way System Settings counts it, and why a small body is committed before its last byte goes out.

    Lesson list (5)Quiz · 5 questions→

  6. 06📦Bytes in Motion

    0/7 lessons

    Jobs that outlive a terminal, chunks and bundles, a stall limit instead of a deadline, and a transfer that is never done on silence

    Tracks 3 to 5 chose the wire, proved the caller and cached the reads. This track moves the files. You will see why a copy is a job inside the daemon rather than a command in a terminal, how big files become 16 MiB chunks spread over every worker while small ones travel in bundles of up to 400 files or 16 MiB a request, and why the timeout that matters is 30 seconds of silence, not a deadline (a bug hidden in sendall made a slow uplink fail every push). Then come the partial that records a chunk only after it is on disk, the two bugs in that record, the four changes that keep a job from saying done when files are missing, rsync's rules for links, patterns and folders that will not open, and the honest table against rsync and scp, including the rows Delta loses.

    Lesson list (7)Quiz · 5 questions→

  7. 07🔁Two-Way Writes

    0/5 lessons

    When both Macs write: a pair that tells a deletion from a new file, and a call that is never sent twice

    Everything so far moved data one way, with one side always right. This track is about the two cases where that rule fails. First, two Macs that both edit one folder: a named pair keeps an archive of what both sides last agreed on, which is the only thing that can tell a deletion from a new file. You will follow the decision table (an edit beats a delete, equal changes agree, newer wins and the loser stays beside it), the backups kept on each Mac before anything is overwritten, and the stops that refuse a whole run before it changes anything. Second, data that has an owner: a write call asks the app that owns a share to write through its own canonical writer, sent at most once, with three outcomes told apart by whether the request ever left this Mac.

    Lesson list (5)Quiz · 4 questions→

  8. 08🛠️Operating and Building

    0/5 lessons

    One service per Mac, every pile bounded, a test for every failure, and a small channel of your own

    Seven tracks of mechanism live in one process per Mac, so this track is about keeping that process honest. You will read the installer that refuses before it acts and reports success only when health answers, the LaunchAgent it renders, and why Delta has no scheduler of its own. Then the list behind invariant 10, where every pile has a number, including the two leaks a review found and the launchd log that is cut back in place while launchd still holds it. Then the test suite that runs two real daemons on one Mac, scripted peers for the failures healthy daemons cannot produce, defects committed first as strict expected failures, and the measuring script that catches what green tests cannot. Then moving an app off SSH with the client every app uses. It ends with a small channel you can run, and a checklist to take home.

    Lesson list (5)Quiz · 4 questions→
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign in — Please sign in to comment.

No comments yet — be the first.