summaryrefslogtreecommitdiff
path: root/docs/typ/building.typ
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-29 16:55:47 -0300
committerGabriel Schneider <[email protected]>2026-10-29 19:54:26 -0300
commit6a6e1b2cb3e328d5abd4435c1c2659f4e4e31eb8 (patch)
treedb996dc7f022cdaff9afd8e15774ddd33ac1c607 /docs/typ/building.typ
parentcd560d4e025e46db6aa583f017dd9e503f45659c (diff)
downloadpardes-6a6e1b2cb3e328d5abd4435c1c2659f4e4e31eb8.tar.gz
pardes-6a6e1b2cb3e328d5abd4435c1c2659f4e4e31eb8.zip
the replica socket: the daemon listens on pardes-replica.sock, a stream `ssh -L` can forward, refuses another build's hello in words and hands the connection to its session, which welcomes it and answers pings
The daemon binds `pardes-replica.sock` beside its own (SOCK_STREAM, so ssh can forward it; the SEQPACKET socket that carries fds stays local) once it holds its lock. A replica's first message is a hello (detached/wire.zig, now version 14): the protocol version at offset 0, the client's semantics hash and the session's name. The daemon reads exactly that much and no further, so whatever the client sends next is the session's, keeps up to 16 hellos still on their way (ponytail: one that never comes holds its slot until it hangs up), and refuses in words another protocol, a session nobody has, or another build: every session now says its own hash in its registration (daemon protocol 2), so a mismatch never reaches it. An accepted connection goes to the session over its link (SCM_RIGHTS) and the daemon keeps no copy; the session welcomes it with its pid and name on a thread of its own and answers each ping with a pong, until bye or a hangup. ponytail: that stub is all a session does with a replica until phase 5 proper; it is what times a round trip through the handoff and `ssh -L`. The semantics hash (wire.semantics) is phase 1's undone item: the protocol, the release and commit, the platform, the build options, every dependency the manifest pins by its content hash (grammars, ghostty, the Unicode tables: build.zig's new `deps` option) and the walker codec's assumptions (pointer width, byte order). Not the OS: a Linux client of a FreeBSD session is the main case. ponytail: an unstamped build has no commit, so two dev trees of one release with the same options are not told apart. `pardes --version` prints it on a second line. The hello lost its grid (a replica's view takes a resize like any other input). test/daemon.py: a hello of this build welcomed by the session itself (its pid, one fd more in the session and none in the daemon, and back once it hangs up), 50 pings, another build's hello and an unknown session's refused, and `--ping <socket> <session> <pardes> [n]`, which times a hello and n pings on any replica socket (a forwarded one, say). Co-Authored-By: Claude Opus 5.5 <[email protected]>
Diffstat (limited to 'docs/typ/building.typ')
-rw-r--r--docs/typ/building.typ17
1 files changed, 13 insertions, 4 deletions
diff --git a/docs/typ/building.typ b/docs/typ/building.typ
index 152be838..00088d7b 100644
--- a/docs/typ/building.typ
+++ b/docs/typ/building.typ
@@ -31,7 +31,8 @@ leaves that copy out. Zig 0.17 keeps the prefix from the build script, so
so always pass `-Dplatform` while developing. Test, benchmark and run steps build what they need
without installing. `pardes --version` prints `pardes <version>` (from
`build.zig.zon`), plus the commit for release builds and the `~/.local`
-install; `pardes --help` lists every flag.
+install, and on a second line the build's semantics hash, which a replica
+must share with its session; `pardes --help` lists every flag.
The ESP32-P4 firmware is linked in the sibling `../05-zig-p4` toolchain,
which needs ESP-IDF register headers: after building the editor object
@@ -223,9 +224,17 @@ process; `pardes-gui --attach` opens one again. `PARDES_DAEMON=off` (the
snapshot harness) runs a session as before the daemon: in the terminal's
own process, ended by its hangup.
-`src/detached/wire.zig` is the input half of the protocol a remote client
-will speak (version 13): fixed-width little-endian fields, a 5-byte header
-(tag, then a u32 length), the hello and its version, the input events.
+A replica (a client running its own copy of the core, phase 5 of
+`docs/next-daemon.md`) connects to `pardes-replica.sock`, a stream socket
+beside it that `ssh -L` can forward. `src/detached/wire.zig` is its
+protocol (version 14): fixed-width little-endian fields, a 5-byte header
+(tag, then a u32 length), the hello, a ping, the input events. The hello
+names a session and carries the client's semantics hash (the protocol,
+release, commit, platform, build options and every dependency's hash); the
+daemon refuses another build's, or a session nobody has, in words, and
+hands an accepted connection to its session (`SCM_RIGHTS`), which welcomes
+it and from then on is the one it talks to. Today the session answers
+pings and nothing more.
= 9P