nervur 0.22.2-8 → 0.23.1-2

package/AUTHORING.md

@@ -1,45 +1,46 @@
-# Writing for nervur
+# Writing a species
 
-This guide teaches the two things you write with `nervur`. A **being**
-holds logic and state. A **faculty** reaches the world outside, and
-[Writing a faculty](FACULTIES.md) teaches it whole. A **ground** runs them on
-a machine, and the library ships it. The examples build one small shop,
-and every file here is a file the package's own tests run.
+A species is a class of beings you write. This guide teaches it whole:
+how to declare one, how she calls others, how beings compose, and how you
+prove her. An author who finishes it writes and proves a species alone.
 
-The shop has three classes and one faculty.
+You meet the library at three moments. Writing a species is this guide.
+Writing a faculty, which reaches the world outside, is
+[Writing a faculty](FACULTIES.md). Running a ground, the process houses
+run in, is [Grounds](GROUNDS.md) and [the command](COMMAND.md).
+[Reading a world](WORLD.md) says which pieces a situation needs.
+
+The examples build one small shop, and every file here is one the
+package's own tests run.
 
 - `Order` is one order, from its first item to its shipping.
-- `Shop` is the steward, the being that runs the house.
-- `Lobby` is the public being, which strangers may ask.
-- `Payments` is a faculty that charges money, which `recipe.ts` holds
-  by name.
+- `Shop` is the steward, the being who runs the house.
+- `Lobby` is the public being, whom strangers may ask.
+
+## A being is five things
 
-## Words
+A being is an instance of a species. She is five things, and nothing
+else reaches her.
 
-| Word | What it is |
+| Part | What it is |
 | --- | --- |
-| being | an instance of a class, born for one ask and dropped after it |
 | cells | her state, JSON values, kept when an ask lands |
