nervur 0.20.1 → 0.20.2

package/src/harbor/dock.ts

@@ -11,39 +11,63 @@
 //   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
-//   route   { ward, at }        where a ward pk is reached, `host:port`, or
-//                               null to forget it; the dock keeps it and
-//                               the harbor hands it to its carrier
-import { Faculty, KIT, type Asker, type AskSpec, type Invitation, type JsonObject } from '../being/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 { readInvitation } from '../quo/index.ts';
-import { ownerAsk, WardBeing, type Lender, type WardBeingStance } from '../ward/index.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: a ward standing, and the seed, as hex,
 // it stands under.
 export interface Hosting {
   host(name: string, invitation: Invitation, seed?: string): Promise<string | null>;
   // Whether the harbor's carrier took the route.
-  route(pk: string, at: string | null): boolean;
+  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 readonly kind: string = 'org.nervur.dock';
-  static override cells: JsonObject = { hosted: [], routes: {} };
+  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, or null', { required: ['ward', 'at'] }),
+    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 },
   };
@@ -55,34 +79,81 @@ export class Dock extends WardBeing implements Lender {
     this.#hosting = hosting;
   }
 
+  // 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 { ...(this.cells.routes as Record<string, string>) };
+  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, at } = args;
-    if (!text(ward) || (at !== null && !text(at)) || !this.#hosting.route(ward, at)) return { error: 'not routed' };
-    const routes = this.cells.routes as Record<string, string>;
+    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;
+    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 (args.class.startsWith(KIT) || !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> {

package/src/harbor/harbor.ts

@@ -17,46 +17,105 @@
 //                                 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, 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, type Loaded } from '../contract/index.ts';
 import { hex, isHex, unhex } from '../crypto/index.ts';
-import { WardKey } from '../quo/index.ts';
-import { DOCK, Pilot, Ward, type Catalogue as Resolving, type WardParts } from '../ward/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 { BOX, Dock, type Hosting } from './dock.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, Cataloguing, Resolving {
   readonly terrain: Terrain;
   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, pack: Package) {
     super();
     this.terrain = terrain;
     this.#package = pack;
-    this.#kit = [catalogueFor(this), Pilot];
+    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, []);
   }
 
-  static async open(terrain: Terrain): Promise<Harbor> {
+  // 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 #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));
-    if (!harbor.box.partition.being(CATALOGUE)) await harbor.dock.standCatalogue();
+    const genesis = !harbor.box.partition.being(CATALOGUE);
+    if (genesis) await harbor.dock.standCatalogue();
     await harbor.catalogue.wake();
-    for (const [pk, at] of Object.entries(harbor.dock.routes)) terrain.carrier.route(pk, at);
-    for (const hosted of harbor.dock.hosted) await harbor.#unpack(hosted.ward, unhex(hosted.seed));
+    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)!;
   }
@@ -90,15 +149,27 @@ export class Harbor extends Carrier implements Hosting, Cataloguing, Resolving {
     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 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);
+  // 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;
   }
 
   // Resolving: a kind, by the registry the catalogue runs.
@@ -111,6 +182,10 @@ export class Harbor extends Carrier implements Hosting, Cataloguing, Resolving {
     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 {
       this.#registry = new Registry(this.#kit, modules);
@@ -153,9 +228,49 @@ export class Harbor extends Carrier implements Hosting, Cataloguing, Resolving {
     return this.box.partition.kept();
   }
 
-  // Hosting: the terrain's carrier takes a route, or does not dial.
-  override route(pk: string, at: string | null): boolean {
-    return this.terrain.carrier.route(pk, at);
+  // 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 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> {
@@ -167,12 +282,26 @@ export class Harbor extends Carrier implements Hosting, Cataloguing, Resolving {
       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

@@ -2,9 +2,12 @@
 // 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 Hosted, type Hosting } from './dock.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 { Package } from './package.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';

package/src/harbor/package.ts

@@ -17,6 +17,17 @@ import { concat, decrypt, encrypt, hex, hkdf, utf8 } from '../crypto/index.ts';
 import type { Entropy, Memory, Rows } from '../contract/index.ts';
 import { HEAD_ROW } from '../ward/index.ts';
 
+// Every place of one memory, written into another, and the places
+// carried. The bytes are the package's own, sealed under a seed neither
+// memory holds, so a harbor opened on the second memory under that seed
+// stands what the first one stood. A place the second memory already
+// holds is written over.
+export const copyPackage = async (from: Memory, to: Memory): Promise<string[]> => {
+  const places = await from.places();
+  for (const place of places) await to.write(place, await from.read(place));
+  return places;
+};
+
 const NONCE = 12;
 const LABEL = utf8('nervur-package');
 
@@ -113,6 +124,11 @@ export class Package {
     return hkdf(this.#key, utf8(JSON.stringify(info)), length);
   }
 
+  // The place a ward's rows live in.
+  place(name: string): Promise<string> {
+    return this.derive(['place', name], 16).then(hex);
+  }
+
   // One ward's rows, as the package kept them.
   async rows(name: string): Promise<Rows> {
     const ward = new Ward(this, name, await this.derive(['seal', name], 32), hex(await this.derive(['place', name], 16)));

package/src/harbor/probe.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+// The ground probe: `Harbor.open()` with no terrain asks each ground an
+// entry knows whether it fits here, the one added last first, and opens on
+// the terrain the first that fits makes. The main entry adds a ground that
+// fits everywhere; an entry that names a platform adds its own.
+import type { Module } from '../contract/index.ts';
+import type { Terrain } from './terrain.ts';
+
+// What a probed harbor is told: the modules its code holds, where it keeps
+// itself, as its ground reads a place, and what the engine handed the
+// code, such as an edge's object state and environment.
+export type Probing = { readonly modules?: readonly Module[]; readonly where?: string; readonly given?: unknown };
+
+export type GroundProbe = {
+  readonly name: string;
+  fits(probing: Probing): boolean;
+  terrain(probing: Probing): Terrain;
+};
+
+const known: GroundProbe[] = [];
+
+// A ground this process can stand on, known once by its name.
+export const addGround = (probe: GroundProbe): void => {
+  if (!known.some((k) => k.name === probe.name)) known.push(probe);
+};
+
+// The grounds known, in the order they are tried.
+export const grounds = (): string[] => known.map((k) => k.name).reverse();
+
+// The terrain of the first ground that fits, and its name.
+export const probeGround = (probing: Probing, probes: readonly GroundProbe[] = known): { ground: string; terrain: Terrain } => {
+  for (const probe of [...probes].reverse()) if (probe.fits(probing)) return { ground: probe.name, terrain: probe.terrain(probing) };
+  throw new Error('no ground fits here');
+};

package/src/harbor/registry.ts

@@ -62,6 +62,17 @@ export class Registry implements Catalogue {
     }
   }
 
+  // Why a registry of these modules would be refused, or null.
+  static refusal(kit: readonly BeingClass[], modules: readonly Module[]): string | null {
+    try {
+      const registry = new Registry(kit, modules);
+      void registry;
+      return null;
+    } catch (e) {
+      return (e as Error).message;
+    }
+  }
+
   classOf(kind: string): BeingClass | undefined {
     return this.#classes.get(kind);
   }