nervur 0.16.0 → 0.17.1

package/GETTING_STARTED.md

@@ -0,0 +1,138 @@
+# Getting started
+
+Quo lets an object ask another object and get an answer, without knowing
+whether that other object is in the same process, on the same device, or
+on another planet. Three words: a harbor boots wards, a ward keeps beings
+and judges its door, and a being is one ordinary object with one voice.
+This is the shortest road from nothing to each of the three, for a
+stranger with a terminal. `SPEC.md` is the truth behind every sentence
+here and assumes nothing; `quo-dock.md` is the dock, the part a box runs.
+
+Quo is the protocol and Nervur is this kit of it. Every name you install
+and every command you type is Nervur's; `quo` stays on the wire, as the
+`quo.` route a ward's door answers at.
+
+Two packages, and you start with the one that fits what you have:
+
+- `nervur`, the library. A harbor, a ward and a being in one
+  process, no wire, no files. For a program that wants Quo inside it.
+- `@nervur-org/dock`, the dock. A daemon and one command, `nervur`, that
+  stand a box up: a person's world with a page, a model's side, an api, a
+  door on the wire. For a box that receives people and models.
+
+The command is in the dock and not in the library, so `npm install nervur`
+gives you something to import and no command, and the command arrives with
+`npm install -g @nervur-org/dock`. That is how a kit of this shape is
+always named: one unscoped headline name for the library, the parts under
+the scope, and the CLI in the package that owns it.
+
+## A being, in one process
+
+```bash
+npm install nervur
+```
+
+A being is a class with `asks`, the methods anyone may reach, each with
+the JSON schema of its input. Everything else on the class is hers alone.
+
+```js
+import { Being } from 'nervur';
+import { Ward } from 'nervur/ward';
+import { MemoryHarbor } from 'nervur/harbor';
+
+class Shop extends Being {
+  static asks = { price: { input: { type: 'object', properties: { item: { type: 'string' } } } } };
+  price({ item }) {
+    return { item, eur: 12 };
+  }
+}
+class Customer extends Being {
+  static asks = {};
+}
+
+const harbor = new MemoryHarbor();
+const ward = await harbor.boot('acme', Ward, { Shop, Customer });
+await ward.ask('boot', { key: 'shop', class: 'Shop' });
+await ward.ask('boot', { key: 'ana', class: 'Customer' });
+```
+
+The harbor booted a ward named `acme` with two classes it may make beings
+of, and the ward's owner, the process itself, booted one of each by key.
+The ward's own asks are seven, `boot`, `public`, `invite`, `knock`,
+`remove`, `unboot` and `ask`, and `ward.ask()` with no method is her
+describe: those asks and her `notes`, the ward's `pk` and her beings.
+
+Nobody reaches a being she has not invited. An invitation is minted on a
+being for one id, the shop's for `ana`, and the customer knocks with it;
+from then she holds a standing at the shop, under the name she took, and
+the shop holds her as an occupant.
+
+```js
+const invitation = await ward.ask('invite', { being: 'shop', id: 'ana' });
+const ana = harbor.objects.get(harbor.partitions.get('acme').beings.ana);
+await ana.knock(invitation);
+await ana.take('shop', invitation);
+console.log(await ana.standings.shop.ask('price', { item: 'bread' }));
+// { item: 'bread', eur: 12 }
+```
+
+That is the whole protocol: a standing on one side, an occupant on the
+other, an ask that rides the relation and an answer that rides it back.
+The two beings here share a process; the same lines hold when the shop is
+on a box across the sea, because a standing is an address and a key, and
+the harbor owns the wire. `harbor.objects` is the memory harbor's hand for
+a test and a first program; a being on a real box is reached through her
+ward, never held.
+
+## A box
+
+```bash
+npm install @nervur-org/dock
+npx nervur init --dir ~/.nervur --ward acme --user ana --domain acme.com --default --show
+npx nervur serve --dir ~/.nervur --http 8787
+```
+
+`init` mints the ward `acme`, boots ana's user being, her doorbell and
+the desk in it, marks it the default ward and shows it at the web route,
+and writes `routes.json`, the four routes of a box, `mcp.`, `web.`, `quo.`
+and `api.` under the domain, for a proxy to map onto the one loopback
+port. Without `--domain`, write it yourself; on a Mac the four are paths
+at one loopback address:
+
+```json
+{ "mcp": "http://127.0.0.1:8787/mcp", "web": "http://127.0.0.1:8787/web", "quo": "http://127.0.0.1:8787/quo", "api": "http://127.0.0.1:8787/api" }
+```
+
+`serve` is the daemon, the one process over that folder, and every other
+command is its client. From a second terminal, a phone:
+
+```bash
+npx nervur invite --dir ~/.nervur '{"being":"ana","id":"phone"}'
+```
+
+The answer carries `link`, the ward's page with the invitation in its
+fragment. Opened on the phone, the tab boots a harbor of its own, joins as
+that device, and is in: no account, nothing typed. What a model gets is
+the same world as tools at `mcp.`, what a program gets is the same asks as
+JSON at `api.`, and what another box gets is the door at `quo.`; a being
+answers each the same, because each is an ask at her door.
+
+The box's own doings are rows on the faculties of its dock ward, placed by
+the root with `nervur ask --ward dock`: a socket held to another box, an
+agent run for a ward, a schedule on the clock. A second box owns this one
+across the wire with an invitation on the ward's own pk, knocked with
+from there, and every owner command with `--via` from then on. Each of
+those, the edge, and what an estate stands beyond the init, is the
+"Getting started" chapter of `quo-dock.md`, proven cold on a Mac by
+somebody with nothing else to read.
+
+## Your own beings on a box
+
+A box holds the dock's classes and yours. `classes/index.ts` beside the
+wards exports each of yours by name, and `nervur boot '{"key":"shop",
+"class":"Shop"}'` boots one; `nervur init --class Shop` makes the ward's home
+being one of yours, an organisation's ward with the org as its being. A
+being's asks may name who may reach them, `for`, over the record of the
+occupant asking, and her `cells` are what she keeps between boots: the
+whole of what a being is, in `SPEC.md`, and the words above the spec, a
+world, a home, a membership, in `WORLDS.md` and `GLOSSARY.md`.

