@quo-systems/quo 0.1.0 → 0.2.0

package/dist/ward/stance.js

@@ -0,0 +1,259 @@
+// SPDX-License-Identifier: Apache-2.0
+// The one stance builder. Used for every being the ward boots. Nothing
+// outer is in what she holds: ids in, values out, keys in the bind table.
+import { silence, isSilence, isUnreached, isWord, word } from '../being/silence.js';
+import { digest } from '../being/digest.js';
+import { RESERVED_IDS } from '../being/types.js';
+import { at, put, drop } from './partition.js';
+import { allow, within, LATE } from './allowance.js';
+import { isWardPk } from './seal.js';
+// The three calls on `standings` share the object with the ids she takes, so
+// a standing named after one of them would be unreachable: `standings.knock`
+// is the call, whatever record sits under that name. One namespace means one
+// list: these are refused at invite and at take, beside the ward's own words.
+const CALLS = ['knock', 'take', 'remove'];
+const reserved = (id) => RESERVED_IDS.includes(id) || CALLS.includes(id);
+export function buildStance(inside, key, cells, bind) {
+    // The name of one relation, as her side files it. A relation is a ward and
+    // a heir, never a heir alone: the heir pk is outer, it rides in the clear on
+    // every lid, and anyone who reads one can quote it back inside an invitation
+    // naming a ward of their own. Filed under the heir alone, that invitation
+    // would share her knock record with the relation the heir really belongs to:
+    // it would sign with that relation's key, and an answer to it would set the
+    // answered flag the other relation is taken on. Both halves, always.
+    const nameOf = (inv) => (inv.heir === undefined ? `public:${inv.ward}` : `${inv.ward}:${inv.heir}`);
+    const valid = (inv) => {
+        const i = inv;
+        if (!i || typeof i !== 'object' || !isWardPk(i.ward))
+            return false;
+        if (i.heir === undefined)
+            return i.secret === undefined;
+        return typeof i.heir === 'string' && typeof i.secret === 'string' && /^[0-9a-f]{64}$/.test(i.heir) && /^[0-9a-f]{64}$/.test(i.secret);
+    };
+    // One relation, one ask at a time. The rotation is a conversation: a send
+    // reads the key that speaks now, announces the next, and moves to it once
+    // the far door has answered. Two sends interleaving on one relation read
+    // each other's half-written keys and the two sides diverge, which no later
+    // ask can repair. So each relation has a lane, and a send waits for the one
+    // before it. Beings may still ask concurrently: the lanes are per relation,
+    // and a slow relation never holds up another.
+    const lanes = new Map();
+    const lane = (name, run) => {
+        const mine = (lanes.get(name) ?? Promise.resolve()).then(run, run);
+        const quiet = mine.then(() => { }, () => { });
+        lanes.set(name, quiet);
+        void quiet.then(() => {
+            if (lanes.get(name) === quiet)
+                lanes.delete(name); // the lane is idle. nothing to remember.
+        });
+        return mine;
+    };
+    // Every ask a being makes, bounded. The bound is outside the lane on
+    // purpose: an ask that waits its turn behind a relation that comes back
+    // round never reaches a send, and a bound that only watched the wire would
+    // never see it hang. A bound that ran out is silence, never unreached:
+    // unreached promises nothing was delivered and is safe to ask again, and a
+    // wait that gave up knows no such thing.
+    //
+    // The bell rings before the work is reached, too: an ask that was still
+    // waiting its turn when the wait ran out is never sent. Sent then, it would
+    // be a fresh ask nobody is waiting on, the far being would do the work, and
+    // what came back would be read into her cells behind a silence she was
+    // already handed. So the work is given the bell, and reads it at the lane.
+    const bounded = async (wanted, work) => {
+        let late = false;
+        const out = await within(allow(wanted).time, work(() => !late), () => {
+            late = true;
+        });
+        return out === LATE ? word('late') : out;
+    };
+    const send = async (keys, method, args, wanted, rec) => {
+        const r = await inside.send(bind, keys, true, method, args, wanted);
+        if (isSilence(r) || isWord(r))
+            return r;
+        if ('silence' in r)
+            return silence;
+        if ('quo' in r)
+            return word(r.quo); // the far door's word for her, sealed to her lid
+        if (rec && method !== undefined && r.seen !== null)
+            rec.seen = r.seen; // the digest rode along
+        return r.object;
+    };
+    const knocking = async (inv, method, args, wanted) => {
+        const name = nameOf(inv);
+        // her own key for this relation, minted once: rotation two. reused if she knocks again.
+        const k = (bind.knocks[name] ??= { current: (await inside.mintKey(bind)).seed, next: null, spoke: false, sent: false, seq: 0 });
+        // the first knock on a heir speaks as the heir, the key the inviter handed out, and announces her own.
+        // once bytes have come back, the heir is spent whatever they said, and her own key speaks.
+        // She sent once as the heir and nothing came back. Either the door heard,
+        // spent the heir and rotated to the key she announced, or nothing arrived
+        // and the heir still stands. Only the far door knows, and it will not say.
+        //
+        // So she asks, and the asking tells her. Under her own key: if the door
+        // heard, that key is the one it admits, and she is answered. If it did
+        // not, the key means nothing there, the ask is refused, and a refusal at
+        // that door writes nothing — the heir is untouched and still speaks. Then
+        // she knocks as the heir, as she would have. One extra round trip in the
+        // one case where a reply was lost, and the relation is not stranded.
+        //
+        // No stranger gains anything by it: whoever holds the invitation could
+        // always knock as the heir, and her own key is admitted only where the
+        // door already bound it to her.
+        if (inv.heir !== undefined && !k.spoke && k.sent) {
+            const own = { ward: inv.ward, heir: inv.heir, current: k.current, next: k.next, seq: k.seq };
+            const r = await inside.send(bind, own, true, method, args, wanted);
+            k.seq = own.seq;
+            k.current = own.current;
+            k.next = own.next;
+            if (isUnreached(r))
+                return r; // still nothing. she knows no more than before.
+            if (!isSilence(r) && !isWord(r) && 'object' in r) {
+                k.spoke = true; // it was heard the first time, and this is the answer
+                bind.answered[name] = true;
+                return r.object;
+            }
+            // Refused. The door never heard her, so the heir is still hers to spend.
+        }
+        const first = inv.heir !== undefined && !k.spoke;
+        const keys = first ? { ward: inv.ward, heir: inv.heir, current: inv.secret, next: k.current, seq: k.seq } : { ward: inv.ward, heir: inv.heir ?? null, current: k.current, next: k.next, seq: k.seq };
+        const r = await inside.send(bind, keys, true, method, args, wanted);
+        k.sent = true; // bytes went out. whether they arrived is the far door's to know.
+        // The number she spoke under, and the key she announced, kept whoever
+        // answered and kept when nobody did. A reply lost on the way back is a
+        // door that has already honoured the number: she must not offer it twice,
+        // or a road that drops one reply silences the relation for good.
+        k.seq = keys.seq;
+        if (!first) {
+            k.current = keys.current;
+            k.next = keys.next;
+        }
+        if (isUnreached(r))
+            return r; // nothing came back. she does not know whether it was heard.
+        // The heir is spent once the door honoured it, whatever she then said: an
+        // object, silence, or that she threw. A refusal wrote nothing, and says
+        // so by its word, so the heir still speaks and the next knock is as it.
+        k.spoke = !(!isSilence(r) && !isWord(r) && 'quo' in r && r.quo !== 'threw');
+        if (isSilence(r) || isWord(r))
+            return r;
+        if ('silence' in r)
+            return silence;
+        if ('quo' in r)
+            return word(r.quo);
+        bind.answered[name] = true;
+        return r.object;
+    };
+    // The id she took this relation under, if she took it. One relation is one
+    // ward and one heir whichever door it is reached by, so the standing and the
+    // invitation answer to the same name.
+    const keyName = (k) => (k.heir === null ? `public:${k.ward}` : `${k.ward}:${k.heir}`);
+    const takenAs = (name) => Object.keys(bind.standings).find((id) => keyName(bind.standings[id]) === name);
+    const calls = {
+        knock: async (inv, method, args = {}, wanted) => {
+            if (!valid(inv))
+                return word('invitation'); // S1. nothing is sent
+            // She may knock again, and after take that knock is an ask: the relation
+            // has one home, so it answers on the standing's lane, under the
+            // standing's keys and its count. A second lane here would speak for the
+            // same relation, and the two would refuse each other.
+            const id = takenAs(nameOf(inv));
+            if (id !== undefined)
+                return bounded(wanted, (live) => lane(`ask:${id}`, () => (live() ? asking(id, bind.standings[id], cells.standings[id], method, args, wanted) : Promise.resolve(word('late')))));
+            return bounded(wanted, (live) => lane(`knock:${nameOf(inv)}`, () => (live() ? knocking(inv, method, args, wanted) : Promise.resolve(word('late')))));
+        },
+        // Take consumes. Until now the relation lived in the knock record, under
+        // the ward and the heir; from now it lives in the standing, under her id.
+        // It never lives in both: two records seeded from one relation are two
+        // lanes speaking for one line of keys and one count, and whichever spoke
+        // last holds it while the other is refused. She would read that refusal as
+        // the far being falling quiet, which is a thing a sovereign being may do,
+        // so the loss would look exactly like an answer she is owed nothing of.
+        // One relation, one home, and the invitation is spent: knocking it again
+        // is another consumed it, and taking it again births nothing.
+        //
+        // So it is spoken on the relation's lane, like every other word spoken
+        // for it. A take reads the count and the keys a knock writes, and copies
+        // them into the standing. Off the lane it reads them between a knock's
+        // send and its answer: the standing is born holding a number the far door
+        // is about to honour and a key it is about to rotate past, and her first
+        // ask on it is refused. The relation she took correctly would be dead
+        // because a second knock on the same invitation was careless.
+        take: async (id, inv) => {
+            if (!valid(inv))
+                return null;
+            const name = nameOf(inv);
+            return lane(`knock:${name}`, () => {
+                if (!bind.answered[name])
+                    return Promise.resolve(null);
+                // Standings and occupants are one namespace — invite and take each
+                // refuse a name the other holds — so a word reserved in one is
+                // reserved in both.
+                if (reserved(id) || at(cells.standings, id) || at(cells.occupants, id))
+                    return Promise.resolve(null);
+                const k = bind.knocks[name];
+                put(bind.standings, id, { ward: inv.ward, heir: inv.heir ?? null, current: k.current, next: k.next, seq: k.seq }); // the count carries over: the standing goes on where the knock left off
+                put(cells.standings, id, { id, digest: null, blueprint: null, seen: null });
+                delete bind.knocks[name];
+                delete bind.answered[name];
+                return Promise.resolve(id);
+            });
+        },
+        remove: (id) => {
+            drop(cells.standings, id);
+            drop(bind.standings, id);
+        },
+    };
+    const standingAt = (id) => ({
+        id,
+        // The keys are read now, not when the lane reaches this ask: an ask
+        // issued while the standing stood is answered even if she drops it in
+        // the next line. Waiting for the lane is not a reason to lose it.
+        ask: (method, args = {}, wanted) => {
+            const keys = at(bind.standings, id);
+            if (!keys)
+                return Promise.resolve(word('dropped')); // S2. she dropped it between one line and the next
+            const rec = at(cells.standings, id);
+            return bounded(wanted, (live) => lane(`ask:${id}`, () => (live() ? asking(id, keys, rec, method, args, wanted) : Promise.resolve(word('late')))));
+        },
+    });
+    const asking = async (id, keys, rec, method, args, wanted) => {
+        const out = await send(keys, method, args, wanted, rec);
+        if (method === undefined && !isSilence(out) && !isWord(out)) {
+            const here = at(cells.standings, id);
+            if (here) {
+                here.blueprint = out;
+                here.digest = here.seen = await digest(out);
+            }
+        }
+        return out;
+    };
+    const standings = new Proxy(calls, {
+        // Own keys only: `in` would also find every name on Object's prototype,
+        // and a standing she took as `constructor` or `toString` would answer with
+        // Object's, not hers.
+        get: (t, id) => (typeof id === 'string' && Object.hasOwn(t, id) ? t[id] : typeof id === 'string' && at(cells.standings, id) ? standingAt(id) : undefined),
+    });
+    return {
+        cells,
+        occupants: {
+            // rotation one: the ward mints the occupant's first key and gives the secret away.
+            // it keeps the pk beside the id and nothing else. the invitation IS the key.
+            invite: async (id) => {
+                if (reserved(id) || at(cells.occupants, id) || at(cells.standings, id))
+                    return null;
+                put(cells.occupants, id, { id, notes: {} });
+                const k = await inside.mintKey(bind);
+                inside.openHeir(k.pk, key, id);
+                put(bind.occupants, id, k.pk);
+                return { ward: inside.pk, heir: k.pk, secret: k.seed };
+            },
+            remove: (id) => {
+                drop(cells.occupants, id);
+                const heir = at(bind.occupants, id);
+                drop(bind.occupants, id);
+                if (heir)
+                    inside.closeHeir(heir); // the heir dies with the id
+            },
+        },
+        standings,
+    };
+}

