nervur 0.22.2-7 → 0.23.0

package/FACULTIES.md

@@ -15,14 +15,22 @@ the package's own tests run.
 ## What a faculty owes
 
 A faculty answers a blueprint: a name, and methods with their schemas.
-A maker in a registry makes it, and the ground hands it to its houses as
+A registry holds it by name as `{ takes?, up, install? }`. The ground
+raises it by its `up` into a body, and hands the body to its houses as
 an offer, with the kinds its entry grants.
 
 ```text
-faculty = { blueprint?, object?, window?, handler?, stop?, registry? }
+faculty = { takes?, install?, up }
+takes   = { args?: schema, secrets?: { [name]: what it holds } }
+body    = { blueprint?, object?, window?, handler?, registry?, down? }
 offer   = { blueprint, object, kinds?, window? }
 ```
 
+- **It declares what it takes.** `takes.args` is a schema built with
+  `s` from `nervur/being`, which its entry's args meet. `takes.secrets`
+  names each secret its entry must name, with a line saying what it
+  holds. The hand refuses an entry that fails either, before it lands,
+  and `facultiesCatalog` shows it to whoever writes the entry.
 - **The object has the blueprint's methods.** Each takes one args object
   and a context, and answers `{ result }` or `{ error: { message } }`.
 - **An error is final, and a throw is not.** An error reaches the being
@@ -45,7 +53,7 @@ answered, with the same call id every time.
 So one call arrives more than once. A reply lost on its way back brings
 it again, and so does a program that died before it answered. A faculty
 that changes the world keeps each call id with the answer it gave, in
-the memory its maker receives, where a restart and a move keep it. It
+the memory its `up` receives, where a restart and a move keep it. It
 answers a call id it has seen with that answer, and acts once.
 
 It keeps them for its `window`, seven days where the offer names none.
@@ -84,31 +92,43 @@ reaches her through a standing, so policy is written as a being.
 
 ### It lives in the ground
 
-The object arrives living. The ground stands each faculty its entries
-name, awaiting its maker, and the house never starts, stops or restarts
-it. Every being whose need it covers holds the same object. A maker
-receives three things beside the faculty's name.
+The object arrives living. The ground raises each faculty its entries
+name, awaiting its `up`, and the house never starts, stops or restarts
+it. Every being whose need it covers holds the same object. Its `up`
+receives four things beside the faculty's name.
 
 - **`args`** are its entry's, as the owner wrote them.
 - **`secrets`** are the secrets its entry names, set through the hand
-  and kept sealed in the ground's drawer. No other code reads them.
+  and kept sealed in a being of the ground's dock. No other code reads
+  them.
 - **`memory`** is the faculty's own, a view of the ground's memory
   sealed under a key the ground derives for it. Its call ids live there,
   so they move with the ground.
+- **`faculties`** holds the object of each body its entry names in
+  `faculties`, so one body calls another directly. It goes up after
+  each of them.
 
-A faculty answers four things beside its methods, each where it has
-one.
+`install` receives the same, and does the slow work once for each entry.
+A program's packages and a repository's checkout are installed there, so
+going up again installs nothing.
+
+A body answers four things beside its methods, each where it has one.
 
 - **`handler`** answers HTTP on the ground's one listener. It takes a
   `Request` and answers a `Response`, or `null` where the request is not
-  its own. A site, an API or an MCP server is a faculty with a handler.
-- **`stop`** is called when the ground stops, faculties in the reverse
-  of the order they stood.
-- **`registry`** makes more faculties and bodies, for every entry that
-  names this faculty in `from`. A module of code, a git repository and a
-  program's catalogue are each a registry.
+  its own. A site, an API or an MCP server is a body with a handler.
+- **`down`** lets go of what its `up` opened. The ground calls it when
+  the body is updated, restarted or removed, and when the ground stops,
+  bodies in the reverse of the order they stood.
+- **`registry`** holds more faculties, for every entry that names this
+  body in `from`. A module of code, a git repository and a program's
+  catalogue are each a registry.
 - **`window`** is how long it remembers a call id.
 
