@nervur-org/dock 0.3.0

package/beings/setup.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+// The root's setup of a fresh ward, as every terrain does it: the front desk
+// booted public, one user being, the desk holding a standing to her under
+// `user:<name>`, placed by the root's knock, and she holding her own ward's
+// door as an owner under `home`. She names the desk `desk`,
+// and that id is the only thing that makes it the desk. A disk harbor does
+// this at `quo init`, the edge at its root route's init; the memory
+// harbor's test world does the same by hand.
+import type { Invitation } from '@nervur-org/nervur';
+import type { Hosted } from '@nervur-org/nervur/harbor';
+import { DESK, HOME } from './user.ts';
+
+// The root boots and steps back: it invites an owner on the ward's own pk
+// and the user being knocks for it, so from then on placing a being,
+// minting a way in or removing one is an ask on her, shown by her gate to a
+// device that may mint, and the box is not logged into for it. The same
+// standing a user being of another ward takes to own this one; here it is
+// her own.
+export async function setupHome(hosted: Hosted, user: string): Promise<void> {
+  const inv = (await hosted.ask('invite', { being: hosted.pk, id: HOME })) as Invitation | { error?: string };
+  if ('error' in inv) throw new Error(`home: ${inv.error}`);
+  const placed = (await hosted.ask('knock', { being: user, id: HOME, invitation: inv })) as { taken?: string; error?: string };
+  if (placed.taken !== HOME) throw new Error(`home: ${placed.error ?? 'she could not take her own door'}`);
+}
+
+// The ward's home being is a `User` unless the device says which class: an
+// organisation's ward has an org's home being, of the estate's own class,
+// and everything else of setup, the desk and the door, is placed on her the
+// same way.
+export async function setup(hosted: Hosted, user: string, cls = 'User'): Promise<void> {
+  if (!/^[\w.-]+$/.test(user) || user === 'desk') throw new Error(`a user is a word, and not desk: ${user}`);
+  const boot = async (args: Record<string, unknown>) => {
+    const out = (await hosted.ask('boot', args)) as { booted?: string; error?: string };
+    if (out.error) throw new Error(`init: ${out.error}`);
+  };
+  await boot({ key: 'desk', class: 'Desk' });
+  const pub = (await hosted.ask('public', { key: 'desk' })) as { error?: string };
+  if (pub.error) throw new Error(`init: ${pub.error}`);
+  await boot({ key: user, class: cls });
+  const inv = (await hosted.ask('invite', { being: user, id: DESK })) as Invitation;
+  // the desk's first hello names her, since a being does not know her own key
+  const placed = (await hosted.ask('knock', { being: 'desk', id: `user:${user}`, invitation: inv, method: 'hello', args: { name: user } })) as { taken?: string };
+  if (placed.taken !== `user:${user}`) throw new Error('init: the desk could not reach the user being');
+  await setupHome(hosted, user);
+}

