nervur 0.22.2-8 → 0.23.0

package/GROUNDS.md

@@ -14,24 +14,41 @@ kept by what the ground stands on: a file, a keychain, a Worker's
 secret. The part of a ground that answers it is its unlock. Everything
 else the ground keeps is sealed under that key.
 
-**It keeps its drawer in its one memory.** The drawer is the ground's
-own sealed places. It holds each house's entry and seed, each faculty's
-entry, every secret you set, and each house's ward. A memory that holds
-places the key does not open is refused, so a ground never opens on
-another's memory.
-
-**Its houses keep their places in the same memory.** Each house and each
-faculty sees a view of the ground's memory under a prefix of its own. A
-house seals its own rows, and the ground seals each faculty's. So what
-rests on the disk is ciphertext, and copying the key, the memory and the
-code moves the whole ground.
-
-**Every faculty has one lifecycle.** A registry holds faculties by name,
-each an object `{ up, install? }`. Standing a faculty raises it by its
-`up` into a body, the living instance houses and other bodies use.
-`install` does the slow work once for each entry. A body's `down` lets
-go of what its `up` opened. A foundation body says what it `serves`: a
-carry, the clock, or each house's memory or code.
+**It unpacks in layers, each a faculty.** Every faculty has one
+lifecycle. A registry holds faculties by name, each an object `{ takes?,
+up, install? }`. Standing one raises it by its `up` into a body, the
+living instance houses and other bodies use. `install` does the slow
+work once for each entry, and a body's `down` lets go of what its `up`
+opened.
+
+| Layer | Its faculties | What they are |
+| --- | --- | --- |
+| primordial | the memory, the unlock, crypto, tools, the clock | the host's, read from the environment alone |
+| the ground's work | `ground` | the library's, offered to the dock alone |
+| the dock | a house of the library's beings | the drawer, and the hand's one road |
+| the ladder | the terrain's defaults and your entries | carries, code, and every custom faculty |
+| the hand | a socket, a key, a channel | the owner's reach, up last and down first |
+
+**It keeps its drawer as cells of the dock's beings.** The dock is a
+house every ground stands, and its beings are the library's. A twin
+stands for each faculty entry, a being for each house, and one for each
+secret. Their cells hold every entry, what each faculty installed, each
+house's seed and ward, every secret, and the ground's bound on every
+ask. No row of the ground's stands beside them.
+
+**Every name an entry gives is a standing.** A house's code, its memory
+and the faculties it uses, and a faculty's registry, its callees and its
+secrets, are relations between those beings. The dock's steward
+introduces each, and her notes name the grant. An entry that names a
+faculty or a secret the dock does not hold is refused, and nothing
+lands.
+
+**Its houses keep their places in the same memory.** The dock, each
+house and each faculty sees a view of the ground's memory under a prefix
+of its own. A house seals its own rows, and the ground seals each
+faculty's. So what rests on the disk is ciphertext, and copying the key,
+the memory and the code moves the whole ground. A memory the key opens
+no dock in is refused.
 
 **It stands its bodies on a ladder.** The ground's own registry is its
 terrain's. A body may carry a registry of its own, and the faculties an
@@ -39,12 +56,13 @@ entry raises `from` it stand after it. A body stands after each body its
 entry names in `faculties`, whose objects its `up` receives. A body that
 fails to stand stays down and says why, and the ground boots beside it.
 
-**Its terrain names default entries, and the drawer's win.** Each ground
-stands its clock, its carries and its bodies of code from entries of its
-own. An entry of the same name in the drawer stands in its place.
+**Its terrain names default entries, and yours win.** Each ground stands
+its carries and its bodies of code from entries of its own. Its one
+clock is primordial, which the dock and every house receive.
+An entry you land under the same name stands in its place.
 
 ```text
-recipe    { make: 'module', args: { at: 'recipe.ts' } }
+recipe    { from: 'folder', make: 'module', args: { at: 'recipe.ts' } }
 payments  { from: 'recipe', make: 'payments', secrets: ['stripe-key'], kinds: ['com.acme.order'] }
 ```
 