-| ask | a method others may call on her, with its entry |
-| asker | who calls her now: an id and notes |
-| occupant | someone who may ask her, by id |
-| standing | someone she may ask, by id |
-| blueprint | the shape of what can be called: a name and its methods |
-| need | the blueprint she calls, at its minimum, under a member of her own |
-| faculty | anything outside the house that answers a blueprint |
-| offer | a faculty the ground hands the house: its blueprint and its object |
-| role | a named test over the asker and her cells |
-| state | a name read from her cells that decides which asks exist |
-| house | what holds beings, keeps their cells, and seals every ask |
-| ground | the process houses run in, holding one key and sealing their seeds, faculties and secrets under it |
-| registry | code that holds faculties by name, for the ground to stand |
-| body | a faculty stood: the living instance houses and bodies use |
-
-## A being
-
-A being is pure logic over her cells. She never knows where she runs,
-who carries her asks, or how her cells are kept. The house does all of
-it, and she trusts it.
+| asks | the methods others may call on her, each with its entry |
+| occupants | edges in: who may ask her, each by id |
+| standings | edges out: other beings she may ask, each by id |
+| bodies | edges out: faculties she calls through her needs |
+
+Two edges every being holds. `house` is a default body: the time, random
+bytes and alarms. `root` is a default occupant: the owner, through the
+house's hand. A normal being also holds her steward, as a standing and as
+an occupant.
+
+A position adds one edge. A steward is a being plus the body `powers`. A
+public being is a being plus the occupant `stranger`, who stands for
+every asker with no relation. Every other rule is the same, so a species
+never asks where she was placed.
+
+## Declaring a species
 
 ```ts
 // classes/order.ts
@@ -72,7 +73,7 @@ export class Order extends Being.of({
   asks: {
     hire: {
       for: 'steward',
-      hints: { idempotent: true },
+      idempotent: true,
       args: s.object({ courier: s.handle() }),
       result: s.string(),
     },
@@ -84,7 +85,7 @@ export class Order extends Being.of({
       result: s.object({ total: s.number() }),
     },
     checkout: { in: 'open', for: 'owner', to: 'paying' },
-    charged: { in: 'paying', args: s.reply(Payments.charge), to: ['paying', 'open'] },
+    charged: { in: 'paying', for: 'pay', args: s.reply(Payments.charge), to: ['paying', 'open'] },
     settled: { in: 'paying', for: 'handle', to: 'paid' },
     ship: { in: 'paid', for: 'owner', to: 'shipped' },
   },
@@ -129,194 +130,199 @@ The order wrote no retry, no catch, no key and no address. `charge` is
 an effect, so it leaves only once `checkout` has landed. Its answer comes
 back to `charged`, and a refused charge opens the order again. The
 provider calls `settled` through the handle once the money arrives.
-`hire` takes a courier's invitation as her standing, and `ship` asks the
-courier through it. `shipped` is a terminal state, and nothing leaves it.
-
-### The declaration
+`ship` asks the courier through the standing `hire` took. `shipped` is a
+terminal state, and nothing leaves it.
 
-A class extends `Being.of({ … })`. That one object declares the class,
-and TypeScript reads from it the types of her cells and her needs.
+A species extends `Being.of({ … })`, and TypeScript reads her types from
+that one object. Every field is optional but `kind` and `asks`.
 
 | Field | What it is |
 | --- | --- |
-| `kind` | the code's name: a reversed domain you own, then a name |
+| `kind` | her name for the house: a reversed domain you own, then a name |
 | `description` | one line for readers and agents |
-| `cells` | the state and its defaults, written where a key is missing |
+| `cells` | her state and its defaults |
 | `needs` | blueprints she calls, each under a member name she chooses |
 | `roles` | named tests over the asker and her cells |
-| `state` | a function of the being that names her current state |
+| `state` | a function naming her current state; omitted, `ready` alone |
 | `asks` | one entry per method she answers |
-| `view` | markup as text over her asks, which a screen renders |
+| `view` | markup as text over her asks, at most 64 KiB, which a screen renders |
 
-A view is data, at most 64 KiB, carried in her describe to every asker.
-It holds no script, and a renderer loads nothing it names, so a view
-neither acts nor tracks. The library defines no markup: a renderer
-speaks its own.
-
-Every field is optional but `kind` and `asks`. A class with no `state`
-has one state, named `ready`. The kind is how the house finds her code
-again, so a bundler that renames classes changes nothing.
-
-A method in TypeScript names its args with `Args<Class, 'method'>`,
-since a subclass's method takes no type from its base. A method in
-JavaScript writes nothing.
+A method in TypeScript names its args with `Args<Class, 'method'>`. A
+method in JavaScript writes nothing.
 
 ### An ask's entry
 
 | Field | What it says |
 | --- | --- |
+| `for` | the roles that may call it |
 | `in` | the states where the ask exists; omitted, every state |
-| `for` | the roles that may call it; omitted, every occupant but handles |
 | `to` | the states it may land in; omitted, the state it began in |
-| `args` | the schema of what it takes; omitted, the empty object alone |
+| `args` | the schema of what it takes; omitted, the empty object |
 | `result` | the schema of what it answers; omitted, nothing |
-| `hints` | `readOnly`, `idempotent`, `destructive` |
-| `examples` | a history of her asks, a role, args, fakes, and what it gives |
+| `readOnly` | it writes nothing, and implies `idempotent`; the house holds it |
+| `idempotent` | it is safe to repeat, so its caller awaits it |
+| `hints` | `{ destructive }`, the one hint, which changes nothing in the house |
+| `replayable` | your word that a stranger may repeat it, though it is not idempotent |
+| `wait` | milliseconds she may run; omitted, thirty seconds, and never past five minutes |
+| `examples` | histories the bench runs, each ending in one ask and what it gives |
 | `description` | one line for readers and agents |
-| `wait` | milliseconds she may run; omitted, thirty seconds |
 
-`in`, `for` and `to` each take one name or a list of names. A method
-with no entry is never reached. An entry with no method is refused when
-the house first loads the class.
+`in`, `for` and `to` each take one name or a list. A method with no entry
+is never reached, and an entry with no method refuses the species.
+
+### Roles
+
+A role names who may ask. An omitted `for` means every occupant, and
+never an edge out of her. Five roles are the house's, for occupants.
+
+- `root` is the owner, through the hand.
+- `steward` is her steward.
+- `being` is a being her steward introduced to her.
+- `stranger` is any asker of a public being with no relation.
+- `handle` is whoever holds a handle she minted to this ask.
+
+The rest are edges out of her, which answer her and ask nothing else.
+Each need's member is a role, held by the body answering her effect on
+it. `standing` is held by a standing answering hers. `powers` is held by
+a being her steward's powers asked, and `house` by the house. So the
+order's `charged` says `for: 'pay'`, and no occupant fakes the payment's
+answer.
+
+Every other role is yours, a function of `(asker, me)`. The order's
+`owner` reads the steward's notes on the asker, so only the steward
+decides who owns an order.
+
+The house checks the table when it first loads the species. It refuses a
+state no ask reaches, an ask no role reaches, and a role no ask names. A
+method that lands in a state outside its `to` fails, and nothing lands.
+
+### Schemas and needs
+
+One builder gives the schema and the TypeScript type: `s.object`,
+`s.string`, `s.number`, `s.integer`, `s.boolean`, `s.array`, `s.enum`,
+`s.const`, `s.bytes`, `s.optional`, `s.handle`, `s.invitation` and
+`s.reply`. The house checks every ask against them.
+
+- `s.bytes` is a `Uint8Array` in the process and hex across a door.
+- `s.handle` carries a relation. A handle leaves as an invitation, and
+  an invitation arrives as a new standing id.
+- `s.invitation` carries an invitation unopened, which she passes on.
+- `s.reply(method)` is the args of an effect's reply.
+
+A need is a blueprint at its minimum: what she calls, never what a
+faculty offers. `need(name, methods)` writes one, and `needs` binds it to
+a member of her own. A faculty covers it where the names match, every
+method is offered, and each is `idempotent` in both or in neither. Every
+need is covered, or she is absent: she answers silence and keeps her
+cells until one is.
+
+## How she calls
 
-Five roles are the house's. `handle` is whoever holds a handle to this
-ask. `stranger` is the asker of a public being. `steward` is her
-steward. `being` is another being her steward introduced to her. `root`
-is the owner, through the house's hand. Every other role is yours, a
-function of `(asker, me)`.
+The callee decides how it is called, by one flag its describe shows. A
+method marked `idempotent` or `readOnly` is harmless to repeat, so she
+awaits it during her ask. Everything else changes the world, so she
+commits it as an effect.
 
-The house checks the table when it first loads the class. It refuses a
-state no ask reaches, an ask no role reaches, and a role no ask names.
-After a method runs, a state outside the entry's `to` fails the ask, and
-nothing lands.
+### Awaited calls answer as data
+
+An awaited call never throws into her code. It answers a
+`Reply<T>`, which is `{ result }` or `{ error: { message } }`. Silence
+reads as an error saying the call answered nothing. She decides what an
+error means.
+
+- `this.must(reply)` gives the result, or fails her ask with the error.
+- `this.fail(message)` refuses her ask with a message the asker can act
+  on. Nothing of her ask lands.
+- `this.silence()` answers nothing, as an absent being does, and nothing
+  lands. A prober learns nothing from it.
+
+A failed ask changed nothing she owns, so asking again is safe.
+
+### Effects commit after she lands
+
+An effect returns nothing. The house writes it in the same write as her
+cells, then sends it with one call id until it is answered. So it acts
+at most once, and never leaves where her ask failed. Its answer asks the
+method `reply` names, as `{ result }` or `{ error }`. It gives up at its
+deadline, seven days for a standing, and its reply hears why. Effects to
+one receiver leave one at a time, in order.
+
+### Who asks
+
+Every ask arrives from one true id on her graph, never a disguise.
+
+- An occupant asks as itself, and `this.asker` holds its id and notes.
+- A reply comes from the edge that answered: a need's member, `standing`
+  or `powers`.
+- An alarm comes from `house`, so its ask names `house` in its `for`.
+- An effect to a stranger's door answers as `house`, since that door is
+  no edge of hers.
 
 ### What she reaches
 
 | Member | What it is |
 | --- | --- |
-| `this.id` | her own id |
-| `this.position` | `steward`, `public` or `normal` |
-| `this.asker` | `{ id, notes, steward }` of who asks now; `signer` for a stranger |
-| `this.cells` | her values |
-| `this.house.now()` | the time, in milliseconds since the epoch |
-| `this.house.random({ length })` | random bytes |
-| `this.house.alarm({ at, ask, args, key })` | one of her asks, at that time |
-| `this.house.cancelAlarm({ key })` | an alarm removed |
-| `this.<need>.<method>({…}, { reply? })` | an awaited call, or an effect |
-| `this.held(id, Need).<ask>({…}, { reply?, after? })` | the same, on a standing, and a watch where `after` is given |
-| `this.held(id).describe()`, `.ask(method, {…}, options)` | a standing with no need: what it shows her, then any ask it showed |
-| `this.stranger({ ward, at }, Need).<ask>({…})` | a far house's public being, asked as a stranger, every ask awaited |
-| `this.stranger({ ward, at }).describe()`, `.ask(method, {…})` | the same with no need: what she shows a stranger, then any ask it showed |
+| `this.id`, `this.cells` | her id and her values |
+| `this.asker` | `{ id, notes, steward }` of who asks now, and `signer` for a stranger |
+| `this.house` | `now()`, `random({ length })`, `alarm({ at, ask, args, key })`, `cancelAlarm({ key })` |
+| `this.<need>.<method>(args, { reply? })` | a call on a body |
+| `this.held(id, Need).<ask>(args, { reply?, after? })` | a call on a standing matched to a need |
+| `this.held(id).describe()`, `.ask(method, args)` | a standing she holds no need for, read first |
+| `this.stranger({ ward, at }, Need).<ask>(args)` | a far house's public being, asked as a stranger |
 | `this.standings` | `list()`, `note(id, notes)` and `drop(id)` |
+| `this.occupants` | `list()`, `note(id, notes)` and `dismiss(id)` |
 | `this.handle(ask, { bind?, notes?, once?, expires? })` | a handle to one of her asks |
 | `this.invite(id, { notes?, expires? })` | a new occupant, as a handle |
-| `this.occupants` | `list()`, `note(id, notes)` and `dismiss(id)` |
 | `this.steward` | her steward, where she is not one |
-| `this.powers` | the house's powers, where she is the steward |
-| `this.fail(message)` | an error the asker can act on |
+| `this.powers` | the steward's six powers |
+| `this.fail`, `this.silence`, `this.must` | how an ask refuses or reads a reply |
 
 An alarm lives in the house's rows and survives every restart. A second
-alarm under one key replaces the first. When its time comes, the house
-asks her named ask as her steward would.
-
-### Awaited calls and effects
-
-The callee decides how it is called, with one flag. A method or ask
-marked `idempotent` is safe to repeat, so the caller awaits it during
-her ask. Everything else is an effect. `readOnly` is stricter: it writes
-nothing, it implies `idempotent`, and the house holds it.
-
-An awaited call answers during her ask. `await this.fx.rate({…})`
-returns the answer, and a failure throws an error she may catch. It
-waits thirty seconds unless its entry says otherwise, and never more
-than five minutes.
-
-An awaited call never comes back to a being in its own chain. While she
-awaits, she holds her queue. A call back to her, other than a
-`readOnly` one, waits behind the ask that waits for it, until the wait
-runs out and the call fails as `answered nothing`. Call back with an
-effect instead.
-
-An effect leaves after her ask lands. She calls it and it returns
-nothing. The house writes it in the same write as her cells, then sends
-it with one call id until it is answered. So an effect acts at most
-once. Its answer comes back to the ask `reply` names, as `{ result }` or
-`{ error: { message } }`.
-
-An effect gives up at its deadline, seven days for a standing and the
-offer's window for a faculty. The reply then hears an error. Effects to
-one receiver leave one at a time, in the order she called them.
-
-Asks to one being run one at a time, in the order they arrive. A
-`readOnly` ask runs beside that queue, on the cells last landed.
-
-### Watching an answer
-
-A watch is a `readOnly` ask asked with `after`, the answer you already
-hold. The house answers at once where the answer differs. Where it is
-the same, the house holds the ask and runs it again each time an ask of
-that being lands. It answers the first answer that differs, or the same
-one when the wait runs out. So a chat, an order's status or a dashboard
-is a loop of watches, and nothing polls.
-
-Through the hand, pass `after` beside the method, as the answer you
-hold: `{ result: [...] }`. From a being, pass the result she holds:
-`this.held(room, Messages).messages({}, { after: seen })`, inside a
-`readOnly` ask of her own, so she stays free while she waits. Only a
-`readOnly` ask is watched, and a watch on anything else is refused where
-she makes it.
-
-A watch may land as a reply instead: `{ after: seen, reply: 'heard' }`.
-It leaves once her ask lands, as an effect does, and its answer asks her
-`heard`, where she writes what she heard and watches again. So a device
-that only dials, a phone or a Pi behind a router, hears its station the
-moment something changes there, and opens no port.
-
-A watch moves only on what its asker could read, since it runs as that
-asker. One asker holds one watch on one ask with the same args, and a
-second answers the first at once. A watch across a door holds its
-relation until it answers, since Quo moves a relation one ask at a time.
-So watch a far being through a handle to the watched ask alone, a
-relation of its own, and ask everything else on your other standing.
-
-### Relations
-
-An **occupant** is someone who may ask her. She mints one with
-`this.invite(id, { notes })`, which answers a handle, and lets one go with
-`dismiss`.
-
-A **standing** is someone she may ask. She receives one where an ask's
-args carry an invitation under `s.handle`, or where her steward
-introduces one. She asks through it with `this.held(id, Need)`, which
-checks the standing's describe covers the need. A standing from an
-invitation is named `standing:` and sixteen hex digits, and the id is
-what her ask receives. One her steward introduced is named by the being
-it reaches. She asks a far standing from the ask after the one that took
-it.
+alarm under one key replaces the first.
+
+### Watching
+
+A watch is a `readOnly` ask or body method asked with `after`, the
+answer she holds. The house answers at once where the answer differs.
+Otherwise it answers the first answer that differs, or the same one when
+the wait runs out. So a chat or an order's status is a loop of watches,
+and nothing polls.
+
+From a being, a watch sits inside a `readOnly` ask of her own:
+`this.held(room, Messages).messages({}, { after: seen })`. Given `reply`
+beside `after`, it leaves as an effect, and its answer asks her `reply`,
+where she watches again. A watch across a door holds its relation until
+it answers. So watch a far ask through a handle to it alone.
+
+## The graph
+
+A relation is born in one of two ways. She mints an invitation, and
+another takes it. Or her steward's `introduce` joins two beings of one
+house. A being is born holding her steward and occupied by no one else.
+
+Each end cuts its own side. `this.standings.drop` lets a standing go.
+`this.occupants.dismiss` ends an occupant, and the far standing fails at
+its next call with `the standing was removed`. A far side that answers
+nothing is never read as gone.
+
+A handle is the only way a relation leaves her. `this.handle(ask)` admits
+its holder to that one ask. `once` dismisses it after its first ask, and
+`bind` fixes args the holder cannot change. `this.invite(id)` mints a
+whole occupant. `expires` gives each invitation that long to be taken. A
+handle never enters her cells.
+
+A standing arrives where an ask's args carry an invitation under
+`s.handle`. Taking one is safe to repeat: the same invitation gives the
+same standing. So the order's `hire` is `idempotent`. She asks a far
+standing from the ask after the one that took it.
 
 Every relation carries two sets of notes. `notes` are hers alone.
-`steward` are her steward's, written when the steward made the relation,
-and she reads them and never writes them. The order's `owner` role reads
-the steward's notes, so only the steward decides who owns an order.
-
-A **handle** is the only way a relation leaves her. `this.handle(ask)`
-admits its holder to that one ask. `once` dismisses it after its first
-ask lands, and `bind` fixes args the holder cannot change. The house
-turns a handle into an invitation for a far house, or a token for a
-faculty. A handle never enters her cells.
-
-`expires`, on `this.handle`, `this.invite` and the steward's `invite`,
-gives each invitation minted from the handle that many milliseconds to
-be taken. Its first knock lands within that time, or it hears silence.
-One taken in time never expires, and one without `expires` waits for
-ever. Give it to every invitation a being mints on each answer, so the
-unspent ones go.
+`steward` are her steward's, which she reads and never writes.
 
 ### The steward
 
-Every house has one steward, with the id `steward`. The holder of the
-house's hand asks her as the occupant `root`, which no sealed box can
-forge. She alone holds `this.powers`.
+Every house has one steward, with the id `steward`. The owner asks her as
+`root`, and she alone holds `this.powers`.
 
 ```ts
 // classes/shop.ts
