nervur 0.20.3 → 0.21.0

package/dist/proof/law.js

@@ -0,0 +1,345 @@
+// 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 } from '../being/index.js';
+import { Memory } from '../contract/index.js';
+import { copyPackage, rootLine } from '../harbor/index.js';
+import { CryptoEntropy, HeldLoader, World } from '../pointer/index.js';
+class Echoes extends Faculty {
+    static kind = 'org.example.echoes';
+}
+class Echo extends Echoes {
+    static kind = 'org.example.echo';
+    static asks = { echo: {} };
+    echo(args, asker) {
+        return { echoed: args.text ?? null, to: asker.id ?? null };
+    }
+}
+class Shop extends Being {
+    static kind = 'org.example.shop';
+    static cells = { sold: [] };
+    static asks = { buy: {} };
+    buy(args, asker) {
+        this.cells.sold.push(`${String(args.item)} to ${asker.id ?? 'nobody'}`);
+        return { bought: args.item ?? null };
+    }
+}
+class Customer extends Being {
+    static kind = 'org.example.customer';
+    static asks = { join: {}, buy: {}, echo: {}, spoil: {} };
+    spoil() {
+        try {
+            this.cells.when = new Date();
+            return { kept: true };
+        }
+        catch {
+            return { refused: true };
+        }
+    }
+    async join(args) {
+        return { joined: await this.stance.standings.take('shop', args.invitation) };
+    }
+    async buy(args) {
+        return { said: ((await this.stance.standings.get('shop')?.ask('buy', args)) ?? null) };
+    }
+    async echo(args) {
+        if (!this.stance.standings.get('echo'))
+            await this.stance.lend(Echoes, 'echo');
+        return { said: ((await this.stance.standings.get('echo')?.ask('echo', args)) ?? null) };
+    }
+}
+// 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: 'org.example.law', version: '1', classes };
+// A harbor of the world whose catalogue runs the law's module.
+export const standOne = async (world, name, parts = {}) => {
+    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 {
+    inner;
+    seen = [];
+    constructor(inner) {
+        super();
+        this.inner = inner;
+    }
+    read(place) {
+        return this.inner.read(place);
+    }
+    write(place, entries) {
+        for (const [name, bytes] of entries)
+            this.seen.push({ place, name, bytes: bytes && bytes.slice() });
+        return this.inner.write(place, entries);
+    }
+    places() {
+        return this.inner.places();
+    }
+    forget(place) {
+        return this.inner.forget(place);
+    }
+}
+const utf8 = (text) => new TextEncoder().encode(text);
+const holds = (bytes, part) => {
+    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) => [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+const census = async (harbor, ward) => {
+    const out = (await (ward === undefined ? harbor.root() : harbor.ward(ward).root()));
+    return out.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, t, bodies, seed, expect) => {
+    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' }));
+    const me = async (method, args = {}) => (await world.get('home').ward('alice').root('ask', { being: 'me', method, args })).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, expect) => [
+    [
+        `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)).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)).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: '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)).beings.echo?.absent, false, 'the module before it runs');
+            const modules = (await split.root('ask', { being: 'catalogue', method: 'modules' })).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) => {
+                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)).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) => (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')).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' } })).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, args = {}) => (await home.ward('alice').root('ask', { being: 'me', method, args })).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, want) => {
+                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' } })).answer, { said: { echoed: 'one', to: 'lent:1' } });
+            expect.same((await h.ward('alice').root('ask', { being: 'me', method: 'echo', args: { text: 'two' } })).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');
+        },
+    ],
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nervur",
-  "version": "0.20.3",
+  "version": "0.21.0",
   "description": "Nervur's kit of Quo: an object asks another object and gets an answer, without knowing where it is.",
   "keywords": [
     "quo",
@@ -46,13 +46,18 @@
     "./http": {
       "types": "./dist/http/index.d.ts",
       "default": "./dist/http/index.js"
+    },
+    "./proof": {
+      "types": "./dist/proof/index.d.ts",
+      "default": "./dist/proof/index.js"
     }
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "check": "tsc -p tsconfig.json && npm run build && node ../../test.mjs \"test/unit/*.test.ts\" \"test/e2e/*.test.ts\"",
     "deep": "node ../../test.mjs \"test/terrain/*.test.ts\"",
-    "cover": "node --test --test-timeout=60000 --experimental-test-coverage --test-coverage-exclude=\"**/dist/**\" --test-coverage-exclude=\"**/test/**\" --test-coverage-exclude=\"**/src/stand/**\" --test-coverage-exclude=\"**/src/browser/**\" --test-coverage-exclude=\"**/src/edge/**\" --test-coverage-exclude=\"../../quo/**\" --test-coverage-lines=99 --test-coverage-branches=93 --test-coverage-functions=95 \"test/unit/*.test.ts\" \"test/e2e/*.test.ts\"",
+    "cover": "node test/cover.mjs",
+    "mutate": "node test/mutate.mjs",
     "prepublishOnly": "test \"$NERVUR_GATED\" = 1 || { echo 'a publish is /release, from the root, on the human'\"'\"'s word' >&2; exit 1; }"
   },
   "engines": {
@@ -70,5 +75,8 @@
     "README.md",
     "LICENSE",
     "NOTICE"
-  ]
+  ],
+  "devDependencies": {
+    "wrangler": "^4.134.0"
+  }
 }

package/src/cli/command.ts

@@ -23,6 +23,10 @@
 //                                                   printed, for the worker's
 //                                                   NERVUR_SEED, and its sealed
 //                                                   package written to the file
+//   nervur edge dev <file> [--port P]               the harbor packed to the file and
+//                                                   run by the worker's own wrangler
+//                                                   dev, from this folder, at
+//                                                   http://127.0.0.1:P/quo
 //   nervur open   <key> <kind>                      a faculty stands in the box ward
 //   nervur host   <ward> [--seed S]                 a hosted ward stands
 //   nervur route  <ward pk> <address... | none>     where a ward is reached, in order
@@ -53,8 +57,12 @@ import type { RootRequest } from '../harbor/index.ts';
 import { WEB_OPENING } from '../line/index.ts';
 import { harborDir, isFile } from '../node/index.ts';
 import { readAt, webAddress } from '../quo/index.ts';
+import { edgeDev } from './edge.ts';
 import { carry, isServed, land, open, pack, request, serve } from './harbor.ts';
 
+// Where `edge dev` answers unless --port names another, wrangler's own.
+const EDGE_PORT = 8787;
+
 const USAGE = 'usage: nervur <init|serve|module|modules|census|sweep|open|host|route|reach|boot|unboot|public|invite|ask|own|disown|pilot|export|import|edge> [args] [--dir D] [--ward W] [--via V] [--seed S] [--with-seed] [--host H] [--port P]';
 const FLAGS = new Set(['dir', 'ward', 'via', 'seed', 'host', 'port']);
 // The one flag that stands alone, since what it names is a yes.
@@ -182,10 +190,16 @@ export const main = async (argv: string[], env: Record<string, string | undefine
     return out({ landed: await land(dir, JSON.parse(text)) });
   }
   if (command === 'edge') {
-    if (words[0] !== 'pack' || words.length !== 2) throw new Error('edge takes pack and a file');
-    if (flags.via !== undefined) throw new Error('edge pack reads this folder, so it takes no --via');
+    if ((words[0] !== 'pack' && words[0] !== 'dev') || words.length !== 2) throw new Error('edge takes pack or dev, and a file');
+    if (flags.via !== undefined) throw new Error(`edge ${words[0]} reads this folder, so it takes no --via`);
     if (await isServed(dir)) throw new Error(`a harbor is served from ${dir}: stop it first`);
-    return out(await pack(dir, words[1]!));
+    if (words[0] === 'pack') return out(await pack(dir, words[1]!));
+    const dev = await edgeDev(dir, words[1]!, process.cwd(), flags.port === undefined ? EDGE_PORT : Number(flags.port));
+    const stop = (): void => void dev.close().then(() => process.exit(0));
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    print(JSON.stringify({ at: dev.at, places: dev.places }));
+    return SERVING;
   }
   if (command === 'serve') {
     if (words.length > 0) throw new Error('serve takes no argument');

package/src/cli/edge.ts

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur edge dev`: an edge harbor on this machine, as it will stand on
+// Cloudflare. The harbor of a folder is packed into the file the worker
+// imports, and the worker's own `wrangler dev` runs it, in the folder the
+// command runs from, with the seed handed as `NERVUR_SEED` through the
+// environment so no listing of processes shows it. The object's storage is
+// kept under `.nervur-edge` there, so a harbor landed once stands again
+// across restarts, as it does on Cloudflare.
+//
+// wrangler is the worker's tool and never the kit's: the one who deploys
+// an edge has it already, and `edge dev` finds it where npm put it.
+import { spawn, type ChildProcess } from 'node:child_process';
+import { join } from 'node:path';
+import { pack } from './harbor.ts';
+
+export const EDGE_STATE = '.nervur-edge';
+const READY_TRIES = 240;
+const READY_EVERY = 250;
+
+export type EdgeDev = { readonly at: string; readonly places: number; close(): Promise<void> };
+
+const answers = (url: string): Promise<boolean> =>
+  fetch(url).then(
+    () => true,
+    () => false,
+  );
+
+// Resolved once wrangler answers at `url`, rejected once it exits or never
+// answers.
+const ready = async (child: ChildProcess, url: string, said: () => string): Promise<void> => {
+  let gone = false;
+  child.once('exit', () => (gone = true));
+  for (let i = 0; i < READY_TRIES; i += 1) {
+    if (gone) throw new Error(`wrangler dev exited: ${said()}`);
+    if (await answers(url)) return;
+    await new Promise((r) => setTimeout(r, READY_EVERY));
+  }
+  throw new Error(`wrangler dev never answered at ${url}: ${said()}`);
+};
+
+export const edgeDev = async (dir: string, file: string, cwd: string, port: number): Promise<EdgeDev> => {
+  const { seed, places } = (await pack(dir, file)) as { seed: string; places: number };
+  const child = spawn('npx', ['--no-install', 'wrangler', 'dev', '--ip', '127.0.0.1', '--port', String(port), '--persist-to', join(cwd, EDGE_STATE), '--log-level', 'warn'], {
+    cwd,
+    env: { ...process.env, NERVUR_SEED: seed, CLOUDFLARE_INCLUDE_PROCESS_ENV: 'true' },
+    stdio: ['ignore', 'ignore', 'pipe'],
+    detached: true,
+  });
+  let err = '';
+  child.stderr!.on('data', (chunk: Buffer) => (err = `${err}${chunk.toString('utf8')}`.slice(-4000)));
+  const at = `http://127.0.0.1:${String(port)}/quo`;
+  const close = (): Promise<void> =>
+    new Promise((done) => {
+      if (child.exitCode !== null) return done();
+      child.once('exit', () => done());
+      process.kill(-child.pid!, 'SIGTERM');
+    });
+  try {
+    await ready(child, at, () => err);
+  } catch (e) {
+    await close();
+    throw e;
+  }
+  return { at, places, close };
+};

package/src/index.ts

@@ -47,7 +47,7 @@ export {
 
 // The pointer dock: a whole world in one process.
 export { CryptoEntropy, HeldCustody, HeldLoader, NoCarrier, PointerCarrier, PointerTerrain, SystemClock, VolatileMemory, World, type PointerParts } from './pointer/index.ts';
-export { NEUTRAL, WEB, WEB_OPENING, WEB_PUSH, WebDialer, webFaculty, webPush, type WebListen, type WebListener, type WebServe } from './line/index.ts';
+export { answerPost, NEUTRAL, WEB, WEB_OPENING, WEB_PUSH, WebDialer, webFaculty, webPush, type WebListen, type WebListener, type WebServe } from './line/index.ts';
 
 // The ground that fits everywhere, tried after any a platform entry adds.
 addGround(neutralGround);

package/src/proof/contracts.ts

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: Apache-2.0
+// The suites of the bodies, Custody, Memory, Entropy and Loader, as scenes
+// with no platform under them, so Node's runner, every engine and a
+// stranger's own runner hold a body to the same assertions.
+import { Custody, Entropy, Loader, Memory } from '../contract/index.ts';
+import type { Expect } from './expect.ts';
+
+export type Scene = [string, () => Promise<void>];
+
+const bytes = (...values: number[]): Uint8Array => Uint8Array.from(values);
+// A place as plain values, in name order, so two can be compared as JSON.
+const plain = (place: ReadonlyMap<string, Uint8Array>): [string, number[]][] => [...place].map(([n, b]): [string, number[]] => [n, [...b]]).sort(([a], [b]) => (a < b ? -1 : 1));
+
+// `make` gives two bodies over one keeping, as two runs would build them,
+// and a fresh keeping each call.
+export const custodyScenes = (name: string, make: () => [Custody, Custody], expect: Expect): Scene[] => [
+  [
+    `[contract] ${name} fulfils Custody: one seed of thirty-two bytes, the same every time`,
+    async () => {
+      const [custody, again] = make();
+      expect.ok(custody instanceof Custody);
+      const seed = await custody.seed();
+      expect.equal(seed.length, 32);
+      const first = [...seed];
+      seed.fill(0);
+      expect.same([...(await custody.seed())], first, 'a seed handed out is a copy');
+      expect.same([...(await again.seed())], first, 'another body over the keeping holds the same');
+      expect.ok([...(await make()[0].seed())].join() !== first.join(), 'another keeping holds another seed');
+      const [fresh, rival] = make();
+      const [a, b] = await Promise.all([fresh.seed(), rival.seed()]);
+      expect.same([...a], [...b], 'two first asks at once keep one seed');
+    },
+  ],
+];
+
+// `cut` is a body whose next keep stops partway, as a run that dies inside
+// one does, and `fresh` the memory a new run opens on the same keeping. A
+// body no crash can cut short, holding its places in one object, names
+// none.
+export type Cut = { cut: Memory; fresh: Memory };
+
+export const memoryScenes = (name: string, make: () => [Memory, Memory], expect: Expect, half?: () => Cut): Scene[] => [
+  [
+    `[contract] ${name} fulfils Memory: it names its places, and forgets one whole`,
+    async () => {
+      const [memory, again] = make();
+      expect.same(await memory.places(), []);
+      await memory.write('aa', new Map([['01', bytes(1)]]));
+      await memory.write('bb', new Map([['01', bytes(2)], ['02', bytes(3)]]));
+      expect.same([...(await again.places())].sort(), ['aa', 'bb']);
+      await memory.forget('aa');
+      expect.same(await again.places(), ['bb']);
+      expect.same(plain(await again.read('aa')), []);
+      await memory.forget('aa');
+      await memory.write('bb', new Map([['01', null], ['02', null]]));
+      expect.same(await again.places(), [], 'a place holding nothing is no place');
+    },
+  ],
+  ...(half
+    ? [
+        [
+          `[contract] ${name} fulfils Memory: a keep that stops partway is whole or is nothing`,
+          async () => {
+            const { cut, fresh } = half();
+            await cut.write('aa', new Map([['01', bytes(1)], ['02', bytes(2)]])).catch(() => undefined);
+            const before = plain(await fresh.read('aa'));
+            await cut.write('aa', new Map([['01', bytes(9)], ['02', null], ['03', bytes(3)]])).catch(() => undefined);
+            const after = JSON.stringify(plain(await fresh.read('aa')));
+            const whole = JSON.stringify(plain(new Map([['01', bytes(9)], ['03', bytes(3)]])));
+            expect.ok(after === JSON.stringify(before) || after === whole, `a keep cut short left ${after}`);
+          },
+        ] satisfies Scene,
+      ]
+    : []),
+  [
+    `[contract] ${name} fulfils Memory: a place read again holds what was kept, and nothing else`,
+    async () => {
+      const [memory, again] = make();
+      expect.ok(memory instanceof Memory);
+      expect.same(plain(await memory.read('aa')), []);
+      const written = bytes(1, 2, 3);
+      await memory.write('aa', new Map([['01', written], ['02', bytes(4)]]));
+      written[0] = 9;
+      await memory.write('bb', new Map([['01', bytes(5)]]));
+      await memory.write('aa', new Map([['02', null], ['03', bytes()], ['04', null]]));
+      const read = await again.read('aa');
+      expect.same(plain(read), [['01', [1, 2, 3]], ['03', []]]);
+      expect.ok(read.get('01') instanceof Uint8Array, 'an entry is bytes');
+      read.get('01')![0] = 7;
+      expect.same([...(await memory.read('aa')).get('01')!], [1, 2, 3], 'an entry handed out is a copy');
+      expect.same(plain(await again.read('bb')), [['01', [5]]]);
+      expect.same(plain(await again.read('cc')), []);
+    },
+  ],
+];
+
+export const entropyScenes = (name: string, make: () => Entropy, expect: Expect): Scene[] => [
+  [
+    `[contract] ${name} fulfils Entropy: bytes of the length asked, never the same twice`,
+    () => {
+      const entropy = make();
+      expect.ok(entropy instanceof Entropy);
+      expect.equal(entropy.draw(0).length, 0);
+      expect.equal(entropy.drawer(33).length, 33);
+      expect.ok([...entropy.draw(32)].join() !== [...entropy.draw(32)].join(), 'two draws differ');
+      return Promise.resolve();
+    },
+  ],
+];
+
+// `make` gives a loader, a name it finds a module by, and one it finds
+// nothing by.
+export const loaderScenes = (name: string, make: () => { loader: Loader; found: string; missing: string }, expect: Expect): Scene[] => [
+  [
+    `[contract] ${name} fulfils Loader: a module by its name, found again by the name it gives back, and nothing else`,
+    async () => {
+      const { loader, found, missing } = make();
+      expect.ok(loader instanceof Loader);
+      const loaded = await loader.load(found);
+      expect.ok(loaded !== null, `nothing found at ${found}`);
+      expect.equal(typeof loaded!.module, 'string');
+      expect.equal(typeof loaded!.version, 'string');
+      expect.ok(Array.isArray(loaded!.classes) && loaded!.classes.every((C) => typeof C === 'function'), 'the classes are classes');
+      const again = await loader.load(loaded!.from);
+      expect.same(again && { module: again.module, version: again.version, from: again.from }, { module: loaded!.module, version: loaded!.version, from: loaded!.from });
+      expect.equal(await loader.load(missing), null);
+    },
+  ],
+];