nervur 0.20.1 → 0.20.2

package/dist/folder/index.d.ts

@@ -1,10 +1,14 @@
 import { Custody, Memory, type Entropy } from '../contract/index.ts';
+export type Keep = Record<string, string | null>;
 export declare class FolderMemory extends Memory {
     #private;
     readonly root: string;
     constructor(root: string);
     read(place: string): Promise<Map<string, Uint8Array>>;
     write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void>;
+    places(): Promise<string[]>;
+    forget(place: string): Promise<void>;
+    protected apply(dir: string, keep?: Keep): Promise<void>;
 }
 export declare class FolderCustody extends Custody {
     #private;

package/dist/folder/index.js

@@ -4,17 +4,26 @@
 //
 //   <root>/seed              the harbor's seed, as hex
 //   <root>/<place>/<entry>   one sealed entry of the harbor's memory
+//   <root>/<place>/keep      a keep of that place, until it is applied
 //
 // Places and entries are the hex names the kit chose, so no name reaches
 // outside its folder, and the disk shows no ward's name. A file is written
-// whole, beside itself and then renamed over, so a crash leaves the last
-// kept copy. The seed is a plain file: custody that seals it is a
-// terrain's, in the dock.
+// whole, beside itself and then renamed over.
+//
+// A keep is whole, by its own file: the whole keep is written under `keep`
+// and renamed over, then its entries are written and removed one by one,
+// then `keep` goes. A read applies a `keep` it finds first, and the same
+// bytes written twice leave the same place, so a keep that a crash cut
+// short finishes at the next read. A place read before its `keep` landed
+// has none of it. `keep` is no hex name, so it is never an entry.
+//
+// The seed is a plain file: custody that seals it is a terrain's.
 import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { hex, isHex, unhex } from '../crypto/index.js';
 import { Custody, Memory } from '../contract/index.js';
 const missing = (e) => e.code === 'ENOENT';
+const KEEP = 'keep';
 const named = (name) => {
     if (!isHex(name) || name === '')
         throw new Error(`${name} is not a name the kit chose`);
@@ -31,10 +40,12 @@ export class FolderMemory extends Memory {
         super();
         this.root = root;
     }
-    // The entries as the disk holds them now. A file that is not an entry,
-    // one still being written among them, is not read.
+    // The entries as the disk holds them now, a keep left unapplied first.
+    // A file that is not an entry, one still being written among them, is
+    // not read.
     async read(place) {
         const dir = join(this.root, named(place));
+        await this.apply(dir);
         const out = new Map();
         const files = await readdir(dir, { withFileTypes: true }).catch((e) => (missing(e) ? [] : Promise.reject(e)));
         for (const file of files) {
@@ -44,22 +55,46 @@ export class FolderMemory extends Memory {
         }
         return out;
     }
-    // One keep at a time, each entry in the order given.
+    // One keep at a time, written whole under `keep` before any entry moves.
     async write(place, entries) {
         const dir = join(this.root, named(place));
+        const keep = {};
+        for (const [name, bytes] of entries)
+            keep[named(name)] = bytes === null ? null : hex(bytes);
         const kept = this.#line.then(async () => {
             await mkdir(dir, { recursive: true, mode: 0o700 });
-            for (const [name, bytes] of entries) {
-                const path = join(dir, named(name));
-                if (bytes === null)
-                    await rm(path, { force: true });
-                else
-                    await writeWhole(path, bytes);
-            }
+            await writeWhole(join(dir, KEEP), JSON.stringify(keep));
+            await this.apply(dir, keep);
         });
         this.#line = kept.catch(() => undefined);
         await kept;
     }
+    // Every folder of the root that is a place.
+    async places() {
+        const files = await readdir(this.root, { withFileTypes: true }).catch((e) => (missing(e) ? [] : Promise.reject(e)));
+        return files.filter((f) => f.isDirectory() && isHex(f.name) && f.name !== '').map((f) => f.name);
+    }
+    forget(place) {
+        return rm(join(this.root, named(place)), { recursive: true, force: true });
+    }
+    // The keep a folder holds, applied and then gone. Writing the same bytes
+    // again leaves the same place, so applying twice is applying once.
+    async apply(dir, keep) {
+        const found = keep ?? (await readFile(join(dir, KEEP), 'utf8').then((text) => JSON.parse(text), () => null));
+        if (found === null)
+            return;
+        for (const [name, written] of Object.entries(found)) {
+            const path = join(dir, named(name));
+            if (written === null)
+                await rm(path, { force: true });
+            else
+                await writeWhole(path, unhex(written));
+        }
+        await rm(join(dir, KEEP), { force: true });
+        const left = await readdir(dir).catch((e) => (missing(e) ? [] : Promise.reject(e)));
+        if (left.length === 0)
+            await rm(dir, { recursive: true, force: true });
+    }
 }
 export class FolderCustody extends Custody {
     root;
@@ -70,6 +105,7 @@ export class FolderCustody extends Custody {
         this.#entropy = entropy;
     }
     // The seed the folder holds, or a drawn one written there the first time.
+    // Two first asks at once keep the one written first.
     async seed() {
         const path = join(this.root, 'seed');
         const kept = await readFile(path, 'utf8').catch((e) => (missing(e) ? undefined : Promise.reject(e)));
@@ -81,7 +117,14 @@ export class FolderCustody extends Custody {
         }
         const seed = this.#entropy.draw(32);
         await mkdir(this.root, { recursive: true, mode: 0o700 });
-        await writeFile(path, `${hex(seed)}\n`, { mode: 0o600, flag: 'wx' });
+        try {
+            await writeFile(path, `${hex(seed)}\n`, { mode: 0o600, flag: 'wx' });
+        }
+        catch (e) {
+            if (e.code === 'EEXIST')
+                return this.seed();
+            throw e;
+        }
         return seed;
     }
 }

