@nervur-org/dock 0.4.1 → 0.6.0

package/beings/doorbell.ts

@@ -22,7 +22,7 @@
 // invitation to this doorbell, so a bell that held both halves of the
 // relation is a bell that could read a banner, and this one cannot.
 import { Being, isSilence, isWord, wordOf } from 'nervur';
-import type { Asker, JsonObject, OccupantRecord } from 'nervur';
+import type { Asker, JsonObject, OccupantRecord, Standing } from 'nervur';
 
 const DEVICE = 'device';
 // Her standing at the box's push faculty, under an id of her own. The ward
@@ -30,13 +30,19 @@ const DEVICE = 'device';
 const MINE = 'push';
 // What a platform will carry. It is the faculty's number, because the
 // faculty is the one that hands a ring to a platform.
-import { SEAL } from '../dock/push.ts';
+import { SEAL, isToken } from '../box/ring.ts';
+import { PUSH } from '../box/push.ts';
+import { join } from '../box/join.ts';
 
 const isDevice = (occ: OccupantRecord | undefined) => occ?.id === DEVICE;
 const isWorld = (occ: OccupantRecord | undefined) => occ !== undefined && occ.id !== DEVICE;
 const isMaker = (occ: OccupantRecord | undefined) => occ !== undefined;
 
 export class Doorbell extends Being {
+  // Where this class lives in a tree, which is her key in a ward. She says
+  // it herself, so the porter who boots her spells no path of her own and a
+  // class moved is one line moved with it.
+  static readonly at = 'beings/Doorbell';
   static override cells: JsonObject = { token: null, admitted: 0, claimed: false };
   static override asks = {
     claim: { description: 'the one way in for this doorbell, handed out once', input: { type: 'object' }, for: isMaker },
@@ -73,11 +79,34 @@ export class Doorbell extends Being {
 
   // Written once and rewritten whenever the platform hands the phone a new
   // one. No world is told anything, because no world was ever given it.
-  keep(args: JsonObject): JsonObject {
+  //
+  // A kind is one of the rings the box behind this bell holds, and a token
+  // of any other kind is refused here, at the door, with an error object.
+  // The faculty is asked which kinds it rings, because the faculty is the
+  // one that hands a ring to a platform and nothing else on this bell knows.
+  // A device told at the moment it hands a token can hand another or ask its
+  // human for a bell that can reach it; a device told nothing goes on
+  // believing it is reachable until a world rings and is refused, and by then
+  // the only one who could act is the only one not there.
+  async keep(args: JsonObject): Promise<JsonObject> {
     const token = args.token;
-    if (token === null || typeof token !== 'object' || Array.isArray(token) || typeof (token as { kind?: unknown }).kind !== 'string') return { error: 'a token names its kind' };
+    if (!isToken(token)) return { error: 'a token names its kind' };
+    const at = await this.at();
+    if (!at) return { error: 'this box rings nothing' };
+    const said = await at.ask('kinds', {});
+    if (said === undefined || isSilence(said)) return { error: 'this box rings nothing' };
+    if (isWord(said)) return { error: wordOf(said) };
+    const kinds = (said as { kinds?: unknown }).kinds;
+    if (!Array.isArray(kinds)) return { error: 'this box rings nothing' };
+    if (!kinds.includes(token.kind)) return { error: `this box cannot ring a ${token.kind}` };
     this.cells.token = token;
-    return { kept: (token as { kind: string }).kind };
+    return { kept: token.kind };
+  }
+
+  // Her standing at the box's push faculty, taken the first time it is
+  // wanted and held from then on.
+  private async at(): Promise<Standing | undefined> {
+    return this.standings[MINE] ?? (await join(this, PUSH, MINE).then(() => this.standings[MINE]));
   }
 
   // The device allows a world by asking for a way in and handing it over.
@@ -113,7 +142,7 @@ export class Doorbell extends Being {
     if (sealed.length > SEAL) return { error: `a sealed payload is at most ${SEAL} bytes` };
     const token = this.cells.token;
     if (token === null) return { error: 'this device has handed no token' };
-    const at = this.standings[MINE] ?? (await this.lend(MINE, MINE).then(() => this.standings[MINE]));
+    const at = await this.at();
     if (!at) return { error: 'this box rings nothing' };
     const out = await at.ask('ring', { token, sealed });
     if (out === undefined || isSilence(out)) return { error: 'this box rings nothing' };
@@ -123,7 +152,7 @@ export class Doorbell extends Being {
     // not take the ring. Passing that on is the whole of the promise a bell
     // makes, because a ring reported as rung and never sent is worse than one
     // that plainly failed: the world stops trying and the human is never told.
-    if (out !== null && typeof out === 'object' && !Array.isArray(out) && typeof (out as JsonObject).error === 'string') return { error: (out as JsonObject).error as string };
+    if (out !== null && typeof out === 'object' && !Array.isArray(out) && typeof out.error === 'string') return { error: out.error };
     return { rang: true };
   }
 }

package/beings/index.ts

@@ -4,13 +4,26 @@ export { User, DESK, HOME, BELL } from './user.ts';
 export { Desk } from './desk.ts';
 export { WAY, kindOf, verified, VERIFY, SEND, type Proof, type Verified } from './way.ts';
 export { Avatar, USER, PUSHER } from './avatar.ts';
-export { Carrier } from './carry.ts';
+export { carry, blueprint, CARRIES, type Carrying } from './carry.ts';
 export { Presence } from './presence.ts';
 export { Courier, MOVER, isMoving, type Moving } from './courier.ts';
 export { Porter } from './porter.ts';
 export { Doorbell } from './doorbell.ts';
-export { Envoy, owner, occupant, type Delivery, type Wake, type Heard } from './envoy.ts';
-export { DOCK, CONSOLE, LOCAL, LOCATION, NOTIFICATIONS, PUSH, TIMER, FACULTIES, FACULTY_CLASSES, Console, Faculty, Local, Location, Notifications, Push, Timer, isToken, join, settled, stand, standOn, lending, facultyOf, type Ring, type Token, type Where, type Watched, type Woke, type Rooted } from '../dock/index.ts';
-export { webPush, mintVapid, publicOf, apnsPush, pkcs8, HOSTS, fcmPush, isAccount, DOORS, handedTo, ringing, routed, type Vapid, type Apns, type Account, type Doors } from '../dock/index.ts';
+export { BOX, BOX_SEED, Dock, LOCAL, LOCATION, NOTIFICATIONS, PUSH, TIMER, Faculty, Local, Location, Notifications, Push, Timer, contract, covers, nameOf, titleOf, keyed, join, settled, stand, standHarbor, classes, lent, type Contract, type Tree, type Where, type Watched, type Rooted } from '../box/index.ts';
+export { isToken, type Ring, type Token } from '../box/index.ts';
+export { webPush, mintVapid, publicOf, apnsPush, pkcs8, HOSTS, fcmPush, isAccount, DOORS, handedTo, ringing, routed, type Vapid, type Apns, type Account, type Doors } from '../box/index.ts';
 export { Clock, CLOCK, setupClock, placeClock, readSchedule, parseCron, nextFire, civil, fromCivil, type Schedule, type Fire, type Cron, type Civil } from './clock.ts';
 export { sanitise, hint, hintFor, groups, type Look, type Hint } from './look.ts';
+
+import { User } from './user.ts';
+import { Desk } from './desk.ts';
+import { Avatar } from './avatar.ts';
+import { Presence } from './presence.ts';
+import { Clock } from './clock.ts';
+import { Courier } from './courier.ts';
+import { Porter } from './porter.ts';
+import { Doorbell } from './doorbell.ts';
+
+// The beings this folder brings to every harbor, as a tree: a ward names
+// one by where it lives, `beings/User`, as it names a faculty.
+export const BEINGS = { beings: { User, Desk, Avatar, Presence, Clock, Courier, Porter, Doorbell } };

package/beings/join.ts

@@ -11,14 +11,17 @@ import type { Hosted } from 'nervur/harbor';
 import type { Invitation } from 'nervur';
 import type { Avatar } from './avatar.ts';
 
-// Her avatar in a ward, found or booted under the identity's key. An
-// identity is a word, and never a being of the ward.
+// An identity is a word, and never the key of a being the ward holds: the
+// ward is asked, so no route names who its beings are.
+export const isIdentity = (hosted: Hosted, identity: unknown): identity is string => typeof identity === 'string' && /^[\w.-]+$/.test(identity) && !hosted.keys().includes(identity);
+
+// Her avatar in a ward, found or booted under the identity's key.
 export async function avatarOf(hosted: Hosted, identity: string): Promise<{ avatar?: Avatar; error?: string }> {
-  if (!/^[\w.-]+$/.test(identity) || identity === hosted.record.user || identity === 'desk') return { error: 'an identity is a word, and not a being of the ward' };
+  if (!isIdentity(hosted, identity)) return { error: 'an identity is a word, and not a being of the ward' };
   const key = `avatar:${identity}`;
   let avatar = hosted.being(key) as Avatar | undefined;
   if (!avatar) {
-    const out = (await hosted.ask('boot', { key, class: 'Avatar' })) as { error?: string };
+    const out = (await hosted.ask('boot', { key, class: 'beings/Avatar' })) as { error?: string };
     if (out.error) return { error: out.error };
     avatar = hosted.being(key) as Avatar;
   }

package/beings/link.ts

@@ -17,7 +17,7 @@ export const KEY = 'nervur';
 // a query string is in every log and every referer, and one read of it is
 // one way in taken. `<kind>.<token>`, the kind the desk knows it by and the
 // token that door minted.
-export const PROOF = 'proof';
+const PROOF = 'proof';
 const HEX = (n: number) => `[0-9a-f]{${n}}`;
 const FULL = new RegExp(`^(${HEX(128)})\\.(${HEX(64)})\\.(${HEX(64)})$`);
 const PUBLIC = new RegExp(`^${HEX(128)}$`);

package/beings/porter.ts

@@ -15,6 +15,7 @@
 // that a loop in this session stops somewhere a human can see.
 import { Being, isSilence, isWord, wordOf } from 'nervur';
 import type { JsonObject } from 'nervur';
+import { Doorbell } from './doorbell.ts';
 
 const ROOM = 64;
 
@@ -28,8 +29,11 @@ export class Porter extends Being {
     const minted = typeof this.cells.minted === 'number' ? this.cells.minted : 0;
     if (minted >= ROOM) return { error: 'this bell holds no more doorbells' };
 
+    // The class says where it lives and the porter reads it off her. A path
+    // spelled here would be the doorbell named by whoever boots her, which
+    // is a class described by someone who is not it.
     const key = `doorbell:${minted + 1}`;
-    const held = await this.boot('Doorbell', key, key);
+    const held = await this.boot(Doorbell.at, key, key);
     if (held === null) return { error: 'this bell could not make a doorbell' };
     this.cells.minted = minted + 1;
 

package/beings/presence.ts

@@ -15,25 +15,35 @@
 // `settled` before it says the box is up.
 import type { Asker, OccupantRecord, Stance } from 'nervur';
 import { Avatar, PUSHER, USER } from './avatar.ts';
-import { FACULTIES, join } from '../dock/index.ts';
+import { LOCATION } from '../box/location.ts';
+import { NOTIFICATIONS } from '../box/notifications.ts';
+import { PUSH } from '../box/push.ts';
+import { TIMER } from '../box/timer.ts';
+import { join } from '../box/join.ts';
+import { titleOf } from '../box/contract.ts';
 
 export class Presence extends Avatar {
   // Her world's user being sees the box, and nobody else: the way back she
   // handed over at the join is the one occupant who may ask through her.
-  static override carries(occupant: OccupantRecord | undefined, _asker: Asker): boolean {
+  static carries(occupant: OccupantRecord | undefined, _asker: Asker): boolean {
     return occupant?.id === PUSHER;
   }
   // Her standing at the user being is hers to speak through and never to
   // carry: the user being carries her, so carrying it back would be a
   // loop, and it is the one standing that is not a faculty.
-  static override skips(id: string): boolean {
+  static skips(id: string): boolean {
     return id === USER;
   }
 
-  // Which names the box lent her, by name, settled after birth.
+  // What a device can do that a world may want: the contracts she asks her
+  // box for, each held under the word the contract calls itself.
+  static needs = [LOCATION, NOTIFICATIONS, PUSH, TIMER];
+
+  // Which of them the box lent her, by that word, settled after birth.
   readonly lent: Promise<Record<string, string | null>>;
   constructor(stance: Stance) {
     super(stance);
-    this.lent = Promise.all(Object.keys(FACULTIES).map(async (name) => [name, await join(this, name)] as const)).then((all) => Object.fromEntries(all));
+    const C = this.constructor as typeof Presence;
+    this.lent = Promise.all(C.needs.map(async (c) => [titleOf(c), await join(this, c, titleOf(c))] as const)).then((all) => Object.fromEntries(all));
   }
 }

package/beings/setup.ts

@@ -1,45 +1,51 @@
 // 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 `nervur init`, the edge at its root route's init; the memory
-// harbor's test world does the same by hand.
+// The root's setup of a fresh ward, as every terrain does it: the front
+// booted public under `desk`, one home being, the front 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 front `desk`, and
+// that id is the only thing that makes it the front. A disk harbor does this
+// at `nervur 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';
 import type { Hosted } from 'nervur/harbor';
 import { DESK, HOME } from './user.ts';
 
+// The classes setup boots, named where they live. A terrain hands its own:
+// an organisation's ward has an org's home being of the estate's class, and
+// a ward may have an estate's front in place of the dock's.
+export type Setup = { front: string; home: string };
+const SETUP: Setup ={ front: 'beings/Desk', home: 'beings/User' };
+
 // 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,
+// and the home 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> {
+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}`);
+// Everything setup places is placed the same way whatever the classes are:
+// a home key the front already holds is refused by the ward, as any key
+// taken is.
+export async function setup(hosted: Hosted, user: string, classes: Partial<Setup> = {}): Promise<void> {
+  const { front, home } = { ...SETUP, ...classes };
+  if (!/^[\w.-]+$/.test(user)) throw new Error(`a user is a word: ${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 };
+  await boot({ key: DESK, class: front });
+  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 });
+  await boot({ key: user, class: home });
   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');
+  // the front'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 front could not reach the home being');
   await setupHome(hosted, user);
 }

package/beings/user.ts

@@ -7,10 +7,15 @@
 // 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';
-import type { Asker, Blueprint, Invitation, JsonObject, OccupantRecord, Stance } from 'nervur';
-import { Carrier } from './carry.ts';
-import { PUSH, banner, isToken, join, sealBanner } from '../dock/index.ts';
+import { Being, isInvitation, isSilence, isWord, wordOf } from 'nervur';
+import type { Asker, Blueprint, Invitation, JsonObject, OccupantRecord, Reply, Stance } from 'nervur';
+import { CARRIES, carry } from './carry.ts';
+import { banner, isToken, sealBanner } from '../box/index.ts';
+import { PUSH as PUSHING } from '../box/push.ts';
+import { join } from '../box/join.ts';
+
+// Her standing at the box's push faculty, under an id of her own.
+const PUSH = 'push';
 
 export const DESK = 'desk';
 // The prefix her doorbell standings are filed under, one per device: the
@@ -68,13 +73,13 @@ const mayMint = (occ: OccupantRecord | undefined) => isDesk(occ) || (isDevice(oc
 // 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
+// She carries her standings, her org, 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 the org 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 {
+export class User extends Being {
+  static 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
@@ -82,20 +87,24 @@ export class User extends Carrier {
   // 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
+  // reach what she holds sees the org 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}:`);
+  static hidden(id: string): boolean {
+    return CARRIES.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 {
+  // device that reaches sees the org and the house, and no `home-boot`.
+  static shows(id: string, occ: OccupantRecord | undefined): boolean {
     return id !== HOME || held(occ).mint;
   }
+
+  override answer(asker: Asker, method?: string, args: JsonObject = {}): Promise<Reply> {
+    return carry(this, asker, method, args, (a, m, g) => super.answer(a, m, g));
+  }
   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
@@ -111,7 +120,7 @@ export class User extends Carrier {
   readonly #push: Promise<string | null>;
   constructor(stance: Stance) {
     super(stance);
-    this.#push = join(this, PUSH);
+    this.#push = join(this, PUSHING, PUSH);
   }
 
   // A world whose own being she is, is a home: a device reaching her holds
@@ -373,9 +382,9 @@ export class User extends Carrier {
     return Object.entries(this.cells.occupants)
       .filter(([id]) => id !== DESK)
       .map(([id, rec]) => {
-        const notes = (rec as OccupantRecord).notes;
+        const notes = rec.notes;
         const name = typeof notes.client === 'string' ? notes.client : id;
-        const has = MINTINGS.filter((w) => held(rec as OccupantRecord)[w]);
+        const has = MINTINGS.filter((w) => held(rec)[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 } : {}) };
       });

package/beings/way.ts

@@ -7,7 +7,7 @@
 //
 // Two kinds of holder, and both are ordinary beings:
 //
-// - the box's, lent by the dock ward, as `local` is: the daemon vouches for
+// - the box's, lent by the box 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

package/{dock → box}/agents.ts

@@ -1,47 +1,30 @@
 // SPDX-License-Identifier: Apache-2.0
-// The box's agents: `agents`, one faculty of the dock ward, standing for the
-// one thing a box does on an event as the timer does on a moment: run a
-// process. What she holds is the table of agents, in her cells and in no
-// file, placed by the root with `keep` the way a schedule is placed on the
-// clock, so a box has one place its state is and the daemon reads no recipe.
+// The box's agents: on an event, run something for an identity, as the timer
+// does on a moment. What she holds is the table of agents in her cells,
+// placed by the root with `keep`. A row names a client identity, the ward
+// she is admitted into, and what runs for her: a process, a command with its
+// args in its folder, or a model at a url.
 //
-// A row names a client identity, the ward she is admitted into, and what
-// runs for her, one of two: a process, a command with its args in its
-// folder, or a model that speaks function calling, a base URL and a model
-// name, OpenRouter, LM Studio, anything with a tools array. At her birth
-// on a daemon she admits each identity into its ward as an avatar, through
-// the box's own way in, and stands the side her row says over that avatar.
-// A push from the user being is the event either way: the agent side runs
-// the command with it and reports what it printed; the runner side turns it
-// into a turn of the model's conversation with her describe as tools. The
-// queue is in the avatar's cells, so it survives a restart; the row is in
-// hers, so the agent comes back with the box.
-//
-// The daemon hands her how to run a row, as it hands the grants faculty how
-// to persist: running an agent is admitting through a socket only a daemon
-// has, and this file is not in the dock's index, since a tab has no process
-// to spawn. A box with no runner keeps the table and runs nobody.
+// How a row runs is the terrain's, since admitting through a socket and
+// spawning a process are things only a daemon has, so it is handed to her
+// at birth in the class body the terrain brings; this body runs nobody and
+// stands nowhere. Every row runs once the box is up.
 import { OWNER } from 'nervur';
-import type { Asker, JsonObject, OccupantRecord } from 'nervur';
+import { contract } from './contract.ts';
+import type { Asker, JsonObject, OccupantRecord, Stance } from 'nervur';
+import type { Harborage } from './box.ts';
 import { Faculty } from './faculty.ts';
 
-// The name the dock ward holds her under.
-export const AGENTS = 'agents';
-
-// One agent. `id` is the client identity the avatar is known by in her ward.
-// A process row and a model row, told apart by what they name.
 export type Process = { command: string; args: string[]; dir: string };
 export type Model = { url: string; model: string; key?: string; turns?: number };
 export type Row = { id: string; ward: string } & (Process | Model);
 export const isProcess = (r: Row): r is { id: string; ward: string } & Process => 'command' in r;
 
-// What a daemon stands for a row: a side over her avatar, closed when the
+// What a terrain stands for a row: a side over her avatar, closed when the
 // row is dropped or the box goes down.
 export type Side = { close(): Promise<void> };
 export type Runner = (row: Row) => Promise<Side>;
 
-// The root and nobody else, as the clock gates `keep`: an ask gated this way
-// is the device's own and cannot be reached through a door.
 const root = (_occ: OccupantRecord | undefined, asker: Asker) => asker.id === OWNER;
 
 const ROW = {
@@ -50,26 +33,36 @@ const ROW = {
   required: ['id', 'ward'],
 };
 
+const ASKS = {
+  keep: { description: 'add an agent, or replace the one of that id: an identity, her ward, and what runs for her, a command with args in a folder, or a model at a url', input: ROW, for: root },
+  drop: { description: 'stop an agent and forget her row; the avatar in her ward stays until the root removes her', input: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] }, for: root },
+  list: { description: 'every agent she holds', input: { type: 'object' }, for: root },
+};
+
+// What the box's own code needs from the faculty that runs its agents.
+export const AGENTS = contract('agents', ASKS);
+
 export class Agents extends Faculty {
   static override cells: JsonObject = { watched: {}, minted: 0, agents: {} };
-  static override asks = {
-    keep: { description: 'add an agent, or replace the one of that id: an identity, her ward, and what runs for her, a command with args in a folder, or a model at a url', input: ROW, for: root },
-    drop: { description: 'stop an agent and forget her row; the avatar in her ward stays until the root removes her', input: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] }, for: root },
-    list: { description: 'every agent she holds', input: { type: 'object' }, for: root },
-  };
+  static override asks = ASKS;
+  static override fulfils = [AGENTS];
+  static override stands(): boolean {
+    return false;
+  }
 
-  runner: Runner | undefined;
+  readonly runner: Runner | undefined;
   readonly running = new Map<string, Side>();
 
-  private get rows(): Record<string, Row> {
-    return this.cells.agents as unknown as Record<string, Row>;
+  constructor(stance: Stance, box?: Harborage, runner?: Runner) {
+    super(stance, box);
+    this.runner = runner;
+    this.box.up(async () => {
+      for (const row of Object.values(this.rows)) await this.#run(row);
+    });
   }
 
-  // Every row up, once the daemon has handed the runner. Called after the
-  // wards are hosted, since an avatar is admitted into one of them.
-  async start(runner: Runner): Promise<void> {
-    this.runner = runner;
-    for (const row of Object.values(this.rows)) await this.#run(row);
+  private get rows(): Record<string, Row> {
+    return this.cells.agents as unknown as Record<string, Row>;
   }
 
   async #run(row: Row): Promise<void> {
@@ -110,7 +103,7 @@ export class Agents extends Faculty {
   }
 
   list(): JsonObject {
-    return { agents: Object.values(this.rows) as unknown as JsonObject[] };
+    return { agents: Object.values(this.rows) };
   }
 
   // The device puts the box down: every side closes, the rows stay.

package/{dock → box}/apns.ts

@@ -27,7 +27,7 @@
 // `quo-harbor.md`'s to say and not this file's. A stand-in in a test is an
 // ordinary HTTP/1.1 server, so what a test proves is the shape and the
 // signing rather than the transport, as the tab's push service did.
-import type { Ring, Token } from './push.ts';
+import type { Ring, Token } from './ring.ts';
 
 const subtle = () => globalThis.crypto.subtle;
 const ES256 = { name: 'ECDSA', namedCurve: 'P-256' } as const;
@@ -83,9 +83,9 @@ export async function provider(a: Apns, made: { at: number; jwt: string } | null
 // The device a token names, or nothing a ring may send. It is checked
 // where a human can read why rather than by Apple two hops later.
 export function device(token: Token): string {
-  const device = token.device;
-  if (typeof device !== 'string' || !/^[0-9a-fA-F]{8,200}$/.test(device)) throw new Error('an apns token is a device token');
-  return device;
+  const named = token.device;
+  if (typeof named !== 'string' || !/^[0-9a-fA-F]{8,200}$/.test(named)) throw new Error('an apns token is a device token');
+  return named;
 }
 
 // One ring, as Apple reads it: the path, the headers and the body. A ring

package/box/box.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+// What the harbor is to a faculty: the three things only a box has, handed
+// to every faculty at birth, so nobody writes into a faculty afterwards.
+//
+// `save` keeps her ward, for a faculty whose cells change outside any ask, a
+// token issued by a route. `now` is the box's clock. `up` is work to do once
+// the box is up, every ward hosted and every being settled, for a faculty
+// whose work reaches the rest of the box, a line dialed or an agent run; the
+// terrain that says the box is up waits for that work, so a box is up when
+// it has landed, and work handed after that runs at once.
+export type Harborage = { save(): Promise<void>; now(): number; up(work: () => Promise<void>): void };
+
+// The harborage a faculty holds when none was handed: a suite's ward, which
+// keeps nothing, reads the runtime's clock, and does its work at once.
+export const ALONE: Harborage = { save: () => Promise.resolve(), now: () => Date.now(), up: (work) => void work().catch(() => {}) };
+
+// A harborage over a ward's save, raised by the terrain once the box is up.
+export function harborageOver(save: () => Promise<void>, now: () => number = () => Date.now()): Harborage & { raise(): Promise<void> } {
+  let waiting: (() => Promise<void>)[] | null = [];
+  const run = (work: () => Promise<void>) => work().catch(() => {});
+  return {
+    save,
+    now,
+    up: (work) => (waiting ? void waiting.push(work) : void run(work)),
+    raise: async () => {
+      const held = waiting ?? [];
+      waiting = null;
+      await Promise.all(held.map(run));
+    },
+  };
+}

package/box/contract.ts

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+// A contract: what a caller needs from a faculty, said as a blueprint and
+// nothing else, so it is written, read and hashed exactly as a describe is.
+// It is known by its digest, and that digest is the name a box lends under.
+// Nothing enforces it, as Quo enforces no blueprint: the caller reads the
+// describe she was handed and decides with `covers`.
+import { canonical, digest } from 'nervur';
+import type { Ask, AskSpec, Blueprint } from 'nervur';
+
+export type Contract = Blueprint;
+
+// A contract out of the asks a class declares. Descriptions stay behind,
+// since they are words for a reader and a reworded sentence must not move a
+// name. The title is the contract's own word for itself.
+export function contract(title: string, asks: Record<string, AskSpec>): Contract {
+  return {
+    asks: Object.entries(asks).map(([name, spec]) => ({ name, input: spec.input ?? { type: 'object' }, ...(spec.output !== undefined ? { output: spec.output } : {}) })),
+    notes: { title },
+  };
+}
+
+// The name a contract is lent under.
+export const nameOf = (c: Contract): Promise<string> => digest(c);
+
+// The word a contract calls itself.
+export const titleOf = (c: Contract): string => {
+  const t = (c.notes as { title?: unknown } | null)?.title;
+  return typeof t === 'string' ? t : '';
+};
+
+// Whether a blueprint covers a contract, ask by ask: every ask the contract
+// names stands in it with the same input, and the same output where the
+// contract says one, in the canonical form. It may carry asks of its own.
+export function covers(held: Blueprint, c: Contract): boolean {
+  const byName = new Map<string, Ask>(held.asks.map((a) => [a.name, a]));
+  return c.asks.every((want) => {
+    const got = byName.get(want.name);
+    if (!got || canonical(got.input) !== canonical(want.input)) return false;
+    return want.output === undefined || (got.output !== undefined && canonical(got.output) === canonical(want.output));
+  });
+}