nervur 0.18.0 → 0.19.0

package/src/harbor/core.ts

@@ -19,8 +19,8 @@
 // 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 { maker, entropy as random, learnPk, type Ground, type WardPointers, type Lend } from '../ward/ground.ts';
-import type { BeingClass, BeingLike } from '../being/types.ts';
+import { maker, entropy as random, learnPk, type Ground, type WardPointers } from '../ward/ground.ts';
+import type { BeingClass, BeingLike, Invitation } from '../being/types.ts';
 import { silence } from '../being/silence.ts';
 import { request, type Reach } from './reach.ts';
 import { isWardPk, openReply, wardSignPk } from '../ward/seal.ts';
@@ -149,22 +149,21 @@ export class Harbor {
     for (const say of this.announcers) say();
   }
 
-  // What this device lends the beings of the wards it hosts, by name. One
-  // for the harbor, and `lendFor` says which ward may ask it: every ward,
-  // unless a terrain says a stranger's ward is lent nothing.
-  // Set at birth or once the harbor's own ward is standing, which is the
-  // usual order: a terrain puts that ward up first, then boots the rest on a
-  // ground that can reach it.
-  lend: Lend | undefined;
+  // The box, as one invitation per ward: what this device hands a ward it
+  // boots so that the ward takes the box's being as a standing. Set once
+  // the harbor's own ward is standing, which is the usual order: a terrain
+  // puts that ward up first, then boots the rest on a ground that can reach
+  // it. A terrain says which ward is handed one by overriding `boxFor`, and
+  // a stranger's ward is handed none.
+  offering: ((name: string) => Promise<Invitation | undefined>) | undefined;
 
