@quo-systems/quo 0.2.14 → 0.2.16

package/quo-kit.md

@@ -0,0 +1,595 @@
+# quo-kit
+
+This is the kit: one TypeScript implementation of Quo, run directly on Node
+with no dependencies, published as `@quo-systems/quo`. It assumes
+`papers/SPEC.md`, which is the protocol and assumes nothing, and it adds
+nothing to it. Everything here is a choice this kit made and another kit may
+refuse: a base class, a spelling for silence, a file layout, a store, a
+bundle, a gate. Where this paper and the protocol disagree the protocol wins,
+because a sentence that a kit in another language needs to interoperate is
+not this paper's to hold.
+
+It carries no version and keeps no history, and it is rewritten in place to
+say what the tree says.
+
+## The tree
+
+The repository is one TypeScript implementation of the protocol, run
+directly on Node's type stripping, no dependencies. Node 22.18
+or later. The package is `@quo-systems/quo`, published from 0.1.0, the
+first version under this name, and it starts over: nothing before it under
+any other name is this protocol. Before 1.0.0 every version may change the
+words, and nothing is kept for a holder of an earlier one.
+
+The tree runs as TypeScript and the package ships as JavaScript. Node
+strips types nowhere under `node_modules`, so a consumer cannot load the
+source. `npm run build` emits `dist/` from `src`
+alone, one JavaScript file and one declaration file per source file with
+every relative import rewritten, and the exports map points there, types
+beside default. The
+build runs before every gate and every publish and is never tracked;
+nothing in this repository imports it except through the package name,
+which is how a consumer does. `test/package.test.ts` is the one
+suite that meets the package as a stranger: it packs the tarball,
+installs it into an empty folder, and imports every entry point under
+plain Node. `npm pack --dry-run` shows what ships: `dist/`, the four
+source folders, the protocol shelf, this paper, the README, the licence and
+the notice, and nothing else. Two papers ship and the build copies both in,
+each to where it belongs: the spec into `protocol/`, beside the vectors it
+is read against and away from every line of TypeScript, because that folder
+is what a kit in another language is written against and nothing else; this
+paper to the package root, where it says which of what a reader sees here
+was a choice. Publishing runs both
+gates first, `npm run check` and `npm run check:terrain`, and refuses on a
+failure.
+
+```
+protocol/         the shelf a second kit reads. SPEC.md, copied in by the build, and the vectors beside it.
+protocol/vectors/ fixed inputs and outputs: the arithmetic, Quo's own framing, the frames on the wire, the door's thirteen cases.
+src/being/        the Being side. types, the base class, silence, the digest.
+src/ward/         the ward. the Ground contract, door, seal, arithmetic, heirs, stance, owner, partition, cells, allowance.
+src/harbor/       the memory harbor, the store, the reach, the dialer and the harbor core.
+src/conformance/  the behaviours any ward must show, and the fixed beings they are shown with.
+test/             the suites.
+```
+
+## The three shelves
+
+The package holds three kinds of thing and they are not interchangeable.
+Knowing which shelf a file is on decides whether a kit in another language
+may read it, whether this paper or the spec governs it, and whether it
+travels the day a second kit exists.
+
+| shelf    | what stands there                                    | language                |
+| -------- | ---------------------------------------------------- | ----------------------- |
+| protocol | `protocol/`: `SPEC.md` and the vectors               | none, prose and bytes   |
+| kit      | `src/being/`, `src/ward/`, `src/harbor/`, this paper | TypeScript, chosen here |
+| harness  | `src/conformance/`, `test/`                          | TypeScript, ours        |
+
+The protocol shelf is the only one a kit in Rust or Go reads. It is a
+document that assumes nothing and four files of fixed bytes, and it is
+written so that folder alone, lifted into an empty repository, is the whole
+protocol. Nothing on it imports anything, because nothing on it is code.
+
+The kit shelf is this interpretation and another kit may refuse every line
+of it: a base class, a spelling for silence, a store interface, a reach, a
+dialer, a file layout.
+
+The harness shelf proves the kit shelf, and it is not the protocol however
+much it reads like it. `src/conformance/` imports `Being`, `silence.ts`,
+`digest.ts` and the kit's own `Store` and `Reach`, so a kit in another
+language cannot run one line of it. It is exported all the same, as
+`@quo-systems/quo/conformance`, because every harbor the dock stands on is
+a TypeScript harbor and the suite is how one is accepted. The day a second
+kit exists, the conformance suite does not run there. It is ported: a kit
+writes the six obligations of the probe, carries the suite and its beings
+into its own language, and reads them beside its own tests.
+
+The hand to that kit is two things of two kinds, as the spec has it. The
+vectors are the byte-level hand and the ported checklist is the
+behavioural one. The suite does not become data, because the beings it is
+shown with run only in the ward its kit wrote. The four areas are the
+whole byte-level hand: `arithmetic.json`, `framing.json`, `wire.json` and
+`door.json`, the last being the door's thirteen cases, each an arrival with
+the bytes in, the bytes out and the partition's digest on both sides of the
+judgement. The shelf owes nothing beyond them.
+
+Entry points: `@quo-systems/quo` is the Being side, `@quo-systems/quo/ward`
+is `Ward`, `@quo-systems/quo/harbor` is `MemoryHarbor`, `Harbor`, the
+store, the reach and the dialer, and `@quo-systems/quo/conformance` is
+`conform` with the store and reach suites beside it.
+
+## The terrain
+
+Under `src/being/`, `src/ward/`, `src/harbor/` and `src/conformance/` no
+runtime is named. The whole
+platform surface is the language plus ten globals. Six are the ward's own:
+`crypto`, `TextEncoder`, `TextDecoder`, `structuredClone`, `setTimeout` and
+`atob`. Four more came with the harbor, and are the whole of what a reach
+costs: `fetch` and `WebSocket`, the two kinds of reach; `DataView`, the frame
+id on a socket; and `clearTimeout`, the dialer's reconnect called off. That
+list is a promise, not an accident: `test/terrain.test.ts` fails the build
+both when a file names a platform and when it reaches for a global outside
+the list, and when the list names one the tree has stopped using.
+
+The package exports the emitted `dist/`, JavaScript with a declaration
+beside it, on every specifier, so plain Node imports it; the tree runs the
+source directly, and every other terrain reaches a ward through a
+bundler. `test/bundle.test.ts` bundles the three words and runs them, and
+asserts the artefact carries nothing a terrain cannot provide.
+
+The five algorithms are read out of WebCrypto, which is why the ward names no
+package, on any terrain that carries them. `crypto.subtle` is read at every
+use and never captured at load, so a page without one, a plain http:// origin
+or a sandboxed frame, fails at the first ask with one sentence rather than
+deep inside a key import. The floor is probed in `test/floor.test.ts`, the
+arithmetic is `src/ward/arithmetic.ts` and the seal is `src/ward/seal.ts`.
+
+## The being side
+
+Silence is the symbol `quo.silence` and a word is a frozen object under the
+symbol key `quo.word` holding its name, both from `src/being/silence.ts`;
+`isWord` and `wordOf` read them, and `isUnreached` is the one word a being
+asks about most. `told` names a word and leaves everything else exactly as it
+came, so asking which word arrived is one comparison rather than two joined by
+an and: `told(out) === 'late'`. A kit in another language spells it however
+that language spells one value standing for either, and owes nothing here.
+
+The digest is `src/being/digest.ts`.
+
+### The base class
+
+The kit offers a base class, `Being` in `src/being/being.ts`, which is a
+convenience and not Quo:
+
+- `static cells` are her defaults, merged at birth only where a key is
+  missing, so a restart keeps what she wrote.
+- `static asks` declares what she can be asked, name to
+  `{ description?, input?, output?, for? }`, in blueprint order.
+  `for(occupant, asker)` decides whether this asker sees the ask, and so
+  whether this asker may call it: what she shows is what she can be asked,
+  one gate for describe and for dispatch.
+- Both statics are read off the class the object was made from, and a
+  subclass that declares either **replaces** its parent's rather than adding
+  to it. That is the rule and not an oversight: a being's blueprint is
+  exactly what the class in front of you declares, in the order she chose,
+  and a merge would hand her asks she may mean to drop and an order she did
+  not write. A subclass that means to extend says so, in one spelling,
+  `static override asks = { ...Parent.asks, mine: {} }`, and the same for
+  cells. A parent that means to be subclassed at all annotates rather than
+  infers, `static override cells: JsonObject = { ... }`, since this language
+  holds a subclass's static side to its parent's and would otherwise refuse a
+  subclass declaring fewer keys than the parent happened to write.
+- `answer` is written for her. The empty ask is `describe(asker)`, which she
+  may override by hand. A named ask calls the method of that name with
+  `(args, asker)`. Anything not declared, hidden from this asker, or
+  inherited from Object's prototype is `{ error: 'unknown ask' }` and the
+  method is never entered.
+- A declared ask with no method, or one named after the base's own members,
+  fails at birth, loudly, so a boot fails and nothing half-lives. The
+  method is one on her prototype chain below Object's: a class field
+  holding a function is not there yet when the base checks, and the
+  refusal says so.
+- `occupant(asker)` is the occupant record for whoever is at the door, and
+  undefined at a public being. `invite`, `knock`, `take`, `boot`, `cells`,
+  `standings` and `occupants` reach the stance and nothing else.
+
+### Examples
+
+The smallest being. Answers whoever her ward names, describes one ask.
+
+```js
+class Echo {
+  constructor(stance) {
+    this.s = stance;
+  }
+  answer(asker, method, args) {
+    if (method === undefined) return { asks: [{ name: 'echo', input: {} }], notes: {} };
+    return { from: asker.id ?? null, ...args };
+  }
+}
+```
+
+A shop. Invites in her own time, hands the invitation out by any channel,
+and takes a guest back only if the guest offers a way.
+
+```js
+class Shop {
+  constructor(stance) {
+    this.s = stance;
+  }
+  async invite(name) {
+    const id = `g-${name}`;
+    const inv = await this.s.occupants.invite(id);
+    this.s.cells.occupants[id].notes.expireAt = 2028; // hers, not Quo's
+    return inv; // goes by mail
+  }
+  async answer(asker, method, args) {
+    if (method === undefined) return { asks: [{ name: 'hello', input: {} }], notes: {} };
+    if (asker.id === undefined) return { welcome: false }; // a stranger at the public door has no record
+    const rec = this.s.cells.occupants[asker.id];
+    if (method === 'hello' && args.invitation) {
+      const back = await this.s.standings.knock(args.invitation, 'hi');
+      if (back !== silence && !isUnreached(back))
+        await this.s.standings.take(`back-${asker.id}`, args.invitation);
+    }
+    return { welcome: rec.notes.expireAt > 2026 };
+  }
+}
+```
+
+A guest. Consumes an invitation, and only then decides to keep the shop.
+
+```js
+class Guest {
+  constructor(stance) {
+    this.s = stance;
+  }
+  async join(invitation) {
+    const mine = await this.s.occupants.invite('shop'); // so the shop can reach me
+    const out = await this.s.standings.knock(invitation, 'hello', { invitation: mine });
+    if (out === silence || isUnreached(out)) return out; // nothing was born
+    await this.s.standings.take('shop', invitation); // now, and only now
+    return out;
+  }
+  answer(asker, method) {
+    if (method === undefined) return { asks: [{ name: 'hi', input: {} }], notes: {} };
+    return { heard: method };
+  }
+}
+```
+
+A relay. Forwards every ask to one standing and never looks inside, and asks
+for a short wait because she is one door of several. Silence passes through
+her; a word does not, since a word out of a being is `threw` at the door,
+D13, so she says it as an error of her own.
+
+```js
+class Relay {
+  constructor(stance) {
+    this.s = stance;
+  }
+  async answer(asker, method, args) {
+    const out = await this.s.standings.next.ask(method, args, { time: 2000 });
+    return isWord(out) ? { error: wordOf(out) } : out; // unreached and late reach her asker as an error, not as a throw
+  }
+}
+```
+
+A watcher. Notices a standing changed shape, then decides.
+
+```js
+class Watcher {
+  constructor(stance) {
+    this.s = stance;
+  }
+  async answer(asker, method, args) {
+    if (method === undefined) return { asks: [{ name: 'poke', input: {} }], notes: {} };
+    const out = await this.s.standings.src.ask('read', args);
+    const rec = this.s.cells.standings.src;
+    if (rec.seen !== rec.digest) {
+      const bp = await this.s.standings.src.ask(); // refresh, or
+      if (!bp?.asks.some((a) => a.name === 'read')) this.s.standings.remove('src'); // walk away
+    }
+    return out;
+  }
+}
+```
+
+## The ward side
+
+The protocol names the ground as seven capabilities and leaves how they are
+gathered to a kit. This kit gathers them into one object, `Ground` in
+`src/ward/ground.ts`, with one name each:
+
+```
+ground
+  seed          bytes, or a string. 32 bytes are the seed; anything else is SHA-256'd to 32 bytes first.
+  memory        the partition. an object.
+  instantiate   (class name, stance) -> object | null
+  carry         (ward pk, bytes) -> bytes | undefined       undefined: no door was reached. a throw is read the same.
+  random        (n) -> n bytes of entropy
+  wrote         () -> nothing. said after every write to the partition. left out by a harbor that keeps nothing.
+  lend          lend(name, take) -> taken. left out by a harbor that lends nothing.
+```
+
+Beside that contract are the three pieces every harbor in this kit builds one
+out of: `maker`, the code half, which finds a class by own key in the first
+registry that holds it and remembers the object by the cells; `entropy`, the
+one line every terrain has; and `learnPk`, the empty ask, since a harbor
+learns its ward's pk the way anyone learns anything and has no second
+derivation to keep in step. They are convenience and never contract: a kit
+writes its own harbor, and may write these again.
+
+The cells guard is `src/ward/cells.ts`. Beside the nesting bound the protocol
+sets, it refuses a hole in a list, an accessor and a key named `__proto__`,
+because this runtime reads each one back as something JSON never wrote. The
+same guard reads args at the seal and her answer at the door.
+
+It also bounds breadth, at `BREADTH`, a million values, which is this kit's
+number and no word of the protocol: a bound on what a being holds is never
+the protocol's business, and what crosses is bounded in bytes at the seal.
+Depth alone does not bound what a value costs to keep. One subvalue may sit
+under two keys, and nesting that forty levels deep is inside the nesting
+bound and is a trillion values once written down. So the walk counts the tree
+while it proves the graph, and a value already counted is a value already
+proven: a graph that shares is walked once per node and never once per path,
+which is the difference between a guard and a ward stopped by one write.
+
+The names this kit reserves beyond `OWNER` and `PUBLIC` are `__proto__`,
+`knock`, `take` and `remove`. The last three are the calls on `standings`,
+which is an object here whose methods are named on the same face as her ids,
+so a standing under one of them would be unreachable. A kit with free
+functions has no such collision, and no far ward can tell either way, because
+an id never crosses a door.
+
+This ward's allowance is thirty seconds by default and five minutes at the
+ceiling, in `src/ward/allowance.ts`. Those two numbers are a ward's own
+policy, never negotiated and never on the wire.
+
+The partition shape is `src/ward/partition.ts`, and the three bounded lists
+the protocol leaves to a ward are numbers here: eight pks under `minted`,
+and `gone` and `knocks` bounded the same way, oldest out. `last` on the heir
+is the cut slot for a reply a later version might keep; nothing writes it and
+nothing reads it.
+
+The seal is `src/ward/seal.ts` and the arithmetic is `src/ward/arithmetic.ts`.
+`SIZE` there is the protocol's one mebibyte, read before an ask is opened and
+before a reply is. `test/ward.test.ts` reads every byte string that crossed,
+so that nothing inner is readable in the bytes.
+
+An ask over two wards on two harbors spends thirty-four calls into
+`crypto.subtle`, fourteen of them key imports, and `test/cost.test.ts` holds
+it to forty and sixteen. Importing a key is the most expensive thing on that
+path and most of the imports are the same key again: a ward signs every reply
+with one key, opens every ask with one padlock, and verifies a relation under
+the key it verified it under last time. So the arithmetic keeps an imported
+key by the bytes it was imported from, and the public half beside the key it
+was read from. The cache is bounded at `KEYS`, five hundred and twelve, least
+recently used out, because a relation mints a fresh key on every ask and one
+that only grew would hold a key for every ask a ward ever made. None of it is
+a decision a peer can see: a kit that caches nothing speaks the same bytes,
+which is why this is the kit's paper and not the protocol's.
+
+## The harbor side
+
+The **store** is `src/harbor/store.ts`, the **reach** is
+`src/harbor/reach.ts`, the **harbor core** is `src/harbor/core.ts` and the
+**dialer** is `src/harbor/dial.ts`. Both kinds of reach are written on the
+standard surface every terrain carries, fetch and WebSocket. The memory store
+beside the store interface is the kit's own; a disk, a tab and an edge object
+each have theirs, outside this tree, and every one of them passes
+`src/conformance/store.ts` untouched, as every reach passes
+`src/conformance/reach.ts`.
+
+The dialer's wait doubles from a second to thirty when a line drops, and
+returns to that first second where the far side announced and was taken.
+Those are this harbor's numbers: what a far side sees is only that a dialer
+refused for a suite waits.
+
+## The memory harbor
+
+The memory harbor, `src/harbor/memory.ts`, is one process and no wire. It
+keeps partitions by seed, routes its own doors, and may be linked to peers,
+which stands in for a wire, and cut, which stands in for weather. It routes
+one hop: a pk that is not its own and not a direct peer's is nothing. It
+keeps no lease: two of them may hold one seed and one partition, which is
+the broken vouch every real harbor refuses, kept here so that the tests can
+show what divergence looks like. Every ward and being assertion in the tree
+is made on it first, so that the network never hides a fault in the words;
+the harbor core then passes the same suite over memory stores.
+
+## The suites
+
+The beings are fixed and the ward is what is tested. A ward kit in any
+language offers the ground, the door, and the owner's ask as written, and
+passes the same suite. Those tests are the checklist, not the mock.
+
+- `test/being.test.ts`: the base class against a stance stub. No ward, no
+  harbor. Defaults, describe, dispatch, the gate, the reserved names, the
+  digest.
+- `src/conformance/index.ts`: one suite of behaviours, written against the
+  stance and one probe. `World` is this kit's spelling of the six obligations
+  the protocol names for a probe, and `conform` takes a call that makes one.
+  A kit hands the suite its ward's heir table and
+  bind table as values, and a forged knock, so the suite can see that a
+  refusal wrote nothing and a knock bound what it should. It reads the
+  tables and never writes them; the forged knock is the one thing it sends
+  through a door. With the beings in `src/conformance/beings.ts`: a
+  printer, a shop, two customers, one raw being with no base class, and a
+  member of an estate. The probe is asked to build a world, and what it is
+  asked for includes what the box lends: a name and the class of the being
+  it lends under it. The harness stands one of each in a ward its harbor
+  roots and grounds every ward it boots to lend them, which is how the
+  seventh member is reached from inside the suite. A harness with no such
+  ward to stand says `canLend: false` at the call and that chapter skips,
+  named, the way `canDown` already works. Any ward must pass it, under any
+  topology.
+- `src/conformance/estate.ts`: the estate, and the last chapter of that
+  suite. Every other chapter is a scene: three beings, one move, one answer.
+  This one is a graph under churn, which is the shape an organisation running
+  on Quo actually has -- scattered wards on scattered harbors, partners and
+  employees invited, knocking, taken, kicked, and moving to harbors of their
+  own. It keeps a model of the graph, plays legal moves against it from three
+  fixed seeds, and after every move holds two things: that the ledger every
+  ward keeps closes on both ends, and that every arc in it answers when asked
+  exactly what being that arc means. The second is held under all three
+  topologies, and that is the promise of Quo at a scale a scene cannot
+  reach: the model never learns the topology, so neither may any answer. The
+  model is the script's own bookkeeping and is never compared with itself
+  across topologies, which would hold by construction and prove nothing. A
+  relation is two arcs and never one edge:
+  the occupant is the host's, the standing is the guest's, and the model
+  keeps them apart because the ward does. A red run prints its seed and the
+  moves that got there. It is read beside one hand-written story that says in
+  prose what the model is for.
+- `test/ward.test.ts`: the conformance suite against the real ward under
+  three topologies over the memory harbor, one ward, one harbor with a ward
+  per being, two harbors; and what only a real ward can be asked: the
+  owner's asks, the door judged byte by byte, rotation and a lost reply,
+  replay, a restart, and every byte on the wire inspected for anything inner.
+- `test/public.test.ts`: the public being, what the door does and does not
+  do for her.
+- `test/silence.test.ts`: the protocol's chapter "Silence, the words, error"
+  by its numbers: the five cases and two unreacheds of her ward, the thirteen
+  cases of the door with a partition snapshot under each, seven strangers
+  met with one silence and six bound keys hearing their word, hops refused
+  at zero, and the six lines of the law of one silence. The world it runs in
+  and the thirteen cases as records are `test/door.ts`, which draws no
+  entropy from the device: every byte comes from one SplitMix64 stream, so
+  the cases are the same bytes twice. The suite reads
+  `protocol/vectors/door.json` and holds the tree to it, and the two laws it
+  states over the whole list, one length for every stranger and one
+  plaintext under the box, run over the corpus rather than a table beside
+  it. `test/write-door-vectors.ts` writes that corpus, by a hand and never
+  by the gate: a diff in it is a protocol change.
+- `test/blueprint.test.ts`: blueprints and instantiation through a real
+  ward. What a boot leaves behind, what a restart brings back when the code
+  moved under the cells, the gate and the door, the reserved ids.
+- `test/allowance.test.ts`: the allowance. Default, ceiling, nonsense, the
+  bound, the signed body, the door's refusal, and one ask through a ward.
+- `test/lend.test.ts`: the seventh member of the ground, over two real wards
+  on one memory harbor. The ground answers an invitation and the ward knocks
+  and takes it, so a being is handed an id and never the value; null is every
+  kind of no; a being of the harbor's own ward wakes her by holding a
+  standing she minted, and her door names it as the occupant she chose;
+  removing that occupant is the whole of unsubscribe; the relation is born
+  again under the same id; a taker that will not take leaves the faculty no
+  occupant and no key, and the next lend stands; and a being taken out of her
+  ward lends nothing.
+- `test/seal.test.ts`: the arithmetic against `protocol/vectors/arithmetic.json`,
+  then the seal, round trip, and what it refuses; then the framing against
+  `protocol/vectors/framing.json`. The arithmetic is standard and any language has
+  it. The framing is Quo's own, and a kit that reproduces the hashes and
+  not the ward pk, the digest, the signed ask body, the two sealed shapes,
+  the invitation or the knock is not this protocol. Every seed in that file
+  is fixed, so every output is fixed. The ask body is the payload as JSON
+  and is not canonical: the vectors pin the order the type declares, and a
+  kit that emits another order interoperates, because a door verifies the
+  bytes it received, and will not reproduce the vectors. `hops` is in no
+  vector, because nothing sets it. The invitation is JSON too, and the
+  knock is pinned as the ask it is, by the heir, to the heir, announcing
+  the knocker's own key, and then proven at a real door: a ward booted on
+  the vector's seed, drawing the heir secret as its first entropy, mints
+  the invitation vector, binds the knock vector at its door, answers it,
+  spends the heir, and refuses the same bytes again.
+- `test/break.test.ts`: adversarial probes. Each states what the protocol
+  promises, then tries to break it.
+- `test/gaps.test.ts` and `test/gaps2.test.ts`: cases the memory harbor
+  cannot express because it is honest, in-order and lossless: a lost reply,
+  a cycle, a partition written down and read back, a long relation, one
+  seed booted twice. Each test is a claim that the ward is wrong; one that
+  will not go red is not a bug.
+- `src/conformance/store.ts`: the store suite, written against the store
+  interface alone and handed a maker of fresh stores. A fresh store keeps
+  nothing; what was put comes back as it went in, as values and not as the
+  object; a name already kept is refused; save and record touch only their
+  part and are nothing on a name not kept; take hands a ward out and frees
+  the name; hints are kept by pk and the last one wins.
+- `src/conformance/reach.ts`: the reach suite, written against the reach
+  interface alone and handed a far side it controls: a door held behind a
+  pk over there, and the far side dropped. The door's bytes come back;
+  nothing for a pk nobody holds; asks in flight at once each get their own
+  answer; what crosses is a copy both ways; and once the far side is gone,
+  nothing. It cannot assert that a reach which sent and then lost the line
+  answers nothing at all, since a suite cannot wait forever.
+- `test/harbor.test.ts`: the harbor pieces on the library's own ground,
+  no device and no wire. The store suite against the memory store; the
+  reach suite against the socket framing over two lines in one process, so
+  the frames are asserted with no network under them; the conformance
+  suite against two harbor cores over memory stores reaching each other
+  in-process, drop and adopt as the migration; a ward that moves harbor
+  keeping its pk and every relation, the rendezvous told on the line in
+  hand; a ward booted or dropped after a line opened, announced on that
+  line, and a claim on a pk nobody holds binding nothing; a restart from
+  the store with the hints; the dialer over a stubbed line, announce, a claim proven
+  at a real door before it binds and a claim nobody there holds left
+  unbound, fallback, unbind and the wait before it dials again; and the frames against
+  `protocol/vectors/wire.json`, the ask, the reply, nothing delivered and the
+  announce, so a kit reproduces the bytes on a socket; and the request
+  reach against the request record in the same file, over a fetch that
+  sees what a listener would, one POST with the suite in its header, the
+  reply as a 200 and nothing delivered as a 404. A socket to a real
+  listener and every real store pass the same suites outside this tree.
+- `test/terrain.test.ts`: the terrain census. Nothing under `src/being/`,
+  `src/ward/`, `src/harbor/` or `src/conformance/` names a runtime, and
+  nothing reaches for a global outside the ones it names; nor does the
+  census name one the tree has stopped using. It reads the source as text
+  and not as a parse: it is there to catch drift, and does not pretend to
+  stop someone determined to get around it.
+- `test/assert.test.ts`: `src/conformance/assert.ts` against
+  `node:assert/strict`, pair by pair. The suite means the same thing on
+  every terrain only if those two agree, so they are compared and not
+  trusted.
+- `test/floor.test.ts`: the five algorithms this terrain must carry, probed
+  one by one; that the arithmetic spends every one of them; and the two ways
+  a terrain can be short -- no `crypto.subtle` at all, and a subtle without
+  the curves -- each failing at the first call, in one sentence.
+- `test/cost.test.ts`: what an ask costs. Every other suite is blind to it:
+  a change that doubles the work per ask leaves all of them green. The
+  assertion is the count of calls into `crypto.subtle`, which is the same
+  number on every terrain and does not move because another lane of the gate
+  is running; a regression in it is somebody deriving again what the ward
+  already holds. Beside it, that the kept keys stay under their bound however
+  long a ward talks, and one wall clock set an order of magnitude wide, which
+  is a smoke alarm and not a measurement.
+- `test/package.test.ts`: the package as a stranger meets it. The tarball
+  is packed, installed into an empty folder with nothing but Node, and
+  every entry point the exports map names is imported. Every other suite
+  reaches the source through a path or a workspace link, which resolves
+  outside `node_modules`, where Node strips types; this is the one that
+  cannot.
+- `test/bundle.test.ts`: the three words bundled as a consumer must bundle
+  them, the artefact read for anything a terrain cannot provide, and then the
+  whole conformance suite run out of the bundle.
+- `test/terrain/browser.test.ts`, `test/terrain/edge.test.ts`,
+  `test/terrain/deno.test.ts` and `test/terrain/bun.test.ts`: that same
+  bundle and that same suite in a real Chromium, in workerd, in Deno and in
+  Bun, plus each terrain's floor, and, for the browser, a page whose
+  `crypto` has no `subtle`. Deno runs it a second time with every permission
+  denied but read -- no net, no environment, no write, no subprocess -- which
+  is where a ward that had quietly come to need one of them would fail, and
+  nowhere else in this repository. A terrain whose binary is absent skips and
+  names the command that installs it; it never passes quietly.
+  `test/terrain/engine.ts` runs the bundle in another engine on this machine.
+  Behind `npm run check:terrain`. `test/terrain/bundle.ts` is the
+  bundler and the reference run, `test/terrain/exercise.ts` is what every
+  terrain runs, `test/terrain/floor.ts` is the floor -- each written once, so
+  no terrain can be probed for less than another.
+- `test/world.ts`: the memory-harbor probe and the three topologies, held
+  apart from any one chapter because every terrain drives the same one. It
+  also answers the two asks the estate needs: the census, which is every
+  partition in the world as values, and a migration, which lifts a partition
+  out of one harbor and boots it from the same seed in the other -- same
+  seed, same pk, so every standing anyone holds still points at her.
+- `test/repo.test.ts`: the papers, the README and the project instructions
+  against the repository: every path they name exists, every
+  source file carries its licence, the package names no host and no user,
+  the awaitable calls are marked and
+  awaited in the examples above, the allowance is decided in the protocol and
+  off its Open list, and the allowance is time alone on both sides of the
+  door.
+
+The conformance suite is checkable wherever a ward runs. Its runner is handed
+in, and the five assertions it makes are `src/conformance/assert.ts`, held to
+`node:assert/strict`'s own behaviour by `test/assert.test.ts`.
+`test/terrain/exercise.ts` is what every terrain runs -- the whole suite,
+under all three topologies, and the floor probe. Node is the reference: no
+terrain carries a count of its own, so a test added to the suite is demanded
+of every terrain at once. Five run it: Node, a browser, workerd, Deno and
+Bun. Bun is the one that is not V8, so "the language alone" is checked
+against two implementations of the language and not one.
+
+## The gate
+
+The gate is `npm run check`: typecheck under TypeScript 7, oxlint with
+type-aware rules, markdownlint, then every suite under `node --test`. There
+is no CI; the gate runs in seconds and is run before every commit. Nothing
+red is committed except a test marked todo, which is a claim the tree does
+not yet meet and says so.
+
+`npm run check` is Node alone, and stays fast. `npm run check:terrain` is
+every other terrain, the browser, workerd, Deno and Bun, kept apart because
+each is a binary of its own and the browser is a download and not a
+package: a fresh clone needs `npx playwright install chromium` first, and is
+told so in one sentence rather than a stack trace.