@@ -58,6 +76,11 @@ each body's name, it holds the args that body hands this house.
 shop  { classes: { faculty: 'folder', at: 'shop' }, faculties: ['payments'], wait: 60000 }
 ```
 
+**A change answers what stands, and an error means nothing landed.**
+Adding or updating a faculty answers why its body is down, where it is.
+Adding or updating a house answers its ward, or why it stays closed.
+The entry lands either way, and the hand mends it later.
+
 **It updates an entry in one write.** `update` lands the new entry over
 the old. A house closes and opens again on it, as the same ward. A body
 goes down, installs where its entry moved, and goes up, and each house
@@ -65,13 +88,21 @@ naming it opens again. `restart` takes a body down and up on its entry.
 
 **It grants a faculty in two steps.** A house uses only the faculties its
 entry names. Inside it, a being holds one only where the faculty's entry
-names her class in `kinds`, or where it names none. So a raw shell
+names her class in `kinds`, or where it names none. So a raw program
 reaches one house and one class inside it.
 
 **It hands each faculty its secrets.** A secret is set through the hand
-and kept in the drawer. A faculty's entry names the secrets its `up`
-receives, and no other code reads one. The hand lists their names, and
-never a value. A changed secret reaches a body when it goes up again.
+and kept in a being's cells. A faculty's entry names the secrets its
+`up` receives, and no other code reads one. The hand lists their names
+and the entries that name each, and never a value. A secret's cells are
+shown to no one, and a changed secret reaches a body when it goes up
+again.
+
+**It holds each entry to what its faculty takes.** A faculty declares
+`takes`: a schema its args meet, and the secrets its entry must name.
+The hand refuses an entry that fails it, or that names a secret not
+kept, and says what failed. `facultiesCatalog` shows every faculty the
+ground can raise, and what each takes.
 
 **It hooks every door and runs one listener.** Each house's door goes to
 the ground's carry, which also delivers between the ground's own houses
@@ -79,36 +110,64 @@ without touching the network. Everything that speaks HTTP, Quo over the
 web and every face, is a handler on one listener. A faculty stood while
 the ground runs is served at once.
 
-**It serves its owner's hand.** The hand answers three things: what the
-ground holds, a faculty's method, and an ask of any being of any house,
-as the house's owner. Four faculties are the ground's own.
-
-| Faculty | Its methods | Who reaches it |
+**The dock's steward reaches the ground through two faculties.** The
+`ground` faculty raises and lowers bodies, opens and closes houses,
+shows the catalogue and moves a house's places. It is offered to the
+dock's beings alone. The `shell` runs a command on the ground's machine,
+where the terrain has one. The dock is offered it as any house is
+offered a body. Its steward stands on the shell's twin, and the twin's
+entry grants it to the dock's shell being alone. No entry names, makes
+or grants either.
+
+**A boot writes only what moved.** Each twin raises its body by a read,
+and her cells are written only where what came of it differs. So a wake
+that finds nothing changed writes nothing.
+
+**It serves its owner's hand, and the hand has one road.** The hand
+answers `describe`, and otherwise asks a being of the dock or of a house
+as `root`. A request that names a house asks a being there. One that
+names none asks the dock's steward. `describe` shows her asks, every
+faculty with its methods or why it is down, and every house.
+
+| The dock's asks | What they do | Who asks them |
 | --- | --- | --- |
-| `houses` | `add`, `update`, `remove`, `list` | the hand, and the kinds its entry grants |
-| `faculties` | `add`, `update`, `restart`, `remove`, `list` | the hand, and the kinds its entry grants |
-| `secrets` | `set`, `remove`, `list` | the hand alone |
-| `moves` | `out`, `in` | the hand alone |
-
-**It lets a pilot possess it from afar.** An entry for `houses` or
-`faculties` holds `kinds` alone, and grants it to one pilot being. A
-standing on that being then pilots the ground. `secrets` and `moves`
-take no entry, so no being ever holds a seed or a secret.
-
-**It moves a house by its seed and its memory.** `moves` takes a house
-out as its seed and every place of its memory, and another ground takes
-them in. The house keeps its identity, so every relation still answers
-and no far house notices.
+| `housesAdd`, `housesUpdate`, `housesRemove`, `housesList` | the houses | `root`, and a pilot |
+| `facultiesAdd`, `facultiesUpdate`, `facultiesRestart`, `facultiesRemove`, `facultiesList` | the faculties | `root`, and a pilot |
+| `facultiesCatalog` | every faculty the ground can raise, and what it takes | `root`, and a pilot |
+| `waitSet`, `waitShow` | the ground's bound on every ask | `root`, and a pilot |
+| `secretsSet`, `secretsRemove`, `secretsList` | the secrets | `root` alone |
+| `movesOut`, `movesIn` | a house moved between grounds | `root` alone |
+| `callFaculty` | a faculty's method, called by name | `root` alone |
+| `shellRun` | a command on the ground's machine | `root` alone |
+| `pilotsInvite`, `pilotsDismiss`, `pilotsList` | who pilots the ground | `root` alone |
+| `boot` | the ladder stood and every house opened, as each boot asks | `root` alone |
+
+**An ask of the dock is safe to send twice.** A request may carry
+`call`, its call id. The same id sent again answers what the first
+answered, and runs nothing twice.
+
+**It lets a pilot possess it from afar.** `pilotsInvite` mints an
+invitation to the dock's steward, and the owner hands it to one being.
+That being then holds a standing on the dock, and asks the houses and
+faculties asks through it. Her class reaches them typed with
+`this.held(id, DockPilot)`, the need `nervur` exports. Secrets, moves,
+the shell and faculties' methods stay the hand's alone. A secret passes
+through `secretsSet`, which answers nothing, so no answer holds one.
+
+**It moves a house by its seed and its memory.** `movesOut` takes a
+house out as its seed and every place of its memory, and another ground
+takes them in with `movesIn`. The house keeps its identity, so every
+relation still answers and no far house notices.
 
 ## The five grounds
 
-| Ground | Where it runs | When it wakes | Its unlock | Its memory |
-| --- | --- | --- | --- | --- |
-| NodeGround | a server, a desktop, a Pi | always on | a key file, or the macOS keychain | a ledger in its folder |
-| EdgeGround | a Cloudflare Worker and its Durable Object | per request, per message, per alarm | the Worker's secret | the object's storage |
-| BrowserGround | a page or its service worker | while a tab is open, and by push | a key sealed under one the browser never hands out | IndexedDB |
-| AppGround | an iOS or Android app's web view | per launch, and by push | the Keychain or the Keystore | the app's native store |
-| BenchGround | memory, in a test | as the test moves its clock | a key drawn from the bench's seed | memory in the process |
+| Ground | Where it runs | When it wakes | Its unlock | Its memory | Its hand |
+| --- | --- | --- | --- | --- | --- |
+| NodeGround | a server, a desktop, a Pi | always on | a key file, or the macOS keychain | a ledger in its folder | a socket in its folder |
+| EdgeGround | a Cloudflare Worker and its Durable Object | per request, per message, per alarm | the Worker's secret | the object's storage | a key the Worker holds |
+| BrowserGround | a page or its service worker | while a tab is open, and by push | a key sealed under one the browser never hands out | IndexedDB | a channel between the origin's tabs |
+| AppGround | an iOS or Android app's web view | per launch, and by push | the Keychain or the Keystore | the app's native store | a channel, as in a page |
+| BenchGround | memory, in a test | as the test moves its clock | a key drawn from the bench's seed | memory in the process | the test's own |
 
 The same class runs unchanged on every row. What differs is the bodies
 each ground hands its houses.
@@ -126,17 +185,29 @@ port is set, on the web. [The command](COMMAND.md) lists its settings
 and runs its hand.
 
 **Its registry holds its terrain's faculties.** `folder` serves each
-house its classes from a folder inside it. `module` imports a module
-inside it as a registry, whose `faculties` export holds `{ up, install? }`
-by name. `bridge` starts a program, in any language, and hands it the
-secrets its entry names as its environment. `tcp` and `web` are its
-carries, and `clock` its clock.
-
-**Its environment gives the default entries.** `clock`, `folder`, `tcp`
-and `web` stand from entries its settings write. An entry of the same
-name in the drawer stands in their place, so a port changes through the
-hand. A `tcp` entry whose args name no port only dials, and its
-invitations name no TCP address.
+house its classes from a folder inside the code folder its args name.
+Its body carries a registry of two more, rooted there. `module` imports
+a module as a registry, whose `faculties` export holds `{ up, install?
+}` by name. `bridge` starts a program, in any language, and hands it the
+secrets its entry names as its environment. An entry stands either with
+`from: 'folder'`. `tcp` and `web` are its carries, `listener` its one
+listener, and `shell` its shell. Its clock is the library's, and
+primordial.
+
+**Its code gives the default entries.** `folder`, `listener`, `tcp`,
+`web` and `shell` stand from entries the library fixes. TCP
+listens on the loopback at 9110, so nothing beyond the machine reaches
+a new ground. A server names its bind through the hand. The web names
+`listener` in its `faculties` and listens on no port. An entry of the
+same name you land stands in their place, so a port changes through the
+hand. Name
+`listener` there too, since the web serves the listener it calls.
+
+**A port another process holds keeps that carry down with why.** The
+ground boots beside it until the hand moves the port. A `tcp` entry
+whose args name no port only dials, and its invitations name no TCP
+address. Its environment names only `NERVUR_STATE`, `NERVUR_UNLOCK` and
+`NERVUR_HAND`.
 
 **Its key rests in `state/key`, its owner's alone.** A key file others
 may read is refused, as ssh refuses a key. On macOS,
@@ -144,10 +215,17 @@ may read is refused, as ssh refuses a key. On macOS,
 instead. Keep `state/` as you keep an ssh key: whoever holds the key and
 the ledger holds the ground.
 
-**It keeps its memory as a ledger.** Every write is one line, chained to
-the line before it and synced before it counts. A ledger edited anywhere
-but its end is refused. A witness file kept on another disk refuses a
-restored copy that is behind.
+**It keeps its memory as a ledger, which holds the folder's lock.** Every
+write is one line, chained to the line before it and synced before it
+counts. A ledger edited anywhere but its end is refused. A witness file
+kept on another disk refuses a restored copy that is behind. While the
+ledger stands, a second ground on the same state is refused.
+
+**Its shell runs a command for the hand alone.** `nervur shell run --
+<command>` runs it in the code folder, and answers its exit code and
+what it printed. Its environment holds `PATH`, `HOME` and a few more of
+the process's, and never a secret or a `NERVUR_` variable. No pilot and
+no being reaches it.
 
 **It runs a program as a faculty, in any language.** The bridge starts a
 program and speaks one JSON value a line on its standard streams. The
@@ -179,21 +257,20 @@ The Worker binds the object's class as `GROUND`, with SQLite storage.
 no `from`. A house's entry names its code with `classes: { faculty:
 'bundle', at: 'shop' }`.
 
-**Its settings are the Worker's.**
+**Its Worker holds two secrets and nothing else.**
 
-| Setting | What it sets |
+| Variable | What it names |
 | --- | --- |
 | `NERVUR_SECRET` | the ground's key, sixty-four hex digits; set as a secret |
 | `NERVUR_HAND` | the key its hand answers; set as a secret |
-| `NERVUR_ADDRESSES` | the addresses it is reached at, by commas, the held line first |
-| `NERVUR_ORIGINS` | the page origins it answers |
-| `NERVUR_ALLOW_PRIVATE` | `1` to let it dial a private address |
-| `NERVUR_WAIT` | the longest any ask may run, a minute where unset |
 
 A Worker learns no name it is reached by, so it writes only the
-addresses `NERVUR_ADDRESSES` names. These settings give the default
-entry of its web carry, and an entry in the drawer stands in its place.
-Its faculties take their secrets from its drawer, as on every ground.
+addresses its `web` entry names, the held line first. Name them through
+the hand with `facultiesUpdate`, as `addresses` in the args of `web`,
+beside its `origins` and `allowPrivate`, and the dock keeps them.
+Every ask runs a minute at most, and `waitSet` keeps a shorter bound.
+Its faculties take their secrets from the dock, as on every ground. It
+has no shell.
 
 **Its hand answers its key alone.** The hand is `POST /nervur/hand`, with
 the key as a bearer token and one request as the body. Every other
@@ -215,18 +292,19 @@ the object. A watch held on that line answers the moment the change lands.
 
 **A BrowserGround is one ground for its origin.** Every tab and the
 service worker of an origin share it. The tab holding a Web Lock runs
-the ground, and every other tab reaches its hand. It only dials, so it
-answers no face. Whoever serves the origin's script possesses the
-ground, so its origin serves nothing else.
+the ground, and its hand answers every other tab over a channel. It
+only dials, so it answers no face. Whoever serves the origin's script
+possesses the ground, so its origin serves nothing else.
 [The package's start](README.md) opens one in a page.
 
 **Its registry is the one the page hands.** `BrowserGround.open({
 registry })` joins it to the terrain's own, whose faculty `origin`
 serves each house its classes from the origin.
 
-**An AppGround is a BrowserGround with the shell's bodies.** The shell
-hands in two small interfaces, one for secrets and one for a store, and
-the library holds the rest. The ground's key rests in the secret store.
+**An AppGround is a BrowserGround with the shell's bodies.** The app's
+native shell hands in two small interfaces, one for secrets and one for
+a store, and the library holds the rest. The ground's key rests in the
+secret store.
 
 ## BenchGround
 

package/README.md

@@ -96,8 +96,8 @@ Run the ground in the folder, and leave it running.
 npx nervur up .
 ```
 
