nervur 0.19.2 → 0.20.0

package/dist/conformance/estate.js

@@ -1,388 +0,0 @@
-// 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 two 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 second is asked under one ward, under a ward per being, and under two
-// harbors, and that is where the promise of Quo is held: a being never learns
-// where the other one is, so every answer, after every move, under every
-// topology, is the answer the model wrote without knowing the topology
-// either. Held after every one of sixty moves, it is the promise at a scale a scene
-// cannot reach, and it is what makes a migration honest: if no answer can
-// tell the topology apart, moving a ward between harbors cannot be felt.
-// The model itself is the script's own bookkeeping and takes nothing from a
-// ward, so it is never compared with itself across topologies: that would
-// hold by construction and prove nothing.
-//
-// 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, told } from '../being/silence.js';
-import { Member } from './beings.js';
-import { HEX64 } from './index.js';
-const said = (x, w) => told(x) === w;
-// 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 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, g) {
-    const at = (why) => `${where}: ${why}`;
-    const heirsSeen = new Set();
-    // What the model knows, which the ward's own bookkeeping cannot tell it.
-    // Without this the ledger only checks the ward against itself, and a drift
-    // is caught late, if the sweep happens to ask the affected arc, or never.
-    if (g) {
-        for (const s of g.seats) {
-            const heir = c.wards[c.binds[s.host].ward].heirs[s.inv.heir];
-            if (!s.live) {
-                assert.ok(!heir, at(`${s.host} kicked ${s.id} and the heir is still held`));
-                assert.ok(!(s.id in c.binds[s.host].occupants), at(`${s.host} kicked ${s.id} and still holds the occupant`));
-                continue;
-            }
-            assert.ok(heir, at(`${s.host}'s live seat ${s.id} has no heir`));
-            assert.equal(heir.id, s.id, at(`the heir for ${s.host}/${s.id} is filed under ${heir.id}`));
-            // A seat nobody has knocked is a heir that has never spoken: fresh, and
-            // at zero. One that answered has spoken, so it is neither.
-            assert.equal(heir.fresh, !s.answered, at(`${s.host}/${s.id} is ${s.answered ? 'answered' : 'unknocked'} and its heir says fresh=${heir.fresh}`));
-            assert.equal(heir.mark === 0, !s.answered, at(`${s.host}/${s.id} is ${s.answered ? 'answered' : 'unknocked'} and its heir is at ${heir.mark}`));
-        }
-        for (const h of g.holds) {
-            const standing = c.binds[h.owner].standings[h.id];
-            if (!h.live) {
-                assert.ok(!standing, at(`${h.owner} dropped ${h.id} and the standing is still there`));
-                continue;
-            }
-            assert.ok(standing, at(`${h.owner}'s live standing ${h.id} is gone from the bind table`));
-            assert.equal(standing.heir, h.seat.inv.heir, at(`${h.owner}/${h.id} names a heir that is not the seat it was born on`));
-            // The count she has spent, against the number the far door honoured.
-            // Her side is never behind: she takes a number, then it crosses.
-            const far = c.wards[c.binds[h.seat.host].ward].heirs[h.seat.inv.heir];
-            if (far)
-                assert.ok(standing.seq >= far.mark, at(`${h.owner}/${h.id} counted ${standing.seq} and the far door has honoured ${far.mark}`));
-        }
-        // Every seat and hold the model knows about, and no relation the ward
-        // holds that the model never made.
-        const mine = new Set(g.seats.filter((s) => s.live).map((s) => `${s.host}/${s.id}`));
-        for (const [key, b] of Object.entries(c.binds))
-            for (const id of Object.keys(b.occupants))
-                assert.ok(mine.has(`${key}/${id}`), at(`${key} holds an occupant ${id} the model never made`));
-    }
-    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, and she is not
-        //    told until she asks: then the door, under the key it bound for her,
-        //    says removed, and only to her.
-        acme.being.occupants.remove('partner-1');
-        assert.ok(said(await partner.being.standings['the-client'].ask('ping'), 'removed'));
-        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(said(await partner.being.standings['the-client'].ask('ping'), 'removed'));
-        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: [] };
-            // What this run actually got to. A generated walk protects only the
-            // states it reaches, and a list of assertions nobody ran is a list of
-            // assertions nobody has. Every case named here is checked off as it
-            // fires and the run fails at the end if one never did.
-            const reached = new Set();
-            const MUST = [
-                'a kicked seat knocked by the guest it bound, who hears removed',
-                'a standing dropped by its owner, whose host is never told',
-                'a seat kicked by its host, whose guest is never told',
-                'a relation taken, so it lives in the standing and not the knock',
-                'a ward moved to another harbor under everyone standing on it',
-            ];
-            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) {
-                    const knock = 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');
-                        // Whether this knock is heard at all: the seat has no guest yet,
-                        // or its guest is this one, and nothing of hers has dropped the
-                        // key the door would bind her by. A hold exists only where a
-                        // guest does, so the two tests are one condition and not two.
-                        // Then the seat says which answer: alive is the pong, kicked is
-                        // `removed`, and unheard is silence whichever it is.
-                        const speaks = (s.guest === null || s.guest === guest) && (hold === undefined || hold.live);
-                        if (!speaks)
-                            assert.ok(isSilence(back), `${guest} knocking ${s.host}/${s.id} should be silence`);
-                        else if (s.live) {
-                            assert.deepEqual(back, { pong: s.id }, `${guest} knocking ${s.host}/${s.id}`);
-                            s.guest = guest;
-                            s.answered = true;
-                        }
-                        else {
-                            assert.ok(said(back, 'removed'), `${guest} knocking kicked ${s.host}/${s.id} should hear removed`);
-                            reached.add('a kicked seat knocked by the guest it bound, who hears removed');
-                        }
-                        return `${guest} knocks ${s.host}/${s.id}`;
-                    };
-                    out.push(knock);
-                    // Weighted, not written twice: the case this move exists to protect
-                    // is a seat kicked after it answered and before it was taken, and a
-                    // uniform walk over a list that grows with every invitation reaches
-                    // it by luck if at all. Three entries make it likely by
-                    // construction, and the count at the end of the run makes it
-                    // certain: a walk that never got there fails rather than passing
-                    // quietly on an assertion that never ran.
-                    if (!s.live && s.answered && !s.taken)
-                        out.push(knock, knock);
-                    // 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 });
-                        reached.add('a relation taken, so it lives in the standing and not the knock');
-                        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;
-                        reached.add('a standing dropped by its owner, whose host is never told');
-                        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;
-                        reached.add('a seat kicked by its host, whose guest is never told');
-                        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);
-                    reached.add('a ward moved to another harbor under everyone standing on it');
-                    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. 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(said(out, 'removed'), `step ${step}: ${h.owner}/${h.id} is kicked and should hear removed`);
-                }
-            };
-            // 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  ')}`;
-            // Whatever fails inside a step carries the trace that got there. One
-            // wrapper, so the move and the sweep are decorated the same way and a
-            // third thing added to a step cannot be decorated a fourth.
-            const inStep = async (step, work) => {
-                try {
-                    return await work();
-                }
-                catch (e) {
-                    throw new Error(`${at(step)}\n  -> ${e.message}`, { cause: e });
-                }
-            };
-            for (let step = 1; step <= 60; step++) {
-                const move = pick(moves());
-                // The move that failed goes into the trace before it runs, not after
-                // it returns: a move names itself as it finishes, so a throw left the
-                // trace ending at the last move that worked and saying nothing about
-                // the one that did not. It is written in twice, provisionally and
-                // then as it named itself, and the provisional line goes when the
-                // real one lands.
-                trace.push(`step ${step}: a move that has not said what it did`);
-                const did = await inStep(step, move);
-                trace[trace.length - 1] = did;
-                const c = w.census();
-                ledger(c, before, at(step), g);
-                before = c;
-                await inStep(step, () => sweep(step));
-            }
-            // And the walk is held to having gone somewhere. Sixty moves under one
-            // seed is a sample, not a proof, so the states the chapter is written
-            // to protect are named and counted: a run that never reached one has
-            // not tested it, and says so here rather than passing on an assertion
-            // that never ran.
-            const missed = MUST.filter((what) => !reached.has(what));
-            assert.deepEqual(missed, [], `seed ${seed} never reached: ${missed.join('; ')}\n  ${trace.join('\n  ')}`);
-        });
-    }
-}

