nervur 0.20.2 → 0.20.4

package/README.md

@@ -35,22 +35,58 @@ while it stands. A folder opens in one run at a time. Bundled for a
 browser, in a page or a worker, it keeps itself in the IndexedDB
 database `where` names, else `nervur`, its seed sealed under a key the
 browser never hands out, speaks the web, and opens in one run at a time.
-On Cloudflare Workers it is one Durable Object:
+On Cloudflare Workers it is one Durable Object, answering Quo at `/quo`
+on whatever host reaches it, and asking over TCP and the web. Anywhere
+else it lives as long as its process and speaks the web. Hand in a
+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:
 
 ```js
 import { harborObject } from 'nervur/edge';
+import carried from './package.json';
 import * as greetings from './greetings.js';
 
-export const Harbor = harborObject([greetings], async (harbor) => {
-  // the worker's own code is the root: runs once the harbor stands
-});
+export const Harbor = harborObject({ modules: [greetings], package: carried });
 ```
 
-Each object keeps its harbor in its storage, its seed sealed under the
-worker's `NERVUR_SECRET`, answers Quo over the web from its requests,
-and asks over TCP and the web. Anywhere else it lives as long as its
-process and speaks the web. Hand in a terrain, as below, and that one
-is used.
+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
+```
+
+`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:
+
+```js
+export const Shop = harborObject({
+  modules: [greetings],
+  stood: async (harbor) => {
+    // runs once the harbor stands
+  },
+});
+```
 
 ## A world in one process
 
@@ -175,8 +211,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
 
@@ -186,7 +227,7 @@ folder, Quo over TCP as its carrier. A module is a file that exports
 
 ```sh
 nervur init  --dir ./harbor
-nervur module add ./greetings.js --dir ./harbor
+nervur module add ./greetings.js --dir ./harbor   # or @acme/greetings, or its id
 nervur serve --dir ./harbor --port 7000
 nervur reach tcp://harbor.example:7000 --dir ./harbor
 nervur open web org.nervur.web --dir ./harbor
@@ -209,9 +250,13 @@ named this way is trusted first.
 listens for Quo on TCP and for the root's asks on a local socket, open to
 you alone. Every other command is one root ask, sent to the served
 harbor, or answered from the folder when none is served. Each prints one
-JSON line. `--dir` defaults to `$NERVUR_DIR`, then `~/.nervur`. The
-catalogue keeps a module by its file's absolute path, and routes live in
-the harbor like everything else, so a restart finds both. `nervur
+JSON line. `--dir` defaults to `$NERVUR_DIR`, then `~/.nervur`.
+`module add` takes a file, an installed package, or a module's id, and
+the catalogue keeps the id the module declares, so the same harbor finds
+its code on any ground: on this machine through `modules.json` beside
+the harbor, which remembers where each id was found, and on an edge or
+in a browser in the bundle. Routes live in the harbor like everything
+else, so a restart finds both. `nervur
 modules` shows what runs, and `nervur module remove <module>` stops one.
 
 A harbor elsewhere is piloted with the owner invitation its `init`

package/dist/cli/command.d.ts

@@ -7,7 +7,7 @@ export declare const parse: (argv: string[]) => {
 };
 export declare const requestOf: (command: string, words: string[], flags: Record<string, string>) => RootRequest;
 export declare const main: (argv: string[], env: Record<string, string | undefined>, print: (line: string) => void) => Promise<number>;
-export declare const pilotRequests: (name: string, invitation: JsonObject, at?: string) => RootRequest[];
+export declare const pilotRequests: (name: string, invitation: JsonObject, at?: string, web?: boolean) => RootRequest[];
 export declare const via: (pilot: string, far: RootRequest) => RootRequest;
 export declare const farAnswer: (local: JsonObject) => JsonObject;
 export declare const SERVING = -1;

package/dist/cli/command.js

@@ -7,7 +7,8 @@
 //                                                   invitation for whoever made it
 //   nervur serve  [--dir D] [--host H] [--port P]   the harbor served: Quo over TCP,
 //                                                   and the root line on its socket
