nervur 0.19.2 → 0.20.0

package/package.json

@@ -1,54 +1,40 @@
 {
   "name": "nervur",
-  "version": "0.19.2",
-  "description": "Nervur's kit of Quo: an object asks another object and gets an answer, without knowing where it is. Being, Ward, Harbor.",
+  "version": "0.20.0",
+  "description": "Nervur's kit of Quo: an object asks another object and gets an answer, without knowing where it is.",
   "keywords": [
     "quo",
     "protocol",
     "capability",
-    "object-capability",
-    "rpc",
-    "ed25519",
-    "x25519"
+    "object-capability"
   ],
   "author": "Razvan Gherghina",
   "license": "Apache-2.0",
   "homepage": "https://nervur.org",
   "type": "module",
-  "engines": {
-    "node": ">=22.18"
-  },
   "exports": {
     ".": {
-      "types": "./dist/being/index.d.ts",
-      "default": "./dist/being/index.js"
-    },
-    "./ward": {
-      "types": "./dist/ward/index.d.ts",
-      "default": "./dist/ward/index.js"
-    },
-    "./harbor": {
-      "types": "./dist/harbor/index.d.ts",
-      "default": "./dist/harbor/index.js"
-    },
-    "./conformance": {
-      "types": "./dist/conformance/index.d.ts",
-      "default": "./dist/conformance/index.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
-    "./vector": {
-      "types": "./dist/vector/index.d.ts",
-      "default": "./dist/vector/index.js"
-    },
-    "./package.json": "./package.json"
+    "./folder": {
+      "types": "./dist/folder/index.d.ts",
+      "default": "./dist/folder/index.js"
+    }
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
-    "check": "node ../../test.mjs \"test/*.test.ts\"",
-    "experimental": "node ../../test.mjs \"experimental/*.test.ts\"",
-    "deep": "node --test --test-timeout=300000 \"test/terrain/*.test.ts\"",
-    "cover": "node --test --test-timeout=60000 --experimental-test-coverage --test-coverage-exclude=\"**/dist/**\" --test-coverage-exclude=\"**/test/**\" --test-coverage-lines=99 --test-coverage-branches=93 --test-coverage-functions=95 \"test/*.test.ts\"",
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json && npm run build && node ../../test.mjs \"test/unit/*.test.ts\" \"test/e2e/*.test.ts\"",
+    "deep": "node ../../test.mjs \"test/terrain/*.test.ts\"",
+    "cover": "node --test --test-timeout=60000 --experimental-test-coverage --test-coverage-exclude=\"**/dist/**\" --test-coverage-exclude=\"**/test/**\" --test-coverage-exclude=\"**/src/stand/**\" --test-coverage-exclude=\"../../quo/**\" --test-coverage-lines=99 --test-coverage-branches=93 --test-coverage-functions=95 \"test/unit/*.test.ts\" \"test/e2e/*.test.ts\"",
     "prepublishOnly": "test \"$NERVUR_GATED\" = 1 || { echo 'a publish is /release, from the root, on the human'\"'\"'s word' >&2; exit 1; }"
   },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "@noble/post-quantum": "0.7.1"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/being/being.ts

@@ -1,28 +1,23 @@
 // SPDX-License-Identifier: Apache-2.0
-// The base class most beings extend. It writes `answer` for you: the empty
-// ask becomes a blueprint from the asks you declare, filtered per asker; a
-// named ask becomes a method call; anything not declared, or hidden from
-// this asker, is an error object. Underneath it is still one function, and
-// a class that writes that function by hand is a being just the same.
-import type { Ask, Asker, Blueprint, Cells, Invitation, JsonObject, Wanted, OccupantRecord, Occupants, Reply, Schema, Stance, Standings, Answer } from './types.ts';
+// The base class most beings extend. It writes `answer`: the empty ask is
+// her blueprint for this asker, a named ask calls her method of that name,
+// and an ask she did not declare, or hides from this asker, is an error
+// object. A class that writes `answer` by hand is a being just the same.
+// What she acts through is `this.stance`.
+import type { Ask, Asker, Blueprint, JsonObject, Reply, Schema, Stance } from './types.ts';
 
-// One declared ask. `for` decides whether this asker sees it, and so whether
-// this asker may call it: what she shows is what she can be asked.
+// One declared ask. `for` decides whether this asker sees it, and so
+// whether this asker may call it.
 export type AskSpec = {
-  description?: string;
-  input?: Schema;
-  output?: Schema;
-  for?: (occupant: OccupantRecord | undefined, asker: Asker) => boolean;
+  readonly description?: string;
+  readonly input?: Schema;
+  readonly for?: (asker: Asker, notes: JsonObject | undefined) => boolean;
 };
 
-// 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']);
+// Names a subclass may not declare as an ask, because they are the base's.
+const RESERVED = new Set(['answer', 'describe', 'stance', 'cells', 'notes', '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.
+// Whether she wrote a method of that name, below Object's prototype.
 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';
@@ -30,18 +25,13 @@ const wrote = (self: object, name: string): boolean => {
   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: {} }`.
+type Method = (args: JsonObject, asker: Asker) => Reply | Promise<Reply>;
+
+// A subclass's statics replace its parent's and never merge: her blueprint
+// is what the class in front of you declares, in its order.
 export class Being {
-  // Her cells' defaults. Merged in at birth, only where a key is missing, so
-  // a restart keeps what she wrote.
+  // Her cells' defaults, written at birth only where a key is missing.
   static cells: JsonObject = {};
-  // 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: Record<string, AskSpec> = {};
 
   readonly stance: Stance;
@@ -51,73 +41,36 @@ 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 (!wrote(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`);
     }
-    // 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(): Cells {
+  get cells(): JsonObject {
     return this.stance.cells;
   }
-  get standings(): Standings {
-    return this.stance.standings;
-  }
-  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);
-  }
-  knock(invitation: Invitation, method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer> {
-    return this.stance.standings.knock(invitation, method, args, wanted);
-  }
-  take(id: string, invitation: Invitation): Promise<string | null> {
-    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: string, key: string, id?: string): Promise<string | null> {
-    return this.stance.boot(className, key, id);
-  }
-  // The occupant record for whoever is at the door. Undefined at a public being.
-  occupant(asker: Asker): OccupantRecord | undefined {
-    return asker.id !== undefined && Object.hasOwn(this.cells.occupants, asker.id) ? this.cells.occupants[asker.id] : undefined;
+
+  // The notes she invited this asker under.
+  notes(asker: Asker): JsonObject | undefined {
+    return asker.id === undefined ? undefined : this.stance.occupants.notes(asker.id);
   }
 
-  // Her blueprint for this asker. Override to shape it by hand.
   describe(asker: Asker): Blueprint {
     const C = this.constructor as typeof Being;
-    const rec = this.occupant(asker);
+    const notes = this.notes(asker);
     const asks: Ask[] = [];
     for (const [name, spec] of Object.entries(C.asks)) {
-      if (spec.for && !spec.for(rec, asker)) continue;
-      const ask: 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);
+      if (spec.for && !spec.for(asker, notes)) continue;
+      asks.push({ name, ...(spec.description === undefined ? {} : { description: spec.description }), input: spec.input ?? { type: 'object' } });
     }
     return { asks, notes: {} };
   }
 
-  // The one function. Override to wrap it; call super to keep the dispatch.
-  async answer(asker: Asker, method?: string, args: JsonObject = {}): Promise<Reply> {
+  async answer(asker: Asker, method: string | undefined, args: JsonObject): Promise<Reply> {
     if (method === undefined) return this.describe(asker);
     const C = this.constructor as typeof Being;
-    // 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 as unknown as Record<string, (args: JsonObject, asker: Asker) => Reply | Promise<Reply>>)[method];
-    return fn.call(this, args ?? {}, asker);
+    if (!spec || (spec.for && !spec.for(asker, this.notes(asker)))) return { error: 'unknown ask' };
+    return ((this as unknown as Record<string, Method>)[method] as Method).call(this, args, asker);
   }
 }

package/src/being/digest.ts

@@ -1,46 +1,18 @@
 // SPDX-License-Identifier: Apache-2.0
-// The digest: SHA-256, as hex, over the JCS (RFC 8785) canonical form of a
-// blueprint. Same bytes from every language. WebCrypto only, so it runs
-// wherever the language runs.
-import type { Json } from './types.ts';
+// A being's `seen`: SHA-256, lowercase hex, over the canonical form of her
+// blueprint for one asker. Keys sorted by UTF-16 code units, numbers as
+// ECMAScript writes them, no whitespace.
+import { hex, sha256, utf8, type Json } from '../crypto/index.ts';
 
-// 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: unknown): boolean => 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: Json): string => {
-  if (Array.isArray(v)) return `[${Array.from(v, (slot) => (absent(slot) ? 'null' : canonical(slot))).join(',')}]`;
+  if (Array.isArray(v)) return `[${v.map(canonical).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])}`)
+      .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: ArrayBuffer): string =>
-  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 = (): SubtleCrypto => {
-  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: Json): Promise<string> => hex(await subtle().digest('SHA-256', new TextEncoder().encode(canonical(blueprint))));
+export const digest = async (blueprint: Json): Promise<string> => hex(await sha256(utf8(canonical(blueprint))));

