nervur 0.20.0 → 0.20.2

package/src/harbor/package.ts

@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: Apache-2.0
+// The package: a harbor's memory, sealed under the harbor's seed. The
+// terrain keeps its bytes and reads neither a ward's name, nor a being's
+// key, nor anything a row holds.
+//
+//   key            HKDF-SHA-256 of the seed under `nervur-package`
+//   place          16 bytes under ["place", ward], as hex
+//   entry          16 bytes under ["entry", ward, row], as hex
+//   seal           32 bytes under ["seal", ward]
+//   entry bytes    nonce (12) || AES-256-GCM( JSON { row, value } ),
+//                  the entry's name as additional data
+//
+// A row is the head, under the empty name, or one being, under her key. An
+// entry that does not open refuses the whole ward, so nothing unpacks from
+// bytes the package did not seal.
+import { concat, decrypt, encrypt, hex, hkdf, utf8 } from '../crypto/index.ts';
+import type { Entropy, Memory, Rows } from '../contract/index.ts';
+import { HEAD_ROW } from '../ward/index.ts';
+
+// Every place of one memory, written into another, and the places
+// carried. The bytes are the package's own, sealed under a seed neither
+// memory holds, so a harbor opened on the second memory under that seed
+// stands what the first one stood. A place the second memory already
+// holds is written over.
+export const copyPackage = async (from: Memory, to: Memory): Promise<string[]> => {
+  const places = await from.places();
+  for (const place of places) await to.write(place, await from.read(place));
+  return places;
+};
+
+const NONCE = 12;
+const LABEL = utf8('nervur-package');
+
+type Sealed = { row: string; value: unknown };
+
+class PackageRows implements Rows {
+  readonly rows: Record<string, unknown>;
+  readonly #ward: Ward;
+  readonly #told = new Set<string>();
+  #line: Promise<boolean> = Promise.resolve(true);
+
+  constructor(ward: Ward, rows: Record<string, unknown>) {
+    this.#ward = ward;
+    this.rows = rows;
+  }
+
+  told(row: string): void {
+    this.#told.add(row);
+  }
+
+  // Every row told since the last keep, sealed and written as one keep, one
+  // keep at a time.
+  kept(): Promise<boolean> {
+    const rows = [...this.#told];
+    this.#told.clear();
+    this.#line = this.#line.then(() => this.#write(rows)).catch(() => false);
+    return this.#line;
+  }
+
+  async #write(told: string[]): Promise<boolean> {
+    const beings = (this.rows.beings ?? {}) as Record<string, unknown>;
+    const entries = new Map<string, Uint8Array | null>();
+    for (const row of told) {
+      const value = row === HEAD_ROW ? (this.rows.ward ?? null) : Object.hasOwn(beings, row) ? beings[row] : undefined;
+      entries.set(await this.#ward.entry(row), value === undefined ? null : await this.#ward.seal(row, value));
+    }
+    await this.#ward.write(entries);
+    return true;
+  }
+}
+
+class Ward {
+  readonly #pack: Package;
+  readonly #name: string;
+  readonly #seal: Uint8Array;
+  readonly place: string;
+
+  constructor(pack: Package, name: string, seal: Uint8Array, place: string) {
+    this.#pack = pack;
+    this.#name = name;
+    this.#seal = seal;
+    this.place = place;
+  }
+
+  entry(row: string): Promise<string> {
+    return this.#pack.derive(['entry', this.#name, row], 16).then(hex);
+  }
+
+  async seal(row: string, value: unknown): Promise<Uint8Array> {
+    const nonce = this.#pack.entropy.draw(NONCE);
+    const text = utf8(JSON.stringify({ row, value } satisfies Sealed));
+    return concat(nonce, await encrypt(this.#seal, nonce, utf8(await this.entry(row)), text));
+  }
+
+  // The name is the additional data, so an entry moved under another name
+  // does not open either.
+  async open(name: string, bytes: Uint8Array): Promise<Sealed> {
+    const text = bytes.length > NONCE ? await decrypt(this.#seal, bytes.subarray(0, NONCE), utf8(name), bytes.subarray(NONCE)) : null;
+    if (text === null) throw new Error('an entry the package did not seal');
+    return JSON.parse(new TextDecoder().decode(text)) as Sealed;
+  }
+
+  write(entries: ReadonlyMap<string, Uint8Array | null>): Promise<void> {
+    return this.#pack.memory.write(this.place, entries);
+  }
+}
+
+export class Package {
+  readonly memory: Memory;
+  readonly entropy: Entropy;
+  readonly #key: Uint8Array;
+
+  private constructor(memory: Memory, entropy: Entropy, key: Uint8Array) {
+    this.memory = memory;
+    this.entropy = entropy;
+    this.#key = key;
+  }
+
+  static async open(memory: Memory, entropy: Entropy, seed: Uint8Array): Promise<Package> {
+    return new Package(memory, entropy, await hkdf(seed, LABEL, 32));
+  }
+
+  derive(info: string[], length: number): Promise<Uint8Array> {
+    return hkdf(this.#key, utf8(JSON.stringify(info)), length);
+  }
+
+  // The place a ward's rows live in.
+  place(name: string): Promise<string> {
+    return this.derive(['place', name], 16).then(hex);
+  }
+
+  // One ward's rows, as the package kept them.
+  async rows(name: string): Promise<Rows> {
+    const ward = new Ward(this, name, await this.derive(['seal', name], 32), hex(await this.derive(['place', name], 16)));
+    const rows: Record<string, unknown> = {};
+    const beings: Record<string, unknown> = {};
+    let any = false;
+    for (const [entry, bytes] of await this.memory.read(ward.place)) {
+      const { row, value } = await ward.open(entry, bytes);
+      any = true;
+      if (row === HEAD_ROW) rows.ward = value;
+      else beings[row] = value;
+    }
+    if (any) rows.beings = beings;
+    return new PackageRows(ward, rows);
+  }
+}

package/src/harbor/probe.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+// The ground probe: `Harbor.open()` with no terrain asks each ground an
+// entry knows whether it fits here, the one added last first, and opens on
+// the terrain the first that fits makes. The main entry adds a ground that
+// fits everywhere; an entry that names a platform adds its own.
+import type { Module } from '../contract/index.ts';
+import type { Terrain } from './terrain.ts';
+
+// What a probed harbor is told: the modules its code holds, where it keeps
+// itself, as its ground reads a place, and what the engine handed the
+// code, such as an edge's object state and environment.
+export type Probing = { readonly modules?: readonly Module[]; readonly where?: string; readonly given?: unknown };
+
+export type GroundProbe = {
+  readonly name: string;
+  fits(probing: Probing): boolean;
+  terrain(probing: Probing): Terrain;
+};
+
+const known: GroundProbe[] = [];
+
+// A ground this process can stand on, known once by its name.
+export const addGround = (probe: GroundProbe): void => {
+  if (!known.some((k) => k.name === probe.name)) known.push(probe);
+};
+
+// The grounds known, in the order they are tried.
+export const grounds = (): string[] => known.map((k) => k.name).reverse();
+
+// The terrain of the first ground that fits, and its name.
+export const probeGround = (probing: Probing, probes: readonly GroundProbe[] = known): { ground: string; terrain: Terrain } => {
+  for (const probe of [...probes].reverse()) if (probe.fits(probing)) return { ground: probe.name, terrain: probe.terrain(probing) };
+  throw new Error('no ground fits here');
+};

package/src/harbor/registry.ts

@@ -1,20 +1,84 @@
 // SPDX-License-Identifier: Apache-2.0
-// The catalogue a program hands its harbor, indexed by class name. It
-// resolves a name a row keeps, and decides nothing about what stands.
-import type { BeingClass } from '../being/index.ts';
+// The catalogue's index: every kind the harbor runs, from the kit's own
+// classes and the modules the catalogue loaded. It resolves a kind a row
+// keeps, and decides nothing about what stands. It refuses any set of
+// modules two readings could split:
+//
+//   a module whose name is no kind, or is the kit's, or two of one name
+//   a class with no kind of its own, or one outside its module's domain
+//   two classes of one kind, or one kind in two modules
+//   a contract with no kind of its own, or one kind for two contracts
+//   a kind that is a class and a contract
+//
+// A module's domain is its name's first two segments: `com.acme.shop`
+// stands classes under `com.acme.` alone. A contract may be any domain's,
+// so a faculty fulfils a contract another module declares. Two harbors hold
+// two registries, and nothing between them names a class.
+import { Faculty, isKind, KIT, kindOf, type BeingClass } from '../being/index.ts';
+import type { Module } from '../contract/index.ts';
 import type { Catalogue } from '../ward/index.ts';
 
+const domainOf = (name: string): string => `${name.split('.').slice(0, 2).join('.')}.`;
+
 export class Registry implements Catalogue {
   readonly #classes = new Map<string, BeingClass>();
+  readonly #modules = new Map<string, string[]>();
 
-  constructor(classes: readonly BeingClass[]) {
-    for (const C of classes) {
-      if (this.#classes.has(C.name) && this.#classes.get(C.name) !== C) throw new Error(`two classes are named ${C.name}`);
-      this.#classes.set(C.name, C);
+  // `kit` holds the kit's own classes, which alone may be of its kinds.
+  constructor(kit: readonly BeingClass[], modules: readonly Module[]) {
+    const contracts = new Map<string, unknown>();
+    const owners = new Map<string, string>();
+    const add = (C: BeingClass, kind: string): void => {
+      if (this.#classes.has(kind) && this.#classes.get(kind) !== C) throw new Error(`two classes are of kind ${kind}`);
+      this.#classes.set(kind, C);
+    };
+    for (const C of kit) add(C, kindOf(C));
+    for (const m of modules) {
+      if (!isKind(m.module) || m.module.startsWith(KIT)) throw new Error(`module ${String(m.module)} is no name a module may take`);
+      if (this.#modules.has(m.module)) throw new Error(`two modules are named ${m.module}`);
+      if (typeof m.version !== 'string' || m.version === '') throw new Error(`module ${m.module} declares no version`);
+      const kinds: string[] = [];
+      for (const C of m.classes) {
+        if (typeof C !== 'function') throw new Error(`module ${m.module} holds something that is no class`);
+        const kind = kindOf(C);
+        if (!kind.startsWith(domainOf(m.module))) throw new Error(`kind ${kind} is outside module ${m.module}`);
+        const owner = owners.get(kind);
+        if (owner !== undefined && owner !== m.module) throw new Error(`kind ${kind} is in modules ${owner} and ${m.module}`);
+        owners.set(kind, m.module);
+        add(C as BeingClass, kind);
+        kinds.push(kind);
+        if (!Faculty.fulfils(C)) continue;
+        for (let c: unknown = Object.getPrototypeOf(C); c !== Faculty; c = Object.getPrototypeOf(c)) {
+          const contract = kindOf(c);
+          if (contract.startsWith(KIT)) throw new Error(`kind ${contract} is the kit's`);
+          if (contracts.has(contract) && contracts.get(contract) !== c) throw new Error(`two contracts are of kind ${contract}`);
+          contracts.set(contract, c);
+        }
+      }
+      this.#modules.set(m.module, kinds);
+    }
+    for (const kind of contracts.keys()) {
+      if (this.#classes.has(kind)) throw new Error(`kind ${kind} is a class and a contract`);
     }
   }
 
-  classOf(name: string): BeingClass | undefined {
-    return this.#classes.get(name);
+  // Why a registry of these modules would be refused, or null.
+  static refusal(kit: readonly BeingClass[], modules: readonly Module[]): string | null {
+    try {
+      const registry = new Registry(kit, modules);
+      void registry;
+      return null;
+    } catch (e) {
+      return (e as Error).message;
+    }
+  }
+
+  classOf(kind: string): BeingClass | undefined {
+    return this.#classes.get(kind);
+  }
+
+  // The kinds a module stands, or none.
+  kindsOf(module: string): string[] {
+    return [...(this.#modules.get(module) ?? [])];
   }
 }

package/src/harbor/relay.ts

@@ -0,0 +1,399 @@
+// SPDX-License-Identifier: Apache-2.0
+// The relay: a harbor nobody dials is reached through a harbor that is,
+// by relations alone. Both sides are kit faculties, opened by the root.
+//
+// On the reached harbor, `org.nervur.relay`:
+//
+//   invite   { id, wards }        a relay client invited under `id`, its
+//                                 notes naming the ward pks it collects for
+//   release  { id }               that client let go, and every box waiting
+//                                 for its wards answered with nothing
+//   collect  { replies?, wait? }  asked by a client: the replies to the boxes
+//                                 it took last, handed to their callers, then
+//                                 the boxes waiting for its wards; with
+//                                 `wait`, it waits for one first
+//   bell     { endpoint }         asked by a client: the push endpoint rung
+//                                 when a box waits for it, or null for none
+//   key                           asked by a client: the key its device
+//                                 subscribes to pushes with
+//
+// A box for a ward a client collects for reaches this harbor on any
+// carrier, and the caller's dial waits for its reply, or for nothing once
+// `RELAY_WAIT` passes. No box is opened here. A box no waiting collect
+// takes rings the client's bell once, through a `Push` faculty the relay
+// lends, until the client collects again.
+//
+// On the harbor nobody dials, `org.nervur.relay-client`:
+//
+//   hold  { invitation, line?, every? }  the relay's invitation taken; a
+//                                        line collects always, `every`
+//                                        rings on a schedule, in ms
+//   ring                                 every waiting box collected, handed
+//                                        to this harbor's doors, and the
+//                                        replies returned: a doorbell
+//   bell  { endpoint }                   the relay's `bell`, asked
+//   key                                  the relay's `key`, asked
+//   drop                                 the relay let go
+//
+// Its harbor's `reach` names the relay's address, so every invitation it
+// gives sends callers there. Whatever hears a push on the device asks
+// `ring`.
+import { Faculty, isSilence, isWord, told, type Asker, type AskSpec, type BeingClass, type JsonObject } from '../being/index.ts';
+import type { Clock } from '../contract/index.ts';
+import { hex, isHex, unhex } from '../crypto/index.ts';
+import { readInvitation } from '../quo/index.ts';
+import { ownerAsk } from '../ward/index.ts';
+import { CarrierFaculty, UNDIALED, type Dialed, type Ground } from './carrying.ts';
+
+export const RELAY = 'org.nervur.relay';
+export const RELAY_CLIENT = 'org.nervur.relay-client';
+export const PUSH = 'org.nervur.push';
+// How long a box waits for its reply: a caller's allowance, unless it
+// asks for another.
+export const RELAY_WAIT = 30_000;
+// How long a collect with `wait` holds, inside the client's allowance.
+export const RELAY_HOLD = 20_000;
+// How long a line rests after a collect that reached nothing.
+export const RELAY_REST = 1_000;
+// The largest box a relay carries, so the collect answering it stays a
+// box Quo carries.
+export const RELAYED = 262_144;
+// The longest push endpoint a relay keeps.
+const ENDPOINT = 2_048;
+// The most boxes one collect hands over.
+const BATCH = 16;
+const CLIENT = 'relay';
+const PUSHER = 'push';
+
+// The contract of a ring with no content: `key` answers the key a device
+// subscribes with, and `ring { endpoint }` answers `rung`, `gone` where
+// the push service has let the endpoint go, or an error.
+export abstract class Push extends Faculty {
+  static override readonly kind: string = PUSH;
+}
+
+type Waiting = { n: number; ward: string; bytes: Uint8Array; answer: (reply: Uint8Array | null) => void; cancel: () => void; collector?: string };
+type Collector = { wards: readonly string[]; wake: () => void };
+type Reply = { n: number; box: string | null };
+
+const text = (v: unknown): v is string => typeof v === 'string';
+const wardsOf = (notes: JsonObject | undefined): string[] => (Array.isArray(notes?.relay) ? notes.relay.filter(text) : []);
+const collects: AskSpec['for'] = (_: Asker, notes) => wardsOf(notes).length > 0;
+const clientAsk = (description: string, input: JsonObject = {}): AskSpec => ({ description, input: { type: 'object', ...input }, for: collects });
+const readReplies = (v: unknown): Reply[] | null =>
+  v === undefined
+    ? []
+    : Array.isArray(v) && v.every((r) => typeof r === 'object' && r !== null && Number.isInteger((r as Reply).n) && ((r as Reply).box === null || isHex((r as Reply).box, ((r as Reply).box ?? '').length / 2)))
+      ? (v as Reply[])
+      : null;
+// An answer, or the error it stands for.
+const answered = (out: unknown): JsonObject => (isSilence(out) ? { error: 'silence' } : isWord(out) ? { error: told(out) as string } : (out as JsonObject));
+
+export const relayFaculty = (clock: Clock): BeingClass =>
+  class Relay extends CarrierFaculty {
+    static override readonly kind: string = RELAY;
+    static override cells: JsonObject = { clients: {}, bells: {} };
+    static override asks: Record<string, AskSpec> = {
+      invite: ownerAsk('a relay client, collecting for the ward pks named', { required: ['id', 'wards'] }),
+      release: ownerAsk('a relay client let go', { required: ['id'] }),
+      collect: clientAsk('the replies to the boxes taken last, then the boxes waiting'),
+      bell: clientAsk('the push endpoint rung when a box waits, or null', { required: ['endpoint'] }),
+      key: clientAsk('the key a device subscribes to pushes with'),
+    };
+
+    #n = 0;
+    readonly #waiting: Waiting[] = [];
+    readonly #taken = new Map<number, Waiting>();
+    readonly #collectors = new Set<Collector>();
+    // The clients rung since they last collected.
+    readonly #rung = new Set<string>();
+    #lending: Promise<string | null> | undefined;
+
+    accepts(): boolean {
+      return false;
+    }
+
+    dial(): Promise<Dialed> {
+      return Promise.resolve(UNDIALED);
+    }
+
+    get #clients(): Record<string, string[]> {
+      return this.cells.clients as Record<string, string[]>;
+    }
+
+    get #bells(): Record<string, string> {
+      return this.cells.bells as Record<string, string>;
+    }
+
+    override relays(pk: string): boolean {
+      return Object.values(this.#clients).some((wards) => wards.includes(pk));
+    }
+
+    override relay(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+      if (!this.relays(pk) || bytes.length > RELAYED) return Promise.resolve(null);
+      return new Promise((resolve) => {
+        const wait = clock.wait(RELAY_WAIT);
+        const box: Waiting = { n: ++this.#n, ward: pk, bytes, answer: resolve, cancel: wait.cancel };
+        void wait.done.then(() => this.#settle(box, null));
+        this.#waiting.push(box);
+        let woken = false;
+        for (const collector of this.#collectors) {
+          if (!collector.wards.includes(pk)) continue;
+          collector.wake();
+          woken = true;
+        }
+        if (woken) return;
+        for (const [id, wards] of Object.entries(this.#clients)) {
+          if (!wards.includes(pk) || !Object.hasOwn(this.#bells, id) || this.#rung.has(id)) continue;
+          this.#rung.add(id);
+          void this.#ring(id);
+        }
+      });
+    }
+
+    // Every box answered with nothing, and every collect woken.
+    override sleep(): Promise<void> {
+      for (const box of [...this.#waiting, ...this.#taken.values()]) this.#settle(box, null);
+      for (const collector of this.#collectors) collector.wake();
+      return Promise.resolve();
+    }
+
+    async invite(args: JsonObject): Promise<JsonObject> {
+      const { id, wards } = args;
+      if (!text(id) || !Array.isArray(wards) || wards.length === 0 || !wards.every((w) => isHex(w, 64))) return { error: 'id is text and wards a list of ward pks' };
+      if (Object.hasOwn(this.#clients, id)) return { error: 'that client is invited' };
+      const invitation = await this.stance.occupants.invite(id, { relay: wards });
+      if (invitation === null) return { error: 'not invited' };
+      this.#clients[id] = [...(wards as string[])];
+      return { invitation };
+    }
+
+    release(args: JsonObject): JsonObject {
+      if (!text(args.id) || !Object.hasOwn(this.#clients, args.id)) return { error: 'no such client' };
+      this.stance.occupants.remove(args.id);
+      delete this.#clients[args.id];
+      delete this.#bells[args.id];
+      this.#rung.delete(args.id);
+      for (const box of [...this.#waiting, ...this.#taken.values()]) if (!this.relays(box.ward)) this.#settle(box, null);
+      return { released: args.id };
+    }
+
+    async collect(args: JsonObject, asker: Asker): Promise<JsonObject> {
+      const replies = readReplies(args.replies);
+      if (replies === null) return { error: 'replies are a list of { n, box }' };
+      const id = asker.id!;
+      this.#rung.delete(id);
+      for (const { n, box } of replies) {
+        const taken = this.#taken.get(n);
+        if (taken?.collector === id) this.#settle(taken, box === null ? null : unhex(box));
+      }
+      const wards = wardsOf(this.notes(asker));
+      if (args.wait === true && !this.#waiting.some((b) => wards.includes(b.ward))) await this.#hold(wards);
+      const boxes = this.#waiting.filter((b) => wards.includes(b.ward)).slice(0, BATCH);
+      for (const box of boxes) {
+        this.#waiting.splice(this.#waiting.indexOf(box), 1);
+        box.collector = id;
+        this.#taken.set(box.n, box);
+      }
+      return { boxes: boxes.map(({ n, ward, bytes }) => ({ n, ward, box: hex(bytes) })) };
+    }
+
+    bell(args: JsonObject, asker: Asker): JsonObject {
+      const { endpoint } = args;
+      const id = asker.id!;
+      if (endpoint === null) {
+        delete this.#bells[id];
+        return { bell: null };
+      }
+      if (!text(endpoint) || endpoint.length > ENDPOINT || !/^https?:\/\//.test(endpoint)) return { error: 'endpoint is a web URL, or null' };
+      this.#bells[id] = endpoint;
+      return { bell: endpoint };
+    }
+
+    async key(): Promise<JsonObject> {
+      const push = await this.#push();
+      return push ? answered(await push.ask('key')) : { error: 'no push faculty is open' };
+    }
+
+    // The client's bell rung. An endpoint the push service calls gone is
+    // forgotten, and kept at the relay's next arrival.
+    async #ring(id: string): Promise<void> {
+      const push = await this.#push();
+      const endpoint = this.#bells[id];
+      if (!push || endpoint === undefined) return;
+      const out = answered(await push.ask('ring', { endpoint }));
+      if (out.gone === true && this.#bells[id] === endpoint) delete this.#bells[id];
+    }
+
+    async #push() {
+      if (!this.stance.standings.get(PUSHER)) {
+        this.#lending ??= this.stance.lend(Push, PUSHER).finally(() => (this.#lending = undefined));
+        await this.#lending;
+      }
+      return this.stance.standings.get(PUSHER);
+    }
+
+    #hold(wards: readonly string[]): Promise<void> {
+      return new Promise((resolve) => {
+        const wait = clock.wait(RELAY_HOLD);
+        const collector: Collector = {
+          wards,
+          wake: () => {
+            wait.cancel();
+            this.#collectors.delete(collector);
+            resolve();
+          },
+        };
+        this.#collectors.add(collector);
+        void wait.done.then(collector.wake);
+      });
+    }
+
+    #settle(box: Waiting, reply: Uint8Array | null): void {
+      box.cancel();
+      const at = this.#waiting.indexOf(box);
+      if (at >= 0) this.#waiting.splice(at, 1);
+      this.#taken.delete(box.n);
+      box.answer(reply);
+    }
+  };
+
+export const relayClient = (ground: Ground, clock: Clock): BeingClass =>
+  class RelayClient extends CarrierFaculty {
+    static override readonly kind: string = RELAY_CLIENT;
+    static override asks: Record<string, AskSpec> = {
+      hold: ownerAsk("a relay's invitation, collected from on a line, a schedule or a ring", { required: ['invitation'] }),
+      ring: ownerAsk('every waiting box collected and answered now'),
+      bell: ownerAsk('the push endpoint the relay rings, or null', { required: ['endpoint'] }),
+      key: ownerAsk('the key this device subscribes to pushes with'),
+      drop: ownerAsk('the relay let go'),
+    };
+
+    #awake = false;
+    #replies: Reply[] = [];
+    // Ends every rest and schedule when the client sleeps or lets go.
+    #stop: () => void = () => {};
+
+    accepts(): boolean {
+      return false;
+    }
+
+    dial(): Promise<Dialed> {
+      return Promise.resolve(UNDIALED);
+    }
+
+    override awake(): Promise<void> {
+      if (!this.#awake) {
+        this.#awake = true;
+        this.#start();
+      }
+      return Promise.resolve();
+    }
+
+    override sleep(): Promise<void> {
+      this.#awake = false;
+      this.#stop();
+      return Promise.resolve();
+    }
+
+    async hold(args: JsonObject): Promise<JsonObject> {
+      const invitation = readInvitation(args.invitation);
+      const { line, every } = args;
+      if (invitation === null || (line !== undefined && typeof line !== 'boolean') || (every !== undefined && !(Number.isInteger(every) && (every as number) > 0))) {
+        return { error: 'an invitation, line a boolean and every a positive integer' };
+      }
+      if (this.stance.standings.get(CLIENT)) return { error: 'a relay is held' };
+      if ((await this.stance.standings.take(CLIENT, invitation)) === null) return { error: 'not taken' };
+      this.cells.line = line === true;
+      if (every !== undefined) this.cells.every = every;
+      this.#start();
+      return { held: invitation.ward };
+    }
+
+    async ring(): Promise<JsonObject> {
+      if (!this.stance.standings.get(CLIENT)) return { error: 'no relay is held' };
+      let carried = 0;
+      for (;;) {
+        const sent = this.#replies.length;
+        const got = await this.#collect(false);
+        if (got === null) return { error: 'the relay was not reached', carried };
+        carried += got;
+        if (got === 0 && sent === 0) return { carried };
+      }
+    }
+
+    bell(args: JsonObject): Promise<JsonObject> {
+      return this.#relay('bell', { endpoint: args.endpoint ?? null });
+    }
+
+    key(): Promise<JsonObject> {
+      return this.#relay('key');
+    }
+
+    drop(): JsonObject {
+      if (!this.stance.standings.remove(CLIENT)) return { error: 'no relay is held' };
+      delete this.cells.line;
+      delete this.cells.every;
+      this.#stop();
+      return { dropped: true };
+    }
+
+    async #relay(method: string, args: JsonObject = {}): Promise<JsonObject> {
+      const standing = this.stance.standings.get(CLIENT);
+      return standing ? answered(await standing.ask(method, args)) : { error: 'no relay is held' };
+    }
+
+    #start(): void {
+      if (!this.#awake || !this.stance.standings.get(CLIENT)) return;
+      this.#stop();
+      let stopped = false;
+      const rests = new Set<() => void>();
+      this.#stop = () => {
+        stopped = true;
+        for (const end of rests) end();
+      };
+      const rest = (ms: number): Promise<void> =>
+        new Promise((resolve) => {
+          const wait = clock.wait(ms);
+          const end = () => {
+            wait.cancel();
+            rests.delete(end);
+            resolve();
+          };
+          rests.add(end);
+          void wait.done.then(end);
+        });
+      const going = () => !stopped && this.stance.standings.get(CLIENT) !== undefined;
+      if (this.cells.line === true) {
+        void (async () => {
+          while (going()) if ((await this.#collect(true)) === null && going()) await rest(RELAY_REST);
+        })();
+      }
+      const every = this.cells.every as number | undefined;
+      if (every !== undefined) {
+        void (async () => {
+          for (await rest(every); going(); await rest(every)) await this.ring();
+        })();
+      }
+    }
+
+    // One collect: the replies owed go with it, and each box it brings is
+    // handed to this harbor's doors. The number of boxes, or null where the
+    // relay was not reached.
+    async #collect(wait: boolean): Promise<number | null> {
+      const standing = this.stance.standings.get(CLIENT);
+      if (!standing) return null;
+      const replies = this.#replies.splice(0);
+      const out = await standing.ask('collect', { replies, wait });
+      const boxes = !isSilence(out) && !isWord(out) && Array.isArray((out as JsonObject).boxes) ? ((out as JsonObject).boxes as JsonObject[]) : null;
+      if (boxes === null) {
+        this.#replies.unshift(...replies);
+        return null;
+      }
+      for (const { n, ward, box } of boxes) {
+        const reply = text(ward) && text(box) && isHex(box, box.length / 2) ? await ground.arrive(ward, unhex(box)) : null;
+        this.#replies.push({ n: n as number, box: reply === null ? null : hex(reply) });
+      }
+      return boxes.length;
+    }
+  };