+The hand changes a body. `faculties update` lands a new entry, and the
+body goes down and up on it. `faculties restart` takes it down and up on
+the same entry. Each house that names it opens again.
+
 ## Three ways to wrap a program
 
 | Way | What the object is | What a crash takes |
@@ -120,7 +140,7 @@ one.
 ## The bridge
 
 `bridge({ command, args, env, cwd, memory })` from `nervur/node` starts
-a program and answers a faculty. A NodeGround makes one by the maker
+a program and answers a body. A NodeGround raises one by its faculty
 `bridge`, from its entry alone. The program may be written in any
 language. It speaks one JSON value a line on its standard streams.
 
@@ -143,7 +163,7 @@ in   { id, result } | { id, error }      the ground's answer to that
   the same every time that call is sent, in every life of the program.
   A handle called with no `call` is refused.
 - **It starts with an empty environment.** It holds only what `env`
-  names, so it never reads the ground's key. The maker `bridge` names
+  names, so it never reads the ground's key. The faculty `bridge` names
   there the secrets of its entry, each under its name.
 - **It keeps its state in the faculty's memory.** A memory line names
   `read`, `list` or `write` and the memory's args, every entry's bytes
@@ -365,22 +385,22 @@ it later, once.
 
 The Pi's folder holds the program and a folder of classes for its
 house, and no code of the ground's. The relay stands from its entry,
-made by the NodeGround's own maker `bridge`, and granted to the twin's
-class alone.
+raised by the faculty `bridge` of the NodeGround's folder, and granted
+to the twin's class alone.
 
 ```bash
-npx nervur faculties add name=relay make=bridge args='{"command":"python3","args":["relay.py"]}' kinds='["org.example.garage"]'
+npx nervur faculties add name=relay from=folder make=bridge args='{"command":"python3","args":["relay.py"]}' kinds='["org.example.garage"]'
 ```
 
 The house is added once, and names the relay among the faculties it
 receives.
 
 ```bash
-npx nervur houses add name=garage classes='{"body":"folder","at":"classes"}' faculties='["relay"]'
+npx nervur houses add name=garage classes='{"faculty":"folder","at":"classes"}' faculties='["relay"]'
 ```
 
-Both entries rest sealed in the ground's drawer, so the ground stands
-the relay again at every start.
+Both entries rest sealed as cells of the ground's dock, so the ground
+stands the relay again at every start.
 
 ## In JavaScript
 
@@ -423,16 +443,16 @@ serve(Doorbell, {
 });
 ```
 
-Its entry makes it with the maker `bridge`, its command `node` and its
-args `["doorbell.js"]`. A faculty that needs no process of its own is a
-plain object a registry's maker answers instead, as the shop's payments
+Its entry raises it with the faculty `bridge`, its command `node` and
+its args `["doorbell.js"]`. A faculty that needs no process of its own
+is a plain object its `up` answers instead, as the shop's payments
 are in [Writing for nervur](AUTHORING.md).
 
 ## Testing a faculty
 
 A faculty is tested on BenchGround, the ground in memory from
 `nervur/bench`, with the program itself behind the bridge. The test
-hands the bench a registry whose maker bridges the program, as a
+hands the bench a registry whose `bridge` faculty bridges the program, as a
 NodeGround's own does, and stands the relay through the ground's hand,
 as an owner does. A `FakeNetwork` joins
 grounds and loses what the test tells it to lose, and its one clock
@@ -476,11 +496,11 @@ test('Each tap on the phone pulses the relay once, whatever fails between', { ti
     host: 'pi',
     names: ['garage.local'],
     modules: { pi },
-    registry: { faculties: { bridge: ({ memory }) => bridge({ command: 'python3', args: [relay], cwd: pin, memory }) } },
+    registry: { faculties: { bridge: { up: ({ memory }) => bridge({ command: 'python3', args: [relay], cwd: pin, memory }) } } },
   });
   t.after(() => garage.down());
   // The relay, granted to the twin's class alone.
-  await garage.hand({ faculty: 'faculties', method: 'add', args: { name: 'relay', make: 'bridge', kinds: ['org.example.garage'] } });
+  await garage.hand({ method: 'facultiesAdd', args: { name: 'relay', make: 'bridge', kinds: ['org.example.garage'] } });
   await garage.add('garage', 'pi', { faculties: ['relay'] });
   await garage.ask({ house: 'garage', method: 'bear', args: { kind: 'org.example.garage', id: 'door' } });
 

package/GROUNDS.md

@@ -14,47 +14,95 @@ 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.
-
-**It stands its faculties on a ladder.** A registry is code that makes
-faculties and bodies by name. The ground's own registry is its
-terrain's. A faculty may carry a registry of its own, and the faculties
-an entry makes `from` it stand after it. A faculty that fails to stand
-stays down and says why, and the ground boots beside it.
+**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
+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 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'] }
 ```
 