package/dist/conformance/index.d.ts

@@ -1,80 +0,0 @@
-import type { BeingClass, Cells, Invitation, JsonObject } from '../being/types.ts';
-import { Printer, Shop, Customer, Echo, Maker, 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>;
-    owner(key: string): (method?: string, args?: JsonObject) => Promise<unknown>;
-} & Partial<Standing> & Partial<Refusing>;
-export type Standing = {
-    partition(key: string): JsonObject;
-    restart(key: string, partition?: JsonObject): Promise<void>;
-};
-export type Refusing = {
-    refuse(key: string, on: boolean): void;
-};
-export { Printer, Shop, Customer, Echo, Maker, Member };
-export declare const HEX64: RegExp;
-export type Runner = (name: string, opts: {
-    skip?: string | false;
-}, fn: () => Promise<void> | void) => void;
-export type Made = {
-    lends?: Record<string, string>;
-};
-export declare function conform(label: string, make: (made?: Made) => Promise<World>, { canDown, canLend, canRestart, canRefuse, test }: {
-    canDown?: boolean;
-    canLend?: boolean;
-    canRestart?: boolean;
-    canRefuse?: boolean;
-    test: Runner;
-}): void;
-export { conformStore } from './store.ts';
-export { conformReach, type FarSide } from './reach.ts';