@quo-systems/quo 0.2.10 → 0.2.12

package/src/harbor/core.ts

@@ -17,16 +17,31 @@
 // 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.ts';
-import type { Ground, WardPointers } from '../ward/ground.ts';
+import { maker, entropy as random, learnPk, type Ground, type WardPointers } from '../ward/ground.ts';
 import type { BeingClass, BeingLike } from '../being/types.ts';
 import { silence } from '../being/silence.ts';
 import { request, type Reach } from './reach.ts';
-import { openReply, wardSignPk } from '../ward/seal.ts';
+import { isWardPk, openReply, wardSignPk } from '../ward/seal.ts';
 import { concat, sealingPair, KEY } from '../ward/arithmetic.ts';
 import { within, LATE } from '../ward/allowance.ts';
 import type { Kept, Store, WardRecord } from './store.ts';
 
-export type Hosted = WardPointers & { pk: string; name: string; record: WardRecord; partition: Record<string, unknown>; being(key: string): BeingLike | undefined; save(): Promise<void> };
+// What a harbor hands its own device for one ward it serves. The two
+// pointers, and beside them what the device needs to be a device: the pk it
+// routes by, the name it is kept under, the record, a save the caller may
+// wait for.
+//
+// And the beings the harbor made. `instantiate` is in the ground, so the
+// harbor is the one that constructs every being of every ward it serves: it
+// holds those objects because it made them, and `being` and `keys` say what
+// it made. This is not a third path to a being. It is the device's own code
+// reaching its own object in its own process, the same reach a being has on
+// one she booted herself, and nothing of it crosses an edge. What a harbor
+// never does is read the partition to decide anything, and the partition is
+// not here: it holds every seed the ward has, and a side that wants to know
+// which beings there are or which one is public asks the ward, which is
+// what the ask pointer is for.
+export type Hosted = WardPointers & { pk: string; name: string; record: WardRecord; being(key: string): BeingLike | undefined; keys(): string[]; save(): Promise<void> };
 
 // One ward's saves, in a line: the ward says it wrote, the harbor writes the
 // partition once the line is free, and never twice at once, so an older
@@ -42,6 +57,9 @@ export type Bound = { reach: Reach; held: boolean };
 export type Loader = (record: WardRecord) => Promise<Record<string, BeingClass>>;
 
 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;
@@ -104,6 +122,18 @@ 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: string): Record<string, unknown> | undefined {
+    return this.#saving.get(name)?.memory;
+  }
+
   // ---- saving
 
   // The ward wrote. Its partition is saved once the line is free, and once
