@quo-systems/quo 0.1.0 → 0.1.1

package/dist/conformance/beings.js

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: Apache-2.0
+// The fixture beings. Fixed, so that the ward is what varies. A printer, a
+// shop, a customer on the base class, and one raw being with no base at all.
+import { Being } from '../being/being.js';
+import { isSilence, isUnreached } from '../being/silence.js';
+// A printer. Invites whom she is told to, prints for her occupants. Her
+// blueprint lives in her cells so a test can change her shape.
+export class Printer extends Being {
+    static cells = { jobs: [], asks: [{ name: 'print', input: { type: 'object' } }] };
+    static asks = { print: { input: { type: 'object' } } };
+    describe() {
+        return { asks: this.cells.asks, notes: { model: 'LX-2' } };
+    }
+    print({ doc }, asker) {
+        this.cells.jobs.push({ by: asker.id ?? null, doc: doc ?? null });
+        return { printed: doc ?? null };
+    }
+}
+// A shop. Invites customers in her own time. Keeps a printer as a standing.
+// Takes a gold customer back if the customer offers a way. Counts every ask
+// per occupant, by wrapping answer.
+export class Shop extends Being {
+    static cells = { printerId: null, sales: [], minted: 0 };
+    static asks = {
+        hello: { input: { type: 'object' } },
+        buy: { input: { type: 'object', properties: { item: { type: 'string' } } } },
+        refund: { input: { type: 'object' }, for: (rec) => rec?.notes.tier === 'gold' },
+    };
+    async answer(asker, method, args) {
+        const rec = this.occupant(asker);
+        if (rec && method !== undefined)
+            rec.notes.asks = (Number(rec.notes.asks) || 0) + 1;
+        return super.answer(asker, method, args);
+    }
+    // Outside any ask. She mints, her ward seals, she hands it out by mail.
+    async invite(tier = 'plain') {
+        const id = `cust${++this.cells.minted}`;
+        const inv = (await super.invite(id));
+        this.cells.occupants[id].notes.tier = tier;
+        return inv;
+    }
+    async keepPrinter(invitation) {
+        const bp = await this.knock(invitation);
+        if (isSilence(bp) || isUnreached(bp))
+            return false;
+        this.cells.printerId = await this.take('prn', invitation);
+        return true;
+    }
+    async hello({ invitation }, asker) {
+        const rec = this.occupant(asker);
+        if (rec?.notes.tier === 'gold' && invitation) {
+            const back = await this.knock(invitation, 'hi');
+            if (!isSilence(back) && !isUnreached(back))
+                await this.take(`vip-${asker.id}`, invitation);
+        }
+        return { welcome: true };
+    }
+    async buy({ item }, asker) {
+        if (typeof item !== 'string')
+            return { error: 'no such item' }; // args are hers to check
+        const id = this.cells.printerId;
+        const printer = id ? this.standings[id] : undefined;
+        if (!printer)
+            return { error: 'no printer' };
+        const out = await printer.ask('print', { doc: `receipt for ${item}` });
+        if (isUnreached(out))
+            return { error: 'printer unreachable', retry: true };
+        if (isSilence(out))
+            return { error: 'printer refused' };
+        const st = this.cells.standings[id];
+        if (st.seen !== st.digest)
+            this.occupant(asker).notes.printerChanged = true;
+        this.cells.sales.push({ item: item ?? null, by: asker.id ?? null });
+        return { ok: true, receipt: out.printed };
+    }
+    refund() {
+        return { ok: true };
+    }
+}
+// A customer. Consumes an invitation, and only then decides to keep the
+// shop. Offers the shop a way back so the shop can reach her.
+export class Customer extends Being {
+    static cells = { heard: [] };
+    static asks = { hi: { input: { type: 'object' } } };
+    async join(invitation) {
+        const mine = (await this.invite('shop-back'));
+        const out = await this.knock(invitation, 'hello', { invitation: mine });
+        if (isSilence(out) || isUnreached(out))
+            return out; // nothing was born
+        await this.take('shop', invitation); // now, and only now
+        return out;
+    }
+    buy(item) {
+        return this.standings.shop.ask('buy', { item });
+    }
+    learn() {
+        return this.standings.shop.ask();
+    }
+    hi(_args, asker) {
+        this.cells.heard.push({ from: asker.id ?? null, method: 'hi' });
+        return { heard: 'hi' };
+    }
+}
+// The raw shape. No base class, no import from the kit. A being all the same.
+export class Echo {
+    s;
+    constructor(stance) {
+        this.s = stance;
+    }
+    answer(asker, method, args = {}) {
+        if (method === undefined)
+            return { asks: [{ name: 'echo', input: {} }], notes: {} };
+        return { from: asker.id ?? null, ...args };
+    }
+}
+// A member of an estate. Nothing scripted: she invites whom she is told to,
+// knocks where she is told to, and answers `ping` with the asker's own name.
+// The estate chapter drives her, and what it drives is the graph, not her.
+export class Member extends Being {
+    static cells = { heard: [] };
+    static asks = { ping: { input: { type: 'object' } } };
+    ping(_args, asker) {
+        this.cells.heard.push({ from: asker.id ?? null });
+        return { pong: asker.id ?? null };
+    }
+}