-//   nervur module add <file>                        a module the catalogue runs
+//   nervur module add <file | package | id>         a module the catalogue runs, kept
+//                                                   by the id it declares
 //   nervur module remove <module>                   a module it runs no more
 //   nervur modules                                  what the catalogue runs
 //   nervur census [--ward W]                        the empty ask
@@ -18,6 +19,10 @@
 //                                                   --with-seed the seed goes too
 //   nervur import <file>                            a carried harbor into an empty
 //                                                   folder, `-` being this input
+//   nervur edge pack <file>                         the harbor for an edge: its seed
+//                                                   printed, for the worker's
+//                                                   NERVUR_SEED, and its sealed
+//                                                   package written to the file
 //   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
@@ -43,9 +48,11 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import { harborDir } from '../node/index.js';
-import { carry, isServed, land, open, request, serve } from './harbor.js';
-const USAGE = 'usage: nervur <init|serve|module|modules|census|sweep|open|host|route|reach|boot|unboot|public|invite|ask|own|disown|pilot|export|import> [args] [--dir D] [--ward W] [--via V] [--seed S] [--with-seed] [--host H] [--port P]';
+import { WEB_OPENING } from '../line/index.js';
+import { harborDir, isFile } from '../node/index.js';
+import { readAt, webAddress } from '../quo/index.js';
+import { carry, isServed, land, open, pack, request, serve } from './harbor.js';
+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.
 const ALONE = 'with-seed';
