nervur 0.20.3 → 0.21.0

package/README.md

@@ -43,38 +43,74 @@ terrain, as below, and that one is used.
 ## A harbor on the edge
 
 An edge harbor is born on your machine and carried there, so you pilot it
-from your own harbor, as you pilot one on a server. Make it and set it
-up with the command below, naming where the edge will reach it:
-
-```sh
-nervur init --dir ./edge
-nervur reach https://harbor.example.workers.dev/quo --dir ./edge
-nervur own pilot --dir ./edge
-nervur edge pack ./package.json --dir ./edge
-```
-
-`own` prints the owner invitation, which never leaves your machine.
-`edge pack` prints the harbor's seed and writes its sealed package. Keep
-the seed as the worker's secret, `wrangler secret put NERVUR_SEED`, and
-bundle the package with the worker:
+from your own harbor, as you pilot one on a server. The worker is a
+folder of its own, an ES module project (`"type": "module"` in its
+`package.json`), holding the worker and its `wrangler.toml`:
 
 ```js
+// worker.js
 import { harborObject } from 'nervur/edge';
-import carried from './package.json';
+import carried from './package.edge.json';
 import * as greetings from './greetings.js';
 
 export const Harbor = harborObject({ modules: [greetings], package: carried });
+
+export default {
+  fetch(request, env) {
+    return env.HARBOR.get(env.HARBOR.idFromName('main')).fetch(request);
+  },
+};
+```
+
+```toml
+# wrangler.toml
+name = "harbor"
+main = "worker.js"
+compatibility_date = "2026-09-01"
+
+[[durable_objects.bindings]]
+name = "HARBOR"
+class_name = "Harbor"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["Harbor"]
 ```
 
-The first time the object starts, the package lands in its storage and
-the harbor opens under that seed; after that the storage is the harbor,
-and a new deploy leaves it be. Then, from your own harbor:
+Make the harbor and set it up with the command, from that folder, naming
+where the edge will reach it:
+
+```sh
+nervur init --dir ./harbor
+nervur module add ./greetings.js --dir ./harbor
+nervur reach http://127.0.0.1:8787/quo --dir ./harbor
+nervur own me --dir ./harbor
+```
+
+`own` prints the owner invitation, which never leaves your machine. Run
+it on this machine first:
+
+```sh
+nervur edge dev ./package.edge.json --dir ./harbor
+```
+
+`edge dev` packs the harbor into `package.edge.json` and runs your
+`wrangler dev` with its seed, keeping the object's storage in
+`.nervur-edge`, so the harbor stands again each time you run it. The
+first time the object starts, the package lands in its storage and the
+harbor opens under that seed; after that the storage is the harbor, and
+a new deploy leaves it be. Then, from your own harbor:
 
 ```sh
 nervur pilot edge '<the owner invitation>' --dir ./mine
 nervur host shop --via edge --dir ./mine
 ```
 
+For Cloudflare, name the address it will answer at with `reach`, then
+`nervur edge pack ./package.edge.json --dir ./harbor` prints the seed and
+writes the package. Keep the seed as the worker's secret,
+`wrangler secret put NERVUR_SEED`, and `wrangler deploy`.
+
 `pilot` opens the web carrier where the invitation names a web address.
 An object with no package draws its own seed, sealed under the worker's
 `NERVUR_SECRET`, and `stood` runs the worker's own code on it as root:
@@ -211,8 +247,13 @@ stands a ward under a seed you name, or a drawn one.
 - **Push, webPush**: a ring with no content, as Web Push sends it,
   signed with VAPID, on fetch and Web Crypto.
 
-Carriers such as MCP, and every screen, are `@nervur-org/*`'s, as
-classes fulfilling these contracts.
+Quo crosses two carriers, TCP and the web, and no third. MCP, an HTTP API
+and every other outside protocol are gateway faculties: classes that
+serve their clients, a UI in a browser, an MCP client, a caller holding
+a bearer token, on one side, and stand as an ordinary being on the
+other, offering standings, holding occupants and speaking Quo inbound
+and outbound. They and every screen
+are `@nervur-org/*`'s.
 
 ## The command
 

package/dist/cli/command.js

@@ -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
@@ -51,7 +55,10 @@ import { join, resolve } from 'node:path';
 import { WEB_OPENING } from '../line/index.js';
 import { harborDir, isFile } from '../node/index.js';
 import { readAt, webAddress } from '../quo/index.js';
+import { edgeDev } from './edge.js';
 import { carry, isServed, land, open, pack, request, serve } from './harbor.js';