package/src/being/faculty.ts

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+// A faculty: a being of the box ward that fulfils a contract. A contract is
+// a class between `Faculty` and the class that stands, usually abstract:
+//
+//   abstract class Timer extends Faculty { ... }     the contract
+//   class IntervalTimer extends Timer { ... }        one class that fulfils it
+//
+// A being lends by the contract and never learns the class. Two asks are the
+// faculty's own and answered to the ward-being that opened her alone:
+// `offer`, an invitation on herself for a ward the dock vouches for, and
+// `retract`, an offer that was not taken.
+import { Being } from './being.ts';
+import { WARD, type Asker, type Blueprint, type JsonObject, type Reply } from './types.ts';
+
+export class Faculty extends Being {
+  // The contracts a class fulfils: itself and every class between it and
+  // `Faculty`, by name.
+  static contracts(C: abstract new (...args: never[]) => unknown): string[] {
+    const names: string[] = [];
+    for (let c: unknown = C; typeof c === 'function' && c !== Faculty; c = Object.getPrototypeOf(c)) names.push((c as { name: string }).name);
+    return names;
+  }
+
+  static fulfils(C: unknown): C is typeof Faculty {
+    return typeof C === 'function' && C.prototype instanceof Faculty;
+  }
+
+  #open(): Record<string, string> {
+    if (this.cells.offers === undefined) this.cells.offers = {};
+    return this.cells.offers as Record<string, string>;
+  }
+
+  async #offer(): Promise<JsonObject> {
+    const n = ((this.cells.offered as number | undefined) ?? 0) + 1;
+    this.cells.offered = n;
+    const id = `lent:${n}`;
+    const invitation = await this.stance.occupants.invite(id);
+    if (invitation === null) return { error: 'not invited' };
+    this.#open()[invitation.heir] = id;
+    return { invitation };
+  }
+
+  #retract(args: JsonObject): JsonObject {
+    const open = this.#open();
+    const id = typeof args.heir === 'string' && Object.hasOwn(open, args.heir) ? open[args.heir] : undefined;
+    if (id === undefined) return { retracted: null };
+    this.stance.occupants.remove(id);
+    delete open[args.heir as string];
+    return { retracted: id };
+  }
+
+  override describe(asker: Asker): Blueprint {
+    const blueprint = super.describe(asker);
+    if (asker.id !== WARD) return blueprint;
+    return { ...blueprint, asks: [...blueprint.asks, { name: 'offer', input: { type: 'object' } }, { name: 'retract', input: { type: 'object', required: ['heir'] } }] };
+  }
+
+  // An offer is closed by the first word from the occupant it was made for.
+  override answer(asker: Asker, method: string | undefined, args: JsonObject): Promise<Reply> {
+    if (asker.id === WARD && method === 'offer') return this.#offer();
+    if (asker.id === WARD && method === 'retract') return Promise.resolve(this.#retract(args));
+    const open = this.#open();
+    for (const [heir, id] of Object.entries(open)) if (id === asker.id) delete open[heir];
+    return super.answer(asker, method, args);
+  }
+}

