nervur 0.20.3 → 0.21.0

package/src/proof/expect.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+// The few assertions a scene needs, with no platform under them, so the
+// same scene runs in Node's runner and inside any other engine.
+export type Expect = {
+  equal(actual: unknown, expected: unknown, message?: string): void;
+  same(actual: unknown, expected: unknown, message?: string): void;
+  ok(value: unknown, message?: string): void;
+};
+
+const fail = (message: string | undefined, detail: string): never => {
+  throw new Error(`${message ? `${message}: ` : ''}${detail}`);
+};
+
+export const expect: Expect = {
+  equal: (actual, expected, message) => {
+    if (!Object.is(actual, expected)) fail(message, `${String(actual)} is not ${String(expected)}`);
+  },
+  same: (actual, expected, message) => {
+    const [a, b] = [JSON.stringify(actual), JSON.stringify(expected)];
+    if (a !== b) fail(message, `${a} is not ${b}`);
+  },
+  ok: (value, message) => {
+    if (!value) fail(message, 'not true');
+  },
+};

package/src/proof/index.ts

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur/proof`: the suites a body of a stranger's passes to be supported,
+// the kit's own. Each is a list of scenes, a title and a function, run by
+// whatever runner the stranger keeps, in the engine the body is for:
+//
+//   for (const [title, scene] of memoryScenes('S3Memory', make, expect, half)) test(title, scene);
+//
+// `expect` throws on the first assertion that fails. The law's scenes stand
+// harbors on a stranger's bodies and hold the unpacking law over them.
+export { entropyScenes, custodyScenes, loaderScenes, memoryScenes, type Cut, type Scene } from './contracts.ts';
+export { expect, type Expect } from './expect.ts';
+export { law, lawScenes, type Bodies, type Terrain } from './law.ts';

package/src/proof/law.ts

@@ -0,0 +1,352 @@
+// SPDX-License-Identifier: Apache-2.0
+// The unpacking law, as scenes any terrain's bodies run: a harbor is one
+// package. Only the seed and the terrain's bodies stand outside it, the
+// terrain keeps sealed bytes it cannot read, and the seed opens the memory,
+// the dock stands the catalogue, the catalogue loads the modules her cells
+// name, the faculties and every ward stand from cells, and the dock lends.
+// It names no runtime, so it bundles.
+import { Being, Faculty, type Asker, type Invitation, type JsonObject } from '../being/index.ts';
+import { Memory, type Custody, type Module } from '../contract/index.ts';
+import { copyPackage, rootLine, type Harbor } from '../harbor/index.ts';
+import { CryptoEntropy, HeldLoader, World } from '../pointer/index.ts';
+import type { Expect } from './expect.ts';
+
+// The bodies a harbor stands on, and the same keeping as a new process
+// would build it.
+export type Bodies = { custody: Custody; memory: Memory };
+export type Terrain = { name: string; make(): Bodies; again(bodies: Bodies): Bodies };
+
+abstract class Echoes extends Faculty {
+  static override kind = 'org.example.echoes';
+}
+class Echo extends Echoes {
+  static override kind = 'org.example.echo';
+  static override asks = { echo: {} };
+  echo(args: JsonObject, asker: Asker): JsonObject {
+    return { echoed: args.text ?? null, to: asker.id ?? null };
+  }
+}
+
+class Shop extends Being {
+  static override kind = 'org.example.shop';
+  static override cells = { sold: [] as string[] };
+  static override asks = { buy: {} };
+  buy(args: JsonObject, asker: Asker): JsonObject {
+    (this.cells.sold as string[]).push(`${String(args.item)} to ${asker.id ?? 'nobody'}`);
+    return { bought: args.item ?? null };
+  }
+}
+
+class Customer extends Being {
+  static override kind = 'org.example.customer';
+  static override asks = { join: {}, buy: {}, echo: {}, spoil: {} };
+  spoil(): JsonObject {
+    try {
+      this.cells.when = new Date() as unknown as string;
+      return { kept: true };
+    } catch {
+      return { refused: true };
+    }
+  }
+  async join(args: JsonObject): Promise<JsonObject> {
+    return { joined: await this.stance.standings.take('shop', args.invitation as Invitation) };
+  }
+  async buy(args: JsonObject): Promise<JsonObject> {
+    return { said: ((await this.stance.standings.get('shop')?.ask('buy', args)) ?? null) as JsonObject };
+  }
+  async echo(args: JsonObject): Promise<JsonObject> {
+    if (!this.stance.standings.get('echo')) await this.stance.lend(Echoes, 'echo');
+    return { said: ((await this.stance.standings.get('echo')?.ask('echo', args)) ?? null) as JsonObject };
+  }
+}
+
+// One set of classes for every scene in a bundle, since a bundler renames
+// a second class of the same name and a row resolves a class by its name.
+export const classes = [Echo, Shop, Customer];
+export const law: Module = { module: 'org.example.law', version: '1', classes };
+
+// A harbor of the world whose catalogue runs the law's module.
+export const standOne = async (world: World, name: string, parts: Partial<Bodies> = {}): Promise<Harbor> => {
+  const harbor = await world.harbor(name, [law], parts);
+  await harbor.root('ask', { being: 'catalogue', method: 'add', args: { from: law.module } });
+  return harbor;
+};
+const CATALOGUE = { catalogue: { class: 'org.nervur.catalogue', public: false, absent: false } };
+const NONE = { wards: {}, routes: {} };
+
+// Every byte a memory is handed, seen from outside it.
+class Watched extends Memory {
+  readonly inner: Memory;
+  readonly seen: { place: string; name: string; bytes: Uint8Array | null }[] = [];
+  constructor(inner: Memory) {
+    super();
+    this.inner = inner;
+  }
+  read(place: string): Promise<Map<string, Uint8Array>> {
+    return this.inner.read(place);
+  }
+  write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void> {
+    for (const [name, bytes] of entries) this.seen.push({ place, name, bytes: bytes && bytes.slice() });
+    return this.inner.write(place, entries);
+  }
+  places(): Promise<string[]> {
+    return this.inner.places();
+  }
+  forget(place: string): Promise<void> {
+    return this.inner.forget(place);
+  }
+}
+
+const utf8 = (text: string): Uint8Array => new TextEncoder().encode(text);
+const holds = (bytes: Uint8Array, part: Uint8Array): boolean => {
+  outer: for (let at = 0; at + part.length <= bytes.length; at += 1) {
+    for (let k = 0; k < part.length; k += 1) if (bytes[at + k] !== part[k]) continue outer;
+    return true;
+  }
+  return false;
+};
+const hex = (bytes: Uint8Array): string => [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+
+const census = async (harbor: Harbor, ward?: string): Promise<unknown> => {
+  const out = (await (ward === undefined ? harbor.root() : harbor.ward(ward)!.root())) as { object?: unknown; notes?: unknown };
+  return (out as { notes?: unknown }).notes;
+};
+
+// Acme hosts a shop; home opens an echo, hosts alice under a drawn seed and
+// bob under a named one, and alice takes the shop and lends the echo.
+const stand = async (world: World, t: Terrain, bodies: { acme: Bodies; home: Bodies }, seed: string, expect: Expect): Promise<void> => {
+  const acme = await standOne(world, 'acme', bodies.acme);
+  const home = await standOne(world, 'home', bodies.home);
+  expect.same(home.names, [], `${t.name}: a new harbor hosts nobody`);
+  expect.same(await home.root('open', { key: 'echo', class: 'org.example.echo' }), { opened: 'echo' });
+  expect.same(await home.root('host', { ward: 'alice' }), { hosted: 'alice' });
+  expect.same(await home.root('host', { ward: 'bob', seed }), { hosted: 'bob' });
+  expect.same(await home.ward('alice')!.root('boot', { key: 'me', class: 'org.example.customer' }), { booted: 'me' });
+  expect.same(await acme.root('host', { ward: 'shop' }), { hosted: 'shop' });
+  expect.same(await acme.ward('shop')!.root('boot', { key: 'shop', class: 'org.example.shop' }), { booted: 'shop' });
+  const invitation = (await acme.ward('shop')!.root('invite', { being: 'shop', id: 'alice' })) as JsonObject;
+  const me = async (method: string, args: JsonObject = {}): Promise<unknown> => ((await world.get('home').ward('alice')!.root('ask', { being: 'me', method, args })) as { answer: unknown }).answer;
+  expect.same(await me('join', { invitation }), { joined: 'shop' });
+  expect.same(await me('buy', { item: 'tea' }), { said: { bought: 'tea' } });
+  expect.same(await me('echo', { text: 'hi' }), { said: { echoed: 'hi', to: 'lent:1' } });
+};
+
+export const lawScenes = (t: Terrain, expect: Expect): [string, () => Promise<void>][] => [
+  [
+    `law on ${t.name}: empty memory unpacks a box ward holding the dock and her catalogue, and it wakes the same`,
+    async () => {
+      const bodies = t.make();
+      const world = new World();
+      const harbor = await world.harbor('h', [], bodies);
+      const pk = harbor.box.pk;
+      expect.same(await census(harbor), { pk, beings: CATALOGUE, failed: NONE });
+      const again = await world.restart('h', t.again(bodies));
+      expect.equal(again.box.pk, pk, 'the seed is the box ward');
+      expect.same(await census(again), { pk, beings: CATALOGUE, failed: NONE });
+    },
+  ],
+  [
+    `law on ${t.name}: a restart without a module the catalogue names stands, its beings absent, and wakes them when it returns`,
+    async () => {
+      const bodies = t.make();
+      const world = new World();
+      const harbor = await standOne(world, 'h', bodies);
+      expect.same(await harbor.root('open', { key: 'echo', class: 'org.example.echo' }), { opened: 'echo' });
+      expect.same(await harbor.root('host', { ward: 'w' }), { hosted: 'w' });
+      const lost = await world.restart('h', { ...t.again(bodies), loader: new HeldLoader([]) });
+      expect.same(lost.names, ['w'], 'the rest of the harbor stands');
+      expect.same(((await census(lost)) as { beings: Record<string, { absent: boolean }> }).beings.echo?.absent, true);
+      expect.same(await lost.root('ask', { being: 'catalogue', method: 'modules' }), {
+        answer: { [law.module]: { version: '1', running: null, from: law.module, failed: `not found at ${law.module}` } },
+      });
+      const again = await world.restart('h', { ...t.again(bodies), loader: new HeldLoader([law]) });
+      expect.same(((await census(again)) as { beings: Record<string, { absent: boolean }> }).beings.echo?.absent, false);
+      expect.same(await again.root('ask', { being: 'catalogue', method: 'modules' }), { answer: { [law.module]: { version: '1', running: '1', from: law.module } } });
+    },
+  ],
+  [
+    `law on ${t.name}: a module that does not load is removed only once no being stands on the kinds kept for it`,
+    async () => {
+      const bodies = t.make();
+      const world = new World();
+      const harbor = await standOne(world, 'h', bodies);
+      expect.same(await harbor.root('open', { key: 'echo', class: 'org.example.echo' }), { opened: 'echo' });
+      const lost = await world.restart('h', { ...t.again(bodies), loader: new HeldLoader([]) });
+      const remove = () => lost.root('ask', { being: 'catalogue', method: 'remove', args: { module: law.module } });
+      expect.same(await remove(), { answer: { error: 'a being stands on this module' } });
+      expect.same(await lost.root('unboot', { being: 'echo' }), { unbooted: 'echo' });
+      expect.same(await remove(), { answer: { removed: law.module } });
+      const after = await world.restart('h', t.again(bodies));
+      expect.same(await after.root('ask', { being: 'catalogue', method: 'modules' }), { answer: {} });
+    },
+  ],
+  [
+    `law on ${t.name}: a restart where a module splits a kind runs the modules before it, and the one alone stays out`,
+    async () => {
+      const bodies = t.make();
+      const world = new World();
+      const twin: Module = { module: 'org.example.twin', version: '1', classes: [] };
+      const harbor = await world.harbor('h', [law, twin], bodies);
+      for (const from of [law.module, twin.module]) await harbor.root('ask', { being: 'catalogue', method: 'add', args: { from } });
+      expect.same(await harbor.root('open', { key: 'echo', class: 'org.example.echo' }), { opened: 'echo' });
+      const split = await world.restart('h', { ...t.again(bodies), loader: new HeldLoader([law, { ...twin, version: '2', classes }]) });
+      expect.same(((await census(split)) as { beings: Record<string, { absent: boolean }> }).beings.echo?.absent, false, 'the module before it runs');
+      const modules = ((await split.root('ask', { being: 'catalogue', method: 'modules' })) as { answer: Record<string, { running: unknown; failed?: string }> }).answer;
+      expect.same([modules[law.module]?.running, modules[twin.module]?.running], ['1', null]);
+      expect.equal(modules[twin.module]?.failed, `kind org.example.echo is in modules ${law.module} and ${twin.module}`);
+    },
+  ],
+  [
+    `law on ${t.name}: a hosted ward whose place does not open fails alone, and a box ward whose place does not open fails the harbor`,
+    async () => {
+      const bodies = t.make();
+      const watched = new Watched(bodies.memory);
+      const world = new World();
+      const harbor = await standOne(world, 'h', { custody: bodies.custody, memory: watched });
+      expect.same(await harbor.root('host', { ward: 'good' }), { hosted: 'good' });
+      const from = watched.seen.length;
+      expect.same(await harbor.root('host', { ward: 'bad' }), { hosted: 'bad' });
+      const box = watched.seen[0]!.place;
+      const bad = watched.seen.slice(from).find((s) => s.place !== box)!.place;
+      const places = [bad, box];
+      const spoil = async (place: string): Promise<void> => {
+        const [[name, bytes]] = [...(await watched.inner.read(place))];
+        const changed = bytes!.slice();
+        changed[0] = changed[0]! ^ 1;
+        await watched.inner.write(place, new Map([[name!, changed]]));
+      };
+      await spoil(places[0]!);
+      const again = await world.restart('h', t.again(bodies));
+      expect.same(again.names, ['good']);
+      expect.same(((await census(again)) as { failed: unknown }).failed, { wards: { bad: 'an entry the package did not seal' }, routes: {} });
+      expect.same(await rootLine(again, { ward: 'bad' }), { error: 'the ward did not stand', reason: 'an entry the package did not seal' });
+      expect.same(await again.root('host', { ward: 'bad' }), { error: 'no such ward to host' }, 'its name and seed stay kept');
+      await spoil(places[1]!);
+      let refused = '';
+      await world.restart('h', t.again(bodies)).catch((e: Error) => (refused = e.message));
+      expect.equal(refused, 'an entry the package did not seal');
+    },
+  ],
+  [
+    `law on ${t.name}: a package carried to another memory stands the same harbor under the same seed`,
+    async () => {
+      const here = t.make();
+      const there = t.make();
+      const world = new World();
+      const harbor = await standOne(world, 'here', here);
+      expect.same(await harbor.root('open', { key: 'echo', class: 'org.example.echo' }), { opened: 'echo' });
+      expect.same(await harbor.root('host', { ward: 'alice' }), { hosted: 'alice' });
+      expect.same(await harbor.ward('alice')!.root('boot', { key: 'me', class: 'org.example.customer' }), { booted: 'me' });
+      const pks = { box: harbor.box.pk, alice: harbor.ward('alice')!.pk };
+      const carried = await copyPackage(here.memory, there.memory);
+      expect.equal(carried.length, 2, 'the box ward and alice');
+      const moved = await world.harbor('there', [law], { custody: here.custody, memory: there.memory, loader: new HeldLoader([law]) });
+      expect.same({ box: moved.box.pk, alice: moved.ward('alice')!.pk }, pks);
+      expect.same(((await census(moved, 'alice')) as { beings: JsonObject }).beings, { me: { class: 'org.example.customer', public: false, absent: false } });
+      expect.same(((await moved.ward('alice')!.root('ask', { being: 'me', method: 'echo', args: { text: 'moved' } })) as { answer: unknown }).answer, { said: { echoed: 'moved', to: 'lent:1' } });
+      const stranger = await world.harbor('stranger', [law], { custody: t.make().custody, memory: there.memory, loader: new HeldLoader([law]) });
+      expect.same(stranger.names, [], 'the bytes carried say nothing without the seed');
+    },
+  ],
+  [
+    `law on ${t.name}: the root sweeps every place the dock does not name, and nothing it does`,
+    async () => {
+      const bodies = t.make();
+      const world = new World();
+      const harbor = await standOne(world, 'h', bodies);
+      expect.same(await harbor.root('host', { ward: 'w' }), { hosted: 'w' });
+      const mine = (await bodies.memory.places()).sort();
+      expect.equal(mine.length, 2, 'the box ward and the ward it hosts');
+      await bodies.memory.write('ff'.repeat(16), new Map([['ab', new Uint8Array([1, 2, 3])]]));
+      expect.same(await harbor.root('sweep'), { swept: ['ff'.repeat(16)] });
+      expect.same((await bodies.memory.places()).sort(), mine, 'what the dock names stays');
+      expect.same(await harbor.root('sweep'), { swept: [] });
+      const again = await world.restart('h', t.again(bodies));
+      expect.same(again.names, ['w']);
+      expect.same(await again.ward('w')!.root('boot', { key: 'me', class: 'org.example.customer' }), { booted: 'me' });
+    },
+  ],
+  [
+    `law on ${t.name}: a restart stands the dock, its faculties, every hosted ward and its beings, and lends, with nobody asking`,
+    async () => {
+      const bodies = { acme: t.make(), home: t.make() };
+      const world = new World();
+      const seed = hex(new CryptoEntropy().draw(32));
+      await stand(world, t, bodies, seed, expect);
+      const before = world.get('home');
+      const pks = { box: before.box.pk, alice: before.ward('alice')!.pk, bob: before.ward('bob')!.pk, shop: world.get('acme').ward('shop')!.pk };
+      const beings = await census(before, 'alice');
+      const home = await world.restart('home', t.again(bodies.home));
+      const acme = await world.restart('acme', t.again(bodies.acme));
+      expect.same(home.names, ['alice', 'bob']);
+      expect.same(acme.names, ['shop']);
+      expect.same({ box: home.box.pk, alice: home.ward('alice')!.pk, bob: home.ward('bob')!.pk, shop: acme.ward('shop')!.pk }, pks);
+      expect.same(await census(home, 'alice'), beings);
+      expect.equal(home.box.partition.being('echo')?.class, 'org.example.echo');
+      const me = async (method: string, args: JsonObject = {}): Promise<unknown> => ((await home.ward('alice')!.root('ask', { being: 'me', method, args })) as { answer: unknown }).answer;
+      expect.same(await me('buy', { item: 'cake' }), { said: { bought: 'cake' } });
+      expect.same(await me('echo', { text: 'again' }), { said: { echoed: 'again', to: 'lent:1' } });
+      expect.same(acme.ward('shop')!.partition.being('shop')?.cells, { sold: ['tea to alice', 'cake to alice'] });
+    },
+  ],
+  [
+    `law on ${t.name}: every root ask is a step a restart may follow, and each step wakes whole`,
+    async () => {
+      const bodies = t.make();
+      const world = new World();
+      await world.harbor('h', [law], bodies);
+      const step = async (ask: (h: Harbor) => Promise<unknown>, want: unknown): Promise<Harbor> => {
+        expect.same(await ask(world.get('h')), want);
+        return world.restart('h', t.again(bodies));
+      };
+      await step((h) => h.root('ask', { being: 'catalogue', method: 'add', args: { from: law.module } }), { answer: { added: law.module, version: law.version } });
+      await step((h) => h.root('open', { key: 'echo', class: 'org.example.echo' }), { opened: 'echo' });
+      await step((h) => h.root('host', { ward: 'alice' }), { hosted: 'alice' });
+      await step((h) => h.ward('alice')!.root('boot', { key: 'me', class: 'org.example.customer' }), { booted: 'me' });
+      const h = await step(async (x) => ((await x.ward('alice')!.root('ask', { being: 'me', method: 'echo', args: { text: 'one' } })) as { answer: unknown }).answer, { said: { echoed: 'one', to: 'lent:1' } });
+      expect.same(((await h.ward('alice')!.root('ask', { being: 'me', method: 'echo', args: { text: 'two' } })) as { answer: unknown }).answer, { said: { echoed: 'two', to: 'lent:1' } });
+    },
+  ],
+  [
+    `law on ${t.name}: the terrain keeps the seed and sealed bytes, and reads no name, cell or hosted seed`,
+    async () => {
+      const home = t.make();
+      const watched = new Watched(home.memory);
+      const world = new World();
+      const seed = hex(new CryptoEntropy().draw(32));
+      await stand(world, t, { acme: t.make(), home: { custody: home.custody, memory: watched } }, seed, expect);
+      const harbor = world.get('home');
+      const secrets = [seed, ...harbor.dock.hosted.map((h) => h.seed)].map(utf8);
+      // Names of five bytes or more: a shorter one turns up in random bytes
+      // of this size often enough to fail a run by chance.
+      const words = ['alice', 'org.example', 'hosted', 'lent:1', 'customer'].map(utf8);
+      expect.ok(watched.seen.length > 0, 'the harbor kept something');
+      for (const { place, name, bytes } of watched.seen) {
+        expect.ok(/^[0-9a-f]+$/.test(place) && /^[0-9a-f]+$/.test(name), 'names are the kit hex');
+        if (bytes === null) continue;
+        for (const secret of secrets) expect.ok(!holds(bytes, secret), 'no hosted seed in the clear');
+        for (const word of words) expect.ok(!holds(bytes, word), 'no name or cell in the clear');
+        expect.ok(!holds(bytes, await home.custody.seed()), 'no harbor seed in memory');
+      }
+    },
+  ],
+  [
+    `law on ${t.name}: another seed finds nothing of the package, and a byte changed refuses to unpack`,
+    async () => {
+      const bodies = t.make();
+      const watched = new Watched(bodies.memory);
+      const world = new World();
+      const harbor = await standOne(world, 'h', { custody: bodies.custody, memory: watched });
+      expect.same(await harbor.root('host', { ward: 'w' }), { hosted: 'w' });
+      const last = [...watched.seen].reverse().find((s) => s.bytes !== null && s.bytes.length > 0)!;
+      const stranger = await world.harbor('stranger', [law], { custody: t.make().custody, memory: watched });
+      expect.same(stranger.names, [], 'another seed opens another package');
+      const bytes = last.bytes!.slice();
+      bytes[0] = bytes[0]! ^ 1;
+      await watched.inner.write(last.place, new Map([[last.name, bytes]]));
+      let refused = false;
+      await world.restart('h', t.again(bodies)).catch(() => (refused = true));
+      expect.ok(refused, 'a changed byte does not unpack');
+    },
+  ],
+];