nervur 0.19.2 → 0.20.1

package/dist/folder/index.js

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+// A harbor on a disk, for local proof: `nervur/folder`, an entry that
+// names a platform.
+//
+//   <root>/seed              the harbor's seed, as hex
+//   <root>/<place>/<entry>   one sealed entry of the harbor's memory
+//
+// 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.
+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 named = (name) => {
+    if (!isHex(name) || name === '')
+        throw new Error(`${name} is not a name the kit chose`);
+    return name;
+};
+const writeWhole = async (path, bytes) => {
+    await writeFile(`${path}.next`, bytes, { mode: 0o600 });
+    await rename(`${path}.next`, path);
+};
+export class FolderMemory extends Memory {
+    root;
+    #line = Promise.resolve();
+    constructor(root) {
+        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.
+    async read(place) {
+        const dir = join(this.root, named(place));
+        const out = new Map();
+        const files = await readdir(dir, { withFileTypes: true }).catch((e) => (missing(e) ? [] : Promise.reject(e)));
+        for (const file of files) {
+            if (!file.isFile() || !isHex(file.name) || file.name === '')
+                continue;
+            out.set(file.name, new Uint8Array(await readFile(join(dir, file.name))));
+        }
+        return out;
+    }
+    // One keep at a time, each entry in the order given.
+    async write(place, entries) {
+        const dir = join(this.root, named(place));
+        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);
+            }
+        });
+        this.#line = kept.catch(() => undefined);
+        await kept;
+    }
+}
+export class FolderCustody extends Custody {
+    root;
+    #entropy;
+    constructor(root, entropy) {
+        super();
+        this.root = root;
+        this.#entropy = entropy;
+    }
+    // The seed the folder holds, or a drawn one written there the first time.
+    async seed() {
+        const path = join(this.root, 'seed');
+        const kept = await readFile(path, 'utf8').catch((e) => (missing(e) ? undefined : Promise.reject(e)));
+        if (kept !== undefined) {
+            const text = kept.trim();
+            if (!isHex(text, 32))
+                throw new Error(`${path} is not a seed`);
+            return unhex(text);
+        }
+        const seed = this.#entropy.draw(32);
+        await mkdir(this.root, { recursive: true, mode: 0o700 });
+        await writeFile(path, `${hex(seed)}\n`, { mode: 0o600, flag: 'wx' });
+        return seed;
+    }
+}

package/dist/harbor/catalogue.d.ts

@@ -0,0 +1,25 @@
+import { Faculty, type AskSpec, type BeingClass, type JsonObject, type Stance } from '../being/index.ts';
+import type { Loaded } from '../contract/index.ts';
+export declare const CATALOGUE = "catalogue";
+export type ModuleRow = {
+    version: string;
+    from: string;
+};
+export interface Cataloguing {
+    load(from: string): Promise<Loaded | null>;
+    run(modules: readonly Loaded[]): string | null;
+    stands(kinds: readonly string[]): boolean;
+    kindsOf(module: string): string[];
+}
+export declare class Catalogue extends Faculty {
+    #private;
+    static readonly kind: string;
+    static cells: JsonObject;
+    static asks: Record<string, AskSpec>;
+    constructor(stance: Stance, harbor: Cataloguing);
+    wake(): Promise<void>;
+    add(args: JsonObject): Promise<JsonObject>;
+    remove(args: JsonObject): JsonObject;
+    modules(): JsonObject;
+}
+export declare const catalogueFor: (harbor: Cataloguing) => BeingClass;

package/dist/harbor/catalogue.js