package/src/being/being.ts

@@ -16,14 +16,14 @@ export type AskSpec = {
 };
 
 // Names a subclass may not use for an ask, because they are the base's own.
-const RESERVED = new Set(['answer', 'describe', 'stance', 'cells', 'standings', 'occupants', 'occupant', 'invite', 'knock', 'take', 'boot', 'constructor']);
+const RESERVED = new Set(['answer', 'describe', 'stance', 'cells', 'standings', 'occupants', 'occupant', 'invite', 'knock', 'take', 'boot', 'lend', 'constructor']);
 
 // Whether she has a method of that name, written on her own prototype chain
 // below Object's. A name Object lends every object, `hasOwnProperty` or
 // `toString`, is not a method she wrote; and a field she assigns in her own
 // constructor is not there yet when the base checks, so an ask is a method
 // on the prototype and nothing else.
-const method = (self: object, name: string): boolean => {
+const wrote = (self: object, name: string): boolean => {
   for (let p = Object.getPrototypeOf(self); p !== null && p !== Object.prototype; p = Object.getPrototypeOf(p)) {
     if (Object.hasOwn(p, name)) return typeof (p as Record<string, unknown>)[name] === 'function';
   }
@@ -51,7 +51,7 @@ export class Being {
     const C = this.constructor as typeof Being;
     for (const name of Object.keys(C.asks)) {
       if (RESERVED.has(name)) throw new Error(`ask '${name}' is a reserved name`);
-      if (!method(this, name)) throw new Error(`ask '${name}' has no method on the prototype`);
+      if (!wrote(this, name)) throw new Error(`ask '${name}' has no method on the prototype`);
     }
     // Own keys only: a default named after a member of Object's prototype is
     // still hers, and still missing until she writes it.
@@ -67,6 +67,11 @@ export class Being {
   get occupants(): Occupants {
     return this.stance.occupants;
   }
+  // A standing at one of the things this device can do, under an id of hers.
+  // The ward knocks and takes it for her; the invitation never reaches her.
+  lend(name: string, id: string): Promise<string | null> {
+    return this.stance.lend(name, id);
+  }
   invite(id: string, notes?: JsonObject): Promise<Invitation | null> {
     return this.stance.occupants.invite(id, notes);
   }

package/src/being/index.ts

@@ -3,5 +3,5 @@
 export { Being, type AskSpec } from './being.ts';
 export { silence, isSilence, answered, unreached, isUnreached, word, isWord, wordOf, told, DOOR_WORDS, isDoorWord } from './silence.ts';
 export { digest, canonical } from './digest.ts';
-export { OWNER, PUBLIC, RESERVED_IDS, isBlueprint, invitationArgs } from './types.ts';
+export { OWNER, PUBLIC, RESERVED_IDS, isBlueprint, invitationArgs, isInvitation } from './types.ts';
 export type * from './types.ts';