@quo-systems/quo 0.2.9 → 0.2.11

package/src/harbor/reach.ts

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // Reach: carrying bytes to a pk off the device. One interface, two
-// implementations, as quo-harbor.md names them:
+// implementations:
 //
-//   request   a URL, the quo. route of a world. POST the bytes to
-//             `<url>/<pk>`, get bytes back. Listener to listener.
+//   request   a URL. POST the bytes to `<url>/<pk>`, get bytes back.
+//             Listener to listener.
 //   socket    a held WebSocket at `<url>`, opened by whichever side can
 //             dial, used in both directions with a frame id. Each side
 //             announces the ward pks it holds when the socket opens, and the
@@ -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,12 +33,22 @@ 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
       }
-      if (res.status === 404) return undefined; // the listener holds no reach for that pk
+      // A status that says the listener did not take the bytes is nothing
+      // delivered: no reach for that pk, a request it refused on its face, a
+      // gateway with nobody behind it. Any other failure is a listener that
+      // took them and failed after, which is sent and no word since.
+      if (res.status === 404 || (res.status >= 400 && res.status < 500) || res.status === 502 || res.status === 503 || res.status === 504) return undefined;
       if (!res.ok) return never();
       return new Uint8Array(await res.arrayBuffer());
     },
@@ -75,6 +85,11 @@ export const SUITE = 1;
 // the refusal names itself on the way out, and the far side may read it.
 export const REFUSED = 4001;
 const OPEN = 1; // WebSocket.OPEN, on every terrain
+// How many asks a socket keeps a resolver for. An ask the far side never
+// answers is ended by the ward's bound, and its resolver stays until the
+// line closes; a far side that answers nothing for long enough would grow
+// the map for as long as this side asks, so the oldest goes when it is full.
+const PENDING = 4096;
 
 // The standard surface, and no more of it: what a browser WebSocket, Node's
 // WebSocket and a `ws` server socket all have.
@@ -106,7 +121,17 @@ export class Socket implements Reach {
   constructor(line: Line, deliver: Carry, onAnnounce: Announce, onClose: (why: { code?: number; reason?: string }) => void) {
     this.line = line;
     line.binaryType = 'arraybuffer';
-    this.#open = line.readyState === OPEN ? Promise.resolve() : new Promise((ok, no) => (line.addEventListener('open', ok), line.addEventListener('error', no)));
+    // A line that opens is a reach; one that errors, or closes before it
+    // opened, is a reach that failed, and an ask waiting on the handshake is
+    // nothing delivered.
+    this.#open =
+      line.readyState === OPEN
+        ? Promise.resolve()
+        : new Promise((ok, no) => {
+            line.addEventListener('open', ok);
+            line.addEventListener('error', no);
+            line.addEventListener('close', () => no(new Error('closed before it opened')));
+          });
     this.#open.catch(() => {}); // a handshake refused is a reach that failed, not a process that dies
     line.addEventListener('message', (e) => {
       if (typeof e.data === 'string') {
@@ -133,12 +158,19 @@ export class Socket implements Reach {
         id = new DataView(buf.buffer, buf.byteOffset, buf.byteLength).getUint32(1);
       if (kind === ASK) {
         const pk = hex(buf.subarray(5, 69));
-        void deliver(pk, new Uint8Array(buf.subarray(69))).then((back) => {
-          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));
-        });
+        // A deliver that rejects has delivered nothing this side can vouch
+        // for, and a listener does not die of it: the far side hears none.
+        void deliver(pk, new Uint8Array(buf.subarray(69)))
+          .then(
+            (back) => back,
+            () => undefined,
+          )
+          .then((back) => {
+            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]));
+          });
         return;
       }
       const waiting = this.pending.get(id);
@@ -171,8 +203,9 @@ export class Socket implements Reach {
     new DataView(head.buffer).setUint32(1, id);
     head.set(unhex(pk), 5);
     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]));
     });
   }
 
@@ -180,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

@@ -5,7 +5,7 @@
 // is held to the ward's ceiling. The door reads it before anything is done
 // under it and refuses a budget already gone, as one silence like every other
 // refusal there. The sender bounds the whole of her ask to the same number,
