@quo-systems/dock 0.2.1 → 0.2.2

package/beings/avatar.ts

@@ -4,7 +4,9 @@
 // exactly one standing, `user`, and everything her side asks goes through
 // it; the user being reaches her only to push, and she hands the push to
 // every side she has. A side is in-process with her, holds the object, and
-// calls the three methods below. Nothing of a side is in her cells.
+// calls the four methods below: one of the two ways in, `enter` behind a
+// route's proof or `join` with an invitation, then `tools` and `call`.
+// Nothing of a side is in her cells.
 import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
 import type { Answer, Blueprint, Invitation, JsonObject, OccupantRecord, Wanted } from '@quo-systems/quo';
 

package/beings/index.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0
-// The beings every side shares. See quo-estate.md, the trunk.
+// The beings every side shares. See quo-dock.md, the trunk.
 export { User, DESK } from './user.ts';
 export { Desk, type Proof, type Verified, type Verifier } from './desk.ts';
 export { Avatar, USER, PUSHER } from './avatar.ts';

package/beings/quo-dock.md

@@ -124,6 +124,31 @@ that every arrival is named and judged.
 - **Route.** A hostname a reverse proxy sends to one process: `web.`, `quo.`,
   `mcp.`. Routes are deployment, never boundaries.
 
+## The ids
+
+Every relation here is named by an id one being minted, and the dock's own
+are these. They are conventions of this package and nothing of Quo's; a
+different estate could choose others and change no word of the spec.
+
+| id                  | who holds it   | what it names                            |
+| ------------------- | -------------- | ---------------------------------------- |
+| `desk`              | the user being | the front desk, her privileged occupant  |
+| `user:<name>`       | the front desk | its standing to that human's user being  |
+| `<client>`          | the user being | one device, by its client identity       |
+| `to:<client>`       | the user being | her way back to that device              |
+| `user`              | an avatar      | her one standing, at the user being      |
+| `user:push`         | an avatar      | the user being as her occupant, to push  |
+| `avatar:<identity>` | the ward       | the being key one client identity boots  |
+
+A device is two relations, because a relation in Quo is one direction: its
+way in, the occupant, and her way back, `to:<client>`. Neither implies the
+other and the door never joins them. The user being joins them herself, as
+her own rule: she does not push to a device she no longer admits, and
+`forget` drops both in one act. Her way back is handed over at hello and
+taken when it can be: a knock back that is unreached, a tab whose pk the
+far harbor has not bound yet or a phone in a tunnel, spends nothing, so she
+keeps the invitation and takes it at the next push. A refusal is final.
+
 ## Architecture
 
 One droplet, one harbor, three routes. Every other placement is a subset.
@@ -173,6 +198,15 @@ standing to the user being is minted once and persists in the partition; a
 side opening and closing is a reconnect, and the keys carry on. Reconnect
 never re-invites.
 
+An avatar is one standing, and a harbor holds as many avatars as it holds
+relations; a ward only groups them. The droplet groups by client identity
+per world, in the avatars ward. A tab groups by world, one local ward per
+far world and one avatar per relation in it, so a fresh invitation is
+always a fresh avatar and never a join on one that already holds hers: two
+invitations into one world are two avatars, and two humans on one family
+tablet are two relations. Which avatar a side speaks through is a switch
+and nothing more.
+
 One class for every side. It has:
 
 - `answer`: the user being asks her only to push, and she forwards the push
@@ -211,8 +245,8 @@ last word. A push is the trigger of a turn, never a line smuggled into one:
 a push that arrives while a turn is running waits in her cells and starts
 the next turn when this one ends. Nothing is dropped and nothing is held;
 the ask that carried the push was answered the moment it landed. Between
-turns, the world reaches a model the way step 11 says, an ask that starts a
-run and a callback when it ends.
+turns, the world reaches a model as `packages/dock/mcp/quo-mcp.md` says: an
+ask that starts a run, and a callback when it ends.
 
 One describe, many renderings. A screen is the user being's describe spoken
 as forms; a tool list is the same describe spoken as tools. Nobody builds a