package/dist/ward/ward.d.ts

@@ -0,0 +1,2 @@
+import type { Ground, WardPointers } from './ground.ts';
+export declare function Ward(ground: Ground): Promise<WardPointers>;

package/dist/ward/ward.js

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: Apache-2.0
+// A ward that is its own ward. Booted by a harbor with one object, the
+// ground, and hands back two pointers: the door and the ask. Boots itself as
+// the first being in its own map, and every being it later instantiates gets
+// a stance built by the same code. Mints every key, seals every ask that
+// leaves, opens every one that arrives.
+import { silence, isSilence, unreached, isWord, word } from '../being/silence.js';
+import { OWNER } from '../being/types.js';
+import { at, open, put, emptyBind, emptyCells } from './partition.js';
+import { Heirs } from './heirs.js';
+import { makeDoor } from './door.js';
+import { buildStance } from './stance.js';
+import { ownerAnswer } from './owner.js';
+import { allow, within, LATE } from './allowance.js';
+import { beingKey, openReply, sealAsk, wardKey, wardPadlock, wardSignPk } from './seal.js';
+import { unhex } from './arithmetic.js';
+import { guardCells, cellFault } from './cells.js';
+// How many minted pks she keeps behind her. Enough to name the keys in play.
+const MINTED = 8;
+// The ward. One call in, two pointers out. Async because keys are derived.
+export async function Ward(ground) {
+    const w = await Self.boot(ground);
+    return { door: w.door, ask: w.ask };
+}
+class Self {
+    key;
+    pk;
+    g;
+    p;
+    heirs;
+    doors = new Map();
+    door;
+    ask;
+    static async boot(ground) {
+        return new Self(ground, await wardKey(ground.seed));
+    }
+    constructor(ground, key) {
+        this.g = ground;
+        this.key = key;
+        this.pk = key.pk;
+        this.p = open(ground.memory); // the partition IS the ward's cells
+        this.heirs = new Heirs(this.p);
+        this.door = makeDoor(key, this.heirs, this.doors, () => this.p.public, (n) => ground.random(n)); // pointer one
+        this.#boot(this.pk, this); // the ward's ward is itself
+        // a restart is silent: every being in the cells is constructed again, unasked.
+        // A throw on a boot the owner asked for is that boot's answer: silence,
+        // and nothing half-lives. This boot nobody asked for, and there is nobody
+        // to hand a silence to. Any constructor may throw — a default that is not
+        // a value, an author's mistake, a shape she no longer recognises after an
+        // upgrade — and let through here it is one being taking down the ward and
+        // every other being in it, on a restart. She is absent instead: no door,
+        // so silence at the door, and her cells sit untouched, waiting for the
+        // run that can read them.
+        for (const [k, c] of Object.entries(this.p.beings)) {
+            if (k === this.pk || !c.class)
+                continue;
+            try {
+                this.#instantiate(k, c.class);
+            }
+            catch {
+                /* she is not here this run. the ward is, and so is everyone else. */
+            }
+        }
+        // pointer two. the owner. the same answer every named asker gets, asker filled in as owner.
+        this.ask = async (method, args = {}) => {
+            try {
+                const out = await this.answer({ id: OWNER }, method, args);
+                return isSilence(out) || isWord(out) ? silence : out;
+            }
+            catch {
+                return silence;
+            }
+        };
+    }
+    // ---- the ward as a being. asked only by its owners: the root, through
+    // the ask pointer, and its occupants, through the door, whom only the root
+    // can invite. A stranger cannot be a named asker here, because the door
+    // names nobody the ward did not bind.
+    async answer(asker, method, args = {}) {
+        if (asker.id === undefined)
+            return { error: 'unknown ask' };
+        return ownerAnswer({
+            pk: this.pk,
+            doors: this.doors,
+            publicKey: () => this.p.public,
+            instantiate: (key, className, isPublic) => this.#instantiate(key, className, isPublic),
+        }, asker, method, args);
+    }
+    // ---- ward functions. on the object. no stance reaches them.
+    #instantiate(key, className, isPublic = false) {
+        if (!key || this.doors.has(key))
+            return null;
+        const door = this.#boot(key, className);
+        if (!door)
+            return null;
+        door.cells.class = className; // so a restart finds her
+        if (isPublic)
+            this.p.public = key;
+        return door;
+    }
+    // Nothing is written until there is somebody to write it for: a class the
+    // harbor does not know makes no being, and a boot that made nobody must
+    // leave the partition as it found it.
+    #boot(key, classNameOrSelf) {
+        const cells = guardCells(at(this.p.beings, key) ?? emptyCells());
+        const bind = at(this.p.bind, key) ?? emptyBind();
+        const stance = buildStance({
+            pk: this.pk,
+            mintKey: (b) => this.#mintKey(b),
+            openHeir: (heir, being, id) => this.heirs.open(heir, being, id),
+            closeHeir: (heir) => this.heirs.close(heir),
+            send: (b, keys, announce, method, args, wanted) => this.#send(b, keys, announce, method, args, wanted),
+        }, key, cells, bind);
+        const being = classNameOrSelf === this ? this : this.g.instantiate(classNameOrSelf, stance);
+        if (!being)
+            return null;
+        put(this.p.beings, key, cells);
+        put(this.p.bind, key, bind);
+        const door = { key, cells, bind, stance, being };
+        this.doors.set(key, door);
+        return door;
+    }
+    async #mintKey(bind) {
+        const k = await beingKey(this.g.random(32));
+        // The last few she minted, and no more. A relation rotates on every ask,
+        // so a list of all of them is a partition that grows for as long as she
+        // keeps talking and can never be written down. Nothing is read from this
+        // but the keys of the moment.
+        bind.minted.push(k.pk);
+        if (bind.minted.length > MINTED)
+            bind.minted.splice(0, bind.minted.length - MINTED);
+        return k;
+    }
+    // One send for every door, the ward's own included. Mine: never leaves.
+    // Not mine: carry. Signs as the standing's current key, announces its
+    // next, seals to the far ward, opens the reply with the ephemeral secret,
+    // and rotates to the announced key once the far door has answered under
+    // the current one.
+    async #send(bind, keys, announce, method, args, wanted) {
+        // What she asked for, held to what this ward allows. Asking for nothing is
+        // the default, and asking for more than the ceiling is the ceiling: budget
+        // is granted by a ward, never minted by a being.
+        const budget = allow(wanted);
+        const by = (await beingKey(unhex(keys.current))).pk;
+        // A public being is reached without a heir, and the door keeps nothing for
+        // whoever asked: no key it vouched for, so nothing to announce and nothing
+        // to rotate to. A standing on her signs with one key for life.
+        if (announce && keys.next === null && keys.heir !== null)
+            keys.next = (await this.#mintKey(bind)).seed;
+        const next = keys.next === null ? null : (await beingKey(unhex(keys.next))).pk;
+        // Her count for this relation, one higher every call and never reused. The
+        // far door honours each number once. One relation sends one at a time, so
+        // the numbers leave in the order they were taken.
+        const seq = (keys.seq += 1);
+        // Args that will not go through the seal are args that never left. A
+        // being holds three answers and a throw is not one of them, so an ask
+        // that cannot be sealed is told what is true of it: no door was reached.
+        // Values only, by the same rule her cells keep: a Date would arrive as a
+        // string, a function would not arrive at all, and she would never know
+        // the far being was asked something other than what she said.
+        if (cellFault(args, 'args') !== null)
+            return unreached();
+        let sealed;
+        try {
+            sealed = await sealAsk(keys.heir, { by, next, seq, time: budget.time, method, args }, unhex(keys.current), wardPadlock(keys.ward), this.g.random(32));
+        }
+        catch {
+            return unreached();
+        }
+        const { bytes, ephemeral } = sealed;
+        // The wait is bounded, and this is the one thing the ward times. A being
+        // holds three answers and a wait that does not end is none of them: a
+        // relation that comes back round holds a lane the answer needs, and only a
+        // bound on the wait can break that. What comes back late is not read.
+        //
+        // A wait that ran out is `late`, never unreached. Unreached promises
+        // nothing was delivered and is safe to retry; a bound that expired knows
+        // no such thing, because the far door may have heard and be working still.
+        //
+        // A harbor answers bytes or nothing. One that throws instead has answered
+        // nothing in a louder voice, and is read as nothing: no door was reached.
+        const carried = (keys.ward === this.pk ? this.door(new Uint8Array(bytes)).then((r) => r.bytes) : this.g.carry(keys.ward, bytes)).then((b) => b, () => undefined);
+        const out = await within(budget.time, carried);
+        if (out === LATE)
+            return word('late');
+        if (out === undefined)
+            return unreached(); // nothing came back. no door was reached.
+        const reply = await openReply(out, ephemeral, wardSignPk(keys.ward));
+        if (!reply)
+            return silence; // did not open, or not from that ward: not Quo's bytes
+        if ('object' in reply && keys.next !== null) {
+            keys.current = keys.next; // the far door holds `next` as announced. move to it.
+            keys.next = null;
+        }
+        return reply;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quo-systems/quo",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Quo: an object asks another object and gets an answer, without knowing where it is. Being, Ward, Harbor.",
   "keywords": [
     "quo",
@@ -18,42 +18,34 @@
     "node": ">=22.18"
   },
   "exports": {
-    ".": "./src/being/index.ts",
-    "./ward": "./src/ward/index.ts",
-    "./harbor": "./src/harbor/index.ts",
-    "./conformance": "./src/conformance/index.ts"
+    ".": {
+      "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"
+    }
   },
   "scripts": {
-    "check": "npm run typecheck && npm run lint && npm test && npm run check:estate",
-    "check:estate": "node --test \"estate/test/*.test.ts\"",
-    "typecheck": "tsc",
-    "typecheck:watch": "tsc --watch",
-    "lint": "npm run lint:ts && npm run lint:md",
-    "lint:ts": "oxlint --type-aware",
-    "lint:md": "markdownlint-cli2",
-    "lint:fix": "oxlint --type-aware --fix && markdownlint-cli2 --fix",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "test": "node --test \"test/*.test.ts\"",
-    "check:terrain": "node --test \"test/terrain/*.test.ts\" \"estate/test/terrain/*.test.ts\"",
-    "test:being": "node --test test/being.test.ts",
-    "test:ward": "node --test test/ward.test.ts",
-    "prepublishOnly": "npm run check && npm run check:terrain"
-  },
-  "devDependencies": {
-    "@types/node": "^26.4.1",
-    "bun": "^1.4.0",
-    "deno": "^2.9.6",
-    "esbuild": "^0.28.2",
-    "markdownlint-cli2": "^0.23.2",
-    "oxlint": "^1.81.0",
-    "oxlint-tsgolint": "^7.0.2001",
-    "playwright": "^1.62.1",
-    "typescript": "^7.0.2",
-    "workerd": "^1.20260904.1"
+    "check:terrain": "node --test \"test/terrain/*.test.ts\"",
+    "prepublishOnly": "cd ../.. && npm run check && npm run check:terrain"
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
+    "dist",
     "src",
     "vectors",
     "SPEC.md",

package/src/being/index.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // @quo-systems/quo — the Being side. What a being author imports, if anything.
 export { Being, type AskSpec } from './being.ts';
-export { silence, isSilence, unreached, isUnreached } from './silence.ts';
+export { silence, isSilence, unreached, isUnreached, word, isWord, wordOf, DOOR_WORDS, isDoorWord } from './silence.ts';
 export { digest, canonical } from './digest.ts';
 export { OWNER, PUBLIC, RESERVED_IDS } from './types.ts';
 export type * from './types.ts';

package/src/being/silence.ts

@@ -1,14 +1,32 @@
 // SPDX-License-Identifier: Apache-2.0
 // Silence is one distinguished value. Null is an answer. Silence is no answer.
-import { UNREACHED_KEY, type Unreached } from './types.ts';
+//
+// 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, type DoorWord, type Unreached, type Word, type WordName } from './types.ts';
 
 export const silence: unique symbol = Symbol.for('quo.silence');
 export const isSilence = (x: unknown): x is typeof silence => x === silence;
 
-// Unreached is the ward's own word: no far door was reached. It carries no
-// reason. Safe to retry, because nothing was delivered. A being cannot
-// produce it: a ward that sees it come out of a being treats it as silence.
-const UNREACHED: Unreached = Object.freeze({ [UNREACHED_KEY]: true });
-export const unreached = (): Unreached => UNREACHED;
-export const isUnreached = (x: unknown): x is Unreached =>
-  x !== null && typeof x === 'object' && (x as Record<symbol, unknown>)[UNREACHED_KEY] === true;
+// 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: readonly DoorWord[] = ['removed', 'absent', 'unannounced', 'repeated', 'threw'];
+export const isDoorWord = (s: unknown): s is DoorWord => typeof s === 'string' && (DOOR_WORDS as readonly string[]).includes(s);
+
+const WORDS = new Map<WordName, Word>();
+export const word = <W extends WordName>(name: W): Word<W> => {
+  let w = WORDS.get(name);
+  if (!w) WORDS.set(name, (w = Object.freeze({ [WORD_KEY]: name })));
+  return w as Word<W>;
+};
+export const isWord = (x: unknown): x is Word => x !== null && typeof x === 'object' && typeof (x as Record<symbol, unknown>)[WORD_KEY] === 'string';
+export const wordOf = (x: Word): WordName => x[WORD_KEY];
+
+// 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 = (): Unreached => word('unreached');
+export const isUnreached = (x: unknown): x is Unreached => isWord(x) && wordOf(x) === 'unreached';

package/src/being/types.ts

@@ -44,11 +44,21 @@ export type Cells = {
 };
 
 export type Silence = typeof silence;
-export type Unreached = { readonly [K in typeof UNREACHED_KEY]: true };
-export const UNREACHED_KEY: unique symbol = Symbol.for('quo.unreached');
+
+// 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 and none crosses an edge as a value.
+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 | Unreached;
+export type Answer = Json | Silence | Word;
 // What a being answers.
 export type Reply = Json | Silence;
 

package/src/conformance/beings.ts

@@ -2,7 +2,7 @@
 // The fixture beings. Fixed, so that the ward is what varies. A printer, a
 // shop, a customer on the base class, and one raw being with no base at all.
 import { Being } from '../being/being.ts';
-import { isSilence, isUnreached } from '../being/silence.ts';
+import { isSilence, isUnreached, isWord } from '../being/silence.ts';
 import type { Asker, Blueprint, Invitation, JsonObject, OccupantRecord, Reply, Stance } from '../being/types.ts';
 
 // A printer. Invites whom she is told to, prints for her occupants. Her
@@ -46,7 +46,7 @@ export class Shop extends Being {
 
   async keepPrinter(invitation: Invitation): Promise<boolean> {
     const bp = await this.knock(invitation);
-    if (isSilence(bp) || isUnreached(bp)) return false;
+    if (isSilence(bp) || isWord(bp)) return false;
     this.cells.printerId = await this.take('prn', invitation);
     return true;
   }
@@ -55,7 +55,7 @@ export class Shop extends Being {
     const rec = this.occupant(asker);
     if (rec?.notes.tier === 'gold' && invitation) {
       const back = await this.knock(invitation as Invitation, 'hi');
-      if (!isSilence(back) && !isUnreached(back)) await this.take(`vip-${asker.id}`, invitation as Invitation);
+      if (!isSilence(back) && !isWord(back)) await this.take(`vip-${asker.id}`, invitation as Invitation);
     }
     return { welcome: true };
   }
@@ -67,7 +67,7 @@ export class Shop extends Being {
     if (!printer) return { error: 'no printer' };
     const out = await printer.ask('print', { doc: `receipt for ${item}` });
     if (isUnreached(out)) return { error: 'printer unreachable', retry: true };
-    if (isSilence(out)) return { error: 'printer refused' };
+    if (isSilence(out) || isWord(out)) return { error: 'printer refused' };
     const st = this.cells.standings[id!];
     if (st.seen !== st.digest) this.occupant(asker)!.notes.printerChanged = true;
     (this.cells.sales as JsonObject[]).push({ item: item ?? null, by: asker.id ?? null });
@@ -88,7 +88,7 @@ export class Customer extends Being {
   async join(invitation: Invitation) {
     const mine = (await this.invite('shop-back'))!;
     const out = await this.knock(invitation, 'hello', { invitation: mine as never });
-    if (isSilence(out) || isUnreached(out)) return out; // nothing was born
+    if (isSilence(out) || isWord(out)) return out; // nothing was born
     await this.take('shop', invitation); // now, and only now
     return out;
   }