nervur 0.20.1 → 0.20.2

package/dist/harbor/harbor.js

@@ -1,37 +1,96 @@
 import { Carrier } from '../contract/index.js';
 import { hex, isHex, unhex } from '../crypto/index.js';
-import { WardKey } from '../quo/index.js';
+import { unspecified, WardKey } from '../quo/index.js';
 import { DOCK, Pilot, Ward } from '../ward/index.js';
 import { Catalogue, CATALOGUE, catalogueFor } from './catalogue.js';
+import { CarrierFaculty, UNDIALED } from './carrying.js';
 import { BOX, Dock } from './dock.js';
 import { Package } from './package.js';
 import { Registry } from './registry.js';
+import { relayClient, relayFaculty } from './relay.js';
+import { probeGround } from './probe.js';
+import { Terrain } from './terrain.js';
 export class Harbor extends Carrier {
     terrain;
     #package;
     #wards = new Map();
     #kit;
+    #grounds;
     #registry;
+    #failed = { wards: {}, routes: {} };
     constructor(terrain, pack) {
         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) {
+    // 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 = {}) {
+        const terrain = from instanceof Terrain ? from : probeGround(from).terrain;
+        await terrain.claim();
+        let 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) {
         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))
+        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() {
+        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() {
+        return { wards: { ...this.#failed.wards }, routes: { ...this.#failed.routes } };
+    }
     get box() {
         return this.#wards.get(BOX);
     }
@@ -57,14 +116,30 @@ export class Harbor extends Carrier {
     holds(pk) {
         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, bytes) {
         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, bytes) {
-        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, bytes) {
+        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.
     classOf(kind) {
@@ -74,6 +149,9 @@ export class Harbor extends Carrier {
     load(from) {
         return this.terrain.loader.load(from);
     }
+    check(modules) {
+        return Registry.refusal(this.#kit, modules);
+    }
     run(modules) {
         try {
             this.#registry = new Registry(this.#kit, modules);
@@ -119,9 +197,46 @@ export class Harbor extends Carrier {
     keep() {
         return this.box.partition.kept();
     }
-    // Hosting: the terrain's carrier takes a route, or does not dial.
+    // Hosting: a route is taken where a carrier of this harbor dials one of
+    // its addresses; forgetting one always is.
     route(pk, at) {
-        return this.terrain.carrier.route(pk, at);
+        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) {
+        return this.#grounds.has(kind);
+    }
+    async awaken(key) {
+        const being = this.box.being(key);
+        if (being instanceof CarrierFaculty)
+            await being.awake();
+    }
+    async lull(key) {
+        const being = this.box.being(key);
+        if (being instanceof CarrierFaculty)
+            await being.sleep();
+    }
+    // The carrier faculties standing in the box ward.
+    get carriers() {
+        return Object.keys(this.box.partition.beings)
+            .map((key) => this.box.being(key))
+            .filter((being) => being instanceof CarrierFaculty);
+    }
+    // Every carrier asleep, the last opened first: nothing listens and no
+    // line stays open.
+    async close() {
+        for (const carrier of this.carriers.reverse())
+            await carrier.sleep();
+        await this.terrain.release();
+    }
+    #relaying(pk) {
+        return this.carriers.find((carrier) => carrier.relays(pk));
+    }
+    #dialable(at) {
+        return at.some((address) => this.carriers.some((carrier) => carrier.accepts(address)));
     }
     async #unpack(name, seed, dock, root) {
         const { entropy, clock } = this.terrain;
@@ -132,11 +247,25 @@ export class Harbor extends Carrier {
             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.
+    #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) {
         for (const ward of this.#wards.values())
             if (ward.pk === pk)

package/dist/harbor/index.d.ts

@@ -1,7 +1,10 @@
 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/dist/harbor/index.js

@@ -3,8 +3,11 @@
 // registry, and the harbor.
 export { Catalogue, CATALOGUE } from './catalogue.js';
 export { BOX, Dock } from './dock.js';
+export { CarrierFaculty, UNDIALED } from './carrying.js';
 export { Harbor } from './harbor.js';
-export { Package } from './package.js';
+export { copyPackage, Package } from './package.js';
 export { readRootRequest, rootLine } from './root-line.js';
+export { addGround, grounds, probeGround } from './probe.js';
 export { Registry } from './registry.js';
+export { Push, PUSH, RELAY, RELAY_CLIENT, RELAY_HOLD, RELAY_REST, RELAY_WAIT, RELAYED } from './relay.js';
 export { Terrain } from './terrain.js';

package/dist/harbor/package.d.ts

@@ -1,4 +1,5 @@
 import type { Entropy, Memory, Rows } from '../contract/index.ts';
+export declare const copyPackage: (from: Memory, to: Memory) => Promise<string[]>;
 export declare class Package {
     #private;
     readonly memory: Memory;
@@ -6,5 +7,6 @@ export declare class Package {
     private constructor();
     static open(memory: Memory, entropy: Entropy, seed: Uint8Array): Promise<Package>;
     derive(info: string[], length: number): Promise<Uint8Array>;
+    place(name: string): Promise<string>;
     rows(name: string): Promise<Rows>;
 }

package/dist/harbor/package.js

@@ -15,6 +15,17 @@
 // bytes the package did not seal.
 import { concat, decrypt, encrypt, hex, hkdf, 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
+// 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, to) => {
+    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');
 class PackageRows {
@@ -94,6 +105,10 @@ export class Package {
     derive(info, length) {
         return hkdf(this.#key, utf8(JSON.stringify(info)), length);
     }
+    // The place a ward's rows live in.
+    place(name) {
+        return this.derive(['place', name], 16).then(hex);
+    }
     // One ward's rows, as the package kept them.
     async rows(name) {
         const ward = new Ward(this, name, await this.derive(['seal', name], 32), hex(await this.derive(['place', name], 16)));

package/dist/harbor/probe.d.ts

@@ -0,0 +1,18 @@
+import type { Module } from '../contract/index.ts';
+import type { Terrain } from './terrain.ts';
+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;
+};
+export declare const addGround: (probe: GroundProbe) => void;
+export declare const grounds: () => string[];
+export declare const probeGround: (probing: Probing, probes?: readonly GroundProbe[]) => {
+    ground: string;
+    terrain: Terrain;
+};

package/dist/harbor/probe.js

@@ -0,0 +1,15 @@
+const known = [];
+// A ground this process can stand on, known once by its name.
+export const addGround = (probe) => {
+    if (!known.some((k) => k.name === probe.name))
+        known.push(probe);
+};
+// The grounds known, in the order they are tried.
+export const grounds = () => known.map((k) => k.name).reverse();
+// The terrain of the first ground that fits, and its name.
+export const probeGround = (probing, probes = known) => {
+    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/dist/harbor/registry.d.ts

@@ -4,6 +4,7 @@ import type { Catalogue } from '../ward/index.ts';
 export declare class Registry implements Catalogue {
     #private;
     constructor(kit: readonly BeingClass[], modules: readonly Module[]);
+    static refusal(kit: readonly BeingClass[], modules: readonly Module[]): string | null;
     classOf(kind: string): BeingClass | undefined;
     kindsOf(module: string): string[];
 }

package/dist/harbor/registry.js

@@ -68,6 +68,17 @@ export class Registry {
                 throw new Error(`kind ${kind} is a class and a contract`);
         }
     }
+    // Why a registry of these modules would be refused, or null.
+    static refusal(kit, modules) {
+        try {
+            const registry = new Registry(kit, modules);
+            void registry;
+            return null;
+        }
+        catch (e) {
+            return e.message;
+        }
+    }
     classOf(kind) {
         return this.#classes.get(kind);
     }

package/dist/harbor/relay.d.ts

@@ -0,0 +1,15 @@
+import { Faculty, type BeingClass } from '../being/index.ts';
+import type { Clock } from '../contract/index.ts';
+import { type Ground } from './carrying.ts';
+export declare const RELAY = "org.nervur.relay";
+export declare const RELAY_CLIENT = "org.nervur.relay-client";
+export declare const PUSH = "org.nervur.push";
+export declare const RELAY_WAIT = 30000;
+export declare const RELAY_HOLD = 20000;
+export declare const RELAY_REST = 1000;
+export declare const RELAYED = 262144;
+export declare abstract class Push extends Faculty {
+    static readonly kind: string;
+}
+export declare const relayFaculty: (clock: Clock) => BeingClass;
+export declare const relayClient: (ground: Ground, clock: Clock) => BeingClass;