docs: crap RFC 0002 — CRAP attach protocol (draft)#30
Open
friedenberg wants to merge 8 commits into
Open
Conversation
Harness detection (CRAP=2, TERM-shaped), content negotiation (CRAP_ACCEPT format tokens, go-plugin-style hello announce with a reserved OOB transport rendezvous), and recursive re-offers (CRAP_PARENT/CRAP_DEPTH, passthrough + mux topologies, shared-channel write discipline) so a process tree nests as one ndjson-crap stream. Prototype lands in just-us; schema doc gains a forward pointer. https://claude.ai/code/session_01J9roWY95WrC2iAoJy2hqmJ
Name the two kinds of child output (crap on the channel vs garbage, the canonical term for unstructured stdio) and require executing nodes to handle both; require withdrawing the offer from children whose stdout is consumed as data (command substitution), with the stdout-default caveat for broadly exported offers; record the prototype's end-to-end validation against crap-present and :: validate. https://claude.ai/code/session_01J9roWY95WrC2iAoJy2hqmJ
crap-present and large-colon were build artifacts of the RFC 0002 prototype validation, committed by accident. https://claude.ai/code/session_01J9roWY95WrC2iAoJy2hqmJ
Supersedes the fd-passthrough first draft. Two named invariants (composable, severable); every node a client of a unix-socket sink server birthed by the tree's root (fork-and-become, re-exec-self, or external binary — no required runtime dep); per-connection grants hand out disjoint deterministic id bases, dissolving random tps, the PIPE_BUF write discipline, output chunking, the hello, CRAP_ACCEPT token negotiation, and the transport rendezvous. Offer shrinks to CRAP=2 with CRAP_SINK/CRAP_PARENT as protocol-managed machinery; lease-pipe EOF drives server self-cleanup; severing = root-election, including on dead-sink reconnect failure. Design history records why the two earlier models fell. https://claude.ai/code/session_01J9roWY95WrC2iAoJy2hqmJ
Nodes must complete attachment (grant received, sink exported) before spawning offer-inheriting children: live sink for root children, parent-before-child by arrival order, and deterministic granted bases for serial trees. Record that parent-assigned monotonic child identity already exists as the CRAP_PARENT value (base+n in spawn order), so the only nondeterminism left is base labels among genuinely parallel attachers within one invocation — irreducible and structure-free. https://claude.ai/code/session_01J9roWY95WrC2iAoJy2hqmJ
A node may attach only if the sink's spawner is its ancestor at attach time; servers enforce at accept via peer credentials and answer trespassers with a deny grant. Denial (a live server said no) degrades to dumb output, distinct from absence (no server: re-root) — so leaked offers, stale env snapshots, and detached daemons can neither inject into someone else's tree nor birth surprise servers. Accept-time checking gives the right temporal semantics: daemonized strays are refused, mid-run orphans keep granted connections. Drain gains a grace timeout; security notes scope this as same-user accident hygiene, not a malice boundary. https://claude.ai/code/session_01J9roWY95WrC2iAoJy2hqmJ
New property: each terminal has zero or one server, never more. Roofless root-capable nodes presenting to a tty rendezvous on a socket path derived from the tty's device number; the kernel's bind atomicity is the election (winner births, losers connect and render as sibling top-level trees — one viewport per terminal). Terminal servers admit by controlling-tty instead of descent, live by refcount instead of lease, and should present rather than splice raw. Stale paths are reclaimed under a sidecar flock. Pipes/files need no election (distinct destinations are distinct by construction); the non-tty shared-destination case is documented residue with a possible dev:ino generalization. https://claude.ai/code/session_01J9roWY95WrC2iAoJy2hqmJ
Conformance section now reflects the landed client/birthed-server implementation and its recorded gaps (scope check at accept, crap-side attach libraries, bats lane). https://claude.ai/code/session_01J9roWY95WrC2iAoJy2hqmJ
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
2 participants
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.
Harness detection (CRAP=2, TERM-shaped), content negotiation
(CRAP_ACCEPT format tokens, go-plugin-style hello announce with a
reserved OOB transport rendezvous), and recursive re-offers
(CRAP_PARENT/CRAP_DEPTH, passthrough + mux topologies, shared-channel
write discipline) so a process tree nests as one ndjson-crap stream.
Prototype lands in just-us; schema doc gains a forward pointer.
https://claude.ai/code/session_01J9roWY95WrC2iAoJy2hqmJ