package/beings/side.ts

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+// The side: the one interface an avatar speaks through to someone outside
+// Quo. A side takes the avatar object, in-process, and renders three things
+// its own way: her describe as what that someone reads, a call as an ask on
+// her one standing, and a push as a notification. Sides in this repository:
+// a screen, an MCP server, a runner, an event-driven agent. None knows
+// another exists, and none of this file names a platform.
+import { isSilence, isUnreached, isWord, wordOf } from '@nervur-org/nervur';
+import type { Answer, Blueprint, Json, JsonObject, Wanted, WordName } from '@nervur-org/nervur';
+import type { Avatar } from './avatar.ts';
+
+// A side, running: it holds the avatar until closed.
+export type Serving = { close(): Promise<void> };
+export type Side = (avatar: Avatar) => Promise<Serving>;
+
+// What a side speaks for: the empty ask and a named one, and the ears a
+// push reaches. An avatar on her one standing is one; the owner's asks on a
+// ward are another; a guest at a world's public being is a third.
+export type Subject = {
+  tools(): Promise<Blueprint | { error: string }>;
+  call(name: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+  ears: Set<(object: JsonObject) => void>;
+};
+
+// The three words for "no object", and the object itself, as every side must
+// tell them apart before rendering. An error object is an ordinary answer
+// that the side may mark; silence and unreached are not objects at all.
+export type Word =
+  | { word: 'object'; value: Json }
+  | { word: 'error'; value: JsonObject }
+  | { word: 'silence' }
+  | { word: 'unreached' }
+  | { word: 'quo'; name: WordName }; // the ward's word, named: why no object came
+
+export function word(answer: Answer): Word {
+  if (isSilence(answer)) return { word: 'silence' };
+  if (isUnreached(answer)) return { word: 'unreached' };
+  if (isWord(answer)) return { word: 'quo', name: wordOf(answer) };
+  if (answer !== null && typeof answer === 'object' && !Array.isArray(answer) && 'error' in answer) return { word: 'error', value: answer };
+  return { word: 'object', value: answer };
+}
+
+// What a side says about the two words that carry nothing, so that whoever
+// reads them can decide: silence promises nothing, unreached promises that
+// nothing was delivered.
+export const SILENCE_TEXT = 'silence: the work may have happened, and no answer came back';
+export const UNREACHED_TEXT = 'unreached: nothing was delivered; asking again is safe';
+// And the ward's other words, each with what a side says of it.
+export const WORD_TEXT: Record<WordName, string> = {
+  unreached: UNREACHED_TEXT,
+  late: 'late: the wait ran out; the work may have happened',
+  invitation: 'invitation: that is not an invitation',
+  dropped: 'dropped: the standing is gone',
+  removed: 'removed: the far being removed you',
+  absent: 'absent: the far being did not come back this run',
+  unannounced: 'unannounced: the knock announced no key of its own',
+  repeated: 'repeated: that number was already honoured',
+  threw: 'threw: the far being threw',
+};
+export const wordText = (name: WordName): string => WORD_TEXT[name];

package/beings/user.ts

@@ -0,0 +1,459 @@
+// SPDX-License-Identifier: Apache-2.0
+// The user being. One per human, running wherever the human's world runs.
+// She holds the human's standings, and everyone who acts for the human is
+// her occupant, seeing what her gate shows. Two of her occupants are
+// 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. A device she let mint brings the
+// next one in, so a human adds a device from a device already in and only
+// the first one has to come from the root, on the box.
+import { isInvitation, isSilence, isWord, wordOf } from '@nervur-org/nervur';
+import type { Asker, Blueprint, Invitation, JsonObject, OccupantRecord, Stance } from '@nervur-org/nervur';
+import { Carrier } from './carry.ts';
+import { PUSH, banner, isToken, join, sealBanner } from '../dock/index.ts';
+
+export const DESK = 'desk';
+// The prefix her doorbell standings are filed under, one per device: the
+// way she rings that device, and never a way anything else may ask on.
+export const BELL = 'bell';
+// Her standing at her own ward's door, as an owner: the root placed it at
+// setup, and through it she boots, invites and removes in her own world.
+export const HOME = 'home';
+const isDesk = (occ: OccupantRecord | undefined) => occ?.id === DESK;
+const isDevice = (occ: OccupantRecord | undefined) => occ !== undefined && occ.id !== DESK;
+// 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);
+
+// The three words that travel with a minting, each a note on the occupant
+// minted: `wake` may ring her other devices, `reach` may see and ask what
+// she holds, `mint` may bring the next device in. What a device holds is
+// also the most it may write on a device of its own, so a chain of devices
+// never gains a power along the way.
+//
+// The desk speaks the human's word at the exchange and holds all three. A
+// device the root minted reaches and may wake without a note, since the
+// root owns everything she holds and chose to mint it. `mint` is never
+// implied, not even there: it admits somebody else, which is not the root's
+// own reaching, and it is said out loud or not at all. The root says it by
+// minting with `{ notes: { mint: true } }`, which is the ward's owner
+// invite, so a harbor with no desk can still let a device beget devices.
+const MINTINGS = ['wake', 'reach', 'mint', 'revoke'] as const;
+// How many unreached pushes she keeps for one device. A device gone for a
+// month is a device that will be told what is recent, not everything.
+const OUTBOX = 32;
+type Minting = (typeof MINTINGS)[number];
+// Whether a ring left. A doorbell and the bell both say `rang`, and every
+// other answer, a word, silence or an error object, is a device unreached.
+const rang = (out: unknown): boolean => !isSilence(out) && !isWord(out) && out !== null && typeof out === 'object' && !Array.isArray(out) && (out as JsonObject).rang !== undefined && (out as JsonObject).rang !== false;
+const held = (occ: OccupantRecord | undefined): Record<Minting, boolean> =>
+  isDesk(occ)
+    ? { wake: true, reach: true, mint: true, revoke: true }
+    : { wake: occ?.notes.wake === true || rootMinted(occ), reach: occ?.notes.reach === true || rootMinted(occ), mint: occ?.notes.mint === true, revoke: occ?.notes.revoke === true };
+const mayWake = (occ: OccupantRecord | undefined) => held(occ).wake;
+// The desk mints for a client it vouched for; a device of hers mints the
+// next one. Nobody else, and no ask on her lets an occupant grant itself
+// a note it does not hold.
+const mayMint = (occ: OccupantRecord | undefined) => isDesk(occ) || (isDevice(occ) && held(occ).mint);
+
+// Revoking is its own word and never `mint`'s. A device that mints adds
+// devices, which is noisy and stays visible; one that revokes can take the
+// human's own devices out of her world, so a stolen phone that could do
+// both would lock her out before she reached a laptop. It follows `mint`
+// otherwise: never a default, held only where it was granted, and handed on
+// by a device that holds it and no further. A world where nobody was given
+// it has the act out of reach and the root's own removals instead, and that
+// is a choice an org makes rather than one the dock makes for it.
+const mayRevoke = (occ: OccupantRecord | undefined) => isDesk(occ) || (isDevice(occ) && held(occ).revoke);
+
+// 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 override carries(occ: OccupantRecord | undefined): boolean {
+    return isDevice(occ) && held(occ).reach;
+  }
+  // `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.
+  // The bell standing is plumbing and carries nothing: a device that may
+  // reach what she holds sees acme and the house, and never the envoy that
+  // wakes it. Her ways back are plumbing too, and a way back to a presence
+  // being carries that device's faculties, `to:phone-location-where`, which
+  // is how a model at home learns where the human is.
+  static override hidden(id: string): boolean {
+    return super.hidden(id) || id === PUSH || id.startsWith(`${BELL}:`);
+  }
+  // Her own door is carried to a device that may mint, and to nobody else:
+  // `mint` is the word for a device trusted to change who is in her world,
+  // and owning the world from that device is that trust said in full. A
+  // device that reaches sees acme and the house, and no `home-boot`.
+  static override shows(id: string, occ: OccupantRecord | undefined): boolean {
+    return id !== HOME || held(occ).mint;
+  }
+  static override cells = { name: '', reports: [] as JsonObject[], ways: {} as Record<string, Invitation>, outbox: {} as Record<string, JsonObject[]> };
+
+  // Her standing at the box's push faculty, taken again at every birth: a
+  // standing points at a being and not at a box, and a ward that moved is
+  // handed the new harbor's ground. It is how she rings a browser endpoint,
+  // which is the one kind of doorbell a world holds itself, since an
+  // endpoint answers only to the VAPID secret this world minted. Birth is
+  // synchronous and taking a standing is not, so the promise is kept and
+  // the ring waits on it.
+  //
+  // A box that lends no push rings no tabs, which is what a world with no
+  // web route behind it is.
+  readonly #push: Promise<string | null>;
+  constructor(stance: Stance) {
+    super(stance);
+    this.#push = join(this, PUSH);
+  }
+
+  // A world whose own being she is, is a home: a device reaching her holds
+  // a standing at home and not a membership, and she says so in her notes,
+  // since nothing else in a describe tells a shell which of its worlds is
+  // the human's own. She knows it by the door she holds: the being setup
+  // knocked on the ward's own door as its owner is home's, and a member of
+  // the same class the desk made in an org's ward holds no door and says
+  // nothing.
+  override describe(asker: Asker): Blueprint {
+    const bp = super.describe(asker);
+    if (!this.standings[HOME]) return bp;
+    const notes = bp.notes !== null && typeof bp.notes === 'object' && !Array.isArray(bp.notes) ? bp.notes : {};
+    return { ...bp, notes: { ...notes, home: true } };
+  }
+  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 },
+    device: { description: 'mint an invitation for another device', input: { type: 'object', properties: { client: { type: 'string' }, wake: { type: 'boolean' }, reach: { type: 'boolean' }, mint: { type: 'boolean' }, revoke: { type: 'boolean' } }, required: ['client'] }, for: mayMint },
+    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: OccupantRecord | undefined) => client(occ) === 'agent' },
+    look: { description: 'how she is shown', input: { type: 'object' }, for: isDevice },
+    page: { description: 'her page, as a tree of values', input: { type: 'object' }, for: isDevice },
+    name: { description: 'what she is called', input: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, for: rootMinted },
+    devices: { description: 'the devices in this world, and which one you are', input: { type: 'object' }, for: isDevice },
+    join: { description: 'join a world with an invitation: she knocks, hands back a way to reach her, and keeps the standing', input: { type: 'object', properties: { invitation: { type: 'object', description: 'the invitation that world minted' }, name: { type: 'string', description: 'what to call it here' } }, required: ['invitation', 'name'] }, for: mayMint },
+    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: mayRevoke },
+    report: { description: 'what a run of yours found', input: { type: 'object', properties: { event: { type: 'object' }, result: {} }, required: ['event', 'result'] }, for: isDevice },
+    bell: { description: 'how to wake this device: a standing at its own doorbell and the banner key it seals to, or a browser push endpoint', input: { type: 'object', properties: { invitation: { type: 'object' }, banner: { type: 'string' }, token: { type: 'object' } } }, for: isDevice },
+    missed: { description: 'what this device missed while it was unreachable', input: { type: 'object' }, 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;
+  // if it cannot be taken now, it is kept and tried at the next push. The
+  // desk's first hello names her: a being does not know her own key, and the
+  // root's setup knocks with the name it booted her under. Once named, she
+  // keeps it.
+  async hello(args: JsonObject, asker: Asker) {
+    if (asker.id !== undefined && args.invitation && typeof args.invitation === 'object' && !Array.isArray(args.invitation)) {
+      await this.wayBack(asker.id, args.invitation as Invitation);
+    }
+    if (asker.id === DESK && !this.cells.name && typeof args.name === 'string' && /^[\w.-]{1,80}$/.test(args.name)) this.cells.name = args.name;
+    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)) };
+  }
+
+  // The front desk asks, or a device of hers that may mint; she mints. The
+  // client identity goes into the occupant's notes, and that is what every
+  // gate reads. The three words travel with it, each asked for and each
+  // written only if the asker holds it: devices beget devices, and a device
+  // hands on no more than it was given.
+  async device(args: JsonObject, asker: Asker) {
+    const c = typeof args.client === 'string' ? args.client : null;
+    if (c === null) return { error: 'client is a string' };
+    const mine = held(this.occupant(asker));
+    const inv = await this.invite(c);
+    if (inv === null) return { error: 'id taken' };
+    const rec = this.cells.occupants[c];
+    if (rec) {
+      rec.notes.client = c;
+      for (const w of MINTINGS) if (args[w] === true && mine[w]) rec.notes[w] = true;
+    }
+    return inv as unknown as JsonObject;
+  }
+
+  // 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: JsonObject) {
+    const c = typeof args.client === 'string' ? args.client : null;
+    if (c === null || !this.cells.occupants[c]) return { error: 'no such device, or it gave no way back' };
+    const ways = this.cells.ways as Record<string, Invitation>;
+    const object = (args.object as JsonObject) ?? {};
+    if (!this.standings[`to:${c}`] && ways[c]) await this.wayBack(c, ways[c]);
+    const st = this.standings[`to:${c}`];
+    // A way back she still could not take is a device that is not there:
+    // the knock itself was unreached, which is the same nothing delivered
+    // as an unreached ask, and it is rung like one.
+    if (!st) return ways[c] ? this.unreached(c, object) : { error: 'no such device, or it gave no way back' };
+    const out = await st.ask('notify', object);
+    if (isWord(out) && wordOf(out) === 'unreached') return this.unreached(c, object);
+    return isSilence(out) ? { error: 'silence' } : isWord(out) ? { error: wordOf(out) } : { pushed: out };
+  }
+
+  // Nothing was delivered, so the device is asleep, closed or in a tunnel.
+  // The object waits in her outbox under that device, bounded and oldest
+  // out, since a device gone for a month must not grow without end; then
+  // she rings, and the pusher hears both facts. What the ring carries is
+  // the device's token and nothing of the object: the device wakes, dials,
+  // and drains it over its own standing, sealed.
+  private async unreached(id: string, object: JsonObject) {
+    const box = ((this.cells.outbox as Record<string, JsonObject[]>)[id] ??= []);
+    box.push(object);
+    while (box.length > OUTBOX) box.shift();
+    return { unreached: true, rang: await this.ring(id, object) };
+  }
+
+  // A phone is rung on the standing it handed her, with the line sealed to
+  // the banner key it handed her beside it. Who is ringing is the standing
+  // the ring arrives on, so the ask carries no world, no pk and no token,
+  // and there is nothing in it to forge. A browser is rung on its endpoint
+  // through this box's own push faculty, because an endpoint answers only
+  // to the key this world minted, and the line goes with it unsealed:
+  // Web Push encrypts a body to the subscription's own keys, so a second
+  // seal would hide it from nobody it is not already hidden from.
+  private async ring(id: string, object: JsonObject): Promise<boolean> {
+    const rec = this.cells.occupants[id];
+    const at = this.standings[`${BELL}:${id}`];
+    const key = rec?.notes.banner;
+    if (at && typeof key === 'string') {
+      const sealed = await sealBanner(banner(object), key);
+      return sealed === null ? false : rang(await at.ask('ring', { sealed }));
+    }
+    const token = rec?.notes.bell;
+    if (!isToken(token)) return false;
+    await this.#push;
+    const st = this.standings[PUSH];
+    if (!st) return false;
+    // A browser is handed the line itself. The ground encrypts it under the
+    // subscription's own keys, RFC 8291, and the box that does it is this
+    // world's own, so the line is never seen by anything between them.
+    return rang(await st.ask('ring', { token: token as unknown as JsonObject, line: banner(object) }));
+  }
+
+  // A device says how it is woken, and what it says is kept on its own
+  // occupant, so forgetting the device forgets the way to wake it in the
+  // same act.
+  //
+  // A phone or a desk hands a standing at a doorbell of its own, and the
+  // banner key that doorbell never learns. This world holds a way to wake
+  // that one device and nothing it could hand on: no other world rings on
+  // this standing, the device cuts it by itself at the doorbell, and the
+  // platform's token rotating is one write there that no world is told of.
+  //
+  // A browser hands its endpoint instead and needs no doorbell: an endpoint
+  // is rung only by whoever holds the VAPID secret the subscription was
+  // made under, and that secret is this world's own.
+  //
+  // A store's token never arrives here. The same token at every world is
+  // the bearer credential the doorbell exists to take away, so one is
+  // refused where a human can read why.
+  async bell(args: JsonObject, asker: Asker): Promise<JsonObject> {
+    const c = client(this.occupant(asker));
+    const rec = c === null ? undefined : this.cells.occupants[c];
+    if (c === null || !rec) return { error: 'no client' };
+    // Asked with nothing, she says what she already holds. That is what
+    // makes handing a doorbell over idempotent: a standing does not rotate
+    // the way a token did, so a device hands one over when this world has
+    // none and never again, and the doorbell's list of the worlds it allows
+    // stays a list a human can read and cut.
+    if (args.invitation === undefined && args.token === undefined) {
+      const at = this.standings[`${BELL}:${c}`];
+      return { kept: at && typeof rec.notes.banner === 'string' ? 'doorbell' : isToken(rec.notes.bell) ? 'web' : null };
+    }
+    if (isInvitation(args.invitation)) {
+      const key = args.banner;
+      if (typeof key !== 'string' || !/^[0-9a-f]{64}$/.test(key)) return { error: 'a banner key is thirty two bytes as hex' };
+      const id = `${BELL}:${c}`;
+      this.standings.remove(id);
+      // She knocks and then takes, as every side does: an invitation is
+      // taken only where it was answered. What she asks for is the
+      // blueprint, which at a doorbell is the one ask `ring`.
+      const out = await this.knock(args.invitation);
+      if (isSilence(out) || isWord(out)) return { error: isSilence(out) ? 'silence' : wordOf(out) };
+      if ((await this.take(id, args.invitation)) === null) return { error: 'that invitation was refused' };
+      rec.notes.banner = key;
+      delete rec.notes.bell;
+      return { kept: 'doorbell' };
+    }
+    if (!isToken(args.token)) return { error: 'a token names its kind' };
+    if (args.token.kind !== 'web') return { error: 'a device hands a standing at its own doorbell, never a store token' };
+    rec.notes.bell = args.token;
+    return { kept: 'web' };
+  }
+
+  // The device is back. It drains what it missed and composes what the
+  // human sees from these objects, which crossed sealed and were never on
+  // a push service. Emptied as it is handed over: an ask that answered is
+  // an ask that arrived, and a device that lost the answer has lost one
+  // notification, not its relation.
+  missed(_args: JsonObject, asker: Asker) {
+    const c = client(this.occupant(asker));
+    if (c === null) return { error: 'no client' };
+    const box = this.cells.outbox as Record<string, JsonObject[]>;
+    const out = box[c] ?? [];
+    delete box[c];
+    return { missed: out };
+  }
+
+  // She joins a world. This is the day a homeless org gains a home: an org
+  // whose whole existence was standings in other orgs' worlds boots a home
+  // on a box it trusts, and that home joins each of those from there.
+  // Nothing is converted and no id changes, because from the far world's
+  // side this home is one more thing of hers holding a standing, exactly as
+  // her phone is: her device there minted the invitation with `device`, and
+  // this is the other half, the knock.
+  //
+  // It is a device that may mint who asks it, and that needs no word of its
+  // own: `mint` is what shows her own door to a device, so one that holds
+  // it can boot and invite in her world already, and adding one standing to
+  // what she carries is less than that. In practice such a device holds
+  // `reach` as well, since a device that joined a world it could not then
+  // see would be a device doing something for somebody else. She hands back a way for the far being
+  // to reach her, as a device does at hello, and a far being who refuses it
+  // is joined all the same.
+  async join(args: JsonObject): Promise<JsonObject> {
+    const inv = args.invitation;
+    if (!isInvitation(inv)) return { error: 'that is not an invitation' };
+    const name = typeof args.name === 'string' ? args.name.trim() : '';
+    if (!/^[\w.-]{1,80}$/.test(name) || name === HOME || name === PUSH) return { error: 'a name is a word, and not home or the push' };
+    if (this.standings[name]) return { error: 'name taken' };
+    const back = `from:${name}`;
+    const mine = await this.invite(back);
+    if (mine === null) return { error: 'name taken' };
+    const out = await this.knock(inv, 'hello', { invitation: mine as unknown as JsonObject });
+    if (isSilence(out) || isWord(out)) {
+      this.occupants.remove(back);
+      return { error: isSilence(out) ? 'silence' : wordOf(out) };
+    }
+    if (out !== null && typeof out === 'object' && !Array.isArray(out) && 'error' in out) this.occupants.remove(back);
+    const took = await this.take(name, inv);
+    if (took === null) {
+      this.occupants.remove(back);
+      return { error: 'that invitation was refused' };
+    }
+    return { joined: name };
+  }
+
+  // Her devices, by the names they were given, with what each was granted
+  // and which of them is asking. Without this a human cannot use `forget`
+  // or `push` at all: both name a device, and nobody who has just lost a
+  // phone remembers what it was called. It is read-only and says nothing
+  // secret; a device is a name and three words, and the keys are in the
+  // relations rather than here.
+  // People-shaped rows, since a page says devices are people: a name, and
+  // a line that says what each may do and which one is asking.
+  devices(_args: JsonObject, asker: Asker) {
+    const me = client(this.occupant(asker));
+    return Object.entries(this.cells.occupants)
+      .filter(([id]) => id !== DESK)
+      .map(([id, rec]) => {
+        const notes = (rec as OccupantRecord).notes;
+        const name = typeof notes.client === 'string' ? notes.client : id;
+        const has = MINTINGS.filter((w) => held(rec as OccupantRecord)[w]);
+        const line = [...(name === me ? ['this one'] : []), ...(has.length ? [`may ${has.join(', ')}`] : [])].join(' · ');
+        return { name, line, client: name, ...(name === me ? { you: true } : {}), ...(has.length ? { may: has } : {}) };
+      });
+  }
+
+  // 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: JsonObject) {
+    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}`);
+    this.standings.remove(`${BELL}:${c}`);
+    delete (this.cells.ways as Record<string, Invitation>)[c];
+    delete (this.cells.outbox as Record<string, JsonObject[]>)[c];
+    return { forgot: c };
+  }
+
+  chores() {
+    return { chores: ['census', 'report'] };
+  }
+
+  // How a device shows her: her name as the title, and what each ask is
+  // called. Values only; the screen and the model side each read their part.
+  look() {
+    return {
+      name: (this.cells.name as string) || 'you',
+      order: ['whoami', 'devices', 'device', 'join', 'push', 'forget', 'name'],
+      asks: { whoami: { title: 'who am I', readOnly: true }, devices: { title: 'your devices', readOnly: true }, device: { title: 'invite a device' }, join: { title: 'join a world' }, push: { title: 'wake a device' }, forget: { title: 'take a device out of your world', destructive: true }, name: { title: 'call her' } },
+    };
+  }
+
+  // Her page for a device: her name, who this device is, the worlds she
+  // holds as sections, and the three things a human does here by hand,
+  // bringing her next device in, waking one and naming her. The invitation
+  // `device` answers is a way in, and the side paints it as the link it is,
+  // since a being does not know where her page lives. `hello` and `report` are wiring, a
+  // device's first word and an agent's callback; they stay in her describe
+  // under the gate and off her page, since a page is presentation and the
+  // gate is permission. A device that may not do a thing sees no form for
+  // it, however the page names it.
+  page(_args: JsonObject, asker: Asker) {
+    return {
+      kind: 'stack',
+      of: [
+        { kind: 'text', text: (this.cells.name as string) || 'you', role: 'title' },
+        { kind: 'text', text: `on ${client(this.occupant(asker)) ?? 'a device'}`, role: 'quiet' },
+        { kind: 'text', text: 'your devices', role: 'label' },
+        { kind: 'answer', ask: 'devices', as: 'people' },
+        // every standing she carries as its section, and the door of her
+        // own world as a door: seven owner asks are a page of their own
+        ...Object.keys(this.cells.standings)
+          .sort((a, b) => (a === HOME ? 1 : b === HOME ? -1 : a.localeCompare(b)))
+          .map((id) => (id === HOME ? { kind: 'standing', id, as: 'door' } : { kind: 'standing', id })),
+        { kind: 'form', ask: 'device' },
+        { kind: 'form', ask: 'join' },
+        { kind: 'form', ask: 'push' },
+        { kind: 'form', ask: 'forget' },
+        { kind: 'form', ask: 'name' },
+      ],
+    };
+  }
+
+  // A device the root minted may say what she is called: the root trusts
+  // it with its id and its reach already, and a being does not know her own
+  // key. A name is a word; she keeps the last one given.
+  name(args: JsonObject) {
+    const name = typeof args.name === 'string' ? args.name.trim() : '';
+    if (!/^[\w.-]{1,80}$/.test(name)) return { error: 'a name is a word' };
+    this.cells.name = name;
+    return { named: name };
+  }
+
+  // A device that ran something for her says what it found. Kept, so that
+  // whoever renders her can show it; the ask itself is the callback.
+  report(args: JsonObject, asker: Asker) {
+    (this.cells.reports as JsonObject[]).push({ from: asker.id ?? null, event: args.event ?? null, result: args.result ?? null });
+    return { reported: true };
+  }
+}

package/beings/way.ts

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: Apache-2.0
+// A way in: one being that turns a proof of one kind into who it is for.
+// The desk holds a standing at each of them, under `way:<kind>`, and that
+// id is the whole of what makes a being a way in: there is no table, no
+// registry and nothing set on a class, so a way in is added and removed the
+// way every other relation is, by the root's knock and by remove.
+//
+// Two kinds of holder, and both are ordinary beings:
+//
+// - the box's, lent by the dock ward, as `local` is: the daemon vouches for
+//   a process it saw on its own socket, and what it knows lives in that
+//   being, on the box, dying with it.
+// - the world's own, in the world's ward, as an estate's post is: she holds
+//   the addresses, mints what she handed out and spends it once.
+//
+// A kind is a word the org chose and the dock knows none of them. There is
+// no list here, no registry and no flag on a class, so mail, a message, a
+// code on a screen, a letter, a voice on a call or a sign-in a person holds
+// at some other company are each one kind, named nowhere in this package.
+// Building one nobody here imagined is booting a being and knocking her
+// onto the desk, and that is the whole of it.
+//
+// A way in answers `verify`. One that hands its proof out itself answers
+// `send` beside it, and the desk shows the form for it because her standing
+// says the being can be asked it. She judges neither: she does not know what
+// an address is, whether one was sent to before, or what a link says.
+import type { AskSpec, Json } from '@nervur-org/nervur';
+
+export type Proof = { kind: string; [more: string]: Json };
+// Who the proof is for, and how far the device it admits may go. `make` is
+// the world saying this is a way in that brings its own people: a being
+// under that key is made when there is none, which is what a world anyone
+// may join needs and a world with a fixed household must never say. What
+// is made is the org's being about that person, a membership and never a
+// home: `true` makes a `User`, a class name makes one of the estate's own.
+export type Verified = { user: string; client: string; wake?: boolean; reach?: boolean; mint?: boolean; revoke?: boolean; make?: boolean | string };
+
+// The desk's id for the way in of one kind, and the kind read back off it.
+// The kinds a world offers are the ids the desk holds, and nothing else.
+export const WAY = (kind: string): string => `way:${kind}`;
+export const kindOf = (id: string): string | null => (id.startsWith('way:') ? id.slice(4) : null);
+
+// The two asks a way in may be asked. Every implementation declares these,
+// so one suite reaches all of them and the desk asks one thing of each.
+export const VERIFY: AskSpec = { description: 'who this proof is for', input: { type: 'object', properties: { proof: { type: 'object' } }, required: ['proof'] } };
+export const SEND: AskSpec = { description: 'send a way in to an address of that kind', input: { type: 'object', properties: { to: { type: 'string' } }, required: ['to'] } };
+
+// What came back from `verify`, read before it is trusted. A way in is
+// somebody else's being, so an answer that is not this shape is a refusal
+// and never a caller the desk makes up.
+export function verified(out: unknown): Verified | null {
+  if (out === null || typeof out !== 'object' || Array.isArray(out)) return null;
+  const v = out as Record<string, unknown>;
+  if (typeof v.user !== 'string' || typeof v.client !== 'string') return null;
+  const make = v.make;
+  return {
+    user: v.user,
+    client: v.client,
+    ...(v.wake === true ? { wake: true } : {}),
+    ...(v.reach === true ? { reach: true } : {}),
+    ...(v.mint === true ? { mint: true } : {}),
+    ...(v.revoke === true ? { revoke: true } : {}),
+    ...(make === true || typeof make === 'string' ? { make } : {}),
+  };
+}

package/cli/bundles.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// Where the daemon finds the browser bundles the dock's build emitted. The
+// route is handed two strings and reads nothing; this file is the terrain's
+// half, and it is Node's because the daemon is. One path answers in both
+// trees, because `dist` mirrors the source layout: `human/<name>.bundle.txt`
+// is beside this file's own folder, whether this file is the source the
+// daemon runs from or the JavaScript in an installed package.
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+export type Bundles = { tab: string; worker: string };
+
+const read = async (name: string) => {
+  const at = fileURLToPath(new URL(`../human/${name}.bundle.txt`, import.meta.url));
+  const text = await readFile(at, 'utf8').catch(() => null);
+  if (text === null) throw new Error(`no ${name} bundle at ${at}: run the dock's build, which emits human/${name}.bundle.txt`);
+  return text;
+};
+
+export const bundles = async (): Promise<Bundles> => ({ tab: await read('tab'), worker: await read('worker') });