@nervur-org/dock 0.4.1 → 0.6.0

package/box/timer.ts

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's clock, and the one being on a device that reads one. A being who
+// could read a clock could not be moved, since the moment she read would be
+// her box's and no other, so the moment reaches every other being the one way
+// anything reaches a being: as an ask at her door, from this faculty, as the
+// occupant she named when she asked to be woken.
+//
+// She arms for the next due moment and for nothing else. Every watcher
+// answers a round with when she is next due, this arms for the earliest of
+// them, and a box whose watchers all say null arms nothing. A round is armed
+// for one moment at a time and never overlaps the one before, and the moment
+// is floored to the minute with half a second after it, since a watcher
+// floors the moment she is handed.
+//
+// One method knows a terrain, `arm`, and a subclass replaces it: a
+// `setTimeout` here, the object's storage alarm on a worker. Her moment is
+// the box's clock.
+import type { JsonObject } from 'nervur';
+import { contract } from './contract.ts';
+import { Faculty, WATCH, type Woke } from './faculty.ts';
+
+const ASKS = {
+  watch: WATCH,
+  due: { description: 'bring my next round forward to this moment', input: { type: 'object', properties: { at: { type: 'number' } }, required: ['at'] } },
+  now: { description: 'this box’s moment', input: { type: 'object' } },
+};
+
+// What a being needs from a box that can wake her at a moment.
+export const TIMER = contract('timer', ASKS);
+
+const MINUTE = 60_000;
+// A timeout further out than this is not trusted, so the arming is capped and
+// made again when it goes off.
+const DAY = 86_400_000;
+
+export class Timer extends Faculty {
+  static override asks = ASKS;
+  static override fulfils = [TIMER];
+
+  #timeout: ReturnType<typeof setTimeout> | undefined;
+  #stopped = false;
+  #armed: number | null = null;
+  #round: Promise<Woke[]> | null = null;
+
+  // The moment she is armed for, or null while she is asleep.
+  get armed(): number | null {
+    return this.#armed;
+  }
+
+  // A watcher says she is due sooner than the box knew. It only ever brings
+  // the round forward.
+  due(args: JsonObject): JsonObject {
+    const at = args.at;
+    if (typeof at !== 'number' || !Number.isFinite(at)) return { error: 'a due carries the moment: { at }' };
+    const when = moment(at);
+    if (this.#armed === null || when < this.#armed) this.#arm(when);
+    return { armed: this.#armed };
+  }
+
+  // Whoever was just filed is ticked at once, and what she answers is what
+  // the box arms for, so she is never waiting for a round nobody scheduled.
+  protected override async welcomed(id: string): Promise<void> {
+    await this.round(this.box.now(), id);
+  }
+
+  // The arming went off. A moment still well ahead is the day's cap, so it is
+  // armed again rather than fired.
+  async rang(): Promise<Woke[]> {
+    if (this.#stopped) return [];
+    if (this.#armed !== null && this.#armed - this.box.now() > 1_000) {
+      this.arm(this.#armed);
+      return [];
+    }
+    return this.fire(this.box.now());
+  }
+
+  // The device's own call at a moment it names: how a suite proves a wake
+  // without waiting for one and how an operator makes a round happen now.
+  fire(now: number): Promise<Woke[]> {
+    return this.round(now);
+  }
+
+  // One round, and never two at once.
+  protected round(now: number, only?: string): Promise<Woke[]> {
+    if (this.#round) return this.#round;
+    const mine = this.#run(now, only);
+    this.#round = mine;
+    return mine.finally(() => {
+      if (this.#round === mine) this.#round = null;
+    });
+  }
+
+  async #run(now: number, only?: string): Promise<Woke[]> {
+    if (only === undefined) this.#arm(null);
+    const woke = await this.woke((w) => ({ ...w.args, now }), only);
+    if (woke === null) {
+      this.stop();
+      return [];
+    }
+    // A moment already gone is no arming.
+    const named = soonest(woke);
+    const said = named !== null && named > this.box.now() ? named : null;
+    const held = this.#armed;
+    const at = said === null ? held : held === null ? moment(said) : Math.min(held, moment(said));
+    if (at !== null && at !== this.#armed) this.#arm(at);
+    else if (at === null && this.#armed !== null) this.#arm(null);
+    return woke;
+  }
+
+  #arm(when: number | null): void {
+    if (this.#stopped) return;
+    this.#armed = when;
+    this.arm(when);
+  }
+
+  // The one thing a terrain says about itself: be woken at this moment, or at
+  // no moment at all. Here a timeout, capped at a day, unreferenced so the box
+  // stays up for its work and never for this.
+  protected arm(when: number | null): void {
+    clearTimeout(this.#timeout);
+    this.#timeout = undefined;
+    if (when === null) return;
+    this.#timeout = setTimeout(() => void this.rang(), Math.min(Math.max(when - this.box.now(), 0), DAY));
+    this.#timeout.unref?.();
+  }
+
+  // The device puts the box down.
+  stop(): void {
+    this.#stopped = true;
+    this.#armed = null;
+    this.arm(null);
+  }
+
+  now(): JsonObject {
+    return { now: this.box.now() };
+  }
+}
+
+const moment = (at: number): number => Math.max(at, Math.floor(at / MINUTE) * MINUTE + 500);
+
+function soonest(woke: Woke[]): number | null {
+  let at: number | null = null;
+  for (const w of woke) {
+    if (w.out === null || typeof w.out !== 'object') continue;
+    const next = (w.out as { next?: unknown }).next;
+    if (typeof next !== 'number' || !Number.isFinite(next)) continue;
+    if (at === null || next < at) at = next;
+  }
+  return at;
+}

package/box/tree.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: Apache-2.0
+// Classes as a harbor is handed them: a tree whose branches are folders and
+// whose leaves are exports, the way a repository holds them. A module
+// namespace is a branch, so `{ box: await import('./box/index.ts') }`
+// is a tree, and so is a bundle's nested exports. The repository is a
+// harbor's DNA; the cells are its memory.
+import type { BeingClass } from 'nervur';
+
+export type Tree = { readonly [name: string]: unknown };
+
+// Every class in a tree, keyed by where it lives: the folders down to it and
+// its export name, `box/Dock`. The key is the class's identity in a ward,
+// as a being's key is hers, and it moves only when the class moves.
+export function keyed(tree: Tree, at = ''): Record<string, BeingClass> {
+  const out: Record<string, BeingClass> = {};
+  for (const [name, v] of Object.entries(tree)) {
+    const key = at ? `${at}/${name}` : name;
+    if (typeof v === 'function' && 'prototype' in v) out[key] = v as BeingClass;
+    else if (v !== null && typeof v === 'object' && !Array.isArray(v)) Object.assign(out, keyed(v as Tree, key));
+  }
+  return out;
+}

package/{dock → box}/webpush.ts

@@ -12,7 +12,7 @@
 // `auth` of the subscription it made, so the one party a banner key would
 // hide the line from on this path is the push service, which that
 // encryption already excludes. A second seal would buy nothing and would
-// make every tab stand a dock ward to keep a banner key in. So the world
+// make every tab stand a box ward to keep a banner key in. So the world
 // encrypts here, the browser decrypts, and the service worker shows what it
 // was handed rather than a line it guessed at.
 //
@@ -23,7 +23,7 @@
 // This is one ground of the three the bell has. APNs and FCM are the
 // stores' own and want a platform key; this one stands where nothing is in
 // the way, a keypair the world mints itself.
-import type { Line, Ring, Token } from './push.ts';
+import type { Line, Ring, Token } from './ring.ts';
 
 const subtle = () => globalThis.crypto.subtle;
 const ES256 = { name: 'ECDSA', namedCurve: 'P-256' } as const;

package/cli/client.ts

@@ -5,7 +5,7 @@ import { connect } from 'node:net';
 import { createInterface } from 'node:readline';
 import { sockPath, sidePath } from './daemon.ts';
 
-export type Answer = { result: unknown } | { error: string };
+export type Answer = { result: unknown; ward?: string } | { error: string };
 
 // `via` names a standing the ward's user being holds at another ward: the
 // ask is then an owner's ask at that ward's door, sealed, and the answer is

package/cli/daemon.ts

@@ -32,11 +32,11 @@
 //               <- { ok: as } | { error }, then one line per final text
 //
 // The proof for a local side is that it reached side.sock: the daemon mints
-// a nonce for the connection on the `local` faculty of its dock ward, the
+// a nonce for the connection on the `local` faculty of its box ward, the
 // box's own way in, and the desk trades it at a standing there, once. A
 // `local` proof arriving any other way names no nonce and is refused.
 //
-// Agents have no door: the `agents` faculty of the dock ward holds each
+// Agents have no door: the `agents` faculty of the box ward holds each
 // agent's identity, her ward, her command and her folder, placed by the
 // root with `keep` as a schedule is placed on the clock, and the daemon
 // admits her on the local proof and runs the agent side beside her avatar
@@ -80,13 +80,12 @@
 // through the droplet it dialed.
 import { createServer, type Server, type Socket } from 'node:net';
 import type { Server as HttpServer } from 'node:http';
-import { unlink, chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { unlink, chmod } from 'node:fs/promises';
 import { createHash, randomBytes } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
-import { isSilence, isWord, wordOf, type Invitation, type JsonObject } from 'nervur';
+import { isSilence, isWord, wordOf, type Invitation, type JsonObject, type Stance } from 'nervur';
 import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { DiskHarbor, defaultWard, type Hosted } from '../harbor/disk.ts';
@@ -94,12 +93,10 @@ import type { Harbor } from 'nervur/harbor';
 import type { Avatar, User } from '../beings/index.ts';
 // an identity in a world: the three asks any terrain's routes make at a ward
 export { avatarOf, letIn, find } from '../beings/join.ts';
-import { avatarOf, letIn, find } from '../beings/join.ts';
-import { DOCK, FACULTIES, LOCAL, PUSH, TIMER, Local, Push, Timer, facultyOf, publicOf, routed, settled, webPush, type Ring } from '../dock/index.ts';
-import { apnsHttp2, apnsOf } from '../dock/http2.ts';
-import { GRANTS, Grants } from '../dock/grants.ts';
-import { AGENTS, Agents, isProcess } from '../dock/agents.ts';
-import { DIALERS, Dialers } from '../dock/dialers.ts';
+import { avatarOf, isIdentity, letIn, find } from '../beings/join.ts';
+import { Http as Wire, routed, webPush, type Ring } from '../box/index.ts';
+import { apnsHttp2, apnsOf } from '../box/http2.ts';
+import { AGENTS, Agents, BOX, BOX_SEED, DIALERS, Dialers, GRANTS, Grants, LOCAL, Local, PUSH, Push, TIMER, Timer, WIRE, boxOf, isProcess, keyLent, lent, settled, type Harborage } from '../box/index.ts';
 import { mcpSide } from '../mcp/server.ts';
 import { runnerSide, type Model } from '../mcp/runner.ts';
 import { agentSide, processRun } from '../mcp/agent.ts';
@@ -118,7 +115,10 @@ import { listenHttp, type Http, type Quo } from '../harbor/http.ts';
 export type { Routes } from '../mcp/route.ts';
 export type Serving = { harbor: DiskHarbor; sock: string; side: string; http: Http | null; grants: Grants | null; oauth: OAuth | null; exchange: Exchange | null; mcp: McpHttp | null; agents: Agents | null; quo: Quo; tick(now: number): Promise<void>; close(): Promise<void> };
 // `rings` is what a test puts in the push faculty beside what the device's
-// environment gives: a recorder where a platform would be.
+// environment gives: a recorder where a platform would be. `http.host` is
+// the address the door binds, loopback when nothing says otherwise: a
+// daemon on a café network is a harbor anyone on it can knock at, so the
+// address is said by hand or it is 127.0.0.1.
 export type Options = { http?: { port: number; host?: string }; routes?: Routes; apps?: Apps | null; dial?: string[]; rings?: Record<string, Ring> };
 
 // The sockets live in the harbor's folder, where the folder's own permissions
@@ -139,17 +139,17 @@ export const sidePath = (dir: string) => socketPath(dir, 'side');
 // the first time only; to change one, remove the occupant and admit again.
 // The one path for a side on the device: agents, and sides on side.sock.
 //
-// The nonce is minted on the `local` faculty of this box's dock ward, in
+// The nonce is minted on the `local` faculty of this box's box ward, in
 // this process, as a device fires its own timer. A box that lends no such
 // name has no local way in, and nothing here can make one up.
 export async function admit(harbor: Harbor, hosted: Hosted, identity: string, wake = false, reach = false): Promise<{ avatar?: Avatar; error?: string }> {
-  const local = facultyOf<Local>(harbor, LOCAL);
+  const local = await lent<Local>(harbor, LOCAL);
   if (!local) return { error: 'this box has no local way in' };
   const found = await avatarOf(hosted, identity);
   if (!found.avatar) return found;
   const nonce = randomBytes(16).toString('hex');
   local.mint(nonce, { user: hosted.record.user, client: identity, ...(wake ? { wake: true } : {}), ...(reach ? { reach: true } : {}) });
-  const entered = await found.avatar.enter({ ward: hosted.pk }, { kind: LOCAL, nonce });
+  const entered = await found.avatar.enter({ ward: hosted.pk }, { kind: 'local', nonce });
   local.drop(nonce);
   await hosted.save(); // the knock went through the ward's own door, which the harbor never sees
   if ('error' in entered && !('asks' in entered)) return { error: entered.error };
@@ -169,8 +169,8 @@ async function tick(harbor: DiskHarbor, now: number): Promise<void> {
   // booted a moment ago is still taking one, and a round that ran past her
   // would be a schedule placed and a minute missed for no reason a reader
   // could see.
-  await settled();
-  const timer = facultyOf<Timer>(harbor, TIMER);
+  await settled(harbor);
+  const timer = await lent<Timer>(harbor, TIMER);
   if (!timer) return;
   try {
     for (const woke of await timer.fire(now)) {
@@ -203,17 +203,55 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
   // world's own web origin; the push faculty reads the map at each ring, so
   // it is this daemon's `Push` body and no static set on a class.
   const rings: Record<string, Ring> = { ...options.rings };
+  // The web ring is hers alone: Web Push signed under the doorbell key she
+  // minted at the root's first ask, with this world's web origin as the
+  // subject a push service may complain to, known once the routes are.
+  let subject: string | undefined;
   class DaemonPush extends Push {
+    static override stands(): boolean {
+      return true;
+    }
+    #web: Ring | undefined;
     protected override get rings(): Readonly<Record<string, Ring>> {
-      return rings;
+      const key = this.key;
+      if (rings.web || !key || !subject) return rings;
+      return { ...rings, web: (this.#web ??= webPush({ key, subject })) };
+    }
+  }
+  const harbor = new DiskHarbor(dir);
+  // The lines this box holds open are dialed for its own harbor, and an
+  // agent runs as an identity admitted on the local proof with a side over
+  // her avatar: the two live things only this process has, handed in the
+  // class bodies it brings.
+  class DaemonDialers extends Dialers {
+    static override stands(): boolean {
+      return true;
+    }
+    constructor(stance: Stance, box?: Harborage) {
+      super(stance, box, harbor);
+    }
+  }
+  class DaemonAgents extends Agents {
+    static override stands(): boolean {
+      return true;
+    }
+    constructor(stance: Stance, box?: Harborage) {
+      super(stance, box, async (row) => {
+        const hosted = harbor.wards.get(row.ward);
+        if (!hosted) throw new Error(`agent ${row.id}: this device hosts no ward ${row.ward}`);
+        const admitted = await admit(harbor, hosted, row.id);
+        if (!admitted.avatar) throw new Error(`agent ${row.id}: ${admitted.error}`);
+        // a process is the agent side, a model is the runner: both take a push as the event
+        return isProcess(row) ? agentSide(admitted.avatar, processRun(row.command, row.args, row.dir), () => hosted.save()) : runnerSide(admitted.avatar, row, () => {}, () => hosted.save());
+      });
     }
   }
-  const harbor = new DiskHarbor(dir, undefined, { Push: DaemonPush, Grants, Agents, Dialers });
-  // What a daemon lends beyond every box's faculties: `local`, the way in
-  // for a process it saw on its own socket, and `grants`, the bearers its
-  // routes honour. A device with no daemon has neither name, and the desk
-  // there is a world nobody walks into locally.
-  harbor.lent = { ...FACULTIES, [LOCAL]: 'Local', [GRANTS]: 'Grants', [AGENTS]: 'Agents', [DIALERS]: 'Dialers' };
+  // What a daemon brings to its own ward: the timer, `local`, the way in for
+  // a process it saw on its own socket, the grants its routes honour, and
+  // the ring, the lines and the agents it builds here. A device with no
+  // daemon brings none of the last five, and the desk there is a world
+  // nobody walks into locally.
+  harbor.faculties = { box: { Timer, Local, Grants, Http: Wire }, cli: { DaemonPush, DaemonDialers, DaemonAgents } };
   // A store that refused a save, once per ward. Every asker whose write was
   // refused has already been told, at the door that caused it, and none of
   // them is this operator: a disk that has stopped taking one world's writes
@@ -223,6 +261,14 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
     if (faults === 1) console.log(JSON.stringify({ at: new Date().toISOString(), refused: name }));
   };
   await harbor.boot();
+  // A contract two classes clashed under is lent to nobody, and the Dock
+  // keeps which; an operator reads it here, once, at boot, and the box is
+  // up either way.
+  const stood = (await harbor.wards.get(BOX_SEED)?.ask('ask', { being: BOX, method: 'lends' })) as { clashes?: Record<string, string[]> } | undefined;
+  for (const [word, keys] of Object.entries(stood?.clashes ?? {})) console.log(JSON.stringify({ at: new Date().toISOString(), clash: word, between: keys }));
+  // What the box is, asked of the Dock and read from no file: its routes,
+  // its apps and its default ward, each placed by the root through her asks.
+  const box = await boxOf(harbor);
   // A ward the folder keeps and the harbor could not open stops this daemon
   // here. The core is right to carry on without it, since a device with many
   // worlds must not lose them all to one, but a daemon's folder is an
@@ -250,7 +296,7 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
   let mcp: McpHttp | null = null;
   let agents: Agents | null = null;
   // the dialers faculty holds the lines; the route's view of them is hers
-  const dialers = facultyOf<Dialers>(harbor, DIALERS);
+  const dialers = await lent<Dialers>(harbor, DIALERS);
   if (!dialers) throw new Error('this box has no dialers faculty');
   const quo: Quo = {
     sockets: new Set(),
@@ -278,37 +324,37 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
       // The box's grants, one faculty for every route: a bearer names an
       // identity in a world, the identity names her avatar there, and the
       // route only says the grammar. Nothing is minted for a bearer. Her
-      // cells are the dock ward's to keep, so a token issued saves it.
-      grants = facultyOf<Grants>(harbor, GRANTS) ?? null;
+      // cells are the box ward's to keep, so a token issued saves it.
+      grants = (await lent<Grants>(harbor, GRANTS)) ?? null;
       if (!grants) throw new Error('this box has no grants');
-      grants.persist = () => harbor.wards.get(DOCK)?.save() ?? Promise.resolve();
-      const resolve = async (identity: string, ward: string) => {
+      const findIn = async (identity: string, ward: string) => {
         const hosted = harbor.wards.get(ward);
         return hosted ? find(hosted, identity) : { error: 'no such world' };
       };
-      const join = async (identity: string, invitation: Invitation, ward: string) => {
+      const joinIn = async (identity: string, invitation: Invitation, ward: string) => {
         const hosted = harbor.wards.get(ward);
         if (!hosted) return { error: 'no such world' };
         const r = await letIn(hosted, identity, invitation);
         return r.error ? { error: r.error } : {};
       };
-      const routes = options.routes ?? (await readRoutes(harbor.dir));
+      const routes = options.routes ?? box.routes;
       const here = `http://${http.host}:${http.port}`;
       const at = { quo: routes?.quo ?? `${here}/quo`, web: routes?.web ?? `${here}/web` };
+      subject = new URL(at.web).origin;
       // a stranger's public being as {}, or an occupant's avatar under a
       // bearer; `web` is for its one human arrival, a redirect landing back
       // which ward a caller who names none is at is the terrain's word, and
       // on a disk it is the mark an operator wrote, read below at `defaultWard`
-      http.mount('/api', apiRoute({ wards: harbor.wards, here: () => harbor.defaultWard }, { grants, resolve, join, web: at.web }));
+      http.mount('/api', apiRoute({ wards: harbor.wards, here: () => harbor.defaultWard }, { grants, resolve: findIn, join: joinIn }));
       // The web ring, under the world's own doorbell key: the push faculty
       // mints it the first time this box serves a web route and keeps it in
       // her cells, so it lives with the wards and in no file. The ring is
       // Web Push signed under it, and the subject a push service may
       // complain to is this world's own web route, which every world has.
-      const push = facultyOf<Push>(harbor, PUSH);
+      const push = await lent<Push>(harbor, PUSH);
       if (!push) throw new Error('this box has no push faculty');
-      const key = await push.mint();
-      rings.web ??= webPush({ key, subject: new URL(at.web).origin });
+      const bell = (await harbor.wards.get(BOX_SEED)?.ask('ask', { being: await keyLent(harbor, PUSH), method: 'bell' })) as { bell?: string } | undefined;
+      if (typeof bell?.bell !== 'string') throw new Error('this box minted no doorbell key');
       // The two rings the stores own. A world holds no platform key and
       // never will, because Apple and Google sign a push only for the team
       // that published the app, so a ring to a phone is handed to a bell
@@ -331,17 +377,17 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
       // the worlds' pages: always, on the daemon's own door when no route names a public one
       // the bundles the dock's build emitted: read here, because reading a
       // file is the terrain's and a route is handed the code
-      const web = webRoute(harbor, { at, code: await bundles(), folder: diskFolder(harbor.dir), apps: options.apps ?? (await readApps(harbor.dir)), bell: publicOf(key), shown: (n) => DiskHarbor.isShown(harbor.dir, n) });
+      const web = webRoute(harbor, { at, code: await bundles(), folder: diskFolder(harbor.dir), apps: options.apps ?? box.apps, bell: bell.bell, shown: (n) => DiskHarbor.isShown(harbor.dir, n) });
       if (routes) {
         // the worlds a client may be allowed into: every ward here but the
         // dock, which is the box's and nobody's world, by name and pk, the device's own first
         const worlds = () =>
           [...harbor.wards]
-            .filter(([ward]) => ward !== DOCK)
+            .filter(([ward]) => ward !== BOX_SEED)
             .sort(([a], [b]) => (a === harbor.defaultWard ? -1 : b === harbor.defaultWard ? 1 : a.localeCompare(b)))
             .map(([ward, h]) => ({ ward, pk: h.pk, user: h.record.user }));
         // the MCP endpoint: a bearer names an identity in a world, the identity names her avatar there, the side runs beside her
-        mcp = new McpHttp(resolve, async () => {
+        mcp = new McpHttp(findIn, async () => {
           for (const h of harbor.wards.values()) await h.save();
         });
         const route = await mcpRoute(danceOnDisk(harbor.dir), routes, mcp, grants);
@@ -350,7 +396,7 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
         http.mount('/.well-known', route.wellKnown); // the same discovery at the origin's root, where a client looks for an issuer that has a path
         const g = grants;
         mcp.gone = (identity, ward) => g.revoke(identity, ward); // removal at the ward ends the grant at the box
-        exchange = new Exchange({ oauth, worlds, join });
+        exchange = new Exchange({ oauth, worlds, join: joinIn });
       }
       const ex = exchange;
       http.mount(
@@ -363,31 +409,25 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
           (ex && (await ex.handle(req, rest))) ??
           new Response('no such page', { status: 404, headers: { 'content-type': 'text/plain' } }),
       );
+      // Every other path is the box's wire: a faculty that claims it answers.
+      // Mounted last, so every route above is tried first.
+      const wire = await lent<Wire>(harbor, WIRE);
+      if (wire) http.mount('/', (req) => wire.handle(req));
     }
     // the routes this box holds a socket to are rows on the dialers faculty,
     // dialed from her cells at every boot; `dial` is a suite's way of placing one
     for (const url of options.dial ?? []) {
       const kept = dialers.keep({ url });
-      if ('error' in kept) throw new Error(String(kept.error));
+      if ('error' in kept) throw new Error(JSON.stringify(kept.error));
     }
-    dialers.start(harbor);
-    // Which of its wards is the default: the agents and the ward the door
-    // answers for hang off it, and a guess failing in silence is not a way
-    // to find out.
-    harbor.defaultWard = defaultWard(await DiskHarbor.marked(harbor.dir), [...harbor.wards.keys()]);
-    // The agents faculty holds the table; this daemon is what runs a row:
-    // the identity admitted into her ward on the local proof, and the agent
-    // side over her avatar for as long as the daemon serves.
-    agents = facultyOf<Agents>(harbor, AGENTS) ?? null;
+    // Which of its wards is the default: the ward the door answers for hangs
+    // off it, and a guess failing in silence is not a way to find out.
+    harbor.defaultWard = defaultWard(box.default === null ? [] : [box.default], [...harbor.wards.keys()]);
+    agents = (await lent<Agents>(harbor, AGENTS)) ?? null;
     if (!agents) throw new Error('this box has no agents faculty');
-    await agents.start(async (row) => {
-      const hosted = harbor.wards.get(row.ward);
-      if (!hosted) throw new Error(`agent ${row.id}: this device hosts no ward ${row.ward}`);
-      const admitted = await admit(harbor, hosted, row.id);
-      if (!admitted.avatar) throw new Error(`agent ${row.id}: ${admitted.error}`);
-      // a process is the agent side, a model is the runner: both take a push as the event
-      return isProcess(row) ? agentSide(admitted.avatar, processRun(row.command, row.args, row.dir), () => hosted.save()) : runnerSide(admitted.avatar, row, () => {}, () => hosted.save());
-    });
+    // The box is up: the lines are dialed and the agents run, and the daemon
+    // serves once they have.
+    await harbor.box.raise();
   } catch (e) {
     for (const s of servers) s.close();
     await agents?.close();
@@ -411,7 +451,7 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
     // daemon fire what is due right now.
     tick: (now: number) => tick(harbor, now),
     close: async () => {
-      facultyOf<Timer>(harbor, TIMER)?.stop();
+      (await lent<Timer>(harbor, TIMER))?.stop();
       await mcp?.close();
       await agents?.close();
       dialers.close();
@@ -435,7 +475,7 @@ async function sideConnection(harbor: DiskHarbor, c: Socket): Promise<void> {
     const req = JSON.parse(hello) as { as?: string; ward?: string; run?: unknown };
     hosted = harbor.wards.get(req.ward ?? harbor.defaultWard);
     if (!hosted) throw new Error('no such ward');
-    if (typeof req.as !== 'string' || !/^[\w.-]+$/.test(req.as) || req.as === hosted.record.user || req.as === 'desk') throw new Error('as is a word, and not a being of the ward');
+    if (!isIdentity(hosted, req.as)) throw new Error('as is a word, and not a being of the ward');
     as = req.as;
     if (req.run !== undefined) {
       const r = req.run as Partial<Model>;
@@ -527,55 +567,13 @@ async function handle(harbor: DiskHarbor, line: string): Promise<string> {
       }
     }
     const out = await hosted.ask(req.method, req.args ?? {});
-    return JSON.stringify({ id, result: isSilence(out) ? { silence: true } : out });
+    // the ward it landed on, named back, since a request naming none is on the default and the caller may need its name
+    return JSON.stringify({ id, ward: hosted.name, result: isSilence(out) ? { silence: true } : out });
   } catch (e) {
     return JSON.stringify({ id, error: e instanceof Error ? e.message : String(e) });
   }
 }
 
-// The four routes by the one convention: `mcp.`, `web.`, `quo.` and `api.`
-// under one domain, over https. A domain is said once and the names follow;
-// an estate whose names break the convention edits the file it wrote.
-export const DOMAIN = /^[a-z0-9.-]+\.[a-z]{2,}$/i;
-export function routesFor(domain: string): Required<Routes> {
-  if (!DOMAIN.test(domain)) throw new Error(`${domain} is not a domain`);
-  return { mcp: `https://mcp.${domain}`, web: `https://web.${domain}`, quo: `https://quo.${domain}`, api: `https://api.${domain}` };
-}
-export async function writeRoutes(dir: string, domain: string): Promise<Required<Routes>> {
-  const routes = routesFor(domain);
-  await mkdir(dir, { recursive: true });
-  await writeFile(join(dir, 'routes.json'), JSON.stringify(routes) + '\n');
-  return routes;
-}
-
-// `<dir>/routes.json`: { mcp, web, quo?, api? }, the public origins the proxy serves.
-export async function readRoutes(dir: string): Promise<Routes | null> {
-  const p = join(dir, 'routes.json');
-  if (!existsSync(p)) return null;
-  const r = JSON.parse(await readFile(p, 'utf8')) as Partial<Routes>;
-  if (typeof r.mcp !== 'string' || typeof r.web !== 'string') return null;
-  const out: Routes = { mcp: r.mcp.replace(/\/$/, ''), web: r.web.replace(/\/$/, '') };
-  if (typeof r.quo === 'string') out.quo = r.quo.replace(/\/$/, '');
-  if (typeof r.api === 'string') out.api = r.api.replace(/\/$/, '');
-  return out;
-}
-
-// `<dir>/app.json`: { apple: [...], android: [{ package, fingerprints }] }, the
-// apps whose links this world's hostname opens, as the two platforms want
-// them named. An estate that ships no app of its own writes no such file,
-// serves no association file, and its links open the tab.
-export async function readApps(dir: string): Promise<Apps | null> {
-  const p = join(dir, 'app.json');
-  if (!existsSync(p)) return null;
-  const r = JSON.parse(await readFile(p, 'utf8')) as Partial<Apps>;
-  const apple = Array.isArray(r.apple) ? r.apple.filter((x): x is string => typeof x === 'string') : [];
-  const android = Array.isArray(r.android)
-    ? r.android
-        .filter((a) => typeof a?.package === 'string' && Array.isArray(a.fingerprints))
-        .map((a) => ({ package: a.package, fingerprints: a.fingerprints.filter((f): f is string => typeof f === 'string') }))
-    : [];
-  return apple.length === 0 && android.length === 0 ? null : { apple, android };
-}
 
 
 

package/cli/estate.ts

@@ -4,7 +4,7 @@
 // that device runs minus what it mints, its routes under the domain, no
 // agents, no schedules, no classes of its own, and that device's unit and
 // Caddyfile; and `mac/`, the launchd agent that runs the daemon on an
-// operator's Mac as a dialer, with the dial list it holds. A package file
+// operator's Mac as a dialer. A package file
 // that depends on this dock and nothing else, and one document to fill in.
 // An estate needs nothing the dock does not give it, and this is the dock
 // giving it.
@@ -12,7 +12,7 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { DOMAIN, routesFor } from './daemon.ts';
+import { DOMAIN } from '../box/index.ts';
 
 // This package's own version, read beside the emitted or the source tree.
 async function version(): Promise<string> {
@@ -33,7 +33,6 @@ export async function estate(dir: string, domain: string): Promise<{ dir: string
   const files: Record<string, string> = {
     'package.json': JSON.stringify({ name, private: true, description: `The ${name} estate: one owner's harbors, built on the dock and nothing else.`, type: 'module', dependencies: { '@nervur-org/dock': `^${await version()}` } }, null, 2) + '\n',
     [`${name}.md`]: `# ${name}\n\nAn estate: all of one owner's harbors. One folder per harbor, each the harbor\ndirectory that device runs minus what it mints, plus that device's unit.\n\`droplet/\` is the first: its routes under \`${domain}\`, its agents, its\nclasses, its systemd unit and its Caddyfile. This folder depends on the\ndock and nothing else.\n\n## The droplet\n\nWhere it is, how it is reached, and what was done to stand it up: yours\nto write.\n`,
-    'droplet/routes.json': JSON.stringify(routesFor(domain)) + '\n',
     'droplet/stand.ts': `// SPDX-License-Identifier: Apache-2.0\n// What the root stands up on this harbor, once, after the inits and with no\n// daemon over the folder: the beings the estate boots for its own working\n// and the relations between them, placed on real invitations. Run as\n// \`node droplet/stand.ts <dir>\`; twice is once.\nimport { stand } from '@nervur-org/dock/stand';\n\nconsole.log(await stand(process.argv[2] ?? process.env.NERVUR_DIR ?? '', { boot: [], wire: [] }));\n`,
     'droplet/classes/index.ts': '// The classes this harbor holds beside the dock\'s built-in ones, exported\n// by name.\nexport {};\n',
     'droplet/nervur.service': (await template('nervur.service')).replaceAll('ESTATE', name),