@quo-systems/quo 0.1.0 → 0.2.0

package/dist/conformance/index.js

@@ -0,0 +1,448 @@
+// 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.js';
+import { silence, isSilence, isUnreached, isWord, wordOf } from '../being/silence.js';
+import { digest } from '../being/digest.js';
+import { Printer, Shop, Customer, Echo, Member } from './beings.js';
+import { estate } from './estate.js';
+export { Printer, Shop, Customer, Echo, Member };
+const HEX64 = /^[0-9a-f]{64}$/;
+// Her ward's word, as she receives it.
+const said = (x, w) => isWord(x) && wordOf(x) === w;
+export function conform(label, make, { canDown = true, test }) {
+    const t = (name, fn) => test(`[${label}] ${name}`, {}, fn);
+    const down = (name, fn) => 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('P', Printer);
+        const shop = await w.boot('S', Shop);
+        const alice = await w.boot('A', Customer);
+        const bob = await w.boot('B', Customer);
+        if (printerInvitesShop)
+            await shop.being.keepPrinter((await printer.being.invite('shop')));
+        return { w, printer, shop, alice, bob };
+    }
+    const bp = (x) => x;
+    // ---- 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, and a knock on it by whoever holds it hears removed', 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(said(await alice.being.join(inv), 'removed'));
+        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(said(await alice.being.join(inv2), 'removed'));
+        assert.deepEqual(Object.keys(alice.cells.standings), ['shop']);
+    });
+    t('take without a knock, or after a knock that was not answered, 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(said(await alice.being.knock(inv, 'hello'), 'removed'));
+        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.length, 1);
+        assert.equal(shop.cells.sales[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([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.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.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) => 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));
+    });
+    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.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' }))));
+        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 hears removed under the key the door bound, 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(said(await alice.being.buy('hat'), 'removed'));
+        alice.being.standings.remove('shop');
+        assert.equal(alice.being.standings.shop, undefined);
+        assert.ok(isSilence(await alice.being.knock(inv, 'hello'))); // her bound key went with the standing: a re-knock is as the heir, which is spent, a stranger
+        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.length, 1);
+    });
+    t('a being that throws is the word threw to whom the door has bound; the ward stays up', async () => {
+        const w = await make();
+        class Bomb {
+            s;
+            constructor(s) {
+                this.s = s;
+            }
+            answer(_, m) {
+                if (m === undefined)
+                    return { asks: [], notes: {} };
+                throw new Error('boom');
+            }
+        }
+        const x = await w.boot('X', Bomb);
+        const a = await w.boot('A', Customer);
+        const inv = (await x.being.s.occupants.invite('a'));
+        assert.ok(said(await a.being.knock(inv, 'any'), 'threw'));
+        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;
+            constructor(s) {
+                this.s = s;
+            }
+            answer(_, m) {
+                return m === undefined ? { asks: [], notes: {} } : null;
+            }
+        }
+        const n = await w.boot('N', Nul);
+        const a = await w.boot('A', Customer);
+        const out = await a.being.knock((await n.being.s.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('E', Echo);
+        const a = await w.boot('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;
+            constructor(s) {
+                this.s = s;
+                this.s.cells.askers ??= [];
+            }
+            answer(asker, m, args) {
+                if (m === undefined)
+                    return { asks: [{ name: 'time', input: {} }], notes: {} };
+                this.s.cells.askers.push(asker);
+                return { time: 12, got: args ?? {} };
+            }
+        }
+        const pub = await w.boot('PUB', Pub, {}, { isPublic: true });
+        const priv = await w.boot('PRIV', Pub); // same class, not public
+        const a = await w.boot('A', Customer);
+        const b = await w.boot('B', Customer);
+        const at = (h) => ({ 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(said(await a.being.knock({ ward: 'not a pk' }, 'time'), 'invitation')); // 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())));
+    });
+    // ---- 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.js';
+export { conformReach } from './reach.js';

package/dist/conformance/reach.d.ts

@@ -0,0 +1,10 @@
+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>;
+};
+export declare function conformReach(label: string, make: () => Promise<FarSide>, { test }: {
+    test: Runner;
+}): void;

package/dist/conformance/reach.js

@@ -0,0 +1,72 @@
+// 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.js';
+const pk = (b) => b.repeat(64);
+const bytes = (...xs) => Uint8Array.from(xs);
+const wait = (ms) => new Promise((ok) => setTimeout(ok, ms));
+export function conformReach(label, make, { test }) {
+    const t = (name, fn) => 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;
+            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);
+    });
+}

package/dist/conformance/store.d.ts

@@ -0,0 +1,5 @@
+import type { Store } from '../harbor/store.ts';
+import type { Runner } from './index.ts';
+export declare function conformStore(label: string, make: () => Promise<Store>, { test }: {
+    test: Runner;
+}): void;

