nervur 0.19.2 → 0.20.0

package/src/conformance/estate.ts

@@ -1,412 +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.ts';
-import { isSilence, isUnreached, told } from '../being/silence.ts';
-import type { Invitation } from '../being/types.ts';
-import { Member } from './beings.ts';
-import { HEX64 } from './index.ts';
-import type { Census, Handle, Runner, World } from './index.ts';
-
-const said = (x: unknown, w: string): boolean => told(x) === w;
-
-// One occupant arc, as the host holds it. `guest` is null until somebody
-// knocks; `live` goes false when she is kicked. Both are the host's business
-// alone -- the guest is never told either one.
-type Seat = { host: string; id: string; inv: Invitation; guest: string | null; answered: boolean; live: boolean; taken: boolean };
-// One standing arc, as the guest holds it. It carries the seat it was born
-// on, because what an ask on it should come back with is the host's name for
-// her, and whether the host has since kicked her.
-type Hold = { owner: string; id: string; seat: Seat; live: boolean };
-type Graph = { seats: Seat[]; holds: Hold[] };
-
-// 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: number) => () => {
-  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: Census, before: Census | undefined, where: string, g?: Graph) {
-  const at = (why: string) => `${where}: ${why}`;
-  const heirsSeen = new Set<string>();
-
-  // 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: string, make: () => Promise<World>, { canDown, test }: { canDown: boolean; test: Runner }) {
-  const t = (name: string, fn: () => Promise<void> | void) => 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<Member>('ACME', Member);
-    const partner = await w.boot<Member>('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 = <T>(xs: T[]): T => xs[Math.floor(roll() * xs.length)];
-      const hands: Record<string, Handle<Member>> = {};
-      const g: Graph = { 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<string>();
-      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: string) => (hands[key] = await w.boot<Member>(key, Member));
-      for (const key of ['M1', 'M2', 'M3']) await born(key);
-      let before: Census | undefined;
-
-      // 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 = (): (() => Promise<string>)[] => {
-        const keys = Object.keys(hands);
-        const out: (() => Promise<string>)[] = [];
-
-        // 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: number) => {
-        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: string[] = [];
-      const at = (step: number) => `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 <T>(step: number, work: () => Promise<T>): Promise<T> => {
-        try {
-          return await work();
-        } catch (e) {
-          throw new Error(`${at(step)}\n  -> ${(e as Error).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  ')}`);
-    });
-  }
-}