@quo-systems/quo 0.2.9 → 0.2.11

package/src/harbor/core.ts

@@ -17,15 +17,38 @@
 // 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
+// snapshot cannot land after a newer one. A save that fails is the harbor's
+// to count and never a door's to answer: the door answered bytes, and a
+// disk that is full is not a reason the far side may hear.
+type Saving = { memory: Record<string, unknown>; dirty: boolean; running: Promise<void> | null; timer: ReturnType<typeof setTimeout> | undefined; gone: boolean };
 // A reach in the directory, and whether this harbor holds it as a socket a
 // dialer opened: only those, and its own doors, take bytes from the wire.
 export type Bound = { reach: Reach; held: boolean };
@@ -34,9 +57,18 @@ 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;
+// How many pks one announce may claim, and how many are proven at once.
+const ANNOUNCE = 64;
+const PROVING = 8;
+// How many times each reach has announced: a proof from an older announce
+// binds nothing when it lands.
+const announces = new WeakMap<Reach, number>();
 
 export class Harbor {
   readonly store: Store;
@@ -46,7 +78,10 @@ export class Harbor {
   readonly reaches = new Map<string, Bound>(); // the directory: foreign ward pk -> reach
   readonly down = new Set<string>(); // pks this harbor will not reach right now: weather, for a test
   readonly refused = new Map<string, number>(); // own ward pk -> arrivals its door would not admit. what a terrain does with it is its own
+  readonly faults = new Map<string, number>(); // ward name -> saves the store refused. what a terrain does with it is its own
+  readonly unbooted: string[] = []; // the wards the store keeps that would not host this run, by name
   readonly classes: Record<string, BeingClass> = {}; // classes handed in-process, beside the loader's
+  readonly #saving = new Map<string, Saving>();
   // The dialers' sockets, in the order they were dialed: where a pk nobody
   // here knows is sent, because the listener a harbor dialed is a rendezvous
   // and may hold that pk for someone else. It is a list because a harbor may
@@ -72,15 +107,68 @@ export class Harbor {
     this.loader = loader;
   }
 
-  // Boot every ward the store keeps, and learn the hints.
+  // Boot every ward the store keeps, and learn the hints. One ward that will
+  // not host, a partition this kit cannot read or a loader that throws, is
+  // named in `unbooted` and takes nobody else down with it.
   async boot(): Promise<void> {
     for (const name of await this.store.list()) {
-      const kept = await this.store.load(name);
-      if (kept) await this.host(name, kept);
+      try {
+        const kept = await this.store.load(name);
+        if (kept) await this.host(name, kept);
+      } catch {
+        this.unbooted.push(name);
+      }
     }
     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
+  // for every burst of writes, in the order the writes came.
+  #wrote(name: string): void {
+    const s = this.#saving.get(name);
+    if (!s || s.gone) return;
+    s.dirty = true;
+    if (s.timer === undefined) s.timer = setTimeout(() => void this.#flush(name), 0);
+  }
+  async #flush(name: string): Promise<void> {
+    const s = this.#saving.get(name);
+    if (!s) return;
+    if (s.timer !== undefined) {
+      clearTimeout(s.timer);
+      s.timer = undefined;
+    }
+    if (s.running) return s.running;
+    s.running = (async () => {
+      while (s.dirty && !s.gone) {
+        s.dirty = false;
+        try {
+          await this.store.save(name, s.memory);
+        } catch {
+          this.faults.set(name, (this.faults.get(name) ?? 0) + 1);
+        }
+      }
+    })();
+    try {
+      await s.running;
+    } finally {
+      s.running = null;
+    }
+  }
+
   // ---- the directory
 
   // Bytes to one of this harbor's own doors, and the one bit the door says
@@ -113,7 +201,7 @@ export class Harbor {
   }
 
   hint(pk: string, url: string): void {
-    if (this.reaches.get(pk)?.held) return; // a socket in hand beats a hint
+    if (this.reaches.has(pk)) return; // a reach proven at a door beats a hint, held or reached through a dialed line
     this.reaches.set(pk, { reach: request(url), held: false });
   }
 
@@ -130,12 +218,11 @@ export class Harbor {
   // signed by the ward key. Only the holder of that ward's seed can write
   // that reply, the lid is fresh so nothing replays, and a box that does not
   // open writes nothing at the ward. This is the one box a harbor ever opens,
-  // the one it sealed itself, and it reads nothing from it but that the
-  // signature is the claimed key's.
+  // 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;
@@ -148,16 +235,37 @@ export class Harbor {
 
   // Bind what the far side claims, each pk proven at its door first. Both
   // sides bind this way: the listener the dialer's claims, the dialer the
-  // listener's, since a claim is a claim whichever end made it.
+  // listener's, since a claim is a claim whichever end made it. An announce
+  // names at most this many pks, and they are proven a few at a time: a
+  // side that announced a thousand would otherwise cost a thousand keys, a
+  // thousand frames and a thousand waits at once, on its word alone.
   async bind(pks: string[], reach: Reach, held: boolean): Promise<void> {
     // An announce is the whole of what that side holds now, so a pk this
-    // reach was bound for and no longer claims is unbound at once: a ward
+    // reach was bound for and does not claim now is unbound at once: a ward
     // that left a dialer is not reachable through it, proof or no proof.
+    // And it is the newest word: a proof still in flight from an earlier
+    // announce on this reach binds nothing when it lands, since the side
+    // has spoken again since.
+    const said = (announces.get(reach) ?? 0) + 1;
+    announces.set(reach, said);
     for (const [pk, b] of this.reaches) if (b.reach === reach && !pks.includes(pk)) this.reaches.delete(pk);
-    await Promise.all(pks.map(async (pk) => {
-      if (this.doors.has(pk) || !(await this.prove(pk, reach))) return;
+    const claimed = [...new Set(pks)].slice(0, ANNOUNCE);
+    const prove = async (pk: string) => {
+      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));
   }
   unbind(reach: Reach): void {
     for (const [pk, b] of this.reaches) if (b.reach === reach) this.reaches.delete(pk);
@@ -167,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);
@@ -175,12 +283,19 @@ export class Harbor {
   }
 
   // Stop serving a ward and take it out of the store: what was kept comes
-  // back, for another harbor to put. The partition is written first, because
-  // a being driven in-process changes it without passing a door.
+  // back, for another harbor to put. The partition is written first, and
+  // never again under this name: whoever still holds the old pointers holds
+  // a ward that saves nothing and answers its owner silence.
   async drop(name: string): Promise<Kept | undefined> {
     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
@@ -188,50 +303,92 @@ 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.
   async host(name: string, kept: Kept): Promise<Hosted> {
     const { seed, partition: memory } = kept;
     const classes = await this.loader(kept.record);
-    const objects = new Map<object, BeingLike>(); // cells -> the object instantiate made. a side's hand, never the ward's
+    const objects = new WeakMap<object, BeingLike>(); // cells -> the object instantiate made. a side's hand, never the ward's; it follows the cells out when she is unbooted
     const ground: Ground = {
       seed,
       memory,
-      instantiate: (className, stance) => {
-        const C = classes[className] ?? this.classes[className];
-        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 w = await Ward(ground);
-    const save = () => this.store.save(name, memory);
-    const after =
-      <A extends unknown[], R>(f: (...a: A) => Promise<R>) =>
-      async (...a: A): Promise<R> => {
-        try {
-          return await f(...a);
-        } finally {
-          await save();
-        }
-      };
-    const door = after(w.door);
-    const ask = after(w.ask);
-    const bp = (await w.ask()) as { notes: { pk: string } }; // learned by asking, as anyone learns anything
+    const saving: Saving = { memory, dirty: false, running: null, timer: undefined, gone: false };
+    this.#saving.set(name, saving);
+    // 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, 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;
+      await this.#flush(name);
+    };
+    const door = async (bytes: Uint8Array) => {
+      const r = await w.door(bytes);
+      // 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>) => {
+      if (saving.gone) return silence;
+      const out = await w.ask(method, args);
+      await save();
+      return out;
+    };
+    // 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

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0
-// A harbor as a dialer: one held socket to a listener's quo. route, its own
+// A harbor as a dialer: one held socket to a listener's URL, its own
 // pks announced, the listener's bound, and a reconnect with backoff from a
 // second to thirty when the line drops. Seed, partition and keys are here;
 // only the reach comes and goes. While the socket is open it is also the
@@ -12,22 +12,35 @@ 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 {
   const d: Dialer = { url, socket: null, wake: () => {}, close: () => {} };
   let stopped = false,
     wait = 1000,
-    timer: ReturnType<typeof setTimeout> | undefined;
+    timer: ReturnType<typeof setTimeout> | undefined,
+    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;
-    const line = new WebSocket(url.replace(/\/$/, '').replace(/^http/, 'ws')) as unknown as Line;
+    line = new WebSocket(url.replace(/\/$/, '').replace(/^http/, 'ws')) as unknown as Line;
     const s: Socket = new Socket(
       line,
       (pk, bytes) => harbor.deliver(pk, bytes),
@@ -40,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.
@@ -53,12 +69,23 @@ 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
     // the line already in hand, and a dropped one stops being claimed at once.
     const say = () => s.announce([...harbor.doors.keys()]);
     line.addEventListener('open', () => {
+      if (stopped) return s.close(); // closed while it was opening: it opens into nothing
       d.socket = s;
       harbor.announcers.add(say);
       say();
@@ -66,17 +93,19 @@ 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 = () => {
     stopped = true;
     clearTimeout(timer);
-    d.socket?.close();
+    line?.close(); // open or opening: a line closed while connecting fires close and never open
   };
   connect();
   return d;

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 Map<object, unknown>(); // cells -> being object. what instantiate constructed. a hand for tests, never the ward's
+  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,24 +54,19 @@ export class MemoryHarbor {
     const ground: Ground = {
       seed,
       memory,
-      instantiate: (name: string, stance: Stance) => {
-        const C = classes[name];
-        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;