-In a second shell, add the house once. The ground keeps its entry in its
-sealed drawer, and opens it again at every start.
+In a second shell, add the house once. The ground keeps its entry as a
+sealed cell of its dock, and opens it again at every start.
 
 ```bash
 npx nervur houses add name=main classes='{"faculty":"folder","at":"house"}'
@@ -130,8 +130,7 @@ const ground = await BrowserGround.open();
 
 // The house's code is a module on this origin, and its rows rest sealed in IndexedDB.
 await ground.hand({
-  faculty: 'houses',
-  method: 'add',
+  method: 'housesAdd',
   args: { name: 'main', classes: { faculty: 'origin', at: '/house/index.js' } },
 });
 
@@ -154,10 +153,11 @@ keeps. [Writing for nervur](AUTHORING.md) shows both.
 | Entry | For |
 | --- | --- |
 | `nervur/being` | writing a being: `Being`, `s`, `need`, `tableOf`, `Args`, `Result`, `Json`, `Table` |
-| `nervur` | any engine: `Ground`, `House` and the bodies they take |
+| `nervur` | any engine: `Ground`, `House`, `DockPilot`, `vouchesOf` and the bodies they take |
 | `nervur/node` | a ground on Node: `NodeGround`, the `nervur` command, and its bodies |
 | `nervur/browser` | a ground in a page or its service worker: `BrowserGround` and its bodies |
-| `nervur/app` | a ground in a phone's app: `AppGround`, and the two interfaces its shell fills |
+| `nervur/edge` | a ground on the edge, a Worker and its Durable Object: `EdgeGround` and its bodies |
+| `nervur/app` | a ground in a phone's app: `AppGround`, and the three interfaces its shell fills: `NativeShell`, `NativeSecrets` and `NativeStore` |
 | `nervur/serve` | a faculty's program in JavaScript: `serve` |
 | `nervur/bench` | tests: `Bench`, `BenchGround` and `FakeNetwork` |
 

package/dist/bench/bench-ground.d.ts

@@ -5,7 +5,6 @@ import { FakeUnlock } from './fake-unlock.ts';
 import { SeededCrypto } from './seeded.ts';
 type BeingClass = ConstructorParameters<typeof ClassList>[0]['steward'];
 type Entry = Parameters<Ground['add']>[1];
-type HandAsk = Parameters<Ground['ask']>[0];
 type Standing = Awaited<ReturnType<Ground['add']>>;
 /** A house module: what a folder's index exports. */
 export interface HouseModule {
@@ -61,8 +60,9 @@ export declare class BenchGround {
     add(name: string, from?: string | Entry, rest?: Omit<Entry, 'classes'>): Promise<Standing>;
     remove(name: string): Promise<void>;
     list(): readonly Standing[];
-    ask(request: HandAsk): ReturnType<Ground['ask']>;
-    /** The ground's hand, as its owner holds it: `describe`, a faculty's method, or an ask of a being. */
+    /** A being in a house asked as `root`, the house's steward where no id is named. */
+    ask(request: Parameters<Ground['ask']>[0]): ReturnType<Ground['ask']>;
+    /** The ground's hand, as its owner holds it: `describe`, or an ask of a being in a house, or of the dock's steward where no house is named. */
     hand(request: Parameters<Ground['hand']>[0]): ReturnType<Ground['hand']>;
     /**
      * A request to the ground's one listener, with no socket: each faculty's

package/dist/bench/bench-ground.js

@@ -3,12 +3,14 @@
 // and its memory in a machine that outlives it, and opens house modules by
 // name. So a test turns it off, opens it again on the same machine, or
 // moves the machine to another host.
+import { s } from '../being/index.js';
 import { ClassList, Ground } from '../index.js';
 import { FakeMemory } from './fake-memory.js';
 import { clockOf } from './fake-network.js';
 import { FakeUnlock } from './fake-unlock.js';
 import { SeededCrypto } from './seeded.js';
 // Registries' faculties as one, the first first: a name one holds is refused to the next, never replaced.
+const NONE = { args: s.object({}) };
 const joined = (...each) => {
     const all = {};
     for (const faculties of each) {
@@ -67,13 +69,24 @@ export class BenchGround {
         const living = Object.fromEntries(Object.entries(faculties).map(([name, { kinds: _kinds, ...body }]) => [name, { up: () => body }]));
         const own = {
             faculties: {
-                'bench-unlock': { up: () => ({ serves: 'unlock', object: machine.unlock }) },
-                'bench-memory': { up: () => ({ serves: 'memory', object: machine.memory }) },
-                seeded: { up: () => ({ serves: 'crypto', object: machine.crypto }) },
-                'bench-clock': { up: () => ({ serves: 'clock', object: clockOf(network) }) },
-                'bench-carry': { up: () => ({ serves: 'carry', schemes: ['bench'], object: network.join(host, { names, listens: names.length > 0, serve: (request) => this.fetch(request) }) }) },
-                fake: { up: () => ({ serves: 'memory', house: ({ house }) => machine.memoryOf(house) }) },
+                'bench-unlock': { takes: NONE, up: () => ({ serves: 'unlock', object: machine.unlock }) },
+                'bench-memory': { takes: NONE, up: () => ({ serves: 'memory', object: machine.memory }) },
+                seeded: { takes: NONE, up: () => ({ serves: 'crypto', object: machine.crypto }) },
+                // The test holds the hand in its own process, so this hand listens on nothing.
+                'bench-hand': { takes: NONE, up: () => ({ serves: 'hand' }) },
+                'bench-clock': { takes: NONE, up: () => ({ serves: 'clock', object: clockOf(network) }) },
+                // Its listener on the network is the ground's one, which its entry names in `faculties`.
+                'bench-carry': {
+                    takes: NONE,
+                    up: ({ faculties: called }) => {
+                        const listener = called.listener;
+                        const serve = async (request) => (await listener.fetch(request)) ?? new Response(null, { status: 404 });
+                        return { serves: 'carry', schemes: ['bench'], object: network.join(host, { names, listens: names.length > 0, serve }) };
+                    },
+                },
+                fake: { takes: NONE, up: () => ({ serves: 'memory', house: ({ house }) => machine.memoryOf(house) }) },
                 module: {
+                    takes: NONE,
                     up: () => ({
                         serves: 'classes',
                         house: ({ args }) => {
@@ -89,8 +102,8 @@ export class BenchGround {
         this.#ground = await Ground.open({
             // The bench's own faculties, then the test's beside them, never in their place.
             registry: { faculties: joined(own.faculties ?? {}, living, registry.faculties ?? {}) },
-            primordial: { unlock: { make: 'bench-unlock' }, memory: { make: 'bench-memory' }, crypto: { make: 'seeded' }, tools: { make: 'strict' } },
-            entries: { clock: { make: 'bench-clock' }, carry: { make: 'bench-carry' }, module: { make: 'module' }, fake: { make: 'fake' } },
+            primordial: { unlock: { make: 'bench-unlock' }, memory: { make: 'bench-memory' }, crypto: { make: 'seeded' }, tools: { make: 'strict' }, clock: { make: 'bench-clock' }, hand: { make: 'bench-hand' } },
+            entries: { listener: { make: 'listener' }, carry: { make: 'bench-carry', faculties: ['listener'] }, module: { make: 'module' }, fake: { make: 'fake' } },
         });
         // Each living faculty stands on its first up, as its owner would stand it through the hand.
         for (const [name, { kinds }] of Object.entries(faculties)) {
@@ -122,10 +135,11 @@ export class BenchGround {
     list() {
         return this.#live().list();
     }
+    /** A being in a house asked as `root`, the house's steward where no id is named. */
     ask(request) {
         return this.#live().ask(request);
     }
-    /** The ground's hand, as its owner holds it: `describe`, a faculty's method, or an ask of a being. */
+    /** The ground's hand, as its owner holds it: `describe`, or an ask of a being in a house, or of the dock's steward where no house is named. */
     hand(request) {
         return this.#live().hand(request);
     }

package/dist/browser/browser-ground.d.ts

@@ -39,16 +39,16 @@ export interface BrowserGroundOptions {
     /** Whether it dials private and loopback addresses, as a page on localhost does. */
     readonly allowPrivate?: boolean;
 }
-/** One request of the hand, as every terrain serves it. */
+/** One request of the hand, as every terrain serves it: `describe`, or an ask of a being in the house it names, or of the dock's steward where it names none. */
 export interface BrowserHandRequest {
     readonly describe?: true;
-    readonly faculty?: string;
     readonly house?: string;
     readonly id?: string;
     readonly method?: string;
     readonly args?: Json;
     readonly after?: Answer;
     readonly cells?: true;
+    readonly call?: string;
 }
 export declare class BrowserGround {
     #private;
@@ -65,8 +65,8 @@ export declare class BrowserGround {
     /** Resolves once this page runs the ground, and rejects where its boot failed. */
     led(): Promise<void>;
     /**
-     * The hand: `describe`, a faculty's method, or an ask of a being in a
-     * named house, answered by whichever page runs the ground.
+     * The hand: `describe`, or an ask of a being in a named house or of the
+     * dock's steward, answered by whichever page runs the ground.
      */
     hand(request: BrowserHandRequest): Promise<Answer | {
         readonly describe: Json;

package/dist/browser/browser-ground.js

@@ -6,6 +6,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { s } from '../being/schema.js';
 import { WebCarry } from '../bodies/web-carry.js';
 import { Ground, joinedRegistry } from '../ground/ground.js';
 import { IndexedDbMemory } from './indexeddb-memory.js';
@@ -19,6 +20,7 @@ let joinOn;
 /** The origin's ground on stores of the terrain's own: an AppGround's, or a proof's in memory. No entry exports it. */
 export const openOn = (options, stores) => joinOn(options, stores);
 const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const NONE = { args: s.object({}) };
 const random = () => Array.from(crypto.getRandomValues(new Uint8Array(8)), (byte) => byte.toString(16).padStart(2, '0')).join('');
 const defaults = (name) => ({
     locks: navigator.locks,
@@ -92,8 +94,8 @@ export class BrowserGround {
         return this.#leading;
     }
     /**
-     * The hand: `describe`, a faculty's method, or an ask of a being in a
-     * named house, answered by whichever page runs the ground.
+     * The hand: `describe`, or an ask of a being in a named house or of the
+     * dock's steward, answered by whichever page runs the ground.
      */
     async hand(request) {
         if (this.#closed)
@@ -127,8 +129,6 @@ export class BrowserGround {
                 this.#say({ kind: 'up', leader: this.#self });
             else if (said.kind === 'up')
                 this.#heard(said.leader);
-            else if (said.kind === 'ask' && said.to === this.#self)
-                void this.#answer(said.id, said.request);
             else if (said.kind === 'answer') {
                 const pending = this.#pending.get(said.id);
                 this.#pending.delete(said.id);
@@ -136,10 +136,6 @@ export class BrowserGround {
             }
         };
     }
-    async #answer(id, request) {
-        const answer = this.#ground === undefined ? { error: { message: 'the ground moved to another page; ask again' } } : await this.#local(request);
-        this.#say({ kind: 'answer', id, answer });
-    }
     // A new page runs the ground: asks sent to the one before may never be answered, so they fail, and whoever waited goes on.
     #heard(leader) {
         if (leader !== this.#leader)
@@ -162,13 +158,20 @@ export class BrowserGround {
     #queue() {
         this.#platform.locks
             .request(`${this.#name}-ground`, { signal: this.#abort.signal }, async () => {
+            let booted;
             try {
-                this.#ground = await this.#boot();
+                booted = await this.#boot();
             }
             catch (error) {
                 this.#failed(error);
                 return;
             }
+            // A page that closed while its boot ran lets the ground go at once, and the lock with it.
+            if (this.#closed) {
+                await booted.close();
+                return;
+            }
+            this.#ground = booted;
             this.#heard(this.#self);
             this.#say({ kind: 'up', leader: this.#self });
             this.#led();
@@ -189,25 +192,60 @@ export class BrowserGround {
         const own = {
             faculties: {
                 'store-unlock': {
+                    takes: NONE,
                     up: async () => {
                         const unlock = await stores.unlock(`${name}-unlock`);
                         return { serves: 'unlock', object: unlock, down: closing(unlock) };
                     },
                 },
                 'store-memory': {
+                    takes: NONE,
                     up: async () => {
                         const memory = await stores.memory(`${name}-ground`);
                         return { serves: 'memory', object: memory, down: closing(memory) };
                     },
                 },
+                // The hand, for every other page of the origin: the asks sent to this page on the channel, each answered there.
+                'channel-hand': {
+                    takes: { args: s.object({ channel: s.string(), self: s.string(), persisted: s.boolean() }) },
+                    up: ({ args, faculties }) => {
+                        const ground = faculties.ground;
+                        const channel = platform.channel(args.channel);
+                        let open = true;
+                        channel.onmessage = (event) => {
+                            const said = event.data;
+                            if (said.kind !== 'ask' || said.to !== args.self)
+                                return;
+                            // An ask this hand's close ended is answered by no one here: the page that runs the ground next is asked again.
+                            void ground.hand(said.request).then((answer) => {
+                                if (!open)
+                                    return;
+                                channel.postMessage({
+                                    kind: 'answer',
+                                    id: said.id,
+                                    answer: said.request.describe === true && 'result' in answer ? { result: { ...answer.result, persisted: args.persisted === true } } : answer,
+                                });
+                            });
+                        };
+                        return {
+                            serves: 'hand',
+                            down: () => {
+                                open = false;
+                                channel.close();
+                            },
+                        };
+                    },
+                },
                 // It only dials, so it writes no address into an invitation.
                 web: {
+                    takes: { args: s.object({ allowPrivate: s.optional(s.boolean()) }) },
                     up: ({ args }) => {
                         const web = new WebCarry({ allowPrivate: args.allowPrivate === true });
                         return { serves: 'carry', schemes: ['https', 'http', 'wss', 'ws'], object: web };
                     },
                 },
                 origin: {
+                    takes: NONE,
                     up: () => ({
                         serves: 'classes',
                         house: ({ args }) => {
@@ -222,9 +260,15 @@ export class BrowserGround {
         const wait = this.#options.wait;
         return Ground.open({
             registry: joinedRegistry(own, this.#options.registry ?? {}),
-            primordial: { unlock: { make: 'store-unlock' }, memory: { make: 'store-memory' }, crypto: { make: 'noble' }, tools: { make: 'strict' } },
-            entries: {
+            primordial: {
+                unlock: { make: 'store-unlock' },
+                memory: { make: 'store-memory' },
+                crypto: { make: 'noble' },
+                tools: { make: 'strict' },
                 clock: { make: 'clock' },
+                hand: { make: 'channel-hand', args: { channel: `${name}-hand`, self: this.#self, persisted: this.#persisted }, faculties: ['ground'] },
+            },
+            entries: {
                 origin: { make: 'origin' },
                 web: { make: 'web', args: this.#options.allowPrivate === true ? { allowPrivate: true } : {} },
             },