package/NOTICE

@@ -1,4 +1,4 @@
-Quo
+Nervur
 Copyright 2026 Razvan Gherghina
 
 This product includes software developed by Razvan Gherghina.

package/README.md

@@ -1,32 +1,120 @@
-# nervur
+# Nervur
+
+Nervur is the first open source kit of Quo, the library itself: harbor, ward
+and being, with the spec and the vectors inside, and no dependencies.
 
 Quo is a protocol that lets an object ask another object and get an answer,
-without knowing whether that other object is in the same process, on the
-same device, or on another planet. Nervur's kit is its first implementation,
-open source, three packages under the `@nervur-org` scope.
+without knowing whether that other object is in the same process, on the same
+device, or on another planet. Quo is the protocol and this is one
+implementation of it; the two names never stand for the same thing.
+
+It is three words, two of which are beings, and two edges.
+Nothing else is Quo.
+
+- **Harbor.** The program a device runs to boot wards. Owns the wire and the
+  operating system. Not a being.
+- **Ward.** One process of its harbor. A being plus ward functions. Keeps
+  beings and judges its door.
+- **Being.** One ordinary object, one voice.
+
+[`protocol/SPEC.md`](protocol/SPEC.md) is the truth. It is the protocol
+alone: what any ward in any language must do for its bytes to be Quo. It is
+self-contained and assumes nothing from any other document, this README
+included. Read it first.
+[`quo-kit.md`](quo-kit.md) is this kit: what one TypeScript
+implementation chose and another kit may refuse. It assumes the spec, and
+where the two disagree the spec wins.
+
+## This package
+
+A TypeScript implementation, written against Node's own type stripping, with
+no dependencies. The package ships JavaScript with declarations beside the
+source it was emitted from, because Node strips types nowhere under
+`node_modules`.
+
+```
+protocol/         the shelf a kit in any language reads: SPEC.md and the vectors, no code
+protocol/vectors/ fixed inputs and outputs, so another language proves its bytes
+src/being/        the Being side: what a being author imports, if anything
+src/ward/         the ward: the Ground contract, door, seal, arithmetic, heirs, stance, allowance
+src/harbor/       MemoryHarbor, and the harbor core with its store, reach and dialer
+src/conformance/  behaviours any ward must show, written against the truth
+```
 
