nervur 0.20.0 → 0.20.2

package/dist/quo/address.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+// Addresses, as `SPEC.md` names them in an invitation's `at`: a URI of
+// RFC 3986 whose scheme, read in any case, names a carrier.
+// `CARRIER-TCP.md` writes `tcp://host:port`, and `CARRIER-WEB.md` writes
+// `http` and `https` for the post and `ws` and `wss` for the held line.
+// RFC 3986 appendix B, with the characters a URI may hold checked apart.
+const SPLIT = /^(?:([^:/?#]+):)?(?:\/\/([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?$/;
+const URI_CHARS = /^(?:[A-Za-z0-9\-._~:/?#[\]@!$&'()*+,;=]|%[0-9A-Fa-f]{2})*$/;
+const SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*$/;
+const REG_NAME = /^(?:[A-Za-z0-9\-._~!$&'()*+,;=]|%[0-9A-Fa-f]{2})*$/;
+const IP_LITERAL = /^\[(?:[0-9A-Fa-f:.]+|v[0-9A-Fa-f]+\.[A-Za-z0-9\-._~!$&'()*+,;=:]+)\]$/;
+// A URI with a scheme, taken apart, or null. `host` is as written,
+// brackets included, and `port` the digits as written.
+const parse = (s) => {
+    if (typeof s !== 'string' || !URI_CHARS.test(s))
+        return null;
+    const m = SPLIT.exec(s);
+    if (!m || m[1] === undefined || !SCHEME.test(m[1]))
+        return null;
+    const out = { scheme: m[1].toLowerCase(), authority: m[2] ?? null, userinfo: null, host: null, port: null, path: m[3] ?? '', query: m[4] ?? null, fragment: m[5] ?? null };
+    if (out.authority === null)
+        return out;
+    let rest = out.authority;
+    const at = rest.lastIndexOf('@');
+    if (at >= 0) {
+        out.userinfo = rest.slice(0, at);
+        rest = rest.slice(at + 1);
+    }
+    const hp = /^(\[[^\]]*\]|[^:[\]]*)(?::([0-9]*))?$/.exec(rest);
+    if (!hp)
+        return null;
+    const host = hp[1];
+    if (host.startsWith('[') ? !IP_LITERAL.test(host) : !REG_NAME.test(host))
+        return null;
+    out.host = host;
+    out.port = hp[2] ?? null;
+    return out;
+};
+// The host as a socket takes it: an IPv6 literal without its brackets.
+const bare = (host) => (host.startsWith('[') ? host.slice(1, -1) : host);
+// The scheme an address names, lowercase, or null for what is no URI.
+export const schemeOf = (s) => parse(s)?.scheme ?? null;
+// A `tcp` address as `CARRIER-TCP.md` writes one, or null.
+export const tcpAddress = (s) => {
+    const a = parse(s);
+    if (!a || a.scheme !== 'tcp' || a.authority === null)
+        return null;
+    if (a.userinfo !== null || a.path !== '' || a.query !== null || a.fragment !== null)
+        return null;
+    if (!a.host || a.port === null || !/^[0-9]+$/.test(a.port))
+        return null;
+    const port = Number(a.port);
+    if (port < 1 || port > 65_535)
+        return null;
+    return { host: bare(a.host), port };
+};
+// The `tcp` address of a host and port.
+export const tcpAt = (host, port) => `tcp://${host.includes(':') ? `[${host}]` : host}:${port}`;
+const WEB = new Set(['http', 'https', 'ws', 'wss']);
+// An address of `CARRIER-WEB.md`, or null. `path` is the path and query
+// a request names, `/` when both are empty.
+export const webAddress = (s) => {
+    const a = parse(s);
+    if (!a || !WEB.has(a.scheme) || a.authority === null)
+        return null;
+    if (a.userinfo !== null || a.fragment !== null || !a.host)
+        return null;
+    if (a.port !== null && a.port !== '' && (!/^[0-9]+$/.test(a.port) || Number(a.port) > 65_535))
+        return null;
+    const scheme = a.scheme;
+    const secure = scheme === 'https' || scheme === 'wss';
+    const port = a.port ? Number(a.port) : secure ? 443 : 80;
+    const path = `${a.path || '/'}${a.query !== null ? `?${a.query}` : ''}`;
+    return { scheme, secure, held: scheme === 'ws' || scheme === 'wss', host: bare(a.host), port, path, href: s };
+};
+// Whether a tcp or web address names the unspecified host, where a
+// listener binds every interface and no caller can dial.
+export const unspecified = (s) => {
+    const host = (tcpAddress(s) ?? webAddress(s))?.host;
+    return host === '0.0.0.0' || host === '::';
+};
+// An invitation's `at` as `SPEC.md` reads it: the strings that are URIs
+// with a scheme, in their order. A value that is no array is absent.
+export const readAt = (value) => (Array.isArray(value) ? value.filter((s) => parse(s) !== null) : []);

package/dist/quo/door.d.ts

@@ -25,7 +25,7 @@ export declare class Door {
     readonly behind: Behind;
     readonly draw: Draw;
     constructor(key: WardKey, relations: Relations, behind: Behind, draw: Draw);
-    invite(): Promise<{
+    invite(at?: readonly string[]): Promise<{
         heir: string;
         invitation: Invitation;
     }>;

package/dist/quo/door.js

@@ -23,16 +23,18 @@ export class Door {
         this.draw = draw;
     }
     // A new heir, held fresh, and its invitation. The lock is drawn at the
-    // first invitation that names a heir, before the heir's secret.
-    async invite() {
+    // first invitation that names an heir, before the heir's secret.
+    // A new heir, and its invitation, naming in `at` the addresses given.
+    async invite(at = []) {
         let lock = this.relations.lock();
         if (!lock)
             this.relations.setLock((lock = drawLock(this.draw)));
         const heir = await SigningKey.draw(this.draw);
         this.relations.set(heir.id, { state: 'fresh' });
-        return { heir: heir.id, invitation: { ward: this.key.pk, heir: heir.id, secret: hex(heir.secret), lock: hex(lock.ek) } };
+        const invitation = { ward: this.key.pk, heir: heir.id, secret: hex(heir.secret), lock: hex(lock.ek), ...(at.length > 0 ? { at: [...at] } : {}) };
+        return { heir: heir.id, invitation };
     }
-    // The door stops holding a heir. A fresh one leaves nothing, a spent one
+    // The door stops holding an heir. A fresh one leaves nothing, a spent one
     // leaves the keys kept at removal.
     remove(heir) {
         const record = this.relations.get(heir);

package/dist/quo/index.d.ts

@@ -1,3 +1,4 @@
+export { readAt, schemeOf, tcpAddress, tcpAt, unspecified, webAddress, type TcpAddress, type WebAddress } from './address.ts';
 export { Door, SPAN, type Behind, type Choice, type Judged } from './door.ts';
 export { readInvitation, type Invitation } from './invitation.ts';
 export { Ephemeral, SigningKey, WardKey, type Draw } from './keys.ts';

package/dist/quo/index.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Quo's wire: keys, the invitation, the payload, the reply, the boxes, the
 // door and the standing. It knows no being, no ward and no terrain.
+export { readAt, schemeOf, tcpAddress, tcpAt, unspecified, webAddress } from './address.js';
 export { Door, SPAN } from './door.js';
 export { readInvitation } from './invitation.js';
 export { Ephemeral, SigningKey, WardKey } from './keys.js';

package/dist/quo/invitation.d.ts

@@ -3,5 +3,6 @@ export type Invitation = {
     readonly heir: string;
     readonly secret: string;
     readonly lock: string;
+    readonly at?: string[];
 };
 export declare const readInvitation: (value: unknown) => Invitation | null;

package/dist/quo/invitation.js

@@ -1,15 +1,19 @@
 // SPDX-License-Identifier: Apache-2.0
-// The invitation: `{ ward, heir, secret, lock }`, a value with no route.
+// The invitation: `{ ward, heir, secret, lock, at? }`. A door reads no
+// route from it; `at`, when present, names where the ward is reached.
 import { EK, encapsulate, isHex, unhex } from '../crypto/index.js';
-// An invitation, or null for any other shape. A field beside the four is
-// ignored, and the lock is held to the modulus check.
+import { readAt } from './address.js';
+// An invitation, or null for any other shape. A field beside the five is
+// ignored, the lock is held to the modulus check, and `at` keeps the
+// addresses it holds, an `at` with none or of another shape being absent.
 export const readInvitation = (value) => {
     if (typeof value !== 'object' || value === null || Array.isArray(value))
         return null;
-    const { ward, heir, secret, lock } = value;
+    const { ward, heir, secret, lock, at } = value;
     if (!isHex(ward, 64) || !isHex(heir, 32) || !isHex(secret, 32) || !isHex(lock, EK))
         return null;
     if (encapsulate(unhex(lock), new Uint8Array(32)) === null)
         return null;
-    return { ward, heir, secret, lock };
+    const addresses = readAt(at);
+    return { ward, heir, secret, lock, ...(addresses.length > 0 ? { at: addresses } : {}) };
 };

package/dist/quo/keys.js

@@ -10,7 +10,7 @@ export const LABEL = {
     wardSign: utf8('quo-ward-sign'),
     wardSeal: utf8('quo-ward-seal'),
 };
-// An Ed25519 pair: a heir, or a standing's own key.
+// An Ed25519 pair: an heir, or a standing's own key.
 export class SigningKey {
     secret;
     pk;

package/dist/tcp/frame.d.ts

@@ -0,0 +1,25 @@
+export declare const ASK = 0;
+export declare const REPLY = 1;
+export declare const NOTHING = 2;
+export declare const MAX_BODY = 1048645;
+export type Frame = {
+    kind: 'ask';
+    id: number;
+    pk: Uint8Array;
+    box: Uint8Array;
+} | {
+    kind: 'reply';
+    id: number;
+    box: Uint8Array;
+} | {
+    kind: 'nothing';
+    id: number;
+};
+export declare const askFrame: (id: number, pk: Uint8Array, box: Uint8Array) => Uint8Array;
+export declare const replyFrame: (id: number, box: Uint8Array) => Uint8Array;
+export declare const nothingFrame: (id: number) => Uint8Array;
+export declare class FrameReader {
+    #private;
+    get bad(): boolean;
+    push(chunk: Uint8Array): Frame[];
+}

package/dist/tcp/frame.js

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: Apache-2.0
+// The frames of Quo over TCP, `quo/CARRIER-TCP.md`:
+//
+//   frame = length (4, big-endian) || kind (1) || id (4, big-endian) || rest
+//   00 ask      rest = ward pk (64) || box
+//   01 reply    rest = box
+//   02 nothing  rest = empty
+//
+// A reader says a stream is not a frame as soon as its bytes say so, and
+// reads nothing after it.
+import { concat } from '../crypto/index.js';
+export const ASK = 0;
+export const REPLY = 1;
+export const NOTHING = 2;
+export const MAX_BODY = 1_048_645;
+const PK = 64;
+const frame = (kind, id, ...rest) => {
+    const head = new Uint8Array(9);
+    const view = new DataView(head.buffer);
+    view.setUint32(0, 5 + rest.reduce((n, r) => n + r.length, 0));
+    head[4] = kind;
+    view.setUint32(5, id >>> 0);
+    return concat(head, ...rest);
+};
+export const askFrame = (id, pk, box) => frame(ASK, id, pk, box);
+export const replyFrame = (id, box) => frame(REPLY, id, box);
+export const nothingFrame = (id) => frame(NOTHING, id);
+// Whether a body of this length, and this first byte when known, is no frame.
+const notAFrame = (length, kind) => length > MAX_BODY || length < 5 || (kind !== undefined && (kind > NOTHING || (kind === ASK && length < 5 + PK) || (kind === NOTHING && length !== 5)));
+export class FrameReader {
+    #buffer = new Uint8Array(0);
+    #bad = false;
+    // True once bytes that are not a frame arrived; nothing is read after.
+    get bad() {
+        return this.#bad;
+    }
+    push(chunk) {
+        if (this.#bad)
+            return [];
+        this.#buffer = this.#buffer.length === 0 ? chunk.slice() : concat(this.#buffer, chunk);
+        const out = [];
+        while (this.#buffer.length >= 4) {
+            const view = new DataView(this.#buffer.buffer, this.#buffer.byteOffset);
+            const length = view.getUint32(0);
+            if (notAFrame(length, this.#buffer.length > 4 ? this.#buffer[4] : undefined)) {
+                this.#bad = true;
+                this.#buffer = new Uint8Array(0);
+                return out;
+            }
+            if (this.#buffer.length < 4 + length)
+                break;
+            const body = this.#buffer.subarray(4, 4 + length);
+            this.#buffer = this.#buffer.slice(4 + length);
+            const id = new DataView(body.buffer, body.byteOffset).getUint32(1);
+            if (body[0] === ASK)
+                out.push({ kind: 'ask', id, pk: body.slice(5, 5 + PK), box: body.slice(5 + PK) });
+            else if (body[0] === REPLY)
+                out.push({ kind: 'reply', id, box: body.slice(5) });
+            else
+                out.push({ kind: 'nothing', id });
+        }
+        return out;
+    }
+}

package/dist/tcp/index.d.ts

@@ -0,0 +1,24 @@
+import { Carrier } from '../contract/index.ts';
+import { type Dialed, type GroundFaculty } from '../harbor/index.ts';
+import { TCP, TCP_OPENING } from '../line/index.ts';
+export interface Doors {
+    arrive(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+}
+export declare class TcpCarrier extends Carrier {
+    #private;
+    route(pk: string, at: readonly string[] | null): boolean;
+    routed(pk: string): boolean;
+    carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+    carryAt(at: readonly string[], pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+    dial(at: string, pk: string, bytes: Uint8Array): Promise<Dialed>;
+    close(): Promise<void>;
+}
+export declare class TcpListener {
+    #private;
+    private constructor();
+    static listen(doors: Doors, host?: string, port?: number): Promise<TcpListener>;
+    get at(): string;
+    close(): Promise<void>;
+}
+export { TCP, TCP_OPENING };
+export declare const tcpFaculty: GroundFaculty;

package/dist/tcp/index.js

@@ -0,0 +1,260 @@
+// 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 } from 'node:net';
+import { hex, isHex, unhex } from '../crypto/index.js';
+import { Carrier } from '../contract/index.js';
+import { CarrierFaculty, UNDIALED } from '../harbor/index.js';
+import { tcpAddress, tcpAt } from '../quo/index.js';
+import { ownerAsk } from '../ward/index.js';
+import { askFrame, FrameReader, nothingFrame, replyFrame, TCP, TCP_OPENING } from '../line/index.js';
+const MAX_ID = 0xffff_ffff;
+// The `tcp` addresses among some, in their order.
+const tcpAddresses = (at) => at.map(tcpAddress).filter((a) => a !== null);
+class Line {
+    #socket;
+    #reader = new FrameReader();
+    #waiting = new Map();
+    #next = 1;
+    closed = false;
+    constructor(socket, onClose) {
+        this.#socket = socket;
+        socket.on('data', (chunk) => {
+            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, port, onClose) {
+        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, box) {
+        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() {
+        this.#socket.destroy();
+    }
+}
+export class TcpCarrier extends Carrier {
+    #routes = new Map();
+    #lines = new Map();
+    // 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, at) {
+        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) {
+        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, bytes) {
+        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, pk, bytes) {
+        return isHex(pk, 64) ? this.#carry(tcpAddresses(at), pk, bytes) : Promise.resolve(null);
+    }
+    async #carry(addresses, pk, bytes) {
+        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, pk, bytes) {
+        const address = tcpAddress(at);
+        return address && isHex(pk, 64) ? this.#dial(address, pk, bytes) : Promise.resolve(UNDIALED);
+    }
+    async #dial(address, pk, bytes) {
+        const line = await this.#line(address);
+        return line ? line.ask(unhex(pk), bytes) : UNDIALED;
+    }
+    #line({ host, port }) {
+        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() {
+        const lines = [...this.#lines.values()];
+        this.#lines.clear();
+        for (const line of await Promise.all(lines))
+            line?.close();
+    }
+}
+export class TcpListener {
+    #server;
+    #doors;
+    #sockets = new Set();
+    constructor(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, host = '127.0.0.1', port = 0) {
+        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() {
+        const address = this.#server.address();
+        return tcpAt(address.address, address.port);
+    }
+    #serve(socket) {
+        this.#sockets.add(socket);
+        const reader = new FrameReader();
+        socket.on('data', (chunk) => {
+            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, id, pk, box) {
+        let reply = 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() {
+        for (const socket of this.#sockets)
+            socket.destroy();
+        return new Promise((resolve) => this.#server.close(() => resolve()));
+    }
+}
+export { TCP, TCP_OPENING };
+const listenOf = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const { host, port } = value;
+    return typeof host === 'string' && Number.isInteger(port) && port >= 0 && port <= 65_535 ? { host, port: port } : 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 = (ground) => class TcpFaculty extends CarrierFaculty {
+    static kind = TCP;
+    static asks = {
+        listen: ownerAsk('listen for Quo over TCP, and on every wake', { properties: { host: { type: 'string' }, port: { type: 'integer' } } }),
+        deaf: ownerAsk('listen nowhere'),
+    };
+    #dialer = new TcpCarrier();
+    #listener;
+    accepts(address) {
+        return tcpAddress(address) !== null;
+    }
+    dial(address, pk, bytes) {
+        return this.#dialer.dial(address, pk, bytes);
+    }
+    listening() {
+        return this.#listener ? [this.#listener.at] : [];
+    }
+    async awake() {
+        const at = listenOf(this.cells.listen);
+        if (at && !this.#listener)
+            this.#listener = await TcpListener.listen(ground, at.host, at.port);
+    }
+    async sleep() {
+        await this.#dialer.close();
+        await this.#listener?.close();
+        this.#listener = undefined;
+    }
+    async listen(args) {
+        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.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() {
+        await this.#listener?.close();
+        this.#listener = undefined;
+        delete this.cells.listen;
+        return { deaf: true };
+    }
+};

package/dist/ward/index.d.ts

@@ -1,5 +1,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/dist/ward/index.js

@@ -4,4 +4,5 @@ export { allow, CEILING, DEFAULT } from './allowance.js';
 export { HEAD_ROW, Partition } from './partition.js';
 export { DEPTH } from './stance.js';
 export { DOCK, Ward } from './ward.js';
-export { ownerAsk, pilots, WardBeing } from './ward-being.js';
+export { ownerAsk, PILOT, pilots, rootAsk, WardBeing } from './ward-being.js';
+export { Pilot } from './pilot.js';

package/dist/ward/pilot.d.ts

@@ -0,0 +1,8 @@
+import { Being, type AskSpec, type JsonObject } from '../being/index.ts';
+export declare class Pilot extends Being {
+    static readonly kind: string;
+    static asks: Record<string, AskSpec>;
+    hold(args: JsonObject): Promise<JsonObject>;
+    pilot(args: JsonObject): Promise<JsonObject>;
+    drop(): JsonObject;
+}

package/dist/ward/pilot.js

@@ -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 } from '../being/index.js';
+import { readInvitation } from '../quo/index.js';
+import { ownerAsk, PILOT } from './ward-being.js';
+// The standing id the far ward-being is held under.
+const FAR = 'far';
+const object = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export class Pilot extends Being {
+    static kind = PILOT;
+    static asks = {
+        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) {
+        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) {
+        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) };
+        return { answer: out };
+    }
+    drop() {
+        return this.stance.standings.remove(FAR) ? { dropped: true } : { error: 'no ward is held' };
+    }
+}

package/dist/ward/stance.d.ts

@@ -14,6 +14,8 @@ export interface Inside {
     boot(maker: string, className: string, key: string, id?: string): Promise<string | null>;
     offer(contract: string): Promise<Invitation | null>;
     retract(contract: string, heir: string): Promise<void>;
+    reach(): readonly string[];
+    learn(ward: string, at: readonly string[]): Promise<void>;
 }
 export declare class WardStance implements Stance {
     #private;
@@ -22,8 +24,6 @@ export declare class WardStance implements Stance {
     readonly standings: Standings;
     constructor(inside: Inside, key: string, row: BeingRow);
     get cells(): JsonObject;
-    boot(className: string, key: string, id?: string): Promise<string | null>;
-    lend(contract: {
-        readonly name: string;
-    }, id: string): Promise<string | null>;
+    boot(kind: string, key: string, id?: string): Promise<string | null>;
+    lend(contract: abstract new (...args: never[]) => unknown, id: string): Promise<string | null>;
 }