package/src/being/index.ts

@@ -1,8 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
-// nervur — the Being side. What a being author imports, if anything.
+// What a being author imports.
 export { Being, type AskSpec } from './being.ts';
-export { Lent, BOX, LENT_ASKS } from './lent.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';
+export { canonical, digest } from './digest.ts';
+export { Faculty } from './faculty.ts';
+export { OWNER, WARD, type Answer, type Ask, type Asker, type BeingClass, type BeingLike, type Blueprint, type Invitation, type Json, type JsonObject, type Occupants, type Reply, type Schema, type Stance, type Standing, type Standings, type Wanted } from './types.ts';
+export { isSilence, isWord, silence, told, word, type Silence, type Word, type WordName } from './words.ts';

package/src/being/types.ts

@@ -1,170 +1,72 @@
 // SPDX-License-Identifier: Apache-2.0
-// The Being side of Quo, as types. Everything a being author can hold.
-// Nothing here knows a runtime, a key, or a wire.
-import type { silence } from './silence.ts';
+// Everything a being author holds, as types.
+import type { Json } from '../crypto/index.ts';
+import type { Invitation } from '../quo/index.ts';
+import type { Silence, Word } from './words.ts';
 
-// I-JSON. Everything that crosses an edge.
-export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+export type { Invitation, Json };
 export type JsonObject = { [key: string]: Json };
 
