@nervur-org/dock 0.3.0

package/harbor/quo-harbor.md

@@ -0,0 +1,850 @@
+# Transports
+
+This is how a harbor lives on a real device and how two of them meet over a real
+network. It implements the harbor of `quo/SPEC.md` on every terrain and
+adds nothing to it: a harbor boots wards, keeps what they are made of, carries
+bytes to one pk, returns what came back or nothing, never reads them, and
+answers nothing only where it knows nothing was sent. This document names no
+being and no side; it knows seeds, partitions, code, sockets and disks.
+
+## One harbor per device, one ward per world
+
+A device runs one harbor. It is what the device already has, offered to Quo,
+and there is one of it because a device has one keychain, one disk and one
+set of processes. Two harbors on one device are a curiosity, not a design.
+
+A harbor hosts many wards, and a ward is a world: a seed, a partition and a
+body of code, with an origin. The wards of the device's owner and wards
+whose code came from a stranger are hosted the same way. A native app is
+therefore a browser of worlds: one harbor, a ward per world, each in its own
+runtime, and the screen showing one at a time.
+
+A ward is whole only where all three of its parts are. The harbor keeps a
+**ward record** per ward, and it is the harbor's, never the ward's:
+
+```
+ward record
+  pk         derived from the seed; the key of the record
+  seed       where it is, in the secret store
+  partition  where it is, in the data store
+  code       where the class bodies come from, and which version boots
+```
+
+One of those wards is the harbor's own, the **dock ward**. A harbor with
+anything to lend boots it and keeps its ask pointer instead of handing it
+out, so it is that ward's root, and every faculty of the box is a being in
+it. It is a ward in every other respect: a seed the store keeps, a
+partition that persists, a door judging the thirteen cases. Two things are
+its own. It is never adopted or dropped as a migration, because its beings
+are the box's and die with it. And the harbor cleans up after a ward that
+leaves: it is the root, so when it drops or hands out a ward it removes the
+relations that ward's beings held at faculties, since a faculty's occupant
+rows are not bounded the way a knock record is. A faculty cleans too, from
+her own end, dropping a subscriber she has heard `unreached` from long
+enough; the two catch different failures and neither is redundant.
+
+`lend` is the last member of the ground, and it is built per ward: given
+a name, the harbor asks its own root to invite on that faculty and hands
+back the invitation, or null. Which ward may ask for which name is the
+harbor's own decision, taken where the ground is built, and a ward whose
+code came from a stranger is lent nothing. The ground is per ward and per
+harbor, so `lend` reaches this box and no other; a ward that migrates is
+handed the new harbor's, which is why a being asks again at every birth.
+
+A harbor need not announce the dock ward's pk on the lines it dials. An
+announce is a claim it chooses to make, and nothing is lost by withholding
+this one: the only way through that door is a heir a faculty minted, and
+the only source of one is `lend`.
+
+## Three parts, three native places
+
+The harbor adapts nothing. Every terrain already has a place for secrets, a
+place for data and a place for code, and those are the three the harbor
+needs:
+
+| a ward is   | Mac, iPhone           | droplet                    | edge                    | browser tab            |
+| ----------- | --------------------- | -------------------------- | ----------------------- | ---------------------- |
+| seed        | a file, sealed        | `.env` or a secrets file   | the platform's secrets  | IndexedDB, per origin  |
+| partition   | a file, sealed        | a file on disk             | Durable Object storage  | IndexedDB, per origin  |
+| the key     | Keychain              | the environment, if any    | the platform's secrets  | none                   |
+| code        | the app bundle        | a folder                   | the deployed worker     | a bundle URL           |
+
+Envoys read their own secrets from the same secret store as the seed. A
+device has one place for secrets and the harbor is one more user of it.
+
+The browser column is the honest weakness: a tab has no secret store for
+bytes, so the seed sits beside the partition, guarded by the origin and
+nothing more. That is the price of a tab, and why a tab is a rented room and
+a native app is not.
+
+### The partition, split or wrapped
+
+Inside the partition one branch is secret, the bind table: each standing's
+current and next keys, and the heirs minted and not yet spoken. Everything
+else is data. That is why a side never holds one. What a harbor hands a side
+for a ward it serves is `Hosted`: the door and the ask, the pk, the name, the
+record, a save, and the beings it made, by key and as a list of keys. No
+partition. A side that wants to know which beings a ward has, or which one it
+marks public, asks the ward and reads the describe; `harbor/ward.ts` is that
+read, `beingsOf` and `publicKey`, and every side here uses it. Asking costs
+nothing to write: a ward that wrote nothing has nothing to save.
+
+The partition is values only and the harbor may persist it as
+it likes, so it may keep the secret branch apart from the data, by terrain:
+
+- **Split.** The bind branch goes to the secret store beside the seed, the
+  rest to the data store. Fits a phone with a few relations; keychain items
+  are small and a being with a thousand standings has a thousand key pairs.
+- **Wrapped.** The secret store holds one key per harbor; the data store
+  holds each ward whole, seed, partition and record as one blob encrypted
+  under it. Any size, one secret. The droplet and edge answer, and it
+  works on the phone too.
+
+The ward never knows any of this. It hands values and gets values back, and
+split or wrapped, one store or two, is the terrain's business. The one thing
+it learns is yes or no: whether what it wrote was kept. A heir given away as
+an invitation is a live credential until it speaks, and on a device other
+apps share that is the argument for the secret store.
+
+Wrapped is what is built, and it is one piece, `seal.ts`: AES-GCM under a
+32-byte key, a fresh nonce each time, nonce and ciphertext together as hex,
+on WebCrypto so it runs wherever a store does. The key is the one secret a
+harbor reads from its terrain's secret store, named `QUO_SEED_KEY` on every
+terrain: a platform secret on the edge, the environment of a daemon on a
+device, handed to it from the Keychain by the app that spawned it. A
+droplet gives no key and its folder stays plain under its file modes. A
+store speaks one form, the one its key decides, and refuses a ward kept in
+the other by name, so a daemon started without its key, or with one
+against a plain folder, fails loudly and boots nothing. Sealing a plain
+folder is a deliberate operator command, never a boot's doing.
+
+### A save the store refuses
+
+A save is part of the ask that caused it. At the end of every arrival, after
+the being has answered and before the ward seals the reply, the ward asks the
+harbor to keep what it wrote. The harbor saves and says whether the store
+took it. That is the last moment anything can still be said: a reply sealed
+to an asker's lid cannot be unsaid, and only the ward can seal.
+
+A store that refused makes that arrival a failed ask, said with the words a
+failed ask already has, `threw` to a key the door holds and silence to
+everyone else. Never a reason. A full disk is an insides of this device, and
+the far side hears no more of it than it hears of anything else in here.
+
+A row the store would not take leaves the being standing at what is kept. The
+harbor knows what that is without asking anybody: it keeps the copy it handed
+the last save that succeeded, row by row, and puts the refused row back to it
+in the ward's memory, in place and behind the cells guard. Her next ask sees
+what the device sees and a smaller write after it is taken. She loses the
+writes that were refused, which is exactly what their askers were told. The
+row is written in place because a booted being holds her cells and her bind
+table by reference: a fresh object in their place would strand her on cells
+nothing keeps. A row the last successful save dropped is a being the store no
+longer keeps, and her row goes with it.
+
+The harbor never asks a store what it holds to find that out. The one moment
+it would ask is from inside a save the store has just refused, which is the
+read least likely to be true: the edge answers it with a partition missing its
+head row, and a ward put back from that loses its heirs and answers its own
+occupants with silence. What the copy costs is one copy of the rows of each
+save, taken before the store is asked and kept only if the store takes it,
+plus one copy of the partition when a ward is hosted, so that a being whose
+first write of the run is refused is put back too. No store is read and no
+extra write is made.
+
+The fault is counted too, and a box says how many saves it refused wherever a
+box says anything about itself: `/health` on the daemon and on the edge
+carries the count per ward, and a daemon journals one line the first time a
+ward's save is refused. A counter nobody reads is the thing this replaces.
+A harbor that keeps nothing is asked nothing, and a ward running over no
+store answers as though none of this were here. A store that refuses every
+save cannot keep a ward's first write either, so no ward stands on it at all.
+
+The reason this is worth a member of the ground: on a terrain where a being
+is one row with a ceiling, a refused save is not a rare disk fault. Past the
+ceiling every save of that being is refused, her memory runs ahead of what is
+kept, and everything written to her afterwards is lost at the next reload
+while every door goes on answering success. A door that says yes to what was
+never kept is the worse fault, and it is the one a counter cannot fix.
+
+### A being's row has a ceiling
+
+A being is one row, and every store that keeps a row as one value has a
+ceiling on it. The store refuses the row itself, before the platform is
+asked, and it reads the ceiling from one place beside the rest of what that
+terrain is: two stores disagreeing about the limit is a row kept the day
+before and refused the day after with nothing in the tree saying why. Where a
+terrain publishes no number, its store has no ceiling of its own and a full
+disk is what refuses.
+
+The edge is the terrain that publishes one. A SQLite-backed Durable Object
+takes a key and a value of 2 MB together, which is `ROW_CEILING` in
+`harbor/edge/given.ts`, and a being whose cells and bind table pass it is
+refused by `DurableStorage` rather than by the platform. What lives beside a
+ward for values a partition cannot hold is a design of its own: a partition
+holds values, and a holiday video is not one.
+
+### Custody is a lease
+
+`quo/SPEC.md` makes custody the harbor's vouch: two harbors over one
+seed are two wards with one pk, and a harbor refuses to boot a ward another
+running harbor holds. The dock makes that a property of the store, not a rule
+people follow: a lease beside the seed in the secret store, taken by the daemon
+that boots the ward, checked before any boot, refused while held. A restored
+backup meets a held lease and does not boot. A second tab on one origin meets a
+lock and is the held page, `papers/quo-human.md` says which, and so does the
+service worker on that origin meet it: it is
+one more claimant of the same lock and holds the harbor only when no page does.
+The edge is a Durable Object, which is the lease built in. None of it stops
+a deliberate copy, and nothing can; it stops every accident, and accidents
+are the whole population of this problem.
+
+### Migration is three moves
+
+A ward moves between harbors by moving its three parts: the seed from one
+secret store to another, the partition from one data store to another, and
+the new harbor pointed at the same code. Same seed, same pk, every standing
+anyone holds still points at her. The old harbor deletes its copies first:
+two harbors holding one seed are two wards with one pk, diverging silently.
+
+What a move costs is not the three parts, which are bytes, but how many
+peers wrote down where the ward was. A pk is permanent by arithmetic; a
+location is soft state in every other harbor's directory, and only that goes
+stale. So the bill is proportional to who hard-coded it, and there are two
+kinds of ward.
+
+A ward whose harbor dials out is free. It announces what it holds when a
+line opens and whenever that changes, the listener proves each claim at the
+door and binds it, and a ward that arrives on a new box is reachable as soon
+as its harbor dials. Nobody is told and no peer acts.
+
+A ward that is dialed keeps a second name. Peers hold a hint, pk at a URL,
+in their own stores and across their own restarts, so that URL is a promise
+the same way the pk is. Moving boxes does not break it, because a hostname
+is not a location: DNS and the proxy point it wherever the harbor now runs,
+which is the whole reason the route is a hostname and not an address.
+Changing the URL itself is the move that costs, and it cannot be announced
+to a peer this ward cannot reach.
+
+When it must change, what is republished is a hint and never an invitation.
+The relation, its keys and its count are untouched, and the invitation is
+as good as it was: that is why the two travel separately, a link being one
+next to the other. Peers on a rendezvous this ward also dials relearn by
+themselves, since a binding is proven at the door and names no URL; peers
+holding a hint need a new one, and a hint is not a capability, so it may be
+published in the open to all of them at once. Nobody is invited twice.
+
+The rule, then: a dialable ward keeps two names and owes the second the same
+care as the first, and a ward that only dials keeps one, which is why a
+laptop, a tab and a phone move home without ceremony and the droplet does
+not.
+
+### Code is a harbor decision
+
+A ward's code has an origin: a folder the owner wrote, a bundle a world
+published, a worker deployed. When the origin ships new bodies the harbor
+decides whether the ward reboots on them. A reboot is silent, the ward cannot
+tell old bodies from new, and a body the cells were not written for is an
+absence this run. So the harbor pins what a ward boots on, records it in the
+ward record, and moves it deliberately: on its own for the owner's own code,
+with the owner's word for a world's.
+
+## The daemon, and the two cores
+
+There are two harbor cores, and every device runs one of them:
+
+- **The node daemon**, `quo serve`. A disk or keychain store, a unix socket
+  for the owner, listeners on localhost for the routes. Droplet, Mac, Linux
+  box: wherever a home runs.
+- **The browser harbor.** A dialer inside a webview or a tab, an IndexedDB
+  store or a sealed store handed in, one socket per world it is connected
+  to. A tab, and every app, phone and desk alike, since an app is a
+  presence and a presence dials.
+
+The two cores meet a ward they cannot open differently, and both are right.
+The core carries on and names it in `unbooted`, because a device with many
+worlds must not lose them all to one. The daemon stops there and says which
+ward and why: a daemon's folder is an operator's, every ward in it is meant
+to be served, and coming up quietly with one missing is that world gone dark
+with nobody told. It is the same rule that makes a sealed folder with no key
+loud rather than a daemon serving nothing.
+
+Tauri and Capacitor are packaging, not harbors. Both apps ship the browser
+harbor over a native sealed store, the phone with push and the desk without
+it, and each is its own owner for its one harbor. Neither ships the daemon:
+a home runs on a box that runs day and night, and a laptop is a presence
+like a phone. The edge is the daemon's core over a Durable Object, one
+single-writer object per ward, or it diverges.
+
+A wrapped app carries its own bundle and never loads it from a hostname.
+Only a plain tab fetches the bundle from a world's `web.`, because it has
+nowhere else to get it. A wrapped app visits a world's `web.` exactly once,
+in a system browser sheet, to do the credential exchange and come back with
+an invitation; after that it speaks to that world's `quo.` for bytes and
+never to its `web.` again. One app on a device meets many worlds, one ward
+each, and there is never an app per world.
+
+## Listeners and dialers
+
+Two kinds of harbor exist in the world, and every pair reduces to them:
+
+| terrain      | can be dialed | can dial | lifetime                | wakes on |
+| ------------ | ------------- | -------- | ----------------------- | -------- |
+| droplet      | yes           | yes      | as long as wanted       | itself   |
+| edge         | yes           | fetch    | per request             | request  |
+| desktop app  | no            | yes      | while running           | itself   |
+| phone app    | no            | yes      | foreground, throttled   | push     |
+| browser tab  | no            | yes      | while open              | itself   |
+
+A ward on a dialer is reached only if its harbor dialed first and something
+holds that line open. A phone's ask must survive a push wake-up, and a
+device that comes back from sleep tells its dialer so, `wake`, since the
+system closes a sleeping socket without a word; `quo/SPEC.md` says
+what the dialer does with it. A tab is a
+device, and one seed never lives in two tabs.
+
+## Transport by necessity
+
+Transport is chosen by necessity and nothing else. Two wards in one harbor:
+no transport, the harbor calls its other door. Both harbors can listen: a
+request, plain HTTP or raw TCP, and a reverse ask is a request the other
+way. One of them cannot listen, behind NAT, in a tab, on a phone: a socket,
+opened by the one that can dial and held by the one that can listen, with
+both sides sending asks over it and a frame id matching replies. There is no
+fourth situation, so there is no fourth reach, and none is ever picked
+because it is nice. A being cannot tell which one carried her ask, and that
+is the proof the choice was free.
+
+A connection is a reach, never a harbor, and a ward outlives it. When a
+socket drops, the listener's directory entry for that pk goes with it, the
+listener answers nothing, the dialer's harbor turns that into unreached, and
+the relation is untouched: seed, partition and keys are on the dialer, not on
+the wire. When the dialer reconnects it announces its pks, the listener
+probes each one at its door and rebinds what proved, and the next ask goes
+through under the same keys and the same count. A phone in a tunnel loses
+signal, never identity.
+
+Untouched is the relation and not her record of it. An ask that reached
+nobody has still taken its number and staged the key it announced, because
+she must never offer one number twice; the count carries the gap and the far
+door honours any number above its mark. So a tunnel costs a number and a
+rotation, and nothing else.
+
+## Reach, directory, rendezvous
+
+A harbor needs two reach kinds and nothing more, which is what
+`quo/SPEC.md` says and what `packages/quo/src/harbor/reach.ts` is:
+
+- **request**: a URL. Send bytes, get bytes. Listener to listener.
+- **socket**: a held connection, opened by whichever side can dial, used in
+  both directions with a frame id. A WebSocket, a WebRTC channel and a
+  native socket are one socket reach.
+
+Two runtimes on one device are no third kind. Either they are one harbor,
+and it calls its other door with no transport at all, or they are two
+harbors, and one of them dials the other as any dialer does.
+
+Plus one forwarding rule: a pk whose reach is another harbor that holds a
+socket to it. That rule is the **rendezvous**, and with it every dialer is
+reachable: a phone holds one socket to `quo.acme.com`, acme's harbor binds
+the phone's pk to that socket, and a third harbor sending to the phone's pk
+sends to acme, which forwards the same bytes to the same pk. Nobody changes
+a pk or a byte, and an intermediary opens nothing.
+
+What a box can see is the wire and only the wire. Its `/health` shows every
+foreign pk and the socket it holds it on, and one phone is one harbor
+holding one socket, so a phone that joined two worlds hosted on that box
+announces both wards together: that is the box hosting both worlds, and
+two worlds on two estates share no socket and have nothing to correlate.
+No being of either world sees any of it, since an occupant sees pks never.
+
+What it does learn is worth writing down, because "pks and ciphertext" is
+true and reads as a smaller thing than it is. A harbor forwarding for
+someone else holds, for every ask it carries: the destination ward pk, in
+the clear, because that is the address and there is no forwarding without
+it; the socket it came in on, and so the dialer's own address; the size of
+the ask and of the reply, which are not padded and so move with the
+plaintext; the time each crossed, and which reply belongs to which ask,
+because it awaits the one to answer the other; and, from the announce
+frame, which ward pks are held by one device. So an operator of a
+rendezvous can keep who spoke to whom, when, and how much, for as long as
+it likes, and break no ciphertext to do it. What it cannot learn is the
+relation: the heir is sealed inside the ask, so one standing at a ward
+cannot be told from another, nor followed from one rendezvous to the next.
+Being reachable through someone costs the fact that you spoke. It does not
+cost what you said, nor who you are to the far being.
+
+A rendezvous is a listener and nothing more, so there is never one of them.
+A harbor may hold sockets to several and be reached through any: the
+directory is keyed by pk and a bind is per socket, so each listener binds
+the same pks independently. Plurality is the design and not a deployment
+habit, and a world that can only be reached through one listener chose
+that.
+
+A line also says which **wire suite** it speaks, one number that is not
+negotiated: in the text frame a socket announces itself with, and as the
+header `quo-suite` on a request. It is never on an ask, so an ask is bytes
+with nothing in front of them, and a harbor still knows before it carries
+anything whether the far side can open what it would send. A side meeting a
+suite it does not know closes the line; a request door answers nothing
+delivered. `quo/SPEC.md` owns the number and says why it exists.
+
+The **directory** is the map from pk to reach. The memory harbor stubs it with
+linked peers. A real one is a table the harbor fills however it likes, and the
+one entry it must learn by itself is a dialer's: when a dialer connects it
+announces the ward pks it holds, and the listener binds to that socket each one
+whose door answered its probe; `quo/SPEC.md` says what the probe is.
+After a migration the pk is unchanged, only its reach, and the next connect
+rebinds it.
+
+## The quo. route, as built
+
+The reach interface and its two implementations are the library's,
+`packages/quo/src/harbor/reach.ts`, and pass its reach suite here: the request
+and a socket to a daemon in `packages/dock/test/wire.test.ts`, the request
+through the worker inside the edge. The route is one file on every terrain,
+`packages/dock/harbor/quo.ts`, `Request` in and `Response` out, mounted by
+the daemon under `/quo` and by the worker under its harbor's prefix; it asks
+its harbor for one thing, an ask delivered to a pk. The listener half is the
+terrain's own and is not in it: `ws` at the daemon's door in
+`packages/dock/harbor/http.ts`, a socket pair in the edge harbor.
+
+```
+request      POST <url>/<pk>, the sealed ask as the body, the sealed reply as the answer;
+             <url> is the world's quo. route, which the proxy maps onto the daemon's /quo
+             404 is "no reach for that pk" and comes back as nothing; a line lost after
+             sending answers nothing at all, and the ward's bound ends the ask
+             at most 1 MiB is read, and a body over it is answered by that same 404: an
+             ask too big for this door is nothing delivered, never a silence, so it is
+             safe to send again and it will fail again. The number is this daemon's and
+             is on no wire; a caller cannot ask for it and is never told which of the
+             two a 404 was
+socket       a WebSocket at <url>, held by the dialer, used both ways
+             text frame   { announce: [pk, ...] }   the ward pks this side holds
+             ask frame    [0][id 4][pk 64][bytes]    a frame id matches the reply
+             reply frame  [1][id 4][bytes]
+             none frame   [2][id 4]                  nothing was delivered
+directory    pk -> reach, filled three ways: a socket a dialer holds, bound once proven
+             and unbound at close; a hint from a link, `quo reach <pk> <url>`, kept in
+             <dir>/reach.json; and the harbor's own doors, always first
+```
+
+One rule makes the rendezvous: bytes that arrive from the wire go to an own
+door or to a socket this harbor holds for that pk, and never onward by
+request. So a third harbor with a hint that a phone's pk is at acme's
+`quo.` sends there, and acme forwards down the socket the phone holds.
+A row on the dock ward's `dialers` faculty makes a daemon a dialer, placed
+once by the root, `quo ask --ward dock dialers keep '{"url":"https://quo.acme.com"}'`,
+kept in her cells and dialed again at every boot: it holds one socket per
+URL, announces its wards on open, binds the listener's pks, and reconnects
+with backoff from a second to thirty when the line drops. `drop` closes
+the line and forgets it. A pk is 64 bytes on the wire, the ward key and
+the padlock.
+
+The proof is `packages/dock/test/wire.test.ts`: the library's conformance suite,
+untouched, against two disk harbors in two folders with HTTP doors on
+loopback, once with every ask a request and once with the second harbor
+dialing the first; down is the reach refused, migrate is the ward folder
+moved and adopted. Then the rendezvous on its own.
+
+Two rules the daemon obeys and a reader would otherwise rediscover: a harbor
+writes the partition before it lets a folder go, because a being driven
+in-process changes it without passing a door; and a proxy sends the route
+root as `/quo/`, with the trailing slash, which the door takes.
+
+## The two cores, as built
+
+The harbor core is the library's, `packages/quo/src/harbor/core.ts`, and so is
+the dialer, `packages/quo/src/harbor/dial.ts`; `quo/SPEC.md` says what
+they are. Every harbor here extends the core and hands it three things: a
+**store**, the library's interface, with `files.ts` on a disk, plain as three
+files per ward or sealed as one blob when the daemon holds `QUO_SEED_KEY`,
+and `idb.ts` in a tab, each passing the library's store suite, the files
+store in both forms; a **loader**, the code half, a
+module from a folder on a daemon and the bundle in a tab; and a **lease**, a pid
+file on disk and a web lock on the database name in a tab, so a second tab on
+one origin meets the lock and is the held page. The disk harbor, `disk.ts`, is the
+core plus files, the loader and the pid, and every socket dialed to it is held
+by its HTTP door, which is where this terrain's `ws` listener stands; the
+browser harbor, `browser.ts`, is the core plus
+IndexedDB, the built-in beings, the lock and one dialer per world.
+
+The harbor folder is the device's and not a package: it has no node_modules
+and is not meant to, and a class file in it imports the library by name like
+any code. So the disk harbor resolves a class file's packages from where the
+dock itself is installed, `resolve.ts`, a module resolution hook registered
+once before the first class loads: a bare name that does not resolve from a
+file outside any node_modules is resolved again from the dock's own place.
+A class sees the packages the daemon sees, the library and the dock's own,
+and one copy of each, so a `Being` in a class file is the daemon's `Being`.
+
+A tab's store keeps values through JSON, as a file does, because the ward
+hands its partition out through a guard that structured clone refuses.
+The daemon's `/quo` and `/health` answer any origin, with the preflight a
+binary POST needs, because a tab on one world's `web.` reaching another
+world's `quo.` is the ordinary case.
+
+`/health` asks for nothing and tells what this harbor hosts: the wards by
+name and pk, the sockets held, the directory, and the saves its store
+refused, per ward. That is a map of the
+device, so it is an operator's surface and not a route: the proxy maps the
+three hostnames onto their paths and nothing onto this one, and a request
+for it from outside meets a 404 at the proxy. It answers any origin because
+it is on loopback, and the day it is put behind a proxy it needs a reason
+and a door.
+
+The proof is `packages/dock/test/terrain/browser.test.ts`, behind
+`npm run deep:dock` beside the library's own browser chapter: the
+conformance suite, untouched, inside a real Chromium, against two browser
+harbors in one tab with two databases, both dialing a Node daemon on
+loopback, so every relation crosses the rendezvous; down is the reach
+refused on both, migrate lifts seed, partition and record from one database
+into the other and boots there, the tab-to-home scene. And the lock: a
+second harbor over one database does not boot.
+
+### One thing a terrain's fetch decides
+
+APNs, the ring `dock/apns.ts` is, speaks HTTP/2 and refuses HTTP/1.1.
+Node's `fetch` is undici, which has no HTTP/2 client, so a daemon on Node
+rings Apple through `dock/http2.ts` instead, the same ring over
+`node:http2`. A worker's fetch reaches Apple over HTTP/2 and so does
+Deno's and Bun's, and those terrains use the `fetch` one. What the two
+send is one function in `dock/apns.ts`, the path, the headers and the
+body, because a phone rung two ways is rung the same way twice; what
+differs is the transport and nothing else. The Node one is its own file
+so that a worker bundle never pulls `node:http2` in, which is why nothing
+terrain neutral names it and `dock/index.ts` does not export it. All of
+this is here rather than in the being because a being names no terrain.
+
+## The edge, as built
+
+`packages/dock/harbor/edge/` is the core over one Durable Object, and the object
+is the harbor. The platform runs one instance of it at a time, which is
+the lease and the single writer every ward needs. Its storage is the
+store, `storage.ts`: one row per ward, seed, partition and record, with the
+seed sealed by `seal.ts` under a key from the platform's secrets,
+`QUO_SEED_KEY`, so the storage holds ciphertext and the secret store holds
+the one key, as the table above says. The deployed worker is the code, the
+built-in beings and whatever it hands in. It is a listener and never a
+dialer: reached by request at `<origin>/h/<name>/quo`, holding the sockets
+dialers open to it on the platform's own socket pair, the rendezvous for
+them, awake per request and kept awake by a held socket.
+
+Its owner door is a route, not a socket, because the platform has no local
+process: the root is whoever holds `QUO_ROOT`, a platform secret, and the
+root's asks arrive as one POST at `<origin>/h/<name>/root` under it, the
+first of them `{ init: { ward, user } }`, the root's setup. That is the
+device's own rule on this terrain, as file permissions are on a disk. The
+first thing a root on the edge does is invite an owner on the ward's pk,
+and from then on the edge is piloted from elsewhere over a standing, with
+`--via`, like any ward.
+
+What a side mounted there is given is one shape, `given.ts`, and it arrives
+in two halves because the halves change at different times. The deploy
+carries the tab's bundle and the service worker's, as text modules a
+`type = "Text"` rule in the `wrangler.toml` names, since a built artefact of
+a deploy is not a row a ward keeps. What is worn or configured while the
+worker runs is rows in the object's own storage, written by the root's door:
+the public origins, the apps table and the bell key under `settings`, and the
+design a world wears one row per file. So the four routes run there with
+nothing of them changed. `<origin>/h/<name>/web/<ward>` is a world's page, and
+the routes that page hands its tab are the worker's own until a root names
+public ones; `<origin>/h/<name>/api` is a describe as JSON for a stranger or
+a bearer, and `<origin>/h/<name>/mcp` is the dance and the endpoint, with the
+dance's records kept in the same object under one key.
+
+A worker stands a box ward, like every other terrain: the box's state has one
+home everywhere, the dock ward's partition, and a terrain that cannot stand
+that ward does not get a second place to keep box state. What differs by
+terrain is which faculties the ward lends, and `given.ts` holds the edge's
+list with the reason for each name that is missing. It lends two. `grants`,
+the bearers its routes honour, which is a record in her cells and the same
+code here as on a disk. And `timer`, on the object's own storage alarm:
+`Alarm` in `edge/alarm.ts` is the box's timer with the one method that knows
+a terrain replaced, since a `setTimeout` dies with the request and an alarm
+does not. One harbor is one object and every ward of it lives there, so the
+alarm wakes the whole harbor and a tick from the timer to a home's Clock is
+in-process here as it is on a disk. The object's `alarm` handler opens the
+harbor, boots every ward from storage and runs the round, so a home on the
+edge with a sweep at three in the morning wakes for it with no request to
+cause it.
+
+The other two are not lent: no place and no screen, since a worker is at
+neither; and no ring, since a ring is signed under this world's own web
+origin and a worker learns its origin from the request and not at boot. A
+faculty the platform has no answer for is not lent, rather than lent and
+hollow.
+
+Which ward a caller who names none is at is the terrain's word too. On a disk
+it is the mark an operator wrote in the folder; at the edge it is the one
+world the object holds, and an object holding several says nothing rather
+than guessing.
+
+The proof is `packages/dock/test/terrain/edge.test.ts`, behind
+`npm run deep:dock`, in the platform's own runtime on loopback under
+`wrangler dev`: the conformance suite, untouched, inside the platform
+against two edge harbors in one object over two prefixed views of its
+storage, reaching each other by request through the worker; the root door
+refused without the secret and answering under it; the box configured after
+it is deployed, its settings merged and answered and a design file worn and
+taken off; a world's page served out of the deploy's bundles and those rows;
+an invitation traded for a bearer at the program side, an ask through the
+avatar answered with the same JSON a Node daemon answers, and the model side
+challenging a caller with no bearer; a home keeping a one-shot for the next
+minute and being woken for it with nothing asking, the fire written down at
+the minute it named and read back a minute later; and a Node daemon
+dialing the edge, its pk held there, reached by a third harbor through the
+edge, unreached when the line drops. Two platform rules shape it: one object
+may not touch another's storage, so the exercise's two harbors share one
+object the way two tabs share a page; and the platform's crypto refuses a
+Uint8Array over a shared buffer and wants a plain one.
+
+The `ws` question the road asked is answered by this terrain: the socket
+reach's framing and the dialer are written on the standard surface and
+hold on every terrain; the listener half is the terrain's own, `ws` on
+Node and the socket pair on the edge, and stays where the terrain is. What
+the library takes, when it takes the reach, is the framing and the dialer.
+
+## The phone, as built
+
+`sealed.ts` is the store an app holds on a device in a hand, the phone and
+the desk alike: one key per harbor in the platform's secret store, marked
+this device only so it never travels in a backup, and one sealed file per
+ward, seed, partition and record as one blob, in a folder no backup
+copies. The seal is `seal.ts`, the same piece the daemon and the edge use.
+Opening the store is where custody is decided, since a backup is the one
+copy nobody makes on purpose: a key with no folder is a reinstall, and the
+stale key is deleted; a folder with no key is a restore to another device,
+and the unreadable files are deleted; either way the harbor starts fresh
+and there is never a twin. What a platform hands it is two small seams,
+files and secrets, and the rule is proven once on the two in memory,
+`test/sealed.test.ts`. `capacitor.ts` hands the phone's, the Filesystem
+plugin in the folder iCloud does not copy and a secure-storage plugin over
+the Keychain. The app that holds the store is `app/`, which the dock does
+not know. Its page is `app/phone/entry.ts`, terrain glue and nothing else:
+this harbor, the dock's shell over it, and the link the platform hands the
+app, as the launch URL and then on every link opened while it runs.
+
+The harbor on a phone is the browser harbor, `browser.ts`, over that
+store: the browser harbor takes a name, which is an IndexedDB database
+under a web lock, or a store handed in, whose lease is the process that
+holds it, since an app has one harbor and nothing else can open its
+files. `nativeHarbor` in `capacitor.ts` is that harbor booted and armed:
+the App plugin's foreground event tells it `wake`, which tells every
+dialer, because a phone asleep loses its sockets silently and the wake is
+what dials them back.
+
+On Android the same store stands on the same two plugins: the key in the
+Keystore-backed secure store, the files in the app's own data folder,
+which the manifest excludes from backup with `allowBackup` false, so a
+restore finds nothing there either.
+
+The phone's faculties are its plugins, geolocation and local
+notifications, and `capacitor.ts` is two being classes over them, booted
+into the phone's dock ward and lent by name: a position as latitude,
+longitude, accuracy and time, and a notification shown under a
+title. The platform's permission prompt is the first ask's; the terrain
+grants it ahead, since no script taps a prompt, with `simctl privacy` and a
+set location on iOS, and with `pm grant` and a geo fix on Android.
+
+On iOS the notifications faculty also plants the banner key, which is the
+one thing a second process needs and cannot ask a ward for. It goes
+through the same secure store the harbor keeps its own key in: an item
+written there lands in the app's first keychain group, which is the group
+the notification extension is in, so the two meet with nothing written to
+make them meet. A plugin of the app's own could not carry it, because the
+bridge builds the page's plugin headers before it hands control to the
+app, and the list that registers one earlier is a file `cap sync`
+rewrites.
+
+A notification is scheduled with `isExactNotification` false, which is not
+the plugin's default. A notification that wants an exact alarm and has no
+permission for one opens the Alarms and reminders settings screen on
+Android 12 and up, and the call never answers until a human comes back
+from it, so the ask goes `late` and nothing says why. Ours is shown now
+and waits for no clock, and the permission it would otherwise want is one
+a store asks an alarm app to justify.
+
+The phone's ear is one more function from the same file, `phoneEar`,
+handed to the shell rather than to a class, since the token is the box's
+and no being's; what the human reads after a wake is the Notifications
+faculty's ask, made by the shell through the harbor's own pointer, and no
+second body. The ear registers for
+remote notifications and answers the token, `apns` on one platform and
+`fcm` on the other, and it is never sprung: registering is what puts the
+permission prompt up, and an app that asks the moment it opens is an app a
+human refuses on principle, so it answers null until notifications are
+already allowed, which they are on the phone's own screen. The token
+arrives as an event rather than as an answer, so the registration is
+awaited once and kept, and the shell asks again on every foreground
+because the platform hands out a new one whenever it likes. Which of
+Apple's two push hosts minted it is the build's word and not the token's:
+`phone/build.ts` writes in whether this shell was built pointed at a
+world, which is the same signal that decides the link claim, and a build
+told nothing is the store build that speaks to the production host.
+
+The proof is two tests behind `npm run deep:app` on one stage,
+`packages/dock/test/terrain/phone.ts`: `ios.test.ts` inside the real app
+in the iOS Simulator and `android.test.ts` inside it in the Android
+emulator. Each runs the store suite, untouched, and the custody rule
+against a real secret store and a real folder; the whole conformance
+suite over two harbors on native stores, both dialing a daemon on the
+Mac's loopback through the tab's own probe; the wake, the app sent
+behind Settings and brought back, its dialer told and its socket held
+again; and the phone joining the daemon's world on an invitation, then a
+model on the daemon asking the user being where the phone is, reaching the
+phone's being on the standing home holds and her own location faculty
+behind it, and getting where the Simulator or the emulator was put.
+The app is synced with the stage's
+origin as its page, built with xcodebuild or gradle, installed fresh and
+launched with simctl or adb; the
+page loads the bundled exercise, `native.ts`, runs it and posts the list
+back. The device names the Mac `localhost`, the Simulator because it
+shares the Mac's network and the emulator because adb reverses the
+stage's two ports, and it has to be that name: a webview grants WebCrypto
+to a plain-http page only on `localhost`, the one origin it counts secure
+without TLS. Through adb's reversed port a socket that Node dropped stays
+open on the device's side, so the stage answers every request with the
+connection closed and every fetch the page makes carries a timeout. Two
+things the plugins taught, held in the store: the secure store keeps
+JSON, so a value is read with the call that parses; and mkdir refuses a
+folder that exists, recursive or not.
+
+## The desk
+
+The desk app is the phone's shell on a desk: the same browser harbor, over
+the same sealed store, showing the same screen, and a presence like the
+phone. `app/tauri/` is the Tauri project, and its Rust core holds three
+small things and nothing else: the files under the app's own data folder,
+which no backup copies, refusing a path that climbs out of it; the keys in
+the OS keychain under the app's service name, this device only; and the
+notification center. `tauri.ts` hands the first two to the sealed store as
+its seams over the core's commands, and its notifications faculty asks
+the third. The window runs `human/app.ts` over that harbor, one ward per
+world, every world dialed, carries the dock's stylesheet in its bundle,
+and tells the harbor it is back whenever the window comes to the front,
+since a desk sleeps and wakes like a phone.
+
+The desk's dock ward lends what a desk has: notifications through the
+platform's notification center, and nothing else. Location is what the
+platform gives, which on a desk is nothing, so it is not lent rather than
+lent and dumb. No timer, because a desk holds presences and no home, so no
+Clock lives on it and a Timer there would arm for nobody; a Timer stands
+only on a box that hosts a home. It has no ear, since no store rings a
+desk, so a desk is reached while the app is open and drains what it
+missed when it opens. The one
+window the desk app has is a surface over the DOM like the tab's, and the
+screen runs in it: nothing of the desk app is a daemon, spawns one or
+attaches to one. A person who wants a home on a Mac runs `quo serve` on it
+as an operator, and that is a home like any other and no concern of the
+app's.
+
+The desk has no honest link. macOS verifies an associated domain for an
+app on the store and Windows and Linux verify nothing, so a join link on a
+desk opens the browser, and the way a world reaches the desk app is the
+Courier: the tab offers, the desk app takes the offer typed or pasted in.
+The store and its custody rule are proven on the two seams in memory, and
+the desk's seams, the keychain and the folder, are proven live: the app
+built with cargo, coming up cold on the Console on the operator's Mac.
+
+## The link
+
+An invitation carries the ward pk of the world that minted it, and not where
+that pk lives. A harbor that has never heard of that world cannot carry the
+first knock. So a link is an invitation next to a **reach hint**, the URL of
+that world's `quo.` route. The being receives the invitation opaque, as
+always; the hint goes to the directory. The link is single-use, because the
+heir dies at the first knock, and whoever opens it first is bound.
+
+## Routes on a daemon
+
+```
+device
+  quo serve                      one process, one harbor, the ask pointer
+    quo.sock                     owner asks; local only; never behind a proxy
+    side.sock                    local sides; local only; never behind a proxy
+    127.0.0.1:8787               the HTTP door, loopback only; routes mount by path
+      /health                    the wards it hosts, by name and pk, and the saves refused; harbor/http.ts
+      /mcp                       the model side; mcp/route.ts
+      /web                       the worlds' pages and the allow page; human/web.ts, mcp/allow.ts
+      /quo                       the socket door: request in, sockets held, the rendezvous; harbor/quo.ts
+      /api                       a describe as JSON, a stranger's or a bearer's; api/route.ts
+  reverse proxy
+    mcp.example.com -> 127.0.0.1:8787/mcp
+    web.example.com -> 127.0.0.1:8787/web
+    quo.example.com -> 127.0.0.1:8787/quo
+    api.example.com -> 127.0.0.1:8787/api
+```
+
+A route is `Request` in and `Response` out, the shapes every runtime speaks,
+and `packages/dock/harbor/http.ts` is that contract. A handler answering
+nothing declines and the mount tries what comes after it. `listenHttp` is
+the one place Node's own objects appear: its door turns an `IncomingMessage`
+into a `Request` and writes a `Response` back onto a `ServerResponse`, and
+no route names either. So the same route runs on this daemon, on a worker at
+the edge, in a browser's own service worker, on Deno and on Bun, and the
+terrain is the door and never the side.
+
+The daemon listens on loopback only, and only when asked, with `--http PORT`
+or `QUO_HTTP`. The proxy faces the world and terminates TLS; the daemon never
+does. `quo estate` writes a systemd unit that runs the daemon as one user
+forever, a launchd agent that does the same on a Mac, and a Caddyfile that
+maps the hostnames onto the one port by path, from the templates in
+`packages/dock/cli/estate/`.
+Unattended, the daemon is that unit: restarted if it dies, the lease
+released on SIGTERM, and every ward rebooted from its folder on the next
+start with relations intact. A Mac is a dialer and not a listener: its
+agent opens no HTTP door, and the routes it holds a socket to are rows the
+root kept on its `dialers` faculty.
+
+The socket is the root owner. Owning a droplet from elsewhere is a standing
+at its ward, minted by the root, carried as a sealed ask like any relation.
+There is no `cli.` route.
+
+**Where the addresses come from, per terrain.** One convention holds
+everywhere: the four routes are `mcp.`, `web.`, `quo.` and `api.` under one
+domain, over https, and nobody types a hostname four times. On a droplet
+the domain is said once, `quo init --domain acme.com` or `quo domain
+acme.com`, and `<dir>/routes.json` is written by the convention; an estate
+whose names break it edits that file, and it is the one file that stands
+beside the wards by right, since a ward knows its pk and never its
+hostname, which is the proxy's fact. With no `routes.json` the daemon
+serves `/web`, `/api` and `/quo` on its loopback door, names that door in
+pages and links, and opens no model door, since OAuth needs a public
+issuer. The app types nothing: it opens a link, the link carries the
+world's `quo.` hint, and the world's `GET /web/` hands it the harbor's
+whole config. The edge is its own origin, `<origin>/h/<name>/quo`, known at
+deploy. A tab is the origin it was served from, with the `quo` address in
+the page's config script. So a domain is said in one place, on the box,
+and every other terrain learns the addresses from a link or a request.
+
+## Acceptance
+
+A harbor here is accepted when it passes the library's conformance suite
+untouched, and by nothing else. Three do: the disk harbor over the wire
+under both reaches, the browser harbor through a daemon, and the edge harbor
+inside the platform's runtime. Every store passes the library's store suite,
+`packages/quo/src/conformance/store.ts`: files in
+`packages/dock/test/store.test.ts`, IndexedDB and the edge's storage inside
+their terrains behind `deep:dock`. Every reach passes the library's reach
+suite, `packages/quo/src/conformance/reach.ts`. The store, the reach and the
+core are the library's, and every harbor here is one of them over its own
+terrain.
+
+## Where the tree stands
+
+The one place under this paper where a gap between it and the folders is
+named. Each line is a debt to close, not a note to keep.
+
+- **A torn write is read, not refused.** A plain store keeps a ward as
+  rows written one after another, and a write interrupted between two of
+  them leaves rows that do not belong to one another. The partition
+  assembled from them boots; it should refuse to, and say which row is
+  wrong, the way a shape it cannot read already does.
+- **A sealed store is one value per ward, and whether it should be rows is
+  undecided.** The phone and the desk seal the whole ward under one key, so
+  a being with much in her cells costs her neighbours there as she costs
+  nobody on a droplet, in a tab or on the edge. Rows there are one seal per
+  being and move the custody rule the sealed store is written around, and
+  that is a question about what a restore means before it is one about
+  speed. The human decides it, and not in passing.