nervur 0.20.0 → 0.20.1

package/dist/ward/ward.js

@@ -5,7 +5,7 @@
 // what is behind its door for `quo/`.
 import { readValue, writeValue } from '../crypto/index.js';
 import { Door, readInvitation, WardKey } from '../quo/index.js';
-import { digest, isSilence, isWord, OWNER, silence, WARD, word } from '../being/index.js';
+import { digest, isSilence, isWord, kindOf, OWNER, silence, WARD, word } from '../being/index.js';
 import { Partition, PartitionRelations } from './partition.js';
 import { DEPTH, WardStance } from './stance.js';
 import { WardBeing } from './ward-being.js';
@@ -47,10 +47,13 @@ export class Ward {
         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)
@@ -67,6 +70,33 @@ export class Ward {
     get wardBeing() {
         return this.#residents.get(WARD).being;
     }
+    // The being standing under a key, for the harbor's own faculties.
+    being(key) {
+        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() {
+        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, args = {}) {
         return this.#kept(WARD, () => this.#answer(WARD, { id: OWNER }, method, args));
@@ -89,7 +119,7 @@ export class Ward {
         }
         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() {
         const key = this.partition.head.public;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nervur",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "description": "Nervur's kit of Quo: an object asks another object and gets an answer, without knowing where it is.",
   "keywords": [
     "quo",
@@ -12,6 +12,9 @@
   "license": "Apache-2.0",
   "homepage": "https://nervur.org",
   "type": "module",
+  "bin": {
+    "nervur": "dist/cli/main.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -20,6 +23,10 @@
     "./folder": {
       "types": "./dist/folder/index.d.ts",
       "default": "./dist/folder/index.js"
+    },
+    "./tcp": {
+      "types": "./dist/tcp/index.d.ts",
+      "default": "./dist/tcp/index.js"
     }
   },
   "scripts": {

package/src/being/being.ts

@@ -28,8 +28,12 @@ const wrote = (self: object, name: string): boolean => {
 type Method = (args: JsonObject, asker: Asker) => Reply | Promise<Reply>;
 
 // A subclass's statics replace its parent's and never merge: her blueprint
-// is what the class in front of you declares, in its order.
+// is what the class in front of you declares, in its order. Her kind is
+// never inherited: see `kind.ts`.
 export class Being {
+  // The name her row keeps for this class. Every class that stands declares
+  // its own.
+  static readonly kind: string = 'org.nervur.being';
   // Her cells' defaults, written at birth only where a key is missing.
   static cells: JsonObject = {};
   static asks: Record<string, AskSpec> = {};

package/src/being/faculty.ts

@@ -2,23 +2,30 @@
 // A faculty: a being of the box ward that fulfils a contract. A contract is
 // a class between `Faculty` and the class that stands, usually abstract:
 //
-//   abstract class Timer extends Faculty { ... }     the contract
-//   class IntervalTimer extends Timer { ... }        one class that fulfils it
+//   abstract class Timer extends Faculty {           the contract
+//     static override kind = 'com.acme.timer' }
+//   class IntervalTimer extends Timer {              one class that fulfils it
+//     static override kind = 'com.acme.interval-timer' }
 //
-// A being lends by the contract and never learns the class. Two asks are the
+// A being lends by the contract's kind and never learns the class. Every
+// class between the faculty and `Faculty` is a contract and declares its
+// own kind, and a faculty fulfils each of them and her own. Two asks are the
 // faculty's own and answered to the ward-being that opened her alone:
 // `offer`, an invitation on herself for a ward the dock vouches for, and
 // `retract`, an offer that was not taken.
 import { Being } from './being.ts';
+import { kindOf } from './kind.ts';
 import { WARD, type Asker, type Blueprint, type JsonObject, type Reply } from './types.ts';
 
 export class Faculty extends Being {
+  static override readonly kind: string = 'org.nervur.faculty';
+
   // The contracts a class fulfils: itself and every class between it and
-  // `Faculty`, by name.
+  // `Faculty`, by kind. A class among them with no kind of its own throws.
   static contracts(C: abstract new (...args: never[]) => unknown): string[] {
-    const names: string[] = [];
-    for (let c: unknown = C; typeof c === 'function' && c !== Faculty; c = Object.getPrototypeOf(c)) names.push((c as { name: string }).name);
-    return names;
+    const kinds: string[] = [];
+    for (let c: unknown = C; typeof c === 'function' && c !== Faculty; c = Object.getPrototypeOf(c)) kinds.push(kindOf(c));
+    return kinds;
   }
 
   static fulfils(C: unknown): C is typeof Faculty {

package/src/being/index.ts

@@ -3,5 +3,6 @@
 export { Being, type AskSpec } from './being.ts';
 export { canonical, digest } from './digest.ts';
 export { Faculty } from './faculty.ts';
+export { isKind, KIT, kindOf, ownKind } from './kind.ts';
 export { OWNER, WARD, type Answer, type Ask, type Asker, type BeingClass, type BeingLike, type Blueprint, type Invitation, type Json, type JsonObject, type Occupants, type Reply, type Schema, type Stance, type Standing, type Standings, type Wanted } from './types.ts';
 export { isSilence, isWord, silence, told, word, type Silence, type Word, type WordName } from './words.ts';

package/src/being/kind.ts

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+// A kind: the name a row keeps for the class a being is born of, and the
+// name a contract is lent by. It is declared on the class, never taken from
+// the name the language gives it, because a bundler renames classes.
+//
+//   static kind = 'com.acme.shop'
+//
+// A kind is a reversed domain its author owns, then a name: at least three
+// segments joined by `.`, each lowercase letters, digits and `-`, starting
+// with a letter or digit. `org.nervur.` is the kit's own. A class declares
+// its own kind: one it inherits names its parent, so it is none.
+export const KIT = 'org.nervur.';
+
+const KIND = /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*){2,}$/;
+
+export const isKind = (text: unknown): text is string => typeof text === 'string' && KIND.test(text);
+
+// The kind a class declares on itself, or undefined.
+export const ownKind = (C: unknown): string | undefined => {
+  if (typeof C !== 'function' || !Object.hasOwn(C, 'kind')) return undefined;
+  const kind = (C as { kind?: unknown }).kind;
+  return isKind(kind) ? kind : undefined;
+};
+
+// The kind a class declares on itself, or a throw naming the class.
+export const kindOf = (C: unknown): string => {
+  const kind = ownKind(C);
+  if (kind === undefined) throw new Error(`class ${typeof C === 'function' ? C.name : String(C)} declares no kind of its own`);
+  return kind;
+};

package/src/being/types.ts

@@ -56,12 +56,13 @@ export interface Stance {
   readonly cells: JsonObject;
   readonly occupants: Occupants;
   readonly standings: Standings;
-  // A new being of her ward, by class name, under a key she chooses. With an
-  // id, the new being invites her under her key, and she takes it under id.
-  boot(className: string, key: string, id?: string): Promise<string | null>;
+  // A new being of her ward, by kind, under a key she chooses. With an id,
+  // the new being invites her under her key, and she takes it under id.
+  boot(kind: string, key: string, id?: string): Promise<string | null>;
   // A standing under `id` at the faculty this harbor opened for a contract:
-  // the id, or null where none is open or the relation was refused.
-  lend(contract: { readonly name: string }, id: string): Promise<string | null>;
+  // the id, or null where none is open, the contract declares no kind of
+  // its own, or the relation was refused.
+  lend(contract: abstract new (...args: never[]) => unknown, id: string): Promise<string | null>;
 }
 
 // Anything with `answer` is a being.
@@ -69,4 +70,5 @@ export interface BeingLike {
   answer(asker: Asker, method: string | undefined, args: JsonObject): Reply | Promise<Reply>;
   describe?(asker: Asker): Blueprint;
 }
-export type BeingClass = (new (stance: Stance) => BeingLike) & { readonly name: string };
+// A class that stands. Its kind is its own, as `kind.ts` says.
+export type BeingClass = (new (stance: Stance) => BeingLike) & { readonly name: string; readonly kind: string };

package/src/cli/command.ts

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur`: a harbor on this machine. Each command is one root request, the
+// same the root line carries from any front, printed as one JSON line.
+//
+//   nervur init   [--dir D]                         the harbor made: its seed drawn,
+//                                                   its catalogue stood, and an owner
+//                                                   invitation for whoever made it
+//   nervur serve  [--dir D] [--host H] [--port P]   the harbor served: Quo over TCP,
+//                                                   and the root line on its socket
+//   nervur module add <file>                        a module the catalogue runs
+//   nervur module remove <module>                   a module it runs no more
+//   nervur modules                                  what the catalogue runs
+//   nervur census [--ward W]                        the empty ask
+//   nervur open   <key> <kind>                      a faculty stands in the box ward
+//   nervur host   <ward> [--seed S]                 a hosted ward stands
+//   nervur route  <ward pk> <host:port | none>      where a ward is reached
+//   nervur boot   [--ward W] <key> <kind>           a being stands
+//   nervur unboot [--ward W] <being>                a being goes
+//   nervur public [--ward W] <key | none>           the being a stranger reaches
+//   nervur invite [--ward W] <being> <id>           an invitation on a being
+//   nervur ask    [--ward W] [being] [method] [args] a being, asked as the owner
+//   nervur own    [--ward W] <id>                   an invitation for an owner
+//   nervur disown [--ward W] <id>                   an owner no more
+//   nervur pilot  <name> <invitation> <host:port>   a far ward held as its owner, by a
+//                                                   pilot being of the box ward
+//   nervur <command> --via <name> ...               the command asked of the far ward
+//                                                   that pilot holds, as its owner
+//
+// D is --dir, then $NERVUR_DIR, then ~/.nervur. A module file is named from
+// where the command runs and kept by its absolute path. No --ward is the box
+// ward, and a pilot holds one ward, so --via takes no --ward. The exit is 1
+// when the answer is an error.
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import type { JsonObject } from '../being/index.ts';
+import type { RootRequest } from '../harbor/index.ts';
+import { open, request, serve } from './harbor.ts';
+
+const USAGE = 'usage: nervur <init|serve|module|modules|census|open|host|route|boot|unboot|public|invite|ask|own|disown|pilot> [args] [--dir D] [--ward W] [--via V] [--seed S] [--host H] [--port P]';
+const FLAGS = new Set(['dir', 'ward', 'via', 'seed', 'host', 'port']);
+
+export const parse = (argv: string[]): { command?: string; words: string[]; flags: Record<string, string> } => {
+  const flags: Record<string, string> = {};
+  const words: string[] = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]!;
+    const name = arg.startsWith('--') ? arg.slice(2) : undefined;
+    if (name === undefined) words.push(arg);
+    else if (!FLAGS.has(name) || argv[i + 1] === undefined) throw new Error(`--${name} is no flag with a value`);
+    else flags[name] = argv[(i += 1)]!;
+  }
+  const [command, ...rest] = words;
+  return { ...(command === undefined ? {} : { command }), words: rest, flags };
+};
+
+const none = (word: string): string | null => (word === 'none' ? null : word);
+const json = (word: string | undefined): JsonObject | undefined => (word === undefined ? undefined : (JSON.parse(word) as JsonObject));
+const catalogue = (method: string, args: JsonObject = {}): RootRequest => ({ method: 'ask', args: { being: 'catalogue', method, args } });
+
+// The root request a command names, or a throw saying what it lacks.
+export const requestOf = (command: string, words: string[], flags: Record<string, string>): RootRequest => {
+  const need = (n: number): string[] => {
+    if (words.length !== n) throw new Error(`${command} takes ${n} argument${n === 1 ? '' : 's'}`);
+    return words;
+  };
+  const at = flags.ward === undefined ? {} : { ward: flags.ward };
+  switch (command) {
+    case 'module': {
+      const [verb, what] = need(2);
+      if (verb === 'add') return catalogue('add', { from: resolve(what!) });
+      if (verb === 'remove') return catalogue('remove', { module: what! });
+      throw new Error('module is add or remove');
+    }
+    case 'modules':
+      return (need(0), catalogue('modules'));
+    case 'census':
+      return (need(0), at);
+    case 'open': {
+      const [key, kind] = need(2);
+      return { method: 'open', args: { key: key!, class: kind! } };
+    }
+    case 'host': {
+      const [ward] = need(1);
+      return { method: 'host', args: { ward: ward!, ...(flags.seed === undefined ? {} : { seed: flags.seed }) } };
+    }
+    case 'route': {
+      const [ward, where] = need(2);
+      return { method: 'route', args: { ward: ward!, at: none(where!) } };
+    }
+    case 'boot': {
+      const [key, kind] = need(2);
+      return { ...at, method: 'boot', args: { key: key!, class: kind! } };
+    }
+    case 'unboot':
+      return { ...at, method: 'unboot', args: { being: need(1)[0]! } };
+    case 'public':
+      return { ...at, method: 'public', args: { key: none(need(1)[0]!) } };
+    case 'invite': {
+      const [being, id] = need(2);
+      return { ...at, method: 'invite', args: { being: being!, id: id! } };
+    }
+    case 'ask': {
+      if (words.length > 3) throw new Error('ask takes at most a being, a method and its args');
+      const [being, method, args] = words;
+      return { ...at, method: 'ask', args: { ...(being === undefined ? {} : { being }), ...(method === undefined ? {} : { method }), ...(args === undefined ? {} : { args: json(args)! }) } };
+    }
+    case 'own':
+    case 'disown':
+      return { ...at, method: command, args: { id: need(1)[0]! } };
+    default:
+      throw new Error(USAGE);
+  }
+};
+
+// An error answer at any depth the root line or an ask carries it.
+const failed = (answer: unknown): boolean => {
+  if (typeof answer !== 'object' || answer === null) return false;
+  const a = answer as JsonObject;
+  return 'error' in a || failed(a.answer);
+};
+
+export const main = async (argv: string[], env: Record<string, string | undefined>, print: (line: string) => void): Promise<number> => {
+  const { command, words, flags } = parse(argv);
+  if (command === undefined) throw new Error(USAGE);
+  const dir = flags.dir ?? env.NERVUR_DIR ?? join(homedir(), '.nervur');
+  const out = (answer: JsonObject): number => {
+    print(JSON.stringify(answer));
+    return failed(answer) ? 1 : 0;
+  };
+  if (command === 'init') {
+    if (words.length > 0) throw new Error('init takes no argument');
+    if (existsSync(join(dir, 'seed'))) return out({ error: `a harbor stands at ${dir}` });
+    const { harbor, carrier } = await open(dir);
+    try {
+      const owner = await harbor.root('own', { id: 'owner' });
+      return out({ pk: harbor.box.pk, owner: owner as JsonObject });
+    } finally {
+      await carrier.close();
+    }
+  }
+  if (command === 'serve') {
+    if (words.length > 0) throw new Error('serve takes no argument');
+    const served = await serve(dir, flags.host, flags.port === undefined ? undefined : Number(flags.port));
+    const stop = (): void => void served.close().then(() => process.exit(0));
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    print(JSON.stringify({ pk: served.pk, at: served.at, root: served.root }));
+    return SERVING;
+  }
+  if (command === 'pilot') {
+    if (words.length !== 3) throw new Error('pilot takes 3 arguments');
+    const [name, invitation, at] = words as [string, string, string];
+    const held = JSON.parse(invitation) as JsonObject;
+    for (const req of pilotRequests(name, held, at)) {
+      const answer = await request(dir, req);
+      if (!failed(answer)) continue;
+      if (req.method === 'ask') await request(dir, { method: 'unboot', args: { being: name } });
+      return out(answer);
+    }
+    return out({ piloting: name, ward: held.ward! });
+  }
+  if (flags.via === undefined) return out(await request(dir, requestOf(command, words, flags)));
+  if (flags.ward !== undefined) throw new Error('--via takes no --ward');
+  return out(farAnswer(await request(dir, via(flags.via, requestOf(command, words, flags)))));
+};
+
+// The root requests that hold a far ward: its route, the pilot, the take.
+export const pilotRequests = (name: string, invitation: JsonObject, at: string): RootRequest[] => [
+  { method: 'route', args: { ward: invitation.ward ?? null, at } },
+  { method: 'boot', args: { key: name, class: 'org.nervur.pilot' } },
+  { method: 'ask', args: { being: name, method: 'hold', args: { invitation } } },
+];
+
+// A root request, asked of the far ward a pilot holds.
+export const via = (pilot: string, far: RootRequest): RootRequest => ({
+  method: 'ask',
+  args: { being: pilot, method: 'pilot', args: { ...(far.method === undefined ? {} : { method: far.method }), ...(far.args === undefined ? {} : { args: far.args }) } },
+});
+
+// The far ward-being's answer out of the pilot's, or the local error.
+export const farAnswer = (local: JsonObject): JsonObject => {
+  const inner = (local.answer as JsonObject | undefined)?.answer;
+  return typeof inner === 'object' && inner !== null && !Array.isArray(inner) ? inner : local;
+};
+
+// What `main` answers for a harbor it keeps serving: no exit yet.
+export const SERVING = -1;

package/src/cli/harbor.ts

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: Apache-2.0
+// A harbor on this machine, as the `nervur` command stands it: its seed and
+// sealed memory in a folder, its code imported from the files its
+// catalogue names, Quo over TCP as its carrier, and the root line on a
+// local socket beside them.
+//
+//   <dir>/seed        the harbor's seed
+//   <dir>/<place>/    its sealed memory
+//   <dir>/root.sock   the root line while the harbor is served, open to
+//                     this user alone, or in the temporary folder for a
+//                     folder too deep for a socket path
+//
+// A root request goes to a served harbor over its socket. With none served,
+// the command unpacks the harbor from its folder, asks, and closes it, so
+// one process at a time writes the folder.
+import { createHash } from 'node:crypto';
+import { chmod, rm } from 'node:fs/promises';
+import { connect, createServer, type Server } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { JsonObject } from '../being/index.ts';
+import { Loader, type Loaded } from '../contract/index.ts';
+import { FolderCustody, FolderMemory } from '../folder/index.ts';
+import { Harbor, rootLine, type RootRequest } from '../harbor/index.ts';
+import { CryptoEntropy, PointerTerrain } from '../pointer/index.ts';
+import { TcpCarrier, TcpListener } from '../tcp/index.ts';
+
+// A socket path has a hundred bytes or so on every system, so a folder too
+// deep for one puts its socket in this user's temporary folder, under a
+// name drawn from the folder's own path.
+const SOCKET_PATH = 100;
+export const socketOf = (dir: string): string => {
+  const beside = join(resolve(dir), 'root.sock');
+  if (Buffer.byteLength(beside) <= SOCKET_PATH) return beside;
+  return join(tmpdir(), `nervur-${createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 32)}.sock`);
+};
+
+// Code from a file: a module that exports `module`, `version` and
+// `classes`, found again by its absolute path. A file that cannot be
+// imported, or exports no module, is none.
+export class ImportLoader extends Loader {
+  async load(from: string): Promise<Loaded | null> {
+    const path = resolve(from);
+    let exported: { module?: unknown; version?: unknown; classes?: unknown };
+    try {
+      exported = (await import(pathToFileURL(path).href)) as typeof exported;
+    } catch {
+      return null;
+    }
+    const { module, version, classes } = exported;
+    if (typeof module !== 'string' || typeof version !== 'string' || !Array.isArray(classes)) return null;
+    return { module, version, classes, from: path };
+  }
+}
+
+export type Opened = { harbor: Harbor; carrier: TcpCarrier };
+
+export const open = async (dir: string): Promise<Opened> => {
+  const entropy = new CryptoEntropy();
+  const carrier = new TcpCarrier();
+  const harbor = await Harbor.open(new PointerTerrain({ entropy, carrier, loader: new ImportLoader(), custody: new FolderCustody(dir, entropy), memory: new FolderMemory(dir) }));
+  return { harbor, carrier };
+};
+
+// One root request over a served harbor's socket, or undefined where none
+// is served.
+const overSocket = (dir: string, request: RootRequest): Promise<JsonObject | undefined> =>
+  new Promise((done, fail) => {
+    const socket = connect(socketOf(dir));
+    let text = '';
+    socket.once('connect', () => socket.write(`${JSON.stringify(request)}\n`));
+    socket.on('data', (chunk: Buffer) => {
+      text += chunk.toString('utf8');
+      const end = text.indexOf('\n');
+      if (end < 0) return;
+      socket.end();
+      done(JSON.parse(text.slice(0, end)) as JsonObject);
+    });
+    socket.once('error', (e: NodeJS.ErrnoException) => (e.code === 'ENOENT' || e.code === 'ECONNREFUSED' ? done(undefined) : fail(e)));
+  });
+
+export const request = async (dir: string, req: RootRequest): Promise<JsonObject> => {
+  const served = await overSocket(dir, req);
+  if (served !== undefined) return served;
+  const { harbor, carrier } = await open(dir);
+  try {
+    return await rootLine(harbor, req);
+  } finally {
+    await carrier.close();
+  }
+};
+
+export type Served = { pk: string; at: string; root: string; close(): Promise<void> };
+
+// The harbor served: Quo over TCP on host and port, the root line on the
+// socket. A socket file nobody answers on is a stale one, and is replaced.
+export const serve = async (dir: string, host?: string, port?: number): Promise<Served> => {
+  if ((await overSocket(dir, {})) !== undefined) throw new Error(`a harbor is already served from ${dir}`);
+  const { harbor, carrier } = await open(dir);
+  const listener = await TcpListener.listen(harbor, host, port);
+  const root = socketOf(dir);
+  await rm(root, { force: true });
+  const server: Server = createServer((socket) => {
+    let text = '';
+    socket.on('data', (chunk: Buffer) => {
+      text += chunk.toString('utf8');
+      for (let end = text.indexOf('\n'); end >= 0; end = text.indexOf('\n')) {
+        const line = text.slice(0, end);
+        text = text.slice(end + 1);
+        let value: unknown;
+        try {
+          value = JSON.parse(line);
+        } catch {
+          value = undefined;
+        }
+        void rootLine(harbor, value)
+          .catch(() => ({ error: 'the harbor threw' }))
+          .then((answer) => socket.write(`${JSON.stringify(answer)}\n`));
+      }
+    });
+    socket.on('error', () => socket.destroy());
+  });
+  await new Promise<void>((done) => server.listen(root, done));
+  await chmod(root, 0o600);
+  return {
+    pk: harbor.box.pk,
+    at: listener.at,
+    root,
+    close: async () => {
+      await new Promise((done) => server.close(done));
+      await rm(root, { force: true });
+      await listener.close();
+      await carrier.close();
+    },
+  };
+};

package/src/cli/main.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// The `nervur` program: `command.ts` over this process's arguments. A
+// command that cannot run exits 2 and says why on stderr.
+import { main, SERVING } from './command.ts';
+
+try {
+  const code = await main(process.argv.slice(2), process.env, (line) => process.stdout.write(`${line}\n`));
+  if (code !== SERVING) process.exitCode = code;
+} catch (e) {
+  process.stderr.write(`nervur: ${(e as Error).message}\n`);
+  process.exitCode = 2;
+}

package/src/contract/index.ts

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
-// The contracts: what the onion cannot unpack from cells, each an abstract
-// class, so a registry can tell at run time which class fulfils which. The
-// class differs by terrain, and the contract does not.
+// The contracts: what the onion cannot unpack from cells, a module's code
+// among them, each an abstract class, so a registry can tell at run time
+// which class fulfils which. The class differs by terrain, and the
+// contract does not.
 import type { Draw } from '../quo/index.ts';
 
 // Drawn bytes.
@@ -20,25 +21,53 @@ export abstract class Clock {
   abstract wait(ms: number): { done: Promise<void>; cancel(): void };
 }
 
-// One ward's partition, opened by name: the rows the ward writes into
-// directly, told after every write, and kept once at the end of an arrival.
+// One ward's partition, as the harbor's package opens it: the rows the
+// ward writes into directly, told after every write, and kept once at the
+// end of an arrival.
 export interface Rows {
   readonly rows: Record<string, unknown>;
   told(row: string): void;
   kept(): Promise<boolean>;
 }
 
+// A harbor's memory as a terrain keeps it: sealed entries it cannot read,
+// in places, each entry by name. Every name is lowercase hex the kit
+// chose, so a body may use it as a file name as it stands.
 export abstract class Memory {
-  abstract open(name: string): Promise<Rows>;
+  // Every entry kept in a place; a place nothing was kept in is empty.
+  abstract read(place: string): Promise<Map<string, Uint8Array>>;
+  // One keep: each entry written whole, or removed where it is null.
+  abstract write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void>;
 }
 
-// A ward's seed by the harbor's name for it: thirty-two bytes, the same
-// every time that name is asked.
+// The harbor's seed: thirty-two bytes, the same every time. It is the one
+// secret a terrain holds.
 export abstract class Custody {
-  abstract seed(name: string): Promise<Uint8Array>;
+  abstract seed(): Promise<Uint8Array>;
+}
+
+// A module: the code a harbor's classes come from. It declares its own
+// name, a reversed domain as a kind is, and its version.
+export type Module = { readonly module: string; readonly version: string; readonly classes: readonly unknown[] };
+
+// A module as a loader found it, with `from`, the name this loader finds
+// it by again.
+export type Loaded = Module & { readonly from: string };
+
+// Code, by the name a harbor keeps for it, or null where this loader has
+// none. Code never crosses a door and never lives in a cell, so it is the
+// one thing beside the seed a terrain hands in: a map, an import, a bundle.
+export abstract class Loader {
+  abstract load(from: string): Promise<Loaded | null>;
 }
 
 // Bytes to a ward pk in; bytes, or null for nothing, out.
 export abstract class Carrier {
   abstract carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+  // Where a ward pk is reached, or null to forget it: true when this
+  // carrier dials by address and took it. The addresses live in the dock's
+  // cells, and the harbor hands them here as it unpacks.
+  route(_pk: string, _at: string | null): boolean {
+    return false;
+  }
 }