-// The asker: her own id for the being at the door. {} at a public being.
-export type Asker = { id: string } | { id?: undefined };
-
-// The ids the ward speaks under, and no being may mint. An asker id is hers:
-// she chooses the strings, and the ward has no business in her namespace. But
-// the ward must sometimes stand at her door itself — its describe asks every
-// being under OWNER — and an id it shares with one of her occupants is two
-// different parties wearing one name. She could not tell them apart, and the
-// ward would shape its describe through an occupant's gate.
-//
-// So the ward's words are shouted, and refused at the mint. A word can only
-// be reserved before anyone has used it: a partition already holding an
-// occupant of that name could never have it taken back. PUBLIC guards nothing
-// today — a public asker is {} and carries no id at all — and that is exactly
-// why it is claimed now, while claiming it is free.
+// Who is at the door: the id she filed the occupant under, `{}` for nobody,
+// and `{ id: OWNER }` for whoever holds the ward's unsealed ask.
+export type Asker = { readonly id: string } | { readonly id?: undefined };
 export const OWNER = 'OWNER';
-export const PUBLIC = 'PUBLIC';
-export const RESERVED_IDS: readonly string[] = [OWNER, PUBLIC];
 
-// An invitation is a value. Opaque to her: the far ward's pk, a heir pk,
-// and the heir's secret. Without a heir it addresses a ward's public being.
-export type Invitation = { ward: string; heir?: string; secret?: string };
+// The ward-being's key in her ward, and so the id every being she makes
+// knows her by.
+export const WARD = 'ward';
 
-// An invitation as one object of values, which is what it already is. A being
-// who hands one on sends it as args, and args are values; this is the one
-// place that is spelled, so nobody spells it with a cast. Absent stays absent:
-// an invitation to a public being carries no heir and no secret, and a key
-// present and undefined is not the same object once JSON has been through it.
-export const invitationArgs = (inv: Invitation): JsonObject => ({
-  ward: inv.ward,
-  ...(inv.heir !== undefined ? { heir: inv.heir } : {}),
-  ...(inv.secret !== undefined ? { secret: inv.secret } : {}),
-});
+// What comes back from an ask, and what a being answers.
+export type Answer = Json | Silence | Word;
+export type Reply = Json | Silence | undefined;
 