package/dist/conformance/estate.d.ts

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

package/dist/conformance/estate.js

@@ -0,0 +1,310 @@
+// SPDX-License-Identifier: Apache-2.0
+// The estate. Every other chapter is a scene: two or three beings, one move,
+// one answer. This one is a graph under churn.
+//
+// An organisation does not run one relation. It runs a few hundred, scattered
+// over wards on scattered harbors, and they are not born together: partners
+// are invited, employees knock, standings are taken, people are kicked, wards
+// move to harbors of their own. Nothing is wrong at the second move. What
+// goes wrong goes wrong at the hundredth, when a kick and a take and a
+// migration have landed on top of each other, and no scene written by hand
+// will ever be that sequence.
+//
+// So this chapter does not write the sequence. It keeps a model of the graph,
+// plays legal moves against it from three fixed seeds, and after every move
+// asks three things:
+//
+//   the ledger is a graph          every arc the wards hold closes on both ends
+//   the ledger is what it can do   every arc in the model is asked, and answers
+//                                  exactly what being that arc means it answers
+//   the graph is not the topology  the same seed, played under one ward, under
+//                                  a ward per being, and under two harbors,
+//                                  ends in the same graph
+//
+// The third is the one that matters most here. A being never learns where the
+// other one is, so a script that is topology-invariant at forty moves is the
+// promise of Quo held at a scale a scene cannot reach -- and it is what makes
+// a migration honest: if nobody can tell the topology apart, moving a ward
+// between harbors cannot be felt.
+//
+// A relation is two arcs and never one edge. The occupant arc is the host's,
+// born at invite; the standing arc is the guest's, born at take, and only
+// after an answer. `SPEC.md`: take binds B's side only, the knock bound hers.
+// A model that kept one symmetric edge would be a wrong model, and would
+// agree happily with a ward that had drifted.
+import { assert } from './assert.js';
+import { isSilence, isUnreached } from '../being/silence.js';
+import { Member } from './beings.js';
+const HEX64 = /^[0-9a-f]{64}$/;
+// A pseudo-random source in the language alone: the estate must replay, on
+// every terrain, from a number a failure can print.
+const rolls = (seed) => () => {
+    seed = (seed + 0x6d2b79f5) | 0;
+    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+};
+// The graph, with nothing of the world in it: no key, no ward pk, no harbor.
+// Two runs under two topologies are the same estate when these agree.
+const abc = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const fingerprint = (g) => JSON.stringify({
+    seats: g.seats.map((s) => JSON.stringify([s.host, s.id, s.guest, s.answered, s.live, s.taken])).sort(abc),
+    holds: g.holds.map((h) => JSON.stringify([h.owner, h.id, h.seat.host, h.seat.id, h.live])).sort(abc),
+});
+// Every run of one seed, under every topology, must land on the same graph.
+// The topologies run in one process, so the first to finish records and the
+// rest are held to it.
+const landed = new Map();
+// ---- the ledger is a graph
+// Held after every move. Each line is a way the bookkeeping could stop being
+// a graph: an arc with one end, an arc with two owners, a relation filed in
+// two places at once, a count that went backwards, a secret in the cells.
+function ledger(c, before, where) {
+    const at = (why) => `${where}: ${why}`;
+    const heirsSeen = new Set();
+    for (const [pk, w] of Object.entries(c.wards)) {
+        for (const [heir, r] of Object.entries(w.heirs)) {
+            assert.ok(!heirsSeen.has(heir), at(`heir ${heir} is held by two wards`));
+            heirsSeen.add(heir);
+            assert.match(heir, HEX64, at(`heir ${heir} is not a key`));
+            // the far end of the arc: the being the ward says minted it holds it back, under the same id
+            const b = c.binds[r.being];
+            assert.ok(b, at(`heir ${heir} names ${r.being}, who lives in no ward`));
+            assert.equal(b.ward, pk, at(`heir ${heir} is kept by ${pk}, but ${r.being} lives behind ${b.ward}`));
+            assert.equal(b.occupants[r.id], heir, at(`heir ${heir} says it is ${r.being}'s ${r.id}, who does not hold it`));
+            assert.ok(r.spent.every((n) => n <= r.mark), at(`heir ${heir} spent a number above its mark`));
+        }
+    }
+    for (const [key, b] of Object.entries(c.binds)) {
+        // every occupant id the being holds is a heir her own ward keeps
+        for (const [id, heir] of Object.entries(b.occupants)) {
+            const r = c.wards[b.ward].heirs[heir];
+            assert.ok(r, at(`${key}'s occupant ${id} names heir ${heir}, which her ward has forgotten`));
+            assert.equal(r.being, key, at(`${key}'s occupant ${id} names a heir of ${r.being}'s`));
+            assert.equal(r.id, id, at(`${key}'s occupant ${id} names a heir filed under ${r.id}`));
+        }
+        // a taken relation lives in the standing and never also in a knock record
+        for (const [id, s] of Object.entries(b.standings)) {
+            const name = s.heir === null ? `public:${s.ward}` : `${s.ward}:${s.heir}`;
+            assert.ok(!b.knocks.includes(name), at(`${key}'s standing ${id} still has a knock record`));
+            assert.ok(!b.answered.includes(name), at(`${key}'s standing ${id} is still marked answered`));
+        }
+        // no key her side holds is anywhere in anyone's cells
+        const cells = JSON.stringify(c.cells);
+        for (const word of b.secrets)
+            assert.ok(!cells.includes(word), at(`a key of ${key}'s is in the cells`));
+        // counts climb and never fall. a door that forgot what it honoured honours it again
+        const was = before?.binds[key];
+        if (was)
+            for (const [id, s] of Object.entries(b.standings))
+                assert.ok(!was.standings[id] || s.seq >= was.standings[id].seq, at(`${key}'s standing ${id} counted backwards`));
+    }
+    if (before)
+        for (const [pk, w] of Object.entries(c.wards))
+            for (const [heir, r] of Object.entries(w.heirs)) {
+                const was = before.wards[pk]?.heirs[heir];
+                if (was)
+                    assert.ok(r.mark >= was.mark, at(`heir ${heir} marked backwards`));
+            }
+}
+// ---- the chapter
+export function estate(label, make, { canDown, test }) {
+    const t = (name, fn) => test(`[${label}] ${name}`, {}, fn);
+    // The story, told once, by hand, so that the next person can read what the
+    // model is for. A partner is invited into a harbor she is borrowing, works,
+    // moves to a harbor of her own, is kicked, and is invited back as somebody
+    // else. Nothing here is random and nothing here is generated.
+    t('estate: a partner is invited into a borrowed harbor, works, moves to her own, is kicked, and comes back as somebody else', async () => {
+        const w = await make();
+        const acme = await w.boot('ACME', Member);
+        const partner = await w.boot('PARTNER', Member);
+        // 1. acme mints a name for her and asks her ward for an invitation. the
+        //    occupant exists from that moment, and the partner knows nothing yet.
+        const first = (await acme.being.invite('partner-1'));
+        assert.deepEqual(Object.keys(acme.cells.occupants), ['partner-1']);
+        assert.deepEqual(partner.cells.standings, {});
+        // 2. she knocks. from now on every ask of hers arrives as that name.
+        assert.deepEqual(await partner.being.knock(first, 'ping'), { pong: 'partner-1' });
+        // 3. and only then does she keep acme, under a name of her own minting.
+        assert.equal(await partner.being.take('the-client', first), 'the-client');
+        assert.deepEqual(await partner.being.standings['the-client'].ask('ping'), { pong: 'partner-1' });
+        // 4. she gets her own harbor. the same seed, the same pk, so the arc acme
+        //    holds still points at her and the arc she holds still points at acme.
+        await w.migrate('PARTNER');
+        await w.migrate('ACME');
+        assert.deepEqual(await partner.being.standings['the-client'].ask('ping'), { pong: 'partner-1' });
+        const back = (await partner.being.invite('acme'));
+        assert.deepEqual(await acme.being.knock(back, 'ping'), { pong: 'acme' });
+        assert.equal(await acme.being.take('them', back), 'them');
+        // 5. acme kicks her. her standing is still hers to hold -- she is never
+        //    told -- and it is silence from here on.
+        acme.being.occupants.remove('partner-1');
+        assert.ok(isSilence(await partner.being.standings['the-client'].ask('ping')));
+        assert.deepEqual(Object.keys(partner.cells.standings), ['the-client']); // she never learns
+        assert.deepEqual(await acme.being.standings.them.ask('ping'), { pong: 'acme' }); // the other arc never moved
+        // 6. and back, as somebody else: a second invitation is a second relation,
+        //    sharing nothing with the first. the old one stays dead.
+        const second = (await acme.being.invite('partner-2'));
+        assert.notEqual(second.heir, first.heir);
+        assert.deepEqual(await partner.being.knock(second, 'ping'), { pong: 'partner-2' });
+        assert.equal(await partner.being.take('the-client-again', second), 'the-client-again');
+        assert.ok(isSilence(await partner.being.standings['the-client'].ask('ping')));
+        ledger(w.census(), undefined, 'the story');
+    });
+    for (const seed of [1, 2, 3]) {
+        t(`estate: sixty moves from seed ${seed}, the ledger a graph and every arc asked after each one`, async () => {
+            const w = await make();
+            const roll = rolls(seed);
+            const pick = (xs) => xs[Math.floor(roll() * xs.length)];
+            const hands = {};
+            const g = { seats: [], holds: [] };
+            let minted = 0;
+            const born = async (key) => (hands[key] = await w.boot(key, Member));
+            for (const key of ['M1', 'M2', 'M3'])
+                await born(key);
+            let before;
+            // Every move that is legal right now, as a thunk. A move that would not
+            // be legal is not written down, so the chapter never asserts on a
+            // question the spec does not answer.
+            const moves = () => {
+                const keys = Object.keys(hands);
+                const out = [];
+                // invite: a fresh occupant arc, and nothing of the guest's in it
+                out.push(async () => {
+                    const host = pick(keys);
+                    const id = `o${++minted}`;
+                    const inv = (await hands[host].being.invite(id));
+                    assert.equal(inv.ward, hands[host].pk);
+                    assert.match(inv.heir, HEX64);
+                    g.seats.push({ host, id, inv, guest: null, answered: false, live: true, taken: false });
+                    return `${host} invites ${id}`;
+                });
+                // knock: the guest an unspent seat gets is anyone but the host; a
+                // spent one only ever answers the one who spent it. Once she has
+                // taken it the invitation is not a knock any more -- it joins the
+                // standing's lane, and is exactly as alive as the standing is.
+                for (const s of g.seats) {
+                    out.push(async () => {
+                        const guest = s.guest ?? pick(keys.filter((k) => k !== s.host));
+                        const hold = g.holds.find((h) => h.seat === s);
+                        const back = await hands[guest].being.knock(s.inv, 'ping');
+                        if (s.live && (s.guest === null || s.guest === guest) && (hold === undefined || hold.live)) {
+                            assert.deepEqual(back, { pong: s.id }, `${guest} knocking ${s.host}/${s.id}`);
+                            s.guest = guest;
+                            s.answered = true;
+                        }
+                        else
+                            assert.ok(isSilence(back), `${guest} knocking ${s.host}/${s.id} should be silence`);
+                        return `${guest} knocks ${s.host}/${s.id}`;
+                    });
+                    // a stranger on a spent seat: silence, and nothing rebinds
+                    if (s.guest !== null)
+                        out.push(async () => {
+                            const other = keys.filter((k) => k !== s.host && k !== s.guest);
+                            if (!other.length)
+                                return 'no stranger to try';
+                            const who = pick(other);
+                            assert.ok(isSilence(await hands[who].being.knock(s.inv, 'ping')), `${who} should not get in on ${s.host}/${s.id}`);
+                            return `${who} is refused at ${s.host}/${s.id}`;
+                        });
+                }
+                // take: only after an answer, only once. the far side may have kicked
+                // her in between -- take reads the knock record, and still births one.
+                for (const s of g.seats.filter((s) => s.answered && !s.taken))
+                    out.push(async () => {
+                        const id = `s${++minted}`;
+                        assert.equal(await hands[s.guest].being.take(id, s.inv), id);
+                        s.taken = true;
+                        g.holds.push({ owner: s.guest, id, seat: s, live: true });
+                        assert.equal(await hands[s.guest].being.take(`${id}-again`, s.inv), null); // spent for her
+                        return `${s.guest} takes ${s.host}/${s.id} as ${id}`;
+                    });
+                // drop: hers to drop, and the host is never told
+                for (const h of g.holds.filter((h) => h.live))
+                    out.push(async () => {
+                        hands[h.owner].being.standings.remove(h.id);
+                        h.live = false;
+                        assert.equal(hands[h.owner].being.standings[h.id], undefined);
+                        return `${h.owner} drops ${h.id}`;
+                    });
+                // kick: the host's, and the guest is never told either
+                for (const s of g.seats.filter((s) => s.live))
+                    out.push(async () => {
+                        hands[s.host].being.occupants.remove(s.id);
+                        s.live = false;
+                        return `${s.host} kicks ${s.id}`;
+                    });
+                // a new being: an estate grows
+                if (keys.length < 6)
+                    out.push(async () => (await born(`M${keys.length + 1}`), `M${keys.length + 1} is booted`));
+                // a ward moves harbor, under everyone standing on it
+                out.push(async () => {
+                    const who = pick(keys);
+                    await w.migrate(who);
+                    return `${who}'s ward moves harbor`;
+                });
+                // weather: the host's door is gone. unreached, never silence, and the
+                // relation is exactly where it was when it comes back.
+                // weather: the host's door is gone. unreached, never silence, and the
+                // relation is exactly where it was when it comes back. The move is on
+                // the list under every topology even where there is nothing to cut,
+                // because the list is the script: a move missing in one world would
+                // make it a different script, and the three could not be compared.
+                for (const h of g.holds.filter((h) => h.live && h.seat.live))
+                    out.push(async () => {
+                        if (!canDown)
+                            return 'nothing to cut inside one ward';
+                        hands[h.seat.host].down = true;
+                        assert.ok(isUnreached(await hands[h.owner].being.standings[h.id].ask('ping')), `${h.owner}/${h.id} should be unreached`);
+                        hands[h.seat.host].down = false;
+                        return `${h.seat.host} is cut and comes back`;
+                    });
+                return out;
+            };
+            // Every arc in the model, asked. This is where the ledger stops being
+            // bookkeeping and becomes what the door actually does.
+            const sweep = async (step) => {
+                for (const h of g.holds) {
+                    const standing = hands[h.owner].being.standings[h.id];
+                    if (!h.live) {
+                        assert.equal(standing, undefined, `step ${step}: ${h.owner}'s dropped ${h.id} is still there`);
+                        continue;
+                    }
+                    const out = await standing.ask('ping');
+                    if (h.seat.live)
+                        assert.deepEqual(out, { pong: h.seat.id }, `step ${step}: ${h.owner}/${h.id} -> ${h.seat.host}/${h.seat.id}`);
+                    else
+                        assert.ok(isSilence(out), `step ${step}: ${h.owner}/${h.id} is kicked and should be silence`);
+                }
+            };
+            // The trace is the seed's own account of itself: a red run prints the
+            // moves that got there, which is the only thing that makes a generated
+            // sequence debuggable at all.
+            const trace = [];
+            const at = (step) => `seed ${seed} step ${step}\n  ${trace.join('\n  ')}`;
+            for (let step = 1; step <= 60; step++) {
+                const move = pick(moves());
+                try {
+                    trace.push(await move());
+                }
+                catch (e) {
+                    throw new Error(`${at(step)}\n  -> ${e.message}`, { cause: e });
+                }
+                const c = w.census();
+                ledger(c, before, at(step));
+                before = c;
+                await sweep(step).catch((e) => {
+                    throw new Error(`${at(step)}\n  -> ${e.message}`, { cause: e });
+                });
+            }
+            // and the estate that came out is the estate every topology comes out with
+            const print = fingerprint(g);
+            const key = `seed ${seed}`;
+            const first = landed.get(key);
+            if (!first)
+                landed.set(key, { by: label, print });
+            else
+                assert.equal(print, first.print, `the estate under ${label} is not the estate under ${first.by}: a being learned the topology`);
+        });
+    }
+}

package/dist/conformance/index.d.ts

@@ -0,0 +1,65 @@
+import type { BeingClass, Cells, Invitation, JsonObject } from '../being/types.ts';
+import { Printer, Shop, Customer, Echo, Member } from './beings.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;
+};
+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 };
+export type Runner = (name: string, opts: {
+    skip?: string | false;
+}, fn: () => Promise<void> | void) => void;
+export declare function conform(label: string, make: () => Promise<World>, { canDown, test }: {
+    canDown?: boolean;
+    test: Runner;
+}): void;
+export { conformStore } from './store.ts';
+export { conformReach, type FarSide } from './reach.ts';