nervur 0.21.4 → 0.22.0

package/dist/{harbor → core/harbor}/dock.d.ts

@@ -1,47 +1,56 @@
-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';
+import { type Asker, type AskSpec, type Blueprint, type Invitation, type JsonObject, type Stance } from '../being/index.ts';
+import { Ward, type Lender, type WardStance } from '../ward/index.ts';
 export interface Hosting {
-    host(name: string, invitation: Invitation, seed?: string, store?: string): Promise<string | null>;
+    host(name: string, invitation: Invitation, seed?: string, memory?: string, kind?: string, registry?: string): Promise<string | null>;
+    stand(hosted: Hosted): Promise<boolean>;
     move(name: string, seed: string, from: string | undefined, to: string | undefined): Promise<string | null>;
-    release(name: string, store: string | undefined): Promise<void>;
+    release(name: string, memory: string | undefined): Promise<void>;
     route(pk: string, at: readonly string[] | null): boolean;
+    reached(pk: string, at: readonly string[]): void;
     keep(): Promise<boolean>;
     failures(): Failures;
     readonly foreground: boolean;
     sweep(): Promise<string[]>;
-    grounds(kind: string): boolean;
     awaken(key: string): Promise<void>;
+    rouse(key: string): Promise<void>;
     lull(key: string): Promise<void>;
+    listening(): string[];
+    heard(): Promise<void>;
 }
 export type Hosted = {
     ward: string;
     seed: string;
-    store?: string;
+    memory?: string;
+    registry?: 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 {
+export type DockStance = WardStance & {
+    readonly ground: Hosting;
+};
+export declare const hostable: (C: unknown) => boolean;
+export declare abstract class Dock extends Ward implements Lender {
     #private;
     static readonly kind: string;
     static cells: JsonObject;
     static asks: Record<string, AskSpec>;
-    constructor(stance: WardBeingStance, hosting: Hosting);
+    constructor(stance: Stance);
+    stand(): Promise<JsonObject | undefined>;
     describe(asker: Asker): Blueprint;
+    heard(): Promise<JsonObject>;
     get hosted(): Hosted[];
     get routes(): Record<string, string[]>;
     get addresses(): string[];
     route(args: JsonObject): JsonObject;
     reach(args: JsonObject): JsonObject;
+    hold(args: JsonObject): Promise<JsonObject>;
     learn(ward: string, at: readonly string[]): Promise<void>;
-    standCatalogue(): Promise<void>;
+    become(args: JsonObject): JsonObject;
+    boot(): Promise<JsonObject>;
     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>;

package/dist/core/harbor/dock.js

@@ -0,0 +1,381 @@
+// SPDX-License-Identifier: Apache-2.0
+// The dock: the contract of the box ward's ward. 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. The core names no class of it:
+// the terrain hands the harbor the one that stands at genesis. She is born
+// of her stance alone, which carries her harbor as `ground`.
+//
+// She stands once the harbor has booted: its seed, its memory, the
+// catalogue and every registry the catalogue resolves stand, and her class
+// resolved through the registry her row names. The harbor hands her the
+// door and is done; from there everything is an ask. Her `stand` is the
+// second level, hers alone, asked by whoever holds the harbor or pilots
+// it: every other faculty of the box, each once the registry it names
+// stands, registries first, then memory faculties, then the rest; then
+// every hosted ward, her house unpacked and her ward stood. A being of a
+// hosted ward stands nowhere: she is born for the asks that reach her. It
+// answers what stood, or silence where everything already stands. A
+// faculty names its class and its registry, and keeps its cells in the box
+// ward. A hosted ward names its class, its registry and the memory that
+// keeps it.
+//
+//   stand                       every faculty and hosted ward that does
+//                               not stand yet, stood
+//   open    { key, class,       a faculty stands in the box ward, her class
+//             registry? }       resolved through the registry faculty named
+//                               or the catalogue, and the dock holds a
+//                               standing on her under her key
+//   host    { ward, seed?,      a hosted ward stands under the seed named,
+//             memory?, class?,  or a drawn one, of the ward class named or
+//             registry? }       the default one, resolved with every class
+//                               of the ward through the registry faculty
+//                               named or the catalogue, holding a standing
+//                               on the dock; the dock keeps its name, its
+//                               seed, its registry and the memory faculty
+//                               that keeps its place, or none for the root
+//                               memory
+//   move    { ward, memory }    a hosted ward's place carried whole to
+//                               another keeper, a memory faculty's key or
+//                               null for the root memory, and forgotten
+//                               where it was
+//   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, addresses in the
+//                               order they are tried, or null to forget
+//                               it; the dock keeps it and the harbor hands
+//                               it to its carrier
+//   hold    { name, invitation, a far being held as the ward's `hold`
+//             at? }             holds it, its ward routed at the address
+//                               named first
+//   reach   { at }              where this harbor is reached, the
+//                               addresses every invitation it gives carries
+//   heard                       a push heard, told to every carrier faculty,
+//                               so one that collects for this harbor
+//                               collects
+//
+// Her census adds, for whoever pilots, what her cells keep, each hosted
+// ward by name with its keeper and registry but never its seed, the routes
+// and the reach; what did not stand; and every address the harbor's
+// carriers listen at.
+//
+// A take of an invitation that carries `at` teaches the dock that ward's
+// route, where the root set none.
+import { Faculty, ships, WARD } from '../being/index.js';
+import { Catalogue, CATALOGUE } from './catalogue.js';
+import { MEMORY, MemoryFaculty } from './memory.js';
+import { registers } from './registry.js';
+import { readAt, readInvitation } from '../quo/index.js';
+import { ownerAsk, pilots, rootAsk, Ward } 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;
+// Whether a class is the catalogue's, which stands under `catalogue` alone.
+const catalogues = (C) => C === Catalogue || (typeof C === 'function' && C.prototype instanceof Catalogue);
+// Whether a class may be a hosted ward's: a ward, and no dock.
+export const hostable = (C) => Ward.fulfils(C) && !Dock.fulfils(C);
+export class Dock extends Ward {
+    static kind = 'org.nervur.dock';
+    static {
+        ships(this);
+    }
+    static cells = { hosted: [], routes: {}, reach: [] };
+    static asks = {
+        ...Ward.asks,
+        stand: ownerAsk('every faculty and hosted ward that does not stand yet, stood; silence where everything stands'),
+        open: ownerAsk('a faculty of this harbor', { required: ['key', 'class'] }),
+        host: ownerAsk('a ward this harbor hosts, kept by the root memory or by the memory faculty named', { required: ['ward'] }),
+        move: ownerAsk('a hosted ward carried to a memory faculty, or to the root memory with null', { required: ['ward', 'memory'] }),
+        hold: ownerAsk('an owner invitation on a far being, held under a name from now on, at the address named', { required: ['name', 'invitation'] }),
+        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'),
+        heard: ownerAsk('a push heard, told to every carrier, so one that collects for this harbor collects'),
+        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) {
+        super(stance);
+        this.#hosting = stance.ground;
+    }
+    // The second level: every faculty of the box that does not stand yet,
+    // each once the registry she names stands, registries first, then
+    // memory faculties, then the rest; every route handed to the carrier;
+    // then every hosted ward and her ward. Asked once the harbor boots, and
+    // again whenever the code that runs moves, so it stands only what does
+    // not stand yet, and answers silence where everything already stands.
+    async stand() {
+        const stood = [...(await this.#standFaculties(registers)), ...(await this.#standFaculties((C) => C.prototype instanceof MemoryFaculty)), ...(await this.#standFaculties(() => true))];
+        for (const [pk, at] of Object.entries(this.routes))
+            this.#hosting.reached(pk, at);
+        const wards = [];
+        for (const row of this.hosted)
+            if (await this.#hosting.stand(row))
+                wards.push(row.ward);
+        return stood.length + wards.length > 0 ? { stood, wards } : undefined;
+    }
+    // The absent faculties whose class resolves now and fits, stood, again
+    // and again while one more stands, since a registry stood makes the
+    // classes named through it resolve.
+    async #standFaculties(fits) {
+        const stood = [];
+        for (let more = true; more;) {
+            more = false;
+            for (const [key, being] of Object.entries(this.steward.beings())) {
+                const C = being.absent ? this.steward.classOf(being.class, being.registry) : undefined;
+                if (!C || !fits(C) || this.steward.stand(key) !== 'booted')
+                    continue;
+                more = true;
+                stood.push(key);
+                await this.#hosting.rouse(key);
+            }
+        }
+        return stood;
+    }
+    // The census adds what did not stand, for whoever pilots, and whether
+    // the harbor lives only as long as a screen.
+    describe(asker) {
+        const blueprint = super.describe(asker);
+        if (!pilots(asker, this.notes(asker)))
+            return blueprint;
+        const notes = blueprint.notes;
+        notes.wards = Object.fromEntries(this.hosted.map(({ ward, memory, registry }) => [ward, { ...(memory === undefined ? {} : { memory }), ...(registry === undefined ? {} : { registry }) }]));
+        notes.routes = this.routes;
+        notes.reach = this.addresses;
+        notes.failed = this.#hosting.failures();
+        notes.listening = this.#hosting.listening();
+        if (this.#hosting.foreground)
+            notes.foreground = true;
+        return blueprint;
+    }
+    async heard() {
+        await this.#hosting.heard();
+        return { heard: true };
+    }
+    get hosted() {
+        return this.cells.hosted.map(({ ward, seed, memory, registry }) => ({
+            ward,
+            seed,
+            ...(memory === undefined ? {} : { memory }),
+            ...(registry === undefined ? {} : { registry }),
+        }));
+    }
+    // Whether a key names a memory faculty the dock opened.
+    #memory(key) {
+        return text(key) && this.#fulfilling(MEMORY).includes(key);
+    }
+    // The registry an ask names: none for the catalogue, the key of a
+    // registry faculty standing in the box, or no registry at all.
+    #registry(named) {
+        if (named === undefined || named === null || named === CATALOGUE)
+            return { registry: undefined };
+        if (!text(named))
+            return null;
+        const being = this.steward.beings()[named];
+        const C = being && !being.absent ? this.steward.classOf(being.class, being.registry) : undefined;
+        return registers(C) ? { registry: named } : null;
+    }
+    get 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 } = 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];
+        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 far ward held at the address named is routed there first, so the
+    // take reaches it where its invitation says nothing.
+    async hold(args) {
+        if (args.at !== undefined) {
+            if (!addresses([args.at]))
+                return { error: 'at is an address' };
+            const ward = readInvitation(args.invitation)?.ward;
+            if (ward === undefined)
+                return { error: 'no invitation' };
+            const routed = this.route({ ward, at: [args.at] });
+            if (routed.error !== undefined)
+                return routed;
+        }
+        return super.hold(args);
+    }
+    // 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();
+    }
+    // The dock born again of a class, resolved through the catalogue or a
+    // registry the catalogue stands, since she stands before any other.
+    become(args) {
+        if (!text(args.class))
+            return { error: 'class is text' };
+        const through = this.#registry(args.registry);
+        if (through === null)
+            return { error: 'no such registry faculty' };
+        const { registry } = through;
+        if (registry !== undefined && this.steward.beings()[registry].registry !== undefined)
+            return { error: 'the dock stands through the catalogue or a registry it stands' };
+        const refused = this.steward.become(args.class, registry);
+        return refused === null ? { became: args.class } : { error: refused };
+    }
+    // The box ward holds faculties alone, and a faculty stands by `open`,
+    // which takes a standing on her.
+    boot() {
+        return Promise.resolve({ error: 'a faculty is opened, and nothing else stands in the box ward' });
+    }
+    // A faculty that goes stops listening first, and a memory faculty
+    // keeping a ward's place does not go.
+    async unboot(args) {
+        if (this.hosted.some((h) => h.memory !== undefined && h.memory === args.being))
+            return { error: 'a ward is kept by this memory faculty' };
+        if (typeof args.being === 'string')
+            await this.#hosting.lull(args.being);
+        return super.unboot(args);
+    }
+    // A faculty of any class the registry named resolves: a kit faculty
+    // resolves only where this ground ships it. The catalogue is the core's,
+    // and no ask opens one.
+    async open(args) {
+        if (!text(args.key) || !text(args.class))
+            return { error: 'key and class are text' };
+        const through = this.#registry(args.registry);
+        if (through === null)
+            return { error: 'no such registry faculty' };
+        const { registry } = through;
+        const C = this.steward.classOf(args.class, registry);
+        if (!Faculty.fulfils(C) || catalogues(C))
+            return { error: 'no such faculty' };
+        if ((await this.steward.boot(args.key, args.class, registry)) !== 'booted')
+            return { error: 'not opened' };
+        const invitation = await this.steward.invite(args.key, WARD, {});
+        if (invitation === null || (await this.stance.standings.take(args.key, invitation)) === null) {
+            this.steward.unboot(args.key);
+            return { error: 'not opened' };
+        }
+        await this.#hosting.awaken(args.key);
+        return { opened: args.key };
+    }
+    async sweep() {
+        return { swept: await this.#hosting.sweep() };
+    }
+    async host(args) {
+        const name = args.ward;
+        if (!text(name))
+            return { error: 'ward is text' };
+        if (name === BOX)
+            return { error: 'box is the box ward' };
+        if (this.hosted.some((h) => h.ward === name))
+            return { error: `${name} is hosted already` };
+        if (args.seed !== undefined && !text(args.seed))
+            return { error: 'seed is text' };
+        const memory = args.memory ?? undefined;
+        if (memory !== undefined && !this.#memory(memory))
+            return { error: 'no such memory faculty' };
+        const through = this.#registry(args.registry);
+        if (through === null)
+            return { error: 'no such registry faculty' };
+        const { registry } = through;
+        const kind = args.class ?? undefined;
+        if (kind !== undefined && (!text(kind) || !hostable(this.steward.classOf(kind, registry))))
+            return { error: 'no such ward class' };
+        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, memory, kind, registry);
+        if (seed === null) {
+            this.stance.occupants.remove(name);
+            return { error: 'not hosted' };
+        }
+        this.cells.hosted.push({ ward: name, seed, ...(memory === undefined ? {} : { memory }), ...(registry === undefined ? {} : { registry }) });
+        return { hosted: name };
+    }
+    // The place is written where it goes before the dock's cells say so, and
+    // forgotten where it was only once they are kept, so a cut at any step
+    // leaves the ward whole under the keeper the cells name.
+    async move(args) {
+        const rows = this.cells.hosted;
+        const row = rows.find((h) => h.ward === args.ward);
+        if (!row)
+            return { error: 'no such ward' };
+        const to = args.memory ?? undefined;
+        if (to !== undefined && !this.#memory(to))
+            return { error: 'no such memory faculty' };
+        const from = row.memory;
+        if (from === to)
+            return { error: `${row.ward} is kept there already` };
+        const refused = await this.#hosting.move(row.ward, row.seed, from, to);
+        if (refused !== null)
+            return { error: refused };
+        const set = (memory) => {
+            if (memory === undefined)
+                delete row.memory;
+            else
+                row.memory = memory;
+        };
+        set(to);
+        if (!(await this.#hosting.keep())) {
+            set(from);
+            await this.#hosting.move(row.ward, row.seed, to, from);
+            return { error: 'not kept' };
+        }
+        await this.#hosting.release(row.ward, from);
+        return { moved: row.ward, memory: to ?? null };
+    }
+    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, being.registry) : undefined;
+            return Faculty.fulfils(C) && Faculty.contracts(C).includes(contract);
+        });
+    }
+}

package/dist/core/harbor/harbor.d.ts

@@ -0,0 +1,16 @@
+import { type JsonObject } from '../being/index.ts';
+import { type Cataloguing } from './catalogue.ts';
+import { type Ground } from './carrying.ts';
+import { type Hosting } from './dock.ts';
+import { type Probing } from './probe.ts';
+import { Terrain } from './terrain.ts';
+export type HarborGround = Hosting & Cataloguing & Ground;
+export declare class Harbor {
+    #private;
+    private constructor();
+    static open(from?: Terrain | Probing): Promise<Harbor>;
+    ask(value: unknown): Promise<JsonObject>;
+    arrive(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
+    holds(pk: string): boolean;
+    close(): Promise<void>;
+}