-// Whether a value that arrived is an invitation. The shape is the spec's, so
-// the reading of it is too, and it is one reading: a form that
-// asks a guest for one, a lent being handed one to wake her maker by, and a
-// shell that finds one in a link all ask the same question, and a kinder
-// answer in one of them is a value that fails at a door instead of at the
-// edge it came in by. A ward pk is a hundred and twenty-eight lowercase hex,
-// and a heir comes with its secret or neither comes: an invitation to a
-// public being carries no heir, and a heir with no secret opens nothing.
-export const isInvitation = (v: unknown): v is Invitation => {
-  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
-  const o = v as Record<string, unknown>;
-  if (typeof o.ward !== 'string' || !/^[0-9a-f]{128}$/.test(o.ward)) return false;
-  const heir = typeof o.heir === 'string',
-    secret = typeof o.secret === 'string';
-  return (heir && secret) || (!heir && !secret && !('heir' in o) && !('secret' in o));
-};
+export type Wanted = { readonly time?: number };
 
-// A blueprint is an MCP tool list plus notes.
+// A blueprint: the asks a being can be asked, as an MCP tool list, and notes.
 export type Schema = JsonObject;
-export type Ask = { name: string; description?: string; input: Schema; output?: Schema };
+export type Ask = { name: string; description?: string; input: Schema };
 export type Blueprint = { asks: Ask[]; notes: Json };
 
-// Whether what came back from an empty ask is a blueprint. Every describe on
-// the far side of a door is somebody else's code, so nothing may be written
-// into a standing's record as a blueprint without being read as one first: a
-// side walks `asks` by name, and a list of anything else, or no list at all,
-// is a side that breaks on a far ward's answer. The asks are checked to the
-// depth a side reads them, a name and an input each, and no further: what a
-// far being puts beside those is hers.
-export const isBlueprint = (v: unknown): v is Blueprint => {
-  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
-  const { asks, notes } = v as { asks?: unknown; notes?: unknown };
-  if (!Array.isArray(asks) || notes === undefined) return false;
-  return asks.every((a) => a !== null && typeof a === 'object' && !Array.isArray(a) && typeof (a as Ask).name === 'string' && (a as Ask).input !== null && typeof (a as Ask).input === 'object' && !Array.isArray((a as Ask).input));
-};
-
-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;
-
-// The ward's words: what her ward says when no object came back and it knows
-// why. A door says the first five to a key it has bound, and rides them on
-// the wire as `{ quo: word }`; her own ward says the last four to her and
-// they never leave the ward. Each is one frozen object under one symbol key,
-// so no being makes one by accident and none crosses an edge as a value. A
-// being who reaches for the symbol on purpose makes an object her ward reads
-// as her having thrown, which is what a being who returns nonsense gets: the
-// key is a guard against collision, never against her.
-export type DoorWord = 'removed' | 'absent' | 'unannounced' | 'repeated' | 'threw';
-export type WardWord = 'unreached' | 'late' | 'invitation' | 'dropped';
-export type WordName = DoorWord | WardWord;
-export const WORD_KEY: unique symbol = Symbol.for('quo.word');
-export type Word<W extends WordName = WordName> = { readonly [K in typeof WORD_KEY]: W };
-export type Unreached = Word<'unreached'>;
-
-// What comes back from an ask or a knock.
-export type Answer = Json | Silence | Word;
-// What a being answers.
-export type Reply = Json | Silence;
-
-// What a being may ask for when she wants to say so herself: the time this
-// one ask may spend. Optional, and so is saying anything at all: an ask that
-// says nothing gets her ward's default, which is the ordinary way to ask.
-export type Wanted = { time?: number };
-
-export type Standing = {
+export interface 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>;
+// Her side of the relations she holds.
+export interface Standings {
+  // Knocks with the empty ask and holds the relation under `id`: the id, or
+  // null where the id is taken or reserved, or no object came back.
   take(id: string, invitation: Invitation): Promise<string | null>;
-  remove(id: string): void;
-} & { readonly [id: string]: Standing | undefined };
+  get(id: string): Standing | undefined;
+  ids(): string[];
+  remove(id: string): boolean;
+}
 