-  constructor(store: Store, loader: Loader = async () => ({}), lend?: Lend) {
+  constructor(store: Store, loader: Loader = async () => ({})) {
     this.store = store;
     this.loader = loader;
-    this.lend = lend;
   }
 
-  protected lendFor(_name: string, _record: WardRecord): Lend | undefined {
-    return this.lend;
+  protected boxFor(name: string, _record: WardRecord): Promise<Invitation | undefined> {
+    return this.offering?.(name) ?? Promise.resolve(undefined);
   }
 
   // Boot every ward the store keeps, and learn the hints. One ward that will
@@ -237,7 +236,7 @@ export class Harbor {
     const moved: string[] = [];
     for (const row of s.kept.keys()) {
       const was = s.kept.get(row);
-      const now = rowsOf(s.memory, [row])[0]![1];
+      const now = rowsOf(s.memory, [row])[0][1];
       if (JSON.stringify(was) === JSON.stringify(now)) continue;
       restoreRow(s.memory as unknown as Partition, row, was);
       moved.push(row);
@@ -283,7 +282,7 @@ export class Harbor {
   // rows where the store already has them.
   #settle(name: string, s: Saving): void {
     for (const [row, value] of s.under) {
-      const now = rowsOf(s.memory, [row])[0]![1];
+      const now = rowsOf(s.memory, [row])[0][1];
       if (JSON.stringify(value) === JSON.stringify(now)) s.kept.set(row, value);
       else s.dirty.add(row);
     }
@@ -546,13 +545,14 @@ export class Harbor {
     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,
       // 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,
-      wrote: (row) => this.#wrote(name, row),
+      memory: {
+        rows: memory,
+        told: (row) => this.#wrote(name, row),
       // What the ward wrote is in the store when this resolves, and it says
       // whether the store took it. The ward calls it at the end of every
       // arrival, before it seals, so a call through a pointer has already
@@ -566,7 +566,7 @@ export class Harbor {
       // A ward on its way out keeps nothing and refuses nothing: an arrival
       // racing an unhost is not a store saying no, and saying so would be a
       // lie in the one direction that matters.
-      keep: async () => {
+      kept: async () => {
         const s = this.#saving.get(name);
         if (!s || s.gone) return true;
         const ok = await this.#flush(name);
@@ -585,7 +585,7 @@ export class Harbor {
       // ward back. The ward is the one that knows, because a being reaching
       // another being of her own ward goes to that ward's door directly and
       // the harbor never sees that call at all.
-      calling: () => {
+      during: () => {
         const s = this.#saving.get(name);
         if (!s) return () => {};
         s.calls += 1;
@@ -603,9 +603,10 @@ export class Harbor {
           else this.#settle(name, s);
         };
       },
+      },
     };
-    const lend = this.lendFor(name, kept.record);
-    if (lend) ground.lend = lend;
+    const box = await this.boxFor(name, kept.record);
+    if (box) ground.box = box;
     // What the store holds for this ward at birth is what it was just handed
     // or just read, row by row. It is copied once here so that a being whose
     // very first write of this run is refused is put back too, rather than
@@ -633,7 +634,7 @@ export class Harbor {
     // here. It answers nothing, because a caller inside the process reads
     // the fault off the harbor and an arrival is the only thing that needs a
     // verdict of its own.
-    const save = async (): Promise<void> => void (await ground.keep?.());
+    const save = async (): Promise<void> => void (await ground.memory.kept());
     const door = (bytes: Uint8Array) => w.door(bytes);
     const ask = async (method?: string, args?: Record<string, unknown>) => {
       if (saving.gone) return silence;

package/src/harbor/index.ts

@@ -11,7 +11,10 @@ export { MemoryStore, values, rowsOf, type Store, type Kept, type WardRecord } f
 // a being, and the partition back from the rows it was cut into.
 export { HEAD, fromRows, rowsIn } from '../ward/partition.ts';
 export { request, Socket, SUITE, REFUSED, type Reach, type Carry, type Line, type Announce } from './reach.ts';
-export type { Ground, WardPointers, Lend } from '../ward/ground.ts';
+export type { Ground, WardPointers, Memory } from '../ward/ground.ts';
+export { BOX, OFFER, RETRACT, volatile } from '../ward/ground.ts';
+// The box as one being, and the acts a harbor runs to stand it.
+export { Box, BOX_SEED, BOX_ASKS, stand, hold, offerTo, roll } from './box.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,9 +4,17 @@
 // 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, BeingLike } from '../being/types.ts';
-import { maker, entropy, learnPk, type Ground, type WardPointers, type Lend } from '../ward/ground.ts';
+//
+// It works in acts, as every harbor does. `up` is act one: the box's own
+// ward on the plain ground, the box's being and the lent beings in it.
+// `host` is act two for one ward: on the roll, and handed one invitation
+// on the box's being. A
+// ward booted with `boot` alone is handed no box and lends nothing, which is
+// what a suite of the ward wants.
+import type { BeingClass, BeingLike, Invitation } from '../being/types.ts';
+import { maker, entropy, learnPk, volatile, type Ground, type WardPointers } from '../ward/ground.ts';
 import { hex } from '../ward/arithmetic.ts';
+import { Box, BOX_SEED, stand, offerTo, roll } from './box.ts';
 
 export type Booted = WardPointers & { pk: string };
 export type WardFactory = (ground: Ground) => Promise<WardPointers>;
@@ -47,22 +55,22 @@ export class MemoryHarbor {
     harbor.peers.add(this);
   }
 
-  // boot by seed. the harbor gets a door and an ask, and learns the pk by asking.
-  // `lend` is what this device lends the ward's beings, and a test's stand-in
-  // for a real terrain's: left out, every name answers null.
-  async boot(seed: string, Ward: WardFactory, classes: Record<string, BeingClass>, lend?: Lend): Promise<Booted> {
+  // boot by seed. the harbor gets a door and an ask, and learns the pk by
+  // asking. `box` is the invitation on this device's box being, for this
+  // ward: left out, the ward holds no box and every lend is null.
+  async boot(seed: string, Ward: WardFactory, classes: Record<string, BeingClass>, box?: Invitation): Promise<Booted> {
     this.partitions.set(seed, {});
-    return this.reboot(seed, Ward, classes, lend);
+    return this.reboot(seed, Ward, classes, box);
   }
 
   // a restart: same seed, same partition, fresh ward. the ward's files are the harbor's to keep.
-  async reboot(seed: string, Ward: WardFactory, classes: Record<string, BeingClass>, lend?: Lend): Promise<Booted> {
-    const memory = this.partitions.get(seed);
-    if (!memory) throw new Error(`no partition for ${seed}`);
+  async reboot(seed: string, Ward: WardFactory, classes: Record<string, BeingClass>, box?: Invitation): Promise<Booted> {
+    const rows = this.partitions.get(seed);
+    if (!rows) throw new Error(`no partition for ${seed}`);
     const ground: Ground = {
       seed,
-      memory,
-      ...(lend ? { lend } : {}),
+      memory: volatile(rows),
+      ...(box ? { box } : {}),
       // 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),
@@ -80,4 +88,36 @@ export class MemoryHarbor {
     this.wards.set(seed, booted);
     return booted;
   }
+
+  // Act one. The box's own ward, the box's being and the lent beings named,
+  // each booted under its name and held by her under it. Run again on a
+  // harbor whose box ward stands, it changes nothing.
+  async up(Ward: WardFactory, lent: Record<string, BeingClass> = {}): Promise<Booted> {
+    const classes: Record<string, BeingClass> = { Box };
+    for (const C of Object.values(lent)) classes[C.name] = C;
+    const box = this.wards.get(BOX_SEED) ?? (await this.boot(BOX_SEED, Ward, classes));
+    await stand(box, lent);
+    return box;
+  }
+
+  get box(): Booted | undefined {
+    return this.wards.get(BOX_SEED);
+  }
+
+  // Act two, one ward: on the roll and handed one invitation on the box's being.
+  // A harbor with no box ward up hosts as `boot` does, with nothing.
+  async host(seed: string, Ward: WardFactory, classes: Record<string, BeingClass>): Promise<Booted> {
+    const box = this.box;
+    const inv = box ? await offerTo(box, seed) : undefined;
+    return this.partitions.has(seed) ? this.reboot(seed, Ward, classes, inv) : this.boot(seed, Ward, classes, inv);
+  }
+
+  // Act two, whole: the box's being says who is hosted, and each comes up.
+  async hosted(Ward: WardFactory, classes: Record<string, BeingClass>): Promise<string[]> {
+    const box = this.box;
+    if (!box) return [];
+    const seeds = await roll(box);
+    for (const seed of seeds) await this.host(seed, Ward, classes);
+    return seeds;
+  }
 }

package/src/harbor/store.ts

@@ -46,7 +46,7 @@ export const values = (p: Record<string, unknown>): Record<string, unknown> => J
 export const rowsOf = (partition: Record<string, unknown>, rows: readonly string[]): [string, Record<string, unknown> | undefined][] =>
   rows.map((row) => {
     const value = rowOf(partition as unknown as Partition, row);
-    return [row, value === undefined ? undefined : (values(value) as Record<string, unknown>)];
+    return [row, value === undefined ? undefined : (values(value))];
   });
 
 // One store's copy, brought up to date with the rows it was told about.

package/src/vector/cases.ts

@@ -18,9 +18,10 @@
 import { Ward } from '../ward/ward.ts';
 import * as seal from '../ward/seal.ts';
 import { hex } from '../ward/arithmetic.ts';
+import { digest } from '../being/digest.ts';
 import type { Json, JsonObject } from '../being/types.ts';
 import type { Booted } from '../harbor/memory.ts';
-import { world, sealed, bound, secret, rnd, partitionDigest, Caller } from './world.ts';
+import { world, sealed, bound, secret, rnd, drawn, partitionDigest, Caller } from './world.ts';
 import type { World, Hand, Sealed } from './world.ts';
 
 export type DoorRecord = {
@@ -33,9 +34,9 @@ export type DoorRecord = {
   ask: string; // hex, exactly as the bytes arrive
   reply: string; // hex, exactly as they leave
   opens: Json | null; // what the reply opens to where the hand holds the lid's secret
-  before: string; // the partition's digest before the door judged
-  after: string; //  and after. equal is `nothing written`
-  wrote: boolean; // the two digests differ. a refusal never sets it
+  draws: number; // how many words of the stream were spent before the arrival
+  blueprint?: JsonObject; // the shape `seen` is the digest of, where a reply carries one
+  wrote: boolean; // the partition changed while the door judged. a refusal never sets it
 };
 
 // `pin` is where the case's own setup ends and the arrival begins. A record
@@ -50,21 +51,43 @@ export type Case = { case: string; name: string; state: string; ward: string; ar
 
 // Stand one case: its world, its setup, its ask. What comes back is enough
 // to knock, and enough for a verifier to check the hand before the door.
-export async function stand(c: Case): Promise<{ w: World; before: string; arrival: Arrival }> {
+export async function stand(c: Case): Promise<{ w: World; before: string; draws: number; arrival: Arrival }> {
   const w = await world();
   let before = await partitionDigest(w.b, c.ward);
   const arrival = await c.arrive(w, async () => {
     before = await partitionDigest(w.b, c.ward);
   });
-  return { w, before, arrival };
+  // Where the stream stands now, which is where the door is about to draw
+  // from. A kit that stood this case its own way sets its stream here.
+  return { w, before, draws: drawn(), arrival };
+}
+
+// The blueprint a reply's `seen` was taken over. The host is the only being
+// in this world whose shape reaches a stranger, and the asker is the id her
+// heir was opened for, so there is one blueprint to find and it is checked
+// against the digest before it is written down.
+async function shown(w: World, seen: string): Promise<JsonObject | undefined> {
+  for (const id of Object.keys(w.host.cells.occupants)) {
+    const bp = w.host.describe({ id }) as unknown as JsonObject;
+    if ((await digest(bp)) === seen) return bp;
+  }
+  return undefined;
 }
 
 async function record(c: Case): Promise<DoorRecord> {
-  const { w, before, arrival } = await stand(c);
+  const { w, before, draws, arrival } = await stand(c);
   const judged = await arrival.door.door(arrival.ask.bytes);
   const after = await partitionDigest(w.b, c.ward);
   const opens = arrival.ask.open ? ((await arrival.ask.open(judged.bytes)) as Json | null) : null;
-  return { case: c.case, name: c.name, state: c.state, ward: c.ward, kind: arrival.kind, heard: judged.heard, ask: hex(arrival.ask.bytes), reply: hex(judged.bytes), opens, before, after, wrote: before !== after };
+  // A reply that carries `seen` carries a being's shape on the wire, which is
+  // the one place in this corpus where what a being answers reaches a
+  // stranger. So the blueprint that digest is taken over is written down
+  // beside it: a kit stands a being that answers exactly this to the empty
+  // ask, and its door's bytes are these bytes. Every other record is the
+  // door alone and needs no being at all.
+  const seen = opens !== null && typeof opens === 'object' && !Array.isArray(opens) ? (opens).seen : undefined;
+  const blueprint = typeof seen === 'string' ? await shown(w, seen) : undefined;
+  return { case: c.case, name: c.name, state: c.state, ward: c.ward, kind: arrival.kind, heard: judged.heard, draws, ask: hex(arrival.ask.bytes), reply: hex(judged.bytes), opens, ...(blueprint ? { blueprint } : {}), wrote: before !== after };
 }
 
 // One after another and never at once: the cases share one stream, and two
@@ -142,10 +165,15 @@ export const cases: Case[] = [
     name: 'she is not there',
     state: 'the ward restarted without her class: her heirs stand and she does not',
     ward: 'B',
+    // Under the key she bound: the heir was spent by her knock and admits
+    // nothing now, so an arrival signed with its secret would be D6 and not
+    // this case. Her own key is what the door holds for her, and it is the
+    // key that hears the word.
     arrive: async (w, pin) => {
+      const b = await bound(w);
       const WB = await w.b.reboot('B', Ward, { Caller });
       await pin();
-      return at(WB, w.inv.heir!, 'word', { signer: secret(w.inv), next: 'a'.repeat(64) });
+      return at(WB, b.inv.heir!, 'word', { signer: b.own });
     },
   },
   {

package/src/vector/world.ts

@@ -8,7 +8,7 @@
 // Nothing here draws from the device. A door's reply is sealed under a fresh
 // ephemeral key and a fresh nonce, so the bytes are fixed only where the
 // entropy is, and every draw in this file comes from one written-down stream.
-// That is what lets `protocol/vectors/door.json` be a corpus and not a
+// That is what lets `quo/vectors/door.json` be a corpus and not a
 // sample, and what lets a kit stand in vector mode for a verifier that holds
 // no key: the spec's chapter of that name is the contract this file keeps.
 import { MemoryHarbor } from '../harbor/memory.ts';
@@ -23,10 +23,10 @@ import type { Answer, Asker, BeingClass, Blueprint, Invitation, Json, JsonObject
 
 // ---- the stream
 //
-// SplitMix64. Sixteen lines a kit in any language writes from this comment
-// alone: the state starts at the seed, every draw adds the golden gamma
-// 0x9e3779b97f4a7c15, mixes with two xor-shift-multiplies, and the sixty-four
-// bit result is spent eight bytes at a time, least significant first. It is
+// SplitMix64, written out in the spec's vector-mode chapter with both
+// multipliers and all three shifts, because a kit that reproduces it by
+// recognising it is a kit that guessed. This is that, and it moves only
+// when that does. It is
 // not a cipher and is not meant to be one. Its whole job is that the bytes
 // this file produces are the same bytes twice.
 const GAMMA = 0x9e3779b97f4a7c15n;
@@ -50,12 +50,23 @@ export function splitmix64(seed: bigint): () => Uint8Array {
 export const STREAM_SEED = 20250901n;
 
 let draw = splitmix64(STREAM_SEED);
+// How many sixty-four bit words have been spent since the stream was reset.
+// A record carries this number at the moment of its arrival, so a kit that
+// built the door's state its own way sets its stream here and draws what
+// this one would have drawn. It is the whole of what the setup's history is
+// worth to a stranger: not how the world was made, but where the stream
+// stands when the door is about to answer.
+let spent = 0;
+export const drawn = (): number => spent;
 // Entropy, from the stream and never from the device. Every signer secret,
 // every ephemeral seed, every byte of noise and every key a ward in this
 // world mints comes through here, in the order the code asks for it.
 export const rnd = (n = 32): Uint8Array => {
   const out = new Uint8Array(n);
-  for (let i = 0; i < n; i += 8) out.set(draw().subarray(0, Math.min(8, n - i)), i);
+  for (let i = 0; i < n; i += 8) {
+    out.set(draw().subarray(0, Math.min(8, n - i)), i);
+    spent += 1;
+  }
   return out;
 };
 
@@ -154,6 +165,7 @@ let counted = 1000;
 
 export async function world() {
   draw = splitmix64(STREAM_SEED); // a fresh world is a fresh stream: two runs, one corpus
+  spent = 0;
   counted = 1000;
   const a = new MemoryHarbor(),
     b = new MemoryHarbor();

package/src/ward/ground.ts

@@ -1,110 +1,99 @@
 // SPDX-License-Identifier: Apache-2.0
-// The ground. The one object a harbor passes a ward at birth: nine things
-// the ward uses. Everything a runtime differs on arrives here, which is why
-// the ward itself knows no runtime.
+// The ground. The one object a harbor passes a ward at birth, and the whole
+// of the device to it: six things, and everything a runtime differs on
+// arrives in one of them, which is why the ward itself knows no runtime.
+//
+//   seed         who the ward is. the pk derives from it and from nothing else
+//   random       entropy. every key the ward mints is drawn from it
+//   memory       what the ward remembers: one interface, a body per terrain
+//   instantiate  the dna: a class name and a stance in, a being or nothing out
+//   carry        the wire: a ward pk and sealed bytes in, sealed bytes or nothing out
+//   box          the device, as one invitation on the box's own being
+//
+// The spec lists nine things and says a kit gathers them however its
+// language gathers things. This kit gathers the partition, wrote, keep and
+// calling into memory, because they are one concern with four moments, and
+// a ward is handed one body and told how to use it rather than four calls
+// it must keep in step.
 import type { Stance, BeingLike, BeingClass, Invitation } from '../being/types.ts';
 
-// What the device lends this ward's beings, by name. What a box can do is
-// beings, in a ward its harbor booted and roots, and this is how a being of
-// another ward comes to hold a standing at one: the harbor asks its own root
-// to invite on that being, and hands the invitation to the taker.
+// Memory. Four moments, and they are the promise a body keeps:
+//
+//   rows    the values the ward holds and writes into directly. synchronous,
+//           always, because the door judges an arrival in one pass and a
+//           disk in the middle of it would be a door that waits on a device
+//   told    the ward says it after every write, naming the row: a being by
+//           her key, or `HEAD` for everything that is not one being's.
+//           nothing comes back. a body that keeps the rows saves in the
+//           order it was told, so a being driven in process is kept the way
+//           one reached through a door is
+//   kept    keep what has been written, now, and say whether it was. the
+//           ward asks it once at the end of an arrival, after the being has
+//           answered and before the answer is sealed, the last moment
+//           anything can still be said about it. false is a store that
+//           refused, and the ward says so with the word a failed ask already
+//           has: `threw` to an asker the door holds, silence to the ask
+//           pointer. never a reason
+//   during  a call of this ward's has begun, and what comes back lowers it.
+//           the ward raises it before it reaches out and lowers it in a
+//           finally, so a call that threw lowers too, and lowering twice is
+//           lowering once. calls nest. a body may go on writing while it is
+//           raised; what it may not do is take a save made there as the
+//           point it puts a refused ward back to
 //
-// The taker is the ward's half, and it is inside this call rather than after
-// it so that nothing half-lives. The harbor minted, so the harbor is the only
-// one who can unmint: a ward that could not knock, or could not take, says so
-// by answering false, and the root that minted removes the occupant it made.
-// A lend that failed leaves no heir open at that being and no relation bound
-// to a ward that does not hold it, which is the promise `boot` keeps with
-// `unmake` and the same promise here.
+// A body that keeps nothing has rows, is told and does nothing, answers yes,
+// and raises nothing: `volatile` below. The ward has one path either way.
+export type Memory = {
+  readonly rows: Record<string, unknown>;
+  told(row: string): void;
+  kept(): Promise<boolean>;
+  during(): () => void;
+};
+
+// The body that keeps nothing: the process is the memory.
+export const volatile = (rows: Record<string, unknown> = {}): Memory => ({ rows, told: () => {}, kept: () => Promise.resolve(true), during: () => () => {} });
+
+// The device is one standing. What a box can do is beings, in a ward its
+// harbor booted and roots, and one being there, the box's own, holds a
+// standing at each of them under the name it is lent as. The ground carries
+// one invitation on her, minted for this ward alone; the ward takes it at
+// boot under `BOX`, as its own first being, and from then on the device is
+// reached the way anything is reached: what it offers is her describe, and a
+// lend is the ask `OFFER` on that standing, naming what a being wants.
 //
-// False is every kind of no, and they are one answer because a being would do
-// nothing different for any of them: this harbor lends nothing, or nothing of
-// that name, or nothing of that name to this ward, or the ward did not take
-// what was minted.
+// She answers the lent being's own invitation, minted by that being on herself,
+// and the ward knocks and takes it in the being's name. No root mints for a
+// lend, and the invitation never reaches the being: it is the device's, a
+// value she could copy is one she could hand to anyone, so the ward holds
+// it and hands her the id. Which ward may have which name is the box's own
+// gate, reading who asks, and a stranger's ward holds no standing at her.
 //
-// The invitation never reaches the being. It is the device's capability, and
-// a value she could copy is one she could hand to anyone, so it lives in this
-// call and nowhere else.
-export type Lend = (name: string, take: (invitation: Invitation) => Promise<boolean>) => Promise<boolean>;
+// A harbor with no box leaves it out, and every lend is null. A ward that
+// could not take it at boot, the box down or the invitation spent, boots all
+// the same, lends nothing this run, and tries again at the next.
+export { BOX } from '../being/lent.ts';
+export const OFFER = 'offer';
+// A lend that was offered and not taken leaves nothing: the ward says so to
+// the box, naming the heir, and the lent being removes what she minted.
+export const RETRACT = 'retract';
 
 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, and which row of it: a being by her key,
-  // or `HEAD` for everything that is not one being's. It says so after every
-  // write, a key rotated, a relation taken, a cell she set, and says nothing
-  // else: this word is told, never asked, and nothing comes back from it. A
-  // harbor that keeps the partition saves in the order it was told, so a
-  // being driven in process is kept the way one reached through a door is.
-  // Whether any of it was kept is one question asked once, at the end of an
-  // arrival, and `keep` is where. A harbor that keeps nothing leaves both
-  // out.
-  //
-  // The row is named because a being's cells are the one part of a partition
-  // that grows without limit, and a harbor told only that something moved has
-  // to write down every being in the ward to be sure of one. What a harbor
-  // does with the name is its own: writing the whole partition on every word
-  // is correct, and slower.
-  wrote?: (row: string) => void;
-  // Keep what has been written, now, and say whether it was kept. The ward
-  // calls it once at the end of an arrival, after the being has answered and
-  // before the answer is sealed, which is the last moment anything can still
-  // be said about it: a reply sealed to an asker's lid cannot be unsaid, and
-  // only the ward can seal.
-  //
-  // False is a store that refused, and the ward says so with the word a
-  // failed ask already has: `threw` to an asker the door holds, silence to
-  // the ask pointer and to a stranger. It is never a reason; a full disk is
-  // no more the far side's business than any other insides of this device.
-  //
-  // A harbor that keeps nothing leaves it out, and so does one that would
-  // rather count a refusal than answer it: absent means the ward asks
-  // nothing and seals what the being said, which is what every harbor did
-  // before this existed. A harbor that writes it saves here and nowhere
-  // else for this arrival, since `wrote` has already named every row.
-  keep?: () => Promise<boolean>;
-  // A call of this ward's has begun, and what comes back says it has ended.
-  // The ward alone knows where a call begins: a being reaching another being,
-  // in this process or over the wire, is one relation and two halves, and she
-  // writes her side of it before the bytes go out and again when they come
-  // back. Between those two writes her rows are half done, and a harbor that
-  // wrote them and then had to put them back would stand the ward at a point
-  // no call ever stood at.
-  //
-  // It is told, and the one thing that comes back is how to lower it. The
-  // ward raises it before it reaches out and lowers it in a finally, so a
-  // call that threw lowers too, and lowering twice is lowering once. Calls
-  // nest: a ward is in flight while any of its beings is.
-  //
-  // A harbor is free to keep writing while it is raised, because the store is
-  // what survives a restart. What it may not do is take a save made there as
-  // the point it puts a refused ward back to. A harbor that keeps nothing
-  // leaves it out.
-  calling?: () => () => void;
+  seed: string | Uint8Array;
+  random(n: number): Uint8Array;
+  memory: Memory;
+  instantiate(className: string, stance: Stance): BeingLike | null;
   // 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
   // delivered. The ward hands it to a being as unreached, which is the one
   // answer that says asking again is safe, so a harbor may only return it
   // when it knows the bytes never arrived: no reach for that pk, a socket
-  // that would not open, a link that is down.
-  //
-  // A harbor that sent the bytes and then gave up waiting knows no such
-  // thing: the far door may have heard and be working still. It must not
-  // answer at all in that case. The ward bounds every ask itself, and an
-  // answer that never comes inside that bound is `late`, which promises
-  // nothing either way. So a harbor may hold a shorter patience than the
-  // ward's for its own reasons, a socket it wants back or a queue it will
-  // not grow, and the two bounds never need to read each other: whichever
-  // ends first ends the ask, and each says only what it can honestly say.
+  // that would not open, a link that is down. A harbor that sent the bytes
+  // and then gave up waiting knows no such thing and must not answer at all:
+  // the ward bounds every ask itself, and an answer that never comes inside
+  // that bound is `late`, which promises nothing either way.
   carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | undefined>;
-  random(n: number): Uint8Array; // entropy. every key a ward mints is drawn from it
-  // A standing at one of the harbor's own beings, by the name that harbor
-  // knows it under. Built per ward, so which ward may ask for which name is
-  // the harbor's own decision and a stranger's ward is lent nothing. A harbor
-  // with nothing to lend leaves it out, and every name answers false.
-  lend?: Lend;
+  box?: Invitation;
 };
 
 // What a ward hands back. Two pointers. The door answers bytes, always, and
@@ -117,11 +106,8 @@ export type WardPointers = {
   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 protocol 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.
+// ---- what every harbor builds a ground out of. Convenience, never contract:
+// a second kit writes its own harbor and may write these again.
 
 // 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
@@ -140,18 +126,14 @@ export const maker =
     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.
+// Entropy, from the one place every terrain that runs Quo has it.
 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.
+// derivation to keep in step with the first.
 export async function learnPk(w: WardPointers): Promise<string> {
   const notes = (await w.ask()) as { notes?: { pk?: unknown } } | null;
   const pk = notes?.notes?.pk;

package/src/ward/heirs.ts

@@ -7,8 +7,10 @@
 import type { DoorWord } from '../being/types.ts';
 import { GONE, type Heir, type Partition } from './partition.ts';
 
-// How wide the span is, is the ward's own — wider is more forgiving of a
-// rough road, and no peer can tell the difference except by being refused.
+// How wide the span is, is the spec's and never a ward's. Wider is more
+// forgiving of a rough road, and that is exactly why it is not a ward's to
+// choose: a peer tells two doors apart by being refused at one and answered
+// at the other, which is one relation dying over one number.
 const SPAN = 64;
 
 export class Heirs {