-// and a wait that ran out is silence, never unreached.
+// and a wait that ran out is the word late, never silence and never unreached.
 //
 // Each ask is bounded on its own. The time an arriving call has left does not
 // bound the asks a being makes while answering it: attributing her onward ask
@@ -33,12 +33,23 @@ export const CEILING: Allowance = { time: 300_000 };
 // is thirty seconds, silently, because the ceiling is not hers to know.
 // Asking for nothing at all is the default, which is the whole point.
 export function allow(wanted: Wanted | undefined, ceiling: Allowance = CEILING, base: Allowance = DEFAULT): Allowance {
-  const whole = (n: unknown, fallback: number) => (typeof n === 'number' && Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback);
+  // Floored first, then tested: a fraction of a millisecond is not a budget,
+  // and falls to the default like every other number that is not a positive
+  // whole one.
+  const whole = (n: unknown, fallback: number) => {
+    const w = typeof n === 'number' ? Math.floor(n) : NaN;
+    return Number.isFinite(w) && w > 0 ? w : fallback;
+  };
   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

@@ -8,7 +8,6 @@
 // runs on. `test/floor.test.ts` names the floor and probes for it. Subtle is
 // asynchronous, so everything here is.
 //
-// Ported from an earlier kit's arithmetic. Same bytes, same vectors.
 // `crypto.subtle` is read at every use and never captured at load. A browser
 // on a plain http:// origin has `crypto` without `subtle`, and a terrain may
 // install one after this module is first imported; a reference taken here
@@ -24,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');
@@ -59,7 +58,12 @@ export function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
   return diff === 0;
 }
 