-export type Occupants = {
-  // awaitable: a key is minted. The notes are the terms it is minted under,
-  // written on the occupant for her gate to read, and hers alone after that.
+// The door's side: the ids she invited.
+export interface Occupants {
   invite(id: string, notes?: JsonObject): Promise<Invitation | null>;
+  notes(id: string): JsonObject | undefined;
+  ids(): string[];
+  remove(id: string): boolean;
+}
 
-  remove(id: string): void;
-};
-
-// The stance. What every being, in every language, is handed at birth.
-export type Stance = {
-  readonly cells: Cells;
+// What every being is handed at birth.
+export interface Stance {
+  readonly key: string;
+  readonly cells: JsonObject;
   readonly occupants: Occupants;
   readonly standings: Standings;
-  // A standing at one of the things this device can do, by the harbor's name
-  // for it, under an id of hers. The id back, or null: this box lends no such
-  // name, the id already names a record or is a reserved word, or the
-  // relation was refused.
-  //
-  // Her ward asks the ground, then knocks and takes in her name, as it does
-  // for a being she boots. So the invitation never reaches her, because it is
-  // the device's capability and not her own relation to give away; what she
-  // holds afterwards is an ordinary standing that counts, rotates, can be
-  // removed and hears `removed`.
-  //
-  // The ground is the booting harbor's, so this reaches the box she is
-  // running on and no other. A standing she wakes up holding names a being on
-  // the box she was on when it was made, and a migration is a restart she
-  // cannot tell from any other, so a being who wants the box she is on asks
-  // again at every birth.
-  lend(name: string, id: string): Promise<string | null>;
-  // A new being of her ward, by class name, under a key she chooses. The key
-  // back, or null: the key is taken, the harbor holds no such class, or the
-  // class threw at birth. A being may make; only the owner reaches into
-  // another. Naming an id asks for a way back too: the being made holds an
-  // occupant for her maker under the maker's own key, and the maker holds
-  // the standing under that id. A relation that could not be made is a boot
-  // that made nobody, and the being made goes with it.
+  // A new being of her ward, by class name, under a key she chooses. With an
+  // id, the new being invites her under her key, and she takes it under id.
   boot(className: string, key: string, id?: string): Promise<string | null>;
-};
+  // A standing under `id` at the faculty this harbor opened for a contract:
+  // the id, or null where none is open or the relation was refused.
+  lend(contract: { readonly name: string }, id: string): Promise<string | null>;
+}
 
-// The raw shape of a being. Anything with these two is a being.
+// Anything with `answer` is a being.
 export interface BeingLike {
-  answer(asker: Asker, method?: string, args?: JsonObject): Reply | Promise<Reply>;
+  answer(asker: Asker, method: string | undefined, args: JsonObject): Reply | Promise<Reply>;
+  describe?(asker: Asker): Blueprint;
 }
-export type BeingClass = new (stance: Stance) => BeingLike;
+export type BeingClass = (new (stance: Stance) => BeingLike) & { readonly name: string };

package/src/being/words.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+// What a being is told when no object came back. Silence is one symbol.
+// A word is one frozen object per name, so a being never makes one by
+// accident, and two copies of the package in one bundle still agree.
+//
+//   removed, unannounced, repeated   a far door's words, as Quo says them
+//   unreached                        nothing came back: asking again is safe
+//   late                             the allowance ran out
+//   dropped                          the standing was removed while asking
+//   invitation                       what was handed is no invitation
+import type { Word as DoorWord } from '../quo/index.ts';
+
+export const silence: unique symbol = Symbol.for('nervur.silence');
+export type Silence = typeof silence;
+export const isSilence = (x: unknown): x is Silence => x === silence;
+
+export type WordName = DoorWord | 'unreached' | 'late' | 'dropped' | 'invitation';
+const KEY: unique symbol = Symbol.for('nervur.word');
+export type Word<W extends WordName = WordName> = { readonly [KEY]: W };
+
+const made = new Map<WordName, Word>();
+export const word = <W extends WordName>(name: W): Word<W> => {
+  let w = made.get(name);
+  if (!w) made.set(name, (w = Object.freeze({ [KEY]: name })));
+  return w as Word<W>;
+};
+export const isWord = (x: unknown): x is Word => typeof x === 'object' && x !== null && typeof (x as Record<symbol, unknown>)[KEY] === 'string';
+
+// A word by its name, and anything else as it is, so one comparison says
+// which answer came back.
+export const told = (x: unknown): unknown => (isWord(x) ? x[KEY] : x);