Not Ours to Fix

The Sentence That Started Delta

After the 152 blank tiles, the obvious move was a patch: raise MaxStartups, add a retry, batch the thumbnails into fewer SSH calls. Each of those would have worked for a while. Dad took a step back instead:

ssh가 계속 문제가 되는 근본 원인은 '우리 것'이 아니기 때문이야. 데이터 주고 받는 우리 서비스를 만드는 게 가장 간단하면서도 scalable 한 방법이야. 그럼 모든 문제가 해결돼. 우리가 고치면 되니까. — 아빠

In English: the root reason SSH keeps being a problem is that it is not ours. Building our own service for moving data is the simplest and most scalable way. Then every problem gets solved, because we are the ones who can fix it. At 10:10 the same morning the name followed: "Delta 로 가자" ("Let's go with Delta").

Read that as an engineering argument, not a slogan. Dad's word was keeps: the thumbnails were one incident in a pattern. Sessions dropped under load, remote commands needed careful quoting, bursts needed throttling. Every one of those had a workaround, and every workaround lived in somebody else's configuration file. When the component that fails is one you cannot change, every fix is a negotiation with it. When the component is yours, a failure is just a bug with a line number.

Ours, End to End

"Ours" has a precise meaning in Delta's design. Authentication, routing, caching and transfer are all Delta's own code. There is no sshd in the data path, no rsync, no copied login files. That list is not purity for its own sake. It is the condition for the next rule to hold: every error has a name.

A Delta failure crosses the wire as a small JSON document, {"error": <cause>, "detail": <sentence>, "status": <code>}, and the receiving side rebuilds it as the same exception class. So an app three hops from the problem does not read "502". It reads which phase failed (connect, first byte, stall), on which route, for which share and path, after how long. You can only promise that if you own every hop the error passes through. A component you do not own will, sooner or later, hand you a bare status code and a closed socket.

What Delta Is

Every family Mac but the household's runs one Delta, and that Delta has exactly three jobs:

Serve this Mac's shares to the other Macs: the account's home (minus credential stores and the folders macOS guards with a privacy prompt), plus any share an app declares. Read-only unless a share says otherwise.
Read the other Macs' shares for the apps on this Mac, through one content-addressed cache and one pool of keep-alive connections per peer.
Move files and folders between this Mac and another, with delta cp and delta sync: resumable, verified, with live progress.

What Delta Is Not

The architecture document is just as specific about the negative space, and the negative space is what keeps a service like this from growing into everything:

Not this	Because
A command runner	SSH stays the family's command channel: `launchctl`, `git pull`, a restart, one small write action.
A backup policy	Callers decide what to copy and when. Delta has no scheduler and moves nothing on its own.
A public surface	It answers family Macs only. A phone on the tailnet that the registry does not list is refused.
An accidental two-way sync	Two-way happens only through a named pair with its own archive and rules, never as a side effect of two one-way syncs.

The first row is the one people get wrong. "We own a service on every Mac now, so let it run commands too" sounds efficient and quietly turns a data channel into a remote shell with a bigger blast radius. Delta's line is clean: data between Macs rides Delta; SSH carries commands only. That is invariant 1, and the architecture names its violation outright: a per-item or bulk ssh for data anywhere in the family is a regression.

Owned Elsewhere

Owning the channel does not mean owning everything that touches it. Delta reads ports and roles from Firelink's ledger and Kit's registry at run time, the app-side client kit_delta lives in the family's shared kit, and each app's domain knowledge (what an Eagle item is, what a soul vault note is) lives in that app's own child class. Delta is the pipe and the rules of the pipe. Everything with an opinion about what flows through it lives with whoever has that opinion.

Code

Delta's named-cause errors (trimmed excerpt)·python

# delta/errors.py (trimmed excerpt)
# A Delta error crosses the wire as {"error": cause, "detail": sentence,
# "status": code} and is rebuilt on the other side with the same class.
class DeltaError(Exception):
    status = 500
    cause = 'internal'

    def __init__(self, detail, *, cause=None, status=None):
        super().__init__(detail)
        self.detail = detail
        if cause:
            self.cause = cause
        if status:
            self.status = status

    def document(self):
        return {'error': self.cause, 'detail': self.detail, 'status': self.status}


class Unavailable(DeltaError):
    status = 503
    cause = 'unavailable'


class Timeout(DeltaError):
    status = 504
    cause = 'timeout'

The same idea, runnable: an error that survives three hops·python

# A named error survives serialization: each hop rebuilds the same class
# from the wire document instead of collapsing it into a bare status code.
import json


class ChannelError(Exception):
    status, cause = 500, 'internal'

    def __init__(self, detail, status=None, cause=None):
        super().__init__(detail)
        self.detail = detail
        self.status = status or self.status
        self.cause = cause or self.cause

    def wire(self):
        return json.dumps({'error': self.cause, 'detail': self.detail, 'status': self.status})


class Timeout(ChannelError):
    status, cause = 504, 'timeout'


BY_STATUS = {cls.status: cls for cls in (Timeout,)}


def rebuild(body, status):
    doc = json.loads(body)
    cls = BY_STATUS.get(status, ChannelError)
    return cls(doc['detail'], status=status, cause=doc['error'])


# The owner's side fails in a specific phase, on a specific route.
err = Timeout('first byte from the workbench via thunderbolt for eagle/items/X/thumbnail after 30 s')
body = err.wire()
for hop in ('engine', 'app server', 'browser API'):
    err = rebuild(body, err.status)
    body = err.wire()
    print(hop, '->', type(err).__name__, err.cause, '|', err.detail)

Exercise

List every way data moves between two of your machines today (scripts, sync tools, mounts, ad hoc scp). For each, write who owns the component in the data path and what its error looks like when it fails, as the calling program sees it. Mark each one whose error you could not trace to a cause without reading another system's logs.

Hint

Try failing each one on purpose: stop the far side, pull the network, fill the disk. The rows where the caller sees only an exit code or a bare 5xx are the ones a channel of your own would change.