@nervur-org/dock 0.4.0 → 0.5.0

package/quo-harbor.md

@@ -1,874 +0,0 @@
-# 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 a ward or a far harbor can observe: what is written here that the
-protocol does not say is a device's own half, a store, a lease, a loader, a
-core and a dialer's patience, and a second kit that answers the same bytes owes
-none of 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 `NERVUR_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**, `nervur 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 dialer holds one socket to a URL, announces the pks
-this harbor holds when the line opens and again whenever they change, and
-dials again with a wait that backs off to a ceiling when the line drops; how
-far it backs off is this harbor's, and the wait goes back to the shortest one
-where the far side announced and was taken, not where the line merely opened,
-or a listener that opens and then refuses is dialed at one short wait for
-good. A harbor may dial several listeners, and a pk nobody here knows is
-tried down that list in order.
-
-A device that comes back from sleep tells its dialer so, `wake`: whatever
-line it holds, open or still opening, is put down and a new one is dialed
-now, the frozen wait called off. Nothing can tell a line the system closed
-under a sleeping device from a live one, and asking would cost a round trip
-the four words do not have; an announce written into a dead line sits in the
-send buffer and errors only when TCP gives up, minutes later, and for all of
-it every ask to a pk bound behind that line hears `late`. Dialing costs one
-handshake when the line was fine, and an ask made meanwhile waits on the new
-socket. A line put down this way closes when the system gets round to it and
-dials nothing: only the line the dialer still holds dials again. A phone's
-ask must survive a push wake-up, and 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/nervur/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 with code 4001; a request door answers
-nothing delivered. A dialer refused that way waits out its ceiling before
-asking again, because a suite does not become speakable by asking sooner.
-`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/nervur/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, `nervur 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, `nervur 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/nervur/src/harbor/core.ts`, and so is
-the dialer, `packages/nervur/src/harbor/dial.ts`. Neither is a word of the
-protocol: `quo/SPEC.md` says what a harbor owes a ward and what a reach owes
-a far harbor, and a core and a dialer are how this kit pays both on every
-terrain. 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 `NERVUR_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,
-`NERVUR_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 `NERVUR_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, `nervur` unless one is given, which
-is an IndexedDB database under the web lock `nervur:<name>`, 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 `nervur 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
-  nervur serve                      one process, one harbor, the ask pointer
-    nervur.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 `NERVUR_HTTP`. The proxy faces the world and terminates TLS; the daemon never
-does. `nervur 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, `nervur init --domain acme.com` or `nervur 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/nervur/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/nervur/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.