package/dist/harbor/carrying.d.ts

@@ -0,0 +1,17 @@
+import { Faculty, type BeingClass } from '../being/index.ts';
+export interface Ground {
+    arrive(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+}
+export type GroundFaculty = (ground: Ground) => BeingClass;
+export declare const UNDIALED: unique symbol;
+export type Dialed = Uint8Array | null | typeof UNDIALED;
+export declare abstract class CarrierFaculty extends Faculty {
+    static readonly kind: string;
+    abstract accepts(address: string): boolean;
+    abstract dial(address: string, pk: string, bytes: Uint8Array): Promise<Dialed>;
+    listening(): string[];
+    relays(_pk: string): boolean;
+    relay(_pk: string, _bytes: Uint8Array): Promise<Uint8Array | null>;
+    awake(): Promise<void>;
+    sleep(): Promise<void>;
+}

package/dist/harbor/carrying.js

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+// A carrier is a faculty. It speaks the schemes of the addresses it dials,
+// dials an address when the harbor carries a box there, and listens where
+// its cells say, handing each box it hears to the harbor. The harbor keeps
+// every route and walks it in order, handing each address to the carrier
+// that speaks its scheme.
+//
+// A ground ships its carriers as classes the terrain names, each made for
+// one harbor, so the class holds the harbor it hands boxes to. They are
+// the kit's, of kinds under `org.nervur.`, and the dock opens them as
+// faculties, at genesis where the terrain says, and on the root's `open`.
+import { Faculty } from '../being/index.js';
+// Beside a reply and nothing, a dial answers `undialed` when the address
+// could not be reached at all, so the harbor tries the next one. A box a
+// line took may have been heard, so after it no other address is tried.
+export const UNDIALED = Symbol('undialed');
+export class CarrierFaculty extends Faculty {
+    static kind = 'org.nervur.carrier';
+    // The addresses it listens at now.
+    listening() {
+        return [];
+    }
+    // Whether it answers for a ward pk no door of this harbor holds, as a
+    // relay does, and its answer.
+    relays(_pk) {
+        return false;
+    }
+    relay(_pk, _bytes) {
+        return Promise.resolve(null);
+    }
+    // Once the harbor has unpacked, and once before it closes.
+    awake() {
+        return Promise.resolve();
+    }
+    sleep() {
+        return Promise.resolve();
+    }
+}

package/dist/harbor/catalogue.d.ts

@@ -4,9 +4,11 @@ export declare const CATALOGUE = "catalogue";
 export type ModuleRow = {
     version: string;
     from: string;
+    kinds: string[];
 };
 export interface Cataloguing {
     load(from: string): Promise<Loaded | null>;
+    check(modules: readonly Loaded[]): string | null;
     run(modules: readonly Loaded[]): string | null;
     stands(kinds: readonly string[]): boolean;
     kindsOf(module: string): string[];

package/dist/harbor/catalogue.js

@@ -2,13 +2,16 @@
 // 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, loads every module she names, and refuses to stand when one is
-// missing.
+// 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, run no more
-//   modules               what she names, each with the version running
+//   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.
@@ -26,6 +29,7 @@ export class Catalogue extends Faculty {
     };
     #harbor;
     #running = new Map();
+    #failed = new Map();
     constructor(stance, harbor) {
         super(stance);
         this.#harbor = harbor;
@@ -33,20 +37,19 @@ export class Catalogue extends Faculty {
     get #rows() {
         return this.cells.modules;
     }
-    // Every module her cells name, loaded and run, or a throw naming the one
-    // that cannot be.
+    // 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() {
         for (const [module, row] of Object.entries(this.#rows)) {
-            const loaded = await this.#harbor.load(row.from);
-            if (loaded === null)
-                throw new Error(`module ${module} is not found at ${row.from}`);
-            if (loaded.module !== module)
-                throw new Error(`${row.from} is module ${loaded.module}, not ${module}`);
-            this.#running.set(module, loaded);
+            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);
         }
-        const refused = this.#harbor.run([...this.#running.values()]);
-        if (refused !== null)
-            throw new Error(refused);
+        this.#harbor.run([...this.#running.values()]);
     }
     async add(args) {
         if (!text(args.from))
@@ -60,26 +63,31 @@ export class Catalogue extends Faculty {
         if (refused !== null)
             return { error: refused };
         this.#running.set(loaded.module, loaded);
-        this.#rows[loaded.module] = { version: loaded.version, from: loaded.from };
+        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) {
         const module = args.module;
-        if (!text(module) || !this.#running.has(module))
+        if (!text(module) || !Object.hasOwn(this.#rows, module))
             return { error: 'no such module' };
-        if (this.#harbor.stands(this.#harbor.kindsOf(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() {
         const out = {};
-        for (const [module, row] of Object.entries(this.#rows))
-            out[module] = { version: row.version, running: this.#running.get(module)?.version ?? null, from: row.from };
+        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;
     }
 }

package/dist/harbor/dock.d.ts

@@ -1,14 +1,23 @@
-import { type AskSpec, type Invitation, type JsonObject } from '../being/index.ts';
+import { type Asker, type AskSpec, type Blueprint, type Invitation, type JsonObject } from '../being/index.ts';
 import { WardBeing, type Lender, type WardBeingStance } from '../ward/index.ts';
 export interface Hosting {
     host(name: string, invitation: Invitation, seed?: string): Promise<string | null>;
-    route(pk: string, at: string | null): boolean;
+    route(pk: string, at: readonly string[] | null): boolean;
     keep(): Promise<boolean>;
+    failures(): Failures;
+    sweep(): Promise<string[]>;
+    grounds(kind: string): boolean;
+    awaken(key: string): Promise<void>;
+    lull(key: string): Promise<void>;
 }
 export type Hosted = {
     ward: string;
     seed: string;
 };
+export type Failures = {
+    wards: Record<string, string>;
+    routes: Record<string, string>;
+};
 export declare const BOX = "box";
 export declare class Dock extends WardBeing implements Lender {
     #private;
@@ -16,11 +25,21 @@ export declare class Dock extends WardBeing implements Lender {
     static cells: JsonObject;
     static asks: Record<string, AskSpec>;
     constructor(stance: WardBeingStance, hosting: Hosting);
+    describe(asker: Asker): Blueprint;
     get hosted(): Hosted[];
-    get routes(): Record<string, string>;
+    get routes(): Record<string, string[]>;
+    get addresses(): string[];
     route(args: JsonObject): JsonObject;
+    reach(args: JsonObject): JsonObject;
+    learn(ward: string, at: readonly string[]): Promise<void>;
     standCatalogue(): Promise<void>;
+    unboot(args: JsonObject): Promise<JsonObject>;
+    standCarriers(opens: readonly {
+        key: string;
+        kind: string;
+    }[]): Promise<void>;
     open(args: JsonObject): Promise<JsonObject>;
+    sweep(): Promise<JsonObject>;
     host(args: JsonObject): Promise<JsonObject>;
     lend(args: JsonObject): Promise<JsonObject>;
     retract(args: JsonObject): Promise<JsonObject>;

package/dist/harbor/dock.js

@@ -11,24 +11,34 @@
 //   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
+//   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 } from '../being/index.js';
 import { CATALOGUE } from './catalogue.js';
-import { readInvitation } from '../quo/index.js';
-import { ownerAsk, WardBeing } from '../ward/index.js';
+import { readAt, readInvitation } from '../quo/index.js';
+import { ownerAsk, pilots, rootAsk, WardBeing } from '../ward/index.js';
 export const BOX = 'box';
 const text = (v) => typeof v === 'string';
+// A list of addresses, each a URI with a scheme, and at least one.
+const addresses = (v) => Array.isArray(v) && v.length > 0 && readAt(v).length === v.length;
 const hosted = (_, notes) => notes?.hosted === true;
 export class Dock extends WardBeing {
     static kind = 'org.nervur.dock';
-    static cells = { hosted: [], routes: {} };
+    static cells = { hosted: [], routes: {}, reach: [] };
     static asks = {
         ...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 },
     };
@@ -37,36 +47,82 @@ export class Dock extends WardBeing {
         super(stance);
         this.#hosting = hosting;
     }
+    // The census adds what did not stand, for whoever pilots.
+    describe(asker) {
+        const blueprint = super.describe(asker);
+        if (pilots(asker, this.notes(asker)))
+            blueprint.notes.failed = this.#hosting.failures();
+        return blueprint;
+    }
     get hosted() {
         return this.cells.hosted.map(({ ward, seed }) => ({ ward, seed }));
     }
     get routes() {
-        return { ...this.cells.routes };
+        return Object.fromEntries(Object.entries(this.cells.routes).map(([pk, at]) => [pk, [...at]]));
+    }
+    // Where this harbor is reached, in the order a caller tries it.
+    get addresses() {
+        return [...this.cells.reach];
     }
     route(args) {
-        const { ward, at } = args;
-        if (!text(ward) || (at !== null && !text(at)) || !this.#hosting.route(ward, at))
+        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;
         if (at === null)
             delete routes[ward];
         else
-            routes[ward] = at;
+            routes[ward] = [...at];
         return { routed: ward };
     }
+    reach(args) {
+        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, at) {
+        const routes = this.cells.routes;
+        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() {
         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.
+    async unboot(args) {
+        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) {
+        for (const { key, kind } of opens)
+            await this.open({ key, class: kind });
+        await this.#hosting.keep();
+    }
     async open(args) {
         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)))
+        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() {
+        return { swept: await this.#hosting.sweep() };
     }
     async host(args) {
         const name = args.ward;

package/dist/harbor/harbor.d.ts

@@ -2,14 +2,18 @@ import type { Answer, BeingClass, Invitation, JsonObject } from '../being/index.
 import { Carrier, type Loaded } from '../contract/index.ts';
 import { Ward, type Catalogue as Resolving } from '../ward/index.ts';
 import { Catalogue, type Cataloguing } from './catalogue.ts';
-import { Dock, type Hosting } from './dock.ts';
+import { CarrierFaculty } from './carrying.ts';
+import { Dock, type Failures, type Hosting } from './dock.ts';
 import { Registry } from './registry.ts';
-import type { Terrain } from './terrain.ts';
+import { type Probing } from './probe.ts';
+import { Terrain } from './terrain.ts';
 export declare class Harbor extends Carrier implements Hosting, Cataloguing, Resolving {
     #private;
     readonly terrain: Terrain;
     private constructor();
-    static open(terrain: Terrain): Promise<Harbor>;
+    static open(from?: Terrain | Probing): Promise<Harbor>;
+    sweep(): Promise<string[]>;
+    failures(): Failures;
     get box(): Ward;
     get dock(): Dock;
     get catalogue(): Catalogue;
@@ -22,10 +26,16 @@ export declare class Harbor extends Carrier implements Hosting, Cataloguing, Res
     carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
     classOf(kind: string): BeingClass | undefined;
     load(from: string): Promise<Loaded | null>;
+    check(modules: readonly Loaded[]): string | null;
     run(modules: readonly Loaded[]): string | null;
     stands(kinds: readonly string[]): boolean;
     kindsOf(module: string): string[];
     host(name: string, invitation: Invitation, seed?: string): Promise<string | null>;
     keep(): Promise<boolean>;
-    route(pk: string, at: string | null): boolean;
+    route(pk: string, at: readonly string[] | null): boolean;
+    grounds(kind: string): boolean;
+    awaken(key: string): Promise<void>;
+    lull(key: string): Promise<void>;
+    get carriers(): CarrierFaculty[];
+    close(): Promise<void>;
 }