@quo-systems/quo 0.2.10 → 0.2.12

package/dist/harbor/core.js

@@ -17,12 +17,16 @@
 // that arrive from the wire go to an own door or a held socket and never
 // onward by request or by fallback; that one rule is the rendezvous.
 import { Ward } from '../ward/ward.js';
+import { maker, entropy as random, learnPk } from '../ward/ground.js';
 import { silence } from '../being/silence.js';
 import { request } from './reach.js';
-import { openReply, wardSignPk } from '../ward/seal.js';
+import { isWardPk, openReply, wardSignPk } from '../ward/seal.js';
 import { concat, sealingPair, KEY } from '../ward/arithmetic.js';
 import { within, LATE } from '../ward/allowance.js';
 export const DEFAULT_CODE = 'classes/index.ts';
+// The device's entropy, spelled once. A harbor draws it for a ward's seed at
+// birth, for the lid of every probe it sends, and it hands the same function
+// to every ward it boots as the ground's `random`.
 // How long a probe waits for the door behind a claim. A claim that answers
 // nothing in this time is not bound; the next announce is another chance.
 const PROBE = 10_000;
@@ -85,6 +89,17 @@ export class Harbor {
         for (const [pk, url] of Object.entries(await this.store.hints()))
             this.hint(pk, url);
     }
+    // The object a ward writes into, by the name it is kept under: the
+    // partition the harbor was handed at boot and keeps so it can save it.
+    // Nothing in the harbor reads it, and it is not on `Hosted`, because a
+    // side that holds a ward would then hold every seed in it and reach any
+    // being past every door. It is here for one reader, the conformance
+    // suite, whose census is ward state read straight and whose forgeries are
+    // ward state written straight, the way `MemoryHarbor.partitions` is. A
+    // side asks the ward.
+    partitionOf(name) {
+        return this.#saving.get(name)?.memory;
+    }
     // ---- saving
     // The ward wrote. Its partition is saved once the line is free, and once
     // for every burst of writes, in the order the writes came.
