nervur 0.20.2 → 0.20.3

package/dist/node/index.js

@@ -21,10 +21,11 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 //
 // One run holds a folder: a terrain refuses a folder another run serves.
 import { createHash } from 'node:crypto';
-import { chmod, rm } from 'node:fs/promises';
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import { connect, createServer } from 'node:net';
 import { homedir, tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Loader } from '../contract/index.js';
 import { FolderCustody, FolderMemory } from '../folder/index.js';
@@ -47,15 +48,26 @@ export const socketOf = (dir) => {
         return beside;
     return join(tmpdir(), `nervur-${createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 32)}.sock`);
 };
-// Code from a file: a module that exports `module`, `version` and
-// `classes`, found again by its absolute path. A file that cannot be
-// imported, or exports no module, is none.
+// A specifier that names a file rather than a package.
+export const isFile = (from) => /^(\.{1,2}[\\/]|[\\/]|[A-Za-z]:[\\/])/.test(from) || /\.(m?[jt]s|c[jt]s)$/.test(from);
+// 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.
 export class ImportLoader extends Loader {
+    #bases;
+    constructor(bases = [process.cwd()]) {
+        super();
+        this.#bases = bases;
+    }
     async load(from) {
-        const path = resolve(from);
+        const found = isFile(from) ? resolve(from) : this.#package(from);
+        if (found === null)
+            return null;
         let exported;
         try {
-            exported = (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
+            exported = (await import(__rewriteRelativeImportExtension(pathToFileURL(found).href)));
         }
         catch {
             return null;
@@ -63,20 +75,72 @@ export class ImportLoader extends Loader {
         const { module, version, classes } = exported;
         if (typeof module !== 'string' || typeof version !== 'string' || !Array.isArray(classes))
             return null;
-        return { module, version, classes, from: path };
+        return { module, version, classes, from: isFile(from) ? found : from };
+    }
+    #package(name) {
+        for (const base of this.#bases) {
+            try {
+                return createRequire(join(resolve(base), 'noop.js')).resolve(name);
+            }
+            catch {
+                // Not installed from here; the next base may hold it.
+            }
+        }
+        return null;
     }
 }
-// The modules a harbor is handed, by name, and then files.
+// A module by its id, the name it declares, so the catalogue's cells name
+// code the same way on every ground. `add` may name a module by its id, a
+// file, or an installed package, and the ground works out which. The
+// modules a harbor is handed are found by their id first. Where else an id
+// is found, a file's path or a package's name, is this ground's own
+// knowledge, kept beside the harbor in `<dir>/modules.json` and never in
+// the sealed package, since another ground finds the same id in its own
+// bundle. Packages resolve from where the command runs, then from the
+// harbor's folder.
 export class NodeLoader extends ImportLoader {
     #held;
-    constructor(modules = []) {
-        super();
+    #map;
+    constructor(modules = [], dir) {
+        super(dir === undefined ? [process.cwd()] : [process.cwd(), dir]);
         this.#held = new HeldLoader(modules);
+        this.#map = dir === undefined ? undefined : join(dir, MODULES);
     }
     async load(from) {
-        return (await this.#held.load(from)) ?? super.load(from);
+        const held = await this.#held.load(from);
+        if (held)
+            return held;
+        const known = await this.#known();
+        const where = known[from];
+        if (where !== undefined) {
+            const loaded = await super.load(where);
+            return loaded?.module === from ? { ...loaded, from } : null;
+        }
+        const loaded = await super.load(from);
+        if (!loaded)
+            return null;
+        if (this.#map && known[loaded.module] !== loaded.from)
+            await this.#keep({ ...known, [loaded.module]: loaded.from });
+        return { ...loaded, from: loaded.module };
+    }
+    async #known() {
+        if (!this.#map)
+            return {};
+        try {
+            return JSON.parse(await readFile(this.#map, 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    async #keep(files) {
+        await mkdir(dirname(this.#map), { recursive: true, mode: 0o700 });
+        await writeFile(`${this.#map}.new`, `${JSON.stringify(files, null, 2)}\n`, { mode: 0o600 });
+        await rename(`${this.#map}.new`, this.#map);
     }
 }
+// Where a Node harbor's module ids find their files.
+export const MODULES = 'modules.json';
 // One root request over a served harbor's socket, or undefined where none
 // is served.
 export const askServed = (dir, request) => new Promise((done, fail) => {
@@ -101,7 +165,7 @@ export class NodeTerrain extends PointerTerrain {
         const entropy = new CryptoEntropy();
         super({
             entropy,
-            loader: new NodeLoader(parts.modules),
+            loader: new NodeLoader(parts.modules, parts.dir),
             custody: new FolderCustody(parts.dir, entropy),
             memory: new FolderMemory(parts.dir),
             faculties: [tcpFaculty, webGround, webPush],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nervur",
-  "version": "0.20.2",
+  "version": "0.20.3",
   "description": "Nervur's kit of Quo: an object asks another object and gets an answer, without knowing where it is.",
   "keywords": [
     "quo",

package/src/cli/command.ts

@@ -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
@@ -45,10 +50,12 @@ import { readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import type { JsonObject } from '../being/index.ts';
 import type { RootRequest } from '../harbor/index.ts';
-import { harborDir } from '../node/index.ts';
-import { carry, isServed, land, open, request, serve } from './harbor.ts';
+import { WEB_OPENING } from '../line/index.ts';
+import { harborDir, isFile } from '../node/index.ts';
+import { readAt, webAddress } from '../quo/index.ts';
+import { carry, isServed, land, open, pack, request, serve } from './harbor.ts';
 
-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]';
+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: string, words: string[], flags: Record<string
   switch (command) {
     case 'module': {
       const [verb, what] = need(2);
-      if (verb === 'add') return catalogue('add', { from: resolve(what!) });
+      if (verb === 'add') 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');
     }
@@ -174,6 +181,12 @@ export const main = async (argv: string[], env: Record<string, string | undefine
     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');
     const served = await serve(dir, flags.host, flags.port === undefined ? undefined : Number(flags.port));
@@ -187,7 +200,9 @@ export const main = async (argv: string[], env: Record<string, string | undefine
     if (words.length !== 2 && words.length !== 3) throw new Error('pilot takes a name, an invitation, and an address where the invitation carries none');
     const [name, invitation, at] = words as [string, string, string | undefined];
     const held = JSON.parse(invitation) as JsonObject;
-    for (const req of pilotRequests(name, held, at)) {
+    const census = (await request(dir, {})) as { answer?: { beings?: JsonObject } };
+    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;
       if (req.method === 'ask') await request(dir, { method: 'unboot', args: { being: name } });
@@ -200,9 +215,12 @@ export const main = async (argv: string[], env: Record<string, string | undefine
   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: string, invitation: JsonObject, at?: string): RootRequest[] => [
+// 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: string, invitation: JsonObject, at?: string, web = false): RootRequest[] => [
+  ...(!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/src/cli/harbor.ts

@@ -7,13 +7,13 @@
 // 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 type { JsonObject } from '../being/index.ts';
-import { hex, isHex, unhex } from '../crypto/index.ts';
+import { hex } from '../crypto/index.ts';
 import { FolderCustody, FolderMemory } from '../folder/index.ts';
-import { Harbor, rootLine, type CarrierFaculty, type RootRequest } from '../harbor/index.ts';
-import { askServed, NodeTerrain, socketOf } from '../node/index.ts';
+import { carryPlaces, Harbor, landPlaces, readCarried, rootLine, type CarrierFaculty, type Carried, type RootRequest } from '../harbor/index.ts';
+import { askServed, MODULES, NodeTerrain, socketOf } from '../node/index.ts';
 import { CryptoEntropy } from '../pointer/index.ts';
 import { TCP_OPENING } from '../tcp/index.ts';
 
@@ -35,51 +35,42 @@ export const request = async (dir: string, req: RootRequest): Promise<JsonObject
   }
 };
 
-// A harbor as one JSON value, for carrying it to another ground: every
-// place of its memory with its sealed entries as hex, and its seed only
-// where the one who asks says so, since custody holds it and a package
-// without it opens nowhere.
-export type Carried = { seed?: string; places: Record<string, Record<string, string>> };
-
-const carried = (value: unknown): Carried | null => {
-  if (typeof value !== 'object' || value === null) return null;
-  const { seed, places } = value as { seed?: unknown; places?: unknown };
-  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 as Carried['places'] };
+// 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: string, seed: boolean): Promise<Carried> => {
+  const places = await carryPlaces(new FolderMemory(dir));
+  const modules = await readFile(join(dir, MODULES), 'utf8').then((text) => JSON.parse(text) as Record<string, string>, () => undefined);
+  return {
+    ...(seed ? { seed: hex(await new FolderCustody(dir, new CryptoEntropy()).seed()) } : {}),
+    places,
+    ...(modules ? { modules } : {}),
+  };
 };
 
-// The harbor of a folder, read as bytes alone. No harbor opens, so
-// nothing is asked and nothing is written.
-export const carry = async (dir: string, seed: boolean): Promise<Carried> => {
-  const memory = new FolderMemory(dir);
-  const places: Carried['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 };
+// 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: string, file: string): Promise<JsonObject> => {
+  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: string, value: unknown): Promise<string[]> => {
-  const held = carried(value);
+  const held = readCarried(value);
   if (held === null) throw new Error('that is no carried harbor');
   const memory = new FolderMemory(dir);
   if ((await memory.places()).length > 0 || (held.seed !== undefined && existsSync(join(dir, 'seed')))) throw new Error(`a harbor stands at ${dir}`);
   await mkdir(dir, { recursive: true, mode: 0o700 });
   if (held.seed !== undefined) 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);
 };
 
 // A served harbor: its pk, its tcp address, every address its carriers

package/src/edge/index.ts

@@ -1,12 +1,18 @@
 // SPDX-License-Identifier: Apache-2.0
 // `nervur/edge`: the edge ground, Cloudflare Workers with a Durable Object
-// per harbor. The object's storage keeps the harbor's sealed memory and
-// its seed, sealed under the worker's `NERVUR_SECRET`; the object answers
-// Quo over the web, a post or a held line, since a worker takes no
-// inbound TCP; and it asks over TCP and the web.
+// per harbor. The object's storage keeps the harbor's sealed memory; the
+// object answers Quo over the web, a post or a held line, since a worker
+// takes no inbound TCP; and it asks over TCP and the web.
+//
+// A harbor born on another ground is carried here: its seed is the
+// worker's `NERVUR_SEED`, and its sealed package, bundled with the worker,
+// lands in the object's storage the first time the object starts. Its
+// owner holds the owner invitation minted where it was born, and pilots
+// it over the web. A harbor born here draws its seed and seals it under
+// the worker's `NERVUR_SECRET`.
 //
 //   m/<place>/<name>   one sealed entry of the harbor's memory
-//   c/seed             the seed, sealed under a key from the secret
+//   c/seed             a drawn seed, sealed under a key from the secret
 //
 // A keep is one storage transaction, whole or nothing. The storage and
 // state types name only what the kit uses, so no Cloudflare package is a
@@ -14,12 +20,14 @@
 import type { AskSpec, JsonObject } from '../being/index.ts';
 import { Custody, Memory, type Entropy, type Module } from '../contract/index.ts';
 import { decrypt, encrypt, hkdf, isHex, unhex, utf8 } from '../crypto/index.ts';
-import { addGround, CarrierFaculty, Harbor, UNDIALED, type Dialed, type Ground, type GroundFaculty, type GroundProbe } from '../harbor/index.ts';
+import { addGround, CarrierFaculty, Harbor, landPlaces, UNDIALED, type Carried, type Dialed, type Ground, type GroundFaculty, type GroundProbe } from '../harbor/index.ts';
 import { answerHeld, answerPost, askFrame, FrameReader, TCP, TCP_OPENING, WEB_OPENING, webFaculty, webPush, type WebListen, type WebListener } from '../line/index.ts';
 import { CryptoEntropy, HeldLoader, PointerTerrain } from '../pointer/index.ts';
 import { tcpAddress, tcpAt, type TcpAddress } from '../quo/index.ts';
 import { ownerAsk } from '../ward/index.ts';
 
+export type { Carried } from '../harbor/index.ts';
+
 export const EDGE = 'edge';
 const ENTRY = 'm/';
 const SEED = 'c/seed';
@@ -39,8 +47,10 @@ export interface EdgeState {
   readonly storage: EdgeStorage;
   blockConcurrencyWhile<T>(work: () => Promise<T>): Promise<T>;
 }
-export type EdgeEnv = { readonly NERVUR_SECRET?: string };
-export type EdgeGiven = { readonly state: EdgeState; readonly env: EdgeEnv };
+export type EdgeEnv = { readonly NERVUR_SEED?: string; readonly NERVUR_SECRET?: string };
+// What the object hands its harbor: its state, the worker's environment,
+// and a carried package to land where the object keeps nothing yet.
+export type EdgeGiven = { readonly state: EdgeState; readonly env: EdgeEnv; readonly package?: Carried };
 
 const chunks = <T>(items: readonly T[]): T[][] => Array.from({ length: Math.ceil(items.length / BATCH) }, (_, i) => items.slice(i * BATCH, (i + 1) * BATCH));
 const bytesOf = (value: unknown): Uint8Array => new Uint8Array(value instanceof ArrayBuffer ? value : (value as Uint8Array));
@@ -89,24 +99,33 @@ 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.
+// The seed a harbor carried here was born with, as 64 hex, where it is
+// named. Otherwise a seed drawn once and kept sealed under a key the
+// secret gives, so the storage alone opens nothing. A harbor with neither
+// does not stand.
+export type EdgeKeys = { readonly seed?: string | undefined; readonly secret?: string | undefined };
+
 export class EdgeCustody extends Custody {
   readonly #storage: EdgeStorage;
-  readonly #secret: string | undefined;
+  readonly #keys: EdgeKeys;
   readonly #entropy: Entropy;
   readonly #key: string;
-  constructor(storage: EdgeStorage, secret: string | undefined, entropy: Entropy = new CryptoEntropy(), root = '') {
+  constructor(storage: EdgeStorage, keys: EdgeKeys, entropy: Entropy = new CryptoEntropy(), root = '') {
     super();
     this.#storage = storage;
-    this.#secret = secret;
+    this.#keys = keys;
     this.#entropy = entropy;
     this.#key = `${root}${SEED}`;
   }
 
   async seed(): Promise<Uint8Array> {
-    if (!this.#secret) throw new Error('the worker holds no NERVUR_SECRET');
-    const key = await hkdf(utf8(this.#secret), SEAL_INFO, 32);
+    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(secret), SEAL_INFO, 32);
     return this.#storage.transaction(async (txn) => {
       const kept = (await txn.get(this.#key)) as { nonce: Uint8Array; sealed: Uint8Array } | undefined;
       if (kept) {
@@ -284,7 +303,9 @@ 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],
@@ -292,6 +313,15 @@ export class EdgeTerrain extends PointerTerrain {
     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`.
+  override async claim(): Promise<void> {
+    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);
+  }
+
   override stand(harbor: Harbor): Promise<void> {
     this.#harbor = harbor;
     return Promise.resolve();
@@ -328,11 +358,27 @@ export const edgeGround: GroundProbe = {
   terrain: ({ given, modules }) => new EdgeTerrain({ given: given as EdgeGiven, ...(modules ? { modules } : {}) }),
 };
 
-// A Durable Object class whose every instance is one harbor: opened once
-// per object, with `stood` run on it as the worker's own code, and every
-// request it receives answered by the harbor's web carrier.
+// What a Durable Object class of harbors is made of:
+//
+//   modules   the code its harbors run
+//   package   a harbor carried here, from `nervur edge pack`, landed the
+//             first time an object starts; or a function of the worker's
+//             environment giving one
+//   path      where every object answers Quo, `/quo` unless named, on
+//             whatever host reaches it
+//   stood     the worker's own code, the root, run once the harbor stands
+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 const harborObject = (modules: readonly Module[], stood?: (harbor: Harbor) => Promise<void>): HarborObjectClass =>
+
+// 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 }: HarborObjectParts): HarborObjectClass =>
   class HarborObject {
     readonly #opening: Promise<Harbor>;
 
@@ -343,10 +389,13 @@ export const harborObject = (modules: readonly Module[], stood?: (harbor: Harbor
 
     constructor(state: EdgeState, env: EdgeEnv) {
       addGround(edgeGround);
+      const held = typeof carried === 'function' ? carried(env) : carried;
+      const given: EdgeGiven = { 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;
       });
@@ -354,6 +403,11 @@ export const harborObject = (modules: readonly Module[], stood?: (harbor: Harbor
 
     async fetch(request: Request): Promise<Response> {
       const harbor = await this.#opening;
-      return (harbor.terrain as EdgeTerrain).answer(request);
+      const terrain = harbor.terrain as EdgeTerrain;
+      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/src/harbor/index.ts

@@ -5,7 +5,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/src/harbor/package.ts

@@ -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.ts';
+import { concat, decrypt, encrypt, hex, hkdf, isHex, unhex, utf8 } from '../crypto/index.ts';
 import type { Entropy, Memory, Rows } from '../contract/index.ts';
 import { HEAD_ROW } from '../ward/index.ts';
 
@@ -28,6 +28,44 @@ export const copyPackage = async (from: Memory, to: Memory): Promise<string[]> =
   return places;
 };
 
+// A harbor as one JSON value, for carrying it to another ground: every
+// place of its memory with its sealed entries as hex, its seed only where
+// the one who carries it says so, and where the ground it left found each
+// module id, a hint the next ground of the same kind may take.
+export type Carried = { seed?: string; places: Record<string, Record<string, string>>; modules?: Record<string, string> };
+
+// A carried harbor as JSON reads, or null for anything else.
+export const readCarried = (value: unknown): Carried | null => {
+  if (typeof value !== 'object' || value === null) return null;
+  const { seed, places, modules } = value as { seed?: unknown; places?: unknown; modules?: unknown };
+  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 as Carried['places'], ...(modules === undefined ? {} : { modules: modules as Record<string, string> }) };
+};
+
+// Every place of a memory, as a carried harbor holds it.
+export const carryPlaces = async (memory: Memory): Promise<Carried['places']> => {
+  const places: Carried['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: Memory, carried: Carried): Promise<string[]> => {
+  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');
 

package/src/harbor/relay.ts

@@ -183,10 +183,20 @@ export const relayFaculty = (clock: Clock): BeingClass =>
       if (replies === null) 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);
       const boxes = this.#waiting.filter((b) => wards.includes(b.ward)).slice(0, BATCH);
@@ -271,6 +281,7 @@ export const relayClient = (ground: Ground, clock: Clock): BeingClass =>
 
     #awake = false;
     #replies: Reply[] = [];
+    #turn: Promise<unknown> = Promise.resolve();
     // Ends every rest and schedule when the client sleeps or lets go.
     #stop: () => void = () => {};
 
@@ -380,7 +391,15 @@ export const relayClient = (ground: Ground, clock: Clock): BeingClass =>
     // 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: boolean): Promise<number | null> {
+    // 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: boolean): Promise<number | null> {
+      const run = this.#turn.then(() => this.#collectNow(wait));
+      this.#turn = run.catch(() => undefined);
+      return run;
+    }
+
+    async #collectNow(wait: boolean): Promise<number | null> {
       const standing = this.stance.standings.get(CLIENT);
       if (!standing) return null;
       const replies = this.#replies.splice(0);