Establish the device architecture from primary sources - #201
Merged
Conversation
Add termiod-device-architecture.md: there is no "remote" — there are
devices, each running one termiod, and every UI including the Mac app is
a client that attaches to one. A device's identity is its host_id, not an
SSH alias; SSH is one route among several to the same machine, so the
same box reachable over LAN, WAN and Tailscale stops forking into three
session lists.
Correct the state-authority section against primary sources. An earlier
draft, written from press paraphrase ("the server maintaining all
state"), concluded we should move to server-side state synchronisation.
Mitchell's architecture video and his reply to tmux maintainer Jonathan
Slenders say the opposite: Superlogical tees raw PTY bytes to clients
"like SSH", and while the server does parse, "the teeing happens ahead of
the server". That is termiod's existing anti-100x invariant, arrived at
independently — the architecture needs no course change.
Adopt their better argument against screen diffs: the problem is less
performance than that a diff-fed client owns no real scrollback and
cannot select across history. That is a capability limit no amount of
encoding work removes, so G stays opt-in even once the wire cell shrinks.
Bring the protocol spec up to the branch's state: §C.10 resumable
subscriptions, and the VT-sequence snapshot format with the measurements
behind it.
Add the hot-path and client-class analysis, and CLAUDE.md, which records
the positioning and the architectural invariants that follow from it.
Refs: #164, #177
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation only — no code. Splits the design work off
termiod/rust-poc(#177) so it can be reviewed and landed without waiting on the implementation.What this adds
termiod-device-architecture.md— there is no "remote". There are devices, each running onetermiod, and every UI including the Mac app is a client that attaches to one. A device's identity is itshost_id, not an SSH alias; SSH is one route among several to the same machine. Keyed by alias, one VPS reachable asvps-lan/vps-wan/ a tailnet name forks into three session lists; keyed by device it stays one machine with three roads.Protocol spec brought up to the branch's state — §C.10 resumable subscriptions (bounded ring, linger,
gapon overflow) and the VT-sequence snapshot format.termiod-hot-path-and-client-classes.md— the hot path and attach join point analysis.CLAUDE.md— the positioning and the architectural invariants that follow from it.The correction worth reading
An earlier draft, written from press paraphrase ("the server maintaining all state"), concluded we should move to server-side state synchronisation.
Primary sources say the opposite. From Mitchell's architecture video:
And answering tmux maintainer Jonathan Slenders, who asked whether sending visible screen state on attach means the server parses too:
That is termiod's existing anti-100× invariant, arrived at independently. The architecture needs no course change — which also means it is not a moat, and the doc says so.
We also adopt their better argument against screen diffs. We had justified keeping
Goff the default path with a bandwidth measurement (8.6× worse for scrolling output, measured against a real VPS). That number is real but indicts our 16-byte-per-cell encoding, not diffing as an idea. Their reason survives any encoding work:A diff-fed client owns no real scrollback and cannot select across history. So
Gstays opt-in even after the wire cell shrinks.Notes for review
host_idis not intrinsic (a cloned VM carries a duplicate), route selection under multiple reachable paths, and whether a single "current device" costs the cross-device agent roster.Release Notes: none — documentation only.