@@ -0,0 +1,93 @@
+// 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, loads every module she names, and refuses to stand when one is
+// missing.
+//
+//   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
+//
+// She is the kit's, of kind `org.nervur.catalogue`, and answers the root
+// and an owner alone.
+import { Faculty } from '../being/index.js';
+import { ownerAsk } from '../ward/index.js';
+export const CATALOGUE = 'catalogue';
+const text = (v) => typeof v === 'string';
+export class Catalogue extends Faculty {
+    static kind = 'org.nervur.catalogue';
+    static cells = { modules: {} };
+    static asks = {
+        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'),
+    };
+    #harbor;
+    #running = new Map();
+    constructor(stance, harbor) {
+        super(stance);
+        this.#harbor = harbor;
+    }
+    get #rows() {
+        return this.cells.modules;
+    }
+    // Every module her cells name, loaded and run, or a throw naming the one
+    // that cannot be.
+    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 refused = this.#harbor.run([...this.#running.values()]);
+        if (refused !== null)
+            throw new Error(refused);
+    }
+    async add(args) {
+        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.#rows[loaded.module] = { version: loaded.version, from: loaded.from };
+        return { added: loaded.module, version: loaded.version };
+    }
+    remove(args) {
+        const module = args.module;
+        if (!text(module) || !this.#running.has(module))
+            return { error: 'no such module' };
+        if (this.#harbor.stands(this.#harbor.kindsOf(module)))
+            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);
+        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 };
+        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) => class extends Catalogue {
+    static kind = Catalogue.kind;
+    constructor(stance) {
+        super(stance, harbor);
+    }
+};

package/dist/harbor/dock.d.ts

@@ -0,0 +1,29 @@
+import { type AskSpec, 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;
+    keep(): Promise<boolean>;
+}
+export type Hosted = {
+    ward: string;
+    seed: string;
+};
+export declare const BOX = "box";
+export declare class Dock extends WardBeing implements Lender {
+    #private;
+    static readonly kind: string;
+    static cells: JsonObject;
+    static asks: Record<string, AskSpec>;
+    constructor(stance: WardBeingStance, hosting: Hosting);
+    get hosted(): Hosted[];
+    get routes(): Record<string, string>;
+    route(args: JsonObject): JsonObject;
+    standCatalogue(): Promise<void>;
+    open(args: JsonObject): Promise<JsonObject>;
+    host(args: JsonObject): Promise<JsonObject>;
+    lend(args: JsonObject): Promise<JsonObject>;
+    retract(args: JsonObject): Promise<JsonObject>;
+    offer(contract: string): Promise<Invitation | null>;
+    withdraw(contract: string, heir: string): Promise<void>;
+}

package/dist/harbor/dock.js

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: Apache-2.0
+// The dock: the box ward's ward-being. Beside the root's asks of every ward,
+// she opens faculties, hosts wards, and lends each contract a faculty
+// fulfils to the wards she hosts.
+//
+//   open    { key, class }      a faculty stands in the box ward, and the
+//                               dock holds a standing on her under her key
+//   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
+//   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 } from '../being/index.js';
+import { CATALOGUE } from './catalogue.js';
+import { readInvitation } from '../quo/index.js';
+import { ownerAsk, WardBeing } from '../ward/index.js';
+export const BOX = 'box';
+const text = (v) => typeof v === 'string';
+const hosted = (_, notes) => notes?.hosted === true;
+export class Dock extends WardBeing {
+    static kind = 'org.nervur.dock';
+    static cells = { hosted: [], routes: {} };
+    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'] }),
+        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 },
+    };
+    #hosting;
+    constructor(stance, hosting) {
+        super(stance);
+        this.#hosting = hosting;
+    }
+    get hosted() {
+        return this.cells.hosted.map(({ ward, seed }) => ({ ward, seed }));
+    }
+    get routes() {
+        return { ...this.cells.routes };
+    }
+    route(args) {
+        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;
+        if (at === null)
+            delete routes[ward];
+        else
+            routes[ward] = at;
+        return { routed: ward };
+    }
+    // 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');
+    }
+    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)))
+            return { error: 'no such faculty' };
+        const opened = await this.stance.boot(args.class, args.key, args.key);
+        return opened === null ? { error: 'not opened' } : { opened };
+    }
+    async host(args) {
+        const name = args.ward;
+        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' };
+        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.push({ ward: name, seed });
+        return { hosted: name };
+    }
+    async lend(args) {
+        if (!text(args.contract))
+            return { error: 'contract is text' };
+        const invitation = await this.offer(args.contract);
+        return invitation ? { invitation } : { error: 'nothing lent' };
+    }
+    async retract(args) {
+        if (!text(args.contract) || !text(args.heir))
+            return { error: 'contract and heir are text' };
+        await this.withdraw(args.contract, args.heir);
+        return { retracted: args.heir };
+    }
+    // Lender: the first standing faculty that fulfils the contract offers.
+    async offer(contract) {
+        for (const key of this.#fulfilling(contract)) {
+            const out = await this.stance.standings.get(key)?.ask('offer');
+            const invitation = readInvitation(out?.invitation);
+            if (invitation)
+                return invitation;
+        }
+        return null;
+    }
+    async withdraw(contract, heir) {
+        for (const key of this.#fulfilling(contract))
+            await this.stance.standings.get(key)?.ask('retract', { heir });
+    }
+    #fulfilling(contract) {
+        const beings = this.steward.beings();
+        return this.stance.standings.ids().filter((key) => {
+            const being = beings[key];
+            const C = being && !being.absent ? this.steward.classOf(being.class) : undefined;
+            return Faculty.fulfils(C) && Faculty.contracts(C).includes(contract);
+        });
+    }
+}