-This package is the unscoped twin of that scope. `import` from it and you
-have the library; run it and you have the dock's command:
+The suites live beside the source in the tree this is developed in and are
+not in the package: what proves the kit is not what a consumer installs.
+What does ship of them is `src/conformance/`, which is the part written for
+somebody else's ward rather than for this one.
 
-```bash
-npm install nervur
-npx nervur init
+## Requirements
+
+Node 22.18 or later, and nothing else. The package has no dependencies, and
+it ships JavaScript with declarations, so nothing is compiled on the way in.
+
+## Where it is proven
+
+The same conformance suite this package exports runs against several worlds:
+one ward, one harbor with a ward per being, two harbors, and the harbor core
+over a memory store. A world declares what it can express and a chapter it
+cannot reach is skipped by name rather than failed, which is how a kit in
+another language reports the same suite honestly.
+
+It is run again out of a bundle in a real Chromium, in workerd, in Deno and
+in Bun, because a ward's truth must hold wherever a ward runs.
+
+## Entry points
+
+```js
+import { Being, silence, digest } from 'nervur';
+import { Ward } from 'nervur/ward';
+import { MemoryHarbor, Harbor, request, dial } from 'nervur/harbor';
+import { conform } from 'nervur/conformance';
+import { Stand } from 'nervur/vector';
 ```
 
-| Package | What it is |
-| --- | --- |
-| [`@nervur-org/nervur`](https://www.npmjs.com/package/@nervur-org/nervur) | the library: harbor, ward and being, the protocol itself, with the spec inside |
-| [`@nervur-org/dock`](https://www.npmjs.com/package/@nervur-org/dock) | what every estate on Quo needs and nobody writes twice: the daemon, the command, the model sides and the screen |
-| [`@nervur-org/ui`](https://www.npmjs.com/package/@nervur-org/ui) | the kit: one token contract, one baseline, and the primitives a screen and a website both need. Knows nothing of Quo |
+## Another language
+
+The hand to a kit in another language is one folder, `protocol/`, and it
+holds two things of two kinds. `SPEC.md` is the protocol, and it assumes
+nothing: a kit is written against it and against nothing else here. The
+vectors beside it are the byte-level hand, everything a stranger can
+observe: `protocol/vectors/arithmetic.json`, the primitives the seal rests
+on, SHA-256, Ed25519, X25519, HKDF and AES-256-GCM;
+`protocol/vectors/framing.json`, Quo's own, the ward pk, the digest, the
+signed ask body, the sealed shapes, the invitation and the knock;
+`protocol/vectors/wire.json`, the frames on a socket and the one request a
+door takes; and `protocol/vectors/door.json`, the door's thirteen cases,
+each one an arrival a ward will not answer, with the bytes that arrive, the
+bytes that leave and the partition's digest on both sides of the judgement.
+They import by name,
+`nervur/protocol/vectors/framing.json`, so a kit's own suite can
+read them from the package. A kit reproduces them or it is not this
+protocol. `door.json` is also replayed from outside, by a verifier holding
+no key, against a kit standing in vector mode, which `SPEC.md` describes
+under that name. This kit stands in it with `Stand` from `nervur/vector`,
+which is vector mode and names no runtime: put it behind any listener that
+hands it a request body and returns what it answers.
+
+Nothing outside that folder is the protocol. `src/` is this kit's
+interpretation, and `src/conformance/` is a checklist a kit ports rather
+than a harness it runs: it imports the base class, the silence spelling and
+this kit's store and reach, so the beings it is shown with run only in a
+TypeScript ward. `quo-kit.md` "The three shelves" says which is which.
+
+## Versions
 
-It pins the library and the dock exactly, so that the name stands for one
-kit. Its own number counts up on its own, because a name and what it
-stands for are two things. An estate that wants the pieces apart installs
-them apart.
+No compatibility promise before 1.0.0: the words may still move, and there
+is no migration to write because there is nothing yet to migrate from. This
+package carries the version of its own work and is bound to no other's, so a
+number equal to `@nervur-org/dock`'s or `@nervur-org/ui`'s is a coincidence.
 
-<https://nervur.org> is the kit. <https://quo.systems> is the protocol.
+What ships is the emitted `dist/`, the source it came from, the protocol
+shelf with the spec and the vectors inside it, this file, the licence and
+the notice. No tests and no configs. The spec ships because it is the truth
+the source and the vectors are read against, and a package a stranger reads
+with no truth beside it is a pile of names.
 
 ## License
 
 Apache-2.0. Copyright 2026 Razvan Gherghina. See [LICENSE](LICENSE) and
-[NOTICE](NOTICE).
+[NOTICE](NOTICE); every source file carries an SPDX line.

package/dist/being/being.d.ts

@@ -0,0 +1,24 @@
+import type { Asker, Blueprint, Cells, Invitation, JsonObject, Wanted, OccupantRecord, Occupants, Reply, Schema, Stance, Standings, Answer } from './types.ts';
+export type AskSpec = {
+    description?: string;
+    input?: Schema;
+    output?: Schema;
+    for?: (occupant: OccupantRecord | undefined, asker: Asker) => boolean;
+};
+export declare class Being {
+    static cells: JsonObject;
+    static asks: Record<string, AskSpec>;
+    readonly stance: Stance;
+    constructor(stance: Stance);
+    get cells(): Cells;
+    get standings(): Standings;
+    get occupants(): Occupants;
+    lend(name: string, id: string): Promise<string | null>;
+    invite(id: string, notes?: JsonObject): Promise<Invitation | null>;
+    knock(invitation: Invitation, method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+    take(id: string, invitation: Invitation): Promise<string | null>;
+    boot(className: string, key: string, id?: string): Promise<string | null>;
+    occupant(asker: Asker): OccupantRecord | undefined;
+    describe(asker: Asker): Blueprint;
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
+}

package/dist/being/being.js

@@ -0,0 +1,109 @@
+// 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', '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 wrote = (self, name) => {
+    for (let p = Object.getPrototypeOf(self); p !== null && p !== Object.prototype; p = Object.getPrototypeOf(p)) {
+        if (Object.hasOwn(p, name))
+            return typeof p[name] === 'function';
+    }
+    return false;
+};
+// Both statics below are read off the class the object was made from, so a
+// subclass declaring either replaces its parent's rather than adding to it.
+// That is the rule: her blueprint is exactly what the class in front of you
+// declares, in the order she chose, and merging down a chain would hand her
+// asks she may mean to drop and an order she did not write. A subclass that
+// means to extend says so, `static override asks = { ...Parent.asks, mine: {} }`.
+export class Being {
+    // Her cells' defaults. Merged in at birth, only where a key is missing, so
+    // a restart keeps what she wrote.
+    static cells = {};
+    // What she can be asked. Declaration order is blueprint order, except a
+    // name that reads as an array index, which the language lists first.
+    static asks = {};
+    stance;
+    constructor(stance) {
+        this.stance = stance;
+        const C = this.constructor;
+        for (const name of Object.keys(C.asks)) {
+            if (RESERVED.has(name))
+                throw new Error(`ask '${name}' is a reserved name`);
+            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.
+        for (const [k, v] of Object.entries(C.cells))
+            if (!Object.hasOwn(stance.cells, k))
+                stance.cells[k] = structuredClone(v);
+    }
+    get cells() {
+        return this.stance.cells;
+    }
+    get standings() {
+        return this.stance.standings;
+    }
+    get 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, id) {
+        return this.stance.lend(name, id);
+    }
+    invite(id, notes) {
+        return this.stance.occupants.invite(id, notes);
+    }
+    knock(invitation, method, args, wanted) {
+        return this.stance.standings.knock(invitation, method, args, wanted);
+    }
+    take(id, invitation) {
+        return this.stance.standings.take(id, invitation);
+    }
+    // A new being of her ward, by class name, under a key she chooses. With an
+    // id, she holds a standing to the being she made, who knows her by her key.
+    boot(className, key, id) {
+        return this.stance.boot(className, key, id);
+    }
+    // The occupant record for whoever is at the door. Undefined at a public being.
+    occupant(asker) {
+        return asker.id !== undefined && Object.hasOwn(this.cells.occupants, asker.id) ? this.cells.occupants[asker.id] : undefined;
+    }
+    // Her blueprint for this asker. Override to shape it by hand.
+    describe(asker) {
+        const C = this.constructor;
+        const rec = this.occupant(asker);
+        const asks = [];
+        for (const [name, spec] of Object.entries(C.asks)) {
+            if (spec.for && !spec.for(rec, asker))
+                continue;
+            const ask = { name, input: spec.input ?? { type: 'object' } };
+            if (spec.description !== undefined)
+                ask.description = spec.description;
+            if (spec.output !== undefined)
+                ask.output = spec.output;
+            asks.push(ask);
+        }
+        return { asks, notes: {} };
+    }
+    // The one function. Override to wrap it; call super to keep the dispatch.
+    async answer(asker, method, args = {}) {
+        if (method === undefined)
+            return this.describe(asker);
+        const C = this.constructor;
+        // Declared, by her, on purpose. `asks` is an ordinary object, so a bare
+        // lookup would also find every name on Object's prototype: `valueOf`
+        // would answer with her stance, `toString` with a string, and neither is
+        // an ask she wrote. Only her own keys are asks, which is what describe
+        // shows. What she shows is what she can be asked.
+        const spec = Object.hasOwn(C.asks, method) ? C.asks[method] : undefined;
+        if (!spec || (spec.for && !spec.for(this.occupant(asker), asker)))
+            return { error: 'unknown ask' };
+        const fn = this[method];
+        return fn.call(this, args ?? {}, asker);
+    }
+}

package/dist/being/digest.d.ts

@@ -0,0 +1,3 @@
+import type { Json } from './types.ts';
+export declare const canonical: (v: Json) => string;
+export declare const digest: (blueprint: Json) => Promise<string>;

package/dist/being/digest.js

@@ -0,0 +1,37 @@
+// A value I-JSON has no room for: a key left empty, a function, a symbol.
+// None of them cross an edge, so none of them may reach a digest. A key
+// carrying one is dropped and a slot carrying one is null, which is what
+// crossing does to them, so the digest names what arrived and not what she
+// happened to be holding.
+const absent = (v) => v === undefined || typeof v === 'function' || typeof v === 'symbol';
+// JCS for I-JSON values: sorted keys, no whitespace, JSON escaping. Numbers
+// are serialized as ES does, which is what RFC 8785 specifies. A hole in a
+// list is null, as JSON writes it.
+export const canonical = (v) => {
+    if (Array.isArray(v))
+        return `[${Array.from(v, (slot) => (absent(slot) ? 'null' : canonical(slot))).join(',')}]`;
+    if (v !== null && typeof v === 'object') {
+        return `{${Object.keys(v)
+            .filter((k) => !absent(v[k]))
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(v);
+};
+// Hex and the guard are spelled here and again in `src/ward/arithmetic.ts`,
+// which is the price of the boundary: nothing under `src/being` imports
+// anything above it, because this is the whole world a being's own code sees
+// and a being reaching the ward is the thing the shape is against.
+const hex = (bytes) => Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, '0')).join('');
+// `crypto.subtle` is read at the call and never captured at load. A browser
+// on a plain http:// origin has `crypto` without `subtle`, and a terrain may
+// install one after this module is first imported; either way the failure is
+// one sentence and not a TypeError from inside a digest nobody can read.
+const subtle = () => {
+    const s = globalThis.crypto?.subtle;
+    if (!s)
+        throw new Error('this terrain has no crypto.subtle: a being needs a secure context to be described');
+    return s;
+};
+export const digest = async (blueprint) => hex(await subtle().digest('SHA-256', new TextEncoder().encode(canonical(blueprint))));

