nervur 0.20.0 → 0.20.2

package/README.md

@@ -18,14 +18,51 @@ Node 22.18 or later. The main entry imports no platform, so it runs in a
 browser, Deno, Bun and workerd as well. `nervur/folder` keeps a harbor on
 a disk and needs Node's file system.
 
+## A harbor where you run
+
+```js
+import { Harbor } from 'nervur';
+import * as greetings from './greetings.js';
+
+const harbor = await Harbor.open({ modules: [greetings] });
+```
+
+With no terrain, the harbor picks its ground's bodies itself. In Node it
+keeps itself in a folder, `where` if you name one, else `$NERVUR_DIR`,
+else `~/.nervur`, speaks TCP and, where you open them, the web and Web
+Push, and serves its root line, so the `nervur` command below asks it
+while it stands. A folder opens in one run at a time. Bundled for a
+browser, in a page or a worker, it keeps itself in the IndexedDB
+database `where` names, else `nervur`, its seed sealed under a key the
+browser never hands out, speaks the web, and opens in one run at a time.
+On Cloudflare Workers it is one Durable Object:
+
+```js
+import { harborObject } from 'nervur/edge';
+import * as greetings from './greetings.js';
+
+export const Harbor = harborObject([greetings], async (harbor) => {
+  // the worker's own code is the root: runs once the harbor stands
+});
+```
+
+Each object keeps its harbor in its storage, its seed sealed under the
+worker's `NERVUR_SECRET`, answers Quo over the web from its requests,
+and asks over TCP and the web. Anywhere else it lives as long as its
+process and speaks the web. Hand in a terrain, as below, and that one
+is used.
+
 ## A world in one process
 
 ```js
 import { Being, Faculty, World } from 'nervur';
 
-// A contract, and a faculty that fulfils it.
-class Clock extends Faculty {}
+// A contract, and a faculty that fulfils it. Every class names its kind.
+class Clock extends Faculty {
+  static kind = 'org.example.clock';
+}
 class SystemTime extends Clock {
+  static kind = 'org.example.system-time';
   static asks = { now: {} };
   now() {
     return { now: Date.now() };
@@ -34,6 +71,7 @@ class SystemTime extends Clock {
 
 // A being, who lends a clock by its contract.
 class Greeter extends Being {
+  static kind = 'org.example.greeter';
   static asks = { hello: {} };
   async hello(args, asker) {
     if (!this.stance.standings.get('clock')) await this.stance.lend(Clock, 'clock');
@@ -42,42 +80,213 @@ class Greeter extends Being {
   }
 }
 
+// The module these classes are: its name, its version, its classes.
+const greetings = { module: 'org.example.greetings', version: '1.0.0', classes: [SystemTime, Greeter] };
+
+// A harbor whose terrain can load that module, and whose catalogue runs it.
 const world = new World();
-const harbor = await world.harbor('home', [SystemTime, Greeter]);
-await harbor.root('open', { key: 'clock', class: 'SystemTime' });
+const harbor = await world.harbor('home', [greetings]);
+await harbor.root('ask', { being: 'catalogue', method: 'add', args: { from: 'org.example.greetings' } });
+await harbor.root('open', { key: 'clock', class: 'org.example.system-time' });
 await harbor.root('host', { ward: 'alice' });
-await harbor.ward('alice').root('boot', { key: 'greeter', class: 'Greeter' });
+await harbor.ward('alice').root('boot', { key: 'greeter', class: 'org.example.greeter' });
 ```
 
 A second harbor in the same world takes an invitation on the greeter and
 asks it through the world, sealed as Quo's bytes. `world.restart('home')`
 opens the harbor again from what its memory kept.
 
+## Kinds
+
+A row keeps the kind of the class a being is born of, and a being lends
+by a contract's kind. A kind is declared on the class, because a bundler
+renames classes. It is a domain you own, reversed, then a name, as Apple
+and Matrix name things: `com.acme.shop`. Every segment is lowercase
+letters, digits and `-`, and there are three at least. Each class
+declares its own: a subclass that stands, and every contract between a
+faculty and `Faculty`. `org.nervur.` is the kit's, and `org.example.` is
+for examples like the one above. A module's classes stand under its own
+domain: `com.acme.shop` stands `com.acme.*` kinds. A harbor refuses a
+module in which one kind names two classes or two contracts, or names a
+class and a contract.
+
+## Modules
+
+Your classes come in modules: `{ module, version, classes }`, a module
+named as a kind is. A harbor's catalogue is a faculty of its own, and her
+cells name the modules the harbor runs. `add { from }` runs the module
+the terrain's loader finds there, and `remove { module }` stops one no
+being stands on. A restart loads every module she names and refuses to
+stand when one is missing. A module found at a new version wakes, and
+`modules` shows the version kept and the version running.
+
 ## The onion
 