+// 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.
@@ -193,13 +200,20 @@ export const main = async (argv, env, print) => {
         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 ((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 pack reads this folder, so it takes no --via');
+            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 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)

package/dist/cli/edge.d.ts

@@ -0,0 +1,7 @@
+export declare const EDGE_STATE = ".nervur-edge";
+export type EdgeDev = {
+    readonly at: string;
+    readonly places: number;
+    close(): Promise<void>;
+};
+export declare const edgeDev: (dir: string, file: string, cwd: string, port: number) => Promise<EdgeDev>;

package/dist/cli/edge.js

@@ -0,0 +1,58 @@
+// 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 } from 'node:child_process';
+import { join } from 'node:path';
+import { pack } from './harbor.js';
+export const EDGE_STATE = '.nervur-edge';
+const READY_TRIES = 240;
+const READY_EVERY = 250;
+const answers = (url) => fetch(url).then(() => true, () => false);
+// Resolved once wrangler answers at `url`, rejected once it exits or never
+// answers.
+const ready = async (child, url, said) => {
+    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, file, cwd, port) => {
+    const { seed, places } = (await pack(dir, file));
+    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) => (err = `${err}${chunk.toString('utf8')}`.slice(-4000)));
+    const at = `http://127.0.0.1:${String(port)}/quo`;
+    const close = () => 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/dist/index.d.ts

@@ -5,4 +5,4 @@ export { Carrier, Clock, Custody, Entropy, Loader, Memory, type Loaded, type Mod
 export { CEILING, DEFAULT, DEPTH, ownerAsk, Pilot, pilots, WardBeing, type Steward, type WardBeingStance } from './ward/index.ts';
 export { BOX, CarrierFaculty, Catalogue, copyPackage, Dock, Harbor, addGround, grounds, readRootRequest, Registry, Push, PUSH, RELAY, RELAY_CLIENT, rootLine, Terrain, UNDIALED, type Dialed, type Failures, type Ground, type GroundFaculty, type GroundProbe, type Opening, type Probing, type RootRequest, } from './harbor/index.ts';
 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';

package/dist/index.js

@@ -15,6 +15,6 @@ export { CEILING, DEFAULT, DEPTH, ownerAsk, Pilot, pilots, WardBeing } from './w
 export { BOX, CarrierFaculty, Catalogue, copyPackage, Dock, Harbor, addGround, grounds, readRootRequest, Registry, Push, PUSH, RELAY, RELAY_CLIENT, rootLine, Terrain, UNDIALED, } from './harbor/index.js';
 // The pointer dock: a whole world in one process.
 export { CryptoEntropy, HeldCustody, HeldLoader, NoCarrier, PointerCarrier, PointerTerrain, SystemClock, VolatileMemory, World } from './pointer/index.js';
-export { NEUTRAL, WEB, WEB_OPENING, WEB_PUSH, WebDialer, webFaculty, webPush } from './line/index.js';
+export { answerPost, NEUTRAL, WEB, WEB_OPENING, WEB_PUSH, WebDialer, webFaculty, webPush } from './line/index.js';
 // The ground that fits everywhere, tried after any a platform entry adds.
 addGround(neutralGround);

package/dist/proof/contracts.d.ts

@@ -0,0 +1,15 @@
+import { Custody, Entropy, Loader, Memory } from '../contract/index.ts';
+import type { Expect } from './expect.ts';
+export type Scene = [string, () => Promise<void>];
+export declare const custodyScenes: (name: string, make: () => [Custody, Custody], expect: Expect) => Scene[];
+export type Cut = {
+    cut: Memory;
+    fresh: Memory;
+};
+export declare const memoryScenes: (name: string, make: () => [Memory, Memory], expect: Expect, half?: () => Cut) => Scene[];
+export declare const entropyScenes: (name: string, make: () => Entropy, expect: Expect) => Scene[];
+export declare const loaderScenes: (name: string, make: () => {
+    loader: Loader;
+    found: string;
+    missing: string;
+}, expect: Expect) => Scene[];

package/dist/proof/contracts.js

@@ -0,0 +1,115 @@
+// 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.js';
+const bytes = (...values) => Uint8Array.from(values);
+// A place as plain values, in name order, so two can be compared as JSON.
+const plain = (place) => [...place].map(([n, b]) => [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, make, expect) => [
+    [
+        `[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');
+        },
+    ],
+];
+export const memoryScenes = (name, make, expect, half) => [
+    [
+        `[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}`);
+                },
+            ],
+        ]
+        : []),
+    [
+        `[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, make, expect) => [
+    [
+        `[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, make, expect) => [
+    [
+        `[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);
+        },
+    ],
+];

package/dist/proof/expect.d.ts

@@ -0,0 +1,6 @@
+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;
+};
+export declare const expect: Expect;

package/dist/proof/expect.js

@@ -0,0 +1,18 @@
+const fail = (message, detail) => {
+    throw new Error(`${message ? `${message}: ` : ''}${detail}`);
+};
+export const 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/dist/proof/index.d.ts

@@ -0,0 +1,3 @@
+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/dist/proof/index.js

@@ -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 } from './contracts.js';
+export { expect } from './expect.js';
+export { law, lawScenes } from './law.js';

package/dist/proof/law.d.ts

@@ -0,0 +1,52 @@
+import { Being, Faculty, type Asker, type JsonObject } from '../being/index.ts';
+import { Memory, type Custody, type Module } from '../contract/index.ts';
+import { type Harbor } from '../harbor/index.ts';
+import { World } from '../pointer/index.ts';
+import type { Expect } from './expect.ts';
+export type Bodies = {
+    custody: Custody;
+    memory: Memory;
+};
+export type Terrain = {
+    name: string;
+    make(): Bodies;
+    again(bodies: Bodies): Bodies;
+};
+declare abstract class Echoes extends Faculty {
+    static kind: string;
+}
+declare class Echo extends Echoes {
+    static kind: string;
+    static asks: {
+        echo: {};
+    };
+    echo(args: JsonObject, asker: Asker): JsonObject;
+}
+declare class Shop extends Being {
+    static kind: string;
+    static cells: {
+        sold: string[];
+    };
+    static asks: {
+        buy: {};
+    };
+    buy(args: JsonObject, asker: Asker): JsonObject;
+}
+declare class Customer extends Being {
+    static kind: string;
+    static asks: {
+        join: {};
+        buy: {};
+        echo: {};
+        spoil: {};
+    };
+    spoil(): JsonObject;
+    join(args: JsonObject): Promise<JsonObject>;
+    buy(args: JsonObject): Promise<JsonObject>;
+    echo(args: JsonObject): Promise<JsonObject>;
+}
+export declare const classes: (typeof Echo | typeof Shop | typeof Customer)[];
+export declare const law: Module;
+export declare const standOne: (world: World, name: string, parts?: Partial<Bodies>) => Promise<Harbor>;
+export declare const lawScenes: (t: Terrain, expect: Expect) => [string, () => Promise<void>][];
+export {};