package/dist/being/index.d.ts

@@ -0,0 +1,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, isInvitation } from './types.ts';
+export type * from './types.ts';

package/dist/being/index.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// nervur — the Being side. What a being author imports, if anything.
+export { Being } from './being.js';
+export { silence, isSilence, answered, unreached, isUnreached, word, isWord, wordOf, told, DOOR_WORDS, isDoorWord } from './silence.js';
+export { digest, canonical } from './digest.js';
+export { OWNER, PUBLIC, RESERVED_IDS, isBlueprint, invitationArgs, isInvitation } from './types.js';

package/dist/being/silence.d.ts

@@ -0,0 +1,12 @@
+import { type DoorWord, type Unreached, type Word, type WordName } from './types.ts';
+export declare const silence: unique symbol;
+export declare const isSilence: (x: unknown) => x is typeof silence;
+export declare const DOOR_WORDS: readonly DoorWord[];
+export declare const isDoorWord: (s: unknown) => s is DoorWord;
+export declare const word: <W extends WordName>(name: W) => Word<W>;
+export declare const isWord: (x: unknown) => x is Word;
+export declare const wordOf: (x: Word) => WordName;
+export declare const answered: <T>(x: T) => x is Exclude<T, typeof silence | Word>;
+export declare const told: (x: unknown) => unknown;
+export declare const unreached: () => Unreached;
+export declare const isUnreached: (x: unknown) => x is Unreached;