-1. The terrain gives the box ward's seed and memory.
-2. The box ward unpacks, its ward-being the dock.
-3. Its faculties are born from their rows.
-4. Every ward the dock hosts unpacks.
-5. In every ward, the ward-being first, then each being from her row.
+A harbor is one package. Only the seed and the terrain's bodies, its
+loader among them, stand outside it.
+
+1. The terrain gives the harbor's seed, which opens its memory. The
+   terrain keeps that memory as sealed bytes and reads none of it.
+2. The box ward unpacks under the seed, its ward-being the dock.
+3. The catalogue wakes, and loads every module she names.
+4. The other faculties are born from their rows.
+5. The routes the dock keeps are handed to the carrier.
+6. Every ward the dock hosts unpacks, under the seed the dock keeps for it.
+7. In every ward, the ward-being first, then each being from her row.
 
-Cells decide what stands. The classes you hand a harbor only resolve a
-name a row keeps. Opening a harbor on empty memory is its genesis, and
-the root's asks write the rest: `open`, `host`, and `boot` on a ward.
+Cells decide what stands. The modules only resolve a kind a row keeps.
+Opening a harbor on empty memory is its genesis: the dock stands the
+catalogue, and the root's asks write the rest: `add` on the catalogue,
+`open`, `host`, `route`, and `boot` on a ward. `host { ward, seed? }`
+stands a ward under a seed you name, or a drawn one.
 
 ## What it holds
 
 - **Being, Faculty.** What you extend. A faculty's contract is its class
   and every class between it and `Faculty`.
-- **Entropy, Clock, Custody, Memory, Carrier.** The contracts a terrain
-  fulfils. Each has one suite, and every body that fulfils it passes it.
-- **Harbor, Terrain, Registry, Dock, WardBeing.** The onion.
-- **World, PointerTerrain** and the pointer bodies. A whole world with
-  this package alone.
+- **Entropy, Clock, Custody, Memory, Carrier, Loader.** The contracts a
+  terrain fulfils. Each has one suite, and every body that fulfils it
+  passes it.
+- **Harbor, Terrain, Dock, Catalogue, Registry, WardBeing.** The onion.
+- **World, PointerTerrain** and the pointer bodies, `HeldLoader` among
+  them. A whole world with this package alone.
+- **addGround, grounds**: the grounds `Harbor.open()` tries, and a way to
+  add your own.
+- **NodeTerrain**, from `nervur/node`: the Node ground's terrain, for a
+  folder you name in code.
+- **BrowserTerrain, IdbMemory, IdbCustody**, from `nervur/browser`: the
+  browser ground's terrain and bodies. `serveWorker(Harbor.open())` at
+  the top of a shared or service worker holds one harbor for every tab,
+  each tab asks it with `rootOf(worker)`, and a push the service worker
+  hears makes every relay client `ring`.
 - **FolderMemory, FolderCustody**, from `nervur/folder`.
