34e6006 · favela-host · pear-git-v3

favela-host commits / 34e6006

README: link sibling repos, which this tree already does and I did not

The convention was already here — favela-web and favela-node link siblings as
[hyper-proto-peer](../hyper-proto-peer), favela-community as [hyper-rooms](../hyper-rooms).
The READMEs I wrote from scratch had ZERO of them; the ones I only edited kept theirs.
Measured before fixing: favela-bridge, favela-host, favela-identity, favela-markdown,
favela-peer, favela-surface and favela-surface-android each had 0 relative links while
mentioning 5-10 siblings by name.

Linked on FIRST mention only, prose only. Skipped code fences, tables, existing links
and URLs, and left later mentions as code spans so a paragraph does not turn into a row
of blue.

One case the automated pass got wrong and I reverted by hand: favela-surface's Boundary
section lists the modules it may NOT import, as a uniform run of code spans. Linking
hyper-overlay and ap-bridge there broke the list's formatting and read as "go read
these" when the point is "never import these". Those two are code spans again.

Rewrapped the lines the inserted links pushed past 100 columns, which is where the rest
of this tree wraps. The long lines that remain in favela-community and favela-node are
pre-existing prose — verified against HEAD — and one is inside a code fence.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

34e60069b99291eb789db1283495028d1b7fad5e

by plankatron <fleeky@gmail.com> · 2026-09-20T21:23:03.000Z

Changed files (1) +12 -6

README.md +12 -6

…	…	@@ -1,6 +1,7 @@
1	1	# favela-host
2	2
3		Whoever holds both halves. Brings a `favela-peer` node up, serves `favela-surface` over loopback,
	3	Whoever holds both halves. Brings a [favela-peer](../favela-peer) node up, serves
	4	[favela-surface](../favela-surface) over loopback,
4	5	and offers the atproto verbs that neither of those two may import.
5	6
6	7	`favela-surface` must not depend on `favela-peer` — its boundary test forbids reaching for storage or
…	…	@@ -32,7 +33,8 @@ This does not replace `favela-peer`. A headless box that wants only the daemon s
32	33	socket. It is a third arrangement, not a replacement for either.
33	34
34	35	The socket is served from the same composition rather than from `dispatch`, using `createServer`'s
35		`call` option — so `favela-bridge` and the `favela` CLI see exactly the verb set the pages see. A host
	36	`call` option — so [favela-bridge](../favela-bridge) and the `favela` CLI see exactly the verb set
	37	the pages see. A host
36	38	serving a smaller set over the socket would be two daemons wearing one name.
37	39
38	40	## API
…	…	@@ -74,7 +76,8 @@ never learns which it got. Not an emulation: `dispatch` is the layer the socket
74	76
75	77	It dispatches `ATPROTO_OPS` first, then falls through to `favela-peer`'s `dispatch`. The atproto ops
76	78	cannot live in `dispatch` — favela-peer's boundary test forbids the daemon importing anything
77		`atproto-`, and hpp's mint reaches `atproto-identity` — but they can live here, where both halves are
	79	`atproto-`, and hpp's mint reaches [atproto-identity](../atproto-identity) — but they can live here,
	80	where both halves are
78	81	already in one process, and the surface calls them the way it calls everything else.
79	82
80	83	### `serveSurface(node, { port, sessions, appUpdate, host }) -> { server, sessions, client, port, url }`
…	…	@@ -96,7 +99,8 @@ port number is a worse failure than a changed URL.
96	99
97	100	### `signIn(node, storage) -> { publicKey, claimed }`
98	101
99		Prove this app's anproto key to the daemon, claiming the instance on first run. The keypair is
	102	Prove this app's [anproto](../anproto) key to the daemon, claiming the instance on first run. The
	103	keypair is
100	104	persisted at `<storage>/browser.key`, mode 0600 — a key regenerated each boot would claim the instance
101	105	on first run and be a stranger on the second, permanently locked out, because TOFU closes on the first
102	106	claim and never reopens, not even for the claimant.
…	…	@@ -162,7 +166,8 @@ to project while the config plainly listed three members.
162	166
163	167	It logs the device public key per DID, because that is the one value another machine needs to admit
164	168	this device to a DID's roster and on a release-signed app it is unreadable from adb. It reports how
165		many DIDs actually booted against how many were configured: favela-android printed the config's
	169	many DIDs actually booted against how many were configured: [favela-android](../favela-android)
	170	printed the config's
166	171	count, so it said "signing enabled" while zero nodes had come up.
167	172
168	173	The booted handle is attached as `node.atproto`, because an op only ever receives `(node, args)` and
…	…	@@ -172,7 +177,8 @@ The booted handle is attached as `node.atproto`, because an op only ever receive
172	177
173	178	`deviceClient(hppNode)`, `peerClient(node)`, `pickNode(hpp, credential)`, `projectBsky(node, hpp, …)`.
174	179
175		This exists because the two networks are not symmetric. ap-bridge holds a registered name's feed and
	180	This exists because the two networks are not symmetric. [ap-bridge](../ap-bridge) holds a registered
	181	name's feed and
176	182	projects the fediverse from it server-side, so a phone federates with nothing running on it. atproto
177	183	is the opposite: the membrane is keyless and re-serves only what the device signed, so an atproto
178	184	record exists solely because something beside the signing key authored it.