package/dist/being/silence.js

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+// Silence is one distinguished value. Null is an answer. Silence is no answer.
+//
+// The ward's words are the other distinguished values: what her ward tells
+// her when no object came back and it knows why. Each is one frozen object
+// under one symbol key, so a being cannot make one by accident, none of them
+// crosses an edge as a value, and a being who compares against them needs
+// no fourth shape. `unreached` is one of them.
+import { WORD_KEY } from './types.js';
+export const silence = Symbol.for('quo.silence');
+export const isSilence = (x) => x === silence;
+// The words a door says to a key it has bound, and no other. They ride on
+// the wire as `{ quo: word }`, so a reply is checked against this list.
+export const DOOR_WORDS = ['removed', 'absent', 'unannounced', 'repeated', 'threw'];
+export const isDoorWord = (s) => typeof s === 'string' && DOOR_WORDS.includes(s);
+const WORDS = new Map();
+export const word = (name) => {
+    let w = WORDS.get(name);
+    if (!w)
+        WORDS.set(name, (w = Object.freeze({ [WORD_KEY]: name })));
+    return w;
+};
+export const isWord = (x) => x !== null && typeof x === 'object' && typeof x[WORD_KEY] === 'string';
+export const wordOf = (x) => x[WORD_KEY];
+// What came back is an answer and not one of the two things that are not
+// answers. A being who only wants the object writes one test instead of
+// three, and the three shapes stay three shapes: silence is no answer, a word
+// is her ward telling her why there is none.
+export const answered = (x) => !isSilence(x) && !isWord(x);
+// What she was told, with a word given its name and everything else left
+// exactly as it came. One value to compare against, so asking which word came
+// back is one test and not two joined by an and: `told(out) === 'late'` says
+// what `isWord(out) && wordOf(out) === 'late'` says, and says which answer
+// arrived instead when it is wrong, where the pair collapses to false and
+// names nothing. Silence stays the symbol it is, and an object stays itself.
+export const told = (x) => (isWord(x) ? wordOf(x) : x);
+// Unreached: no far door was reached. Nothing is known to have been
+// delivered, so asking again is safe. A being cannot produce it: a ward that
+// sees a word come out of a being reads it as her having thrown.
+export const unreached = () => word('unreached');
+export const isUnreached = (x) => isWord(x) && wordOf(x) === 'unreached';