+- **TcpCarrier, TcpListener**, from `nervur/tcp`: Quo over TCP. Route a
+  ward pk to its `tcp://host:port` addresses on the carrier, hand the
+  listener your harbor, and harbors in two processes, or a harbor and
+  another kit, speak. `tcpFaculty` is the same carrier as a faculty of a
+  harbor.
+- **WebDialer, webFaculty**: Quo over the web, a post to `https://` or a
+  held line to `wss://`, in any engine with `fetch` and WebSocket.
+  `webServe` and `webGround`, from `nervur/http`, listen for it on Node.
+
+- **The relay**, `org.nervur.relay` and `org.nervur.relay-client`, in
+  every harbor: a harbor nobody can dial is reached through one that
+  can, by relations alone. See "A harbor nobody dials" below.
+- **Push, webPush**: a ring with no content, as Web Push sends it,
+  signed with VAPID, on fetch and Web Crypto.
+
+Carriers such as MCP, and every screen, are `@nervur-org/*`'s, as
+classes fulfilling these contracts.
+
+## The command
+
+`nervur` stands a harbor on this machine: its seed and sealed memory in a
+folder, Quo over TCP as its carrier. A module is a file that exports
+`module`, `version` and `classes`.
+
+```sh
+nervur init  --dir ./harbor
+nervur module add ./greetings.js --dir ./harbor
+nervur serve --dir ./harbor --port 7000
+nervur reach tcp://harbor.example:7000 --dir ./harbor
+nervur open web org.nervur.web --dir ./harbor
+nervur ask web listen '{"port":8080,"path":"/quo"}' --dir ./harbor
+nervur host alice --dir ./harbor
+nervur boot --ward alice greeter org.example.greeter --dir ./harbor
+nervur ask --ward alice greeter hello --dir ./harbor
+```
+
+`reach` names where the harbor is reached, and every invitation it gives
+carries those addresses in `at`. With no `reach`, an invitation carries
+where the harbor listens, which serves a harbor callers reach directly;
+behind a router or a proxy, name the public address with `reach`. A
+harbor that takes such an invitation keeps them as that ward's route,
+so nobody routes it by hand. Where an invitation carries no `at`,
+`nervur route <ward pk> tcp://host:port` names the route, and a route
+named this way is trusted first.
+
+`init` makes the harbor and prints its pk and an owner invitation. `serve`
+listens for Quo on TCP and for the root's asks on a local socket, open to
+you alone. Every other command is one root ask, sent to the served
+harbor, or answered from the folder when none is served. Each prints one
+JSON line. `--dir` defaults to `$NERVUR_DIR`, then `~/.nervur`. The
+catalogue keeps a module by its file's absolute path, and routes live in
+the harbor like everything else, so a restart finds both. `nervur
+modules` shows what runs, and `nervur module remove <module>` stops one.
+
+A harbor elsewhere is piloted with the owner invitation its `init`
+printed, from a harbor of your own:
+
+```sh
+nervur pilot far '<owner invitation>' --dir ./mine
+nervur host shop --via far --dir ./mine
+```
+
+`pilot` boots an `org.nervur.pilot` being in your harbor that holds the
+invitation as an ordinary Quo relation, kept in your harbor's memory, and
+reaches the far harbor where its invitation's `at` says; where it says
+nothing, name the address after the invitation. With
+`--via far`, any command is asked of the far harbor as its owner, sealed
+over TCP, except `own` and `disown`, which stay the far root's.
+`nervur unboot far` lets it go.
+
+`rootLine(harbor, request)` is the same request in code, for any other
+front: `{ ward?, method?, args? }` in, one JSON answer out.
+
+## A harbor nobody dials
+
+A device behind a home router listens nowhere a caller can reach. A
+served harbor that can be reached relays for it. On the relay's harbor:
+
+```sh
+nervur open relay org.nervur.relay --dir ./relay
+nervur ask relay invite '{"id":"house","wards":["<camera ward pk>"]}' --dir ./relay
+```
+
+On the device, with the relay's address as its own reach:
+
+```sh
+nervur open client org.nervur.relay-client --dir ./house
+nervur ask client hold '{"invitation":<the invitation>,"line":true}' --dir ./house
+nervur reach tcp://relay.example:7000 --dir ./house
+nervur serve --dir ./house
+```
+
+Every invitation the device gives now sends callers to the relay. The
+relay holds each sealed box, the client collects it by an ordinary ask,
+hands it to the device's door, and returns the sealed reply in its next
+ask. Nothing is opened on the way. `line` keeps collecting, for a
+camera. Without it the client is a doorbell: `ring` collects what waits,
+and `"every": 60000` rings on a schedule, for a garage door.
+
+A doorbell can also be rung by a push with nothing in it. The relay's
+harbor opens Web Push and names who it is:
+
+```sh
+nervur open push org.nervur.web-push --dir ./relay
+nervur ask push subject '{"subject":"mailto:ops@example.org"}' --dir ./relay
+```
+
+The device asks its client for the key (`nervur ask client key`),
+subscribes to pushes with it, and hands the subscription's endpoint to
+`nervur ask client bell '{"endpoint":"https://..."}'`. When a box waits
+and no line collects, the relay rings that endpoint once. Whatever hears
+the push on the device asks the client's `ring`.
+
+## Moving a harbor
+
+A harbor moves to another machine by its bytes, with no harbor open:
+
+```sh
+nervur export --with-seed --dir ./harbor > harbor.json
+nervur import harbor.json --dir ./elsewhere
+```
 
