nervur 0.20.0 → 0.20.2

package/src/tcp/index.ts

@@ -0,0 +1,284 @@
+// SPDX-License-Identifier: Apache-2.0
+// Quo over TCP: `nervur/tcp`, an entry that names a platform, Node's
+// sockets.
+//
+//   TcpCarrier    a Carrier that dials: bytes to a ward pk go in an ask
+//                 frame to the `tcp://host:port` addresses its book holds
+//                 for that pk, in their order
+//   TcpListener   answers ask frames for the doors it is handed, a harbor
+//                 among them, at a `tcp://` address
+//
+// A connection is opened per address, carries many asks at once, and is
+// dropped when either side closes it; the next ask dials again. An ask
+// goes to the next address only when the one before could not be dialed,
+// since an ask a line took may have been heard.
+import { connect, createServer, type Server, type Socket } from 'node:net';
+import { hex, isHex, unhex } from '../crypto/index.ts';
+import { Carrier } from '../contract/index.ts';
+import { CarrierFaculty, UNDIALED, type Dialed, type Ground, type GroundFaculty } from '../harbor/index.ts';
+import { tcpAddress, tcpAt, type TcpAddress } from '../quo/index.ts';
+import { ownerAsk } from '../ward/index.ts';
+import type { AskSpec, JsonObject } from '../being/index.ts';
+import { askFrame, FrameReader, nothingFrame, replyFrame, TCP, TCP_OPENING } from '../line/index.ts';
+
+// What a listener hands an ask to: bytes for a ward pk, or nothing.
+export interface Doors {
+  arrive(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+}
+
+const MAX_ID = 0xffff_ffff;
+
+// The `tcp` addresses among some, in their order.
+const tcpAddresses = (at: readonly string[]): TcpAddress[] => at.map(tcpAddress).filter((a): a is TcpAddress => a !== null);
+
+class Line {
+  readonly #socket: Socket;
+  readonly #reader = new FrameReader();
+  readonly #waiting = new Map<number, (box: Uint8Array | null) => void>();
+  #next = 1;
+  closed = false;
+
+  constructor(socket: Socket, onClose: () => void) {
+    this.#socket = socket;
+    socket.on('data', (chunk: Buffer) => {
+      for (const f of this.#reader.push(new Uint8Array(chunk))) {
+        if (f.kind === 'ask') continue;
+        const resolve = this.#waiting.get(f.id);
+        this.#waiting.delete(f.id);
+        resolve?.(f.kind === 'reply' ? f.box : null);
+      }
+      if (this.#reader.bad) socket.destroy();
+    });
+    socket.on('error', () => socket.destroy());
+    socket.on('close', () => {
+      this.closed = true;
+      onClose();
+      for (const resolve of this.#waiting.values()) resolve(null);
+      this.#waiting.clear();
+    });
+  }
+
+  static open(host: string, port: number, onClose: () => void): Promise<Line | null> {
+    return new Promise((resolve) => {
+      const socket = connect({ host, port });
+      socket.once('connect', () => resolve(new Line(socket, onClose)));
+      socket.once('error', () => {
+        socket.destroy();
+        resolve(null);
+      });
+    });
+  }
+
+  ask(pk: Uint8Array, box: Uint8Array): Promise<Uint8Array | null> {
+    if (this.closed) return Promise.resolve(null);
+    const id = this.#next;
+    this.#next = this.#next === MAX_ID ? 1 : this.#next + 1;
+    return new Promise((resolve) => {
+      this.#waiting.set(id, resolve);
+      this.#socket.write(askFrame(id, pk, box));
+    });
+  }
+
+  close(): void {
+    this.#socket.destroy();
+  }
+}
+
+export class TcpCarrier extends Carrier {
+  readonly #routes = new Map<string, TcpAddress[]>();
+  readonly #lines = new Map<string, Promise<Line | null>>();
+
+  // Where a ward pk is reached, replacing any route before: its `tcp`
+  // addresses in order, the others skipped. A list with none is not
+  // taken; null forgets the route.
+  route(pk: string, at: readonly string[] | null): boolean {
+    if (!isHex(pk, 64)) return false;
+    if (at === null) return this.#routes.delete(pk) || true;
+    const mine = tcpAddresses(at);
+    if (mine.length === 0) return false;
+    this.#routes.set(pk, mine);
+    return true;
+  }
+
+  // Whether a ward pk has a route.
+  routed(pk: string): boolean {
+    return this.#routes.has(pk);
+  }
+
+  // Nothing where the pk has no route, no address is reached, or the
+  // connection closed before an answer.
+  carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+    return this.#carry(this.#routes.get(pk) ?? [], pk, bytes);
+  }
+
+  // Bytes to a ward pk at the addresses named, as a route would carry them.
+  carryAt(at: readonly string[], pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+    return isHex(pk, 64) ? this.#carry(tcpAddresses(at), pk, bytes) : Promise.resolve(null);
+  }
+
+  async #carry(addresses: readonly TcpAddress[], pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+    for (const address of addresses) {
+      const out = await this.#dial(address, pk, bytes);
+      if (out !== UNDIALED) return out;
+    }
+    return null;
+  }
+
+  // Bytes to a ward pk at one address, or `UNDIALED` where no line opens.
+  dial(at: string, pk: string, bytes: Uint8Array): Promise<Dialed> {
+    const address = tcpAddress(at);
+    return address && isHex(pk, 64) ? this.#dial(address, pk, bytes) : Promise.resolve(UNDIALED);
+  }
+
+  async #dial(address: TcpAddress, pk: string, bytes: Uint8Array): Promise<Dialed> {
+    const line = await this.#line(address);
+    return line ? line.ask(unhex(pk), bytes) : UNDIALED;
+  }
+
+  #line({ host, port }: TcpAddress): Promise<Line | null> {
+    const at = tcpAt(host, port);
+    let line = this.#lines.get(at);
+    if (!line) {
+      line = Line.open(host, port, () => this.#lines.delete(at)).then((dialed) => {
+        if (!dialed) this.#lines.delete(at);
+        return dialed;
+      });
+      this.#lines.set(at, line);
+    }
+    return line;
+  }
+
+  async close(): Promise<void> {
+    const lines = [...this.#lines.values()];
+    this.#lines.clear();
+    for (const line of await Promise.all(lines)) line?.close();
+  }
+}
+
+export class TcpListener {
+  readonly #server: Server;
+  readonly #doors: Doors;
+  readonly #sockets = new Set<Socket>();
+
+  private constructor(doors: Doors) {
+    this.#doors = doors;
+    this.#server = createServer((socket) => this.#serve(socket));
+  }
+
+  // A listener on `host` and `port`, 127.0.0.1 and a free port unless named.
+  static listen(doors: Doors, host = '127.0.0.1', port = 0): Promise<TcpListener> {
+    const listener = new TcpListener(doors);
+    return new Promise((resolve, reject) => {
+      listener.#server.once('error', reject);
+      listener.#server.listen(port, host, () => resolve(listener));
+    });
+  }
+
+  // The `tcp://host:port` address this listener answers at.
+  get at(): string {
+    const address = this.#server.address() as { address: string; port: number };
+    return tcpAt(address.address, address.port);
+  }
+
+  #serve(socket: Socket): void {
+    this.#sockets.add(socket);
+    const reader = new FrameReader();
+    socket.on('data', (chunk: Buffer) => {
+      for (const f of reader.push(new Uint8Array(chunk))) {
+        if (f.kind === 'ask') void this.#answer(socket, f.id, f.pk, f.box);
+      }
+      if (reader.bad) socket.destroy();
+    });
+    socket.on('error', () => socket.destroy());
+    socket.on('close', () => this.#sockets.delete(socket));
+  }
+
+  async #answer(socket: Socket, id: number, pk: Uint8Array, box: Uint8Array): Promise<void> {
+    let reply: Uint8Array | null = null;
+    try {
+      reply = await this.#doors.arrive(hex(pk), box);
+    } catch {
+      reply = null;
+    }
+    if (!socket.destroyed) socket.write(reply === null ? nothingFrame(id) : replyFrame(id, reply));
+  }
+
+  close(): Promise<void> {
+    for (const socket of this.#sockets) socket.destroy();
+    return new Promise((resolve) => this.#server.close(() => resolve()));
+  }
+}
+
+export { TCP, TCP_OPENING };
+
+type Listen = { host: string; port: number };
+const listenOf = (value: unknown): Listen | null => {
+  if (typeof value !== 'object' || value === null) return null;
+  const { host, port } = value as Record<string, unknown>;
+  return typeof host === 'string' && Number.isInteger(port) && (port as number) >= 0 && (port as number) <= 65_535 ? { host, port: port as number } : null;
+};
+
+// Quo over TCP as a carrier faculty of one harbor. It dials every `tcp://`
+// address the harbor routes, and listens where its cells say:
+//
+//   listen  { host?, port? }   listen there from now on, 127.0.0.1 and a
+//                              free port unless named, and on every wake
+//                              at the port it bound
+//   deaf                       listen nowhere from now on
+export const tcpFaculty: GroundFaculty = (ground: Ground) =>
+  class TcpFaculty extends CarrierFaculty {
+    static override readonly kind: string = TCP;
+    static override asks: Record<string, AskSpec> = {
+      listen: ownerAsk('listen for Quo over TCP, and on every wake', { properties: { host: { type: 'string' }, port: { type: 'integer' } } }),
+      deaf: ownerAsk('listen nowhere'),
+    };
+
+    readonly #dialer = new TcpCarrier();
+    #listener: TcpListener | undefined;
+
+    accepts(address: string): boolean {
+      return tcpAddress(address) !== null;
+    }
+
+    dial(address: string, pk: string, bytes: Uint8Array): Promise<Dialed> {
+      return this.#dialer.dial(address, pk, bytes);
+    }
+
+    override listening(): string[] {
+      return this.#listener ? [this.#listener.at] : [];
+    }
+
+    override async awake(): Promise<void> {
+      const at = listenOf(this.cells.listen);
+      if (at && !this.#listener) this.#listener = await TcpListener.listen(ground, at.host, at.port);
+    }
+
+    override async sleep(): Promise<void> {
+      await this.#dialer.close();
+      await this.#listener?.close();
+      this.#listener = undefined;
+    }
+
+    async listen(args: JsonObject): Promise<JsonObject> {
+      const at = listenOf({ host: args.host ?? '127.0.0.1', port: args.port ?? 0 });
+      if (at === null) return { error: 'host is text and port a port' };
+      await this.#listener?.close();
+      this.#listener = undefined;
+      try {
+        this.#listener = await TcpListener.listen(ground, at.host, at.port);
+      } catch (e) {
+        return { error: (e as Error).message };
+      }
+      // The port it bound, so a wake listens where every route and every
+      // invitation already points.
+      this.cells.listen = { host: at.host, port: tcpAddress(this.#listener.at)!.port };
+      return { at: this.#listener.at };
+    }
+
+    async deaf(): Promise<JsonObject> {
+      await this.#listener?.close();
+      this.#listener = undefined;
+      delete this.cells.listen;
+      return { deaf: true };
+    }
+  };

package/src/ward/index.ts

@@ -3,5 +3,6 @@
 export { allow, CEILING, DEFAULT } from './allowance.ts';
 export { HEAD_ROW, Partition, type BeingRow, type Head, type StandingRow } from './partition.ts';
 export { DEPTH } from './stance.ts';
-export { DOCK, Ward, type Catalogue, type Lender, type WardParts } from './ward.ts';
-export { ownerAsk, pilots, WardBeing, type Steward, type WardBeingStance } from './ward-being.ts';
+export { DOCK, Ward, type Catalogue, type Lender, type Routes, type WardParts } from './ward.ts';
+export { ownerAsk, PILOT, pilots, rootAsk, WardBeing, type Steward, type WardBeingStance } from './ward-being.ts';
+export { Pilot } from './pilot.ts';

package/src/ward/pilot.ts

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+// The pilot: a kit being that holds an owner's relation on another ward's
+// ward-being, so whoever pilots her ward pilots that ward from afar. The
+// relation is an ordinary standing, kept in her ward's partition, so it
+// moves its keys and survives a restart like any other.
+//
+//   hold   { invitation }        the owner invitation taken, under `far`
+//   pilot  { method?, args? }    the far ward-being asked, as its owner
+//   drop                         the relation let go
+//
+// She is the kit's, of kind `org.nervur.pilot`, and answers whoever pilots
+// her own ward alone.
+import { Being, isSilence, isWord, told, type AskSpec, type JsonObject } from '../being/index.ts';
+import { readInvitation } from '../quo/index.ts';
+import { ownerAsk, PILOT } from './ward-being.ts';
+
+// The standing id the far ward-being is held under.
+const FAR = 'far';
+
+const object = (v: unknown): v is JsonObject => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+export class Pilot extends Being {
+  static override readonly kind: string = PILOT;
+  static override asks: Record<string, AskSpec> = {
+    hold: ownerAsk('an owner invitation on a far ward, held from now on', { required: ['invitation'] }),
+    pilot: ownerAsk('the far ward-being, asked as its owner'),
+    drop: ownerAsk('the far ward let go'),
+  };
+
+  async hold(args: JsonObject): Promise<JsonObject> {
+    const invitation = readInvitation(args.invitation);
+    if (invitation === null) return { error: 'no invitation' };
+    if (this.stance.standings.get(FAR)) return { error: 'a ward is held' };
+    return (await this.stance.standings.take(FAR, invitation)) === null ? { error: 'not taken' } : { held: invitation.ward };
+  }
+
+  async pilot(args: JsonObject): Promise<JsonObject> {
+    if ((args.method !== undefined && typeof args.method !== 'string') || (args.args !== undefined && !object(args.args))) return { error: 'method is text, args an object' };
+    const standing = this.stance.standings.get(FAR);
+    if (!standing) return { error: 'no ward is held' };
+    const out = await standing.ask(args.method, args.args ?? {});
+    if (isSilence(out)) return { error: 'silence' };
+    if (isWord(out)) return { error: told(out) as string };
+    return { answer: out };
+  }
+
+  drop(): JsonObject {
+    return this.stance.standings.remove(FAR) ? { dropped: true } : { error: 'no ward is held' };
+  }
+}

package/src/ward/stance.ts

@@ -5,7 +5,7 @@
 import { readValue, writeValue } from '../crypto/index.ts';
 import { readInvitation, Standing as Wire, freshStanding, type Door, type Draw, type Invitation, type Read } from '../quo/index.ts';
 import type { Clock } from '../contract/index.ts';
-import { OWNER, silence, word, type Answer, type JsonObject, type Occupants, type Stance, type Standing, type Standings, type Wanted } from '../being/index.ts';
+import { OWNER, ownKind, silence, word, type Answer, type JsonObject, type Occupants, type Stance, type Standing, type Standings, type Wanted } from '../being/index.ts';
 import { allow, Bell, LATE } from './allowance.ts';
 import type { BeingRow, Partition } from './partition.ts';
 import { Cells, DEPTH } from './cells.ts';
@@ -25,6 +25,10 @@ export interface Inside {
   // retraction when the offer was not taken.
   offer(contract: string): Promise<Invitation | null>;
   retract(contract: string, heir: string): Promise<void>;
+  // Where this ward is reached, for the invitations it gives, and where a
+  // ward it takes an invitation of is reached, learned from that `at`.
+  reach(): readonly string[];
+  learn(ward: string, at: readonly string[]): Promise<void>;
 }
 
 const RESERVED = new Set([OWNER]);
@@ -88,16 +92,17 @@ export class WardStance implements Stance {
     return this.#inside.live(this.key, this.#row);
   }
 
-  boot(className: string, key: string, id?: string): Promise<string | null> {
-    return this.#live ? this.#inside.boot(this.key, className, key, id) : Promise.resolve(null);
+  boot(kind: string, key: string, id?: string): Promise<string | null> {
+    return this.#live ? this.#inside.boot(this.key, kind, key, id) : Promise.resolve(null);
   }
 
-  async lend(contract: { readonly name: string }, id: string): Promise<string | null> {
-    if (!this.#free(id, this.#row.standings)) return null;
-    const invitation = await this.#inside.offer(contract.name);
+  async lend(contract: abstract new (...args: never[]) => unknown, id: string): Promise<string | null> {
+    const kind = ownKind(contract);
+    if (kind === undefined || !this.#free(id, this.#row.standings)) return null;
+    const invitation = await this.#inside.offer(kind);
     if (invitation === null) return null;
     const taken = await this.#take(id, invitation);
-    if (taken === null) await this.#inside.retract(contract.name, invitation.heir);
+    if (taken === null) await this.#inside.retract(kind, invitation.heir);
     return taken;
   }
 
@@ -108,7 +113,7 @@ export class WardStance implements Stance {
   async #invite(id: string, notes: JsonObject = {}): Promise<Invitation | null> {
     const kept = writeValue(notes, DEPTH);
     if (!this.#free(id, this.#row.occupants) || kept === undefined) return null;
-    const { heir, invitation } = await this.#inside.door.invite();
+    const { heir, invitation } = await this.#inside.door.invite(this.#inside.reach());
     if (!this.#free(id, this.#row.occupants)) {
       this.#inside.door.remove(heir);
       return null;
@@ -134,6 +139,7 @@ export class WardStance implements Stance {
   async #take(id: string, value: Invitation): Promise<string | null> {
     const invitation = readInvitation(value);
     if (!invitation || !this.#free(id, this.#row.standings)) return null;
+    if (invitation.at) await this.#inside.learn(invitation.ward, invitation.at);
     const wire = new Wire(invitation, freshStanding(), this.#inside.draw);
     const read = await this.#lanes.run(`take:${id}`, async () => {
       // A knock that brought nothing back may have bound: the standing asks

package/src/ward/ward-being.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // The ward-being: the first being of every ward, the ward itself. Her asks
 // are the root's, shown and answered to `OWNER` alone.
-import { Being, isSilence, isWord, OWNER, told, type Answer, type Asker, type AskSpec, type BeingClass, type Blueprint, type Invitation, type JsonObject, type Stance } from '../being/index.ts';
+import { Being, isSilence, isWord, KIT, OWNER, told, type Answer, type Asker, type AskSpec, type BeingClass, type Blueprint, type Invitation, type JsonObject, type Stance } from '../being/index.ts';
 
 // What the ward lends its ward-being, and no other being.
 export interface Steward {
@@ -26,11 +26,16 @@ export const ownerAsk = (description: string, input: JsonObject = {}): AskSpec =
 
 // An ask the root alone may make, so a carried key pilots but never hands
 // piloting on.
-const rootAsk = (description: string, input: JsonObject = {}): AskSpec => ({ description, input: { type: 'object', ...input }, for: (asker: Asker) => asker.id === OWNER });
+export const rootAsk = (description: string, input: JsonObject = {}): AskSpec => ({ description, input: { type: 'object', ...input }, for: (asker: Asker) => asker.id === OWNER });
+// The one kit kind the root boots: every other kit class stands where the
+// kit puts it.
+export const PILOT = 'org.nervur.pilot';
+
 const text = (v: unknown): v is string => typeof v === 'string';
 const object = (v: unknown): v is JsonObject => typeof v === 'object' && v !== null && !Array.isArray(v);
 
 export class WardBeing extends Being {
+  static override readonly kind: string = 'org.nervur.ward-being';
   static override asks: Record<string, AskSpec> = {
     boot: ownerAsk('a new being of this ward', { required: ['key', 'class'] }),
     unboot: ownerAsk('a being out, with every relation she holds', { required: ['being'] }),
@@ -66,11 +71,12 @@ export class WardBeing extends Being {
 
   async boot(args: JsonObject): Promise<JsonObject> {
     if (!text(args.key) || !text(args.class)) return { error: 'key and class are text' };
+    if (args.class.startsWith(KIT) && args.class !== PILOT) return { error: 'no such class' };
     const out = await this.steward.boot(args.key, args.class);
     return out === 'booted' ? { booted: args.key } : { error: out };
   }
 
-  unboot(args: JsonObject): JsonObject {
+  unboot(args: JsonObject): JsonObject | Promise<JsonObject> {
     return text(args.being) && this.steward.unboot(args.being) ? { unbooted: args.being } : { error: 'no such being' };
   }
 

package/src/ward/ward.ts

@@ -6,14 +6,14 @@
 import { readValue, writeValue } from '../crypto/index.ts';
 import { Door, readInvitation, WardKey, type Behind, type Choice, type Invitation, type Payload } from '../quo/index.ts';
 import type { Carrier, Clock, Entropy, Rows } from '../contract/index.ts';
-import { digest, isSilence, isWord, OWNER, silence, WARD, word, type Answer, type Asker, type BeingClass, type BeingLike, type JsonObject, type Reply } from '../being/index.ts';
+import { digest, isSilence, isWord, kindOf, OWNER, silence, WARD, word, type Answer, type Asker, type BeingClass, type BeingLike, type JsonObject, type Reply } from '../being/index.ts';
 import { Partition, PartitionRelations, type BeingRow } from './partition.ts';
 import { DEPTH, WardStance, type Inside } from './stance.ts';
 import { WardBeing, type Steward, type WardBeingStance } from './ward-being.ts';
 
-// Where a ward finds a class by the name its row keeps.
+// Where a ward finds a class by the kind its row keeps.
 export interface Catalogue {
-  classOf(name: string): BeingClass | undefined;
+  classOf(kind: string): BeingClass | undefined;
 }
 
 export type WardParts = {
@@ -28,8 +28,16 @@ export type WardParts = {
   // An invitation on the dock, taken by the ward-being under `dock` when
   // she holds no such standing yet.
   readonly dock?: Invitation;
+  // Where the ward is reached, and where a ward it takes an invitation of
+  // is reached. A ward alone is reached nowhere and learns nothing.
+  readonly routes?: Routes;
 };
 
+export interface Routes {
+  reach(): readonly string[];
+  learn(ward: string, at: readonly string[]): Promise<void>;
+}
+
 // The standing every hosted ward's ward-being holds on the dock.
 export const DOCK = 'dock';
 
@@ -81,9 +89,13 @@ export class Ward implements Behind, Inside {
     const own = ward.partition.being(WARD)!;
     const stance = new RootStance(ward, own, ward.#steward);
     const being = parts.root ? parts.root(stance) : new WardBeing(stance);
-    own.class = being.constructor.name;
+    own.class = kindOf(being.constructor);
     ward.#residents.set(WARD, { being, row: own, stance });
-    if (parts.dock && !Object.hasOwn(own.standings, DOCK)) await stance.standings.take(DOCK, parts.dock);
+    // The standing on the dock is kept at once: its heir is spent, so a
+    // restart before the ward's first keep would find no way back.
+    if (parts.dock && !Object.hasOwn(own.standings, DOCK) && (await stance.standings.take(DOCK, parts.dock)) !== null && !(await ward.partition.kept())) {
+      throw new Error('the standing on the dock was not kept');
+    }
     for (const [key, row] of Object.entries(ward.partition.beings)) {
       const C = key === WARD ? undefined : parts.catalogue.classOf(row.class);
       if (C) ward.#bear(key, row, C);
@@ -103,6 +115,33 @@ export class Ward implements Behind, Inside {
     return this.#residents.get(WARD)!.being as WardBeing;
   }
 
+  // The being standing under a key, for the harbor's own faculties.
+  being(key: string): BeingLike | undefined {
+    return this.#residents.get(key)?.being;
+  }
+
+  // Every being her row names, of the class the catalogue now resolves for
+  // her kind: an absent being is born, and one whose class a module
+  // replaced is born again of the new class on the stance she holds, so
+  // her relations and their lanes stay hers. A new class that throws at
+  // birth leaves her as she was.
+  bearAnew(): void {
+    for (const [key, row] of Object.entries(this.partition.beings)) {
+      const C = key === WARD ? undefined : this.#parts.catalogue.classOf(row.class);
+      const resident = this.#residents.get(key);
+      if (!C || resident?.being.constructor === C) continue;
+      if (!resident) {
+        this.#bear(key, row, C);
+        continue;
+      }
+      try {
+        resident.being = new C(resident.stance);
+      } catch {
+        continue;
+      }
+    }
+  }
+
   // The unsealed ask: the ward-being, asked by whoever holds this ward.
   async root(method?: string, args: JsonObject = {}): Promise<Answer> {
     return this.#kept(WARD, () => this.#answer(WARD, { id: OWNER }, method, args));
@@ -124,7 +163,7 @@ export class Ward implements Behind, Inside {
     return silence;
   }
 
-  // Behind: the zero head reaches the public being, a heir the being that
+  // Behind: the zero head reaches the public being, an heir the being that
   // invited it.
   get zero(): boolean {
     const key = this.partition.head.public;
@@ -182,6 +221,14 @@ export class Ward implements Behind, Inside {
     await own.stance.standings.get(DOCK)?.ask('retract', { contract, heir });
   }
 
+  reach(): readonly string[] {
+    return this.#parts.routes?.reach() ?? [];
+  }
+
+  learn(ward: string, at: readonly string[]): Promise<void> {
+    return this.#parts.routes?.learn(ward, at) ?? Promise.resolve();
+  }
+
   live(key: string, row: BeingRow): boolean {
     return this.#residents.get(key)?.row === row;
   }