@@ -191,9 +221,8 @@ 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: string, reach: Reach): Promise<boolean> {
-    if (!/^[0-9a-f]{128}$/.test(pk)) return false;
+    if (!isWardPk(pk)) return false;
     try {
-      const random = (n: number) => 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) return false;
@@ -222,8 +251,18 @@ export class Harbor {
     for (const [pk, b] of this.reaches) if (b.reach === reach && !pks.includes(pk)) this.reaches.delete(pk);
     const claimed = [...new Set(pks)].slice(0, ANNOUNCE);
     const prove = async (pk: string) => {
-      if (this.doors.has(pk) || !(await this.prove(pk, reach))) return;
+      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) await Promise.all(claimed.slice(i, i + PROVING).map(prove));
@@ -236,7 +275,7 @@ export class Harbor {
 
   // Mint a seed and boot an empty ward under a name: a world born here.
   async create(name: string, user = '', code = DEFAULT_CODE): Promise<Hosted> {
-    const kept: Kept = { seed: globalThis.crypto.getRandomValues(new Uint8Array(32)), partition: {}, record: { pk: '', code, user } };
+    const kept: 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);
@@ -251,8 +290,12 @@ 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
@@ -260,10 +303,21 @@ export class Harbor {
     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: string, kept: Kept): Promise<Hosted> {
     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.
@@ -274,33 +328,47 @@ export class Harbor {
     const ground: 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: 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: WardPointers, pk: string;
+    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: Uint8Array) => {
       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?: string, args?: Record<string, unknown>) => {
@@ -309,13 +377,18 @@ export class Harbor {
       await save();
       return out;
     };
-    const bp = (await w.ask()) as { notes: { pk: string } }; // 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 as Record<string, object> | undefined;
     const being = (key: string) => {
-      const cells = beings?.[key];
+      const cells = beings && Object.hasOwn(beings, key) ? beings[key] : undefined;
       return cells ? objects.get(cells) : undefined;
     };
-    const hosted: 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: 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/src/harbor/dial.ts

@@ -12,11 +12,22 @@ import type { Harbor } from './core.ts';
 import { REFUSED, Socket, type Line } from './reach.ts';
 
 // `wake` is the device saying it is back: a phone out of a pocket, a
-// laptop's lid opened. A device that slept comes back with its timer
-// frozen and, often, its socket closed under it by the system without a
-// word. So a line in hand is made to speak, an announce, and a dead one
-// closes under the word and is dialed again; a line that is down is dialed
-// now instead of waiting out the backoff; a dial in flight is left alone.
+// laptop's lid opened. A device that slept comes back with its timer frozen
+// and, often, its socket closed under it by the system without a word. So
+// nothing in hand is trusted: whatever line there is, open or still opening,
+// is put down and a new one is dialed now.
+//
+// Nothing here can tell a line the system dropped from a live one, and
+// asking is worse than dialing. An announce written into a dead line is
+// taken into the send buffer and the error comes when TCP gives up
+// retransmitting, one to two minutes on a Mac and up to fifteen on Linux,
+// and for all of it every ask to a pk bound behind that line hears `late`.
+// A probe with a bound would want a round trip the wire does not have: four
+// words, none of them a ping, and making one out of an ask would give a
+// second kit's listener a meaning to reproduce. Dialing costs one handshake
+// when the line was fine, and an ask made meanwhile waits on the new socket
+// rather than being lost, because a socket is a fallback from the moment it
+// is dialed.
 export type Dialer = { url: string; socket: Socket | null; wake(): void; close(): void };
 
 export function dial(harbor: Harbor, url: string): Dialer {
@@ -24,7 +35,8 @@ export function dial(harbor: Harbor, url: string): Dialer {
   let stopped = false,
     wait = 1000,
     timer: ReturnType<typeof setTimeout> | undefined,
-    line: Line | undefined; // the line in hand, open or still opening: close() closes it either way
+    line: Line | undefined, // the line in hand, open or still opening: close() closes it either way
+    held: { socket: Socket; shed: () => void } | undefined; // 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) return;
@@ -41,11 +53,14 @@ export function dial(harbor: Harbor, url: string): Dialer {
         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.
@@ -54,6 +69,16 @@ export function dial(harbor: Harbor, url: string): Dialer {
         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
@@ -68,11 +93,13 @@ export function dial(harbor: Harbor, url: string): Dialer {
   };
   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/src/harbor/index.ts

@@ -9,3 +9,6 @@ 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';
+// 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.ts';

package/src/harbor/memory.ts

@@ -4,8 +4,8 @@
 // keeping TWO pointers. Routes one ward pk to one door. Knows no being,
 // reads no partition, opens no byte. Several memory harbors may be linked,
 // which stands in for a wire, and cut, which stands in for weather.
-import type { BeingClass, Stance } from '../being/types.ts';
-import type { Ground, WardPointers } from '../ward/ground.ts';
+import type { BeingClass, BeingLike } from '../being/types.ts';
+import { maker, entropy, learnPk, type Ground, type WardPointers } from '../ward/ground.ts';
 import { hex } from '../ward/arithmetic.ts';
 
 export type Booted = WardPointers & { pk: string };
@@ -20,7 +20,7 @@ export class MemoryHarbor {
   cut = false;
   readonly partitions = new Map<string, Record<string, unknown>>(); // seed -> memory. the harbor keeps it and reads nothing
   readonly wards = new Map<string, Booted>(); // seed -> pointers
-  readonly objects = new WeakMap<object, unknown>(); // cells -> being object. what instantiate constructed. a hand for tests, never the ward's; it follows the cells out when she is unbooted
+  readonly objects = new WeakMap<object, BeingLike>(); // cells -> being object. what instantiate constructed. a hand for tests, never the ward's; it follows the cells out when she is unbooted
 
   // the directory: its own doors, else a peer it is linked to. Quo says nothing about how.
   async route(farPk: string, bytes: Uint8Array): Promise<Uint8Array | undefined> {
@@ -54,25 +54,19 @@ export class MemoryHarbor {
     const ground: Ground = {
       seed,
       memory,
-      instantiate: (name: string, stance: 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()) as { notes: { pk: string } }; // the harbor learns its ward's pk the way anyone learns anything: by asking
-    const booted: Booted = { ...w, pk: bp.notes.pk };
+    const booted: Booted = { ...w, pk: await learnPk(w) };
     this.doors.set(booted.pk, booted.door);
     this.wards.set(seed, booted);
     return booted;

package/src/harbor/reach.ts

@@ -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.ts';
+import { concat, hex, unhex } from '../ward/arithmetic.ts';
 
 export type Carry = (pk: string, bytes: Uint8Array) => Promise<Uint8Array | undefined>;
 export type Reach = { carry: Carry; close(): void };
@@ -33,8 +33,14 @@ export function request(url: string): Reach {
     close: () => {},
     carry: async (pk, bytes) => {
       let res: Response;
+      // 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) as unknown as BodyInit });
+        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
       }
@@ -163,7 +169,7 @@ export class Socket implements Reach {
             const head = new Uint8Array(5);
             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));
+            if (line.readyState === OPEN) line.send(back === undefined ? head : concat([head, back]));
           });
         return;
       }
@@ -199,7 +205,7 @@ export class Socket implements Reach {
     return new Promise((ok) => {
       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]));
     });
   }
 
@@ -207,10 +213,3 @@ export class Socket implements Reach {
     this.line.close();
   }
 }
-
-function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
-  const out = new Uint8Array(a.length + b.length);
-  out.set(a, 0);
-  out.set(b, a.length);
-  return out;
-}

package/src/ward/allowance.ts

@@ -43,8 +43,13 @@ export function allow(wanted: Wanted | undefined, ceiling: Allowance = CEILING,
   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: Allowance): boolean => !(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: Allowance): boolean => !(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.

package/src/ward/arithmetic.ts

@@ -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');
@@ -135,22 +135,31 @@ export async function agree(secret: Uint8Array, peerPk: Uint8Array): Promise<Uin
   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: Uint8Array, label: Uint8Array, bytes: number): Promise<Uint8Array> {
+  const material = await subtle().importKey('raw', secret as BufferSource, 'HKDF', false, ['deriveBits']);
+  return new Uint8Array(await subtle().deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: SALT, info: label as BufferSource }, 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: Uint8Array, use: KeyUsage) {
-  const material = await subtle().importKey('raw', shared as BufferSource, '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) as BufferSource, '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.
 export async function encrypt(shared: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): Promise<Uint8Array> {
   const { key, nonce } = await cipherKey(shared, 'encrypt');
-  return new Uint8Array(await subtle().encrypt({ name: 'AES-GCM', iv: nonce, additionalData: key32(aad, 'aad') as BufferSource, tagLength: TAG * 8 }, key, plaintext as BufferSource));
+  return new Uint8Array(await subtle().encrypt({ name: 'AES-GCM', iv: nonce as BufferSource, additionalData: key32(aad, 'aad') as BufferSource, tagLength: TAG * 8 }, key, plaintext as BufferSource));
 }
 export async function decrypt(shared: Uint8Array, ciphertext: Uint8Array, aad: Uint8Array): Promise<Uint8Array> {
   if (ciphertext.length < TAG) throw new Error('short input');
   const { key, nonce } = await cipherKey(shared, 'decrypt');
-  return new Uint8Array(await subtle().decrypt({ name: 'AES-GCM', iv: nonce, additionalData: key32(aad, 'aad') as BufferSource, tagLength: TAG * 8 }, key, ciphertext as BufferSource));
+  return new Uint8Array(await subtle().decrypt({ name: 'AES-GCM', iv: nonce as BufferSource, additionalData: key32(aad, 'aad') as BufferSource, tagLength: TAG * 8 }, key, ciphertext as BufferSource));
 }
 
 // A box: an ephemeral X25519 pk outside, one ciphertext sealed to the

package/src/ward/door.ts

@@ -9,7 +9,7 @@
 // asker rides back with the object.
 import { isSilence, isWord } from '../being/silence.ts';
 import { digest } from '../being/digest.ts';
-import type { Asker, BeingLike, DoorWord, JsonObject } from '../being/types.ts';
+import type { Asker, BeingLike, DoorWord, JsonObject, OccupantRecord } from '../being/types.ts';
 import { at } from './partition.ts';
 import type { Heirs } from './heirs.ts';
 import { openAsk, sealReply, verifyAsk, type ReplyPayload, type WardKey } from './seal.ts';
@@ -17,7 +17,7 @@ import { spent } from './allowance.ts';
 import { KEY, sealingPair } from './arithmetic.ts';
 import { cellFault } from './cells.ts';
 
-export type Door = { key: string; being: BeingLike; cells: { occupants: Record<string, unknown> } };
+export type Door = { key: string; being: BeingLike; cells: { occupants: Record<string, OccupantRecord> } };
 export type Judged = { bytes: Uint8Array; heard: boolean };
 const SILENCE: ReplyPayload = { silence: true };
 const said = (quo: DoorWord): ReplyPayload => ({ quo });
@@ -69,9 +69,10 @@ export function makeDoor(key: WardKey, heirs: Heirs, doors: Map<string, Door>, p
     if (!a) return null; // D1. it did not open. there is nobody to answer.
     const { to, payload, ephemeralPk } = a;
     const refuse = (): Verdict => ({ 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 ?? {};
     if (to === null) {
@@ -81,7 +82,10 @@ export function makeDoor(key: WardKey, heirs: Heirs, doors: Map<string, Door>, p
       const pk = publicKey();
       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) {
@@ -120,8 +124,13 @@ export function makeDoor(key: WardKey, heirs: Heirs, doors: Map<string, Door>, p
   // 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: Uint8Array): Promise<Judged> {
-    const out = await judge(bytes);
+    const out = await judge(bytes).catch(() => null);
     const reply = out?.reply ?? SILENCE;
     const heard = out?.heard ?? false;
     try {

package/src/ward/ground.ts

@@ -2,7 +2,7 @@
 // The ground. The one object a harbor passes a ward at birth. Six things,
 // never a seventh. Everything a runtime differs on arrives here, which is
 // why the ward itself knows no runtime.
-import type { Stance, BeingLike } from '../being/types.ts';
+import type { Stance, BeingLike, BeingClass } from '../being/types.ts';
 
 export type Ground = {
   seed: string | Uint8Array; // the ward derives its pk from it and nothing else
@@ -44,3 +44,45 @@ export type WardPointers = {
   door(bytes: Uint8Array): Promise<{ bytes: Uint8Array; heard: boolean }>;
   ask(method?: string, args?: Record<string, unknown>): Promise<unknown>;
 };
+
+// ---- 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: WeakMap<object, BeingLike>, ...registries: (Record<string, BeingClass> | undefined)[]): Ground['instantiate'] =>
+  (className: string, stance: 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: number): Uint8Array => 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: WardPointers): Promise<string> {
+  const notes = (await w.ask()) as { notes?: { pk?: unknown } } | null;
+  const pk = notes?.notes?.pk;
+  if (typeof pk !== 'string') throw new Error('the ward did not say its pk');
+  return pk;
+}