@quo-systems/quo 0.1.0

package/src/conformance/estate.ts

@@ -0,0 +1,339 @@
+// 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.ts';
+import { isSilence, isUnreached } from '../being/silence.ts';
+import type { Invitation } from '../being/types.ts';
+import { Member } from './beings.ts';
+import type { Census, Handle, Runner, World } from './index.ts';
+
+const HEX64 = /^[0-9a-f]{64}$/;
+
+// 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 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: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+const fingerprint = (g: Graph): string =>
+  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<string, { by: string; print: string }>();
+
+// ---- 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) {
+  const at = (why: string) => `${where}: ${why}`;
+  const heirsSeen = new Set<string>();
+
+  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 -- 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 = <T>(xs: T[]): T => xs[Math.floor(roll() * xs.length)];
+      const hands: Record<string, Handle<Member>> = {};
+      const g: Graph = { seats: [], holds: [] };
+      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) {
+          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: 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(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: string[] = [];
+      const at = (step: number) => `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 as Error).message}`, { cause: e });
+        }
+        const c = w.census();
+        ledger(c, before, at(step));
+        before = c;
+        await sweep(step).catch((e: Error) => {
+          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`);
+    });
+  }
+}