@quo-systems/dock 0.1.0 → 0.2.1

package/dist/mcp/oauth.d.ts

@@ -6,6 +6,7 @@ export type Client = {
     client_id: string;
     client_name: string;
     redirect_uris: string[];
+    exp: number;
 };
 export type Pending = {
     client_id: string;
@@ -17,6 +18,7 @@ export type Pending = {
 };
 export type Grant = {
     identity: string;
+    ward: string;
     client_id: string;
     exp: number;
 };
@@ -25,6 +27,7 @@ export type Store = {
     pending: Record<string, Pending>;
     codes: Record<string, Pending & {
         identity: string;
+        ward: string;
     }>;
     access: Record<string, Grant>;
     refresh: Record<string, Grant>;
@@ -62,6 +65,7 @@ export declare class OAuth {
     register(body: unknown): Promise<Client | {
         error: string;
     }>;
+    client(id: string): Client | undefined;
     authorize(q: URLSearchParams): Promise<{
         redirect: string;
     } | {
@@ -70,7 +74,7 @@ export declare class OAuth {
     pending(id: string): (Pending & {
         client: Client;
     }) | null;
-    complete(id: string, identity: string): Promise<{
+    complete(id: string, identity: string, ward?: string): Promise<{
         redirect: string;
     } | {
         error: string;
@@ -81,15 +85,18 @@ export declare class OAuth {
         error: string;
     }>;
     token(body: URLSearchParams): Promise<Record<string, unknown>>;
-    issue(identity: string, client_id: string): Promise<{
+    issue(identity: string, ward: string, client_id: string): Promise<{
         access_token: string;
         token_type: string;
         expires_in: number;
         refresh_token: string;
         scope: string;
     }>;
-    bearer(req: IncomingMessage): string | null;
-    revoke(identity: string): Promise<void>;
+    bearer(req: IncomingMessage): {
+        identity: string;
+        ward: string;
+    } | null;
+    revoke(identity: string, ward?: string): Promise<void>;
     sweep(): void;
     handle(req: IncomingMessage, res: ServerResponse, rest: string): Promise<boolean>;
     challenge(res: ServerResponse): void;

package/dist/mcp/oauth.js

@@ -60,15 +60,22 @@ export class OAuth {
         const uris = Array.isArray(b.redirect_uris) ? b.redirect_uris.filter((u) => typeof u === 'string' && /^https?:\/\//.test(u)) : [];
         if (uris.length === 0)
             return { error: 'invalid_redirect_uri' };
-        const client = { client_id: token(), client_name: typeof b.client_name === 'string' ? b.client_name.slice(0, 80) : 'client', redirect_uris: uris };
+        const client = { client_id: token(), client_name: typeof b.client_name === 'string' ? b.client_name.slice(0, 80) : 'client', redirect_uris: uris, exp: this.now() + CODE_TTL };
         this.store.clients[client.client_id] = client;
+        this.sweep();
         await this.o.persist(this.store);
-        return client;
+        const { exp: _, ...shown } = client;
+        return shown;
+    }
+    // A client still alive, by id.
+    client(id) {
+        const c = own(this.store.clients, id);
+        return c && c.exp >= this.now() ? c : undefined;
     }
     // Start a request. What comes back is where to send the browser: the web
     // route with the request id, or the client's redirect with an error.
     async authorize(q) {
-        const client = own(this.store.clients, q.get('client_id') ?? '');
+        const client = this.client(q.get('client_id') ?? '');
         const redirect = q.get('redirect_uri') ?? client?.redirect_uris[0] ?? null;
         if (!client || redirect === null || !client.redirect_uris.includes(redirect))
             return { error: 'invalid_client' };
@@ -89,17 +96,18 @@ export class OAuth {
         const p = own(this.store.pending, id);
         if (!p || p.exp < this.now())
             return null;
-        const client = own(this.store.clients, p.client_id);
+        const client = this.client(p.client_id);
         return client ? { ...p, client } : null;
     }
-    // The web route's last step: the human allowed this client as this identity.
-    async complete(id, identity) {
+    // The web route's last step: the human allowed this client as this
+    // identity, into this world.
+    async complete(id, identity, ward = 'main') {
         const p = this.pending(id);
         if (!p)
             return { error: 'expired' };
         delete this.store.pending[id];
         const code = token();
-        this.store.codes[code] = { ...p, identity, exp: this.now() + CODE_TTL };
+        this.store.codes[code] = { ...p, identity, ward, exp: this.now() + CODE_TTL };
         await this.o.persist(this.store);
         return { redirect: withQuery(p.redirect_uri, { code, state: p.state }) };
     }
@@ -124,7 +132,7 @@ export class OAuth {
                 await this.o.persist(this.store);
                 return { error: 'invalid_grant' };
             }
-            return this.issue(c.identity, c.client_id);
+            return this.issue(c.identity, c.ward ?? 'main', c.client_id);
         }
         if (grant === 'refresh_token') {
             const rt = body.get('refresh_token') ?? '';
@@ -132,40 +140,43 @@ export class OAuth {
             if (!r || r.exp < this.now())
                 return { error: 'invalid_grant' };
             delete this.store.refresh[rt]; // rotated: the old one is gone with the new one's birth
-            return this.issue(r.identity, r.client_id);
+            return this.issue(r.identity, r.ward ?? 'main', r.client_id);
         }
         return { error: 'unsupported_grant_type' };
     }
-    async issue(identity, client_id) {
+    async issue(identity, ward, client_id) {
         const access_token = token(), refresh_token = token();
-        this.store.access[access_token] = { identity, client_id, exp: this.now() + ACCESS_TTL };
-        this.store.refresh[refresh_token] = { identity, client_id, exp: this.now() + REFRESH_TTL };
+        this.store.access[access_token] = { identity, ward, client_id, exp: this.now() + ACCESS_TTL };
+        this.store.refresh[refresh_token] = { identity, ward, client_id, exp: this.now() + REFRESH_TTL };
+        const c = own(this.store.clients, client_id);
+        if (c)
+            c.exp = this.now() + REFRESH_TTL; // allowed: the client lives as long as what it was granted
         this.sweep();
         await this.o.persist(this.store);
         return { access_token, token_type: 'Bearer', expires_in: ACCESS_TTL / 1000, refresh_token, scope: 'quo' };
     }
-    // The bearer on an MCP request, to a client identity. Null is 401.
+    // The bearer on an MCP request, to a client identity in a world. Null is 401.
     bearer(req) {
         const h = req.headers.authorization ?? '';
         const t = h.startsWith('Bearer ') ? h.slice(7) : '';
         const g = own(this.store.access, t);
-        return g && g.exp >= this.now() && typeof g.identity === 'string' ? g.identity : null;
+        return g && g.exp >= this.now() && typeof g.identity === 'string' ? { identity: g.identity, ward: g.ward ?? 'main' } : null;
     }
-    // Every grant an identity holds, gone: the route's half of revocation.
-    // The other half is the user being removing the occupant.
-    async revoke(identity) {
+    // Every grant an identity holds in a world, gone: the route's half of
+    // revocation. The other half is the user being removing the occupant.
+    async revoke(identity, ward = 'main') {
         for (const k of ['access', 'refresh'])
             for (const [t, g] of Object.entries(this.store[k]))
-                if (g.identity === identity)
+                if (g.identity === identity && (g.ward ?? 'main') === ward)
                     delete this.store[k][t];
         await this.o.persist(this.store);
     }
     sweep() {
         const now = this.now();
-        for (const k of ['pending', 'codes', 'access', 'refresh'])
+        for (const k of ['clients', 'pending', 'codes', 'access', 'refresh'])
             for (const [t, g] of Object.entries(this.store[k]))
-                if (g.exp < now)
-                    delete this.store[k][t];
+                if (!(g.exp >= now))
+                    delete this.store[k][t]; // a record with no exp is from before there was one, and goes too
     }
     // The HTTP face. `rest` is the path under the route.
     async handle(req, res, rest) {

package/dist/mcp/pilot.d.ts

@@ -1,6 +1,5 @@
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
-import { type Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Serving } from '../beings/side.ts';
-export declare const PILOT_TOOLS: Tool[];
-export type Log = (line: string) => void;
-export declare function pilotSide(dir: string, ward: string, transport: Transport, log?: Log, via?: string): Promise<Serving>;
+import { type Subject } from './server.ts';
+export declare function owner(dir: string, ward: string, via?: string): Subject;
+export declare function pilotSide(dir: string, ward: string, transport: Transport, via?: string): Promise<Serving>;

package/dist/mcp/pilot.js

@@ -1,68 +1,22 @@
-// SPDX-License-Identifier: Apache-2.0
-// The owner pilot: `quo pilot`. An MCP server over stdio that reaches a
-// ward's owner asks through the daemon's root socket, and exposes four tools
-// and no more, plus the one read. Whoever runs this process is the owner, by
-// the device's own rules: the root of the ward here, or, with `via`, an
-// owner at another ward's door, on a standing the user being here holds
-// there. Every call is logged with what it made. The owner creates and
-// places; the work goes through `quo side`, under a gate.
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { ask } from '../cli/client.js';
-export const PILOT_TOOLS = [
-    {
-        name: 'census',
-        description: 'the empty ask: the ward pk and every being, with class, public and digest',
-        inputSchema: { type: 'object', properties: {} },
-    },
-    {
-        name: 'boot',
-        description: 'boot a being by class name under a key; public marks the one public being',
-        inputSchema: { type: 'object', properties: { key: { type: 'string' }, class: { type: 'string' }, public: { type: 'boolean' } }, required: ['key', 'class'] },
-    },
-    {
-        name: 'invite',
-        description: 'mint an invitation on a being of the ward, under an id she will know the occupant by',
-        inputSchema: { type: 'object', properties: { being: { type: 'string' }, id: { type: 'string' } }, required: ['being', 'id'] },
-    },
-    {
-        name: 'knock',
-        description: 'knock for a being of the ward with an invitation, and take the standing under id if answered',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                being: { description: 'a key already booted, or { boot: class, key } to boot her first' },
-                id: { type: 'string' },
-                invitation: { type: 'object' },
-                method: { type: 'string' },
-                args: { type: 'object' },
-                wanted: { type: 'object', properties: { time: { type: 'number' } } },
-            },
-            required: ['being', 'id', 'invitation'],
-        },
-    },
-    {
-        name: 'remove',
-        description: 'take a relation out of a being of the ward by id, occupant or standing; on the ward pk, an owner, by the root alone',
-        inputSchema: { type: 'object', properties: { being: { type: 'string' }, id: { type: 'string' } }, required: ['being', 'id'] },
-    },
-];
+import { mcpSide } from './server.js';
 const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
-export async function pilotSide(dir, ward, transport, log = () => { }, via) {
-    const server = new Server({ name: 'quo-pilot', version: '0.0.0' }, { capabilities: { tools: {} } });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: PILOT_TOOLS }));
-    server.setRequestHandler(CallToolRequestSchema, async (req) => {
-        const name = req.params.name;
-        const args = req.params.arguments ?? {};
-        if (!PILOT_TOOLS.some((t) => t.name === name))
-            return { content: [{ type: 'text', text: JSON.stringify({ error: 'unknown ask' }) }], structuredContent: { error: 'unknown ask' }, isError: true };
-        const out = await ask(dir, name === 'census' ? undefined : name, args, ward, via);
-        const value = 'error' in out ? { error: out.error } : out.result;
-        const failed = 'error' in out || (typeof value === 'object' && value !== null && 'error' in value);
-        log(`${via === undefined ? ward : `${ward} via ${via}`} ${name} ${JSON.stringify(args)} -> ${JSON.stringify(value)}`);
-        const structured = isRecord(value) ? { structuredContent: value } : {};
-        return { content: [{ type: 'text', text: JSON.stringify(value) }], ...structured, ...(failed ? { isError: true } : {}) };
-    });
-    await server.connect(transport);
-    return { close: () => server.close() };
+// The owner hears objects: the socket's own failure, a silence and a word
+// each come back as an error object named for what it was.
+export function owner(dir, ward, via) {
+    const one = async (method, args) => {
+        const out = await ask(dir, method, args, ward, via);
+        if ('error' in out)
+            return { error: out.error };
+        const r = out.result;
+        if (isRecord(r) && r.silence === true)
+            return { error: 'silence' };
+        if (isRecord(r) && typeof r.word === 'string')
+            return { error: r.word };
+        return r;
+    };
+    return { tools: () => one(undefined, {}), call: (name, args) => one(name, args ?? {}), ears: new Set() };
+}
+export function pilotSide(dir, ward, transport, via) {
+    return mcpSide(owner(dir, ward, via), transport);
 }

package/dist/mcp/server.d.ts

@@ -1,9 +1,11 @@
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { type Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Blueprint } from '@quo-systems/quo';
-import type { Avatar } from '../beings/avatar.ts';
-import { type Serving } from '../beings/side.ts';
+import { type Serving, type Subject } from '../beings/side.ts';
+import { type Look } from '../beings/look.ts';
 export declare const NAME = "quo";
 export declare const VERSION = "0.0.0";
-export declare function tools(bp: Blueprint): Tool[];
-export declare function mcpSide(avatar: Avatar, transport: Transport, after?: () => Promise<void>): Promise<Serving>;
+export type { Subject } from '../beings/side.ts';
+export declare const DESCRIBE: Tool;
+export declare function tools(bp: Blueprint, look?: Look): Tool[];
+export declare function mcpSide(avatar: Subject, transport: Transport, after?: () => Promise<void>): Promise<Serving>;

package/dist/mcp/server.js

@@ -1,39 +1,76 @@
 // SPDX-License-Identifier: Apache-2.0
-// The model side as an MCP server: one avatar, one transport. The mapping is
-// total and needs nothing beyond this envelope. tools/list is her describe,
-// tools/call is a named ask on her one standing, a push is a logging
-// notification, and the three words for "no object" each cross as the table
-// in quo-mcp.md says. The transport is whatever the caller connected: the
+// The model side as an MCP server: one subject, one transport. The subject
+// is whoever answers the empty ask and a named one: an avatar on her one
+// standing, or a ward's owner asks through the pilot. The mapping is total
+// and needs nothing beyond this envelope. tools/list is her describe, and
+// the empty ask itself is the first tool, so the notes of the describe are
+// readable; tools/call is a named ask, a push is a logging notification,
+// and the three words for "no object" each cross as the table in
+// quo-mcp.md says. The transport is whatever the caller connected: the
 // SDK's in-memory pair in a test, stdio for a local client, HTTP on a route.
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT } from '../beings/side.js';
+import { hintFor, sanitise } from '../beings/look.js';
+import { isSilence, isWord, digest } from '@quo-systems/quo';
 export const NAME = 'quo';
 export const VERSION = '0.0.0';
-// Her describe, spoken as tools. Name, description and input are verbatim;
-// an output schema crosses when she declared one.
-export function tools(bp) {
-    return bp.asks.map((a) => {
+// The empty ask as a tool: her describe whole, asks and notes.
+export const DESCRIBE = { name: 'describe', description: 'the empty ask: her describe, the asks and the notes', inputSchema: { type: 'object' } };
+// Her describe, spoken as tools, the empty ask first. Name, description and
+// input are verbatim; an output schema crosses when she declared one. Her
+// look, when she has one, is the hints: a title, and the annotations a host
+// reads. The `look` ask itself is presentation, and is not a tool.
+export function tools(bp, look = {}) {
+    const asks = bp.asks
+        .filter((a) => a.name !== 'look')
+        .map((a) => {
         const t = { name: a.name, inputSchema: { ...a.input, type: 'object' } };
         if (a.description !== undefined)
             t.description = a.description;
         if (a.output !== undefined)
             t.outputSchema = { ...a.output, type: 'object' };
+        const h = hintFor(bp, look, a.name);
+        if (h.title !== undefined)
+            t.title = h.title;
+        const notes = {};
+        if (h.readOnly !== undefined)
+            notes.readOnlyHint = h.readOnly;
+        if (h.destructive !== undefined)
+            notes.destructiveHint = h.destructive;
+        if (h.idempotent !== undefined)
+            notes.idempotentHint = h.idempotent;
+        if (Object.keys(notes).length)
+            t.annotations = notes;
         return t;
     });
+    return [DESCRIBE, ...asks];
 }
 // `after` runs when a call is done: a harbor that must write what the ward
 // changed hooks it, since a same-ward ask never crosses the harbor.
 export async function mcpSide(avatar, transport, after = async () => { }) {
     const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: { listChanged: true }, logging: {} } });
+    // Her look, asked once per digest of her describe.
+    let seen = null;
+    let look = {};
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         const bp = await avatar.tools();
         if ('error' in bp && !('asks' in bp))
             return { tools: [] }; // not joined: nothing to show, and nothing to call
-        return { tools: tools(bp) };
+        const d = await digest(bp);
+        if (d !== seen) {
+            seen = d;
+            if (bp.asks.some((a) => a.name === 'look')) {
+                const l = await avatar.call('look', {});
+                look = isSilence(l) || isWord(l) ? {} : sanitise(l);
+            }
+            else
+                look = {};
+        }
+        return { tools: tools(bp, look) };
     });
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
-        const w = word(await avatar.call(req.params.name, (req.params.arguments ?? {})));
+        const w = word(req.params.name === DESCRIBE.name ? await avatar.tools() : await avatar.call(req.params.name, (req.params.arguments ?? {})));
         await after();
         if (w.word === 'object') {
             const structured = w.value !== null && typeof w.value === 'object' && !Array.isArray(w.value) ? { structuredContent: w.value } : {};

package/dist/mcp/web/exchange.d.ts

@@ -1,14 +1,17 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { OAuth } from '../oauth.ts';
 export declare const SESSION_TTL: number;
-export type Admit = (identity: string, wake: boolean) => Promise<{
+export type Admit = (identity: string, wake: boolean, reach: boolean, ward: string) => Promise<{
     error?: string;
 }>;
 export type Options = {
     oauth: OAuth;
     password: () => string | undefined;
     admit: Admit;
-    user: string;
+    worlds: () => {
+        ward: string;
+        user: string;
+    }[];
     now?: () => number;
 };
 export declare const suggest: (name: string) => string;

package/dist/mcp/web/exchange.js

@@ -90,7 +90,7 @@ export class Exchange {
                 return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
             if (!this.valid(req))
                 return go(`/login?request=${encodeURIComponent(request)}`), true;
-            return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.user)), true;
+            return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.worlds())), true;
         }
         if (rest === '/allow' && req.method === 'POST') {
             const f = await readForm(req);
@@ -104,13 +104,17 @@ export class Exchange {
                 const out = await this.o.oauth.deny(request);
                 return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`), true;
             }
+            const worlds = this.o.worlds();
+            const world = worlds.find((w) => w.ward === (f.get('ward') ?? worlds[0]?.ward));
+            if (!world)
+                return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), worlds, 'That is not a world of this harbor.')), true;
             const identity = word(f.get('identity'));
-            if (identity === null || identity === this.o.user || identity === 'desk')
-                return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.user, 'An identity is one word, and not the user or the desk.')), true;
-            const admitted = await this.o.admit(identity, f.get('wake') === 'on');
+            if (identity === null || identity === world.user || identity === 'desk')
+                return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), worlds, 'An identity is one word, and not the user or the desk.')), true;
+            const admitted = await this.o.admit(identity, f.get('wake') === 'on', f.get('reach') === 'on', world.ward);
             if (admitted.error)
                 return page(500, `<h1>Not admitted</h1><p>${esc(admitted.error)}</p>`), true;
-            const out = await this.o.oauth.complete(request, identity);
+            const out = await this.o.oauth.complete(request, identity, world.ward);
             return 'redirect' in out ? go(out.redirect, { 'set-cookie': `${COOKIE}=; Path=/; Max-Age=0` }) : page(400, `<h1>Gone</h1>`), true;
         }
         return false;
@@ -125,12 +129,22 @@ ${err ? `<p class="err">${esc(err)}</p>` : ''}
 <form method="post" action="/login"><input type="hidden" name="request" value="${esc(request)}">
 <label for="p">Owner password</label><input id="p" name="password" type="password" autocomplete="current-password" autofocus required>
 <button type="submit">Log in</button></form>`;
-const allowForm = (request, client, redirect, identity, user, err = '') => `<h1>Allow ${esc(client)}?</h1>
-<div class="who"><p><strong>${esc(client)}</strong> asks to be an occupant of <strong>${esc(user)}</strong>.</p>
+// The world is a choice when the harbor has more than one; the user named
+// is the first world's, and the page says which world each identity lands in.
+const allowForm = (request, client, redirect, identity, worlds, err = '') => {
+    const user = worlds[0]?.user ?? '';
+    const pick = worlds.length > 1
+        ? `<label for="wd">World</label><select id="wd" name="ward">${worlds.map((w) => `<option value="${esc(w.ward)}">${esc(w.ward)}, ${esc(w.user)}'s</option>`).join('')}</select>`
+        : `<input type="hidden" name="ward" value="${esc(worlds[0]?.ward ?? 'main')}">`;
+    return `<h1>Allow ${esc(client)}?</h1>
+<div class="who"><p><strong>${esc(client)}</strong> asks to be an occupant of <strong>${esc(user)}</strong>${worlds.length > 1 ? ', or of another world below' : ''}.</p>
 <p>It will see exactly what ${esc(user)} shows the identity below, and nothing else. You can remove it any time.</p>
 <p>It returns to <code>${esc(redirect)}</code>.</p></div>
 ${err ? `<p class="err">${esc(err)}</p>` : ''}
 <form method="post" action="/allow"><input type="hidden" name="request" value="${esc(request)}">
+${pick}
 <label for="i">Identity</label><input id="i" name="identity" value="${esc(identity)}" pattern="[\\w.-]{1,40}" required>
+<label for="r"><input id="r" name="reach" type="checkbox" style="width:auto"> May reach what ${esc(user)} holds: her standings, acme and the rest, as asks of hers</label>
 <label for="w"><input id="w" name="wake" type="checkbox" style="width:auto"> May wake your other devices: hand an agent an event through ${esc(user)}</label>
 <button type="submit" name="decision" value="allow">Allow</button><button type="submit" name="decision" value="deny">Deny</button></form>`;
+};

package/harbor/edge/exercise.ts

@@ -70,7 +70,8 @@ function probe(base: string, state: State, env: Env): () => Promise<World> {
           learn(i, w);
         }
         wardOf.set(key, name);
-        assert.deepEqual(await w.ask('boot', { key, class: Class.name, public: isPublic }), { booted: key });
+        assert.deepEqual(await w.ask('boot', { key, class: Class.name }), { booted: key });
+        if (isPublic) assert.deepEqual(await w.ask('public', { key }), { public: key });
         if (Object.keys(cells).length) Object.assign(at(name).p.beings[key]!, cells);
         return {
           pk: w.pk,

package/harbor/quo-harbor.md

@@ -88,6 +88,38 @@ 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
@@ -235,6 +267,11 @@ request      POST <url>/<pk>, the sealed ask as the body, the sealed reply as th
              <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

package/human/guest.ts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+// A guest at a world's door: the world's public being, whatever class she
+// is, as a subject the screen can render. Her describe for a stranger is the
+// guest page; a form on it is a knock on the public invitation; and an
+// answer that is an invitation is the way in, which the tab takes by
+// joining. Nothing here knows the desk: the desk's `device` is one ask
+// that answers an invitation, and any being may write another.
+import { isSilence, isWord, wordOf } from '@quo-systems/quo';
+import type { Answer, Blueprint, Invitation, JsonObject, Wanted } from '@quo-systems/quo';
+import type { Avatar } from '../beings/avatar.ts';
+import type { Subject } from '../beings/side.ts';
+
+export function guest(avatar: Avatar, ward: string): Subject {
+  const at: Invitation = { ward };
+  return {
+    tools: async () => {
+      const bp = await avatar.knock(at);
+      if (isSilence(bp)) return { error: 'silence' };
+      if (isWord(bp)) return { error: wordOf(bp) };
+      if (bp === null || typeof bp !== 'object' || Array.isArray(bp) || !Array.isArray((bp as Blueprint).asks)) return { error: 'nobody is home' };
+      return bp as Blueprint;
+    },
+    call: (name: string, args: JsonObject = {}, wanted?: Wanted): Promise<Answer> => avatar.knock(at, name, args, wanted),
+    ears: new Set(),
+  };
+}