@@ -178,10 +193,9 @@ export class Harbor {
     // the one it sealed itself, and it reads nothing from it but that it is
     // the silence a door owes such a box, signed by the claimed key.
     async prove(pk, reach) {
-        if (!/^[0-9a-f]{128}$/.test(pk))
+        if (!isWardPk(pk))
             return false;
         try {
-            const random = (n) => globalThis.crypto.getRandomValues(new Uint8Array(n));
             const lid = await sealingPair(random(KEY));
             const back = await within(PROBE, reach.carry(pk, concat([lid.pk, random(KEY)])));
             if (back === LATE || back === undefined)
@@ -213,10 +227,23 @@ export class Harbor {
                 this.reaches.delete(pk);
         const claimed = [...new Set(pks)].slice(0, ANNOUNCE);
         const prove = async (pk) => {
-            if (this.doors.has(pk) || !(await this.prove(pk, reach)))
+            if (this.doors.has(pk))
+                return;
+            // A line already held for this pk is not displaced by another line that
+            // proves the same pk. A proof says only that the ward is reachable that
+            // way, and a relay that forwards to the real ward proves as well as the
+            // ward's own line does: taking the binding would add a hop the relay
+            // chooses, and can drop. The first held line keeps it until it closes,
+            // which unbind says.
+            const standing = this.reaches.get(pk);
+            if (standing?.held && standing.reach !== reach)
+                return;
+            if (!(await this.prove(pk, reach)))
                 return;
             if (announces.get(reach) !== said)
                 return; // a newer announce has spoken since
+            if (this.reaches.get(pk)?.held && this.reaches.get(pk).reach !== reach)
+                return; // one took it while this was proving
             this.reaches.set(pk, { reach, held });
         };
         for (let i = 0; i < claimed.length; i += PROVING)
@@ -230,7 +257,7 @@ export class Harbor {
     // ---- wards
     // Mint a seed and boot an empty ward under a name: a world born here.
     async create(name, user = '', code = DEFAULT_CODE) {
-        const kept = { seed: globalThis.crypto.getRandomValues(new Uint8Array(32)), partition: {}, record: { pk: '', code, user } };
+        const kept = { seed: random(KEY), partition: {}, record: { pk: '', code, user } };
         await this.store.put(name, kept);
         const hosted = await this.host(name, kept);
         await this.store.record(name, hosted.record);
@@ -244,19 +271,35 @@ export class Harbor {
         const h = this.wards.get(name);
         if (h) {
             await h.save();
+            // Gone for whoever still holds the old pointers, whose save closure has
+            // this row in hand, and out of the map, which now says what this harbor
+            // serves and nothing else.
             const s = this.#saving.get(name);
             if (s)
                 s.gone = true;
+            this.#saving.delete(name);
             this.wards.delete(name);
             this.doors.delete(h.pk);
             this.#announce(); // this harbor no longer claims it: a listener unbinds a pk an announce stops naming
         }
         return this.store.take(name);
     }
-    // Put what another harbor dropped, and boot it: same seed, same pk.
+    // Put what another harbor dropped, and boot it: same seed, same pk. A ward
+    // that will not boot is not adopted. This is the one path where a partition
+    // written somewhere else arrives, so it is the one place the ward's own
+    // shape check is met, and the name is refused for as long as it is kept:
+    // a partition put and left would hold the name against every later try,
+    // with a copy of it in a store that can never serve it. It goes back out,
+    // and the only copy is the one the caller is still holding.
     async adopt(name, kept) {
         await this.store.put(name, kept);
-        return this.host(name, kept);
+        try {
+            return await this.host(name, kept);
+        }
+        catch (e) {
+            await this.store.take(name);
+            throw e;
+        }
     }
     // A ward from what the store keeps: the ground, once, and two pointers.
     async host(name, kept) {
@@ -266,36 +309,49 @@ export class Harbor {
         const ground = {
             seed,
             memory,
-            instantiate: (className, stance) => {
-                // Own keys only: `constructor` is a name Object lends every registry.
-                const C = Object.hasOwn(classes, className) ? classes[className] : Object.hasOwn(this.classes, className) ? this.classes[className] : undefined;
-                if (!C)
-                    return null;
-                const obj = new C(stance);
-                objects.set(stance.cells, obj);
-                return obj;
-            },
+            // This ward's own classes first, then the harbor's: a ward that names a
+            // class of its own is answered with hers.
+            instantiate: maker(objects, classes, this.classes),
             carry: (pk, bytes) => this.carry(pk, new Uint8Array(bytes)),
-            random: (n) => globalThis.crypto.getRandomValues(new Uint8Array(n)),
+            random,
             wrote: () => this.#wrote(name),
         };
         const saving = { memory, dirty: false, running: null, timer: undefined, gone: false };
         this.#saving.set(name, saving);
-        const w = await Ward(ground);
+        // A ward that will not be born leaves nothing behind: a partition of a
+        // shape this kit cannot read throws here, and a name the harbor does not
+        // serve must not have a saving row saying it does. Learning the pk is
+        // inside this, because a ward that will not say its pk is a ward this
+        // harbor cannot route to and is no more born than one that threw.
+        let w, pk;
+        try {
+            w = await Ward(ground);
+            pk = await learnPk(w);
+        }
+        catch (e) {
+            saving.gone = true;
+            this.#saving.delete(name);
+            throw e;
+        }
         // A save the caller may wait for: what the ward wrote so far is in the
         // store when this resolves, or the fault is counted. After a call through
         // a pointer the store is current, so a restart right after it finds
-        // everything; a refusal at the door wrote nothing and saves nothing.
+        // everything; a refusal at the door wrote nothing and saves nothing, and
+        // neither does a read. A ward that wrote nothing has nothing to save, so
+        // asking it what it holds is free, which is what makes the ask pointer
+        // the way to find out rather than an expensive way.
         const save = async () => {
             if (saving.gone)
                 return;
-            saving.dirty = true;
             await this.#flush(name);
         };
         const door = async (bytes) => {
             const r = await w.door(bytes);
-            if (r.heard)
-                await save();
+            // The reply waits for the store, so a restart right after it finds
+            // what the arrival wrote. Whether a key this door holds spoke is not
+            // the test: a stranger at the public being is not heard and her being
+            // may still have written, and a refusal wrote nothing whoever made it.
+            await save();
             return r;
         };
         const ask = async (method, args) => {
@@ -305,13 +361,18 @@ export class Harbor {
             await save();
             return out;
         };
-        const bp = (await w.ask()); // learned by asking, as anyone learns anything
+        // The objects map is keyed by the cells the ward handed instantiate, so
+        // the way back to a being is her cells; the partition is read for that
+        // one lookup and for nothing else, and a key with no object is a being
+        // who is not here this run. `keys` is what the map holds, so a caller
+        // never needs the beings table to find out what to ask for.
         const beings = memory.beings;
         const being = (key) => {
-            const cells = beings?.[key];
+            const cells = beings && Object.hasOwn(beings, key) ? beings[key] : undefined;
             return cells ? objects.get(cells) : undefined;
         };
-        const hosted = { door, ask, pk: bp.notes.pk, name, record: { ...kept.record, pk: bp.notes.pk }, partition: memory, being, save };
+        const keys = () => Object.keys(beings ?? {}).filter((k) => being(k) !== undefined);
+        const hosted = { door, ask, pk, name, record: { ...kept.record, pk }, being, keys, save };
         this.wards.set(name, hosted);
         this.doors.set(hosted.pk, door);
         await save();

package/dist/harbor/dial.js

@@ -1,7 +1,8 @@
 import { REFUSED, Socket } from './reach.js';
 export function dial(harbor, url) {
     const d = { url, socket: null, wake: () => { }, close: () => { } };
-    let stopped = false, wait = 1000, timer, line; // the line in hand, open or still opening: close() closes it either way
+    let stopped = false, wait = 1000, timer, line, // the line in hand, open or still opening: close() closes it either way
+    held; // the one this dialer owns now, and how it gives back what the line took
     const connect = () => {
         timer = undefined; // no wait pending: this is the dial it was waiting for
         if (stopped)
@@ -15,13 +16,15 @@ export function dial(harbor, url) {
             wait = 1000;
             void harbor.bind(far, s, false); // the listener's claims, each proven at its door: reached through this socket, not held for others
         }, (why) => {
-            harbor.announcers.delete(say);
-            harbor.unbind(s);
-            if (d.socket === s)
-                d.socket = null;
-            const at = harbor.fallbacks.indexOf(s);
-            if (at !== -1)
-                harbor.fallbacks.splice(at, 1); // this line only: another dialer's stays
+            shed();
+            // A line this dialer already put down. Its close arrives whenever the
+            // system gets round to noticing, which on a socket that died under a
+            // sleeping device is minutes; by then the line dialed in its place is
+            // the one in hand, so this one gives back what it took and dials
+            // nothing. Only the line the dialer still holds dials again.
+            if (held?.socket !== s)
+                return;
+            held = undefined;
             // A suite this listener will not speak is not a line that dropped. It
             // will not become speakable by asking again sooner, so the wait goes
             // straight to the ceiling and stays there until it changes its mind.
@@ -31,6 +34,18 @@ export function dial(harbor, url) {
                 timer = setTimeout(connect, wait);
             wait = Math.min(wait * 2, 30000);
         });
+        // Everything this line took from the harbor, given back. Said when it
+        // closes, and when the dialer puts it down without waiting for that.
+        const shed = () => {
+            harbor.announcers.delete(say);
+            harbor.unbind(s);
+            if (d.socket === s)
+                d.socket = null;
+            const at = harbor.fallbacks.indexOf(s);
+            if (at !== -1)
+                harbor.fallbacks.splice(at, 1); // this line only: another dialer's stays
+        };
+        held = { socket: s, shed };
         harbor.fallbacks.push(s); // from the moment it is dialed: an ask made before the handshake waits on the socket, and is not unreached
         // What this harbor holds, said when the line opens and again whenever it
         // changes. A ward booted or adopted after the handshake is announced on
@@ -47,13 +62,13 @@ export function dial(harbor, url) {
     d.wake = () => {
         if (stopped)
             return;
-        if (d.socket)
-            return d.socket.announce([...harbor.doors.keys()]);
-        if (timer === undefined)
-            return;
         clearTimeout(timer);
         timer = undefined;
-        wait = 1000;
+        wait = 1000; // the device is back, and the wait it froze belongs to the sleep, not to this line
+        const old = held;
+        held = undefined; // put down before the new one is dialed, so a fallback list never holds the dead line ahead of the live one
+        old?.shed();
+        old?.socket.close();
         connect();
     };
     d.close = () => {

package/dist/harbor/index.d.ts

@@ -4,3 +4,4 @@ export { dial, type Dialer } from './dial.ts';
 export { MemoryStore, values, type Store, type Kept, type WardRecord } from './store.ts';
 export { request, Socket, SUITE, REFUSED, type Reach, type Carry, type Line, type Announce } from './reach.ts';
 export type { Ground, WardPointers } from '../ward/ground.ts';
+export { maker, entropy, learnPk } from '../ward/ground.ts';

package/dist/harbor/index.js

@@ -8,3 +8,6 @@ export { Harbor, DEFAULT_CODE } from './core.js';
 export { dial } from './dial.js';
 export { MemoryStore, values } from './store.js';
 export { request, Socket, SUITE, REFUSED } from './reach.js';
+// What a harbor builds a ground out of. Convenience, never contract: a kit
+// writing its own harbor may write these three again.
+export { maker, entropy, learnPk } from '../ward/ground.js';

package/dist/harbor/memory.d.ts

@@ -1,5 +1,5 @@
-import type { BeingClass } from '../being/types.ts';
-import type { Ground, WardPointers } from '../ward/ground.ts';
+import type { BeingClass, BeingLike } from '../being/types.ts';
+import { type Ground, type WardPointers } from '../ward/ground.ts';
 export type Booted = WardPointers & {
     pk: string;
 };
@@ -16,7 +16,7 @@ export declare class MemoryHarbor {
     cut: boolean;
     readonly partitions: Map<string, Record<string, unknown>>;
     readonly wards: Map<string, Booted>;
-    readonly objects: WeakMap<object, unknown>;
+    readonly objects: WeakMap<object, BeingLike>;
     route(farPk: string, bytes: Uint8Array): Promise<Uint8Array | undefined>;
     link(harbor: MemoryHarbor): void;
     boot(seed: string, Ward: WardFactory, classes: Record<string, BeingClass>): Promise<Booted>;

package/dist/harbor/memory.js

@@ -1,3 +1,4 @@
+import { maker, entropy, learnPk } from '../ward/ground.js';
 import { hex } from '../ward/arithmetic.js';
 export class MemoryHarbor {
     doors = new Map(); // ward pk -> door
@@ -42,26 +43,19 @@ export class MemoryHarbor {
         const ground = {
             seed,
             memory,
-            instantiate: (name, stance) => {
-                // Own keys only: `constructor` is a name Object lends every registry.
-                const C = Object.hasOwn(classes, name) ? classes[name] : undefined;
-                if (!C)
-                    return null;
-                const obj = new C(stance);
-                this.objects.set(stance.cells, obj);
-                return obj;
-            },
+            // One objects map for the whole harbor, not one per ward: every ward
+            // here is in this process and a test reaches any being of any of them.
+            instantiate: maker(this.objects, classes),
             // bytes cross, copied, never a reference. both ways.
             carry: async (farPk, bytes) => {
                 this.wire.push(hex(bytes));
                 const back = await this.route(farPk, new Uint8Array(bytes));
                 return back === undefined ? undefined : new Uint8Array(back);
             },
-            random: (n) => globalThis.crypto.getRandomValues(new Uint8Array(n)),
+            random: entropy,
         };
         const w = await Ward(ground);
-        const bp = (await w.ask()); // the harbor learns its ward's pk the way anyone learns anything: by asking
-        const booted = { ...w, pk: bp.notes.pk };
+        const booted = { ...w, pk: await learnPk(w) };
         this.doors.set(booted.pk, booted.door);
         this.wards.set(seed, booted);
         return booted;

package/dist/harbor/reach.js

@@ -19,7 +19,7 @@
 // at the far end, a connection that would not open, a socket that is gone.
 // A reach that sent the bytes and lost the line afterwards answers nothing
 // at all, and the ward's own bound ends the ask.
-import { hex, unhex } from '../ward/arithmetic.js';
+import { concat, hex, unhex } from '../ward/arithmetic.js';
 const never = () => new Promise(() => { }); // sent, and no word since: the ward's bound decides
 // A request reach to one listener.
 export function request(url) {
@@ -28,8 +28,14 @@ export function request(url) {
         close: () => { },
         carry: async (pk, bytes) => {
             let res;
+            // A body of its own, not the caller's view: fetch reads it after this
+            // line returns, and a buffer somebody else may write is not a body. The
+            // copy is its own ArrayBuffer, which is what a body is; the bytes handed
+            // in are typed as backed by anything, shared memory included.
+            const body = new Uint8Array(bytes.length);
+            body.set(bytes);
             try {
-                res = await fetch(`${base}/${pk}`, { method: 'POST', headers: { 'content-type': 'application/octet-stream', 'quo-suite': String(SUITE) }, body: new Uint8Array(bytes) });
+                res = await fetch(`${base}/${pk}`, { method: 'POST', headers: { 'content-type': 'application/octet-stream', 'quo-suite': String(SUITE) }, body });
             }
             catch {
                 return undefined; // the connection never opened: nothing was delivered
@@ -137,7 +143,7 @@ export class Socket {
                     head[0] = back === undefined ? NONE : REPLY;
                     new DataView(head.buffer).setUint32(1, id);
                     if (line.readyState === OPEN)
-                        line.send(back === undefined ? head : concat(head, back));
+                        line.send(back === undefined ? head : concat([head, back]));
                 });
                 return;
             }
@@ -176,16 +182,10 @@ export class Socket {
             if (this.pending.size >= PENDING)
                 this.pending.delete(this.pending.keys().next().value); // the oldest, which the ward's bound ended long ago
             this.pending.set(id, ok);
-            this.line.send(concat(head, bytes));
+            this.line.send(concat([head, bytes]));
         });
     }
     close() {
         this.line.close();
     }
 }
-function concat(a, b) {
-    const out = new Uint8Array(a.length + b.length);
-    out.set(a, 0);
-    out.set(b, a.length);
-    return out;
-}

package/dist/ward/allowance.js

@@ -33,8 +33,13 @@ export function allow(wanted, ceiling = CEILING, base = DEFAULT) {
     };
     return { time: Math.min(whole(wanted?.time, base.time), ceiling.time) };
 }
-// Whether a budget has anything left to spend. A door reads this on arrival.
-export const spent = (a) => !(a.time > 0);
+// Whether a budget has anything left to spend, and the one reader of it: the
+// door calls this on arrival and nothing else asks the question anywhere. A
+// time that is not a whole number above zero is not a budget that ran out, it
+// is no budget at all, and the door refuses both the same way, since a peer
+// learns nothing from the difference. `allow` never makes one, so only bytes
+// off the road ever carry one.
+export const spent = (a) => !(Number.isSafeInteger(a.time) && a.time > 0);
 // What a wait that ran out comes back as. Its own value, held by nobody
 // outside the ward, so no answer from any door can be mistaken for it.
 export const LATE = Symbol('late');

package/dist/ward/arithmetic.d.ts

@@ -17,6 +17,7 @@ export declare function sealingPair(seed: Uint8Array): Promise<Pair>;
 export declare function sign(message: Uint8Array, secret: Uint8Array): Promise<Uint8Array>;
 export declare function verify(message: Uint8Array, signature: Uint8Array, pk: Uint8Array): Promise<boolean>;
 export declare function agree(secret: Uint8Array, peerPk: Uint8Array): Promise<Uint8Array>;
+export declare function derive(secret: Uint8Array, label: Uint8Array, bytes: number): Promise<Uint8Array>;
 export declare function encrypt(shared: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): Promise<Uint8Array>;
 export declare function decrypt(shared: Uint8Array, ciphertext: Uint8Array, aad: Uint8Array): Promise<Uint8Array>;
 export declare function box(inside: Uint8Array, padlock: Uint8Array, seed: Uint8Array): Promise<{

package/dist/ward/arithmetic.js

@@ -23,7 +23,7 @@ export const SIGNATURE = 64;
 export const NONCE = 12;
 export const TAG = 16;
 const SEAL_INFO = new TextEncoder().encode('quo-seal');
-const SEAL_SALT = new Uint8Array(0);
+const SALT = new Uint8Array(0);
 // A 32-byte secret plus a fixed prefix is the whole PKCS#8 wrapping for both curves.
 const ED_SECRET = unhex('302e020100300506032b657004220420');
 const X_SECRET = unhex('302e020100300506032b656e04220420');
@@ -132,11 +132,19 @@ export async function agree(secret, peerPk) {
         throw new Error('dead agreement'); // a padlock that was not a real key
     return shared;
 }
+// HKDF-SHA-256: bytes from a secret, under a label that says what they are
+// for. No salt, because the secret handed in is already a secret of full
+// strength and the label is what keeps one use apart from another. Every
+// label in this kit is spelled where it is used, never here: this is
+// arithmetic and a label is a decision.
+export async function derive(secret, label, bytes) {
+    const material = await subtle().importKey('raw', secret, 'HKDF', false, ['deriveBits']);
+    return new Uint8Array(await subtle().deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: SALT, info: label }, material, bytes * 8));
+}
 // One HKDF-SHA-256 yields the AES key and the nonce together. The nonce needs
 // no randomness of its own: the key it pairs with is fresh on every message.
 async function cipherKey(shared, use) {
-    const material = await subtle().importKey('raw', shared, 'HKDF', false, ['deriveBits']);
-    const out = new Uint8Array(await subtle().deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: SEAL_SALT, info: SEAL_INFO }, material, (KEY + NONCE) * 8));
+    const out = await derive(shared, SEAL_INFO, KEY + NONCE);
     return { key: await subtle().importKey('raw', out.subarray(0, KEY), 'AES-GCM', false, [use]), nonce: out.subarray(KEY) };
 }
 // The additional authenticated data is the ephemeral public key: the one thing outside the seal, bound to it.

package/dist/ward/door.d.ts

@@ -1,11 +1,11 @@
-import type { Asker, BeingLike, JsonObject } from '../being/types.ts';
+import type { Asker, BeingLike, JsonObject, OccupantRecord } from '../being/types.ts';
 import type { Heirs } from './heirs.ts';
 import { type ReplyPayload, type WardKey } from './seal.ts';
 export type Door = {
     key: string;
     being: BeingLike;
     cells: {
-        occupants: Record<string, unknown>;
+        occupants: Record<string, OccupantRecord>;
     };
 };
 export type Judged = {

package/dist/ward/door.js

@@ -66,9 +66,10 @@ export function makeDoor(key, heirs, doors, publicKey, random) {
             return null; // D1. it did not open. there is nobody to answer.
         const { to, payload, ephemeralPk } = a;
         const refuse = () => ({ reply: SILENCE, ephemeralPk, heard: false });
-        // D2, the rest of it. The allowance is read before anything is done under
-        // it, and hops at zero is refused so that a relay chain invented later
-        // meets doors that already stop it. Nothing sets hops.
+        // D2. The allowance is read here, before anything is done under it, and
+        // here only: a time that is not a whole number above zero is malformed and
+        // is refused as one. Hops at zero is refused beside it, so that a relay
+        // chain invented later meets doors that already stop it. Nothing sets hops.
         if (spent({ time: payload.time }) || payload.hops === 0)
             return refuse();
         const args = payload.args ?? {};
@@ -80,7 +81,10 @@ export function makeDoor(key, heirs, doors, publicKey, random) {
             const pub = pk !== null ? doors.get(pk) : undefined;
             if (!pub || !(await verifyAsk(a, payload.by)))
                 return refuse();
-            return { reply: await arrive(pub, {}, payload.method, args, false), ephemeralPk, heard: true };
+            // She answers, and the bit stays false: no key this door holds spoke.
+            // The public being is the one place a stranger is answered by design,
+            // so it is the one place a harbor must still be able to rate her.
+            return { reply: await arrive(pub, {}, payload.method, args, false), ephemeralPk, heard: false };
         }
         const h = heirs.admits(to, payload.by);
         if (!h) {
@@ -124,8 +128,13 @@ export function makeDoor(key, heirs, doors, publicKey, random) {
     // door never throws: that reply is noise, a plain silence sealed to a key
     // nobody holds, and the same is written for anything else the seal will
     // not take.
+    // `judge` reads rows it does not check: open() reads the partition's shape
+    // at birth, so a row it acts on is the shape it expects. That is the first
+    // line and this is the second, because "the door never throws" is a promise
+    // to the harbor, which has nobody to hand a rejection to and would count it
+    // as no answer at all. Anything unforeseen is the silence a stranger hears.
     return async function door(bytes) {
-        const out = await judge(bytes);
+        const out = await judge(bytes).catch(() => null);
         const reply = out?.reply ?? SILENCE;
         const heard = out?.heard ?? false;
         try {

package/dist/ward/ground.d.ts

@@ -1,4 +1,4 @@
-import type { Stance, BeingLike } from '../being/types.ts';
+import type { Stance, BeingLike, BeingClass } from '../being/types.ts';
 export type Ground = {
     seed: string | Uint8Array;
     memory: Record<string, unknown>;
@@ -14,3 +14,6 @@ export type WardPointers = {
     }>;
     ask(method?: string, args?: Record<string, unknown>): Promise<unknown>;
 };
+export declare const maker: (objects: WeakMap<object, BeingLike>, ...registries: (Record<string, BeingClass> | undefined)[]) => Ground['instantiate'];
+export declare const entropy: (n: number) => Uint8Array;
+export declare function learnPk(w: WardPointers): Promise<string>;

package/dist/ward/ground.js

@@ -1 +1,38 @@
-export {};
+// ---- what every harbor builds a ground out of. Three pieces, because every
+// harbor in this tree writes the same three and the spec keeps the harbors
+// themselves apart: what a memory harbor and a real one differ on is the
+// route and the store, and nothing here. A second kit writes its own harbor
+// and may write these again; they are convenience, never contract.
+// The code half of a ground, and the map back to what it made. A class is
+// found by own key only, since `constructor` is a name Object lends every
+// registry, and the first registry holding the name wins, so a ward's own
+// classes stand in front of the harbor's. The object is remembered by the
+// cells the ward handed in, which is how a side reaches a being it made and
+// how that hand follows her out when she is unbooted.
+export const maker = (objects, ...registries) => (className, stance) => {
+    const r = registries.find((reg) => reg !== undefined && Object.hasOwn(reg, className));
+    const C = r?.[className];
+    if (!C)
+        return null;
+    const obj = new C(stance);
+    objects.set(stance.cells, obj);
+    return obj;
+};
+// Entropy, from the one place every terrain that runs Quo has it. Every key a
+// ward mints is drawn from this, so a harbor that wants another source hands
+// its own and nothing here has to know.
+export const entropy = (n) => globalThis.crypto.getRandomValues(new Uint8Array(n));
+// A ward's pk, learned the way anyone learns anything: by asking. The empty
+// ask on the ask pointer is the ward's own describe and its notes carry the
+// pk. A harbor has no other way to it and wants none: the ward mints it from
+// the seed, and a harbor that read it off the seed itself would be a second
+// derivation to keep in step with the first. A ward that answers anything
+// else is not one this harbor can route to, and says so here rather than
+// leaving an undefined pk in a directory.
+export async function learnPk(w) {
+    const notes = (await w.ask());
+    const pk = notes?.notes?.pk;
+    if (typeof pk !== 'string')
+        throw new Error('the ward did not say its pk');
+    return pk;
+}

package/dist/ward/heirs.d.ts

@@ -6,9 +6,8 @@ export declare class Heirs {
     open(heir: string, being: string, id: string): void;
     close(heir: string): void;
     gone(heir: string, by: string): boolean;
-    get(heir: string): Heir | undefined;
     admits(heir: string, by: string): Heir | null;
     spend(h: Heir, seq: number): boolean;
     honour(h: Heir, by: string, next: string | null, seq: number): true | DoorWord;
-    settle(h: Heir, by: string, next: string | null): boolean;
+    settle(h: Heir, by: string, next: string | null): void;
 }

package/dist/ward/heirs.js

@@ -33,9 +33,6 @@ export class Heirs {
         const g = this.#p.gone[heir];
         return !!g && (by === g.current || by === g.announced);
     }
-    get(heir) {
-        return this.#p.heirs[heir];
-    }
     // May `by` speak for this heir? Returns the record if so, null if not.
     // Does not write: the caller verifies the signature first, then settles.
     admits(heir, by) {
@@ -79,31 +76,33 @@ export class Heirs {
     // neither: a call that binds nothing must not burn a number on its way to
     // being refused, or a stranger who cannot be heard would still leave a mark
     // behind her. Every write below this line is one that is going to hold.
+    // This is where a knock is judged and where `unannounced` is said. settle
+    // below is the writing alone, and it judges nothing: one owner for the
+    // question, one for the answer.
     honour(h, by, next, seq) {
         if (h.fresh && (next === null || next === h.current))
             return 'unannounced'; // a knock without a key of her own binds nothing, and the heir is not a key of her own
         if (!this.spend(h, seq))
             return 'repeated';
-        const settled = this.settle(h, by, next);
-        this.#wrote(); // the number is spent whether or not the keys settled
-        return settled ? true : 'unannounced';
+        this.settle(h, by, next);
+        this.#wrote(); // the number and the keys moved together
+        return true;
     }
-    // The signature checked out. Settle the keys: a fresh heir rotates at once
-    // to what it announced and must announce something that is not itself, so
-    // that the heir dies as it speaks; a current key replaces its
-    // announcement; an announced key becomes current.
+    // The signature checked out and honour has judged. Settle the keys: a fresh
+    // heir rotates at once to what it announced, which honour has already held
+    // to being something other than itself, so that the heir dies as it speaks;
+    // a current key replaces its announcement; an announced key becomes current.
     settle(h, by, next) {
         if (h.fresh) {
-            if (next === null || next === h.current)
-                return false;
+            if (next === null)
+                return; // honour judged this. the compiler has not read it, so the narrowing stays.
             h.current = next;
             h.announced = null;
             h.fresh = false;
-            return true;
+            return;
         }
         if (by === h.announced)
             h.current = by;
         h.announced = next;
-        return true;
     }
 }