nervur 0.20.0 → 0.20.2

package/src/harbor/catalogue.ts

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: Apache-2.0
+// The catalogue: the dock's first faculty, the code a harbor runs. Her
+// cells name each module by the name it declares, its version, and where
+// the terrain's loader finds it. The harbor wakes her before any other
+// faculty, and she runs every module she names that is found and splits
+// no kind. One that is not stays out alone, with its reason, and the
+// beings of its kinds stand absent.
+//
+//   add     { from }      the module the loader finds there, run from now
+//                         on; the same module again takes its new version
+//   remove  { module }    a module no being stands on, by the kinds kept
+//                         for it, run no more
+//   modules               what she names, each with the version running,
+//                         and why one does not run
+//
+// She is the kit's, of kind `org.nervur.catalogue`, and answers the root
+// and an owner alone.
+import { Faculty, type AskSpec, type BeingClass, type JsonObject, type Stance } from '../being/index.ts';
+import type { Loaded } from '../contract/index.ts';
+import { ownerAsk } from '../ward/index.ts';
+
+export const CATALOGUE = 'catalogue';
+
+// One module, as her cells keep it.
+// Its kinds are kept beside it, so a module that does not load is still
+// known by the beings that stand on it.
+export type ModuleRow = { version: string; from: string; kinds: string[] };
+
+// What the catalogue asks of her harbor.
+export interface Cataloguing {
+  load(from: string): Promise<Loaded | null>;
+  // Why these modules cannot run together, or null.
+  check(modules: readonly Loaded[]): string | null;
+  // The modules run from now on, or why they cannot be.
+  run(modules: readonly Loaded[]): string | null;
+  // Whether a being of any ward stands on one of these kinds.
+  stands(kinds: readonly string[]): boolean;
+  kindsOf(module: string): string[];
+}
+
+const text = (v: unknown): v is string => typeof v === 'string';
+
+export class Catalogue extends Faculty {
+  static override readonly kind: string = 'org.nervur.catalogue';
+  static override cells: JsonObject = { modules: {} };
+  static override asks: Record<string, AskSpec> = {
+    add: ownerAsk('a module run from now on', { required: ['from'] }),
+    remove: ownerAsk('a module run no more', { required: ['module'] }),
+    modules: ownerAsk('the modules this harbor runs'),
+  };
+
+  readonly #harbor: Cataloguing;
+  readonly #running = new Map<string, Loaded>();
+  readonly #failed = new Map<string, string>();
+
+  constructor(stance: Stance, harbor: Cataloguing) {
+    super(stance);
+    this.#harbor = harbor;
+  }
+
+  get #rows(): Record<string, ModuleRow> {
+    return this.cells.modules as Record<string, ModuleRow>;
+  }
+
+  // Every module her cells name, in their order, loaded and run where it
+  // is found, is the module named, and splits no kind with those before
+  // 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 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!);
+      else this.#failed.set(module, refused);
+    }
+    this.#harbor.run([...this.#running.values()]);
+  }
+
+  async add(args: JsonObject): Promise<JsonObject> {
+    if (!text(args.from)) return { error: 'from is text' };
+    const loaded = await this.#harbor.load(args.from);
+    if (loaded === null) return { error: 'no such module' };
+    const running = new Map(this.#running);
+    running.set(loaded.module, loaded);
+    const refused = this.#harbor.run([...running.values()]);
+    if (refused !== null) return { error: refused };
+    this.#running.set(loaded.module, loaded);
+    this.#failed.delete(loaded.module);
+    this.#rows[loaded.module] = { version: loaded.version, from: loaded.from, kinds: this.#harbor.kindsOf(loaded.module) };
+    return { added: loaded.module, version: loaded.version };
+  }
+
+  remove(args: JsonObject): JsonObject {
+    const module = args.module;
+    if (!text(module) || !Object.hasOwn(this.#rows, module)) return { error: 'no such module' };
+    const kinds = new Set([...this.#rows[module]!.kinds, ...this.#harbor.kindsOf(module)]);
+    if (this.#harbor.stands([...kinds])) return { error: 'a being stands on this module' };
+    const running = new Map(this.#running);
+    running.delete(module);
+    this.#harbor.run([...running.values()]);
+    this.#running.delete(module);
+    this.#failed.delete(module);
+    delete this.#rows[module];
+    return { removed: module };
+  }
+
+  modules(): JsonObject {
+    const out: JsonObject = {};
+    for (const [module, row] of Object.entries(this.#rows)) {
+      const failed = this.#failed.get(module);
+      out[module] = { version: row.version, running: this.#running.get(module)?.version ?? null, from: row.from, ...(failed === undefined ? {} : { failed }) };
+    }
+    return out;
+  }
+}
+
+// The catalogue class one harbor stands: a being is born of her class and
+// her stance alone, so the class holds its harbor.
+export const catalogueFor = (harbor: Cataloguing): BeingClass =>
+  class extends Catalogue {
+    static override readonly kind: string = Catalogue.kind;
+    constructor(stance: Stance) {
+      super(stance, harbor);
+    }
+  };

package/src/harbor/dock.ts

@@ -5,30 +5,69 @@
 //
 //   open    { key, class }      a faculty stands in the box ward, and the
 //                               dock holds a standing on her under her key
-//   host    { ward }            a hosted ward stands, holding a standing on
-//                               the dock
+//   host    { ward, seed? }     a hosted ward stands under the seed named,
+//                               or a drawn one, holding a standing on the
+//                               dock; the dock keeps its name and seed
 //   lend    { contract }        asked by a hosted ward: an offer from a
 //                               faculty that fulfils the contract
 //   retract { contract, heir }  an offer that was not taken
-import { Faculty, type Asker, type AskSpec, type Invitation, type JsonObject } from '../being/index.ts';
-import { readInvitation } from '../quo/index.ts';
-import { ownerAsk, WardBeing, type Lender, type WardBeingStance } from '../ward/index.ts';
+//   route   { ward, at }        where a ward pk is reached, addresses in the
+//                               order they are tried, or null to forget
+//                               it; the dock keeps it and the harbor hands
+//                               it to its carrier
+//   reach   { at }              where this harbor is reached, the
+//                               addresses every invitation it gives carries
+//
+// A take of an invitation that carries `at` teaches the dock that ward's
+// route, where the root set none.
+import { Faculty, KIT, type Asker, type AskSpec, type Blueprint, type Invitation, type JsonObject } from '../being/index.ts';
+import { CATALOGUE } from './catalogue.ts';
+import { readAt, readInvitation } from '../quo/index.ts';
+import { ownerAsk, pilots, rootAsk, WardBeing, type Lender, type WardBeingStance } from '../ward/index.ts';
 
-// What the dock asks of her harbor.
+// What the dock asks of her harbor: a ward standing, and the seed, as hex,
+// it stands under.
 export interface Hosting {
-  host(name: string, invitation: Invitation): Promise<boolean>;
+  host(name: string, invitation: Invitation, seed?: string): Promise<string | null>;
+  // Whether the harbor's carrier took the route.
+  route(pk: string, at: readonly string[] | null): boolean;
+  // Whether the box ward's partition was kept.
+  keep(): Promise<boolean>;
+  // What did not stand when the harbor opened.
+  failures(): Failures;
+  // Every place of the memory the dock does not name, gone.
+  sweep(): Promise<string[]>;
+  // Whether a kind is a carrier this harbor's ground ships.
+  grounds(kind: string): boolean;
+  // A faculty just opened, woken where it wakes, and one about to go, put
+  // to sleep.
+  awaken(key: string): Promise<void>;
+  lull(key: string): Promise<void>;
 }
 
+// One hosted ward, as the dock's cells keep it.
+export type Hosted = { ward: string; seed: string };
+
+// Each hosted ward that did not unpack and each route the carrier did not
+// take, with the reason, by name and by ward pk.
+export type Failures = { wards: Record<string, string>; routes: Record<string, string> };
+
 export const BOX = 'box';
 const text = (v: unknown): v is string => typeof v === 'string';
+// A list of addresses, each a URI with a scheme, and at least one.
+const addresses = (v: unknown): v is string[] => Array.isArray(v) && v.length > 0 && readAt(v).length === v.length;
 const hosted: AskSpec['for'] = (_: Asker, notes: JsonObject | undefined) => notes?.hosted === true;
 
 export class Dock extends WardBeing implements Lender {
-  static override cells: JsonObject = { hosted: [] };
+  static override readonly kind: string = 'org.nervur.dock';
+  static override cells: JsonObject = { hosted: [], routes: {}, reach: [] };
   static override asks: Record<string, AskSpec> = {
     ...WardBeing.asks,
     open: ownerAsk('a faculty of this harbor', { required: ['key', 'class'] }),
     host: ownerAsk('a ward this harbor hosts', { required: ['ward'] }),
+    route: ownerAsk('where a ward is reached, addresses in order, or null', { required: ['ward', 'at'] }),
+    reach: ownerAsk('where this harbor is reached, the addresses every invitation carries', { required: ['at'] }),
+    sweep: rootAsk('every place of the memory this harbor does not name, gone'),
     lend: { description: 'an offer from a faculty fulfilling a contract', input: { type: 'object', required: ['contract'] }, for: hosted },
     retract: { description: 'an offer that was not taken', input: { type: 'object', required: ['contract', 'heir'] }, for: hosted },
   };
@@ -40,27 +79,95 @@ export class Dock extends WardBeing implements Lender {
     this.#hosting = hosting;
   }
 
-  get hosted(): string[] {
-    return [...(this.cells.hosted as string[])];
+  // The census adds what did not stand, for whoever pilots.
+  override describe(asker: Asker): Blueprint {
+    const blueprint = super.describe(asker);
+    if (pilots(asker, this.notes(asker))) (blueprint.notes as JsonObject).failed = this.#hosting.failures();
+    return blueprint;
+  }
+
+  get hosted(): Hosted[] {
+    return (this.cells.hosted as Hosted[]).map(({ ward, seed }) => ({ ward, seed }));
+  }
+
+  get routes(): Record<string, string[]> {
+    return Object.fromEntries(Object.entries(this.cells.routes as Record<string, string[]>).map(([pk, at]) => [pk, [...at]]));
+  }
+
+  // Where this harbor is reached, in the order a caller tries it.
+  get addresses(): string[] {
+    return [...(this.cells.reach as string[])];
+  }
+
+  route(args: JsonObject): JsonObject {
+    const { ward } = args;
+    const at = typeof args.at === 'string' ? [args.at] : args.at;
+    if (!text(ward) || (at !== null && !addresses(at)) || !this.#hosting.route(ward, at)) return { error: 'not routed' };
+    const routes = this.cells.routes as Record<string, string[]>;
+    if (at === null) delete routes[ward];
+    else routes[ward] = [...at];
+    return { routed: ward };
+  }
+
+  reach(args: JsonObject): JsonObject {
+    if (!addresses(args.at)) return { error: 'at is a list of addresses' };
+    this.cells.reach = [...args.at];
+    return { reach: [...args.at] };
+  }
+
+  // A route learned from an invitation's `at`, where the root set none,
+  // and where the carrier dials one of its addresses.
+  async learn(ward: string, at: readonly string[]): Promise<void> {
+    const routes = this.cells.routes as Record<string, string[]>;
+    if (Object.hasOwn(routes, ward) || !this.#hosting.route(ward, at)) return;
+    routes[ward] = [...at];
+    await this.#hosting.keep();
+  }
+
+  // Genesis: the catalogue stands first, and is kept at once.
+  async standCatalogue(): Promise<void> {
+    const kind = 'org.nervur.catalogue';
+    if ((await this.stance.boot(kind, CATALOGUE, CATALOGUE)) === null || !(await this.#hosting.keep())) throw new Error('the catalogue did not stand');
+  }
+
+  // A faculty that goes stops listening first.
+  override async unboot(args: JsonObject): Promise<JsonObject> {
+    if (typeof args.being === 'string') await this.#hosting.lull(args.being);
+    return super.unboot(args);
+  }
+
+  // Genesis: the carriers the terrain names stand next, each kept at once.
+  async standCarriers(opens: readonly { key: string; kind: string }[]): Promise<void> {
+    for (const { key, kind } of opens) await this.open({ key, class: kind });
+    await this.#hosting.keep();
   }
 
   async open(args: JsonObject): Promise<JsonObject> {
     if (!text(args.key) || !text(args.class)) return { error: 'key and class are text' };
-    if (!Faculty.fulfils(this.steward.classOf(args.class))) return { error: 'no such faculty' };
+    const mine = args.class.startsWith(KIT) ? this.#hosting.grounds(args.class) : true;
+    if (!mine || !Faculty.fulfils(this.steward.classOf(args.class))) return { error: 'no such faculty' };
     const opened = await this.stance.boot(args.class, args.key, args.key);
-    return opened === null ? { error: 'not opened' } : { opened };
+    if (opened === null) return { error: 'not opened' };
+    await this.#hosting.awaken(opened);
+    return { opened };
+  }
+
+  async sweep(): Promise<JsonObject> {
+    return { swept: await this.#hosting.sweep() };
   }
 
   async host(args: JsonObject): Promise<JsonObject> {
     const name = args.ward;
-    if (!text(name) || name === BOX || this.hosted.includes(name)) return { error: 'no such ward to host' };
+    if (!text(name) || name === BOX || this.hosted.some((h) => h.ward === name)) return { error: 'no such ward to host' };
+    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' };
-    if (!(await this.#hosting.host(name, invitation))) {
+    const seed = await this.#hosting.host(name, invitation, args.seed);
+    if (seed === null) {
       this.stance.occupants.remove(name);
       return { error: 'not hosted' };
     }
-    (this.cells.hosted as string[]).push(name);
+    (this.cells.hosted as Hosted[]).push({ ward: name, seed });
     return { hosted: name };
   }
 

package/src/harbor/harbor.ts

@@ -1,39 +1,121 @@
 // SPDX-License-Identifier: Apache-2.0
-// The harbor: the onion, unpacked from a terrain and a catalogue.
+// The harbor: the onion, unpacked from a terrain alone.
 //
-//   1. custody and memory     the box ward's seed and rows, from the terrain
-//   2. the box ward           unpacked as every ward is, its ward-being the dock
-//   3. the faculties          the box ward's beings, each from her own row
-//   4. the hosted wards       as the dock's cells list them
-//   5. the beings             in each ward, each from her own row
+//   1. the seed and the package   the harbor's one secret, from custody,
+//                                 opens its sealed memory
+//   2. the box ward               unpacked as every ward is, under the
+//                                 harbor's seed, its ward-being the dock
+//   3. the catalogue              the dock's first faculty, a kit class:
+//                                 every module her cells name is loaded
+//                                 through the terrain, or the harbor does
+//                                 not stand
+//   4. the faculties              the box ward's other beings, each from her
+//                                 own row, by the kinds the modules bring
+//   5. the routes                 as the dock's cells keep them, handed to
+//                                 the terrain's carrier
+//   6. the hosted wards           as the dock's cells list them, each under
+//                                 the seed the dock keeps for it
+//   7. the beings                 in each ward, each from her own row
+//
+// The harbor fails only where the seed or the box ward's own place cannot
+// be read. A module, a route, a hosted ward or a being that cannot stand
+// fails alone, and the census names it.
 //
 // Genesis and wake are one path: empty memory unpacks a box ward holding
-// the dock alone, and the root's asks write the rest.
+// the dock, the dock stands the catalogue, and the root's asks write the
+// rest.
 import type { Answer, BeingClass, Invitation, JsonObject } from '../being/index.ts';
-import { Carrier } from '../contract/index.ts';
-import { DOCK, Ward, type WardParts } from '../ward/index.ts';
-import { BOX, Dock, type Hosting } from './dock.ts';
+import { Carrier, type Loaded } from '../contract/index.ts';
+import { hex, isHex, unhex } from '../crypto/index.ts';
+import { unspecified, WardKey } from '../quo/index.ts';
+import { DOCK, Pilot, Ward, type Catalogue as Resolving, type Routes, type WardParts } from '../ward/index.ts';
+import { Catalogue, CATALOGUE, catalogueFor, type Cataloguing } from './catalogue.ts';
+import { CarrierFaculty, UNDIALED } from './carrying.ts';
+import { BOX, Dock, type Failures, type Hosting } from './dock.ts';
+import { Package } from './package.ts';
 import { Registry } from './registry.ts';
-import type { Terrain } from './terrain.ts';
+import { relayClient, relayFaculty } from './relay.ts';
+import { probeGround, type Probing } from './probe.ts';
+import { Terrain } from './terrain.ts';
 
-export class Harbor extends Carrier implements Hosting {
+export class Harbor extends Carrier implements Hosting, Cataloguing, Resolving {
   readonly terrain: Terrain;
-  readonly registry: Registry;
+  readonly #package: Package;
   readonly #wards = new Map<string, Ward>();
+  readonly #kit: BeingClass[];
+  readonly #grounds: Set<string>;
+  #registry: Registry;
+  readonly #failed: Failures = { wards: {}, routes: {} };
 
-  private constructor(terrain: Terrain, registry: Registry) {
+  private constructor(terrain: Terrain, pack: Package) {
     super();
     this.terrain = terrain;
-    this.registry = registry;
+    this.#package = pack;
+    const faculties = [...terrain.faculties.map((make) => make(this)), relayFaculty(terrain.clock), relayClient(this, terrain.clock)];
+    this.#grounds = new Set(faculties.map((C) => C.kind));
+    this.#kit = [catalogueFor(this), Pilot, ...faculties];
+    this.#registry = new Registry(this.#kit, []);
+  }
+
+  // A harbor on the terrain handed in, or, with none, on the ground the
+  // probe finds here. A ground another run holds refuses, and what the
+  // ground serves beside the harbor stands once it is whole.
+  static async open(from: Terrain | Probing = {}): Promise<Harbor> {
+    const terrain = from instanceof Terrain ? from : probeGround(from).terrain;
+    await terrain.claim();
+    let harbor: Harbor;
+    try {
+      harbor = await Harbor.#stand(terrain);
+    } catch (e) {
+      await terrain.release();
+      throw e;
+    }
+    try {
+      await terrain.stand(harbor);
+    } catch (e) {
+      await harbor.close();
+      throw e;
+    }
+    return harbor;
   }
 
-  static async open(terrain: Terrain, classes: readonly BeingClass[]): Promise<Harbor> {
-    const harbor = new Harbor(terrain, new Registry(classes));
-    await harbor.#unpack(BOX, undefined, (stance) => new Dock(stance, harbor));
-    for (const name of harbor.dock.hosted) await harbor.#unpack(name);
+  static async #stand(terrain: Terrain): Promise<Harbor> {
+    const seed = await terrain.custody.seed();
+    const harbor = new Harbor(terrain, await Package.open(terrain.memory, terrain.entropy, seed));
+    await harbor.#unpack(BOX, seed, undefined, (stance) => new Dock(stance, harbor));
+    const genesis = !harbor.box.partition.being(CATALOGUE);
+    if (genesis) await harbor.dock.standCatalogue();
+    await harbor.catalogue.wake();
+    if (genesis) await harbor.dock.standCarriers(terrain.opens);
+    else if (terrain.wakes) for (const carrier of harbor.carriers) await carrier.awake();
+    for (const [pk, at] of Object.entries(harbor.dock.routes)) {
+      if (!harbor.#dialable(at)) harbor.#failed.routes[pk] = 'no carrier dials it';
+    }
+    for (const hosted of harbor.dock.hosted) {
+      try {
+        await harbor.#unpack(hosted.ward, unhex(hosted.seed));
+      } catch (e) {
+        harbor.#failed.wards[hosted.ward] = e instanceof Error ? e.message : String(e);
+      }
+    }
     return harbor;
   }
 
+  // Hosting: every place of the terrain's memory the dock does not name,
+  // gone. A crash inside `host` leaves such a place, sealed under a seed
+  // nothing kept, and nothing else writes one.
+  async sweep(): Promise<string[]> {
+    const mine = new Set(await Promise.all([BOX, ...this.dock.hosted.map((h) => h.ward)].map((name) => this.#package.place(name))));
+    const swept = (await this.terrain.memory.places()).filter((place) => !mine.has(place));
+    for (const place of swept) await this.terrain.memory.forget(place);
+    return swept;
+  }
+
+  // Hosting: what did not stand when the harbor opened, each alone.
+  failures(): Failures {
+    return { wards: { ...this.#failed.wards }, routes: { ...this.#failed.routes } };
+  }
+
   get box(): Ward {
     return this.#wards.get(BOX)!;
   }
@@ -42,6 +124,14 @@ export class Harbor extends Carrier implements Hosting {
     return this.box.wardBeing as Dock;
   }
 
+  get catalogue(): Catalogue {
+    return this.box.being(CATALOGUE) as Catalogue;
+  }
+
+  get registry(): Registry {
+    return this.#registry;
+  }
+
   ward(name: string): Ward | undefined {
     return this.#wards.get(name);
   }
@@ -59,45 +149,159 @@ export class Harbor extends Carrier implements Hosting {
     return this.#door(pk) !== undefined;
   }
 
-  // Bytes for one of this harbor's doors, or nothing.
+  // Bytes for one of this harbor's doors, or for a ward a relay of this
+  // harbor answers for, or nothing.
   async arrive(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
     const ward = this.#door(pk);
-    return ward ? (await ward.door.arrive(bytes)).bytes : null;
+    if (ward) return (await ward.door.arrive(bytes)).bytes;
+    return (await this.#relaying(pk)?.relay(pk, bytes)) ?? null;
+  }
+
+  // Carrier: this harbor's own doors and relays first, then a route's
+  // addresses in order, each to the carrier that dials it, and with no
+  // route the terrain's carrier.
+  async carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+    if (this.holds(pk) || this.#relaying(pk)) return this.arrive(pk, bytes);
+    const at = this.dock.routes[pk];
+    if (at === undefined) return this.terrain.carrier.carry(pk, bytes);
+    for (const address of at) {
+      const carrier = this.carriers.find((c) => c.accepts(address));
+      const out = carrier ? await carrier.dial(address, pk, bytes) : UNDIALED;
+      if (out !== UNDIALED) return out;
+    }
+    return null;
   }
 
-  // Carrier: this harbor's own doors first, then the terrain's.
-  carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
-    return this.holds(pk) ? this.arrive(pk, bytes) : this.terrain.carrier.carry(pk, bytes);
+  // Resolving: a kind, by the registry the catalogue runs.
+  classOf(kind: string): BeingClass | undefined {
+    return this.#registry.classOf(kind);
   }
 
-  // Hosting: a ward the dock hosts stands now.
-  async host(name: string, invitation: Invitation): Promise<boolean> {
-    if (this.#wards.has(name)) return false;
+  // Cataloguing: code through the terrain, and the modules run.
+  load(from: string): Promise<Loaded | null> {
+    return this.terrain.loader.load(from);
+  }
+
+  check(modules: readonly Loaded[]): string | null {
+    return Registry.refusal(this.#kit, modules);
+  }
+
+  run(modules: readonly Loaded[]): string | null {
     try {
-      await this.#unpack(name, invitation);
+      this.#registry = new Registry(this.#kit, modules);
+    } catch (e) {
+      return (e as Error).message;
+    }
+    for (const ward of this.#wards.values()) ward.bearAnew();
+    return null;
+  }
+
+  stands(kinds: readonly string[]): boolean {
+    for (const ward of this.#wards.values()) {
+      for (const row of Object.values(ward.partition.beings)) if (kinds.includes(row.class)) return true;
+    }
+    return false;
+  }
+
+  kindsOf(module: string): string[] {
+    return this.#registry.kindsOf(module);
+  }
+
+  // Hosting: a ward the dock hosts stands now, under the seed named or a
+  // drawn one, and the seed it stands under comes back. A ward whose key
+  // another ward of this harbor already has does not stand.
+  async host(name: string, invitation: Invitation, seed?: string): Promise<string | null> {
+    if (this.#wards.has(name)) return null;
+    const bytes = seed === undefined ? this.terrain.entropy.draw(32) : isHex(seed, 32) ? unhex(seed) : null;
+    if (bytes === null || this.holds((await WardKey.from(bytes)).pk)) return null;
+    try {
+      await this.#unpack(name, bytes, invitation);
     } catch {
-      return false;
+      return null;
     }
-    if (this.#wards.get(name)!.wardBeing.stance.standings.get(DOCK)) return true;
+    if (this.#wards.get(name)!.wardBeing.stance.standings.get(DOCK)) return hex(bytes);
     this.#wards.delete(name);
-    return false;
+    return null;
+  }
+
+  keep(): Promise<boolean> {
+    return this.box.partition.kept();
+  }
+
+  // Hosting: a route is taken where a carrier of this harbor dials one of
+  // its addresses; forgetting one always is.
+  route(pk: string, at: readonly string[] | null): boolean {
+    const taken = isHex(pk, 64) && (at === null || this.#dialable(at));
+    if (taken) delete this.#failed.routes[pk];
+    return taken;
+  }
+
+  // Hosting: the carriers this ground ships, and their sleep and waking.
+  grounds(kind: string): boolean {
+    return this.#grounds.has(kind);
   }
 
-  async #unpack(name: string, dock?: Invitation, root?: WardParts['root']): Promise<void> {
-    const { entropy, clock, custody, memory } = this.terrain;
+  async awaken(key: string): Promise<void> {
+    const being = this.box.being(key);
+    if (being instanceof CarrierFaculty) await being.awake();
+  }
+
+  async lull(key: string): Promise<void> {
+    const being = this.box.being(key);
+    if (being instanceof CarrierFaculty) await being.sleep();
+  }
+
+  // The carrier faculties standing in the box ward.
+  get carriers(): CarrierFaculty[] {
+    return Object.keys(this.box.partition.beings)
+      .map((key) => this.box.being(key))
+      .filter((being): being is CarrierFaculty => being instanceof CarrierFaculty);
+  }
+
+  // Every carrier asleep, the last opened first: nothing listens and no
+  // line stays open.
+  async close(): Promise<void> {
+    for (const carrier of this.carriers.reverse()) await carrier.sleep();
+    await this.terrain.release();
+  }
+
+  #relaying(pk: string): CarrierFaculty | undefined {
+    return this.carriers.find((carrier) => carrier.relays(pk));
+  }
+
+  #dialable(at: readonly string[]): boolean {
+    return at.some((address) => this.carriers.some((carrier) => carrier.accepts(address)));
+  }
+
+  async #unpack(name: string, seed: Uint8Array, dock?: Invitation, root?: WardParts['root']): Promise<void> {
+    const { entropy, clock } = this.terrain;
     const ward = await Ward.unpack({
-      seed: await custody.seed(name),
-      memory: await memory.open(name),
-      catalogue: this.registry,
+      seed,
+      memory: await this.#package.rows(name),
+      catalogue: this,
       entropy,
       clock,
       carrier: this,
+      routes: this.#routes,
       ...(dock ? { dock } : {}),
       ...(root ? { root } : {}),
     });
     this.#wards.set(name, ward);
   }
 
+  // Every ward is reached where the harbor is: where the root's `reach`
+  // says, and where it said nothing, where its carriers listen, save the
+  // unspecified host. What a ward learns from an invitation's `at` is the
+  // dock's to keep. A ward of this harbor needs no route.
+  readonly #routes: Routes = {
+    reach: () => {
+      if (!this.#wards.has(BOX)) return [];
+      const set = this.dock.addresses;
+      return set.length > 0 ? set : this.carriers.flatMap((carrier) => carrier.listening()).filter((address) => !unspecified(address));
+    },
+    learn: (ward, at) => (this.holds(ward) ? Promise.resolve() : this.dock.learn(ward, at)),
+  };
+
   #door(pk: string): Ward | undefined {
     for (const ward of this.#wards.values()) if (ward.pk === pk) return ward;
     return undefined;

package/src/harbor/index.ts

@@ -1,6 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
-// The onion: a terrain, a registry, the dock, and the harbor.
-export { BOX, Dock, type Hosting } from './dock.ts';
+// The onion: a terrain, the package, the dock, the catalogue and its
+// registry, and the harbor.
+export { Catalogue, CATALOGUE, type Cataloguing, type ModuleRow } from './catalogue.ts';
+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 { readRootRequest, rootLine, type RootRequest } from './root-line.ts';
+export { addGround, grounds, probeGround, type GroundProbe, type Probing } from './probe.ts';
 export { Registry } from './registry.ts';
-export { Terrain } from './terrain.ts';
+export { Push, PUSH, RELAY, RELAY_CLIENT, RELAY_HOLD, RELAY_REST, RELAY_WAIT, RELAYED } from './relay.ts';
+export { Terrain, type Opening } from './terrain.ts';