nervur 0.20.1 → 0.20.2

package/dist/tcp/frame.js

@@ -62,13 +62,3 @@ export class FrameReader {
         return out;
     }
 }
-// "host:port" to its parts, or null. A host in brackets is an IPv6 address.
-export const parseAt = (at) => {
-    if (typeof at !== 'string')
-        return null;
-    const m = /^(?:\[([^\]]+)\]|([^:[\]]+)):(\d{1,5})$/.exec(at);
-    if (!m)
-        return null;
-    const port = Number(m[3]);
-    return port > 0 && port < 65_536 ? { host: m[1] ?? m[2], port } : null;
-};

package/dist/tcp/index.d.ts

@@ -1,12 +1,16 @@
 import { Carrier } from '../contract/index.ts';
-export { parseAt } from './frame.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: string | null): boolean;
+    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 {
@@ -16,3 +20,5 @@ export declare class TcpListener {
     get at(): string;
     close(): Promise<void>;
 }
+export { TCP, TCP_OPENING };
+export declare const tcpFaculty: GroundFaculty;

package/dist/tcp/index.js

@@ -3,20 +3,26 @@
 // sockets.
 //
 //   TcpCarrier    a Carrier that dials: bytes to a ward pk go in an ask
-//                 frame to the address its book holds for that pk
+//                 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
+//                 among them, at a `tcp://` address
 //
-// Where a ward is reached is the carrier's own, and never on the wire. A
-// connection is opened per address, carries many asks at once, and is
-// dropped when either side closes it; the next ask dials again.
+// 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 { askFrame, FrameReader, nothingFrame, parseAt, replyFrame } from './frame.js';
-export { parseAt } from './frame.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;
-class Dialed {
+// 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();
@@ -47,7 +53,7 @@ class Dialed {
     static open(host, port, onClose) {
         return new Promise((resolve) => {
             const socket = connect({ host, port });
-            socket.once('connect', () => resolve(new Dialed(socket, onClose)));
+            socket.once('connect', () => resolve(new Line(socket, onClose)));
             socket.once('error', () => {
                 socket.destroy();
                 resolve(null);
@@ -71,31 +77,55 @@ class Dialed {
 export class TcpCarrier extends Carrier {
     #routes = new Map();
     #lines = new Map();
-    // The address a ward pk is reached at, replacing any before, or null to
-    // forget it.
+    // 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) || (at !== null && parseAt(at) === null))
+        if (!isHex(pk, 64))
             return false;
         if (at === null)
-            this.#routes.delete(pk);
-        else
-            this.#routes.set(pk, at);
+            return this.#routes.delete(pk) || true;
+        const mine = tcpAddresses(at);
+        if (mine.length === 0)
+            return false;
+        this.#routes.set(pk, mine);
         return true;
     }
-    // Nothing where the pk has no route, the address is not reached, or the
+    // 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.
-    async carry(pk, bytes) {
-        const at = this.#routes.get(pk);
-        if (at === undefined)
-            return null;
-        const line = await this.#line(at);
-        return line ? line.ask(unhex(pk), bytes) : null;
-    }
-    #line(at) {
+    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) {
-            const { host, port } = parseAt(at);
-            line = Dialed.open(host, port, () => this.#lines.delete(at)).then((dialed) => {
+            line = Line.open(host, port, () => this.#lines.delete(at)).then((dialed) => {
                 if (!dialed)
                     this.#lines.delete(at);
                 return dialed;
@@ -127,9 +157,10 @@ export class TcpListener {
             listener.#server.listen(port, host, () => resolve(listener));
         });
     }
+    // The `tcp://host:port` address this listener answers at.
     get at() {
         const address = this.#server.address();
-        return address.family === 'IPv6' ? `[${address.address}]:${address.port}` : `${address.address}:${address.port}`;
+        return tcpAt(address.address, address.port);
     }
     #serve(socket) {
         this.#sockets.add(socket);
@@ -162,3 +193,68 @@ export class TcpListener {
         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,6 +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,5 +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/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;

package/dist/ward/stance.js

@@ -87,7 +87,7 @@ export class WardStance {
         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;
@@ -113,6 +113,8 @@ export class WardStance {
         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/dist/ward/ward-being.d.ts

@@ -18,6 +18,7 @@ export type WardBeingStance = Stance & {
 };
 export declare const pilots: (asker: Asker, notes: JsonObject | undefined) => boolean;
 export declare const ownerAsk: (description: string, input?: JsonObject) => AskSpec;
+export declare const rootAsk: (description: string, input?: JsonObject) => AskSpec;
 export declare const PILOT = "org.nervur.pilot";
 export declare class WardBeing extends Being {
     static readonly kind: string;
@@ -28,7 +29,7 @@ export declare class WardBeing extends Being {
     own(args: JsonObject): Promise<JsonObject>;
     disown(args: JsonObject): JsonObject;
     boot(args: JsonObject): Promise<JsonObject>;
-    unboot(args: JsonObject): JsonObject;
+    unboot(args: JsonObject): JsonObject | Promise<JsonObject>;
     public(args: JsonObject): JsonObject;
     invite(args: JsonObject): Promise<JsonObject>;
     ask(args: JsonObject): Promise<JsonObject>;

package/dist/ward/ward-being.js

@@ -9,7 +9,7 @@ export const pilots = (asker, notes) => asker.id === OWNER || notes?.owner === t
 export const ownerAsk = (description, input = {}) => ({ description, input: { type: 'object', ...input }, for: pilots });
 // An ask the root alone may make, so a carried key pilots but never hands
 // piloting on.
-const rootAsk = (description, input = {}) => ({ description, input: { type: 'object', ...input }, for: (asker) => asker.id === OWNER });
+export const rootAsk = (description, input = {}) => ({ description, input: { type: 'object', ...input }, for: (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';

package/dist/ward/ward.d.ts

@@ -16,7 +16,12 @@ export type WardParts = {
     readonly carrier: Carrier;
     readonly root?: (stance: WardBeingStance) => WardBeing;
     readonly dock?: Invitation;
+    readonly routes?: Routes;
 };
+export interface Routes {
+    reach(): readonly string[];
+    learn(ward: string, at: readonly string[]): Promise<void>;
+}
 export declare const DOCK = "dock";
 export interface Lender {
     offer(contract: string): Promise<Invitation | null>;
@@ -41,6 +46,8 @@ export declare class Ward implements Behind, Inside {
     send(pk: string, bytes: Uint8Array): Promise<Uint8Array | 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>;
     live(key: string, row: BeingRow): boolean;
     boot(maker: string, className: string, key: string, id?: string): Promise<string | null>;
 }

package/dist/ward/ward.js

@@ -177,6 +177,12 @@ export class Ward {
             return own.being.withdraw(contract, heir);
         await own.stance.standings.get(DOCK)?.ask('retract', { contract, heir });
     }
+    reach() {
+        return this.#parts.routes?.reach() ?? [];
+    }
+    learn(ward, at) {
+        return this.#parts.routes?.learn(ward, at) ?? Promise.resolve();
+    }
     live(key, row) {
         return this.#residents.get(key)?.row === row;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nervur",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "description": "Nervur's kit of Quo: an object asks another object and gets an answer, without knowing where it is.",
   "keywords": [
     "quo",
@@ -18,8 +18,23 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "workerd": "./dist/edge.js",
+      "browser": "./dist/browser.js",
+      "node": "./dist/node.js",
       "default": "./dist/index.js"
     },
+    "./edge": {
+      "types": "./dist/edge/index.d.ts",
+      "default": "./dist/edge/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "default": "./dist/browser/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "default": "./dist/node/index.js"
+    },
     "./folder": {
       "types": "./dist/folder/index.d.ts",
       "default": "./dist/folder/index.js"
@@ -27,13 +42,17 @@
     "./tcp": {
       "types": "./dist/tcp/index.d.ts",
       "default": "./dist/tcp/index.js"
+    },
+    "./http": {
+      "types": "./dist/http/index.d.ts",
+      "default": "./dist/http/index.js"
     }
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "check": "tsc -p tsconfig.json && npm run build && node ../../test.mjs \"test/unit/*.test.ts\" \"test/e2e/*.test.ts\"",
     "deep": "node ../../test.mjs \"test/terrain/*.test.ts\"",
-    "cover": "node --test --test-timeout=60000 --experimental-test-coverage --test-coverage-exclude=\"**/dist/**\" --test-coverage-exclude=\"**/test/**\" --test-coverage-exclude=\"**/src/stand/**\" --test-coverage-exclude=\"../../quo/**\" --test-coverage-lines=99 --test-coverage-branches=93 --test-coverage-functions=95 \"test/unit/*.test.ts\" \"test/e2e/*.test.ts\"",
+    "cover": "node --test --test-timeout=60000 --experimental-test-coverage --test-coverage-exclude=\"**/dist/**\" --test-coverage-exclude=\"**/test/**\" --test-coverage-exclude=\"**/src/stand/**\" --test-coverage-exclude=\"**/src/browser/**\" --test-coverage-exclude=\"**/src/edge/**\" --test-coverage-exclude=\"../../quo/**\" --test-coverage-lines=99 --test-coverage-branches=93 --test-coverage-functions=95 \"test/unit/*.test.ts\" \"test/e2e/*.test.ts\"",
     "prepublishOnly": "test \"$NERVUR_GATED\" = 1 || { echo 'a publish is /release, from the root, on the human'\"'\"'s word' >&2; exit 1; }"
   },
   "engines": {

package/src/browser/index.ts

@@ -0,0 +1,207 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur/browser`: the browser ground, in a page or a worker. A harbor
+// keeps its sealed memory and its seed in one IndexedDB database, named
+// by `where`, speaks the web, and holds its database to one run with a
+// Web Lock of the same name.
+//
+//   entries   one sealed entry per key [place, name]
+//   custody   the seed, sealed under an AES-GCM key the engine never
+//             hands out, itself kept as the engine keeps a CryptoKey
+//
+// A keep is one transaction, so it is whole or nothing by IndexedDB's own
+// rule.
+import { Custody, Memory, type Entropy, type Module } from '../contract/index.ts';
+import type { GroundProbe } from '../harbor/index.ts';
+import { webFaculty, WEB_OPENING, webPush } from '../line/index.ts';
+import { CryptoEntropy, HeldLoader, PointerTerrain } from '../pointer/index.ts';
+
+export { ringAll, rootOf, serveWorker, type Reaching } from './worker.ts';
+
+export const BROWSER = 'browser';
+// The database a harbor keeps itself in unless named.
+export const BROWSER_HARBOR = 'nervur';
+
+const ENTRIES = 'entries';
+const CUSTODY = 'custody';
+const SEED = 'seed';
+// Past every lowercase hex name, so [place, END] bounds a place's keys.
+const END = '￿';
+
+type Sealed = { key: CryptoKey; iv: Uint8Array<ArrayBuffer>; sealed: ArrayBuffer };
+
+const done = <T>(request: IDBRequest<T>): Promise<T> =>
+  new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('IndexedDB refused'));
+  });
+
+// A transaction's end. A request that fails aborts it, and the abort
+// carries that request's error.
+const finished = (tx: IDBTransaction): Promise<void> =>
+  new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onabort = () => reject(tx.error ?? new Error('the keep was aborted'));
+  });
+
+// One database, opened once per body and made on first open.
+class Database {
+  readonly name: string;
+  #open: Promise<IDBDatabase> | undefined;
+  constructor(name: string) {
+    this.name = name;
+  }
+  get(): Promise<IDBDatabase> {
+    this.#open ??= new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.name, 1);
+      request.onupgradeneeded = () => {
+        request.result.createObjectStore(ENTRIES);
+        request.result.createObjectStore(CUSTODY);
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error ?? new Error(`${this.name} did not open`));
+    });
+    return this.#open;
+  }
+  async close(): Promise<void> {
+    const open = this.#open;
+    this.#open = undefined;
+    if (open) (await open).close();
+  }
+}
+
+export class IdbMemory extends Memory {
+  readonly #db: Database;
+  constructor(name: string = BROWSER_HARBOR) {
+    super();
+    this.#db = new Database(name);
+  }
+
+  // The database it keeps in.
+  get name(): string {
+    return this.#db.name;
+  }
+
+  async read(place: string): Promise<Map<string, Uint8Array>> {
+    const store = (await this.#db.get()).transaction(ENTRIES).objectStore(ENTRIES);
+    const range = IDBKeyRange.bound([place, ''], [place, END]);
+    const [keys, values] = await Promise.all([done(store.getAllKeys(range)), done(store.getAll(range))]);
+    return new Map(keys.map((key, i) => [(key as [string, string])[1], new Uint8Array(values[i] as ArrayBuffer)]));
+  }
+
+  async write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void> {
+    const tx = (await this.#db.get()).transaction(ENTRIES, 'readwrite');
+    const kept = finished(tx);
+    const store = tx.objectStore(ENTRIES);
+    try {
+      for (const [name, bytes] of entries) this.put(store, [place, name], bytes === null ? null : bytes.slice().buffer);
+    } catch (e) {
+      tx.abort();
+      await kept.catch(() => undefined);
+      throw e;
+    }
+    await kept;
+  }
+
+  // One entry of a keep: its bytes, or null where it goes.
+  protected put(store: IDBObjectStore, key: [string, string], bytes: ArrayBuffer | null): void {
+    if (bytes === null) store.delete(key);
+    else store.put(bytes, key);
+  }
+
+  async places(): Promise<string[]> {
+    const keys = await done((await this.#db.get()).transaction(ENTRIES).objectStore(ENTRIES).getAllKeys());
+    return [...new Set(keys.map((key) => (key as [string, string])[0]))];
+  }
+
+  async forget(place: string): Promise<void> {
+    const tx = (await this.#db.get()).transaction(ENTRIES, 'readwrite');
+    tx.objectStore(ENTRIES).delete(IDBKeyRange.bound([place, ''], [place, END]));
+    await finished(tx);
+  }
+
+  close(): Promise<void> {
+    return this.#db.close();
+  }
+}
+
+export class IdbCustody extends Custody {
+  readonly #db: Database;
+  readonly #entropy: Entropy;
+  constructor(name: string = BROWSER_HARBOR, entropy: Entropy = new CryptoEntropy()) {
+    super();
+    this.#db = new Database(name);
+    this.#entropy = entropy;
+  }
+
+  // The seed the database holds, or a drawn one sealed there the first
+  // time. Two first asks at once keep the one added first.
+  async seed(): Promise<Uint8Array> {
+    const db = await this.#db.get();
+    const kept = (await done(db.transaction(CUSTODY).objectStore(CUSTODY).get(SEED))) as Sealed | undefined;
+    if (kept) return new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: kept.iv }, kept.key, kept.sealed));
+    const seed = this.#entropy.draw(32);
+    const key = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+    const iv = new Uint8Array(this.#entropy.draw(12));
+    const sealed = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, new Uint8Array(seed));
+    const tx = db.transaction(CUSTODY, 'readwrite');
+    tx.objectStore(CUSTODY).add({ key, iv, sealed } satisfies Sealed, SEED);
+    try {
+      await finished(tx);
+    } catch (e) {
+      if ((e as { name?: string }).name === 'ConstraintError') return this.seed();
+      throw e;
+    }
+    return seed;
+  }
+
+  close(): Promise<void> {
+    return this.#db.close();
+  }
+}
+
+export type BrowserParts = { readonly where?: string; readonly modules?: readonly Module[] };
+
+// A harbor of the browser: its database, the web opened at genesis, Web
+// Push beside it, and one run to a database, held by a Web Lock where the
+// engine has them.
+export class BrowserTerrain extends PointerTerrain {
+  readonly where: string;
+  #release: (() => void) | undefined;
+
+  constructor(parts: BrowserParts = {}) {
+    const where = parts.where ?? BROWSER_HARBOR;
+    const entropy = new CryptoEntropy();
+    super({ entropy, loader: new HeldLoader(parts.modules ?? []), custody: new IdbCustody(where, entropy), memory: new IdbMemory(where), faculties: [webFaculty(), webPush], opens: [WEB_OPENING] });
+    this.where = where;
+  }
+
+  override async claim(): Promise<void> {
+    const locks = (globalThis as { navigator?: { locks?: LockManager } }).navigator?.locks;
+    if (!locks) return;
+    const held = await new Promise<boolean>((granted) => {
+      void locks.request(`nervur:${this.where}`, { ifAvailable: true }, (lock) => {
+        if (lock === null) {
+          granted(false);
+          return undefined;
+        }
+        granted(true);
+        return new Promise<void>((release) => (this.#release = release));
+      });
+    });
+    if (!held) throw new Error(`a harbor is already open on ${this.where}`);
+  }
+
+  override async release(): Promise<void> {
+    this.#release?.();
+    this.#release = undefined;
+    await (this.memory as IdbMemory).close();
+    await (this.custody as IdbCustody).close();
+  }
+}
+
+// A page or a worker with IndexedDB and Web Crypto.
+export const browserGround: GroundProbe = {
+  name: BROWSER,
+  fits: () => typeof indexedDB !== 'undefined' && typeof crypto?.subtle !== 'undefined',
+  terrain: ({ modules, where }) => new BrowserTerrain({ ...(where ? { where } : {}), ...(modules ? { modules } : {}) }),
+};