package/dist/being/types.d.ts

@@ -0,0 +1,89 @@
+import type { silence } from './silence.ts';
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type JsonObject = {
+    [key: string]: Json;
+};
+export type Asker = {
+    id: string;
+} | {
+    id?: undefined;
+};
+export declare const OWNER = "OWNER";
+export declare const PUBLIC = "PUBLIC";
+export declare const RESERVED_IDS: readonly string[];
+export type Invitation = {
+    ward: string;
+    heir?: string;
+    secret?: string;
+};
+export declare const invitationArgs: (inv: Invitation) => JsonObject;
+export declare const isInvitation: (v: unknown) => v is Invitation;
+export type Schema = JsonObject;
+export type Ask = {
+    name: string;
+    description?: string;
+    input: Schema;
+    output?: Schema;
+};
+export type Blueprint = {
+    asks: Ask[];
+    notes: Json;
+};
+export declare const isBlueprint: (v: unknown) => v is Blueprint;
+export type StandingRecord = {
+    id: string;
+    digest: string | null;
+    blueprint: Blueprint | null;
+    seen: string | null;
+};
+export type OccupantRecord = {
+    id: string;
+    notes: JsonObject;
+};
+export type Cells = {
+    standings: Record<string, StandingRecord>;
+    occupants: Record<string, OccupantRecord>;
+    [hers: string]: Json;
+};
+export type Silence = typeof silence;
+export type DoorWord = 'removed' | 'absent' | 'unannounced' | 'repeated' | 'threw';
+export type WardWord = 'unreached' | 'late' | 'invitation' | 'dropped';
+export type WordName = DoorWord | WardWord;
+export declare const WORD_KEY: unique symbol;
+export type Word<W extends WordName = WordName> = {
+    readonly [K in typeof WORD_KEY]: W;
+};
+export type Unreached = Word<'unreached'>;
+export type Answer = Json | Silence | Word;
+export type Reply = Json | Silence;
+export type Wanted = {
+    time?: number;
+};
+export type Standing = {
+    readonly id: string;
+    ask(method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+};
+export type Standings = {
+    knock(invitation: Invitation, method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+    take(id: string, invitation: Invitation): Promise<string | null>;
+    remove(id: string): void;
+} & {
+    readonly [id: string]: Standing | undefined;
+};
+export type Occupants = {
+    invite(id: string, notes?: JsonObject): Promise<Invitation | null>;
+    remove(id: string): void;
+};
+export type Stance = {
+    readonly cells: Cells;
+    readonly occupants: Occupants;
+    readonly standings: Standings;
+    lend(name: string, id: string): Promise<string | null>;
+    boot(className: string, key: string, id?: string): Promise<string | null>;
+};
+export interface BeingLike {
+    answer(asker: Asker, method?: string, args?: JsonObject): Reply | Promise<Reply>;
+}
+export type BeingClass = new (stance: Stance) => BeingLike;