package/dist/harbor/harbor.d.ts

@@ -0,0 +1,31 @@
+import type { Answer, BeingClass, Invitation, JsonObject } from '../being/index.ts';
+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 { Registry } from './registry.ts';
+import type { 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>;
+    get box(): Ward;
+    get dock(): Dock;
+    get catalogue(): Catalogue;
+    get registry(): Registry;
+    ward(name: string): Ward | undefined;
+    get names(): string[];
+    root(method?: string, args?: JsonObject): Promise<Answer>;
+    holds(pk: string): boolean;
+    arrive(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+    carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+    classOf(kind: string): BeingClass | undefined;
+    load(from: string): Promise<Loaded | 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;
+}

package/dist/harbor/harbor.js

@@ -0,0 +1,146 @@
+import { Carrier } from '../contract/index.js';
+import { hex, isHex, unhex } from '../crypto/index.js';
+import { WardKey } from '../quo/index.js';
+import { DOCK, Pilot, Ward } from '../ward/index.js';
+import { Catalogue, CATALOGUE, catalogueFor } from './catalogue.js';
+import { BOX, Dock } from './dock.js';
+import { Package } from './package.js';
+import { Registry } from './registry.js';
+export class Harbor extends Carrier {
+    terrain;
+    #package;
+    #wards = new Map();
+    #kit;
+    #registry;
+    constructor(terrain, pack) {
+        super();
+        this.terrain = terrain;
+        this.#package = pack;
+        this.#kit = [catalogueFor(this), Pilot];
+        this.#registry = new Registry(this.#kit, []);
+    }
+    static async open(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))
+            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));
+        return harbor;
+    }
+    get box() {
+        return this.#wards.get(BOX);
+    }
+    get dock() {
+        return this.box.wardBeing;
+    }
+    get catalogue() {
+        return this.box.being(CATALOGUE);
+    }
+    get registry() {
+        return this.#registry;
+    }
+    ward(name) {
+        return this.#wards.get(name);
+    }
+    get names() {
+        return [...this.#wards.keys()].filter((name) => name !== BOX);
+    }
+    // The unsealed ask on the box ward: what a command line carries.
+    root(method, args) {
+        return this.box.root(method, args);
+    }
+    holds(pk) {
+        return this.#door(pk) !== undefined;
+    }
+    // Bytes for one of this harbor's doors, or nothing.
+    async arrive(pk, bytes) {
+        const ward = this.#door(pk);
+        return ward ? (await ward.door.arrive(bytes)).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);
+    }
+    // Resolving: a kind, by the registry the catalogue runs.
+    classOf(kind) {
+        return this.#registry.classOf(kind);
+    }
+    // Cataloguing: code through the terrain, and the modules run.
+    load(from) {
+        return this.terrain.loader.load(from);
+    }
+    run(modules) {
+        try {
+            this.#registry = new Registry(this.#kit, modules);
+        }
+        catch (e) {
+            return e.message;
+        }
+        for (const ward of this.#wards.values())
+            ward.bearAnew();
+        return null;
+    }
+    stands(kinds) {
+        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) {
+        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, invitation, seed) {
+        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 null;
+        }
+        if (this.#wards.get(name).wardBeing.stance.standings.get(DOCK))
+            return hex(bytes);
+        this.#wards.delete(name);
+        return null;
+    }
+    keep() {
+        return this.box.partition.kept();
+    }
+    // Hosting: the terrain's carrier takes a route, or does not dial.
+    route(pk, at) {
+        return this.terrain.carrier.route(pk, at);
+    }
+    async #unpack(name, seed, dock, root) {
+        const { entropy, clock } = this.terrain;
+        const ward = await Ward.unpack({
+            seed,
+            memory: await this.#package.rows(name),
+            catalogue: this,
+            entropy,
+            clock,
+            carrier: this,
+            ...(dock ? { dock } : {}),
+            ...(root ? { root } : {}),
+        });
+        this.#wards.set(name, ward);
+    }
+    #door(pk) {
+        for (const ward of this.#wards.values())
+            if (ward.pk === pk)
+                return ward;
+        return undefined;
+    }
+}