-**It opens each house on its entry.** An entry names the body of the
-house's code, the custom faculties it may use, and the longest any of
-its asks may run. It names a body of memory only where the house keeps
-its places apart from the ground's memory.
+**It opens each house on its entry.** An entry names the body that
+serves the house's code, the custom faculties it may use, and the
+longest any of its asks may run. It names a body serving memory only
+where the house keeps its places apart from the ground's memory. Beside
+each body's name, it holds the args that body hands this house.
 
 ```text
-shop  { classes: { body: 'folder', at: 'shop' }, faculties: ['payments'], wait: 60000 }
+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
+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 maker its secrets.** A secret is set through the hand
-and kept in the drawer. A faculty's entry names the secrets its maker
-receives, and no other code reads one. The hand lists their names, and
-never a value.
+**It hands each faculty its secrets.** A secret is set through the hand
+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
@@ -62,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`, `remove`, `list` | the hand, and the kinds its entry grants |
-| `faculties` | `add`, `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.
@@ -108,11 +184,30 @@ shows. The ground's folder is an ES module package, so its
 port is set, on the web. [The command](COMMAND.md) lists its settings
 and runs its hand.
 
-**Its registry makes three things.** The body `folder` loads a house's
-classes from a folder inside it. The maker `module` imports a module
-inside it as a registry, whose `faculties`, `memory` and `classes` are
-maps of makers. The maker `bridge` starts a program, in any language,
-and hands it the secrets its entry names as its environment.
+**Its registry holds its terrain's faculties.** `folder` serves each
+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,
@@ -120,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
@@ -151,24 +253,24 @@ export default EdgeGround.worker();
 ```
 
 The Worker binds the object's class as `GROUND`, with SQLite storage.
-`registry` joins the terrain's own, so an entry makes `payments` with no
-`from`. A house's entry names its code with `classes: { body: 'bundle',
-at: 'shop' }`.
+`registry` joins the terrain's own, so an entry raises `payments` with
+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. 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
@@ -190,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 body `origin` loads a
-house's classes from the origin.
+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,11 +96,11 @@ 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='{"body":"folder","at":"house"}'
+npx nervur houses add name=main classes='{"faculty":"folder","at":"house"}'
 ```
 
 Then ask the steward through the ground's hand.
@@ -130,9 +130,8 @@ 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',
-  args: { name: 'main', classes: { body: 'origin', at: '/house/index.js' } },
+  method: 'housesAdd',
+  args: { name: 'main', classes: { faculty: 'origin', at: '/house/index.js' } },
 });
 
 console.log(await ground.hand({ house: 'main', method: 'hello', args: { name: 'Ada' } }));
@@ -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

@@ -1,11 +1,10 @@
-import { ClassList, Ground, type Faculty, type Registry } from '../index.ts';
+import { ClassList, Ground, type Body, type Registry } from '../index.ts';
 import { FakeMemory } from './fake-memory.ts';
 import { type FakeNetwork } from './fake-network.ts';
 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 {
@@ -13,8 +12,8 @@ export interface HouseModule {
     readonly public?: BeingClass;
     readonly beings?: readonly BeingClass[];
 }
-/** A faculty the test writes, living, with the kinds it is granted. */
-export type Living = Faculty & {
+/** A body the test writes, living, with the kinds it is granted. */
+export type Living = Body & {
     readonly kinds?: readonly string[];
 };
 /** What a ground keeps across its lives: its key, its randomness, its memory, and each house's own where it names the `fake` body. */
@@ -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