@@ -334,17 +340,17 @@ export class Shop extends Being.of({
       args: s.object({ id: s.string() }),
       result: s.object({ owner: s.invitation() }),
     },
-    orders: { for: 'pilot', hints: { readOnly: true }, result: s.array(s.string()) },
+    orders: { for: 'pilot', readOnly: true, result: s.array(s.string()) },
     hire: {
       for: 'pilot',
       description: 'Hands a courier’s invitation to an order, which takes it.',
-      hints: { idempotent: true },
+      idempotent: true,
       args: s.object({ order: s.string(), courier: s.invitation() }),
       result: s.string(),
     },
     enroll: {
       for: 'being',
-      hints: { idempotent: true },
+      idempotent: true,
       args: s.object({ signer: s.bytes() }),
       result: s.object({ invitation: s.invitation() }),
     },
@@ -362,7 +368,7 @@ export class Shop extends Being.of({
 
   // She carries the invitation unopened, and the order she names takes it.
   async hire({ order, courier }: Args<Shop, 'hire'>) {
-    return (await this.powers!.ask({ id: order, method: 'hire', args: { courier } })) as string;
+    return this.must(await this.powers!.ask({ id: order, method: 'hire', args: { courier } })) as string;
   }
 
   // One order a signer: asked twice, the same id is borne once.
@@ -380,36 +386,21 @@ export class Shop extends Being.of({
 | `bear({ kind, id, args })` | places a new being; the same id twice answers the first |
 | `remove({ id })` | removes a being and everything of hers |
 | `list()` | every being, her kind, whether she is absent, and her dead letters |
-| `ask({ id, method, args }, { reply? })` | asks any being as her occupant `steward`; with no method, reads what she shows the steward |
+| `ask({ id, method, args }, { reply? })` | asks a being as her occupant `steward` |
 | `introduce({ from, to, notes })` | gives `from` a standing on `to`, and `to` an occupant |
 | `invite({ id, occupant, notes, expires? })` | gives a being a new occupant, and the steward its handle |
 
-`bear`, `remove`, `introduce` and `invite` land in the steward's own
-write. If her ask fails, none of them happened. A being borne runs her
-`born` ask first, where her class declares one, asked as the occupant
-`steward`, so its entry says `for: 'steward'`.
-
-Every other being is placed as `normal`. She holds the standing
-`steward` and the occupant `steward`, and can drop neither.
-
-An invitation from outside lands where the owner says. The courier's
-invitation reaches the owner by any road, a mail or a link. The owner
-hands it to the steward's `hire` with the order it is for. `hire`
-declares it `s.invitation`, so the steward carries it unopened and never
-holds it. The order's `hire` declares it `s.handle`, so the order takes
-it, and the standing is hers.
+The powers land in the steward's own write, so a failed ask did none of
+them. A being borne runs her `born` ask first, where she declares one,
+asked by `steward`. The steward's `hire` declares the courier
+`s.invitation`, so she carries it unopened. The order's declares it
+`s.handle`, so the order holds the standing.
 
-Taking an invitation is safe to repeat. The same invitation taken again
-gives the same standing, so the order's `hire` is `idempotent`, and the
-steward awaits it. The owner hears the standing, or why it was refused.
-A steward that bears a being for an invitation bears her first, then
-hands it to her the same way.
+### Strangers
 
-### A public being
-
-A house may name one public being, with the id `public`. She answers
-strangers: every asker with no relation is the occupant `stranger`, and
-`this.asker.signer` is the key the ask was signed with.
+A house may name one public being, with the id `public`. She is
+sovereign: each ask follows its own flag, and she answers what her
+author wrote. `this.asker.signer` is the key a stranger signed with.
 
 ```ts
 // classes/lobby.ts
@@ -418,7 +409,7 @@ import { Being, need, s } from 'nervur/being';
 /** What the lobby asks of her steward. */
 const Signup = need('signup', {
   enroll: {
-    hints: { idempotent: true },
+    idempotent: true,
     args: s.object({ signer: s.bytes() }),
     result: s.object({ invitation: s.invitation() }),
   },
@@ -428,240 +419,298 @@ export class Lobby extends Being.of({
   kind: 'com.acme.lobby',
   description: 'The shop’s front door: a stranger signs up and receives an order of their own.',
   asks: {
-    signup: { for: 'stranger', result: s.object({ invitation: s.invitation() }) },
+    signup: { for: 'stranger', idempotent: true, result: s.object({ invitation: s.invitation() }) },
   },
 }) {
-  signup() {
-    return this.held('steward', Signup).enroll({ signer: this.asker.signer! });
+  async signup() {
+    return this.must(await this.held('steward', Signup).enroll({ signer: this.asker.signer! }));
   }
 }
 ```
 
-A public being's asks are idempotent by default, since a stranger's box
-may arrive twice. The house answers a replayed stranger's box from a
-cache for ten minutes, and nothing runs twice. An ask marked
-`hints: { idempotent: false }` is refused to strangers.
+A stranger holds no relation, so a stranger's box may arrive twice. The
+house answers a replayed box from a cache for ten minutes. Beyond that,
+make every ask a stranger reaches `idempotent`, or mark it
+`replayable: true`. A stranger who signs up twice here holds one order.
 
-Signup awaits the steward. The lobby asks `enroll`, which is
-`idempotent`, so the lobby awaits its answer and returns the invitation
-unopened. A stranger who signs up twice holds one order.
+She asks a far public being with `this.stranger({ ward, at }, Need)`. She
+awaits its idempotent asks and commits any other as an effect. That
+effect's answer reaches her `reply` as `house`.
 
-Signup is this shop's choice, not the house's. A house is its owner's,
-and a public being does only what its owner wrote. One may answer who
-the house is and nothing more. A house with no public being answers
-strangers silence.
+## What the house holds
 
-### Schemas
+- **Cells stay small.** Cells past one mebibyte fail her ask, and
+  nothing lands.
+- **Some ids are the house's.** `root`, `stranger`, `steward`, `house`,
+  `powers` and `standing` are reserved, with every id beginning
+  `handle:`, `being:` or `standing:`.
+- **A member name never clashes.** An ask named as a member of `Being`,
+  such as `invite` or `held`, refuses the species.
+- **A species is pure.** It imports `nervur/being`, other species and its
+  own files, and nothing that reaches a machine. It reaches time and
+  randomness through `this.house` alone.
+- **A species runs contained.** Each house runs in a runner of its own.
+  A loop without end, or a rejection she left unawaited, fails her ask
+  at its wait. Every other house and being goes on.
 
-One builder gives the schema and the TypeScript type: `s.object`,
-`s.string`, `s.number`, `s.integer`, `s.boolean`, `s.array`, `s.enum`,
-`s.const`, `s.bytes`, `s.optional`, `s.handle`, `s.invitation` and
-`s.reply`. They write JSON Schema 2020-12, in a subset the house checks
-on every ask.
+## Composition
 
-- `s.bytes` is a `Uint8Array` in the process and lowercase hex across a
-  door.
-- `s.handle` carries a relation. A handle leaves as an invitation, and
-  an invitation arrives as a new standing id.
-- `s.invitation` carries an invitation unopened, as the lobby does.
-  Passed on under `s.handle`, it is taken by the being that receives
-  it. Taking one is safe to repeat: the same invitation gives the same
-  standing.
-- `s.reply(method)` is the args of an effect's reply: `{ result }` or
-  `{ error: { message } }`.
+Beings compose by asking each other. Four patterns cover what one being
+alone cannot do.
 
-### Needs
+### A saga, since nothing is atomic across beings
+
+Her ask lands whole, but two beings never land together. So a step that
+spans beings is a saga: one effect at a time, each answered through its
+reply, and a step that fails undoes the ones before it.
+
+```ts
+// patterns/trip.ts
+import { Being, need, s, type Args } from 'nervur/being';
 
-A need is a blueprint at its minimum: what she will call, never what a
-faculty offers. `need(name, methods)` writes one, and she binds it to a
-member of her own in `needs`. An offer covers a need when four things
-hold.
+export const Hotel = need('hotel', {
+  hold: { args: s.object({ trip: s.string() }) },
+  release: { args: s.object({ trip: s.string() }) },
+});
 
-1. The blueprint's name is the same.
-2. Every method the need names is offered. More are allowed.
-3. The offer requires no property the need does not require.
-4. Each method is `idempotent` in both, or in neither.
+export const Flight = need('flight', {
+  book: { args: s.object({ trip: s.string(), seats: s.integer() }) },
+});
 
-Every need is covered, or she is absent. An absent being answers silence
-and keeps her cells, and answers again once an offer covers her needs.
+// A saga: each step is an effect, and a step that fails undoes the ones before it.
+export class Trip extends Being.of({
+  kind: 'org.example.trip',
+  cells: { state: 'planning', seats: 0 },
+  state: (me) => me.cells.state,
+  asks: {
+    book: { in: 'planning', for: 'root', to: 'holding', args: s.object({ seats: s.integer() }) },
+    roomHeld: { in: 'holding', for: 'standing', args: s.reply(Hotel.hold), to: ['booking', 'planning'] },
+    flown: { in: 'booking', for: 'standing', args: s.reply(Flight.book), to: ['booked', 'planning'] },
+  },
+}) {
+  book({ seats }: Args<Trip, 'book'>) {
+    this.cells.seats = seats;
+    this.held('hotel', Hotel).hold({ trip: this.id }, { reply: 'roomHeld' });
+    this.cells.state = 'holding';
+  }
 
-A standing is matched to a need by rules two to four alone. A describe
-names no blueprint, so the need's name is hers to choose there.
+  roomHeld({ error }: Args<Trip, 'roomHeld'>) {
+    if (error) {
+      this.cells.state = 'planning';
+      return;
+    }
+    this.held('flight', Flight).book({ trip: this.id, seats: this.cells.seats }, { reply: 'flown' });
+    this.cells.state = 'booking';
+  }
 
-A need she forgot to declare is a member she does not hold, and the call
-throws inside her ask, which answers only `the ask failed`. So check your
-classes with `npx tsc --noEmit` beside your tests, which run with
-`node --test`.
+  flown({ error }: Args<Trip, 'flown'>) {
+    if (error) {
+      // The room is held and the flight is not: the saga lets the room go.
+      this.held('hotel', Hotel).release({ trip: this.id });
+      this.cells.state = 'planning';
+      return;
+    }
+    this.cells.state = 'booked';
+  }
+}
+```
 
-### Testing on the bench
+### Awaited edges form no cycle
 
-The bench opens two houses on one ground in memory, on fake memory,
-keys and clock. A being of the bench's own house asks hers through a
-door, so every ask crosses as it would in production.
+While she awaits, she holds her queue. A call back to her waits behind
+the ask that waits for it, until the wait runs out. So a being answering
+her caller calls back with an effect, which leaves once her ask lands.
 
 ```ts
-// order.test.ts
-import assert from 'node:assert/strict';
-import { test } from 'node:test';
-import { Bench } from 'nervur/bench';
-import { Order } from './classes/order.ts';
-import { Payments, paymentsOffer } from './payments.ts';
+// patterns/team.ts
+import { Being, need, s, type Args } from 'nervur/being';
 
-test('Order keeps her table: every state and role shows what it owes', async () => {
-  await Bench.check(Order);
+const Work = need('work', {
+  work: { idempotent: true, args: s.object({ job: s.string() }), result: s.string() },
 });
 
-test('An order is paid once the provider calls the handle it was given', async () => {
-  const payments = new Payments();
-  const bench = await Bench.open({ classes: [Order], offers: [paymentsOffer(payments)] });
-  const order = await bench.place(Order, { id: 'first' });
+const Report = need('report', {
+  done: { args: s.object({ job: s.string() }) },
+});
 
-  assert.deepEqual(await order.ask('checkout'), { error: { message: 'Add an item first.' } });
-  assert.deepEqual(await order.ask('add', { sku: 'tea', price: 4 }), { result: { total: 4 } });
-  assert.deepEqual(await order.ask('checkout'), { result: null });
-  await bench.settle();
-  assert.equal((await order.describe())?.state, 'paying', 'the charge left once checkout landed, and answered pending');
+export class Manager extends Being.of({
+  kind: 'org.example.manager',
+  cells: { done: [] as string[] },
+  asks: {
+    assign: { for: 'root', idempotent: true, args: s.object({ job: s.string() }), result: s.string() },
+    done: { for: 'being', args: s.object({ job: s.string() }) },
+    report: { for: 'root', readOnly: true, result: s.array(s.string()) },
+  },
+}) {
+  async assign({ job }: Args<Manager, 'assign'>) {
+    return this.must(await this.held('clerk', Work).work({ job }));
+  }
 
-  assert.deepEqual(await payments.settle('first'), { result: null });
-  await bench.settle();
-  assert.equal((await order.describe())?.state, 'paid');
-  assert.deepEqual(await order.ask('add', { sku: 'jam', price: 1 }), { error: { message: 'not in this state' } });
-});
+  done({ job }: Args<Manager, 'done'>) {
+    if (!this.cells.done.includes(job)) this.cells.done = [...this.cells.done, job];
+  }
+
+  report() {
+    return this.cells.done;
+  }
+}
+
+export class Clerk extends Being.of({
+  kind: 'org.example.clerk',
+  asks: {
+    work: { for: 'being', idempotent: true, args: s.object({ job: s.string() }), result: s.string() },
+  },
+}) {
+  work({ job }: Args<Clerk, 'work'>) {
+    // The manager awaits this ask, so she answers back with an effect.
+    this.held('manager', Report).done({ job });
+    return `on it: ${job}`;
+  }
+}
+
+export const beings = [Manager, Clerk];
 ```
 
-`place(Class, { id, born })` has the bench's steward bear a being. A
-placed being is asked with `ask(method, args, { role })` and described
-with `describe({ role })`. Test her through her asks first, as every
-asker meets her. `cells()` reads her cells through the hand, as her owner
-inspects them. An effect answers with the reply it brings once it lands.
-`settle()` lets every effect and reply run, and `advance(ms)` moves the
-fake clock.
-
-The bench plays a role as an owner could, judged on her cells as they
-stand. `root`, and a role root holds, is the hand. `steward` is the
-bench's steward, and `being` a being it introduces to her. Any other
-role is an occupant the bench's steward invites, with the role `true` in
-its steward notes. A role read from her own notes is hers to grant, and
-a handle only her own ask mints.
-
-A steward and a public being are placed where the house places them.
-`Bench.open({ steward: Shop, public: Lobby, classes: [Order] })` opens the
-author's house with them there, and `place(Shop)` and `place(Lobby)` find
-them. On the public being, a role a stranger holds is played by a being
-of the bench's own house, asking as a stranger. Beside a steward the test
-brings, the bench plays `root` and `stranger` alone, and places no other
-being. A world of your steward and the beings she bears is tested on a
-BenchGround, as [Faces](FACES.md) tests its desk.
-`Bench.check(Shop, { position: 'steward' })` and `Bench.check(Lobby, {
-position: 'public' })` check them.
-
-An entry's `examples` are tests the bench runs. Each is a history, then
-one ask, on a fresh bench. `given` lists the asks of hers that bring her
-from her `born` to where the example starts. `role` asks, `args` are the
-ask's, `fakes` answer her needs, and `gives` is the answer owed.
-`Bench.check` runs every example twice from one seed and flags a class
-that answers differently, or leaves her cells differently. It then
-describes every state to every role it plays, and names every finding
-that failed.
-
-## A faculty
-
-A faculty is anything a being may call that is not a being: a payment
-provider, a mail sender, a model, a sensor. The ground hands it to the
-house as an offer, and the house matches it to every need it covers.
+### An index being answers questions across beings
+
+A being knows only her own cells. A question across many, such as the
+cheapest listings, needs an index being that each one tells. The index
+keys what it hears by the true asker, so no listing writes another's
+entry.
 
 ```ts
-// payments.ts
-import type { FacultyContext, Offer } from 'nervur';
-import { need, s } from 'nervur/being';
+// patterns/search.ts
+import { Being, need, s, type Args } from 'nervur/being';
 
-/** What the faculty offers. An order's need is covered by it. */
-export const PaymentsBlueprint = need('payments', {
-  charge: {
-    description: 'Charges an order, and calls notify once the money arrives.',
-    args: s.object({ order: s.string(), amount: s.number(), notify: s.handle() }),
-    result: s.object({ pending: s.boolean() }),
-  },
+const Index = need('index', {
+  put: { idempotent: true, args: s.object({ price: s.number() }) },
 });
 
-type Answer = { result: { pending: boolean } } | { error: { message: string } };
-
-/**
- * A payment provider in the ground's process. It answers a call id it has
- * seen with the answer it gave, so an effect sent twice charges once. A
- * provider that changes the world keeps these in the memory its faculty's
- * `up` receives, where a restart and a move keep them.
- */
-export class Payments {
-  readonly #answered = new Map<string, Answer>();
-  readonly #waiting = new Map<string, { notify: string; context: FacultyContext }>();
-
-  async charge({ order, amount, notify }: { order: string; amount: number; notify: string }, context: FacultyContext): Promise<Answer> {
-    const seen = this.#answered.get(context.id);
-    if (seen !== undefined) return seen;
-    const answer: Answer = amount > 0 ? { result: { pending: true } } : { error: { message: 'Nothing to charge.' } };
-    if (amount > 0) this.#waiting.set(order, { notify, context });
-    this.#answered.set(context.id, answer);
-    return answer;
+export class Listing extends Being.of({
+  kind: 'org.example.listing',
+  cells: { price: 0 },
+  asks: {
+    price: { for: 'root', args: s.object({ price: s.number() }) },
+  },
+}) {
+  async price({ price }: Args<Listing, 'price'>) {
+    this.must(await this.held('search', Index).put({ price }));
+    this.cells.price = price;
+  }
+}
+
+// The index answers the question no listing can: which are cheapest.
+export class Search extends Being.of({
+  kind: 'org.example.search',
+  cells: { prices: {} },
+  asks: {
+    put: { for: 'being', idempotent: true, args: s.object({ price: s.number() }) },
+    cheapest: { for: 'root', readOnly: true, result: s.array(s.string()) },
+  },
+}) {
+  // Keyed by the true asker, so no listing writes another's price.
+  put({ price }: Args<Search, 'put'>) {
+    this.cells.prices = { ...this.cells.prices, [this.asker.id]: price };
   }
 
-  /** The money for an order arrived: the provider calls the handle it was given. */
-  settle(order: string) {
-    const waiting = this.#waiting.get(order);
-    if (waiting === undefined) throw new Error(`no charge waits for ${order}`);
-    this.#waiting.delete(order);
-    return waiting.context.call({ token: waiting.notify, id: `settle:${order}` });
+  cheapest() {
+    const sorted = Object.entries<number>(this.cells.prices).sort(([, a], [, b]) => a - b);
+    return sorted.slice(0, 3).map(([id]) => id);
   }
 }
 
-/** The offer a ground hands: the blueprint, the object, and a week's memory of call ids. */
-export const paymentsOffer = (payments: Payments): Offer => ({ blueprint: PaymentsBlueprint, object: payments, window: 7 * 86_400_000 });
+export const beings = [Listing, Search];
 ```
 
-An offer is `{ blueprint, object, kinds?, window? }`. The object answers
-each call with its call id, and one that changes the world answers a
-call id it has seen with the answer it gave. A registry holds each
-faculty by name, as `{ up, install? }`. The ground raises a faculty by
-its `up` when an entry names it, and the entry's `kinds` grants it to
-the classes it names. [Writing a faculty](FACULTIES.md) teaches the
-craft whole, with a faculty written in Python.
+### Verifying who accepted an invitation
+
+An invitation admits whoever takes it first. Where that must be one
+person, the being checks it herself. Here the club keeps a pin in her
+notes on the new occupant, and the pin travels by another road. A role
+reads her notes, so the asks a member reaches stay hidden until the pin
+is shown.
 
 ```ts
-// recipe.ts
-import { Payments, paymentsOffer } from './payments.ts';
+// patterns/club.ts
+import { Being, need, s, type Args } from 'nervur/being';
 
-// A registry: the ground raises each faculty an entry names by its `up` here.
-export const faculties = {
-  payments: { up: () => paymentsOffer(new Payments()) },
-};
-```
+const hex = (bytes: Uint8Array) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+
+export class Club extends Being.of({
+  kind: 'org.example.club',
+  roles: {
+    guest: (asker) => typeof asker.notes.pin === 'string',
+    member: (asker) => asker.notes.member === true,
+  },
+  asks: {
+    admit: {
+      for: 'root',
+      args: s.object({ name: s.string() }),
+      result: s.object({ invitation: s.handle(), pin: s.string() }),
+    },
+    claim: { for: 'guest', idempotent: true, args: s.object({ pin: s.string() }) },
+    enter: { for: 'member', readOnly: true, result: s.string() },
+  },
+}) {
+  // The invitation travels by one road and the pin by another.
+  admit({ name }: Args<Club, 'admit'>) {
+    const pin = hex(this.house.random({ length: 4 }));
+    const invitation = this.invite(`guest-${name}`, { notes: { pin, name }, expires: 86_400_000 });
+    return { invitation, pin };
+  }
+
+  // Whoever took the invitation proves they are the one it was meant for.
+  claim({ pin }: Args<Club, 'claim'>) {
+    if (pin !== this.asker.notes.pin) this.fail('That is not the pin.');
+    this.occupants.note(this.asker.id, { member: true, name: this.asker.notes.name ?? '' });
+  }
 
-## A ground
+  enter() {
+    return `Welcome, ${String(this.asker.notes.name)}.`;
+  }
+}
 
-A ground is the process houses run in, and you write none. `nervur up`
-runs one on a folder of code: a folder for each house, and each module
-your entries name. It holds one key in `state/`, and keeps every entry
-sealed in its drawer: which faculties stand, and which houses open on
-which bodies.
+const Claim = need('claim', {
+  claim: { idempotent: true, args: s.object({ pin: s.string() }) },
+});
 
-### The shop's folder
+const Entry = need('entry', {
+  enter: { readOnly: true, result: s.string() },
+});
 
-```text
-nervur-ground/
-  recipe.ts
-  payments.ts
-  classes/index.ts, order.ts, shop.ts, lobby.ts
-  state/        made by the ground, its owner's alone
-```
+export class Guest extends Being.of({
+  kind: 'org.example.guest',
+  cells: { club: '' },
+  asks: {
+    join: { for: 'root', idempotent: true, args: s.object({ invitation: s.handle() }) },
+    claim: { for: 'root', idempotent: true, args: s.object({ pin: s.string() }) },
+    enter: { for: 'root', idempotent: true, result: s.string() },
+  },
+}) {
+  join({ invitation }: Args<Guest, 'join'>) {
+    this.cells.club = invitation;
+  }
 
-The folder is a package of ECMAScript modules, so Node reads its
-TypeScript as it is written, with no build step.
+  async claim({ pin }: Args<Guest, 'claim'>) {
+    this.must(await this.held(this.cells.club, Claim).claim({ pin }));
+  }
 
-```bash
-npm init -y && npm pkg set type=module && npm install nervur
+  async enter() {
+    return this.must(await this.held(this.cells.club, Entry).enter());
+  }
+}
 ```
 
-A house's folder names what the house holds.
+A code the steward writes in her own notes serves the same end, as the
+shop's `owner` does.
+
+## Proving a species
+
+`nervur/bench` proves a species at three levels: alone, as a household,
+and as a world. The bench runs contained, as every ground does, so it
+takes her module by its URL and loads her classes in the house's runner.
+
+A house's folder names what the house holds, and the household reads it.
 
 ```ts
 // classes/index.ts
@@ -672,240 +721,193 @@ import { Order } from './order.ts';
 export const beings = [Order];
 ```
 
-### Running it
-
-```bash
-npx nervur up .
-```
-
-The ground boots in one order, and a stop is that order reversed, on an
-interrupt and on `SIGTERM`.
-
-1. **Lock.** One ground to its state.
-2. **Primordial.** Its unlock, its ledger, crypto and tools go up. Its
-   key is read from `state/key`, drawn there on the first start.
-3. **Drawer.** The key opens its drawer in the ledger.
-4. **Entries.** The drawer's entries join the defaults its environment
-   gives, the drawer's winning by name.
-5. **Ladder.** Each body is installed where its entry is new, and goes
-   up. One that fails stays down, and says why.
-6. **Houses.** Each house of the drawer opens on its bodies, and its
-   door joins the carry.
-7. **Ready.** The hand takes its socket, and it tells systemd it is up.
-
-It is set by its environment.
+```ts
+// order.test.ts
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { Bench } from 'nervur/bench';
+import { Lobby } from './classes/lobby.ts';
+import { Courier, Order } from './classes/order.ts';
+import { Shop } from './classes/shop.ts';
+import { Payments, paymentsOffer } from './payments.ts';
 
-| Setting | What it sets |
-| --- | --- |
-| `NERVUR_TCP_PORT` | its TCP port, 9110 where unset |
-| `NERVUR_HTTP_PORT` | its HTTP port, for Quo over the web and every handler; no HTTP where unset |
-| `NERVUR_ADDRESSES` | the public addresses it writes into invitations, by commas: `tcp`, `https`, `http`, `wss` or `ws` |
-| `NERVUR_ORIGINS` | the pages of other origins it answers on the web, by commas; a page of its own host needs none |
-| `NERVUR_ALLOW_PRIVATE` | `1` to dial private and loopback addresses, as two grounds on one machine do |
-| `NERVUR_BIND` | the address it listens on, `0.0.0.0` where unset |
-| `NERVUR_STATE` | its state, `state/` in its folder where unset |
-| `NERVUR_UNLOCK` | `keychain:<account>` keeps its key in the macOS keychain, in place of `state/key` |
-| `NERVUR_WAIT` | its bound on every ask, in milliseconds |
-
-The state holds the key in a file its owner alone reads, and the
-ground's ledger. Every house keeps its rows in that ledger, sealed. A
-ledger appends every write and never rewrites one. Its witness keeps
-where it last stood, and a ledger behind its witness is refused. So a
-ledger restored alone cannot replay what a house already answered,
-though a whole state folder restored with its witness is not seen. A
-lost key is a lost ground.
-
-The ladder stands once, and the ground stands it again at every start.
-The first entry stands the folder's `recipe.ts` as a registry, by the
-ground's own faculty `module`. The second raises the payments from it.
-
-```bash
-npx nervur faculties add name=recipe make=module args='{"at":"recipe.ts"}'
-```
+// Her module, which the bench loads in the house's own runner.
+const module = new URL('./classes/order.ts', import.meta.url);
 
-```bash
-npx nervur faculties add name=payments from=recipe make=payments
-```
+test('Order keeps her table: every state and role shows what it owes', async () => {
+  await Bench.check(Order, { module });
+});
 
-A house is added once, and the ground opens it again at every start.
+test('An order is paid once the provider calls the handle it was given', async () => {
+  // The provider stands in memory.
+  const payments = new Payments();
+  const bench = await Bench.open({ module, offers: [paymentsOffer(payments)] });
+  const order = await bench.place(Order, { id: 'first' });
 
-```bash
-npx nervur houses add name=shop classes='{"faculty":"folder","at":"classes"}' faculties='["payments"]'
-```
+  assert.deepEqual(await order.ask('checkout'), { error: { message: 'Add an item first.' } });
+  assert.deepEqual(await order.ask('add', { sku: 'tea', price: 4 }), { result: { total: 4 } });
+  assert.deepEqual(await order.ask('checkout'), { result: null });
+  await bench.settle();
+  assert.equal((await order.describe())?.state, 'paying', 'the charge left once checkout landed, and answered pending');
 
-`classes` names the faculty whose body serves the house's code. `folder`
-is the ground's own, and a registry may add more, a git repository among
-them. A house keeps its rows in the ground's ledger unless its entry
-names a `memory` faculty. `faculties` names what the house receives, and
-within it each faculty's entry names in `kinds` the classes that hold
-it. `houses update` and `faculties update` land a new entry in one
-write, and `faculties restart` takes a body down and up again.
+  assert.deepEqual(await payments.settle('first'), { result: null });
+  await bench.settle();
+  assert.equal((await order.describe())?.state, 'paid');
+  assert.deepEqual(await order.ask('add', { sku: 'jam', price: 1 }), { error: { message: 'not in this state' } });
+});
 
-A secret reaches a faculty the same way, and never through the
-environment. `npx nervur secrets set -` reads `{ name, value }` from
-standard input into the ground's sealed drawer. A faculty's entry names
-the secrets its `up` receives in `secrets`.
+test('A paid order ships through the courier she hired, whose stand-in hears her', async (t) => {
+  const payments = new Payments();
+  const bench = await Bench.open({
+    module,
+    offers: [paymentsOffer(payments)],
+    // The courier's side of her standing, answered by the handlers in courier.ts.
+    standIns: { courier: { need: Courier, module: new URL('./courier.ts', import.meta.url) } },
+  });
+  t.after(() => bench.close());
+  const order = await bench.place(Order, { id: 'second' });
+
+  // Her steward carries the invitation, and she takes it as a standing of her own.
+  await order.ask('hire', { courier: await bench.invitation('courier') });
+  await order.ask('add', { sku: 'tea', price: 4 });
+  await order.ask('checkout');
+  await payments.settle('second');
+  await bench.settle();
+  assert.deepEqual(await order.ask('ship'), { result: null });
+  await bench.settle();
+  assert.deepEqual(await bench.heard('courier'), [{ method: 'pickup', args: { items: ['tea'] } }]);
+});
 
-### The hand
+// The house module: its steward, its public being and its beings.
+const house = new URL('./classes/index.ts', import.meta.url);
 
-The command is a face on the ground's hand. It holds no word of its own
-beyond `up` and `service`, and reads every other from what the ground
-describes.
+test('The steward and the lobby keep their tables where the house places them', async () => {
+  await Bench.check(Shop, { module: house, position: 'steward' });
+  await Bench.check(Lobby, { module: house, position: 'public' });
+});
 
-```bash
-npx nervur help
+test('Her house keeps its table as one household: each being walked beside the others', async () => {
+  await Bench.household({ module: house });
+});
 ```
 
-A faculty's method is called as its owner calls it, and a faculty named
-alone shows its methods. Args are one JSON object, or words `key=value`.
+### Alone
+
+`Bench.check(Class, { module, position?, steward? })` proves her alone,
+where the house would place her: `normal`, `steward` or `public`. It runs
+every example and walks every state. An owner's dock steward is checked
+at `dock`, as GROUNDS.md says. It throws an error naming every
+finding that failed.
+
+An example is a history, then one ask. `given` lists the asks that
+bring her from her `born` to where it starts. `role` asks, `args` are
+the ask's, `fakes` answer her needs, and `gives` is the answer owed.
+
+The walk describes every state she reaches to every role the bench can
+play. It then plays each ask by each role its `for` names. The bench
+plays a role as an owner could: `root` through the hand, `steward` as her
+steward, `being` as a being introduced to her, and `stranger` at the
+public being. A role of yours is an occupant whose steward notes hold it
+`true`. A role read from her own notes is hers to grant, and the bench
+plays it only where her asks grant it.
+
+The checker flags each of these.
+
+- An example whose answer differs from its `gives`.
+- A re-run of one history that answers differently, or leaves her cells
+  differently.
+- A state that shows a role other asks than her table owes it.
+- An ask she refuses to a role her table gives it.
+- A `readOnly` ask that writes.
+- An ask that lands in a state its `to` does not name.
+- An ask that throws past `fail`.
+- A reply her table refused, played where her own asks reach its edge.
+- An ask a stranger reaches that is neither `idempotent` nor
+  `replayable`.
+
+### Her bodies and standings
+
+`Bench.open({ module, offers, standIns, steward, public })` opens a
+bench to drive her by hand. `place(Class, { id, born })` places her.
+`ask(method, args, { role })` and `describe({ role })` meet her as a role
+would. `cells()` reads her cells as her owner reads them. `settle()` lets
+every effect and reply run, and `advance(ms)` moves the clock.
+
+A body stands beside her as an offer: `{ blueprint, object }`, an object
+your test writes, which keeps its own calls. The order's payments are
+one, and [Writing a faculty](FACULTIES.md) teaches how to write them.
+
+A standing stands beside her as a stand-in. `standIns` names each by id,
+with her need and a module of handlers, one function for each method. A
+throw refuses the ask with its message. The bench introduces each to
+every being it places, under that id. `bench.invitation(id)` answers an
+invitation to one, which her ask takes as a standing of her own.
+`bench.heard(id)` answers what it heard, in order.
+
+A standing on another species of yours is an introduction.
+`bench.introduce(from, to)` makes one as a steward does, each side a
+placed being or an id. `{ notes }` writes her steward's notes on the
+relation, where she finds a standing by them. So a manager and her
+clerk are proven on one bench, before their household. The bench
+introduces beside its own steward alone. A steward you bring holds the
+powers, and the bench bears nothing in her house, neither a being nor
+a stand-in.
 
-```bash
-npx nervur houses list
+```ts
+// courier.ts
+// The courier's side of her standing, one function for each method of
+// her need. On the bench a stand-in runs them in the house's own runner.
+export const pickup = ({ items }: { items: string[] }): void => {
+  if (items.length === 0) throw new Error('Nothing to pick up.');
+};
 ```
 
-`ask` asks a being in a house as `root`: the steward, or the being
-`--id` names. The owner opens an order through the steward, and hands a
-courier's paper to it the same way. The steward's `hire` carries the
-paper unopened, and the order takes it.
-
-```bash
-npx nervur ask shop open id=first
-```
+### A household
 
-```bash
-npx nervur ask shop hire order=first courier=7b22…
-```
+`Bench.household({ module, beings?, introduce? })` stands a house module
+whole. The bench's steward bears every being it lists, places its public
+being, and makes each introduction `introduce` names. Each being is
+walked in place, beside the others. An awaited call that answered nothing
+between two of them is a finding naming both, since it came back into
+its own chain.
 
-`--id` names the being asked in the steward's place, as `npx nervur ask
-shop --id first` shows the order's describe. `--cells` reads her cells
-and asks nothing, as `npx nervur ask shop --id first --cells`. No one
-but the owner reads them, and only her own asks write them.
+### A world
 
-Each prints one JSON value. It exits 0 on a result and 1 on an error
-answered. It exits 2 where nothing was asked, so a script tells a
-refusal from a ground that is down. The hand is `state/hand` in the
-folder where the command runs, or the socket `--at` or `NERVUR_HAND`
-names.
+A world is proven on a `BenchGround`: a ground in memory, on a
+`FakeNetwork` whose one clock the test moves. The test stands faculties
+and houses through the ground's hand, as an owner does. Several grounds
+join one network, so one test proves the same species at every distance.
 
-### Running it as a service
+```ts
+// world.test.ts
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { BenchGround, FakeNetwork } from 'nervur/bench';
+import { faculties } from './recipe.ts';
 
-`nervur service` writes the unit that runs a folder: a systemd user unit
-on Linux, started again after any exit, and a launchd agent on macOS.
+const shop = new URL('./classes/index.ts', import.meta.url);
 
-```bash
-npx nervur service . > ~/.config/systemd/user/nervur-ground.service
-```
+test('The shop stands as a world: its owner opens an order through the hand', async (t) => {
+  const ground = await BenchGround.open({ network: new FakeNetwork(), host: 'shop', modules: { shop }, registry: { faculties } });
+  t.after(() => ground.down());
+  await ground.hand({ method: 'facultiesAdd', args: { name: 'payments', make: 'payments' } });
+  await ground.add('shop', 'shop', { faculties: ['payments'] });
 
-```bash
-systemctl --user enable --now nervur-ground
+  assert.ok('result' in (await ground.ask({ house: 'shop', method: 'open', args: { id: 'first' } })));
+  assert.deepEqual(await ground.ask({ house: 'shop', method: 'orders' }), { result: ['first'] });
+  const order = await ground.ask({ house: 'shop', id: 'first' });
+  assert.equal('describe' in order && (order.describe as { state: string }).state, 'open');
+});
 ```
 
-A user unit stops when its user logs out, unless lingering is enabled
-with `loginctl enable-linger`. On macOS, the agent goes to
-`~/Library/LaunchAgents/` and is started with `launchctl bootstrap`.
-
-### In a page
-
-`BrowserGround.open({ registry })` from `nervur/browser` runs the same
-houses in a page. Every tab and the service worker of one origin share
-one ground: the one holding the Web Lock runs it, and the others reach
-its hand over a `BroadcastChannel`. When it closes, the next opens the
-ground from the same storage. `hand` answers the same three requests
-the command sends: `describe`, a faculty's method, and an ask of a being
-in a named house.
-
-Its bodies are the browser's. The ground's key is sealed under an AES
-key that IndexedDB holds unextractable, and its memory is IndexedDB.
-Classes load from the page's own origin through the `origin` faculty, `{
-faculty: 'origin', at: '/house/index.js' }`, and a path off the origin
-is refused. The registry is the object you pass: faculties by name,
-foundation and custom alike, beside the terrain's own.
-
-Any script on the origin can use the ground's keys, so the ground is
-whoever serves the origin's script. Give it an origin of its own, serve
-nothing a stranger wrote there, and set a strict content security
-policy. The page and the house's module must share one copy of
-`nervur/being`, since a house knows a class by a mark that module gives.
-A bundler's shared chunk or an import map gives the one copy.
-
-A service worker opens the ground the same way, on a push, where no tab
-runs it. It may not `import()`, so hand it the modules it imported
-itself: `platform: { load: (href) => modules[new URL(href).pathname] }`.
-
-### In an app
-
-`AppGround.open({ shell })` from `nervur/app` is a BrowserGround in the
-app's web view, on two interfaces the shell fills in native code:
-
-- `NativeSecrets`: `get(name)` and `set(name, value)`, text kept by the
-  iOS Keychain or the Android Keystore on this device alone.
-- `NativeStore`: `get(key)`, `keys(prefix)`, and `swap(writes, expect)`,
-  which lands every write only where each key in `expect` still holds
-  what it names, and answers whether it landed.
-
-The library holds the rest. The ground's key goes into the secret store,
-and its memory into the native store, which the system never evicts as
-it may a web view's storage. A push token reaches the ground through a
-faculty your registry holds.
-
-## What the house guarantees
-
-1. **Every need is covered, or she is absent.** An absent being answers
-   silence and keeps her cells.
-2. **The asker's id is true.** Wherever the asker lives, the id she reads
-   is who asked.
-3. **Her notes are hers.** No one else writes them, and she never writes
-   her steward's.
-4. **She never holds an invitation's bytes.** Handles leave, standing ids
-   arrive, and `s.invitation` passes through unopened.
-5. **One ask at a time.** Asks to one being run in order, and `readOnly`
-   asks run beside them.
-6. **An ask lands whole or not at all.** Her cells, her relations, her
-   effects and her call ids land in one write.
-7. **An effect acts at most once, and its outcome is known.** Its answer,
-   or its giving up, reaches her through `reply`.
-8. **Her class is checked before her first ask.** A class that fails
-   leaves her absent, and the refusal says why.
+`recipe.ts` is the registry of the shop's faculties, and
+[Grounds](GROUNDS.md) says how a ground stands one.
 
-A failed ask changed nothing she owns, so asking again is safe.
+### In your gate and in CI
 
-## What the house refuses
-
-Each refusal answers why, where it is met: at her class's first resolve,
-at her call, or where an ask arrives.
-
-- A being reaching anything her position, her needs and `this.house` do
-  not give.
-- A ground's own references handed to a being, or offered to her as a
-  faculty.
-- A handle or an invitation in her cells.
-- Her cells read by anyone but the owner's hand.
-- A standing she mints herself. Standings arrive from the house.
-- A far standing asked in the ask that took it. She asks it from her next
-  ask.
-- A write by anyone else to her notes, and by her to her steward's.
-- An occupant id the house reserves, and one she already holds.
-- Two member names that clash.
-- An ask with no entry.
-- A state no ask reaches, an ask no role reaches, and a role unused.
-- A method landing in a state its `to` does not name.
-- A `readOnly` ask that writes.
-- A need and an offer that disagree on `idempotent`.
-- A schema keyword outside the subset `s` writes.
-- Two offers covering one need for one kind, and a kind two sources
-  claim.
-- An effect sent before its ask landed, or sent again while a call for
-  it is pending.
-- An ask a stranger reaches that is not idempotent.
-- An invite from a public being.
-- A seed inside the house, and a seed that is not sixty-four hex digits.
-- A memory opened with keys that derive another bound.
-- A send to a private address, unless its ground allows it.
-- A call on the house beside `House.open`, `door` and `ask`.
-- A faculty in a house's code. Faculties are the ground's.
-- A drawer opened with a key that did not seal it.
-- A secret read by a being, a describe or anyone but a faculty whose
-  entry names it.
-- A faculty raised any way but its `up`, foundation or custom.
-- A faculty entry for `secrets` or `moves`, which the hand alone reaches.
-- A ground an owner must write. Each terrain's ships.
+The same checker runs in your gate and in CI. `@nervur-org/proof`, an
+open package beside the library, proves a folder with `nervur test`. It
+checks each species where its ground places her, with `Bench.check`, and
+walks each house folder with `Bench.household`. Run your own suites with
+`node --test`, and check your types with `npx tsc --noEmit`, since a need
+you forgot to declare fails only inside her ask.