package/dist/conformance/store.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: Apache-2.0
+// The store conformance suite: what every store must show, written against
+// the interface alone. A store is handed in as a maker of fresh ones: an
+// empty folder, a database nobody opened, a view of storage under a prefix
+// nobody used. Nothing here knows how a store keeps anything; it asks for
+// what it put and expects it back, as the harbor will.
+import { assert } from './assert.js';
+const seed = (b) => new Uint8Array(32).fill(b);
+const kept = (b, extra = {}) => ({ seed: seed(b), partition: { beings: {}, ...extra }, record: { pk: '', code: 'classes/index.ts', user: 'me' } });
+export function conformStore(label, make, { test }) {
+    const t = (name, fn) => test(`[${label}] ${name}`, {}, fn);
+    t('a fresh store keeps nothing', async () => {
+        const s = await make();
+        assert.deepEqual(await s.list(), []);
+        assert.equal(await s.load('main'), undefined);
+        assert.equal(await s.take('main'), undefined);
+        assert.deepEqual(await s.hints(), {});
+    });
+    t('put, then load: seed, partition and record come back as they went in', async () => {
+        const s = await make();
+        await s.put('main', kept(7, { n: 1, deep: { list: [1, 'two', null], flag: true } }));
+        assert.deepEqual(await s.list(), ['main']);
+        const back = await s.load('main');
+        assert.ok(back);
+        assert.deepEqual(back.seed, seed(7));
+        assert.deepEqual(back.partition, { beings: {}, n: 1, deep: { list: [1, 'two', null], flag: true } });
+        assert.deepEqual(back.record, { pk: '', code: 'classes/index.ts', user: 'me' });
+    });
+    t('a name already kept is refused, and what was kept stands', async () => {
+        const s = await make();
+        await s.put('main', kept(1));
+        let refused = false;
+        try {
+            await s.put('main', kept(2));
+        }
+        catch {
+            refused = true;
+        }
+        assert.ok(refused, 'a second put under one name must throw');
+        assert.deepEqual((await s.load('main')).seed, seed(1));
+    });
+    t('save replaces the partition and touches nothing else', async () => {
+        const s = await make();
+        await s.put('main', kept(3));
+        await s.save('main', { beings: { a: { x: 1 } }, bind: {} });
+        const back = (await s.load('main'));
+        assert.deepEqual(back.partition, { beings: { a: { x: 1 } }, bind: {} });
+        assert.deepEqual(back.seed, seed(3));
+        assert.deepEqual(back.record, kept(3).record);
+    });
+    t('record replaces the record and touches nothing else', async () => {
+        const s = await make();
+        await s.put('main', kept(4, { n: 9 }));
+        await s.record('main', { pk: 'ab'.repeat(64), code: 'elsewhere.ts', user: 'her' });
+        const back = (await s.load('main'));
+        assert.deepEqual(back.record, { pk: 'ab'.repeat(64), code: 'elsewhere.ts', user: 'her' });
+        assert.deepEqual(back.partition, { beings: {}, n: 9 });
+    });
+    t('save and record on a name not kept are nothing', async () => {
+        const s = await make();
+        await s.save('ghost', { beings: {} });
+        await s.record('ghost', { pk: '', code: '', user: '' });
+        assert.deepEqual(await s.list(), []);
+    });
+    t('the partition handed back is values, not the object that was put', async () => {
+        const s = await make();
+        const k = kept(5, { n: 1 });
+        await s.put('main', k);
+        k.partition.n = 2;
+        assert.deepEqual((await s.load('main')).partition, { beings: {}, n: 1 });
+        const a = (await s.load('main'));
+        a.partition.n = 3;
+        assert.deepEqual((await s.load('main')).partition, { beings: {}, n: 1 });
+    });
+    t('take hands the ward out and forgets it; the name is free again', async () => {
+        const s = await make();
+        await s.put('main', kept(6, { n: 6 }));
+        await s.put('other', kept(8));
+        const out = await s.take('main');
+        assert.ok(out);
+        assert.deepEqual(out.seed, seed(6));
+        assert.deepEqual(out.partition, { beings: {}, n: 6 });
+        assert.equal(await s.load('main'), undefined);
+        assert.deepEqual(await s.list(), ['other']);
+        await s.put('main', kept(9));
+        assert.deepEqual((await s.load('main')).seed, seed(9));
+    });
+    t('hints are kept by pk and the last one wins', async () => {
+        const s = await make();
+        const pk = 'cd'.repeat(64);
+        await s.hint(pk, 'https://quo.acme.com/quo');
+        await s.hint('ef'.repeat(64), 'http://127.0.0.1:1/quo');
+        assert.deepEqual(await s.hints(), { [pk]: 'https://quo.acme.com/quo', ['ef'.repeat(64)]: 'http://127.0.0.1:1/quo' });
+        await s.hint(pk, 'https://quo.other.com/quo');
+        assert.equal((await s.hints())[pk], 'https://quo.other.com/quo');
+    });
+}