@@ -340,12 +374,32 @@ gate reads the note: `push` is shown to the desk and to a device with the
 `wake` note, and her standings are carried for a device with the `reach`
 note, and for nobody else. A device that may wake can hand an agent an event
 through the user being, and she sees who did; a device that may reach sees
-acme on her, and a model sees acme only because the human said it may. A tab
-opened with the owner password reaches, since the owner opened it. The notes
-are written when the occupant is minted; to change one, remove the occupant
-and allow again, because reconnect mints nothing.
-
-Tokens, cookies and grants exist for the length of step 1 and are never
+acme on her, and a model sees acme only because the human said it may. The
+notes are written when the occupant is minted; to change one, remove the
+occupant and allow again, because reconnect mints nothing. A device the
+root mints on her directly, with `quo invite`, carries no note: the id the
+root chose is its client identity, and it reaches and may wake, since the
+root owns everything she holds and chose to mint it.
+
+Two proof kinds exist, and each arrives only the one way it is made:
+`local`, a side that reached the daemon's side socket; `web`, a human who
+passed the exchange pages. Each is a nonce the daemon minted for one kind
+and honours once, under that kind alone, so a proof of any other provenance
+names no nonce and is refused. A human at a screen passes no exchange: a
+tab enters by a link, an invitation a user being minted, and nothing is
+ever typed to get in. The root's first device is no exception; the root
+mints its invitation with `quo invite` on the box and opens the link.
+
+The route's own lifetimes, where it speaks OAuth: a pending request and a
+code live ten minutes, an access token one hour, a refresh token thirty
+days. A registered client lives ten minutes, and as long as its refresh
+token once the human allowed it, since the register door is open to anyone
+and what nobody allowed must not stay on disk. A code is spent the first
+time it is offered, right or wrong. The client identity is chosen by the
+human at the allow page and never taken from the client's registration: a
+client may register afresh on every connect, and the avatar outlives that.
+
+Tokens, cookies and grants exist for the length of step 1 above and are never
 stored on a Quo side. Revocation is `occupants.remove(id)` on the user being:
 the client's next ask, under the key the door bound for its avatar, hears
 `removed`, and the side speaks that in its own vocabulary: the MCP route
@@ -355,7 +409,11 @@ answers 401 at the next session and forgets the grant.
 
 One command, `quo`, under `packages/dock/cli/`. It imports the four library exports
 and nothing else, holds no class body, and never speaks to a ward except
