@quo-systems/quo 0.1.0

package/src/conformance/index.ts

@@ -0,0 +1,516 @@
+// SPDX-License-Identifier: Apache-2.0
+// The ward conformance suite. The beings are fixed; the ward is under test.
+//
+// A ward is handed in as a probe:
+//
+//   make()                                       -> world
+//   world.boot(key, Class, cells?, { isPublic })  -> handle
+//   world.heir(invitation)                        -> { current, announced, fresh } | undefined
+//                                                    what the inviting ward holds for that heir
+//   world.oneWard                                 true when every being shares one ward
+//   handle.pk                                     the ward pk she lives behind
+//   handle.being                                  the object, as the test drives it
+//   handle.cells                                  her cells, as the ward keeps them
+//   handle.down = true | false                    her door is unreachable (needs canDown)
+//   handle.minted.has(pk)                         every pk her side ever minted
+//   handle.forgeKnock(invitation)                 make her side knock with a key of its own, unannounced
+//   world.census()                                every partition in the world, as values
+//   world.migrate(key)                            her ward moves to another harbor, same seed, same pk
+//
+// Every assertion here is the truth's. Nothing here knows how a ward is built.
+import { assert } from './assert.ts';
+import { silence, isSilence, isUnreached } from '../being/silence.ts';
+import { digest } from '../being/digest.ts';
+import type { Asker, BeingClass, Cells, Invitation, Json, JsonObject } from '../being/types.ts';
+import { Printer, Shop, Customer, Echo, Member } from './beings.ts';
+import { estate } from './estate.ts';
+
+export type Handle<B = unknown> = {
+  pk: string;
+  being: B;
+  cells: Cells;
+  down: boolean;
+  minted: { has(pk: string): boolean };
+  forgeKnock(inv: Invitation): void;
+};
+export type HeirView = { current: string; announced: string | null; fresh: boolean };
+
+// The whole world's bookkeeping, as values. What a ward keeps, read the way
+// an auditor reads it: the estate chapter holds it to being a graph, and the
+// secrets are here so that it can prove they are nowhere else.
+export type Census = {
+  wards: Record<string, { beings: string[]; public: string | null; heirs: Record<string, { being: string; id: string; current: string; announced: string | null; fresh: boolean; mark: number; spent: number[] }> }>;
+  binds: Record<string, { ward: string; standings: Record<string, { ward: string; heir: string | null; seq: number }>; occupants: Record<string, string>; knocks: string[]; answered: string[]; minted: string[]; secrets: string[] }>;
+  cells: Record<string, Cells>;
+};
+export type World = {
+  oneWard?: boolean;
+  boot<B>(key: string, Class: BeingClass, cells?: JsonObject, opts?: { isPublic?: boolean }): Promise<Handle<B>>;
+  heir(inv: Invitation): HeirView | undefined;
+  census(): Census;
+  migrate(key: string): Promise<void>;
+};
+
+export { Printer, Shop, Customer, Echo, Member };
+
+const HEX64 = /^[0-9a-f]{64}$/;
+
+// The runner is handed in. Node passes `node:test`; a browser and an edge
+// worker pass a shim of their own. The suite is the ward's truth, and the
+// ward's truth must be checkable wherever a ward runs, not only here.
+export type Runner = (name: string, opts: { skip?: string | false }, fn: () => Promise<void> | void) => void;
+
+export function conform(label: string, make: () => Promise<World>, { canDown = true, test }: { canDown?: boolean; test: Runner }) {
+  const t = (name: string, fn: () => Promise<void> | void) => test(`[${label}] ${name}`, {}, fn);
+  const down = (name: string, fn: () => Promise<void> | void) => test(`[${label}] ${name}`, { skip: !canDown && 'nothing to cut inside one ward' }, fn);
+
+  async function world({ printerInvitesShop = true } = {}) {
+    const w = await make();
+    const printer = await w.boot<Printer>('P', Printer);
+    const shop = await w.boot<Shop>('S', Shop);
+    const alice = await w.boot<Customer>('A', Customer);
+    const bob = await w.boot<Customer>('B', Customer);
+    if (printerInvitesShop) await shop.being.keepPrinter((await printer.being.invite('shop'))!);
+    return { w, printer, shop, alice, bob };
+  }
+  const bp = (x: unknown) => x as { asks: { name: string }[] };
+
+  // ---- invite
+
+  t('invite mints the occupant and a heir: the invitation is the far ward pk, the heir pk, and the heir secret. nothing of her.', async () => {
+    const { w, shop } = await world();
+    const inv = await shop.being.invite('gold');
+    assert.deepEqual(Object.keys(shop.cells.occupants), ['cust1']);
+    assert.deepEqual(Object.keys(inv).sort(), ['heir', 'secret', 'ward']);
+    assert.match(inv.ward, /^[0-9a-f]{128}$/);
+    assert.match(inv.heir!, HEX64);
+    assert.match(inv.secret!, HEX64);
+    assert.equal(inv.ward, shop.pk);
+    assert.ok(shop.minted.has(inv.heir!)); // rotation one: her ward minted the occupant's first key
+    assert.deepEqual(w.heir(inv), { current: inv.heir, announced: null, fresh: true }); // and keeps only its pk
+    for (const word of [inv.heir!, inv.secret!]) assert.ok(!JSON.stringify(shop.cells).includes(word)); // never in her cells
+  });
+
+  t('two invites, two heirs, nothing shared', async () => {
+    const { shop } = await world();
+    const i1 = await shop.being.invite();
+    const i2 = await shop.being.invite();
+    assert.notEqual(i1.heir, i2.heir);
+    assert.notEqual(i1.secret, i2.secret);
+    assert.equal(i1.ward, i2.ward);
+  });
+
+  t('remove before any knock: the heir is forgotten, a knock on it is silence', async () => {
+    const { w, shop, alice } = await world();
+    const inv = await shop.being.invite();
+    shop.being.occupants.remove('cust1');
+    assert.equal(w.heir(inv), undefined);
+    assert.ok(isSilence(await alice.being.join(inv)));
+    assert.deepEqual(alice.cells.standings, {});
+  });
+
+  // ---- consume, the knock
+
+  t('a valid knock binds the id to her own key and spends the heir; the asker is { id }', async () => {
+    const { w, shop, alice } = await world();
+    const inv = await shop.being.invite('gold');
+    assert.deepEqual(await alice.being.join(inv), { welcome: true });
+    const h = w.heir(inv)!;
+    assert.equal(h.fresh, false);
+    assert.notEqual(h.current, inv.heir); // rotation two: the heir is spent
+    assert.ok(alice.minted.has(h.current)); // her own key speaks now
+    assert.ok(!shop.minted.has(h.current)); // which the inviter never held
+    assert.equal(shop.cells.occupants.cust1.notes.asks, 1);
+  });
+
+  t('a second knock with the same invitation, from another: silence, nothing rebinds', async () => {
+    const { w, shop, alice, bob } = await world();
+    const inv = await shop.being.invite();
+    await alice.being.join(inv);
+    const bound = w.heir(inv)!.current;
+    assert.ok(isSilence(await bob.being.join(inv)));
+    assert.equal(w.heir(inv)!.current, bound); // still alice's
+    assert.deepEqual(bob.cells.standings, {});
+  });
+
+  t('a knock with the wrong secret, or a forged heir, is silence and never reaches her', async () => {
+    const { w, shop, alice } = await world();
+    let reached = 0;
+    const real = shop.being.answer.bind(shop.being);
+    shop.being.answer = (...a) => (reached++, real(...a));
+    const inv = await shop.being.invite();
+    const other = await shop.being.invite();
+    assert.ok(isSilence(await alice.being.knock({ ward: inv.ward, heir: 'f'.repeat(64), secret: inv.secret }, 'hello')));
+    assert.ok(isSilence(await alice.being.knock({ ward: inv.ward, heir: inv.heir, secret: other.secret }, 'hello'))); // a real secret, the wrong heir
+    assert.ok(isSilence(await alice.being.knock({ ward: inv.ward, heir: inv.heir, secret: '0'.repeat(64) }, 'hello')));
+    assert.equal(reached, 0);
+    assert.equal(w.heir(inv)!.fresh, true); // still unbound
+  });
+
+  t('the same knocker may knock again: her key is bound, no heir needed, it is an ask, and it announces her next key', async () => {
+    const { w, shop, alice } = await world();
+    const inv = await shop.being.invite();
+    assert.deepEqual(await alice.being.join(inv), { welcome: true });
+    const k1 = w.heir(inv)!.current;
+    assert.equal(w.heir(inv)!.announced, null); // a knock announces her key and dies; nothing further yet
+    assert.deepEqual(await alice.being.knock(inv, 'hello'), { welcome: true });
+    assert.equal(shop.cells.occupants.cust1.notes.asks, 2);
+    const h = w.heir(inv)!;
+    assert.equal(h.current, k1); // k1 spoke
+    assert.ok(h.announced && alice.minted.has(h.announced) && h.announced !== k1); // and vouched for the next
+  });
+
+  t('a knocker who presents a key of her own, unannounced, on a bound heir: silence', async () => {
+    const { w, shop, alice, bob } = await world();
+    const inv = await shop.being.invite();
+    await alice.being.join(inv);
+    const bound = w.heir(inv)!.current;
+    bob.forgeKnock(inv);
+    assert.ok(isSilence(await bob.being.knock(inv, 'hello')));
+    assert.equal(w.heir(inv)!.current, bound);
+    assert.equal(shop.cells.occupants.cust1.notes.asks, 1);
+  });
+
+  t('ids never cross: hers for me and mine for her are unrelated', async () => {
+    const { shop, alice } = await world();
+    await alice.being.join(await shop.being.invite());
+    assert.deepEqual(Object.keys(alice.cells.standings), ['shop']);
+    assert.deepEqual(Object.keys(shop.cells.occupants), ['cust1']);
+  });
+
+  down('a standing is born only after an answer; silence or unreached births nothing; an unreached knock does not spend the heir', async () => {
+    const { w, shop, alice } = await world();
+    const inv = await shop.being.invite();
+    shop.down = true;
+    assert.ok(isUnreached(await alice.being.join(inv)));
+    assert.deepEqual(alice.cells.standings, {});
+    assert.equal(w.heir(inv)!.fresh, true);
+    shop.down = false;
+    assert.deepEqual(await alice.being.join(inv), { welcome: true }); // the same invitation still works
+    const inv2 = await shop.being.invite();
+    shop.being.occupants.remove('cust2'); // she changed her mind before the knock
+    assert.ok(isSilence(await alice.being.join(inv2)));
+    assert.deepEqual(Object.keys(alice.cells.standings), ['shop']);
+  });
+
+  t('take without a knock, or after a silent knock, births nothing', async () => {
+    const { shop, alice } = await world();
+    const inv = await shop.being.invite();
+    assert.equal(await alice.being.take('shop', inv), null);
+    shop.being.occupants.remove('cust1');
+    assert.ok(isSilence(await alice.being.knock(inv, 'hello')));
+    assert.equal(await alice.being.take('shop', inv), null);
+    assert.deepEqual(alice.cells.standings, {});
+  });
+
+  // ---- asks
+
+  t('an occupant asks, a standing is asked, an object comes back', async () => {
+    const { alice, printer, shop } = await world();
+    await alice.being.join(await shop.being.invite());
+    assert.deepEqual(await alice.being.buy('hat'), { ok: true, receipt: 'receipt for hat' });
+    assert.equal((printer.cells.jobs as unknown[]).length, 1);
+    assert.equal((shop.cells.sales as JsonObject[])[0].by, 'cust1');
+  });
+
+  t('every answered ask rotates: each call speaks as the key the last one announced, and announces a fresh one, all minted by her side', async () => {
+    const { w, shop, alice } = await world();
+    const inv = await shop.being.invite();
+    await alice.being.join(inv);
+    const seen = new Set<string>([w.heir(inv)!.current]);
+    let expectNext = w.heir(inv)!.current; // after the knock, her key is current and nothing is announced
+    for (let i = 0; i < 3; i++) {
+      await alice.being.buy('hat');
+      const h = w.heir(inv)!;
+      assert.equal(h.current, expectNext); // this call spoke as what was announced before
+      assert.ok(h.announced && alice.minted.has(h.announced) && !seen.has(h.announced)); // and announced a fresh key
+      seen.add(h.announced);
+      expectNext = h.announced!;
+    }
+    assert.equal((shop.cells.sales as unknown[]).length, 3);
+    assert.equal(seen.size, 4);
+  });
+
+  t('asks in flight together on one standing: every one is answered, the rotation stays a single line, and the relation lives', async () => {
+    const { w, shop, alice } = await world();
+    const inv = await shop.being.invite();
+    await alice.being.join(inv);
+    const bound = w.heir(inv)!.current; // the key her side bound at the knock
+
+    const out = await Promise.all(Array.from({ length: 5 }, (_, i) => alice.being.buy(`hat${i}`)));
+    for (const [i, o] of out.entries()) assert.deepEqual(o, { ok: true, receipt: `receipt for hat${i}` }, `ask ${i} was answered`);
+    assert.equal((shop.cells.sales as unknown[]).length, 5); // each arrived once. none was lost, none was doubled
+
+    // five asks, five rotations, one line: the door's key is the fifth her
+    // side minted, and the side that did not mint it never held it.
+    const h = w.heir(inv)!;
+    assert.notEqual(h.current, bound);
+    assert.ok(alice.minted.has(h.current));
+    assert.ok(!shop.minted.has(h.current));
+
+    // and the two sides still agree, which is the whole of it: a relation
+    // that survived the crowd is a relation that still answers.
+    assert.deepEqual(await alice.being.buy('after'), { ok: true, receipt: 'receipt for after' });
+  });
+
+  t('two knocks in flight on one invitation: one heir, one binding, and she may still ask', async () => {
+    const { w, shop, alice } = await world();
+    const inv = await shop.being.invite();
+    const [a, b] = await Promise.all([alice.being.join(inv), alice.being.join(inv)]);
+    // the same knocker knocking twice at once is not two occupants: the heir
+    // is spent once, and both calls speak for the one relation she is building.
+    assert.deepEqual(Object.keys(shop.cells.occupants), ['cust1']);
+    for (const r of [a, b]) assert.ok(!isSilence(r) && !isUnreached(r), 'both knocks were answered');
+    const h = w.heir(inv)!;
+    assert.equal(h.fresh, false);
+    assert.ok(alice.minted.has(h.current)); // her own key speaks, exactly as after one knock
+    // What she does with the standing afterwards is not this test's. A take
+    // reads the relation where the knock left it, and a knock still in flight
+    // has not left it anywhere yet: the standing is born a step behind the
+    // door, and its first ask speaks under a number already honoured.
+  });
+
+  t('an inherited name is not an ask through a ward either: her cells do not come back for the asking', async () => {
+    const { shop, alice } = await world();
+    await alice.being.join(await shop.being.invite()); // plain: refund is hidden from her
+    shop.cells.ledger = { swiss: 'CH-99' };
+    for (const name of ['valueOf', 'toString', 'constructor', '__proto__', 'hasOwnProperty']) {
+      const out = await alice.being.standings.shop!.ask(name);
+      assert.deepEqual(out, { error: 'unknown ask' }, name);
+      assert.ok(!JSON.stringify(out).includes('CH-99'), `${name} carried her cells out`);
+    }
+    // the blueprint never named one of them, and the gate is the same gate
+    const blueprint = bp(await alice.being.learn());
+    for (const ask of blueprint.asks) assert.ok(!['valueOf', 'toString', 'constructor'].includes(ask.name));
+    assert.deepEqual(await alice.being.standings.shop!.ask('refund'), { error: 'unknown ask' }); // still hidden, still the same answer
+  });
+
+  t('symmetry: the customer offers a way back inside args; the shop takes a gold one', async () => {
+    const { shop, alice, bob } = await world();
+    await alice.being.join(await shop.being.invite('gold'));
+    await bob.being.join(await shop.being.invite('plain'));
+    assert.deepEqual(Object.keys(shop.cells.standings), ['prn', 'vip-cust1']);
+    assert.deepEqual(alice.cells.heard, [{ from: 'shop-back', method: 'hi' }]);
+    assert.deepEqual(bob.cells.heard, []);
+    assert.deepEqual(await shop.being.standings['vip-cust1']!.ask('hi'), { heard: 'hi' });
+  });
+
+  t('the printer never invited the shop: no standing, an error object, no throw', async () => {
+    const { alice, shop } = await world({ printerInvitesShop: false });
+    await alice.being.join(await shop.being.invite());
+    assert.deepEqual(await alice.being.buy('hat'), { error: 'no printer' });
+  });
+
+  t('the empty ask is describe; shaped per asker', async () => {
+    const { shop, alice, bob } = await world();
+    await alice.being.join(await shop.being.invite('gold'));
+    await bob.being.join(await shop.being.invite());
+    const names = (x: unknown) => bp(x).asks.map((a) => a.name);
+    assert.deepEqual(names(await alice.being.learn()), ['hello', 'buy', 'refund']);
+    assert.deepEqual(names(await bob.being.learn()), ['hello', 'buy']);
+  });
+
+  t('the digest is per relation: two occupants, two digests of one being, both true', async () => {
+    const { shop, alice, bob } = await world();
+    await alice.being.join(await shop.being.invite('gold'));
+    await bob.being.join(await shop.being.invite());
+    await alice.being.learn();
+    await bob.being.learn();
+    assert.notEqual(alice.cells.standings.shop.digest, bob.cells.standings.shop.digest);
+  });
+
+  t('describe caches blueprint and digest in the asker cells', async () => {
+    const { shop, alice } = await world();
+    await alice.being.join(await shop.being.invite());
+    const out = await alice.being.learn();
+    assert.deepEqual(alice.cells.standings.shop.blueprint, out);
+    assert.equal(alice.cells.standings.shop.digest, await digest(out as Json));
+  });
+
+  t('a changed standing is noticed by digest, without carrying the blueprint', async () => {
+    const { alice, printer, shop } = await world();
+    await alice.being.join(await shop.being.invite());
+    await shop.being.standings.prn!.ask();
+    (printer.cells.asks as JsonObject[]).push({ name: 'scan', input: {} }); // she changed
+    await alice.being.buy('hat');
+    const st = shop.cells.standings.prn;
+    assert.notEqual(st.seen, st.digest);
+    assert.equal(shop.cells.occupants.cust1.notes.printerChanged, true);
+  });
+
+  t('the digest rides on every answer: seen updates without a describe from her side', async () => {
+    const { alice, printer, shop } = await world();
+    await alice.being.join(await shop.being.invite());
+    let describes = 0;
+    const real = printer.being.answer.bind(printer.being);
+    printer.being.answer = (a, m, x) => (m === undefined && describes++, real(a, m, x));
+    await alice.being.buy('hat'); // shop asks printer once
+    const st = shop.cells.standings.prn;
+    assert.equal(st.seen, await digest((await real({ id: 'shop' })) as Json));
+    assert.equal(describes, 1); // the far ward ran her describe, in process, once per answer
+    assert.equal(st.digest, null); // she never fetched it herself
+  });
+
+  t('a silent refresh leaves seen untouched', async () => {
+    const { alice, printer, shop } = await world();
+    await alice.being.join(await shop.being.invite());
+    await shop.being.standings.prn!.ask();
+    const before = shop.cells.standings.prn.seen;
+    const real = printer.being.answer.bind(printer.being);
+    printer.being.answer = async (a, m, x) => (m === undefined ? silence : real(a, m, x));
+    await alice.being.buy('hat');
+    assert.equal(shop.cells.standings.prn.seen, before);
+  });
+
+  down('unreached is the ward word, distinct from silence, carries nothing, safe to retry', async () => {
+    const { alice, printer, shop } = await world();
+    await alice.being.join(await shop.being.invite());
+    printer.down = true;
+    assert.deepEqual(await alice.being.buy('hat'), { error: 'printer unreachable', retry: true });
+    const out = await shop.being.standings.prn!.ask('print', { doc: 'x' });
+    assert.ok(isUnreached(out) && !isSilence(out));
+    assert.deepEqual(Object.keys(out), []);
+    printer.down = false;
+    assert.deepEqual(await alice.being.buy('hat'), { ok: true, receipt: 'receipt for hat' });
+  });
+
+  t('a removed occupant is silence to the far side and her heir is forgotten; a dropped standing is gone', async () => {
+    const { w, alice, shop } = await world();
+    const inv = await shop.being.invite();
+    await alice.being.join(inv);
+    shop.being.occupants.remove('cust1');
+    assert.equal(w.heir(inv), undefined);
+    assert.ok(isSilence(await alice.being.buy('hat')));
+    alice.being.standings.remove('shop');
+    assert.equal(alice.being.standings.shop, undefined);
+    assert.ok(isSilence(await alice.being.knock(inv, 'hello'))); // and a re-knock finds no heir
+    const again = await shop.being.invite(); // cust2. a new heir
+    assert.notEqual(again.heir, inv.heir);
+    assert.deepEqual(await alice.being.knock(again, 'hello'), { welcome: true });
+  });
+
+  t('dropping a standing while an ask on it is in flight does not crash', async () => {
+    const { alice, shop } = await world();
+    await alice.being.join(await shop.being.invite());
+    const p = alice.being.buy('hat');
+    alice.being.standings.remove('shop');
+    assert.deepEqual(await p, { ok: true, receipt: 'receipt for hat' });
+    assert.equal((shop.cells.sales as unknown[]).length, 1);
+  });
+
+  t('a being that throws is silence outside; the ward stays up', async () => {
+    const w = await make();
+    class Bomb {
+      s: unknown;
+      constructor(s: unknown) {
+        this.s = s;
+      }
+      answer(_: Asker, m?: string) {
+        if (m === undefined) return { asks: [], notes: {} };
+        throw new Error('boom');
+      }
+    }
+    const x = await w.boot<Bomb>('X', Bomb);
+    const a = await w.boot<Customer>('A', Customer);
+    const inv = (await (x.being.s as Customer['stance']).occupants.invite('a'))!;
+    assert.ok(isSilence(await a.being.knock(inv, 'any')));
+    assert.deepEqual(await a.being.knock(inv), { asks: [], notes: {} });
+  });
+
+  t('null is an answer, silence is not', async () => {
+    const w = await make();
+    class Nul {
+      s: unknown;
+      constructor(s: unknown) {
+        this.s = s;
+      }
+      answer(_: Asker, m?: string) {
+        return m === undefined ? { asks: [], notes: {} } : null;
+      }
+    }
+    const n = await w.boot<Nul>('N', Nul);
+    const a = await w.boot<Customer>('A', Customer);
+    const out = await a.being.knock((await (n.being.s as Customer['stance']).occupants.invite('a'))!, 'x');
+    assert.equal(out, null);
+    assert.ok(!isSilence(out));
+  });
+
+  t('the raw shape is a being through a ward, exactly like one on the base class', async () => {
+    const w = await make();
+    const e = await w.boot<Echo>('E', Echo);
+    const a = await w.boot<Customer>('A', Customer);
+    const inv = (await e.being.s.occupants.invite('a'))!;
+    assert.deepEqual(await a.being.knock(inv, 'echo', { x: 1 }), { from: 'a', x: 1 });
+    assert.equal(await a.being.take('echo', inv), 'echo');
+    assert.deepEqual(await a.being.standings.echo!.ask('echo', { y: 2 }), { from: 'a', y: 2 });
+    assert.equal(a.cells.standings.echo.seen, await digest({ asks: [{ name: 'echo', input: {} }], notes: {} }));
+  });
+
+  // ---- public
+
+  t('a public being is asked by anyone as {}; a knock on her needs no heir and may be taken; a ward with none is silence; an unknown pk is unreached', async () => {
+    const w = await make();
+    class Pub {
+      s: { cells: Cells };
+      constructor(s: { cells: Cells }) {
+        this.s = s;
+        this.s.cells.askers ??= [];
+      }
+      answer(asker: Asker, m?: string, args?: JsonObject) {
+        if (m === undefined) return { asks: [{ name: 'time', input: {} }], notes: {} };
+        (this.s.cells.askers as Json[]).push(asker as Json);
+        return { time: 12, got: args ?? {} };
+      }
+    }
+    const pub = await w.boot<Pub>('PUB', Pub as never, {}, { isPublic: true });
+    const priv = await w.boot<Pub>('PRIV', Pub as never); // same class, not public
+    const a = await w.boot<Customer>('A', Customer);
+    const b = await w.boot<Customer>('B', Customer);
+    const at = (h: { pk: string }) => ({ ward: h.pk });
+    assert.deepEqual(await a.being.knock(at(pub), 'time', { x: 1 }), { time: 12, got: { x: 1 } });
+    assert.deepEqual(await b.being.knock(at(pub), 'time'), { time: 12, got: {} });
+    assert.deepEqual(pub.cells.askers, [{}, {}]);
+    assert.deepEqual(pub.cells.occupants, {}); // she never invited anyone
+    if (!w.oneWard) assert.ok(isSilence(await a.being.knock(at(priv), 'time'))); // a ward with no public being: silence
+    assert.ok(isUnreached(await a.being.knock({ ward: 'a'.repeat(128) }, 'time'))); // no door anywhere: unreached
+    assert.ok(isSilence(await a.being.knock({ ward: 'not a pk' }, 'time'))); // not even an address
+    assert.equal(await a.being.take('clock', at(pub)), 'clock');
+    assert.deepEqual(await a.being.standings.clock!.ask('time'), { time: 12, got: {} });
+    assert.equal(a.cells.standings.clock.seen, await digest((await a.being.standings.clock!.ask()) as Json));
+  });
+
+  // ---- keys stay where they belong
+
+  t("two rotations: the heir is the inviter's, the bound key is the knocker's, and neither side minted the other's", async () => {
+    const { w, shop, alice, bob } = await world();
+    const i1 = await shop.being.invite('gold');
+    const i2 = await shop.being.invite();
+    assert.ok(shop.minted.has(i1.heir!) && shop.minted.has(i2.heir!));
+    await alice.being.join(i1);
+    await bob.being.join(i2);
+    const h1 = w.heir(i1)!, h2 = w.heir(i2)!;
+    assert.ok(alice.minted.has(h1.current) && !shop.minted.has(h1.current) && !bob.minted.has(h1.current));
+    assert.ok(bob.minted.has(h2.current) && !shop.minted.has(h2.current) && !alice.minted.has(h2.current));
+    assert.notEqual(h1.current, h2.current); // no key serves two relations
+    assert.ok(!alice.minted.has(i1.heir!)); // alice never minted anything of the shop's
+  });
+
+  t('her cells carry no key: heir, secret, and bound key live in the bind table only', async () => {
+    const { w, shop, alice } = await world();
+    const inv = await shop.being.invite();
+    await alice.being.join(inv);
+    await alice.being.learn();
+    const words = [inv.heir!, inv.secret!, w.heir(inv)!.current];
+    for (const cells of [shop.cells, alice.cells]) for (const word of words) assert.ok(!JSON.stringify(cells).includes(word), `${word} in cells`);
+  });
+
+  // ---- the estate
+
+  estate(label, make, { canDown, test });
+}
+
+// The store and reach suites, beside the ward's: every store a harbor keeps
+// wards in and every reach it carries bytes by passes its own, on the
+// terrain it is written for.
+export { conformStore } from './store.ts';
+export { conformReach, type FarSide } from './reach.ts';

