@quo-systems/dock 0.2.0 → 0.2.2

package/cli/quo.ts

@@ -8,9 +8,10 @@
 //   quo serve  [--dir D] [--http PORT] [--dial URL]  the daemon: harbor from disk, the two sockets, the HTTP door on loopback, a socket held to URL
 //   quo census [--dir D] [--ward W] [--via S]        the empty ask: pk and every being
 //   quo boot   [--dir D] [--ward W] [--via S] <json> { key, class, public? }
-//   quo invite [--dir D] [--ward W] [--via S] <json> { being, id }
+//   quo invite [--dir D] [--ward W] [--via S] <json> { being, id }; with routes.json naming web., the answer carries the link
 //   quo knock  [--dir D] [--ward W] [--via S] <json> { being | { boot, key }, id, invitation, method?, args?, wanted? }
 //   quo remove [--dir D] [--ward W] [--via S] <json> { being, id }: a relation out of a being; on the ward pk, an owner
+//   quo unboot [--dir D] [--ward W] [--via S] <json> { being }: a being out of the ward, with every relation she holds
 //   quo side   [--dir D] [--ward W] --as NAME  an avatar over stdio for a local MCP client; NAME is the client identity
 //   quo run    [--dir D] [--ward W] --as NAME --url URL --model NAME [--turns N]  a human at a terminal talking to a model through an avatar: a line in, the model's final text out
 //   quo pilot  [--dir D] [--ward W] [--via S]        the owner pilot over stdio: census, boot, invite, knock, remove
@@ -29,12 +30,13 @@ import { homedir, userInfo } from 'node:os';
 import { join } from 'node:path';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { DiskHarbor } from '../harbor/disk.ts';
-import { serve } from './daemon.ts';
+import { serve, readRoutes } from './daemon.ts';
 import { ask, side, reach, type Run } from './client.ts';
+import { link, isInvitation } from '../beings/link.ts';
 import { pilotSide } from '../mcp/pilot.ts';
 import { estate } from './estate.ts';
 
