nervur 0.20.0 → 0.20.2

package/src/edge/index.ts

@@ -0,0 +1,359 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur/edge`: the edge ground, Cloudflare Workers with a Durable Object
+// per harbor. The object's storage keeps the harbor's sealed memory and
+// its seed, sealed under the worker's `NERVUR_SECRET`; the object answers
+// Quo over the web, a post or a held line, since a worker takes no
+// inbound TCP; and it asks over TCP and the web.
+//
+//   m/<place>/<name>   one sealed entry of the harbor's memory
+//   c/seed             the seed, sealed under a key from the secret
+//
+// A keep is one storage transaction, whole or nothing. The storage and
+// state types name only what the kit uses, so no Cloudflare package is a
+// dependency.
+import type { AskSpec, JsonObject } from '../being/index.ts';
+import { Custody, Memory, type Entropy, type Module } from '../contract/index.ts';
+import { decrypt, encrypt, hkdf, isHex, unhex, utf8 } from '../crypto/index.ts';
+import { addGround, CarrierFaculty, Harbor, UNDIALED, type Dialed, type Ground, type GroundFaculty, type GroundProbe } from '../harbor/index.ts';
+import { answerHeld, answerPost, askFrame, FrameReader, TCP, TCP_OPENING, WEB_OPENING, webFaculty, webPush, type WebListen, type WebListener } from '../line/index.ts';
+import { CryptoEntropy, HeldLoader, PointerTerrain } from '../pointer/index.ts';
+import { tcpAddress, tcpAt, type TcpAddress } from '../quo/index.ts';
+import { ownerAsk } from '../ward/index.ts';
+
+export const EDGE = 'edge';
+const ENTRY = 'm/';
+const SEED = 'c/seed';
+// The most keys one storage call takes.
+const BATCH = 128;
+const SEAL_INFO = utf8('nervur edge custody');
+const MAX_ID = 0xffff_ffff;
+
+export interface EdgeStorage {
+  get(key: string): Promise<unknown>;
+  put(entries: Record<string, unknown>): Promise<void>;
+  delete(keys: string[]): Promise<number>;
+  list(options: { prefix: string }): Promise<Map<string, unknown>>;
+  transaction<T>(work: (txn: EdgeStorage) => Promise<T>): Promise<T>;
+}
+export interface EdgeState {
+  readonly storage: EdgeStorage;
+  blockConcurrencyWhile<T>(work: () => Promise<T>): Promise<T>;
+}
+export type EdgeEnv = { readonly NERVUR_SECRET?: string };
+export type EdgeGiven = { readonly state: EdgeState; readonly env: EdgeEnv };
+
+const chunks = <T>(items: readonly T[]): T[][] => Array.from({ length: Math.ceil(items.length / BATCH) }, (_, i) => items.slice(i * BATCH, (i + 1) * BATCH));
+const bytesOf = (value: unknown): Uint8Array => new Uint8Array(value instanceof ArrayBuffer ? value : (value as Uint8Array));
+
+// A body keeps its keys under `root`, so one object may hold more than one
+// keeping.
+export class EdgeMemory extends Memory {
+  readonly #storage: EdgeStorage;
+  readonly #entry: string;
+  constructor(storage: EdgeStorage, root = '') {
+    super();
+    this.#storage = storage;
+    this.#entry = `${root}${ENTRY}`;
+  }
+
+  async read(place: string): Promise<Map<string, Uint8Array>> {
+    const prefix = `${this.#entry}${place}/`;
+    const listed = await this.#storage.list({ prefix });
+    return new Map([...listed].map(([key, value]) => [key.slice(prefix.length), bytesOf(value).slice()]));
+  }
+
+  write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void> {
+    const put: [string, Uint8Array][] = [];
+    const gone: string[] = [];
+    for (const [name, bytes] of entries) {
+      if (bytes === null) gone.push(`${this.#entry}${place}/${name}`);
+      else put.push([`${this.#entry}${place}/${name}`, bytes.slice()]);
+    }
+    return this.#storage.transaction(async (txn) => {
+      for (const batch of chunks(put)) await txn.put(Object.fromEntries(batch));
+      for (const batch of chunks(gone)) await txn.delete(batch);
+    });
+  }
+
+  async places(): Promise<string[]> {
+    const entry = this.#entry;
+    const keys = [...(await this.#storage.list({ prefix: entry })).keys()];
+    return [...new Set(keys.map((key) => key.slice(entry.length, key.indexOf('/', entry.length))))];
+  }
+
+  async forget(place: string): Promise<void> {
+    const keys = [...(await this.#storage.list({ prefix: `${this.#entry}${place}/` })).keys()];
+    await this.#storage.transaction(async (txn) => {
+      for (const batch of chunks(keys)) await txn.delete(batch);
+    });
+  }
+}
+
+// The seed, drawn once and kept sealed under a key the secret gives, so
+// the storage alone opens nothing. A harbor with no secret does not stand.
+export class EdgeCustody extends Custody {
+  readonly #storage: EdgeStorage;
+  readonly #secret: string | undefined;
+  readonly #entropy: Entropy;
+  readonly #key: string;
+  constructor(storage: EdgeStorage, secret: string | undefined, entropy: Entropy = new CryptoEntropy(), root = '') {
+    super();
+    this.#storage = storage;
+    this.#secret = secret;
+    this.#entropy = entropy;
+    this.#key = `${root}${SEED}`;
+  }
+
+  async seed(): Promise<Uint8Array> {
+    if (!this.#secret) throw new Error('the worker holds no NERVUR_SECRET');
+    const key = await hkdf(utf8(this.#secret), SEAL_INFO, 32);
+    return this.#storage.transaction(async (txn) => {
+      const kept = (await txn.get(this.#key)) as { nonce: Uint8Array; sealed: Uint8Array } | undefined;
+      if (kept) {
+        const seed = await decrypt(key, bytesOf(kept.nonce), new Uint8Array(0), bytesOf(kept.sealed));
+        if (seed === null) throw new Error('the seed does not open under this NERVUR_SECRET');
+        return seed;
+      }
+      const seed = this.#entropy.draw(32);
+      const nonce = this.#entropy.draw(12);
+      await txn.put({ [this.#key]: { nonce, sealed: await encrypt(key, nonce, new Uint8Array(0), seed) } });
+      return seed.slice();
+    });
+  }
+}
+
+// One TCP line opened by the worker's `connect`, many asks on it.
+type EdgeSocket = {
+  readonly opened: Promise<unknown>;
+  readonly closed: Promise<unknown>;
+  readonly readable: ReadableStream<Uint8Array>;
+  readonly writable: WritableStream<Uint8Array>;
+  close(): Promise<void>;
+};
+type Connect = (address: { hostname: string; port: number }) => EdgeSocket;
+
+class EdgeLine {
+  readonly #socket: EdgeSocket;
+  readonly #writer: WritableStreamDefaultWriter<Uint8Array>;
+  readonly #waiting = new Map<number, (box: Uint8Array | null) => void>();
+  #next = 1;
+  #closed = false;
+
+  constructor(socket: EdgeSocket, onClose: () => void) {
+    this.#socket = socket;
+    this.#writer = socket.writable.getWriter();
+    const reader = new FrameReader();
+    void (async () => {
+      try {
+        for await (const chunk of socket.readable) {
+          for (const frame of reader.push(new Uint8Array(chunk))) {
+            if (frame.kind === 'ask') continue;
+            const done = this.#waiting.get(frame.id);
+            this.#waiting.delete(frame.id);
+            done?.(frame.kind === 'reply' ? frame.box : null);
+          }
+          if (reader.bad) break;
+        }
+      } catch {
+        // A line that broke answers nothing more.
+      }
+      this.#closed = true;
+      onClose();
+      for (const done of this.#waiting.values()) done(null);
+      this.#waiting.clear();
+      await socket.close().catch(() => undefined);
+    })();
+  }
+
+  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.#writer.write(askFrame(id, pk, box)).catch(() => resolve(null));
+    });
+  }
+
+  close(): Promise<void> {
+    this.#closed = true;
+    return this.#socket.close().catch(() => undefined);
+  }
+}
+
+const sockets = 'cloudflare:sockets';
+const connector = async (): Promise<Connect | null> => {
+  try {
+    return ((await import(/* @vite-ignore */ sockets)) as { connect: Connect }).connect;
+  } catch {
+    return null;
+  }
+};
+
+// Quo over TCP from a worker: it dials, and takes no inbound TCP.
+export const edgeTcp: GroundFaculty = () =>
+  class EdgeTcp extends CarrierFaculty {
+    static override readonly kind: string = TCP;
+    static override asks: Record<string, AskSpec> = {
+      listen: ownerAsk('an edge takes no inbound TCP'),
+      deaf: ownerAsk('listen nowhere'),
+    };
+
+    readonly #lines = new Map<string, Promise<EdgeLine | null>>();
+
+    accepts(address: string): boolean {
+      return tcpAddress(address) !== null;
+    }
+
+    async dial(address: string, pk: string, bytes: Uint8Array): Promise<Dialed> {
+      const at = tcpAddress(address);
+      if (at === null || !isHex(pk, 64)) return UNDIALED;
+      const line = await this.#line(at);
+      return line ? line.ask(unhex(pk), bytes) : UNDIALED;
+    }
+
+    #line({ host, port }: TcpAddress): Promise<EdgeLine | null> {
+      const at = tcpAt(host, port);
+      let line = this.#lines.get(at);
+      if (!line) {
+        line = (async () => {
+          const connect = await connector();
+          if (!connect) return null;
+          try {
+            const socket = connect({ hostname: host, port });
+            await socket.opened;
+            return new EdgeLine(socket, () => this.#lines.delete(at));
+          } catch {
+            return null;
+          }
+        })();
+        this.#lines.set(at, line);
+        void line.then((open) => open ?? this.#lines.delete(at));
+      }
+      return line;
+    }
+
+    override async sleep(): Promise<void> {
+      const lines = [...this.#lines.values()];
+      this.#lines.clear();
+      for (const line of await Promise.all(lines)) await line?.close();
+    }
+
+    listen(): JsonObject {
+      return { error: 'an edge takes no inbound TCP' };
+    }
+
+    deaf(): JsonObject {
+      return { deaf: true };
+    }
+  };
+
+// Where the edge's web carrier listens: the object's own requests, at the
+// host and path its cells name. A port of 0 is the edge's own https.
+const edgeServe = (ground: Ground, listen: WebListen): Promise<WebListener> => {
+  const terrain = (ground as unknown as { terrain?: unknown }).terrain;
+  if (!(terrain instanceof EdgeTerrain)) return Promise.reject(new Error('this harbor stands on no edge'));
+  terrain.listening = listen;
+  const authority = listen.port === 0 ? listen.host : `${tcpAt(listen.host, listen.port).slice('tcp://'.length)}`;
+  const [post, held] = listen.port === 0 ? ['https', 'wss'] : ['http', 'ws'];
+  return Promise.resolve({
+    port: listen.port,
+    at: [`${post}://${authority}${listen.path}`, `${held}://${authority}${listen.path}`],
+    close: () => {
+      if (terrain.listening === listen) terrain.listening = undefined;
+      return Promise.resolve();
+    },
+  });
+};
+
+// What a worker hands a WebSocket upgrade.
+type EdgePair = { 0: EdgeWebSocket; 1: EdgeWebSocket };
+type EdgeWebSocket = WebSocket & { accept(): void };
+
+export type EdgeParts = { readonly given: EdgeGiven; readonly modules?: readonly Module[] };
+
+export class EdgeTerrain extends PointerTerrain {
+  readonly given: EdgeGiven;
+  // Where the web carrier listens now, as the object answers requests.
+  listening: WebListen | undefined;
+  #harbor: Harbor | undefined;
+
+  constructor(parts: EdgeParts) {
+    const entropy = new CryptoEntropy();
+    const { storage } = parts.given.state;
+    super({
+      entropy,
+      loader: new HeldLoader(parts.modules ?? []),
+      custody: new EdgeCustody(storage, parts.given.env.NERVUR_SECRET, entropy),
+      memory: new EdgeMemory(storage),
+      faculties: [edgeTcp, webFaculty(edgeServe), webPush],
+      opens: [TCP_OPENING, WEB_OPENING],
+    });
+    this.given = parts.given;
+  }
+
+  override stand(harbor: Harbor): Promise<void> {
+    this.#harbor = harbor;
+    return Promise.resolve();
+  }
+
+  // One request to the object: a post, or a held line opened, where the
+  // web carrier listens.
+  answer(request: Request): Promise<Response> {
+    const listen = this.listening;
+    const harbor = this.#harbor;
+    if (!listen || !harbor) return Promise.resolve(new Response(null, { status: 404 }));
+    if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') return answerPost(harbor, listen, request);
+    const offered = (request.headers.get('sec-websocket-protocol') ?? '').split(',').map((p) => p.trim());
+    if (new URL(request.url).pathname !== listen.path || !offered.includes('quo')) return Promise.resolve(new Response(null, { status: 400 }));
+    const Pair = (globalThis as unknown as { WebSocketPair: new () => EdgePair }).WebSocketPair;
+    const pair = new Pair();
+    const [client, server] = [pair[0], pair[1]];
+    server.accept();
+    const side = { send: (body: Uint8Array) => server.send(new Uint8Array(body)), close: () => server.close() };
+    server.addEventListener('message', (event: MessageEvent) => answerHeld(harbor, side, typeof event.data === 'string' ? event.data : new Uint8Array(event.data as ArrayBuffer)));
+    return Promise.resolve(new Response(null, { status: 101, webSocket: client, headers: { 'sec-websocket-protocol': 'quo' } } as ResponseInit));
+  }
+}
+
+const isGiven = (value: unknown): value is EdgeGiven => {
+  const given = value as Partial<EdgeGiven> | null;
+  return typeof given?.state?.storage?.transaction === 'function' && typeof given.env === 'object';
+};
+
+// A harbor handed a Durable Object's state and environment.
+export const edgeGround: GroundProbe = {
+  name: EDGE,
+  fits: ({ given }) => isGiven(given),
+  terrain: ({ given, modules }) => new EdgeTerrain({ given: given as EdgeGiven, ...(modules ? { modules } : {}) }),
+};
+
+// A Durable Object class whose every instance is one harbor: opened once
+// per object, with `stood` run on it as the worker's own code, and every
+// request it receives answered by the harbor's web carrier.
+export type HarborObjectClass = new (state: EdgeState, env: EdgeEnv) => { readonly harbor: Promise<Harbor>; fetch(request: Request): Promise<Response> };
+export const harborObject = (modules: readonly Module[], stood?: (harbor: Harbor) => Promise<void>): HarborObjectClass =>
+  class HarborObject {
+    readonly #opening: Promise<Harbor>;
+
+    // The object's harbor, once it stands.
+    get harbor(): Promise<Harbor> {
+      return this.#opening;
+    }
+
+    constructor(state: EdgeState, env: EdgeEnv) {
+      addGround(edgeGround);
+      // Opened inside the object's block, so no request reaches it half
+      // open and its storage answers the opening.
+      this.#opening = state.blockConcurrencyWhile(async () => {
+        const harbor = await Harbor.open({ modules, given: { state, env } });
+        await stood?.(harbor);
+        return harbor;
+      });
+    }
+
+    async fetch(request: Request): Promise<Response> {
+      const harbor = await this.#opening;
+      return (harbor.terrain as EdgeTerrain).answer(request);
+    }
+  };

package/src/edge.ts

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur` as a Workers bundle reads it: the main entry, with the edge
+// ground added, so `Harbor.open({ given: { state, env } })` in a Durable
+// Object keeps a harbor in its storage.
+import { edgeGround } from './edge/index.ts';
+import { addGround } from './harbor/index.ts';
+
+export * from './index.ts';
+
+addGround(edgeGround);

package/src/folder/index.ts

@@ -1,109 +1,106 @@
 // SPDX-License-Identifier: Apache-2.0
-// A harbor on a disk, for local proof: `nervur/folder`, the one entry that
+// A harbor on a disk, for local proof: `nervur/folder`, an entry that
 // names a platform.
 //
-//   <root>/<ward>/seed               the ward's seed, as hex
-//   <root>/<ward>/ward.json          the ward's head
-//   <root>/<ward>/<key>/being.json   one being: class, cells, relations
+//   <root>/seed              the harbor's seed, as hex
+//   <root>/<place>/<entry>   one sealed entry of the harbor's memory
+//   <root>/<place>/keep      a keep of that place, until it is applied
 //
-// A folder name is the ward's name or the being's key, escaped, so no name
-// reaches outside its folder. A file is written whole, beside itself and
-// then renamed over, so a crash leaves the last kept copy. Seeds are plain
-// files: custody that seals them is a terrain's, in the dock.
+// Places and entries are the hex names the kit chose, so no name reaches
+// outside its folder, and the disk shows no ward's name. A file is written
+// whole, beside itself and then renamed over.
+//
+// A keep is whole, by its own file: the whole keep is written under `keep`
+// and renamed over, then its entries are written and removed one by one,
+// then `keep` goes. A read applies a `keep` it finds first, and the same
+// bytes written twice leave the same place, so a keep that a crash cut
+// short finishes at the next read. A place read before its `keep` landed
+// has none of it. `keep` is no hex name, so it is never an entry.
+//
+// The seed is a plain file: custody that seals it is a terrain's.
 import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { hex, isHex, unhex } from '../crypto/index.ts';
-import { Custody, Memory, type Entropy, type Rows } from '../contract/index.ts';
-import { HEAD_ROW } from '../ward/index.ts';
-
-const HEAD = 'ward.json';
-const BEING = 'being.json';
-
-export const folderName = (name: string): string => encodeURIComponent(name).replaceAll('.', '%2E').replaceAll('*', '%2A') || '%';
-const nameOf = (folder: string): string => (folder === '%' ? '' : decodeURIComponent(folder));
+import { Custody, Memory, type Entropy } from '../contract/index.ts';
 
 const missing = (e: unknown): boolean => (e as { code?: string }).code === 'ENOENT';
 
-const readJson = async (path: string): Promise<unknown> => {
-  try {
-    return JSON.parse(await readFile(path, 'utf8')) as unknown;
-  } catch (e) {
-    if (missing(e)) return undefined;
-    throw e;
-  }
+// One keep as a place's `keep` file holds it: every entry's bytes as hex,
+// or null where it goes.
+export type Keep = Record<string, string | null>;
+const KEEP = 'keep';
+
+const named = (name: string): string => {
+  if (!isHex(name) || name === '') throw new Error(`${name} is not a name the kit chose`);
+  return name;
 };
 
-const writeWhole = async (path: string, text: string): Promise<void> => {
-  await writeFile(`${path}.next`, text, { mode: 0o600 });
+const writeWhole = async (path: string, bytes: Uint8Array | string): Promise<void> => {
+  await writeFile(`${path}.next`, bytes, { mode: 0o600 });
   await rename(`${path}.next`, path);
 };
 
-class FolderRows implements Rows {
-  readonly rows: Record<string, unknown>;
-  readonly #dir: string;
-  readonly #told = new Set<string>();
-  #line: Promise<boolean> = Promise.resolve(true);
-
-  constructor(dir: string, rows: Record<string, unknown>) {
-    this.#dir = dir;
-    this.rows = rows;
-  }
+export class FolderMemory extends Memory {
+  readonly root: string;
+  #line: Promise<unknown> = Promise.resolve();
 
-  told(row: string): void {
-    this.#told.add(row);
+  constructor(root: string) {
+    super();
+    this.root = root;
   }
 
-  // Every row told since the last keep, written in order, 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;
+  // The entries as the disk holds them now, a keep left unapplied first.
+  // A file that is not an entry, one still being written among them, is
+  // not read.
+  async read(place: string): Promise<Map<string, Uint8Array>> {
+    const dir = join(this.root, named(place));
+    await this.apply(dir);
+    const out = new Map<string, Uint8Array>();
+    const files = await readdir(dir, { withFileTypes: true }).catch((e: unknown) => (missing(e) ? [] : Promise.reject(e)));
+    for (const file of files) {
+      if (!file.isFile() || !isHex(file.name) || file.name === '') continue;
+      out.set(file.name, new Uint8Array(await readFile(join(dir, file.name))));
+    }
+    return out;
   }
 
-  async #write(told: string[]): Promise<boolean> {
-    await mkdir(this.#dir, { recursive: true, mode: 0o700 });
-    const beings = (this.rows.beings ?? {}) as Record<string, unknown>;
-    for (const row of told) {
-      if (row === HEAD_ROW) {
-        await writeWhole(join(this.#dir, HEAD), JSON.stringify(this.rows.ward ?? null));
-        continue;
-      }
-      const dir = join(this.#dir, folderName(row));
-      if (!Object.hasOwn(beings, row)) {
-        await rm(dir, { recursive: true, force: true });
-        continue;
-      }
+  // One keep at a time, written whole under `keep` before any entry moves.
+  async write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void> {
+    const dir = join(this.root, named(place));
+    const keep: Keep = {};
+    for (const [name, bytes] of entries) keep[named(name)] = bytes === null ? null : hex(bytes);
+    const kept = this.#line.then(async () => {
       await mkdir(dir, { recursive: true, mode: 0o700 });
-      await writeWhole(join(dir, BEING), JSON.stringify(beings[row]));
-    }
-    return true;
+      await writeWhole(join(dir, KEEP), JSON.stringify(keep));
+      await this.apply(dir, keep);
+    });
+    this.#line = kept.catch(() => undefined);
+    await kept;
   }
-}
 
-export class FolderMemory extends Memory {
-  readonly root: string;
+  // Every folder of the root that is a place.
+  async places(): Promise<string[]> {
+    const files = await readdir(this.root, { withFileTypes: true }).catch((e: unknown) => (missing(e) ? [] : Promise.reject(e)));
+    return files.filter((f) => f.isDirectory() && isHex(f.name) && f.name !== '').map((f) => f.name);
+  }
 
-  constructor(root: string) {
-    super();
-    this.root = root;
+  forget(place: string): Promise<void> {
+    return rm(join(this.root, named(place)), { recursive: true, force: true });
   }
 
-  // The rows as the disk holds them now.
-  async open(name: string): Promise<Rows> {
-    const dir = join(this.root, folderName(name));
-    const rows: Record<string, unknown> = {};
-    const head = await readJson(join(dir, HEAD));
-    if (head !== undefined) rows.ward = head;
-    const beings: Record<string, unknown> = {};
-    const entries = await readdir(dir, { withFileTypes: true }).catch((e: unknown) => (missing(e) ? [] : Promise.reject(e)));
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const row = await readJson(join(dir, entry.name, BEING));
-      if (row !== undefined) beings[nameOf(entry.name)] = row;
+  // The keep a folder holds, applied and then gone. Writing the same bytes
+  // again leaves the same place, so applying twice is applying once.
+  protected async apply(dir: string, keep?: Keep): Promise<void> {
+    const found = keep ?? (await readFile(join(dir, KEEP), 'utf8').then((text) => JSON.parse(text) as Keep, () => null));
+    if (found === null) return;
+    for (const [name, written] of Object.entries(found)) {
+      const path = join(dir, named(name));
+      if (written === null) await rm(path, { force: true });
+      else await writeWhole(path, unhex(written));
     }
-    if (head !== undefined || Object.keys(beings).length > 0) rows.beings = beings;
-    return new FolderRows(dir, rows);
+    await rm(join(dir, KEEP), { force: true });
+    const left = await readdir(dir).catch((e: unknown) => (missing(e) ? [] : Promise.reject(e)));
+    if (left.length === 0) await rm(dir, { recursive: true, force: true });
   }
 }
 
@@ -117,9 +114,10 @@ export class FolderCustody extends Custody {
     this.#entropy = entropy;
   }
 
-  async seed(name: string): Promise<Uint8Array> {
-    const dir = join(this.root, folderName(name));
-    const path = join(dir, 'seed');
+  // The seed the folder holds, or a drawn one written there the first time.
+  // Two first asks at once keep the one written first.
+  async seed(): Promise<Uint8Array> {
+    const path = join(this.root, 'seed');
     const kept = await readFile(path, 'utf8').catch((e: unknown) => (missing(e) ? undefined : Promise.reject(e)));
     if (kept !== undefined) {
       const text = kept.trim();
@@ -127,8 +125,13 @@ export class FolderCustody extends Custody {
       return unhex(text);
     }
     const seed = this.#entropy.draw(32);
-    await mkdir(dir, { recursive: true, mode: 0o700 });
-    await writeFile(path, `${hex(seed)}\n`, { mode: 0o600, flag: 'wx' });
+    await mkdir(this.root, { recursive: true, mode: 0o700 });
+    try {
+      await writeFile(path, `${hex(seed)}\n`, { mode: 0o600, flag: 'wx' });
+    } catch (e) {
+      if ((e as { code?: string }).code === 'EEXIST') return this.seed();
+      throw e;
+    }
     return seed;
   }
 }

package/src/harbor/carrying.ts

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+// A carrier is a faculty. It speaks the schemes of the addresses it dials,
+// dials an address when the harbor carries a box there, and listens where
+// its cells say, handing each box it hears to the harbor. The harbor keeps
+// every route and walks it in order, handing each address to the carrier
+// that speaks its scheme.
+//
+// A ground ships its carriers as classes the terrain names, each made for
+// one harbor, so the class holds the harbor it hands boxes to. They are
+// the kit's, of kinds under `org.nervur.`, and the dock opens them as
+// faculties, at genesis where the terrain says, and on the root's `open`.
+import { Faculty, type BeingClass } from '../being/index.ts';
+
+// What a carrier hands a box it heard to.
+export interface Ground {
+  arrive(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+}
+
+// A carrier class of a ground, made for one harbor.
+export type GroundFaculty = (ground: Ground) => BeingClass;
+
+// Beside a reply and nothing, a dial answers `undialed` when the address
+// could not be reached at all, so the harbor tries the next one. A box a
+// line took may have been heard, so after it no other address is tried.
+export const UNDIALED = Symbol('undialed');
+export type Dialed = Uint8Array | null | typeof UNDIALED;
+
+export abstract class CarrierFaculty extends Faculty {
+  static override readonly kind: string = 'org.nervur.carrier';
+
+  // Whether this carrier dials an address, written as its carrier writes it.
+  abstract accepts(address: string): boolean;
+  abstract dial(address: string, pk: string, bytes: Uint8Array): Promise<Dialed>;
+
+  // The addresses it listens at now.
+  listening(): string[] {
+    return [];
+  }
+
+  // Whether it answers for a ward pk no door of this harbor holds, as a
+  // relay does, and its answer.
+  relays(_pk: string): boolean {
+    return false;
+  }
+  relay(_pk: string, _bytes: Uint8Array): Promise<Uint8Array | null> {
+    return Promise.resolve(null);
+  }
+
+  // Once the harbor has unpacked, and once before it closes.
+  awake(): Promise<void> {
+    return Promise.resolve();
+  }
+  sleep(): Promise<void> {
+    return Promise.resolve();
+  }
+}