nervur 0.20.4 → 0.21.1

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: 'bad is hosted already' }, '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.4",
+  "version": "0.21.1",
   "description": "Nervur's kit of Quo: an object asks another object and gets an answer, without knowing where it is.",
   "keywords": [
     "quo",
@@ -46,6 +46,10 @@
     "./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": {
@@ -71,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/contract/index.ts

@@ -62,7 +62,8 @@ export type Module = { readonly module: string; readonly version: string; readon
 export type Loaded = Module & { readonly from: string };
 
 // Code, by the name a harbor keeps for it, or null where this loader has
-// none. Code never crosses a door and never lives in a cell, so it is the
+// none. Code it has that does not load throws, saying why. Code never
+// crosses a door and never lives in a cell, so it is the
 // one thing beside the seed a terrain hands in: a map, an import, a bundle.
 export abstract class Loader {
   abstract load(from: string): Promise<Loaded | null>;

package/src/harbor/catalogue.ts

@@ -67,10 +67,16 @@ export class Catalogue extends Faculty {
   // it. The rest stay out, each with its reason.
   async wake(): Promise<void> {
     for (const [module, row] of Object.entries(this.#rows)) {
-      const loaded = await this.#harbor.load(row.from).catch(() => null);
+      const loaded = await this.#harbor.load(row.from).catch((e: Error) => e);
       const refused =
-        loaded === null ? `not found at ${row.from}` : loaded.module !== module ? `${row.from} is module ${loaded.module}` : this.#harbor.check([...this.#running.values(), loaded]);
-      if (refused === null) this.#running.set(module, loaded!);
+        loaded instanceof Error
+          ? loaded.message
+          : loaded === null
+            ? `not found at ${row.from}`
+            : loaded.module !== module
+              ? `${row.from} is module ${loaded.module}`
+              : this.#harbor.check([...this.#running.values(), loaded]);
+      if (refused === null) this.#running.set(module, loaded as Loaded);
       else this.#failed.set(module, refused);
     }
     this.#harbor.run([...this.#running.values()]);
@@ -78,7 +84,8 @@ export class Catalogue extends Faculty {
 
   async add(args: JsonObject): Promise<JsonObject> {
     if (!text(args.from)) return { error: 'from is text' };
-    const loaded = await this.#harbor.load(args.from);
+    const loaded = await this.#harbor.load(args.from).catch((e: Error) => e);
+    if (loaded instanceof Error) return { error: loaded.message };
     if (loaded === null) return { error: 'no such module' };
     const running = new Map(this.#running);
     running.set(loaded.module, loaded);

package/src/harbor/dock.ts

@@ -158,7 +158,9 @@ export class Dock extends WardBeing implements Lender {
 
   async host(args: JsonObject): Promise<JsonObject> {
     const name = args.ward;
-    if (!text(name) || name === BOX || this.hosted.some((h) => h.ward === name)) return { error: 'no such ward to host' };
+    if (!text(name)) return { error: 'ward is text' };
+    if (name === BOX) return { error: 'box is the box ward' };
+    if (this.hosted.some((h) => h.ward === name)) return { error: `${name} is hosted already` };
     if (args.seed !== undefined && !text(args.seed)) return { error: 'seed is text' };
     const invitation = await this.stance.occupants.invite(name, { hosted: true });
     if (invitation === null) return { error: 'not hosted' };

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/node/index.ts

@@ -50,8 +50,10 @@ export const isFile = (from: string): boolean => /^(\.{1,2}[\\/]|[\\/]|[A-Za-z]:
 // Code from a file or an installed package: a module that exports
 // `module`, `version` and `classes`, found again by where it was found, a
 // file by its absolute path and a package by its name, resolved from each
-// folder of `bases` in order. What cannot be imported, or exports no
-// module, is none.
+// folder of `bases` in order. What is not there, or exports no module, is
+// none. Code that is there and does not import throws Node's reason, so
+// whoever added it learns why; an ES module read as CommonJS says which
+// field its package.json lacks.
 export class ImportLoader extends Loader {
   readonly #bases: readonly string[];
   constructor(bases: readonly string[] = [process.cwd()]) {
@@ -65,8 +67,13 @@ export class ImportLoader extends Loader {
     let exported: { module?: unknown; version?: unknown; classes?: unknown };
     try {
       exported = (await import(pathToFileURL(found).href)) as typeof exported;
-    } catch {
-      return null;
+    } catch (e) {
+      const said = (e as Error).message;
+      // The name itself is nowhere, as against code there that needs
+      // something that is not.
+      if ((e as { code?: string }).code === 'ERR_MODULE_NOT_FOUND' && said.includes(`'${found}'`)) return null;
+      const commonjs = e instanceof SyntaxError && /\b(export|import)\b/.test(said);
+      throw new Error(`${found} did not load: ${said}${commonjs ? '; it is an ES module read as CommonJS, so set "type": "module" in its package.json' : ''}`, { cause: e });
     }
     const { module, version, classes } = exported;
     if (typeof module !== 'string' || typeof version !== 'string' || !Array.isArray(classes)) return null;