package/src/conformance/reach.ts

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+// The reach conformance suite: what every reach must show, written against
+// the interface alone. A reach is handed in as a maker of a fresh line to a
+// far side the suite controls: `hold` puts a door behind a pk over there,
+// `drop` takes the far side away, the line down or the listener gone. The
+// suite asks for bytes and expects the door's bytes back, nothing for a pk
+// nobody holds, and nothing once the far side is gone. It cannot assert
+// that a reach which sent and then lost the line answers nothing at all,
+// since a suite cannot wait forever; that promise is read in the code.
+import { assert } from './assert.ts';
+import type { Reach } from '../harbor/reach.ts';
+import type { Runner } from './index.ts';
+
+export type FarSide = {
+  reach: Reach;
+  hold(pk: string, door: (bytes: Uint8Array) => Promise<Uint8Array>): Promise<void>;
+  drop(): Promise<void>;
+};
+
+const pk = (b: string) => b.repeat(64);
+const bytes = (...xs: number[]) => Uint8Array.from(xs);
+const wait = (ms: number) => new Promise<void>((ok) => setTimeout(ok, ms));
+
+export function conformReach(label: string, make: () => Promise<FarSide>, { test }: { test: Runner }) {
+  const t = (name: string, fn: () => Promise<void>) => test(`[${label}] ${name}`, {}, fn);
+
+  t('bytes to a pk the far side holds come back as the door answered', async () => {
+    const far = await make();
+    try {
+      await far.hold(pk('aa'), async (b) => bytes(...b, 9));
+      assert.deepEqual(await far.reach.carry(pk('aa'), bytes(1, 2, 3)), bytes(1, 2, 3, 9));
+    } finally {
+      await far.drop();
+    }
+  });
+
+  t('bytes to a pk nobody holds are nothing', async () => {
+    const far = await make();
+    try {
+      await far.hold(pk('aa'), async (b) => b);
+      assert.equal(await far.reach.carry(pk('bb'), bytes(1)), undefined);
+    } finally {
+      await far.drop();
+    }
+  });
+
+  t('asks in flight at once each get their own answer', async () => {
+    const far = await make();
+    try {
+      await far.hold(pk('aa'), async (b) => (await wait(b[0]! * 10), bytes(b[0]!)));
+      const out = await Promise.all([far.reach.carry(pk('aa'), bytes(3)), far.reach.carry(pk('aa'), bytes(1)), far.reach.carry(pk('aa'), bytes(2))]);
+      assert.deepEqual(out, [bytes(3), bytes(1), bytes(2)]);
+    } finally {
+      await far.drop();
+    }
+  });
+
+  t('what comes back is a copy, and what was sent was one', async () => {
+    const far = await make();
+    try {
+      let seen: Uint8Array | undefined;
+      const reply = bytes(7, 7);
+      await far.hold(pk('aa'), async (b) => ((seen = b), reply));
+      const sent = bytes(4, 5);
+      const back = (await far.reach.carry(pk('aa'), sent))!;
+      assert.deepEqual(back, bytes(7, 7));
+      back[0] = 0;
+      assert.deepEqual(reply, bytes(7, 7), 'the caller wrote through to the door');
+      seen![0] = 0;
+      assert.deepEqual(sent, bytes(4, 5), 'the door wrote through to the caller');
+    } finally {
+      await far.drop();
+    }
+  });
+
+  t('once the far side is gone, bytes are nothing', async () => {
+    const far = await make();
+    await far.hold(pk('aa'), async (b) => b);
+    assert.deepEqual(await far.reach.carry(pk('aa'), bytes(1)), bytes(1));
+    await far.drop();
+    assert.equal(await far.reach.carry(pk('aa'), bytes(1)), undefined);
+  });
+}