-const OWNER_ASKS = new Set(['boot', 'public', 'invite', 'knock', 'remove']);
+const OWNER_ASKS = new Set(['boot', 'public', 'invite', 'knock', 'remove', 'unboot']);
 
 function parse(argv: string[]) {
   const flags: Record<string, string> = {};
@@ -115,13 +117,19 @@ async function main(argv: string[]): Promise<number> {
   if (cmd === 'census' || (cmd !== undefined && OWNER_ASKS.has(cmd))) {
     const args = json ? (JSON.parse(json) as Record<string, unknown>) : {};
     const out = await ask(dir, cmd === 'census' ? undefined : cmd, args, ward, via);
-    print('error' in out ? { error: out.error } : out.result);
+    // an invitation minted here is handed on as a link when the harbor's
+    // routes name a web. origin: the world's page with the invitation in
+    // the fragment, one string to send to the person it is for
+    const minted = cmd === 'invite' && !via && 'result' in out && isInvitation(out.result) ? out.result : null;
+    const routes = minted ? await readRoutes(dir) : null;
+    if (minted && routes) print({ ...minted, link: link(`${routes.web}/${encodeURIComponent(ward)}`, minted) });
+    else print('error' in out ? { error: out.error } : out.result);
     // an error object the ward answered is an ordinary answer, and still a
     // non-zero exit, so a script can tell a boot that happened from one that did not.
     const failed = 'error' in out || (typeof out.result === 'object' && out.result !== null && 'error' in out.result);
     return failed ? 1 : 0;
   }
-  console.error('usage: quo init|serve|census|boot|public|invite|knock|remove|side|run|pilot|reach|estate [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
+  console.error('usage: quo init|serve|census|boot|public|invite|knock|remove|unboot|side|run|pilot|reach|estate [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
   return 2;
 }
 

package/dist/beings/avatar.js

@@ -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';
 // Her one standing, and the id under which the user being pushes to her.
 // Two ids for one far being, because standings and occupants share one
@@ -47,8 +49,11 @@ export class Avatar extends Being {
             return inv ?? { error: 'no invitation' };
         return this.join(inv);
     }
-    // Knock with an invitation, hand the user being one back so she can push,
-    // and take her as `user`. The only moment a standing is born here.
+    // Knock with an invitation, hand the far being one back so she can push,
+    // and take her as `user`. The only moment a standing is born here. A being
+    // who answers the hello with an error object is a being who answered: she
+    // is taken all the same, and the way back she did not take is dropped, so
+    // any world's public being may admit a guest, hello or not.
     async join(invitation) {
         if (this.standings[USER])
             return this.tools();
@@ -60,6 +65,8 @@ export class Avatar extends Being {
             this.occupants.remove(PUSHER);
             return { error: isSilence(out) ? 'silence' : wordOf(out) };
         }
+        if (out !== null && typeof out === 'object' && !Array.isArray(out) && 'error' in out)
+            this.occupants.remove(PUSHER);
         await this.take(USER, invitation);
         return this.tools();
     }

package/dist/beings/carry.d.ts

@@ -0,0 +1,10 @@
+import { Being } from '@quo-systems/quo';
+import type { Asker, Blueprint, JsonObject, OccupantRecord, Reply } from '@quo-systems/quo';
+export declare class Carrier extends Being {
+    static carries(_occupant: OccupantRecord | undefined, _asker: Asker): boolean;
+    static hidden(id: string): boolean;
+    private get carried();
+    private get looks();
+    blueprint(asker: Asker): Promise<Blueprint>;
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
+}

package/dist/beings/carry.js

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: Apache-2.0
+// A carrier: a being who shows the asks of the standings she holds as asks
+// of her own, and forwards. Whoever she carries for sees, in one describe,
+// what she can be asked and what every being she holds can be asked, each
+// under that standing's name; asking one is an ask on that standing, in her
+// name, so the far being sees her and never who is behind her. A user being
+// carries acme for the human's devices; a house being could carry its
+// rooms; nothing here knows what she is.
+//
+// A carried ask is `<id>-<name>`, and the mapping back is kept in her cells
+// and never parsed from the name, so an id with a dash in it is no trouble.
+// The notes say which asks are whose, `standings: { id: { asks, look? } }`,
+// so a screen draws one section per standing and a model side keeps the
+// flat list it needs. Her own asks come first and are never shadowed: a
+// carried name that collides with one of hers is dropped.
+//
+// She asks a standing's describe again when its digest moved, and its
+// `look` once per digest, and keeps both in her cells. So a describe of
+// hers may cost one ask per stale standing, which is the price of a page
+// that is never more than one ask behind.
+import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
+import { sanitise } from './look.js';
+export class Carrier extends Being {
+    // Who sees what she carries. Nobody, until a subclass says who.
+    static carries(_occupant, _asker) {
+        return false;
+    }
+    // Standings she never carries: a way back to a device is one, by the
+    // dock's own convention, and a subclass may name more.
+    static hidden(id) {
+        return id.startsWith('to:');
+    }
+    get carried() {
+        return (this.cells.carried ??= {});
+    }
+    get looks() {
+        return (this.cells.looks ??= {});
+    }
+    // Her describe with her standings carried into it, for an asker who may
+    // see them. Every other asker gets her describe alone.
+    async blueprint(asker) {
+        const C = this.constructor;
+        const bp = this.describe(asker);
+        if (!C.carries(this.occupant(asker), asker))
+            return bp;
+        const own = new Set(bp.asks.map((a) => a.name));
+        const carried = {};
+        const groups = {};
+        for (const [id, rec] of Object.entries(this.cells.standings)) {
+            if (C.hidden(id))
+                continue;
+            const st = this.standings[id];
+            if (!st)
+                continue;
+            if (!rec.blueprint || rec.seen !== rec.digest)
+                await st.ask(); // her ward writes the record
+            if (!rec.blueprint)
+                continue;
+            const names = [];
+            for (const a of rec.blueprint.asks) {
+                if (a.name === 'look')
+                    continue;
+                const name = `${id}-${a.name}`;
+                if (own.has(name))
+                    continue;
+                carried[name] = { id, ask: a.name };
+                names.push(name);
+                bp.asks.push({ ...a, name });
+            }
+            const group = { asks: names };
+            if (rec.blueprint.asks.some((a) => a.name === 'look')) {
+                const kept = this.looks[id];
+                if (!kept || kept.digest !== rec.digest) {
+                    const l = await st.ask('look');
+                    this.looks[id] = { digest: rec.digest, look: isSilence(l) || isWord(l) ? {} : sanitise(l) };
+                }
+                group.look = this.looks[id].look;
+            }
+            groups[id] = group;
+        }
+        for (const id of Object.keys(this.looks))
+            if (!(id in groups))
+                delete this.looks[id];
+        this.cells.carried = carried;
+        const notes = bp.notes !== null && typeof bp.notes === 'object' && !Array.isArray(bp.notes) ? bp.notes : {};
+        return { asks: bp.asks, notes: { ...notes, standings: groups } };
+    }
+    async answer(asker, method, args = {}) {
+        if (method === undefined)
+            return this.blueprint(asker);
+        const C = this.constructor;
+        const to = Object.hasOwn(this.carried, method) ? this.carried[method] : undefined;
+        if (to && C.carries(this.occupant(asker), asker)) {
+            const st = this.standings[to.id];
+            if (!st)
+                return { error: 'unknown ask' };
+            const out = await st.ask(to.ask, args);
+            if (isSilence(out))
+                return out;
+            if (isWord(out))
+                return { error: wordOf(out) };
+            return out;
+        }
+        return super.answer(asker, method, args);
+    }
+}

package/dist/beings/desk.d.ts

@@ -8,6 +8,7 @@ export type Verified = {
     user: string;
     client: string;
     wake?: boolean;
+    reach?: boolean;
 };
 export type Verifier = (proof: Proof) => Promise<Verified | null> | Verified | null;
 export declare class Desk extends Being {

package/dist/beings/desk.js

@@ -33,7 +33,7 @@ export class Desk extends Being {
         const user = this.standings[`user:${who.user}`];
         if (!user)
             return { error: 'no such user' };
-        const inv = await user.ask('device', who.wake === true ? { client: who.client, wake: true } : { client: who.client });
+        const inv = await user.ask('device', { client: who.client, ...(who.wake === true ? { wake: true } : {}), ...(who.reach === true ? { reach: true } : {}) });
         if (isSilence(inv))
             return { error: 'silence' };
         if (isWord(inv))

package/dist/beings/index.d.ts

@@ -1,3 +1,5 @@
 export { User, DESK } from './user.ts';
 export { Desk, type Proof, type Verified, type Verifier } from './desk.ts';
 export { Avatar, USER, PUSHER } from './avatar.ts';
+export { Carrier } from './carry.ts';
+export { sanitise, hint, hintFor, groups, type Look, type Hint } from './look.ts';

package/dist/beings/index.js

@@ -1,5 +1,7 @@
 // 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.js';
 export { Desk } from './desk.js';
 export { Avatar, USER, PUSHER } from './avatar.js';
+export { Carrier } from './carry.js';
+export { sanitise, hint, hintFor, groups } from './look.js';

package/dist/beings/link.d.ts

@@ -0,0 +1,7 @@
+import type { Invitation } from '@quo-systems/quo';
+export declare const KEY = "quo";
+export declare function format(inv: Invitation): string;
+export declare function parse(hash: string): Invitation | null;
+export declare function strip(hash: string): string;
+export declare function link(page: string, inv: Invitation): string;
+export declare function isInvitation(v: unknown): v is Invitation;

package/dist/beings/link.js

@@ -0,0 +1,42 @@
+export const KEY = 'quo';
+const HEX = (n) => `[0-9a-f]{${n}}`;
+const FULL = new RegExp(`^(${HEX(128)})\\.(${HEX(64)})\\.(${HEX(64)})$`);
+const PUBLIC = new RegExp(`^${HEX(128)}$`);
+export function format(inv) {
+    return inv.heir && inv.secret ? `${inv.ward}.${inv.heir}.${inv.secret}` : inv.ward;
+}
+// The invitation in a fragment, or null. Anything else in the fragment is
+// the page's own and is left alone.
+export function parse(hash) {
+    const m = /(?:^#|&)quo=([^&]+)/.exec(hash.startsWith('#') ? hash : `#${hash}`);
+    if (!m)
+        return null;
+    const v = decodeURIComponent(m[1]);
+    const full = FULL.exec(v);
+    if (full)
+        return { ward: full[1], heir: full[2], secret: full[3] };
+    return PUBLIC.test(v) ? { ward: v } : null;
+}
+// The fragment without the invitation, so the page keeps whatever else it
+// put there and the capability is gone from the address bar.
+export function strip(hash) {
+    const rest = (hash.startsWith('#') ? hash.slice(1) : hash)
+        .split('&')
+        .filter((p) => !p.startsWith(`${KEY}=`))
+        .join('&');
+    return rest ? `#${rest}` : '';
+}
+export function link(page, inv) {
+    return `${page}#${KEY}=${format(inv)}`;
+}
+// Whether an answer is an invitation: a ward pk, and a heir with its secret
+// or neither. What a guest's form answers with to be let in.
+export function isInvitation(v) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const o = v;
+    if (typeof o.ward !== 'string' || !PUBLIC.test(o.ward))
+        return false;
+    const heir = typeof o.heir === 'string', secret = typeof o.secret === 'string';
+    return (heir && secret) || (!heir && !secret && !('heir' in o) && !('secret' in o));
+}

package/dist/beings/look.d.ts

@@ -0,0 +1,27 @@
+import type { Blueprint, Json } from '@quo-systems/quo';
+export type Hint = {
+    title?: string;
+    readOnly?: boolean;
+    destructive?: boolean;
+    idempotent?: boolean;
+    icon?: string;
+};
+export type Look = {
+    name?: string;
+    logo?: string;
+    accent?: string;
+    background?: string;
+    foreground?: string;
+    font?: string;
+    radius?: number;
+    order?: string[];
+    asks?: Record<string, Hint>;
+};
+export declare function sanitise(v: Json | undefined): Look;
+export declare const hint: (l: Look | undefined, name: string) => Hint;
+export type Group = {
+    asks?: string[];
+    look?: Json;
+};
+export declare function groups(bp: Blueprint | null): Record<string, Group>;
+export declare function hintFor(bp: Blueprint | null, mine: Look, name: string): Hint;

package/dist/beings/look.js

@@ -0,0 +1,71 @@
+const COLOUR = /^#[0-9a-fA-F]{3,8}$/;
+const FONT = /^[\w\s,'"-]{1,80}$/;
+const LOGO = /^data:image\/(svg\+xml|png|jpeg|webp);base64,[A-Za-z0-9+/=]{1,40000}$/;
+const NAME = /^[^<>&]{1,60}$/;
+const ICON = /^[^<>&"']{1,8}$/;
+const str = (v, re) => (typeof v === 'string' && re.test(v) ? v : undefined);
+// The look as a side may use it: every token held to its shape, everything
+// else gone. A value that is not an object is no look at all.
+export function sanitise(v) {
+    if (v === null || v === undefined || typeof v !== 'object' || Array.isArray(v))
+        return {};
+    const l = {};
+    const name = str(v.name, NAME);
+    if (name !== undefined)
+        l.name = name;
+    const logo = str(v.logo, LOGO);
+    if (logo !== undefined)
+        l.logo = logo;
+    for (const k of ['accent', 'background', 'foreground']) {
+        const c = str(v[k], COLOUR);
+        if (c !== undefined)
+            l[k] = c;
+    }
+    const font = str(v.font, FONT);
+    if (font !== undefined)
+        l.font = font;
+    if (typeof v.radius === 'number' && Number.isFinite(v.radius) && v.radius >= 0 && v.radius <= 40)
+        l.radius = Math.round(v.radius);
+    if (Array.isArray(v.order))
+        l.order = v.order.filter((x) => typeof x === 'string');
+    if (v.asks !== null && typeof v.asks === 'object' && !Array.isArray(v.asks)) {
+        const asks = {};
+        for (const [ask, h] of Object.entries(v.asks)) {
+            if (h === null || typeof h !== 'object' || Array.isArray(h))
+                continue;
+            const hint = {};
+            const title = str(h.title, NAME);
+            if (title !== undefined)
+                hint.title = title;
+            const icon = str(h.icon, ICON);
+            if (icon !== undefined)
+                hint.icon = icon;
+            for (const k of ['readOnly', 'destructive', 'idempotent'])
+                if (typeof h[k] === 'boolean')
+                    hint[k] = h[k];
+            if (Object.keys(hint).length)
+                asks[ask] = hint;
+        }
+        if (Object.keys(asks).length)
+            l.asks = asks;
+    }
+    return l;
+}
+// The one hint a side reads first: whether this ask is in the look at all.
+export const hint = (l, name) => l?.asks?.[name] ?? {};
+export function groups(bp) {
+    const n = bp?.notes;
+    const g = n !== null && n !== undefined && typeof n === 'object' && !Array.isArray(n) ? n.standings : undefined;
+    return g !== null && g !== undefined && typeof g === 'object' && !Array.isArray(g) ? g : {};
+}
+// The hint for one ask, hers or a standing's: a carried ask is looked up
+// under its bare name in that standing's look.
+export function hintFor(bp, mine, name) {
+    for (const [id, g] of Object.entries(groups(bp))) {
+        if (!g.asks?.includes(name))
+            continue;
+        const prefix = `${id}-`;
+        return hint(sanitise(g.look), name.startsWith(prefix) ? name.slice(prefix.length) : name);
+    }
+    return hint(mine, name);
+}

package/dist/beings/side.d.ts

@@ -1,9 +1,16 @@
-import type { Answer, Json, JsonObject, WordName } from '@quo-systems/quo';
+import type { Answer, Blueprint, Json, JsonObject, Wanted, WordName } from '@quo-systems/quo';
 import type { Avatar } from './avatar.ts';
 export type Serving = {
     close(): Promise<void>;
 };
 export type Side = (avatar: Avatar) => Promise<Serving>;
+export type Subject = {
+    tools(): Promise<Blueprint | {
+        error: string;
+    }>;
+    call(name: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+    ears: Set<(object: JsonObject) => void>;
+};
 export type Word = {
     word: 'object';
     value: Json;

package/dist/beings/user.d.ts

@@ -1,13 +1,15 @@
-import { Being } from '@quo-systems/quo';
-import type { Asker, JsonObject, OccupantRecord } from '@quo-systems/quo';
+import type { Asker, Invitation, JsonObject, OccupantRecord } from '@quo-systems/quo';
+import { Carrier } from './carry.ts';
 export declare const DESK = "desk";
 declare const isDesk: (occ: OccupantRecord | undefined) => boolean;
 declare const isDevice: (occ: OccupantRecord | undefined) => boolean;
 declare const mayWake: (occ: OccupantRecord | undefined) => boolean;
-export declare class User extends Being {
+export declare class User extends Carrier {
+    static carries(occ: OccupantRecord | undefined): boolean;
     static cells: {
         name: string;
         reports: JsonObject[];
+        ways: Record<string, Invitation>;
     };
     static asks: {
         hello: {
@@ -39,6 +41,9 @@ export declare class User extends Being {
                     wake: {
                         type: string;
                     };
+                    reach: {
+                        type: string;
+                    };
                 };
                 required: string[];
             };
@@ -67,6 +72,19 @@ export declare class User extends Being {
             };
             for: (occ: OccupantRecord | undefined) => boolean;
         };
+        forget: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    client: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof isDesk;
+        };
         report: {
             description: string;
             input: {
@@ -86,6 +104,7 @@ export declare class User extends Being {
         welcome: string | null;
         name: import("@quo-systems/quo").Json;
     }>;
+    wayBack(id: string, inv: Invitation): Promise<boolean>;
     whoami(_args: JsonObject, asker: Asker): {
         id: string | null;
         client: string | null;
@@ -98,6 +117,13 @@ export declare class User extends Being {
         error?: undefined;
         pushed: import("@quo-systems/quo").Json;
     }>;
+    forget(args: JsonObject): {
+        error: string;
+        forgot?: undefined;
+    } | {
+        error?: undefined;
+        forgot: string;
+    };
     chores(): {
         chores: string[];
     };

package/dist/beings/user.js

@@ -5,40 +5,74 @@
 // special only by the id the root chose for them: `desk`, the front desk,
 // who may ask her to invite a device; and each device, whose id is the
 // client identity the desk established.
-import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
+import { isSilence, isWord, wordOf } from '@quo-systems/quo';
+import { Carrier } from './carry.js';
 export const DESK = 'desk';
 const isDesk = (occ) => occ?.id === DESK;
 const isDevice = (occ) => occ !== undefined && occ.id !== DESK;
-const client = (occ) => (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) => isDesk(occ) || occ?.notes.wake === true;
-export class User extends Being {
-    static cells = { name: '', reports: [] };
+// 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) => isDevice(occ) && occ?.notes.client === undefined;
+const client = (occ) => (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) => 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. 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 carries(occ) {
+        return isDevice(occ) && (occ?.notes.reach === true || rootMinted(occ));
+    }
+    // `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 cells = { name: '', reports: [], ways: {} };
     static 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 },
-        device: { description: 'mint an invitation for a device', input: { type: 'object', properties: { client: { type: 'string' }, wake: { type: 'boolean' } }, required: ['client'] }, for: isDesk },
+        device: { description: 'mint an invitation for a device', input: { type: 'object', properties: { client: { type: 'string' }, wake: { type: 'boolean' }, reach: { type: 'boolean' } }, required: ['client'] }, for: isDesk },
         push: { description: 'push an object to a device: wake it with an event', input: { type: 'object', properties: { client: { type: 'string' }, object: { type: 'object' } }, required: ['client', 'object'] }, for: mayWake },
         chores: { description: 'what the agent may run', input: { type: 'object' }, for: (occ) => client(occ) === 'agent' },
+        forget: { description: 'revoke a device: drop its way in and her way back to it, in one act', input: { type: 'object', properties: { client: { type: 'string' } }, required: ['client'] }, for: isDesk },
         report: { description: 'what a run of yours found', input: { type: 'object', properties: { event: { type: 'object' }, result: {} }, required: ['event', 'result'] }, for: isDevice },
     };
     // 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, asker) {
         if (asker.id !== undefined && args.invitation && typeof args.invitation === 'object' && !Array.isArray(args.invitation)) {
-            const inv = args.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);
         }
         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, inv) {
+        const ways = this.cells.ways;
+        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, asker) {
         return { id: asker.id ?? null, client: client(this.occupant(asker)) };
     }
     // The front desk asks; she mints. The client identity goes into the
     // occupant's notes, and that is what every gate reads. `wake` is the
-    // human's word at the exchange that this device may wake her others.
+    // human's word at the exchange that this device may wake her others, and
+    // `reach` that it may see and ask what she holds: her standings, carried.
     async device(args) {
         const c = typeof args.client === 'string' ? args.client : null;
         if (c === null)
@@ -51,17 +85,40 @@ export class User extends Being {
             rec.notes.client = c;
             if (args.wake === true)
                 rec.notes.wake = true;
+            if (args.reach === true)
+                rec.notes.reach = true;
         }
         return inv;
     }
+    // Her way out and the device's way in are two relations, and Quo keeps
+    // them apart. She joins them herself, here, as her own rule: she does
+    // not reach a device she no longer admits. Without it a revoked device
+    // stops being able to ask her and keeps receiving everything she pushes.
     async push(args) {
         const c = typeof args.client === 'string' ? args.client : null;
-        const st = c === null ? 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[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 ?? {});
         return isSilence(out) ? { error: 'silence' } : isWord(out) ? { error: wordOf(out) } : { pushed: out };
     }
+    // Revocation is one act at her, because only she knows both ids. A side
+    // that had to remove two relations by hand could leave half of one
+    // standing, and every side would have to remember which half.
+    forget(args) {
+        const c = typeof args.client === 'string' ? args.client : null;
+        if (c === null)
+            return { error: 'client is a string' };
+        this.occupants.remove(c);
+        this.standings.remove(`to:${c}`);
+        delete this.cells.ways[c];
+        return { forgot: c };
+    }
     chores() {
         return { chores: ['census', 'report'] };
     }