@@ -89,7 +96,7 @@ export const requestOf = (command, words, flags) => {
         case 'module': {
             const [verb, what] = need(2);
             if (verb === 'add')
-                return catalogue('add', { from: resolve(what) });
+                return catalogue('add', { from: isFile(what) ? resolve(what) : what });
             if (verb === 'remove')
                 return catalogue('remove', { module: what });
             throw new Error('module is add or remove');
@@ -185,6 +192,15 @@ export const main = async (argv, env, print) => {
         const text = words[0] === '-' ? await standingIn() : await readFile(words[0], 'utf8');
         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 (await isServed(dir))
+            throw new Error(`a harbor is served from ${dir}: stop it first`);
+        return out(await pack(dir, words[1]));
+    }
     if (command === 'serve') {
         if (words.length > 0)
             throw new Error('serve takes no argument');
@@ -200,7 +216,9 @@ export const main = async (argv, env, print) => {
             throw new Error('pilot takes a name, an invitation, and an address where the invitation carries none');
         const [name, invitation, at] = words;
         const held = JSON.parse(invitation);
-        for (const req of pilotRequests(name, held, at)) {
+        const census = (await request(dir, {}));
+        const web = census.answer?.beings !== undefined && Object.hasOwn(census.answer.beings, WEB_OPENING.key);
+        for (const req of pilotRequests(name, held, at, web)) {
             const answer = await request(dir, req);
             if (!failed(answer))
                 continue;
@@ -216,9 +234,12 @@ export const main = async (argv, env, print) => {
         throw new Error('--via takes no --ward');
     return out(farAnswer(await request(dir, via(flags.via, requestOf(command, words, flags)))));
 };
-// The root requests that hold a far ward: its route where one is named,
-// else the take learns it from the invitation's `at`; the pilot; the take.
-export const pilotRequests = (name, invitation, at) => [
+// The root requests that hold a far ward: the web carrier opened, where the
+// far ward is reached on the web and this harbor has none; its route where
+// one is named, else the take learns it from the invitation's `at`; the
+// pilot; the take.
+export const pilotRequests = (name, invitation, at, web = false) => [
+    ...(!web && readAt([...(at === undefined ? [] : [at]), ...readAt(invitation.at)]).some((a) => webAddress(a) !== null) ? [{ method: 'open', args: { key: WEB_OPENING.key, class: WEB_OPENING.kind } }] : []),
     ...(at === undefined ? [] : [{ method: 'route', args: { ward: invitation.ward ?? null, at: [at] } }]),
     { method: 'boot', args: { key: name, class: 'org.nervur.pilot' } },
     { method: 'ask', args: { being: name, method: 'hold', args: { invitation } } },

package/dist/cli/harbor.d.ts

@@ -1,13 +1,10 @@
 import type { JsonObject } from '../being/index.ts';
-import { Harbor, type RootRequest } from '../harbor/index.ts';
+import { Harbor, type Carried, type RootRequest } from '../harbor/index.ts';
 export declare const open: (dir: string) => Promise<Harbor>;
 export declare const isServed: (dir: string) => Promise<boolean>;
 export declare const request: (dir: string, req: RootRequest) => Promise<JsonObject>;
-export type Carried = {
-    seed?: string;
-    places: Record<string, Record<string, string>>;
-};
 export declare const carry: (dir: string, seed: boolean) => Promise<Carried>;
+export declare const pack: (dir: string, file: string) => Promise<JsonObject>;
 export declare const land: (dir: string, value: unknown) => Promise<string[]>;
 export type Served = {
     pk: string;

package/dist/cli/harbor.js

@@ -7,12 +7,12 @@
 // the command unpacks the harbor from its folder, asks, and closes it, so
 // one process at a time writes the folder.
 import { existsSync } from 'node:fs';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { hex, isHex, unhex } from '../crypto/index.js';
+import { hex } from '../crypto/index.js';
 import { FolderCustody, FolderMemory } from '../folder/index.js';
-import { Harbor, rootLine } from '../harbor/index.js';
-import { askServed, NodeTerrain, socketOf } from '../node/index.js';
+import { carryPlaces, Harbor, landPlaces, readCarried, rootLine } from '../harbor/index.js';
+import { askServed, MODULES, NodeTerrain, socketOf } from '../node/index.js';
 import { CryptoEntropy } from '../pointer/index.js';
 import { TCP_OPENING } from '../tcp/index.js';
 // A harbor of a folder, opened for one ask: it listens nowhere and serves
@@ -32,40 +32,33 @@ export const request = async (dir, req) => {
         await harbor.close();
     }
 };
-const carried = (value) => {
-    if (typeof value !== 'object' || value === null)
-        return null;
-    const { seed, places } = value;
-    if (seed !== undefined && !isHex(seed, 32))
-        return null;
-    if (typeof places !== 'object' || places === null || Array.isArray(places))
-        return null;
-    for (const entries of Object.values(places)) {
-        if (typeof entries !== 'object' || entries === null || Array.isArray(entries))
-            return null;
-        for (const bytes of Object.values(entries))
-            if (!isHex(bytes))
-                return null;
-    }
-    return { ...(seed === undefined ? {} : { seed }), places: places };
-};
-// The harbor of a folder, read as bytes alone. No harbor opens, so
-// nothing is asked and nothing is written.
+// The harbor of a folder, read as bytes alone, its seed only where the
+// one who asks says so, since custody holds it and a package without it
+// opens nowhere. No harbor opens, so nothing is asked and nothing is
+// written.
 export const carry = async (dir, seed) => {
-    const memory = new FolderMemory(dir);
-    const places = {};
-    for (const place of await memory.places()) {
-        places[place] = Object.fromEntries([...(await memory.read(place))].map(([name, bytes]) => [name, hex(bytes)]));
-    }
-    if (!seed)
-        return { places };
-    return { seed: hex(await new FolderCustody(dir, new CryptoEntropy()).seed()), places };
+    const places = await carryPlaces(new FolderMemory(dir));
+    const modules = await readFile(join(dir, MODULES), 'utf8').then((text) => JSON.parse(text), () => undefined);
+    return {
+        ...(seed ? { seed: hex(await new FolderCustody(dir, new CryptoEntropy()).seed()) } : {}),
+        places,
+        ...(modules ? { modules } : {}),
+    };
+};
+// What `nervur edge pack` hands a deploy: the seed, for the worker's
+// `NERVUR_SEED`, and the sealed package without it, for the bundle.
+export const pack = async (dir, file) => {
+    if (!existsSync(join(dir, 'seed')))
+        throw new Error(`no harbor stands at ${dir}`);
+    const { seed, places } = await carry(dir, true);
+    await writeFile(file, `${JSON.stringify({ places })}\n`, { mode: 0o600 });
+    return { seed: seed, package: file, places: Object.keys(places).length };
 };
 // A carried harbor into an empty folder. A folder holding a seed or a
 // place is left as it stands, and a package with no seed needs one there
 // already, which a terrain that seals its custody writes its own way.
 export const land = async (dir, value) => {
-    const held = carried(value);
+    const held = readCarried(value);
     if (held === null)
         throw new Error('that is no carried harbor');
     const memory = new FolderMemory(dir);
@@ -76,10 +69,9 @@ export const land = async (dir, value) => {
         await writeFile(join(dir, 'seed'), `${held.seed}\n`, { mode: 0o600, flag: 'wx' });
     else if (!existsSync(join(dir, 'seed')))
         throw new Error('the package carries no seed, and none is held here');
-    for (const [place, entries] of Object.entries(held.places)) {
-        await memory.write(place, new Map(Object.entries(entries).map(([name, bytes]) => [name, unhex(bytes)])));
-    }
-    return Object.keys(held.places);
+    if (held.modules && !existsSync(join(dir, MODULES)))
+        await writeFile(join(dir, MODULES), `${JSON.stringify(held.modules, null, 2)}\n`, { mode: 0o600 });
+    return landPlaces(memory, held);
 };
 // The harbor served: a harbor of the Node ground, with Quo over TCP on
 // host and port.

package/dist/edge/index.d.ts

@@ -1,7 +1,8 @@
 import { Custody, Memory, type Entropy, type Module } from '../contract/index.ts';
-import { Harbor, type GroundFaculty, type GroundProbe } from '../harbor/index.ts';
+import { Harbor, type Carried, type GroundFaculty, type GroundProbe } from '../harbor/index.ts';
 import { type WebListen } from '../line/index.ts';
 import { PointerTerrain } from '../pointer/index.ts';
+export type { Carried } from '../harbor/index.ts';
 export declare const EDGE = "edge";
 export interface EdgeStorage {
     get(key: string): Promise<unknown>;
@@ -17,11 +18,13 @@ export interface EdgeState {
     blockConcurrencyWhile<T>(work: () => Promise<T>): Promise<T>;
 }
 export type EdgeEnv = {
+    readonly NERVUR_SEED?: string;
     readonly NERVUR_SECRET?: string;
 };
 export type EdgeGiven = {
     readonly state: EdgeState;
     readonly env: EdgeEnv;
+    readonly package?: Carried;
 };
 export declare class EdgeMemory extends Memory {
     #private;
@@ -31,9 +34,13 @@ export declare class EdgeMemory extends Memory {
     places(): Promise<string[]>;
     forget(place: string): Promise<void>;
 }
+export type EdgeKeys = {
+    readonly seed?: string | undefined;
+    readonly secret?: string | undefined;
+};
 export declare class EdgeCustody extends Custody {
     #private;
-    constructor(storage: EdgeStorage, secret: string | undefined, entropy?: Entropy, root?: string);
+    constructor(storage: EdgeStorage, keys: EdgeKeys, entropy?: Entropy, root?: string);
     seed(): Promise<Uint8Array>;
 }
 export declare const edgeTcp: GroundFaculty;
@@ -46,12 +53,19 @@ export declare class EdgeTerrain extends PointerTerrain {
     readonly given: EdgeGiven;
     listening: WebListen | undefined;
     constructor(parts: EdgeParts);
+    claim(): Promise<void>;
     stand(harbor: Harbor): Promise<void>;
     answer(request: Request): Promise<Response>;
 }
 export declare const edgeGround: GroundProbe;
+export type HarborObjectParts = {
+    readonly modules: readonly Module[];
+    readonly package?: Carried | ((env: EdgeEnv) => Carried | undefined);
+    readonly path?: string;
+    readonly stood?: (harbor: Harbor) => Promise<void>;
+};
 export type HarborObjectClass = new (state: EdgeState, env: EdgeEnv) => {
     readonly harbor: Promise<Harbor>;
     fetch(request: Request): Promise<Response>;
 };
-export declare const harborObject: (modules: readonly Module[], stood?: (harbor: Harbor) => Promise<void>) => HarborObjectClass;
+export declare const harborObject: ({ modules, package: carried, path, stood }: HarborObjectParts) => HarborObjectClass;

package/dist/edge/index.js

@@ -8,7 +8,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { Custody, Memory } from '../contract/index.js';
 import { decrypt, encrypt, hkdf, isHex, unhex, utf8 } from '../crypto/index.js';
-import { addGround, CarrierFaculty, Harbor, UNDIALED } from '../harbor/index.js';
+import { addGround, CarrierFaculty, Harbor, landPlaces, UNDIALED } from '../harbor/index.js';
 import { answerHeld, answerPost, askFrame, FrameReader, TCP, TCP_OPENING, WEB_OPENING, webFaculty, webPush } from '../line/index.js';
 import { CryptoEntropy, HeldLoader, PointerTerrain } from '../pointer/index.js';
 import { tcpAddress, tcpAt } from '../quo/index.js';
@@ -66,24 +66,28 @@ export class EdgeMemory extends Memory {
         });
     }
 }
-// The seed, drawn once and kept sealed under a key the secret gives, so
-// the storage alone opens nothing. A harbor with no secret does not stand.
 export class EdgeCustody extends Custody {
     #storage;
-    #secret;
+    #keys;
     #entropy;
     #key;
-    constructor(storage, secret, entropy = new CryptoEntropy(), root = '') {
+    constructor(storage, keys, entropy = new CryptoEntropy(), root = '') {
         super();
         this.#storage = storage;
-        this.#secret = secret;
+        this.#keys = keys;
         this.#entropy = entropy;
         this.#key = `${root}${SEED}`;
     }
     async seed() {
-        if (!this.#secret)
+        const { seed: named, secret } = this.#keys;
+        if (named !== undefined) {
+            if (!isHex(named.trim(), 32))
+                throw new Error('NERVUR_SEED is not 64 hex');
+            return unhex(named.trim());
+        }
+        if (!secret)
             throw new Error('the worker holds no NERVUR_SECRET');
-        const key = await hkdf(utf8(this.#secret), SEAL_INFO, 32);
+        const key = await hkdf(utf8(secret), SEAL_INFO, 32);
         return this.#storage.transaction(async (txn) => {
             const kept = (await txn.get(this.#key));
             if (kept) {
@@ -241,13 +245,25 @@ export class EdgeTerrain extends PointerTerrain {
         super({
             entropy,
             loader: new HeldLoader(parts.modules ?? []),
-            custody: new EdgeCustody(storage, parts.given.env.NERVUR_SECRET, entropy),
+            // Only a harbor carried here takes the worker's NERVUR_SEED; every
+            // other object of the worker draws its own.
+            custody: new EdgeCustody(storage, { seed: parts.given.package ? parts.given.env.NERVUR_SEED : undefined, secret: parts.given.env.NERVUR_SECRET }, entropy),
             memory: new EdgeMemory(storage),
             faculties: [edgeTcp, webFaculty(edgeServe), webPush],
             opens: [TCP_OPENING, WEB_OPENING],
         });
         this.given = parts.given;
     }
+    // A carried package lands where the object keeps nothing yet, and only
+    // under the seed it was sealed with, the worker's `NERVUR_SEED`.
+    async claim() {
+        const { package: carried, env } = this.given;
+        if (!carried || (await this.memory.places()).length > 0)
+            return;
+        if (env.NERVUR_SEED === undefined)
+            throw new Error('a carried package opens only under NERVUR_SEED');
+        await landPlaces(this.memory, carried);
+    }
     stand(harbor) {
         this.#harbor = harbor;
         return Promise.resolve();
@@ -283,7 +299,10 @@ export const edgeGround = {
     fits: ({ given }) => isGiven(given),
     terrain: ({ given, modules }) => new EdgeTerrain({ given: given, ...(modules ? { modules } : {}) }),
 };
-export const harborObject = (modules, stood) => class HarborObject {
+// A Durable Object class whose every instance is one harbor: opened once
+// per object, its web carrier opened, and every request it receives
+// answered by that carrier at `path`.
+export const harborObject = ({ modules, package: carried, path = '/quo', stood }) => class HarborObject {
     #opening;
     // The object's harbor, once it stands.
     get harbor() {
@@ -291,16 +310,25 @@ export const harborObject = (modules, stood) => class HarborObject {
     }
     constructor(state, env) {
         addGround(edgeGround);
+        const held = typeof carried === 'function' ? carried(env) : carried;
+        const given = { state, env, ...(held ? { package: held } : {}) };
         // Opened inside the object's block, so no request reaches it half
         // open and its storage answers the opening.
         this.#opening = state.blockConcurrencyWhile(async () => {
-            const harbor = await Harbor.open({ modules, given: { state, env } });
+            const harbor = await Harbor.open({ modules, given });
+            if (!harbor.box.being(WEB_OPENING.key))
+                await harbor.root('open', { key: WEB_OPENING.key, class: WEB_OPENING.kind });
             await stood?.(harbor);
             return harbor;
         });
     }
     async fetch(request) {
         const harbor = await this.#opening;
-        return harbor.terrain.answer(request);
+        const terrain = harbor.terrain;
+        if (terrain.listening?.path !== path) {
+            const url = new URL(request.url);
+            await harbor.root('ask', { being: WEB_OPENING.key, method: 'listen', args: { host: url.hostname, port: url.port === '' ? 0 : Number(url.port), path } });
+        }
+        return terrain.answer(request);
     }
 };

package/dist/harbor/index.d.ts

@@ -2,7 +2,7 @@ export { Catalogue, CATALOGUE, type Cataloguing, type ModuleRow } from './catalo
 export { BOX, Dock, type Failures, type Hosted, type Hosting } from './dock.ts';
 export { CarrierFaculty, UNDIALED, type Dialed, type Ground, type GroundFaculty } from './carrying.ts';
 export { Harbor } from './harbor.ts';
-export { copyPackage, Package } from './package.ts';
+export { carryPlaces, copyPackage, landPlaces, Package, readCarried, type Carried } from './package.ts';
 export { readRootRequest, rootLine, type RootRequest } from './root-line.ts';
 export { addGround, grounds, probeGround, type GroundProbe, type Probing } from './probe.ts';
 export { Registry } from './registry.ts';

package/dist/harbor/index.js

@@ -5,7 +5,7 @@ export { Catalogue, CATALOGUE } from './catalogue.js';
 export { BOX, Dock } from './dock.js';
 export { CarrierFaculty, UNDIALED } from './carrying.js';
 export { Harbor } from './harbor.js';
-export { copyPackage, Package } from './package.js';
+export { carryPlaces, copyPackage, landPlaces, Package, readCarried } from './package.js';
 export { readRootRequest, rootLine } from './root-line.js';
 export { addGround, grounds, probeGround } from './probe.js';
 export { Registry } from './registry.js';

package/dist/harbor/package.d.ts

@@ -1,5 +1,13 @@
 import type { Entropy, Memory, Rows } from '../contract/index.ts';
 export declare const copyPackage: (from: Memory, to: Memory) => Promise<string[]>;
+export type Carried = {
+    seed?: string;
+    places: Record<string, Record<string, string>>;
+    modules?: Record<string, string>;
+};
+export declare const readCarried: (value: unknown) => Carried | null;
+export declare const carryPlaces: (memory: Memory) => Promise<Carried['places']>;
+export declare const landPlaces: (memory: Memory, carried: Carried) => Promise<string[]>;
 export declare class Package {
     #private;
     readonly memory: Memory;

package/dist/harbor/package.js

@@ -13,7 +13,7 @@
 // A row is the head, under the empty name, or one being, under her key. An
 // entry that does not open refuses the whole ward, so nothing unpacks from
 // bytes the package did not seal.
-import { concat, decrypt, encrypt, hex, hkdf, utf8 } from '../crypto/index.js';
+import { concat, decrypt, encrypt, hex, hkdf, isHex, unhex, utf8 } from '../crypto/index.js';
 import { HEAD_ROW } from '../ward/index.js';
 // Every place of one memory, written into another, and the places
 // carried. The bytes are the package's own, sealed under a seed neither
@@ -26,6 +26,42 @@ export const copyPackage = async (from, to) => {
         await to.write(place, await from.read(place));
     return places;
 };
+// A carried harbor as JSON reads, or null for anything else.
+export const readCarried = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const { seed, places, modules } = value;
+    if (seed !== undefined && !isHex(seed, 32))
+        return null;
+    const hints = modules === undefined || (typeof modules === 'object' && modules !== null && !Array.isArray(modules) && Object.values(modules).every((m) => typeof m === 'string'));
+    if (!hints)
+        return null;
+    if (typeof places !== 'object' || places === null || Array.isArray(places))
+        return null;
+    for (const entries of Object.values(places)) {
+        if (typeof entries !== 'object' || entries === null || Array.isArray(entries))
+            return null;
+        for (const bytes of Object.values(entries))
+            if (!isHex(bytes))
+                return null;
+    }
+    return { ...(seed === undefined ? {} : { seed }), places: places, ...(modules === undefined ? {} : { modules: modules }) };
+};
+// Every place of a memory, as a carried harbor holds it.
+export const carryPlaces = async (memory) => {
+    const places = {};
+    for (const place of await memory.places()) {
+        places[place] = Object.fromEntries([...(await memory.read(place))].map(([name, bytes]) => [name, hex(bytes)]));
+    }
+    return places;
+};
+// A carried harbor's places, written into a memory, and their names.
+export const landPlaces = async (memory, carried) => {
+    for (const [place, entries] of Object.entries(carried.places)) {
+        await memory.write(place, new Map(Object.entries(entries).map(([name, bytes]) => [name, unhex(bytes)])));
+    }
+    return Object.keys(carried.places);
+};
 const NONCE = 12;
 const LABEL = utf8('nervur-package');
 class PackageRows {

package/dist/harbor/relay.js

@@ -174,11 +174,22 @@ export const relayFaculty = (clock) => class Relay extends CarrierFaculty {
             return { error: 'replies are a list of { n, box }' };
         const id = asker.id;
         this.#rung.delete(id);
+        const replied = new Set(replies.map((r) => r.n));
         for (const { n, box } of replies) {
             const taken = this.#taken.get(n);
             if (taken?.collector === id)
                 this.#settle(taken, box === null ? null : unhex(box));
         }
+        // A client answers every box it took in its next collect, so a box it
+        // left out never reached its doors, and waits again. A door that
+        // hears it twice answers the second as repeated.
+        for (const taken of [...this.#taken.values()]) {
+            if (taken.collector !== id || replied.has(taken.n))
+                continue;
+            this.#taken.delete(taken.n);
+            delete taken.collector;
+            this.#waiting.unshift(taken);
+        }
         const wards = wardsOf(this.notes(asker));
         if (args.wait === true && !this.#waiting.some((b) => wards.includes(b.ward)))
             await this.#hold(wards);
@@ -259,6 +270,7 @@ export const relayClient = (ground, clock) => class RelayClient extends CarrierF
     };
     #awake = false;
     #replies = [];
+    #turn = Promise.resolve();
     // Ends every rest and schedule when the client sleeps or lets go.
     #stop = () => { };
     accepts() {
@@ -367,7 +379,14 @@ export const relayClient = (ground, clock) => class RelayClient extends CarrierF
     // One collect: the replies owed go with it, and each box it brings is
     // handed to this harbor's doors. The number of boxes, or null where the
     // relay was not reached.
-    async #collect(wait) {
+    // Collects run one after another, so each carries the replies to every
+    // box the one before it brought, as the relay counts on.
+    #collect(wait) {
+        const run = this.#turn.then(() => this.#collectNow(wait));
+        this.#turn = run.catch(() => undefined);
+        return run;
+    }
+    async #collectNow(wait) {
         const standing = this.stance.standings.get(CLIENT);
         if (!standing)
             return null;

package/dist/node/index.d.ts

@@ -5,14 +5,18 @@ import { PointerTerrain } from '../pointer/index.ts';
 export declare const NODE = "node";
 export declare const harborDir: (env?: Record<string, string | undefined>) => string;
 export declare const socketOf: (dir: string) => string;
+export declare const isFile: (from: string) => boolean;
 export declare class ImportLoader extends Loader {
+    #private;
+    constructor(bases?: readonly string[]);
     load(from: string): Promise<Loaded | null>;
 }
 export declare class NodeLoader extends ImportLoader {
     #private;
-    constructor(modules?: readonly Module[]);
+    constructor(modules?: readonly Module[], dir?: string);
     load(from: string): Promise<Loaded | null>;
 }
+export declare const MODULES = "modules.json";
 export declare const askServed: (dir: string, request: RootRequest) => Promise<JsonObject | undefined>;
 export type NodeParts = {
     readonly dir: string;