-// The eight small-order points. A public key among them verifies nothing.
+// The eight small-order points of Ed25519, in their canonical encoding. A
+// public key among them verifies nothing. An encoding whose y coordinate is
+// not reduced, y at or above the field's prime p, names one of the same
+// points under another spelling, and a terrain's verify may accept a zero
+// signature under it; the field has room for the spelling, so it is refused
+// before the list is read.
 const SMALL_ORDER = [
   '0100000000000000000000000000000000000000000000000000000000000000',
   'ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
@@ -70,7 +74,11 @@ const SMALL_ORDER = [
   '26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc85',
   'c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac03fa',
 ].map(unhex);
-export const smallOrder = (pk: Uint8Array): boolean => SMALL_ORDER.some((p) => sameBytes(p, pk));
+// y >= p, read little-endian with the sign bit masked off: the top byte is
+// 0x7f under the mask, every middle byte is 0xff, and the low byte is at
+// least 0xed, which is p's.
+const unreduced = (pk: Uint8Array): boolean => (pk[31] & 0x7f) === 0x7f && pk[0] >= 0xed && pk.subarray(1, 31).every((b) => b === 0xff);
+export const smallOrder = (pk: Uint8Array): boolean => unreduced(pk) || SMALL_ORDER.some((p) => sameBytes(p, pk));
 
 const key32 = (value: Uint8Array, what: string): Uint8Array => {
   if (!(value instanceof Uint8Array) || value.length !== KEY) throw new Error(`${what} is not a 32-byte key`);
@@ -127,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/cells.ts

@@ -3,12 +3,12 @@
 // persist a being's cells as it likes: as this process's objects, as a row, as
 // a line of JSON on a disk. That promise is only worth what the cells honour.
 //
-// Nothing checked it. A being could write a Map, a Date, an undefined, a NaN.
-// In a memory harbor the object survives, because there is nowhere for it to
-// go and come back from. Through any harbor that keeps values it silently
-// becomes {}, or a string, or absent, or null — and she is never told which
-// harbor she is standing in. That is the memory harbor lying to her, which is
-// the one thing it must never do.
+// Unchecked, a being could write a Map, a Date, an undefined, a NaN. In a
+// memory harbor the object would survive, because there is nowhere for it to
+// go and come back from. Through any harbor that keeps values it would
+// silently become {}, or a string, or absent, or null, and she is never told
+// which harbor she is standing in. That would be the memory harbor lying to
+// her, which is the one thing it must never do.
 //
 // So the cells refuse the write. Loud, where she wrote it, in her own frame:
 // a being holds three answers and a throw is not one of them, so this throw
@@ -17,18 +17,27 @@
 // that a harbor would have to lie about later.
 import type { Cells, Json } from '../being/types.ts';
 
+// How deep a value may nest. Every walk over a value in the kit recurses,
+// and a peer chooses the depth of what she answers; a bound keeps a hostile
+// reply from ending a walk in a stack overflow instead of a refusal.
+export const DEPTH = 64;
+
 // I-JSON, all the way down. A number that JSON cannot write is not a number
-// a harbor can keep, and a key on the prototype is not a key she wrote.
-function fault(v: unknown, path: string, seen: Set<object>): string | null {
+// a harbor can keep, a key on the prototype is not a key she wrote, and a
+// hole in a list, or a key named `__proto__`, is a thing JSON writes one way
+// and a runtime reads another.
+function fault(v: unknown, path: string, seen: Set<object>, depth: number): string | null {
   if (v === null || typeof v === 'boolean' || typeof v === 'string') return null;
   if (typeof v === 'number') return Number.isFinite(v) ? null : `${path} is ${String(v)}, which no harbor can write down`;
   if (typeof v !== 'object') return `${path} is a ${typeof v}, which is not a value`;
   if (seen.has(v)) return `${path} refers back to itself`;
+  if (depth >= DEPTH) return `${path} is nested past ${DEPTH} levels, which no harbor can keep`;
   seen.add(v);
   try {
     if (Array.isArray(v)) {
       for (let i = 0; i < v.length; i += 1) {
-        const f = fault(v[i], `${path}[${i}]`, seen);
+        if (!(i in v)) return `${path}[${i}] is a hole, which no harbor can write down`;
+        const f = fault(v[i], `${path}[${i}]`, seen, depth + 1);
         if (f) return f;
       }
       return null;
@@ -36,7 +45,8 @@ function fault(v: unknown, path: string, seen: Set<object>): string | null {
     const proto = Object.getPrototypeOf(v);
     if (proto !== Object.prototype && proto !== null) return `${path} is a ${(v).constructor?.name ?? 'object'}, which is not a value`;
     for (const k of Object.keys(v)) {
-      const f = fault((v as Record<string, unknown>)[k], `${path}.${k}`, seen);
+      if (k === '__proto__') return `${path}.__proto__ is a key no harbor can keep`;
+      const f = fault((v as Record<string, unknown>)[k], `${path}.${k}`, seen, depth + 1);
       if (f) return f;
     }
     return null;
@@ -45,16 +55,43 @@ function fault(v: unknown, path: string, seen: Set<object>): string | null {
   }
 }
 
-export const cellFault = (v: unknown, path: string): string | null => fault(v, path, new Set());
+export const cellFault = (v: unknown, path: string): string | null => fault(v, path, new Set(), 0);
+
+// The three keys at the root of her cells that are the ward's: it writes
+// them, she reads them, and a write of hers there is refused like a non-value.
+const WARDS = new Set(['standings', 'occupants', 'class']);
 
 // The guard is one proxy at the root and one for every container read through
 // it, so a write nested three deep is refused the same way a write at the top
 // is. Wrappers are remembered, so reading the same array twice is the same
 // object twice and a being may still compare what she holds.
 const wrapped = new WeakMap<object, object>();
+const targets = new WeakMap<object, object>();
 const guards = new WeakSet();
 
-function guard<T extends object>(target: T, path: string): T {
+// A key a write may land on: a string that is not `__proto__`, and not one
+// of the ward's at the root. A symbol key is a thing JSON never writes.
+const refuse: (why: string) => never = (why) => {
+  throw new TypeError(`cells hold values: ${why}`);
+};
+function keyFault(t: object, k: string | symbol, v: unknown, path: string, root: boolean): void {
+  if (typeof k !== 'string') refuse(`${path} takes no symbol key`);
+  if (k === '__proto__') refuse(`${path}.__proto__ is a key no harbor can keep`);
+  if (root && WARDS.has(k)) refuse(`${path}.${k} is the ward's to write`);
+  // A list grows by one at its end, or it has holes JSON cannot write. A
+  // push sets the slot at its length and then the length: both pass. A
+  // length set past what she wrote, or a slot beyond it, would leave holes.
+  if (Array.isArray(t)) {
+    if (k === 'length') {
+      if (typeof v !== 'number' || v > t.length) refuse(`${path}.length set past what she wrote would leave holes`);
+      return;
+    }
+    const i = Number(k);
+    if (Number.isInteger(i) && i > t.length) refuse(`${path}[${i}] would leave a hole`);
+  }
+}
+
+function guard<T extends object>(target: T, path: string, wrote: () => void, root = false): T {
   if (guards.has(target)) return target;
   const had = wrapped.get(target);
   if (had) return had as T;
@@ -62,29 +99,43 @@ function guard<T extends object>(target: T, path: string): T {
     get(t, k, r) {
       const v = Reflect.get(t, k, r);
       // A container reached through her cells is part of her cells.
-      return v !== null && typeof v === 'object' && !ArrayBuffer.isView(v) ? guard(v as object, `${path}.${String(k)}`) : v;
+      return v !== null && typeof v === 'object' && !ArrayBuffer.isView(v) ? guard(v as object, `${path}.${String(k)}`, wrote) : v;
     },
     set(t, k, v, r) {
-      if (typeof k === 'string') {
-        const f = cellFault(v, `${path}.${k}`);
-        if (f) throw new TypeError(`cells hold values: ${f}`);
-      }
-      return Reflect.set(t, k, v, r);
+      keyFault(t, k, v, path, root);
+      const f = cellFault(v, `${path}.${String(k)}`);
+      if (f) refuse(f);
+      const ok = Reflect.set(t, k, v, r);
+      wrote();
+      return ok;
     },
     defineProperty(t, k, d) {
-      if (typeof k === 'string' && 'value' in d) {
-        const f = cellFault(d.value, `${path}.${k}`);
-        if (f) throw new TypeError(`cells hold values: ${f}`);
-      }
-      return Reflect.defineProperty(t, k, d);
+      if (!('value' in d)) refuse(`${path}.${String(k)} is an accessor, which no harbor can keep`);
+      keyFault(t, k, d.value, path, root);
+      const f = cellFault(d.value, `${path}.${String(k)}`);
+      if (f) refuse(f);
+      const ok = Reflect.defineProperty(t, k, d);
+      wrote();
+      return ok;
+    },
+    deleteProperty(t, k) {
+      if (root && typeof k === 'string' && WARDS.has(k)) refuse(`${path}.${k} is the ward's to keep`);
+      const ok = Reflect.deleteProperty(t, k);
+      wrote();
+      return ok;
     },
   });
   wrapped.set(target, p);
+  targets.set(p, target);
   guards.add(p);
   return p;
 }
 
 // Her cells, guarded. Called once per being at boot; the guarded object is
 // what goes into the partition and what the stance hands her, so there is no
-// second door onto the same cells.
-export const guardCells = (cells: Cells): Cells => guard(cells as unknown as Record<string, Json>, 'cells') as unknown as Cells;
+// second door onto the same cells. Every write that passes says so to the
+// ward, which says so to its harbor.
+export const guardCells = (cells: Cells, wrote: () => void = () => {}): Cells => guard(cells as unknown as Record<string, Json>, 'cells', wrote, true) as unknown as Cells;
+// The cells behind the guard, for the ward alone: the one writer of the
+// three keys that are its own.
+export const unguarded = (cells: Cells): Cells => (targets.get(cells as unknown as object) ?? cells) as Cells;

package/src/ward/door.ts

@@ -9,14 +9,15 @@
 // 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';
 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 });
@@ -37,13 +38,21 @@ export async function arrive(door: Door, asker: Asker, method: string | undefine
   // on the way out and the far side reads back as a fourth word.
   if (out === undefined || isSilence(out)) return SILENCE;
   if (isWord(out)) return threw; // a word is the ward's to say, never hers
+  // Her answer is held to the rule her args and her cells are held to. A
+  // shape JSON would drop or rewrite on the way out, a Date, a Map, a NaN, a
+  // cycle, is not hers to make: the far side would read something she never
+  // said, or the door itself would fail to write her reply after the number
+  // was spent. It is threw, like a word out of her.
+  if (cellFault(out, 'answer') !== null) return threw;
   if (method === undefined) return { object: out, seen: null };
   // The digest rides along, it is not the answer. She has already answered:
   // a describe that will not run costs the digest, and nothing else.
   return { object: out, seen: await seen(door, asker) };
 }
 
-async function seen(door: Door, asker: Asker): Promise<string | null> {
+// Her digest for this asker, or null when her describe threw or fell silent.
+// The owner's describe reads it the same way for every being of the ward.
+export async function seen(door: Door, asker: Asker): Promise<string | null> {
   try {
     const bp = await door.being.answer(asker);
     return isSilence(bp) || isWord(bp) ? null : await digest(bp);
@@ -60,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) {
@@ -72,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) {
@@ -83,6 +96,12 @@ export function makeDoor(key: WardKey, heirs: Heirs, doors: Map<string, Door>, p
       return { reply: said('removed'), ephemeralPk, heard: true };
     }
     if (!(await verifyAsk(a, payload.by))) return refuse(); // D7, under an admitted key
+    // The signature took time, and another arrival on this heir may have been
+    // honoured meanwhile: a knock that raced this one and won spent the heir,
+    // and the key this ask speaks under may not be admitted any more. The
+    // door judges concurrently, so admission is read again now that writing
+    // is next, and what changed under the await is judged as it stands.
+    if (!heirs.admits(to, payload.by)) return heirs.gone(to, payload.by) ? { reply: said('removed'), ephemeralPk, heard: true } : refuse();
     // From here the door has heard a key it holds. Every answer below is
     // sealed to that key's lid; nothing below is a stranger's.
     const door = doors.get(h.being);
@@ -100,17 +119,24 @@ export function makeDoor(key: WardKey, heirs: Heirs, doors: Map<string, Door>, p
   // reply is sealed to the ephemeral pk on its lid, which is all a stranger
   // holds, and says silence.
   //
-  // A lid that is not a key -- a small-order point, of which the two curves
-  // have several each -- makes a dead agreement, and the seal refuses it. The
-  // door never throws: that reply is noise, sealed to a key nobody holds.
+  // A lid that is not a key, a small-order point, of which the two curves
+  // have several each, makes a dead agreement, and the seal refuses it. The
+  // 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 {
       return { bytes: await sealReply(reply, out?.ephemeralPk ?? lid(bytes, random), key.sign, random(32)), heard };
     } catch {
-      return { bytes: await sealReply(reply, (await sealingPair(random(32))).pk, key.sign, random(32)), heard };
+      return { bytes: await sealReply(SILENCE, (await sealingPair(random(32))).pk, key.sign, random(32)), heard };
     }
   };
 }

package/src/ward/ground.ts

@@ -1,13 +1,20 @@
 // SPDX-License-Identifier: Apache-2.0
-// The ground. The one object a harbor passes a ward at birth. Five things,
-// never a sixth. Everything a runtime differs on arrives here, which is
+// 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
   memory: Record<string, unknown>; // the partition. the ward's files. opaque to the harbor
   instantiate(className: string, stance: Stance): BeingLike | null; // the code half
+  // The ward wrote its partition. It says so after every write, a key
+  // rotated, a relation taken, a cell she set, and says nothing else: it
+  // never learns whether anything was kept. A harbor that keeps the
+  // partition saves after this, when it likes and in the order it was told,
+  // so a being driven in process is kept the way one reached through a door
+  // is. A harbor that keeps nothing leaves it out.
+  wrote?: () => void;
   // Sealed bytes to a ward pk. What comes back, or undefined.
   //
   // undefined is a promise, not a shrug: no door was reached, and nothing was
@@ -37,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;
+}