-Carriers over a network, storage beyond a folder, key custody, and every
-screen are `@nervur-org/dock`'s, as classes fulfilling these contracts.
+`export` reads the folder's sealed places, and carries the seed only
+where you ask for it. `import` writes them into a folder that holds none.
+A package with no seed lands where custody already holds the one it was
+sealed under. In code, `copyPackage(from, to)` carries every place of one
+memory into another.
 
 ## License
 

package/dist/being/being.d.ts

@@ -5,6 +5,7 @@ export type AskSpec = {
     readonly for?: (asker: Asker, notes: JsonObject | undefined) => boolean;
 };
 export declare class Being {
+    static readonly kind: string;
     static cells: JsonObject;
     static asks: Record<string, AskSpec>;
     readonly stance: Stance;

package/dist/being/being.js

@@ -9,8 +9,12 @@ const wrote = (self, name) => {
     return false;
 };
 // 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 kind = 'org.nervur.being';
     // Her cells' defaults, written at birth only where a key is missing.
     static cells = {};
     static asks = {};

package/dist/being/faculty.d.ts

@@ -2,6 +2,7 @@ import { Being } from './being.ts';
 import { type Asker, type Blueprint, type JsonObject, type Reply } from './types.ts';
 export declare class Faculty extends Being {
     #private;
+    static readonly kind: string;
     static contracts(C: abstract new (...args: never[]) => unknown): string[];
     static fulfils(C: unknown): C is typeof Faculty;
     describe(asker: Asker): Blueprint;

package/dist/being/faculty.js

@@ -2,23 +2,29 @@
 // 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.js';
+import { kindOf } from './kind.js';
 import { WARD } from './types.js';
 export class Faculty extends Being {
+    static kind = '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) {
-        const names = [];
+        const kinds = [];
         for (let c = C; typeof c === 'function' && c !== Faculty; c = Object.getPrototypeOf(c))
-            names.push(c.name);
-        return names;
+            kinds.push(kindOf(c));
+        return kinds;
     }
     static fulfils(C) {
         return typeof C === 'function' && C.prototype instanceof Faculty;

package/dist/being/index.d.ts

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

@@ -3,5 +3,6 @@
 export { Being } from './being.js';
 export { canonical, digest } from './digest.js';
 export { Faculty } from './faculty.js';
+export { isKind, KIT, kindOf, ownKind } from './kind.js';
 export { OWNER, WARD } from './types.js';
 export { isSilence, isWord, silence, told, word } from './words.js';

package/dist/being/kind.d.ts

@@ -0,0 +1,4 @@
+export declare const KIT = "org.nervur.";
+export declare const isKind: (text: unknown) => text is string;
+export declare const ownKind: (C: unknown) => string | undefined;
+export declare const kindOf: (C: unknown) => string;

package/dist/being/kind.js

@@ -0,0 +1,28 @@
+// 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) => typeof text === 'string' && KIND.test(text);
+// The kind a class declares on itself, or undefined.
+export const ownKind = (C) => {
+    if (typeof C !== 'function' || !Object.hasOwn(C, 'kind'))
+        return undefined;
+    const kind = C.kind;
+    return isKind(kind) ? kind : undefined;
+};
+// The kind a class declares on itself, or a throw naming the class.
+export const kindOf = (C) => {
+    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/dist/being/types.d.ts

@@ -48,10 +48,8 @@ export interface Stance {
     readonly cells: JsonObject;
     readonly occupants: Occupants;
     readonly standings: Standings;
-    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>;
 }
 export interface BeingLike {
     answer(asker: Asker, method: string | undefined, args: JsonObject): Reply | Promise<Reply>;
@@ -59,4 +57,5 @@ export interface BeingLike {
 }
 export type BeingClass = (new (stance: Stance) => BeingLike) & {
     readonly name: string;
+    readonly kind: string;
 };

package/dist/browser/index.d.ts

@@ -0,0 +1,35 @@
+import { Custody, Memory, type Entropy, type Module } from '../contract/index.ts';
+import type { GroundProbe } from '../harbor/index.ts';
+import { PointerTerrain } from '../pointer/index.ts';
+export { ringAll, rootOf, serveWorker, type Reaching } from './worker.ts';
+export declare const BROWSER = "browser";
+export declare const BROWSER_HARBOR = "nervur";
+export declare class IdbMemory extends Memory {
+    #private;
+    constructor(name?: string);
+    get name(): string;
+    read(place: string): Promise<Map<string, Uint8Array>>;
+    write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void>;
+    protected put(store: IDBObjectStore, key: [string, string], bytes: ArrayBuffer | null): void;
+    places(): Promise<string[]>;
+    forget(place: string): Promise<void>;
+    close(): Promise<void>;
+}
+export declare class IdbCustody extends Custody {
+    #private;
+    constructor(name?: string, entropy?: Entropy);
+    seed(): Promise<Uint8Array>;
+    close(): Promise<void>;
+}
+export type BrowserParts = {
+    readonly where?: string;
+    readonly modules?: readonly Module[];
+};
+export declare class BrowserTerrain extends PointerTerrain {
+    #private;
+    readonly where: string;
+    constructor(parts?: BrowserParts);
+    claim(): Promise<void>;
+    release(): Promise<void>;
+}
+export declare const browserGround: GroundProbe;

package/dist/browser/index.js

@@ -0,0 +1,188 @@
+// 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 } from '../contract/index.js';
+import { webFaculty, WEB_OPENING, webPush } from '../line/index.js';
+import { CryptoEntropy, HeldLoader, PointerTerrain } from '../pointer/index.js';
+export { ringAll, rootOf, serveWorker } from './worker.js';
+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 = '￿';
+const done = (request) => 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) => 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 {
+    name;
+    #open;
+    constructor(name) {
+        this.name = name;
+    }
+    get() {
+        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() {
+        const open = this.#open;
+        this.#open = undefined;
+        if (open)
+            (await open).close();
+    }
+}
+export class IdbMemory extends Memory {
+    #db;
+    constructor(name = BROWSER_HARBOR) {
+        super();
+        this.#db = new Database(name);
+    }
+    // The database it keeps in.
+    get name() {
+        return this.#db.name;
+    }
+    async read(place) {
+        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[1], new Uint8Array(values[i])]));
+    }
+    async write(place, entries) {
+        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.
+    put(store, key, bytes) {
+        if (bytes === null)
+            store.delete(key);
+        else
+            store.put(bytes, key);
+    }
+    async places() {
+        const keys = await done((await this.#db.get()).transaction(ENTRIES).objectStore(ENTRIES).getAllKeys());
+        return [...new Set(keys.map((key) => key[0]))];
+    }
+    async forget(place) {
+        const tx = (await this.#db.get()).transaction(ENTRIES, 'readwrite');
+        tx.objectStore(ENTRIES).delete(IDBKeyRange.bound([place, ''], [place, END]));
+        await finished(tx);
+    }
+    close() {
+        return this.#db.close();
+    }
+}
+export class IdbCustody extends Custody {
+    #db;
+    #entropy;
+    constructor(name = BROWSER_HARBOR, 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() {
+        const db = await this.#db.get();
+        const kept = (await done(db.transaction(CUSTODY).objectStore(CUSTODY).get(SEED)));
+        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 }, SEED);
+        try {
+            await finished(tx);
+        }
+        catch (e) {
+            if (e.name === 'ConstraintError')
+                return this.seed();
+            throw e;
+        }
+        return seed;
+    }
+    close() {
+        return this.#db.close();
+    }
+}
+// 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 {
+    where;
+    #release;
+    constructor(parts = {}) {
+        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;
+    }
+    async claim() {
+        const locks = globalThis.navigator?.locks;
+        if (!locks)
+            return;
+        const held = await new Promise((granted) => {
+            void locks.request(`nervur:${this.where}`, { ifAvailable: true }, (lock) => {
+                if (lock === null) {
+                    granted(false);
+                    return undefined;
+                }
+                granted(true);
+                return new Promise((release) => (this.#release = release));
+            });
+        });
+        if (!held)
+            throw new Error(`a harbor is already open on ${this.where}`);
+    }
+    async release() {
+        this.#release?.();
+        this.#release = undefined;
+        await this.memory.close();
+        await this.custody.close();
+    }
+}
+// A page or a worker with IndexedDB and Web Crypto.
+export const browserGround = {
+    name: BROWSER,
+    fits: () => typeof indexedDB !== 'undefined' && typeof crypto?.subtle !== 'undefined',
+    terrain: ({ modules, where }) => new BrowserTerrain({ ...(where ? { where } : {}), ...(modules ? { modules } : {}) }),
+};