package/dist/harbor/index.d.ts

@@ -1,10 +1,7 @@
-export { MemoryHarbor, type Booted, type WardFactory } from './memory.ts';
-export { Harbor, DEFAULT_CODE, type Hosted, type Bound, type Loader } from './core.ts';
-export { dial, type Dialer } from './dial.ts';
-export { MemoryStore, values, rowsOf, type Store, type Kept, type WardRecord } from './store.ts';
-export { HEAD, fromRows, rowsIn } from '../ward/partition.ts';
-export { request, Socket, SUITE, REFUSED, type Reach, type Carry, type Line, type Announce } from './reach.ts';
-export type { Ground, WardPointers, Memory } from '../ward/ground.ts';
-export { BOX, OFFER, RETRACT, volatile } from '../ward/ground.ts';
-export { Box, BOX_SEED, BOX_ASKS, stand, hold, offerTo, roll } from './box.ts';
-export { maker, entropy, learnPk } from '../ward/ground.ts';
+export { Catalogue, CATALOGUE, type Cataloguing, type ModuleRow } from './catalogue.ts';
+export { BOX, Dock, type Hosted, type Hosting } from './dock.ts';
+export { Harbor } from './harbor.ts';
+export { Package } from './package.ts';
+export { readRootRequest, rootLine, type RootRequest } from './root-line.ts';
+export { Registry } from './registry.ts';
+export { Terrain } from './terrain.ts';

package/dist/harbor/index.js

@@ -1,19 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
-// nervur/harbor — the Ground contract and the harbors. The only
-// place in the package that may know a wire, and it knows one on the
-// standard surface alone: fetch and WebSocket. MemoryHarbor knows none: it
-// is one process talking to itself, where every ward assertion is made.
-export { MemoryHarbor } from './memory.js';
-export { Harbor, DEFAULT_CODE } from './core.js';
-export { dial } from './dial.js';
-export { MemoryStore, values, rowsOf } from './store.js';
-// What a store keeping a ward in rows needs: the name of the row that is not
-// a being, and the partition back from the rows it was cut into.
-export { HEAD, fromRows, rowsIn } from '../ward/partition.js';
-export { request, Socket, SUITE, REFUSED } from './reach.js';
-export { BOX, OFFER, RETRACT, volatile } from '../ward/ground.js';
-// The box as one being, and the acts a harbor runs to stand it.
-export { Box, BOX_SEED, BOX_ASKS, stand, hold, offerTo, roll } from './box.js';
-// What a harbor builds a ground out of. Convenience, never contract: a kit
-// writing its own harbor may write these three again.
-export { maker, entropy, learnPk } from '../ward/ground.js';
+// The onion: a terrain, the package, the dock, the catalogue and its
+// registry, and the harbor.
+export { Catalogue, CATALOGUE } from './catalogue.js';
+export { BOX, Dock } from './dock.js';
+export { Harbor } from './harbor.js';
+export { Package } from './package.js';
+export { readRootRequest, rootLine } from './root-line.js';
+export { Registry } from './registry.js';
+export { Terrain } from './terrain.js';

package/dist/harbor/package.d.ts

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