-through the ask pointer or an avatar, the two doors everyone has.
+through the ask pointer or an avatar, the two doors everyone has. The
+daemon's folder holds the process and its doors, the two sockets and the
+HTTP listener; each route on that listener lives in the folder whose truth
+it is, `human/web.ts`, `mcp/route.ts`, `harbor/quo.ts`, and the daemon only
+mounts them.
 
 ```
 quo init [--dir D]        mint a seed, boot a harbor and one ward over a disk store, write both
@@ -465,8 +523,8 @@ to be decided.
 
 ## Generality
 
-Six general pieces exist under `packages/dock/`, and everything concrete is an
-implementation of one of them. An estate implements none of them: it holds
+Eight general pieces exist under `packages/dock/`, and everything concrete is
+an implementation of one of them. An estate implements none of them: it holds
 class bodies and placement, and reaches every piece through the dock.
 
 | piece        | one interface for                          | implementations                                  |
@@ -489,8 +547,8 @@ Two rules keep them general:
 
 Harbor core, reach and store held across three terrains and moved into
 `packages/quo/src` with `packages/quo/SPEC.md` in the same commit on 2026-09-04;
-what stays here of them is each terrain's store, loader, lease and listener. The
-other three are dock conventions and stay here.
+what stays here of them is each terrain's store, loader, lease and listener.
+The other five are dock conventions and stay here.
 
 ## Invariants
 
@@ -518,8 +576,11 @@ other three are dock conventions and stay here.
 
 ## Where the dock stands
 
-The one place under `packages/dock/` where a gap between these documents and the
-folders is named. Each line is a debt to close, not a note to keep.
+The one place under `packages/dock/` where a gap between these documents and
+the folders is named. Each line is a debt to close, not a note to keep.
+
+No gap today. Everything these documents describe is in the folders and on
+the machines, and MCP is complete.
 
 Two rules hold:
 
@@ -533,292 +594,7 @@ Two rules hold:
   keep in step with every change, and the vectors under `packages/quo/vectors/`
   are the hand that will be extended when the time comes.
 
-The order of work, each step usable on its own and each proving a sentence
-above or sending us back to fix it:
-
-1. Done. `packages/dock/` scaffold: its own package linking the library, the
-   four exports only, `check:dock` in the root gate, the terrain test pointed at
-   `packages/dock/beings`. The disk harbor in `packages/dock/harbor/disk.ts`:
-   one folder per ward holding seed, partition and the class source, a ward
-   record, the lease, and a save after every call. The `quo` CLI: init, serve,
-   census, boot, invite, knock, over the daemon's unix socket. Pilot and side
-   landed at steps 4 and 5.
-2. Done. The beings in `packages/dock/beings/`: `User`, `Desk`, `Avatar`, proven
-   on the memory harbor in `packages/dock/test/beings.test.ts`. A fake proof
-   becomes an invitation the user being minted, the avatar knocks and takes
-   her, and her tool list equals the user being's describe for her;
-   reconnect mints nothing; two clients see two tool lists; a push is a
-   reverse ask that reaches the side; revocation is her sixth ask,
-   `forget({ client })`, the desk's alone. The ids that
-   carry the conventions: the desk is the occupant the root named `desk`
-   at the user being; the desk holds each user being as `user:<name>`; the
-   user being holds each device's way back as `to:<client>`; the avatar
-   holds the user being as `user` and is pushed to as `user:push`, two ids
-   because standings and occupants share one namespace.
-   A device is two relations, because a relation in Quo is one direction:
-   its way in, the occupant, and her way back, `to:<client>`. Neither
-   implies the other, and the door will never join them. She joins them
-   herself, as her own rule and not Quo's: she does not push to a device
-   she no longer admits, and `forget` drops both in one act, so no side
-   has to remember there were two. Before this a revoked device kept
-   receiving every push.
-3. Done. The side in `packages/dock/beings/side.ts`: a function of the avatar
-   that runs until closed, and `word`, which tells the three words and the
-   object apart before any side renders them. The MCP server in
-   `packages/dock/mcp/server.ts`, proven over the SDK's in-memory transport in
-   `packages/dock/test/mcp.test.ts`: tools/list is her describe spoken as tools,
-   tools/call is a named ask, an object is a result, an error object and
-   the two words are error results with the text the trunk gives them, a
-   push is a logging notification, and a session closing and opening
-   reuses the standing. The SDK is the dock's first dependency, under
-   `packages/dock/` alone.
-4. Done. `quo side --as NAME` over stdio, proven in
-   `packages/dock/test/cli.test.ts` with the SDK's stdio client as a child
-   process: the daemon finds or boots
-   `avatar:NAME`, enters her with a nonce the desk honours once, and runs
-   the model side beside her; the tool list is the user being's describe
-   for that client; a second start is a reconnect and mints nothing; a
-   `local` proof from anywhere else is refused. `quo init` now does the
-   root's setup, the desk public and one user being named by `--user`, so
-   a fresh folder is a world. Claude Code and Claude Desktop on the Mac
-   need only `quo serve` running and `quo side --as claude` as the server
-   command: no droplet, no OAuth.
-5. Done. `quo pilot` in `packages/dock/mcp/pilot.ts`, proven in
-   `packages/dock/test/cli.test.ts` with the SDK's stdio client as a child
-   process: the model side of step 3 over the ward's owner asks, the
-   ward's describe as tools and no list of its own, each call an owner ask
-   on the daemon's root socket, and nothing logged. It is the root and not
-   an avatar: nothing is booted for it and no occupant is minted for it.
-   With no daemon it says so and exits. Claude Code as the owner is
-   `claude mcp add` with `quo pilot` as the command.
-6. Done. `quo serve --http PORT`: the HTTP door on loopback, `/health`
-   naming the wards, routes mounting by path so a hostname on the proxy is
-   a path on the daemon; proven in `packages/dock/test/cli.test.ts`. The systemd
-   unit and the Caddyfile are in `estates/lab/droplet/`. Disk store, the
-   lease and reboot from disk with relations intact were steps 1 and 4.
-7. Done. OAuth on the `mcp.` route in `packages/dock/mcp/oauth.ts`, mounted by
-   the daemon when `<dir>/routes.json` names the two public origins, and
-   proven over real HTTP in `packages/dock/test/oauth.test.ts`: metadata,
-   protected-resource metadata, dynamic registration, PKCE with S256, the
-   code grant, refresh with rotation, opaque tokens mapping a bearer to a
-   client identity, revoke by identity, and expiry. The conventions pinned
-   here: a pending request and a code live ten minutes, an access token
-   one hour, a refresh token thirty days; a registered client lives ten
-   minutes, and as long as its refresh token once the human allowed it,
-   since the register door is open to anyone and what nobody allowed must
-   not stay on disk; a code is spent the first time
-   it is offered, right or wrong; the client identity is chosen at the
-   allow page, not taken from the client's registration, because a client
-   like claude.ai registers a fresh client id on every connect and the
-   avatar must outlive that. The store is `<dir>/oauth.json`, the route's
-   own, mode 0600, and holds no secret of Quo's.
-8. Done. The exchange pages in `packages/dock/mcp/web/exchange.ts`, mounted on
-   the web route, proven over real HTTP in `packages/dock/test/web.test.ts`.
-   Login checks `QUO_OWNER_PASSWORD` in constant time and sets a signed
-   session cookie that lives ten minutes, the life of a request; with no
-   password set the exchange is closed. Allow names the client, where it
-   returns to, and the identity it will be, suggested from the client's
-   name and editable, one word and not the user or the desk. Allow admits
-   her through the one path every side uses: find or boot the avatar,
-   enter with a nonce the desk honours once under the `web` proof kind,
-   then complete the OAuth request with that identity. Deny sends the
-   client `access_denied`. Two pages, hand-written, rendering no blueprint.
-9. Done. The MCP endpoint in `packages/dock/mcp/http.ts` at `/mcp` on the mcp
-   route: streamable HTTP, a bearer names the identity, the identity names
-   her avatar through the same admit path, the side from step 3 runs
-   beside her, one session per connection, a session belonging to the
-   identity that opened it. Proven in `packages/dock/test/http.test.ts` with the
-   SDK's streamable HTTP client over the whole exchange. MCP is complete:
-   every human-assisted case on every device, with nothing of Quo's
-   crossing a machine.
-10. Done. The runner in `packages/dock/mcp/runner.ts`: the second side, an MCP
-    client written inline for a model that speaks function calling. Her
-    describe is a tools array, a tool call is a named ask, the three words
-    are tool messages, a line from the human or a push from the user being
-    starts a turn, and turns never overlap. Proven in
-    `packages/dock/test/runner.test.ts` over a scripted endpoint on loopback, and
-    live against Qwen3 Coder 30B in LM Studio on the Mac, which read her
-    describe, called `whoami` through the gate and answered with the id she
-    minted. What it taught: LM Studio refuses a parameters schema with no
-    `properties`, so the runner is where a describe is narrowed for an
-    endpoint, and nowhere else.
-11. Done. The agent side in `packages/dock/mcp/agent.ts`: the world is the loop.
-    A push from the user being is acknowledged at once by her `notify`,
-    lands in her inbox, which is the queue in her cells, and the side runs
-    it, one event at a time in order, then asks the user being back with
-    `report({ event, result })`, the ask this step added to her, gated to
-    devices. A run is a function of the event or a process in the agent's
-    folder with the event as its last argument, which is what `claude -p`
-    is. Proven in `packages/dock/test/agent.test.ts` with a fake run and a fake
-    process: the ask is answered before the run ends, a throw reports an
-    error object, and events that came while no side was up run when one
-    comes up. What it decided: the queue lives in the partition and not in
-    the side, so a restart loses nothing but the one run in flight. On a
-    device, `<dir>/agents.json` names each agent's identity, command and
-    folder, and the daemon admits her on the local proof and runs her side
-    beside her avatar; proven in the same suite over a disk harbor.
-12. The `quo.` route: Done. The reach interface with request and socket, since
-    the library move `packages/quo/src/harbor/reach.ts`, the disk harbor holds
-    the directory, and the daemon mounts `/quo` and dials with `--dial`. The
-    library's conformance suite passed untouched over two disk harbors on
-    loopback under both reaches, and the rendezvous carried a knock from a third
-    harbor to a dialer through its listener; `packages/dock/test/wire.test.ts`.
-    Live: a Mac daemon dialed `quo.lab.quo.systems`, an avatar there knocked at
-    the lab's user being across the internet, the lab knocked back over the held
-    socket and took `to:mac`, and a push from the lab landed in her inbox on the
-    Mac. What it taught: the proxy rewrites the route root with a trailing
-    slash, and a ward pk is 64 bytes on the wire;
-    `packages/dock/harbor/quo-harbor.md` has both.
-13. The browser harbor: Done. Harbor core carved out of the disk harbor
-    into a core of its own, since the library move `packages/quo/src/harbor/core.ts`,
-    the store a piece with files and IndexedDB under it, the dialer its
-    own terrain-free piece, the socket reach on the standard surface.
-    `packages/dock/harbor/browser.ts` is the core in a tab: IndexedDB, a web lock
-    for the lease, one socket per world.
-    The library's conformance suite passed untouched inside a real
-    Chromium against two browser harbors in one tab through a daemon on
-    loopback, migration between two databases included;
-    `packages/dock/test/terrain/browser.test.ts`, behind `check:terrain`. And the
-    first screen, `packages/dock/human/tab.ts`, rudimentary on purpose: a page on
-    the web route that boots a harbor in the tab, takes the owner password
-    once under the `tab` proof kind, and renders her describe as buttons,
-    with pushes landing on the page; a reload asks nothing. What it taught:
-    a tab's store keeps values through JSON because the cells guard refuses
-    structured clone; a side in a tab saves after the exchange and after
-    every call, as the daemon does; and a dialed socket is the fallback
-    from the moment it is dialed, because a ward asks the instant it boots.
-14. Owners at the door in the CLI: Done. The root socket takes `via`, a
-    standing the user being holds at another ward, and the daemon asks on
-    it in-process and saves; `quo pilot` and the bare owner asks take
-    `--via S`. Scene 8 on two daemons over a dialed socket in
-    `packages/dock/test/cli.test.ts`: the far root invites on its ward's pk, the
-    user being here knocks and takes `lab`, census and boot land there,
-    invite on the far pk is refused at the door, the standing survives a
-    restart, and the owner removed meets silence. What it taught: the
-    library had no owner ask that removes an owner, and the test reached
-    into the ward's cells; the word is `remove` now, decided in `packages/quo/SPEC.md`
-    at step 16.
-15. The human side, minimal: Done. Three pieces under `packages/dock/human/`:
-    `html.ts`, pure, a schema as a form, a form back as typed arguments,
-    an answer as a view, the three words with faces; `screen.ts`, the side
-    over a surface that can only show a page and hand back a form,
-    re-asking her describe after every call so the page follows the
-    digest; `dom.ts`, the surface on an element. The tab keeps its harbor
-    and exchange and hands the avatar to the side. Proven on the memory
-    harbor with a fake surface in `packages/dock/test/human.test.ts`, and in
-    Chromium behind `check:terrain`. Minimal on purpose: design, a
-    switcher, the guest's page and the native app are left to the human
-    document's own sitting, and none of them blocks a world from having
-    a screen.
-16. Removing: Done. `packages/quo/SPEC.md` gave the owner its fourth ask, `remove`,
-    the mirror of knock: a relation out of a being by id, occupant or
-    standing, and on the ward's own pk an owner, by the root alone. In
-    `packages/quo/src/ward/owner.ts` with its test; the pilot's fourth tool; `quo
-    remove` from the shell, the same word; the step 14 test asks it
-    instead of reaching into the cells. The lab's leftovers went with it,
-    recorded in `estates/lab/lab.md`.
-17. What the lab wants: Done. A launchd agent beside the systemd unit in
-    `estates/lab/droplet/`, the daemon as the user forever with
-    `~/.quo/dial.json` naming the routes it holds a socket to, installed
-    on the operator's Mac against the lab. And `quo run`: the runner from
-    a terminal, the same pipe as `quo side` with a model named in the
-    hello, the daemon running the runner beside the avatar, a line in a
-    turn and the final text a line out, proven with a scripted endpoint
-    as a child process in `packages/dock/test/cli.test.ts`.
-18. The edge terrain: Done. `packages/dock/harbor/edge/`, the core over a Durable
-    Object: its storage the store with the seed sealed under a platform
-    secret, the deployed worker the code, the object the lease; reached by
-    request, holding dialers' sockets, the root a route under a platform
-    secret. The conformance suite passed untouched inside the platform's
-    runtime, behind `check:terrain`; deployed to the lab's account and
-    piloted from the Mac over a standing, `--via edge`. The third terrain
-    the library move waited for; the `ws` question answered in the harbor
-    document. `estates/lab/lab.md` keeps the record, one slip included.
-
-19. The split: Done. The estate folder became the dock, the lab's own
-    things moved to `estates/lab/`, and the dock's package took its name.
-    Then the repository took the shape that says what ships by where it
-    lives: `packages/quo/` and `packages/dock/` are the two published
-    packages, `estates/` is private, and the root is nobody's package, the
-    workspaces and the gate. The lab is an estate folder of the shape this
-    document names, one folder per harbor, and `estates/lab/test/boot.test.ts`
-    is invariant 12 proven: a copy of the folder, the two packages installed
-    into it and nothing else, and the droplet boots. The lab redeployed
-    from it: the droplet from a clean export of HEAD with its unit copied
-    from the estate's folder, the edge from the estate's own config
-    resolving the dock's worker by name, the Mac's agent on the new path.
-    What it taught: a nested npm under `npm run` inherits the outer run's
-    local prefix by environment and installs into the repository instead
-    of the empty folder, so the stranger tests keep nothing of it; and
-    `npx` in a workspace runs at the package root, so an estate names its
-    edge config from its own folder.
-20. The dock published: Done. `@quo-systems/dock` 0.1.0, the same shape
-    the library took, an emitted `dist/` with the `quo` command pointing
-    into it, the source and the four documents beside it, and
-    `packages/dock/test/package.test.ts` as the one suite that meets it as
-    an adopter: the library's tarball and this one installed into an empty
-    folder with nothing but Node, then `quo init`, a daemon, and
-    `quo census` answering with the desk and the user being. The library
-    went to 0.2.0 first, since the door's words moved the wire. What it
-    decided: the daemon bundles the tab from beside itself, emitted or
-    source, whichever is there, the one place the dock reads a file by
-    path at run time.
-
-21. A second estate: Done, and live. `estates/gherghina/`,
-    staging like the lab and nothing more, one harbor on the shared droplet
-    `nervur-staging-0`, routes under `gherghina.quo.systems`, no agents and
-    no classes of its own yet, the same unit and Caddyfile shape as the
-    lab's. It is the first proof that the dock has two users: its folder
-    depends on the dock alone, and `estates/gherghina/test/boot.test.ts`
-    runs the one proof every estate here runs, `estates/proof.ts`, shared
-    between them and shipped nowhere. The three staging droplets are shared
-    by every estate in this repository, and none of them is production or
-    holds real data. Its droplet stood up the same day, its document says
-    how; what it taught went into both estates' units: the agent's folders
-    are optional to the daemon, since a harbor may have no agent.
-
-22. The scaffold: Done. `quo estate <dir> --domain D` writes an estate
-    folder of the shape the two estates here agreed on: a package file
-    depending on this dock and nothing else, one document to fill in, and
-    `droplet/` as the first harbor, its routes under the domain, no
-    agents, no classes of its own, and that device's unit and Caddyfile
-    from templates the dock ships beside its command. The unit it writes
-    runs the installed dock from the estate's folder on the box, since an
-    adopter has no tree there; the two estates here run the tree. Proven
-    in `packages/dock/test/cli.test.ts`: the folder is written, refuses to
-    overwrite a package or take a name that is no domain, and its droplet
-    boots, `quo init` into it and a daemon answering the census.
-
-23. The human side proper, in flight. What the twelfth sitting decided, in
-    the order it lands: **carrying**, `beings/carry.ts`, the user being on
-    it, a device seeing acme's asks on her under the `reach` note from the
-    exchange, proven in `test/human.test.ts` and `test/mcp.test.ts` on the
-    memory harbor with a shop that has a look; **the look**, `beings/look.ts`,
-    one closed vocabulary read by the screen as a section per standing under
-    its tokens and by the model side as titles and annotations, the `look`
-    ask neither a form nor a tool. Then **worlds**: a world is a ward with a
-    public being, its guest page is that being's describe rendered by the
-    screen, whatever class she is, `human/guest.ts`, and a form whose answer
-    is an invitation is the way in; worlds have addresses, `web./<ward>`,
-    `web./` the list, a hostname per world the proxy's line; a link is the
-    page plus the invitation in the fragment under the reserved key `quo`,
-    never in a query string, `beings/link.ts`; the tab is a browser of worlds,
-    one ward per joined world, a switcher over them, and a content security
-    policy on its shell; the avatar joins a being with no `hello` all the
-    same. Proven on the memory harbor with a door that is not a desk and in
-    Chromium against the desk. Then **the routes read again against the
-    same pieces**: a grant names the world the human allowed the client
-    into, the allow page offers the harbor's worlds when it has more than
-    one, a session is an identity's in a world, and revocation is per world;
-    the MCP endpoint stays one per harbor, `/mcp`, since the grant says
-    which world. Done. What the lab taught before any of it was
-    written: a standing's blueprint is empty after take until the empty ask
-    fills it, so a carrier refreshes on describe; and a dotted name is
-    refused by the model side, so a carried name takes a dash.
-
-Steps 1 to 22 are in the tree and on the machines, and MCP is complete;
-the documents and the folders agree up to step 22, and step 23 is in flight
-as its line says. `next.md` is where the next sitting starts.
+`next.md` is where the next sitting starts.
 
 ## Glossary
 

package/beings/user.ts

@@ -12,19 +12,29 @@ import { Carrier } from './carry.ts';
 export const DESK = 'desk';
 const isDesk = (occ: OccupantRecord | undefined) => occ?.id === DESK;
 const isDevice = (occ: OccupantRecord | undefined) => occ !== undefined && occ.id !== DESK;
-const client = (occ: OccupantRecord | undefined) => (typeof occ?.notes.client === 'string' ? occ.notes.client : null);
-// A device the human allowed to wake her other devices: the note says so.
-const mayWake = (occ: OccupantRecord | undefined) => isDesk(occ) || occ?.notes.wake === true;
+// A device is known by its client identity. The desk writes it as a note
+// when it asks her to mint; the root, minting on her directly, writes
+// nothing, and then the id the root chose is the identity.
+const rootMinted = (occ: OccupantRecord | undefined) => isDevice(occ) && occ?.notes.client === undefined;
+const client = (occ: OccupantRecord | undefined) => (typeof occ?.notes.client === 'string' ? occ.notes.client : rootMinted(occ) ? occ!.id : null);
+// A device the human allowed to wake her other devices: the note says so,
+// or the root minted it, and the root's word needs no note.
+const mayWake = (occ: OccupantRecord | undefined) => isDesk(occ) || occ?.notes.wake === true || rootMinted(occ);
 
 // She carries her standings, acme, the calendar, the house, for a device the
 // human allowed to reach them at the exchange: the note says so. A device
 // without the note sees her own asks alone, and a model sees acme only
-// because the human said it may.
+// because the human said it may. A device the root minted reaches: the root
+// is the owner of everything she holds and chose to mint it.
 export class User extends Carrier {
   static override carries(occ: OccupantRecord | undefined): boolean {
-    return isDevice(occ) && occ?.notes.reach === true;
+    return isDevice(occ) && (occ?.notes.reach === true || rootMinted(occ));
   }
-  static override cells = { name: '', reports: [] as JsonObject[] };
+  // `ways` holds a device's way back that could not be taken when it was
+  // handed over: the knock was unreached, a tab whose pk the far harbor had
+  // not bound yet, a phone in a tunnel. Nothing delivered spends nothing,
+  // so the invitation is tried again at the next push.
+  static override cells = { name: '', reports: [] as JsonObject[], ways: {} as Record<string, Invitation> };
   static override asks = {
     hello: { description: 'say hello, and hand back an invitation so she can reach you', input: { type: 'object', properties: { invitation: { type: 'object' } } } },
     whoami: { description: 'who she thinks you are', input: { type: 'object' }, for: isDevice },
@@ -36,16 +46,30 @@ export class User extends Carrier {
   };
 
   // Anyone may say hello. A device that hands her an invitation in the args
-  // is taken as a standing under its own id, so she can push to it later.
+  // is taken as a standing under its own id, so she can push to it later;
+  // if it cannot be taken now, it is kept and tried at the next push.
   async hello(args: JsonObject, asker: Asker) {
     if (asker.id !== undefined && args.invitation && typeof args.invitation === 'object' && !Array.isArray(args.invitation)) {
-      const inv = args.invitation as Invitation;
-      const back = await this.knock(inv);
-      if (!isSilence(back) && !isWord(back)) await this.take(`to:${asker.id}`, inv);
+      await this.wayBack(asker.id, args.invitation as Invitation);
     }
     return { welcome: asker.id ?? null, name: this.cells.name };
   }
 
+  // Take a device's way back, or keep it for later when the knock did not
+  // reach. A refusal spends the heir and is final; the way is dropped.
+  async wayBack(id: string, inv: Invitation): Promise<boolean> {
+    const ways = this.cells.ways as Record<string, Invitation>;
+    const back = await this.knock(inv);
+    if (!isSilence(back) && !isWord(back)) {
+      await this.take(`to:${id}`, inv);
+      delete ways[id];
+      return true;
+    }
+    if (isWord(back) && wordOf(back) !== 'unreached') delete ways[id];
+    else ways[id] = inv;
+    return false;
+  }
+
   whoami(_args: JsonObject, asker: Asker) {
     return { id: asker.id ?? null, client: client(this.occupant(asker)) };
   }
@@ -74,7 +98,10 @@ export class User extends Carrier {
   // stops being able to ask her and keeps receiving everything she pushes.
   async push(args: JsonObject) {
     const c = typeof args.client === 'string' ? args.client : null;
-    const st = c === null || !this.cells.occupants[c] ? undefined : this.standings[`to:${c}`];
+    if (c === null || !this.cells.occupants[c]) return { error: 'no such device, or it gave no way back' };
+    const kept = (this.cells.ways as Record<string, Invitation>)[c];
+    if (!this.standings[`to:${c}`] && kept) await this.wayBack(c, kept);
+    const st = this.standings[`to:${c}`];
     if (!st) return { error: 'no such device, or it gave no way back' };
     const out = await st.ask('notify', (args.object as JsonObject) ?? {});
     return isSilence(out) ? { error: 'silence' } : isWord(out) ? { error: wordOf(out) } : { pushed: out };
@@ -88,6 +115,7 @@ export class User extends Carrier {
     if (c === null) return { error: 'client is a string' };
     this.occupants.remove(c);
     this.standings.remove(`to:${c}`);
+    delete (this.cells.ways as Record<string, Invitation>)[c];
     return { forgot: c };
   }